dsh-bridge-gateway 0.1.0

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+# dsh-bridge bundle patch
+- insert:
+    - id: dsh-bridge
+      name: '@wenbin_wb/dsh-bridge'

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/feishu-usage.md

@@ -0,0 +1,116 @@
+# 飞书 (Feishu / Lark) 机器人接入指南
+
+> 通过飞书官方开放平台 **WebSocket 长连接（免公网 IP）** 模式，将本地 DeepSeek Harness 接入飞书，支持单聊、群聊、表格命令与原生交互卡片权限审批。
+
+---
+
+## 🌟 核心优势
+
+- **100% 免公网 IP**：基于飞书官方最新 WebSocket 长连接协议，无需配置公网服务器、无需域名、无需内网穿透工具。
+- **免验签与加密配置**：长连接由飞书官方 SDK 在建立通道时完成认证，无需开发者手动处理 HTTP 回调验签。
+- **飞书原生交互卡片**：Agent 触发敏感工具审批时，飞书端下发带点击按钮的交互卡片，手机/电脑端单手一键点击即可完成批准或拒绝。
+- **多工作区与会话持久化**：支持 `/sessions` 表格查看历史会话、`/use <序号>` 极速切换、`/workspaces` 工作区调度。
+
+---
+
+## 🛠️ 第一步：创建飞书企业自建应用
+
+1. 登录 [飞书开放平台开发者后台](https://open.feishu.cn/app)；
+2. 点击右上角 **「创建企业自建应用」**，填写应用名称（如 `DeepSeek Harness`）与应用描述，上传机器人头像；
+3. 创建完成后，在左侧导航栏点击 **「凭证与基础信息」**，即可查看到：
+   - **App ID**（格式如 `cli_a1b2c3d4...`）
+   - **App Secret**（点击复制密钥）
+
+---
+
+## 🤖 第二步：添加机器人能力
+
+1. 在应用详情页左侧导航栏，点击 **「添加应用能力」**；
+2. 找到 **「机器人」**，点击 **「添加」** 开启机器人能力。
+
+---
+
+## 🔐 第三步：开通必要权限
+
+在左侧导航栏点击 **「权限管理」**，搜索并开通以下权限：
+
+| 权限名称 | 权限 Key | 权限说明 |
+| :--- | :--- | :--- |
+| **获取与发送单聊/群聊消息** | `im:message` | 基础消息收发权限 |
+| **以应用的身份发消息** | `im:message:send_as_bot` | 允许机器人向用户/群回复消息 |
+| **获取群组中所有消息** | `im:message.group_msg` | 允许机器人在群聊中被 `@` 时接收消息 |
+| **获取用户 user ID** | `contact:user.id:readonly` | (可选) 获取用户信息 |
+
+---
+
+## ⚡ 第四步：开启 WebSocket 长连接事件订阅
+
+1. 在左侧导航栏点击 **「事件与回调」**；
+2. 在 **「事件配置」** 页面，将事件接收方式切换为 **「使用长连接接收事件」**（WebSocket 模式）；
+3. 点击 **「添加事件」**，勾选并添加：
+   - **`im.message.receive_v1`**（接收消息）
+   - **`card.action.trigger`**（消息卡片回传交互 / 审批按钮点击）
+4. 保存配置。
+
+---
+
+## 🚀 第五步：版本发布
+
+1. 在左侧导航栏点击 **「版本管理与发布」**；
+2. 点击 **「创建版本」**，填写版本号（如 `1.0.0`），设置应用可用范围（如「所有员工」或「仅自己」）；
+3. 点击 **「申请发布」**（自建应用通常由企业管理员直接免审或一键通过）。
+
+---
+
+## 📱 第六步：在 DSH 客户端中连接
+
+1. 打开 DeepSeek Harness，进入「设置」➔「远程访问」➔「IM 机器人」➔ 选择 **「飞书」**；
+2. 在表单中填入刚才复制的 **App ID** 和 **App Secret**；
+3. 点击 **「保存并连接」**；
+4. 状态显示为绿色 **「已连接」** 即表示长连接成功建立！
+
+![飞书机器人配置](screenshots/feishu-bot-config.jpg)
+
+---
+
+## 💬 常用操作与指令
+
+在飞书与机器人单聊或在群里 `@机器人` 即可开始对话：
+
+### 1. 会话与工作区管理
+| 指令 | 说明 | 示例 |
+| :--- | :--- | :--- |
+| `/sessions` | 查看所有历史会话表格 | `/sessions` 或 `/list` |
+| `/use <编号>` | 切换到指定编号会话 | `/use 1` 或 `/resume 1` |
+| `/new <提示词>` | 在当前工作区创建新会话并开始 | `/new 帮我写个脚本` |
+| `/new <词> @N` | 在指定工作区新建会话 | `/new 帮我写个脚本 @1` |
+| `/rename <新标题>` | 重命名当前活动会话 | `/rename 优化登录交互` |
+| `/workspaces` | 查看所有已注册的工作区列表 | `/workspaces` |
+| `/addworkspace <路径>` | 注册添加新的电脑工作区目录 | `/addworkspace D:\projects\app` |
+| `/status` | 查看 Agent 运行状态看板 | `/status` |
+| `/stop` | 中断停止当前正在执行的任务 | `/stop` |
+| `/end` | 结束当前会话回到空闲状态 | `/end` |
+
+### 2. 权限审批交互
+当 Agent 尝试执行需授权的操作（如终端命令、写敏感文件）时，飞书端会自动推送 **原生交互卡片**：
+- 点击卡片上的 **「✓ 批准执行」** 或 **「✕ 拒绝执行」** 按钮即可一键处理；
+- 亦可直接回复文字 `/yes` (或 `1`) / `/no` (或 `2`)。
+
+![飞书对话与卡片审批](screenshots/feishu-chat.jpg)
+
+---
+
+## ❓ 常见问题 (FAQ)
+
+### Q1: 点击卡片上的「批准」/「拒绝」按钮提示无权限或无反应？
+请依次核对以下三项飞书开放平台配置：
+1. **是否订阅了卡片交互事件**：在开放平台后台 **「事件与回调」➔「事件配置」** 中，必须添加 **`card.action.trigger`**（消息卡片回传交互）事件。若只添加了接收消息事件，卡片点击不会下发回调。
+2. **是否发布了新版本生效**：飞书平台的所有权限与事件变更，**必须在「版本管理与发布」中「创建版本」并申请发布通过后才会生效**。
+3. **应用可用范围**：在「版本管理与发布」中，确认应用可用范围包含了您当前的飞书账号（建议设为「所有员工」或将自己加入可用成员）。
+4. **快速应急处理**：如果卡片按钮暂时受网络或配置影响，可直接在聊天中回复文字 **`/yes`**（或 `1`）批准，回复 **`/no`**（或 `2`）拒绝。
+
+### Q2: 机器人无法在群聊中回复消息？
+1. 确保在「权限管理」中开通了 **`im:message.group_msg`**（获取群组中所有消息）权限；
+2. 确保在「版本管理与发布」中发布了包含该权限的新版本；
+3. 将机器人拉入群聊后，需要 **`@机器人`** 唤醒并发送指令。
+

package/docs/fix-tunnel-sse-and-session-list.md

@@ -0,0 +1,134 @@
+# Fix: 自建隧道 SSE 504 超时 & 会话列表不显示
+
+## 问题现象
+
+通过自建 WebSocket 隧道（`wss://` 中转服务器）远程访问 DSH 时，出现两个问题：
+
+1. **`/plugins/events` SSE 端点返回 504 超时** — HMR 插件的 Server-Sent Events 连接永远不结束，隧道服务器超时后返回 504
+2. **Web 侧边栏会话列表不显示** — 页面其他功能正常，唯独会话列表空白
+
+## 根因分析
+
+### 问题 1：SSE 504 超时
+
+隧道协议将 HTTP 请求/响应封装为 WebSocket 消息：tunnel client 向本地 DSH 发起 HTTP 请求，**缓冲完整响应**后再通过 WebSocket 回传给 tunnel server，再由 tunnel server 转发给浏览器。
+
+SSE（`text/event-stream`）响应是**永不结束**的流式连接 — 服务器持续推送事件，不调用 `res.end()`。原代码的 `res.on('end')` 回调永远不会触发，tunnel server 的超时（30s 非 API 路径 / 120s API 路径）到期后返回 504。
+
+### 问题 2：会话列表不显示
+
+DSH 的 `session.list` RPC 返回所有会话的完整投影数据。在会话数量较多时（233 个会话），响应体高达 **63MB**，其中：
+
+| 字段 | 大小 | 占比 |
+|------|------|------|
+| `contextHeaders` | 57.4 MB | 92% |
+| `contextTimeline` | 5.0 MB | 8% |
+| 其他投影字段 | ~0.2 MB | <1% |
+
+`contextHeaders` 包含每个会话的完整对话上下文头（系统提示、消息头等），侧边栏列表**完全不需要**这些数据 — 打开会话时通过 WebSocket 实时获取即可。
+
+即使 gzip 压缩后仍有 13.5MB，通过 WebSocket 隧道传输需要 ~33s，超过 DSH 客户端的 `AbortSignal.timeout(30000)` 默认超时，导致请求被中止。
+
+## 修复方案
+
+### 修复 1：SSE 流式响应提前返回
+
+### 修复 1：SSE 流式响应提前返回
+
+在 `_handleHttpRequest()` 中检测 `text/event-stream` content-type，收集初始数据（2 个 chunk 或 500ms 超时）后立即返回响应，不等 `res.end()`：
+
+```javascript
+if (isSSE) {
+  let sseSent = false;
+  const sseTimer = setTimeout(() => { /* 发送已收集数据 */ }, 500);
+  res.on('data', (c) => {
+    if (sseSent) return;
+    chunks.push(c);
+    if (chunks.length >= 2) {
+      clearTimeout(sseTimer);
+      sseSent = true;
+      // 立即发送已收集的初始数据
+      this._sendMessage({ type: 'response', ... });
+      res.destroy();
+    }
+  });
+  // ... error/end 处理
+  return;
+}
+```
+
+### 修复 2：剥离 session.list 中的大字段
+
+对 `/api/session.list` 的 200 响应，解析 JSON 并删除每个会话投影中的 `contextHeaders` 和 `contextTimeline`：
+
+```javascript
+if (path === '/api/session.list' && res.statusCode === 200) {
+  try {
+    const json = JSON.parse(bodyBuf.toString('utf8'));
+    if (json?.result?.ok && json.result.value?.items) {
+      for (const item of json.result.value.items) {
+        const proj = item?.projections?.values;
+        if (proj) {
+          delete proj.contextHeaders;
+          delete proj.contextTimeline;
+        }
+      }
+      bodyBuf = Buffer.from(JSON.stringify(json), 'utf8');
+    }
+  } catch {}
+}
+```
+
+### 修复 3：大响应 gzip 压缩
+
+对超过 100KB 的可压缩响应（`text/*`、`application/json` 等）自动 gzip 压缩，设置 `content-encoding: gzip` 头：
+
+```javascript
+if (bodyBuf.length > GZIP_THRESHOLD && compressible && !alreadyEncoded) {
+  bodyBuf = gzipSync(bodyBuf);
+  respHeaders['content-encoding'] = 'gzip';
+  respHeaders['content-length'] = String(bodyBuf.length);
+}
+```
+
+### 修复 4：启用 WebSocket per-message 压缩
+
+将隧道 WebSocket 的 `perMessageDeflate` 从 `false` 改为启用，进一步减少隧道传输量：
+
+```javascript
+this.ws = new WebSocket(url.toString(), {
+  handshakeTimeout: 10000,
+  perMessageDeflate: {
+    clientNoContextTakeover: true,
+    serverNoContextTakeover: true,
+    clientMaxWindowBits: 15,
+    serverMaxWindowBits: 15,
+  },
+});
+```
+
+## 效果
+
+| 指标 | 修复前 | 修复后 |
+|------|--------|--------|
+| `session.list` 响应大小 | 63 MB | ~290 KB (剥离后) / 31 KB (gzip 后) |
+| `session.list` 隧道传输时间 | 33s (超时) | 0.74s |
+| `/plugins/events` SSE | 504 超时 | 正常返回初始数据 |
+| 侧边栏会话列表 | 不显示 | 正常显示 |
+
+## 影响范围
+
+- **非隧道模式不受影响**：所有修改仅在 `_handleHttpRequest()` 中，只影响自建隧道的 HTTP 代理路径
+- **WebSocket 透传不受影响**：`/api/events.mux` 和 `/api/events.host` 的 WebSocket 升级走独立的 `_handleWsOpen()` 路径，不受此修改影响
+- **非 session.list 请求不受影响**：contextHeaders 剥离仅对 `/api/session.list` 路径生效
+- **小响应不受影响**：gzip 压缩仅对超过 100KB 的可压缩响应生效
+- **已有 content-encoding 的响应不受影响**：不重复压缩
+
+## 测试验证
+
+- ✅ 本地 WebSocket 直连 DSH（`/api/events.mux`）正常接收 `session/subscribed` 事件
+- ✅ 通过隧道的 WebSocket（`wss://ds.missus.top/api/events.mux`）正常接收 26+ 条消息
+- ✅ 通过隧道的 `session.list` 请求：31KB / 0.74s（修复前 63MB / 33s 超时）
+- ✅ 响应包含 234 个会话，`contextHeaders` 和 `contextTimeline` 已剥离，`title` 等字段完整
+- ✅ TLS 证书有效，gzip content-encoding 头正确传递
+>>>>>>> pr-21