utility-update-pm-skills

PM Skills 更新器

此技能会将本地 pm-skills 安装更新到最新公开版本。它会验证网络连接、比较版本、预览更改，并生成结构化报告，记录已更新的内容和可用的新功能。

适用场景

• 想要将本地 pm-skills 更新到最新版本时
• 想要检查是否有可用的新版本时
• pm-skills 发布新版本后
• 新用户上手时，想确认自己使用的是最新版本

不适用场景

• 创建或编辑单项技能 → 使用 utility-pm-skill-builder 或 utility-pm-skill-iterate
• 根据规范验证技能 → 使用 utility-pm-skill-validate
• 直接在 pm-skills 仓库中工作的维护者（使用 git）
• 固定到某个较旧版本（此技能始终以最新版本为目标）

标志

标志	行为
(none)	完整更新流程：预检 → 预览 → 确认 → 更新 → 报告
--report-only	预检 → 预览 → 报告（不写入文件）
--status	轻量级版本检查——打印当前版本和最新版本，然后停止

--status 行为

提供 --status 时，只运行预检并显示：

pm-skills v{local} (installed, from {source})
pm-skills v{latest} (latest, released {date})
{Status: up to date | update available ({type})}

Run utility-update-pm-skills for details, or utility-update-pm-skills --report-only for a preview.

不会生成报告文件，也不会写入任何文件。

说明

收到更新 pm-skills 的请求时（未提供 --status），请按以下步骤操作：

步骤 1：预检

继续操作前，运行三项检查：

1. 网络访问：访问 GitHub API 或仓库 URL （https://github.com/product-on-purpose/pm-skills）。使用任何可用方式：curl、wget、GitHub CLI（gh）或 MCP 工具。

2. 最新版本：按以下回退顺序查询最新发布版本 （依次尝试，使用第一个成功的方法）：

   1. GitHub API：GET /repos/product-on-purpose/pm-skills/releases/latest
   2. GitHub CLI：gh release list --repo product-on-purpose/pm-skills --limit 1
   3. Git：git ls-remote --tags https://github.com/product-on-purpose/pm-skills.git

   如果三种方法都失败（速率限制、404、响应格式错误或无网络）， 则进入降级模式（见下文）。

   记录：版本字符串、发布日期、发布说明 URL 和发布说明正文。

3. 本地版本：从以下第一个可用来源读取：

   • .claude-plugin/plugin.json → version 字段
   • marketplace.json → plugins[0].version 字段
   • CHANGELOG.md → 最近的版本标题
   • Git 标签 → 最近的 v* 标签

   版本解析： 去掉可选的 v 前缀并清除首尾空白。如果来源存在，但得到的字符串为空、不是 semver 格式或格式错误（JSON 无效、字段缺失），则跳过该来源并显示警告，然后尝试下一个来源。只有在四个来源全部失败后，才回退到 0.0.0。

如果网络访问失败（降级模式）：

• 报告失败情况及错误详情。
• 提供手动更新说明：

  访问 https://github.com/product-on-purpose/pm-skills/releases 下载最新版本。解压归档文件，并将 skills/、commands/、_workflows/ 和其他内容目录复制到本地 pm-skills 安装目录。

• 停止执行。

步骤 2：版本比较

使用 semver 比较本地版本与最新发布版本。

如果本地版本 >= 最新版本：

• 报告：“你的 pm-skills 安装已是最新版本（v{local}）。”
• 询问是否仍要生成仅报告。
• 停止执行。

如果本地版本 < 最新版本：

• 显示版本差异：

  Local version:  v{local}
  Latest version: v{latest}
  Update type:    {major | minor | patch}
  

• 主版本警告：如果更新涉及主版本升级（例如，从 v2.x 升级到 v3.x），请显示醒目的警告：

  这是一次主版本更新，可能会对技能约定造成破坏性更改。继续前请查看发布说明。

• 继续执行步骤 3。

步骤 3：预览

向用户展示此次更新包含的内容：

1. 版本差异：本地版本、最新版本、更新类型。

2. 价值摘要：根据两个版本之间的 CHANGELOG 条目、GitHub 发布说明和目录差异（新增的 skills/、_workflows/ 文件）整理：

   • 新增的技能及其用途
   • 更新的技能及改进内容
   • 新增的工作流及其连接的内容
   • 其他值得注意的更改

