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

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

@@ -0,0 +1,54 @@
+# dataset delete
+
+废弃数据集。命令调用服务端删除接口，将平台数据集置为已删除，并由服务端同步删除关联页面和菜单；不会删除物理数据库或物理表。
+
+## 命令
+
+```bash
+rabetbase dataset delete --id 44964 --dry-run --format json
+rabetbase dataset delete --code 86f8efc75370461f95e1e9526d8d9386 --dry-run --format json
+rabetbase dataset delete --dbid 10282 --expected-count 3 --dry-run --format json
+```
+
+确认 dry-run 目标列表无误后再正式执行：
+
+```bash
+rabetbase dataset delete --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` 读取每个 Dataset 的 `get-driven-data.relatedPageInfoList`，表示当前有效关联页面数。
+- 不读取 `get-dataset-list` 响应中的 `relationPages`。
+- 正式执行调用 `/smartapi/dataset/delete-dataset`。
+- 服务端会软删除数据集，并软删除该数据集关联页面和菜单。
+- `--dbid` 批量废弃建议始终配合 `--expected-count`。
+- 该命令不会删除物理数据库、数据库连接或物理表。
+
+## 验证建议
+
+废弃后可在平台已删除数据集视图确认。需要恢复时使用：
+
+```bash
+rabetbase dataset restore --id <datasetId> --dry-run --format json
+```
+
+## 参考
+
+- [dataset restore](rabetbase-dataset-restore.md)
+- [dataset list](rabetbase-dataset-list.md)

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

