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 逗号分隔、system_prompt textarea）、导出声明式 Agent 定义 YAML、删除；is_enabled Switch 点击即持久化（PUT /orchestrations/agents/:id）。
一句话总结：集中维护 AI 角色 Agent 的标识、角色、能力、模型与系统提示词，并支持一键导出为声明式 YAML 制品。
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. 交互元素
| 控件 | 位置 | 含义与作用 |
|---|---|---|
| 「刷新」 | 页面头 | 重拉 Agent 列表（GET /orchestrations/agents） |
| 「导出 Agent 定义(YAML)」 | 页面头 | 下载 agent_definitions.yaml（GET /orchestrations/agents/export，blob 下载） |
| 「新建 Agent」 | 页面头 | 打开新建弹窗，默认 role=general |
| 启用 Switch | 列表行 | 点击即 PUT /orchestrations/agents/:id 持久化 is_enabled，并更新「启用/停用」文案 |
| 「编辑」 | 列表行 | 打开弹窗回填字段（name 编辑态禁用） |
| 「删除」 | 列表行 | confirm 后软删（DELETE /orchestrations/agents/:id） |
| 角色下拉 | 编辑弹窗 | finance 财务 / supply_chain 供应链 / sales 销售 / general 通用 |
5. 后端关联
端点（AIP 18080，/orchestrations 前缀）：
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /orchestrations/agents | Agent 列表（protected） |
| POST | /orchestrations/agents | 注册新 Agent（admin），body {name, display_name, role, capabilities?, model_id?, system_prompt?} |
| PUT | /orchestrations/agents/:id | 更新 Agent（admin），部分字段可选，含 is_enabled |
| DELETE | /orchestrations/agents/:id | 注销 Agent（admin，软删） |
| GET | /orchestrations/agents/export | 导出声明式 YAML（admin，application/x-yaml 附件） |
关键机制
- 4 个内置角色：finance 财务、supply_chain 供应链、sales 销售、general 通用；capabilities 前端归一化（数组或逗号/空白分隔字符串均可）。
- 启停即改：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 可选，多个能力用逗号分隔。
8. 已知缺陷与边界
| 项目 | 说明 |
|---|---|
| name 不可改 | 创建后不可改（编辑态输入框禁用），修改需删除重建 |
| capabilities 无校验 | 输入按 [,，;；\s] 切分，不校验能力是否在预定义集合内 |
| priority/max_concurrency | 列表展示字段，新建/编辑弹窗暂不提供输入（由后端种子或 AI 侧维护） |
| 软删与导出 | 删除为软删，导出的 YAML 不含已删除 Agent；导出能力依赖 admin 组接口，未就绪时前端提示失败 |