飞书授权卡片通道方案（DSH 引擎层扩展 approval-feishu + auth_request.py 发卡，dsh-im 零修改）

[evilh2019]

方案背景

飞书通道的提权审批需要发交互式授权卡片（用户点卡片按钮直接授权），web GUI 通道维持浏览器弹窗，两通道互不混淆。

设计硬约束：dsh-im 插件升级必须天然继承此能力 → 因此禁止修改 dsh-im 源码，方案完全落在 DSH 引擎层。

架构

approval/request (DSH 引擎, 飞书会话)
  → approval-feishu 引擎扩展 (只拦 agentPreset 匹配 *-feishu 的会话, 其余 next())
  → auth_request.py 发卡 (lark-cli im +messages-send, Card 1.0 横排按钮)
  → 用户点击 (card.action.trigger)
  → dsh-im 已有回调处理: 写状态文件 + message.patch 原卡
  → auth_request.py 轮询状态文件 → exit 0/1
超时 (默认 300s) → 先写状态文件 timeout, 再 patch 原卡为灰化过期态

• DSH 引擎 extensions/approval-feishu（packages/extensions/ 下的私有扩展）
• 发卡脚本 auth_request.py（独立工作区，lark-cli 发送，零 LLM 依赖）
• dsh-im 仅作为消费方：收 card.action.trigger → 写 authDir/<auth_id>.json → message.patch 结果卡

授权卡 UX（已全部实测验收）

1. 有效期显示：卡片正文 ⏱️ 有效期 N 秒（截止 HH:MM:SS），超时自动失效
2. 超时自动更新：lark-cli api PATCH /open-apis/im/v1/messages/{id} 更新原卡
3. 按钮横排：Card 2.0 不支持 action 容器（按钮只能竖排）→ 迁移 Card 1.0（顶层 elements + {"tag":"action"}），按钮一行横排；Card 1.0 按钮 value 字段与 dsh-im 回调原生兼容
4. 超时灰化 disabled：保留按钮但全部 disabled:true + disabled_tips:"授权已过期，请重新发起"，header 变灰

双层防线（超时后点击双重拒绝）

层	机制
逻辑层	状态文件先写 timeout；dsh-im 见 status !== 'pending' 直接 return
UI 层	patch 灰化 disabled 按钮，视觉不可点

顺序铁律：必须先写状态文件 timeout、再 patch 卡片，否则 patch 期间（≤30s）状态仍 pending，点击会被接受（竞态漏洞，已修复）。

Schema 匹配铁律

message.patch 要求 patch 卡片与原消息 schema 一致：Card 1.0 原消息必须 Card 1.0 结构 patch，Card 2.0 必须 Card 2.0 结构——不一致报 230099。patch_card_expired 内置容错：Card 1.0 失败自动改 Card 2.0 重试。

升级继承

dsh-im tgz 升级天然不影响（零修改）；DSH 侧三处改动均有备份/恢复路径（upgrade-dsh.sh --backup/--restore + $DSH_HOME patch + 独立工作区脚本）。

讨论点

1. 此方案作为 DSH 引擎层扩展，是否有更合适的归属/打包方式？（当前是私有扩展，未进官方仓库）
2. 审批卡片通道是否有进官方 packages/extensions/ 的价值？还是保持社区私有扩展？
3. 卡片 UX（有效期/超时灰化/横排）是否有可改进处？

E2E 实测证据：5 条闭环（授权通过 / 60s 超时自动更新 / Card 1.0 横排点击 / 灰化 disabled / 僵尸卡 schema 容错）。

[denial123789]

这个方向里，把飞书接在 approval/request waterfall 上是对的：rc.2 的 answerer 本来就应当只处理自己拥有的请求，否则 next()。但如果 Web 和飞书可能同时观察同一个审批，建议再收紧几处边界：

1. 一个审批只能有一个 decision owner。 Web/飞书可以是多个展示 observer，但不能成为并列的终态写入者。*-feishu 后缀适合作为原型路由提示；长期更稳的是 Session 创建时写入显式、不可变的 ApprovalChannelBinding。
2. 卡片点击不是天然可信的批准。 服务端应校验并绑定 tenant/app、actor/role、chat/channel、runtime/session、approval id、call id、outcome、nonce、issued/expiry 和 card schema。可用短期签名 opaque token，或高熵 token 对应的服务端记录；转发卡片本身不能授予权限。
3. 不要让卡片暗示展示了 rc.2 没有提供的内容。 当前 approval/request 只有 tool、reason 和可选 call id，没有 tool arguments；因此卡片不能声称用户审核了“完整命令/参数”。若要展示，需另加受控 disclosure seam。
4. 超时先落盘再禁用卡片的顺序合理，但普通 JSON 的 check-then-write 不是 exactly-once。 点击和超时必须争用同一个原子 CAS：pending -> allowed-once | rejected | cancelled，只有胜者返回 outcome；迟到点击只得到 stale/expired，不得覆盖或重新打开。
5. ApprovalService 应继续拥有成对的 approval/asked / approval/decided 审计。 answerer 只返回 outcome，避免脚本和服务各写一份、产生不一致记录。卡片 patch 是派生投影，patch 失败不得改变或重开决定。
6. Card 1.0/2.0 不应靠失败后猜测切换。 创建时持久化确切 schema 与 message id，后续更新按同一 schema 执行。
7. 打包上建议先做受支持的 out-of-tree plugin。 Feishu adapter 负责验签、身份映射和 UI；core 只需要 provider-neutral 的 binding、identity 与 settlement seam。dsh-im callback 即使不改主流程，也应当版本化并做契约测试。生产环境最好用常驻受限服务替代轮询共享目录；若保留文件原型，目录权限、symlink 防护、原子 rename、文件 owner/mode、过期清理都需要进入验收。

我把这套模型、恢复语义和 36 个验收门整理成了可视化指南，便于直接对实现逐项检查：
https://sandbaseai.github.io/deepseek-harness-handbook/sdk-human-interaction-wire.html

核心结论可以压缩成一句：many observers, one decision owner; card state is a projection, not authority.