nav-upgrade

自动化Navigator插件更新。检测当前版本，更新插件，验证安装，更新项目CLAUDE.md，并验证新功能。当用户提及升级Navigator或获取新功能时自动调用。

Navigator升级技能

自动化Navigator插件更新，包括版本检测、冲突解决和更新后验证。

何时调用

自动调用当用户说：

“更新Navigator”
“升级Navigator插件”
“获取最新Navigator版本”
“更新到Navigator v3.3.0”
“安装新Navigator功能”
“检查Navigator更新”

这个做了什么

6步工作流程：

版本检测：检查当前Navigator版本与最新版本
插件更新：执行 /plugin update navigator
验证：确认更新成功
CLAUDE.md更新：通过nav-update-claude更新项目配置
钩子设置：在项目中安装/更新令牌监控钩子
功能发现：展示可用的新功能

节省时间：手动更新（10-15分钟）→ 自动化（2分钟）

先决条件

Navigator插件已安装
项目已用Navigator初始化
插件更新需要互联网连接

工作流程协议

第1步：版本检测

执行：version_detector.py

检查稳定和预发布版本：

# 当前安装版本
grep '"version"' .claude-plugin/plugin.json

# 获取所有发布（包括预发布）
curl -s https://api.github.com/repos/alekspetrov/navigator/releases

# 解析：
# - 最新稳定（预发布：false）
# - 最新预发布（预发布：true）
# - 与当前版本比较

输出场景：

场景1：稳定更新可用

{
  "current_version": "4.0.0",
  "latest_stable": "4.2.0",
  "latest_prerelease": null,
  "recommendation": "update_to_stable"
}

场景2：预发布可用（用户在稳定版上）

{
  "current_version": "4.0.0",
  "latest_stable": "4.0.0",
  "latest_prerelease": "4.3.0",
  "recommendation": "offer_prerelease_option"
}

提供选择：

✅ 您使用的是最新的稳定版本（v4.0.0）

⚡ 有实验版本可用：v4.3.0

v4.3.0新功能（实验）：
• 多Claude代理工作流
• 30%成功率（用于简单功能）
• PM集成与工单关闭

选项：
[1] 留在稳定版v4.0.0（推荐）
[2] 尝试实验版v4.3.0（早期采用者）

您的选择 [1-2]：

场景3：已经是最新（稳定或预发布）

✅ 您使用的是v4.3.0（最新的实验版）

最新稳定版：v4.0.0
状态：您已经超过稳定版（测试实验功能）

您版本中的新功能：
- 多Claude工作流
- 子Claude阶段中的任务代理

跳转到第5步（功能发现）。

场景4：在预发布上，有更新的稳定版可用

⚠️  您使用的是v4.3.0（实验版）
最新稳定版：v4.6.0

建议：更新到稳定版v4.6.0
v4.3.0中的实验功能现在已稳定。

第2步：插件更新

基于场景的更新策略：

场景2：预发布可用（用户在稳定版上）

当检测到预发布时，使用AskUserQuestion工具提供选择：

✅ 您使用的是最新的稳定版本（v4.0.0）

⚡ 有实验版本可用：v4.3.0

v4.3.0新功能（实验）：
• 多Claude代理工作流
• 30%成功率（用于简单功能）
• PM集成与工单关闭

**问题**：您想要哪个版本？

**选项**：
[1] **留在稳定版v4.0.0**（推荐）
    - 生产就绪
    - 无实验功能
    - 最可靠

[2] **尝试实验版v4.3.0**（早期采用者）
    - 多Claude工作流
    - 最新功能
    - 30%完成率
    - 帮助测试新功能

您的选择？

如果用户选择[1]（保持稳定）：

✓ 保持在v4.0.0（最新稳定版）

无需操作。当您准备好尝试实验功能时，再次运行nav-upgrade。

如果用户选择[2]（尝试实验版）：

# 卸载当前版本
/plugin uninstall navigator

# 添加市场（如果尚未添加）
/plugin marketplace add alekspetrov/navigator

