Hermes Decision Trace
Feishu Card v3 吸收方案：稳定、美观与升级省事
本方案建议以 Partial Absorb + Native Consolidation 方式吸收 baileyh8/hermes-feishu-streaming-card：不整包替换本机 Feishu card 体系，不引入它的 installer patcher 作为生产主链；重点吸收它的 流式事件协议、会话状态机、终态优先、footer 信息密度、doctor/status 诊断与升级 smoke 流程。
🧭
推荐路径先按已确认方向推进，不继续扩大改动面。
🔎
关键依据见证据摘要与完整记录中的状态、产物和校验链。
🛠️
落地方式先把已验证方案当成稳定基线：保留当前 schedule / deliver / workdir，不急着继续扩面；新增候选先读源码、看 output、做 run-now 验证，再决定是否转 script-only。
证据摘要
- 正文保留完整证据链；本页顶部只展示可读摘要。
行动清单
按需继续推进。
边界 / 风险
风险 / 边界
正文未抽取到明确风险；上线前仍需确认权限、回退路径与运行态影响。
完整记录
本节目录结论背景与目标吸收边界目标架构展示体系设计Footer v3 设计稳定性设计升级省事方案：Feishu Card Upgrade Pack实施阶段Rollback 与保守开关成功标准初版任务拆解风险判断最终推荐
Feishu Card v3 吸收方案（草案）
结论
本方案建议以 Partial Absorb + Native Consolidation 方式吸收 baileyh8/hermes-feishu-streaming-card：不整包替换本机 Feishu card 体系，不引入它的 installer patcher 作为生产主链；重点吸收它的 流式事件协议、会话状态机、终态优先、footer 信息密度、doctor/status 诊断与升级 smoke 流程。
目标是三件事：
- 更稳定：把 Feishu card 从散落的 send/edit/render 逻辑，收敛为事件 contract + card session + renderer + smoke matrix。
- 更美观：吸收对方卡片的状态 header、工具摘要、密集但克制的 footer；保留本机 Card V2 原生 table、collapsible、分页、Decision Trace 入口。
- 升级更省事：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.pypatcher 作为生产主链。 - 不吸收一行安装脚本。
- 不让 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 视觉原则
- 状态清晰：header 一眼看到 thinking/completed/failed/waiting。
- 正文优先：结论、结果、核心回答必须展开，不被工具信息抢权重。
- 工具透明但低噪声：工具摘要默认显示；超过 3 个工具折叠。
- footer 更完整但克制：小字号、灰色、单行优先，debug 模式再展开。
- 长内容不上 card：决策型长分析仍进入 Decision Trace HTML，只在 card 放短摘要和按钮入口。
- 移动端优先：避免横向 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 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 字段来源
| 字段 | 来源 | 当前状态 |
|---|---|---|
| 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 → 输出失败卡，保留已完成工具摘要
终态优先规则
message.completed.answer非空：最终正文使用 completed answer。- completed answer 为空但 answer delta 非空：使用 delta 累积结果。
- completed-only 模型没有 delta：允许 completed 直接填充最终 card。
- final card 成功后，禁止再发原生重复最终文本。
- 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/*.jsonartifacts/feishu-card-smoke/<date>/preview.htmlartifacts/feishu-card-smoke/<date>/preview.pngartifacts/feishu-card-smoke/<date>/result.json- 一张 Feishu 升级验收 card
实施阶段
Phase 0：冻结基线
目标：先知道当前体系不能丢什么。
动作：
- 生成当前 8 类 card payload fixture。
- 生成当前 preview HTML/PNG。
- 记录当前 footer 输出。
- 记录不可回退能力：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。
动作：
- 新增 preview generator。
- 做 3 张 mock：短结论、表格报告、长决策入口。
- 对比外部项目样式：状态 header + 工具摘要 + footer。
- 涛哥确认后再进入 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
上线顺序：
- 先
preview_only: true。 - 再对测试 chat 开 v3。
- 再对 DM 开 v3。
- 最后再考虑 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。
风险判断
| 风险 | 判断 | 缓解 |
|---|---|---|
| v3 视觉越改越重 | 中 | preview 先行，compact 默认 |
| footer 信息过载 | 中 | compact/debug 两档 |
| 事件状态机引入复杂度 | 中 | 先只接 streaming final |
| 与现有 Card V2 冲突 | 中 | feature flag，v2 可回退 |
| 外部项目快速变化 | 低 | 只吸 design/contract，不追 installer |
| Hermes 升级仍要验证 | 必然 | 但固定为 Upgrade Pack，不再临场验证 |
最终推荐
采用 Feishu Card v3 渐进吸收路线：
- 先定视觉和 footer。
- 再做 smoke matrix。
- 再接 renderer。
- 最后才接 streaming session。
- 全程 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