fix(agents): remove zh garbling and normalize mixed-language docs

Author: wangzhuo

agents/zh/s01_agent_loop.py

@@ -68,7 +68,7 @@ class LoopState:
 def run_bash(command: str) -> str:
     dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
     if any(item in command for item in dangerous):
-        return "Error: ???????"
+        return "Error: 危险命令已拦截"
     try:
         result = subprocess.run(
             command,

agents/zh/s02_tool_use.py

@@ -43,7 +43,7 @@ def safe_path(p: str) -> Path:
 def run_bash(command: str) -> str:
     dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
     if any(d in command for d in dangerous):
-        return "Error: ???????"
+        return "Error: 危险命令已拦截"
     try:
         r = subprocess.run(command, shell=True, cwd=WORKDIR,
                            capture_output=True, text=True, timeout=120)

agents/zh/s03_todo_write.py

@@ -124,7 +124,7 @@ def safe_path(path_str: str) -> Path:
 def run_bash(command: str) -> str:
     dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
     if any(item in command for item in dangerous):
-        return "Error: ???????"
+        return "Error: 危险命令已拦截"
     try:
         result = subprocess.run(
             command,

agents/zh/s04_subagent.py

@@ -6,19 +6,18 @@
 通过 fresh `messages=[]` 启动 child agent（子智能体）。
 子智能体在独立上下文中工作、共享同一文件系统，最后只把摘要返回给父智能体。
 
-    Parent agent                     Subagent
+    父智能体（Parent agent）              子智能体（Subagent）
     +------------------+             +------------------+
-    | messages=[...]   |             | messages=[]      |  <-- fresh
-    |                  |  dispatch   |                  |
-    | tool: task       | ---------->| while tool_use:  |
-    |   prompt="..."   |            |   call tools     |
-    |   description="" |            |   append results |
-    |                  |  summary   |                  |
-    |   result = "..." | <--------- | return last text |
+    | messages=[...]   |             | messages=[]      |  <-- fresh（新上下文）
+    |                  | dispatch（派发）|                |
+    | 工具: task        | ---------->| while tool_use（工具调用）: |
+    | prompt="..."     |            |   call tools（调用工具）     |
+    | description=""   |            |   append results（追加结果） |
+    |                  | summary（汇总） |                |
+    | result = "..."   | <--------- | return last text（返回摘要） |
     +------------------+             +------------------+
               |
-    父上下文保持干净。
-    子上下文在任务完成后丢弃。
+    父上下文保持干净，子上下文任务结束后丢弃。
 
 关键洞察：
 "fresh messages=[] 就是上下文隔离，父上下文不会被污染。"
@@ -28,20 +27,17 @@
 但拥有新的消息数组和隔离的工具上下文，这与本教学实现一致。
 
     与真实 Claude Code 的对比：
-    +-------------------+------------------+----------------------------------+
-    | Aspect            | This demo        | Real Claude Code                 |
-    +-------------------+------------------+----------------------------------+
-    | Backend           | in-process only  | 5 backends: in-process, tmux,    |
-    |                   |                  | iTerm2, fork, remote             |
-    | Context isolation | fresh messages=[]| createSubagentContext() isolates  |
-    |                   |                  | ~20 fields (tools, permissions,  |
-    |                   |                  | cwd, env, hooks, etc.)           |
-    | Tool filtering    | manually curated | resolveAgentTools() filters from |
-    |                   |                  | parent pool; allowedTools         |
-    |                   |                  | replaces all allow rules         |
-    | Agent definition  | hardcoded system | .claude/agents/*.md with YAML    |
-    |                   | prompt           | frontmatter (AgentTemplate)      |
-    +-------------------+------------------+----------------------------------+
+    +-------------------+----------------------+---------------------------------------------+
+    | 维度（Aspect）     | 教学实现（This demo） | 真实 Claude Code（Real Claude Code）          |
+    +-------------------+----------------------+---------------------------------------------+
+    | 后端（Backend）    | 仅 in-process         | 5 种后端：in-process、tmux、iTerm2、fork、remote |
+    | 上下文隔离         | fresh messages=[]     | createSubagentContext() 隔离约 20 个字段（tools、 |
+    | （Context isolation）|                      | permissions、cwd、env、hooks 等）             |
+    | 工具过滤           | 手工挑选               | resolveAgentTools() 从父工具池过滤；allowedTools |
+    | （Tool filtering） |                      | 可替代所有 allow 规则                        |
+    | 智能体定义         | 代码内硬编码 prompt    | `.claude/agents/*.md` + YAML frontmatter      |
+    | （Agent definition）|                     | （模板 AgentTemplate）                        |
+    +-------------------+----------------------+---------------------------------------------+
 """
 
 import os
@@ -78,8 +74,9 @@ class AgentTemplate:
 
     真实 Claude Code 会从 `.claude/agents/*.md` 读取 agent 定义。
     frontmatter 字段包括：name、tools、disallowedTools、skills、hooks、
-    model、effort、permissionMode、maxTurns、memory、isolation、color、
-    background、initialPrompt、mcpServers。
+    model（模型）、effort（推理力度）、permissionMode（权限模式）、maxTurns（轮次上限）、
+    memory（记忆）、isolation（隔离）、color（颜色）、background（后台）、
+    initialPrompt（初始提示）、mcpServers（MCP 服务配置）。
     来源通常有三类：built-in、custom（`.claude/agents/`）、plugin-provided。
     """
     def __init__(self, path):
@@ -113,7 +110,7 @@ def safe_path(p: str) -> Path:
 def run_bash(command: str) -> str:
     dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
     if any(d in command for d in dangerous):
-        return "Error: ???????"
+        return "Error: 危险命令已拦截"
     try:
         r = subprocess.run(command, shell=True, cwd=WORKDIR,
                            capture_output=True, text=True, timeout=120)

agents/zh/s05_skill_loading.py

@@ -117,7 +117,7 @@ def safe_path(path_str: str) -> Path:
 def run_bash(command: str) -> str:
     dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
     if any(item in command for item in dangerous):
-        return "Error: ???????"
+        return "Error: 危险命令已拦截"
     try:
         result = subprocess.run(
             command,

agents/zh/s06_context_compact.py

@@ -173,7 +173,7 @@ def compact_history(messages: list, state: CompactState, focus: str | None = Non
 def run_bash(command: str, tool_use_id: str) -> str:
     dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
     if any(item in command for item in dangerous):
-        return "Error: ???????"
+        return "Error: 危险命令已拦截"
     try:
         result = subprocess.run(
             command,

agents/zh/s07_permission_system.py

@@ -6,15 +6,15 @@
 每一次工具调用在执行前都必须经过权限管线（permission pipeline）。
 
 教学版管线：
-  1. deny rules
-  2. mode check
-  3. allow rules
-  4. ask user
+  1. deny rules（拒绝规则）
+  2. mode check（模式检查）
+  3. allow rules（放行规则）
+  4. ask user（询问用户）
 
 本版本先聚焦三种模式：
-  - default
-  - plan
-  - auto
+  - default（默认）
+  - plan（规划）
+  - auto（自动）
 
 这已足够搭建可用且可理解的权限系统，不会在起步阶段被复杂策略分支淹没。
 

agents/zh/s08_hook_system.py

@@ -7,14 +7,14 @@
 它允许在不重写循环的前提下增量添加行为。
 
 教学版包含：
-  - SessionStart
-  - PreToolUse
-  - PostToolUse
+  - SessionStart（会话开始）
+  - PreToolUse（工具调用前）
+  - PostToolUse（工具调用后）
 
 教学版退出码约定：
-  - 0 -> continue
-  - 1 -> block
-  - 2 -> inject a message
+  - 0 -> continue（继续）
+  - 1 -> block（阻断）
+  - 2 -> inject a message（注入消息）
 
 这里刻意简化于生产系统，先把扩展模式讲清楚，再进入事件级边界细节。
 
@@ -183,7 +183,7 @@ def safe_path(p: str) -> Path:
 def run_bash(command: str) -> str:
     dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
     if any(d in command for d in dangerous):
-        return "Error: ???????"
+        return "Error: 危险命令已拦截"
     try:
         r = subprocess.run(command, shell=True, cwd=WORKDIR,
                            capture_output=True, text=True, timeout=120)

agents/zh/s09_memory_system.py

@@ -7,15 +7,15 @@
 有些信息应该跨会话保留，但并非所有内容都适合进入 memory（记忆）。
 
 建议写入 memory 的内容：
-  - user preferences
-  - repeated user feedback
-  - project facts that are NOT obvious from the current code
-  - pointers to external resources
+  - user preferences（用户偏好）
+  - repeated user feedback（反复出现的用户反馈）
+  - project facts that are NOT obvious from the current code（无法直接从当前代码显见的项目事实）
+  - pointers to external resources（外部资源指针）
 
 不应写入 memory 的内容：
-  - code structure that can be re-read from the repo
-  - temporary task state
-  - secrets
+  - code structure that can be re-read from the repo（可从仓库重新读取的代码结构）
+  - temporary task state（临时任务状态）
+  - secrets（敏感密钥与口令）
 
 存储结构：
   .memory/
@@ -351,7 +351,7 @@ def safe_path(p: str) -> Path:
 def run_bash(command: str) -> str:
     dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
     if any(d in command for d in dangerous):
-        return "Error: ???????"
+        return "Error: 危险命令已拦截"
     try:
         r = subprocess.run(command, shell=True, cwd=WORKDIR,
                            capture_output=True, text=True, timeout=120)

agents/zh/s10_system_prompt.py

@@ -7,12 +7,12 @@
 system prompt 应由清晰分段组装，而不是写成一整块硬编码大文本。
 
 教学版构建管线：
-  1. core instructions
-  2. tool listing
-  3. skill metadata
-  4. memory section
-  5. CLAUDE.md chain
-  6. dynamic context
+  1. core instructions（核心指令）
+  2. tool listing（工具清单）
+  3. skill metadata（技能元数据）
+  4. memory section（记忆区段）
+  5. CLAUDE.md chain（CLAUDE 指令链）
+  6. dynamic context（动态上下文）
 
 构建器会把稳定信息与高频变化信息分离，
 并用 `DYNAMIC_BOUNDARY` 标记显式展示边界。
@@ -153,15 +153,15 @@ def _build_claude_md(self) -> str:
         # 项目根目录
         project_claude = self.workdir / "CLAUDE.md"
         if project_claude.exists():
-            sources.append(("project root (CLAUDE.md)", project_claude.read_text()))
+            sources.append(("项目根目录（project root / CLAUDE.md）", project_claude.read_text()))
 
         # 子目录：真实 CC 会从 cwd 向上遍历到项目根；
         # 教学版简化为仅在 cwd != workdir 时检查一次。
         cwd = Path.cwd()
         if cwd != self.workdir:
             subdir_claude = cwd / "CLAUDE.md"
             if subdir_claude.exists():
-                sources.append((f"subdir ({cwd.name}/CLAUDE.md)", subdir_claude.read_text()))
+                sources.append((f"子目录（subdir / {cwd.name}/CLAUDE.md）", subdir_claude.read_text()))
 
         if not sources:
             return ""
@@ -176,8 +176,8 @@ def _build_dynamic_context(self) -> str:
         lines = [
             f"当前日期: {datetime.date.today().isoformat()}",
             f"工作目录: {self.workdir}",
-            f"Model: {MODEL}",
-            f"Platform: {platform.system()}",
+            f"模型（Model）: {MODEL}",
+            f"平台（Platform）: {platform.system()}",
         ]
         return "# 动态上下文\n" + "\n".join(lines)
 
@@ -248,7 +248,7 @@ def safe_path(p: str) -> Path:
 def run_bash(command: str) -> str:
     dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
     if any(d in command for d in dangerous):
-        return "Error: ???????"
+        return "Error: 危险命令已拦截"
     try:
         r = subprocess.run(command, shell=True, cwd=WORKDIR,
                            capture_output=True, text=True, timeout=120)