1. Claude Code 源码深度解析：从编译开关到隐藏功能

最近在研究 Claude Code 这个项目，它是一个基于 TypeScript 开发的命令行 AI 助手，官方版本功能已经很强大了，但通过分析其源码，我发现了一个完全不同的世界。这个项目内部隐藏了大量未公开的功能，这些功能通过编译开关、用户类型和远程配置层层控制，外部用户拿到的其实是一个“阉割版”。今天我就来详细拆解一下，这些隐藏功能到底是什么，以及它们背后的设计逻辑。

Claude Code 的核心是一个本地运行的 AI 助手，你可以通过命令行与它交互，让它帮你写代码、执行命令、分析文件。但它的源码结构揭示了一个更宏大的愿景：它不仅仅是一个对话工具，而是一个可以持久运行、多代理协作、甚至拥有虚拟伙伴的智能体平台。这些高级功能在构建时就被 feature() 函数包裹，只有特定的构建配置才能启用。对于开发者来说，理解这套机制不仅能满足好奇心，更能让我们思考大型 AI 应用是如何进行功能灰度发布和内部测试的。

1.1 源码还原与项目结构概览

首先需要明确，我们讨论的源码是基于公开的 npm 包 @anthropic-ai/claude-code 中的 source map 还原而来。source map 是 JavaScript/TypeScript 构建时生成的调试文件，它建立了压缩后的代码与原始源码之间的映射关系。通过提取 cli.js.map 中的 sourcesContent 字段，我们可以近乎完整地恢复出近 2000 个 TypeScript 源文件。

整个项目的结构非常清晰，采用了典型的前端工程化组织方式。 src/ 目录是核心，里面包含了 53 个工具定义（如文件编辑、Bash 执行、MCP 集成）、87 个斜杠命令（如 /buddy , /ultraplan ）、148 个基于 React + Ink 的终端 UI 组件，以及专门的功能模块目录，如 buddy/ 、 assistant/ 、 coordinator/ 。这种模块化设计使得每个隐藏功能都能独立开发、测试和开关控制。

构建系统显然是高度定制化的。项目使用 Bun 作为运行时和包管理器，这比传统的 Node.js 生态在启动速度和工具链集成上更有优势。更重要的是，构建过程中会注入一系列编译时常量，其中最关键的就是 feature() 函数和 USER_TYPE 变量。 feature() 用于判断某个功能开关是否在本次构建中被启用，而 USER_TYPE 则区分了内部员工（ 'ant' ）和外部用户（ 'external' ），这两者共同决定了最终二进制文件中包含了哪些代码路径。

2. 七大隐藏功能详解与实现原理

2.1 BUDDY：终端里的 AI 电子宠物系统

这可能是最令人惊喜的隐藏功能。在 src/buddy/ 目录下，实现了一套完整的虚拟宠物系统，官方称之为“Buddy”。它的设计非常精巧，不是一个简单的彩蛋，而是一个有完整状态、交互和收集要素的游戏化系统。

核心机制与确定性生成： 宠物的生成算法是确定性的，这意味着每个用户账户会固定获得一只宠物，无法通过反复尝试“刷”出稀有宠物。其核心逻辑是利用用户的唯一标识（推测是账户 UUID）加上一个固定的盐值字符串 'friend-2026-401' ，通过 FNV-1a 哈希算法生成一个初始种子。这个种子再输入到一个名为 Mulberry32 的伪随机数生成器中，后续所有随机判定（如物种、稀有度、是否闪光）都基于这个 PRNG 的序列。这种设计保证了体验的一致性，也防止了用户通过外部手段作弊。

