@wenbin_wb/dsh-bridge 2.3.3 → 2.5.0

package/README.en.md

@@ -14,16 +14,21 @@ Seamlessly extend your local DeepSeek Harness to mobile phones, tablets, public
 
 ## Features
 
+- **🔐 Enterprise Access Security & Admin Guard (v2.5.0 Major Release)**:
+  - **1st Line of Defense (Visitor Access Guard)**: Auto-injected 256-bit security Token in QR codes for 1-click passwordless login; manual IP/domain visits enforce password verification; granular channel scoping (All / Public Tunnels Only / LAN Only);
+  - **2nd Line of Defense (Admin Console Guard)**: Separated administrator password and visitor password; global console lockout for remote devices to prevent unauthorized configuration changes (Password Unlock / Local Host Only / Open);
+  - **Fail-safe Recovery System (Triple Protection)**: Host machine (`127.0.0.1`) enjoys permanent physical privileges (never locked out) + terminal command `touch ~/.dsh/dsh-bridge/reset-auth` for instant emergency recovery + built-in "Forgot Password" guides;
+  - **Financial-grade Security Engine**: PBKDF2 + SHA-256 salted password hashing, 30-day HttpOnly SameSite session protection, IP brute-force rate limiter (5 failed attempts trigger 60s cooldown).
 - **LAN Access**: Scan QR code with your smartphone/tablet, direct access on the same Wi-Fi — keep the conversation going from your phone
 - **Cloudflare Tunnel**: One-click public internet exposure, connect from anywhere without a public server of your own — keep working even when you're away from home
 - **Custom Tunnel**: Connect to your own tunnel server with a fixed domain ([Setup Guide](docs/custom-tunnel.md))
 - **WeChat Bot (ClawBot / iLink)**: Scan a QR code to log in a WeChat personal account, then chat with, control, and approve your DeepSeek Harness agents right inside WeChat. **Multi-workspace selection, restart-persistent sessions, grouped session listing with titles, media (image/file/voice) transfer, and permission approvals** — over Tencent's official iLink Bot API, no public server or tunnel required ([Usage Guide](docs/wechat-usage.md))
 - **QQ Bot (OpenAPI v2)**: Connect your QQ Bot to receive private/group messages, send Markdown, button keyboards, and rich media. **Full event coverage (C2C / GROUP_AT_MESSAGE_CREATE), auto token refresh, reconnection with backoff, message deduplication** — over Tencent's official QQ Bot OpenAPI v2 ([Usage Guide](docs/qq-usage.md))
 - **Feishu / Lark Bot (Official WebSocket)**: Connect enterprise self-built apps via Feishu's official WebSocket protocol. **No public IP / no Webhook required, Markdown table formatting, native interactive card permission approvals with 1-click button actions** ([Usage Guide](docs/feishu-usage.md))
+- **Telegram Bot (Official Bot API + Proxy Support)**: Connect official Telegram bots for private and group interactions. **No public IP required (Long Polling getUpdates), built-in zero-dependency HTTP/HTTPS proxy tunnel, smooth typewriter streaming output, native command menu (Menu button), and Inline Keyboard interactive approval cards** ([Usage Guide](docs/telegram-usage.md))
 - **Official Brand SVG Icons**: Authentic vector brand icons for WeChat, QQ, Feishu, Telegram with real-time status indicators
 - **Fast Version Check & 1-Click Upgrade**: Dual-channel registry check (npmmirror + npmjs fallback in ~200ms) with seamless **1-click in-app upgrade**, no terminal copying required
 - **Dark Mode Support**: Deep integration with DeepSeek Harness Design Tokens (`--dsw-alias-*`), QR code background protection for safe dark mode scanning
