Spec Kit 社区生态完全指南：扩展、预设、Bundle、演练与 Friends 的目录结构、分类体系与安装策略

Spec Kit 社区生态完全指南：扩展、预设、Bundle、演练与 Friends 的目录结构、分类体系与安装策略

【免费下载链接】spec-kit 💫 Toolkit to help you get started with Spec-Driven Development 项目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit

Spec Kit 社区围绕 Spec-Driven Development（SDD）沉淀了五类可组合的社区产物：扩展（Extensions）、预设（Presets）、Bundle、演练示例（Walkthroughs）与 Friends 陪伴项目，它们各自通过独立的社区目录文件（catalog）发布，并通过 specify CLI 的 catalog 机制被发现与安装。读完本文，你能理解社区产物的分层关系与安全边界，掌握从目录检索、catalog add 到 bundle install 的完整安装链路，并知道如何核实一个社区条目的元数据与来源。

社区生态总览：五类产物与各自的职责

社区总览文档 定义了 Spec Kit 社区的产物版图。所有社区贡献均由各自作者独立创建和维护，GitHub 官方维护者只负责验证目录条目的完整性与格式正确性，不审查、不审计、不背书、不维护社区代码本身。五类产物的分工如下：

产物类型	职责	入口文档	社区目录文件
Extensions	为 Spec Kit 增加新能力：领域命令、外部工具集成、质量门禁等	extensions.md	extensions/catalog.community.json
Presets	定制 Spec Kit 行为：覆写模板、命令与术语，不改动任何工具链	presets.md	presets/catalog.community.json
Bundles	将扩展、预设、工作流与步骤组合成可按角色/团队整体安装的堆栈	bundles.md	bundles/catalog.community.json
Walkthroughs	展示 SDD 在不同场景、语言、框架下的端到端实操示例	walkthroughs.md	—（外部示例仓库列表）
Friends	扩展、可视化或基于 Spec Kit 构建的陪伴项目（VS Code 插件、Claude Code 插件等）	friends.md	—（外部项目列表）

这条安全边界贯穿社区文档的每一个板块：每个分类页顶部都有相同的 NOTE 声明，要求用户在安装前自行审阅源码，安装后果自负。这意味着社区目录（catalog）本质上是一份"经过格式校验的注册表"，而不是质量认证清单。

社区扩展：分类体系、Effect 语义与目录条目结构

规模与分类

总览文档给出"130+ 扩展、70+ 作者"的量级描述；核对仓库内的实际目录文件 extensions/catalog.community.json 可以确认其真实规模——当前共收录 163 个扩展条目，来自 97 位独立作者，覆盖从可访问性治理到多智能体编排的完整谱系。

扩展条目使用一套开放的分类法（catalog 文档中的常见取值，但任意字符串都允许）：

• docs — 读取、校验或生成规格工件；
• code — 审查、校验或修改源代码；
• process — 跨阶段编排工作流；
• integration — 与外部平台同步；
• visibility — 报告项目健康度或进展。

Effect（副作用级别） 则是二值的规范值，决定扩展是否会落盘：

• read-only — 只产生报告，不修改文件；
• read-write — 会修改文件、创建工件或更新规格。

扩展作者可以在自己的 extension.yml 的 extension: 块中声明 category 与 effect，这两个字段同时会体现在 catalog.community.json 中，供工具链与 CLI 使用——例如 specify extension info 就能读取它们。仓库内的参考实现（如 extensions/agent-context/extension.yml、extensions/assess/extension.yml）展示了这类清单文件的标准形态。

目录条目的完整字段

从 catalog.community.json 的实际条目（以 adrkit 为例）可以看到，一个规范的扩展条目包含：

{
  "name": "adrkit — decision memory for spec-driven development",
  "id": "adrkit",
  "author": "Mark Beacom (@mbeacom)",
  "version": "0.1.2",
  "download_url": "…adrkit.zip",
  "repository": "…/mbeacom/adrkit",
  "license": "Apache-2.0",
  "category": "process",
  "effect": "read-write",
  "requires": {
    "speckit_version": ">=0.13.0,<0.16.0",
    "tools": [{ "name": "adr", "version": ">=0.3.0", "required": true }]
  },
  "provides": { "commands": 3, "hooks": 1 },
  "tags": ["adr", "governance", "decision-records", "architecture", "compliance"],
  "verified": false
}

