Back to Details

upgrade-plugin

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Upgrade Plugin

升级插件

Orchestrate project-level migrations by reading CHANGELOG.md as the single source of truth for migration steps.
以CHANGELOG.md作为迁移步骤的唯一可信来源，编排项目级别的迁移操作。

When to Use

使用场景

Called by 
/workflows:upgrade
command to handle the upgrade process.
由
/workflows:upgrade
命令调用，用于处理升级流程。

How It Works

工作原理

1. Detect Current Version

1. 检测当前版本

Read 
thoughts/.version
in the project directory:
current: v1.2.2
migrated_from: v1.2.1
migration_date: 2026-02-03
If file doesn't exist, detect from directory structure and create it.
读取项目目录下的
thoughts/.version
文件：
current: v1.2.2
migrated_from: v1.2.1
migration_date: 2026-02-03
如果该文件不存在，则通过目录结构检测版本并创建该文件。

2. Read CHANGELOG

2. 读取CHANGELOG

Read 
CHANGELOG.md
from the plugin directory to understand:
  • What changed in the target version
  • Migration steps required
  • Version detection patterns
  • What to ask the user
The CHANGELOG contains all version-specific migration logic.
从插件目录读取
CHANGELOG.md
文件，以了解：
  • 目标版本中的变更内容
  • 所需的迁移步骤
  • 版本检测规则
  • 需要向用户询问的内容
CHANGELOG中包含所有特定版本的迁移逻辑。

3. Execute Migration

3. 执行迁移

Follow the migration steps described in CHANGELOG:
  • Ask user questions using AskUserQuestion (for groupings, edge cases, cleanup)
  • Copy/move files as described
  • Update cross-references
  • Preserve originals until user confirms cleanup
按照CHANGELOG中描述的迁移步骤执行：
  • 使用AskUserQuestion向用户询问问题（用于分组、边缘情况处理、清理操作）
  • 按照描述复制/移动文件
  • 更新交叉引用
  • 在用户确认清理前保留原始文件

4. Update Version File

4. 更新版本文件

After successful migration, update 
thoughts/.version
:
current: v1.3.0
migrated_from: v1.2.2
migration_date: 2026-02-04
迁移成功后，更新
thoughts/.version
文件：
current: v1.3.0
migrated_from: v1.2.2
migration_date: 2026-02-04

Key Principles

核心原则

  • CHANGELOG is source of truth - All version-specific logic lives there
  • Project-level tracking - Each project has its own 
    thoughts/.version
  • Ask, don't assume - Use AskUserQuestion for all decisions
  • Preserve data - Never delete without user confirmation
  • Generate reports - Show what was done after migration
  • CHANGELOG为唯一可信来源 - 所有特定版本的逻辑都存储于此
  • 项目级跟踪 - 每个项目都有独立的
    thoughts/.version
    文件
  • 询问而非假设 - 所有决策都通过AskUserQuestion向用户确认
  • 数据保留 - 未经用户确认绝不删除任何内容
  • 生成报告 - 迁移完成后展示操作内容

Example Workflow

示例流程

1. User runs /workflows:upgrade
2. Skill reads thoughts/.version → "v1.2.2"
3. Skill reads CHANGELOG.md → finds v1.3.0 migration section
4. Skill follows migration steps from CHANGELOG
5. Skill asks user questions via AskUserQuestion
6. Skill executes migration
7. Skill updates thoughts/.version → "v1.3.0"
8. Skill generates report
This design means the skill never needs updating - only CHANGELOG changes per version.
1. User runs /workflows:upgrade
2. Skill reads thoughts/.version → "v1.2.2"
3. Skill reads CHANGELOG.md → finds v1.3.0 migration section
4. Skill follows migration steps from CHANGELOG
5. Skill asks user questions via AskUserQuestion
6. Skill executes migration
7. Skill updates thoughts/.version → "v1.3.0"
8. Skill generates report
这种设计意味着该Skill无需更新——仅需针对每个版本修改CHANGELOG即可。