前言¶

在 DeepSeek Harness（DSH）里接 QQ，常见做法是自行拼 NapCat、OneBot、Koishi 和模型网关：路径、端口、反向 WebSocket、权限与 AI 触发分散在多处配置里，启停和排查成本高。社区插件 dsh-qqbot（维护者 prophetcrab）把 DSH 端定位为「控制中心」：由 DSH 负责安装/启停、配置控制面、AI 网关、人设/画像与 Web 面板；NapCat 与 Koishi 作为外部运行时仍由插件管理，但不承担 DSH 侧的权限策略与模型编排。当前实现 仅支持 macOS / Apple Silicon，与 Linux 或 Windows 上的自建方案不在同一支持范围内。

这是什么¶

dsh-qqbot 是 DSH 的 客户端类插件（package.json 中 dsh.client.platform 为 web，并注入侧边栏与设置 UI）。一句话链路如下：

QQ ↔ NapCat ↔ OneBot 11 ↔ Koishi ↔ DSH Host ↔ 面板 / LLM

插件版本 0.5.1，许可证 MIT，依赖 DSH >=0.2.1-rc.2 <0.3.0，Node ^22.19.0 || >=24.0.0。GitHub 仓库 prophetcrab/dsh-qqbot 当前分支为 dshbot-mac；社区目录页见 SkillHub 条目（独立站点，与 DeepSeek / 幻方无官方从属关系）。

三端分工¶

理解插件前先对齐职责边界（摘自 README 表格）：

NapCat 只从内置离线包安装（vendor/napcat/payload/NapCat.Shell-4.18.42.zip），校验 size 与 SHA-256，不联网下载。Koishi 使用模板项目 ~/project/qq-bot，版本 4.18.11，默认端口 5140，反向 WS 路径 /onebot。

核心功能¶

下面介绍 README 中可核对的能力，不展开未在资料中出现的「一键」细节以外的承诺。

Host 与 Client 插件化¶

Host 侧每个能力是一个 host plugin，统一贡献 registerRoute、registerTool、registerFeature、registerStatusProvider、registerClientTab、provide(service)；关闭某个插件时，其路由、工具、Feature 与 Tab 一并消失。Client 侧每个 Tab 是独立 Client 插件，源码在 client/，构建产物为 client.js（npm run build:client），避免单文件巨石。

面板侧 Client 插件目录包括：overview、ai、messages、access、plugins、features、logs——对应总览、AI、消息、权限、插件、特性与日志等 Tab。

NapCat 与 Koishi 管理¶

NapCat 侧要点：

• QQ.app：/Applications/QQ.app
• WebUI：127.0.0.1:6099
• 反向 WS：ws://127.0.0.1:5140/onebot

可配置字段（空值表示走默认推导）：napcatPort、napcatToken、qqPath、napcatDir、offlineVendorDir、offlineNapcatVersion。

Koishi 侧可配置：projectDir（默认 ~/project/qq-bot）、koishiPort、reversePath、napcatToken、autoRestartKoishi、autoInstallDeps、autoSyncSelfId、logLines。

AI、人设、权限与消息¶

• DSH 写 配置 / 人设 / 画像；Koishi 模板插件（如 access-control、ai/*）执行 权限、触发与发送。
• Koishi 侧 AI 子模块包括 gateway.ts（DSH HTTP 契约）、trigger.ts（概率/@/回复/跟进）、context.ts（背景/图片）等，插件间通过 ctx.qqbot.* 服务通信。
• 运行时数据落在 ~/project/qq-bot/data/：config/（access.json、ai-settings.json、persona.json）、state/（含 koishi.db、napcat-login-qr.png 等）、assets/、logs/。

旧版平铺的 data/*.json 可用迁移脚本一次性迁入（迁移前需停止 Koishi）：

node scripts/migrate-data.mjs ~/project/qq-bot --database

安全与架构约束¶

• NapCat token 不落日志、不返回明文；外部命令使用 argv 数组，不拼 shell。
• 离线包校验失败即拒绝安装；权限策略由 Koishi access-control 执行。
• 仓库内 npm run check 覆盖测试、client 构建、host/client 冒烟、架构与离线包校验等（README 称 host 冒烟约 41 routes / 6 tools / 5 features）。

安装与启用¶

资料中的安装入口是项目内脚本，不是 dsh plugin add github:... 形式的目录命令。使用前需已将插件源码放到本地路径（README 示例为 ~/project/dsh-qqbot），并在该目录执行：

cd ~/project/dsh-qqbot
node scripts/install-profile.mjs --profile desktop --install

首次加载会依次：

1. 从 template/ 创建 ~/project/qq-bot
2. 解压内置 Koishi darwin-arm64 依赖（template/runtime-bundles/node_modules-darwin-arm64.tar.gz）
3. 从 vendor/napcat 离线安装 NapCat
4. 写入 OneBot 反向 WS 配置
5. 启动后扫码登录 QQ

安装前请自行阅读仓库源码与 MIT 许可证；插件以当前 DSH 进程权限运行，会写本地项目目录与 QQ/NapCat 相关路径，仅在可信环境中启用。

典型用法与开发校验¶

日常运维围绕 DSH 面板与各 Tab 完成启停、消息查看、权限与 AI 设置；具体按钮与 API 以 Host 注册的路由为准。若你参与插件开发或二次打包，README 给出的校验命令如下：

npm test                 # 198 tests
npm run build:client
npm run smoke:host
npm run smoke:client
npm run check:architecture
npm run offline:verify
npm run check            # 全部

Client 源码与生成物需保持同步：

npm run build:client
node scripts/build-client.mjs --check

更细的模块与重构说明见仓库 docs/archive/refactor-v2/ 与 docs/decisions/ 下的设计文档（如人格/记忆、群消息监听闭环等）。

适用场景与注意¶

适合：已在 macOS（Apple Silicon）上使用 DSH，希望用统一面板管理 NapCat + Koishi + AI 网关与人设/画像的 QQ 机器人方案，并接受离线内置 NapCat/Koishi 依赖的维护方式。

不适合或需注意：

• 非 macOS 环境：README 明确当前分支只支持 macOS / Apple Silicon。
• 需要自行从 GitHub 拉取或审查代码后再安装；不要使用资料未给出的安装命令。
• NapCat 涉及 QQ 协议与第三方实现，合规与账号风险需自行评估；权限策略虽在 Koishi 执行，策略内容仍由你在面板与配置中定义。

结尾¶

dsh-qqbot 把 QQ 机器人链路上 DSH 该管的一层（安装启停、控制面、AI 网关、人设/画像、Web 客户端）收拢为插件化 Host/Client，并与 NapCat、Koishi 的职责划分写死在架构里，便于在 DSH「一切皆插件」的生态中按需开关能力。

• 社区目录：https://www.skillhub.cn/plugins/prophetcrab/dsh-qqbot
• 源码与 README：https://github.com/prophetcrab/dsh-qqbot