插件与技能系统

职责概述

解决的问题：用户想给 CC 加新能力，但不想写代码。同时，开发者想分发自己做的 CC 扩展。需要一个完整的插件生态：用户能发现、安装、管理插件；开发者能打包、发布、更新插件；CC 能安全地加载和运行插件。

应用场景：① 用户从市场安装一个"代码审查"插件，CC 就会自动在每次提交前做 review ② 团队在 .claude/commands/ 目录放几个 Markdown 文件，团队成员就能用 /review、/deploy 等自定义命令 ③ 插件开发者打包技能+MCP Server+Hooks 为一个完整的分发单元 ④ 文件变化时自动热加载更新后的插件。

一句话理解：就像 VS Code 的扩展系统——有市场、有安装、有配置、有热加载，用户和开发者各取所需。

架构设计

核心数据流

插件加载流程

技能发现流程

关键类型与接口

插件定义类型

// skills/bundledSkills.ts:15-41
export type BundledSkillDefinition = {
  name: string
  description: string
  allowedTools?: string[]
  argumentHint?: string
  whenToUse?: string
  model?: string
  disableModelInvocation?: boolean
  userInvocable?: boolean
  defaultEnabled?: boolean
  isEnabled?: () => boolean
  // 钩子、上下文、Agent 定义等
  hooks?: HooksSettings
  context?: string
  agent?: AgentDefinition
  // 参考文件（提取到磁盘供模型读取）
  files?: Record<string, string>
  // 自定义提示生成
  getPromptForCommand?: (args: string, toolUseContext: ToolUseContext)
    => Promise<ContentBlockParam[]>
}

内建插件定义

// plugins/builtinPlugins.ts — 内建插件注册表
const BUILTIN_PLUGINS: Map<string, BuiltinPluginDefinition> = new Map()

export function registerBuiltinPlugin(definition: BuiltinPluginDefinition): void {
  BUILTIN_PLUGINS.set(definition.name, definition)
}

// 获取启用的内建插件，转换为 LoadedPlugin 对象
export function getBuiltinPlugins(): {
  enabled: LoadedPlugin[]
  disabled: LoadedPlugin[]
}

技能 Frontmatter 解析

// skills/loadSkillsDir.ts:185-265
export function parseSkillFrontmatterFields(
  frontmatter: FrontmatterData,
  markdownContent: string,
  resolvedName: string,
  descriptionFallbackLabel: 'Skill' | 'Custom command' = 'Skill',
): {
  name: string
  description: string
  allowedTools: string[]
  argumentHint?: string
  whenToUse?: string
  model?: string
  // ... 更多字段
}

依赖解析结果

// utils/plugins/dependencyResolver.ts:58-67
export type ResolutionResult =
  | { type: 'ok'; id: PluginId }
  | { type: 'missing'; id: PluginId; requiredBy: PluginId }
  | { type: 'cross-marketplace'; id: PluginId; requiredBy: PluginId }

// DFS 遍历传递依赖闭包
export async function resolveDependencyClosure(
  rootId: PluginId,
  lookup: (id: PluginId) => Promise<DependencyLookupResult | null>,
  alreadyEnabled: ReadonlySet<PluginId>,
  allowedCrossMarketplaces: string[],
): Promise<ResolutionResult[]>

设计模式与亮点

◈ 可视化处理拓扑图

插件与技能系统是一个多源发现、加载验证、统一注册的三阶段管线。插件从 session/marketplace/built-in 三个来源汇聚，经过 manifest 验证和路径安全检查后，将其 skills、hooks、MCP 配置注册到 Claude Code 运行时。所有技能最终统一为 Command 对象，模型调用时无感知来源差异。

Phase 2 — 安装分发、Manifest 验证与加载

Phase 3 — 组件注册（Hooks / Skills / Commands）

Phase 4 — 工具合并与权限应用

⇉ 核心处理流程详解

插件与技能系统是将外部能力注入 Claude Code 的核心机制。插件（Plugin）是包含 skills、hooks 和 MCP 配置的完整包；技能（Skill/Command）是可被模型调用的 prompt 模板。以下是从插件发现到技能激活的完整处理链路：

