free-code-dotnet/docs/free-code 项目结构完整分析报告.md

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