HelloAgents Code Agent CLI 是一个基于 HelloAgents 框架开发的智能代码助手，提供类似 Claude Code/Codex 的交互体验，专注于本地代码仓库的安全智能操作。
- 🎯 精准检索：按需探索代码库，先证据后结论，避免全库扫描
- 🛡️ 安全可控：补丁式修改 + 原子写入 + 自动备份，危险修改需人工确认
- 🧠 智能推理：基于 ReAct 范式，支持多步推理与行动
- 📊 任务管理：内置 Todo 系统，可视化追踪多步骤任务进度
- 🔧 工具丰富：集成终端、上下文获取、Note管理
- ✅ 代码库探索与分析
- ✅ 智能代码修改与重构
- ✅ 局部功能修复与优化
- ✅ 项目结构理解
- ✅ 代码审查辅助
- ✅ 技术演示与教学
- ReAct Agent：结合推理（Reasoning）与行动（Acting），支持多步骤复杂任务
- 多步跟踪：Todo Board 实时展示任务进度（pending → in_progress → completed）
*** Begin Patch
Update File: src/example.py
```python
# 修改后的代码
*** End Patch
- ✅ 标准化补丁格式
- ✅ 原子化文件操作
- ✅ 自动备份（.backup 后缀）
- ✅ 白名单文件类型控制
- ✅ 人工确认机制
### 3. 多源上下文构建
**GSSC 流水线**（Gather-Select-Structure-Compress）：
用户查询 → 收集信息 → 相关性筛选 → 结构化组织 → Token 压缩 → 生成回复
### 4. 工具生态
| 工具类型 | 功能描述 | 主要用途 |
|---------|---------|---------|
| **Terminal Tool** | 安全终端执行（白名单命令） | 文件浏览、搜索、文本处理 |
| **Context Fetch Tool** | 按需代码检索 | 读取特定文件/目录内容 |
| **Note Tool** | 笔记增删改查 | 记录重要信息、决策点 |
| **Todo Tool** | 任务管理 | 多步任务跟踪、进度可视化 |
| **Plan Tool** | 规划生成 | 复杂任务分解与执行计划 |
| **Memory Tool** | 记忆管理 | 长期知识存储与检索 |
## 🏗️ 系统架构
### 整体架构图
┌─────────────────────────────────────────────────────────────┐
│ 用户交互层 (CLI) │
│ hello_code_cli.py │
└────────────────────────┬────────────────────────────────────┘
│
┌────────────────────────▼────────────────────────────────────┐
│ 智能体层 (Agents) │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ ReActAgent │ │ PlanAgent │ │
│ └─────────────┘ └─────────────┘ │
└────────────────────────┬────────────────────────────────────┘
│
┌────────────────────────▼────────────────────────────────────┐
│ 核心层 (Core) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ LLM │ │ Message │ │ Config │ │ Exception│ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└────────────────────────┬────────────────────────────────────┘
│
┌────────────────────────▼────────────────────────────────────┐
│ 能力层 (Capabilities) │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Context Builder │ │ Memory Manager │ │
│ │ (GSSC流水线) │ │ (多层记忆) │ │
│ └─────────────────┘ └─────────────────┘ │
└────────────────────────┬────────────────────────────────────┘
│
┌────────────────────────▼────────────────────────────────────┐
│ 工具层 (Tools) │
│ Terminal │ ContextFetch │ Note │ Todo │ Plan │ Memory │... │
└────────────────────────┬────────────────────────────────────┘
│
┌────────────────────────▼────────────────────────────────────┐
│ 执行器层 (Executors) │
│ ApplyPatchExecutor - 安全补丁应用与文件操作 │
└─────────────────────────────────────────────────────────────┘
### 核心模块说明
#### 1. Agents 层
- **ReActAgent**：主引擎，循环执行"思考→行动→观察"
- **PlanSolveAgent**：规划式任务分解
- **ReflectionAgent**：自我反思与优化
- **SimpleAgent**：基础对话型 Agent
#### 2. Core 层
- **HelloAgentsLLM**：统一 LLM 接口，支持 OpenAI/DeepSeek/Qwen 等
- **Message**：消息抽象与序列化
- **Config**：配置管理
- **Exceptions**：异常体系
#### 3. Context 层
- **ContextBuilder**：GSSC 流水线实现
- **ContextConfig**：上下文构建配置
- **ContextPacket**：信息包抽象
#### 4. Memory 层
- **MemoryManager**：统一记忆管理接口
- **Types**：WorkingMemory, EpisodicMemory, SemanticMemory, PerceptualMemory
#### 5. Tools 层
- **ToolRegistry**：工具注册与管理
- **Builtin Tools**：内置工具集
- **Base**：工具基类与参数定义
#### 6. Executors 层
- **ApplyPatchExecutor**：补丁解析与安全应用
---
## 🚀 快速开始
### 环境要求
- **Python**：3.10 或更高版本
- **操作系统**：macOS / Linux / Windows
### 安装步骤
#### 1. 克隆项目
```bash
git clone <repository-url>
cd YYHDBL-HelloCodeAgentCli
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activatepip install -r requirements.txt创建 .env 文件：
# LLM 配置（必需）
LLM_BASE_URL=https://api.deepseek.com
LLM_MODEL=deepseek-chat
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxx# 在当前目录启动
python -m code_agent.hello_code_cli --repo .# 指定其他代码库
python -m code_agent.hello_code_cli --repo /path/to/your/project启动后进入交互式命令行：
🚀 HelloAgents Code Agent CLI
📂 Repo: /path/to/project
💡 输入 'help' 查看帮助，'exit' 退出
👤 > 帮我分析 src/main.py 的入口函数
🤖 Thought: 需要先获取文件内容
Action: context_fetch[path=src/main.py]
Observation: [文件内容]
Thought: 已获取内容，开始分析
Action: Finish[分析结果...]
视频演示：https://www.bilibili.com/video/BV1UzBpBBE75/?vd_source=b0893117eda5f3e931a05d426f9789ed
图片演示：
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 显示帮助信息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 实现
│ │ └── code_agent.py
│ ├── executors/ # 执行器
│ │ └── apply_patch_executor.py
│ └── prompts/ # 提示词模板
│ ├── system.md
│ ├── react.md
│ ├── plan.md
│ └── tools.md
│
├── core/ # 核心模块
│ ├── agent.py # Agent 基类
│ ├── llm.py # LLM 接口
│ ├── message.py # 消息抽象
│ ├── config.py # 配置管理
│ └── exceptions.py # 异常定义
│
├── context/ # 上下文构建
│ └── builder.py # GSSC 流水线
│
├── memory/ # 记忆系统
│ ├── manager.py # 记忆管理器
│ ├── base.py # 基础定义
│ ├── embedding.py # 嵌入模型
│ ├── 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
│
├── 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
│ └── ...
│
├── utils/ # 工具函数
│ ├── cli_ui.py # CLI 界面
│ ├── helpers.py # 辅助函数
│ ├── logging.py # 日志配置
│ └── serialization.py # 序列化工具
---
- 会话恢复：支持断点续传，自动恢复摘要
- 细分终端命令工具：将Terminal Tool拆分为原子性的命令工具
- 改写Note Tool：
- 改写记忆系统：
本项目采用 MIT License 开源协议。
- YYHDBL - 项目维护者
- Datawhale 社区：提供学习资源与支持
- Hello-Agents 项目：提供框架基础
- OpenAI & DeepSeek：LLM 技术支持
如果这个项目对你有帮助，请给一个 ⭐ Star！
Made with ❤️ by HelloAgents Community