@@ -0,0 +1,106 @@
+# dataset detail
+
+获取指定 Dataset 的完整详情：字段定义（含 v1/v2 归一化）、操作端点（含解析后的 request/response schema）、关联页面、dbtable 摘要等。默认即为「完整视图」，无需额外开关。
+
+## 命令
+
+```bash
+rabetbase dataset detail --code 097b7361b76c42bcb12b923fa5a08861 --format json
+rabetbase dataset detail --alias order --format json
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--code <code>` | string | 与 alias 二选一 | — | Dataset code（32 位 hex UUID） |
+| `--alias <name>` | string | 与 code 二选一 | — | `api.ts` 中定义的别名 |
+| `--format <fmt>` | string | 否 | `pretty` | 输出格式 |
+
+## 输出（要点）
+
+- **fields**：归一化字段（`name` / `displayName` / `type` / `pk` / `required` / `deprecated` / `options` 等）
+- **operations**：每项含 `method`、`path`、`host`（若有）、**已解析 JSON 的** `requestBody` / `responseBody`（原 API 为字符串）
+- **dbtable**：`dbtableConfig` 关键信息（含 `allFieldNames` 由 `allFields` 拆分）
+- **relatedPages**：来自 `relatedPageInfoList`（`id` / `type` / `code` / `title` / `deleted`）
+- **relations**、**indexes**、**formatRules**、**validateRules** 等与平台返回一致
+
+## CLI 标准信封与 `data` 指代
+
+声明式命令（含本命令）在 `--format json` 或 `compress` 下，顶层为：
+
+`{ ok, command, risk, data }`（失败时可能含 `error` 等，以实际输出为准）。
+
+下文及 **`references/`、`guides/`** 中凡写「`data.*`」，均指该 **`data` 对象**（不是 HTTP 原始体里其它层级的同名键）。
+
+## 平台 `get-driven-data` 与 CLI 输出的对应
+
+阅读 OpenAPI 或对照 `rabetbase-cli/mock/get-driven-data.json` 时，需与 CLI 归一化结果区分：
+
+| 概念 | 平台原始（`get-driven-data` 业务负载内） | CLI `dataset detail` 的 `data` |
+|------|------------------------------------------|-------------------------------|
+| 数据集数字 ID | `modelId` 或 `dataset.datasetId` | `data.id` |
+| 数据集 32 位 hex | `modelCode` / `dataset.datasetCode` | `data.code` |
+| 库表级配置 | `dbtableConfig`（与 `fields`、`operations` 等并列） | `data.dbtable`（子字段键名与 `dbtableConfig` **一致**；`allFields` 为逗号串时衍生 **`allFieldNames`**） |
+| 字段列表 | `fields[]`（原始字段名可能与归一化不一致） | `data.fields[]`（v1/v2 统一为 `name` / `type` / `pk` 等） |
+
+**日常以 CLI 的 `data.fields[]` 为准。** 完整原始形状见仓库 **`rabetbase-cli/mock/get-driven-data.json`**。勿与 HTTP 最外层的 `success`/`msg` 混淆——平台文档里的「`data`」指业务负载；CLI 文档里的「`data`」指信封内的 `data` 对象。
+
+**平台 URL**（如 `.../data/dataset/{datasetId}#api-list`）中的 **`datasetId`** 与 OpenAPI 中的 **`data.modelId`**（或 **`data.dataset.datasetId`**）一致；CLI 中为 **`data.id`**（数字），与 **`data.code`**（32 位 hex）描述同一数据集。
+
+### `data` 内常用键（速查）
+
+| 信息项 | 路径（`data` 内） | 说明 |
+|--------|------------------|------|
+| 数据集标识 | `id`, `code`, `name`, `doVersion` | 数字 id、32 位 code、展示名 |
+| 字段列表 | `fields[]` | 归一化字段（表单、查询、SQL 列名均以 `name` 为准） |
+| 操作端点 | `operations[]` | 含 `method`/`path` 及解析后的 `requestBody`/`responseBody` |
+| 依赖关系 | `relations[]` | 主外键（无关联时为空数组） |
+| 库与表 | `db`, `dbtable`, `table` | `db` 为 `{ id, name }`；`dbtable` 为表级配置摘要 |
+
+### 字段归一化（`data.fields[]`）
+
+| 字段 | 含义 | 用途 |
+|------|------|------|
+| `name` | **列名**（接口参数中的字段名） | 查询 / 写入 / SQL |
+| `displayName` | 人类可读展示名 | 表单 label |
+| `type` | API 层类型（对应平台 `doType`） | 接口约束 |
+| `dbType` | 数据库存储类型 | SQL 编写 |
+| `pk` | 是否主键 | create 策略 |
+| `required` | 是否必填 | 校验 |
+| `deprecated` | 字段是否已废弃 | 字段治理、页面/脚本迁移判断 |
+| `options` | SELECT/ENUM 的 `{label, value, children}[]` | 下拉枚举 |
+
+平台原始 JSON 中的 `systemRetain` / `autoIncrement` 等 **不会逐字段完整体现在归一化 `fields[]`**；字段生命周期标记 `deprecated` 会归一化为布尔值。系统时间列请结合 **`data.dbtable.createTimeField` / `updateTimeField`** 与 [`guides/backend-function.md`](../guides/backend-function.md) 约定判断。
+
+### 数据库配置（`data.dbtable`）关键字段
+
+| 路径 | 含义 | 用途 |
+|------|------|------|
+| `dbId` | 数据库 ID | SQL、跨库 |
+| `tableName` | 物理表名 | SQL 表名 |
+| `pkField` | 主键列名 | JOIN、条件 |
+| `createTimeField.fieldName` | 创建时间列 | 筛选、排序 |
+| `updateTimeField.fieldName` | 更新时间列 | 筛选、排序 |
+| `creatorIdField.fieldName` | 创建人 ID 列（可能为 `null`） | 权限过滤 |
+
+需要再缩小 JSON 时，用全局 **`--jq`**（在 `--format json` 或 `compress` 之后对信封做投影），例如：
+
+```bash
+# 仅 data 里的字段与操作名（envelope 含 ok/command/data）
+rabetbase dataset detail --code <数据集编码> --format json --jq '.data | {fields, opNames: [.operations[].name]}'
+
+# 仅查看 filter 操作的请求体 schema
+rabetbase dataset detail --code <数据集编码> --format json --jq '.data.operations[] | select(.name=="filter") | .requestBody'
+```
+
+## 提示
+
+- 写 SQL / BFF 前先调用此命令确认真实字段名、类型与枚举；关联关系统一看 **`dataset relations`**
+- `--alias` 需要先执行 `rabetbase api pull` 生成 `api.ts`
+- 横切数据访问流程、外键与性能：见 [`guides/data-api-guidelines.md`](../guides/data-api-guidelines.md)
+
+## 参考
+
+- [SKILL.md](../SKILL.md)
+- 响应形状示例：`rabetbase-cli/mock/get-driven-data.json`

