@zaofan/dsh-qqbot 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tencent Connect
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,308 @@
+# @zaofan/dsh-qqbot
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE) ![Platform](https://img.shields.io/badge/platform-QQ%20Bot%20(dsh)-blue)
+
+基于 [deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) 的 QQ Bot IM 插件**增强 fork**：将 QQ 消息平台作为 dsh agent 的前端协议驱动，并加入表情包图库、富媒体收发、定时任务、多实例人格、可视化设置面板等能力。
+
+📦 仓库: [gcry13067381632-jpg/dsh-qqbot](https://github.com/gcry13067381632-jpg/dsh-qqbot)（fork 自 [tencent-connect/dsh-qqbot](https://github.com/tencent-connect/dsh-qqbot)）
+
+中文 | [English](./README_EN.md)
+
+## 🐋 本 fork 增强版
+
+**一句话**：让跑在 dsh 上的 QQ 机器人"活"起来——会存表情包、会挑图回你、到点主动开口、一个DSH还能同时开好几个不同性格的机器人号。
+
+它是上游 [@tencent-connect/dsh-qqbot](https://github.com/tencent-connect/dsh-qqbot) 的增强 fork（改动不在上游源码里，升级/重装上游会被冲掉）。
+
+### 装上之后，它能帮你……
+
+**🤳 群里的表情包，自动变成它的收藏**
+群里谁发了图，机器人自动存进本地图库（自动去重、分"待整理/收藏/回收站"）。你只要说一句"发个开心点的图"——它自己搜库、自己挑、自己发，还会挑场合出手（可配置：冷场不发、刷屏限量、同图不连发）。
+
+**⏰ 到点它会自己开口**
+设置里告诉它"每天早 9 点去群里说早安"，它就准点出现；跟它说"30 秒后提醒我去喝水"，它到点真会来催你。
+
+**🧑‍🤝‍🧑 一个电脑，多个人格同时在线**
+傲娇系、元气系、高冷系……想开几个开几个：每个号独立 AppID、独立人格、独立工作目录（图库/定时/闸门全分开，互不串号）。新号不用翻教程——Web 页点「扫码绑定」，手机 QQ 扫一下，凭据自动填好。
+
+**🛡️ 群主/群管理员的帮手：入群审批 + 禁言**
+机器人为群管理员时，可在设置面板「⑥ QQ 群管理」开总开关：有人申请进群，机器人收实时事件并在群里提醒你，回一句"通过/拒绝"就审批；也能查禁言状态、把人禁言或解禁（全部走官方接口，出错给"人话"提示：不是管理员/不能禁群主等）。
+
+**🧹 图库乱？让 AI 自己整理**
+一句话"看看收藏里哪些图还没写介绍"，它列出清单、自己补标签补描述，越用越懂你。
+
+**🖥️ 不用碰配置文件，全在设置面板点**
+机器人怎么回、能发什么图、什么时候主动说话、每个号用什么人格——都在一个面板里改，保存即生效（账号增减才需重启）。
+
+### 📸 效果展示
+
+图①：dsh 运行后台——思考过程、工具调用、Token 用量一目了然（配合「回复闸门 reply_gate」可让机器人自主判断该开口还是静默吃瓜）；
+图②：QQ 群里的抓鬼游戏互动——该回就回、该藏就藏，角色扮演全自动；
+图③：斗图实战——机器人用自己收藏的表情包接招回击，图、文分开两条连发。
+
+![后台运行日志（思考过程与工具调用可见）](docs/showcase-1-log.png)
+
+![QQ 群聊互动效果（角色扮演/自主静默）](docs/showcase-2-chat.png)
+
+![斗图实战（发表情包接招回击）](docs/showcase-3-doutu.png)
+
+### 给开发者的话
+- QQ 会话内可直接调用的标准工具：发图/撤图/查库/打标/查未整理/定时（`send_media`/`recall_message`/`list_stickers`/`sticker_tag`/`sticker_untagged`/`schedule_timer`/`schedule_cancel`…），会话按账号精确路由
+- **群管理工具**（`group_join_requests`/`group_approve_join`/`group_mute_state`/`group_mute_member`…）：入群审批与禁言，需机器人为该群管理员；对话内管当前群，web/非群会话用配置的 `manageGroup`
+- **纯文本也能发图撤消息**：让ai再回复里写 `[MEDIA:image|图片路径或网址]` 就自动变成真图发出去（`voice`/`video`/`file` 同理）；写 `[RECALL]` 撤回自己刚发的那条
+- 会话归属、工作区挂载等宿主问题已按官方机制修好（移植上游 PR #21，幂等、全 fail-soft）
+
+> 🛡️ 仓库**不含**任何机器人凭据、图库数据、日志与个人路径（发布前已清理）。AppID/AppSecret 请走环境变量或 Web 面板注入，**不要提交进 git**。
+
+### 构建与部署
+
+```bash
+npm install                 # 安装依赖（peer 依赖由 dsh 宿主解析）
+npm run build               # 或: node node_modules/typescript/lib/tsc.js -p tsconfig.json
+npm run check:package       # 发布前自检(单包四项家当齐全)
+pnpm pack                   # 打 tarball(供 dsh plugin add 安装)
+```
+
+安装到 dsh profile 见下方「安装」小节（同样支持 `dsh plugin add` 与扫码引导）。
+仓库根的 `install.ps1` 提供 Windows 一键安装（自动 pack 到无空格目录 → add → 重启提示）。
+
+---
+
+## 架构
+
+```
+QQ 用户 → QQ WebSocket → dsh-im-qqbot → ctx.agents → dsh agent loop → LLM
+                                 ↑                           │
+                                 └── session/event ──────────┘
+                                       (assistant reply → QQ sendMarkdown)
+```
+
+## 安装
+
+> ⚠️ **必须装到 `web` profile**（`dsh web` 设置面板的宿主）；装到别的 profile 只会得到没有设置面板的裸环境。
+> 也不要 `add @tencent-connect/dsh-qqbot`——那会装上游官方版（无本 fork 增强功能）。
+>
+> ✅ **单包自含，装一个就全有**：QQ 机器人 + Web 可视化设置面板（host 桥 + 设置页 UI）都打包在
+> 这一个包内——装完它，dsh Web「设置」里就会出现「QQ 机器人 (im-qqbot)」面板（多账号时每个实例各一页），
+> **无需再单独安装 dsh-qqbot-settings**。
+
+### 方式一（发布到 npm 后）：一条命令
+
+```powershell
+npx @deepseek-ai/dsh plugin --profile web add @zaofan/dsh-qqbot
+```
+
+> 尚未发布到 npm 前，请用下面的方式二。
+
+### 方式二：源码分发（当前推荐）
+
+**Windows（一键脚本）**：
+
+```powershell
+git clone https://github.com/gcry13067381632-jpg/dsh-qqbot.git
+cd dsh-qqbot
+.\install.ps1          # 自动 install/build → pack → add tarball → 输出重启指引
+```
+
+> 若系统禁止运行脚本，改用：`powershell -ExecutionPolicy Bypass -File .\install.ps1`
+
+**macOS / Linux（手动）**：
+
+```bash
+git clone https://github.com/gcry13067381632-jpg/dsh-qqbot.git
+cd dsh-qqbot
+npm install && npm run build
+pnpm pack --pack-destination /tmp
+npx @deepseek-ai/dsh plugin --profile web add /tmp/zaofan-dsh-qqbot-0.4.0.tgz
+```
+
+> 💡 为什么打 tarball、而不是 `add` 源码目录？实测教训：
+> ① 目录路径含空格时 Windows 会把参数在空格处拆碎（pnpm 报 `- isn't supported`）；
+> ② `add` 目录 = pnpm link(junction)，插件无法按"代码位置"反推 profile → 扫码凭据落不了盘，只能走环境变量。
+
+### 排障: npm 安装报 ERESOLVE(2026-09-06 移植上游 PR #42)
+
+首次 `npm install` 可能报 `ERESOLVE could not resolve`——原因: `@deepseek-ai/dsh-tools`/`dsh-agent` 等 peer 依赖仍在 prerelease(-rc) 版本线,npm 7+ 严格解析拒绝不相交组合。**这是上游版本线问题,不是插件 bug**,两条绕过路:
+
+```bash
+npm install --legacy-peer-deps     # 仅安装期解析策略, 不改运行行为
+# 或: 装完依赖后手动 build + pack(peer 由 dsh 宿主解析, 不受影响)
+```
+
+> 跟踪中: 上游 #37 根治后此段可删(版本线收敛后 npm 不再报错)。
+
+### 首次启动与绑定
+
+启动 `dsh web` 后，若未配置凭据会自动进入**扫码引导**：终端输出二维码 → 手机 QQ 扫码绑定 → 凭据自动保存，重启不丢（设置面板里也可随时「扫码绑定」/改账号）。
+
+![二维码扫码示意图](./docs/assets/qrcode.png)
+
+> **提示**：建议使用 `0.4.0` 以上版本扫码，支持点击链接在浏览器打开，避免部分终端二维码渲染错位的问题。
+
+### 还没有 QQ 机器人？先注册一个（拿 AppID / AppSecret）
+
+1. 打开 [QQ 开放平台](https://q.qq.com)，用 QQ 号登录；
+2. 进入「机器人」→「创建机器人」，填好名称、头像、简介；
+3. 创建完成后在机器人详情页拿到 **AppID** 与 **AppSecret**；
+4. 在 dsh Web → 设置 →「QQ 机器人」→「账号与预设」里填入并保存
+   （或设为环境变量 `QQBOT_APPID` / `QQBOT_SECRET`）；
+5. 按需在平台开通**单聊/群聊**消息权限（群聊一般需要提交用途审核）。
+
+> 💡 更省事：机器人建好即可，首次启动直接**扫码绑定**，不用手抄凭据。
+
+### 开发者：--patch 开发模式
+
+```bash
+export QQBOT_APPID="你的AppID" QQBOT_SECRET="你的AppSecret"
+npx @deepseek-ai/dsh web --patch /path/to/dsh-qqbot/cordis.dev.yml
+```
+
+## QQ 远程审批(可选)
+
+当 Agent 的工具要访问**工作区之外**的位置时,dsh 会触发权限审批。开启后,机器人把审批请求**发到 QQ**(任务发起者的会话),你直接在 QQ 里放行/拒绝:
+
+> ⚠️ **DSH 权限申请**
+> 工具：pwsh
+> 原因：需要访问工作区外路径
+>
+> 允许本次操作：`/approve A1B2C3`
+> 拒绝本次操作：`/deny A1B2C3`
+> 仅本次有效，120 秒后自动拒绝。
+
+**启用**(二选一;保存即对新审批请求生效,无需重启):
+- **Web 设置面板**:设置 →「QQ 机器人」→ ⑤ QQ 远程审批 → 勾选开启;
+- 或 `cordis.patch.yml` 的实例 config 加两行后重启:
+
+```yaml
+- id: im-qqbot
+  config:
+    enableApprovals: true          # 默认 false
+    approvalTimeoutMs: 120000      # 等待时长, 超时自动拒绝
+```
+
+**安全边界**:验证码一次性;仅"任务发起者本人 + 同一会话"可批(群聊里其他人看到验证码也无效);只授权当前这一次操作;Agent 取消或 dsh 退出自动取消。
+
+> 思路来源: wang-22-code/dsh-qqbot-bridge 的 QQ 审批设计(宿主 dsh `approval/request` 标准事件,官方 dsh-acp / Web 审批弹窗同款机制)。
+
+## QQ 群管理(可选)
+
+机器人**为群管理员**时,可开启群管理能力:实时接收「入群申请」并自动提醒主人、按申请审批入群、查询/设置群成员禁言。所有操作走腾讯官方 GroupOpenMsg 接口,错误信息已做"人话"映射(如 11703=机器人不是该群管理员、40103004=不能禁言群主/管理员、11255=群已注销)。
+
+**能力总开关**:
+
+- **Web 设置面板**: 设置 →「QQ 机器人」→ ⑥ QQ 群管理 → 勾选开启,并填/选「默认管理群」;
+- 或 `cordis.patch.yml` 的实例 config 加配置后重启:
+
+```yaml
+- id: im-qqbot
+  config:
+    groupAdmin:
+      enabled: true
+      owners: []                       # 主人 openid 白名单(空=不校验)
+      manageGroup: "群openid"           # 对话内默认管理群(web/非群会话用; 群会话自动取当前群)
+      watchJoinRequests: true          # 订阅入群申请事件(改后需重启: 涉及连接期 intents)
+      notifyInGroup: true              # 收到申请时在群内发提醒
+```
+
+> ⚠️ `watchJoinRequests` 需要连接期注册 intents(GROUP_MEMBER_EVENT, 1<<24)——**改它必须重启**,不是 live 热改;且需官方对该机器人开放对应能力,否则连接可能被拒(4914/4915)。
+
+**入群审批怎么用**: 事件到达 → bot 在群里发一条提醒(含申请人昵称/验证语)→ 你在对话里说"通过/拒绝"(AI 调 `group_approve_join`)→ 官方落库审批。也可以在设置面板「⑥ QQ 群管理 → 入群审批」页看待审批清单手动批。
+
+**配置项**(Web 面板 ⑥ 可改, 见下表 `groupAdmin.*`)
+
+## 配置项
+
+| 配置 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `appId` | string | **必填** | QQ Bot AppID（或通过 `QQBOT_APPID` 环境变量） |
+| `appSecret` | string | **必填** | QQ Bot AppSecret（或通过 `QQBOT_SECRET` 环境变量） |
+| `provider` | string | `deepseek-official` | LLM 提供商名称 |
+| `model` | string | `deepseek-chat` | 模型名称 |
+| `preset` | string | - | Agent preset id |
+| `cwd` | string | `process.cwd()` | Agent 工作目录 |
+| `requireMention` | boolean | `true` | 群聊是否需要 @bot 才触发 |
+| `groupPrompt` | string | - | 群聊额外 system prompt |
+| `directPrompt` | string | - | 私聊额外 system prompt |
+| `textChunkLimit` | number | `4500` | 单条消息最大字符数 |
+| `sessionIdleTimeout` | number | `1800000` | 会话闲置超时(ms)，默认 30 分钟 |
+| `debug` | boolean | `false` | 调试模式 |
+| `groupAdmin.enabled` | boolean | `false` | 群管理总开关(需机器人为群管理员) |
+| `groupAdmin.owners` | string[] | `[]` | 可操作群管理的主人 openid 白名单(空=不校验) |
+| `groupAdmin.manageGroup` | string | `''` | 对话内默认管理群 openid(web/非群会话时用) |
+| `groupAdmin.watchJoinRequests` | boolean | `false` | 订阅入群申请事件(改后需重启) |
+| `groupAdmin.notifyInGroup` | boolean | `true` | 收到申请时在群内发提醒 |
+
+> 🔧 新版 Web 面板把群管理单开成「⑥ QQ 群管理」卡片(入群审批/禁言/成员信息/黑名单), 与上方 `groupAdmin.*` 配置同一份数据。
+
+## 内置命令
+
+| 命令 | 说明 |
+|------|------|
+| `/bot-reset` | 重置当前会话（清除上下文） |
+| `/bot-model` | 查看或切换模型 |
+| `/bot-status` | 查看当前会话状态 |
+| `/bot-help` | 查看所有指令 |
+
+## 核心模块
+
+```
+src/
+├── index.ts                    # Cordis 插件入口（async apply）
+├── config.ts                   # 配置 Schema
+├── types.ts                    # 全局类型定义
+├── setup.ts                    # 凭据绑定（扫码）
+├── transport/                  # 传输层
+│   ├── inbound.ts              # QQ 入站消息 → agent.followup()
+│   ├── outbound.ts             # session/event → QQ sendMarkdown
+│   ├── outbound-buffer.ts      # 流式缓冲
+│   └── chunker.ts              # Markdown 文本切分
+├── session/                    # 会话管理层
+│   ├── session-manager.ts      # QQ peer → Agent 映射
+│   └── idle-evictor.ts         # 闲置回收
+├── model/                      # 模型路由层
+│   ├── model-resolver.ts       # 路由解析
+│   ├── prefs-store.ts          # per-peer 偏好持久化
+│   └── settings-reader.ts      # settings.yaml 只读
+├── shared/                     # 共享工具
+│   ├── utils.ts                # 通用函数
+│   ├── scope.ts                # scope/peer 提取
+│   └── send-helper.ts          # 分块发送
+├── commands/                   # 斜杠命令
+└── typings/                    # 外部模块声明
+```
+
+## 会话路由
+
+sessionKey: `qqbot:${appId}:${scope}:${peerId}`，由 SHA-256 确定性派生 SessionId，重启后可恢复。
+
+解析策略：进程内复用 → 持久化恢复 → 全新创建。
+
+## 设计原则
+
+- **纯 Cordis 插件** — 遵循 dsh "Plugins, not loop changes" 原则
+- **声明式依赖** — `inject = ['agents']`，不直接耦合其他插件
+- **会话隔离** — 每个 QQ 私聊用户/群聊各一个独立 Agent
+- **Preset 支持** — 可通过 `agent-presets` 服务挂载预设（工具集、prompt 等）
+- **闲置回收** — 超时自动 dispose Agent，防止内存泄漏
+- **Markdown 输出** — 回复以 Markdown 格式发送，支持代码块/表格感知切分
+
+## 本地开发
+
+```bash
+# 安装依赖
+pnpm install
+
+# 构建
+pnpm build
+
+# 开发模式（watch）
+pnpm dev
+
+# 用 --patch 方式调试
+export QQBOT_APPID="xxx" QQBOT_SECRET="xxx"
+npx @deepseek-ai/dsh web --patch /path/to/dsh-qqbot/cordis.dev.yml
+```
+
+## License
+
+[MIT](./LICENSE)

package/README_EN.md

@@ -0,0 +1,273 @@
+# @zaofan/dsh-qqbot
+
+An **enhanced fork** of the QQ Bot IM plugin for [deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) (dsh): it drives the dsh agent loop with the QQ messaging platform as the frontend protocol, adding a local sticker library, rich media send/recall, scheduled tasks, multi-instance personas, and a visual settings panel.
+
+📦 Repo: [gcry13067381632-jpg/dsh-qqbot](https://github.com/gcry13067381632-jpg/dsh-qqbot) (forked from [tencent-connect/dsh-qqbot](https://github.com/tencent-connect/dsh-qqbot))
+
+[中文文档](./README.md) | English
+
+## 🐋 This fork (enhanced edition)
+
+**In one line**: bring your dsh-powered QQ bot to life — it auto-collects stickers from group chats, picks and sends the right one when the mood hits, speaks up on schedule, and lets you run several bots with different personalities from one computer.
+
+This repo is an enhanced fork of [@tencent-connect/dsh-qqbot](https://github.com/tencent-connect/dsh-qqbot) (changes live outside the upstream source — reinstalling/upgrading upstream will wipe them).
+
+### What it does for you
+
+- **🤳 Group images become its sticker library automatically** — saved locally with dedup, organized into "to-sort / favorite / trash". Just say *"send something happy"* and it searches, picks and sends on its own — with optional guardrails (no posting into a cold chat, rate limits, no repeat stickers).
+- **⏰ It speaks up on time** — schedule a daily greeting at 9:00, or tell it *"remind me to drink water in 30 seconds"* and it actually will.
+- **🧑‍🤝‍🧑 Multiple bots, multiple personalities, one machine** — each bot has its own AppID, persona preset and working directory (sticker library / timers / gates fully isolated). Adding a bot is a phone-QR scan away from the Web panel — credentials are filled in automatically.
+- **🛡️ Group admin helper: join-request approval + mute management** — when the bot is a group admin, enable it in the panel (⑥ QQ Group Admin): join requests arrive as real-time events with an in-group reminder (reply "approve/reject" to handle them), and you can inspect mute state or mute/unmute members — all through official APIs with human-readable errors (not an admin / cannot mute the owner, etc.).
+- **🧹 Messy library? Let the AI tidy it** — ask *"which stickers still lack tags or descriptions"* and it lists them, then tags and describes them itself.
+- **🖥️ No config-file surgery** — reply pacing, sticker gates, scheduled wake-ups, and per-bot personas are all editable in the settings panel; saving applies live (only adding/removing bots needs a restart).
+
+### 📸 Showcase
+
+Left: the dsh runtime backend — reasoning, tool calls and token usage are fully visible (paired with the `reply_gate` gate tool, the bot decides on its own whether to speak or stay silently idle);
+Middle: real QQ group conversation — hide-and-seek role-play, replying when it should and staying quiet when it shouldn't;
+Right: sticker-battle in action — the bot answers with stickers from its own library, image and text sent as separate messages.
+
+![Runtime backend log (reasoning & tool calls visible)](docs/showcase-1-log.png)
+
+![QQ group conversation (role-play / self-decided silence)](docs/showcase-2-chat.png)
+
+![Sticker battle (replying with own sticker library)](docs/showcase-3-doutu.png)
+
+### For developers
+- Standard tools available inside QQ sessions: `send_media` / `recall_message` / `list_stickers` / `sticker_tag` / `sticker_untagged` / `schedule_timer` / `schedule_cancel` …, routed per bot account.
+- **Group admin tools** (`group_join_requests` / `group_approve_join` / `group_mute_state` / `group_mute_member` …): join-request approval and mute management — requires the bot to be a group admin; inside a group session the current group is used, elsewhere the configured `manageGroup` applies.
+- **Plain text can send media or recall messages**: writing `[MEDIA:image|path-or-url]` in a reply turns it into a real image message (`voice`/`video`/`file` work the same); a lone `[RECALL]` line recalls the bot's own last message.
+- Host-level fixes (workspace session attachment, upstream PR #21) are included — idempotent and fully fail-soft.
+
+> 🛡️ This repo contains **no** bot credentials, sticker data, logs or personal paths (cleaned before publishing). Inject AppID/AppSecret via env vars or the Web panel — **never commit them**.
+
+### Build & deploy
+
+```bash
+npm install                 # install deps (peer deps resolved by the dsh host)
+node node_modules/typescript/lib/tsc.js -p tsconfig.json   # or npm run build
+# then copy dist/ over your dsh profile's
+# node_modules/@tencent-connect/dsh-qqbot/dist/ and restart dsh
+```
+
+See the upstream "Installation" section below (`dsh plugin add` + QR onboarding both work).
+
+---
+
+## Architecture
+
+```
+QQ User → QQ WebSocket → dsh-im-qqbot → ctx.agents → dsh agent loop → LLM
+                                 ↑                           │
+                                 └── session/event ──────────┘
+                                       (assistant reply → QQ sendMarkdown)
+```
+
+## Installation
+
+> ⚠️ **Install into the `web` profile** (host of the `dsh web` settings panel); other profiles get a bare
+> environment with no settings UI. Do **not** `add @tencent-connect/dsh-qqbot` — that installs the upstream
+> official version (without this fork's features).
+>
+> ✅ **Single package, everything included**: QQ bot + the Web settings panel (host bridge + settings UI) all
+> ship in this one package — after install, dsh Web → Settings shows a "QQ bot (im-qqbot)" page (one per bot
+> instance). **No separate dsh-qqbot-settings install needed.**
+
+### Method 1 (after npm release): one command
+
+```powershell
+npx @deepseek-ai/dsh plugin --profile web add @zaofan/dsh-qqbot
+```
+
+> Until it is published to npm, use Method 2 below.
+
+### Method 2: from source (recommended for now)
+
+**Windows (one-click script)**:
+
+```powershell
+git clone https://github.com/gcry13067381632-jpg/dsh-qqbot.git
+cd dsh-qqbot
+.\install.ps1          # npm install/build -> pack -> add tarball -> prints restart steps
+```
+
+> If script execution is blocked: `powershell -ExecutionPolicy Bypass -File .\install.ps1`
+
+**macOS / Linux (manual)**:
+
+```bash
+git clone https://github.com/gcry13067381632-jpg/dsh-qqbot.git
+cd dsh-qqbot
+npm install && npm run build
+pnpm pack --pack-destination /tmp
+npx @deepseek-ai/dsh plugin --profile web add /tmp/zaofan-dsh-qqbot-0.4.0.tgz
+```
+
+> 💡 Why a tarball instead of `add <source dir>`? Lessons from real installs:
+> ① a directory path containing spaces gets split at the spaces on Windows (pnpm reports `- isn't supported`);
+> ② `add <dir>` becomes a pnpm link (junction), so the plugin can't locate the profile by its code location,
+> and scanned credentials cannot be persisted (env-var-only fallback).
+
+### Troubleshooting: npm install fails with ERESOLVE (backported from upstream PR #42)
+
+A fresh `npm install` may fail with `ERESOLVE could not resolve`. Cause: peer deps like
+`@deepseek-ai/dsh-tools` / `dsh-agent` are still on prerelease (-rc) version lines, and npm 7+
+strict resolution rejects non-intersecting combinations. **This is an upstream version-line issue, not a plugin bug.** Two workarounds:
+
+```bash
+npm install --legacy-peer-deps     # install-time resolution only; runtime behavior unchanged
+# or: install deps, then build & pack manually (peers are resolved by the dsh host)
+```
+
+> Tracked: once upstream #37 is fixed and version lines converge, this section can be removed.
+
+### First launch & binding
+
+Start `dsh web`. If credentials are missing, the **QR flow** starts automatically: a QR code is printed in the
+terminal → scan it with the QQ mobile app → credentials are saved and survive restarts (you can also use
+"QR bind" / edit accounts in the settings panel at any time).
+
+![QR code scan example](./docs/assets/qrcode.png)
+
+> **Note**: Use `0.4.0` or later for browser-link scanning, which avoids QR code misalignment in some terminals.
+
+### Don't have a QQ bot yet? Register one (get AppID / AppSecret)
+
+1. Open the [QQ Open Platform](https://q.qq.com) and sign in with your QQ account;
+2. Go to "Bot" → "Create Bot" and fill in name, avatar and description;
+3. After creation, copy the **AppID** and **AppSecret** from the bot detail page;
+4. Enter them in dsh Web → Settings → "QQ bot" → "Accounts & presets" and save
+   (or set env vars `QQBOT_APPID` / `QQBOT_SECRET`);
+5. Enable the needed **single-chat / group-chat** message permissions on the platform
+   (group chat usually requires a use-case review).
+
+> 💡 Easier: once the bot exists, just use the **QR scan bind** on first launch — no need to type credentials.
+
+### For developers: --patch dev mode
+
+```bash
+export QQBOT_APPID="yourAppID" QQBOT_SECRET="yourAppSecret"
+npx @deepseek-ai/dsh web --patch /path/to/dsh-qqbot/cordis.dev.yml
+```
+
+## Remote approval over QQ (optional)
+
+When an Agent tool needs access **outside the workspace**, dsh raises a permission request. With this
+feature on, the bot forwards the request to the **QQ conversation of the task's initiator**, and you
+allow/deny right from QQ:
+
+> ⚠️ **DSH permission request**
+> Tool: pwsh
+> Reason: needs access outside the workspace
+>
+> Allow this operation: `/approve A1B2C3`
+> Deny this operation: `/deny A1B2C3`
+> One-time only; auto-denied after 120 s.
+
+**Enable** (either way; takes effect for new requests right after saving, no restart needed):
+- **Web settings panel**: Settings → "QQ bot" → ⑤ QQ remote approval → tick it on;
+- or add two lines to the instance `config` in `cordis.patch.yml`, then restart:
+
+```yaml
+- id: im-qqbot
+  config:
+    enableApprovals: true          # default false
+    approvalTimeoutMs: 120000      # wait window; auto-deny on timeout
+```
+
+**Security boundaries**: one-time code; only the **initiator in the same conversation** may decide
+(others in a group chat cannot approve even if they see the code); grants only the current operation;
+auto-cancelled when the agent is cancelled or dsh exits.
+
+> Idea source: QQ-approval design of wang-22-code/dsh-qqbot-bridge (host dsh `approval/request`
+> standard event — the same wiring used by official dsh-acp and the Web approval dialog).
+
+## Configuration
+
+| Config | Type | Default | Description |
+|------|------|--------|------|
+| `appId` | string | **required** | QQ Bot AppID (or via `QQBOT_APPID` env var) |
+| `appSecret` | string | **required** | QQ Bot AppSecret (or via `QQBOT_SECRET` env var) |
+| `provider` | string | `deepseek-official` | LLM provider name |
+| `model` | string | `deepseek-chat` | Model name |
+| `preset` | string | - | Agent preset id |
+| `cwd` | string | `process.cwd()` | Agent working directory |
+| `requireMention` | boolean | `true` | Whether group messages require @bot to trigger |
+| `groupPrompt` | string | - | Extra system prompt for group chats |
+| `directPrompt` | string | - | Extra system prompt for direct chats |
+| `textChunkLimit` | number | `4500` | Max chars per message |
+| `sessionIdleTimeout` | number | `1800000` | Session idle timeout (ms), default 30 min |
+| `debug` | boolean | `false` | Debug mode |
+
+## Built-in Commands
+
+| Command | Description |
+|------|------|
+| `/bot-reset` | Reset the current session (clear context) |
+| `/bot-model` | View or switch model |
+| `/bot-status` | View current session status |
+| `/bot-help` | View all commands |
+
+## Core Modules
+
+```
+src/
+├── index.ts                    # Cordis plugin entry (async apply)
+├── config.ts                   # Config schema
+├── types.ts                    # Global types
+├── setup.ts                    # Credential binding (QR)
+├── transport/                  # Transport layer
+│   ├── inbound.ts              # QQ inbound message → agent.followup()
+│   ├── outbound.ts             # session/event → QQ sendMarkdown
+│   ├── outbound-buffer.ts      # Streaming buffer
+│   └── chunker.ts              # Markdown chunking
+├── session/                    # Session management
+│   ├── session-manager.ts      # QQ peer → Agent mapping
+│   └── idle-evictor.ts         # Idle eviction
+├── model/                      # Model routing
+│   ├── model-resolver.ts       # Route resolution
+│   ├── prefs-store.ts          # Per-peer preference persistence
+│   └── settings-reader.ts      # settings.yaml read-only
+├── shared/                     # Shared utilities
+│   ├── utils.ts                # Common helpers
+│   ├── scope.ts                # scope/peer extraction
+│   └── send-helper.ts          # Chunked send
+├── commands/                   # Slash commands
+└── typings/                    # External module declarations
+```
+
+## Session Routing
+
+sessionKey: `qqbot:${appId}:${scope}:${peerId}`, with the SessionId derived deterministically via SHA-256 so sessions survive restarts.
+
+Resolution strategy: in-process reuse → persisted resume → fresh create.
+
+## Design Principles
+
+- **Pure Cordis plugin** — follows the dsh "Plugins, not loop changes" principle
+- **Declarative dependencies** — `inject = ['agents']`, no direct coupling to other plugins
+- **Session isolation** — one independent Agent per QQ direct user / group
+- **Preset support** — mount presets (toolkits, prompts, etc.) via the `agent-presets` service
+- **Idle eviction** — auto-dispose Agents on timeout to prevent memory leaks
+- **Markdown output** — replies sent as Markdown with code-block/table-aware chunking
+
+## Local Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build
+pnpm build
+
+# Dev mode (watch)
+pnpm dev
+
+# Debug via --patch
+export QQBOT_APPID="xxx" QQBOT_SECRET="xxx"
+npx @deepseek-ai/dsh web --patch /path/to/dsh-qqbot/cordis.dev.yml
+```
+
+## License
+
+[MIT](./LICENSE)