@lovrabet/rabetbase-cli 2.5.2 → 2.5.3-beta.1

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

@@ -2,7 +2,7 @@
 
 > 目标：根据 `rabetbase api pull` 返回的数据集事实，生成或更新浏览器子应用的 `src/api/api.ts` 与 `src/api/client.ts`，并保留项目已有的自定义写法。
 >
-> CLI 默认不覆盖 TypeScript。`api pull` 只保证：刷新 `sdk-config.ts`、返回 `data.models`，并在文件缺失时写入 Cookie-first 脚手架。已有文件由本指南更新；只有用户明确要求放弃本地定制并完整重建时，才使用 `--force --yes`。
+> CLI 默认不覆盖 TypeScript。`api pull` 只保证：刷新 `data.files.sdkConfig.path` 指向的应用级 SDK 路由文件、返回 `data.models`，并在文件缺失时写入 Cookie-first 脚手架。已有文件由本指南更新；只有用户明确要求放弃本地定制并完整重建时，才使用 `--force --yes`。
 
 ## 何时执行
 
@@ -21,7 +21,7 @@
 rabetbase api pull --format compress
   → 单应用读 data；项目应用清单逐项读 data.apps[]
   → 读取每项的 models / configName / isDefaultConfig / files / needsAgentMerge
-  → 读已有 api.ts、client.ts、sdk-config.ts（含 {prefix}-api.ts / {prefix}-client.ts）
+  → 读已有 api.ts、client.ts 与 files.sdkConfig.path（含 {prefix}-api.ts / {prefix}-client.ts / {prefix}-sdk-config.ts）
   → 按事实更新 models，保留本地 extras
   → 不要改已经正确的 createClient({ apiConfigName, ...LOVRABET_SDK_CONFIG })
 ```
@@ -32,8 +32,8 @@ rabetbase api pull --format compress
 2. 直接单应用结果使用 `data.models`；项目应用清单结果逐项使用 `data.apps[].models`。不要手写或猜测 `datasetCode`。也可用 `rabetbase api list --format compress` 核对目录，但写文件以 pull 返回的 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`。
+   - 多应用非 default：`{name}-api.ts` / `{name}-client.ts` / `{name}-sdk-config.ts`（以 `data.files.*.path` 为准）
+4. SDK 路由文件由 CLI 维护（`data.files.sdkConfig.action === "refreshed"`），不要往里面写 `cookie` / `accessKey` / `token`。若保留的旧 `{name}-client.ts` 仍导入共享 `./sdk-config`，只把该 import 改为 `./{name}-sdk-config`，其余本地定制保持不变。
 5. 看 `data.needsAgentMerge` 和 `data.files.*.action`，**不要**用已删除的 `wroteScaffold`：
    - `needsAgentMerge === false` 且 `api`/`client` 均为 `created` 或 `overwritten`：脚手架已按当前 `models` 写好，只需检查项目 extras。
    - `needsAgentMerge === true`：至少有一个 TypeScript 文件被 **preserved**。先比较本地配置与返回事实，只在有差异时合并；即使 `client` 刚 `created`，也不能据此跳过对已保留 `api.ts` 的检查。
@@ -44,7 +44,7 @@ rabetbase api pull --format compress
 
 浏览器子应用的权威形态与 `templates/projects/sub-app-react-demo/src/api/` 一致。脚手架模板是 `templates/generate-api/*.tpl`，生成结果应对齐 demo，而不是另造一套。
 
