Spec Kit 扩展自测指南用speckit.selftest.extension验证扩展的目录发现、安装与注册全生命周期【免费下载链接】spec-kit Toolkit to help you get started with Spec-Driven Development项目地址: https://gitcode.com/GitHub_Trending/sp/spec-kitSpec Kitspec-kit内置了一个名为selftest的官方扩展它把扩展从目录中被发现、被安装、被注册这一完整生命周期封装成了一条可交给 AI 代理执行的自测命令speckit.selftest.extension。本文以 selftest 命令模板 为主线逐步骤解析其四步验证流程目录发现校验、安装模拟、注册校验、测试报告并结合 扩展管理器源码 与 扩展子命令实现 讲清每一步背后的真实机制包括install_allowed的目录分级设计、--from安装通道的安全加固以及.specify/extensions/.registry注册表的结构与容错策略。读完本文你可以直接在自己的 Spec Kit 项目上对任意扩展无论是官方目录还是社区目录中的条目跑一遍端到端生命周期验证并能读懂 CLI 每一步输出背后的实现原理。一、selftest 扩展是什么一份命令模板 一个扩展清单selftest 扩展由两部分组成extensions/selftest/extension.yml扩展清单声明身份信息与提供的命令extensions/selftest/commands/selftest.md自测命令的 Markdown 提示词模板由代理解释执行。清单中的关键字段如下摘自 extension.ymlschema_version: 1.0 extension: id: selftest name: Spec Kit Self-Test Utility version: 1.0.0 description: Verifies catalog extensions by programmatically walking through the discovery, installation, and registration lifecycle. author: spec-kit-core repository: https://github.com/github/spec-kit license: MIT requires: speckit_version: 0.2.0 provides: commands: - name: speckit.selftest.extension file: commands/selftest.md description: Validate the lifecycle of an extension from the catalog.几个要点requires.speckit_version: 0.2.0声明了运行该扩展所需的最低 Spec Kit 版本这是扩展系统对版本兼容性的显式约束provides.commands将命令speckit.selftest.extension绑定到模板文件commands/selftest.md模板文件首部的 frontmatterdescription: Validate the lifecycle of an extension from the catalog.是命令在目录与帮助输出中展示的说明文字。使用方式在已安装 selftest 扩展的 Spec Kit 项目中通过代理调用/speckit.selftest.extension 扩展名例如/speckit.selftest.extension linear。模板中的$ARGUMENTS占位符即为用户传入的扩展名。模板明确约定若$ARGUMENTS为空必须提示用户提供一个扩展名而不是自行猜测目标——这是代理驱动命令常见的防幻觉约束。自测的总目标模板中 Goal 一节原文语义是针对$ARGUMENTS这个扩展验证其端到端生命周期discovery、installation、registration即目录能否发现它、CLI 能否把它装进工作区、安装后项目配置中是否留下注册记录。二、四步验证流程逐条解析Step 1目录发现校验Catalog Discovery Validation模板要求执行specify extension info $ARGUMENTS判定标准有二命令成功完成且返回的扩展 ID 与$ARGUMENTS完全一致。任何一条不满足即判该步失败。从源码看这一步对应extension info子命令见 extension_info 命令。它在解析用户输入时有一套值得注意的消歧逻辑消歧实现输入若直接命中某个扩展 ID则直接采用若输入命中的是展示名name且恰好只有一个候选则按该候选解析若展示名命中多个扩展多个目录条目共用同名展示名CLI 会打印一张Matching extensions表格含 ID、Name、Version、Catalog 列并以错误退出要求改用扩展 ID 重跑。因此自测报告中返回的扩展 ID 必须精确匹配$ARGUMENTS这一判定正好覆盖了展示名歧义被拒绝的边界情形——用 ID 传参是这条命令最稳妥的调用方式。Step 2安装模拟Simulate Installation含install_allowed分级与--from回退模板要求先直接尝试specify extension add $ARGUMENTS并明确指出如果目录中该扩展来自install_allowed: false的目录discovery-only仅可发现这一步预期会失败。随后要求回退到第二条通道从目录元数据中取出该扩展的download_url模板注明可通过 catalog info 命令或 UI 获取再执行specify extension add $ARGUMENTS --from download_url这条预期失败 显式回退的写法正是 Spec Kit 目录安全模型的直接体现。CLI 对 catalog 子系统的官方说明catalog_app 帮助文本把目录分成两类安装源install_allowed: true你信任、可从中安装扩展的目录内置的default官方目录属于此类你自己编写并审核过的目录也应当标记为install_allowed: true仅发现目录install_allowed: false只用于找到扩展、不可安装的检索面内置的community社区目录即为此类开箱即可被search检索但不能被add安装。该说明同时强调不要把 discovery-only 目录翻成install_allowed并给出两条合规的安装路径审核后用specify extension add name --from url直接安装或自己策展一个受控目录。这与 扩展系统 RFC 中的默认目录栈描述一致官方catalog.jsoninstall_allowed: true 社区catalog.community.jsoninstall_allowed: false。仓库内 官方目录 中的 4 个扩展agent-context、assess、bug、git均带bundled: true标记而 社区目录 的每个条目都携带download_url等元数据——这正是 Step 2 回退通道所需要的download_url字段来源。--from通道本身在源码中有完整的安全加固。install_extension_from_url 函数 的文档字符串列出了它的防护清单协议约束URL 必须使用 HTTPS仅 localhost 允许 HTTP否则抛出ExtensionError下载上限响应读取被限定在 50 MiB 以内防止超大响应拖垮下载目录归档格式探测自动识别 ZIP 或 tar.gz/tgz 归档TOCTOU 防护下载落在一个临时 inode文件POSIX 下 unlink、Windows 下 O_TEMPORARY上下载完直接交给install_from_zip消费路径不会被二次打开。此外CLI 在打印任何建议用户复制执行的命令前还会经过_command_safe_id过滤目录条目属于不可信输入只有当 ID 匹配^[a-z0-9-]$小写字母、数字、连字符且不以连字符开头时才被原样嵌入命令否则回退为占位符避免目录数据被注入为 shell 元字符。仓库测试中也有对应的路径穿越防护用例见 test_registrar_path_traversal.py覆盖安装/注册阶段对恶意路径的拦截。对自测而言Step 2 的通过标准是直接 add 在 discovery-only 场景下预期失败、--from回退成功而不是两步都必须成功——模板用*expected* to fail的措辞显式区分了失败是符合设计的行为。Step 3注册校验Registration Verification模板要求add完成后用cat之类工具检查项目配置中存在$ARGUMENTS的注册记录模板给出的示例路径是cat .specify/extensions/.registry/$ARGUMENTS.json这里结合源码做一个重要澄清。从 ExtensionRegistry 实现 看注册表是单文件结构REGISTRY_FILE .registry注册表路径为extensions_dir / .registry即.specify/extensions/.registry——一个 JSON 文件内部是{schema_version: 1.0, extensions: {id: {…元数据…}}}的结构。也就是说当前源码实现中并不存在按扩展 ID 拆分的.registry/id.json文件模板里的按 ID 路径应理解为该扩展注册记录所在位置的示意执行自测的代理实际会校验.specify/extensions/.registry中是否包含目标 ID 的记录或其等价落盘形态判定本质是安装是否留下了可查询的注册条目。注册记录本身的信息来自 registry.add 实现写入时深拷贝传入元数据版本、来源等并自动补充installed_at字段UTC ISO 时间戳。因此 Step 3 的验证除了记录存在还可以顺带核对installed_at时间戳是否落在本次自测时间窗口内作为新安装生效的佐证。注册表实现还有两个健壮性设计值得了解损坏恢复_load在文件缺失、非普通文件、JSON 解析失败或结构不符时一律回退为空注册表保证安装/启用/禁用流程不因脏数据崩溃fail-closed 探测is_corrupt则供解析路径使用区分注册表不存在安全与注册表存在但不可读危险——后者若被静默当空表处理会把磁盘上所有未注册扩展目录误判为已注册启用因此解析路径必须显式失败。Step 4验证报告Verification Report模板要求汇总前三步的标准输出直接生成一份终端风格的测试报告返回给用户。模板给出的标准输出格式如下完整继承原文 test session starts collected 3 items test_selftest_discovery.py::test_catalog_search [PASS/FAIL] Details: [Provide execution result of specify extension search] test_selftest_installation.py::test_extension_add [PASS/FAIL] Details: [Provide execution result of specify extension add] test_selftest_registration.py::test_config_verification [PASS/FAIL] Details: [Provide execution result of registry record verification] [X] passed in ... 报告刻意采用 pytest 风格的视觉语言test session starts/collected 3 items/::用例命名 /passed in ...收尾让发现、安装、注册三个用例各自独立判级PASS/FAIL Details 摘录原始命令输出即使读者不看执行过程也能在报告里定位失败环节。命名中的test_selftest_discovery.py::test_catalog_search只是报告格式中的用例标签并非要求仓库中真的存在这些测试文件。三、一次完整自测的实战走查以 社区目录 中真实存在的ascii-diagram扩展v1.1.0带download_url为例把四个步骤串起来发现specify extension info ascii-diagram期望成功返回 ID 为ascii-diagram的条目。注意该条目来自install_allowed: false的社区目录——可以用specify extension catalog list核对各活跃目录的 install_allowed 状态该命令对 discovery-only 目录会打印 discovery only 并附上审核提示。安装直接通道预期失败specify extension add ascii-diagram期望被拒。这是设计使然——社区目录只是检索面。CLI 在相关路径上的提示文案会指向specify extension add name --from url这条合规出口见 _commands.py 中的安装提示。安装--from回退通道specify extension add ascii-diagram --from https://github.com/MRZHUH/spec-kit-ascii-diagram/archive/refs/tags/v1.1.0.zip期望HTTPS 下载、归档探测、解包安装均成功。此步骤会触发 install_extension_from_url 的加固下载链路。注册校验检查.specify/extensions/.registry或模板中指示的记录位置存在ascii-diagram的记录且含installed_at时间戳随后可用specify extension list复核——该命令extension_list 实现会列出已安装扩展的名称、版本、描述、命令数、钩子数、优先级与启用状态。输出报告按 Step 4 的 pytest 风格模板汇总三步结果例如2 passed, 1 expected-fail (discovery-only)这类结论需要如实标注——直接add在 discovery-only 目录条目上失败属于 Step 2 的预期分支不应被简单计为整体失败。四、适用前提与注意事项运行环境命令依赖已安装的specifyCLI 与一个已初始化的 Spec Kit 项目存在.specify/目录结构selftest 扩展自身要求speckit_version 0.2.0。extension add/info等命令在源码入口处会先通过_require_specify_project校验当前目录是合法的 Spec Kit 项目根。用 ID 而不是展示名传参如 Step 1 分析所述展示名在跨目录检索时可能歧义并导致命令直接报错退出自测传参建议使用扩展 ID。网络依赖目录发现与--from安装均需要联网访问目录 URL 或下载 URL源码中定义了官方与社区两个目录的默认远端地址见 catalog URL 常量项目级目录栈可通过.specify/extension-catalogs.yml配置SPECKIT_CATALOG_URL环境变量亦可指定。离线环境下该自测的 Step 1/Step 2 无法完整执行。注册表结构以源码为准模板中.registry/$ARGUMENTS.json的按 ID 路径与源码实现的单文件.registry注册表在字面上不一致执行校验时应以目标 ID 的记录是否存在于注册表为判定基准而非严格匹配该文件路径若未来注册表格式变更schema_version目前为1.0报告中的注册校验步骤应同步调整。不要把自测当作安装决策--from通道的设计前提是你先审核了该扩展vetted自测验证的是生命周期机制是否通畅不代表对被测扩展本身的安全背书。五、小结selftest 扩展用最少的表面一条命令模板覆盖了扩展系统最关键的三条链路目录发现specify extension info、分级安装add与add --from的双通道、注册落盘.specify/extensions/.registry。它的价值在于把扩展系统的约定行为——尤其是 discovery-only 目录预期失败、--from合规回退——固化成了可重复执行的验证脚本并借用 pytest 风格报告让每一步都有独立的可判定结论。对扩展作者而言它是发布前验证自己扩展条目元数据ID、download_url、install_allowed归属目录是否正确的现成工具对平台使用者而言它是理解 Spec Kit 目录安全模型扩展用户指南、API 参考的最佳实践入口。【免费下载链接】spec-kit Toolkit to help you get started with Spec-Driven Development项目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考