用途
Ratchet 是一个用于跟踪 RPI 工作流进度的技能，通过永久性关卡（gate）锁定各阶段的完成状态。其核心模型为“布朗尼棘轮”：进度 = 混沌 × 过滤 → 棘轮。混沌指多次尝试（探索、实现），过滤指验证关卡（测试、/vibe、审查），棘轮指将进度永久锁定（合并、关闭、存储）。关键理念是进度是永久的，无法“反棘轮”。
注意：/ratchet 仅跟踪和锁定进度，它本身不“运行循环”——需配合 /crank（史诗循环）或 /swarm（Ralph 循环）来实际执行工作。
主要能力
Ratchet 提供以下命令：
- status：检查当前状态。可运行
ao ratchet status 2>/dev/null，或手动检查链：cat .agents/ao/chain.jsonl 2>/dev/null | tail -10。 - check [step]：验证关卡。运行
ao ratchet check <step> 2>/dev/null。步骤包括：research、plan、implement、vibe、post-mortem。 - record [step]：记录完成。运行
ao ratchet record <step> --output "<artifact-path>" 2>/dev/null，或手动写入链：echo '{"step":"<step>","status":"completed","output":"<path>","time":"<ISO-timestamp>"}' >> .agents/ao/chain.jsonl。 - skip [step]：有意跳过。运行
ao ratchet skip <step> --reason "<why>" 2>/dev/null。
工作流步骤
各步骤对应关卡与输出：
- research：关卡为研究产物存在，输出至 .agents/research/*.md
- plan：关卡为计划产物存在，输出至 .agents/plans/*.md
- implement：关卡为代码 + 测试通过，输出为源文件
- vibe：关卡为 /vibe 通过，输出至 .agents/vibe/*.md
- post-mortem：关卡为经验教训已提取，输出至 .agents/learnings/*.md
使用方式
进度存储在 .agents/ao/chain.jsonl 中，每行一条 JSON 记录，例如：
{"step":"research","status":"completed","output":".agents/research/auth.md","time":"2026-01-25T10:00:00Z"}
{"step":"plan","status":"completed","output":".agents/plans/auth-plan.md","time":"2026-01-25T11:00:00Z"}
{"step":"implement","status":"in_progress","time":"2026-01-25T12:00:00Z"}
关键规则：
- 进度是永久的——无法反棘轮。
- 关卡必须通过——继续前先验证。
- 记录一切——维护链的完整性。
- 显式跳过——若跳过某步骤，需记录原因。
示例一：检查 RPI 进度。用户输入 /ratchet status，代理调用 ao ratchet status 2>/dev/null 检查当前状态，CLI 读取 .agents/ao/chain.jsonl 并解析进度，代理报告哪些步骤已完成、进行中或待处理，显示已完成步骤的输出产物路径，并识别下一个需通过的关卡。结果：单屏展示 RPI 工作流进度，显示已通过的关卡和下一步。
示例二：记录步骤完成。技能在 /research 完成后触发，代理调用 ao ratchet record research --output ".agents/research/auth.md"，CLI 将完成条目追加到 .agents/ao/chain.jsonl，代理将 research 步骤锁定为永久完成，随后进入 plan 阶段。结果：进度被永久记录，关卡锁定，工作流前进且不会倒退。
适用场景
适用于需要严格跟踪多阶段工作流进度、确保各阶段验证关卡通过且进度不可回退的开发流程，尤其是与 /crank 或 /swarm 配合执行实际工作的场景。
限制与故障排除
ao ratchet status失败：原因可能是 ao CLI 不可用或 chain.jsonl 缺失。解决：手动检查 .agents/ao/chain.jsonl 或创建空文件。- “步骤已完成”错误：原因可能是尝试重新棘轮已锁定的步骤。解决：使用
ao ratchet status检查状态；若已完成则跳过。 - chain.jsonl 损坏：原因可能是 JSON 条目格式错误。解决：手动编辑修复 JSON；用
jq -c '.' <file>验证每一行。 - 步骤顺序错乱：原因可能是在计划前就实现。解决：严格遵循 RPI 顺序；仅在明确原因时使用 --skip。
参考文档：references/ratchet.feature — 可执行规范：Chaos×Filter→Ratchet、record/check 循环步骤关卡、单调链（soc-qk4b.2）。