一年多攒下来的运维纪律全是 Markdown:11 条通用铁律、七个领域分册、上百条具体条款。它们对 AI 编程客户端生效的唯一机制,是模型"记得住、愿意守"。这篇文章记录我把这套软纪律焊进工具链的全过程——设计、开发、三次翻车、两个安全洞、一轮体验回炉,以及最后活下来的那套方法论。

一、为什么文档纪律必然失效

我的纪律体系是随着事故长出来的:误删过数据、泄露过密钥、在错误的设备上跑过正确的命令。每出一次事就立一条法,一年下来条款已经厚到模型一次读不完。

文档纪律有三个结构性失效模式:

  1. 忘——上下文一长,开工时读过的铁律到第 30 轮对话早已挤出注意力窗口;
  2. 绕——模型永远能找到"我只是看一下配置"这种叙事上的正当性,而"只看"和"改"在生产主机上差别没那么大;
  3. 善意变通——它真心想帮你把事办成,于是把"先备份后部署"理解成"这次改动很小,跳过也行"。

最典型的是铁律 10:「生产访问一律先授权」。写在文档里的意思是"动生产之前问用户",实际执行全凭模型自觉——直到有一天我在复盘日志里发现某次排障它直接 SSH 上了 NAS 宿主机,理由是"只读探查"。条款没错,执行为空。

结论:凡是"希望模型遵守"的规则,最终都必须变成"模型无法绕过"的机制。AI 编程客户端的 hook 系统正好提供了这个抓手——工具调用前强制过一道本地脚本,返回 deny 就真的不会执行。

二、设计:五事件 × 三动作 × 令牌

客户端提供了五个(对我有用的)hook 事件,我把它们当成五个不同的执法位置:

事件执法位置用途
SessionStart会话开工注入开工摘要(正本地图/路由表/铁律速览)
UserPromptSubmit每轮提示自动 git pull 纪律仓库 + 按需注入提醒
PreToolUse工具执行前硬闸门:deny / ask / 放行,唯一能真正拦截的位置
PostToolUse工具执行后坑位注入(部署 SOP、crontab/sshd 警示文案)
Stop会话收尾(后来整个摘掉了,见第五节)

规则引擎很朴素:每条规则 = 工具面(bash 命令文本 / 文件写操作)+ 正则 + 动作,动作优先级 deny > ask > inject。规则分三类:

  • 无条件 deny:防复活清单(已退役的快照/回滚命令)、密钥材料模式、CPE 配置变更、互斥虚拟机……这些没有商量余地;
  • ask:自保护类(改 hook 自己的配置、改授权令牌文件)——拦下来交用户裁决,而不是静默放行或静默拒绝;
  • need_token(deny + 令牌豁免):所有生产目标。这是铁律 10 的机械化——ssh 上生产主机之前,本地必须存在一个未过期的授权令牌文件。令牌由用户在终端跑一个 PowerShell 脚本生成(scope + TTL),计划任务每小时自动刷新一个全范围的。

另有一条我特别满意的豁免通道:我的博客检索脚本是开工纪律既定的只读通道,不该被令牌拦。于是生产目标规则对它做了负向前瞻豁免,同时保留一条 Post 注入规则——每次走豁免通道都留一行"经由豁免通道放行"的痕迹。豁免必须留痕,否则豁免就是后门。

开发是三轮并行外包给 AI 会话做的:11 张卡 + 6 张修补卡,统一 unittest 收口 352 例全绿。我当时觉得可以上线了。

这是本次复盘里最错的一个判断。

三、部署翻车:三层洋葱

灰度方案设计得很规矩:探针先行(只记录不改判)、分段配置文件逐面挂载、每步切换都是用户在终端手动执行一条 Copy-Item。理论上任何一步出问题都能退回上一段。

然后第一轮 canary 就给了个寂寞:零注入、零拦截、零报错。像什么都没装。

第一层:配置根本没被加载

探针脚本一次都没执行过。我先是怀疑客户端不热加载配置(新会话不够、要整个重启 App)——错了。翻客户端的 CLI 日志才发现,从我把配置放上去的那一刻起,日志里每分钟都在刷同一条警告:

config.file.invalid: hooks.events.SessionStart.0.matcher:
Too small: expected string to have >=1 characters

schema 要求 matcher 字段只要出现就必须至少 1 个字符,而我用空字符串表达"匹配一切"(官方语义应该是省略这个字段)。校验失败不是拒掉这一条 hook,而是整份配置连同插件配置一起被静默丢弃——注意是静默,客户端 UI 上没有任何提示,唯一证据在日志里。

