QQ 聊天机器人 wufa-cat/dsh-qq-bot

dsh-qq-bot

-8b5cf6)

非官方移植：本项目是 QQ-bot 的 DeepSeek Harness 插件版。
原项目作者 ezoiLZH —— 人设协议、表情包机制、消息聚合、SKIP/LEAVE 冷却、群内指令等设计全部来自原项目，特此致谢。
本项目经原作者许可发布；按原作者要求，任何转载或二次分发请保留本段署名与上方原项目链接。
如果原作者希望调整署名或撤下本项目，开个 issue 即可，我会立刻处理。

仓库：https://github.com/wufa-cat/dsh-qq-bot · 下载：https://github.com/wufa-cat/dsh-qq-bot/releases

把 QQ 变成 DeepSeek Harness 的聊天入口：OneBot v11（NapCat）收消息，Harness 的模型回消息。
macOS 与 Windows 都能开箱即用——装好插件，在界面里点几下就能跑起来，不需要命令行、不需要 clone 任何仓库。

- 每个 (机器人, 群/私聊) 一个持久智能体会话，人设走系统提示词
- 消息聚合、冷却限频、[SKIP] / [LEAVE] 行为
- 人格（persona/.md）在插件界面里直接编辑
- 表情包按「机器人/分类」管理，界面里上传、删除、直接测试发送
- NapCat（Docker）服务的启动/停止/重启、扫码登录、环境自检、目录打开全在界面里
- 工具白名单：聊天会话默认一个工具都不给；要联网才开 web_search（P0，防止群友间接拿到命令能力）
- 对话巡检：状态灯 + 最近事件 + 跳过原因 + 聊天记录尾巴，排障不用翻日志
- 关键词规则：命中直接回，不进模型
- 定时消息：每天/指定星期往群里发固定内容
- 长期记忆：直接在界面里编辑 data/memory-<chat>.json
- 图片多模态、B 站/分享链接解析、群内指令（/ping、/表情、/reload …）

一、准备：装 Docker

机器人通过 NapCat 连接 QQ，NapCat 跑在 Docker 里。

Windows

1. 安装 Docker Desktop for Windows（自带 docker compose）。
2. 启动 Docker Desktop，等托盘图标变成绿色（引擎就绪）。
3. 不需要在 WSL 里手动装任何东西。

macOS

任选一种：

- Docker Desktop：装好并启动即可；
- colima（更轻）：

brew install colima docker docker-compose
colima start --arch aarch64 --vm-type vz --cpu 2 --memory 4

插件会在点「启动服务」时自动 colima start（已装但没运行时）。

Linux 也能跑（用系统 Docker），只是没做专门适配。

二、安装插件

需要已安装 DeepSeek Harness（桌面版或 Web 版）。

直接从 GitHub Release 装（推荐）
dsh plugin --profile desktop add https://github.com/wufa-cat/dsh-qq-bot/releases/download/v1.3.2/dsh-qq-bot-1.3.2.tgz
或者用本地下发的 tarball / 目录
dsh plugin --profile desktop add ./dsh-qq-bot-1.3.2.tgz
或者直接用目录
dsh plugin --profile desktop add /path/to/dsh-plugin
发布到 npm 之后也可以
dsh plugin --profile desktop add dsh-qq-bot

--profile desktop 是桌面版专用配置档；Web 版改成 --profile web。
目录软链安装（add /path/to/dsh-plugin）不会安装插件的依赖，v1.2.2 起已自动回退到 Node 内置 WebSocket，不需要额外处理。

安装完完全退出并重启 Harness（Cmd+Q / 托盘退出），让 Host 侧代码生效。

三、界面里配置（三步）

打开 设置 → QQ 机器人（也可以在插件页找到 QQ 机器人那一行）。

1. 初始化目录

点服务卡片里的 「初始化目录」。它会创建（已存在的绝不覆盖）：

~/dsh-qq-bot/ ← 默认工作目录（Windows: %USERPROFILE%\dsh-qq-bot） ├── persona/人设参考模板.md ├── stickers/ ├── data/ └── onebot/napcat-docker/ ├── docker-compose.yml ← 已配好端口与 WebUI 令牌 ├── README.md └── data/{qq,config,plugins}

