Spec Kit 扩展系统详解：目录（Catalog）机制、安装流程与社区扩展接入实战

本文基于 spec-kit 仓库中的 extensions/README.md 展开，系统讲解 Spec Kit 扩展系统的核心机制：默认目录与社区目录的双目录（catalog stack）设计、组织级目录定制、specify extension 系列命令的完整用法，以及将扩展提交到社区目录的流程。读完本文，你将能够为自己的团队搭建受控的扩展目录、从目录或 URL 安装扩展，并理解目录解析顺序、安装安全边界等底层实现。

1. 扩展系统是什么：为 Spec Kit 增加功能而不臃肿核心

Spec Kit 的扩展（Extension）是一类模块化功能包：它以命令（command）、钩子（hook）、脚本和配置模板的形式，把新功能注入到 Spec Kit 项目中，而核心框架本身保持轻量。extensions/README.md 给出的定位是：

Extension system for Spec Kit - add new functionality without bloating the core framework.

从仓库结构看，核心扩展就存放在 extensions/ 目录下，例如：

• git 扩展：特性分支创建、分支编号、校验与远端检测；
• bug 扩展：缺陷报告评估、修复与验证工作流；
• assess 扩展：在正式开发前对想法做 intake、research、define、shape、decide 五段式评估；
• agent-context 扩展：管理编码代理上下文文件（如 CLAUDE.md、copilot-instructions.md）。

每个扩展目录都包含 extension.yml 清单（manifest）、commands/ 下的命令文件（Markdown 提示词）以及可选的 scripts/（bash/powershell/python 三套实现）。命令名遵循 speckit.{扩展ID}.{命令} 命名空间约定，例如 speckit.git.commit、speckit.bug.fix，从命名规则上避免多个扩展之间的命令冲突。

2. 双目录设计：catalog.json 与 catalog.community.json

Spec Kit 的扩展分发建立在两个目录文件之上，二者职责完全不同，这是理解整个扩展系统的关键。

2.1 你的目录（catalog.json）：默认可安装的来源

• 用途：Spec Kit CLI 默认使用的上游扩展目录（default upstream catalog）；
• 默认状态：在上游仓库中按设计为空——由你或你的组织在 fork/副本中填入信任的扩展；
• 位置（上游）：extensions/catalog.json；
• CLI 默认行为：specify extension 系列命令默认使用上游目录 URL，除非被覆盖；
• 组织目录：通过环境变量 SPECKIT_CATALOG_URL 指向组织自己的 fork 或托管目录 JSON 即可替换上游默认；
• 自定义方式：把社区目录中的条目复制进组织目录，或直接添加自己的扩展。

原文档给出的覆盖示例：

# 用组织目录覆盖默认的 upstream catalog
export SPECKIT_CATALOG_URL="https://your-org.com/spec-kit/catalog.json"
specify extension search  # 现在使用的是你组织的目录，而不是上游默认

当前仓库中 extensions/catalog.json 的实际内容印证了这一点：它目前只登记了 4 个 spec-kit-core 作者、bundled: true 的核心扩展（agent-context、assess、bug、git），schema_version 为 "1.0"，结构为顶层 extensions 对象 + 每个扩展的 name / id / version / description / repository / tags 字段。

2.2 社区参考目录（catalog.community.json）：只读发现区

• 用途：浏览社区贡献的可用扩展；
• 状态：Active，包含社区提交的扩展；
• 位置：extensions/catalog.community.json（当前仓库中该文件已相当庞大，收录了数百个条目的完整元数据，每条含 download_url、repository、license、requires、tags、verified 等字段）；
• 用途定位：仅作发现（discovery）用的参考目录；
• 提交通道：社区可通过 issue 模板提交扩展。

文档在此处明确了一条安全声明，原文要点：社区扩展由各自作者独立创建和维护；维护者只校验目录条目的完整性和格式正确性，不审查、不审计、不背书、不支持扩展代码本身；安装前请自行审查扩展源码，后果自负。

2.3 从源码看目录解析的真实顺序

目录解析实现（get_active_catalogs）确认了 CLI 查找目录的优先级，共四级：

1. SPECKIT_CATALOG_URL 环境变量 —— 单一目录替换所有默认目录（向后兼容）；若 URL 不是内置默认值，还会向 stderr 打印一次"仅使用你信任的来源"的警告；
2. 项目级 .specify/extension-catalogs.yml；
3. 用户级 ~/.specify/extension-catalogs.yml；
4. 内置默认目录栈：优先级 1 的 catalog.json（install_allowed=True）+ 优先级 2 的 catalog.community.json（install_allowed=False，仅发现）。

