05 · 主项目与课程路线图

课程结束的时候，你手里会有什么

一个叫 mini-coding-agent 的 CLI 工具。用 TypeScript + Node.js 写成，在终端里运行。它能接收你的自然语言指令，在本地仓库里搜索代码、理解上下文、修改文件、跑测试、看 diff，最终把任务完成的结果交还给你。

这不是一堆散落的示例项目。从第 1 章写下第一行代码开始，到第 11 章收尾，所有改动都叠加在同一个项目上。每一章补一块核心能力，最终形成一个完整的工具。

用一个简单的节奏来理解这个演进过程：

• 前几章让它"能跑起来"
• 中间几章让它"跑得安全、跑得可见、跑得聪明"
• 最后几章让它"能扩展、能协作、能交付"

从起点到终点：12 章的全景

课程一共 12 章（第 0 章到第 11 章），分为三个阶段。先看全貌，再逐阶段展开。

阶段一：基础闭环（第 0-3 章）

目标是做出一个能理解任务、搜索代码、修改文件、跑测试的 agent。这四个章节解决的是"从零到能做事"的问题。

• 第 0 章：全局认知。 理解 coding agent 是什么、主流产品怎么做、课程的边界在哪里。也就是你现在正在读的部分。
• 第 1 章：最小可用 Agent。 搭出消息、模型、工具、输出四层骨架，让 agent 能回答关于仓库的问题。这一章结束时，你就有了一个能跟大模型对话、能读代码的最小 agent。
• 第 2 章：Agent Loop 与任务规划。 加入 ReAct 循环、Todo 机制、退出条件与失败恢复，从单轮问答升级到多步骤执行。这一章之后，agent 不再只是回答一个问题，而是能规划并执行一系列步骤。
• 第 3 章：Tools 工具系统。 补齐搜索、文件、命令、Git 四类工具，跑通"读代码-改代码-跑命令-看 diff"的完整闭环。到这一章结束，agent 已经具备基本的代码操作能力。

阶段二：工程化能力（第 4-8 章）

基础闭环做好了，但它还有很多粗糙的地方：没有权限控制、用户看不到执行过程、跨轮次没有记忆、能力都堆在 prompt 里不好维护。这五章逐一补齐这些短板。

• 第 4 章：Permissions 安全与权限。 加入 allow/ask/deny 权限模型，建立可审计的执行边界。agent 不能想执行什么命令就执行什么，需要规则和用户确认。
• 第 5 章：Streaming 与交互体验。 加入流式输出和终端状态面板，让用户能实时看到 agent 在做什么、进展到哪一步。
• 第 6 章：Memory 与上下文工程。 加入短期记忆、会话记忆和项目规则，让 agent 跨轮次保持连续性，不再每次对话都从零开始。
• 第 7 章：Skills 能力模块化。 加入技能定义、触发和复用机制，把大 prompt 拆成可维护的能力模块，而不是把所有指令塞进一个巨大的系统提示词里。
• 第 8 章：Hooks 生命周期扩展。 加入 before/after hooks，在关键时机注入自动格式化、风险拦截和日志采集，让 agent 的行为更可控、更可观测。

阶段三：平台化扩展（第 9-11 章）

工程化做好了，接下来让 agent 能加载外部工具、能拆分角色协作、最终收敛为一个可交付的产品。

• 第 9 章：MCP 工具扩展。 加入 MCP client，让 agent 能加载外部工具而不必把所有能力写死在主进程中。
• 第 10 章：Multi-Agent 协作。 加入 subagent 调度和上下文隔离，用角色拆分应对复杂任务。
• 第 11 章：CLI 产品化与毕业项目。 收敛成完整的命令行工具，并用真实仓库任务完成毕业验收。

每一章，代码会变成什么样

下面列出每一章会在代码上增加什么。现在不需要理解每项的技术细节，只需要建立一个大致印象。后面每学完一章回来对照，感受会更具体。

