飞书流式卡片桥cmfok/dsh-feishucard

dsh-feishucard — DSH ↔ 飞书流式卡片桥接

把飞书（Lark）机器人接入 DeepSeek Harness 的 Agent 会话——完全自研（非 fork）。官方 SDK 长连接收发（无需公网 IP/域名/隧道）、每聊天独立专属会话、/new /switch /list /help 命令、处理中表情回执，以及流式回复卡片：过程话语内联 + 工具调用折叠面板 + 限流/退避/熔断/文本兜底。

一个自研（非 fork）的飞书（Lark）聊天与 DeepSeek Harness agent 会话之间的桥接：官方 SDK 长连接（无需公网 URL）、每聊天独立专属会话、/new /switch /list /help 命令、输入中表情回执，以及流式回复卡片——内联 agent 过程话语、带状态符号的可折叠工具调用面板，以及限流 / 退避 / 熔断 / 纯文本兜底可靠性。

单包即用：Host 插件（桥接逻辑）+ helper 子进程（长连接）+ bundle 补丁（自动注册）。一个包，三部分：host 插件、长连接 helper 子进程，以及自动注册的 bundle 补丁。

独立自研，不依赖任何第三方 DSH 飞书插件。配置独立存放于 ~/.dsh-feishucard/；检测到旧生态路径（~/.cc-connect/）有配置时启动自动迁移一次。不要与其他 DSH 飞书插件同时安装（同一飞书 App 的 WS 长连接互踢）。
完全独立。配置存放于 ~/.dsh-feishucard/；若在 ~/.cc-connect/ 发现旧配置，会在启动时自动迁移一次。不要与其他 DSH 飞书插件同时安装（同一 app 上的两个 WS 长连接会互踢）。

⚠️ Windows 开发陷阱（2026-08-15 实测）：本包以 file: 依赖安装后，DSH profile 的 node_modules/dsh-feishucard/ 是实体副本而非软链——改源文件后 dsh 仍加载旧副本，改动“重启也不生效”。改代码后必须同步副本：cp index.js helper.cjs /node_modules/dsh-feishucard/（或重新 dsh plugin --profile web add dsh-feishucard），再重启 dsh。排查“改了没生效”先 md5sum 对比源与副本。

功能 / Features

- 长连接收发 / Long-connection messaging：im.message.receive_v1 官方 SDK WebSocket → 注入 Agent 会话 → 交互卡片回复同一会话，全程无需公网地址。官方 SDK WebSocket；无需公网 IP、域名或隧道。
- 流式回复卡片 / Streaming reply card：
- 收到消息即建卡「正在工作中…」，agent 干活时实时 PATCH 更新。卡片会立即出现，并在 agent 工作时通过 PATCH 实时更新。
- 过程话语（agent 每步说的话）按事件顺序内联可见。内联 agent 过程话语，按事件顺序。
- 工具调用折叠面板：🛠️ 每工具一行「状态符号 · 工具名 · 参数摘要 · 失败原因」，默认折叠。可折叠工具调用面板：每行包含状态符号、工具名、参数摘要、失败原因。
- 完成 sealed：最终回复入卡、状态行消失、面板保持折叠。以最终回复封卡；状态行移除。
- 可靠性：串行更新队列 + 400ms 限流合并 + 指数退避 + 5 次熔断 + 15s 超时 + 卡片失败自动降级纯文本。串行队列、400ms 合并、指数退避、5 次失败熔断、15s 超时、文本兜底。
- 每聊天独立会话 / Dedicated per-chat sessions：每个飞书聊天专属 Agent 会话池（绝不串进 GUI 会话）；首条消息自动创建；持久化 + 重启恢复（live 会话直接复用、上下文不丢）；/new [名称]、/switch 、/list、/help。绝不共享 GUI 会话；首条消息自动创建；live 会话跨重启复用，因此上下文得以保留。
- 处理中表情 / Typing reaction：消息到达加 OnIt，回复送达后撤销（reactionEmoji 可配，none 关闭）。消息到达时添加 OnIt 表情，送达后移除。
- 工具 / Model tool：feishu_send（agent 主动发消息，appId 指定机器人，缺省发到最近会话）。Agent 主动发消息。
- 审批卡片 / Approval card：dsh 会话的工具调用需要确认时（audit 哨兵等），飞书弹出交互卡片「✅ 允许一次 / ❌ 拒绝」按钮，点击即回决策（card.action.trigger 长连接事件）；5 分钟超时自动拒绝、会话取消自动取消——避免飞书通道下审批无人应答导致会话永久挂起。插件自有会话的审批 approval/request 通过按钮卡片应答；超时自动拒绝。
- 保活 / Keep-alive：helper 崩溃自动重启（5s 冷却防重复）+ 凭据变更自动重连 + SDK 自带重连 + 状态可观测。崩溃后带 spawn 冷却自动重启、自动重连、连接状态可观测。
- 多机器人 / Multi-bot：一个实例多个机器人，各自绑定工作区。一个实例，多个机器人，各自一个工作区。