# 安装特定预发布版本
# 注意：/plugin update只获取稳定版，必须安装特定版本
git clone https://github.com/alekspetrov/navigator.git /tmp/navigator-v4.3.0
cd /tmp/navigator-v4.3.0
git checkout v4.3.0

# 从本地检出安装
/plugin install /tmp/navigator-v4.3.0

然后验证安装：

/plugin list | grep navigator
# 应显示：navigator (v4.3.0)

场景1：稳定更新可用

执行：/plugin update navigator

监控输出：

更新navigator...
✅ Navigator更新到v4.2.0

如果更新失败：

❌ 更新失败：[错误信息]

故障排除：
1. 重启Claude Code
2. 尝试：/plugin uninstall navigator && /plugin install navigator
3. 检查互联网连接
4. 报告问题：https://github.com/alekspetrov/navigator/issues

自动重试（一次）：如果更新失败，尝试自动卸载/重新安装：

/plugin uninstall navigator
/plugin marketplace add alekspetrov/navigator
/plugin install navigator

第3步：验证

执行：plugin_verifier.py

验证：

插件版本与最新匹配
新技能在文件系统中注册
技能可调用

测试新技能（v3.3.0示例）：

# 测试visual-regression技能是否存在
ls ~/.config/claude/plugins/navigator/skills/visual-regression/SKILL.md 2>/dev/null || echo "技能未找到"

输出：

✅ 更新验证

版本：v3.3.0 ✅
新技能注册：visual-regression ✅
技能可调用：✅

更新成功！

如果验证失败：

⚠️ 更新完成但验证失败

问题：visual-regression技能未找到
修复：重启Claude Code以重新加载技能

重启后验证：
"为Button设置视觉回归"

提示用户重启Claude Code。

重要 - 所有更新后都需要重启：

Claude Code在会话开始时缓存技能路径。即使更新成功，也需要重启才能加载新技能：

⚠️  需要重启

插件成功更新到vX.Y.Z。
Claude Code在会话开始时缓存技能路径。

要使用新/更新的技能：
1. 关闭Claude Code
2. 重新打开Claude Code
3. 运行"nav start"以验证新版本

不重启：
- 旧技能版本继续运行
- 新技能将不可用
- 可能会看到"技能未找到"错误

这是Claude Code的行为，不是Navigator问题。插件文件正确更新，但活动会话继续使用旧版本的缓存技能路径。

第4步：更新项目CLAUDE.md（自动）

插件更新后，自动调用：nav-update-claude技能

🔄 与更新的插件同步项目CLAUDE.md...

✓ 使用GitHub上的模板（v4.3.0）
✓ 提取自定义设置
✓ 生成更新的CLAUDE.md

自动发生什么：

检测到新插件版本（例如，v4.3.0）
从GitHub获取匹配的模板
保留项目自定义设置
在当前项目中更新CLAUDE.md
显示差异以供审查

模板同步的好处：

✅ CLAUDE.md始终与安装的插件版本匹配
✅ 无模板漂移（v4.0模板与v4.3插件）
✅ 可以访问预发布模板
✅ 离线回退到捆绑模板

用户操作所需：

审查更改并提交：

git add CLAUDE.md
git commit -m "chore: update CLAUDE.md to Navigator v4.3.0"

查看：nav-update-claude技能了解详细信息。

第5步：设置令牌监控钩子

安装或更新项目钩子以监控令牌预算：

# 创建.claude目录（如果不存在）
mkdir -p .claude

# 检查settings.json是否存在
if [ -f ".claude/settings.json" ]; then
  # 备份现有设置
  cp .claude/settings.json .claude/settings.json.backup
  echo "✓ 备份现有.claude/settings.json"
fi

# 写入钩子配置
cat > .claude/settings.json << 'EOF'
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|Bash|Task",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"${CLAUDE_PLUGIN_DIR}/hooks/monitor-tokens.py\"",
            "timeout": 5
          }
        ]
      }
    ]
  }
}
EOF

echo "✓ 安装令牌监控钩子"

这能实现什么：

