docs(zh): s20-s34 标题修正，s35-s48 补充运行验证与新文章

hashpanda · claude · hashpanda · commit d4ae90ab5c68 · 2026-04-09T20:05:13.000+08:00
- s20-s34: 统一验证章节标题为"运行验证"
- s35-s44: 补充运行验证章节，含命令与预期输出
- s45-s46: 新增 feature-flags 与 packaging 完整文章
- s47-s48: 补充运行验证章节

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/docs/zh/s20-basic-streaming.md b/docs/zh/s20-basic-streaming.md
@@ -137,7 +137,7 @@ function StreamingMessage({ content }: { content: string }) {
 )}
 ```
 
-## 验证
+## 运行验证
 
 ```bash
 cd agents/s20-basic-streaming && npm run dev
diff --git a/docs/zh/s21-advanced-streaming.md b/docs/zh/s21-advanced-streaming.md
@@ -175,7 +175,7 @@ function ThinkingMessage({ content, streaming }) {
 }
 ```
 
-## 验证
+## 运行验证
 
 ```bash
 cd agents/s21-advanced-streaming && npm run dev
diff --git a/docs/zh/s22-parallel-tools.md b/docs/zh/s22-parallel-tools.md
@@ -174,7 +174,7 @@ if (safeCount > 1) {
 const toolResults = await executor.executeAll();
 ```
 
-## 验证
+## 运行验证
 
 ```bash
 cd agents/s22-parallel-tools && npm run dev
diff --git a/docs/zh/s23-startup-perf.md b/docs/zh/s23-startup-perf.md
@@ -221,7 +221,7 @@ export function startPrefetch(cwd: string) {
   - 预热 API 连接
 ```
 
-## 验证
+## 运行验证
 
 ```bash
 cd agents/s23-startup-perf
diff --git a/docs/zh/s24-auto-compact.md b/docs/zh/s24-auto-compact.md
@@ -204,7 +204,7 @@ private async maybeCompact(onOutput): Promise<void> {
 
 关键点：`this.messages` 是跨 `run()` 调用持久化的。压缩后直接替换引用。
 
-## 验证
+## 运行验证
 
 ```bash
 cd agents/s24-auto-compact
diff --git a/docs/zh/s25-multi-compact.md b/docs/zh/s25-multi-compact.md
@@ -173,7 +173,7 @@ try {
 await this.maybeAutoCompact(onOutput);
 ```
 
-## 验证
+## 运行验证
 
 ```bash
 cd agents/s25-multi-compact
diff --git a/docs/zh/s26-tool-result-budget.md b/docs/zh/s26-tool-result-budget.md
@@ -169,7 +169,7 @@ const processed = processToolResult(
 this.applyBudget(onOutput);  // 确保不超预算
 ```
 
-## 验证
+## 运行验证
 
 ```bash
 cd agents/s26-tool-result-budget
diff --git a/docs/zh/s27-todo-write.md b/docs/zh/s27-todo-write.md
@@ -163,7 +163,7 @@ export const todoWriteTool = buildTool({
 });
 ```
 
-## 验证
+## 运行验证
 
 ```bash
 cd agents/s27-todo-write
diff --git a/docs/zh/s28-subagent-basic.md b/docs/zh/s28-subagent-basic.md
@@ -125,7 +125,7 @@ export const agentTool = buildTool({
 
 关键点：子 Agent 运行完整的 Agent Loop（while + tool_use），但有自己独立的 messages 数组。
 
-## 验证
+## 运行验证
 
 ```bash
 cd agents/s28-subagent-basic
diff --git a/docs/zh/s29-subagent-advanced.md b/docs/zh/s29-subagent-advanced.md
@@ -134,7 +134,7 @@ async call(input, context) {
 }
 ```
 
-## 验证
+## 运行验证
 
 ```bash
 cd agents/s29-subagent-advanced
diff --git a/docs/zh/s30-skill-system.md b/docs/zh/s30-skill-system.md
@@ -144,7 +144,7 @@ export const toolSearchTool = buildTool({
 });
 ```
 
-## 验证
+## 运行验证
 
 ```bash
 cd agents/s30-skill-system
diff --git a/docs/zh/s31-task-system.md b/docs/zh/s31-task-system.md
@@ -147,7 +147,7 @@ task_list({ status: "pending" })
 task_get({ id: "1" })
 ```
 
-## 验证
+## 运行验证
 
 ```bash
 cd agents/s31-task-system
diff --git a/docs/zh/s32-permission-engine.md b/docs/zh/s32-permission-engine.md
@@ -168,7 +168,7 @@ function checkBashPermissions(input): PermissionDecision {
 }
 ```
 
-## 验证
+## 运行验证
 
 ```bash
 cd agents/s32-permission-engine
diff --git a/docs/zh/s33-permission-ui.md b/docs/zh/s33-permission-ui.md
@@ -156,7 +156,7 @@ export class PermissionManager {
 
 关键：`Promise` 将异步的 UI 交互转为同步的等待——Agent Loop 在用户做出选择前不会继续执行。
 
-## 验证
+## 运行验证
 
 ```bash
 cd agents/s33-permission-ui
diff --git a/docs/zh/s34-subagent-permissions.md b/docs/zh/s34-subagent-permissions.md
@@ -140,7 +140,7 @@ function resolveSubagentMode(
 }
 ```
 
-## 验证
+## 运行验证
 
 ```bash
 cd agents/s34-subagent-permissions
diff --git a/docs/zh/s35-mcp-client.md b/docs/zh/s35-mcp-client.md
@@ -148,6 +148,25 @@ function createMcpToolProxy(serverName, mcpTool, child): Tool {
 }
 ```
 
+## 运行验证
+
+```bash
+cd agents/s35-mcp-client
+npm run dev
+
+# 1. 启动后观察 MCP 服务器连接日志
+#    → [mcp] Connecting to github-mcp via stdio...
+#    → [mcp] Connected. Discovered 12 tools.
+
+# 2. 让 Agent 调用 MCP 工具
+#    > 帮我查一下 GitHub 上的 open issues
+#    → Agent 调用 mcp__github__list_issues
+#    → 工具名前缀 mcp__<server>__<tool> 表示代理调用
+
+# 3. 观察 JSON-RPC 通信
+#    → initialize → tools/list → tools/call 完整流程
+```
+
 ## 对照 Claude Code
 
 | 维度 | 教学版 (s35) | Claude Code |
diff --git a/docs/zh/s36-mcp-server.md b/docs/zh/s36-mcp-server.md
@@ -93,6 +93,27 @@ export function getMergedMcpConfig(cwd): Record<string, McpServerConfig> {
 }
 ```
 
+## 运行验证
+
+```bash
+cd agents/s36-mcp-server
+
+# 1. 以 MCP 服务端模式启动
+npm run dev -- mcp serve
+
+# 2. 在另一个终端发送 JSON-RPC 请求
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{}}}' | npm run dev -- mcp serve
+# → 返回 serverInfo + capabilities
+
+# 3. 测试工具发现
+echo '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | ...
+# → 返回内置工具列表（bash, file_read, file_write 等）
+
+# 4. 测试多作用域配置
+npm run dev -- mcp list
+# → 显示 user / project / local 三级 MCP 配置
+```
+
 ## 对照 Claude Code
 
 | 维度 | 教学版 (s36) | Claude Code |
diff --git a/docs/zh/s37-session-persistence.md b/docs/zh/s37-session-persistence.md
@@ -119,6 +119,26 @@ export function resumeSession(sessionId, cwd) {
 }
 ```
 
+## 运行验证
+
+```bash
+cd agents/s37-session-persistence
+npm run dev
+
+# 1. 进行几轮对话，建立上下文
+#    > 帮我分析 src/agent.ts 的结构
+#    > 继续优化错误处理部分
+
+# 2. Ctrl+C 退出，检查持久化文件
+ls ~/.agent-cli/projects/*/sessions/
+# → 看到 <sessionId>.jsonl 文件
+
+# 3. 用 --resume 恢复会话
+npm run dev -- --resume
+# → 列出可恢复的会话（时间、消息数、最后发言）
+# → 选择后 Agent 恢复上下文，继续之前的任务
+```
+
 ## 对照 Claude Code
 
 | 维度 | 教学版 (s37) | Claude Code |
diff --git a/docs/zh/s38-plugin-system.md b/docs/zh/s38-plugin-system.md
@@ -131,6 +131,32 @@ export function getPluginMcpServers() {
 }
 ```
 
+## 运行验证
+
+```bash
+cd agents/s38-plugin-system
+
+# 1. 创建一个测试插件
+mkdir -p .plugins/hello-plugin
+cat > .plugins/hello-plugin/plugin.json << 'EOF'
+{
+  "name": "hello-plugin",
+  "version": "1.0.0",
+  "description": "测试插件",
+  "permissions": ["file_read"]
+}
+EOF
+
+# 2. 启动 Agent，观察插件加载
+npm run dev
+# → [plugin] Loaded hello-plugin@1.0.0
+# → [plugin] Validated manifest: permissions OK
+
+# 3. 验证插件注册与启用/禁用
+#    > 列出已加载的插件
+#    → 显示 hello-plugin 及其状态
+```
+
 ## 对照 Claude Code
 
 | 维度 | 教学版 (s38) | Claude Code |
diff --git a/docs/zh/s39-agent-definition.md b/docs/zh/s39-agent-definition.md
@@ -83,6 +83,34 @@ export function parseAgentFromMarkdown(content, source): AgentDefinition | null
 }
 ```
 
+## 运行验证
+
+```bash
+cd agents/s39-agent-definition
+
+# 1. 创建一个自定义 Agent 定义
+mkdir -p .agents
+cat > .agents/reviewer.md << 'EOF'
+---
+name: reviewer
+model: claude-sonnet
+tools:
+  - file_read
+  - grep
+  - glob
+---
+你是一个代码审查专家。只做审查，不修改代码。
+EOF
+
+# 2. 启动并加载自定义 Agent
+npm run dev
+# → [agent-def] Loaded reviewer from .agents/reviewer.md
+# → Agent 使用 reviewer 定义的 system prompt 和工具集
+
+# 3. 验证来源优先级
+#    project 定义覆盖 built-in 同名定义
+```
+
 ## 对照 Claude Code
 
 | 维度 | 教学版 (s39) | Claude Code |
diff --git a/docs/zh/s40-coordinator.md b/docs/zh/s40-coordinator.md
@@ -87,6 +87,26 @@ export function filterWorkerTools(allTools) {
 }
 ```
 
+## 运行验证
+
+```bash
+cd agents/s40-coordinator
+npm run dev
+
+# 1. 提交一个需要并行处理的任务
+#    > 帮我同时重构 auth.ts、db.ts 和 api.ts
+
+# 2. 观察 Coordinator 分配任务
+#    → [coordinator] Dispatching 3 workers...
+#    → Worker-1: 处理 auth.ts
+#    → Worker-2: 处理 db.ts
+#    → Worker-3: 处理 api.ts
+
+# 3. 验证工具池隔离
+#    → Coordinator 只有 agent、send_message 等编排工具
+#    → Worker 有 file_read、file_write 等执行工具，但无 agent 工具
+```
+
 ## 对照 Claude Code
 
 | 维度 | 教学版 (s40) | Claude Code |
diff --git a/docs/zh/s41-team-mailbox.md b/docs/zh/s41-team-mailbox.md
@@ -96,6 +96,26 @@ export function readUnreadMessages(teamName, memberName): TeammateMessage[] {
 }
 ```
 
+## 运行验证
+
+```bash
+cd agents/s41-team-mailbox
+npm run dev
+
+# 1. 创建 Team 并观察邮箱初始化
+#    → [team] Created team: my-team
+#    → [mailbox] Initialized inbox for leader, worker-1, worker-2
+
+# 2. 触发跨成员通信
+#    > 让 worker-1 分析代码，结果发给 worker-2
+#    → worker-1 → writeToMailbox("worker-2", result)
+#    → worker-2 → readUnreadMessages() 获取结果
+
+# 3. 检查邮箱文件
+ls ~/.agent-cli/teams/my-team/inboxes/
+# → leader.json  worker-1.json  worker-2.json
+```
+
 ## 对照 Claude Code
 
 | 维度 | 教学版 (s41) | Claude Code |
diff --git a/docs/zh/s42-team-protocols.md b/docs/zh/s42-team-protocols.md
@@ -118,6 +118,25 @@ export function pollForPermissionResponse(teamName, workerName, requestId) {
 }
 ```
 
+## 运行验证
+
+```bash
+cd agents/s42-team-protocols
+npm run dev
+
+# 1. 让 Worker 执行需要权限的操作
+#    > 帮我删除所有临时文件
+
+# 2. 观察协议消息流
+#    → Worker → Leader: PermissionRequest { toolName: "bash", command: "rm ..." }
+#    → Leader 审批: PermissionResponse { approved: true, requestId: "xxx" }
+#    → Worker 收到响应后继续执行
+
+# 3. 验证协议消息与普通消息分离
+#    → isProtocolMessage() 正确识别结构化协议 JSON
+#    → requestId 匹配：响应精确关联到对应请求
+```
+
 ## 对照 Claude Code
 
 | 维度 | 教学版 (s42) | Claude Code |
diff --git a/docs/zh/s43-worktree-isolation.md b/docs/zh/s43-worktree-isolation.md
@@ -113,6 +113,30 @@ export function withAgentWorktree(agentId, cwd, fn) {
 }
 ```
 
+## 运行验证
+
+```bash
+cd agents/s43-worktree-isolation
+npm run dev
+
+# 1. 让 Agent 创建子 Agent 执行任务
+#    > 帮我在隔离环境中重构 auth.ts
+
+# 2. 观察 Worktree 创建
+#    → [worktree] Created .claude/worktrees/agent-abc12345/
+#    → [worktree] Branch: worktree-agent-abc12345
+#    → Agent 在隔离目录中工作，主目录不受影响
+
+# 3. 验证隔离性
+ls .claude/worktrees/
+# → 每个 Agent 有独立目录和分支
+
+# 4. 观察清理行为
+#    → 无更改的 worktree 自动清理
+#    → 有更改的保留供用户审查
+git worktree list
+```
+
 ## 对照 Claude Code
 
 | 维度 | 教学版 (s43) | Claude Code |
diff --git a/docs/zh/s44-error-recovery.md b/docs/zh/s44-error-recovery.md
diff --git a/docs/zh/s45-feature-flags.md b/docs/zh/s45-feature-flags.md
diff --git a/docs/zh/s46-packaging.md b/docs/zh/s46-packaging.md
diff --git a/docs/zh/s47-native-capabilities.md b/docs/zh/s47-native-capabilities.md
diff --git a/docs/zh/s48-telemetry-diagnostics.md b/docs/zh/s48-telemetry-diagnostics.md

Original file line number	Diff line number	Diff line change
`@@ -175,7 +175,7 @@ function ThinkingMessage({ content, streaming }) {`
`175`	`175`	`}`
`176`	`176`	```
`177`	`177`
`178`		`-## 验证`
	`178`	`+## 运行验证`
`179`	`179`
`180`	`180`	```bash
`181`	`181`	`cd agents/s21-advanced-streaming && npm run dev`
Original file line number	Diff line number	Diff line change
`@@ -134,7 +134,7 @@ async call(input, context) {`
`134`	`134`	`}`
`135`	`135`	```
`136`	`136`
`137`		`-## 验证`
	`137`	`+## 运行验证`
`138`	`138`
`139`	`139`	```bash
`140`	`140`	`cd agents/s29-subagent-advanced`