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

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

@@ -0,0 +1,48 @@
+# menu rename
+
+按精确菜单 ID 修改菜单名称。该能力适用于所有菜单类型，不根据页面类型、打开方式或是否为分组选择不同命令。
+
+## 命令
+
+```bash
+rabetbase menu rename --id "<menu-id>" --label "新名称" --expect-label "原名称" --dry-run --format compress
+rabetbase menu rename --id "<menu-id>" --label "新名称" --expect-label "原名称" --format compress
+```
+
+## Flags
+
+| Flag | 类型 | 说明 |
+|---|---|---|
+| `--id <id>` | number | 必填，`menu list` 返回的精确菜单 ID |
+| `--label <label>` | string | 必填，新菜单名称；首尾空白会被移除，不能是空字符串 |
+| `--expect-label <label>` | string | 必填，断言当前菜单名称，防止覆盖他人的并发修改 |
+| `--dry-run` | boolean | 输出完整 before/after 和写入计划，不修改线上菜单 |
+
+## 执行顺序
+
+1. 先运行 `rabetbase menu list --format compress`，确认目标菜单的 `id` 和当前 `label`。
+2. 使用当前名称作为 `--expect-label` 执行 dry-run。
+3. 确认 `before/after` 仅有 `label` 发生预期变化。
+4. 复用相同参数并移除 `--dry-run`，执行正式写入。
+5. 检查结果中的 `verification.matchesRequestedState=true`。
+
+新名称与当前名称相同时返回成功 no-op，不发送写请求。即使是 no-op，当前名称仍必须匹配 `--expect-label`。
+
+## 安全规则
+
+- 不按 `folder`、`iframe`、`link`、`procode` 或其他类型分支。
+- 只修改 `label`，保留菜单 ID、父级、排序、path、URL、页面绑定、资源、可见性和权限关联。
+- dry-run 后线上菜单事实发生变化时，正式执行会拒绝写入，需重新获取菜单事实并预览。
+- 响应丢失时不自动重试写入。CLI 回读确认新名称与其他菜单事实后才返回 `recovered=true`；无法确认时按返回的 `verification.lookupCommand` 检查线上状态。
+
+## 常见错误
+
+- `menu_state_drift`：当前名称或菜单快照已变化。重新执行 `menu list` 和 dry-run，并更新 `--expect-label`。
+- `menu_update_recovery_required`：写入结果无法安全确认。先执行错误结果中的只读 lookup 命令，不要直接重试。
+
+## 相关命令
+
+- [menu list](rabetbase-menu-list.md)
+- [menu group-update](rabetbase-menu-group-update.md)
+- [menu external-link-update](rabetbase-menu-external-link-update.md)
+- [menu asset-update](rabetbase-menu-asset-update.md)

package/skills/rabetbase/references/rabetbase-menu-sync.md

@@ -0,0 +1,60 @@
+# menu sync
+
+扫描本地 `src/pages/**/*.tsx`，把线上缺失的路由注册为平台 `procode` 菜单。
+
+> **风险等级：write** — 修改平台菜单配置。
+
+## 命令
+
+```bash
+# 交互模式（TTY）
+rabetbase menu sync
+
+# 发现待同步页面的真实 path，不写入
+rabetbase menu sync --dry-run --format json
+
+# 按 targetPages[].path 精确预览
+rabetbase menu sync --paths "<local-page-path>" --params '{"jsUrl":"https://cdn.example.com/app.js"}' --dry-run --format compress
+
+# 静默全量同步
+rabetbase menu sync --yes
+
+# 静默部分同步（预填 URL 和精确 path）
+rabetbase menu sync --paths "<local-page-path-1>,<local-page-path-2>" --params '{"jsUrl":"https://...js","cssUrl":"https://...css"}' --yes
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--params <json>` | string | 否 | — | 预填 JS/CSS URL。JSON 格式：`{"jsUrl":"...","cssUrl":"..."}` |
+| `--paths <csv>` | string | 否 | — | 按本地页面 path 精确选择；值来自 dry-run 的 `targetPages[].path` |
+| `--yes` | boolean | 否 | — | 确认非交互执行；未传 `--paths` 时创建全部本地未上线页面 |
+| `--dry-run` | boolean | 否 | `false` | 复用真实扫描、线上 diff 和 URL 校验，返回计划但不创建菜单 |
+| `--format <fmt>` | string | 否 | `compress` | 输出格式 |
+
+## 三种执行模式
+
+1. **`--yes`** — 非交互同步；未传 `--paths` 时创建全部本地未在平台上的页面
+2. **`--paths` + `--yes`** — 按本地 path 精确同步指定页面
+3. **TTY 交互式** — 展示名称、path 与线上状态 → checkbox 选择未注册页面 → 输入 JS/CSS URL → 确认 → 执行创建
+
+## 输出
+
+- 成功：`✓ Menu sync completed: N menu(s) created`
+- 无需同步：`✓ All local pages are already on platform` 或 `! No local pages found in src/pages`
+- `--dry-run`：返回 `targetPages` 和 `plannedMenus`；`created=0`，且不调用菜单创建接口
+
+## 提示
+
+- 本地页面扫描 `src/pages` 目录
+- 同步前会获取线上菜单列表做 diff
+- path 是稳定选择器，名称只用于展示；多个 path 必须全部匹配
+- 已在平台存在的 path 不会重复创建
+- 交互模式下会展示 compare table（名称、path、本地与线上状态）
+- CLI 只注册菜单和资源引用，不构建、不上传源码或静态资源
+- 当前 React/Vite 模板使用 `loadScriptMode=import`；资源 URL 指向已部署的 CDN 构建产物
+
+## 参考
+
+- [SKILL.md](../SKILL.md)

