用 HelloAgents 组件搭建类 Claude Code 的本地 Code Agent CLI多轮对话、按需代码探索与安全补丁落盘实战【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents本文以开源仓库Co-creation-projects/YYHDBL-HelloCodeAgentCli中的code_agent/README.md为核心深入拆解一个基于 HelloAgents 组件HelloAgentsLLM/ContextBuilder/ReActAgent/TerminalTool/NoteTool/MemoryTool实现的简易 Code Agent CLI。它面向本地代码仓库提供类似 Claude Code / Codex 的交互体验支持多轮对话、按需探索代码库、生成补丁并在用户确认后安全落盘。读完本文你将掌握该 CLI 的安装启动方式、ReActAgent多轮对话与规划机制、GSSC 上下文工程与按需探索lazy_fetch模式、终端工具的沙箱与危险命令确认策略以及 Codex 风格补丁从模型输出到原子落盘的完整链路。项目定位与整体设计HelloAgents Code Agent CLI代码目录Co-creation-projects/YYHDBL-HelloCodeAgentCli/是一个面向本地代码仓库的命令行智能体。与通用对话机器人不同它被设计为在仓库内工作的 CLI 编程助手工作区固定为仓库根目录所有路径都必须经过 repo_root 前缀校验写盘唯一通道是补丁 apply_patch禁止cat /tee/ Here-Doc / 重定向等终端写法。从源码结构看系统采用分层设计CLI 层code_agent/hello_code_cli.py负责参数解析、环境初始化、交互循环、补丁提取与确认智能体层agents/react_agent.py提供 ReAct推理 工具调用主循环配合agents/simple_agent.py、agents/plan_solve_agent.py、agents/reflection_agent.py等范式核心层core/llm.pyHelloAgentsLLM统一 LLM 接口、core/message.py、core/config.py、core/exceptions.py上下文层context/builder.py实现 GSSC 流水线工具层tools/builtin/下的terminal_tool.py、context_fetch_tool.py、note_tool.py、todo_tool.py、plan_tool.py、memory_tool.py等执行器层code_agent/executors/apply_patch_executor.py负责安全补丁应用与文件操作。其中 Code Agent 的主逻辑封装在code_agent/agentic/code_agent.py的CodeAgent类中CLI 入口main()只负责拼装组件与交互循环hello_code_cli.py。快速开始从依赖到启动 CLI1. 准备依赖与环境变量依赖定义在项目根目录的requirement.txtopenai1.0.0 pydantic2.0.0 python-dotenv1.0.0 tiktoken0.5.0 hello-agents[all]0.2.7建议先安装根目录的requirements-mvp.txt见code_agent/README.md再在仓库根目录创建.env参考.env.example不要提交到版本库至少包含DEEPSEEK_API_KEYsk-xxxxxxxxxxxx可选配置OpenAI 兼容 provider 均可LLM_MODEL_IDdeepseek-chat LLM_BASE_URLhttps://api.deepseek.comCLI 启动时会执行load_dotenv(dotenv_pathrepo_root / .env, overrideFalse)加载环境变量并通过HelloAgentsLLM()自动从环境探测 providerhello_code_cli.py。启动时还会做一次 LLM 预检ping请求max_tokens1若认证失败会给出明确提示并返回退出码 2。2. 启动 CLI# 工作区默认为当前目录 python3 -m code_agent.hello_code_cli --repo . # 指定其他代码库 python3 -m code_agent.hello_code_cli --repo /path/to/your/project支持的启动参数参数说明默认值--repo代码库根目录工作区.--project项目名称默认取 repo 目录名用于笔记标签等目录名启动后进入交互循环命令:quit或:q/quit/exit退出:plan 目标强制生成计划平时由模型按需调用plan[...]工具直接输入自然语言即触发一轮 ReAct 对话hello_code_cli.py。多轮对话与智能体范式ReAct 主循环 可选规划Code Agent 的核心循环使用ReActAgent每次回复必须包含Thought与Action两部分Action二选一——调用工具tool_name[tool_input]或以Finish[最终回答]结束Finish中可携带*** Begin Patch ... *** End Patch补丁react.md。在CodeAgent.__init__中工具注册表包含六个工具terminal、note、plan、todo、context_fetch以及通过MemoryTool启用的情景记忆ReAct 最大步数设置为 20并注入observation_summarizer当工具输出超过 8000 字符时先截断再交给 LLM 以summarize_observation.md模板压缩为不超过 400 token 的摘要避免把巨大原始输出直接塞进 Promptcode_agent.py。run_turn每轮流程为空输入提示、闲聊hi/hello/你好/在吗等直接自然回复避免无谓工具调用元请求刚才说了什么 / recap直接总结最近对话历史不调用 memory/note检测到分步/步骤/计划/改造/完成后等多步骤词汇时向系统提示追加轻量 hint引导模型先用 todo 记录用ContextBuilder.build_base构建保底上下文系统指令 对话历史 最近工具摘要运行 ReAct 循环收集last_trace中的工具证据摘要存入recent_tool_packets缓冲区上限 8 个追加用户/助手消息到历史保留最近 50 条并持久化会话到sessions/下的 JSON 文件若模型使用了 todo 但未在结尾todo list汇总自动补一张 Todo board 快照code_agent.py。规划能力作为可选工具plan[...]暴露给模型模型按需调用计划模板要求输出## Plan5~12 条可运行步骤、## Risks、## Validation三节plan.md。多步骤任务的进度追踪由todo[...]完成状态为pending / in_progress仅 1 个/ completed。上下文工程GSSC 流水线与按需探索lazy_fetch上下文构建由context/builder.py的ContextBuilder实现 GSSC 流水线Gather从历史、记忆、RAG、工具结果多源收集→Select基于优先级、相关性、多样性筛选支持 MMR→Structure组织成结构化模板→Compress在 token 预算内压缩。Code Agent 的关键设计是ContextConfig(lazy_fetchTrue)默认不做全仓扫描、不主动查询 memory/rag只构建保底上下文系统提示 最近 10 轮对话历史 上次工具摘要扩展上下文改由模型通过context_fetch工具按需获取code_agent.py。ContextConfig的核心参数builder.py参数默认值说明max_tokens8000上下文总预算reserve_ratio0.15生成余量可用预算 max_tokens × (1 − reserve_ratio)min_relevance0.3扩展上下文最小相关性阈值max_history_turns10最大保留对话轮数enable_mmr/mmr_lambdaTrue / 0.7最大边际相关性0纯多样性1纯相关性enable_compressionTrue启用压缩lazy_fetchTrue按需探索模式不主动查 memory/ragcontext_fetch是聚合搜索工具一次调用可搜索多个源files/notes/memory/tests自动控制 token 预算默认每源约 800 token单次 5 行上下文比反复单独调用 note/memory search 更省步数使用策略是先用保底上下文推理证据不足再调用tools.md。安全终端工具白名单、shell 语义与危险命令确认TerminalTool是 Code Agent 查看/检索代码库的主要通道实现于tools/builtin/terminal_tool.py具有多层安全机制命令白名单ALLOWED_COMMANDS仅包含只读与文本处理命令——ls/dir/tree、cat/head/tail/less/more、find/grep/egrep/fgrep/rg、wc/sort/uniq/cut/awk/sed、echo/printf、mkdir、pwd/cd、file/stat/du/df、which/whereis、gitterminal_tool.pyshell 语义默认启用default_shell_modeTrue体验更像 Claude Code支持管道等写法如rg ... | head但重定向//dev/null除外、子命令替换$()/反引号、rm/chmod、git reset --hard均被判定为高风险必须allow_dangeroustrue并通过交互确认confirm_dangerousTrue后才执行terminal_tool.py路径沙箱cd被限制在工作空间内rm/chmod/mkdir的路径参数跳过-选项逐一resolve()后校验是否位于 workspace 内超时与输出限制默认超时 30 秒CodeAgent 实例化时传入 60 秒、输出上限 10MB超限截断terminal_tool.pyargv-only 执行非 shell 模式使用shlex.splitsubprocess.run(shellFalse)避免 shell 注入git 子命令仅放行只读的status/diff。git的默认策略是仅允许status/diffgit reset --hard需要显式放行——这与 CLI 层补丁确认策略一致共同构成默认只读、危险操作必须人工确认的安全基调terminal_tool.py。补丁落盘B 路线从模型输出到原子写入补丁格式规范模型在Finish[...]中输出 Codex 风格补丁格式必须严格遵守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/Update后跟完整文件内容、Delete后不需要内容不要在补丁外包裹 markdown 代码块路径相对于仓库根目录。CLI 侧的提取与确认CLI 使用两个正则从响应中提取补丁PATCH_FENCE_RE优先匹配 patch/diff/text 围栏内的补丁块PATCH_RE作为宽松兜底跨行匹配*** Begin Patch ... *** End Patchhello_code_cli.py。_normalize_patch会宽容修复模型常见的格式错误——如缺少前导***的Add File: / Update File: / Delete File:行会被自动补齐hello_code_cli.py。_patch_requires_confirmation定义高风险补丁触发二次确认的条件hello_code_cli.py包含*** Delete File:删除操作文件操作数 ≥ 6 个变更行数 ≥ 400 行。命中任一条件即进入y/n确认流程拒绝则取消落盘。应用成功后CLI 会自动通过 NoteTool 以note_typeaction、tags[project, patch_applied]记录一条Patch applied笔记失败则记录blocker类型的Patch failed笔记便于后续复盘hello_code_cli.py。ApplyPatchExecutor 的安全执行落盘由code_agent/executors/apply_patch_executor.py的ApplyPatchExecutor完成支持三种操作Add File、Update File、Delete File。其安全特性MVP包括repo_root 路径限制_safe_path拒绝绝对路径/、~开头、拒绝逃逸 repo_root 的路径resolve 后前缀校验、拒绝修改符号链接防止路径穿越apply_patch_executor.py后缀白名单allowed_write_suffixes默认仅允许.py/.md/.toml/.json/.yml/.yaml/.txt/.html/.htm/.css/.js等文本文件防止误改二进制或敏感文件apply_patch_executor.py规模限制单个补丁最多 10 个文件、总变更行数上限 800 行_estimate_changed_lines对 add 按行数、delete 按 1 行、update 只计/-行原子写入_atomic_write先写临时文件并os.fsync刷盘再用os.replace原子替换避免中断导致文件损坏apply_patch_executor.py自动备份每次应用前在repo/.helloagents/backups/时间戳/下为被修改文件生成.bak备份保留仓库相对路径结构冲突检测Update File按 hunk或空行分隔精确匹配上下文子序列找不到匹配时抛出PatchApplyError并附recheck_targets提示如rel_path:search:上下文行匹配失败还会尝试忽略行尾空白的宽松匹配以及将 payload 视作新的完整文件的兜底回退apply_patch_executor.py。记忆与笔记episodic 情景记忆与结构化笔记NoteTool在repo/.helloagents/notes/下写入结构化 Markdown 笔记note_type支持action / decision / blocker / task_state等用于记录决策、阻塞与行动CLI 还会自动把补丁成功/失败写入笔记。MemoryTool仅启用episodic类型SQLite 持久化默认存储在repo/.helloagents/memory/情景记忆需要显式add不会自动写入避免上下文污染跨会话可通过search回忆发生过什么tools.md。会话持久化每轮对话结束后最近 50 条历史以 JSON 形式写入repo/.helloagents/sessions/session_id.jsoncode_agent.py。存储布局默认使用repo/.helloagents/notes/memory/sessions/logs/backups/todos可通过环境变量覆盖。配置项与存储布局core/config.py的Config类集中管理全部配置支持环境变量加载CODE_AGENT_配置项大写或传统命名与手动覆盖config.py。code_agent/README.md明确给出的覆盖变量HELLOAGENTS_DIR.helloagents状态存储根目录也可用CODE_AGENT_STATE_DIRCODE_AGENT_MAX_STEPS8ReAct 最大推理步数源码默认 20源码另支持CODE_AGENT_MAX_REACT_STEPS。其余可通过环境变量调节的常用项源码确认CODE_AGENT_PATCH_MAX_FILES默认 10、CODE_AGENT_PATCH_MAX_LINES默认 800、CODE_AGENT_TERMINAL_TIMEOUT默认 60 秒、LLM_TIMEOUT默认 60 秒、TEMPERATURE默认 0.7、LOG_LEVEL默认 INFO。上下文构建的独立配置ContextConfig见上文表格补丁确认阈值6 个文件 / 400 行对应Config.large_change_threshold_files/large_change_threshold_lines。约束与已知限制目前敏感操作确认优先覆盖Delete File、git reset --hard、rm/chmod、大规模变更更细粒度的策略如按命令/路径/目录的白名单后续可扩展TerminalTool仍是字符串命令入口但非 shell 模式执行为 argv-only并在工具内拦截 shell 语义重定向/命令替换/危险命令需确认更严格的参数级白名单可以继续收紧补丁应用依赖上下文精确匹配若文件在生成补丁后被改动Update File可能失败并给出recheck_targets提示需要人工复核记忆默认只启用 episodic 类型semantic/perceptual/working 等其他记忆类型memory/types/下均有实现未在 Code Agent 中启用。相关文件索引CLI 入口code_agent/hello_code_cli.py主逻辑/上下文工程code_agent/agentic/code_agent.py补丁执行器code_agent/executors/apply_patch_executor.py提示词模板code_agent/prompts/system.md/react.md/plan.md/tools.md/summarize_observation.md终端安全工具tools/builtin/terminal_tool.py上下文构建 GSSCcontext/builder.py统一配置core/config.py依赖清单requirement.txt上下文工程原理解读可对照仓库文档 docs/chapter9/第九章 上下文工程.md如需深入理解 Code Agent 所依赖的组件原理可继续阅读仓库agents/、core/、memory/、tools/目录下的对应实现。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考