# agent_dev **Repository Path**: wangdong_cmcc/agent_dev ## Basic Information - **Project Name**: agent_dev - **Description**: 智能体开发 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-05-16 - **Last Updated**: 2026-06-03 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # EVA — 可进化的 AI 代理系统 EVA（Evolvable AI Agent）是一个在终端环境中运行的 AI 助手，将大模型的推理规划能力与本地环境执行能力相结合，具备记忆管理、会话持久化和工具调用能力。 ## 项目结构 ```text . ├── eva # 系统命令（e.g. sudo ln -s .../eva /usr/local/bin/eva） ├── eva1/ # 单体脚本（原生 requests） │ ├── eva_extreme.py # ★ 架构重构版！借鉴Claude Code，AppState/ToolRegistry/CommandRegistry │ ├── eva_ultra.py # EVA Ultra（增量知识库、Qdrant默认、可配置路径） │ ├── eva_pro.py # 整合版（RAG + 规划 + 长期记忆） │ ├── eva.py # 远程版（DeepSeek API） │ ├── eva_planner.py # 远程增强版（显式任务规划） │ ├── shuke.py # 本地版（Ollama） │ ├── eval_kb_quality.py # 知识库 chunk 质量分析 │ ├── eval_qa_quality.py # 端到端 RAG QA 评估（MRR / KW 召回） │ ├── issues.md # 问题排查与解决记录 │ ├── docs/ │ │ ├── eva_extreme_design.md # EVA Extreme 设计文档 │ │ ├── eva_pro_design.md # EVA Pro 设计文档 │ │ ├── eva_max_design.md # EVA Max 设计文档 │ │ ├── eva_ultra_design.md # EVA Ultra 设计文档 │ │ ├── kb_quality_report.md # 知识库质量评估与改进报告 │ │ └── questions.md # Python 专家问答 │ ├── eva_design.md # eva.py 设计文档 │ ├── eva_planner_design.md # eva_planner.py 设计文档 │ ├── shuke_design.md # shuke.py 设计文档 │ ├── reading_guide.md # eva.py 源码阅读指南 │ ├── test[1-5].py # LangChain/LangGraph 示例 │ └── README.md │ ├── eva2/ # 模块化重构（LangGraph/LangChain） │ ├── __init__.py # 包版本号 2.0.0 │ ├── __main__.py # python -m eva2 入口 │ ├── cli.py # 命令行入口（Rich 图形终端） │ ├── config.py # Pydantic 配置管理 │ ├── llm.py # LLM 工厂（OpenAI/Anthropic/Ollama） │ ├── agent.py # LangGraph Agent 组装 │ ├── memory.py # 自动记忆压缩 │ ├── prompts.py # System prompt 模板 │ ├── session.py # 会话持久化 │ ├── tools/ │ │ ├── __init__.py # 工具注册工厂 │ │ ├── run_cli.py # CLI 执行工具（含安全审查） │ │ └── store.py # 持久化记忆存储 │ ├── eva2_learn.py # 交互式学习向导 │ ├── run.sh # 一键启动脚本 │ └── docs/ │ ├── eva2_design.md # 设计思路文档 │ └── bugs.md # Bug 记录 │ └── eva3/ # 模块化重构 v3（推荐） ├── __init__.py # 包版本号 3.0.0 ├── __main__.py # python -m eva3 入口 ├── cli.py # 交互循环 + 运行时命令 ├── config.py # 配置中心（Pydantic EVA3_） ├── agent.py # Agent 组装 ├── planner.py # 三阶段规划 + DAG 依赖 ├── memory_manager.py # 双层记忆管理（工作+长期） ├── knowledge.py # RAG 知识库（混合检索·中文翻译·PDF 章节提取） ├── embeddings.py # 统一嵌入（Ollama → 哈希降级） ├── llm.py # LLM 工厂（含 DeepSeek reasoning 补丁） ├── prompts.py # System prompt 模板 ├── session.py # 会话持久化 ├── vector_store/ # 4 种向量存储后端（维度自动检测重建） ├── tools/ # Agent 工具 ├── run.sh # 一键启动脚本 ├── docker-compose.yml # Milvus 容器编排 └── docs/ ├── eva3_design.md # 架构设计文档 └── usage_guide.md # 使用指南 └── eva_apex/ # eva_extreme.py 优化重构版（★ 最新） ├── __init__.py # 包版本号 4.0.0 ├── __main__.py # python -m eva_apex 入口 ├── cli.py # argparse + main() ├── app.py # EVAApex 应用（惰性初始化 + _initialized 标记） ├── agent.py # Agent Loop（结构化 MemoryHints + 复用 ctx_mgr） ├── config.py # Config + FeatureFlags（-u 模式 fail-fast） ├── state.py # AppState + Phase（集中状态机 transition()） ├── planner.py # StepState + PlanStep + TaskPlan（前移消除脆弱性） ├── env.py # 惰性环境信息收集（不再模块加载时执行） ├── exceptions.py # 异常类体系 ├── llm.py # LLM 调用 + 统一 HTTP 工具层（消除重复 fallback） ├── embeddings.py # Ollama 嵌入 + 中文翻译 + 关键词评分 ├── prompts.py # System prompt + COMPACT_MARKER 常量统一 ├── memory.py # MemoryManager + MemoryType ├── knowledge.py # KnowledgeBase（SQLite bigram 索引 + min_score 过滤） ├── context_compactor.py # ContextManager（复用 ctx_mgr + 引用常量） ├── permissions.py # PermissionEngine（EOFError 处理） ├── session.py # 会话持久化 ├── eva_apex_design.md # 设计文档 ├── tools/ # 工具子包（8 文件） ├── commands/ # 命令子包（6 文件） └── vector_store/ # 向量存储子包（5 文件，修复 Qdrant delete bug） ``` ## 安装 ```bash # 1. 安装依赖 pip install langgraph langchain-core langchain-openai rich pydantic pydantic-settings tiktoken requests # 2. [可选]本地拉取嵌入模型,构建 RAG知识库需要, 以nomic-embed-text:latest 为例 ollama pull nomic-embed-text:latest ``` ## 快速开始 ### EVA1 (单体脚本) EVA1 路径下的脚本按进化顺序：`eva.py` → `eva_planner.py` → `eva_pro.py` → `eva_ultra.py` → **`eva_extreme.py`（最新）**。新用户直接使用最后一个。 ```bash cd eva1 # ★ 最新版：EVA Extreme — 架构重构版，9 个类体系，新增文件工具，借鉴 Claude Code EVA_API_KEY="sk-xxx" python eva_extreme.py # 功能开关 EVA_FILE_TOOLS=0 python eva_extreme.py # 关闭文件工具 EVA_CONCURRENT=0 python eva_extreme.py # 回到全串行 # 前代版本（供参考） # EVA_API_KEY="sk-xxx" python eva_ultra.py --store qdrant # EVA_API_KEY="sk-xxx" python eva_pro.py # EVA_API_KEY="sk-xxx" python eva.py # python shuke.py ``` ### EVA2（模块化重构） ```bash # 一般使用 cd agent_dev/eva2/ EVA2_LLM_API_KEY=sk-your-key ./run.sh # 建议使用deepseek api key, 可通过https://platform.deepseek.com/api_keys注册申请，至少充值1元才可使用 # 首次使用建议构建本地知识库 /knowledge build ``` ### 交互式学习eva2的设计 ```bash cd eva2 python3 eva2_learn.py # 交互模式，从第 1 关开始 python3 eva2_learn.py list # 查看所有关卡 python3 eva2_learn.py 5 # 跳到第 5 关 ``` ### EVA3（模块化重构 v3，推荐） 集成了 eva_pro.py 的核心能力：**混合检索知识库**（中文自动翻译 + Bigram 倒排索引 + 关键词重排序）、**PDF Outline 章节提取**（含噪声过滤）、**内容级去重**、**模型上下文自动检测**。 知识库支持 **13 种文件格式**：`.md .txt .py .json .yaml .yml .sh .log .html .htm .pdf .epub .docx .pptx .xlsx .xls .csv` ```bash cd agent_dev/eva3/ # 启动 Milvus（默认向量存储） docker compose up -d # 配置 API Key 并启动 export EVA3_LLM_PROVIDER=openai export EVA3_LLM_MODEL=deepseek-v4-flash export EVA3_LLM_BASE_URL=https://api.deepseek.com/v1 export EVA3_LLM_API_KEY=sk-xxx python -m eva3 ``` ### EVA Apex（eva_extreme.py 优化重构版，★ 最新） 基于 `eva_extreme.py` 的模块化重构，修复 3 个 bug、3 个架构问题、3 个性能问题和 7 个代码质量问题。 ```bash cd agent_dev/ # 配置 API Key 并启动（详见 eva_apex/eva_apex_design.md 环境变量章节） export EVA_API_KEY=sk-xxx python -m eva_apex # 单次执行模式 python -m eva_apex -u "查找当前目录下的 Python 文件" # 深度推理模式 python -m eva_apex --mode deep # 指定向量数据库 python -m eva_apex --store milvus ``` ### 知识库使用 ```text /kb build [dir] 全量重建（删旧 + 重新扫描全部文件） /kb update 增量更新（仅处理新增/修改/删除的文件，原有数据不受影响） /kb status 查看知识库状态（文档数、文本块数、目录等） /kb clear 清空知识库 ``` **推荐的日常流程：** 1. 把文档放入 `knowledgebase/` 目录 2. 首次构建：`/kb build` 3. 后续新增或修改文件后：`/kb update` ## 版本对比 | 特性 | eva1 (eva.py) | eva1 (eva_planner.py) | eva1 (eva_pro.py) | eva1 (eva_ultra.py) | eva1 (eva_extreme.py) | eva2 | eva3 | **eva_apex** | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | 架构 | 单体~740行 | 单体~860行 | 单体~2200行 | 单体~3200行 | 单体~3100行（9类体系） | 模块化（12 文件） | 模块化（26 文件） | **模块化（37 文件）** | | 框架 | 原生 requests | 原生 requests | 原生 requests | 原生 requests | 原生 requests | LangGraph+LangChain | LangGraph+LangChain | **原生 requests** | | 任务规划 | 隐式 | **显式三阶段** | **显式三阶段** | **显式三阶段** | **显式三阶段** | 隐式 | **显式三阶段+DAG** | **显式三阶段** | | 步骤追踪 | 无 | **DAG 解析** | **DAG 解析** | **DAG 解析** | **DAG 解析** | 无 | **DAG 解析** | **DAG 解析** | | RAG 知识库 | 无 | 无 | **/kb build** | **/kb build/update** | **/kb build/update** | **/knowledge build** | **混合检索+增量+中文** | **SQLite bigram + 增量+中文** | | 知识库格式 | — | — | .md/.txt/.pdf/.epub | **17 种** | **17 种** | .md/.txt | **17 种** | **17 种** | | 向量存储 | 无 | 无 | Q/M/F/C | Q/M/F/C | Q/M/F/C | Chroma（本地） | **Q/M/F/C（自动重建）** | **Q/M/F/C（自动重建）** | | 中文检索 | 无 | 无 | **中译英** | **中译英** | **中译英** | 无 | **中译英+Bigram+重排序** | **中译英+SQLite Bigram+重排序** | | 会话管理 | 支持 | 支持 | 支持 | 支持 | 支持 | — | — | **支持** | | 记忆压缩 | 压缩归档 | 预留 | 压缩归档 | 压缩归档 | **ContextManager 多策略** | Token 感知 | **MemoryManager 双层** | **ContextManager 多策略** | | **AppState** | 全局变量 | 全局变量 | 全局变量 | 10+全局变量 | **1个AppState** | — | — | **1个AppState** | | **Phase 状态机** | 无 | 无 | 无 | 无 | 散落各处 | — | 集中 | **集中 transition()** | | **工具并发** | 全串行 | 全串行 | 全串行 | 全串行 | **只读并发+写串行** | 全异步 | **全异步** | **只读并发+写串行** | | **Schema生成** | 手写 dict | 手写 dict | 手写 dict | 手写 dict | **dataclass自动生成** | Pydantic | **Pydantic** | **dataclass自动生成** | | **命令处理** | if-elif | if-elif | if-elif | 23个if/elif | **CommandRegistry** | — | — | **CommandRegistry** | | **文件工具** | 仅 run_cli | 仅 run_cli | 仅 run_cli | 仅 run_cli | **read/write/edit** | — | — | **read/write/edit** | | **FeatureFlags** | 无 | 无 | 无 | 无 | **支持** | — | — | **支持** | | **Plugin** | 无 | 无 | 无 | 无 | **基类预留** | — | — | **基类预留** | | **Bug 修复** | — | — | — | — | 3 个未修 | — | — | ✅ **全部修复** | | 推荐场景 | 学习参考 | 学习参考 | 学习参考 | 学习参考 | 研究Claude Code设计 | 日常使用 | **日常使用** | **★ 最新** | ## 配置 ### eva_apex 环境变量（前缀 `EVA_*`） | 变量 | 默认值 | 说明 | | --- | --- | --- | | `EVA_API_KEY` | — | **API 密钥（必填）** | | `EVA_BASE_URL` | `https://api.deepseek.com/v1` | API 地址 | | `EVA_MODEL_NAME` | `deepseek-v4-flash` | 模型名称 | | `EVA_DEBUG` | `0` | 设为 `1` 启用调试输出 | | `EVA_KNOWLEDGE_DIR` | `.eva/knowledge` | 知识库文档目录 | | `EVA_FILE_TOOLS` | `1` | 设为 `0` 禁用文件工具 | | `EVA_CONCURRENT` | `1` | 设为 `0` 禁用工具并发执行 | | `EVA_TRANSLATE` | `1` | 设为 `0` 禁用中文查询自动翻译 | | `EVA_TRAJECTORY` | `1` | 设为 `0` 禁用轨迹记忆 | | `EVA_PLANNING` | `1` | 设为 `0` 禁用任务规划 | | `EVA_REFLECTION` | `1` | 设为 `0` 禁用反思记忆 | | `OLLAMA_HOST` | `http://localhost:11434` | Ollama 嵌入服务地址 | ### eva2/eva3 环境变量（前缀 `EVA2_*` / `EVA3_*`） | 变量 | 默认值 | 说明 | | --- | --- | --- | | `EVA2_LLM_PROVIDER` | `openai` | API 协议 | | `EVA2_LLM_MODEL` | `deepseek-v4-flash` | 模型名称 | | `EVA2_LLM_BASE_URL` | `https://api.deepseek.com/v1` | API 地址 | | `EVA2_LLM_API_KEY` | — | API 密钥 | ## 开源与致谢 本项目基于 [usepr/eva](https://github.com/usepr/eva) 进行二次开发与重构。 - **eva1/** — 单体脚本风格，直接使用原生 requests 调用 LLM API。`eva_pro.py` 为其中功能最完整的旗舰版，融合了 RAG、任务规划和长期记忆。源自 [usepr/eva](https://github.com/usepr/eva)，保留原始设计思路与核心逻辑。 - **eva2/** — 基于 LangGraph + LangChain 技术栈的模块化重构，架构设计与接口协议与 eva1 有较大差异，使用 Rich 图形化终端、Pydantic 配置管理、全异步执行。 - **eva3/** — 在 eva2 基础上的进一步迭代，增加规划器、权限引擎、向量存储抽象层、命令自动发现等能力。 - **eva_apex/** — 基于 `eva1/eva_extreme.py` 的模块化优化重构，修复 3 个 bug、解决 3 个架构问题、优化 3 个性能点和提升 7 个代码质量点。保持原生 requests 调用，无 LangChain/LangGraph 依赖。详见 [eva_apex_design.md](eva_apex/eva_apex_design.md)。 遵循上游项目的开源许可协议。感谢原作者 [usepr](https://github.com/usepr) 的开源贡献。 ## 安全机制 - 非只读命令（rm、dd、wget 等）执行前需用户确认 - LLM 预审查命令安全分类 - `-a` 参数可跳过确认（谨慎使用）