Spec Kit business-analyst 示例 bundle 详解：用 bundle.yml 组装面向角色的组件栈

本篇以 Spec Kit 仓库中的示例 bundle business-analyst 为主体，完整拆解其 bundle.yml 清单中每个字段的含义（schema 版本、requires 约束、provides 四类组件的版本与合并策略），并结合 Bundles 参考手册 的 validate、build、install 等命令，说明如何把一个"业务分析师"角色的 Spec-Driven Development 工作环境验证、打包并分发。读完你可以独立读懂任意 bundle.yml，并复现"清单校验 → 构建 zip 工件 → 安装到项目"的完整流程。

1. business-analyst bundle 是什么

examples/bundles/business-analyst/README.md 将其定位为一个面向业务分析师（business analyst）的角色 bundle，覆盖三类工作场景：

• requirements elicitation：需求获取/澄清；
• traceability：需求到验收标准、再到规格说明（spec）的可追溯性；
• acceptance criteria：验收标准的沉淀与追踪。

与 Spec Kit 仓库中其他三类示例角色 bundle（developer、product-manager、security-researcher，见 examples/bundles/）一样，它本身不引入任何新的运行时行为——bundle 只是"分发与组合层"，把已有的 extension、preset、steps、workflow 四类基础组件按角色打包，通过各组件自身的安装机制一次性装好。

按 README 的说明，该 bundle 会安装以下组件：

组件类型	ID	说明
Extension	agent-context	保持 agent 上下文文件（如 CLAUDE.md 等）与项目状态同步
Preset	requirements-elicitation（priority 10，strategy append）	需求获取与分析的命令集
Steps	capture-requirements、trace-acceptance-criteria	两个 workflow 步骤
Workflow	requirements-to-spec	把捕获到的需求转成 spec

README 同时强调该 bundle 是 integration-agnostic 的：它不指定具体编码 agent 集成，安装时继承当前项目已激活的 integration（这一点在 Bundles 参考手册 的 install 一节中有对应语义说明：集成无关的 bundle 会继承项目的 active integration）。

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

bundle.yml 是 bundle 的唯一声明文件，全文如下：

schema_version: "1.0"

bundle:
  id: "business-analyst"
  name: "Business Analyst"
  version: "1.0.0"
  role: "business-analyst"
  description: "Spec-Driven Development setup for business analysts: requirements elicitation, traceability, and acceptance criteria."
  author: "spec-kit-examples"
  license: "MIT"

requires:
  speckit_version: ">=0.9.0"
  tools: []
  mcp: []

provides:
  extensions:
    - id: "agent-context"
      version: "1.0.0"
  presets:
    - id: "requirements-elicitation"
      version: "1.0.0"
      priority: 10
      strategy: "append"
  steps:
    - id: "capture-requirements"
    - id: "trace-acceptance-criteria"
  workflows:
    - id: "requirements-to-spec"
      version: "1.0.0"

tags: ["requirements", "traceability", "analysis"]

2.1 schema_version 与 bundle 元数据

• schema_version: "1.0"：清单 schema 版本，用于校验器判断格式演进。
• bundle 块是元数据区：id 是 catalog 检索与安装的唯一标识（与 specify bundle install <bundle_id>、remove、update 使用的 id 一致）；name 是人类可读名称；version 参与版本化分发；role 声明目标角色（business-analyst），供 specify bundle search 等场景按角色筛选；description 用于 catalog 展示；author 与 license 用于溯源与合规（示例统一为 spec-kit-examples / MIT）。

2.2 requires：安装前置约束

requires:
  speckit_version: ">=0.9.0"
  tools: []
  mcp: []

• speckit_version: ">=0.9.0"：要求宿主项目的 Spec Kit CLI 满足最低版本约束；
• tools 与 mcp 均为空数组，表示该 bundle 不依赖额外命令行工具或 MCP server。这一结构允许其他 bundle 在此声明外部工具与 MCP 依赖，本示例没有。

2.3 provides：四类组件及其版本钉扎

provides 块是清单的核心，按组件类型分组声明 bundle 会安装的内容：

Extensions——只钉 id + version：

extensions:
  - id: "agent-context"
    version: "1.0.0"

agent-context 是 Spec Kit 自带的内置 extension。在 extensions/catalog.json 中可以确认其登记信息：

