// src/services/mcp/types.ts
export const TransportSchema = z.enum([
  'stdio',   // 标准输入输出
  'sse',     // Server-Sent Events
  'sse-ide', // IDE 专用 SSE
  'http',    // HTTP Streamable
  'ws',      // WebSocket
  'ws-ide',  // IDE 专用 WebSocket
  'sdk',     // SDK 模式
])

// src/services/mcp/client.ts:595-961
export const connectToServer = memoize(
  async (name, serverRef, serverStats) => {
    // 1. 根据传输类型创建 Transport
    let transport
    if (serverRef.type === 'sse') {
      transport = new SSEClientTransport(new URL(serverRef.url), options)
    } else if (serverRef.type === 'http') {
      transport = new StreamableHTTPClientTransport(new URL(serverRef.url), options)
    } else if (serverRef.type === 'ws') {
      transport = new WebSocketTransport(wsClient)
    } else if (serverRef.type === 'stdio') {
      transport = new StdioClientTransport({ command, args, env })
    }
    
    // 2. 创建 MCP Client
    const client = new Client({
      name: 'claude-code',
      version: MACRO.VERSION,
    }, {
      capabilities: { roots: {}, elicitation: {} },
    })
    
    // 3. 设置请求处理器
    client.setRequestHandler(ListRootsRequestSchema, async () => ({
      roots: [{ uri: `file://${getOriginalCwd()}` }],
    }))
    
    // 4. 连接并设置错误处理
    await client.connect(transport)
  }
)

// src/entrypoints/mcp.ts:35-57
export async function startMCPServer(cwd: string, debug: boolean, verbose: boolean) {
  const server = new Server({
    name: 'claude/tengu',
    version: MACRO.VERSION,
  }, {
    capabilities: { tools: {} },
  })

  // 暴露工具列表
  server.setRequestHandler(ListToolsRequestSchema, async () => {
    const tools = getTools(toolPermissionContext)
    return {
      tools: tools.map(tool => ({
        name: tool.name,
        description: await tool.prompt(...),
        inputSchema: zodToJsonSchema(tool.inputSchema),
      })),
    }
  })

  // 处理工具调用
  server.setRequestHandler(CallToolRequestSchema, async ({ params }) => {
    const tool = findToolByName(tools, params.name)
    const result = await tool.call(params.arguments, toolUseContext, ...)
    return { content: [{ type: 'text', text: jsonStringify(result) }] }
  })

  const transport = new StdioServerTransport()
  await server.connect(transport)
}

// src/services/mcp/client.ts:619-641
if (serverRef.type === 'sse') {
  const authProvider = new ClaudeAuthProvider(name, serverRef)
  const transportOptions: SSEClientTransportOptions = {
    authProvider,
    fetch: wrapFetchWithTimeout(
      wrapFetchWithStepUpDetection(createFetchWithInit(), authProvider)
    ),
  }
}

// src/services/mcp/mcpStringUtils.ts
export function buildMcpToolName(serverName: string, toolName: string): string {
  return `mcp__${normalizeNameForMCP(serverName)}__${normalizeNameForMCP(toolName)}`
}

// src/utils/plugins/schemas.ts:884-898
export const PluginManifestSchema = lazySchema(() =>
  z.object({
    ...PluginManifestMetadataSchema().shape,
    ...PluginManifestHooksSchema().partial().shape,      // 钩子扩展
    ...PluginManifestCommandsSchema().partial().shape,   // 命令扩展
    ...PluginManifestAgentsSchema().partial().shape,    // Agent 扩展
    ...PluginManifestSkillsSchema().partial().shape,    // Skill 扩展
    ...PluginManifestOutputStylesSchema().partial().shape, // 输出样式扩展
    ...PluginManifestMcpServerSchema().partial().shape, // MCP 服务器
    ...PluginManifestLspServerSchema().partial().shape, // LSP 服务器
  }),
)

// src/types/plugin.ts:48-70
export type LoadedPlugin = {
  name: string
  manifest: PluginManifest
  path: string
  source: string
  repository: string
  enabled?: boolean
  isBuiltin?: boolean
  sha?: string  // Git commit SHA for version pinning
  commandsPath?: string
  agentsPath?: string
  skillsPath?: string
  hooksConfig?: HooksSettings
  mcpServers?: Record<string, McpServerConfig>
  lspServers?: Record<string, LspServerConfig>
  settings?: Record<string, unknown>
}

