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

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

## 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. 首次使用（一次性）

在仓库根目录执行：

```bash
./.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，写入：

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

PLAN 必须满足：
- 步数 3~7
- 每步包含：
  - `step_id`
  - `action`
  - `verification`
  - `rollback`
  - `risk_level`
  - `expected_output`

### 第三步：审批 PLAN（强制）

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

如果要改计划：

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

取消任务：

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

### 第四步：单步执行

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

或指定步号：

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

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

### 第五步：每步后再次审批

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

或要求改计划：

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

然后继续 `step`，直到完成。

## 4. 常用命令速查

查看当前任务状态：

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

执行验证（手动）：

```bash
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
```

创建快照：

```bash
./.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 命中原因。
- 评估是否真的需要解锁，不建议为省事放开高风险命令。

快照文件需要检查：

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

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

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

```text
请基于 .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 循环。