claude-code with OpenAI mode fix

2026-06-18 14:25:51 +00:00 · 2026-04-04 01:21:00 +08:00
commit c9f95fc34d
3050 changed files with 557030 additions and 0 deletions
--- a/docs/extensibility/custom-agents.mdx
+++ b/docs/extensibility/custom-agents.mdx
@@ -0,0 +1,211 @@
+---
+title: "自定义 Agent - 从 Markdown 到运行时的完整链路"
+description: "揭秘 Claude Code 自定义 Agent 完整链路：Agent 定义的 Markdown 数据模型、三种加载来源、工具过滤策略和与 AgentTool 的联动机制。"
+keywords: ["自定义 Agent", "Agent 定义", "Markdown Agent", "Agent 配置", "角色定制"]
+---
+
+{/* 本章目标：揭示 Agent 定义的完整数据模型、加载发现机制、工具过滤和与 AgentTool 的联动 */}
+
+## Agent 定义的三种来源
+
+Claude Code 的 Agent 不仅仅来自用户自定义——系统有三类来源，按优先级合并：
+
+| 来源 | 位置 | 优先级 |
+|------|------|--------|
+| **Built-in** | `src/tools/AgentTool/built-in/` 硬编码 | 最低（可被覆盖） |
+| **Plugin** | 通过插件系统注册 | 中 |
+| **User/Project/Policy** | `.claude/agents/*.md` 或 settings.json | 最高 |
+
+合并逻辑在 `getActiveAgentsFromList()` 中：按 `agentType` 去重，后者覆盖前者。这意味着你可以在 `.claude/agents/` 中放一个 `Explore.md` 来完全替换内置的 Explore Agent。
+
+## Markdown Agent 文件的完整格式
+
+```markdown
+---
+# === 必需字段 ===
+name: "reviewer"                    # Agent 标识（agentType）
+description: "Code review specialist, read-only analysis"
+
+# === 工具控制 ===
+tools: "Read,Glob,Grep,Bash"        # 允许的工具列表（逗号分隔）
+disallowedTools: "Write,Edit"       # 显式禁止的工具
+
+# === 模型配置 ===
+model: "haiku"                      # 指定模型（或 "inherit" 继承主线程）
+effort: "high"                      # 推理努力程度：low/medium/high 或整数
+
+# === 行为控制 ===
+maxTurns: 10                        # 最大 agentic 轮次
+permissionMode: "plan"              # 权限模式：plan/bypassPermissions 等
+background: true                    # 始终作为后台任务运行
+initialPrompt: "/search TODO"       # 首轮用户消息前缀（支持斜杠命令）
+
+# === 隔离与持久化 ===
+isolation: "worktree"               # 在独立 git worktree 中运行
+memory: "project"                   # 持久记忆范围：user/project/local
+
+# === MCP 服务器 ===
+mcpServers:
+  - "slack"                         # 引用已配置的 MCP 服务器
+  - database:                       # 内联定义
+      command: "npx"
+      args: ["mcp-db"]
+
+# === Hooks ===
+hooks:
+  PreToolUse:
+    - command: "audit-log.sh"
+      timeout: 5000
+
+# === Skills ===
+skills: "code-review,security-review"  # 预加载的 skills（逗号分隔）
+
+# === 显示 ===
+color: "blue"                       # 终端中的 Agent 颜色标识
+---
+
+你是代码审查专家。你的职责是...
+
+（正文内容 = system prompt）
+```
+
+### 字段解析细节
+
+- **`tools`**：通过 `parseAgentToolsFromFrontmatter()` 解析，支持逗号分隔字符串或数组
+- **`model: "inherit"`**：使用主线程的模型（区分大小写，只有小写 "inherit" 有效）
+- **`memory`**：启用后自动注入 `Write`/`Edit`/`Read` 工具（即使 `tools` 未包含），并在 system prompt 末尾追加 memory 指令
+- **`isolation: "remote"`**：仅在 Anthropic 内部可用（`USER_TYPE === 'ant'`），外部构建只支持 `worktree`
+- **`background`**：`true` 使 Agent 始终在后台运行，主线程不等待结果
+
+## 加载与发现机制
+
+`getAgentDefinitionsWithOverrides()`（被 `memoize` 缓存）执行完整的发现流程：
+
+```
+1. 加载 Markdown 文件
+   ├── loadMarkdownFilesForSubdir('agents', cwd)
+   │   ├── ~/.claude/agents/*.md  （用户级，source = 'userSettings'）
+   │   ├── .claude/agents/*.md    （项目级，source = 'projectSettings'）
+   │   └── managed/policy sources （策略级，source = 'policySettings'）
+   │
+   └── 每个 .md 文件：
+       ├── 解析 YAML frontmatter
+       ├── 正文作为 system prompt
+       ├── 校验必需字段（name, description）
+       ├── 静默跳过无 frontmatter 的 .md 文件（可能是参考文档）
+       └── 解析失败 → 记录到 failedFiles，不阻塞其他 Agent
+
+2. 并行加载 Plugin Agents
+   └── loadPluginAgents() → memoized
+
+3. 初始化 Memory Snapshots（如果 AGENT_MEMORY_SNAPSHOT 启用）
+   └── initializeAgentMemorySnapshots()
+
+4. 合并 Built-in + Plugin + Custom
+   └── getActiveAgentsFromList() → 按 agentType 去重，后者覆盖前者
+
+5. 分配颜色
+   └── setAgentColor(agentType, color) → 终端 UI 中区分不同 Agent
+```
+
+## 工具过滤的实现
+
+当 Agent 被派生时，`AgentTool` 根据定义中的 `tools` / `disallowedTools` 过滤可用工具列表：
+
+```
+全部工具
+  ↓ disallowedTools 移除
+  ↓ tools 白名单过滤（如果指定）
+可用工具
+```
+
+- **`tools` 未指定**：Agent 可以使用所有工具（默认全能）
+- **`tools` 指定**：只能使用列出的工具
+- **`disallowedTools`**：即使 `tools` 未指定，这些工具也被禁止
+- **自动注入**：`memory` 启用时自动添加 `Write`/`Edit`/`Read`
+
+以内置 Explore Agent 为例：
+
+```typescript
+// src/tools/AgentTool/built-in/exploreAgent.ts
+disallowedTools: [
+  'Agent',           // 不能嵌套调用 Agent
+  'ExitPlanMode',    // 不需要 plan mode
+  'FileEdit',        // 只读
+  'FileWrite',       // 只读
+  'NotebookEdit',    // 只读
+]
+```
+
+## System Prompt 的注入方式
+
+Agent 的 system prompt 通过 `getSystemPrompt()` 闭包延迟生成：
+
+```typescript
+// Markdown Agent
+getSystemPrompt: () => {
+  if (isAutoMemoryEnabled() && memory) {
+    return systemPrompt + '\n\n' + loadAgentMemoryPrompt(agentType, memory)
+  }
+  return systemPrompt
+}
+```
+
+这意味着：
+1. **Markdown 正文 = 完整的 system prompt**——不是追加，而是替换默认 prompt
+2. **Memory 指令**在 memory 启用时自动追加到末尾
+3. **闭包延迟计算**——memory 状态可能在文件加载后才变化
+
+对于 Built-in Agent，`getSystemPrompt` 接受 `toolUseContext` 参数，可以根据运行时状态（如是否使用嵌入式搜索工具）动态调整 prompt 内容。
+
+## 与 AgentTool 的联动
+
+当主 Agent 需要派生子 Agent 时：
+
+```
+AgentTool.call({ subagent_type: "reviewer", ... })
+  ↓
+1. 从 agentDefinitions.activeAgents 查找 agentType === "reviewer"
+  ↓
+2. 检查 requiredMcpServers（如果 Agent 要求特定 MCP 服务器）
+  ↓
+3. 过滤工具列表（tools / disallowedTools）
+  ↓
+4. 解析模型：
+   - "inherit" → 使用主线程模型
+   - 具体模型名 → 直接使用
+   - 未指定 → 主线程模型
+  ↓
+5. 解析权限模式（permissionMode）
+  ↓
+6. 构建隔离环境（如果 isolation === "worktree"）
+  ↓
+7. 注入 system prompt（getSystemPrompt()）
+  ↓
+8. 注入 initialPrompt（如果定义了）
+  ↓
+9. 启动子 Agent 循环（forkSubagent / runAgent）
+```
+
+## 内置 Agent 参考
+
+| Agent | agentType | 角色 | 工具限制 | 模型 |
+|-------|-----------|------|---------|------|
+| **General Purpose** | `general-purpose` | 默认子 Agent | 全部工具 | 主线程模型 |
+| **Explore** | `Explore` | 代码搜索专家 | 只读（无 Write/Edit） | haiku（外部） |
+| **Plan** | `Plan` | 规划专家 | 只读 + ExitPlanMode | inherit |
+| **Verification** | `verification` | 结果验证 | 由 feature flag 控制 | — |
+| **Code Guide** | `claude-code-guide` | Claude Code 使用指南 | 只读 | — |
+| **Statusline Setup** | `statusline-setup` | 终端状态栏配置 | 有限 | — |
+
+SDK 入口（`sdk-ts`/`sdk-py`/`sdk-cli`）不加载 Code Guide Agent。环境变量 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` 可以完全禁用内置 Agent，给 SDK 用户提供空白画布。
+
+## Agent Memory：持久化的 Agent 状态
+
+当 `memory` 字段启用时，Agent 获得跨会话的持久记忆：
+
+- **`local`**：当前项目、当前用户有效
+- **`project`**：当前项目所有用户共享
+- **`user`**：所有项目共享
+
+Memory 通过 `loadAgentMemoryPrompt()` 注入到 system prompt 末尾，包含读写记忆的指令。Agent Memory Snapshot 机制在项目间同步 `user` 级记忆。
--- a/docs/extensibility/hooks.mdx
+++ b/docs/extensibility/hooks.mdx
@@ -0,0 +1,239 @@
+---
+title: "Hooks 生命周期钩子 - 执行引擎与拦截协议"
+description: "从源码角度解析 Claude Code Hooks 系统：22 种 Hook 事件、6 种 Hook 类型、同步/异步执行协议、JSON 输出 schema、if 条件匹配、以及 Hook 如何注入上下文和拦截工具调用。"
+keywords: ["Hooks", "生命周期钩子", "拦截器", "PreToolUse", "Hook 协议"]
+---
+
+{/* 本章目标：从源码角度揭示 Hook 的执行引擎、匹配机制、返回值协议和生命周期管理 */}
+
+## 22 种 Hook 事件
+
+Claude Code 定义了 22 种 Hook 事件（`coreTypes.ts:25-53`），覆盖完整的 Agent 生命周期：
+
+| 阶段 | 事件 | 触发时机 | 匹配字段 |
+|------|------|---------|---------|
+| **会话** | `SessionStart` | 会话启动 | `source` |
+| | `SessionEnd` | 会话结束 | `reason` |
+| | `Setup` | 初始化完成 | `trigger` |
+| **用户交互** | `UserPromptSubmit` | 用户提交消息 | — |
+| | `Stop` | Agent 停止响应 | — |
+| | `StopFailure` | Agent 停止失败 | `error` |
+| **工具执行** | `PreToolUse` | 工具调用前 | `tool_name` |
+| | `PostToolUse` | 工具调用后（成功） | `tool_name` |
+| | `PostToolUseFailure` | 工具调用后（失败） | `tool_name` |
+| **权限** | `PermissionRequest` | 权限请求 | `tool_name` |
+| | `PermissionDenied` | 权限被拒 | `tool_name` |
+| **子 Agent** | `SubagentStart` | 子 Agent 启动 | `agent_type` |
+| | `SubagentStop` | 子 Agent 停止 | `agent_type` |
+| **压缩** | `PreCompact` | 上下文压缩前 | `trigger` |
+| | `PostCompact` | 上下文压缩后 | `trigger` |
+| **协作** | `TeammateIdle` | Teammate 空闲 | — |
+| | `TaskCreated` | 任务创建 | — |
+| | `TaskCompleted` | 任务完成 | — |
+| **MCP** | `Elicitation` | MCP 服务器请求用户输入 | `mcp_server_name` |
+| | `ElicitationResult` | Elicitation 结果返回 | `mcp_server_name` |
+| **环境** | `ConfigChange` | 配置变更 | `source` |
+| | `CwdChanged` | 工作目录变更 | — |
+| | `FileChanged` | 文件变更 | `file_path` |
+| | `InstructionsLoaded` | 指令加载 | `load_reason` |
+| | `WorktreeCreate` / `WorktreeRemove` | Worktree 操作 | — |
+
+## 6 种 Hook 类型
+
+Hooks 配置支持 6 种执行方式（`src/types/hooks.ts`）：
+
+| 类型 | 执行方式 | 适用场景 |
+|------|---------|---------|
+| `command` | Shell 命令（bash/PowerShell） | 通用脚本、CI 检查 |
+| `prompt` | 注入到 AI 上下文 | 代码规范提醒 |
+| `agent` | 启动子 Agent 执行 | 复杂分析任务 |
+| `http` | HTTP 请求 | 远程服务、Webhook |
+| `callback` | 内部 JS 函数 | 系统内置 Hook |
+| `function` | 运行时注册的函数 Hook | Agent/Skill 内部使用 |
+
+## 执行引擎：execCommandHook
+
+`execCommandHook()`（`src/utils/hooks.ts:829-1417`）是命令型 Hook 的执行核心：
+
+```
+execCommandHook(hook, hookEvent, hookName, jsonInput, signal)
+  ├── Shell 选择: hook.shell ?? DEFAULT_HOOK_SHELL
+  │   ├── bash: spawn(cmd, [], { shell: gitBashPath | true })
+  │   └── powershell: spawn(pwsh, ['-NoProfile', '-NonInteractive', '-Command', cmd])
+  ├── 变量替换
+  │   ├── ${CLAUDE_PLUGIN_ROOT} → pluginRoot 路径
+  │   ├── ${CLAUDE_PLUGIN_DATA} → plugin 数据目录
+  │   └── ${user_config.X} → 用户配置值
+  ├── 环境变量注入
+  │   ├── CLAUDE_PROJECT_DIR
+  │   ├── CLAUDE_ENV_FILE（SessionStart/Setup/CwdChanged/FileChanged）
+  │   └── CLAUDE_PLUGIN_OPTION_*（plugin options）
+  ├── stdin 写入: jsonInput + '\n'
+  ├── 超时: hook.timeout * 1000 ?? 600000ms（10分钟）
+  └── 异步检测: 检查 stdout 首行是否为 {"async":true}
+```
+
+### 异步 Hook 的检测协议
+
+Hook 进程的 stdout 第一行如果是 `{"async":true}`，系统将其转为后台任务（`hooks.ts:1199-1246`）：
+
+```typescript
+const firstLine = firstLineOf(stdout).trim()
+if (isAsyncHookJSONOutput(parsed)) {
+  executeInBackground({
+    processId: `async_hook_${child.pid}`,
+    asyncResponse: parsed,
+    ...
+  })
+}
+```
+
+后台 Hook 通过 `registerPendingAsyncHook()` 注册到 `AsyncHookRegistry`，完成后通过 `enqueuePendingNotification()` 通知主线程。
+
+### asyncRewake：Hook 唤醒模型
+
+`asyncRewake` 模式的 Hook 绕过 `AsyncHookRegistry`。当 Hook 退出码为 2 时，通过 `enqueuePendingNotification()` 以 `task-notification` 模式注入消息，唤醒空闲的模型（通过 `useQueueProcessor`）或在忙碌时注入 `queued_command` 附件。
+
+## Hook 输出的 JSON Schema
+
+同步 Hook 的输出遵循严格的 Zod schema（`src/types/hooks.ts:49-567`）：
+
+```json
+{
+  "continue": false,                    // 是否继续执行
+  "suppressOutput": true,               // 隐藏 stdout
+  "stopReason": "安全检查失败",           // continue=false 时的原因
+  "decision": "approve" | "block",      // 全局决策
+  "reason": "原因说明",                   // 决策原因
+  "systemMessage": "警告内容",           // 注入到上下文的系统消息
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "allow" | "deny" | "ask",
+    "permissionDecisionReason": "匹配了安全规则",
+    "updatedInput": { ... },            // 修改后的工具输入
+    "additionalContext": "额外上下文"     // 注入到对话
+  }
+}
+```
+
+### 各事件的 hookSpecificOutput
+
+| 事件 | 专有字段 | 作用 |
+|------|---------|------|
+| `PreToolUse` | `permissionDecision`, `updatedInput`, `additionalContext` | 拦截/修改工具输入 |
+| `UserPromptSubmit` | `additionalContext` | 注入额外上下文 |
+| `PostToolUse` | `additionalContext`, `updatedMCPToolOutput` | 修改 MCP 工具输出 |
+| `SessionStart` | `initialUserMessage`, `watchPaths` | 设置初始消息和文件监控 |
+| `PermissionDenied` | `retry` | 指示是否重试 |
+| `Elicitation` | `action`, `content` | 控制用户输入对话框 |
+
+## Hook 匹配机制：getMatchingHooks
+
+`getMatchingHooks()`（`hooks.ts:1685-1956`）负责从所有来源中查找匹配的 Hook：
+
+### 多来源合并
+
+```
+getHooksConfig()
+  ├── getHooksConfigFromSnapshot()    ← settings.json 中的 Hook（user/project/local）
+  ├── getRegisteredHooks()            ← SDK 注册的 callback Hook
+  ├── getSessionHooks()               ← Agent/Skill 前置注册的 session Hook
+  └── getSessionFunctionHooks()       ← 运行时 function Hook
+```
+
+### 匹配规则
+
+`matcher` 字段支持三种模式（`matchesPattern()`, `hooks.ts:1428-1463`）：
+
+```
+"Write"              → 精确匹配
+"Write|Edit"         → 管道分隔的多值匹配
+"^Bash(git.*)"       → 正则匹配
+"*" 或 ""            → 通配（匹配所有）
+```
+
+### if 条件过滤
+
+Hook 可以指定 `if` 条件，只在特定输入时触发。`prepareIfConditionMatcher()`（`hooks.ts:1472-1503`）预编译匹配器：
+
+```json
+{
+  "hooks": [{
+    "command": "check-git-branch.sh",
+    "if": "Bash(git push*)"
+  }]
+}
+```
+
+`if` 条件使用 `permissionRuleValueFromString` 解析，支持与权限规则相同的语法（工具名 + 参数模式）。Bash 工具还会使用 tree-sitter 进行 AST 级别的命令解析。
+
+### Hook 去重
+
+同一个 Hook 命令在不同配置层级（user/project/local）可能重复。系统按 `pluginRoot\0command` 做 Map 去重，保留**最后合并的层级**。
+
+## 工作区信任检查
+
+**所有 Hook 都要求工作区信任**（`shouldSkipHookDueToTrust()`, `hooks.ts:286-296`）。这是纵深防御措施——防止恶意仓库的 `.claude/settings.json` 在未信任的情况下执行任意命令。
+
+```typescript
+// 交互模式下，所有 Hook 要求信任
+const hasTrust = checkHasTrustDialogAccepted()
+return !hasTrust
+```
+
+SDK 非交互模式下信任是隐式的（`getIsNonInteractiveSession()` 为 true 时跳过检查）。
+
+## 四种 Hook 能力的源码映射
+
+### 1. 拦截操作（PreToolUse）
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "deny"
+  }
+}
+```
+
+`processHookJSONOutput()` 将 `permissionDecision` 映射为 `result.permissionBehavior = 'deny'`，并设置 `blockingError`，阻止工具执行。
+
+### 2. 修改行为（updatedInput / updatedMCPToolOutput）
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "updatedInput": { "command": "npm test -- --bail" }
+  }
+}
+```
+
+`updatedInput` 替换原始工具输入；`updatedMCPToolOutput`（PostToolUse 事件）替换 MCP 工具的返回值——可用于过滤敏感数据。
+
+### 3. 注入上下文（additionalContext / systemMessage）
+
+- `additionalContext` → 通过 `createAttachmentMessage({ type: 'hook_additional_context' })` 注入为用户消息
+- `systemMessage` → 注入为系统警告，直接显示给用户
+
+### 4. 控制流程（continue / stopReason）
+
+```json
+{ "continue": false, "stopReason": "构建失败，停止执行" }
+```
+
+`continue: false` 设置 `preventContinuation = true`，阻止 Agent 继续执行后续操作。
+
+## Session Hook 的生命周期
+
+Agent 和 Skill 的前置 Hook 通过 `registerFrontmatterHooks()` 注册（`runAgent.ts:567-575`），绑定到 agent 的 session ID。Agent 结束时通过 `clearSessionHooks()` 清理。
+
+```typescript
+// runAgent.ts:567 — 注册 agent 的前置 Hook
+registerFrontmatterHooks(rootSetAppState, agentId, agentDefinition.hooks, ...)
+
+// runAgent.ts:820 — finally 块清理
+clearSessionHooks(rootSetAppState, agentId)
+```
+
+这确保 Agent A 的 Hook 不会泄漏到 Agent B 的执行中。
--- a/docs/extensibility/mcp-protocol.mdx
+++ b/docs/extensibility/mcp-protocol.mdx
@@ -0,0 +1,191 @@
+---
+title: "MCP 协议 - 连接管理、工具发现与执行链路"
+description: "从源码角度解析 Claude Code 的 MCP 集成：7 种传输层实现、connectToServer 的 memoize 缓存、工具发现的 LRU 策略、认证状态机、以及 MCP 工具如何进入权限检查链路。"
+keywords: ["MCP", "Model Context Protocol", "工具扩展", "MCP 客户端", "工具发现"]
+---
+
+{/* 本章目标：从源码角度揭示 MCP 客户端的连接管理、工具发现协议和执行链路 */}
+
+## 架构总览：从配置到可用工具
+
+```
+settings.json: { mcpServers: { "my-db": { command: "npx", args: [...] } } }
+  ↓
+getAllMcpConfigs()                    ← 合并 user/project/local 三级配置
+  ↓
+useManageMCPConnections()             ← React Hook 管理连接生命周期
+  ↓
+connectToServer(name, config)         ← memoize 缓存（lodash memoize）
+  ├── 创建 Transport（stdio/sse/http/...）
+  ├── new Client()                    ← @modelcontextprotocol/sdk
+  ├── client.connect(transport)       ← 超时控制（MCP_TIMEOUT, 默认 30s）
+  └── 返回 MCPServerConnection        ← { connected | failed | needs-auth | pending }
+  ↓
+fetchToolsForClient(client)           ← LRU(20) 缓存
+  ├── client.request({ method: 'tools/list' })
+  └── 每个工具包装为 MCPTool            ← 统一 Tool 接口
+  ↓
+assembleToolPool()                    ← 合并内置工具 + MCP 工具
+  ↓
+工具名格式: mcp__<serverName>__<toolName>  ← buildMcpToolName()
+```
+
+## 7 种传输层实现
+
+`connectToServer()`（`client.ts:596-1643`）根据 `config.type` 分发到不同的 Transport 实现：
+
+| 传输类型 | Transport 类 | 适用场景 | 认证方式 |
+|----------|-------------|---------|---------|
+| `stdio`（默认） | `StdioClientTransport` | 本地子进程 | 无 |
+| `sse` | `SSEClientTransport` | 远程 SSE 服务 | `ClaudeAuthProvider` + OAuth |
+| `http` | `StreamableHTTPClientTransport` | HTTP 流 | `ClaudeAuthProvider` + OAuth |
+| `sse-ide` | `SSEClientTransport` | IDE 集成 | lockfile token |
+| `ws-ide` | `WebSocketTransport` | IDE WebSocket | `X-Claude-Code-Ide-Authorization` |
+| `ws` | `WebSocketTransport` | WebSocket 服务 | session ingress token |
+| `claudeai-proxy` | `StreamableHTTPClientTransport` | claude.ai 代理 | OAuth bearer + 401 重试 |
+
+### stdio 传输的进程管理
+
+stdio 类型的 MCP 服务器作为子进程运行，cleanup 时采用 **信号升级策略**（`client.ts:1431-1564`）：
+
+```
+SIGINT (100ms) → SIGTERM (400ms) → SIGKILL
+```
+
+总清理时间上限 600ms，防止 MCP 服务器关闭阻塞 CLI 退出。
+
+### 远程传输的认证状态机
+
+SSE/HTTP 类型使用 `ClaudeAuthProvider` 实现 OAuth 认证流程。认证失败时进入 `needs-auth` 状态，并写入 15 分钟 TTL 的缓存文件（`mcp-needs-auth-cache.json`），避免重复弹出认证提示。
+
+```
+连接尝试 → 401 Unauthorized
+  ↓
+handleRemoteAuthFailure()
+  ├── logEvent('tengu_mcp_server_needs_auth')
+  ├── setMcpAuthCacheEntry(name)         ← 写入 15min TTL 缓存
+  └── return { type: 'needs-auth' }      ← UI 显示认证提示
+```
+
+## 连接缓存与重连机制
+
+`connectToServer` 使用 lodash `memoize` 缓存连接对象，缓存 key 为 `${name}-${JSON.stringify(config)}`。
+
+### 缓存失效触发
+
+当连接关闭时（`client.onclose`），清除所有相关缓存（`client.ts:1376-1404`）：
+
+```typescript
+client.onclose = () => {
+  const key = getServerCacheKey(name, serverRef)
+  fetchToolsForClient.cache.delete(name)      // 工具缓存
+  fetchResourcesForClient.cache.delete(name)  // 资源缓存
+  fetchCommandsForClient.cache.delete(name)   // 命令缓存
+  connectToServer.cache.delete(key)           // 连接缓存
+}
+```
+
+### 连接降级检测
+
+远程传输有 **连续错误计数器**（`client.ts:1229`）：
+
+```typescript
+let consecutiveConnectionErrors = 0
+const MAX_ERRORS_BEFORE_RECONNECT = 3
+```
+
+遇到终端错误（ECONNRESET、ETIMEDOUT、EPIPE 等）连续 3 次后，主动关闭 transport 触发重连。对于 HTTP 传输，还检测 session 过期（404 + JSON-RPC code -32001）。
+
+### 请求级超时保护
+
+每个 HTTP 请求使用独立的 `setTimeout` 超时（`wrapFetchWithTimeout`，`client.ts:493`），而非共享 `AbortSignal.timeout()`。原因是 Bun 对 AbortSignal.timeout 的 GC 是惰性的——每个请求约 2.4KB 原生内存，即使请求毫秒级完成也要等 60s 才回收。
+
+```typescript
+const controller = new AbortController()
+const timer = setTimeout(c => c.abort(...), MCP_REQUEST_TIMEOUT_MS, controller)
+timer.unref?.()  // 不阻止进程退出
+```
+
+## 工具发现：从 MCP 到 Tool 接口
+
+`fetchToolsForClient()`（`client.ts:1745-2000`）使用 `memoizeWithLRU` 缓存（上限 20），将 MCP 工具转换为 Claude Code 的统一 Tool 接口：
+
+```typescript
+const fullyQualifiedName = buildMcpToolName(client.name, tool.name)
+// 结果: "mcp__my-db__query"
+```
+
+### 工具描述截断
+
+MCP 工具描述上限 2048 字符（`MAX_MCP_DESCRIPTION_LENGTH`）。OpenAPI 生成的 MCP 服务器曾观察到 15-60KB 的描述文档。
+
+### 工具能力标注
+
+每个 MCP 工具根据 `tool.annotations` 自动标注：
+
+| 注解 | 映射到 | 含义 |
+|------|--------|------|
+| `readOnlyHint` | `isReadOnly()` + `isConcurrencySafe()` | 只读，可并行 |
+| `destructiveHint` | `isDestructive()` | 破坏性操作 |
+| `openWorldHint` | `isOpenWorld()` | 开放世界（不可枚举） |
+| `title` | `userFacingName()` | 显示名称 |
+
+### MCP 工具的权限检查
+
+MCP 工具默认返回 `{ behavior: 'passthrough' }`（`client.ts:1816-1834`），意味着它们始终进入权限确认流程。工具名使用 `mcp__` 前缀精确匹配权限规则。
+
+## MCP 工具的执行链路
+
+```
+AI 生成 tool_use: { name: "mcp__my-db__query", input: { sql: "..." } }
+  ↓
+MCPTool.call()                               ← client.ts:1835
+  ├── ensureConnectedClient()                ← 确保连接有效（重连）
+  ├── callMCPToolWithUrlElicitationRetry()   ← 带 Elicitation 重试
+  │   ├── client.request({ method: 'tools/call' })
+  │   ├── 处理图片结果（resize + persist）
+  │   └── 内容截断（mcpContentNeedsTruncation）
+  ├── McpSessionExpiredError → 重试一次
+  └── 返回 { data: content, mcpMeta }
+```
+
+### Session 过期自动重试
+
+HTTP 传输的 MCP session 可能过期。检测到 `McpSessionExpiredError` 后自动重试一次（`client.ts:1862`），因为 `ensureConnectedClient()` 已经清除了缓存并建立了新连接。
+
+### 内容截断与持久化
+
+大型 MCP 工具输出通过 `truncateMcpContentIfNeeded` 截断，二进制内容（图片）通过 `persistBinaryContent` 写入文件并返回文件路径。图片自动 resize（`maybeResizeAndDownsampleImageBuffer`）。
+
+## MCP 连接的并发控制
+
+```typescript
+// 本地服务器并发连接数
+getMcpServerConnectionBatchSize()    // 默认 3
+
+// 远程服务器并发连接数
+getRemoteMcpServerConnectionBatchSize()  // 默认 20
+```
+
+本地 MCP 服务器（stdio）是重量级的子进程，默认限制 3 个并发连接。远程服务器是轻量级 HTTP 请求，允许 20 个并发。
+
+## 实际配置示例
+
+```json
+// settings.json 中的 MCP 配置
+{
+  "mcpServers": {
+    "my-database": {
+      "command": "npx",
+      "args": ["@my-org/db-mcp-server"],
+      "env": { "DB_URL": "postgres://..." }
+    },
+    "remote-api": {
+      "type": "http",
+      "url": "https://api.example.com/mcp"
+    }
+  }
+}
+```
+
+配置后，AI 的工具列表中会出现 `mcp__my-database__query` 和 `mcp__remote-api__*` 工具——与内置工具使用相同的权限检查链路和 UI 渲染。
--- a/docs/extensibility/skills.mdx
+++ b/docs/extensibility/skills.mdx
@@ -0,0 +1,221 @@
+---
+title: "Skills 技能系统 - Prompt 即能力的架构哲学"
+description: "深入剖析 Claude Code Skills 系统的完整实现：从磁盘加载、Frontmatter 解析、预算感知描述截断、双模式执行（inline/fork）、权限白名单、条件激活、动态发现到远程技能加载，揭示一条完整的 Skill 生命周期链路。"
+keywords: ["Skills", "SkillTool", "技能加载", "Frontmatter", "whenToUse", "allowedTools", "fork执行", "动态发现"]
+---
+
+{/* 本章目标：揭示 Skill 系统从文件到执行的全链路实现 */}
+
+## Tool vs Skill：本质差异
+
+| | Tool | Skill |
+|---|---|---|
+| 粒度 | 单个原子操作（读文件、执行命令） | 一套完整的工作流（代码审查、创建 PR） |
+| 触发方式 | AI 自主选择 | 用户 `/skill-name` 或 AI 通过 `SkillTool` 自动匹配 |
+| 本质 | TypeScript 执行逻辑 | **Prompt + 权限配置**的声明式封装 |
+| 注册位置 | `src/tools.ts` → `getTools()` | `src/commands.ts` → `getCommands()` |
+| 执行器 | 各 Tool 的 `call()` 方法 | `SkillTool.call()` → 两条分支（inline / fork） |
+
+Skill 的核心洞见：**复杂任务的关键不在代码逻辑，而在 Prompt 质量**。一个代码审查 Skill 不需要审查引擎，只需告诉 AI "审查什么、按什么顺序、输出什么格式"——Skill 把这种"经验"封装为可复用的 Markdown。
+
+## Skill 的五个来源与加载链路
+
+### 1. 内置命令（Built-in Commands）
+
+硬编码在 `src/commands.ts:258` 的 `COMMANDS` memoize 数组中，包含 70+ 条命令（`/commit`、`/review`、`/compact` 等）。这些是 TypeScript 模块而非 Markdown，但实现了相同的 `Command` 接口（`src/types/command.ts`）。
+
+### 2. Bundled Skills（编译时打包）
+
+通过 `registerBundledSkill()`（`src/skills/bundledSkills.ts:53`）在模块初始化时注册。关键特性：
+
+- **延迟文件提取**：如果 Skill 声明了 `files`（参考文件），首次调用时才解压到临时目录（`getBundledSkillExtractDir()`），使用 `O_NOFOLLOW | O_EXCL` 防止符号链接攻击（`safeWriteFile`，第 186 行）
+- **闭包级 memoize**：并发调用共享同一个 extraction promise，避免竞态写入
+- 来源标记为 `source: 'bundled'`，在 Prompt 预算中享有**不可截断**的特权
+
+### 3. 磁盘 Skills（`.claude/skills/`）
+
+由 `loadSkillsFromSkillsDir()`（`src/skills/loadSkillsDir.ts:407`）加载，这是最重要的加载路径：
+
+```
+管理策略: $MANAGED_DIR/.claude/skills/     (policySettings)
+用户全局: ~/.claude/skills/                 (userSettings)
+项目级:   .claude/skills/                   (projectSettings, 向上遍历至 home)
+附加目录: --add-dir 指定的路径下 .claude/skills/
+```
+
+**加载协议**：只识别 `skill-name/SKILL.md` 目录格式，不再支持单文件 `.md`。加载流程：
+
+1. `readdir` 扫描目录 → 仅保留 `isDirectory()` 或 `isSymbolicLink()` 的条目
+2. 在每个子目录中查找 `SKILL.md`，未找到则跳过
+3. `parseFrontmatter()` 解析 YAML 头部，提取 `whenToUse`、`allowedTools`、`context` 等字段
+4. `parseSkillFrontmatterFields()`（第 185 行）统一解析 17 个 frontmatter 字段
+5. `createSkillCommand()`（第 270 行）构造 `Command` 对象
+
+**去重机制**：使用 `realpath()` 解析符号链接获得规范路径（`getFileIdentity`，第 118 行），避免通过符号链接或重叠父目录导致的重复加载。
+
+### 4. MCP Skills（动态发现）
+
+通过 `registerMCPSkillBuilders()` 注册构建器，MCP Server 的 prompt 被 `mcpSkillBuilders.ts` 转换为 `Command` 对象。标记为 `loadedFrom: 'mcp'`。
+
+**安全边界**：MCP Skills 的 Prompt 内容**禁止执行内联 shell 命令**（`loadSkillsDir.ts:374` 的 `loadedFrom !== 'mcp'` 守卫），因为远程内容不可信。
+
+### 5. Legacy Commands（`/commands/` 目录）
+
+向后兼容的旧格式，由 `loadSkillsFromCommandsDir()`（第 566 行）加载。同时支持 `SKILL.md` 目录格式和单 `.md` 文件格式。
+
+## Frontmatter 字段全景
+
+一个 `SKILL.md` 的完整 frontmatter（`parseSkillFrontmatterFields`，第 185 行）：
+
+```yaml
+---
+name: code-review                    # 显示名称（覆盖目录名）
+description: 系统性代码审查           # 描述（或从 Markdown 首段提取）
+when_to_use: "用户说审查代码、找 bug"  # AI 自动匹配依据
+allowed-tools:                       # 工具白名单
+  - Read
+  - Grep
+  - Glob
+argument-hint: "<file-or-directory>" # 参数提示
+arguments: [path]                    # 声明式参数名（用于 $ARGUMENTS 替换）
+model: opus                          # 模型覆盖
+effort: high                         # 努力级别
+context: fork                        # 执行模式：inline（默认）| fork
+agent: code-reviewer                 # 指定 Agent 定义文件
+user-invocable: true                 # 用户是否可 /调用
+disable-model-invocation: false      # 禁止 AI 自主调用
+version: "1.0"                       # 版本号
+paths:                               # 条件激活的文件路径模式
+  - "src/**/*.ts"
+hooks:                               # Hook 配置
+  PreToolUse:
+    - command: ["echo", "checking"]
+shell: ["bash"]                      # Shell 执行环境
+---
+```
+
+解析后有 17 个字段被提取，其中 `allowedTools`、`model`、`effort` 在执行时动态修改 `toolPermissionContext`。
+
+## 两条执行路径：Inline vs Fork
+
+SkillTool（`src/tools/SkillTool/SkillTool.ts:332`）在 `call()` 中根据 `command.context` 分流：
+
+### Inline 模式（默认）
+
+Skill 的 Prompt 内容被注入为 **UserMessage**，在主对话流中继续执行：
+
+1. `processPromptSlashCommand()` 处理参数替换（`$ARGUMENTS`）和 shell 命令展开（`` !`...` ``）
+2. `${CLAUDE_SKILL_DIR}` 被替换为 Skill 所在目录的绝对路径
+3. `${CLAUDE_SESSION_ID}` 被替换为当前会话 ID
+4. 返回 `newMessages`（注入到对话流）+ `contextModifier`（修改权限上下文）
+
+`contextModifier`（第 776 行）做了三件事：
+- **工具白名单注入**：将 `allowedTools` 合并到 `alwaysAllowRules.command`
+- **模型切换**：`resolveSkillModelOverride()` 处理模型覆盖，保留 `[1m]` 后缀以避免 200K 窗口截断
+- **努力级别覆盖**：修改 `effortValue`
+
+### Fork 模式（`context: fork`）
+
+Skill 在**独立子 Agent** 中执行（`executeForkedSkill`，第 122 行）：
+
+1. `prepareForkedCommandContext()` 构建隔离的 Agent 定义和 Prompt
+2. `runAgent()` 启动子 Agent 循环，拥有独立的 token 预算
+3. 通过 `onProgress` 回调报告工具使用进度
+4. 结果通过 `extractResultText()` 提取，子 Agent 的全部消息在提取后被释放（`agentMessages.length = 0`）
+5. 最终通过 `clearInvokedSkillsForAgent()` 清理状态
+
+Fork 模式适用于需要强隔离的场景（如长时间运行的审查任务），避免污染主对话的上下文。
+
+## 权限模型：Safe Properties 白名单
+
+`checkPermissions()`（第 433 行）实现了一个四层权限检查：
+
+```
+1. Deny 规则匹配（支持精确匹配和 prefix:* 通配符）
+   ↓ 未命中
+2. 官方市场 Skill 自动放行（plugin + isOfficialMarketplaceName）
+   ↓ 未命中
+3. Allow 规则匹配
+   ↓ 未命中
+4. Safe Properties 白名单检查（skillHasOnlySafeProperties，第 911 行）
+   ↓ 有非安全属性
+5. Ask 用户确认（附带精确匹配和前缀匹配两条建议规则）
+```
+
+**Safe Properties**（`SAFE_SKILL_PROPERTIES`，第 876 行）是一个包含 28 个属性名的白名单。任何不在白名单中的**有意义的属性值**（排除 `undefined`、`null`、空数组、空对象）都会触发权限请求。这是**正向安全**设计——未来新增的属性默认需要权限。
+
+## Prompt 预算：1% 上下文窗口的截断策略
+
+Skill 列表注入 System Prompt 时有严格的字符预算（`prompt.ts`）：
+
+- **预算计算**：`contextWindowTokens × 4 chars/token × 1%`（约 8000 字符）
+- **单条上限**：`MAX_LISTING_DESC_CHARS = 250` 字符（超出截断为 `…`）
+- **Bundled Skills 不可截断**：它们始终保留完整描述，预算不足时只截断非 bundled 的
+- **降级策略**：
+  1. 尝试完整描述 → 超预算？
+  2. Bundled 保留完整，非 bundled 均分剩余预算 → 每条描述低于 20 字符？
+  3. 非 bundled 仅保留名称
+
+`formatCommandsWithinBudget()`（`prompt.ts:70`）实现了这个三级降级。
+
+## 动态发现与条件激活
+
+### 基于文件路径的动态发现
+
+`discoverSkillDirsForPaths()`（`loadSkillsDir.ts:861`）在文件操作时触发：
+
+1. 从被操作的文件路径开始，**向上遍历**至 CWD（不包含 CWD 本身）
+2. 在每层查找 `.claude/skills/` 目录
+3. 使用 `realpath` 去重，`git check-ignore` 过滤 gitignored 目录
+4. 按路径深度排序（**深层优先**），更接近文件的 Skill 优先级更高
+
+### 条件激活（paths frontmatter）
+
+带有 `paths` 模式的 Skill 在加载时不会立即可用，而是存入 `conditionalSkills` Map。当被操作的文件路径匹配某个 Skill 的 paths 模式时（使用 `ignore` 库做 gitignore 风格匹配），该 Skill 才被**激活**——从 `conditionalSkills` 移入 `dynamicSkills`。
+
+这意味着一个只在 `*.test.ts` 上激活的测试 Skill，平时完全不可见，只有当 AI 读取或编辑测试文件时才会出现。
+
+## 使用频率排名
+
+`recordSkillUsage()`（`skillUsageTracking.ts`）使用指数衰减算法计算 Skill 排名分数：
+
+```
+score = usageCount × max(0.5^(daysSinceUse / 7), 0.1)
+```
+
+- **7 天半衰期**：一周前的使用权重减半
+- **最低 0.1 保底**：避免老但高频使用的 Skill 完全沉底
+- **60 秒去抖**：同一 Skill 在 1 分钟内的多次调用只计一次，减少文件 I/O
+
+排名数据持久化在全局配置的 `skillUsage` 字段中。
+
+## 远程技能加载（Experimental）
+
+通过 `EXPERIMENTAL_SKILL_SEARCH` feature flag 控制，支持从远程（AKI/GCS/S3）加载 `_canonical_<slug>` 格式的 Skill：
+
+1. `validateInput()` 中 `stripCanonicalPrefix()` 拦截 canonical 名称
+2. `executeRemoteSkill()`（第 970 行）从远程 URL 加载 SKILL.md
+3. 支持 `gs://`、`https://`、`s3://` 等 URL 协议
+4. 内容经过 frontmatter 剥离、`${CLAUDE_SKILL_DIR}` 替换后直接注入
+5. 通过 `addInvokedSkill()` 注册到 compaction 保留状态，确保压缩后仍可恢复
+6. 远程 Skill 不经过 `processPromptSlashCommand`——无 `!command` 替换、无 `$ARGUMENTS` 展开
+
+## 完整生命周期总结
+
+```
+磁盘 SKILL.md
+  ↓ parseFrontmatter()
+  ↓ parseSkillFrontmatterFields() → 17 个字段
+  ↓ createSkillCommand() → Command 对象
+  ↓ 去重（realpath + seenFileIds）
+  ↓ 条件 Skill → conditionalSkills Map（等待路径匹配激活）
+  ↓ getSkillDirCommands() memoize 缓存
+  ↓ getAllCommands() 合并 local + MCP
+  ↓ formatCommandsWithinBudget() → 截断后的 Skill 列表注入 System Prompt
+  ↓ AI 选择匹配的 Skill
+  ↓ SkillTool.validateInput() → 名称校验 + 存在性检查
+  ↓ SkillTool.checkPermissions() → 四层权限检查
+  ↓ SkillTool.call() → inline 或 fork 执行
+  ↓ contextModifier() → 注入 allowedTools + model + effort
+  ↓ recordSkillUsage() → 更新使用频率排名
+```