多智能体编排

1. 页面概览

多智能体编排页是 LightAIP 的多 Agent 协同任务入口，路由为 /orchestrate。它把"一个复杂业务问题"交给后端编排引擎（TAD-07）拆解为多个子任务，由不同角色的 LLM Agent 分别分析，最后融合为一份报告。页面提供四种编排策略：串行、并行、领导者-跟随者、辩论，并就地展示子任务列表与融合结果。

页面同时提供编排历史列表（分页表格）、任务详情弹窗、融合报告弹窗与运行中任务取消能力。所有能力对接 AIP 后端 18080 端口的 /api/v1/orchestrations 路由组。一句话总结：多智能体编排页是"策略选择 + 任务发起 + 过程与结果查看"的一体化操作台。

2. 访问入口

2.1 路由与菜单

2.2 认证与权限

meta 配置 requiresAuth: true，未登录访问被前端路由守卫拦到登录页。页面所有请求通过 action/web/src/api/aipClient.js 的 axios 实例发出：请求拦截器从 localStorage 读取 aip_token，以 Authorization: Bearer <token> 附带 JWT；响应拦截器收到 401 时清除 aip_token 与 aip_username 并跳转 /login。普通登录用户即可访问。

2.3 端口与 API 前缀

AIP 后端默认端口 18080，API 前缀 /aip-api（实际请求路径均带 /v1，即 /aip-api/v1/orchestrations），开发环境下由 Vite（默认 5173）代理并重写为 /api/v1。

3. 界面布局

+--------------------------------------------------+
| 多智能体编排  [刷新]                               |
+--------------------------------------------------+
| [操作结果提示 alert（有消息时显示，可关闭）]          |
+--------------------------------------------------+
| 新建编排任务（card）                               |
|  编排策略* [串行▾]   任务描述* [textarea]           |
|  上下文（context，可选 JSON）[textarea]             |
|  ☐ 手动指定子任务（sub_tasks，可选，≤16）           |
|    [id|描述*|角色▾|优先级|依赖] [删除] [+ 添加子任务] |
|  [运行编排] [清空结果]  说明：最长约 600 秒          |
+--------------------------------------------------+
| 编排结果（有结果时）：状态徽标 + orchestration_id     |
|  子任务列表（#/描述/角色/Agent名/状态/耗时/依赖/结果） |
|  融合结果（result） code-block                     |
+--------------------------------------------------+
| 编排历史（card）                                   |
|  表格：ID|描述|策略|状态|Agent数|结果摘要|创建时间|操作 |
|  [上一页] 第 N 页 / 共 M 页 [下一页]                |
+--------------------------------------------------+

各板块职责：

• 操作结果提示：页面顶部单例 alert，成功（alert-success）/失败（alert-error）/信息统一经 showAlert 展示，右上角「关闭」清空消息。
• 新建编排任务：核心输入区，选策略、填任务描述（必填）、可选注入 context JSON，点「运行编排」同步执行。
• 编排结果：创建成功后就地渲染状态徽标、orchestration_id、策略、子任务列表与融合报告。
• 编排历史：分页表格列出历史任务（PAGE_SIZE=20），行内提供「详情」「结果」「取消」三个操作。
• 详情/结果弹窗：分别加载 GET /orchestrations/:id 与 /result，子任务可展开 result_summary。

4. 交互元素

5. 后端关联

5.1 端点表

5.2 关键机制

• 同步执行 + 600s 超时：创建请求即同步跑完整链路（LLM 任务分解 → Agent 匹配 → 按策略执行 → 结果融合），前端对该请求单独放宽超时到 600 秒（实测 LLM 分解 + 波次并发子任务 + 融合的同步长链路可达 5-6 分钟），执行期间按钮禁用并显示 spinner。
• 手动 sub_tasks 契约：CreateRequest.sub_tasks 为 []SubTaskInput，字段为 {id, description, required_role, priority, depends_on}（orchestration/types.go:56-70），后端上限 MaxSubTasksPerTask = 16（types.go:53），超限返回 400「子任务数量超过上限 16」（service.go:85-87）。用户提供 id 时后端会重映射为全局唯一 ID 并同步改写 depends_on 引用（service.go:174-197、remapSubTaskIDs 见 service.go:232-259），故前端行的 id 仅用于表达依赖关系，不必全局唯一。debate 策略后端固定生成 finance+sales 两视角子任务、直接忽略用户 sub_tasks（service.go:165-172），故该策略下前端禁用复选框。
• 子任务响应字段：TaskView.sub_tasks 为 []SubTaskView，字段 {id, description, required_role, status, agent_id, agent_name, depends_on, result_summary, error, started_at, completed_at}（types.go:115-128）；agent_name/depends_on/started_at/completed_at 均由 viewTask 从 Agent 表与实体补齐（service.go:1279-1322）。前端据此展示子任务列表的 Agent 名、耗时（completed_at - started_at）与依赖链。
• 四策略调度：sequential 按依赖拓扑逐个执行；parallel 无依赖子任务并发；leader_follow 由 Leader 制定计划、Worker 执行、Leader 汇总；debate 两视角 Agent 各抒己见后 LLM 仲裁。子任务按 required_role（finance/supply_chain/sales/general）匹配角色 Agent。
• 状态口径：任务与子任务状态统一映射为中文徽标（已完成/失败/已取消/执行中/等待中/排队中/已跳过）；前端 unwrap 兼容 {code,data} 与直接对象两种外层结构，后端未就绪时优雅提示不白屏。
• Agent 治理分离：Agent 注册/更新/注销走 admin 组 /orchestrations/agents，本页未暴露，由后台「Agent 管理」承接。

6. 权限与安全

• 认证为 JWT（aip_token），编排路由挂 protected 登录组，未带有效 Token 一律 401。
• 编排记录按登录用户执行，currentUser 由鉴权中间件注入（非匿名用户）。
• 创建/取消为普通登录用户写操作；Agent 注册等治理写操作需管理员角色。

7. 常见问题与排错

问题 1：点「运行编排」提示"编排执行失败"

现象：顶部红色 alert 报失败。

原因：多为后端未启动、Token 失效（401）、context 非合法 JSON、或 LLM 调用超时。

处理：先看 DevTools Network 确认请求落在 /aip-api/v1/orchestrations 且非 401；再确认后端 18080 进程与 LLM 配置正常；context 字段需严格 JSON 格式。

问题 2：创建成功但「编排结果」区显示"未返回子任务数据"

现象：提示"编排任务执行完成"，但无子任务列表。

原因：后端返回结构与前端 normalizeCreate 期望不一致（字段缺失），或同步返回空 sub_tasks。

处理：用「结果」弹窗查看 GET /orchestrations/:id/result 原始文本；若仍为空说明任务尚未产出融合报告，稍后刷新历史再点「结果」。

问题 3：运行中的任务没有「取消」按钮

现象：任务行操作区没有「取消」。

原因：isRunnable 仅识别 running/in_progress/queued/pending 四种未终态；已完成/失败/已取消任务不显示取消按钮。

处理：确认任务确实未进入终态；若状态异常（如 partial_complete）不支持取消，需人工处置。

8. 已知缺陷与边界