# 声明式 OpenSpec 循环 - 参考

## 预期/校验方式的写法

### 校验命令

用户直接给命令，成功 = 退出码 0（或约定输出内容）：

```
"跑 make test-one2，通过就行"
"运行 pytest tests/test_foo.py，全部 green 即符合预期"
"make build && ./run_check.sh，输出里必须包含 ALL PASSED"
```

Agent 收到后在 `expectation.md` 中记录：命令、成功条件（退出码 / 输出关键字）。

### 预期文档（含校验项）

文档里有「校验项」或「预期说明」，Agent 按此检查输出/日志/文件。推荐文档结构：

```markdown
## 整体预期描述

<这个功能/轮廓/接口应该怎样>

## 详细说明

<按顺序的几何/行为描述>

## 校验项

| 序号 | 检查点 | 预期说明 | 日志/输出关键字 |
| ---- | ------ | -------- | --------------- |
| 1    | ...    | ...      | ...             |
```

本仓库示例：`docs/tmp/expect_desc.md` — 描述弧顶七字形轮廓几何，末尾有 8 项校验表。

### 校验清单（条目化）

用户列几条「必须满足」的条件：

- 日志中必须出现：`阶段2 圆弧起点(左上角)`、`阶段3 右边竖边: 上端=...`
- 生成文件 `out/result.json` 中 `status` 必须为 `ok`
- 拟合轮廓 2D PLY 点数 > 100

### 自由描述

由 Agent 归纳为可执行检查步骤并在 `expectation.md` 中记录归纳结果，执行前向用户确认理解是否正确。

---

## 迭代日志模板 `iteration_<NNN>.md`

每轮写入 `docs/tmp/<change-name>/iteration_<NNN>.md`，推荐结构：

```markdown
# 第 N 轮

## apply 要点

- 执行了哪些 task / 修复了什么

## 校验结果

- 命令：`make test-one2`
- 退出码：1
- 通过项：1, 2, 3, 5, 6
- 未通过项：4（底边端点偏差 > 2mm）、7（右下斜边日志缺失）、8（左侧竖边未闭合）

## 分级

Level 2：task 2.3 缺少右下斜边独立成段的验证

## 下一步

- 在 tasks.md 补充 task 2.3 的验证步骤
- 修改 sampleArcTopSevenShape2D 中右下斜边的端点取值
```

---

## 端到端示例（基于本项目）

以下是一个完整循环的示例，基于「弧顶七字形拟合与 expect_desc 对齐」场景。

### 用户输入

```
目标：让弧顶七字形拟合结果与 docs/tmp/expect_desc.md 描述一致
校验方式：
  1. 运行 make test-one2
  2. 拟合日志中应包含 expect_desc.md「校验项」表的 8 项（各段端点 world 坐标与 PLY 一致，容差 2mm）
```

### 第 0 步：初始化

```
mkdir -p docs/tmp/arc-top-seven-expect-align/
```

写 `docs/tmp/arc-top-seven-expect-align/expectation.md`：

```markdown
## 校验方式

1. 命令：`make test-one2`，退出码 0
2. 文档：`docs/tmp/expect_desc.md`「校验项」表 8 项全部通过（world 坐标容差 2mm）
```

### 第 1 步：propose

读取 openspec-propose SKILL.md → 执行：

```bash
openspec new change "arc-top-seven-expect-align"
```

生成 proposal.md、design.md、tasks.md。tasks 中每个 task 带验收标准，例如：

```markdown
- [ ] 2.3 运行 make test-one2，对比拟合日志中各段端点与 expect_desc 表；不符则修改后重复
```

### 第 2 步：apply（第 1 轮）

读取 openspec-apply-change SKILL.md → 逐 task 实现。

### 第 3 步：校验（第 1 轮）

```bash
make test-one2 2>&1 | tee docs/tmp/arc-top-seven-expect-align/check_result_001.txt
```

结果：编译通过，但校验 8 项中 5 项通过、3 项不通过（底边端点、右下斜边、左侧竖边）。

→ 写 `iteration_001.md`

### 第 4 步：分级 → Level 1（代码小修复）

底边端点偏差原因：`sampleArcTopSevenShape2D` 中取错了变量。直接修复，重新编译运行。

### 第 5 步：校验（第 2 轮）

6/8 通过，右下斜边和左侧竖边仍不对。

→ 写 `iteration_002.md`，分析发现 tasks 中缺少右下斜边独立成段的 task。

### 第 6 步：分级 → Level 2（补 task）

在 tasks.md 中补充 task，apply 新 task。

### 第 7 步：校验（第 3 轮）

8/8 通过。

→ 输出变更摘要与思路，写 `iteration_final.md`。

---

## 过程数据目录结构示例

```
docs/tmp/arc-top-seven-expect-align/
├── expectation.md          # 校验方式
├── iteration_001.md        # 第 1 轮：5/8 通过
├── check_result_001.txt    # make test-one2 第 1 轮原始输出
├── iteration_002.md        # 第 2 轮：6/8 通过，Level 2 补 task
├── check_result_002.txt    # 第 2 轮原始输出
├── iteration_003.md        # 第 3 轮：8/8 通过
├── check_result_003.txt    # 第 3 轮原始输出
└── iteration_final.md      # 最终摘要
```