Claude Code Skill Runtime 深度解析：可复用 AI 工作流引擎的架构与实现

// src/skills/loadSkillsDir.ts — createSkillCommand 核心
async getPromptForCommand(args, toolUseContext) {
  // Step 1: Base directory 前缀注入
  let finalContent = baseDir
    ? `Base directory for this skill: ${baseDir}\n\n${markdownContent}`
    : markdownContent

  // Step 2: 命名参数替换 ($arg_name → 实际值)
  finalContent = substituteArguments(finalContent, args, true, argumentNames)

  // Step 3: ${CLAUDE_SKILL_DIR} 变量替换 (Windows 路径归一化)
  if (baseDir) {
    const skillDir = process.platform === 'win32'
      ? baseDir.replace(/\\/g, '/')  // Windows: 反斜杠 → 正斜杠
      : baseDir
    finalContent = finalContent.replace(/\${CLAUDE_SKILL_DIR}/g, skillDir)
  }

  // Step 4: ${CLAUDE_SESSION_ID} 替换
  finalContent = finalContent.replace(/\${CLAUDE_SESSION_ID}/g, getSessionId())

  // Step 5: Shell 命令内联执行 (!`command` 语法)
  // 安全关键: MCP 技能 (loadedFrom === 'mcp') 禁止此步骤
  if (loadedFrom !== 'mcp') {
    finalContent = await executeShellCommandsInPrompt(
      finalContent,
      {
        ...toolUseContext,
        getAppState() {
          // 注入 allowedTools 到权限上下文，使 shell 命令继承技能权限
          const appState = toolUseContext.getAppState()
          return {
            ...appState,
            toolPermissionContext: {
              ...appState.toolPermissionContext,
              alwaysAllowRules: {
                ...appState.toolPermissionContext.alwaysAllowRules,
                command: allowedTools,  // ← 技能声明的工具权限
              },
            },
          }
        },
      },
      `/${skillName}`,
      shell,  // 可选的自定义 shell (从 frontmatter 解析)
    )
  }

  return [{ type: 'text', text: finalContent }]
}

// src/skills/bundledSkills.ts
export function registerBundledSkill(definition: BundledSkillDefinition): void {
  if (files && Object.keys(files).length > 0) {
    skillRoot = getBundledSkillExtractDir(definition.name)
    // 关键: memo 的是 Promise 本身, 不是 result
    let extractionPromise: Promise<string | null> | undefined
    const inner = definition.getPromptForCommand
    getPromptForCommand = async (args, ctx) => {
      extractionPromise ??= extractBundledSkillFiles(definition.name, files)
      const extractedDir = await extractionPromise
      const blocks = await inner(args, ctx)
      if (extractedDir === null) return blocks  // 提取失败 → 优雅降级
      return prependBaseDir(blocks, extractedDir)
    }
  }
  // ...
}

// 安全层级 1: per-process nonce 目录 (getBundledSkillsRoot)
// 即使攻击者通过 inotify 获知父目录, 也无法预测子目录名

// 安全层级 2: 路径遍历防护
function resolveSkillFilePath(baseDir: string, relPath: string): string {
  const normalized = normalize(relPath)
  if (isAbsolute(normalized) ||
      normalized.split(pathSep).includes('..') ||
      normalized.split('/').includes('..'))  // 兼容 Windows 路径分隔符
    throw new Error(`bundled skill file path escapes skill dir: ${relPath}`)
  return join(baseDir, normalized)
}

// 安全层级 3: 防符号链接写入
const SAFE_WRITE_FLAGS = process.platform === 'win32'
  ? 'wx'  // Windows: libuv 不支持 numeric O_EXCL
  : fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | O_NOFOLLOW

async function safeWriteFile(p: string, content: string): Promise<void> {
  const fh = await open(p, SAFE_WRITE_FLAGS, 0o600)  // owner-only
  try { await fh.writeFile(content, 'utf8') }
  finally { await fh.close() }
}