// src/utils/plugins/schemas.ts:1062-1161
export const PluginSourceSchema = z.union([
  RelativePath(),  // 本地相对路径
  
  // 远程来源
  z.object({ source: 'npm', package: NpmPackageNameSchema(), version?: string }),
  z.object({ source: 'pip', package: string, version?: string }),  // Python
  z.object({ source: 'github', repo: string, ref?: string, sha?: string }),
  z.object({ source: 'url', url: string, ref?: string, sha?: string }),
  z.object({ source: 'git-subdir', url: string, path: string, ... }),
])

// src/plugins/builtinPlugins.ts
export type BuiltinPluginDefinition = {
  name: string
  description: string
  version?: string
  skills?: BundledSkillDefinition[]
  hooks?: HooksSettings
  mcpServers?: Record<string, McpServerConfig>
  isAvailable?: () => boolean
  defaultEnabled?: boolean
}

// src/utils/plugins/schemas.ts:1293-1326
export const PluginMarketplaceSchema = lazySchema(() =>
  z.object({
    name: MarketplaceNameSchema(),
    owner: PluginAuthorSchema(),
    plugins: z.array(PluginMarketplaceEntrySchema()),
    forceRemoveDeletedPlugins?: boolean,
    metadata?: { pluginRoot?: string, version?: string },
    allowCrossMarketplaceDependenciesOn?: string[],
  }),
)

// src/bridge/bridgeMain.ts:141-151
export async function runBridgeLoop(
  config: BridgeConfig,
  environmentId: string,
  environmentSecret: string,
  api: BridgeApiClient,
  spawner: SessionSpawner,
  logger: BridgeLogger,
  signal: AbortSignal,
  backoffConfig: BackoffConfig = DEFAULT_BACKOFF,
) {
  const activeSessions = new Map<string, SessionHandle>()
  
  while (!loopSignal.aborted) {
    // 1. 轮询工作
    const work = await api.pollForWork(environmentId, environmentSecret, ...)
    
    // 2. 处理工作类型
    switch (work.data.type) {
      case 'healthcheck':
        await ackWork()
        break
      case 'session':
        // 启动新会话
        const handle = spawner.spawn({ sessionId, sdkUrl, accessToken, ... })
        activeSessions.set(sessionId, handle)
        break
    }
    
    // 3. 心跳保活
    await heartbeatActiveWorkItems()
  }
}

// src/bridge/bridgeMain.ts:442-591
function onSessionDone(sessionId, startTime, handle) {
  return (status: SessionDoneStatus) => {
    // 清理会话
    activeSessions.delete(sessionId)
    
    // 通知服务器工作完成
    stopWorkWithRetry(api, environmentId, workId, ...)
    
    // 清理关联的工作树
    removeAgentWorktree(wt.worktreePath, wt.worktreeBranch, ...)
    
    // 多会话模式: 存档会话; 单会话模式: 关闭环境
    if (config.spawnMode !== 'single-session') {
      api.archiveSession(compatId)
    } else {
      controller.abort()  // 关闭桥接循环
    }
  }
}

// src/bridge/bridgeMain.ts:976-1015
if (spawnModeAtDecision === 'worktree' && ...) {
  const wt = await createAgentWorktree(`bridge-${safeFilenameId(sessionId)}`)
  sessionWorktrees.set(sessionId, {
    worktreePath: wt.worktreePath,
    worktreeBranch: wt.worktreeBranch,
    gitRoot: wt.gitRoot,
  })
  sessionDir = wt.worktreePath
}

// src/bridge/bridgeMain.ts:279-313
const tokenRefresh = createTokenRefreshScheduler({
  getAccessToken,
  onRefresh: (sessionId, oauthToken) => {
    const handle = activeSessions.get(sessionId)
    if (v2Sessions.has(sessionId)) {
      // v2: 调用 reconnectSession 触发服务器重新分发
      api.reconnectSession(environmentId, sessionId)
    } else {
      // v1: 直接更新 access token
      handle.updateAccessToken(oauthToken)
    }
  },
})

