Agent 运行 · LightAIP · frontend-intro-v5

1. 页面概览

「Agent 运行」是 AIP 的 Agent 任务执行与回放页面（action/web/src/views/AgentRunPage.vue，普通登录用户可访问）。用户输入一个自然语言「目标」（goal），选择执行模式（当前仅 plan_execute：规划 + 执行），前端 POST /agents/tasks 同步执行——执行期间按钮旋转等待，后端一次返回完整结果后，页面展示每一步骤的时间线（工具名 + 状态徽标 + 描述 + 结果摘要）与最终结果；同时提供历史任务列表与详情弹窗，可回放任意历史任务的执行步骤。一句话总结：本页是 AIP Agent 的「运行台」，用于发起目标型任务并回看每一步干了什么。

2. 访问入口

2.1 路由与菜单

路由 path: /agent、name: AgentRun、meta 标题「Agent 运行」、requiresAuth；顶部导航栏菜单「Agent」（title 提示「AIP Agent 运行（自然语言目标规划并执行）」）。源码 action/web/src/views/AgentRunPage.vue。

2.2 认证与权限

需要登录（aip_token）；普通登录用户即可访问，无管理员门槛。

2.3 端口与 API 前缀

AIP 后端 18080；客户端 action/web/src/api/aipClient.js，baseURL /aip-api/v1。

3. 界面布局

单栏纵向布局，从上到下依次为页头、提示条、新建任务卡片、历史任务卡片；另有全局覆盖层的详情弹窗。

┌───────────────────────────────────────────┐
│ Agent 运行                       [刷新]     │
│ [操作提示 alert]                           │
│ ┌ 新建 Agent 任务 ───────────────────────┐ │
│ │ 模式 [plan_execute（规划 + 执行）]        │ │
│ │ 目标 * [textarea]                    │ │
│ │ [运行] [清空结果]                      │ │
│ │ ── 运行结果 ──                          │ │
│ │ 运行结果：已完成  task_id: xxx          │ │
│ │ #1 工具名 [状态] 描述/结果摘要           │ │
│ │ 最终结果 <pre>                        │ │
│ └──────────────────────────────────────┘ │
│ ┌ 历史任务 ────────────────────────────┐ │
│ │ 目标 | 模式 | 状态 | 结果摘要 | 创建时间  │ │
│ │ (行点击打开详情)                       │ │
│ └──────────────────────────────────────┘ │
└───────────────────────────────────────────┘
   └─ 任务详情弹窗：模式/状态/task_id + 目标 + 步骤时间线 + 最终结果

页头：标题「Agent 运行」+「刷新」按钮（重拉历史任务）。
新建 Agent 任务卡片：模式下拉 + 目标文本域 + 运行/清空结果按钮 + 运行结果区。
历史任务卡片：任务表格，行可点击打开详情。
任务详情弹窗：从历史行打开，展示完整步骤时间线与最终结果。

4. 交互元素

控件	位置	含义与作用
下拉「模式」	新建任务	当前仅 `plan_execute（规划 + 执行）` 一个选项
文本域「目标 *」	新建任务	必填自然语言目标，如「统计2024年各产品销量并按季度汇总」
按钮「运行」	新建任务	同步执行；执行中显示 spinner + 文案「执行中（同步执行，请稍候）...」并禁用
按钮「清空结果」	新建任务	清空当前运行结果（`currentDetail`），仅影响本表单下方展示
按钮「刷新」	页头	重新拉取历史任务列表
历史任务表格行	历史任务	点击打开详情弹窗（`openDetail`）

状态徽标映射：已完成（completed/succeeded/success/done）、失败（failed/error）、已取消（cancelled）、执行中（running/in_progress）、等待中（pending）、排队中（queued）、已跳过（skipped）。

5. 后端关联

5.1 API 客户端

action/web/src/api/aipClient.js（baseURL /aip-api/v1）；任务创建请求单独放宽 timeout: 120000（同步执行可能较久）。

5.2 端点表

方法	路径	请求体/参数	页面触发点	成功响应 data
POST	`/agents/tasks`	`{mode, goal}`	「运行」	`{task_id, mode, goal, status, result_summary, error, steps:[{order, description, tool_name, status, result_summary, error}], result, created_at, created_by}`
GET	`/agents/tasks`	`limit=50`	加载历史、刷新	`{items, total, page, page_size}`
GET	`/agents/tasks/:id`	—	详情弹窗	同 POST 响应结构

5.3 关键机制

后端 agent.Handler 挂 protected 登录组，路由前缀 /agents；CreateTask 为同步执行（RunSync），一次请求跑完整个「规划 + 执行」过程；前端 unwrap 兼容 {code:0, data:...} 与直接 {key:...} 两种外层结构，normalizeTasks 兼容 tasks/items/list/records 数组，详情取值 id ?? task_id。错误处理：请求体不合法返回 INVALID_REQUEST（400）；后端未就绪时列表提示「暂无任务记录（后端可能未就绪）」，页面不白屏。

6. 权限与安全

/agents/tasks 全部挂在 protected 分组（JWT 鉴权）。
普通用户可用（非 admin）；当前仅开放 plan_execute 模式，模式集合由前端下拉冻结。
Agent 执行过程中的工具调用由后端工具系统校验（toolActionValidator），写操作受治理。

7. 常见问题与排错

点「运行」后一直转圈：原因是同步执行耗时长（多步 LLM），timeout 为 120s，超过或后端无响应则失败。处理：等待执行完成；失败后看 alert 错误详情；确认 AIP 后端 18080 已启动。
历史任务列表为空/提示「暂无任务记录」：原因是 GET /agents/tasks 失败（后端未就绪）或确实无任务。处理：确认后端启动后点「刷新」；Network 查看返回是否含 {items:[...]}。
点击历史行详情加载失败：原因是该任务无 id/task_id，或 GET /agents/tasks/:id 报错。处理：看 alert「该任务无 ID，无法加载详情」；若后端 404 确认任务 ID 有效。
步骤时间线状态显示原始英文：原因是 status 值不在前端 STATUS_TEXT 映射内。处理：属正常兜底（返回原值），比对后端 status 取值。

8. 已知缺陷与边界

模式下拉仅一项 plan_execute，未来扩展模式需前端同步添加 option。
任务为同步执行，长任务期间无步骤流式进度（只有旋转动画），执行完才一次性展示时间线。
列表一次只拉 50 条（limit=50），无分页 UI。
「清空结果」只清当前运行结果，不影响历史任务列表。