HelloAgents Code Agent CLI基于 ReAct 与安全补丁系统的本地代码智能助手实战指南【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents导读HelloAgents Code Agent CLI 是基于 HelloAgents 框架开发的智能代码助手提供类似 Claude Code / Codex 的交互式命令行体验让用户以自然语言驱动智能体在本地代码仓库内完成按需探索、分析与安全修改。本文以该项目的 README.md 为主线结合仓库源码CLI 入口、补丁执行器、ReAct 智能体、上下文构建器、工具实现等深入讲解其五层系统架构、ReAct 推理循环、GSSC 上下文流水线、安全补丁落盘机制与完整配置参数读者读完可以独立安装、运行并定制这个 Code Agent也能理解先证据后结论、补丁式写盘、人工确认这一套可复用的本地代码智能体设计范式。一、项目定位面向本地仓库的安全 Code AgentHelloAgents Code Agent CLI 的核心价值可概括为四点与 README.md 一致精准检索按需探索代码库先证据后结论避免全库扫描安全可控补丁式修改 原子写入 自动备份危险修改需人工确认智能推理基于 ReAct 范式支持多步推理与行动任务管理内置 Todo 系统可视化追踪多步骤任务进度工具丰富集成终端、上下文获取、Note 管理、记忆、规划等工具。从适用场景看它主要面向代码库探索与分析、智能代码修改与重构、局部功能修复与优化、项目结构理解、代码审查辅助以及技术演示与教学是一个工作区锁定在仓库根目录内的受限智能体——这一点从 code_agent/agentic/code_agent.py 中repo_root贯穿所有组件即可看出终端工具的工作区、上下文获取工具的搜索范围、补丁执行器的路径沙箱全部以仓库根目录为边界。二、系统架构五层职责分明的智能体骨架README 给出了完整的架构图按层次从上到下分别是用户交互层 (CLI) → hello_code_cli.py 智能体层 (Agents) → ReActAgent / PlanAgent 核心层 (Core) → LLM / Message / Config / Exceptions 能力层 (Capabilities) → ContextBuilder (GSSC流水线) / MemoryManager (多层记忆) 工具层 (Tools) → Terminal / ContextFetch / Note / Todo / Plan / Memory ... 执行器层 (Executors) → ApplyPatchExecutor安全补丁应用与文件操作对应到仓库目录结构见 项目结构章节各层职责如下层次核心模块职责Agents 层agents/react_agent.py、agents/plan_solve_agent.py、agents/reflection_agent.py、agents/simple_agent.pyReActAgent 是主引擎循环执行思考 → 行动 → 观察另有规划式、反思式、基础对话式 AgentCore 层core/llm.py、core/message.py、core/config.py、core/exceptions.pyHelloAgentsLLM 统一 LLM 接口支持 OpenAI / DeepSeek / Qwen 等Message 负责消息抽象与序列化Config 集中配置管理Context 层context/builder.pyContextBuilder 实现 GSSC 流水线ContextConfig 控制上下文预算ContextPacket 是信息包抽象Memory 层memory/manager.py、memory/types/MemoryManager 统一记忆管理接口类型覆盖 WorkingMemory、EpisodicMemory、SemanticMemory、PerceptualMemoryTools 层tools/registry.py、tools/builtin/、tools/base.pyToolRegistry 负责工具注册与管理builtin 目录内置终端、上下文获取、Note、Todo、Plan、Memory 等工具Executors 层code_agent/executors/apply_patch_executor.py补丁解析与安全应用是写盘的唯一通道从源码结构可以推断这个分层设计让对话入口CLI— 智能体决策Agents— 基础设施Core— 上下文/记忆Capabilities— 执行动作Tools/Executors各自独立、可替换其中CodeAgentcode_agent.py正是把各层组件装配起来的中枢。三、ReAct 推理引擎思考、行动与观察的循环3.1 核心循环ReActReasoning and Acting是本项目智能推理的基础。ReActAgentagents/react_agent.py在每个步骤内用提示词模板拼接工具描述、当前问题与执行历史调用 LLM解析输出得到Thought思考与Action行动两部分若行动是Finish[最终答案]结束循环返回答案否则解析tool_name[tool_input]通过ToolRegistry执行工具把结果作为Observation追加进历史进入下一步。解析器兼容多种模型输出变体全角冒号、中文标签思考/行动、Markdown 强调**Thought:**并且在 Action 内使用括号匹配算法而非贪婪正则以正确处理嵌套 JSON 参数见_parse_action。3.2 三个工程化兜底机制从源码看ReActAgent 针对真实环境中的失败模式做了三层兜底格式修复当模型输出无法解析出 Action 时会用一条严格格式指令让 LLM 重写一次输出repair_sys避免模型闲聊/混用 Markdown 导致循环卡死重复行动检测early_stop_on_repeatTrue时若连续repeat_action_threshold默认 2次执行相同工具名|参数且无明显进展会主动终止并提示模型停止继续调用工具最大步数收敛达到max_steps仍未Finish时调用一次最终收敛器finalize prompt让 LLM 基于已有 Thought/Action/Observation 历史给出尽可能有用的最终回答若再次失败则返回兜底文案。此外CodeAgent在创建 ReActAgent 时注入了observation_summarizercode_agent.py 的_summarize_observation当工具原始输出超过summarize_threshold_chars默认 1800 字符时先用专门的摘要提示词code_agent/prompts/summarize_observation.md把工具输出压缩到约 400 tokens 再进入上下文防止终端输出撑爆 Prompt——这是上下文预算控制在循环层面的直接体现。四、安全补丁系统补丁式写盘与多层防护这是本项目最有工程价值的部分。补丁Patch是模型向仓库写盘的唯一通道CLI 与执行器围绕它构建了完整的安全链路。4.1 补丁格式模型在Finish[...]中输出 Codex 风格补丁*** Begin Patch *** Update File: src/example.py # 修改后的代码 *** End Patch支持三种操作*** Add File: path新增、*** Update File: path更新、*** Delete File: path删除。4.2 CLI 侧的提取与确认hello_code_cli.pycode_agent/hello_code_cli.py 负责在每轮对话后处理响应中的补丁提取_extract_patch先用PATCH_FENCE_RE匹配代码围栏patch/diff/text内的补丁再退回PATCH_RE宽松匹配*** Begin Patch ... *** End Patch规范化_normalize_patch容忍模型的格式瑕疵——若Add File:/Update File:/Delete File:缺少前导***会自动补齐风险分级_patch_requires_confirmation判定三类高风险补丁必须二次确认y/n包含*** Delete File:删除操作涉及文件数 ≥ 6 个变更行数/-开头的行≥ 400 行应用与记录调用ApplyPatchExecutor.apply()落盘成功后自动通过 NoteTool 写入一条patch_applied行动笔记失败则写入patch_failed阻塞笔记便于后续排查。4.3 执行器侧的五层安全防护apply_patch_executor.pycode_agent/executors/apply_patch_executor.py 的ApplyPatchExecutor将安全设计落到文件系统层面安全特性实现位置说明路径沙箱_safe_path拒绝绝对路径与~开头路径resolve()后校验必须以 repo_root 为前缀防止路径遍历逃逸拒绝修改符号链接后缀白名单_enforce_suffix默认仅允许.py .md .toml .json .yml .yaml .txt .html .htm .css .js防止误改二进制或敏感文件规模限制apply()单补丁最多max_files默认 10个文件、最多max_total_changed_lines默认 800行超限即抛PatchApplyError原子写入_atomic_write先写临时文件并os.fsync再用os.replace原子替换目标避免写入中断导致文件损坏自动备份_backup_file每次应用前将原文件复制到repo/.helloagents/backups/时间戳/下、后缀.bak删除操作同样先备份在Update File的 hunk 应用上执行器采用精确上下文匹配将 payload 按分隔符或空行拆成多个 hunk每个 hunk 分离出 before上下文 删除行与 after上下文 新增行在文件中查找 before 的精确子序列并替换匹配失败时先尝试忽略行尾空白的宽松匹配仍失败则抛出带recheck_targets提示的错误最后还有整文件替换兜底payload 不含任何/-/空格前缀行时视为新完整文件。这套机制保证了补丁不会静默错位地写入错误位置。五、GSSC 上下文流水线多源信息的结构化组织5.1 流水线四阶段ContextBuildercontext/builder.py实现了 README 中描述的 GSSC 流水线用户查询 → 收集信息(Gather) → 相关性筛选(Select) → 结构化组织(Structure) → Token压缩(Compress) → 生成回复Gather收集系统指令、最近 N 轮对话历史、记忆检索结果memory_tool、RAG 证据rag_tool、额外上下文包Select以关键词重叠计算相关性结合指数衰减的新近性recency_score时间尺度 1 小时得到复合分0.7×相关性 0.3×新近性系统指令与对话历史强制保留其余按min_relevance默认 0.3过滤、按 token 预算get_available_tokens默认 8000×(1−0.15)择优填充Structure组织为[Role Policies] / [Task] / [State] / [Evidence] / [Recent Conversation] / [Output]分段模板Compress超出预算时优先用 LLM 压缩保留分段标题与关键约束/证据失败则退化为按段落截断token 计数基于 tiktokencl100k_base不可用时按 1 token ≈ 4 字符估算。5.2 按需探索lazy_fetch模式CodeAgent 实际采用lazy_fetchTruecode_agent.py 中的ContextConfig只自动注入保底上下文系统指令 最近对话 上次工具摘要不再主动查询 memory/RAG扩展上下文代码、笔记、记忆改由模型在证据不足时通过context_fetch工具自行按需获取。这正是 README 所说先证据后结论避免全库扫描的实现机制与 Claude Code 的按需探索理念一致。保底上下文的结构化模板_structure_base包含[Role Policies]系统指令、[Context]对话历史、[Evidence]上次工具摘要、[State]待确认状态、[Task]用户查询五个区块其中[Context]区块在系统提示词code_agent/prompts/system.md中被明确告知模型用户询问之前聊了什么时只总结该区块的对话记录避免把系统规则和工具定义误当作对话内容。六、工具生态六个内置工具的职责与调用约定README 用表格概括了六类工具结合源码可进一步明确各自的调用格式tools/builtin/目录调用约定见 react.md工具功能描述调用示例关键实现点Terminal Tool安全终端执行terminal[{command:rg -n \ContextBuilder\ -S .,allow_dangerous:false}]命令白名单 shell 语义检测 危险命令确认见下Context Fetch Tool按需聚合检索context_fetch[{sources:[files,notes],query:ContextBuilder,paths:context/**/*.py}]一次调用多源每源 ~800 tokens 预算带 LRU 缓存20 条Note Tool笔记增删改查note[{action:create,title:...,content:...,note_type:task_state,tags:[...]}]结构化笔记类型含 blocker/insight/decision 等Todo Tool多步任务跟踪todo[{action:add,title:...,status:pending}]状态机 pending → in_progress → completed同时仅允许 1 个 in_progressPlan Tool规划生成plan[目标文本]由 LLM 生成分步计划prompt 模板为code_agent/prompts/plan.mdMemory Tool跨会话记忆memory[{action:add,memory_type:episodic,content:...,importance:0.6}]情景记忆持久化SQLite需显式 add其中 Terminal Tooltools/builtin/terminal_tool.py的安全模型最值得关注命令白名单ALLOWED_COMMANDS仅允许ls/cat/head/tail/find/grep/rg/wc/sort/uniq/sed/echo/mkdir/pwd/cd/git等只读与信息类命令Shell 模式支持管道|、、;等 shell 语义体验类似 Claude Code但_shell_requires_allow_dangerous会识别写盘重定向/排除/dev/null、命令替换$()/反引号、rm/chmod、git reset --hard等高风险点未放行时拒绝执行重定向到/dev/null、|| echo等只读掩埋写法可放宽危险命令确认confirm_dangerousTrue时高风险命令执行前弹出(y/n)交互确认Git 限制未放行时仅允许git status/git diff只读子命令git reset --hard需显式放行路径沙箱cd、mkdir、以及放行后的rm/chmod都会校验目标路径必须落在工作区内。ContextFetchTooltools/builtin/context_fetch_tool.py则用 ripgrep 实现代码检索rg -n -C 5可按pathsglob 限定范围命中结果按文件分组、按 budget 截断返回ripgrep 不可用时自动降级为grep。七、快速开始从克隆到首次对话7.1 环境要求Python3.10 或更高版本依赖hello-agents[all]0.2.7等见 requirement.txt操作系统macOS / Linux / Windows需要一个 OpenAI 兼容的 LLM 服务DeepSeek、OpenAI、Qwen、Kimi、智谱、Ollama、vLLM 等均可。7.2 安装步骤# 1. 克隆项目 git clone repository-url cd YYHDBL-HelloCodeAgentCli # 2. 创建虚拟环境 python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate # 3. 安装依赖 pip install -r requirements.txt7.3 配置环境变量在仓库根目录创建.env文件# LLM 配置必需 LLM_BASE_URLhttps://api.deepseek.com LLM_MODELdeepseek-chat DEEPSEEK_API_KEYsk-xxxxxxxxxxxxHelloAgentsLLMcore/llm.py采用参数优先、环境变量兜底策略provider 自动检测依次依据特定厂商环境变量OPENAI_API_KEY、DEEPSEEK_API_KEY、DASHSCOPE_API_KEY、MODELSCOPE_API_KEY、KIMI_API_KEY/MOONSHOT_API_KEY、ZHIPU_API_KEY/GLM_API_KEY、OLLAMA_API_KEY/OLLAMA_HOST、VLLM_API_KEY/VLLM_HOST、API Key 格式ms-前缀 → ModelScope、含点号 → 智谱等与 base_urlapi.deepseek.com→ deepseek、localhost/127.0.0.1→ 本地部署三级推断。模型未指定时自动选择各厂商默认模型deepseek-chat、qwen-plus、glm-4、llama3.2 等请求超时默认 60 秒LLM_TIMEOUT。7.4 运行 CLI# 在当前目录启动 python -m code_agent.hello_code_cli --repo . # 指定其他代码库 python -m code_agent.hello_code_cli --repo /path/to/your/project启动时会显示工作区路径、LLM provider/model/base_url 与状态目录并执行一次ping预检——若 API key/base_url 配置有误会直接提示检查.env中的DEEPSEEK_API_KEY/LLM_*配置并以退出码 2 结束。八、使用指南交互式命令行详解8.1 基础用法启动后进入交互式命令行直接输入自然语言需求即可 HelloAgents Code Agent CLI Repo: /path/to/project 输入 help 查看帮助exit 退出 帮我分析 src/main.py 的入口函数 Thought: 需要先获取文件内容 Action: context_fetch[pathsrc/main.py] Observation: [文件内容] Thought: 已获取内容开始分析 Action: Finish[分析结果...]内置命令见 hello_code_cli.py 交互循环命令作用:quit/:q/exit/quit退出 CLI:plan 目标强制调用 plan 工具生成执行计划平时由模型按需调用任意自然语言进入一轮 ReAct 对话y/n可对高风险补丁直接表态CodeAgent.run_turncode_agent.py对两类输入做了快捷处理问候/闲聊hi/hello/你好等直接回复不调用工具回顾刚才说了什么类元请求则从本地历史生成摘要。当用户输入包含分步/步骤/计划/改造/多步等词汇时会在系统指令后追加多步骤提示建议先todo add记录、结尾todo list汇总。每轮对话结束后会话以 JSON 持久化到repo/.helloagents/sessions/。8.2 命令行参数python -m code_agent.hello_code_cli [OPTIONS] 选项 --repo PATH 代码库路径默认当前目录 --model TEXT LLM 模型名称 --api-key TEXT API 密钥 --base-url TEXT API 基础 URL --max-steps INTEGER 最大推理步数默认15 --enable-memory 启用记忆系统 --enable-rag 启用 RAG 检索 --debug 调试模式 --help 显示帮助信息注当前仓库中的 CLI 入口实际解析的参数为--repo仓库根目录与--project项目名默认取仓库目录名其余选项在 code_agent/README.md 中作为可扩展方向说明LLM 相关配置建议通过环境变量/.env提供.env会被自动加载到repo_root/.envload_dotenv(overrideFalse)。8.3 配置项一览环境变量Configcore/config.py集中管理全部配置支持环境变量覆盖与默认值类别配置项环境变量默认值基础调试模式 / 日志级别DEBUG/CODE_AGENT_DEBUG、LOG_LEVELfalse / INFOLLM温度 / 超时TEMPERATURE、LLM_TIMEOUT0.7 / 60sAgent最大 ReAct 步数CODE_AGENT_MAX_REACT_STEPS或CODE_AGENT_MAX_STEPS20上下文最大 token / 预留比例 / 压缩 / 按需获取代码内配置项8000 / 0.15 / true / true终端超时 / 危险命令确认 / Shell 模式CODE_AGENT_TERMINAL_TIMEOUT60s / true / true补丁最大文件数 / 最大总行数CODE_AGENT_PATCH_MAX_FILES、CODE_AGENT_PATCH_MAX_LINES10 / 800存储状态目录HELLOAGENTS_DIR或CODE_AGENT_STATE_DIR.helloagents安全删除确认 / 大规模变更阈值代码内配置项文件 ≥6 或行 ≥400 需确认所有状态笔记、记忆、会话、备份、Todo默认落在repo/.helloagents/目录下可整体通过HELLOAGENTS_DIR重定向。九、补丁生产规范给模型的关键约束补丁能否被正确解析取决于输出格式。CLI 的提取器虽然做了规范化兜底但模型侧仍须遵循 react.md 与 system.md 中强调的格式要求正确格式说明文字与补丁之间空行分隔*** Begin Patch/*** End Patch各自独占一行不用 包裹Finish[ 已为 testDemo/hello.html 添加样式。 *** Begin Patch *** Update File: testDemo/hello.html !DOCTYPE html html head style body { background: #f0f0f0; } /style /head body h1Hello World/h1 /body /html *** End Patch ]常见错误❌ 错误1补丁前有冒号 Finish[补丁如下*** Begin Patch...] ❌ 错误2补丁前有文字在同一行 Finish[这是补丁 *** Begin Patch...] ❌ 错误3没有空行分隔 Finish[已添加样式\n*** Begin Patch...]行为准则方面系统提示词要求模型先证据后结论回答项目结构类问题前先用 terminal 取证、写盘唯一通道是补丁严禁cat /tee/ Here-Doc / 重定向等终端写法、删除文件/大改动先解释风险并征求确认以及拿到足够证据必须Finish[...]结束不要重复调用相同工具。十、项目结构YYHDBL-HelloCodeAgentCli/ ├── agents/ # 智能体实现 │ ├── react_agent.py # ReAct 范式 │ ├── plan_solve_agent.py # 规划式 Agent │ ├── reflection_agent.py # 反思式 Agent │ └── simple_agent.py # 简单对话 Agent ├── code_agent/ # 主应用 │ ├── hello_code_cli.py # CLI 入口 │ ├── agentic/code_agent.py # Code Agent 实现 │ ├── executors/apply_patch_executor.py # 补丁执行器 │ └── prompts/ # 提示词模板system/react/plan/tools 等 ├── core/ # 核心模块agent/llm/message/config/exceptions ├── context/ # 上下文构建builder.py 实现 GSSC 流水线 ├── memory/ # 记忆系统manager/base/embedding/types/storage/rag ├── tools/ # 工具系统base/registry/chain/builtin └── utils/ # 工具函数cli_ui/helpers/logging/serialization十一、已知限制与未来规划README 中列出了明确的演进方向会话恢复支持断点续传自动恢复摘要细分终端命令工具将 Terminal Tool 拆分为原子性的命令工具改写 Note Tool与改写记忆系统原文未展开细节。从 code_agent/README.md 还能看到当前版本已知约束敏感操作确认目前优先覆盖Delete File、git reset --hard、rm/chmod与大规模变更Terminal Tool 仍是字符串命令入口执行为 argv-only 并在工具内拦截 shell 语义更严格的参数级白名单可继续收紧存储布局默认使用repo/.helloagents/。结语HelloAgents Code Agent CLI 的价值不在于堆砌功能而在于把本地代码智能体最关键的三个问题——证据从哪来按需探索 context_fetch 聚合检索、如何安全写盘补丁 路径沙箱 原子写入 备份 人工确认、上下文如何不失控GSSC 预算控制 工具输出摘要——用清晰的分层架构与可配置的安全策略落了地。对于想深入理解 Claude Code / Codex 类工具内部机制、或需要在自己仓库里搭建一个可控 Code Agent 的开发者这份源码是很好的参考起点从 hello_code_cli.py 读入口沿 code_agent.py 看装配再到 apply_patch_executor.py 和 builder.py 看安全与上下文即可获得一条完整的实现脉络。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考