-### sdk-config.ts（路由，无凭证）
+### sdk-config.ts / {name}-sdk-config.ts（路由，无凭证）
 
 ```typescript
 /**

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

@@ -21,7 +21,13 @@ tags: [jsx, custom-component, page-schema]
 
 ## 机制
 
-`render` 只写 `source`，不写编译后的 `value`。`source` 按 React 组件源码编写，固定使用 `function render(props)`；页面上下文从 `props.env` 读取。Agent 只维护 `source`。
+`render` 只写 `source`，不手工写编译后的 `value`。`source` 按 React 组件源码编写，固定使用 `function render(props)`；页面上下文从 `props.env` 读取。Agent 只维护 `source`。
+
+页面编辑器与 `rabetbase page push` 都使用平台正式 JSX 编译器把 `source` 包装为运行时函数，并在调用源码组件时注入 `{ env, sdkClient }`。因此：
+
+- `props.env` / `props.sdkClient` 是源码 React 组件的 props，不是原始 `render.value` 函数的直接参数
+- 不要根据运行时外层 `function render(env)` 手工拼装 `value`，也不要在源码中改用 `this`
+- 通过 CLI 推送时，缺失或变化的 `value` 会自动生成；编译失败时页面不会更新
 
 推荐固定写法：
 
@@ -45,6 +51,7 @@ function render(props) {
 |------|------|------|
 | `props.render.type` | 是 | 固定为 `JSFunction` |
 | `props.render.source` | 是 | JSX 源码 |
+| `props._context` | 是 | 页面运行时上下文，固定为 `{ "type": "JSExpression", "value": "this" }`；`rabetbase page push` 会自动补齐或规范化 |
 
 ### source 可用参数
 
@@ -114,6 +121,7 @@ function render(props) {
 
 | 要点 | 说明 |
 |------|------|
-| 只需提供 `source` | `value` 由系统自动生成 |
-| source 中访问上下文 | 使用 `props.env`；不要手写编译后的函数参数 |
+| 只需维护 `source` | `value` 由页面编辑器或 `rabetbase page push` 使用平台正式编译器生成 |
+| source 中访问上下文 | 使用 `props.env` / `props.sdkClient`；不要手写编译后的函数参数，不要改用 `this` |
+| `_context` 固定 | 运行时需要页面上下文；CLI 推送时会自动规范为 `JSExpression: this` |
 | `setState` 触发刷新的前提 | 数据源 params 必须绑定 `this.state.xxx` |

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

@@ -1,6 +1,6 @@
 # api pull
 
-拉取当前 App 下所有数据集（Dataset）的元信息，刷新 `src/api/sdk-config.ts`，并在 `api.ts` / `client.ts` **缺失时**写入 Cookie-first 脚手架。项目公开 Domain 路由由 [`project domain-routing-sync`](rabetbase-project-domain-routing-sync.md) 独立维护。
+拉取当前 App 下所有数据集（Dataset）的元信息，刷新对应 SDK 路由配置，并在 `api.ts` / `client.ts` **缺失时**写入 Cookie-first 脚手架。默认应用使用 `src/api/sdk-config.ts`，非默认应用使用 `<name>-sdk-config.ts`。项目公开 Domain 路由由 [`project domain-routing-sync`](rabetbase-project-domain-routing-sync.md) 独立维护。
 
 已有 TypeScript 默认**不会被覆盖**。Agent 必须用返回的 `data.models` 按 [`sdk-client-generation.md`](../guides/sdk-client-generation.md) 更新 `api.ts` / `client.ts`。人类明确要放弃本地定制并重新生成完整脚手架时，可使用 `--force --yes`。
 
@@ -40,7 +40,8 @@ rabetbase api pull --appcode app-order-001 --format compress
 多应用模式下：
 - **不加 `--app` / `--appcode`**：遍历已配置应用（默认仅 **项目** `.rabetbase.json` 中的 `apps`；若需包含全局里合并进来的应用，加 **`--global`**）
 - **加 `--app <name>`**：仅拉取指定应用
-- **加 `--appcode <code>`**：反查到对应 app profile，使用其 cookie/env/apiDir
+- **加 `--appcode <code>`**：反查到对应 app profile 时，使用其 `region`、cookie 和 apiDir；没有匹配 profile 时使用顶层国家/地区回退
+- 每个应用请求前都会切换到其有效 `region`，不会沿用上一个应用的官方服务地址
 
 ## 配置作用域
 
@@ -52,11 +53,11 @@ rabetbase api pull --appcode app-order-001 --format compress
 
 | 文件 | 行为 |
 |------|------|
-| `sdk-config.ts` | **每次刷新**。只含必要的最终 `runtimeDomain`，不含凭证 |
+| `sdk-config.ts` / `<prefix>-sdk-config.ts` | **每次刷新**。默认应用无前缀，非默认应用使用应用名前缀；只含必要的最终 `runtimeDomain`，不含凭证 |
 | `<prefix>-api.ts` | 文件缺失时写入脚手架（含当前 `models`）；已存在时默认跳过，`--force` 时整体替换 |
 | `<prefix>-client.ts` | 文件缺失时写入 Cookie-first `createClient`；已存在时默认跳过，`--force` 时整体替换 |
 
-默认 `prefix` 为空（单应用），多应用非 default 应用使用应用名作为 prefix。
+默认 `prefix` 为空（单应用或默认应用），多应用非 default 应用使用应用名作为 prefix；生成的 `<prefix>-client.ts` 导入同前缀 SDK 路由文件。
 
 `project create` 在拷贝空 demo 脚手架后会覆盖写入一次 TypeScript，以便带上真实 models。首次拉取失败时，恢复提示会要求执行 `rabetbase api pull --force --yes`，避免占位脚手架被继续保留。日常 `api pull` 遇到已有 `api.ts` / `client.ts` 时跳过，只刷新 `sdk-config.ts` 并返回 Dataset 事实。
 

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

@@ -48,6 +48,9 @@ rabetbase app list --remote
 | `definedIn` | `global` / `project` / `both`（合并视图下；单边视图下为对应侧） |
 | `isDefault` | 是否为当前解析出的默认应用 |
 | `isCurrent` | 是否为当前激活应用（合并视图） |
+| `region` | profile 中显式保存的国家/地区；未配置时为 `null` |
+| `effectiveRegion` | 当前应用最终使用的国家/地区 |
+| `regionSource` | `app` / `project` / `global` / `default`，表示有效值来源 |
 
 **jq 示例**（只取命名应用名）：`--format json --jq '.data.items[] | select(.named) | .name'`
 

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

@@ -38,7 +38,7 @@ rabetbase bff list --appcode app-xxxxxxxx
 
 ## 输出
 
-默认返回精简列表（id, functionName, description, scriptType）。`--verbose` 返回完整对象。
+CLI 自动聚合服务端全部分页。默认返回精简列表（id, functionName, description, scriptType）。`--verbose` 返回完整对象。
 
 ## Backend Function 脚本类型
 

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

@@ -29,6 +29,8 @@ rabetbase bff pull --type HOOK --force --format json
 
 `--dry-run` 时返回预览对象，包含远端脚本、目标 `filePath` 和预期状态（如 `would_pull` / `conflict`）。
 
+远端脚本列表会自动聚合服务端全部分页；不会只同步第一页。
+
 ## 提示
 
 - 默认会保护本地未同步改动，冲突时进入 `skipped: local unsynced changes`

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

@@ -23,6 +23,8 @@ rabetbase bff status --remote --format json
 - `unchanged`：本地与 lock 一致
 - `remoteOnly`：仅远端存在（需 `--remote`）
 
+启用 `--remote` 时，CLI 会自动聚合远端 Backend Function 的全部分页后再计算 `remoteOnly`。
+
 ## 提示
 
 - `push` 前先看 `status`

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

@@ -33,6 +33,8 @@ rabetbase workspace init --appcode <code>
 
 CLI 对旧版顶层 `appcode` 仍兼容读取，但它已经不是推荐主模型。
 
+CLI 新写入或重写配置时不会持久化默认内部路由字段；历史文件仍保持读取兼容。若顶层存在非默认值，而某个应用显式回到默认值，写入时会把非默认值下沉到实际继承它的应用，再省略默认标记，确保配置精简且生效语义不变。
+
 ## 兼容读取的单应用模式
 
 兼容读取的最简配置只需 `appcode` 和 `env`：
@@ -59,7 +61,6 @@ CLI 对旧版顶层 `appcode` 仍兼容读取，但它已经不是推荐主模
 ```json
 {
   "appcode": "app-xxx",
-  "env": "production",
   "locale": "en-US",
   "cookie": "session-cookie-value",
   "accessKey": "ak-xxx",
@@ -94,20 +95,20 @@ CLI 对旧版顶层 `appcode` 仍兼容读取，但它已经不是推荐主模
     },
     "product": {
       "appcode": "app-zzzzzzzz",
-      "env": "production",
+      "region": "id",
       "apiDir": "./src/api/product"
     }
   }
 }
 ```
 
-每个 app profile 可单独覆盖普通顶层字段。唯一 app 自动激活；两个及以上 app 必须通过 `--app <name>` 临时选择，或用 `defaultApp` 持久选择，CLI 不按 JSON key 顺序猜测。`riskLevel` 是安全例外：默认值为 `write`，全局、项目与 profile 决定基础上限并取最严格值。权限不足时停止执行并请求授权人员处理；Agent 和自动化脚本不得自行修改 `riskLevel`、配置文件、环境变量或尝试提权。
+每个 app profile 可单独覆盖普通顶层字段。顶层 `region` 是共享国家/地区回退值，`apps.<name>.region` 优先；因此同一个项目可以同时登记中国大陆与印尼应用。唯一 app 自动激活；两个及以上 app 必须通过 `--app <name>` 临时选择，或用 `defaultApp` 持久选择，CLI 不按 JSON key 顺序猜测。`riskLevel` 是安全例外：默认值为 `write`，全局、项目与 profile 决定基础上限并取最严格值。权限不足时停止执行并请求授权人员处理；Agent 和自动化脚本不得自行修改 `riskLevel`、配置文件、环境变量或尝试提权。
 
 管理命令（声明式 flags，非位置参数）：
 
 ```bash
 rabetbase workspace add order --appcode app-order-001 --env daily