"agent-context": {
  "name": "Coding Agent Context",
  "id": "agent-context",
  "version": "1.0.0",
  "description": "Manages coding agent context/instruction files (e.g., CLAUDE.md, copilot-instructions.md) with project-specific plan references and configurable markers",
  "author": "spec-kit-core",
  "bundled": true
}

即它负责管理各编码 agent 的上下文/指令文件（CLAUDE.md、copilot-instructions.md 等），并支持项目级 plan 引用与可配置标记；其实现入口见 extensions/agent-context/ 与命令 speckit.agent-context.update。这正是 README 中"keeps the agent context file in sync"的具体所指。

Presets——额外携带合并语义：

presets:
  - id: "requirements-elicitation"
    version: "1.0.0"
    priority: 10
    strategy: "append"

preset 用于覆写/补充核心命令模板，而 priority 与 strategy 是 preset 组合时的关键参数：

• priority: 10：优先级数值，决定多个 preset 对同一模板生效的先后；
• strategy: "append"：追加式合并——在既有模板内容后附加本 preset 的命令集，而不是整体替换。

specify bundle info 的输出会展示每个 preset 的 priority 与 strategy，让你在安装前预览完整展开的组件集；specify bundle update 刷新组件时也会"preserving primitive-level overrides (such as preset priority)"，即保留这类 preset 级参数。

Steps 与 Workflows：

steps:
  - id: "capture-requirements"
  - id: "trace-acceptance-criteria"
workflows:
  - id: "requirements-to-spec"
    version: "1.0.0"

两个 step（需求捕获、验收标准追溯）供 workflow 引擎编排使用；workflow requirements-to-spec 钉住版本 1.0.0，把捕获到的需求转成 spec。需要说明的是：在仓库自带的 step/workflow 目录（workflows/step-catalog.json、workflows/catalog.json）中查不到这两个 step id，这说明它们属于示例 bundle 的声明式组件引用——从清单机制看，bundle validate 会把这些引用对照 bundled 组件、已安装组件与在线 active catalog 进行解析，解析不到且无法证实缺失的引用会被降级为警告（详见下文第 4 节），而非直接失败。

2.4 tags

tags: ["requirements", "traceability", "analysis"]

标签用于检索与分类，恰好对应 README 开篇概括的三大工作场景：需求、可追溯性、分析。

3. 实操：校验与构建（README 官方用法）

examples/bundles/business-analyst/README.md 给出的两条标准命令：

specify bundle validate --path examples/bundles/business-analyst
specify bundle build --path examples/bundles/business-analyst --output dist/

3.1 validate：清单合法性与引用可解析性

按 Bundles 参考手册 的定义：

选项	说明
--path	bundle 目录或 bundle.yml（默认：当前目录）
--offline	仅对照 bundled/已安装组件校验引用

validate 做两件事：检查 bundle.yml 是否 well-formed（schema 与字段结构合法），以及每个声明的组件引用是否可解析。引用检查顺序是：bundled 组件 → 项目已安装组件 →（在线时）active catalogs。仅当某个可达的 active catalog 明确证实该组件不存在时校验才失败；离线或 catalog 不可达导致的"无法验证"会降级为警告，保证作者可以继续开发。对 business-analyst 这类示例 bundle 来说，agent-context 属于内置 bundled 组件可直接命中，而 requirements-elicitation、requirements-to-spec 等示例组件若不在任何可达 catalog 中，校验结果将体现为相应的警告而非硬失败——这也解释了为什么示例仓库允许它们以"纯声明"的形式存在。

3.2 build：产出可分发工件

选项	说明
--path	bundle 目录（默认：当前目录）
--output	工件输出目录

build 从 bundle 目录生成一个单一、版本化的 .zip 工件，其中嵌入 bundle.yml 清单。该工件可以直接安装：

specify bundle install <business-analyst-1.0.0.zip>

安装路径既可以是 catalog 中的 bundle id，也可以是本地 .zip、bundle 目录或 bundle.yml 文件；本地来源直接安装，不查询 catalog 栈。

4. 安装与生命周期：这个 bundle 装进项目后会发生什么

结合 docs/reference/bundles.md 的 install 语义，specify bundle install business-analyst（或安装上述 zip 工件）的行为要点：

