dsh-mic-dictation 0.1.0 → 0.1.1

package/README.md

@@ -1,77 +1,175 @@
-# dsh-mic-dictation
+# 🎤 dsh-mic-dictation
 
-DeepSeek Harness 原生客户端插件：在 Web 提问栏的 **Full access 左侧** 插入一个麦克风按钮，点一下直接说话，识别文字写进提问框。
+<p align="center">
+  <a href="https://www.npmjs.com/package/dsh-mic-dictation"><img src="https://img.shields.io/npm/v/dsh-mic-dictation" alt="npm version"></a>
+  <a href="https://github.com/Kilganon725/dsh-mic-dictation/releases"><img src="https://img.shields.io/github/v/release/Kilganon725/dsh-mic-dictation" alt="GitHub release"></a>
+  <a href="https://github.com/Kilganon725/dsh-mic-dictation/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Kilganon725/dsh-mic-dictation" alt="License"></a>
+</p>
 
-- 浏览器原生 `SpeechRecognition`，中文识别（`zh-CN`）
-- 无需外部 API Key
-- 纯客户端插件：host 半是空 `apply`，浏览器半通过 `dsh.client` 清单发货
-- 用 `MutationObserver` 盯住 DSH 的 React DOM，把按钮稳定地放在 Full access（访问模式）按钮左边
+**dsh-mic-dictation** 是一个 DeepSeek Harness 原生客户端插件：它在 Web 提问栏的 **Full access 左侧** 加一个麦克风按钮，让你直接用电脑麦克风说话布置任务，识别出的文字会自动写进提问框。
 
-## 目录
+- 🎙️ 浏览器原生语音识别，中文优先（`zh-CN`）
+- 🔌 纯客户端插件，安装即用，无需改 DSH 源码
+- 🔐 不索取、不存储任何 API Key 或账号信息
+- ♻️ 自动跟随 React 重渲染，按钮始终待在 Full access 左边
+- 🧹 HMR / 插件卸载时自动清理按钮、样式与监听器
 
-```text
-dsh-mic-dictation/
-├── package.json        # 插件清单 + dsh.client / dsh.bundle 声明
-├── cordis.patch.yml    # bundle patch：把本插件插入 web profile
-├── lib/
-│   ├── index.js        # host half（空 apply）
-│   ├── index.d.ts
-│   ├── client.js       # 浏览器 half（lazy-CJS factory bundle）
-│   └── client.d.ts
-├── README.md
-└── LICENSE
-```
+---
+
+## 效果演示
+
+<div align="center">
+  <img src="docs/images/screenshot-composer.png" width="720" alt="提问栏麦克风按钮演示">
+  <p><sub>麦克风按钮出现在 Full access 左侧</sub></p>
+</div>
+
+<div align="center">
+  <img src="docs/images/screenshot-install.png" width="720" alt="安装命令演示">
+  <p><sub>安装后重启 dsh web 即可使用</sub></p>
+</div>
+
+> 说明：以上为产品演示图；实际界面以你的 DSH 版本与主题为准。
+
+---
+
+## 环境要求
 
-## 安装到自己的 DeepSeek Harness
+| 项目 | 要求 |
+| --- | --- |
+| DeepSeek Harness | Web profile（`dsh web`） |
+| 浏览器 | Chrome / Edge / Safari |
+| 页面地址 | localhost 或 127.0.0.1（浏览器安全上下文要求） |
+| 网络 | Chrome 语音识别依赖 Google 语音服务，需联网 |
+| 包管理器 | 安装插件需要 pnpm（`dsh plugin` 内部调用 pnpm） |
 
-先发布到 npm 或 GitHub，然后用户在自己的终端里执行：
+---
+
+## 安装
+
+### 从 npm 安装（推荐）
 
 ```bash
-# 从 npm 安装
 dsh plugin --profile web add dsh-mic-dictation
+```
+
+### 从 GitHub 安装
 
-# 或从 GitHub 安装（pnpm 会直接安装该仓库）
-dsh plugin --profile web add github:你的用户名/dsh-mic-dictation
+```bash
+# 安装最新 main 分支
+dsh plugin --profile web add github:Kilganon725/dsh-mic-dictation
+
+# 或安装指定版本
+dsh plugin --profile web add github:Kilganon725/dsh-mic-dictation#v0.1.0
 ```
 
-重启 Web：
+### 启动
 
 ```bash
 dsh web
 ```
 
-刷新页面后，首次点麦克风并允许浏览器使用麦克风即可。
+刷新页面后，提问栏 **Full access 左侧** 会出现麦克风按钮。首次点击时，浏览器会请求麦克风权限，选择 **允许**。
 
-> 说明：当前 DSH 版本的「插件市场」是**只读清单**（设置 → 插件列表）；安装入口是 `dsh plugin --profile web add ...`。等官方市场 UI 上线后，只要这个包发布在 npm/GitHub，就能被市场检索到。
+---
 
-## 发布到 GitHub / npm
+## 使用方法
 
