mutation-gate

RHDH 写入门禁

外部写入是指用户无法通过关闭会话来撤销的任何操作：推送提交、创建拉取请求、转换 Jira 状态、发布消息、修改他人仓库中的文件。

读取不属于写入。获取、分类处理、分析或报告的请求都属于读取意图，不代表批准任何操作。

门禁

1. 说明操作。 按执行顺序列出即将执行的每项操作。对于每项操作，提供以下信息：

字段	内容
目标	要更改的确切对象：owner/repo#412、RHIDP-1234、分支名称或频道
命令	实际执行的确切命令或请求，不得改述
预览	将要提交的正文、标签、字段值或差异
前置条件	必须已满足的条件。执行前立即检查；若不满足，则停止这一批操作
失败时	如果此操作失败，后续操作将如何处理
恢复	此操作执行后，如何撤销或控制影响

请在对话中以表格形式呈现。用户在当前所在位置批准，因此计划应直接发给用户，而不是写入文件。

恢复措施不可省略，也不同于失败处理。 失败处理说明尚未执行的操作将如何处理。恢复措施说明已执行的操作应如何处理。请求批准前就要写明恢复措施：如果无法说明如何撤销某项操作，用户就是在盲目批准。当确实无法撤销时——例如已发布的消息、已触发的流水线、已发布的软件包——请明确写出这些话。“无法撤销；消息会保留”就是完整且有用的恢复说明。不能保持沉默。

如果计划太长，无法在对话记录中阅读——例如涉及多个仓库的版本更新，或影响数十个文件的目录变更——则按照 /handoff 的约定，将计划写入操作系统的临时目录，并打印绝对路径。不要将其写入用户的检出目录，以免它被提交。

2. 就所述操作集征求批准。 用户批准的是他们看到的内容。先前表达过发布意图，并不代表授权执行尚未展示确切目标和载荷的操作。如果计划在获批后发生变化——目标不同、增加操作或编辑正文——这就是新计划，需要重新获得批准。

3. 执行，然后报告每项操作。 按计划顺序逐项报告已完成、失败或已跳过的操作。因前一项操作失败而未执行的操作，应报告为已跳过，不得省略。写入失败时必须报告，不得悄悄以其他形式重试。

凭据不得出现在预览中

预览会显示实际执行的命令，因此可能包含粘贴的令牌、从环境中插入的令牌，或由工具返回的令牌。展示前请先扫描：

uv run scripts/scan_credentials.py <plan.json> --json
uv run scripts/scan_credentials.py --text "<a single command or body>"

如果发现形似凭据的字段或值——例如授权标头、PEM 私钥、ghp_、glpat-、xox、sk- 或 AKIA 令牌，或任意深度下名称类似 secret 的字段——该命令会以非零状态退出，并指出违规路径。它会报告字段，而不会泄露密钥。

计划中的凭据说明命令的构造方式有问题，不是可以遮盖后继续的内容。请修正构造方式，让已认证的工具在运行时提供密钥。

谁来执行

由负责目标的技能执行操作。需要写入 Jira 的调用方应调用 /rhdh-jira-update；需要写入代码托管平台的调用方则自行构造并运行命令。/rhdh-forge 负责构造代码托管平台载荷，但绝不执行它们——这种分离正是此门禁得以强制执行的关键，因为知道如何构造命令的模块无法运行它。

完成

当用户批准的每项操作都有结果、结果顺序与计划一致，且每项结果都注明目标时，流程才算完成。报告中遗漏某项操作，或报告未注明其更改的目标，都意味着门禁尚未闭合。