package/skills/rabetbase/references/rabetbase-dataset-extend-update.md

@@ -0,0 +1,70 @@
+# dataset extend-update
+
+Dataset 顶层 `extend` 更新命令。
+
+本命令保留为 Dataset 顶层 `extend` 的专用入口，但当前可写 key 白名单为空。它不是字段更新工具，不修改 `fields[]` 或 `properties[]` 中的字段对象，也不作为业务模型分组更新路径；业务模型分组请使用 `dataset business-group-update`。
+
+## 命令
+
+```bash
+rabetbase dataset extend-update \
+  --appcode app-64e32817 \
+  --code 1a90dbff5f094a9a89936fa99b10984c \
+  --patch-json '{"someExtendKey":"value"}' \
+  --dry-run \
+  --format compress
+```
+
+当前该命令会因白名单为空拒绝 patch key。若目标是修改业务模型分组，不要使用本命令。
+
+## 参数
+
+| Flag                   | 必填                       | 说明                                                       |
+| ---------------------- | -------------------------- | ---------------------------------------------------------- |
+| `--appcode <code>`     | 否                         | 目标应用编码；未配置默认 app 时必填                        |
+| `--code <code>`        | 是                         | Dataset code，32 位 hex UUID                               |
+| `--patch-json <json>`  | 是                         | JSON 对象 patch；当前白名单为空                            |
+| `--expect-json <json>` | 否                         | 当前 `extend` 值保护；任一键不匹配即中止且不写入           |
+| `--dry-run`            | 否                         | 预览模式；当前仍会因白名单为空被拒绝                       |
+| `--format <fmt>`       | 否                         | 输出格式，AI Agent 优先用 `compress`                       |
+
+## 可修改字段
+
+当前白名单为空，没有开放可修改字段。
+
+`businessGroup` 会被明确拒绝，并提示改用 `dataset business-group-update`。
+
+## 输出
+
+当前传入 `businessGroup` 时会返回校验错误，错误语义类似：
+
+```json
+{
+  "ok": false,
+  "error": {
+    "message": "dataset extend-update does not support businessGroup; use dataset business-group-update"
+  }
+}
+```
+
+## 操作边界
+
+- 命令只使用 `--code` 定位 Dataset，保持目标清晰且可复现。
+- 当前白名单为空；任何 `--patch-json` key 都会被拒绝。
+- `businessGroup` 不属于本命令职责。
+- 命令不修改字段对象。字段级业务配置继续使用 `rabetbase dataset field-update`。
+- 业务模型分组更新请使用 `rabetbase dataset business-group-update`。
+
+## 提示
+
+- 不要用 `extend-update` 修改业务模型分组。
+- 修改业务模型分组时，使用 `rabetbase dataset business-group-update`，并先执行 `--dry-run`。
+- 不确定 Dataset code 时，先用 `rabetbase dataset list --name <name> --format compress` 或 `rabetbase dataset detail` 相关上下文定位，再回到本命令显式传 `--code`。
+
+## 参考
+
+- [dataset detail](rabetbase-dataset-detail.md)
+- [dataset business-group-update](rabetbase-dataset-business-group-update.md)
+- [dataset field-update](rabetbase-dataset-field-update.md)
+- [dataset list](rabetbase-dataset-list.md)
+- [SKILL.md](../SKILL.md)

package/skills/rabetbase/references/rabetbase-dataset-field-update.md

