@wenbin_wb/dsh-bridge 1.0.8 → 1.2.0

package/docs/custom-tunnel.md

@@ -0,0 +1,220 @@
+# 自建隧道服务器搭建教程
+
+dsh-bridge 的「自建隧道」功能需要一台有公网 IP 的服务器来中转流量。本教程提供一键部署脚本，执行完成后直接复制输出的配置信息填入 dsh-bridge 即可。
+
+## 前置条件
+
+- 一台运行 Linux 的公网服务器（VPS、云主机均可，国内外皆可）
+- 服务器有 root 权限
+- Node.js 18+ 会**自动安装**，无需手动准备
+
+---
+
+## 一键部署（推荐）
+
+在服务器上以 root 身份执行以下命令：
+
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/wenbin-wb/dsh-bridge/main/scripts/install-tunnel-server.sh)
+```
+
+脚本会自动完成：
+
+- 检测并安装 Node.js 22 LTS
+- 自动获取服务器公网 IP，自动选择可用端口
+- 随机生成 16 位访问路径 + 32 位连接令牌（双重保护）
+- 部署隧道服务端到 `/opt/dsh-tunnel`
+- 注册 systemd 服务并设为开机自启
+- 放行防火墙端口（支持 ufw / firewalld）
+- 验证服务是否正常运行
+
+执行完成后，终端会打印如下信息：
+
+```
+  ┌──────────────────────────────────────────────────────────────┐
+  │  DSH 设置  →  远程访问  →  自建隧道                          │
+  ├──────────────────────────────────────────────────────────────┤
+  │  WebSocket 地址                                              │
+  │  ws://YOUR_IP:3000/connect                                   │
+  │                                                              │
+  │  访问令牌                                                    │
+  │  xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx                            │
+  └──────────────────────────────────────────────────────────────┘
+
+  连接成功后，dsh-bridge 会显示以下公网访问地址：
+  http://YOUR_IP:3000/a7f2k9m3x1b4c8d2
+
+  安全说明：该地址含随机路径（/a7f2k9m3x1b4c8d2），不知道路径无法访问。
+            端口扫描只能看到 404，不会暴露 DSH 的存在。
+```
+
+将 WebSocket 地址和访问令牌复制到 DSH 设置页「远程访问 → 自建隧道」，保存后点「开启」即可。
+
+### 安全设计说明
+
+脚本部署的服务端采用**双重保护**机制：
+
+| 层 | 机制 | 说明 |
+|----|------|------|
+| WebSocket 连接层 | 连接令牌（TOKEN） | dsh-bridge 连接服务端时验证，防止他人建立隧道连接 |
+| HTTP 访问层 | 随机路径前缀 | 所有不含该路径的请求返回 404，端口扫描看不出服务存在 |
+
+最终对外的公网地址形如 `http://IP:PORT/a7f2k9m3x1b4c8d2`，路径本身即是密钥——不知道完整地址就无法访问你的 DSH。
+
+### 自定义参数（可选）
+
+如需自定义端口、令牌或指定域名，可通过环境变量传入：
+
+```bash
+# 自定义端口
+PORT=8080 bash <(curl -fsSL ...)
+
+# 自定义令牌
+TOKEN=my-secret-token bash <(curl -fsSL ...)
+
+# 有域名时指定（会自动使用 wss:// 安全连接）
+DOMAIN=tunnel.example.com bash <(curl -fsSL ...)
+```
+
+### 日常管理
+
+```bash
+# 查看服务状态
+systemctl status dsh-tunnel
+
+# 查看实时日志
+journalctl -u dsh-tunnel -f
+
+# 重启服务
+systemctl restart dsh-tunnel
+
+# 修改配置后重启
+nano /opt/dsh-tunnel/.env
+systemctl restart dsh-tunnel
+```
+
+---
+
+## 启用 HTTPS / WSS（可选，有域名时推荐）
+
+默认部署使用 HTTP，如果你有域名并配置了 SSL 证书，可以通过 Nginx 反向代理启用 HTTPS，连接更安全稳定。
+
+### 安装 Nginx 和 Certbot
+
+```bash
+# Debian/Ubuntu
+apt-get install -y nginx certbot python3-certbot-nginx
+
+# CentOS/Rocky
+dnf install -y nginx certbot python3-certbot-nginx
+```
+
+### 申请证书并配置 Nginx
+
+```bash
+# 申请免费 Let's Encrypt 证书
+certbot --nginx -d tunnel.example.com
+```
+
+Nginx 配置 `/etc/nginx/sites-available/dsh-tunnel`（Debian 系）：
+
+```nginx
+server {
+    listen 443 ssl;
+    server_name tunnel.example.com;
+
+    ssl_certificate     /etc/letsencrypt/live/tunnel.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/tunnel.example.com/privkey.pem;
+
+    location / {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_read_timeout 3600s;
+    }
+}
+
+server {
+    listen 80;
+    server_name tunnel.example.com;
+    return 301 https://$host$request_uri;
+}
+```
+
+启用并重启 Nginx：
+
+```bash
+ln -s /etc/nginx/sites-available/dsh-tunnel /etc/nginx/sites-enabled/
+nginx -t && systemctl restart nginx
+```
+
+配置完成后，修改 `/opt/dsh-tunnel/.env`：
+
+```
+PUBLIC_URL=https://tunnel.example.com
+```
+
+重启服务并更新 dsh-bridge 中的地址为 `wss://tunnel.example.com/connect`：
+
+```bash
+systemctl restart dsh-tunnel
+```
+
+---
+
+## 工作原理
+
+```
+手机/外网设备
+    │  HTTPS 请求
+    ▼
+隧道服务端（你的公网服务器）
+    │  WebSocket 实时转发
+    ▼
+dsh-bridge（你的本地电脑，主动发起连接）
+    │  HTTP 本地转发
+    ▼
+DSH（127.0.0.1:3080）
+```
+
+本地电脑主动连接到服务端，**本地无需开放任何端口**，防火墙不需要特殊配置。
+
+---
+
+## 常见问题
+
+**连接超时 / 无法连接**
+
+1. 检查服务器**云控制台安全组**是否放行了端口（默认 3000）——云主机有两层防火墙：云安全组（控制台配置）和系统防火墙（ufw/firewalld），两层都要放行
+2. 确认服务正在运行：`systemctl status dsh-tunnel`
+3. 验证健康检查（在服务器本机执行）：`curl http://127.0.0.1:3000/healthz`，应返回 `{"ok":true,...}`
+4. 外网访问 `healthz` 返回 404 是正常的（安全设计，防止探测）
+
+**历史记录加载失败 / 提示 "The user aborted a request."**
+
+历史消息较多时，API 响应时间较长。请确保服务端版本 ≥ 1.0.6（脚本已将 API 请求超时提升至 120s）。重新运行安装脚本即可更新：
+
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/wenbin-wb/dsh-bridge/main/scripts/install-tunnel-server.sh)
+```
+
+**重装后端口变了，安全组不匹配**
+
+插件会自动保留已有配置（令牌/端口/路径不变）。若出现端口变化，通常是上次重装时旧进程仍在占用端口导致自动选了新端口。脚本 1.0.6 起已修复：清理旧进程提前到端口检测之前，重装时始终复用原端口。
+
+WebSocket 长连接需要较长的超时配置。如果使用 Nginx，确保 `proxy_read_timeout` 设为 `3600s`。
+
+**页面加载缓慢**
+
+自建隧道的速度取决于服务器带宽和网络延迟。国内用户建议选择国内云服务器节点。
+
+**重新部署 / 更新**
+
+重新执行一键部署命令即可，会覆盖旧版本并保留配置文件：
+
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/wenbin-wb/dsh-bridge/main/scripts/install-tunnel-server.sh)
+```

