QQ远程机器人 cyanovo/dsh-remote-qqbot

dsh-remote-qqbot

DSH 的 QQ 远程机器人插件。DSH 在电脑上干活，你在外面：跑完了、需要你拍板、出错了，它主动发到你 QQ；你在 QQ 里引用那条消息回一句，这句话就回到它所属的会话里，跟你坐在电脑前打字一样。

上手：两步

1. 装插件 —— 一条命令，或者把「安装」里那段话整个复制给 DSH，让它自己装。
2. 填一对 QQ 机器人凭证 —— DSH 里「设置 → QQ 远程提醒与跨会话记忆 → QQ 远程提醒」，打开「QQ 机器人通道」，填 AppID 与 ClientSecret，然后重启 DSH。

不需要注册账号、不需要登录、不需要服务器、不需要公网 IP、不需要 frp。
插件直接连腾讯官方机器人接口：收事件走 WebSocket 纯出站长连接，往会话里投递走本机 127.0.0.1 的 DSH 接口 —— 两头都不需要被外网访问。

安装

不想敲命令：把下面这段复制给 DSH

DSH 自己能装插件。把下面这段整个复制下来（GitHub 代码块右上角有复制按钮），粘进 DSH 的输入框发出去：

帮我把 dsh-remote-qqbot 装到 DSH 里。

请执行这条命令，源是 GitHub，仓库里带了构建好的 lib/，装完即可用：
dsh plugin --profile desktop add github:cyanovo/dsh-remote-qqbot

如果你这台是 dsh web 起的，把 --profile desktop 换成 --profile web。

装完核对一次结果（版本号、profile 的 bundles 里有没有 dsh-remote-qqbot），然后提醒我：要重启 DSH 才会生效。

它会自己装好、核对一遍，再把结果告诉你。接着照上面「上手：两步」的第 2 步填 QQ 凭证。

方式一：从 GitHub 装 —— 仓库里带了构建好的 lib/，装完即可用，不需要本地构建：

dsh plugin --profile desktop add github:cyanovo/dsh-remote-qqbot

方式二：从 npm 装 —— 包还没有发布到 npm，这条现在会报 ERR_PNPM_FETCH_404：

dsh plugin --profile desktop add dsh-remote-qqbot

方式三：本机构建 tgz（改过源码，或想离线装）：

cd dsh-remote-qqbot
npm run pack # 产出 dsh-remote-qqbot-<版本>.tgz
dsh plugin --profile desktop add ./dsh-remote-qqbot-<版本>.tgz

用 dsh web 起的把命令里的 --profile desktop 换成 --profile web，其余不变。

三个容易踩的地方（都踩过）：

| 坑 | 说明 |
| --profile 装错 | DSH 桌面版用 desktop；dsh web 起的用 web。装错 profile = 装了个看不见的 |
| tgz 路径必须带 ./ | 写 dsh-remote-qqbot-<版本>.tgz 会被 pnpm 当成 npm 上的包名 ⇒ ERR_PNPM_FETCH_404 |
| 升级要先 remove 再 add | profile 里残留指向已删除 tgz 的依赖时，add 在解析阶段就会 ENOENT |

装完必须重启 DSH 进程才会加载 —— 桌面版是长驻进程，插件没有热加载。

装完第一件事：确认它活着

在 QQ 里给机器人发一句 /status，应该回：

📊 现在的状态 QQ 连着，有事我立刻能收到引用回复能送进会话没有在等你回答的问题 ▶ 现在没有会话在跑，都闲着

回了就说明整条链路通了。没反应的话按这个顺序查（九成是前两条）：

| 现象 | 原因 | 怎么办 |
| 发什么都没回 | 还没重启 DSH，或凭证填错 | 重启桌面版；检查 AppID / ClientSecret 有没有多余空格 |
| 通知收得到，但你引用它回复 → 回一句 ❌ 这句没送进 …：DSH 会话密钥不可用，无法注入 | 桌面版把「会话签名记录」（~/.dsh/.credentials.yaml 里的 client-connection/browser-session，/api 的 cookie 用它签名）弄丢了。推送不需要它，所以通知照发 —— 故障只在入站，最难查 | 插件 1.0.1 起会自己把这条记录补回来（原文件先备份到 ~/.dsh/.credentials.yaml.bak-remote-qqbot-*）。补完重启一次 DSH 桌面版即可恢复；/status 里会明确写着「引用回复送不进会话：…」以及已做过什么补救 |
| 日志说还不知道你的 open_id | 你还从没给机器人发过消息 | 用你的 QQ 给机器人发任意一句话 —— open_id 只能从你发来的消息里被动学到，官方不提供「按 QQ 号查 openid」的接口 |
| 推送收不到，报 40054004 无好友关系 | 没加好友 | 用你的 QQ 把机器人加为好友 |
| 推送收不到，报 40054013 用户拒收消息 | QQ 客户端里关掉了主动消息 | 在 QQ 的机器人会话设置里打开「允许主动发送」 |
| 推送收不到，报 40034105 主动消息无权限 | 平台权限没开 | 到 q.qq.com 的机器人权限里打开单聊主动消息 |

