dsh-qq-agent
这是给 K0nd1us/QQ-agent 写的 DSH 插件。 先装好并登录 QQ-agent，再装这个插件。
把 DeepSeek Harness（DSH） 接到本机的 QQ-agent 上：在 QQ 里下指令，DSH 在绑定的工作区里干活，结果和审批都回到 QQ；普通聊天仍由 QQ Agent 自己回，两边不抢话。
QQ 是遥控器，DSH 是干活的，QQ Agent 是嘴。
English · 功能 · 配套软件 · 前置要求 · 安装 · 配置 · 命令 · 工具 · 排查
功能
- 在 QQ 里给 DSH 派活：
/工作 <任务>直接送进绑定的工作区，DSH 用真会话（模型 + 全部工具）跑，结果发回 QQ - 审批 / 提问回 QQ：要执行命令、要写文件、要你选的时候，问题推到 QQ，回「执行 / 取消 / 1」即可
- 阶段报告：别的 DSH 工作区在跑长任务时，按「开始 / 工具 / 完成」同步进度到 QQ
- 普通聊天归 QQ Agent：只有指令和审批回答进 DSH，闲聊不占 DSH 的 token
- 人格与记忆一致：注入 QQ Agent 的人设和最近聊天记录，回复像同一个人
- 会话复用：同一个 QQ 聊天始终是同一个 DSH 会话；上下文用到阈值自动换新会话，靠
dsh-handoff把记忆带过去 - 发言限制：一段回复、连发合并、不夹动作描写、发前自查重复/打脸
- QQ Agent 当子代理：DSH 可以调
qq_agent_run让 QQ Agent 用它的技能干活并直接回 QQ - QQ 监控：读 QQ Agent 的
qq-dsh-bridge事件流，看谁说了什么、机器人回了什么
配套软件：QQ-agent
本插件不是独立的 QQ 客户端。它对接的是：
K0nd1us/QQ-agent —— 一个本地运行的 LLM QQ 机器人应用（内置 SnowLuma / OneBot 11）， 用自己的模型和技能在 QQ 上聊天。本插件把它的「嘴」和 DSH 的「手」接起来：
| QQ-agent 负责 | dsh-qq-agent 负责 |
|---|---|
| 收/发 QQ 消息（OneBot HTTP） | 把指令转给 DSH 工作区 |
| 普通聊天、人设、表情、技能 | 把 DSH 的结果 / 审批送回 QQ |
| 提供聊天记录当记忆 | 会话复用、上下文轮换、阶段报告 |
装 QQ-agent：从 Releases 下载安装包，登录机器人号，
确认它的 OneBot HTTP API 已开启（默认 127.0.0.1:3000）。本插件会读它的
%LOCALAPPDATA%\Programs\QQ Agent\data\config.json 拿地址、token、人设和白名单。
前置要求
| 依赖 | 要求 | 说明 |
|---|---|---|
| 系统 | Windows 10/11 | 目前只在 Windows 上验证（PowerShell、路径处理） |
| DSH | 0.2.x（在 0.2.1-rc.3 上验证） |
需要 web profile；用到 sessionController、webServer、workspaceRegistry 等服务 |
| QQ-agent | 本机安装、已登录 | 内置 SnowLuma / OneBot 11 HTTP API（默认 http://127.0.0.1:3000） |
| Node.js | ≥ 22 | DSH 自带；插件本身没有额外运行时依赖 |
| 可选 | dsh-handoff |
上下文到阈值时写交接笔记，换新会话自动带上，强烈建议 |
QQ-agent 的 OneBot HTTP API 要打开，机器人号要在线。插件会从
%LOCALAPPDATA%\Programs\QQ Agent\data\config.json 自动读地址和 token；读不到就在设置里手填。
安装
# 从 GitHub
dsh plugin --profile web add github:Yaeluli/dsh-qq-agent
# 本地开发（link）
dsh plugin --profile web add link:C:\path\to\dsh-qq-agent
装完 重启一次 DSH，然后到 设置 → QQ Agent：
- 打开 总开关
- 填 私聊 QQ 或 群号（至少一个）
- 选 默认工作区
- 在 QQ 里发
/状态或/ws验证
安全默认：总开关默认关、试运行默认开。不手动打开，一条都不会真发出去。
配置
配置文件：~/.dsh/qq-agent-config.json（也可在设置页改）
| 键 | 默认 | 说明 |
|---|---|---|
总开关 |
false |
关掉就完全不发消息 |
试运行 |
true |
只记账不真发 |
接收QQ |
true |
接收 QQ 消息并交给 DSH |
httpUrl / token |
自动 | OneBot 11 HTTP 地址 / token（手填优先） |
私聊QQ / 群号 |
空 | 允许的私聊 / 群 |
默认工作区 |
空 | 没单独绑定时用哪个工作区 |
绑定 |
{} |
聊天 → { workspaceId, sessionId }，插件自动维护 |
审批转发 |
true |
审批 / 提问推 QQ |
人格一致 |
true |
用 QQ Agent 的人设说话 |
记忆条数 |
12 |
带多少条聊天记录进提示词 |
复用会话 |
true |
一个聊天固定用一个 DSH 会话 |
上下文阈值 |
0.8 |
用到这个比例就换新会话（交接笔记由 dsh-handoff 带） |
自查重复 |
true |
发回 QQ 前跟自己刚说过的话比对 |
重复阈值 |
0.7 |
相似度阈值 |
合并消息 |
true |
连发几条合并成一次处理 |
合并等待毫秒 / 合并最长毫秒 |
5000 / 15000 |
合并窗口 |
拆条回复 |
false |
开着时按行拆成多条气泡 |
转交端口 |
4322 |
QQ Agent「做不了就交给 DSH」的本地回填口 |
子代理地址 |
http://127.0.0.1:4321 |
QQ Agent 的 dsh-subagent 插件地址 |
QQ 里能用的命令
| 命令 | 作用 |
|---|---|
/工作 <任务> |
让 DSH 在绑定工作区里干活，结果回 QQ（/做 /干 /ask /task 同义） |
/ws · /工作区 |
列出 DSH 工作区（带序号，当前标「（现在）」） |
/去 <序号 或 名字> |
切到该工作区并开新会话 |
/状态 · /当前 |
看当前绑定、会话、连接 |
/新会话 · /重置 |
清掉会话绑定，下一条开新会话 |
/帮助 |
命令列表 |
@工作区 任务 |
切过去 + 立刻执行这一句 |
工作区匹配顺序：序号 → 完整 id → id 前缀 → 标题 → 标题片段 → 路径末段。
普通聊天不会进 DSH，由 QQ Agent 自己回；只有 /工作、@工作区 和审批回答会走 DSH。
连发合并
对方一口气打好几条时，最后一条之后安静 合并等待毫秒（默认 5 秒、最长 15 秒）才动手，把这批合并成一段交给 DSH，只回一次；上一轮没跑完时新消息继续攒着，不抢答。
给 DSH 的工具
| 工具 | 作用 |
|---|---|
qq_send |
往 QQ 发消息；target = auto/private/group，id 可临时指定 |
qq_status |
看当前登录的 QQ |
qq_groups |
列出机器人所在的群 |
qq_monitor |
看最近的 QQ 消息 / 事件（配合 qq-dsh-bridge） |
qq_agent_run |
让 QQ Agent 子代理干活，结果由它直接回 QQ |
工作流程
QQ 消息
├─ 命令 / 审批回答 → dsh-qq-agent → DSH 会话（绑定工作区）
└─ 普通聊天 → QQ Agent（不动 DSH）
DSH 跑完 → replyToChat → QQ
DSH 要审批 → approval/request → QQ「执行 / 取消」
其他工作区 → 阶段报告 → QQ
QQ Agent 作为子代理
QQ Agent 装 dsh-subagent 插件后，DSH 多一个 qq_agent_run：
- 传一句任务过去，QQ Agent 用自己的技能跑一轮，结果直接发到 QQ，DSH 只收到回执
- 子代理工具集不带发送类工具；最终那段话经过动作描写 / 重复自查
- 地址默认
http://127.0.0.1:4321，GET /health看ready
B 站内容分享
装了 dsh-bili-humanism 后，它读视频时返回的字幕/正文会被整理成一条摘要私聊发到指定 QQ（同一视频只发一次）。设置页可关、可改收件人、可限字数。
QQ 监控
QQ Agent 装 qq-dsh-bridge 后会把事件写到
%LOCALAPPDATA%\Programs\QQ Agent\data\dsh-bridge\（events.jsonl / state.json）。
本插件直接读这两个文件，不走 OneBot 端口；设置页有摘要卡片，会话里用 qq_monitor。
数据
- 配置：
%USERPROFILE%\.dsh\qq-agent-config.json - 只读 QQ Agent 的
data/messages/<chat>.json当记忆，不写它的文件 - 会话在 DSH 自己的会话列表里，标题以
QQ ·开头
排查
- 状态面板：
GET http://127.0.0.1:<DSH端口>/dsh-qq-agent/state - 日志关键字：
[qq-agent] - 发不出去：先看「试运行」、
私聊QQ/群号、token 是否读到 - 收不到消息：确认 QQ Agent 的 OneBot HTTP API 开着、端口/token 对得上
- 会话一直新建：检查「复用会话」，以及
dsh-handoff是否装了 - 和
dsh-qq-bridge同时开着会重复轮询，建议只开一边
安全
- 只连本机回环，不监听公网
- 转交口只绑
127.0.0.1 - 建议在 QQ Agent 侧配
allow/deny白名单，别让陌生人指挥 DSH
自测
node tests/smoke.mjs # 配置归一化 / 拆段 / 取正文
node tests/report.mjs # 阶段报告流水线（假 ctx）
node tests/bridge.mjs # QQ→DSH、回复、审批、提问（假宿主 + 假 OneBot）
都不联网、不改真实配置。
English
dsh-qq-agent is a DeepSeek Harness plugin for K0nd1us/QQ-agent — a local LLM QQ bot app (SnowLuma / OneBot 11). Use /work <task> (or /工作 <task>) in QQ to run a task inside a DSH workspace and get the answer back in QQ; approvals and questions from DSH are forwarded to QQ too. Ordinary chat stays in QQ Agent. Requires Windows, DSH 0.2.x, a logged-in QQ Agent with OneBot HTTP API, and Node >= 22.
License
MIT
No comments yet. Be the first to write one.