xhj的博客

工具系统解析：Tool 抽象与 tools 注册表Claude Code 的执行力来自工具，不只来自模型很多人讨论 AI 编程工具时，容易把注意力全部放在模型上。但从 Claude Code 源码来看，真正让它“能干活”的，是模型外面的工具系统。 如果没有工具，Claude Code 再强也只是会分析代码。有了工具，它才能真正读文件、改文件、跑命令、接 MCP、问用户、开子任务。 Tool.ts 负责定义统一协议Tool.ts 不是某个具体工具实现，而是全系统的工具抽象层。 这里最重要的价值有两个： 统一工具的输入、输出、上下文和权限语义 给所有工具提供相同的运行契约 文件里能看到很多关键类型： ToolInputJSONSchema ToolUseContext ToolPermissionContext 各类进度与状态类型 这些类型说明 Claude Code 设计工具时，不是把工具当命令快捷方式，而是把它们当系统级能力对象。 对应源码片段1234567export type ToolInputJSONSchema = { [x: string]: unk...

Claude Code 的提示词工程不要把 Claude Code 的 prompt 理解成“一大段总提示词”很多人第一次研究 Claude Code，都会先找那段“终极 system prompt”。但源码里真正存在的，不是一条 prompt，而是一整套分层装配的提示词系统 。 Claude Code 至少同时存在这几类 prompt： 会话级 system prompt 运行时动态追加的 prompt section 工具级 prompt 专项子系统 prompt 多 Agent / teammate 模式下的附加 prompt 也就是说，Claude Code 的 prompt 工程不是“写一段厉害的话”，而是“把不同职责的提示词放到不同层，再按运行时状态拼起来”。 一张图看懂 Claude Code 的提示词体系第一层：主会话的 System PromptClaude Code 最核心的 prompt 入口在 constants/prompts.ts。 源码里最醒目的一段是： 12345678910function getSimpleIntroSection...

核心循环解析：QueryEngine 如何驱动一次任务完成QueryEngine 为什么是核心中的核心如果只能选一个文件代表 Claude Code 的灵魂，那大概率就是 QueryEngine.ts。 因为它负责的不是某个局部能力，而是整个任务生命周期： 接收用户输入 组装上下文 驱动模型调用 处理中间工具执行 维护会话状态 把任务一直推进到结束 这就是典型的 Agent 主循环。 它管理的是“会话”，不是“一次请求”源码中的注释已经把定位写得很明确： One QueryEngine per conversation. 这句话很关键。说明 QueryEngine 不是一次性 request handler，而是一个围绕会话长期存在的对象。 因此它会保留很多跨轮次状态，例如： mutableMessages permissionDenials readFileState totalUsage 发现过的 skill 名称 已加载的 memory 路径 这也是 Claude Code 能连续工作的基础。 对应源码片段123456789export class QueryE...

如果你想自己做一个 Claude Code，需要哪些模块先说结论：别从“聊天 + 几个工具”开始想很多人研究 Claude Code 源码之后，第一反应是：“我是不是也能自己做一个类似的系统？” 可以，但前提是你要先放弃一个误区： 不要把它理解成“模型 + function calling + terminal UI”。 从源码看，一个像样的 Claude Code，至少需要一整套运行时模块。 先看最小完整架构图模块 1：入口与交互层你至少需要一个明确的运行宿主： 命令行 TUI IDE 插件 Web UI Claude Code 选的是终端 + React Ink。这不是唯一选择，但你必须先有一个稳定的交互外壳。 模块 2：会话主循环这一层对应 Claude Code 的 QueryEngine.ts。没有它，你就只有零散 API 调用，无法形成真正任务闭环。 主循环至少要负责： 消息历史 模型调用 工具调用 结果回流 中断与预算 会话状态延续 模块 3：统一工具协议这层对应 Tool.ts。如果没有统一工具协议，系统很快会出现： 每个工具输入格式不一致 权限难统...

启动流程解析：main.tsx 到 REPL 是怎么串起来的为什么 main.tsx 值得重点看很多项目的入口文件只是薄薄一层，但 Claude Code 的 main.tsx 明显不是。从导入规模和初始化动作就能看出来，它承担的是“系统装配器”的角色。 它做的事情至少包括： 启动早期性能预热 解析命令行参数 加载设置、策略和环境变量 初始化认证与实验开关 收集命令与工具 启动交互式 REPL 或其他运行模式 一开头就在抢启动时间文件最前面的几个 side effect 很有代表性： profileCheckpoint startMdmRawRead() startKeychainPrefetch() 这说明 Claude Code 团队已经把启动性能当成正式问题来优化。也就是说，入口文件不只是“能跑起来”，而是在尽量把一些 I/O 提前并行化。 对应源码片段12345profileCheckpoint('main_tsx_entry');import { startMdmRawRead } from './ut...

Claude Code 源码架构总览先看整体图如果只从源码目录去看，很容易被大量文件吓住。但从主干关系看，Claude Code 的架构并不乱，它大致可以抽象成下面这张图： 再看一张更贴近源码目录的分层图第一层：启动与装配main.tsx 的职责非常重，它不像普通 CLI 那样只是简单解析参数后执行一个函数。它会在启动阶段做很多装配工作： 预热性能敏感模块 加载配置与托管设置 初始化认证、遥测、策略限制 初始化 MCP、LSP、插件、Skills 汇总命令和工具 根据模式启动 REPL、非交互流程或远程会话 所以 main.tsx 更像一个系统引导器。 对应源码片段1234567import { getSystemContext, getUserContext } from './context.js';import { launchRepl } from './replLauncher.js';import { getTools } from './tools.js...

概述：Claude Code 到底是什么Claude Code 是Anthropic 推出的命令行 AI 编程搭档，它直接运行在终端里，能理解你的整个项目代码，并帮你编写、修改、调试代码，甚至执行命令和 Git 操作。 一张图先建立整体感觉 类比一下：如果说 Google AI Studio 更像一个在线原型实验场，那 Claude Code 更像一个真正驻扎在你电脑项目目录里的高级工程搭档。 它最核心的能力是什么先不要急着看源码细节，先建立一个产品级认知。Claude Code 之所以强，最核心的能力可以概括成下面这几项： 能力 说明 典型问题 理解项目 读取并分析整个代码仓库 “这个项目整体架构是怎样的？” 编写和修改代码 直接创建、更新、重构文件 “给用户列表页加一个搜索功能” 调试修复 定位报错、修 bug、补验证 “这个接口为什么返回 500？” 执行命令 运行测试、构建、安装依赖、Git “帮我跑一下测试，看看哪里挂了” 遵守项目规范 结合 CLAUDE.md 和项目上下文工作 “按这个仓库现有风格改，不要乱来” 所以它强的地方，并不...

Claude Code 源码核心概念一览为什么要先看概念很多人第一次看 Claude Code 源码时，会被一堆词反复轰炸： QueryEngine Tool AppState Plan Mode MCP LSP Skills Agent 如果这些词没有先建立基本认知，后面看源码会非常容易迷路。 所以这篇文章的目标不是深入讲实现，而是先给你一张“核心概念地图”。 一张图先看整体关系1. QueryEngine这是 Claude Code 的核心引擎。你可以把它理解成整个任务循环的大脑调度器。 它负责： 接收用户输入 组织消息历史 调用模型 处理工具调用 把结果回流到下一轮 一句话理解： QueryEngine 决定一项任务如何一轮一轮推进下去。 2. ToolTool 就是 Claude Code 让模型“真正动手”的方式。Claude 不只是输出文字，还可以通过 Tool： 读文件 改文件 跑命令 访问外部资源 进入 Plan Mode 一句话理解： Tool 是 Claude Code 的执行接口层。 3. AppStateAppState 是终端界面的运...

最近，小J在尝试用 AI Agent 为一个中等规模的代码库完整添加国际化（i18n）支持。 理论上，这是一类非常适合 AI 处理的任务：规则明确，需要识别所有硬编码字符串并替换为t(‘KEY’)的形式，同时在语言文件中补充对应键值；任务重复性高，几乎不需要创造性。 一开始进展顺利。Agent 像一台推土机一样，一个文件接一个文件地处理代码。但几个小时后，情况开始失控。对话历史、数百行代码搜索结果、工具调用日志、Linter 报错、人工补充指令……所有信息都被不断塞进同一个上下文窗口。Agent 的响应速度从秒级下降到分钟级，随后开始“胡言乱语”。它会突然忘记之前已经处理过的文件，在一个无关的函数里问我“这个变量是什么意思”，甚至开始修改一些完全不相关的业务逻辑。 最终，当一个简单的 JSON 配置文件也被改得面目全非时，小宁只能选择终止任务。原本寄予厚望的 AI 助手，变成了一个堆满草稿、废弃代码和错误日志的“垃圾场”。 单一 Agent 模式中，上下文不断堆积，噪声与历史信息会持续侵蚀主流程 这次失败揭示了一个关键问题：当任务复杂度超过一定阈值时，单一 Agent 模式极易...

一、最新研究进展Google DeepMind 联合 MIT，做了一件业界期待已久的事：用 180 组控制实验，定量回答”多 Agent 到底比单 Agent 强多少”。 论文叫《Towards a Science of Scaling Agent Systems》（arXiv: 2512.08296），跨 3 个模型家族（OpenAI、Google、Anthropic）、5 种架构、4 个基准任务。不是理论推导，不是案例论证，这是真金白银烧 token 跑出来的实验数据。 结论一句话： “More Agents Is NOT All You Need.” 更多的 Agent 不等于更好的结果。在大多数场景下，多 Agent 系统的表现不仅没有显著优于单 Agent，反而因为协调开销而更差。 二、论文里的六个关键数字这篇论文最大的价值不是观点，是数据。以下是六个关键定量发现，每一个都直接对应我们日常使用中的某种”体感”： 1：工具协调惩罚系数 = -0.330在论文的 20 参数回归模型中，工具 - 协调交互项是最大的负因子。 翻译成人话：你给多 Agent 系统...