lumen-agent
v1.0.3
Published
基于大模型的 AI Agent 系统 — 远程VM操控、MCP扩展、AI定时任务、RAG知识库、双模记忆、工具审批流
Maintainers
renkinngReadme
流明 Agent (LumenAgent)
一个基于大模型的多轮对话 Agent 系统 — 搭载远程虚拟机操控、MCP 协议扩展、AI 自动定时任务、可插拔技能、RAG 知识库、双模记忆系统、工具审批流等完整的企业级功能模块。
✨ 亮点功能
| 维度 | LumenAgent |
|------|-----------|
| 远程 VM 操控 | Agent 直接通过 SSH 操控远程虚拟机，执行命令、查看状态，支持 WebSocket 实时回显 |
| 工具审批流 | 三档审批模式（无/全部/按危险度）+ 前端弹窗实时审批，超时自动拒绝 |
| MCP 协议支持 | 支持加载外部 MCP Server 作为扩展工具池，前端可选择性启用 |
| AI 定时任务 | Agent 在对话中即可创建/管理定时任务（cron/interval/date），任务触发时自动执行工具循环 |
| 双模记忆 | 每日记忆（自动摘要）+ 长期记忆（自动压缩）+ 双重向量检索（ChromaDB + 语义搜索） |
| 滑动窗口摘要 | 动态压缩策略：N 轮触发一次，压缩前 M 轮为摘要，保留后 K 轮原文 |
| 热更新配置 | Agent 可通过 env_editor 工具运行时修改自身配置，无需重启服务 |
| 双入口 + API Key | 同时运行 CLI 和 Web UI，API Key 认证保护所有端点 |
| 管理前端 | 13 个视图组件覆盖工具/技能/记忆/知识库/虚拟机/定时任务/MCP/系统配置/日志/API Key 全管理场景 |
📋 功能总览
| 模块 | 功能 | 说明 |
|------|------|------|
| 💬 对话 | 流式聊天 | SSE 实时推送，支持思考链、工具调用、正文的端到端流式渲染 |
| 🤖 Agent 模式 | 多轮工具循环 | LLM 自动推理 → 调用工具 → 观察结果 → 继续推理，支持最多 20 轮 |
| 🛠 工具系统 | 11 个内置工具 | Read / Write / Bash / WebSearch / WebFetch / KnowledgeSearch / KnowledgeInsert / MemorySearch / EnvEditor / TaskScheduler / VirtualMachineOperation |
| 🖥 远程虚拟机 | SSH 操控 | Agent 直接连接远程服务器执行命令、查看状态，带 WebSocket 实时回显 |
| 👮 工具审批流 | 三档审批 | 无审批 / 全量审批 / 按危险度审批，前端弹窗实时决策 |
| 🔌 MCP 协议 | 外部工具扩展 | 加载任意 MCP Server 的工具，前端可选择性启用 |
| ⏰ AI 定时任务 | 自动调度 | Agent 对话中创建 cron/interval/date 定时任务，触发时自动执行工具循环 |
| 🧠 知识库 | RAG 向量检索 | 文本切分 → Embedding → ChromaDB 检索，支持入库、删除、重建 |
| 💾 记忆系统 | 自动摘要 + 向量检索 | 每日对话自动摘要落盘，长期记忆自动整理，双重向量语义检索 |
| 📜 会话管理 | 滑动窗口摘要 | SQLite 持久化，游标分页，自动标题生成 |
| 🔌 技能系统 | 可插拔扩展 | SKILL.md 驱动，环境依赖校验，兼容 clawhub 生态 |
| ⚙️ 配置管理 | 热更新 | Agent 调用 env_editor 工具随时读/写配置，无需重启服务 |
| 🔑 API 安全 | API Key 认证 | 完整的 Key 创建/列表/启用/禁用管理，首次启动自动生成默认 Key |
| 🌐 双入口 | Web UI + CLI | Vue 3 管理控制台；CLI 命令行模式，支持斜杠命令 |
🗂 项目结构
LumenAgent/
├── lumen_agent/ # 后端 Python 包（~7000 行）
│ ├── agent/ # Agent 核心引擎
│ │ ├── agent.py # AgentStreamExecutor — 多轮工具循环引擎
│ │ ├── context.py # 上下文管理、防循环守卫
│ │ ├── memory/
│ │ │ └── memory_utils.py # 记忆文件操作工具
│ │ ├── prompts/
│ │ │ ├── builder.py # System Prompt 构造器
│ │ │ └── docs/ # Prompt 模板
│ │ ├── skills/
│ │ │ ├── loader.py # 技能加载器
│ │ │ └── meta.py # 技能元数据模型
│ │ ├── tokens/
│ │ │ ├── char_counter.py # 字符计数
│ │ │ └── tiktoken_counter.py # tiktoken 计数
│ │ └── tools/ # 11 个工具实现
│ │ ├── base.py # BaseTool + ToolResult 基类
│ │ ├── registry.py # 工具注册表（装饰器驱动）
│ │ ├── read.py / write.py / bash.py # 文件/命令操作
│ │ ├── web_search.py / web_fetch.py # 网络工具
│ │ ├── knowledge.py # 知识库检索与入库
│ │ ├── memory_search.py # 记忆向量检索
│ │ ├── env_editor.py # .env 配置编辑（热更新）
│ │ ├── task_scheduler.py # ⌚ 定时任务创建与管理
│ │ ├── vm_operation.py # 🖥 虚拟机 SSH 操作
│ │ └── mcp_bridge.py # 🔌 MCP 工具桥接
│ ├── api/ # FastAPI 路由层（28+ 端点）
│ │ ├── routers/
│ │ │ ├── chat.py # 对话：POST + SSE 流式 + 中断 + 审批
│ │ │ ├── sessions.py # 会话 CRUD + 游标分页
│ │ │ ├── vm.py # 🖥 虚拟机注册/更新/删除/列表/执行
│ │ │ ├── vm_ws.py # 🖥 WebSocket 实时回显
│ │ │ ├── scheduler_router.py # ⏰ 定时任务 CRUD + 执行记录
│ │ │ ├── mcp_servers.py # 🔌 MCP Server 配置管理
│ │ │ ├── api_keys.py # 🔑 API Key 管理
│ │ │ ├── knowledge.py # 📚 知识库管理
│ │ │ ├── configs.py / logs_router.py # ⚙️ 配置 / 📋 日志
│ │ │ ├── tools.py / skills.py # 🛠 工具/技能列表
│ │ │ └── memories.py # 🧠 记忆文件浏览
│ │ └── schemas/ # Pydantic DTO + SSE 事件
│ ├── application/ # 应用服务层（~2500 行）
│ │ ├── service/
│ │ │ ├── chat_service.py # 对话编排（单轮/流式/Agent）
│ │ │ ├── vm_connection_service.py # 🖥 SSH 连接池 + 流式命令执行
│ │ │ ├── scheduler_task_service.py # ⏰ 定时任务服务
│ │ │ ├── mcp_server_service.py # 🔌 MCP 服务
│ │ │ ├── summary_service.py # 📝 滑动窗口摘要 + 长期记忆整理
│ │ │ ├── rag_service.py # 📚 知识库 RAG 服务
│ │ │ ├── memory_rag_service.py # 🧠 记忆向量检索服务
│ │ │ ├── config_service.py # ⚙️ 配置管理服务
│ │ │ ├── api_key_service.py # 🔑 API Key 服务
│ │ │ ├── memory_file_service.py # 🧠 记忆文件浏览服务
│ │ │ ├── log_service.py # 📋 日志服务
│ │ │ └── title_service.py # 🏷 会话标题自动生成
│ │ └── utils/
│ │ ├── context_assembly.py # 上下文组装 + Token 预算检查
│ │ ├── text_splitter.py # 文本切分
│ │ └── llm_error_policy.py # LLM 链路错误映射
│ ├── infrastructure/ # 基础设施层
│ │ ├── startup/ # 启动引导
│ │ │ ├── workspace.py # 工作区初始化
│ │ │ ├── uvicorn_runner.py # uvicorn 启动
│ │ │ └── flask_proxy.py # Flask 静态 + API 代理
│ │ ├── data_base/ # SQLite 仓储
│ │ │ ├── sqlite_conversation.py # 会话仓储
│ │ │ ├── sqlite_knowledge.py # 知识库仓储
│ │ │ ├── sqlite_scheduler.py # 定时任务仓储
│ │ │ ├── sqlite_mcp.py # MCP 配置仓储
│ │ │ ├── sqlite_api_key.py # API Key 仓储
│ │ │ └── sqlite_vm_config.py # VM 配置仓储
│ │ ├── client/
│ │ │ ├── deepseek_client.py # DeepSeek HTTP 客户端
│ │ │ ├── embedding_client.py # 阿里云 Embedding 客户端
│ │ │ ├── chroma_client.py # Chroma 向量存储封装
│ │ │ └── mcp_client.py # MCP SSE 客户端管理器
│ │ ├── scheduler/
│ │ │ ├── scheduler_service.py # APScheduler 封装（单例）
│ │ │ └── tasks.py # 预定义系统任务
│ │ ├── virtual_machine/
│ │ │ └── virtual_machine_registry.py # VM 注册中心
│ │ ├── approval_registry.py # 👮 工具审批注册表
│ │ ├── vm_event_bus.py # 🖥 VM 事件总线
│ │ ├── websocket_manager.py # 🖥 WebSocket 连接管理器
│ │ ├── sse_registry.py # SSE 中断注册表
│ │ └── http_pool.py # 共享 HTTP 连接池
│ ├── model_adapters/ # 模型适配层
│ │ ├── base.py # ModelAdapter 抽象接口
│ │ └── deepseek.py # DeepSeek 适配器实现
├── webChannel/ # 前端 Vue 3 + TypeScript（~8800 行）
│ └── src/
│ ├── App.vue # 主布局（侧栏导航 + 顶栏 + 内容区 + 输入区）
│ ├── components/ # 13 个视图组件
│ │ ├── ChatView.vue # 对话面板
│ │ ├── ChatMessage.vue # 消息渲染（Markdown/思考链/工具/审批）
│ │ ├── SessionList.vue # 会话列表
│ │ ├── VMView.vue (1366 行) # 🖥 虚拟机管理 + 终端
│ │ ├── SchedulerView.vue # ⏰ 定时任务管理
│ │ ├── MCPServerView.vue # 🔌 MCP 配置
│ │ ├── KnowledgeView.vue # 📚 知识库管理
│ │ ├── ConfigView.vue # ⚙️ 系统配置编辑
│ │ ├── LogView.vue # 📋 日志实时监控
│ │ ├── MemoryView.vue / ToolView.vue / SkillView.vue / ApiKeyManager.vue
│ │ └── MiniChatPanel.vue # 浮动聊天面板
│ ├── composables/
│ │ ├── useChatStream.ts # SSE 流式消息管理
│ │ └── useVMWebSocket.ts # 🖥 VM WebSocket 连接管理
│ ├── types.ts # TypeScript 类型定义
│ └── utils/markdown.ts # Markdown + 代码高亮渲染
├── work_space/ # 工作空间
│ ├── memory/ # 每日记忆文件 YYYY-MM-DD.md
│ ├── MEMORY.md # 长期记忆
│ ├── ME.md / USER.md / RULE.md # 项目/用户/规则上下文
│ └── skills/ # 可插拔技能包
├── pyproject.toml # Python 包配置
├── package.json / start.js / install.js # Node.js 启动/安装脚本
└── lumen_agent/.env / config.json # 环境变量 + 默认配置🚀 快速启动
0️⃣ 一行命令启动（推荐）
确保已安装 Node.js ≥ 18 和 Python ≥ 3.13 后：
# 一键安装 + 启动（自动装 Python/Node 依赖、构建前端、启动服务）
npx lumen-start首次运行会自动完成：Python 依赖安装 → 前端依赖安装 → 前端构建 → 服务启动。
然后只需配置 lumen_agent/.env 中的 LLM_API_KEY，重启即可。
国内用户：npm 和 pip 下载慢时可配置镜像加速：
npm config set registry https://registry.npmmirror.com pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
1️⃣ 环境要求
- Python ≥ 3.13
- Node.js ≥ 18
- 一个 DeepSeek API Key（或其他兼容的 OpenAI API）
- 一个 阿里云 DashScope API Key（仅知识库 RAG + 记忆向量检索需要，纯对话可不配）
2️⃣ 配置环境变量
编辑 lumen_agent/.env：
# ── LLM 配置 ──
LLM_API_KEY=sk-your-deepseek-api-key
LLM_BASE_URL=https://api.deepseek.com
LLM_MODEL=deepseek-v4-flash
# ── 阿里云 Embedding（可选，RAG/记忆需要）──
EMBEDDING_API_KEY=sk-your-dashscope-api-key
EMBEDDING_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings
EMBEDDING_MODEL=text-embedding-v4
# ── 服务端口 ──
HOST=127.0.0.1
PORT=21675全部可配置项详见 config.json（同名 .env 变量覆盖）。
3️⃣ 全局安装后启动（或手动分步）
# 方式一：全局安装
npm install -g lumen-agent
lumen-start
# 方式二：克隆仓库手动分步
git clone https://github.com/renking-W/LumenAgent.git
cd LumenAgent
npm install # 自动安装 Python + Node 依赖
npm start # 构建前端 + 启动服务4️⃣ 传统方式：纯 Python 启动后端
pip install -r lumen_agent/requirements.txt
python -m lumen_agent.app后端默认运行在 http://127.0.0.1:21675。
首次启动会自动创建默认 API Key 并打印到日志，请妥善保管。
- Swagger 文档：
http://127.0.0.1:21675/docs - 健康检查：
http://127.0.0.1:21675/health
4️⃣ 启动前端（开发模式）
cd webChannel
npm install
npm run dev前端默认运行在 http://127.0.0.1:5173，已配置代理转发 API 请求到后端 21675 端口。
5️⃣ 构建生产版本
cd webChannel
npm run build构建产物输出到 webChannel/dist/，后端启动时自动通过 Flask 提供静态文件服务，访问 http://127.0.0.1:21675 即可。
6️⃣ CLI 模式（可选）
# 自动同时启动 HTTP 服务
lumen-cli
# 或
python -m lumen_agent.application.common.chat_in_cliCLI 支持斜杠命令：/exit /new /knowledge
🖥 管理控制台界面
导航面板
左侧栏包含 10 个管理视图，按功能分组：
核心
| 视图 | 说明 | |------|------| | 💬 对话 | 实时流式对话面板 | | 🛠️ 工具 | 浏览 Agent 的全部可用工具及其参数 | | 🎯 技能 | 展示可插拔技能的状态（可用/缺失环境） | | 🧠 记忆 | 浏览每日记忆 + 长期记忆文件 |
功能
| 视图 | 说明 | |------|------| | 🔌 MCP | 管理 MCP Server 配置（CRUD + 测试连接） | | 🖥 虚拟机 | 注册/管理远程虚拟机，实时终端回显 | | 📚 知识库 | 知识文档入库、检索、Chunk 详情查看 | | ⏰ 定时任务 | 查看 AI 创建的定时任务及执行记录 |
其它
| 视图 | 说明 | |------|------| | ⚙️ 系统配置 | 编辑系统运行参数 | | 📋 日志 | 实时查看/下载日志文件 |
1️⃣ 对话视图
会话列表
- 所有历史会话按更新时间排序
- 相对时间显示（"3 分钟前"）
- 支持新建/切换/删除（带确认弹窗）
- 可折叠收起
消息区域 — 每条助手消息按区块渲染：
| 区块 | 渲染方式 | 说明 |
|------|---------|------|
| 💭 思考链 | 可折叠 <details> | DeepSeek reasoning_content，默认收起 |
| 📝 正文 | GFM Markdown | 代码高亮 + 表格 + 链接 + 复制按钮 |
| 🛠 工具调用 | 可折叠 details | 工具名 + 参数 + 耗时 + 结果 |
| 👮 审批等待 | 弹窗按钮 | 批准/拒绝当前工具调用（按审批模式） |
| ⚠️ 错误 | 可折叠 details | 错误详情 + 「重试」按钮 |
模式切换
- Simple 模式 — 单轮对话，LLM 直接回复
- Agent 模式（默认）— 多轮工具循环，LLM 可调用 11 个工具
输入区
- 多行文本框（自动调整高度 4–10 行）
Enter发送，Ctrl+Enter换行- 发送中可随时中断流式回复
- 支持选择 MCP Server 挂载到当前对话
2️⃣ 🖥 虚拟机管理视图
这是项目的核心特色功能之一，提供完整的远程服务器管理体验。
- 注册 VM：填写 IP、端口、用户名、密码
- 状态面板：查看所有已注册 VM 的连接状态
- 内置终端：通过 WebSocket 实时回显，支持命令执行、流式输出、退出码显示
- 一键操作：连接/断开/删除，操作结果实时反馈
- Agent 联动：Agent 可在对话中自动连接 VM 执行任务，用户通过 Web 界面实时观察执行过程
3️⃣ ⏰ AI 定时任务视图
- 展示所有 AI 创建的定时任务
- 显示触发器类型（cron/interval/date）、表达式、下次执行时间
- 查看每次触发的执行记录 + 输出内容
- 支持暂停/恢复/删除
4️⃣ 🔌 MCP Server 管理
- 添加/编辑/删除 MCP Server 配置
- 测试连接并查看暴露的工具列表
- 对话时通过下拉选择框选择性挂载 MCP 工具
🧠 核心架构解读
Agent 工具循环
用户输入
│
▼
┌─────────────────────────────────┐
│ 1. 上下文组装 │
│ (摘要 + 历史 + 本轮消息 │
│ + Token 预算检查) │
└──────────┬──────────────────────┘
▼
┌─────────────────────────────────┐
│ 2. LLM 推理（流式 SSE） │
│ 输出: text + thinking │
│ 或发起: tool_use │
└──────┬──────────────────────────┘
│
├── 无工具调用 → yield "done" → 落库 + 摘要触发
│
└── 有工具调用
│
▼
┌───────────────────┐
│ 3. 审批检查 │
│ (选: 无/全部/危险) │
└──────┬────────────┘
│ 通过
▼
┌───────────────────┐
│ 4. 执行工具 │
│ (逐个流式执行) │
└──────┬────────────┘
│
▼
┌───────────────────┐
│ 5. 结果返回 LLM │
│ → 回到步骤 2 │
│ (最多 20 轮) │
└───────────────────┘滑动窗口摘要
轮次: 1 2 3 4 5 6 │ 7 8 9 ...
│
▼
┌───────────┐
│ 触发摘要 │
│ (阈值=6) │
└───────────┘
│
压缩前 4 轮为摘要
保留后 2 轮为原文
count → 2summary_threshold_turns=6：每 6 轮触发一次摘要summary_compress_turns=4：前 4 轮压缩为摘要summary_keep_turns=2：后 2 轮保留原文- 摘要结果同时写入每日记忆文件（YYYY-MM-DD.md）+ ChromaDB 向量库
SSE 事件流
Agent 模式下完整的 SSE 事件序列：
event: reasoning_update ← 思考链增量
event: message_update ← 正文增量
event: tool_calls ← 本轮工具调用列表
event: awaiting_approval ← 等待用户审批（含工具 ID/名称/参数）
event: tool_execution_start← 单个工具开始执行
event: tool_execution_end ← 单个工具执行完毕（含耗时）
event: reasoning_update ← 工具结果返回后继续推理
event: message_update ← 最终回复
event: assistant_done ← 本轮完成
event: error ← 错误（可选）
[DONE] ← 流结束标记🛠 工具系统详解
11 个内置工具
| 工具名 | 用途 | 需审批 | 说明 |
|--------|------|--------|------|
| read | 读取文件 | 否 | offset/limit 分块，单次 2000 行 / 50KB |
| write | 写入/追加/替换 | 否 | 三种写入模式 |
| bash | 执行 Shell 命令 | 否 | 自动适配 Win/Unix，30s 超时 |
| web_search | 网页搜索 | 否 | DuckDuckGo，无需额外 API Key |
| web_fetch | 网页抓取 | 否 | HTML → Markdown，支持文件下载 |
| knowledge_search | RAG 知识检索 | 否 | 从 ChromaDB 检索相关 chunk |
| knowledge_insert | 知识入库 | 否 | 文本/文件入库到知识库 |
| memory_search | 记忆检索 | 否 | 语义检索历史对话记忆 |
| env_editor | 配置编辑 | 否 | 运行时读写 .env，热更新 |
| task_scheduler | 定时任务管理 | ✅ 是 | 创建/列表/删除/暂停/恢复定时任务 |
| virtual_machine_operation | 虚拟机操作 | ✅ 是 | SSH 执行命令/连接/断开/查看状态 |
工具审批系统
三种审批模式可在对话时动态切换：
| 模式 | 行为 | 适用场景 |
|------|------|---------|
| none | 不审批，直接执行 | 调试/可信环境 |
| dangerous（默认） | 仅审批标记 requires_approval=True 的工具 | 日常使用 |
| all | 全部工具调用都需审批 | 高安全要求 |
审批流程：
- LLM 发起工具调用 → 进入审批挂起状态
- 前端弹出审批对话框，展示工具名称 + 参数
- 用户逐一点击批准/拒绝（或超时自动全部拒绝）
- 拒绝的工具注入
"用户已拒绝该工具调用"错误结果 - Agent 根据结果继续推理
MCP 工具扩展
支持加载任意 MCP Server 作为工具源：
- 前端管理面板配置 MCP Server URL + API Key
- 启动时自动连接所有 enabled 的 Server
- 对话时通过下拉选择框选择性挂载
- 挂载后 MCP Server 暴露的工具自动注入 Agent 工具池
🖥 虚拟机模块架构
┌────────────────────────────────────────────────────────┐
│ Agent (VirtualMachineOperation 工具) │
│ - exec_command / connect / disconnect / get_status │
│ - list_vms │
└──────────┬─────────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────┐
│ VMConnectionService (SSH 连接池) │
│ - asyncssh 驱动，支持连接复用 │
│ - 流式命令执行 (async for kind, data in ...) │
└────┬──────────────┬──────────────────┬─────────────────┘
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────────┐ ┌──────────────────┐
│ SQLite │ │ WebSocket │ │ VMEventBus │
│ VM 配置 │ │ 连接管理器 │ │ (事件发布/订阅) │
│ 仓储 │ │ (前端实时) │ │ │
└──────────┘ └──────────────┘ └──────────────────┘
前端 VMView.vue：
- 注册/管理 VM 配置
- 通过 WebSocket 实时订阅命令执行输出
- 内置终端面板
- 与 Agent 对话中的 VM 操作联动⏰ AI 定时任务系统
Agent 通过 task_scheduler 工具可在对话中直接创建定时任务：
用户: "每天早上9点帮我查一下AI的最新资讯"
Agent → 调用 task_scheduler (action=create, trigger_type=cron,
trigger_expr="0 9 * * *", ...)
系统：
┌─ 向用户确认任务步骤 + 产物格式
├─ 注册到 APScheduler
├─ 持久化到 scheduled_tasks 表
└─ 返回任务 ID
到达触发时间：
┌─ 使用独立 session (__scheduled__{id})
├─ 执行一轮完整的 Agent 工具循环
├─ 结果落库到 scheduled_executions 表
└─ 可被前端 SchedulerView 查看支持三种触发器：cron（0 9 * * *）/ interval（1800秒）/ date（ISO 时间）
📝 记忆系统
双层结构
记忆系统
├── 📅 每日记忆 (work_space/memory/YYYY-MM-DD.md)
│ ├── 每次摘要触发时自动追加
│ ├── 按 "---" + "## timestamp session=xxx" 分段
│ └── 自动向量化 → ChromaDB (memory_store)
│
└── 📌 长期记忆 (work_space/memory/MEMORY.md)
├── 超过 150KB 时自动 LLM 压缩整理
├── 保持内容精炼
└── 启动时全量索引 → ChromaDB检索方式
- Agent 语义检索：
memory_search工具 → ChromaDB 向量搜索 - 前端浏览：记忆面板查看全部文件内容 + 类型区分
📚 知识库 (RAG)
| 步骤 | 技术栈 | 说明 | |------|--------|------| | 文本切分 | 自定义 TextSplitter | 按 chunk_size=500, overlap=150 切分 | | 向量化 | 阿里云 DashScope Embedding | text-embedding-v4 | | 存储 | ChromaDB | collection: knowledge_base | | 检索 | 余弦相似度 | top_k=5, threshold=0.2 |
向量模型可以自定义，只需要修改config.json中的EMBEDDING_BASE_URL、EMBEDDING_MODEL 即可
🔧 技能扩展
技能是预定义的可复用指令包，兼容 clawhub 生态。
work_space/skills/
└── skill-creator-0.1.0/
├── SKILL.md # YAML frontmatter + Markdown 指令
├── _meta.json # 元数据
└── scripts/ # 配套脚本SKILL.md frontmatter：
---
name: skill-name
description: 简要描述
requires:
env: [API_KEY_NAME] # 可选：依赖的环境变量
primaryEnv: API_KEY_NAME # 可选：主环境变量名
emoji: 🔧 # 可选：显示图标
---通过 load_skills() 自动扫描加载，校验环境变量后标记为「可用/不可用」。
📡 API 一览
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /health | 健康检查 |
| POST | /v1/chat | 整段对话（非流式） |
| POST | /v1/chat/stream | SSE 流式对话 |
| POST | /v1/chat/stream/interrupt | 中断流式对话 |
| POST | /v1/chat/stream/approve | 提交工具审批决策 |
| GET | /v1/sessions | 会话列表（分页） |
| GET | /v1/sessions/{id}/messages | 会话消息（游标分页） |
| POST | /v1/sessions/{id}/messages | 追加消息 |
| PUT | /v1/sessions/{id}/title | 修改标题 |
| DELETE | /v1/sessions/{id} | 删除会话 |
| GET | /v1/tools | 工具列表 |
| GET | /v1/skills | 技能列表 |
| GET | /v1/memories | 记忆文件列表 |
| POST | /v1/knowledge/ingest | 知识入库 |
| POST | /v1/knowledge/search | 知识检索 |
| GET | /v1/knowledge/collections | 知识库集合列表 |
| GET | /v1/knowledge/documents | 知识文档列表 |
| GET | /v1/mcp-servers | MCP Server 列表 |
| POST | /v1/mcp-servers | 创建 MCP Server |
| PUT | /v1/mcp-servers/{id} | 更新 MCP Server |
| DELETE | /v1/mcp-servers/{id} | 删除 MCP Server |
| POST | /v1/mcp-servers/{id}/test | 测试 MCP Server 连接 |
| GET | /v1/scheduled-tasks | 定时任务列表 |
| POST | /v1/scheduled-tasks | 创建定时任务 |
| DELETE | /v1/scheduled-tasks/{task_id} | 删除定时任务 |
| GET | /v1/scheduled-tasks/{task_id}/executions | 任务执行记录 |
| GET | /v1/api-keys | API Key 列表 |
| POST | /v1/api-keys | 创建 API Key |
| DELETE | /v1/api-keys/{key_id} | 删除 API Key |
| PATCH | /v1/api-keys/{key_id} | 启用/禁用 API Key |
| GET | /v1/config | 获取配置列表 |
| PUT | /v1/config | 更新配置项 |
| GET | /v1/logs | 日志文件列表 |
| GET | /v1/logs/{filename} | 日志文件内容 |
| GET | /v1/vm | VM 列表 |
| POST | /v1/vm/register | 注册 VM |
| PUT | /v1/vm/{vm_id} | 更新 VM 配置 |
| POST | /v1/vm/execute | 流式执行命令 |
| DELETE | /v1/vm/{vm_id} | 删除 VM |
| WS | /v1/vm/ws | VM 实时事件 WebSocket |
⚙️ 完整配置项
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| LLM_API_KEY | (必填) | DeepSeek API 密钥 |
| LLM_BASE_URL | https://api.deepseek.com | API 地址 |
| LLM_MODEL | deepseek-v4-flash | 模型标识 |
| LLM_TEMPERATURE | null | 温度参数 |
| LLM_MAX_TOKENS | null | 最大输出 Token |
| LLM_ENABLE_THINKING | true | 是否启用思考链 |
| EMBEDDING_API_KEY | (可选) | 阿里云 Embedding API |
| EMBEDDING_MODEL | text-embedding-v4 | Embedding 模型 |
| HOST / PORT | 127.0.0.1:21675 | 服务监听地址 |
| CORS_ORIGINS | http://127.0.0.1:5173 | 允许的跨域源 |
| AGENT_MAX_TURNS | 20 | 工具循环最大轮次 |
| TOOL_APPROVAL_MODE | dangerous | 审批模式 |
| TOOL_APPROVAL_TIMEOUT | 300 | 审批超时（秒） |
| CONVERSATION_MAX_CONTEXT_MESSAGES | 5 | 取最近 N 条消息 |
| SUMMARY_THRESHOLD_TURNS | 6 | 摘要触发轮次 |
| SUMMARY_COMPRESS_TURNS | 4 | 压缩轮次数 |
| SUMMARY_KEEP_TURNS | 2 | 保留原文轮次数 |
| RAG_CHUNK_SIZE / RAG_CHUNK_OVERLAP | 500 / 150 | 文本切分 |
| RAG_TOP_K / RAG_SIMILARITY_THRESHOLD | 5 / 0.2 | 检索参数 |
| SCHEDULER_TIMEZONE | Asia/Shanghai | 时区 |
| VM_SSH_TIMEOUT | 60 | SSH 连接超时 |
| VM_SSH_KEEPALIVE | 40 | SSH 心跳间隔 |
| VM_EXECUTE_TIMEOUT | 30 | 命令执行超时 |
| VM_DANGEROUS_COMMANDS | rm -rf,shutdown... | 危险命令列表 |
Agent 可通过
env_editor工具运行时查看和修改配置，无需重启。
🧪 技术栈
| 层 | 技术 | 版本 | |---|------|------| | 语言 | Python | ≥ 3.13 | | Web 框架 | FastAPI | ≥ 0.136 | | 模型适配 | DeepSeek API / OpenAI 兼容 | - | | 向量存储 | ChromaDB | ≥ 1.5.9 | | Embedding | 阿里云 DashScope / 阿里灵积 | - | | 调度器 | APScheduler | ≥ 3.10 | | SSH | asyncssh | (VM 模块) | | MCP | Python MCP SDK | ≥ 1.0 | | 数据库 | SQLite (aiosqlite) | - | | 前端框架 | Vue 3 + TypeScript | ≥ 3.5 | | UI 库 | Element Plus | ≥ 2.10 | | 前端构建 | Vite | ≥ 7.1 |
📦 依赖安装
# Python 依赖
pip install -r lumen_agent/requirements.txt
# 前端依赖
cd webChannel && npm install💡 设计原则
- 模型无关：通过
ModelAdapter抽象层，理论上可切换任意 LLM（当前适配 DeepSeek） - 全局单例模式：HTTP 连接池 / MCP 管理器 / 审批注册表 / SSE 注册表 / VM 连接服务 均为全局单例
- 热配置：Agent 可在运行时修改自身配置，无需重启
- 双入口：CLI 模式自动启动后台 HTTP 服务
- 最小依赖：核心 Python 依赖仅 10 个，前端仅 8 个
The End
项目持续开发中，欢迎贡献！
联系方式：[email protected]
如果觉得本项目有帮助，欢迎给一个 ⭐ Star！