想换位置：把「工作目录」填成别的绝对路径，再点一次「初始化目录」。

2. 启动服务并扫码登录

- 点 「环境自检」 先确认 Docker / compose / 目录都是 ✔；
- 点 「启动服务」，插件会 docker compose up -d，并自动打开 NapCat WebUI；
- WebUI 里用机器人 QQ 扫码登录（首次约 2 分钟出码，过期就点「重启」重新生成）。

3. 添加机器人

在「机器人」卡片点 添加机器人，填：

| 字段 | 说明 | 例子 |
| QQ 号 | 机器人自己的 QQ | 3177752843 |
| 名字 | 日志与表情包目录用 | 千早爱音 |
| 人设 | persona/ 里的文件名（不带 .md） | Anonther |
| 管理员 | 能用 /reload、/clear 的 QQ 号，逗号分隔 | 3635811460 |
| WS 地址 | 默认指向本机 NapCat | ws://127.0.0.1:3001 |
| WS Token | NapCat 没设就留空 | |

保存后插件会重载并连接。日志里看到 qq-bot: 🤖 [名字] ... 就说明通了。

四、人格

「人格」卡片：列出 persona/.md，点名字在页面里编辑，保存后群里发 /reload（管理员）让机器人换用新人设。
也可以新建（带模板）、删除、重命名。人设内容会作为系统提示词注入每个会话。

五、表情包

目录结构（机器人名字必须与配置里的「名字」一致）：

stickers/
└── 千早爱音/ ├── 开心/开心.jpg ├── 喜欢/喜欢.png └── 震惊/震惊-这啥啊.jpg

- 分类名 = 目录名；目录里的图片文件名随意，支持 png/jpg/jpeg/gif/bmp/webp；
- 模型在回复里写 [动画表情:分类名]，插件随机挑一张发出去（整条回复只有这个标记时就是单发一张表情）；
- 插件把「可用分类」自动写进提示词，不需要在人设里手写清单；
- 界面里可 上传图片到分类、新建分类、展开删除；
- 发送用 base64:// 而不是本地路径——NapCat 在容器里看不到宿主机路径，用路径会静默失败；
- 回复长度限制（chat.maxReplyLength，默认 800）作用在展开表情之前，不会把 base64 截断；
- 手动测试：群里 @机器人 /表情 列分类，@机器人 /表情 开心 直接发一张。

旧布局兼容：stickers/<分类>/图片 也能识别（当 stickers/<机器人名字>/ 不存在时）。根目录直接放图片不会被发送——那些只会显示在卡片的「根目录图片」里。

六、工具白名单与联网搜索（P0）

群里任何人说话都可能触发模型，所以聊天档默认不给任何工具——不能跑命令、不能写文件、不能开子代理。
要什么给什么，白名单写在每个机器人的 tools 里：

| 开关 | 工具 | 说明 |
| webSearch | web_search | 联网搜索，默认 关 |
| webFetch | web_fetch | 抓取网页正文，默认 关（打开搜索后才有意义） |

1.4.0 起：插件自己注册 web_search（宿主全局层）

DSH 桌面版把工具搬进了「agent 预设」，而插件用 agents.create() 建的聊天 agent 不经过预设流程——实测那个 agent 里只有 working_directory，web_search 根本不存在，所以以前「配了搜索也没用」、模型只能自己编 <invoke> 语法。

现在插件在宿主全局层注册一个 web_search（lib/webtool.js），检索仍走后端 ctx.web（凭据/provider 还是 profile 里那套），聊天 agent 自动继承；关掉 tools.webSearch 时用 per-agent restrict 遮掉。另用 tools.guard() 拒绝 bash/write/edit/subagent 这类危险工具执行。

状态接口 web.tool 会告诉你注册结果： json
"web": { "available": true, "tool": { "ok": true, "reason": "已注册" } }

实现是 agentCtx.tools.restrict({ allow })（必须用 agentCtx.tools，用 ctx.get('tools') 会抛 "requires a scoped context"）。

