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

package/skills/rabetbase/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rabetbase
-version: 2.5.2
+version: 2.5.3-beta.2
 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:
@@ -22,7 +22,7 @@ metadata:
 2. **AppCode**：确保 `.rabetbase.json` 中设置了 `apps`（单应用自动选中；多应用再配 `defaultApp`），或兼容读取的顶层 `appcode`，或通过 `--appcode <code>` / `--app <name>` 传入。旧 `.lovrabet.json` 不会自动读取
 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 …` 登记各应用，再用 `--app <name>` 临时切换，或 `workspace use --app <name>` 修改当前工作目录默认应用
+5. **多应用场景**：一个项目有多个应用时，先 `rabetbase workspace add <name> --appcode … [--region cn|id]` 登记各应用；profile 的 `region` 高于顶层国家/地区回退值。再用 `--app <name>` 临时切换，或 `workspace use --app <name>` 修改当前工作目录默认应用
 6. **平台发现**：当你不知道当前登录账号能访问哪些应用时，先 `rabetbase app list --remote`；它查询平台目录，不修改本地配置
 7. **本地配置视图**：当你要确认当前项目或全局已经登记了哪些应用、默认应用是谁时，用 `rabetbase app list`。`rabetbase app` 本身只显示帮助，不等价于 `app list`
 8. **人员目录查询**：查询某租户的人员用 `rabetbase tenant members-list --tenant-code <code>`；查询某应用的人员及其角色归属用 `rabetbase app members-list --appcode <code>`。两者均为只读全量查询，不提供分页、模糊搜索或写入能力。
@@ -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
@@ -62,13 +63,14 @@ metadata:
    - 输出很大且只需子集时，在 `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`，经人工确认后再正式发布
+   - 需要按 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. **页面体系选择**
@@ -84,6 +86,7 @@ metadata:
    - 遇到“关联数据带不出 / 数据列表页没有生成关联关系 / 页面关联绑定异常”类问题，固定顺序是：`dataset relations` 只读确认关系事实 → `dataset relation-audit` 审计关系事实风险 → `page data-list-status` 判断页面是否存在 → `page relation-audit` 审计页面绑定；若关系事实本身不对，先按 [`dataset relation-create/update/delete`](references/rabetbase-dataset-relation-mutations.md) 做 `--dry-run` 方案并等用户确认；已有页面再 `page sync --dry-run`，无页面走 `page generate-start --dry-run`
    - `page sync` 只负责同步已有数据列表页，不是数据集关系修复命令，也不能承诺自动修复所有 `wrong_code` / `wrong_label` / `missing`
    - 本地 schema 开发：[`page pull`](references/rabetbase-page-pull.md) → IDE 编辑 → [`page push`](references/rabetbase-page-push.md)
+   - 编辑 `LrSmartJsx` 时只维护 `props.render.source`，不要手写 `render.value` 或把运行时上下文改成自定义函数参数；`page push` 会使用平台正式编译器生成 `value` 并补齐 `_context`
    - 恢复已删除页面：先读 [`page restore`](references/rabetbase-page-restore.md)，CLI 产品类型只使用 `DATA_LIST|CUSTOM`；默认按 ID 自动识别，存在跨类型同 ID 时显式传 `--page-type`
    - 需要理解 formal schema 组件语义时，再按需阅读 `knowledge/page-schema/` 下的 PageSchema 组件资料；不要把它与 `rabetbase page` 命令 reference 混淆
 7. **自定义页面工作流**
@@ -95,6 +98,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**
@@ -162,7 +176,7 @@ 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`（见各命令 reference）。
+- **`api pull` / `api list`**：默认仅针对**项目** `apps`；需要合并全局已登记应用时加 `--global`。多应用遍历会在每个请求前应用该 profile 的有效 `region`；`api pull` 为非默认应用生成独立 `<name>-sdk-config.ts`（见各命令 reference）。
 - **`app list`**：默认展示**合并**后的全量；`--global` 仅全局、`--project` 仅项目（见 [`rabetbase app list`](references/rabetbase-app-list.md)）。
 
 ## app vs workspace 职责边界
