pluginLoader.ts` 3302 行 — 插件加载器完整实现¶

重要性：⭐⭐⭐⭐（插件系统的核心——6 种安装源 + 缓存 + 清单 + Hooks） 真实位置：src/utils/plugins/pluginLoader.ts（3302 行）角色：插件从 npm / git / GitHub / 本地 / marketplace / session-only 6 种源安装、缓存、加载、清单解析、Hooks 装载关联：topics/deep-dive-marketplace.md（marketplace）、topics/deep-dive-manage-plugins.md（管理 UI）

1. 文件全景¶

pluginLoader.ts (3302 行)
│
├── 行 1-220   ：imports + 缓存路径工具
│   ├── getPluginCachePath (行 126)
│   ├── getVersionedCachePathIn / getVersionedCachePath / getVersionedZipCachePath
│   └── probeSeedCache / probeSeedCacheAnyVersion (行 195-220)
│
├── 行 220-470 ：本地复制 / 缓存
│   ├── getLegacyCachePath
│   ├── resolvePluginPath (行 266)
│   ├── copyDir (行 293)
│   └── copyPluginToVersionedCache (行 365, ~100 行)
│
├── 行 470-870 ：6 种安装源
│   ├── validateGitUrl (行 470)
│   ├── installFromNpm (行 492, ~40 行)
│   ├── gitClone (行 534, ~110 行)
│   ├── installFromGit (行 645)
│   ├── installFromGitHub (行 662)
│   ├── resolveGitSubdirUrl
│   ├── installFromGitSubdir (行 718, ~140 行)
│   ├── installFromLocal (行 856)
│   └── generateTemporaryCacheNameForPlugin
│
├── 行 911-1147：cachePlugin (~230 行) — 完整缓存逻辑
│
├── 行 1147-1348：清单 + Hooks 加载
│   ├── loadPluginManifest (行 1147, ~80 行)
│   ├── loadPluginHooks (行 1224, ~40 行)
│   └── validatePluginPaths (行 1265, ~80 行)
│
├── 行 1348-1776：**createPluginFromPath (行 1348, ~430 行)** — 核心：从路径构造 plugin
│
├── 行 1776-1854：settings 解析
│   ├── PluginSettingsSchema (lazy)
│   ├── parsePluginSettings
│   ├── loadPluginSettings
│   └── mergeHooksSettings
│
├── 行 1888-2928：**loadPluginsFromMarketplaces (行 1888, ~210 行)** — 从 marketplace 加载
│   ├── loadPluginFromMarketplaceEntryCacheOnly
│   ├── loadPluginFromMarketplaceEntry
│   └── finishLoadingPluginFromPath (行 2420, ~500 行)
│
├── 行 2928-3009：loadSessionOnlyPlugins (行 2928, ~80 行) — session 内插件
│
├── 行 3009-3096：mergePluginSources (行 3009, ~85 行) — 合并多源
│
├── 行 3096-3155：**loadAllPlugins (memoize)** + loadAllPluginsCacheOnly
│
├── 行 3155-3225：assemblePluginLoadResult
│
└── 行 3225-3302：clearPluginCache + cachePluginSettings + isRecord

2. 缓存路径架构¶

export function getPluginCachePath(): string { ... }
export function getVersionedCachePathIn(...): string { ... }
export function getVersionedCachePath(pluginName: string, version: string): string { ... }
export function getVersionedZipCachePath(...): string { ... }

4 级缓存路径： 1. getPluginCachePath —— 根目录 2. getVersionedCachePathIn —— 自定义根的版本化路径 3. getVersionedCachePath(name, version) —— <root>/<name>@<version> 4. getVersionedZipCachePath(...) —— 远程 zip 缓存

版本化设计：每个插件每个版本独立目录——避免版本冲突。

3. 6 种安装源¶

3.1 `installFromNpm`（行 492）¶

export async function installFromNpm(name: string, ...): Promise<...> {
  // npm install 风格
}

~40 行——npm pack + 解压 + 缓存。

3.2 `gitClone`（行 534）¶

export async function gitClone(url: string, dest: string, ...): Promise<...> {
  // ~110 行
}

核心 git clone——git clone --depth 1 + checkout ref。

3.3 `installFromGit`（行 645）+ `installFromGitHub`（行 662）+ `installFromGitSubdir`（行 718）¶

async function installFromGit(url, ...) { ... }
async function installFromGitHub(url, ...) { ... }
async function installFromGitSubdir(url, ...) { ... }  // ~140 行

3 种 git 变体： - fromGit —— 任意 git URL - fromGitHub —— GitHub 优化（可能用 tarball API 加速） - fromGitSubdir —— monorepo 子目录

resolveGitSubdirUrl（行 686）——解析 git+https://...#subdir=path 语法。

3.4 `installFromLocal`（行 856）¶

async function installFromLocal(path: string, ...): Promise<...> {
  // 本地路径
}

本地路径——直接 copyDir 到缓存。

3.5 validateGitUrl¶

function validateGitUrl(url: string): string {
  // 校验 + 标准化 git URL
}

安全——防止恶意 URL（SSRF、命令注入）。

4. `cachePlugin` — 230 行（行 911-1147）¶

export async function cachePlugin(source: PluginSource, ...): Promise<CachedPlugin> {
  // 行 911
  // 1. 分发到 installFromXxx
  // 2. 解析 manifest
  // 3. 校验 hooks 路径
  // 4. 返回 CachedPlugin
}

核心 cache 逻辑： 1. 选择源（npm/git/github/local/zip） 2. 下载 + 解压到 <cache>/<name>@<version> 3. 解析 manifest（package.json + plugin.json） 4. 校验 hooks 路径（防止 ../../ 跳出） 5. 返回 CachedPlugin

5. `loadPluginManifest` — 80 行（行 1147）¶

export async function loadPluginManifest(pluginPath: string): Promise<PluginManifest> {
  // 行 1147
  // 解析 plugin.json
}

Manifest 字段： - name, version, description - author - hooks (PreToolUse, PostToolUse, SessionStart, ...) - commands - agents - mcpServers

6. `loadPluginHooks` + `validatePluginPaths`（行 1224-1348）¶

async function loadPluginHooks(pluginPath: string, manifest: PluginManifest): Promise<HooksConfig> {
  // 行 1224
  // 解析 manifest.hooks → 实际脚本路径
}

async function validatePluginPaths(pluginPath: string, manifest: PluginManifest): Promise<void> {
  // 行 1265
  // 安全：确保所有 hooks 路径在 plugin 目录内
}

安全： - 防止 hooks 引用 ../../etc/passwd 等 - 防止 .. 跳出插件目录

7. `createPluginFromPath` — 430 行核心（行 1348-1776）¶

export async function createPluginFromPath(pluginPath: string, ...): Promise<LoadedPlugin> {
  // 行 1348
  // 1. 加载 manifest
  // 2. 加载 hooks
  // 3. 校验路径
  // 4. 加载 commands
  // 5. 加载 agents
  // 6. 加载 MCP servers
  // 7. 返回 LoadedPlugin
}

最核心的"从路径构造插件"——所有逻辑都在这里。

430 行反映插件系统的复杂度。

8. Settings 解析（行 1776-1854）¶

const PluginSettingsSchema = lazySchema(() => ...);
function parsePluginSettings(raw: unknown): PluginSettings { ... }
async function loadPluginSettings(pluginName: string, scope: ...): Promise<...> { ... }
function mergeHooksSettings(...): HooksConfig { ... }

4 个 functions： - PluginSettingsSchema —— Zod schema（lazy） - parsePluginSettings —— 解析 - loadPluginSettings —— 从磁盘读 - mergeHooksSettings —— 合并多源 settings

9. `loadPluginsFromMarketplaces` — 210 行（行 1888-2098）¶

async function loadPluginsFromMarketplaces({...}) {
  // 行 1888
  // 1. 遍历 marketplaces
  // 2. 对每个 marketplace 加载 plugins
  // 3. 合并结果
}

Marketplace 加载——参见 marketplaceManager.ts。

10. `finishLoadingPluginFromPath` — 500 行（行 2420-2928）¶

async function finishLoadingPluginFromPath(...): Promise<LoadedPlugin> {
  // 行 2420
  // 1. 校验 manifest
  // 2. 解析 hooks
  // 3. 校验路径
  // 4. 处理 settings
  // 5. 构造 LoadedPlugin
}

500 行——是从 cache 路径到 LoadedPlugin 的"完成最后一步"。

为什么这么大：包含所有边界情况处理（settings 缺失、hooks 失败、agent 解析、MCP 服务器校验等）。

11. `loadSessionOnlyPlugins` — 80 行（行 2928-3009）¶

async function loadSessionOnlyPlugins(...): Promise<...> {
  // 行 2928
  // session-only 插件（--plugin-dir）
}

--plugin-dir CLI flag 指定的插件——仅本次 session。

12. `mergePluginSources` — 85 行（行 3009-3096）¶

export function mergePluginSources(sources: PluginSource[]): PluginLoadResult {
  // 行 3009
  // 合并 marketplace + session-only + settings 插件
}

合并多个源——按优先级去重。

13. `loadAllPlugins` (memoize) + `loadAllPluginsCacheOnly` (memoize)¶

export const loadAllPlugins = memoize(async (): Promise<PluginLoadResult> => {
  // 行 3096
});

export const loadAllPluginsCacheOnly = memoize(
  async (): Promise<PluginLoadResult> => { ... }
);

2 个 memoize 入口： - loadAllPlugins —— 完整加载（sync + async） - loadAllPluginsCacheOnly —— 只读缓存

memoize —— 同一进程内只跑一次。

14. `assemblePluginLoadResult`¶

async function assemblePluginLoadResult(...): Promise<PluginLoadResult> {
  // 行 3155
  // 组装最终结果
}

组装——把 marketplace + session-only + settings 合并成最终 PluginLoadResult。

15. `clearPluginCache` (行 3225)¶

export function clearPluginCache(reason?: string): void {
  // 清缓存
}

手动清缓存——/plugin refresh 或 --plugin-dir 变化时调。

接受 reason——logging。

16. `cachePluginSettings` (行 3281)¶

export function cachePluginSettings(plugins: LoadedPlugin[]): void {
  // 缓存 settings
}

缓存 plugin settings——加速下次启动。

17. 关键设计模式¶

17.1 6 种安装源统一抽象¶

所有安装源（npm / git / GitHub / git-subdir / local / session-only）都返回 CachedPlugin ——统一接口。

17.2 版本化缓存路径¶

<cache>/<name>@<version>/ —— 同名不同版本独立缓存。

17.3 安全路径校验¶

validatePluginPaths —— 防止 hooks 引用 ../ 跳出插件目录。

17.4 两层 memoize¶

loadAllPlugins (memoize) + loadAllPluginsCacheOnly (memoize) —— 避免重复加载。

17.5 lazy schema¶

const PluginSettingsSchema = lazySchema(() => ...);

lazy 加载——schema 验证不是关键路径，按需加载。

17.6 路径验证 + 错误恢复¶

manifest 缺失 → 跳过 hooks 路径非法 → 警告但继续 agent 解析失败 → 跳过该 agent

"宽容失败"——一个插件错不全盘崩溃。

17.7 settings 多源合并¶

function mergeHooksSettings(...): HooksConfig { ... }

合并 user settings + project settings + plugin defaults。

18. 复杂度分析¶

维度	数字
总行数	3302
安装源	6 种
主要函数	30+
缓存层	3 级（plugin / versioned / zip）
安全校验	validateGitUrl + validatePluginPaths
加载入口	2 个 memoize

19. 性能特征¶

19.1 启动加载¶

缓存命中：< 50ms（只读 manifest）
缓存未命中：~500ms-2s（从 npm/git 拉）
loadAllPluginsCacheOnly：~10-20ms

19.2 内存占用¶

每个 LoadedPlugin 约 10-100KB（manifest + hooks + commands + agents）。 100 个插件 ≈ 1-10MB。

19.3 优化手段¶

memoize 双层
版本化缓存
lazy schema
cachePluginSettings

20. 与其他文件的关系¶

pluginLoader.ts
  ├──→ npm registry
  ├──→ git
  ├──→ GitHub API
  ├──→ 本地文件系统
  ├──→ .claude/settings.json
  ├──→ marketplace.json
  └──→ plugin.json (manifest)

pluginLoader 是"插件的总线"——其他 plugin 文件（marketplaceManager、ManagePlugins、pluginCliCommands）都委托它。

21. 关键洞察¶

21.1 6 种源 = "所有可能的分发渠道"¶

npm（包）/ git（任意）/ GitHub（优化）/ subdir（monorepo）/ local（开发）/ session-only（一次性）。

21.2 路径安全校验是"反恶意插件"基础¶

防止 plugins 通过 ../ 读 /etc/passwd 或写 ~/.ssh/authorized_keys。

21.3 两层 memoize 节省大量 I/O¶

不缓存会每次启动都重新拉所有 plugins。

21.4 lazy schema 节省启动时间¶

zod schema 不需要立即加载——按需。

21.5 settings 多源合并是"配置灵活性"¶

user + project + plugin defaults 三方合并。

21.6 "宽容失败"是商业产品哲学¶

一个插件坏了不全盘崩溃——降级而不是拒绝启动。

21.7 缓存版本化避免冲突¶

<name>@<version> —— 同名不同版本独立。

22. 阅读建议¶

看 6 种安装源（行 470-870）—— 完整分发
看 cachePlugin（行 911）—— 缓存逻辑
看 createPluginFromPath（行 1348）—— 核心
看 finishLoadingPluginFromPath（行 2420）—— 最后一步
看 loadAllPlugins (memoize)（行 3096）—— 入口

23. 与其他深度拆解的关系¶

文件	关系
`marketplaceManager.ts`	marketplace 加载（被 loadPluginsFromMarketplaces 调用）
`ManagePlugins.tsx`	UI 委托 pluginLoader
`pluginCliCommands.ts`	CLI 子命令（`/plugin install`）委托
`bundled/index.ts`	内置 plugins（不走 cache）

24. 阅读清单¶

✅ 看 6 种安装源（行 470-870）
✅ 看 cachePlugin（行 911）
✅ 看 createPluginFromPath（行 1348）
✅ 看 finishLoadingPluginFromPath（行 2420）
✅ 看 loadAllPlugins memoize（行 3096）
📌 对照 topics/deep-dive-marketplace.md 看 marketplace
📌 对照 topics/deep-dive-manage-plugins.md 看 UI

25. 练习任务¶

数安装源（grep）—— 6 种
数 memoize（grep）—— 2 层
数 validateXxx（grep）—— 安全校验
画插件加载流程 —— 6 种源 → cache → loadAllPlugins → LoadedPlugin
手写迷你 pluginLoader（~100 行）—— npm install + 缓存 + 加载
思考：插件系统的"权限隔离"应该在哪一层做？

Deep Dive ｜ src/utils/plugins/pluginLoader.ts 3302 行 — 插件加载器完整实现¶