也就是说，社区目录在默认栈中永远不可直接安装——specify extension search 会把社区扩展显示出来并标注来源，但要安装必须走"经你审查后用 --from URL 直接安装"或"把它收录进自己控制的目录"这两条路径。这一点在 catalog 子命令的帮助文本 中被进一步强化为设计原则："社区目录是未经验证的（unvetted），可搜索但不可安装……永远不要把一个仅发现目录翻转为 install_allowed——那就是审查边界（the vetting boundary）"。

3. 让团队可用的两种方式：精选目录 vs 直接 URL

原文档指出"你控制你的团队能发现并安装哪些扩展"，并给出两个选项。

3.1 选项一：精选目录（Curated Catalog，组织推荐）

操作流程四步：

1. 发现（Discover）：从多个来源找扩展——
   • 浏览 catalog.community.json 中的社区扩展；
   • 在组织内部仓库中寻找私有/内部扩展；
   • 从可信第三方发现扩展；
2. 评审（Review）：评审扩展，决定放行哪些；
3. 添加（Add）：把选中扩展的条目加入你自己的 catalog.json；
4. 团队成员使用：
   • specify extension search 展示你的精选目录；
   • specify extension add <name> 按名从目录安装。

收益：完全控制可用扩展范围、团队一致性、组织级审批流程。示例：把 catalog.community.json 里的一条复制到你的 catalog.json，团队成员即可按名字发现并安装它。

3.2 选项二：直接 URL（临时/临时性使用）

跳过目录策展，成员直接用 URL 安装：

specify extension add <extension-name> --from https://github.com/org/spec-kit-ext/archive/refs/tags/v1.0.0.zip

收益：一次性测试或私有扩展场景下快速。代价（Tradeoff）：以这种方式安装的扩展不会出现在其他团队成员的 specify extension search 结果里——除非你也把它加进 catalog.json。

3.3 URL 安装背后的安全加固

install_extension_from_url 的源码注释说明，--from 路径复用了与目录安装相同的下载加固链：HTTPS 强制、目录鉴权 + 防重定向的 URL 打开、50 MiB 上限的响应读取、归档格式探测（ZIP 或 tar.gz/tgz）、以及 TOCTOU 安全的临时下载文件消费。结合 下载安全模块 可以确认：非 HTTPS（且非 localhost 的测试用 HTTP）的下载 URL 会被拒绝，这也是用户指南中"URL 必须使用 HTTPS（localhost 测试除外）"要求的实现依据。

4. 安装与管理扩展：specify extension 命令全貌

原文档给出的最小安装集：

# 从你的精选目录（按名字）
specify extension search                  # 查看目录里有什么
specify extension add <extension-name>    # 按名字安装

# 直接从 URL（绕过目录）
specify extension add <extension-name> --from https://github.com/<org>/<repo>/archive/refs/tags/<version>.zip

# 列出已安装扩展
specify extension list

对照 扩展命令处理器源码，specify extension 实际注册的完整命令集为：

命令	作用
specify extension list	列出已安装扩展及其命令/hook 状态
specify extension search [关键词]	跨所有激活目录搜索（默认可搜索社区目录）
specify extension info <name>	查看描述、依赖、命令、hooks、链接与安装状态
specify extension add <name>	从目录按名安装
specify extension add <name> --from <url>	直接从 URL 安装
specify extension add --dev <path>	本地目录安装（开发调试用）
specify extension remove <name>	移除（支持 --keep-config、--force）
specify extension enable / disable <name>	临时启用/停用，无需卸载
specify extension update [name]	检查并升级扩展
specify extension set-priority <name> <n>	调整扩展优先级
specify extension catalog list / add / remove	管理项目级目录栈

其中目录管理子命令与 .specify/extension-catalogs.yml 直接对应：catalog add 支持 --name、--priority、--install-allowed 参数把新目录写入项目配置；catalog remove 按名字移除；catalog list 打印当前激活目录。用户指南 EXTENSION-USER-GUIDE.md 进一步给出了完整的手写 YAML 示例（default / internal / community 三条目、优先级与 install_allowed 字段），以及核心环境变量 GH_TOKEN / GITHUB_TOKEN 用于私有 GitHub 托管目录与 ZIP 的鉴权说明。