收得到 ≠ 回得进去。 这个插件有两条互相独立的腿：出站推送只走 QQ 长连接，入站注入（引用通知接着聊、/task 派活、/sessions 挑会话）要走本机 127.0.0.1:19387/api，而那个接口的 cookie 由桌面版 ~/.dsh/.credentials.yaml 里的会话签名记录签名。所以「QQ 连着、通知正常」并不代表引用回复能用 —— 2026-10-04 的事故就是这条记录消失导致引用回复全线失效，而通知一切正常。
想一眼确认两条腿都在：QQ 里发 /status。

想知道「中枢 / 云端 / agentmd / 界面里改过的配置」各自落在哪、值是什么，看 设置 → QQ 远程提醒与跨会话记忆 → 顶部「运行状态」（只读）。

要不要登录？只有一件事需要

| 你想要的功能 | 要准备什么 |
| 跑完 / 提问 / 出错推送到 QQ；QQ 里引用回复；/status /sessions /screen /update /help | 只要一对 QQ 凭证 |
| agentmd 自动操作日志、会话上下文注入 | 只要填一个本机目录 agentmdDir |
| 同一工作区多会话自动协作、QQ 闲聊 | 零配置（默认就开着） |
| 跨会话记忆（memory_read / memory_write） | 一个中枢地址（可自建）—— 可选 |
| 在 QQ 里点开「完整回答」的短链接 | 一个云端账号 —— 唯一需要登录的功能，可选 |

把最后一行说白：只有「把完整回答存到服务器、换一条能点开的短链接」这一档需要登录。
它的默认档不需要任何账号 —— 正文切成几条直接发进 QQ，一个字节都不离开你的机器。
而且「允许上传正文」这个总闸 cloudEnabled 默认是关的：就算你把模式改成「存服务器」，也传不出去（日志会写明是哪一道闸挡住的）。
真想要短链接，再看后面「完整回答去哪」那一节。

能做什么

| # | 能力 | 触发点 |
| 1 | 任务完成推送到手机 | agent/status running → idle |
| 2 | 需要你回答问题时推送 | 拦截 tools/pre-execute 的 ask_user_question |
| 3 | 执行出错时推送 | agent/error |
| 4 | 跨会话持久化记忆 | memory_write / memory_read / memory_forget |
| 5 | agentmd 操作日志自动追加 | 会话转 idle 时写入 main.md 第四节表格 |
| 6 | 会话上下文注入 | agent/created 时把 main.md 全文注入 system prompt |
| 7 | QQ 主动私聊通知 | 任务完成 / 提问 / 出错时经官方机器人主动发给你 |
| 8 | QQ 引用回复 → 回到对应会话 | 引用机器人发的某条消息再回复，就回到那条消息所属的会话 |
| 9 | DSH 设置里的独立一项 | 「设置 → QQ 远程提醒与跨会话记忆」：图形界面改全部配置（含 QQ 凭证） |
| 10 | 输入框下方的两个低调小开关 | QQ 提醒 与 协作模式 各自一键开关，不影响连接、不用重启 |
| 11 | 协作模式：同工作区多会话自动协作 | 自动登记「谁在写哪个文件」，撞车当场提醒，会话之间可留言（可在输入框下方或设置里关掉） |
| 12 | 完整回答三档可选（默认不落服务器） | chat=正文切成几条直接发到 QQ（默认）/ note=存服务器但不给链接 / note-link=存服务器并给短链接。见「完整回答去哪」 |
| 13 | 闲聊：只看不动 + 回答直接回聊天框 | 不引用直接发消息时，会话被切成只读（能查不能改），回答正文直接发回 QQ、不占服务器 |
| 14 | QQ 菜单里的「屏幕」→ 手机收到电脑截图 | 点菜单「屏幕」（把 /screen 填进输入框）或直接发 /screen：抓所有显示器合成的整块桌面，压缩成 JPEG 发给你 |
| 15 | QQ 菜单里的「会话」→ 挑一个最近的会话说话 | 点菜单「会话」（/sessions）→ 列出最近在聊的 6 个会话 → 回个数字就切过去；之后不引用消息直接说的话都进它，直到你再切 |
| 16 | 远程更新：有新版本 QQ 提醒，/update 一句话装好 | 插件定期查版本索引；装完自动重启 DSH（不重启不生效）。见「QQ 指令」 |

