dsh-remote-qqbot
DSH 的 QQ 远程机器人插件。DSH 在电脑上干活，你在外面：跑完了、需要你拍板、出错了，它主动发到你 QQ；
你在 QQ 里引用那条消息回一句，这句话就回到它所属的会话里，跟你坐在电脑前打字一样。
上手：两步
- 装插件 —— 一条命令，或者把「安装」里那段话整个复制给 DSH，让它自己装。
- 填一对 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（不重启不生效）。见「」 |
一句话记住入站规则：引用机器人的消息 = 对那条消息所属的会话说话；
不引用直接发 = 用 /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。
文档
开发
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。
