04 · 课程边界与工程取舍

为什么先划边界

假设一门课同时讲终端 agent、IDE 插件、云端沙箱、浏览器自动化，每个方向分到四分之一篇幅，学习者最后对每条路线都有印象，但没有一条能从零写出来。更糟的是，这几条路线的分歧点出现得很早——终端 agent 处理的是 stdin/stdout 文本流，IDE 插件处理的是 Extension Host 和 Language Server Protocol，云端沙箱处理的是容器隔离和网络策略。从第三层开始它们就分叉了，两边都讲的结果是两边都停在第二层。

所以这一课要做的不是列一个"做/不做"的清单，而是把每条边界背后的取舍逻辑讲清楚。理解了"为什么选 A 不选 B"，后面遇到新的技术选项时，你自己就能判断它属于课程内还是课程外。

课程选了什么

一句话概括：在本地终端里，做一个能读懂、修改、执行、验证代码的 agent。

拆开看，这条主线由三条边界共同定义。

终端优先：命令行是唯一交互界面

agent 的输入输出都发生在终端里。用户打字描述需求，agent 在终端里展示执行过程和结果。不需要打开浏览器，不需要启动 GUI，不需要安装编辑器插件。

实际使用时，交互长这样：

$ mca
> 帮我在 src/utils 下新建一个 format.ts，实现日期格式化函数，并补上测试

[search] 搜索 src/utils 目录结构...
[read]  读取现有文件确认风格...
[edit]  创建 src/utils/format.ts
[edit]  创建 src/utils/format.test.ts
[run]   执行 pnpm test src/utils/format.test.ts
[结果]  2 tests passed

> 还需要做什么修改吗？

选终端作为界面，不只是"简单"这么一个理由。终端天然支持文本流和命令执行，agent 不需要自己实现"运行测试"的能力，它调用你已经安装好的工具就行。而且终端 agent 可以直接嵌入 CI/CD pipeline、shell 脚本和自动化工作流，这是 GUI 应用很难做到的事。

本地运行：不依赖云平台和远程沙箱

agent 直接在本地文件系统上读写，直接在本地进程中执行命令。

• 用 fs.readFile / fs.writeFile 读写本地文件，而不是通过远程 API
• 用 child_process.exec 在本地 shell 中执行命令，而不是把代码发送到远程沙箱
• 用本地 Git 操作管理版本，而不是通过云端的 Git 服务

这条边界的直接好处是：课程中的所有代码在你自己的电脑上就能跑，不需要配置云服务、不需要管理容器环境、不需要处理网络延迟。起步门槛降到最低。

聚焦编码：只做代码仓库内的读、改、跑、验、提交

agent 的能力范围严格限定在"操作代码仓库"这件事上。它不会帮你发邮件、订外卖、操控浏览器。它只做这几件事：

这五件事形成一个闭环：读懂当前代码状态，做出修改，跑测试验证，提交变更。闭环之外的事情，课程不碰。

课程不做什么，以及为什么

划清"不做"的边界和划清"做"的边界同样重要。下面每一个方向本身都有价值，只是它们和课程主线朝不同方向延伸。

不做 IDE 插件

Cursor、GitHub Copilot、Windsurf 已经证明 IDE 插件是一个有价值的产品方向。但它的技术栈和终端 agent 完全不同：你需要理解 Language Server Protocol 才能让 agent 理解代码语义，需要理解 VS Code Extension Host 才能让 agent 和编辑器交互，需要处理光标位置、选区范围、诊断信息等编辑器特有的概念。

这些复杂度和"agent 自身如何思考、如何使用工具、如何管理上下文"是两个不同的方向。课程选择后者作为主线，原因很实际：理解了 agent 的核心能力模型之后，把它迁移到 IDE 插件场景主要需要补的是编辑器接口层，agent 本身的逻辑可以复用。

不做云端沙箱

E2B、Fly.io、Cloud Sandbox 等产品提供了安全隔离的代码执行环境，这在生产场景中很重要。但云端沙箱的安全模型和本地 agent 完全不同：你需要用容器或虚拟机隔离执行环境，需要管理网络策略防止 agent 访问不该访问的服务，需要处理文件系统快照、资源限制、超时回收等运维问题。

这些是安全工程和基础设施的问题，不是 agent 能力模型的问题。课程聚焦本地执行，让你先理解 agent 本身怎么工作。以后要扩展到云端，只需要把"在本地执行命令"替换成"在远程沙箱执行命令"，agent 的核心逻辑不需要重写。

不做 GUI/浏览器自动化

能够点击按钮、填写表单、截取屏幕的 agent 在很多场景下都很有用，但它的能力模型和 coding agent 不同：你需要屏幕解析能力来理解当前界面状态，需要点击模拟和坐标定位来操作 GUI 元素，需要处理渲染引擎、DOM 结构、CSS 布局等前端特有的问题。

