shrekcg/dsh-lark-bridge

DSH ↔ Feishu/Lark Bridge

将 DeepSeek Harness 接入飞书/Lark 的双向智能通道

---

项目简介

DSH ↔ Feishu/Lark Bridge 是一个把 DeepSeek Harness（DSH，AI Agent 运行时）接入飞书 / Lark 的完整双向通道插件。它在飞书里为你的 AI 助手提供「原生应用」般的完整体验：

• 💬 持久对话：跨消息上下文记忆，话题隔离，群聊/私聊
• ⌨️ 真流式输出：边生成边显示，平滑打字机效果
• 🛠️ 40 个飞书对象工具：agent 可直接操作文档、表格、日历、任务、邮件等
• 🧩 可插拔插件形态：不侵入 DSH 核心，一键安装/卸载

对齐 OpenClaw 飞书官方插件 的能力与体验，但基于 DSH 生态构建。

---

✨ 功能特性

💬 对话体验

特性	说明
持久会话	跨消息上下文记忆（DSH agents.resume）
话题隔离	每个话题独立上下文，如从主线 fork
群聊支持	不 @ 也响应，或按群细粒度策略（白名单/仅@）
思考表情	收到消息显示 THINKING，回复后自动移除
真流式输出	边生成边显示，平滑打字机（自适应节奏）
底部耗时	回复底部小字「已完成 · 耗时 xx」，对齐 OpenClaw
@ 用户渲染	回复中可 @ 用户/所有人（原生 mention）
Bot 互 @	支持 bot 间对话（可配置）

📎 消息能力

特性	说明
多媒体收发	图片/文件/音频/视频下载与发送
合并转发	合并转发消息识别与展开
表情反馈	👍/❤️ 等表情反馈给 agent
文档评论@	文档评论中 @ 机器人触发对话

🛠️ 飞书对象工具（MCP × 40）

通过 Model Context Protocol 暴露 40 个飞书工具，agent 以 mcp__feishu__* 原生调用：

类别	工具
消息	send_message read_messages search_chats get_chat_members search_messages read_thread_messages
文档	read_document create_document update_document doc_insert_media doc_list_comments
日历	calendar_agenda create_calendar_event calendar_freebusy calendar_search_events calendar_add_attendee
任务	get_my_tasks create_task task_create_subtask task_get_detail task_related task_add_comment
多维表格	base_read_records base_create_table base_create_record base_create_field base_create_view
电子表格	sheets_read
Wiki	wiki_search wiki_list_spaces wiki_create_node
邮件	mail_list mail_send
云盘	drive_search drive_list_folder
妙记/审批/搜索	minutes_search approval_list_todo search_docs
通讯录	get_user_info

🧩 平台能力

特性	说明
多账号多机器人	一个进程管理多个飞书 bot，session 自动隔离
可插拔插件	一键安装/卸载，不侵入 DSH 核心
初始化向导	npm run setup 6 步引导（应用/权限/授权/事件订阅）
诊断自修复	npm run doctor 21 项检查 + --fix 自动修复
功能清单	npm run features 查看各能力配置状态
权限管理	自动检测缺失权限，生成一键申请链接
CI	GitHub Actions 自动测试 + MCP 冒烟验证
渠道状态页	内置 HTTP 状态页，实时查看飞书在线/账号/健康（http://127.0.0.1:8899）
IM 机器人设置页	DSH 设置页「插件」内新增 IM 机器人 tab，展示渠道状态（web-plugin/）
斜杠命令	飞书对话内直接使用 /new /compact /model /status 等命令

⌨️ 斜杠命令

在飞书对话中直接输入命令（不消耗 AI 调用，即时响应）：

命令	说明
/help	显示所有可用命令
/new / /clear	开启新对话（清空当前会话上下文）
/compact	压缩当前会话（减少上下文）
/model [name]	查看 / 切换模型（如 /model deepseek-v4-flash）
/status / /state	查看当前状态（模型/会话/工具/运行时长）
/tools	列出可用飞书工具（40 个）
/features	查看功能配置清单
/doctor	运行诊断

---

📦 快速开始

前置依赖

依赖	说明
DSH	DeepSeek Harness 运行时
lark-cli	飞书官方 CLI（工具执行后端）
Node.js ≥ 18	运行环境

安装

# 1. 克隆
git clone https://github.com/shrekcg/dsh-lark-bridge.git
cd dsh-lark-bridge

# 2. 安装依赖
npm install

# 3. 初始化向导 (创建应用/授权/事件订阅 一步步引导)
npm run setup

# 4. 安装为插件 + 常驻服务
npm run install-bridge

# 5. 验证
npm run doctor        # 诊断 (21 项)
npm run features      # 功能清单

详细配置见 docs/SETUP.md 与 docs/INSTALL.md。

---

🔧 配置

配置通过环境变量或 config.json（见 config.example.json）：

