@lovrabet/rabetbase-cli 2.4.7 → 2.5.0-beta.1

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

@@ -48,10 +48,12 @@
 
 ## 平台配置地址
 
+优先使用相关命令返回的 `data.links`。需要手工拼接时，以当前生效的 `appDomain` 作为 `<appDomain>`，不要硬编码 `app.lovrabet.com`：
+
 | 类型 | 地址 |
 |------|------|
-| HOOK | `https://app.lovrabet.com/app/{appCode}/data/dataset/{datasetId}#api-list` |
-| ENDPOINT | `https://app.lovrabet.com/app/{appCode}/data/backend-function` |
+| HOOK | `<appDomain>/app/{appCode}/data/dataset/{datasetId}#api-list` |
+| ENDPOINT | `<appDomain>/app/{appCode}/data/backend-function` |
 
 其中 `datasetId` 需要通过 `rabetbase dataset detail --code xxx --format json` 获取。
 
@@ -85,10 +87,10 @@ Backend Function 脚本统一存放在 `.rabetbase/bff/<appCode>/` 目录下，
 
 HOOK 的第一层子目录名（标识数据集）按以下优先级确定：
 
-1. **alias**（优先）：来自 `api.ts`（由 `rabetbase api pull` 生成）
+1. **alias**（优先）：来自 `api.ts`（`api pull` 返回的 models，按 [`sdk-client-generation.md`](sdk-client-generation.md) 维护）
 2. **datasetCode**（兜底）：当 `api.ts` 不可用时，直接使用 32 位数据集编码
 
-推荐始终先执行 `rabetbase api pull` 以获得可读性更好的 alias 命名。
+推荐先执行 `rabetbase api pull --format compress`，再按 guide 更新 `api.ts` 以获得可读 alias。
 
 ## 文件命名与函数命名
 
@@ -108,7 +110,7 @@ HOOK 的第一层子目录名（标识数据集）按以下优先级确定：
 * `delete`
 * `aggregate`（仅在数据集 operation 实际返回时使用；METADATA 默认不会提供）
 
-使用 `aggregate` 时，聚合列名写在 `aggregate[].column`；`field` 只是历史兼容别名，新脚本不要使用。
+使用 `aggregate` 时，聚合列名写在 `aggregate[].column`；`field` 是兼容别名，默认使用 `column`。
 
 Backend Function HOOK 可以挂在 `DB_TABLE` 或 `METADATA` 数据集上；是否可挂某个 operation，以平台返回的 operation types 为准。
 
@@ -343,7 +345,20 @@ rabetbase dataset detail --code <datasetCode> --format compress \
 
 ## 数据集调用规范
 
-通过 `context.client.models` 调用数据集。模型键格式为固定前缀 `"dataset_"` 拼接 32 位数据集编码，编码来自 `rabetbase dataset list/detail` 返回的 `code` 字段。
+通过 `context.client.models` 调用数据集。有物理表的 `DB_TABLE` 默认按物理表名解析，避免把 Dataset code 写入业务代码：
+
+```javascript
+const primary = context.client.models.byTable("<primary_physical_table>");
+const detail = context.client.models.byTable("<detail_physical_table>", {
+  dblinkId: "<dblinkId>", // 从 rabetbase db list 确认后替换
+});
+
+const record = await primary.getOne({ id: params.id });
+```
+
+`byTable` 只在当前应用内解析。若物理表名只对应一个数据集，不需要 `dblinkId`；若同名表来自多个 dblink，必须从 `rabetbase db list` 取得真实 dblink ID 后传入，运行时遇到 `DATASET_TABLE_AMBIGUOUS` 不会按更新时间或任意 Dataset code 选择。表不存在时返回 `DATASET_TABLE_NOT_FOUND`。
+
+`METADATA` 没有物理表，使用 Dataset code 访问；`DB_TABLE` 的 Dataset code 访问作为兼容方式。模型键格式为固定前缀 `"dataset_"` 拼接数据集编码，编码来自 `rabetbase dataset list/detail` 返回的 `code` 字段：
 
 ```javascript
 const TABLES = {
@@ -357,7 +372,10 @@ const record = await models[TABLES.primary].getOne({ id: params.id });
 
 规则：
 
-* 必须使用 `"dataset_" + 32 位数据集编码`，不要只写裸 `code`
+* `DB_TABLE` 默认使用 `models.byTable("<物理表名>", { dblinkId? })`
+* 同名表跨 dblink 时必须显式传已确认的 `dblinkId`；不要把歧义错误改为任意 Dataset code
+* `METADATA` 使用 `"dataset_" + 数据集 code`；`DB_TABLE` 的该形式仅作为兼容路径
+* 使用兼容路径时必须使用 `"dataset_" + 32 位数据集编码`，不要只写裸 `code`
 * 每个映射后写 `// 数据集: ... | 数据表: ...`
 * 查询单条统一使用 `getOne({ id })`
 * 列表查询优先使用 `filter()`
