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-kitSpec-Driven DevelopmentSDD中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-elicitationcapture-requirements, trace-acceptance-criteriarequirements-to-specdeveloper开发者implementation-planningplan-implementation, break-down-tasksspec-to-implementationproduct-manager产品经理product-discoverydraft-spec, review-specspec-to-roadmapsecurity-researcher安全研究员security-compliance (priority 5)threat-model, security-reviewsecure-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 projects 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_version1.0清单格式版本供校验器与解析器识别bundle.idproduct-manager全局唯一标识bundle install/info/list均以此为准bundle.name/versionProduct Manager/1.0.0展示名与语义化版本构建产物以此版本命名bundle.roleproduct-manager面向角色标签用于bundle search的角色检索与信任展示bundle.description一句话定位说明该角色的 SDD 场景discovery、specification、roadmap workflowsauthor/licensespec-kit-examples/MIT归属与许可证元数据requires.speckit_version0.9.0宿主 CLI 最低版本约束requires.tools/requires.mcp空列表声明式的外部工具与 MCP 依赖位此示例无额外依赖provides.*见下文Bundle 承诺提供的组件清单按四类分组tagsproduct, discovery, roadmap检索标签其中requires.speckit_version: 0.9.0说明该清单假定宿主specifyCLI 版本不低于 0.9.0阅读本示例时应以此作为适用前提。2.1 provides四类组件的声明差异provides区块是清单的核心四类组件的声明详略不同extensions声明id与version如agent-context锁定1.0.0presets除id、version外还声明priority: 10与strategy: append。priority 控制多预设共存时的叠加顺序数值越小优先级越高security-researcher 示例用 5 抢占更早位置strategy 决定预设内容并入既有命令集的方式append即追加而非替换steps只声明iddraft-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 projects active integration.对照 docs/reference/bundles.md 中install的规则可以精确理解这一设计的边界若 Bundle钉死了某个集成而项目当前 active integration 无法判定缺失或不可读的.specify/integration.json--integration会用于确认目标--integration不会覆盖一个已初始化项目的 active integration——如果 Bundle 目标集成与项目不一致安装直接中止且不做任何修改integration-agnostic 的 Bundle 则继承项目当前 active integrationproduct-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.mdOptionDescription--pathBundle 目录或bundle.yml文件默认当前目录--offline只对照捆绑/已安装组件校验不访问网络行为要点它检查两件事——bundle.yml是否格式良好well-formed以及每个声明的组件引用是否可解析。引用依次对照捆绑组件、项目已安装组件以及在线时的活跃目录栈只有当某个活跃目录可达且确认该组件缺失时才判定失败离线或目录不可达这类无法验证的引用降级为 warning。这意味着 product-manager 这种引用外部组件 ID 的示例在校验时更可能以格式通过 部分引用 warning的形态收敛而非硬性失败。5.2 specify bundle buildOptionDescription--pathBundle 目录默认当前目录--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-onlysearch/info可查但按 ID 安装需显式添加 install-allowed 的目录。6. 小结编写一个角色 Bundle 的检查清单以 product-manager 为模板产出一个自己的角色 Bundle 需要落实四件事清单骨架schema_version: 1.0bundle元数据id/name/version/role/description/author/licenserequires至少给出speckit_version下界tagsprovides 组合按角色需要选 extension/preset/step/workflowpreset 记得给出priority与strategy步骤可只给 ID集成策略明确是 agnostic继承项目集成还是钉死某个集成——后者在install时与项目不一致会直接中止验证闭环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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考