Spec Kit：从可测试意图到可追踪验收
Spec Kit 源码分析：返回路径不等于完成前置验证
追踪 PowerShell 的提前退出、必需文档开关和可选输出，以及 Python 解析入口的委托与错误处理。
你将学会
- 先看 PowerShell 的仅路径分支
- 分别理解验证与输出开关
- Python 入口是适配器，不是整个引擎
开始前需要
- 了解基本需求、Git 与测试
- 分清本地开发和应用部署
追踪小功能从意图到证据的过程，区分流程约定与已验证行为。
先看结论
- -PathsOnly 返回位置，但不检查前置文档。
- 要求任务存在与把任务列入输出是不同开关。
- 入口源码不能证明导入引擎的全部行为。
先看 PowerShell 的仅路径分支
check-prerequisites.ps1 导入 common.ps1 后获取功能路径。在 -PathsOnly 模式下，它向 Get-FeaturePathsEnv 传入 -NoPersist，输出路径变量，然后在检查文件之前退出。源码注释说明，这样可避免纯路径解析过程中持久化 feature.json 的副作用。
因此，仅路径模式成功并不能证明功能目录、计划、规格或任务文件确实存在。其他模式调用普通路径解析。本次检查的是脚本入口，而非完整导入模块，所以不能声称已经列出整个调用链的所有文件系统行为。
分别理解验证与输出开关
正常验证先检查功能目录和 plan.md，再根据 -RequireSpec 与 -RequireTasks 检查规格和任务。-IncludeTasks 决定是否把已经存在的任务文件列入 AVAILABLE_DOCS；“要求存在”和“把它列出来”是两个不同决定。缺少必需输入会输出错误并返回非零状态。
脚本还列出可用的研究、数据模型、接口目录和快速上手等可选资料。使用 -Template 时，会请求辅助函数解析模板，缺少结果则失败。一个可用文档列表不能替代对内容完整性、正确性和一致性的检查。
Python 入口是适配器，不是整个引擎
resolve_template.py 解析模板名和可选 --json 参数，确定仓库根目录并调用 resolve_template_content。它捕获 TemplateResolutionError，结果为 None 时也返回失败。成功 JSON 包含 TEMPLATE_NAME 与 TEMPLATE_CONTENT，使用 ensure_ascii=False 保留非 ASCII 文本。
纯文本分支直接输出返回的内容。这些细节有助于区分缺失模板和成功结果，并理解多语言输出，但不能证明 common.py 中所有覆盖规则或安全性质。本次未执行上游 PowerShell 或 Python；实际测试的是独立的追加约定教学模型。
如何选择
| 比较维度 | 方案 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
标记仍需检查的导入行为。
- 4
区分源码观察和运行验证。
可复制示例
{
"源码追踪": true,
"仅路径模式": {
"验证文档": false,
"请求不持久化": true
},
"要求任务": "检查存在",
"列入任务": "控制输出",
"已执行上游": false
}常见问题
-PathsOnly 能证明 plan.md 存在吗？
不能，它在必需文件验证之前退出。
成功 JSON 能证明规格已完整吗？
不能，它报告路径、可用文档或模板内容，不证明语义正确。
资料来源
- Spec Kit / scripts/powershell/check-prerequisites.ps1来源核查 2026-09-14
- Spec Kit / scripts/python/resolve_template.py来源核查 2026-09-14
- Spec Kit / templates/commands/analyze.md来源核查 2026-09-14