refine: incremental code pattern — each code.py visibly builds on previous

Rewrite all 19 code.py files to show explicit "在 sXX 基础上新增" lineage:
- Docstring states which chapter this builds on and what was added
- Visual markers (═══ FROM sXX / NEW in sYY ═══) separate inherited
  from new code
- agent_loop comments show exact line changes from previous chapter
- Print message at startup tells reader which chapter they're extending

This restores the "incremental optimization" soul that made the original
agents/s01-s12 version feel like a coherent step-by-step build, rather
than 19 disconnected standalone chapters.

s01-s04: Full cumulative code with markers
s05-s08: Cumulative code with markers (compact for later chapters)
s09-s19: Incremental docstrings + agent_loop with change annotations

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: Bill-Billion

s02_tool_use/code.py

@@ -1,22 +1,20 @@
 #!/usr/bin/env python3
 """
-s02: Tool Use — 工具分发，循环不变。
+s02: Tool Use — 在 s01 基础上新增 4 个工具 + 分发映射 + 并发分区。
 
-运行方式:
-    python s02_tool_use/code.py
+运行: python s02_tool_use/code.py
+需要: pip install anthropic python-dotenv + .env 中配置 ANTHROPIC_API_KEY
 
-需要:
-    - pip install anthropic python-dotenv
-    - .env 文件中配置 ANTHROPIC_API_KEY 或 ANTHROPIC_BASE_URL + MODEL_ID
+本文件 = s01 的全部代码 + 以下新增:
+  + run_read / run_write / run_edit / run_glob 四个工具实现
+  + TOOL_HANDLERS 分发映射（替代 s01 中硬编码的 run_bash 调用）
+  + partition_tool_calls 并发分区
+  + safe_path 路径安全校验
 
-代码对应 README 章节:
-    TOOLS / TOOL_HANDLERS  → 工具定义与分发
-    partition_tool_calls() → 并发 vs 顺序执行
-    agent_loop()           → 循环本身（与 s01 完全相同）
+循环本身（agent_loop）与 s01 完全一致。
 """
 
-import os
-import subprocess
+import os, subprocess
 from pathlib import Path
 
 try:
@@ -32,7 +30,6 @@
 from dotenv import load_dotenv
 
 load_dotenv(override=True)
-
 if os.getenv("ANTHROPIC_BASE_URL"):
     os.environ.pop("ANTHROPIC_AUTH_TOKEN", None)
 
@@ -43,14 +40,9 @@
 SYSTEM = f"You are a coding agent at {WORKDIR}. Use tools to solve tasks. Act, don't explain."
 
 
-def safe_path(p: str) -> Path:
-    path = (WORKDIR / p).resolve()
-    if not path.is_relative_to(WORKDIR):
-        raise ValueError(f"Path escapes workspace: {p}")
-    return path
-
-
-# ── 工具实现 ──────────────────────────────────────────────
+# ═══════════════════════════════════════════════════════════
+#  FROM s01 (unchanged)
+# ═══════════════════════════════════════════════════════════
 
 def run_bash(command: str) -> str:
     dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
@@ -63,6 +55,19 @@ def run_bash(command: str) -> str:
         return out[:50000] if out else "(no output)"
     except subprocess.TimeoutExpired:
         return "Error: Timeout (120s)"
+    except (FileNotFoundError, OSError) as e:
+        return f"Error: {e}"
+
+
+# ═══════════════════════════════════════════════════════════
+#  NEW in s02: 4 个新工具
+# ═══════════════════════════════════════════════════════════
+
+def safe_path(p: str) -> Path:
+    path = (WORKDIR / p).resolve()
+    if not path.is_relative_to(WORKDIR):
+        raise ValueError(f"Path escapes workspace: {p}")
+    return path
 
 
 def run_read(path: str, limit: int | None = None) -> str:
@@ -106,79 +111,38 @@ def run_glob(pattern: str) -> str:
         return f"Error: {e}"
 
 
-# ── 工具定义 ──────────────────────────────────────────────
+# ═══════════════════════════════════════════════════════════
+#  NEW in s02: 工具定义（s01 只有一个 bash，现在扩展到 5 个）
+# ═══════════════════════════════════════════════════════════
 
 TOOLS = [
-    {
-        "name": "bash",
-        "description": "Run a shell command.",
-        "input_schema": {
-            "type": "object",
-            "properties": {"command": {"type": "string"}},
-            "required": ["command"],
-        },
-    },
-    {
-        "name": "read_file",
-        "description": "Read file contents.",
-        "input_schema": {
-            "type": "object",
-            "properties": {
-                "path": {"type": "string"},
-                "limit": {"type": "integer"},
-            },
-            "required": ["path"],
-        },
-    },
-    {
-        "name": "write_file",
-        "description": "Write content to a file.",
-        "input_schema": {
-            "type": "object",
-            "properties": {
-                "path": {"type": "string"},
-                "content": {"type": "string"},
-            },
-            "required": ["path", "content"],
-        },
-    },
-    {
-        "name": "edit_file",
-        "description": "Replace exact text in a file once.",
-        "input_schema": {
-            "type": "object",
-            "properties": {
-                "path": {"type": "string"},
-                "old_text": {"type": "string"},
-                "new_text": {"type": "string"},
-            },
-            "required": ["path", "old_text", "new_text"],
-        },
-    },
-    {
-        "name": "glob",
-        "description": "Find files matching a glob pattern.",
-        "input_schema": {
-            "type": "object",
-            "properties": {"pattern": {"type": "string"}},
-            "required": ["pattern"],
-        },
-    },
+    {"name": "bash", "description": "Run a shell command.",
+     "input_schema": {"type": "object", "properties": {"command": {"type": "string"}}, "required": ["command"]}},
+    {"name": "read_file", "description": "Read file contents.",
+     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "limit": {"type": "integer"}}, "required": ["path"]}},
+    {"name": "write_file", "description": "Write content to a file.",
+     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "content": {"type": "string"}}, "required": ["path", "content"]}},
+    {"name": "edit_file", "description": "Replace exact text in a file once.",
+     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "old_text": {"type": "string"}, "new_text": {"type": "string"}}, "required": ["path", "old_text", "new_text"]}},
+    {"name": "glob", "description": "Find files matching a glob pattern.",
+     "input_schema": {"type": "object", "properties": {"pattern": {"type": "string"}}, "required": ["pattern"]}},
 ]
 
