HelloCodeAgentCli 内置工具使用指南从何时用到源码级原理的完整解析【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents导读本文围绕 HelloAgents 共创项目YYHDBL-HelloCodeAgentCli中 Code Agent 的六个内置工具terminal、context_fetch、todo、note、memory、plan展开逐一定义其何时用 / 何时不用 / 如何用并结合tools/builtin/下的真实源码terminal_tool.py、context_fetch_tool.py 等剖析底层实现与安全机制。读完本文你将掌握一套类似 Claude Code/Codex 风格的按需探索 最小工具调用 补丁落盘的 Agent 工具使用范式并能在自己的 Agent 工程中复刻这套工具编排与安全边界设计。一、背景一套 Claude Code 风格的工具体系HelloCodeAgentCli 是一个基于 HelloAgents 组件HelloAgentsLLM/ContextBuilder/ReActAgent等搭建的简易 Code Agent CLI目标体验类似 Claude Code/Codex支持多轮对话、按需探索代码库、生成补丁并在确认后落盘。其整体架构与启动方式见 code_agent/README.md。该项目的提示词工程集中管理在code_agent/prompts/目录见 prompts/README.md文件职责system.md全局行为与安全边界按需探索 / 敏感操作确认 / 补丁格式react.mdReAct 回合格式与工具输入约定plan.md规划工具plan[...]专用提示词summarize_observation.md工具输出摘要提示词tools.md六种内置工具的完整使用指南本文主体其中 tools.md 的核心设计理念是明确何时用 / 何时不用 / 如何用避免模型盲目调用工具。这与system.md中的按需探索原则一脉相承先有足够上下文就推理证据不足再调用工具绝不无端全库扫描。六种工具均实现在tools/builtin/目录下tools/builtin并通过统一的 Tool 基类 与 registry 注册、编排。二、工具调用总则三种思维在逐一展开六个工具前先记住三个总原则原文与源码共同强调先推理后取证优先使用保底上下文系统提示 对话历史 上次工具摘要推理不足时再调用工具避免无端多次搜索。聚合优先于零散需要搜索时优先context_fetch一次查多源而不是反复单独调用 note/memory 的 search。写盘唯一通道是补丁写/改文件必须用*** Begin Patch ... *** End Patch格式严禁cat file/ Here-Doc /tee/ 重定向写盘。三、terminal只读检索与快速查看3.1 使用边界原文要点用途只读检索与快速查看ls/rg/cat/sed/head/tail/grep/git status/diff。何时用定位文件/符号/报错小范围查看片段确认目录结构。何时不用写文件用补丁大范围全库扫描除非用户要求危险命令rm/chmod/git reset --hard。调用示例terminal[{command:rg -n \foo\ context/**/*.py,allow_dangerous:false}]3.2 源码级安全机制terminal_tool.py 将上述边界落地为多层安全检查run()主流程见 L138-L216命令白名单ALLOWED_COMMANDSL65-L86只放行ls/cat/head/tail/find/grep/rg/wc/sort/uniq/sed/awk/pwd/cd/file/git等只读或轻量命令白名单外直接拒绝并列出允许项。路径沙箱cd与mkdir的目标路径必须解析后位于workspace内_handle_cd见 L535-L591rm/chmod放行时同样逐参数校验路径防止符号链接/相对路径逃逸。危险操作确认DANGEROUS_BASE_COMMANDS {rm, chmod}DANGEROUS_GIT_SUBCOMMANDS覆盖git reset --hardL93-L97。这些命令默认拒绝allow_dangeroustrue且开启confirm_dangerous时才会交互式询问y/n。shell 语义分级支持管道如rg ... | head而无需确认但重定向/排除/dev/null、命令替换$()/ 反引号会被_shell_requires_allow_dangerous标记为需危险权限L344-L395git默认只允许status/diff子命令L397-L459。资源护栏默认超时 30 秒、输出上限 10MB构造函数参数timeout/max_output_size见 L99-L136防止长时间命令与超大输出耗尽上下文预算。可见terminal的何时不用写文件并非仅靠提示词约束而是底层直接禁掉了写盘通道——写文件被强制走补丁流程。四、context_fetch聚合搜索控制预算4.1 使用边界原文要点用途聚合搜索files / notes / memory / tests自动摘要控制预算。何时用需要更多证据时搜类名/函数名/错误栈需要相关笔记/记忆比单独 note/memory 搜索更省步数。何时不用已经有足够证据用户仅问对话历史此时直接读对话历史即可不需要调用工具。调用示例context_fetch[{sources:[files,notes],query:ContextBuilder,paths:context/**/*.py}]4.2 源码级实现一次调用多源取证context_fetch_tool.py 的设计理念在文件头注释中写得很清楚保底上下文由 ContextBuilder 自动注入系统提示、对话历史、上次工具摘要扩展上下文通过此工具按需获取notes、memory、files、tests模型自行决定何时需要更多证据避免盲目全局扫描。核心实现要点参数模型L57-L84sources必填notes/memory/files/tests可多选query必填搜索关键词/符号名/错误栈片段paths可选限定文件搜索范围的 glob如src/**/*.py避免全仓库扫描budget_tokens可选单个数据源的 token 上限默认 800。预算控制每个数据源返回最多约 800 tokens_truncate按1 token ≈ 4 字符英文/ 2 字符中文粗估截断_format_file_results还按文件数平分预算并截断更多结果L269-L296。files 源底层调用rg -n -C context_lines默认前后各 5 行做带上下文的搜索命中行按文件分组返回结构化证据rg不可用时降级为grepL166-L222。tests 源检索.pytest_cache/v/cache/lastfailed、test-results.xml、.coverage等测试产物L224-L247。结果缓存以sources|query|paths为键做 LRU 缓存上限 20 条命中时返回[缓存命中]避免同一查询重复消耗L96-L125。这正是比单独 note/memory 搜索更省步数的底层原因一次工具调用完成多源检索 结构化汇总 预算截断把上下文爆炸的风险消化在工具内部。五、todo多步骤任务跟踪5.1 使用边界原文要点用途多步骤任务跟踪状态机为pending | in_progress仅 1 个| completed。何时用3 步以上或多文件/多特性用户列出多项需求跨回合/需确认的任务开始工作前先标记in_progress完成后立即completed。何时不用单一步、琐碎或纯问答。示例原文完整继承todo[{action:add,title:设计简介页布局,desc:头部/简介/技能,status:pending}]todo[{action:update,id:1,status:in_progress}]todo[{action:update,id:1,status:completed}]todo[{action:list}]5.2 源码级约束强制的单 in_progresstodo_tool.py 的核心是状态强约束状态枚举STATUSES (pending, in_progress, completed)L21_enforce_single_in_progressL107-L113保证同时最多一个in_progress若已存在进行中任务新的in_progress会被拒绝并提示先完成/更新它后再切换——这是防止 Agent 多任务并发失控的工程化手段存储.helloagents/todos/todos.json采用临时文件 os.replace原子写入写前自动备份todos.json.bakL90-L98list输出按in_progress / pending / completed分组用 ANSI 颜色与☒/☐标记便于 LLM 快速消化L167-L213。在 react.md 的策略中进一步细化了 todo 的触发条件任务有 ≥2 个子步骤、需用户确认或跨回合继续时先todo add再行动结尾todo list汇总当用户表达分步/步骤/三步/改造/计划/完成后等语义时多数情况下应主动用 todo。六、note结构化笔记Markdown 持久化6.1 使用边界原文要点用途结构化笔记action/decision/blocker/task_state等Markdown 持久化。何时用记录关键结论/风险/阻塞补丁成功/失败总结阶段小结。何时不用临时想法可先留在对话不必频繁写笔记。示例note[{action:create,title:Patch applied,content:...,note_type:action,tags:[patch]}]6.2 源码级实现YAML frontmatter 索引note_tool.py 支持create / read / update / delete / list / search / summary七种动作run()分发见 L193-L215并内置完整参数定义title/content/note_type/tags/note_id/query/limit见 L217-L276。实现细节笔记类型task_state任务状态、conclusion关键结论、blocker阻塞项、action行动计划、reference参考资料、general通用默认general存储格式每条笔记是一个独立.md文件头部携带 YAML frontmatterid/title/type/tags/created_at/updated_at正文为 Markdown_note_to_markdown见 L128-L146天然可被人类阅读与版本管理索引与限额notes_index.json维护元数据索引支持按类型过滤与关键词搜索标题/内容/标签max_notes默认上限 1000 条。七、memory跨会话情景记忆SQLite 持久化7.1 使用边界原文要点用途情景记忆SQLite跨会话回忆发生过什么。默认不开自动写需要显式添加。何时用需要在未来回忆本次决策/阻塞/结论会话结束前写一条小结复用过往经验时可先search。何时不用即时对话短期内容已有 history信息尚不确定。示例原文完整继承memory[{action:add,memory_type:episodic,content:完成 hello.html 样式改造见补丁...,importance:0.7}]memory[{action:search,query:hello.html 样式,memory_types:[episodic],limit:5}]7.2 源码级实现四类记忆 重要性评分memory_tool.py 是连接 MemoryManager 的工具适配层支持动作多达 9 种add / search / summary / stats / update / remove / forget / consolidate / clear_all见 L98-L127。关键参数与设计记忆类型working工作记忆、episodic情景记忆、semantic语义记忆、perceptual感知记忆支持通过file_pathmodality记录图片/音频等模态扩展名自动推断见 L169-L179。在 Code Agent 场景下仅启用episodicSQLite 持久化于repo/.helloagents/memory/重要性评分importance取值 0.0~1.0默认 0.5search支持min_importance过滤summary会按重要性排序输出重要记忆Top N记忆生命周期forget支持importance_based/time_based/capacity_based三种遗忘策略默认重要性阈值 0.1、最大保留 30 天consolidate可将重要短期记忆默认working阈值 0.7整合提升为长期记忆默认episodic——对应人类记忆的睡眠巩固机制明确性设计默认不开自动写需要显式添加对应源码中auto_record_conversation这类自动记录方法并不在默认 ReAct 循环里强制触发避免每轮对话都污染长期记忆。八、plan显式规划工具8.1 使用边界原文要点用途显式规划工具生成分步计划。何时用任务模糊或明显多步骤用户要求出计划执行前需要拆解。何时不用非常简单的一步任务。示例:plan 添加 dark mode 开关或plan[{goal:优化渲染性能先梳理瓶颈再改}]8.2 源码级实现LLM 驱动的计划生成plan_tool.py 是一个可选工具默认提示词要求输出可执行计划5~12 步并包含 Risks 与 Validation若配置了prompt_path即code_agent/prompts/plan.md则读取该文件作为系统提示词。参数包括goal必填计划目标constraints可选额外约束output可选markdown | json默认markdown。实现上它通过HelloAgentsLLM.invoke调用大模型生成计划max_tokens800。在 CLI 中还有一个配套入口:plan 目标命令用于用户强制要求出计划平时则由模型按需调用plan[...]工具不强制每步都规划。九、重要提醒补丁是唯一写盘通道原文的重要提醒部分必须原样继承并加深写/改文件必须用补丁*** Begin Patch ...禁止cat file/ Here-Doc /tee/ 重定向写盘。先用已有上下文推理不足再调用工具避免无端多次搜索。todo 只保持 1 个in_progress完成立刻标记completed阻塞则新增一条说明阻塞。补丁格式的规范在 system.md 中有完整定义核心规则如下原文完整继承*** Begin Patch *** Add File: path/to/new_file.py 文件内容... 可以多行... *** Update File: path/to/existing_file.py 更新后的完整文件内容... *** Delete File: path/to/old_file.py *** End Patch关键规则第一行必须是*** Begin Patch前面不能有任何文字最后一行必须是*** End Patch操作行为*** Add File:/*** Update File:/*** Delete File:Add/Update 后跟完整文件内容Delete 后不需要内容不要用 markdown 代码块包裹补丁路径相对于仓库根目录。react.md 还补充了说明文字与补丁之间要有空行分隔等易错点。补丁落盘执行器的源码级保障补丁由 apply_patch_executor.py 负责解析与应用其安全特性MVP从工程上坐实了补丁是唯一写盘通道路径限制_safe_path拒绝绝对路径/、~开头、拒绝符号链接、解析后必须位于repo_root内L185-L207后缀白名单默认仅允许.py / .md / .toml / .json / .yml / .yaml / .txt / .html / .htm / .css / .js等文本文件防止误改二进制与敏感文件L72-L84规模限制单个补丁默认最多 10 个文件、800 行变更max_files/max_total_changed_lines防止一次补丁造成失控改动L114-L121原子写入与备份先写临时文件再os.replace改前备份到.helloagents/backups/timestamp/L245-L260冲突检测Update 的 hunk 需在文件中精确匹配上下文匹配失败会抛出带recheck_targets提示的异常并支持整文件替换宽松回退L369-L494。十、综合工作流六种工具如何协同将六种工具串起来一个典型的 Code Agent 任务遵循system.md定义的节奏计划 → 取证 → 补丁 → 确认 → 落盘 → 验证。示例如下用户提出多步改造需求 →todo[{action:add,title:...,status:pending}]登记随后todo[{action:update,id:1,status:in_progress}]任务模糊或步骤多 →plan[{goal:...}]生成分步计划需要定位代码 → 优先terminal[{command:rg -n \ContextBuilder\ context/**/*.py,allow_dangerous:false}]小范围检索证据仍不足时 →context_fetch[{sources:[files,notes,memory],query:ContextBuilder,paths:context/**/*.py}]聚合取证得到结论 →note[{action:create,title:...,content:...,note_type:decision,tags:[...]}]记录决策会话结束前 →memory[{action:add,memory_type:episodic,content:...,importance:0.7}]写入跨会话小结修改代码 → 在Finish[...]中输出*** Begin Patch ... *** End Patch经执行器校验后落盘并todo[{action:update,id:1,status:completed}]收尾。这套流程的底层支撑全部可在仓库中验证提示词约定见 react.md 与 system.md工具实现见 tools/builtin补丁落盘见 apply_patch_executor.py。若要在本地体验可参考 code_agent/README.md 配置DEEPSEEK_API_KEY等环境变量后运行python3 -m code_agent.hello_code_cli --repo .启动 CLI。总结tools.md表面上是一份工具使用清单实质上定义了一套最小工具调用 强安全边界 显式状态管理的 Agent 工程哲学——何时该出手取证、何时该忍住不调、何时必须走补丁均有提示词约定与源码强制双重保障。理解这份指南等于同时掌握了 Claude Code 风格 Agent 的用户手册与实现原理。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考