dsh-lark-bridge

Readme

# dsh-lark-bridge

飞书机器人 ↔ DeepSeek Harness (DSH) 会话桥接。通过飞书单聊/群聊与 DSH 会话对话，操作审批路由到飞书交互卡片。

> **DSH Store** 插件兼容声明：`dsh.compatibility.dshReleases` 已在 `package.json` 中声明，支持 DSH `0.1.0-rc.8` / `0.1.1-rc.1` / `0.1.1-rc.2`。插件补丁清单见 `dsh-bundle-patch.json`。

## 功能

### 实时对话
- 在飞书给机器人发消息 → 注入到 DSH 会话作为用户回合 → 助手回复回传飞书
- 支持**私聊**和**群聊 @机器人**
- 每个飞书聊天（私聊/每个群聊）拥有**独立的 DSH 会话**，互不干扰
- 会话上下文持久化，重启 bot 后自动复用

### 操作审批
- DSH 执行中触发操作审批 → 飞书交互卡片（同意/拒绝按钮）
- 用户在飞书点击 → 裁决回传 DSH 继续执行
- 审批卡片发到触发操作的聊天中，**只有管理员能点击审批**

### 提问交互
- DSH 调用 `ask_user_question` → 每个问题发一张飞书交互卡片
- 支持选项按钮、自定义输入、跳过
- 自由文本问题通过 @机器人回复
- 所有答案收集完成后一次性提交给 DSH

### 会话管理（斜杠指令）
| 指令 | 功能 |
|---|---|
| `/help` | 显示所有指令 |
| `/new` | 创建新会话（清空当前上下文） |
| `/list` | 列出所有会话（过滤已删除的残留会话） |
| `/switch <序号/ID>` | 切换到指定会话 |
| `/model` | 列出可用模型，标注当前使用的 |
| `/model <序号> [effort]` | 切换模型，可选设置推理强度（off/high/max） |
| `/mode <queue\|steer>` | 切换发送模式（排队/插话） |
| `/stop` | 停止当前正在运行的回合 |
| `/context [N]` | 查看最近 N 条消息（默认 10，上下文查询） |
| `/compact` | 触发上下文压缩（压缩历史，释放上下文窗口） |
| `/status` | 查看当前桥接状态（含模型、上下文压力信息） |
| `/clean` | 查看如何清理旧会话 |

### 停止回合
- 运行中发 **`/stop`** → 调用 DSH `session.cancel` 停止当前回合（保留排队中的消息）
- 运行中直接发 **「停止」「stop」「中止」** → 同上，自然语言停止
- 消息前加 **`!`** → 插话模式（steer），打断当前回合并注入新消息

### 模型切换
| 指令 | 效果 |
|---|---|
| `/model` | 列出所有可用模型，标注当前使用的 |
| `/model 2` | 切换到序号 2 对应的模型 |
| `/model 2 max` | 切换模型并设置推理强度为 max |
| `/model fuyao fuyao-work` | 用 provider + model 名精确切换 |

可用模型取决于 DSH 配置，常见包括 DeepSeek-V4-Flash、DeepSeek-V4-Pro、fuyao-coding 等。

### 发送模式
| 操作 | 效果 |
|---|---|
| 默认（排队） | 消息排队等当前回合结束后处理 |
| `/mode steer` | 每条消息立即打断当前回合 |
| `!消息内容` | 任何模式下临时插话（可跳出提问循环） |

### 权限管理
| 操作 | 管理员 | 其他人 |
|---|---|---|
| 聊天问问题 | ✅ | ✅ |
| 斜杠指令 | ✅ | ❌ |
| 审批卡片 | ✅ | ❌ |
| 提问卡片选选项 | ✅ | ✅ |
| 消息已收表情 | ✅ | ✅ |

## 架构

```
飞书用户 ←WS长连接→ 飞书开放平台 ←→ dsh-lark-bridge (bot进程)
                                              ↕ HTTP RPC + WebSocket
                                      DSH 会话 (127.0.0.1:3080)
```