工具名从 tools.view(scope).restrictableNames 读（读不到再退回 schemas() / 逐个 get）。读不到工具表时不会用 allow: [] 一刀切——那会把 web_search 一起屏蔽，模型就只能自己编 <invoke> 语法发到群里；这时改成 deny 掉危险工具（bash/write/edit/subagent…），保证联网还能用。

改完后在群里发 /搜索 看状态，/qqbot-status 里每个机器人有： json
"tools": { "webSearch": true, "webFetch": false }, // 配置/指令层面
"toolsAvailable": { "webSearch": true, "webFetch": false } // agent 里真的拿到的

toolsAvailable.webSearch 为 true 才算联网真的可用；为 false 说明 Harness 没把工具给聊天 agent（缺 @deepseek-ai/dsh-tool-web 或 web 服务）。

界面：插件页 → 机器人卡片 → 「工具权限」。也有运行时开关：

- /搜索 on|off（管理员）：下一轮重建会话时生效，/搜索 不带参数看当前状态；
- 「运行状态」卡片里的 开 / 关 / 跟随配置 按钮。

搜索凭据不是这个插件管的

搜索后端是 Harness 内置的 DeepSeek 官方搜索（deepseek-official）：
- 用 DeepSeek 账号登录 Harness → 自动可用；
- 或环境变量 DEEPSEEK_API_KEY；
- 或「设置 → 插件 → 官方 → 网页搜索」里填 Key。

⚠️ 聊天模型如果走别的服务商（例如 SiliconFlow），搜索仍需要单独的 DeepSeek 凭据，否则报 401。插件界面的状态卡会直接给出这条提示。
💰 Messages 模式搜索 = 一次完整模型调用（60s 超时、最多 5 次），开之前先想清楚值不值。

七、谁可以调用功能（权限）

每个功能单独设置，不再是一个总开关。三个功能：

| 功能 | 管的动作 |
| sticker | /收图（写表情包目录） |
| search | /搜索（切换联网） |
| manage | /ai、/clear、/reload |
yaml
access:
mode: admin # 默认范围：all 全员 | admin 仅管理员 | list 仅白名单
users: [] # 默认白名单 QQ
groups: [] # 默认白名单群号（群里任何人都算）
denyUsers: [] # 默认黑名单，永远优先
denyGroups: []
features: # 每个功能可以覆盖默认值；mode: inherit = 跟随默认
sticker:{ mode: admin }
search: { mode: inherit }
manage: { mode: admin, denyUsers: ["10002"] }

- 判定顺序：黑名单（默认+该功能）→ 管理员 → 该功能 mode（inherit 时用默认 mode）；
- 名单和黑名单的条目：QQ 号，或 群:群号（群里任何人都算）；
- 管理员始终可用，除非被黑名单点名；

界面里就是一张表：每个功能一行，选范围、填名单（一行一个，也吃逗号）、黑名单折叠在下面。

八、对话巡检与状态灯

插件页顶部「运行状态」：

- 绿/红状态灯：是否连上 OneBot、重连次数、最近错误、已运行时长；
- 计数：收到消息 / 发出回复 / 跳过 / 错误；
- 搜索与 AI 的当前状态（只读；运行时开关用群指令 /搜索、/ai）。

「对话巡检」卡片：

- 最近 60 条事件：谁、在哪个聊天、说了什么、bot 回没回、为什么跳过（冷却 / 没被 @ / AI 关 / 聚合中）；
- 下拉选一个 data/<chat>.json 直接看最近 20 条聊天记录。

事件只存在内存环形缓冲（400 条），重启清空；聊天记录本体仍在 data/。

九、关键词规则

命中关键词直接回复，不进模型：快、省钱、不受上下文影响。
yaml
rules:
- enabled: true
pattern: 在吗 mode: contains # contains | exact | regex reply: 在的 {user}
bots: [千早爱音] # 留空 = 所有机器人

- reply 支持 {user}（昵称）、{qq}、{bot}；
- 规则优先于模型，但指令优先于规则（/ping 不会被规则抢走）。

十、定时消息 yaml schedules:
- enabled: true
label: 早安 at: "08:00"
days: [1, 2, 3, 4, 5] # 1=周一 … 7=周日；留空 = 每天
bot: 千早爱音 chat: group:123456789 # 或 private:10001 text: 早上好呀～ {weekday}