@@ -0,0 +1,117 @@
+# dataset field-update
+
+安全更新 Dataset 原始 `fields[]` 中的单个 field 对象。
+
+本命令用于修正字段的业务配置元数据，例如把负责人字段的 `doType` 从 `TEXT` 改为 `USER`，补齐 `SELECT` 字段的 `options`，或把字段标记为 `deprecated=true`。它不是物理字段迁移工具，不修改字段身份、数据库类型或删除/主键等系统状态。
+
+## 命令
+
+```bash
+rabetbase dataset field-update \
+  --appcode app-64e32817 \
+  --code 1a90dbff5f094a9a89936fa99b10984c \
+  --field assignee_id \
+  --patch-json '{"doType":"USER"}' \
+  --expect-json '{"doType":"TEXT"}' \
+  --dry-run \
+  --format compress
+```
+
+## 参数
+
+| Flag | 必填 | 说明 |
+|------|------|------|
+| `--appcode <code>` | 否 | 目标应用编码；未配置默认 app 时必填 |
+| `--code <code>` | 是 | Dataset code，32 位 hex UUID |
+| `--field <name>` | 是 | 精确匹配原始 `fields[].name` |
+| `--patch-json <json>` | 是 | JSON 对象 patch；对象深度合并，数组/标量整体替换 |
+| `--expect-json <json>` | 否 | 当前值保护；任一键不匹配即中止且不写入 |
+| `--dry-run` | 否 | 只返回 before/after、changedPaths 和提交预览，不调用写接口 |
+| `--format <fmt>` | 否 | 输出格式，AI Agent 优先用 `compress` |
+
+## 可修改字段
+
+第一版只允许 patch 已知可变业务配置属性：
+
+- `doType`
+- `displayName`
+- `description`
+- `options`
+- `required`
+- `datetimeFormat`
+- `defaultAggregation`
+- `chartRole`
+- `deprecated`
+
+## 禁止修改字段
+
+`--patch-json` 禁止包含以下字段：
+
+- 字段身份：`id`、`name`、`code`
+- 物理库映射：`dbType`、`dbTypeLen`、`dbTypeScale`、`dbFieldName`、`tableName`
+- 系统或生命周期属性：`deleted`、`pkField`、`autoIncrement`、`systemRetain`
+
+禁止规则只约束写入 patch。`--expect-json` 可以包含这些字段，用于确认当前 field 仍是预期对象。
+
+## 输出
+
+返回结构包含：
+
+```json
+{
+  "appCode": "app-64e32817",
+  "selector": {
+    "code": "1a90dbff5f094a9a89936fa99b10984c"
+  },
+  "dataset": {
+    "id": 1010859,
+    "code": "1a90dbff5f094a9a89936fa99b10984c",
+    "name": "需求",
+    "table": "requirements"
+  },
+  "field": {
+    "id": 832007,
+    "name": "assignee_id"
+  },
+  "dryRun": true,
+  "changed": true,
+  "changedPaths": ["doType"],
+  "before": {
+    "id": 832007,
+    "name": "assignee_id",
+    "displayName": "负责人",
+    "doType": "TEXT"
+  },
+  "after": {
+    "id": 832007,
+    "name": "assignee_id",
+    "displayName": "负责人",
+    "doType": "USER"
+  },
+  "submitted": false
+}
+```
+
+当 patch 后无变化时，返回 `changed=false`，不会调用写接口。
+
+## 操作边界
+
+- 命令读取平台 `get-driven-data` 原始结构，按 `fields[].name` 精确定位字段。
+- 命令只使用 `--code` 定位 Dataset，保持 AI First 协议标识清晰且可复现。
+- 非 `--dry-run` 且确有变化时，命令通过 `/smartapi/dataset/update-driven-data` 提交完整 driven data。
+- V2 后端保存链路会触发关联页面更新；CLI 不额外调用 `rabetbase page sync`。
+- 页面仍未生效时，再按页面状态单独处理 `page sync`、页面保存或发布。
+
+## 提示
+
+- 写入前必须先运行 `--dry-run`。
+- 推荐用 `--expect-json` 保护当前值，例如 `--expect-json '{"doType":"TEXT"}'`。
+- 不要修改 `dataset detail` 归一化输出里的 `type`；本命令 patch 的是平台原始 field 对象上的 `doType`。
+- 不要用本命令修改字段名、数据库类型、主键、自增、删除状态等结构性或系统性属性；字段废弃状态只允许通过 `deprecated` 显式 patch。
+- 不确定 Dataset code 时，可先用 `rabetbase dataset list --name <name> --format compress` 定位，再回到本命令显式传 `--code`。
+
+## 参考
+
+- [dataset detail](rabetbase-dataset-detail.md)
+- [dataset list](rabetbase-dataset-list.md)
+- [SKILL.md](../SKILL.md)

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