+# ═══════════════════════════════════════════════════════════
+#  NEW in s02: 工具分发映射（s01 是硬编码 run_bash，现在改为查表）
+# ═══════════════════════════════════════════════════════════
+
 TOOL_HANDLERS = {
-    "bash": run_bash,
-    "read_file": run_read,
-    "write_file": run_write,
-    "edit_file": run_edit,
-    "glob": run_glob,
+    "bash": run_bash, "read_file": run_read, "write_file": run_write,
+    "edit_file": run_edit, "glob": run_glob,
 }
 
 
-# ── 工具分区 ──────────────────────────────────────────────
+# ═══════════════════════════════════════════════════════════
+#  NEW in s02: 并发分区（s01 只有 bash 单个工具，不需要分区）
+# ═══════════════════════════════════════════════════════════
 
 def partition_tool_calls(blocks):
-    """Split tool calls into sequential (may modify filesystem) and concurrent (read-only)."""
     concurrent, sequential = [], []
     for block in blocks:
         if block.type != "tool_use":
@@ -190,58 +154,46 @@ def partition_tool_calls(blocks):
     return concurrent, sequential
 
 
-# ── 核心：Agent Loop（与 s01 完全相同）────────────────────
-
-def execute_tool(block) -> str:
-    handler = TOOL_HANDLERS.get(block.name)
-    if not handler:
-        return f"Unknown tool: {block.name}"
-    return handler(**block.input)
-
+# ═══════════════════════════════════════════════════════════
+#  agent_loop — 与 s01 结构完全一致，只改了工具执行那一行
+#  s01: output = run_bash(block.input["command"])
+#  s02: output = TOOL_HANDLERS[block.name](**block.input)
+# ═══════════════════════════════════════════════════════════
 
 def agent_loop(messages: list):
     while True:
         response = client.messages.create(
             model=MODEL, system=SYSTEM, messages=messages,
             tools=TOOLS, max_tokens=8000,
         )
-
         messages.append({"role": "assistant", "content": response.content})
 
         if response.stop_reason != "tool_use":
             return
 
-        # 分区执行：先跑可能改文件系统的，再并发跑只读的
+        # s02 改动: 分区执行（s01 是直接循环执行）
         concurrent, sequential = partition_tool_calls(response.content)
         results = []
 
         for block in sequential:
-            print(f"\033[33m> {block.name}({list(block.input.values())[:1]})\033[0m")
-            output = execute_tool(block)
-            print(output[:200])
-            results.append({
-                "type": "tool_result",
-                "tool_use_id": block.id,
-                "content": output,
-            })
+            print(f"\033[33m> {block.name}\033[0m")
+            handler = TOOL_HANDLERS.get(block.name)  # s02: 查表替代硬编码
+            output = handler(**block.input) if handler else f"Unknown: {block.name}"
+            print(str(output)[:200])
+            results.append({"type": "tool_result", "tool_use_id": block.id, "content": output})
 
         for block in concurrent:
-            print(f"\033[36m> {block.name}({list(block.input.values())[:1]})\033[0m")
-            output = execute_tool(block)
-            print(output[:200])
-            results.append({
-                "type": "tool_result",
-                "tool_use_id": block.id,
-                "content": output,
-            })
+            print(f"\033[36m> {block.name}\033[0m")
+            handler = TOOL_HANDLERS.get(block.name)
+            output = handler(**block.input) if handler else f"Unknown: {block.name}"
+            print(str(output)[:200])
+            results.append({"type": "tool_result", "tool_use_id": block.id, "content": output})
 
         messages.append({"role": "user", "content": results})
 
 
-# ── 入口 ─────────────────────────────────────────────────
-
 if __name__ == "__main__":
-    print("s02: Tool Use")
+    print("s02: Tool Use — 在 s01 基础上加了 4 个工具")
     print("输入问题，回车发送。输入 q 退出。\n")
 
     history = []
@@ -254,9 +206,7 @@ def agent_loop(messages: list):
             break
         history.append({"role": "user", "content": query})
         agent_loop(history)
-        response_content = history[-1]["content"]
-        if isinstance(response_content, list):
-            for block in response_content:
-                if getattr(block, "type", None) == "text":
-                    print(block.text)
+        for block in history[-1]["content"]:
+            if getattr(block, "type", None) == "text":
+                print(block.text)
         print()