feat(lzwcai-agile-db): 更新AgileDB技能至v0.4.2版本并扩展工具集

- 将技能版本从0.2.0升级至0.4.2 - 工具数量从33个扩展至57个，新增数据源管理、AI训练、库表关联配置等功能 - 新增MQTT字段关联同步模块（8个工具）和库表关联配置（3个工具） - 添加重要的契约提示和安全确认原则，包括target默认值、alter_table操作限制等 - 修正工具参数说明，如execute_sql的executableSql改为sql，参数结构优化 - 增强安全机制，明确危险操作的用户确认流程和目标资源选择规则 - 更新README.md中的工具数量统计和功能描述
2026-06-17 14:40:43 +08:00
parent 557361632c
commit ba5cd4bbe1
115 changed files with 7587 additions and 575 deletions
--- a/.kilo/skills/lzwcai-agile-db/SKILL.md
+++ b/.kilo/skills/lzwcai-agile-db/SKILL.md
@@ -1,7 +1,8 @@
 ---
 name: lzwcai-agile-db
 description: AgileDB 数据库管理平台的 MCP 技能。为 AI Agent 提供完整的数据库操作工作流指导，适合零基础用户。
-version: 0.2.0
+metadata:
+  version: 0.4.2
 ---

 # lzwcai-agile-db
@@ -9,33 +10,56 @@ version: 0.2.0
 AgileDB 数据库管理平台的 MCP 技能。为 AI Agent 提供完整的数据库操作工作流指导，适合零基础用户。


-## 完整工具清单（33 个工具）
+## 完整工具清单（57 个工具）

-本 skill 基于 `lzwcai_mcp_agile_db` MCP Server，共提供 33 个工具，分为 9 大类：
+本 skill 基于 `lzwcai_mcp_agile_db` MCP Server，共提供 57 个工具，分为 12 大类。

-### 一、数据源管理（6 个工具）
+> **⚠️ 契约提示（2026-06 真机验证）**：以下契约文档曾写错、已按真机修正，调用时务必遵守：
+> - **`target` 默认 `test`**（不是 prod）。写线上库必须显式传 `target="prod"`。
+> - **`alter_table` 的 operation 只有 3 种**：`ADD_COLUMN` / `MODIFY_COLUMN` / `DROP_COLUMN`。其余（RENAME_COLUMN/ALTER_COLUMN_TYPE/SET_NOT_NULL...）后端**不支持**。
+> - **`alter_database` 改名字段是 `newName`**（不是 newDatabaseName）。
+> - **`generate_table_by_description` 是异步**：返回 taskId，需用 `get_ai_training_detail` 轮询。
+> - **`list_tables_with_ai` 的 `datasourceId` 实为「库/配置 ID」**（list_databases 返回的 config id），不是连接 ID。
+
+### 一、数据源管理（10 个工具）

 | 工具 | 功能 | 危险等级 |
 |------|------|----------|
 | `list_datasources` | 获取数据源列表 | 安全 |
 | `get_datasource_detail` | 获取数据源详情（含数据库、表结构） | 安全 |
-| `create_datasource` | 创建外部数据源连接 | 安全 |
+| `create_datasource` | 创建外部数据源连接（可选先测连接） | 安全 |
 | `update_datasource` | 更新数据源连接信息 | 中等 |
 | `toggle_datasource_status` | 启用/停用数据源 | 中等 |
 | `delete_datasource` | 删除数据源 | **危险** |
+| `test_connection` | 测试外部数据库连接（不创建） | 安全 |
+| `get_realtime_structure` | 实时探测远端库表结构 | 安全 |
+| `create_builtin_datasource` | 创建内置 PostgreSQL 连接（建库表链路第一步） | 安全 |
+| `update_builtin_datasource` | 修改内置 PostgreSQL 连接 | 中等 |

-### 二、数据库与表管理（6 个工具）
+### 二、数据库与表管理（9 个工具）

 | 工具 | 功能 | 危险等级 |
 |------|------|----------|
 | `list_databases` | 获取数据源下的数据库列表 | 安全 |
-| `list_tables` | 获取数据源下的表列表 | 安全 |
+| `list_tables` | 获取数据源下的表列表（基础） | 安全 |
+| `list_tables_with_ai` | 获取表元数据列表（含 AI 训练描述，内置库主列表） | 安全 |
 | `get_table_detail` | 获取表结构详情（字段、类型、主键） | 安全 |
