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

package/skills/rabetbase/references/rabetbase-dataset-relation-audit.md

@@ -0,0 +1,63 @@
+# dataset relation-audit
+
+只读审计数据集关系事实是否结构完整，并列出明确错误、结构风险和需要人工复核的关系。它消费 `dataset relations` 同一套关系事实，不修改数据集关系，也不审计页面字段选项绑定。
+
+## 命令
+
+```bash
+rabetbase dataset relation-audit --format compress
+rabetbase dataset relation-audit --datasetcode <datasetCode> --format compress
+rabetbase dataset relation-audit --from-source DB_TABLE --to-source METADATA --format compress
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `--datasetcode <code>` | string | 否 | 只审计指定来源数据集的关系 |
+| `--from-source <type>` | string | 否 | 来源数据集类型：`DB_TABLE` / `METADATA` |
+| `--to-source <type>` | string | 否 | 目标数据集类型：`DB_TABLE` / `METADATA` |
+| `--appcode <code>` | string | 否 | 覆盖当前配置中的 AppCode |
+
+## 输出
+
+输出包含 `summary` 与按风险排序的 `items`。`status` 取值为 `ok`、`warning`、`error`、`manual_review`；`manual_review` 表示 CLI 不能仅凭元数据证明业务语义正确，需要人工确认。
+
+```json
+{
+  "appCode": "app-xxx",
+  "total": 1,
+  "summary": {
+    "ok": 0,
+    "warning": 0,
+    "error": 0,
+    "manualReview": 1
+  },
+  "items": [{
+    "status": "manual_review",
+    "severity": "medium",
+    "manualReviewRequired": true,
+    "from": { "source": "DB_TABLE", "datasetCode": "order", "field": "customer_id" },
+    "to": { "source": "DB_TABLE", "datasetCode": "customer", "field": "id" },
+    "relation": { "cardinality": "MANY_TO_ONE" },
+    "reasons": [{
+      "code": "missing_label_field",
+      "message": "目标关系缺少展示字段，需要人工确认业务展示口径"
+    }]
+  }]
+}
+```
+
+## Agent 使用规则
+
+- DB 增量变更排查顺序：先 `db diff` 看物理表与数据集差异，再 `dataset relation-audit` 看关系事实风险。
+- 页面展示异常排查顺序：先 `dataset relations` 确认关系事实，再 `dataset relation-audit` 判断关系事实是否需要修复，最后用 `page relation-audit` 审计页面绑定。
+- `error` 表示结构上能确定的问题，例如目标数据集不存在、字段不存在或方向不支持。
+- `manual_review` 不是失败结论，表示缺展示字段、关系基数不明或物理约束证据不足，需要人工确认业务口径。
+- 本命令只读；修复关系必须先走 `dataset relation-create/update/delete --dry-run`，并等用户确认。
+
+## 参考
+
+- [dataset relations](rabetbase-dataset-relations.md)
+- [dataset relation mutations](rabetbase-dataset-relation-mutations.md)
+- [page relation binding](rabetbase-page-relation-binding.md)

package/skills/rabetbase/references/rabetbase-dataset-relation-mutations.md

@@ -0,0 +1,141 @@
+# dataset relation-create / relation-update / relation-delete
+
+管理应用的单条数据集关联关系。这里的“关联关系”不是传统外键：它可以是 V2 数据集之间的字段映射、自关联父子关系，也可以是 `DB_TABLE` 字段消费 `METADATA` 字典数据集；目标展示字段 `refTableLabelName` / `to-label-column` 是关系的一等属性。
+
+读取数据集关联关系事实使用 `rabetbase dataset relations`。新增、更新、删除单条关联关系分别使用 `rabetbase dataset relation-create` / `relation-update` / `relation-delete`。
+
+create 使用来源和目标 datasetCode 描述关系两端。relation-update 只要求 `appCode + relationId` 定位待更新关系，其余关系参数都是可选覆盖项；CLI 先读取完整关系，再合并显式参数并提交完整对象。CLI 会读取合并后的数据集类型并做方向校验。支持 `DB_TABLE -> DB_TABLE`、`DB_TABLE -> METADATA`、`METADATA -> METADATA`；暂不支持 `METADATA -> DB_TABLE`。
+
+## Agent 安全边界
+
+- 面向用户答疑时，只给出“先只读确认、再生成 dry-run 方案、用户确认后执行”的路径，不直接让用户执行正式写入。
+- 关系缺失时使用 `relation-create --dry-run` 预览；展示字段或支持的关系属性不符合预期时使用 `relation-update --dry-run` 预览。
+- 正式写入后 CLI 会自动回读关系事实验证结果；如果后端调用返回但关系未创建、未更新或未删除，命令会失败，不要把这种失败当作已落库。
+- `relation-update` 可覆盖关系两端字段，但执行前必须通过 `--dry-run` 核对合并后的完整关系对象，避免把关系移动到错误的数据集或字段。
+- 不要把关系写入、页面审计和 `page sync` 混成“一键修复”。关系事实修正后，再重新执行 `page relation-audit`，页面仍需同步时再走 `page sync --dry-run`。
+
+## 命令
+
+```bash
+rabetbase dataset relation-create --from-datasetcode <fromDatasetCode> --from-column <fromField> --to-datasetcode <toDatasetCode> --to-column <toField> --to-label-column <toLabelField> --cardinality MANY_TO_ONE --dry-run --format json
+rabetbase dataset relation-update --appcode <appCode> --relation-id <relationId> --to-label-column <nextLabelField> --dry-run --format json
+rabetbase dataset relation-update --appcode <appCode> --relation-id <relationId> --expect-to-label-column <currentLabelField> --to-label-column <nextLabelField> --dry-run --format json
+rabetbase dataset relation-delete --appcode <appCode> --relation-id <relationId> --dry-run --format json
+```
+
+## 参数
+
+| Flag | create | update | delete | 说明 |
+|------|--------|--------|--------|------|
+| `--appcode <appCode>` | 可选 | 必填 | 必填 | 目标应用 code；update/delete 必须显式传入 |
+| `--from-datasetcode <code>` | 必填 | 可选覆盖 | 不支持 | 来源数据集 code；update 省略时沿用当前值 |
+| `--from-column <column>` | 必填 | 可选覆盖 | 不支持 | 源字段名；update 省略时沿用当前值 |
+| `--to-datasetcode <code>` | 必填 | 可选覆盖 | 不支持 | 目标数据集 code；update 省略时沿用当前值 |
+| `--to-column <column>` | 必填 | 可选覆盖 | 不支持 | 目标字段名；update 省略时沿用当前值 |
+| `--to-label-column <column>` | 必填 | 可选覆盖 | 不支持 | 目标展示字段名；update 省略时沿用当前值 |
+| `--cardinality <value>` | 必填 | 可选覆盖 | 不支持 | create 的所有支持方向均必填；create/update 均使用显式合法值，update 省略时沿用已有值，缺失时默认 `ONE_TO_MANY` |
+| `--biz-relation-type <type>` | 可选 | 可选覆盖 | 不支持 | 业务关系类型；update 的所有支持方向均可设置为 `normal` / `main_sub` |
+| `--relation-id <id>` | 不支持 | 必填 | 必填 | 关系记录 ID；update/delete 使用该 ID 定位关系 |
+| `--dry-run` | 可选 | 可选 | 可选 | 只预览请求，不实际写入；预览中包含应用、关系定位和待写入字段 |
+| `--yes` | - | - | 非交互执行必填 | `relation-delete` 是高风险写操作 |
+| `--format <fmt>` | 可选 | 可选 | 可选 | 输出格式 |
+
+`relation-update` 先按 `appCode + relationId` 读取完整关系，再用显式参数覆盖同名字段。最终请求始终包含 relationId、两端 datasetCode/字段、目标展示字段、关系基数和业务关系类型。所有支持方向都可显式传入 `--cardinality` 与 `--biz-relation-type`，不区分 DB_TABLE/METADATA；cardinality 使用显式合法值，省略时沿用已有值，已有值缺失时默认 `ONE_TO_MANY`。
+
+支持矩阵：
+
+| From | To | 支持 | 说明 |
+|------|----|:---:|------|
+| `DB_TABLE` | `DB_TABLE` | 是 | V2 数据集之间关系，底层可映射到表关系 |
+| `DB_TABLE` | `METADATA` | 是 | `DB_TABLE` 字段消费 `METADATA` 字典/选项源 |
+| `METADATA` | `METADATA` | 是 | V2 标准页面/配置数据集关系 |
+| `METADATA` | `DB_TABLE` | 否 | CLI 校验阶段拒绝 |
+
+| Flag | update | 说明 |
+|------|--------|------|
+| `--appcode <appCode>` | 必填 | 目标应用 code |
+| `--relation-id <id>` | 必填 | 待更新关系的记录 ID |
+| `--from-datasetcode <code>` | 可选 | 覆盖来源数据集 code |
+| `--from-column <column>` | 可选 | 覆盖来源字段 |
+| `--to-datasetcode <code>` | 可选 | 覆盖目标数据集 code |
+| `--to-column <column>` | 可选 | 覆盖目标字段 |
+| `--to-label-column <column>` | 可选 | 覆盖目标展示字段 |
+| `--expect-to-label-column <column>` | 推荐 | 可选乐观并发检查；DB_TABLE 显式传入时回读当前目标展示字段，未配置目标展示字段时按服务端兜底语义使用 `to-column` 作为默认当前值 |
+| `--cardinality` | 可选 | 所有支持方向均使用显式合法值；省略时沿用已有值，缺失时默认 `ONE_TO_MANY` |
+| `--biz-relation-type <type>` | 可选 | 所有支持方向均可设置为 `normal` / `main_sub`；省略时沿用当前值 |
+
+## 输出
+
+实际写入返回变更前后状态、写后验证结果和执行信息。`relation-update --dry-run` 返回完整请求体、`before` 和 `warnings`，并在适用时返回 `suggestedExpectFlags`；create/delete 的 dry-run 返回各自的请求预览和定位信息。update/delete 使用 `appCode + relationId` 定位，不解析字符串 key。
+
+正式写入后，CLI 会自动回读关系事实：
+
+- `relation-create`：确认关系已存在，且 `to-label-column` 与请求一致；请求包含 `cardinality` 时一并确认回读值一致；显式传入 `biz-relation-type` 时校验业务关系类型。
+- `relation-update`：确认关系仍存在，且 `to-label-column`、合并后的 `cardinality` 和业务关系类型与请求一致。
+- `relation-delete`：确认关系已不存在。
+
+如果后端写接口返回但回读不匹配，命令以 `relation_write_not_verified` 失败，不返回成功结果。
+
+关系事实字段主定位字段为 `datasetCode + field`；单条关系写入命令返回结构化执行结果。
+
+```json
+{
+  "operation": "create",
+  "appCode": "app-xxx",
+  "selector": {
+    "fromDatasetCode": "from_dataset_code",
+    "fromColumn": "from_field",
+    "toDatasetCode": "to_dataset_code",
+    "toColumn": "to_field"
+  },
+  "before": null,
+  "after": {
+    "from": { "datasetCode": "from_dataset_code", "column": "from_field" },
+    "to": { "datasetCode": "to_dataset_code", "column": "to_field", "labelColumn": "to_label_field" },
+    "cardinality": "MANY_TO_ONE"
+  },
+  "dryRun": false,
+  "backend": {
+    "method": "POST",
+    "path": "/smartapi/question/er-config/cli/erCreate"
+  },
+  "verification": {
+    "verified": true,
+    "status": "matched",
+    "afterReadback": {
+      "from": { "datasetCode": "from_dataset_code", "column": "from_field" },
+      "to": { "datasetCode": "to_dataset_code", "column": "to_field", "labelColumn": "to_label_field" },
+      "cardinality": "MANY_TO_ONE",
+      "condition": null
+    }
+  },
+  "warnings": []
+}
+```
+
+`before` / `after` / `verification.afterReadback` 表示写入前后可稳定确认的关系事实。`selector` 使用 `fromDatasetCode`、`fromColumn`、`toDatasetCode`、`toColumn` 表达关系两端。
+
+未传 `--expect-to-label-column` 且当前 label 可读取时，METADATA `relation-update` 输出 `warnings[].code = "no_drift_check_applied"` 和 `suggestedExpectFlags`。
+
+`DB_TABLE -> METADATA` 场景下，`--to-label-column` 表示消费 METADATA 数据集时使用的目标展示字段。例如来源字段保存目标 `toField`，页面或运行时展示 `toLabelField`。
+
+## 提示
+
+- 写入前如需读取现状，统一运行 `rabetbase dataset relations --format compress` 或 `--format json`；更新或删除前确认 `relationId`，并确认来源/目标 `datasetCode + field`、`to.labelField`、`relation.cardinality` 和 `relation.bizRelationType`
+- 正式写入返回成功表示 CLI 已完成写后回读验证；若返回 `relation_write_not_verified`，先重新执行 `dataset relations` 查看当前事实，不要继续批量写入。
+- create 使用 `--from-datasetcode` 和 `--to-datasetcode` 描述关系两端；update/delete 使用 `--appcode + --relation-id` 定位当前关系，update 的其他参数只负责覆盖现值
+- 共享自动化可传 `--expect-to-label-column` 做 label 漂移校验
+- 写命令只使用结构化定位字段；不要从 dataset 展示名或字符串 key 自行推断关系
+- `relation-update` 可覆盖来源/目标 datasetCode、字段、展示字段、关系基数和业务关系类型；未传字段保持当前值
+- `to-label-column` 必须来自用户明确指定、目标字段清单，或当前关系事实 `to.labelField`；不确定时不要执行更新
+- `relation-create --cardinality` 不区分 DB_TABLE/METADATA，所有支持方向均必填并按显式合法值提交；update 省略时沿用已有值，缺失时默认 `ONE_TO_MANY`
+- 暂不支持 `METADATA -> DB_TABLE`
+- 修改关系两端字段时必须先检查 `--dry-run` 中的完整合并结果，并确认新方向仍在支持矩阵内
+- 不要在自动化流程中把删除旧关系再新增新关系视为原子编辑操作
+- 如确需删除旧关系再新增新关系，先用 `dataset relations` 核对当前关系，分别对删除和新增执行 `--dry-run`，并在用户明确确认后分步执行
+- 新增、更新、删除单条关系分别使用 `relation-create` / `relation-update` / `relation-delete`
+
+## 参考
+
+- [dataset relations](rabetbase-dataset-relations.md)
+- [SKILL.md](../SKILL.md)

package/skills/rabetbase/references/rabetbase-dataset-relations.md

@@ -0,0 +1,71 @@
+# dataset relations
+
+读取应用的数据集关联关系清单，默认读取 D0/DO V2 关系事实。这里的关联关系不是数据库外键：它可以是 V2 数据集之间的字段映射、自关联父子关系，也可以是 `DB_TABLE` 字段消费 `METADATA` 字典数据集。默认输出只包含稳定领域字段，Agent 不消费服务端原始 relation。
+
+如果目标是判断关系事实是否存在缺字段、缺目标、重复关系或需要人工复核，使用 [`dataset relation-audit`](rabetbase-dataset-relation-audit.md)。
+
+## 命令
+
+```bash
+rabetbase dataset relations --format compress
+rabetbase dataset relations --datasetcode <datasetCode> --format compress
+rabetbase dataset relations --from-source DB_TABLE --to-source METADATA --format compress
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `--datasetcode <code>` | string | 否 | 只读取指定来源数据集的关系 |
+| `--from-source <type>` | string | 否 | 来源数据集类型：`DB_TABLE` / `METADATA` |
+| `--to-source <type>` | string | 否 | 目标数据集类型：`DB_TABLE` / `METADATA` |
+| `--appcode <code>` | string | 否 | 覆盖当前配置中的 AppCode |
+
+暂不支持 `METADATA -> DB_TABLE`，命令会在校验阶段拒绝该方向。
+
+## 输出
+
+返回数据集关系事实。主定位字段是 `datasetCode + field`；`from.table` 来自来源数据集详情，`DB_TABLE` 表示物理表，`METADATA` 在 `data.dataset.tableName` 有值时输出、无值时省略；`to.table` 仅在目标为 `DB_TABLE` 时输出。有效的关系记录 ID 使用顶层 `relationId`，目标展示字段使用 `to.labelField`，关系基数使用 `relation.cardinality`，业务关系类型使用 `relation.bizRelationType`；`main_sub` 表示主子表关系，`null` 表示普通关系。
+
+```json
+{
+  "appCode": "app-xxx",
+  "total": 1,
+  "relations": [{
+    "relationId": 14263,
+    "from": {
+      "source": "DB_TABLE",
+      "datasetCode": "from-dataset-code",
+      "datasetName": "来源数据集",
+      "table": "from_table",
+      "field": "from_field"
+    },
+    "to": {
+      "source": "METADATA",
+      "datasetCode": "to-dataset-code",
+      "datasetName": "目标数据集",
+      "field": "to_field",
+      "labelField": "to_label_field"
+    },
+    "relation": {
+      "cardinality": "ONE_TO_MANY",
+      "bizRelationType": "main_sub"
+    }
+  }]
+}
+```
+
+## Agent 使用规则
+
+- 页面关系审计、标准页面绑定、字典/选项源判断，直接使用 `dataset relations --format compress`；命令底层默认读取 D0/DO V2 关系事实
+- 更新或删除前确认 `relationId`；写入前确认来源/目标 `datasetCode + field`、`to.labelField`、`relation.cardinality` 和 `relation.bizRelationType`
+- `DB_TABLE -> METADATA` 表示业务表字段消费 METADATA 字典，不要把它理解为数据库外键
+- `METADATA -> METADATA` 可以是自关联父子关系；是否自关联由 `from.datasetCode === to.datasetCode` 自行判断，不在协议里增加派生字段
+- 读取输出只表达关系事实，不输出派生能力字段
+- 物理库连接、测连、表清单和结构差异属于 `rabetbase db ...` 命令职责；数据集关系读取统一使用本命令
+
+## 参考
+
+- [dataset relation audit](rabetbase-dataset-relation-audit.md)
+- [dataset relation mutations](rabetbase-dataset-relation-mutations.md)
+- [SKILL.md](../SKILL.md)