一句话记住入站规则：引用机器人的消息 = 对那条消息所属的会话说话；不引用直接发 = 用 /sessions 指定过就进那个会话（有提问在等时优先当作答），什么都没指定时才是闲聊（进独立的「闲聊会话」，不进任何工作会话）。

不打扰你的两类"完成"：子智能体（subagent）跑完不推送 —— 它是你派出去的内部活儿；闲聊会话跑完也不推送 —— 你人就在 QQ 里等着回复。两者都可用配置打开。

闲聊会话是"只读"的（默认开）：机器人可以查状态、读文件、跑查看类命令，但任何写入 / 修改 / 删除都会被拒绝，回答只做分析和建议。
⚠️ 只读保护的是本机文件系统；它拦不住 shell 里去改远程主机（例如 ssh 到服务器上删文件）——那属于远程侧权限，需要服务端自己收紧。

闲聊的回答直接发在 QQ 聊天框里（默认开）：不发推送卡片、也不上传「完整回答」笔记，所以不会在服务器上留下任何文件；代价是超长回答会被截断（默认 1500 字）。

隐私默认值：云上传总闸 cloudEnabled 默认关闭。
关着的时候，即使模式选了「存服务器」，插件也一个字节都不会往服务器传，而是退回「把正文直接切条发到 QQ」（日志会明说这件事）。
也就是说：默认配置下，你的回答正文只存在于你自己的机器和你的 QQ 聊天记录里。
想用短链接就得自己去设置里把这个总闸打开 —— 这是刻意的：「把你的正文上传到别处的服务器」这件事必须由你明确同意。

网站：完整回答在这里看

QQ 消息里放不下长回答。这个站点是完整回答的落脚点：插件把正文存上去，QQ 里只留一条短链接，点开就是排版好的全文，手机上打开的也是这个页面。

网站入口：<https://cyanovo.top>

| 站点上有什么 | 说明 |
| 完整回答 | 登录后打开记录，读排版好的原文，不受聊天窗口长度限制 |
| 账号与额度 | 免费版每天可看 100 次、记录保留 5 小时；付费版 ¥2.99 / 30 天，每天 1000 次、保留 48 小时 |
| 设备码绑定 | 插件里不用填账号密码：设置里点绑定，网站给一组设备码，确认一次就把插件挂到你账号下 |
| 记录列表 | 每条记录带来源会话、时间与过期时间 |

网站是可选的。默认配置下插件一个字节都不上传，正文只存在于你自己的机器和 QQ 聊天记录里。
要用短链接，先在设置里打开 cloudEnabled 总闸。

想自己部署也可以，代码就在本仓库 server/ 下，见 server/README.md。

仓库结构

| 路径 | 内容 |
| 根目录 | 插件本体 —— 仓库根目录就是 npm 包，dsh.bundle 指向 cordis.patch.yml |
| server/dsh-web | 网站：账号、额度、记录、完整回答页面 |
| server/dsh-notes-render | 把 markdown 渲染成网页，并生成 QQ 能展开的预览卡 |
| docs/ | 配置、接入 QQ、完整回答、开发等专题文档 |

QQ 指令

发在聊天框里、以 / 开头的话：

| 指令 | 作用 |
| /task <内容> | 强制当新任务送进专属会话（压过引用与闲聊的全部判断） |
| /sessions（也认 /会话、/list） | 列出最近在聊的几个会话（默认 6 个，见 qqRecentCount），回个数字就切过去 |
| /use <N>（也认 /切 <N>） | 直接切到第 N 个；/use 0 = 取消指定 |
| /screen（也认 /screenshot、/shot、/截图、/屏幕） | 抓一张电脑屏幕发给你，见 docs/QQ.md |
| /status | 看状态：正在跑哪些会话，以及 QQ 与入站链路是否正常 |
| /update（也认 /更新） | 把插件更新到最新版（默认装完自动重启 DSH）；/update check 只查不装 |
| /help | 打印指令清单 |

有新版本时：它来告诉你，/update 一句话装好

QQ 里会收到「🔔 插件有新版本 x.y.z（现在跑的是 a.b.c）。发 /update 我就装上 —— 装完会自动重启 DSH，中间有十几秒连不上。」
回一个 /update 就行；只想确认一下，用 /update check。

