# DSH 桌面客户端集成

> 相关：[01-方案设计.md](01-方案设计.md) ｜ [02-进展与下一步.md](02-进展与下一步.md)

本文回答一件事：**这个插件怎么在 DSH 桌面客户端里用起来**，以及为什么这样实现。

---

## 一、形态：输入框旁的小挂件

在对话输入框的工具行里，模型选择器与提交按钮之间，多了一个 AI Passport 小挂件：

```
┌─────────────────────────────────────────────────────────┐
│  对话内容…                                              │
│                                                          │
│  [+ 附件] [●已连接] [模型 ▾] [计划] [🎤]  [▶ 发送]      │
│              ↑                                           │
│         AI Passport 挂件                                 │
└─────────────────────────────────────────────────────────┘
```

挂件本身只占一行内联空间，显示**当前最该知道的那一件事**：

| 状态 | 显示 |
| --- | --- |
| 未连接 | 灰点 + 「未连接」 |
| 扫描/连接中 | 黄点 + 「扫描中」「连接中」 |
| 已连接、无任务在跑 | 绿点 + 「已连接」 |
| 有等待中的审批 | 绿点 + 右侧红色数字角标 |

点开是一个 180px 的浮层，**右对齐挂件**（`--ap-pop-x`，默认 24px，用于再向左微调），
从上到下依次是：

1. **动作结果**（有操作时才出现）—— 上一次面板动作返回的文字，避免"点了没反应"的错觉
2. **设备** —— 设备名 + 固件 / 电量 / 信号 / 握手四格；断开 / 诊断蓝牙；未连接时给出「扫描并连接」与失败原因
3. **语音** —— 一行搞定：`语音  已启用`（状态跟在标题右侧，绿色=已启用）；只有"确实没装 /
   上次准备失败"时，才在**状态右边**再挂一个小的「准备模型」按钮。下载/加载期间该位置显示进度说明
   （插件**启动时**就探测一次识别目录、带 3 次重试，所以首屏状态就是准的；
   打开弹窗再刷一次，未就绪期间每 5 秒继续刷，就绪后按钮自行消失）

> 待审批、任务列表、DeepSeek 余额三块已移除：审批由设备端审批页处理（插件只保留角标），
> 余额由设备端长按下键查看，任务区按用户要求去掉。
>
> **"已启用"的判定**（2026-10-06 修正）：DSH 在推理时接受 `ready` **或 `standby`** 两种资源
> （`standby` = 模型已装好、只是没预热，第一次录音会自动唤醒 worker）。早先按 `phase === 'ready'`
> 判定，模型一闲置就显示"未启用" —— 真机反馈"模型早就配好了却显示未启用"即此。
> 现在：`ready|standby` → 已启用；`unprepared|failed|cancelled` → 给「准备模型」；
> `checking|downloading|preparing|loading|waking` → 显示进度说明。
>
> 附带一个事实澄清：主机快照里**从来没有** `tasks` 列表（只有给设备端用的 `taskState`），
> 所以挂件那块任务 UI 一直是"暂无任务"的空壳；`device.refresh` 也早已退化成"重推一次状态"。
> 独立控制面板页（`lib/panel/static`）里同样的任务区也一直是空的，**本次未动**。

---

## 二、语音：识别结果填进当前输入框

设备上长按「确定」录音 → 音频经 BLE 到电脑 → 本地识别 → **设备端弹出识别结果卡**：
单击「确定」= 填入光标处、双击 = 整段替换并直接发送、长按 = 重说。
挂件在这一链里负责执行与回执：认领结果（`voice.take`）→ 调 `inputActions` → 回执（`voice.ack`），
设备端据此给出「已填入 / 已发送」的提示。

为什么是"填进去"而不是"直接发送"：语音识别必然有误识别，尤其人名、路径、代码标识符。
让用户看一眼再发，比事后发现任务跑错了要便宜得多。设备侧也有对应的确认步骤。

### 怎么插进输入框

用的是 DSH 官方语音输入插件**同一套**动词。`conversation.input.activity` 槽位的宿主
（`ui-conversation`）会给每个注册者注入一个 `inputActions`：

```js
inputActions.captureInsertion()          // 取当前光标位置 + 草稿修订号
inputActions.insertText(text, span)      // 在光标处插入，返回是否成功
```

关键设计：