// src/bridge/types.ts
export type BridgeConfig = {
  apiBaseUrl: string
  sessionIngressUrl: string
  spawnMode: 'single-session' | 'worktree' | 'same-dir'
  maxSessions: number
  sessionTimeoutMs?: number
  debugFile?: string
}

// src/Tool.ts
export abstract class Tool {
  name: string
  description: string
  inputSchema: z.ZodType
  outputSchema?: z.ZodType
  
  abstract prompt(params: ToolParams): string | Promise<string>
  abstract call(params: unknown, context: ToolUseContext, ...): Promise<ToolResult>
  validateInput?(params: unknown, context: ToolUseContext): ValidationResult
  isEnabled?(): boolean
}

// src/tools/MCPTool/MCPTool.ts
export class MCPTool extends Tool {
  constructor(
    private serverName: string,
    private toolName: string,
    private client: Client,
  ) {
    super({
      name: buildMcpToolName(serverName, toolName),
      description: tool.description,
      inputSchema: tool.inputSchema,
    })
  }

  async call(params: unknown, context: ToolUseContext) {
    const result = await this.client.callTool({
      name: this.toolName,
      arguments: params,
    })
    return this.formatResult(result)
  }
}

// src/utils/permissions/permissions.ts
export function hasPermissionsToUseTool(
  tool: Tool,
  context: ToolUseContext,
): Promise<PermissionResult> {
  // 检查工具是否需要权限
  // 检查用户是否已授权
  // 返回允许/拒绝/询问结果
}

// src/services/tools/toolExecution.ts
export async function executeTool(
  tool: Tool,
  params: unknown,
  context: ToolUseContext,
): Promise<ToolResult> {
  // 1. 权限检查
  const permission = await hasPermissionsToUseTool(tool, context)
  if (permission.behavior === 'deny') {
    return { success: false, reason: 'Permission denied' }
  }

  // 2. 输入验证
  if (tool.validateInput) {
    const validation = await tool.validateInput(params, context)
    if (!validation.result) {
      throw new Error(validation.message)
    }
  }

  // 3. 执行工具
  const result = await tool.call(params, context, hasPermissionsToUseTool)

  // 4. 触发后置钩子
  runPostToolUseHooks(tool.name, result)

  return result
}

// src/services/plugins/pluginOperations.ts:321-418
export async function installPluginOp(
  plugin: string,
  scope: InstallableScope = 'user',
): Promise<PluginOperationResult> {
  // 1. 解析插件标识符
  const { name: pluginName, marketplace: marketplaceName } = 
    parsePluginIdentifier(plugin)

  // 2. 搜索市场获取插件信息
  let foundPlugin: PluginMarketplaceEntry | undefined
  if (marketplaceName) {
    pluginInfo = await getPluginById(plugin)
  } else {
    // 在所有已知市场中搜索
    const marketplaces = await loadKnownMarketplacesConfig()
    for (const [mktName, mktConfig] of Object.entries(marketplaces)) {
      const marketplace = await getMarketplace(mktName)
      const pluginEntry = marketplace.plugins.find(p => p.name === pluginName)
      // ...
    }
  }

  // 3. 执行安装
  const result = await installResolvedPlugin({
    pluginId,
    entry: foundPlugin,
    scope,
    marketplaceInstallLocation,
  })

  // 4. 写入配置 (设置优先原则)
  updateSettingsForSource(settingSource, {
    enabledPlugins: { [pluginId]: true },
  })

  // 5. 缓存插件
  copyPluginToVersionedCache(sourcePath, pluginId, version)
}