物种、稀有度与外观系统： 系统预设了 18 种宠物物种，从常见的鸭子、猫、兔子，到奇幻的龙、幽灵，甚至还有机器人、仙人掌这种创意形象。稀有度分为五级：普通（60%）、非凡（25%）、稀有（10%）、史诗（4%）、传说（1%）。此外，还有一个独立于稀有度的“闪光”判定，任何宠物都有 1% 的概率成为闪光个体，这通常会改变宠物的颜色或增加特效。外观上，宠物有 6 种眼睛样式和 8 种帽子（如皇冠、巫师帽、光环），但普通稀有度的宠物不会佩戴帽子，这进一步区分了稀有度带来的视觉差异。

交互与终端适配： 用户可以通过 /buddy pet 命令抚摸宠物，触发一个爱心动画； /buddy hatch 用于孵化（首次获取）； /buddy card 可以查看宠物的详细属性卡片。动画系统考虑到终端环境的限制，采用了 500ms 帧率的 ASCII 精灵动画来表现宠物的待机和动作。更巧妙的是，它具备终端宽度自适应能力：在较窄的终端中，复杂的 ASCII 动画会自动退化为简单的表情文字脸，比如猫会显示为 =·ω·= ，确保了在各种环境下的可显示性。

注意：虽然这个功能趣味性很强，但从工程角度看，它被隐藏在 feature('BUDDY') 开关后，说明 Anthropic 可能将其视为一个实验性功能或员工福利，用于测试 AI 产品的“情感化”设计，评估用户对非功利性、游戏化交互的接受程度。

2.2 KAIROS：永不中断的持久助手模式

如果说 Buddy 是情趣小菜，那 KAIROS 就是硬核主菜。这个功能的目标是让 Claude 成为一个“永不关机”的后台助手，即使你关闭了终端窗口，它依然在运行并处理任务。这彻底改变了 CLI 工具的一次性会话模式。

持久化与状态管理： 启用 KAIROS 模式后，用户需要在 .claude/settings.json 中设置 "assistant": true 。此时，Claude 的会话状态（包括对话历史、记忆、任务队列）会被序列化并持久化到本地磁盘。这意味着你可以随时断开连接，下次启动时，Claude 会从上次中断的地方继续工作。状态管理模块需要精心处理文件锁和并发访问，防止数据损坏。

自动做梦（Auto Dream）：记忆整合引擎 这是 KAIROS 最核心的子功能之一，位于 src/services/autoDream/ 。它的作用是模仿人类的记忆整合过程，定期对零散的会话信息进行梳理、归纳和提炼。触发条件有两个：距离上次整合超过 24 小时，并且在此期间产生了至少 5 个新的会话片段。 一旦触发，系统会在后台启动一个独立的“记忆整合子代理”，其工作流程分为四个阶段：

1. Orient（定向） ：扫描所有新增的会话记忆，确定整合的主题和范围。
2. Gather（收集） ：提取相关记忆片段，并尝试寻找它们之间的关联。
3. Consolidate（巩固） ：将碎片信息合成结构化的摘要、关键知识点或待办事项列表。
4. Prune（修剪） ：剔除冗余或过时的信息，优化记忆存储。 整个过程通过一个 .consolidate-lock 锁文件配合进程 PID 检查来防止多个整合进程同时运行，确保数据一致性。整合后的日志会按日期归档到 /<autoMemPath>/logs/YYYY/MM/YYYY-MM-DD.md 这样的路径中。

主动模式（Proactive）与后台任务： 在主动模式下，Claude 在“空闲”时不会傻等。它内部有一个调度器，会定期（通过接收一个特殊的 <tick> 系统提示）检查是否有任务可做。例如，检查是否有定时任务到期，或者扫描工作区看看有没有新的变更需要处理。如果没找到事情，它会调用一个 SleepTool 进入低功耗等待状态。 对于长时间运行的任务（超过15秒），系统会自动将其丢到后台执行，用户可以在前台继续其他对话。更强大的是，它支持持久化的 cron 任务，通过设置 permanent: true 标志，可以让任务不受默认的 7 天过期时间限制，实现真正的常驻后台作业。