// 安全层级 4: 目录权限
await mkdir(parent, { recursive: true, mode: 0o700 })  // owner-only

const [managed, user, projectNested, additionalNested, legacy] = await Promise.all([
  // 1. 管理策略目录 (除非 CLAUDE_CODE_DISABLE_POLICY_SKILLS)
  loadSkillsFromSkillsDir(managedSkillsDir, 'policySettings'),
  // 2. 用户目录 (除非 !isSettingSourceEnabled('userSettings') || locked)
  loadSkillsFromSkillsDir(userSkillsDir, 'userSettings'),
  // 3. 项目目录 (逐级上行: cwd/.claude/skills, ../claude/skills, ...)
  Promise.all(projectDirs.map(dir => loadSkillsFromSkillsDir(dir, 'projectSettings'))),
  // 4. --add-dir 附加目录
  Promise.all(additionalDirs.map(dir => loadSkillsFromSkillsDir(...))),
  // 5. 旧式 /commands/ 目录
  loadSkillsFromCommandsDir(cwd),
])

// Phase 1: 并行预计算所有文件的 canonical path
const fileIds = await Promise.all(
  allSkillsWithPaths.map(({ skill, filePath }) =>
    skill.type === 'prompt' ? getFileIdentity(filePath) : Promise.resolve(null),
  ),
)

// Phase 2: 同步去重 (first-wins 优先级)
const seenFileIds = new Map<string, SettingSource>()
for (let i = 0; i < allSkillsWithPaths.length; i++) {
  const fileId = fileIds[i]
  if (fileId === null || fileId === undefined) {
    deduplicatedSkills.push(skill)  // 无法解析的文件不去重
    continue
  }
  const existingSource = seenFileIds.get(fileId)
  if (existingSource !== undefined) {
    logForDebugging(`Skipping duplicate skill '${skill.name}' from ${skill.source}`)
    continue
  }
  seenFileIds.set(fileId, skill.source)
  deduplicatedSkills.push(skill)
}

const conditionalSkills = new Map<string, Command>()       // 待激活池
const activatedConditionalSkillNames = new Set<string>()     // 已激活名 (跨 cache clear)
const dynamicSkills = new Map<string, Command>()             // 活跃池

export function activateConditionalSkillsForPaths(filePaths, cwd): string[] {
  for (const [name, skill] of conditionalSkills) {
    const skillIgnore = ignore().add(skill.paths)  // gitignore 风格匹配
    for (const filePath of filePaths) {
      const relativePath = isAbsolute(filePath) ? relative(cwd, filePath) : filePath
      // 防御: 空路径、../逃逸、跨驱动器绝对路径
      if (!relativePath || relativePath.startsWith('..') || isAbsolute(relativePath)) continue
      if (skillIgnore.ignores(relativePath)) {
        dynamicSkills.set(name, skill)         // 移入活跃池
        conditionalSkills.delete(name)          // 从待激活池移除
        activatedConditionalSkillNames.add(name) // 持久记录 (cache clear 不影响)
        break
      }
    }
  }
  skillsLoaded.emit()  // Signal 通知
}

// src/skills/mcpSkillBuilders.ts — 依赖图叶子节点 (只导入类型)
let builders: MCPSkillBuilders | null = null

export function registerMCPSkillBuilders(b: MCPSkillBuilders): void { builders = b }
export function getMCPSkillBuilders(): MCPSkillBuilders {
  if (!builders) throw new Error('MCP skill builders not registered')
  return builders
}

// loadSkillsDir.ts 文件末尾的顶层副作用 (模块初始化时执行)
registerMCPSkillBuilders({ createSkillCommand, parseSkillFrontmatterFields })

