如果你想真正搞懂 Claude Code / Cursor 背后的 Agent 是怎么“会思考、会调工具、会持续完成任务”的，这套教程就是给你的。
你将从 0 开始，一步步做出一个可运行、可扩展、可发布的 Agent CLI，不只会“调用模型”，还会完整打通 REPL、Agentic Loop、上下文构建、工具系统和工程化发布。
第 0 部分：准备 (第 0 章)
第 1 部分：核心骨架 (第 1-8 章)
第 2 部分：工具系统 (第 9-15 章)
第 3 部分：高级特性 (第 16-20 章)
第 4 部分：工程化 (第 21-24 章)
第 5 部分：扩展生态 (第 25-27 章)
第 6 部分：综合实战 (第 28 章)
- 实现目标：明确教程定位、环境准备、项目结构和学习方式。
- 里程碑：
bun init -y && bun add @anthropic-ai/sdk ink react commander lodash-es
- 实现目标：完成最小可运行问答（stdin -> LLM -> stdout）。
- 里程碑：
echo "用一句话解释闭包" | bun run src/index.ts -p
- 实现目标：实现
--version快速路径、参数分发、动态加载。 - 里程碑：
bun run src/index.ts --version
- 实现目标：支持流式输出和交互式 REPL。
- 里程碑：
bun run src/index.ts
- 实现目标：实现 LLM -> tool -> LLM 的循环调用，直到任务完成。
- 里程碑：
bun run src/index.ts -p "当前目录有多少个 .ts 文件？"
- 实现目标：构建并注入 Git/项目规则/日期等上下文。
- 里程碑：
bun run src/index.ts -p "我们现在在哪个分支？最近有什么改动？"
- 实现目标：打通 REPL、Loop、Context 三层，使
REPL与-p共用执行链路。 - 里程碑：
bun run src/index.ts后在 REPL 内触发工具调用与上下文回答。
- 实现目标：承接第 6 章的统一循环。
工具轮仍为阻塞式，保证
tool_calls拼接完整后再执行； 对用户可见的最后一轮文本可走流式delta，驱动 Ink 逐段刷新； 整体与-p共用上下文，并与后续权限策略衔接。 - 里程碑：
bun run src/index.ts，在 REPL 中先触发需bash的问题，再问开放题，二者均正常；后者可见流式打字（或等价的分块刷新），前者工具结果后再出整段结论。
- 实现目标：对齐 claude-js 的 REPL 组件思路，升级消息区、输入区、状态栏、工具进行中区域等布局与交互骨架；未实现的能力可先隐藏或占位，但组件结构先搭好。
- 里程碑：
bun run src/index.ts，可看到分区化 REPL 布局（消息列表/ 输入行/状态提示），支持流式文本渲染、工具进行中提示、基础键位交互 （如/clear、/help、滚动或焦点切换预留）。
- 实现目标：定义 Tool 接口、注册表、执行器。
- 里程碑：
bun run src/index.ts -p "把字符串 hello 转为大写"
- 实现目标：实现
read_file、write_file、edit_file。 - 里程碑：
bun run src/index.ts "修改 README.md，把所有 TODO 改为 DONE"
- 实现目标：实现
bash、glob、grep三类高频工具。 - 里程碑：
bun run src/index.ts "运行测试，找出失败原因，给我摘要"
- 实现目标：实现
web_fetch、web_search、ask_user。 - 里程碑：
bun run src/index.ts "搜索 Bun 1.2 breaking changes，然后问我是否更新"
- 实现目标：实现
todo_write、计划模式、worktree 隔离流程。 - 里程碑：
bun run src/index.ts "先给我计划，再重构认证系统"
- 实现目标：支持子代理并行执行与主代理汇总。
- 里程碑：
bun run src/index.ts "并行为 src/utils/ 每个文件生成测试"
- 实现目标：实现 MCP 客户端并动态加载外部工具。
- 里程碑：
bun run src/index.ts "列出这个仓库最新的 5 个 PR"
- 实现目标：实现跨会话记忆提取、存储、召回。
- 里程碑：重启会话后仍能回答“项目测试命令是什么”。
- 实现目标：实现工具调用权限判定与确认流程。
- 里程碑：危险命令需要确认，安全命令自动放行。
- 实现目标：实现可选 OS 沙箱与资源/路径隔离。
- 里程碑：沙箱模式下拒绝访问项目外敏感路径。
- 实现目标：长对话自动压缩，保持任务连续性。
- 里程碑：上下文接近上限时自动 compact 并继续工作。
- 实现目标：实现 Pre/Post/Session 三级 Hook。
- 里程碑：工具执行后自动触发自定义命令（如
git add）。
- 实现目标：建立单元、集成、端到端测试体系。
- 里程碑：
bun test核心模块通过。
- 实现目标：接入结构化日志、性能打点、错误追踪。
- 里程碑：可查看一次会话的完整调用链和耗时。
- 实现目标：实现全局/项目/环境变量/CLI 参数优先级。
- 里程碑：
myagent config set model ...后立即生效。
- 实现目标：支持本地打包、npm 发布、多平台分发。
- 里程碑：
npm i -g myagent && myagent --version
- 实现目标：实现 Skill 扫描、加载与插件扩展入口。
- 里程碑：安装后可调用自定义 Skill。
- 实现目标：实现 Coordinator/Worker 协同执行。
- 里程碑：多模块任务可并行拆解并汇总。
- 实现目标：统一 Provider 抽象，支持多云模型接入。
- 里程碑：切换环境变量即可切换 Provider。
- 实现目标：从空目录到可发布的
myagent v1.0.0全流程演练。 - 里程碑：完成一次可复现的构建、测试、发布流程。
- 快速上手：第 1-3 章
- 可用 Agent：第 1-12 章
- 生产可用：第 1-23 章
- 完整版本：全部 28 章
每章的代码按照分支存放在仓库中， 分支名称为 chapter-xxx。
| 文件 | 行数 | 对应章节 |
|---|---|---|
src/entrypoints/cli.tsx |
320 | 第 2 章 |
src/main.tsx |
4,683 | 第 2 章 |
src/screens/REPL.tsx |
5,009 | 第 3 / 7 / 8 章 |
src/query.ts |
1,732 | 第 4 章 |
src/QueryEngine.ts |
1,320 | 第 4 章 |
src/context.ts |
189 | 第 5 章 |
src/tools.ts |
389 | 第 9 章 |
src/services/api/claude.ts |
3,420 | 第 1 章 |
src/services/mcp/ |
12,242 | 第 15 章 |
src/memdir/ |
— | 第 16 章 |
src/hooks/toolPermission/ |
— | 第 17 章 |
src/services/compact/ |
— | 第 19 章 |
src/utils/config.ts |
1,000+ | 第 23 章 |
- 通用 Agent 系统提示词
- 子代理（Explore / Plan / Verify）提示词
- 记忆提取专用提示词
- Coordinator 角色提示词
| 目标 | 需完成 | 耗时 |
|---|---|---|
| 快速上手，能聊天 | 第 1-3 章 | 1-2 天 |
| 能干活的 Agent | 第 1-12 章 | 3-5 天 |
| 生产可用 | 第 1-23 章 | 2-3 周 |
| 完整版本 | 全部 28 章 | 1 个月 |
- 用 OpenAI 还是 Anthropic？ 两者均可；Anthropic 的 Tool Use API 更贴近本教程的设计
- 必须用 Bun 吗？ 推荐用 Bun，Node.js 也可以，但需跳过第 2 章的部分优化技巧
- React Ink 难吗？ 会 React 的话 Ink 一天上手；不会 React 可以先用
readline实现简单版本 - API 费用多少？ 完成全教程约 $5-20，可用
DeepSeek/GLM/Qwen降低成本