hermes-feishu-streaming-card 与本机 Feishu Card 主链对比评估

hermes-feishu-streaming-card 与本机 Feishu Card 主链对比评估

结论

baileyh8/hermes-feishu-streaming-card 不是一个单纯 card renderer，而是围绕 Hermes Gateway 的 Feishu 出口做的 streaming card sidecar + hook installer + 诊断运维层。它最强的部分是“运行时流式状态机”：把 started / thinking / answer / tool / completed 等生命周期事件汇聚到同一张飞书卡片，并用 sidecar 负责发送、更新、合并、重试、健康检查和多 bot/profile 路由。

和我们自己的 card 主链相比，它不是更适合直接替代当前实现，而是更适合作为 L3 局部能力吸收 / Partial Absorb：吸收它的事件协议、sidecar 状态机、终态优先、更新合并、doctor/repair 诊断设计；不要吸收它的整套 installer，也不要让它 patch 当前 Hermes core/gateway。当前我们自己的 Card V2 渲染、分类器、长内容 guard、Decision Trace HTML/wiki/retain 链路更贴近涛哥实际使用习惯；对方的“持续更新一张卡”体验好，但会重新引入 Feishu progressive edit 类风险。

最终判断：Partial Absorb，不 Core Merge。

项目定位

项目地址：https://github.com/baileyh8/hermes-feishu-streaming-card

从仓库结构看，它是 Python 包 hermes-feishu-streaming-card，当前版本 3.6.5，核心目录是 hermes_feishu_card/，包含：

• server.py：sidecar HTTP 服务，提供 /events、/health、card action 等接口。
• session.py：CardSession 状态累积与事件应用。
• render.py：把会话状态渲染成 Feishu interactive card JSON。
• feishu_client.py：tenant token、send card、update card 的飞书 HTTP 边界。
• hook_runtime.py：从 Hermes runtime local vars 中提取事件并发给 sidecar。
• install/patcher.py：给 Hermes gateway/run.py 打 hook，注入 started/completed/tool/delta/clarify/approval/cron 等事件点。
• cli.py：setup/install/doctor/repair/start/status/stop/smoke 等运维入口。

它的项目 README 和 architecture 文档明确把主路线放在 sidecar-only：Hermes 内只留很薄的 hook，飞书卡片创建、更新、状态累积放到独立 sidecar 里处理。参见 README、docs/architecture.md。

进入体系的位置

它属于 出口层 + 运行时观测/状态层增强，不是主 agent 控制面，也不是长期知识层。

在我们的体系里对应位置：

层级	本机当前能力	对方项目能力	关系
平台出口层	gateway/platforms/feishu.py 直接 send/edit，feishu_cards.py 做 Card V2 渲染	sidecar 调 Feishu send/update	部分重叠
Card 渲染层	Card V2、原生 table、collapsible_panel、长表分页、footer、Decision Trace guard	会话状态卡，主要呈现流式主文本/工具计数/footer	方向不同
流式运行层	GatewayStreamConsumer 负责跨平台 streaming/edit/fresh-final/fallback	Hermes hook 事件 + sidecar CardSession	对方更专注 Feishu card lifecycle
运维诊断层	gateway log、builder tests、Feishu skill runbook	doctor/status/health/repair/runtime_import/metrics	对方值得吸收
长内容归档层	Decision Trace HTML + wiki + retain	主要仍在卡片内承载/更新	我们更强

与我们自己的 card 主链对比

我们当前主链

本机 Hermes 的 Feishu 能力已经不只是临时 card sender，而是原生 gateway adapter 里的一套分流与渲染系统：

• gateway/platforms/feishu.py 负责真实 send/edit、reply/thread、media、approval、webhook/ws、入站事件、出站 payload 选择。
• gateway/platforms/feishu_cards.py 负责 Card V2 payload：schema: 2.0、table、collapsible_panel、分页卡、completion receipt、long decision guard。
• gateway/stream_consumer.py 是通用 streaming/edit 层，支持 edit fallback、fresh-final、overflow split、final_response_sent 等跨平台状态。
• Feishu 长决策/外部项目评估默认应该上升到 Decision Trace：HTML/wiki/retain，而不是把中长论证硬塞 card。

关键差异：我们更像 平台原生能力 + 渲染策略 + 长内容治理；对方更像 专门为 Feishu streaming card 做的 sidecar runtime。

对方项目强项

1. 事件协议完整

对方定义了 message.started、thinking.delta、tool.updated、answer.delta、message.completed、message.failed、interaction.requested 等事件，sidecar 只消费事件语义，不把飞书逻辑塞回 Hermes 主进程。参见 docs/event-protocol.md。

1. 状态机与终态收口做得细

它的 CardSession.apply() 会处理 delta 顺序、终态补 answer、工具状态、附件、duration/model/token/context 等。V3.6.5 还专门处理了 completed-only 模型没有 delta 但最终答案仍要回填卡片的问题。参见 release notes v3.6.5。

1. sidecar 运维面成熟

