第19章 · 插件系统
第19章 · 插件系统
19.1 命名空间设计
Claude Code的插件采用{name}@{marketplace}的命名空间设计：
export const BUILTIN_MARKETPLACE_NAME = 'builtin'
// 例如：my-plugin@official-marketplace这种设计借鉴了npm的@scope/package模式，但将"作用域"替换为"市场"概念，允许同名插件在不同市场中共存。
19.2 PluginInstallationManager
services/plugins/PluginInstallationManager.ts实现了后台安装生命周期：
export async function performBackgroundPluginInstallations(
setAppState: SetAppState,
): Promise<void>安装状态追踪：
function updateMarketplaceStatus(
setAppState: SetAppState,
name: string,
status: 'pending' | 'installing' | 'installed' | 'failed',
error?: string,
): void关键架构决策：
- 非阻塞市场克隆（快速Git clone，本地缓存）
- 基于Diff的Reconcile（对比声明的vs已物化的市场）
- 新安装时自动刷新，更新时不自动刷新（由用户选择时机）
- 失败时优雅降级（设置
needsRefresh标志，等待手动/reload-plugins） - 分析日志记录（installed_count, updated_count, failed_count）
19.3 内置插件注册表
plugins/builtinPlugins.ts管理内置插件：
const BUILTIN_PLUGINS: Map<string, BuiltinPluginDefinition> = new Map()
export function registerBuiltinPlugin(def: BuiltinPluginDefinition): void
export function isBuiltinPluginId(pluginId: string): boolean
export function getBuiltinPlugins(): {
enabled: LoadedPlugin[]
disabled: LoadedPlugin[]
}插件启用逻辑：
- 用户设置存储在
settings.enabledPlugins[pluginId] - 默认启用通过
definition.defaultEnabled控制 - 用户偏好覆盖默认值
- 可用性检查通过
isAvailable()函数
19.4 DXT格式：插件打包标准
utils/dxt/定义了Claude Code的插件打包格式（DXT）。
安全验证是DXT处理的核心关注点：
const LIMITS = {
MAX_FILE_SIZE: 512 * 1024 * 1024, // 512MB/文件
MAX_TOTAL_SIZE: 1024 * 1024 * 1024, // 1GB总量
MAX_FILE_COUNT: 100000,
MAX_COMPRESSION_RATIO: 50, // Zip炸弹检测
MIN_COMPRESSION_RATIO: 0.5,
}路径安全：
export function isPathSafe(filePath: string): boolean {
return !containsPathTraversal(filePath) && !isAbsolute(normalized)
}Zip炸弹检测通过压缩比阈值（50:1）实现——如果解压后的大小是压缩大小的50倍以上，视为潜在的Zip炸弹攻击。