@wenbin_wb/dsh-bridge 2.5.0 → 2.5.2

package/docs/wechat-bot-plan.md

@@ -0,0 +1,294 @@
+# 微信 ClawBot / iLink Bot 接入方案设计
+
+> 目标：在本插件 `dsh-bridge`（`@wenbin_wb/dsh-bridge`）的「远程访问」页面里新增一个**微信 Bot** 入口，
+> 让用户扫码登录微信个人号后，直接在微信里对话、驱动和控制本地 DSH agent（会话切换、新建、停止、审批）。
+> 底座为腾讯官方的 **iLink Bot API**（微信 ClawBot 插件功能）。方案同时预留 QQ / 飞书多平台扩展。**本轮只做方案，不写代码。**
+
+---
+
+## 一、结论先行（TL;DR）
+
+1. **iLink 是「拉取式长轮询」协议，不是「推送式回调」**。这与微信公众平台/飞书事件回调完全不同，
+   因此**完全不需要** dsh-bridge 现有的自建隧道 / Cloudflare / webhook 入口 —— 机器人像"隧道客户端"一样
+   从 DSH 所在的电脑主动连出到腾讯服务器 `ilinkai.weixin.qq.com`，天然打洞，无需公网 IP/端口。
+2. 市面上已有一个**成熟、可直接参考/复用的开源实现**：`Jesse-njx/dsh-chatnode-wechat`，它已经完整实现了
+   "微信 iLink 网关 + DSH 会话桥"，与我们的需求几乎一致。**建议在其协议实现上二次开发/精简，而非从零逆向。**
+3. 本项目 nicest 的做法：把「iLink 网关」与「DSH 会话桥」做成 dsh-bridge 内的独立模块（`lib/wechat/`），
+   网关层 Platform-agnostic，以后 QQ / 飞书只需各写一个薄网关适配器，复用同一套会话桥 / 命令 / 审批逻辑。
+4. **安全是首要约束**：强制 `allowFrom` 白名单，非白名单发件人的消息绝不喂给模型（防 prompt injection）。
+5. **风险提示（必须先对用户讲清）**：
+   - iLink 是腾讯官方开放通道，仍有内容过滤/限速/条款约束；
+   - 每条 bot token 只允许**一个** poller，与 hermes-agent / openclaw 同账号并存会互相 403 掉线；
+   - 建议用**专用微信小号**承载，避免主号被封影响日常使用。
+
+---
+
+## 二、iLink Bot API 协议速览（已调研确认）
+
+**接入域名**：`https://ilinkai.weixin.qq.com`（HTTP/JSON，无需 SDK，直接 fetch）
+**CDN**：`https://novac2c.cdn.weixin.qq.com/c2c`（媒体 AES-128-ECB 加密）
+
+### 关键 Endpoint
+
+| Endpoint | 方法 | 用途 |
+|---|---|---|
+| `/ilink/bot/get_bot_qrcode` | GET | 获取登录二维码（`?bot_type=3`） |
+| `/ilink/bot/get_qrcode_status` | GET | 轮询扫码状态，返回 `bot_token` + `baseurl` |
+| `/ilink/bot/getupdates` | POST | **长轮询收消息**（核心，hold 最多 35s） |
+| `/ilink/bot/sendmessage` | POST | 发消息（文本/图片/文件/视频/语音） |
+| `/ilink/bot/sendtyping` | POST | 显示"正在输入" |
+| `/ilink/bot/getconfig` | POST | 获取 typing_ticket（每用户缓存 24h） |
+| `/ilink/bot/getuploadurl` | POST | 媒体 CDN 预签名上传 |
+
+### 鉴权头（每个请求都带）
+
+```
+Content-Type: application/json
+AuthorizationType: ilink_bot_token
+X-WECHAT-UIN: base64(randomUint32)   # 每次随机，防重放
+iLink-App-Id: bot
+iLink-App-ClientVersion: <2.x>
+Authorization: Bearer <bot_token>     # 扫码后才有
+```
+
+### 消息收发核心
+
+- 收：`POST getupdates { get_updates_buf: "<游标,首次空>", base_info }`，
+  返回 `{ msgs, get_updates_buf, longpolling_timeout_ms }`。
+  `get_updates_buf` 是**游标**，必须每次回传更新，否则重复收消息。
+- 发：`POST sendmessage`，**必须原样回带最新 `context_token`**（取自收到的消息），
+  缺少字段会导致 HTTP 200 但消息静默丢失。
+  `sendmessage` 结构见下。
+- 消息里 `message_type`：1=用户消息；`item_list[].type`：1=文本 2=图片 3=语音 4=文件 5=视频
+
+### sendmessage 必填结构
+
+```json
+{
+  "msg": {
+    "from_user_id": "",
+    "to_user_id": "<用户ID@im.wechat>",
+    "client_id": "openclaw-weixin-<随机hex>",
+    "message_type": 2,
+    "message_state": 2,
+    "context_token": "<原样取回>",
+    "item_list": [{ "type": 1, "text_item": { "text": "回复" } }]
+  },
+  "base_info": { "channel_version": "2.4.3", "bot_agent": "..." }
+}
+```
+
+**用户 ID 格式**：`xxx@im.wechat`；**Bot ID**：`xxx@im.bot`；登录后每次扫码 Bot ID 会变。
+
+### 媒体（v0.2 再做）
+
+图片/文件/语音：随机 AES-128-ECB key → 加密 → `getuploadurl` 拿预签名 URL → PUT 到 CDN →
+`sendmessage` 带 `aes_key`(base64) + CDN 引用。语音 silk 编码，接收时可附带转文字。
+
+---
+
+## 三、架构设计
+
+### 3.1 整体数据流
+
+```
+微信用户
+   │ 发消息
+   ▼
+ilinkai.weixin.qq.com（腾讯，长轮询）
+   │ getupdates (主动拉)  /  sendmessage (主动发)
+   ▼
+dsh-bridge (本地电脑，本插件内)
+   ├── lib/wechat/gateway/       iLink 网关：扫码登录+长轮询+重连+typing+媒体CDN
+   │        → 暴露 ctx.wechat 服务 + 'wechat/message' 事件
+   └── lib/wechat/node/          微信⇄DSH 会话桥：白名单/会话/命令/审批/digest 输出
+            → 消费 ctx.sessions / ctx.agents / ctx.approval
+   ▼
+DSH (运行在 127.0.0.1:3080，agent 会话)
+```
+
+**关键点：这是纯 Outbound 连接**，类似现有 `lib/tunnel-client.mjs` 的"本地主动连出"模式，
+所以不需要自建隧道也可以工作；即使配合隧道，隧道也只在"手机浏览器远程访问 DSH 网页"时才需要，
+与微信机器人链路**相互独立**。
+
+### 3.2 模块划分（可插拔，为 QQ/飞书预留）
+
+```
+lib/
+  wechat/
+    gateway/
+      ilink-client.ts       # 纯协议：qrLogin/getupdates/sendmessage/sendtyping/getconfig/media CDN
+      gateway.ts            # Cordis 服务(Service<WechatGateway>)：轮询循环/重连退避/403独占锁/上下文token表
+      media.ts              # AES-128-ECB 加解密 + CDN 上传下载
+      types.ts              # 消息结构/常量/配置 schema
+    node/                   # 微信⇄DSH 会话桥（平台无关部分尽量抽到通用 layer）
+      core.ts               # 编排：活跃会话/白名单/审批队列
+      inbound.ts            # 入站：提取文本/群聊识别/只放行白名单
+      outbound.ts           # 出站：digest 式摘要/分块/限流/心跳
+      commands.ts           # /sessions /use /new /stop /status /yes /no /help
+      approvals.ts          # DSH 审批请求 ⇄ 微信文本问答(1/2 或 /yes /no)
+      index.ts              # 插件入口
+  bots/                     # 未来：qq/, feishu/ 等网关适配器，复用 node/ 会话桥
+```
+
+**多平台策略**：把 `node/`（会话桥）设计成**平台无关**的上层，网关通过统一接口注入收/发能力。
+未来 QQ / 飞书各自写一个 `gateway/` 适配器即可复用整套会话/命令/审批逻辑，这正是用户后续诉求。
+
+### 3.3 与 DSH 内部服务的对接（沿用 dsh-chatnode-wechat 已验证的注入面）
+
+```
+inject = ['wechat', 'sessions', 'agents', 'approval']
+```
+
+- `ctx.sessions` / `ctx.agents`：会话列表、新建 agent（`ctx.agents.create({sessionId, meta:{cwd,agentPreset}, agentOptions})`）、
+  `agent.followup(createUserMessage(...))` 驱动、`agent.stop()`。
+- `ctx.approval`：DSH 在 agent 需要权限时发审批请求；桥把「工具名+原因」渲染成微信文本问询，
+  用户回 `/yes` `/no`（或唯一待审批时回 1/2），超时默认拒绝（`allowed-once` / deny）。
+  参考 `dsh-chatnode-wechat` 的 `approvals.ts`。
+
+### 3.4 出站策略（微信无富文本/按钮，用文本摘要，不刷屏）
+
+- 回合开始：`⏳ 收到，开始处理…`
+- 进行中：每 `digestIntervalSec` 报一次 `🔄 仍在处理中…` 心跳
+- 产出：assistant 实际文本，按 `maxMessageChars`（微信气泡上限 ~2000）分块、`sendChunkDelayMs` 限流
+- 结束：`✅ 完成` / `❌ 出错…` / `⏹ 已停止`
+
+（注：项目偏好不用 emoji，上述标志仅是参考实现 dsh-chatnode 的风格，落地时换成纯文本标记，如 `[收到]`、`[处理中]`、`[完成]` 等。）
+
+---
+
+## 四、UI 集成（远程访问页新增「微信 Bot」卡片）
+
+现有 `client/index.js` 是设置页「远程访问」面板，`bridge-rpc.js` 走 loopback RPC。
+新增入口沿用同一套模式：
+
+### 4.1 RPC 新增 endpoint（`lib/bridge-rpc.js`）
+
+| Endpoint | 用途 |
+|---|---|
+| `wechatGetStatus` | 状态：idle/starting/connected/reconnecting/paused/error、账号、白名单、会话数 |
+| `wechatLogin` | 发起扫码（返回二维码 dataURL，浏览器可直接展示，复用现有 `QrCache`） |
+| `wechatSetAllowFrom` | 设置白名单（安全，必填） |
+| `wechatStop` | 断开网关 |
+| `wechatSetConfig` | 心跳间隔/审批超时/每气泡字数等 |
+
+### 4.2 卡片 UI（`client/index.js` 新增 React 组件）
+
+```
+┌─ 微信 Bot ─────────────────────────────────────┐
+│ 状态: ● 已连接 (账号: xxx, 会话: 3)    [断开]   │
+│                                                 │
+│ [首次] 扫码授权:  <二维码 dataURL>               │
+│ 白名单(你的微信ID): [o9cq...@im.wechat]          │
+│ 提示: 只有白名单账号能驱动 agent                 │
+│ [保存白名单] [重新扫码]                          │
+└─────────────────────────────────────────────────┘
+```
+
+### 4.3 UI 重新设计的思考（用户提到"现在的 UI 可以考虑重新设计"）
+
+- 现状是单页多个独立卡片（LAN 二维码、Cloudflare、自建隧道、微信 Bot）。
+- 建议演进为**分 Tab / 步骤式导航**：`局域网 | 公网隧道 | IM 机器人`。
+- IM 机器人 Tab 内做成**平台列表**（微信 / QQ / 飞书，未接入的置灰），选中微信后进入上图卡片。
+- 复用现有 `QrCache`（已带 TTL+LRU）与 `s` 样式变量，保持视觉一致。
+- UI 重新设计可单独作为一个子任务，优先保证微信 Bot 功能链路先通。
+
+---
+
+## 五、安全设计（必须项）
+
+1. **强制白名单** `allowFrom`：无默认、空则拒绝启动。非白名单发件人的消息仅记录日志，绝不喂给模型。
+   这是防 prompt-injection 的前门。
+2. **审批默认拒绝 + 超时自动拒绝**：`approvalTimeoutSec`（默认 600s）内未回 `/yes` 则 deny。
+3. bot token 存 DSH 凭证服务（`$DSH_HOME/.credentials.yaml`），**不落 patch 文件、不提交仓库**。
+   与现有 `.credentials` 偏好一致。
+4. 仅回应当前由该微信用户驱动的 agent 的审批，其余沿 Cordis answerer 链下放。
+5. **独占锁提示**：同一 bot token 只允许一个 poller。若用户同时跑 hermes-agent / openclaw，
+   检测到 403 时**响亮报错并停止轮询**，而不是无限重试。
+
+---
+
+## 六、命名 / 依赖 / 配置
+
+### 依赖（新增）
+- 纯实现无需新三方依赖（Node 18+ 内置 fetch）。媒体可选：`node:crypto` 内置 AES。
+
+### 配置示例（`cordis.patch.yml` / 设置页持久化）
+
+```yaml
+plugins:
+  dsh-bridge:
+    wechat:
+      allowFrom: ["<your-wechat-id>"]   # 必填，web UI 里设置并持久化到 $DSH_HOME/dsh-bridge/config.json
+      digestIntervalSec: 300
+      approvalTimeoutSec: 600
+      maxMessageChars: 2000
+      sendChunkDelayMs: 1500
+      # agentPreset / agentProvider / agentModel / cwd   # 用于 /new 会话
+```
+
+持久化沿用现有 `loadConfig/saveConfig`（`$DSH_HOME/dsh-bridge/config.json`），凭证单独走 DSH 凭证服务。
+
+---
+
+## 七、里程碑（Roadmap）
+
+**v0.1（微信 Bot 最小可用）— 已实施并完成真机验证**
+- [x] iLink 网关：扫码登录、长轮询收消息、sendmessage、sendtyping、自动重连/退避、403 独占锁
+- [x] 会话桥：白名单、`/sessions /use /new /stop /status /help`、文本双向
+- [x] 审批桥：`/yes /no`（1/2）、超时默认拒绝
+- [x] 出站 digest：`[收到]/[处理中]/[完成]/[出错]`，分块+限流
+- [x] RPC + UI 卡片：「微信 Bot」入口（扫码、状态、白名单管理）
+- [x] README / README.zh-CN 增加微信接入章节
+- [x] 真机验证：微信扫码登录 → `/new` 创建会话 → agent 正常回复（routing-suite preset 模板变量 `{{cwd}}`/`{{model}}` 已补默认值）
+
+**v0.2（媒体双向支持）— 实施中，入站下载解密已修通，待真机最终验证**
+- [x] 媒体入站：图片/文件接收（AES-128-ECB 解密 + 保存到 `.wechat-media/` + 路径附加到消息通知 agent）
+- [x] `lib/wechat/media.js`：AES 加解密、PKCS#7 填充、CDN 上传下载、SSRF 防护、aes_key 归一化
+- [x] `gateway.js` 扩展：`getUploadUrl` + `sendMedia` 方法支持媒体消息收发
+- [x] `node.js` 扩展：`_processMediaItems` / `_downloadMediaItem` 处理媒体入站
+- [x] 正确的媒体字段结构：`image_item.media` / `file_item.media` / `video_item.media`（含 `encrypt_query_param`）
+- [x] AES key 归一化：兼容裸 hex（`image_item.aeskey`）与 base64 编码
+- [x] 语音转文字：`extractText` 提取 `voice_item.text`
+- [x] 单元测试：16 个媒体测试（含 normalizeAesKey）
+- [x] 优化：去掉回合开始 `[OK] 收到，开始处理…` 刷屏，改 typing 指示 + 心跳；活动会话持久化
+- [x] 真机验证：微信发图片 → 下载解密保存到 `.wechat-media/`（文件头 `FFD8` 确认为标准 JPEG）→ 路径通知 agent → agent 响应。全链路打通
+- [ ] 媒体出站：agent 自动发送文件功能（API 已就绪，需监控 agent 文件输出并自动上传，待后续实现）
+
+**v0.3（多平台 + 群聊）**
+- [ ] 群聊支持（风险高，可选）
+- [ ] 抽象 `node/` 会话桥为平台无关 layer
+- [ ] 增加 QQ（NapCat/Mirai）、飞书（官方 push API）网关适配器，复用同一会话桥
+- [ ] UI 重构为「局域网 | 公网隧道 | IM 机器人」分 Tab 结构
+
+---
+
+## 八、参考实现（可复用/对照）
+
+| 项目 | 链接 | 说明 |
+|---|---|---|
+| dsh-chatnode-wechat | https://github.com/Jesse-njx/dsh-chatnode-wechat | **最相关**：微信 iLink 网关 + DSH 会话桥，含 35 个测试、fake-iLink-server、fixtures，可直接参考或精简复用 |
+| weixin-ClawBot-API | https://github.com/SiverKing/weixin-ClawBot-API | Python + Node 双实现，含 24h 自动重连、config.json 多 provider |
+| openclaw-weixin 逆向文档 | https://github.com/hao-ji-xing/openclaw-weixin/blob/main/weixin-bot-api.md | iLink 协议完整技术解析 |
+| hermes-agent weixin.py | https://github.com/NousResearch/hermes-agent/blob/main/gateway/platforms/weixin.py | 生产级 Python 网关，含证书/重连/媒体细节，协议参考价值高 |
+| OpenClaw 官方 | https://docs.openclaw.ai 、npm `@tencent-weixin/openclaw-weixin` | 官方通道背景 |
+
+---
+
+## 九、决策记录（用户已拍板，实施前无需再问）
+
+| # | 议题 | 决定 | 说明 |
+|---|---|---|---|
+| 1 | 实现底座 | **复用/精简 dsh-chatnode-wechat 协议层** | 在其 MIT 协议层上二次开发，改造成 dsh-bridge 内置 `lib/wechat/` 模块（含测试/fixtures 一并利用），不从零逆向 |
+| 2 | UI 结构 | **允许演进为分 Tab** | 「局域网 \| 公网隧道 \| IM 机器人」，拆成 v0.3 独立迭代，v0.1 先以卡片形式嵌入现有面板 |
+| 3 | 白名单 | **扫码即自动加入（一步到位）** | 扫码登录成功后，把返回的"我的微信 ID"自动写入 `allowFrom`；同时 UI 允许手动增删维护 |
+| 4 | v0.1 范围 | **只做文本** | 媒体/群聊放 v0.2 |
+
+> 以上即用户对第八节外遗留问题的最终拍板，新会话实施时直接按此执行，不要再让用户重复。
+
+---
+
+## 十、遗留问题（其余需实施时注意）
+
+- 白名单"扫码自动加入"仍需在 UI 上提供**手动增删白名单**入口，便于增补其他微信用户或移除。所有非白名单发件人消息仅记日志、绝不喂模型。
+- UI 分 Tab 重构（v0.3）与微信 Bot 卡片（v0.1）的关系：v0.1 先在现有面板加卡片，不做整体布局调整。

