前言¶
如果你在 DSH 里做过智能体落地，大概率会遇到同一个需求：模型在面板里聊得很好，能不能接到 QQ 上，让用户直接发消息？常见的做法是自己拉一个 NapCat 或 go-cqhttp 客户端，装登录态，再写一套收发消息的服务——这一步的安装和部署成本往往比写业务逻辑还高。
下面介绍的插件 luchengfj/qq-bot（面板插件名 @local/qq-bot）就是针对这个痛点的。它属于 DeepSeek Harness 生态里「一切皆插件」思路下的一个通道插件，由 luchengfj 维护，目的是把 Harness 变成一个 QQ 机器人通道：接收文字、图片消息，调用模型生成回答，再把回答发回去。它的设计取向与上面那类方案有明显区别——插件本身纯 Node 实现、零 npm 依赖、不下载、不安装、不启动任何 QQ 客户端，也不再自动下载 NapCat；要对接真实 QQ，它复用你已经装好并正在运行的 OneBot v11 实现端。
这是什么¶
一句话定位：一个 DSH 面板插件，提供 QQ 机器人收发消息的通道，默认在面板里即可直接聊天验证，连真实 QQ 是可选能力。
仓库为 https://github.com/luchengfj/qq-bot，协议 MIT，package.json 中声明 version 为 1.0.0，engines.dsh 要求 >=0.1.7-rc.1。当前仓库星标为 0，说明还没有形成规模化的用户反馈，功能以 README 为准。
插件基于 OneBot v11 协议，适配 NapCatQQ、Lagrange.Core、LLOneBot、go-cqhttp 等已经装好的实现端。
核心功能¶
下面按 README 列出的已核实能力逐条说明。
1. 面板直聊测试（默认路径，零下载）
侧边栏「QQ 机器人」面板的「① 直聊测试」区块，不装任何东西就能发文字或图片，走完整的 BotLogic 管线：收图 → 记忆 / 上下文 → 模型作答 → 分段回复。也就是说，不接入任何 QQ 端，也可以立刻验证插件的完整链路是通的。
2. 默认跟随 Harness 模型，免密钥
默认 llm.mode='harness'，跟随 Harness 里当前选中的模型，不需要任何 API 密钥。图片消息走附件服务。也可以切到 external，走 OpenAI 兼容的 /chat/completions 端点，此时才需要 apiKey。external 端点可换成 OpenAI、DeepSeek、本地 Ollama / vLLM 等任何兼容服务。
3. 本机 OneBot 端口自动探测 + 自动连接
插件启动时自动扫描本机常见端口（默认 3001, 3000, 5700, 8080, 6099, 3333），对每个端口尝试 / 与 /onebot 路径，发送 OneBot get_version 探测（收到 meta_event / lifecycle 推送也算命中），发现可用服务就自动连上。默认每 20 秒重扫一次。插件自身的 6700 端口始终被排除在探测之外。手工填的地址永远不会被覆盖——自动探测只在尚未配置 / 连接正向 WS 地址时启用。
4. 与已有 OneBot 实现对接的四种方式
除了自动探测，其余三种手工方式：
- 正向 WebSocket（插件主动连出）：填一个已运行的 OneBot v11 正向 WS 地址，或写进
cordis.patch.yml的forward:块。 - 反向 WebSocket（实现端连回插件）：把任意 OneBot 实现的反向 WS 客户端地址指向
ws://127.0.0.1:6700/onebot。 - HTTP POST 上报：同一路径
/onebot也接受 OneBot 的 HTTP POST 上报，可用secret做 HMAC-SHA1 签名；这种单向连接发回复需要配合httpApiBase指向 OneBot 的 HTTP API，优先推荐前两种方式。
5. 长期记忆与对话上下文
机器人自动记住用户陈述的关键事实（例如「我叫小明」「我住在杭州」），私聊与群聊完全隔离，同主题覆盖不堆积；超过 memory.ttlDays（默认 30 天）没说话自动遗忘。对话上下文是另一套机制：保留最近若干轮真实问答并注入模型，静默超过 historyTtlMinutes 自动清空，/new 可立即清空且不影响长期记忆。
6. 内置指令与回复清洗
聊天里可用 /help、/status、/new、/memory、/forget，均有中文别名（/帮助、/状态、/换话题、/我的记忆、/忘记我），指令只在消息开头生效。模型返回后插件做本地清洗（lib/reply.js，不额外调用模型）：去开场白、折叠空行；超过 llm.maxReplyChars（默认 600）时按段落 → 句子 → 空格拆成多条并标注 (1/4)，而不是直接截断。
安装与启用¶
README 给出的安装方式是挂目录，没有写 dsh plugin add 这类命令，照原文执行即可：
- 把插件目录挂到 Harness 的插件目录；
- 或者用
cordis.patch.yml的insert行指向本目录：
insert:
- { id: qq-bot, name: '@local/qq-bot' }
然后在 DSH「插件」里启用 @local/qq-bot。
需要注意的加载规则：改过配置或代码后必须禁用 → 再启用才会重新加载，本地链接安装的插件不会自动热更新文件。
典型用法¶
先做零下载验证，再做真实 QQ 接入。
第一步：面板直聊
1. 启用 @local/qq-bot
2. 打开侧边栏「QQ 机器人」面板
3. 在「① 直聊测试」输入框发一句话（或贴一张图）
这一步不需要 QQ 客户端、不需要 token、不需要 API key，默认走 Harness 原生模型。/help、/status 等指令在面板直聊里同样可用。
第二步：连真实 QQ
README 明确写了前提：QQ 官方没有「免客户端」的 HTTP 机器人 API，所以要真实收发 QQ 消息，仍然需要一个已经装好并正在运行的 OneBot v11 实现端，插件只是不再替你下载它。最省事的做法是什么都不配，让自动探测去找；也可以手工配置。修改配置的入口是 cordis.patch.yml：
host: 0.0.0.0
port: 6700
path: /onebot
插件默认监听 0.0.0.0:6700，路径 /onebot。只在本机使用的话，把 host 改成 127.0.0.1。
第三步：跑一次自检
面板的「③ 运行自检」逐项检查 6 项：OneBot 监听、模型后端、反向 WS 连接、正向 WS 连接、面板直聊可用、记忆功能，并附模型连通性测试、统计清零、实时日志。自检通过后再通过面板的 send 接口发测试消息，可以减少盲调时间。
面板与接口概览¶
面板每几秒自动刷新，按 5 个分组区块组织（响应式两栏，窄屏自动单栏）：
| 区块 | 内容 |
|---|---|
| ① 直聊测试 | 不装任何东西验证收图、答题、记忆与分段回复；清空当前会话（chat-clear） |
| ② 连接真实 QQ（可选） | 自动探测卡片（「立即扫描」、开关、候选列表），正向 WS 地址配置 / 断开，反向 WS 接入地址，测试消息发送 |
| ③ 运行自检 | 6 项检查、模型连通性测试、统计清零、实时日志 |
| ④ 记忆与上下文 | 查看 / 删除记忆，换话题清上下文，立即写盘，查看最近对话 |
| ⑤ 配置与日志 | 当前配置（只读）、完整日志环、日志清空 |
面板共注册 19 个 /api/qq-bot/* 路由，全部经 ctx.webServer 注册，只允许本机同源访问：sec-fetch-site: cross-site、Origin 与 Host 不一致、非 loopback 的 Host 或远端地址都会被拒绝（403）。也就是说这个面板默认是本机调试界面，不要指望把它暴露到公网当运维后台。面板里的配置默认是只读的，正向 WS 例外，可在面板改并写盘到 ~/.dsh/qq-bot-forward.json；其余配置一律编辑 cordis.patch.yml 后禁用 → 启用。
配置要点¶
完整配置项以仓库里的 cordis.patch.yml 为准，这里只列容易踩坑的几项：
llm:
mode: harness # harness: 跟随 Harness 当前模型，免密钥（默认）
# external: OpenAI 兼容端点，需 apiKey
temperature: 0.4
maxReplyChars: 600
maxReplyParts: 4
allowPrivateImages: false # 默认拒绝下载内网 / 本机图片，防 SSRF
memory:
enabled: true
maxFacts: 60
ttlDays: 30
file: # 留空 = 仅内存，重启即失效；填路径才写盘
detect:
enabled: true
ports: [3001, 3000, 5700, 8080, 6099, 3333]
intervalMs: 20000
excludePorts: [] # 插件自身端口 6700 始终自动排除
trigger:
privateAlways: true # 私聊是否全部响应
groupRequiresAt: true # 群消息是否需 @机器人 或前缀
prefix: ""
allow:
groups: [] # 白名单，空 = 不限制
users: []
denyUsers: []
几个值得注意的默认值：llm.allowPrivateImages 默认 false，内网或本机图片地址默认不会去下载；trigger.groupRequiresAt 默认 true，群消息要 @ 机器人或带命令前缀才会触发；单图下载上限为 maxImageBytes: 8388608（8MB）。
适用场景与注意¶
适合谁：
- 已经装了 NapCatQQ、Lagrange.Core、LLOneBot、go-cqhttp 等 OneBot v11 实现端，想少写胶水代码就把 QQ 接到 Harness 模型上的人；
- 想先在面板里把链路验证通，再决定要不要接真实 QQ 的人；
- 希望默认不配任何 API key、直接复用 Harness 当前模型的人。
注意事项：
- 插件以当前 dsh 进程的权限运行，安装前应检查源码与许可证（MIT），不要在没有读完代码的情况下把它暴露到非本机网络。
- QQ 官方没有免客户端的机器人 API，所谓「零下载」指的是插件不下载任何东西，真实 QQ 收发仍然依赖一个已存在的 OneBot v11 端。
- 插件是纯 Node 实现、零 npm 依赖，但
engines.dsh要求>=0.1.7-rc.1；该信息来自package.json，实际兼容性以安装环境为准。 - 改配置或改代码后记得禁用 → 再启用，否则不会生效。
- 本仓库星标为 0，社区验证有限，遇到问题建议直接读 README 与源码，或向维护者 luchengfj 反馈。
结尾¶
这个插件的价值在于把「QQ 机器人接入」拆成了一条零下载的默认路径和一条可选的真实接入路径：前者让联调可以立刻开始，后者不替你承担安装 QQ 端的成本。如果你已经有一个跑着的 OneBot v11 实现端，并且想让它在 Harness 里直接对话、带记忆、带图片，可以从自动探测那条路试起。
目录页：https://www.skillhub.cn/plugins/luchengfj/qq-bot
GitHub：https://github.com/luchengfj/qq-bot
