OpenSpec 入门：把 AI 编程需求变成可审阅的变更材料
阅读 OpenSpec ArtifactGraph：为什么先推荐规格
检查声明顺序的优先规则，并用六个离线用例验证实际图类。
阅读 OpenSpec ArtifactGraph：为什么先推荐规格知识学习CN编辑简报更新 2026-09-23
你将学会
- 沿着拓扑排序看实现
- 比较完整顺序与当前就绪项
- 不要扩大预验证输入的含义
开始前需要
- 基本 Git 与 Node 知识
- 可独立试验的样例仓库
用合成模式解释阻塞原因，把规划状态与实现证据放在不同列中。
先看结论
- 代码重新排序整个队列。
- 用例执行实际的纯图类。
- 六项断言不等于完整 CLI 验证。
沿着拓扑排序看实现
getBuildOrder 先建立入度和反向邻接关系，把没有依赖的材料入队，再逐个移除并减少后继入度。队列依据材料在模式中的声明位置排序。
新就绪材料加入后，代码会重新排序整个队列，只排序新加入部分会遗漏已经等待的材料。这里提供确定性的声明顺序，而不是按字母排序。
比较完整顺序与当前就绪项
getNextArtifacts 跳过已完成材料，并要求每项依赖都在完成集合中。离线用例在提案完成后得到规格和设计，在提案与规格完成后只得到设计。
测试去除所检查纯类的 TypeScript 类型和模块导入，用合成的有效模式调用 fromSchema。六项断言覆盖顺序、就绪与完成，不运行加载器、文件检测、CLI 或模型。
不要扩大预验证输入的含义
fromSchema 明确要求输入已经验证。当前用例没有证明循环依赖、重复标识或未知依赖会被拒绝，不能从正常路径测试推断畸形模式也受支持。
当下一步建议出乎预期时，分别检查声明顺序、完成集合和依赖边。任何一项变化都可能改变结果，不必立即把问题归因于拓扑排序错误。
如何选择
| 比较维度 | 方案 A | 方案 B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
实施步骤
- 1
检查声明位置与队列排序。
- 2
复现完成集合的变化。
- 3
把模式验证排除在本测试结论外。
可复制示例
json
{"completed":["proposal"],"ready":["specs","design"],"buildOrder":["proposal","specs","design","tasks"]}常见问题
为何不按字母先显示 design？
类使用模式声明位置处理同时就绪的材料。
测试了错误模式吗？
没有，用例采用已验证模式的入口与有效的合成数据。
资料来源
- OpenSpec / src/core/artifact-graph/graph.ts来源核查 2026-09-23
- OpenSpec / schemas/spec-driven/schema.yaml来源核查 2026-09-23