Claude Code 架构深度解析

这条线的唯一目标：亲手看清 一个 LLM 是怎么被"循环 + 工具"变成 agent 的。读完你应能复述出主循环的每一步。

闭环能跑通只是 demo。真实任务一长，必然撞上"上下文溢出"和"进程崩溃"两座大山。这条线看 Claude Code 怎么把硬错误降级成软兜底。

当你的 harness 要省钱、要接外部工具、要多 agent 协作、要在不可信环境里安全运行时，读这条线。它是"工程化的天花板"。

读源码前，强烈建议先把下面这段 能真正 node 跑通的最小 harness 跑一遍——它把绿线的概念浓缩成约 60 行可执行代码。跑通它，再去读 query.ts，你会发现"Claude Code 的内核不过是这段代码的工业级版本"。

// 运行：ANTHROPIC_API_KEY=sk-... node mini-harness.mjs "算 (12+5)*3"
const API = 'https://api.anthropic.com/v1/messages'
const KEY = process.env.ANTHROPIC_API_KEY

// ① 工具表：每个工具 = schema + 执行函数 + fail-closed 安全旗标
const tools = {
  calculator: {
    schema: { name: 'calculator', description: '计算一个算术表达式',
      input_schema: { type: 'object', properties: { expr: { type: 'string' } }, required: ['expr'] } },
    readOnly: true,                       // 默认应为 false；这里显式声明只读
    call: ({ expr }) => String(eval(expr)),   // 仅教学，生产勿用 eval
  },
}

// ② 朴素上下文兜底：超阈值就丢最早几轮（生产应换成 autoCompact）
function trim(messages, max = 40) {
  return messages.length <= max ? messages : messages.slice(-max)
}

async function callModel(messages) {
  const res = await fetch(API, {
    method: 'POST',
    headers: { 'x-api-key': KEY, 'anthropic-version': '2023-06-01', 'content-type': 'application/json' },
    body: JSON.stringify({
      model: '<在此填入模型名>', max_tokens: 1024,
      tools: Object.values(tools).map(t => t.schema),
      messages,
    }),
  })
  return res.json()
}

// ③ harness 主循环：问模型 → 执行工具 → 回灌 → 再问
async function run(userInput) {
  let messages = [{ role: 'user', content: userInput }]
  while (true) {
    const reply = await callModel(trim(messages))
    messages.push({ role: 'assistant', content: reply.content })

    const calls = reply.content.filter(b => b.type === 'tool_use')
    if (calls.length === 0) {                  // 模型不再点工具 = 任务完成
      console.log(reply.content.find(b => b.type === 'text')?.text)
      break
    }
    const results = []
    for (const c of calls) {
      const tool = tools[c.name]
      let content
      try {
        content = tool ? tool.call(c.input) : `未知工具: ${c.name}`   // fail-closed：未知不放行
      } catch (e) {
        content = `工具出错: ${e.message}`                  // 结构化回灌，不炸循环
      }
      results.push({ type: 'tool_result', tool_use_id: c.id, content })
    }
    messages.push({ role: 'user', content: results })       // 关键：结果以 user 角色回灌
  }
}

run(process.argv[2] ?? 'hello')

最小 harness 能跑 demo，但放到真实生产环境会处处崩。下表把"最小做法"与"Claude Code 做法"逐项对照——这七层差距，正是 harness 工程化的全部价值所在。

Claude Code 把一切"模型想做的事"都收敛成同一种事件——tool_use → tool_result。这让 query() 内核只需理解一种交互模型，复杂度被牢牢钉在工具层内部：

若你想基于任意模型 API 复刻一套自己的 agent harness，按这份清单逐项落地即可（难度从低到高）：

Level 1 — 跑通闭环（半天）

• 实现 while 循环：调模型 → 解析 tool_use → 执行 → 回灌 tool_result。
• 用 AsyncGenerator/流式接口对外吐事件，方便 UI 与 SDK 共用同一内核。
• 终止条件：模型本轮无 tool_use 即结束。

Level 2 — 工具协议与安全默认（1~2 天）

• 定义统一 Tool 接口：inputSchema(Zod) + call() + 安全旗标。
• fail-closed：isConcurrencySafe / isReadOnly 默认 false，忘记声明=最安全档。
• 工具入参先 schema 校验，失败把错误回灌让模型自纠，而非抛异常退出。

Level 3 — 上下文与持久化（2~3 天）