★ 设计精华

1. 统一 Command 抽象与来源多态

Bundled skill、目录 skill、插件 skill 三者使用同一个 Command 类型，但 source 字段不同。这使得下游系统（工具合并、权限检查、UI 渲染）可以用统一接口处理所有技能，只在需要区分时检查 source。createSkillCommand()（loadSkillsDir.ts:270）是统一构建入口，无论来源如何，产出的对象都有相同的 getPromptForCommand() 方法签名。

export function createSkillCommand({
  name, description, source, filePath, content,
  frontmatter: { allowedTools, model, ... }
}): Command {
  return {
    type: 'prompt',
    name,
    source,  // 'bundled' | 'user' | 'project' | 'plugin'
    userFacingName: () => name,
    getPromptForCommand: async (args, ctx) => {
      // 读取 .md 文件内容，支持参数替换
      // Bundled skill 额外提取引用文件
      return contentBlocks
    }
  }
}

2. 版本化缓存的多级查找

插件安装后通过 getVersionedCachePath()（pluginLoader.ts:172）缓存到版本化目录（plugins/cache/v1/{pluginId}/{version}/）。加载时通过 resolvePluginPath()（pluginLoader.ts:266）按优先级查找：先查主缓存目录，再查 seed 目录（预装插件），最后查 legacy 非版本化缓存。这种三级查找确保了：(1) 版本升级时新旧缓存共存不冲突；(2) 新安装可以使用预装的 seed 缓存加速；(3) 老版本的非版本化缓存仍可被找到。

export async function resolvePluginPath(pluginId, version) {
  // 1. 版本化主缓存
  const versionedPath = getVersionedCachePath(pluginId, version)
  if (await exists(versionedPath)) return versionedPath
  // 2. Seed 缓存（预装）
  const seedPath = await probeSeedCache(pluginId, version)
  if (seedPath) return seedPath
  // 3. Legacy 非版本化缓存
  const legacyPath = getLegacyCachePath(pluginId)
  if (await exists(legacyPath)) return legacyPath
}

3. 条件技能的文件路径触发

普通技能在启动时一次性加载，而条件技能（带 paths frontmatter 的技能）在运行时按需激活。activateConditionalSkillsForPaths()（loadSkillsDir.ts:997）接收当前被访问的文件路径列表，通过 discoverSkillDirsForPaths()（loadSkillsDir.ts:861）从文件路径向上遍历目录树，发现匹配的 .claude/skills/ 目录。这种"文件访问 → 目录遍历 → 技能激活"的延迟绑定实现了上下文感知：只有当用户实际操作相关文件时，对应的技能才被注入模型上下文。

4. 插件安全的三层防御

插件安全通过验证层、策略层和运行时层三重保障。验证层（validatePlugin.ts）检查路径穿越攻击——插件的组件文件路径（如 hooks.json、skill .md 文件）不能通过 ../ 引用插件目录外的文件。策略层（pluginPolicy.ts）允许企业管理员限制允许的插件来源。运行时层通过 source 字段区分信任等级——bundled 技能（source: 'bundled'）跳过权限确认，插件技能（source: 'plugin'）必须经过用户批准。

◈ Agent 实践借鉴 — 客服 Agent 插件/扩展设计

场景映射：客服 agent 在插件扩展上的真实问题

不同业务线的客服需要不同的技能，技能需要由业务方自己开发维护。典型痛点包括：

• 不同业务线不同技能：电商客服有"查物流"、"查订单"、"处理退款"；金融客服有"查账单"、"处理挂失"、"利率计算"；教育客服有"查课表"、"预约试听"、"退课"。硬编码所有技能不现实。
• 业务方想自己开发：物流部门最了解物流查询的细节（快递公司编码、轨迹节点含义），他们想自己开发"查物流"技能，不想每次都提需求给 AI 团队。
• 技能需要声明权限："查订单"技能需要 CRM 读取权限和 ERP 读取权限；"处理退款"技能需要支付网关写入权限。不同技能的权限差异很大，不能一刀切。
• 上线新技能不能影响老技能：金融客服上线"利率计算"技能，不能导致电商客服的"查物流"技能出问题。技能之间必须隔离。