在每次工具调用后监控上下文使用情况
在70%使用时警告，85%时发出严重警报
在最佳时机建议/nav:compact
防止长时间会话期间上下文崩溃

输出：

✓ 安装令牌监控钩子

v4.6.0中的新功能：
  - 自动上下文预算监控
  - 在达到上下限之前警告
  - 在最佳时机建议紧凑

第6步：升级后设置检查

检查新功能是否需要设置：

# 检查有设置要求的技能
if [ -f "$NAVIGATOR_PATH/skills/product-design/setup.sh" ]; then
  # 检查venv是否存在
  if [ ! -d "$NAVIGATOR_PATH/skills/product-design/venv" ]; then
    echo "⚠️  product-design技能需要设置"
    NEEDS_SETUP=true
  fi
fi

如果需要设置，显示说明：

⚠️  新功能需要设置

product-design技能（v3.4.0+）需要Python依赖项：

**一次性设置**（30秒）：
```bash
cd ~/.claude/plugins/marketplaces/jitd-marketplace/skills/product-design
./setup.sh

这将安装：

用于直接Figma连接的Python MCP SDK
95%的编排减少
92%的令牌节省

使用后： “从Figma回顾这个设计：[URL]”


**在TodoWrite中记录设置需求**以跟踪。

---

### 第7步：功能发现

**展示**在更新版本中可用的新功能。

**对于v3.3.0更新**：
````markdown
🎉 Navigator v3.3.0更新完成！

## 新功能可用

### visual-regression技能（新）
5分钟内设置Storybook + Chromatic，而不是2-3小时。

**用法**：

“为ProfileCard设置视觉回归” “为Button组件添加Chromatic” “为Input, Card, Modal配置视觉测试”


**它的作用**：
✅ 生成所有变体的Storybook故事
✅ 配置Chromatic/Percy/BackstopJS
✅ 创建CI工作流（GitHub Actions, GitLab CI）
✅ 添加可访问性测试

**完整的设计管道**（v3.2 + v3.3）：
1. "从Figma回顾这个设计"（v3.2）
2. 实施组件
3. "设置视觉回归"（v3.3新）
4. CI中的自动视觉测试

### 更新后的技能计数
- **17个总技能**（之前是16）
- 10个核心Navigator技能
- 7个开发技能

### 集成
visual-regression与product-design技能集成，为完整的设计→代码→测试工作流。

## 现在就试试

如果您的项目中有Storybook：

“为[ComponentName]设置视觉回归”


如果您没有Storybook：
```bash
npx storybook init

然后：

"为[ComponentName]设置视觉回归"

文档

发布说明：https://github.com/alekspetrov/navigator/releases/tag/v3.3.0
技能文档：skills/visual-regression/SKILL.md
示例：skills/visual-regression/examples/
SOP：.agent/sops/testing/visual-regression-setup.md（在您的项目中创建）


---

## 预定义函数

### functions/version_detector.py

**目的**：检测当前和最新的Navigator版本

**用法**：
```bash
python3 functions/version_detector.py
```

**输出**：
```json
{
  "current_version": "3.2.0",
  "latest_version": "3.3.0",
  "update_available": true,
  "release_url": "https://github.com/alekspetrov/navigator/releases/tag/v3.3.0",
  "changes": {
    "new_skills": ["visual-regression"],
    "updated_skills": ["product-design"],
    "new_features": ["多工具VR支持", "CI工作流"],
    "breaking_changes": []
  }
}
```

### functions/plugin_updater.py

**目的**：执行插件更新，带重试逻辑

**用法**：
```bash
python3 functions/plugin_updater.py --target-version 3.3.0
```

**操作**：
1. 执行 `/plugin update navigator`
2. 如果失败，重试卸载/重新安装
3. 验证更新成功
4. 返回状态

### functions/plugin_verifier.py

**目的**：验证更新是否成功完成

**用法**：
```bash
python3 functions/plugin_verifier.py --expected-version 3.3.0
```

**检查**：
- 插件版本与预期匹配
- 新技能在文件系统中存在
- 技能在plugin.json中注册
- 技能可调用（测试调用）

