docs: add main architecture + bridge/remote architecture documents

ARCHITECTURE-BRIDGE-REMOTE.md

@@ -0,0 +1,298 @@
+# Bridge / Remote / Coordinator 架构详细文档
+
+---
+
+## Bridge 系统 (src/bridge/, 31 文件)
+
+### 概述
+
+Bridge 是 Claude Code 的 **远程控制核心**，实现本地 CLI 与 claude.ai/web/mobile 之间的双向通信。核心场景：用户通过手机上的 Claude 应用控制本地终端中的 Claude Code 会话。
+
+### 文件清单与职责
+
+#### 核心会话管理
+
+| 文件 | 行数(估) | 职责 |
+|------|---------|------|
+| `bridgeMain.ts` | ~3000 | 桥接主循环。连接 claude.ai bridge API、轮询 work、生成 session、管理生命周期 |
+| `sessionRunner.ts` | ~400 | 会话执行器：生成子进程执行 work item，管理 worktree 隔离 |
+| `createSession.ts` | ~200 | 会话创建辅助 |
+| `replBridge.ts` | ~2400 | REPL 与远程的桥接核心。处理 SDK 消息的 ingress/egress、权限转发 |
+| `replBridgeHandle.ts` | ~200 | Bridge handle 管理 |
+| `replBridgeTransport.ts` | ~300 | 传输层抽象：v1 (WebSocket) 和 v2 (HybridTransport) |
+
+#### 消息与控制
+
+| 文件 | 职责 |
+|------|------|
+| `bridgeMessaging.ts` | 共享传输层：SDK 消息解析、控制请求处理、echo 去重、结果消息构建 |
+| `inboundMessages.ts` | 入站消息处理 |
+| `inboundAttachments.ts` | 入站附件处理 |
+| `bridgeApi.ts` | Bridge API 客户端：环境发现、work 轮询、session 报告 |
+| `bridgePermissionCallbacks.ts` | 权限回调代理：将远程权限请求转发到本地 REPL |
+
+#### 安全与认证
+
+| 文件 | 职责 |
+|------|------|
+| `jwtUtils.ts` | JWT token 管理：创建、刷新调度、过期检测 |
+| `trustedDevice.ts` | 可信设备认证：注册设备 token，用于 Remote Control 安全验证 |
+| `workSecret.ts` | Work secret 解码/构建：解析 server 下发的 session ingress token、API base URL 等 |
+| `sessionIdCompat.ts` | Session ID 兼容层：infra session ID 与 compat session ID 转换 |
+
+#### 配置与控制
+
+| 文件 | 职责 |
+|------|------|
+| `bridgeConfig.ts` | Bridge 配置：token、org UUID、environment ID |
+| `envLessBridgeConfig.ts` | 无环境变量的 Bridge 配置 |
+| `bridgeEnabled.ts` | 功能开关检查：是否启用 Remote Control |
+| `initReplBridge.ts` | REPL Bridge 初始化 |
+| `pollConfig.ts` / `pollConfigDefaults.ts` | 轮询间隔配置（指数退避） |
+| `flushGate.ts` | 消息刷新门控 |
+
+#### 其他
+
+| 文件 | 职责 |
+|------|------|
+| `bridgeUI.ts` | Bridge UI 日志工具 |
+| `bridgeDebug.ts` / `debugUtils.ts` | 调试工具 |
+| `bridgeStatusUtil.ts` | 状态格式化 |
+| `bridgePointer.ts` | Bridge 指针管理 |
+| `capacityWake.ts` | 容量唤醒：检测是否有 capacity 来处理新的 work |
+| `codeSessionApi.ts` | 代码会话 API |
+| `types.ts` | 类型定义：BridgeConfig, SessionHandle, SpawnMode 等 |
+
+### 核心流程
+
+```
+claude remote-control
+  │
+  ├─ bridgeMain.ts: 连接 claude.ai bridge API
+  │   ├─ 获取 environment ID
+  │   ├─ 注册 trusted device
+  │   └─ 开始轮询 work
+  │
+  ├─ 轮询循环 (指数退避):
+  │   ├─ GET /environments/{id}/work
+  │   ├─ 收到 work item → sessionRunner 生成子进程
+  │   │   ├─ 创建 worktree (隔离)
+  │   │   ├─ 解析 work secret → session ingress token
+  │   │   ├─ spawn claude CLI 子进程
+  │   │   └─ 收集输出 → 上报
+  │   └─ 无 work → 继续轮询
+  │
+  └─ 子进程通过 SDK 流式输出消息
+      └─ bridgeMessaging.ts 处理 ingress
+          ├─ SDKMessage → 转发到远程
+          ├─ control_request → 权限代理
+          └─ echo → 去重跳过
+```
+
+### 协议层
+
+Bridge 使用 **SDK 消息协议** (与 Anthropic Agent SDK 兼容):
+
+```
+SDKMessage = 
+  | assistant message    (text, tool_use blocks)
+  | user message         (tool_result blocks)
+  | system message       (info, warning)
+  | result message       (usage, cost, duration)
+  | control_request      (permission prompts)
+  | control_response     (permission decisions)
+```
+
+传输层支持两种模式：
+- **v1**: WebSocket 直连
+- **v2**: HybridTransport (WebSocket + HTTP fallback)
+
+---
+
+## Remote 系统 (src/remote/, 4 文件)
+
+### 概述
+
+Remote 系统实现 **CCR (Claude Code Remote)** 模式：用户通过 `--remote` 标志创建远程会话，本地 TUI 作为 viewer/client。
+
+### 文件清单
+
+| 文件 | 职责 |
+|------|------|
+| `RemoteSessionManager.ts` | 远程会话管理器：创建会话配置、处理 SDK 消息和控制请求 |
+| `SessionsWebSocket.ts` | WebSocket 客户端：连接 CCR 后端、处理消息、重连逻辑 |
+| `remotePermissionBridge.ts` | 远程权限桥接 |
+| `sdkMessageAdapter.ts` | SDK 消息适配器 |
+
+### 核心流程
+
+```
+claude --remote "task description"
+  │
+  ├─ prepareApiRequest() → 获取 OAuth token
+  ├─ teleportToRemoteWithErrorHandling() → 创建远程会话
+  ├─ createRemoteSessionConfig() → 生成连接配置
+  │
+  └─ REPL 启动:
+      ├─ SessionsWebSocket 连接远程
+      ├─ RemoteSessionManager 管理消息流
+      │   ├─ 用户输入 → WebSocket → 远程执行
+      │   └─ 远程输出 → WebSocket → 本地显示
+      └─ 权限请求 → remotePermissionBridge → 本地确认
+```
+
+---
+
+## Server 系统 (src/server/, 3 文件)
+
+### Direct Connect
+
+`createDirectConnectSession.ts` — 创建直连会话。POST 到 `${serverUrl}/sessions`，返回 `DirectConnectConfig` 供 REPL 使用。
+
+`directConnectManager.ts` — 直连会话管理。
+
+`types.ts` — 连接响应 schema 验证。
+
+### 使用场景
+
+```
+claude connect cc://server-url
+  │
+  ├─ parseConnectUrl() → 提取 serverUrl + authToken
+  ├─ createDirectConnectSession() → 创建会话
+  └─ launchRepl() with directConnectConfig
+      └─ REPL 通过 DirectConnectConfig 与远程通信
+```
+
+---
+
+## Coordinator 系统 (src/coordinator/)
+
+### 概述
+
+`coordinatorMode.ts` — 多 Agent 协调模式。一个 "协调者" Agent 分发任务给多个 "工作器" Agent。
+
+### 核心机制
+
+协调模式通过环境变量 `CLAUDE_CODE_COORDINATOR_MODE=1` 启用。
+
+工具过滤：
+- 协调者只能使用：AgentTool, TaskStopTool, SendMessageTool, TeamCreateTool, TeamDeleteTool
+- 工作器使用：BashTool, FileReadTool, FileEditTool, FileWriteTool 等基础工具
+- 工作器禁止：AgentTool (防止递归), TeamCreateTool, TeamDeleteTool
+
+### 协调者工具集
+
+```typescript
+const COORDINATOR_MODE_ALLOWED_TOOLS = [
+  AGENT_TOOL_NAME,        // 派发子任务给工作器
+  BASH_TOOL_NAME,         // 读取文件/检查状态
+  FILE_READ_TOOL_NAME,    // 读文件
+  FILE_EDIT_TOOL_NAME,    // 编辑文件
+  TASK_STOP_TOOL_NAME,    // 停止工作器
+  SEND_MESSAGE_TOOL_NAME, // 与工作器通信
+]
+```
+
+### 工作器执行
+
+工作器以 in-process 或 tmux 方式启动：
+- `in-process`: 子 Agent 在同一进程内运行
+- `tmux`: 子 Agent 在独立 tmux 窗格中运行
+
+每个工作器有独立的工作树 (worktree)、独立的工具权限上下文。
+
+---
+
+## Swarm 团队系统 (utils/swarm/)
+
+### 目录结构
+
+```
+utils/swarm/
+├── backends/
+│   ├── InProcessBackend.ts    — 进程内执行后端
+│   ├── TmuxBackend.ts         — tmux 执行后端
+│   ├── ITermBackend.ts        — iTerm2 执行后端
+│   ├── PaneBackendExecutor.ts — 窗格执行器
+│   ├── detection.ts           — 后端检测
+│   ├── registry.ts            — 后端注册
+│   └── types.ts               — 类型定义
+├── constants.ts               — 常量
+├── inProcessRunner.ts         — 进程内运行器
+├── leaderPermissionBridge.ts  — 领导者权限桥接
+├── permissionSync.ts          — 权限同步
+├── reconnection.ts            — 重连逻辑
+├── spawnInProcess.ts          — 进程内生成
+├── spawnUtils.ts              — 生成工具
+├── teamHelpers.ts             — 团队辅助
+├── teammateInit.ts            — 队友初始化
+├── teammateLayoutManager.ts   — 队友布局管理
+├── teammateModel.ts           — 队友模型
+└── teammatePromptAddendum.ts  — 队友提示补充
+```
+
+### 架构
+
+Swarm 团队由一个 Leader 和多个 Teammate 组成：
+
+```
+Leader (协调者)
+  │
+  ├─ Teammate 1 (tmux/in-process)
+  ├─ Teammate 2 (tmux/in-process)
+  └─ Teammate N (tmux/in-process)
+```
+
+Leader 通过 `TeamCreateTool` 创建队友，通过 `SendMessageTool` 与队友通信。
+
+权限同步：Leader 的权限决策通过 `leaderPermissionBridge` 同步给所有队友。
+
+---
+
+## 系统间协作关系
+
+```
+┌──────────────────┐     ┌──────────────────┐
+│   claude.ai      │     │  Mobile/Web App  │
+│   Bridge API     │     │   (CCR Client)   │
+└────────┬─────────┘     └────────┬─────────┘
+         │                        │
+    Bridge 协议              Remote 协议
+    (JWT auth)              (OAuth auth)
+         │                        │
+┌────────▼────────────────────────▼────────┐
+│          本地 Claude Code CLI            │
+│                                          │
+│  ┌──────────┐  ┌──────────┐  ┌────────┐ │
+│  │  Bridge  │  │  Remote  │  │ Server │ │
+│  │ Manager  │  │  Session │  │ Mode   │ │
+│  └────┬─────┘  └────┬─────┘  └───┬────┘ │
+│       │             │            │       │
+│       └─────────────┼────────────┘       │
+│                     │                    │
+│              ┌──────▼──────┐             │
+│              │    REPL     │             │
+│              │  (本地交互)  │             │
+│              └──────┬──────┘             │
+│                     │                    │
+│              ┌──────▼──────┐             │
+│              │   Query     │             │
+│              │  Engine     │             │
+│              └──────┬──────┘             │
+│                     │                    │
+│              ┌──────▼──────┐             │
+│              │   Tools     │             │
+│              │  (执行层)   │             │
+│              └─────────────┘             │
+└──────────────────────────────────────────┘
+```
+
+## 关键设计决策
+
+1. **Worktree 隔离**：每个远程会话在独立 worktree 中执行，避免污染本地工作区
+2. **JWT 认证**：Bridge 使用 JWT 而非 OAuth，支持 token 刷新调度
+3. **Echo 去重**：bridgeMessaging.ts 中的 BoundedUUIDSet 防止消息回环
+4. **指数退避轮询**：pollConfig.ts 实现智能轮询，空闲时降低频率
+5. **Trusted Device**：远程控制需要设备注册，增强安全性
+6. **v1/v2 传输**：支持 WebSocket (v1) 和 HybridTransport (v2) 两种传输模式