-rabetbase workspace add product --appcode app-product-002
+rabetbase workspace add product --appcode app-product-002 --region id
 rabetbase workspace use --app order
 rabetbase app list
 rabetbase workspace remove product --yes
@@ -120,7 +121,7 @@ rabetbase workspace remove product --yes
 | 字段 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
 | `appcode` | string | — | 顶层单应用兼容字段。新写入优先使用 `apps`。兼容旧名 `app` |
-| `env` | string | `"production"` | 环境。可选值：`production`、`daily`（配置文件若仍为旧值 `online`，加载时会规范为 `production`） |
+| `env` | string | — | 历史兼容字段；默认连接不落盘，读取旧配置时仍兼容 |
 | `locale` | string | `"en-US"` | 应用本地化设置（不是 CLI 语言；目前命令尚未消费） |
 | `cookie` | string | — | 内联 session cookie。设置后优先于 `~/.lovrabet/cookie` 文件 |
 | `accessKey` | string | — | Access Key 认证（预留，未来替代 cookie） |
@@ -146,7 +147,8 @@ rabetbase workspace remove product --yes
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `appcode` | string | **必填**。该应用的 appcode |
-| `env` | string | 覆盖顶层 `env` |
+| `region` | string | 覆盖顶层国家/地区；当前可写 `cn`、`id`。显式 `cn` 会保留，以便覆盖顶层 `id` |
+| `env` | string | 历史兼容字段；默认连接不落盘 |
 | `apiDir` | string | 覆盖顶层 `apiDir` |
 | `cookie` | string | 覆盖顶层 `cookie` |
 | `accessKey` | string | 覆盖顶层 `accessKey` |