编译与远程开关： 该功能受多个开关控制： feature('KAIROS') 是总开关， feature('KAIROS_BRIEF') 控制简报模式， feature('KAIROS_CHANNELS') 控制通知通道。此外，它还受远程 GrowthBook 开关 tengu_kairos 和 tengu_onyx_plover （用于控制自动做梦的阈值参数）控制，这体现了云端动态配置能力。

2.3 ULTRAPLAN：云端深度规划与执行

当你遇到一个极其复杂、需要长时间思考和研究的问题时，本地 Claude 可能受限于上下文长度和计算资源。ULTRAPLAN 功能就是为了解决这个问题而生，它能把难题“甩给”云端更强大的模型（如 Claude 3 Opus）进行深度处理。

工作流程解析：

1. 触发 ：用户输入 /ultraplan <一个复杂的问题描述> ，或者在对话中自然提及 “ultraplan” 关键词。系统会智能过滤，避免将代码路径或引号内的“ultraplan”误判为指令。
2. 创建远程会话 ：本地 CLI 会在 Anthropic 的云端创建一个 CCR（可能是“Claude Code Remote”的缩写）会话，并将问题描述、相关上下文（有时会通过 Git Bundle 打包部分代码）上传。
3. 云端处理 ：云端分配一个 Opus 模型实例，独立研究该问题，最长运行时间可达 30 分钟。在这期间，它可以进行多轮思考、搜索（如果集成）、编写和测试方案。
4. 轮询与等待 ：本地 CLI 会启动一个后台轮询进程，定期检查远程会话的状态，等待结果或超时（30分钟）。
5. 审查与执行 ：完成后，用户可以在浏览器中打开一个专属界面，查看云端模型生成的详细方案，并可以进行修改和调整。最终，用户可以选择批准该方案，系统会将其“传送”回本地 CLI 环境准备执行。

“传送”机制： 这是 ULTRAPLAN 的关键技术，由 src/utils/teleport.tsx 实现。它需要解决本地和远程两个隔离环境之间的状态同步问题。除了传输文本方案，更重要的是能打包并传输“代码上下文”（比如整个项目的工作区状态）。源码中提到了使用 Git Bundle 来高效地打包和传输代码变更集，这比传输整个文件夹要聪明得多。

严格的内部限定： 源码中有一个硬性检查： isEnabled: () => "external" === 'ant' 。这个条件永远为假，因为 'external' 字符串不可能等于 'ant' 字符串。这意味着，无论编译开关如何，外部用户版本的这个函数永远返回 false ，ULTRAPLAN 功能被彻底锁死。这是功能门控的终极手段，确保该能力仅为内部开发或测试使用。

2.4 Coordinator：多智能体协作编排模式

当任务复杂到需要分工协作时，单一个体就显得力不从心。Coordinator 模式将主 Claude 实例转变为一个纯粹的“指挥官”，它负责分解任务、协调资源，而具体的执行工作则交给多个独立的“Worker”代理去并行完成。

角色分离与核心铁律： 在 Coordinator 模式下，主代理（Coordinator）的工具箱被大幅精简，通常只保留三个核心工具： Agent （创建并指派任务给 Worker）、 SendMessage （与 Worker 通信）、 Shutdown （终止 Worker）。它不再直接操作文件系统或执行命令，而是专注于规划和协调。 Worker 则运行在完全独立的子进程中，每个 Worker 都拥有完整的工具集（Bash、FileEdit 等），可以独立完成任务。这种架构隔离了执行环境，一个 Worker 的崩溃不会影响 Coordinator 和其他 Worker。 系统提示词中强调了一条“核心铁律”：Coordinator 禁止进行“甩锅式委派”。也就是说，它不能把一个自己都没想清楚的需求直接丢给 Worker，它必须自己先理解任务，并将其分解成明确的、可执行的子步骤。这防止了任务在传递过程中信息失真。

