# free-code 项目结构完整分析报告

## 一、项目概览

| 项目 | 详情 |
|---|---|
| **名称** | free-code (Claude Code 的开源重建版本) |
| **版本** | 2.1.87 |
| **来源** | Anthropic Claude Code CLI 的源码快照（2026-03-31 npm 分发包 source map 暴露后重建） |
| **运行时** | Bun >= 1.3.11 |
| **语言** | TypeScript (ESNext, JSX: react-jsx) |
| **总代码量** | ~1,997 个 TS/TSX 文件，共 ~512,834 行代码 |
| **核心框架** | React 19 + Ink 6 (终端 UI) |

### 三大修改方向

1. **遥测移除** — 所有 OpenTelemetry/gRPC、GrowthBook 分析、Sentry 报告等外发遥测全部替换为空实现（stub）
2. **安全提示护栏移除** — 移除了 Anthropic 注入的额外限制性系统提示
3. **实验性功能解锁** — 88 个 feature flag 中 54 个可编译通过并启用

---

## 二、目录结构与代码量

| 目录 | 文件数 | 代码行数 | 职责 |
|---|---|---|---|
| `../src/utils/` | 577 | 178,924 | 工具函数（模型管理、认证、设置、权限等） |
| `../src/components/` | 400 | 81,808 | Ink/React 终端 UI 组件 |
| `../src/services/` | 147 | 54,351 | API 客户端、OAuth、MCP、分析（已 stub） |
| `../src/tools/` | 210 | 51,068 | 40+ Agent 工具实现 |
| `../src/commands/` | 218 | 26,526 | 70+ 斜杠命令 |
| `../src/ink/` | 98 | 19,844 | Ink 框架内部（终端渲染引擎） |
| `../src/hooks/` | 104 | 19,205 | React hooks |
| `../src/bridge/` | 32 | 12,614 | IDE 远程控制桥接 |
| `../src/cli/` | 21 | 12,408 | CLI 参数解析和命令分发 |
| `../src/screens/` | 3 | 5,981 | 主界面 REPL |
| `../src/entrypoints/` | 11 | 4,162 | 入口点 |
| `../src/skills/` | 50 | 4,092 | 技能系统 |
| `../src/native-ts/` | 4 | 4,081 | 原生模块绑定 |
| `../src/types/` | 12 | 3,468 | 类型定义 |
| `../src/tasks/` | 14 | 3,288 | 后台任务管理 |
| `../src/keybindings/` | 14 | 3,159 | 快捷键配置 |
| `../src/constants/` | 22 | 2,725 | 常量定义 |
| 其他 (18 个目录) | — | — | vim、状态、迁移、MCP 等 |

### 完整目录列表

```
../src/
  assistant/          # 助手会话管理
  bootstrap/          # 启动引导
  bridge/             # IDE 远程控制桥接（32 文件）
  buddy/              # Buddy 功能
  cli/                # CLI 参数解析和快速路径分发（21 文件）
  commands/           # 70+ 斜杠命令实现（218 文件）
  components/         # Ink/React 终端 UI 组件（400 文件）
  constants/          # 常量定义（22 文件）
  context/            # React 上下文
  coordinator/        # 协调器模式
  daemon/             # 后台守护进程
  entrypoints/        # 入口点（11 文件）
  environment-runner/ # BYOC 环境运行器
  hooks/              # React hooks（104 文件）
  ink/                # Ink 终端渲染引擎（98 文件）
  jobs/               # 作业系统
  keybindings/        # 快捷键配置（14 文件）
  memdir/             # 记忆目录管理
  migrations/         # 数据迁移（11 文件）
  moreright/          # 扩展权限
  native-ts/          # 原生 TypeScript 模块（4 文件）
  outputStyles/       # 输出样式
  plugins/            # 插件系统（2 文件）
  proactive/          # 主动任务
  query/              # 查询管道（4 文件）
  remote/             # 远程会话管理（4 文件）
  schemas/            # JSON Schema
  screens/            # 主界面屏幕（3 文件）
  self-hosted-runner/ # 自托管运行器
  server/             # 服务器模式（11 文件）
  services/           # 服务层（147 文件）
  skills/             # 技能系统（50 文件）
  ssh/                # SSH 远程会话
  state/              # 应用状态管理（6 文件）
  tasks/              # 后台任务类型（14 文件）
  tools/              # Agent 工具实现（210 文件）
  types/              # 类型定义（12 文件）
  upstreamproxy/      # 上游代理
  utils/              # 工具函数（577 文件）
  vendor/             # 第三方内联代码
  vim/                # Vim 编辑模式（5 文件）
  voice/              # 语音输入
```

---

## 三、核心架构

### 3.1 启动流程

```
cli.tsx (快速路径分发)
  ├─ --version            → 直接输出，零模块加载
  ├─ --dump-system-prompt → 转储系统提示（feature-gated）
  ├─ --computer-use-mcp   → Chrome/Computer Use 模式
  ├─ --daemon-worker      → 后台守护进程
  ├─ remote-control       → 远程控制桥接
  └─ 默认交互模式         → main.tsx
                             ├─ 并行初始化（MDM、Keychain 预取）
                             ├─ Commander.js CLI 解析
                             ├─ 插件/技能加载
                             ├─ MCP 服务器初始化
                             └─ REPL.tsx (主 UI)
```

**入口文件详解：**

