@wenbin_wb/dsh-bridge 2.2.3 → 2.2.5

package/README.md

@@ -1,6 +1,6 @@
 # dsh-bridge
 
-[中文文档](README.zh-CN.md)
+English | [简体中文](README.zh-CN.md)
 
 ![dsh-bridge banner](docs/banner.jpg)
 
@@ -73,12 +73,21 @@ npm install -g @deepseek-ai/dsh
 
 ## Installation
 
-### From npm
+### From npm (Recommended)
 
 ```bash
+# Install latest version
 dsh plugin --profile web add @wenbin_wb/dsh-bridge
+
+# Or specify version (e.g. 2.2.4)
+dsh plugin --profile web add @wenbin_wb/dsh-bridge@2.2.4
 ```
 
+> 💡 **No global install permission?** Use `npx`:
+> ```bash
+> npx --yes @deepseek-ai/dsh plugin --profile web add @wenbin_wb/dsh-bridge
+> ```
+
 ### From source
 
 ```bash
@@ -91,7 +100,10 @@ After installation, restart DSH and find "Remote Access" in settings.
 ### Upgrade to latest
 
 ```bash
+# Force install latest version (recommended)
 dsh plugin --profile web add @wenbin_wb/dsh-bridge@latest
+
+# Or copy the upgrade command from DSH Web Settings → "Remote Access" → "Version Check"
 ```
 
 > **Note**: `update --latest` may fail to reach the newest major version due to version constraints from already-installed dependencies. Use the `add @latest` command above to force-install the latest version (no need to know the exact version number).
@@ -103,7 +115,7 @@ If you upgrade right after a release, `add @latest` may still install an older v
 **Solutions** (pick one):
 
 1. **Add `minimumReleaseAge: 0` to your profile's `pnpm-workspace.yaml`**, then run `pnpm install` (recommended, permanent)
-2. **Specify the exact version**: `dsh plugin --profile web add @wenbin_wb/dsh-bridge@2.0.2` (works immediately, no waiting)
+2. **Copy the versioned upgrade command from DSH Web Settings → "Remote Access" → "Version Check"** (works immediately, no waiting)
 3. **Wait 24 hours**: the protection lifts automatically after 1 day
 
 After upgrading, restart DSH and **hard-refresh** the browser (Windows: `Ctrl+Shift+R`, macOS: `Cmd+Shift+R`) to clear the cache, then confirm the latest version is shown in settings.
@@ -116,6 +128,8 @@ After upgrading, restart DSH and **hard-refresh** the browser (Windows: `Ctrl+Sh
 
 Automatically enabled after plugin starts, no configuration needed. Open Settings → "Remote Access", scan the QR code with your mobile device.
 
+![QR Code Access](docs/screenshots/qr-scan.jpg)
+
 ### Cloudflare Tunnel
 
 1. Click "Enable" in the Cloudflare Tunnel card
@@ -137,6 +151,8 @@ Config is auto-persisted to `~/.dsh/dsh-bridge/config.json`, no need to re-enter
 
 Built on Tencent's official WeChat ClawBot feature (iLink Bot API). Scan a QR code to log in a WeChat personal account, then chat with, control, and approve your DeepSeek Harness agents directly in WeChat — all through Tencent's official servers, no public server or tunnel required.
 
+![WeChat Chat Example](docs/screenshots/wechat-chat.jpg)
+
 **Highlights**
 
 - 🗂️ **Multi-workspace**: `/workspaces` to list workspaces; `@N` or `@path` to create sessions in a specific project directory
@@ -158,12 +174,13 @@ Built on Tencent's official WeChat ClawBot feature (iLink Bot API). Scan a QR co
 | Command | What it does |
 |---------|--------------|
 | *(plain text)* | Routes to the active agent |
-| `/sessions` | List sessions (grouped by workspace, with titles) |
-| `/use N` | Switch to session N |
+| `/sessions` (or `/list`) | List sessions (grouped by workspace, with titles) |
+| `/use N` (or `/resume N`) | Switch to session N |
 | `/workspaces` | List available workspaces |
 | `/new <prompt>` | Create a fresh session and start (current workspace) |
 | `/new <prompt> @N` (or `@path`) | Create a session in a specific workspace |
 | `/stop` | Cancel the active turn |
+| `/end` | End current session |
 | `/status` | Agent status + session summary |
 | `/yes` `/no` (or `1`/`2`) | Answer a permission request |
 | `/start` | Auto-start a session after first scan |
@@ -180,12 +197,59 @@ Built on Tencent's official WeChat ClawBot feature (iLink Bot API). Scan a QR co
 
 ---
 
