dsh-feishucard

dsh plugin --profile web add dsh-feishucard

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.

📌 需求与功能状态的唯一登记处 = 需求与功能清单.md（2026-10-06 结论建立：「所有的功能清单放在那里，我提需求就在里面补一句，完成了就打个勾」）。

接手前先读它：☐=没做，🔴=已结论但没实现（漂移，优先做），✅ 才有证据。本 README 只放门面与部署现状，CHANGELOG.md 记"哪版改了什么"，功能基线.md 记"哪条判据由哪个用例钉住"。

功能矩阵 / Feature matrix

功能 · 说明

流式回复卡片 · 过程话语内联 + 工具调用折叠面板（带状态符号）+ 内联 agent 备注；失败时纯文本降级

单实例多 bot · 一个 DSH 实例挂多个飞书机器人，各自绑定 workspace 与 AGENTS.md

群里 @ 才回复 · 群聊只在被 @ 时处理（避免多 bot 互相刷屏）；单聊照常全处理

审批卡 / 提问卡 · 工具审批与 ask_user_question 直接落到飞书卡片，点按钮即回

/switch 两级选择 · 先选工作区（与 GUI 侧边栏同源），再选会话：接管或新建；另有 /list /new /help

身份注入 · 入站消息按 open_id 解析为「人」；工具入参里的身份字段由身份表覆写

Agent 互认（0.8.0） · 群里 @ 到了谁、这条消息是谁发的、卡片被谁点的——三个身份都会标注并喂给 agent；出站 @[名字] 展开成真 @（能唤醒对方 bot）。🔴 只标注、不授权：权限仍然只认身份闸门解析出来的那个人

bot 名单采集 · scripts/collect_bot_roster.mjs 采集同群 bot 的 union_id / 本应用视角 ou，插件按 mtime 热读。飞书成员接口只返回人不返回 bot（真机取证 V5），所以名单必须自己采

群接力（默认关） · groupRelay 默认 self_only＝与旧版一字不动（没 @ 本 bot 的群消息一律忽略）；显式 opt-in 才放宽，内置三层防互刷预算

长连接收发 · 官方 SDK WebSocket 长连接，无需公网 IP / 域名 / 隧道

可靠性兜底 · 限流 / 退避 / 熔断 / 纯文本降级；helper 崩溃后可自动拉起

English summary: streaming reply card, many bots in one instance (own workspace + AGENTS.md each),

mention-gated group replies, approval / ask cards, two-level /switch picker, identity injection,

long-connection transport, and rate-limit / backoff / circuit-breaker / text fallback.

Since 0.8.0 also: agent mutual recognition (who was mentioned, who sent the message, who tapped the

card — annotated for the agent, never used as authorization), outbound @[name] that really pings

another bot, a collected bot roster, and an opt-in group relay with anti-loop budgets (default off).

单包即用：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).

✅ 更正（2026-10-02 实测，推翻本文件 2026-08-15 / 2026-09-18 的旧结论）：本机 DSH profile 里

~/.dsh-feishucard/feishu.config.json 是目录联接（Junction），直接指向本仓库

（Get-Item 报 LinkType: Junction、Target: <本仓库路径>）⇒ 改源码 = 改 profile 副本，

配合 @deepseek-ai/dsh-hmr（0.2 起；0.1.x 时期为 cordis-plugin-hmr）保存即热重载。

实证：2026-10-02 同一轮里连续 4 次保存，日志依次出现 plugin apply #8 / #9 / #10 / #11，

每次的 md5 / bytes 都与源码一致。

旧结论「实体副本、HMR 覆盖不到源码、必须 sync + 重启」在本机不成立，已作废。

若你的安装方式不是 Junction（例如 file: 物化出实体副本），npm run sync 仍是正确兜底 ——

体检 + 备份 + 同步 + 哈希复验，--dry-run 只体检（退出码非 0 = 副本与源码不一致）。

复验"线上跑的是哪一版"：grep 'plugin apply' <dsh日志>，行内含 v<版本> md5=<前8位> bytes=<大小>。

Corrected 2026-10-02: on this machine the profile entry is a junction to this repo, so the HMR

watcher and the running copy coincide — saving the source hot-reloads the plugin (verified:

plugin apply #8–#11 on four consecutive saves). The older "copy, not symlink ⇒ sync + restart

required" note is stale; npm run sync remains the correct fallback for non-junction installs.

⚠️ 重启 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、/compact（压缩上下文；agent 空闲时才可用）、/stop、/help。Never shares GUI sessions; auto-created on first message; live sessions are

…(truncated)