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

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 是其中之一：

示例 Bundle	面向角色	预设	步骤	工作流
business-analyst	业务分析师	requirements-elicitation	capture-requirements, trace-acceptance-criteria	requirements-to-spec
developer	开发者	implementation-planning	plan-implementation, break-down-tasks	spec-to-implementation
product-manager	产品经理	product-discovery	draft-spec, review-spec	spec-to-roadmap
security-researcher	安全研究员	security-compliance (priority 5)	threat-model, security-review	secure-sdd

四个示例共享同一套骨架：都声明 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"]

各字段的作用：

字段	取值（product-manager）	说明
schema_version	1.0	清单格式版本，供校验器与解析器识别
bundle.id	product-manager	全局唯一标识，bundle install / info / list 均以此为准
bundle.name / version	Product Manager / 1.0.0	展示名与语义化版本；构建产物以此版本命名
bundle.role	product-manager	面向角色标签，用于 bundle search 的角色检索与信任展示
bundle.description	一句话定位	说明该角色的 SDD 场景：discovery、specification、roadmap workflows
author / license	spec-kit-examples / MIT	归属与许可证元数据
requires.speckit_version	>=0.9.0	宿主 CLI 最低版本约束
requires.tools / requires.mcp	空列表	声明式的外部工具与 MCP 依赖位，此示例无额外依赖
provides.*	见下文	Bundle 承诺提供的组件清单，按四类分组
tags	product, discovery, roadmap	检索标签

其中 requires.speckit_version: ">=0.9.0" 说明该清单假定宿主 specify CLI 版本不低于 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）：

Option	Description
--path	Bundle 目录或 bundle.yml 文件（默认当前目录）
--offline	只对照捆绑/已安装组件校验，不访问网络

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

5.2 specify bundle build

Option	Description
--path	Bundle 目录（默认当前目录）
--output	产物输出目录

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 规范时最贴手的对照样本。