ARCHITECTURE.md

@@ -0,0 +1,493 @@
+# Claude Code — 架构全景
+
+> 项目规模：~1,900 源文件，512,000+ 行 TypeScript/TSX
+> 运行时：Bun | 终端 UI：React + Ink (自定义渲染器) | CLI：Commander.js
+
+---
+
+## 1. 整体架构分层
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    CLI 入口 (main.tsx)                   │
+│  Commander.js 参数解析 → 会话初始化 → 渲染上下文         │
+├─────────────────────────────────────────────────────────┤
+│                    REPL 屏幕 (REPL.tsx)                  │
+│  主交互循环：用户输入 → LLM 查询 → 工具执行 → UI 渲染    │
+├──────────┬──────────┬──────────┬────────────────────────┤
+│ Commands │  Tools   │ Services │    Bridge/Remote       │
+│ (斜杠命令)│ (工具系统)│ (服务层)  │    (IDE/远程集成)      │
+├──────────┴──────────┴──────────┴────────────────────────┤
+│                    State Management                     │
+│  Zustand store + onChangeAppState + hooks               │
+├─────────────────────────────────────────────────────────┤
+│                    Ink 渲染器 (ink/)                     │
+│  自定义 React 渲染器 → 终端 ANSI 输出                    │
+├─────────────────────────────────────────────────────────┤
+│                    组件层 (components/)                   │
+│  346 个 React 组件：消息渲染、权限对话框、导航等          │
+├─────────────────────────────────────────────────────────┤
+│                    Hooks 层 (hooks/)                     │
+│  104 个自定义 hooks：输入处理、权限、IDE集成、通知等      │
+├─────────────────────────────────────────────────────────┤
+│                    工具函数层 (utils/)                    │
+│  ~300 个工具文件：git、shell、权限、插件、模型等          │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. 入口与初始化流程
+
+### main.tsx (4,683 行)
+
+程序的唯一入口。初始化顺序：
+
+```
+1. 启动优化：profileCheckpoint + MDM 子进程 + Keychain 预取 (并行)
+2. 导入权重模块 (~135ms)
+3. 检测调试模式 → 拦截调试器
+4. main() 函数:
+   ├─ 安全设置 (Windows PATH 安全)
+   ├─ URL 处理 (cc://, deep link, SSH, assistant)
+   ├─ 检测 -p/--print (非交互模式) vs 交互模式
+   ├─ Commander.js 程序定义 (~100 个 CLI 选项)
+   ├─ preAction hook:
+   │   ├─ init() - 配置、认证、特性开关初始化
+   │   ├─ 运行迁移 (11 个版本迁移)
+   │   ├─ 加载远程管理设置
+   │   └─ 加载策略限制
+   └─ 主命令 action:
+       ├─ initializeToolPermissionContext()
+       ├─ setup() - 工作目录、工作树
+       ├─ getCommands() + getAgentDefinitions() (并行)
+       ├─ showSetupScreens() - 信任对话框、OAuth、引导
+       ├─ MCP 配置加载和连接
+       ├─ 构建初始 AppState
+       └─ 分支:
+           ├─ --continue → 加载最近对话 → launchRepl()
+           ├─ --resume <id> → 恢复指定会话 → launchRepl()
+           ├─ --teleport → 远程恢复 → launchRepl()
+           ├─ --remote → 远程会话 → launchRepl()
+           ├─ -p/--print → runHeadless() (非交互)
+           └─ 默认 → launchRepl() (新会话)
+```
+
+### 初始化优化策略
+
+- **并行预取**：MDM 读取、Keychain 读取、API 预连接在导入前并行启动
+- **延迟加载**：OpenTelemetry (~400KB)、gRPC (~700KB) 等通过 `import()` 延迟
+- **Feature Flag 死码消除**：`bun:bundle` 的 `feature()` 在构建时裁剪未启用的功能
+- **Memoize 缓存**：`getCommands()`、`getTools()` 等昂贵操作通过 lodash memoize 缓存
+
+### Feature Flags (关键)
+
+| Flag | 功能 |
+|------|------|
+| `PROACTIVE` / `KAIROS` | 主动模式 / 助手模式 |
+| `BRIDGE_MODE` | 远程控制 (Remote Control) |
+| `DIRECT_CONNECT` | cc:// URL 直连 |
+| `SSH_REMOTE` | SSH 远程会话 |
+| `COORDINATOR_MODE` | 多 Agent 协调模式 |
+| `TRANSCRIPT_CLASSIFIER` | 自动模式 (auto-mode) |
+| `VOICE_MODE` | 语音输入 |
+| `AGENT_TRIGGERS` | Cron 定时触发 |
+| `WORKFLOW_SCRIPTS` | 工作流脚本 |
+| `TERMINAL_PANEL` | 终端面板捕获 |
+| `WEB_BROWSER_TOOL` | 内嵌浏览器 |
+
+---
+
+## 3. REPL 交互循环 (REPL.tsx, 5,005 行)
+
+核心交互界面。数据流：
+
+```
+用户输入 (PromptInput)
+  │
+  ├─ /命令 → processSlashCommand() → 命令处理
+  │
+  └─ 普通文本 → processUserInput()
+       │
+       ├─ fetchSystemPromptParts() → 系统提示
+       ├─ loadMemoryPrompt() → 记忆
+       ├─ buildEffectiveSystemPrompt() → 合成最终系统提示
+       │
+       └─ query() [QueryEngine.ts, 1,295 行]
+            │
+            ├─ API 调用 (Anthropic SDK, 流式)
+            ├─ 思考模式 (thinking config)
+            ├─ Token 预算管理
+            │
+            └─ 工具调用循环:
+                 │
+                 ├─ 工具使用块 → 权限检查
+                 │   ├─ 通过 → 执行工具
+                 │   └─ 拒绝 → 提示用户批准/拒绝
+                 │
+                 └─ 继续 API 调用直到完成
+```
+
+### QueryEngine.ts 核心职责
+
+1. 构建 API 请求（消息、系统提示、工具定义）
+2. 处理流式响应（thinking、工具使用、文本）
+3. Token 计数和预算管理
+4. 重试逻辑和错误处理
+5. 紧凑/压缩触发
+6. 副本记录 (transcript recording)
+
+---
+
+## 4. 状态管理
+
+### AppStateStore.ts (569 行)
+
+使用自定义的 `createStore()` 实现（非 Redux，非 Zustand），类型安全。
+
+核心状态字段：
+
+```typescript
+AppState {
+  // 核心
+  verbose: boolean
+  mainLoopModel: ModelSetting
+  toolPermissionContext: ToolPermissionContext
+  isBriefOnly: boolean
+
+  // MCP
+  mcp: { clients, tools, commands, resources }
+
+  // 插件
+  plugins: { enabled, disabled, commands, errors }
+
+  // 远程控制
+  replBridgeEnabled: boolean
+  replBridgeConnected: boolean
+
+  // 任务
+  tasks: Record<string, TaskState>
+  todos: Record<string, TodoList>
+
+  // 团队
+  teamContext: TeamContext
+
+  // 通知
+  notifications: { current, queue }
+
+  // 会话
+  inbox: { messages }
+  speculation: SpeculationState
+  attribution: AttributionState
+  sessionHooks: Map
+}
+```
+
+### onChangeAppState
+
+状态变更时触发的副作用集合。`store.setState()` 后会执行 `onChangeAppState` 中注册的所有回调。
+
+---
+
+## 5. 工具系统 (tools/, 42 个工具)
+
+### 工具接口 (Tool.ts, 792 行)
+
+每个工具实现 `Tool` 接口：
+
+```typescript
+Tool {
+  name: string                    // 工具名称
+  description: string             // 描述 (用于系统提示)
+  inputSchema: JSONSchema         // 输入 JSON Schema
+  userFacingName(): string        // 用户显示名
+  isEnabled(): boolean            // 是否启用
+  needsPermissions(input): boolean // 是否需要权限
+  call(input, context): Result    // 执行函数
+  renderToolUseMessage(input): UI // UI 渲染
+  renderToolResultMessage(): UI   // 结果渲染
+}
+```
+
+### 核心工具分类
+
+**文件操作**: FileReadTool, FileEditTool, FileWriteTool, GlobTool, GrepTool
+**执行**: BashTool, PowerShellTool (Windows)
+**AI**: AgentTool (子 Agent), SkillTool (技能执行)
+**外部**: WebFetchTool, WebSearchTool
+**MCP**: MCPTool, ListMcpResourcesTool, ReadMcpResourceTool
+**规划**: EnterPlanModeTool, ExitPlanModeV2Tool
+**任务**: TaskCreateTool, TaskGetTool, TaskUpdateTool, TaskListTool, TaskStopTool
+**团队**: TeamCreateTool, TeamDeleteTool, SendMessageTool
+**其他**: TodoWriteTool, BriefTool, AskUserQuestionTool, ConfigTool
+
+### 工具执行流程
+
+```
+1. QueryEngine 产出 ToolUseBlock
+2. useCanUseTool hook → 权限检查
+3. 工具 handler 执行
+4. 结果 → ToolResultBlock → 回到 QueryEngine
+```
+
+### 权限系统
+
+`ToolPermissionContext` 定义权限模式：
+- `default` — 每次询问用户
+- `plan` — 只读，编辑需批准
+- `bypassPermissions` — 跳过所有检查（危险）
+- `auto` — 基于分类器自动决策
+
+权限规则通过 `PermissionRule` 配置，支持 allow/deny 规则匹配。
+
+---
+
+## 6. 命令系统 (commands/, 80+ 命令)
+
+### 命令类型
+
+- **`prompt` 型** — 扩展为文本发送给 LLM（如 `/commit`）
+- **`local` 型** — 本地执行并显示结果（如 `/cost`）
+- **`local-jsx` 型** — 渲染 JSX UI（如 `/config`）
+
+### 命令来源
+
+1. **内置命令** — `commands.ts` 中的 `COMMANDS()` (memoize)
+2. **技能命令** — `skills/` 目录中的 `.md` 文件
+3. **插件命令** — 插件注册的命令
+4. **Bundled 技能** — `skills/bundled/` 中的内置技能
+5. **MCP 命令** — MCP 服务器提供的 prompt 资源
+
+### 加载优先级
+
+```
+Bundled Skills → Plugin Skills → Skill Dir → Workflows → Plugin Commands → Built-in
+```
+
+---
+
+## 7. 服务层 (services/)
+
+### 核心服务
+
+| 服务 | 职责 |
+|------|------|
+| `api/` | Anthropic API 客户端、使用量跟踪、bootstrap |
+| `mcp/` | MCP 协议：服务器连接、工具发现、认证 |
+| `oauth/` | OAuth 2.0 认证流程 |
+| `lsp/` | LSP 语言服务器管理 |
+| `analytics/` | GrowthBook 特性开关 + 遥测 |
+| `compact/` | 上下文压缩（microcompact、auto-compact） |
+| `plugins/` | 插件安装、加载、版本管理 |
+| `extractMemories/` | 自动记忆提取 |
+| `tokenEstimation.ts` | Token 计数估算 |
+| `teamMemorySync/` | 团队记忆同步 |
+| `tips/` | 提示系统 |
+| `policyLimits/` | 组织策略限制 |
+
+---
+
+## 8. Bridge / 远程系统 (bridge/, remote/, server/)
+
+### Bridge (IDE 集成)
+
+双向通信层，连接 VS Code / JetBrains 扩展与 CLI。
+
+```
+IDE Extension ←── JSON-RPC ──→ Bridge Manager ←── Session ──→ REPL
+                   (ws/stdio)                     (权限桥接)
+```
+
+关键组件：
+- `bridgeMain.ts` — 桥接主循环
+- `bridgeMessaging.ts` — 消息协议
+- `bridgePermissionCallbacks.ts` — 权限回调代理
+- `replBridge.ts` — REPL 会话桥接
+- `sessionRunner.ts` — 会话执行管理
+- `trustedDevice.ts` — 可信设备认证
+
+### Remote Control
+
+用户从 claude.ai/web/mobile 控制本地会话：
+- `bridge/bridgeMain.ts` — 服务器连接
+- `remote/RemoteSessionManager.ts` — 远程会话管理
+- `remote/SessionsWebSocket.ts` — WebSocket 连接
+
+### Server 模式
+
+独立的 HTTP 服务器模式（`server/`），支持多会话并发。
+
+---
+
+## 9. Ink 渲染器 (ink/, 96 个文件)
+
+**自定义的 React 终端渲染器**，不是直接使用 npm ink 包，而是 fork 并深度定制。
+
+核心模块：
+- `reconciler.ts` — React reconciler 实现
+- `renderer.ts` — 终端 ANSI 输出渲染
+- `layout/` — Yoga 布局引擎集成
+- `events/` — 键盘/鼠标/终端事件系统
+- `screen.ts` — 屏幕管理
+- `selection.ts` — 文本选择
+- `searchHighlight.ts` — 搜索高亮
+- `termio/` — 终端 I/O 解析（ANSI/CSI/OSC/SGR）
+
+---
+
+## 10. 钩子系统 (hooks/)
+
+### 工具权限钩子
+
+```
+toolPermission/
+├── PermissionContext.ts           — 权限上下文
+├── handlers/
+│   ├── interactiveHandler.ts      — 交互模式处理器
+│   ├── coordinatorHandler.ts      — 协调器模式处理器
+│   └── swarmWorkerHandler.ts      — Swarm 工作器处理器
+└── permissionLogging.ts           — 权限日志
+```
+
+### 通知钩子
+
+`hooks/notifs/` — 16 个通知钩子，处理各种状态通知（模型迁移、速率限制、IDE 状态等）。
+
+### 关键 hooks
+
+| Hook | 职责 |
+|------|------|
+| `useReplBridge.tsx` | 远程控制桥接 |
+| `useCanUseTool.tsx` | 工具权限检查 |
+| `useGlobalKeybindings.tsx` | 全局键盘快捷键 |
+| `useVoice.ts` / `useVoiceIntegration.tsx` | 语音输入 |
+| `useTasksV2.ts` | 任务管理 |
+| `useSwarmInitialization.ts` | Swarm 团队初始化 |
+| `useMergedTools.ts` | 工具池合并 (内置 + MCP) |
+| `useMergedCommands.ts` | 命令池合并 |
+| `useSettings.ts` | 设置管理 |
+
+---
+
+## 11. 插件系统 (plugins/)
+
+### 架构
+
+```
+plugins/
+├── builtinPlugins.ts      — 内置插件列表
+├── bundled/
+│   └── index.ts           — 捆绑插件初始化
+utils/plugins/
+├── pluginLoader.ts        — 插件加载器
+├── installedPluginsManager.ts — 已安装插件管理
+├── marketplaceManager.ts  — 市场管理
+├── validatePlugin.ts      — 插件验证
+├── loadPluginCommands.ts  — 加载插件命令
+├── loadPluginHooks.ts     — 加载插件钩子
+├── loadPluginAgents.ts    — 加载插件 Agent
+└── loadPluginOutputStyles.ts — 加载输出样式
+```
+
+插件可以提供：命令、工具、钩子、Agent 定义、输出样式。
+
+---
+
+## 12. 配置系统
+
+### 多层级配置
+
+```
+1. 远程管理设置 (enterprise MDM)
+2. 策略设置 (organization policy)
+3. 用户设置 (~/.claude/settings.json)
+4. 项目设置 (.claude/settings.json)
+5. 本地设置 (.claude/settings.local.json)
+6. CLI 标志 (--model, --permission-mode 等)
+7. 环境变量 (ANTHROPIC_API_KEY, CLAUDE_CODE_* 等)
+```
+
+### 设置验证
+
+`utils/settings/validation.ts` — Zod schema 验证，支持类型检查和错误报告。
+
+### 迁移系统
+
+`migrations/` — 11 个版本迁移脚本，按序号执行（模型名称迁移、配置迁移等）。
+
+---
+
+## 13. 记忆系统 (memdir/)
+
+```
+memdir/
+├── memdir.ts             — 记忆目录操作
+├── paths.ts              — 路径解析
+├── memoryScan.ts         — 记忆扫描
+├── memoryAge.ts          — 记忆年龄管理
+├── memoryTypes.ts        — 类型定义
+├── findRelevantMemories.ts — 相关记忆查找
+├── teamMemPaths.ts       — 团队记忆路径
+└── teamMemPrompts.ts     — 团队记忆提示
+```
+
+记忆存储在 `~/.claude/memory/` 目录，自动从对话中提取。
+
+---
+
+## 14. 性能优化
+
+### 启动优化
+
+1. **并行子进程**：MDM 读取 + Keychain 预取 + 导入并行 (~135ms)
+2. **延迟加载**：重型模块动态导入（OpenTelemetry, gRPC, print.ts）
+3. **Feature Flag DCE**：未启用的功能在构建时完全裁剪
+4. **Memoize**：`getCommands()`, `getTools()`, `getSkills()` 等结果缓存
+5. **预连接**：API 预连接在用户输入前完成
+
+### 运行时优化
+
+1. **Token 预算**：上下文压缩触发管理
+2. **文件历史快照**：高效的文件变更追踪
+3. **虚拟滚动**：`VirtualMessageList` 支持大量消息
+4. **流式渲染**：增量 ANSI 输出
+
+---
+
+## 15. 关键数据流总结
+
+```
+用户输入
+  │
+  ├→ /command → processSlashCommand → 命令执行 → 可能触发 query()
+  │
+  └→ 文本输入 → processUserInput
+       │
+       ├→ processBashCommand (以 ! 开头)
+       └→ processTextPrompt
+            │
+            └→ QueryEngine.query()
+                 │
+                 ├→ 构建 system prompt (fetchSystemPromptParts + buildEffectiveSystemPrompt)
+                 ├→ 构建 messages (对话历史)
+                 ├→ 构建 tools (getTools + MCP tools)
+                 │
+                 ├→ API 调用 (Anthropic SDK, streaming)
+                 │
+                 └→ 循环处理响应:
+                      │
+                      ├→ text block → 显示消息
+                      ├→ thinking block → 显示思考过程
+                      └→ tool_use block → 权限检查 → 执行 → 结果回传 API
+```
+
+---
+
+## 附录：详细模块文档
+
+- [Tools 详细分析](./ARCHITECTURE-TOOLS.md)
+- [Services 详细分析](./ARCHITECTURE-SERVICES.md)
+- [Components 详细分析](./ARCHITECTURE-COMPONENTS.md)
+- [Bridge/Remote 详细分析](./ARCHITECTURE-BRIDGE-REMOTE.md)
+- [Utils 详细分析](./ARCHITECTURE-UTILS.md)
+- [Commands/Skills/Plugins 详细分析](./ARCHITECTURE-COMMANDS.md)