coding agent 的核心场景是"理解代码文本、执行代码命令"，GUI 自动化的核心场景是"理解视觉界面、模拟人类操作"。这是两套不同的输入输出模型。课程选择前者，因为终端文本交互是 coding agent 最直接的界面。

终端：最适合的界面，以及它的代价

三条边界中，终端优先 最值得展开讲，因为它直接影响课程中每一个技术决策。终端是适合的界面，但不是完美的界面。适合的地方要用好，不适合的地方要有对策。

终端的三个优势

开发者的自然栖息地。 无论你用什么编辑器写代码，你几乎都会同时开着一个终端窗口来跑测试、启动服务、查看日志。coding agent 出现在你已经在的地方，不需要切换上下文。

文本流、命令执行、管道组合，终端天生就会。 agent 的输出本质上是一段文本流——"我在读什么文件、我要做什么改动、测试结果是什么"。终端处理文本流的能力是内建的。而且终端可以执行任意命令，意味着 agent 不需要自己实现"运行测试"或"启动构建"，直接调用已有工具。

容易嵌入自动化流程。 一个在终端里运行的 agent 可以被 shell 脚本调用、可以在 GitHub Actions 里跑、可以和其他命令行工具通过管道组合。

终端的两个限制

没有富文本渲染。 终端只能显示等宽字符，不能渲染 Markdown、不能显示图片、语法高亮能力也很有限（ANSI 颜色码能做的事不多）。agent 的输出必须以纯文本形式组织，不能依赖视觉排版传递信息。

交互模式受限。 终端的交互主要是"用户输入一段文本、agent 输出一段文本"的轮流模式。它不支持按钮、下拉框、拖拽等 GUI 元素。agent 不能用"请从以下选项中选择一个"的方式交互，只能用文本提示。

两个应对策略

策略一：结构化文本输出。 虽然终端不能渲染富文本，但结构化的纯文本仍然可以很清晰：

[search] 搜索 src/utils 目录...
  找到 3 个 .ts 文件

[read] 读取 src/utils/format.ts（42 行）

[edit] 修改 src/utils/format.ts
  + 第 15 行：新增 formatDate 函数
  - 第 8 行：删除旧的 format 方法

[run] pnpm test src/utils/format.test.ts
  PASS src/utils/format.test.ts
  Tests: 2 passed, 2 total

方括号标注动作类型，缩进表示层级关系，+ 和 - 表示新增和删除。这些约定让纯文本输出也能承载清晰的语义。

策略二：状态面板展示执行进度。 当 agent 在执行一个多步骤任务时，终端可以显示一个简洁的进度面板，让你随时知道 agent 在做什么、做到哪一步了。这个能力会在课程的 streaming 和 CLI 章节中具体实现。

边界一览

下面这张图把课程范围和范围外的方向放在一起看。绿色区域是课程要逐步实现的十个能力模块，红色区域是课程不深入但各自有价值的方向。

绿色区域从核心到外围排列：Agent Loop 是最核心的决策循环，Tools 是 agent 操作代码的能力基础，Permissions 控制权限，Streaming 处理流式输出，Memory 管理上下文记忆，Skills 支持能力扩展，Hooks 提供生命周期钩子，MCP 连接外部工具协议，Subagents 支持子代理协作，CLI 把所有能力包装成可用的命令行产品。

红色区域内的四个方向不在课程范围内。边界线标注的是"课程选择不深入"的分隔线，不是"这些方向不重要"的意思。

边界之外的东西还有用吗

如果你关心的是"做浏览器自动化的 agent，这门课对我有用吗"——有用。课程中讲到的 agent loop、工具调用、权限控制、上下文管理等概念，在浏览器自动化 agent 中同样适用。区别主要在于工具层的实现：课程中的工具是文件读写和命令执行，浏览器自动化 agent 的工具是页面导航和元素操作。理解了核心模型之后，替换工具层是相对直接的事。

如果你关心的是"以后能扩展成云端版本吗"——可以，而且课程的设计让这个扩展变得直接。课程中 agent 执行命令的方式是通过 child_process 在本地执行，改成云端执行只需要替换这一层，agent 的决策逻辑、工具调用、上下文管理都不需要重写。

课程选择 本地运行、终端优先、聚焦编码，不是为了画地为牢，而是为了在有限篇幅内把主线走深。后续课程的所有内容都在这三条边界之内推进。如果你在某个章节产生"这个能力能不能扩展到 XX 场景"的想法，那说明你已经理解了这些边界的作用——边界之内打好基础，边界之外自然有路。