基于文件系统的任务追踪： 多代理间的协作需要一个共享的状态中心。Claude Code 采用了基于文件系统的简单方案：在 ~/.claude/tasks/ 目录下维护一个共享的任务列表文件。Coordinator 将任务写入该列表，Worker 从中领取任务，并在完成后更新状态。这种去中心化的方式避免了引入复杂的消息队列，但要求代码具备良好的文件锁和并发读写处理能力。

开关与部署： 该功能由 feature('COORDINATOR_MODE') 编译开关控制。同时，也可以通过环境变量 CLAUDE_CODE_COORDINATOR_MODE 在运行时动态启用或禁用，这为调试和场景化使用提供了灵活性。

2.5 Bridge：从 Web 端远程控制本地 CLI

这个功能打通了 Web 应用（claude.ai）与本地命令行工具之间的壁垒，让你能在浏览器里或手机上直接操作运行在电脑终端里的 Claude。

技术实现：双向通信通道 Bridge 功能的核心是建立一个低延迟、全双工的通信链路。本地 claude-code CLI 启动后，会作为一个 WebSocket 客户端，主动连接到一个由 claude.ai 服务端管理的 WebSocket 服务。这样就建立了一条从本地到云端的实时通道。 通过这个通道，远程的 Web 界面可以：

• 发送消息 ：直接在 Web 聊天框输入，消息会通过 Bridge 发送到本地 CLI，就像在本地终端输入一样。
• 接收输出 ：本地 CLI 的执行结果、流式输出会被实时推送到 Web 界面展示。
• 审批权限 ：当本地 CLI 需要执行高风险操作（如 sudo 命令）时，可以弹出一个权限请求到 Web 界面，由用户远程点击批准。
• 管理会话 ：远程端可以查看所有本地会话的状态，并进行切换、终止等操作。

进程间通信与状态同步： Bridge 模块（ src/bridge/ 下的 31 个文件）处理了复杂的 IPC（进程间通信）逻辑。因为本地可能同时运行多个 Claude 会话（比如多个终端窗口或后台任务），Bridge 需要能够将消息路由到正确的目标会话。 bridgeStatusUtil.ts 负责同步本地 CLI 的运行状态（是否忙碌、当前任务等）到云端。 bridgePermissionCallbacks.ts 则管理着一套回调函数，用于处理远程发来的权限审批结果。这套机制使得远程控制不仅限于“打字”，而是能进行深度的交互和管理。

2.6 隐藏命令与秘密开关大全

除了上述大型功能模块，源码中还散落着大量通过编译开关或用户类型控制的隐藏命令，它们像是开发者的“后门”和调试工具。

编译开关控制的命令： 这些命令只有在构建时启用了对应的 feature() 开关才会被包含进最终的可执行文件。例如：

• /voice ：启用语音交互模式，这需要集成系统的语音识别与合成 API。
• /fork ：允许当前会话“分叉”出一个子代理去并行处理某项任务，子代理完成后将结果返回。
• /peers ：启用基于 Unix Domain Socket 的收件箱，用于同一台机器上不同 Claude 进程间的对等通信。
• /workflows ：加载和执行预定义的工作流脚本，实现任务自动化。
• /force-snip ：强制对过长的对话历史进行截断，以节省上下文 token。

仅限内部用户的命令： 当 USER_TYPE === 'ant' 时，一系列强大的内部工具会被解锁：

• /teleport ：手动触发会话传送，用于调试 ULTRAPLAN 的传输机制。
• /bughunter ：启动内部 Bug 报告和诊断工具。
• /mock-limits ：模拟各种 API 速率限制和错误，用于测试客户端的容错能力。
• /ctx_viz ：将当前会话的上下文使用情况以可视化图表形式输出，帮助理解 token 消耗。
• /break-cache ：强制清除内部的各种缓存（如提示词缓存、模型响应缓存）。
• /ant-trace ：启用详细的内部追踪日志，用于性能分析和调试。
• /agents-platform ：连接到内部的智能体平台进行测试。 这些命令是 Anthropic 员工开发和调试 Claude Code 的利器，外部用户无从知晓。