- 独立 Node.js 进程，使用 `@larksuiteoapi/node-sdk` **长连接**（WebSocket，免公网 IP）接收飞书事件
- 通过 DSH 的 HTTP/WS API 代理（与 Web GUI 同一套接口）发送消息、订阅事件流、回传审批裁决
- 每个飞书 chatId → 独立 DshClient → 独立 DSH 会话，多会话完全隔离
- 仅写入工作目录（沙箱友好），不修改 DSH 核心
- 无鉴权（DSH 安全靠 loopback 绑定，bot 必须与 DSH 同机运行）

## 配置

### 方式一：交互式向导（推荐）

```bash
node setup.mjs
```

按提示依次填写飞书 App ID、App Secret、管理员 open_id，其余项回车用默认值。完成后自动生成 `.env`。

### 方式二：手动复制

复制 `.env.example` 为 `.env` 并填写：

```bash
copy .env.example .env
```

| 环境变量 | 必填 | 说明 |
|---|---|---|
| `LARK_APP_ID` | ✅ | 飞书应用 App ID |
| `LARK_APP_SECRET` | ✅ | 飞书应用 App Secret |
| `LARK_TARGET_OPEN_ID` | ✅ | 管理员的飞书 open_id（ou_xxx） |
| `LARK_BOT_NAME` | | 机器人显示名称（默认「DSH桥接机器人」） |
| `BRIDGE_DSH_API_BASE` | | DSH 地址（默认 `http://127.0.0.1:3080`） |
| `BRIDGE_DSH_CREATE_SESSION` | | `true` 则创建独立会话并缓存（默认 true） |
| `BRIDGE_DSH_SESSION_CWD` | | 新会话工作目录（留空用 DSH 默认） |
| `BRIDGE_DSH_SESSION_ID` | | 指定已有会话 ID（留空自动创建/复用） |

> 首次双击 `start-bot.bat` 时如检测到没有 `.env`，会提示你先运行 `node setup.mjs` 完成配置。

## 启动

### 方式一：双击启动脚本（推荐）
双击 `start-bot.bat`，弹出独立命令行窗口运行 bot。
- 关闭 DSH Web GUI 不影响 bot
- 关闭弹出的窗口即停止 bot

### 方式二：命令行
```bash
cd E:\Workspace\dsh-lark-bridge
node src/bot.js
```

### 停止 bot
- 关闭运行 bot 的命令行窗口（或按 Ctrl+C）
- 任务管理器 → 详细信息 → 添加「命令行」列 → 找含 `dsh-lark-bridge` 的 node.exe → 结束任务

## 飞书后台配置清单（开发者后台）

1. **应用能力**：开启「机器人」能力
2. **事件订阅**：接收方式选择「使用长连接接收事件」
3. **订阅事件**：
   - `im.message.receive_v1`（接收消息）
   - `card.action.trigger`（交互卡片回调）
4. **权限范围**：
   - `im:message`、`im:message:send_as_bot`（发送消息）
   - `im:message.p2p_msg:readonly`（接收单聊消息）
   - 交互卡片相关权限
5. 发布版本并审核通过（自建应用内部可用）

## 项目结构

```
dsh-lark-bridge/
├── src/
│   ├── bot.js              # 主入口：多会话管理、消息路由、指令处理
│   ├── dsh/
│   │   └── client.js       # DSH API 客户端（RPC + WS mux + 审批/提问/模型切换）
│   └── feishu/
│       └── bridge.js       # 飞书传输层（LarkChannel 长连接 + 卡片构建）
├── setup.mjs               # 交互式配置向导（生成 .env）
├── dsh-bundle-patch.json   # DSH 插件补丁声明（DSH Store 上架契约）
├── .env.example            # 配置模板
├── .session-cache.json     # 会话缓存（自动生成）
├── .chat-session-map.json  # 飞书chatId → DSH会话ID 映射（自动生成）
├── start-bot.bat           # Windows 启动脚本
└── package.json
```

## 会话管理说明

- 首次在某个聊天发消息 → bot 自动创建 DSH 会话并缓存映射
- 重启 bot → 自动复用缓存的会话，上下文不丢失
- `/new` → 创建新会话，旧会话保留可 `/switch` 回去
- `/list` → 只显示磁盘上实际存在的会话（过滤 DSH 内存缓存的残留）
- `/clean` → 查看手动清理旧会话的方法（DSH 无删除 API，需手动删文件）