它有 doctor --json/--explain、runtime import 检查、setup/repair/restore/uninstall、health metrics、routing diagnostics、多 profile 定向 smoke。这个对我们有参考价值，尤其是 Feishu 出口出问题时快速判断是 hook、sidecar、凭据、update API、message id 还是 profile 路由问题。参见 release-readiness.md。

1. 多 bot / 多 profile / thread / cron 的专项覆盖多

仓库 README 的版本记录显示，它持续修了 thread reply、cron deliver、Hermes 0.13/0.15/0.17 hook strategy、runtime venv import 等边界。这说明项目不是 demo，而是围绕真实 Feishu 运行问题反复迭代过。

对方项目短板

1. patch Hermes runtime 是最大风险点

它通过 installer 修改 Hermes gateway/run.py，对 _run_agent_inner、callback、completion、cron 等位置注入 hook。这个方案在独立项目里能跑，但不适合作为我们当前主链默认做法。Hermes 本身升级频繁，打 patch 会和本机已有 Feishu gateway 改动、Card V2 路由、Decision Trace guard 产生维护冲突。

1. 与 Hermes 原生 plugin/adapter 方向有冲突

Hermes 的架构原则是能力尽量在边缘扩展，核心保持窄腰。对方的 sidecar 可以作为外部 runtime，但 installer patch core/gateway 文件的做法不适合作为长期 canonical。更好的吸收方式是把事件 contract 与状态机思想转成 Hermes 原生 stream event interface 或 Feishu adapter 内部模块，而不是继续靠外部 patch。

1. 渲染审美和信息治理不完全贴合我们当前口径

我们已经把 Feishu card 分成短回执、表格、状态、长结构化、Decision Trace 入口等多个出口。对方更强调“同一张流式卡片持续更新”，这对实时体验很好，但对复杂分析并不等价于“读起来更好”。涛哥当前偏好是：短结论 card，详细论证进 HTML/wiki/retain；不是在飞书里滚动一张超长卡。

1. 重复建设了部分 Hermes 已有能力

我们已有：

• stream_consumer.py 的通用 streaming/edit/fallback/fresh-final。
• feishu.py 的 send/edit/reply/thread/media/approval 基础能力。
• feishu_cards.py 的 Card V2 渲染、原生 table、collapsible_panel、分页、long decision guard。

因此不能把对方整套 sidecar 作为替代主链，否则会出现双状态机、双分类器、双发送路径、双诊断口径。

四层审计

宣称层

项目宣称解决 Feishu Hermes 的流式卡片、工具进度、按钮交互、长表格/代码块、多 bot/profile、sidecar 诊断和安装升级问题。结合 README、版本记录、测试目录与文档，这些不是空壳宣传，仓库有明确实现文件和回归测试。

可信度：中高。

实现层

实现是 sidecar-only + hook patch：Hermes hook 只负责事件提取和 HTTP 转发，sidecar 负责状态、渲染和 Feishu API。架构清晰，可拆性也不错：事件协议、CardSession、render、client、doctor 都能单独吸收思路。

主要风险在 patcher。install/patcher.py 里有大量 marker 和 AST 注入逻辑，说明它需要跟 Hermes 版本强绑定。这个不适合我们直接接入生产主链。

运行层

项目声称有 mock Feishu server、真实 Feishu smoke、长卡压力测试、Hermes 版本兼容矩阵。我们本轮没有在本机安装运行它，也没有对真实飞书发它的 smoke 卡，所以不把“可在我们机器直接生产运行”当已验证结论。

运行层判断：可以做离线吸收评估；暂不建议接入本机 live gateway。

检索与治理层

对方文档和测试较齐，但它是独立 repo 的运维体系。若整包引入，会让本机 Feishu 出口的真相源分裂：一部分在 Hermes gateway，一部分在 sidecar config，一部分在 patch manifest。

治理建议：吸收为 skill/reference/wiki + 局部代码启发；不要让它成为本机 Feishu 出口的第二套 canonical runtime。

三个专项验证

静态面 vs 运行面一致性

静态文件支持它的宣称：有 server/session/render/feishu_client/patcher/cli/tests/docs。README 与 release-readiness 对应到具体代码结构。

但我们没有实际启动它，因此“运行面一致性”只到静态可信，不到本机验收。

精确回捞能力

它的诊断面值得参考：/health 暴露 active sessions、metrics、routing profile，CLI doctor/status 能定位 runtime import、hook strategy、sidecar 状态、bot route。这个对我们后续 Feishu 出口排障很有价值。

降级与回退路径

它设计了 fail-open hook、no-op client、restore/uninstall、repair、update retry、send/update metrics。回退意识强。

但从我们的生产角度看，“能 restore patch”仍不如“不 patch 主链”。所以回退能力是加分项，但不能抵消 patcher 的架构风险。

最值得吸收的能力单元

P0：事件协议与状态机骨架

吸收内容：

