fix: address Q2 and Q6 from PR #265 review

Bill-Billion · claude · Bill-Billion · commit 39f521617895 · 2026-05-04T09:38:21.000+08:00
Q2: Replace stage labels ("阶段一：工具管线 | 第 1/4 章")
    with simple chapter numbering ("第 1/19 章")
    — beginner-friendly, no unexplained jargon

Q6: Add inline footnotes to s02 CC deep dive for forward references
    - TaskCreate → "(TaskCreate 在 s12 介绍)"
    - PreToolUse hooks → "(s04 详细介绍)"
    - Zod schema → "(教学版用 JSON Schema 替代)"
    - FileRead Infinity → expanded circular loop explanation

Co-Authored-By: Claude Opus 4.7 &lt;noreply@anthropic.com&gt;
diff --git a/s01_agent_loop/README.md b/s01_agent_loop/README.md
@@ -4,7 +4,7 @@
 
 `s01` → s02 → s03 → s04 → ... → s19
 
-> 阶段一：工具管线  |  第 1/4 章
+> 第 1/19 章
 
 ---
 
diff --git a/s02_tool_use/README.md b/s02_tool_use/README.md
@@ -4,7 +4,7 @@
 
 s01 → `s02` → [s03](../s03_permission/) → s04 → ... → s19
 
-> 阶段一：工具管线  |  第 2/4 章
+> 第 2/19 章
 
 ---
 
@@ -209,7 +209,7 @@ s03 Permission → 在工具执行之前加一道门：这个操作安全吗？
 | Glob | true | true |
 | Bash `ls` | true | **true** ← 关键差异 |
 | Bash `rm` | false | false |
-| TaskCreate | false | **true** ← 改状态但可并发 |
+| TaskCreate | false | **true** ← 改状态但可并发（TaskCreate 在 s12 介绍） |
 
 CC 的 Bash tool 的 `isConcurrencySafe` 等于 `isReadOnly`——只读命令可并发，写命令不可。TaskCreate 虽然改了任务文件，但每次都写不同的文件，所以可以并发。教学版用工具名硬编码分组，丢了 Bash 的输入相关性，但保留了核心概念。
 
@@ -230,10 +230,10 @@ CC 的 `partitionToolCalls()`（`toolOrchestration.ts:91`）不是分两组，
 
 CC 的每个工具调用经过严格的 5 步验证（`toolExecution.ts:599`）：
 
-1. **Zod schema 验证**：参数类型/结构检查
+1. **Zod schema 验证**（教学版用 JSON Schema 替代）：参数类型/结构检查
 2. **工具级 validateInput()**：参数值验证（如路径是否在工作区内）
-3. **PreToolUse hooks**：钩子可以返回消息、修改输入、阻止执行
-4. **权限检查**：canUseTool + checkPermissions → allow/deny/ask
+3. **PreToolUse hooks**（s04 详细介绍）：钩子可以返回消息、修改输入、阻止执行
+4. **权限检查**（s03 的核心内容）：canUseTool + checkPermissions → allow/deny/ask
 5. **执行 tool.call()**
 
 教学版省略了 Zod（用 JSON Schema）、省略了 validateInput（用安全函数）、保留了权限检查和钩子概念。
@@ -244,7 +244,7 @@ CC 的 `StreamingToolExecutor`（`StreamingToolExecutor.ts`）让工具在模型
 
 ### 六、工具结果持久化
 
-每个工具有一个 `maxResultSizeChars` 字段。结果超过这个值就落盘，模型看到的是预览 + 文件路径。FileRead 特殊——设为 `Infinity`，防止读文件的输出又被当成文件落盘（无限循环）。
+每个工具有一个 `maxResultSizeChars` 字段。结果超过这个值就落盘，模型看到的是预览 + 文件路径。FileRead 特殊——设为 `Infinity`，防止读文件的输出又被当成文件落盘。具体来说，如果 FileRead 的结果超过阈值被落盘，模型下次读那个落盘文件时又会触发落盘 → 无限循环（读文件 → 落盘 → 再读 → 再落盘 → ...）。
 
 </details>
 
diff --git a/s03_permission/README.md b/s03_permission/README.md
@@ -4,7 +4,7 @@
 
 s01 → s02 → `s03` → [s04](../s04_hooks/) → s05 → ... → s19
 
-> 阶段一：工具管线  |  第 3/4 章
+> 第 3/19 章
 
 ---
 
diff --git a/s04_hooks/README.md b/s04_hooks/README.md
@@ -4,7 +4,7 @@
 
 s01 → s02 → s03 → `s04` → [s05](../s05_todo_write/) → s06 → ... → s19
 
-> 阶段一：工具管线  |  第 4/4 章
+> 第 4/19 章
 
 ---
 
diff --git a/s05_todo_write/README.md b/s05_todo_write/README.md
@@ -4,7 +4,7 @@
 
 s01 → s02 → s03 → s04 → `s05` → [s06](../s06_subagent/) → s07 → ... → s19
 
-> 阶段二：单 Agent 能力  |  第 1/4 章
+> 第 5/19 章
 
 ---
 
diff --git a/s06_subagent/README.md b/s06_subagent/README.md
@@ -4,7 +4,7 @@
 
 s01 → s02 → s03 → s04 → s05 → `s06` → [s07](../s07_skill_loading/) → s08 → ... → s19
 
