QQ 渠道 Aegink/dsh-channel-qq

dsh-channel-qq

把 QQ 接入 DeepSeek Harness 的渠道插件。
通过 OneBot v11 收发消息（协议端默认用 SnowLuma， NapCat 仍可作回滚方案），以 cordis Service 形式挂进 dsh，提供工具面、长期记忆、主动行为与管理后台。

来源与致谢｜Origin & Credits

本项目源自 DandanLLab/dsh-channel-qq 的早期版本：OneBot v11 传输（含半开连接看门狗与双栈绑定）、表情包库、好感度面板、音乐点歌与主动行为调度这些地基，都是从那个仓库长出来的。
感谢原作者的开源工作。 本仓库在其基础上继续演进（分层重构、长期记忆与知识库、审批网关、技能包、管理后台等），如与上游有出入，以本仓库的实现与文档为准。

非官方项目，与腾讯 / QQ 无隶属关系。协议端属于非官方实现，账号风控、掉线、要求重新验证都是常态——请自行遵守 QQ 用户协议与当地法律。

特性

- 消息：群聊 / 私聊、图片、语音、文件、引用回复、戳一戳，自动分句发送
- 工具面：90 个细粒度工具；tools.v2 下合并为 18 个动作组（qq_message、qq_lookup…）
- 群聊准入：进 agent 之前先判"要不要说话"；非 @ 消息不进队列，省上下文与模型调用
- 长期记忆：日记 → 结构化记录 → 检索；夜间九个任务（分块 / 抽取 / 反思 / 遗忘 / 摘要 / 向量重建）
- 每回合自动注入 3–8 条证据（≤600 字）；qq_memory_search 深召回原文块（带文件行号）
- 可选向量检索：本机 embed 服务（deploy/embed-server/），不开就退回关键词
- 主动行为：事件书驱动巡逻、早报、主动私聊——时间表是数据，不是代码
- 技能：磁盘上的 Agent Skills 目录包（SKILL.md），按房间定可见范围（全部 / 仅私聊 / 指定群 / 指定房间 / 仅管理员），模型自动发现 + /名字 直接触发；后台可增删改、从 URL 或粘贴导入（先落待审区）
- 管理后台：27 个页面，配置热生效、审计、会话重建、模型供应商管理
- 发送侧探针：/api/healthz 用一次 get_status 往返判断"消息发不发得出去"，不产生消息、只接受本机请求
- 曲库账号：后台「音乐」页扫码登录网易云 / 酷狗（二维码在浏览器本地生成），可看登录态、清除登录、先搜一首歌自检，不必等群里点歌才发现没登录
- 审批网关：高危命令 L0–L3 分级 + 一次性令牌；管理员在 QQ 私聊回一句「批准」即可执行（待批 / 申请 / 批准 / 拒绝，全程不经模型）
- 交互提示（可选，默认关）：私聊回合显示「正在输入」，群里给触发消息贴一个表情回应
- 合并转发（可选，默认关）：长清单/日志/总结改发一张聊天记录卡片，失败自动回退逐条
- 指标（可选，默认关）：回合耗时 p50/p90、token 四个桶、发送/工具失败，后台按房间与天看
- 原话簿（可选，默认关）：按群按日保存原始消息流水（<工作区>/chatlog，默认保留 14 天）， qq_group_digest 可按日期翻某群聊了什么
- 人物档（可选，默认关）：qq_person_note 手动记录「谁爱用什么说法、忌讳什么」，按群分开存，与自动侧写互补
- 渠道健康告警（可选，默认关）：消息链路失联超过阈值私聊管理员，恢复后再报，同场故障限频
- 访问门控（默认开）：陌生人私聊 / 未批准的群只回一句「待主人批准」，不进 agent；后台「安全」页批准后才放行（也可切白名单或全放行）

与其它 QQ 接入方案的分工

dsh 生态里已经有几种 QQ 接入，定位不同：

| 方案 | 接入 | 适合 |
| 官方 dsh-qqbot | QQ Bot API v2 | 官方机器人身份、扫码、流式回复；不接个人号 |
| dsh-im | 13 个 IM 渠道 | 一个插件同时接多种平台，广而薄 |
| 本项目 | OneBot v11（SnowLuma） | 个人 QQ 号 + 完整群能力：长期记忆、知识库、主动行为、审批、技能包、群运营 |