- **../src/entrypoints/cli.tsx** — 主入口，实现零导入快速路径优化
  - 所有导入都是动态的，以最小化模块评估
  - 特殊模式处理：Chrome 集成、daemon、bridge、后台会话、模板任务等
  - 环境特定优化（CCR 容器分配 8GB 堆内存）

- **../src/main.tsx** — 完整初始化流程
  - 带性能分析检查点的重型初始化
  - 并行启动优化（MDM 原始读取、Keychain 预取）
  - Commander.js CLI 设置
  - 会话管理和恢复
  - 插件/技能初始化
  - MCP 服务器管理
  - 分析和遥测设置

### 3.2 查询引擎 (`../src/QueryEngine.ts`)

`QueryEngine` 是整个 LLM 交互的核心：

- **异步生成器模式** — `submitMessage()` 以 async generator 流式输出 SDK 消息
- **系统提示组装** — 整合自定义提示、记忆机制、思考配置
- **权限管理** — `canUseTool()` 包装，追踪拒绝情况
- **对话循环** — 多轮对话，带 budget/turn 限制
- **会话持久化** — API 响应前保存会话，防崩溃丢数据
- **Snip-boundary 回放** — 长会话的内存管理
- **结构化输出执行** — 带重试限制
- **错误追踪** — 基于 watermark 的 turn 范围界定

**查询管道：**

```
User Input → processUserInput() → QueryEngine.submitMessage()
                                        ↓
                                  System Prompt Assembly
                                        ↓
                                  Permission Checking
                                        ↓
                                  LLM API Call (query.ts)
                                        ↓
                                  Stream Response → SDK Messages
```

### 3.3 工具注册 (`../src/tools.ts`)

`getAllBaseTools()` 注册 80+ 工具，通过以下方式过滤：
- Feature flag 条件编译
- 权限上下文过滤
- 模式过滤（SIMPLE/REPL/普通）
- 工具预设配置

关键函数：
- `getAllBaseTools()` — 所有工具的真实来源
- `getTools()` — 按权限上下文和模式过滤
- `assembleToolPool()` — 组合内置 + MCP 工具，去重
- 稳定排序以确保 prompt-cache 效率

### 3.4 命令注册 (`../src/commands.ts`)

`getCommands()` 加载 ~150 个命令，来源包括：
- 内置命令
- Bundled skills
- 插件 skills
- MCP 命令
- Workflow 命令

关键特性：
- 通过 lodash memoization 实现延迟求值
- 多源命令组合
- 技能缓存与粒度失效
- `REMOTE_SAFE_COMMANDS` / `BRIDGE_SAFE_COMMANDS` 安全过滤
- `meetsAvailabilityRequirement()` 基于认证/提供商的过滤

### 3.5 REPL 屏幕 (`../src/screens/REPL.tsx`)

- 基于 React 的 Ink TUI，支持虚拟滚动
- 基于消息的状态管理，不可变更新
- 复杂的权限处理（auto-mode、sandbox、swarm）
- 实时流式 LLM 响应
- 多模式输入处理（normal、vim、search）
- 成本追踪和预算执行
- 后台任务管理
- Swarm/Teammate 多 Agent 协调

---

## 四、五大 API 提供商支持

| 提供商 | 环境变量 | 认证方式 |
|---|---|---|
| **Anthropic（默认）** | — | `ANTHROPIC_API_KEY` 或 OAuth |
| **OpenAI Codex** | `CLAUDE_CODE_USE_OPENAI=1` | OpenAI OAuth |
| **AWS Bedrock** | `CLAUDE_CODE_USE_BEDROCK=1` | AWS credentials |
| **Google Vertex AI** | `CLAUDE_CODE_USE_VERTEX=1` | gcloud ADC |
| **Anthropic Foundry** | `CLAUDE_CODE_USE_FOUNDRY=1` | API Key |

**API 客户端架构：**

`../src/services/api/client.ts` 是统一的 API 客户端工厂，根据配置自动路由到不同提供商。

**Codex 适配器：**

`../src/services/api/codex-fetch-adapter.ts` 负责将 Anthropic 消息格式转换为 OpenAI Codex 格式：
- Anthropic `base64` 图像 schema 映射到 Codex `input_image` 载荷
- `tool_result` 项路由为顶层 `function_call_output` 对象
- 剥离 Anthropic 专有的 `cache_control` 注解
- 拦截 Codex `response.reasoning.delta` SSE 帧并包装为 Anthropic `<thinking>` 事件
- 绑定 `response.completed` 事件以追踪 token 使用量

### 支持的模型

**Anthropic (Direct API) — 默认：**

| Model | ID |
|---|---|
| Claude Opus 4.6 | `claude-opus-4-6` |
| Claude Sonnet 4.6 | `claude-sonnet-4-6` |
| Claude Haiku 4.5 | `claude-haiku-4-5` |

**OpenAI Codex：**

| Model | ID |
|---|---|
| GPT-5.3 Codex (recommended) | `gpt-5.3-codex` |
| GPT-5.4 | `gpt-5.4` |
| GPT-5.4 Mini | `gpt-5.4-mini` |

### 环境变量参考

