# lucid **Repository Path**: starboot/lucid ## Basic Information - **Project Name**: lucid - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-05-20 - **Last Updated**: 2026-07-03 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README
Lucid Logo
# 🚀 Lucid — Multi-Agent System: Lucid多智能体框架 Lucid 是基于 LangChain、LangGraph、LangSmith、DeepAgent、Milvus、Neo4j、Redis 构建的企业级多智能体框架系统。

--- # Lucid Enterprise multi-agent collaboration system built with DeepAgents, LangChain/LangGraph, and FastAPI. Vue 3 frontend with SSE streaming chat. ## Features - **Hierarchical Agent Architecture**: Supervisor agent for task planning and decomposition, sub-agents (Research, Data) for specialized tasks - **Human-in-the-Loop**: Sub-agent tool calls require human approval before execution - **Multi-user, Multi-session**: Isolated session storage with CRUD management - **Streaming Response**: Real-time SSE streaming for chat responses - **Dual Memory System**: Short-term (session-scoped TTL) and long-term (persistent with search) memory - **Offline Swagger UI**: Local static assets, no CDN dependency ## Project Structure ``` lucid/ ├── lucid/ # Backend Python package │ ├── agents/ # Supervisor, Research, Data agents + AgentFactory │ ├── api/ │ │ ├── endpoints/ # chat, session, approval, health │ │ ├── models/ # Pydantic request/response models │ │ ├── static/swagger-ui/ # Local Swagger UI assets (offline) │ │ └── server.py # FastAPI app definition │ ├── middleware/ # ApprovalMiddleware, MemoryMiddleware │ ├── memory/ # Short-term, long-term, VectorStore │ ├── tools/ # data_tools, file_tools, web_tools │ └── utils/ # config (layered YAML + env), logger, validators ├── lucid_webui/ # Vue 3 frontend │ └── src/ │ ├── api/ # Axios client + session/chat/approval API modules │ ├── stores/ # Pinia stores (session, chat, approval) │ ├── components/ # ChatMessage, ChatInput, SessionSidebar, ApprovalPanel │ └── views/ # ChatView ├── tests/ # Unit tests (pytest + pytest-asyncio) ├── config/default.yaml # Default configuration ├── examples/ # External framework reference code (not part of this project) ├── main.py # Dev server entry (hot reload, debug logging) ├── api_server.py # Production server entry (multi-worker) ├── docker-compose.yml # App + Redis + PostgreSQL └── pyproject.toml # uv project config ``` ## Quick Start ### Prerequisites - Python 3.12+ - Node.js ≥22.12（前端） - [uv](https://docs.astral.sh/uv/)（Python 包管理器） ### Backend ```bash # Install dependencies uv sync # Copy and edit environment variables cp .env.example .env # Development server (hot reload) uv run python main.py # Production server uv run python api_server.py ``` ### Frontend ```bash cd lucid_webui # Install dependencies npm install # Development server (proxies /api to localhost:8000) npm run dev # Production build npm run build ``` ### Docker ```bash # 基础服务 docker compose up -d # 基础 + 监控 docker compose -f docker-compose.yaml -f docker-compose-extra.yaml up -d # 基础 + 监控 + 管理工具 docker compose -f docker-compose.yaml -f docker-compose-extra.yaml -f docker-compose-manager.yaml up -d ``` ## API Endpoints | Endpoint | Method | Description | |---|---|---| | `/api/health` | GET | Health check | | `/api/sessions` | POST | Create session | | `/api/sessions/{user_id}` | GET | List user sessions | | `/api/sessions/{user_id}/{session_id}` | GET | Get session info | | `/api/sessions/{user_id}/{session_id}` | DELETE | Delete session | | `/api/sessions/{user_id}/{session_id}/clear` | POST | Clear session data | | `/api/chat/{user_id}/{session_id}` | POST | Send message (SSE stream) | | `/api/chat/{user_id}/{session_id}/history` | GET | Chat history | | `/api/approve` | POST | Request tool approval | | `/api/approve/{request_id}` | POST | Approve / reject | | `/api/approve/{request_id}` | GET | Approval status | | `/api/approve/{user_id}/{session_id}/pending` | GET | List pending approvals | | `/api/approve/{request_id}` | DELETE | Cancel approval | | `/api/docs` | GET | Swagger UI (offline) | | `/api/redoc` | GET | ReDoc | ## Architecture ### Agent System ``` User Input → SupervisorAgent ├── intent analysis ├── task decomposition (keyword → Task list) ├── delegation → AgentFactory.create_agent(type) │ ├── ResearchAgent → web_search │ └── DataAgent → calculate / statistics └── aggregation → response ``` - **SupervisorAgent**: Plans, decomposes, delegates, and aggregates. Currently keyword-based; LLM integration planned. - **AgentFactory**: Registry pattern (`register_agent()`), tracks instances per session. - **BaseAgent**: Abstract class with `process()` / `stream()` / `reset()` + `AgentState`. ### Data Flow ``` Browser (Vue) ──SSE──> FastAPI /api/chat ──> SupervisorAgent ──> Sub-agents │ │ └── ApprovalMiddleware ◄── Human-in-the-loop ──┘ │ └── MemoryMiddleware (short-term + long-term) ``` ### Configuration Layered: `config/default.yaml` → environment variable overrides. All config models are Pydantic `BaseModel` subclasses, cached via `@lru_cache()`. ## Running Tests ```bash uv run pytest uv run pytest tests/unit/test_agents.py uv run pytest tests/unit/test_agents.py::TestSupervisorAgent::test_process_simple_request ``` ## Key Conventions - Python 3.12+, managed with `uv`, Tsinghua mirror configured in `pyproject.toml` - Backend imports assume `lucid/` is on `sys.path` (entry scripts handle this) - Agent implementations use keyword-based logic (stubs); LLM integration via LangChain is the next step - In-memory stores throughout (`_sessions`, `_pending_approvals`, `_active_agents`) — marked as placeholders for DB-backed storage - Chinese is used in user-facing output strings ## Tech Stack | Layer | Technology | |---|---| | Agent framework | LangChain, LangGraph, DeepAgents | | API server | FastAPI + Uvicorn | | Frontend | Vue 3 + Vite + TypeScript | | UI library | Element Plus | | State management | Pinia | | HTTP client | Axios | | SSE streaming | @microsoft/fetch-event-source | | Markdown | marked | | Config | YAML + Pydantic | | Vector store | In-memory (Chroma/Pinecone planned) | | Database | PostgreSQL + Redis (via docker-compose) | | Package manager | uv (Python) / npm (Frontend) | ## License MIT # Multi-Agent System 生产级多智能体系统，基于 Docker Compose 部署。业务服务、监控、管理工具三层分离，各文件独立启停。 --- ## 文件说明 | 文件 | 用途 | 运行策略 | 包含服务 | |------|------|----------|----------| | `docker-compose.yaml` | **业务服务** | 🟢 始终运行 | Nginx, App, MySQL, Dameng(国产化,按需), Redis, Neo4j, Milvus, etcd, MinIO | | `docker-compose-extra.yaml` | **监控服务** | 🟢 始终运行 | Prometheus, Grafana | | `docker-compose-manager.yaml` | **Web UI 管理工具** | 🔴 上线后关闭 | RedisInsight, Attu | 上线后关闭管理工具（不影响业务 + 监控）： ```bash docker compose -f docker-compose-manager.yaml down ``` --- ## 架构概览 ``` +-------------+ | Nginx :80 | 前端入口 & 反向代理 | /api/ -> app | +------+------+ | +-------------+-------------+ v v +------------------+ +------------------+ | App :8000 | | 静态文件 | | Metrics :8080 | | /usr/share/ | +--+--+--+--+--+--+ | nginx/html | | | | | | | +------------------+ v v v v v v +---------+ +----------+ +--------+ +--------+ +----------+ | MySQL | | Dameng | | Redis | | Neo4j | | Milvus | | :3306 | | :5236 | | :6379 | |:7474 | | :19530 | +---------+ +----------+ +--------+ |:7687 | | :9091 | +--------+ +--+---+---+ | | +----------+ +----------+ v v +----------+ +----------+ | etcd | | MinIO | | (内部) | |:9000:9001| +----------+ +----------+ - - - - - - - - docker-compose-extra.yaml (monitoring, always on) +--------------+ +--------------+ | Prometheus |--| Grafana | | :9090 | | :3000 | +------+-------+ +--------------+ | scrape metrics from business services - - - - - - - - docker-compose-manager.yaml (web UI, offline after launch) +--------------+ +--------------+ | RedisInsight | | Attu | | :5540 | | :3001 | +------+-------+ +------+-------+ | | Redis GUI Milvus GUI ``` --- ## 目录结构 ``` . ├── docker-compose.yaml # 业务服务 ├── docker-compose-extra.yaml # 监控服务 ├── docker-compose-manager.yaml # Web UI 管理工具 (按需) ├── Dockerfile # 应用镜像构建文件 ├── .env # 环境变量 ├── README.md ├── CLAUDE.md └── deploy/ ├── data/ │ ├── nginx/ │ ├── prometheus/ │ └── grafana/ └── frontend/ └── dist/ # 前端静态文件 (构建产物) ``` --- ## 前置准备 ### 1. 创建 `.env` 文件 在项目根目录创建 `.env` 文件（已提供模板，需填写密码）： ```bash # ==================== 端口配置（统一管理，避免冲突） ==================== NGINX_HOST_PORT=18100 MYSQL_HOST_PORT=18101 REDIS_HOST_PORT=18102 NEO4J_HTTP_HOST_PORT=18103 NEO4J_BOLT_HOST_PORT=18104 MINIO_API_HOST_PORT=18105 MINIO_CONSOLE_HOST_PORT=18106 MILVUS_GRPC_HOST_PORT=18107 MILVUS_METRICS_HOST_PORT=18108 APP_API_HOST_PORT=18109 APP_METRICS_HOST_PORT=18110 PROMETHEUS_HOST_PORT=18111 GRAFANA_HOST_PORT=18112 REDISINSIGHT_HOST_PORT=18119 ATTU_HOST_PORT=18120 DAMENG_HOST_PORT=18121 # ==================== 数据库密码 ==================== # MySQL（必需） MYSQL_ROOT_PASSWORD= # 达梦 DM8（国产化数据库，按需） DAMENG_SYSDBA_PASSWORD= # Neo4j NEO4J_PASSWORD= # MinIO MINIO_ACCESS_KEY=minioadmin MINIO_SECRET_KEY= # Grafana（默认 admin/admin） GRAFANA_ADMIN_USER=admin GRAFANA_ADMIN_PASSWORD= ``` > **注意**：端口修改只需改 `.env` 后 `--force-recreate`。 ### 2. 准备配置文件 所有必需配置已内置于 `docker-compose.yaml` 的 `command` / `environment` 中，无需额外准备。`data/` 下仅保留 Nginx、Prometheus、Grafana 模板配置。 --- ## 快速启动 ```bash # 基础服务 docker compose up -d # 基础 + 监控 docker compose -f docker-compose.yaml -f docker-compose-extra.yaml up -d # 基础 + 监控 + 管理工具 docker compose -f docker-compose.yaml -f docker-compose-extra.yaml -f docker-compose-manager.yaml up -d # 查看状态 docker compose ps # 停止 docker compose down # 仅基础服务 docker compose -f docker-compose.yaml -f docker-compose-extra.yaml -f docker-compose-manager.yaml down # 基础 + 监控 ``` --- ## 业务服务清单 (docker-compose.yaml) | 服务 | 容器名 | 镜像 | 端口 | 用途 | |------|--------|------|------|------| | **Nginx** | `agent-nginx` | `nginx:1.25-alpine` | `80` | 前端入口 & 反向代理 | | **App** | `multi-agent-system` | 本地构建 | `8000` | API 服务 | | **MySQL** | `agent-mysql` | `mysql:8.0` | `3306` | 关系数据库 | | **Dameng** | `agent-dameng` | `dameng/dm8:latest` | `5236` | 国产数据库（按需启用） | | **Redis** | `agent-redis` | `redis:7.2-alpine` | `6379` | 缓存 | | **Neo4j** | `agent-neo4j` | `neo4j:5.26` | `7474` `7687` | 图数据库 | | **Milvus** | `agent-milvus` | `milvusdb/milvus:v2.6.18` | `19530` `9091` | 向量数据库 | | **etcd** | `agent-etcd` | `quay.io/coreos/etcd:v3.5.25` | 内网 `2379` | Milvus 元数据 | | **MinIO** | `agent-minio` | `minio/minio:RELEASE.2024-12-18T13-15-44Z` | `9000` `9001` | Milvus 对象存储 | ## 监控服务清单 (docker-compose-extra.yaml) | 服务 | 容器名 | 访问地址 | 用途 | |------|--------|----------|------| | **Prometheus** | `agent-prometheus` | `http://localhost:18111` | 指标采集与存储 | | **Grafana** | `agent-grafana` | `http://localhost:18112` | 可视化面板 | ## 管理工具清单 (docker-compose-manager.yaml) | 服务 | 容器名 | 访问地址 | 用途 | |------|--------|----------|------| | **RedisInsight** | `agent-redisinsight` | `http://localhost:18119` | Redis 可视化管理 | | **Attu** | `agent-attu` | `http://localhost:18120` | Milvus 可视化管理 | ## 各服务访问方式 ### 前端入口 - **地址**：`http://localhost:18100` - Nginx 作为统一入口，`/api/` 路径自动代理到后端 App 服务，其余路径返回静态文件 - 前端静态文件放在 `deploy/frontend/dist/` 目录 ```bash # 检查 Nginx 状态 curl http://localhost:18100/nginx-health ``` ### MySQL ```bash mysql -h 127.0.0.1 -P 18101 -u root -p docker exec -it agent-mysql mysql -u root -p ``` - 数据库：`agent_db`，用户：`root` (密码见 `.env`) ### 达梦 DM8（国产数据库，按需启用） ```bash # 需先获取镜像：docker load -i dm8_xxx.tar docker exec -it agent-dameng /opt/dmdbms/bin/disql SYSDBA/${DAMENG_SYSDBA_PASSWORD}@localhost:5236 ``` - 端口：`18121`，用户：`SYSDBA`，数据库：`agent_db` - 需要国产化时取消 `docker-compose.yaml` 中 dameng 服务段注释即可 ### Redis ```bash redis-cli -h 127.0.0.1 -p 18102 -a ${REDIS_PASSWORD} docker exec -it agent-redis redis-cli -a ${REDIS_PASSWORD} ``` - 内存上限 4GB，淘汰策略 `allkeys-lru`，AOF + RDB 双写 - 密码认证已启用，密码见 `.env` 中的 `REDIS_PASSWORD` ### Neo4j - 浏览器：`http://localhost:18103`，用户 `neo4j`，密码 `.env` 中 - Bolt：`bolt://localhost:18104` ```bash docker exec -it agent-neo4j cypher-shell -u neo4j -p ``` ### Milvus ```bash curl http://localhost:18108/healthz # 健康状态 curl http://localhost:18108/metrics # 指标 ``` Python SDK 连接：`connections.connect(host="localhost", port="18107")` ### MinIO - Web 控制台：`http://localhost:18106` - S3 API：`http://localhost:18105`，密钥见 `.env` --- ## 监控服务使用 (docker-compose-extra.yaml) ### Prometheus (`http://localhost:18111`) **页面功能：** - `/targets` -- 采集目标状态 (绿色 UP = 正常) - `/alerts` -- 当前触发的告警 - `/graph` -- PromQL 查询图表 - `/rules` -- 告警规则列表 **常用 PromQL：** ```promql up # 所有服务在线状态 rate(process_cpu_seconds_total{job="app"}[5m]) * 100 # CPU 使用率 process_resident_memory_bytes{job="app"} / 1024^3 # 内存占用 GB ``` ### Grafana (`http://localhost:18112`) - 默认账号 `admin`，密码见 `.env` (未设置则 `admin`，首次登录强制修改) - 数据源 Prometheus 已自动配置 **创建面板：** 1. 左侧菜单 -> **Dashboards** -> **New** -> **New Dashboard** -> **Add panel** 2. 选择数据源 `Prometheus`，输入 PromQL 3. 右侧选图表类型 -> **Apply** -> **Save dashboard** **导入社区仪表盘：** 1. **Dashboards** -> **New** -> **Import** 2. 输入 Grafana.com 的 Dashboard ID (搜索 "Milvus"、"MySQL" 等) 3. 选择数据源 -> **Import** **持久化仪表盘：** 导出 JSON -> 放入 `data/grafana/dashboards/json/` -> 重启 Grafana 自动加载 --- ## 管理工具使用 (docker-compose-manager.yaml, 上线后关闭) ### RedisInsight (`http://localhost:18119`) Redis 可视化管理工具。连接信息：Host `redis`，Port `6379`，Password 见 `.env` 中 `REDIS_PASSWORD`。 ### Attu (`http://localhost:18120`) Milvus 可视化管理工具。连接信息：Address `standalone:19530`。 --- ## 健康检查 ```bash curl http://localhost:18109/api/health/live # App docker exec agent-mysql mysqladmin ping -u root -p${MYSQL_ROOT_PASSWORD} # MySQL docker exec agent-redis redis-cli -a ${REDIS_PASSWORD} ping # Redis curl http://localhost:18103 # Neo4j curl http://localhost:18108/healthz # Milvus curl http://localhost:18111/-/healthy # Prometheus curl http://localhost:18112/api/health # Grafana ``` --- ## 查看日志 ```bash docker compose logs -f --tail=100 ``` --- ## 常见操作 ### MySQL 备份与恢复 ```bash docker exec agent-mysql mysqldump -u root -p${MYSQL_ROOT_PASSWORD} agent_db > backup.sql docker exec -i agent-mysql mysql -u root -p${MYSQL_ROOT_PASSWORD} agent_db < backup.sql ``` ### Redis 备份 ```bash docker exec agent-redis redis-cli -a ${REDIS_PASSWORD} BGSAVE ``` ### Neo4j 导出 ```bash docker exec agent-neo4j neo4j-admin dump --database=neo4j --to=/dump/neo4j.dump ``` ### 上线后关闭管理工具 ```bash docker compose -f docker-compose-manager.yaml down ``` ### 只重启监控 (不影响业务) ```bash docker compose -f docker-compose-extra.yaml restart ``` ### 重置某个服务的数据 ```bash docker compose -f docker-compose.yaml stop docker volume rm agent_ docker compose -f docker-compose.yaml up -d ``` --- ## 安全建议 1. **`.env` 文件不要提交到 Git** 2. **生产环境将敏感端口绑定到 `127.0.0.1`**： ```yaml ports: - "127.0.0.1:3306:3306" ``` 3. **修改 Grafana 默认密码** (首次登录强制要求) 4. **Prometheus admin API 生产环境应关闭**：移除 `--web.enable-admin-api` 5. **上线后关闭管理工具**：`docker compose -f docker-compose-manager.yaml down` 6. **etcd 不对外暴露端口** (仅 agent-network 内网访问) 7. **定期更新镜像**避免安全漏洞 --- ## 网络 ### 业务网络 `agent-network` (172.20.0.0/16) 业务服务 + 监控 + 管理工具共用此网络，容器间通过服务名通信： | 服务名 | 内部端口 | |--------|----------| | `nginx` | `80` | | `app` | `8000` `8080` | | `db` | `3306` | | `dameng` | `5236` | | `redis` | `6379` | | `neo4j` | `7474` `7687` | | `standalone` | `19530` `9091` | | `etcd` | `2379` (内部) | | `minio` | `9000` | | `prometheus` | `9090` | | `grafana` | `3000` |