-| `create_table` | 创建新表 | **危险** |
-| `alter_table` | 修改表结构 | **危险** |
-| `generate_table_by_description` | AI 根据自然语言生成表结构 | 安全（仅生成，不创建） |
+| `create_database` | 在内置源下创建数据库（建表前置） | **危险** |
+| `create_table` | 在指定库创建新表 | **危险** |
+| `create_database_table` | 一次性建库+表（合并接口） | **危险** |
+| `alter_table` | 修改表结构（仅 ADD/MODIFY/DROP_COLUMN） | **危险** |
+| `alter_database` | 修改数据库（改名，字段 newName） | **危险** |

-### 三、表数据 CRUD（5 个工具）
+### 三、AI 训练与生成（4 个工具）
+
+| 工具 | 功能 | 危险等级 |
+|------|------|----------|
+| `generate_table_by_description` | AI 自然语言生成表结构（异步，返回 taskId） | 安全（仅生成，不创建） |
+| `get_ai_training_detail` | 查询/轮询 AI 训练任务详情 | 安全 |
+| `list_ai_trainings` | AI 补全训练任务列表 | 安全 |
+| `create_ai_training_by_selected` | 按选中表创建 AI 补全训练 | 中等 |
+
+### 四、表数据 CRUD（5 个工具，target 默认 test）

 | 工具 | 功能 | 危险等级 |
 |------|------|----------|
@@ -45,26 +69,26 @@ AgileDB 数据库管理平台的 MCP 技能。为 AI Agent 提供完整的数据
 | `delete_table_rows` | 删除数据行（按主键） | **危险** |
 | `export_table_excel` | 导出表数据为 Excel（base64） | 安全 |

-### 四、SQL 执行（1 个工具）
+### 五、SQL 执行（1 个工具）

 | 工具 | 功能 | 危险等级 |
 |------|------|----------|
-| `execute_sql` | 执行原生 SQL 查询 | 中等/危险 |
+| `execute_sql` | 执行原生 SQL 查询（入参 `sql`，target 默认 prod） | 中等/危险 |

-### 五、数据导入（2 个工具）
+### 六、数据导入（2 个工具）

 | 工具 | 功能 | 危险等级 |
 |------|------|----------|
-| `preview_import_data` | 上传 Excel 文件，AI 智能识别并预览 | 安全 |
-| `confirm_import_data` | 确认导入 AI 识别后的数据 | **危险** |
+| `preview_import_data` | 从 URL 下载 Excel 文件，AI 智能识别并预览 | 安全 |
+| `confirm_import_data` | 确认导入（需传 databaseName，自动组装结构） | **危险** |

-### 六、表订阅（1 个工具）
+### 七、表订阅（1 个工具）

 | 工具 | 功能 | 危险等级 |
 |------|------|----------|
-| `toggle_table_subscription` | 切换表的订阅状态 | 中等 |
+| `toggle_table_subscription` | 切换表的订阅状态（configId+tableName+subscribe） | 中等 |

-### 七、API 密钥管理（6 个工具）
+### 八、API 密钥管理（7 个工具）

 | 工具 | 功能 | 危险等级 |
 |------|------|----------|
@@ -74,8 +98,9 @@ AgileDB 数据库管理平台的 MCP 技能。为 AI Agent 提供完整的数据
 | `delete_api_key` | 删除 API 密钥 | **危险** |
 | `get_api_key_permissions` | 查看指定密钥的权限配置 | 安全 |
 | `grant_api_key_permissions` | 批量为 API 密钥授予权限 | **危险** |
+| `revoke_api_key_permissions` | 撤销/删除已授予的权限（按权限记录 ID） | **危险** |

-### 八、技能与工具管理（6 个工具）
+### 九、技能与工具管理（7 个工具）

 | 工具 | 功能 | 危险等级 |
 |------|------|----------|
@@ -84,7 +109,29 @@ AgileDB 数据库管理平台的 MCP 技能。为 AI Agent 提供完整的数据
 | `create_skill` | 为数据源创建技能 | 中等 |
 | `create_sql_tool` | 将 SQL 查询创建为可复用工具 | 中等 |
 | `delete_skill_tool` | 删除技能下的工具 | **危险** |