- 只在真的有新版时才吭声：同一个版本只提醒一次，已经是最新版就什么都不发（不刷屏）。
🔴 远端版本比本机旧时同样不发、也绝不安装 —— 版本号不一样就装等于把用户降级。
- 装完回一条 ✅ 已装 x.y.z（原来是 a.b.c），然后自动重启 DSH（DSH 没有插件热重载，重启是唯一让新版本生效的办法）。
起来之后还会再回一条 ✅ 重启完成，插件现在是 x.y.z；那条回执靠一个重启标记文件，所以手动重启也会收到。
- 那句话里带着兜底动作：要是过了一分钟 DSH 还没回来，手动打开一次就行。插件自己会被这个重启流程杀掉，没法当场汇报重启结果，所以这句必须提前说。
- 不想自动重启，把 qqUpdateAutoRestart 关掉：只回一句「重启后生效」，由你自己挑时间。
- 更新源默认是作者服务器上的版本索引（https://cyanovo.top/plugins/dsh-remote-qqbot/update.json：版本号 + 压缩包地址 + sha256），所以发版不需要往 Git 仓库里塞提交。想换成 GitHub 或 npm，把 qqUpdateSource 改成 github:作者/仓库 或包名。自己搭通道的格式见 docs/UPDATE.md。
- 更新走桌面版自带的那套运行时（DeepSeek Harness.exe --expose-internals …/pnpm.mjs add …），不会去调用 PATH 上的 dsh（开发机上那个 dsh 常常指向一份源码检出，用它更新会装错地方）。
- 自动重启在 Windows 上有两个坑（1.0.10 / 1.0.11 修）：启动新进程前要清掉从插件进程继承来的 ELECTRON_RUN_AS_NODE（带着它的 DeepSeek Harness.exe 只当 node 跑一下就退出，桌面版不会启动）；认进程不能只看 Get-Process 的 .Path（刚创建的进程读不到它），要用 CIM 兜底。
细节见 docs/UPDATE.md 与 docs/ARCHITECTURE.md §3.10。
- 每次检查与安装都追加到 ~/.dsh/dsh-remote-update.log，事后能查。

工具

| 工具 | 作用 |
| agentmd_read | 读取 agentmd 主文档（或指定文件），支持 maxChars 截断 |
| memory_write | 记住一条持久化信息 |
| memory_read | 读取已记住的信息 |
| memory_forget | 删除一条记忆 |
| collab_status | 协作模式：看同工作区其他会话 + 文件占用 + 留言 |
| collab_post | 协作模式：给其他会话留言 |
| collab_claim | 协作模式：手动认领文件占用（写文件时插件已自动认领） |
| collab_release | 协作模式：释放文件占用（会话转空闲时也会自动释放） |

完整回答去哪（三档）

| 档 | 正文去哪 | 要账号吗 |
| chat（默认） | 切成几条直接发进 QQ | 不要 |
| note | 存到网站，但 QQ 里不给链接 | 要 |
| note-link | 存到网站，并在 QQ 里给一条短链接 | 要 |

三档的取舍、设备码绑定、短链接的实现细节，见 docs/FULLTEXT.md。

配置

在 DSH 里打开「设置 → QQ 远程提醒与跨会话记忆」，全部配置项都能在图形界面里改，不用手写 YAML。
配置文件是 ~/.dsh/settings.yaml，界面里改过的值会覆盖文件里的值。
全部字段、默认值、以及谁盖谁，见 docs/CONFIG.md。

文档

| 文档 | 内容 |
| docs/CONFIG.md | 配置写在哪个文件、谁盖谁、全部字段与默认值 |
| docs/QQ.md | 接入 QQ 官方机器人：能力边界、配置步骤、指令、屏幕与会话 |
| docs/UPDATE.md | 远程更新：版本索引的格式、自己搭通道、自动重启与失败排查 |
| docs/FULLTEXT.md | 完整回答三档、设备码绑定、短链接 |
| docs/COLLAB.md | 协作模式：同一工作区多会话自动避让 |
| docs/AGENTMD.md | agentmd 自动操作日志与会话上下文注入 |
| docs/DEVELOPMENT.md | 开发：测试、构建、代码结构、硬约束、自检 |
| docs/ARCHITECTURE.md | 架构与内部实现：模块职责、数据流、状态文件、踩坑清单 |
| CHANGELOG.md | 版本变更 |
| LICENSE | MIT |

开发

~~~bash
npm install # 装 DSH 自己的包，仅用于本地测试；跑起来时由 DSH 宿主提供
npm test # 19 组测试
npm run pack # 构建 + 打出 tgz

本机开发也可以不装依赖，用 node scripts/link-dev.mjs 建一个指向 DSH profile 的 node_modules 联接。
测试链、构建流程、代码结构与必须遵守的加载期约束，见 docs/DEVELOPMENT.md。

联系方式

装不上、报错看不懂、想要新功能，直接找我。

QQ 1103416608 ｜ GitHub @cyanovo

License

MIT，见 LICENSE。