@@ -323,6 +337,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` |
@@ -369,11 +385,11 @@ const result = await client.bff.execute<DashboardData>({
 | 审计数据列表页关系绑定 | [`rabetbase page relation-audit --datasetcode <code>`](references/rabetbase-page-relation-binding.md) | 只读检查数据列表页 options 绑定是否匹配 `dataset relations` |
 | 同步已有数据列表页 | [`rabetbase page sync --datasetcode <code>`](references/rabetbase-page-sync.md) | 数据集字段变更后同步到关联数据列表页 |
 | 拉取数据列表页 schema 到本地 | [`rabetbase page pull --id <pageId>`](references/rabetbase-page-pull.md) | 写入 `.rabetbase/page/<appCode>/`，进入本地编辑工作流 |
-| 推送本地数据列表页 schema | [`rabetbase page push --id <pageId>`](references/rabetbase-page-push.md) | 推送后自动回拉 canonical schema 覆盖本地 |
+| 推送本地数据列表页 schema | [`rabetbase page push --id <pageId>`](references/rabetbase-page-push.md) | `LrSmartJsx` 只维护 `render.source`，CLI 写前生成 `render.value`；推送后自动回拉 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` |
 | 独立部署应用范围补偿同步 | [`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-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 路由文件；已有 `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 内容和参数定义 |
@@ -386,6 +402,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) | 从远端同步到本地 |
@@ -430,6 +447,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` |
@@ -440,7 +458,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) |
@@ -521,3 +539,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 的沟通义务

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

@@ -113,6 +113,8 @@ rabetbase page pull --datasetcode <datasetCode> --version-tag <versionTag> --for
 1. 先 `pull` 建立基线，不要手工从零伪造页面文件
 2. 如需理解 PageSchema 组件语义，再按需查看 `knowledge/page-schema/`；那是组件知识，不是 CLI 命令 reference
 
+若页面包含 `LrSmartJsx`，只编辑 `props.render.source`。不要手写 `render.value`，也不要把平台渲染函数的内部参数模型复制进源码；`page push` 会调用平台正式编译器生成 `value`，补齐 `_context`，并在编译失败时阻止页面更新。
+
 ### 6. 推送前先做 `push --dry-run`
 
 真实推送前，先执行 [`page push`](../references/rabetbase-page-push.md) 的预演：
@@ -127,6 +129,7 @@ rabetbase page push --datasetcode <datasetCode> --version-tag <tag> --dry-run --
 - 本地是否存在基线
 - 远端页面版本是否已变化
 - 批量模式下目标页面组是否正确
+- `LrSmartJsx.render.source` 是否能被平台正式编译器成功编译
 
 若命令提示先重新 `pull`，不要盲推覆盖。
 

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
 /**
@@ -77,6 +77,7 @@ registerModels(LOVRABET_MODELS_CONFIG, CONFIG_NAMES.DEFAULT);
 - 非默认 / 具名应用：用 `data.configName`（不含引号的字符串，如 `order`）作为 `registerModels` 第二参数和 `apiConfigName`，不要再 import 未使用的 `CONFIG_NAMES`。
 - 数字开头的文件前缀使用 `APP_` 变量前缀（如 `APP_5B732428_APP_CODE`），运行时 `appCode` 保持原值。
 - `registerModels` 是 `@lovrabet/sdk` 的独立命名导出，**不是** `client.registerModels()`。
+- `api.ts` 可以作为稳定入口，从一个或多个项目内相对模块转导出模型配置。例如 `export { APP_MODELS_CONFIG as LOVRABET_MODELS_CONFIG } from "./app-api"`。CLI 会静态读取每个本地 `export … from` 目标中的模型，不执行 TypeScript；HOOK 目录和 `--code` alias 会使用汇总后的模型别名。每个 Dataset 必须只有一个 alias，且一个 alias 不能对应多个 Dataset；冲突时 CLI 会停止而不是猜测绑定目标。
 
 ### client.ts（Cookie-first）