三周把编排式 Agent 接进交付流程:一份可信边界落地记录
一句话结论:能力早就够了,卡住我们的是「敢让它动多少」。把权限当成分阶段放开的开关,而不是一次性配置,整个落地过程就没出过事故。
一、起点:工具换了,工作方式没换
T 团队,9 人全栈,接一个内部数据平台。三周前的现状:
| 维度 | 现状 |
|---|---|
| 编码助手 | 6 人在用,主要做补全和解释 |
| Agent 能力 | 2 人试过自动改文件,跑飞一次后没人再用 |
| 外部资料 | 靠手动复制文档进对话 |
| 权限管理 | 客户端配置散在各人机器上,含明文密钥 |
| 诉求 | 让 Agent 承担一部分可验收的改动,但别再出事故 |
那次「跑飞」的复盘结论很直接:Agent 接到一句模糊需求,自己扩大了范围,改到清单外的文件,等发现时已经混在同一批改动里。问题不在模型不够聪明,在没人给它划边界。
二、主线:三件更新正好拼成一套方案
11 月中旬这一批工具更新,单独看是零散的 changelog,放一起看是一条完整链路:
- 编排模式:规划模型出方案并审查,快速模型写码跑测试,卡住时再交回规划模型。规划与执行分离,意味着贵模型可以只处理少量高价值 token。
- 终端侧信任门槛:不可信目录默认不加载项目级配置与 MCP,需要显式声明信任。CI 与共享目录因此不会被目录里一份配置悄悄劫持。
- 客户端确认与凭据注入:仓库级变更前二次确认;MCP 配置支持从标准输入读取,密钥不再进 shell history 或明文 JSON。
再加上一个本地抓取服务把外部网页转成干净文本,规划位要的资料也有了稳定来源。四篇内容其实是同一件事的四个切面:配置细节见 双模型编排配置指南,提示协议见本站提示词模块的「编排式三段提示协议」,抓取服务见本站 MCP 模块的「Firecrawl Local 实战」。
三、选型决策:不统一工具,统一契约
团队里 VS Code、终端派、JetBrains 都有,强行统一工具会先耗掉两周。最后决定:工具随便选,交接格式必须统一。
| 决策点 | 选择 | 理由 |
|---|---|---|
| 工具统一 | 不统一 | 迁移成本高于收益,各人用顺手的客户端 |
| 统一项 | 改动契约 + 验收条件 | 唯一跨工具、跨人可复用的东西 |
| 模型分工 | 中档编排 + 快速执行 | 规划贵但 token 少,执行便宜但量大 |
| 外部资料 | 本地抓取转干净文本 | 避免整页 HTML 进上下文 |
| 凭据 | 注入式,不落配置文件 | 配合客户端的 stdin 配置能力 |
改动契约固定四个字段:目标、改动清单、约束、验收条件。写不出三条验收条件的任务,不进 Agent 流程。字段定义和三段提示词见本站提示词模块的编排式三段协议。
四、三周时间线:权限按阶段放开
| 周次 | 放开的权限 | 准入条件 | 回滚方式 |
|---|---|---|---|
| 第 1 周 | 只读:读文件、检索、列目录、抓文档 | 目录白名单生效 | 关闭工具即可,无写入 |
| 第 2 周 | 单文件写入,且必须人工确认契约 | 契约含可判定验收条件 | Git 检查点回滚 |
| 第 3 周 | 跨文件改动,限白名单目录 | 前两周返工率低于阈值 | 按契约逐条对照回退 |
三个关键设计:
- 只读周不是走过场。整整一周让 Agent 只读,团队借此摸清它读资料的习惯、会抓哪些无关文件、上下文怎么膨胀。第 2 周放开写入时,系统提示和拼接顺序已经调稳了。
- 契约必须人工过一眼。第 2 周起,规划位输出契约后由人确认才放行执行位。这是全流程唯一的人工点,成本最低。
- 验收位不许用便宜模型。最后一道闸交给执行位自己验,等于没验。
五、可信边界怎么落地
权限不是一句「小心点」,是四条可检查的规则:
- 目录白名单:只挂需要改的仓库目录,主目录、密钥目录、部署配置一律不挂。
- 不可信目录显式信任:CI 与共享工作区沿用客户端默认的收窄策略,需要项目级 MCP 时显式声明,不靠全局开关。
- 凭据注入:密钥从明文 JSON 迁到环境变量 / 标准输入注入,仓库里不再有任何可提交的密钥文件。
- 仓库级变更二次确认:涉及安装应用、覆盖文件、退出工作区这类动作,保留客户端的确认提示,不为了少点几次把它关掉。
有一条经验值得单独写:每少一次确认,省下的是几秒;每漏一次边界,赔进去的是半天。 团队第 2 周曾有人把确认关掉图快,结果一次覆盖丢了未提交的改动,之后这条被写进准入清单。
六、结果(三周实测)
| 指标 | 接入前 | 三周后 |
|---|---|---|
| 日均活跃使用 | 6/9 人 | 7/9 人 |
| AI 参与改动的 PR 占比 | 约 6% | 44% |
| 改动返工率 | 19% | 8% |
| 单 PR 平均评审时长 | 42 分钟 | 31 分钟 |
| 月模型支出 | ¥120 左右 | ¥386 |
| 外部资料准备耗时 | 人均每天约 25 分钟 | 约 6 分钟 |
成本涨了三倍多,但结构变了:以前主要花在补全,现在主要花在编排位的规划与验收。团队算过一笔账,评审时长下降与返工率下降省下的人工,远超多出来的模型支出。
还有个没预期的收获:契约本身成了 PR 描述。评审人不用再从 diff 里反推「你到底想干什么」,直接对照验收条件看就行。
七、五条踩坑记录
- 一次抓整站,上下文直接爆掉。改成先列链接清单、按标题挑页,再取正文片段。
- 每轮把时间戳拼进系统提示,缓存全不命中。固定系统提示文本、历史按顺序追加后,同一会话的缓存输入占比才上来。
- 验收条件写成「代码更清晰」,验收位只能含糊放行。改成绑定可观察对象:某测试通过、某签名未变。
- CI 升级后项目级 MCP 静默失效。根因是新版本对不可信目录默认收窄,显式声明信任后恢复。这条最容易被误判成「工具坏了」。
- 把执行位的解释一起喂给验收位。模型开始被解释带偏,改成只给契约和 diff,判定立刻稳定。
八、准入清单(可直接复制)
- 目录白名单已配置,敏感目录未挂载
- 不可信目录保持默认收窄,需要时显式信任
- 凭据全部注入,仓库内无明文密钥
- 仓库级变更确认提示保持开启
- 改动契约四字段齐全,验收条件可判定
- 规划位输出不含代码块
- 执行位 diff 可逐条对应清单
- 验收位与规划位同档模型
- 系统提示固定,不在每轮拼接动态内容
- 每个阶段有 Git 检查点可回滚
- 有明确的阶段升级阈值(如返工率)
相关阅读
- 编排模型的分工配置:双模型编排配置指南
- 客户端自动批准与检查点:Cline 接入指南
- 终端侧 Agent 工作流:OpenCode 接入