@lovrabet/rabetbase-cli 2.4.3 → 2.4.4-beta.1

package/skills/rabetbase/guides/backend-function.md

@@ -226,7 +226,7 @@ rabetbase dataset detail --code <datasetCode> --format compress \
 
 确认无误后执行：
 
-* `rabetbase bff push --yes --type <type> --name <name> --format json`
+* `rabetbase bff push --type <type> --name <name> --format json`
 
 如果目标是同步远端到本地，则执行：
 
@@ -387,12 +387,12 @@ const rows = aggregateResult.tableData;
 | `groupBy` | 不支持 | 使用真实数据集字段 |
 | `orderBy` | 支持 | 可以引用聚合输出别名 |
 
-需要按聚合结果过滤且 `aggregate()` 无法用真实字段表达时，使用已配置的 Custom SQL。不要在运行时静默切换到 Custom SQL，也不要动态拼接 SQL。
+需要按聚合结果过滤且 `aggregate()` 无法用真实字段表达时，使用已发布的 Custom SQL。不要在运行时静默切换到 Custom SQL，也不要动态拼接 SQL。
 
 选型规则：
 
 * 单个 `DB_TABLE` 数据集的简单聚合优先使用 `aggregate()`，不要先写 Custom SQL
-* 只有 JOIN、跨表统计、数据库特有函数或 `aggregate()` 无法表达的查询才使用已配置的 Custom SQL
+* 只有 JOIN、跨表统计、数据库特有函数或 `aggregate()` 无法表达的查询才使用已发布的 Custom SQL
 * `aggregate()` 返回值与 `filter()` 一样，从 `.tableData` 读取数据，不要按 SQL 数组返回值处理
 * `METADATA` 数据集不支持 `aggregate()` 或 Custom SQL；不要在失败后静默降级为动态 SQL
 