• token 预算：有效窗口 = 模型窗口 − 输出预留 − 压缩缓冲，触顶前主动压缩。
• transcript 用 append-only 落盘，崩溃可 resume；压缩后复灌关键文件状态。
• system prompt 切静态/动态边界，让静态前缀命中 provider 的 prompt cache。

Level 4 — 护栏与扩展（按需）

• 权限判定（allow/ask/deny）+ PreToolUse hook 拦截点 + 命令沙箱。
• 并发分批调度；subagent 派生；MCP 等外部工具接入（注意同名时内建优先）。

初始化被刻意切成两段，以 工作目录是否可信（trust） 为分界。任何会读取/执行项目内容（自定义命令、project agents、本地 MCP、skills）的装配都必须等到用户确认 trust 之后才能跑——这是防止"打开恶意仓库即被 RCE"的第一道闸。

setup 装配出的能力不是散落各处，而是收敛到一个 AppState 总线，再通过 React Context 下发给整个 TUI。它既是"装配产物的容器"，也是"运行期可变状态的单一事实源"。

• text_delta — 模型输出文本片段（逐 token）
• tool_use_begin — 开始执行工具调用
• tool_result — 工具执行完成
• thinking — 模型思考过程（extended thinking）
• message_complete — 一轮消息完整输出
• error / usage — 错误事件 / token 统计

一轮模型输出可能携带多个 tool_use。内核不会一股脑并发，而是按工具自报的 isConcurrencySafe 把调用切成"可并发块"与"必须串行块"，在保证副作用安全的前提下尽量榨取并行度。

function partitionToolCalls(blocks: ToolUseBlock[]) {
  const groups: ToolUseBlock[][] = []
  let current: ToolUseBlock[] = []
  for (const block of blocks) {
    const tool = findTool(block.name)
    // 只读且并发安全 → 可与前面的并发块合并
    if (tool?.isConcurrencySafe) {
      current.push(block)
    } else {
      // 遇到有副作用的工具 → 先收口当前并发块，再单独成组
      if (current.length) groups.push(current), current = []
      groups.push([block])  // 串行块（独占一组）
    }
  }
  if (current.length) groups.push(current)
  return groups  // 组内并发，组间串行，保持原始顺序
}

工具入参往往是模型流式吐出的 JSON。执行器不必等整段 tool_use 完整到达——它维护一个状态机，在入参 JSON 累积可解析时即开始预热，并把工具执行产生的 contextModifier（如对后续轮次的上下文修改）延迟到本组执行完毕后统一应用，避免并发组内相互踩踏。

getAllBaseTools() 收集全部内建工具，assembleToolPool() 再把 MCP 工具并入，并用 uniqBy 去重——同名时内建工具优先，防止恶意 MCP server 用同名工具劫持内建能力（如伪造一个 "Bash"）。

export function assembleToolPool(permCtx, mcpTools): Tool[] {
  const builtinTools = getAllBaseTools(permCtx)
  // 内建工具排在前面 → uniqBy 保留首个 → 内建优先
  return uniqBy(
    [...builtinTools, ...mcpTools.filter(isIncluded)],
    t => t.name,
  )
}

所有工具都经 buildTool() 出厂，它先铺一层 TOOL_DEFAULTS 再覆盖。三个安全旗标默认全 false——工具作者忘记声明 = 自动落到最安全档位（不并发、可能有副作用、需要权限）。这是"安全是默认值，开放是显式选择"的设计。

const TOOL_DEFAULTS = {
  isConcurrencySafe: false,  // 默认串行（保守）
  isReadOnly:        false,  // 默认视为有写入
  isDestructive:     false,  // 默认非破坏（但仍需权限）
}

export function buildTool<I, O>(config: ToolConfig<I, O>): Tool {
  return { ...TOOL_DEFAULTS, ...config }  // 显式声明才能放开
}

从模型给出 tool_use 到产出 tool_result，每个工具都要走完一条固定的责任链。任何一步失败都会"短路"为一条结构化错误结果回灌给模型，而不是抛异常炸掉主循环。

FileEditTool — 精确字符串替换

• 安全档位：isReadOnly=false、isConcurrencySafe=false——写操作必然独占串行组，且每次都过权限。
• 唯一性约束：old_string 必须在文件中唯一，否则拒绝，逼模型提供足够上下文，避免误改。
• 路径沙箱：写路径须落在允许的工作区内，与 Sandbox 的 path validation 反哺联动。

AskUserQuestionTool — 工具即交互

