374 lines
11 KiB
Markdown
374 lines
11 KiB
Markdown
# Minor Agent 系统架构、部署与开发指南（飞书版）
|
||
|
||
## 1. 文档目标
|
||
|
||
本文面向 Minor Agent 的研发、部署和维护人员，说明当前系统的整体架构、核心运行链路、Plan TodoList 机制、工具扩展方式、Web 前端交互、部署步骤与常见排障方法。
|
||
|
||
## 2. 系统概览
|
||
|
||
Minor Agent 是一个基于 LangGraph 的多模态本地 Agent 系统，提供 Web 对话界面，支持文本、图片、音频和文件输入，并通过 LangChain Tool 接入外部能力。
|
||
|
||
### 2.1 核心能力
|
||
|
||
- 多模态对话：文本、图片、音频、普通文件。
|
||
- Agent 模式：普通 agent、plan、team 预留。
|
||
- ReAct 工具调用：浏览器控制、屏幕截图、目录查看、人工交互、本机软件控制、Todo 状态更新等。
|
||
- 历史持久化：SQLite 保存对话历史与压缩元信息。
|
||
- 上下文压缩：按 token 阈值触发轻量/全量摘要。
|
||
- Plan TodoList：Plan 模式下生成 `.todo`，前端浮窗展示，执行过程中动态更新。
|
||
|
||
## 3. 目录结构
|
||
|
||
```text
|
||
Agent/
|
||
├─ requirements.txt
|
||
├─ pyproject.toml
|
||
├─ README.md
|
||
├─ docs/
|
||
│ └─ feishu_development_guide.md
|
||
└─ src/
|
||
├─ web/
|
||
│ ├─ server.py # FastAPI 后端 API 与静态资源服务
|
||
│ ├─ app.js # Web 前端主逻辑
|
||
│ ├─ app.css # Web 前端样式
|
||
│ └─ index.html # Web 页面入口
|
||
└─ agent/
|
||
├─ agents/
|
||
│ └─ main_agent.py # 主 Agent 装配入口
|
||
├─ core/
|
||
│ ├─ runtime.py # Agent 执行、Plan 确认、人工交互续跑
|
||
│ ├─ graph.py # LangGraph ReAct 图构建
|
||
│ ├─ nodes.py # LLM 节点与工具产物处理
|
||
│ ├─ routing.py # 工具调用路由/审批识别
|
||
│ ├─ plan.py # Plan 模式路径选择 pending action
|
||
│ ├─ todo_manager.py # `.todo` 读写、解析、状态更新、上下文注入
|
||
│ └─ state.py # LangGraph 状态定义
|
||
├─ memory/
|
||
│ └─ system_prompt.py # 系统提示词、Plan 提示词
|
||
├─ tools/
|
||
│ ├─ tool.py # 通用工具集合
|
||
│ ├─ tool_software_control.py # Windows 本机软件控制工具
|
||
│ └─ __init__.py # 工具注册
|
||
├─ utils/
|
||
│ └─ agent_utils.py # 历史、压缩、多模态文件处理
|
||
├─ history/ # 聊天历史、会话附件、数据库
|
||
└─ workspace/
|
||
└─ .todo # Plan TodoList 文件
|
||
```
|
||
|
||
## 4. 后端架构
|
||
|
||
### 4.1 Web API 层
|
||
|
||
入口文件：`src/web/server.py`
|
||
|
||
主要职责：
|
||
|
||
- 提供静态页面：`/`、`/app.js`、`/app.css`、`/image/{asset}`。
|
||
- 会话管理：新建、切换、清空、删除。
|
||
- 多模态上传：将上传文件临时落盘，再同步到会话目录。
|
||
- Agent 执行：调用 `chatbot_agent` 间接进入 `AgentRuntime`。
|
||
- 人工交互回调：处理工具审批、Plan 路径确认等 pending action。
|
||
- Todo API：`GET /api/todo` 返回当前 `.todo` 内容和结构化任务列表。
|
||
|
||
### 4.2 Runtime 层
|
||
|
||
入口文件：`src/agent/core/runtime.py`
|
||
|
||
核心接口：
|
||
|
||
- `execute_agent(...)`：处理用户新消息，执行普通 agent / plan / team 流程。
|
||
- `continue_after_human_action(...)`：处理人工确认、Plan 路径选择、工具审批后的续跑。
|
||
|
||
运行流程：
|
||
|
||
1. Web UI 提交用户消息。
|
||
2. Runtime 调用 `summarizer(...)` 组装模型上下文。
|
||
3. 普通模式直接执行 LangGraph。
|
||
4. Plan 模式先进入研究阶段，只输出可选路径，不执行任务。
|
||
5. 用户确认路径后，Runtime 调用模型生成 TodoList，并覆盖写入 `agent/workspace/.todo`。
|
||
6. 后续 Plan 上下文会在系统提示词后注入 `.todo` 内容，确保压缩不影响 TodoList。
|
||
|
||
### 4.3 LangGraph 层
|
||
|
||
入口文件：`src/agent/core/graph_builder.py`
|
||
|
||
图结构：
|
||
|
||
```text
|
||
START -> agent -> (tools | END)
|
||
tools -> process_tool_artifact -> agent
|
||
```
|
||
|
||
说明：
|
||
|
||
- `agent` 节点调用已绑定工具的 LLM。
|
||
- `tools` 节点执行 LangChain Tool。
|
||
- `process_tool_artifact` 处理截图等 artifact，将图片转为模型可见的多模态消息。
|
||
|
||
## 5. Plan TodoList 机制
|
||
|
||
### 5.1 设计目标
|
||
|
||
Plan 模式应实现：
|
||
|
||
- 根据用户选择的路径生成动态 TodoList。
|
||
- TodoList 写入 `src/agent/workspace/.todo`。
|
||
- 每次 Plan 模式制定 TodoList 时覆盖旧 `.todo`。
|
||
- 前端以浮窗展示，可收起为悬浮球。
|
||
- Plan 模式上下文开头携带 `.todo`，紧跟系统提示词。
|
||
- 上下文压缩不应压缩或丢失 `.todo`。
|
||
- Agent 执行过程中可更新任务状态。
|
||
|
||
### 5.2 当前实现
|
||
|
||
核心文件：`src/agent/core/todo_manager.py`
|
||
|
||
能力：
|
||
|
||
- `read_todo_text()`：读取 `.todo`。
|
||
- `write_todo_text()`：覆盖写入 `.todo`。
|
||
- `overwrite_todo_from_plan()`：Plan 路径确认后覆盖旧 TodoList。
|
||
- `todo_context_block()`：生成上下文注入块。
|
||
- `system_prompt_with_todo()`：将 `.todo` 紧贴系统提示词之后注入。
|
||
- `parse_todo_items()`：解析 Markdown checkbox 和状态前缀。
|
||
- `update_todo_status()`：按任务描述更新状态，不匹配时追加新任务。
|
||
- `todo_payload()`：提供给前端的结构化数据。
|
||
|
||
### 5.3 前端展示
|
||
|
||
核心文件：`src/web/app.js`、`src/web/app.css`
|
||
|
||
- 前端启动时调用 `/api/todo`。
|
||
- 每 2.5 秒自动刷新一次。
|
||
- TodoList 显示为右侧浮窗。
|
||
- 点击收起后变成悬浮球。
|
||
- 展示任务状态、完成数量、任务文本。
|
||
|
||
### 5.4 Agent 更新 Todo 状态
|
||
|
||
工具：`todo_status_update`
|
||
|
||
注册位置：`src/agent/tools/__init__.py`
|
||
|
||
适用场景：
|
||
|
||
- 任务开始：更新为 `in_progress`。
|
||
- 任务完成：更新为 `completed`。
|
||
- 任务取消：更新为 `cancelled`。
|
||
- 计划变化：追加或修改任务状态。
|
||
|
||
## 6. 工具系统
|
||
|
||
### 6.1 工具注册
|
||
|
||
入口文件：`src/agent/tools/__init__.py`
|
||
|
||
当前主 Agent 工具包含：
|
||
|
||
- `web_search_class`：网络搜索。
|
||
- `date_query_class`：当前日期时间。
|
||
- `screen_capture`：屏幕截图。
|
||
- `browser_control`：浏览器打开/关闭/刷新。
|
||
- `human_interaction`：人工补充、选择、审批。
|
||
- `software_control`：Windows 本机软件打开/关闭/强制关闭。
|
||
- `todo_status_update`：更新 `.todo` 中任务状态。
|
||
- `directory_listing`：查看目录。
|
||
|
||
### 6.2 本机软件控制工具
|
||
|
||
文件：`src/agent/tools/tool_software_control.py`
|
||
|
||
能力：
|
||
|
||
- 扫描 Windows 开始菜单、桌面快捷方式和 App Paths。
|
||
- 建立软件索引：`src/agent/history/data_base/software_index.json`。
|
||
- 根据软件名做模糊匹配。
|
||
- 支持打开、正常关闭、强制关闭。
|
||
|
||
安全策略：
|
||
|
||
- 仅当用户明确要求操作本机软件时调用。
|
||
- `close` 只发送正常关闭请求。
|
||
- `force_close` 或 `force=True` 才允许强制结束进程。
|
||
- 非 Windows 平台返回明确不支持提示。
|
||
|
||
## 7. 历史与上下文压缩
|
||
|
||
核心文件：`src/agent/utils/agent_utils.py`
|
||
|
||
### 7.1 历史存储
|
||
|
||
- SQLite 数据库：`src/agent/history/data_base/chat_history.db`
|
||
- 表：
|
||
- `message_store`：聊天消息。
|
||
- `session_meta`：压缩游标、摘要、上次 token 用量。
|
||
|
||
### 7.2 压缩策略
|
||
|
||
- 当 token 超过轻量阈值，触发轻量压缩，保留最近若干轮对话。
|
||
- 当 token 超过硬阈值，触发全量压缩。
|
||
- `.todo` 不进入历史压缩摘要，而是每次 Plan 模式构造系统提示词时重新从文件读取并注入，因此不会被压缩丢失。
|
||
|
||
## 8. 前端架构
|
||
|
||
文件：`src/web/index.html`、`src/web/app.js`、`src/web/app.css`
|
||
|
||
主要模块：
|
||
|
||
- 会话侧栏：新建、切换、删除会话。
|
||
- 消息区：Markdown 渲染、代码块复制、图片/音频展示。
|
||
- 输入区：文本、文件、麦克风、自动语音输入。
|
||
- Pending Action 卡片：工具审批、人工交互、Plan 路径选择。
|
||
- Todo 浮窗：Plan TodoList 展示和自动刷新。
|
||
|
||
## 9. 部署指南
|
||
|
||
### 9.1 环境准备
|
||
|
||
推荐 Python 3.10+。
|
||
|
||
```bash
|
||
cd Agent
|
||
python -m venv myenv
|
||
```
|
||
|
||
Windows PowerShell：
|
||
|
||
```powershell
|
||
.\myenv\Scripts\Activate.ps1
|
||
```
|
||
|
||
macOS / Linux：
|
||
|
||
```bash
|
||
source myenv/bin/activate
|
||
```
|
||
|
||
安装依赖：
|
||
|
||
```bash
|
||
pip install --upgrade pip
|
||
pip install -r requirements.txt
|
||
pip install -e .
|
||
```
|
||
|
||
### 9.2 环境变量
|
||
|
||
在 `Agent/.env` 中配置：
|
||
|
||
```text
|
||
LLM_BASE_URL=...
|
||
LLM_API_KEY=...
|
||
LLM_MODEL=...
|
||
TTS_BASE_URL=...
|
||
ASR_BASE_URL=...
|
||
RAG_BASE_URL=...
|
||
```
|
||
|
||
其中 TTS、ASR、RAG 可按实际功能启用情况配置。
|
||
|
||
### 9.3 启动 Web 服务
|
||
|
||
Windows PowerShell：
|
||
|
||
```powershell
|
||
cd Agent
|
||
$env:PYTHONPATH="src;$env:PYTHONPATH"
|
||
uvicorn web.server:app --host 127.0.0.1 --port 8765
|
||
```
|
||
|
||
macOS / Linux：
|
||
|
||
```bash
|
||
cd Agent
|
||
export PYTHONPATH=src:$PYTHONPATH
|
||
uvicorn web.server:app --host 127.0.0.1 --port 8765
|
||
```
|
||
|
||
访问：
|
||
|
||
```text
|
||
http://127.0.0.1:8765
|
||
```
|
||
|
||
### 9.4 公网访问（可选）
|
||
|
||
```bash
|
||
cloudflared tunnel --url http://localhost:8765
|
||
```
|
||
|
||
## 10. 开发指南
|
||
|
||
### 10.1 新增工具
|
||
|
||
1. 在 `src/agent/tools/tool.py` 或独立工具文件中实现 `BaseTool`。
|
||
2. 定义 `args_schema`、`name`、`description`、`_run()`、可选 `_arun()`。
|
||
3. 在 `src/agent/tools/__init__.py` 的 `_all_tools` 中注册。
|
||
4. 重启服务，让 `llm.bind_tools(...)` 重新绑定工具。
|
||
|
||
### 10.2 修改 Plan 流程
|
||
|
||
相关文件：
|
||
|
||
- `src/agent/memory/system_prompt.py`
|
||
- `src/agent/core/plan.py`
|
||
- `src/agent/core/runtime.py`
|
||
- `src/agent/core/todo_manager.py`
|
||
|
||
注意事项：
|
||
|
||
- 研究阶段不能执行实际任务或调用工具。
|
||
- 用户确认路径后才能生成 TodoList。
|
||
- 生成 TodoList 后必须覆盖 `.todo`。
|
||
- 执行阶段应根据任务进度调用 `todo_status_update`。
|
||
|
||
### 10.3 修改前端 Todo 浮窗
|
||
|
||
相关文件：
|
||
|
||
- `src/web/app.js`：渲染、刷新、收起逻辑。
|
||
- `src/web/app.css`：浮窗视觉样式。
|
||
- `src/web/server.py`：`/api/todo` 数据接口。
|
||
|
||
## 11. 常见问题排查
|
||
|
||
### 11.1 前端看不到 Todo 浮窗
|
||
|
||
检查：
|
||
|
||
1. 后端 `/api/todo` 是否返回内容。
|
||
2. `src/agent/workspace/.todo` 是否存在且非空。
|
||
3. 浏览器控制台是否有 JS 错误。
|
||
4. 是否被收起为右侧悬浮球。
|
||
|
||
### 11.2 Plan 模式没有写入 `.todo`
|
||
|
||
检查：
|
||
|
||
1. 是否完成了路径选择确认。
|
||
2. `continue_after_human_action` 中 pending type 是否为 `plan_choice`。
|
||
3. 模型是否返回了 TodoList 文本。
|
||
4. 进程是否有写入 `src/agent/workspace/.todo` 的权限。
|
||
|
||
### 11.3 软件控制工具找不到软件
|
||
|
||
处理：
|
||
|
||
1. 使用更具体的软件名称。
|
||
2. 调用时设置 `rescan=True` 重建索引。
|
||
3. 确认软件有开始菜单或桌面快捷方式，或注册了 App Paths。
|
||
4. 检查索引文件：`src/agent/history/data_base/software_index.json`。
|
||
|
||
### 11.4 上下文过长
|
||
|
||
系统会基于 token 阈值自动压缩历史。如果超过硬限制，会提示新建会话。Plan TodoList 不依赖历史摘要保存，而是从 `.todo` 文件注入，因此不会因压缩丢失。
|
||
|
||
## 12. 维护建议
|
||
|
||
- `.todo` 属于运行态工作区文件，不建议作为长期知识库。
|
||
- 对高风险工具应保持人工审批或明确调用条件。
|
||
- 工具描述应写清楚“何时调用”和“何时严禁调用”，降低误调用概率。
|
||
- 修改工具注册后必须重启服务。
|
||
- 修改前端静态文件后刷新浏览器缓存。
|