| Variable | Purpose |
|---|---|
| `ANTHROPIC_API_KEY` | Anthropic API key |
| `ANTHROPIC_AUTH_TOKEN` | Auth token (alternative) |
| `ANTHROPIC_MODEL` | Override default model |
| `ANTHROPIC_BASE_URL` | Custom API endpoint |
| `ANTHROPIC_DEFAULT_OPUS_MODEL` | Custom Opus model ID |
| `ANTHROPIC_DEFAULT_SONNET_MODEL` | Custom Sonnet model ID |
| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | Custom Haiku model ID |
| `CLAUDE_CODE_OAUTH_TOKEN` | OAuth token via env |
| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | API key helper cache TTL |
| `AWS_REGION` / `AWS_DEFAULT_REGION` | AWS region for Bedrock |
| `ANTHROPIC_BEDROCK_BASE_URL` | Custom Bedrock endpoint |
| `ANTHROPIC_FOUNDRY_API_KEY` | Foundry API key |

---

## 五、Feature Flag 系统

### 构建系统 (`scripts/build.ts`)

- 使用 `bun:bundle` 的 `feature()` 宏实现编译时死代码消除
- Bun 编译带字节码生成
- 宏系统提供构建时常量（VERSION、BUILD_TIME 等）

### 构建变体

| 命令 | 输出 | Feature Flags | 描述 |
|---|---|---|---|
| `bun run build` | `./cli` | 仅 VOICE_MODE | 生产构建 |
| `bun run build:dev` | `./cli-dev` | 仅 VOICE_MODE | 开发版 |
| `bun run build:dev:full` | `./cli-dev` | 全部 54 个实验性 flag | 完整解锁构建 |
| `bun run compile` | `./dist/cli` | 仅 VOICE_MODE | 替代输出路径 |
| 自定义 | 自定义 | 指定 flags | `bun run ./scripts/build.ts --feature=ULTRAPLAN --feature=ULTRATHINK` |

### 54 个可工作 Feature Flags

#### 交互与 UI（14 个）

| Flag | 描述 |
|---|---|
| `AWAY_SUMMARY` | 离开键盘摘要行为 |
| `HISTORY_PICKER` | 交互式提示历史选择器 |
| `HOOK_PROMPTS` | 将 prompt/request 文本传入 hook 执行流程 |
| `KAIROS_BRIEF` | 简短转录布局和 BriefTool UX |
| `KAIROS_CHANNELS` | 频道通知和回调 |
| `LODESTONE` | 深度链接/协议注册相关流程 |
| `MESSAGE_ACTIONS` | 消息操作入口点 |
| `NEW_INIT` | 新版 `/init` 决策路径 |
| `QUICK_SEARCH` | 提示快速搜索 |
| `SHOT_STATS` | 额外的 shot-distribution 统计视图 |
| `TOKEN_BUDGET` | Token 预算追踪和警告 UI |
| `ULTRAPLAN` | 远程多 Agent 规划（Opus 级别） |
| `ULTRATHINK` | 深度思考模式 |
| `VOICE_MODE` | 语音切换、听写、语音通知和 UI |

#### Agent/记忆/规划（10 个）

| Flag | 描述 |
|---|---|
| `AGENT_MEMORY_SNAPSHOT` | 存储 Agent 记忆快照状态 |
| `AGENT_TRIGGERS` | 本地 cron/触发器工具 |
| `AGENT_TRIGGERS_REMOTE` | 远程触发器工具路径 |
| `BUILTIN_EXPLORE_PLAN_AGENTS` | 内置 explore/plan agent 预设 |
| `CACHED_MICROCOMPACT` | 通过查询和 API 流程缓存的微压缩状态 |
| `COMPACTION_REMINDERS` | 压缩和附件流程的提醒 |
| `EXTRACT_MEMORIES` | 查询后记忆提取 hooks |
| `PROMPT_CACHE_BREAK_DETECTION` | 压缩/查询流程中的缓存中断检测 |
| `TEAMMEM` | 团队记忆文件和 watcher hooks |
| `VERIFICATION_AGENT` | 验证 Agent 指导 |

#### 工具/权限/远程（13 个）

| Flag | 描述 |
|---|---|
| `BASH_CLASSIFIER` | 分类器辅助的 bash 权限决策 |
| `BRIDGE_MODE` | 远程控制 / REPL 桥接命令 |
| `CCR_AUTO_CONNECT` | CCR 自动连接默认路径 |
| `CCR_MIRROR` | 仅出站 CCR 镜像会话 |
| `CCR_REMOTE_SETUP` | 远程设置命令路径 |
| `CHICAGO_MCP` | Computer-use MCP 集成 |
| `CONNECTOR_TEXT` | 连接器文本块处理 |
| `MCP_RICH_OUTPUT` | 更丰富的 MCP UI 渲染 |
| `NATIVE_CLIPBOARD_IMAGE` | 原生 macOS 剪贴板图像快速路径 |
| `POWERSHELL_AUTO_MODE` | PowerShell 自动模式权限处理 |
| `TREE_SITTER_BASH` | tree-sitter bash 解析器后端 |
| `TREE_SITTER_BASH_SHADOW` | tree-sitter bash 影子发布路径 |
| `UNATTENDED_RETRY` | API 重试流程中的无人值守重试 |

#### 支撑性 Flag（17 个）

