前言¶
在 DeepSeek Harness（DSH）里做智能体，常见做法是浏览器或桌面会话里对话。若你希望同一套 Harness 在手机上用 QQ 私聊也能收发——文字、图片、表情、语音，并且回复只回到发起那一侧（QQ 来的回 QQ，桌面来的留在桌面），就需要一条从 QQ 生态到 DSH 的桥，而不是再搭一套 IM 机器人框架或消息队列。
dsh-qq 由维护者 wyinthe 发布，在 SkillHub 社区目录中归类为客户端插件。它只做桥接：通过 NapCat 的 OneBot11 WebSocket 把私聊进出接到指定 DSH 会话。本文介绍其定位、能力与安装用法；事实以仓库 README 与 package.json 为准。
这是什么¶
一句话：它是桥，不是机器人。
数据路径可以理解为：
QQ 客户端 ──> NapCat(WSL) ──OneBot11 WS──> dsh-qq ──> DSH 会话
│
回话按来源分流 ◀───┘
（QQ 发起的才回 QQ；桌面发起的留在桌面）
仓库为纯 ESM、零依赖的单文件实现（index.js），当前版本 0.2.1，许可证 MIT，要求 Node.js >= 20，对 DSH 的 peer 依赖为 @deepseek-ai/dsh >= 0.2.0。维护者自述在单机单人自用场景下已验证文字、图片、表情、语音（收）通路；发语音条尚未实现。
DSH 生态理念是「一切皆插件」；SkillHub 目录页 与 GitHub 仓库为社区资源，与 DeepSeek / 幻方无官方从属关系，不宜当作官方应用商店条目理解。
核心功能¶
下面按「有什么 / 没有什么」说明，避免预期错位。
私聊与接入
- 支持 OneBot11 / NapCat 下的私聊双向文字。
- 一个号只接白名单内用户的私聊：
owners不填则谁都不接。 - 会话绑定：可接到指定会话，或首次使用时自建。
- 回话跟着来源走：仅 QQ 发起的那一轮才回 QQ，避免桌面说一句、手机跟着震。
媒体与标记
| 方向 | 能力 |
|---|---|
| 收图 | 落盘后把路径交给 AI，由模型侧 read_image 打开；插件不做识别 |
| 收表情 / 商城表情包 | 记成文本标记 |
| 发图 / 发表情 / 发表情包 | 通过输出标记（见下文「典型用法」） |
| 收语音 | 需自备转写脚本（earScript），DSH 侧看到转写与语气维度文本 |
| 发语音条 | 未做；文档指向 ffmpeg + silk-wasm 外挂方案 |
明确不做（README 表格）
- 群聊投递：
groupMessages默认关闭，仅记日志。 - 自带 ASR、表情图库、记忆与上下文压缩管理。
设计上的第三条原则：能力靠标记不靠魔法——要发图就写 [[img:路径]]，不猜测用户意图。
安装与启用¶
安装前请自行阅读 GitHub 源码 与许可证；插件在当前 dsh 进程权限下运行，白名单与 NapCat token 等配置涉及账号安全，不宜在未审代码的情况下直接用于生产账号。
1、准备 NapCat
在 NapCat 中开启 WebSocket 服务端（细节见仓库 docs/配置.md），记下端口与 token。
2、安装插件
官方 README 给出的命令为（使用 Git 仓库直装，--profile web）：
dsh plugin --profile web add https://github.com/wyinthe/dsh-qq
3、配置四类信息
地址、token、白名单（owners）、工作目录等，可参考带注释样例 examples/cordis.patch.yml，并配合 cordis.patch.yml 挂载声明使用。
4、重启 DSH 并验证
重启后，在 QQ 上向该号发一句私聊；预期为 QQ 侧收到回复，且桌面会话不会重复收到同一条回流。
典型用法¶
QQ 进来的内容在 DSH 里长什么样¶
| 你发 | DSH 看到 |
|---|---|
| 文字 | 原文 |
| 语音 | [语音] 转写文本 + [语气] 等（需配 earScript） |
| 图片 | [用户发了图片，已存到本机，可以直接用 read_image 打开：<路径>] |
| 表情 | [QQ表情 id=178] |
| 表情包 | [表情包「名字」emoji_id=… package_id=…] |
AI 输出如何发到 QQ¶
| 写入内容 | 发出结果 |
|---|---|
[[img:D:/pics/a.png]] |
图片（自动转 base64://，适配 NapCat 在 WSL 下无法直接读 Windows 盘符的情况） |
[[face:178]] |
QQ 表情 |
[[mface:emoji_id/package_id/名字]] |
商城表情包 |
| 纯文字 | 文字（超过 maxChars 自动切段） |
收发标记、行为细节与已知限制见仓库 docs/用法.md；连接、白名单、语音转写约定见 docs/配置.md；按症状排查见 docs/排错.md。
适用场景与注意¶
适合谁
- 已在用 DSH，且愿意自建 NapCat（常见 WSL 部署）与 OneBot11 WS 的开发者。
- 需要单人私聊、来源分流，并愿意用显式标记控制发图发情的场景。
- 接受语音转写、发语音条需自行扩展（脚本或 ffmpeg 方案），而非插件内置。
使用注意
- 默认不接群聊；多人群、多账号需在上层扩展，README 写明当前优先私聊是因为可独立跑通。
- 图片理解依赖模型与
read_image，不是插件内置能力。 - 社区目录显示该仓库 GitHub 1 stars（截至目录收录信息）；版本与能力以 CHANGELOG 与 README「状态」一节为准。
结尾¶
dsh-qq 把 QQ 私聊通过 NapCat / OneBot11 接到 DeepSeek Harness：白名单、会话绑定、按来源回流，并用 [[img:]] / [[face:]] 等标记约束出站能力。若你要在 DSH 上接 QQ 而非另起一套机器人框架，可从 README 的 60 秒步骤与 examples/cordis.patch.yml 动手验证。