- 每 20 秒检查一次，同一天同一分钟只发一次；
- {date} {time} {weekday} 会替换；
- 机器人不在线就跳过并记日志（不会补发）。

十一、长期记忆

「长期记忆」卡片直接编辑 data/memory-<chat>.json：一行一条，保存时自动补日期。
新会话建立（种子）时会把这些摘要注入提示词；也可以整份删除。

十二、群内指令

| 指令 | 说明 |
| /help | 指令列表 |
| /ping | 延迟测试 |
| /time | 服务器时间 |
| /表情 [分类] | 列出表情分类 / 直接发一张 |
| /echo 文本 | 复读 |
| /roll | 掷骰子 |
| /calc 1+23 | 计算 |
| /clear [N] | 清除对话记忆 |
| /ai on\|off\|status | 开关 AI 回复（受 access.features.manage 限制） |
| /收图 [分类] | 把图片收进表情包（受 access.features.sticker 限制） |
| /搜索 [on\|off\|跟随] | 联网搜索开关（受 access.features.search 限制） |
| /reload | 重读人设与表情包（管理员） |

十三、目录与清理

「目录与清理」卡片：

- 一键打开 仓库目录 / 人格 / 表情包 / 聊天数据 / OneBot 目录；
- 清理未使用镜像：docker system prune -af（在用的容器不受影响）；
- 删除虚拟机：仅 macOS + colima 可用，回收约 3.5 GB，下次启动会重建并重新拉镜像； Windows 上引擎在 WSL2 里，插件不会动它（要彻底重置用 Docker Desktop → Troubleshoot → Reset）。

十四、配置项（cordis.patch.yml）

界面保存的就是这些；一般不用手写。所有字段都有默认值，最小配置只需要 bots： yaml
- id: qq-bot
name: dsh-qq-bot
config:
repoDir: "" # 留空 = ~/dsh-qq-bot（首次启动自动创建） autoStart: true bots:
- qq: "3177752843"
name: 千早爱音 persona: Anonther
admins: ["3635811460"]
yaml
ws: { url: "ws://127.0.0.1:3001", accessToken: "" }

provider: guijiliudong # 可选：缺省用 DSH 默认模型

model: deepseek-ai/DeepSeek-V4.1-Flash

timeout: 180
tools: { webSearch: false, webFetch: false } # 聊天档工具白名单
access: # 每个功能单独设；features 里的 mode=inherit 跟随默认 mode: admin
users: []
groups: []
denyUsers: []
denyGroups: []
features:
sticker: { mode: inherit }
search: { mode: inherit }
manage: { mode: inherit }
rules: [] # 关键词规则
schedules: [] # 定时消息
service:
onebotDir: "" # 留空 = <repoDir>/onebot/napcat-docker webuiPort: 6099 wsPort: 3001 chat: maxReplyLength: 800 # 作用在展开表情之前 replyCooldown: 5 leaveCooldown: 300 logMaxEntries: 300
blacklistGroups: []
aggregation:
windowTimeout: 8
maxMessages: 8
rateLimit:
tier1Count: 3 # 1 分钟 ≥4 条 → 冷却 ×1.5 tier2Count: 10 # 5 分钟 ≥11 条 → 冷却 ×2 capCount: 15 # 10 分钟 ≥16 条 → 停止回复

provider/model 缺省时使用 DSH 全局默认模型；指定时使用该 provider（须已在 DSH 设置里配好）。

十五、界面背后的接口

界面按钮打到 Harness 自带 web 服务器的两个前缀（不额外开端口）：

- /qqbot-service/：status、doctor（环境自检）、init（初始化目录）、action（start/stop/restart）
- /qqbot-files/：list、persona/{load,save,create,delete,rename}、sticker/{upload,category,delete}、memory/{list,read,save,delete}、chats、chat/tail、open、clean
- /qqbot-status：状态灯数据（连接/计数/工具策略/搜索可用性）
- /qqbot-inspect：巡检事件
- /qqbot-runtime/{search,ai}：运行时开关（不改配置文件，重载后回到配置值）
- /qqbot-runtime/models：POST {baseURL, apiKey|apiKeyEnv} → 上游模型 id 列表（界面「拉取模型」）