package/docs/wechat-usage.md

@@ -0,0 +1,101 @@
+# 微信 Bot 使用说明
+
+> dsh-bridge 的微信 Bot（ClawBot / iLink）让你**直接在微信里**与你的 DeepSeek Harness agent 对话、控制和审批——无需公网、无需隧道，走腾讯官方 iLink Bot API。
+
+扫码登录微信个人号后，发消息就能驱动 agent；`/` 开头的命令管理会话、切换工作区、审批权限。会话与工作区信息跨重启持久化，不会丢。
+
+---
+
+## 一、快速开始
+
+1. 打开 DSH 设置页 → 「远程访问」→ 「IM 机器人」标签页 → 选中「微信」平台
+2. 点击「扫码登录」，用微信扫二维码并按提示确认
+3. 登录成功后，**向该微信 Bot 发送第一条消息，自动完成白名单授权**（一步到位）
+4. 之后就可以直接在微信里下命令、发消息了
+
+> 💡 登录后左侧「IM 机器人」标签会出现绿色圆点，表示微信 Bot 已连接。
+
+---
+
+## 二、基本对话
+
+直接发送普通文本即可与当前活动的 agent 对话。支持发送**图片 / 文件 / 语音**（语音自动转文字），agent 也能在需要时把文件发回给你。
+
+- 长回复会自动**分多条发送**，并在消息间留出间隔，避免刷屏
+- 任务处理中会周期性发送「[处理中] 第 N 轮 | …」的心跳进度
+
+---
+
+## 三、命令一览
+
+| 命令 | 说明 |
+|------|------|
+| *(普通文本)* | 发给当前活动 agent |
+| `/sessions` | 列出所有会话（按**工作区**分组，显示**会话标题**） |
+| `/use N` | 切换到会话 N |
+| `/workspaces` | 列出可用工作区 |
+| `/new <提示词>` | 在**当前工作区**新建会话并开始 |
+| `/new <提示词> @N` | 在**编号 N 的工作区**新建会话 |
+| `/new <提示词> @路径` | 在**指定目录**新建会话 |
+| `/stop` | 停止当前任务 |
+| `/status` | 查看当前 agent 状态与会话摘要 |
+| `/yes` `/no`（或 `1`/`2`） | 回应权限审批请求 |
+| `/start` | 首次扫码后自动开始一个会话 |
+| `/help` | 查看全部命令 |
+
+### 例子
+
+```
+/new 帮我重构这个项目的路由                  # 默认工作区新建
+/new 继续上周的 ypbin 开发 @2                # 在 2 号工作区新建
+/sessions                                     # 按工作区分组列出所有会话（带标题）
+/use 3                                        # 切到 3 号会话继续聊
+```
+
+---
+
+## 四、会话与工作区
+
+### 会话持久化
+
+- 会话数据保存到 DSH 的持久化存储，**重启 DSH 后会话不丢失**，下次直接发消息就能接着上次继续
+- `/sessions` 会按工作区（项目目录）分组展示，并为每个会话显示**标题**（DSH 自动生成），方便区分
+
+### 工作区（项目目录）
+
+- `/workspaces` 列出可用的工作区
+- 新建会话时用 `@N` 或 `@路径` 指定工作区，让 agent 在指定项目目录下工作
+- 不指定则使用默认工作区（当前启动目录）
+
+---
+
+## 五、权限审批
+
+当 agent 需要执行敏感操作（改文件、跑命令、调用外部服务等）时，会在微信里给你发送一条审批问询：
+
+```
+[待确认] 1. agent 想要执行某个操作
+请回复 /yes（允许）或 /no（拒绝）
+```
+
+- 回复 `/yes` `/no`，或仅有一条待确认时直接回复 `1` / `2`
+- 默认 **10 分钟**内未回复则**自动拒绝**（可在设置页「高级设置」调整审批超时）
+
+---
+
+## 六、安全说明
+
+- **强制白名单**：仅白名单内的微信用户能驱动 agent，其他人发的消息一律忽略、**绝不喂给模型**
+- **审批默认拒绝**：未及时回复的权限请求自动拒绝
+- **凭证加密存储**：经 DSH 凭证服务保存，不落配置明文
+- **建议专用微信号**：iLink 每个账号只允许一个 poller，与 hermes-agent / OpenClaw 并存会互相 403；为避免影响主号，**请用专用微信小号承载 Bot**
+
+> 声明：iLink 为腾讯官方开放通道，仍需遵守《微信 ClawBot 功能使用条款》，腾讯保留内容过滤和限速的权利。不建议用于核心业务。
+
+---
+
+## 七、注意事项
+
+- **解绑账号**：设置页微信卡片里点「解绑账号」可清除登录凭证，下次需重新扫码
+- **高级设置**：设置页「高级设置」可调整心跳间隔、审批超时、每气泡字数、分块发送延迟
+- 发送媒体文件时请耐心等待上传/下载，大文件耗时较长

