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

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

```text
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 中继或隧道

## 构建并安装准确产物

```sh
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` 消息。图片、音频请求片段、非流式回复和工具调用都会被拒绝。

更多内容见 [架构说明](docs/ARCHITECTURE.md)、[验证记录](docs/SMOKE_TEST.md) 与 [安全说明](SECURITY.md)。