HelloAgents Code Agent CLI 项目结构深度解析模块化智能体框架的架构设计与源码实现【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents本文以 YYHDBL-HelloCodeAgentCli 项目中的《项目结构分析》笔记为核心骨架结合仓库源码逐层拆解该 Python AI Agent 框架的模块化设计。读者将理解 agents / code_agent / core / context / memory / tools / utils 七大核心目录的职责边界、ReAct 智能体的运行闭环、安全补丁执行器的实现原理以及如何通过 .env 与 Code Agent 配置体系驱动整套工具运行。HelloAgents Code Agent CLI 是一个面向本地代码仓库的智能 Code Agent 命令行工具提供类似 Claude Code / Codex 的交互体验。项目的设计目标决定了它的目录组织方式按职责分层、模块化解耦、安全可控。本篇文章将依据项目内记录的《项目结构分析》笔记笔记原文结合 README.md 与各模块源码带你从目录结构出发一直深入到源码实现彻底看懂这个智能体框架的每一层。一、项目定位与核心特征《项目结构分析》笔记首先给出了项目的基本定性项目类型Python AI Agent 框架 / 工具包核心特征模块化设计——清晰的目录结构虚拟环境已配置.venv版本控制.gitignore环境变量配置.env依赖管理requirements-*.txt从仓库实际内容看这一分析与 README.md 的描述完全吻合项目定位为面向本地代码仓库的智能 Code Agent 命令行工具核心价值包括精准检索先证据后结论避免全库扫描、安全可控补丁式修改 原子写入 自动备份 人工确认、智能推理基于 ReAct 范式多步推理、任务管理内置 Todo 系统与丰富工具终端、上下文获取、笔记管理、记忆等。需要说明的是笔记中提到的.venv虚拟环境与.env环境变量文件属于开发者的本地运行配置通常被.gitignore排除仓库根目录确实存在 .gitignore因此仓库快照中看不到它们而.helloagents/状态目录笔记、备份、待办则真实存在于仓库中我们将在后文专门讲解。二、目录结构总览一份可以对照源码的模块地图笔记记录了项目顶层目录的职责划分与仓库实际结构一一对应目录职责仓库中的关键文件agents/Agent 实现四种范式react_agent.py、plan_solve_agent.py、reflection_agent.py、simple_agent.pycode_agent/代码相关 AgentCLI 主应用hello_code_cli.py、agentic/code_agent.py、executors/apply_patch_executor.py、prompts/context/上下文管理GSSC 流水线builder.pycore/核心框架基类与公共设施agent.py、llm.py、config.py、message.py、exceptions.py、database_config.pymemory/记忆管理四类记忆 RAGmanager.py、base.py、embedding.py、types/、storage/、rag/tools/工具库注册表 内置工具registry.py、base.py、chain.py、async_executor.py、builtin/utils/工具函数cli_ui.py、helpers.py、logging.py、serialization.py笔记中记录的依赖文件为requirements-mvp.txt最小可行产品依赖与requirements-optional.txt可选依赖体现的是按需拆分依赖的设计意图在当前仓库快照中对应的依赖清单文件是 requirement.txt。此外仓库还包含 __init__.py 包定义与.gitignore版本控制配置。三、分层架构从用户输入到安全落盘的六层调用链README.md 给出了系统架构图结合源码可以还原出完整的六层结构用户交互层 (CLI: code_agent/hello_code_cli.py) │ 智能体层 (agents/: ReActAgent / PlanSolveAgent / ReflectionAgent / SimpleAgent) │ 核心层 (core/: HelloAgentsLLM / Message / Config / Exceptions) │ 能力层 (context/ GSSC 流水线 · memory/ 多层记忆) │ 工具层 (tools/: Terminal · ContextFetch · Note · Todo · Plan · Memory · MCP 等) │ 执行器层 (code_agent/executors/: ApplyPatchExecutor 安全补丁应用)一次典型的交互流程是用户输入自然语言 → CLI 入口解析参数并初始化 LLM 与配置 → 交由 CodeAgent 进入 ReAct 循环思考 → 调用工具 → 观察 → 再思考→ 若 LLM 输出补丁块则由 ApplyPatchExecutor 完成安全落盘。下面逐层深入。3.1 智能体层四种 Agent 范式agents/目录实现了四种经典智能体范式继承自统一基类 AgentSimpleAgent基础对话型 Agent直接问答ReActAgent主引擎循环执行思考 → 行动 → 观察Reasoning and ActingReflectionAgent自我反思与优化PlanSolveAgent规划式任务分解先制定计划再执行。以 react_agent.py 为例其默认提示词模板要求模型每轮严格输出两行Thought: 分析当前问题思考需要什么信息或采取什么行动。 Action: tool_name[tool_input] 或 Finish[最终答案]源码在 react_agent.py 的主循环中实现了一整套工程化细节严格的输出解析_parse_output兼容Thought/思考、Action/行动等中英文变体、全角冒号与 Markdown 加粗格式react_agent.py鲁棒的 Action 解析_parse_action采用括号匹配算法而非贪婪正则可正确处理嵌套 JSON 参数react_agent.py观察摘要当工具输出超过summarize_threshold_chars默认 2000 字符时调用observation_summarizer压缩后再进入下一轮提示词防止上下文膨胀重复行动检测连续repeat_action_threshold默认 2 次执行相同工具|参数时提前终止避免模型原地打转收敛兜底达到最大步数未 Finish 时用最终收敛器提示词基于已有 Thought/Action/Observation 历史生成尽可能有用的回答react_agent.py。值得注意的还有 MCP 支持add_tool检测到带auto_expand属性的 MCP 工具时会自动将其展开为多个独立子工具注册进工具表react_agent.py这使框架天然兼容 MCP 生态。3.2 CLI 入口hello_code_cli.py 的运行机制code_agent/hello_code_cli.py 是整个工具的主入口执行流程如下参数解析从源码看入口当前仅解析--repo代码库根目录默认当前目录与--project项目名默认取仓库文件夹名两个参数hello_code_cli.py。需要说明的是README 中列出的--model、--max-steps、--enable-memory等参数在入口实现中尚未出现可以推断这些能力目前通过环境变量与Config配置驱动相关 CLI 参数属于文档先行/规划项环境初始化从仓库根目录加载.env由Config.from_env()读取配置、HelloAgentsLLM()自动检测 LLM 提供商hello_code_cli.pyLLM 预检启动时用一次max_tokens1的调用验证 API key / base_url / model 配置是否有效失败则明确提示检查.envhello_code_cli.py交互循环支持:quit退出、:plan 目标强制生成计划普通输入则交给CodeAgent.run_turn处理hello_code_cli.py。CLI 中还有一个关键机制从 LLM 回复中提取*** Begin Patch ... *** End Patch补丁块支持代码围栏内提取与格式规范化根据风险策略决定是否需要人工确认最后交给补丁执行器应用详见 3.5 节。3.3 核心层LLM 统一接口与配置管理HelloAgentsLLM统一 LLM 接口core/llm.py 基于 OpenAI 原生 SDK 封装设计理念是参数优先、环境变量兜底、流式响应默认。它支持 11 种提供商openai、deepseek、qwen、modelscope、kimi、zhipu、ollama、vllm、local、auto等llm.py。_auto_detect_provider实现三级检测逻辑llm.py优先检查特定提供商的环境变量如DEEPSEEK_API_KEY→ deepseek、DASHSCOPE_API_KEY→ qwen、KIMI_API_KEY/MOONSHOT_API_KEY→ kimi、OLLAMA_HOST→ ollama 等根据 API Key 格式推断ms-前缀 → modelscope、含点号 → zhipu、ollama/vllm字面量 → 对应本地服务根据 base_url 推断api.deepseek.com→ deepseek、dashscope.aliyuncs.com→ qwen、localhost:11434→ ollama、:8000vllm→ vllm常见本地端口:8080/:7860/:5000→ local。随后_resolve_credentials按 provider 解析出最终的 api_key 与 base_url如 deepseek 默认https://api.deepseek.comqwen 默认https://dashscope.aliyuncs.com/compatible-mode/v1未指定模型时由_get_default_model按 provider 返回默认模型如 deepseek-chat、qwen-plus、glm-4、llama3.2 等。Config统一配置core/config.py 用 pydantic 模型集中管理全部配置分六大类基础配置debug、log_level、LLM 配置temperature 默认 0.7、llm_timeout 默认 60s、Agent 配置max_react_steps 默认 20、max_history_turns 默认 50、observation_summary_threshold 默认 2000、上下文配置context_max_tokens 默认 8000、压缩与懒加载开关、工具配置terminal_timeout、terminal_max_output_size 默认 10MB、补丁执行器配置patch_max_files 默认 10、patch_max_total_lines 默认 800、白名单后缀、安全配置大规模变更阈值6 个文件 / 400 行。from_env()支持环境变量注入命名规则为CODE_AGENT_配置项大写或传统命名例如CODE_AGENT_MAX_REACT_STEPS、CODE_AGENT_TERMINAL_TIMEOUT、CODE_AGENT_PATCH_MAX_FILES、CODE_AGENT_STATE_DIR状态目录默认.helloagents。此外get_notes_dir/get_sessions_dir/get_backups_dir/get_todos_dir方法把状态目录细分为 notes、sessions、backups、todos 四个子目录与仓库中.helloagents/下的实际目录一一对应。3.4 能力层与工具层上下文构建、记忆与工具生态上下文构建GSSC 流水线context/builder.py 实现 GSSC 流水线Gather收集→Select相关性筛选→Structure结构化组织→CompressToken 压缩对应用户查询 → 收集信息 → 筛选 → 组织 → 压缩 → 生成回复的链路配合 Config 中的context_max_tokens8000、context_lazy_fetch按需获取默认开启等参数实现先证据后结论、避免全库扫描的精准检索目标。记忆系统多层记忆 RAGmemory/ 目录按类型 — 存储 — 检索三个维度组织types/四种记忆类型——working.py工作记忆、episodic.py情景记忆、semantic.py语义记忆、perceptual.py感知记忆storage/三种存储后端——document_store.py文档存储、qdrant_store.py向量数据库、neo4j_store.py图数据库rag/RAG 检索系统——document.py文档处理与pipeline.py检索流水线顶层manager.py统一管理接口、embedding.py嵌入模型、base.py基础定义。工具系统tools/ 提供base.py工具基类与参数定义、registry.py工具注册表、chain.py工具链编排、async_executor.py异步执行。builtin/下内置九类工具工具功能用途terminal_tool.py安全终端执行白名单命令文件浏览、搜索、文本处理context_fetch_tool.py按需代码检索读取特定文件/目录内容note_tool.py笔记增删改查记录重要信息、决策点todo_tool.py任务管理多步任务跟踪、进度可视化plan_tool.py规划生成复杂任务分解与执行计划memory_tool.py记忆管理长期知识存储与检索mcp_wrapper_tool.pyMCP 工具包装对接外部 MCP 服务protocol_tools.py协议相关工具通信协议支持search.py搜索工具代码库检索3.5 执行器层安全补丁系统code_agent/executors/apply_patch_executor.py 是安全可控这一核心价值的落点实现 Codex 风格的补丁应用格式如下*** Begin Patch Update File: src/example.py python # 修改后的代码*** End Patch执行器在 [apply_patch_executor.py](https://link.gitcode.com/i/b1bc10a76a89461dd7f3eb0ef0888962#L39-L49) 中明确了五项 MVP 安全特性 1. **repo_root 路径限制**所有操作限制在仓库根目录内防止路径逃逸 2. **原子写入**通过临时文件 os.replace 实现避免写一半留下损坏文件 3. **自动备份**修改前备份到 repo_root/.helloagents/backups/timestamp/仓库中可看到 20251218_200920、20251219_192206 等时间戳备份目录 4. **大小限制**单补丁最大 10 个文件、最大 800 行变更与 Config 的 patch_max_files、patch_max_total_lines 对应 5. **白名单后缀**默认仅允许 .py、.md、.toml、.json、.yml、.yaml、.txt、.html、.htm、.css、.js 等文本类文件防止误改二进制或敏感文件。 与之配套的还有 CLI 侧的人工确认策略[hello_code_cli.py](https://link.gitcode.com/i/b22f45822c0506d2f5ece3cae390be0f#L63-L81)包含 Delete File 操作、涉及文件数 ≥ 6、或变更行数 ≥ 400 时视为高风险补丁必须输入 y 确认后才应用。应用成功后CLI 会自动通过 note_tool 把补丁内容记录为一条 action 类型笔记失败则记录为 blocker 类型笔记供后续追溯——这正是 .helloagents/notes/ 目录下大量笔记的来源机制。 ## 四、.helloagents 状态目录笔记、备份与待办的落盘位置 笔记中提到的 .helloagents 项目特定配置在仓库中有真实体现.helloagents/ ├── backups/ # 补丁应用的自动备份按时间戳分目录 │ ├── 20251218_200920/testDemo/hello.html.bak │ ├── 20251219_192206/testDemo/我讨厌java.txt.bak │ └── ... ├── notes/ # 智能体笔记note_*.md带 frontmatter 元数据 │ ├── note_20251217_160215_2.md # 本文依据的《项目结构分析》笔记 │ ├── note_20251218_191343_6.md │ └── ... └── todos/ # 待办任务 └── todos.json.bak笔记文件采用 YAML frontmatter 记录 id、title、typegeneral / blocker / action 等、tags、created_at、updated_at 元数据正文为 Markdown。例如本文所依据的《项目结构分析》笔记其 type: general正文从项目类型、主要特征、目录结构、依赖文件、配置五个维度完成了对项目的第一次结构化认识。这套笔记机制本身也是项目长期记忆能力的实际体现——智能体在会话中产生的发现、决策与问题都会被持久化到 notes/ 供后续会话检索复用。 ## 五、配置与快速上手 ### 5.1 .env 环境变量配置 在仓库根目录创建 .env 文件源码通过 load_dotenv(dotenv_pathrepo_root / .env) 加载以 DeepSeek 为例 bash # LLM 配置必需 LLM_BASE_URLhttps://api.deepseek.com LLM_MODEL_IDdeepseek-chat DEEPSEEK_API_KEYsk-xxxxxxxxxxxx需要以源码为准说明两点一是模型名环境变量在 llm.py 中读取的是LLM_MODEL_ID二是只要配置了对应的提供商密钥如DEEPSEEK_API_KEY、OPENAI_API_KEY、DASHSCOPE_API_KEY、OLLAMA_HOST等HelloAgentsLLM会自动检测提供商并填充默认 base_url 与模型此时甚至可以不写LLM_*变量。常用可调环境变量汇总对应 core/config.py环境变量作用默认值LLM_BASE_URLAPI 服务地址按 provider 自动推断LLM_MODEL_ID模型名称按 provider 自动推断LLM_TIMEOUTLLM 请求超时秒60TEMPERATURE采样温度0.7CODE_AGENT_MAX_REACT_STEPSReAct 最大步数20CODE_AGENT_TERMINAL_TIMEOUT终端命令超时秒60CODE_AGENT_PATCH_MAX_FILES单补丁最大文件数10CODE_AGENT_PATCH_MAX_LINES单补丁最大行数800CODE_AGENT_STATE_DIR状态存储目录.helloagentsDEBUG调试模式false5.2 安装与运行# 1. 创建虚拟环境对应笔记中虚拟环境已配置的特征 python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate # 2. 安装依赖 pip install -r Co-creation-projects/YYHDBL-HelloCodeAgentCli/requirement.txt # 3. 配置 .env见 5.1 # 4. 启动 CLI需在项目目录下执行 cd Co-creation-projects/YYHDBL-HelloCodeAgentCli python -m code_agent.hello_code_cli --repo . # 或指定其他代码库 python -m code_agent.hello_code_cli --repo /path/to/your/project启动后进入交互式命令行输入自然语言即可驱动智能体工作例如帮我分析 src/main.py 的入口函数智能体会按Thought → Action: context_fetch[path...] → Observation → Finish[...]的 ReAct 闭环完成分析需要修改代码时模型输出补丁块经风险校验与人工确认后由执行器原子写入并自动备份。六、小结从结构分析到架构理解回顾《项目结构分析》笔记给出的这张模块地图再对照源码逐层印证可以得出一个清晰的架构结论这是一个CLI 入口 分层核心 可插拔工具 安全执行器的经典智能体工程化布局。core/提供与 LLM 供应商无关的统一抽象agents/承载可替换的推理范式context/与memory/解决长程任务的信息组织与记忆问题tools/以注册表机制实现能力的按需注入含 MCP 扩展而code_agent/则把这一切收敛为对开发者友好的命令行体验并以补丁 备份 确认的安全机制守住代码仓库的最后一道防线。对于希望在此基础上二次开发的读者建议按以下路径阅读源码从 hello_code_cli.py 入口看整体调用链到 react_agent.py 理解推理闭环再到 llm.py 与 config.py 掌握扩展接入点最后通过 apply_patch_executor.py 学习安全文件操作的最佳实践——这份目录结构背后正是一套可复用、可扩展、可安全落地的 Agent 框架设计范本。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考