groove-admin-update

groove-admin-update

维护者（andreadellacorte/groove 仓库）： 发布新的 GitHub Release 后，请在 groove 仓库根目录运行此命令，确保已提交的 .agents/skills/groove* 与 npx skills add andreadellacorte/groove 安装的内容一致——参见 CONTRIBUTING.md（“Publish release”）。不要对此使用从 skills/ 执行的手动 rsync。

结果

所有待处理的迁移均按版本顺序应用到用户本地的 groove 状态中。.groove/index.md 反映当前已安装的 groove 版本。

验收标准

• 更新后，.groove/index.md 中的 groove-version: 与 skills/groove/SKILL.md 中的 version: 一致
• 每个待处理迁移均按顺序应用
• 每次迁移成功后都会更新 groove-version:（可恢复部分进度）
• 如果已是最新版本，清晰地报告并退出
• 真实来源检查：只有当已安装的技能版本与最新 GitHub release 相同时，才报告“已是最新”；如果添加步骤在磁盘上留下了较旧的版本（例如缓存版本或默认分支版本），则向用户发出警告并告知如何修复

步骤

1. 获取最新 release 标签，从 https://api.github.com/repos/andreadellacorte/groove/releases/latest 获取（tag_name，去掉前导 v）。此为目标版本。如果 API 调用失败，则跳过版本检查并继续，不设置目标版本。
2. 重试安装：运行 npx skills add andreadellacorte/groove --yes（不要使用 @tag——CLI 不支持标签语法）。完成后，从 skills/groove/SKILL.md 读取 version: 并与目标版本比较。如果已安装版本仍低于目标版本，等待 10 秒后重试 npx skills add andreadellacorte/groove --yes。最多总共重试 3 次。如果所有尝试都未能安装目标版本，则报告：“Installed v but latest release is v — npx skills add may be caching an older version. Try again later.”并退出。
   • 安装成功后，继续之前先从磁盘重新读取此 SKILL.md（skills/groove-admin-update/SKILL.md）——技能刷新可能已更新更新命令本身，后续步骤必须遵循最新版本
3. 从 .groove/index.md 读取 groove-version:——如果不存在此键，则假定为 0.1.0 并写入该值
4. 从 skills/groove/SKILL.md 的 version: 读取已安装版本（步骤 2 中已确认其与目标版本一致）
5. 如果本地版本与已安装版本相同：报告“groove is up to date (v)”并退出
6. 读取 skills/groove/migrations/index.md——解析迁移表
7. 按表格顺序筛选 To > 本地版本且 To <= 已安装版本的行——From 字段仅供参考，不影响是否执行
8. 如果找不到迁移但版本不同：直接将 .groove/index.md 中的 groove-version: 更新为已安装版本，并报告“no state migrations needed — version bumped to v”
9. 对每个待处理迁移： a. 报告“Applying → : ” b. 读取并执行迁移文件 c. 将 .groove/index.md 中的 groove-version: 更新为 To 版本 d. 报告“✓ → applied”
10. 报告摘要：已应用 N 个迁移，目前版本为 v
11. 更新后重新同步平台符号链接：
    • 对 .agents/skills/ 中名称以 groove 开头的每个目录：
      • 确保 .claude/skills/<name> 是指向 ../../.agents/skills/<name> 的符号链接（如不存在或已失效，则创建或更新）
      • 如果 .cursor/skills/ 存在，则确保 .cursor/skills/<name> 是指向 ../../.agents/skills/<name> 的符号链接
    • 移除 .agents/skills/ 中已不存在的所有 .claude/skills/groove-* 或 .cursor/skills/groove-* 条目（已移除技能留下的失效符号链接）
    • 运行：for skill in .agents/skills/groove*; do name=$(basename "$skill"); ln -sfn "../../.agents/skills/$name" ".claude/skills/$name"; done
    • 使用 ln -sfn（不解引用），以避免在现有目录符号链接内创建嵌套符号链接
    • 报告：“✓ platform symlinks refreshed”

约束

• “最新”版本以 GitHub releases 为准 — npx skills add 可能会缓存较旧的版本。步骤 1-2 会获取最新的 release 标签，并最多重试安装 3 次，以确保安装了正确的版本。
• 切勿跳过迁移 — 即使 From 与本地版本不完全匹配，也要按表格顺序应用所有匹配的迁移
• 每次单独迁移后都要更新 groove-version:，而不是只在最后更新
• 如果迁移失败：停止操作，报告失败情况和当前版本，不要继续
• 不要修改技能文件 — npx skills update 会处理这些文件；此命令仅迁移本地状态
• 本地状态包括：.groove/index.md 配置键、记忆目录结构、AGENTS.md 章节
• 每个迁移文件都具有幂等性 — 如果部分失败后重新运行，应当是安全的