@@ -0,0 +1,206 @@
+# dataset generate-start / generate-status
+
+从自然语言需求生成可审阅的数据集 design 快照，再基于快照提交异步创建任务，最后查询任务状态拿到新 Dataset。
+
+推荐顺序：
+
+1. `dataset generate-start` preview：生成并写出本地 design JSON。
+2. `dataset generate-start --apply`：读取已审阅的 design JSON，提交异步任务。
+3. `dataset generate-status`：查询任务状态；成功后使用 `createdDataset.code`。
+
+## 适用范围
+
+当前能力面向服务端支持的 `METADATA` 数据集生成链路。design 文件结构由服务端返回并由 CLI 原样提交，调用方不需要手写或选择内部 DO 版本。
+
+## Preview：生成 design 快照
+
+```bash
+rabetbase dataset generate-start \
+  --name "客户档案" \
+  --description "记录客户姓名、手机号、归属销售和跟进状态" \
+  --design-output .rabetbase/dataset-designs/customer-profile.json \
+  --format compress
+```
+
+Preview 阶段必填：
+
+| Flag | 说明 |
+|------|------|
+| `--name <name>` | 目标 Dataset 展示名 |
+| `--description <text>` | 自然语言需求描述 |
+| `--design-output <path>` | 写出的本地 design JSON 文件 |
+| `--appcode <code>` | 可选；未配置默认 app 时必填 |
+| `--format compress` | Agent 优先使用 |
+
+Preview 阶段禁止传 `--design-file`。Preview 只产生 design 文件，不创建 Dataset。
+
+## Start：提交异步创建任务
+
+确认 design 文件后再执行：
+
+```bash
+rabetbase dataset generate-start \
+  --apply \
+  --design-file .rabetbase/dataset-designs/customer-profile.json \
+  --format compress
+```
+
+Start 阶段必填：
+
+| Flag | 说明 |
+|------|------|
+| `--apply` | 提交异步创建任务 |
+| `--design-file <path>` | 已审阅的 design JSON 文件 |
+| `--appcode <code>` | 可选；未配置默认 app 时必填 |
+| `--format compress` | Agent 优先使用 |
+
+Start 阶段禁止同时传 `--name`、`--description`、`--design-output`。Start 不会重新根据描述生成 design，也不代表 Dataset 已创建完成。
+
+## Status：查询任务状态
+
+优先使用 start 输出里的 `query.command`：
+
+```bash
+rabetbase dataset generate-status --task-id 2da9d1d7-8e34-4ce5-97af-72d2df9870aa --format compress
+```
+
+如果旧响应没有 `taskId`，可回退 `operationId`；如果两者都没有，再使用 `clientOperationId`：
+
+```bash
+rabetbase dataset generate-status --operation-id op-xxx --format compress
+rabetbase dataset generate-status --client-operation-id dataset-generate-xxx --format compress
+```
+
+`--task-id`、`--operation-id` 与 `--client-operation-id` 必须且只能传一个。taskId 是首选恢复标识；CLI 会把它映射为后端 Dataset status 的 `operationId` query，服务端接口本身没有原生 taskId query。只有 status 输出 `status=generated_dataset_created` 且包含非空 `createdDataset.code` 时，后续才可执行 `dataset detail`、`page generate-start` 或 `api pull`。
+
+## dry-run
+
+三条路径都支持 `--dry-run`：
+
+```bash
+rabetbase dataset generate-start \
+  --name "客户档案" \
+  --description "记录客户姓名和手机号" \
+  --design-output .rabetbase/dataset-designs/customer-profile.json \
+  --dry-run \
+  --format compress
+
+rabetbase dataset generate-start \
+  --apply \
+  --design-file .rabetbase/dataset-designs/customer-profile.json \
+  --dry-run \
+  --format compress
+
+rabetbase dataset generate-status --task-id 2da9d1d7-8e34-4ce5-97af-72d2df9870aa --dry-run --format compress
+```
+
+Preview dry-run 只返回将调用的 preview endpoint 和 body，不写文件。Start dry-run 会读取本地 design 文件，并返回将调用的 start endpoint 和 body，但不提交任务。Status dry-run 只返回将查询的 status endpoint。
+
+## 输出
+
+Preview 输出的 `data` 包含：
+
+```json
+{
+  "operation": "dataset.generate.preview",
+  "input": {
+    "appCode": "app-xxx",
+    "datasetName": "客户档案",
+    "requirementDescription": "记录客户姓名和手机号"
+  },
+  "design": {},
+  "designFile": ".rabetbase/dataset-designs/customer-profile.json",
+  "warnings": [],
+  "nextAction": {
+    "command": "rabetbase dataset generate-start --apply --design-file .rabetbase/dataset-designs/customer-profile.json --format compress"
+  }
+}
+```
+
+Start 输出的 `data` 包含：
+
+```json
+{
+  "operation": "dataset.generate.start",
+  "appCode": "app-xxx",
+  "taskId": "2da9d1d7-8e34-4ce5-97af-72d2df9870aa",
+  "operationId": "2da9d1d7-8e34-4ce5-97af-72d2df9870aa",
+  "clientOperationId": "dataset-generate-xxx",
+  "jobStatus": "PENDING",
+  "progressRate": 0,
+  "currentStep": "queued",
+  "reused": false,
+  "status": "operation_pending",
+  "nextAction": "query_operation_status",
+  "query": {
+    "command": "rabetbase dataset generate-status --task-id 2da9d1d7-8e34-4ce5-97af-72d2df9870aa --format compress"
+  }
+}
+```
+
+Status 成功后的 `data` 包含：
+
+```json
+{
+  "operation": "dataset.generate.status",
+  "appCode": "app-xxx",
+  "taskId": "2da9d1d7-8e34-4ce5-97af-72d2df9870aa",
+  "operationId": "2da9d1d7-8e34-4ce5-97af-72d2df9870aa",
+  "clientOperationId": "dataset-generate-xxx",
+  "jobStatus": "SUCCESS",
+  "progressRate": 100,
+  "currentStep": "done",
+  "errorMsg": null,
+  "status": "generated_dataset_created",
+  "createdDataset": {
+    "id": 123,
+    "code": "1a90dbff5f094a9a89936fa99b10984c",
+    "name": "客户档案",
+    "tableName": "meta_customer_profile",
+    "fieldCount": 4,
+    "relationCount": 0
+  },
+  "nextAction": null,
+  "query": {
+    "command": "rabetbase dataset generate-status --task-id 2da9d1d7-8e34-4ce5-97af-72d2df9870aa --format compress"
+  }
+}
+```
+
+`status` 常见值：
+
+| status | 含义 |
+|--------|------|
+| `operation_pending` | 任务等待执行 |
+| `operation_running` | 任务执行中；服务端 `PROCESSING` / `RUNNING` 等非终态均继续查询同一个 taskId |
+| `generated_dataset_created` | Dataset 已创建，可使用 `createdDataset.code` |
+| `operation_failed` | 任务失败，查看 `errorMsg` |
+| `unknown_reconcile_failed` | 任务状态无法与 Dataset 结果对应，继续用 `query.command` 查询或人工确认 |
+
+## Agent 执行要求
+
+- 先执行 preview，审阅 `--design-output` 文件，再执行 start。
+- 不要把 preview 输出视为已创建 Dataset。
+- 不要把 start 输出视为已创建 Dataset；必须用 `generate-status` 查询到 `generated_dataset_created`。
+- `PENDING` / `PROCESSING` 都不是完成；始终继续查询同一个 taskId。
+- 超时、未知状态或 start 响应丢失时只做状态恢复，不得自动重提生成请求。
+- 成功后用 `rabetbase dataset detail --code <createdDataset.code> --format compress` 确认结构。
+- 如需生成智能列表页，再执行 `rabetbase page generate-start --datasetcode <createdDataset.code> --format compress`。
+- 真实业务行数据验证交接到 `lovrabet data filter|getOne`。
+
+## 常见失败
+
+| 失败 | 处理 |
+|------|------|
+| Preview 缺 `--name` / `--description` / `--design-output` | 补齐必填参数 |
+| Preview 传了 `--design-file` | 去掉 `--design-file`，或改用 `--apply` |
+| Start 缺 `--design-file` | 指向已审阅的 design JSON 文件 |
+| Start 同时传了 `--name` / `--description` / `--design-output` | 删除这些 preview 参数 |
+| Status 缺任务标识 | 首选传 `--task-id`；旧响应才回退 `--operation-id` 或 `--client-operation-id` |
+| design 文件不是 JSON object | 修正为 JSON object 后重试 |
+
+## 参考
+
+- [dataset detail](rabetbase-dataset-detail.md)
+- [page generate-start](rabetbase-page-generate-start.md)
+- [api pull](rabetbase-api-pull.md)

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

