声云智能鼠标插件

使用声云智能鼠标在桌面应用中进行语音输入、翻译和搜索，并通过 DeepSeek Harness 管理鼠标按键和灵敏度。安装后，可在 Harness 设置中的“声云设备”查看和配置鼠标。

你可以做什么

• 语音打字：按住鼠标语音键说话，松开后将识别文字填入按键时聚焦的可编辑输入框，不自动发送。
• 语音翻译：设置源语言和目标语言，将语音键或 M 键设为语音翻译，松开后回填译文。
• 语音搜索：将 M 键设为语音搜索，说出关键词后使用所选搜索引擎搜索。
• 自定义按键：为 M 键选择回车、后退、一键链接等动作；长按 AI 键可唤起 Harness 并向 AI 对话输入框填入语音文字，默认自动发送，可在设备设置关闭。
• 管理多台鼠标：查看连接方式、电量和设备序列号，分别保存每台鼠标的语言、按键和灵敏度设置。

插件根据当前鼠标身份自动接入服务，无需手填鉴权配置。

使用前准备

• DeepSeek Harness 0.2.1-rc.5 或更高版本。
• 支持本插件的声云智能鼠标，通过蓝牙或 2.4G USB 接收器连接。
• 插件安装包（.tgz 文件），以及可访问语音服务的网络。

安装包包含 Apple 芯片 Mac 和 Windows x64 所需的设备组件。维护者已确认完成 0.1.0 的实机验收；其他系统暂不保证可用。

安装与启用

1. 启动一次 Harness，完成初始化，然后完全退出应用。

2. 在终端执行以下命令，将路径替换为你取得的安装包的完整路径：

   dsh plugin --profile desktop add "/绝对路径/sonicloud-dsh-sonicloud-device-0.1.1.tgz"
   

   文件名以实际安装包为准。Mac 如果提示找不到 dsh，可使用：

   "/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh" plugin --profile desktop add "/绝对路径/sonicloud-dsh-sonicloud-device-0.1.1.tgz"
   

3. 重新启动 Harness，在插件管理中启用 dsh-sonicloud-device。

4. 打开设置，进入侧栏的“声云设备”。

正式版也可按确切版本从 npm 安装：

dsh plugin --profile desktop add @sonicloud/dsh-sonicloud-device@0.1.1

若安装提示 ERR_PNPM_IGNORED_BUILDS 且指向 koffi，在该 profile 的 pnpm-workspace.yaml 中补充以下配置，替换为报错中的确切版本后重试；保留已有配置，仅批准这一原生依赖：

allowBuilds:
  "koffi@<报错中的版本>": true

从旧包迁移时，完全退出 Harness，先运行 dsh plugin --profile desktop remove dsh-sonicloud-device，再安装新包。插件实例 ID 仍为 dsh-sonicloud-device，按 SN 保存的设备偏好继续使用原存储键；不要删除 profile 数据。

测试包从 Actions 的运行摘要下载，保留 30 天；下载需要登录 GitHub，解压外层归档后安装其中的 .tgz。

开始使用

连接与设置鼠标

打开鼠标电源，选择蓝牙或 2.4G 模式并完成连接。在“声云设备”中选中鼠标，即可查看电量、连接方式和序列号（SN）。

你可以调整语音识别语言、是否保留标点、鼠标灵敏度（DPI）以及按键动作。更改后自动保存，无需点击保存按钮。“恢复默认”只重置当前鼠标；重新连接同一台鼠标时会恢复已保存的设置。

语音输入

1. 在“声云设备”中，将“语音键”设为“语音打字”，选择识别语言。
2. 在目标应用的可编辑输入框中放置光标；不必打开 Harness 对话。
3. 按住鼠标语音键说话，松开后等待识别完成。
4. 检查输入框中的文字，再自行发送。