@@ -160,9 +162,9 @@ rabetbase workspace remove product --yes
 每个配置项的解析优先级从高到低（`appcode` 不从环境变量自动解析，必须来自 `--appcode` 或配置文件）：
 
 ```
-CLI flag (--appcode, --env, --format, --app ...)
+CLI flag (--appcode, --format, --app ...)
   ↓
-当前项目 app profile / 顶层字段
+当前项目 app profile（包括 `region`）/ 顶层字段
   ↓
 环境变量 (RABETBASE_ENV, RABETBASE_FORMAT ...)
   ↓
@@ -243,7 +245,6 @@ rabetbase dataset list --appcode "$RABETBASE_APPCODE"
     },
     "product": {
       "appcode": "app-product-002",
-      "env": "production",
       "riskLevel": "read"
     }
   }

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

@@ -22,9 +22,9 @@ rabetbase doctor check
 | Built-in Skill | 目标路径、包版本、Skill 版本、内容状态；不一致时给出 `rabetbase cli-skill install` 修复命令 |
 | Config Files | 全局和项目级配置文件路径 |
 | Config JSON | 分别检测全局/项目配置文件是否为**合法 JSON**；非法时标红并给出解析错误（常见于尾随逗号、注释等，会导致该侧配置在合并时被忽略） |
-| Country/Region Configuration | 检查项目与全局 `region`；显式未知值会标明来源，并给出对应作用域的 `config delete region` 修复命令 |
+| Country/Region Configuration | 检查项目、全局和各 app profile 的 `region`；显式未知值会标明来源与修复位置 |
 | Merged Config | 合并后的所有配置项（appCode / env / cookie / apiDir 等） |
-| Apps | 多应用模式下的应用列表及各自配置 |
+| Apps | 多应用模式下的应用列表及各自显式或继承的 `region` |
 | API Endpoints | 最终生效的 region 与域名（user / api / runtime / skill / kb / app）；KB 管理与 search 共用 SmartCode Java origin |
 | Auth | 登录状态及 cookie 有效性 |
 

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

@@ -31,7 +31,11 @@ rabetbase page push --id 1020286 --dry-run --format json
 ## 行为说明
 
 - 单页模式：校验本地文件、读取 lock、比对远端版本，再调用更新接口
-- 批量模式：只推送本地 hash 有变更的页面；无基线时会 fail-fast，提示先执行 `page pull`
+- 批量模式：先完成远端版本检查与 `LrSmartJsx` 编译准备，再只推送结果 hash 与 lock 不同的页面；无基线时会 fail-fast，提示先执行 `page pull`
+- 遇到 `LrSmartJsx` 时，以 `props.render.source` 为唯一手工维护内容；源码变化、`render.value` 缺失或远端无编译值时，CLI 调用平台正式编译器生成 `value`
+- CLI 会把 `LrSmartJsx.props._context` 规范为 `{ "type": "JSExpression", "value": "this" }`；`source` 组件仍通过 `props.env` / `props.sdkClient` 消费平台注入能力
+- `--dry-run` 同样执行编译校验，但不会更新页面；任一组件编译失败时整页不提交
+- 不要手写或直接修改 `render.value`；当 `source` 未变化但本地 `value` 与远端不一致时，命令会拒绝推送并提示修改 `source`
 - 推送后会再次拉取远端 canonical schema，并覆盖本地文件和 lock，避免本地保留非 canonical 版本
 
 ## 提示

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

@@ -9,7 +9,7 @@
 ## 命令
 
 ```bash
