整体架构、Domain Model 与 Model Adapter

1. 为什么这组知识要一起学

本章把前 20 个模块收束成 Shadow Harness 的完整架构，所有组件都要求有内部 contract、测试边界和可观测证据。

这几个知识点处在同一条工程链上。如果只记单个名词，很容易在真实系统里把责任放错层：例如让模型管理程序事实、让数据库 transaction 承担外部 API 原子性，或把一个 provider SDK 的行为误认为 Agent 的通用规律。

2. Mental Model

Shadow Harness 是所有知识的集成验证场：核心价值不是代码量，而是稳定 domain boundary、可恢复 Runtime、可测量设计和可解释取舍。

API → Run → Context → Model/Planner → Graph/Scheduler → Tool/Retrieval/Workspace → State/Checkpoint → Trace/Eval → Result

3. 核心机制

Architecture Overview

总体架构以 domain contract 为中心：Run/Node/Tool/Context/Trace 等内部类型稳定，provider、DB、MCP、sandbox 作为 adapter。

Domain Model

总体架构以 domain contract 为中心：Run/Node/Tool/Context/Trace 等内部类型稳定，provider、DB、MCP、sandbox 作为 adapter。

Model Adapter

ModelAdapter 隔离 provider；ContextManager 组装 working set；Retriever 只返回带 provenance 的证据，三者通过 typed contract 组合。

4. 最小实现 / 伪代码

下面代码只表达边界和生命周期，不要求照抄到项目中：

request → api → run_state → context → model/planner
                     ↓
                graph/scheduler
             ↙ tool   retrieval ↘
          workspace             mcp
                     ↓
         checkpoint + trace + eval

真正实现时应把 I/O、状态持久化、错误翻译和策略注入拆成可测试组件，而不是把示例扩成一个巨型函数。

5. 在 Shadow Harness 中怎么落地

每个模块只依赖内部 domain contract；Provider/MCP/DB/Sandbox 都作为 adapter；Developer Console 读取 trace/state，不反向控制核心语义。

建议为本章涉及的行为留下明确的 domain object、interface 和 trace event；只要一个关键行为只能通过读日志猜测，就说明 Runtime contract 仍不够清晰。

6. Production Engineering 检查项

• 先单 Agent 再扩展
• 所有版本进入 Run Manifest
• 关键副作用幂等
• 每周有 deterministic tests/benchmark/ADR/failure log

7. Failure Modes

7.1 Codex 写完但自己讲不清

当出现「Codex 写完但自己讲不清」时，用端到端 trace + Run Manifest 把问题归到 domain contract/adapter/policy/state，再在对应模块修复，避免在 Console 层打补丁。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

7.2 框架类型侵入 domain

当出现「框架类型侵入 domain」时，用端到端 trace + Run Manifest 把问题归到 domain contract/adapter/policy/state，再在对应模块修复，避免在 Console 层打补丁。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

7.3 无 eval 就宣称优化

当出现「无 eval 就宣称优化」时，用端到端 trace + Run Manifest 把问题归到 domain contract/adapter/policy/state，再在对应模块修复，避免在 Console 层打补丁。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

7.4 Demo 能跑但 crash/resume/permission 全空白

当出现「Demo 能跑但 crash/resume/permission 全空白」时，用端到端 trace + Run Manifest 把问题归到 domain contract/adapter/policy/state，再在对应模块修复，避免在 Console 层打补丁。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

8. Trade-offs

自研用于理解边界，不追求替代成熟框架；重要的是对照 OpenAI Agents SDK/LangGraph/MCP 解释自己的设计差异。

设计记录最好明确：当前约束是什么、备选方案有哪些、为什么现在选这个、未来什么条件出现时需要重构。 这样 ADR 才能随着模型和基础设施变化被重新审视。

9. Experiment / Evaluation

最终用固定 task suite 跑 end-to-end：tool、RAG、DAG、HITL、checkpoint、sandbox、failure injection、trace、cost。

实验应固定数据集、版本和环境，至少记录 success、latency、token/cost、attempt/step 数以及失败类型；涉及随机模型时需要重复运行而不是只看一次结果。

10. 常见问题

基础：Architecture Overview 最容易被误解的点是什么？

总体架构以 domain contract 为中心：Run/Node/Tool/Context/Trace 等内部类型稳定，provider、DB、MCP、sandbox 作为 adapter。

机制：这些能力在一次 Run 的哪个生命周期阶段生效？

沿着 API → Run → Context → Model/Planner → Graph/Scheduler → Tool/Retrieval/Workspace → State/Checkpoint → Trace/Eval → Result 找位置，并明确它的输入、输出、持久化事实和失败传播。

工程：如果这一层失败，应该由谁恢复？

先区分 transient failure、invalid input、permission、semantic failure 与 irreversible side effect。恢复策略属于拥有该状态与副作用的 Runtime/adapter，而不是交给模型自由决定。

设计：规模扩大 10 倍后，哪个假设最先失效？

优先检查 context/token、并发/连接池、catalog 大小、持久化吞吐、trace 体积、身份与租户隔离。不要默认“多加机器”能解决语义和一致性问题。

11. Sources

• Anthropic — Building effective agents
• OpenAI Agents SDK
• LangGraph — Persistence
• MCP — 2026-07-28 Specification

12. 本文结论

掌握本文的标准不是能背定义，而是能画出数据流、写出最小 contract、解释失败恢复，并用测试或 benchmark 证明设计没有只停留在概念层。