- 用 `insertText` 而**不是** `setDraft`。`setDraft` 会整段替换，把用户已经写了一半的内容冲掉；
  `insertText` 只在光标处插入。
- `insertText` 带 `draftRev` 冲突检测：如果识别期间用户改了草稿，插入会被拒绝而不是覆盖。
  此时挂件不静默失败，会通过 `voice.ack` 把失败原因回给设备（toast）。
- 挂件对 `inputActions` 缺失是**容错**的：拿不到就只是不做插入，其余功能照常。
  这样 DSH 以后调整这个槽位的契约时，最坏结果是少一个动作，而不是挂件整个崩掉。

---

## 三、为什么用同源 HTTP 而不是 Remote

客户端半区跑在页面里，宿主半区（BLE、任务、审批）跑在 Node 里，两者要通信。
DSH 里有一等公民 `ctx.remote.*`，但它**用不了**：

`ctx.remote.<namespace>` 那些命名空间由宿主侧 `@Remote` 装饰器在 **DSH 自己的构建期**
经 Typert 生成 codec 与网关路由。第三方包在自己的仓库里构建，无法注册新的 Remote 命名空间。

所以走**同源 HTTP**：宿主半区用 `ctx.webServer.register()` 挂 `/dsh-passport/*`，
客户端与页面同源，直接 `fetch` 即可。

| 端点 | 方法 | 用途 |
| --- | --- | --- |
| `/dsh-passport/state.json` | GET | 完整状态快照 |
| `/dsh-passport/action` | POST | 唯一写入口 |
| `/dsh-passport/events` | GET | SSE（完整面板页用） |
| `/dsh-passport` | GET | 完整控制面板页（浏览器打开时用） |

这套接口**同时**服务挂件与完整面板页，于是两边共用一套鉴权、一套数据源，
不会出现"挂件看到的和面板看到的不一样"。

### 为什么挂件用轮询而不是 SSE

挂件是常驻的、每个窗口一份。SSE 连接会一直占着（同源并发连接数有限），
而挂件需要的信息量只有几百字节，2 秒轮询在桌面上完全无感。
真正需要实时性的审批由宿主半区**主动推给设备**，挂件迟 2 秒看到不影响正确性——
用户是在设备上按键决定的。

页面隐藏时轮询自动降频到 10 秒，避免后台空转。

---

## 四、客户端 bundle 的硬约束

客户端半区（`lib/client.js`）是**预先构建好的浏览器 bundle**，由 `@deepseek-ai/dsh-client-modules`
扫描、拼接、下发。格式是硬约束，任一条不满足都会让 **client 包组合整体失败**，
表现为"客户端起不来"，排查成本极高：

1. 文件是 `window.__ModuleLoader__.load({ id, factory })` 调用；
2. **`id` 必须严格等于包名**（`dsh-ai-passport`）；
3. factory 内用注入的 `require` 取共享依赖，只能取 DSH 提供的那些
   （本插件只用了 `react`）；
4. 导出 `apply(ctx)` 与 `inject`（硬依赖服务名数组）；
5. bundle 路径由 `package.json` 的 `exports["./client"]` 解析；
6. `package.json` 必须有 `dsh.client` 段，否则根本不会被扫描。

因为**没有构建步骤**（本插件刻意不引入打包链），所以 `client.js` 里不写 JSX，
全部用 `React.createElement`。

### 这一层怎么测

`test/client-bundle.test.js` 用一个假的 `window.__ModuleLoader__` 与假的 `require`
把 bundle 真跑一遍，卡住上面每一条：

- id 与包名一致；
- 只 require 允许的模块（多 require 一个不存在的模块就会在这里失败，而不是等 DSH 启动）；
- 导出形状正确；
- `apply()` 确实在 `conversation.input.activity` 注册了组件；
- 样式 effect 返回清理函数（否则热重载几次就会堆一串重复 `<style>`）；
- 首屏状态（后端还没起来、`state` 为 `null`）下组件能渲染不崩。

这个测试在写它的过程中就抓到了一个真问题：假环境里 `document` 被过早还原，
导致样式被静默跳过——正是这类"环境差异"最容易在真机上变成难查的故障。

---

## 五、怎么启用

插件已经装进桌面 profile：

```
~/.dsh/profiles/desktop/
├── dsh-ai-passport/          # 插件本体（从 packages/ 同步）
├── node_modules/dsh-ai-passport   # pnpm 安装的链接
└── package.json              # bundles 里已加入 dsh-ai-passport
```

