Agent 运行 · LightAIP · frontend-intro-v5

1. 页面概览

「Agent 运行」是 AIP 的 Agent 任务执行与回放页面（action/web/src/views/AgentRunPage.vue，普通登录用户可访问）。用户输入一个自然语言「目标」（goal），选择执行模式（当前仅 plan_execute：规划 + 执行），前端 POST /agents/tasks 同步执行——执行期间按钮旋转等待，并按 1.5s 轮询已落库的步骤，实时展示步骤时间线（后端无步骤流式端点，属客户端轮询）；后端一次返回完整结果后再展示最终结果与完整步骤时间线（工具名 + 状态徽标 + 描述 + 结果摘要）；同时提供服务端分页的历史任务列表与详情弹窗，可回放任意历史任务的执行步骤。一句话总结：本页是 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]                    │ │
│ │ [运行] [清空结果]                      │ │
│ │ ── 运行结果 ──                          │ │
│ │ 运行中：轮询步骤时间线（1.5s 刷新）      │ │
│ │ 运行结果：已完成  task_id: xxx          │ │
│ │ #1 工具名 [状态] 描述/结果摘要           │ │
│ │ 最终结果 <pre>                        │ │
│ └──────────────────────────────────────┘ │
│ ┌ 历史任务 ────────────────────────────┐ │
│ │ 目标 | 模式 | 状态 | 结果摘要 | 创建时间  │ │
│ │ (行点击打开详情)                       │ │
│ │ 共 N 条 · 第 x/y 页 每页[10|20|50] 上下页│ │
│ └──────────────────────────────────────┘ │
└───────────────────────────────────────────┘
   └─ 任务详情弹窗：模式/状态/task_id + 目标 + 步骤时间线 + 最终结果

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

4. 交互元素

控件	位置	含义与作用
下拉「模式」	新建任务	当前仅 `plan_execute（规划 + 执行）` 一个选项
文本域「目标 *」	新建任务	必填自然语言目标，如「统计2024年各产品销量并按季度汇总」
按钮「运行」	新建任务	同步执行；执行中显示 spinner + 文案「执行中（同步执行，请稍候）...」并禁用
运行中实时步骤时间线	新建任务·运行结果区	执行期间按 1.5s 轮询刷新已落库的步骤（工具名 + 状态徽标 + 描述/结果摘要），并常驻说明「后端为同步执行且未提供步骤流式端点，此处为轮询而非服务端推送」（2026-09-13 补）
按钮「清空结果」	新建任务	清空当前运行结果（`currentDetail`），仅影响本表单下方展示
按钮「刷新」	页头	重新拉取历史任务列表（回到当前页）
分页控件（每页 10/20/50 + 上一页/下一页）	历史任务·表尾	服务端分页：请求带 `page`/`page_size`，表尾显示「共 N 条 · 第 x / y 页」，分页常量来自后端返回的 `total`/`page`/`page_size`（2026-09-13 补）
历史任务表格行	历史任务	点击打开详情弹窗（`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`	`page=1&page_size=20`（默认 20，1≤page_size≤100，越界回落 20）	加载历史、刷新、分页、运行中任务发现	`{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）；后端未就绪时列表提示「暂无任务记录（后端可能未就绪）」，页面不白屏。

仅三个路由，无步骤/事件流端点：agent.Handler.RegisterRoutes 只注册 POST /agents/tasks、GET /agents/tasks、GET /agents/tasks/:id（action/products/aip/agent/handler.go:48-54），没有 SSE / 步骤事件 / 日志端点。
服务端分页（已支持）：ListTasks 解析 page/page_size（handler.go:117-125），service.ListTasks 以 created_at DESC + Offset/Limit 分页并返回 total（agent/service.go:225-247），且非 admin 仅返回本人任务（:230-233）。前端据此改为真分页，替换此前无效的 limit=50（后端不读 limit，旧实现实际只拿到默认 20 条）。
运行中步骤轮询（无推送，靠增量落库）：RunSync 会先把任务行写入库（status=running，agent/service.go:48-59），再逐条 Create 步骤日志（agent/service.go:78-93，每条先 running 后回填 succeeded/failed），因此同步请求进行中 GET /agents/tasks/:id 已能读到部分步骤。因 task_id 只在同步响应返回时才可知，前端在发起 POST 后并发轮询 GET /agents/tasks?page=1&page_size=5（本人任务、created_at DESC）发现本次新建的 running 任务（按 goal 与创建时间匹配），拿到 id 后每 1.5s 拉详情刷新步骤时间线；POST 返回或组件卸载时停止轮询（onUnmounted 兜底清理）。这是客户端轮询而非服务端推送，仅在当前实现的落库行为下有效。

6. 权限与安全

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

7. 常见问题与排错

点「运行」后一直转圈：原因是同步执行耗时长（多步 LLM），timeout 为 120s，超过或后端无响应则失败。处理：等待执行完成（期间可在运行结果区看到 1.5s 轮询出的实时步骤）；失败后看 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。
长任务步骤为客户端轮询，非服务端流式（已于 2026-09-13 补）：后端无步骤/事件流端点（agent/handler.go:48-54 仅三个 REST 路由），实现方式是前端在同步 POST 期间轮询「已落库的增量步骤」：RunSync 先落任务行、再逐条写 agent_step_logs（agent/service.go:48-59、:78-93），故步骤可边执行边出现。由于 task_id 只在同步响应返回时可知，前端需先用列表（page_size=5、本人任务、created_at DESC）按 goal + 创建时间发现本次新建的 running 任务再轮询详情；若同名目标存在并发任务或列表/详情轮询失败，会退化为「无实时步骤」（静默、不影响主请求），执行完成后仍会一次性展示完整时间线。
列表分页（已于 2026-09-13 补，服务端真分页）：后端 GET /agents/tasks 支持 page/page_size 并返回 total/page/page_size（agent/handler.go:117-135、agent/service.go:225-247），前端已改服务端分页（每页 10/20/50 + 上/下一页）。此前前端发送的 limit=50 后端不读取，实际每页仅默认 20 条。
「清空结果」只清当前运行结果，不影响历史任务列表。