| Flag | 描述 |
|---|---|
| `ABLATION_BASELINE` | CLI 消融/基线入口开关 |
| `ALLOW_TEST_VERSIONS` | 允许原生安装程序中的测试版本 |
| `ANTI_DISTILLATION_CC` | 添加反蒸馏请求元数据 |
| `BREAK_CACHE_COMMAND` | 注入 break-cache 命令路径 |
| `COWORKER_TYPE_TELEMETRY` | 添加协作者类型遥测字段 |
| `DOWNLOAD_USER_SETTINGS` | 启用设置同步拉取路径 |
| `DUMP_SYSTEM_PROMPT` | 启用系统提示转储路径 |
| `FILE_PERSISTENCE` | 启用文件持久化管道 |
| `HARD_FAIL` | 启用更严格的失败/日志行为 |
| `IS_LIBC_GLIBC` | 强制 glibc 环境检测 |
| `IS_LIBC_MUSL` | 强制 musl 环境检测 |
| `NATIVE_CLIENT_ATTESTATION` | 添加原生证明标记文本 |
| `PERFETTO_TRACING` | 启用 perfetto 追踪 hooks |
| `SKILL_IMPROVEMENT` | 启用技能改进 hooks |
| `SKIP_DETECTION_WHEN_AUTOUPDATES_DISABLED` | 自动更新禁用时跳过更新检测 |
| `SLOW_OPERATION_LOGGING` | 启用慢操作日志 |
| `UPLOAD_USER_SETTINGS` | 启用设置同步推送路径 |

### 运行时注意事项

部分 flag 虽然编译通过但有运行时限制：

- `VOICE_MODE` — 需要 claude.ai OAuth 和本地录制后端
- `NATIVE_CLIPBOARD_IMAGE` — 仅在 macOS 且存在 `image-processor-napi` 时加速
- `BRIDGE_MODE`、`CCR_*` — 运行时需要 claude.ai OAuth + GrowthBook 权限检查
- `KAIROS_BRIEF`、`KAIROS_CHANNELS` — 仅暴露已存在的 brief/channel 特定接口
- `CHICAGO_MCP` — 运行时仍需 `@ant/computer-use-*` 外部包

### 34 个不可编译 Flag

#### 易修复（15 个）— 缺少单个文件或资产

| Flag | 缺失内容 |
|---|---|
| `AUTO_THEME` | `../src/utils/systemThemeWatcher.js`（OSC 11 watcher） |
| `BG_SESSIONS` | `../src/cli/bg.js` |
| `BUDDY` | `../src/commands/buddy/index.js` |
| `BUILDING_CLAUDE_APPS` | `../src/claude-api/csharp/claude-api.md`（文档资产） |
| `COMMIT_ATTRIBUTION` | `../src/utils/attributionHooks.js` |
| `FORK_SUBAGENT` | `../src/commands/fork/index.js` |
| `HISTORY_SNIP` | `../src/commands/force-snip.js` |
| `KAIROS_GITHUB_WEBHOOKS` | `../src/tools/SubscribePRTool/SubscribePRTool.js` |
| `KAIROS_PUSH_NOTIFICATION` | `../src/tools/PushNotificationTool/PushNotificationTool.js` |
| `MCP_SKILLS` | `../src/skills/mcpSkills.js` |
| `MEMORY_SHAPE_TELEMETRY` | `../src/memdir/memoryShapeTelemetry.js` |
| `OVERFLOW_TEST_TOOL` | `../src/tools/OverflowTestTool/OverflowTestTool.js` |
| `RUN_SKILL_GENERATOR` | `../src/runSkillGenerator.js` |
| `TEMPLATES` | `../src/cli/handlers/templateJobs.js` |
| `TORCH` | `../src/commands/torch.js` |
| `TRANSCRIPT_CLASSIFIER` | `../src/utils/permissions/yolo-classifier-prompts/auto_mode_system_prompt.txt` |

#### 中等修复（16 个）— 缺少较大子系统部分

| Flag | 缺失内容 |
|---|---|
| `BYOC_ENVIRONMENT_RUNNER` | `../src/environment-runner/main.js` |
| `CONTEXT_COLLAPSE` | `../src/tools/CtxInspectTool/CtxInspectTool.js` |
| `COORDINATOR_MODE` | `../src/coordinator/workerAgent.js` |
| `DAEMON` | `../src/daemon/workerRegistry.js` |
| `DIRECT_CONNECT` | `../src/server/parseConnectUrl.js` |
| `EXPERIMENTAL_SKILL_SEARCH` | `../src/services/skillSearch/localSearch.js` |
| `MONITOR_TOOL` | `../src/tools/MonitorTool/MonitorTool.js` |
| `REACTIVE_COMPACT` | `../src/services/compact/reactiveCompact.js` |
| `REVIEW_ARTIFACT` | `../src/hunter.js` |
| `SELF_HOSTED_RUNNER` | `../src/self-hosted-runner/main.js` |
| `SSH_REMOTE` | `../src/ssh/createSSHSession.js` |
| `TERMINAL_PANEL` | `../src/tools/TerminalCaptureTool/TerminalCaptureTool.js` |
| `UDS_INBOX` | `../src/utils/udsMessaging.js` |
| `WEB_BROWSER_TOOL` | `../src/tools/WebBrowserTool/WebBrowserTool.js` |
| `WORKFLOW_SCRIPTS` | `../src/commands/workflows/index.js` 及多个相关文件 |

#### 大型缺失（3 个）— 需要重建完整子系统

| Flag | 缺失内容 |
|---|---|
| `KAIROS` | `../src/assistant/index.js` 及大部分助手栈 |
| `KAIROS_DREAM` | `../src/dream.js` 及 dream-task 行为 |
| `PROACTIVE` | `../src/proactive/index.js` 及主动任务/工具栈 |

---