借鉴 CC + 客服改造

1. 技能清单（Skill Manifest）定义（借鉴 CC plugin.json）

CC 的 plugin.json 声明插件提供的 skills/agents/hooks。客服场景的技能清单声明 name、description、permissions、handler：

// 借鉴 CC 的 plugin.json → 客服场景的技能清单
interface SkillManifest {
  name: string                    // 技能唯一标识，如 "query_logistics"
  version: string                 // 版本号，如 "1.2.0"
  description: string             // 技能描述，如 "查询物流轨迹和预计到达时间"
  businessLine: string            // 所属业务线，如 "ecommerce" | "finance" | "education"
  triggerPatterns: string[]       // 触发模式，如 ["查物流", "物流查询", "快递到哪了"]
  permissions: SkillPermission[]  // 声明所需权限
  inputSchema: {                  // 参数 schema
    type: 'object',
    properties: {
      orderNo: { type: 'string', description: '订单号' },
      expressCompany: { type: 'string', description: '快递公司（可选）' },
    },
    required: ['orderNo'],
  }
  handler: SkillHandler           // 技能处理函数
}

interface SkillPermission {
  system: string                  // 外部系统，如 "crm" | "erp" | "payment"
  access: 'read' | 'write'        // 权限级别
  scope: string                   // 权限范围，如 "order:*" | "customer:phone"
}

// 示例：物流查询技能的清单
const queryLogisticsSkill: SkillManifest = {
  name: 'query_logistics',
  version: '1.2.0',
  description: '查询物流轨迹和预计到达时间',
  businessLine: 'ecommerce',
  triggerPatterns: ['查物流', '物流查询', '快递到哪了', '我的包裹到哪了'],
  permissions: [
    { system: 'erp', access: 'read', scope: 'order:logistics' },
    { system: 'logistics', access: 'read', scope: 'tracking:*' },
  ],
  inputSchema: {
    type: 'object',
    properties: {
      orderNo: { type: 'string', description: '订单号' },
    },
    required: ['orderNo'],
  },
  handler: async (params) => { /* ... */ },
}

2. 三层加载：内置 → 企业 → 第三方（借鉴 CC 三层扩展）

CC 的 Bundled → 目录 → 插件三层加载，对应客服场景的：内置技能 → 企业自定义技能 → 第三方技能：

// 借鉴 CC 的三层技能加载 → 客服场景的三层技能体系
type SkillSource = 'builtin' | 'enterprise' | 'third_party'

// 统一技能接口——借鉴 CC 的 Command 抽象
interface CustomerServiceSkill {
  name: string
  source: SkillSource           // 仅用于权限分流
  manifest: SkillManifest
  execute(params: any, context: SkillContext): Promise<SkillResult>
}

// 三层加载——优先级从高到低，同名技能高优先级覆盖低优先级
async function loadAllSkills(): Promise<Map<string, CustomerServiceSkill>> {
  const skillRegistry = new Map<string, CustomerServiceSkill>()

  // Layer 1: 内置技能（最高信任，代码审计过）
  // 查订单、查物流、退款处理等核心技能
  const builtinSkills = await loadBuiltinSkills()
  for (const skill of builtinSkills) {
    skillRegistry.set(skill.name, { ...skill, source: 'builtin' })
  }

  // Layer 2: 企业自定义技能（业务方开发，内部分发）
  // 从企业技能仓库加载，如 "利率计算"、"预约试听"
  const enterpriseSkills = await loadEnterpriseSkills()
  for (const skill of enterpriseSkills) {
    skillRegistry.set(skill.name, { ...skill, source: 'enterprise' })
  }

  // Layer 3: 第三方技能（最低信任，需额外权限确认）
  // 从第三方市场加载，如 "某 SaaS 工单系统集成"
  const thirdPartySkills = await loadThirdPartySkills()
  for (const skill of thirdPartySkills) {
    // 同名不覆盖（内置/企业优先级更高）
    if (!skillRegistry.has(skill.name)) {
      skillRegistry.set(skill.name, { ...skill, source: 'third_party' })
    }
  }

  return skillRegistry
}