-| `update_skill_config` | 更新技能配置 | 中等 |
+| `update_skill_config` | 更新技能配置（名称/描述/模板） | 中等 |
+| `update_skill_tool` | 修改技能工具（id+description+uniqueName） | 中等 |
+
+### 十、库表关联配置（3 个工具，外置源纳管/内置删库）
+
+| 工具 | 功能 | 危险等级 |
+|------|------|----------|
+| `create_connection_config` | 建库表关联（外置源建连后选库选表的最后一步） | 中等 |
+| `update_connection_config` | 改库表关联范围 | 中等 |
+| `delete_connection_config` | 删库表关联（也是「删内置库」的实现） | **危险** |
+
+### 十一、MQTT 字段关联同步（8 个工具，内置源专属）
+
+| 工具 | 功能 | 危险等级 |
+|------|------|----------|
+| `list_mqtt_configs` | MQTT 同步配置列表 | 安全 |
+| `get_mqtt_config_detail` | 配置详情 | 安全 |
+| `list_mqtt_target_tables` | 可同步目标表列表 | 安全 |
+| `list_mqtt_target_table_columns` | 目标表字段列表 | 安全 |
+| `create_mqtt_config` | 新增同步配置 | 中等 |
+| `update_mqtt_config` | 修改同步配置 | 中等 |
+| `delete_mqtt_config` | 删除同步配置 | **危险** |
+| `refresh_mqtt_config_cache` | 刷新配置缓存 | 安全 |

 ---

@@ -103,8 +150,11 @@ AgileDB 数据库管理平台的 MCP 技能。为 AI Agent 提供完整的数据

 ### 环境参数 `target`

- `prod` = 生产环境（正式数据，默认值）
- `test` = 测试环境（测试数据）
+- `prod` = 生产环境（正式数据）
+- `test` = 测试环境（调试数据）
+
+> **重要**：表数据 CRUD（query/insert/update/delete/export）的 `target` **默认 `test`**（安全优先）。要操作正式数据必须**显式传 `target="prod"`**。
+> 例外：`execute_sql` 的 target 默认 `prod`（沿用原行为）。

 ### 主键 `primaryKey`

@@ -120,6 +170,20 @@ AgileDB 数据库管理平台的 MCP 技能。为 AI Agent 提供完整的数据

 ## ⚠️ 安全确认原则（必须遵守）

+### 〇、目标资源不得擅自选择（最高优先级铁律）
+
+定位操作目标的参数（`datasourceId` / `connectionId` / `databaseName` / `tableId` / `tableName` / `apiKeyId` / `skillId` 等），**永远不得猜测、编造或"随手挑一个"**：
+
+- **多个候选** → 列出全部，让用户选；严禁默认第一个或自认为"最合理"的那个。
+- **唯一候选** → 先声明"我将使用 XXX"，给用户否决机会；创建/写入/删除类仍需用户确认后执行。
+- **没有候选 / 信息不足** → 直接问用户，不得编造。
+
+> 当你发现自己正在"替用户决定用哪个数据源/数据库/表"时，立刻停下来改成提问。
+
+**创建类操作**（`create_table` / `create_datasource` 等）执行前必须逐项确认落点，绝不"随便找个数据源就建"。例如建表须确认：数据源（`connectionId`）+ 数据库（`databaseName`）+ 表名（`tableName`），三者都要用户点头。
+
+---
+
 ### 一、执行工具前的风险评估

 当执行以下类型的操作时，**必须先询问用户确认**，不得擅作主张：
@@ -294,26 +358,36 @@ AgileDB 数据库管理平台的 MCP 技能。为 AI Agent 提供完整的数据
 **用户**: "查一下 users 表前 10 条数据"

 ```
-调用: query_table_data(tableId="5", pageNum=1, pageSize=10)
+调用: query_table_data(tableId="5", pageNum=1, pageSize=10)   // target 默认 test；查正式数据传 target="prod"
 返回: {
-  "columns": [{"name": "id", "type": "INTEGER"}, {"name": "username", "type": "VARCHAR"}, ...],
-  "data": [{"id": 1, "username": "admin", "email": "admin@test.com"}, ...],
-  "total": 156
+  "data": {
+    "tables": {
+      "tableName": "users",
+      "columns": [
+        {"columnName": "id", "columnType": "serial", "isPrimaryKey": true},
+        {"columnName": "username", "columnType": "varchar"}, ...
+      ]
+    },
+    "content": [[1, "admin", "admin@test.com"], [2, "user1", "user1@test.com"], ...],
+    "total": 156
+  }
 }
 回复: users 表共 156 条记录，当前显示第 1-10 条：
-      | id | username | email           | created_at          |
-      |----|----------|-----------------|---------------------|
-      | 1  | admin    | admin@test.com  | 2024-01-15 10:30:00 |
-      | 2  | user1    | user1@test.com  | 2024-01-16 14:20:00 |
+      | id | username | email           |
+      |----|----------|-----------------|
+      | 1  | admin    | admin@test.com  |
+      | 2  | user1    | user1@test.com  |
      ...
 ```

