dsh-listener 0.3.10

package/CHANGELOG.md

@@ -0,0 +1,93 @@
+# 更新记录
+
+## 0.3.10 — 2026-10-02
+
+- 统一恢复名称为 `dsh-listener`：npm 包、插件标识、设置命名空间、接口路径、客户端模块、音频处理器、样式、凭据变量、发布脚本和文档同步更名。
+- 安装与检查更新均使用 `dsh-listener` 的 npm 默认渠道；首次安装新包需重新配置密钥和设置。
+
+## 0.3.9 — 2026-10-02
+
+- 发布与插件检查更新统一使用 npm 默认渠道 `latest`，不再区分测试版与正式版。
+- 从 npm 下载固定版本安装包，验证 SHA-512、包名、版本及构建文件后交给官方管理器安装。
+- 下载设置改为 npm 官方 / npm 镜像，迁移旧默认 GitHub 代理；检查更新不再依赖插件安装服务。
+
+## 0.3.8 — 2026-10-02
+
+- 移除“一键卸载”按钮、客户端调用及服务端卸载逻辑，插件管理仅保留检查更新和更新。
+- 精简 README，集中说明 npm 安装、配置、使用与必要限制。
+
+## 0.3.7 — 2026-10-02
+
+- 准备 npm beta 分发，补充包仓库与安装说明；发布包校验自动读取版本，增加免 Token 的 GitHub Actions 手动发布工作流。
+- 将完整语音设置接入插件详情的设置页，使用与 dshmarket 相同的 `plugins.bundle.config` 插槽；增加设置内的插件标签入口，保留右键麦克风弹窗。
+- 移除独立的“语音输入”设置导航项。
+- 插件自带更新/卸载遇到 `bundle-in-use`、`stop-profile` 时显示可操作的中文错误；失败不显示更新完成。
+
+## 0.3.6 — 2026-10-02
+
+- 开放 `package.json` 导出，修复 Desktop 0.2.0-rc.2 插件列表无法读取简介的问题。
+- 设置页副标题改为“dsh-listener: 轻量化云端实时识别语音”。
+- 发布包校验增加简介与元数据导出检查。
+
+## 0.3.5 — 2026-10-02
+
+- 精简识别模型下方的提示文案。
+
+## 0.3.4 — 2026-10-02
+
+- 移除 Escape 取消录音，录音仅由设置的快捷键和麦克风按钮控制；保留失焦、切换会话等生命周期取消。
+- 删除使用说明折叠区及冗余管理提示，将地域/空间和模型说明移至对应输入框下方。
+- 录入快捷键按钮移至输入框右侧。
+- 将清除密钥复选框替换为刷新前的“清除已保存配置”按钮，清除密钥并恢复默认设置。
+- 独立重构进度显示和设置操作，减少嵌套 JSX 与重复回填，保留现有核心功能。
+
+## 0.3.3 — 2026-10-02
+
+- 默认预填支持标签 API 的镜像 `https://gh-proxy.org`，保留已有自定义地址。
+- 官方下载模式隐藏镜像网址，切回镜像后保留已有地址。
+- 下载来源与有效镜像网址自动保存；切换来源、关闭并重新打开设置后保持。
+- 自动保存仅修改下载设置，和手动保存串行处理，不提交未保存的模型或密钥。
+
+## 0.3.2 — 2026-10-02
+
+- 插件管理增加 GitHub 官方 / 镜像下载选择和镜像网址输入框，支持保存配置，旧配置默认官方来源。
+- 镜像模式同时代理版本标签与版本清单，并通过固定标签的 `.tar.gz` 地址交给官方插件管理器安装。
+- 新增下载字节/百分比进度、安装阶段及完成提示；官方与镜像均先下载固定版本包并校验，安装后仅清理本次临时文件。
+- 检查网络超时由 10 秒延长至 30 秒，超时与镜像返回非 JSON 改为明确中文提示。
+- 来源修改后清除旧检查结果，检查/更新立即使用当前表单中的来源；镜像失败不自动回退。
+
+## 0.3.1 — 2026-10-02
+
+- 修复 Alt 修饰键过早确认的问题，支持 Alt+Space、Ctrl+Shift+V 及仅修饰键的组合；长按组合键松开任一组成键即停止。
+- 服务正常但未识别到文字、极短录音未采到音频时安静结束，不弹窗、不修改草稿、不自动发送；服务错误仍提示。
+- 插件管理状态移至检查更新按钮下方，与保存设置提示分开。
+- README 按桌面版、命令行和本地开发分条说明安装步骤。
+
+## 0.3.0 — 2026-10-02
+
+- 本地语音通道改为同源 HTTP 二进制分块上传和结果长轮询，绕开 Desktop 中自定义 WebSocket 握手失败；百炼端仍为实时 WebSocket。
+- 上传顺序串行化，结束指令等待全部 PCM 上传；取消中止请求并释放任务，断联任务定时回收。
+- 设置页新增“检查更新”“更新”“一键卸载”，使用官方插件管理器，固定操作本仓库/本插件。
+- 检查正式发布标签并验证清单；录音期间拒绝更新/卸载，显示版本更新需要重启的实际结果。
+- 复用或按需挂载官方配置 HMR 和包管理服务，支持热卸载，不做不受控的目录删除。
+
+验证：HTTP 集成测试中禁用本地 WebSocket，仍完成 PCM 上传与最终文字返回；管理操作以 mock 验证固定目标、鉴权、忙状态和重启要求。实际 Harness 浏览器中完成 GitHub 更新检查，禁用插件 WebSocket 后仍连接到百炼并收到占位密钥的预期 HTTP 401。没有使用用户密钥，未实际卸载用户 profile。
+
+## 0.2.1 — 2026-10-02
+
+- 输入框旁只保留麦克风；错误和需手动处理的结果改用弹窗，设置入口为“设置 → 语音输入”，也可右键麦克风。
+- 设置表单缩小字号、间距、输入框尺寸，说明折叠显示。
+- Workspace ID 支持粘贴百炼完整 API Host，自动提取北京/新加坡地域与空间 ID。
+- 区分 Harness 本地握手、登录/来源拒绝与百炼鉴权失败；密钥缺失或不可读取时通过已建立的通道返回明确错误。
+- 修复设置初次加载可能覆盖正在编辑的表单。
+
+验证：33 项测试、类型检查、构建和打包检查；真实 Harness WebSocket 与无效测试密钥的百炼 HTTP 401 路径已验证。用户 Desktop 的握手失败原因尚待新提示进一步确认。
+
+## 0.2.0 — 2026-10-02
+
+- 在麦克风旁新增“语音设置”按钮，直接打开 API Key 和录音选项配置。
+- 设置页改为独立的“云端语音输入”导航，避免依赖插件设置子页。
+- 更新 Desktop 安装说明及宿主 HMR、热启停、版本升级的区别。
+- 保留百炼流式上传、右 Alt 长按/点按及默认关闭的自动发送。
+
+验证：TypeScript、26 项测试、构建及安装包检查通过；同版本 Harness Web 中验证两个设置入口。真实百炼调用和用户 Desktop 实例仍需验收。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-listener contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# dsh-listener
+
+DeepSeek Harness 云端实时语音输入插件。按住右 Alt 说话，松开停止；识别文字追加到当前会话草稿，默认不发送。
+
+当前版本 **0.3.10**。安装与检查更新统一使用 npm 默认渠道。兼容 Harness **0.2.0-rc.2**、Node.js **22.19+（22.x）或 24+**，推荐 Chrome / Edge。更新记录见 [CHANGELOG.md](CHANGELOG.md)。
+
+## 安装
+
+在 DSH Desktop 的 **插件 → 添加插件** 中填写 `dsh-listener` 安装最新版。安装后完全退出并重新打开 Desktop。
+
+命令行安装：
+
+```powershell
+npm install -g @deepseek-ai/dsh@0.2.0-rc.2
+dsh plugin --profile web add dsh-listener
+dsh web
+```
+
+## 配置
+
+打开 **插件 → dsh-listener → 设置**，或右键会话输入框旁的麦克风。填写百炼 API Key，确认地域与 Workspace ID，点击保存。Workspace ID 支持粘贴完整 API Host 自动提取。
+
+| 设置 | 默认值 / 说明 |
+| --- | --- |
+| 地域 | 北京，可选新加坡；须与密钥匹配 |
+| Workspace ID | 工作空间 ID；留空使用传统 DashScope 域名 |
+| 识别模型 | `qwen-audio-3.1-asr-flash-streaming`；须支持 DashScope 流式 ASR 协议 |
+| 快捷键 | 右 Alt，可录入单键或组合键 |
+| 录音模式 | 长按，可切换为点按 |
+| 自动发送 | 关闭；开启后连同原草稿一起发送 |
+
+API Key 由 Harness 凭据服务保存，设置接口不回传密钥；也支持启动环境变量 `DSH_LISTENER_API_KEY`。环境变量优先时页面可能无法修改密钥。“清除已保存配置”会清除已保存密钥并恢复默认设置。
+
+## 使用
+
+- 选择会话并允许麦克风权限，按钮变绿后开始收音。长按快捷键录音，松开停止；点按模式和麦克风按钮均为再次点击停止。
+- 录音中悬停麦克风可查看预览；停止后等待最终文字追加到草稿，原内容与引用保留。没有识别到语音时安静结束。
+- 快捷键仅在页面获得焦点时生效。AltGr 用户请改绑其他键；浏览器或系统保留的组合可能不可用。
+- 切换会话、标签页或窗口失焦会取消本次录音。每次最多录音 120 秒；远程页面需要 HTTPS，localhost 可直接使用。
+
+## 更新
+
+设置中的 **插件管理** 提供检查更新、更新及下载进度，与安装统一查询 npm 的 `latest`。发布新版后，点击检查更新即可发现；本地修改尚未发布时不会推送给用户。录音期间禁止更新，安装后按提示重启 Desktop。
+
+下载来源默认 npm 官方，可切换为 npm 镜像（默认 `https://registry.npmmirror.com`）。镜像可能延迟同步，刚发布后优先使用官方来源；失败时不会自动回退。下载设置自动保存，镜像不代理百炼音频或密钥。安装前验证安装包完整性与插件版本。
+
+此前使用旧包名安装的用户，请在 Desktop 插件管理中停用旧插件，安装 `dsh-listener` 并重启，重新填写密钥和设置。安装新包后，后续版本可通过设置检查 npm 更新。
+
+## 隐私与排错
+
+音频经 Harness Host 上传至阿里云百炼，插件不保存音频文件或录音日志；最终文字遵循 Harness 草稿和消息的保存行为。取消无法撤回已上传音频，可能已经计费。同一 Host/profile 的设置与密钥由已授权用户共享，默认凭据存储不是加密钥匙串。
+
+按钮不可用时检查会话与 HTTPS；本地握手失败时更新插件并重启 Desktop；百炼 401/403 时检查密钥、地域、空间和模型权限。失败不会自动重试或切换服务。
+
+真实百炼准确率、延迟、计费、各 Desktop 环境、接近 120 秒录音收尾和更新期间开始录音的并发行为仍需验收。
+
+## 开发
+
+```powershell
+pnpm install --frozen-lockfile
+pnpm check
+pnpm verify:package
+```
+
+详细说明：[验证记录](docs/VALIDATION.md) · [更新机制](docs/UPDATES.md) · [npm 发布](docs/PUBLISHING.md)。
+
+采用 [MIT](LICENSE)，上游来源与版权见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,52 @@
+# 借鉴工程与版权声明
+
+本插件复用 Harness 的公共插槽、输入动作、连接鉴权、凭据与设置服务；不修改 Harness 源码。
+
+## DeepSeek Harness
+
+- 项目：https://github.com/deepseek-ai/deepseek-harness
+- 调研源码版本：`639ed015397290b3745d163aafe02ffee4aa3f84`
+- 实际编译和运行接口：npm `0.2.0-rc.2`（Cordis `4.0.4`）。
+- 来源：`packages/experimental/client-ui-voice-input/src/client/audio.ts` 和 `mount.ts`。
+- 使用位置：`src/client/audio.ts` 的麦克风获取、迟到授权取消和轨道释放生命周期；`src/client/index.tsx` 的插槽注册方式。
+- 改动：完整录音改为 AudioWorklet PCM16 分块；新增右 Alt 和点按控制；最终结果追加末尾；新增百炼服务端流式通道。没有复制或安装 SenseVoice 本地识别运行时。
+
+## dsh-voice-input
+
+- 项目：https://github.com/forrestahha/dsh-voice-input
+- 来源版本：`76c1c5acbb9cc51584e14199d4fc588a4699f965`（v0.1.1）。
+- 来源：`package.json`、`cordis.patch.yml`、`tsdown.config.ts`。
+- 使用位置：插件的 Host/Client 双入口、Bundle 安装清单以及 `scripts/build.mjs` 的 Harness CommonJS 客户端模块工厂包装。
+- 改动：使用 esbuild 构建；更换包名和兼容版本；新增流式 Host；替换 Web Speech 识别。
+
+## 调研参考，未复制其实现
+
+- https://github.com/Richard-Yang0130/dsh-web-speech-input — 最终结果进入草稿、状态提示。
+- https://github.com/GooDAnDReaDY/dsh-voice — 快捷键与点按/按住手势对比。
+- https://github.com/agent-mobile/dsh-speech — Host 语音适配结构对比；其 DashScope 批量接口没有用作本插件流式接口。
+
+## 上游 MIT 许可
+
+Copyright (c) 2026 DeepSeek
+
+Copyright (c) 2026 forrestahha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+`ws`、React、Harness 及其他 npm 依赖的许可证归各自项目所有，安装时由包管理器分发；本项目的 MIT 不替代其许可证。百炼 API 是独立云服务，使用者应遵循其服务条款。

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsh-listener
+      name: dsh-listener

