3a463313ea
## Bug 详情 /plugin marketplace 中的 Enable/Disable auto-update 会继承 CLI binary auto-updater 的禁用状态。在 CSC 默认关闭 CLI auto-updater 的场景下，plugin marketplace 的自动更新配置入口不可见，用户无法按 marketplace 配置 autoUpdate。 ## 根因 shouldSkipPluginAutoupdate() 复用了 isAutoUpdaterDisabled()，导致 ENABLE_AUTOUPDATER、/config channel、development build、nonessential traffic 等 CLI updater 门禁同时影响 plugin marketplace 自动更新。 ## 修复方案 将 plugin marketplace auto-update 门禁收敛为 DISABLE_AUTOUPDATER 和 FORCE_AUTOUPDATE_PLUGINS：默认不跳过 plugin auto-update；DISABLE_AUTOUPDATER 显式关闭；FORCE_AUTOUPDATE_PLUGINS 可覆盖关闭状态。 ## 变更要点 - 调整 shouldSkipPluginAutoupdate()，使 plugin auto-update 独立于 CLI binary updater 配置 - 新增 plugin autoupdate 门禁单元测试 - 补充 plugin auto-update 机制文档，记录 UI、配置优先级和环境变量行为 ## 自测 - bun test src/utils/__tests__/pluginAutoupdateConfig.test.ts - bun test src/utils/settings/__tests__/config.test.ts - bun run typecheck 仍失败，失败项为仓库既有 Zod 类型、缺声明和依赖类型问题，非本次变更引入
185 lines
8.6 KiB
Markdown
185 lines
8.6 KiB
Markdown
# Plugin Auto-Update 机制说明
|
||
|
||
本文记录当前代码中的 plugin auto-update 机制，包括启动链路、配置来源、UI 配置项、手动更新行为，以及复核时发现的配置注意点。
|
||
|
||
## 结论摘要
|
||
|
||
Plugin auto-update 是启动后的后台任务，用于刷新开启了 `autoUpdate` 的 marketplaces，并把这些 marketplaces 下已安装且与当前项目相关的 plugins bump 到新版本缓存。
|
||
|
||
它由两层配置决定：
|
||
|
||
1. Plugin auto-update 门禁不能处于跳过状态：`DISABLE_AUTOUPDATER=1` 会关闭它，除非设置 `FORCE_AUTOUPDATE_PLUGINS=true` 强制运行。
|
||
2. 单个 marketplace 必须被判定为 `autoUpdate: true`。
|
||
|
||
更新是 disk-only：后台任务只更新版本缓存和 `installed_plugins.json`，当前会话内存中的 plugin 列表不会立即替换。用户需要运行 `/reload-plugins` 或重启后才会使用新版本。
|
||
|
||
## 启动链路
|
||
|
||
后台入口在 `src/utils/backgroundHousekeeping.ts`：
|
||
|
||
- `startBackgroundHousekeeping()` 会调用 `autoUpdateMarketplacesAndPluginsInBackground()`。
|
||
- REPL 中第一次提交后会启动 housekeeping。
|
||
- headless 主流程在非 bare 模式下也会动态导入并启动 housekeeping。
|
||
|
||
核心实现位于 `src/utils/plugins/pluginAutoupdate.ts`：
|
||
|
||
1. `autoUpdateMarketplacesAndPluginsInBackground()` 先调用 `shouldSkipPluginAutoupdate()`。
|
||
2. 如果未跳过，读取启用 auto-update 的 marketplaces。
|
||
3. 对这些 marketplaces 调用 `refreshMarketplace()`。
|
||
4. 调用 `updatePluginsForMarketplaces()` 更新这些 marketplaces 下已安装的 plugins。
|
||
5. 如果有 plugin 被更新，通过 `onPluginsAutoUpdated()` 通知 UI。
|
||
|
||
后台刷新 marketplace 时会传入 `disableCredentialHelper: true`，避免启动后台任务触发交互式凭据提示。
|
||
|
||
## Plugin Auto-Update 门禁
|
||
|
||
门禁在 `src/utils/config.ts` 的 `shouldSkipPluginAutoupdate()`：
|
||
|
||
- 默认不跳过 plugin auto-update，因此 `/plugin marketplace` 中的 `Enable/Disable auto-update` 默认可见。
|
||
- `DISABLE_AUTOUPDATER=1` 会跳过 plugin auto-update，并隐藏 marketplace 详情里的 `Enable/Disable auto-update`。
|
||
- `FORCE_AUTOUPDATE_PLUGINS=1` 可以在 `DISABLE_AUTOUPDATER=1` 时重新启用 plugin auto-update 及其 UI 配置入口。
|
||
|
||
这与官方插件文档中的配置方式一致：如果用户禁用了自动更新，但仍希望插件自动更新可配置/可运行，可同时设置：
|
||
|
||
```bash
|
||
export DISABLE_AUTOUPDATER=1
|
||
export FORCE_AUTOUPDATE_PLUGINS=1
|
||
```
|
||
|
||
注意：`/config` 中的 CLI binary auto-update 状态、development build 限制、`ENABLE_AUTOUPDATER` 门禁和 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 不再决定 plugin marketplace 的 per-marketplace auto-update 开关是否可见。
|
||
|
||
## Marketplace `autoUpdate` 判定
|
||
|
||
判定逻辑在 `src/utils/plugins/schemas.ts` 的 `isMarketplaceAutoUpdate()`：
|
||
|
||
- 如果 marketplace entry 明确设置了 `autoUpdate`，使用显式值。
|
||
- 否则，官方 marketplace 默认开启 auto-update。
|
||
- 第三方 marketplace 默认关闭 auto-update。
|
||
- `knowledge-work-plugins` 虽在官方名称集合中，但默认不自动更新。
|
||
|
||
官方名称集合包括：
|
||
|
||
- `claude-code-marketplace`
|
||
- `claude-code-plugins`
|
||
- `claude-plugins-official`
|
||
- `anthropic-marketplace`
|
||
- `anthropic-plugins`
|
||
- `agent-skills`
|
||
- `life-sciences`
|
||
- `knowledge-work-plugins`
|
||
|
||
其中 `knowledge-work-plugins` 在 `NO_AUTO_UPDATE_OFFICIAL_MARKETPLACES` 中，因此默认关闭。
|
||
|
||
## 配置来源和优先级
|
||
|
||
Plugin auto-update 涉及两类 marketplace 配置：
|
||
|
||
1. 状态层：`known_marketplaces.json`
|
||
- schema 在 `KnownMarketplaceSchema`。
|
||
- 字段包括 `source`、`installLocation`、`lastUpdated`、可选 `autoUpdate`。
|
||
- 记录已 materialized 的 marketplace 缓存位置和刷新状态。
|
||
|
||
2. 意图层：settings 中的 `extraKnownMarketplaces`
|
||
- schema 在 `ExtraKnownMarketplaceSchema`。
|
||
- 也支持可选 `autoUpdate`。
|
||
- 用于 user/project/local/managed settings 声明希望存在的 marketplace。
|
||
|
||
自动更新读取启用 marketplaces 时，会先读取 `known_marketplaces.json`，再用 settings 声明的 `extraKnownMarketplaces[name].autoUpdate` 覆盖状态层值。也就是说，settings 声明的 `autoUpdate` 优先于 `known_marketplaces.json` 中的 `autoUpdate`。
|
||
|
||
`getDeclaredMarketplaces()` 的合并顺序是：
|
||
|
||
1. 隐式官方 marketplace 声明。
|
||
2. `--add-dir` 里的 extra marketplaces。
|
||
3. merged settings 里的 `extraKnownMarketplaces`。
|
||
|
||
## `/plugin marketplace` UI
|
||
|
||
Marketplace 管理 UI 在 `src/commands/plugin/ManageMarketplaces.tsx`。
|
||
|
||
详情菜单包含：
|
||
|
||
- `Browse plugins`
|
||
- `Update marketplace`
|
||
- `Enable auto-update` 或 `Disable auto-update`
|
||
- `Remove marketplace`
|
||
|
||
`Enable/Disable auto-update` 只有在 `shouldSkipPluginAutoupdate()` 为 false 时才显示。默认情况下该条件为 false，因此 marketplace auto-update 配置默认可见。只有显式设置 `DISABLE_AUTOUPDATER=1` 且未设置 `FORCE_AUTOUPDATE_PLUGINS=1` 时才会隐藏。
|
||
|
||
点击该开关后会调用 `setMarketplaceAutoUpdate()`：
|
||
|
||
- 更新 `known_marketplaces.json` 中该 marketplace 的 `autoUpdate`。
|
||
- 如果该 marketplace 是 settings 声明的，还会写回声明它的同一个 settings source，避免下次被 settings 覆盖。
|
||
- seed-managed marketplace 不允许切换 auto-update，会报错提示 seed 内容由管理员控制。
|
||
|
||
当某 marketplace 的 auto-update 已启用时，详情页底部会显示说明：CoStrict 会自动更新该 marketplace 及其已安装 plugins。
|
||
|
||
## `/config` UI
|
||
|
||
`/config` 中的 `Auto-update channel` 属于全局 CLI auto-updater 配置，不是 plugin 专用配置。
|
||
|
||
它会展示：
|
||
|
||
- `latest`
|
||
- `stable`
|
||
- `disabled` 和 disabled reason
|
||
|
||
Plugin auto-update 不使用 `latest/stable` channel 来选择插件版本，也不通过 `/config` 配置。插件版本来自 marketplace 刷新后的 plugin source、manifest version、git commit 等版本计算逻辑。
|
||
|
||
## 手动更新和自动更新的区别
|
||
|
||
手动更新路径包括：
|
||
|
||
- `/plugin marketplace update`
|
||
- marketplace 详情页中的 `Update marketplace`
|
||
|
||
手动更新会：
|
||
|
||
1. 调用 `refreshMarketplace()` 刷新指定 marketplace。
|
||
2. 调用 `updatePluginsForMarketplaces()` bump 该 marketplace 下已安装的 plugins。
|
||
3. 清理缓存并刷新 UI 状态。
|
||
|
||
手动更新不依赖该 marketplace 的 `autoUpdate` 标记，也不通过后台 auto-update 的通知回调。它是用户主动操作。
|
||
|
||
自动更新只处理 auto-update enabled marketplaces，并在后台静默执行；失败通常只写 debug log，不阻塞用户。
|
||
|
||
## Plugin 更新细节
|
||
|
||
实际 plugin bump 由 `src/services/plugins/pluginOperations.ts` 的 `updatePluginOp()` 完成：
|
||
|
||
1. 解析 plugin ID。
|
||
2. 从 marketplace 找到 plugin entry。
|
||
3. 从 `installed_plugins.json` 找到对应 scope 和 projectPath 的安装记录。
|
||
4. 对远程 source 下载临时副本；对本地 source 使用 marketplace 中的相对路径。
|
||
5. 调用 `calculatePluginVersion()` 计算新版本。
|
||
6. 如果当前安装已经是新版本，返回 already up to date。
|
||
7. 否则复制到 versioned cache。
|
||
8. 调用 `updateInstallationPathOnDisk()` 写回 `installed_plugins.json`。
|
||
9. 如果旧版本路径不再被任何安装引用，标记为 orphaned。
|
||
|
||
`updateInstallationPathOnDisk()` 只改磁盘文件，并清掉 installed plugins cache；它不会更新当前会话中的 in-memory installed plugins。这个设计保证后台更新不会在运行中替换正在使用的 plugin。
|
||
|
||
## Pending 更新和通知
|
||
|
||
后台 auto-update 成功后：
|
||
|
||
- 如果 REPL 已注册 callback，立即调用 callback。
|
||
- 如果 auto-update 先完成而 REPL hook 尚未注册，会先保存到 `pendingNotification`，注册后补发。
|
||
|
||
UI hook 在 `src/hooks/notifs/usePluginAutoupdateNotification.tsx`：
|
||
|
||
- remote mode 下不显示。
|
||
- 通知内容为 plugin 名称和 `Run /reload-plugins to apply`。
|
||
- 通知优先级为 low，默认 10 秒超时。
|
||
|
||
`getAutoUpdatedPluginNames()` 会通过 `hasPendingUpdates()` 判断磁盘安装记录和内存安装记录是否不同，并返回 pending update 的 plugin 名称。
|
||
|
||
## 关键注意点
|
||
|
||
- Plugin marketplace auto-update 配置默认可见。
|
||
- `DISABLE_AUTOUPDATER=1` 会关闭 plugin auto-update；`FORCE_AUTOUPDATE_PLUGINS=1` 可专门恢复 plugin auto-update。
|
||
- 官方 marketplaces 默认 auto-update，第三方 marketplaces 默认不 auto-update。
|
||
- settings 中 `extraKnownMarketplaces[name].autoUpdate` 优先于 `known_marketplaces.json`。
|
||
- 手动 marketplace update 会同步 bump 已安装 plugins，但不等于开启 auto-update。
|
||
- auto-update 是 disk-only；当前会话需要 `/reload-plugins` 或重启才能应用。
|
||
- `/config` 的 `Auto-update channel` 不决定 plugin 版本来源。
|