loop-build 使用指南（简体中文）

本文件是 loop-build (Codex CLI harness) 的中文操作手册，面向日常使用者。
目标是让你按固定节奏推进任务：先计划、再审批、单步执行、验证、再次审批。

快速开始 QUICKSTART.md

1. 这套 harness 是做什么的

loop-build 用于长时间运行、可中断、可回滚的任务执行。
它把一次任务拆成 3~7 个步骤，并强制执行以下状态机：

1. 生成 PLAN
2. 人类审批 PLAN（APPROVE_PLAN / REVISE_PLAN / CANCEL_TASK）
3. 每次只执行 1 个 step
4. step 后汇报并等待下一次审批（APPROVE_NEXT / REVISE_PLAN / CANCEL_TASK）

2. 首次使用（一次性）

在仓库根目录执行：

./.loop-build/scripts/init.sh

初始化脚本会：

• 检查依赖：git、bash、rg、jq
• 初始化 .loop-build 所需目录与默认配置
• 生成任务模板与状态文件（若缺失）
• 提示你尽量在 git 工作树较干净时开始

3. 每个任务的标准流程

第一步：准备任务输入

你需要准备 4 类输入给 planner：

• goal：任务目标
• constraints：约束条件
• repo_context_hint：仓库上下文提示
• current_state_summary：当前状态摘要（可选）

第二步：产出并写入 PLAN

用 ./.loop-build/prompts/planner.md 让 Codex 生成严格 JSON，写入：

./.loop-build/state/current_task.json

PLAN 必须满足：

• 步数 3~7
• 每步包含：
  • step_id
  • action
  • verification
  • rollback
  • risk_level
  • expected_output

第三步：审批 PLAN（强制）

./.loop-build/scripts/run_task.sh APPROVE_PLAN

如果要改计划：

./.loop-build/scripts/run_task.sh REVISE_PLAN "说明你要改什么"

取消任务：

./.loop-build/scripts/run_task.sh CANCEL_TASK

第四步：单步执行

./.loop-build/scripts/run_task.sh step

或指定步号：

./.loop-build/scripts/run_task.sh step 2

执行特性：

• 一次只推进一个 step
• 默认输出 unified diff，不整文件倾泻
• 按 step 的 verification 决定是否触发验证
• 写入历史记录到 state/history.ndjson
• 更新 current_task.json 的进度字段

第五步：每步后再次审批

./.loop-build/scripts/run_task.sh APPROVE_NEXT

或要求改计划：

./.loop-build/scripts/run_task.sh REVISE_PLAN "下一步前先调整计划"

然后继续 step，直到完成。

4. 常用命令速查

查看当前任务状态：

./.loop-build/scripts/run_task.sh status

执行验证（手动）：

APPROVE=1 ./.loop-build/scripts/verify.sh unit
APPROVE=1 ./.loop-build/scripts/verify.sh lint
APPROVE=1 ./.loop-build/scripts/verify.sh typecheck
APPROVE=1 ./.loop-build/scripts/verify.sh all

创建快照：

./.loop-build/scripts/snapshot.sh
./.loop-build/scripts/snapshot.sh before-step-2

5. 安全策略说明（必须了解）

策略文件在 ./.loop-build/config/：

• allowlist.txt：默认允许的只读命令
• denylist.txt：默认禁止的高风险命令
• policy.env：显式解锁开关

关键点：

• 命令会按分段检查（如 &&、||、;、|）
• 命中 denylist 默认拦截
• 需在 policy.env 显式解锁并启用二次确认，才允许执行高风险动作

6. 实战建议（推荐）

• 每个 step 只做一个最小可验证改动（MVC）。
• 每个 step 最多改 2 个文件，超过就拆分计划。
• action 尽量写成可直接执行的最小命令列表。
• verification 只写当前 step 真正需要的 target，避免全量跑。
• 每步都写清 rollback，失败时能快速恢复。
• 发现计划偏离时优先 REVISE_PLAN，不要硬推进。

7. 常见问题排查

run_task.sh 提示 plan 未审批：

• 先执行 APPROVE_PLAN。

验证被阻止：

• 手动运行 verify 时需要 APPROVE=1。

step 被策略拦截：

• 查看 denylist 命中原因。
• 评估是否真的需要解锁，不建议为省事放开高风险命令。

快照文件需要检查：

latest=$(ls -1t ./.loop-build/state/snapshots/snapshot-*.json | head -n 1)
jq . "$latest"

8. 推荐协作模板（给 Codex CLI）

你可以直接用下面这段话发起任务：

请基于 .loop-build/prompts/planner.md 生成严格 JSON 计划，目标是：
<goal>
约束是：
<constraints>
仓库上下文：
<repo_context_hint>
当前状态：
<current_state_summary>
要求 3~7 步，每步包含 step_id/action/verification/rollback/risk_level/expected_output。

生成后先写入 state/current_task.json，再走审批与 step 循环。