手把手给AI装上13个工具claude-code-from-scratch工具系统设计与edit_file防坑实战【免费下载链接】claude-code-from-scratchBuild your own Claude Code from scratch. Claude Code 开源了 50 万行代码读不动用 ~5000 行 TypeScript / Python 从零复现核心架构11 章分步教程带你理解 coding agent 精髓项目地址: https://gitcode.com/gh_mirrors/cl/claude-code-from-scratchClaude Code 开源了 50 万行代码读不动claude-code-from-scratch用约 5000 行 TypeScript / Python 代码从零复现了它的核心架构而工具系统Tool System正是让 AI 从只会聊天进化为能干活的 coding agent的关键一步。本文带你手把手拆解这个开源项目如何给 AI 装上 13 个工具一个静态数组 一个 switch 分发器就搭起了完整工具系统再深入edit_file工具看清改错地方、引号不匹配、覆盖用户修改三大坑是如何被逐一堵上的。为什么 AI 需要工具一个工具只有三样东西大模型本身只能说话它不能读文件、不能跑测试。工具就是 AI 的手模型决定调什么工具、传什么参数真正干活的函数由你的代码执行。在 src/tools.ts 中每个工具只需要三样东西组成说明作用名字如read_file、edit_file模型调用时用的标识给模型看的说明description input_schema让模型知道工具能干什么、传什么参数干活的函数一个普通函数真正执行文件读写、搜索等操作这个设计极简但威力巨大——模型通过 schema 理解工具函数负责落地执行两者之间只差一层 JSON 参数。13 个工具全家福6 核心 7 扩展项目共定义 13 个工具全部集中在一个 toolDefinitions 静态数组里分类工具能力 文件读写read_file读取文件带行号write_file新建 / 覆盖文件自动创建父目录edit_file精确字符串替换本章重点 ⭐ 探索代码list_filesglob 模式列文件grep_search正则搜索优先系统 grep⚡ 执行命令run_shell跑测试、git、装依赖 扩展能力skill调用.claude/skills/里的技能模板web_fetch抓取 URL 并去 HTML 标签enter_plan_mode/exit_plan_modePlan 模式进出deferred 延迟加载agent派生子 Agent 隔离干活tool_search按需激活延迟加载的工具Python 版功能完全一致实现在 python/mini_claude/tools.py两版可对照阅读。工具系统核心设计数组 switch拒绝过度工程Claude Code 的 66 工具用类体系管理继承、多态、独立测试但教程项目里 13 个工具完全够用更简单的方案定义层toolDefinitions 静态数组格式与 Anthropic API 的tools参数完全一致零转换直接发送执行层executeTool 分发器 用一个switch把工具名分派到对应函数。// src/tools.ts — 工具执行分发 switch (name) { case read_file: result readFile(input); break; case write_file: result writeFile(input); break; case edit_file: result editFile(input); break; // ... list_files, grep_search, run_shell, web_fetch, tool_search default: return Unknown tool: ${name}; }设计哲学错误是数据不是异常。未知工具返回Unknown tool: xxx字符串而非抛异常——这段文字会回到模型手里让它自己发现我幻觉出了一个不存在的工具名并纠正。edit_file 防坑实战这个工具藏着 3 个真实的坑edit_file是 13 个工具里唯一有坑的。它的工作方式很简单给一段old_string和一段new_string把文件里精确匹配到的旧字符串替换掉。听起来没问题实际运行会撞上三个坑。坑 1改错地方 —— 唯一性检查如果old_string在文件里出现 3 次静默替换第一个匹配项就是灾难。editFile 实现 先数出现次数不唯一就直接拒绝const count content.split(actual).length - 1; if (count 1) return Error: old_string found ${count} times. Must be unique.;出现 0 次说明模型记错了文件内容幻觉检测出现 1 次则要求模型提供更多信息来唯一定位。宁可失败也不猜测——错误信息会喂回给模型它会带上更多上下文重试。坑 2引号不匹配 —— 引号容错LLM 的 tokenization 可能把文件里的直引号生成成弯引号没有容错的话这类编辑会 100% 失败。项目用 normalizeQuotes findActualString 解决先尝试精确匹配失败后把两边的弯引号统一归一化再找匹配成功后返回文件中的原始字符串去替换保持文件原有字符风格不被改写。细节彩蛋替换用content.split(actual).join(new_string)而不是String.replace——后者的$有替换符语义遇到含$的代码会被悄悄改写。坑 3覆盖用户正在改的东西 —— read-before-edit mtime 防护这是整个工具系统最有价值的防护executeTool 中的检查逻辑场景系统行为AI 没读过就直接改已有文件❌ 拒绝You must read this file before editingAI 读完后你在 IDE 里手动改了它⚠️ 警告modified externally, read_file again新建文件✅ 跳过检查新文件无需先读原理Agent 用一个 Map 记录每个文件读取时的mtime修改时间戳写入前再比对一次。时间戳变了 文件在 AI 读取后被外部动过。这与 Claude Code 的readFileTimestamps机制对齐——编辑必须基于已知状态不能盲写。编辑成功还送一份 diff编辑完成后工具会生成一段带行号的简易 diff 返回generateDiff模型和人都能立刻确认改对了哪几行。为什么选字符串替换而不是行号或 diff项目文档 docs/02-tools.md 里有张精彩的方案对比表值得新手记住备选方案致命缺陷行号编辑插入 3 行后所有后续行号偏移多步编辑要复杂重算AST 编辑语法错误的文件恰恰最需要编辑AST 解析器直接报错Unified diffLLM 生成严格格式很差一个/-前缀错就废全文件重写大文件烧 Token还可能静默丢掉没改的代码字符串替换✅ 且自带幻觉安全字符串不存在就直接失败逼模型重读纠正另外 3 个值得抄作业的工具设计结果截断保头尾超过 50K 字符时truncateResult 保留开头和结尾各一半——因为编译错误摘要、测试统计往往在末尾只砍中间并明确标注truncated N chars只读工具并行跑read_file、grep_search等无副作用的工具标记为 CONCURRENCY_SAFE_TOOLS可并发执行2-3 倍加速deferred 延迟加载不常用的工具如 plan mode只把名字发给模型需要时模型调tool_search激活完整 schema——工具一多起来这是省 token 的关键。动手跑起来一条命令验证工具系统仓库是只读的先 clone 到本地再运行git clone https://gitcode.com/gh_mirrors/cl/claude-code-from-scratch cd claude-code-from-scratch npm install node steps/run.mjs 2 # 跑第 2 章工具系统无需 API key node steps/run.mjs 2 --diff # 看这一章比上一章多了什么 node steps/run.mjs 2 --py # 换 Python 版第 2 章的可运行最小实现位于 steps/canonical/ts/tools.ts文档与代码由同一真源生成保证文档说的和代码对得上。完整 13 项工具行为可用 test/TEST-GUIDE.md 逐一手动验证。总结~5000 行看懂工具系统的精髓要点一句话总结工具结构名字 说明 函数静态数组定义、switch 分发执行错误处理错误是数据失败信息回喂模型让它自我纠正edit_file 三坑唯一性检查 / 引号容错 / read-before-edit mtime防上下文爆炸50K 截断保头尾、大结果持久化到磁盘工具定义了 agent 的能力下一篇可以顺着 docs/03-system-prompt.md 看 System Prompt 如何定义它的行为——什么时候该小心、优先用哪个工具。 想交流 AI Agent 开发心得可以加入AI Agent 工坊交流群群号 1090526244扫码进群一起讨论 coding agent 的实现细节。【免费下载链接】claude-code-from-scratchBuild your own Claude Code from scratch. Claude Code 开源了 50 万行代码读不动用 ~5000 行 TypeScript / Python 从零复现核心架构11 章分步教程带你理解 coding agent 精髓项目地址: https://gitcode.com/gh_mirrors/cl/claude-code-from-scratch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考