xhj的博客

FileWriteTool：写入文件它解决的是“整文件写入”问题FileWriteTool 适合两种典型场景： 新建一个文件 用一整块新内容覆盖一个现有文件 如果说 FileEditTool 更像外科手术，那 FileWriteTool 更像“整块材料重新铺设”。 Claude Code 明确把这两件事拆成了不同工具，而不是统统交给 shell。这就是它工程设计上的一个细节点。 源码里最关键的输入定义tools/FileWriteTool/FileWriteTool.ts： 1234const inputSchema = z.strictObject({ file_path: z.string().describe('The absolute path to the file to write'), content: z.string().describe('The content to write to the file'),}) 它的输入非常干净： 写到哪里 写什么内容 这说明 Write 的职责就是完...

FileEditTool：编辑文件这个工具解决的不是“能改文件”，而是“怎么安全地改”FileEditTool 负责对已有文件做定点修改。在 Claude Code 里，它的价值从来不只是“替换一段字符串”，而是： 先确认文件读过 再确认文件没被别人改过 再确认当前编辑权限允许 最后才生成 patch 并写回 也就是说，FileEditTool 体现的是 Claude Code 的受控编辑模型 。 看源码，它的依赖明显比想象中重tools/FileEditTool/FileEditTool.ts： 12345import { countLinesChanged } from '../../utils/diff.js'import { fetchSingleFileGitDiff } from '../../utils/gitDiff.js'import { checkWritePermissionForTool } from '../../utils/permissi...