+> **返回结构注意**：列定义在 `data.tables.columns[]`（字段名 `columnName`、是否主键 `isPrimaryKey`），行数据在 `data.content[]` 且是**位置数组**（按列顺序，不是键值对象）。展示/取主键时要把 content 的每个位置对到 columns 的同序字段。
+
 ### 注意事项
- `target` 参数：`prod`=生产环境（默认），`test`=测试环境
+- `target` 参数：`test`=测试环境（**默认**），`prod`=生产环境（查正式数据须显式传）
 - 如果用户未指定数量，默认 `pageSize=10`
 - 如果用户说"翻页"，增加 `pageNum` 参数
 - 如果用户想看更多数据，可以增大 `pageSize`（最大根据 API 限制）
- 数据返回格式为对象数组
+- 行数据是位置数组（`data.content[]`），需对照 `data.tables.columns[]` 的列顺序解析

 ---

@@ -329,7 +403,7 @@ AgileDB 数据库管理平台的 MCP 技能。为 AI Agent 提供完整的数据
 1. 如果用户直接提供 SQL，直接使用
   如果用户提供自然语言需求，先转换为 SQL
    ↓
-2. 调用 execute_sql(datasourceId="xx", executableSql="SELECT ...")
+2. 调用 execute_sql(datasourceId="xx", sql="SELECT ...")
    ↓
 3. 展示查询结果
    ↓
