Skip to content

Latest commit

 

History

History
323 lines (251 loc) · 9.09 KB

README.md

File metadata and controls

323 lines (251 loc) · 9.09 KB

MLA-V3 Web UI

这是一个简单的 Web 前端界面，用于与 MLA-V3 框架进行交互。

功能特性

  • 🎨 现代化的对话界面
  • 🤖 显示当前执行的 Agent（带头像）
  • 📂 显示 Task ID 和 Workspace 路径
  • 🧭 可视化入口 Agent 选择器：在 Task ID 左侧选择对话入口智能体，并实时展示该智能体为根的 Agent Tree
  • 📊 实时流式输出（JSONL 事件流）
  • 🔔 Human-in-Loop (HIL) 交互支持：自动检测并响应 Agent 的人类交互任务
  • 💬 支持多行输入和 Enter 发送
  • 💾 对话历史自动保存到 task_id/conversations/ 目录
  • 📁 集成文件浏览器，可查看和管理任务文件

安装依赖

pip install flask flask-cors

或者添加到 requirements.txt：

flask
flask-cors

启动方式

方法 1：使用便捷脚本（推荐）

注意：当前版本使用进程内 direct-tools 运行时，不需要单独启动工具服务器。首次运行时会询问您设置工作空间路径（Workspace Root）。

  1. 启动服务器（会自动启动 Web UI 服务并调用 Python 后端）：

    • 首次运行时会提示输入工作空间路径
    • 直接回车将使用当前目录作为工作空间（与 CLI 模式相同）
    • 或输入绝对路径指定自定义工作空间
    cd web_ui/server
./start.sh

    或者使用统一管理脚本：

    cd web_ui/server
./server start

  2. 停止服务器：

    cd web_ui/server
./stop.sh

    或者：

    cd web_ui/server
./server stop

  3. 查看服务器状态：

    cd web_ui/server
./server status

    会显示 Web UI 运行状态。

  4. 重启服务器：

    cd web_ui/server
./server restart

  5. 打开浏览器访问：

    http://localhost:22228

    服务器地址：

方法 2：直接运行 Python（传统方式）

注意：如果使用此方法，只需要启动 Web UI 服务；工具调用由 Python 后端进程内完成。

  1. 启动 Web UI 服务器：

    cd web_ui/server
python server.py

  2. 打开浏览器访问：

    http://localhost:22228

端口配置

  • Web UI 默认端口: 22228（因为 macOS 的 AirPlay 可能占用 5000 端口）
  • 可以通过环境变量指定其他端口： 
    cd web_ui/server
PORT=8080 ./start.sh
# 或
PORT=8080 ./server start

使用说明

1. 设置 Task ID

在顶部的 "Task ID" 输入框中输入任务目录的绝对路径，例如：

/mla_task

或

/Users/username/Desktop/my_project

2. Agent 配置

  • 入口 Agent 选择：
    • 在 Task ID 左侧有一个 Select Agent 按钮，默认入口 Agent 为 alpha_agent
    • 点击后会弹出 Agent 选择面板，左侧展示所有可用 Agent 列表，右侧展示以当前选中 Agent 作为根节点的 Agent Tree
    • 你可以通过列表选择任意 Agent 作为本次对话的入口智能体，后续所有对话都会从该 Agent 开始编排调用
    • 选择结果会保存在浏览器本地（localStorage），刷新页面后仍会保持
  • Agent 系统：
    • 当前版本默认使用 Researcher 系统（config/agent_library/Researcher）
    • Agent 体系结构请参考主仓库 README 中的配置说明

3. 输入任务

在底部的输入框中输入任务描述，例如：

帮我找一篇关于 ECM 的论文

然后点击 "发送" 按钮或按 Enter 键（Shift+Enter 换行）。

4. 查看输出

Agent 的执行输出会实时显示在对话窗口中：

  • 每条消息显示 Agent 头像和名称
  • 不同类型的消息有不同的颜色：
    • 🔧 工具调用（tool_call）：青色
    • 🤖 子 Agent 调用（agent_call）：蓝色
    • ✅ 成功消息：青色
    • ❌ 错误消息：红色
    • ⚠️ 警告消息：黄色
    • 📊 结果消息：橙色
    • 💭 思考消息：紫色

5. Human-in-Loop (HIL) 交互

当 Agent 需要人工输入时：

  • 输入框会自动显示红色闪烁效果
  • 输入框 placeholder 会显示 Agent 的指令
  • Send 按钮自动启用（即使输入框为空）
  • 在输入框中输入响应并点击 Send
  • Agent 会继续执行任务

