Spec Kit CN 扩展开发完整指南:从0到1发布你的 extension.yml、Hooks 与目录上架

原创2026-11-01 17:54:391,395 阅读
文章标签:开发工具CLI提示工程人工智能AI 技能代码生成

Spec Kit CN 扩展开发完整指南:从0到1发布你的 extension.yml、Hooks 与目录上架

Spec Kit CN 扩展开发入门:本教程带你从 0 到 1 发布属于自己的扩展,逐步讲解 extension.yml 清单字段、命令文件编写、after_tasks 等 Hooks 钩子配置,以及如何将扩展上架到社区目录(catalog),让任何人都能用一条命令安装你的扩展。

Spec Kit 完整开发指南封面

一、认识扩展:不用改核心就能加功能

Spec Kit 通过**扩展(Extension)**机制实现功能扩展:每个扩展是一个独立的小目录,包含一个 extension.yml 清单、若干个 Markdown 命令文件,以及可选的钩子和配置模板。扩展安装后会注册到项目里,AI 代理(如 Claude Code)即可调用形如 /speckit.你的扩展.命令名 的新命令。

核心好处:

  • ✅ 核心保持轻量:不需要的功能不安装
  • ✅ 独立版本管理:扩展可以单独发布、单独迭代
  • ✅ 可分享:上架目录后,用户通过 specify-cn extension search 即可发现并按名称安装

在终端中使用 Spec Kit 命令进行扩展开发演示

二、扩展目录结构:照着模板抄就行

官方已经内置了一份可复制的扩展模板,直接复制后改名就能开工:

cp -r extensions/template my-extension
cd my-extension

一个标准扩展的目录结构如下:

my-extension/
├── extension.yml        # 必填:扩展清单(扩展的"身份证")
├── README.md            # 必填:安装与使用说明
├── LICENSE              # 必填:开源许可证(推荐 MIT)
├── CHANGELOG.md         # 推荐:版本历史
├── config-template.yml  # 可选:配置模板
└── commands/            # 扩展命令(Markdown 文件)
    └── example.md

各文件的作用可对照模板了解:extensions/template/README.md、清单模板 extensions/template/extension.yml、示例命令 extensions/template/commands/example.md。

三、extension.yml 清单:逐字段速查

extension.yml 是扩展的"身份证",CLI 靠它完成校验、安装和注册。必填字段只有 4 个,其余按需添加:

字段 必填 说明 示例
schema_version ✅ 清单模式版本,固定写 "1.0" "1.0"
extension.id ✅ 小写字母、数字、连字符,不能带下划线 jira-sync
extension.name ✅ 人类可读名称 Jira Sync
extension.version ✅ 语义化版本 X.Y.Z 1.0.0
extension.description ✅ 一句话简介(建议 100 字符内) 同步任务到 Jira
requires.speckit_version ✅ 兼容的 Spec Kit 版本范围 ">=0.1.0"
provides.commands ✅ 至少 1 个命令 见下
hooks ❌ 集成钩子,见第五节 —
provides.config ❌ 配置文件模板 —
tags ❌ 目录搜索标签(推荐 2~5 个) jira、issue-tracking

命令命名必须遵循 speckit.{扩展id}.{命令名} 规则,例如扩展 id 是 my-ext,命令名就不能叫 hello,而要叫 speckit.my-ext.hello。一个最小可用的清单长这样:

schema_version: "1.0"
extension:
  id: "my-ext"
  name: "My Extension"
  version: "1.0.0"
  description: "My custom extension"
requires:
  speckit_version: ">=0.1.0"
provides:
  commands:
    - name: "speckit.my-ext.hello"
      file: "commands/hello.md"
      description: "Say hello"
tags:
  - "example"

完整的字段参考(含 requires.tools 外部依赖、defaults 默认配置、config_schema 等)请查阅官方文档:extensions/EXTENSION-DEVELOPMENT-GUIDE.md。

四、命令文件:一个 Markdown 就是 AI 能执行的命令

命令文件放在 commands/ 下,格式 = YAML frontmatter + Markdown 正文。frontmatter 里必须写 description,正文里用 $ARGUMENTS 占位符接收用户输入:

---
description: "Say hello command"
tools:
  - 'some-tool/function'     # 可选:命令用到的 MCP 工具
scripts:
  sh: ../../scripts/bash/helper.sh   # 可选:辅助脚本
---
# Hello Command

## User Input

