plugin-refresh 插件刷新
定位
刷新 Claude Code 插件，把 marketplace 远端 / 本地源目录的最新内容（skill / hook / agent / SKILL.md 正文）落到本机 cache 并生效。
对话里说「刷新插件」「拉最新 skill」「为啥改了 SKILL.md 没生效」「为啥 cc 看到的还是旧 skill」「刷 cache」等都会触发。
关键认知（必读）
Claude Code 的插件加载分两层，这两层可能不一致：
| 层 | 数据来源 | 改源后是否实时反映 |
|---|---|---|
claude plugin details <plugin> 显示的组件清单（skill 名字、数量） | 源目录 | ✅ 实时 |
| CC 冷启动时注入 LLM system prompt 的 SKILL.md 正文 | ~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/ | ❌ 不会，必须刷 cache |
危险之处在于：改了 SKILL.md 后 plugin details 里数量、名字全对，看起来生效了，但 LLM 拿到的指令可能还是旧版。
改完源要做两件事
1) 刷 cache（本地目录插件走下方脚本；远端插件见后文）
2) 重启 Claude Code 会话
缺一不可：不刷 cache，LLM 读到的 SKILL.md 正文是旧的；不重启会话，system prompt 是冷启动时注入的，当前会话里还是旧版。
⚠️ 不要把 cache 做成指向源目录的软链
有一种流行的「偷懒」做法：把 ~/.claude/plugins/cache/<mp>/<plugin>/<ver> 换成指向源目录的软链，让源一改 cache 立即跟上，从此免刷。
别这么做，它会损坏你的源码。
claude plugin uninstall / install 会对 cache 目录做删除和写入。cache 若是软链，这些写操作会穿透软链直接改写源目录。实测后果：一个已经从 A 插件移走的 skill，被 install 从旧内容里写回了 A 的源目录，而 B 插件反而少了它——源码被静默改写，git 里凭空多出 / 少掉文件。
更阴险的是，软链方案和「改完刷 cache」的纪律不能共存：只要在软链生效时刷一次 cache，雷就炸了。
正确做法是让 cache 保持真实副本——CC 的读写只作用于副本，永远碰不到源码。用这条命令确认：
ls -ld ~/.claude/plugins/cache/<marketplace>/<plugin>/<version>
# 以 d 开头 → 真实副本（正确）
# 以 l 开头 → 软链（危险，删掉它重新 install）
本地目录插件（cache 是真副本时）
先确认来源类型：
claude plugin marketplace list
Source: 行有两类：Source: Directory (/abs/path) 是本地目录插件；Source: GitHub (...) / HTTP (...) 是远端。
本地目录插件直接跑 vft-kit 封装的脚本（幂等）：
bash ${CLAUDE_PLUGIN_ROOT}/skills/plugin-refresh/scripts/refresh-local-plugin.sh -p <plugin-name>
# marketplace 名与 plugin 名不同时
bash ${CLAUDE_PLUGIN_ROOT}/skills/plugin-refresh/scripts/refresh-local-plugin.sh -p <plugin> -m <marketplace>
脚本做的事：校验来源是 Directory → uninstall → install（完整重建 cache）→ 比对源与 cache 下 SKILL.md 数量 → 抽一份比 size，提早抓「个数对但内容旧」。
为什么 marketplace update / 单跑 plugin install 都不行
| 命令 | 是否刷 cache |
|---|---|
claude plugin marketplace update <mp> | ❌ 只更新索引 manifest，不动 cache |
claude plugin install <plugin>@<mp>（已装） | ❌ 跳过：Plugin is already installed |
uninstall 然后 install | ✅ 完整重建 cache |
所以脚本走 uninstall + install 这条路。
远端 marketplace 插件
# 1) 更新 marketplace 索引（拉远端最新 manifest）
claude plugin marketplace update <marketplace-name>
# 2) 重装插件（CLI 读 manifest 后落最新版到 cache）
claude plugin install <plugin-name>@<marketplace-name>
# 3) 验证
claude plugin details <plugin-name>
若 plugin install 提示 already installed 但你确认远端有更新，走 uninstall + install 兜底。
常见诊断对照
| 现象 | 大概率原因 | 处理 |
|---|---|---|
| 改了 SKILL.md，cc 看到的还是旧版 | cache 是真副本且没刷 | 刷 cache + 重启会话 |
| 刷了 cache 还是旧版 | 没重启会话（system prompt 冷启动加载） | 重启会话 |
| 新加了 skill 目录，cc 调用时找不到 | cache 没刷 + 没重启 | 先刷，再重启 |
details 数量对得上，但 skill 行为还是老的 | 经典陷阱：组件清单读源、SKILL.md 正文读 cache | 刷 cache |
| 源目录里凭空多出 / 少掉文件 | cache 被做成了软链，写操作穿透到源目录 | 删掉软链、重新 install，让 cache 回真副本 |
details 数量对不上 | marketplace 索引或注册损坏 | marketplace remove + add + install 兜底 |
plugin install 报已装 | install 幂等会跳过 | 用 refresh-local-plugin.sh，它先 uninstall |
操作原则
- 确保 cache 是真实副本，不是软链——软链会让写操作穿透到源目录，损坏源码。
- 命令幂等，重复跑无副作用。
- 别用
claude plugin update（不同 CLI 版本行为不一致）。 - 无论刷不刷，都要重启会话——cache 对了但 CC 已把旧版加载进 system prompt，必须冷启。
相关
- 备份 / 恢复插件清单 → cc-backup-restore
- 核对插件装齐了没 → cc-baseline
还没有留言，来发表第一条吧～