Agent 系统的运行状态思维模型

复杂 Agent 系统里，真正要管理的不是任务列表或记忆文本，而是可恢复、可验证、可归属的运行状态。

一页版

以后遇到任何 agent 系统问题，不要先听代码叙事，也不要先做抽象 taxonomy。先穿过这八个模型。

这篇不讲什么

这不是“系统思维”“第一性原理”“复杂系统涌现”这种大词集合。那些词不落到 runtime contract，就会变成装饰。

• 不讲 agent swarm 自动化最大化。Zayn 当前更需要 ownership、review、handoff、状态可见性，不是多开 agent。
• 不讲 CQRS、event sourcing、microservice boundary 这类架构炫技。当前很多问题不是缺复杂架构，而是 transition 和 source-of-truth 没画清。
• 不讲纯 prompt engineering。对当前系统最有用的是工具、状态、部署、证据链，而不是把 prompt 写得更漂亮。
• 不把 OpenViking 讲成抽象 memory database。更接近的上层抽象是 context lifecycle、checkpoint、provenance、rehydration。

1. Runtime Contract > 代码叙事

代码叙事是“这个函数名、注释、PR description 看起来在做什么”。Runtime contract 是“运行时到底由谁消费哪个字段，哪个值触发哪个行为”。复杂系统里，可信的是 runtime contract，不是命名。

不要问：  这段代码是不是写了 reset？ 要问：  runtime 收到的 contract 是什么？  哪个字段决定 cold-start？  谁可以覆盖它？  旧 session 从哪里被重新引入？  哪个测试能证明 reset 后不会 resume？

2. State Transition > 静态状态

很多线上问题不是“状态错了”，而是“状态从 A 到 B 的过程没有守门”。连接重建、workspace 切换、daemon restart、agent stop/start、token 过期、activity 更新，这些 transition 如果没有 guard / invalidation / ack，就会制造漂移。

Zayn 需要训练的不是“看状态”，而是“看状态转换边界”。真正的 bug 常常藏在边界上：A 已经不该写了但还在写，B 已经启动了但没有宣告 ready，旧 owner 已失效但仍被当成 source of truth。

3. Source-of-Truth Routing

复杂协作里，修错地方比修错代码更常见。一个行为可能经过 source repo、build artifact、npm/pip package、PM2 process、Cloudflare deploy、browser cache。任何一层搞错，代码正确也不会生效。

动手前先画 routing： source repo:  这段代码真正应该在哪个 repo 改？ publish artifact:  运行时吃的是源码、npm 包、pip wheel、Docker image，还是静态 build？ running process:  PM2 / Railway / Cloudflare 当前跑的是哪个版本？ deployment path:  CI/CD 从哪个 branch、tag、workflow 出发？ verification:  我如何证明线上吃到的是这个 commit / version？

4. Behavior Fix 与 Cleanup 解耦

用户当前行为错了，应该先修 behavior contract；老接口、死代码、架构不干净，通常是另一个任务。把两者混成一个 PR，会让范围膨胀、验证困难、rollback 不清楚。

例如 reset 修复，立即要修的是 cold-start 不 resume；prompt / toolDefinitions / OV startup context 的死代码删除，可以是后续 cleanup。这个分离能保留 deployment-safe intermediate state。

5. Evidence Ladder：fact / inference / proposal 分层

Zayn 对 plausible narrative 的容忍度很低。不是因为不能接受推断，而是推断必须标注为推断。一个可靠技术更新应该让人一眼看出：哪些是事实，哪些是根因假设，哪些是建议动作。

Confirmed fact:  日志、代码、接口返回、测试输出、commit、version、CI 状态。 Inference:  基于事实推断的可能根因，必须可被反证。 Proposal:  建议采取的修法、验证路径、rollback 或后续 cleanup。

这适用于 OpenViking permission denied、CLI result nesting、Remote Compact、Cloudflare deployment、agent stuck working。不要把 observation、interpretation、recommendation 写成同一种语气。

6. User-Visible Feedback Loop

Zouk 不是普通 UI，而是协作 runtime。协作 runtime 的错误不能只留在 server logs 或 activity panel 里；如果错误影响协作，它应该进入协作流，让用户和其他 agents 能共同处理。

• daemon 重连失败：说明哪个 daemon、哪个 workspace、最后一次 ready 是什么时候。
• tool bridge 失败：说明哪个 tool、哪类输入、是否可重试。
• agent activity stuck：说明 owner、session、stop/idle 信号是否收到。
• 部署未生效：说明当前线上 commit/version 和期望 commit/version 的差异。

这不是把错误吵闹化，而是把不可见状态变成可协作对象。用户看到“agent 没反应”时，系统已经失败；用户看到“哪个 bot 因为什么错误停住”时，协作还在。

7. Default Path as Product Contract

默认路径不是 UI convenience，而是产品对“用户一打开应该看到什么”的承诺。默认打开的东西应该服务最高频判断，不应该只是暴露原始树的第一层。

同样逻辑也适用于 notes、zaynjarvis.com、Studio、PWA。第一屏不是装饰，而是 product contract：它应该把最高频判断提前。

8. Small Patch, Full Verification

Zayn 可以接受快速 merge，但前提是验证闭环完整。小 patch 不等于小风险；很多协作系统 bug 恰恰来自“小改动 + 没验证部署产物”。

验证不是仪式，而是 source-of-truth routing 的最后一步：证明运行中的系统真的吃到了这次改动。

把八个模型合成一个默认调试协议

1. State   当前用户可见错误是什么？它在哪个 transition 出现？ 2. Runtime contract   谁真正决定这个行为？字段、协议、版本、owner 是什么？ 3. Source of truth   应该改哪个 repo？发布产物是什么？运行进程吃哪个版本？ 4. Evidence ladder   confirmed fact / inference / proposal 分别是什么？ 5. Patch shape   行为修复是什么？cleanup 是否需要拆出去？ 6. Feedback   用户是否能看见错误、恢复、进展？ 7. Verification   如何证明代码、产物、部署、运行态都一致？ 8. Residual risk   还可能在哪个 transition 漂移？rollback 路径是什么？

对 OpenViking / Zouk 的设计影响

• OpenViking 不应只卖“记忆”。更强的 framing 是 context lifecycle：checkpoint、provenance、rehydration、source-of-truth、debug surface。
• Zouk 不应只展示消息。它应该展示协作 runtime 的状态变化：谁在工作、谁卡住、哪个 daemon 断了、哪个 deploy 未生效。
• Agent 协作不应只追求并行。并行之前先要有 ownership、handoff、review、验证和可见状态。
• Notes 不应只是文章。它应该沉淀 Zayn 的判断协议，让未来的系统设计和 agent 行为可复用。

Knowledge Update Card

最后压缩

复杂 Agent 系统的核心能力，不是“会做更多任务”，而是“状态不会漂移，漂移后能被看见、归因、恢复”。