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

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

@@ -1 +1 @@
-function a294_0x35f4(){var _0x2b5c44=['6860920AYCZbb','503556asmQvk','62460hfOfnD','736850bwWWEF','114qQnRaD','428005YcdcTT','8841889unYpPG','3272103vNdpFQ','303oGILBb'];a294_0x35f4=function(){return _0x2b5c44;};return a294_0x35f4();}(function(_0x245cc1,_0x203cbc){var _0x466e06=a294_0x4a08,_0x41ab4e=_0x245cc1();while(!![]){try{var _0xf3a117=parseInt(_0x466e06(0x11f))/0x1+parseInt(_0x466e06(0x11d))/0x2+-parseInt(_0x466e06(0x124))/0x3*(-parseInt(_0x466e06(0x11e))/0x4)+-parseInt(_0x466e06(0x121))/0x5*(parseInt(_0x466e06(0x120))/0x6)+-parseInt(_0x466e06(0x122))/0x7+parseInt(_0x466e06(0x125))/0x8+parseInt(_0x466e06(0x123))/0x9;if(_0xf3a117===_0x203cbc)break;else _0x41ab4e['push'](_0x41ab4e['shift']());}catch(_0x2ad90a){_0x41ab4e['push'](_0x41ab4e['shift']());}}}(a294_0x35f4,0xdb163));import{setActiveCookie,clearActiveCookie}from'../core/api-client.js';function a294_0x4a08(_0x257199,_0x1b08c7){_0x257199=_0x257199-0x11d;var _0x35f4d1=a294_0x35f4();var _0x4a088e=_0x35f4d1[_0x257199];return _0x4a088e;}export async function withActiveCookie(_0x3eecd9,_0x564d48){setActiveCookie(_0x3eecd9);try{return await _0x564d48();}finally{clearActiveCookie();}}
+function a296_0x3226(){var _0x5048a7=['425IzPSut','452845kLpuqo','4ddlWKJ','10sQEJNQ','7061576XVKsCx','41016drgkZu','319815OIFEOS','2028387axsxNW','6700260VjYSvR','1893648lxsDzc'];a296_0x3226=function(){return _0x5048a7;};return a296_0x3226();}function a296_0x16fa(_0x76ec02,_0x124570){_0x76ec02=_0x76ec02-0x15d;var _0x3226ee=a296_0x3226();var _0x16fac0=_0x3226ee[_0x76ec02];return _0x16fac0;}(function(_0x1f076e,_0x3caed4){var _0x5891f6=a296_0x16fa,_0x5cd822=_0x1f076e();while(!![]){try{var _0x650e4d=-parseInt(_0x5891f6(0x15e))/0x1+-parseInt(_0x5891f6(0x166))/0x2+parseInt(_0x5891f6(0x164))/0x3*(parseInt(_0x5891f6(0x15f))/0x4)+parseInt(_0x5891f6(0x15d))/0x5*(-parseInt(_0x5891f6(0x162))/0x6)+parseInt(_0x5891f6(0x165))/0x7+parseInt(_0x5891f6(0x161))/0x8+parseInt(_0x5891f6(0x163))/0x9*(-parseInt(_0x5891f6(0x160))/0xa);if(_0x650e4d===_0x3caed4)break;else _0x5cd822['push'](_0x5cd822['shift']());}catch(_0x55a9f2){_0x5cd822['push'](_0x5cd822['shift']());}}}(a296_0x3226,0x7a01e));import{setActiveCookie,clearActiveCookie}from'../core/api-client.js';export async function withActiveCookie(_0x1377b6,_0x538d32){setActiveCookie(_0x1377b6);try{return await _0x538d32();}finally{clearActiveCookie();}}

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

