@lovrabet/rabetbase-cli 2.4.3 → 2.4.4

package/lib/utils/with-active-cookie.js

@@ -1 +1 @@
-(function(_0x34037,_0x39adc8){var _0x2aba10=a292_0x5b51,_0x18f0c0=_0x34037();while(!![]){try{var _0x14f89e=-parseInt(_0x2aba10(0x105))/0x1*(parseInt(_0x2aba10(0x108))/0x2)+-parseInt(_0x2aba10(0x104))/0x3*(-parseInt(_0x2aba10(0x106))/0x4)+-parseInt(_0x2aba10(0x109))/0x5*(-parseInt(_0x2aba10(0x10b))/0x6)+-parseInt(_0x2aba10(0x10a))/0x7*(-parseInt(_0x2aba10(0x107))/0x8)+parseInt(_0x2aba10(0xff))/0x9*(-parseInt(_0x2aba10(0x100))/0xa)+-parseInt(_0x2aba10(0x102))/0xb+-parseInt(_0x2aba10(0x101))/0xc*(-parseInt(_0x2aba10(0x103))/0xd);if(_0x14f89e===_0x39adc8)break;else _0x18f0c0['push'](_0x18f0c0['shift']());}catch(_0x4bdb36){_0x18f0c0['push'](_0x18f0c0['shift']());}}}(a292_0x3d8a,0x36b15));import{setActiveCookie,clearActiveCookie}from'../core/api-client.js';function a292_0x5b51(_0x1a36b7,_0xa4038c){_0x1a36b7=_0x1a36b7-0xff;var _0x3d8a07=a292_0x3d8a();var _0x5b5111=_0x3d8a07[_0x1a36b7];return _0x5b5111;}function a292_0x3d8a(){var _0x1ee5ef=['369yamOsH','1WyUpzi','6848QCdiLd','386200omNFQz','725446jhOXZI','762145ygcmlv','28BRWifM','12kcYqyK','31905GvfrzV','960wTvQmy','7784844Ohxfcm','4732277wuFfuo','13bOEXMT'];a292_0x3d8a=function(){return _0x1ee5ef;};return a292_0x3d8a();}export async function withActiveCookie(_0x52613c,_0x3e5551){setActiveCookie(_0x52613c);try{return await _0x3e5551();}finally{clearActiveCookie();}}
+(function(_0x299776,_0x2b50ab){var _0x46bbf2=a299_0x1642,_0x4f2c8a=_0x299776();while(!![]){try{var _0x317665=parseInt(_0x46bbf2(0xea))/0x1+parseInt(_0x46bbf2(0xf0))/0x2+-parseInt(_0x46bbf2(0xed))/0x3*(parseInt(_0x46bbf2(0xef))/0x4)+parseInt(_0x46bbf2(0xee))/0x5+parseInt(_0x46bbf2(0xe9))/0x6+parseInt(_0x46bbf2(0xf1))/0x7+parseInt(_0x46bbf2(0xeb))/0x8*(-parseInt(_0x46bbf2(0xec))/0x9);if(_0x317665===_0x2b50ab)break;else _0x4f2c8a['push'](_0x4f2c8a['shift']());}catch(_0x4c8043){_0x4f2c8a['push'](_0x4f2c8a['shift']());}}}(a299_0x9efd,0xd3847));function a299_0x1642(_0x56bbe9,_0x103afe){_0x56bbe9=_0x56bbe9-0xe9;var _0x9efd36=a299_0x9efd();var _0x1642d9=_0x9efd36[_0x56bbe9];return _0x1642d9;}import{setActiveCookie,clearActiveCookie}from'../core/api-client.js';export async function withActiveCookie(_0x157e49,_0x38760b){setActiveCookie(_0x157e49);try{return await _0x38760b();}finally{clearActiveCookie();}}function a299_0x9efd(){var _0x39ac97=['341128jDkzTq','819cGbyJU','2011821wDWRPm','4380720IaHuCg','4MFupJA','3364112KFXleB','6747937kqpblV','6038328McvctF','888734IVJChs'];a299_0x9efd=function(){return _0x39ac97;};return a299_0x9efd();}

package/lib/utils/write-cli-side-channel.js