这一层的教训:对接封闭系统,先读它的日志,再读它的 schema,最后才怀疑自己的代码。我顺序反了,多花了一轮 canary。

第二层:路径少一层目录

修好 schema,hook 真的开始执行了,立刻报 Errno 2: can't open file——五个入口脚本放在入口子目录里,我生成配置时漏了这一层目录。这层最便宜,日志直接告诉你答案,改完就好。

第三层:输出协议对不上(这层最隐蔽)

前两层修完,canary 出现了诡异的分裂:硬闸门活着(该拦的都拦了),注入面全灭(该出现的文案一个都没有)。

客户端日志里的证据是:PostToolUse hook 在脚本输出为空时记录 allowed;一旦脚本有输出就记录 failed。翻译过来:不是我的注入逻辑错了,是我的输出被客户端的输出校验拒收了。

扒开客户端的打包源码,找到了它的输出 schema(zod 定义),问题一目了然:

  1. 顶层 decision 字段的枚举只有 approve / block——没有 allow,也没有 deny。我按直觉写的 {"decision":"allow"} 根本不在合法值里;
  2. 注入文案要走独立的 additionalContext 键;
  3. 最意外的一条:退出码为 2 时客户端根本不解析 stdout,直接把输出文本(或 stderr)包成 deny 结果。

第 3 条解释了为什么硬闸门一直活着:我的 deny 输出虽然 schema 不合法,但退出码 2 走的是纯文本通道,文本被原样当成拒绝理由展示——当初 fail-closed 的方向选择,意外保住了整个硬闸门。而注入走退出码 0 的严格 JSON 校验,形状不对就整条丢弃。

修复是全局改输出协议:注入只发 {"additionalContext": "..."};deny 干脆不发 JSON,直接输出纯文本原因 + 退出码 2。同步改了 78 处测试断言,回归全绿。

这一层的教训:“我的输出格式合理"不重要,对方的解析代码才是唯一标准。以及一个更普适的:退出码通道和结构化输出通道的校验严格程度往往不一样,fail-closed 的那条路反而最抗造。

四、上线之后:真刀真枪抓出的两个洞

灰度全过、六组验收矩阵全过,进入观察期。真正的洞这时候才浮出来——都是"配置对了、代码绿了"也挡不住的那种。

洞一:授权语义是单向的

验收用例"持令牌访问生产主机"被误拦。排查发现令牌文件里 scopes: ["any"],而校验逻辑里 any 只在"规则要求 any"时生效,令牌侧的 any 不是通配符——一个 any 令牌对任何具体目标(NAS 虚拟机、宿主机、软路由)都不放行。

