diff --git a/.gitignore b/.gitignore index e43b0f9..85ef4cc 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ .DS_Store +command.log diff --git "a/00-\345\211\215\350\250\200.md" "b/00-\345\211\215\350\250\200.md" index 3301dd7..1d08788 100644 --- "a/00-\345\211\215\350\250\200.md" +++ "b/00-\345\211\215\350\250\200.md" @@ -43,50 +43,8 @@ 这三次浪潮可以用一张简明的演进图来概括： -```mermaid -flowchart LR - subgraph wave1["2021-2022"] - A["代码补全\nInline Complete"] - end - subgraph wave2["2023-2024"] - B["对话助手\nChat Assisted"] - end - subgraph wave3["2025 至今"] - C["自主智能体\nAgent Autonomy"] - end - - wave1 --> wave2 --> wave3 - - classDef era fill:#e8f4f8,stroke:#2196F3,stroke-width:2px,color:#1565C0 - class A,B,C era -``` - -```mermaid -flowchart LR - subgraph w1["第一次浪潮"] - direction TB - A1["Tab 接受建议"] - A2["单文件局部补全"] - A3["被动等待触发"] - A4["无执行能力"] - end - subgraph w2["第二次浪潮"] - direction TB - B1["Ctrl+L 对话提问"] - B2["多文件跨文件生成"] - B3["主动理解意图"] - B4["无执行能力"] - end - subgraph w3["第三次浪潮"] - direction TB - C1["直接交付任务"] - C2["跨工具自主编排"] - C3["主动规划执行路径"] - C4["读/写/执行/验证"] - end - - w1 --> w2 --> w3 -``` +![AI 编程范式演进](assets/render_evolution_graph.png) + ### Agent Harness：一个新架构概念的诞生 @@ -164,32 +122,7 @@ flowchart LR 本书分为四个部分，按照从宏观到微观、从概念到实现的组织方式： -```mermaid -flowchart TD - subgraph part1["第一部分：基础篇（第 1-4 章）"] - direction LR - ch1["第1章\n新范式\n全景导览"] --> ch2["第2章\n对话循环\nAgent心跳"] --> ch3["第3章\n工具系统\nAgent双手"] --> ch4["第4章\n权限管线\nAgent护栏"] - end - - subgraph part2["第二部分：核心篇（第 5-8 章）"] - core["上下文管理 · 缓存策略 · 流式架构 · 错误恢复"] - end - - subgraph part3["第三部分：扩展篇（第 9-12 章）"] - ext["MCP 协议 · 子智能体 · 插件系统 · Hook 机制"] - end - - subgraph part4["第四部分：实战篇（第 13-15 章）"] - practice["Mini Agent Harness 构建 · 调试技巧 · 生产部署"] - end - - part1 --> part2 --> part3 --> part4 - - classDef section fill:#f3f9ff,stroke:#3b82f6,stroke-width:2px,color:#1e40af - classDef chapter fill:#eff6ff,stroke:#60a5fa,stroke-width:1px,color:#2563eb - class part1,part2,part3,part4 section - class ch1,ch2,ch3,ch4 chapter -``` +![书籍结构概述](assets/book_structure_overview.png) **如果你时间有限（快速路径）：** 至少阅读第 1 章（建立心智模型）和第 2 章（理解核心循环），然后用 15 分钟浏览第 3-4 章的关键要点部分。这两章是理解后续所有内容的基础。 diff --git a/README.md b/README.md index 2008f80..9c12937 100644 --- a/README.md +++ b/README.md @@ -162,7 +162,7 @@ ## 背景 -2026 年 3 月 31 日，安全研究员 [Chaofan Shou (@Fried_rice)](https://x.com/Fried_rice) 发现 npm registry 中的 `@anthropic-ai/claude-code` 包存在构建配置失误，source map 文件引用了未设访问控制的 Cloudflare R2 存储桶。披露推文获得超 1700 万次浏览，引发了技术社区对 Agent 架构的空前讨论。 +2026 年 3 月 31 日，安全研究员 [Chaofan Shou (@Fried_rice)](https://x.com/Fried_rice) 发现 npm registry 中的 `@anthropic-ai/claude-code` 包存在构建配置失误。披露推文获得超 1700 万次浏览，引发了技术社区对 Agent 架构的空前讨论。 这本书的诞生正是受到这场讨论的启发——当 Agent 架构成为热门话题，我们意识到需要一本系统性的书来讲解 Agent Harness 的设计原理。 diff --git a/assets/book_structure_overview.png b/assets/book_structure_overview.png new file mode 100644 index 0000000..e634ebc Binary files /dev/null and b/assets/book_structure_overview.png differ diff --git a/assets/fundamentals/ai_programming_tools_evolution_timeline.png b/assets/fundamentals/ai_programming_tools_evolution_timeline.png new file mode 100644 index 0000000..458f198 Binary files /dev/null and b/assets/fundamentals/ai_programming_tools_evolution_timeline.png differ diff --git a/assets/fundamentals/async_generator_diagram.png b/assets/fundamentals/async_generator_diagram.png new file mode 100644 index 0000000..b15e0b2 Binary files /dev/null and b/assets/fundamentals/async_generator_diagram.png differ diff --git a/assets/fundamentals/claude_code_architecture_overview.png b/assets/fundamentals/claude_code_architecture_overview.png new file mode 100644 index 0000000..dd2ea97 Binary files /dev/null and b/assets/fundamentals/claude_code_architecture_overview.png differ diff --git a/assets/fundamentals/llm_human_interaction.png b/assets/fundamentals/llm_human_interaction.png new file mode 100644 index 0000000..53bc8f2 Binary files /dev/null and b/assets/fundamentals/llm_human_interaction.png differ diff --git a/assets/fundamentals/message_types_diagram.png b/assets/fundamentals/message_types_diagram.png new file mode 100644 index 0000000..f3198a5 Binary files /dev/null and b/assets/fundamentals/message_types_diagram.png differ diff --git a/assets/fundamentals/six_engineering_challenges.png b/assets/fundamentals/six_engineering_challenges.png new file mode 100644 index 0000000..92d7f9a Binary files /dev/null and b/assets/fundamentals/six_engineering_challenges.png differ diff --git a/assets/fundamentals/state_transition_diagram.jpeg b/assets/fundamentals/state_transition_diagram.jpeg new file mode 100644 index 0000000..bcef2ab Binary files /dev/null and b/assets/fundamentals/state_transition_diagram.jpeg differ diff --git a/assets/fundamentals/termination_reasons_diagram.png b/assets/fundamentals/termination_reasons_diagram.png new file mode 100644 index 0000000..6f75765 Binary files /dev/null and b/assets/fundamentals/termination_reasons_diagram.png differ diff --git a/assets/fundamentals/tools_partition_example.png b/assets/fundamentals/tools_partition_example.png new file mode 100644 index 0000000..e6edd44 Binary files /dev/null and b/assets/fundamentals/tools_partition_example.png differ diff --git a/assets/fundamentals/tools_state_machine.png b/assets/fundamentals/tools_state_machine.png new file mode 100644 index 0000000..ac6672b Binary files /dev/null and b/assets/fundamentals/tools_state_machine.png differ diff --git a/assets/fundamentals/turn_lifecycle_diagram.png b/assets/fundamentals/turn_lifecycle_diagram.png new file mode 100644 index 0000000..35b13f3 Binary files /dev/null and b/assets/fundamentals/turn_lifecycle_diagram.png differ diff --git a/assets/render_evolution_graph.png b/assets/render_evolution_graph.png new file mode 100644 index 0000000..7ce327d Binary files /dev/null and b/assets/render_evolution_graph.png differ diff --git a/en/00-Foreword.md b/en/00-Foreword.md index 0087f9c..43b96eb 100644 --- a/en/00-Foreword.md +++ b/en/00-Foreword.md @@ -14,50 +14,7 @@ Looking back over the past few years, AI-assisted programming has gone through t These three waves can be summarized in a concise evolution diagram: -```mermaid -flowchart LR - subgraph wave1["2021-2022"] - A["Code Completion\nInline Complete"] - end - subgraph wave2["2023-2024"] - B["Chat Assistant\nChat Assisted"] - end - subgraph wave3["2025 to present"] - C["Autonomous Agent\nAgent Autonomy"] - end - - wave1 --> wave2 --> wave3 - - classDef era fill:#e8f4f8,stroke:#2196F3,stroke-width:2px,color:#1565C0 - class A,B,C era -``` - -```mermaid -flowchart LR - subgraph w1["First Wave"] - direction TB - A1["Tab to accept suggestions"] - A2["Single-file local completion"] - A3["Passively waiting for triggers"] - A4["No execution capability"] - end - subgraph w2["Second Wave"] - direction TB - B1["Ctrl+L conversational queries"] - B2["Multi-file cross-file generation"] - B3["Proactive intent understanding"] - B4["No execution capability"] - end - subgraph w3["Third Wave"] - direction TB - C1["Direct task delegation"] - C2["Cross-tool autonomous orchestration"] - C3["Proactive execution path planning"] - C4["Read/Write/Execute/Verify"] - end - - w1 --> w2 --> w3 -``` +![Evolution of the AI Programming Paradigm](assets/render_evolution_graph.png) ### Agent Harness: The Birth of a New Architectural Concept @@ -135,32 +92,7 @@ This book is suitable for the following readers, each of whom can gain unique va This book is divided into four parts, organized from macro to micro, from concept to implementation: -```mermaid -flowchart TD - subgraph part1["Part 1: Foundations (Chapters 1-4)"] - direction LR - ch1["Chapter 1\nNew Paradigm\nPanoramic Overview"] --> ch2["Chapter 2\nDialog Loop\nAgent Heartbeat"] --> ch3["Chapter 3\nTool System\nAgent Hands"] --> ch4["Chapter 4\nPermission Pipeline\nAgent Guardrails"] - end - - subgraph part2["Part 2: Core (Chapters 5-8)"] - core["Context Management · Cache Strategy · Streaming Architecture · Error Recovery"] - end - - subgraph part3["Part 3: Extensions (Chapters 9-12)"] - ext["MCP Protocol · Sub-Agents · Plugin System · Hook Mechanism"] - end - - subgraph part4["Part 4: Practice (Chapters 13-15)"] - practice["Mini Agent Harness Build · Debugging Tips · Production Deployment"] - end - - part1 --> part2 --> part3 --> part4 - - classDef section fill:#f3f9ff,stroke:#3b82f6,stroke-width:2px,color:#1e40af - classDef chapter fill:#eff6ff,stroke:#60a5fa,stroke-width:1px,color:#2563eb - class part1,part2,part3,part4 section - class ch1,ch2,ch3,ch4 chapter -``` +![Book Structure Overview](assets/book_structure_overview.png) **If you are short on time (Fast Path):** Read at least Chapter 1 (to establish a mental model) and Chapter 2 (to understand the core loop), then spend 15 minutes browsing the key takeaways sections of Chapters 3-4. These two chapters are the foundation for understanding everything that follows. diff --git a/en/Part-1-Foundations/01-The-New-Paradigm-of-Agent-Programming.md b/en/Part-1-Foundations/01-The-New-Paradigm-of-Agent-Programming.md index 47d659c..b0fa807 100644 --- a/en/Part-1-Foundations/01-The-New-Paradigm-of-Agent-Programming.md +++ b/en/Part-1-Foundations/01-The-New-Paradigm-of-Agent-Programming.md @@ -22,16 +22,8 @@ In 2023, most developers interacted with LLMs like this: open a web page, enter This mode can be described with a simple model: -```mermaid -sequenceDiagram - participant Human Send - participant LLM - participant Human Receive - Human Send->>LLM: Prompt - LLM->>Human Receive: Response (Text) - Note over Human Receive,Human Send: Human copies, pastes, executes manually - Human Receive->>Human Send: Manually transport results -``` +![llm_human_interaction](../assets/fundamentals/llm_human_interaction.png) + The core limitation of this mode is that the LLM can only "speak," not "act." It cannot read your file system, execute test commands, create Git branches, or autonomously adjust its strategy when encountering errors. Every interaction with the outside world requires a human intermediary to manually complete -- copying code to the editor, switching to the terminal to run commands, and then copying the output back to the dialog box. This "human glue" pattern is not only inefficient but also error-prone. @@ -58,31 +50,7 @@ But tool calling also introduces new engineering challenges. These challenges ar These questions gave birth to a new architectural concept: **Agent Harness**. -```mermaid -flowchart TD - subgraph challenges["Six Engineering Challenges from Tool Calling"] - c1["Tool Registration & Discovery"] - c2["Parameter Validation"] - c3["Permission Control"] - c4["Error Recovery"] - c5["State Consistency"] - c6["Concurrency & Scheduling"] - end - - harness["Agent Harness
Unified Runtime Framework"] - - c1 --> harness - c2 --> harness - c3 --> harness - c4 --> harness - c5 --> harness - c6 --> harness - - classDef challenge fill:#fef9f0,stroke:#f59e0b,stroke-width:1px,color:#92400e - classDef center fill:#e8f4f8,stroke:#2196F3,stroke-width:2px,color:#1565C0 - class c1,c2,c3,c4,c5,c6 challenge - class harness center -``` +![Six Engineering Challenges](../assets/fundamentals/six_engineering_challenges.png) ### Why Agent Harness Instead of Simple Wrappers @@ -126,28 +94,7 @@ Before diving into design philosophy, let's first examine Claude Code's codebase Before analyzing Claude Code's architecture, let's widen our perspective and look at the evolution of AI programming tools. Understanding this timeline helps us see where Claude Code sits in the technological lineage: -```mermaid -flowchart TD - A["2021.06 GitHub Copilot Technical Preview
First LLM integration into editor"] --> - B["2022.12 ChatGPT Launch
Proves LLM's general conversational ability"] --> - C["2023.03 GPT-4 + Function Calling
LLM transforms from text generator to instruction orchestrator"] --> - D["2023.06 OpenAI Code Interpreter
LLM gains code execution capability for the first time"] --> - E["2023.11 Claude 2.1 + Tool Use
200K context window"] --> - F["2024.01 Devin Launch
First AI software engineer"] --> - G["2024.08 Cursor Agent Mode
Editor-integrated Agent"] --> - H["2024.10 Anthropic Computer Use
LLM can operate GUI"] --> - I["2025.02 Claude Code Launch
Terminal-native Agent"] --> - J["2025.11 Anthropic Publishes MCP
Standardized Agent communication protocol"] --> - K["2026.03 Source Code Accidentally Exposed
Community deeply examines Agent Harness"] --> - L["Now ← You are here"] - - classDef event fill:#f0f7ff,stroke:#3b82f6,stroke-width:1px,color:#1e3a5f - classDef milestone fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e40af - classDef current fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#92400e - class A,B,C,D,E,F,G,H event - class I,J,K milestone - class L current -``` +![AI Programming Tools Evolution Timeline](../assets/fundamentals/ai_programming_tools_evolution_timeline.png) This timeline reveals an important pattern: the direction of AI programming tool evolution has always been "giving LLMs more agency." From only being able to see the current file, to seeing the entire project; from only being able to generate suggestions, to being able to execute commands; from single-step operations to multi-step autonomous planning. Agent Harness is the inevitable architectural product of this evolutionary direction. @@ -161,35 +108,7 @@ But this does not mean the code is bloated. On the contrary, Claude Code's code Let's use an architectural overview diagram to visually illustrate Claude Code's module organization: -```mermaid -flowchart TD - entry["Entry Module
CLI Parsing · Startup Optimization · React/Ink Initialization"] - query["Query Engine
Session State Management · Message History · File Cache · Usage Statistics"] - loop["Dialog Main Loop (AsyncGenerator)
Preprocessing Pipeline → API Call → Tool Detection → State Construction"] - - subgraph loop_inner[" "] - direction LR - p1["Preprocessing Pipeline
Compression/Trimming"] --> p2["API Call
Streaming Reception"] --> p3["Tool Detection
Permission Check"] --> p4["State Construction
Message Backfill"] - end - - tools["Tool System
45+ Tools · Orchestration Engine · Concurrency Partitioning"] - perm["Permission Pipeline
Four-Stage Check · Five Modes · Rule Persistence"] - ext["Extension Layer
MCP Protocol · Sub-Agent Dispatch · Plugin System · Hook Mechanism"] - - entry --> query --> loop - loop --- loop_inner - loop --> tools - loop --> perm - perm -.->|Permission Constraints| tools - tools --> ext - - classDef module fill:#f0f7ff,stroke:#3b82f6,stroke-width:2px,color:#1e3a5f - classDef inner fill:#f8fafc,stroke:#93c5fd,stroke-width:1px,color:#475569 - classDef extmod fill:#fef9f0,stroke:#f59e0b,stroke-width:2px,color:#78350f - class entry,query,loop,module module - class p1,p2,p3,p4 inner - class tools,perm,ext extmod -``` +![Claude Code Architecture Overview](../assets/fundamentals/claude_code_architecture_overview.png) This diagram reveals the layered nature of Claude Code's architecture: from the user entry point at the top to the extension layer at the bottom, each layer has clear responsibilities and interface boundaries. The dialog main loop is the "heart" of the entire system, driving data flow between the various subsystems. diff --git a/en/Part-1-Foundations/02-The-Dialog-Loop-Heartbeat-of-an-Agent.md b/en/Part-1-Foundations/02-The-Dialog-Loop-Heartbeat-of-an-Agent.md index 1f62213..43776c2 100644 --- a/en/Part-1-Foundations/02-The-Dialog-Loop-Heartbeat-of-an-Agent.md +++ b/en/Part-1-Foundations/02-The-Dialog-Loop-Heartbeat-of-an-Agent.md @@ -21,36 +21,7 @@ This design choice deserves more space to fully understand. In traditional progr Faced with these requirements, the traditional function call model falls short. Async generators provide the perfect answer: they act like a "coroutine" that can be paused and resumed at any time, establishing a real-time event pipeline between the "producer" (the dialog loop) and the "consumer" (the UI rendering layer). -```mermaid -flowchart TD - subgraph layer1["Layer 1: Streaming Output"] - direction LR - e1["Event 1"] -->|"yield"| e2["Event 2"] -->|"yield"| e3["Event 3"] - end - - note1["UI renders each event immediately; user does not need to wait for completion"] - - subgraph layer2["Layer 2: Cancellability"] - cancel["Caller can invoke generator.return() at any time to terminate"] - clean["Triggers finally block for resource cleanup"] - scene2["Corresponding scenario: user presses Ctrl+C to interrupt"] - cancel --> clean --> scene2 - end - - subgraph layer3["Layer 3: Backpressure Control"] - bp["When consumer processing speed < producer speed, generator auto-pauses"] - mem["Prevents event accumulation leading to memory overflow"] - scene3["Corresponding scenario: tool execution produces large amounts of output"] - bp --> mem --> scene3 - end - - layer1 --- note1 - - classDef layer fill:#e8f4f8,stroke:#2196F3,stroke-width:2px,color:#1565C0 - classDef note fill:#f0fdf4,stroke:#22c55e,stroke-width:1px,color:#166534 - class layer1,layer2,layer3 layer - class note1 note -``` +![Async Generator Diagram](../assets/fundamentals/async_generator_diagram.png) ### Function Signature and the AsyncGenerator Pattern @@ -86,45 +57,7 @@ The events flowing through the dialog loop can be categorized as follows. Togeth Claude Code's messaging system defines clear role divisions. The core message types include: -```mermaid -classDiagram - class UserMessage { - +User input - +Carries tool execution results (tool_result) - } - class AssistantMessage { - +Text blocks - +Tool call blocks (tool_use) - } - class SystemMessage { - +System-level notifications - +Permission changes - +Model fallback prompts - } - class AttachmentMessage { - +File change notifications - +Memory file contents - +Task notifications - } - class ProgressMessage { - +Tool execution progress - +Bash output stream - +File read progress - } - class TombstoneMessage { - +Marks message as deprecated - +Triggered by streaming fallback - } - class ToolUseSummaryMessage { - +Tool call summary - +UI collapsed display - } - - UserMessage : API role is user - AssistantMessage : Can contain both text and tool calls - SystemMessage : Does not participate in API communication - TombstoneMessage : Marks message as "invalidated" -``` +![Message Type Diagram](../assets/fundamentals/message_type_diagram.png) - **UserMessage**: The user's input message, which also carries tool execution results (tool_result). From the API's perspective, tool results are always sent with the user role. This design may seem counterintuitive -- why are tool results in the "user" role? The reason is that at the API protocol level there are only three roles (system/user/assistant), and tool results need to be "seen" by the model, so they must be sent in the user role. This is a classic case of an engineering constraint driving a design decision. - **AssistantMessage**: The message returned by the model, which may contain text blocks and tool_use blocks. When the model detects that a tool needs to be called, the response will include a content block with `type: 'tool_use'`. A key characteristic of AssistantMessage is that it may simultaneously contain text and tool calls -- the model might first output an explanation ("Let me check your package.json file"), then append a tool call. This "talking while doing" pattern makes the Agent's behavior more transparent. @@ -142,36 +75,7 @@ Now let's follow a complete Turn -- from the user pressing the Enter key to the Using a medical analogy, a Turn is like a complete diagnostic process: the doctor (model) first reviews the medical record (context preprocessing), then communicates with the patient (API call), may need to order tests (tool calls), and after receiving the test results (tool execution), makes a diagnosis (final response). If the test results are insufficient for a diagnosis, the doctor orders more tests (next loop iteration). -```mermaid -flowchart TD - input["User Input: Help me fix this bug"] - - phase1["Phase 1: State Initialization
Destructure variables needed for current iteration from state object
Build new mutable state container"] - - phase2["Phase 2: Context Preprocessing (Seven-Step Pipeline)
1. Tool result budget -> 2. Snip compression -> 3. Microcompact
4. Context Collapse -> 5. System prompt assembly
6. Autocompact -> 7. Token block check"] - - phase3["Phase 3: API Call (Streaming Reception)
Send system prompt + message history + tool definitions
Receive streaming response events
Collect assistant messages and tool call blocks"] - - decision{"Tool calls?"} - - phase4["Phase 4: Tool Call Execution
Permission check · Concurrency partition scheduling
Streaming/batch execution · Instant progress output"] - - terminal["Termination Path
Check stop hooks · Check token budget
Return Terminal state"] - - phase5["Phase 5: Tool Result Backfill & Next Round
Attachment injection · Package new state object
continue back to Phase 1"] - - input --> phase1 --> phase2 --> phase3 --> decision - decision -->|Yes| phase4 --> phase5 - decision -->|No| terminal - phase5 -.->|Next iteration| phase1 - - classDef phase fill:#e8f4f8,stroke:#2196F3,stroke-width:2px,color:#1565C0 - classDef term fill:#fef2f2,stroke:#ef4444,stroke-width:2px,color:#991b1b - classDef dec fill:#fef9f0,stroke:#f59e0b,stroke-width:2px,color:#92400e - class input,phase1,phase2,phase3,phase4,phase5 phase - class terminal term - class decision dec -``` +![Dialog Loop Flow Diagram](../assets/fundamentals/dialog_loop_flow_diagram.png) ### Phase 1: State Initialization @@ -252,34 +156,7 @@ The dialog loop's termination occurs at multiple points, with each termination r These termination reasons can also be categorized into three groups: -```mermaid -flowchart TD - subgraph normal["Normal Termination"] - completed["completed
Agent completed the task"] - end - - subgraph user_stop["User-Initiated Termination"] - aborted_s["aborted_streaming
User Ctrl+C interrupt"] - aborted_t["aborted_tools
Interrupt during tool execution"] - end - - subgraph error["Abnormal Termination"] - max_turns["max_turns
Maximum loop count reached"] - blocking["blocking_limit
Token exceeds hard limit"] - too_long["prompt_too_long
Context too long and recovery failed"] - model_err["model_error
API call exception"] - stop_hook["stop_hook_prevented
Stop hook prevented"] - hook_stop["hook_stopped
Tool Hook prevented"] - img_err["image_error
Image size/format error"] - end - - classDef ok fill:#f0fdf4,stroke:#22c55e,stroke-width:2px,color:#166534 - classDef user fill:#fef9f0,stroke:#f59e0b,stroke-width:2px,color:#92400e - classDef err fill:#fef2f2,stroke:#ef4444,stroke-width:2px,color:#991b1b - class completed ok - class aborted_s,aborted_t user - class max_turns,blocking,too_long,model_err,stop_hook,hook_stop,img_err err -``` +![Termination Reason Categories](../assets/fundamentals/termination_reason_categories.png) - **Normal Termination**: `completed` -- the Agent completed the task - **User-Initiated Termination**: `aborted_streaming`, `aborted_tools` -- the user decided to stop @@ -341,35 +218,7 @@ The elegance of this three-element model (State + Continue + Terminal) lies in h The entire loop's state transitions can be summarized in the following state machine: -```mermaid -flowchart TD - init["Initialization"] --> preprocess["Preprocessing"] - preprocess --> api["API Call"] - api --> has_tool{"Tool calls?"} - - has_tool -->|No tools| no_tool["Termination check"] - has_tool -->|Has tools| yes_tool["Tool Execution"] - - no_tool --> done{"Terminal result"} - done -->|Complete| terminal1["Terminal: completed"] - done -->|Stop hook| terminal2["Terminal: stop_hook_prevented"] - done -->|Recovery| recovery_path["continue -> recovery"] - - yes_tool --> result["Result Backfill"] - result --> next_turn["continue -> next_turn"] - next_turn -.->|Next round| init - - recovery_path -.->|Retry| init - - classDef state fill:#e8f4f8,stroke:#2196F3,stroke-width:2px,color:#1565C0 - classDef decision fill:#fef9f0,stroke:#f59e0b,stroke-width:2px,color:#92400e - classDef terminal fill:#fef2f2,stroke:#ef4444,stroke-width:2px,color:#991b1b - classDef cont fill:#f0fdf4,stroke:#22c55e,stroke-width:2px,color:#166534 - class init,preprocess,api,no_tool,yes_tool,result state - class has_tool,done decision - class terminal1,terminal2 terminal - class next_turn,recovery_path cont -``` +![State Transition Diagram](../assets/fundamentals/state_transition_diagram.png) Key transition paths include: diff --git a/en/Part-1-Foundations/03-The-Tool-System-Agent-Hands.md b/en/Part-1-Foundations/03-The-Tool-System-Agent-Hands.md index 4f4d436..e15ac3e 100644 --- a/en/Part-1-Foundations/03-The-Tool-System-Agent-Hands.md +++ b/en/Part-1-Foundations/03-The-Tool-System-Agent-Hands.md @@ -263,50 +263,7 @@ This algorithm can be compared to an assembly line: imagine a factory with multi For example, if the model requests four tool calls: `[Read(a.ts), Read(b.ts), Bash(ls), Read(c.ts)]`, the partitioning result is: -```mermaid -flowchart LR - subgraph input["Input Sequence"] - direction LR - t1["Read(a.ts)
Safe=Yes"] ~~~ t2["Read(b.ts)
Safe=Yes"] ~~~ t3["Bash(ls)
Safe=No"] ~~~ t4["Read(c.ts)
Safe=Yes"] - end - - subgraph b1["Batch 1: Concurrency Safe = true -- Parallel Execution"] - direction LR - b1a["Read(a.ts)"] ~~~ b1b["Read(b.ts)"] - end - - subgraph b2["Batch 2: Concurrency Safe = false -- Serial Execution"] - b2a["Bash(ls)"] - end - - subgraph b3["Batch 3: Concurrency Safe = true -- Parallel Execution"] - b3a["Read(c.ts)"] - end - - input --> b1 --> b2 --> b3 - - classDef safe fill:#f0fdf4,stroke:#22c55e,stroke-width:2px,color:#166534 - classDef unsafe fill:#fef2f2,stroke:#ef4444,stroke-width:2px,color:#991b1b - class t1,t2,t4,b1,b1a,b1b,b3,b3a safe - class t3,b2,b2a unsafe -``` - -```mermaid -flowchart LR - subgraph timeline["Execution Timeline"] - direction LR - batch1["Batch 1: Read(a.ts) ‖ Read(b.ts)"] - batch2["Batch 2: Bash(ls)"] - batch3["Batch 3: Read(c.ts)"] - end - - batch1 --> batch2 --> batch3 - - note["Note: Batch 3 must wait for Batch 2 to complete
because Bash may have side effects"] - - classDef batch fill:#f0f7ff,stroke:#3b82f6,stroke-width:2px,color:#1e3a5f - class batch1,batch2,batch3 batch -``` +![Concurrency partitioning example showing tool call batching: Read operations grouped together for parallel execution, followed by Bash command in separate batch, then remaining read and edit operations](../assets/fundamentals/tool-partitioning-example.png) The concurrency limit for parallel execution is controlled by an environment variable, defaulting to 10. @@ -320,19 +277,7 @@ The impact of this design is significant. Suppose the model requests five tool c Each tracked tool has a four-stage state machine: -```mermaid -stateDiagram-v2 - [*] --> queued : Tool enqueued - queued --> executing : Execution conditions met - executing --> completed : Execution complete - completed --> yielded : Sequential turn to output - yielded --> [*] : Lifecycle ends - - note_right of queued : Waiting for execution conditions - note_right of executing : Check concurrency conditions
Start when no tools executing or all are concurrency-safe - note_right of completed : Waiting for sequential turn to output - note_right of yielded : Result has been yielded -``` +![Four-stage state machine of StreamingToolExecutor: queued → executing → completed → yielded](../assets/fundamentals/streaming-tool-executor-state-machine.png) - **queued**: The tool has been enqueued, waiting for execution conditions to be met. - **executing**: Currently executing. Before execution, concurrency conditions are checked: execution is allowed to start only when no tools are executing, or all executing tools are concurrency-safe. diff --git a/en/Part-2-Core-Systems/06-The-Memory-System-Agent-Long-Term-Memory.md b/en/Part-2-Core-Systems/06-The-Memory-System-Agent-Long-Term-Memory.md index 3966509..aeda271 100644 --- a/en/Part-2-Core-Systems/06-The-Memory-System-Agent-Long-Term-Memory.md +++ b/en/Part-2-Core-Systems/06-The-Memory-System-Agent-Long-Term-Memory.md @@ -128,9 +128,9 @@ how_to_use: When the user references external systems or needs to look up exter **Practical Application Scenarios:** -Scenario 1: Monitoring dashboards. The user says "the production Grafana dashboard is at https://grafana.company.com/d/abc123," and the Agent saves this as a reference memory. When the user asks "any anomalies recently," the Agent can remind the user to check this dashboard. +Scenario 1: Monitoring dashboards. The user says: "the production Grafana dashboard is at [https://grafana.company.com/d/abc123](https://grafana.company.com/d/abc123)." The Agent saves this as a reference memory. When the user asks, "any anomalies recently," the Agent can remind the user to check this dashboard. -Scenario 2: Documentation links. The user says "the API docs are on Confluence at https://confluence.company.com/pages/api-docs," and the Agent saves this as a reference memory. +Scenario 2: Documentation links. The user says: "the API docs are on Confluence at [https://confluence.company.com/pages/api-docs](https://confluence.company.com/pages/api-docs)." The Agent saves this as a reference memory. Scenario 3: Communication channels. The user says "backend team discussions are in the #backend-dev Slack channel," and the Agent saves this as a reference memory, reminding the user when cross-team coordination is needed. diff --git a/en/Part-3-Advanced-Patterns/10-The-Coordinator-Pattern-Multi-Agent-Orchestration.md b/en/Part-3-Advanced-Patterns/10-The-Coordinator-Pattern-Multi-Agent-Orchestration.md index 60466aa..e70ec01 100644 --- a/en/Part-3-Advanced-Patterns/10-The-Coordinator-Pattern-Multi-Agent-Orchestration.md +++ b/en/Part-3-Advanced-Patterns/10-The-Coordinator-Pattern-Multi-Agent-Orchestration.md @@ -396,15 +396,20 @@ The Coordinator system prompt defines a clear concurrency strategy: | Verification | Sometimes parallel with implementation | Safe when operating on different file regions | ```mermaid +--- +config: + gantt: + leftPadding: 180 +--- gantt title Concurrency Strategy Example (OAuth2 Integration Task) dateFormat X axisFormat %s section Research (All Parallel) - Worker A: API Analysis :a1, 0, 3 - Worker B: Database Analysis :a2, 0, 3 - Worker C: Auth Analysis :a3, 0, 3 + Worker A: API Analysis :a1, 0, 4 + Worker B: Database Analysis :a2, 0, 4 + Worker C: Auth Analysis :a3, 0, 4 section Implementation (Exclusive Files) Worker D: route/auth.ts :b1, 3, 6 diff --git a/en/assets/book_structure_overview.png b/en/assets/book_structure_overview.png new file mode 100644 index 0000000..f3ecca6 Binary files /dev/null and b/en/assets/book_structure_overview.png differ diff --git a/en/assets/fundamentals/ai_programming_tools_evolution_timeline.png b/en/assets/fundamentals/ai_programming_tools_evolution_timeline.png new file mode 100644 index 0000000..95edb0c Binary files /dev/null and b/en/assets/fundamentals/ai_programming_tools_evolution_timeline.png differ diff --git a/en/assets/fundamentals/async_generator_diagram.png b/en/assets/fundamentals/async_generator_diagram.png new file mode 100644 index 0000000..2987bc4 Binary files /dev/null and b/en/assets/fundamentals/async_generator_diagram.png differ diff --git a/en/assets/fundamentals/claude_code_architecture_overview.png b/en/assets/fundamentals/claude_code_architecture_overview.png new file mode 100644 index 0000000..6808b69 Binary files /dev/null and b/en/assets/fundamentals/claude_code_architecture_overview.png differ diff --git a/en/assets/fundamentals/dialog_loop_flow_diagram.png b/en/assets/fundamentals/dialog_loop_flow_diagram.png new file mode 100644 index 0000000..363c2d4 Binary files /dev/null and b/en/assets/fundamentals/dialog_loop_flow_diagram.png differ diff --git a/en/assets/fundamentals/llm_human_interaction.png b/en/assets/fundamentals/llm_human_interaction.png new file mode 100644 index 0000000..e1da5fa Binary files /dev/null and b/en/assets/fundamentals/llm_human_interaction.png differ diff --git a/en/assets/fundamentals/message_type_diagram.png b/en/assets/fundamentals/message_type_diagram.png new file mode 100644 index 0000000..a934f6d Binary files /dev/null and b/en/assets/fundamentals/message_type_diagram.png differ diff --git a/en/assets/fundamentals/six_engineering_challenges.png b/en/assets/fundamentals/six_engineering_challenges.png new file mode 100644 index 0000000..bdc447f Binary files /dev/null and b/en/assets/fundamentals/six_engineering_challenges.png differ diff --git a/en/assets/fundamentals/state_transition_diagram.png b/en/assets/fundamentals/state_transition_diagram.png new file mode 100644 index 0000000..b39ccc9 Binary files /dev/null and b/en/assets/fundamentals/state_transition_diagram.png differ diff --git a/en/assets/fundamentals/streaming-tool-executor-state-machine.png b/en/assets/fundamentals/streaming-tool-executor-state-machine.png new file mode 100644 index 0000000..33a802d Binary files /dev/null and b/en/assets/fundamentals/streaming-tool-executor-state-machine.png differ diff --git a/en/assets/fundamentals/termination_reason_categories.png b/en/assets/fundamentals/termination_reason_categories.png new file mode 100644 index 0000000..4296ad8 Binary files /dev/null and b/en/assets/fundamentals/termination_reason_categories.png differ diff --git a/en/assets/fundamentals/tool-partitioning-example.png b/en/assets/fundamentals/tool-partitioning-example.png new file mode 100644 index 0000000..b39ccc9 Binary files /dev/null and b/en/assets/fundamentals/tool-partitioning-example.png differ diff --git a/en/assets/render_evolution_graph.png b/en/assets/render_evolution_graph.png new file mode 100644 index 0000000..7ce327d Binary files /dev/null and b/en/assets/render_evolution_graph.png differ diff --git "a/\347\254\254\344\270\200\351\203\250\345\210\206-\345\237\272\347\241\200\347\257\207/01-\346\231\272\350\203\275\344\275\223\347\274\226\347\250\213\347\232\204\346\226\260\350\214\203\345\274\217.md" "b/\347\254\254\344\270\200\351\203\250\345\210\206-\345\237\272\347\241\200\347\257\207/01-\346\231\272\350\203\275\344\275\223\347\274\226\347\250\213\347\232\204\346\226\260\350\214\203\345\274\217.md" index d0e73a8..932bffd 100644 --- "a/\347\254\254\344\270\200\351\203\250\345\210\206-\345\237\272\347\241\200\347\257\207/01-\346\231\272\350\203\275\344\275\223\347\274\226\347\250\213\347\232\204\346\226\260\350\214\203\345\274\217.md" +++ "b/\347\254\254\344\270\200\351\203\250\345\210\206-\345\237\272\347\241\200\347\257\207/01-\346\231\272\350\203\275\344\275\223\347\274\226\347\250\213\347\232\204\346\226\260\350\214\203\345\274\217.md" @@ -22,16 +22,7 @@ 这种模式可以用一个简单的模型来描述： -```mermaid -sequenceDiagram - participant 人类发送 - participant LLM - participant 人类接收 - 人类发送->>LLM: Prompt - LLM->>人类接收: Response（文本） - Note over 人类接收,人类发送: 人类复制粘贴、手动执行 - 人类接收->>人类发送: 手动搬运结果 -``` +![基于大语言模型（LLM）的人机交互流程](../assets/fundamentals/llm_human_interaction.png) 这种模式的核心局限在于：LLM 只能"说话"，不能"做事"。它无法读取你的文件系统，无法执行测试命令，无法创建 Git 分支，更无法在遇到错误时自主调整策略。每一次与外部世界的交互，都需要人类作为中间人手动完成——复制代码到编辑器，切换到终端运行命令，再把输出结果复制回对话框。这种"人类胶水"的模式不仅低效，而且容易出错。 @@ -58,31 +49,7 @@ sequenceDiagram 这些问题催生了一个新的架构概念：**Agent Harness**。 -```mermaid -flowchart TD - subgraph challenges["工具调用带来的六大工程挑战"] - c1["工具注册与发现"] - c2["参数校验"] - c3["权限管控"] - c4["错误恢复"] - c5["状态一致性"] - c6["并发与调度"] - end - - harness["Agent Harness
统一的运行时框架"] - - c1 --> harness - c2 --> harness - c3 --> harness - c4 --> harness - c5 --> harness - c6 --> harness - - classDef challenge fill:#fef9f0,stroke:#f59e0b,stroke-width:1px,color:#92400e - classDef center fill:#e8f4f8,stroke:#2196F3,stroke-width:2px,color:#1565C0 - class c1,c2,c3,c4,c5,c6 challenge - class harness center -``` +![六大工程挑战](../assets/fundamentals/six_engineering_challenges.png) ### 为什么需要 Agent Harness 而非简单封装 @@ -126,28 +93,7 @@ flowchart TD 在分析 Claude Code 的架构之前，让我们把视野拉宽，看看 AI 编程工具的发展历程。理解这个时间线有助于我们看清 Claude Code 在技术谱系中的位置： -```mermaid -flowchart TD - A["2021.06 GitHub Copilot 技术预览
首次将 LLM 集成到编辑器"] --> - B["2022.12 ChatGPT 发布
证明 LLM 的通用对话能力"] --> - C["2023.03 GPT-4 + Function Calling
LLM 从文本生成器变为指令编排器"] --> - D["2023.06 OpenAI Code Interpreter
LLM 首次获得代码执行能力"] --> - E["2023.11 Claude 2.1 + Tool Use
200K 上下文窗口"] --> - F["2024.01 Devin 发布
第一个 AI 软件工程师"] --> - G["2024.08 Cursor Agent 模式
编辑器集成的 Agent"] --> - H["2024.10 Anthropic Computer Use
LLM 可以操作 GUI"] --> - I["2025.02 Claude Code 发布
终端原生 Agent"] --> - J["2025.11 Anthropic 发布 MCP
标准化 Agent 通信协议"] --> - K["2026.03 源码意外公开
社区深入审视 Agent Harness"] --> - L["现在 ← 你在这里"] - - classDef event fill:#f0f7ff,stroke:#3b82f6,stroke-width:1px,color:#1e3a5f - classDef milestone fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e40af - classDef current fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#92400e - class A,B,C,D,E,F,G,H event - class I,J,K milestone - class L current -``` +![AI 编程工具演进时间线](../assets/fundamentals/ai_programming_tools_evolution_timeline.png) 这个时间线揭示了一个重要规律：AI 编程工具的演进方向始终是"给 LLM 更多的行动能力"。从只能看到当前文件，到能看到整个项目；从只能生成建议，到能执行命令；从单步操作，到多步自主规划。Agent Harness 正是这个演进方向在架构层面的必然产物。 @@ -161,35 +107,7 @@ Claude Code 的 `src` 目录包含 1,884 个 TypeScript 文件，总计 512,664 让我们用一张架构全景图来直观展示 Claude Code 的模块组织： -```mermaid -flowchart TD - entry["入口模块 (Entry)
CLI 解析 · 启动优化 · React/Ink 初始化"] - query["查询引擎 (QueryEngine)
会话状态管理 · 消息历史 · 文件缓存 · 用量统计"] - loop["对话主循环 (AsyncGenerator)
预处理管线 → API 调用 → 工具检测 → 状态构建"] - - subgraph loop_inner[" "] - direction LR - p1["预处理管线
压缩/裁剪"] --> p2["API 调用
流式接收"] --> p3["工具检测
权限检查"] --> p4["状态构建
消息回填"] - end - - tools["工具系统
45+ 工具 · 编排引擎 · 并发分区"] - perm["权限管线
四阶段检查 · 五种模式 · 规则持久化"] - ext["扩展层
MCP 协议 · 子智能体调度 · 插件系统 · Hook 机制"] - - entry --> query --> loop - loop --- loop_inner - loop --> tools - loop --> perm - perm -.->|权限约束| tools - tools --> ext - - classDef module fill:#f0f7ff,stroke:#3b82f6,stroke-width:2px,color:#1e3a5f - classDef inner fill:#f8fafc,stroke:#93c5fd,stroke-width:1px,color:#475569 - classDef extmod fill:#fef9f0,stroke:#f59e0b,stroke-width:2px,color:#78350f - class entry,query,loop,module module - class p1,p2,p3,p4 inner - class tools,perm,ext extmod -``` +![Claude Code 架构全景图](../assets/fundamentals/claude_code_architecture_overview.png) 这张图揭示了 Claude Code 架构的层次性：从顶部的用户入口到底部的扩展层，每一层都有清晰的职责和接口边界。对话主循环是整个系统的"心脏"，它驱动着数据在各个子系统之间流转。 diff --git "a/\347\254\254\344\270\200\351\203\250\345\210\206-\345\237\272\347\241\200\347\257\207/02-\345\257\271\350\257\235\345\276\252\347\216\257-Agent\347\232\204\345\277\203\350\267\263.md" "b/\347\254\254\344\270\200\351\203\250\345\210\206-\345\237\272\347\241\200\347\257\207/02-\345\257\271\350\257\235\345\276\252\347\216\257-Agent\347\232\204\345\277\203\350\267\263.md" index 360f83a..869c74a 100644 --- "a/\347\254\254\344\270\200\351\203\250\345\210\206-\345\237\272\347\241\200\347\257\207/02-\345\257\271\350\257\235\345\276\252\347\216\257-Agent\347\232\204\345\277\203\350\267\263.md" +++ "b/\347\254\254\344\270\200\351\203\250\345\210\206-\345\237\272\347\241\200\347\257\207/02-\345\257\271\350\257\235\345\276\252\347\216\257-Agent\347\232\204\345\277\203\350\267\263.md" @@ -21,36 +21,7 @@ Claude Code 的对话主循环是一个以 `async function*` 定义的异步生 面对这些需求，传统的函数调用模型力不从心。异步生成器提供了完美的答案：它像一个可以随时暂停和恢复的"协程"，在"生产者"（对话循环）和"消费者"（UI 渲染层）之间建立了一条实时的事件管道。 -```mermaid -flowchart TD - subgraph layer1["第一层：流式输出"] - direction LR - e1["事件1"] -->|"yield"| e2["事件2"] -->|"yield"| e3["事件3"] - end - - note1["UI 即时渲染每个事件，用户无需等待全部完成"] - - subgraph layer2["第二层：可取消性"] - cancel["调用者可随时调用 generator.return() 终止"] - clean["触发 finally 块执行资源清理"] - scene2["对应场景：用户按 Ctrl+C 中断操作"] - cancel --> clean --> scene2 - end - - subgraph layer3["第三层：背压控制"] - bp["消费者处理速度 < 生产速度时，生成器自动暂停"] - mem["避免事件堆积导致内存溢出"] - scene3["对应场景：工具执行产生大量输出时"] - bp --> mem --> scene3 - end - - layer1 --- note1 - - classDef layer fill:#e8f4f8,stroke:#2196F3,stroke-width:2px,color:#1565C0 - classDef note fill:#f0fdf4,stroke:#22c55e,stroke-width:1px,color:#166534 - class layer1,layer2,layer3 layer - class note1 note -``` +![异步生成器的生产者-消费者模型示意图](../assets/fundamentals/async_generator_diagram.png) ### 函数签名与 AsyncGenerator 模式 @@ -86,45 +57,7 @@ flowchart TD Claude Code 的消息系统定义了清晰的角色分工。核心消息类型包括： -```mermaid -classDiagram - class UserMessage { - +用户输入 - +承载工具执行结果(tool_result) - } - class AssistantMessage { - +文本块 - +工具调用块(tool_use) - } - class SystemMessage { - +系统级通知 - +权限变更 - +模型回退提示 - } - class AttachmentMessage { - +文件变更通知 - +内存文件内容 - +任务通知 - } - class ProgressMessage { - +工具执行进度 - +Bash 输出流 - +文件读取进度 - } - class TombstoneMessage { - +标记消息废弃 - +流式回退触发 - } - class ToolUseSummaryMessage { - +工具调用摘要 - +UI 折叠展示 - } - - UserMessage : API 角色为 user - AssistantMessage : 可同时包含文本和工具调用 - SystemMessage : 不参与 API 通信 - TombstoneMessage : 标记消息"失效" -``` +![消息类型体系图](../assets/fundamentals/message_types_diagram.png) - **UserMessage**：用户的输入消息，也承载工具执行结果（tool_result）。在 API 的视角里，工具结果总是以 user 角色发送。这个设计可能看起来违反直觉——为什么工具结果是"user"角色？原因是 API 协议层面只有三种角色（system/user/assistant），工具结果需要被模型"看到"，所以必须以 user 角色发送。这是一个工程约束驱动设计决策的典型案例。 - **AssistantMessage**：模型返回的消息，可能包含文本块和 tool_use 块。当模型检测到需要调用工具时，响应中会包含 `type: 'tool_use'` 的内容块。AssistantMessage 的关键特性是它可能同时包含文本和工具调用——模型可能先输出一段解释（"我需要查看你的文件"），然后附加一个工具调用。这种"边说边做"的模式让 Agent 的行为更加透明。 @@ -142,36 +75,7 @@ classDiagram 用医学来类比，一个 Turn 就像一次完整的诊断过程：医生（模型）先查看病历（上下文预处理），然后与病人交流（API 调用），可能需要安排检查（工具调用），拿到检查结果后（工具执行）做出诊断（最终回复）。如果检查结果不足以确诊，医生会安排更多检查（下一轮循环）。 -```mermaid -flowchart TD - input["用户输入: 帮我修复这个 bug"] - - phase1["阶段一：状态初始化
从状态对象解构当前迭代所需的变量
构建新的可变状态容器"] - - phase2["阶段二：上下文预处理（七步管线）
① 工具结果预算 → ② Snip压缩 → ③ Microcompact
④ Context Collapse → ⑤ 系统提示组装
⑥ Autocompact → ⑦ Token阻断检查"] - - phase3["阶段三：API 调用（流式接收）
发送系统提示 + 消息历史 + 工具定义
流式接收响应事件
收集 assistant 消息和工具调用块"] - - decision{"有工具调用？"} - - phase4["阶段四：工具调用执行
权限检查 · 并发分区调度
流式/批量执行 · 进度即时产出"] - - terminal["终止路径
检查 stop hooks · 检查 token 预算
返回 Terminal 状态"] - - phase5["阶段五：工具结果回填与下一轮
附件注入 · 打包新状态对象
continue 回到阶段一"] - - input --> phase1 --> phase2 --> phase3 --> decision - decision -->|是| phase4 --> phase5 - decision -->|否| terminal - phase5 -.->|下一轮迭代| phase1 - - classDef phase fill:#e8f4f8,stroke:#2196F3,stroke-width:2px,color:#1565C0 - classDef term fill:#fef2f2,stroke:#ef4444,stroke-width:2px,color:#991b1b - classDef dec fill:#fef9f0,stroke:#f59e0b,stroke-width:2px,color:#92400e - class input,phase1,phase2,phase3,phase4,phase5 phase - class terminal term - class decision dec -``` +![对话循环的 Turn 生命周期示意图](../assets/fundamentals/turn_lifecycle_diagram.png) ### 阶段一：状态初始化 @@ -252,34 +156,7 @@ flowchart TD 这些终止原因还可以分为三类： -```mermaid -flowchart TD - subgraph normal["正常终止"] - completed["completed
Agent 完成了任务"] - end - - subgraph user_stop["用户主动终止"] - aborted_s["aborted_streaming
用户 Ctrl+C 中断"] - aborted_t["aborted_tools
工具执行期间中断"] - end - - subgraph error["异常终止"] - max_turns["max_turns
达到最大循环次数"] - blocking["blocking_limit
Token 超过硬性限制"] - too_long["prompt_too_long
上下文过长且恢复失败"] - model_err["model_error
API 调用异常"] - stop_hook["stop_hook_prevented
Stop hook 阻止"] - hook_stop["hook_stopped
工具 Hook 阻止"] - img_err["image_error
图片尺寸/格式错误"] - end - - classDef ok fill:#f0fdf4,stroke:#22c55e,stroke-width:2px,color:#166534 - classDef user fill:#fef9f0,stroke:#f59e0b,stroke-width:2px,color:#92400e - classDef err fill:#fef2f2,stroke:#ef4444,stroke-width:2px,color:#991b1b - class completed ok - class aborted_s,aborted_t user - class max_turns,blocking,too_long,model_err,stop_hook,hook_stop,img_err err -``` +![终止原因分类图](../assets/fundamentals/termination_reasons_diagram.png) - **正常终止**：`completed`——Agent 完成了任务 - **用户主动终止**：`aborted_streaming`、`aborted_tools`——用户决定停止 @@ -341,35 +218,7 @@ Terminal 和 Continue 类型定义在独立的模块中。Terminal 标记对话 整个循环的状态转换可以归纳为以下状态机： -```mermaid -flowchart TD - init["初始化"] --> preprocess["预处理"] - preprocess --> api["API调用"] - api --> has_tool{"工具调用?"} - - has_tool -->|无工具| no_tool["终止检查"] - has_tool -->|有工具| yes_tool["工具执行"] - - no_tool --> done{"终止结果"} - done -->|完成| terminal1["Terminal: completed"] - done -->|stop hook| terminal2["Terminal: stop_hook_prevented"] - done -->|recovery| recovery_path["continue → recovery"] - - yes_tool --> result["结果回填"] - result --> next_turn["continue → next_turn"] - next_turn -.->|下一轮| init - - recovery_path -.->|重试| init - - classDef state fill:#e8f4f8,stroke:#2196F3,stroke-width:2px,color:#1565C0 - classDef decision fill:#fef9f0,stroke:#f59e0b,stroke-width:2px,color:#92400e - classDef terminal fill:#fef2f2,stroke:#ef4444,stroke-width:2px,color:#991b1b - classDef cont fill:#f0fdf4,stroke:#22c55e,stroke-width:2px,color:#166534 - class init,preprocess,api,no_tool,yes_tool,result state - class has_tool,done decision - class terminal1,terminal2 terminal - class next_turn,recovery_path cont -``` +![状态转换模型图](../assets/fundamentals/state_transition_diagram.jpeg) 关键的转换路径包括： diff --git "a/\347\254\254\344\270\200\351\203\250\345\210\206-\345\237\272\347\241\200\347\257\207/03-\345\267\245\345\205\267\347\263\273\347\273\237-Agent\347\232\204\345\217\214\346\211\213.md" "b/\347\254\254\344\270\200\351\203\250\345\210\206-\345\237\272\347\241\200\347\257\207/03-\345\267\245\345\205\267\347\263\273\347\273\237-Agent\347\232\204\345\217\214\346\211\213.md" index 71ffa3f..fd51b53 100644 --- "a/\347\254\254\344\270\200\351\203\250\345\210\206-\345\237\272\347\241\200\347\257\207/03-\345\267\245\345\205\267\347\263\273\347\273\237-Agent\347\232\204\345\217\214\346\211\213.md" +++ "b/\347\254\254\344\270\200\351\203\250\345\210\206-\345\237\272\347\241\200\347\257\207/03-\345\267\245\345\205\267\347\263\273\347\273\237-Agent\347\232\204\345\217\214\346\211\213.md" @@ -263,50 +263,7 @@ AgentTool 在工具系统中有几个特殊属性： 举例来说，如果模型请求了四个工具调用：`[Read(a.ts), Read(b.ts), Bash(ls), Read(c.ts)]`，分区结果为： -```mermaid -flowchart LR - subgraph input["输入序列"] - direction LR - t1["Read(a.ts)
安全=是"] ~~~ t2["Read(b.ts)
安全=是"] ~~~ t3["Bash(ls)
安全=否"] ~~~ t4["Read(c.ts)
安全=是"] - end - - subgraph b1["Batch 1: 并发安全 = true — 并行执行"] - direction LR - b1a["Read(a.ts)"] ~~~ b1b["Read(b.ts)"] - end - - subgraph b2["Batch 2: 并发安全 = false — 串行执行"] - b2a["Bash(ls)"] - end - - subgraph b3["Batch 3: 并发安全 = true — 并行执行"] - b3a["Read(c.ts)"] - end - - input --> b1 --> b2 --> b3 - - classDef safe fill:#f0fdf4,stroke:#22c55e,stroke-width:2px,color:#166534 - classDef unsafe fill:#fef2f2,stroke:#ef4444,stroke-width:2px,color:#991b1b - class t1,t2,t4,b1,b1a,b1b,b3,b3a safe - class t3,b2,b2a unsafe -``` - -```mermaid -flowchart LR - subgraph timeline["执行时间线"] - direction LR - batch1["Batch 1: Read(a.ts) ‖ Read(b.ts)"] - batch2["Batch 2: Bash(ls)"] - batch3["Batch 3: Read(c.ts)"] - end - - batch1 --> batch2 --> batch3 - - note["注意：Batch 3 必须等 Batch 2 完成
因为 Bash 可能有副作用"] - - classDef batch fill:#f0f7ff,stroke:#3b82f6,stroke-width:2px,color:#1e3a5f - class batch1,batch2,batch3 batch -``` +![工具调用并发分区示例：Read和Read可并行，Bash中断其他操作，后续Read需串行](../assets/fundamentals/tools_partition_example.png) 并发执行的并发度上限由环境变量控制，默认为 10。 @@ -320,19 +277,7 @@ flowchart LR 每个被追踪的工具拥有四阶段状态机： -```mermaid -stateDiagram-v2 - [*] --> queued : 工具入队 - queued --> executing : 执行条件满足 - executing --> completed : 执行完成 - completed --> yielded : 顺序轮到输出 - yielded --> [*] : 生命周期结束 - - note_right of queued : 等待执行条件满足 - note_right of executing : 检查并发条件
无工具在执行或全部并发安全时启动 - note_right of completed : 等待顺序轮到输出 - note_right of yielded : 结果已产出 -``` +![工具状态机示例：queued → executing → completed → yielded](../assets/fundamentals/tools_state_machine.png) - **queued**：工具已入队，等待执行条件满足。 - **executing**：正在执行。执行前会检查并发条件：只有当没有工具在执行，或所有执行中的工具都是并发安全时，才允许开始执行。 diff --git "a/\347\254\254\344\270\211\351\203\250\345\210\206-\351\253\230\347\272\247\346\250\241\345\274\217\347\257\207/10-\345\215\217\350\260\203\345\231\250\346\250\241\345\274\217-\345\244\232\346\231\272\350\203\275\344\275\223\347\274\226\346\216\222.md" "b/\347\254\254\344\270\211\351\203\250\345\210\206-\351\253\230\347\272\247\346\250\241\345\274\217\347\257\207/10-\345\215\217\350\260\203\345\231\250\346\250\241\345\274\217-\345\244\232\346\231\272\350\203\275\344\275\223\347\274\226\346\216\222.md" index 585b390..0ce3b94 100644 --- "a/\347\254\254\344\270\211\351\203\250\345\210\206-\351\253\230\347\272\247\346\250\241\345\274\217\347\257\207/10-\345\215\217\350\260\203\345\231\250\346\250\241\345\274\217-\345\244\232\346\231\272\350\203\275\344\275\223\347\274\226\346\216\222.md" +++ "b/\347\254\254\344\270\211\351\203\250\345\210\206-\351\253\230\347\272\247\346\250\241\345\274\217\347\257\207/10-\345\215\217\350\260\203\345\231\250\346\250\241\345\274\217-\345\244\232\346\231\272\350\203\275\344\275\223\347\274\226\346\216\222.md" @@ -396,23 +396,28 @@ Coordinator 系统提示定义了清晰的并发策略： | 验证 | 有时可与实施并行 | 在不同文件区域操作时安全 | ```mermaid +--- +config: + gantt: + leftPadding: 150 +--- gantt - title 并发策略示例（OAuth2 集成任务） + title 并发策略示例 (OAuth2 集成任务) dateFormat X axisFormat %s - section Research（全部并行） - Worker A: API 分析 :a1, 0, 3 - Worker B: 数据库分析 :a2, 0, 3 - Worker C: Auth 分析 :a3, 0, 3 + section Research (全部并行) + Worker A (API 分析) :a1, 0, 4 + Worker B (数据库分析) :a2, 0, 4 + Worker C (Auth 分析) :a3, 0, 4 - section Implementation（独占文件） - Worker D: route/auth.ts :b1, 3, 6 - Worker E: db/migration.ts :b2, 6, 9 + section Implementation (独占文件) + Worker D (route/auth.ts) :b1, 3, 6 + Worker E (db/migration.ts) :b2, 6, 9 - section Verification（并行验证） - Worker F: 测试 auth :c1, 9, 12 - Worker G: 测试 DB :c2, 9, 12 + section Verification (并行验证) + Worker F (测试 auth) :c1, 9, 12 + Worker G (测试 DB) :c2, 9, 12 ``` 系统提示还鼓励协调者"fan out"——在一次消息中发起多个并行工作者调用。这利用了 Claude 的并行工具调用能力，让多个工作者同时启动。 diff --git "a/\347\254\254\344\272\214\351\203\250\345\210\206-\346\240\270\345\277\203\347\263\273\347\273\237\347\257\207/06-\350\256\260\345\277\206\347\263\273\347\273\237-Agent\347\232\204\351\225\277\346\234\237\350\256\260\345\277\206.md" "b/\347\254\254\344\272\214\351\203\250\345\210\206-\346\240\270\345\277\203\347\263\273\347\273\237\347\257\207/06-\350\256\260\345\277\206\347\263\273\347\273\237-Agent\347\232\204\351\225\277\346\234\237\350\256\260\345\277\206.md" index 717eef3..a3c2178 100644 --- "a/\347\254\254\344\272\214\351\203\250\345\210\206-\346\240\270\345\277\203\347\263\273\347\273\237\347\257\207/06-\350\256\260\345\277\206\347\263\273\347\273\237-Agent\347\232\204\351\225\277\346\234\237\350\256\260\345\277\206.md" +++ "b/\347\254\254\344\272\214\351\203\250\345\210\206-\346\240\270\345\277\203\347\263\273\347\273\237\347\257\207/06-\350\256\260\345\277\206\347\263\273\347\273\237-Agent\347\232\204\351\225\277\346\234\237\350\256\260\345\277\206.md" @@ -128,9 +128,9 @@ how_to_use: 当用户引用外部系统或需要查找外部信息时 **实际应用场景：** -场景一：监控仪表盘。用户说"生产环境的 Grafana 仪表盘在 https://grafana.company.com/d/abc123"，Agent 保存为 reference 记忆。当用户问"最近有什么异常"时，Agent 能提醒用户查看这个仪表盘。 +场景一：监控仪表盘。用户说：“生产环境的 Grafana 仪表盘在 [https://grafana.company.com/d/abc123](https://grafana.company.com/d/abc123)”，Agent 保存为 reference 记忆。当用户问：“最近有什么异常”时，Agent 能提醒用户查看这个仪表盘。 -场景二：文档链接。用户说"API 文档在 Confluence 的 https://confluence.company.com/pages/api-docs"，Agent 保存为 reference 记忆。 +场景二：文档链接。用户说：“API 文档在 Confluence 的 [https://confluence.company.com/pages/api-docs](https://confluence.company.com/pages/api-docs)”，Agent 保存为 reference 记忆。 场景三：通信渠道。用户说"后端团队的讨论在 #backend-dev Slack 频道"，Agent 保存为 reference 记忆，在需要跨团队协调时提醒用户。