几个值得注意的字段：requires.speckit_version 声明了对 specify CLI 的 SemVer 兼容区间（如 adrkit 要求 >=0.13.0,<0.16.0），provides 给出命令数与 hook 数，requires.tools 还可以声明对外部工具的硬性依赖。这些字段让"这个扩展能不能在我当前版本的 Spec Kit 上跑"变成一条可机器校验的判断，而不是盲装。

代表性扩展

目录中的条目按首字母排列，这里挑几个体现生态广度的代表（完整清单见 extensions.md）：

• adrkit（process）：把决策记录（ADR）拉入 agent 上下文、对照检查产出的计划并从计划工件起草 ADR；
• Brownfield Bootstrap（process）：为既有代码库自动发现架构、渐进式引入 SDD；
• Jira Mirror / Linear Weave / GitHub Issues Integration（integration）：把 spec/tasks 与团队的项目跟踪系统做幂等同步；
• CI Guard（process, read-only）：在 CI/CD 中校验规格存在性并检测漂移，缺规格时阻断合并；
• Token Budget / Token Consumption Analyzer（process / visibility）：压缩工作流产物、度量 token 消耗；
• Verify Tasks（code, read-only）：检测"幻影完成"——tasks.md 中打了 [X] 但实际没有实现的任务。

要发布自己的扩展，可参照仓库中的 扩展发布指南，其中也定义了扩展 API 的规范（参见 EXTENSION-API-REFERENCE.md）。

社区预设：覆写模板与命令，不动工具链

预设（Preset）与扩展的关键区别在于：预设只改变 Spec Kit 的行为外观与措辞——覆写模板、命令提示词和术语，而不引入新的工具逻辑。总览文档概括得很准确："社区预设从语言本地化到完全不同的开发方法论都有"。

社区预设收录在 presets/catalog.community.json（当前 34 个条目、19 位作者）。条目结构与扩展类似，含 version、download_url（通常指向带 tag 的 release 压缩包）、requires.speckit_version、provides（模板数/命令数/脚本数）与 tags。几个典型例子能说明预设的上限：

• Pirate Speak (Full)：把全部 Spec Kit 输出改写成海盗黑话——spec 变成 "Voyage Manifests"，plan 变成 "Battle Plans"，tasks 变成 "Crew Assignments"，6 个模板 + 9 个命令，零工具链改动；
• Jira Issue Tracking：覆写 speckit.taskstoissues 单条命令，用 Atlassian MCP 工具把任务创建到 Jira 的 Epic/Story/Task，而不是 GitHub Issues；
• Screenwriting / Fiction Book Writing：把 SDD 流程整体改造为剧本写作（26 模板 + 32 命令，支持 Fountain 导出）或小说创作（12 种语言、34 命令）；
• Spec2Cloud：为"规格 → 计划 → 任务 → 实现 → 部署到 Azure"调优的 8 命令工作流；
• Test-First Governance / Security Governance：以模板和门禁形式注入 TDD 治理、STRIDE/CAPEC 威胁建模等治理要求。

预设与仓库内一方预设（如 presets/lean、presets/scaffold）共享同一套结构：preset.yml 清单 + 要覆写的 commands/ 与 templates/ 文件，这保证了社区预设可以无缝套用一方的加载机制。

社区 Bundle：角色化组件堆栈与安装策略

概念与目录

Bundle 把扩展、预设、工作流与步骤打包成一个"角色/团队堆栈"，让用户一次安装一套经过组合验证的组件，而不必分别执行多条安装命令。当前 bundles/catalog.community.json 收录了 2 个社区 Bundle：

Bundle	目标角色	提供内容	说明
SicarioSpec Security & Governance	security-engineer	1 扩展 + 11 预设	默认安全的治理堆栈：数据分级、威胁建模、代码自有的验证门禁
SpecAssay	developer	1 扩展 + 1 预设	为 stock Spec Kit 增加持久 ID（Durable-ID）、Gate 2 拒绝与 trace-manifest 输出

