第 1 周 · AI Agent 工程基线

本周产出：可运行的 Monorepo、CI、第一份 ADR、统一事件词典 · 预计投入：15 到 20 小时 · 对应原 24 周编号：第 1 周

学前自测

先自己答一遍，答不上来的去看本页最后的复习与延伸。

1. 普通程序、Workflow 和 Agent 的边界在哪？给一个业务例子说明什么时候不该用 Agent。

规则明确、路径固定、结果可预期的用普通程序；步骤固定但需要编排、有分支和重试的用 Workflow；只有目标明确、路径需要模型自己决定的才用 Agent。举例：订单金额计算绝对不能交给 Agent，那是纯规则问题，用 Agent 只会引入非确定性和成本。

2. 为什么 Agent 系统比普通后端更需要严格的类型契约？

因为 Agent 的输出是非确定性的。普通后端的错误来自代码逻辑，可以靠测试穷举；Agent 的错误来自模型输出，同样的输入下次可能不一样。唯一能守住的边界就是入口和出口的 Schema 校验，让非法结构在进入业务逻辑之前就失败。

3. AbortSignal 解决什么问题？不处理会怎样？

解决长时间运行的异步操作的取消传播。Agent 一次 Run 可能跑几分钟、调十几次模型和工具，用户点了取消如果不能真正中断，就会继续烧 Token、继续产生副作用。不处理的后果是成本失控加上不可逆操作被误执行。

4. ADR 是什么？为什么架构决策要写下来而不是记在脑子里？

Architecture Decision Record，一份记录某个技术决策的背景、可选项、结论和后果的文档。写下来的价值在于半年后有人问为什么选 Mastra 不选 LangChain 时，答案不依赖于当事人还在不在职。这在面试里也是 Senior 和 Junior 的分水岭。

建立 Agent OS 的工程骨架和统一开发规范。这一周不写任何模型调用代码，全部投入在骨架上。很多人急着第一天就调 API，结果第五周开始重构地狱，这周的投入是为了后面九周不返工。

这一周最重要的一条架构不变量，用一张图就能说清：

箭头只能向内。contracts 不 import 任何实现，实现之间也不互相 import。守住这一条，第 9 周的双 Runtime 和程序员进阶版的 exit drill 才做得成；守不住，每加一个框架都要改一遍业务代码

给你的事件协议写十条架构不变量，用测试固化其中三条。

不变量的写法是断言句，比如「任何 ToolExecution 事件都必须能通过 run_id 关联到一个 AgentRun」「PolicyDecision 一旦产生就不可变更」。写完之后挑三条最关键的，用 Vitest 写成会失败的测试，然后实现到通过。

这个练习的意义在于：你会立刻发现自己的契约里有多少含糊地带。大多数人第一次写会卡在第四条，那正是需要想清楚的地方。

核心档（程序员基础版毕业线）

1. 你的 Monorepo 里，哪些包允许 import 模型 SDK？为什么其他包不允许？

只有 Provider Adapter 层允许。其他包一旦 import 了 SDK，Provider 的私有类型就会泄漏到业务逻辑，换 Provider 时改动面无法收敛。这条约束在第 2 周会被真正检验。

2. 列出你的高风险副作用清单，说明每一项的不可逆程度。

典型清单：发送邮件（不可逆）、修改价格（可逆但影响外部）、删除文件（可逆当且仅当有备份）、执行 shell 命令（取决于命令）、支付（不可逆且有金额）。分级的目的是第 3 周设计 Permission Gate 时知道哪些必须走审批。

3. 如果模型返回的 JSON 少了一个必填字段，你的系统在哪一层失败？

必须在 Zod 校验层失败，并且产生一个可见的错误事件，而不是让 undefined 流进业务逻辑在三层之后炸掉。能答清楚失败点在哪、错误怎么分类、Agent 怎么拿到反馈重试，这一周就算通了。

在仓库里交付三份文件，这三份直接进你的作品集：

docs/decisions/ADR-001-*.md：第一份 ADR，说明为什么采用 Harness-first 与框架 Adapter 策略，必须包含被否决的方案和否决理由
docs/architecture.md：系统上下文图 + 容器图（C4 前两层即可），加威胁模型表
docs/invariants.md：至少 10 条架构不变量，标注哪三条已经有测试覆盖

这一周的内容对应面试里的架构表达能力，通常出现在简历深挖环节。

「你这个项目为什么用 Monorepo？」：答模块边界和契约共享，不要答方便。重点讲你怎么防止业务包依赖框架私有类型。
「Agent 系统和普通后端在工程上最大的区别是什么？」：标准骨架是非确定性。展开讲三点：输出要 Schema 校验、执行要有预算上限、行为要可回放。这三点后面九周都会具体实现。
「你们怎么记录技术决策？」：拿出 ADR。这个问题看起来软，但能拿出真实 ADR 的候选人比例极低，是免费的加分项。

面试官问到架构时最想听的不是你用了什么，是你否决了什么以及为什么。ADR 里的否决理由部分要能背下来。

官方文档

本仓库对应源码

packages/contracts/src/ 是本周契约的参考实现，重点看 agent.ts、event.ts、policy.ts 三个文件怎么把非确定性约束成类型
packages/contracts/src/index.test.ts 展示了架构不变量怎么写成测试