从 CHANGELOG 读 Spec Kit：218 个版本如何把 SDD 工具演进到 1.0

本文以 Spec Kit 仓库根目录的 CHANGELOG.md 为主体，完整拆解这份变更日志的结构约定、版本号语义与发布节奏，并结合 docs/history.md 和 src/specify_cli/ 源码，还原 Spec Kit 从 0.0.1 到 1.0.2 的五个架构里程碑——扩展系统、预设系统、集成架构、工作流引擎与社区目录——以及贯穿其中的安全加固与跨平台治理线索。读完你可以独立阅读并检索这份日志，准确定位任意功能的引入版本、破坏性变更边界与升级注意点。

一、CHANGELOG.md 的文件结构与阅读方法

CHANGELOG.md 是一份 2777 行、覆盖 218 个版本条目（## [版本号] - 日期）与 1684 条变更项的完整发布记录，时间跨度从 2025-08-22 的 0.0.1 到 2026-08-31 的 1.0.2。其固定结构如下：

• 文件顶部第 3 行是一条 HTML 注释 <!-- insert new changelog below this comment -->，它标记了新版本条目的插入点——每次发版时，新版本的记录都追加在这条注释的正下方，旧版本依次下移。这意味着日志按"时间倒序"组织，最新版本永远最靠上。
• 每个版本是一个 H2 标题，格式为 ## [版本号] - YYYY-MM-DD，例如 ## [1.0.2] - 2026-08-31。
• 版本正文统一使用 H3 的 ### Changed 分组，条目为无序列表。

每条变更项采用 Conventional Commit 风格 的书写规范（自约 0.0.87 之后逐步统一，到 0.5.x 起完全成型）：

