AI Engineering KB

Appearance

Trace、Evaluation 与 MCP Adapter ​

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

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

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

2. Mental Model ​

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

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

3. 核心机制 ​

Trace Pipeline ​

Trace Pipeline 输出统一 spans/events/metrics；Eval Harness 消费真实/合成 run 数据做 component/end-to-end regression。

Evaluation Harness ​

Trace Pipeline 输出统一 spans/events/metrics；Eval Harness 消费真实/合成 run 数据做 component/end-to-end regression。

MCP Adapter ​

MCP/Workspace 是两类外部 capability adapter：前者协议互操作，后者真实执行环境；都受同一 permission/trace contract 管理。

4. 最小实现 / 伪代码 ​

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

text
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. 常见问题 ​

基础：Trace Pipeline 最容易被误解的点是什么？ ​

Trace Pipeline 输出统一 spans/events/metrics；Eval Harness 消费真实/合成 run 数据做 component/end-to-end regression。

机制：这些能力在一次 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 ​

12. 本文结论 ​

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

AI Engineering · Agent · Harness · Backend Systems

Built as a living technical knowledge base.