• 第 0 章 -- 只有课程认知，没有代码改动
• 第 1 章 -- 消息类型定义、模型调用封装、工具接口、执行入口
• 第 2 章 -- loop 循环体、Todo 列表与步骤状态管理、退出条件判断、失败重试逻辑
• 第 3 章 -- tools 注册表与统一执行层：搜索工具（rg、glob）、文件工具（read、write、patch）、命令工具（run）、Git 工具（status、diff、branch）
• 第 4 章 -- permissions 权限模型：allow/ask/deny 规则匹配、高风险操作识别、用户确认流程、执行日志记录
• 第 5 章 -- streaming 事件体系：模型 token 流、工具调用事件、命令状态事件、终端渲染面板
• 第 6 章 -- memory 层：短期记忆（当前链路）、会话记忆（任务历史）、项目记忆（AGENTS.md、配置文件）、上下文选择与压缩引擎
• 第 7 章 -- skills 加载与触发机制：技能文件结构、技能注册表、任务分类与自动匹配
• 第 8 章 -- hooks 生命周期扩展：before_tool / after_tool / before_edit / after_edit / before_finish 钩子、自动格式化、风险拦截
• 第 9 章 -- MCP client：协议适配、工具发现与注册、外部工具桥接到统一工具执行层
• 第 10 章 -- subagent 调度：角色定义（planner、explorer、editor、reviewer）、上下文隔离、结果汇总、并行与串行协作
• 第 11 章 -- CLI 产品化：命令设计（ask、plan、run、resume）、配置文件、会话持久化、非交互模式、错误码与退出码

四个阶段性的验收项目

课程安排了四个实践项目，分别在不同阶段检验你是否已经把前面几章的能力整合到了一起。它们不是孤立的练习题，而是沿着主项目演进路线设置的验收节点。

项目 A：最小仓库问答 agent -- 第 1 章结束后验收。让 agent 能接收自然语言问题，在本地仓库中搜索相关代码并给出回答。核心能力：模型调用、消息构造、搜索工具、文件读取。

项目 B：自动修复一个简单 bug -- 第 2-4 章结束后验收。让 agent 能理解 bug 描述，定位问题代码，提出修改方案，并在权限确认后执行修改。核心能力：agent loop、任务规划、工具执行、权限控制。

项目 C：带测试验证的本地开发 agent -- 第 5-8 章结束后验收。让 agent 能在终端中实时展示执行过程，记住上下文，按技能模板工作，并在编辑后自动验证。核心能力：streaming 输出、记忆系统、skills、hooks。

项目 D：支持 MCP 和 subagent 的完整 CLI 工具 -- 第 11 章毕业验收。完成最终的 CLI 工具，支持外部工具扩展和多 agent 协作，能在真实仓库中完成完整开发任务。核心能力：MCP 扩展、subagent 协作、CLI 产品化。

关于学习节奏的建议

课程按章节层层叠加设计，建议按顺序学习。第 2 章依赖第 1 章的 agent 骨架，第 4 章依赖第 3 章的工具系统，第 6 章依赖第 5 章的事件体系。跳着学容易遇到"这段代码从哪来的"这种困惑。如果你已经有 agent 开发经验，可以快速浏览前几章，但至少把每章的代码演进和关键设计决策过一遍，确保理解和课程主线对齐。

关于每章所需的时间，大致参考：对 TypeScript 和 Node.js 比较熟练的话，每章大约 2-4 小时（阅读文档、理解代码、跑通示例）；还不够熟练的话，可能需要 4-6 小时来消化语言和工具层面的细节。第 11 章的毕业项目可能额外需要 4-8 小时。整体下来大约 40-60 小时。

学完之后，你应该能清楚理解 Claude Code、Codex CLI、Gemini CLI、OpenCode 这类产品的核心架构，能独立实现一个具备完整能力闭环的 terminal coding agent，并具备继续扩展或参与其他 agent 项目开发的工程基础。课程的边界在第 4 节已经讲过：聚焦 终端优先、本地运行 的 coding agent，不涉及 IDE 插件、云端沙箱或 GUI 自动化。

---

第 0 章到这里全部结束。你已经建立了全局认知：理解了 Harness 的概念和六个核心组件，知道 Coding Agent 是什么，看过了主流产品的设计，清楚了课程的边界和 12 章的完整路线。下一步，进入第 1 章，开始写代码。