# Progression Contract
本教程的代码不是 24 个孤立 demo，而是一条围绕桌面 Agent Harness 展开的渐进学习路径：每章继承上一章的稳定边界，只新增一个主要机制。`tests/test_project_structure.py` 会检查每个 `code.py` 都声明 `PROGRESSION` 元数据。
## 机器可检查规则
- 每章 `code.py` 必须定义 `PROGRESSION`。
- `chapter` 必须等于目录名。
- 除 s01 外，每章 `builds_on` 必须指向前一章。
- `adds` 和 `preserves` 必须非空。
- s24 必须把前面机制收束为一个完整 harness。
## 24 章渐进链路
| 章节 | 继承 | 本章新增 | 保留不变 |
|---|---|---|---|
| `s01_agent_loop` | 起点 | minimal agent loop
single bash tool
tool_use/tool_result feedback | interactive CLI |
| `s02_tool_dispatch` | s01_agent_loop | tool dispatch map
read/write/edit/glob tools
workspace path guard | same agent loop shape |
| `s03_deferred_loading` | s02_tool_dispatch | compact deferred tool directory
deterministic tool discovery
session-scoped schema loading | single-source tool registry
dispatch boundary |
| `s04_permission_hooks` | s03_deferred_loading | allow/ask/deny decisions
workspace path scope
separate user approval
auditable execution outcomes | multi-tool execution boundary
hook lifecycle |
| `s05_electron_shell` | s04_permission_hooks | main/renderer/preload split
IPC bridge
process isolation | agent request boundary |
| `s06_sidecar_server` | s05_electron_shell | sidecar control plane
JSON-RPC routing
ring buffer logs | desktop process boundary |
| `s07_session_management` | s06_sidecar_server | logical session and runtime separation
create/resume/close lifecycle
ACP-like HTTP boundary | sidecar-managed runtime |
| `s08_model_routing` | s07_session_management | lite/default/craft routing
cost tracking
agent-to-model mapping | session runtime context |
| `s09_jsonl_transcript` | s08_model_routing | sequenced transcript evidence
derived replay state
partial-tail recovery | model turn event shape |
| `s10_workspace_memory` | s09_jsonl_transcript | workspace-scoped fact log
policy-driven memory distillation
atomic curated memory view | append-only evidence and restart recovery |
| `s11_user_memory` | s10_workspace_memory | user-level memory
preference dedupe
identity prompt blocks | workspace memory layer |
| `s12_cloud_memory` | s11_user_memory | remote profile injection
history recall tool
memory selector | three-layer memory model |
| `s13_output_externalization` | s12_cloud_memory | large output threshold
tool-results swap files
page-fault reads | context budget mindset |
| `s14_context_compact` | s13_output_externalization | token pressure detection
structured compaction
summary preservation | externalized output pointers |
| `s15_prompt_assembly` | s14_context_compact | runtime prompt segments
budgeted context blocks
assembly order | memory and compaction inputs |
| `s16_skills_system` | s15_prompt_assembly | SKILL.md discovery
frontmatter parsing
on-demand skill loading | prompt assembly pipeline |
| `s17_mcp_connectors` | s16_skills_system | connector config
trust workflow
MCP tool namespace | lazy capability loading |
| `s18_experts_system` | s17_mcp_connectors | expert packages
expert prompt injection
session-level expert state | external capability model |
| `s19_visualizer` | s18_experts_system | visualizer protocol
SVG/HTML widget generation
theme-aware output | specialized output routing |
| `s20_result_presentation` | s19_visualizer | present_files flow
artifact cards
deliverable prioritization | visual output artifacts |
| `s21_sqlite_database` | s20_result_presentation | SQLite WAL database
session metadata
usage tracking | deliverable and session persistence |
| `s22_automation_scheduler` | s21_sqlite_database | RRULE scheduling
automation run history
runtime state table | SQLite persistence layer |
| `s23_audit_sandbox` | s22_automation_scheduler | hash-chain audit log
command safety classifier
sandbox policy | scheduled autonomous execution boundary |
| `s24_comprehensive` | s23_audit_sandbox | integrated mini harness
end-to-end agent pipeline
all-layer wiring | all previous chapter mechanisms |
## 读代码时怎么看
先看 `PROGRESSION["adds"]`，再搜索源码里的 `NEW in sXX`、`FROM sXX`、`LAYER` 注释。这样读者能区分：哪些是上一章留下来的 harness 骨架，哪些是本章新加的机制。