// 按业务线过滤——电商客服只看到电商技能
function filterSkillsByBusinessLine(
  registry: Map<string, CustomerServiceSkill>,
  businessLine: string,
): CustomerServiceSkill[] {
  return Array.from(registry.values()).filter(
    skill => skill.manifest.businessLine === businessLine
           || skill.manifest.businessLine === 'common'  // 通用技能
  )
}

3. 权限声明 + 运行时检查（借鉴 CC source 字段权限分流）

CC 用 source 字段区分 bundled（默认信任）和 plugin（需权限确认）。客服场景按技能来源和权限声明做运行时检查：

// 借鉴 CC 的 source 字段权限分流 → 客服场景的权限检查
async function executeSkillWithPermissionCheck(
  skill: CustomerServiceSkill,
  params: any,
  context: SkillContext,
): Promise<SkillResult> {
  // 1. 按 source 信任级别分流
  if (skill.source === 'third_party') {
    // 第三方技能：必须确认用户授权
    const approved = await confirmUserApproval(skill.manifest)
    if (!approved) {
      return { success: false, error: '用户未授权第三方技能执行' }
    }
  }
  // builtin 和 enterprise 技能：跳过用户确认（已通过内部审计）

  // 2. 运行时权限检查——技能声明了哪些权限，必须全部满足
  for (const perm of skill.manifest.permissions) {
    const hasPermission = await checkSystemPermission(
      context.agentId,
      perm.system,
      perm.access,
      perm.scope,
    )
    if (!hasPermission) {
      return {
        success: false,
        error: `技能 ${skill.name} 需要 ${perm.system} 的 ${perm.access}(${perm.scope}) 权限，当前 agent 无此权限`,
      }
    }
  }

  // 3. 执行技能
  try {
    const result = await skill.execute(params, context)
    return result
  } catch (error) {
    logError(`技能 ${skill.name} 执行失败`, error)
    return { success: false, error: `技能执行异常: ${error.message}` }
  }
}

4. 技能隔离：单个技能加载失败不影响其他（借鉴 CC 错误隔离）

// 借鉴 CC 的 errors 数组收集模式 → 技能加载隔离
interface SkillLoadResult {
  loaded: CustomerServiceSkill[]
  failed: SkillLoadError[]
}

interface SkillLoadError {
  skillName: string
  source: SkillSource
  error: string
}

async function loadSkillsSafely(
  manifests: SkillManifest[],
): Promise<SkillLoadResult> {
  const loaded: CustomerServiceSkill[] = []
  const failed: SkillLoadError[] = []

  // 并行加载，每个技能独立 try-catch
  await Promise.allSettled(
    manifests.map(async (manifest) => {
      try {
        // 验证清单格式
        validateManifest(manifest)
        // 验证权限声明完整性
        validatePermissions(manifest.permissions)
        // 加载并注册技能
        const skill = await compileSkill(manifest)
        // 健康检查：确保依赖的外部系统可达
        await healthCheckSkill(skill)
        loaded.push(skill)
      } catch (error) {
        // 单个技能失败不影响其他技能
        failed.push({
          skillName: manifest.name,
          source: manifest.businessLine as SkillSource,
          error: error.message,
        })
        logWarning(`技能 ${manifest.name} 加载失败: ${error.message}`)
        // 不 throw！继续加载其他技能
      }
    })
  )

  logInfo(`技能加载完成: ${loaded.length} 成功, ${failed.length} 失败`)
  return { loaded, failed }
}

// 借鉴 CC 的 verifyAndDemote：依赖缺失时降级而非报错
function handleSkillDependencyFailure(
  skill: CustomerServiceSkill,
  missingSystems: string[],
): void {
  logWarning(`技能 ${skill.name} 依赖的系统 ${missingSystems.join(', ')} 不可达，技能已降级为只读模式`)
  // 不删除技能，而是降级为只读（可以查看配置但不能执行）
  skill.execute = async () => ({
    success: false,
    error: `依赖系统不可用: ${missingSystems.join(', ')}，请联系运维`,
  })
}

落地清单

代码索引