@@ -555,6 +555,8 @@ export default async function runBusinessFlow(params, context) {
 
 ## SQL 调用规则
 
+BFF 入参使用业务参数；需要执行 SQL 时，通过已发布 Custom SQL 的 `sqlCode` + `params` 调用。执行失败时保留并报告原始错误，根据 SQL 资源状态、参数与权限定位问题。
+
 在 BFF 中使用：
 
 ```javascript

package/skills/rabetbase/guides/bff-creation-workflow.md

@@ -87,7 +87,7 @@ rabetbase dataset detail --code <数据集编码> --format compress \
 * dry-run 不会上传远端，也不会改 lock
 
 ### 8. 推送到平台
-执行 `rabetbase bff push --yes --type <type> --name <name> --format json`：
+执行 `rabetbase bff push --type <type> --name <name> --format json`：
 * 成功项进入 `uploaded`
 * 未变更项进入 `skipped: unchanged`
 * 失败项进入 `failed`
@@ -131,7 +131,7 @@ lovrabet bff exec --appcode <appCode> --name <functionName> --params '<json>' --
 
 ## 修改已有脚本
 
-`rabetbase bff list --format json` → `rabetbase bff detail --id <id> --format json` 拉最新内容 → 如需覆盖本地则 `bff pull` → 修改本地文件 → `bff status` → `bff push --yes`
+`rabetbase bff list --format json` → `rabetbase bff detail --id <id> --format json` 拉最新内容 → 如需覆盖本地则 `bff pull` → 修改本地文件 → `bff status` → `bff push`
 
 ## BFF 语义差异
 

package/skills/rabetbase/guides/conflict-detection.md

@@ -61,8 +61,8 @@
 |------|----------------|-------------|
 | `sql create --dry-run` 成功 | 否 | 说明只是预览，尚未创建远端 SQL |
 | `bff create` 成功 | 否 | 说明本地脚手架已生成，尚未推送远端 |
-| `sql push --yes` 成功 | 是 | 告知已同步远端，可附带 sqlCode / 路径 |
-| `bff push --yes` 成功 | 是 | 告知已推送远端，可附带 lockKey / 名称 |
+| `sql push` 成功 | 是 | 告知已同步远端，可附带 sqlCode / 路径 |
+| `bff push` 成功 | 是 | 告知已推送远端，可附带 lockKey / 名称 |
 | `blocked: true` / `action: blocked` | 否 | 明确说平台未保存，提示手动处理或联系相关人 |
 | 校验失败 / validation error | 否 | 说明未写入远端，先修内容或参数 |
 ## blocked 场景

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

@@ -38,6 +38,39 @@ trace/plan  → 见下一节（分析任务专用）
 
 ## 推荐流程（Agent）
 
+### 差异读取策略（所有流程共用）
+
+```text
+db detail --id <id>
+  → 读取 data.tableCount
+
+用户明确要求实时/强制刷新：
+  → 无论 tableCount 多少，走“刷新后读取”
+
+用户明确要求不刷新：
+  → 直接读取；tableCount > 200 时提示结果可能滞后
+
+用户未指定：
+  tableCount <= 200 → 直接读取
+  tableCount > 200  → 刷新后读取
+  tableCount 缺失   → 直接读取并说明新鲜度未知，不隐式写入
+
+直接读取：
+  db diff --id <id> --all --changed-only
+
+刷新后读取：
+  db diff-refresh-start --id <id>
+    → 只提交一次，保存 data.traceId
+  db diff-refresh-status --id <id> --plan <同一 traceId>
+    → 非终态只重复查询同一 traceId
+    → SUCCESS 后执行 data.lookup.command
+    → FAILED / CANCELLED 停止，不自动重提
+```
+
+`tableCount <= 200` 时服务端通常实时计算默认差异视角，刷新收益很小。`tableCount > 200` 时服务端可能读取最近差异快照，刷新可以降低滞后。`db diff --view all` 是实时全部表分页，用于查看无差异表或主动重新分析已有表，不需要先刷新快照。
+
+差异刷新与 schema 分析是两个独立任务：`diff-refresh-*` 只刷新差异事实，`analyze-*` 才把选中表同步为数据集。两类 traceId 不得混用。
+
 ### A. 取消已有任务
 
 ```text
@@ -59,7 +92,7 @@ db list --format compress
   → 记下目标 connections[].id
 db test --id <id>
 db tables --id <id>
-db diff --id <id>        # 可选：看与上次分析的 schema 差异
+按“差异读取策略”执行 db diff        # 可选：看与上次分析的 schema 差异
 ```
 
 ### C. 新建连接并跑分析
@@ -71,7 +104,7 @@ 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.isTerminal=true 后按“差异读取策略”复查，确认目标差异收敛
   → 检查并返回 data.links.erPage，引导用户确认 ER 图与数据集同步结果
 ```
 
@@ -79,7 +112,7 @@ db analyze-status --id <id> --plan <planId>   # 轮询直到终态
 
 ```text
 db detail --id <id>
-db diff --id <id> --all --changed-only
+按“差异读取策略”刷新或直接执行 db diff --id <id> --all --changed-only
   → 只取 data.toAnalyzeTables；用户要求跳过的表先从列表中剔除
 db analyze-batch-plan --id <id> --tables <toAnalyzeTables> --format compress
   → 保存 data.batches；这是本地 batch plan，不是服务端任务 plan
@@ -101,7 +134,7 @@ db analyze-batch-plan --id <id> --tables <toAnalyzeTables> --format compress
     → 未知状态：停止自动推进并报告，不猜测为终态
 
 全部批次处理完毕：
-db diff --id <id> --all --changed-only
+按“差异读取策略”刷新或直接执行 db diff --id <id> --all --changed-only
   → 重新读取完整事实；目标差异收敛后才算本轮分析完成
   → 仍未收敛则只对剩余非删除表进入下面的逐表恢复
 ```
@@ -117,7 +150,7 @@ db diff --id <id> --all --changed-only
     → 到达终态后才处理下一张表
 
 全部单表任务结束后：
-  db diff --id <id> --all --changed-only
+  按“差异读取策略”刷新或直接执行 db diff --id <id> --all --changed-only
     → 以最终 `db diff --all --changed-only` 的 data.toAnalyzeTables 判断是否收敛
     → 已尝试的剩余表只恢复一次，不再次循环提交
 ```
@@ -156,6 +189,7 @@ 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 diff --view all`；默认 `db diff` 只读取差异结果。
 - **给用户确认页面**：DB 更新或分析完成后返回 `data.links.erPage`；新建连接后返回 `data.links.databasePage`。
 - **不确定 flags**：`rabetbase schema`（无需登录）查契约。
 

package/skills/rabetbase/guides/react-custom-page-workflow.md

@@ -7,6 +7,7 @@
 适用于以下目标：
 
 - 新建或修改 React 自定义页面、看板、门户、落地页或复杂交互页面
+- 使用 ECharts 实现图表、统计卡片和数据大屏
 
 ## 前置上下文
 
@@ -94,6 +95,8 @@ page react-create
 
 ## 数据与服务契约
 
+图表与统计场景使用 `page react-create/update/publish` 管理的 React JSX 页面，呈现层直接使用白名单内的 `echarts@5`。
+
 ### 选型
 
 根据页面的实际业务需求选择数据访问方式，不要为了简单查询引入 SQL 或 BFF：
@@ -101,10 +104,12 @@ page react-create
 | 方式 | 适用场景 | 边界 |
 | --- | --- | --- |
 | 单一数据集请求 | 只涉及一个数据集的查询、详情、分页、筛选、创建、更新或删除 | 严格按照当前数据集 API-doc 返回的调用说明实现，不得自行推测或自由发挥调用标识、方法、字段、参数、返回值或异常处理 |
-| 自定义 SQL | 需要组合多个数据集，或需要数据库完成关联、聚合、分组、排序、计算和复杂筛选 | 先确认 SQL 资源、参数和执行结果，再按 `@lovrabet/sdk` 规范调用；不要在页面中拼接 SQL，也不要把 CLI 的 `data.rows` 当作运行时返回结构 |
-| BFF | 需要注入业务校验、数据转换、加密、条件分支、多步业务编排或外部服务调用 | 将业务逻辑放入已确认的 BFF，由页面通过 SDK 调用；简单数据集请求或单纯数据关联不应额外包装成 BFF |
+| Custom SQL | 需要组合多个数据集，或需要数据库完成关联、聚合、分组、排序、计算和复杂筛选 | 先复用或按 SQL 工作流创建、校验并发布 Custom SQL，再通过 `client.sql.execute({ sqlCode, params })` 调用；不要把 CLI 的 `data.rows` 当作运行时返回结构 |
+| BFF | 需要按当前用户、角色、数据范围或业务规则额外鉴权，或需要数据转换、条件分支、多步编排和外部服务调用 | 将校验和编排放入已确认的 BFF，由页面通过 SDK 调用；前端只传业务参数，BFF 内按需执行已发布的 Custom SQL；简单查询不额外包装成 BFF |
+
+判断顺序：先确认单一数据集请求能否满足需求；数据组合和数据库计算是主要问题时选择 Custom SQL；当前用户、角色、数据范围或业务规则需要额外控制时选择 BFF。三种方式可以根据已确认的 SDK 契约配合使用，但不得自行推测方法、参数或返回结构。
 
-判断顺序：先确认单一数据集请求能否满足需求；数据组合和数据库计算是主要问题时选择自定义 SQL；业务规则、数据处理流程或外部服务协同是主要问题时选择 BFF。三种方式可以根据已确认的 SDK 契约配合使用，但不得自行推测方法、参数或返回结构。
+页面和 BFF 通过已发布 Custom SQL 的 `sqlCode` + `params` 执行查询。Dataset、Custom SQL 或 BFF 执行失败时，保留并报告原始错误，根据资源状态、参数与权限定位问题。
 
 页面需要读取或写入数据集时，先按以下顺序确认事实：
 
@@ -115,7 +120,7 @@ page react-create
 
 页面需要调用自定义 SQL 或 BFF 时，先通过当前 CLI 获取目标资源事实：
 
-1. SQL：执行 `rabetbase sql list`，再执行 `rabetbase sql detail --sqlcode <sqlCode>` 确认目标 SQL
+1. SQL：先执行 `rabetbase sql list` 查找可复用 SQL；命中后执行 `rabetbase sql detail --sqlcode <sqlCode>` 确认目标 SQL。没有满足需求的 SQL 时，先阅读并遵循 [`sql-creation-workflow.md`](sql-creation-workflow.md) 与 [`sql-mybatis.md`](sql-mybatis.md)，完成其中规定的流程后，再使用服务端生成的 `sqlCode` 编写页面
 2. BFF：执行 `rabetbase bff list`，再执行 `rabetbase bff detail --id <id>` 确认目标脚本
 3. 按 `@lovrabet/sdk` 的使用规范实现 `client.sql` 或 `client.bff` 调用，不得根据 CLI 返回结构猜测页面调用参数或返回值
 4. 页面使用自定义 SQL 前，使用代表性参数执行 `rabetbase sql exec --sqlcode <sqlCode> --params <json> --format json`，确认执行没有报错并检查实际数据结构
@@ -123,6 +128,13 @@ page react-create
 
 当前 CLI 没有按单个数据集返回页面数据访问说明的专用命令。在页面中使用 `client` 前，必须以数据集、SQL 或 BFF 的事实，以及对应的 `@lovrabet/sdk` 使用规范为依据；无法确认的字段、接口路径和响应结构不得猜测。
 
+### ECharts 呈现层
+
+- 在 React 页面中直接使用白名单内的 `echarts@5` 构建图表；按组件生命周期初始化、更新和销毁实例。
+- ECharts 只消费页面已经取得的业务数据，不负责访问数据库、执行 SQL 或做权限判断。
+- `page react-*` 页面与 `project create` 微前端模板是不同运行环境；前者不得因为模板示例使用了包装库，就引入白名单外依赖。
+- 图表查询使用 Dataset、`client.sql.execute({ sqlCode, params })` 或受控 BFF，并完整处理加载、空态、失败和重试行为。
+
 ## 页面开发参考
 
 编写页面内容前，先阅读 [`generation-standards.md`](../knowledge/react-page/generation-standards.md)。

package/skills/rabetbase/guides/sql-creation-workflow.md

@@ -6,10 +6,12 @@
 
 平台是唯一 source of truth。团队长期维护 SQL 时，优先使用 **本地同步工作流**：`sql create / pull / status / push / delete` + `.rabetbase/sql.lock.json`。
 
+SQL 内容编写、参数绑定与 MyBatis 语法以 [`sql-mybatis.md`](sql-mybatis.md) 为准。页面和 BFF 执行已发布的 Custom SQL 时使用 `sqlCode` + `params`。
+
 ## 工作流
 
 ```
-确认需求 → [按需]查现有 SQL → 校验字段 → 拉/落本地（pull/new）→ 编辑本地文件 → [建议]validate → status → push/delete → detail/exec 验证
+确认需求 → [按需]查现有 SQL → 校验字段 → 拉/落本地（pull/create）→ 编辑本地文件 → [建议]validate → status → push/delete → detail/exec 验证
 ```
 
 ### 1. 确认需求
@@ -114,7 +116,7 @@ rabetbase sql push --sqlcode <sqlCode> --dry-run --format json
 确认无误后正式执行：
 
 ```bash
-rabetbase sql push --sqlcode <sqlCode> --yes --format json
+rabetbase sql push --sqlcode <sqlCode> --format json
 ```
 
 补充规则：

package/skills/rabetbase/guides/sql-mybatis.md

@@ -42,11 +42,11 @@
 * **用途**：确认当前本地文件是否被识别为 `modified` / `added` / `missing` / `unchanged`。
 * **动作**：若状态与预期不符，先解释原因再继续，不要跳过状态检查直接推送。
 
-### 6. `rabetbase sql push --sqlcode xxx --dry-run|--yes --format json`
+### 6. `rabetbase sql push --sqlcode xxx [--dry-run] --format json`
 * **用途**：将同步目录中的本地文件上传到平台。
 * **动作**：
   * 先 `--dry-run` 看预览
-  * 再 `--yes` 正式执行
+  * 再移除 `--dry-run` 正式执行
 * **补充**：
   * 文件名变化会驱动远端 `sqlName` 更新
   * 文件移动到新的数据库目录时，会尝试按目录重绑 `dbId`

package/skills/rabetbase/knowledge/page-schema/YtPage.md

@@ -14,7 +14,7 @@ tags: [page, layout, page-schema]
 
 | 类型 | 判断条件 | 特点 | 场景 |
 |------|----------|------|------|
-| 磁贴布局 | 包含 `YtRglContainer` | 网格定位、支持并排 | 仪表盘、数据看板 |
+| 磁贴布局 | 包含 `YtRglContainer` | 网格定位、支持并排 | 多区域表单、列表与详情组合 |
 | 流式布局 | 无 `YtRglContainer` | 上下排列 | 表单页、详情页 |
 
 ---
@@ -56,7 +56,6 @@ tags: [page, layout, page-schema]
 |------|------|
 | 每行总宽度 | 必须为 12 |
 | Filter/Table | 必须独占一行（w: 12） |
-| 图表并排 | 两个图表各占 w: 6 |
 
 ---
 
@@ -83,31 +82,6 @@ tags: [page, layout, page-schema]
 
 ## 常见布局场景
 
-### 并排图表
-
-```json
-{
-  "RGLlayout": [
-    {"i": "chart1", "w": 6, "h": 20, "x": 0, "y": 0},
-    {"i": "chart2", "w": 6, "h": 20, "x": 6, "y": 0}
-  ]
-}
-```
-
-### 统计卡 + 图表
-
-```json
-{
-  "RGLlayout": [
-    {"i": "stat1", "w": 3, "h": 10, "x": 0, "y": 0},
-    {"i": "stat2", "w": 3, "h": 10, "x": 3, "y": 0},
-    {"i": "stat3", "w": 3, "h": 10, "x": 6, "y": 0},
-    {"i": "stat4", "w": 3, "h": 10, "x": 9, "y": 0},
-    {"i": "chart1", "w": 12, "h": 20, "x": 0, "y": 10}
-  ]
-}
-```
-
 ### Filter + Table
 
 ```json
@@ -151,19 +125,11 @@ tags: [page, layout, page-schema]
     "componentName": "YtRglContainer",
     "props": {
       "RGLlayout": [
-        {"i": "node_stat1", "w": 3, "h": 8, "x": 0, "y": 0},
-        {"i": "node_stat2", "w": 3, "h": 8, "x": 3, "y": 0},
-        {"i": "node_stat3", "w": 3, "h": 8, "x": 6, "y": 0},
-        {"i": "node_stat4", "w": 3, "h": 8, "x": 9, "y": 0},
-        {"i": "node_filter", "w": 12, "h": 10, "x": 0, "y": 8, "autoHeight": true},
-        {"i": "node_table", "w": 12, "h": 30, "x": 0, "y": 18}
+        {"i": "node_filter", "w": 12, "h": 10, "x": 0, "y": 0, "autoHeight": true},
+        {"i": "node_table", "w": 12, "h": 30, "x": 0, "y": 10}
       ]
     },
     "children": [
-      {"id": "node_stat1", "componentName": "LrSmartStatistic"},
-      {"id": "node_stat2", "componentName": "LrSmartStatistic"},
-      {"id": "node_stat3", "componentName": "LrSmartStatistic"},
-      {"id": "node_stat4", "componentName": "LrSmartStatistic"},
       {"id": "node_filter", "componentName": "LrSmartFilter"},
       {"id": "node_table", "componentName": "LrSmartTable"}
     ]

package/skills/rabetbase/knowledge/react-page/generation-standards.md

@@ -23,6 +23,7 @@
 | 路由     | 使用 `navigate` 跳转、使用 `location` 读取地址，不使用 `window.location`                                                  |
 | 样式     | 使用 Ant Design CSS 变量，不写死颜色或其他样式常量                                                                        |
 | 数据访问 | `client` 支持当前页面可用的全部 `@lovrabet/sdk` 能力，先确认数据集、SQL 或 BFF 的事实与 SDK 调用方式，再使用 `client` |
+| 图表     | 使用 `echarts@5` 构建图表、统计卡片与数据大屏；ECharts 只负责呈现，不承担数据访问或权限判断                         |
 
 ### 依赖白名单（严格）
 
@@ -97,10 +98,18 @@ export default App;
 | 方式 | 优先考虑的场景 | 使用边界 |
 | --- | --- | --- |
 | 单一数据集请求 | 只涉及一个数据集的列表查询、详情读取、分页、筛选、创建、更新或删除，且业务逻辑主要由数据集模型能力完成 | 优先使用 API-doc 中确认过的 `client.models` 方法；不要为简单的数据集操作改用 SQL 或 BFF，也不要猜测未在 API-doc 中出现的字段和参数 |
-| 自定义 SQL | 需要一次查询组合多个数据集，或需要数据库完成明确的关联、聚合、分组、排序、计算和复杂筛选 | 先确认 SQL 资源、参数和实际返回结构，再按 SDK 规范调用；不要在页面中拼接 SQL、把 SQL 当作通用业务逻辑容器，或据 CLI 的 `data.rows` 推断运行时返回值 |
-| BFF | 需要在数据操作生命周期中注入业务校验、转换、加密、条件分支、多步编排，或需要调用外部服务 | 将这类业务逻辑放在已确认的 BFF 中，由页面通过 SDK 调用；不要用 BFF 包装本可直接完成的简单 CRUD，也不要在页面中实现应由 BFF 负责的敏感逻辑 |
+| Custom SQL | 需要一次查询组合多个数据集，或需要数据库完成明确的关联、聚合、分组、排序、计算和复杂筛选 | 先复用或按 SQL 工作流创建、校验并发布 Custom SQL，再通过 `client.sql.execute({ sqlCode, params })` 调用；不要在页面中拼接 SQL、把 SQL 当作通用业务逻辑容器，或据 CLI 的 `data.rows` 推断运行时返回值 |
+| BFF | 需要基于当前用户、角色、数据范围或业务规则额外鉴权，或需要转换、加密、条件分支、多步编排和外部服务 | 将校验与业务逻辑放在已确认的 BFF 中，由页面通过 SDK 调用；前端只传业务参数，BFF 内按需执行已发布的 Custom SQL；不要用 BFF 包装本可直接完成的简单查询 |
 
-选择顺序：先判断单一数据集请求是否能直接满足需求；仅在数据组合或数据库计算是主要问题时使用自定义 SQL；当核心问题是业务规则、数据处理流程或外部服务协同时使用 BFF。三种方式的具体方法、参数、返回值和异常形态，均以当前资源事实和 `@lovrabet/sdk` 使用规范为准。
+选择顺序：先判断单一数据集请求是否能直接满足需求；仅在数据组合或数据库计算是主要问题时使用 Custom SQL；当当前用户、角色、数据范围或业务规则需要额外控制时使用 BFF。三种方式的具体方法、参数、返回值和异常形态，均以当前资源事实和 `@lovrabet/sdk` 使用规范为准。
+
+页面和 BFF 通过已发布 Custom SQL 的 `sqlCode` + `params` 执行查询。执行失败时保留并报告原始错误，根据 SQL 资源状态、参数与权限定位问题。
+
+### 图表与统计页面
+
+- 使用 `echarts@5` 构建图表、统计卡片和数据大屏，复用 React 组件生命周期管理图表实例。
+- ECharts option 只负责数据映射与呈现，数据通过 Dataset、已发布的 Custom SQL 或受控 BFF 获取。
+- ECharts 不做权限判断；需要额外用户、角色或数据范围控制时由 BFF 承担。
 
 ### 国际化与样式
 
@@ -161,11 +170,13 @@ const client = useSdkClient();
 
 - 数据集模型调用（如 `models.<dataset>`）的调用标识、方法、参数、返回值和异常形态，严格以当前数据集的 API-doc 返回文档为准，不得自行推测或自由发挥
 - SQL、BFF 及其他非数据集能力的可用方法、参数、返回值和异常形态，均以 `@lovrabet/sdk` 的使用规范为准
+- 页面通过已发布 Custom SQL 的 `sqlCode` + `params` 执行查询
 - 页面调用 SQL 前，先用 `rabetbase sql list` 与 `rabetbase sql detail --sqlcode <sqlCode>` 确认目标资源
 - 生成使用自定义 SQL 的页面代码前，使用代表性参数执行 `rabetbase sql exec --sqlcode <sqlCode> --params <json> --format json`。若返回 `data.error`，先解决执行错误；成功后再根据 `data.rows` 与 `data.rowCount` 确认实际数据结构
 - `sql exec` 仅用于确认 SQL 可执行及返回数据结构。页面代码按 `@lovrabet/sdk` 的使用规范处理 `client.sql` 的返回值，不使用 CLI 输出字段 `data.rows`
 - 页面调用 BFF 前，先用 `rabetbase bff list` 与 `rabetbase bff detail --id <id>` 确认目标资源
 - 数据操作需要注入自定义业务逻辑，例如校验、转换或加密时，优先考虑使用 BFF；页面运行时通过 `client` 按 `@lovrabet/sdk` 规范调用已确认的 BFF
+- Dataset、Custom SQL 或 BFF 执行失败时保留并报告原始错误，根据资源状态、参数与权限定位问题
 - CLI 只用于读取 SQL 与 BFF 的资源事实，页面运行时仍通过 `client` 调用，不在页面中拼接 CLI 命令或平台接口
 - 不在文档中出现的 dataset 字段、参数名、返回形态、方法名不得猜测
 - `client` 只是页面内可直接调用的入口，页面侧不在本地重新创建 `createClient` 或重复注册模型

package/skills/rabetbase/references/rabetbase-app-config.md

@@ -11,7 +11,7 @@ rabetbase app-config list --format compress
 rabetbase app-config get <key> --format compress
 rabetbase app-config get <key> --reveal --format compress
 rabetbase app-config set <key> --from-env ENV_NAME --dry-run
-rabetbase app-config set <key> --from-env ENV_NAME --yes
+rabetbase app-config set <key> --from-env ENV_NAME
 rabetbase app-config delete <key> --dry-run
 rabetbase app-config delete <key> --yes
 ```
@@ -66,7 +66,7 @@ rabetbase app-config set vectorengine.apiKey --file ./secret.txt --dry-run
 确认 dry-run 的 `operation`、`selector.appCode`、`selector.key`、`before`、`after` 后，再执行正式写入：
 
 ```bash
-rabetbase app-config set vectorengine.apiKey --from-env VECTORENGINE_API_KEY --yes
+rabetbase app-config set vectorengine.apiKey --from-env VECTORENGINE_API_KEY
 ```
 
 显式位置参数 `<value>` 可用，但不推荐用于敏感值，因为 shell history 可能记录明文。

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

@@ -2,15 +2,15 @@
 
 把本地 BFF 脚本上传到远端。
 
-> **风险等级：high-risk-write** — 必须显式 `--yes`。
+> **风险等级：write** — 建议先使用 `--dry-run` 预览。
 
 ## 命令
 
 ```bash
-rabetbase bff push --yes --format json
-rabetbase bff push --yes --type ENDPOINT --name getUserList --format json
+rabetbase bff push --format json
+rabetbase bff push --type ENDPOINT --name getUserList --format json
 rabetbase bff push --type ENDPOINT --name getUserList --dry-run --format json
-rabetbase bff push --yes --type HOOK --name beforeFilter --format json
+rabetbase bff push --type HOOK --name beforeFilter --format json
 ```
 
 ## 参数
@@ -21,7 +21,6 @@ rabetbase bff push --yes --type HOOK --name beforeFilter --format json
 | `--name <name>` | string | 否 | — | 仅推指定函数名；传时必须搭配 `--type` |
 | `--force` | boolean | 否 | — | 忽略 hash 保护强制推送 |
 | `--dry-run` | boolean | 否 | — | 仅预览将要推送的本地脚本 |
-| `--yes` | boolean | 是 | — | 跳过高风险确认 |
 | `--format <fmt>` | string | 否 | `pretty` | 输出格式 |
 
 ## 输出

package/skills/rabetbase/references/rabetbase-bff-save.md

@@ -7,7 +7,7 @@
 > - 本地创建：`rabetbase bff create`
 > - 查看状态：`rabetbase bff status`
 > - 预览上传：`rabetbase bff push --dry-run`
-> - 推送远端：`rabetbase bff push --yes`
+> - 推送远端：`rabetbase bff push`
 > - 拉取远端：`rabetbase bff pull`
 > - 删除脚本：`rabetbase bff delete --yes --target ...`
 
@@ -27,7 +27,7 @@ rabetbase bff save --file ./scripts/getUserInfo.js --name getUserInfo --format j
 rabetbase bff create --type ENDPOINT --name getUserInfo --format json
 # 编辑 .rabetbase/bff/<appCode>/ENDPOINT/getUserInfo.js
 rabetbase bff push --dry-run --format json
-rabetbase bff push --yes --format json
+rabetbase bff push --format json
 ```
 
 ### 旧“更新已有脚本”
@@ -45,7 +45,7 @@ rabetbase bff pull --format json
 # 编辑同步目录中的本地文件
 rabetbase bff status --format json
 rabetbase bff push --dry-run --format json
-rabetbase bff push --yes --format json
+rabetbase bff push --format json
 ```
 
 ## Agent 规则

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

@@ -87,7 +87,7 @@ CLI 对旧版顶层 `appcode` 仍兼容读取，但它已经不是推荐主模
 }
 ```
 
-每个 app profile 可单独覆盖普通顶层字段。`riskLevel` 是安全例外：默认值为 `high-risk-write`，全局、项目、profile 与环境变量都作为 ceiling，最终取最严格值。CLI 运行时根据 `--app <name>` 或 `defaultApp` 选择激活的 profile。
+每个 app profile 可单独覆盖普通顶层字段。`riskLevel` 是安全例外：默认值为 `write`，全局、项目与 profile 决定基础上限并取最严格值；环境变量只能继续收紧，不能提权。CLI 运行时根据 `--app <name>` 或 `defaultApp` 选择激活的 profile。权限不足时只能提醒用户手动编辑配置；Agent 和自动化脚本不得自行修改 `riskLevel` 或尝试提权。
 
 管理命令（声明式 flags，非位置参数）：
 
@@ -112,7 +112,7 @@ rabetbase workspace remove product --yes
 | `accessKey` | string | — | Access Key 认证（预留，未来替代 cookie） |
 | `format` | string | — | 默认输出格式。可选值：`json`、`pretty`、`compress`。不设则命令默认 `compress` |
 | `pageSize` | number | — | 默认分页大小，用于 `sql list` 等分页命令 |
-| `riskLevel` | string | `"high-risk-write"` | 允许执行的最高风险等级。可选值：`read`、`write`、`high-risk-write`。兼容旧名 `maxRisk` |
+| `riskLevel` | string | `"write"` | 允许执行的最高风险等级。可选值：`read`、`write`、`high-risk-write`。兼容旧名 `maxRisk` |
 | `inherit` | boolean | 省略 | 配置继承模式。**省略**（默认）：项目主导，仅从全局白名单继承 cookie/accessKey/locale/format/riskLevel/pageSize，不继承 apps/defaultApp/appcode。**`true`**：全量合并全局+项目（旧行为，需显式开启）。**`false`**：普通字段完全隔离；全局 `riskLevel` 仍作为不可绕过的上限 |
 | `apiDir` | string | `"./src/api"` | `api pull` 生成代码的输出目录 |
 | `template_base_url` | string | 平台默认 CDN | 模板 CDN 基础 URL，一般无需修改 |

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

@@ -70,7 +70,7 @@ rabetbase db analyze-status --id 10157 --plan <traceId> --format compress
 
 必须按 `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` 没有明确返回 `data.planId`，停止自动推进且不得盲目重试，因为请求结果可能不确定。全部批次结束后按 `db detail.tableCount` 的 200 表阈值决定直接读取或先执行 `db diff-refresh-start/status`，再执行完整 `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` 的全量分析不受此保护影响。
 
@@ -101,7 +101,7 @@ rabetbase db analyze-status --id 10157 --plan <traceId> --format compress
 | `data.totalElapsedMs` | 从 `firstStartTime` 到 `endTime` 或当前查询时刻的 plan 墙钟耗时；缺少可靠时间戳时为 `null` |
 | `data.hasMultipleAttempts` | `firstStartTime` 与 `startTime` 都有效且不相同时为 `true`，表示服务端开启过后续执行尝试 |
 
-`PENDING / RUNNING / RETRYING / CANCELING` 与未知状态都不是终态。不要根据 `failedTables`、`retryCount` 或错误文案推测状态。`PARTIAL_SUCCESS` 只表示任务已到终态；必须复跑 `db diff --all --changed-only` 验证目标差异收敛，才能得出本轮分析完成结论。
+`PENDING / RUNNING / RETRYING / CANCELING` 与未知状态都不是终态。不要根据 `failedTables`、`retryCount` 或错误文案推测状态。`PARTIAL_SUCCESS` 只表示任务已到终态；必须按 200 表阈值刷新或直接复跑 `db diff --all --changed-only` 验证目标差异收敛，才能得出本轮分析完成结论。
 
 `analyze-status` 每次只查询一次。轮询时必须继续使用当前任务的同一 `planId`；查询超时、断网或临时 API 失败不等于分析失败，也不得触发新的 `analyze-start`。当前稳定任务状态中没有独立的 `TIMEOUT` 终态。
 

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

@@ -5,6 +5,7 @@
 ## 何时用
 
 - 已用 `db list` 拿到 `id`，需要比列表更全的字段
+- 读取 `tableCount`，按 200 张表阈值决定是否先刷新差异结果
 - 需要当前 **`latestAnalysisTraceId`** 查询最新分析状态；取消已知任务时仍使用正在跟踪的原 planId
 
 ## 命令
@@ -23,5 +24,7 @@ rabetbase db detail --id 10157 --format compress
 
 ## 参考
 
+输出中的 `tableCount` 是当前连接表数量：不大于 200 时通常直接读取 `db diff`；大于 200 时建议先执行 `db diff-refresh-start/status`。字段缺失时不猜测数量，也不隐式刷新。
+
 - [database-connection-workflow.md](../guides/database-connection-workflow.md)
 - [SKILL.md](../SKILL.md)

package/skills/rabetbase/references/rabetbase-db-diff-refresh.md

@@ -0,0 +1,53 @@
+# db diff-refresh-start / diff-refresh-status
+
+显式刷新服务端数据库表差异结果。`diff-refresh-start` 为 **write**，只提交一次异步任务；`diff-refresh-status` 为 **read**，只查询一次指定 `traceId`。
+
+## 何时刷新
+
+- `db detail` 返回 `tableCount > 200`，读取差异前建议刷新。
+- 用户明确要求“实时刷新”或“强制刷新”，无论表数量多少都刷新。
+- `tableCount <= 200` 时服务端通常实时计算差异，默认不刷新。
+
+刷新只影响默认 `db diff` 差异视角；`db diff --view all` 本身就是实时全表分页，不需要先刷新差异快照。
+
+## 命令
+
+```bash
+rabetbase db diff-refresh-start --id 10157 --format compress
+rabetbase db diff-refresh-status --id 10157 --plan <traceId> --format compress
+```
+
+## 执行规则
+
+1. `diff-refresh-start` 只执行一次并保存 `data.traceId`。
+2. 若响应没有明确 `traceId`，结果未知，停止且不得自动重提。
+3. `PENDING / RUNNING / RETRYING` 时继续执行 `data.query.command`，始终查询同一个 traceId。
+4. `SUCCESS` 时执行 `data.lookup.command`，重新读取刷新后的差异结果。
+5. `FAILED / CANCELLED` 为失败终态；报告 `data.status.errorMsg`，不得自动重启。
+6. 未知状态不是终态，停止自动推进或继续只读查询，不猜测成功。
+
+## 输出
+
+`diff-refresh-start`：
+
+- `data.dbLinkId`
+- `data.traceId`
+- `data.status`
+- `data.query.command`
+
+`diff-refresh-status`：
+
+- `data.status`：服务端原始任务事实
+- `data.knownStatus`：是否属于已知运行态或终态；未知时为 `false` 且不提供自动查询命令
+- `data.isTerminal`
+- `data.isSuccessful`
+- `data.query`：非终态时的同 traceId 查询命令
+- `data.lookup`：仅成功时返回的 `db diff --all --changed-only` 命令
+
+差异刷新任务与 schema 分析任务不是同一业务动作。不要用 `diff-refresh-start` 代替 `analyze-start`，也不要把刷新成功描述为数据集分析已经完成。
+
+## 参考
+
+- [db diff](rabetbase-db-diff.md)
+- [database-connection-workflow.md](../guides/database-connection-workflow.md)
+- [SKILL.md](../SKILL.md)