隐藏的 CLI 启动参数： 除了交互式命令，启动 claude 程序时还可以传入一些隐藏参数来改变其行为模式：

• --proactive ：直接以主动模式启动，Claude 会自主寻找任务。
• --assistant ：以持久化助手模式启动。
• --remote-control ：启用远程控制服务端，可能与 Bridge 功能配合。
• --hard-fail ：启用硬失败模式，任何工具调用错误都会立即终止会话，用于严格测试。
• --agent-teams ：实验性的多代理团队模式，可能比 Coordinator 更复杂。

2.7 功能门控的三层架构

Anthropic 对功能发布采取了极其谨慎和精细的控制策略，这体现在源码中清晰的三层门控架构上。

第一层：编译时开关 这是最严格的一层，在代码构建阶段就决定了功能的去留。源码中定义了约 50 个 feature() 开关，例如 feature('BUDDY') 、 feature('KAIROS') 。在构建外部用户版本时，构建脚本（如 Webpack 或 Rollup）可以通过 tree-shaking 和 dead code elimination 技术，将所有判断条件为假的功能代码完全移除，从而减小最终打包体积，并绝对防止功能泄露。例如， VOICE_MODE 、 TORCH （可能指 PyTorch 集成）、 CHICAGO_MCP （一个计算机使用扩展）等开关，在公开版中对应的代码根本不存在。

第二层：运行时用户类型检查 即使代码被包含在二进制文件中，还需要通过运行时检查来决定是否启用。 USER_TYPE 是一个在运行时注入的常量，对于内部构建是 'ant' ，对于公开构建是 'external' 。源码中有超过 200 处检查 USER_TYPE === 'ant' 的地方。这为内部员工提供了一个“超级用户”模式，他们可以使用所有功能，包括那些仍在激烈开发中、极不稳定的特性。同时，内部版本的远程配置（GrowthBook）刷新间隔更短（20分钟 vs 6小时），使得内部测试和功能回滚可以更快生效。

第三层：远程动态配置 这是最灵活的一层，通过集成 GrowthBook 这类 A/B 测试和服务端功能开关平台来实现。即使前两层都通过了，一个功能是否对某个用户生效，最终还要查询远程配置。例如：

• tengu_kairos : 控制 KAIROS 模式对哪些用户群组开放。
• tengu_onyx_plover : 动态调整自动做梦的触发阈值（间隔时间和最少会话数）。
• tengu_ultraplan_model : 控制 ULTRAPLAN 功能背后使用哪个模型（如 Claude 3 Opus 或 Sonnet）。
• tengu_max_version_config : 一个“紧急制动”开关，可以远程禁用特定版本客户端的自动更新或关键功能。 这种设计允许 Anthropic 在不发布新版本的情况下，动态调整功能策略、进行小流量实验，或在出现问题时快速全局禁用某个功能。

3. 环境变量与高级配置指南

除了代码中的开关，Claude Code 还提供了丰富的环境变量供高级用户进行调优和自定义。这些变量是运行时配置，比编译开关更灵活。

核心功能与环境变量：

• ANTHROPIC_MODEL ：强制覆盖 Claude Code 使用的模型，例如可以指定 claude-3-5-sonnet-20241022 来使用特定版本。
• CLAUDE_CODE_MAX_OUTPUT_TOKENS ：设置模型单次响应的最大 token 数，用于控制输出长度。
• CLAUDE_CODE_DISABLE_THINKING ：设置为 1 或 true 可以禁用模型的“思考链”输出，让回复更直接，但可能降低复杂任务的质量。
• CLAUDE_CODE_USE_BEDROCK / CLAUDE_CODE_USE_VERTEX ：如果用户通过 AWS Bedrock 或 Google Vertex AI 来访问 Claude API，可以通过这些变量启用对应的平台集成。
• CLAUDE_CODE_DISABLE_AUTO_MEMORY ：禁用自动记忆功能，对于追求绝对隐私或调试记忆系统的用户有用。
• CLAUDE_CODE_EXTRA_BODY ：一个 JSON 字符串，可以附加到每次调用 Claude API 的请求体中，用于传递实验性参数或覆盖默认设置。
• CLAUDE_CODE_SYNTAX_HIGHLIGHT ：设置代码语法高亮的主题，例如 github-dark 。
• CLAUDE_CODE_IDLE_THRESHOLD_MINUTES ：定义系统认为会话“空闲”的阈值，超过此时间，某些后台任务可能会被触发，默认是 75 分钟。