3. 文件清单：列出将要写入的文件和文件夹，按目录分组并统计数量：

   Files to be written:
     skills/       31 files (2 new, 29 updated)
     commands/     38 files (2 new, 36 updated)
     _workflows/    9 files (1 new, 8 updated)
     other          7 files
     Total:        85 files
   

如果使用 --report-only： 使用 references/TEMPLATE.md 生成报告，并添加横幅“仅生成报告——未应用更新。”保存到 _pm-skills/updates/update-report_v{latest}_report-only_{YYYY-MM-DD_HHMMSS}.md。停止执行。

步骤 4：确认

请用户决定以下两项：

1. 确认更新： “这些文件将被覆盖。是否继续？[yes / no]”

   • 如果是主版本号升级：必须明确输入“yes”。
   • 如果用户拒绝：保存一份仅报告，并停止。

2. 备份选项： “是否在更新前备份当前文件？ [yes（推荐）/ no]”

   • 如果选择 yes：将所有范围内的文件复制到 _pm-skills/backups/v{current}_{YYYY-MM-DD_HHMMSS}/
   • 如果 _pm-skills/ 目录不存在，则创建该目录。

步骤 5：更新

使用先验证再复制的方式执行更新，并进行备份：

1. 下载：从 GitHub Release 页面将发布 ZIP 资源（pm-skills-vX.Y.Z.zip）下载到临时目录。这是由 build-release.sh 生成的精选构建产物——仅包含面向用户的内容，不包含 docs/internal/。

2. 验证：确认解压后的归档包含 skills/、commands/、AGENTS.md 和 .claude-plugin/plugin.json。如果验证失败，报告错误并停止，不写入任何文件。

3. 复制：将解压后归档中的范围内文件覆盖到安装根目录。按目录显示进度：

   Updating pm-skills v2.9.0 -> v2.10.0...
     skills/       31/31 ████████████████████  done
     commands/     38/38 ████████████████████  done
     _workflows/    9/9  ████████████████████  done
     other files    7/7  ████████████████████  done
   

4. 清理：删除临时目录。

步骤 6：更新后