选型建议：要官方身份与流式，用官方插件；要一次接多个平台，用 dsh-im；要一个「住在群里」的长期陪伴/群运营机器人，用本项目。

快速开始

需要 Node.js 22+、一个 dsh 宿主、一个 OneBot v11 协议端。

npm install
npm run build # 生成后台前端 + 编译 TypeScript
npm run verify # 类型 + 测试 + 分层 + 体积，全绿再继续

挂载（<dshHome>/profiles/<profile>/cordis.patch.yml）：

- id: channel-qq
config:
connection: { mode: forward, url: ws://127.0.0.1:3001 }
accessToken: <OneBot access token>
selfId: <机器人 QQ 号>
admins: [<管理员 QQ 号>]
primaryGroup: <主群号> workspacePath: /path/to/agent-workspace

部署与运维细节见 docs/deployment.md。

文档

| 文档 | 内容 |
| docs/architecture.md | 分层、消息旅程、关键决定、往哪里加东西 |
| docs/configuration.md | 配置三层覆盖、生效方式、环境变量 |
| docs/deployment.md | 部署、发布、回滚、故障排查 |
| docs/memory.md | 记忆系统：夜间任务、embed 服务、评测与限制 |
| docs/memory-standalone.md | 记忆库插件化：脱离 cordis 独立使用 |
| SECURITY.md | 威胁模型与部署清单 |
| CONTRIBUTING.md | 门禁、硬规则、提交信息 |

开发

npm run verify # 门禁
npm run eval # 行为评测（红队 7 + 场景 15 + 人格 30 + 转录 8 + 记忆基准）
npm run audit # 静态审计
npm run probe:admin # 后台浏览器回归（headless Chrome）

- test/golden/ 是逐字节快照：改动输出必须先解释差异，不能静默更新。
- 每个改变行为的升级都必须带独立开关、默认关——关着时与旧版逐字节一致。

目录

src/
core/ 纯逻辑（可重放） app/ 入站流水线、组包、回合 features/ 子插件（工具、记忆、主动行为、后台、审批…）
adapters/ 宿主与外部世界 config/ 配置 schema 与页面清单 assets/persona/ 人格与提示词（纯文本） deploy/ 发布、备份、审批执行器 eval/ 行为评测 scripts/ 构建与门禁

安全

管理后台是远程控制面：默认只监听 127.0.0.1，请通过 SSH 隧道访问；口令只从环境变量读取。详见 SECURITY.md。

访问门控：默认 access.mode = pairing——陌生 QQ 的私聊、以及尚未批准的群里的消息，只会收到一句「待主人批准」，不会进入智能体；主人在后台「安全」页批准后放行。
管理员始终允许。需要预先授权时可把模式改成 allowlist，用 access.allowUsers / access.allowGroups 指定名单；open 是旧的全放行行为，不建议在公网使用。

管理员也可以直接私聊机器人处理，不必开后台：

| 私聊命令 | 作用 |
| 待批访问 / 访问请求 | 列出待批的人/群，并给出可复制的放行命令 |
| 放行 999 | 批准某个 QQ 的私聊 |
| 放行群 107 | 批准某个群 |
| 拒绝访问 999 / 拒绝访问群 107 | 拒绝 |

这些命令只认管理员私聊，且在高危命令审批网关之前处理（动词刻意用「放行」，不与网关的「批准/拒绝」冲突）。

群策略 access.groupPolicy：

| 值 | 行为 |
| member（推荐） | 机器人已经在的群直接放行——加群本身就是主人操作，不用逐群批准 |
| pairing（默认） | 未批准的群先申请，和私聊一样待主人批准 |
| allowlist | 群只认 allowGroups 与后台已批准列表 |

私聊始终按 mode 走配对/白名单。群消息仍然受 groupEnabled、requireMention 与「群聊与房间」里的按群覆盖约束——那两处管的是“怎么回”，访问门控管的是“能不能触发”。

未批准的群默认完全安静：只有真正 @ 或命中关键词的消息才会生成一条请求并私聊通知主人，群里不回「待主人批准」（access.replyPendingInGroups 可打开，且每个请求只回一次）。
没人叫机器人的闲聊不会触发配对，也不会刷屏。

许可

MIT