「Claude Code 源码精读」01 要学 harness,看教程不如精读源码

要学 Harness，看教程不如精读源码。 Claude Code 源码精读这个系列将逐模块拆解 Claude Code 的完整源码，带你从零理解一个行业最顶尖水平的 AI Agent 是怎么构建的。

为什么是精读源码？

如果你想学 Harness，网上有大量教程、博客。但说实话，看完之后你大概率还是不会做。

原因很简单：大部分教程教你的是”一个简化的 demo 怎么跑起来”，但真实产品和 demo 之间的差距，就像驾校教练场和上海内环高架的区别。你知道方向盘怎么转，但一上路你就慌了。

学 Harness 最好的方式，是直接看一个真实的、生产级的、每天几百万人在用的产品是怎么做的。

在一周之前，这些大模型的 agent 逻辑，你看不到。你只能用，不能学。

直到 Claude Code 的完整源码泄露了，天赐良机。现在，所有人都能学习这个绝佳样本了。

Claude Code 本质上就是 Anthropic 对 claude 模型做的 harness，让模型真实的介入生产环境。

同一个 Claude 模型，在网页聊天窗口里只能跟你对话。但套上 Claude Code 这层壳，它就能成为你的工作助手。

让同一个模型从”只能说”变成”能做事”的这层壳，就是 Harness engineering（AI 驾驭工程）。

它的源码里沉淀了 Anthropic 团队在工程上的全部思考——工具系统怎么设计、上下文怎么管理、权限怎么控制、多 Agent 怎么协作。是最一手的经验。

所以就有了这个系列：Claude Code 源码精读。一个模块一个模块地拆，用尽可能非技术的语言讲清楚它在做什么、为什么这么做。读完之后，你可以用同样的思路接入任何模型（GPT、Gemini、DeepSeek、Kimi），搭一个服务于你自己的 Agent。

先来看看 Claude Code 的源码全貌，建立一个全局认知。

Claude Code 源码全貌

claudecodesrc/├── assistant/          # 助手模式├── bootstrap/          # 启动引导├── bridge/             # 桥接层├── buddy/              # 伙伴模式├── cli/                # 命令行接口├── commands/          # 斜杠命令（/help, /compact, /model 等）├── components/        # 终端 UI 组件├── constants/          # 常量定义├── context/            # 上下文管理├── coordinator/        # 多 Agent 协调├── entrypoints/        # 入口点（CLI / SDK）├── hooks/              # 事件钩子系统├── ink/                # 终端渲染引擎├── keybindings/        # 快捷键├── memdir/             # 记忆目录├── migrations/         # 数据迁移├── moreright/          # 权限扩展├── native-ts/          # 原生 TS 模块├── outputStyles/       # 输出样式├── plugins/            # 插件系统├── query/              # 查询处理├── remote/             # 远程功能├── schemas/            # 数据结构定义├── screens/            # 界面屏幕├── server/                 # 服务端├── services/               # 核心服务（API、MCP、压缩、记忆等）├── skills/           # 技能系统├── state/             # 全局状态管理├── tasks/                  # 后台任务管理├── tools/                  # 工具实现（Read、Edit、Bash、Agent 等）├── types/                  # 类型定义├── upstreamproxy/          # 上游代理├── utils/                  # 工具函数├── vim/                    # Vim 模式├── voice/                  # 语音功能├── commands.ts             # 命令注册├── context.ts              # 上下文组装入口├── cost-tracker.ts         # 费用追踪├── costHook.ts             # 费用钩子├── dialogLaunchers.tsx     # 对话框启动器├── history.ts              # 对话历史├── ink.ts                  # 渲染引擎入口├── interactiveHelpers.tsx  # 交互辅助├── main.tsx            # 程序总入口├── projectOnboardingState.ts # 项目引导状态├── query.ts          # 主循环入口├── QueryEngine.ts          # 查询引擎├── replLauncher.tsx        # REPL 启动器├── setup.ts                # 初始化配置├── Task.ts                 # 任务基类├── tasks.ts                # 任务注册├── Tool.ts                 # 工具接口定义├── tools.ts                # 工具注册

看起来文件很多，总共有 1900+文件，50 万+行代码，但别被吓到。

整个 Claude Code 做的事情可以用一句话概括：

接收用户的指令 → 把指令和上下文一起发给 Claude 模型 → 模型决定要调用什么工具 → 执行工具 → 把结果喂回模型 → 模型继续思考下一步 → 循环，直到任务完成。

所有的代码，都是围绕这一个循环展开的。query.ts 是循环本身，tools/ 是循环中可以调用的能力，context.ts 决定每次循环给模型看什么信息，permissions/ 控制哪些操作需要人来批准。其他的都是辅助。

理解了这一点，再去看每个模块就不会迷路了。后续我们会一个一个拆开来看。

这个系列会怎么走？

大致的路线图（后面根据进展可能会有一定的调整）：

每一期的目标都是：用尽可能非技术的语言，讲清楚一个关键概念。 如果你有编程基础，你还能直接看到对应的源码。如果你没有，你至少能理解这些设计背后的思路。

Harness 会不会被淘汰？

可能有人会说：大模型能力越来越强，以后还需要 Harness 吗？

确实，Harness 里有一部分工作是在弥补当前模型的不足——比如复杂的 prompt 引导、错误重试、上下文压缩。随着模型变强，这些”补偿性工程”会逐渐减少。

但 Harness 的核心永远不会消失。

就像电脑的 CPU 越来越强，但你仍然需要键盘、屏幕、硬盘、网卡。CPU 再快，它自己不能连网络、不能操作数据库、不能操作界面。模型也一样——它再聪明，也不能直接执行一条终端命令、不能直接调一个 API、不能直接帮你发一封邮件。这些事情，永远需要 Harness 来完成。

大部分人参与不了模型的训练和开发。 模型的能力会不断提升，这不是我们能决定的。但要用好模型去解决实际问题————核心就在于针对各种场景的 Harness。

模型越强，Harness 也就越有价值。你也就能完成各种越来越难的任务。真正让 AI Agent 成为你的助手。

这才是大多数人真正能参与、也真正有机会的事情。与你共勉。