声网语音桥接chenjie1129/deepseek-harness-shengwang-voice-bridge

DeepSeek Harness × 声网实时语音桥接插件

这是一个与现有 Harness 工程隔离的 PoC 插件，包含中英文配置页、浏览器麦克风控制，以及声网对话式 AI 所需的 OpenAI Chat Completions 流式接口。

Harness 设置 → 插件 → 声网语音
↕ 浏览器麦克风与通话控制
声网 RTC → 托管 ASR → 对话式 AI → 托管 TTS
↓ HTTPS OpenAI SSE
仅转发单一路径的公网隧道 → 127.0.0.1:54120
↓
本插件 ↔ 一个独立且禁用全部工具的 Harness 会话

它不是 ACP 前端，不在本地处理音频编码，也不是可直接暴露到公网的服务。

PoC 已实现

- 在 Harness 设置中配置 App ID、服务区域、公网地址、识别语言、开场语和语音指令。
- App Certificate 与桥接 Bearer Token 以只写方式保存到 Harness credentials。
- 不改 YAML、不重启 Harness 即可启停本地桥接。
- 在宿主侧创建真实声网对话式 AI 会话，并给浏览器签发一小时、单频道范围的 RTC Token。
- 浏览器只拥有一条麦克风轨道，支持播放 Agent 音频、静音、结束和失败清理。
- 把声网 Custom LLM 请求送进真实 Harness turn，并逐 token 返回 OpenAI 兼容 SSE。
- 断流、显式取消或新 turn 抢占时取消旧 turn，并阻断旧事件泄漏。
- 给插件拥有的 Agent 设置空工具白名单。

确定性测试和打包后的浏览器验证，不代表已经证明真实声网账号、真实 DeepSeek 模型、语音质量或线上延迟。只有用有效账号完成麦克风通话并听到回复，才算真实端到端证据。

环境要求

- 与 DeepSeek Harness 0.1.1-rc.2 兼容的软件包
- Node.js ^22.19.0 或 >=24
- 已开通对话式 AI 的声网项目
- 已配置的 Harness 模型路由
- 只公开 /v1/chat/completions 的 HTTPS 中继或隧道

构建并安装准确产物

corepack pnpm install
corepack pnpm test
corepack pnpm run typecheck
npm pack

dsh plugin --profile web add ./dsh-shengwang-voice-bridge-0.2.0.tgz
dsh --profile web

打开 设置 → 插件 → 声网语音：

1. 填写声网 App ID，并选择服务区域；shengwang.cn 的中国大陆项目选择 CN。
2. 填写 App Certificate，并生成至少 32 位 URL 安全字符作为桥接 Token。保存后密码框会清空，页面无法读取密钥原文。
3. 填写以 /v1/chat/completions 结尾的公网 HTTPS 地址；该地址只能转发到 127.0.0.1:54120 的这一条路径。
4. 调整识别语言、开场语和口语回答指令，启用桥接并保存。
5. 在设置 → 模型中配置要使用的 Harness 模型。
6. 四项实测条件全部变绿后，点击 开始实时语音 并允许麦克风权限。

高级部署仍可在 Cordis 配置中覆盖 port、tokenEnv、appCertificateEnv、provider、model、cwd 以及请求上限；普通浏览器配置不需要编辑 YAML。

实时语音链路

点击开始后，插件宿主使用声网托管 Deepgram STT、本插件 Custom LLM 地址和托管 MiniMax TTS 创建 Agent。App Certificate 始终留在 Harness 宿主，浏览器只收到一小时有效的 RTC 能力 Token。浏览器加入频道并发布一条麦克风轨道，结束通话、页面销毁或启动失败时都会清理本地和远端资源。

声网把桥接 Token 作为 Authorization: Bearer ... 发送。用户打断通常会关闭当前 LLM 流，插件把断流映射为 agent.cancel({ kind: 'user' })。

本插件不会创建公网地址。请使用只转发单一路径的中继或隧道，绝不要公开 Harness Web UI、/v1/cancel 或 /v1/reset。

接口

| 路径 | 鉴权 | 用途 |
| --- | --- | --- |
| GET /health | 无 | 仅检查本地监听状态 |
| POST /v1/chat/completions | Bearer | 流式文字 turn |
| POST /v1/cancel | Bearer | 本地取消探针 |
| POST /v1/reset | Bearer | 销毁插件拥有的 Harness 对话状态 |
| GET /api/shengwang-voice/config | 同源 | 脱敏配置与凭据状态 |
| PUT /api/shengwang-voice/config | 同源 | 保存设置与只写凭据 |
| POST /api/shengwang-voice/session/start | 同源 | 创建声网 Agent 与浏览器 RTC 能力 |
| POST /api/shengwang-voice/session/stop | 同源 | 停止插件拥有的声网 Agent |

由于历史已经保存在 Harness 会话中，插件只提交请求里的最后一条 user 消息。图片、音频请求片段、非流式回复和工具调用都会被拒绝。

更多内容见 架构说明、验证记录 与 安全说明。