dsh-feishucard — DSH ↔ Feishu Streaming Card Bridge
把飞书（Lark）机器人接入 DeepSeek Harness 的 Agent 会话——完全自研（非 fork）。官方 SDK 长连接收发（无需公网 IP/域名/隧道）、每聊天独立专属会话、/new /switch /list /help 命令、处理中表情回执，以及流式回复卡片：过程话语内联 + 工具调用折叠面板 + 限流/退避/熔断/文本兜底。
A self-developed (not a fork) bridge between Feishu (Lark) chats and DeepSeek Harness agent sessions: official-SDK long connection (no public URL needed), dedicated per-chat sessions, /new /switch /list /help commands, a typing reaction, and a streaming reply card — inline agent notes, collapsible tool-call panels with status symbols, and rate-limit / backoff / circuit-breaker / plain-text fallback reliability.
单包即用：Host 插件（桥接逻辑）+ helper 子进程（长连接）+ bundle 补丁（自动注册）。One package, three pieces: host plugin, long-connection helper subprocess, and an auto-registered bundle patch.
独立自研，不依赖任何第三方 DSH 飞书插件。配置独立存放于 ~/.dsh-feishucard/；检测到旧生态路径（~/.cc-connect/）有配置时启动自动迁移一次。不要与其他 DSH 飞书插件同时安装（同一飞书 App 的 WS 长连接互踢）。
Fully independent. Config lives in ~/.dsh-feishucard/; a legacy config found at ~/.cc-connect/ is auto-migrated once on boot. Do not install alongside other DSH Feishu plugins (two WS long connections on one app kick each other).
⚠️ Windows 开发陷阱（2026-08-15 实测）：本包以 file: 依赖安装后，DSH profile 的 node_modules/dsh-feishucard/ 是实体副本而非软链——改源文件后 dsh 仍加载旧副本，改动"重启也不生效"。改代码后必须同步副本：cp index.js helper.cjs <profile>/node_modules/dsh-feishucard/（或重新 dsh plugin --profile web add dsh-feishucard），再重启 dsh。排查"改了没生效"先 md5sum 对比源与副本。
⚠️ 重启 dsh web 必须走带 key 的启动器（2026-09-08 事故教训）：部署机上 DEEPSEEK_API_KEY 通常放在用户环境变量（Windows 注册表 HKCU\Environment）——它不在 dsh 凭据文件里、dsh 也没有 .env 层去读它。裸 node <dsh包>/lib/bin.js web 启动 = 进程没有 key = 所有 LLM 调用失败 = 飞书全部空白回复。需要重启时，请通过你本机的 dsh 启动脚本/计划任务（会先注入用户环境变量再拉起 dsh）；不要 kill 进程后用裸 node 拉起。排查"为什么空白回复"先看进程环境里有没有 DEEPSEEK_API_KEY。
⚠️ session 事件 API 跨版本差异（2026-09-14 事故教训）：DSH **0.1.0-rc.5（公开版）**暴露的是
agent.session.events（数组，下标=seq）；0.1.2-rc.1（内含 dev 版）把它废弃为
agent.session.snapshotEvents()。两者不通用——写死任一版本都会在另一版本上炸
（0.1.0-rc.5 上写死 snapshotEvents 的症状 = 入站消息一进 runTurn 就
TypeError: snapshotEvents is not a function，机器人收消息但永不回复）。
本包统一走 sessionEvents(session) 兼容取值（有 snapshot 用 snapshot，否则退回 events），
改这块代码前先确认目标版本的真实 API（以部署机上实际运行的那版为准，不是 dev 仓库）。
功能 / Features
-
长连接收发 / Long-connection messaging：im.message.receive_v1 官方 SDK WebSocket → 注入 Agent 会话 → 交互卡片回复同一会话，全程无需公网地址。Official SDK WebSocket; no public IP, domain, or tunnel required.
-
流式回复卡片 / Streaming reply card：
- 收到消息即建卡「正在工作中…」，agent 干活时实时 PATCH 更新。A card appears instantly and is PATCH-updated live as the agent works.
- 过程话语（agent 每步说的话）按事件顺序内联可见。Inline agent narration, in event order.
- 工具调用折叠面板：🛠️ 每工具一行「状态符号 · 工具名 · 参数摘要 · 失败原因」，默认折叠。Collapsible tool-call panels: status symbol, tool name, arg summary, failure reason per line.
- 完成 sealed：最终回复入卡、状态行消失、面板保持折叠。Sealed with the final reply; status line removed.
- 可靠性：串行更新队列 + 400ms 限流合并 + 指数退避 + 5 次熔断 + 15s 超时 + 卡片失败自动降级纯文本。Serialized queue, 400ms coalescing, exponential backoff, 5-failure breaker, 15s timeout, text fallback.
-
每聊天独立会话 / Dedicated per-chat sessions：每个飞书聊天专属 Agent 会话池（绝不串进 GUI 会话）；首条消息自动创建；持久化 + 重启恢复（live 会话直接复用、上下文不丢）；/new [名称]、/switch、/list、/plan [off]、/goal、/stop、/help。Never shares GUI sessions; auto-created on first message; live sessions are reused across restarts so context is preserved.
-
处理中表情 / Typing reaction：消息到达加 OnIt，回复送达后撤销（reactionEmoji 可配，none 关闭）。OnIt reaction added on arrival, removed after delivery.
-
工具 / Model tool：feishu_send（agent 主动发消息，appId 指定机器人，缺省发到最近会话）。Proactive messaging from the agent.
-
审批卡片 / Approval card：dsh 会话的工具调用需要确认时（audit 哨兵等），飞书弹出交互卡片「✅ 允许一次 / ❌ 拒绝」按钮，点击即回决策（card.action.trigger 长连接事件）；10 分钟超时自动拒绝（2026-09-16 由 3 分钟延长；卡面文案由 APPROVAL_TIMEOUT_MIN 推导，不再写死）、会话取消自动取消——避免飞书通道下审批无人应答导致会话永久挂起。Approval approval/request for plugin-owned sessions is answered via a button card; timeout auto-rejects.
-
保活 / Keep-alive：helper 崩溃自动重启（5s 冷却防重复）+ 凭据变更自动重连 + SDK 自带重连 + 状态可观测。Crash-restart with spawn cooldown, auto-reconnect, observable connection status.
-
多机器人 / Multi-bot：一个实例多个机器人，各自绑定工作区。One instance, many bots, one workspace each.
-
目标模式进度卡 / Goal-round progress cards（2026-09-16，CM 拍板方案 A）：目标模式（goal 模式）的续轮不经过飞书入站，过去在飞书完全看不到它在干什么。现在插件订阅 ：某轮由目标轮驱动 → 自动建卡「🎯 目标模式 · 第 N 轮开始，正在工作…」，流式卡（过程话语 / 工具面板 / 表格换卡全部生效），轮结束封口写「✅ 本轮结束」。只报目标轮，其它自动回合不建卡（不刷屏）。Goal-round continuations never pass through Feishu inbound, so they used to be invisible; an hook now opens the same streaming card per goal round.
快速开始 / 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 后重跑安装命令。
If pnpm blocks protobufjs's build script, set allowBuilds.protobufjs to true in the profile's pnpm-workspace.yaml and re-run.
本地开发安装 / 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-<appId>.json。配置支持热更新（10 秒轮询），改完无需重启。Session state persists to ~/.dsh-feishucard/state-<appId>.json; config is hot-reloaded every 10s.
开关 / Switches（环境变量作用于整个插件进程 / env vars are process-wide）：
| 变量 / Variable | 缺省 / Default | 作用 / Effect |
|---|
DSH_FEISHU_GOAL_CARDS | 1（开） | 设 0 全局关闭「目标模式进度卡」。Set 0 to disable goal-round progress cards. |
DSH_FEISHU_APPROVAL | 0（关） | 设 1 恢复飞书审批拦截卡片（CM 2026-09-16 拍板默认关闭，不许改回）。 |
FS_CONFIG_DIR | ~/.dsh-feishucard | 配置文件目录（测试用）。 |
per-bot 配置项 notifyGoalRounds（false 关闭该机器人的目标卡）写在 feishu.config.json 的对应 bot 里。Per-bot notifyGoalRounds: false disables goal cards for that bot only.
从旧插件迁移 / migrating from the legacy plugin：无需手动操作。首次启动若新路径无配置而 ~/.cc-connect/feishu.config.json 存在，自动复制迁移（日志 migrated config from legacy ...）。Nothing to do — the legacy config is copied automatically on first boot.
飞书开放平台一次性配置 / 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 polling plus a seal-time catch-up scan so fast turns keep their narration.
- 会话恢复 / session recovery：优先复用 live 会话（
agents.list() 命中 → 上下文保留），其次 resume 持久化会话，最后才新建。Reuse live sessions first, then resume persisted ones, create only as a last resort.
- 卡片 / card：
POST /im/v1/messages 创建 → PATCH /im/v1/messages/{id} 更新 → sealed 终态。
- 配置热读 / hot config：10s 轮询；helper 每机器人一个子进程，崩溃自动重启（5s 冷却）。One helper subprocess per bot, crash-restarted with a 5s cooldown.
开发 / 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 registration, inbound pipeline, streaming card lifecycle, commands, end-to-end stability.
License
MIT