## 六、核心子系统详解

### 6.1 状态管理 (`../src/state/`)

自定义 Store 模式（非 Redux/Zustand）：

**核心文件：**

- **store.ts** — `getState()/setState()/subscribe()` 基础实现
  - 可选 `onChange` 回调用于状态变更追踪
  - Listener set 用于 React 风格订阅

- **AppStateStore.ts** — 450+ 行的类型定义，涵盖：
  - 设置和配置
  - 任务状态管理（tasks、agentNameRegistry）
  - MCP 状态（clients、tools、commands、resources）
  - 插件状态（enabled、disabled、errors、installation status）
  - 远程桥接状态（connection、session、polling）
  - UI 状态（expandedView、footerSelection、spinnerTip）
  - 权限上下文和模式
  - 文件历史和归属追踪
  - Tungsten (tmux) 集成状态
  - Computer Use (chicago MCP) 状态
  - Team/swarm 上下文和收件箱管理

- **AppState.tsx** — React 集成：
  - `AppStateProvider` 上下文组件
  - `useAppState(selector)` — 使用 `useSyncExternalStore` 的优化 hook
  - `useSetAppState()` — 非订阅 setter
  - `useAppStateStore()` — 直接 store 访问
  - `useAppStateMaybeOutsideOfProvider()` — 可选上下文的安全版本

- **selectors.ts** — 纯选择器函数：
  - `getViewedTeammateTask()` — 获取当前查看的 teammate
  - `getActiveAgentForInput()` — 确定输入路由（leader/viewed/named）

- **onChangeAppState.ts** — 状态变更副作用处理器：
  - 权限模式同步到 CCR/SDK
  - 模型设置持久化
  - 展开视图持久化
  - 设置变更时清除认证缓存

### 6.2 服务层 (`../src/services/`)

28 个主要服务区域：

#### API 客户端 (`../src/services/api/`)

- **client.ts** — 统一 API 客户端工厂，支持五大提供商
- **codex-fetch-adapter.ts** — Anthropic → OpenAI Codex 格式转换
- OAuth token 刷新、自定义 headers、CCH 签名、代理支持
- 错误处理、重试逻辑、使用量追踪

#### OAuth (`../src/services/oauth/`)

- **index.ts** — OAuthService 类，实现 OAuth 2.0 Authorization Code Flow + PKCE
- **client.ts** — OAuth 客户端操作（构建 auth URL、交换 code 为 token、获取 profile）
- **auth-code-listener.ts** — 本地 HTTP 服务器用于自动 OAuth 回调处理
- **crypto.ts** — PKCE code verifier/challenge 生成
- **codex-client.ts** — Codex 特定 OAuth 客户端

#### MCP 集成 (`../src/services/mcp/`)

- **client.ts** — MCP 客户端管理
- **types.ts** — MCP 服务器配置的全面类型定义（stdio、SSE、HTTP、WebSocket、SDK、IDE 特定）
- **config.ts** — MCP 配置管理
- **useManageMCPConnections.ts** — MCP 连接生命周期的 React hook
- **channelPermissions.ts** — MCP 频道权限处理（Telegram、iMessage 等）
- 支持 XAA（Cross-App Access）、elicitation 处理、资源管理

#### 分析 (`../src/services/analytics/`) — 已 STUB

- 所有函数都是空操作（logEvent、attachAnalyticsSink 等）
- 作为兼容性边界，使现有调用点保持不变而遥测被禁用
- 包括：datadog.ts、firstPartyEventLogger.ts、growthbook.ts、sink.ts

#### 其他主要服务

| 服务 | 职责 | 状态 |
|---|---|---|
| `compact/` | 上下文压缩（auto-compact、micro-compact、reactive compact） | 完整 |
| `tools/` | 工具执行编排（StreamingToolExecutor、toolOrchestration） | 完整 |
| `plugins/` | 插件操作和安装管理 | 完整 |
| `SessionMemory/` | 会话记忆持久化和检索 | 完整 |
| `skillSearch/` | 技能搜索，带远程状态管理 | 完整 |
| `remoteManagedSettings/` | 远程托管设置同步 | 完整 |
| `extractMemories/` | 从对话上下文中提取记忆 | 完整 |
| `lsp/` | Language Server Protocol 集成 | 完整 |
| `contextCollapse/` | 上下文窗口优化 | 完整 |
| `tips/` | 用户提示和指导系统 | 完整 |
| `voice.ts` | 语音集成（STT、keyterms、streaming） | 完整 |

### 6.3 IDE 桥接 (`../src/bridge/`)

远程控制架构：

1. 注册环境到后端（机器名、目录、分支、仓库 URL）
2. 轮询获取 work items（要执行的会话）
3. 为每个会话创建子进程
4. 管理会话生命周期（心跳、停止、归档）
5. 权限响应回传
6. 支持多种生成模式（单会话、worktree、同目录）

**核心文件：**

- **bridgeApi.ts** — Bridge API 客户端（环境注册/注销、工作轮询/确认、会话生命周期管理）
- **types.ts** — 全面的桥接类型定义（260+ 行）
- **bridgeConfig.ts** — 桥接认证/URL 解析
- **remoteBridgeCore.ts** — 远程桥接核心逻辑
- **replBridgeHandle.ts** — REPL 桥接句柄实现
- **replBridgeTransport.ts** — 桥接传输层
- **createSession.ts** — 会话创建逻辑
- **sessionRunner.ts** — 会话执行运行器
- **jwtUtils.ts** — JWT token 工具
- **peerSessions.ts** — 对等会话管理
- **trustedDevice.ts** — 受信任设备认证