-### GitHub
+1. 点击提问栏左侧的 🎤 按钮。
+2. 直接说话，例如：`帮我整理一下桌面上的 DeepSeek Harness 项目`。
+3. 识别中的文字会实时显示在按钮提示里，最终结果自动写入提问框。
+4. 再点一次按钮停止识别，然后正常按发送。
 
-1. 把这个目录推到新仓库。
-2. 用户安装：`dsh plugin --profile web add github:OWNER/dsh-mic-dictation`。
-3. 仓库里必须保留 `cordis.patch.yml`、`lib/client.js` 和 `package.json`；它们是发布内容，不是构建产物。
+---
 
-### npm
+## 它是怎么工作的
 
-```bash
-npm login
-npm publish --access public
+```text
+浏览器 SpeechRecognition
+        │
+        ▼
+识别出文字
+        │
+        ▼
+原生 value setter + input 事件写入 textarea
+        │
+        ▼
+DSH React 状态机接管草稿，正常发送
+```
+
+插件通过 `MutationObserver` 定位 `[data-composer-card]` 里的 Full access / 访问模式按钮，并把麦克风按钮插到它的正前方，所以位置精确且稳定。
+
+---
+
+## 隐私说明
+
+- 插件**不收集**你的语音、文字或任何会话数据。
+- 语音识别由浏览器原生的 `SpeechRecognition` / `webkitSpeechRecognition` 完成；Chrome 会把音频发送到 Google 语音服务进行识别。
+- 如果你对语音数据敏感，请不要在使用本插件时口述敏感信息。
+
+---
+
+## 常见问题
+
+<details>
+<summary>按钮没有出现？</summary>
+
+确认你运行的是 Web profile（`dsh web`），并且刷新了页面。检查插件是否已启用：设置 → 插件列表，应能看到 `dsh-mic-dictation`。
+</details>
+
+<details>
+<summary>点击后提示麦克风权限被拒绝？</summary>
+
+在浏览器地址栏左侧的权限图标里，把麦克风权限改为「允许」，然后刷新页面重试。
+</details>
+
+<details>
+<summary>识别不到中文？</summary>
+
+当前识别语言固定为 `zh-CN`。如果你的系统没有中文语音识别支持，可修改 `lib/client.js` 中的 `rec.lang` 后重新安装。
+</details>
+
+<details>
+<summary>为什么 Firefox 用不了？</summary>
+
+Firefox 对 `SpeechRecognition` 支持不完整，请使用 Chrome、Edge 或 Safari。
+</details>
+
+---
+
+## 开发
+
+本仓库是已构建好的客户端 bundle，不需要额外构建步骤。
+
+```text
+dsh-mic-dictation/
+├── package.json        # 插件清单 + dsh.client / dsh.bundle 声明
+├── cordis.patch.yml    # bundle patch：把本插件插入 web profile
+├── lib/
+│   ├── index.js        # host half（空 apply）
+│   ├── client.js       # 浏览器 half（lazy-CJS factory bundle）
+│   └── *.d.ts          # 类型声明
+└── docs/images/        # 演示图
 ```
 
-之后用户直接 `dsh plugin --profile web add dsh-mic-dictation`。
+如果你想改按钮样式、识别语言或行为，编辑 `lib/client.js`，提交后发一个新版本即可。
 
-## 工作原理
+---
+
+## 发布新版本
+
+```bash
+# 更新版本号
+npm version patch
+
+# 推送到 GitHub
+git push origin main --tags
+
+# 发布到 npm（需要已登录 npm 且通过 2FA）
+npm publish --access public
+```
 
-1. `cordis.patch.yml` 把 `dsh-mic-dictation` 作为一个 Loader entry 插进 profile。
-2. host 扫描该 entry，读到 `package.json` 的 `dsh.client` 声明，把 `exports["./client"]`（`lib/client.js`）作为客户端 bundle 提供给浏览器。
-3. 浏览器用 `window.__ModuleLoader__.load({ id, factory })` 注册这个 lazy-CJS 模块。
-4. `apply(ctx)` 在页面启动后挂载一个 DOM controller，找到 `[data-composer-card]` 里的 Full access / 访问模式按钮，把麦克风按钮插到它前面。
-5. 语音识别结果通过原生 value setter + `input` 事件写入 textarea，React 正常接管草稿。
+---
 
-## 限制
+## License
 
-- 需要 Chrome / Edge / Safari（`SpeechRecognition` / `webkitSpeechRecognition`）。
-- 需要页面运行在 localhost / 127.0.0.1（浏览器的安全上下文要求）。
-- Chrome 的语音识别依赖 Google 语音服务，需要联网。
-- 如果 DSH 前端升级改变了 `data-composer-card` 或访问模式按钮的 `aria-label`，需要同步调整 `lib/client.js` 里的选择器。
+[MIT](./LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mic-dictation",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "DeepSeek Harness client plugin: a microphone dictation button to the left of the Full access control in the web composer.",
   "type": "module",
   "main": "lib/index.js",
@@ -43,4 +43,4 @@
     "dictation",
     "speech-recognition"
   ]
-}
+}