# 打字不如说话，说话不如截图——AI 代码助手的多模态输入实践

> 其实写代码这事儿，打字再快也有个上限。有时候说一句话的事，非得敲半天键盘；有时候一张图就能说明白，却得用一堆文字去描述。本文聊聊我们在做 [HagiCode](https://hagicode.com) 时遇到的那些事儿——语音识别也好，图片上传也罢，反正就是想让 AI 代码助手变得好用一点，罢了。

## 背景

在做 HagiCode 的时候，我们发现了一个问题——或者说，用户们用得多了，自然就显现出来的问题：光靠打字，有时候挺累的。

你想啊，用户和 Agent 交互，这可是核心场景。可是每次都得坐在键盘上噼里啪啦地敲，怎么说呢，效率确实不太高：

1. **打字太慢了**：有些复杂的问题，什么报错啊、界面上的事儿啊，打字说出来得耗上半分钟，嘴上可能十秒就说完了。这时间差，挺让人难受的。

2. **图片更直接**：有时候界面报错了，或者想对比一下设计稿，又或者想展示代码结构……"一图胜千言"这话虽老，可理儿不假。让 AI 直接"看"到问题，比描述半天要清楚得多。

3. **交互就该自然点**：现在的 AI 助手，应该支持文字、语音、图片这些方式吧？用户想用什么就用什么，这才叫自然，不是吗？

所以啊，我们就想，不如给 HagiCode 加上语音识别和图片上传的功能，让 Agent 操作变得方便些。毕竟，能让用户少敲几个字，也是好的。

## 关于 HagiCode

本文分享的这些方案，来自我们在 [HagiCode](https://hagicode.com) 项目中的实践——或者说，是在不断踩坑中摸索出来的经验。

HagiCode 是个开源的 AI 代码助手项目，想法很简单：用 AI 技术提升开发效率。做着做着就发现，用户对多模态输入的需求其实挺强烈的——有时候说一句话比打一堆字快，有时候一张截图比描述半天清楚。

这些需求推着我们往前走，最后也就有了语音识别和图片上传这些功能。用户可以用最自然的方式和 AI 交互，这感觉，挺好的。

## 分析

### 语音识别的技术挑战

做语音识别功能的时候，我们遇到了一个挺棘手的问题：**浏览器的 WebSocket API 不支持自定义 HTTP header**。

而我们选的语音识别服务，是字节跳动的豆包语音识别 API。这个 API 偏偏要求通过 HTTP header 传递认证信息，什么 `accessToken`、`secretKey` 之类的。这下好了，技术矛盾来了：

```javascript
// 浏览器 WebSocket API 不支持以下方式
const ws = new WebSocket('wss://api.com/ws', {
  headers: {
    'Authorization': 'Bearer token'  // 不支持
  }
});
```

摆在我们面前的方案，大概有两个：

1. **URL 查询参数方案**：把认证信息放在 URL 里
   - 优点是，实现起来简单
   - 缺点是，凭证暴露在前端，安全性差；而且有些 API 强制要求 header 验证

2. **后端代理方案**：在后端实现 WebSocket 代理
   - 优点是，凭证安全存储在后端；完全兼容 API 要求
   - 缺点是，实现起来稍微复杂一点

最后我们还是选了**后端代理方案**。毕竟啊，安全性这东西，是不能妥协的底线——这一点，谁也别想糊弄过去。

### 图片上传的功能需求

图片上传功能嘛，我们的需求其实也挺简单的：

1. **多种上传方式**：点击选文件、拖拽上传、剪贴板粘贴，总得有吧？
2. **文件验证**：类型限制（PNG、JPG、WebP、GIF）、大小限制（5-10MB），这些是基本操作
3. **用户体验**：上传进度、预览、错误提示，总得让人知道发生了什么
4. **安全性**：服务端验证、防止恶意文件上传，这可是大事

## 解决方案

### 语音识别：WebSocket 代理架构

我们设计了一个三层架构的语音识别方案，怎么说呢，算是找到了一条路：

```
Browser WebSocket
       |
       | ws://backend/api/voice/ws
       | (binary audio)
       v
Backend Proxy
       |
       | wss://openspeech.bytedance.com/ (with auth header)
       v
Doubao API
```

**核心组件实现**：

1. **前端 AudioWorklet 处理器**：

```javascript
class AudioProcessorWorklet extends AudioWorkletProcessor {
  process(inputs, outputs, parameters) {
    const input = inputs[0]?.[0];
    if (!input) return true;

    // 重采样到 16kHz（豆包 API 要求）
    const samples = this.resampleAudio(input, 48000, 16000);

    // 累积样本到 500ms 块
    this.accumulatedSamples.push(...samples);

    if (this.accumulatedSamples.length >= 8000) {
      // 转换为 16-bit PCM 并发送
      const pcm = this.floatToPcm16(this.accumulatedSamples);
      this.port.postMessage({ type: 'audioData', data: pcm.buffer }, [pcm.buffer]);
      this.accumulatedSamples = [];
    }
    return true;
  }
}
```

2. **后端 WebSocket 处理器**（C#）：

```csharp
[HttpGet("ws")]
public async Task GetWebSocket()
{
    if (HttpContext.WebSockets.IsWebSocketRequest)
    {
        await _webSocketHandler.HandleAsync(HttpContext);
    }
}
```

3. **前端 VoiceTextArea 组件**：

```tsx
export const VoiceTextArea = forwardRef<HTMLTextAreaElement, VoiceTextAreaProps>(
  ({ value, onChange, onTextRecognized, maxDuration }, ref) => {
    const { isRecording, interimText, volume, duration, startRecording, stopRecording } =
      useVoiceRecording({ onTextRecognized, maxDuration });

    return (
      <div className="flex gap-2">
        {/* 语音按钮 */}
        <button onClick={handleButtonClick}>
          {isRecording ? <VolumeWaveform volume={volume} /> : <Mic />}
        </button>
        {/* 文本输入框 */}
        <textarea value={displayValue} onChange={handleChange} />
      </div>
    );
  }
);
```

### 图片上传：多方式上传组件

我们做了一个功能完整的图片上传组件，三种上传方式都支持，怎么说呢，算是把用户常用的场景都覆盖到了。

**核心特性**：

1. **三种上传方式**：

```tsx
// 点击上传
const handleClick = () => fileInputRef.current?.click();

// 拖拽上传
const handleDrop = (e: React.DragEvent) => {
  const file = e.dataTransfer.files?.[0];
  if (file) uploadFile(file);
};

// 剪贴板粘贴
const handlePaste = (e: ClipboardEvent) => {
  for (const item of Array.from(e.clipboardData?.items || [])) {
    if (item.type.startsWith('image/')) {
      const file = item.getAsFile();
      if (file) uploadFile(file);
    }
  }
};
```

2. **前端验证**：

```tsx
const validateFile = (file: File): { valid: boolean; error?: string } => {
  if (!acceptedTypes.includes(file.type)) {
    return { valid: false, error: 'Only PNG, JPG, JPEG, WebP, and GIF images are allowed' };
  }
  if (file.size > maxSize) {
    return { valid: false, error: `Maximum file size is ${(maxSize / 1024 / 1024).toFixed(1)}MB` };
  }
  return { valid: true };
};
```

3. **后端上传处理**（TypeScript）：

```typescript
export const Route = createFileRoute('/api/upload')({
  server: {
    handlers: {
      POST: async ({ request }) => {
        const formData = await request.formData();
        const file = formData.get('file') as File;

        // 验证
        const validation = validateFile(file);
        if (!validation.isValid) {
          return Response.json({ error: validation.error }, { status: 400 });
        }

        // 保存文件
        const uuid = uuidv4();
        const filePath = join(uploadDir, `${uuid}${extension}`);
        await writeFile(filePath, buffer);

        return Response.json({ url: `/uploaded/${today}/${uuid}${extension}` });
      }
    }
  }
});
```

## 实践指南

### 如何使用语音识别

1. **配置语音识别服务**：
   - 进入语音识别设置页面
   - 配置豆包语音的 `AppId` 和 `AccessToken`
   - （可选）配置热词以提升专业术语识别准确率

2. **在输入框中使用**：
   - 点击输入框左侧的麦克风图标
   - 看到波形动画后开始说话
   - 再次点击图标停止录音
   - 识别结果会自动插入到光标位置

3. **热词配置示例**：

```text
TypeScript
React
useState
useEffect
```

### 如何使用图片上传

1. **上传方式**：
   - 点击上传按钮选择文件
   - 直接拖拽图片到上传区域
   - 使用 `Ctrl+V` 粘贴剪贴板中的截图

2. **支持的格式**：PNG、JPG、JPEG、WebP、GIF
3. **大小限制**：默认 5MB（可配置）

### 注意事项

1. **语音识别**：
   - 需要麦克风权限
   - 建议在安静环境下使用
   - 支持的最大录音时长为 300 秒（可配置）

2. **图片上传**：
   - 仅支持常见图片格式
   - 注意文件大小限制
   - 上传后的图片会自动生成预览 URL

3. **安全考虑**：
   - 语音识别凭证存储在后端
   - 图片上传有严格的服务端验证
   - 生产环境建议使用 HTTPS/WSS

## 总结

加上语音识别和图片上传之后，HagiCode 的用户体验确实提升了不少。用户现在可以用更自然的方式和 AI 交互——说话代替打字，截图代替描述。这种感觉，怎么说呢，就像是终于找到了一种更舒服的沟通方式。

做这个功能的时候，我们遇到了浏览器 WebSocket 不支持自定义 header 的问题，最后还是通过后端代理方案搞定了。这个方案不仅保证了安全性，也为后续集成其他需要认证的 WebSocket 服务打下了基础——也算是个意外收获吧。

图片上传组件也是，用了多种上传方式，让用户可以根据场景选择最方便的那一个。点击也好，拖拽也罢，或者直接粘贴，都能快速完成上传。条条大路通罗马，只是有的路好走一点，有的路稍微曲折一点罢了。

"打字不如说话，说话不如截图"，这话放在这里，倒也贴切。如果你也在做类似的 AI 助手产品，希望这些经验能对你有所帮助，哪怕只是一点点。

## 参考资料

- [HagiCode GitHub 仓库](https://github.com/HagiCode-org/site)
- [HagiCode 官网](https://hagicode.com)
- [豆包语音识别 API 文档](https://www.volcengine.com/docs/6561/79829)
- [Web Audio API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API)
- [WebSocket API](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)

---

如果本文对你有帮助：
- 点个赞让更多人看到
- 来 GitHub 给个 Star：[github.com/HagiCode-org/site](https://github.com/HagiCode-org/site)
- 访问官网了解更多：[hagicode.com](https://hagicode.com)
- 观看 30 分钟实战演示：[www.bilibili.com/video/BV1pirZBuEzq/](https://www.bilibili.com/video/BV1pirZBuEzq/)
- 一键安装体验：[docs.hagicode.com/installation/docker-compose](https://docs.hagicode.com/installation/docker-compose)
- Desktop 桌面端快速安装：[hagicode.com/desktop/](https://hagicode.com/desktop/)
- 公测已开始，欢迎安装体验


## 原文与版权说明

感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。
本内容采用人工智能辅助协作,最终内容由作者审核并确认。
- 本文作者: [newbe36524](https://www.newbe.pro)
- 原文链接: [https://docs.hagicode.com/go?platform=tencent-cloud-community&target=%2Fblog%2F2026-03-31-voice-and-image-upload-multimodal-input%2F](https://docs.hagicode.com/go?platform=tencent-cloud-community&target=%2Fblog%2F2026-03-31-voice-and-image-upload-multimodal-input%2F)
- 版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

其实写代码这事儿，打字再快也有个上限。有时候说一句话的事，非得敲半天键盘；有时候一张图就能说明白，却得用一堆文字去描述。本文聊聊我们在做 HagiCode 时遇到的那些事儿——语音识别也好，图片上传也罢，反正就是想让 AI 代码助手变得好用一点，罢了。

打字不如说话，说话不如截图——AI 代码助手的多模态输入实践

后端开发工程师

人工智能

前端

开发工具

AI代码助手HagiCode创新实现多模态输入，支持语音识别和图片上传功能，提升开发者效率。语音识别采用安全的后端代理方案，图片上传支持拖拽、粘贴等多种方式。通过自然交互方式，让开发者用说话代替打字、截图代替描述，显著优化编程体验。

语音识别

TypeScript

Docker

GitHub

Agent

语音产品特惠新用户14.9元起


2026采购季 | AI焕新·智启新局

ai-class

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

打字不如说话，说话不如截图——AI 代码助手的多模态输入实践-腾讯云开发者社区-腾讯云

打字不如说话，说话不如截图——AI 代码助手的多模态输入实践

打字不如说话，说话不如截图——AI 代码助手的多模态输入实践

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