快速开始 / Quick Start

dsh plugin --profile web add dsh-feishucard
dsh web   # 重启 / restart

首次安装若提示 ERR_PNPM_IGNORED_BUILDS（pnpm ≥10 默认拦截 protobufjs 构建脚本）：编辑 $DSH_HOME/profiles/web/pnpm-workspace.yaml，把 allowBuilds 下的 protobufjs 改为 true 后重跑安装命令。
若 pnpm 拦截 protobufjs 的构建脚本，在 profile 的 pnpm-workspace.yaml 中把 allowBuilds.protobufjs 设为 true，然后重跑安装。

本地开发安装 / local install: dsh plugin --profile web add  或 file:。

配置 / Configuration

写在 ~/.dsh-feishucard/feishu.config.json（与仓库解耦 / decoupled from any repo）：

{
"bots": [
{
"name": "我的机器人",
"workspace": "C:\\path\\to\\workspace",
"appId": "cli_xxxxxxxxxxxxxxxx",
"appSecret": "your_app_secret",
"reactionEmoji": "OnIt"
}
]
}

会话状态持久化在 ~/.dsh-feishucard/state-.json。配置支持热更新（10 秒轮询），改完无需重启。会话状态持久化到 ~/.dsh-feishucard/state-.json；配置每 10 秒热重载。

从旧插件迁移 / migrating from the legacy plugin：无需手动操作。首次启动若新路径无配置而 ~/.cc-connect/feishu.config.json 存在，自动复制迁移（日志 migrated config from legacy ...）。无需任何操作——首次启动时会自动复制旧配置。

飞书开放平台一次性配置 / One-time Feishu Open Platform setup

- 创建企业自建应用，启用机器人 / create an enterprise self-built app, enable the bot
- 权限 / permissions：im:message.p2p_msg:readonly、im:message.group_at_msg:readonly、im:message:send_as_bot、im:message.reaction（可选 / optional）
- 事件与回调 → 订阅方式选「使用长连接接收事件」→ 添加事件 im.message.receive_v1 / events & callbacks → long-connection mode → add im.message.receive_v1
- 创建版本并发布 / create a version and publish

架构 / Architecture

飞书开放平台 ⇄ WebSocket 长连接 ⇄ helper.cjs（官方 SDK WSClient / official SDK）
⇅ stdout JSON 行（ready/status/event/error）
index.js（Host 插件，id=feishu-stream）
⇅ ctx.agents（dedicated 会话）/ fetch（卡片 API）
Agent 会话（绑定配置工作区 / bound workspace）

- 事件轮询：agent.session.events（assistant/message → note；tool/call、tool/result → 工具面板），300ms 轮询 + seal 前补扫（快速回合不丢中间过程）。300ms 轮询加上 seal 时的补扫，让快速回合也能保留其叙述过程。
- 会话恢复 / session recovery：优先复用 live 会话（agents.list() 命中 → 上下文保留），其次 resume 持久化会话，最后才新建。优先复用 live 会话，其次 resume 持久化会话，最后才新建。
- 卡片 / card：POST /im/v1/messages 创建 → PATCH /im/v1/messages/{id} 更新 → sealed 终态。
- 配置热读 / hot config：10s 轮询；helper 每机器人一个子进程，崩溃自动重启（5s 冷却）。每个机器人一个 helper 子进程，崩溃后以 5s 冷却自动重启。

开发 / Development

npm i                          # 安装依赖 / install deps
npm run check                  # node --check 语法检查 / syntax check
npm run smoke                  # 冒烟测试：mock DSH ctx + mock 飞书 API，跑完整回合链路

冒烟测试覆盖 / covered by the smoke suite：helper 注册、入站消息管线（会话创建/消息投递）、流式卡片（create/PATCH/schema/工具面板/状态符号/note/seal）、命令处理、链路稳定性。Helper 注册、入站管线、流式卡片生命周期、命令、端到端稳定性。

License

MIT