@tencent-connect/dsh-qqbot 0.4.0 → 0.5.1

package/.orange-ci.yml

@@ -1,68 +1,2 @@
-$:
-  tag_push:
-    - services:
-        - docker
-      docker:
-        image: node:24
-      runner:
-        network: devnet
-      stages:
-        - name: 安装依赖
-          script: npm install
-        - name: 构建项目
-          script: npm run build
-        - name: 配置 npm 官方源
-          script: npm config set registry https://registry.npmjs.org
-        - name: 配置 token
-          imports: https://git.woa.com/qq-ai/web/secret/blob/master/envs/npm/npmjs.txt
-          script: npm config set //registry.npmjs.org/:_authToken=$NPM_TOKEN
-        - name: 设置 npm 包版本号
-          script: npm version ${ORANGE_BRANCH} --no-git-tag-version --allow-same-version
-        - name: 发布 npm 包
-          script: npm publish --access public
-        - name: 生成通知
-          script: echo "@tencent-connect/dsh-qqbot@${ORANGE_BRANCH} 发布成功" > message.txt
-        - name: 发送通知
-          type: wework:message
-          options:
-            fromFile: message.txt
-
-# ── master 分支：MR 检查 ──
-master:
-  merge_request:
-    - docker:
-        image: node:24
-      wework:
-        silent: true
-      stages:
-        - name: 安装依赖
-          script: npm install
-        - name: TypeScript 类型检查
-          script: npx tsc --noEmit
-
-# ── feat/fix 分支 push：内网发布 dev 版本 ──
-(feat|fix)/**:
-  push:
-    - docker:
-        image: node:24
-      runner:
-        network: devnet
-      stages:
-        - name: 安装依赖
-          script: npm install
-        - name: 构建项目
-          script: npm run build
-        - name: 设置测试包名
-          script: npm run ci:prepare-test-pkg
-        - name: 设置测试版本
-          script: npm version "0.0.0-dev.${ORANGE_COMMIT_SHORT}" --no-git-tag-version
-        - name: 发布 npm 包
-          image: tencentcom/npm:latest
-          imports: https://git.woa.com/qq-ai/web/secret/blob/master/envs/npm/public.txt
-          settings:
-            username: $USER
-            password: $PWD
-            email: $EMAIL
-            registry: https://mirrors.tencent.com/npm/
-            folder: ./
-            tag: dev
+include:
+  - https://git.woa.com/qq-ai/web/secret/blob/master/ci/tencent-connect/dsh-qqbot.yml

package/CHANGELOG.md

@@ -1,9 +1,65 @@
 # Changelog
 
+> [English](./CHANGELOG_EN.md)
+
 本文件从产品视角记录 dsh-qqbot 的重要更新，聚焦用户可感知的变化。
 
 格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)。
 
+## [0.5.1] - 2026-10-12
+
+### 新功能
+
+- **端内扫码绑定**：在 DSH 桌面版 / Web 的设置页「QQ 机器人」栏目即可完成绑定——手机 QQ 扫码或手动填写 AppID / AppSecret，绑定状态实时可见；未绑定时侧栏会自动打开引导页。支持一键更换凭据与解绑。
+- **端内配置面板**：常用配置告别手改文件——私聊 / 群聊访问控制（开放、白名单、停用）、群聊是否需要 @机器人、流式输出、工具结果展示、模型覆盖与补充指令，保存后自动生效。
+
+### 体验优化
+
+- **升级 QQ Bot SDK 至 1.0.5**：机器人掉线时日志会说明掉线原因以及是否会自动恢复；连接始终无法建立时快速失败并给出明确原因，不再一直等待。
+
+## [0.5.0] - 2026-09-08
+
+### 新功能
+
+- **图片理解**：发送图片给机器人，它会自动理解图片内容（截图、照片、图表等），可结合文字指令一起分析。
+- **发送文件**：机器人可将本地文件（文档、图片等）直接发送给你，不再局限于纯文字回复。
+- **主动提问**：机器人遇到不确定的信息时，会主动向你提问，并通过按钮让你一键选择，交互更顺畅。
+- **操作确认**：执行敏感或关键操作前，机器人会先发起确认，你通过「允许/拒绝」按钮即可放行或拦截。
+- **会话压缩**：新增 `/compact` 指令，一键压缩当前会话历史，保留上下文的同时释放空间，适合超长对话。
+- **预设切换**：新增 `/preset` 指令，查看或切换机器人的人格/行为预设。
+- **网络延迟检测**：`/bot-ping` 升级，返回网络传输耗时与插件处理耗时，方便排查连接延迟。
+
+### 体验优化
+
+- 长任务执行超时延长到 30 分钟，复杂任务不再中途中断。
+- 私聊与群聊按场景注入更贴合的系统提示词，回复更符合语境。
+- 主动消息推送失败时自动降级为被动回复，减少「机器人没反应」的情况。
+- 图片等媒体文件使用后自动清理，避免长期占用磁盘空间。
+
+### 问题修复
+
+- 修复 `/stop` 指令无法真正中止正在生成内容的问题（此前为无效操作）。
+- 修复操作确认通道的注册顺序问题，确保确认请求能被正确捕获和处理。
+
+### 文档
+
+- README 补充 `/preset`、`/compact` 等新增指令说明，以及扫码升级引导。
+
+## [0.4.0] - 2026-08-16
+
+### 新功能
+
+- **扫码链接**：二维码显示异常时，可直接点击终端输出的链接，在浏览器中完成扫码。
+
+### 体验优化
+
+- 支持 Windows 平台自动保存扫码凭据（此前会因路径问题失效）。
+- 凭据自动保存失败时，会明确引导手动配置，不再静默丢失已有配置。
+
+### 文档
+
+- 新增扫码示意图与升级引导。
+
 ## [0.3.0] - 2026-08-15
 
 ### 新功能

package/CHANGELOG_EN.md

@@ -0,0 +1,95 @@
+# Changelog
+
+> [简体中文](./CHANGELOG.md)
+
+This file records significant dsh-qqbot updates from a product perspective, focusing on user-visible changes.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [0.5.1] - 2026-10-12
+
+### Added
+
+- **In-app QR binding**: bind your bot entirely from the DSH Desktop / Web settings page — scan with your phone's QQ or enter the AppID / AppSecret manually, with live binding status; the sidebar opens a guided page automatically while unbound. Credential rotation and unbinding are one click away.
+- **In-app config panel**: no more hand-editing files — c2c/group access control (open, allowlist, disabled), mention-required in groups, streaming, tool-result display, model overrides and extra prompts, all applied automatically on save.
+
+### Improved
+
+- **Upgraded the QQ Bot SDK to 1.0.5**: disconnects are now logged with the reason and whether the bot will recover on its own, and a connection that can never be established fails fast with a clear reason instead of waiting forever.
+
+## [0.5.0] - 2026-09-08
+
+### Added
+
+- **Image understanding**: send images to the bot and it will automatically understand their content (screenshots, photos, charts, etc.), and can analyze them together with text instructions.
+- **File sending**: the bot can send local files (documents, images, etc.) directly to you, no longer limited to plain-text replies.
+- **Proactive questions**: when the bot encounters uncertain information, it proactively asks you questions, letting you pick an answer with a single tap for smoother interaction.
+- **Action confirmation**: before performing sensitive or critical operations, the bot requests confirmation, which you approve or block via "Allow/Deny" buttons.
+- **Session compaction**: new `/compact` command to compress the current session history in one step, preserving context while freeing space — ideal for very long conversations.
+- **Preset switching**: new `/preset` command to view or switch the bot's persona/behavior preset.
+- **Network latency test**: upgraded `/bot-ping` to return network transport time and plugin processing time, making it easier to diagnose connection latency.
+
+### Improved
+
+- Long-task execution timeout extended to 30 minutes, so complex tasks are no longer interrupted mid-way.
+- Direct and group chats now receive more context-appropriate system prompts.
+- Failed proactive message pushes automatically fall back to passive replies, reducing "the bot didn't respond" situations.
+- Media files such as images are automatically cleaned up after use, avoiding long-term disk usage.
+
+### Fixed
+
+- Fixed the `/stop` command not actually aborting in-progress generation (it was previously a no-op).
+- Fixed the registration order of the approval channel, ensuring confirmation requests are captured and handled correctly.
+
+### Documentation
+
+- README updated with the new `/preset` and `/compact` commands, plus QR-code upgrade guidance.
+
+## [0.4.0] - 2026-08-16
+
+### Added
+
+- **QR link**: when the QR code renders incorrectly, you can click the link printed in the terminal to complete scanning in a browser.
+
+### Improved
+
+- Supports auto-saving QR credentials on Windows (previously failed due to path issues).
+- When auto-saving credentials fails, it now clearly guides manual configuration instead of silently dropping existing config.
+
+### Documentation
+
+- Added QR-code screenshots and upgrade guidance.
+
+## [0.3.0] - 2026-08-15
+
+### Added
+
+- **File understanding**: send a file to the bot and it will automatically download and understand its contents, supporting extract, read, analyze, and more.
+- **Streaming replies**: replies are displayed incrementally in real time, no need to wait for full generation — a smoother, more natural experience.
+- **Visible progress**: when the bot runs tasks (running commands, reading/writing files), you can see what it is doing — no longer a "black box".
+- **Error feedback**: when a task ends abnormally, the bot clearly explains the reason, no more "half replies" or "no response at all".
+
+### Improved
+
+- Correctly displays the speaker's nickname in group chats instead of an unreadable string.
+- Automatically clears group chat history after replying to avoid cross-conversation interference.
+- Voice messages are recognized and kept as text only, without extra invalid links.
+- The bot now "actually gets things done": for requests like "download, extract, install", it executes real tool actions instead of just restating the steps.
+
+### Fixed
+
+- Fixed the bot being unable to read/write files (the working directory was misconfigured).
+- Fixed duplicate content and too-few chunks in streaming replies.
+
+## [0.1.0] - 2026-08-14
+
+### Added
+
+- **First release**: QQ bot integrated with an AI assistant, supporting direct and group chats.
+- **Model switching**: supports switching between different AI models.
+- **Common commands**: built-in help, status query, session management, and more.
+- **QR binding**: bind the bot by scanning a QR code on first use, with simple setup.
+
+### Fixed
+
+- Fixed config parsing issues.

package/README.md

@@ -1,13 +1,33 @@
-# @tencent-connect/dsh-qqbot
+<div align="center">
 
-基于 [deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) 的 QQ Bot IM 插件，将 QQ 消息平台作为 dsh agent 的前端协议驱动。
+<img width="120" src="https://img.shields.io/badge/🤖-QQ_Bot-blue?style=for-the-badge" alt="QQ Bot" />
 
-中文 | [English](./README_EN.md)
+**基于 [deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) 的 QQ Bot 插件，将 DeepSeek AI 助手接入 QQ 私聊与群聊。**
+
+[![npm version](https://img.shields.io/npm/v/@tencent-connect/dsh-qqbot)](https://www.npmjs.com/package/@tencent-connect/dsh-qqbot)
+[![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/tencent-connect/dsh-qqbot)](https://github.com/tencent-connect/dsh-qqbot)
+[![QQ Bot](https://img.shields.io/badge/QQ_Bot-API_v2-red)](https://bot.q.qq.com/wiki/)
+
+<br/>
+
+**[English](./README_EN.md) | 简体中文**
+
+扫码加入 QQ 群 / 频道
+
+<table>
+<tr>
+<td align="center" width="50%"><img src="./docs/assets/qqgroup.jpg" height="360" alt="QQ 群二维码" /><br /><b>QQ 开发者交流群</b><br /><sub>群号: 1032635674</sub></td>
+<td align="center" width="50%"><img src="./docs/assets/qqchannel.jpg" height="360" alt="QQ 频道二维码" /><br /><b>QQ 开发者社区频道</b><br /><sub>频道号: 20dnumts4z</sub></td>
+</tr>
+</table>
+
+</div>
 
 ## 架构
 
 ```
-QQ 用户 → QQ WebSocket → dsh-im-qqbot → ctx.agents → dsh agent loop → LLM
+QQ 用户 → QQ WebSocket → dsh-qqbot → ctx.agents → dsh agent loop → LLM
                                  ↑                           │
                                  └── session/event ──────────┘
                                        (assistant reply → QQ sendMarkdown)
@@ -19,14 +39,20 @@ QQ 用户 → QQ WebSocket → dsh-im-qqbot → ctx.agents → dsh agent loop
 
 ```bash
 # 安装到 profile
-dsh plugin --profile qqbot add @tencent-connect/dsh-qqbot
+npx @deepseek-ai/dsh plugin --profile qqbot add @tencent-connect/dsh-qqbot
 
 # 启动
-dsh --profile qqbot
+npx @deepseek-ai/dsh --profile qqbot
 ```
 
 首次启动时，插件检测到凭据未配置会自动进入扫码引导：终端输出二维码 → 手机 QQ 扫码绑定 → 凭据自动保存到 profile，后续启动无需再次扫码。
 
+DSH **桌面版 / Web** 下会自动打开应用内「QQ Bot 绑定」页（右侧边栏），端内渲染二维码并实时展示绑定状态，扫码成功后自动完成保存与插件重载；CLI 模式保持终端二维码引导。设置 `QQBOT_BIND_OPEN_BROWSER=1` 可在无端内页的环境额外拉起系统浏览器扫码页作为降级通道。
+
+<img src="./docs/assets/qrcode.png" alt="二维码扫码示意图" width="280" />
+
+> **提示**：建议升级至 `0.4.0` 以上版本扫码，支持点击链接在浏览器打开，避免部分终端二维码渲染错位的问题。
+
 ### 方式二：本地路径安装
 
 ```bash
@@ -35,19 +61,18 @@ cd /path/to/dsh-qqbot
 pnpm install && pnpm build
 
 # 安装到 profile（本地路径）
-dsh plugin --profile qqbot add /path/to/dsh-qqbot
+npx @deepseek-ai/dsh plugin --profile qqbot add /path/to/dsh-qqbot
 
 # 启动
 export QQBOT_APPID="你的AppID" QQBOT_SECRET="你的AppSecret"
-dsh --profile qqbot
+npx @deepseek-ai/dsh --profile qqbot
 ```
 
 ### 方式三：--patch 开发模式
 
 ```bash
-cd /path/to/deepseek-harness
 export QQBOT_APPID="你的AppID" QQBOT_SECRET="你的AppSecret"
-pnpm dsh web --patch /path/to/dsh-qqbot/cordis.dev.yml
+npx @deepseek-ai/dsh web --patch /path/to/dsh-qqbot/cordis.dev.yml
 ```
 
 ## 配置项
@@ -64,15 +89,61 @@ pnpm dsh web --patch /path/to/dsh-qqbot/cordis.dev.yml
 | `groupPrompt` | string | - | 群聊额外 system prompt |
 | `directPrompt` | string | - | 私聊额外 system prompt |
 | `textChunkLimit` | number | `4500` | 单条消息最大字符数 |
+| `streaming` | boolean | `true` | 是否启用流式输出（群聊始终不启用） |
 | `sessionIdleTimeout` | number | `1800000` | 会话闲置超时(ms)，默认 30 分钟 |
+| `processingTimeoutMs` | number | `1800000` | 处理超时(ms)，超时中断当前 LLM 调用 |
+| `maxQueue` | number | `20` | 并发队列最大长度 |
+| `historyLimit` | number | `10` | 群历史缓冲条数 |
+| `askTimeoutMs` | number | `300000` | 待答问题超时(ms)，默认 5 分钟（ask_user_question） |
+| `showToolResults` | boolean | `false` | 是否展示工具调用成功结果（错误始终展示） |
 | `debug` | boolean | `false` | 调试模式 |
 
+### 访问控制（access）
+
+| 配置 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `access.c2cMode` | `open`/`allowlist`/`disabled` | `open` | 私聊访问模式 |
+| `access.c2cAllow` | string[] | `[]` | 私聊白名单（user openid） |
+| `access.groupMode` | `open`/`allowlist`/`disabled` | `open` | 群聊访问模式 |
+| `access.groupAllow` | string[] | `[]` | 群聊白名单（group openid） |
+
+### 富媒体理解（media）
+
+| 配置 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `media.enabled` | boolean | `true` | 是否启用富媒体理解（图片/视频下载 + 工具分析） |
+| `media.maxMB` | number | `200` | 富媒体下载大小上限(MB) |
+| `media.ttlHours` | number | `24` | 富媒体存活时长(小时)，0=永不过期 |
+
+### 视觉理解（vision）
+
+| 配置 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `vision.enabled` | boolean | `false` | 是否启用视觉理解（qqbot_describe_image 工具） |
+| `vision.provider` | string | - | 视觉模型 provider（如 pi-ai） |
+| `vision.model` | string | - | 视觉模型 id（如 qwen-vl-max） |
+| `vision.maxBytes` | number | `10MB` | 图片字节上限 |
+| `vision.maxTokens` | number | `1024` | 输出 token 上限 |
+| `vision.timeoutMs` | number | `120000` | 视觉调用超时(ms) |
+
+### 附件发送（sendFile）
+
+| 配置 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `sendFile.restrictPaths` | boolean | `true` | 是否启用路径白名单（仅 media + cwd + extraRoots） |
+| `sendFile.extraRoots` | string[] | `[]` | 额外允许访问的根目录 |
+
 ## 内置命令
 
 | 命令 | 说明 |
 |------|------|
-| `/bot-reset` | 重置当前会话（清除上下文） |
-| `/bot-model` | 查看或切换模型 |
+| `/new`（别名 `/reset` `/clear`） | 开始新会话（清空上下文） |
+| `/compact` | 压缩会话历史（摘要替换旧记录，保留上下文） |
+| `/model` | 查看或切换模型 |
+| `/preset` | 查看或切换 agent preset（新会话生效） |
+| `/stop` | 中止当前生成 |
+| `/bot-ping` | 网络延迟检测（返回传输与处理耗时） |
+| `/bot-version` | 查看版本信息 |
 | `/bot-status` | 查看当前会话状态 |
 | `/bot-help` | 查看所有指令 |
 
@@ -83,11 +154,28 @@ src/
 ├── index.ts                    # Cordis 插件入口（async apply）
 ├── config.ts                   # 配置 Schema
 ├── types.ts                    # 全局类型定义
-├── setup.ts                    # 凭据绑定（扫码）
+├── setup/                      # 凭据绑定（扫码）
+│   ├── index.ts                # 绑定编排（ensureCredentials）
+│   ├── binding-service.ts      # 扫码状态机（宿主内唯一事实源）
+│   ├── bind-routes.ts          # 端内绑定页路由（/qqbot/im-qqbot/bind）
+│   ├── presenters.ts           # 呈现策略（终端/浏览器降级）
+│   ├── qr-svg.ts               # 二维码 SVG 渲染（宿主侧）
+│   └── persist.ts              # 凭据写入 cordis.patch.yml
+├── client/                     # 浏览器半边（dsh.client Web Bundle）
+│   ├── index.ts                # 侧栏 Tab 注册 + 待绑定自动引导
+│   └── bind-page.ts             # 端内绑定页（二维码 + 状态轮询）
+├── gateway/                    # 网关装配
+│   ├── bootstrap.ts            # 启动装配（监听 session/event 等）
+│   └── middleware-setup.ts     # 中间件链配置
 ├── transport/                  # 传输层
 │   ├── inbound.ts              # QQ 入站消息 → agent.followup()
 │   ├── outbound.ts             # session/event → QQ sendMarkdown
 │   ├── outbound-buffer.ts      # 流式缓冲
+│   ├── streaming-writer.ts     # 流式写入
+│   ├── reply-target.ts         # 回复目标解析
+│   ├── msgid-cache.ts          # 被动回复 msgid 缓存
+│   ├── reply-limiter.ts        # 被动回复限流
+│   ├── tool-presenter.ts       # 工具调用展示
 │   └── chunker.ts              # Markdown 文本切分
 ├── session/                    # 会话管理层
 │   ├── session-manager.ts      # QQ peer → Agent 映射
@@ -96,12 +184,22 @@ src/
 │   ├── model-resolver.ts       # 路由解析
 │   ├── prefs-store.ts          # per-peer 偏好持久化
 │   └── settings-reader.ts      # settings.yaml 只读
+├── features/                   # 交互特性
+│   ├── question-channel.ts     # ask_user_question 问答通道
+│   ├── approval-channel.ts     # approval 审批确认通道
+│   └── answer-parser.ts        # 答案解析
+├── media/                      # 多媒体
+│   ├── vision-tool.ts          # 图片视觉理解
+│   ├── send-file-tool.ts       # 发送本地文件
+│   └── media-cleaner.ts        # 媒体 TTL 清理
+├── middleware/                 # 中间件
+│   ├── question-answer.ts      # 问答答案处理
+│   └── attachment.ts           # 附件处理
 ├── shared/                     # 共享工具
 │   ├── utils.ts                # 通用函数
 │   ├── scope.ts                # scope/peer 提取
 │   └── send-helper.ts          # 分块发送
-├── commands/                   # 斜杠命令
-└── typings/                    # 外部模块声明
+└── commands/                   # 斜杠命令
 ```
 
 ## 会话路由
@@ -118,6 +216,10 @@ sessionKey: `qqbot:${appId}:${scope}:${peerId}`，由 SHA-256 确定性派生 Se
 - **Preset 支持** — 可通过 `agent-presets` 服务挂载预设（工具集、prompt 等）
 - **闲置回收** — 超时自动 dispose Agent，防止内存泄漏
 - **Markdown 输出** — 回复以 Markdown 格式发送，支持代码块/表格感知切分
+- **图片理解** — 支持 `qqbot_describe_image` 视觉理解，可分析用户发送的图片
+- **附件发送** — 支持 `qqbot_send_file` 将本地文件发送给用户（默认启用路径白名单）
+- **问答互动** — 支持 `ask_user_question`，单选生成内联按钮（点一个其余变灰）、多选回复编号，逐题推进 + 问题级超时
+- **操作确认** — 支持 `approval/request`，关键操作通过「允许/拒绝」按钮请求用户确认
 
 ## 本地开发
 
@@ -131,10 +233,9 @@ pnpm build
 # 开发模式（watch）
 pnpm dev
 
-# 用 --patch 方式调试（在 dsh monorepo 中）
-cd /path/to/deepseek-harness
+# 用 --patch 方式调试
 export QQBOT_APPID="xxx" QQBOT_SECRET="xxx"
-pnpm dsh web --patch /path/to/dsh-qqbot/cordis.dev.yml
+npx @deepseek-ai/dsh web --patch /path/to/dsh-qqbot/cordis.dev.yml
 ```
 
 ## License

package/README_EN.md

@@ -1,13 +1,33 @@
-# @tencent-connect/dsh-qqbot
+<div align="center">
 
-A QQ Bot IM plugin for [deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) (dsh), driving the dsh agent loop with the QQ messaging platform as the frontend protocol.
+<img width="120" src="https://img.shields.io/badge/🤖-QQ_Bot-blue?style=for-the-badge" alt="QQ Bot" />
 
-[中文文档](./README.md) | English
+**A QQ Bot plugin for [deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) (dsh), connecting DeepSeek AI assistants to QQ private and group chats.**
+
+[![npm version](https://img.shields.io/npm/v/@tencent-connect/dsh-qqbot)](https://www.npmjs.com/package/@tencent-connect/dsh-qqbot)
+[![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/tencent-connect/dsh-qqbot)](https://github.com/tencent-connect/dsh-qqbot)
+[![QQ Bot](https://img.shields.io/badge/QQ_Bot-API_v2-red)](https://bot.q.qq.com/wiki/)
+
+<br/>
+
+**[简体中文](./README.md) | English**
+
+Scan to join the QQ group / channel
+
+<table>
+<tr>
+<td align="center" width="50%"><img src="./docs/assets/qqgroup.jpg" height="360" alt="QQ Group QR Code" /><br /><b>QQ Developer Group</b><br /><sub>Group ID: 1032635674</sub></td>
+<td align="center" width="50%"><img src="./docs/assets/qqchannel.jpg" height="360" alt="QQ Channel QR Code" /><br /><b>QQ Developer Channel</b><br /><sub>Channel ID: 20dnumts4z</sub></td>
+</tr>
+</table>
+
+</div>
 
 ## Architecture
 
 ```
-QQ User → QQ WebSocket → dsh-im-qqbot → ctx.agents → dsh agent loop → LLM
+QQ User → QQ WebSocket → dsh-qqbot → ctx.agents → dsh agent loop → LLM
                                  ↑                           │
                                  └── session/event ──────────┘
                                        (assistant reply → QQ sendMarkdown)
@@ -19,14 +39,18 @@ QQ User → QQ WebSocket → dsh-im-qqbot → ctx.agents → dsh agent loop →
 
 ```bash
 # Add to a profile
-dsh plugin --profile qqbot add @tencent-connect/dsh-qqbot
+npx @deepseek-ai/dsh plugin --profile qqbot add @tencent-connect/dsh-qqbot
 
 # Start
-dsh --profile qqbot
+npx @deepseek-ai/dsh --profile qqbot
 ```
 
 On first launch, the plugin detects missing credentials and automatically starts the QR flow: a QR code is printed in the terminal → scan it with the QQ mobile app → credentials are saved to the profile, so subsequent launches require no re-scan.
 
+<img src="./docs/assets/qrcode.png" alt="QR code scan example" width="280" />
+
+> **Note**: Upgrade to `0.4.0` or later for browser-link scanning, which avoids QR code misalignment in some terminals.
+
 ### Method 2: Local path
 
 ```bash
@@ -35,19 +59,18 @@ cd /path/to/dsh-qqbot
 pnpm install && pnpm build
 
 # Add to a profile (local path)
-dsh plugin --profile qqbot add /path/to/dsh-qqbot
+npx @deepseek-ai/dsh plugin --profile qqbot add /path/to/dsh-qqbot
 
 # Start
 export QQBOT_APPID="yourAppID" QQBOT_SECRET="yourAppSecret"
-dsh --profile qqbot
+npx @deepseek-ai/dsh --profile qqbot
 ```
 
 ### Method 3: --patch dev mode
 
 ```bash
-cd /path/to/deepseek-harness
 export QQBOT_APPID="yourAppID" QQBOT_SECRET="yourAppSecret"
-pnpm dsh web --patch /path/to/dsh-qqbot/cordis.dev.yml
+npx @deepseek-ai/dsh web --patch /path/to/dsh-qqbot/cordis.dev.yml
 ```
 
 ## Configuration
@@ -64,15 +87,61 @@ pnpm dsh web --patch /path/to/dsh-qqbot/cordis.dev.yml
 | `groupPrompt` | string | - | Extra system prompt for group chats |
 | `directPrompt` | string | - | Extra system prompt for direct chats |
 | `textChunkLimit` | number | `4500` | Max chars per message |
+| `streaming` | boolean | `true` | Enable streaming output (always disabled in groups) |
 | `sessionIdleTimeout` | number | `1800000` | Session idle timeout (ms), default 30 min |
+| `processingTimeoutMs` | number | `1800000` | Processing timeout (ms), aborts the current LLM call |
+| `maxQueue` | number | `20` | Max concurrent queue length |
+| `historyLimit` | number | `10` | Group history buffer size |
+| `askTimeoutMs` | number | `300000` | Question timeout (ms), default 5 min (ask_user_question) |
+| `showToolResults` | boolean | `false` | Show successful tool-call results (errors always shown) |
 | `debug` | boolean | `false` | Debug mode |
 
+### Access control (access)
+
+| Config | Type | Default | Description |
+|------|------|--------|------|
+| `access.c2cMode` | `open`/`allowlist`/`disabled` | `open` | Direct-chat access mode |
+| `access.c2cAllow` | string[] | `[]` | Direct-chat allowlist (user openid) |
+| `access.groupMode` | `open`/`allowlist`/`disabled` | `open` | Group access mode |
+| `access.groupAllow` | string[] | `[]` | Group allowlist (group openid) |
+
+### Rich media (media)
+
+| Config | Type | Default | Description |
+|------|------|--------|------|
+| `media.enabled` | boolean | `true` | Enable rich media understanding (image/video download + tool analysis) |
+| `media.maxMB` | number | `200` | Max download size (MB) |
+| `media.ttlHours` | number | `24` | Media lifetime (hours), 0 = never expire |
+
+### Vision (vision)
+
+| Config | Type | Default | Description |
+|------|------|--------|------|
+| `vision.enabled` | boolean | `false` | Enable vision (qqbot_describe_image tool) |
+| `vision.provider` | string | - | Vision model provider (e.g. pi-ai) |
+| `vision.model` | string | - | Vision model id (e.g. qwen-vl-max) |
+| `vision.maxBytes` | number | `10MB` | Max image bytes |
+| `vision.maxTokens` | number | `1024` | Max output tokens |
+| `vision.timeoutMs` | number | `120000` | Vision call timeout (ms) |
+
+### File sending (sendFile)
+
+| Config | Type | Default | Description |
+|------|------|--------|------|
+| `sendFile.restrictPaths` | boolean | `true` | Enable path allowlist (media + cwd + extraRoots only) |
+| `sendFile.extraRoots` | string[] | `[]` | Extra allowed root directories |
+
 ## Built-in Commands
 
 | Command | Description |
 |------|------|
-| `/bot-reset` | Reset the current session (clear context) |
-| `/bot-model` | View or switch model |
+| `/new` (aliases `/reset` `/clear`) | Start a new session (clear context) |
+| `/compact` | Compact session history (replace old records with a summary) |
+| `/model` | View or switch model |
+| `/preset` | View or switch agent preset (applies to new sessions) |
+| `/stop` | Abort the current generation |
+| `/bot-ping` | Network latency test (transport & processing time) |
+| `/bot-version` | View version info |
 | `/bot-status` | View current session status |
 | `/bot-help` | View all commands |
 
@@ -84,10 +153,18 @@ src/
 ├── config.ts                   # Config schema
 ├── types.ts                    # Global types
 ├── setup.ts                    # Credential binding (QR)
+├── gateway/                    # Gateway assembly
+│   ├── bootstrap.ts            # Startup wiring (session/event listeners, etc.)
+│   └── middleware-setup.ts     # Middleware chain config
 ├── transport/                  # Transport layer
 │   ├── inbound.ts              # QQ inbound message → agent.followup()
 │   ├── outbound.ts             # session/event → QQ sendMarkdown
 │   ├── outbound-buffer.ts      # Streaming buffer
+│   ├── streaming-writer.ts     # Streaming writer
+│   ├── reply-target.ts         # Reply target resolution
+│   ├── msgid-cache.ts          # Passive reply msgid cache
+│   ├── reply-limiter.ts        # Passive reply rate limiter
+│   ├── tool-presenter.ts       # Tool-call presentation
 │   └── chunker.ts              # Markdown chunking
 ├── session/                    # Session management
 │   ├── session-manager.ts      # QQ peer → Agent mapping
@@ -96,12 +173,22 @@ src/
 │   ├── model-resolver.ts       # Route resolution
 │   ├── prefs-store.ts          # Per-peer preference persistence
 │   └── settings-reader.ts      # settings.yaml read-only
+├── features/                   # Interaction features
+│   ├── question-channel.ts     # ask_user_question Q&A channel
+│   ├── approval-channel.ts     # approval confirmation channel
+│   └── answer-parser.ts        # Answer parsing
+├── media/                      # Media
+│   ├── vision-tool.ts          # Image vision understanding
+│   ├── send-file-tool.ts       # Send local files
+│   └── media-cleaner.ts        # Media TTL cleanup
+├── middleware/                 # Middleware
+│   ├── question-answer.ts      # Q&A answer handling
+│   └── attachment.ts           # Attachment handling
 ├── shared/                     # Shared utilities
 │   ├── utils.ts                # Common helpers
 │   ├── scope.ts                # scope/peer extraction
 │   └── send-helper.ts          # Chunked send
-├── commands/                   # Slash commands
-└── typings/                    # External module declarations
+└── commands/                   # Slash commands
 ```
 
 ## Session Routing
@@ -118,6 +205,10 @@ Resolution strategy: in-process reuse → persisted resume → fresh create.
 - **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
+- **Image understanding** — supports `qqbot_describe_image` vision to analyze images sent by users
+- **File sending** — supports `qqbot_send_file` to send local files to users (path allowlist enabled by default)
+- **Question interaction** — supports `ask_user_question` with inline keyboard buttons (mutually exclusive) or numbered replies, one question at a time with timeout
+- **Approval confirmation** — supports `approval/request` to ask for user confirmation on critical actions via allow/deny buttons
 
 ## Local Development
 
@@ -131,10 +222,9 @@ pnpm build
 # Dev mode (watch)
 pnpm dev
 
-# Debug via --patch (inside the dsh monorepo)
-cd /path/to/deepseek-harness
+# Debug via --patch
 export QQBOT_APPID="xxx" QQBOT_SECRET="xxx"
-pnpm dsh web --patch /path/to/dsh-qqbot/cordis.dev.yml
+npx @deepseek-ai/dsh web --patch /path/to/dsh-qqbot/cordis.dev.yml
 ```
 
 ## License