@lovrabet/rabetbase-cli 2.3.16-beta.7 → 2.4.1

package/skills/rabetbase/guides/data-api-guidelines.md

@@ -0,0 +1,414 @@
+# 数据接口访问规范
+
+> **目标**：统一前后端数据接口访问方式，确保性能最优、数据准确
+>
+> **适用范围**：前端页面开发、Backend Function 编写、SQL 查询编写
+
+---
+
+## 核心原则
+
+| 原则 | 说明 |
+|------|------|
+| **先获取数据集详情** | 使用 CLI 命令获取字段信息和依赖关系 |
+| **分析主外键关系** | 理解表间关联，正确处理下拉框数据 |
+| **使用真实接口** | 不使用 mock 数据，直接调用数据集接口 |
+| **避免循环访问** | 批量查询替代循环单个查询 |
+| **性能优先** | 单次接口调用次数 < 50 次 |
+
+---
+
+## 编写前强制检查清单
+
+在编写任何数据访问代码前，**必须先完成以下检查**：
+
+- [ ] 使用 `rabetbase dataset detail --code <数据集编码> --format json` 获取数据集完整字段与操作信息
+- [ ] 核对字段名（区分大小写）、类型、是否必填、枚举选项
+- [ ] 分析数据集依赖关系（主外键约束）
+- [ ] 识别外键字段，确定下拉框数据来源
+
+**注意**：系统自动维护字段（id、create_time 等）的处理方式，详见 `backend-function.md`。
+
+**CLI 信封、`data.*` 键位、平台 `get-driven-data` 与 CLI 归一化对照**：单一权威见 [`references/rabetbase-dataset-detail.md`](../references/rabetbase-dataset-detail.md)。
+
+**不要复制示例字段名。** 本指南里的表名、字段名、枚举值只用于说明形态；真实代码必须从当前项目的 `rabetbase dataset detail` 输出中取 `data.fields[]`、`data.relations[]` 和 `data.dbtable`。
+
+---
+
+## 先判定数据访问路线
+
+在决定写 SQL、BFF 还是直接查数据前，先看 `rabetbase dataset detail --code <数据集编码> --format json` 的 `source`：
+
+| `source` | 建议路线 |
+|----------|----------|
+| `METADATA` | **不要走 SQL / aggregate**；优先 `filter` / `getOne` / `create` / `update` / `delete` 等平台返回的标准操作；BFF HOOK 可挂载，operation 以后端返回为准 |
+| `CUSTOM` / `DB` | 可继续评估 SQL、BFF 或标准数据接口 |
+
+---
+
+## 元数据取值规则
+
+字段事实以 `rabetbase dataset detail` 的归一化输出为准：
+
+| 目标 | 路径 | 规则 |
+|------|------|------|
+| 字段名 | `data.fields[].name` | 查询、写入、SQL 列名均使用它，不猜通用字段名 |
+| 聚合列名 | `aggregate[].column` | SDK aggregate 定义使用 `column`，不要写旧别名 `field` |
+| 必填字段 | `data.fields[].required` | `true` 表示创建/写入时需处理，平台自动维护字段除外 |
+| 枚举/选择值 | `data.fields[].options[].value` | 写入持久化 `value`，不要写展示用的 `label` |
+| 外键关系 | `data.relations[]` / `dataset relations` | 只有确认存在关系后才写关联查询或校验 |
+
+常用投影：
+
+```bash
+rabetbase dataset detail --code <数据集编码> --format compress \
+  --jq '.data.fields[] | {name, displayName, type, required, options}'
+```
+
+---
+
+## 可选：`lovrabet` CLI 查数（`data filter` / `data getOne`）
+
+本 skill 的**主路径**始终基于 **`rabetbase`**（`dataset detail`、`sql exec` 等），**不要求**安装其它 CLI。
+
+若开发者本机已单独安装 **Lovrabet 运行时 CLI**（npm 包 **`@lovrabet/lovrabet-cli`**，命令名 **`lovrabet`**），可在终端用 **`lovrabet data filter`**、**`lovrabet data getOne`** 按 **与 `@lovrabet/sdk` 相同的语义** 查询数据集行数据，并直接查看 JSON 结构，便于与前端 / BFF 里的 `filter`、`getOne` 对照调试。
+
+**版本要求：须 `lovrabet` CLI ≥ 2.0**（主版本 2 及以上）。低于 2.0 的旧包**没有**与本文一致的 `data filter` / `data getOne` 能力（或行为不同），请勿按本节操作；请升级：`npm install -g @lovrabet/lovrabet-cli@^2.0.0`（或 `latest`）。自检：`lovrabet --version`。
+
+**注意：**
+
+| 点 | 说明 |
+|----|------|
+| **非必备** | 团队未必全局安装 `lovrabet`；**不要**在文档或 Agent 流程里把 `lovrabet` 写成前置条件。 |
+| **≥ 2.0** | 本节所述 `data` 子命令以 **2.0+** 为准；版本不符时先升级，勿将异常当作 skill 错误。 |
+| **未安装时** | 仍用 `rabetbase dataset detail` 拿结构；要看真实数据可用 **`rabetbase sql exec`**（已有对应 `sqlCode`）、或平台控制台；勿假设用户会去装第二个 CLI。 |
+| **配置与认证** | `lovrabet` 与 `rabetbase` 的配置项、鉴权方式**可能不完全相同**，需按各自 CLI 文档分别配置；勿照搬一条 `rabetbase` 的 flag 就认为 `lovrabet` 等价。 |
+| **详细用法** | 以 `lovrabet data --help`、`lovrabet data filter --help` 为准（参数多为 `--code` + `--params` JSON）。 |
+
+示例（仅作形态参考，需本机已安装且已登录/配置）：
+
+```bash
+lovrabet data filter --code <数据集code> --params '{"where":{...},"currentPage":1,"pageSize":10}' --format json
+lovrabet data getOne --code <数据集code> --params '{"id":123}' --format json
+```
+
+---
+
+## 步骤 1: 获取数据集详情
+
+```bash
+rabetbase dataset detail --code <数据集编码> --format json
+```
+
+字段表、归一化规则、`dbtable`、jq 示例：**见 [`references/rabetbase-dataset-detail.md`](../references/rabetbase-dataset-detail.md)**。
+
+做行数据验证时，补一个现实预期：
+
+- **不要默认 `filter()` 返回完整字段**。列表接口常为展示做裁剪，某些字段可能缺失。
+- 需要确认“某条记录的完整字段”或依赖关键字段时，优先 `getOne({ id })`。
+- 遇到 `USER` 类型字段时，留意同名的 `_label` 扩展对象（如 `creator_id_label`、`assignee_id_label`），很多展示信息已在其中，无需立刻反查 SQL 或额外写 BFF。
+
+### 错误处理
+
+**CLI 命令执行失败时**：
+
+检查以下常见问题：
+1. 数据集编码是否正确
+2. 是否有权限访问该数据集
+3. CLI 是否已正确认证（`rabetbase auth`）
+
+**Backend Function 中的错误处理**：
+
+```javascript
+export default async function validateRelatedRecord(params, context) {
+  const result = await context.client.models["dataset_0123456789abcdef0123456789abcdef"].filter({
+    where: { id: { $eq: params.related_id } },
+    select: ['id', '<displayField>']
+  });
+
+  if (!result.tableData || result.tableData.length === 0) {
+    throw new Error(`关联记录 ${params.related_id} 不存在`);
+  }
+
+  // 继续业务逻辑...
+}
+```
+
+---
+
+## 步骤 2: 分析字段依赖关系
+
+### 主外键关系分析
+
+**从数据集详情中获取依赖关系**，重点关注：
+
+```
+主数据集依赖关系示例：
+1. related_id → related_table.id (外键)
+   - 创建主记录时 related_id 必须存在
+   - 下拉框数据来自关联数据集
+   - 需要显示关联记录名称，存储 related_id
+
+2. item_id → item_table.id (外键)
+   - 下拉框数据来自另一关联数据集
+   - 需要显示条目名称，存储 item_id
+
+3. status (无外键，`type` 为 SELECT)
+   - 枚举字段，直接使用 `data.fields[].options` 数组
+   - 不需要额外接口请求
+```
+
+### 下拉框数据来源推理
+
+| 字段类型 | 识别方式 | 数据来源 | 处理方式 |
+|---------|---------|---------|---------|
+| **外键字段** | `relations[]` 中有对应记录 | 关联的数据集 | 调用关联数据集的 filter 接口 |
+| **枚举字段** | `type === "SELECT"` 且 `options` 非空 | `data.fields[].options` | 写入 `option.value`，展示 `option.label` |
+| **级联选择** | 父字段决定子字段 | 父字段变化时动态加载 | 监听父字段变化，动态加载子选项 |
+
+枚举/选择字段的 `label` 只用于展示，写入 BFF、SDK 或 SQL 参数时使用对应 `value`。`value` 的类型以数据集详情为准，可能是字符串、数字或其它平台约定类型。
+
+**前端示例**：
+
+```tsx
+// 分析：status 字段 type === "SELECT"，options 已有枚举值
+// 直接从字段定义取，不需要接口请求
+const statusOptions = field.options.map(o => ({ label: o.label, value: o.value }));
+
+// 分析：related_id 是外键，关联另一个数据集
+// 需要获取关联记录列表作为下拉框数据
+const [relatedRecords, setRelatedRecords] = useState([]);
+
+useEffect(() => {
+  client.models.related.filter({
+    select: ['id', '<displayField>'],
+    where: { status: { $eq: 'active' } }
+  }).then(result => {
+    setRelatedRecords(result.tableData || []);
+  });
+}, []);
+
+// 下拉框配置
+const relatedOptions = relatedRecords.map(record => ({
+  label: record["<displayField>"],
+  value: record.id,
+}));
+```
+
+**Backend Function 示例**：
+
+```javascript
+// 分析：related_id 是外键
+// 创建记录前需要校验关联记录是否存在
+
+const related = await relatedDS.getOne({ id: params.related_id });
+if (!related) {
+  throw new Error(`关联记录 ${params.related_id} 不存在`);
+}
+```
+
+---
+
+## 步骤 3: 使用真实接口
+
+### 禁止使用 Mock 数据
+
+```tsx
+// ❌ 错误：使用 mock 数据
+const STATIC_OPTIONS = [
+  { label: '示例A', value: 1 },
+  { label: '示例B', value: 2 },
+];
+
+// ✅ 正确：使用真实接口
+const [relatedRecords, setRelatedRecords] = useState([]);
+useEffect(() => {
+  client.models.related.filter({
+    select: ['id', '<displayField>'],
+  }).then(result => {
+    setRelatedRecords(result.tableData || []);
+  });
+}, []);
+```
+
+### 标准接口调用方式
+
+**前端**：
+
+```tsx
+import { createClient } from '@lovrabet/sdk';
+
+const client = createClient({ appCode: 'your-app-code' });
+
+// 查询列表
+const result = await client.models.dataset_0123456789abcdef0123456789abcdef.filter({
+  where: { status: { $eq: 'active' } },
+  select: ['id', 'name'],
+  pageSize: 100,
+});
+
+const data = result.tableData || [];
+```
+
+**Backend Function**：
+
+```javascript
+// 使用 context.client 访问数据集
+const models = context.client.models;
+const TABLES = {
+  primary: 'dataset_0123456789abcdef0123456789abcdef', // 数据集: <displayName> | 数据表: <tableName>
+};
+
+const result = await models[TABLES.primary].filter({
+  where: { status: { $eq: 'active' } },
+  select: ['id', '<fieldName>'],
+});
+```
+
+---
+
+## 步骤 4: 性能优化（避免循环访问）
+
+### 场景识别
+
+代码中出现**循环内调用接口**时，必须优化：
+
+```tsx
+// ❌ 性能灾难：N 次接口调用
+for (const row of rows) {
+  const related = await getRelatedRecord(row.related_id);
+}
+```
+
+### 优化方案选择
+
+```
+循环访问接口（N 次调用）
+    │
+    ├─ 关联类型是 1:1 或 N:1？
+    │   │
+    │   ├─ 是 → 使用 filter 多表关联查询（推荐）
+    │   │        一次查询，自动 JOIN
+    │   │
+    │   └─ 否 → 使用批量查询（$in）
+    │        一次查询，手动映射
+```
+
+### 方案 1：多表关联查询（推荐）
+
+<span style={{fontSize: '0.9em', color: '#888'}}>v1.2.0+</span>
+
+**适用于**：1:1 或 N:1 关联（主记录→关联记录、成员→组织等）
+
+```tsx
+// ✅ 一次查询，自动 JOIN
+const result = await client.models.primary.filter({
+  select: [
+    "id", "record_no",
+    "related.name",     // 关联表字段
+    "related.level"     // 关联表字段
+  ],
+  where: {
+    status: { $eq: "pending" },
+    "related.level": { $eq: "important" }
+  },
+});
+
+// result.tableData[0].related.name ← 直接可用
+```
+
+### 方案 2：批量查询
+
+**适用于**：复杂场景或不支持多表关联时
+
+```tsx
+// ✅ 一次查询，$in 批量获取
+const relatedIds = [...new Set(rows.map(row => row.related_id))];
+const relatedRows = await client.models.related.filter({
+  where: { id: { $in: relatedIds } },
+  select: ['id', 'name']
+});
+const relatedMap = Object.fromEntries(
+  relatedRows.tableData?.map(row => [row.id, row.name]) || []
+);
+rows.forEach(row => row.relatedName = relatedMap[row.related_id]);
+```
+
+### 性能对比
+
+| 方案 | 调用次数 | 耗时 |
+|------|---------|------|
+| 循环单条（100 条） | 100 次 | ~10 秒 |
+| 多表关联 | 1 次 | ~0.1 秒 |
+| 批量查询 | 1 次 | ~0.1 秒 |
+
+---
+
+## 步骤 5: 批量操作优化
+
+### 大量数据写入场景
+
+**场景**：批量复制 100 条记录
+
+```javascript
+// ❌ 错误：循环创建（100 次接口调用）
+for (const row of rows) {
+  await model.create(row);
+}
+
+// ✅ 正确：使用自定义 SQL（1 次接口调用）
+await context.client.sql.execute({
+  sqlCode: "batch-copy-records",
+  params: { sourceId, targetId }
+});
+```
+
+**自定义 SQL 创建流程**：
+
+1. 优先使用 `rabetbase sql create` 创建 SQL（此时平台端已创建记录），再在本地同步目录中编辑并通过 `sql push` 更新
+2. 获得返回或已存在的 `sqlCode`
+3. 在代码中调用 `context.client.sql.execute({ sqlCode, params })`
+
+详见：`sql-creation-workflow.md`
+
+---
+
+## 检查清单
+
+### 前端页面开发
+
+- [ ] **已获取数据集详情**：使用 CLI 命令获取字段和依赖关系
+- [ ] **外键字段已识别**：下拉框数据来自关联数据集接口
+- [ ] **枚举字段已处理**：展示使用 `options[].label`，写入使用 `options[].value`
+- [ ] **未使用 mock 数据**：所有下拉框数据来自真实接口
+- [ ] **无循环访问**：优先使用多表关联查询，或使用批量查询
+- [ ] **字段名正确**：使用 `data.fields[].name`（列名），区分大小写，与数据集定义一致
+- [ ] **系统字段已识别**：结合 `data.dbtable` 与 `backend-function.md`，创建/更新时间等按平台约定不传
+- [ ] **关联表使用表名**：多表关联时使用 `tableName.fieldName` 格式
+
+### Backend Function 开发
+
+- [ ] **已获取数据集详情**：使用 CLI 命令获取字段和依赖关系
+- [ ] **主外键关系已分析**：理解表间关联关系
+- [ ] **必填字段已覆盖**：`data.fields[].required === true` 的业务字段已提供值
+- [ ] **枚举字段写入正确**：写入 `options[].value`，不是展示 `label`
+- [ ] **外键校验已处理**：创建/更新前校验外键有效性
+- [ ] **系统字段未设置**：主键自增、系统时间等按平台约定不手工传入，详见 `backend-function.md`
+- [ ] **无循环访问**：使用 filter + $in 批量查询
+- [ ] **批量操作已优化**：大量数据操作使用自定义 SQL
+
+### SQL 开发
+
+- [ ] **已获取数据集详情**：通过 `data.dbtable.tableName` 确认表名，通过 `data.dbtable.dbId` 确认数据库
+- [ ] **必填字段已确认**：INSERT 包含所有业务必填字段（`data.fields[].required === true` 中需由调用方传入的列）
+- [ ] **主外键关系已分析**：JOIN 条件使用 `data.dbtable.pkField` 等
+- [ ] **SQL 已验证**：使用 `rabetbase sql validate` 验证
+- [ ] **SELECT 已测试**：使用 `rabetbase sql exec` 测试
+
+---
+
+## 相关指南
+
+- **前端页面开发**：`frontend-development.md`
+- **SQL 创建工作流**：`sql-creation-workflow.md`
+- **Backend Function 规范**：`backend-function.md`