@@ -0,0 +1,42 @@
+# dataset list
+
+列出当前 App 下所有 DO V2 Dataset，包含 `source = DB_TABLE` 和 `source = METADATA`，支持服务端过滤。返回**精简列表**（每行含 `id`、`name`、`code`、`source`、`db`、`table` 等；若列表接口提供字段摘要，也会透出 `fields` 字段名列表）。单数据集的完整结构请用 **`dataset detail`**。
+
+## 命令
+
+```bash
+rabetbase dataset list --format json
+rabetbase dataset list --source METADATA --format json
+rabetbase dataset list --source DB_TABLE --format json
+rabetbase dataset list --name "用户" --format json
+rabetbase dataset list --code "8f737f49c23e4506865b07ebe9dfa316" --format json
+rabetbase dataset list --name "用户" --code "abc" --format json
+rabetbase dataset list --format table
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--name <name>` | string | 否 | — | 按名称模糊过滤（服务端） |
+| `--code <code>` | string | 否 | — | 按 dataset code 精确过滤（服务端） |
+| `--source <source>` | string | 否 | — | 按来源过滤：`DB_TABLE` / `METADATA` |
+| `--format <fmt>` | string | 否 | `pretty` | 输出格式：`json` / `pretty` / `table` |
+
+## 输出
+
+默认返回所有 DO V2 数据集的精简列表（`id`, `name`, `code`, `description`, `source`, `db`, `table`, `datasetKey`, `pk`，以及列表接口提供时的 `fields` 字段名字符串数组）。`dataset list` 不隐式调用详情接口，`fields` 为空是符合预期的轻量列表行为；METADATA 数据集没有物理表配置时，`db` / `table` / `datasetKey` / `pk` 为空是预期行为。需要完整字段定义、操作、关联页等请执行 `rabetbase dataset detail --code …`。
+
+## 提示
+
+- `--name` 和 `--code` 均为服务端过滤，响应快、带宽小
+- `--code` 为精确匹配，适合已知 datasetCode 的场景
+- `--name` 为模糊匹配，适合搜索探索
+- 两者可组合使用，同时传递时取交集
+- 要回答“有哪些 METADATA 类型数据集”时，优先使用 `rabetbase dataset list --source METADATA --format json`
+- AI Agent 推荐始终使用 `--format json`
+- 列表项较多时可用 `--jq` 只取需要的键，例如：`--jq '.data.datasets[] | {code, name}'`
+
+## 参考
+
+- [SKILL.md](../SKILL.md)

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

