learn-claude-code-rs
wulawulu/learn-claude-code-rs加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
深夜，一个 Rust 爱好者盯着屏幕，手指悬在键盘上。Claude Code 的回复精准优雅——但她想知道：这个 Agent 是怎么做出来的？
大多数 LLM 教程止步于"调用 API 返回文字"。这个项目不一样。它从最小的 agent loop 开始，像搭积木一样，逐步加入工具调用、任务规划、子代理、记忆系统、权限控制、MCP 插件……最终收敛成一个完整的 Agent 运行时（Agent Harness）。
这不是调 API，这是在造一个会思考的工具。
Coding Agent 领域这几年飞速发展。从最初的 ChatGPT 插件，到 Claude Code、Cursor Agent、Devin，每一个产品背后都有一套相似的工程架构：Agent Runtime。
所谓"Agent Runtime"，就是围绕语言模型的那一圈工程：如何让模型调用工具？如何管理记忆？如何做权限控制？如何让多个 Agent 协作？这些问题不解决，Agent 就只是一个"会说话的 API"。
learn-claude-code-rs 的作者 wulawulu 就是想做这件事——用 Rust 语言，从零手写一个完整的 Agent Runtime。它受到 shareAI-lab/learn-claude-code 启发，但针对 Rust 生态做了完整重设计。
项目于 2026 年 4 月上线 GitHub，8 个月内获得 124 颗星，21 个 Fork，主题覆盖 agentic、coding-agent、multi-agent 等 14 个领域标签。Rust 语言本身在工程可靠性和并发性能上的优势，让这个实现特别值得关注。
项目最独特的设计是 20 个独立章节，每章一个可运行的 Rust crate。它们不是文档，是代码——你 clone 下来就能跑，跑完就能改。
这张架构图展示了完整 Agent 的内部结构。从下往上看：LLM 客户端在最底层，之上是工具路由层，左边是各个 Manager（Memory、Task、Team、Hook 等），最顶层是 MCP 插件系统和 CLI 交互层。
1. Agent Loop（s01_agent_loop）
一切从最简单的循环开始：读取输入 → 调用模型 → 处理响应 → 回到开头。这一章的代码量很少，但定义了后续所有章节的基础数据结构。
2. 工具系统（s02_tool_use）
把工具抽象成统一 trait。引入了 read_file、write_file、edit_file、bash 等核心工具。核心是 Tool trait，所有工具都要实现 execute 方法。
3. 子代理（s04_subagent）
主 Agent 可以创建子 Agent 来完成特定任务。子 Agent 有独立的上下文，完成后返回总结给主 Agent。这是复杂任务分解的基础。
4. 上下文压缩（s06_context_compact）
当对话历史变长，上下文窗口会被撑爆。compact 工具会在达到阈值时自动压缩历史，保留关键信息同时节省 token。这是生产级 Agent 的必备能力。
5. 权限系统（s07_permission_system）
Agent 能执行危险操作（删除文件、执行命令）——权限系统决定哪些能做、哪些不能。支持三种模式：Default（手动确认）、Plan（规划模式）、Auto（完全自动）。
6. Hook 系统（s08_hook_system）
在工具执行前后插入自定义逻辑。典型用途：日志记录、token 计数、安全审计。
7. 记忆系统（s09_memory_system）
memory 工具让 Agent 可以持久化关键信息，在多轮对话中记住之前学到的事实。这是真正"智能"的基础设施。
8. MCP 插件（s19_mcp_plugin）
MCP（Model Context Protocol）是一种插件标准，让外部工具可以无缝接入 Agent。这里通过扫描 .claude-plugin/plugin.json 自动连接 MCP Server。
9. Worktree 隔离（s18_worktree_task_isolation）
用 Git Worktree 技术隔离不同任务的工作目录，防止子 Agent 之间互相干扰。这是多任务并行的安全保障。
s01 到 s20 每章独立，但最终所有章节收敛到 sfull ——一个完整的 Agent Runtime。
运行方式：
cargo run -p sfull
启动时会让你选择权限模式：
Default → 每条命令手动确认
Plan → 规划模式，批量执行
Auto → 完全自动，无需确认
主循环的核心流程：
micro compact → 检查上下文是否超限，自动压缩
构造 system prompt → 根据历史构建动态 prompt
调用 LLM → 发请求给模型
权限检查 → 每条工具调用前过一遍权限
hook 执行 → 前后拦截，可注入日志/计数
工具执行 → ToolRouter 派发到对应工具
核心结构 Agent 如下：
pub struct Agent {
pub runtime: AgentRuntime, // LLM 客户端、上下文、compact
pub tool_context: ToolContext, // 工具可访问的业务依赖
pub tools: ToolRouter, // 本地工具注册和调用
pub mcp_router: MCPToolRouter, // MCP 外部工具
pub hooks: Vec<Hook>, // 拦截器
pub system_prompt: AgentSystemPrompt,
}
| 维度 | 技术选型 |
|---|---|
| 主力语言 | Rust（workspace 20+ crate） |
| LLM 接口 | Anthropic Messages API 兼容 |
| 异步运行时 | Tokio（rt-multi-thread, macros） |
| 序列化 | Serde（JSON/YAML） |
| 模板引擎 | Tera（system prompt 渲染） |
| 依赖注入 | 手动 ToolContext 结构体注入 |
| 代码生成 | derive_builder、async-trait、syn/quote/proc-macro2 |
| 持久化 | fs4（文件锁 + 持久化 Store） |
| 定时任务 | cron crate |
| 工具宏 | s20_tool_refactor_macros（手写过程宏简化工具定义） |
AI Framework: Anthropic SDK（anthropic-ai-sdk = "0.2.27"），支持任意兼容 Anthropic Messages API 的服务商。README 中明确给出了 DeepSeek、智谱 GLM、阿里百炼、Kimi、MiniMax 等国产模型的配置示例。
项目工程规范相当严格：
deny.toml: 依赖安全审计（cargo-deny）cliff.toml: 规范化 commit message（Conventional Commits + cliff工具）.pre-commit-config.yaml: pre-commit hooks（typos 检查等）_typos.toml: 拼写检查配置ci.yml）整个 workspace 使用 Rust 2024 edition，属于较早采用前沿标准的项目。deny.toml 长达 11KB，说明作者对依赖安全和许可证合规非常重视。
部署方式：纯 CLI，无 Docker，无 Web UI。
上手步骤：
rustup update）.env.example 为 .env，填入 ANTHROPIC_API_KEYcargo run -p sfull硬件需求：无 GPU 要求，标准开发机即可（建议 4GB+ 内存）。
配置灵活性：API 地址和模型名完全可替换，支持 DeepSeek、智谱、阿里通义、Kimi、MiniMax 等国产服务商。
部署难度：困难。门槛是 Rust 语言基础 + LLM API 配置，适合有系统编程经验的开发者。
learn-claude-code-rs 填补了一个空白：用 Rust 构建 AI Agent 的系统性教程。之前大部分 Agent 教程都是 Python/JavaScript，这个项目证明了 Rust 在这个领域的可行性。
Rust 的类型安全（无 GC、内存安全、并发无忧）和 AI Agent 的确定性执行需求高度契合。更重要的是，通过 workspace 管理 20+ 个独立 crate 的设计，让学习者可以按需切入——不需要从第一章读到最后，可以直接跳到感兴趣的主题目录运行代码。
124 颗星在教育型项目中属于正常水平，但考虑到这是 Rust 生态（社区相对 Python 更小），而且是纯技术教程（非产品/工具），这个增长速度反映了 Rust 开发者对 AI Agent 工程知识的强烈需求。