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

package/lib/utils/version.js

@@ -1 +1 @@
-function a323_0x5c3a(_0x32a266,_0x5bef78){_0x32a266=_0x32a266-0xf7;var _0x338af1=a323_0x338a();var _0x5c3adc=_0x338af1[_0x32a266];return _0x5c3adc;}(function(_0x2a65d1,_0x36b28d){var _0x57e1d9=a323_0x5c3a,_0x29b68a=_0x2a65d1();while(!![]){try{var _0x113e51=-parseInt(_0x57e1d9(0x100))/0x1*(parseInt(_0x57e1d9(0xfc))/0x2)+-parseInt(_0x57e1d9(0xfb))/0x3+-parseInt(_0x57e1d9(0xfd))/0x4+-parseInt(_0x57e1d9(0xfe))/0x5+parseInt(_0x57e1d9(0xff))/0x6+-parseInt(_0x57e1d9(0xf7))/0x7*(-parseInt(_0x57e1d9(0xf8))/0x8)+parseInt(_0x57e1d9(0xfa))/0x9*(parseInt(_0x57e1d9(0xf9))/0xa);if(_0x113e51===_0x36b28d)break;else _0x29b68a['push'](_0x29b68a['shift']());}catch(_0x4f7658){_0x29b68a['push'](_0x29b68a['shift']());}}}(a323_0x338a,0x8e6d8));function a323_0x338a(){var _0x58f70f=['3959480wGjWfZ','3302196YzBxma','1076874YqOJCp','7oInVIy','6000328znVkzm','9633160uquJBR','18qrmJzz','919647vfMBel','2izEXck','1873344mUbNuv'];a323_0x338a=function(){return _0x58f70f;};return a323_0x338a();}import{VERSION}from'../generated/build-info.js';export function getCliVersion(){return VERSION;}
+(function(_0x4c51d5,_0x29ff3f){var _0x3e10a1=a351_0x5d56,_0x1f037b=_0x4c51d5();while(!![]){try{var _0x191713=parseInt(_0x3e10a1(0x1c6))/0x1*(-parseInt(_0x3e10a1(0x1c4))/0x2)+-parseInt(_0x3e10a1(0x1c0))/0x3*(parseInt(_0x3e10a1(0x1bf))/0x4)+-parseInt(_0x3e10a1(0x1c3))/0x5*(-parseInt(_0x3e10a1(0x1c2))/0x6)+parseInt(_0x3e10a1(0x1c9))/0x7+parseInt(_0x3e10a1(0x1c7))/0x8+parseInt(_0x3e10a1(0x1c5))/0x9*(-parseInt(_0x3e10a1(0x1c1))/0xa)+parseInt(_0x3e10a1(0x1c8))/0xb*(parseInt(_0x3e10a1(0x1be))/0xc);if(_0x191713===_0x29ff3f)break;else _0x1f037b['push'](_0x1f037b['shift']());}catch(_0x3018a8){_0x1f037b['push'](_0x1f037b['shift']());}}}(a351_0x45f4,0x77910));import{VERSION}from'../generated/build-info.js';function a351_0x5d56(_0x440cab,_0x52a7c7){_0x440cab=_0x440cab-0x1be;var _0x45f449=a351_0x45f4();var _0x5d56f6=_0x45f449[_0x440cab];return _0x5d56f6;}function a351_0x45f4(){var _0x17045f=['9NancbE','132137snvxnn','1387776PiQOuF','11UEYMFf','111475KmclDd','11303256xdUjgo','4AoieKX','1703220NXiLxx','254990wiTblz','5259642gpHUda','5KXURWh','14wWGTnE'];a351_0x45f4=function(){return _0x17045f;};return a351_0x45f4();}export function getCliVersion(){return VERSION;}

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

@@ -1 +1 @@
-function a324_0x35ad(_0x1e6a91,_0x3702c6){_0x1e6a91=_0x1e6a91-0x188;var _0x1535df=a324_0x1535();var _0x35adb9=_0x1535df[_0x1e6a91];return _0x35adb9;}(function(_0x2228fc,_0x22263e){var _0x51d8e1=a324_0x35ad,_0x4e5994=_0x2228fc();while(!![]){try{var _0x529dec=-parseInt(_0x51d8e1(0x190))/0x1*(parseInt(_0x51d8e1(0x191))/0x2)+parseInt(_0x51d8e1(0x18d))/0x3+parseInt(_0x51d8e1(0x18f))/0x4*(parseInt(_0x51d8e1(0x18a))/0x5)+parseInt(_0x51d8e1(0x18c))/0x6+parseInt(_0x51d8e1(0x18b))/0x7*(parseInt(_0x51d8e1(0x188))/0x8)+parseInt(_0x51d8e1(0x18e))/0x9*(parseInt(_0x51d8e1(0x189))/0xa)+-parseInt(_0x51d8e1(0x192))/0xb;if(_0x529dec===_0x22263e)break;else _0x4e5994['push'](_0x4e5994['shift']());}catch(_0x7d9a8f){_0x4e5994['push'](_0x4e5994['shift']());}}}(a324_0x1535,0x76aef));function a324_0x1535(){var _0x2874d9=['14qxmAPU','2003466xXWAhs','2870727UQGpwt','2067453VyEnlH','28GYXWfq','13355SZxJPq','2SMOUTR','24826549pYYToN','1201480FkfSYl','20Iuuyoa','504155zQCOVT'];a324_0x1535=function(){return _0x2874d9;};return a324_0x1535();}import{setActiveCookie,clearActiveCookie}from'../core/api-client.js';export async function withActiveCookie(_0x2762a0,_0x3af75a){setActiveCookie(_0x2762a0);try{return await _0x3af75a();}finally{clearActiveCookie();}}
+(function(_0x1fc9f2,_0x567a3b){var _0x1e2882=a352_0x5c85,_0x3714bb=_0x1fc9f2();while(!![]){try{var _0x556c03=parseInt(_0x1e2882(0x177))/0x1+-parseInt(_0x1e2882(0x17b))/0x2+parseInt(_0x1e2882(0x17c))/0x3+parseInt(_0x1e2882(0x17d))/0x4*(parseInt(_0x1e2882(0x17a))/0x5)+parseInt(_0x1e2882(0x178))/0x6+-parseInt(_0x1e2882(0x17f))/0x7+parseInt(_0x1e2882(0x17e))/0x8*(-parseInt(_0x1e2882(0x179))/0x9);if(_0x556c03===_0x567a3b)break;else _0x3714bb['push'](_0x3714bb['shift']());}catch(_0x15082d){_0x3714bb['push'](_0x3714bb['shift']());}}}(a352_0x5c67,0x89364));import{setActiveCookie,clearActiveCookie}from'../core/api-client.js';function a352_0x5c85(_0x30dc8b,_0x3bf303){_0x30dc8b=_0x30dc8b-0x177;var _0x5c674d=a352_0x5c67();var _0x5c851e=_0x5c674d[_0x30dc8b];return _0x5c851e;}function a352_0x5c67(){var _0x1beebc=['785130mzJqba','9ynFHYK','430GzdKOC','642186FkhZUd','2164875ynqfUF','27096TsmUFn','8806960qpIOxB','3792516TzpFcy','1090727jxNbWF'];a352_0x5c67=function(){return _0x1beebc;};return a352_0x5c67();}export async function withActiveCookie(_0x1ab858,_0x3afcfc){setActiveCookie(_0x1ab858);try{return await _0x3afcfc();}finally{clearActiveCookie();}}

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