-- **Security Alerts**: URLs and QR codes with access warnings to prevent accidental sharing
 
 ![npm](https://img.shields.io/npm/v/@wenbin_wb/dsh-bridge?label=npm)
 ![npm downloads](https://img.shields.io/npm/dt/@wenbin_wb/dsh-bridge?label=downloads)
@@ -36,12 +41,12 @@ Seamlessly extend your local DeepSeek Harness to mobile phones, tablets, public
 
 | Target | Description | Status |
 |--------|-------------|--------|
+| **Access Security** | Visitor Access Auth Guard + Admin Console Anti-Tamper + Fail-safe Recovery | ✅ **Completed** (v2.5.0) |
+| **Telegram** | IM channel suited for self-hosting and overseas (Long Polling / Proxy / Native Menu / Inline Cards / Streaming) | ✅ **Completed** (v2.4.0) |
+| **Feishu** | Feishu / Lark official persistent WebSocket bot (No-public-IP WS / Card Approvals) | ✅ **Completed** (v2.3.0) |
+| **QQ Bot** | QQ bot integration for group/private chat (Markdown / buttons / rich media) | ✅ **Completed** (v2.1.0) |
+| **WeChat** | Chat with your Agent directly in WeChat (workspaces / persisted sessions / media / approvals) | ✅ **Completed** (v1.0.0) |
 | **Platform Abstraction** | Platform-agnostic core (sessions / approvals / commands / digest) shared across IM channels | ✅ **Completed** (v2.0.0) |
-| **WeChat** | Chat with your Agent directly in WeChat | ✅ Supported (workspaces / persisted sessions / media / approvals) |
-| **QQ Bot** | QQ bot integration for group/private chat | ✅ **Completed** (v2.1.0) — Markdown / buttons / rich media |
-| **Feishu** | Feishu / Lark official persistent WebSocket bot | ✅ **Completed** (v2.3.0) — No-public-IP WS / Card Approvals |
-| **Telegram** | IM channel suited for self-hosting and overseas | Planned |
-| **OpenClaw** | Connect with the OpenClaw ecosystem | Planned |
 
 ---
 
@@ -81,8 +86,8 @@ npm install -g @deepseek-ai/dsh
 # Install the latest version
 dsh plugin --profile web add @wenbin_wb/dsh-bridge
 
-# Or specify a version (e.g. 2.2.6)
-dsh plugin --profile web add @wenbin_wb/dsh-bridge@2.2.6
+# Or specify a version (e.g. 2.5.0)
+dsh plugin --profile web add @wenbin_wb/dsh-bridge@2.5.0
 ```
 
 > 💡 **No global install permission?** Use `npx`:
@@ -126,6 +131,39 @@ After upgrading, restart DSH, perform a **hard refresh** in your browser (Window
 
 ## Usage
 
+### 🔐 Access Security & Admin Guard (v2.5.0 Major Release)
+
+Go to Settings -> "Remote Access" -> "**Security**" tab to enable enterprise-grade protection with a single click.
+
+#### 1. 🛡️ 1st Line of Defense: Visitor Access Guard (Protects Web UI Entry)
+- **Flexible Scope Control**:
+  - `Protect All Channels`: LAN and all public tunnels require authentication;
+  - `Protect Public Tunnels Only (Recommended)`: LAN keeps zero-friction passwordless access, while public internet exposure requires authentication;
+  - `Protect LAN Only`: Enforces guard exclusively on local network.
+- **Three Verification Modes**:
+  - 🟢 **Scan QR Code Passwordless + Password Verification (Recommended)**: Console-generated QR codes automatically inject a 256-bit secure Token for instant 1-second passwordless access. Visitors manually typing IP/domain must enter the visitor access password;
+  - 🔑 **Password / PIN Only**: All external devices must manually enter the password;
+  - 🎫 **Secure Token Only**: Only devices with valid QR codes or Token links can enter.
+- **1-Click Token Rotation**: Click "🔄 Reset Security Token" to immediately invalidate all previously shared QR codes and URLs.
+
+#### 2. 🔒 2nd Line of Defense: Admin Console Anti-Tamper Guard (Protects Plugin Settings)
+- **Separated Admin Password**: Independent administrator password decoupled from visitor password; guests with access passwords cannot tamper with tunnels, bots, or tokens;
+- **Three Admin Policies**:
+  - 🔑 **Password Unlock (Recommended)**: Remote devices see a full-screen lock until the admin password is entered for a temporary session;
+  - 🛡️ **Host Computer Only (Highest Security)**: Remote devices are strictly blocked from viewing or changing network/bot/security settings — management is only allowed from the physical host (`127.0.0.1`);
+  - 🌐 **Open Mode**: Remote authenticated users can directly manage settings.
+
+#### 3. 🛟 Fail-safe Recovery System (Never Locked Out)
+- **Physical Host Privileges**: Host computer running DSH (`127.0.0.1` / `localhost`) has permanent physical privileges — **never requires access password, settings panel is never locked**;
+- **Emergency Terminal Command**: On headless Linux servers or in case of forgotten passwords, run a single command in your terminal:
+  ```bash
+  touch ~/.dsh/dsh-bridge/reset-auth
+  ```
+  The plugin instantly detects the marker, wipes all passwords and locks, deletes the marker, and restores default passwordless access;
+- **Built-in Recovery Guides**: Both visitor login pages and admin lock screens provide expandable `❓ Forgot Password?` help cards.
+
+---
+
 ### LAN Access
 
 Automatically active when the plugin starts, zero configuration needed. Open Settings -> "Remote Access", and scan the QR code with your phone.
@@ -283,6 +321,45 @@ Connect your enterprise self-built app via Feishu's official WebSocket protocol.
 
 ---
 
+### Telegram Bot (Official Bot API + Proxy Support)
+
+Connect official Telegram Bot API for real-time private and group interactions. Powered by official Long Polling (`getUpdates`), **no public IP / no Webhook required**, built-in **zero-dependency HTTP/HTTPS CONNECT proxy tunnel**, ready to use in any network environment.
+
+**Key Features**
+
+- ⚡ **100% No Public IP Needed**: Official Long Polling mechanism allows local machines or private servers to connect directly
+- 🌐 **Built-in HTTP/HTTPS Proxy Support**: Easily configure local proxies like Clash / v2ray (`http://127.0.0.1:7890`) with zero external dependencies
+- 📜 **Typewriter Streaming Output**: Integrated turn lifecycle updates existing message in-place with `editMessageText`, eliminating message fragmentation
+- 🎯 **Native Command Menu (`Menu` Button)**: Automatically registered with `setMyCommands` & `setChatMenuButton`, type `/` or tap `[Menu]` for 1-click command navigation
+- 🛡️ **Inline Keyboard Interactive Cards**: Permission approvals send `[✓ Approve]` / `[✕ Reject]` buttons for 1-second approval actions
+- 🖼️ **Multimodal & File Transfers**: Inbound images/files automatically saved and sent to Agent; generated artifacts sent back to Telegram
+- 🔄 **Session & Workspace Management**: Manage multiple sessions with `/sessions`, switch with `/use N`, view workspaces with `/workspaces`
+
+**Quick Start**
+
+1. Send `/newbot` to [@BotFather](https://t.me/BotFather) on Telegram to create your bot and obtain the **Bot Token**
+2. Open DSH Settings → "Remote Access" → "IM Bots" → select "**Telegram**"
+3. Enter your **Bot Token** (and optional proxy address like `http://127.0.0.1:7890`), click "Save and Connect"
+4. Scan the QR code with Telegram on your phone, send the first message (e.g. `/help`) to **automatically authorize your account into the allowlist**
+
+**Commands in Telegram** (Full guide in [Telegram Bot Guide](docs/telegram-usage.md))
+
+| Command | Description | Interactive Card |
+|---------|-------------|------------------|
+| *(plain text)* | Send to current active agent | Real-time typewriter stream |
+| `/new <prompt>` | Create and start a new session in current workspace | Start fresh turn |
+| `/new <prompt> @N` | Create a new session in workspace N | Multi-workspace routing |
+| `/sessions` (or `/list`) | List all sessions | 1-click switch buttons |
+| `/use N` (or `/resume N`） | Switch to/resume session N | Instant context switch |
+| `/workspaces` | List all available workspaces | View workspace paths |
+| `/status` | View agent status dashboard | Refresh/Stop/End buttons |
+| `/stop` | Stop currently executing task | Immediate abort |
+| `/end` | End current active session | Quick-start button attached |
+| `/yes` `/no` (or `1`/`2`) | Respond to permission approvals | Click inline buttons directly |
+| `/help` | Display quick buttons and help | Full navigation buttons |
+
+---
+
 ## Optional Configuration
 
 The plugin is ready to use out of the box. To customize the proxy port, add to `cordis.yml`:

package/README.md

@@ -14,16 +14,21 @@
 
 ## 功能特性
 
+- **🔐 全套访问安全认证与后台防篡改（v2.5.0 重磅）**：
+  - **第一道防线（外部访问门禁）**：二维码自带专属 Token 扫码一秒免密直入；手动输入 IP 或公网域名强制验证密码；支持「全部防护 / 仅公网 / 仅局域网」精准通道分流；
+  - **第二道防线（管理控制台防篡改）**：独立管理员密码，远程设备进入控制台全局锁定网络配置与 IM 机器人密钥，支持「需密码解锁 / 仅电脑本机管理 / 宽松直管」；
+  - **三重容灾保命体系**：电脑本机（`127.0.0.1`）永久最高物理特权（永不自锁） + 终端 `touch ~/.dsh/dsh-bridge/reset-auth` 一秒救急重置 + 全界面忘记密码求助引导；
+  - **金融级安全引擎**：PBKDF2 + SHA-256 加盐哈希安全存储、30 天 HttpOnly SameSite 会话、单 IP 连续 5 次错误封禁 60 秒防暴力破解。
 - **局域网访问**：手机/平板扫码，同一 Wi-Fi 直接访问，躺着也能在手机上接着聊
 - **Cloudflare 隧道**：一键暴露公网地址，随时随地连接，出差在外、不在家也能接着干，无需自建公网服务器
 - **自建隧道**：连接自己的隧道服务器，获得固定域名（[搭建教程](docs/custom-tunnel.md)）
 - **微信 Bot（ClawBot / iLink）**：扫码登录微信个人号后，直接在微信里对话、控制 DeepSeek Harness 的 agent。**支持多工作区选择、会话跨重启持久化、按工作区分组查看、媒体（图片/文件/语音）收发、权限审批**——走腾讯官方 iLink Bot API，无需公网（[使用说明](docs/wechat-usage.md)）
 - **QQ Bot（OpenAPI v2）**：接入 QQ 机器人，私聊/群聊接收消息，发送 Markdown、按钮键盘和富媒体。**完整事件覆盖（C2C / GROUP_AT_MESSAGE_CREATE）、Token 自动刷新、断线重连、消息去重**——走腾讯官方 QQ Bot OpenAPI v2（[使用说明](docs/qq-usage.md)）
 - **飞书 Bot（官方 WebSocket 长连接）**：接入飞书开放平台企业自建应用，私聊/群聊实时交互。**无需公网 IP / 无需 Webhook、支持飞书 Markdown 表格排版、原生交互卡片权限审批一键点击确认**——走飞书官方最新 WebSocket 长连接协议（[使用说明](docs/feishu-usage.md)）
+- **Telegram Bot（官方 Bot API + 代理支持）**：接入官方 Telegram 机器人，单聊/群聊实时交互。**无需公网 IP（长轮询 getUpdates）、内置零依赖 HTTP/HTTPS 代理隧道、打字机平滑流式输出、原生快捷指令菜单（Menu 按钮）与 Inline 交互卡片审批**（[使用说明](docs/telegram-usage.md)）
 - **IM 官方品牌矢量图标**：微信、QQ、飞书、Telegram 官方矢量图标与状态展示，直接在聊天软件里呼唤你的 Agent
 - **极速版本检查与一键升级**：国内高速镜像（npmmirror）优先 + 官方源毫秒级双通道检查，检测到新版本支持**界面一键直接升级**，无需手动打开终端
 - **深色模式深度适配**：完美适配 DeepSeek Harness 设计系统明暗主题切换，二维码自带白底安全垫，暗光下手机扫码 100% 极速识别
-- **安全提示**：URL 和二维码带访问警告，防止误分享
 
 ![npm](https://img.shields.io/npm/v/@wenbin_wb/dsh-bridge?label=npm)
 ![npm downloads](https://img.shields.io/npm/dt/@wenbin_wb/dsh-bridge?label=downloads)
@@ -36,12 +41,12 @@
 
 | 目标 | 说明 | 状态 |
 |------|------|------|
+| **访问安全认证** | 外部访问门禁拦截 + 管理后台防篡改锁 + 三重容灾保命体系 | ✅ **已完成**（v2.5.0） |
+| **Telegram** | 适合自托管与海外的 IM 渠道（免公网长轮询 / 代理支持 / 原生菜单 / Inline 卡片 / 流式打字机） | ✅ **已完成**（v2.4.0） |
+| **飞书** | 飞书开放平台长连接机器人，办公场景直接调用（免公网 WS / 卡片审批） | ✅ **已完成**（v2.3.0） |
+| **QQ Bot** | 接入 QQ 机器人，群聊/私聊唤起 Agent（Markdown / 按钮 / 富媒体） | ✅ **已完成**（v2.1.0） |
+| **微信** | 在微信里直接与你的 Agent 对话（多工作区 / 会话持久化 / 媒体 / 审批） | ✅ **已完成**（v1.0.0） |
 | **平台抽象层** | 平台无关的核心（会话/审批/命令/digest）跨 IM 渠道复用 | ✅ **已完成**（v2.0.0） |
-| **微信** | 在微信里直接与你的 Agent 对话 | ✅ 已支持（多工作区 / 会话持久化 / 媒体 / 审批） |
-| **QQ Bot** | 接入 QQ 机器人，群聊/私聊唤起 Agent | ✅ **已完成**（v2.1.0）— Markdown / 按钮 / 富媒体 |
-| **飞书** | 飞书开放平台长连接机器人，办公场景直接调用 | ✅ **已完成**（v2.3.0）— 免公网 WS / 卡片审批 |
-| **Telegram** | 适合自托管与海外的 IM 渠道 | 规划中 |
-| **OpenClaw** | 与 OpenClaw 生态打通 | 规划中 |
 
 ---
 
@@ -81,8 +86,8 @@ npm install -g @deepseek-ai/dsh
 # 安装最新版
 dsh plugin --profile web add @wenbin_wb/dsh-bridge
 
-# 或指定版本（如 2.2.6）
-dsh plugin --profile web add @wenbin_wb/dsh-bridge@2.2.6
+# 或指定版本（如 2.5.0）
+dsh plugin --profile web add @wenbin_wb/dsh-bridge@2.5.0
 ```
 
 > 💡 **没有全局安装权限？** 使用 `npx` 方式：
@@ -126,6 +131,39 @@ dsh plugin --profile web add @wenbin_wb/dsh-bridge@latest
 
 ## 使用
 
+### 🔐 访问安全认证与后台防篡改（v2.5.0 重磅）
+
+打开设置页「远程访问」→「**安全认证**」Tab 即可一键启用全方位安全守护。
+
+#### 1. 🛡️ 第一道防线：外部访问门禁（保护谁能进 Web 界面）
+- **多通道分流生效**：
+  - `全部通道开启防护`：局域网与所有公网隧道均需认证；
+  - `仅公网隧道开启防护 (推荐)`：局域网同一 Wi-Fi 内保持免密，暴露至公网的隧道强制开启认证门禁；
+  - `仅局域网开启防护`：仅对局域网进行门禁拦截。
+- **三种灵活验证模式**：
+  - 🟢 **扫码免密 + 密码认证 (默认推荐)**：控制台生成的二维码已自动注入 256-bit 专属安全 Token，手机扫码即可免密秒进；直接在浏览器手动输入 IP 或公网域名的访客，需输入您设置的访客访问密码；
+  - 🔑 **仅密码 / PIN 码**：所有外部设备一律要求输入访问密码；
+  - 🎫 **仅专属 Token 免密**：仅允许通过控制台生成的二维码或带 Token 的专属链接进入。
+- **一键轮换凭据**：点击「🔄 重置安全 Token」即可使之前分享的旧二维码和链接立即全部失效。
+
+#### 2. 🔒 第二道防线：管理后台防篡改（保护谁能改插件设置）
+- **独立管理员密码**：访客访问密码与管理控制密码彻底分离，即使将访问密码告诉外部朋友，对方也无法查看或篡改您的插件设置；
+- **三种后台权限策略**：
+  - 🔑 **需密码解锁 (默认推荐)**：远程设备进入控制台时全屏锁定，输入管理密码后解锁临时会话；
+  - 🛡️ **仅限电脑本机管理 (最高安全)**：远程设备一律禁止查看与修改任何网络、机器人配置与 Token，仅允许在电脑本机（`127.0.0.1`）操作；
+  - 🌐 **宽松模式**：允许通过访客认证的远程设备直接管理。
+
+#### 3. 🛟 三重容灾保命体系（永不自锁）
+- **物理机免密直通**：运行 DSH 的宿主电脑（`127.0.0.1` / `localhost`）享有全局最高物理特权，**永不要求输入访问密码，设置面板永不会被锁定**；
+- **服务器一键救急指令**：无头 Linux 服务器或极端忘记密码时，在宿主电脑终端执行单行命令：
+  ```bash
+  touch ~/.dsh/dsh-bridge/reset-auth
+  ```
+  插件将在毫秒级自动清空密码与策略并删除标记，瞬间恢复初始免密状态；
+- **全界面忘记密码指引**：访客登录页与锁屏页均提供 `❓ 忘记密码？` 救助展开卡片。
+
+---
+
 ### 局域网访问
 
 插件启动后自动开启，无需任何配置。打开设置页「远程访问」，用手机扫描二维码即可访问。
@@ -283,6 +321,45 @@ dsh plugin --profile web add @wenbin_wb/dsh-bridge@latest
 
 ---
 
+### Telegram Bot（官方 Bot API + 代理支持）
+
+接入 Telegram 官方 Bot API，单聊与群聊实时交互。采用官方 Long Polling（长轮询）机制，**无需公网 IP / 免 Webhook**，内置**零依赖 HTTP/HTTPS CONNECT 代理隧道**，国内网络即开即连。
+
+**功能亮点**
+
+- ⚡ **100% 免公网 IP**：官方 Long Polling 长轮询，本地电脑或内网服务器即可直连通信
+- 🌐 **内置 HTTP/HTTPS 代理支持**：支持填写本地 Clash / v2ray 代理（如 `http://127.0.0.1:7890`），零外部依赖
+- 📜 **实时打字机流式输出**：接入轮次生命周期，单条气泡原地 `editMessageText` 增量刷新，告别频繁发碎消息
+- 🎯 **原生快捷指令菜单（Menu 按钮）**：自动注册全范围指令，输入 `/` 或点击左下角 `[Menu]` 按钮一键直达常用命令
+- 🛡️ **Inline Keyboard 交互卡片**：权限审批下发 `[✓ 批准执行]` / `[✕ 拒绝执行]` 按键，一秒点击即时放行
+- 🖼️ **多模态与文件传输**：支持入站图片/文档自动转存交付 Agent，出站产物文件自动推回 Telegram
+- 🔄 **会话与工作区管理**：支持 `/sessions` 列出历史会话、`/use N` 切换、`/workspaces` 调度工作区
+
+**使用步骤**
+
+1. 在 Telegram 中向 [@BotFather](https://t.me/BotFather) 发送 `/newbot` 创建机器人并获取 **Bot Token**
+2. 打开 DSH 设置页「远程访问」→「IM 机器人」→ 选中「**Telegram**」
+3. 填入 **Bot Token**（国内网络可按需填入代理地址如 `http://127.0.0.1:7890`），点击「保存并连接」
+4. 手机 Telegram 扫码打开机器人，发送第一条消息（如 `/help`）即**自动完成白名单授权**
+
+**Telegram 里的命令**（完整说明见 [Telegram Bot 使用说明](docs/telegram-usage.md)）
+
+| 命令 | 说明 | 交互卡片 |
+|------|------|------|
+| *(普通文本)* | 发给当前活动 agent | 实时打字机流式输出 |
+| `/new <提示词>` | 在当前工作区新建会话并开始 | 立即启动新轮次 |
+| `/new <提示词> @N` | 在指定工作区新建会话 | 多工作区调度 |
+| `/sessions`（或 `/list`） | 查看所有会话列表 | 挂载一键切换按键 |
+| `/use N`（或 `/resume N`） | 切换到会话 N | 快速切换上下文 |
+| `/workspaces` | 列出可用工作区 | 查看工作区路径 |
+| `/status` | 查看 agent 状态看板 | 挂载刷新/停止/结束按键 |
+| `/stop` | 停止当前正在运行的任务 | 即刻中断执行 |
+| `/end` | 结束当前活动会话 | 挂载快捷开始按键 |
+| `/yes` `/no`（或 `1`/`2`） | 响应权限审批请求 | 支持直接点击卡片按钮 |
+| `/help` | 显示快捷按键与完整帮助 | 挂载全套功能导航按键 |
+
+---
+
 ## 可选配置
 
 插件开箱即用，无需配置。如需修改代理端口，在 cordis.yml 中添加：