173 lines
4.6 KiB
Markdown
173 lines
4.6 KiB
Markdown
# loop-build（Codex CLI harness）
|
||
|
||
本目录提供一套受控的长周期执行流程：**PLAN -> APPROVE -> 单步 LOOP -> VERIFY -> RE-APPROVE -> 重复**。
|
||
|
||
## 1）一次性初始化
|
||
|
||
1. 运行：
|
||
|
||
```bash
|
||
./.loop-build/scripts/init.sh
|
||
```
|
||
|
||
2. 阅读依赖检查结果；建议在工作树基本干净（clean）时开始任务。
|
||
3. 保留生成的 `.loop-build/TASKS.md`，作为任务记录模板。
|
||
|
||
## 2）创建任务并产出 PLAN
|
||
|
||
你需要提供：
|
||
- `goal`
|
||
- `constraints`
|
||
- `repo_context_hint`
|
||
- `current_state_summary`
|
||
|
||
随后在 Codex CLI 会话中使用 `prompts/planner.md`，生成严格 JSON，且 `plan_steps` 需为 3~7 步。
|
||
|
||
将结果写入：
|
||
|
||
```bash
|
||
./.loop-build/state/current_task.json
|
||
```
|
||
|
||
推荐包含字段：
|
||
- `task_id`、`goal`、`constraints`、`plan_steps[]`、`success_criteria`、`risk_notes`、`required_files`、`verify_targets`
|
||
|
||
每个 `plan_step` 必须包含：
|
||
- `step_id`
|
||
- `action`
|
||
- `verification`
|
||
- `rollback`
|
||
- `risk_level`
|
||
- `expected_output`
|
||
|
||
### Plan 审批（强制）
|
||
|
||
未记录审批前，**不要**执行任何 `step`。
|
||
|
||
执行：
|
||
|
||
```bash
|
||
./.loop-build/scripts/run_task.sh APPROVE_PLAN
|
||
```
|
||
|
||
需要修改 plan 时：
|
||
|
||
```bash
|
||
./.loop-build/scripts/run_task.sh REVISE_PLAN "need narrower scope"
|
||
```
|
||
|
||
取消任务：
|
||
|
||
```bash
|
||
./.loop-build/scripts/run_task.sh CANCEL_TASK
|
||
```
|
||
|
||
`run_task.sh` 会读取 `current_task.json`，输出 plan 概览（步骤、风险、文件、验证、回滚），并等待一次性人类回复。
|
||
|
||
## 3）循环执行（每次只跑 1 步）
|
||
|
||
审批通过后：
|
||
|
||
```bash
|
||
./.loop-build/scripts/run_task.sh step 1
|
||
```
|
||
|
||
执行行为：
|
||
- 仅执行一个 plan step。
|
||
- 默认输出统一 diff（`git diff` 风格）。
|
||
- 仅当该 step 的 plan 指定 verification 时才执行验证。
|
||
- 向 `.loop-build/state/history.ndjson` 追加一条 NDJSON 记录。
|
||
- 更新 `.loop-build/state/current_task.json` 的 `completed_steps` / `next_step` / `open_questions`。
|
||
- 暂停并等待 `APPROVE_NEXT`，再继续下一步。
|
||
|
||
### 每步后再次审批
|
||
|
||
一步完成后，选择其中一个：
|
||
|
||
```bash
|
||
./.loop-build/scripts/run_task.sh APPROVE_NEXT
|
||
./.loop-build/scripts/run_task.sh REVISE_PLAN "scope too large for current diff"
|
||
./.loop-build/scripts/run_task.sh CANCEL_TASK
|
||
```
|
||
|
||
继续执行：
|
||
|
||
```bash
|
||
./.loop-build/scripts/run_task.sh step 2
|
||
```
|
||
|
||
## 4）验证流程
|
||
|
||
`verify.sh` 支持：
|
||
|
||
```bash
|
||
./.loop-build/scripts/verify.sh unit
|
||
./.loop-build/scripts/verify.sh lint
|
||
./.loop-build/scripts/verify.sh typecheck
|
||
./.loop-build/scripts/verify.sh all
|
||
```
|
||
|
||
手动验证时：
|
||
|
||
```bash
|
||
APPROVE=1 ./.loop-build/scripts/verify.sh unit
|
||
```
|
||
|
||
在 `run_task.sh` 的循环中，验证会经过同一套策略门禁。
|
||
|
||
## 5）防“代码倾泻”规则（由 prompt 与脚本共同执行）
|
||
|
||
- 默认只输出统一 diff，不输出完整文件。
|
||
- 每个 step 默认最多改动 **2 个文件**（超过则必须拆分 step）。
|
||
- 单步失败会自动重试，最多 2 次。
|
||
- 错误输出只保留前后关键片段，避免噪声。
|
||
|
||
## 6）安全策略模型
|
||
|
||
策略文件位于 `.loop-build/config/`：
|
||
|
||
- `policy.env`：开关配置和显式解锁变量。
|
||
- `allowlist.txt`：默认只读安全前缀（无需审批）。
|
||
- `denylist.txt`：默认禁止的动作，需显式解锁。
|
||
|
||
`run_task.sh` 执行任何命令前都会经过 `check_policy`（前缀匹配 + 显式解锁校验）。
|
||
|
||
默认受限动作示例：`sudo`、`rm -rf`、`curl`、`wget`、`git clone`、`curl|bash` / 下载并执行类写法。
|
||
|
||
## 7）示例任务
|
||
|
||
### 示例 1：修复一个失败测试
|
||
1. 填写 goal/constraints。
|
||
2. 生成 3~7 步 PLAN。
|
||
3. 执行 `APPROVE_PLAN`。
|
||
4. `step 1` -> `verify`（如配置）。
|
||
5. `APPROVE_NEXT` -> `step 2` -> `step ...`。
|
||
|
||
### 示例 2：小范围重构（<=2 文件）
|
||
1. 明确范围仅限文件 A/B。
|
||
2. 要求 plan step 包含 `risk_level=LOW` 且有回滚说明。
|
||
3. 每步独立执行，并在每个 diff 后重新审批。
|
||
|
||
### 示例 3：新增一个测试用例
|
||
1. Plan 应包含 fixtures/setup、断言、针对性验证。
|
||
2. 确保每步最多触及 1 个测试文件 + 1 个源码文件。
|
||
3. 步骤间重新审批以控制变更边界。
|
||
|
||
## 8）文件清单
|
||
|
||
- `.loop-build/README.md`
|
||
- `.loop-build/TASKS.md`
|
||
- `.loop-build/state/current_task.json`
|
||
- `.loop-build/state/history.ndjson`
|
||
- `.loop-build/prompts/planner.md`
|
||
- `.loop-build/prompts/executor.md`
|
||
- `.loop-build/prompts/reviewer.md`
|
||
- `.loop-build/scripts/init.sh`
|
||
- `.loop-build/scripts/verify.sh`
|
||
- `.loop-build/scripts/run_task.sh`
|
||
- `.loop-build/scripts/apply_patch.sh`
|
||
- `.loop-build/scripts/snapshot.sh`
|
||
- `.loop-build/config/policy.env`
|
||
- `.loop-build/config/allowlist.txt`
|
||
- `.loop-build/config/denylist.txt`
|