@@ -345,7 +419,7 @@ AgileDB 数据库管理平台的 MCP 技能。为 AI Agent 提供完整的数据

 调用: execute_sql(
  datasourceId="58",
-  executableSql="SELECT region, COUNT(*) as order_count FROM orders GROUP BY region ORDER BY order_count DESC"
+  sql="SELECT region, COUNT(*) as order_count FROM orders GROUP BY region ORDER BY order_count DESC"
 )
 返回: {
  "columns": [{"name": "region"}, {"name": "order_count"}],
@@ -362,7 +436,8 @@ AgileDB 数据库管理平台的 MCP 技能。为 AI Agent 提供完整的数据
 ### 注意事项
 - `datasourceId` 必须提供，如果用户未指定，先询问
 - `sqlTemplate` 可选，用于模板化查询
- `parameters` 可选，用于参数化查询（防止 SQL 注入）
+- `params` 可选（对象），用于参数化查询（防止 SQL 注入）；工具内部映射为后端的 `parameters`
+- `target` 可选：`test`=测试环境（默认），`prod`=生产环境
 - **执行危险操作（DELETE/DROP/TRUNCATE）前，必须向用户确认**
 - 如果查询结果超过 100 行，建议用户使用 `query_table_data` 代替
 - 对于只读查询（SELECT），可以直接执行；对于写操作（INSERT/UPDATE/DELETE），必须二次确认
@@ -497,7 +572,7 @@ AgileDB 数据库管理平台的 MCP 技能。为 AI Agent 提供完整的数据
 - `data` 只包含要更新的字段，不需要提供全部字段
 - 插入数据时，自增主键不需要提供
 - 如果操作涉及多行，使用批量操作或循环调用
- 增删改操作默认作用于 `prod` 环境
+- 增删改操作 `target` **默认 `test`**（安全优先）；要写正式数据必须显式传 `target="prod"`

 ---

@@ -511,12 +586,20 @@ AgileDB 数据库管理平台的 MCP 技能。为 AI Agent 提供完整的数据
 用户请求: "我需要一个用户表" / "帮我设计一个订单系统的表结构"
    ↓
 1. 调用 generate_table_by_description(requirement="用户描述")
+   → 返回 taskId（异步任务，此时还没有表结构）
    ↓
-2. 展示 AI 生成的表结构（表名、字段、类型、注释）
+2. 轮询 get_ai_training_detail(taskId="xx") 直到 trainingStatus=2（已完成）
+   trainingStatus: 0 待训练 / 1 训练中 / 2 已完成 / 3 失败
+   完成后表结构在 createTableData.data.tables[] 里
    ↓
-3. 用户确认后，调用 create_table(connectionId="xx", databaseName="xx", tableName="xx", columns=[...])
+3. 展示 AI 生成的表结构（表名、字段、类型、注释）
    ↓
-4. 确认创建成功
+4. ⚠️ 确认落点：列出可用数据源，让用户选择 connectionId 和 databaseName
+   （多个数据源时必须让用户选，绝不擅自找一个；只有一个也要说明后再继续）
+    ↓
+5. 用户确认表结构 + 落点后，调用 create_table(connectionId="xx", databaseName="xx", tableName="xx", columns=[...])
+    ↓
+6. 确认创建成功
 ```

 ### 示例
@@ -527,28 +610,34 @@ AgileDB 数据库管理平台的 MCP 技能。为 AI Agent 提供完整的数据
 调用: generate_table_by_description(
  requirement="我需要一个商品表，包含商品名称、价格、库存、分类，用于电商系统"
 )
-返回: {
-  "tableName": "products",
-  "tableComment": "商品表",
-  "columns": [
-    {"columnName": "id", "columnType": "SERIAL", "isPrimaryKey": true, "isAutoIncrement": true, "columnComment": "主键ID"},
-    {"columnName": "name", "columnType": "VARCHAR", "columnLength": 200, "isNullable": false, "columnComment": "商品名称"},
-    {"columnName": "price", "columnType": "DECIMAL", "columnLength": 10, "columnComment": "价格"},
-    {"columnName": "stock", "columnType": "INTEGER", "columnComment": "库存数量"},
-    {"columnName": "category_id", "columnType": "INTEGER", "columnComment": "分类ID"},
-    {"columnName": "created_at", "columnType": "TIMESTAMP", "defaultValue": "NOW()", "columnComment": "创建时间"}
-  ]
+返回: {"data": {"taskId": "831", "status": "0", "message": "任务已提交，等待AI生成表结构"}}
+   ← 异步！返回的是 taskId，不是表结构
+
+轮询: get_ai_training_detail(taskId="831")
+返回(完成时): {
+  "data": {
+    "trainingStatus": "2",  // 2=已完成
+    "progress": 100,
+    "createTableData": {"data": {"tables": [{
+      "tableName": "products",
+      "tableComment": "商品表",
+      "columns": [
+        {"columnName": "id", "columnType": "SERIAL", "isPrimaryKey": true, "columnComment": "主键ID"},
+        {"columnName": "name", "columnType": "VARCHAR", "columnLength": 200, "isNullable": false, "columnComment": "商品名称"},
+        {"columnName": "price", "columnType": "DECIMAL", "columnLength": 10, "columnComment": "价格"},
+        {"columnName": "stock", "columnType": "INTEGER", "columnComment": "库存数量"}
+      ]
+    }]}}
+  }
 }

 回复: AI 已生成表结构设计：
      表名: products (商品表)
      字段:
-        - id (SERIAL, 主键, 自增) - 主键ID
+        - id (SERIAL, 主键) - 主键ID
        - name (VARCHAR(200), 非空) - 商品名称
        - price (DECIMAL(10)) - 价格
        - stock (INTEGER) - 库存数量
-        - category_id (INTEGER) - 分类ID
-        - created_at (TIMESTAMP, 默认NOW()) - 创建时间
      
      是否需要在此基础上修改或直接创建？

@@ -559,7 +648,7 @@ AgileDB 数据库管理平台的 MCP 技能。为 AI Agent 提供完整的数据
  databaseName="order_db",
  tableName="products",
  tableComment="商品表",
-  columns=[...]  // 使用 AI 生成的 columns
+  columns=[...]  // 使用轮询拿到的 createTableData.data.tables[0].columns
 )
 回复: 已成功创建表 products (商品表)
 ```
@@ -580,15 +669,13 @@ AgileDB 数据库管理平台的 MCP 技能。为 AI Agent 提供完整的数据
 4. 确认修改成功
 ```

-**可用的 operations 类型**：
+**可用的 operations 类型（真机验证，后端仅支持这 3 种）**：
 - `ADD_COLUMN`：添加字段
+- `MODIFY_COLUMN`：修改字段（改类型/长度/可空/默认值/注释，整列重定义）
 - `DROP_COLUMN`：删除字段
- `RENAME_COLUMN`：重命名字段
- `ALTER_COLUMN_TYPE`：修改字段类型
- `SET_NOT_NULL`：设置为非空
- `DROP_NOT_NULL`：取消非空约束
- `SET_DEFAULT`：设置默认值
- `DROP_DEFAULT`：删除默认值
+
+> ⚠️ 后端**不支持** `RENAME_COLUMN`/`ALTER_COLUMN_TYPE`/`SET_NOT_NULL`/`DROP_NOT_NULL`/`SET_DEFAULT`/`DROP_DEFAULT`（会报「不支持的操作类型」）。改字段类型/约束统一用 `MODIFY_COLUMN` 传完整列定义。
+> `operations[].column` 是列定义对象，字段同建表（columnName/columnType/columnLength/isNullable/columnComment/defaultValue 等）。

 ### 注意事项
 - `requirement` 参数应尽可能详细，包含业务场景和字段需求
@@ -608,9 +695,9 @@ AgileDB 数据库管理平台的 MCP 技能。为 AI Agent 提供完整的数据
 ```
 用户请求: "帮我导入这个 Excel 文件" / "把表格数据导入数据库"
    ↓
-1. 用户将 Excel 文件转为 base64 编码
+1. 拿到 Excel 文件的可下载 URL（http/https，<500KB，.xlsx/.xls）
    ↓
-2. 调用 preview_import_data(connectionId="xx", file_base64="...", file_name="data.xlsx", target="test")
+2. 调用 preview_import_data(connectionId="xx", file_url="https://example.com/data.xlsx", target="test")
    ↓
 3. 展示 AI 识别的表结构和数据预览
    ↓
@@ -618,9 +705,10 @@ AgileDB 数据库管理平台的 MCP 技能。为 AI Agent 提供完整的数据
   说明：导入的数据将写入数据库，请确认数据来源合法合规，不包含敏感信息、政治内容或违规内容。
   请确认是否继续？
    ↓
-5. 用户确认无误后，调用 confirm_import_data(connectionId="xx", data={...}, target="test")
+5. 用户确认无误后，调用 confirm_import_data(connectionId="xx", databaseName="目标库名", data=<预览返回的原文>, target="test")
+   （把 preview_import_data 的返回原样传给 data，工具会自动组装后端要求的结构；databaseName 是落库的目标库）
    ↓
-6. 确认导入成功
+6. 确认导入成功（返回含 insertedRows 插入行数）
 ```

 ### 注意事项
@@ -628,7 +716,10 @@ AgileDB 数据库管理平台的 MCP 技能。为 AI Agent 提供完整的数据
 - 支持格式：.xlsx / .xls
 - 导入前默认使用 `test` 环境（安全做法）
 - 如果用户要导入到正式环境，必须二次确认
- base64 编码的文件内容需要提供文件名
+- `file_url` 要求 http/https 可下载链接，且文件大小 < 500KB
+- `file_url` 对应的文件扩展名需为 `.xlsx` / `.xls`
+- **`confirm_import_data` 必须传 `databaseName`**（落库目标库）；`data` 直接传 `preview_import_data` 的返回原文即可，工具内部会自动解包并组装成 `{tableStructure(含databaseName), allData}`
+- AI 识别会把中文表头转成英文列名（如「姓名」→`name`）；若导入数据键名与生成的列名对不上会报「未找到 XX 字段」，此时需按预览返回的列名核对

 ---

@@ -707,6 +798,23 @@ AgileDB 数据库管理平台的 MCP 技能。为 AI Agent 提供完整的数据
 - `database`：数据库级别权限
 - `table`：表级别权限

+### 7.7 撤销权限
+
+```
+调用: get_api_key_permissions(apiKeyId="7")
+返回: {
+  "data": {
+    "connectionPermissions": [{"id": "101", "connectionId": "58", "permissionType": "read"}],
+    "databasePermissions": [...],
+    "tablePermissions": [...]
+  }
+}
+
+调用: revoke_api_key_permissions(permissionIds=["101"])
+```
+
+> 说明：`revoke_api_key_permissions` 按权限记录的 `id` 删除，需先从 `get_api_key_permissions` 获取。
+
 ---

 ## 场景 8：技能与工具管理
@@ -768,6 +876,20 @@ AgileDB 数据库管理平台的 MCP 技能。为 AI Agent 提供完整的数据
 )
 ```

+### 8.7 修改技能下某个工具
+
+```
+调用: update_skill_tool(
+  id="2066468871151718402",        // 工具 ID（来自 get_skill_tools 返回的 id）
+  description="改后的业务描述",      // 可选
+  uniqueName="新展示名",            // 可选（工具展示名）
+  sqlTemplate="SELECT ...",         // 可选
+  resultType="list"                 // 可选：single / list
+)
+```
+
+> 说明：后端实体真实字段为 `id`/`uniqueName`/`description`/`sqlTemplate`/`resultType`。旧参数名 `skillToolId`/`name`/`businessDescription` 仍有兼容映射，但建议直接用上面的真实字段名。`businessScenario` 后端无此字段，会被丢弃。
+
 ---

 ## 场景 9：表订阅管理
@@ -778,13 +900,117 @@ AgileDB 数据库管理平台的 MCP 技能。为 AI Agent 提供完整的数据
 调用: toggle_table_subscription(
  configId="数据库配置ID",
  tableName="orders",
-  isSubscribe=true   // true=订阅, false=取消订阅
+  subscribe=true   // true=订阅, false=取消订阅
 )
 ```

 ---

-## 最佳实践
+## 场景 10：库表关联配置（外置源纳管 / 内置删库）
+
+「库表关联配置」是数据源能用于智能问数的**最后一步**：外置数据源建好连接后，必须选定要纳管的库与表，平台才会同步结构、允许后续问数。这一类有 3 个工具：`create_connection_config` / `update_connection_config` / `delete_connection_config`。
+
+> **概念澄清**：
+> - 配置（config）≠ 连接（connection）。`create_connection_config` 落库后产生的 **config id**，正是 `list_databases` / `list_tables_with_ai` 里要传的那个「库/配置 ID」（`datasourceId` 参数实际指它，不是连接 ID）。
+> - `delete_connection_config` 既是「删库表关联」，也是**「删除内置库」的唯一实现**——删内置库就是删掉它对应的那条配置。
+
+### 10.1 外置源纳管（建连接后的收尾步骤）
+
+```
+用户请求: "把刚建的 MySQL 数据源接进来" / "让这个数据源能问数"
+    ↓
+1. 已有外置连接（create_datasource 返回的 connectionId）
+    ↓
+2. 调用 get_realtime_structure(datasourceId="连接ID") 探测真实库表
+    ↓
+3. ⚠️ 列出探测到的库和表，让用户勾选要纳管的范围
+   （多个库/表时必须让用户选，不得擅自全选或挑第一个）
+    ↓
+4. 调用 create_connection_config(connectionId="xx", databases=[{databaseName, tableNames:[...]}])
+    ↓
+5. 确认纳管成功（返回 config id，后续 list_tables_with_ai 用它）
+```
+
+**示例**:
+
+**用户**: "把 mysql_test 数据源的 order_db 库接进来，纳管 orders 和 users 两张表"
+
+```
+调用: get_realtime_structure(datasourceId="58")   // 先确认库表真实存在
+调用: create_connection_config(
+  connectionId="58",
+  syncTables=true,                                 // 默认 true，同步表结构
+  databases=[
+    {"databaseName": "order_db", "tableNames": ["orders", "users"]}
+  ]
+)
+回复: 已纳管 order_db 库的 orders、users 两张表，该数据源现在可用于智能问数。
+```
+
+### 10.2 修改纳管范围
+
+```
+用户请求: "再把 products 表也纳管进来" / "改一下纳管的表"
+    ↓
+1. 先拿到该配置的 config id（list_databases 返回里的 id）
+    ↓
+2. ⚠️ 与用户确认最终要纳管的完整库表清单（这是全量覆盖，不是增量追加）
+    ↓
+3. 调用 update_connection_config(id="配置ID", connectionId="xx", databases=[...])
+    ↓
+4. 确认更新成功
+```
+
+> ⚠️ **全量覆盖语义**：`databases` 传的是更新后的**完整**纳管范围，不是增量。漏传已有的表会导致那些表被移出纳管，务必带上全部要保留的表。
+
+**示例**:
+
+```
+调用: update_connection_config(
+  id="123",                                        // 配置 ID（编辑必传）
+  connectionId="58",
+  databases=[
+    {"databaseName": "order_db", "tableNames": ["orders", "users", "products"]}
+  ]
+)
+回复: 已更新纳管范围，order_db 现纳管 orders、users、products 三张表。
+```
+
+### 10.3 删除配置（含删除内置库）
+
+```
+⚠️ 安全提醒：此操作存在删除风险。
+说明：删除库表关联配置后，该库表将退出纳管、无法再问数；
+若目标是内置库，则该库本身会被删除，库内数据永久丢失，不可恢复。
+请确认是否继续？（回复"确认"继续，或取消操作）
+    ↓
+用户确认后，调用 delete_connection_config(ids=["配置ID1", "配置ID2"])
+```
+
+**示例**:
+
+**用户**: "删掉那个测试内置库"
+
+```
+回复: ⚠️ 确认要删除内置库「test_db」（配置 ID=456）吗？
+      库内全部数据将永久删除，不可恢复。请回复"确认删除"继续。
+
+用户: "确认删除"
+
+调用: delete_connection_config(ids=["456"])
+回复: 已删除配置 456（内置库 test_db）。
+```
+
+### 注意事项
+- `databases` 每项是 `{databaseName, tableNames:[...]}`，`tableNames` 是表名字符串数组（不是 tableId）
+- `syncTables` 默认 `true`（纳管时同步表结构），一般无需手动传
+- `update_connection_config` 必传 `id`（配置 ID），且 `databases` 为**全量**覆盖
+- `delete_connection_config` 的 `ids` 是数组，支持批量删；删内置库即删其对应配置 ID
+- 内置库删除属**危险操作**，务必先确认库名与影响后再执行
+
+---
+
+

 ### 1. 安全第一

@@ -839,8 +1065,8 @@ AgileDB 数据库管理平台的 MCP 技能。为 AI Agent 提供完整的数据
 - `1` - 已停止

 ### 环境
- `prod` - 生产环境（默认）
- `test` - 测试环境
+- `test` - 测试环境（**表数据 CRUD 的默认值**，安全优先）
+- `prod` - 生产环境（操作正式数据须显式传 `target="prod"`；仅 `execute_sql` 默认 prod）

 ### 常用字段类型
 | 类型 | 用途 | 示例 |
@@ -854,16 +1080,13 @@ AgileDB 数据库管理平台的 MCP 技能。为 AI Agent 提供完整的数据
 | `BOOLEAN` | 布尔值 | `is_active BOOLEAN` |

 ### 表结构变更操作类型（alter_table）
-| 类型 | 用途 |
-|------|------|
-| `ADD_COLUMN` | 添加字段 |
-| `DROP_COLUMN` | 删除字段 |
-| `RENAME_COLUMN` | 重命名字段 |
-| `ALTER_COLUMN_TYPE` | 修改字段类型 |
-| `SET_NOT_NULL` | 设置为非空 |
-| `DROP_NOT_NULL` | 取消非空约束 |
-| `SET_DEFAULT` | 设置默认值 |
-| `DROP_DEFAULT` | 删除默认值 |
+| 类型 | 用途 | column 对象关键字段 |
+|------|------|------|
+| `ADD_COLUMN` | 添加字段 | columnName, columnType, columnLength, isNullable, columnComment |
+| `MODIFY_COLUMN` | 修改字段（类型/长度/约束等，含改类型） | columnName, columnType, columnLength, ... |
+| `DROP_COLUMN` | 删除字段 | columnName |
+
+> 后端**只支持上述 3 种**。`RENAME_COLUMN`/`ALTER_COLUMN_TYPE`/`SET_NOT_NULL`/`DROP_NOT_NULL`/`SET_DEFAULT`/`DROP_DEFAULT` 均会报「不支持的操作类型」（已真机验证）。改字段类型用 `MODIFY_COLUMN`。

 ### 权限级别（API 密钥授权）
 | 级别 | 范围 |
@@ -879,7 +1102,7 @@ AgileDB 数据库管理平台的 MCP 技能。为 AI Agent 提供完整的数据
 如果用户说"帮我查一下数据库"，按以下步骤操作：

 1. 调用 `list_datasources()` 获取数据源列表
-2. 展示列表，让用户选择或默认第一个运行中的数据源
+2. 展示列表，让用户选择目标数据源（**多个候选时必须让用户选，不得默认第一个**；只有一个候选也要先说明"我将使用 XXX"再继续）
 3. 调用 `get_datasource_detail(datasourceId="xx")` 获取数据库和表信息
 4. 引导用户选择要操作的表
 5. 根据用户意图调用相应的工具：