@@ -1 +1 @@
-(function(_0x12c9c8,_0x490437){var _0x25c34b=a295_0x57d4,_0x51a524=_0x12c9c8();while(!![]){try{var _0x2dc9a4=-parseInt(_0x25c34b(0xfe))/0x1*(-parseInt(_0x25c34b(0x103))/0x2)+-parseInt(_0x25c34b(0x10b))/0x3*(parseInt(_0x25c34b(0x102))/0x4)+-parseInt(_0x25c34b(0xff))/0x5*(-parseInt(_0x25c34b(0x105))/0x6)+-parseInt(_0x25c34b(0x100))/0x7+-parseInt(_0x25c34b(0x108))/0x8*(-parseInt(_0x25c34b(0x109))/0x9)+parseInt(_0x25c34b(0x107))/0xa*(parseInt(_0x25c34b(0x106))/0xb)+-parseInt(_0x25c34b(0x10a))/0xc*(parseInt(_0x25c34b(0x101))/0xd);if(_0x2dc9a4===_0x490437)break;else _0x51a524['push'](_0x51a524['shift']());}catch(_0x49e542){_0x51a524['push'](_0x51a524['shift']());}}}(a295_0xf87a,0x92bb3));function a295_0x57d4(_0x347494,_0x3f73c0){_0x347494=_0x347494-0xfe;var _0xf87a73=a295_0xf87a();var _0x57d4b8=_0xf87a73[_0x347494];return _0x57d4b8;}export function writeCliSideChannelLine(_0x4d6a2b){var _0x44c375=a295_0x57d4;process[_0x44c375(0x104)]['write'](_0x4d6a2b+'\x0a');}function a295_0xf87a(){var _0x54e53d=['8802iUpPHE','stderr','1197606dQpsfC','66ZenEIY','1555530SvqWgs','9704KFKBjz','1395JIwMXY','36wpnZuG','269697VNoVsU','251xUEcWa','25GDUeRe','2011296KOWGhp','8952463FdAHdo','12jcZJZh'];a295_0xf87a=function(){return _0x54e53d;};return a295_0xf87a();}
+function a297_0x35b0(_0x59e167,_0x346f96){_0x59e167=_0x59e167-0x15b;var _0x42c766=a297_0x42c7();var _0x35b04e=_0x42c766[_0x59e167];return _0x35b04e;}function a297_0x42c7(){var _0x3402ec=['12LoQOFP','21384kmdNJv','92dsYKfW','7JOWCPC','24oKSccq','117VjrRCZ','7692509liEUXr','219390aLVvOd','59474mimdkV','542488uLnbvz','370245WWdEur','3893334YRRxAS'];a297_0x42c7=function(){return _0x3402ec;};return a297_0x42c7();}(function(_0x28a5df,_0x28f9f0){var _0x381714=a297_0x35b0,_0x369f95=_0x28a5df();while(!![]){try{var _0x41f6f8=parseInt(_0x381714(0x15c))/0x1+parseInt(_0x381714(0x162))/0x2*(-parseInt(_0x381714(0x161))/0x3)+-parseInt(_0x381714(0x164))/0x4*(-parseInt(_0x381714(0x15e))/0x5)+-parseInt(_0x381714(0x15f))/0x6*(-parseInt(_0x381714(0x163))/0x7)+-parseInt(_0x381714(0x15d))/0x8+-parseInt(_0x381714(0x165))/0x9*(-parseInt(_0x381714(0x15b))/0xa)+parseInt(_0x381714(0x166))/0xb*(-parseInt(_0x381714(0x160))/0xc);if(_0x41f6f8===_0x28f9f0)break;else _0x369f95['push'](_0x369f95['shift']());}catch(_0x121291){_0x369f95['push'](_0x369f95['shift']());}}}(a297_0x42c7,0x53b3e));export function writeCliSideChannelLine(_0x1b341c){process['stderr']['write'](_0x1b341c+'\x0a');}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lovrabet/rabetbase-cli",
-  "version": "2.5.0",
+  "version": "2.5.1-beta.1",
   "description": "Developer CLI for Lovrabet apps, datasets, pages, SQL, Backend Function, database connections, skills, and AI agent workflows.",
   "license": "SEE LICENSE IN LICENSE",
   "keywords": [
@@ -43,7 +43,6 @@
     "prebuild:dev": "node scripts/generate-build-info.js",
     "build:dev": "node scripts/clean-build-output.mjs && tsc && tsc-alias",
     "start": "tsc --watch",
-    "sync-template": "node scripts/sync-template.js",
     "sync:cdn": "node scripts/sync-cdn-assets.js",
     "verify:bundled-jq": "node scripts/verify-bundled-jq.mjs",
     "regression:release-smoke": "node scripts/regression-release-smoke.mjs",

package/skills/rabetbase/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rabetbase
-version: 2.5.0
+version: 2.5.1-beta.1
 description: "Lovrabet 开发工作流 CLI — 通过 rabetbase 命令管理数据集、数据库连接（dblink）、数据列表页（Data List Page）、自定义页面（Custom Page）、SQL 查询、Backend Function 脚本、通知配置、企业知识库、菜单事实读取与同步、开发角色与协作者、应用文件、面向票证类业务材料文字与结构化字段提取的 OCR、代码生成，以及平台问题上报。触发词：数据集、数据表、dataset relation-audit、dataset delete、dataset restore、废弃数据集、恢复数据集、dataset rename、dataset field-update、dataset extend-update、dataset business-groups、dataset business-group-update、businessGroup、字段对象更新、doType、options、数据列表页、Data List Page、自定义页面、Custom Page、page create、page custom-list、page custom-detail、page custom-update、page custom-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 create、db update、db delete、db test、db tables、db diff、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 消息通知、Backend Function 消息通知、notification config-list、EMAIL configCode、通知配置、notification.send、企业知识库、公司知识、公共知识、kb search、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 visibility-update、菜单显示、菜单隐藏、visible、menu external-link-create、menu external-link-update、menu rename、菜单改名、外链菜单创建、外链 URL 更新、菜单异常审计、菜单手动删除清单、menu sync、menu asset-update、菜单资源更新、menu move、菜单移动、开发角色、开发协作者、role、role list、role user-add、role user-remove、user-resolve、加入开发者、ADMIN、DEV、OWNER、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:
@@ -18,7 +18,7 @@ metadata:
 
 ## 前置条件
 
-1. **连接配置与认证分离**：首次使用先执行 `rabetbase config init`。交互模式选择 `Mainland China (cn)` 或 `Indonesia (id)`；非交互模式显式传 `--region cn|id`，未传时默认 `cn`。企业独立部署使用 `--domain-config <file>` 或六个 `--*-domain` flags。`config init` 固定重建全局节点/Domain 配置，保留 Cookie、AccessKey、format、locale 和应用绑定，但不登录、不绑定项目；随后再执行 `rabetbase auth login`
+1. **连接配置与认证分离**：首次使用先执行 `rabetbase config init`。交互模式选择 `Mainland China (cn)` 或 `Indonesia (id)`；非交互模式显式传 `--region cn|id`，未传时默认 `cn`。尚未发布的 `global` 不出现在新配置入口中。企业独立部署使用 `--domain-config <file>` 或对应 `--*-domain` flags；自定义 HTTPS 本地回调时同时提供 Local 与 Certificate Domain。当前所有已开放节点和独立部署统一使用中国大陆 CDN 配置，Lovrabet 服务 Domain 仍分别解析。`config init` 固定重建全局节点/Domain 配置，保留 Cookie、AccessKey、format、locale 和应用绑定，但不登录、不绑定项目；随后再执行 `rabetbase auth login`
 2. **AppCode**：确保 `.rabetbase.json` 中设置了 `apps`（单应用自动选中；多应用再配 `defaultApp`），或兼容读取的顶层 `appcode`，或通过 `--appcode <code>` / `--app <name>` 传入。旧 `.lovrabet.json` 不会自动读取
 3. **配置文件**：`rabetbase config init` 固定写全局 `~/.rabetbase.json`，不接受项目作用域；默认 `cn` 不落冗余 `region`。官方节点模式清理显式和遗留 Domain，独立部署模式清理旧 `region`/Domain 后写入所提供的覆盖值。完整字段说明见 [`.rabetbase.json` 配置参考](references/rabetbase-config.md)。当前目录应用绑定使用下方 `workspace init`，二者不要混用
 4. **工作目录应用绑定**：当前目录要固定使用某个应用时，使用 `rabetbase workspace init --appcode <code>` 或 `rabetbase workspace use --app <name>`（选型见「app vs workspace 职责边界」）
@@ -158,7 +158,7 @@ metadata:
 - **普通写操作默认当前项目**（`workspace add`、`config set`、`project create` 等），除非用户**显式**传 `--global`；`config init` 是首次连接配置入口，固定写全局配置。
 - **不要**在用户未要求时给命令加 `--global`** — 默认行为已是「项目优先」；只有用户明确要改全局配置或不在项目内且意图写全局时才使用。
 - **`config set`**：在**没有**项目配置文件（当前目录未解析到 `.rabetbase.json`）且**未**传 `--global` 时，CLI **拒绝执行**并提示使用 `--global` 或先 `rabetbase workspace init --appcode <code>`，**不会**静默写入全局。
-- **`project create`** 生成的新项目 `.rabetbase.json` **只继承**少量全局偏好（如 `cookie` / `locale` / `format` / `riskLevel` 等），**不会**把全局 `apps` / `defaultApp` 带入新项目文件；同时生成浏览器安全的 `src/api/sdk-config.ts`：默认中国大陆节点不写路由，ID 写 `region: "id"`，非默认企业 Runtime 写 `runtimeDomain` 且优先于 region，不下发认证配置。模板的 Vite 本地开发和 preview 地址也按项目 region 选择对应的 HTTPS 域名与证书：ID 使用 `https://dev.lovrabet.id`，中国大陆使用 `https://dev.lovrabet.com`。
+- **`project create`** 生成的新项目 `.rabetbase.json` **只继承**少量全局偏好（如 `cookie` / `locale` / `format` / `riskLevel` 等），**不会**把全局 `apps` / `defaultApp` 带入新项目文件；同时生成浏览器安全的 `src/api/sdk-config.ts` 与 `rabetbase.routing.json`。中国大陆、ID、Global 的 Lovrabet 服务 Domain、本地地址和证书由统一 Routing Profile 解析；当前共享资源统一使用中国大陆 CDN 配置，独立部署写客户最终服务 Domain。两个生成文件都不下发认证配置，后续 `api pull` 会刷新。
 - **`api pull` / `api list`**：默认仅针对**项目** `apps`；需要合并全局已登记应用时加 `--global`（见各命令 reference）。
 - **`app list`**：默认展示**合并**后的全量；`--global` 仅全局、`--project` 仅项目（见 [`rabetbase app list`](references/rabetbase-app-list.md)）。
 
@@ -273,6 +273,10 @@ const result = await client.bff.execute<DashboardData>({
 });
 ```
 
+### Personal Backend Function 调用
+
+前端或 Node 服务通过 `client.personal.bff.execute({ scriptId, params })` 调用 Personal Backend Function。认证方式、兼容性检查、`undefined` 处理和返回值约定见 [`typescript-sdk.md`](guides/typescript-sdk.md#4-前端--node-调用-personal-backend-function-api)。
+
 ### 前端 vs Backend Function 关键差异
 
 |                 | 前端 SDK                                     | Backend Function (context.client)                 |
@@ -284,6 +288,7 @@ const result = await client.bff.execute<DashboardData>({
 | `create()` 返回 | 以 SDK 文档/类型为准                         | 新记录 ID，不是完整对象              |
 | SDK 初始化能力  | `createClient` / `registerModels`            | 不可用；`context.client` 由平台注入  |
 | 调 Backend Function          | `client.bff.execute({ scriptName, params })` | —                                    |
+| 调 Personal Backend Function | `client.personal.bff.execute({ scriptId, params })` | —                              |
 
 ## 意图 → 命令索引
 
@@ -357,7 +362,7 @@ const result = await client.bff.execute<DashboardData>({
 | 推送本地数据列表页 schema | [`rabetbase page push --id <pageId>`](references/rabetbase-page-push.md) | 推送后自动回拉 canonical schema 覆盖本地 |
 | 恢复已删除页面 | [`rabetbase page restore --id <pageId>`](references/rabetbase-page-restore.md) | 支持 `DATA_LIST|CUSTOM` 自动识别；跨类型同 ID 时显式传 `--page-type` |
 | 数据库连接（dblink）/ 测连 / 结构分析 | [`rabetbase db list`](references/rabetbase-db-list.md) 起 | **`id`**、**trace/plan id** 与“终态 + 复跑 diff”完成口径见 [database-connection-workflow.md](guides/database-connection-workflow.md)；各子命令见 `references/rabetbase-db-*.md` |
-| 生成 / 更新 API 客户端代码 | [`rabetbase api pull`](references/rabetbase-api-pull.md) → [`sdk-client-generation.md`](guides/sdk-client-generation.md) | `api pull` 拉 Dataset 事实并刷新 `sdk-config.ts`；已有 `api.ts`/`client.ts` 按 guide 合并更新 |
+| 生成 / 更新 API 客户端代码 | [`rabetbase api pull`](references/rabetbase-api-pull.md) → [`sdk-client-generation.md`](guides/sdk-client-generation.md) | `api pull` 拉 Dataset 事实并刷新 `sdk-config.ts` 与 `rabetbase.routing.json`；已有 `api.ts`/`client.ts` 按 guide 合并更新 |
 | 查看生成的 API 模型 | [`rabetbase api list`](references/rabetbase-api-list.md) | 列出已生成的数据模型 |
 | 查看现有 SQL | [`rabetbase sql list --name "xxx"`](references/rabetbase-sql-list.md) | 分页，按名称过滤；默认查当前决议到的单个应用 |
 | 查看 SQL 详情 | [`rabetbase sql detail --sqlcode xxx`](references/rabetbase-sql-detail.md) | 含完整 SQL 内容和参数定义 |
@@ -489,7 +494,7 @@ const result = await client.bff.execute<DashboardData>({
 
 | 主题                   | Use when                                                                                                              | Guide                                                                       |
 | ---------------------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
-| SDK 完整参数与返回值   | 初始化 client、filter/create、sql.execute、bff.execute、错误处理                                                      | [`typescript-sdk.md`](guides/typescript-sdk.md)                             |
+| SDK 完整参数与返回值   | 初始化 client、filter/create、sql.execute、bff.execute、personal.bff.execute、安全能力检测与错误处理                  | [`typescript-sdk.md`](guides/typescript-sdk.md)                             |
 | 生成 / 更新 api.ts 与 client.ts | `api pull` 之后、模型过期、脚手架缺失、或用户要求修复 SDK 客户端                                                         | [`sdk-client-generation.md`](guides/sdk-client-generation.md)               |
 | SQL MyBatis 与动态 SQL | 写自定义 SQL、`<if>`/`<foreach>`、参数绑定                                                                            | [`sql-mybatis.md`](guides/sql-mybatis.md)                                   |
 | 前端页面开发约束       | React 页、表单、列表、与数据集绑定                                                                                    | [`frontend-development.md`](guides/frontend-development.md)                 |

package/skills/rabetbase/guides/frontend-development.md

@@ -120,6 +120,8 @@ const customer = await client.models.customers.getOne({ id: customerId });
 * 使用 `filter()` 进行列表和条件查询
 * 不要在页面里写循环单条请求
 * 批量查询和性能优化统一参考 `data-api-guidelines.md`
+* 调用 Personal Backend Function 时使用 `client.personal.bff.execute({ scriptId, params })`；先显式校验能力存在，禁止用 `execute?.(...)` 静默吞掉旧版 SDK 或 client 未初始化问题
+* 浏览器只使用当前登录 Cookie，不在前端源码、构建变量或页面配置中保存 Client AK；完整示例与返回值校验见 `typescript-sdk.md`
 
 ## 禁止 Mock 替代正式数据
 

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

@@ -51,7 +51,7 @@ rabetbase api pull --format compress
 export const LOVRABET_SDK_CONFIG = {} as const;
 ```
 
-CLI 可能写入 `region: "id"` 或 `runtimeDomain: "https://…"`。不要手改成认证字段。
+CLI 可能写入 `region: "id"`（由 SDK 1.5.3+ 解析）或 `runtimeDomain: "https://…"`（Global 与独立部署）。不要手改成认证字段。项目根目录 `rabetbase.routing.json` 同时承载模板最终 Domain 与资源策略，也由 CLI 刷新。
 
 ### api.ts
 
@@ -138,9 +138,10 @@ export const lovrabetClient = createClient({
 | `isDefaultConfig` | 默认应用为 `true` |
 | `models[]` | `datasetCode` / `tableName` / `name` / `alias` |
 | `sdkRouting` | `{ region?: "id", runtimeDomain?: string }` |
+| `projectRouting` | `{ path, manifest }`，最终公开 Domain 与资源策略 |
 | `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[]` 为上述对象的数组。
+多应用时 `data.apps[]` 为上述对象的数组，`data.projectRouting` 为项目共享路由清单。

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

@@ -235,6 +235,45 @@ const dashboard = await client.bff.execute<DashboardData>({
 console.log(dashboard.userCount);
 ```
 
+## 4. 前端 / Node 调用 Personal Backend Function API
+
+Personal Backend Function 通过数值型 `scriptId` 定位，`params` 必须是业务契约允许的对象。返回值是个人函数直接 `return` 的业务数据，不带 `execSuccess` 或 `execResult` 包装。
+
+```typescript
+interface DashboardData {
+  userCount: number;
+}
+
+const personalBff = client?.personal?.bff;
+if (typeof personalBff?.execute !== "function") {
+  throw new Error("client.personal.bff.execute is not available");
+}
+
+const dashboard = await personalBff.execute<DashboardData>({
+  scriptId: 123,
+  params: { userId: "123" },
+});
+
+if (!dashboard || typeof dashboard.userCount !== "number") {
+  throw new Error("Unexpected Personal Backend Function response");
+}
+```
+
+认证边界：
+
+- 浏览器 client 使用当前登录 Cookie。不要把 Cookie、AccessKey、SecretKey 或 token 写进前端源码、构建变量、页面配置或日志。
+- Node 服务使用 Client AK 时，凭据只保存在服务端，并显式设置 `authMode: "client-ak"`。
+- Personal Backend Function 不支持 `authMode: "openapi"`。
+
+兼容与 `undefined` 安全规则：
+
+- 可选链只用于读取能力：`const personalBff = client?.personal?.bff`。
+- 禁止调用 `client.personal?.bff?.execute?.(...)`。方法缺失时该写法会静默返回 `undefined`，无法与业务函数的空返回可靠区分。
+- 能力不存在时立即抛出明确错误，提示升级到包含 `client.personal.bff.execute` 的 SDK 版本。
+- 检测通过后通过 `personalBff.execute(...)` 调用；不要提取成 `const execute = personalBff.execute` 后裸调用，以免丢失方法上下文。
+- 不以 `result === undefined` 作为能力检测；根据个人函数已确认的返回契约校验必需字段和空态。
+- 接入页面前，先通过 `lovrabet personal-bff exec --id <id> --params '<json>' --format compress` 核对同一 `scriptId` 的字段、空态和错误形状。
+
 ## 异常处理底线
 
 所有通过 `client` 发起的网络调用都可能抛出 HTTP 级别的错误，AI 必须养成使用 `try...catch` 包裹代码的习惯，并识别 `LovrabetError`。
@@ -260,4 +299,7 @@ try {
 * [ ] `where` 对象里是否老老实实带了 `$eq` 等操作符？
 * [ ] 处理 SQL 的返回值时，判断了 `execSuccess` 吗？
 * [ ] 处理 Backend Function 的返回值时，是不是直接使用了业务数据？
+* [ ] 调 Personal Backend Function 前，是否显式校验了 `client.personal.bff.execute`，且没有使用可选调用？
+* [ ] 浏览器代码是否只依赖登录 Cookie，没有写入 Client AK 或其他凭据？
+* [ ] 是否按已确认契约校验 Personal Backend Function 的返回形状，而不是用 `undefined` 猜测能力状态？
 * [ ] 加入了 `try...catch` 块防止整个应用崩溃吗？

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 脚手架。
+拉取当前 App 下所有数据集（Dataset）的元信息，刷新 `src/api/sdk-config.ts` 与项目根目录 `rabetbase.routing.json`，并在 `api.ts` / `client.ts` **缺失时**写入 Cookie-first 脚手架。
 
 已有 TypeScript **不会被覆盖**。Agent 必须用返回的 `data.models` 按 [`sdk-client-generation.md`](../guides/sdk-client-generation.md) 更新 `api.ts` / `client.ts`。人类若要重新得到脚手架，删除对应文件后再跑本命令。
 
@@ -48,7 +48,8 @@ rabetbase api pull --appcode app-order-001 --format compress
 
 | 文件 | 行为 |
 |------|------|
-| `sdk-config.ts` | **每次刷新**。只含 `region` / `runtimeDomain`，不含凭证 |
+| `sdk-config.ts` | **每次刷新**。只含必要的 `region` / `runtimeDomain`，不含凭证 |
+| `rabetbase.routing.json` | **每次刷新**。只含最终 Domain、资源策略与本地路由，不含凭证 |
 | `<prefix>-api.ts` | 文件缺失时写入脚手架（含当前 `models`）；已存在则跳过 |
 | `<prefix>-client.ts` | 文件缺失时写入 Cookie-first `createClient`；已存在则跳过 |
 
@@ -65,12 +66,13 @@ rabetbase api pull --appcode app-order-001 --format compress
 | `isDefaultConfig` | 默认应用为 `true` |
 | `models[]` | `datasetCode` / `tableName` / `name` / `alias` |
 | `sdkRouting` | `{ region?: "id", runtimeDomain?: string }` |
+| `projectRouting` | `{ path, manifest }`，manifest 为最终公开路由清单 |
 | `files.api` / `files.client` / `files.sdkConfig` | `{ path, action }`：`created` / `overwritten` / `preserved` / `refreshed` |
 | `needsAgentMerge` | 任一 TypeScript 被 `preserved` 时为 `true` |
 | `apiFilePath` / `clientFilePath` / `sdkConfigPath` | 与 `files.*.path` 相同 |
 | `modelCount` / `datasetCount` | 模型数量 |
 
-多应用时 `data` 为 `{ apps, succeeded, failed }`。
+多应用时 `data` 为 `{ apps, succeeded, failed, projectRouting }`。
 
 ## 生成标识符
 

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

@@ -73,7 +73,9 @@ CLI 对旧版顶层 `appcode` 仍兼容读取，但它已经不是推荐主模
   "runtimeDomain": "https://custom-runtime.example.com",
   "skillDomain": "https://custom-skills.example.com",
   "kbDomain": "https://custom-kb.example.com",
-  "appDomain": "https://custom-app.example.com"
+  "appDomain": "https://custom-app.example.com",
+  "localDomain": "https://custom-local.example.com",
+  "certificateDomain": "https://custom-cert.example.com"
 }
 ```
 
@@ -126,7 +128,7 @@ rabetbase workspace remove product --yes
 | `pageSize` | number | — | 默认分页大小，用于 `sql list` 等分页命令 |
 | `riskLevel` | string | `"write"` | 允许执行的最高风险等级。可选值：`read`、`write`、`high-risk-write` |
 | `apiDir` | string | `"./src/api"` | `api pull` 生成代码的输出目录 |
-| `region` | string | `"cn"`（省略） | 当前开放的官方节点快捷配置：`cn`、`id` |
+| `region` | string | `"cn"`（省略） | 官方节点快捷配置：当前开放 `cn`、`id`；历史 `global` 配置仅保留读取兼容 |
 | `template_base_url` | string | 平台默认 CDN | 模板 CDN 基础 URL，一般无需修改 |
 | `defaultApp` | string | — | 多应用模式下的默认应用名称；单应用省略 |
 | `apps` | object | — | 多应用配置。key 为应用名，value 为 AppProfile（见下方） |
@@ -136,6 +138,8 @@ rabetbase workspace remove product --yes
 | `skillDomain` | string | 节点默认 | SkillHub HTTPS origin 覆盖 |
 | `kbDomain` | string | 跟随 `apiDomain` / 节点 API 默认值 | 企业知识库 HTTPS origin 覆盖；显式配置时优先，`runtimeDomain` 不参与回退 |
 | `appDomain` | string | 节点默认 | 工作台、页面编辑器和发布页面域名 |
+| `localDomain` | string | 独立部署默认 `http://localhost` | 自定义 HTTPS 本地回调 origin；与 `certificateDomain` 同时配置 |
+| `certificateDomain` | string | 节点默认；独立部署无 | 本地 HTTPS 证书服务 origin；与 `localDomain` 同时配置 |
 
 ### AppProfile 字段（`apps.*` 内的每个应用）
 
@@ -194,7 +198,7 @@ CLI flag (--appcode, --env, --format, --app ...)
 配置合并使用固定模型，`inherit` 不是受支持的配置项：
 
 - 项目显式值覆盖全局显式值。
-- 项目存在时，仅从全局白名单继承 `cookie`、`accessKey`、`locale`、`format`、`riskLevel`、`pageSize`、`region` 和六个 Domain（`userDomain` / `apiDomain` / `runtimeDomain` / `skillDomain` / `kbDomain` / `appDomain`）；不继承 `apps` / `defaultApp` / `appcode` / `env`。
+- 项目存在时，仅从全局白名单继承 `cookie`、`accessKey`、`locale`、`format`、`riskLevel`、`pageSize`、`region` 和显式 Domain（服务、本地回调、证书服务）；不继承 `apps` / `defaultApp` / `appcode` 等项目状态。
 - `apps` / `defaultApp` 始终项目隔离，避免研发写操作落到全局应用。
 - `region` 是 Domain fallback profile；显式 Domain 按普通 key 继承和覆盖，不会被 `region` 清除或屏蔽。
 - `riskLevel` 始终取全局与项目顶层的更严格值，项目不能借配置覆盖提权。
@@ -323,7 +327,7 @@ rabetbase config set --key region --value id --global
 rabetbase config init --domain-config ./lovrabet-domains.json
 ```
 
-该文件只接收 `userDomain`、`apiDomain`、`runtimeDomain`、`skillDomain`、`kbDomain`、`appDomain`；值必须是无 path/query/fragment 的 HTTPS origin。完整行为与命令行 flags 见 [`rabetbase config init`](rabetbase-init.md)。
+该文件接收六个服务 Domain，以及可选的 `localDomain`、`certificateDomain`；值必须是无 path/query/fragment 的 HTTPS origin。自定义 HTTPS 本地回调必须同时提供 `localDomain` 与 `certificateDomain`。完整行为与命令行 flags 见 [`rabetbase config init`](rabetbase-init.md)。
 
 也可以逐项覆盖：
 
@@ -337,4 +341,4 @@ rabetbase config set --key kbDomain --value https://your-kb.example.com --global
 rabetbase config set --key appDomain --value https://your-app.example.com --global
 ```
 
-官方模式：`region` 内置完整 Domain 映射，默认 `cn`，配置文件可省略；`id` 只需保存 `"region": "id"`。企业独立部署模式才保存显式 Domain。项目级配置可覆盖全局配置；默认项目合并会继承全局节点配置。
+官方模式：`region` 内置 Routing Profile，默认 `cn`，配置文件可省略；当前新配置只开放 `cn`、`id`，`id` 需保存对应 region。历史文件中的 `global` 仍可读取，但不能通过 `config init` 或 `config set` 新写入。企业独立部署模式才保存显式 Domain。当前所有已开放节点和独立部署统一使用中国大陆 CDN 配置。项目级配置可覆盖全局配置；默认项目合并会继承全局节点配置。

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

@@ -19,21 +19,23 @@ rabetbase config init \
   --runtime-domain https://runtime.customer.example.com \
   --skill-domain https://skills.customer.example.com \
   --kb-domain https://kb.customer.example.com \
-  --app-domain https://app.customer.example.com
+  --app-domain https://app.customer.example.com \
+  --local-domain https://local.customer.example.com \
+  --certificate-domain https://cert.customer.example.com
 ```
 
 ## 交互与默认行为
 
 - 交互执行时选择 `Mainland China (cn)` 或 `Indonesia (id)`，默认选中 `cn`
 - 非交互执行时应显式传 `--region cn|id`；未传 region/Domain 时回退 `cn`
-- 当前只开放 `cn`、`id`；`global` 不可选择
+- 当前只开放 `cn`、`id`；尚未发布的 `global` 不可选择
 
 ## 写入行为
 
 - 固定写入全局 `~/.rabetbase.json`
 - 不使用也不需要 `--global`，不能写入项目配置
 - 默认中国节点 `cn` 不写冗余 `region` 字段
-- 官方节点模式会清除六个显式 Domain，以及遗留的 `agentDomain` / `platformDomain` / `skillHubDomain`
+- 官方节点模式会清除所有显式 Domain，以及遗留的 `agentDomain` / `platformDomain` / `skillHubDomain`
 - 独立部署模式会清除旧 `region`、显式 Domain 和遗留 Domain，再写入本次提供的 Domain
 - 保留 Cookie、AccessKey、format、locale、apps 等无关配置
 - 不负责登录，也不绑定当前项目应用
@@ -49,12 +51,16 @@ rabetbase config init \
   "runtimeDomain": "https://runtime.customer.example.com",
   "skillDomain": "https://skills.customer.example.com",
   "kbDomain": "https://kb.customer.example.com",
-  "appDomain": "https://app.customer.example.com"
+  "appDomain": "https://app.customer.example.com",
+  "localDomain": "https://local.customer.example.com",
+  "certificateDomain": "https://cert.customer.example.com"
 }
 ```
 
 - 每个值必须是 HTTPS origin，不能包含账号、密码、path、query 或 fragment
-- 文件至少提供一个受支持 Domain；企业完整独立部署建议显式提供全部六个
+- 文件至少提供一个受支持 Domain；完整独立部署应提供实际由客户部署的全部服务 Domain
+- 当前所有官方节点和独立部署统一使用中国大陆 CDN 配置；User/App/Runtime 等 Lovrabet 服务 Domain 仍按节点或客户配置分别解析
+- 未提供 `localDomain` / `certificateDomain` 时，本地回调使用 `http://localhost`；自定义 HTTPS 本地回调时两者必须同时提供
 - 同名 `--*-domain` flag 覆盖文件中的值
 - `--region` 与任意独立部署 Domain 互斥，不能混用
 - 未提供的 Domain 会按默认 `cn` 映射回退，因此完整独立部署不要遗漏实际由客户部署的服务入口

package/skills/rabetbase/references/rabetbase-project-create.md

@@ -42,15 +42,16 @@ rabetbase project create my-project --appcode <code> --env production
 - 交互与非交互模式使用同一创建流程，都会安装依赖、格式化代码并写入项目配置
 - 项目模板从 CDN 下载并校验 SHA-256；CDN 不可用、模板不兼容或校验失败时命令停止，修复后重试
 - 新项目中的 `.rabetbase.json` **只继承**全局中的少量偏好及 `region` / Domain 路由配置，**不会**把全局的 `apps` / `defaultApp` 复制进新项目
-- `src/api/sdk-config.ts` 只生成浏览器可公开的非默认 SDK 路由，不会写入 `cookie`、`accessKey` 等认证配置；后续执行 `rabetbase api pull` 会按当前有效配置刷新该文件。`api.ts` / `client.ts` 仅在缺失时由 CLI 写脚手架，已有文件按 [`sdk-client-generation.md`](../guides/sdk-client-generation.md) 更新
+- `src/api/sdk-config.ts` 与 `rabetbase.routing.json` 只生成浏览器可公开的最终路由，不会写入 `cookie`、`accessKey` 等认证配置；后续执行 `rabetbase api pull` 会按当前有效配置刷新。`api.ts` / `client.ts` 仅在缺失时由 CLI 写脚手架，已有文件按 [`sdk-client-generation.md`](../guides/sdk-client-generation.md) 更新
 
 | 当前有效路由 | `src/api/sdk-config.ts` |
 |--------------|-------------------------|
-| 默认 CN，且没有非默认 `runtimeDomain` | `{}`，由 SDK 使用默认 CN 映射 |
-| ID，且没有非默认 `runtimeDomain` | `{ region: "id" }`，由 SDK 结合项目 env 选择 ID Runtime |
-| 非默认企业 `runtimeDomain` | `{ runtimeDomain: "https://…" }`，不再冗余写 region |
+| 默认中国大陆节点 | `{}`，由 SDK 使用默认映射 |
+| ID | `{ region: "id" }`，由 SDK 1.5.3+ 选择 ID Runtime |
+| Global | `{ runtimeDomain: "https://runtime.lovrabet.ai" }`，兼容 SDK 1.5.3 |
+| 独立部署 | `{ runtimeDomain: "https://…" }` |
 
-如果显式 `runtimeDomain` 恰好等于当前 region/env 的 SDK 内置地址，CLI 会把它视为默认值：CN 不写路由，ID 仍只写 `region: "id"`。这样生成项目不会固定当前的具体公共 URL，后续仍可跟随 SDK 的内置映射升级。
+模板依赖 SDK 1.5.3+。CLI 从统一 Routing Profile 生成 `rabetbase.routing.json`，其中只包含最终 User/App/Runtime Domain、资源策略、本地地址和证书 URL，不复制节点注册表。当前所有官方节点和独立部署统一使用中国大陆 CDN 配置，Lovrabet 服务 Domain 仍分别解析。后续执行 `rabetbase api pull` 会刷新两个路由文件。
 
 ## 参考
 

package/skills/rabetbase.manifest.json

@@ -2,8 +2,8 @@
   "schemaVersion": 1,
   "name": "rabetbase",
   "packageName": "@lovrabet/rabetbase-cli",
-  "packageVersion": "2.5.0",
-  "skillVersion": "2.5.0",
+  "packageVersion": "2.5.1-beta.1",
+  "skillVersion": "2.5.1-beta.1",
   "files": [
     "SKILL.md",
     "guides/backend-function.md",
@@ -132,5 +132,5 @@
     "references/rabetbase-user-account.md",
     "references/rabetbase-workspace.md"
   ],
-  "digest": "dca9ab8c944c37266a62b08c870f666f5a3646bcc01098f2750f9b318456a477"
+  "digest": "a115d40353c6e1a7dd167f84e0dedeba993b267ede3bb7a4e950d8096c2d81c7"
 }

package/templates/README.md

@@ -9,7 +9,7 @@ templates/
 ├── README.md           # 本说明文档
 ├── generate-api/       # API 生成模板
 └── projects/           # 项目模板，用于 `rabetbase project create` 命令
-    └── sub-app-react-demo/  # React 微前端项目模板快照
+    └── sub-app-react-demo/  # React 微前端项目模板真源
 ```
 
 ## API 生成模板
@@ -18,33 +18,29 @@ templates/
 
 ## 项目模板
 
-### 远程模板同步
+### 模板真源与 CDN 资产
 
-`projects/sub-app-react-demo/` 目录是从模板真源仓同步来的 CDN 构建源：
-**仓库地址**: https://github.com/lovrabet/sub-app-react-demo
+`projects/sub-app-react-demo/` 是 Rabetbase React 项目的仓内模板真源，也是 CDN ZIP 的唯一构建输入。
+模板能力最终沉淀到该目录；不维护额外的外部 `sub-app-react-demo` 真源或同步链路。
 
-#### 开发者：同步模板
+#### 开发者：维护与验证模板
 
-更新项目模板到最新版本：
+需要新增页面、组件或示例能力时，先从当前正式模板创建一个临时实例：
 
 ```bash
-npm run sync-template
+npm run build:dev
+node lib/cli.js project create template-test --template-source templates/projects/sub-app-react-demo
 ```
 
-在提交、推送和生成 CDN ZIP 前，可先把本地工作区（包含未提交修改）转换到独立目录：
+在实例中完成开发、运行和构建验证后，明确告诉 AI 要沉淀的页面、组件、样式、依赖或配置范围。AI 仅提取这些经过确认的变更，过滤具体 AppCode、应用模型、认证信息、项目路由和本地状态，再合入正式模板。
 
-```bash
-npm run sync-template -- --source ../sub-app-react-demo --output /tmp/sub-app-react-template
-```
-
-再使用已经准备好的模板创建调试项目：
+正式模板更新后，必须重新创建一个干净实例复验，不能把原开发实例整体覆盖回模板：
 
 ```bash
-node lib/cli.js project create template-test --template-source /tmp/sub-app-react-template
+node lib/cli.js project create template-verify --template-source templates/projects/sub-app-react-demo
 ```
 
-`sync-template` 负责“原始项目 → 标准模板”，`project create --template-source` 负责
-“标准模板 → 新项目”，并保留普通创建的认证、AppCode、依赖安装和格式化流程。
+`project create --template-source` 保留普通创建的认证、AppCode、依赖安装、格式化和项目配置流程。
 使用尚未发布的 CLI 时，先执行 `npm run build:dev`；
 使用已安装版本时，可把第二条命令换成 `rabetbase project create ...`。
 
@@ -78,7 +74,7 @@ npm run sync:cdn
 
 ## 注意事项
 
-- `templates/projects/sub-app-react-demo/` 是项目模板快照，不是独立 Git 仓
+- `templates/projects/sub-app-react-demo/` 是项目模板真源，不是独立 Git 仓，也不是外部仓快照
 - `rabetbase project create` 从 CDN 下载 ZIP，然后更新 `package.json` 与 `.rabetbase.json`；此仓库模板不进入 npm 发布包
 - 模板文件名必须兼容 Windows、macOS 和 Linux；禁止符号链接、大小写冲突路径和 Windows 保留名称
 - 有 AppCode 时，CLI 会重新生成 `src/api/api.ts` 和 `src/api/client.ts`