安装
$npx -p @deepseek-ai/dsh dsh plugin --profile web add github:DLive/dsh-qqbot-community
QQ 官方机器人适配器 (dsh-qqbot-community)
为 DeepSeek Harness 提供 QQ 官方机器人的接入能力。本项目由 openclaw-qqbot 插件功能迁移而来。
整体功能未严格测试，部分功能可能不稳定，欢迎反馈问题，或者直接提交 PR。
安装
npm install dsh-qqbot-community
该包以 npm 形式分发，供宿主消费。如需从源码构建/调试，参见下文「接入指南」。
致谢与来源
本插件的核心接入、网关与会话管理逻辑源自 openclaw-qqbot 项目，遵循原项目的 MIT 许可证。在此向原作者与贡献者致谢。
功能特性
基础
- 消息收发：频道
@机器人、群聊 @机器人 和单聊消息。
- 会话管理：按频道、群或单聊用户创建或恢复独立的 Agent 会话（cwd 对齐持久化 header，工作区分组，归档自动恢复）。
- Agent preset 挂载：每个 QQ 会话在 setup 阶段自动
agentPresets.mount() 加入预设（默认 standard，用 agentPreset 配置可换成 code / minimal / cordis 或任意用户自定义 id），恢复持久会话时沿用 header 中记录的 preset —— 因此 QQ 里的 agent 与 Web UI 拥有同一套工具（bash / 文件 / 代码运行等）和提示词，仅追加 qq_send_media / qq_api 等 QQ 专属工具。
- 沙箱支持：开启后使用 QQ 官方沙箱 OpenAPI 接入点。
- 网关可靠性：WebSocket 心跳、断线重连退避、会话 RESUME（session_id + seq 持久化，重启不重放事件）。
- @mention 清洗：`` →
@昵称，机器人自身提及剔除（群/频道消息友好）。
- 引用消息上下文：记录每条消息到持久化引用索引（LRU + JSONL，
~/.dsh/storages/qq-refindex.jsonl）；用户回复某条消息时自动解析（ref index 优先，msg_elements 兜底）并以 [引用消息开始]…[引用消息结束] 前缀注入模型上下文。
- 图片理解：入站图片经 DSH attachment 服务持久化为
ImageBlock（模型直接可见）；服务不可用或格式不支持（如 bmp）时回退下载到 /.qq-media/ 并注入路径。
- 语音转写（STT）：优先使用 QQ 自带 ASR（
asr_refer_text）；配置 stt（OpenAI 兼容接口）时下载语音转写；均不可用时注入占位描述。
- 附件落盘：视频/文件等非图片附件下载到
/.qq-media/，路径注入文本，供 agent 文件工具读取。
- 富媒体发送：AI 可通过
qq_send_media 工具发送图片/语音/视频/文件（URL / data URL / 本地路径）；>10MB 本地文件自动走分片上传（upload_prepare → presigned PUT 并行 → part_finish → complete）。
session/event 的 assistant/chunk → QQ stream_messages 替换模式（全量帧、msg_seq 固定、index 递增、节流）；前缀不一致自动合并；失败降级静态消息。出站合并与分段：同一轮多条文本回复按窗口合并（默认 900ms/6s 上限）；超长回复按段落边界分段（默认 4000 字/段）；剥离 / 等内部标签。被动回复限额：每条入站消息被动回复（带 msg_id）默认上限 4 次、群 5 分钟/C2C 30 分钟窗口，超限自动降级主动消息（ RouteStore 持久化，重启后提醒类主动推送仍可路由）。typing 指示：C2C 处理期间 60s 输入中状态自动续发（50s 间隔）。访问控制：allowFrom（C2C openid）/ groupAllowFrom（群 openid）白名单，'*' 通配，留空放行。审批桥（inline keyboard）：为每个 QQ 会话注册 agent 作用域 approval/request answerer —— 审批请求以三按钮消息送达 QQ（✅ 允许一次 / ⭐ 始终允许 / ❌ 拒绝），按钮回调即决策；"始终允许"按 会话×工具 持久化（qq-always-allow.json）。QQ API 代理工具：qq_api 工具代理任意 QQ 开放平台 REST 调用（频道/群管理、公告、日程等），自动注入鉴权。斜杠命令：/help /ping /me /new /approve ask|never|status /always clear（在投递给 agent 之前拦截，映射 DSH 审批策略；完整列表见下节）。定时提醒：复用 DSH schedule 子系统（web profile 自带 schedule_create 等工具）；提醒到期触发同会话 follow-up，回复经出站管线（含主动降级）送达 QQ。明确不迁移（平台强绑定或 DSH 已覆盖）
Webhook transport、热升级（/bot-upgrade/update-checker）、/bot-logs//bot-version//bot-clear-storage（DSH Web UI 承担）、pairing 配对流、credential-backup、claw_cfg 私有协议、群自主模式（需 QQ 特批 GROUP_MESSAGE_CREATE）、群历史缓冲注入（DSH 会话日志已持久化完整上下文）。
斜杠命令
在投递给 agent 之前由本插件直接拦截并响应（slashCommands: false 时整组关闭）。所有命令都以行首 / 触发，参数以空白分隔。
| 命令 | 参数 | 说明 |
|---|
/help | — | 在 QQ 内列出全部可用斜杠命令。 |
/ping | — | 立即返回 ✅ pong（HH:MM:SS），用于延迟/可达性自检。 |
/me | — | 返回当前会话发送者的 openid（可选附带昵称），便于排查白名单。 |
/new | — | 强制关闭当前 thread 上的流式回复（stream_messages DONE 帧）并取消进行中的 agent，再为同一会话目标分配下一个 thread id（#n1、#n2 …）；旧 session 保留，仍可在侧边栏切换。 |
/approve | ask | never | status（缺省 status） | ask/never 切换当前会话的审批策略（仅当 approval: true 且当前环境提供了 approval 服务时生效）；status 列出本会话已"始终允许"的工具名。 |
/always | clear | 清空本会话的"始终允许"清单；其它子命令视为未识别并回落到 agent。 |
未识别的命令（例如 /foo）会被原样转发给 agent，不会被插件吞掉。
接入指南
本包以 DSH bundle 形式分发 —— package.json 声明 dsh.bundle.patch，仓库根的 cordis.patch.yml 是该 bundle 的默认配置层。用户通过 dsh plugin add 一行安装，DSH 自动把它加入 ~/.dsh/profiles//package.json 的 dsh.profile.bundles 列表，并在下次启动时作为独立一层叠加。
1. 安装到 profile
# 从 npm 安装（正式用户）
dsh plugin --profile web add dsh-qqbot-community
# 从 GitHub / 本地 checkout 安装（开发/调试）
dsh plugin --profile web add github:DLive/dsh-qqbot-community
dsh plugin --profile web add /path/to/dsh-qqbot-community
# 安装后核对：bundle 已被识别为独立一层
dsh --profile web --dump-config | grep -A2 "dsh-qqbot-community"
2. 在 profile 的 cordis.patch.yml 覆盖默认配置
DSH 的层顺序是：每个 bundle 的 patch → profile 的 cordis.patch.yml → home 级 cordis.patch.yml → --patch 覆盖层。后者覆盖前者，所以用户在自己 profile 的 patch 文件里补 QQ 凭证即可，不需要改 bundle。
编辑 ~/.dsh/profiles/web/cordis.patch.yml，在已有内容末尾追加（不要覆盖文件里已有的其它 patch）：
⚠️ patch 必须是替换形式（- id: ...），不能是 insert 形式（- insert: [...]）。
本 bundle 自身的 cordis.patch.yml 已经声明了 id: qqbot-community 的 row。用户层再写一个 - insert: [{ id: qqbot-community, ... }] 会让合并后的 entry 列表里出现两个同 id 的 row，DSH 会拒绝加载：
Error: duplicate loader entry id: qqbot-community
正确写法是按 id 替换 row 的 config——DSH 的 patch 算法会用你写的 config 覆盖 bundle 提供的默认值；同一 id 的 row 在最终树里只剩一个。
- id: qqbot-community
name: dsh-qqbot-community
config:
id: '你的 AppID' # 必须加引号（避免 YAML 数字解析）
secret: '你的 AppSecret'
sandbox: true
provider: 'DeepSeek' # 新建会话默认提供商
model: 'DeepSeek-V4-Flash' # 新建会话默认模型
agentPreset: 'standard' # preset id：standard / code / minimal / cordis / 自定义；缺省值 standard
cwd: '/Users/xxxx/workdir' # QQ 会话 agent 工作区目录（须真实存在）
# 以下均可省略，以下为默认值
allowFrom: ['*'] # C2C 白名单；填 openid 数组限定用户
groupAllowFrom: ['*'] # 群白名单
markdown: false # msg_type 2，需开通 markdown 权限
typing: true # C2C 输入中指示
streaming: true # C2C 流式回复
streamThrottleMs: 1200 # 流式帧节流
deliverWindowMs: 900 # 轮内回复合并窗口
deliverMaxWaitMs: 6000 # 合并最大等待
textChunkLimit: 4000 # 单条静态回复上限
replyPassiveLimit: 4 # 每条消息被动回复上限
mediaDownload: true # 非图片附件落盘 /.qq-media/
approval: true # QQ 内联键盘审批
approvalTimeoutMs: 300000 # 审批等待超时
slashCommands: true # /help /ping /me /new /approve /always
# stt: # 可选：语音转写（OpenAI 兼容）
# baseUrl: 'https://api.openai.com/v1'
# apiKey: 'sk-...'
# model: 'whisper-1'
如果你只想临时调试本仓库代码、不走 npm，也可以在不修改 profile 的前提下用 --patch 直接喂这份 patch 给 dsh：
cd /path/to/dsh-qqbot-community
pnpm install && pnpm run build
dsh web --patch ./cordis.patch.yml
这条路径绕开 dsh plugin 的依赖管理，仅适合本地开发。
3. 启动
启动后自动：获取 token → 建立 WS 网关（RESUME 恢复）→ 收到消息按会话创建/恢复 agent → 回复经出站管线送回 QQ。
注意事项
- 权限：默认 intents 同时订阅频道 @、群 @、单聊与按钮交互（INTERACTION）。审批按钮需要开通「消息按钮」能力。
- markdown：
markdown: true 需在 QQ 开放平台申请 markdown 模板权限，否则发送失败。
- 审批链路：QQ answerer 仅在会话审批策略为
ask 时收到请求（never 直接拒绝）；/approve never 关闭审批后所有 ask 确定性拒绝 —— 与 DSH 审批语义一致。
- 流式与 markdown：
stream_messages 帧固定 content_type: markdown，与 markdown 配置独立（QQ 流式接口本身就是 markdown 渲染）。
- 工作目录：
cwd 必须是已存在的绝对路径（workspaceRegistry.create 会 fs.realpath 校验）；已恢复会话保留原 cwd。
- 运行时产物：
~/.dsh/storages/qq-{routes,gateway-session,always-allow}.json、qq-refindex.jsonl、/.qq-media/；删除后自动重建。
故障排查
- 收不到消息：
debug: true 查看网关 op 帧；确认 intents 与 QQ 平台消息权限审核状态。
- 回复没到：查看被动限额日志 —— 超限自动转主动消息，QQ 对主动消息有频控。
- 图片模型看不到：确认 DSH 挂载 attachment 服务（web profile 默认有）；不支持格式自动回退为路径注入。
- 审批按钮无响应：确认开通按钮权限；
/approve status 查看始终允许清单；超时默认 5 分钟自动拒绝。
Error: duplicate loader entry id: qqbot-community：合并后的 entry 树里出现了两个同 id 的 row。常见原因有两个：(1) 用户 cordis.patch.yml 里写了 - insert: [{ id: qqbot-community, ... }]（应该改成 - id: qqbot-community, config: {...} 替换形式）；(2) 旧 file:// 形式的 row 没清掉。执行 dsh --profile web --dump-config | grep "id: qqbot-community" 应该只看到一行；多于一行就重复了。- QQ 里只有基础对话、bash 等工具全无：说明 QQ 会话没有挂上 agent preset —— DSH 会打印
agent "qq:..." was published without joining an agent preset。本插件默认会调 agentPresets.mount('standard')，但要求 host 上有 dsh-agent-presets row（web / cli profile 自带，自定义 profile 需手动加载）。要换 preset 时在 patch 里设置 agentPreset: 'code'（或自定义 id）；已有会话恢复时沿用 header 里记录的 preset，重启 dsh 或 /new 会用新值。