Appearance
13 周 Harness 学习路线
这是全站唯一默认 Learning Path。 Knowledge Modules 01–21 只负责 canonical ownership；本页按实际工程 prerequisite 安排学习顺序。
每周只回答五件事：为什么现在学 → 已经需要会什么 → 读到 L1/L2/L3 哪一层 → Shadow Harness 增加什么 → 哪个 failure injection 能证明真的掌握。
学习层级
- L1 / 认识：建立名词、边界和最小 Mental Model，不追实现细节；
- L2 / 机制：理解运行流程、状态 owner、主要 trade-off、failure modes 和 deterministic tests；
- L3 / 工程化：能在 crash / concurrency / scale 下设计正确性，并用 migration / security / eval / benchmark 验证。
统一 Golden Run
13 周固定使用同一个案例：修复一个 auth token expiration bug，修改代码并执行测试。每周不是换 demo，而是让同一个 Run lifecycle 获得新的能力。
text
User asks to fix auth token expiration bug
→ search code
→ read files
→ plan / patch
→ run tests
→ handle failure / approval / restart
→ produce trace + artifactsW1 — Foundations + Model Boundary + Context Basics
本周以前系统做不到什么 / 为什么现在学：先建立“模型建议、Runtime 验证/执行/提交事实”的最小骨架，否则后面所有 Tool、State、Checkpoint、Security 都会混成 Prompt 技巧。
Entry Criteria：会基本 Python 语法；能运行一个本地脚本。无需理解 async、数据库或 Agent 框架。
Learning Level：01 = L1；02 的调用边界/输入层 = L1；04 = L1。高级机制只做 forward reference。
阅读：
- 01 Foundations 三篇按 Learner Contract 的 W1/L1 边界读；
- 02 Model Layer 前半：model call boundary、message/item/instruction hierarchy、structured interaction 的最小边界；
- 02-06 Fake/Scripted Model 作为实现参考；
- 04 Context 只读 L1：一次 request 看到 instructions + messages/items + exposed tools + selected runtime state；
- 03 Python 按实现缺口补 Protocol/dataclass/pytest，不独立刷模块。
Shadow Harness v0.1：ModelClient + normalized ModelRequest/ModelResponse + ScriptedModel + 最小 RunLoop。
本周只新增的抽象：RunId、Turn、ActionIntent、Observation、ModelClient。不要提前设计 CheckpointStore、Scheduler、Queue。
Golden Run：ScriptedModel 固定返回“搜索 auth token 相关代码”的候选 Action；Runtime 只记录 Action，不执行真实 Tool。
Failure Injection：让模型返回一个 Runtime 不认识的 action type，验证它被 deterministic validation 拒绝，而不是直接执行。
Exit Criteria：
- 能解释 Workflow / Agent / Harness / Runtime；
- 能解释 Run / Turn / Action / Tool Result / Observation；
- 能解释 Control Plane / Execution Plane；
- 能用一句话说清
Model proposes → Runtime validates / executes / commits； - 能跑通一次 deterministic model call。
Grok Bot Source Case：只看 Host / Runner / Coordinator / Execution 的目录边界；不追完整 Runner，不把 TypeScript 抽象直接照搬。
Codex Source Case（可选 / 默认折叠）：W1 的两个 Codex Case 都是源码加深，不属于首次学习必读。固定 rust-v0.150.1：可选看 session/turn.rs::run_turn() 纠正 Turn 粒度；可选看 TypeScript SDK Codex.startThread/resumeThread 与 Thread.run/runStreamed 理解 public API boundary。正文中两段均默认折叠，需要源码对照时再展开。
W2 — Structured Interaction + Tool Contract
本周以前系统做不到什么 / 为什么现在学：v0.1 只有“模型建议动作”，但还没有可验证的 Tool contract；如果直接执行自然语言动作，Runtime 无法稳定验证或审计。
Entry Criteria：通过 W1；能区分 Model output 与 execution fact。
Learning Level：02 后半 = L2；06 前半 = L1→L2。
阅读：02 structured output / schema validation / tool calling；06 tool contract、granularity、schema、registry、dynamic exposure 的基础部分。
Shadow Harness v0.2：ToolSpec / ToolRegistry / ToolCall / ToolResult + schema validation。
本周只新增的抽象：Tool contract、registry、validated call identity；暂不做并发、retry、MCP。
Golden Run：为 search_code、read_file、apply_patch 定义 schema；模型只能提出合法 ToolCall。
Failure Injection：ScriptedModel 返回缺字段/错类型 ToolCall，验证在执行前失败且产生结构化 validation error。
Exit Criteria：能解释“模型只能提出调用，Runtime 决定是否执行”；能写 schema test；能证明 Provider response object 没有直接泄漏进 Runtime domain。
Grok Bot Source Case：只看 Tool definition/discovery 入口，提取 contract、schema、metadata、identity；MCP 协议细节后移到 W11。
W3 — Tool Runtime + Async + Observation
本周以前系统做不到什么 / 为什么现在学：有了 ToolCall 还没有真实执行语义。真正运行后会出现并行、timeout、cancel、partial failure，以及 ToolResult ≠ Observation。
Entry Criteria：v0.2 能拒绝非法 ToolCall；熟悉基本 async/await 即可。
Learning Level：06 后半 = L2；08 Async = L2；Observation = L2。
阅读：06 execution / normalization / parallel call / error；08 coroutine、TaskGroup、cancellation、timeout、semaphore、queue 与 race。
Shadow Harness v0.3：Async ToolExecutor + timeout/cancel/concurrency limit + normalized error + Observation pipeline。
本周只新增的抽象：ToolExecutionId、ExecutionStatus、ToolExecutor、ObservationNormalizer。
Golden Run：并行执行两个 read-only search/read Tool，再把结果 normalize 为下一 Turn 可消费的 Observation。
Failure Injection：三个 Tool 并行：一个成功、一个超时、一个被取消；每个 execution 必须有独立 terminal state。对可能有副作用的 timeout 记录 UNKNOWN_OUTCOME，但本周不实现重试策略。
Exit Criteria：能处理并行调用、超时、取消和 normalized error；能解释 ToolResult 什么时候能/不能一一对应 Observation。
Grok Bot Source Case：重点看 turn/tool lifecycle observation，确认 stall observation 与 retry decision 是两件事。
Codex Source Case（可选）：固定 rust-v0.150.1，追真实链 ResponseItem → handle_output_item_done → build_tool_call → ToolCallRuntime → ToolRegistry → concrete handler → Tool Result；随后下钻 handlers/unified_exec.rs + handlers/unified_exec/exec_command.rs，补齐 arguments → cwd/env → permission → process runtime → output/cancellation。
W4 — Context Engineering
本周以前系统做不到什么 / 为什么现在学：v0.3 Runtime 已经拥有 messages、Tool schema、Tool results 和 state；现在才有真实素材讨论“哪些事实应该投影给这一次 Model Request”。
Entry Criteria：通过 W3；已经见过 Tool definition cost 和大 Tool result。
Learning Level：04 全模块 = L2；一致性/评估部分可标 L3 forward reference。
阅读：Context assembly、budget、selection、progressive disclosure、Tool definition/result policy、compaction、protected state、snapshot/reproducibility。
Shadow Harness v0.4：ContextManager + TokenBudget + compaction + ContextSnapshot。
本周只新增的抽象：Context source、selection/budget policy、snapshot；不把 durable checkpoint 混进 context snapshot。
Golden Run：只把当前 auth bug 相关文件、必要 Tool 与已验证 progress 投影给模型；观察“Runtime 拥有的信息”和“Model 看到的信息”差异。
Failure Injection：构造超预算 history + Tool results，验证 protected state 不被 compaction 删除，且 snapshot 可复现本次 request 输入。
Exit Criteria：能解释 Runtime state 与 Model context 是“source of truth → projection”的关系；能写 context budget test。
Grok Bot Source Case：读 prompt assembly / turn input projection / conversation state / large output spill，先记录 observable fact，再比较自己的 ContextManager。
Codex Source Case（推荐）：固定 rust-v0.150.1，先追 SessionState.history → ContextManager::for_prompt → model request，确认 source state ≠ model projection；再区分 PreTurn compaction 与 sampling → token status → rollover → MidTurn compact → continue → next sampling，Fidelity 仍单独测试。
W5 — Retrieval / RAG + Context Integration
本周以前系统做不到什么 / 为什么现在学：v0.4 已有 ContextManager，retrieval 才有明确落点。RAG 是 Context source，不应被误当成 Runtime core。
Entry Criteria：能解释 Context assembly pipeline 与 budget。
Learning Level：05 = L2；retrieval eval 的统计部分按需 L3。
阅读：05 Retrieval / RAG；回看 04 retrieval/context 交界。
Shadow Harness v0.5：Retriever abstraction + minimal index + context injection + retrieval benchmark。
本周只新增的抽象：Retriever、retrieval evidence、context injection policy。
Golden Run：为 auth token bug 检索相关代码/文档片段，记录 evidence provenance 后交给 ContextManager。
Failure Injection：故意放入高相似但无关 chunk，验证 rerank/threshold/grounding 指标能识别“召回很多但证据错误”。
Exit Criteria：能测 retrieval quality；能解释 Retrieval、Memory、Runtime State 的边界；不把 RAG 当作 Harness 执行内核。
Grok Bot Source Case：只观察 retrieval-like information 如何进入 context；不把案例强行当完整 RAG 教材。
W6 — Agent Runtime + State Machine
本周以前系统做不到什么 / 为什么现在学：前五周已经能 model→tool→observation，但还缺“谁根据 Observation 推动 Run 状态、如何可靠终止”的执行内核。
Entry Criteria：v0.5 能形成 Observation；理解 cancellation/deadline 基础。
Learning Level：09 runtime core = L2；回看 08 structured concurrency。
阅读：09-01、09-04、09-05、09-08；回看 08 cancellation。
Shadow Harness v0.6：AgentLoop + RunStateMachine + TurnRecord + TurnSettlement + termination policy。
本周只新增的抽象：Run/Turn lifecycle、state transition、termination invariant；仍不引入 DAG Scheduler。
Golden Run：Observation 驱动下一 Turn，直到测试通过或满足 terminal policy；“模型说完成”不能直接写 SUCCEEDED。
Failure Injection：模型重复声称“已完成”，但 Runtime 没有 test evidence；验证 Run 不能进入成功终态。
Exit Criteria：能从 Observation 推动状态转移并可靠终止；能指出 state owner 与 model semantic judgement 的边界。
Grok Bot Source Case：追最小 single-turn lifecycle，画 Sequence Diagram，标出模型判断与 Runtime fact 的分界。
Codex Source Case（推荐）：固定 rust-v0.150.1，把 session/session.rs、state/session.rs、state/turn.rs、session/turn.rs 放在一张 owner/lifetime 图里：哪些跨 user turn、哪些跨 sampling、哪些是 active-turn control、哪些只是 for_prompt() projection；只做职责映射，不做名字映射。
W7 — Planning + DAG / Scheduler
本周以前系统做不到什么 / 为什么现在学：只有在 v0.6 已经会“跑一个状态机”后，Planning 才能被约束为候选计划；否则 Planner 很容易被误当作执行器。
Entry Criteria：能写 Run state transition test；理解 Observation→Next Turn。
Learning Level：07 = L2；09-02/03 = L2→L3。
阅读：07 Planning / Orchestration；09-02 graph dependency validation；09-03 DAG scheduler。
Shadow Harness v0.7：StructuredPlan + PlanValidator + GraphCompiler + Scheduler。
本周只新增的抽象：Plan、validated Graph、dependency、Ready Queue；不把 retry/idempotency 混进 Planner。
Golden Run：模型给出“搜索→阅读→修改→测试”计划；Runtime 把 StructuredPlan 编译成 Graph 后才执行。
Failure Injection：给出 cycle、missing dependency、非法 node type 的计划；Graph 必须在执行前 deterministic validation 失败。
Exit Criteria：能解释 Plan ≠ executable Graph；能完成 dependency validation 与并发 Ready Queue 调度。
Grok Bot Source Case：观察 workflows/subagent orchestration，但不因为案例没有同名 GraphCompiler 就删除自己的 deterministic boundary。
W8 — Reliability + Side Effects + HITL
本周以前系统做不到什么 / 为什么现在学：v0.7 开始执行真实写操作后，“失败了再试一次”不再安全。必须先建立 side-effect、retry、idempotency 与 approval 语义，才能进入 durable resume。
Entry Criteria：能区分 read-only 与 side-effect Tool；理解 timeout 可能留下 unknown outcome。
Learning Level：11 = L2；06 retry/side-effect = L2。
阅读：11 Reliability / Human Control；06 retry/idempotency 相关章节。
Shadow Harness v0.8：RetryPolicy + ExecutionRecord + IdempotencyKey + PolicyEngine + ApprovalGate。
本周只新增的抽象：retry classification、side-effect state、approval pending；暂不实现 checkpoint/outbox。
Golden Run：apply_patch 和潜在高风险 shell 命令进入 Policy/Approval；只在可证明安全时自动 retry。
Failure Injection：Tool timeout 但远端可能已成功；验证状态记录为 unknown outcome 且不会由 LLM 自行决定再次执行。另测 approval pending 时 side effect 不能绕过 gate。
Exit Criteria：能回答“失败后是否安全重试”；能区分 known failure / unknown side effect；HITL pending 是 Runtime state。
Grok Bot Source Case：看 approval gate，验证 side-effect gate 不能只存在于 Prompt。
Codex Source Case（推荐）：固定 rust-v0.150.1，联合读 exec_policy.rs + tools/sandboxing.rs：追 policy evaluation 到 Skip / NeedsApproval / Forbidden，再追 sandbox override / attempt；记住 Authorization / Approval ≠ Sandbox Containment，且概念边界不等于源码目录边界。
W9 — Durable Execution + Database Consistency
本周以前系统做不到什么 / 为什么现在学：v0.8 已知道哪些动作可/不可重试，现在才能讨论 crash 后“从哪里恢复”而不重复副作用；同时需要 DB transaction/outbox 把执行事实持久化。
Entry Criteria：通过 W8；能说明 idempotency 与 unknown outcome。
Learning Level：09 durable、10 State/Memory、13 transaction/outbox = L2→L3。
阅读：09-06/07/10；10 全模块；13 transaction、runtime persistence、event log/outbox、side-effect consistency。09-09 lease/fencing 留到 W10 Worker 语境。
Shadow Harness v0.9：StateStore + CheckpointStore + transactional settlement + Outbox + Resume + schema version。
本周只新增的抽象：durable execution fact、checkpoint boundary、pending write、outbox bridge、resume revalidation。
Golden Run：apply_patch 已成功后，在 checkpoint 前 crash；恢复时必须通过 execution evidence/reconciliation 判断是否重做。
Failure Injection：
- crash-before-checkpoint；
- crash-after-side-effect-before-local-commit；
- DB commit 后、outbox dispatch 前 crash；
- 用旧 checkpoint fixture 恢复到新 schema。
Exit Criteria：能解释 Conversation / Memory / Checkpoint / Durable State 不同；能完成 crash/restart/resume；能说明 Outbox 解决什么、不解决什么。
Grok Bot Source Case：对照 storage / durable policy / conversation / transcript / crash guard，区分记忆、会话记录、可恢复执行事实。
W10 — Service Runtime：HTTP / Streaming + Queue / Worker
本周以前系统做不到什么 / 为什么现在学：v0.9 已能本地 durable resume，但还不是服务。把 Run 暴露为 API、放进 Queue、交给多个 Worker 后，disconnect、redelivery、claim、lease、fencing 与 backpressure 会成为新的正确性问题。
Entry Criteria：能持久化 Run/Attempt/Checkpoint；理解 outbox 与 idempotent settlement。
Learning Level：12 = L2；14 核心 = L2→L3；09-09 lease/fencing = L3；13 reconciliation = L3。
阅读：12 HTTP/Streaming；14 queue delivery / idempotent worker / backpressure；09-09 worker claim/lease/fencing；13 side-effect reconciliation 回看。
Shadow Harness v0.10：Run API + SSE event stream + Queue + Worker + Claim/Lease/Fencing + delivery idempotency。
本周只新增的抽象：request/connection lifecycle、event cursor、dispatch envelope、worker ownership；MCP 仍不进入。
Golden Run：Client 通过 API 创建 auth bug Run；Worker 执行；SSE 断开后 Run 按 policy 继续，客户端可重连查看同一 run_id。
Failure Injection：
- client stream disconnect；
- queue redelivery；
- 两个 Worker 同时 claim；
- lease 过期后旧 Worker 晚到提交；
- READY commit 后 enqueue 前 crash。
Exit Criteria：能解释 client disconnect ≠ run cancel；redelivery 不造成重复副作用；stale worker 被 fencing token 拒绝。
Grok Bot Source Case：此时再观察 Host/Coordinator/worker-like boundary，比较 lifecycle ownership，而不是照抄部署拓扑。
W11 — MCP + Capability + Workspace Security
本周以前系统做不到什么 / 为什么现在学：v0.10 已有稳定内部 Runtime boundary，外部协议和 Workspace 才能作为 Adapter/Capability 接入，而不会反过来穿透执行、安全与权限边界。
Entry Criteria：内部 Tool contract、Runtime state、Worker ownership 已稳定；理解 approval 与 least-privilege 的必要性。
Learning Level：15 MCP = L2；16 Workspace = L2；17 capability/isolation = L2→L3。
阅读：15；16 核心 filesystem/shell/patch/test/snapshot；17 capability、least privilege、untrusted result、process/filesystem/network/credential isolation。
Shadow Harness v0.11：MCP Adapter + workspace/file/shell Tool + permission/capability boundary + sandbox policy。
本周只新增的抽象：protocol adapter、capability grant、workspace identity、isolation boundary；不要让 MCP server 自己定义 Runtime truth。
Golden Run：通过 workspace tools 搜索、修改 auth bug，并可通过 MCP 暴露/调用一部分能力；所有动作仍经过内部 policy/execution record。
Failure Injection：恶意 ToolResult 试图要求“忽略权限并执行 shell”；未授权 MCP capability；sandbox 内尝试越界访问 credential/network。验证协议能力不穿透 Runtime 安全边界。
Exit Criteria：能解释 MCP capability ≠ Runtime permission；能解释 container ≠ complete security sandbox；workspace change 有可验证 artifact/test evidence。
Grok Bot Source Case：读 routed MCP bridge、workspace/local exec/isolation/auth，先提取 capability 与 trust boundary，再比较自己的 Adapter。
Codex Source Case（推荐）：不扩新文件面，回到 unified exec + exec_policy.rs + tools/sandboxing.rs，验证 model-visible capability ≠ executable permission：即使 action 被批准，filesystem/network containment 仍必须独立生效。
W12 — Observability / Testing / Eval + Performance
本周以前系统做不到什么 / 为什么现在学：系统已经具备完整运行链路，此时才有足够真实事件做 trace、fault test、eval 与 capacity benchmark；否则指标只是在测 toy demo。
Entry Criteria：v0.11 能跑完整 Run，具备 Queue/Worker、MCP/Workspace、checkpoint/retry。
Learning Level：18 = L3；19 = L3。
阅读：18 Observability / Testing / Eval；19 Performance / Cost / Capacity。
Shadow Harness v0.12：Run/Turn/Model/Tool/Queue trace + deterministic fault suite + eval harness + latency/token/queue metrics + benchmark/backpressure test。
本周只新增的抽象：correlation identity、trace/eval evidence、baseline、capacity envelope；不为“好看 dashboard”增加无 owner 指标。
Golden Run：对同一个 auth bug run_id 关联 model/tool/retry/queue/workspace 事件，并形成可重放 Golden Trace 与 regression eval case。
Failure Injection：故意制造 provider latency、queue overload、Tool timeout、resume；验证能从 trace 定位故障，并用 bounded queue/admission/backpressure 保持容量边界。
Exit Criteria：能从 trace 复盘失败；能区分 deterministic testing 与 model/e2e eval；能做 baseline benchmark、p95 latency/token/cost 和 backpressure 验证。
Grok Bot Source Case：观察 telemetry/action audit/usage 的可关联事实，不照抄 schema；只提取“哪些 execution facts 必须可复盘”。
W13 — Deployment + Full Integration
本周以前系统做不到什么 / 为什么现在学：此前已经补齐 DB/HTTP/Queue/Performance 等生产前置，现在 W13 只做部署与闭环，不再第一次遇到基础运行时机制。
Entry Criteria：v0.12 的 fault suite、trace/eval、benchmark 已通过；所有核心状态有明确 owner 与 durable representation。
Learning Level：20 = L2；21 = L3；按需回看 01–19。
阅读：20 Linux/Docker/Deployment；21 Shadow Harness Integration。
Shadow Harness v1.0：deployment + graceful drain + RunManifest + E2E demo + regression eval。
本周只新增的抽象：process lifecycle、health/readiness、drain protocol、deployment manifest；不再引入新的业务执行语义。
最终链路：
text
Client
→ Run API / Event Stream
→ Context + Model
→ Runtime / Planner / Scheduler
→ Tool / MCP / Workspace
→ Policy / Approval
→ State / Checkpoint / Outbox / Queue
→ Worker / Resume
→ Trace / Test / Eval / BenchmarkGolden Run：在 rolling deploy 中让正在执行的 auth bug Run graceful drain / resume，最终产出 patch、test artifact、RunManifest、trace 与 eval result。
Failure Injection：active worker 收到 termination signal；服务重启；rolling deploy；恢复后 regression eval 必须保持通过。
Exit Criteria：完整 crash/restart/resume + rolling deploy + graceful drain + regression eval；能给每个核心 execution fact 指出 owner、持久化位置和验证方式。
Grok Bot Source Case：最后才回看 Renderer / Electron / Coordinator / Host / Runner / Execution 全链路，比较边界和 trade-off，不追求项目形状一致。
Codex Source Case（推荐）：按 OpenAI Codex Source Map 回看固定的 7 个落点，不再扩覆盖面；每个 Case 必须交付 tag/file/symbol → call chain → Source Fact → invariant → Codex trade-off → Shadow Harness Delta → do-not-over-infer。
每周固定记录
每周在同一个 Shadow Harness 仓库维护：
ADR：本周新增 boundary / invariant 为什么这样设计；Failure Log：本周 failure injection、观测到的错误、修复；Golden Run：同一个 auth token expiration bug 在当前版本下如何运行；Regression：上一版本能力必须继续通过。
最终故障验收清单
- Tool side effect 成功后、本地 checkpoint 前 crash；
- approval pending 时另一个 side effect 尝试启动；
- READY commit 后、enqueue 前 crash；
- 两个 Worker 同时 claim；
- Lease 过期后旧 Worker 晚到提交；
- WAITING 期间整个服务重启；
- webhook 早于 wait registration 到达；
- 旧 checkpoint 被新版本代码恢复；
- Queue redelivery；
- Tool timeout 时无法确认远端是否已经产生副作用；
- Client stream 断开但 Run 按 policy 继续；
- rolling deploy 时 active worker graceful drain。