前言¶
DeepSeek Harness（命令是 dsh）把自己的架构概括成一句话：一切皆插件。模型、工具、会话、沙箱，甚至 Agent 循环本身，都可以替换。官方仓库目前仍处于 developer preview，兼容性破坏变更是预期内的事。开箱后常见入口是 Web UI 和 headless 一次性任务；如果你希望同一套 Agent 出现在 QQ 里——私聊能接着聊、群里被 @ 才开口——就需要一条 IM 通道，而不是改 Agent 循环。
dsh-qqbot 做的就是这件事。仓库由 tencent-connect 维护，定位是把 QQ 消息平台当成 dsh Agent 的前端协议驱动：QQ 进来的消息进入 ctx.agents，模型回复再以 Markdown 发回 QQ。社区插件目录把它归在「工具与能力」，收录日期是 2026-08-15。需要说明：这个目录是独立站点，和 DeepSeek / 幻方没有官方从属关系，不能当成官方应用商店。仓库自己写的「官方插件」，指的是腾讯 QQ Bot 侧接入 dsh 的插件，不是目录站点的官方背书。
本文按插件目录页、GitHub 仓库 README、package.json 以及 DeepSeek Harness 官方仓库核对后整理：它是什么、装到哪个 profile、扫码之后怎么聊。
这是什么¶
dsh-qqbot 的 npm 包名是 @tencent-connect/dsh-qqbot，当前 package.json 版本为 0.4.0，主要语言是 TypeScript，许可证 MIT（Copyright 2026 Tencent Connect）。GitHub 仓库 tencent-connect/dsh-qqbot 创建于 2026-08-14；写作时（2026-08-17）GitHub API 显示 53 星，社区目录页当时展示为 26 星，星标以 GitHub 一手数据为准。
它解决的问题很具体：让已经初始化好的 dsh 环境，通过 QQ Bot 收发消息。README 里的数据流可以看成：
QQ 用户 → QQ WebSocket → dsh-im-qqbot → ctx.agents → dsh agent loop → LLM
↑ │
└── session/event ──────────┘
(assistant reply → QQ sendMarkdown)
也就是说，QQ 不是另写一套机器人逻辑，而是给现有 dsh Agent 加一条 IM 前端。插件声明自己是纯 Cordis 插件，遵循 dsh 的 “Plugins, not loop changes”：依赖写成 inject = ['agents']，不直接耦合其他插件。
核心功能¶
私聊、群聊各走独立会话¶
每个 QQ 私聊用户、每个群各对应一个独立 Agent。会话键是 qqbot:${appId}:${scope}:${peerId}，SessionId 由 SHA-256 确定性派生，进程重启后可以按同一套规则恢复。解析顺序是：进程内复用 → 持久化恢复 → 全新创建。闲置超时默认 30 分钟（sessionIdleTimeout，1800000 ms），超时后自动 dispose Agent，避免会话一直占着内存。
群聊默认要 @ 才回复¶
requireMention 默认是 true：群里没有 @ 机器人，插件不会把普通闲聊送进 Agent。私聊和群聊还可以分别加 directPrompt、groupPrompt，用来补一段额外的 system prompt。源码里的配置 Schema 还提供了访问控制：私聊 / 群聊可设为 open、allowlist 或 disabled，并支持 openid 白名单。README 配置表没有列出这一项，需要精细权限时以仓库源码为准。
回复走 Markdown，并按 QQ 长度切开¶
出站不是纯文本直出，而是 sendMarkdown。单条消息默认最多 4500 字符（textChunkLimit），源码注释写明 QQ 限制大约 5000 字符。切分会感知代码块和表格，避免把 Markdown 结构从中间截断。
聊天里可以管会话和模型¶
README 列出的斜杠命令如下：
| 命令 | 说明 |
|---|---|
/bot-reset |
重置当前会话（清除上下文） |
/bot-model |
查看或切换模型 |
/bot-status |
查看当前会话状态 |
/bot-help |
查看所有指令 |
源码里还可以看到 /bot-new（新开会话）、/bot-clear（与 reset 同类）、/bot-ping、/bot-version 等注册项；对外说明以 README 这四条为准。默认 LLM 提供商是 deepseek-official，默认模型是 deepseek-chat，也可以改 provider、model，或通过 preset 挂上 agent-presets 里的预设（工具集、prompt 等）。
安装与启用¶
开始前，先按 DeepSeek Harness 官方指引完成 dsh 初始化和模型配置。官方仓库当前的开发者预览启动方式是：
npx @deepseek-ai/dsh web
社区目录页给出的安装命令是：
dsh plugin add github:tencent-connect/dsh-qqbot
如需可复现安装，目录页建议固定 commit 哈希：
dsh plugin add github:tencent-connect/dsh-qqbot#<commit>
把 <commit> 换成仓库里实际的提交哈希。插件以当前 dsh 进程的权限运行，安装时可能执行代码；装之前应检查源代码仓库和许可证。
仓库 README 推荐的日常用法是单独建一个 qqbot profile，并安装 npm 包（当前版本 0.4.0）。README 提示：建议升级到 0.4.0 以上再扫码，支持点击链接在浏览器打开，避免部分终端二维码渲染错位。
# 安装到 profile
npx @deepseek-ai/dsh plugin --profile qqbot add @tencent-connect/dsh-qqbot
# 启动
npx @deepseek-ai/dsh --profile qqbot
首次启动时，如果凭据还没配，插件会进入扫码引导：终端输出二维码 → 手机 QQ 扫码绑定 → 凭据写入该 profile。之后再启动不必重复扫码。
本地改源码、或不走扫码、直接用环境变量时，README 给的是路径安装：
cd /path/to/dsh-qqbot
pnpm install && pnpm build
npx @deepseek-ai/dsh plugin --profile qqbot add /path/to/dsh-qqbot
export QQBOT_APPID="你的AppID" QQBOT_SECRET="你的AppSecret"
npx @deepseek-ai/dsh --profile qqbot
开发调试还可以用 --patch：
export QQBOT_APPID="你的AppID" QQBOT_SECRET="你的AppSecret"
npx @deepseek-ai/dsh web --patch /path/to/dsh-qqbot/cordis.dev.yml
appId、appSecret 是必填项，也可以只走环境变量 QQBOT_APPID、QQBOT_SECRET。不要把密钥写进公开仓库。
从 GitHub 源码安装时，dsh 官方文档还提醒过：git 依赖拉取的是源码而不是构建产物，pnpm ≥10 可能要求在 profile 的 pnpm-workspace.yaml 里为该包打开 allowBuilds 后再执行一次 add。若第一次 add 失败，按终端提示处理，不要跳过授权检查。
典型用法¶
绑定完成后，直接在 QQ 里给机器人发消息即可。下面几步都可以按仓库说明复现。
1. 私聊里跑通一轮对话¶
启动 qqbot profile 并完成扫码后，向机器人发一句普通问题。消息会经 WebSocket 进入插件，再调用 agent.followup()。回复以 Markdown 发回；超过 textChunkLimit 会被切开。默认模型是 deepseek-chat。
2. 群里只在被 @ 时说话¶
把机器人拉进群后，默认不会对每条群消息作答。需要 @ 机器人，或把 requireMention 改成 false（群很吵时不建议关）。群聊还可以单独写 groupPrompt，例如限制语气、禁止代发敏感操作。
3. 用斜杠命令管理当前会话¶
在对应私聊或群里发送：
/bot-help
/bot-status
/bot-model
/bot-reset
/bot-help 列出指令；/bot-status 看当前会话；/bot-model 查看或切换模型；聊偏了用 /bot-reset 清上下文。这些命令作用在当前 peer 的会话上，不会把其他用户或群的记忆清掉。
4. 按 README 改常用配置¶
README 配置表里和日常使用最相关的几项：
| 配置 | 默认值 | 说明 |
|---|---|---|
appId |
必填 | QQ Bot AppID，或环境变量 QQBOT_APPID |
appSecret |
必填 | QQ Bot AppSecret，或环境变量 QQBOT_SECRET |
provider |
deepseek-official |
LLM 提供商名称 |
model |
deepseek-chat |
模型名称 |
preset |
- | Agent preset id |
cwd |
process.cwd() |
Agent 工作目录 |
requireMention |
true |
群聊是否需要 @bot 才触发 |
textChunkLimit |
4500 |
单条消息最大字符数 |
sessionIdleTimeout |
1800000 |
会话闲置超时（毫秒） |
debug |
false |
调试模式 |
cwd 决定 Agent 在磁盘上的工作目录。dsh 的工具默认跟当前进程权限走，把机器人接到 QQ 之后，等于把这套权限暴露给能发消息的人，白名单和 requireMention 值得先想清楚。
适用场景与注意事项¶
适合已经在用 dsh、希望把同一套 Agent 接到 QQ 的人：个人助手放在私聊、小团队在群里 @ 机器人查代码或跑任务、自己写 preset 后再从 QQ 触发。不适合把它理解成「装完就能代替官方 QQ 客服后台」——它是 IM 通道插件，模型、工具、沙箱仍然来自你当前的 dsh profile。
使用前注意这几件事：
- 权限与源码。 插件以当前 dsh 进程的权限运行，安装时可能执行代码。装之前阅读
tencent-connect/dsh-qqbot源码和 MIT 许可证；生产环境用目录页那种github:owner/repo#commit固定提交。 - 凭据。 AppID / AppSecret 或扫码写入的凭据等同于机器人身份，不要提交到 git，也不要在多人共享的机器上用未加访问控制的开放模式。
- 预览版兼容性。 DeepSeek Harness 官方 README 写明当前是 developer preview，会有破坏性变更。插件的 peer 依赖指向
@deepseek-ai/cordis >=4.0.1以及@deepseek-ai/dsh-agent/dsh-llm/dsh-session的>=0.1.0-rc.6。dsh 升级后若加载失败，先对一下这几项版本。 - 群聊打扰。 默认
@门控是为了少插话。关掉requireMention前，先确认群规模和访问控制。 - 目录与仓库不是同一件事。 安装命令以目录页原文为准；具体扫码流程、配置项和命令以 GitHub README 为准。两者冲突时，配置与用法以仓库一手文档更接近实现。
小结¶
dsh-qqbot 把 QQ 变成 dsh Agent 的一条前端：私聊和群聊隔离会话，重启可按同一 sessionKey 恢复，群默认要 @ 才响应，回复按 Markdown 切分发送。目录页安装命令是 dsh plugin add github:tencent-connect/dsh-qqbot；实际跑起来，仓库更完整的路径是装进 qqbot profile，启动后扫码绑定。
目录页：https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-qqbot/
GitHub：https://github.com/tencent-connect/dsh-qqbot