-> 阶段二：单 Agent 能力  |  第 2/4 章
+> 第 6/19 章
 
 ---
 
diff --git a/s07_skill_loading/README.md b/s07_skill_loading/README.md
@@ -4,7 +4,7 @@
 
 s01 → s02 → s03 → s04 → s05 → s06 → `s07` → [s08](../s08_context_compact/) → s09 → ... → s19
 
-> 阶段二：单 Agent 能力  |  第 3/4 章
+> 第 7/19 章
 
 ---
 
diff --git a/s08_context_compact/README.md b/s08_context_compact/README.md
@@ -4,7 +4,7 @@
 
 s01 → s02 → s03 → s04 → s05 → s06 → s07 → `s08` → [s09](../s09_memory/) → s10 → ... → s19
 
-> 阶段二：单 Agent 能力  |  第 4/4 章
+> 第 8/19 章
 
 ---
 
diff --git a/s09_memory/README.md b/s09_memory/README.md
@@ -4,7 +4,7 @@
 
 s01 → ... → s07 → s08 → `s09` → [s10](../s10_system_prompt/) → s11 → ... → s19
 
-> 阶段三：知识与韧性  |  第 1/3 章
+> 第 9/19 章
 
 ---
 
diff --git a/s10_system_prompt/README.md b/s10_system_prompt/README.md
@@ -4,7 +4,7 @@
 
 s01 → ... → s08 → s09 → `s10` → [s11](../s11_error_recovery/) → s12 → ... → s19
 
-> 阶段三：知识与韧性  |  第 2/3 章
+> 第 10/19 章
 
 ---
 
diff --git a/s11_error_recovery/README.md b/s11_error_recovery/README.md
@@ -4,7 +4,7 @@
 
 s01 → ... → s09 → s10 → `s11` → [s12](../s12_task_system/) → s13 → ... → s19
 
-> 阶段三：知识与韧性  |  第 3/3 章
+> 第 11/19 章
 
 ---
 
diff --git a/s12_task_system/README.md b/s12_task_system/README.md
@@ -4,7 +4,7 @@
 
 s01 → ... → s10 → s11 → `s12` → [s13](../s13_background_tasks/) → s14 → ... → s19
 
-> 阶段四：持久化工作  |  第 1/3 章
+> 第 12/19 章
 
 ---
 
diff --git a/s13_background_tasks/README.md b/s13_background_tasks/README.md
@@ -4,7 +4,7 @@
 
 s01 → ... → s11 → s12 → `s13` → [s14](../s14_cron_scheduler/) → s15 → ... → s19
 
-> 阶段四：持久化工作  |  第 2/3 章
+> 第 13/19 章
 
 ---
 
diff --git a/s14_cron_scheduler/README.md b/s14_cron_scheduler/README.md
@@ -4,7 +4,7 @@
 
 s01 → ... → s12 → s13 → `s14` → [s15](../s15_agent_teams/) → s16 → ... → s19
 
-> 阶段四：持久化工作  |  第 3/3 章
+> 第 14/19 章
 
 ---
 
diff --git a/s15_agent_teams/README.md b/s15_agent_teams/README.md
@@ -4,7 +4,7 @@
 
 s01 → ... → s13 → s14 → `s15` → [s16](../s16_team_protocols/) → s17 → s18 → s19
 
-> 阶段五：多 Agent 平台  |  第 1/5 章
+> 第 15/19 章
 
 ---
 
diff --git a/s16_team_protocols/README.md b/s16_team_protocols/README.md
@@ -4,7 +4,7 @@
 
 s01 → ... → s14 → s15 → `s16` → [s17](../s17_autonomous_agents/) → s18 → s19
 
-> 阶段五：多 Agent 平台  |  第 2/5 章
+> 第 16/19 章
 
 ---
 
diff --git a/s17_autonomous_agents/README.md b/s17_autonomous_agents/README.md
@@ -4,7 +4,7 @@
 
 s01 → ... → s15 → s16 → `s17` → [s18](../s18_worktree_isolation/) → s19
 
-> 阶段五：多 Agent 平台  |  第 3/5 章
+> 第 17/19 章
 
 > **教学说明**：本章的 autonomous agent 机制（空闲循环、自动认领）是教学假设——真实 CC 中没有这套独立的自组织系统。CC 的任务认领是通过 `useTaskListWatcher` + 文件锁实现的，没有 idle cycle。本章的教学目的是展示**自组织 Agent 团队的核心思想**，不声称这是 CC 的实际实现。
 
diff --git a/s18_worktree_isolation/README.md b/s18_worktree_isolation/README.md
@@ -4,7 +4,7 @@
 
 s01 → ... → s16 → s17 → `s18` → [s19](../s19_mcp_plugin/)
 
-> 阶段五：多 Agent 平台  |  第 4/5 章
+> 第 18/19 章
 
 ---
 
diff --git a/s19_mcp_plugin/README.md b/s19_mcp_plugin/README.md
@@ -4,7 +4,7 @@
 
 s01 → ... → s17 → s18 → `s19`
 
-> 阶段五：多 Agent 平台  |  第 5/5 章
+> 第 19/19 章
 
 ---
 
