190 lines
4.6 KiB
Markdown
190 lines
4.6 KiB
Markdown
# 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 循环。
|