`package.json` 的 bundles 现在是：

```json
"bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-ai-passport"]
```

bundle 列表在 **DSH 启动时**读取。当前正在运行的宿主仍然是 186 个条目，
说明它还没加载这个新 bundle，因此：

> **需要重启 DSH 桌面客户端**，挂件才会出现。

重启后应该看到：

1. 输入框工具行里出现 AI Passport 挂件（灰点 + 「未连接」）；
2. 点开 → 「扫描并连接」；
3. 点「准备模型」开始下载本地识别模型（约 240 MB），或者先用 `transport: mock` 走通界面。

### 先用假设备把界面走通

还没烧固件之前，把配置改成 mock 就能看到完整的界面与交互：

```yaml
# ~/.dsh/profiles/desktop/cordis.patch.yml 里追加
- id: dsh-ai-passport
  name: dsh-ai-passport
  config:
    transport: mock
    autoConnect: true
```

mock 传输带一台虚拟设备，会应答握手、心跳、任务列表（4 条不同状态的假任务）与余额，
足够验证挂件的每一种状态显示。

---

## 六、与完整面板的关系

完整面板页（`/dsh-passport`）**保留**，定位变成"重活"入口：

| 场景 | 用哪个 |
| --- | --- |
| 日常盯状态、审批、填语音 | 挂件 |
| 看链路诊断、丢片统计、事件流 | 面板页 |
| 长时间观察、多窗口 | 面板页 |

挂件与面板读写的是**同一份状态**，所以两边永远不会打架。

---

## 七、语音资产落位（模型 / 程序 / 代码）

排查"语音为什么不工作""能不能换盘""能不能删"时，先看这三张表。

### 7.1 模型（数据，当前 230MB）

| 内容 | 路径 | 大小 |
| --- | --- | --- |
| 主模型（SenseVoice int8 ONNX） | `~/.dsh/speech-to-text/sensevoice/models/sensevoice-onnx/model.int8.onnx` | 228M |
| 词表 | `~/.dsh/speech-to-text/sensevoice/models/sensevoice-onnx/tokens.txt` | 312K |
| VAD（静音检测） | `~/.dsh/speech-to-text/sensevoice/models/silero/silero_vad.onnx` | 1.7M |

路径由**用户配置**决定，不是写死的：

```yaml
# ~/.dsh/profiles/desktop/cordis.patch.yml
- id: speech-to-text-sensevoice
  name: "@deepseek-ai/dsh-experimental-speech-to-text-sensevoice"
  config:
    dataRoot: !!js dshHomePath('speech-to-text', 'sensevoice')   # ← 模型缓存根，可改
```

复核命令：

```bash
du -sh ~/.dsh/speech-to-text/sensevoice
find ~/.dsh/speech-to-text -type f -exec du -h {} +
```

### 7.2 程序与原生库（随 DSH 应用分发，不在用户目录）

| 内容 | 位置（`/Applications/DeepSeek Harness.app/Contents/Resources/app.asar` 内） |
| --- | --- |
| 识别服务本体 | `node_modules/@deepseek-ai/dsh-experimental-speech-to-text` |
| 本地提供者（SenseVoice） | `node_modules/@deepseek-ai/dsh-experimental-speech-to-text-sensevoice` |
| 云端提供者（兜底） | `node_modules/@deepseek-ai/dsh-experimental-api-speech-to-text` |
| 原生推理库 | `sherpa-onnx.node` + `sherpa-onnx-darwin-arm64` |

配置里的原话是"包与 sherpa-onnx-darwin-arm64 原生库都已内置在 DSH 应用里，这里只是打开开关"，
所以**升级/重装 DSH 不会丢模型**（模型在 `~/.dsh` 下，见 7.1）。

### 7.3 本项目的语音相关文件

**主机半区（插件）**