从源码行为看，安装流程还会自动联动代理技能注册：若项目使用基于 skills 的集成方式，扩展命令在安装时被自动注册为 agent skills，移除时自动清理，且不会覆盖人工修改过的既有 skill（见 用户指南对应章节）。

5. 向社区目录提交你的扩展

原文档的提交流程（Submission Process）四步：

1. 按 扩展开发指南 准备你的扩展；
2. 为你的扩展创建一个 release；
3. 使用扩展提交（Extension Submission）issue 模板提交，附齐全部所需元数据；
4. 等待评审——维护者审核提交、更新目录并关闭 issue。

配套的提交前检查清单（Submission Checklist）：

• 有效的 extension.yml 清单；
• 完整的 README，含安装与使用说明；
• 附带 LICENSE 文件；
• 已创建带语义化版本号（如 v1.0.0）的 release；
• 扩展在真实项目上测试过；
• 所有命令与文档描述一致可用。

更详细的分步说明见 扩展发布指南。

从 manifest 结构 与开发指南可以交叉印证清单的最小要素：schema_version: "1.0"、extension（id/name/version/description 必填）、requires（speckit_version 版本约束、可选 tools）、provides.commands（命令名必须符合 speckit.{ext-id}.{cmd} 模式）以及可选的 hooks / tags。仓库内的 扩展模板目录 则提供了可直接照抄起步的骨架（extension.yml、config-template.yml、示例命令、CHANGELOG 等）。

6. 深入一步：目录条目 Schema 与搜索行为

如果你想维护组织目录，需要知道 catalog.json 的字段规范。结合仓库中两份真实目录文件与用户指南中的 Schema 表，每条扩展条目的字段为：

字段	类型	必填	说明
name	string	是	人类可读名称
id	string	是	唯一标识（小写字母+连字符）
version	string	是	语义化版本（X.Y.Z）
download_url	string	是*	ZIP 归档 URL（bundled 内置扩展可无）
repository	string	是	源码仓库 URL
description	string	否	简短描述
author	string	否	作者/组织
license	string	否	SPDX 许可证标识
requires.speckit_version	string	否	版本约束
requires.tools	array	否	依赖的外部工具
provides.commands / hooks	number	否	命令 / 钩子数量
tags	array	否	搜索标签
verified	boolean	否	验证状态

*上游仓库的 catalog.json 中核心扩展标记了 bundled: true 因而没有 download_url；社区目录 catalog.community.json 的条目则普遍携带 download_url、homepage、category、effect、created_at 等更丰富的元数据，可作为组织目录的书写参考。

搜索行为上，specify extension search 会同时检索所有激活目录并默认包含社区目录，结果会标注来源目录与安装状态；也支持按关键词、标签（--tag）、作者（--author）过滤和 --verified 只看已验证扩展（见 用户指南）。CLI 对目录内容本身也保持防御性姿态：命令提示中的扩展 ID 安全化逻辑 明确说明目录条目（尤其来自仅发现目录的）是不可信输入，ID 若不匹配 ^[a-z0-9-]+$ 规则就降级为占位符，防止恶意条目把 shell 元字符注入到"建议用户复制执行"的命令中。

7. 小结

• 两个目录，两条信任边界：catalog.json 是"可安装"的策展来源，catalog.community.json 是"仅发现"的浏览区；源码中社区目录被硬性设为 install_allowed=False，这是有意设计的审查边界；
• 组织控制三件套：fork 目录 + SPECKIT_CATALOG_URL（或 .specify/extension-catalogs.yml 目录栈）+ 评审流程，即可实现全团队的扩展白名单管理，私有目录还可叠加 GH_TOKEN 鉴权；
• 安装路径：search → info → add <name>（目录）/ add --from <url>（直装，带 HTTPS、大小上限、TOCTOU 安全等加固）/ add --dev <path>（本地开发），配合 list / enable / disable / remove / update 完成生命周期管理；
• 贡献路径：按 开发指南 建扩展 → 打 release → issue 模板提交 → 维护者更新目录；提交前对照检查清单逐项确认；
• 延伸阅读：EXTENSION-USER-GUIDE.md（配置分层、故障排查与最佳实践）、EXTENSION-API-REFERENCE.md（API 参考）、RFC-EXTENSION-SYSTEM.md（系统设计 RFC）。