# open-agent **Repository Path**: xiaoxinzhss/open-agent ## Basic Information - **Project Name**: open-agent - **Description**: AI 学习项目 无人机 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-07-18 - **Last Updated**: 2026-08-22 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Open Agent（无人机智能助手） 通用 AI Agent 平台，具备工具调用、多步骤推理、长期记忆、知识库 RAG、多 Agent 协作能力。通过 MCP 连接无人机运营管理系统（drone）与高德地图，实现对话式无人机业务操作。 ## 里程碑 | 阶段 | 目标 | 状态 | 设计文档 | |------|------|:---:|---------| | M1 | 基础对话 + 短期记忆 | ✅ | [提示词工程](docs/提示词工程设计方案.md) | | M2 | 长期记忆 + 上下文窗口管理 | ✅ | [记忆功能](docs/大模型记忆功能设计方案.md) · [上下文工程](docs/上下文工程设计方案.md) | | M3 | Tool Calling（函数调用） | ✅ | [工具调用](docs/工具调用设计方案.md) · [MCP](docs/MCP设计方案.md) | | M4 | 知识库 RAG + 认证授权 | ✅ | [RAG](docs/RAG设计方案.md) · [认证授权](docs/认证授权设计方案.md) · [RBAC](docs/RBAC权限模型技术详解.md) | | M5 | Skill 框架 + SubAgent 协作 | ✅ | [Skill](docs/Skill框架设计方案.md) · [SubAgent](docs/SubAgent框架设计方案.md) · [智能体模式](docs/智能体模式设计方案.md) | | M6 | Harness 工程（护栏/评估/反馈） | ✅ | [Harness](docs/Harness工程设计方案.md) | --- ## 项目启动指南（完整流程） open-agent 不是独立运行的系统，它依赖无人机项目（drone）、无人机 MCP-Server 和数据库。按以下顺序启动。 ### 启动架构与依赖关系 ``` ┌─────────────────────────────────────────────────────────┐ │ MySQL (3306) Milvus (19530, 可选) │ │ 库: drone 向量库: drone_knowledge │ └─────────┬───────────────────────┬───────────────────────┘ │ │ ┌─────────▼───────────────────────▼───────────────────────┐ │ drone 后端 (9090) 无人机运营管理系统 │ │ /v1/user/login 认证源 │ └───────┬──────────────────────────────────────────────────┘ │ ┌───────▼──────────────┐ ┌──────────────────────────────┐ │ drone-mcp-server │ │ drone-web 前端 (9090) │ │ (8081) /mcp │ │ 无人机管理页面 │ └───────┬──────────────┘ └──────────────────────────────┘ │ ┌───────▼──────────────────────────────────────────────────┐ │ open-agent 后端 (8080) 智能助手 │ │ ├─ /api/auth/login → drone /v1/user/login（账号认证） │ │ ├─ 对话模型: DeepSeek（deepseek-v4-pro） │ │ ├─ 向量模型: 智谱（embedding-2, 1024 维） │ │ ├─ 工具: MCP 连接 drone-mcp-server (8081) + 高德地图 │ │ └─ 告警查询: drone /v1/alarm/list │ └───────┬──────────────────────────────────────────────────┘ │ ┌───────▼──────────────┐ │ open-agent web 前端 │ │ (5173, /api → 8080) │ └──────────────────────┘ ``` ### 第一步：配置环境变量（模型 Key） | 变量 | 用途 | 必须 | |------|------|:---:| | `DEEPSEEK_API_KEY` | 对话模型 Key（DeepSeek，deepseek-v4-pro） | ✅ | | `ZHIPU_API_KEY` | 向量模型 Key（智谱，embedding-2，历史记忆相关性过滤用） | ✅ 建议 | | `JWT_SECRET` | JWT 签名密钥（不设置则用默认值） | ⬜ | ```bash # macOS / Linux export DEEPSEEK_API_KEY="sk-xxx" export ZHIPU_API_KEY="xxx.yyy" # 智谱 BigModel 平台获取 # Windows PowerShell $env:DEEPSEEK_API_KEY="sk-xxx" $env:ZHIPU_API_KEY="xxx.yyy" ``` ### 第二步：配置数据库 **1. MySQL（必选，drone 项目使用）** - 创建数据库 `drone`，连接信息默认 `root/root@localhost:3306/drone` - 如密码不同，修改 `drone/drone/src/main/resources/application.properties` 的 `spring.datasource.username/password` - 初始化表结构与账号（见 drone 项目 README，账号示例：admin/123456） **2. Milvus 向量数据库（可选，用于历史记忆向量检索）** - 启动方式见 `docs/Docker-Milvus安装手册.md`： ```bash curl -sfL https://raw.githubusercontent.com/milvus-io/milvus/master/scripts/standalone_embed.sh -o standalone_embed.sh bash standalone_embed.sh start curl http://localhost:9091/healthz # 返回 OK ``` - 若暂不启动 Milvus，将 open-agent 的 `application.yml` 中 `memory.context.history-filter.embedding-store` 保持为 `memory`（默认，内存实现） - 使用 Milvus 时改为 `milvus`（向量存储于 localhost:19530，集合 `drone_knowledge`，维度 1024 与智谱 embedding-2 对应） ### 第三步：启动无人机项目（drone） 前置：JDK 17+、MySQL 已启动、Node.js 16+；如需 MQTT 告警另需 EMQX（`mqtt.enabled` 默认 false） ```bash # 3.1 drone 后端（端口 9090） cd drone/drone ./mvnw spring-boot:run # 3.2 drone-web 前端（Vue CLI，端口 9090；若端口被后端占用会自动顺延） cd drone/drone-web npm install npm run serve ``` - 后端 API 文档：`http://localhost:9090/doc.html` - 前端 API 地址硬编码为 `http://localhost:9090`（`main.js` 的 `BASE_URL`） ### 第四步：启动无人机 MCP-Server ```bash # drone-mcp-server（端口 8081，/mcp 端点，转发 drone 9090 的 API） cd drone/drone-mcp-server ./mvnw spring-boot:run ``` - 依赖 drone 后端已启动（`drone.api.url=http://localhost:9090`） ### 第五步：启动智能助手后端（open-agent server，端口 8080） ```bash cd open-agent/server mvn spring-boot:run ``` 验证： ```bash curl http://localhost:8080/api/test # {"status":"ok","timestamp":...} ``` ### 第六步：启动智能助手前端（open-agent web，端口 5173） ```bash cd open-agent/web npm install npm run dev ``` 访问 `http://localhost:5173`，使用 drone 数据库中的账号登录（如 admin/123456）。 ### 验证清单 - [ ] MySQL 已启动且 drone 库存在 - [ ] （可选）Milvus healthz 返回 OK - [ ] drone 后端 9090：`curl http://localhost:9090/doc.html` 有响应 - [ ] drone-mcp-server 8081 已启动 - [ ] open-agent 后端 8080：`curl http://localhost:8080/api/test` 返回 ok - [ ] 浏览器 5173 登录成功（admin/123456） - [ ] 对话中调用无人机工具（如"查看告警列表"）能返回真实数据 ### 常见问题 | 问题 | 处理 | |------|------| | 登录报"认证服务不可用" | drone 后端未启动或端口不是 9090；确认 open-agent 后端能访问 `localhost:9090/v1/user/login` | | 对话能聊但工具调用失败 | 确认 drone-mcp-server (8081) 已启动 | | 历史记忆筛选报嵌入失败 | `ZHIPU_API_KEY` 未配置或无效 | | 知识库检索报 Milvus 连接失败 | 启动 Milvus，或把 `embedding-store` 改回 `memory` | --- ## 项目结构 ``` open-agent/ ├── AGENTS.md # AI 开发规范（SDD 规约驱动） ├── README.md # 本文件 ├── docs/ # 文档体系（详见 docs/README.md） │ ├── specs/ # 功能规约（24 篇） │ ├── tests/ # 测试规约（11 篇） │ └── *.md # 设计方案（18 篇） ├── server/ # Java 后端（Spring Boot 3.3 / Java 17 / Maven） │ └── src/main/java/com/openagent/ │ ├── auth/ # 认证授权（JWT + RBAC 三角色） │ ├── chat/ # 对话引擎（AgentLoop / 多模式路由 / 上下文装配） │ ├── config/ # 配置类 │ ├── controller/ # REST 接口层 │ ├── evaluation/ # 评估可观测（审计 / 指标 / 校验 / 脱敏） │ ├── feedback/ # 反馈学习（用户反馈 / 失败捕获） │ ├── guardrail/ # 安全护栏（参数校验 / 危险操作 / 注入防护） │ ├── knowledge/ # 知识库 RAG（文档加载 / 向量化 / 检索） │ ├── llm/ # LLM 调用层（DeepSeek API） │ ├── mcp/ # MCP 客户端（JSON-RPC 2.0 / HTTP+Stdio） │ ├── memory/ # 记忆模块（短期 / 长期 / 向量 / 裁剪） │ ├── prompt/ # 提示词管理（模板 / 渲染） │ ├── skill/ # Skill 框架（工具打包 / 渐进式披露） │ ├── subagent/ # SubAgent 框架（并行执行 / 黑板汇总） │ └── tool/ # 工具模块（接口 / 注册表 / 执行器 / 实现） └── web/ # 前端（Vue 3 + Vite 4） └── src/ ├── api/ # API 调用封装 ├── components/ # 组件（ChatInput / ChatMessage / ChatSidebar / FeedbackButtons） └── views/ # 页面（Login） ``` --- ## API 端点 ### 核心接口 | 方法 | 路径 | 说明 | 认证 | |------|------|------|:---:| | POST | `/api/auth/login` | 登录（转发 drone 验证，返回 JWT） | ❌ | | GET | `/api/test` | 健康检查 | ❌ | | POST | `/api/chat` | 聊天接口（含工具调用） | ✅ | ### 管理接口 | 方法 | 路径 | 说明 | 认证 | |------|------|------|:---:| | GET | `/api/skills` | 查看已加载 Skill | ✅ | | POST | `/api/skills/validate` | 校验 Skill 定义 | ✅ | | GET | `/api/subagents` | 查看已加载子代理 | ✅ | | POST | `/api/subagents/validate` | 校验子代理定义 | ✅ | | POST | `/api/subagents/run` | 手动触发子代理（调试） | ✅ admin | | POST | `/api/feedback` | 提交用户反馈 | ✅ | | GET | `/api/feedback` | 查询反馈记录 | ✅ | | GET | `/api/memory/history` | 查询会话历史 | ✅ | | DELETE | `/api/memory/history` | 清除会话历史 | ✅ | | POST | `/api/memory/flush` | 手动刷新记忆到文件 | ✅ | --- ## 可用工具（47 个，按角色权限） | 工具组 | 功能 | admin | pilot | maintainer | |--------|------|:---:|:---:|:---:| | 全部 47 个工具 | — | ✅ `*` | — | — | | `drone_*` (3) | 设备查询 | ✅ | ✅ | ✅ | | `task_*` (8) | 任务操作 | ✅ | ✅ | ✅ | | `alarm_*` (11) | 告警查询/处理 | ✅ | ✅ | ✅ | | `media_*` (3) | 媒体查看 | ✅ | ✅ | ✅ | | `dashboard_summary` | 仪表盘 | ✅ | ✅ | ✅ | | `user_*` (3) | 用户管理 | ✅ | ❌ | ❌ | | `fence_*` (3) | 电子围栏 | ✅ | ✅ | ❌ | | `maps_*` (10) | 地图/天气/导航 | ✅ | ✅ | ❌ | | 内置工具 (6) | 文件/Bash/搜索 | ✅ | ✅ | ✅ | --- ## 核心能力 ### 1. 多模式智能体 | 模式 | 触发条件 | 核心机制 | |------|---------|---------| | REACT | 简单问题 | 边想边做，工具循环 | | PLAN | 复杂问题 | 先规划再执行 | | REFLECT | 报告类回答 | 答后审查修正 | ### 2. Skill 框架（渐进式披露） 13 个内置 Skill，按业务场景打包工具，token 从全量 3,450 降为按需。 ### 3. SubAgent 框架（并行执行） 3 个内置子代理，复杂任务分解给多个专业子代理并行执行，黑板汇总结果。 ### 4. 知识库 RAG 文档加载→向量化→检索→注入，支持 Milvus/内存双实现。 ### 5. 安全护栏 参数校验→危险操作确认→注入防护，三层防护。 --- ## 技术栈 - **后端**：Spring Boot 3.3.3 / Java 17 / Maven - **前端**：Vue 3 / Vite 4 - **对话模型**：DeepSeek V4 Pro（`DEEPSEEK_API_KEY`） - **向量模型**：智谱 embedding-2（`ZHIPU_API_KEY`） - **向量数据库**：Milvus（可选，默认内存实现） - **记忆存储**：内存（短期） + Markdown 文件（长期，按日期/大小滚动） + 历史向量过滤 - **工具调用**：OpenAI 兼容 function calling + MCP（JSON-RPC 2.0） - **认证授权**：JWT + RBAC（admin/pilot/maintainer 三角色） --- ## 设计文档 详见 [docs/README.md](docs/README.md) 完整文档索引。 ### 设计方案（22 篇） | 类别 | 文档 | |------|------| | 核心架构 | [Harness 工程](docs/Harness工程设计方案.md) · [上下文工程](docs/上下文工程设计方案.md) · [提示词工程](docs/提示词工程设计方案.md) · [智能体模式](docs/智能体模式设计方案.md) | | 记忆系统 | [记忆功能](docs/大模型记忆功能设计方案.md) · [记忆相关性过滤](docs/会话记忆相关性过滤设计方案.md) · [上下文污染分析](docs/会话上下文污染-根因分析与解决方案.md) | | 工具系统 | [工具调用](docs/工具调用设计方案.md) · [MCP](docs/MCP设计方案.md) · [Skill 框架](docs/Skill框架设计方案.md) · [SubAgent 框架](docs/SubAgent框架设计方案.md) | | 知识库 | [RAG 总体](docs/RAG设计方案.md) · [查询理解](docs/RAG-查询理解增强方案.md) · [检索阶段](docs/RAG-检索阶段方案.md) · [检索后处理](docs/RAG-检索后处理方案.md) | | 安全认证 | [认证授权](docs/认证授权设计方案.md) · [RBAC](docs/RBAC权限模型技术详解.md) · [JWT](docs/登录认证与JWT技术详解.md) | ### 功能规约（24 篇） 详见 [docs/specs/](docs/specs/) 目录。 ### 测试规约（11 篇） 详见 [docs/tests/](docs/tests/) 目录。 --- ## 开发规范 本项目采用 **SDD（规约驱动开发）** 模式，详见 [AGENTS.md](AGENTS.md)。 核心流程：`需求描述 → 规约文档(docs/specs/) → 评审确认 → 生成代码 → 验证测试(docs/tests/)`