| 文件 | 职责 |
| --- | --- |
| `packages/dsh-ai-passport/lib/bridge/voice.js` | 语音域：会话 FIFO 组装、ADPCM 解码、转写、结果登记、识别目录刷新与阶段判定 |
| `packages/dsh-ai-passport/lib/config.js` | `voice.*` 配置（`directSend`/`fallbackPrompt`/`providerId`/`language`/`maxSeconds`） |
| `packages/dsh-ai-passport/lib/client.js` | 挂件语音区（启用状态 + 条件「准备模型」）与识别结果消费链（`voice.take`/`voice.ack`） |
| `packages/dsh-ai-passport/lib/protocol/constants.js` | `VOICE_*` 消息名与链路常量 |
| `packages/dsh-ai-passport/lib/index.js` | 动作 `speech.refresh` / `speech.prepare` / `voice.take` / `voice.ack` |
| `lib/bridge/voice.test.js`、`lib/bridge/voice-fill.test.js`、`test/questions-voice-integration.test.js` | 对应测试 |

**设备半区（固件）**

| 文件 | 职责 |
| --- | --- |
| `vendor/ai-passport/main/app_voice.c/.h` | PTT 采集、IMA-ADPCM 编码、分片上行、30s 录音上限与电平上报 |
| `vendor/ai-passport/main/app_alert.c/.h` | 提示音（运行时合成，不占 Flash） |
| `vendor/ai-passport/components/bsp/include/bsp_audio.h`、`components/bsp/src/bsp_audio.c` | I2S / ES8311 音频通路 |
| `vendor/ai-passport/components/bsp/src/bsp_es8311_sleep_check.c` | 编解码器休眠检查 |
| `vendor/ai-passport/components/bsp/include/bsp_pins.h` | 麦克风/I2S 引脚定义 |
| `vendor/ai-passport/main/app_ui.c`、`main/app_screens.c`、`main/app_link.c`、`main/app.c` | 录音指示、识别结果卡与语音输入页、`voice.*` 分片收发、消息分发 |

**日志**：`~/.dsh/dsh-ai-passport.log`（插件日志；串口日志见 [03-构建与烧录](03-构建与烧录.md)）。

### 7.4 可选操作：迁移或清理模型

**迁移到别的盘**（例如外置 SSD）：

1. 备份配置：`cp ~/.dsh/profiles/desktop/cordis.patch.yml{,.bak}`；
2. 移动目录：`mv ~/.dsh/speech-to-text/sensevoice /Volumes/你的盘/dsh-speech/sensevoice`；
3. 改 `dataRoot:` 指向新路径（见 7.1 的配置块）；
4. 重启 DSH；点开挂件确认语音区是**绿色「已启用」**；
   必要时核对状态快照里的 `speech.phase` 应为 `ready` 或 `standby`。
   **端口是动态分配的**（不是固定的 19387），先查再连：

   ```bash
   PID=$(pgrep -f "dsh-desktop-host/lib/index.js" | head -1)
   PORT=$(lsof -nP -a -p "$PID" -iTCP -sTCP:LISTEN | awk 'NR>1{print $9}' | sed 's/.*://' | head -1)
   curl -s --noproxy '*' "http://127.0.0.1:$PORT/dsh-passport/state.json" | head -c 400
   ```

   > 本机装了代理（OpenClash 等）时，`curl` 会把 127.0.0.1 也发给代理并得到 502，
   > 必须加 `--noproxy '*'`。

**清理释放 230MB**：删除 `~/.dsh/speech-to-text/sensevoice/` 即可。
**代价**：下次转写前要重新下载约 239MB（或提前点挂件里的「准备模型」）。

### 7.5 录音归档（**默认开启**）

每次成功解码的录音都会**落到挂件目录**并**自动清理**（用户决策：正式版默认开启）。
不想留档就在配置里显式关掉：

```yaml
# ~/.dsh/profiles/desktop/cordis.patch.yml 的 dsh-ai-passport.config 下
voice:
  keepAudio: true          # 默认 true；改成 false 即彻底不写盘
  audioDir: ''             # 空 = 挂件目录（插件包）下的 audio/
  audioKeepFiles: 20       # 保留最新多少组，超出自动清理最旧的
```

磁盘占用有上限：一组约 135KB（108KB wav + 27KB adpcm），默认 20 组 **≈ 2.7MB**。
（音频在挂件目录内，若以后把插件包纳入版本控制，记得把 `audio/` 加进 `.gitignore`。）

