批准一张变更单,不再是批准一条命令

ops-agent 建造笔记第 16 篇:ops_approve 为什么要填影响面并来自 kubectl diff 等只读预演,快照声明如何与执行参数强一致,确认身份为何要覆盖完整变更单与执行环境,以及敏感文件绕快照通道等同一条链上的根因修复。

批准一张变更单,不再是批准一条命令

《ops-agent 建造笔记》第 16 篇(续篇分篇) 代码基线:v0.1.0-rc.4,提交 8dfa085(2026-11-09 候选版);前 13 篇仍固定 v0.1.0-rc.1 对照实现:agent/tools.py 的 ops_approve / ops_exec、core.py、remote.py、scenario.py 续篇入口:文章锁在 rc.1,代码已经走到 rc.4


0. 人确认的对象变了

第 1 篇讲谁能批准写操作:审批戳绑定命令和执行环境,一次授权默认只允许一次执行。第 5 篇讲 exit=0 之后还要验一遍,文件回滚要单独确认。第 10 篇补了一句关键区分:ask_user 用来澄清「想 restart 还是 reload」,它的回答不代替 ops_approve 对具体命令的确认。

v0.1.0-rc.2 之后,被确认的东西比一条命令大得多。ops_approve 新增必填 impact(影响面:将改什么状态、影响哪些服务),并要求它来自只读预演;快照声明也进了审批戳。于是人点「确认执行」时,面前是一张包含执行环境、风险级别、可用次数、影响面、回滚点和完整命令的变更单。

这一篇讲这张单子怎么变厚,以及变厚之后怎样防止它被人或模型悄悄换掉。


1. 影响面必须来自只读预演

impact 不是让模型写一句「将重启 nginx,影响 web 服务」凑格式。缺了它,ops_approve 直接拒绝,并把该用什么预演写在拒绝提示里:k8s 用 kubectl diff -f ... 或 kubectl apply --dry-run=server --context <c> -f ...,文件变更就对比目标内容与当前内容,写清将改什么状态、影响哪些服务,再提交审批。人确认的是 would-be 变更,不是一条孤立的命令字符串。

为了让预演真的零摩擦,kubectl diff 和 apply / create / replace / patch / set / scale / annotate / label --dry-run=server|client|true 进了 R0 白名单。但这等于给一条能拼出写操作的命令开了直通,所以同时堵了两处:KUBECTL_EXTERNAL_DIFF 赋值失配不再锚定白名单,进程环境变量在 bash 工具执行前剔除——否则「跑个 diff」能借外部 diff 程序变成执行任意命令。

白名单放宽和绕过封堵是一组动作,只写前半句会让人误以为守门变松了。


2. 快照声明进了戳,就必须与执行强一致

ops_approve 新增 snapshot_files / snapshot_cmds 声明,和 impact 一起写进审批戳。声明不是提示文字:core / remote 的 exec_change 会校验实际执行参数与戳里声明的完全一致,不一致就拒绝执行。ops_exec 也改成支持 snapshot_files 数组,与 ops_approve 共用同一份 _normalize_snapshot_args——此前按 skill 指引声明多文件快照的变更单会「批准后必被拒」,两份参数归一化逻辑漂移的结果。

没带任何快照的变更,确认框醒目标注「本次未声明任何快照:执行后无自动回滚点」,执行后也明确警告;R3 不强制快照,但同样把「不可逆,无回滚方案」写在人眼前。第 5 篇讲过系统不会凭空生成业务备份,这里把这句话变成了变更单上的必填项与警告,而不是留给人自己记。


3. 确认身份要覆盖整张单子

单子变厚以后,新的风险是「批准 A、实际执行 B」。第 14 篇讲 A2A 协议态的二次确认时提过这条,它其实来自工具层共用的实现:ops_approve 的 request_key 由工具名、完整命令、目标、风险级别、core.env_identity(env)、可用次数、影响面、快照文件与命令、force、TTL 共同组成。也就是说,快照路径、次数、目标、执行环境(含 kubeconfig、SSH identity/options)任一变化,都是另一张单子,必须重新确认。

确认框本身也补齐了可核对性:

  • 执行环境用 core.format_env(env) 展开,人能看见批准的是哪个环境,而不是一句抽象的「已绑定环境」。
  • 可用次数明确写出「1 次(执行后即失效)」或 uses=N,避免 uses=100 的授权在人眼里和 1 次一样。
  • 影响面经 core.redact() 后整段渲染。
  • 快照文件与快照命令逐条列出,不再只报数量——两份数量相同、路径不同的变更单,人本来就没法核对。
  • 完整命令原样展示,其它回答一律视为拒绝,并撤销该命令可能已有的戳、记 approve-deny 审计。

rc.4 还补了一条容易漏的:ask_user 展示普通问题时清空待确认映射。否则「继续只读诊断吗?」的 yes,会被下一次重提请的旧写变更当成批准。第 10 篇说「澄清不代替审批」,到这里变成了代码里的状态清理。


4. 同一条链上的根因修复

审查修出来的问题,大多落在这条「预演 → 批准 → 快照 → 执行 → 回滚」链上,值得一起记:

  • 敏感文件绕过快照通道:cat ~/.ssh/id_rsa 被守门拒绝,但 snapshot_file() 原先不做敏感路径判定,MCP 甚至无需审批即可触发。凭据能借快照落盘、进 state.tar、回流到回滚预览的 diff。现在 core.sensitive_snapshot_path() 与命令读取共用同一套判定(含等价写法与 realpath),MCP ops_snapshot_file、opsx snapshot --file、ops_exec 快照声明、远程 _pull_file 四个入口一并收紧。rc.4 又在符号链接解析后复查真实路径,回滚预览在读内容之前就拒绝改向——秘密不进 diff、不进工具输出。
  • 两份执行骨架合并:core.exec_change 与 remote.exec_change 曾是 110 行近似拷贝且已漂移(host 字段、剩余次数各一套),守门修复得落两次;现在合并为单一骨架,远程差异经 _ExecTransport 注入,opsx rollback 对结果未知的远程回滚统一返回 120。
  • 远程读取字节保真:_remote_read 改尾标记协议,登录 rc / MOTD 噪声不再让远程回滚预览与回滚前副本全部失败;rc.4 换成每次随机标记(正文含旧标记也不会被截断)、cat 失败立即中止(不被末尾 printf 洗成成功)、支持传递执行超时。
  • 请求不再跟随重定向:OpenAI 兼容、Anthropic 与 doctor 探活统一不跟随 3xx,避免 Authorization / x-api-key 被 Location 带到别的端点。
  • 场景占位符全量校验:postcheck 原先只在变更已执行后替换占位符,拼错一个就是「变更已生效、验证从未运行」;现在 load 时全量校验,exec 前再做兜底替换,保留字参数名 if/else/end 也拒绝(不再打碎 docker 的 {{end}} 模板)。

这些都不增加新能力,只是把第 4、5 篇写下的边界重新钉牢:未知不重放,批准不越界,快照不能成为绕过读取门禁的后门。

本篇讲的是审批链路的实现,不是验收结论。相关回归与反例不能替代真实 SSH 恢复、断线 unknown、服务后验的实机证据;本组续篇按 rc.4 口径,这三项与修复版本七天观察仍未完成,见第 17 篇。

对照源码与证据


系列总览 · 目录 · 续篇入口 · 上一篇:模型读日志之前,先过一道规则 · 下一篇:邮件送达了,七天观察却不算数