# 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` 属于运行态工作区文件，不建议作为长期知识库。 - 对高风险工具应保持人工审批或明确调用条件。 - 工具描述应写清楚“何时调用”和“何时严禁调用”，降低误调用概率。 - 修改工具注册后必须重启服务。 - 修改前端静态文件后刷新浏览器缓存。