@@ -1 +1 @@
-function a293_0x3105(_0x29f4b7,_0x552f7a){_0x29f4b7=_0x29f4b7-0x149;var _0x15b70b=a293_0x15b7();var _0x3105c7=_0x15b70b[_0x29f4b7];return _0x3105c7;}(function(_0x5b58fd,_0x10d06b){var _0x45c9dd=a293_0x3105,_0x4d4e2b=_0x5b58fd();while(!![]){try{var _0x4784d2=parseInt(_0x45c9dd(0x153))/0x1+-parseInt(_0x45c9dd(0x14f))/0x2*(-parseInt(_0x45c9dd(0x154))/0x3)+parseInt(_0x45c9dd(0x152))/0x4+parseInt(_0x45c9dd(0x155))/0x5+-parseInt(_0x45c9dd(0x14a))/0x6*(-parseInt(_0x45c9dd(0x150))/0x7)+parseInt(_0x45c9dd(0x14c))/0x8*(parseInt(_0x45c9dd(0x14d))/0x9)+-parseInt(_0x45c9dd(0x14e))/0xa*(parseInt(_0x45c9dd(0x151))/0xb);if(_0x4784d2===_0x10d06b)break;else _0x4d4e2b['push'](_0x4d4e2b['shift']());}catch(_0x2b9491){_0x4d4e2b['push'](_0x4d4e2b['shift']());}}}(a293_0x15b7,0x89a82));export function writeCliSideChannelLine(_0x49f44a){var _0x5c8aa9=a293_0x3105;process[_0x5c8aa9(0x14b)][_0x5c8aa9(0x149)](_0x49f44a+'\x0a');}function a293_0x15b7(){var _0x245d5e=['63GcDAeE','8575390vMCrpx','148NVfcSx','577199oYitML','22aRsTTx','3477252fqxLnw','333670RyiQEn','9117BjYQAL','905445VblMPb','write','30luiyXb','stderr','294488oUimvK'];a293_0x15b7=function(){return _0x245d5e;};return a293_0x15b7();}
+function a300_0x3e24(_0x1b1bfc,_0x4183e2){_0x1b1bfc=_0x1b1bfc-0x1ba;var _0x43799e=a300_0x4379();var _0x3e245b=_0x43799e[_0x1b1bfc];return _0x3e245b;}(function(_0x36c898,_0x4a4ba7){var _0x2e3bf5=a300_0x3e24,_0x43b8b5=_0x36c898();while(!![]){try{var _0xda82ce=-parseInt(_0x2e3bf5(0x1c0))/0x1*(parseInt(_0x2e3bf5(0x1ba))/0x2)+parseInt(_0x2e3bf5(0x1bf))/0x3+-parseInt(_0x2e3bf5(0x1c2))/0x4+parseInt(_0x2e3bf5(0x1c1))/0x5+parseInt(_0x2e3bf5(0x1bb))/0x6*(-parseInt(_0x2e3bf5(0x1bd))/0x7)+-parseInt(_0x2e3bf5(0x1be))/0x8+parseInt(_0x2e3bf5(0x1c3))/0x9*(parseInt(_0x2e3bf5(0x1bc))/0xa);if(_0xda82ce===_0x4a4ba7)break;else _0x43b8b5['push'](_0x43b8b5['shift']());}catch(_0xee0844){_0x43b8b5['push'](_0x43b8b5['shift']());}}}(a300_0x4379,0xea9d2));export function writeCliSideChannelLine(_0xda8c1c){process['stderr']['write'](_0xda8c1c+'\x0a');}function a300_0x4379(){var _0x4a9b8=['2370342zYtdHf','1nkUfqO','1670050eZMoZG','1306928kJzBCh','667971rcudWI','1281910NyhHpz','65388MhyipS','370VLFkBO','1057MxaeIe','2367712CtVpIN'];a300_0x4379=function(){return _0x4a9b8;};return a300_0x4379();}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lovrabet/rabetbase-cli",
-  "version": "2.4.3",
+  "version": "2.4.4",
   "description": "Developer CLI for Lovrabet apps, datasets, pages, SQL, BFF, database connections, skills, and AI agent workflows.",
   "license": "SEE LICENSE IN LICENSE",
   "keywords": [
@@ -83,7 +83,9 @@
     "skills/rabetbase",
     "skills/rabetbase.manifest.json",
     "scripts/postinstall.mjs",
-    "templates",
+    "templates/generate-api",
+    "templates/rules",
+    "templates/skill",
     "sidecar",
     "README.md",
     "LICENSE"
@@ -100,18 +102,21 @@
     "ora": "^9.3.0",
     "prettier": "^3.6.2",
     "semver": "^7.7.3",
-    "winston": "^3.17.0"
+    "winston": "^3.17.0",
+    "yauzl": "3.4.0"
   },
   "devDependencies": {
     "@types/listr": "^0.14.9",
     "@types/node": "^24.5.2",
     "@types/semver": "^7.7.1",
+    "@types/yauzl": "2.10.3",
     "@vitest/coverage-v8": "^3.2.4",
     "@vitest/ui": "^3.2.4",
     "c8": "^10.1.3",
     "javascript-obfuscator": "^5.4.1",
     "tsc-alias": "^1.8.10",
     "typescript": "5.9.3",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "yazl": "3.3.1"
   }
 }

package/skills/rabetbase/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: rabetbase
-version: 2.4.3
-description: "Lovrabet 开发工作流 CLI — 通过 rabetbase 命令管理数据集、数据库连接（dblink）、智能列表页（Smart List Page）、React 自定义页面（JSX 页面）、SQL 查询、BFF 脚本、通知配置、菜单事实读取与同步、应用文件、OCR 识别、代码生成，以及平台问题上报。触发词：数据集、数据表、dataset relation-audit、dataset delete、dataset restore、废弃数据集、恢复数据集、dataset rename、dataset field-update、dataset extend-update、dataset business-group-update、businessGroup、字段对象更新、doType、options、智能列表页、Smart List Page、React 自定义页面、JSX 页面、page react-create、page react-list、page react-detail、page react-update、page react-publish、page generate-start、page generate-status、page relation-audit、page sync、page pull、page push、page restore、恢复已删除页面、dblink、数据库连接、schema 分析、db list、db detail、db test、db tables、db diff、db diff --table、db analyze-batch-plan、db analyze-start、analyze-cancel、analyze-status、traceId、自定义 SQL、sql.execute、bff.execute、BF 消息通知、BFF 消息通知、Backend Function 消息通知、notification config-list、EMAIL configCode、通知配置、notification.send、get_dataset_detail、validate_sql_content、save_or_update_custom_sql、@lovrabet/sdk、lovrabet 开发、rabetbase、filter、codegen、init、appcode、app list、app members-list、tenant members-list、应用人员列表、租户人员列表、workspace、workspace init、workspace use、workspace add、workspace remove、多应用、默认应用、menu list、menu external-link-create、menu external-link-update、menu rename、菜单改名、外链菜单创建、外链 URL 更新、菜单异常审计、菜单手动删除清单、menu sync、menu asset-update、菜单资源更新、menu move、菜单移动、角色、用户组、权限、role、permit、role list、role create、role user-add、role user-remove、user-resolve、销售组、加入开发者、page-set、page-get、row-roles、SELF、ALL、行级权限、role-menus-set、role-apis-set、菜单权限、API 权限、DEV、CUSTOM、project create、project upgrade、schema、jq、compress、file upload、file query-url、ocr recognize、文件上传、OCR 识别、发票识别、图片识别、长期链接、issue report、平台问题、platform issue、问题上报、user-account dingding-sandbox-bind、钉钉沙箱账号绑定。"
+version: 2.4.4
+description: "Lovrabet 开发工作流 CLI — 通过 rabetbase 命令管理数据集、数据库连接（dblink）、智能列表页（Smart List Page）、React 自定义页面（JSX 页面）、SQL 查询、BFF 脚本、通知配置、菜单事实读取与同步、应用文件、OCR 识别、代码生成，以及平台问题上报。触发词：数据集、数据表、dataset relation-audit、dataset delete、dataset restore、废弃数据集、恢复数据集、dataset rename、dataset field-update、dataset extend-update、dataset business-group-update、businessGroup、字段对象更新、doType、options、智能列表页、Smart List Page、React 自定义页面、JSX 页面、page react-create、page react-list、page react-detail、page react-update、page react-publish、page generate-start、page generate-status、page relation-audit、page sync、page pull、page push、page restore、恢复已删除页面、dblink、数据库连接、schema 分析、db list、db detail、db test、db tables、db diff、db diff --view all、db diff-refresh-start、db diff-refresh-status、db analyze-batch-plan、db analyze-start、analyze-cancel、analyze-status、traceId、自定义 SQL、sql.execute、bff.execute、BF 消息通知、BFF 消息通知、Backend Function 消息通知、notification config-list、EMAIL configCode、通知配置、notification.send、get_dataset_detail、validate_sql_content、save_or_update_custom_sql、@lovrabet/sdk、lovrabet 开发、rabetbase、filter、codegen、init、appcode、app list、app members-list、tenant members-list、应用人员列表、租户人员列表、workspace、workspace init、workspace use、workspace add、workspace remove、多应用、默认应用、menu list、menu external-link-create、menu external-link-update、menu rename、菜单改名、外链菜单创建、外链 URL 更新、菜单异常审计、菜单手动删除清单、menu sync、menu asset-update、菜单资源更新、menu move、菜单移动、角色、用户组、权限、role、permit、role list、role create、role user-add、role user-remove、user-resolve、销售组、加入开发者、page-set、page-get、row-roles、SELF、ALL、行级权限、role-menus-set、role-apis-set、菜单权限、API 权限、DEV、CUSTOM、project create、project upgrade、schema、jq、compress、file upload、file query-url、ocr recognize、文件上传、OCR 识别、发票识别、图片识别、长期链接、issue report、平台问题、platform issue、问题上报、user-account dingding-sandbox-bind、钉钉沙箱账号绑定。"
 metadata:
   requires:
     bins: ["rabetbase"]
@@ -43,8 +43,9 @@ metadata:
 1. **判断需求类型**
    - Instant API 标准数据记录操作 → SDK filter/getOne/create/batchCreate/update/delete；批量更新使用 `update({ id: [...] })`，不存在 `batchUpdate()`
    - 简单聚合且数据集是 DB_TABLE → SDK aggregate；聚合列用 `aggregate[].column`，不要用旧别名 `field`
-   - 复杂 JOIN / 数据库函数且数据集是 DB_TABLE → 自定义 SQL
-   - 外部系统调用 / 跨表事务 / 复杂业务编排 → BFF；BFF HOOK 可挂 DB_TABLE 或 METADATA，具体 operation 以后端返回为准
+   - 复杂 JOIN / 数据库函数且数据集是 DB_TABLE → Custom SQL
+   - 图表、统计卡片或数据大屏 → React 自定义页面 + ECharts；数据层根据查询复杂度选择 Dataset 或 Custom SQL
+   - 当前用户、角色、数据范围、外部系统、跨表事务或复杂业务编排 → BFF；BFF HOOK 可挂 DB_TABLE 或 METADATA，具体 operation 以后端返回为准
 2. **先拿元数据，再写代码**
    - 至少先查 `rabetbase dataset detail --code xxx --format compress`（或 `json`）获取表结构
    - 跨表场景还需查目标表的结构
@@ -52,12 +53,16 @@ metadata:
    - 需要了解数据集关联关系时用 `rabetbase dataset relations --format compress`（或 `json`）；需要审计关系事实错误和人工复核项时用 `rabetbase dataset relation-audit --format compress`
    - 需要从文本需求创建新的 `METADATA` 数据集时，先读 [`dataset generate-start/status`](references/rabetbase-dataset-generate.md)，执行 preview 写出 design 文件，审阅后用 `generate-start --apply --design-file` 提交任务，再用 `generate-status` 查询到成功
    - **管理物理库连接 / 测连 / 同步表结构分析**时用 `rabetbase db …`（先 [`db list`](references/rabetbase-db-list.md)，trace/plan id 见 [`database-connection-workflow.md`](guides/database-connection-workflow.md)）
+   - DB 差异读取先用 `db detail` 获取 `tableCount`：不大于 200 时直接 `db diff --all --changed-only`；大于 200 或用户明确要求实时刷新时，先执行一次 `db diff-refresh-start`，保存 traceId 并用 `db diff-refresh-status` 查询同一任务到终态，成功后再读取 diff。用户明确不刷新时直接读取并提示大库结果可能滞后；数量未知时不隐式启动写任务
+   - 需要查看无差异表或主动重新分析既有表时，用 `db diff --view all`；`--all` 只表示聚合当前视角全部分页，不等价于全部表
    - DB 增量分析先对完整 `toAnalyzeTables` 执行 `db analyze-batch-plan`；它生成的是本地批次方案，不是服务端 `planId`，也不会创建任务。再严格按批次顺序启动；每批独立保存 `planId`（即 `analyze-start` 返回值），当前批次到达已知终态前不得启动下一批
-   - 全部批次结束后复跑完整 `db diff --all --changed-only`；仍未收敛时，按 [`database-connection-workflow.md`](guides/database-connection-workflow.md) 对剩余 `toAnalyzeTables` 逐表串行重试且每表只恢复一次。状态查询失败继续使用原 `planId`，不得重复启动任务
+   - 全部批次结束后按上述 200 表阈值重新获取差异；仍未收敛时，按 [`database-connection-workflow.md`](guides/database-connection-workflow.md) 对剩余 `toAnalyzeTables` 逐表串行重试且每表只恢复一次。状态查询失败继续使用原 `planId`，不得重复启动任务
    - 输出很大且只需子集时，在 `compress`/`json` 上加 `--jq '.data…'` 缩小结果
    - **（可选）** 若环境已安装 **`lovrabet` ≥ 2.0**，可用 `lovrabet data filter` / `data getOne` 对数据集做与 SDK 同语义的终端查数；**不要**假设用户已安装或版本够新，见 [`guides/data-api-guidelines.md`](guides/data-api-guidelines.md)
 3. **SQL 工作流严格分步**
    - 推荐路径：查现有(`sql list/detail`) 或新建(`sql create`) → 拉/落本地(`sql pull` / `sql create`) → 编辑同步目录文件 → 可选校验(`sql validate`) → 检查状态(`sql status`) → 先预览(`sql push --dry-run` / `sql delete --dry-run`) → 再 `sql push` / `sql delete` → `sql detail` / `sql exec` 验证
+   - 先使用 `sql list/detail` 查找可复用的 Custom SQL；没有满足需求的资源时，按照 [`sql-creation-workflow.md`](guides/sql-creation-workflow.md) 与 [`sql-mybatis.md`](guides/sql-mybatis.md) 创建、校验、发布并验证
+   - 页面和 BFF 执行已发布的 Custom SQL 时使用 `sqlCode` + `params`
 4. **BFF 工作流严格分步**
    - 查现有 → 确认字段或通知配置 → 查公共函数 → 本地创建(`bff create`) → 检查状态(`bff status`) → 先预览(`--dry-run`) → 再拉取/推送/删除
    - 创建会发送消息通知的 BFF 时，先读取 [`backend-function.md`](guides/backend-function.md) 的“消息通知扩展”契约，再执行 [`rabetbase notification config-list --type EMAIL`](references/rabetbase-notification-config-list.md) 获取当前应用的 `configCode`；不得猜测渠道、收件人或把密钥写进脚本
@@ -65,6 +70,7 @@ metadata:
 5. **页面体系选择**
    - 智能标准页面（Smart List Page）是内置的基础表单、表格展示和常规数据操作页面，常规数据管理需求优先使用它
    - 仅当标准页面无法满足个性化布局、可视化、复杂交互或自定义页面结构时，才使用 React 自定义 JSX 页面
+   - 图表、统计卡片和数据大屏使用 React 自定义页面与白名单内的 ECharts
    - 页面体系不明确时，先向用户确认；不要为同一目标同时创建标准页面与 React 页面
 6. **智能列表页（Smart List Page，page）工作流**
    - 工作流判断先看 [`guides/page-development-workflow.md`](guides/page-development-workflow.md)
@@ -125,12 +131,13 @@ metadata:
 与 **`dataset`（数据集模型）** 的分工：**`db *`** 管平台登记的 **物理库连接（dblink）**、**测连**、**schema 分析任务**、**物理表清单与差异**；表字段、枚举以 **`dataset detail`** 为准，数据集关联关系优先以 **`dataset relations`** 为准，关系事实风险用 **`dataset relation-audit`**。
 
 - **入口**：先 [`db list`](references/rabetbase-db-list.md) 取 `id` 与 `latestAnalysisTraceId`（如有）。
-- **只读常用**：[`db detail`](references/rabetbase-db-detail.md)、[`db test`](references/rabetbase-db-test.md)、[`db tables`](references/rabetbase-db-tables.md)、[`db diff`](references/rabetbase-db-diff.md)（`--table` 为表名**子串**过滤，分页用 `--page` / `--pagesize`）。
+- **只读常用**：[`db detail`](references/rabetbase-db-detail.md)、[`db test`](references/rabetbase-db-test.md)、[`db tables`](references/rabetbase-db-tables.md)、[`db diff`](references/rabetbase-db-diff.md)。`db diff` 默认只读差异结果；`--view all` 才是实时全部表视角；`--all` 只聚合当前视角全部分页。
+- **差异刷新**：[`db diff-refresh-start/status`](references/rabetbase-db-diff-refresh.md)。先从 `db detail` 读取 `tableCount`；大于 200 或用户强制要求时刷新，小于等于 200 默认直接读取。刷新与 schema `analyze-*` 是两类任务，不得混用。
 - **分析任务**：`db analyze-batch-plan` / `analyze-start` / `analyze-cancel` / `analyze-status`（服务端 plan/trace 来源见下）。
 - **状态诊断边界**：`analyze-status` 的 `requestedAnalysis` 只还原原始提交范围；`hasMultipleAttempts=true` 只表示观察到多个执行尝试。不得据此推断尝试间连续性、实际执行范围或自动重启。
 - **增量分批**：先用本地只读的 `db analyze-batch-plan --id <id> --tables <清单>` 得到确定性批次及 `planningEstimate`；这里生成的是本地批次方案，不是服务端 `planId`，不会创建或预留任务。再逐批调用一次 `analyze-start`，读取真实 `planId` 与当前任务的 `serverEstimate`；每批独立保存其返回的 `planId`，同一 dblink 严格串行。两类估算都不得驱动超时、取消、重试、自动重启或状态判断，`PENDING / RUNNING / RETRYING / CANCELING` 均不得推进下一批。
 - **取消已有任务**：只使用正在跟踪的原 `planId` 执行 `analyze-cancel --plan <原 planId>`；取消分支不得调用 `analyze-start`，也不得用可能变化的 `latestAnalysisTraceId` 替换已知目标。
-- **失败恢复**：全部批次结束后以完整 `db diff --all --changed-only` 获取未收敛表，逐表串行执行 `analyze-start --tables <单表>`，每表只恢复一次；累计原因计数只作可能不完整的参考展示。Agent 可语义理解原始 `errorMsg` 辅助解释和建议，但两者都不驱动任务状态、重提任务或收敛判断。
+- **失败恢复**：全部批次结束后按 200 表阈值刷新或直接读取完整 `db diff --all --changed-only` 获取未收敛表，逐表串行执行 `analyze-start --tables <单表>`，每表只恢复一次；累计原因计数只作可能不完整的参考展示。Agent 可语义理解原始 `errorMsg` 辅助解释和建议，但两者都不驱动任务状态、重提任务或收敛判断。
 - **ER 图引导**：`db analyze-status` 终态成功后，检查并转述 `data.links.erPage`；若没有 `data.links`，补 `--appcode` 或进入已配置 app 的项目上下文后重查。
 - **写入**：[`db create`](references/rabetbase-db-create.md) / [`db update`](references/rabetbase-db-update.md) / [`db delete`](references/rabetbase-db-delete.md)（高危删连需确认）；`create`/`update` 支持 **`--dry-run`** 预览。`db create` 成功后返回连接信息与数据库连接页链接。
 - **横切流程与 trace/plan**：[`database-connection-workflow.md`](guides/database-connection-workflow.md)。**单命令细则**见 `references/rabetbase-db-*.md`（与仓库 `src/commands/db/` 一一对应）。
