独立章节页 · 第 05 章

扩展与预设系统

这一章解释 spec-kit 如何在不改动核心流程的前提下,借助扩展与预设进行团队级定制。 适合已经理解核心工作流、准备进入进阶配置阶段的读者。

章节定位:进阶能力 关键词:Extensions / Presets 适合角色:开发负责人 / 平台团队
5.1

扩展(Extensions)

扩展用于给 spec-kit 增加新的能力,例如测试命令、系统集成、自动化钩子或自定义模板。

一句话理解

Extension 更像“插件”,重点是为 spec-kit 增加能力,而不是只改默认文案。

扩展能做什么

  • 增加新的斜杠命令,例如 V-Model 扩展带来的 9 个测试相关命令。
  • 注册生命周期钩子,例如 before_planafter_implement
  • 提供模板覆盖,影响文档生成结果。
  • 对接外部系统,如 Jira、Linear、GitHub Issues 等。

典型使用场景

测试增强

例如接入 V-Model,把测试设计和开发规格绑定在一起。

系统集成

例如把任务同步到 Jira、GitHub Issues 或其他协作平台。

自动化钩子

例如在实现前后自动运行 lint、格式化或校验动作。

命令扩展

为团队增加特定领域命令,而不是手动重复提示词。

扩展管理命令

# 搜索可用扩展
specify extension search testing

# 安装扩展(从目录)
specify extension add v-model

# 安装扩展(从 ZIP/URL,精确控制版本)
specify extension add v-model --from https://github.com/leocamello/spec-kit-v-model/archive/refs/tags/v0.4.0.zip

# 本地开发扩展
specify extension add --dev ./my-extension

# 查看已安装扩展
specify extension list

# 查看扩展详情
specify extension info v-model

# 更新扩展
specify extension update v-model

# 启用 / 禁用扩展(不卸载)
specify extension enable v-model
specify extension disable v-model

# 调整扩展优先级
specify extension set-priority v-model 5

# 管理扩展目录(catalog)
specify extension catalog list
specify extension catalog add https://example.com/catalog.json --name my-org
specify extension catalog remove my-org

# 卸载扩展
specify extension remove v-model

管理动作怎么理解

动作 作用
search 从扩展目录中搜索可安装扩展
add 安装扩展,可来自目录、URL 或本地开发目录
info 查看扩展详情、来源和功能说明
enable / disable 临时启用或停用扩展,但保留安装状态
set-priority 调整扩展参与模板解析时的优先级
remove 彻底卸载扩展
5.2

预设(Presets)

预设不是“加功能”,而是为团队或行业提供一整套模板、命令和行为覆盖方案。

一句话理解

Preset 更像“配置包 / 规则包”,重点是定制流程表达方式,而不是新增技术能力。

预设适合什么场景

  • 企业级合规要求,例如金融、医疗行业的审查步骤和强制说明。
  • 团队特定编码规范,例如前后端团队使用不同模板。
  • 行业术语定制,例如把通用词汇改成业务域统一术语。

预设管理命令

# 搜索预设
specify preset search enterprise

# 安装预设(带优先级,数字越小优先级越高)
specify preset add enterprise-safe --priority 10
specify preset add healthcare-compliance --priority 5

# 查看已安装预设
specify preset list

# 查看预设详情
specify preset info enterprise-safe

# 查看模板解析顺序
specify preset resolve spec-template

# 调整已安装预设的优先级
specify preset set-priority enterprise-safe 3

# 启用 / 禁用预设(不卸载)
specify preset enable enterprise-safe
specify preset disable enterprise-safe

# 卸载预设
specify preset remove enterprise-safe

# 管理预设目录(catalog)
specify preset catalog list
specify preset catalog add https://example.com/catalog.json --name my-org
specify preset catalog remove my-org

预设和扩展的区别

维度 扩展(Extension) 预设(Preset)
核心目标 增加新能力 覆盖默认模板与规则
典型产出 新命令、钩子、集成 新模板、团队规范、行业流程
适用人群 平台团队、工具维护者 团队负责人、规范制定者
使用场景 功能增强 行为定制
重点

模板解析优先级

这部分决定当多个地方都提供了模板覆盖时,最终到底采用哪一份。

解析顺序(从高到低)

1. .specify/templates/overrides/    ← 项目级覆盖(最高优先级)
2. .specify/presets/<preset>/       ← 预设模板(按 priority 排序)
3. .specify/extensions/*/templates/ ← 扩展模板
4. .specify/templates/              ← 核心模板(最低优先级)
模板解析优先级层叠图

图 5 · 模板解析优先级:overrides → presets → extensions → core

怎么理解这条规则

  1. 项目级 overrides 最优先:项目自己明确覆盖的模板,优先于一切。
  2. Preset 次之:适合承载团队或企业层面的规则。
  3. Extension 再后:扩展可以带模板,但通常不应该压过项目或团队显式约定。
  4. 核心模板兜底:如果上面都没覆盖,就使用 spec-kit 默认模板。
实践建议

如果只是当前项目的小范围定制,用 .specify/templates/overrides/; 如果是团队级或行业级的通用规则,优先做成 Preset; 如果需要增加命令或自动化行为,再考虑 Extension。