toprank-upgrade

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/toprank-upgrade

Upgrade the toprank plugin to the latest version and show what's new.

将toprank插件升级至最新版本并展示更新内容。

Key paths

关键路径

What	Path
Marketplace repo	`~/.claude/plugins/marketplaces/nowork-studio/`
Plugin cache	`~/.claude/plugins/cache/nowork-studio/toprank/<version>/`
Installed plugins	`~/.claude/plugins/installed_plugins.json`
Update state	`~/.toprank/`

内容	路径
市场仓库	`~/.claude/plugins/marketplaces/nowork-studio/`
插件缓存	`~/.claude/plugins/cache/nowork-studio/toprank/<version>/`
已安装插件	`~/.claude/plugins/installed_plugins.json`
更新状态	`~/.toprank/`

Inline upgrade flow

内联升级流程

This section is used when a skill preamble outputs

UPGRADE_AVAILABLE

本节用于技能前置输出

UPGRADE_AVAILABLE

时的场景。

Step 1: Auto-upgrade

步骤1：自动升级

Log "Upgrading toprank v{old} → v{new}..." and proceed to Step 2.

记录日志“Upgrading toprank v{old} → v{new}...”，然后进入步骤2。

Step 2: Detect current install

步骤2：检测当前安装

First check for dev symlink (see "Dev symlink detection" section). If detected, stop — do not upgrade.

bash

undefined

首先检查是否存在开发符号链接（参见“开发符号链接检测”部分）。如果检测到，则停止操作——不进行升级。

bash

undefined

Find the currently installed plugin path

INSTALLED_DIR=$(ls -d ~/.claude/plugins/cache/nowork-studio/toprank/*/ 2>/dev/null | grep -v '.bak' | head -1) if [ -z "$INSTALLED_DIR" ]; then echo "ERROR: toprank plugin not found in cache"; exit 1 fi MARKETPLACE_DIR="$HOME/.claude/plugins/marketplaces/nowork-studio" if [ ! -d "$MARKETPLACE_DIR/.git" ]; then echo "ERROR: marketplace repo not found at $MARKETPLACE_DIR"; exit 1 fi echo "Current install: $INSTALLED_DIR" echo "Marketplace repo: $MARKETPLACE_DIR"

undefined

undefined

Step 3: Save old version

步骤3：保存旧版本

bash

OLD_VERSION=$(cat "$INSTALLED_DIR/VERSION" 2>/dev/null | tr -d '[:space:]' || echo "unknown")

bash

OLD_VERSION=$(cat "$INSTALLED_DIR/VERSION" 2>/dev/null | tr -d '[:space:]' || echo "unknown")

Step 4: Update marketplace repo and install

步骤4：更新市场仓库并安装

bash

cd "$MARKETPLACE_DIR"
git fetch origin
git reset --hard origin/main
NEW_VERSION=$(cat VERSION | tr -d '[:space:]')
GIT_SHA=$(git rev-parse HEAD)

bash

cd "$MARKETPLACE_DIR"
git fetch origin
git reset --hard origin/main
NEW_VERSION=$(cat VERSION | tr -d '[:space:]')
GIT_SHA=$(git rev-parse HEAD)

Create new versioned cache directory

NEW_CACHE_DIR="$HOME/.claude/plugins/cache/nowork-studio/toprank/$NEW_VERSION" if [ -d "$NEW_CACHE_DIR" ]; then rm -rf "$NEW_CACHE_DIR" fi mkdir -p "$NEW_CACHE_DIR"

Copy plugin files (exclude .git to save space)

rsync -a --exclude='.git' "$MARKETPLACE_DIR/" "$NEW_CACHE_DIR/"


If the copy fails, warn: "Upgrade failed — the old version is still active. Run `/toprank-upgrade` manually." and stop.

rsync -a --exclude='.git' "$MARKETPLACE_DIR/" "$NEW_CACHE_DIR/"


如果复制失败，提示：“Upgrade failed — the old version is still active. Run `/toprank-upgrade` manually.” 并停止操作。

Step 5: Update installed_plugins.json

步骤5：更新installed_plugins.json

Read

~/.claude/plugins/installed_plugins.json

, then update the

toprank@nowork-studio

entry:

bash

python3 -c "
import json, os
from datetime import datetime, timezone

path = os.path.expanduser('~/.claude/plugins/installed_plugins.json')
with open(path) as f:
    data = json.load(f)

data['plugins']['toprank@nowork-studio'] = [{
    'scope': 'user',
    'installPath': os.path.expanduser('~/.claude/plugins/cache/nowork-studio/toprank/$NEW_VERSION'),
    'version': '$NEW_VERSION',
    'installedAt': data['plugins'].get('toprank@nowork-studio', [{}])[0].get('installedAt', datetime.now(timezone.utc).isoformat()),
    'lastUpdated': datetime.now(timezone.utc).isoformat(),
    'gitCommitSha': '$GIT_SHA'
}]

with open(path, 'w') as f:
    json.dump(data, f, indent=4)
print('Updated installed_plugins.json: toprank@nowork-studio -> v$NEW_VERSION')
"

读取

~/.claude/plugins/installed_plugins.json

，然后更新

toprank@nowork-studio

条目：

bash

python3 -c "
import json, os
from datetime import datetime, timezone

path = os.path.expanduser('~/.claude/plugins/installed_plugins.json')
with open(path) as f:
    data = json.load(f)

data['plugins']['toprank@nowork-studio'] = [{
    'scope': 'user',
    'installPath': os.path.expanduser('~/.claude/plugins/cache/nowork-studio/toprank/$NEW_VERSION'),
    'version': '$NEW_VERSION',
    'installedAt': data['plugins'].get('toprank@nowork-studio', [{}])[0].get('installedAt', datetime.now(timezone.utc).isoformat()),
    'lastUpdated': datetime.now(timezone.utc).isoformat(),
    'gitCommitSha': '$GIT_SHA'
}]

with open(path, 'w') as f:
    json.dump(data, f, indent=4)
print('Updated installed_plugins.json: toprank@nowork-studio -> v$NEW_VERSION')
"

Step 6: Clean up old cache versions

步骤6：清理旧缓存版本

Remove old versioned cache directories (keep only the new one). Never remove a

dev

symlink:

bash

for dir in ~/.claude/plugins/cache/nowork-studio/toprank/*/; do
  ver=$(basename "$dir")
  if [ "$ver" != "$NEW_VERSION" ] && [ "$ver" != "dev" ]; then
    rm -rf "$dir"
    echo "Removed old cache: $ver"
  fi
done

移除旧版本的缓存目录（仅保留新版本）。切勿删除

dev

符号链接：

bash

for dir in ~/.claude/plugins/cache/nowork-studio/toprank/*/; do
  ver=$(basename "$dir")
  if [ "$ver" != "$NEW_VERSION" ] && [ "$ver" != "dev" ]; then
    rm -rf "$dir"
    echo "Removed old cache: $ver"
  fi
done

Step 7: Write marker + clear update state

步骤7：写入标记并清除更新状态

bash

mkdir -p ~/.toprank
echo "$OLD_VERSION" > ~/.toprank/just-upgraded-from
rm -f ~/.toprank/last-update-check
rm -f ~/.toprank/update-snoozed

bash

mkdir -p ~/.toprank
echo "$OLD_VERSION" > ~/.toprank/just-upgraded-from
rm -f ~/.toprank/last-update-check
rm -f ~/.toprank/update-snoozed

Step 8: Show What's New

步骤8：展示更新内容

Read

$NEW_CACHE_DIR/CHANGELOG.md

. Find all version entries between the old version and the new version. Summarize as 3-7 bullets grouped by theme — focus on user-facing changes, skip internal refactors.

Format:

toprank v{new} — upgraded from v{old}!

What's new:
- [bullet 1]
- [bullet 2]
- ...

The new version will be fully active on your next Claude Code session.

读取

$NEW_CACHE_DIR/CHANGELOG.md

。找出旧版本与新版本之间的所有版本条目。按主题整理为3-7条要点——聚焦于用户可见的变更，跳过内部重构内容。

格式：

toprank v{new} — upgraded from v{old}!

What's new:
- [bullet 1]
- [bullet 2]
- ...

The new version will be fully active on your next Claude Code session.

Step 9: Continue

步骤9：继续操作

After showing What's New, continue with whatever skill the user originally invoked.

展示更新内容后，继续执行用户最初调用的技能。

Dev symlink detection

开发符号链接检测

Before upgrading, check if the installed cache directory is a symlink named

dev

bash

CACHE_DIR=$(ls -d ~/.claude/plugins/cache/nowork-studio/toprank/*/ 2>/dev/null | head -1)
if [ -L "${CACHE_DIR%/}" ] && [ "$(basename "$CACHE_DIR")" = "dev" ]; then
  echo "DEV_SYMLINK"