package/docs/PUBLISHING.md

@@ -0,0 +1,34 @@
+# npm 发布
+
+包名为 `dsh-listener`，默认渠道为 `latest`，目标 registry 为 `https://registry.npmjs.org`。发布同一版本前应检查该版本是否已存在；每次发布新内容必须提升版本。
+
+## 本机发布
+
+先由维护者运行 `npm login --registry=https://registry.npmjs.org`，完成浏览器认证；同一操作系统用户下的 npm 命令可使用登录凭据，不需要向聊天发送密码或 Token。发布仍可能要求交互式二次认证。
+
+依次执行（前一步失败时停止）：
+
+```powershell
+pnpm check
+pnpm verify:package
+npm publish ./output/dsh-listener-版本号.tgz --dry-run --tag latest --access public --registry=https://registry.npmjs.org
+npm publish ./output/dsh-listener-版本号.tgz --tag latest --access public --registry=https://registry.npmjs.org
+```
+
+将命令中的版本号替换为 `package.json` 的 version。实际发布使用已经校验的 tgz。发布后运行 `npm view dsh-listener dist-tags --registry=https://registry.npmjs.org` 核对渠道和版本。
+
+## GitHub 自动发布
+
+首次建立 npm 包后，在 npm 包 Settings → Trusted Publisher 添加 GitHub Actions：
+
+- GitHub 用户：`gone1724`
+- 仓库：`dsh-listener`
+- 工作流文件名：`publish.yml`
+- Environment：留空（此工作流没有声明 GitHub Environment）
+- 允许操作：`npm publish`
+
+配置完成后，在 GitHub Actions 中选择 **Publish npm → Run workflow**，选择 `master` 分支。工作流验证、构建、打包并通过 OIDC 发布，不需要 `NPM_TOKEN`。同一版本已经发布时需要先提升版本再运行。
+
+工作流使用 Node.js 24 和 npm 11，满足 npm Trusted Publishing 要求。统一发布到 `latest`；发布成功后，0.3.9 起的插件检查更新会查询该渠道。每次发布前完成适当验证，真实云端与 Desktop 的验收限制见 README。
+
+官方说明：https://docs.npmjs.com/trusted-publishers/