@@ -1 +1 @@
-function a325_0x9b7f(){var _0x154e28=['517CLRRfG','3cjVbQN','9071433PGleqa','27XDlRMy','958FtgBxD','stderr','418270NTqPzb','6089965sqKIjN','2196664oXZpuy','264hhARps','2171460YJZWNM','5744800UfdAwe'];a325_0x9b7f=function(){return _0x154e28;};return a325_0x9b7f();}function a325_0x40f2(_0x2dae63,_0x4d4273){_0x2dae63=_0x2dae63-0x1d7;var _0x9b7f61=a325_0x9b7f();var _0x40f2e0=_0x9b7f61[_0x2dae63];return _0x40f2e0;}(function(_0x47aefe,_0x5956e8){var _0x5cf7f1=a325_0x40f2,_0x16ce45=_0x47aefe();while(!![]){try{var _0x21c85b=parseInt(_0x5cf7f1(0x1d7))/0x1*(-parseInt(_0x5cf7f1(0x1de))/0x2)+-parseInt(_0x5cf7f1(0x1db))/0x3*(parseInt(_0x5cf7f1(0x1d9))/0x4)+parseInt(_0x5cf7f1(0x1e1))/0x5+-parseInt(_0x5cf7f1(0x1d8))/0x6+-parseInt(_0x5cf7f1(0x1dc))/0x7+-parseInt(_0x5cf7f1(0x1e2))/0x8*(-parseInt(_0x5cf7f1(0x1dd))/0x9)+-parseInt(_0x5cf7f1(0x1e0))/0xa*(-parseInt(_0x5cf7f1(0x1da))/0xb);if(_0x21c85b===_0x5956e8)break;else _0x16ce45['push'](_0x16ce45['shift']());}catch(_0x1bc4dc){_0x16ce45['push'](_0x16ce45['shift']());}}}(a325_0x9b7f,0xc02b6));export function writeCliSideChannelLine(_0x229f13){var _0x19e6c0=a325_0x40f2;process[_0x19e6c0(0x1df)]['write'](_0x229f13+'\x0a');}
+(function(_0x4ee1cc,_0x55f544){var _0x5884ca=a353_0x214a,_0x5570a0=_0x4ee1cc();while(!![]){try{var _0x2bab25=parseInt(_0x5884ca(0xdc))/0x1*(parseInt(_0x5884ca(0xda))/0x2)+parseInt(_0x5884ca(0xd4))/0x3*(parseInt(_0x5884ca(0xe0))/0x4)+-parseInt(_0x5884ca(0xd6))/0x5+parseInt(_0x5884ca(0xd9))/0x6*(parseInt(_0x5884ca(0xde))/0x7)+-parseInt(_0x5884ca(0xdd))/0x8*(-parseInt(_0x5884ca(0xd8))/0x9)+parseInt(_0x5884ca(0xd7))/0xa+-parseInt(_0x5884ca(0xdb))/0xb*(parseInt(_0x5884ca(0xdf))/0xc);if(_0x2bab25===_0x55f544)break;else _0x5570a0['push'](_0x5570a0['shift']());}catch(_0x928a7e){_0x5570a0['push'](_0x5570a0['shift']());}}}(a353_0x139e,0x9be38));function a353_0x139e(){var _0x1ce6bc=['36VIKlav','10632tztAoO','2FEPbqh','14960lnvkgB','1128782IArovo','1871400QPSQQS','3479cAhAET','19056dkPAjb','12BKYxdl','314646QnSfVJ','write','5364350DyQCqX','6112580dbCyTT'];a353_0x139e=function(){return _0x1ce6bc;};return a353_0x139e();}function a353_0x214a(_0x3c3c95,_0x185167){_0x3c3c95=_0x3c3c95-0xd4;var _0x139e73=a353_0x139e();var _0x214aac=_0x139e73[_0x3c3c95];return _0x214aac;}export function writeCliSideChannelLine(_0x3344bd){var _0x5b31ff=a353_0x214a;process['stderr'][_0x5b31ff(0xd5)](_0x3344bd+'\x0a');}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lovrabet/rabetbase-cli",
-  "version": "2.5.3-beta.1",
+  "version": "2.5.3-beta.3",
   "description": "Developer CLI for Lovrabet apps, datasets, pages, SQL, Backend Function, database connections, skills, and AI agent workflows.",
   "license": "SEE LICENSE IN LICENSE",
   "keywords": [
@@ -44,6 +44,9 @@
     "build:dev": "node scripts/clean-build-output.mjs && tsc && tsc-alias",
     "start": "tsc --watch",
     "sync:cdn": "node scripts/sync-cdn-assets.js",
+    "sync:cdn:beta": "node scripts/sync-cdn-assets.js --beta",
+    "check:cdn": "node scripts/sync-cdn-assets.js --check",
+    "check:cdn:beta": "node scripts/sync-cdn-assets.js --beta --check",
     "verify:bundled-jq": "node scripts/verify-bundled-jq.mjs",
     "regression:release-smoke": "node scripts/regression-release-smoke.mjs",
     "release:summary:prepare": "node scripts/release-summary-preparation.mjs",

package/skills/rabetbase/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rabetbase
-version: 2.5.3-beta.1
+version: 2.5.3-beta.3
 description: "Use for Lovrabet development work through the rabetbase CLI: create or bind projects (including creating an AppCode project in the current folder), pull Dataset/API facts and maintain SDK clients, or manage datasets, Instant API access policies, database connections, pages, SQL, Backend Functions, menus, notifications, knowledge bases and kb search, Agent Context Rules, roles, files, OCR, deployment metadata, platform issues, and 钉钉沙箱账号绑定. Trigger when the user mentions rabetbase, Lovrabet development, AppCode, Dataset, Instant API allow/deny/route policy, project creation, api pull/codegen, dblink, page, SQL, BFF, menu, notification, knowledge base, kb search, Agent Context Rules, RULES.md, DATABASE.md, rule list/get/set, role, file/OCR, or related development workflows."
 metadata:
   requires:
@@ -19,7 +19,7 @@ metadata:
 ## 前置条件
 
 1. **连接配置与认证分离**：首次使用先执行 `rabetbase config init`。交互模式选择当前已开放国家/地区；非交互模式显式传 `--region`，未传时使用默认节点。企业独立部署优先导入 `lovrabet-routing/v1` 清单，也兼容旧扁平 Domain 文件和对应 `--*-domain` flags。`config init` 默认重建当前项目节点/Domain 配置，显式 `--global` 时写全局；保留 Cookie、AccessKey、format、locale 和应用绑定，但不登录、不绑定项目，随后再执行 `rabetbase auth login`
-2. **AppCode**：确保 `.rabetbase.json` 中设置了 `apps`（单应用自动选中；多应用再配 `defaultApp`），或兼容读取的顶层 `appcode`，或通过 `--appcode <code>` / `--app <name>` 传入。旧 `.lovrabet.json` 不会自动读取
+2. **AppCode**：确保 `.rabetbase.json` 中设置了 `apps`（单应用自动选中；多应用再配 `defaultApp`），或兼容读取的顶层 `appcode`，或通过 `--appcode <code>` / `--app <name>` 传入。`.lovrabet.json` 属于 Lovrabet 运行态 CLI；Rabetbase 不读取也不修改它，两份配置可在同一项目共存
 3. **配置文件**：`rabetbase config init` 默认写当前项目 `.rabetbase.json`，显式 `--global` 时写 `~/.rabetbase.json`；默认节点不落冗余 `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 职责边界」）
 5. **多应用场景**：一个项目有多个应用时，先 `rabetbase workspace add <name> --appcode … [--region cn|id]` 登记各应用；profile 的 `region` 高于顶层国家/地区回退值。再用 `--app <name>` 临时切换，或 `workspace use --app <name>` 修改当前工作目录默认应用
@@ -42,6 +42,7 @@ metadata:
 ## Agent 快速执行顺序
 
 1. **判断需求类型**
+   - 表单审批流或独立工作流定义 → 先读 [`approval-flow-development-workflow.md`](guides/approval-flow-development-workflow.md)，先确定 `flowType`，再使用 `flow validate/create/update/publish`
    - Instant API 标准数据记录操作 → SDK filter/getOne/create/batchCreate/update/delete；批量更新使用 `update({ id: [...] })`，不存在 `batchUpdate()`
    - 简单聚合且数据集是 DB_TABLE → SDK aggregate；聚合列用 `aggregate[].column`，不要用旧别名 `field`
    - 复杂 JOIN / 数据库函数且数据集是 DB_TABLE → Custom SQL
@@ -52,6 +53,7 @@ metadata:
    - 跨表场景还需查目标表的结构
    - 写入前用 `data.fields[]` 确认真实字段、必填字段、枚举选项；枚举/选择字段写入 `options[].value`，不是展示 `label`
    - 需要了解数据集关联关系时用 `rabetbase dataset relations --format compress`（或 `json`）；需要审计关系事实错误和人工复核项时用 `rabetbase dataset relation-audit --format compress`
+   - 需要管理不同数据库连接之间的 DB_TABLE 关联时，先读 [跨库关系](references/rabetbase-dataset-cross-relations.md)，使用 `dataset cross-relation-list/create/update/delete`；源数据集＋字段定位，更新/删除必须唯一匹配，写前 dry-run，写后以跨库 list 回读为准
    - 需要从文本需求创建新的 `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)）
    - 研发资源保存后的增量同步由服务端自动处理；仅在管理员明确要求首次初始化、历史回填或故障恢复时读 [`deployment sync-all`](references/rabetbase-deployment-sync-all.md)，在停止编辑的安静窗口执行；提交成功后按 jobId 查询状态，提交结果未知时用 `sync-jobs` 恢复任务事实
