Feishu Card v3 吸收方案：稳定、美观与升级省事

• HTML: https://decision.ht1072.top/2026-06-25-feishu-card-v3-absorption-plan.html
• Local HTML: [已移除本地路径]
• Generated: 2026-06-25T21:37:08+08:00

Feishu Card v3 吸收方案（草案）

结论

本方案建议以 Partial Absorb + Native Consolidation 方式吸收 baileyh8/hermes-feishu-streaming-card：不整包替换本机 Feishu card 体系，不引入它的 installer patcher 作为生产主链；重点吸收它的 流式事件协议、会话状态机、终态优先、footer 信息密度、doctor/status 诊断与升级 smoke 流程。

目标是三件事：

1. 更稳定：把 Feishu card 从散落的 send/edit/render 逻辑，收敛为事件 contract + card session + renderer + smoke matrix。
2. 更美观：吸收对方卡片的状态 header、工具摘要、密集但克制的 footer；保留本机 Card V2 原生 table、collapsible、分页、Decision Trace 入口。
3. 升级更省事：Hermes 升级后不再靠人工逐项想验证点，而是固定跑 Feishu Card Upgrade Pack。

一句话：用对方项目补“流式状态与诊断”，用我们现有体系保“最终展示、长内容治理和平台稳定性”。

背景与目标

涛哥当前关注点不是“能不能发 card”，而是：

• 展示更稳定，少出现最终卡空、重复灰色文本、footer 丢、长内容吞、表格 raw markdown。
• 视觉更像一个成熟 agent 输出面，不只是 markdown 外壳。
• Hermes 升级时尽量减少 patch 回归负担，形成固定流程。
• 在最终定稿前先看清外部项目推送 card 的外观与效果。

已查看外部项目公开预览与官方样例。它的卡片视觉优点主要是：

• 顶部状态明显：思考中 / 已完成用不同 header 颜色区分。
• 工具调用摘要清楚：工具调用次数与状态直接显示。
• footer 信息多：耗时、模型、token、context 等更适合技术用户审计。
• 流式状态切换强：同一张 card 从 thinking 更新到 completed。

但它的生产接入风险也明确：主路径依赖 Hermes runtime hook patch，不适合直接替换本机主链。

吸收边界

吸收

• 事件协议：message.started、thinking.delta、answer.delta、tool.updated、message.completed、message.failed、interaction.requested。
• 状态机：CardSession 累积 answer/thinking/tools/footer，并用终态事件收口。
• 终态优先：completed final answer 优先，completed-only 模型也能落完整 card。
• update 合并：非终态限频，终态立即 flush。
• footer 信息密度：duration、provider_model、input_tokens、output_tokens、context_pct、tool_count、sent_at。
• doctor/status/smoke：诊断配置、凭据、builder、真实发送、升级 smoke matrix。

不吸收

• 不吸收外部项目的 gateway/run.py patcher 作为生产主链。
• 不吸收一行安装脚本。
• 不让 sidecar 成为默认 Feishu 出口。
• 不用它的 card renderer 替换本机 feishu_cards.py。
• 不把所有回复都变成一张持续更新的 streaming card。
• 不牺牲本机 Decision Trace HTML/wiki/retain 长内容治理。

目标架构

Hermes runtime / GatewayStreamConsumer
        ↓
FeishuCardEvent contract
        ↓
FeishuCardSession
        ↓
FeishuCardV3Renderer
        ↓
FeishuAdapter send / update / fresh-final fallback
        ↓
Feishu Card Upgrade Pack 验收

模块分工

展示体系设计

Card v3 视觉原则

1. 状态清晰：header 一眼看到 thinking/completed/failed/waiting。
2. 正文优先：结论、结果、核心回答必须展开，不被工具信息抢权重。
3. 工具透明但低噪声：工具摘要默认显示；超过 3 个工具折叠。
4. footer 更完整但克制：小字号、灰色、单行优先，debug 模式再展开。
5. 长内容不上 card：决策型长分析仍进入 Decision Trace HTML，只在 card 放短摘要和按钮入口。
6. 移动端优先：避免横向 field grid 滥用，状态/回执默认单列竖排。

推荐布局

┌ Header：状态 / 标题 / subtitle
├ Main：核心答案 / 结论 / 表格 / 短结构化内容
├ Tools：工具调用次数 + 状态摘要
├ Details：可选折叠区，放中间过程或长工具列表
└ Footer：duration · provider-model · tokens · context · sent_at

状态色

Footer v3 设计

外部项目的 footer 值得吸收。我们当前 runtime footer 已支持 model/provider、sent_at、context_pct、cwd，但缺少 duration 和 token usage。建议升级为两档。

Compact 默认版

11s · custom-HS-5.2 · in 12.8k / out 1.1k · ctx 34% · 20:55

Debug 扩展版

11s · custom-HS-5.2 · input 12,846 · output 1,142 · ctx 34% · tools 5 · default · 2026-06-25 20:55

配置建议

