# deepagent **Repository Path**: YunAbove/deepagent ## Basic Information - **Project Name**: deepagent - **Description**: DeepAgent v5.0.0 - AI Coding Assistant with Harness Framework - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-07-12 - **Last Updated**: 2026-08-24 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 🔥 DeepAgent v5.2.0 **AI Agent 框架 (v5.2.0，积极开发中)，包含 142 个注册工具（core 层 29 个）、MCP 支持和自学习能力。生产级功能仍在完善中 — 查看 [ROADMAP](ROADMAP.md) 了解当前状态。** [![Python 3.11+](https://img.shields.io/badge/Python-3.11+-blue.svg)](https://www.python.org/downloads/) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) [![Tests](https://img.shields.io/badge/Tests-621%20通过-passing-brightgreen.svg)]() --- ## ✨ 特性 ### 🧠 核心智能 | 模块 | 功能 | 描述 | |------|------|------| | **Brain** | 推理与规划 | 任务分解、思维链、自我反思 | | **Memory** | 回忆与存储 | 工作记忆、上下文压缩、RAG | | **Goal** | 边界 | 终止标准、范围控制、失败处理 | | **Eye+Hand** | 验证 | 自我验证、指标、失败归因 | | **Trust** | 协作 | 执行追踪、干预、透明度 | | **Energy** | 成本控制 | 模型路由、时间预算、缓存 | ### 🛠️ 142 个注册工具（core 层 29 个） | 类别 | 工具数 | 描述 | |------|--------|------| | 文件操作 | 15+ | 读取、写入、编辑、搜索 | | 代码智能 | 16 | AST 分析、符号搜索 | | Git | 5 | 状态、差异、日志、提交 | | 项目管理 | 15 | 依赖、脚手架 | | API 测试 | 4 | HTTP 请求、端点 | | 数据库 | 10 | SQLite、PostgreSQL | | 安全 | 5 | 漏洞扫描 | | 性能 | 14 | 性能分析、优化 | | 监控 | 11 | 系统资源 | | 更多... | 50+ | 各类工具 | ### 🔌 MCP 支持 通过模型上下文协议连接外部工具服务器： ```python await agent.add_mcp_server( name="firecrawl", command="npx", args=["-y", "firecrawl-mcp"], env={"FIRECRAWL_API_KEY": "fc-xxx"} ) ``` ### 🎯 技能系统 8 个内置技能 + 自定义技能支持： | 技能 | 触发词 | 描述 | |------|--------|------| | explain-code | "解释这段代码" | 详细代码解释 | | fix-bug | "修复这个 bug" | Bug 修复辅助 | | add-feature | "添加功能" | 功能实现 | | write-docs | "编写文档" | 文档生成 | | optimize-code | "优化代码" | 性能优化 | | refactor-code | "重构代码" | 代码重构 | | security-audit | "安全审计" | 安全分析 | | test-generation | "生成测试" | 测试创建 | ### 🚀 生产特性（实现状态） - **流式输出** [已实现]：run_stream + CLI 流式 + WebSocket 流式均已接线 - **用户确认** [已实现]：CLI 确认回调与 Web 端确认均已接入 - **并行执行** [已实现]：独立工具并行执行 - **自动任务分解** [已实现]：TaskPlanner 已接入主循环 - **记忆检索** [已实现]：三级记忆 + run_stream 自动 recall - **结果验证** [部分]：单步验证与失败归因已接入，闭环验证待完善 - **安全沙箱** [已实现]：Docker/进程隔离（默认关闭，按需初始化） - **会话持久化** [已实现]：保存/恢复已实现 - **成本控制** [部分]：时间预算已接入主循环，模型路由待接入 - **自学习** [部分]：反馈/模式框架就绪，实际模式提取待完善 - **多智能体** [部分]：Orchestrator 基础框架，角色协作待完善 - **Webhook 集成** [已实现]：飞书/Slack/钉钉通知 --- ## 🚀 快速开始 ### 安装 ```bash # 克隆仓库 git clone https://gitee.com/hankaizhou/deepagent.git cd deepagent # 安装依赖 pip install -e ".[dev]" # 配置 API export DEEPAGENT_PROVIDER="deepseek" export DEEPAGENT_API_KEY="your-api-key" ``` ### Docker 部署 ```bash # 快速启动 (Web UI) docker-compose up -d # 使用自定义 API 密钥 DEEPAGENT_API_KEY=xxx docker-compose up -d # 开发模式 (热重载) docker-compose -f docker-compose.dev.yml up # 挂载项目目录 PROJECT_DIR=/path/to/your/project docker-compose up -d ``` ### 运行 ```bash # CLI 模式 python -m deepagent # Web UI 模式 python -m deepagent.web --port 8000 ``` --- ## 📖 使用 ### CLI 命令 | 命令 | 描述 | |------|------| | `/help` | 显示帮助 | | `/clear` | 清除历史 | | `/compact` | 压缩对话 | | `/summarize` | 显示摘要 | | `/history [N]` | 查看历史 | | `/tokens` | Token 统计 | | `/stats` | 会话统计 | | `/tools` | 可用工具 | | `/session save/load/list` | 会话管理 | | `/plugin install/list` | 插件管理 | | `/memory ` | 搜索记忆 | | `/export` | 导出对话 | ### Python API ```python from deepagent.core.agent import Agent from deepagent.core.config import AgentConfig # 创建 agent config = AgentConfig() agent = Agent(config) # 带流式输出运行 async for event in agent.run_stream("Fix this bug"): if event.type == "tool_call": print(f"Calling {event.name}...") elif event.type == "response": print(event.output) # 添加 MCP 服务器 await agent.add_mcp_server("firecrawl", "npx", ["-y", "firecrawl-mcp"]) # 添加 webhook agent.add_webhook("feishu", "https://open.feishu.cn/...") # 保存会话 agent.save_session("my_session") # 获取性能报告 report = agent.get_performance_report() ``` --- ## 🏗️ 架构 ``` ┌─────────────────────────────────────────────────────────────────┐ │ 用户界面 │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ CLI │ │ Web UI │ │ VS Code │ │ API │ │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ └──────────────┴──────────────┴──────────────┘ │ └────────────────────────────────┬────────────────────────────────┘ │ ┌────────────────────────────────┴────────────────────────────────┐ │ Agent 核心 │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ ReAct 循环 │ │ │ │ 思考 → 行动 → 观察 → 思考 → ... → 输出 │ │ │ └──────────────────────────────────────────────────────────┘ │ └────────────────────────────────┬────────────────────────────────┘ │ ┌────────────────────────────────┴────────────────────────────────┐ │ 核心智能 │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Brain │ │ Memory │ │ Goal │ │ Eye+Hand │ │ │ │ 推理 │ │ 回忆 │ │ 边界 │ │ 验证 │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ └────────────────────────────────┬────────────────────────────────┘ │ ┌────────────────────────────────┴────────────────────────────────┐ │ 基础设施 │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Tools │ │ Memory │ │ Learning │ │ MCP │ │ │ │ 150+ │ │ 3-tier │ │ 自学习 │ │ 外部 │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## 📊 统计 | 指标 | 值 | |------|-----| | 测试 | 621 通过（`pytest -m "not integration"` 实测） | | 工具 | 150+ | | 技能 | 8 个内置 | | LLM 提供商 | 4 (DeepSeek, OpenAI, Anthropic, Ollama) | | Python 文件 | 150+ | | 代码行数 | 38,000+ | --- ## ⚡ 性能 | 指标 | 值 | |------|-----| | 首次响应 | < 2秒 | | 工具执行 | < 100毫秒 | | 记忆检索 | < 50毫秒 | | 上下文构建 | < 200毫秒 | | 流式延迟 | < 100毫秒 | ### 基准测试（DeepBench 实测，2026-08-23） 自建能力基准（bug 修复 + 功能实现，三档难度；判定=任务工作区测试全绿）。 模型 `deepseek-chat`，每题独立子进程 + 独立判定器，非 LLM 自评： | 轮次 | auto_verify 关 | auto_verify 开（写后验证闭环） | |------|---------------|------------------------------| | **DeepBench-12**（首轮对照） | 10/12 (83.3%) · 309.5s · 1.88M tok | **12/12 (100%) · 263.2s (-15%) · 1.44M tok (-23%)** | | **DeepBench-16**（扩容后水位） | 16/16 (100%) · 307.6s · 2.40M tok | 16/16 (100%) · 318.3s · 2.37M tok | > 解读：12 题对照中闭环挽回全部失败且更省更快；16 题扩容后基线即达 > 天花板（题目对 deepseek-chat 偏易），两配置差异被掩盖。 > n=16、单次采样存在模型非确定性噪声。复现： > `python evals/run_bench.py --mode agent --auto-verify off|on` > 明细见 `evals/results/`。 --- ## 🛡️ 安全 - **沙箱执行** [已实现]：Docker/进程隔离（默认关闭，按需初始化） - **用户确认** [已实现]：CLI 与 Web 端均已接入 - **路径遍历保护**：安全文件路径解析 - **原子写入**：文件操作崩溃安全 - **命令阻止**：默认阻止危险命令 --- ## 🔧 配置 ```yaml # .deepagent/config.yaml llm: provider: "deepseek" model: "deepseek-chat" api_key: "your-key" max_tokens: 8192 temperature: 0.7 memory: short_term_max_tokens: 128000 context: max_tokens: 128000 summarize_threshold: 0.8 max_steps: 20 ``` --- ## 📁 项目结构 ``` deepagent/ # 主代码包 ├── core/ # 核心 Agent（ReAct 循环） ├── core_intelligence/ # 六大核心智能 ├── harness/ # 控制系统 ├── tools/ # 142 个工具（core 层 29 个） ├── providers/ # 多 LLM 支持 ├── plugins/ # 插件系统 + 市场 ├── skills/ # 技能系统 + 市场 ├── orchestration/ # 多智能体协作 ├── workflows/ # 工作流自动化 ├── collaboration/ # 协作：会话共享/评论/权限 ├── review/ # AI 代码审查 ├── workspace/ # 工作区感知 ├── docs_generator/ # 文档生成 ├── mcp/ # MCP 支持 ├── integration/ # Webhook 集成 ├── memory/ # 三层记忆 ├── context/ # 上下文管理 ├── learning/ # 自学习 ├── sandbox/ # 安全沙箱 ├── optimization/ # 性能优化 ├── llm/ # LLM 客户端与工厂 ├── web/ # Web UI ├── cli/ # CLI 接口 └── utils/ # 通用工具 其他目录: ├── tests/ # 测试套件 ├── examples/ # 示例 ├── docs/ # 文档 └── vscode-extension/ # VS Code 扩展 ``` --- ## 🧪 测试 ```bash # 运行所有测试 pytest -m "not integration" # 运行特定测试 pytest tests/test_basic.py # 带覆盖率 pytest --cov=deepagent ``` **621 个测试通过**（`pytest -m "not integration"` 实测；个别 Docker 探测用例需 Docker 环境） --- ## 🪟 Windows 已知问题 - **embedding 模型加载**：torch 等原生库在部分 Windows + conda 组合下， 后台加载 `SentenceTransformer` 可能触发进程级崩溃（access violation）。 设置环境变量 `DEEPAGENT_NO_EMBEDDER=1` 可彻底关闭（RAG 语义检索随之降级， 其余功能不受影响）。测试套件默认已关闭（见 `tests/conftest.py`）。 - **控制台编码**：CLI/TUI 输出强制 UTF-8；若终端仍出现乱码， 执行 `chcp 65001` 或使用 Windows Terminal。 --- ## 🖥️ 桌面版（MVP） 打开即用的本机 Web 体验（形态对标 `codex app`）： ```bash # 源码直接运行（起本机服务并打开浏览器） python desktop/deepagent_desktop.py ``` - 仅绑定 `127.0.0.1`，端口自动避让；默认关闭嵌入模型加载（`NO_EMBEDDER=1`） - 便携包构建（嵌入式 Python 分发，无需用户安装 Python）： ```powershell powershell -ExecutionPolicy Bypass -File scripts/build_desktop.ps1 # 产物 dist/desktop/ —— 双击 DeepAgent.bat 即用 ``` ✅ 首跑已验证：产物约 **105 MB / 8200 文件**，脱离系统 Python 独立运行 （health/首页均 200）。不含 chromadb（语义记忆需 `-WithMemory` 或 pip 装 `[memory]` extra） - **Tauri 2 原生窗口壳已实现**（`desktop/src-tauri/`）： 构建脚本自动把 release 壳复制为 `dist/desktop/DeepAgent.exe`—— **双击 DeepAgent.exe = 原生窗口；双击 DeepAgent.bat = 浏览器回退**。 壳负责：拉起/终止 Python 后端进程树（无孤儿）、就绪探测、原生窗口。 ✅ 分发物已实测：干净状态二次启动 health 200，运行时产物（episodic.db 等） 均为首次运行自动生成。 --- ## 📚 文档 | 文档 | 描述 | |------|------| | [API 参考](docs/api.md) | 完整 API 文档 | | [用户指南](docs/user-guide.md) | 入门指南 | | [开发者指南](docs/developer-guide.md) | 贡献指南 | | [架构](docs/architecture.md) | 系统架构 | | [ROADMAP](ROADMAP.md) | 开发路线图与当前状态 | | [ARCHITECTURE](ARCHITECTURE.md) | 项目架构详解 | | [CHANGELOG](CHANGELOG.md) | 版本更新日志 | --- ## 🤝 贡献 1. Fork 仓库 2. 创建功能分支 (`git checkout -b feature/amazing-feature`) 3. 提交更改 (`git commit -m 'Add amazing feature'`) 4. 推送到分支 (`git push origin feature/amazing-feature`) 5. 开启 Pull Request --- ## 📄 许可证 本项目基于 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。 --- ## 🙏 致谢 - 使用 Python ❤️ 构建 - 灵感来自 Claude Code、Cursor 和 Aider - 感谢所有贡献者 --- **如果觉得有用，请给这个仓库点个 Star ⭐！**