@@ -61,14 +63,15 @@ metadata:
    - 全部批次结束后再次执行异步差异刷新并重新获取完整差异；仍未收敛时，按 [`database-connection-workflow.md`](guides/database-connection-workflow.md) 对剩余 `toAnalyzeTables` 逐表串行重试且每表只恢复一次。仅当用户明确要求跳过分析/刷新时直接读取现有差异。状态查询失败继续使用原 `planId`，不得重复启动任务
    - 输出很大且只需子集时，在 `compress`/`json` 上加 `--jq '.data…'` 缩小结果
    - 需要真实业务行数据时必须交接给 `lovrabet data filter/getOne`；`lovrabet` 不可用时报告阻断并提示安装 Skill 与 CLI，不要静默安装或修复，也不要用 `rabetbase sql exec` 当行数据替代，见 [`guides/data-api-guidelines.md`](guides/data-api-guidelines.md)
-   - 需要 `src/api/api.ts` / `client.ts` 时：先 `rabetbase api pull --format compress` 取 `data.models`、`data.files`、`data.needsAgentMerge`，再按 [`sdk-client-generation.md`](guides/sdk-client-generation.md) 更新 TypeScript。`api pull` 默认**不会覆盖已有** `api.ts`/`client.ts`；只有用户明确要求放弃本地定制并完整重建时才使用 `--force --yes`
-   - 需要按 Dataset + API 配置 Instant API 的 `allow`、`deny` 或 `route` 时，先读取 [`rabetbase-instant-api-policy.md`](references/rabetbase-instant-api-policy.md)，只编辑固定 `policy.json`，随后依次执行 `validate`、`publish --dry-run`，经人工确认后再正式发布
+   - 需要 `src/api/api.ts` / `client.ts` 时：已有项目先执行 `rabetbase project upgrade --dry-run`，确认计划后执行 `rabetbase project upgrade --yes`；再运行 `rabetbase api pull --format compress` 刷新模型事实。按 [`sdk-client-generation.md`](guides/sdk-client-generation.md) 检查 `data.files`、`data.needsProjectUpgrade` 与模型注册表；注册表源码迁移仅使用 `project upgrade`
+   - 需要按 Dataset + API 配置 Instant API 的 `allow`、`deny` 或 `route` 时，先读取 [`rabetbase-instant-api-policy.md`](references/rabetbase-instant-api-policy.md)。先执行 `api pull` 更新模型事实，从生成的 `models[].datasetCode` 取得精确选择器；**不得**把 SDK `alias` 当作 `datasetCode`。精确 Dataset 选择器在 v1/v2 都可写 `{ datasetCode: "<real-dataset-code>" }` 或 `{ tableName: "<real-table-name>" }`；两者同时写时必须指向同一 Dataset，已有 code 时优先只写 `datasetCode`。再用 `dataset detail --code <datasetCode>` 确认目标操作存在，只编辑固定 `policy.json`。仅版本 2 可以使用通配：全部 Dataset 固定写作 `datasets: [{"datasetCode":"*"}]`，全部 API 固定写作 `apis: ["*"]`；每种通配都必须是其数组的唯一元素，`tableName: "*"` 不支持，也不得与 Dataset 通配混用。需要从通配规则中豁免组合时，用 `excludes: [{ datasets: [{ datasetCode: "<real-dataset-code>" }], apis: ["<api>"] }]`，豁免项会回退到其他非重叠规则或 `defaults.instantApi`。版本 1 禁止 `*` 与 `excludes`。随后依次执行 `validate`、`publish --dry-run`，经人工确认后再正式发布。认证不可用时报告阻断，不得猜测或复用过期的 Dataset 信息
 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) 创建、校验、发布并验证
    - 页面执行已发布的 Custom SQL 时使用 `sqlCode` + `params`；Backend Function 默认使用 `context.client.sql.byName(sqlName).execute({ params })`，`sql.execute({ sqlCode, params })` 仅作兼容路径
 4. **Backend Function 工作流严格分步**
