“基于泄露的Claude Code公开源码从 Harness 工程视角系统性分析一、引言什么是 Agent Harness1.1 Harness 的核心定义在 AI Agent 领域中“Harness”缰绳/套具是一个至关重要的工程概念。它指的是围绕大语言模型构建的、使 Agent 能够在特定领域中有效运作的完整基础设施体系。正如shareAI-lab/learn-claude-code项目所精确定义的Harness Tools Knowledge Observation Action Interfaces Permissions Tools: file I/O, shell, network, database, browser Knowledge: product docs, domain references, API specs, style guides Observation: git diff, error logs, browser state, sensor data Action: CLI commands, API calls, UI interactions Permissions: sandboxing, approval workflows, trust boundariesClaude Code 是 Anthropic 官方推出的命令行编码 Agent 工具其源代码于 2026 年 3 月 31 日因 npm 发布包中的 source map 文件意外暴露而公开。该仓库共计约1,900 个文件、512,000 行 TypeScript 代码为我们提供了一个前所未有的深入理解工业级 Agent Harness 架构的机会。本报告将从 Harness 工程的角度出发系统性地拆解 Claude Code 的源码架构。核心理念是“模型决定做什么Harness 负责执行怎么做。1.2 研究背景与源码来源Claude Code 的源码并非由 Anthropic 主动开源。研究者 Fried_riceChaofan Shou发现 Claude Code 在 npm 发布包中暴露了.map文件该文件引用了存储在 Anthropic R2 存储桶中的未混淆 TypeScript 源码使得完整的src/目录可以被公开下载。这一事件揭示了软件供应链安全中的一个重要问题构建产物的泄露build artifact leak。从研究角度来看这份源码快照为我们提供了一个分析现代 AI Agent 系统架构的珍贵标本。二、整体架构“Claude Code 单循环 HarnessClaude Code 的架构可以用一个极简公式概括其本质Claude Code one agent loop tools (bash, read, write, edit, glob, grep, browser...) on-demand skill loading context compression subagent spawning task system with dependency graph team coordination with async mailboxes worktree isolation for parallel execution permission governance这个公式揭示了 Claude Code 作为 Harness 的最核心设计哲学不试图成为智能体本身而是为智能体Claude 模型提供一个功能完备的操作环境。每一个组件都是一个 Harness 机制——为 Agent 提供手Tools、眼Observation、记忆Context/Memory、协作Team和边界Permissions。2.1 目录结构与模块划分Claude Code 的源码按照功能职责清晰地划分为 30 个顶层目录每个目录对应一个 Harness 子系统目录Harness 角色功能说明src/tools/Agent 的双手约 40 个工具实现提供文件 I/O、Shell 执行、代码搜索等操作能力src/commands/用户指令接口约 50 个斜杠命令用户直接驱动的操作入口src/services/外部服务集成API 客户端、MCP 协议、OAuth 认证、LSP 集成等src/coordinator/多智能体协调子智能体的编排、调度和协作管理src/skills/按需知识加载可复用的工作流定义按需注入领域知识src/bridge/IDE 桥接层连接 VS Code、JetBrains 等 IDE 与 CLI 的双向通信src/hooks/权限与生命周期工具权限校验、会话生命周期管理src/plugins/插件扩展第三方插件加载与管理src/components/终端 UI约 140 个 ReactInk 组件构建 TUI 界面src/screens/全屏界面诊断、REPL、恢复等全屏交互界面src/memdir/持久记忆跨会话的记忆存储目录src/tasks/任务系统带依赖图的任务管理系统src/state/状态管理全局应用状态管理src/migrations/配置迁移配置文件的版本迁移管理src/schemas/配置 Schema基于 Zod 的配置验证 Schema2.2 关键文件概览文件规模职责QueryEngine.ts~46K 行LLM 查询引擎流式响应、工具调用循环、思考模式、重试逻辑、Token 计数Tool.ts~29K 行工具基础类型定义输入 Schema、权限模型、进度状态commands.ts~25K 行斜杠命令注册与执行条件加载不同环境下的命令集main.tsx入口Commander.js CLI 解析 React/Ink 渲染器初始化启动并行预取context.ts—系统提示与用户上下文动态收集cost-tracker.ts—Token 成本追踪三、核心循环“Agent Loop 的 Harness 实现Claude Code 的 Harness 体系建立在最基础的 Agent Loop 之上。这个循环模式是所有 AI Agent 系统的通用骨架模型接收消息、决定行动、执行工具、获取结果、再次决策。3.1 QueryEngineHarness 的大脑中枢QueryEngine.ts约 46K 行作为 Claude Code 的 LLM 查询引擎承担了以下关键 Harness 职责1流式响应处理Streaming ResponseQueryEngine 负责处理来自 Anthropic API 的流式响应用户可以实时看到模型生成的内容而不是等待完整响应返回。这种设计对于终端交互体验至关重要让用户能够即时感知 Agent 的思考过程。流式处理还与终端 UI 组件ReactInk紧密集成实现实时渲染。2工具调用循环Tool-Call Loop这是 Agent Loop 的核心机制。当模型的stop_reason为tool_use时QueryEngine 会自动执行对应的工具将结果作为tool_result追加到消息列表中然后再次调用模型。这个循环持续进行直到模型返回end_turn或其他非工具使用的停止原因。伪代码如下def agent_loop(messages): whileTrue: response client.messages.create( modelMODEL, systemSYSTEM, messagesmessages, toolsTOOLS, ) messages.append({role: assistant, content: response.content}) if response.stop_reason ! tool_use: return results [] for block in response.content: if block.type tool_use: output TOOL_HANDLERS[block.name](**block.input) results.append({ type: tool_result, tool_use_id: block.id, content: output, }) messages.append({role: user, content: results})3思考模式集成Extended ThinkingQueryEngine 支持 Claude 的扩展思考模式允许模型在执行工具之前进行更深层的推理。这是 Harness 为 Agent 提供的认知增强机制使 Agent 能够在复杂任务中进行更周密的规划。4重试逻辑与 Token 计数引擎内置了完善的重试机制来应对 API 错误和速率限制同时精确追踪每次调用的 Token 消耗支持成本控制通过cost-tracker.ts。3.2 最小循环模式的 Harness 意义从 Harness 的视角看这个循环模式的设计哲学是循环属于 Agent机制属于 Harness。Claude Code 的所有其他 Harness 机制——工具系统、技能加载、上下文压缩、子智能体——都是在这个循环之上层层叠加的而不改变循环本身的结构。四、工具系统Agent 的双手工具系统是 Harness 最核心的组成部分。它定义了 Agent 在环境中能够执行的每一个原子操作。在 Claude Code 中Tool.ts约 29K 行定义了所有工具的基础类型和接口基于 Zod v4每个工具模块都是自包含的定义了自己的输入验证、权限要求和执行逻辑。4.1 核心工具清单与 Harness 功能映射工具名称功能描述Harness 层次BashToolShell 命令执行Agent 的核心操作能力行动层FileReadTool文件读取支持图片、PDF、Notebook感知层FileWriteTool文件创建与覆写行动层FileEditTool字符串替换式的局部文件修改行动层GlobTool文件模式匹配搜索感知层GrepTool基于 ripgrep 的内容搜索感知层WebFetchTool获取 URL 内容感知层WebSearchTool网络搜索感知层AgentTool子智能体生成Subagent Spawning协调层SkillTool技能文件加载与执行知识层MCPToolMCP 服务器工具调用扩展层LSPTool语言服务协议集成感知层NotebookEditToolJupyter Notebook 编辑行动层TaskCreateTool/TaskUpdateTool任务创建与管理协调层SendMessageTool智能体间消息传递协调层TeamCreateTool/TeamDeleteTool团队智能体管理协调层EnterPlanModeTool/ExitPlanModeTool规划模式切换认知层EnterWorktreeTool/ExitWorktreeToolGit Worktree 隔离隔离层ToolSearchTool延迟工具发现元层CronCreateTool定时触发器创建调度层RemoteTriggerTool远程触发调度层SleepTool主动模式等待调度层SyntheticOutputTool结构化输出生成元层4.2 工具设计的 Harness 原则从上述工具清单可以提炼出 Claude Code 工具系统的三条核心设计原则原子性Atomicity每个工具只做一件事职责单一且明确。例如FileReadTool只负责读取文件FileEditTool只负责编辑文件两者不混用。这种设计使得模型的工具选择更加精准减少了误操作的风险。可组合性Composability工具之间可以灵活组合。模型可以先使用GrepTool搜索代码再用FileReadTool读取匹配文件然后用FileEditTool修改目标位置。每个工具的输出都是下一个工具的自然输入。自我描述性Self-Describing每个工具都通过 Zod v4 Schema 精确定义了输入输出格式模型通过工具描述就能理解何时以及如何使用它。此外ToolSearchTool实现了延迟工具发现Deferred Tool Discovery允许 Agent 在运行时动态发现和使用新工具而不需要在系统提示中预加载所有工具描述这大大节省了上下文窗口空间。4.3 命令系统用户驱动的工具接口除了 Agent 自动调用的工具外Claude Code 还提供了约 50 个用户可手动触发的斜杠命令src/commands/命令功能Harness 角色/commit创建 git 提交工作流自动化/review代码审查质量保障/compact上下文压缩上下文管理/mcpMCP 服务器管理外部工具集成/config设置管理配置系统/doctor环境诊断健康检查/login//logout认证管理安全认证/memory持久记忆管理记忆系统/skills技能管理知识系统/tasks任务管理任务系统/vimVim 模式切换界面交互/diff查看变更感知层/cost查看使用成本资源管理/resume恢复上次会话会话持久化/share分享会话协作/pr_comments查看 PR 评论感知层五、知识与技能系统“Agent 的按需学习机制在 Harness 工程中知识不是预先灌入系统提示的静态信息而是按需加载的动态资源。Claude Code 的技能系统src/skills/完美诠释了这一原则。5.1 按需知识加载On-Demand Knowledge LoadingClaude Code 的技能系统采用了“需要时才加载而非预先加载”的设计哲学。具体实现方式是技能定义以.md文件存储在skills/目录中每个技能文件包含 YAML frontmatter描述触发条件和简短描述和详细的知识体当模型判断需要某个技能时通过SkillTool加载对应文件内容通过tool_result注入到对话上下文中这种设计的关键优势在于避免了上下文窗口的浪费。在一个编码会话中Agent 可能需要不同领域的知识前端框架、数据库设计、API 设计等如果将所有知识都预加载到系统提示中会快速消耗宝贵的 Token 预算。5.2 Progressive Disclosure渐进式披露更先进的 Harness 实现进一步发展了“渐进式披露”策略。技能内容被分为三个层次Level 1: Metadata元数据触发描述 — Agent 首先看到的摘要Level 2: Body主体内容 — 判断需要后加载的详细信息 Level 3: References引用资料 — 深入分析时才加载的参考资料Agent 首先只看到触发描述判断是否需要该技能如果需要再加载主体内容如果还需要更深入的信息才加载引用资料。这种多层次的信息架构最大化了上下文利用效率是 Harness 工程中知识管理子系统的高级实践。5.3 插件架构src/plugins/实现了插件加载系统允许内置和第三方插件扩展 Claude Code 的能力。插件可以定义自己的工具、命令和技能通过标准的注册机制集成到 Harness 中。六、上下文管理Agent 的记忆工程上下文管理是 Harness 工程中最具技术挑战性的环节之一。由于大语言模型的上下文窗口有固定大小限制Harness 必须在保留有用信息和腾出空间之间找到平衡。6.1 三层压缩策略Claude Code 实现了一套三层上下文压缩策略来应对无限会话的需求第一层子智能体隔离Subagent Isolation通过AgentTool生成的子智能体拥有独立的messages[]数组它们的操作历史不会污染主会话的上下文。主会话只接收子智能体返回的最终结果摘要而非完整的执行过程。这种设计从根本上防止了噪音从子任务泄漏到主对话中。Lead Agent (messages[]) ── spawn SubAgent ── SubAgent (fresh messages[]) | execute task | return summary ── Lead Agent第二层上下文压缩Context Compression由src/services/compact/实现当对话历史接近上下文窗口限制时系统会自动将早期的对话内容压缩为摘要。压缩过程中保留关键信息如代码变更、决策理由、用户反馈丢弃冗余细节。第三层任务持久化Task Persistence通过src/tasks/和src/memdir/实现目标任务被持久化到磁盘文件中。即使单个会话结束任务状态也可以在下次启动时恢复通过/resume命令。这种机制将 Agent 的记忆从易失的对话上下文扩展到了持久化的文件系统。6.2 系统提示与上下文收集context.ts负责收集和组装发送给模型的系统提示包括用户自定义指令CLAUDE.md文件项目级配置环境信息操作系统类型、可用工具列表当前工作目录的代码结构摘要系统提示的构建是动态的——根据当前会话状态和可用资源每次请求都可能生成略有不同的系统提示以最大化利用有限的上下文窗口。七、多智能体协调“Team Harness 架构当单个 Agent 无法独立完成复杂任务时Harness 需要提供多智能体协调能力。Claude Code 在src/coordinator/中实现了一套完整的多智能体编排系统。7.1 子智能体生成与隔离AgentTool是实现子智能体生成的核心工具。当主 AgentLead Agent判断需要将子任务委派给独立智能体时它通过调用AgentTool来生成一个全新的子智能体实例。每个子智能体拥有完全独立的执行环境独立的messages[]数组确保上下文隔离独立的工作目录通过 Git Worktree 实现文件系统隔离独立的权限边界子智能体的权限不超出主 Agent 授权范围子智能体完成后只将结果摘要返回给主 Agent。主 Agent 甚至不知道子智能体的具体执行过程——它只知道任务完成的结果。7.2 团队协作与异步通信Claude Code 进一步提供了TeamCreateTool、TeamDeleteTool和SendMessageTool来支持更复杂的团队协作模式Teammates持久化的团队成员智能体实例JSONL Mailbox基于 JSONL 文件的异步邮箱通信机制统一请求-响应模式包括关闭协商和计划审批等状态机管理自主任务认领团队成员在空闲时自动扫描任务面板识别并认领适合自己技能的任务7.3 六种架构模式根据对 Claude Code Harness 生态的研究特别是 RevFactory Harness 插件的分析Claude Code 的多智能体协调支持以下六种经过验证的架构模式模式适用场景通信方式Pipeline顺序依赖任务设计 → 前端 → 后端 → 测试上一步输出作为下一步输入Fan-out/Fan-in并行独立任务多维度代码审查分发后聚合结果Expert Pool上下文依赖的专业任务选择根据任务类型动态选择专家Producer-Reviewer生成后验证内容创作 质量审核生产者-审核者交替Supervisor中心化动态调度YouTube 内容规划Supervisor 统一调度Hierarchical Delegation复杂任务的自顶向下递归拆分树状层级委派7.4 Worktree 隔离并行执行的安全保障EnterWorktreeTool和ExitWorktreeTool实现了基于 Git Worktree 的文件系统隔离。每个子智能体或并行任务可以在独立的 Worktree 中工作修改自己的文件副本而不影响主分支或其他任务。任务完成后通过 Git Merge 将结果合并回主分支。main branch: /project/ (shared) ├── worktree-task-1/ (agent As sandbox) ├── worktree-task-2/ (agent Bs sandbox) └── worktree-task-3/ (agent Cs sandbox)八、权限系统Agent 的安全边界权限控制是 Harness 工程中安全工程的核心体现。Claude Code 在src/hooks/toolPermission/中实现了精细化的权限管理系统。8.1 多级权限模式权限模式行为描述适用场景default每次工具调用前提示用户审批日常开发安全优先plan规划阶段只读执行阶段需审批大型重构任务auto自动批准低风险操作高风险仍需审批信任环境中的快速迭代bypassPermissions跳过所有权限检查沙箱/测试环境8.2 细粒度权限控制权限系统的实现非常精细。每次工具调用时toolPermission hook都会介入检查。系统支持基于以下维度的细粒度规则配置工具类型不同工具有不同的默认权限级别操作类型读取操作通常比写入操作更容易获得批准文件路径模式可以限制 Agent 只在特定目录下操作命令模式BashTool 中可以配置允许的命令白名单此外Git Worktree 隔离机制提供了文件系统级别的沙箱——每个子智能体在自己的 Worktree 中工作不会影响主分支的文件。这种多层防护确保了 Agent 在拥有强大操作能力的同时不会意外造成不可逆的损害。九、Bridge 系统“跨越终端的 Harness 延伸Claude Code 最初是一个终端CLI工具但通过src/bridge/实现的桥接系统它能够无缝嵌入到 IDE 环境中如 VS Code、JetBrains。这是一个双向通信层包含以下核心组件组件功能bridgeMain.ts桥接主循环管理 IDE 与 CLI 进程之间的通信生命周期bridgeMessaging.ts定义消息协议包括请求类型、响应格式和错误处理规范bridgePermissionCallbacks.ts将权限审批流程桥接到 IDE 的 UI 中jwtUtils.ts基于 JWT 的认证机制确保通信安全sessionRunner.ts管理会话的启动、运行和终止生命周期replBridge.tsREPL 会话桥接从 Harness 的视角看Bridge 系统的意义在于它将 Agent 的操作环境从纯终端扩展到了 IDE。用户可以在熟悉的编辑器界面中使用 Claude Code 的全部能力同时享受 IDE 提供的代码高亮、文件导航、Git 集成等增强功能。十、性能优化“Harness 的工程细节Claude Code 作为生产级 Harness在性能优化方面展现了极高的工程水准。10.1 并行预取启动优化在应用启动阶段Claude Code 采用了并行预取策略来最小化启动延迟。main.tsx在模块评估开始之前就通过副作用代码并行启动了// main.tsx — fired as side-effects before other importsstartMdmRawRead() // MDM 设置读取startKeychainPrefetch() // Keychain 凭据预取// GrowthBook 初始化 API 预连接当用户看到命令行提示符时这些耗时操作已经在后台并行完成了。10.2 懒加载与死代码消除重量级模块如 OpenTelemetry、gRPC、分析服务和部分特性门控子系统通过动态import()延迟加载。更关键的是Claude Code 利用 Bun 运行时的bun:bundle特性标志实现了编译时死代码消除import { feature } from bun:bundle// 未激活的代码在构建时被完全剔除const voiceCommand feature(VOICE_MODE) ? require(./commands/voice/index.js).default : null主要特性标志包括特性标志功能状态PROACTIVE主动模式Heartbeat 驱动可选KAIROS时间感知调度可选BRIDGE_MODEIDE 桥接模式可选DAEMON守护进程模式可选VOICE_MODE语音输入模式可选AGENT_TRIGGERSAgent 触发器可选MONITOR_TOOL监控工具可选10.3 技术栈分析类别技术选型Harness 意义运行时Bun高性能 JS/TS 运行时原生支持 bundle 特性标志语言TypeScript (strict)类型安全大型代码库的可维护性终端 UIReact Ink用 React 组件模型构建终端界面140 组件CLI 解析Commander.js成熟的命令行解析框架Schema 验证Zod v4工具输入输出的运行时类型安全代码搜索ripgrep极快的正则表达式代码搜索外部协议MCP SDK, LSP标准化的外部工具集成APIAnthropic SDK与 Claude 模型的直接通信遥测OpenTelemetry gRPC可观测性基础设施特性标志GrowthBookA/B 测试与渐进式功能发布认证OAuth 2.0, JWT, Keychain多层次安全认证十一、Harness 工程的核心洞察11.1 模型即智能体代码即缰绳Claude Code 的架构最深刻的教训在于“The model is the agent. The code is the harness.Claude Code 不试图通过复杂的规则引擎、决策树或工作流编排来模拟智能——它完全信任 Claude 模型的决策能力将全部工程精力投入到为模型提供一个清晰、丰富、安全的工作环境中。正如 learn-claude-code 项目所总结的“Prompt plumbing “agents” are the fantasy of programmers who don’t train models. They attempt to brute-force intelligence by stacking procedural logic — massive rule trees, node graphs, chain-of-prompt waterfalls — and praying that enough glue code will somehow emergently produce autonomous behavior. It won’t. You cannot engineer your way to agency. Agency is learned, not programmed.11.2 Harness 工程师的五大职责基于 Claude Code 的源码分析Harness 工程师的核心职责可以归纳为以下五个维度(1) 实现工具Implement Tools— 给 Agent 双手工具的原子性、可组合性和自我描述性直接决定了 Agent 的操作精度每个工具都应该像一个精心设计的 API——输入明确、输出可预测、错误可处理(2) 策划知识Curate Knowledge— 给 Agent 专业知识按需加载、渐进式披露的策略确保了知识的高效利用领域文档、架构决策记录、编码规范等知识资源的组织和触发条件设计是 Harness 质量的关键(3) 管理上下文Manage Context— 给 Agent 清洁记忆子智能体隔离、上下文压缩、任务持久化三层策略共同确保 Agent 在长时间会话中保持高效“Context will fill up; you need a way to make room”(4) 控制权限Control Permissions— 给 Agent 安全边界多级权限模式、细粒度规则配置和 Worktree 文件系统隔离构成了多层次安全防护这是 Harness 工程中安全工程的核心(5) 收集训练信号Collect Task-Process Data— 改进下一代 Agent每一次 Agent 在 Harness 中执行的感知-推理-行动序列都是宝贵的训练信号Harness 不仅服务于当前的 Agent还可以帮助改进下一代 Agent 模型11.3 通用化启示Claude Code 作为编码 Agent Harness 的设计模式具有广泛的通用性。同样的 Harness 架构原则可以应用于任何需要 AI Agent 操作的领域Estate management agent model property sensors maintenance tools tenant commsAgricultural agent model soil/weather data irrigation controls crop knowledgeHotel operations agent model booking system guest channels facility APIsMedical research agent model literature search lab instruments protocol docsManufacturing agent model production line sensors quality controls logisticsEducation agent model curriculum knowledge student progress assessment tools核心循环始终相同模型接收消息、决定行动、执行工具、获取结果、再次决策。改变的只是工具、知识和权限——这些正是 Harness 工程师的工作范畴。通过对 Claude Code 源码快照的 Harness 视角深度解读我们发现 Claude Code 是一个经过精心设计的、工业级的 Agent Harness 系统。其核心架构可以用一句话概括“一个智能体循环 一套完备的操作环境从工具系统40 个原子工具、分层行动-感知体系到知识管理按需加载、渐进式披露从上下文工程三层压缩策略到多智能体协调六种架构模式、异步邮箱通信从权限治理多级模式、细粒度控制到性能优化并行预取、懒加载、死代码消除Claude Code 在每一个 Harness 子系统上都展现了成熟的工程决策和优雅的实现方式。Claude Code 给我们的最重要启示是“最好的 Agent 产品来自于那些理解自己的工作是 Harness而非智能的工程师。当我们将工程精力从试图编程智能转向为智能构建世界时Agent 系统的能力上限将由模型本身的智能水平决定而非被差劲的 Harness 设计所限制。学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】