@@ -0,0 +1,34 @@
+# dataset operations
+
+获取指定 Dataset 的操作列表；可选指定单个操作名获取完整参数定义。
+
+## 命令
+
+```bash
+rabetbase dataset operations --alias order --format json
+rabetbase dataset operations --alias order --operation filter --format json
+rabetbase dataset operations --code 097b7361b76c42bcb12b923fa5a08861 --operation getOne --format json
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--code <code>` | string | 与 alias 二选一 | — | Dataset code（32 位 hex UUID） |
+| `--alias <name>` | string | 与 code 二选一 | — | `api.ts` 中定义的别名 |
+| `--operation <name>` | string | 否 | — | 操作名（如 `filter` `getOne` `create` `update` `delete`） |
+| `--verbose` | boolean | 否 | — | 返回完整操作对象（含 `requestFields` / `responseFields` / `path`） |
+| `--format <fmt>` | string | 否 | `pretty` | 输出格式 |
+
+## 输出
+
+不传 `--operation` 时返回操作摘要列表；传 `--operation` 时返回该操作的完整参数定义。
+
+## 提示
+
+- 生成 SDK 代码前，先用此命令确认操作是否存在、参数定义
+- 常见操作：`filter`（列表查询）、`getOne`（单条）、`create`（新建）、`update`（更新）、`delete`（删除）、`aggregate`（聚合）
+
+## 参考
+
+- [SKILL.md](../SKILL.md)