package/skills/rabetbase/references/rabetbase-dataset-rename.md

@@ -0,0 +1,107 @@
+# dataset rename
+
+安全修改 Dataset 展示名。命令只更新 Dataset 名称，不修改字段、关系、物理表映射或业务数据。
+
+## 命令
+
+```bash
+rabetbase dataset rename \
+  --code 1a90dbff5f094a9a89936fa99b10984c \
+  --name "发票明细-销项" \
+  --expect-name "发票明细" \
+  --dry-run
+```
+
+确认 dry-run 结果无误后再去掉 `--dry-run` 执行：
+
+```bash
+rabetbase dataset rename \
+  --code 1a90dbff5f094a9a89936fa99b10984c \
+  --name "发票明细-销项" \
+  --expect-name "发票明细" \
+  --format json
+```
+
+## 参数
+
+| Flag | 必填 | 说明 |
+|------|------|------|
+| `--appcode <code>` | 否 | 目标应用编码；未配置默认 app 时必填 |
+| `--code <code>` | 是 | Dataset code，32 位 hex |
+| `--name <newName>` | 是 | 新展示名 |
+| `--expect-name <oldName>` | 是 | 当前展示名保护；不匹配即中止且不写入 |
+| `--dry-run` | 否 | 只返回 before/after 与提交预览，不调用写接口 |
+| `--format <fmt>` | 否 | 输出格式，AI Agent 优先用 `compress` |
+
+## 输出
+
+`--format json` / `--format compress` 返回 CLI envelope，rename 业务结果固定在 `data` 下。Agent 校验 dry-run 或正式执行结果时，只读取 `data.after.name`、`data.request`、`data.submitted` 等内层稳定字段；不要按顶层 `changed` 判断，因为顶层属于框架 envelope。
+
+```json
+{
+  "ok": true,
+  "command": "rabetbase dataset rename",
+  "risk": "write",
+  "dryRun": true,
+  "data": {
+    "dataset": {
+      "id": 1010859,
+      "code": "1a90dbff5f094a9a89936fa99b10984c"
+    },
+    "dryRun": true,
+    "changed": true,
+    "before": { "name": "发票明细" },
+    "after": { "name": "发票明细-销项" },
+    "request": {
+      "modelId": 1010859,
+      "modelCode": "1a90dbff5f094a9a89936fa99b10984c",
+      "name": "发票明细-销项",
+      "dataset": {
+        "datasetId": 1010859,
+        "datasetCode": "1a90dbff5f094a9a89936fa99b10984c",
+        "datasetName": "发票明细-销项"
+      }
+    },
+    "submitted": false
+  }
+}
+```
+
+dry-run 输出会在同一个 `data` 对象内额外包含 `method`、`url`、`body`、`description`；这些字段只用于展示请求预览，不作为 Agent 的稳定校验入口。
+
+当新旧名称相同时返回 `data.changed=false` 且 `data.submitted=false`，不会调用写接口。
+
+## 连续重命名 SOP
+
+当需要连续修改多个 Dataset 展示名时，逐条执行 `rabetbase dataset rename`，不要自行拼 HTTP 请求。
+
+1. 先用 `rabetbase dataset list --format compress` 拉取线上最新 Dataset 事实；数据量大时用 `--jq` 缩小到 code/name/source 等必要字段。
+2. 本地生成 rename plan，至少包含 `code`、`oldName`、`newName`、`reason`，并以线上事实填充 `oldName`。
+3. 提交前做目标名唯一性和占用预检。该检查只是 best-effort：必须说明检查范围和过滤条件，不能把本地预检当作平台唯一性约束。
+4. 每条先执行 `rabetbase dataset rename --code <code> --name <newName> --expect-name <oldName> --dry-run --format compress`。
+5. dry-run 只读取 CLI envelope 内的 `data.after.name`、`data.request`、`data.submitted`、`data.changed` 等稳定字段；不要读取顶层 `changed`，不要依赖 stdout 文本片段。
+6. dry-run 通过后，使用同一组 `code/name/expect-name` 去掉 `--dry-run` 正式执行，并逐条记录结果。
+7. 全部执行后重新 `rabetbase dataset list`，按 code 回查线上名称，确认每条都与 plan 的 `newName` 一致。
+8. 执行脚本包裹 CLI 时，不要假设 `stderr` 一定是 string；要按子进程库的真实类型处理 stdout/stderr/exit code。
+
+## 操作边界
+
+- 命令先读取平台 `get-driven-data`，用返回的 Dataset id/code 构造最小重命名 payload。
+- 写入时通过 `/smartapi/dataset/update-driven-data` 提交，仅携带 `modelId`、`modelCode`、顶层 `name` 与 `dataset.datasetName`。
+- 命令不提交 `fields` / `properties`，避免用 CLI 本地快照覆盖字段元数据。
+- `--expect-name` 是强制防漂移保护，目标 Dataset 当前名称不匹配时不写入。
+
+## 验证建议
+
+执行后用以下命令确认：
+
+```bash
+rabetbase dataset detail --code <datasetCode> --format compress --jq '.data | {id, code, name}'
+rabetbase dataset list --code <datasetCode> --format compress --jq '.data.datasets[] | {id, code, name}'
+```
+
+## 参考
+
+- [dataset detail](rabetbase-dataset-detail.md)
+- [dataset list](rabetbase-dataset-list.md)
+- [SKILL.md](../SKILL.md)

