174 lines
4.6 KiB
Markdown
174 lines
4.6 KiB
Markdown
# 声明式 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 # 最终摘要
|
||
```
|