Spec Kit Bundles 完全指南bundle.yml 清单、specify bundle 命令体系与 Bundler 源码实现【免费下载链接】spec-kit Toolkit to help you get started with Spec-Driven Development项目地址: https://gitcode.com/GitHub_Trending/sp/spec-kitBundle 是 Spec Kit 把已有组件extensions、presets、workflows、steps组合成一个版本化、可安装单元的分发层。读完本文你将掌握specify bundle全部子命令search / info / install / update / remove / list / init / validate / build / catalog的参数与行为边界理解bundle.yml清单的完整结构与校验规则并能从源码层面弄清安装幂等性、集成integration冲突检测、来源记录provenance与目录栈catalog stack的底层实现。1. Bundle 是什么组合层而非运行时层用 Bundles 参考文档 的表述extensions 和 presets 是原语primitives而 bundle 是一层分发与组合distribution and composition机制——它声明一个团队或角色所需的全部组件并通过每个组件自身的安装机制一次性装好。Bundle 本身不引入任何新的运行时行为。一条 bundle 的完整生命周期可以概括为四个动作描述由bundle.yml清单声明元数据、版本依赖与组件引用发现与其他组件共用同一套目录栈catalog stack被发现解析安装时把声明的组件按固定版本pinned version解析成具体的安装计划执行检查唯一的跨 bundle 冲突点活动集成幂等地应用每个组件并写入完整的来源记录以便日后干净地移除或刷新。从源码结构看这套机制全部落在src/specify_cli/bundler/包中按职责分层模型层 models/manifest.py清单解析与结构校验、records.py已安装 bundle 的来源记录、catalog.py目录栈服务层 services/resolver.py清单 → 安装计划、installer.py执行安装/卸载、conflict.py冲突检测、catalog_stack.py跨源解析与搜索、packager.py构建产物、validator.py 与 references.py校验CLI 层 commands/bundle/init.py只负责参数解析与 Rich 输出渲染业务逻辑全部委托给服务层源码注释称之为 Principle Ithin commands over services。2. bundle.yml 清单结构与校验规则2.1 一个真实的清单示例仓库自带示例 examples/bundles/business-analyst/bundle.yml完整展示了清单的全部顶层字段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]examples/bundles/下还有 developer、product-manager、security-researcher 三个同构示例可对照阅读。2.2 字段校验规则来自 manifest.py 源码BundleManifest 在from_dict之后通过structural_errors()做结构校验规则如下规则说明schema_version必须在支持集合内当前为{1.0}SUPPORTED_SCHEMA_VERSIONS必填字段bundle.id、bundle.name、bundle.version、bundle.role、bundle.description、bundle.author、bundle.license、requires.speckit_versionbundle.version必须是合法 semverbundle.id必须是文件系统安全 slug^a-z0-9?$小写字母、数字、.、_、-禁止路径分隔符。这是因为 id 会被直接拼进产物文件名id-version.zip防止路径穿越组件版本 pinextensions、presets、workflows 条目必须固定versionsteps 可以不定版本版本号一经声明必须是合法 semverpresets 额外要求必须声明整数prioritystrategy必须是replace、prepend、append、wrap之一另外两个容易踩坑的解析细节源码注释中明确记录YAML null 不会变成字符串 Noneauthor:后面留空在 YAML 中是 null解析器通过_text()把它映射为空字符串再由必填检查拒绝而不是放行一个None的作者integration写成裸字符串会被拒绝如果integration存在但不是 mapping例如直接写integration: copilot解析直接报错而不是静默丢弃、把 bundle 错误地变成集成无关。2.3 组件引用与集成声明每个组件条目被解析为ComponentRefkind/id/version/source/priority/strategy。可选的integration字段mapping 形式含id声明该 bundle 目标集成若清单不声明integration则 bundle 是集成无关的is_agnostic()为 True安装时继承项目当前活动集成。requires.tools与requires.mcp是软依赖解析安装计划时它们只产生警告Requires external tools: ...不会阻断安装而requires.speckit_version是硬门控——见下文 resolver。3. 消费侧命令search / info / install / update / remove / list / init3.1 search在目录栈中检索specify bundle search [query]选项说明--offline不访问网络--json输出机器可读 JSON在所有活动目录中搜索匹配查询的 bundle。不带查询时列出全部可用 bundle附版本、角色、来源和信任指标org 维护目录中的条目为verified其余为community让你在安装前判断信任级别。从 catalog_stack.py 的search()看匹配是对 id、name、role、description、tags 做小写子串检索更关键的是每个 bundle id 只会出现一次且解析到最高优先级的来源——先按优先级占用 id再过滤查询避免低优先级的同 id 影子条目把你装不到的那个版本广告出来。--json输出中每条记录还包含install_policyinstall-allowed/discovery-only与trust字段。3.2 info安装前的完整预览specify bundle info bundle_id选项说明--offline不访问网络--json输出机器可读 JSON显示 bundle 的完整元数据以及它完全展开的组件集合——每个 extension、preset、step、workflow 及其固定版本外加 preset 的 priority 与 strategy并附信任指标。这个预览与install实际应用的计划是同一份你可以精确看到将被添加什么。与已安装 bundle 的可预见重叠也会在这里被提示。源码中这条命令刻意做到要么完整、要么报错bundle_info 会真正下载并解析远端清单而不是退化成目录里的provides计数——否则用户可能把一个无法验证的 bundle 误认为已知可安装。清单下载失败会以非零码退出而不是静默降级。3.3 install一条命令装完整个组件栈specify bundle install bundle_id | path选项说明--integration覆盖初始化/安装时使用的集成--offline不访问网络参数既可以是目录中的 bundle id也可以是本地路径构建好的.zip产物、bundle 目录、或bundle.yml文件本身。本地源不经过目录栈直接安装_local_manifest_source()在目录解析之前处理这三类本地形态。安装语义的几个关键点均与文档一致并可在 installer.py 中逐条印证自动初始化当前目录还不是 Spec Kit 项目时install会先初始化项目让全新 checkout 一条命令进入可用状态。此时--integration用于选择集成优先级显式覆盖 → bundle 声明 → 默认值。注意源码里有一道顺序保障所有硬兼容门控Spec Kit 版本、集成冲突都在specify init之前解析避免一个不兼容的 bundle 先初始化出项目状态、随后才在版本检查上失败而留下半截状态。不覆盖已初始化的项目--integration不能绕过已初始化项目的活动集成。若 bundle 目标集成与项目不一致安装直接中止且不做任何改动若项目活动集成无法确定缺失或不可读的.specify/integration.json而 bundle 又 pin 了集成则用--integration确认目标。集成无关的 bundle 继承项目活动集成。幂等已存在的组件被跳过。这里的已存在判断是按 id 而非版本的见 3.4 的 pin 语义。失败不留记录安装失败时不写任何来源记录本次运行中已装上的组件会被尽力回滚——回滚错误被吞掉因此磁盘上可能残留部分状态。源码中回滚是有界的只回滚本次调用新装的组件事先就存在的组件永不被回滚组件归属采用引用计数式逻辑独立安装未被任何 bundle 记录追踪的组件绝不会被记到 bundle 名下防止日后remove时误删源码注释引用的 FR-022。3.4 update重新解析并刷新组件specify bundle update [bundle_id]选项说明--all更新所有已安装 bundle--integration覆盖刷新组件时使用的集成仅在项目活动集成无法确定时生效--offline不访问网络重新解析 bundle并通过每个原语自己的 update 路径刷新组件把已装组件提升到 bundle 新 pin 的版本同时保留原语级覆盖例如 preset priority。update走的是install_bundle(..., refreshTrue)路径已安装组件不再被跳过而是重新应用旧版本拥有、新清单不再提供的组件会被卸载前提是其他已安装 bundle 不再需要它们首次安装时间installed_at在跨刷新时保留。Pin 只在安装时强制。幂等检查是按 id 的、版本无感的已存在的组件在install期间被跳过不会拿磁盘上的版本与清单 pin 比较。因此版本 pin 只有在 bundler 真正首次安装或刷新某个组件时才保证被应用。用specify bundle update可以把每个自有组件重新按其 pin 版本应用一遍。3.5 remove / list / initspecify bundle remove bundle_id specify bundle list [--json] specify bundle init [bundle_id] [--integration ...] [--offline]remove只卸载该 bundle 贡献的组件其他已安装 bundle 仍需要的组件会原样保留不做连带删除。实现上由 records.py 的components_still_needed()算出其他 bundle 仍需要的 (kind, id) 集合再逐组件判定卸载或跳过移除中途失败时bundle 记录保持不动错误信息会明确说明可能已部分卸载。list列出项目中已安装 bundle 的版本、组件数与安装时间。init先确保当前目录是 Spec Kit 项目必要时幂等初始化再可选地安装给定 bundle适合作为新 checkout 的显式一步式引导。4. 创建侧命令validate / build / publish4.1 validate清单是否良构、引用能否解析specify bundle validate [--path bundle目录|bundle.yml] [--offline]选项说明--pathbundle 目录或bundle.yml默认当前目录--offline只对照 bundled/已安装组件校验引用报告bundle.yml是否良构、以及每个声明的组件引用能否解析。引用依次对照 bundled 组件、项目已安装组件、以及在线时活动目录来检查。只有当引用在所有可查位置都确定不存在时校验才失败——即有活动目录可达且确认该组件缺失。无法验证的引用离线校验、或目录不可达被降级为警告让作者可以继续编写而不是直接跑挂。4.2 build产出单一版本化分发产物specify bundle build [--path bundle目录] [--output 输出目录]选项说明--pathbundle 目录默认当前目录--output产物输出目录从 bundle 目录生成一个版本化、可分发的.zip产物命名id-version.zip内嵌清单可直接specify bundle install artifact.zip安装。packager.py 中的构建约束值得作者注意缺少bundle.yml或README.md直接拒绝——每个 bundle 必须随附描述文档清单结构无效时拒绝构建并指向validate所有文件读取被限制在 bundle 源目录内路径收敛排除.git、__pycache__、.DS_Store产物使用固定的 zip 时间戳zip epoch保证字节级可复现。4.3 publish托管产物与目录条目Bundle 作者先在本地校验、打包再把生成的产物和目录元数据托管到用户可访问的位置。目录条目指向 bundle 产物但bundle.yml内部声明的组件仍会经过 bundled 组件、已安装组件或活动的 extension / preset / workflow / step 目录来解析。如果你的 bundle 引用了非默认目录中的组件请在文档中写明这些目录 URL并在一个添加了对应目录的干净项目上实测安装路径。提交社区 bundle 时应把这份依赖解析证据附在 GitHub 仓库的 Bundle Submission issue 模板中。社区 bundle 的完整提交清单公开仓库 合法bundle.yml、带specify bundle build产物的版本化 release、说明文档、目录条目建议、干净项目测试证据与维护者的审核范围见 Community Bundles 文档——维护者只核验提交元数据完整、格式正确、链接可达不审计也不背书bundle 及其安装组件的行为安装前请自行审查清单与组件来源。5. 目录源管理优先级、策略与信任bundle 通过优先级有序的目录源栈project、user、built-in 三级作用域被发现。# 查看活动目录栈含各来源的作用域与安装策略 specify bundle catalog list # 添加一个项目作用域的目录源 specify bundle catalog add url [--policy install-allowed|discovery-only] [--priority n] [--id id]选项说明--policyinstall-allowed或discovery-only--priority来源优先级越小越优先默认 10--id显式指定来源 id# 移除项目作用域的目录源 specify bundle catalog remove id_or_url持久化在.specify/bundle-catalogs.yml中见 catalog_config.py磁盘形状为{schema_version, catalogs: [{id, url, priority, install_policy}]}。几个实现层面的约束内置默认源不可删除要用同 id 来源去覆盖它。HTTPS-onlyhttp(s) 目录 URL 只允许 httpslocalhost 可用 http无主机的 URL 在写入时即被拒绝本地路径会被规范化为绝对路径再存储因此remove可以按当时添加的相对路径反查。discovery-only 的来源只能 search/info不能 installinstall与update解析到 discovery-only 来源会直接报错。内置 community 源就是 discovery-only按 id 安装需要先显式添加一个 install-allowed 目录显式目录的默认优先级高于内置 community 源。信任指标org 维护目录条目显示verified其余显示community_trust_level()。注意命令的作用域差异search和info在任何位置都可用——没有项目时回退到 built-in/user 目录栈。而改变状态的命令list、update、remove、catalog要求已用specify init初始化过的项目install和init在目录未初始化时会按需自动初始化。5.1 远端下载的安全约束当info/install走目录解析时清单从条目的download_url下载。CLI 层 对此有一整套硬约束file://、裸文件系统路径、无 scheme 的值一律拒绝从磁盘安装请直接传路径参数非 HTTPS 下载直接拒绝重定向目标也要逐个校验下载有字节上限MAX_DOWNLOAD_BYTES目录条目若带sha256则下载后逐字节校验。对 GitHub release 下载链接会先解析为 REST API 资产 URL 以兼容私有/SSO 仓库。这些约束在--offline下依然先行检查避免离线模式报出误导性的网络已禁用。6. 底层机制速览来源记录、解析门控与冲突检测来源记录provenance每次成功安装后records.py 把InstalledBundleRecordbundle_id、version、contributed_components、installed_at写入.specify/bundle-records.jsonschema 版本1.0。文件读取路径带防符号链接/路径穿越的收敛检查schema 主版本不匹配时快速失败而不是错误解析——这是 remove/update 能精确只碰本 bundle 组件的数据基础。解析门控resolver.py 的resolve_install_plan()把清单展开为InstallPlan并执行两道硬门控Spec Kit 版本门控satisfies()检查requires.speckit_version不满足即拒绝安装与集成兼容性检查。info的预览与install的执行共享这同一个计划来源保证你看到的正是将装上的。冲突检测conflict.py 确认文档的说法——唯一的跨 bundle 硬冲突点是活动集成bundle pin 的集成与项目活动集成不一致即中止。组件级重叠例如另一个 bundle 也提供了同名 preset只是信息性提示实际由原语机制自己的优先级规则裁决。install前打印的黄色!提示即来自这里。执行与回滚installer.py 的install_bundle()对计划逐组件执行is_installed → install/skip全部成功后才 upsert 记录任何异常触发_rollback()逆序移除本次新装组件尽力而为、吞掉移除错误与文档On failure, no provenance record is written完全对应。7. 实战走查从示例 bundle 到安装以仓库内置的 business-analyst 示例走一遍完整链路# 1. 检索并预览任何位置可用 specify bundle search business specify bundle info business-analyst # 2. 在干净目录一条命令初始化 安装目录未初始化时自动 init specify bundle install business-analyst # 或从本地源安装目录 / bundle.yml / .zip 均可不查目录栈 specify bundle install ./examples/bundles/business-analyst specify bundle install ./business-analyst-1.0.0.zip # 3. 查看已安装与来源记录 specify bundle list # 4. 需要升级时把组件刷新到清单新 pin 的版本 specify bundle update business-analyst # 5. 卸载其他 bundle 仍需要的组件会保留 specify bundle remove business-analyst作者侧则是对称的# 1. 校验清单良构与引用可达 specify bundle validate --path ./my-bundle # 2. 产出 id-version.zip specify bundle build --path ./my-bundle --output ./dist # 3. 托管 dist 下的产物 目录条目非默认目录依赖需随提交附解析证据 # 4. 在干净项目上按 5.1 节的 HTTPS/策略约束实测安装8. 小结维度结论定位分发与组合层零新增运行时行为复用各原语自身安装机制清单bundle.ymlschema 1.0id 为安全 slugextensions/presets/workflows 必须 pin semverpresets 必须声明 priority strategy安装幂等按 id失败不留记录 有界回滚集成冲突是唯一直止点更新update才保证按 pin 版本重新应用所有自有组件移除引用计数无连带删除发现project user built-in 优先级目录栈install-allowed / discovery-only 策略verified / community 信任指标分发build 出可复现id-version.zipHTTPS-only sha256 校验本地路径安装不走目录栈本文所有行为描述均以当前仓库src/specify_cli/bundler/与 docs/reference/bundles.md 为准清单字段级细节可对照 manifest.py安装/回滚/引用计数逻辑可对照 installer.py 与 records.py。【免费下载链接】spec-kit Toolkit to help you get started with Spec-Driven Development项目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考