4.6 KiB
声明式 OpenSpec 循环 - 参考
预期/校验方式的写法
校验命令
用户直接给命令，成功 = 退出码 0（或约定输出内容）：
"跑 make test-one2，通过就行"
"运行 pytest tests/test_foo.py，全部 green 即符合预期"
"make build && ./run_check.sh，输出里必须包含 ALL PASSED"
Agent 收到后在 expectation.md 中记录：命令、成功条件（退出码 / 输出关键字）。
预期文档（含校验项）
文档里有「校验项」或「预期说明」，Agent 按此检查输出/日志/文件。推荐文档结构：
## 整体预期描述
<这个功能/轮廓/接口应该怎样>
## 详细说明
<按顺序的几何/行为描述>
## 校验项
| 序号 | 检查点 | 预期说明 | 日志/输出关键字 |
| ---- | ------ | -------- | --------------- |
| 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，推荐结构：
# 第 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：
## 校验方式
1. 命令：`make test-one2`，退出码 0
2. 文档：`docs/tmp/expect_desc.md`「校验项」表 8 项全部通过（world 坐标容差 2mm）
第 1 步：propose
读取 openspec-propose SKILL.md → 执行：
openspec new change "arc-top-seven-expect-align"
生成 proposal.md、design.md、tasks.md。tasks 中每个 task 带验收标准，例如：
- [ ] 2.3 运行 make test-one2，对比拟合日志中各段端点与 expect_desc 表；不符则修改后重复
第 2 步：apply（第 1 轮）
读取 openspec-apply-change SKILL.md → 逐 task 实现。
第 3 步：校验（第 1 轮）
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 # 最终摘要