从 CHANGELOG 读 Spec Kit218 个版本如何把 SDD 工具演进到 1.0【免费下载链接】spec-kit Toolkit to help you get started with Spec-Driven Development项目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit本文以 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的规则一致——每次发版后主干版本号立即推进为下一个版本的.dev0PEP 440 开发版说明 1.0.2 是最近一次正式发版而主干已在开发 1.0.3。二、版本语义与发布节奏从 218 个版本条目中可以读出清晰的三段式发布节奏0.0.x 快速试错期2025-08 ~ 2026-02约 100 个版本版本号几乎逐日递增0.0.1 到 0.0.102条目多为简短的Update README.md、fix: ...等自由文本记录 Codex、Gemini、Cursor、Windsurf 等早期 Agent 支持的逐次接入。这一段是日志的考古层格式尚不规范。0.1.x ~ 0.9.x 特性堆积期2026-03 ~ 06约 90 个版本条目全面规范化feat/fix(scope) PR 编号成为标准句式发版频率仍是每数天一版。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.932026-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 支持.extensionignore0.3.2 引入 preset 的 enable/disable0.10.0 将 git 扩展改为 opt-in 并移除--no-git0.16.2 起扩展清单支持provides.templates与provides.scripts#4012。2. 可插拔预设系统0.3.02026-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.52026-03-23 ~ 04-02这是一段罕见的Stage 1~6分阶段迁移记录值得逐条读版本日志条目含义0.4.0feat(cli): embed core pack in wheel for offline/air-gapped deployment (#1803)核心资产嵌入 Python 包离线/隔离环境可初始化0.4.4Stage 1: Integration foundation — base classes, manifest system, and registry (#1925)集成基类、清单与注册表0.4.4Stage 2: Copilot integration — proof of concept (#2035)Copilot 试点0.4.5Stage 3: Standard markdown integrations — 19 agents migrated (#2038)19 个 Agent 迁移0.4.5Stage 4: TOML integrations — gemini and tabnine migrated (#2050)TOML 格式 Agent 迁移0.4.5Stage 5: Skills, Generic Option-Driven Integrations (#2052)技能与通用选项驱动0.4.5Stage 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.02026-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_json0.11.1 加入output_format: json。仓库内的示例工作流见 workflows/speckit/workflow.yml。5. 从原语到打包1.0 的稳定形态0.11.4 ~ 1.0.20.11.4 引入specify bundle命令#3070把扩展、预设、工作流与步骤打包为面向角色/团队的成套配置0.16.5 增加feature-assessagentic workflow#41860.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.5fix(agents): block directory traversal in command write paths (#2296)0.8.0fix: --force now overwrites shared infra files (#2320)与fix(agents)类路径问题0.10.2fix(presets): harden preset URL installs against unsafe redirects (#2911)0.11.7harden: reject shellTrue 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/38190.16.2fix: cap stdin read at 1 MiB to prevent DoS (#3857)。这些条目与 pyproject.toml 末尾的 ruff 配置相互印证——extend-select [S602, S604, S605]显式锁定 subprocess 安全姿态注释写明任何shellTrue的重新引入都必须在代码评审中以# 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.15fix: PS 5.1 compat — replace non-ASCII chars in shipped PowerShell scripts (#2709)0.9.3fix(cli): force UTF-8 stdout/stderr on Windows (#2817)0.11.1fix: disable Rich Live transient mode on Windows to prevent PS 5.1 hang (#2938)0.16.5fix(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.6feat(scripts): add Python check-prerequisites PoC (#3302)→ 0.12.4feat(cli): add py script type Python interpreter resolution (#3278)→ 0.13.2feat(scripts): port create-new-feature, setup-plan and setup-tasks to Python (#3386)→ 0.12.16feat(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 用三种方式标记行为不兼容变更升级前应全部检索feat!前缀0.10.0 的feat!: remove legacy --ai, --ai-commands-dir, and --ai-skills flags (0.10.0) (#2872)是唯一一次feat!移除旧--ai系列参数。日志中还有 0.7.1chore: deprecate --ai flag in favor of --integration (#2218)与 0.8.2feat(init): deprecate --no-git flag, gate deprecations at v0.10.0 (#2357)的预告链——先 deprecate、后按版本门控移除是该项目的固定模式。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同理。gate deprecations at vX.Y.0措辞日志会显式写出破坏性变更的生效版本如 0.10.0 移除--no-git的条目。此外 0.5.1 的fix: pin typer0.24.0 and click8.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 先落 stubfeat(cli): add specify self check and self upgrade stub (#2316)0.9.3 正式实现feat(cli): implement specify self upgrade (#2475)。实现位于 src/specify_cli/_version.pyself_check用importlib.metadata读取已安装分布的版本而非 pyproject 值self_upgrade则按 uv-tool / pipx / 源码检出三级探测安装方式只支持前两者自动升级源码检出则提示git pull pip install -e .。七、关键版本速查表版本日期日志中的标志性条目源码证据0.0.932026-02-10模块化扩展系统 (#1551)extensions/ 四个内置扩展0.3.02026-03-13可插拔预设系统 (#1787)、specify doctor(#1828)src/specify_cli/presets/0.4.4~0.4.52026-04-01~02集成架构 Stage 1~6 重写src/specify_cli/integrations/0.7.02026-04-14工作流引擎 目录系统 (#2158)src/specify_cli/workflows/0.7.22026-04-16集成目录发现、版本化、社区分发 (#2130)integrations/catalog.json0.9.32026-06-03specify self upgrade实现 (#2475)_version.py0.10.02026-06-09feat!移除--ai系列git 扩展转 opt-in--no-git门控移除0.11.02026-06-16工作流步骤目录社区可安装步骤类型(#2394)workflows/step-catalog.json0.13.22026-07-21核心脚本移植到 Python (#3386)scripts/python/0.16.52026-08-19feature-assess agentic workflow (#4186)extensions/assess/1.0.0 / 1.0.12026-08-21首个稳定版switch 步骤cases校验修复 (#4144)pyproject.toml现 1.0.3.dev01.0.22026-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的版本自检这份日志本身就构成了一张可检索、可验证的升级路线图。【免费下载链接】spec-kit Toolkit to help you get started with Spec-Driven Development项目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考