# dsh-vocechat-bridge 开发与验收约定

以下内容从原 README 迁移，保留项目需求和开发边界。当前已实现能力与安装方式以 README.md 和 docs/ 为准；规划项不代表已实现功能。

已实现 **v0.4.1**：面向 **DSH 0.2.1-rc.3 / Node.js 22.19+** 的原生 TypeScript 插件。支持固定会话双向文字/图片/文件/音频、组合发送、来源隔离和持久化队列。在 **设置 → VoceChat** 提供连接与语音配置，以及启动/停止/重载后端按钮。支持标准 OpenAI 与小米 MiMo 的识别、合成；语音输入同时保留原文件和转写文字。私聊默认静默 4 秒、群聊 1.5 秒、最长 12 秒封批，支持忙碌排队与缓冲恢复。每批默认附带 6 条同会话历史，另提供私聊/群聊最近 N 条查询工具；历史仅作背景，不触发旧消息补回复。桥接及 ASR/TTS 默认禁用，安装默认不启用通信。

v0.4.1 修复记忆召回、时间快照和模型切换通知被误判成其他渠道输入的问题。正常回合恢复自动回复；真正混合来源的回合继续关闭自动回复，但显式工具发送按主动发送开关和白名单校验，历史查询独立校验固定 Session 与白名单。

- [安装、配置、工具与运行说明](docs/USAGE.md)
- [升级、配置迁移与回滚](docs/MIGRATION.md)
- [验证结果和已知限制](docs/VALIDATION.md)
- [DSH 接口核实](docs/DSH-API.md) · [VoceChat API 核实](docs/VOCECHAT-API.md)
- [语音设置页、OpenAI / MiMo 与 Provider 扩展](docs/PROVIDERS.md)
- [防抖合并、持久化与恢复语义](docs/DEBOUNCE.md)
- [完整配置示例](config.example.yml)

```powershell
npm ci --legacy-peer-deps
npm run check
npm pack
dsh plugin --profile web add "<absolute-path-to-repository>"
```

安装后打开 **设置 → VoceChat**，填写服务地址、Bot UID、Key、Session 与白名单，点击“启动桥接后端”。语音配置保存后下一次请求生效，连接参数修改后点击“保存并重载后端”，无需重启 DSH。已完成本地功能验证、真实 DSH 发行库兼容性，以及真实 VoceChat 私聊的文本/Markdown/图片/已有语音双向收发验证；用户确认 Markdown 正常渲染、图片可预览、语音可播放。真实 DSH Agent 回复和云端 ASR/TTS 仍待配置服务后联调。音频理解（如 Qwen Omni）继续保留扩展接口。以下保留原始项目目标和验收要求。

## 一、项目目标

开发独立的 DeepSeek Harness 原生插件 `dsh-vocechat-bridge`，提供基于 VoceChat API 和 Webhook 的完整双向多模态通信能力。

兼容当前 DSH 0.2.1-rc.3，优先使用 TypeScript + Node.js。

核心能力：

- 接收 VoceChat 文字、图片、语音和文件。
- 收到语音后自动下载、识别并转写为文本。
- 支持 Agent 主动发送文字、图片、语音和文件。
- 支持一条回复包含文字和多个媒体附件。
- 支持固定 DSH Session，实现跨渠道记忆连续性。
- 预留音频理解能力，未来可以接入 Qwen Omni。
- 不通过复杂的文本标记或大段提示词实现消息协议。

**本项目仅负责 VoceChat 通信与多模态处理，不实现人格、记忆或自主定时调度。**

## 二、开始前的调查

首先检查：

1. DSH 当前版本的插件开发接口、Agent 和 Session API。
2. VoceChat Webhook 协议与服务端实际行为。
3. `dsh-qq-bridge` 的消息接收、Session 绑定、消息发送和工具注册机制。
4. VoceChat 官方 Bot API、Webhook、附件下载、文件上传、语音与图片发送方式。
5. 当前 DSH 是否提供原生音频、图片或多模态消息输入接口。

