概述

用 Rust 构建 Coding Agent — 动手实践教程，在 mini-claw-code-starter 模板里从零搭建自己的 AI coding agent，架构参考 Claude Code。

想找最初的 V1 教程？已归档至 archive/v1-book/en/（中文版见 archive/v1-book/zh/）。

你将构建什么

读完本书，你就有了一个完整的 coding agent，能做到：

• 连接 LLM，通过兼容 OpenAI 的 HTTP provider
• 调用工具：bash、文件读/写/编辑，统一用 Tool trait 封装
• 自主循环：SimpleAgent 驱动 provider-工具循环，直到任务完成
• 流式推送事件，通过 channel 让 UI 实时展示进度
• 确定性测试，用 MockProvider 返回预设响应，无需真实 API
• 安全策略：权限引擎、安全检查、hook 三重保障
• 加载项目说明，从 CLAUDE.md 和分层配置中读取

架构

starter 代码库采用扁平模块结构：

mini-claw-code-starter/src/
  types.rs          -- Messages, tools, ToolSet, Provider trait, TokenUsage
  agent.rs          -- SimpleAgent (the core agent loop) and AgentEvent
  mock.rs           -- MockProvider for deterministic testing
  streaming.rs      -- SSE parsing, StreamAccumulator
  instructions.rs   -- InstructionLoader (CLAUDE.md discovery)
  permissions.rs    -- PermissionEngine
  safety.rs         -- SafetyChecker, SafeToolWrapper
  hooks.rs          -- Hook trait, HookRegistry
  planning.rs       -- PlanAgent (two-phase plan/execute)
  config.rs         -- Config, ConfigLoader, CostTracker
  context.rs        -- SystemPromptBuilder
  providers/
    openrouter.rs   -- OpenRouterProvider (real HTTP backend)
  tools/            -- Tool implementations (bash, file read/write/edit)

怎么用这本书

先看第 1–3 章。 三章短小精悍，不到一小时就能从零跑起一个 agent：

1. 第一次 LLM 调用 — 实现 MockProvider（test_mock_）
2. 第一次工具调用 — 实现 ReadTool（test_read_）
3. Agentic 循环 — 实现 single_turn 和 SimpleAgent（test_single_turn_、test_simple_agent_）

之后继续第 4–18 章，深入完整架构：流式、权限、hook、计划模式、配置等。

mini-claw-code-starter crate 里的 stub 实现带有 unimplemented!() 占位和说明注释，告诉你该做什么。读完章节，填好 stub，跑测试验证。

跑测试检查进度：

# 跑某章的测试（用下表对应的测试名称）
cargo test -p mini-claw-code-starter test_mock_

# 跑所有测试
cargo test -p mini-claw-code-starter

前置条件

• Rust（edition 2024，1.85+）
• 了解 async Rust 基础（async/await、tokio）
• OpenRouter API key（实时 provider 章节需要）

章节路线图

入门

第一部分：核心 Agent

第二部分：Prompt 与工具

第三部分：安全与控制

第四部分：配置

附加内容（暂无章节，stub 与测试已就绪）

开始构建。