+## QQ Bot (OpenAPI v2)
+
+Connect your official QQ Bot for private/group chat (@mention in groups), streaming output, Markdown rendering, message buttons, and rich media (images/files). Built on Tencent's official QQ Bot OpenAPI v2, WebSocket real-time push, auto token refresh, auto-reconnect.
+
+![QQ Private Chat](docs/screenshots/qq-chat.jpg)
+
+![QQ Group Chat](docs/screenshots/qq-group.jpg)
+
+**Highlights**
+
+- 💬 **Private + Group Chat**: direct message for private chat, @mention to trigger in groups (first @mention auto-authorizes the group)
+- 📝 **Streaming Markdown**: real-time streaming output, code highlighting, tables, lists fully rendered
+- 🎯 **Message Buttons**: /end and other commands trigger quick buttons (new session/list/help), requires latest QQ client
+- 🖼️ **Rich Media**: send/receive images and files
+- 🔄 **Session Management**: multi-session switching, persistence, grouped by workspace
+- ✅ **Auto Authorization**: first message in private chat, first @mention in group auto-adds to allowlist
+
+**Usage**
+
+1. Go to [QQ Open Platform](https://q.qq.com) to create a bot app, get AppID and ClientSecret
+2. Open Settings → "Remote Access" → "IM Bots" → select "QQ"
+3. Fill in AppID and ClientSecret, click "Save Config" to auto-connect
+4. **Private Chat**: add bot as friend, send first message to auto-authorize
+5. **Group Chat**: invite bot to group, @mention bot to send message (first @mention auto-authorizes the group)
+
+**Commands in QQ** (full details in [QQ Bot Guide](docs/qq-usage.md))
+
+| Command | What it does |
+|---------|--------------|
+| *(plain text)* | Routes to the active agent |
+| `/new <prompt>` | Create new session and start |
+| `/sessions` (or `/list`) | List sessions (grouped by workspace) |
+| `/use N` (or `/resume N`) | Switch to session N |
+| `/end` | End current session (triggers quick buttons) |
+| `/stop` | Stop current task |
+| `/status` | View agent status |
+| `/workspaces` | List available workspaces |
+| `/help` | View all commands |
+
+**Important Notes**
+
+- **Custom menus / command panels / message buttons require latest QQ client** (2026-08-12 new feature, mobile version priority support)
+- API config success but client not showing is normal — update QQ to latest version and try again, or wait for official gradual rollout
+- Plain text commands (like `/new` `/sessions` `/help`) work on any version
+
+---
+
 ## Optional Configuration
 
 Plugin works out-of-the-box, no configuration needed. To change proxy port, add to cordis.yml:
 
 ```yaml
-- name: dsh-bridge
+- name: '@wenbin_wb/dsh-bridge'
   config:
     port: 3082  # Default 3082
 ```

package/README.zh-CN.md

@@ -1,6 +1,6 @@
 # dsh-bridge
 
-[English](README.md)
+[English](README.md) | 简体中文
 
 ![dsh-bridge banner](docs/banner.jpg)
 
@@ -73,12 +73,21 @@ npm install -g @deepseek-ai/dsh
 
 ## 安装
 
-### 从 npm 安装
+### 从 npm 安装（推荐）
 
 ```bash
+# 安装最新版
 dsh plugin --profile web add @wenbin_wb/dsh-bridge
+
+# 或指定版本（如 2.2.4）
+dsh plugin --profile web add @wenbin_wb/dsh-bridge@2.2.4
 ```
 
+> 💡 **没有全局安装权限？** 使用 `npx` 方式：
+> ```bash
+> npx --yes @deepseek-ai/dsh plugin --profile web add @wenbin_wb/dsh-bridge
+> ```
+
 ### 从源码安装
 
 ```bash
@@ -91,7 +100,10 @@ dsh plugin --profile web add ./dsh-bridge
 ### 升级到最新版
 
 ```bash
+# 强制安装最新版（推荐）
 dsh plugin --profile web add @wenbin_wb/dsh-bridge@latest
+
+# 或在 DSH Web 设置页的「远程访问」→「版本检查」中一键复制升级命令
 ```
 
 > **注意**：`update --latest` 可能因已安装依赖的版本约束而无法升级到最新版。用上面的 `add @latest` 命令即可强制安装最新版（无需知道具体版本号）。
@@ -103,7 +115,7 @@ dsh plugin --profile web add @wenbin_wb/dsh-bridge@latest
 **解决方法**（任选其一）：
 
 1. **在 profile 的 `pnpm-workspace.yaml` 添加 `minimumReleaseAge: 0`**，然后重新 `pnpm install`（推荐，一劳永逸）
-2. **显式指定版本号**：`dsh plugin --profile web add @wenbin_wb/dsh-bridge@2.0.2`（立即生效，无需等待）
+2. **在 DSH Web 设置页的「远程访问」→「版本检查」中复制带版本号的升级命令**（立即生效，无需等待）
 3. **等待 24 小时**：发布满 1 天后保护自动解除
 
 升级完成后重启 DSH，并在浏览器**硬刷新**（Windows: `Ctrl+Shift+R`，macOS: `Cmd+Shift+R`）清除缓存，然后确认设置页显示最新版本号。
@@ -116,6 +128,8 @@ dsh plugin --profile web add @wenbin_wb/dsh-bridge@latest
 
 插件启动后自动开启，无需任何配置。打开设置页「远程访问」，用手机扫描二维码即可访问。
 
+![扫码访问](docs/screenshots/qr-scan.jpg)
+
 ### Cloudflare 隧道
 
 1. 点击「Cloudflare 隧道」卡片中的「开启」按钮
@@ -137,6 +151,8 @@ dsh plugin --profile web add @wenbin_wb/dsh-bridge@latest
 
 基于腾讯官方开放的微信 ClawBot 插件功能（底层 iLink Bot API），扫码登录微信个人号后，即可在微信里直接与你的 DeepSeek Harness agent 对话、控制和审批，全程走腾讯官方服务器，无需公网与隧道。
 
+![微信对话示例](docs/screenshots/wechat-chat.jpg)
+
 **功能亮点**
 
 - 🗂️ **多工作区**：`/workspaces` 查看工作区，`@N` 或 `@路径` 指定项目目录新建会话
@@ -158,12 +174,13 @@ dsh plugin --profile web add @wenbin_wb/dsh-bridge@latest
 | 命令 | 说明 |
 |------|------|
 | *(普通文本)* | 发给当前活动 agent |
-| `/sessions` | 列出会话（按工作区分组，带标题） |
-| `/use N` | 切换到会话 N |
+| `/sessions`（或 `/list`） | 列出会话（按工作区分组，带标题） |
+| `/use N`（或 `/resume N`） | 切换到会话 N |
 | `/workspaces` | 列出可用工作区 |
 | `/new <提示词>` | 新建会话并开始（当前工作区） |
 | `/new <提示词> @N`（或 `@路径`） | 在指定工作区新建会话 |
 | `/stop` | 停止当前任务 |
+| `/end` | 结束当前会话 |
 | `/status` | 查看 agent 状态与会话摘要 |
 | `/yes` `/no`（或 `1`/`2`） | 回应权限审批请求 |
 | `/start` | 首次扫码后自动开始一个会话 |
@@ -180,12 +197,59 @@ dsh plugin --profile web add @wenbin_wb/dsh-bridge@latest
 
 ---
 
+### QQ Bot（OpenAPI v2）
+
+接入 QQ 官方机器人，支持单聊/群聊（群聊需 @机器人）、流式输出、Markdown 渲染、消息按钮、富媒体消息（图片/文件）。走腾讯官方 QQ Bot OpenAPI v2，WebSocket 实时推送，Token 自动刷新，断线自动重连。
+
+![QQ 单聊对话](docs/screenshots/qq-chat.jpg)
+
+![QQ 群聊对话](docs/screenshots/qq-group.jpg)
+
+**功能亮点**
+
+- 💬 **单聊 + 群聊**：私聊直接对话，群聊 @机器人 触发（首次 @自动授权该群）
+- 📝 **流式 Markdown**：实时流式输出，代码高亮、表格、列表完整渲染
+- 🎯 **消息按钮**：/end 等命令触发快捷按钮（新建会话/列表/帮助），需最新版 QQ 客户端
+- 🖼️ **富媒体**：图片/文件双向传输
+- 🔄 **会话管理**：多会话切换、持久化、按工作区分组
+- ✅ **自动授权**：单聊首次发消息、群聊首次 @机器人 自动加白名单
+
+**使用步骤**
+
+1. 前往 [QQ 开放平台](https://q.qq.com) 创建机器人应用，获取 AppID 和 ClientSecret
+2. 打开设置页「远程访问」→「IM 机器人」→ 选中「QQ」
+3. 填入 AppID 和 ClientSecret，点「保存配置」后自动连接
+4. **单聊**：添加机器人好友，发送第一条消息自动完成授权
+5. **群聊**：将机器人拉入群，@机器人 发送消息（首次 @自动授权该群）
+
+**QQ 里的命令**（完整说明见 [QQ Bot 使用说明](docs/qq-usage.md)）
+
+| 命令 | 说明 |
+|------|------|
+| *(普通文本)* | 发给当前活动 agent |
+| `/new <提示词>` | 新建会话并开始 |
+| `/sessions`（或 `/list`） | 列出会话（按工作区分组） |
+| `/use N`（或 `/resume N`） | 切换到/恢复会话 N |
+| `/end` | 结束当前会话（触发快捷按钮） |
+| `/stop` | 停止当前任务 |
+| `/status` | 查看 agent 状态 |
+| `/workspaces` | 列出可用工作区 |
+| `/help` | 查看全部命令 |
+
+**重要提示**
+
+- **自定义菜单 / 指令面板 / 消息按钮需要最新版 QQ 客户端**（2026-08-12 新功能，手机版优先支持）
+- API 配置成功但客户端不显示是正常现象——更新 QQ 到最新版再试，或等官方灰度全量开放
+- 纯文字命令（如 `/new` `/sessions` `/help`）在任何版本都完全可用
+
+---
+
 ## 可选配置
 
 插件开箱即用，无需配置。如需修改代理端口，在 cordis.yml 中添加：
 
 ```yaml
-- name: dsh-bridge
+- name: '@wenbin_wb/dsh-bridge'
   config:
     port: 3082  # 默认 3082
 ```