参考资料：

- https://github.com/deepseek-ai/deepseek-harness
- https://github.com/sj244/dsh-qq-bridge
- https://doc.voce.chat/

必须基于实际源码和 API 文档开发，不得臆造接口或消息字段。

## 三、消息接收

支持：

- VoceChat 私聊、群聊。
- UID / GID 白名单。
- 指定固定 DSH Session。
- 文本、图片、语音、普通附件。
- 消息 ID 去重和顺序处理。
- Bot 自身消息过滤，避免循环。
- 多消息并发时的安全排队及消息合并。

内部使用统一的结构化消息对象，保留来源、发送者、消息时间、消息 ID、附件元数据。

不要再把来源说明、`<noop>` 规则和 `[img:路径]` 之类的字符串追加到每条用户消息后面。

## 四、语音接收与自动转写

这是本次新增的重点功能。

### 4.1 语音处理流程

VoceChat 收到语音消息后：

1. 识别语音消息类型。
2. 通过 VoceChat API 下载原始语音。
3. 检测实际音频格式和时长。
4. 必要时转换为 ASR 服务支持的格式。
5. 调用可配置的语音识别服务。
6. 获得文字转写结果。
7. 将转写内容和原始消息来源送入绑定的 DSH Session。
8. 清理临时文件，保留必要的处理记录。

支持常见的 WAV、MP3、OGG/Opus、M4A 等格式；实际支持范围应以 VoceChat 接口和音频解码能力为准。

音频转换可以使用 FFmpeg，但应检测依赖是否存在，并提供明确错误说明。

### 4.2 ASR 引擎

设计可扩展的语音识别 Provider 接口。

第一阶段至少支持一种可以实际运行的 ASR 服务，并预留：

- OpenAI 兼容的语音转写 API。
- 阿里云百炼语音识别接口。
- 本地 Whisper / faster-whisper 等服务。

支持配置 API 地址、模型、鉴权、超时、语言和音频大小限制。

ASR 不可用时，要明确记录错误，不能生成虚假的转写内容。

### 4.3 音频理解扩展

预留 `AudioUnderstandingProvider` 接口。

未来可接入 Qwen Omni，对原始语音进行：

- 语音内容识别。
- 语速、音量、语调等声学线索分析。
- 笑声、叹气、哭声等非语言声音识别。
- 环境声音与背景音描述。
- 不确定的情绪线索分析。

**语音转写和音频理解必须是两个可以独立启用的功能。**

第一阶段优先保证转写稳定，音频理解可以只实现接口及可扩展架构，不强制接入模型。

## 五、多模态消息发送

这是第二个新增重点。

### 5.1 文字发送

支持：

- 普通文本。
- 多行文本。
- 回复指定消息。
- 主动发送。
- 根据 VoceChat 能力进行必要的长文本分段。

### 5.2 图片发送

支持：

- 发送本地图片。
- 发送允许访问的远程图片。
- PNG、JPEG、WebP 等常用格式。
- 一次发送多张图片。
- 文字与图片组合回复。

图片应通过插件的文件上传和消息发送接口处理，不依赖 `[img:/绝对路径]` 这样的文本协议。

### 5.3 语音发送

支持两种方式：

**方式 A：发送已有音频**

Agent 可以选择本地音频文件，通过插件上传并作为 VoceChat 语音或音频消息发送。

**方式 B：文字转语音**

预留可配置的 TTS Provider：

- 输入文字。
- 调用 TTS 模型生成语音。
- 转换成 VoceChat 支持的格式。
- 上传并发送。

第一阶段优先实现已有音频文件发送，TTS 可作为独立扩展能力。

不要强制每条回复都生成语音。

### 5.4 组合消息

统一支持以下出站内容：

- 纯文字。
- 纯图片。
- 纯语音。
- 文字 + 图片。
- 文字 + 语音。
- 文字 + 多张图片 + 音频附件。