-rabetbase workspace init --appcode <code> [--env daily|production]
+rabetbase workspace init --appcode <code> [--region cn|id]
 rabetbase workspace init --app <name> --appcode <code>
 rabetbase workspace use --app <name>
 rabetbase workspace use --app <name> --appcode <code>
@@ -23,7 +23,8 @@ rabetbase workspace remove <name> [--global]
 |------|------|
 | `--app <name>` | 工作空间里的应用名，如 `crm`、`order` |
 | `--appcode <code>` | 应用 App Code；不知道本地应用名时可直接使用 |
-| `--env <env>` | 写入该 app profile 的环境：`daily` / `production` |
+| `--region <region>` | 写入该 app profile 的国家/地区：`cn` / `id` |
+| `--env <env>` | 历史兼容参数；默认内部路由值不会写入 app profile |
 | `--apiDir <dir>` | 写入该 app profile 的 API 目录 |
 | `--defaultFormat <format>` | 写入该 app profile 的默认输出格式 |
 | `--pageSize <n>` | 写入该 app profile 的分页大小 |
@@ -39,6 +40,7 @@ rabetbase workspace remove <name> [--global]
 - `workspace use --app crm`：切换当前目录默认应用；如果 `crm` 只存在于全局配置，会复制非敏感 profile 字段到当前目录。
 - `workspace use --app crm --appcode app-xxx`：直接在当前目录新增或更新 `crm`，并设为默认应用。
 - `workspace add crm --appcode app-xxx`：登记应用 profile（默认写当前项目，`--global` 写全局）。第一个应用不写 `defaultApp`；增加第二个应用时保留原应用为默认。已存在则更新。
+- `region` 省略时继承项目顶层、再继承全局回退；显式传 `--region cn` 或 `--region id` 时只作用于该应用。
 - `workspace remove crm`：移除本地应用 profile。默认按「项目优先、其次全局」定位要删的那一层，`--global` 强制删全局；只剩一个应用时删除冗余的 `defaultApp`，仍有多个应用时才自动切换；若该应用在项目与全局都有定义，只删单侧并在结果里提示另一侧仍存在。
 
 `workspace init` / `workspace use` 不会从全局配置复制 `cookie` / `accessKey` 到项目文件。若当前项目文件里原本已有这些字段，更新应用时会保留它们。

package/skills/rabetbase.manifest.json

@@ -2,8 +2,8 @@
   "schemaVersion": 1,
   "name": "rabetbase",
   "packageName": "@lovrabet/rabetbase-cli",
-  "packageVersion": "2.5.2",
-  "skillVersion": "2.5.2",
+  "packageVersion": "2.5.3-beta.1",
+  "skillVersion": "2.5.3-beta.1",
   "files": [
     "SKILL.md",
     "guides/backend-function.md",
@@ -140,5 +140,5 @@
     "references/rabetbase-user-account.md",
     "references/rabetbase-workspace.md"
   ],
-  "digest": "85bd9afc1c6af3d817dd6a6317e0c1cee9fce3e1df76904165e79d5e6a9e63a1"
+  "digest": "737d15dee0512e879514bb4ab5e657b2e817656ba483dd285f5fbfe59adabc05"
 }

package/templates/generate-api/client.ts.tpl

@@ -9,7 +9,7 @@
 
 import { createClient, CONFIG_NAMES } from "@lovrabet/sdk";
 import "./{ApiFileName}"; // 导入配置文件，执行 registerModels() 注册
-import { LOVRABET_SDK_CONFIG } from "./sdk-config";
+import { LOVRABET_SDK_CONFIG } from "./{SdkConfigFileName}";
 
 /**
  * 主要的客户端实例