Bundle 条目除常规字段外还多一个 role 字段标识适用角色，provides 中则按 extensions / presets / steps / workflows 分类计数（如 SicarioSpec 为 extensions: 1, presets: 11, steps: 0, workflows: 0）。仓库内的 examples/bundles/ 目录提供了四个一方示例 Bundle（business-analyst、developer、product-manager、security-researcher），其 bundle.yml 是清单文件的标准写法。

发现与安装的关键约束：discovery-only 策略

bundles.md 中最容易被忽略但最关键的机制是：内置社区源只用于发现（discovery-only）。specify bundle search 和 specify bundle info 可以检索社区目录里的条目，但按 ID 安装必须显式添加一个 install-allowed 的 catalog；显式添加的 catalog 具有比内置社区源更高的默认优先级。

这一设计在源码中有直接印证。src/specify_cli/bundler/services/adapters.py 中的注释写明"默认 catalog 预留给一方 Bundle，社区条目走 catalog.community.json"，并实现了 builtin://community 这一特殊 scheme（adapters.py）：当请求 URL 为 builtin://community 时，加载随 wheel 打包（或仓库内 bundles/catalog.community.json）的内置社区目录。也就是说，社区目录随 CLI 分发、永远可检索，而安装权限默认关闭，用户必须显式 opt-in。

组件解析与完整安装流程

Bundle 条目只描述"从哪里下载 Bundle 制品"，但 Bundle 内引用的组件在安装时仍需能解析——它们可以来自：Bundle 自带的组件、已安装的组件、或当前激活的扩展/预设/工作流/步骤 catalog。若你的 Bundle 依赖不在 Spec Kit 默认 catalog 中的组件，必须把所需 catalog 的 URL 写进提交材料与 README。

一次完整的"添加 catalog + 安装"实操流程（摘自 bundles.md，把 URL 换成你自己的）：

# 1. 注册组件所在的预设/扩展 catalog，并标记为允许安装
specify preset catalog add https://example.com/presets.json --name example-bundle --install-allowed
specify extension catalog add https://example.com/extensions.json --name example-bundle --install-allowed

# 2a. 直接安装下载的 Bundle 制品
curl -L -o example-bundle-1.0.0.zip https://example.com/example-bundle-1.0.0.zip
specify bundle install ./example-bundle-1.0.0.zip

# 2b. 或者：按 ID 从 install-allowed 的 bundle catalog 安装
specify bundle catalog add https://example.com/bundles.json --id example-bundle-catalog --policy install-allowed
specify bundle install example-bundle

提交与审查边界

提交一个社区 Bundle 需要：公开仓库中有效的 bundle.yml 清单、用 specify bundle build 生成的制品的带版本 GitHub Release、说明目标角色/已装组件/所需 catalog/预期工作流的文档、含元数据与组件计数的目录条目、以及一份从干净 Spec Kit 项目出发的测试证据。维护者的审查范围很明确——只核对提交字段完整性与格式、URL 可达性、bundle.yml 存在性、所需 catalog 的声明、以及目录条目形状是否符合预期；不审计被安装组件（扩展/预设/工作流/步骤/脚本）的运行行为。更新 Bundle 则是再提一次提交 issue，附新版本、下载 URL、变更后的组件清单与测试证据。

社区 Walkthroughs：七种场景的端到端参考

walkthroughs.md 列出了 7 个社区演练项目，覆盖 greenfield（从零）与 brownfield（存量代码）两大象限：