// src/utils/plugins/pluginLoader.ts:1348-1587
export async function createPluginFromPath(
  pluginPath: string,
  source: string,
  enabled: boolean,
  fallbackName: string,
): Promise<{ plugin: LoadedPlugin; errors: PluginError[] }> {
  // 1. 加载插件清单
  const manifestPath = join(pluginPath, '.claude-plugin', 'plugin.json')
  const manifest = await loadPluginManifest(manifestPath, fallbackName, source)

  // 2. 创建基础插件对象
  const plugin: LoadedPlugin = {
    name: manifest.name,
    manifest,
    path: pluginPath,
    source,
    repository: source,
    enabled,
  }

  // 3. 自动检测组件目录
  const [commandsDirExists, agentsDirExists, skillsDirExists, outputStylesDirExists] =
    await Promise.all([
      pathExists(join(pluginPath, 'commands')),
      pathExists(join(pluginPath, 'agents')),
      pathExists(join(pluginPath, 'skills')),
      pathExists(join(pluginPath, 'output-styles')),
    ])

  // 4. 注册组件路径
  if (commandsDirExists) plugin.commandsPath = commandsPath
  if (agentsDirExists) plugin.agentsPath = agentsPath
  if (skillsDirExists) plugin.skillsPath = skillsPath
  if (outputStylesDirExists) plugin.outputStylesPath = outputStylesPath

  // 5. 加载钩子配置
  if (manifest.hooks) {
    plugin.hooksConfig = await loadPluginHooks(hooksConfigPath, plugin.name)
  }

  return { plugin, errors }
}

// src/utils/plugins/pluginLoader.ts:139-177
export function getVersionedCachePath(
  pluginId: string,
  version: string,
): string {
  return join(
    getPluginsDirectory(),
    'cache',
    sanitizedMarketplace,
    sanitizedPlugin,
    sanitizedVersion,
  )
}

// 缓存目录格式:
// ~/.claude/plugins/cache/{marketplace}/{plugin}/{version}/

// src/services/plugins/pluginOperations.ts:71-75
export const VALID_INSTALLABLE_SCOPES = ['user', 'project', 'local'] as const

// 优先级: local > project > user

// src/utils/plugins/loadPluginHooks.ts:28-86
function convertPluginHooksToMatchers(
  plugin: LoadedPlugin,
): Record<HookEvent, PluginHookMatcher[]> {
  const pluginMatchers: Record<HookEvent, PluginHookMatcher[]> = {
    PreToolUse: [],
    PostToolUse: [],
    PostToolUseFailure: [],
    PermissionDenied: [],
    Notification: [],
    UserPromptSubmit: [],
    SessionStart: [],
    SessionEnd: [],
    Stop: [],
    // ... 更多事件
  }

  if (!plugin.hooksConfig) return pluginMatchers

  for (const [event, matchers] of Object.entries(plugin.hooksConfig)) {
    const hookEvent = event as HookEvent
    for (const matcher of matchers) {
      pluginMatchers[hookEvent].push({
        matcher: matcher.matcher,
        hooks: matcher.hooks,
        pluginRoot: plugin.path,
        pluginName: plugin.name,
      })
    }
  }

  return pluginMatchers
}

// src/types/hooks.ts
export type HookEvent = 
  | 'PreToolUse'
  | 'PostToolUse'
  | 'PostToolUseFailure'
  | 'PermissionDenied'
  | 'Notification'
  | 'UserPromptSubmit'
  | 'SessionStart'
  | 'SessionEnd'
  | 'Stop'
  | 'StopFailure'
  | 'SubagentStart'
  | 'SubagentStop'
  | 'PreCompact'
  | 'PostCompact'
  | 'PermissionRequest'
  | 'Setup'
  | 'TeammateIdle'
  | 'TaskCreated'
  | 'TaskCompleted'
  | 'Elicitation'
  | 'ElicitationResult'
  | 'ConfigChange'
  | 'WorktreeCreate'
  | 'WorktreeRemove'
  | 'InstructionsLoaded'
  | 'CwdChanged'
  | 'FileChanged'

// src/utils/plugins/dependencyResolver.ts
export function findReverseDependents(
  pluginId: string,
  plugins: LoadedPlugin[],
): string[] {
  // 查找依赖该插件的其他插件
}

export function verifyAndDemote(
  pluginId: string,
  plugins: LoadedPlugin[],
): void {
  // 验证依赖链，禁用无法满足依赖的插件
}

// src/utils/plugins/loadPluginHooks.ts:255-286
export function setupPluginHookHotReload(): void {
  settingsChangeDetector.subscribe(source => {
    if (source === 'policySettings') {
      // 检测插件相关设置的变更
      const newSnapshot = getPluginAffectingSettingsSnapshot()
      if (newSnapshot !== lastPluginSettingsSnapshot) {
        lastPluginSettingsSnapshot = newSnapshot
        // 清除缓存并重新加载
        clearPluginCache(...)
        clearPluginHookCache()
        void loadPluginHooks()
      }
    }
  })
}