变量	默认	说明
LARK_APP_ID	—	飞书应用 App ID
LARK_APP_SECRET	—	飞书应用密钥
REQUIRE_MENTION	false	群聊是否要求 @ 才响应
ALLOW_BOTS	false	bot 互 @：false/true/mentions
GROUP_POLICY	open	群策略：open/allowlist/closed
GROUP_ALLOW_FROM	—	群白名单（逗号分隔 open_id）
REACTION_NOTIFICATIONS	off	表情反馈：off/own/all
STREAM_THROTTLE_MS	60	流式节流时间阈值 (ms)
STREAM_THROTTLE_CHARS	3	流式节流字符阈值
ALLOW_USER_WRITES	—	允许 user 身份写操作（默认仅发消息用 bot）
DSH_BIN / DSH_HOME	—	DSH 路径

---

🚀 使用

对话

• 私聊：直接在飞书单聊机器人
• 群聊：拉机器人进群，直接发消息（或 @，取决于配置）
• 话题：在群消息上创建话题，获得独立上下文

飞书工具

直接用自然语言告诉 agent：

• 「帮我查一下今天的日程」
• 「创建一个文档，内容是……」
• 「给 XX 发一条消息」
• 「列一下我的待办任务」

管理命令

npm start                # 启动 bridge
# 状态页: 打开 http://127.0.0.1:8899 (飞书在线状态/账号/健康)
npm run setup            # 初始化向导
npm run doctor           # 诊断 (--fix 自动修复)
npm run features         # 功能配置清单
npm test                 # 运行测试 (65 用例)
npm run install-bridge   # 安装插件 + 常驻服务
npm run uninstall-bridge # 卸载 (可逆, 不影响 DSH 核心)
npm run mcp              # 单独运行 MCP server

---

🏗️ 架构

┌──────────────────────────────────────────────────┐
│                     飞书 / Lark                   │
│   用户私聊 · 群聊 · 话题 · 表情 · 评论 · 卡片交互   │
└───────────────────────┬──────────────────────────┘
                        │ WebSocket 长连接 (SDK)
┌───────────────────────▼──────────────────────────┐
│               bridge (常驻进程)                   │
│  ┌─────────┐ ┌────────────┐ ┌─────────────────┐  │
│  │ channel │ │  inbound   │ │    outbound     │  │
│  │ (SDK)   │ │ policy     │ │ stream (真流式)  │  │
│  │         │ │ media      │ │ mention (@渲染)  │  │
│  │         │ │ reaction   │ │ footer (耗时)   │  │
│  │         │ │ merge-fw   │ │                 │  │
│  └────┬────┘ └─────┬──────┘ └────────┬────────┘  │
│       └────────────┼─────────────────┘           │
└────────────────────┼─────────────────────────────┘
                     │ DSH headless (持久会话)
              ┌──────▼──────┐
              │  agents.resume│
              │  + MCP client │
              └──────┬──────┘
                     │ mcp__feishu__* (40 工具)
              ┌──────▼──────┐
              │ Feishu MCP  │
              │ server      │
              └──────┬──────┘
                     │ lark-cli
              ┌──────▼──────┐
              │  飞书 OpenAPI│
              └─────────────┘

• 接收：@larksuite/channel SDK WebSocket 长连接（无需公网回调地址）
• 会话：固定 session + DSH agents.resume（跨消息记忆）
• 工具：40 个 MCP 工具，lark-cli 执行后端

详见 docs/ARCHITECTURE.md。

---

📁 项目结构

dsh-lark-bridge/
├── src/
│   ├── index.js              # 入口 (多账号消息流水线)
│   ├── config.js             # 配置管理
│   ├── channel.js            # 飞书通道 (SDK + 流式)
│   ├── session.js            # 持久会话 + 互斥锁
│   ├── core/
│   │   ├── scope-manager.js  # 权限管理
│   │   ├── adaptive.js       # 流式自适应步长
│   │   └── pacing.js         # 流式节奏控制
│   ├── inbound/
│   │   ├── policy.js         # 群策略/bot/@
│   │   ├── media.js          # 多媒体接收
│   │   ├── reaction.js       # 表情反馈
│   │   ├── merge-forward.js  # 合并转发
│   │   └── comment.js        # 文档评论@
│   ├── outbound/
│   │   └── mention.js        # @渲染
│   ├── tools/
│   │   └── mcp-server.js     # 飞书 MCP server (40 工具)
│   └── commands/
│       ├── doctor.js         # 诊断自修复 (21 项)
│       └── features.js       # 功能配置清单
├── dsh-lark-session/         # DSH 插件 (持久会话 runner)
├── scripts/
│   ├── install.js            # 安装/卸载/状态
│   └── setup.js              # 初始化向导
├── tests/                    # 65 个单元测试
└── docs/                     # 文档

---

📚 文档

文档	说明
SETUP.md	详细配置指南
INSTALL.md	插件化安装指南
ARCHITECTURE.md	架构设计
README.en.md	English README

---

🧪 测试

npm test    # 65 个单元测试

CI（GitHub Actions）自动运行：单元测试 + 语法检查 + MCP server 冒烟验证。

---

📄 License

MIT

🙏 致谢

• DeepSeek Harness — Agent 运行时
• OpenClaw 及 飞书官方插件
• @larksuite/channel — 飞书 SDK
• lark-cli — 飞书 CLI