内部调试变量：

• CLAUDE_INTERNAL_FC_OVERRIDES ：这是一个强大的变量，仅供 USER_TYPE === 'ant' 时生效。它可以是一个 JSON 对象，用于本地覆盖从 GrowthBook 获取的远程功能开关。内部开发者在测试新功能时，可以不用等待远程配置推送，直接通过此变量在本地开启或关闭特定功能，极大提升了开发效率。

实操心得：合理使用环境变量可以显著改善使用体验。例如，在网速较慢的环境下，可以设置 CLAUDE_CODE_MAX_OUTPUT_TOKENS=500 来获取更快的首次响应。如果发现 Claude 在简单问题上也进行冗长的思考，可以尝试 CLAUDE_CODE_DISABLE_THINKING=true 来提速。但要注意，这些调整是以牺牲输出质量或深度为代价的，需要根据任务类型权衡。

4. 从源码中学到的工程实践与避坑指南

阅读这份还原的源码，不仅是为了猎奇，更能从中学习到 Anthropic 在构建复杂 AI 应用时的工程哲学和具体实践。

4.1 功能开关与渐进式发布 大规模 AI 应用的功能发布充满不确定性。Claude Code 的三层门控（编译时、用户类型、远程开关）提供了一个教科书级的案例。编译时开关用于永久性移除或保留代码，适合区分内部版和外部版。用户类型用于提供内部员工的“上帝视角”。远程开关则提供了终极的灵活性和安全网。在自己的项目中引入类似机制，尤其是在进行 AI 功能实验时，能有效控制风险。

4.2 状态持久化与恢复 KAIROS 模式展示了如何将一个有状态的 CLI 应用转化为持久化服务。关键点在于：将会话状态（包括对话历史、工具调用记录、内存向量等）序列化为一个可存储、可版本控制的格式（很可能是 JSON 或 MessagePack）。恢复时，不仅要加载数据，还要重建运行时上下文，确保工具、环境变量等工作正常。这里的一个常见坑是文件锁和并发写入，Claude Code 使用 .lock 文件和 PID 检查的机制值得借鉴。

4.3 多进程与进程间通信 Coordinator 和后台任务机制都涉及多进程。Node.js/Bun 环境下，可以使用 child_process 或 worker_threads 来创建 Worker。进程间通信（IPC）可以选择标准输入/输出、消息端口或文件系统。Claude Code 在 Bridge 和任务协调中似乎混合使用了 WebSocket（用于远程）和基于文件的共享状态（用于本地多进程），这种根据通信距离选择方案的思路很实用。

4.4 终端 UI 与用户体验 项目使用了 React + Ink 来构建终端界面。这带来了组件化开发的便利，但也引入了复杂性。源码中 148 个 UI 组件说明了其界面的丰富程度。一个重要的细节是 Buddy 宠物系统的终端宽度自适应，这提醒我们，终端应用的 UI 必须考虑不同用户环境（如 iTerm2, Windows Terminal, 简单的 SSH 连接）的兼容性，提供降级方案。

4.5 安全与权限边界 AI 助手拥有执行命令和读写文件的能力，安全是重中之重。从源码中可以看到，对于高风险操作（如 sudo 、删除文件、网络访问），系统会有明确的权限请求步骤。Bridge 功能甚至将权限审批移到了远程的 Web 界面，这可能出于安全审计的考虑。在自行开发类似工具时，必须实现一个“沙盒”或“确认”机制，尤其是当工具能执行任意 Shell 命令时。

