从一个最小 Agent 出发，逐步构建可运行、可扩展的 AI 编程代理
Important
本仓库是掘金小册《深入 Claude Code 源码：从架构到实践，构建你自己的 AI 编程代理》的配套源码。仓库侧重提供可运行的最终实现，小册则完整讲解每一步为什么这样设计、如何动手实现，以及如何调试和验证。两者内容会随更新存在差异，建议以小册为学习主线，以本仓库作为实践和查阅材料。
直接阅读完成后的源码，你能看到“答案”；跟着小册学习，你会掌握从需求拆解、架构取舍到工程落地的完整过程。
- 从底层原理开始：不依赖 Agent 框架，从 Agent Loop、Tool Calling 和流式执行开始搭建核心引擎。
- 覆盖完整工程能力：系统学习上下文压缩、会话记忆、权限、Hooks、MCP、Skills、成本追踪与多代理协作。
- 以真实项目贯穿：通过 MiniAgent、MCP Server 和多代理 Review，把概念转化为可以运行和扩展的代码。
- 不仅告诉你怎么写：结合 Claude Code 的架构与源码设计，解释关键方案的适用场景、权衡与演进路径。
如果你正在学习 AI Agent、准备开发自己的编程助手，或者希望真正理解 Claude Code 这类产品如何工作，这本小册可以帮你建立一套完整、可复用的工程认知。
| 项目 | 你会得到什么 | 对应章节 | API Key |
|---|---|---|---|
mini-agent/ |
最小可用 Code Agent：文件读写、命令执行、搜索、上下文与权限 | 2–6、11 | 对话需要；测试不需要 |
mini-agent-full/ |
完整整合版：记忆、MagicDocs、Hooks、MCP、Skills、工程化与离线 Eval | 5、7–19 | 对话需要；测试不需要 |
project-analyzer-mcp/ |
MCP Server：项目结构、依赖和复杂度分析 | 13–15 | 不需要 |
multi-agent-review/ |
多代理代码审查：Coordinator + Security / Performance / Style Worker | 17–18 | 真实审查需要；测试不需要 |
- 正在跟着小册动手实现：从
mini-agent/开始。它刻意只保留单代理核心，便于逐章添加能力。 - 想查看完整实现或对照答案：阅读
mini-agent-full/。它整合了各章教学实现，并说明了与正文存在差异的地方。 - 想专项学习 MCP 或多代理：直接进入
project-analyzer-mcp/或multi-agent-review/。
- 阅读小册中的 Agent Loop 与工具系统章节，同时运行
mini-agent/。 - 逐步加入上下文、权限、记忆、Hooks 和 Skills，并与
mini-agent-full/对照。 - 使用
project-analyzer-mcp/理解 MCP 的 Tools、Resources 与 Prompts。 - 使用
multi-agent-review/掌握 Coordinator、Worker、任务调度与结果聚合。
Tip
建议先自己实现，再查看完整版本。遇到卡点时，用测试和 mini-agent-full/ 定位差异，学习效果会比直接复制代码更好。
- Node.js 20+
- npm 10+
- Anthropic API Key（仅真实对话需要）
git clone https://github.com/jiji262/mini-code-agent.git
cd mini-code-agent/mini-agent
npm ci
npm run buildexport ANTHROPIC_API_KEY="sk-ant-..." npm start -- --cwd . --no-session
看到欢迎界面后，输入：
请读取 package.json，告诉我这个项目有哪些 npm scripts。
你将看到以下执行过程：
- 终端输出
[Tool] ReadFile(...)。 - 工具返回
package.json内容摘要。 - Agent 用自然语言列出
build、start、dev、typecheck、test等脚本。
npm run typecheck
npm test
npm run build这些命令不会调用模型，只验证 TypeScript、工具注册表、文件读写、搜索、命令执行和权限判断等本地逻辑。
在仓库根目录运行：
./scripts/smoke.sh
脚本会依次进入四个项目执行：
npm ci
npm run typecheck
npm test
npm run build全部通过时会输出：
All smoke checks passed.
ANTHROPIC_API_KEY environment variable is not set
真实对话需要先设置 API Key：
export ANTHROPIC_API_KEY="sk-ant-..."
如果只想验证本地代码，执行 npm test 即可，不需要 API Key。
npm: command not found
请先安装 Node.js 20+，然后确认版本：
node -v npm -v
Cannot find module ... 或 dist/index.js 不存在
重新安装依赖并构建：
npm ci npm run build
MCP stdio 模式没有响应
project-analyzer-mcp 的 stdio 输出是 JSON-RPC 协议通道。不要在 stdio 入口中使用 console.log 输出调试信息，日志应写入 stderr。
mini-agent/ 与 mini-agent-full/ 共享 12 个应当逐字相同的文件，包括五个工具、权限、类型、入口和四个基线测试。修改其中任何一个后，请运行：
./scripts/check-baseline-drift.sh
如果只修改了一边，脚本会失败并输出 diff。
mini-agent/：本教程原创教学实现。mini-agent-full/：各章教学实现完成整合和接线后的版本。project-analyzer-mcp/：本教程原创 MCP 示例。multi-agent-review/：本教程原创多代理示例。
教程会参考 Claude Code 的公开架构与使用体验解释设计取舍。本仓库不是 Claude Code 源码复刻，也不承诺与 Claude Code 内部实现逐行一致。
准备好从“会调用 API”进阶到“能设计 Agent 系统”了吗？
前往掘金小册，开始系统学习 →