HelloAgents Code Agent CLI 项目结构深度解析从目录设计看本地代码智能体的分层架构【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agents本篇文章以 HelloAgents Code Agent CLI 的项目结构分析为核心主线逐层拆解这个面向本地代码仓库的智能 Code Agent 命令行工具的目录组织、模块职责与依赖配置体系。读者通过本文可以掌握一个生产级 Agent 项目的标准分层方法——从 CLI 交互层、智能体层、核心层到能力层与工具层的完整架构脉络并理解 ReAct 推理循环、GSSC 上下文流水线、安全补丁系统等核心机制分别落在哪个模块、由哪些代码实现。项目定位一个类 Claude Code / Codex 的本地代码智能体在深入目录结构之前先明确项目整体定位。根据 README.md 的说明HelloAgents Code Agent CLI是一个基于 HelloAgents 框架开发的智能代码助手提供类似 Claude Code / Codex 的交互体验专注于本地代码仓库的安全智能操作。其核心价值可归纳为四点精准检索按需探索代码库先证据后结论避免全库扫描安全可控补丁式修改 原子写入 自动备份危险修改需人工确认智能推理基于 ReAct 范式支持多步推理与行动任务管理内置 Todo 系统可视化追踪多步骤任务进度。项目采用 Python 编写要求 Python 3.10跨平台支持 macOS / Linux / Windows。该定位决定了其目录结构必须以可扩展的 Agent 框架而非单文件脚本的方式组织——这正是本文要拆解的核心。顶层目录一张模块化设计的组织地图项目的目录结构是理解整个系统的第一把钥匙。从仓库根目录Co-creation-projects/YYHDBL-HelloCodeAgentCli/看顶层共 8 个源码/内容目录加 1 个根文件每一层都对应一类明确职责目录职责核心载体agents/智能体实现四种范式react_agent.pycode_agent/主应用CLI 入口 执行器 提示词hello_code_cli.pycontext/上下文构建GSSC 流水线builder.pycore/核心框架LLM / 配置 / 消息 / 异常llm.py、config.pymemory/记忆系统四种类型 存储后端 RAGmanager.pytools/工具系统注册表 内置工具集registry.py、builtin/utils/通用工具函数CLI 界面 / 日志 / 序列化cli_ui.py这种按职责分目录的设计遵循了经典的分层架构思想上层依赖下层、同层之间通过接口协作。从调用链看code_agent/主应用依赖agents/智能体、core/核心、context/上下文、tools/工具而agents/又依赖core/与tools/。每一层的内部实现细节被封装在模块内部对外只暴露清晰的类与函数接口。配置与依赖管理环境变量、状态目录与依赖拆分项目结构的另一个重要维度是非代码资源的组织方式这在原结构笔记中占据了重要篇幅。环境变量与 LLM 配置项目通过.env文件承载环境变量配置由 CLI 入口在启动时加载# 见 code_agent/hello_code_cli.py load_dotenv(dotenv_pathrepo_root / .env, overrideFalse)最小化配置示例摘自 README.md 快速开始章节# LLM 配置必需 LLM_BASE_URLhttps://api.deepseek.com LLM_MODELdeepseek-chat DEEPSEEK_API_KEYsk-xxxxxxxxxxxx配置读取并非散落在各模块而是集中在 core/config.py 的Config类中统一管理。Config基于 pydantic 的BaseModel实现按主题划分为 7 大配置段基础配置debug、log_levelLLM 配置default_model、default_provider、temperature默认 0.7、max_tokens、llm_timeout默认 60 秒Agent 配置max_react_steps默认 20上限 50、max_history_turns默认 50、observation_summary_threshold上下文配置context_max_tokens默认 8000、context_reserve_ratio默认 0.15、context_enable_compression、context_lazy_fetch默认 True工具配置terminal_timeout默认 60 秒、terminal_max_output_size默认 10MB、terminal_confirm_dangerous、context_fetch_max_tokens默认 800、context_fetch_context_lines默认 5补丁执行器配置patch_max_files默认 10、patch_max_total_lines默认 800、patch_allowed_suffixes白名单后缀存储与安全配置helloagents_dir默认.helloagents、confirm_delete_files、large_change_threshold_files默认 6、large_change_threshold_lines默认 400。Config.from_env()提供了统一的环境变量读取入口支持CODE_AGENT_配置项大写与传统命名的双轨读取。这意味着所有运行时行为如终端超时、补丁规模上限、是否启用压缩都可以通过环境变量无侵入式调整无需改动代码。状态目录.helloagents.helloagents是项目约定的状态存储目录集中存放运行时产生的所有过程资产。从 code_agent.py 中CodeAgentPaths的定义可以看到其完整子结构.helloagents/ ├── notes/ # 结构化笔记Agent 的长期记忆载体 ├── memory/ # 记忆系统存储 ├── sessions/ # 会话持久化JSON ├── todos/ # Todo 任务看板 ├── backups/ # 补丁应用前的自动备份时间戳命名 └── logs/ # 日志其中notes/目录内的笔记文件采用Markdown YAML 前置元数据的格式如本系列结构分析笔记本身所示包含id、title、type、tags、created_at、updated_at等字段与 note_tool.py 中_note_to_markdown的实现一一对应。这种设计让Agent 的记忆既是机器可读的结构化数据又是人类可读的 Markdown 文档。依赖管理原结构笔记提到依赖采用拆分管理思路实际仓库中依赖集中声明在 requirement.txtopenai1.0.0 pydantic2.0.0 python-dotenv1.0.0 tiktoken0.5.0 hello-agents[all]0.2.7依赖选择上有两个值得注意的工程决策hello-agents[all]0.2.7项目本身是 HelloAgents 生态下的应用直接依赖框架包含[all]扩展说明其用到了框架的可选能力tiktoken用于上下文的 token 精确计数——这是 context/builder.py 中count_tokens的实现基础它使用cl100k_base编码器失败时降级为1 token ≈ 4 字符的估算策略。核心层core/Agent 的操作系统core/是全部上层模块的公共底座共 6 个文件职责高度内聚llm.pyHelloAgentsLLM统一 LLM 接口。源码中最具特色的是Provider 自动检测_auto_detect_provider它按特定环境变量 → API Key 格式 → base_url 特征三级顺序推断服务商支持 openai / deepseek / qwen / modelscope / kimi / zhipu / ollama / vllm / local / auto 共 10 种来源。若推理失败_resolve_credentials会为每种 Provider 回填默认的 base_url 与默认模型如 DeepSeek 对应https://api.deepseek.com与deepseek-chatconfig.py上文已详述的统一配置中心message.pyMessage消息抽象携带 role、content、timestamp是对话历史与记忆的通用载体agent.pyAgent基类定义所有智能体的公共生命周期如add_message历史写入exceptions.pyHelloAgentsException统一异常体系LLM 调用失败、配置缺失等错误都被包装为该类型便于上层统一捕获与提示。CLI 启动时对 core 层有一个巧妙的预检用法hello_code_cli.py先调用一次llm.invoke([{role: user, content: ping}], max_tokens1)若抛出HelloAgentsException则立即以退出码 2 结束并提示检查 API key / base_url / model把认证问题在最早期暴露给用户。智能体层agents/四种范式并存agents/目录实现了四种智能体范式对应 README.md 中的 Agent 层描述文件范式特点react_agent.pyReAct主引擎循环执行思考→行动→观察plan_solve_agent.pyPlan-and-Solve规划式任务分解reflection_agent.pyReflection自我反思与优化simple_agent.pySimple基础对话型 Agent其中ReActAgent是 Code Agent 的运行时核心其实现细节体现了大量针对真实模型输出的工程化容错宽容的输出解析_parse_output同时兼容全角/半角冒号、Thought/思考中英文标签、Markdown 强调符**Thought:**并在 action 中截断可能混入的多轮循环内容括号匹配而非正则_parse_action用深度计数 字符串状态机解析工具名[参数]正确处理嵌套 JSON避免贪婪正则的误匹配格式修复重试当 LLM 输出无法解析出合法 Action 时追加一条严格两行格式的 system 指令让模型重写一次重复行动检测相同 action 连续出现repeat_action_threshold默认 2次时提前终止避免死循环最大步数兜底收敛finalize_on_max_steps超过max_steps仍未 Finish 时以最终收敛器提示词让模型基于已有 Thought/Action/Observation 轨迹给出总结性回答。此外 ReActAgent 支持observation_summarizer回调——当工具输出超过阈值Code Agent 中配置为 1800 字符时先用 LLM 压缩再注入下一轮 Prompt这正是避免上下文爆炸的关键手段。上下文层context/GSSC 流水线与按需探索context/builder.py 实现了GSSC 流水线Gather-Select-Structure-Compress是项目最值得一提的上下文工程实践用户查询 → 收集信息(Gather) → 相关性筛选(Select) → 结构化组织(Structure) → Token压缩(Compress) → 生成回复四个阶段在代码中各有对应实现Gather_gather收集系统指令、最近对话历史以及在lazy_fetchFalse传统模式下记忆与 RAG 检索结果Select_select计算相关性关键词重叠与新近性1 小时时间尺度的指数衰减按0.7 × 相关性 0.3 × 新近性复合打分系统指令与对话历史被强制保留扩展上下文需满足min_relevance默认 0.3并在 token 预算内按分择优MMR 多样性控制在配置中可开关Structure_structure/_structure_base组织成[Role Policies]、[Task]、[State]、[Evidence]、[Recent Conversation]、[Output]的分段模板其中[Output]还内置了结论/依据/风险/下一步的格式约束Compress_compress超预算时优先用 LLM 高保真压缩保留结构标题与关键证据LLM 压缩失败则退化为按段落截断。最值得关注的是lazy_fetch按需探索模式。借鉴 Claude Code 的设计理念code_agent.py 将lazy_fetchTrue只构建系统提示 对话历史 上次工具摘要的保底上下文而记忆、RAG 等扩展信息一律不再主动注入改由模型通过context_fetch工具在推理过程中按需获取。这一设计大幅降低了每轮 Prompt 的固定开销让先证据后结论从理念变成了架构。工具层tools/能力注册表与内置工具集tools/是 Agent 的行动接口围绕ToolRegistry设计base.pyTool基类与ToolParameter参数定义所有工具必须实现run(parameters)与get_parameters()registry.py工具注册与执行分发chain.py 与 async_executor.py工具链编排与异步执行builtin/9 个内置工具。内置工具按用途可归纳为下表工具文件功能Terminal Toolterminal_tool.py安全终端执行白名单 沙箱Context Fetch Toolcontext_fetch_tool.py按需读取文件/目录单源 800 tokenNote Toolnote_tool.py笔记增删改查与搜索Todo Tooltodo_tool.py多步任务进度可视化Plan Toolplan_tool.py复杂任务分解与执行计划Memory Toolmemory_tool.py长期知识存储与检索MCP 包装 / 协议 / 其他mcp_wrapper_tool.py 等MCP 工具接入与协议支持TerminalTool是安全设计的集中体现其安全防线可分为五层命令白名单ALLOWED_COMMANDS仅放行 ls/cat/grep/wc 等只读命令并限制 git 仅可执行 status/diff路径沙箱cd与所有路径参数都被relative_to(workspace)限制在仓库内shell 元字符检测对|、、;、、$()等特殊字符逐一判定写盘与命令替换必须显式allow_dangerous危险命令确认rm/chmod 及git reset --hard触发人工 y/n 确认超时与输出上限默认 60 秒、10MB 截断。NoteTool则承担Agent 的记事本角色支持task_state任务状态、conclusion结论、blocker阻塞项、action行动计划、reference参考、general通用六种笔记类型配合notes_index.json索引实现快速搜索——本系列项目结构分析笔记本身就是 NoteTool 产出格式的实例。执行器层与主应用code_agent/安全补丁与交互循环code_agent/是项目的可执行外壳包含三个子模块hello_code_cli.pyargparse 命令行入口agentic/code_agent.py组装一切组件工具注册、ContextBuilder、ReActAgent、会话持久化的编排核心executors/apply_patch_executor.py安全补丁引擎prompts/system.md、react.md、plan.md、tools.md、summarize_observation.md五份提示词模板以文件而非字符串硬编码便于独立迭代。CLI 命令参数python -m code_agent.hello_code_cli [OPTIONS] 选项 --repo PATH 代码库路径默认当前目录 --project TEXT 项目名称默认仓库文件夹名 --help 显示帮助信息启动方式摘自 README.mdpython -m code_agent.hello_code_cli --repo . python -m code_agent.hello_code_cli --repo /path/to/your/project进入交互式命令行后支持自然语言输入与:quit退出、:plan 目标强制生成计划两类内部命令。一个典型会话片段摘自 README为 帮我分析 src/main.py 的入口函数 Thought: 需要先获取文件内容 Action: context_fetch[pathsrc/main.py] Observation: [文件内容] Thought: 已获取内容开始分析 Action: Finish[分析结果...]补丁提取与应用流程CLI 与执行器之间通过 Codex 风格补丁协议衔接流程位于 hello_code_cli.py提取_extract_patch正则匹配*** Begin Patch ... *** End Patch块优先识别patch /diff 代码围栏内的补丁规范化_normalize_patch宽容处理模型输出的格式错误为缺失***前缀的Add File:/Update File:/Delete File:自动补前缀风险判定_patch_requires_confirmation包含文件删除、涉及文件数 ≥ 6、或变更行数 ≥ 400 时判定为高风险要求人工 y/n 确认执行调用ApplyPatchExecutor.apply()落盘成功后自动将补丁记录为action类型笔记失败则记录为blocker类型笔记打上patch_failed标签供后续会话复盘。ApplyPatchExecutor 的安全机制apply_patch_executor.py 是修改代码环节的最后一道防线实现了五重安全特性路径逃逸防护_safe_path拒绝绝对路径与~开头路径resolve()后必须位于 repo_root 内拒绝符号链接后缀白名单_enforce_suffix仅允许.py/.md/.toml/.json/.yml/.yaml/.txt/.html/.htm/.css/.js等文本后缀防止修改二进制或敏感文件原子写入_atomic_write临时文件 os.fsyncos.replace保证写入过程中断不会损坏目标文件自动备份_backup_file每次应用前将原文件备份到.helloagents/backups/时间戳/并保留相对路径结构与.bak后缀冲突检测_apply_hunk/_find_subsequenceUpdate 操作按 hunk 精确匹配上下文匹配失败时抛PatchApplyError并附带file:search:上下文行形式的recheck_targets提示辅助模型定位漂移位置若模型输出无/-前缀则视为整文件替换并支持匹配失败后按 after 内容回退重建。补丁支持Add File新建已存在则报错、Update File修改先备份再匹配替换、Delete File删除先备份三类操作且受max_files默认 10与max_total_changed_lines默认 800双重规模限制。记忆系统memory/四型记忆与多后端存储memory/目录体现了对 Agent 记忆的分层抽象按类型 × 存储 × 检索三个维度组织base.py记忆的基础抽象types/四种记忆类型——working.py工作记忆、episodic.py情景记忆、semantic.py语义记忆、perceptual.py感知记忆storage/多种存储后端——document_store.py文档存储、qdrant_store.py向量存储、neo4j_store.py图存储rag/document.py与pipeline.py构成 RAG 检索管线embedding.py嵌入模型封装manager.pyMemoryManager统一入口屏蔽底层存储差异。从架构上看记忆系统被设计为可插拔能力在 Code Agent 的当前配置中memory_tool传入None以配合lazy_fetchTrue的按需模式code_agent.py记忆的读写权完全交给模型通过工具自行决定而当lazy_fetchFalse时ContextBuilder._gather会主动调用MemoryTool.execute(search, ...)按min_importance过滤任务状态记忆。两种模式的切换只需改动一行配置体现了配置驱动能力的设计取向。工具函数层utils/可复用能力底座utils/存放跨模块复用的基础设施cli_ui.py终端渲染c颜色函数、hr分隔线、Spinner加载动画、clamp_text文本裁剪、log_tool_event工具事件日志helpers.py通用辅助函数logging.py日志配置serialization.py序列化工具。其中cli_ui.py的作用在 CLI 体验中随处可见——例如 ReAct 循环中每步的--- Step N/20 ---分段提示、 code_agent前缀、以及启动横幅中的彩色分隔线均由该模块提供。从结构到架构一条完整的数据流将以上各层串联起来一次完整的 Code Agent 交互如修复 src/util.py 中的某个 bug的数据流为CLI 层hello_code_cli.py解析参数、加载.env、预检 LLM构造CodeAgent与ApplyPatchExecutor编排层code_agent.py调用ContextBuilder.build_base构建保底上下文系统提示 历史 上次工具摘要识别多步任务关键词时附加 Todo 提示推理层ReActAgent.run进入思考-行动-观察循环按需调用注册表中的terminal/context_fetch/note/todo/plan工具超长观察被 LLM 摘要压缩重复行动被检测终止证据回流本轮工具执行摘要被封装为ContextPacket存入recent_tool_packets缓冲区最多 8 条供下一轮构建[Evidence]段落会话持久化每轮对话追加到history保留最近 50 条并写入.helloagents/sessions/session_*.json补丁闭环CLI 从响应中提取补丁风险判定后交由ApplyPatchExecutor执行备份 → 原子写入 → 冲突检测结果以action/blocker笔记沉淀到.helloagents/notes/。这一链路完整覆盖了理解仓库 → 制定方案 → 安全修改 → 记录沉淀的智能体工作闭环而整个仓库的分层目录正是为支撑这条链路而设计的——这正是阅读项目结构时最值得体会的工程思想。结语从顶层目录的职责划分到core/的统一底座、agents/的范式实现、context/的上下文流水线、tools/的能力注册、code_agent/的安全补丁闭环再到memory/的记忆分层与utils/的基础设施HelloAgents Code Agent CLI用一套清晰的分层目录结构将一个类 Claude Code / Codex 的本地代码智能体拆解为高内聚、低耦合、可独立演进与替换的模块集合。对于想要自研代码 Agent 的开发者而言这份结构本身就是一份值得参照的架构蓝图CLI 与逻辑分离、推理与工具解耦、上下文按需加载、修改必须安全可控。沿着本文给出的各模块入口CLI 主循环、ReAct 实现、补丁执行器、上下文流水线继续阅读源码即可由点及面地掌握整个系统的运行全貌。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/18 4:03:43 · 阅读 1.2k HelloAgents Code Agent CLI 项目结构深度解析：从目录设计看本地代码智能体的分层架构
HelloAgents Code Agent CLI 项目结构深度解析从目录设计看本地代码智能体的分层架构【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agents本篇文章以 HelloAgents Code Agent CLI 的项目结构分析为核心主线逐层拆解这个面向本地代码仓库的智能 Code Agent 命令行工具的目录组织、模块职责与依赖配置体系。读者通过本文可以掌握一个生产级 Agent 项目的标准分层方法——从 CLI 交互层、智能体层、核心层到能力层与工具层的完整架构脉络并理解 ReAct 推理循环、GSSC 上下文流水线、安全补丁系统等核心机制分别落在哪个模块、由哪些代码实现。项目定位一个类 Claude Code / Codex 的本地代码智能体在深入目录结构之前先明确项目整体定位。根据 README.md 的说明HelloAgents Code Agent CLI是一个基于 HelloAgents 框架开发的智能代码助手提供类似 Claude Code / Codex 的交互体验专注于本地代码仓库的安全智能操作。其核心价值可归纳为四点精准检索按需探索代码库先证据后结论避免全库扫描安全可控补丁式修改 原子写入 自动备份危险修改需人工确认智能推理基于 ReAct 范式支持多步推理与行动任务管理内置 Todo 系统可视化追踪多步骤任务进度。项目采用 Python 编写要求 Python 3.10跨平台支持 macOS / Linux / Windows。该定位决定了其目录结构必须以可扩展的 Agent 框架而非单文件脚本的方式组织——这正是本文要拆解的核心。顶层目录一张模块化设计的组织地图项目的目录结构是理解整个系统的第一把钥匙。从仓库根目录Co-creation-projects/YYHDBL-HelloCodeAgentCli/看顶层共 8 个源码/内容目录加 1 个根文件每一层都对应一类明确职责目录职责核心载体agents/智能体实现四种范式react_agent.pycode_agent/主应用CLI 入口 执行器 提示词hello_code_cli.pycontext/上下文构建GSSC 流水线builder.pycore/核心框架LLM / 配置 / 消息 / 异常llm.py、config.pymemory/记忆系统四种类型 存储后端 RAGmanager.pytools/工具系统注册表 内置工具集registry.py、builtin/utils/通用工具函数CLI 界面 / 日志 / 序列化cli_ui.py这种按职责分目录的设计遵循了经典的分层架构思想上层依赖下层、同层之间通过接口协作。从调用链看code_agent/主应用依赖agents/智能体、core/核心、context/上下文、tools/工具而agents/又依赖core/与tools/。每一层的内部实现细节被封装在模块内部对外只暴露清晰的类与函数接口。配置与依赖管理环境变量、状态目录与依赖拆分项目结构的另一个重要维度是非代码资源的组织方式这在原结构笔记中占据了重要篇幅。环境变量与 LLM 配置项目通过.env文件承载环境变量配置由 CLI 入口在启动时加载# 见 code_agent/hello_code_cli.py load_dotenv(dotenv_pathrepo_root / .env, overrideFalse)最小化配置示例摘自 README.md 快速开始章节# LLM 配置必需 LLM_BASE_URLhttps://api.deepseek.com LLM_MODELdeepseek-chat DEEPSEEK_API_KEYsk-xxxxxxxxxxxx配置读取并非散落在各模块而是集中在 core/config.py 的Config类中统一管理。Config基于 pydantic 的BaseModel实现按主题划分为 7 大配置段基础配置debug、log_levelLLM 配置default_model、default_provider、temperature默认 0.7、max_tokens、llm_timeout默认 60 秒Agent 配置max_react_steps默认 20上限 50、max_history_turns默认 50、observation_summary_threshold上下文配置context_max_tokens默认 8000、context_reserve_ratio默认 0.15、context_enable_compression、context_lazy_fetch默认 True工具配置terminal_timeout默认 60 秒、terminal_max_output_size默认 10MB、terminal_confirm_dangerous、context_fetch_max_tokens默认 800、context_fetch_context_lines默认 5补丁执行器配置patch_max_files默认 10、patch_max_total_lines默认 800、patch_allowed_suffixes白名单后缀存储与安全配置helloagents_dir默认.helloagents、confirm_delete_files、large_change_threshold_files默认 6、large_change_threshold_lines默认 400。Config.from_env()提供了统一的环境变量读取入口支持CODE_AGENT_配置项大写与传统命名的双轨读取。这意味着所有运行时行为如终端超时、补丁规模上限、是否启用压缩都可以通过环境变量无侵入式调整无需改动代码。状态目录.helloagents.helloagents是项目约定的状态存储目录集中存放运行时产生的所有过程资产。从 code_agent.py 中CodeAgentPaths的定义可以看到其完整子结构.helloagents/ ├── notes/ # 结构化笔记Agent 的长期记忆载体 ├── memory/ # 记忆系统存储 ├── sessions/ # 会话持久化JSON ├── todos/ # Todo 任务看板 ├── backups/ # 补丁应用前的自动备份时间戳命名 └── logs/ # 日志其中notes/目录内的笔记文件采用Markdown YAML 前置元数据的格式如本系列结构分析笔记本身所示包含id、title、type、tags、created_at、updated_at等字段与 note_tool.py 中_note_to_markdown的实现一一对应。这种设计让Agent 的记忆既是机器可读的结构化数据又是人类可读的 Markdown 文档。依赖管理原结构笔记提到依赖采用拆分管理思路实际仓库中依赖集中声明在 requirement.txtopenai1.0.0 pydantic2.0.0 python-dotenv1.0.0 tiktoken0.5.0 hello-agents[all]0.2.7依赖选择上有两个值得注意的工程决策hello-agents[all]0.2.7项目本身是 HelloAgents 生态下的应用直接依赖框架包含[all]扩展说明其用到了框架的可选能力tiktoken用于上下文的 token 精确计数——这是 context/builder.py 中count_tokens的实现基础它使用cl100k_base编码器失败时降级为1 token ≈ 4 字符的估算策略。核心层core/Agent 的操作系统core/是全部上层模块的公共底座共 6 个文件职责高度内聚llm.pyHelloAgentsLLM统一 LLM 接口。源码中最具特色的是Provider 自动检测_auto_detect_provider它按特定环境变量 → API Key 格式 → base_url 特征三级顺序推断服务商支持 openai / deepseek / qwen / modelscope / kimi / zhipu / ollama / vllm / local / auto 共 10 种来源。若推理失败_resolve_credentials会为每种 Provider 回填默认的 base_url 与默认模型如 DeepSeek 对应https://api.deepseek.com与deepseek-chatconfig.py上文已详述的统一配置中心message.pyMessage消息抽象携带 role、content、timestamp是对话历史与记忆的通用载体agent.pyAgent基类定义所有智能体的公共生命周期如add_message历史写入exceptions.pyHelloAgentsException统一异常体系LLM 调用失败、配置缺失等错误都被包装为该类型便于上层统一捕获与提示。CLI 启动时对 core 层有一个巧妙的预检用法hello_code_cli.py先调用一次llm.invoke([{role: user, content: ping}], max_tokens1)若抛出HelloAgentsException则立即以退出码 2 结束并提示检查 API key / base_url / model把认证问题在最早期暴露给用户。智能体层agents/四种范式并存agents/目录实现了四种智能体范式对应 README.md 中的 Agent 层描述文件范式特点react_agent.pyReAct主引擎循环执行思考→行动→观察plan_solve_agent.pyPlan-and-Solve规划式任务分解reflection_agent.pyReflection自我反思与优化simple_agent.pySimple基础对话型 Agent其中ReActAgent是 Code Agent 的运行时核心其实现细节体现了大量针对真实模型输出的工程化容错宽容的输出解析_parse_output同时兼容全角/半角冒号、Thought/思考中英文标签、Markdown 强调符**Thought:**并在 action 中截断可能混入的多轮循环内容括号匹配而非正则_parse_action用深度计数 字符串状态机解析工具名[参数]正确处理嵌套 JSON避免贪婪正则的误匹配格式修复重试当 LLM 输出无法解析出合法 Action 时追加一条严格两行格式的 system 指令让模型重写一次重复行动检测相同 action 连续出现repeat_action_threshold默认 2次时提前终止避免死循环最大步数兜底收敛finalize_on_max_steps超过max_steps仍未 Finish 时以最终收敛器提示词让模型基于已有 Thought/Action/Observation 轨迹给出总结性回答。此外 ReActAgent 支持observation_summarizer回调——当工具输出超过阈值Code Agent 中配置为 1800 字符时先用 LLM 压缩再注入下一轮 Prompt这正是避免上下文爆炸的关键手段。上下文层context/GSSC 流水线与按需探索context/builder.py 实现了GSSC 流水线Gather-Select-Structure-Compress是项目最值得一提的上下文工程实践用户查询 → 收集信息(Gather) → 相关性筛选(Select) → 结构化组织(Structure) → Token压缩(Compress) → 生成回复四个阶段在代码中各有对应实现Gather_gather收集系统指令、最近对话历史以及在lazy_fetchFalse传统模式下记忆与 RAG 检索结果Select_select计算相关性关键词重叠与新近性1 小时时间尺度的指数衰减按0.7 × 相关性 0.3 × 新近性复合打分系统指令与对话历史被强制保留扩展上下文需满足min_relevance默认 0.3并在 token 预算内按分择优MMR 多样性控制在配置中可开关Structure_structure/_structure_base组织成[Role Policies]、[Task]、[State]、[Evidence]、[Recent Conversation]、[Output]的分段模板其中[Output]还内置了结论/依据/风险/下一步的格式约束Compress_compress超预算时优先用 LLM 高保真压缩保留结构标题与关键证据LLM 压缩失败则退化为按段落截断。最值得关注的是lazy_fetch按需探索模式。借鉴 Claude Code 的设计理念code_agent.py 将lazy_fetchTrue只构建系统提示 对话历史 上次工具摘要的保底上下文而记忆、RAG 等扩展信息一律不再主动注入改由模型通过context_fetch工具在推理过程中按需获取。这一设计大幅降低了每轮 Prompt 的固定开销让先证据后结论从理念变成了架构。工具层tools/能力注册表与内置工具集tools/是 Agent 的行动接口围绕ToolRegistry设计base.pyTool基类与ToolParameter参数定义所有工具必须实现run(parameters)与get_parameters()registry.py工具注册与执行分发chain.py 与 async_executor.py工具链编排与异步执行builtin/9 个内置工具。内置工具按用途可归纳为下表工具文件功能Terminal Toolterminal_tool.py安全终端执行白名单 沙箱Context Fetch Toolcontext_fetch_tool.py按需读取文件/目录单源 800 tokenNote Toolnote_tool.py笔记增删改查与搜索Todo Tooltodo_tool.py多步任务进度可视化Plan Toolplan_tool.py复杂任务分解与执行计划Memory Toolmemory_tool.py长期知识存储与检索MCP 包装 / 协议 / 其他mcp_wrapper_tool.py 等MCP 工具接入与协议支持TerminalTool是安全设计的集中体现其安全防线可分为五层命令白名单ALLOWED_COMMANDS仅放行 ls/cat/grep/wc 等只读命令并限制 git 仅可执行 status/diff路径沙箱cd与所有路径参数都被relative_to(workspace)限制在仓库内shell 元字符检测对|、、;、、$()等特殊字符逐一判定写盘与命令替换必须显式allow_dangerous危险命令确认rm/chmod 及git reset --hard触发人工 y/n 确认超时与输出上限默认 60 秒、10MB 截断。NoteTool则承担Agent 的记事本角色支持task_state任务状态、conclusion结论、blocker阻塞项、action行动计划、reference参考、general通用六种笔记类型配合notes_index.json索引实现快速搜索——本系列项目结构分析笔记本身就是 NoteTool 产出格式的实例。执行器层与主应用code_agent/安全补丁与交互循环code_agent/是项目的可执行外壳包含三个子模块hello_code_cli.pyargparse 命令行入口agentic/code_agent.py组装一切组件工具注册、ContextBuilder、ReActAgent、会话持久化的编排核心executors/apply_patch_executor.py安全补丁引擎prompts/system.md、react.md、plan.md、tools.md、summarize_observation.md五份提示词模板以文件而非字符串硬编码便于独立迭代。CLI 命令参数python -m code_agent.hello_code_cli [OPTIONS] 选项 --repo PATH 代码库路径默认当前目录 --project TEXT 项目名称默认仓库文件夹名 --help 显示帮助信息启动方式摘自 README.mdpython -m code_agent.hello_code_cli --repo . python -m code_agent.hello_code_cli --repo /path/to/your/project进入交互式命令行后支持自然语言输入与:quit退出、:plan 目标强制生成计划两类内部命令。一个典型会话片段摘自 README为 帮我分析 src/main.py 的入口函数 Thought: 需要先获取文件内容 Action: context_fetch[pathsrc/main.py] Observation: [文件内容] Thought: 已获取内容开始分析 Action: Finish[分析结果...]补丁提取与应用流程CLI 与执行器之间通过 Codex 风格补丁协议衔接流程位于 hello_code_cli.py提取_extract_patch正则匹配*** Begin Patch ... *** End Patch块优先识别patch /diff 代码围栏内的补丁规范化_normalize_patch宽容处理模型输出的格式错误为缺失***前缀的Add File:/Update File:/Delete File:自动补前缀风险判定_patch_requires_confirmation包含文件删除、涉及文件数 ≥ 6、或变更行数 ≥ 400 时判定为高风险要求人工 y/n 确认执行调用ApplyPatchExecutor.apply()落盘成功后自动将补丁记录为action类型笔记失败则记录为blocker类型笔记打上patch_failed标签供后续会话复盘。ApplyPatchExecutor 的安全机制apply_patch_executor.py 是修改代码环节的最后一道防线实现了五重安全特性路径逃逸防护_safe_path拒绝绝对路径与~开头路径resolve()后必须位于 repo_root 内拒绝符号链接后缀白名单_enforce_suffix仅允许.py/.md/.toml/.json/.yml/.yaml/.txt/.html/.htm/.css/.js等文本后缀防止修改二进制或敏感文件原子写入_atomic_write临时文件 os.fsyncos.replace保证写入过程中断不会损坏目标文件自动备份_backup_file每次应用前将原文件备份到.helloagents/backups/时间戳/并保留相对路径结构与.bak后缀冲突检测_apply_hunk/_find_subsequenceUpdate 操作按 hunk 精确匹配上下文匹配失败时抛PatchApplyError并附带file:search:上下文行形式的recheck_targets提示辅助模型定位漂移位置若模型输出无/-前缀则视为整文件替换并支持匹配失败后按 after 内容回退重建。补丁支持Add File新建已存在则报错、Update File修改先备份再匹配替换、Delete File删除先备份三类操作且受max_files默认 10与max_total_changed_lines默认 800双重规模限制。记忆系统memory/四型记忆与多后端存储memory/目录体现了对 Agent 记忆的分层抽象按类型 × 存储 × 检索三个维度组织base.py记忆的基础抽象types/四种记忆类型——working.py工作记忆、episodic.py情景记忆、semantic.py语义记忆、perceptual.py感知记忆storage/多种存储后端——document_store.py文档存储、qdrant_store.py向量存储、neo4j_store.py图存储rag/document.py与pipeline.py构成 RAG 检索管线embedding.py嵌入模型封装manager.pyMemoryManager统一入口屏蔽底层存储差异。从架构上看记忆系统被设计为可插拔能力在 Code Agent 的当前配置中memory_tool传入None以配合lazy_fetchTrue的按需模式code_agent.py记忆的读写权完全交给模型通过工具自行决定而当lazy_fetchFalse时ContextBuilder._gather会主动调用MemoryTool.execute(search, ...)按min_importance过滤任务状态记忆。两种模式的切换只需改动一行配置体现了配置驱动能力的设计取向。工具函数层utils/可复用能力底座utils/存放跨模块复用的基础设施cli_ui.py终端渲染c颜色函数、hr分隔线、Spinner加载动画、clamp_text文本裁剪、log_tool_event工具事件日志helpers.py通用辅助函数logging.py日志配置serialization.py序列化工具。其中cli_ui.py的作用在 CLI 体验中随处可见——例如 ReAct 循环中每步的--- Step N/20 ---分段提示、 code_agent前缀、以及启动横幅中的彩色分隔线均由该模块提供。从结构到架构一条完整的数据流将以上各层串联起来一次完整的 Code Agent 交互如修复 src/util.py 中的某个 bug的数据流为CLI 层hello_code_cli.py解析参数、加载.env、预检 LLM构造CodeAgent与ApplyPatchExecutor编排层code_agent.py调用ContextBuilder.build_base构建保底上下文系统提示 历史 上次工具摘要识别多步任务关键词时附加 Todo 提示推理层ReActAgent.run进入思考-行动-观察循环按需调用注册表中的terminal/context_fetch/note/todo/plan工具超长观察被 LLM 摘要压缩重复行动被检测终止证据回流本轮工具执行摘要被封装为ContextPacket存入recent_tool_packets缓冲区最多 8 条供下一轮构建[Evidence]段落会话持久化每轮对话追加到history保留最近 50 条并写入.helloagents/sessions/session_*.json补丁闭环CLI 从响应中提取补丁风险判定后交由ApplyPatchExecutor执行备份 → 原子写入 → 冲突检测结果以action/blocker笔记沉淀到.helloagents/notes/。这一链路完整覆盖了理解仓库 → 制定方案 → 安全修改 → 记录沉淀的智能体工作闭环而整个仓库的分层目录正是为支撑这条链路而设计的——这正是阅读项目结构时最值得体会的工程思想。结语从顶层目录的职责划分到core/的统一底座、agents/的范式实现、context/的上下文流水线、tools/的能力注册、code_agent/的安全补丁闭环再到memory/的记忆分层与utils/的基础设施HelloAgents Code Agent CLI用一套清晰的分层目录结构将一个类 Claude Code / Codex 的本地代码智能体拆解为高内聚、低耦合、可独立演进与替换的模块集合。对于想要自研代码 Agent 的开发者而言这份结构本身就是一份值得参照的架构蓝图CLI 与逻辑分离、推理与工具解耦、上下文按需加载、修改必须安全可控。沿着本文给出的各模块入口CLI 主循环、ReAct 实现、补丁执行器、上下文流水线继续阅读源码即可由点及面地掌握整个系统的运行全貌。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考