-   - 查现有 → 确认字段或通知配置 → 查公共函数 → 本地创建(`bff create`) → 检查状态(`bff status`) → 先预览(`--dry-run`) → 再拉取/推送/删除
+   - 查现有 → 确认字段或通知配置 → 查公共函数 → 本地创建(`bff create`) → 检查状态(`bff status`) → 先预览(`--dry-run`) → 再拉取/推送/删除；运行行为异常时用 `bff logs` 按时间、级别和关键字查询日志
+   - `bff pull` / `bff push` 返回 `data.conflicts` 时，逐项报告 `lockKey` 和 `code`，并只在审阅后执行该项 `nextAction`；不得把同步冲突说成失败、自动使用 `--force`，或盲目重试整批脚本
    - 创建会发送消息通知的 Backend Function 时，先读取 [`backend-function.md`](guides/backend-function.md) 的“消息通知扩展”契约，再执行 [`rabetbase notification config-list --type EMAIL`](references/rabetbase-notification-config-list.md) 获取当前应用的 `configCode`；不得猜测渠道、收件人或把密钥写进脚本
    - 推送完成只代表脚本配置已同步到平台；若用户要确认最终运行效果，显式交接到运行验证（如可用的 `lovrabet bff exec`），不要把运行验证伪装成 `rabetbase` 已完成
 5. **页面体系选择**
@@ -96,6 +99,17 @@ metadata:
    - 主产物是 `.rabetbase/blueprint/<appCode>/application-blueprint.md`，不是直接生成或推送 SQL/Backend Function
    - 必须把老代码 Logic Graph 与 dbagent 已生成的 Dataset / Relations 绑定，再判断 Instant API、Custom SQL、Backend Function、Hook、COMMON 或 Java Service 落点
 
+## 流程定义（`flow`）
+
+- 先按 [`approval-flow-development-workflow.md`](guides/approval-flow-development-workflow.md) 编排流程，再逐条阅读 [`rabetbase-flow-commands.md`](references/rabetbase-flow-commands.md)。
+- 角色、用户等候选资源按 [`rabetbase-flow-resources.md`](references/rabetbase-flow-resources.md) 查询；运行态责任边界见 [`rabetbase-flow-runtime-boundary.md`](references/rabetbase-flow-runtime-boundary.md)。
+- 填写办理人、角色或转交候选人前，使用 `rabetbase flow runtime-user-search`、`runtime-role-list`、`runtime-role-user-list` 查询运行态真实 ID；这些命令只读，不办理待办。
+- FlowConfig 字段和校验规则以 [`knowledge/approval-flow/config-json-schema.md`](knowledge/approval-flow/config-json-schema.md) 为准；CLI 校验结果区分 `READY`、`NEEDS_USER_CONFIRMATION`、`NEEDS_DSL_EXTENSION`、`INVALID_CONFIG` 和 `REMOTE_VALIDATION_FAILED`。
+- `FORM_FLOW` 是表单审批流，人工节点只能使用 `taskMode: APPROVAL`，不得生成 `HANDLE`。
+- `INDEPENDENT_FLOW` 是工作流，可以组合 `APPROVAL` 和 `HANDLE`；包含审批节点也不会改变其工作流类型。
+- `pageMode` 只属于独立工作流：当前公开 Skill 只生成 `CUSTOM_PAGE`，由业务页面根据业务状态自行渲染并通过 SDK 驱动；缺省也按 `CUSTOM_PAGE`。用户要求 `PLATFORM_FORM` 时返回 `NEEDS_DSL_EXTENSION`，不生成或提交 FlowConfig。`CUSTOM_PAGE` 可选配置 `flowJson.startPageId` 和人工节点 `pageId` 作为纯导航信息；二者都不参与流程执行。
+- 自定义页面 SDK/OpenAPI 只面向 `INDEPENDENT_FLOW + CUSTOM_PAGE`，不得把表单审批流或平台表单工作流混入该入口。
+
 ## 应用决议指引
 
 1. **已明确 appcode**
@@ -163,7 +177,8 @@ metadata:
 - **不要**在用户未要求时给命令加 `--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` 与 `rabetbase.domain-routing.json`。每个官方节点直接声明自己的第三方库 CDN 与 Lovrabet 自有资源 Domain；项目文件始终包含解析后的完整地址，企业独立部署从共用清单读取显式 CDN。两个生成文件都不下发认证配置；`rabetbase run start|dev|build|preview` 会在执行脚本前刷新公开 Domain 快照，也可用 `project domain-routing-sync` 立即显式刷新；`api pull` 只刷新 SDK/API 文件。
-- **`api pull` / `api list`**：默认仅针对**项目** `apps`；需要合并全局已登记应用时加 `--global`。多应用遍历会在每个请求前应用该 profile 的有效 `region`；`api pull` 为非默认应用生成独立 `<name>-sdk-config.ts`（见各命令 reference）。
+- **`api pull` / `api list`**：默认仅针对**项目** `apps`；需要合并全局已登记应用时加 `--global`。多应用遍历会在每个请求前应用该 profile 的有效 `region`。一个 AppCode 匹配多个 profile 时必须用 `--app <profile>` 消除歧义；只有显式相同 `apiGroup` 且使用同一 `apiDir` 的 profile 才共享生成注册表（见各命令 reference）。
+- **多 profile SDK 的运行边界**：共享注册表只解决“同一份业务代码分别运行在不同节点，并按当前 Runtime Domain 选择唯一 profile”；它不是跨节点网关，也不允许浏览器 client 在一次运行中同时读取多个节点。业务代码只使用 alias，不硬编码或跨 profile 取 `datasetCode`。确需跨节点聚合时，交给可信服务端或 Backend Function 编排；完整约束见 [`sdk-client-generation.md`](guides/sdk-client-generation.md) 与 [`typescript-sdk.md`](guides/typescript-sdk.md)。
 - **`app list`**：默认展示**合并**后的全量；`--global` 仅全局、`--project` 仅项目（见 [`rabetbase app list`](references/rabetbase-app-list.md)）。
 
 ## app vs workspace 职责边界
@@ -211,6 +226,7 @@ metadata:
 - **不要跳过 Dataset rename 最终线上回查** — 连续重命名后必须按 code 重新查询线上名称，不能只相信本地 plan 或 dry-run
 - **不要把 MCP 工具名当 CLI 命令** — 使用 `rabetbase sql list`，不是 `list_sql_queries`
 - **不要擅自加 `--global`** — 见上文「配置作用域原则」；默认写项目、读合并；仅在用户明确要求或文档说明的场景使用 `--global`。
+- **不要迁移或删除 Lovrabet 运行态配置** — `.lovrabet.json`、`.lovrabet/` 与 Lovrabet Skill 不属于 Rabetbase 项目升级范围；即使它们与 `.rabetbase.json` 同时存在也必须保留
 - **不要为 Instant API Policy 传任意文件路径或写入 app-config** — 策略只使用 `.rabetbase/instant-api-policy/<appCode>/policy.json` 与独立策略接口；发布和回滚前必须校验并预览。
 
 ## 接口选型优先级