package/docs/UPDATES.md

@@ -0,0 +1,83 @@
+# 设置入口与更新机制
+
+## 0.3.10 恢复名称
+
+插件统一使用 `dsh-listener`，更新查询为 `https://registry.npmjs.org/dsh-listener/latest`。旧包安装不会自动更名，请在 Desktop 停用旧插件后安装 `dsh-listener` 并重启，重新配置 API Key 和设置。凭据变量改为 `DSH_LISTENER_API_KEY`，接口、配置命名空间与客户端标识也随包名同步更新。
+
+## 0.3.9 统一 npm 更新
+
+安装与插件内“检查更新”统一使用 npm 的 `latest`。检查请求为 `https://registry.npmjs.org/dsh-listener/latest`，不再查询 GitHub 标签，也不再区分 beta / 正式渠道。检查无需启动官方管理器；点击更新时重新查询并固定版本，下载 npm `.tgz`，验证 SHA-512、包名、版本及构建文件后调用 `installBundle`。官方管理器的版本替换和重启限制仍适用。
+
+下载来源为 npm 官方或 npm registry 镜像，默认镜像 `https://registry.npmmirror.com`；镜像按 registry 路径请求，不拼接完整 GitHub URL。旧默认 GitHub 代理自动迁移，其他自定义地址应改为 npm registry。镜像可能延迟同步，检查最新发布优先使用官方来源。
+
+0.3.8 及更早版本仍执行旧 GitHub 更新逻辑，0.3.9 查询旧 npm 包；这些版本均需在 Desktop 插件管理中安装 `dsh-listener` 并重启一次。下文是历史版本记录。
+
+## v0.3.7 插件详情设置入口
+
+完整语音设置接入宿主 `plugins.bundle.config`，以包名 `dsh-listener` 为 key，显示在插件列表中本插件的详情设置页。与 dshmarket 使用同一插槽机制，不向插件卡片摘要塞入整个表单。另注册 `settings.plugins.tab` 的“语音输入”标签，并保留右键麦克风弹窗；移除单独的 `settings.section` 导航项。
+
+入口包含密钥、录音、快捷键、下载来源、检查更新和更新，复用同一表单及接口。插件运行时可发起更新，更新直接调用官方 `installBundle`；安装返回 `restart-required` 时仍需完全退出并重开 Desktop。设置热生效与代码版本的无重启替换是不同能力，当前未实现后者。
+
+`bundle-in-use` 表示宿主卸载配置层后仍发现该 bundle 的运行条目，不能当作安装成功。插件自带管理接口将该错误转为中文，并将更新进度保留为失败；Desktop 自身的 JSON 错误展示不由本插件控制。若需要禁用后操作，应使用 Desktop 自带插件管理入口，禁用后本插件的设置入口随之消失。
+
+## 0.3.4 设置页
+
+删除 Escape 录音取消和额外使用说明，录音使用自定义快捷键或麦克风按钮。失焦和切换会话仍取消录音。空间/地域与模型提示分别移至对应输入框下面；快捷键按钮和文本框同一行。
+
+“清除已保存配置”位于刷新前，清除凭据并恢复插件默认设置，Host 验证可写权限与配置版本，录音期间拒绝清除。下载设置仍自动保存，失败使用简短弹窗提示，不在表单中显示冗长错误。
+
+## 0.3.3 下载设置自动保存
+
+默认镜像预填 `https://gh-proxy.org`，保留已有自定义地址。官方模式隐藏镜像网址；镜像模式显示。来源与有效镜像前缀自动保存到当前 profile，输入停止 500 ms 后提交，关闭页面时提交待保存的地址。切换官方不会清除镜像网址。镜像为空时可记住来源，实际检查/下载仍要求填写有效前缀。自动保存只更新下载字段，不提交 API Key 或覆盖其他未保存表单；写请求按顺序发送并使用最新设置版本。
+
+## 0.3.2 下载来源
+
+设置 → 语音输入 → 插件管理增加 GitHub 官方下载和 GitHub 镜像下载；镜像前缀支持 HTTPS，可带路径，不支持账号、查询参数或 URL 片段。镜像需支持 API、Raw 与 Archive 请求。版本检查与清单验证使用相同镜像；安装目标为固定仓库、正式标签的 `.tar.gz`，继续交由官方包管理器处理，不写入安装目录。
+
+表单选择立即用于本次检查/更新，保存后写入当前 profile。旧配置迁移为官方模式。镜像不接收百炼密钥和音频，npm 依赖下载仍使用宿主 registry。版本替换仍可能要求重启。
+
+官方与镜像下载均先写入一个随机命名的临时 `.tgz` 文件，限制 32 MB。下载进度按实际已接收字节报告；无 Content-Length 时只显示已下载容量。下载完成后校验包名、目标版本及必要构建文件，再显示安装阶段并交给官方管理器。安装成功显示 100% 和重启要求，失败不标记完成；成功或失败均仅删除本次明确路径的临时文件。安装阶段无法取得百分比，因此使用不定进度。
+
+## 0.3.0 插件管理与传输
+
+设置页提供“检查更新”和“更新”。查询固定 GitHub 仓库的正式标签并验证包名/版本；更新通过 Harness 官方包管理器的 `installBundle`，使用 profile 锁和官方 pnpm 调用。管理器不足时在应用根上下文挂载官方服务，保证版本替换期间管理器仍可运行；配置 HMR 只监听 profile，不监听其他源码。录音中禁止版本替换。
+
+`0.2.0-rc.2` 对已安装版本的替换仍返回 `restart-required`，界面直接显示重启要求。热配置与热卸载可以生效，版本替换不宣称一定无需重启。没有自建远程代码下载执行器，也不调用任意 shell。
+
+本地录音改用带 Harness 同源鉴权的 HTTP 分块 PCM 上传和结果长轮询，Host 到百炼仍为 WebSocket。这避免依赖 Desktop 自定义 WebSocket 转发；每个通道使用随机会话 ID、4 个活动通道上限、30 秒断联回收、串行上传和取消清理。HTTP 可用但本地 WebSocket 不可用的情况已在集成测试复现，真实用户 Desktop 修复效果待新版本验收。
+
+## 0.2.1 当前入口
+
+设置页名称为“语音输入”。输入框旁只显示麦克风；右键麦克风打开设置，尚未配置时点击也可打开。错误通过应用内弹窗呈现，参考 [dsh-plugin-notify](https://github.com/c-ling/dsh-plugin-notify) 将临时提示放在页面浮层的方式，自行实现原生 dialog，不引入额外通知插件。下文记录 0.2.0 的入口修复及宿主更新机制。
+
+Workspace ID 支持直接粘贴百炼域名或完整 API Host，自动提取地域和空间 ID；音频仍只上传至允许的百炼域名，使用 `/api-ws/v1/inference`。
+
+原有笼统连接报错已拆分：浏览器到 Harness 本地 WebSocket 的失败，以及 Host 到百炼的连接/鉴权失败。前者会额外检查同源设置接口的 HTTP 状态；后者显示安全的 HTTP 状态或网络错误代码。尚未在用户 Desktop 实例中确认导致本地握手失败的具体原因。
+
+## 0.2.0 设置入口修复
+
+旧版将设置页注册到 `settings.plugins.tab`。这个插槽由插件设置页面的拥有者声明，Desktop 的页面组合未提供该页面时，注册会等待，麦克风仍可显示。这是目前的可能原因，尚未直接检查用户 Desktop 的运行时页面组合。
+
+当前改用 `settings.section` 提供独立的“云端语音输入”页，并在麦克风旁提供“语音设置”按钮，直接打开同一表单。API Key 仍通过原来的鉴权接口写入 Harness 凭据服务。
+
+## 三种更新
+
+| 操作 | 实现及限制 |
+| --- | --- |
+| 修改 API Key、模型、快捷键、自动发送 | 已实现。保存后更新客户端配置，下一次录音使用新配置，无须重启。 |
+| 热启停 / 本地源码重载 | 使用宿主 Cordis Loader 和 HMR。插件释放麦克风、连接、事件和界面，宿主重新激活。是否启用文件监听由 Desktop profile 配置决定。 |
+| 下载并替换新版本 | 使用 Desktop / 官方插件管理器。官方当前文档明确说明替换已安装包版本仍需重启，不能把热启停称作无重启升级。 |
+
+本地安装不等于源码文件自动监听。如果 Desktop 将本地包复制到 profile 中，修改本仓库的 `lib/` 不会修改安装副本；需要在 Desktop 的插件管理中重新安装同一本地目录。若是链接安装，也需要宿主 HMR 监控真实路径。源码修改后先执行 `pnpm build`；未启用 HMR 时重启 Desktop，以加载新的 Host 和 Client。
+
+首次使用这次修复，请重新安装本地插件源码目录并重启 Desktop。更新表单入口后，普通设置修改不再需要重新安装或重启。
+
+## 调研来源
+
+- [官方 HMR](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/boot/hmr/README.md)：统一重载队列、配置监听、模块监听；已安装包版本替换仍需重启，Client 有独立加载机制。
+- [官方插件管理器](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/boot/plugin-manager/README.md)：包操作、profile 写锁、配置重新组合和资源卸载。
+- [dsh-plugin-hot-toggle](https://github.com/5102a/dsh-plugin-hot-toggle)：调用 `Entry.update({ disabled })` 热启停，写入 patch 持久化；它不是下载新版本的更新器。
+- [dsh-plugin-toggle](https://github.com/Zenjibad/dsh-plugin-toggle)：同类启停机制，并提示新 Client bundle 可能需要完整页面刷新。
+- [DSH Desktop](https://github.com/dsh-tauri/deepseek-harness-desktop/blob/main/README.en.md)：由桌面插件管理负责升级/卸载，内核更新与插件版本更新分别管理。
+
+目前未增加独立远程自动更新器：直接写 Desktop 的安装目录会绕过宿主包管理及并发保护。仓库 `gone1724/dsh-listener` 通过 `v0.2.0` 发布标签提供固定版本，通过 Desktop 的插件管理流程分发。

package/docs/VALIDATION.md

@@ -0,0 +1,76 @@
+# 验证记录
+
+## v0.3.7 插件详情设置入口
+
+- `pnpm check` 通过：51 项测试、TypeScript 检查及 Host/Client 构建。
+- 对照本地 Harness 0.2.0-rc.2 的插件页面源码确认 `plugins.bundle.config` 为包名 keyed 插槽，详情页传入 `view: 'page'`；语音表单以 `dsh-listener` 为 key 注册。
+- 管理接口回归覆盖 `bundle-in-use` 返回结果及抛出对象两种形式，均显示中文、进度为 error，并可重试；成功替换仍返回宿主的重启要求。
+- 尚未在用户 Desktop 上验证插件图标点击后的实际页面，也未验证真实版本替换或无重启加载新版。
+
+日期：2026-10-02。环境：Windows、Node.js 22.23.2、pnpm 10.18.0、Harness 0.2.0-rc.2、Cordis 4.0.4。
+
+## v0.3.4 新增验证
+
+- 51 项测试、类型检查和构建通过；配置清除测试验证恢复默认、移除凭据、拒绝过期和混合保存请求。
+- 真实 Harness 页面验证删除的说明不再显示，Workspace/模型提示位于对应输入框下方，快捷键录入按钮位于输入框右侧，操作顺序为保存、清除已保存配置、刷新。
+- 合成静音麦克风、真实 AudioWorklet 和 mock HTTP 通道：按住 F8 录音时按 Escape 不停止，松开 F8 正常结束。未使用用户密钥。
+- 在独立测试 profile 中实际执行清除，凭据变为未配置、快捷键恢复 AltRight、自动发送关闭、默认官方来源和镜像地址恢复；刷新后仍保持。没有清除用户 Desktop 的配置。
+- 按 code-simplification 技能分开提交功能与重构；进度显示移入独立组件，保存/清除使用命名函数与共享回填逻辑，每次重构均通过现有测试。浏览器 mock 重新验证下载 50%、不定安装、完成 100% 及重启提示。
+
+## v0.3.3 新增验证
+
+- 51 项测试、类型检查和构建通过；新增覆盖下载字段独立保存和与手动保存串行，旧设置补齐默认镜像。
+- 真实 Harness 页面验证官方模式隐藏镜像文本框，切回镜像保留内容；无手动保存时自动写入 Host；输入后立即关闭设置仍保存，刷新页面后地址保留。
+- 自动保存未提交正在编辑的模型，也不提交 API Key；已有自定义镜像优先于默认地址。
+- 2026-10-02 实测默认镜像 https://gh-proxy.org 的标签 API 和 v0.3.2 清单均 HTTP 200，固定标签压缩包下载及包名/版本/构建文件校验通过。第三方服务后续可用性仍取决于用户网络。
+
+## v0.3.2 新增验证
+
+- 49 项测试、类型检查和构建通过：镜像标签/清单/压缩包请求地址、旧设置迁移、前缀校验、下载失败、进度鉴权及安装目标均有覆盖。
+- 真实本机 HTTP 分块下载测试：已下载字节与文件内容一致；Content-Length 存在时报告总大小，不存在时保持未知总大小；校验错误版本包和 HTTP 错误；临时文件按单一路径清理。
+- 实际下载 GitHub v0.3.1 源码 `.tar.gz`，包名、版本和构建文件校验通过，临时文件删除成功。未对用户 profile 执行真实更新或卸载。
+- 真实 Harness 设置页保存镜像前缀并刷新后仍显示；浏览器 mock 更新操作验证 50% 下载、不定安装进度、100% 完成及重启提示，更新请求携带所选镜像。截图保存在本地 output/playwright/v032-*.png。
+- 国内网络环境、第三方镜像可用性和真实版本替换仍需用户环境验收；本机 HTTP / 浏览器 mock 不代表镜像服务已完成真实下载验收。
+
+## v0.3.1 新增验证
+
+- 43 项测试、类型检查和构建通过；新增覆盖 Alt 组合录入、纯修饰键组合、组合键释放、空文本正常结束和零 PCM 取消。
+- 在独立测试 profile 的真实 Harness 0.2.0-rc.2 Chromium 页面中录入 Alt+Space 与 Control+Shift+KeyV，成功保存。
+- 设置页实际查询 GitHub 标签；“当前已是最新版本”位于检查更新按钮下方，同时保留“设置已保存”。截图：本地 output/playwright/v031-settings.png（不随包发布）。
+- 使用合成静音麦克风和真实 AudioWorklet，经 mock HTTP 服务正常返回空最终文本：麦克风轨道释放，无弹窗，已有草稿保持不变。未使用用户密钥或真实百炼识别。
+
+## 已验证
+
+- `pnpm check`：TypeScript 检查、43 项测试及 Host/Client 构建通过。
+- 本机真实 WebSocket mock 上游：run-task、等待 task-started、二进制音频顺序、finish-task、句尾结果及 task-finished。
+- 客户端异步权限申请取消、连接等待缓冲、残余音频先于结束指令、断线取消及 120 秒上限正常收尾。
+- 快捷键长按/点按状态机、重复事件、左右 Alt 区分、AltGr 排除、按住期间改变模式。
+- 草稿追加、引用芯片坐标、自动发送动作顺序、编辑后抑制自动发送、锁定时保留结果。
+- 用 `dsh plugin --profile web add .` 从本地源码目录安装到独立测试 profile 并启动，Client 模块能实际激活。
+- 实际 Harness 设置页：默认模型、右 Alt、长按、自动发送关闭；API Key 保存成功且不回传密钥；刷新页面后配置仍可用。
+- 实际 Chromium 页面：合成麦克风音频通过真实 AudioWorklet 产生 242 个 PCM 块（774400 字节）；麦克风录音按钮显示绿色，停止时释放轨道。
+- 浏览器 mock 最终结果将 `已有草稿。` 更新为 `已有草稿。这是流式语音测试。`，没有自动发送。
+- 实际 Host 设置接口：无登录状态返回 401，外部 Origin 返回 403。
+- `pnpm verify:package`：安装包包含 11 个文件，包含客户端模块工厂、PCM worklet、更新日志、更新说明和本验证记录，排除了凭据、测试 profile、node_modules 等私有文件。
+- 设置入口修复后在同版本真实 Harness Web 中验证：麦克风旁的“语音设置”弹窗可打开 API Key 表单；设置导航独立的“云端语音输入”页也显示完整表单。用户 Desktop 实例仍待复核。
+
+## 尚未验证
+
+0.3.0 新增验证：默认 HTTP 通道在真实本机 HTTP 服务（禁用所有 WebSocket 升级）中完成实时 PCM 上传、顺序 finish、最终文本和取消。管理接口测试验证 GitHub 正式版本与固定发布标签、更新/卸载仅针对本插件、鉴权和录音期间拒绝操作。真实 Harness 设置页执行了 GitHub 检查更新，并实际激活官方包管理服务；浏览器禁止插件 WebSocket 后，仍经 HTTP 通道到达百炼并收到无效占位密钥的 HTTP 401。尚未执行真实版本下载替换或真实卸载，用户 Desktop 上仍需更新后验收。
+
+0.2.1 新增验证：真实 Harness 页面中的本地 WebSocket 握手成功，使用独立测试 profile 中的无效占位密钥收到百炼 HTTP 401（没有使用用户提供的密钥）。浏览器模拟本地握手失败时，正确显示弹窗；右键麦克风打开设置；没有额外固定按钮；API Host 自动提取及紧凑布局已截图检查。新增测试覆盖缺失/不可读凭据的本地 WebSocket 错误响应、域名校验和 HTTP 401/403 定位。用户 Desktop 的真实失败原因尚未确认。
+
+- 真实百炼 API Key、账户模型开通、专属 Workspace 域名、识别准确率、延迟和计费。当前只验证官方协议对应的 mock，不能将其视为云端验收。
+- 物理键盘上的 AltGr 各语言布局、其他浏览器、macOS/Linux、Harness 桌面容器。
+- GitHub 远程安装和 GitHub Actions 实际运行：本次验证未执行远程安装或检查远程 CI；CI 工作流已提供。
+
+## 人工云端验收
+
+1. 按 README 安装，在设置页填写真实百炼密钥、对应地域和 Workspace ID。
+2. 先确认自动发送关闭。用麦克风按钮和右 Alt 各录一次，检查开头、句尾和停止后的等待时间。
+3. 点按模式中检查第二次按下停止、松开不重启。
+4. 草稿中已有文字和引用时录音；等待期间继续编辑，确认文字和引用完整、一次撤销能撤回追加。
+5. 开启自动发送，用没有敏感内容的草稿检查完整提交；录音期间编辑草稿，确认只追加并提示手动发送。
+6. 录音期间切出窗口或切换会话，检查浏览器麦克风标记消失、迟到结果不写入其他会话。按 Escape 不应停止录音；使用已配置快捷键或麦克风按钮正常停止。
+7. 在 AltGr 布局输入特殊字符，确认不触发录音；改绑 F8 再检查正常录音。
+8. 分别使用错误密钥、不可用模型和断网状态，检查明确错误、无自动重试、无自动发送。