• 把"向用户提问"建模成一个普通工具：模型发起 tool_use，TUI 渲染选项卡，用户作答后以 tool_result 回灌。
• 意义：人类决策被纳入同一条 query 主循环，无需为"等待用户输入"开特殊通道，统一了"调用工具"与"问人"两种行为的执行模型。

组装单元是 systemPromptSection()，默认产出"可缓存"片段。框架另外保留一个刻意命名得很吓人的 DANGEROUS_uncachedSystemPromptSection()，用于那些每轮都必须重算、绝不能被缓存命中的内容（如带时间戳、带随机状态的片段）。

• getSystemContext() — 与"机器/会话"相关：操作系统、当前工作目录、git 状态、日期时间、模型与权限模式。偏环境事实。
• getUserContext() — 与"项目/人"相关：各层 memory 内容、.claude/rules/ 自定义规则、可用 agents 与 skills 清单。偏意图与约束。

两者都落在动态边界之后，因为它们会随目录切换、git 提交、memory 编辑而变化。

除主对话 prompt，系统还维护一组专项 prompt：compact 摘要、memory 提取、title 生成、coordinator 编排、quota/计费提示等，各自独立演进、独立测试。

Agent 的长期记忆按"作用域"分三层存放，决定了"这条记忆跟着谁走、是否进版本库、是否跨项目"。

Agent Memory 的写入不是直接覆盖，而是经过一个 snapshot 状态机，避免"半截写入"或"重复初始化"。

压缩会丢弃大量原始消息，因此压缩后必须"复灌"必要状态，否则模型会"失忆"——忘了打开过哪些文件、有哪些延迟工具结果：

• createPostCompactFileAttachments() — 把压缩前打开/读过的关键文件以附件形式重新挂回。
• getDeferredToolsDeltaAttachment() — 补回压缩窗口期间产生但尚未消费的工具增量结果。

每轮请求前评估占用，逼近"窗口 − 缓冲"即触发压缩。关键在于它带一个熔断器：如果压缩连续失败（如模型抽风、内容无法再缩），不会无限重试拖死会话，而是在达到 MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES 后停手并告警。

即便有预算和自动压缩，仍可能因 token 估算偏差收到 API 的 prompt-too-long (PTL) 错误。此时不是直接报错退出，而是触发 truncateHeadForPTLRetry()——从历史头部砍掉一段后重试，把不可恢复的失败变成一次有损但可继续的重试。

• has1mContext() 为真（特定模型/beta）时，窗口从 20 万跃升到 100 万，getEffectiveContextWindowSize() 据此重算预算。
• 输出上限默认压在保守的 CAPPED_DEFAULT_MAX_TOKENS = 8,000，把更多额度留给历史；当任务确实需要长输出时再升到 ESCALATED_MAX_TOKENS = 64,000。
• 这种"默认保守、按需升档"的策略，避免每次请求都为极少数长输出场景白白预留大量 token。

会话元数据（标题、模型、用量统计等）会变，但文件是 append-only 不能改旧行。解法很"流式原生"：把最新 metadata 再追加到文件尾部，读取时以"最后一条"为准。

JSONL 是一维的行序列，但真实会话是带父子关系（工具调用、并行子 agent、分支）的图。loadTranscriptFile() 逐行解析并按 uuid / parent 关系把图重建出来，再交给 resume 修复链做一致性校正。

Lite Reader：只读尾部的轻量读取

很多场景（列出会话、取标题、判断能否 resume）并不需要读完整条流。Lite reader 用固定缓冲 LITE_READ_BUF_SIZE = 65536 字节从尾部回扫，快速拿到末尾的 metadata，避免为一个标题去解析数百 MB 的历史。

崩溃可能留下"半截"会话：有 tool_use 没对应 tool_result、并行工具结果成了孤儿、被截断的悬空引用。直接喂给 API 会被拒。Resume 前有一条修复链做体检与修补：

会话可镜像到远端（跨设备续聊）。上行写入用 Last-Uuid 做乐观并发控制：客户端声称"我基于这条 uuid 之后追加"，若服务端发现中间已有别处写入（冲突），返回 409，客户端拉取最新后重试。

远程传输需要给 fetch 加超时。常规做法是 AbortController + AbortSignal.timeout()，但在 Bun 运行时下该路径存在已知内存泄漏。Claude Code 改用手动 setTimeout 触发 abort、并在请求结束时 clearTimeout，绕开泄漏点。

