前言¶
在 DeepSeek Harness（DSH）里做「住在群里」的助手，常见路线有两类：走 QQ 官方 Bot API 的机器人身份，或走 OneBot 协议端挂个人号。前者合规路径清晰，但不接个人号、群能力也受平台接口约束；后者能覆盖群聊运营、长期记忆、审批与后台运维，却要自己扛协议端稳定性与账号风控。
下面介绍社区插件 dsh-channel-qq（维护者 Aegink，分类：客户端）。它以 cordis Service 形式挂进 dsh，默认通过 OneBot v11 与协议端通信（README 写明协议端默认用 SnowLuma，NapCat 仍可作回滚方案），把群聊 / 私聊消息纳入同一套 agent 流水线，并附带工具面、长期记忆、主动行为与管理后台。
这是什么¶
dsh-channel-qq 是 DSH 的 QQ 渠道插件：收发消息走 OneBot v11，在宿主内提供工具调用、记忆检索、事件驱动的主动行为，以及本地管理后台。项目为 MIT 许可，非官方，与腾讯 / QQ 无隶属关系；协议端属于非官方实现，账号风控、掉线、要求重新验证 README 均标明为常态。
与生态内其它 QQ 接入的分工（摘自 README 对比表）：
| 方案 | 接入 | 适合 |
|---|---|---|
| 官方 dsh-qqbot | QQ Bot API v2 | 官方机器人身份、扫码、流式回复；不接个人号 |
| dsh-im | 多 IM 渠道 | 一个插件同时接多种平台，广而薄 |
| dsh-channel-qq | OneBot v11（SnowLuma） | 个人 QQ 号 + 完整群能力：长期记忆、知识库、主动行为、审批、技能包、群运营 |
选型上：要官方身份与流式用官方插件；要一次接多平台用 dsh-im；要个人号长期在群里运营，用本项目。
核心功能¶
以下能力均来自仓库 README，按模块归纳。
消息与群聊策略¶
- 群聊 / 私聊、图片、语音、文件、引用回复、戳一戳；支持自动分句发送。
- 群聊准入：进 agent 前先判断「要不要说话」；非 @ 消息不进队列，减少上下文与模型调用。
- 可选交互提示（默认关）：私聊显示「正在输入」，群里对触发消息贴表情回应。
- 可选合并转发（默认关）：长清单 / 日志 / 总结可发聊天记录卡片，失败回退逐条。
工具面¶
- 约 90 个细粒度工具；在
tools.v2下合并为 17 个动作组（如qq_message、qq_lookup等）。
长期记忆¶
- 流程：日记 → 结构化记录 → 检索；夜间九个任务（分块 / 抽取 / 反思 / 遗忘 / 摘要 / 向量重建）。
- 每回合自动注入 3–8 条证据（≤600 字）；
qq_memory_search可深召回原文块（带文件行号）。 - 可选向量检索：本机 embed 服务（
deploy/embed-server/），未开启则退回关键词。
主动行为与技能¶
- 主动行为：事件书驱动巡逻、早报、主动私聊；时间表以数据配置，而非硬编码。
- 技能：磁盘上的 Agent Skills 目录包（
SKILL.md），按房间定可见范围（全部 / 仅私聊 / 指定群 / 指定房间 / 仅管理员）；模型自动发现，也可用/名字触发；后台可增删改、从 URL 或粘贴导入（先落待审区）。
管理后台与安全¶
- 管理后台：27 个页面，配置热生效、审计、会话重建、模型供应商管理。默认只监听
127.0.0.1，README 要求通过 SSH 隧道访问；口令从环境变量读取（详见 SECURITY.md）。 - 发送侧探针：
/api/healthz通过一次get_status往返判断消息能否发出，不产生消息，仅接受本机请求。 - 曲库账号：后台「音乐」页扫码登录网易云 / 酷狗，可自检登录态与搜歌。
- 审批网关：高危命令 L0–L3 分级 + 一次性令牌；管理员在 QQ 私聊回复「批准」即可执行（
待批 / 申请 / 批准 / 拒绝，不经模型）。
访问门控（默认开）¶
陌生人私聊、未批准群的消息默认只回「待主人批准」，不进 agent；后台「安全」页批准后放行。也可切换白名单或全放行（open 不建议公网使用）。
群策略 access.groupPolicy 支持 member（已在群即放行，推荐）、pairing（默认，未批准群需申请）、allowlist。管理员可在私聊使用 待批访问、放行 <QQ>、放行群 <群号>、拒绝访问 等命令（README 有完整表）。
其它可选能力（多数默认关）¶
原话簿（chatlog）、人物档（qq_person_note）、渠道健康告警、回合指标等；开关关闭时 README 要求行为与旧版逐字节一致。
安装与启用¶
环境要求：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/configuration.md。
已抓取资料中未给出 dsh plugin add 一类的一行安装命令；以 README 的构建 + cordis.patch.yml 挂载为准。
典型用法与文档入口¶
- 协议端：按 SnowLuma（或回滚 NapCat）文档启动 OneBot v11，WebSocket 地址与
accessToken与上面connection一致。 - 首次私聊 / 新群：在默认
pairing模式下，到管理后台「安全」页或管理员私聊命令放行。 - 群内对话：注意
requireMention与按群覆盖；非 @ 不会进 agent 队列。 - 记忆与向量：需要语义检索时部署
deploy/embed-server/并按 docs/memory.md 配置。 - 运维自检：本机请求
/api/healthz确认发送链路；音乐、审批、主动行为分别在后台对应页面配置。
架构与消息旅程见 docs/architecture.md。
适用场景与注意¶
适合：已有 DSH 宿主，希望用个人 QQ 号在群 / 私聊里跑完整 agent（工具、记忆、主动消息、审批、技能包、群运营），并愿意维护 OneBot 协议端。
不适合：必须 QQ 官方 Bot 身份或官方流式 API——应选 dsh-qqbot；只想多平台薄接入——应选 dsh-im。
安全与合规：
- 插件以当前 dsh 进程权限运行；安装前请阅读源码与 MIT 许可，并遵守 QQ 用户协议与当地法律。
- 管理后台是远程控制面，勿在公网裸露；访问门控勿随意设为
open。 - 非官方协议端带来的账号风险由部署者自行承担。
结尾¶
dsh-channel-qq 把 OneBot v11 上的 QQ 消息接到 DSH，并在单插件内叠了工具面、长期记忆、主动行为、审批与 27 页管理后台，定位是「个人号 + 群运营」而非官方 Bot 或多平台薄接入。
- 社区目录页：https://www.skillhub.cn/plugins/Aegink/dsh-channel-qq
- 源码与 README：https://github.com/Aegink/dsh-channel-qq
DSH 生态强调「一切皆插件」；SkillHub 等社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。本文事实均来自上述仓库 README 与已抓取资料，版本以仓库当前 package.json（如 0.1.0）为准。