package/lib/bridge-rpc-constants.js

@@ -0,0 +1,21 @@
+// DSH Bridge - RPC constants (dependency-free, safe to import from browser client)
+
+export const BRIDGE_RPC_CHANNEL = '/dsh-bridge';
+
+export const BRIDGE_ENDPOINTS = {
+  getStatus: 'getStatus',
+  startCustomTunnel: 'startCustomTunnel',
+  stopCustomTunnel: 'stopCustomTunnel',
+  startCloudflared: 'startCloudflared',
+  stopCloudflared: 'stopCloudflared',
+  resetCloudflared: 'resetCloudflared',
+  saveCustomTunnelConfig: 'saveCustomTunnelConfig',
+  checkVersion: 'checkVersion',
+  wechatGetStatus: 'wechatGetStatus',
+  wechatLogin: 'wechatLogin',
+  wechatSetAllowFrom: 'wechatSetAllowFrom',
+  wechatSetConfig: 'wechatSetConfig',
+  wechatStop: 'wechatStop',
+  wechatStart: 'wechatStart',
+  wechatUnbind: 'wechatUnbind',
+};

package/lib/bridge-rpc.js

@@ -1,18 +1,10 @@
-// DSH Bridge - RPC Interface
+// DSH Bridge - RPC Interface (server side)
 // Loopback-only RPC methods for browser UI
 
