升级、卸载与清理

区分插件缓存和 Hub 数据，安全处理升级、迁移、缓存清理和彻底删除。

插件缓存和 Hub 数据是两套独立资产；先理解它们，再进行升级或清理。

升级流程

marketplace 指向 GitHub master。本地改动需要 commit、push，并由 Release workflow 发布后才会成为可安装版本。

bun run check
git commit
git push origin master

Release workflow 通过 semantic-release bump 版本、同步 metadata、更新 CHANGELOG.md、打 tag，并提交生成文件。

宿主刷新

在 /plugins 中 upgrade 或 reinstall 后，刷新或重启宿主并开启新 task。旧 task 可能仍持有旧 MCP tools schema。

如果 UI 报 upgrade failed 但这些条件成立，可以按安装成功处理：

~/.codex/plugins/cache/usora/usora/<new-version> exists
插件详情页显示 <new-version>
新 task 能看到预期 Usora tools

v1 Hub 迁移

Foundry 2.0 不会静默迁移 v1 Hub。先 dry run，再确认迁移：

hub_migrate
hub_migrate(confirm: true)

迁移会写入备份和 HubMigrated 事件。迁移前不要用写入工具创建新记录。

缓存清理

Clean old Usora plugin cache 调用 plugin_cache_cleanup。它默认 dry run，只会预览旧安装缓存；确认后才删除。该操作不会删除 Hub 数据。

卸载与数据删除

宿主负责卸载插件。卸载不会删除本地 Usora 数据。

彻底清空 Hub：

hub_status
hub_cleanup(mode: all, confirm: true)

hub_cleanup(mode: generated) 只归档状态为 PROCESSED、USED、ABSORBED 的 Activities。mode: all 会永久删除 Hub 记录、Skill、archive、event 和 config，因此必须传 confirm: true。