企业官网建设流程全解析

spec-kit 角色 Bundle 实战：以 Product Manager 示例解析 bundle.yml 清单、组件组合与构建发布流程

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

Spec-Driven Development（SDD）中，spec-kit 用 Bundle 把 extension、preset、step、workflow 四类组件打包成一个面向特定角色的一体化安装单元。本文以官方示例examples/bundles/product-manager为样本，完整拆解它的bundle.yml清单结构、四类组件的声明方式、integration-agnostic 设计，以及如何用specify bundle validate/specify bundle build完成校验与构建，帮助读者掌握从编写、校验到打包发布一个角色 Bundle 的完整链路。

1. 角色 Bundle 的定位：组件之上的组合分发层

在 spec-kit 的组件体系里，extension 和 preset 属于"原语"，而 Bundle 是一个版本化、可安装的分发与组合层：它声明一个团队或角色所需的全部组件，并通过每个组件自身的安装机制一次性落地（见 docs/reference/bundles.md）。Bundle 自身不引入新的运行时行为，它只负责把已存在的组件按角色需要"选进同一套栈"。

仓库在 examples/bundles/ 下提供了四个官方角色示例，product-manager是其中之一：

四个示例共享同一套骨架：都声明agent-context扩展、一个带priority: 10, strategy: append的角色专属预设（security-researcher 用 5 体现更高优先级）、两个步骤和一条端到端工作流。理解 product-manager 的写法，也就理解了这一整套角色 Bundle 的范式。

2. bundle.yml 清单逐字段解析

Product Manager 示例的入口文档是 examples/bundles/product-manager/README.md，声明文件是 examples/bundles/product-manager/bundle.yml。完整清单如下：

schema_version: "1.0" bundle: id: "product-manager" name: "Product Manager" version: "1.0.0" role: "product-manager" description: "Spec-Driven Development setup for product managers: discovery, specification, and roadmap workflows." author: "spec-kit-examples" license: "MIT" requires: speckit_version: ">=0.9.0" tools: [] mcp: [] # Agnostic bundle: inherits the project's active integration. provides: extensions: - id: "agent-context" version: "1.0.0" presets: - id: "product-discovery" version: "1.0.0" priority: 10 strategy: "append" steps: - id: "draft-spec" - id: "review-spec" workflows: - id: "spec-to-roadmap" version: "1.0.0" tags: ["product", "discovery", "roadmap"]

各字段的作用：

其中requires.speckit_version: ">=0.9.0"说明该清单假定宿主specifyCLI 版本不低于 0.9.0，阅读本示例时应以此作为适用前提。

2.1 provides：四类组件的声明差异

provides区块是清单的核心，四类组件的声明详略不同：

• extensions：声明id与version，如agent-context锁定1.0.0；
• presets：除id、version外还声明priority: 10与strategy: "append"。priority 控制多预设共存时的叠加顺序（数值越小优先级越高，security-researcher 示例用 5 抢占更早位置），strategy 决定预设内容并入既有命令集的方式（append即追加而非替换）；
• steps：只声明id（draft-spec、review-spec），版本由组件自身目录或目录源解析；
• workflows：声明id与version，如spec-to-roadmap锁定1.0.0。

安装时，Bundle 的每个组件引用都会按"捆绑组件 → 已安装组件 → 活跃的 extension/preset/workflow/step 目录"的顺序解析（组件解析规则见 docs/community/bundles.md 的 Component Resolution 一节）。需要指出：当前仓库的 presets/ 目录中并没有product-discovery预设目录，说明该示例清单中的组件 ID 属于声明式引用，实际解析依赖目录源；按照 docs/reference/bundles.md 对validate的行为描述，"无法验证"的引用会被降级为 warning 以不阻塞编写，只有目录可达且明确缺失时才会失败。

3. 组件深读：agent-context 扩展做了什么

Product Manager 示例声明的唯一扩展是agent-context（版本1.0.0），其仓库实现位于 extensions/agent-context/。按 extensions/agent-context/README.md：

• 它管理当前 integration 的编码代理上下文文件（如CLAUDE.md、.github/copilot-instructions.md、AGENTS.md、GEMINI.md），负责维护由可配置标记包围的受管区块（默认<!-- SPECKIT START -->/<!-- SPECKIT END -->），.mdc文件还会确保 frontmatter 含alwaysApply: true；区块之外的内容一律不碰。
• 这是显式 opt-in组件：specify init默认不安装它；不装则任何 Spec Kit 组件都不修改代理上下文文件。
• 可手动执行speckit.agent-context.update命令刷新受管区块，也可通过扩展声明的after_specify、after_plan钩子在核心命令后自动刷新。
• 配置集中在.specify/extensions/agent-context/agent-context-config.yml（仓库内模板见 extensions/agent-context/agent-context-config.yml），可改context_markers与context_files。
• 脚本依赖 Python 3 + PyYAML；若钩子报 PyYAML 缺失，需在与specify相同的解释器环境中pip install pyyaml。

