CC源码剖析 #11 · 插件系统：Plugin 架构与生命周期

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

// 内置插件 vs Skills：
// - Skills: 单个 Markdown 文件
// - 内置插件: 多组件（skills + hooks + MCP servers）

// 插件 ID 格式：{name}@builtin
export function isBuiltinPluginId(pluginId: string): boolean {
  return pluginId.endsWith('@builtin')
}

// 注册内置插件
export function registerBuiltinPlugin(
  definition: BuiltinPluginDefinition,
): void {
  BUILTIN_PLUGINS.set(definition.name, definition)
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

// 从插件市场安装
// 插件市场：plugins.claude.com

interface MarketplacePlugin {
  id: string           // name@marketplace
  name: string
  version: string
  description: string
  skills: SkillDefinition[]
  hooks: HookDefinition[]
  mcpServers?: McpServerConfig[]
}

1
2

// 项目本地的 .claude/plugins/ 目录
// 对项目成员可见

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

export interface LoadedPlugin {
  name: string
  manifest: PluginManifest
  path: string
  skills: Command[]
  hooks: HookDefinition[]
  mcpServers?: McpServerConfig[]
  agents?: AgentDefinition[]
}

// 加载插件
loadAllPluginsCacheOnly(): Promise<LoadedPlugin[]>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# plugin.json
{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "My Claude Code plugin",
  "skills": ["skills/*.md"],
  "hooks": ["hooks/*.ts"],
  "mcpServers": ["mcp.json"],
  "agents": ["agents/*.md"]
}

1
2
3
4

// 插件代码在独立作用域执行
// 防止插件之间的命名冲突

// 插件只能访问显式导出的内容

1
2
3
4
5
6
7

// 插件安装目录
const PLUGIN_DIRS = {
  user: '~/.claude/plugins/',        // 用户插件
  project: '.claude/plugins/',        // 项目插件
  managed: '{managedPath}/plugins/',  // 企业托管
  bundled: '{installPath}/bundled/'    // 内置插件
}

1
2
3
4
5
6
7

export async function getPluginCommands(): Promise<Command[]> {
  const plugins = await loadAllPluginsCacheOnly()
  return plugins.flatMap(p => p.skills)
}

// Skill 文件格式与标准 Skills 相同
// 通过 frontmatter 定义参数和行为

1
2
3
4
5
6
7
8
9

// 插件可能依赖其他插件
// 依赖解析确保加载顺序正确

interface PluginDependency {
  name: string
  version: string  // 支持 semver 范围
}

resolveDependencies(plugins: LoadedPlugin[]): LoadedPlugin[]

1
2
3
4
5
6
7
8

type HookType =
  | 'sessionStart'      // 会话开始
  | 'sessionEnd'        // 会话结束
  | 'turnEnd'          // 回合结束
  | 'preToolCall'      // 工具调用前
  | 'postToolCall'      // 工具调用后
  | 'preAgentCall'     // Agent 调用前
  | 'postAgentCall'     // Agent 调用后

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

interface HookDefinition {
  type: HookType
  name: string
  handler: (context: HookContext) => Promise<void | HookResult>
}

interface HookContext {
  sessionId: string
  messages: Message[]
  tools: Tool[]
  // ...
}

1
2
3
4
5
6

// 插件可以提供 MCP 服务器配置
// 加载后自动连接

interface PluginMcpConfig {
  servers: McpServerConfig[]
}

1
2
3
4

// 1. 解析插件的 mcp.json
// 2. 验证 MCP 配置
// 3. 连接到 MCP 服务器
// 4. 注册 MCP 工具

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

// 支持 semver 语义化版本
// 自动更新检查

interface PluginVersion {
  major: number
  minor: number
  patch: number
  prerelease?: string
}

// 版本兼容性检查
isCompatible(current: Version, required: Version): boolean

1
2
3

// 检查插件更新
// 自动下载新版本
// 回滚机制

1
2
3
4
5
6

// 插件代码在受限环境运行
// 不能直接访问系统资源

// 文件访问：只允许插件目录内
// 网络访问：只允许配置的端点
// 敏感API：需要明确授权

1
2
3
4
5
6
7
8

// 企业可以配置插件策略
// 允许/禁止特定插件

interface PluginPolicy {
  allowedPlugins: string[]
  blockedPlugins: string[]
  requireApproval: string[]
}

1
2
3

// 静态分析插件代码
// 检测可疑模式
// 隔离执行