fi

DEV_SYMLINK

: tell the user "toprank is installed as a dev symlink — it always points to your local source (v$(cat "$CACHE_DIR/VERSION" 2>/dev/null | tr -d '[:space:]')). No upgrade needed." and stop. Do not proceed with Steps 2–8.

升级前，检查已安装的缓存目录是否为名为

dev

的符号链接：

bash

CACHE_DIR=$(ls -d ~/.claude/plugins/cache/nowork-studio/toprank/*/ 2>/dev/null | head -1)
if [ -L "${CACHE_DIR%/}" ] && [ "$(basename "$CACHE_DIR")" = "dev" ]; then
  echo "DEV_SYMLINK"
fi

如果检测到

DEV_SYMLINK

：告知用户“toprank is installed as a dev symlink — it always points to your local source (v$(cat "$CACHE_DIR/VERSION" 2>/dev/null | tr -d '[:space:]')). No upgrade needed.” 并停止操作。不执行步骤2至8。

Standalone usage

独立使用方式

When invoked directly as

/toprank-upgrade

Check for dev symlink (see "Dev symlink detection" above). If detected, stop.
Force a fresh update check (bypass cache and snooze):

bash

_UPD_BIN=$(ls ~/.claude/plugins/cache/nowork-studio/toprank/*/bin/toprank-update-check 2>/dev/null | head -1)
[ -n "$_UPD_BIN" ] && _UPD=$("$_UPD_BIN" --force 2>/dev/null || true) || _UPD=""
echo "$_UPD"

If
```
UPGRADE_AVAILABLE <old> <new>
```
: follow Steps 2–8 above.
If no
```
UPGRADE_AVAILABLE
```
output: tell the user "You're already on the latest version (v{LOCAL})."

当直接调用

/toprank-upgrade

时：

检查是否存在开发符号链接（参见上文“开发符号链接检测”）。如果检测到，则停止操作。
强制进行全新更新检查（绕过缓存和暂不更新设置）：

bash

_UPD_BIN=$(ls ~/.claude/plugins/cache/nowork-studio/toprank/*/bin/toprank-update-check 2>/dev/null | head -1)
[ -n "$_UPD_BIN" ] && _UPD=$("$_UPD_BIN" --force 2>/dev/null || true) || _UPD=""
echo "$_UPD"

如果输出
```
UPGRADE_AVAILABLE <old> <new>
```
：执行上述步骤2至8。
如果未输出
```
UPGRADE_AVAILABLE
```
：告知用户“You're already on the latest version (v{LOCAL}).”