package/skills/rabetbase/guides/database-connection-workflow.md

@@ -0,0 +1,169 @@
+# 数据库连接（db）工作流
+
+前置知识：`auth` 已登录，并已通过 `.rabetbase.json` 或 `--appcode` 提供 **appcode**。详见 [SKILL.md](../SKILL.md)「前置条件」。
+
+## 解决什么问题
+
+| 场景 | 说明 |
+|------|------|
+| 接入已有 MySQL/PostgreSQL 等 | 在平台登记 **dblink**，供后续同步表结构、生成数据集 |
+| 改连接串 / 账号 | 更新已有连接，避免在界面点来点去 |
+| 验证网络与白名单 | **测连**确认研发环境能打到库 |
+| 同步结构到 Lovrabet | **分析任务**把表结构同步到平台；可看进度、取消 |
+| 看物理表与差异 | **tables / diff** 在写 SQL、对表前确认真实库状态 |
+
+**与 `dataset` 的区别**：`dataset detail` 里的 `dbId` 来自数据集绑定；**`db list` 的 `id` 是 dblink 主键**，二者数值上通常一致，但 **CLI 管连接用 `db *`，管模型用 `dataset *`**。
+
+## 前置参数从哪拿
+
+```text
+appcode     → 配置 / rabetbase app list / --appcode app-xxxx
+dblink id   → rabetbase db list 返回 connections[].id（或工作台「数据库连接」列表上的 id）
+trace/plan  → 见下一节（分析任务专用）
+```
+
+## traceId / planId（`db analyze-*` 用）
+
+三者等价说法：**分析任务 id、plan id、trace id**（平台字段名多为 `latestAnalysisTraceId`）。
+
+| 来源 | 命令 | 字段 |
+|------|------|------|
+| 列表快照 | `db list` | 每条连接 `latestAnalysisTraceId`、`latestAnalysisStatus` |
+| 单条详情 | `db detail --id <n>` | 同上 |
+| 刚启动的任务 | `db analyze-start --id <n>` | 响应 `data.planId` |
+
+**`db analyze-status`**：必须传 **`--plan <id>`**，值来自上表之一。
+
+**`db analyze-cancel`**：必须显式传入要取消的既有任务 **`--plan <id>`**。优先使用当前正在跟踪的原 `planId`；`latestAnalysisTraceId` 只是连接快照，不得覆盖已知目标。
+
+## 推荐流程（Agent）
+
+### A. 取消已有任务
+
+```text
+已知需要取消的原 <planId>：
+  db analyze-cancel --id <id> --plan <原 planId>
+    → 只取消该 planId 对应的既有任务，不调用 analyze-start
+  db analyze-status --id <id> --plan <原 planId>
+    → 继续查询同一 planId；取消请求已提交不等于已到达 CANCELLED
+```
+
+- 取消分支不得调用 `analyze-start`，不得为了获得 planId 新建全量或单表任务。
+- 只取消该 `planId` 对应的既有任务，不得用连接级最新快照替换明确目标。
+- `CANCELING` 不是终态；只有状态真实变为 `CANCELLED` 或其它既有终态后，才按后续业务意图决定是否启动新分析。
+
+### B. 只读排查（已有连接）
+
+```text
+db list --format compress
+  → 记下目标 connections[].id
+db test --id <id>
+db tables --id <id>
+db diff --id <id>        # 可选：看与上次分析的 schema 差异
+```
+
+### C. 新建连接并跑分析
+
+```text
+db create --dbname … --dbtype MYSQL --dburl host:port --username … --password … [--autostart]
+  → 记下返回的 data.connection.id；可把 data.links.databasePage 返回给用户按需查看
+db test --id <id>        # 可选
+db analyze-start --id <id>
+  → 记下 data.planId；把 data.links.erPage 返回给用户确认 ER 图
+db analyze-status --id <id> --plan <planId>   # 轮询直到终态
+  → data.isTerminal=true 后复跑 db diff，确认目标差异收敛
+  → 检查并返回 data.links.erPage，引导用户确认 ER 图与数据集同步结果
+```
+
+### D. 既有连接增量分析
+
+```text
+db detail --id <id>
+db diff --id <id> --all --changed-only
+  → 只取 data.toAnalyzeTables；用户要求跳过的表先从列表中剔除
+db analyze-batch-plan --id <id> --tables <toAnalyzeTables> --format compress
+  → 保存 data.batches；这是本地 batch plan，不是服务端任务 plan
+  → 命令不创建或预留任务，输出不包含 `planId`
+  → data.planningEstimate 与 batches[].estimatedDurationSeconds 按每表 60 秒估算，仅用于排期
+
+按 data.batches[].index 顺序处理，每批严格串行：
+  db analyze-start --id <id> --tables <当前 batch.tableNames>
+    → 只有此时才创建服务端任务；每批只调用一次并独立保存返回的 data.planId
+    → 如果没有明确返回 `data.planId`，立即停止；请求结果不确定时不得盲目重试
+  db analyze-status --id <id> --plan <当前批次 planId>
+    → 始终查询当前批次的同一 planId
+    → 对照 data.requestedAnalysis 核验最初提交范围；它不代表实际执行范围
+    → data.hasMultipleAttempts=true 只表示观察到多个执行尝试，不推断执行连续性或实际分析范围
+    → PENDING / RUNNING / RETRYING / CANCELING：继续等待，不启动下一批
+    → SUCCESS：进入下一批
+    → PARTIAL_SUCCESS：记录失败事实后进入下一批
+    → FAILED / CANCELLED：停止整个批次编排，不再启动后续批次
+    → 未知状态：停止自动推进并报告，不猜测为终态
+
+全部批次处理完毕：
+db diff --id <id> --all --changed-only
+  → 重新读取完整事实；目标差异收敛后才算本轮分析完成
+  → 仍未收敛则只对剩余非删除表进入下面的逐表恢复
+```
+
+全部批次终态后，如果新的 `data.toAnalyzeTables` 仍非空，按返回顺序逐表处理，每张表在本轮只恢复一次：
+
+```text
+对每个 <tableName>（每次只传一张表）：
+  db analyze-start --id <id> --tables <tableName>
+    → 保存本次返回的 data.planId
+  db analyze-status --id <id> --plan <本次 planId>
+    → 使用本次 planId 重复查询，直到 data.isTerminal=true
+    → 到达终态后才处理下一张表
+
+全部单表任务结束后：
+  db diff --id <id> --all --changed-only
+    → 以最终 `db diff --all --changed-only` 的 data.toAnalyzeTables 判断是否收敛
+    → 已尝试的剩余表只恢复一次，不再次循环提交
+```
+
+规划估算的 `basis` 固定为 `heuristic`。排队、表复杂度、关系分析和自动重试可能延长实际耗时，因此估算不是服务端 SLA，也不得驱动超时、取消、重试、自动重启或状态判断；任务事实与实际耗时始终以同一 `planId` 的 `db analyze-status` 返回为准。
+
+- 规划出的每个批次对应一个真实且独立的 `planId`；不存在聚合父 planId，也不得把多个 planId 合成为一个虚假标识。
+- 状态查询超时、断网或临时 API 失败时，继续使用同一 `planId` 恢复查询，不重新执行 `analyze-start`。
+- `data.attemptElapsedMs` 是当前或最近执行尝试耗时；累计墙钟时间看 `data.totalElapsedMs`。两者都只用于观察，不驱动自动超时或重启。
+- `data.requestedAnalysis` 只还原最初请求范围；`data.hasMultipleAttempts` 只表示观察到多个执行尝试。两者都不能证明实际执行范围。
+- 同一个 dblink 不并行启动多个单表任务。单表任务进入 `PARTIAL_SUCCESS`、`FAILED` 或 `CANCELLED` 后记录结果并继续下一张，避免一张异常表阻断其它表。
+- 同一张表到达终态后，本轮编排不再无限提交；最终仍未收敛时返回表名、单表任务 `planId`、原始终态及可用排障信息。
+- `data.accumulatedErrorTypeCounts` 只原样展示并注明可能不完整；字段缺失、为空或原因码大小写不一致均不得改变编排。
+- Agent 可以语义理解 `data.status.errorMsg`，用于解释、建议和问题上报，但要标明它是低置信度辅助证据；不得仅凭文案判断终态、计算失败表数或重新提交任务。
+
+- `PARTIAL_SUCCESS` 是任务终态，不等于目标差异已经收敛。
+- `data.isRetrying=true` 只对应后端 `RETRYING`；运行中的 `failedTables` 不是最终失败结论。
+- `DELETED_TABLE` 只进入 `data.deletedTables` 供人工确认，不传给 `analyze-start`，也不自动清理。
+- 未知状态的 `data.isTerminal` 为 `false`，继续查询或人工排查，不猜测结果。
+
+### E. 改连接再测
+
+```text
+db detail --id <id>
+db update --id <id> --dburl … [--username …] [--password …]   # 只传要改的字段
+db test --id <id>
+```
+
+### F. 删除连接（高危）
+
+```text
+db delete --id <id> --yes    # high-risk-write，非交互必须 --yes
+```
+
+## 与其它命令的配合
+
+- **写 SQL 前要 `dbId`**：`dataset detail --code …` 里 `db.id`；或 `db list` 的 `id` 与数据集侧 `dbId` 对应。
+- **看模型关系**：用 `dataset relations`；物理库连接和表清单仍用 `db list` / `db tables` 对照。
+- **给用户确认页面**：DB 更新或分析完成后返回 `data.links.erPage`；新建连接后返回 `data.links.databasePage`。
+- **不确定 flags**：`rabetbase schema`（无需登录）查契约。
+
+## 输出格式
+
+db 子命令默认 **`--format compress`**（省 token）。需要人工读时用 `--format json`。
+
+## 参考
+
+- 各子命令单页：`../references/rabetbase-db-*.md`
+- [SKILL.md](../SKILL.md)