package/skills/rabetbase/references/rabetbase-notification-config-list.md

@@ -0,0 +1,80 @@
+# rabetbase notification config-list
+
+只读查询当前应用的应用级通知渠道配置，主要用于获取 BFF 消息通知扩展需要的 `configCode`。
+
+## 命令
+
+```bash
+rabetbase notification config-list --format compress
+rabetbase notification config-list --type EMAIL --format compress
+rabetbase notification config-list --type EMAIL --appcode app-xxxxx --format json
+```
+
+`--type` 默认 `EMAIL`，支持：
+
+* `EMAIL`
+* `FEISHU`
+* `DINGTALK`
+* `WECOM`
+* `WEBHOOK`
+
+类型值使用大写。
+
+## 输出
+
+```json
+{
+  "ok": true,
+  "data": {
+    "appCode": "app-xxxxx",
+    "channelType": "EMAIL",
+    "count": 1,
+    "configs": [
+      {
+        "id": 7,
+        "configCode": "ncc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+        "configName": "官方邮件",
+        "channelType": "EMAIL",
+        "description": "业务通知邮件",
+        "createTime": "2026-07-01T00:00:00Z",
+        "updateTime": "2026-07-02T00:00:00Z"
+      }
+    ]
+  },
+  "message": "Found 1 EMAIL notification config(s)"
+}
+```
+
+CLI 只输出用于选择配置的安全字段，不输出：
+
+* `channelConfig`
+* `endpointUrl`
+* SMTP 用户名、密码、token、secret
+* 连接超时和创建人/更新人等身份审计字段
+
+若服务端返回的任一记录缺少非空的 `configCode`、`configName` 或 `channelType`，CLI 会返回 `api_error`，不会用空字符串伪造可用配置，也不会输出可能不完整的成功列表。
+
+## BFF 使用
+
+先根据 `configName` 和 `description` 选择目标配置，再把同一项的 `configCode` 传给：
+
+```javascript
+await context.client.extension.execute("notification", "send", {
+  configCode: "ncc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+  audiences,
+  message,
+});
+```
+
+边界：
+
+* `configCode` 是应用级通知配置编码。
+* dataset 级通知通道的 `channelCode` 不能替代 `configCode`。
+* 没有查询结果时，不要编造配置编码。
+* 多个候选无法判断时，向用户确认，不要默认取第一条。
+* 该命令不会发送通知，也不会修改平台配置。
+
+## 参考
+
+* [BFF 创建工作流](../guides/bff-creation-workflow.md)
+* [Backend Function 消息通知扩展](../guides/backend-function.md#消息通知扩展)

package/skills/rabetbase/references/rabetbase-ocr.md

@@ -0,0 +1,86 @@
+# ocr recognize
+
+使用平台 OCR 服务识别远程 URL 或本地图片/PDF。适用于发票、证照、表格图片、合同附件和普通文字识别。
+
+## 风险边界
+
+`ocr recognize` 的风险等级为 `read`：命令不创建、更新或删除业务数据。服务端仍可能记录审计、调用第三方 OCR 服务并产生计费；如需将识别结果写入 Dataset，后续写入命令继续按其 `write` 或 `high-risk-write` 规则执行。
+
+本地文件模式会把文件上传到目标应用并生成未绑定业务记录的文件对象。执行前需要核对 `appCode`、文件敏感性和账号权限；最终答复不回显 Cookie 或签名 URL。
+
+## 命令
+
+```bash
+# 远程 URL
+rabetbase ocr recognize \
+  --scene invoice \
+  --image-url 'https://files.example.com/invoice.png' \
+  --appcode app-demo \
+  --format compress
+
+# 本地文件
+rabetbase ocr recognize \
+  --scene invoice \
+  --image-file ./invoice.png \
+  --appcode app-demo \
+  --format compress
+```
+
+## Flags
+
+| Flag | 必填 | 说明 |
+|------|------|------|
+| `--scene <scene>` | 是 | `invoice`、`general`、`form` 或 `idCard` |
+| `--image-url <url>` | 二选一 | 公开可访问的图片或文件 URL |
+| `--image-file <path>` | 二选一 | 本地图片或 PDF，普通文件且不超过 50 MB |
+| `--appcode <code>` | 取决于项目上下文 | 目标应用；项目未配置默认应用时显式传入 |
+| `--dry-run` | 否 | 只预览调用链，不上传、不查询 URL、不调用 OCR |
+
+`--image-url` 与 `--image-file` 必须且只能选择一个。
+
+## Scene 映射
+
+| scene | 服务端 type | 用途 |
+|-------|-------------|------|
+| `invoice` | `Invoice` | 发票 |
+| `general` | `General` | 通用文字 |
+| `form` | `Table` | 表格 |
+| `idCard` | `IdCard` | 身份证 |
+
+## 调用链
+
+- URL 模式：直接调用平台 OCR 接口。
+- 本地文件模式：`file upload` → `file query-url`（短效 URL）→ OCR。
+- OCR 中间 URL 不使用 `--long-term`，输出的 `sourceFile.filePath` 可用于后续文件引用。
+
+正式执行前可先预览：
+
+```bash
+rabetbase ocr recognize \
+  --scene form \
+  --image-file ./table.png \
+  --appcode app-demo \
+  --dry-run \
+  --format compress
+```
+
+## 输出
+
+稳定输出包含 `scene`，并透传服务端可用的 OCR 事实，例如 `text`、`lines`、`type`、`kvData`、`width`、`height` 和 `requestId`。本地文件模式额外返回 `sourceFile.fileName/filePath`。
+
+不要假设所有识别类型都会返回结构化 `kvData`，也不要伪造积分或计费字段。
+
+## 失败处理
+
+| 情况 | 处理 |
+|------|------|
+| 缺少输入或同时提供两种输入 | 只保留 `--image-url` 或 `--image-file` 之一 |
+| scene 不支持 | 改用 `invoice/general/form/idCard` |
+| 本地文件不存在、不是普通文件或超过 50 MB | 修正文件路径或缩小文件后重试 |
+| 上传结果缺少 `filePath` | 报告上传响应异常，不继续查询 URL 或 OCR |
+| URL 查询缺少 `fileUrl` | 报告链接响应异常，不调用 OCR |
+| OCR 权限不足 | 核对目标 `appCode` 和当前 rabetbase 登录账号的应用权限 |
+
+## 相关参考
+
+- [file upload / query-url](rabetbase-file.md)

package/skills/rabetbase/references/rabetbase-page-generate-start.md

@@ -0,0 +1,32 @@
+# page generate-start
+
+异步提交或复用智能列表页（Smart List Page）生成任务。
+
+## 命令
+
+```bash
+# 默认行为：仅预览，不调用平台 API
+rabetbase page generate-start --datasetcode 097b7361b76c42bcb12b923fa5a08861 --format json
+rabetbase page generate-start --alias order --format json
+rabetbase page generate-start --datasetcode 097b7361b76c42bcb12b923fa5a08861 --dry-run --format json
+
+# 真正提交任务
+rabetbase page generate-start --datasetcode 097b7361b76c42bcb12b923fa5a08861 --apply --format json
+rabetbase page generate-start --alias order --apply --format json
+```
+
+## 行为说明
+
+- 这是智能列表页生成的 **async-first 提交入口**。
+- **默认仅返回 dry-run 预览，不会调用 `generate-standard-pages/start`**；需要真正提交任务必须显式加 `--apply`。`--dry-run` 与不传 `--apply` 行为等价。
+- CLI 会先查 `standard-page-status` 做前置判定。
+- 若允许生成且传入 `--apply`，CLI 会自动生成 `clientOperationId`，并调用 Java 侧 `generate-standard-pages/start`。
+- 返回结果里的 `operationId` 是服务端 job 主标识；`clientOperationId` 是调用方恢复 / 幂等锚点。
+- `query.command` 默认给出 `operationId` 查询；调用方若只保留了 `clientOperationId`，也可以用它恢复到同一条任务查询。
+- Agent / 自动化编排优先直接复用返回值里的 `query.command`，不要自己重新拼接恢复查询命令。
+- Agent 自动化场景下，编排器应先跑一次默认预览校验候选数据集，再带 `--apply` 提交；不应直接对所有数据集跑 `--apply`。
+
+## 参考
+
+- [rabetbase-page-generate-status.md](rabetbase-page-generate-status.md)
+- [rabetbase-standard-page-status.md](rabetbase-standard-page-status.md)

package/skills/rabetbase/references/rabetbase-page-generate-status.md

@@ -0,0 +1,32 @@
+# page generate-status
+
+查询智能列表页（Smart List Page）生成任务状态。
+
+## 命令
+
+```bash
+rabetbase page generate-status --datasetcode 097b7361b76c42bcb12b923fa5a08861 --task-id 2da9d1d7-8e34-4ce5-97af-72d2df9870aa --format json
+rabetbase page generate-status --datasetcode 097b7361b76c42bcb12b923fa5a08861 --operation-id op-001 --format json
+rabetbase page generate-status --datasetcode 097b7361b76c42bcb12b923fa5a08861 --client-operation-id client-001 --format json
+```
+
+## 参数
+
+- `--task-id`、`--operation-id` 与 `--client-operation-id` 必须且只能传一个
+- taskId 是首选查询标识，优先直接执行 Start 返回的 `data.query.command`
+- `--operation-id` 用于旧响应或兼容查询
+- `--client-operation-id` 用于调用方恢复 / 幂等查询；通常只在拿不到或丢失 taskId/operationId 时使用
+
+## 行为说明
+
+- 命令查询的是**任务状态**，不是页面事实。
+- 当任务进入成功终态时，CLI 会补查 `standard-page-status`，把页面事实一并附在结果里，方便你直接判断是否形成完整智能列表页组。
+- 若任务仍在 `PENDING/PROCESSING/RUNNING`，结果会保持机器可读的 `status / nextAction / query`。
+- 提交生成后保存 `taskId`、`operationId` 与 `clientOperationId`；超时、未知状态或网络失败时复用原标识查询，不重新执行 `generate-start --apply`，不得自动重提。
+- 成功终态时，页面组锚点位于 `data.standardPageStatus.pageSets[].versionTag`。存在多个完整组、残留页或冲突时交给用户确认，不猜测 `versionTag`。
+- 确认页面组后，使用 `page pull --datasetcode <code> --version-tag <tag>` 精确拉取。
+
+## 参考
+
+- [rabetbase-page-generate-start.md](rabetbase-page-generate-start.md)
+- [rabetbase-standard-page-status.md](rabetbase-standard-page-status.md)

package/skills/rabetbase/references/rabetbase-page-pull.md

@@ -0,0 +1,47 @@
+# page pull
+
+拉取智能列表页（Smart List Page，DOV2 `smart_page`）的 formal schema 到本地 **`.rabetbase/page/<appCode>/`**，进入 `pull -> IDE 编辑 -> push` 工作流。
+
+## 命令
+
+```bash
+rabetbase page pull --id 1020286 --format json
+rabetbase page pull --datasetcode 097b7361b76c42bcb12b923fa5a08861 --format json
+rabetbase page pull --datasetcode 097b7361b76c42bcb12b923fa5a08861 --version-tag a1b2c3d4 --format json
+rabetbase page pull --id 1020286 --force --format json
+rabetbase page pull --datasetcode 097b7361b76c42bcb12b923fa5a08861 --dry-run --format json
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--id <pageId>` | number | 与 `--datasetcode` / `--alias` 互斥二选一 | — | 单页拉取 |
+| `--datasetcode <code>` | string | 与 `--id` 互斥；和 `--alias` 二选一 | — | 按数据集批量拉取 |
+| `--alias <name>` | string | 与 `--id` 互斥；和 `--datasetcode` 二选一 | — | 数据集别名 |
+| `--version-tag <tag>` | string | 否 | — | 批量模式下指定页面组 |
+| `--force` | boolean | 否 | `false` | 覆盖本地未推送修改 |
+| `--dry-run` | boolean | 否 | `false` | 仅预览将被拉取/跳过的页面 |
+| `--format <fmt>` | string | 否 | `compress` | 输出格式 |
+
+## 本地文件
+
+- 页面文件：`.rabetbase/page/<appCode>/<pageId>-<TYPE>.json`
+- 基线锁文件：`.rabetbase/page.lock.json`
+
+## 行为说明
+
+- 单页模式：按 `pageId` 拉取单个页面并更新 lock
+- 批量模式：按数据集筛选关联页面；若存在多个 `versionTag` 组且未指定 `--version-tag`，命令会 fail-fast
+- 本地文件存在未推送修改且未传 `--force` 时，会跳过或报冲突
+- 页面生成链路中的 `versionTag` 来自 `page generate-status` 的 `data.standardPageStatus.pageSets[]`；存在多个候选组时先由用户确认，不按顺序或时间猜测
+
+## 提示
+
+- 本地编辑 formal schema 前，先执行一次 pull 建立基线
+- 若要理解 schema 组件语义，再按需查看 `knowledge/page-schema/` 下的 PageSchema 知识；那是组件参考，不是 CLI 命令 reference
+
+## 参考
+
+- [SKILL.md](../SKILL.md)
+- [rabetbase-page-push.md](rabetbase-page-push.md)

package/skills/rabetbase/references/rabetbase-page-push.md

@@ -0,0 +1,45 @@
+# page push
+
+将本地页面 schema 推送回平台；推送成功后会自动回拉 canonical schema 覆盖本地文件与 lock。
+
+## 命令
+
+```bash
+rabetbase page push --id 1020286 --format json
+rabetbase page push --datasetcode 097b7361b76c42bcb12b923fa5a08861 --format json
+rabetbase page push --datasetcode 097b7361b76c42bcb12b923fa5a08861 --version-tag a1b2c3d4 --format json
+rabetbase page push --id 1020286 --dry-run --format json
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--id <pageId>` | number | 与 `--datasetcode` / `--alias` 互斥二选一 | — | 单页推送 |
+| `--datasetcode <code>` | string | 与 `--id` 互斥；和 `--alias` 二选一 | — | 按数据集批量推送 |
+| `--alias <name>` | string | 与 `--id` 互斥；和 `--datasetcode` 二选一 | — | 数据集别名 |
+| `--version-tag <tag>` | string | 否 | — | 批量模式下指定页面组 |
+| `--dry-run` | boolean | 否 | `false` | 做本地校验与远端版本检查，不实际推送 |
+| `--format <fmt>` | string | 否 | `compress` | 输出格式 |
+
+## 前置条件
+
+- 本地已通过 [`rabetbase page pull`](rabetbase-page-pull.md) 建立基线
+- 本地页面文件位于 `.rabetbase/page/<appCode>/`
+- lock 文件 `.rabetbase/page.lock.json` 存在对应页面记录
+
+## 行为说明
+
+- 单页模式：校验本地文件、读取 lock、比对远端版本，再调用更新接口
+- 批量模式：只推送本地 hash 有变更的页面；无基线时会 fail-fast，提示先执行 `page pull`
+- 推送后会再次拉取远端 canonical schema，并覆盖本地文件和 lock，避免本地保留非 canonical 版本
+
+## 提示
+
+- 若远端页面已发生变化，命令会要求先重新 pull，而不是盲推覆盖
+- 批量模式下若存在多个 `versionTag` 组，需显式传 `--version-tag`
+
+## 参考
+
+- [SKILL.md](../SKILL.md)
+- [rabetbase-page-pull.md](rabetbase-page-pull.md)

package/skills/rabetbase/references/rabetbase-page-react-create.md

@@ -0,0 +1,29 @@
+# page react-create
+
+创建 React 自定义页面，初始化 JSX、样式和多语言词包，并同时创建菜单入口。
+
+```bash
+rabetbase page react-create --name "客户看板" --appcode <appCode> --dry-run --format compress
+rabetbase page react-create --name "客户看板" --parent-menu-id 100 --appcode <appCode>
+rabetbase page react-create --name "客户看板" --page-content '<json>' --appcode <appCode>
+rabetbase page react-create --appcode <appCode> --dry-run --format compress
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|---|---|---|
+| `--name <name>` | 否 | 可选页面名称，1–100 个字符；省略时默认 `自定义页面_<timestamp>` |
+| `--parent-menu-id <id>` | 否 | 父菜单 ID |
+| `--page-content <json>` | 否 | 完整页面文件 JSON；对象的键为相对路径，值为文件内容，省略时生成默认 JSX、样式和词包 |
+| `--appcode <code>` | 是 | 目标应用 code |
+
+## 执行步骤
+
+1. 可选传入 `--page-content` 作为完整页面文件 JSON；省略时 CLI 生成默认文件。
+2. 使用 `--dry-run` 确认页面名称、父菜单与最终页面文件。
+3. 确认后使用相同参数执行创建。
+4. 从结构化输出的 `data.after.pageId` 确认新页面 ID，并核对页面名称和生成的文件。
+5. 输出的 `pageUrl` 用于查看最新保存内容，包含尚未发布的修改；`editPageUrl` 用于打开页面编辑器，继续修改页面。
+
+页面创建始终同时创建菜单。CLI 会按应用语言设置生成词包；读取设置失败时使用默认中英文词包。

package/skills/rabetbase/references/rabetbase-page-react-detail.md

@@ -0,0 +1,26 @@
+# page react-detail
+
+查询 React 自定义页面详情。
+
+```bash
+rabetbase page react-detail --id <pageId> --format compress
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|---|---|---|
+| `--id <pageId>` | 是 | React 自定义页面 ID |
+| `--appcode <code>` | 否 | 目标应用 code，省略时根据 `pageId` 查询 |
+
+## 输出
+
+返回页面详情和当前完整页面文件。`createTime` 和 `updateTime` 以 `YYYY-MM-DD HH:mm:ss` 展示。
+
+地址说明（按当前环境）：
+
+- `pageUrl`：查看最新保存内容的页面地址，包含尚未发布的修改
+- `runtimePageUrl`：查看已发布内容的页面地址，仅在有已发布内容时返回；格式为 `https://<appCode>.lovrabet.com/<pageCode>`（线上）或 `https://<appCode>.daily.lovrabet.com/<pageCode>`（日常）
+- `editPageUrl`：打开页面编辑器的地址，可继续修改页面；格式为 `https://<env>.lovrabet.com/web-app/app/<appCode>/ide/<pageId>`（线上为 `app.lovrabet.com`，日常为 `daily.lovrabet.com`）
+
+`data.codeContent` 是当前完整页面文件，可在本地完成新增、修改或删除后，作为 `page react-update --page-content <json>` 的完整页面内容提交。

package/skills/rabetbase/references/rabetbase-page-react-list.md

@@ -0,0 +1,23 @@
+# 查询 React 自定义页面 ID
+
+## 命令
+
+```bash
+rabetbase page react-list --appcode <appCode> --format json
+```
+
+## 适用场景
+
+需要查找 React 自定义页面的 `pageId`，再执行 `page react-detail`、`page react-update` 或 `page react-publish`。
+
+## 参数
+
+- `--appcode <appCode>`：必填，目标应用 code
+
+## 输出
+
+`data.pages` 是当前应用中可操作的 React 自定义页面列表
+
+- `label`：页面名称
+- `pageUrl`：查看最新保存内容的页面地址，包含尚未发布的修改；日常为 `https://daily.lovrabet.com/web-app/app/<appCode>/pages/<path>`，线上为 `https://app.lovrabet.com/app/<appCode>/pages/<path>`
+- `editPageUrl`：打开页面编辑器的地址，可继续修改页面；线上域名为 `app.lovrabet.com`，日常域名为 `daily.lovrabet.com`

package/skills/rabetbase/references/rabetbase-page-react-publish.md

@@ -0,0 +1,23 @@
+# page react-publish
+
+发布 React 自定义页面的当前保存内容。
+
+```bash
+rabetbase page react-publish --id <pageId> --dry-run --format compress
+rabetbase page react-publish --id <pageId> --remark "发布说明" --yes
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|---|---|---|
+| `--id <pageId>` | 是 | React 自定义页面 ID |
+| `--remark <text>` | 否 | 发布备注 |
+
+## 执行步骤
+
+1. 先使用 `page react-detail` 检查 `status` 和页面版本
+2. `status` 为 `FORMAL` 时表示当前内容已经发布，跳过发布，继续查看已发布页面或后续流程
+3. `status` 不是 `FORMAL` 时，使用 `--dry-run` 确认目标页面和发布备注
+4. 用户明确确认后，使用相同参数加 `--yes` 执行发布
+5. 命令发布后回读确认 `data.after.status` 为 `FORMAL`；`data.runtimePageUrl` 查看最近一次已发布内容，`data.pageUrl` 查看最新保存内容（包含尚未发布的修改），`data.editPageUrl` 用于打开页面编辑器。

package/skills/rabetbase/references/rabetbase-page-react-update.md

@@ -0,0 +1,24 @@
+# page react-update
+
+以完整页面文件 JSON 更新 React 自定义页面，并创建新的保存版本。未包含的文件会被删除。
+
+```bash
+rabetbase page react-update --id <pageId> --page-content '<json>' --dry-run --format compress
+rabetbase page react-update --id <pageId> --page-content '<json>' --appcode <appCode>
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|---|---|---|
+| `--id <pageId>` | 是 | React 自定义页面 ID |
+| `--page-content <json>` | 是 | 完整页面文件 JSON；对象的键为相对路径，值为文件内容 |
+| `--appcode <code>` | 否 | 目标应用 code，省略时根据 `pageId` 查询 |
+
+## 执行步骤
+
+1. 先使用 `page react-detail` 读取 `data.codeContent` 中的完整页面文件。
+2. 在本地完成所有文件新增、修改或删除后，使用 `--dry-run` 确认完整页面文件。
+3. 确认后使用相同参数执行更新。
+4. 从结构化输出的 `data.after.version` 确认已保存新版本。
+5. 输出的 `pageUrl` 用于查看最新保存内容，包含尚未发布的修改；`editPageUrl` 用于打开页面编辑器，继续修改页面。

package/skills/rabetbase/references/rabetbase-page-relation-binding.md

@@ -0,0 +1,72 @@
+# page relation binding
+
+页面关系绑定用于校准 Smart List Page 中选择类字段的 options 来源。执行前先读取数据集关系事实，再审计页面 schema，最后通过本地 schema 工作流做可回滚修改。
+
+## 执行流程
+
+```bash
+rabetbase dataset relations --appcode <appCode> --datasetcode <datasetCode> --format compress
+rabetbase page relation-audit --appcode <appCode> --datasetcode <datasetCode> --format compress
+rabetbase page pull --appcode <appCode> --id <pageId> --format json
+rabetbase page push --appcode <appCode> --id <pageId> --dry-run --format compress
+```
+
+`dataset relations` 是关系事实来源；底层默认读取 D0/DO V2，不需要在主流程显式传版本参数。不要靠页面 schema 反推出关系。展示字段以 `dataset relations` 的 `to.labelField` 为准，关系基数以 `relation.cardinality` 为准。`page relation-audit` 只读输出差异，不修改平台。修改页面前先 `page pull` 建立本地基线，提交前必须先跑 `page push --dry-run`。
+
+Agent 不得假设存在自动修复命令，也不得把 audit 结果直接转成平台写入。修复必须走本地 schema 工作流：先 `page pull`，只改审计命中的本地字段节点和对应数据源，再用 `page push --dry-run` 复核差异，最后由明确授权的 `page push` 提交。
+
+## 审计到处理边界
+
+- `relation_options` 通常表示页面绑定与数据集关系匹配，不应作为错误处理。
+- `custom_options` 表示字段或页面当前使用自定义选项，不一定是错误；先确认业务是否期望数据集关联选项。
+- `wrong_label` / `wrong_code` / `wrong_state` / `missing` 只说明审计发现差异，不能直接承诺 `page sync` 自动修复。
+- 若 `dataset relations` 关系事实本身不符合预期，先修正数据集关系并重新审计；若关系事实正确但页面绑定仍不一致，再按本地 schema 工作流或页面同步流程处理。
+- `page sync` 是已有页面同步动作，不是页面 schema 审计结果的通用自动修复器。
+
+## relation options 绑定规则
+
+`optionsType=relation` 来自平台数据集关系时，使用 Page 层 `dataSource.list`，字段层绑定同名 state：
+
+- `dataSource.id` 应稳定指向当前字段的 options 数据源，例如 `<field>_options` 或已有页面中的等价 id。
+- 请求目标使用 `/api/<appCode>/<toDatasetCode>/getSelectOptions`。
+- 值字段写在 `options.params.code`，数组参数形态写在 `paramsArr[name=code].value`。
+- 展示字段写在 `options.params.label`，数组参数形态写在 `paramsArr[name=label].value`。
+- 字段组件通过 `this.state.<dataSource.id>` 读取 options。
+
+`optionsRequest` 只用于外部 options 源。平台数据集的 `getSelectOptions` 不放在字段级 `optionsRequest`，避免页面配置绑定到具体域名或环境。
+
+## custom options
+
+字段自身已有 `options` / `selectItems` 枚举数组时，服务端字段扩展为 `optionsType=custom`，审计结果可以是 `custom_options`。这类字段通常来自数据集枚举，不需要强制改成关系数据源。
+
+## From 字段元数据
+
+`page relation-audit` 会输出 `fromField`，包含 From 数据集字段的 `name`、`doType` / `type`、`optionsType` 和 `hasOptions`。其中 `fromField.optionsType` 与服务端字段扩展 `optionsType` 对齐：
+
+- `relation_options`：页面字段使用 `getSelectOptions` / `JSExpression`，绑定匹配关系事实；对应服务端 `optionsType=relation`。
+- `custom_options`：页面字段使用枚举数组，且 From 字段自身存在 `options` / `selectItems`；对应服务端 `optionsType=custom`。
+
+`fromField.doType` / `fromField.type` 只作为审计上下文输出，不通过本地硬编码类型白名单拦截有效关系绑定。不同业务可能使用字符串、数字或其他类型保存关联值，判断应以关系事实和页面绑定为准。
+
+## 结构化修改边界
+
+只修改审计命中的字段节点和对应 `dataSource.id`。不要做全局字符串替换，也不要因为某个 label 字段变化就同时改其他数据源。
+
+检查顺序：
+
+1. 以 `page relation-audit` 的 `field`、`pageId`、`currentBinding.dataSourceId` 定位 schema。
+2. 校准 `options.params.code` / `paramsArr[name=code].value`。
+3. 校准 `options.params.label` / `paramsArr[name=label].value`。
+4. 确认字段层 state key 与 `dataSource.id` 一致。
+5. 运行 `page push --dry-run`，确认请求体只包含预期页面。
+
+## 输出判断
+
+- `relation_options`：字段使用 `getSelectOptions` / `JSExpression`，且绑定与数据集关系一致。
+- `wrong_label`：展示字段不一致，优先修正 label。
+- `wrong_code`：值字段不一致，需要确认关系方向后再修正。
+- `wrong_state`：字段绑定的 state key 与数据源 id 不一致。
+- `missing`：关系字段没有找到可识别绑定。
+- `ambiguous_binding`：字段候选、目标数据集 URI/ID 和 state key 无法收敛到唯一数据源；查看 `currentBinding.candidates` 中的数据源 ID、URI、code 和 label，人工确认后再修改页面，不能默认取第一项。
+- `custom_options`：字段使用枚举数组，且 From 字段自身存在 `optionsType=custom`。
+- `pageStatus=main_sub_missing`：`relation.bizRelationType=main_sub` 命中 CREATE / UPDATE / DETAIL 页面，且 `LrSmartCreate` / `LrSmartDetail` / `LrSmartUpdate` 中未识别到对象类型的 `props.sub_info`；`status` 仍保留原有字段绑定检查结果。