工具管理 · LightAIP · frontend-intro-v5

1. 页面概览

工具管理页（路由 /admin/tools）是 AIP 管理后台面向管理员的 Agent 工具治理台。它提供工具列表（名称/描述/内置标记/危险标记/启用开关）、工具详情（参数 JSON Schema 抽屉）、测试执行（按工具参数 Schema 生成表单并执行，展示结果与耗时）三类能力，用于管理 Agent/NLQ 链路可调用的工具注册表（tool_definitions）。启用/禁用接口需管理员权限，403 时前端明确提示「启用/禁用工具需要管理员权限」。所有请求走 aipClient（/aip-api/v1 → AIP 18080），后端未就绪时优雅提示不白屏。

一句话总结：本页是工具注册表的「查看 + 启停 + 试运行」控制台，内置工具与外部工具统一治理。

2. 访问入口

路由与菜单：path /admin/tools、name AdminTools、路由 title「工具管理」，位于 AIP 管理后台侧边栏（菜单项「工具管理」）；源码 action/web/src/views/ToolsPage.vue。
认证与权限：父路由 /admin 配置 requiresAuth: true, requiresAdmin: true；工具启停接口 PUT /tools/:name/enable 挂 admin 组，普通用户调用返回 403。
端口与 API 前缀：AIP 后端 18080，前端 baseURL /aip-api/v1（Vite 将 /aip-api 重写为 /api）。

3. 界面布局

+--------------------------------------------------------------+
| 工具管理                                      [刷新]           |
| 工具列表：名称|描述|类型(内置/外部)|危险|启用(switch)|操作(详情/   |
|   测试执行)                                                    |
| 详情抽屉（右侧滑出）：描述/内置/危险/启用 + 参数 JSON Schema       |
| 测试执行：选择工具[select] + 数据源[select]（需要时）             |
|   按工具类型参数表单（SQL/max_rows|表名|问题|通用 JSON）          |
|   [执行] [清空]  结果区：执行耗时 + 结果                        |
+--------------------------------------------------------------+

各板块职责：

工具列表：核心区，展示工具定义与启用态，行内「详情」「测试执行」入口；启用开关切换即时生效并提示。
详情抽屉：右侧滑出面板，展示描述/内置/危险/启用元信息与参数 JSON Schema（格式化 JSON）。
测试执行：选择工具后按参数 Schema 生成表单，执行并展示 {result, execution_ms}。

4. 交互元素

控件	位置	含义与作用
刷新	页面头部	并行刷新工具列表与数据源下拉，加载中禁用并显示「加载中...」
启用开关	工具列表启用列	切换调 `PUT /tools/:name/enable`（body `{enabled}`），成功后刷新该行状态；403 时提示「启用/禁用工具需要管理员权限」
详情	行操作	打开右侧抽屉，先展示本地定义再按 `GET /tools/:name` 拉取最新并合并展示参数 JSON Schema
测试执行	行操作	选中该工具进入测试表单；需数据源的工具（query_data/get_table_schema/nlq_to_sql）出现数据源下拉
执行	测试执行卡片	按工具类型组装 params 后 `POST /tools/:name/execute`，展示执行耗时与结果
清空	测试执行卡片	复位工具表单与结果

测试表单按工具类型分支：query_data→SQL 文本域 + max_rows（可选）；get_table_schema→表名输入；nlq_to_sql→问题文本域；其他工具→通用「参数 JSON」输入框（JSON 格式错误会提示「参数 JSON 格式错误，请检查」）。

5. 后端关联

5.1 端点表

方法	路径	用途
GET	/tools	工具列表（name/description/parameters/is_dangerous/builtin/enabled），登录组
GET	/tools/:name	单个工具详情（含参数 Schema），登录组
POST	/tools/:name/execute	执行工具，body `{params, data_source_id?}`，返回 `{result, execution_ms}`，登录组
PUT	/tools	工具注册（Upsert），admin 组
PUT	/tools/:name	工具更新（Update），admin 组
PUT	/tools/:name/enable	启用/禁用，body `{enabled}`，admin 组

5.2 关键机制

工具定义与参数 Schema：工具字段为 name/description/parameters（JSON Schema 对象，服务端序列化为 parameters_json 落库）/is_dangerous/builtin/enabled；详情抽屉把参数对象格式化 JSON 展示。
执行管线：Execute 走 executor 管线（参数校验/安全检查/超时/审计），成功返回 {result, execution_ms}；需数据源的工具由前端传 data_source_id。
启用同步：Enable 同步更新 DB 与注册表，返回值 {name, enabled}；切换失败（403）由前端按状态码提示管理员权限。
内置工具：注册表含内置 query_data/get_table_schema/nlq_to_sql 等，演示数据源由 bootstrap 重建 demo SQLite（orders/customers/products）。

6. 权限与安全

列表/详情/执行属 protected 登录组；启停/注册/更新属 admin 组，写操作需管理员角色。
危险工具（is_dangerous）以红色「危险」标记；工具执行经安全服务做 RLS/CLS 校验。
启用开关切换无二次确认，但 403 会被前端拦截提示。

7. 常见问题与排错

现象：列表显示「暂无工具数据（后端可能未就绪）。」。原因：后端未启动或工具表为空。处理：确认 AIP 服务存活与注册表初始化日志，点「刷新」重试。
现象：切换启用开关提示「启用/禁用工具需要管理员权限」。原因：当前账号非管理员，接口返回 403。处理：使用管理员账号登录（aip_is_admin === '1'）后操作。
现象：测试执行提示「参数 JSON 格式错误，请检查」。原因：通用工具的参数 JSON 输入非法。处理：确认 JSON 为合法对象（如 {"key":"value"}）后重试。
现象：执行报 401 跳登录页。原因：aip_token 过期。处理：重新登录。

8. 已知缺陷与边界

项	说明
工具注册/更新未暴露	后端提供 PUT /tools（Upsert）与 PUT /tools/:name（Update），前端仅做启停与执行
参数表单有限	仅 query_data/get_table_schema/nlq_to_sql 有专用表单，其余工具走通用 JSON
数据源下拉依赖登录态	数据源列表来自 `GET /datasources`，失败时下拉为空但不阻塞工具列表

注：危险工具执行无二次确认（「执行」危险工具不弹二次确认，仅靠 is_dangerous 标记提示）已于 2026-09-06 修复（is_dangerous 工具先确认再执行）。