<类型>(<作用域>): <小写祈使句描述> (#PR 编号)

示例：
- feat(workflows): make shell step timeout configurable (#3327) (#3328)
- fix(bundler): reject non-string catalog entry tag members (#4318)
- feat!: remove legacy --ai, --ai-commands-dir, and --ai-skills flags (0.10.0) (#2872)

• 类型前缀：feat（新功能）、fix（缺陷修复）、docs、chore、test、refactor、harden（安全加固）、feat!（破坏性变更）。
• 作用域括号：(workflows)、(extensions)、(presets)、(bundler)、(integrations)、(scripts)、(powershell)、(init)、(auth)、(templates) 等，与 src/specify_cli/ 下的模块划分一一对应，可按作用域过滤检索。
• PR 编号：括号内 (#NNNN) 是拉取请求编号，是追溯完整 diff 的唯一入口。
• 社区目录更新使用固定句式 Add/Update <名称> extension/preset/bundle to community catalog (#NNNN)，可用这句话作为正则一次性筛出所有生态条目。

一个细节印证了日志与源码的同步关系：每个版本末尾都有形如 chore: release 1.0.1, begin 1.0.2.dev0 development 的条目，这与 pyproject.toml 中当前版本字段 version = "1.0.3.dev0" 的规则一致——每次发版后，主干版本号立即推进为下一个版本的 .dev0（PEP 440 开发版），说明 1.0.2 是最近一次正式发版，而主干已在开发 1.0.3。

二、版本语义与发布节奏

从 218 个版本条目中可以读出清晰的三段式发布节奏：

1. 0.0.x 快速试错期（2025-08 ~ 2026-02，约 100 个版本）：版本号几乎逐日递增（0.0.1 到 0.0.102），条目多为简短的 Update README.md、fix: ... 等自由文本，记录 Codex、Gemini、Cursor、Windsurf 等早期 Agent 支持的逐次接入。这一段是日志的"考古层"，格式尚不规范。
2. 0.1.x ~ 0.9.x 特性堆积期（2026-03 ~ 06，约 90 个版本）：条目全面规范化，feat/fix(scope) + PR 编号成为标准句式；发版频率仍是每数天一版。
3. 1.0 稳定期（2026-08-21 起）：1.0.0 与 1.0.1 同日（2026-08-21）发布，1.0.2 于 2026-08-31 发布，节奏明显放缓，条目质量以 fix 硬化修复与社区目录更新为主。

关于"1.0.0 是什么"，docs/history.md 给出了明确定位：1.0.0 没有冻结任何模型，只是给已经成型的五原语模型（Integrations、Extensions、Presets、Workflows、Workflow steps）一个整数版本号；该文档同时记录，截至一周年时文档站点报告的生态规模是 38 个编码代理集成、157 个社区扩展、33 个预设与 270+ 贡献者。从源码结构看，src/specify_cli/integrations/ 目录当前包含 39 个按 Agent 命名的子包（claude、copilot、codex、gemini、goose、kimi、qwen 等），与这份数字相互印证。

三、五个架构里程碑：日志与源码的对照

CHANGELOG 中最有价值的是几条"架构级"条目。以下按时间顺序列出，并给出源码中的落地位置：

1. 模块化扩展系统（0.0.93，2026-02-10）

日志条目：Add modular extension system (#1551)。这是整个生态的地基，使核心流程不再需要膨胀即可添加命令、模板、脚本与钩子。落地证据：

• 仓库内 extensions/ 目录保留四个内置扩展：extensions/git、extensions/agent-context、extensions/assess、extensions/bug，均以 extension.yml 清单驱动；
• pyproject.toml 的 force-include 段显示这四个扩展被直接打进 wheel 的 core_pack，可通过 specify extension add <name> 离线安装；
• 扩展规范文档为 extensions/EXTENSION-API-REFERENCE.md 与 extensions/RFC-EXTENSION-SYSTEM.md。

后续相关条目值得注意：0.2.1 支持 .extensionignore；0.3.2 引入 preset 的 enable/disable；0.10.0 将 git 扩展改为 opt-in 并移除 --no-git；0.16.2 起扩展清单支持 provides.templates 与 provides.scripts（#4012）。

2. 可插拔预设系统（0.3.0，2026-03-13）

日志条目：feat(presets): Pluggable preset system with catalog, resolver, and skills propagation (#1787)，同版本还有 Add specify doctor command for project health diagnostics (#1828)。预设让模板与命令可被替换或组合，而 CLI 体验不变。落地证据：src/specify_cli/presets/ 包、仓库内 presets/lean 与 presets/constitution-sync 两个内置预设（同样被打包进 wheel core_pack），以及组合策略文档 presets/ARCHITECTURE.md。0.8.0 的条目 feat(presets): Composition strategies (prepend, append, wrap) for templates, commands, and scripts (#2133) 补齐了三种组合策略。

3. 集成架构重写（0.4.0 ~ 0.4.5，2026-03-23 ~ 04-02）

这是一段罕见的"Stage 1~6"分阶段迁移记录，值得逐条读：

版本	日志条目	含义
0.4.0	feat(cli): embed core pack in wheel for offline/air-gapped deployment (#1803)	核心资产嵌入 Python 包，离线/隔离环境可初始化
0.4.4	Stage 1: Integration foundation — base classes, manifest system, and registry (#1925)	集成基类、清单与注册表
0.4.4	Stage 2: Copilot integration — proof of concept (#2035)	Copilot 试点
0.4.5	Stage 3: Standard markdown integrations — 19 agents migrated (#2038)	19 个 Agent 迁移
0.4.5	Stage 4: TOML integrations — gemini and tabnine migrated (#2050)	TOML 格式 Agent 迁移
0.4.5	Stage 5: Skills, Generic & Option-Driven Integrations (#2052)	技能与通用选项驱动
0.4.5	Stage 6: Complete migration — remove legacy scaffold path (#2063)	移除旧脚手架路径

对应源码即 src/specify_cli/integrations/：base.py（基类）、manifest.py（清单）、catalog.py（目录）、_commands.py/_install_commands.py/_scaffold_commands.py 等命令层，每个 Agent 一个子包。0.7.2 的 feat: Integration catalog — discovery, versioning, and community distribution (#2130) 又为其加上社区可发现的分发层（integrations/catalog.json 与 integrations/catalog.community.json）。

4. 工作流引擎与步骤目录（0.7.0，2026-04-14 起）

Add workflow engine with catalog system (#2158) 是日志中体量最大的子系统起点。此后数十个版本围绕它持续加固：0.9.2 加入 continue_on_error 步骤字段；0.9.4 为 run/resume/status 增加 --json 输出；0.10.4 让 fan-out 的 items 表达式解析失败时"大声失败"；0.12.16 暴露 workflow 源目录给步骤；0.12.13 使 shell 步骤 timeout 可配置；0.15.0 通过 feat: first-class agent-native runtime hooks for integrations (#3704) 引入运行时钩子；0.11.0 的 Add workflow step catalog — community-installable step types (#2394) 则把步骤类型本身变成社区可安装的组件。

源码落地位于 src/specify_cli/workflows/：engine.py 中的 WorkflowDefinition.validate_workflow（静态校验）、RunState（带原子写入的运行状态持久化）、execute/resume（断点恢复）；steps/ 下是 11 个内置步骤类型（init、prompt、command、shell、gate、if_then、switch、while_loop、do_while、fan_in、fan_out），各自实现 execute 与 validate 两个接口；overlays/ 子包提供工作流叠加层（0.12.x 起的 overlay 合并与 workflow resolve 命令）；expressions.py 实现 {{ }} 表达式与过滤器（default、join、map、contains、from_json 等，0.11.2 加入 from_json，0.11.1 加入 output_format: json）。仓库内的示例工作流见 workflows/speckit/workflow.yml。

5. 从原语到打包：1.0 的稳定形态（0.11.4 ~ 1.0.2）

0.11.4 引入 specify bundle 命令（#3070），把扩展、预设、工作流与步骤打包为面向角色/团队的成套配置；0.16.5 增加 feature-assess agentic workflow（#4186）；0.12.4 加入 label 驱动的 bug-fix 与 bug-test 工作流；0.13.0 内置 opt-in 的 assess 扩展（intake → research → define → shape → decide 流程，见 extensions/assess/README.md）。到 1.0.0，日志中的"五大原语"齐备：integrations/、extensions/、presets/、workflows/（含步骤目录）与 bundles/（bundles/catalog.community.json）。

1.0 发布后的条目以高价值硬化修复为主，例如 1.0.2 中：fix(auth): reject malformed URL ports before credential matching (#4362)、fix(presets): validate catalog URL port, not just hostname (#4341)、fix: decode feature.json as UTF-8 in Windows PowerShell (#4359)、fix(events): stop event run crashing on every piped stdin payload (#4326)——每一条都对应一个具体故障场景，可直接作为升级检查单使用。

四、贯穿全史的两条治理线索

安全加固（harden / fix 安全条目）

日志中可以按 harden: 前缀和 "reject/validate/bound" 关键词筛出一条完整的安全演进线：0.7.5 fix(agents): block directory traversal in command write paths (#2296)；0.8.0 fix: --force now overwrites shared infra files (#2320) 与 fix(agents) 类路径问题；0.10.2 fix(presets): harden preset URL installs against unsafe redirects (#2911)；0.11.7 harden: reject shell=True in run_command (#3132) 与 verify catalog archive sha256 before install (#3080)；0.14.4 起 harden: bound HTTP reads and enforce strict redirects (#3140)；0.15.0/0.15.1 连续消除 RunState.load 与文件删除的 TOCTOU 竞态（#3839、#3855、#3811/3815/3819）；0.16.2 fix: cap stdin read at 1 MiB to prevent DoS (#3857)。这些条目与 pyproject.toml 末尾的 ruff 配置相互印证——extend-select = ["S602", "S604", "S605"] 显式锁定 subprocess 安全姿态，注释写明任何 shell=True 的重新引入都必须在代码评审中以 # noqa 明示。此外 0.12.12 的 fix(bundle): reject file:// / local download_url — catalog URLs are HTTPS-only (#3344) 与 0.13.3 的 fix(workflows): validate every redirect hop when fetching workflow/step catalogs (#3637) 说明：目录下载链路只接受 HTTPS，且每一跳重定向都会重新校验。

跨平台与编码一致性

Windows PowerShell 是日志中出现频率最高的问题域：0.8.15 fix: PS 5.1 compat — replace non-ASCII chars in shipped PowerShell scripts (#2709)；0.9.3 fix(cli): force UTF-8 stdout/stderr on Windows (#2817)；0.11.1 fix: disable Rich Live transient mode on Windows to prevent PS 5.1 hang (#2938)；0.16.5 fix(powershell): stop Out-Null swallowing setup-tasks AVAILABLE_DOCS lines (#4188)。bash 侧则有 0.12.2 的 bash 3.2 可移植性修复与 0.9.1 起的大量 UTF-8 编码声明。另一条线是脚本类型的三平台等价：0.12.6 feat(scripts): add Python check-prerequisites PoC (#3302) → 0.12.4 feat(cli): add py script type & Python interpreter resolution (#3278) → 0.13.2 feat(scripts): port create-new-feature, setup-plan and setup-tasks to Python (#3386) → 0.12.16 feat(extensions): port git extension scripts to Python (#3400)。仓库 scripts/ 目录下的 bash/powershell/python 三套同名脚本（check-prerequisites、create-new-feature、setup-plan、setup-tasks、resolve-template）以及 pyproject.toml 中 scripts/python 被打入 wheel 的 force-include，正是这条线的当前形态；仓库内的双实现等价测试（如 tests/test_git_extension_python_parity.py）也保证了三套实现的输出一致。

五、破坏性变更如何从日志中识别

Spec Kit 用三种方式标记行为不兼容变更，升级前应全部检索：

1. feat! 前缀：0.10.0 的 feat!: remove legacy --ai, --ai-commands-dir, and --ai-skills flags (0.10.0) (#2872) 是唯一一次 feat!，移除旧 --ai 系列参数。日志中还有 0.7.1 chore: deprecate --ai flag in favor of --integration (#2218) 与 0.8.2 feat(init): deprecate --no-git flag, gate deprecations at v0.10.0 (#2357) 的预告链——"先 deprecate、后按版本门控移除"是该项目的固定模式。
2. remove/retire 关键词：0.12.3 与 0.12.2 连续退役三个集成（retire Roo Code integration — extension shut down (#3212)、retire Windsurf integration — absorbed into Cognition Devin (#3213)、retire iflow integration — product discontinued (#3211)），均注明原因；0.4.5 的 Stage 6: remove legacy scaffold path 同理。
3. gate deprecations at vX.Y.0 措辞：日志会显式写出破坏性变更的生效版本，如 0.10.0 移除 --no-git 的条目。

此外 0.5.1 的 fix: pin typer>=0.24.0 and click>=8.2.1 to fix import crash (#2136) 提示：依赖下限本身就是兼容性契约，当前 pyproject.toml 仍维持这两个下限。

六、实用检索方法与交叉验证

CHANGELOG 面向人与脚本双读，常用检索方式（在本仓库只读查看即可）：

# 1) 找出某个子系统的全部变更（按作用域）
grep -E '^- (feat|fix)(\(workflows\))' CHANGELOG.md

# 2) 找出所有破坏性变更
grep -n 'feat!' CHANGELOG.md

# 3) 找出某次发版之间的全部条目（版本号是时间倒序，用 sed 截取）
sed -n '/^## \[1.0.2\]/,/^## \[1.0.0\]/p' CHANGELOG.md

# 4) 社区生态条目
grep -E 'to community catalog' CHANGELOG.md | head -30

# 5) 统计版本数与条目数
grep -c '^## \[' CHANGELOG.md   # 218
grep -c '^- ' CHANGELOG.md       # 1684

交叉验证的两个入口：

• docs/history.md：以"里程碑"视角叙述同一历史（2025-08 奠基、2026-02~04 原语建设期、2026-06~07 组合应用期、2026-08 一周年），并注明两段维护期（2025-08 ~ 2026-01 创始期、2026-01 起社区维护期）。当你需要"某原语是何时、为什么出现"的叙事性答案时看它，需要精确条目与 PR 号时回到 CHANGELOG。
• 版本号语义可用 specify self check 与 specify self upgrade 验证——0.7.5 先落 stub（feat(cli): add specify self check and self upgrade stub (#2316)），0.9.3 正式实现（feat(cli): implement specify self upgrade (#2475)）。实现位于 src/specify_cli/_version.py：self_check 用 importlib.metadata 读取已安装分布的版本（而非 pyproject 值），self_upgrade 则按 uv-tool / pipx / 源码检出三级探测安装方式，只支持前两者自动升级，源码检出则提示 git pull && pip install -e .。

七、关键版本速查表

版本	日期	日志中的标志性条目	源码证据
0.0.93	2026-02-10	模块化扩展系统 (#1551)	extensions/ 四个内置扩展
0.3.0	2026-03-13	可插拔预设系统 (#1787)、specify doctor (#1828)	src/specify_cli/presets/
0.4.4~0.4.5	2026-04-01~02	集成架构 Stage 1~6 重写	src/specify_cli/integrations/
0.7.0	2026-04-14	工作流引擎 + 目录系统 (#2158)	src/specify_cli/workflows/
0.7.2	2026-04-16	集成目录：发现、版本化、社区分发 (#2130)	integrations/catalog.json
0.9.3	2026-06-03	specify self upgrade 实现 (#2475)	_version.py
0.10.0	2026-06-09	feat! 移除 --ai 系列；git 扩展转 opt-in	--no-git 门控移除
0.11.0	2026-06-16	工作流步骤目录（社区可安装步骤类型）(#2394)	workflows/step-catalog.json
0.13.2	2026-07-21	核心脚本移植到 Python (#3386)	scripts/python/
0.16.5	2026-08-19	feature-assess agentic workflow (#4186)	extensions/assess/
1.0.0 / 1.0.1	2026-08-21	首个稳定版；switch 步骤 cases 校验修复 (#4144)	pyproject.toml（现 1.0.3.dev0）
1.0.2	2026-08-31	目录清单类型加固、auth URL 端口校验 (#4318/#4362/#4341)	src/specify_cli/authentication/

八、小结

CHANGELOG.md 是 Spec Kit 事实层最密集的一份文档：218 个版本条目完整保留了从"单 Agent 脚手架"到"五原语可组合工具链"的每一步决策。对使用者，它回答三个问题——某命令/参数从哪个版本可用、哪次升级会改变既有行为、某类报错在哪个版本修复；对开发者，scope(PR 编号) 的条目格式允许按子系统精确回放历史，再与 docs/history.md 的里程碑叙事和 src/specify_cli/ 的当前实现三方对照。结合 specify self check 的版本自检，这份日志本身就构成了一张可检索、可验证的升级路线图。