#Skill 与 MCP：能力扩展体系

// src/skills/bundledSkills.ts (lines 15-41)
type BundledSkillDefinition = {
  name: string                  // 技能名，如 "commit"
  description: string           // 一行描述
  aliases?: string[]            // 别名
  whenToUse?: string            // 什么时候用（给 AI 看的触发条件）
  argumentHint?: string         // 参数提示，如 "<pr-number>"
  allowedTools?: string[]       // 允许使用的工具
  model?: string                // 模型覆盖
  disableModelInvocation?: bool // 禁止 AI 主动调用（只能用户手动）
  userInvocable?: boolean       // 用户是否可以通过 /xxx 调用
  hooks?: HooksSettings         // 钩子配置
  context?: 'inline' | 'fork'  // 执行方式：内联 or 子 Agent
  agent?: string                // 指定执行 Agent 类型
  files?: Record<string, string>// 附带的参考文件

  // 核心：生成 prompt 内容的函数
  getPromptForCommand: (args: string, context: ToolUseContext)
    => Promise<ContentBlockParam[]>
}

// src/skills/loadSkillsDir.ts (lines 407-550)
function loadSkillsFromSkillsDir(basePath, source) {
  // 1. 扫描目录下的子目录（不是 .md 文件）
  for (const entry of readdir(basePath)) {
    // 2. 在子目录中寻找 SKILL.md
    const skillFile = path.join(basePath, entry, 'SKILL.md')

    // 3. 解析 frontmatter（YAML 头部）
    const { frontmatter, content } = parseFrontmatter(skillFile)

    // 4. 提取元数据字段
    const metadata = parseSkillFrontmatterFields(frontmatter, content)
    // → name, description, allowedTools, model, hooks, ...

    // 5. 创建 Command 对象
    return createSkillCommand({ metadata, content, basePath })
  }
}

// src/skills/loadSkillsDir.ts (lines 344-396)
function getPromptForCommand(args, context) {
  let content = skillMarkdown

  // 替换参数占位符
  content = substituteArguments(content, args)
  // ${ARGUMENTS} → 用户传入的参数

  // 替换技能目录路径
  content = content.replace('${CLAUDE_SKILL_DIR}', skillDir)

  // 替换会话 ID
  content = content.replace('${CLAUDE_SESSION_ID}', sessionId)

  // 执行内嵌 Shell 命令（仅非 MCP 技能）
  if (source !== 'mcp') {
    content = await executeShellCommandsInPrompt(content)
    // !`git status` → 实际执行并替换为输出
  }

  return content
}

// src/tools/SkillTool/SkillTool.ts (lines 432-578)
function checkPermissions(input, context) {
  // 1. 检查 deny 规则（精确匹配 + 前缀匹配）
  //    "commit" → 精确匹配
  //    "review:*" → 匹配 review-pr, review-docs 等

  // 2. 检查 allow 规则

  // 3. 安全属性自动放行
  //    如果技能只有 description/name 没有 hooks/tools → 自动允许

  // 4. 都没匹配 → 弹窗问用户
}

// src/services/mcp/types.ts (lines 179-226)
type MCPServerConnection =
  | ConnectedMCPServer     // 已连接，正常工作
  | FailedMCPServer        // 连接失败
  | NeedsAuthMCPServer     // 需要认证（OAuth）
  | PendingMCPServer       // 连接中 / 重连中
  | DisabledMCPServer      // 已禁用

// src/services/mcp/client.ts (lines 595-677)
// 连接函数使用 memoize，同名服务器只连接一次
const connectToServer = memoize(async (name, serverConfig) => {
  // 根据传输类型创建不同的 Transport
  switch (serverConfig.type) {
    case 'stdio':
      // 启动子进程，通过 stdin/stdout 通信
      transport = new StdioClientTransport({
        command: config.command,
        args: config.args,
        env: config.env,
      })
      break

    case 'sse':
      // 创建 OAuth 认证提供者
      const authProvider = new ClaudeAuthProvider(name, config)
      transport = new SSEClientTransport(url, {
        authProvider,
        requestInit: { headers },
      })
      break

    case 'http':
      transport = new StreamableHTTPClientTransport(url, { headers })
      break

    case 'ws':
      transport = new WebSocketTransport(url)
      break
  }

  // 创建 MCP Client 并连接
  const client = new Client({ name: 'claude-code', version })
  await client.connect(transport)

  return { client, name, type: 'connected', capabilities, cleanup }
})

// src/services/mcp/client.ts (lines 1743-1800)
const fetchToolsForClient = memoizeWithLRU(async (server) => {
  // 1. 通过 MCP 协议请求工具列表
  const result = await server.client.listTools()

  // 2. 为每个工具生成标准化名称
  return result.tools.map(tool => ({
    // 格式: mcp__{服务器名}__{工具名}
    name: `mcp__${normalize(server.name)}__${tool.name}`,
    // 例如: mcp__postgres__query, mcp__slack__send_message

    inputSchema: tool.inputSchema,
    isMcp: true,

    // 调用时路由到 MCP 服务器
    call: (input) => callMCPTool({ server, tool: tool.name, args: input }),
  }))
})

// src/services/mcp/client.ts (lines 3029-3247)
async function callMCPTool({ client, tool, args, signal }) {
  // 每 30 秒记录一次进度日志
  const progressInterval = setInterval(() => {
    log(`MCP tool ${tool} still running...`)
  }, 30_000)

  // 带超时的调用
  const result = await Promise.race([
    client.callTool({ name: tool, arguments: args }, { signal }),
    timeoutPromise(getMcpToolTimeoutMs()),
  ])

  // 转换结果
  return transformMCPResult(result, supportedMimeTypes)
}

// src/services/mcp/client.ts (lines 2033-2107)
const fetchCommandsForClient = memoizeWithLRU(async (server) => {
  const result = await server.client.listPrompts()

  return result.prompts.map(prompt => ({
    // 命名格式和 Tool 一样
    name: `mcp__${normalize(server.name)}__${prompt.name}`,
    type: 'prompt',
    source: 'mcp',
    loadedFrom: 'mcp',
    isMcp: true,

    // 调用时获取 prompt 内容
    getPromptForCommand: async (args) => {
      const result = await server.client.getPrompt({
        name: prompt.name,
        arguments: zipObject(argNames, args.split(' ')),
      })
      return transformResultContent(result.messages)
    },
  }))
})

// src/services/mcp/auth.ts (lines 1376-1450)
class ClaudeAuthProvider implements OAuthClientProvider {
  // 支持的认证特性：
  // - 动态客户端注册（Dynamic Client Registration）
  // - URL 作为 client_id（CIMD 标准）
  // - Token 刷新
  // - 权限提升（scope step-up，处理 403）
  // - Keychain 持久化存储 token
}

// src/services/mcp/useManageMCPConnections.ts
function useManageMCPConnections() {
  // 自动重连（指数退避：1s → 2s → 4s → ... → 30s，最多 5 次）
  // 监听工具列表变化通知 → 刷新工具缓存
  // 监听 prompt 列表变化 → 刷新 Skill 缓存
  // 监听资源列表变化 → 刷新资源缓存

  return {
    toolsByServer,     // 每个服务器提供的工具
    commandsByServer,  // 每个服务器提供的 Skill
    resourcesByServer, // 每个服务器提供的资源
    clients,           // 所有连接
    reconnect,         // 手动重连
    setServerDisabled, // 启用/禁用
  }
}