Agent 管理

1. 页面概览

「Agent 管理」是 AIP 管理后台的 Agent 定义维护页（源码 action/web/src/views/AgentsPage.vue）。管理员维护多智能体编排（orchestration）使用的 Agent：列表展示 name / display_name / 角色 Tag / capabilities chips / model_id / 启用 Switch / priority / max_concurrency，支持新建/编辑（角色下拉 finance/supply_chain/sales/general、capabilities 预定义集多选并校验、priority/max_concurrency 整数输入、system_prompt textarea）、导出声明式 Agent 定义 YAML、删除；is_enabled Switch 点击即持久化（PUT /orchestrations/agents/:id）。

2. 访问入口

• 路由与菜单：/admin/agents，路由名 AdminAgents；位于 AIP 管理后台左侧边栏「Agent 管理」。
• 认证与权限：/admin 父路由 requiresAdmin，须管理员登录；写操作（创建/更新/删除/导出）后端挂 admin 组。
• 端口与 API 前缀：AIP 18080，aipClient baseURL /aip-api/v1。

3. 界面布局

┌ 页面头: Agent 管理 [刷新] [导出 Agent 定义(YAML)] [新建 Agent] ┐
│ alert 提示条（可关闭）                                        │
│ 卡片: Agent 列表（共 N 个）                                    │
│  ID|名称|显示名|角色|能力(capabilities)|模型|启用|优先级|并发|操作 │
│  启用列: Switch（点击即保存）+ 启用/停用文案                     │
│  操作列: 编辑 / 删除                                           │
│ 弹窗: 新建/编辑 Agent（名称/显示名/角色/模型/优先级/并发/       │
│       能力多选[预定义集]/系统提示词）  [取消] [创建|保存]         │
└─────────────────────────────────────────────────────────────┘

各板块职责：页面头提供刷新、YAML 导出与新建；列表展示 Agent 全量字段并支持行内启停；弹窗完成 Agent 定义的新建与编辑。

4. 交互元素

5. 后端关联

端点（AIP 18080，/orchestrations 前缀）：

关键机制

• 4 个内置角色：finance 财务、supply_chain 供应链、sales 销售、general 通用；capabilities 前端归一化（数组或逗号/空白分隔字符串均可）。
• capabilities 权威预定义集：后端 action/products/aip/orchestration/seed.go 的 roleDefaultCapabilities（四角色并集：financial_analysis / profit_margin / cost / revenue / gross_profit / net_profit / sales / discount / customer / product_line / quota / inventory / logistics / supply / procurement / warehouse / material_cost / analysis / summary / report / integration，共 21 项）。前端以此作为唯一可选集来源做多选与提交前校验。
• priority / max_concurrency 字段口径：后端 action/products/aip/orchestration/types.go 的 AgentInput / AgentUpdateInput（JSON 字段名 priority / max_concurrency，类型 *int，未传则不覆盖）。
• 启停即改：Switch 点击直接 PUT 全量字段（含 is_enabled），不做本地先行，失败回滚靠 alert 提示。
• 导出：后端把现有 Agent 渲染为声明式 YAML 文本，空库返回空列表不报错；前端以 blob 触发下载，文件名为 agent_definitions.yaml。
• 前端防御式取值：兼容 {code, data} 与直接 {...} 两层结构；列表兼容 agents/items/list/records 字段。

6. 权限与安全

• 路由级：/admin 父路由 requiresAdmin，非管理员被守卫重定向到智能查询。
• 接口级：列表读挂 protected，注册/更新/删除/导出挂 admin 组，后端强制管理员。
• 写操作防护：删除前 confirm 不可撤销提示；导出/删除/启停中按钮置灰防重复；name 编辑态禁用保证标识稳定。

7. 常见问题与排错

• 现象：列表为空并提示「暂无 Agent（后端可能未就绪）」。原因：GET /orchestrations/agents 失败或返回空（如未启动 AIP、未登录）。处理：确认 18080 服务运行并重新登录，点「刷新」。
• 现象：点 Switch 无反应或提示「更新 Agent 状态失败」。原因：非管理员 token 或后端未启动（401/500）。处理：用管理员账号登录；PUT 属于 admin 组，普通用户会被拒。
• 现象：导出下载的 YAML 为空或按钮报失败。原因：空库导出空列表，或 admin 组导出接口未就绪。处理：先确认列表有数据；导出依赖 /orchestrations/agents/export，未就绪时查看 alert 报错。
• 现象：保存报「名称（name）必填」/「显示名（display_name）必填」。原因：前端必填校验拦截。处理：两项必填；capabilities / model_id / system_prompt / priority / max_concurrency 可选。
• 现象：保存报「以下能力不在预定义集内：xxx」。原因：既有 Agent 的 capabilities 含预定义集之外的值（历史数据），提交前校验拦截。处理：点击提示旁的「移除」清除非法能力，或改选预定义集内的能力后再提交。
• 现象：保存报「priority 必须为整数 / 不能小于 0」「max_concurrency 必须为整数 / 不能小于 1」。原因：前端整数范围校验拦截。处理：priority 填 ≥0 整数、max_concurrency 填 ≥1 整数，或留空使用后端默认。

8. 已知缺陷与边界