飞书对话网关 kriskwok/dsh-feishu-gateway

dsh-feishu-gateway

npm version
License: MIT
GitHub stars

在飞书（Feishu/Lark）里与你的 DeepSeek Harness（DSH） agent 对话。

这是一个 DSH 插件 bundle：挂载飞书长连接监听器，每条飞书消息路由到稳定的 DSH 会话（通过 agents 服务的 resume 恢复，多轮对话保持在同一个会话），agent 的答复以 Markdown 富文本（post 消息的 md 标签）回复。支持 /new 开启全新会话、原生 Typing 表情处理中指示、长任务的流式进度卡片、权限审批与 ask_user_question 的点击即答卡片、以及主动推送。

功能

- 💬 完整对话 — 飞书私聊 / 群聊 @机器人 → DSH agent → 回复。群聊中每个话题（thread）都是独立的 DSH 会话，该话题下的所有对话都保持在同一会话里，直到发 /new。
- 🔁 会话保持 — 每个飞书会话（或群聊话题）对应一个 DSH 会话（agents.resume / agents.create）；发 /new（或"另起会话 / 新会话 / 重新开始 / 换个话题"）开启全新会话，群聊话题里发 /new 同样新开一个会话（该话题绑定新的 DSH 会话）。
- ⌨️ 原生 Typing 指示 — 处理期间机器人在你的消息上加一个 Typing 表情回复（同 hermes-agent 的飞书网关），回答未结束就一直显示，失败时换成 CrossMark。默认不再发"思考中…"提示语。
- 🎞 流式汇报 — 长任务持续汇报：一张实时交互卡片流式显示 agent 的思考、工具调用、回答草稿（reporting.mode: 'stream'，默认开启）；设为 reporting.mode: 'final' 则只显示最终结果。
- 🃏 点击即答卡片 — 权限审批（approval/request，如沙箱提权）与模型的 ask_user_question 工具会渲染成飞书交互卡片：点 ✅ 允许一次 / 🚫 拒绝或选项按钮即可作答。点击后回调响应会瞬间把卡片替换为已处理态（按钮移除、显示结果）并弹出 toast 确认。
- ✍️ Markdown 回复 — 用普通富文本（post）消息的 md 标签：粗体、行内代码、列表、链接原生渲染，无需卡片
- 🧩 Web-only 交互围栏降级 — 模型输出的 dsh-ui 交互组件围栏（如 dsh-genui）只在 Web UI 渲染；飞书渠道会自动降级成一行可读提示（提取标题，注明"请在 Web UI 查看"），不会出现裸 JSON 代码块
- 🤖 完整 agent 能力 — DSH agent 自带模型与工具（bash、文件、子代理…），完全自主
- 📨 主动推送 — 可选管理 HTTP API（/api/push），随时向用户/群推送文本、Markdown、卡片
- 🔌 无需公网 — 飞书长连接，不需要回调地址
- 🗂 持久化 — 飞书↔DSH 会话映射重启不丢

环境要求

- 已安装并构建的 DeepSeek Harness（dsh CLI），并配置好 DEEPSEEK_API_KEY （agent 直接使用 DSH 当前模型，无需另配）
- 一个飞书开放平台企业自建应用，已开启机器人能力（见下）

飞书应用配置

1. 飞书开放平台 → 创建企业自建应用。
2. 开启机器人能力。
3. 开通权限：im:message、im:message:send_as_bot（如需读取消息内容再加 im:message:send_as_bot:readonly），然后创建版本并发布。
4. 事件与回调 → 选择使用长连接接收事件，订阅 im.message.receive_v1（无需公网）。
审批/问答卡片的按钮点击（card.action.trigger）也走同一条长连接，无需回调地址。
5. 在飞书客户端搜索应用名，添加机器人为联系人。

Typing 表情与卡片按钮依赖机器人在会话内有消息交互权限（im:message）。
若表情接口被拒，网关会自动退回发送 hintText 提示语。

安装（作为 DSH 插件）

前提：本包已发布到 npm，且 dsh 命令可用。

推荐把网关挂载到 web profile：与 DSH Web UI 同进程运行，启动 Web UI 即同时启动飞书网关，两者共用同一个 DSH agent。也可以用独立 profile 运行（见文末「备选」）。

方式一（推荐）：挂载到 web profile

web profile 是 DSH 的默认图形界面 profile（dsh --profile web）。

1. 编辑 ~/.dsh/profiles/web/package.json，加入依赖与 bundle：

{
"name": "dsh-profile-web",
"private": true,
"dependencies": {
"@kriskwok/dsh-feishu-gateway": "^0.2.0"
},
"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-web-app",
"@kriskwok/dsh-feishu-gateway"
]
}
}
}

2. 在 web profile 目录安装依赖：

cd ~/.dsh/profiles/web && pnpm install

3. 编辑 ~/.dsh/profiles/web/cordis.patch.yml，填入飞书应用凭据：

- id: feishu-gateway
config:
feishu:
appId: cli_xxxxxxxxxxxxxxxx
appSecret: xxxxxxxxxxxxxxxxxxxxxxxx
http:
port: 3100 # 可选管理 API token: your-token

4. 启动（或重启）web profile：

dsh --profile web

也可以直接运行本仓库的一键脚本：./scripts/create-profile.sh （默认挂载到 web profile；--standalone 则创建独立 feishu profile）。

备选：独立 feishu profile

若不想通过 Web UI 使用，可让网关在独立 profile 中运行：

mkdir -p ~/.dsh/profiles/feishu && cd ~/.dsh/profiles/feishu

cat > package.json pnpm-workspace.yaml web profile 下的问答卡片：ask_user_question 的作答走唯一的
ctx.userQuestions provider 槽位。网关从不抢占该槽位（否则 Web UI 的 apiProxy 宿主会因 DUPLICATE_PROVIDER 启动失败）——它在服务边界包裹 service.ask 做桥接：飞书会话的提问用飞书卡片作答，其余会话继续走 Web UI provider。权限审批卡片在任何部署下都从飞书作答。独立 feishu profile 下，ask_user_question 与审批都在飞书卡片中作答。

会话共存与自愈

- 预设编排（有工具！） — 在 preset-roster 部署（如 web profile）下，飞书 agent 会从部署的 agent preset 编排（meta.agentPreset + preset mount），模型因此拿到工具，而不会把工具调用当成纯文本。
- 与 Web UI 共存 — 会话单 owner。当 Web UI 打开某会话后，飞书侧通过
agents.get() 接管正在运行的 agent 并驱动同一会话，不再报
"while it is live" / "already exists"；两个界面共享同一段对话。
- wedged 会话自愈 — 进程中途死亡留下永久冲突的会话（"already exists"）时，网关自动换一个新 session id，并把飞书会话映射重指向它，继续对话。

管理 HTTP API（可选）

设置 http.port 启用。端点：

- GET /health — 状态
- POST /api/push — 主动推送 { "receive_id": "ou_xxx", "receive_id_type": "open_id", "msg_type": "text", "content": "" }
- GET /api/sessions — 飞书↔DSH 会话映射概览

开发 bash
pnpm install
pnpm build # tsc → lib/
pnpm test # 离线自测

说明：@deepseek-ai/* 运行时由 DSH 宿主提供；本地类型检查从你的 deepseek-harness 检出目录 symlink（见发布检查清单）。

许可

MIT