display:
  platforms:
    feishu:
      runtime_footer:
        enabled: true
        style: compact
        fields:
          - duration
          - provider_model
          - input_tokens
          - output_tokens
          - context_pct
          - sent_at

Debug 时：

display:
  platforms:
    feishu:
      runtime_footer:
        style: debug
        fields:
          - duration
          - provider_model
          - input_tokens
          - output_tokens
          - total_tokens
          - context_pct
          - tool_count
          - profile
          - sent_at

Footer 字段来源

稳定性设计

Event Contract

定义内部事件，不暴露为用户工具，不新增 core model tool。

@dataclass
class FeishuCardEvent:
    type: Literal[
        "message.started",
        "thinking.delta",
        "answer.delta",
        "tool.updated",
        "message.completed",
        "message.failed",
        "interaction.requested",
    ]
    chat_id: str
    message_id: str | None
    thread_id: str | None
    content: str = ""
    tool_name: str | None = None
    tool_status: str | None = None
    usage: dict[str, int] | None = None
    metadata: dict[str, Any] = field(default_factory=dict)

CardSession 行为

started → 创建 session
thinking.delta → 累积 thinking_text，仅用于中间态
answer.delta → 累积 answer_text
工具事件 → 更新 tool list
completed → 用 final answer 覆盖中间态，补 footer，立即 flush
failed → 输出失败卡，保留已完成工具摘要

终态优先规则

1. message.completed.answer 非空：最终正文使用 completed answer。
2. completed answer 为空但 answer delta 非空：使用 delta 累积结果。
3. completed-only 模型没有 delta：允许 completed 直接填充最终 card。
4. final card 成功后，禁止再发原生重复最终文本。
5. final update 失败时，优先 fresh-final 发送完整 card；旧预览 best-effort 删除或保留。

Update 合并

• 非终态 update 限频：300–800ms。
• 工具状态批量合并：同一工具最后状态覆盖旧状态。
• 终态事件立即 flush。
• 连续 PATCH 失败超过阈值：禁用 progressive update，走 final card。
• Feishu API 返回 payload invalid：降级 plain text，但记录 doctor signal。

升级省事方案：Feishu Card Upgrade Pack

Hermes 升级后只跑固定矩阵，不再临场想验证点。

8 项 Smoke Matrix

Doctor 检查

tools/feishu_card_doctor.py --explain 输出：

Feishu Card Doctor
✅ runtime footer enabled for feishu
✅ Card v3 builder import ok
✅ schema 2.0 payload generation ok
✅ table element generation ok
✅ decision trace guard enabled
✅ Feishu credentials present
⚠️ streaming PATCH disabled in this profile, final-card fallback active

--json 机器可读：

{
  "ok": true,
  "builder": {"import": "ok", "schema": "2.0"},
  "footer": {"enabled": true, "fields": ["duration", "provider_model", "input_tokens", "output_tokens", "context_pct", "sent_at"]},
  "smoke": {"payloads": "8/8"},
  "warnings": []
}

升级验收命令

python -m pytest tests/gateway/test_feishu_cards.py -q
python -m pytest tests/gateway/test_feishu_runtime_footer.py -q
python tools/feishu_card_smoke_matrix.py --preview
python tools/feishu_card_doctor.py --explain
python tools/feishu_card_smoke_matrix.py --send-test --chat-id <test_chat>

验收产物

每次升级保留：

