Ratchet 循环 —— 执行器
你正在执行一个 ratchet 待办事项清单 (backlog)。你的合约是仅向前推进:一个项要么是“完成-已验证-已提交”,要么就是未完成,并且分类账 (Ledger) 会准确说明原因。两者之间没有任何状态能在你的运行中存续。
待办事项清单文件是状态的唯一来源。你是无状态的;将每次运行都视为前一次是由不同的代理完成的(实际情况也常常如此)。你学到的重要信息都必须写入文件,而不是记在你的“脑海”里。
首先加载执行器规则。 在接触任何项之前,先从这个技能所在目录(此 SKILL.md 文件所在的文件夹)读取 executor-rules.md 文件——其中包含从实际运行中提炼出的 13 条具有约束力的、必须严格遵守的规则。当一条规则与你的直觉相悖时,遵循规则。
调用方式
/ratchet-loop [path] [--lane NAME] [--max-items N] [--only ID[,ID...]] [--verify inline|fresh] [--dry-run]
path—— 待办事项清单文件。默认为ratchet/BACKLOG.md,或者仓库根目录下的BACKLOG.md。如果两者都不存在,请说明情况并建议使用/ratchet-audit或/ratchet-backlog create。解析后的路径即是下文所说的待办事项清单文件,其所在目录是循环的状态目录(默认是ratchet/)。--lane NAME—— 仅适用于 v2 待办事项清单(对 v1 文件会报错):将候选资格限制为Lane: NAME的项,并且只将状态写入lanes/NAME.md文件。这是并行安全模式——详情见下文“v2 待办事项清单——工作流 (lanes)”。--lane是一个状态选择器,而非路由选择器:它永远无法满足高风险门控的--only要求。--max-items N—— 在此次运行中,当 N 个项达到终态后停止。--only—— 将候选资格限制为所列出的 ID(仍然会考虑依赖关系)。这也是高风险门控所要求的显式路由信号——见下文。--verify—— 验证模式,见下文“验证模式”。默认为inline。--dry-run—— 仅执行阶段 0:验证、报告执行计划以及真实运行会执行的任何恢复操作,不写入也不提交任何内容。
状态文件。 下文中的所有分类账和日志写入都指向状态文件:在 v1 中,那就是待办事项清单文件本身;在 v2 中,那是你所在工作流 (lane) 的文件 lanes/<lane>.md,而待办事项清单文件对你来说是只读的。
阶段 0 —— 预检查(绝不跳过,绝不重排序)
- 完整读取待办事项清单文件并验证其结构: 靠近文件顶部的位置必须有一个版本标记——准确地说是
<!-- ratchet:v1 -->或<!-- ratchet:v2 -->(一个包含:lane的标记意味着你被指向了一个工作流 (lane) 文件,而不是待办事项清单——拒绝执行并指向真正的待办事项清单);对于 v1,必须有全部四个部分(## Items、## Ledger、## Journal,可选## Global checks);对于 v2,必须有## Lanes+## Items(+ 可选## Global checks),待办事项清单中不能有 Ledger/Journal,再加上下文“v2 待办事项清单——工作流 (lanes)”中的 v2 结构检查;ID 必须匹配[A-Z]+-\d+并且唯一;每个项都必须有规约 (Spec) 和至少一个验收标准 (Acceptance criterion);每个项在分类账 (Ledger) 中都有一行(v2 中:在其工作流 (lane) 文件的Lane:中指定)且状态必须是合法集合中的一种(todo/in-progress/done/blocked/needs-human/skipped)。结构损坏 → 停止,报告确切的问题,建议使用/ratchet-backlog validate。绝不要猜测格式错误的文件。不破坏结构的逐项缺陷——过时的证据、在未设门控的项上存在不可运行的验收标准——将通过停用 (parking) 该特定项来处理,而不是拒绝整个文件。(完整约定:ratchet 仓库中的docs/backlog-format.md;你需要执行的检查是此处列出的这些。) - 要求一个干净的工作树——循环状态文件例外。
git status必须显示已追踪文件没有暂存或未暂存的更改。对发现的任何脏状态进行分类:- 你自己的状态—— v1:待办事项清单文件和状态目录。v2:仅你自己的工作流 (lane) 文件。未追踪 (Untracked) → 不是用户产生的脏数据;它将在步骤 3 中被提交(在 v1 中,这是管理工具新写入的待办事项清单进入历史记录的方式)。脏但已追踪 (Dirty but tracked) → 前一次运行遗留的状态(崩溃,或未同步的 sha 回填);在日志 (Journal) 中记录一行,并让步骤 3 提交它。
- 仅 v2——不属于你的东西永远不能由你来清理。
BACKLOG.md对你来说是只读的,因此它绝不是“前一次运行的状态”:脏的已追踪文件 (Dirty tracked) → 超出窗口的人工编辑或合并残留 → 停止并报告。未追踪 (Untracked)(待办事项清单或工作流 (lane) 文件)→ 管理工具的输出从未被提交;只有在集成分支 (integration branch) 上,步骤 3 会像 v1 一样将它作为ratchet: add backlog提交,这才没问题。在工作流 (lane) 分支上,未追踪的状态意味着你在待办事项清单被提交之前就被启动了 → 停止(“先在集成分支上提交待办事项清单”)。另一个工作流 (lane) 的文件,无论是脏的还是包含一个in-progress行:可能第二次运行正在使用此工作树 → 停止(“可能存在并行的活动运行——请为每个工作流分配独立的工作树”)。绝不提交其中任何一个,也绝不恢复任何一个。在工作流 (lane) 的工作树中,一个脏的或未追踪的NEXT.md文件:保持原样(绝不暂存,绝不提交——它只属于集成分支)并在报告中注明。 - 属于一个
in-progress分类账 (Ledger) 项的脏源路径是崩溃残留,在步骤 3 中处理——通过日志 (Journal) 的尾部以及该项的证据 (Evidence)/规约 (Spec) 来归因;如果归因不明确,停止并询问。 - 任何其他脏的已追踪文件 → 停止并询问用户(他们的工作不是你可以 stash 的)。这个不变性 (invariant) 使得你的故障恢复是安全的。
- v2——在进行任何写入之前确定你工作流 (lane) 的活动状态。 读取你的工作流 (lane) 的运行标记——即
--lane命名的那个,或者在顺序模式下,是你将要处理的第一个工作流 (lane)(见“v2 待办事项清单——工作流 (lanes)”)。已关闭 (Closed) → 这是新的运行。已打开 (Open),且命名了你的当前分支 → 崩溃残留;你在现有标记下继续。已打开 (Open),但命名了不同的分支 → 该工作流 (lane) 可能在其他地方处于活动状态:停止。然后,如果这是一个默认工作流 (lane) 运行或一个不带有--lane的顺序运行,请验证屏障前置条件——所有其他工作流 (lane) 都已关闭并且已合并——如果不满足则在此处拒绝。此步骤中的每次拒绝都发生在步骤 3 写入任何内容之前,因此,本不应启动的运行不会留下任何标记。
- 恢复,然后一次性提交恢复结果。 卡在
in-progress的分类账 (Ledger) 行是崩溃运行的残留——在 v2 中,仅存在于你自己的工作流 (lane) 文件中;另一个工作流 (lane) 的in-progress行可能是正在进行的并行运行,你绝不能触碰。对于每一行:如果步骤 2 中归因于它的源路径仍然存在,则还原这些路径(执行器规则 9);在日志 (Journal) 中记录found in-progress from a crashed run — reset to todo;将该行状态设回todo。这是执行器唯一允许的回退状态操作,且仅在预检查阶段发生。然后创建一次提交,涵盖步骤 2-3 涉及的所有内容——首次运行状态 (ratchet: add backlog) 或恢复 (ratchet: recover state)。在 v2 中,同一次提交也包含你的工作流 (lane) 的打开日志行,取决于步骤 2 发现了什么:一个新的工作流 (lane) 会得到- <date> run started (lane <name>, branch <branch>);一个被发现在你自己的分支上已打开的工作流 (lane) 会得到- <date> found open run from <date> — presumed crashed, recovering并且没有第二个run started(现有的那个仍然是你的工作流 (lane) 的打开标记,并且你的run ended将与之平衡)。如果没有其他内容要提交,则仅提交该行,描述为ratchet(<lane>): run open。在 v1 中,如果步骤 2-3 没有发现任何内容,则无需提交任何内容。 - 读取分类账 (Ledger) 和完整日志 (Journal)——在 v2 中,这意味着每个工作流 (lane) 文件的分类账和日志,而不仅仅是你的(你写入一个工作流 (lane);你要读取它们全部)。日志 (Journal) 是你的遗产——先前的尝试、已知的陷阱、失败的假设。在没有新理由的情况下,不要重新尝试日志 (Journal) 说已失败的事情。
- 建立绿色基线。 对于
## Global checks下的每个命令,执行一次其确定性形式——冷启动,不依赖增量缓存,不依赖正在运行的开发服务器生成的类型(一次热缓存的tsc --noEmit可能报告为绿色,而当相同的检查冷启动运行时(就像 CI 运行它那样),结果可能是红色)。如果一个全局检查看起来对缓存敏感,并且待办事项清单没有固定其形式,那么你自己运行冷启动形式,并在日志 (Journal) 中注明差异。红色基线 → 停止并报告(你无法从一个有问题的起点向前推进 ratchet)——除非存在一个带有[BASELINE]标签的项并且归属于你运行(v1:总是;v2:其Lane:匹配你的--lane,或者没有指定--lane),在这种情况下,该项是你强制性的首选,优先于文件顺序。在 v2 的--lane X运行中,如果[BASELINE]项属于另一个工作流 (lane),则停止并报告:“基线被<ID>阻塞(位于工作流<Y>中)——先运行那个工作流 (lane),合并,然后重新启动”。等待是一个停止动作,永远不要写入另一个工作流 (lane)。 - 从
git log --oneline -15检测仓库的提交约定(约定式提交?纯文本句子?范围前缀?)。你将匹配它。 - 检查分支。 如果你在仓库的默认分支上,并且仓库是基于 PR 或推送即部署的,建议在首次提交之前创建一个工作分支 (
ratchet/<scope-or-date>)——/ratchet-ship稍后会打开 PR。仅当用户明确同意时,才在默认分支上继续。在 v2 的--lane X运行中,分支不是可选的:如果分支ratchet/X存在则恢复使用,否则从集成分支的头部创建它,如果你落后于集成分支,则将其合并进来——见“v2 待办事项清单——工作流 (lanes)”。 - 读取
NEXT.md(如果存在的话,位于状态目录中)。它是来自/ratchet-recommend的路由计划:尊重其每个项的验证分配——它路由为 SUPERVISED 或 SENIOR 的项需要--verify fresh。如果 fresh 未生效,则仅停用那些在本次运行中本会执行(通过资格检查并匹配--only)的 SUPERVISED/SENIOR 项;本次运行范围之外的项保持不动——它们的波 (wave) 命令已经携带了正确的标志。如果 NEXT.md 的日期早于上一次分类账 (Ledger) 更改(v2:早于你的工作流 (lane) 文件的最后一次更改),则说明其已过时,建议重新生成它——v1:照常在状态目录中;v2:在集成分支上,绝不在工作流 (lane) 工作树中。调用者的显式标志会覆盖 NEXT.md。v2 中为只读:你绝不写入、暂存或提交 NEXT.md。 - 宣布计划: 按顺序列出的符合条件的项、已停用的项及其原因、分支、生效的停止条件。在
--dry-run模式下,在此处停止——并且由于 dry-run 不写入任何内容,因此报告步骤 2-3 本会创建的提交,而不是实际创建它们。因此,dry-run 永远不会打开一个工作流 (lane):不会写入或提交run started标记,因此它不会在身后留下任何已打开的工作流 (lane)。
资格
当一个项满足所有以下条件时,它才有资格:分类账 (Ledger) 状态为 todo · 没有人网关标签([USER-DECISION]、[OPS]、[RISKY])· 每个 Depends: ID 都是 done 状态(v2:跨工作流 (lane) 的依赖关系仅作为在你的工作树中可见的 done 行计数——已完成的并已合并)· 如果给出了 --only 则需匹配 · 如果给出了 --lane 则需匹配。按文件顺序处理符合条件的项。如果每个 --only ID 都存在,但没有任何一个携带了调用时的工作流 (lane) 的 Lane:,那么这是一个错误(“SEC-01 位于工作流 ui 中——请使用 --lane ui 重新运行或重新生成 NEXT.md”),绝不是静默地“待办事项清单为空”。人网关的 todo 项:将其分类账 (Ledger) 状态设为 needs-human,并将标签作为备注(一次),然后继续。已停用的项将保持停用状态,直到人类取消其停用——状态回到 todo,移除门控标签,在日志 (Journal) 中记录决策(格式的“人工转换”过程);你自己永远不会这样做。
高风险门控(机械式)。 当一个项的规约 (Spec) 或证据 (Evidence) 涉及触发列表中的任何内容时(直接引用执行器规则 1),该项属于高风险:认证/权限、租户边界 (companyId / ownership 作用域)、支付或金钱计算、总账/日记账过账、数据库迁移、密钥/环境变量、文件或行删除、会话/Cookie 处理。一个未设门控的高风险项只有在同时满足以下两个条件时才可执行:(a) 启用了 --verify fresh,并且 (b) 调用者显式地将其列入了 --only 中——即一个人或 NEXT.md 路由选择了它以便在此次运行中执行。--lane 永远不算作 (b)。否则,将其停用为 needs-human(备注:“高风险;通过 /ratchet-recommend 路由”)。例外:一个 [BASELINE] 项不受 --only 要求的限制——其标签就是人工路由,并且没有它运行无法继续——但是当它触及触发列表并且 fresh 模式可用时,请对其使用 fresh 验证。不要自行评估你是什么模型——由标志来决定。在认证或金钱上出现错误的“绿色”是 Ratchet 存在以防止的最昂贵的失败;人工过一眼的成本总是更低的。
v2 待办事项清单——工作流 (lanes)
v2 待办事项清单(<!-- ratchet:v2 -->)按工作流 (lane) 拆分状态:待办事项清单包含 ## Lanes + ## Items(每个项携带 Lane: <name>),每个工作流 (lane) 的分类账 (Ledger) 和日志 (Journal) 存放在 lanes/<lane>.md 中——单个写入者,因此并行代理不会写入同一个文件。完整约定:ratchet 仓库中的 docs/backlog-format.md §5;执行器所需的一切都在下面。
v2 结构检查(预检查步骤 1 附加项)。 遇到以下任一情况时停止:没有 ## Lanes;第一个工作流 (lane) 的作用域 (Scope) 不是字面量 (rest),或者第二个工作流 (lane) 也声明了 (rest)(恰好一个默认工作流 (lane));有命名作用域的工作流 (lane) 作用域重叠;一个项缺少 Lane: 或命名了未声明的工作流 (lane);一个已声明的工作流 (lane) 的 lanes/<lane>.md 文件缺失或其 <!-- ratchet:v2:lane <name> --> 标记与文件名和声明不匹配;一个项在任何地方都没有分类账行、行在错误的工作流 (lane) 文件中,或者跨文件存在重复行。你从不创建工作流 (lane) 文件——那是管理工具的工作(/ratchet-backlog)。在 --lane X 运行中的拒绝作用域:待办事项清单、lanes/X.md 或 X 自身的项的行驻留中的缺陷属于停止 (STOP) 情况;局限于另一个工作流 (lane) 文件的内部损坏是一个响亮的警告 (WARN)——报告它,但绝不触碰它。
运行标记(活动信号)。 当从工作流 (lane) 的日志 (Journal) 自下而上扫描时,找到的第一个运行标记是 run started 时,该工作流 (lane) 被认为已打开。一次运行通过在即将处理的工作流 (lane) 的日志 (Journal) 中追加一行 - <date> run started (lane <name>, branch <branch>) 并提交它来打开该工作流 (lane)(预检查步骤 3,或 ratchet(<lane>)</p>...
[应根据实际情况提供完整内容。由于原始内容被截断,此处呈现了基于所提供文本的完整翻译。]