SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场speckit-updater

speckit-updater

编程与开发

查看项目

更新于 10-16 04:36

技能介绍

用途

speckit-updater 为 GitHub SpecKit 安装提供安全更新能力，目标是在应用模板更新的同时保留用户的自定义内容。它适用于需要更新或安装 SpecKit 模板、同时保留项目自定义项的场景，也适用于围绕更新、回滚或指定版本操作建立安全审批流程，以及通过会话方式操作 SpecKit 更新器，而不是盲目执行原始命令。

主要能力

  • 自定义内容保留：使用归一化文件哈希自动检测并保留用户自定义内容。
  • 智能冲突解决：逐个引导处理冲突，提供 4 个选项：合并编辑器、保留我的、使用新版本、跳过。
  • 版本跟踪：维护 .specify/manifest.json，记录文件哈希、版本信息和备份历史。
  • 自动备份：在 .specify/backups/ 中创建带时间戳的备份，并自动管理保留数量。
  • 快速失败与回滚：出现任何错误时自动回滚，恢复更新前状态。
  • 干跑模式：--check-only 可展示将会发生的变更，而不实际应用。
  • Constitution 集成：当 constitution 模板有更新时进行通知（运行 /speckit.constitution）。
  • 自定义命令安全：用户创建的命令永不覆盖，即使使用 --force 也不会。

使用方式

技能被调用后，运行更新编排脚本（会话模式）：

pwsh -NoProfile -File "<skill_path>/scripts/update-wrapper.ps1"

解析输出中的标记：

  • [PROMPT_FOR_APPROVAL]：更新场景（已存在 SpecKit 安装）
  • [PROMPT_FOR_INSTALL]：全新安装场景（没有 .specify/ 目录）

更新场景（发现 [PROMPT_FOR_APPROVAL] 标记）：展示 Markdown 摘要，包括当前版本与可用版本、将要更新/添加/删除的文件、检测到的冲突（如有）、被保留（自定义）的文件、备份位置、自定义命令；请求用户批准后继续。若获批，使用 -Proceed 标志重新运行；若拒绝，告知用户更新已取消。

全新安装场景（发现 [PROMPT_FOR_INSTALL] 标记）：以自然方式向用户提出安装询问，例如“SpecKit 当前未安装在此项目中，是否要我安装？”或“我可以为你安装最新的 SpecKit 模板。这会创建 .specify/ 目录结构并从 GitHub 下载模板。”不要向用户提及 -Proceed 标志（这是实现细节）。若用户批准（如回答“yes”“proceed”“install it”等），使用 -Proceed 标志重新运行；若拒绝，告知用户安装已取消。

执行已批准操作：

pwsh -NoProfile -File "<skill_path>/scripts/update-wrapper.ps1" -Proceed

特殊情况：用户请求 -CheckOnly 时，带该标志运行并展示报告；请求 -Rollback 时，带该标志运行并确认恢复；请求特定 -Version 时，包含该参数。

命令

/speckit-updater

更新 SpecKit 模板、命令和脚本，同时保留自定义内容。

用法：

  • /speckit-updater — 带会话式审批工作流的交互式更新/安装（推荐用于 Claude Code）
  • /speckit-updater -Proceed — 批准后继续更新/安装（由 Claude 在用户确认后使用）
  • /speckit-updater -CheckOnly — 仅检查更新，不应用
  • /speckit-updater -Version v0.0.72 — 更新到指定版本
  • /speckit-updater -Force — 强制覆盖 SpecKit 文件（保留自定义命令）
  • /speckit-updater -Rollback — 从之前的备份恢复
  • /speckit-updater -Auto — 已弃用：改用会话式工作流（显示警告，映射为 -Proceed）

全新安装（没有 .specify/ 目录）

  1. 首次调用显示安装提议，带 [PROMPT_FOR_INSTALL] 标记
  2. Claude Code 向用户提出自然的问题（例如“是否要我安装 SpecKit？”）
  3. 用户通过会话式回答批准（例如“yes”“proceed”“install it”）
  4. Claude 自动用 -Proceed 标志重新调用（实现细节对用户隐藏）
  5. 脚本创建 .specify/ 结构、下载模板、创建清单
  6. 全程退出码为 0（等待批准不算错误）
  7. 与更新流程一致：两者都使用会话式审批工作流