FileReadTool：读取文件它为什么比 cat 更重要FileReadTool 表面看只是“读文件”，但在 Claude Code 里，它其实承担了三层职责： 给模型稳定读取项目文件的入口 让读取结果结构化、可追踪 为后续编辑建立“已读状态” 第三点最容易被忽视。Claude Code 不是随便改文件的，它很强调： 先读，再改 而 FileReadTool 就是这个链路的起点。 先看它的 prompt 怎么定义自己tools/FileReadTool/prompt.ts： 123456export const DESCRIPTION = 'Read a file from the local filesystem.'return `Reads a file from the local filesystem.- The file_path parameter must be an absolute path- By default, it reads up to 2000 lines- This tool can only read files,...

BashTool：Shell 执行器这个工具为什么是核心中的核心如果说 Read、Edit、Write 是 Claude Code 的精细手术刀，那 BashTool 就是它的重型工程机械。 它让 Claude Code 真正接入开发环境： 跑测试 跑构建 看 Git 状态 调用编译器、包管理器、脚本 启动开发服务 执行系统命令 没有 BashTool，Claude Code 顶多是一个“懂代码的文本编辑器”；有了它，Claude Code 才真正变成“能操作本地工程环境的 Agent”。 先看它依赖了多少子模块tools/BashTool/BashTool.tsx 的导入非常夸张，这本身就是一个信号：它绝不是简单 exec() 一下就结束。 123456import { parseForSecurity } from '../../utils/bash/ast.js'import { bashToolHasPermission } from './bashPermissions.js'impor...

AgentTool：子 Agent 调度器这个工具到底解决什么问题AgentTool 是 Claude Code 最有代表性的工具之一。它解决的不是“读文件”或者“跑命令”这种单点能力，而是： 当主线程模型觉得一个任务太大、太杂、太适合并行时，如何把一部分工作拆给另一个 Agent 去做。 这也是 Claude Code 和普通代码助手的核心分水岭之一。很多 AI 工具只有一个主线程模型一直往下跑，而 Claude Code 明确支持： 研究型子任务 后台执行 多 Agent 协作 本地 / 远程子 Agent 先看它的输入长什么样tools/AgentTool/AgentTool.tsx 一上来就把核心参数暴露出来了： 1234567const baseInputSchema = z.object({ description: z.string().describe('A short (3-5 word) description of the task'), prompt: z.string().describe('...

Claude Code 的 Bash 工具为什么这么关键如果只能保留一个执行工具，很多时候就是 BashClaude Code 的工具很多，但从真实开发工作流看，BashTool 几乎是最关键的执行工具之一 。 因为它把 Claude Code 从“能改代码”推进到了“能操作开发环境”。 没有 Bash，它能做的更多是静态修改；有了 Bash，它才能： 跑测试 看构建结果 搜索系统信息 调用项目脚本 和 Git、包管理器、构建链路打通 源码里为什么这部分这么重只看 BashTool.tsx 的导入规模就能知道，这不是一个简单的 child_process.exec 包装： 1234567import { backgroundExistingForegroundTask, markTaskNotified, registerForeground, spawnShellTask, unregisterForeground } from '../../tasks/LocalShellTask/LocalShellTask.js';import...

Claude Code 的文件读写与编辑链路为什么文件链路是 Claude Code 的基本盘再强的 AI 编程工具，如果不能稳定地： 读取文件 理解文件 编辑文件 写回文件 那它就只能停留在“建议型助手”的层面。Claude Code 之所以真正进入工程工作流，文件链路是最底层的原因之一。 从工具注册表看，文件能力是一级公民在 tools.ts 里，文件工具是基础工具集的一部分： 1234567891011121314export function getAllBaseTools(): Tools { return [ AgentTool, TaskOutputTool, BashTool, ...(hasEmbeddedSearchTools() ? [] : [GlobTool, GrepTool]), ExitPlanModeV2Tool, FileReadTool, FileEditTool, FileWriteTool, NotebookEditTool, WebFetchTool, ]&#...

上下文压缩管理很多人第一次接触 Claude Code，都会以为它的“长上下文”能力主要来自模型本身。但从源码看，真正撑住长任务的，不只是上下文窗口，而是一整套分级压缩机制。 Claude Code 并不是等消息塞满之后，简单做一次摘要。它在主查询链路里准备了多层处理： 工具结果预算裁剪 snip 细粒度裁剪 microcompact 微压缩 context collapse 折叠视图 autocompact 自动摘要压缩 reactive compact 出错后的兜底压缩 这意味着 Claude Code 的“上下文管理”本质上是一个多阶段管线，而不是单点能力。 为什么 Claude Code 必须做压缩Claude Code 的任务不是一次问答，而是持续执行工程任务： 读取多个文件 搜索代码库 运行 Bash 命令 写文件和补丁 调用子 Agent 与 MCP / LSP 交换结果 这些行为会不断把新消息和工具结果追加进会话历史。如果没有压缩，模型很快就会被旧消息、长工具输出和附件塞满。 Anthropic 在系统提示词里甚至直接提醒了这一点： 123fun...

上下文系统解析：Git、CLAUDE.md 与系统提示词注入Claude Code 为什么看起来“懂项目”Claude Code 给人的一个强烈印象是：它不像在面对一段孤立代码，而像是在理解整个项目。 这背后最关键的原因之一，就是上下文系统。 context.ts 让系统在对话开始前，就准备好一些高价值项目信息，再注入到后续主循环里。 getSystemContext()：补充系统级背景从源码看，getSystemContext() 至少会处理一类非常重要的信息：Git 状态 。 它会尝试收集： 当前分支 主分支 工作区状态 最近提交 Git 用户信息 这带来的好处非常直接： 模型知道当前仓库是不是脏的 模型知道你现在在哪条分支上 模型知道近期代码变化的大致方向 这对工程任务判断非常重要。 对应源码片段1234567891011121314151617const [branch, mainBranch, status, log, userName] = await Promise.all([ getBranch(), getDefaultBranch(), exec...

命令系统解析：Slash Commands 是怎么工作的命令系统和工具系统不是一回事Claude Code 里有两套很容易混淆的机制： 工具系统 ：给模型调用 命令系统 ：给用户显式输入 比如 /config、/mcp、/review、/plugin 这类东西，不是让模型在主循环里随便调用的，而是用户主动触发的控制入口。 commands.ts 是聚合中心commands.ts 的体量很大，原因很简单：它把系统内的各类命令都汇总起来了。 从导入列表就能看出 Claude Code 的命令能力非常丰富，覆盖： 配置和环境 登录和会话 审查和 diff MCP 和插件 model、usage、status、cost plan、permissions、hooks、files 远程模式、mobile、chrome、branch、skills 这说明命令系统不是边角料，而是 Claude Code 的控制面。 对应源码片段1234567891011import config from './commands/config/index.js'import ...