---

## 错误处理

### 更新失败：网络错误

```
❌ 更新失败：无法连接到插件市场

修复：
1. 检查互联网连接
2. 稍后再试
3. 手动更新：/plugin uninstall navigator && /plugin install navigator
```

### 更新失败：权限拒绝

```
❌ 更新失败：权限拒绝

修复：
1. 关闭Claude Code
2. 检查~/.config/claude/plugins/权限
3. 重启Claude Code
4. 再次尝试更新
```

### 验证失败：技能未找到

```
⚠️ 更新完成但新技能未找到

修复：
1. 重启Claude Code（技能重新加载所需）
2. 验证：/plugin list
3. 测试："为Button设置视觉回归"
```

自动提示用户重启。

### CLAUDE.md更新冲突

```
⚠️ CLAUDE.md更新与您的自定义设置有冲突

选项：
[1] 保留我的自定义设置（合并新功能）
[2] 使用新模板（丢失自定义设置）
[3] 先给我看看差异

回复选择
```

让用户决定如何处理冲突。

---

## 升级路径

### 从v3.0.x到v3.3.0

**变更**：
- +2技能（nav-markers在v3.1，visual-regression在v3.3）
- OpenTelemetry集成（v3.1）
- 产品设计技能（v3.2）
- 视觉回归技能（v3.3）

**破坏性变更**：无（完全向后兼容）

### 从v3.1.x到v3.3.0

**变更**：
- 产品设计技能（v3.2）
- 视觉回归技能（v3.3）
- 更新后的技能计数（17个总技能）

**破坏性变更**：无

### 从v3.2.x到v3.3.0

**变更**：
- 视觉回归技能
- 与product-design工作流集成
- 更新后的技能计数（17个总技能）

**破坏性变更**：无

---

## 升级后清单

升级后验证：
- ✅ `/plugin list`显示新版本
- ✅ CLAUDE.md更新了新模式
- ✅ 新技能自动调用自然语言
- ✅ 现有技能仍然有效
- ✅ 项目配置无冲突

**如果全部检查**：更新成功！

---

## 回滚

如果更新导致问题：

```
"将Navigator回滚到v3.2.0"
```

这将：
1. 卸载当前版本
2. 从市场安装特定版本
3. 更新CLAUDE.md以匹配
4. 验证回滚成功

---

## 集成点

### 与nav-update-claude

插件更新后，自动调用`nav-update-claude`以同步项目配置。

### 与nav-start

更新后，`nav-start`显示会话统计中可用的新功能。

### 与nav-init

如果升级前未初始化项目，建议使用最新功能运行`nav-init`。

---

## 示例

### 示例1：简单更新

```
用户："更新Navigator"

→ 检测到：v3.2.0 → v3.3.0可用
→ 更新插件
→ 更新CLAUDE.md
→ 显示："visual-regression技能现在可用"
→ 建议："为[组件]设置视觉回归"
```

### 示例2：已经是最新

```
用户："更新Navigator"

→ 检测到：已经是v3.3.0
→ 显示可用的新功能
→ 如果尚未使用，则建议尝试visual-regression
```

### 示例3：需要重启的更新

```
用户："更新Navigator"

→ 更新插件
→ 验证：技能未找到（需要重启）
→ 提示："请重启Claude Code以完成更新"
→ 重启后：验证成功
```

---

## 最佳实践

1. **定期更新**：每月检查更新
2. **阅读发布说明**：在使用新功能之前了解新功能
3. **测试新技能**：先在测试项目中尝试新功能
4. **报告问题**：为更新问题提交GitHub问题
5. **备份CLAUDE.md**：更新前保留备份（自动创建）

---

## 版本历史

- **v1.0.0**：初始nav-upgrade技能（Navigator v3.3.1）

---

## 未来增强

- 在`nav-start`上自动检查更新（选择加入）
- CLI中显示变更日志
- 主要版本更新通知
- 破坏性变更的自动迁移脚本

---

**最后更新**：2025-10-21
**技能类型**：核心Navigator
**自动调用**：是