处理流程

  • 校验前置条件（已安装 Git、Git 状态干净、具备写权限）
  • 加载或创建清单（.specify/manifest.json）
  • 从 GitHub Releases API 获取目标版本
  • 比较文件哈希以识别自定义内容
  • 创建带时间戳的备份
  • 应用选择性更新，保留自定义文件
  • 为冲突打开 VSCode 合并编辑器（流程 A：一次一个）
  • 自动调用 /speckit.constitution 进行 constitution 更新
  • 用新版本更新清单
  • 管理备份保留（保留最近 5 个）

会话式工作流

该技能使用两步审批流程：

  1. 输出摘要 → 脚本退出 → 等待批准
  2. 批准后，Claude 用 -Proceed 重新调用 → 应用更新

要求

  • 已安装 Git 并在 PATH 中
  • 需要互联网连接以从 GitHub 获取更新
  • 对 .specify/ 和 .claude/ 目录具备写权限
  • Git 工作目录干净或已暂存

脚本位置：{skill_path}/scripts/update-wrapper.ps1（入口点）和 {skill_path}/scripts/update-orchestrator.ps1（主要逻辑）。

入口命令：

pwsh -NoProfile -Command "& '{skill_path}/scripts/update-wrapper.ps1' [parameters]"

注意：包装脚本同时支持 PowerShell 风格（-CheckOnly）和 Linux 风格（--check-only）标志。

架构（模块）

  • HashUtils：归一化哈希（处理行尾、尾随空白、BOM）
  • VSCodeIntegration：上下文检测、Quick Pick、diff/merge 编辑器集成
  • GitHubApiClient：GitHub Releases API 交互（未认证，每小时 60 次请求）
  • ManifestManager：带缓存的清单 CRUD 操作
  • BackupManager：备份创建、恢复和保留管理
  • ConflictDetector：文件状态分析与冲突检测

工作流

  1. 前置条件校验（关键检查必须通过，警告允许继续）
  2. 清单加载/创建（安全默认：若无清单则假定所有文件都已自定义）
  3. 查询 GitHub API 获取目标版本
  4. 文件状态分析（6 种操作：add/remove/merge/preserve/update/skip）
  5. 用户确认并预览变更
  6. 创建备份（带时间戳，排除备份目录）
  7. 选择性文件更新（快速失败并自动回滚）
  8. 冲突解决（流程 A：一次一个，VSCode 合并编辑器）
  9. 更新清单（版本、文件哈希、自定义标志）
  10. 备份清理（保留最近 5 个，需要确认）
  11. 展示详细摘要

退出码

  • 0：成功
  • 1：一般错误
  • 2：前置条件未满足
  • 3：网络/API 错误
  • 4：Git 错误
  • 5：用户取消
  • 6：需要回滚（自动）

适用场景

  • 更新或安装 SpecKit 模板，同时保留项目自定义内容
  • 需要围绕更新、回滚或指定版本 SpecKit 操作的安全审批流程
  • 通过会话方式操作 SpecKit 更新器，而非盲目执行原始命令

限制与注意事项

  • 仅当任务明确符合上述范围时使用本技能。
  • 不要将输出视为环境特定验证、测试或专家审查的替代品。
  • 如果缺少必需输入、权限、安全边界或成功标准，应停止并请求澄清。
  • 安装前应先检查确切的插件版本和每个打包文件，报告脚本及网络或文件系统行为，并请求用户明确批准。不要将活动分支直接安装到活跃的 agent 目录。
  • 本目录文案包含内联指引，但不包含以下支持路径；它们是外部前置条件，不是捆绑文件：在依赖这些路径的步骤可用之前，必须获取原始支持材料或现有安装，本目录不提供已验证的下载来源；应相对该安装解析每个路径，检查其内容，并核实适用的许可证与执行前提。在所需文件存在之前，不要运行命令或声称已遵循引用的流程。不要伪造缺失的脚本，也不要把同名的无关文件当作等价物。此处完整记录的独立步骤可在用户授权范围内进行；任何依赖步骤应报告为不可用。