package/skills/rabetbase/references/rabetbase-dataset-restore.md

@@ -0,0 +1,54 @@
+# dataset restore
+
+恢复已删除数据集。命令调用服务端恢复接口，将数据集恢复为可用状态，并由服务端恢复该数据集关联的已删除页面和菜单。
+
+## 命令
+
+```bash
+rabetbase dataset restore --id 44791 --dry-run --format json
+rabetbase dataset restore --code 058b8cb7aac0466eb1b3332fd6cd381d --dry-run --format json
+rabetbase dataset restore --dbid 10282 --expected-count 3 --dry-run --format json
+```
+
+确认 dry-run 目标列表无误后再正式执行：
+
+```bash
+rabetbase dataset restore --dbid 10282 --expected-count 3 --confirm --yes --format json
+```
+
+## 参数
+
+| Flag | 必填 | 说明 |
+|------|------|------|
+| `--appcode <code>` | 否 | 目标应用编码；未配置默认 app 时必填 |
+| `--id <id>` | 与 `--code` / `--dbid` 三选一 | 数据集 ID |
+| `--code <code>` | 与 `--id` / `--dbid` 三选一 | Dataset code |
+| `--dbid <id>` | 与 `--id` / `--code` 三选一 | 恢复该数据库连接下所有已删除数据集 |
+| `--expected-count <n>` | 否 | 命中数量保护；实际命中数不一致时中止 |
+| `--confirm` | 正式执行必填 | 确认执行恢复 |
+| `--dry-run` | 否 | 只预览目标列表，不调用恢复接口 |
+| `--yes` | 正式执行建议 | 跳过高风险写入确认；非交互环境必填 |
+| `--format <fmt>` | 否 | 输出格式，AI Agent 优先用 `compress` |
+
+## 行为
+
+- 命令只在已删除数据集中定位目标。
+- 目标列表只用于定位；`relatedPageCount` 分页查询 `getDeletedPageList(type=STANDARD)`，并按页面 `datasetIds` 聚合。
+- 不读取 `get-dataset-list` 响应中的 `relationPages`。
+- 正式执行调用 `/smartapi/dataset/restore-dataset`。
+- 服务端会恢复数据集，并恢复该数据集关联的已删除页面和菜单。
+- `--dbid` 批量恢复建议始终配合 `--expected-count`。
+- 该命令不会创建新的物理表，也不会修改业务数据。
+
+## 验证建议
+
+恢复后可重新查看数据集详情：
+
+```bash
+rabetbase dataset detail --code <datasetCode> --format compress
+```
+
+## 参考
+
+- [dataset delete](rabetbase-dataset-delete.md)
+- [dataset list](rabetbase-dataset-list.md)