async function getAllCommands(context: ToolUseContext): Promise<Command[]> {
  // 只包含 loadedFrom === 'mcp' 的 MCP skills, 不包含 plain MCP prompts
  // 修复: 此前模型可以通过猜测 mcp__server__prompt 名称调用 MCP prompts
  const mcpSkills = context.getAppState().mcp.commands.filter(
    cmd => cmd.type === 'prompt' && cmd.loadedFrom === 'mcp',
  )
  if (mcpSkills.length === 0) return getCommands(getProjectRoot())
  const localCommands = await getCommands(getProjectRoot())
  return uniqBy([...localCommands, ...mcpSkills], 'name')  // 本地优先
}

return {
  data: { success: true, commandName, allowedTools, model },
  newMessages,       // 技能 prompt 注入主对话
  contextModifier(ctx) {
    let modifiedContext = ctx

    // Layer 1: 工具权限合并
    if (allowedTools.length > 0) {
      const previousGetAppState = modifiedContext.getAppState  // 捕获前一层
      modifiedContext = {
        ...modifiedContext,
        getAppState() {
          const appState = previousGetAppState()  // 链式调用, 不是 ctx.getAppState
          return {
            ...appState,
            toolPermissionContext: {
              ...appState.toolPermissionContext,
              alwaysAllowRules: {
                ...appState.toolPermissionContext.alwaysAllowRules,
                command: [
                  ...new Set([  // Set 去重
                    ...(appState.toolPermissionContext.alwaysAllowRules.command || []),
                    ...allowedTools,
                  ]),
                ],
              },
            },
          }
        },
      }
    }

    // Layer 2: 模型覆盖 (保留 [1m] 后缀防止降低 context window)
    if (model) {
      modifiedContext = {
        ...modifiedContext,
        options: {
          ...modifiedContext.options,
          mainLoopModel: resolveSkillModelOverride(model, ctx.options.mainLoopModel),
        },
      }
    }

    // Layer 3: Effort level 覆盖
    if (effort !== undefined) {
      const previousGetAppState = modifiedContext.getAppState  // 再次捕获
      modifiedContext = {
        ...modifiedContext,
        getAppState() {
          return { ...previousGetAppState(), effortValue: effort }
        },
      }
    }

    return modifiedContext
  },
}

async function executeForkedSkill(command, commandName, args, context, ...) {
  const agentId = createAgentId()

  // prepareForkedCommandContext: 获取 prompt + 工具权限 + agent 定义
  const { modifiedGetAppState, baseAgent, promptMessages, skillContent } =
    await prepareForkedCommandContext(command, args || '', context)

  // 合并 effort 到 agent definition
  const agentDefinition = command.effort !== undefined
    ? { ...baseAgent, effort: command.effort }
    : baseAgent

  const agentMessages: Message[] = []
  try {
    // runAgent 返回 async iterator
    for await (const message of runAgent({
      agentDefinition,
      promptMessages,
      toolUseContext: { ...context, getAppState: modifiedGetAppState },
      isAsync: false,           // 同步执行, 阻塞主对话
      querySource: 'agent:custom',
      model: command.model as ModelAlias | undefined,
      override: { agentId },    // 注入自定义 agentId
    })) {
      agentMessages.push(message)
      // 上报进度 (tool_use / tool_result)
      if ((message.type === 'assistant' || message.type === 'user') && onProgress) {
        // ... progress reporting
      }
    }

    const resultText = extractResultText(agentMessages, 'Skill execution completed')
    agentMessages.length = 0   // 显式释放消息内存

    return { data: { success: true, commandName, status: 'forked', agentId, result: resultText } }
  } finally {
    clearInvokedSkillsForAgent(agentId)  // 释放 compaction 状态
  }
}

const SAFE_SKILL_PROPERTIES = new Set([
  // PromptCommand properties
  'type', 'progressMessage', 'contentLength', 'argNames', 'model',
  'effort', 'source', 'pluginInfo', 'disableNonInteractive',
  'skillRoot', 'context', 'agent', 'getPromptForCommand', 'frontmatterKeys',
  // CommandBase properties
  'name', 'description', 'hasUserSpecifiedDescription', 'isEnabled',
  'isHidden', 'aliases', 'isMcp', 'argumentHint', 'whenToUse',
  'paths', 'version', 'disableModelInvocation', 'userInvocable',
  'loadedFrom', 'immediate', 'userFacingName',
])