由统一的消息发送层根据 VoceChat 实际 API 能力决定如何上传及发送。

如果平台不支持单个消息气泡携带多种媒体，应按顺序拆分发送，并尽量保持逻辑关联。

## 六、Agent 工具接口

注册独立的消息工具，例如：

- `voce_send_text`
- `voce_send_image`
- `voce_send_audio`
- `voce_send_file`
- `voce_send_message`（统一组合消息接口）

具体工具命名遵守 DSH 规范。

发送目标必须明确，并校验 UID/GID 权限。

支持 Agent 主动发消息，也支持常规用户消息的自动回复。

不应要求模型自己拼接图片标记、音频标记、上传 URL 或 API 请求参数。

支持安静结束，不回复时由桥接层完成处理。

## 七、Session 与消息路由

支持绑定现有 DSH Session，保留已有会话的 SOUL、长期记忆、人格和聊天历史。

区分：

- VoceChat 私聊。
- VoceChat 群聊。
- DSH Web。
- QQ。
- 其他系统内部消息。

必须正确处理回复目标，防止跨渠道误发。

同一 Session 收到多个来源消息时，需要安全排队，避免产生冲突的 Agent Turn。

## 八、配置管理

插件应提供配置界面或等效配置入口，包括：

- VoceChat 服务地址。
- Bot API Key。
- Webhook 端口和路径。
- UID/GID 白名单。
- Session 绑定。
- ASR Provider 与模型。
- ASR API 地址及鉴权。
- 音频格式、时长和大小限制。
- TTS Provider（可选）。
- 自动回复与主动发送开关。
- 临时文件目录。
- 日志级别。

所有敏感凭据应安全保存，不得出现在模型上下文或普通日志。

## 九、安全和稳定性

- 验证 Webhook 来源及签名（若接口支持）。
- 对入站消息进行去重和来源校验。
- 限制媒体大小、音频时长和请求超时。
- 下载媒体时防止 SSRF 和不可信文件路径访问。
- 处理音频转换失败、ASR 超时和附件上传失败。
- 临时文件定期清理。
- 避免 Bot 自发自收造成消息循环。
- 外部消息不得提升 DSH 工具权限。
- 不允许通过消息附件访问任意本地文件。
- 不修改 DSH 核心程序和现有 SOUL/记忆文件。

## 十、测试要求

测试至少覆盖：

1. VoceChat 私聊、群聊文本收发。
2. 收到语音并成功转写。
3. 转写失败时正确处理。
4. 接收图片和普通文件。
5. 主动发送文字、图片及语音。
6. 文字与多个媒体组合发送。
7. 文件格式不支持时的错误处理。
8. ASR 服务不可用及超时。
9. UID/GID 白名单与消息去重。
10. 多渠道共享 Session 的并发安全。
11. Bot 回环保护。
12. 重启后连接和 Session 恢复。
13. 插件启用、禁用及异常恢复。

使用 Mock VoceChat API 和测试 DSH Session 完成自动化测试。

有条件时进行真实服务联调，并区分模拟测试与实际测试结果。

## 十一、最终交付

- `dsh-vocechat-bridge` 完整源码。
- 可安装的 DSH 插件。
- 配置说明及配置示例。
- ASR Provider 扩展文档。
- 多模态消息发送工具说明。
- 自动化测试。
- 实际运行验证结果。
- 安装升级与配置迁移的操作指南。
- 已知限制及回滚方法。

## 十二、开发执行要求

先调查接口，再设计架构，然后实际完成代码与测试。

优先完成文本桥接、语音转写、图片发送和已有音频发送，之后完善 TTS 扩展能力。

不要只输出技术方案。

不要修改人格、记忆、自主定时任务或其他不相关模块。

不覆盖既有部署配置；线上变更前先备份并验证。

除真正阻塞开发的事项外，自主解决实现细节并记录取舍。