package/skills/rabetbase/references/rabetbase-db-analyze.md

@@ -0,0 +1,135 @@
+# db analyze-batch-plan / analyze-start / analyze-cancel / analyze-status
+
+规划并管理 **schema 分析任务**。`analyze-batch-plan` 是生成本地批次方案的 **read** 命令；它不需要登录或 appcode，也不会创建、预留或返回服务端 `planId`。`analyze-start` 与 `analyze-cancel` 为 **write**；`analyze-status` 为 **read**（仅按服务端 plan 查询；命令能解析到 appcode 时会返回页面确认链接）。
+
+## 何时用
+
+- **analyze-batch-plan**：增量表清单较多时，先预览确定性安全批次；不创建服务端任务
+- **analyze-start**：接入新库或表结构大变后，同步到 Lovrabet（一次调用只启动一个任务）
+- **analyze-cancel**：任务卡住或误触，需要停掉当前分析
+- **analyze-status**：轮询任务状态，并读取 CLI 派生的终态、重试和耗时字段
+
+## trace / plan id 从哪来
+
+见 [database-connection-workflow.md](../guides/database-connection-workflow.md) 第二节。摘要：
+
+1. **`db list` / `db detail`** 中的 **`latestAnalysisTraceId`**
+2. **`db analyze-start`** 返回的 **`data.planId`**
+
+## 命令
+
+```bash
+# 预览本地增量表批次（不调用 API、不返回服务端 planId）
+rabetbase db analyze-batch-plan --id 10157 --tables orders,order_item --format compress
+
+# 全量或默认分析
+rabetbase db analyze-start --id 10157 --format compress
+
+# 仅分析指定表（逗号分隔）
+rabetbase db analyze-start --id 10157 --tables orders,order_item --format compress
+
+# 取消既有任务（必须使用要取消任务的原 planId）
+rabetbase db analyze-cancel --id 10157 --plan <existingPlanId> --format compress
+
+# 查状态（必须 --plan）
+rabetbase db analyze-status --id 10157 --plan <traceId> --format compress
+```
+
+## 参数
+
+| 子命令 | 主要 flags |
+|--------|------------|
+| **analyze-batch-plan** | `--id`（必填）、`--tables`（必填，增量表名列表） |
+| **analyze-start** | `--id`（必填）、`--tables`（可选，增量表名列表） |
+| **analyze-cancel** | `--id`（必填）、`--plan`（必填，必须是要取消的既有任务） |
+| **analyze-status** | `--id`（必填）、`--plan`（必填） |
+
+取消是独立分支：不得先执行 `analyze-start` 获取新 planId，再取消新任务。取消请求提交后，继续使用同一原 planId 查询状态；不要用可能变化的 `latestAnalysisTraceId` 替换已经明确的取消目标。
+
+## `analyze-batch-plan` 输出与执行规则
+
+`analyze-batch-plan` 输出的是本地 batch plan，不是服务端任务计划。它对表名执行 trim、过滤空项和按首次出现顺序去重，再按输入顺序贪心分批。每批最多 10 张表，紧凑 JSON UTF-8 字节数最多 960；单张表自身超过安全预算时返回 validation error。输出不包含 `planId`，只有后续 `analyze-start` 才会创建任务并返回真实 `planId`。规划结果还按每表 60 秒给出启发式耗时估算。
+
+| 字段 | 语义 |
+|------|------|
+| `data.dbLinkId` | 本次规划的 dblink id |
+| `data.tableCount` / `data.batchCount` | 归一化后的表数量与批次数 |
+| `data.maxTablesPerBatch` | 每批最多表数，当前为 10 |
+| `data.maxSerializedBytesPerBatch` | 规划安全预算，当前为 960 UTF-8 bytes |
+| `data.serverInputParamsLimitBytes` | 单次启动的本地硬保护上限，当前为 1024 bytes |
+| `data.planningEstimate.basis` | 估算依据，固定为 `heuristic` |
+| `data.planningEstimate.assumedSecondsPerTable` | 规划假设，当前为每表 60 秒 |
+| `data.planningEstimate.estimatedTotalSeconds` / `estimatedTotalMinutes` | 按归一化表数量计算的总耗时估算 |
+| `data.batches[].index` | 从 1 开始的稳定批次序号 |
+| `data.batches[].tableCount` | 当前批次表数量 |
+| `data.batches[].inputParamsBytes` | `{dbLinkId, tableNames}` 紧凑 JSON 的 UTF-8 字节数 |
+| `data.batches[].estimatedDurationSeconds` | 当前批次按每表 60 秒计算的耗时估算 |
+| `data.batches[].tableNames` | 当前批次需要传给 `analyze-start --tables` 的有序表名 |
+
+上述估算仅用于排期，不是服务端 SLA。排队、表复杂度、关系分析和自动重试都可能延长实际耗时；不得据此触发超时、取消、重试、自动重启或推断任务状态，任务事实和实际耗时以同一 `planId` 的 `analyze-status` 返回为准。
+
+必须按 `index` 严格串行：每批独立调用一次 `analyze-start`，并保存一个独立 `planId`。当前批次为 `PENDING / RUNNING / RETRYING / CANCELING` 时继续查询同一 planId；`SUCCESS` 才直接进入下一批；`PARTIAL_SUCCESS` 记录失败事实后继续；`FAILED / CANCELLED` 停止整个批次编排；未知状态停止自动推进。
+
+如果 `analyze-start` 没有明确返回 `data.planId`，停止自动推进且不得盲目重试，因为请求结果可能不确定。全部批次结束后重新执行完整 `db diff --all --changed-only`；只对仍在 `data.toAnalyzeTables` 的非删除表逐表串行恢复一次，最后再执行一次完整 diff。
+
+显式单批 `analyze-start --tables` 的持久化参数超过 1024 UTF-8 bytes 时，CLI 会在调用 API 前返回 validation error 并提示先运行 `db analyze-batch-plan`。960 是规划安全预算；960 至 1024 bytes 的显式单批仍允许启动。未传 `--tables` 的全量分析不受此保护影响。
+
+## `analyze-start` 输出
+
+| 字段 | 语义 |
+|------|------|
+| `data.planId` | 当前服务端任务的唯一查询标识 |
+| `data.serverEstimate.estimatedMinutes` | 服务端返回的当前任务耗时估算（分钟） |
+| `data.serverEstimate.estimatedDurationDesc` | 服务端返回的当前任务耗时描述 |
+
+`serverEstimate` 属于已经创建的当前任务；`analyze-batch-plan` 的 `planningEstimate` 属于创建任务前的本地批次规划。两者都不用于判断任务状态。
+
+## `analyze-status` 输出
+
+| 字段 | 语义 |
+|------|------|
+| `data.status` | 后端原始任务对象，保留 `status / jobContext / errorMsg` 等排障事实 |
+| `data.requestedAnalysis` | 从原始 `inputParams` 还原的提交范围：`mode` 为 `TARGETED / FULL / UNKNOWN`，并附 `tableCount / tableNames`；仅表示最初请求，不表示实际执行范围 |
+| `data.requestedAnalysisParseWarning` | `inputParams` 缺失、非法或无法表达分析范围时的警告；成功还原时为 `null` |
+| `data.parsedJobContext` | `jobContext` 为 JSON 对象时的完整解析结果；空值或非法值返回 `null` |
+| `data.jobContextParseWarning` | 非法 JSON 或非对象 JSON 的解析警告；正常或空上下文为 `null` |
+| `data.accumulatedErrorTypeCounts` | 原样读取 `parsedJobContext.accumulatedErrorTypeCounts` 的非空对象；缺失、空对象或非法类型返回 `null`，原因码大小写不做归一化 |
+| `data.accumulatedErrorTypeCountsAdvisory` | 累计计数的数据质量提示；当前只作为参考信息展示，不作为自动决策输入 |
+| `data.isTerminal` | 仅 `SUCCESS / PARTIAL_SUCCESS / FAILED / CANCELLED` 为 `true` |
+| `data.isRetrying` | 仅原始状态为 `RETRYING` 时为 `true` |
+| `data.attemptElapsedMs` | 当前或最近一次执行尝试耗时：优先使用服务端 `costTimeMs`，否则由 `startTime` 计算；无法计算时为 `null` |
+| `data.totalElapsedMs` | 从 `firstStartTime` 到 `endTime` 或当前查询时刻的 plan 墙钟耗时；缺少可靠时间戳时为 `null` |
+| `data.hasMultipleAttempts` | `firstStartTime` 与 `startTime` 都有效且不相同时为 `true`，表示服务端开启过后续执行尝试 |
+
+`PENDING / RUNNING / RETRYING / CANCELING` 与未知状态都不是终态。不要根据 `failedTables`、`retryCount` 或错误文案推测状态。`PARTIAL_SUCCESS` 只表示任务已到终态；必须复跑 `db diff --all --changed-only` 验证目标差异收敛，才能得出本轮分析完成结论。
+
+`analyze-status` 每次只查询一次。轮询时必须继续使用当前任务的同一 `planId`；查询超时、断网或临时 API 失败不等于分析失败，也不得触发新的 `analyze-start`。当前稳定任务状态中没有独立的 `TIMEOUT` 终态。
+
+CLI 不通过固定格式或正则把 `errorMsg` 转换成机器协议；`data.status.errorMsg` 原文仍完整保留。Agent 可以语义理解该原文，并将其作为低置信度辅助证据，用于解释异常、提出排障建议和问题上报，但不得覆盖 `status` 的任务生命周期事实，不得替代最终完整 `db diff` 的收敛结论，也不得仅凭文案重新提交任务。服务端契约完成“顶层异常持久化、成功态保留、同表同轮去重”的回归验收前，`accumulatedErrorTypeCounts` 只作为参考信息展示，不驱动自动分支。
+
+`RETRYING` 状态下的服务端 `costTimeMs` 可能只代表当前或最近一轮执行耗时，因此 `attemptElapsedMs` 不应解释为整个任务的累计总耗时。同一 `planId` 出现后续执行尝试，不证明尝试间执行连续性；`requestedAnalysis` 只反映原请求，当前状态契约不提供实际执行范围，CLI 不猜测二者是否一致。
+
+## 输出链接
+
+`analyze-start` 和 `analyze-status` 在配置或 `--appcode` 能提供 appcode 时，会返回：
+
+| 字段 | 用途 |
+|------|------|
+| `data.links.erPage` | 分析后引导用户打开数据集关系页面确认数据集关系 |
+| `data.links.databasePage` | 引导用户打开数据库连接页 |
+
+当 `analyze-status` 返回的原始任务状态为 `SUCCESS` 或 `PARTIAL_SUCCESS` 时，应检查 `data.links.erPage`，并把该链接返回给用户，用于确认 ER 关系与数据集同步结果。若没有 `data.links`，通常是当前命令上下文没有解析到 appcode；重新传 `--appcode` 或在已配置 app 的项目中查询即可生成 ER 页面链接。
+
+链接会按当前环境生成：
+
+```text
+daily      https://daily.lovrabet.com/web-app/app/<appCode>/data/er?dbId=<id>
+daily      https://daily.lovrabet.com/web-app/app/<appCode>/data/database
+production https://app.lovrabet.com/app/<appCode>/data/er?dbId=<id>
+production https://app.lovrabet.com/app/<appCode>/data/database
+```
+
+## 参考
+
+- [database-connection-workflow.md](../guides/database-connection-workflow.md)
+- [SKILL.md](../SKILL.md)