| 要点 | 说明 |
| --- | --- |
| 落盘位置 | 默认 `<插件包>/audio/`，即挂件目录下；`audioDir` 可改成任意路径 |
| 文件 | 每次录音两个：`<时间戳>-session<id>.wav`（可播放）+ 同名 `.adpcm`（BLE 收到的压缩原流，排查丢片用） |
| 自动清除 | 每次写入后按 **WAV 组**计数，只保留最新 `audioKeepFiles` 组；`.adpcm` 成对删除，不留孤儿 |
| 失败处理 | 归档失败只记日志（`[voice] 音频归档失败：…`），**绝不影响识别** |
| 覆盖范围 | 只归档转写前的完整录音（<500ms 的误碰按压在归档之前就被丢弃） |

> 历史遗留：早期排查"识别不准/丢片"时有一段**临时诊断**，会把每次录音无条件写到
> `~/.dsh/voice-debug/`（无开关、无清理）。该段代码与其 1.9MB 产物都已删除，
> 取而代之的就是这里的归档开关（默认开 + 自动清理，行为可控且占用有上限）。

### 7.6 判定语义（别被 "standby" 误导）

`speech.phase` 的取值与含义：

| phase | 含义 | 界面 |
| --- | --- | --- |
| `ready` | 已装且已预热 | 已启用 |
| `standby` | **已装好、只是没常驻内存**（首次推理自动唤醒） | **已启用** |
| `unprepared` / `failed` / `cancelled` | 没装 / 上次准备失败 | 未启用 + 「准备模型」 |
| `checking` / `downloading` / `preparing` / `loading` / `waking` | 正在准备 | 未启用 + 进度说明 |

## 配对（认领 / 信任握手）

- **信任表**：`~/.dsh/dsh-ai-passport.pairing.json`（权限 `0600`，由插件自管）
  内容：`{deviceId, token, name, pairedAt}`；删除即"这台电脑不再被该设备信任"。
- **动作**：`pair.submit{code}`（挂件输码后调用）· `pair.unpair`（解除配对，会通知设备清 token）。
- **快照字段**：`state.pairing = {needed, paired, deviceId, devicePaired, hostName, error, remaining}`
  - `needed=true` → 挂件显示配对输入区（未配对 / token 不匹配 / 配对失败后都会置真）
  - `error` → `bad-input` / `bad-code` / `rate-limited` / `send-failed` / `token-mismatch` / `empty-token`
- **握手**：已配对时 `hello` 带 `token`；设备校验通过才处理业务消息，否则回 `pair.required`。
- **实时性**：`needed=true` 期间挂件用 500ms 快轮询；配对状态一变就清掉过渡提示。
- 设计与安全边界见 docs/06 §9.14。

## Windows 客户端行为差异

macOS 与 Windows 跑的是**同一份插件代码、同一套 BLE 协议**（协议 v1 不分平台），
差异只在系统 BLE 后端与安装/路径形态；设备固件一次烧录、两端通用。

| 维度 | macOS | Windows |
| --- | --- | --- |
| BLE 后端（noble） | CoreBluetooth（Darwin） | WinRT（`lib/win`，需 Windows 10 1703+） |
| 扫描识别 | 广播包内短名 + 服务 UUID/厂商数据双过滤（不依赖 scan response） | 同一过滤逻辑，可靠命中 |
| MTU | `requestMtu(517)` 按请求协商 | WinRT 自动协商大 MTU；取不到数值时插件按 244 载荷工作，与固件 preferred MTU（≥247）兼容 |
| 蓝牙权限提示 | 系统设置 → 隐私与安全性 → 蓝牙 | 设置 → 蓝牙和其他设备 |
| 安装链接 | 符号链接 | 目录 junction（免管理员）；受限时自动降级复制 |
| DSH 目录 | `~/.dsh/...` | `%USERPROFILE%\.dsh\...`（同一 `os.homedir()/.dsh` 规则） |
| 语音识别 | DSH 宿主 `speechToText`（SenseVoice 本地模型） | 完全相同（宿主 API，与平台无关） |
| 录音归档 | 插件包 `audio/` 目录 | 相同 |

已知边界：

- **Windows 10 1703 之前的版本**没有 WinRT BLE 后端，noble 会走 HCI 兜底，基本不可用。
- **Windows on ARM64** 没有 noble 预编译产物，需要 VS Build Tools 源码编译 `@stoprocent/noble`。
- 挂件诊断行的 `noble <实现名>` 显示的是桥进程实际加载的后端名，排查时先看它。

Windows 上的实测项与反馈方式见 [08-Windows反馈清单](08-Windows反馈清单.md)。