工作流程：

  1. Agent 调用 human_in_loop 工具
  2. 前端自动检测到 HIL 任务
  3. 输入框显示红色闪烁提示
  4. 用户输入响应并发送
  5. Agent 继续执行

界面说明

顶部控制栏

  • Select Agent：入口智能体选择按钮，点击后可在弹窗中选择对话入口 Agent，并查看对应 Agent Tree
  • Task ID: 任务工作目录路径（支持任务选择下拉框）
  • Agent: 当前选中的入口 Agent（默认 alpha_agent）
  • System: 默认使用 Researcher 系统，可切换到 OpenCowork
  • 文件浏览器: 右侧可浏览和管理任务文件

对话窗口

  • 显示所有消息（用户输入和 Agent 输出）
  • 自动滚动到最新消息
  • 支持长文本和多行显示

输入区域

  • 文本输入框（支持多行）
    • 正常状态：蓝色边框
    • HIL 等待状态：红色闪烁边框
  • 发送按钮
    • 有内容时自动启用
    • HIL 模式下始终启用
  • 状态栏（显示运行状态和 Workspace 路径）

技术架构

  • 后端: Flask + Server-Sent Events (SSE)
  • 前端: 原生 HTML + CSS + JavaScript
  • 事件流: 直接解析 JSONL 事件流（--jsonl 模式）
  • 流式传输: 使用 SSE 实现实时输出
  • HIL 支持: 事件触发 + 智能轮询检测机制
  • 数据存储: 对话历史存储在 task_id/conversations/ 目录

文件结构

web_ui/
├── server/                    # 服务器相关文件
│   ├── server.py              # Flask 后端服务器
│   ├── start.sh               # 启动脚本（支持 workspace 配置）
│   ├── stop.sh                # 停止脚本
│   └── users.yaml             # 用户认证配置
├── index.html                 # 前端页面
├── login.html                 # 登录页面
├── static/                    # 静态资源
│   ├── style.css             # 样式文件
│   └── app.js                # JavaScript 逻辑（包含 HIL 检测）
├── requirements.txt           # Python 依赖
└── README.md                 # 使用说明

数据存储

存储位置

系统使用两个存储位置来管理不同类别的数据：

1. Workspace 目录 ({task_id}/)

任务工作目录，存储任务相关的工作文件：

{task_id}/
├── temp/                      # 临时文件目录
├── code_run/                  # 代码执行目录
├── code_env/                  # 代码环境目录
├── reference.bib              # 参考文件
├── chat_history.json          # Web UI 聊天记录（前端显示）
└── latest_output.json         # 最新输出（用于快速预览）

注意：删除 task_id 目录会删除所有任务相关的工作文件和 Web UI 聊天记录。

2. 主目录 (~/mla_v3/conversations/)

Agent 对话历史和状态存储位置：

~/mla_v3/conversations/
├── {task_hash}_{task_folder}_stack.json           # Agent 调用栈
├── {task_hash}_{task_folder}_share_context.json   # 共享上下文
└── {task_hash}_{task_folder}_{agent_id}_actions.json  # Agent 动作历史

其中：

  • task_hash: task_id 的 MD5 前 8 位
  • task_folder: 如果 task_id 是路径，取最后一级文件夹名；否则使用 task_id 本身
  • agent_id: Agent 的唯一标识符

注意：删除此目录会删除所有任务的 Agent 对话历史。如果要清理特定任务的历史，可以根据文件名前缀（{task_hash}_{task_folder}）来识别和删除。

故障排除

1. 无法连接到服务器

  • 检查服务器是否正在运行
  • 检查端口 5000 是否被占用
  • 查看服务器终端的错误信息

2. Agent 执行失败

  • 检查 Task ID 路径是否正确
  • 检查工具服务器是否正常运行
  • 查看浏览器控制台的错误信息

3. 输出不显示

  • 检查浏览器控制台是否有 JavaScript 错误
  • 检查 SSE 连接是否正常（Network 标签页）
  • 查看服务器日志

4. HIL 任务无响应

  • 确认工具服务器正在运行（检查端口 8001/8002）
  • 检查浏览器控制台是否有错误信息
  • 刷新页面重试

5. 工作空间路径问题

  • 确保路径是绝对路径
  • 检查路径是否有写权限
  • 重新运行 start.sh 配置正确的 workspace

开发说明

修改端口

在 server.py 中修改：

port = int(os.environ.get('PORT', 5000))

或通过环境变量：

PORT=8080 python server.py

添加新的 Agent 头像

在 app.js 中的 agentAvatars 对象中添加：

const agentAvatars = {
    'your_agent': '🎯',
    // ...
};

自定义样式

修改 static/style.css 文件来自定义界面样式。

许可证

与主项目相同。