### 6.4 任务系统 (`../src/tasks/`)

7 种任务类型：

| 任务类型 | 用途 |
|---|---|
| `LocalShellTask` | 后台 Bash 命令执行 |
| `LocalAgentTask` | 本地 Agent 子进程（自主工作） |
| `RemoteAgentTask` | 远程 CCR Agent（通过 CCR API 执行） |
| `InProcessTeammateTask` | 进程内 Teammate（共享主进程） |
| `LocalWorkflowTask` | 预定义工作流脚本 |
| `MonitorMcpTask` | MCP 资源变更监控 |
| `DreamTask` | 异步/Dream 任务 |

**任务管理特性：**
- 任务状态：pending → in_progress → completed（或 deleted）
- 后台任务：带 `isBackgrounded` 标志
- 任务依赖：`blocks` 和 `blockedBy` 关系
- 任务所有权：可分配给特定 Agent
- 团队任务列表：团队共享任务列表以协调工作

### 6.5 工具系统 (`../src/tools/`)

40+ 工具按功能分类：

#### 文件操作

| 工具 | 功能 |
|---|---|
| FileReadTool | 读取文件（支持图像、PDF、Jupyter notebook） |
| FileWriteTool | 写入文件（需先读取现有文件） |
| FileEditTool | 精确字符串替换（支持 replace_all） |
| GlobTool | 快速文件模式匹配 |
| GrepTool | 基于 ripgrep 的内容搜索 |
| NotebookEditTool | Jupyter notebook 单元格编辑 |
| SnipTool | 代码片段管理 |
| SendUserFileTool | 向用户发送文件 |

#### Shell 和系统

| 工具 | 功能 |
|---|---|
| BashTool | 执行 bash 命令（支持后台执行、超时、沙盒） |
| PowerShellTool | 执行 PowerShell 命令（Windows） |
| SleepTool | 等待指定时间 |
| TerminalCaptureTool | 终端捕获 |

#### 通信和规划

| 工具 | 功能 |
|---|---|
| AskUserQuestionTool | 向用户提问（支持多选、预览） |
| SendMessageTool | 向其他 Agent 发送消息 |
| EnterPlanModeTool | 进入规划模式 |
| ExitPlanModeTool | 退出规划模式 |
| BriefTool | 向用户发送消息（主通信通道） |

#### Web 和网络

| 工具 | 功能 |
|---|---|
| WebFetchTool | 获取 URL 内容（HTML → markdown，15 分钟缓存） |
| WebSearchTool | Web 搜索 |
| WebBrowserTool | Web 浏览器面板 |
| RemoteTriggerTool | 管理远程 Agent 触发器 |

#### MCP

| 工具 | 功能 |
|---|---|
| MCPTool | 通用 MCP 工具包装器 |
| ListMcpResourcesTool | 列出 MCP 服务器资源 |
| ReadMcpResourceTool | 读取 MCP 服务器资源 |
| McpAuthTool | MCP 认证处理 |

#### Agent 和团队

| 工具 | 功能 |
|---|---|
| AgentTool | 启动专门的 Agent 子进程 |
| TeamCreateTool | 创建 Agent 团队 |
| TeamDeleteTool | 删除 Agent 团队 |

#### 任务管理

| 工具 | 功能 |
|---|---|
| TaskCreateTool | 创建任务列表 |
| TaskUpdateTool | 更新任务 |
| TaskGetTool | 获取任务详情 |
| TaskListTool | 列出所有任务 |
| TaskStopTool | 停止后台任务 |
| TaskOutputTool | 查看后台任务输出 |

#### Git

| 工具 | 功能 |
|---|---|
| EnterWorktreeTool | 创建隔离的 git worktree |
| ExitWorktreeTool | 退出 worktree |

#### 调度

| 工具 | 功能 |
|---|---|
| CronCreateTool | 创建定时任务 |
| CronDeleteTool | 删除定时任务 |
| CronListTool | 列出定时任务 |

#### 配置和发现

| 工具 | 功能 |
|---|---|
| ConfigTool | 获取/设置配置 |
| ToolSearchTool | 获取延迟加载工具的 schema |
| DiscoverSkillsTool | 发现可用技能 |
| LSPTool | LSP 服务器交互（goToDefinition、findReferences 等） |

#### 验证

| 工具 | 功能 |
|---|---|
| VerifyPlanExecutionTool | 验证计划执行 |

**工具延迟加载：**
- 工具可被延迟加载（不包含在初始 prompt 中）以减少上下文
- 延迟加载的工具需要 ToolSearch 来获取 schema
- MCP 工具始终延迟加载
- 部分工具永不延迟（Agent、Brief when KAIROS enabled）

### 6.6 命令系统 (`../src/commands/`)

70+ 斜杠命令：

#### 配置和设置

| 命令 | 功能 |
|---|---|
| `/config` (别名: `/settings`) | 打开配置面板 |
| `/keybindings` | 打开/创建快捷键配置文件 |
| `/add-dir` | 添加新的工作目录 |
| `/memory` | 编辑记忆文件 |
| `/sandbox` | 切换沙盒模式 |
| `/vim` | 切换 Vim/普通编辑模式 |
| `/terminal-setup` | 安装 Shift+Enter 换行绑定 |
| `/color` | 设置提示栏颜色 |
| `/effort` | 设置模型努力级别 |
| `/model` | 更改模型设置 |
| `/fast` | 切换快速模式 |
| `/theme` | 更改主题 |