1. 自动初始化项目：如果当前目录还不是 Spec Kit 项目，install 会先初始化，使全新 checkout 一条命令达到可用状态；
2. 集成检查：business-analyst 不钉 integration，因此直接继承项目当前激活的 integration。若某个 bundle 钉了特定 integration 且与项目不一致，install 会中止且不落盘——本 bundle 不受此约束；
3. 幂等安装：已存在的组件被跳过，可重复执行；
4. 版本钉扎时机：幂等判断基于 id 而非版本，pin 只在首次安装或 specify bundle update 刷新时强制生效。要按 bundle 声明的版本重新刷新全部组件，使用 specify bundle update（支持 --all）；
5. provenance 追踪与干净移除：每次成功安装都写入溯源记录，specify bundle remove business-analyst 只卸载该 bundle 贡献的组件，其他 bundle 仍在使用的组件不会被连带删除；失败的安装不写任何溯源记录，并对本次已装组件做尽力回滚；
6. 安装前预览：specify bundle info business-analyst 会展示完整展开的组件集（每个 extension、preset、step、workflow 及其钉住版本、preset 的 priority 与 strategy），与 install 实际应用的计划一致，并附带 verified / community 信任指示。

组件引用的解析来源共有三类：bundle 自带的 bundled 组件、项目已安装组件、以及 active 的 extension/preset/workflow/step catalogs。如果某 bundle 依赖默认 catalog 之外的组件，需要按 docs/community/bundles.md 的做法显式添加 install-allowed 的 catalog 来源：

specify preset catalog add <presets-catalog-url> --name example-bundle --install-allowed
specify extension catalog add <extensions-catalog-url> --name example-bundle --install-allowed

business-analyst 示例的 agent-context 属于 bundled: true 的内置组件（见 extensions/catalog.json），而其余示例组件属于声明式引用，实际安装时依赖上述解析链——阅读 validate/info 的输出即可确认每个引用最终落在哪个来源。

5. 与 developer bundle 对照：理解"角色 bundle"的组装范式

把 business-analyst/bundle.yml 与 developer/bundle.yml 对照，可以清楚看到 Spec Kit 角色 bundle 的统一组装范式：

维度	business-analyst	developer
role	business-analyst	developer
公共 extension	agent-context v1.0.0	agent-context v1.0.0
preset	requirements-elicitation（priority 10，append）	implementation-planning（priority 10，append）
steps	capture-requirements、trace-acceptance-criteria	plan-implementation、break-down-tasks
workflow	requires 块同为 speckit_version: ">=0.9.0"、无 tools/mcp 依赖，且同为 integration-agnostic
workflow	requirements-to-spec	spec-to-implementation

两者结构完全同构，仅组件内容随角色而变：business-analyst 聚焦"需求 → 验收标准 → spec"的上游链路，developer 则覆盖"spec → 实现计划 → 任务拆解 → 代码"的下游链路。这意味着同一个团队的上下游角色可以分别安装各自的角色 bundle，agent-context extension 的幂等安装与 remove 的"无连带删除"语义（bundle 只卸载自己贡献的组件）保证了多角色并存时的干净边界。

6. 小结：从示例到自建 bundle

以 business-analyst 为例，可以提炼出编写角色 bundle 的完整路径：

1. 编写 bundle.yml：schema_version 固定 "1.0"；bundle 块给出 id/name/version/role 等元数据；requires 声明 speckit_version 下限及 tools/mcp 依赖；provides 按 extensions/presets/steps/workflows 分组钉版本，preset 额外给出 priority 与 strategy；tags 对齐角色工作场景；
2. specify bundle validate --path <bundle目录> 校验格式与引用可解析性（离线引用缺失降级为警告）；
3. specify bundle build --path <bundle目录> --output dist/ 产出单一版本化 .zip 工件；
4. 分发工件与 catalog 元数据，用户侧通过 specify bundle install（支持 id、zip 路径、目录、bundle.yml 文件四种来源）安装，info/list/update/remove 覆盖完整的生命周期管理；
5. 依赖非默认 catalog 的组件时，随提交文档说明所需 catalog 地址，并用 --install-allowed 策略的 catalog 来源在干净项目上完整测试安装链路（见 docs/community/bundles.md）。

整套机制下，business-analyst 这个示例既是可直接运行的参考实现，也是 bundle.yml schema 各字段最完整的最小示范。