-export const BRIDGE_RPC_CHANNEL = '/dsh-bridge';
+import QRCode from 'qrcode';
+import { BRIDGE_RPC_CHANNEL, BRIDGE_ENDPOINTS } from './bridge-rpc-constants.js';
 
-export const BRIDGE_ENDPOINTS = {
-  getStatus: 'getStatus',
-  startCustomTunnel: 'startCustomTunnel',
-  stopCustomTunnel: 'stopCustomTunnel',
-  startCloudflared: 'startCloudflared',
-  stopCloudflared: 'stopCloudflared',
-  resetCloudflared: 'resetCloudflared',
-  saveCustomTunnelConfig: 'saveCustomTunnelConfig',
-  checkVersion: 'checkVersion',
-};
+export { BRIDGE_RPC_CHANNEL, BRIDGE_ENDPOINTS };
 
 function ok(value) {
   return { ok: true, value };
@@ -32,7 +24,37 @@ function fail(code, message, details = {}) {
   };
 }
 
-export function installBridgeRpc(ctx, { service, logger, saveCustomTunnelConfig }) {
+// 把登录态里的二维码载荷渲染成浏览器可展示的 dataURL（带缓存，避免重复生成）
+async function renderQr(loginState) {
+  if (!loginState?.qrPayload) return null;
+  const cacheKey = `${loginState.qrKind}:${loginState.qrPayload.slice(0, 80)}`;
+  if (renderQr.cache && renderQr.cache.key === cacheKey) return renderQr.cache.url;
+  let url = null;
+  const payload = loginState.qrPayload;
+  if (loginState.qrKind === 'img') {
+    url = /^data:/i.test(payload) ? payload : `data:image/png;base64,${payload}`;
+  } else {
+    try {
+      url = await QRCode.toDataURL(payload, {
+        width: 300, margin: 2, color: { dark: '#1F2421', light: '#FFFFFF' },
+      });
+    } catch { url = null; }
+  }
+  renderQr.cache = { key: cacheKey, url };
+  return url;
+}
+
+/** 归一化 wechat 状态返回：把 loginState 里的 qrPayload 渲染成 qr dataURL。 */
+async function wechatStatusValue(wechatService, logger) {
+  const status = wechatService.getStatus();
+  const qr = await renderQr(status.login).catch((err) => {
+    logger.warn('dsh-bridge: render wechat qr failed: %s', err?.message ?? err);
+    return null;
+  });
+  return { ...status, login: { ...status.login, qr, qrPayload: undefined, qrKind: undefined } };
+}
+
+export function installBridgeRpc(ctx, { service, wechat, logger, saveCustomTunnelConfig }) {
   if (!ctx?.connection?.rpc?.handle) {
     logger.warn('dsh-bridge: Connection RPC unavailable — UI will not work');
     return () => {};
@@ -101,6 +123,60 @@ export function installBridgeRpc(ctx, { service, logger, saveCustomTunnelConfig
           return ok(result);
         }
 
+        // ---- 微信 Bot ----
+
+        if (endpoint === BRIDGE_ENDPOINTS.wechatGetStatus) {
+          if (!wechat) return fail('bad-request', '微信 Bot 未初始化');
+          const value = await wechatStatusValue(wechat, logger);
+          return ok(value);
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.wechatLogin) {
+          if (!wechat) return fail('bad-request', '微信 Bot 未初始化');
+          const { qrType } = payload;
+          const result = await wechat.login({ qrType });
+          if (!result.ok) return fail('bad-request', result.error ?? '登录启动失败');
+          const value = await wechatStatusValue(wechat, logger);
+          return ok(value);
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.wechatSetAllowFrom) {
+          if (!wechat) return fail('bad-request', '微信 Bot 未初始化');
+          await wechat.setAllowFrom(payload.allowFrom);
+          const value = await wechatStatusValue(wechat, logger);
+          return ok(value);
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.wechatSetConfig) {
+          if (!wechat) return fail('bad-request', '微信 Bot 未初始化');
+          await wechat.setConfig(payload);
+          const value = await wechatStatusValue(wechat, logger);
+          return ok(value);
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.wechatStop) {
+          if (!wechat) return fail('bad-request', '微信 Bot 未初始化');
+          await wechat.stop();
+          const value = await wechatStatusValue(wechat, logger);
+          return ok(value);
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.wechatStart) {
+          if (!wechat) return fail('bad-request', '微信 Bot 未初始化');
+          await wechat.gateway.start().catch((err) => {
+            logger.error('wechat start failed: %s', err?.message ?? err);
+          });
+          const value = await wechatStatusValue(wechat, logger);
+          return ok(value);
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.wechatUnbind) {
+          if (!wechat) return fail('bad-request', '微信 Bot 未初始化');
+          await wechat.unbind();
+          const value = await wechatStatusValue(wechat, logger);
+          return ok(value);
+        }
+
         return fail('bad-request', `Unknown endpoint: ${endpoint}`);
       } catch (err) {
         logger.error('RPC endpoint %s failed: %s', endpoint, err.message);

package/lib/index.js

@@ -16,9 +16,11 @@ import QRCode from 'qrcode';
 import { installBridgeRpc } from './bridge-rpc.js';
 import { CustomTunnelClient } from './tunnel-client.mjs';
 import { CloudflaredManager } from './cloudflared-manager.mjs';
+import { WechatService } from './wechat/index.js';
 
 const name = 'dsh-bridge';
-const inject = ['connection', 'webServer'];
+// 微信 Bot 会话桥依赖 DSH 提供的会话/agent/审批/工作区/持久化服务，需显式 inject
+const inject = ['connection', 'webServer', 'sessions', 'agents', 'approval', 'workspaceRegistry', 'sessionPersistence'];
 
 // 从 package.json 动态读取版本号，发版只需改 package.json 一处
 const PACKAGE_JSON = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8'));
@@ -320,6 +322,9 @@ class BridgeService {
           : null,
         state: this.customTunnelState,
       },
+
+      // 轻量摘要，供 UI Tab 状态点使用（完整状态由 wechatGetStatus 提供）
+      wechat: this.wechat ? { status: this.wechat.gateway?.status ?? 'idle' } : null,
     };
   }
 
@@ -478,8 +483,45 @@ function apply(ctx, config = {}) {
     }
   }).catch(() => {});
 