#### 任务和会话管理

| 命令 | 功能 |
|---|---|
| `/tasks` (别名: `/bashes`) | 列出和管理后台任务 |
| `/plan` | 启用规划模式或查看当前计划 |
| `/branch` (别名: `/fork`) | 在当前点创建对话分支 |
| `/resume` (别名: `/continue`) | 恢复之前的对话 |
| `/session` | 会话管理 |
| `/compact` | 清除对话历史但保留摘要 |
| `/exit` | 退出 CLI |
| `/btw` | 快速旁问（不打断主对话） |

#### 信息和诊断

| 命令 | 功能 |
|---|---|
| `/help` | 显示帮助信息 |
| `/context` | 可视化当前上下文使用情况 |
| `/cost` | 显示当前会话的总成本和时长 |
| `/usage` | 显示使用信息 |
| `/stats` | 显示统计信息 |
| `/doctor` | 诊断和验证安装 |
| `/status` | 显示状态信息 |
| `/statusline` | 状态栏管理 |
| `/release-notes` | 显示发行说明 |

#### 功能和集成

| 命令 | 功能 |
|---|---|
| `/ide` | 管理 IDE 集成 |
| `/agents` | 管理 Agent 配置 |
| `/skills` | 技能管理 |
| `/plugin` | 插件管理 |
| `/mcp` | MCP 管理 |
| `/voice` | 语音模式 |
| `/remote-control` (别名: `/rc`) | 远程控制会话 |
| `/chrome` | Chrome 集成 |

#### Git 和版本控制

| 命令 | 功能 |
|---|---|
| `/commit` | 创建 git 提交（技能） |
| `/commit-push-pr` | 提交、推送并创建 PR |
| `/diff` | 显示差异 |
| `/tag` | 标签管理 |

#### 账户和认证

| 命令 | 功能 |
|---|---|
| `/login` | 登录账户 |
| `/logout` | 登出账户 |
| `/upgrade` | 升级到 Max |
| `/permissions` | 管理权限 |
| `/hooks` | Hooks 管理 |
| `/init` | 初始化 Claude Code |

### 6.7 技能系统 (`../src/skills/`)

13+ 个内置技能：

| 技能 | 功能 |
|---|---|
| `/update-config` | 通过 settings.json 配置 hooks 和自动化行为 |
| `/simplify` | 审查代码质量（启动 3 个并行 Agent） |
| `/loop` | 定时循环执行命令 |
| `/verify` | 验证代码变更 |
| `/remember` | 审查自动记忆并提议提升到 CLAUDE.md |
| `/debug` | 调试技能 |
| `/keybindings` | 快捷键管理 |
| `/batch` | 批量操作 |
| `/stuck` | 获取解困帮助 |
| `/skillify` | 创建新技能 |
| `/claudeApi` | Claude API 文档和示例 |
| `/dream` | Dream 技能 |
| `/hunter` | 代码审查工件 |
| `/runSkillGenerator` | 运行技能生成器 |

**技能系统架构：**

- **注册** — `registerBundledSkill()` 在启动时注册技能
- **定义** — 技能包含 name、description、aliases、whenToUse、allowedTools、model、hooks
- **引用文件** — 首次调用时提取到磁盘
- **发现** — 技能出现在 Skill 工具提示中（bundled 技能永不截断）
- **调用** — 通过 Skill 工具或 `/skill-name` 斜杠命令

### 6.8 插件系统 (`../src/plugins/`)

- 内置插件格式：`{name}@builtin`
- 区别于市场插件：`{name}@{marketplace}`
- 可提供 skills、hooks、MCP servers
- 通过 `/plugin` UI 管理
- 用户设置控制启用状态（默认：`defaultEnabled ?? true`）

---

## 七、React Hooks (`../src/hooks/`)

104 个 React hooks 按类别：

### 数据获取和状态

- `useTasksV2`、`useTaskListWatcher` — 任务管理
- `useSettings`、`useSettingsChange` — 设置同步
- `useApiKeyVerification` — API key 验证
- `useInboxPoller` — 消息收件箱轮询
- `useDiffData` — Diff 数据计算

### UI/交互

- `useTypeahead` — 输入自动完成
- `useSearchInput` — 搜索功能
- `useArrowKeyHistory` — 命令历史导航
- `useVirtualScroll` — 虚拟滚动
- `usePasteHandler` — 剪贴板粘贴处理
- `useBlink` — 光标闪烁效果

### IDE 集成

- `useIdeLogging` — IDE 日志
- `useDiffInIDE` — IDE diff 查看
- `useIdeAtMentioned` — IDE @mention 处理
- `useLspPluginRecommendation` — LSP 插件建议

### 功能特定

- `useVoice`、`useVoiceIntegration`、`useVoiceEnabled` — 语音功能
- `useDirectConnect` — 直接连接模式
- `useSSHSession` — SSH 会话管理
- `useBackgroundTaskNavigation` — 后台任务路由
- `useSwarmInitialization`、`useSwarmPermissionPoller` — Agent swarm 管理

### 工具

- `useTerminalSize` — 终端尺寸
- `useMemoryUsage` — 内存监控
- `useScheduledTasks` — 任务调度
- `useDynamicConfig` — 动态配置加载