1. Greenfield .NET CLI 工具——从空目录用 Copilot agents 构建单二进制时区工具，跑完 constitution → specify → plan → tasks → 多轮 implement 全流程；
2. Greenfield Spring Boot + React 平台——LLM 性能分析平台（REST API + 图表 + 迭代追踪），PostgreSQL + Docker Compose，含 clarify 与跨工件一致性分析；
3. Brownfield ASP.NET CMS 扩展——在约 30.7 万行 C#/Razor/SQL/JS 的开源 CMS 上加 Docker Compose 基础设施与 token 认证的 headless REST API，演示无规格、无 constitution 时如何切入；
4. Brownfield Java 运行时扩展——在约 42 万行、180 个 Maven 模块的 Jakarta EE 运行时上加密保护的 Server Admin Console，展示大型多模块 Java 项目的 SDD 打法；
5. Brownfield Go/React 看板——完全用终端的 Copilot CLI 驱动，为 Go 地面支持系统加 React 遥测看板；
6. Greenfield + 自定义预设——用 Pirate Speak 预设从零构建 Spring Boot MVC，演示预设如何重塑整套体验；
7. Greenfield + 自定义扩展——用 AIDE 扩展（7 步迭代生命周期：vision → roadmap → 进度追踪 → 工作队列 → 工作项 → 执行 → 反馈环）构建家庭交易平台，演示"Kit"的扩展机制。

文档同时明确了使用边界：这些演练是有用的只读示例（completed flows），但不是生成 spec/plan/tasks 的官方黄金输出——引用它们的产出时不应视为标准答案。

社区 Friends：可视化与陪伴工具

friends.md 收录直接构建在 Spec Kit 之上的陪伴项目，形态包括 VS Code 扩展、Claude Code 插件与终端 UI：

• VS Code Spec Kit Assistant：完整 SDD 工作流的可视化编排器（constitution → specification → planning → tasks → implementation），含阶段状态可视化、交互式任务清单与 DAG 可视化，支持 Claude/Gemini/Copilot/OpenAI 后端，要求 specify CLI 在 PATH 中；
• SpecKit Assistant（npm）：npx speckit-assistant 即可运行的同类可视化编排器，无需全局安装；
• SpecKit Companion（VS Code）：富 Markdown 规格浏览、带图片附件的规格创建、行内评论（GitHub 风格 review）、阶段步进器；
• cc-spex：Claude Code 插件，在 Spec Kit 上叠加可组合 trait、质量门禁、git worktree 隔离与并行实现；
• cc-spec-kit：社区维护的 Claude Code / Copilot CLI 插件，经插件市场安装 Spec Kit skills；
• spectatui：终端 UI 仪表盘，管理 features/specs/integrations/presets/workflows/extensions 并可接入既有 AI 会话；
• spec-kit-copilot：列表中唯一标注为 GitHub 一方项目 的条目——把 specify CLI 的各命令组（setup、init、check、extensions、presets、bundles、workflows 等）封装成 Copilot skills 插件，用自然语言驱动整个 Spec Kit 生态。

Friends 与其他四类产物的区别在于：它不走 catalog 机制，是独立生态位的可视化/编排层；除明确标注的一方项目外，同样不经过官方审查与背书。

实操清单：安全使用社区资产的检查路径

把总览文档与目录机制串起来，安装社区资产前建议走这四步（全部可由 CLI 与仓库文件完成，不依赖第三方网站）：

1. 检索：用 specify extension search / specify preset search / specify bundle search 在目录中定位条目——注意 Bundle 的内置社区源只供发现；
2. 读元数据：用 specify extension info 等命令查看 category、effect、requires.speckit_version 与 provides，确认与当前 CLI 版本的兼容区间；
3. 核对目录文件：社区条目的权威快照就在仓库内——extensions/catalog.community.json、presets/catalog.community.json、bundles/catalog.community.json，updated_at 字段可判断新鲜度；
4. 审阅源码再安装：目录条目中的 repository 指向作者仓库，安装前通读 extension.yml / preset.yml / bundle.yml 及其中引用的脚本；Bundle 场景还需显式 catalog add --install-allowed（或 --policy install-allowed）后才可按 ID 安装。

社区生态是 Spec Kit 的"Kit"真正成立的方式：核心工作流保持稳定，能力通过扩展叠加、行为通过预设重塑、组合通过 Bundle 交付、而 Walkthroughs 与 Friends 分别提供了可对照的实操样例和可替换的交互外壳。理解"目录格式校验 ≠ 代码背书"这条边界，并熟练使用 catalog 与 install-allowed 策略，就是在社区生态中安全选型的全部前提。

【免费下载链接】spec-kit 💫 Toolkit to help you get started with Spec-Driven Development 项目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit