Decision Trace
DECISION TRACE · 复盘 · AUDITABLE RECORD

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

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

最终判断本方案建议以 Partial Absorb + Native Consolidation 方式吸收 baileyh8/hermes-feishu-streaming-card:不整包替换本机 Feishu card 体系,不引入它的 installer patcher 作为生产主链;重点吸收它的 流式事件协议、会话状态机、终态优先、footer 信息密度、d
记录日期2026-06-25
记录类型复盘
章节数量15
预计阅读~4 min
核心结论本方案建议以 Partial Absorb + Native Consolidation 方式吸收 baileyh8/hermesfeishustreamingcard:不整包替换本机 Feishu card 体系,不引入它的 installer patcher 作为生产主链;重点吸收它的 流式事件协议、会话状态机、终态优先、footer 信息密度、doctor/status 诊断与升级 smoke 流程。
  • 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 验收

模块分工

模块 职责 落点建议
Event Contract 标准化 started/delta/tool/completed/failed gateway/platforms/feishu_card_events.py
Card Session 累积正文、思考、工具、token、footer gateway/platforms/feishu_card_session.py
Card V3 Renderer 输出 CardKit v2 payload 继续扩展 gateway/platforms/feishu_cards.py 或拆 feishu_card_v3.py
Footer Adapter 统一 runtime footer 字段 gateway/runtime_footer.py
Smoke Matrix 生成 preview + 真实发送验证 tools/feishu_card_smoke_matrix.py
Doctor 检查配置/凭据/builder/send/update/log tools/feishu_card_doctor.py

展示体系设计

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

状态色

状态 header template icon 语义
thinking indigo / blue 🔄 生成中、工具执行中
completed green ✅ 成功完成
failed red / orange ❌ / ⚠️ 失败或部分失败
waiting orange ⏸️ 等用户确认 / approval / clarify
decision purple ⚖️ 决策、方案、吸收评估
data indigo 📊 表格、指标、报告

外部项目的 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
字段 来源 当前状态
provider_model model/provider config + runtime result 已有基础,需统一显示
sent_at runtime_footer 当前时间 已有
context_pct context_tokens / context_length 已有
cwd cwd / TERMINAL_CWD 已有,但 Feishu 默认不建议展示
duration turn start/end timestamp 需新增
input_tokens model usage 或 run result usage 需新增
output_tokens model usage 或 run result usage 需新增
total_tokens input + output 可选
tool_count tool call events 计数 需从 stream/tool layer 注入
profile Hermes profile id 可选 debug

稳定性设计

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

编号 场景 输入样例 成功标准
S1 短普通回复 一句话确认 不被错误包成长卡,显示完整
S2 结构化短回复 结论/建议/下一步 Card v3 header/footer 正常
S3 Markdown 表格 3x5 表格 原生 table,不 raw markdown
S4 长表分页 20 行表格 分页或安全拆分,不吞消息
S5 长决策分析 外部项目吸收评估 触发 Decision Trace,card 只发入口
S6 streaming final answer delta + completed final card 完整,不重复灰色文本
S7 工具调用 terminal + browser mock 工具摘要显示,状态正确
S8 footer usage/duration/context footer 字段齐全、格式稳定

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。

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

改动:

  • 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。
  • 涛哥确认视觉方向。
  • 扩展 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。

风险判断

风险 判断 缓解
v3 视觉越改越重 中 preview 先行,compact 默认
footer 信息过载 中 compact/debug 两档
事件状态机引入复杂度 中 先只接 streaming final
与现有 Card V2 冲突 中 feature flag,v2 可回退
外部项目快速变化 低 只吸 design/contract,不追 installer
Hermes 升级仍要验证 必然 但固定为 Upgrade Pack,不再临场验证

最终推荐

采用 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