@@ -241,6 +248,8 @@ where 条件强制使用操作符：`$eq` `$ne` `$gte` `$lte` `$gt` `$lt` `$in`
 
 ### SQL 调用
 
+页面和 BFF 通过已发布 Custom SQL 的 `sqlCode` + `params` 执行查询。
+
 ```typescript
 const data = await client.sql.execute<MyRow>({
   sqlCode: "xxx",
@@ -251,6 +260,8 @@ if (data.execSuccess && data.execResult) {
 }
 ```
 
+React 页面需要图表时，使用 React 自定义页面 + ECharts 呈现；只读查询且平台 `sqlCode` 权限已经满足时可以直接调用上面已发布的 Custom SQL。需要基于当前用户、角色、数据范围或业务规则做额外控制时，页面改调 BFF，由 BFF 完成校验后再执行该 Custom SQL。执行失败时保留并报告原始错误，根据 SQL 资源状态、参数与权限定位问题。
+
 ### BFF 调用
 
 ```typescript
@@ -280,10 +291,10 @@ const result = await client.bff.execute<DashboardData>({
 | 创建新项目 | [`rabetbase project create`](references/rabetbase-project-create.md) | 支持 `--name` + `--appcode` 非交互 |
 | 从 lovrabet-cli 迁移 | [`rabetbase project upgrade`](references/rabetbase-project-upgrade.md) | 6 步自动迁移，`--yes` 跳过确认 |
 | 老项目翻新蓝图 / Legacy Application Blueprint | [`guides/legacy-application-blueprint-workflow.md`](guides/legacy-application-blueprint-workflow.md) | 先输出 `.rabetbase/blueprint/<appCode>/application-blueprint.md`，把老代码逻辑与 Dataset / Relations 绑定后再生成迁移 Backlog |
-| 运行 package.json 脚本 | [`rabetbase run <script>`](references/rabetbase-run.md) | `high-risk-write`；先审阅脚本命令体，独立 CLI 需人工提升风险上限并确认，嵌入式工具暂不开放 |
+| 运行 package.json 脚本 | [`rabetbase run <script>`](references/rabetbase-run.md) | `write`；先审阅脚本命令体，嵌入式工具暂不开放 |
 | 安装 / 重装 / 刷新 CLI Built-in Skill | [`rabetbase cli-skill install`](references/rabetbase-cli-skill-install.md) | 由最新版官方 Skills CLI 从当前 npm 包内本地源重装同版本 Skill；发现本地 skill 过期时优先执行 |
 | 退出登录 | [`rabetbase auth logout`](references/rabetbase-auth-logout.md) | 删除本地认证 cookie |
-| 绑定当前用户的钉钉沙箱账号 | [`rabetbase user-account dingding-sandbox-bind`](references/rabetbase-user-account.md) | 先 `--dry-run` 核对 ID，正式执行显式加 `--yes`；不需要 appCode |
+| 绑定当前用户的钉钉沙箱账号 | [`rabetbase user-account dingding-sandbox-bind`](references/rabetbase-user-account.md) | `write`；先 `--dry-run` 核对 ID，正式执行不要求 `--yes`；不需要 appCode |
 | 诊断配置问题 | [`rabetbase doctor`](references/rabetbase-doctor.md) | Built-in Skill 一致性、合并配置、各侧 JSON 语法、域名、认证状态 |
 | 上报平台问题 | [`rabetbase issue report`](references/rabetbase-issue-report.md) | 由 Skill 组织完整客观事实，禁止代替平台侧做根因判断或方案设计 |
 | 上传应用文件 | [`rabetbase file upload`](references/rabetbase-file.md) | 返回可持久保存的 `filePath` |
@@ -294,15 +305,15 @@ const result = await client.bff.execute<DashboardData>({
 | 初始化/切换当前工作目录应用 | [`rabetbase workspace`](references/rabetbase-workspace.md) | 写当前目录 `.rabetbase.json`；不从全局复制 cookie/accessKey |
 | 修改配置文件 | [`rabetbase config set <key> <value>`](references/rabetbase-config.md) | 默认写项目；无项目配置且未 `--global` 会拒绝；`--global` 写 `~/.rabetbase.json` |
 | 列出配置 | [`rabetbase config list`](references/rabetbase-config.md) | 查看当前生效的配置 |
-| 管理运行态 app-config | [`rabetbase app-config list/get/set/delete`](references/rabetbase-app-config.md) | 运行态 app-config 管理面；默认不输出明文 value，`set/delete` 先 `--dry-run` |
-| 管理当前研发应用的企业知识库 | [`rabetbase kb list/detail/create/update/delete`](references/rabetbase-kb.md) | 标准解析 `--app/--appcode`；仅 company scope；写操作先 dry-run，再显式 `--yes` |
-| 获取 BFF 通知配置 `configCode` | [`rabetbase notification config-list`](references/rabetbase-notification-config-list.md) | 默认查询 EMAIL 应用级通知配置；不输出渠道地址、配置内容或凭据 |
+| 管理运行态 app-config | [`rabetbase app-config list/get/set/delete`](references/rabetbase-app-config.md) | 运行态 app-config 管理面；默认不输出明文 value；`set` 为 `write`，`delete` 保持 `high-risk-write` |
+| 管理当前研发应用的企业知识库 | [`rabetbase kb list/detail/create/update/delete`](references/rabetbase-kb.md) | 标准解析 `--app/--appcode`；仅 company scope；`create/update` 为 `write`，`delete` 保持 `high-risk-write` |
+| 查询或管理应用级通知配置 | [`rabetbase notification config-list`](references/rabetbase-notification-config-list.md) / [`rabetbase notification config-create`](references/rabetbase-notification-config-mutations.md) / [`rabetbase notification config-update`](references/rabetbase-notification-config-mutations.md) / [`rabetbase notification config-delete`](references/rabetbase-notification-config-mutations.md) | list 获取 BFF 所需 `configCode`；写入只接收单一敏感 JSON 源，先 dry-run；update/delete 必须 `--yes` |
 | 查看线上菜单事实 / 菜单异常审计 | [`rabetbase menu list`](references/rabetbase-menu-list.md) | 返回 DFS 事实、children/page、URL、最近更新人/时间和 snapshotHash；异常治理先读 [`menu-anomaly-manual-cleanup`](guides/menu-anomaly-manual-cleanup.md) |
 | 创建外部网站链接菜单 | [`rabetbase menu external-link-create`](references/rabetbase-menu-external-link-create.md) | `write`；显式选择 `embedded` 或 `new-window`，仅接受 HTTPS；建议先 dry-run，正式执行不要求 `--yes` |
-| 原地更新既有外链 URL | [`rabetbase menu external-link-update`](references/rabetbase-menu-external-link-update.md) | 精确单 ID、URL-only；必须带旧 URL 与父级断言，先 dry-run，再复用参数加 `--yes` |
+| 原地更新既有外链 URL | [`rabetbase menu external-link-update`](references/rabetbase-menu-external-link-update.md) | `write`；精确单 ID、URL-only；必须带旧 URL 与父级断言，先 dry-run，再复用参数正式执行 |
 | 修改任意类型菜单名称 | [`rabetbase menu rename`](references/rabetbase-menu-rename.md) | 精确单 ID、label-only；使用 `--expect-label` 防漂移，先 dry-run 并检查 before/after |
 | 同步本地微前端路由到平台 | [`rabetbase menu sync`](references/rabetbase-menu-sync.md) | 扫描 `src/pages` 创建缺失的 `procode` 菜单；不上传构建产物；正式执行前先 `--dry-run` |
-| 修改微前端菜单资源 URL | [`rabetbase menu asset-update`](references/rabetbase-menu-asset-update.md) | 高频高风险写入；用 ID/path 精确选目标或显式 `--all`，默认 patch 且保留加载模式，先 dry-run 再复用参数加 `--yes` |
+| 修改微前端菜单资源 URL | [`rabetbase menu asset-update`](references/rabetbase-menu-asset-update.md) | `write`；用 ID/path 精确选目标或显式 `--all`，默认 patch 且保留加载模式，先 dry-run 再复用参数正式执行 |
 | 用户组与权限总览（先读工作流/决策树） | [`guides/role-permit-workflow.md`](guides/role-permit-workflow.md) | 先分清「成员归属」vs「能力授权」，再定位到具体命令；含 `role-menus-set` 与 `page-set` 的区别与 5 个剧本 |
 | 查看/创建/管理角色（用户组） | [`rabetbase role list/detail/create/update/delete`](references/rabetbase-role-list.md) | 仅 CUSTOM 可改/删；DEV/ADMIN 拒绝；写操作先 `--dry-run` 再 `--yes` |
 | 解析昵称/用户名到 userId | [`rabetbase role user-resolve`](references/rabetbase-role-user-resolve.md) | 基于租户成员目录；重名报错要求 `--user <id>` 消歧 |
@@ -315,7 +326,7 @@ const result = await client.bff.execute<DashboardData>({
 | 创建空菜单分组 | [`rabetbase menu group-create`](references/rabetbase-menu-group-create.md) | group 持久化为 `type=folder`，保留平台生成的非空 path；先 dry-run 并检查创建位置与排序 |
 | 修改菜单分组排序 | [`rabetbase menu group-update`](references/rabetbase-menu-group-update.md) | 目标必须为 folder；修改任意菜单类型的名称统一使用 `menu rename`；先 dry-run 并检查 before/after |
 | 移动已有叶子菜单 | [`rabetbase menu move`](references/rabetbase-menu-move.md) | 使用精确源 ID、目标父级 ID 和当前父级断言；逐项 dry-run 并检查写后回读 |
-| 异步新建根分组 | [`rabetbase menu regroup-start`](references/rabetbase-menu-regroup-start.md) | 只接收精确非 folder 叶子 ID；返回 taskId，非幂等请求不自动重提 |
+| 异步新建根分组 | [`rabetbase menu regroup-start`](references/rabetbase-menu-regroup-start.md) | `write`；只接收精确非 folder 叶子 ID；返回 taskId，非幂等请求不自动重提 |
 | 查询通用异步任务 | [`rabetbase task status`](references/rabetbase-task-status.md) | 按 taskId + appCode 查询 `PENDING / PROCESSING / SUCCESS / FAILED`；只读，不重启业务操作 |
 | 查找数据集 | [`rabetbase dataset list --name "xxx"`](references/rabetbase-dataset-list.md) | 默认返回全部 DO V2 数据集；查指定来源用 `--source DB_TABLE` / `--source METADATA`；也可 `--code` 精确查 |
 | 查看表结构和字段 | [`rabetbase dataset detail --code xxx`](references/rabetbase-dataset-detail.md) | 含字段定义和操作列表 |
@@ -335,7 +346,7 @@ const result = await client.bff.execute<DashboardData>({
 | 查询 React 自定义页面 | [`rabetbase page react-list`](references/rabetbase-page-react-list.md) | 返回页面 ID、页面名称、`pageUrl`（查看最新保存内容）和 `editPageUrl`（打开编辑器） |
 | 查看 React 自定义页面详情 | [`rabetbase page react-detail --id <pageId>`](references/rabetbase-page-react-detail.md) | 查询页面详情，`codeContent` 包含可修改后整体提交的完整页面文件 |
 | 更新 React 自定义页面 | [`rabetbase page react-update --id <pageId> --page-content <json>`](references/rabetbase-page-react-update.md) | 保存完整页面文件并创建新版本；先 dry-run |
-| 发布 React 自定义页面 | [`rabetbase page react-publish --id <pageId>`](references/rabetbase-page-react-publish.md) | 发布当前保存内容；先 dry-run 并明确确认 |
+| 发布 React 自定义页面 | [`rabetbase page react-publish --id <pageId>`](references/rabetbase-page-react-publish.md) | `write`；发布当前保存内容，先 dry-run 并审阅预览 |
 | 查询智能列表页生成任务状态 | [`rabetbase page generate-status --datasetcode <code> --operation-id <id>`](references/rabetbase-page-generate-status.md) | 查询 job 状态，支持 `operationId` / `clientOperationId` |
 | 查询智能列表页生成任务状态 | [`rabetbase page generate-status --datasetcode <code> --task-id <id>`](references/rabetbase-page-generate-status.md) | 查询 job 状态；taskId 首选，operationId/clientOperationId 兼容。成功后仍读取标准页事实，未知状态不得自动重提 |
 | 查询智能列表页事实快照 | [`rabetbase page standard-page-status --datasetcode <code>`](references/rabetbase-standard-page-status.md) | 查询智能列表页四件套、残留页与菜单事实 |
@@ -352,7 +363,7 @@ const result = await client.bff.execute<DashboardData>({
 | 新建本地同步 SQL | [`rabetbase sql create --name xxx --db-id 10001 --mode sql`](references/rabetbase-sql-create.md) | 先在远端创建，再落本地文件与 `sql.lock.json` |
 | 查看本地同步状态 | [`rabetbase sql status`](references/rabetbase-sql-status.md) | 检查 `added / modified / missing / unchanged / remoteOnly` |
 | 拉取远端 SQL 到本地 | [`rabetbase sql pull`](references/rabetbase-sql-pull.md) | 写入 `.rabetbase/sql/<appCode>/<dbName|db-<id>>/`，含 `@lovrabet` 头注释 |
-| 推送本地 SQL 到远端 | [`rabetbase sql push --sqlcode xxx --yes`](references/rabetbase-sql-push.md) | 以 `sql.lock.json` 为基准上传同步目录中的本地文件 |
+| 推送本地 SQL 到远端 | [`rabetbase sql push --sqlcode xxx`](references/rabetbase-sql-push.md) | `write`；以 `sql.lock.json` 为基准上传同步目录中的本地文件 |
 | 删除 SQL | [`rabetbase sql delete --sqlcode xxx --yes`](references/rabetbase-sql-delete.md) | 删除远端并将本地文件移入 `.rabetbase/sql-trash/` |
 | 校验 SQL 内容 | [`rabetbase sql validate --file xxx`](references/rabetbase-sql-validate.md) | 类型检测、危险语句检查、参数提取 |
 | 执行 SQL 查询 | [`rabetbase sql exec --sqlcode xxx`](references/rabetbase-sql-exec.md) | 支持 `--params` JSON 参数 |
@@ -361,7 +372,7 @@ const result = await client.bff.execute<DashboardData>({
 | 创建本地 BFF | [`rabetbase bff create --type ENDPOINT --name xxx`](references/rabetbase-bff-create.md) | 在 `.rabetbase/bff/<appCode>/...` 下创建脚手架 |
 | 查看 BFF 本地状态 | [`rabetbase bff status`](references/rabetbase-bff-status.md) | 检查 added / modified / unchanged / remoteOnly |
 | 拉取远端 BFF | [`rabetbase bff pull`](references/rabetbase-bff-pull.md) | 从远端同步到本地 |
-| 推送本地 BFF | [`rabetbase bff push --yes`](references/rabetbase-bff-push.md) | high-risk-write，需 `--yes` |
+| 推送本地 BFF | [`rabetbase bff push`](references/rabetbase-bff-push.md) | `write`；建议先 dry-run，正式执行不要求 `--yes` |
 | 删除 BFF | [`rabetbase bff delete --yes --target xxx`](references/rabetbase-bff-delete.md) | high-risk-write，删远端并清理本地 |
 | 生成 SDK 代码 | [`rabetbase codegen sdk --code xxx`](references/rabetbase-codegen-sdk.md) | 按操作生成 TypeScript |
 | 生成 SQL 调用代码 | [`rabetbase codegen sql --sqlcode xxx`](references/rabetbase-codegen-sql.md) | sdk/bff 两种 target |
@@ -399,7 +410,7 @@ const result = await client.bff.execute<DashboardData>({
 | Company Knowledge Base | [`kb list/detail/create/update/delete`](references/rabetbase-kb.md) |
 | Menu | [`list`](references/rabetbase-menu-list.md) / [`external-link-create`](references/rabetbase-menu-external-link-create.md) / [`external-link-update`](references/rabetbase-menu-external-link-update.md) / [`rename`](references/rabetbase-menu-rename.md) / [`sync`](references/rabetbase-menu-sync.md) / [`asset-update`](references/rabetbase-menu-asset-update.md) / [`delete`](references/rabetbase-menu-delete.md) / [`group-create`](references/rabetbase-menu-group-create.md) / [`group-update`](references/rabetbase-menu-group-update.md) / [`move`](references/rabetbase-menu-move.md) / [`regroup-start`](references/rabetbase-menu-regroup-start.md) |
 | Async Tasks | [`task status`](references/rabetbase-task-status.md) |
-| Notification Configuration | [`notification config-list`](references/rabetbase-notification-config-list.md) |
+| Notification Configuration | [`notification config-list`](references/rabetbase-notification-config-list.md) / [`notification config-create`](references/rabetbase-notification-config-mutations.md) / [`notification config-update`](references/rabetbase-notification-config-mutations.md) / [`notification config-delete`](references/rabetbase-notification-config-mutations.md) |
 | Roles | [`list`](references/rabetbase-role-list.md) / `detail` / `create` / `update` / `delete` / [`user-resolve`](references/rabetbase-role-user-resolve.md) / [`user-add` / `user-remove`](references/rabetbase-role-user-add.md) |
 | Permissions | [`page-get` / `page-set`](references/rabetbase-permit-page-set.md) / `role-menus` / [`role-menus-set`](references/rabetbase-permit-role-menus-set.md) / [`role-apis-set`](references/rabetbase-permit-role-apis-set.md) |
 | Tenant Members | [`tenant members-list`](references/rabetbase-tenant-members-list.md)（当前账号所属租户的全量人员目录） |
@@ -407,7 +418,7 @@ const result = await client.bff.execute<DashboardData>({
 | dataset commands | [`list`](references/rabetbase-dataset-list.md) / [`detail`](references/rabetbase-dataset-detail.md) / [`delete`](references/rabetbase-dataset-delete.md) / [`restore`](references/rabetbase-dataset-restore.md) / [`generate-start/status`](references/rabetbase-dataset-generate.md) / [`rename`](references/rabetbase-dataset-rename.md) / [`field-update`](references/rabetbase-dataset-field-update.md) / [`extend-update`](references/rabetbase-dataset-extend-update.md) / [`business-group-update`](references/rabetbase-dataset-business-group-update.md) / [`operations`](references/rabetbase-dataset-operations.md) / [`relations`](references/rabetbase-dataset-relations.md) / [`relation-audit`](references/rabetbase-dataset-relation-audit.md) / [`relation-create/update/delete`](references/rabetbase-dataset-relation-mutations.md) |
 | Smart List Page commands | [`generate-start`](references/rabetbase-page-generate-start.md) / [`generate-status`](references/rabetbase-page-generate-status.md) / [`standard-page-status`](references/rabetbase-standard-page-status.md) / [`relation-audit`](references/rabetbase-page-relation-binding.md) / [`sync`](references/rabetbase-page-sync.md) / [`pull`](references/rabetbase-page-pull.md) / [`push`](references/rabetbase-page-push.md) |
 | React custom page commands | [`react-create`](references/rabetbase-page-react-create.md) / [`react-list`](references/rabetbase-page-react-list.md) / [`react-detail`](references/rabetbase-page-react-detail.md) / [`react-update`](references/rabetbase-page-react-update.md) / [`react-publish`](references/rabetbase-page-react-publish.md) |
-| Database Connections (`db`) | [`list`](references/rabetbase-db-list.md) / [`detail`](references/rabetbase-db-detail.md) / [`create`](references/rabetbase-db-create.md) / [`update`](references/rabetbase-db-update.md) / [`delete`](references/rabetbase-db-delete.md) / [`test`](references/rabetbase-db-test.md) / [`analyze`](references/rabetbase-db-analyze.md) / [`tables`](references/rabetbase-db-tables.md) / [`diff`](references/rabetbase-db-diff.md) |
+| Database Connections (`db`) | [`list`](references/rabetbase-db-list.md) / [`detail`](references/rabetbase-db-detail.md) / [`create`](references/rabetbase-db-create.md) / [`update`](references/rabetbase-db-update.md) / [`delete`](references/rabetbase-db-delete.md) / [`test`](references/rabetbase-db-test.md) / [`analyze`](references/rabetbase-db-analyze.md) / [`tables`](references/rabetbase-db-tables.md) / [`diff`](references/rabetbase-db-diff.md) / [`diff-refresh-start/status`](references/rabetbase-db-diff-refresh.md) |
 | api commands | [`pull`](references/rabetbase-api-pull.md) / [`list`](references/rabetbase-api-list.md) |
 | sql commands | [`list`](references/rabetbase-sql-list.md) / [`detail`](references/rabetbase-sql-detail.md) / [`create`](references/rabetbase-sql-create.md) / [`status`](references/rabetbase-sql-status.md) / [`pull`](references/rabetbase-sql-pull.md) / [`push`](references/rabetbase-sql-push.md) / [`delete`](references/rabetbase-sql-delete.md) / [`validate`](references/rabetbase-sql-validate.md) / [`save`（deprecated）](references/rabetbase-sql-save.md) / [`exec`](references/rabetbase-sql-exec.md) |
 | bff commands | [`list`](references/rabetbase-bff-list.md) / [`detail`](references/rabetbase-bff-detail.md) / [`create`](references/rabetbase-bff-create.md) / [`status`](references/rabetbase-bff-status.md) / [`pull`](references/rabetbase-bff-pull.md) / [`push`](references/rabetbase-bff-push.md) / [`delete`](references/rabetbase-bff-delete.md) |
@@ -429,7 +440,7 @@ const result = await client.bff.execute<DashboardData>({
 
 `sql validate` 是 SQL 内容校验入口；SQL 写入统一通过 `sql create` 或编辑同步文件后执行 `sql push`。
 
-配置 `riskLevel` 可限制允许执行的最高风险等级（详见 [配置参考](references/rabetbase-config.md)）。
+配置 `riskLevel` 可限制允许执行的最高风险等级，默认值为 `write`（详见 [配置参考](references/rabetbase-config.md)）。权限不足时，Agent 只能提醒用户手动编辑 `.rabetbase.json`；**禁止 Agent 或自动化脚本自行修改 `riskLevel`、写入环境变量或以其他方式尝试提权**。
 
 ## 输出格式
 
@@ -484,7 +495,7 @@ const result = await client.bff.execute<DashboardData>({
 | 故障诊断               | CLI/登录/数据集/保存失败排障                                                                                          | [`troubleshooting.md`](guides/troubleshooting.md)                           |
 | BFF 脚本规范           | HOOK/ENDPOINT/COMMON、`context.client`、消息通知扩展、目录与注释模板                                                   | [`backend-function.md`](guides/backend-function.md)                         |
 | 数据接口访问           | 先 detail 再编码、外键/枚举、禁止 N+1、批量与关联查询；可选 `lovrabet data` 查数（**`lovrabet` CLI ≥ 2.0** 且已安装） | [`data-api-guidelines.md`](guides/data-api-guidelines.md)                   |
-| SQL 创建工作流         | list/detail → pull/new → edit → validate → status → push/delete → exec 全链路                                         | [`sql-creation-workflow.md`](guides/sql-creation-workflow.md)               |
+| SQL 创建工作流         | list/detail → pull/create → edit → validate → status → push/delete → exec 全链路                                      | [`sql-creation-workflow.md`](guides/sql-creation-workflow.md)               |
 | BFF 创建工作流         | new → status → dry-run → pull/push                                                                                    | [`bff-creation-workflow.md`](guides/bff-creation-workflow.md)               |
 | 冲突检测与保存         | `blocked`、未保存时的用户沟通、响应结构                                                                               | [`conflict-detection.md`](guides/conflict-detection.md)                     |
 | 质量与最佳实践         | 审查 SQL/BFF、命名、高危边界、描述字段                                                                                | [`best-practices.md`](guides/best-practices.md)                             |

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`