@@ -303,7 +319,7 @@ const result = await client.bff.execute<DashboardData>({
 | 初始化连接配置 | [`rabetbase config init`](references/rabetbase-init.md) | 选择官方节点或导入独立部署 Domain |
 | 创建新项目 | [`rabetbase project create`](references/rabetbase-project-create.md) | 支持新目录或当前空目录创建；完成口径与安全边界见 reference |
 | 刷新项目公开 Domain 路由 | [`rabetbase project domain-routing-sync`](references/rabetbase-project-domain-routing-sync.md) | 根据当前有效配置原子生成项目级 `rabetbase.domain-routing.json`；与前端页面路由无关 |
-| 从 lovrabet-cli 迁移 | [`rabetbase project upgrade`](references/rabetbase-project-upgrade.md) | 6 步自动迁移，`--yes` 跳过确认 |
+| 升级已有项目依赖与源码架构 | [`rabetbase project upgrade`](references/rabetbase-project-upgrade.md) | 先 `--dry-run`，标准旧脚手架自动备份迁移，业务定制写候选文件；不修改 Lovrabet 运行态配置 |
 | 老项目翻新蓝图 / 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) | `write`；先审阅脚本命令体，嵌入式工具暂不开放 |
 | 安装 / 重装 / 刷新 CLI Built-in Skill | [`rabetbase cli-skill install`](references/rabetbase-cli-skill-install.md) | 由最新版官方 Skills CLI 从当前 npm 包内本地源重装同版本 Skill；发现本地 skill 过期时优先执行 |
@@ -324,6 +340,8 @@ const result = await client.bff.execute<DashboardData>({
 | 管理和检索当前研发应用的企业知识库 | [`rabetbase kb list/detail/search/create/update/delete`](references/rabetbase-kb.md) | 管理仅 company scope；search 固定 Development 且仅 `public/company`；`create/update` 为 `write`，`delete` 保持 `high-risk-write` |
 | 管理当前研发应用的 Agent context 规则 | [`rabetbase rule list/get/set`](references/rabetbase-rule.md) | `RULES.md` 供页面、API 等研发 Agent 使用且排除 DB Agent；`DATABASE.md` 仅供数据库分析时 DB Agent 使用；两者在各自流程全程参与 context；set 为 `write`，先 dry-run |
 | 查询或管理应用级通知配置 | [`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 获取 Backend Function 所需 `configCode`；写入只接收单一敏感 JSON 源，先 dry-run；update/delete 必须 `--yes` |
+| 设计、校验和发布表单审批流或独立工作流 | [`rabetbase flow validate/list/detail/create/update/publish`](references/rabetbase-flow-commands.md) | 先确定 `flowType`；本地 validate 后再 create/update 和 publish |
+| 查询审批流运行态人员和角色 | [`rabetbase flow runtime-user-search/runtime-role-list/runtime-role-user-list`](references/rabetbase-flow-resources.md) | 只读，结果标记 `scope: runtime`；用于填写 FlowConfig 的 userId/roleId |
 | 查看线上菜单事实 / 菜单异常审计 | [`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 visibility-update`](references/rabetbase-menu-visibility-update.md) | 用精确 ID/path 选择目标；先 dry-run，使用 `--expect-visible` / `--expected-count` 防漂移，正式执行必须 `--yes` |
 | 创建外部网站链接菜单 | [`rabetbase menu external-link-create`](references/rabetbase-menu-external-link-create.md) | `write`；显式选择 `embedded` 或 `new-window`，仅接受 HTTPS；建议先 dry-run，正式执行不要求 `--yes` |
@@ -358,6 +376,7 @@ const result = await client.bff.execute<DashboardData>({
 | 查看数据集关联关系 | [`rabetbase dataset relations`](references/rabetbase-dataset-relations.md) | 标准只读入口，输出 `datasetCode + field` 关系事实；支持 `DB_TABLE -> DB_TABLE`、`DB_TABLE -> METADATA`、`METADATA -> METADATA` |
 | 审计数据集关联关系 | [`rabetbase dataset relation-audit`](references/rabetbase-dataset-relation-audit.md) | 只读审计关系事实结构错误、风险和人工复核项 |
 | 管理单条数据集关联关系 | [`rabetbase dataset relation-create/update/delete`](references/rabetbase-dataset-relation-mutations.md) | 单条关系写入；写入前用 `relations` 确认 `datasetCode + field` 关系事实，DB_TABLE 写入所需表名来自显式参数或物理表事实 |
+| 管理跨库数据集关联 | [`dataset cross-relation-list/create/update/delete`](references/rabetbase-dataset-cross-relations.md) | 不同连接的 DB_TABLE 逻辑关系；源端定位，更新/删除要求唯一匹配 |
 | 首次生成数据列表页 | [`rabetbase page generate-start --datasetcode <code>`](references/rabetbase-page-generate-start.md) | 提交或复用服务端异步任务 |
 | 创建自定义页面 | [`rabetbase page create --page-pattern BLANK --name "客户看板"`](references/rabetbase-page-create.md) | 综合操作页面优先使用 `ONEPAGE`，业务数据可视化使用 `DASHBOARD`，基础页面使用 `BLANK`；模板详情见 [`page-templates.md`](knowledge/custom-page/page-templates.md)，也可通过 `--page-dir` 创建完整页面；先 dry-run |
 | 查询自定义页面 | [`rabetbase page custom-list`](references/rabetbase-page-custom-list.md) | 返回页面 ID、页面名称、`pageUrl`（查看最新保存内容）和 `editPageUrl`（打开编辑器） |
@@ -374,7 +393,7 @@ const result = await client.bff.execute<DashboardData>({
 | 恢复已删除页面 | [`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` |
 | 独立部署应用范围补偿同步 | [`rabetbase deployment sync-all`](references/rabetbase-deployment-sync-all.md) | 管理员首次初始化、历史回填或故障恢复时使用；`write`，只提交 appCode；在停止编辑的安静窗口执行，保存 jobId 后查询状态，结果未知时用 `sync-jobs` 恢复任务事实，不自动重提；不是精确镜像 |
-| 生成 / 更新 API 客户端代码 | [`rabetbase api pull`](references/rabetbase-api-pull.md) → [`sdk-client-generation.md`](guides/sdk-client-generation.md) | `api pull` 拉 Dataset 事实并刷新匹配应用的 SDK 路由文件；已有 `api.ts`/`client.ts` 按 guide 合并更新 |
+| 升级 API 客户端源码结构并刷新模型 | [`rabetbase project upgrade`](references/rabetbase-project-upgrade.md) → [`rabetbase api pull`](references/rabetbase-api-pull.md) → [`sdk-client-generation.md`](guides/sdk-client-generation.md) | `project upgrade` 迁移稳定入口，`api pull` 只刷新 Dataset 模型事实 |
 | 查看生成的 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 内容和参数定义 |
@@ -387,6 +406,7 @@ const result = await client.bff.execute<DashboardData>({
 | 执行 SQL 查询 | [`rabetbase sql exec --sqlcode xxx`](references/rabetbase-sql-exec.md) | 支持 `--params` JSON 参数 |
 | 查看现有 Backend Function | [`rabetbase bff list`](references/rabetbase-bff-list.md) | 按类型和名称过滤，支持 `--app` 限定应用 |
 | 查看 Backend Function 详情 | [`rabetbase bff detail --id n`](references/rabetbase-bff-detail.md) | 含完整脚本内容 |
+| 查询 Backend Function 运行日志 | [`rabetbase bff logs`](references/rabetbase-bff-logs.md) | 默认最近 30 分钟；支持时间范围、级别、关键字和条数过滤 |
 | 创建本地 Backend Function | [`rabetbase bff create --type ENDPOINT --name xxx`](references/rabetbase-bff-create.md) | 在 `.rabetbase/bff/<appCode>/...` 下创建脚手架 |
 | 查看 Backend Function 本地状态 | [`rabetbase bff status`](references/rabetbase-bff-status.md) | 检查 added / modified / unchanged / remoteOnly |
 | 拉取远端 Backend Function | [`rabetbase bff pull`](references/rabetbase-bff-pull.md) | 从远端同步到本地 |
@@ -431,6 +451,7 @@ const result = await client.bff.execute<DashboardData>({
 | 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 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) |
+| Approval Flow | [`validate/list/detail/create/update/publish`](references/rabetbase-flow-commands.md) / [`runtime-user-search/runtime-role-list/runtime-role-user-list`](references/rabetbase-flow-resources.md) |
 | Roles | [`list`](references/rabetbase-role-list.md) / `detail` / `update` / `delete` / [`user-resolve`](references/rabetbase-role-user-resolve.md) / [`user-add` / `user-remove`](references/rabetbase-role-user-add.md) |
 | Tenant Members | [`tenant members-list`](references/rabetbase-tenant-members-list.md)（当前账号所属租户的全量人员目录） |
 | app commands | [`list`](references/rabetbase-app-list.md)（只读应用事实；平台目录用 `list --remote`）/ [`members-list`](references/rabetbase-app-members-list.md)（应用人员及角色归属）。登记/移除应用改用 `workspace add` / `workspace remove` |
@@ -441,7 +462,7 @@ const result = await client.bff.execute<DashboardData>({
 | Deployment | [`sync-all` / `sync-status` / `sync-jobs`](references/rabetbase-deployment-sync-all.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) |
+| bff commands | [`list`](references/rabetbase-bff-list.md) / [`detail`](references/rabetbase-bff-detail.md) / [`logs`](references/rabetbase-bff-logs.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) |
 | file / ocr commands | [`file upload/query-url`](references/rabetbase-file.md) / [`ocr recognize`](references/rabetbase-ocr.md) |
 | codegen commands | [`sdk`](references/rabetbase-codegen-sdk.md) / [`sql`](references/rabetbase-codegen-sql.md) |
 | CLI Built-in Skill | [`install`](references/rabetbase-cli-skill-install.md) |
@@ -522,3 +543,4 @@ const result = await client.bff.execute<DashboardData>({
 | 质量与最佳实践         | 审查 SQL/Backend Function、命名、高危边界、描述字段                                                                                | [`best-practices.md`](guides/best-practices.md)                             |
 | 数据库连接与分析       | 接入/改连/测连、`traceId` 来源、`db analyze-*` 与 dataset 分工；子命令速查见上文 **「数据库连接（db）」**             | [`database-connection-workflow.md`](guides/database-connection-workflow.md) |
 | 菜单异常审计与安全修复 | 重复 path、根级菜单重名、空 folder 删除计划和平台处理后回查                                                          | [`menu-anomaly-manual-cleanup.md`](guides/menu-anomaly-manual-cleanup.md)   |
+| 表单审批流与独立工作流设计态开发 | 流程分类、资源发现、FlowConfig、校验、创建、发布和启停                                                   | [`approval-flow-development-workflow.md`](guides/approval-flow-development-workflow.md) |

package/skills/rabetbase/guides/approval-flow-development-workflow.md

@@ -0,0 +1,137 @@
+# 流程设计态开发工作流
+
+本工作流用于在 `rabetbase` 中创建、校验和管理表单审批流与独立工作流定义。它只覆盖设计态流程，不办理运行态待办。
+
+执行前按当前步骤阅读：
+
+- 命令参数与风险：[flow 命令参考](../references/rabetbase-flow-commands.md)
+- 人员、角色、脚本和通知配置发现：[审批流资源发现](../references/rabetbase-flow-resources.md)
+- FlowConfig 字段与拓扑规则：[FlowConfig 契约](../knowledge/approval-flow/config-json-schema.md)
+- 设计态与运行态边界：[审批流职责边界](../references/rabetbase-flow-runtime-boundary.md)
+
+## 流程类型判定
+
+先确定外层 `flowType`，再设计节点；不要根据是否出现审批节点反推流程类型。
+
+| `flowType` | 产品语义 | 人工节点 | 页面与数据边界 |
+|---|---|---|---|
+| `FORM_FLOW` | 表单审批流 | 只允许 `taskMode: APPROVAL`，禁止 `HANDLE` | 绑定 `datasetCode/pageId`；表单填写发生在发起前，驳回修改走重新提交 |
+| `INDEPENDENT_FLOW` | 独立工作流 | 可同时使用 `APPROVAL` 和 `HANDLE` | 不绑定 `datasetCode/pageId`；业务数据由工作流页面和 SDK 管理 |
+
+独立工作流即使包含审批节点仍然是 `INDEPENDENT_FLOW`。需要填写、补充材料、执行采购或确认收货等人工办理步骤时，必须使用独立工作流，不能把 `HANDLE` 塞进表单审批流。
+
+独立工作流的服务端语义包含两种 `flowJson.pageMode`：
+
+- `CUSTOM_PAGE`：业务自定义页面；缺省时按此模式处理。
+- `PLATFORM_FORM`：服务端平台表单页面语义；当前公开 Skill 和 CLI 不生成或提交该模式。
+
+用户要求 `PLATFORM_FORM` 时，直接返回 `NEEDS_DSL_EXTENSION`，说明当前版本只支持业务自定义页面；不要继续生成 FlowConfig，也不要执行 create/update。
+
+`pageMode` 不适用于 `FORM_FLOW`。自定义页面 SDK/OpenAPI 只查询和操作 `INDEPENDENT_FLOW + CUSTOM_PAGE`。
+
+`INDEPENDENT_FLOW + CUSTOM_PAGE` 可以选择性配置：
+
+- `flowJson.startPageId`：进入发起页面时使用。
+- 人工节点 `pageId`：待办、已办或任务详情进入当前节点页面时使用。
+
+这两个字段只是导航元数据，不是业务字段，不参与分支、权限、办理人或流程状态计算；不配置时由业务应用自行选择页面。
+
+## 标准流程
+
+1. 明确 `flowName`、业务描述、业务状态、办理步骤和通过/拒绝路径，并按上表显式选择 `flowType`。
+2. `FORM_FLOW` 配置外层 `datasetCode/pageId`；`INDEPENDENT_FLOW` 不配置这两个表单绑定字段，并使用显式或默认的 `pageMode: "CUSTOM_PAGE"`。用户要求 `PLATFORM_FORM` 时返回 `NEEDS_DSL_EXTENSION`。自定义页面可按需配置 `flowJson.startPageId` 和人工节点 `pageId`，自行查询和修改业务数据集，并按业务状态决定展示内容。
+3. 建立业务变量契约：逐项确认变量名、类型、初始来源、更新节点、消费节点以及是否用于待办/已办查询；区分顶层 `variables` 与 `formData`，禁止把 `approval_sys_*`、`approved` 当作业务变量。
+4. 根据业务逻辑直接生成完整的 `nodes + edges` 拓扑，不使用 `templateName` 或 SmartCode 模板表。
+5. 为每个人工节点确认 `taskMode`、`approvalMode`、`assignee.strategy` 和是否 `sequential`。决策用 `APPROVAL`；仅 `INDEPENDENT_FLOW` 可用 `HANDLE` 表达填写或确认数据后继续。办理完成后需要按业务变量分支时，按下方“HANDLE 后续路由”组合节点。
+6. 逐个人工节点确认可选配置：自定义页面 `pageId`、转交候选人 `transferCandidates`、超时动作 `timeout`、节点完成后默认抄送 `cc`；用户未提出时保持不配置，不自行推断人员、页面或超时时长。
+7. 固定办理人、转交候选人和默认抄送人使用 `flow runtime-user-search` 查询运行态 `userId`；角色审批使用 `flow runtime-role-list` 查询运行态 `roleId`，必要时用 `flow runtime-role-user-list` 核对成员。不要把 `role *` 查询出的配置端人员/角色写入 FlowConfig。
+8. `SCRIPT` 节点和 `timeout.action: "EXECUTE_BFF"` 使用 `bff list --type ENDPOINT` 选择真实 `functionName`；同时确认同步/异步方式、重试配置和独立的 `resultVariable`。不要让多个脚本依赖默认的 `scriptResult`。
+9. `NOTIFICATION` 节点使用 `notification config-list --all` 选择真实 `configCode`，并确认 `failurePolicy`、模板内容、变量占位符和收件人来源。
+10. 生成最小 FlowConfig。不要把服务端 id、`appCode`、部署状态、编译上下文、`templateName`、`formSchema/formDefinitions/formPermissions` 或节点 `form/formPermission` 写入文件。
+11. 执行 `rabetbase flow validate --file <path> --format compress`。
+12. 展示变量契约、拓扑、资源绑定、节点可选配置、warnings 和校验结果。只有 `valid=true` 才能进入远程写入。
+13. 用户确认后先执行 create/update 的 `--dry-run`，再正式提交。
+14. publish 属于 `high-risk-write`，先 `--dry-run`，正式执行必须显式 `--yes`。
+
+## 业务变量契约
+
+流程定义不保存发起请求的实际业务数据，但 CONDITION、SCRIPT、NOTIFICATION 和运行态查询都依赖稳定的变量名称。生成拓扑前至少整理下列信息：
+
+| 项目 | 说明 |
+|---|---|
+| 名称与类型 | 例如 `amount: number`、`businessStatus: string`、`purchase: object` |
+| 初始来源 | 发起请求的顶层 `variables`，或 `formData` 内字段 |
+| 更新者 | 发起页面、某个 HANDLE/APPROVAL 办理请求、SCRIPT 结果 |
+| 消费者 | CONDITION 表达式、SCRIPT、NOTIFICATION 或业务页面 |
+| 查询用途 | 用于待办/已办变量查询时，只能使用非系统的字符串、数字或布尔值做等值条件 |
+
+同一份数据在不同位置的访问方式不同：
+
+| 数据来源 | CONDITION | SCRIPT 入参 | NOTIFICATION |
+|---|---|---|---|
+| 顶层 `variables.amount` | `${amount > 10000}` | `params.amount` | `${variables.amount}` |
+| `formData.amount` | `${formData.amount > 10000}` | `params.formData.amount` | `${variables.formData.amount}` |
+
+- `variables` 办理参数更新顶层流程变量；`formPatch` 增量增加、修改或删除 `formData` 字段。
+- 对象和数组可以作为流程变量供页面、脚本或通知读取，但当前待办/已办变量查询只支持字符串、数字和布尔值等值条件；需要查询的业务状态应单独保存为顶层标量变量。
+- `approval_sys_*`、`approved` 和平台维护的 `formData` 容器名属于保留范围，不作为业务变量名或 SCRIPT `resultVariable`。
+
+## HANDLE 后续路由
+
+- `HANDLE` 只表示“填写或确认数据后继续”，自身必须且只能保留一条 `ALWAYS` 出边，不承担业务分支选择。
+- 自定义页面办理任务时，可以在办理请求中的 `variables` 更新业务变量，也可以用 `formPatch` 增量更新 `formData`；任务完成后，下游节点读取更新后的值。
+- 路由变量已由页面准备好时，生成 `HANDLE → CONDITION`，由条件网关表达多条业务路径。
+- 需要 Backend Function 先计算、校验或归一化路由变量时，生成 `HANDLE → SCRIPT → CONDITION`；不需要计算时不要为了分支强制插入 `SCRIPT`。
+- 不要给 `HANDLE` 直接配置多条出边，也不要让调用方传 `targetNodeId` 绕过流程图。办理节点存在多个业务结果不应判定为 `NEEDS_DSL_EXTENSION`；只有下游节点也无法表达需求时才进入 DSL 扩展判断。
+
+## 候选确认
+
+- 不编造 `userId`、`roleId`、`datasetCode`、`pageId`、`scriptName` 或 `configCode`。
+- 多个候选必须展示稳定标识并请用户选择。
+- 唯一命中可作为推荐项，但人员身份、角色、拓扑和通知渠道仍需用户确认。
+- 无命中时继续询问关键词，不自动替换为相似资源。
+- 当前 DSL 支持有向环路；无法表达并行网关、子流程、加签、委派、动态审批人或流程配置式自定义表单时，停止生成可提交配置。
+
+## 状态
+
+| 状态 | 含义 |
+|---|---|
+| `READY` | FlowConfig 完整且本地校验通过，可以等待用户决定是否提交 |
+| `NEEDS_USER_CONFIRMATION` | 资源候选、身份、拓扑或写操作尚未确认 |
+| `NEEDS_DSL_EXTENSION` | 需求超出当前简单审批 DSL |
+| `INVALID_CONFIG` | 本地结构或拓扑校验失败 |
+| `REMOTE_VALIDATION_FAILED` | 服务端拒绝 create、update 或 publish |
+
+`READY` 只表示本地配置可提交，不表示已经创建、发布或启用。远程结果必须以对应命令的服务端响应为准。
+
+## 本地文件与提交
+
+推荐目录：
+
+```text
+.rabetbase/flows/<flow-name>.json
+```
+
+旧文件先执行：
+
+```bash
+rabetbase flow validate --file .rabetbase/flows/purchase.json
+rabetbase flow validate --file .rabetbase/flows/purchase.json --write-normalized
+```
+
+`--write-normalized` 会原子替换原文件。warnings 中列出的旧字段会被删除；为服务端编译临时注入的上下文只存在于内存，不会写回文件。
+
+远程提交顺序：
+
+```bash
+rabetbase flow create --file .rabetbase/flows/purchase.json --dry-run --format compress
+rabetbase flow create --file .rabetbase/flows/purchase.json --format compress
+
+rabetbase flow update --id 42 --file .rabetbase/flows/purchase.json --dry-run --format compress
+rabetbase flow update --id 42 --file .rabetbase/flows/purchase.json --format compress
+
+rabetbase flow publish --id 42 --dry-run --format compress
+rabetbase flow publish --id 42 --yes --format compress
+```
+
+不要根据本地文件中的遗留 `id` 或 `appCode` 决定提交目标。流程 ID 来自命令参数，应用编码来自当前工作区或显式 CLI app 选择。

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

@@ -66,7 +66,7 @@ Backend Function 脚本统一存放在 `.rabetbase/bff/<appCode>/` 目录下，
 ```text
 .rabetbase/bff/<appCode>/
 ├── HOOK/
-│   └── <alias>/
+│   └── <alias-or-datasetCode>/
 │       └── <operationType>/
 │           └── <functionNode>/
 │               └── <name>.js
@@ -78,26 +78,28 @@ Backend Function 脚本统一存放在 `.rabetbase/bff/<appCode>/` 目录下，
 
 规则：
 
-* HOOK 放在 `.rabetbase/bff/<appCode>/HOOK/<alias>/<operationType>/<functionNode>/`
+* HOOK 放在 `.rabetbase/bff/<appCode>/HOOK/<alias-or-datasetCode>/<operationType>/<functionNode>/`
 * ENDPOINT 放在 `.rabetbase/bff/<appCode>/ENDPOINT/`
 * COMMON 放在 `.rabetbase/bff/<appCode>/COMMON/`
 * 本地文件是可选的人类辅助物，平台是唯一 source of truth
 
-### HOOK 目录名优先级
+### HOOK 目录协议
 
-HOOK 的第一层子目录名（标识数据集）按以下优先级确定：
+HOOK 的第一层子目录名按 SDK 模型配置确定：
 
-1. **alias**（优先）：来自 `api.ts`（`api pull` 返回的 models，按 [`sdk-client-generation.md`](sdk-client-generation.md) 维护）
-2. **datasetCode**（兜底）：当 `api.ts` 不可用时，直接使用 32 位数据集编码
+1. SDK 模型中有唯一 alias 时使用 alias。
+2. 没有可用 alias（包括已删除 Dataset 遗留的 HOOK）时，使用 Dataset code。
+3. `bff pull` 会将 lock 跟踪的旧表名或过期 alias 目录安全迁移到当前 alias；当前没有 alias 时迁移到 Dataset code。`--dry-run` 会返回迁移计划。
+4. alias / Dataset code 命名空间碰撞、映射漂移，或同一 Dataset 同时存在两个实际本地目录时，pull/push 在首次写入前失败，不猜测、不合并、不覆盖；pull 迁移时目标目录已存在也会失败。
 
-推荐先执行 `rabetbase api pull --format compress`，再按 guide 更新 `api.ts` 以获得可读 alias。
+目录协议只影响本地源码组织。正式 push 始终解析并提交平台真实 Dataset ID；operationType、functionNode 和脚本内容合同不变。
 
 ## 文件命名与函数命名
 
 | 类型 | 文件名 | 导出函数 |
 |------|--------|---------|
-| HOOK Before | `<name>.js`（位于 `HOOK/<alias>/<operationType>/before/`） | `<name>` |
-| HOOK After | `<name>.js`（位于 `HOOK/<alias>/<operationType>/after/`） | `<name>` |
+| HOOK Before | `<name>.js`（位于 `HOOK/<alias-or-datasetCode>/<operationType>/before/`） | `<name>` |
+| HOOK After | `<name>.js`（位于 `HOOK/<alias-or-datasetCode>/<operationType>/after/`） | `<name>` |
 | ENDPOINT | `<scriptName>.js`（位于 `ENDPOINT/`） | `<scriptName>` |
 | COMMON | `<scriptName>.js`（位于 `COMMON/`） | `<scriptName>` |
 
@@ -201,6 +203,14 @@ rabetbase dataset detail --code <datasetCode> --format compress \
 
 先确认“远端现在是什么”，再决定是否继续改本地、查页面或查锁状态。
 
+需要定位运行时输入、分支或异常时，用只读日志查询缩小范围：
+
+* `rabetbase bff logs --since 10 --format compress`
+* `rabetbase bff logs --since 30 --level ERROR --keyword timeout --format compress`
+* 已知精确时段时使用 `--start-time <毫秒时间戳> --end-time <毫秒时间戳>`
+
+日志查询默认最近 30 分钟、最多 200 行。无结果时先核对 App Code 和时间范围，再逐步移除 `level` / `keyword`，不要通过反复执行写操作来制造日志。
+
 ### Step 5：自检
 
 至少检查：

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

@@ -94,6 +94,7 @@ rabetbase dataset detail --code <数据集编码> --format compress \
 执行 `rabetbase bff push --type <type> --name <name> --format json`：
 * 成功项进入 `uploaded`
 * 未变更项进入 `skipped: unchanged`
+* 同步分歧进入 `conflicts`；逐项审阅 `lockKey`、`code` 和 `nextAction`，不要将它们说成失败
 * 失败项进入 `failed`
 
 ### 9. 运行态 smoke（按需）
@@ -114,11 +115,19 @@ lovrabet bff exec --appcode <appCode> --name <functionName> --params '<json>' --
 ### 10. 本地文件
 脚本内容直接保存在本地文件中，纳入 Git 管理。路径遵循 `.rabetbase/bff/<appCode>/` 目录约定（详见 `backend-function.md`）：
 * ENDPOINT → `.rabetbase/bff/<appCode>/ENDPOINT/<name>.js`
-* HOOK → `.rabetbase/bff/<appCode>/HOOK/<alias>/<operationType>/<functionNode>/<name>.js`
+* HOOK → `.rabetbase/bff/<appCode>/HOOK/<alias-or-datasetCode>/<operationType>/<functionNode>/<name>.js`
 * COMMON → `.rabetbase/bff/<appCode>/COMMON/<name>.js`
 
+`bff create` 使用 Dataset alias；没有可用 alias（例如已删除 Dataset 遗留的 HOOK）时，CLI 使用 Dataset code 目录。`bff pull` 会将 lock 跟踪的旧表名或过期 alias 目录安全迁移到当前 SDK alias；当前没有 alias 时迁移到 Dataset code。目标目录冲突、映射歧义或无法安全迁移时，命令会失败而不会覆盖本地脚本；先用 `--dry-run` 查看迁移计划。
+
 ## 冲突处理
 
+若返回 `conflicts`：
+* 告知用户冲突的 `lockKey`、`code` 和 `nextAction`
+* `BFF_LOCAL_UNSYNCED`：审阅本地脚本；确认本地版本应生效后，执行该项精确 `bff push` 命令更新远端
+* `BFF_REMOTE_VERSION_CHANGED` / `BFF_REMOTE_VERSION_MISSING`：保留本地脚本，先执行该项 `bff detail` 命令读取远端源码，合并后再重试 push
+* 不要自动使用 `--force`、盲目重试整批脚本，或将同步分歧报告为失败
+
 若返回 `failed`：
 * 告知用户失败的 `lockKey` 和错误原因
 * 不要假装成功

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

@@ -37,6 +37,8 @@
 - `--dry-run` 预览成功，不等于远端已执行
 - 命令执行失败时，不能用“已处理”“已保存”这类表述蒙混过去
 
+**BFF 同步分歧例外**：`bff pull` / `bff push` 的 `data.conflicts` 表示可恢复的本地与远端分歧，不是 `failed`。必须报告每项 `lockKey`、`code` 和 `nextAction`；`BFF_LOCAL_UNSYNCED` 经审阅后可精确 push 更新远端，`BFF_REMOTE_VERSION_CHANGED` / `BFF_REMOTE_VERSION_MISSING` 则先用其 `bff detail` 命令读取远端源码并合并。两类场景都不得自动 `--force` 或声称已完成同步。
+
 ---
 
 ## AI 的沟通义务