function skillHasOnlySafeProperties(command: Command): boolean {
  for (const key of Object.keys(command)) {
    if (SAFE_SKILL_PROPERTIES.has(key)) continue
    const value = (command as Record<string, unknown>)[key]
    // 忽略: undefined, null, 空数组, 空对象
    if (value === undefined || value === null) continue
    if (Array.isArray(value) && value.length === 0) continue
    if (typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length === 0) continue
    return false  // 有非安全属性且有值 → 需要权限
  }
  return true
}

// src/utils/hooks/skillImprovement.ts
function createSkillImprovementHook() {
  let lastAnalyzedCount = 0   // 上次分析时的 user 消息数
  let lastAnalyzedIndex = 0   // 上次分析到的消息索引

  const config: ApiQueryHookConfig<SkillUpdate[]> = {
    async shouldRun(context) {
      if (context.querySource !== 'repl_main_thread') return false
      if (!findProjectSkill()) return false  // 只分析项目级技能
      const userCount = count(context.messages, m => m.type === 'user')
      if (userCount - lastAnalyzedCount < 5) return false  // 每 5 条才触发
      lastAnalyzedCount = userCount
      return true
    },

    buildMessages(context) {
      const projectSkill = findProjectSkill()!
      const newMessages = context.messages.slice(lastAnalyzedIndex)  // 增量分析
      lastAnalyzedIndex = context.messages.length
      return [createUserMessage({
        content: `...<skill_definition>${projectSkill.content}</skill_definition>
        <recent_messages>${formatRecentMessages(newMessages)}</recent_messages>...`
      })]
    },

    parseResponse(content) {
      const updatesStr = extractTag(content, 'updates')
      return updatesStr ? jsonParse(updatesStr) : []  // 解析失败 → 空数组
    },

    getModel: getSmallFastModel,  // 使用小模型降低成本
  }
  return createApiQueryHook(config)
}

export async function applySkillImprovement(skillName: string, updates: SkillUpdate[]) {
  const filePath = join(getCwd(), '.claude', 'skills', skillName, 'SKILL.md')
  const currentContent = await fs.readFile(filePath, 'utf-8')

  const response = await queryModelWithoutStreaming({
    messages: [createUserMessage({ content: `...` })],
    systemPrompt: asSystemPrompt(['You edit skill definition files...']),
    thinkingConfig: { type: 'disabled' },  // 省 token
    tools: [],                              // 不需要工具
    signal: createAbortController().signal,  // 非阻塞
    options: {
      model: getSmallFastModel(),
      temperatureOverride: 0,               // 确定性输出
      querySource: 'skill_improvement_apply',
    },
  })

  const updatedContent = extractTag(responseText, 'updated_file')
  if (updatedContent) await fs.writeFile(filePath, updatedContent, 'utf-8')
}

// src/utils/hooks/registerSkillHooks.ts
export function registerSkillHooks(setAppState, sessionId, hooks, skillName, skillRoot?) {
  for (const eventName of HOOK_EVENTS) {
    const matchers = hooks[eventName]
    if (!matchers) continue
    for (const matcher of matchers) {
      for (const hook of matcher.hooks) {
        // once: true → 成功后自动 removeSessionHook
        const onHookSuccess = hook.once
          ? () => removeSessionHook(setAppState, sessionId, eventName, hook)
          : undefined
        addSessionHook(setAppState, sessionId, eventName,
          matcher.matcher || '', hook, onHookSuccess, skillRoot)
      }
    }
  }
}