• message.started / thinking.delta / answer.delta / tool.updated / message.completed / message.failed / interaction.requested 这类标准事件命名。
• 以 conversation_id + message_id + chat_id + thread_id/profile_id 做会话键。
• 非终态事件快速 ACK，终态事件优先落卡。
• completed-only 模型用最终答案回填，避免 delta 缺失导致空卡。

落点：Hermes 原生 stream_consumer / Feishu adapter 的内部 event contract，不是外部 hook patch。

P0：Feishu card update 合并与终态优先

吸收内容：

• 同一 message id 更新串行化，避免旧快照覆盖新内容。
• PATCH 合并/节流，非终态减少阻塞，终态强制 flush。
• update failures / retries / last_terminal_event 指标。

落点：gateway/platforms/feishu.py 的 edit/update 路径与 gateway/stream_consumer.py 的 Feishu-specific policy。

P1：doctor/status/health 诊断模型

吸收内容：

• Feishu 出口诊断分区：config、credentials、runtime import、platform capability、send/update API、thread routing、profile/bot routing、message update metrics。
• doctor --json 机器可读输出 + --explain 人读输出。
• smoke-feishu-card 支持 profile/chat 定向验证。

落点：Hermes 原生 hermes tools/status 或 Feishu adapter diagnostic CLI，不作为独立 sidecar CLI。

P1：多 bot/profile/chat binding 的 routing diagnostics

吸收内容：

• bindings.chats 类显式 chat_id → bot/profile 绑定思路。
• health 中展示 last_route、last_route_error、profile sessions。

落点：如果未来本机需要多飞书 bot，再进入 Feishu adapter 配置模型；当前不用急着扩。

P1：交互卡按钮 fallback 策略

吸收内容：

• public callback 可用时走按钮。
• localhost/private sidecar 时退回编号文本选择，不阻断原生 Hermes 流程。

落点：当前 Hermes clarify/approval Feishu card 路径可参考，不需要吸整个 /card/actions sidecar。

P2：安装/修复体验

吸收内容：

• runtime venv import 检查。
• 安装前 anchor/版本诊断。
• repair 只修可验证状态，不覆盖用户改动。

落点：适合进入 Hermes 官方/本机运维 skill，但不照搬 patcher。

不建议吸收的部分

1. 整套 installer patcher

原因：会修改 Hermes gateway/run.py，与本机主链、Hermes 升级、官方 plugin/adapter 方向冲突。

1. 独立 sidecar 作为默认生产出口

原因：本机已经有 Feishu adapter + Card V2 + Decision Trace 长内容治理。再加 sidecar 会形成双主链。

1. 把所有回复都变成同一张 streaming card

原因：我们的实际经验是 Feishu 中长内容可读性、折叠、footer、表格、HTML 入口都要分流治理。持续更新一张卡不是所有内容的最优解。

1. 把对方 card renderer 替换本机 feishu_cards.py

原因：本机 renderer 已经有 Card V2 原生 table、collapsible_panel、分页、long decision guard、移动端回执规则。这些更贴近当前使用偏好。

和我们当前 card 的核心差异

维度	对方项目	本机当前 card 主链	判断
架构	外部 sidecar + hook patch	原生 Feishu adapter + card builder	本机更稳
流式体验	同一张卡持续更新	通用 stream_consumer + send/edit/fresh-final	对方 Feishu 专项更完整
卡片渲染	会话状态卡	Card V2、多类型卡、分页、长决策 guard	本机更贴合当前需求
长内容	倾向卡内承载/更新	HTML/wiki/retain + 短 card 入口	本机明显更好
诊断	doctor/status/health 很完整	分散在日志、skill、测试	对方值得吸收
多 bot/profile	对方覆盖多	本机目前不是主需求	可参考，不急接
接入风险	patch core/gateway	已在主链内	对方不宜整包接入

建议动作

1. 开一个本地 reference：Feishu streaming card sidecar partial absorb

把本评估沉淀到 llm-wikis 或 Feishu card skill reference，后续做 Feishu streaming/diagnostics 时直接查。

1. 只拆 P0/P1 能力进本机 issue/待办，不安装它

优先拆：事件 contract、update 合并指标、doctor/status、completed-only final answer fallback。

1. 若要验证对方项目，只做隔离 side-stage

不能直接跑 installer 改 live Hermes。应使用隔离 HERMES_HOME 或临时 Hermes checkout，确认 patch diff、sidecar health、fake event、mock Feishu payload，再决定是否吸代码。

最终判断

吸收层级：L3 局部能力吸收

最终决策：Partial Absorb

一句话：这个项目强在 Feishu streaming runtime 和运维诊断，不强在替代我们当前 card 渲染与长内容治理；最好的用法是吸事件协议、状态机和 doctor 设计，不把整包装进生产主链。

来源

• GitHub 项目主页：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
• 发布验收：https://github.com/baileyh8/hermes-feishu-streaming-card/blob/main/docs/release-readiness.md
• V3.6.5 发布说明：https://github.com/baileyh8/hermes-feishu-streaming-card/blob/main/docs/release-notes-v3.6.5.md
• Hermes issue #33854：https://github.com/NousResearch/hermes-agent/issues/33854