+  // 微信 Bot（ClawBot/iLink）
+  const wechat = new WechatService({
+    ctx,
+    logger,
+    config: config.wechat ?? {},
+    onPersist: async (patch) => {
+      const stored = await loadConfig();
+      stored.wechat = { ...(stored.wechat ?? {}), ...patch };
+      await saveConfig(stored);
+    },
+  });
+
+  // 启动时读取已保存的微信 Bot 配置（凭证 + 白名单 + 活动会话）
+  loadConfig().then((stored) => {
+    if (stored?.wechat) {
+      const cfg = stored.wechat;
+      wechat.node.config.allowFrom = Array.isArray(cfg.allowFrom) ? cfg.allowFrom : [];
+      // 恢复活动会话 ID（直接覆盖，不判断当前值）
+      if (cfg.activeSessionId) {
+        wechat.node.activeSessionId = cfg.activeSessionId;
+        logger.info('dsh-bridge: restored wechat active session: %s', cfg.activeSessionId);
+      } else {
+        // 没有持久化的会话时，回退到选第一个
+        wechat.node._pickDefaultSession().catch(() => {});
+      }
+      if (cfg.token && cfg.accountId) {
+        wechat.gateway.setCredentials({
+          token: cfg.token,
+          accountId: cfg.accountId,
+          baseUrl: cfg.baseUrl,
+        });
+        logger.info('dsh-bridge: loaded saved wechat bot config, starting polling');
+      }
+    }
+  }).catch(() => {});
+
   const disposeRpc = installBridgeRpc(ctx, {
     service,
+    wechat,
     logger,
     saveCustomTunnelConfig: async (serverUrl, accessToken) => {
       const stored = await loadConfig();
@@ -496,8 +538,9 @@ function apply(ctx, config = {}) {
 
   ctx.effect(() => async () => {
     try { disposeRpc(); } catch {}
+    await wechat.destroy();
     await service.dispose();
-  }, 'dsh-bridge: stop proxy and tunnels');
+  }, 'dsh-bridge: stop wechat, proxy and tunnels');
 }
 
 export { name, inject, apply };