auto_agent/docs/feishu_development_guide.md

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. 目录结构

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

图结构：

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+。

cd Agent
python -m venv myenv

Windows PowerShell：

.\myenv\Scripts\Activate.ps1

macOS / Linux：

source myenv/bin/activate

安装依赖：

pip install --upgrade pip
pip install -r requirements.txt
pip install -e .

9.2 环境变量

在 Agent/.env 中配置：

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：

cd Agent
$env:PYTHONPATH="src;$env:PYTHONPATH"
uvicorn web.server:app --host 127.0.0.1 --port 8765

macOS / Linux：

cd Agent
export PYTHONPATH=src:$PYTHONPATH
uvicorn web.server:app --host 127.0.0.1 --port 8765

访问：

http://127.0.0.1:8765

9.4 公网访问（可选）

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