• artifacts/feishu-card-smoke/<date>/payloads/*.json
• artifacts/feishu-card-smoke/<date>/preview.html
• artifacts/feishu-card-smoke/<date>/preview.png
• artifacts/feishu-card-smoke/<date>/result.json
• 一张 Feishu 升级验收 card

实施阶段

Phase 0：冻结基线

目标：先知道当前体系不能丢什么。

动作：

1. 生成当前 8 类 card payload fixture。
2. 生成当前 preview HTML/PNG。
3. 记录当前 footer 输出。
4. 记录不可回退能力：table、collapsible、分页、Decision Trace guard、compact receipt、footer signature。

验收：

• 当前 8 类 fixture 可生成。
• preview 可打开。
• 真实测试 chat 可收到至少 3 类 card。

Phase 1：Footer v3

目标：先吸收最稳、最直接的收益。

改动：

• gateway/runtime_footer.py 支持 duration/input_tokens/output_tokens/total_tokens/tool_count/profile。
• gateway/run.py 在 final response 构建时传入 usage/duration。
• gateway/platforms/feishu_cards.py 保持 footer 独立灰色小字。
• 新增 tests：format、config、Feishu card footer split。

验收：

• compact footer 正常。
• debug footer 正常。
• footer 不污染正文分类。
• Feishu card footer 显示在末尾，不触发错误 header color。

Phase 2：Card v3 Preview 与视觉基线

目标：先出 mock，不直接改 live。

动作：

1. 新增 preview generator。
2. 做 3 张 mock：短结论、表格报告、长决策入口。
3. 对比外部项目样式：状态 header + 工具摘要 + footer。
4. 涛哥确认后再进入 live builder。

验收：

• preview 图可读、美观、移动端不过密。
• footer 信息密度接近外部项目，但不喧宾夺主。
• 表格/折叠/Decision Trace 仍保留本机风格。

Phase 3：Card v3 Renderer

目标：把视觉基线接入 builder。

动作：

• 在 feishu_cards.py 增加 v3 渲染 helper，或拆成 feishu_card_v3.py。
• 保留现有 classification，不大改分流。
• 只替换部分 card kind 的布局。
• 加 payload invariant tests。

验收：

• S1–S5 payload tests 通过。
• 真实 Feishu smoke 通过。
• 长内容仍触发 Decision Trace。

Phase 4：FeishuCardSession Streaming Final

目标：解决 streaming final 稳定性。

动作：

• 新增轻量 CardSession。
• 先只接 streaming final 路径。
• 支持 completed-only fallback。
• 支持 tool summary。
• update 失败进入 final fresh card fallback。

验收：

• answer delta + completed：最终 card 完整。
• completed-only：最终 card 完整。
• 工具状态保留。
• 无重复灰色文本。

Phase 5：Doctor + Upgrade Pack

目标：升级流程固定化。

动作：

• 新增 tools/feishu_card_doctor.py。
• 新增 tools/feishu_card_smoke_matrix.py。
• 写入 Hermes upgrade SOP。
• 将 preview/result 归档到 artifacts。

验收：

• 升级后能一键生成 preview。
• 能一键发测试 chat。
• 能输出 json/explain 诊断。
• 失败时能指出是 footer、builder、Feishu API、credential、streaming 还是 Decision Trace guard。

Rollback 与保守开关

所有新增行为必须可回退。

建议配置：

display:
  platforms:
    feishu:
      card_version: v2          # v2 | v3
      card_v3_preview_only: true
      streaming_card_session: false
      runtime_footer:
        enabled: true
        style: compact

上线顺序：

1. 先 preview_only: true。
2. 再对测试 chat 开 v3。
3. 再对 DM 开 v3。
4. 最后再考虑 group/thread。

失败回退：

display:
  platforms:
    feishu:
      card_version: v2
      streaming_card_session: false

成功标准

稳定性

• Feishu card smoke matrix 8/8 通过。
• streaming final 不再重复发送原生文本。
• completed-only 模型能生成最终 card。
• PATCH 失败有 fallback，不导致空卡。

美观

• footer 信息比当前更完整。
• 短结论 card 不拥挤。
• 表格 card 不 raw markdown。
• 长决策只发入口，不吞飞书消息。
• 移动端阅读不横向挤压。

升级省事

• Hermes 升级后固定跑 Upgrade Pack。
• smoke 结果归档。
• 失败定位到具体层，不再靠人工猜。
• 本机 patch 保留清单与 card smoke 绑定。

初版任务拆解

T0：设计与 preview 确认

• 写本方案。
• 生成 3 张 Card v3 mock preview。
• 涛哥确认视觉方向。

T1：Footer v3

• 扩展 runtime_footer.py。
• 补 run 层 usage/duration 传递。
• 补 Feishu card footer rendering tests。

T2：Smoke Matrix

• 新增 preview generator。
• 生成 8 类 payload fixture。
• 输出 result.json。

T3：Card v3 Renderer

• 新增 v3 builder。
• 接 2–3 类低风险 card kind。
• 真实 Feishu smoke。

T4：Streaming Session

• 新增 CardSession。
• 接 streaming final。
• 验证 delta/completed/completed-only。

T5：Doctor 与 SOP

• 新增 doctor。
• 更新 Hermes upgrade SOP。
• 将结果沉淀到 skill/reference。

风险判断

最终推荐

采用 Feishu Card v3 渐进吸收路线：

1. 先定视觉和 footer。
2. 再做 smoke matrix。
3. 再接 renderer。
4. 最后才接 streaming session。
5. 全程 feature flag + preview + rollback。

这条路线比“完全替换成外部项目”更稳，也比“只保留现状”更能解决 footer、流式、升级验证的问题。

来源

• 外部项目主页：https://github.com/baileyh8/hermes-feishu-streaming-card
• 外部项目 README：https://github.com/baileyh8/hermes-feishu-streaming-card/blob/main/README.md
• 外部项目架构说明：https://github.com/baileyh8/hermes-feishu-streaming-card/blob/main/docs/architecture.md
• 外部项目事件协议：https://github.com/baileyh8/hermes-feishu-streaming-card/blob/main/docs/event-protocol.md
• 外部项目 release readiness：https://github.com/baileyh8/hermes-feishu-streaming-card/blob/main/docs/release-readiness.md
• 外部项目 v3.6.5 release notes：https://github.com/baileyh8/hermes-feishu-streaming-card/blob/main/docs/release-notes-v3.6.5.md
• 本机当前评估报告：https://decision.ht1072.top/2026-06-25-hermes-feishu-streaming-card-vs-local-feishu-card.html