package/lib/auth/manager.js

@@ -34,6 +34,8 @@ export class AuthManager {
     this.adminPasswordSalt = config.adminPasswordSalt || ''
     this.secretToken = config.secretToken || this._generateToken()
     this.allowLoopback = config.allowLoopback !== false
+    // 内部隧道专用鉴权密钥（内存生成，用于辨别本地自建隧道转发流量与真实本机访问）
+    this.internalTunnelSecret = randomBytes(24).toString('hex')
 
     // Session 内存存储：sessionToken -> { createdAt, expiresAt }
     this.sessions = new Map()
@@ -63,7 +65,43 @@ export class AuthManager {
     return Boolean(this.adminPasswordHash && this.adminPasswordSalt)
   }
 
-  getStatus() {
+  /**
+   * 获取安全认证状态（默认脱敏保护，防止普通接口泄露完整 Secret Token）
+   */
+  getStatus({ masked = true } = {}) {
+    let token = this.secretToken;
+    if (masked && token) {
+      token = `${token.slice(0, 8)}****************`;
+    }
+    return {
+      enabled: this.enabled,
+      mode: this.mode,
+      scope: this.scope,
+      adminPolicy: this.adminPolicy,
+      hasPassword: this.hasPassword,
+      hasAdminPassword: this.hasAdminPassword,
+      secretToken: token,
+      allowLoopback: this.allowLoopback,
+    }
+  }
+
+  /**
+   * 仅限经过鉴权的管理员会话或公开策略下获取原始未脱敏 Secret Token
+   */
+  getRawSecretToken(adminToken) {
+    if (this.adminPolicy !== 'open') {
+      const hasAnyPassword = this.hasAdminPassword || this.hasPassword
+      if (hasAnyPassword && (!adminToken || !this.validateAdminSession(adminToken))) {
+        return null
+      }
+    }
+    return this.secretToken
+  }
+
+  /**
+   * 公开状态查询（供未认证访客/登录页使用，严格不包含 secretToken）
+   */
+  getPublicStatus() {
     return {
       enabled: this.enabled,
       mode: this.mode,
@@ -71,7 +109,6 @@ export class AuthManager {
       adminPolicy: this.adminPolicy,
       hasPassword: this.hasPassword,
       hasAdminPassword: this.hasAdminPassword,
-      secretToken: this.secretToken,
       allowLoopback: this.allowLoopback,
     }
   }
@@ -171,6 +208,10 @@ export class AuthManager {
     return true
   }
 
+  revokeAdminSession(adminToken) {
+    if (adminToken) this.adminSessions.delete(adminToken)
+  }
+
   verifyAdminPassword(inputPassword, clientIp = '') {
     if (this.isIpBlocked(clientIp)) {
       return { success: false, error: '尝试次数过多，请稍后再试' }
@@ -244,6 +285,11 @@ export class AuthManager {
       return { success: false, error: '尝试次数过多，请稍后再试' }
     }
 
+    // 严禁 token_only 模式下通过密码登录接口获取 Session
+    if (this.mode === 'token_only') {
+      return { success: false, error: '当前仅允许专属安全 Token 扫码访问，不支持密码登录' }
+    }
+
     if (!this.hasPassword) {
       // 若处于仅密码模式但尚未设置密码，不允许直接空白登录
       if (this.mode === 'password_only') {
@@ -347,7 +393,7 @@ export class AuthManager {
   /**
    * 检查请求是否已授权
    * @param {import('node:http').IncomingMessage} req
-   * @returns {{ authenticated: boolean, fromToken?: boolean, sessionToken?: string, loopback?: boolean, bypass?: boolean }}
+   * @returns {{ authenticated: boolean, fromToken?: boolean, sessionToken?: string, loopback?: boolean, bypass?: boolean, lanBypass?: boolean, publicBypass?: boolean }}
    */
   verifyRequest(req) {
     // 1. 未开启认证 -> 允许直通
@@ -355,25 +401,24 @@ export class AuthManager {
       return { authenticated: true, bypass: true }
     }
 
-    // 2. 本地环回免认证（宿主机 127.0.0.1 访问不阻断）
-    if (this.allowLoopback) {
-      const remote = req.socket?.remoteAddress || ''
-      if (remote === '127.0.0.1' || remote === '::1' || remote === '::ffff:127.0.0.1') {
-        const host = String(req.headers?.host || '')
-        if (host.startsWith('127.0.0.1') || host.startsWith('localhost')) {
-          return { authenticated: true, loopback: true }
-        }
+    const remote = req.socket?.remoteAddress || ''
+    const isLoopback = (remote === '127.0.0.1' || remote === '::1' || remote === '::ffff:127.0.0.1')
+
+    // 辨别是否来自自建隧道或 Cloudflare 隧道 (只有从 127.0.0.1 传入且带有合法内部凭据/Cloudflare 标头才算)
+    const internalTunnelHeader = req.headers?.['x-dsh-internal-tunnel']
+    const isCustomTunnel = Boolean(isLoopback && internalTunnelHeader && internalTunnelHeader === this.internalTunnelSecret)
+    const isCloudflare = Boolean(isLoopback && (req.headers?.['cf-ray'] || req.headers?.['cf-connecting-ip']))
+    const isPublicTunnel = isCustomTunnel || isCloudflare
+
+    // 2. 本地环回免认证（真正的宿主机物理浏览器 127.0.0.1 访问，非 Tunnel 转发）
+    if (this.allowLoopback && isLoopback && !isPublicTunnel) {
+      const host = String(req.headers?.host || '')
+      if (host.startsWith('127.0.0.1') || host.startsWith('localhost') || host === '') {
+        return { authenticated: true, loopback: true }
       }
     }
 
     // 3. 检查防护范围 (scope: 'all' | 'public_only' | 'lan_only')
-    const isPublicTunnel = Boolean(
-      req.headers?.['cf-connecting-ip'] ||
-      req.headers?.['cf-ray'] ||
-      req.headers?.['x-dsh-tunnel'] ||
-      (req.headers?.['x-forwarded-proto'] && req.headers?.['x-forwarded-host'])
-    )
-
     if (this.scope === 'public_only' && !isPublicTunnel) {
       return { authenticated: true, lanBypass: true }
     }