这就是"role bundle 让产品经理项目开箱即同步代理上下文"的底层机制：Bundle 只是声明引用，实际写文件的行为完全由agent-context扩展自己的脚本与钩子完成。

4. integration-agnostic：不锁定具体集成

README 明确写道：该 Bundle 是integration-agnostic（集成无关）的，"继承项目已使用的集成（如copilot、claude）"。清单中对应的注释行是：

# Agnostic bundle: inherits the project's active integration.

对照 docs/reference/bundles.md 中install的规则可以精确理解这一设计的边界：

• 若 Bundle钉死了某个集成而项目当前 active integration 无法判定（缺失或不可读的.specify/integration.json），--integration会用于确认目标；
• --integration不会覆盖一个已初始化项目的 active integration——如果 Bundle 目标集成与项目不一致，安装直接中止且不做任何修改；
• integration-agnostic 的 Bundle 则继承项目当前 active integration，product-manager 正是走这条路，因此同一份产物可以同时落到 Copilot、Claude 等不同集成环境。

5. 校验与构建：validate 和 build 两条命令

examples/bundles/product-manager/README.md 给出的两条 Usage 命令是该 Bundle 从编写到分发的标准动作：

specify bundle validate --path examples/bundles/product-manager specify bundle build --path examples/bundles/product-manager --output dist/

5.1 specify bundle validate

参数（见 docs/reference/bundles.md）：

行为要点：它检查两件事——bundle.yml是否格式良好（well-formed），以及每个声明的组件引用是否可解析。引用依次对照捆绑组件、项目已安装组件，以及在线时的活跃目录栈；只有当某个活跃目录可达且确认该组件缺失时才判定失败，离线或目录不可达这类"无法验证"的引用降级为 warning。这意味着 product-manager 这种引用外部组件 ID 的示例，在校验时更可能以"格式通过 + 部分引用 warning"的形态收敛，而非硬性失败。

5.2 specify bundle build

build从 Bundle 目录产出一个单一、版本化、可分发的.zip工件，工件内嵌清单，之后可以直接specify bundle install <artifact.zip>安装。对 product-manager 而言，即得到形如product-manager-1.0.0.zip的产物（--output dist/指定落在dist/下）。

5.3 下游安装与溯源

构建产物进入项目后的完整生命周期同样值得了解（同一参考文档）：

• specify bundle install <bundle_id | path>：接受目录 ID、本地.zip、Bundle 目录或bundle.yml路径；本地源不查目录栈直接安装；当前目录不是 Spec Kit 项目时会先初始化，一条命令到达可用状态；安装幂等，已存在的组件跳过；
• 每次成功安装都会写入溯源记录，存储在.specify/bundle-records.json。从 src/specify_cli/bundler/models/records.py 的结构看，InstalledBundleRecord精确记录bundle_id、version、contributed_components（该 Bundle 贡献了哪些组件）与installed_at——这正是remove能"只卸载本 Bundle 贡献的组件、不误删别的 Bundle 仍在使用的组件"的依据；
• specify bundle update按新钉版本刷新组件（注意版本钉只在首次安装/刷新时强制执行），specify bundle remove按溯源精确卸载，specify bundle list列出已装 Bundle 的版本与组件数；
• 若要走社区目录分发，还需一个 catalog 条目指向工件下载地址，社区条目形态可对照 bundles/catalog.community.json（如sicario-spec、specassay两条目的download_url、requires、provides计数字段），提交规范见 docs/community/bundles.md——注意内置社区源是 discovery-only：search/info可查，但按 ID 安装需显式添加 install-allowed 的目录。

6. 小结：编写一个角色 Bundle 的检查清单

以 product-manager 为模板，产出一个自己的角色 Bundle 需要落实四件事：

1. 清单骨架：schema_version: "1.0"+bundle元数据（id/name/version/role/description/author/license）+requires（至少给出speckit_version下界）+tags；
2. provides 组合：按角色需要选 extension/preset/step/workflow，preset 记得给出priority与strategy，步骤可只给 ID；
3. 集成策略：明确是 agnostic（继承项目集成）还是钉死某个集成——后者在install时与项目不一致会直接中止；
4. 验证闭环：specify bundle validate --path <dir>确认格式与引用，specify bundle build --path <dir> --output dist/产出.zip工件，再到干净项目里跑一遍完整安装路径作为测试证据。

product-manager 示例的价值正在于此：它用最少的组件数（1 扩展 + 1 预设 + 2 步骤 + 1 工作流）完整演示了角色 Bundle 的声明范式，是阅读 docs/reference/bundles.md 规范时最贴手的对照样本。

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