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 骨架，哪些是本章新加的机制。