$ARGUMENTS

## Steps

1. 向用户问好
2. 演示扩展工作正常

安装后,这个文件会被复制到 AI 代理的命令目录(如 Claude Code 的 .claude/commands/speckit.my-ext.hello.md),用户直接在对话框里输入 /speckit.my-ext.hello world 即可触发。

PowerShell 终端中运行 specify-cn CLI 的演示

五、Hooks 钩子:让扩展"自动跑"

命令是用户手动触发的,而 Hooks(钩子) 让扩展能在核心命令执行完后自动介入,这是扩展最有价值的功能之一。目前可用的钩子点:

  • after_tasks:/speckit.tasks 生成任务列表之后
  • after_implement:/speckit.implement 完成之后(规划中)

配置非常简单,在 extension.yml 中加一段:

hooks:
  after_tasks:
    command: "speckit.my-ext.check"   # 必须是 provides.commands 里声明的命令
    optional: true                    # true=执行前询问用户,false=自动执行
    prompt: "运行检查命令?"
    description: "任务生成后自动做合规检查"

典型玩法:生成任务后自动同步到 Jira、自动跑一次质量检查、自动打标签……社区目录里不少成熟扩展(如 jira、cleanup、plan-review-gate)都依赖 after_tasks 钩子实现工作流自动化,可以参考 extensions/catalog.community.json 里的真实条目。

六、本地测试扩展:一条命令搞定

开发过程中无需打包,用 --dev 指向本地目录即可在真实项目里验证:

# 在你的 Spec Kit 项目中(含 .specify/ 目录)
specify-cn extension add --dev /path/to/my-extension
specify-cn extension list        # 应显示:✓ My Extension (v1.0.0)
specify-cn extension remove my-ext   # 卸载

验证命令是否注册成功,可以看 AI 代理的命令目录是否出现了 speckit.my-ext.*.md 文件。常见的安装报错(如 Invalid extension ID、Command file not found)及修复方式,官方指南的"故障排除"一节都有对照表:extensions/EXTENSION-DEVELOPMENT-GUIDE.md。

七、上架目录:让你的扩展被全世界搜到

本地测试通过后,分两步发布:

第 1 步:打发布版本。 在扩展仓库中创建语义化版本标签(如 v1.0.0)并发布 Release,生成可下载的 ZIP 归档地址,例如:

https://<你的仓库平台>/<你的组织>/spec-kit-my-ext/archive/refs/tags/v1.0.0.zip

第 2 步:提交目录 PR。 Spec Kit 采用"双目录"机制:

具体操作:Fork 仓库 → 在 catalog.community.json 的 extensions 对象中按条目模式添加你的扩展(name、id、version、download_url、requires、provides、tags 等)→ 提交 Pull Request 等待维护者审查。目录条目的完整字段模式见 extensions/EXTENSION-PUBLISHING-GUIDE.md 的"附录:目录模式"。

提交前请过一遍官方检查清单:

  • ✅ 有效的 extension.yml 清单
  • ✅ 包含安装和使用说明的 README
  • ✅ 包含 LICENSE 文件
  • ✅ 已创建带语义化版本号的 Release(如 v1.0.0)
  • ✅ 在真实项目中测试过,所有命令可用

八、审查、验证与后续维护

PR 提交后,维护者会做格式与策略审查(通常 3~7 个工作日),通过后即可被 specify-cn extension search 搜到;通过更严格的功能、安全、质量审查后,扩展还会获得 verified: true 标记,出现在 specify-cn extension search --verified 结果中,获得更多信任与曝光。

后续版本更新流程:

  1. 更新 extension.yml 中的 version 和 CHANGELOG.md
  2. 打新标签、发布新 Release
  3. 再提交一个 PR,更新目录条目中的 version、download_url 和 updated_at

总结:从 0 到 1 的路径图

步骤 动作 关键产出
1 复制 extensions/template/ 模板 扩展骨架目录
2 编写 extension.yml + 命令文件 可安装的最小扩展
3 配置 hooks.after_tasks(可选) 自动化能力
4 specify-cn extension add --dev 本地验证 测试通过的扩展
5 打 Release → PR 到 catalog.community.json 目录上架

想深入学习,还可以阅读这些官方文档:

现在,复制模板、填好 extension.yml、跑通第一个 --dev 安装——你的 Spec Kit CN 扩展离上架只差一个 PR 的距离。🚀

登录后查看全文
spec-kit-cn