1. 冒烟测试：

   • 版本一致性：plugin.json、marketplace.json 和 CHANGELOG.md 均反映新版本。（注意：步骤 1 中的版本检测采用首次匹配；冒烟测试会验证所有来源是否一致。此处出现不匹配，说明发布打包可能存在问题。）
   • 文件完整性：AGENTS.md、skills/、commands/、_workflows/ 均存在。
   • 技能数量变化：统计更新前后的技能数量，并报告变化。
   • 如果任何检查未通过：向用户说明具体详情。不要自动回滚。提供恢复指引：
     • 版本不匹配：“重新运行更新，或手动编辑 {file}，将版本设置为 {expected}。”
     • 文件缺失：“重新运行 utility-update-pm-skills 以重新下载，或从备份恢复：cp -r _pm-skills/backups/{dir}/* .”
     • 如果存在备份：务必提醒用户备份位置和恢复命令。

2. 摘要行：显示一条便于快速查看的确认信息：

   Updated v{old} -> v{new} | +{n} skills, +{n} workflows | Report: _pm-skills/updates/{file}
   

3. 完成报告：使用 references/TEMPLATE.md 生成报告，并保存到 _pm-skills/updates/update-report_v{from}-to-v{to}_{YYYY-MM-DD_HHMMSS}.md

4. MCP 提示：如果 ../pm-skills-mcp/ 存在，尝试读取 pm-skills-source.json。如果文件缺失或格式错误，显示： “检测到 pm-skills-mcp，但未找到或无法读取 pm-skills-source.json。请手动检查 MCP 仓库。”如果可读取，则显示：

   pm-skills-mcp detected at ../pm-skills-mcp/
     Embedded skills version: v{embedded}
     Updated pm-skills version: v{new}
   
     To update the MCP server's embedded skills:
       cd ../pm-skills-mcp && npm run embed-skills && npm run build
   

5. 后续步骤：

   Next Steps:
   - Review the update report at _pm-skills/updates/{report-file}
   - Run utility-pm-skill-validate --all to verify skill integrity
   - Run local CI: bash scripts/lint-skills-frontmatter.sh
   - Check release notes: {release-url}
   

文件范围

更新程序仅写入发布 ZIP 压缩包（ pm-skills-vX.Y.Z.zip）中包含的文件。该压缩包是由 build-release.sh 生成的精选构建产物。截至 v2.30.0，ZIP 还包含 agents/ 子 Agent 定义和 hooks/ 激活钩子，因此通过 ZIP 安装后，运行时文件可供分发技能引用。ZIP 不包含 docs/internal/ 和其他非面向用户的内容，因此复制时无需执行排除逻辑。

发布 ZIP 中包含的文件（将更新）：

路径	原因
skills/	核心技能文件
commands/	斜杠命令定义
_workflows/	工作流链
agents/	utility-pm-* 分发技能在运行时读取的子 Agent 定义
hooks/	激活钩子（防护措施 + 阶段路由器），包括 hooks.json
library/	示例库和技能输出示例（注意：用户添加的示例可能会被覆盖）
AGENTS.md	IDE 的技能发现配置
.claude-plugin/plugin.json	版本和插件元数据
marketplace.json	市场元数据
CHANGELOG.md	发布历史
README.md	公开文档
docs/（公开指南、参考资料、工作流）	面向用户的文档
scripts/	CI/验证脚本
mkdocs.yml	文档网站配置

发布 ZIP 中不包含的文件（绝不会被覆盖）：

路径	原因
docs/internal/	已由 build-release.sh 从 ZIP 中排除
_NOTES/	仅本地使用，已被 git 忽略，不在 ZIP 中
_pm-skills/	本地状态（报告、备份），不在 ZIP 中
.github/	CI 工作流，不在 ZIP 中
CONTRIBUTING.md、LICENSE	不在 ZIP 中（仓库级文件）

输出约定

该技能必须：

• 在执行任何远程操作前验证网络访问
• 写入任何文件前显示预览
• 覆盖文件前要求用户明确确认
• 覆盖前提供备份选项
• 采用先验证后复制的方式（先下载到临时目录，再验证，然后复制；备份是应对复制中途失败的恢复途径）
• 两种模式（仅报告和完成）均生成报告
• 运行更新后冒烟测试
• 检测到同级仓库时显示 MCP 提示

该技能不得：

• 未经用户确认写入文件
• 未确认网络访问就继续操作
• 修改 pm-skills 目录之外的文件
• 使用上游内容修改 docs/internal/、_NOTES/ 或 _pm-skills/
• 在冒烟测试失败时自动回滚（应告知用户）
• 删除上游发布版本中不存在的本地文件

质量检查清单

将更新标记为完成前，请确认：

• 预检通过：网络可用，已检测到版本
• 写入任何文件前已向用户显示预览
• 继续更新前已获得用户明确确认
• 已提供备份选项（并在用户接受时创建备份）
• 已将压缩包下载到临时目录，并在复制前完成验证
• 所有范围内的文件均已成功写入
• 版本一致性：plugin.json、marketplace.json、CHANGELOG 匹配
• 文件完整性：AGENTS.md、skills/、commands/、_workflows/ 均存在
• 已报告技能数量变化（更新前 -> 更新后）
• 已生成报告并保存到 _pm-skills/updates/
• 检测到同级仓库时已显示 MCP 提示
• 已提供后续步骤
• 已显示摘要行

常见问题

我是克隆了此仓库的贡献者，应该使用此技能吗？ 不应该。请改用 git pull 或 git fetch && git merge。此技能适用于将 pm-skills 作为插件安装或下载了发行版的终端用户。

我可以更新到特定版本，而不是最新版本吗？ v1 中不支持。此技能始终以最新发行版为目标。如需安装特定版本，请从发行版页面手动下载。

我的本地笔记和规划文档会怎样？ 它们绝不会被触及。此技能会明确将 docs/internal/、_NOTES/ 和 _pm-skills/ 排除在更新范围之外。请参阅文件范围表。

我添加的、不在上游发行版中的文件会怎样？ 它们会保持原样。此技能只会覆盖新发行版中存在的文件，绝不会删除本地文件。

如何撤销更新？ 如果你创建了备份（默认会提供此选项），请还原备份： cp -r _pm-skills/backups/v{version}_{timestamp}/* . 如果你没有创建备份，但使用了 git，请使用 git checkout . 将受跟踪的文件还原到最后一次提交时的状态。

更新进行到一半失败了，该怎么办？ 此技能会在复制前进行验证（下载到临时目录、检查，然后写入），因此部分失败的情况很少发生。如果确实发生了：如有备份，请从备份还原；否则，重新运行 utility-update-pm-skills 重试。

延伸阅读

如需查看图文操作指南和更多背景信息，请参阅 更新 PM Skills 指南。