录音来自鼠标。识别中间文字、整理和翻译状态显示在鼠标所在屏幕底部居中的独立浮层，不抢占输入焦点。Harness 主窗口最小化、隐藏或切换页面不会取消会话；插件后台仍须运行，完全退出 Harness 后不可用。

点击浮层叉号按钮或断开鼠标可取消会话。输入目标、内容或选区发生变化，或应用不支持安全回填时，浮层保留结果供复制。macOS 自动回填需要在“系统设置 → 隐私与安全性 → 辅助功能”中允许 Sonicloud Voice；没有权限仍可识别并复制结果。Windows 对不提供可编辑 UI Automation 文本接口的输入框保留结果供复制。

macOS 默认使用兼容粘贴回填，支持 Zed 等未提供辅助功能写入接口的应用。录音期间保持目标窗口和文档，不进行键盘编辑、鼠标点击或滚动；可读取内容与选区时也会检查是否变化。回填临时使用剪贴板并恢复原内容，不覆盖期间的新复制内容；检测到目标或输入活动变化时保留结果供复制。

按键与搜索

按键	使用方式
语音键	选择语音打字或语音翻译，按住说话、松开结束
M 键	可选回车、后退、语音打字、语音翻译、语音搜索、一键链接等动作；语音动作按住说话，其他动作在松键时执行
AI 键	长按说话、松开结束；Harness 不在前台时自动唤起，在 AI 对话页时填充当前对话，否则新建对话并填充；无需输入框焦点；“自动发送”默认开启，关闭时仅填充

AI 键仅作用于 DeepSeek Harness，沿用当前鼠标的识别语言与标点配置。识别结果追加到已有草稿末尾；“自动发送”开启时提交完整草稿及附件，关闭时保留供手动发送。开关按设备保存，录音使用按下时的设置；录音期间切换页面或对话，完成后仍回到本次目标对话并填充。唤起、创建或填充失败时，浮层保留结果供复制。宿主和插件须已运行，完全退出后不可用。

使用语音搜索时，在设置中选择百度、Bing 或 Google。使用一键链接时，先填写网址并点击“确认”；https:// 或 http:// 可省略，保存和打开时保留原地址。搜索和打开链接无需先选中对话输入框。

多台鼠标可同时连接、分别设置，但同一时间只能进行一次语音操作。

常见问题

接收器已插入但没有设备

先确认鼠标已开机、切到 2.4G 模式并已唤醒。如果正在运行 ClawMouse 等鼠标管理软件，请完全退出后再试，它们可能占用连接。普通光标能够移动，并不代表语音功能已经连接成功。

Mac 上请留意“声云设备”中的占用提示。若显示“已检测到 2.4G 接收器，正在等待鼠标响应”，请再次检查鼠标的电源和连接模式。

语音或翻译失败

先确认鼠标身份已识别、网络可用，翻译源语言和目标语言不同。鉴权失效会自动重试一次，仍失败时弹出提示；翻译失败可复制识别原文。

设置或按键没有生效

• DPI 提示应用失败时，重新选择后重试。
• Mac 上的回车、后退等系统按键动作可能需要为 Harness 授予辅助功能权限。
• 如果提示原语言选项已不再支持，请重新选择语言。

如何更新或卸载

更新时，完全退出 Harness，用安装命令安装新版本的 .tgz 文件，再重新启动。

卸载时，完全退出 Harness 后执行：

dsh plugin --profile desktop remove @sonicloud/dsh-sonicloud-device

Mac 如果找不到 dsh，使用安装步骤中的完整命令路径。

联系方式

如需商务合作、技术支持或购买鼠标硬件，欢迎通过以下方式联系我们：

• 邮箱：xu_heng_yu@sinicloud.com
• 微信：扫描下方二维码联系。

参与贡献

想修改插件或贡献代码，请阅读本地开发与代码贡献指南，了解环境准备、调试、测试和提交流程。

版本变更见更新日志。

许可

项目代码使用 MIT 许可。随包原生 SDK 和第三方库保留各自许可，见 组件声明。