---

## 八、UI 组件 (`../src/components/`)

27 个主要组件目录：

### 核心 UI

- **ui/** — 基础 UI 组件（按钮、输入框等）
- **design-system/** — 设计系统组件

### 功能组件

- **tasks/** — 任务列表和管理 UI
- **messages/** — 消息显示和渲染
- **permissions/** — 权限请求对话框
- **mcp/** — MCP 服务器管理 UI
- **diff/** — 代码差异查看
- **shell/** — Shell/输出显示
- **memory/** — 记忆管理 UI
- **sandbox/** — 沙盒权限
- **agents/** — Agent 创建和管理

### 设置和配置

- **Settings/** — 设置面板
- **ManagedSettingsSecurityDialog/** — 托管设置安全对话框

### 集成

- **groove/** — Grove 集成
- **teams/** — 团队协作
- **skills/** — 技能管理
- **wizard/** — 引导向导
- **LspRecommendation/** — LSP 插件建议

### 专用

- **TrustDialog/** — 信任/安全对话框
- **FeedbackSurvey/** — 用户反馈
- **Spinner/** — 加载旋转器
- **PromptInput/** — 输入提示组件
- **HelpV2/** — 帮助系统
- **LogoV2/** — Logo 组件

---

## 九、构建与依赖

### 运行时依赖（关键）

| 类别 | 包 |
|---|---|
| **AI SDK** | @anthropic-ai/sdk, @anthropic-ai/bedrock-sdk, @anthropic-ai/vertex-sdk, @anthropic-ai/foundry-sdk |
| **Agent SDK** | @anthropic-ai/claude-agent-sdk |
| **MCP** | @modelcontextprotocol/sdk, @anthropic-ai/mcpb |
| **终端 UI** | react, ink, chalk, cli-highlight |
| **搜索** | fuse.js, picomatch |
| **协议** | vscode-jsonrpc, vscode-languageserver-protocol |
| **可观测性** | @opentelemetry/* (完整 suite，但遥测已 stub) |
| **验证** | zod, ajv |
| **图片** | sharp |
| **网络** | axios, undici, ws, https-proxy-agent |
| **CLI** | @commander-js/extra-typings |
| **其他** | diff, marked, yaml, lodash-es, lru-cache, semver, chokidar |

### 开发依赖

- `@types/bun` — Bun 类型定义
- `typescript ^6.0.2` — TypeScript 编译器

---

## 十、Git 状态

当前仓库只有 **1 个 commit**：

```
a4deee0 因无法 fork，手动迁移代码 source: https://github.com/paoloanzn/free-code
```

**76 个未跟踪文件/目录**，包括许多新增的子系统文件（assistant、buddy、fork、workflows、daemon、ssh 等），对应于之前不可编译但已被手动补充代码的 feature flags。

**3 个已修改文件**：`bun.lock`、`package.json`、`scripts/build.ts`。

---

## 十一、架构亮点与设计模式

1. **编译时 Feature Flag** — `bun:bundle` 的 `feature()` 宏实现真正的死代码消除，非运行时 if/else
2. **异步生成器查询管线** — QueryEngine 用 async generator 实现流式 LLM 响应
3. **多 Agent 协作** — Agent Swarm 支持 Team 创建、共享任务列表、跨会话消息传递
4. **工具延迟加载** — 大型工具集通过 ToolSearch 按需加载 schema，优化 context window
5. **多提供商 API 抽象** — 统一接口适配 5 个 API 提供商
6. **自定义状态管理** — 轻量 store + useSyncExternalStore，非 Redux
7. **IDE 桥接轮询架构** — 远程控制通过环境注册 + work polling 实现
8. **上下文压缩** — 多级压缩策略（auto-compact、micro-compact、reactive-compact）
9. **MCP 协议完整实现** — 支持 stdio、SSE、HTTP、WebSocket、SDK 等多种传输方式
10. **沙盒安全** — 文件/网络访问控制，支持 macOS/Linux 平台

---

## 十二、工具函数层 (`../src/utils/`)

最大的源码目录（577 文件，178,924 行）：

### 模型管理 (`../src/utils/model/`)

- **model.ts** — 核心模型选择逻辑、别名、规范化
- **modelStrings.ts** — 模型名称常量和映射
- **providers.ts** — API 提供商检测
- **modelCapabilities.ts** — 模型能力标志
- **modelAllowlist.ts** — 模型访问控制
- **validateModel.ts** — 模型验证
- **modelCost.ts** — 模型定价信息
- **check1mAccess.ts** — 1M 上下文访问检查

### 设置管理 (`../src/utils/settings/`)

- **settings.ts** — 设置加载和持久化
- **validation.ts** — 设置验证
- **types.ts** — 设置类型定义
- **applySettingsChange.ts** — 设置变更应用
- **permissionValidation.ts** — 权限验证
- **mdm/** — 移动设备管理集成

### 其他重要工具模块

- **auth.ts** — 认证和凭证管理（67KB，1800+ 行）
- **attachments.ts** — 附件处理（127KB）
- **analyzeContext.ts** — 上下文分析（43KB）
- **ansiToPng.ts** — ANSI 转 PNG（215KB）
- **bash/** — Bash 命令执行
- **permissions/** — 权限系统
- **config.ts** — 配置管理
- **todo/** — TODO 列表管理
- **commitAttribution.ts** — Git 提交归属

---

*报告生成日期：2026-04-05*