常见问题与排查技巧实录：

1. 启动失败，提示 Bun 或 Node 版本不对

   • 问题 ：运行 bun install 或 bun run dev 时报错。
   • 排查 ：首先确认 Bun 版本 ≥ 1.3.5，Node.js 版本 ≥ 24。使用 bun --version 和 node --version 检查。Bun 版本过低是常见问题，其 API 和包管理逻辑变化较快。
   • 解决 ：升级 Bun 到最新稳定版。如果使用 Node，确保是活跃的 LTS 版本。有时需要清除 Bun 的安装缓存 rm -rf ~/.bun/install/cache 再重试。

2. 功能开关不生效

   • 问题 ：按照文档设置了环境变量或修改了配置，但隐藏功能（如主动模式）没有出现。
   • 排查 ：90% 的情况是，你运行的是官方发布的二进制包，这些包在构建时就已经通过 feature() 开关移除了相关代码。环境变量和运行时配置只能控制“已编译进去”的功能的开关。
   • 解决 ：想要体验完整功能，必须从源码自行构建。你需要克隆还原后的源码仓库，并修改构建脚本或配置，确保所需的 feature('XXX') 开关在编译时被设置为 true 。这通常需要修改 Webpack 定义插件或 Bun 的构建参数。

3. Bridge 模式连接失败

   • 问题 ：启用 --remote-control 或 Bridge 相关功能后，无法连接到 claude.ai。
   • 排查 ：首先检查网络，确保能正常访问 Anthropic 服务。其次，Bridge 功能很可能需要身份认证，确保你使用的 API Key 有相应权限。查看 CLI 的调试日志（如果有启动参数开启详细日志）。
   • 解决 ：Bridge 是高度内部化的功能，依赖 Anthropic 内部的基础设施。外部用户几乎无法使用。除非你有内部测试环境，否则此功能可能无法连通。

4. 内存使用过高或响应变慢

   • 问题 ：长时间运行 KAIROS 模式后，CLI 变得迟缓。
   • 排查 ：可能是自动记忆（Auto Memory）功能积累了太多向量数据，或者后台任务堆积。检查 ~/.claude/ 目录下的文件大小，特别是记忆存储文件。
   • 解决 ：可以尝试设置环境变量 CLAUDE_CODE_DISABLE_AUTO_MEMORY=true 来禁用自动记忆。定期清理 ~/.claude/cache/ 目录。对于后台任务，检查是否有永久任务 ( permanent: true ) 在持续运行，考虑将其停止。

5. 自定义工具或扩展集成问题

   • 问题 ：想要为 Claude Code 添加自定义工具或通过 MCP 集成新数据源，但遇到困难。
   • 排查 ：Claude Code 的工具系统定义在 src/tools/ 目录下，遵循特定的接口。MCP 集成需要实现对应的服务器协议。首先确认你的工具或 MCP 服务器本身能独立运行。
   • 解决 ：仔细阅读工具定义的 TypeScript 接口。一个工具通常需要提供 name 、 description 、 parameters 和一个 execute 函数。对于 MCP，确保你的服务器实现了正确版本的协议，并且 Claude Code 的配置指向了正确的服务器地址和端口。参考 src/tools/ 中现有工具的代码是最快的学习方式。

这份还原的源码像是一张精心绘制但未完成的地图，揭示了 Claude Code 这个产品的宏大蓝图和内部运作机制。从游戏化的 Buddy 到工业级的 KAIROS，从云端协作的 ULTRAPLAN 到微服务化的 Coordinator，它展示了一个 CLI 工具如何演进为一个平台化的智能体操作系统。对于开发者而言，其模块化设计、功能门控策略、状态管理和多进程架构都提供了宝贵的参考。虽然大部分隐藏功能对外部用户不可用，但理解其设计思想，无疑能帮助我们更好地使用现有功能，并预见 AI 开发工具的未来形态。