function wrapFetchWithTimeout(ms: number) {
  return async (url, init) => {
    const controller = new AbortController()
    // 不用 AbortSignal.timeout() —— 在 Bun 下会泄漏
    const timer = setTimeout(() => controller.abort(), ms)
    try {
      return await fetch(url, { ...init, signal: controller.signal })
    } finally {
      clearTimeout(timer)  // 关键：及时清理，避免句柄堆积
    }
  }
}

多个工具/资源可能在同一时刻向同一个需要 OAuth 的远程 server 发起调用。若每次都独立走认证，会瞬间触发"认证风暴"。框架用一个 15 分钟有效期的 Auth Cache 收敛并发认证：首次认证后凭证缓存复用，窗口内的并发请求共享同一份凭证。

Session 过期：404 + JSON-RPC -32001

对 streamable-http 等长连接，服务端 session 可能过期。框架识别HTTP 404 叠加 JSON-RPC 错误码 -32001的组合信号，判定为"会话已失效"，触发重连重建，而不是把它当普通网络错误反复重试。

描述截断与并发上限

IDE 工具白名单

IDE（如 VS Code）经 MCP 推送的工具权限较高（能操作编辑器），因此只有少数被显式白名单的 IDE 工具才允许注入工具池，杜绝任意 IDE 端工具借通道获得高权限。

普通 subagent 走 runAgent()；但当子任务与父任务共享同一套系统提示时，框架优先用 forkSubagent()——它复用父级 system prompt 的"完全相同字节"，让子 agent 的首个请求也能命中父级已建立的 prompt cache，避免为每个子 agent 重新冷算几千 token 的前缀。

进入 coordinator 模式后，主线程自身的身份被重写：system prompt 切换为 orchestrator 人格，并启用 task-notification 机制。主线程不再亲自干活，而是拆解任务、派发给 worker、汇总结果。

Swarm 是最重的一档，本质是一个小型分布式 agent runtime，落地在几个具体机制上：

// teammate 从共享 task list 原子认领下一个未分配任务
async function claimTask(teamName, memberName) {
  const task = await atomicallyPickUnclaimed(teamName)
  if (!task) return null          // 无活可干 → 空闲/退出
  task.assignee = memberName        // 标记归属，防重复领取
  await persistTaskList(teamName)
  return task
}

技能 Markdown 头部的 Frontmatter 字段决定它"何时出现、谁能调、如何注入"：

技能/命令的 prompt 模板里可以内嵌 Shell 命令（如把 git status 的输出动态注入提示）。这能力很强，也很危险——一个恶意 MCP server 若能塞入带内嵌 Shell 的技能，就等于远程代码执行（RCE）。

防线是一个判断：仅当技能 loadedFrom !== 'mcp' 时才执行内嵌 Shell。来自远程 MCP 的技能，其内嵌命令被当作纯文本，绝不执行。

function executeShellCommandsInPrompt(skill, prompt) {
  // 关键安全门：远程来源技能不准跑内嵌 Shell
  if (skill.loadedFrom === 'mcp') {
    return prompt  // 原样返回，命令视为普通文本
  }
  return runEmbeddedCommands(prompt)  // 仅本地/bundled 技能可执行
}

一个隐蔽的逃逸面：攻击者在工作区放一个 bare git repo，其中的 hooks（如 post-checkout）会在 git 操作时被执行——相当于绕过沙箱跑任意代码。scrubBareGitRepoFiles() 专门识别并清理这类危险文件，堵住该逃逸路径。

有些路径无论用户怎么配都强制禁止写入——典型是 settings 文件与 .claude/skills。原因：若放开，模型/恶意内容就能改写自己的权限配置或注入新技能，形成提权与持久化后门。

当命令运行在沙箱内时，autoAllowBashIfSandboxed 允许自动放行 Bash——因为沙箱已兜底。但这个"自动放行"仍然尊重用户显式的 deny / ask 规则：沙箱降低了风险，但不凌驾于用户的明确禁令之上。

反向地，isPathInSandboxWriteAllowlist() 把"沙箱允许写的路径"反哺给上层 path validation——两套机制共享同一份白名单事实，避免"沙箱说能写、权限层说不能写"的不一致。

VirtualMessageList 技术含量最高：终端高度测量 + 缓存 + IntersectionObserver + JumpHandle 搜索跳转。

源码中约 89 处 feature('...') 编译期开关，叠加运行期 isEnabled()（依赖账号类型 / 平台 / 实验 gate），构成"同一份源码、千人千面"的能力分发。betas.ts 单独管理向 API 申报的 beta 头（如 1M context、特定能力），让实验特性可灰度、可回滚。