package/skills/rabetbase/references/rabetbase-db-create.md

@@ -0,0 +1,54 @@
+# db create
+
+在平台**新建**一条数据库连接（dblink）。写操作（`write`），成功后可用返回的 **`id`** 做测连、分析。
+
+## 何时用
+
+- 新项目要把业务库接到 Lovrabet
+- 与「工作台 → 连接数据库」等价，适合脚本/Agent 自动化
+
+## 命令
+
+```bash
+rabetbase db create \
+  --dbname myapp \
+  --dbtype MYSQL \
+  --dburl db.example.com:3306 \
+  --username app \
+  --password '***' \
+  --dbversion 8.0 \
+  --format compress
+```
+
+可选：`--dbparam` 连接串附加参数、`--dbdesc` 描述、`--autostart` 创建成功后自动发起 schema 分析（等同再执行一次 `db analyze-start`）。若分析启动失败，连接仍已创建，响应中会含 `data.analysisStartWarning`。写操作支持 **`--dry-run`** 预览请求体（密码不落盘）。
+
+成功响应会返回连接信息与 `data.links.databasePage`，用于引导用户按需打开数据库连接页查看新建连接。
+
+## 参数（节选）
+
+| Flag | 必填 | 说明 |
+|------|------|------|
+| `--dbname` | 是 | 库名/Schema 名 |
+| `--dbtype` | 是 | 如 `MYSQL`、`POSTGRESQL` |
+| `--dburl` | 是 | `host:port` |
+| `--username` / `--password` | 是 | 凭据 |
+| `--dbversion` | 否 | 默认 `8.0` |
+| `--autostart` | 否 | 创建后是否自动启动分析 |
+
+## 输出链接
+
+`data.links.databasePage` 会按当前环境生成：
+
+```text
+daily      https://daily.lovrabet.com/web-app/app/<appCode>/data/database
+production https://app.lovrabet.com/app/<appCode>/data/database
+```
+
+## 校验
+
+`--dburl` 须为可解析的 `host:port` 形式（见 CLI 报错提示）。
+
+## 参考
+
+- [database-connection-workflow.md](../guides/database-connection-workflow.md)
+- [SKILL.md](../SKILL.md)

package/skills/rabetbase/references/rabetbase-db-delete.md

@@ -0,0 +1,26 @@
+# db delete
+
+**永久删除**一条 dblink 配置。**high-risk-write**：非交互环境必须带 **`--yes`**。
+
+## 何时用
+
+- 下线环境、误建连接需清理（确认无数据集仍依赖该连接）
+
+## 命令
+
+```bash
+rabetbase db delete --id 10157 --yes --format compress
+```
+
+## 参数
+
+| Flag | 必填 | 说明 |
+|------|------|------|
+| `--id` | **是** | dblink id |
+| `--yes` | CI/脚本必填 | 跳过高危确认 |
+| `--appcode` | 否 | 覆盖 app |
+
+## 参考
+
+- [database-connection-workflow.md](../guides/database-connection-workflow.md)
+- [SKILL.md](../SKILL.md)「风险控制」