Learn Claude Code Agent 开发 | 2、插拔式工具系统：扩展功能不修改核心循环

Learn Claude Code Agent 开发 | 2、插拔式工具系统扩展功能不修改核心循环整体概述多工具分发核心实现是基础智能体循环的直接扩展核心思想就是“加一个工具, 只加一个 handler”– 循环不用动, 新工具注册进 dispatch map 就行。这是智能体工具分发机制的核心实现体现了 Harness 层最重要的设计原则扩展工具不修改核心循环。解决的核心问题单bash工具存在很多缺陷cat截断不可预测sed遇到特殊字符容易崩溃每次 bash 调用都是不受约束的安全面容易产生越权操作扩展工具需要修改核心循环代码违反开闭原则核心设计思想-------- ------- ------------------ | User | --- | LLM | --- | Tool Dispatch | | prompt | | | | { | -------- ------ | bash: run_bash | ^ | read: run_read | | | write: run_wr | ----------- edit: run_edit | tool_result | } | ------------------核心创新用**分发字典dispatch map**替代硬编码的工具调用实现工具的插拔式扩展。逐段解析1. 环境初始化WORKDIRPath.cwd()clientAnthropic(base_urlos.getenv(ANTHROPIC_BASE_URL))MODELos.environ[MODEL_ID]SYSTEMfYou are a coding agent at{WORKDIR}. Use tools to solve tasks. Act, dont explain.新增WORKDIR常量作为工作区根目录是路径沙箱的基础系统提示从 “Use bash” 改成 “Use tools”明确支持多工具2. 路径安全沙箱 ⭐ 核心安全机制defsafe_path(p:str)-Path:path(WORKDIR/p).resolve()ifnotpath.is_relative_to(WORKDIR):raiseValueError(fPath escapes workspace:{p})returnpath功能防止智能体访问工作目录之外的文件将输入路径解析为绝对路径校验路径是否在WORKDIR之下如果路径逃逸比如../etc/passwd直接抛出错误所有文件操作工具都会先调用这个函数做安全校验3. 工具实现提供了4个工具每个工具都是独立的处理函数1bash 工具和基础实现基本一致只是将cwd固定为WORKDIR提升安全性。2read_file 工具defrun_read(path:str,limit:intNone)-str:try:textsafe_path(path).read_text()linestext.splitlines()iflimitandlimitlen(lines):lineslines[:limit][f... ({len(lines)-limit}more lines)]return\n.join(lines)[:50000]exceptExceptionase:returnfError:{e}功能安全读取文件内容支持limit参数限制读取行数避免大文件撑爆上下文超过行数限制时会提示剩余行数更友好统一异常处理错误信息直接返回给模型3write_file 工具defrun_write(path:str,content:str)-str:try:fpsafe_path(path)fp.parent.mkdir(parentsTrue,exist_okTrue)fp.write_text(content)returnfWrote{len(content)}bytes to{path}exceptExceptionase:returnfError:{e}功能写入文件自动创建不存在的父目录返回写入结果给模型确认4edit_file 工具defrun_edit(path:str,old_text:str,new_text:str)-str:try:fpsafe_path(path)contentfp.read_text()ifold_textnotincontent:returnfError: Text not found in{path}fp.write_text(content.replace(old_text,new_text,1))returnfEdited{path}exceptExceptionase:returnfError:{e}功能精确替换文件内容只替换第一次出现的匹配文本避免误修改匹配不到内容时明确返回错误模型可以调整匹配文本重试4. 工具分发字典 ⭐ 核心扩展机制TOOL_HANDLERS{bash:lambda**kw:run_bash(kw[command]),read_file:lambda**kw:run_read(kw[path],kw.get(limit)),write_file:lambda**kw:run_write(kw[path],kw[content]),edit_file:lambda**kw:run_edit(kw[path],kw[old_text],kw[new_text]),}键是工具名值是对应的处理函数用 lambda 统一参数传递适配不同工具的参数差异加新工具只需要在这里加一行映射不需要修改其他代码5. 工具定义数组TOOLS[{name:bash,description:Run a shell command.,input_schema:{type:object,properties:{command:{type:string}},required:[command]}},{name:read_file,description:Read file contents.,input_schema:{type:object,properties:{path:{type:string},limit:{type:integer}},required:[path]}},{name:write_file,description:Write content to file.,input_schema:{type:object,properties:{path:{type:string},content:{type:string}},required:[path,content]}},{name:edit_file,description:Replace exact text in file.,input_schema:{type:object,properties:{path:{type:string},old_text:{type:string},new_text:{type:string}},required:[path,old_text,new_text]}},]给 LLM 提供的工具描述遵循 Anthropic 函数调用格式每个工具包含名称、功能描述、参数结构JSON SchemaLLM 根据这些描述决定调用什么工具、传递什么参数6. 核心智能体循环和基础智能体循环几乎完全一致只有工具调用部分做了修改defagent_loop(messages:list):whileTrue:responseclient.messages.create(modelMODEL,systemSYSTEM,messagesmessages,toolsTOOLS,max_tokens8000,)messages.append({role:assistant,content:response.content})ifresponse.stop_reason!tool_use:returnresults[]forblockinresponse.content:ifblock.typetool_use:# 从分发字典取处理函数替代硬编码调用handlerTOOL_HANDLERS.get(block.name)outputhandler(**block.input)ifhandlerelsefUnknown tool:{block.name}print(f{block.name}:{output[:200]})results.append({type:tool_result,tool_use_id:block.id,content:output})messages.append({role:user,content:results})关键变化去掉了硬编码的run_bash调用改为从TOOL_HANDLERS字典中根据工具名查找处理函数支持未知工具的错误提示鲁棒性更强核心循环逻辑完全不变实现了对扩展开放、对修改关闭的开闭原则7. 交互式主循环和基础实现完全一致仅提示符做了修改。基础版对比组件基础版s01多工具版s02工具数量1个仅 bash4个bash, read, write, edit工具调用方式硬编码 bash 调用TOOL_HANDLERS分发字典路径安全无safe_path()沙箱防护Agent 循环固定完全不变设计优势扩展性极强加新工具只需要两步写工具处理函数在TOOL_HANDLERS和TOOLS中注册核心循环不需要动一行代码安全性提升路径沙箱防止文件越权访问专用工具比 bash 更可控减少安全风险稳定性更高核心循环经过验证不需要修改减少出问题的概率工具之间独立修改一个工具不影响其他功能使用示例启动后可以测试这些指令python agents/s02_tool_use.py s02Read thefilerequirements.txtread_file:[文件内容]s02Create afilecalled greet.py with a greet(name)functionwrite_file: Wrote50bytes to greet.py s02Edit greet.py toadda docstring to thefunctionedit_file: Edited greet.py s02Read greet.py to verify the edit workedread_file:[修改后的文件内容]核心收获这个版本建立了 Harness 层最核心的设计范式循环永远不变变化的只有工具和分发规则后续的所有功能扩展都是在这个基础上扩展更多工具和机制核心循环始终保持稳定。这种设计思想也贯穿了整个 Claude Code 的架构。本内容参考开源项目 learn-claude-code