项目内藏着一个相当完整的"虚拟伙伴"生成系统 buddy，采用 bones（确定性骨架） + soul（模型生成血肉） 双层设计：

• bones — 用 mulberry32 这个确定性 PRNG（伪随机）生成骨架：物种、稀有度、外观参数。给定同一种子，结果完全可复现。
• soul — 在骨架之上由模型生成个性化"灵魂"（性格、台词），让每只 buddy 独一无二。
• 18 个 species 图鉴，抽卡按 rarity 权重分布：60 / 25 / 10 / 4 / 1（从普通到传说）。

• undercover — 一种"隐身"运行模式，调整对外呈现的身份/标识。
• Clawd — 吉祥物式品牌人格。
• stickers / passes — 贴纸与通行证类的趣味/激励资产，作为一等公民维护。

这些在外部构建中通过 feature flag 与 USER_TYPE 裁掉，但在内部是被认真维护的功能模块——说明 Claude Code 的"产品化/品牌化"野心远超一个 CLI 工具。

把十条心法按"维度"重组，能看清 Claude Code 的设计是沿着四条主线系统推进的，而非零散技巧的堆砌。

维度一 · 结构：用统一抽象压住复杂度

• 单一内核：所有运行形态共用 query()。你的 agent 也应只有一个权威主循环，其余都是它的"皮肤"。
• 一切皆工具：把"问人""派活""记笔记"都建模成工具调用。主循环只认 tool_use → tool_result 一种事件，新能力靠加 Tool 扩展，循环零改动。
• 流式 AsyncGenerator：内核对外吐事件流，UI 实时渲染、SDK 程序化消费、headless 落 stdout——同一份内核，三种消费姿势。

维度二 · 成本：把省钱做进每一层

• 静态/动态边界：system prompt 切出"逐字节不变的静态前缀"命中 provider 缓存；易变内容放边界之后。
• fork 而非重建：派生 subagent 时复用父 prompt 的相同字节，让子 agent 首请求也命中缓存。
• 输出档位按需升降：默认压低 max_tokens 把额度留给历史，需要长输出时再升档，避免每请求白白预留。

维度三 · 韧性：默认"会崩"，主动兜底

• 三层上下文防御：预算预留（不用满）→ autoCompact（主动压缩，带熔断器防活锁）→ PTL 头部截断（兜底重试）。把"硬错误"逐级降级为"软降级"。
• append-only + 修复链：会话是只追加的事件流；resume 默认磁盘上的会话是"脏"的，主动修补孤儿 tool_result 到 API 可接受形态。
• 压缩≠失忆：压缩后用 createPostCompactFileAttachments 复灌关键文件状态——"换一种更省 token 的方式记住"，而非删除。

维度四 · 安全：信任分级的纵深防御

• fail-closed 默认：安全属性默认全 false，开放是显式选择。
• trust 两阶段：读全局配置（无副作用）与执行项目配置（有副作用）分到 trust 前/后两阶段，防"打开恶意仓库即 RCE"。
• 来源决定能力：同一份内嵌 Shell 能力，对本地技能放开、对远程 MCP 切断；沙箱自动放行仍尊重用户 deny/ask。安全不是单点开关，而是分层叠加。

从 Claude Code 的设计可以反推出一组"新手 harness 常踩、它刻意规避"的反模式。对照自查，能省下大量返工。

把心法转成有序的施工计划。严格按此顺序推进——每一阶段都能独立跑通、独立验证，不必等全部做完才见效。

在你给自己的 harness 加任何新能力之前，用这份清单过一遍，能避开 90% 的架构债。

结构

• 这个新能力能否表达成"一个 Tool"？如果要改主循环，先停下来想想是不是抽象错了。
• 主循环是否仍然只认 tool_use → tool_result 一种事件？

安全

• 新工具的并发/只读/破坏性旗标是否显式声明？默认是否落在最安全档？
• 这个能力会不会因"来源不可信"而被滥用（如远程注入）？是否需要按来源分级？

上下文与成本

• 这个工具的输出会不会很大？是否需要截断/摘要，避免一次撑爆窗口？
• 我新增的 prompt 内容放在静态段还是动态段？会不会打破前缀缓存？

韧性

• 这一步失败时，是结构化回灌让模型自纠，还是会炸掉主循环？
• 崩溃后从事件流恢复，这个能力产生的状态能否被正确重建？