// src/bootstrap/state.ts
// 键格式: `${agentId ?? ''}:${skillName}`  — 防止跨 agent 覆盖
invokedSkills: Map<string, {
  skillName: string
  skillPath: string     // 格式: `${source}:${name}` (如 "projectSettings:my-skill")
  content: string       // 已经过完整展开的 prompt 内容
  invokedAt: number
  agentId: string | null  // null = 主线程
}>

// src/utils/processUserInput/processSlashCommand.tsx
async function getMessagesForPromptSlashCommand(command, args, context, ...) {
  // 1. 获取展开后的 prompt 内容
  const result = await command.getPromptForCommand(args, context)

  // 2. 注册 skill hooks (受策略控制)
  const hooksAllowed = !isRestrictedToPluginOnly('hooks') || isSourceAdminTrusted(command.source)
  if (command.hooks && hooksAllowed) {
    registerSkillHooks(context.setAppState, sessionId, command.hooks, command.name, command.skillRoot)
  }

  // 3. 注册到 compaction 恢复系统
  const skillPath = command.source ? `${command.source}:${command.name}` : command.name
  const skillContent = result.filter(b => b.type === 'text').map(b => b.text).join('\n\n')
  addInvokedSkill(command.name, skillPath, skillContent, getAgentContext()?.agentId ?? null)

  // 4. 提取附件 (@-mentions, MCP resources) — skipSkillDiscovery 避免 AKI 延迟
  const attachmentMessages = await toArray(
    getAttachmentMessages(/* ... */, { skipSkillDiscovery: true })
  )

  // 5. 构建消息列表
  return {
    messages: [
      createUserMessage({ content: metadata, uuid }),          // 元数据
      createUserMessage({ content: mainContent, isMeta: true }), // 技能内容
      ...attachmentMessages,                                    // 附件
      createAttachmentMessage({ type: 'command_permissions', allowedTools, model }), // 权限
    ],
    shouldQuery: true,
    allowedTools, model, effort, command,
  }
}

// src/utils/skills/skillChangeDetector.ts
const USE_POLLING = typeof Bun !== 'undefined'

const RELOAD_DEBOUNCE_MS = 300

function scheduleReload(changedPath: string): void {
  pendingChangedPaths.add(changedPath)       // 累积路径
  if (reloadTimer) clearTimeout(reloadTimer) // 重置定时器
  reloadTimer = setTimeout(async () => {
    reloadTimer = null
    const paths = [...pendingChangedPaths]
    pendingChangedPaths.clear()

    // 保护 1: ConfigChange hook 可阻止重载
    const results = await executeConfigChangeHooks('skills', paths[0]!)
    if (hasBlockingResult(results)) return

    // 保护 2: 级联清除三层缓存
    clearSkillCaches()       // getSkillDirCommands.cache + conditionalSkills
    clearCommandsCache()     // getCommands memoization
    resetSentSkillNames()    // 触发技能列表重发

    // 保护 3: Signal 通知 UI (React hook 订阅)
    skillsChanged.emit()
  }, RELOAD_DEBOUNCE_MS)
}

export const SKILL_BUDGET_CONTEXT_PERCENT = 0.01  // 上下文窗口的 1%
export const CHARS_PER_TOKEN = 4
export const MAX_LISTING_DESC_CHARS = 250

export function formatCommandsWithinBudget(commands, contextWindowTokens?) {
  const budget = getCharBudget(contextWindowTokens)
  const fullTotal = commands.reduce((sum, cmd) => sum + stringWidth(formatDesc(cmd)), 0)
  if (fullTotal <= budget) return fullEntries.join('\n')  // 全描述

  // 分区: bundled (永不截断) vs rest
  const bundledChars = /* bundled 技能占用 */
  const remainingBudget = budget - bundledChars
  const maxDescLen = Math.floor(remainingBudget / restCommands.length)

  if (maxDescLen < 20) return /* 极端: rest 只显示名字 */
  return /* 截断 rest 描述到 maxDescLen */
}