# 案例 06 · CodePilot:AI Agent / 编码 Agent 平台
> 一句话点题:**本案例练的是「能动手的 AI 如何不失控」——编码 Agent 的难点不是让模型会写代码,而是让它在能读仓库、改文件、跑命令、调用工具、长时间执行任务时,仍然被权限、沙箱、预算、审批、检查点和评测约束住。**
---
> **🧪 案例篇第 6 篇 · 本案例只练一件事**
>
> 练**AI Agent / 编码 Agent 平台**下的架构判断:什么时候用工作流,什么时候才让 Agent 自主循环,工具调用为什么必须过权限网关,沙箱和人工审批为什么不是一回事,长任务如何靠检查点和上下文压缩恢复,子代理如何隔离重活,以及 eval 如何防止模型 / prompt 升级后质量悄悄退化。
>
> | 读完你应该能 | 本案例靠什么练 |
> |---|---|
> | 说清 Agent 和聊天框的根本差异 | 用「读仓库 → 改文件 → 跑测试 → 看结果 → 再改」的行动循环解释 |
> | 判断工具调用为什么不能直接交给模型 | 用权限网关、沙箱、工作区边界和高危审批兜住副作用 |
> | 看懂长任务为什么会忘目标、烧预算、跑偏 | 用检查点、trace、上下文压缩、预算上限和恢复流程处理 |
> | 判断子代理什么时候有用、什么时候只是增加噪声 | 用独立上下文、独立预算、结果摘要回灌主线来隔离重活 |
>
> **重要提醒:下面是教学化案例,不是某个真实编码 Agent 产品的内部图纸。** 数字用于数量级推理,目的是练判断,不是给出唯一答案。
---
## 开场:为什么编码 Agent 不是「更会写代码的聊天框」
因为聊天框只会给建议,编码 Agent 会真的动你的仓库。
> **CodePilot** 是一个给工程团队用的编码 Agent 平台。工程师可以提交任务:「修复这个失败测试」「给支付回调补幂等」「把这个依赖升级到新版」「读这个模块并给出重构方案」。CodePilot 会拉取仓库、阅读代码、制定计划、修改文件、运行测试、根据报错继续调整,最后交付一个 diff 或 Pull Request。
第一眼看,它像是「会写代码的模型」:
- 用户描述需求;
- 模型读代码;
- 模型生成补丁;
- 跑测试;
- 输出结果。
但真正上线后,最危险的不是「代码写得不够漂亮」,而是:
> **Agent 被 README 里的提示注入诱导去读密钥,跑了危险命令,改了工作区外的文件,长任务压缩后忘了用户要求,子代理各改各的互相冲突,模型升级后修 bug 成功率悄悄下降。**
所以这一章不写「怎么调一个大模型 API」。它问一个更具体的问题:
> **如何让一个能读写代码、能执行命令、能长时间自主工作的 Agent,既有用,又停得住、审得清、恢复得了?**
这章和前五章的压力源不同:
- [StarArena](../stararena-ticketing/README.md) 怕的是库存和支付状态。
- [PatchDesk](../patchdesk-saas/README.md) 怕的是多租户边界。
- [DocuMind](../documind-rag/README.md) 怕的是答案可信和提示注入。
- [SyncRoom](../syncroom-collaboration/README.md) 怕的是实时状态收敛。
- [FeedStream](../feedstream-content/README.md) 怕的是内容分发放大。
- **CodePilot 怕的是 AI 一旦能动手,错误就从「说错」变成「改坏、泄露、花钱、提交」。**
---
## 读前小词典
这篇会反复出现几个词,先用人话对齐一下:
| 词 | 人话解释 |
|---|---|
| Agent | 能自己多步行动的 AI。不是只回答,而是会规划、调工具、看结果、再决定下一步。 |
| Workflow | 工作流。步骤提前写死或半固定,模型只在某些节点判断。比 Agent 更可控、更便宜。 |
| Agent loop | Agent 行动循环。通常是「计划 → 调工具 → 观察结果 → 再计划」。 |
| Tool call | 工具调用。模型请求读文件、搜代码、改文件、跑测试、查网页、调用内部 API。 |
| Sandbox | 沙箱。把命令关在隔离环境里执行,限制它能读哪里、写哪里、能不能联网。 |
| Workspace | 工作区。Agent 被允许读写的项目目录。工作区外通常不该被动到。 |
| Permission gateway | 权限网关。所有工具调用先过它,决定放行、拒绝,还是暂停问人。 |
| Approval | 人工审批。高风险动作前停下来问用户,比如联网、删除文件、提交、部署。 |
| Checkpoint | 检查点。保存任务状态、已改 diff、工具结果摘要和预算,中断后能继续。 |
| Trace | 执行轨迹。记录 Agent 每一步做了什么、调了什么工具、看到了什么结果。 |
| Context window | 上下文窗口。模型一次能看见的内容上限。任务长了会装不下。 |
| Compaction | 上下文压缩。把早期历史摘要成短记录,腾出窗口继续任务。 |
| Memory | 记忆。跨步骤或跨会话保留的规则、偏好、历史经验。不是越多越好,会过时。 |
| Subagent | 子代理。把搜索、日志排查、审查这类子任务丢给独立上下文的 Agent,只把摘要带回主线。 |
| Prompt injection | 提示注入。外部内容里夹带「忽略规则、泄露密钥」这类指令,诱导模型违规。 |
| Budget | 预算。单任务最大步数、token、时间、工具调用次数和花费上限。 |
| Eval | 评测。用一批代表性任务持续衡量成功率、安全性和回归,防止升级后悄悄变差。 |
---
## 一、起始状态:先做受控编码助手,别先做全自动工程师
CodePilot 的第一版目标很克制:**让小团队把低风险工程任务交给 Agent 处理,但所有真实改动都能被人看见和拦住。**
起始阶段的约束大概是这样:
| 维度 | 起始阶段 |
|---|---|
| 试点团队 | 20～50 名工程师 |
| 接入仓库 | 5～20 个 |
| 单仓库规模 | 1 万～20 万行代码 |
| 每日 Agent 任务 | 50～200 个 |
| 峰值并发任务 | 5～20 个 |
| 常见任务 | 补测试、小 bug、读代码、改文档、简单依赖升级 |
| 核心目标 | 能交付可 review 的 diff,并能解释每一步为什么这么改 |
| 最不能错 | 读密钥、改工作区外文件、自动执行不可逆操作、没有 trace |
这时最合理的架构不是「全自动软件工程师」,而是**受控 Agent loop + 工具网关 + 工作区沙箱 + 人工 review**:
```
工程师提交任务
│
▼
┌────────────────────────────────────────────┐
│ 任务服务 │
│ 记录目标、仓库、分支、预算、权限档位 │
└──────────────┬─────────────────────────────┘
▼
┌────────────────────────────────────────────┐
│ Agent 编排器 │
│ 计划 → 读文件 / 搜索 → 打补丁 → 跑测试 → 再调整 │
└──────────────┬─────────────────────────────┘
▼
┌────────────────────────────────────────────┐
│ 工具网关 + 沙箱 │
│ 限定工作区、限制网络、危险动作问人、全程 trace │
└──────────────┬─────────────────────────────┘
▼
diff / 测试结果 / 执行轨迹 → 人工 review
```
这不是保守,而是把第一版的边界讲清楚:
- Agent 可以读仓库,但敏感路径默认不可读。
- Agent 可以改文件,但只能改工作区。
- Agent 可以跑测试,但命令要有超时和资源限制。
- Agent 可以建议提交或开 PR,但不能绕过 review。
- Agent 可以长时间执行,但每一步都要可追踪、可恢复、可停止。
---
## 二、量化假设:它不是先被 QPS 压垮,而是被权限、上下文和副作用压垮
先算一笔账。假设 CodePilot 从试点推广到一个中型研发组织:
```
工程师:300
仓库:800
活跃仓库:150
单仓库规模:5 万～80 万行代码
每日 Agent 任务:1,000～3,000 个
峰值并发任务:50～120 个
单任务平均轮次:8～20 步
长任务轮次:30～80 步
每轮工具调用:1～4 次
常见工具:读文件、搜索、打补丁、跑测试、包管理、Git、内部 API
目标:简单任务 5～10 分钟内给出 diff
目标:复杂任务 30～60 分钟内给出 PR 或明确失败原因
安全目标:越权写工作区外文件 = 0;敏感文件外泄 = 0
预算目标:每个任务都有最大步数、最大 token、最大执行时间、最大并发
质量目标:模型 / prompt / 工具策略变更前,核心 eval 不低于基线
```
这个数量级里,请求量不是第一个问题。普通 Web 系统会先算 QPS,但 CodePilot 会先撞上这些东西:
1. **权限边界**:Agent 能执行命令,就可能误删、误改、误联网。
2. **上下文边界**:仓库太大、日志太长、任务太久,模型会装不下。
3. **副作用边界**:文件编辑可回滚,但发请求、推代码、部署、改数据库可能收不回。
4. **成本边界**:多试几步可能修好,也可能无限循环烧钱。
5. **质量边界**:模型升级后,成功率可能提升,也可能在某类任务上退化。
所以 CodePilot 的架构重心不是「怎么多扛几个请求」,而是:
> **把 Agent 的自主性关进可执行、可审计、可恢复、可评测的边界里。**
---
## 三、触发信号:什么时候说明第一版开始不够用
第一版跑起来后,不要凭感觉升级。看这些信号:
| 信号 | 表现 | 为什么这是架构问题 |
|---|---|---|
| 用户频繁盲批 | 每个命令都问,用户开始不看就批准 | 审批策略太吵,安全变成形式 |
| 越权请求增多 | Agent 经常想读 `~/.ssh`、`.env`、工作区外路径 | 权限默认值和提示注入防线不够清楚 |
| 长任务中断后全废 | 跑了 40 分钟,进程挂了只能重来 | 没有持久化检查点和可恢复任务状态 |
| 压缩后忘要求 | 一开始要求「别动数据库层」,后面压缩后还是改了 | 关键约束没有固定保留和重载 |
| 工具日志撑爆窗口 | 全量测试日志、依赖树、搜索结果把上下文塞满 | 工具输出缺少摘要、截断和引用 |
| 子代理互相冲突 | 两个子代理同时改同一片代码 | 子任务边界和合并协调缺失 |
| 成本突然升高 | 某类任务反复尝试、无限修复同一个错误 | 缺少步数、时间、token、重复检测上限 |
| 结果无法复盘 | 只看到最终 diff,不知道为什么这么改 | trace 不完整,review 没有证据链 |
| 升级模型后退化 | 小 bug 修得更多,但安全拒绝能力下降 | 没有 eval 门禁衡量多维质量 |
| prompt injection 事故 | issue / README 里一句话诱导 Agent 泄密或外联 | 外部内容被当成指令,没有不可信输入隔离 |
这些信号不是在说「模型还不够聪明」。它们在说:**只靠模型能力无法让 Agent 进入生产,必须把控制能力做进架构。**
---
## 四、核心矛盾:Agent 越能干,越必须被限制
CodePilot 的核心对象有五组:
1. **任务 / 目标 / 预算**:用户要它做什么,允许花多少步、多少时间、多少钱。
2. **仓库 / 工作区 / 分支**:它能读写哪个项目,最终产物落到哪里。
3. **工具 / 权限 / 沙箱**:它能调用什么工具,每个工具的物理边界在哪里。
4. **上下文 / 记忆 / 压缩**:它每一步看见什么,哪些约束必须长期保留。
5. **trace / diff / eval**:它做过什么,怎么 review,质量是否持续稳定。
如果只看最简单路径,它像这样:
```
用户给任务 → 模型生成代码 → 跑测试 → 返回
```
但真实系统必须在每一步都回答:
- 这次工具调用只是读文件,还是会改变世界?
- 这个命令能不能联网?能不能写工作区外?
- 这段 README 是项目说明,还是有人写进去的提示注入?
- 这次修改能不能回滚?要不要先 checkpoint?
- 上下文压缩时,用户的硬约束有没有保住?
- 子代理的结果是证据,还是只是建议?
- Agent 失败时,是测试失败、权限失败、预算耗尽,还是模型跑偏?
- 新模型上线后,任务成功率、安全拒绝率、最小改动率有没有退?
所以新的架构命题变成:
> **CodePilot 的价值来自自治执行,风险也来自自治执行。架构的核心不是让它更自由,而是把「能动什么、何时问人、怎么恢复、怎么证明没变差」做成系统结构。**
最关键的分类是按风险看工具:
| 工具类型 | 例子 | 默认策略 |
|---|---|---|
| 只读低风险 | 搜索代码、读非敏感文件、查看测试配置 | 可自动,但输出仍当不可信观察 |
| 可逆中风险 | 修改工作区文件、生成 diff、格式化代码 | 沙箱内允许,保留 checkpoint 和 diff |
| 高风险副作用 | 联网下载、发请求、写数据库、发邮件、推代码 | 默认 ask 或 deny |
| 不可逆 / 组织风险 | 部署、删除远端资源、改权限、转账 | 强制人工审批,很多场景直接禁止 |
---
## 五、方案推演:编码 Agent 到底该怎么执行工具
这是本案例最重要的决策。很多 Demo 能跑,但一旦接入真实仓库和 shell,风险马上变成工程问题。
### 方案 A:只做聊天建议,不执行工具
```
用户贴代码 / 错误日志
└─▶ 模型给建议
└─▶ 人自己复制、改、跑测试
```
| 优点 | 代价 |
|---|---|
| 安全边界简单,模型没有真实副作用 | 用户仍要搬运上下文,效率提升有限 |
| 容易接入 | 无法自己验证,容易停在「看起来对」 |
| 适合学习和解释 | 不能承担整段工程任务 |
### 方案 B:本地 Agent 直接拿完整 shell 权限
```
Agent 读仓库 → 改文件 → 跑任意命令 → 联网 → 提交
```
| 优点 | 代价 |
|---|---|
| 最灵活,遇到问题可以自己试 | 风险最大,误删、泄密、外联、越权都可能发生 |
| Demo 体验强 | 很难给团队统一治理和审计 |
| 实现看似简单 | 一旦出事故,没有结构化边界可兜底 |
### 方案 C:平台化 Agent,所有工具过网关和沙箱
```
模型提出工具调用
└─▶ 权限网关判断 allow / ask / deny
└─▶ 沙箱执行
└─▶ 结果作为观察返回模型
└─▶ trace / checkpoint / budget 全程记录
```
| 优点 | 代价 |
|---|---|
| 能动手,但有物理边界 | 配置和心智复杂度更高 |
| 工具副作用可审计、可限制 | 某些合法任务会被沙箱挡住,需要显式授权 |
| 支持团队治理、CI、云端任务 | 需要建设任务状态、trace、沙箱池和 eval |
CodePilot 成长期选择:**方案 C。工具调用必须经过权限网关和沙箱,高风险动作必须能暂停问人。**
关键不是「信不信模型」,而是:
> **凡是模型指令能影响的层,都不算硬约束。硬约束必须落在模型绕不过的地方:权限网关、沙箱、预算、审批、CI、eval。**
---
## 六、关键架构决策:用 ADR 把为什么留下来
ADR 是 Architecture Decision Record,可以理解成「架构决策记录」。编码 Agent 最容易在后面被人问:「为什么不全自动?为什么沙箱和审批要分开?为什么要保存 trace?为什么子代理不能继承全部上下文?」这些都应该提前写下来。
### ADR-01:默认工作流优先,只在开放任务上使用自主 Agent loop
- **背景**:很多工程任务其实步骤明确,比如「跑 lint → 修格式 → 跑测试 → 提交 diff」。这类任务用固定工作流更便宜、更可预测。
- **选择**:CodePilot 默认先把任务拆成可控工作流;只有当路径不确定、必须根据工具反馈多次调整时,才进入自主 Agent loop。
- **放弃**:放弃所有任务都让模型自由规划的简单宣传口径。
- **换来**:更低成本、更强可控性、更容易复盘失败原因。
- **风险**:工作流边界设计不好时,会限制 Agent 的灵活性。
- **复审条件**:当大量任务在固定流程里卡住,且人工复盘说明确实需要开放探索时,再放宽对应任务类型。
### ADR-02:工具调用必须经过权限网关和沙箱,不能由模型直接执行
- **背景**:编码 Agent 能读写文件、跑 shell、联网、调用内部 API,副作用真实。
- **选择**:所有工具调用先过权限网关;文件写入限制在工作区;敏感路径默认拒绝;命令在沙箱里执行;网络默认收窄;高风险动作 ask 或 deny。
- **放弃**:放弃「模型想跑什么就跑什么」的灵活性。
- **换来**:即使模型被提示注入诱导,物理边界仍能兜住大部分事故。
- **风险**:权限配置会变复杂,某些开发任务需要额外授权。
- **复审条件**:当团队接入更多内部工具、MCP(Model Context Protocol,工具 / 数据接入协议)或云资源时,重新审权限分层和默认 deny 策略。
### ADR-03:沙箱模式和人工审批解耦成两根轴
- **背景**:很多人把「自动 / 手动」当一个档位,但这会混淆两件事:物理上能动哪里,流程上什么时候问人。
- **选择**:沙箱管物理边界,审批管流程打断。例如 `read-only + never` 适合 CI 分析,`workspace-write + on-request` 适合默认编码任务,高风险外部副作用必须 ask。
- **放弃**:放弃一个简单但含糊的一维自动化档位。
- **换来**:权限边界更清楚,能同时支持本地结对、CI 只读分析、云端异步任务。
- **风险**:用户需要理解两个维度,否则会误以为「少问人 = 权限更大」。
- **复审条件**:当用户频繁盲批,或合法任务频繁被打断,说明审批策略需要重调。
### ADR-04:长任务必须持久化检查点、trace 和预算状态
- **背景**:编码任务可能跑几十分钟,中间会话变长、工具输出变大、进程也可能中断。
- **选择**:保存任务状态、步骤 trace、已改 diff、工具结果摘要、预算用量;接近上下文上限时自动压缩,但从稳定存储重载项目规则、用户目标和关键约束。
- **放弃**:放弃只靠一次长对话硬撑到底。
- **换来**:任务可恢复、可审计,压缩后不至于完全忘记核心约束。
- **风险**:摘要可能丢细节,错误摘要会误导后续步骤。
- **复审条件**:如果长任务失败多来自「忘了早期约束」,需要改压缩模板、固定保留清单或拆任务。
### ADR-05:子代理只隔离重活,结果摘要回灌主线
- **背景**:全仓搜索、依赖分析、测试日志排查会产生大量中间信息,容易污染主上下文。
- **选择**:子代理有独立上下文、独立工具权限、独立预算;主线只接收结构化摘要、证据文件和建议,最终决策仍由主线合并。
- **放弃**:放弃让子代理继承全部主对话历史。
- **换来**:主线上下文更干净,复杂任务可并行拆分。
- **风险**:子代理摘要可能漏掉关键事实,多代理还会放大成本和延迟。
- **复审条件**:只有当单 Agent 的上下文被重活挤爆,或任务天然可拆且写入范围不重叠时,才引入子代理。
---
## 七、演进后的结构与数据流
下面只画 CodePilot 的核心结构。它不是「模型 + shell」,而是一套任务执行、权限控制、上下文管理、可观测和评测系统。
### 起始路径
```
用户发任务 → 模型生成补丁 → 本地跑命令 → 用户看结果
```
问题是:权限、沙箱、预算、恢复、trace、eval 都没有结构化。
### 演进后的结构
```
用户 / CI / 定时任务
│
▼
┌──────────────────────────────────────────────┐
│ 任务入口 │
│ 目标、仓库、分支、权限档位、预算、审批策略 │
└──────┬───────────────────────────────────────┘
▼
┌──────────────────────────────────────────────┐
│ Agent 编排器 │
│ 工作流优先;必要时进入 Agent loop │
│ 计划 → 工具调用 → 观察 → 再计划 │
└──────┬───────────────────────┬───────────────┘
│ │
▼ ▼
┌──────────────┐ ┌──────────────────────┐
│ 上下文构建器 │ │ 任务状态 / trace │
│ 仓库地图、文件、 │ │ 检查点、diff、预算 │
│ 规则、记忆、压缩 │ │ 工具结果摘要 │
└──────┬───────┘ └──────────────────────┘
│
▼
┌──────────────────────────────────────────────┐
│ 工具网关 │
│ allow / ask / deny;敏感路径;网络策略;资源上限 │
└──────┬───────────────────────┬───────────────┘
▼ ▼
┌──────────────┐ ┌──────────────────────┐
│ 沙箱执行器 │ │ 人工审批 / Review Gate │
│ 工作区隔离、超时 │ │ 高风险动作、最终 PR 审查 │
│ CPU/内存/网络限额│ └──────────────────────┘
└──────┬───────┘
▼
工具结果 / 测试日志 / diff → 回到 Agent 编排器
旁路:eval 平台持续跑代表性任务,卡住模型 / prompt / 工具策略升级
```
这张图的核心变化不是「多了几个服务」,而是结构变清楚了:
- **任务入口**定义目标、仓库、预算和权限档位。
- **Agent 编排器**决定走固定工作流还是自主循环。
- **上下文构建器**只给模型必要信息,并把项目规则和关键约束固定保留。
- **工具网关**把模型意图变成受控工具调用。
- **沙箱执行器**给命令物理边界,限制工作区、网络和资源。
- **trace / checkpoint**让长任务可恢复、可审计。
- **Review Gate**把不可逆动作和最终产物交还给人。
- **eval 平台**防止系统升级后质量无声退化。
### 跟一次「修失败测试并补回归」走到底
```
1. 工程师提交任务:「修复 billing 模块这个失败测试,并补一个回归测试」。
2. 任务入口记录仓库、分支、预算:最多 25 步、30 分钟、只能写工作区。
3. 上下文构建器加载项目规则、相关 AGENTS.md、测试命令、最近失败日志。
4. Agent 编排器先计划:定位失败 → 读相关文件 → 修改 → 跑单测 → 补回归。
5. 模型请求搜索代码。工具网关判断为只读低风险,自动放行。
6. 模型请求修改 `billing/refund.ts`。这是工作区内可逆写入,沙箱允许,先保存 checkpoint。
7. 模型请求运行 `pnpm test billing`。命令在沙箱中执行,带超时、CPU / 内存限制和网络禁用。
8. 测试失败,工具结果摘要进入上下文,原始日志以 trace 引用保留。
9. Agent 再读失败栈,发现缺少幂等键边界处理,继续打补丁。
10. 测试通过,Agent 生成最终 diff、解释、测试证据。
11. Review Gate 要求人 review diff;通过后才允许开 PR 或提交。
```
这里的关键点:
- 模型不是直接操作机器,它只是提出工具调用。
- 工具结果是观察,不是新指令;README、issue、测试日志都可能包含提示注入。
- 每次写入前有 checkpoint,最终 diff 可 review。
- 测试日志可以摘要进上下文,但原始 trace 要可追溯。
- 没有通过 review gate,Agent 不能把改动推到主干。
### 跟一次「长任务上下文快满」走到底
```
1. Agent 已经执行 40 步,读了很多文件,跑了多轮测试。
2. 上下文窗口接近上限,系统触发 compaction。
3. 压缩器把早期对话整理成结构化摘要:
- 用户目标
- 硬约束
- 已尝试方案
- 当前 diff
- 未解决问题
- 证据文件和 trace 链接
4. 系统从稳定存储重新加载项目规则和权限策略,而不是指望摘要记住一切。
5. 预算状态也被带回:还剩 8 步、10 分钟、不能联网。
6. Agent 继续执行;如果再次接近上限或预算耗尽,必须停下来交代状态,不能无限循环。
```
上下文压缩不是魔法。它只是把「装不下」变成「有纪律地丢掉低价值历史」。真正不能丢的东西,要进入稳定规则、检查点和 trace。
---
## 八、坏了怎么办:故障场景与兜底
| 故障 | 直接后果 | 检测方式 | 架构兜底 |
|---|---|---|---|
| 模型直接执行 shell | 误删、外联、泄密、越权 | 高危命令审计、越权尝试 | 所有工具调用先过权限网关和沙箱 |
| 工作区边界缺失 | 改到用户机器其他项目 | 文件写入路径审计 | 只允许指定 workspace 写入,工作区外 deny |
| 敏感路径可读 | `.env`、SSH key、云凭据被读出 | 敏感路径访问告警 | deny 读取敏感路径,必要时物理隔离凭据 |
| 网络默认放开 | 注入内容诱导外传代码或密钥 | 外联域名审计、异常 egress | 默认断网或 allowlist,高风险联网 ask |
| 工具结果被当系统指令 | README / issue 诱导 Agent 忽略规则 | 注入测试用例、异常工具链行为 | 外部内容标成不可信数据,不能覆盖系统规则 |
| 审批太多 | 用户疲劳盲批 | 批准耗时、连续批准率 | 低风险靠沙箱自动,高风险才问 |
| 审批太少 | 不可逆操作自动发生 | 高风险操作审计 | 外部副作用强制 ask / deny |
| 长任务无 checkpoint | 中断后重来,状态不一致 | 中断恢复失败率 | 持久化任务状态、diff、trace、预算 |
| 上下文压缩丢规则 | 后续步骤违反早期约束 | 失败复盘、压缩后违规率 | 压缩后重载项目规则,硬约束固定保留 |
| 子代理全量继承上下文 | 主线被中间噪声淹没 | 上下文占用、无关 token 比例 | 子代理隔离,只回灌摘要和证据 |
| 子代理写入冲突 | 多个子任务改同一片代码 | diff 冲突率 | 分配不重叠写入范围,主线统一合并 |
| 无预算上限 | 无限循环、烧 token、打爆测试环境 | 步数 / 成本异常 | 步数、时间、token、工具调用、并发上限 |
| 只看最终 diff | review 不知道为什么改 | review 退回率 | trace 记录计划、工具调用、测试证据 |
| 没有 eval | 模型升级后质量退化 | 线上失败、人工投诉 | 代表性任务 eval 接入发布门禁 |
| 测试命令无超时 | 某个任务长期占住 worker | worker 占用时间 | 命令超时、资源配额、任务取消 |
| 自动提交绕过 review | 错误代码进主干 | 未审 PR / commit | 最终提交、PR、部署必须过 Review Gate |
编码 Agent 的成熟度,不是看它能不能一次写出漂亮代码,而是看它在读错上下文、工具失败、注入诱导、任务中断、预算耗尽时,能不能停得住、恢复得了、解释得清、评测不过不上线。
---
## 📌 拿模板验证这次推演
本案例不是重写某个编码 Agent 产品模板,而是把「能动手的 AI」里最容易互相影响的几条链路放在一起推演。
| 可复用模板 / 章节 | 本案例复用什么 | 本案例重点补什么 |
|---|---|---|
| [AI Agent / 工作流平台](../../templates/ai-agent-platform/README.md) | 工作流 vs Agent、行动循环、工具、记忆、人类介入、trace | 把通用 Agent 落到代码仓库和真实 shell 副作用 |
| [OpenAI Codex](../../templates/codex/README.md) | 沙箱 × 审批双轴、工作区边界、云端异步任务、PR 交付 | 用教学案例解释为什么「能动多大」和「何时问人」要分开 |
| [Claude Code](../../templates/claude-code/README.md) | 上下文工程、权限层、OS 沙箱、子代理、hooks、compaction | 强调子代理隔离重活,以及外部内容不可信 |
| [OpenClaw](../../templates/openclaw/README.md) | 常驻 Agent、渠道入口、工具审批、自托管边界、记忆透明 | 提醒「单用户信任边界」不能直接当团队多租户平台 |
| [Hermes Agent](../../templates/hermes/README.md) | 长期记忆、技能沉淀、cron Agent 任务、可插拔子系统 | 补充长期 Agent 会遇到的记忆过时和技能漂移 |
| [23 · 规格即架构约束](../../tutorial/23-规格即架构约束怎么写给AI.md) | AGENTS.md / 规则 / CI 约束 | 把项目规则变成 Agent 每次都能读、机器能检查的边界 |
| [24 · 审查清单](../../tutorial/24-审查清单AI产出默认缺什么.md) | AI 默认漏掉安全、失败、边界 | 最终 diff 必须用 review checklist 把关 |
| [25 · 评测驱动](../../tutorial/25-评测驱动把够好写进架构.md) | eval 门禁 | 防止模型 / prompt / 工具策略升级后无声退化 |
> **读法建议**:先读本章,再回看 [AI Agent 平台模板](../../templates/ai-agent-platform/README.md)、[Codex 模板](../../templates/codex/README.md) 和 [Claude Code 模板](../../templates/claude-code/README.md)。你会更容易看懂:编码 Agent 的核心不是「模型更强」,而是「自主行动被工程边界包住」。
---
## 🎯 随堂检验
---
## 本案例小结
- **编码 Agent 不是聊天框,而是能改变仓库状态的执行系统。** 一旦能改文件、跑命令、联网,架构重点就从「回答质量」变成「受控执行」。
- **能用工作流就先用工作流。** 自主 Agent loop 适合路径不确定的任务;固定流程更便宜、更稳定、更容易审计。
- **工具调用必须过权限网关和沙箱。** 模型只提出意图,真正执行要由模型绕不过的层来决定 allow / ask / deny。
- **沙箱和审批是两根轴。** 沙箱管物理边界,审批管流程打断;两者解耦后,团队才能按场景组合自治程度。
- **长任务要靠 checkpoint、trace、compaction 和预算活下来。** 不保存状态、不限制步数、不记录证据,长任务迟早变成不可复盘的黑盒。
- **子代理用于隔离重活,不是默认炫技。** 只有搜索、日志、审查这类会挤爆主上下文的任务,才值得拆出去。
- **eval 是编码 Agent 的发布门禁。** 模型、prompt、工具策略升级前,必须用代表性任务验证成功率、安全拒绝、最小改动和回归稳定性。
> **第一期收束**:到这里,案例篇第一批 6 个核心案例完成了一轮闭环:从库存交易、多租户 SaaS、企业 RAG、实时协同、内容分发,走到能动手的编码 Agent。后续如果继续扩展案例篇,可以围绕行业纵深或专项技术栈再开第二批,而不是和这 6 篇重复。
---
## 相关链接
- 模板对照:[AI Agent / 工作流平台](../../templates/ai-agent-platform/README.md) · [OpenAI Codex](../../templates/codex/README.md) · [Claude Code](../../templates/claude-code/README.md) · [OpenClaw](../../templates/openclaw/README.md) · [Hermes Agent](../../templates/hermes/README.md)
- 方法论:[07 · 从 0 到 1 设计一个系统](../../tutorial/07-从0到1设计一个系统.md) · [08 · 架构决策记录与演进](../../tutorial/08-架构决策记录与演进.md) · [17 · 大模型时代的架构判断](../../tutorial/17-大模型时代的架构判断.md)
- AI 协同:[23 · 规格即架构约束](../../tutorial/23-规格即架构约束怎么写给AI.md) · [24 · 审查清单](../../tutorial/24-审查清单AI产出默认缺什么.md) · [25 · 评测驱动](../../tutorial/25-评测驱动把够好写进架构.md)