@@ -395,7 +413,13 @@ await models[TABLES.primary].update({
 
 ### aggregate 调用与选型
 
-`` context.client.models[`dataset_${datasetCode}`].aggregate(params) `` 是 Backend Function 的数据集 Instant API。实际脚本仍按上文的数据集映射，通过 `models[TABLES.xxx]` 访问；示例字段只用于展示参数契约，编写业务脚本前必须用 `dataset detail` 替换为真实字段：
+`aggregate()` 只适用于 `DB_TABLE`：
+
+- `` context.client.models.byTable("<物理表名>"[, { dblinkId }]).aggregate(params) ``：`DB_TABLE` 的推荐寻址
+- `context.client.models[`dataset_${datasetCode}`].aggregate(params)`：仅 `DB_TABLE` 的兼容寻址
+- `METADATA`：**不支持** `aggregate()`
+
+实际脚本仍按上文的数据集映射，通过 `models[TABLES.xxx]` 访问；示例字段只用于展示参数契约，编写业务脚本前必须用 `dataset detail` 替换为真实字段：
 
 ```javascript
 const aggregateResult = await models[TABLES.primary].aggregate({
@@ -597,17 +621,20 @@ export default async function runBusinessFlow(params, context) {
 
 ## SQL 调用规则
 
-Backend Function 入参使用业务参数；需要执行 SQL 时，通过已发布 Custom SQL 的 `sqlCode` + `params` 调用。执行失败时保留并报告原始错误，根据 SQL 资源状态、参数与权限定位问题。
+Backend Function 入参使用业务参数，默认通过已发布 Custom SQL 的唯一 `sqlName` + `params` 调用，避免在业务代码中硬编码 `sqlCode`。执行失败时保留并报告原始错误，根据 SQL 资源状态、参数与权限定位问题。
 
 在 Backend Function 中使用：
 
 ```javascript
-const rows = await context.client.sql.execute({
-  sqlCode: "example-read-list",
+const rows = await context.client.sql.byName("<confirmed_sql_name>").execute({
   params,
 });
 ```
 
+`sqlName` 只在当前应用内解析。名称不存在时返回 `SQL_NAME_NOT_FOUND`，重名时返回 `SQL_NAME_AMBIGUOUS`；两种情况都不会选择任意 SQL。使用前通过 `rabetbase sql list --name "<名称>"` 与 `rabetbase sql detail --sqlcode <code>` 确认目标 SQL 和参数契约。
+
+Backend Function 默认使用 `byName`；`context.client.sql.execute({ sqlCode, params })` 是兼容调用方式。前端 SDK 使用 `sqlCode`。
+
 关键差异：
 
 * 前端 SDK：返回 `{ execSuccess, execResult }`
@@ -860,7 +887,8 @@ await context.client.db.transaction(async (tx) => {
 * [ ] 顶部注释完整且占位符已替换
 * [ ] JSDoc 已覆盖根请求参数、实际字段和返回值；显式抛出异常时已补充 `@throws`
 * [ ] 依赖数据集、调用 BF、执行 SQL 和副作用说明与实际代码一致
-* [ ] 数据集映射使用 `"dataset_" + 32 位编码`
+* [ ] `DB_TABLE` 数据集优先使用 `models.byTable("<物理表名>", { dblinkId? })`；同名表已按真实 dblink ID 消歧
+* [ ] `METADATA` 使用 `"dataset_" + 32 位编码`；`DB_TABLE` 使用该形式时属于兼容路径
 * [ ] 单条查询统一使用 `getOne`
 * [ ] 列表查询使用 `filter`，并从 `.tableData` 读取结果
 * [ ] DB_TABLE 简单单表聚合优先使用 `aggregate()`，并从 `.tableData` 读取结果
@@ -869,6 +897,7 @@ await context.client.db.transaction(async (tx) => {
 * [ ] 批量更新使用 `update({ id: [...] })`，没有使用不存在的 `batchUpdate()` 或记录数组参数
 * [ ] 枚举/选择字段写入 `options[].value`，不是展示 `label`
 * [ ] SQL 返回值按 Backend Function 语义处理
+* [ ] Backend Function 的 Custom SQL 默认使用 `sql.byName("<唯一名称>").execute({ params })`，并已确认名称在当前应用唯一
 * [ ] 未设置系统自动维护字段
 * [ ] 无明显 N+1 或循环写入问题
 * [ ] HOOK 返回 `params`，ENDPOINT 返回业务对象

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

@@ -29,7 +29,7 @@ rabetbase notification config-list --type EMAIL --format compress
 
 从 `data.configs[]` 按 `configName` / `description` 选择配置，并使用同一项的 `configCode`。命令不会输出 `channelConfig`、`endpointUrl` 或通知凭据。没有结果或存在多个候选且业务目标不明确时，停下向用户确认；不得猜测。不要把 dataset 级通知通道的 `channelCode` 当成 Backend Function 所需的应用级 `configCode`。
 
-Backend Function HOOK 可挂载 `DB_TABLE` 或 `METADATA` 数据集，具体 operation 以平台返回为准。`METADATA` 数据集不支持 SQL / aggregate 路径；脚本中应使用 `` context.client.models[`dataset_${datasetCode}`] `` 的标准操作能力。
+Backend Function HOOK 可挂载 `DB_TABLE` 或 `METADATA` 数据集，具体 operation 以平台返回为准。`DB_TABLE` 使用 `context.client.models.byTable("<物理表名>")`；同名物理表来自多个 dblink 时，必须从 `rabetbase db list` 取得真实 ID 后传入 `{ dblinkId }`，不要让运行时任选。`METADATA` 没有物理表，且不支持 SQL / aggregate 路径，使用 `` context.client.models[`dataset_${datasetCode}`] `` 的标准操作能力。
 
 常用字段投影：
 
@@ -59,7 +59,8 @@ rabetbase dataset detail --code <数据集编码> --format compress \
 ### 5. 自检
 * 方法名正确
 * 单条查询用 `getOne`
-* Backend Function 模型键使用 `"dataset_" + 32 位数据集 code`
+* `DB_TABLE` 优先使用 `context.client.models.byTable("<物理表名>")`；同名表存在多个 dblink 时补 `{ dblinkId: <已确认 ID> }`
+* `METADATA` 使用 `"dataset_" + 数据集 code`；`DB_TABLE` 仅在兼容调用时使用该形式
 * METADATA 数据集的 Backend Function / HOOK 不走 SQL 或 aggregate；只使用平台返回的标准数据操作
 * `filter()` 结果从 `.tableData` 读取，不是 `.list`
 * `create()` 返回新记录 ID，不是完整对象；不要访问 `created.id`
@@ -67,6 +68,7 @@ rabetbase dataset detail --code <数据集编码> --format compress \
 * 批量更新使用 `update({ id: [...] })`；不存在 `batchUpdate()`，也不传记录数组
 * 枚举/选择字段写入 `options[].value`，不是展示 `label`
 * Backend Function 中 `sql.execute` 返回数组，不是 `{ execSuccess, execResult }`
+* Backend Function 中 Custom SQL 默认使用 `context.client.sql.byName("<唯一 SQL 名>").execute({ params })`；名称不唯一时先处理 `SQL_NAME_AMBIGUOUS`，不要回退任意 `sqlCode`
 * 没有在 Backend Function 中使用前端 SDK 初始化能力，如 `createClient`、`registerModels`
 * 参数校验、错误处理、脱敏
 * 中文 JSDoc 已写清根请求参数、实际 `params.<字段名>`、返回值；显式抛出异常时包含 `@throws`
@@ -139,8 +141,8 @@ lovrabet bff exec --appcode <appCode> --name <functionName> --params '<json>' --
 
 | 场景 | 前端 SDK | Backend Function (context.client) |
 |------|---------|---------------------|
-| SQL 返回值 | `{ execSuccess, execResult }` | 直接返回数组 |
-| 模型键 | 可通过初始化/生成代码使用 alias | 使用 `"dataset_" + 32 位数据集 code` |
+| SQL 调用 / 返回值 | `sql.execute({ sqlCode, params })`，返回 `{ execSuccess, execResult }` | 默认使用 `sql.byName(sqlName).execute({ params })`，直接返回数组；`sql.execute({ sqlCode, params })` 为兼容调用方式 |
+| 数据集访问 | 可通过初始化/生成代码使用 alias | `DB_TABLE` 默认使用 `models.byTable(tableName, { dblinkId? })`；`METADATA` 使用 `"dataset_" + 数据集 code`，`DB_TABLE` 也支持该兼容调用方式 |
 | `filter()` 返回 | `tableData` 为列表数据 | `tableData` 为列表数据，不是 `list` |
 | `create()` 返回 | 以 SDK 文档/类型为准 | 新记录 ID，不是完整对象 |
 | `batchCreate()` 返回 | 以 SDK 文档/类型为准 | 新记录 ID 数组；直接传非空对象数组 |

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

@@ -109,7 +109,7 @@ page create --page-pattern BLANK
 
 判断顺序：先确认单一数据集请求能否满足需求；数据组合和数据库计算是主要问题时选择 Custom SQL；当前用户、角色、数据范围或业务规则需要额外控制时选择 Backend Function。三种方式可以根据已确认的 SDK 契约配合使用，但不得自行推测方法、参数或返回结构。
 
-页面和 Backend Function 通过已发布 Custom SQL 的 `sqlCode` + `params` 执行查询。Dataset、Custom SQL 或 Backend Function 执行失败时，保留并报告原始错误，根据资源状态、参数与权限定位问题。
+页面通过已发布 Custom SQL 的 `sqlCode` + `params` 执行查询；Backend Function 默认使用 `context.client.sql.byName(sqlName).execute({ params })`，`sql.execute({ sqlCode, params })` 仅作兼容路径。Dataset、Custom SQL 或 Backend Function 执行失败时，保留并报告原始错误，根据资源状态、参数与权限定位问题。
 
 页面需要读取或写入数据集时，先按以下顺序确认事实：
 

package/skills/rabetbase/guides/data-api-guidelines.md

@@ -67,22 +67,22 @@ rabetbase dataset detail --code <数据集编码> --format compress \
 
 ---
 
-## 可选：`lovrabet` CLI 查数（`data filter` / `data getOne`）
+## 真实行数据：交接给 `lovrabet`
 
-本 skill 的**主路径**始终基于 **`rabetbase`**（`dataset detail`、`sql exec` 等），**不要求**安装其它 CLI。
+不需要真实行数据时，`lovrabet` CLI 可以不装；本 skill 的结构/发布主路径始终基于 **`rabetbase`**（`dataset detail`、`sql exec` 验证已发布 SQL 等）。
 
-若开发者本机已单独安装 **Lovrabet 运行时 CLI**（npm 包 **`@lovrabet/lovrabet-cli`**，命令名 **`lovrabet`**），可在终端用 **`lovrabet data filter`**、**`lovrabet data getOne`** 按 **与 `@lovrabet/sdk` 相同的语义** 查询数据集行数据，并直接查看 JSON 结构，便于与前端 / Backend Function 里的 `filter`、`getOne` 对照调试。
+一旦要验证真实业务行数据，必须交接给 **`lovrabet data filter`** / **`lovrabet data getOne`**（与 `@lovrabet/sdk` 相同语义）。`rabetbase` 与 `lovrabet` Skill 不互斥：不可用时**报告阻断**并提示安装，不要静默安装或修复运行态 CLI，也不要把 `rabetbase sql exec` 当成行数据查询的通用替代。
 
-**版本要求：须 `lovrabet` CLI ≥ 2.0**（主版本 2 及以上）。低于 2.0 的旧包**没有**与本文一致的 `data filter` / `data getOne` 能力（或行为不同），请勿按本节操作；请升级：`npm install -g @lovrabet/lovrabet-cli@^2.0.0`（或 `latest`）。自检：`lovrabet --version`。
+若本机已安装 **Lovrabet 运行时 CLI**（npm 包 **`@lovrabet/lovrabet-cli`**，命令名 **`lovrabet`**，须 **≥ 2.0**），可在终端对照调试前端 / Backend Function 里的 `filter`、`getOne`。低于 2.0 请先升级：`npm install -g @lovrabet/lovrabet-cli@^2.0.0`。自检：`lovrabet --version`。
 
 **注意：**
 
 | 点 | 说明 |
 |----|------|
-| **非必备** | 团队未必全局安装 `lovrabet`；**不要**在文档或 Agent 流程里把 `lovrabet` 写成前置条件。 |
-| **≥ 2.0** | 本节所述 `data` 子命令以 **2.0+** 为准；版本不符时先升级，勿将异常当作 skill 错误。 |
-| **未安装时** | 仍用 `rabetbase dataset detail` 拿结构；要看真实数据可用 **`rabetbase sql exec`**（已有对应 `sqlCode`）、或平台控制台；勿假设用户会去装第二个 CLI。 |
-| **配置与认证** | `lovrabet` 与 `rabetbase` 的配置项、鉴权方式**可能不完全相同**，需按各自 CLI 文档分别配置；勿照搬一条 `rabetbase` 的 flag 就认为 `lovrabet` 等价。 |
+| **结构 vs 行数据** | 结构用 `rabetbase dataset detail`。真实行数据必须用 `lovrabet data filter` / `data getOne`。 |
+| **未安装时** | 报告阻断，并提示安装 `lovrabet` Skill（`npx skills add lovrabet/lovrabet-cli`）和 CLI。不要由本 Skill 静默安装或修复。**`rabetbase sql exec` 只验证已发布 SQL 的可执行性与结果结构。** |
+| **≥ 2.0** | 本节 `data` 子命令以 **2.0+** 为准；版本不符时先升级。 |
+| **配置与认证** | `lovrabet` 与 `rabetbase` 的配置项、鉴权方式可能不完全相同，按各自 CLI 文档配置。 |
 | **详细用法** | 以 `lovrabet data --help`、`lovrabet data filter --help` 为准（参数多为 `--code` + `--params` JSON）。 |
 
 示例（仅作形态参考，需本机已安装且已登录/配置）：

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

@@ -41,19 +41,11 @@ trace/plan  → 见下一节（分析任务专用）
 ### 差异读取策略（所有流程共用）
 
 ```text
-db detail --id <id>
-  → 读取 data.tableCount
-
-用户明确要求实时/强制刷新：
-  → 无论 tableCount 多少，走“刷新后读取”
-
-用户明确要求不刷新：
-  → 直接读取；tableCount > 200 时提示结果可能滞后
+用户明确要求不分析、不刷新或只看现有结果：
+  → 直接读取，并说明结果可能不是最新事实
 
-用户未指定：
-  tableCount <= 200 → 直接读取
-  tableCount > 200  → 刷新后读取
-  tableCount 缺失   → 直接读取并说明新鲜度未知，不隐式写入
+其他情况（默认）：
+  → 无论 tableCount 多少或是否缺失，都走“刷新后读取”
 
 直接读取：
   db diff --id <id> --all --changed-only
@@ -67,7 +59,7 @@ db detail --id <id>
     → FAILED / CANCELLED 停止，不自动重提
 ```
 
-`tableCount <= 200` 时服务端通常实时计算默认差异视角，刷新收益很小。`tableCount > 200` 时服务端可能读取最近差异快照，刷新可以降低滞后。`db diff --view all` 是实时全部表分页，用于查看无差异表或主动重新分析已有表，不需要先刷新快照。
+CLI 不再依据 `tableCount` 推断异步刷新是否值得执行。默认通过一次可跟踪的异步任务取得最新差异事实，避免小库、数量未知或服务端实现变化时沿用旧快照。`db diff --view all` 是实时全部表分页，用于查看无差异表或主动重新分析已有表；但在 DBAgent 增量分析工作流中，仍按上述默认策略先完成异步差异刷新，除非用户明确要求跳过。
 
 差异刷新与 schema 分析是两个独立任务：`diff-refresh-*` 只刷新差异事实，`analyze-*` 才把选中表同步为数据集。两类 traceId 不得混用。
 
@@ -113,7 +105,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
@@ -135,7 +127,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
   → 重新读取完整事实；目标差异收敛后才算本轮分析完成
   → 仍未收敛则只对剩余非删除表进入下面的逐表恢复
 ```
@@ -151,7 +143,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
     → 以最终 `db diff --all --changed-only` 的 data.toAnalyzeTables 判断是否收敛
     → 已尝试的剩余表只恢复一次，不再次循环提交
 ```

package/skills/rabetbase/guides/menu-anomaly-manual-cleanup.md

@@ -13,12 +13,7 @@
 
 ## 平台入口
 
-先按当前 `rabetbase` 环境计算 `<appBaseUrl>`：
-
-```text
-production https://app.lovrabet.com/app/<appCode>
-daily      https://daily.lovrabet.com/web-app/app/<appCode>
-```
+优先使用命令返回的页面链接。需要手工拼接时，从当前生效的 `appDomain` 得到 `<appBaseUrl>`，不要硬编码官方域名；独立部署和不同 region 的入口可能不同。
 
 总入口：
 

package/skills/rabetbase/guides/sdk-client-generation.md

@@ -0,0 +1,146 @@
+# SDK 客户端代码生成（api.ts / client.ts）
+
+> 目标：根据 `rabetbase api pull` 返回的数据集事实，生成或更新浏览器子应用的 `src/api/api.ts` 与 `src/api/client.ts`，并保留项目已有的自定义写法。
+>
+> CLI 不再每次覆盖 TypeScript。`api pull` 只保证：刷新 `sdk-config.ts`、返回 `data.models`，并在文件缺失时写入 Cookie-first 脚手架。已有文件由本指南更新。
+
+## 何时执行
+
+出现以下任一情况时，先读本指南再改 `src/api/`：
+
+- 刚执行 `rabetbase api pull` 或 `rabetbase project create`（带 appCode）
+- 平台增删了 Dataset，本地 `models` 过期
+- `api.ts` / `client.ts` 缺失、空 `models: []`、或 `LOVRABET_APP_CODE` 仍是 `NOT-SET`
+- 用户要求修复 SDK 客户端初始化
+
+不要凭空编造 `datasetCode`。不要把本指南里的浏览器 Cookie 客户端写成服务端 `accessKey` 客户端。
+
+## 工作流
+
+```
+rabetbase api pull --format compress
+  → 读 data.models / data.configName / data.isDefaultConfig / data.files / data.needsAgentMerge
+  → 读已有 api.ts、client.ts、sdk-config.ts（含 {prefix}-api.ts / {prefix}-client.ts）
+  → 按事实更新 models，保留本地 extras
+  → 不要改已经正确的 createClient({ apiConfigName, ...LOVRABET_SDK_CONFIG })
+```
+
+1. 执行 `rabetbase api pull --format compress`（需要人类可读缩进时用 `--format json`）。
+2. 使用返回的 `data.models`，不要手写或猜测 `datasetCode`。也可用 `rabetbase api list --format compress` 核对目录，但写文件以 pull 的 `data.models` 为准。
+3. 先读现有文件再写：
+   - 默认单应用：`src/api/api.ts`、`src/api/client.ts`、`src/api/sdk-config.ts`
+   - 多应用非 default：`{name}-api.ts` / `{name}-client.ts`（`data.files.api.path` / `data.files.client.path`）
+4. `sdk-config.ts` 由 CLI 维护（`data.files.sdkConfig.action === "refreshed"`），不要往里面写 `cookie` / `accessKey` / `token`。
+5. 看 `data.needsAgentMerge` 和 `data.files.*.action`，**不要**用已删除的 `wroteScaffold`：
+   - `needsAgentMerge === false` 且 `api`/`client` 均为 `created` 或 `overwritten`：脚手架已按当前 `models` 写好，只需检查项目 extras。
+   - `needsAgentMerge === true`：至少有一个 TypeScript 文件被 **preserved**。即使 `client` 刚 `created`，过期的 `api.ts` 仍要按下方规则合并，**不要**当成脚手架已完成。
+6. 默认应用：`data.isDefaultConfig === true`，`data.configName === "default"`，代码里用 `CONFIG_NAMES.DEFAULT`。
+7. 具名应用：`data.isDefaultConfig === false`，`data.configName` 是不含引号的名字（如 `order`），`registerModels(..., "order")` 与 `apiConfigName: "order"`。不要把 `configName` 再包一层引号。
+
+## 权威结构
+
+浏览器子应用的权威形态与 `templates/projects/sub-app-react-demo/src/api/` 一致。脚手架模板是 `templates/generate-api/*.tpl`，生成结果应对齐 demo，而不是另造一套。
+
+### sdk-config.ts（路由，无凭证）
+
+```typescript
+/**
+ * Lovrabet SDK runtime routing.
+ * Generated by Rabetbase CLI. Do not add credentials to this file.
+ */
+export const LOVRABET_SDK_CONFIG = {} as const;
+```
+
+CLI 可能写入 `region: "id"` 或 `runtimeDomain: "https://…"`。不要手改成认证字段。
+
+### api.ts
+
+```typescript
+import { registerModels, CONFIG_NAMES, type ModelsConfig } from "@lovrabet/sdk";
+
+export const LOVRABET_APP_CODE = "app-xxxxxxxx";
+
+export const LOVRABET_MODELS_CONFIG: ModelsConfig = {
+  appCode: LOVRABET_APP_CODE,
+  models: [
+    { datasetCode: "abc123", tableName: "orders", name: "订单", alias: "orders" },
+  ],
+} as const;
+
+registerModels(LOVRABET_MODELS_CONFIG, CONFIG_NAMES.DEFAULT);
+```
+
+- 默认应用：`data.isDefaultConfig` 为 true 时用 `CONFIG_NAMES.DEFAULT`。
+- 非默认 / 具名应用：用 `data.configName`（不含引号的字符串，如 `order`）作为 `registerModels` 第二参数和 `apiConfigName`，不要再 import 未使用的 `CONFIG_NAMES`。
+- 数字开头的文件前缀使用 `APP_` 变量前缀（如 `APP_5B732428_APP_CODE`），运行时 `appCode` 保持原值。
+- `registerModels` 是 `@lovrabet/sdk` 的独立命名导出，**不是** `client.registerModels()`。
+
+### client.ts（Cookie-first）
+
+```typescript
+import { createClient, CONFIG_NAMES } from "@lovrabet/sdk";
+import "./api";
+import { LOVRABET_SDK_CONFIG } from "./sdk-config";
+
+export const lovrabetClient = createClient({
+  apiConfigName: CONFIG_NAMES.DEFAULT,
+  ...LOVRABET_SDK_CONFIG,
+});
+```
+
+- 必须 `import "./api"`（或 `./{prefix}-api`）以执行 `registerModels`。
+- 浏览器子应用默认登录态 Cookie：省略 `authMode`，**不要**在此文件写入 `accessKey` / `token`。
+- 已有 `createClient({ apiConfigName, ...LOVRABET_SDK_CONFIG })` 且与 `data.isDefaultConfig` / `data.configName` 一致时，不要改参数形态。
+- 非生产环境脚手架可能带 `env: "daily"`；已有客户端已能工作则不要为了对称去改。
+
+## 合并规则
+
+以 `data.models` 为 Dataset 清单的唯一事实来源：
+
+- **新增**：pull 有、本地没有的 `datasetCode`，追加到 `models`
+- **删除**：本地有、pull 没有的 `datasetCode`，从 `models` 移除
+- **更新**：同一 `datasetCode` 的 `tableName` / `name` 以 pull 为准
+- **别名**：本地已有且仍对应同一 `datasetCode` 的 `alias` 保留；新建项使用 pull 给出的 `alias`
+- **保留 extras**：额外的 `registerModels(...)`、额外 client 导出、项目自定义注释（非 Generated 头）不要删
+- **多应用**：继续使用 CLI 的 `{name}-api.ts` / `{name}-client.ts` 命名，不要把多个 app 的 models 揉进同一个 `api.ts`
+
+## 认证（不要写进浏览器 client.ts）
+
+浏览器子应用走 Cookie，本指南的默认 `client.ts` 不声明 `authMode`。
+
+仅当用户明确要求**服务端**文件时才使用密钥，且必须显式 `authMode`：
+
+- 仅 `accessKey` → `authMode: "client-ak"`，且只放服务端
+- `accessKey`（+ 可选 `secretKey`）签名，或预计算 `token` + 配对 `timestamp` → `authMode: "openapi"`
+- 预计算 token 必须同时提供 `timestamp`，否则首次请求报 `timestamp is required`
+- OpenAPI 凭据通过 `X-Token` / `X-Time-Stamp` 传递，不是 `Authorization: Bearer`
+
+服务端写法详见 [`typescript-sdk.md`](typescript-sdk.md)。
+
+## 禁止
+
+- `client.registerModels(...)`
+- 把 `filter()` 返回值当数组：必须 `result.tableData`
+- `result.total`：总数是 `result.paging.totalCount`
+- `client.models.dataset_[code]`：动态访问用 `client.models[\`dataset_${code}\`]`
+- 传了 `accessKey` / `token` 却省略 `authMode`
+- 把 Cookie / AccessKey 写进 `sdk-config.ts` 或浏览器 `client.ts`
+- 在已有正确 `createClient` 形态上改成另一种参数风格
+
+## pull 输出字段
+
+`rabetbase api pull --format compress` 的 `data`（单应用）：
+
+| 字段 | 含义 |
+|------|------|
+| `appCode` | 当前应用 |
+| `configName` | `"default"` 或具名应用名（不含 TS 引号） |
+| `isDefaultConfig` | 默认应用为 `true` |
+| `models[]` | `datasetCode` / `tableName` / `name` / `alias` |
+| `sdkRouting` | `{ region?: "id", runtimeDomain?: string }` |
+| `files.api` / `files.client` / `files.sdkConfig` | `{ path, action }`；`action` 为 `created` / `overwritten` / `preserved` / `refreshed` |
+| `needsAgentMerge` | 任一 TypeScript 被 `preserved` 时为 `true`，必须合并 `models` |
+| `apiFilePath` / `clientFilePath` / `sdkConfigPath` | 与 `files.*.path` 相同，兼容路径字段 |
+| `modelCount` / `datasetCount` | 模型数量 |
+
+多应用时 `data.apps[]` 为上述对象的数组。

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

@@ -6,7 +6,7 @@
 
 平台是唯一 source of truth。团队长期维护 SQL 时，优先使用 **本地同步工作流**：`sql create / pull / status / push / delete` + `.rabetbase/sql.lock.json`。
 
-SQL 内容编写、参数绑定与 MyBatis 语法以 [`sql-mybatis.md`](sql-mybatis.md) 为准。页面和 Backend Function 执行已发布的 Custom SQL 时使用 `sqlCode` + `params`。
+SQL 内容编写、参数绑定与 MyBatis 语法以 [`sql-mybatis.md`](sql-mybatis.md) 为准。页面执行已发布的 Custom SQL 时使用 `sqlCode` + `params`；Backend Function 默认使用 `context.client.sql.byName(sqlName).execute({ params })`，`sql.execute({ sqlCode, params })` 仅作兼容路径。
 
 ## 工作流
 

package/skills/rabetbase/guides/troubleshooting.md

@@ -54,7 +54,7 @@
 
 * ❌ 错误排查方向：建议用户重装各种库
 * ✅ **强制动作**：
-  * 建议用户检查 `.lovrabetrc`（或其他配置）中的 `appcode` 是否正确
+  * 建议用户检查 `.rabetbase.json` 中的 `appcode` 是否正确
   * 建议用户在终端执行 `rabetbase auth` 检查是否未登录或 Cookie 过期
   * 帮用户执行 `rabetbase dataset list --format json` 确认该环境到底有哪些可用数据集
 

package/skills/rabetbase/guides/typescript-sdk.md

@@ -16,6 +16,8 @@
 
 不要把本指南里的 `createClient`、`registerModels` 等前端 / Node SDK 初始化能力套用到 Backend Function。Backend Function 内只使用平台注入的 `context.client`。
 
+生成或更新项目里的 `src/api/api.ts` / `client.ts` 时，先 `rabetbase api pull --format compress`，再遵守 [`sdk-client-generation.md`](sdk-client-generation.md)。浏览器子应用的默认 client 是 Cookie + `...LOVRABET_SDK_CONFIG`，不要把下面的服务端 `accessKey` 示例写进 `src/api/client.ts`。
+
 ## 初始化规则
 
 必须使用 `createClient` 命名导出，禁止使用 `new LovrabetClient()`：
@@ -25,6 +27,7 @@ import { createClient } from "@lovrabet/sdk";
 
 const client = createClient({
   appCode: "your-app-code",
+  authMode: "client-ak", // 必须显式声明；否则一律走 cookie 模式，accessKey 会被忽略
   accessKey: process.env.RABETBASE_ACCESS_KEY, // 仅在服务端使用
   models: [
     { tableName: "users", datasetCode: "39f758e7b38c476b8bb3996771a601a1", alias: "users" }
@@ -32,6 +35,12 @@ const client = createClient({
 });
 ```
 
+认证模式必须显式声明,不会按字段自动推断:
+
+* 仅 `accessKey` → `authMode: "client-ak"`
+* `accessKey`(+可选 `secretKey`)签名，或已配对的预计算 `token` + `timestamp` → `authMode: "openapi"`（凭据通过 `X-Token` / `X-Time-Stamp` 请求头传递，不是 Authorization Bearer；用 `token` 时必须同时提供配对的 `timestamp`，否则首次请求报 `timestamp is required`）
+* 浏览器 Cookie 环境 → 省略 `authMode`(默认 cookie)
+
 ## 1. 模型查询 (Filter API)
 
 这是操作模型（表）的**最高优** API。
@@ -47,7 +56,7 @@ const client = createClient({
 * ❌ `where: { status: 'active' }`
 * ✅ `where: { status: { $eq: 'active' } }`
 
-支持的操作符：`$eq`, `$ne`, `$gte`, `$lte`, `$gt`, `$lt`, `$contain`, `$startWith`, `$endWith`, `$in`。
+支持的操作符：`$eq`, `$ne`, `$gt`, `$lt`, `$gte`（或兼容旧写法 `$gteq`）, `$lte`（或兼容旧写法 `$lteq`）, `$contain`, `$startWith`, `$endWith`, `$in`, `$notNull`。`$gteq` / `$lteq` 是后端保留的别名，与 `$gte` / `$lte` 映射到同一 SQL 比较，新代码推荐用 `$gte` / `$lte`。
 
 逻辑组合：
 ```typescript
@@ -80,7 +89,7 @@ const result = await client.models.article.filter({
 
 **接口**：
 ```typescript
-client.models.dataset_[code].update({
+client.models[`dataset_${code}`].update({
   id: number | string | (number | string)[]; [key: string]: any
 })
 ```
@@ -108,7 +117,7 @@ await client.models.customer.update({
 
 **接口**：
 ```typescript
-client.models.dataset_[code].delete({ id: number | string | (number | string)[] })
+client.models[`dataset_${code}`].delete({ id: number | string | (number | string)[] })
 ```
 
 **示例**：
@@ -122,8 +131,9 @@ const inactiveUsers = await client.models.customer.filter({
   select: ['id']
 });
 
+// filter() 返回 ListResponse（{ tableData, paging, tableColumns }），列表数据在 tableData
 await client.models.customer.delete({
-  id: inactiveUsers.map(u => u.id)
+  id: inactiveUsers.tableData.map(u => u.id)
 });
 ```
 
@@ -148,17 +158,43 @@ async function updateInBatches(ids: number[], batchSize = 1000) {
 
 ### 别名模式（Alias Pattern）
 
-如果在前端 / Node SDK 中使用 `registerModels` 定义了别名，批量操作同样支持。此能力不适用于 Backend Function 的 `context.client`。
+在前端 / Node SDK 中给数据集配置 `alias` 后，可用别名访问模型，批量操作同样支持。此能力不适用于 Backend Function 的 `context.client`。
+
+别名在初始化时配置，最常见的是直接写进 `createClient` 的 `models`：
 
 ```typescript
-// 注册别名
-client.registerModels({
-  primary: 'dataset_abc123',
-  detail: 'dataset_def456'
+import { createClient } from "@lovrabet/sdk";
+
+const client = createClient({
+  appCode: "your-app-code",
+  models: [
+    { tableName: "orders", datasetCode: "abc123", alias: "primary" },
+    { tableName: "order_items", datasetCode: "def456", alias: "detail" },
+  ],
 });
 
 // 使用别名批量操作
-await client.models.primary.update({ id: [1, 2, 3], status: 'active' });
+await client.models.primary.update({ id: [1, 2, 3], status: "active" });
+```
+
+`registerModels` 是 `@lovrabet/sdk` 的独立命名导出（不是 client 实例方法），用于把一份完整 `ModelsConfig`（`{ appCode, models }`）注册到全局配置表，再由 `createClient` 按配置名引用（CLI 生成的 `src/api/*.ts` 就是这样自动注册的）：
+
+```typescript
+import { createClient, registerModels } from "@lovrabet/sdk";
+
+registerModels(
+  {
+    appCode: "your-app-code",
+    models: [
+      { tableName: "orders", datasetCode: "abc123", alias: "primary" },
+      { tableName: "order_items", datasetCode: "def456", alias: "detail" },
+    ],
+  },
+  "prod",
+);
+
+const client = createClient("prod"); // 或 createClient({ apiConfigName: "prod", authMode: "openapi", token, timestamp, env })（用 token 时必须显式 authMode 且带配对 timestamp）
+await client.models.primary.update({ id: [1, 2, 3], status: "active" });
 ```
 
 ## 2. 自定义 SQL (SQL API)

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

@@ -1,6 +1,6 @@
 # api list
 
-列出当前 App 下已生成的所有数据集（Dataset）模型，查看 API 客户端代码中有哪些可用 Model。
+列出当前 App 下平台返回的数据集（Dataset）模型事实。本命令查询远端 Dataset 元信息，**不检查**本地是否已生成 `api.ts` / `client.ts`。
 
 ## 命令
 
@@ -23,7 +23,7 @@ rabetbase api list --format json
 
 | 参数 | 说明 |
 |------|------|
-| `--global` | 多应用时从「全局+项目」合并配置解析 `apps`（默认仅项目级 `apps`）。项目配置了 `inherit: false` 时见 `api pull` 文档同名词条 |
+| `--global` | 多应用时显式从「全局+项目」双层解析 `apps`；默认仅项目级 `apps` |
 | `--app <name>` | 多应用模式下，指定应用名称 |
 | `--appcode <code>` | 直接指定 appcode |
 | `--format json` | JSON 格式输出（用于脚本解析） |
@@ -46,7 +46,7 @@ rabetbase api list --format json
 - **加 `--app <name>`**：仅列出指定应用的模型
 - **加 `--appcode <code>`**：反查到对应 app profile，使用其 cookie/env
 
-若项目 **`inherit: false`**，`--global` 无法合并进全局 `apps`，行为与 `api pull` 一致（详见 **api pull** 文档「与 inherit: false 的关系」）。
+`inherit` 不是受支持的配置项；`--global` 始终显式读取全局和项目双层 apps。
 
 ## 风险等级
 
@@ -55,4 +55,4 @@ rabetbase api list --format json
 ## 前置条件
 
 - 已完成 `rabetbase auth` 登录
-- 已运行过 `rabetbase api pull` 生成过 API 代码（用于确认本地已有哪些模型）
+- 已配置 appcode（单应用或多应用）