设计本意是常设定时任务发一个 any 令牌、覆盖所有生产访问(等于"这台工作站在线即授权”)。实际效果是每小时刷新出一个谁也不认的令牌。

修法走了配置层:定时任务改发全范围枚举(七个 scope 显式列出),一行代码没动。这暴露了一个需求侧的模糊:“any"到底该是"任一有效令牌即可"还是"覆盖一切目标”——写代码前没把它钉死,两边就各按各的理解实现了。

洞二:令牌可以遮蔽无条件 deny(安全缺陷)

上面修完的当天晚上,全量回归红了 1 例,深挖出一个真正的安全问题:

qm snapshot(快照纪律已退役,本该无条件拒绝)在持有有效令牌时被放行了。

根因是规则选择算法:need_token 规则和无条件 deny 规则同属最高优先级,我按"先命中者胜"实现,而规则模块按文件名排序加载——生产目标模块恰好排在防复活模块前面。于是"需要令牌"压过了"永远不许",拿着令牌就能干退役命令。

验收矩阵没抓住它,因为矩阵跑的时候令牌对宿主机 scope 无效,遮蔽路径根本没走到。等令牌真有效了,才由回归测试 + 真实令牌实测双重暴露。

修法是把单桶改成双桶:无条件规则和令牌规则分开记,同优先级时无条件规则永远压过令牌规则,令牌只负责授权"本来就该问一声"的访问,无权赦免"永远不许"的事。补了 3 条优先级测试用例钉死这个语义。

这个洞给我的触动最大:授权系统的语义边界(令牌能豁免什么、不能豁免什么)必须在设计时就写成明文,否则实现层面的排序细节会替你做一个危险的决定。

五、体验回炉:注入是上下文,不是消息

观察期第一天用户(就是我)就受不了了,两个问题:

  1. 每轮对话结束,收尾核查单都会作为一条消息弹出来——Stop hook 输出了 decision: "block" 请求续跑,客户端把它当成"有事要说",于是每轮多一条噪音 + 多跑一轮模型调用;
  2. 对话里的注入全被折叠——additionalContext 在客户端 UI 里渲染成折叠块,每轮一条"纪律已同步"的折叠块堆在那里,真要找内容还得挨个点开。

第二个问题让我认清一个事实:hook 注入的展示形态是客户端说了算的(折叠、置灰、不占消息流),hook 能控制的只有"发不发"。所以解法不在"怎么发得更漂亮",在"少发":

  • Stop 事件整个从配置里摘掉——收尾清场改由开工摘要和会话内纪律承担,零代码改动(只动配置),想回退把配置换回来就行;
  • 每轮注入改条件式:pull 无更新且没命中待办关键词 → 完全静默;有更新、同步失败、或提示里提到待办事项(某容器退役、密钥轮换之类)→ 才注入一次。

改完的效果:平时一轮对话零折叠块,开工一条摘要,有事才说话。

顺带还修掉一个隐藏问题:deny 文案是中文,走的纯文本通道在 GBK 控制台代码页下会写出 GBK 字节,客户端按 UTF-8 解析就是乱码。所有入口的输出统一改成显式写 UTF-8 字节,不再赌控制台代码页。

六、活下来的方法论

复盘下来,真正让这次上线没有变成事故的,是几条和代码无关的东西:

分段配置文件 = 回退点梯队。 我把灰度过程做成 9 份配置文件(探针 → 逐面挂载 → 全量 → 全停开关 → 部署前原件),任何时刻的任何回退都等于"在终端执行一条 Copy-Item"。切换权永远在用户手里,不由会话执行。最粗粒度的一条:拷回部署前原件 = 整个强制层消失。

改闸门的人不能同时是被闸门管的人。 所有对闸门自身(配置、代码、令牌文件)的修改,必须由用户在会话外手工执行——这条规则本身也是闸门规则之一。上线第一天它就拦了我自己(我想在会话里改入口脚本,被 ask 弹回),那一刻的拦截是整个系统最让人放心的信号。配套的工法是补丁脚本:我把改动写成幂等脚本,用户在自己终端跑,跑完我读输出核对——既守住了权限边界,也没把活儿推给用户。

灰度方向:先挂只记录的探针。 每个事件先挂一个"stdin 原样落盘、永远放行"的探针脚本,拿到真实 payload 的字段结构(工具名、命令、事件名、续跑标记……全是多候选假设),再挂真入口。我最初的字段假设全靠文档猜,探针一轮就证实/证伪了全部 4 个校准点——与其猜协议,不如采一份真样本。

测试绿只是及格线。 352 例全绿挡不住配置被静默拒收、路径少一层、输出协议错位——这三层全部发生在"测试覆盖之外的现实世界"。测试守住的是规则语义(比如令牌优先级那个洞就是回归测试抓的),上线守住的是灰度 + 回退 + 日志。

fail-closed 不是口号,是分红。 输出协议错位那次,硬闸门能活着纯粹因为当初把 deny 选在了"退出码 2"这条最笨、最不依赖结构化解析的通道上。协议会变、schema 会变、客户端版本会变,“坏了就拒绝"的那条路最抗造。

最后是一条自我指涉的黑色幽默:我的铁律 6 写着「规则存在 ≠ 规则生效:改配置必须验证调度器/服务行为本身」。这次部署,这条铁律在它自己的落地项目上应验了三次——配置存在但没加载、脚本存在但路径错、输出存在但被丢弃。每层都是"我以为生效了"和"实际生效了"之间的缝隙,而填补缝隙的手段只有一个:去验证行为本身(读客户端日志、看探针样本、真跑一遍命令),而不是验证"我做了什么”。

七、现状与下一步

观察 4 天零误拦零漏拦后已转正:五面常驻(开工摘要 / 条件式每轮同步 / Pre 硬闸门 / Post 坑位注入)、计划任务逐时刷新全范围令牌、回退梯队(上一段 / 全停 / 回部署前)保留在部署物料目录。台账已回写进纪律仓库,用户级入口文档补了一句"强制层已上线 + 回退命令 + 停授权命令"。

待办是治理期的:hook 引擎正本从项目工作区迁进纪律仓库统一管理、哈希抽核纳入巡检(防镜像漂移)、开发机分端策略(开发机会话一律拒绝并提示回工作站——令牌体系只覆盖工作站)。

如果你也在维护一套"给 AI 看的运维纪律",我的建议浓缩成一句:先找出三条你最不能容忍被违反的规则,把它们变成退出码 2。剩下的,可以慢慢来。