十六、运行日志

qq-bot: 仓库目录 /Users/you/dsh-qq-bot，数据目录 /Users/you/dsh-qq-bot/data qq-bot: 初始化工作区，创建 12 项 qq-bot: 正在连接 ws://127.0.0.1:3001 ... qq-bot: ✅ 已连接 qq-bot: 启动监测 [千早爱音] [chat=group-42] qq-bot: 🤖 [千早爱音] 上下文 5行, 2图 qq-bot: 📤 [千早爱音] 分段回复 (2段)

十七、开发 bash
node --check lib/.js # 语法检查
npm run check # 同上（含 client.js）
npm pack # 打 tarball 给别人装

| 文件 | 作用 |
| lib/index.js | 插件入口、Config schema、装配 worker |
| lib/onebot.js | OneBot v11 WS 客户端 |
| lib/hub.js | 消息分发、指令、聚合 |
| lib/bot.js | 单个机器人运行时（触发判断、限频、发送） |
| lib/brain.js | 与 Harness agent 的桥接、会话压缩 |
| lib/chatlog.js | data/.json 聊天日志（与原版兼容） |
| lib/cq.js | CQ 码解析、表情包、@、分段 |
| lib/files.js | 人格/表情包/目录管理路由 |
| lib/service.js | Docker/NapCat 启停与自检 |
| lib/scaffold.js | 工作区初始化（目录 + compose 模板） |
| lib/platform.js | 平台差异（打开目录、compose 探测、虚拟机信息） |
| lib/client.js | 界面（设置分区 + 插件页配置入口） |

十八、已知行为差异（相对原 Python 版）

1. 命令必须空格分隔：@bot /ping 生效，@bot/ping 不生效。
2. data/.json 里图片以 liveImages（base64）内联保存，不再落 data/images/。
3. compact 后的记忆总结不再自动生成；已有 memory-<chat>.json 会继续注入种子文本。
4. 一个 (bot, 聊天) 的会话在插件进程存活期间复用；DSH 重启后首轮用聊天日志窗口整体重建。

十九、排障：插件「消失」与 404

| 现象 | 原因 | 处理 |
| 设置侧栏没有「QQ 机器人」、插件页也无此项 | Host 侧 apply()/import 失败（最常见：软链安装缺依赖） | 看启动日志的 failed to import；v1.2.2 起软链安装已自动回退内置 WebSocket |
| 界面卡片在，接口 404（/qqbot-status 等） | 页面刷新只换前端，Host 还是旧进程 | 完全退出并重启 Harness，不是刷新页面 |
| 状态灯红、lastError 有内容 | NapCat 没起来 / 端口不对 / token 不对 | 用「服务」卡片启动，或 docker logs napcat |
| 搜索报 401 | 聊天模型不是 DeepSeek 账号模型，搜索仍需 DeepSeek 凭据 | 「设置 → 插件 → 官方 → 网页搜索」填 Key |
| 群里出现 <invoke> / <parameter> 之类的文本 | 搜索开着但智能体没拿到 web_search，模型自己编了调用语法 | 1.3.2 起会自动过滤并丢弃纯语法回复；看 /qqbot-status 的 toolsAvailable.webSearch 排查 |

致谢

| 项目 | 说明 |
| ezoiLZH/QQ-bot | 原项目（Python + Claude Code CLI）。本插件的人设系统、表情包协议、消息聚合、冷却与指令都移植自它 |
| NapCatQQ | 本插件默认使用的 OneBot v11 实现（Docker 镜像 mlikiowa/napcat-docker） |
| LLOneBot | 另一种 OneBot v11 实现，同样可用 |
| DeepSeek Harness | 宿主：智能体会话、模型路由、系统提示词、插件槽位 |

出处引用：本项目基于 QQ-bot（作者 ezoiLZH）改写，经原作者许可发布；转载、二次分发请保留本段署名与链接。

原项目没有附带开源许可证，所以本移植版不对原项目的代码与设计主张任何权利；新增的插件封装、界面与跨平台适配代码以 MIT 发布（见 LICENSE 与 NOTICE）。

MIT License.