Appearance
第 22 章 上线准备
本章要解决的问题
评估通过(第 21 章)只是拿到了发布资格。把 Agent 交到真实用户手里,还要补齐交互、配置、协作边界和发布流程;任何一项缺失,都会变成具体事故。
本章内容多数在四个参考实现里能找到对应物;发布流程一节则把它们和第 21 章的评估串成一条线。
这五项不是一份互不相关的功能清单。它们分别回答从“谁在用”到“怎样安全发出去”的五个交付问题：
| 交付问题 | 不明确会造成什么 | 对应机制 |
|---|---|---|
| 用户在哪里操作 Agent | 审批、diff、取消没有合适的交互位置 | 22.1 交互形态 |
| 不同环境怎样得到一致行为 | 同一仓库换台机器就表现不同 | 22.2 配置体系 |
| Agent 能否改变协作历史 | 检查点污染分支，或未授权写入远端 | 22.3 git 纪律 |
| 哪些任务由哪个模型执行 | 路由没有数据支撑，成本上升却不提质 | 22.4 模型路由 |
| 行为变更怎样灰度与撤回 | 出问题时不知道发了什么，也无法回滚 | 22.5～22.6 发布流程与清单 |
22.1 交互形态:终端还是浏览器
四个参考实现给出三类答案:codex 主打终端 TUI(+ headless 模式做 CI/脚本);grok 同为 TUI(+ ACP 协议嵌编辑器);dsh 反其道,主打 Web UI(浏览器是它的第一公民,CLI 主要负责启动);pi 则同时提供 TUI、print/JSON、RPC 和可嵌入 SDK。
三种形态对应三类用户,没有优劣。但要看到形态换来的东西:dsh 用 Web 形态换来了审批 UI、diff 卡片这类富交互的天然优势——第 9 章的审批请求、第 7 章的三种 diff(预览/提交/净变化)都长在 Web 上;终端形态则换来无处不在(SSH 里也能跑)和可脚本化。第 20 章讲的是形态之下的运行时与事件协议,这里先选形态。
22.2 配置体系:多级配置与 Schema
多级配置(用户级 / 项目级 / 命令行)是常见做法——没有它,同一个仓库在不同成员的机器上行为不一致,问题会以"在我机器上是好的"的形态反复出现。三家值得看的做法:codex 为配置生成 JSON Schema(可由程序校验的数据结构说明),配置写错可以尽早暴露;配置即清单的思路在 dsh 走得更远——它的配置是 YAML 插件清单(第 17 章),配置、能力和装配是同一份东西;pi 则把用户级与项目级设置分别放在 JSON 文件中,项目设置要经过信任检查才加载。
自建时的最小要求:至少两级(用户级 + 项目级),每项配置有默认值和类型检查,配置变更写进日志——它和系统提示词、工具 schema 一样,都是影响 Agent 行为的"代码"。
22.3 git 纪律:何时提交、怎么写信息、哪些禁止
Agent 改了代码,就要回答 git 的三个问题。生产约定:
text
何时提交 默认:不主动提交——用户明确要求才 commit(codex 的默认指令同时禁止
未经要求创建新分支,防止 Agent 替用户决定历史结构)。
例外:隔离的会话分支可以承担内部检查点——grok 在 conv/* 会话分支上
做"turn 结束若有脏文件就 add -A + commit"(--no-verify、禁 gpgsign、
有进行中 git 操作则跳过),不直接改用户原来的工作分支。
提交信息 LLM 从 diff 生成的总结,但结构上应是"建议+待确认",而非直接执行;
push 是否需要确认由权限策略决定;高风险远端和保护分支必须拦截。
禁止操作 强推、改历史、动保护分支、`git config` 全局篡改——第 9 章的
危险命令特判里有专门针对 git 危险 flag 的拦截。设计原则:git 的 commit/push 会改变协作历史或远端状态,应按第 9 章的授权与风险规则处理;内部检查点(第 7 章的文件快照、grok 的会话分支提交)则用于失败后恢复到旧状态。两者必须分开——混在一起,要么检查点污染用户历史,要么该恢复的时候没有恢复点。
22.4 模型路由:先统一,再有数据地分化
Agent 可以由运行程序按任务难度选择模型:
text
简单确定性任务(格式转换、读文件总结、生成 commit message)→ 小/快/便宜模型
复杂推理(根因定位、架构改动、跨文件重构) → 强模型/思考模型两个生产实现给出了不同佐证:codex 的 spawn_agent 指引明确"子 Agent 默认继承当前模型,除非用户明确要求否则别设 model"——模型选择是显式决策,不是随手参数;dsh 允许插件依次处理 agent/request,按任务改写 provider/model,且每次变更记为 request/header 事件。模型切换会断开原有缓存(第 19 章排查表第 3 条),这是路由最直接的代价。
是否启用更长思考也属于模型选择,但不能靠"探索关、定案开"这类直觉写死;应按任务标签在第 21 章的评估集里实测质量、延迟与成本。
给自建 Agent 的起步策略:先不要自动选模型——先全用一档模型把功能跑通,等 token 计量与运行指标(第 19 章)告诉你"哪类调用最贵且最简单",再只把那一类换成更便宜的模型。自动选择本身也增加复杂度,要有数据再做。
22.5 发布:什么在发布,怎样灰度与回滚
先想清楚"发布的内容是什么"。对一套 Agent 来说,提示词、工具 schema、Skill、记忆格式和评分规则都是发布内容——它们和二进制一样会改变行为,却不走传统的构建流水线,这是 Agent 产品和传统软件在发布上最大的不同。把"线上可随意改的字符串"当成发布单元,出了问题连"回滚到哪个版本"都答不出来。
发布流程接在第 21 章的评估之后:
text
回归集通过(CI 门禁)
→ 留出测试集复跑(没参与调优的那份)
→ 只改一个变量做对照(一次失败记录只产生一份待验证改动)
→ 线上小流量试运行(少量真实流量 + 安全限制 + 快速回滚)
→ 目标指标 + 安全指标达标 → 全量;否则回滚两条容易漏的纪律:发布前先确认起始环境和检查程序没变——有时分数变化不是 Agent 变了,是题或环境变了;线上任务记录默认不全量收集敏感正文,保存脱敏字段、哈希和证据引用即可(第 19 章的三条记录流)。
22.6 上线检查清单
把本章和前面各章的上线相关结论收进一张清单,发布前逐项过:
text
□ 交互形态确定,审批与取消在该形态下可用(第 9、20 章)
□ 配置至少两级、有类型检查,配置变更入日志
□ git 纪律成文:不主动提交、push 按权限策略处理、检查点与用户工作分支分离
□ 模型路由策略明确:先统一一档,有数据再分化;换模型记录为显式事件
□ 提示词/工具/Skill/评分规则全部版本化,回滚目标明确
□ 回归集接 CI,门禁生效(第 21 章)
□ 三条记录流(会话可信记录/运行指标/安全审计)分开保存(第 19 章)
□ 预算与停止条件:轮数、token、费用上限生效(第 4、19 章)【对比小结】
| codex | grok-build | dsh | pi | |
|---|---|---|---|---|
| 交互形态 | TUI + headless | TUI + ACP 嵌编辑器 | Web UI 第一公民 | TUI + print/JSON/RPC + SDK |
| 配置 | 多级 + JSON Schema | profile + 规则 | YAML 插件清单即配置 | 用户级/项目级 JSON 设置 + 环境变量 |
| git 检查点 | 无(ghost snapshot 已移除) | conv/* 隔离的会话分支 | 无 | 无(会话树 ≠ 文件备份) |
| 模型路由 | 子 Agent 默认继承 | 任务级选择 | 插件改写 provider/model | 会话级指定 |
| 发布单元 | 版本发布 | 版本发布 | 插件/bundle 版本化 | npm 包 + 扩展版本化 |
共同点比差异更重要:面向用户的 git 历史和远端操作都需要清楚的授权边界;提示词、工具和配置也要能随版本追踪。分歧只在发布单元的形态——这取决于你的产品以什么为单位演进。
到这里,本册的主线走完:从一次 LLM 请求和一条 while 循环,到骨架六章,再到高级部分的压缩、渐进加载、会话恢复、长任务、记忆、协作、扩展、可靠性与界面,最后以评估和上线收束。深入的源码精读入口见附录 B;四个参考实现仍在快速演进,机制会变,取舍的逻辑不会。