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

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

@@ -1,8 +1,18 @@
-# SDK 客户端代码生成（api.ts / client.ts）
+# SDK 客户端代码生成（稳定入口与模型注册表）
 
-> 目标：根据 `rabetbase api pull` 返回的数据集事实，生成或更新浏览器子应用的 `src/api/api.ts` 与 `src/api/client.ts`，并保留项目已有的自定义写法。
+> 目标：根据 `rabetbase api pull` 返回的数据集事实，维护浏览器子应用的稳定 SDK 入口，并让同一套业务 API 的不同部署使用各自正确的 `datasetCode`。
 >
-> CLI 默认不覆盖 TypeScript。`api pull` 只保证：刷新 `data.files.sdkConfig.path` 指向的应用级 SDK 路由文件、返回 `data.models`，并在文件缺失时写入 Cookie-first 脚手架。已有文件由本指南更新；只有用户明确要求放弃本地定制并完整重建时，才使用 `--force --yes`。
+> 单应用或显式配置同一 `apiGroup` 的 profile 使用注册表模式：`project create` / `project upgrade` 维护稳定源码结构，`api pull` 只刷新 `models.generated.ts` 中的模型事实。`apiGroup` 只负责归并，不进入文件名或运行时对象。
+
+## 重要运行边界：一次运行只选择一个 profile
+
+注册表模式解决的是：**同一份业务代码分别部署到不同节点，并由当前 Runtime Domain 选择唯一 profile**。它不提供跨节点数据访问，也不把多个 profile 合并成一个可同时查询的浏览器 client。
+
+- 业务代码始终通过稳定 alias 调用 `lovrabetClient.models.<alias>`；不要读取注册表后自行挑选其他 profile 的 `datasetCode`，也不要把该代码硬编码进业务模块。
+- 当前 profile 只物化自己的模型。仅其他 profile 存在的 alias 不会注册到当前 client；误用时应保留 SDK 的 `MODEL_NOT_FOUND`，不得回退默认 profile 或借用其他节点的代码。
+- 节点独有功能可先检查 `LOVRABET_PROFILE_NAME` 再决定是否调用；共享功能不需要分支，同一 alias 会自动绑定当前 profile 的代码。
+- 浏览器 Cookie 与 Runtime Domain 都属于当前节点。不要为了“一次查询两端”在浏览器中创建两个 profile client、跨 Domain 转发认证信息或绕过 Domain 选择器。
+- 真正需要跨节点读取、比对或聚合时，使用具备明确认证和授权边界的可信服务端或 Backend Function 编排；CLI 侧排查则分别用 `--app <profile>` 查询，不把两个 profile 当成一个运行实例。
 
 ## 何时执行
 
@@ -10,7 +20,7 @@
 
 - 刚执行 `rabetbase api pull` 或 `rabetbase project create`（带 appCode）
 - 平台增删了 Dataset，本地 `models` 过期
-- `api.ts` / `client.ts` 缺失、空 `models: []`、或 `LOVRABET_APP_CODE` 仍是 `NOT-SET`
+- `api.ts` / `client.ts` 缺失、注册表为空、或生成 profile 的 AppCode 仍是 `NOT-SET`
 - 用户要求修复 SDK 客户端初始化
 
 不要凭空编造 `datasetCode`。不要把本指南里的浏览器 Cookie 客户端写成服务端 `accessKey` 客户端。
@@ -18,94 +28,134 @@
 ## 工作流
 
 ```
+rabetbase project upgrade --dry-run
+  → 审阅 apiArchitecture.groups[].files[]
+rabetbase project upgrade --yes
+  → 标准旧脚手架自动备份迁移；业务定制生成候选入口
 rabetbase api pull --format compress
   → 单应用读 data；项目应用清单逐项读 data.apps[]
-  → 读取每项的 models / configName / isDefaultConfig / files / needsAgentMerge
-  → 读已有 api.ts、client.ts 与 files.sdkConfig.path（含 {prefix}-api.ts / {prefix}-client.ts / {prefix}-sdk-config.ts）
-  → 按事实更新 models，保留本地 extras
-  → 不要改已经正确的 createClient({ apiConfigName, ...LOVRABET_SDK_CONFIG })
+  → 读取每项的 models / modelProfile / files / needsProjectUpgrade
+  → 注册表模式检查 models.generated.ts / model-runtime.ts / api.ts / client.ts
+  → 验证最终 Runtime Domain 能选中目标 profile
 ```
 
-1. 执行 `rabetbase api pull --format compress`（需要人类可读缩进时用 `--format json`）。
-   - 不要自动添加 `--force`。
-   - 只有用户明确要求丢弃本地 `api.ts` / `client.ts` 定制并完整重建时，才执行 `rabetbase api pull --force --yes --format compress`；此时根据返回的 `files.*.action` 回查是否为 `overwritten`。
-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` / `{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` 的检查。
-6. 默认应用：`data.isDefaultConfig === true`，`data.configName === "default"`，代码里用 `CONFIG_NAMES.DEFAULT`。
-7. 具名应用：`data.isDefaultConfig === false`，`data.configName` 是不含引号的名字（如 `order`），`registerModels(..., "order")` 与 `apiConfigName: "order"`。不要把 `configName` 再包一层引号。
+1. 已有项目先执行 `rabetbase project upgrade --dry-run`。标准旧脚手架可直接正式升级；`manual-merge` 表示原入口含业务定制，正式升级只会写候选文件，不会覆盖原文件。
+2. 执行 `rabetbase project upgrade --yes` 后审阅 `apiArchitecture.manualMergeRequired`。候选文件在 `.rabetbase/project-upgrade/api-model-registry-v2/candidates/`；完成合并前不要删除原入口。
+3. 执行 `rabetbase api pull --format compress`（需要人类可读缩进时用 `--format json`），刷新远端 Dataset 事实。不要自动添加 `--force`；它在注册表模式只用于明确接受空结果。
+4. 直接单应用结果使用 `data.models`；项目应用清单结果逐项使用 `data.apps[].models`。不要手写或猜测 `datasetCode`。
+5. `data.modelProfile` 存在时检查 `data.files.modelRegistry`：同一平台 `alias` 只有一条模型，`tableName` 必须在各 profile 间一致。所有当前 profile 都存在且代码相同时使用 `datasetCode`；代码不同或仅部分 profile 存在时使用 `datasetCodes[modelProfile]`，缺失 profile 不写空字符串。
+6. `model-runtime.ts` 由项目创建/升级维护，`models.generated.ts` 由 pull 刷新；都不要写入凭据或应用业务函数。若 `data.needsProjectUpgrade === true`，回到第 1 步，不要手工覆盖入口。
+7. 一个 AppCode 对应多个 profile 时，所有拉取与别名写操作都用 `--app <profile>`；不要使用有歧义的 `--appcode`。AppCode 相同不会自动归并，只有显式相同的 `apiGroup` 才表示共享业务 API。
 
 ## 权威结构
 
 浏览器子应用的权威形态与 `templates/projects/sub-app-react-demo/src/api/` 一致。脚手架模板是 `templates/generate-api/*.tpl`，生成结果应对齐 demo，而不是另造一套。
 
-### sdk-config.ts / {name}-sdk-config.ts（路由，无凭证）
+### models.generated.ts（CLI 生成事实）
 
 ```typescript
-/**
- * Lovrabet SDK runtime routing.
- * Generated by Rabetbase CLI. Do not add credentials to this file.
- */
-export const LOVRABET_SDK_CONFIG = {} as const;
+/* rabetbase-model-registry:v2 */
+export const LOVRABET_MODEL_REGISTRY = {
+  defaultProfile: "oa-cn",
+  profiles: {
+    "oa-cn": {
+      appCode: "app-xxxxxxxx",
+      runtimeDomain: "https://runtime.lovrabet.com",
+    },
+    "oa-id": {
+      appCode: "app-xxxxxxxx",
+      runtimeDomain: "https://runtime.lovrabet.id",
+    },
+  },
+  models: [
+    {
+      alias: "paymentApplication",
+      tableName: "payment_application",
+      name: "Payment Application",
+      datasetCode: "shared-dataset-code",
+    },
+    {
+      alias: "orders",
+      tableName: "orders",
+      name: "Orders",
+      datasetCodes: {
+        "oa-cn": "cn-dataset-code",
+        "oa-id": "id-dataset-code",
+      },
+    },
+  ],
+} as const;
 ```
 
-默认节点保持空对象；其他官方节点和企业独立部署统一写入最终 `runtimeDomain`。不要手改成认证字段。项目模板所需的完整公开 Domain 与资源策略由独立命令 `rabetbase project domain-routing-sync` 写入项目根目录的 `rabetbase.domain-routing.json`。
+- 以平台稳定 `alias` 作为跨 profile 的模型归并键，`tableName` 作为一致性校验；同 alias 指向不同表或同表出现不同 alias 时停止写入。
+- 默认 profile 提供公共 `alias` / `name`；其他 profile 的同表展示名不同不会制造第二份模型。
+- 所有当前 profile 都存在且 Dataset 代码相同时只写单数 `datasetCode`。
+- 某 profile 独有的表只包含自己的 `datasetCodes` key；运行时不会把它提供给其他 profile。
+- 文件版本由 CLI 专用注释标记识别，不进入应用运行时对象。
+- 此文件由 CLI 原子刷新，不手工编辑。
 
-### api.ts
+### model-runtime.ts（通用选择器）
 
-```typescript
-import { registerModels, CONFIG_NAMES, type ModelsConfig } from "@lovrabet/sdk";
+该文件根据平台注入的 Runtime Domain 选择唯一 profile；本地构建读取项目根目录的 `rabetbase.domain-routing.json`。零匹配或多匹配都直接报错，不回退 `defaultProfile`。它只将所选 profile 物化为 SDK 的 `{ appCode, models }`，不会创建多节点 client，不放业务函数，也不硬编码具体 Dataset。
 
-export const LOVRABET_APP_CODE = "app-xxxxxxxx";
-
-export const LOVRABET_MODELS_CONFIG: ModelsConfig = {
-  appCode: LOVRABET_APP_CODE,
-  models: [
-    { datasetCode: "abc123", tableName: "orders", name: "订单", alias: "orders" },
-  ],
-} as const;
+### api.ts
 
+```typescript
+import { registerModels, CONFIG_NAMES } from "@lovrabet/sdk";
+import projectRouting from "../../rabetbase.domain-routing.json";
+import { LOVRABET_MODEL_REGISTRY } from "./models.generated";
+import { resolveActiveModelConfig } from "./model-runtime";
+
+const activeModelConfig = resolveActiveModelConfig(
+  LOVRABET_MODEL_REGISTRY,
+  projectRouting.domains.runtime,
+);
+
+export const LOVRABET_PROFILE_NAME = activeModelConfig.profileName;
+export const LOVRABET_APP_CODE = activeModelConfig.appCode;
+export const LOVRABET_RUNTIME_DOMAIN = activeModelConfig.runtimeDomain;
+export const LOVRABET_MODELS_CONFIG = activeModelConfig.modelsConfig;
 registerModels(LOVRABET_MODELS_CONFIG, CONFIG_NAMES.DEFAULT);
 ```
 
-- 默认应用：`data.isDefaultConfig` 为 true 时用 `CONFIG_NAMES.DEFAULT`。
-- 非默认 / 具名应用：用 `data.configName`（不含引号的字符串，如 `order`）作为 `registerModels` 第二参数和 `apiConfigName`，不要再 import 未使用的 `CONFIG_NAMES`。
-- 数字开头的文件前缀使用 `APP_` 变量前缀（如 `APP_5B732428_APP_CODE`），运行时 `appCode` 保持原值。
-- `registerModels` 是 `@lovrabet/sdk` 的独立命名导出，**不是** `client.registerModels()`。
+`api.ts` 只负责连接注册表、路由事实和 SDK 注册。业务层继续从原路径 import，无需感知 profile 数量。
+
+`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 会停止而不是猜测绑定目标。旧式前缀路径的默认应用使用 `CONFIG_NAMES.DEFAULT`，具名应用使用 `data.configName`；数字开头的文件前缀继续使用 `APP_` 变量前缀。
 
 ### client.ts（Cookie-first）
 
 ```typescript
 import { createClient, CONFIG_NAMES } from "@lovrabet/sdk";
-import "./api";
+import { LOVRABET_RUNTIME_DOMAIN } from "./api";
 import { LOVRABET_SDK_CONFIG } from "./sdk-config";
 
 export const lovrabetClient = createClient({
   apiConfigName: CONFIG_NAMES.DEFAULT,
   ...LOVRABET_SDK_CONFIG,
+  runtimeDomain: LOVRABET_RUNTIME_DOMAIN,
 });
 ```
 
-- 必须 `import "./api"`（或 `./{prefix}-api`）以执行 `registerModels`。
 - 浏览器子应用默认登录态 Cookie：省略 `authMode`，**不要**在此文件写入 `accessKey` / `token`。
-- 已有 `createClient({ apiConfigName, ...LOVRABET_SDK_CONFIG })` 且与 `data.isDefaultConfig` / `data.configName` 一致时，不要改参数形态。
-- 非生产环境脚手架可能带 `env: "daily"`；已有客户端已能工作则不要为了对称去改。
+- `runtimeDomain` 放在 spread 之后，确保运行时选中的 profile 是最终路由事实。
+
+### sdk-config.ts（路由，无凭证）
+
+该文件仍由 CLI 刷新并保持浏览器安全。注册表模式的最终 Runtime Domain 来自 `api.ts`，项目的完整公开 Domain 与资源策略由 `rabetbase project domain-routing-sync` 写入 `rabetbase.domain-routing.json`。
+
+## apiGroup、目录隔离与旧式兼容
 
-## 合并规则
+CLI 仍能读取已有 `[name-]api.ts` 中的 `models`，页面与 BFF 的 `--alias` 不会立即失效。迁移时：
 
-以 `data.models` 为 Dataset 清单的唯一事实来源：
+- 先执行 `project upgrade --dry-run`，审阅标准生成文件与业务定制文件的分类。
+- 有本地定制时，将业务 helper 移到独立业务模块；不要放进 `models.generated.ts` 或 `model-runtime.ts`。
+- 正式执行 `project upgrade --yes`；标准旧入口先备份再替换，定制入口只生成候选文件。
+- 执行 `api pull --format compress` 刷新远端事实；业务 import 继续指向 `src/api/api.ts` / `client.ts`。
+- 旧的 `[name-]api.ts` / `[name-]client.ts` 可在确认无引用后再删除；CLI 不自动删除用户文件。
 
-- **新增**：pull 有、本地没有的 `datasetCode`，追加到 `models`
-- **删除**：本地有、pull 没有的 `datasetCode`，从 `models` 移除
-- **更新**：同一 `datasetCode` 的 `tableName` / `name` 以 pull 为准
-- **别名**：本地已有且仍对应同一 `datasetCode` 的 `alias` 保留；新建项使用 pull 给出的 `alias`
-- **保留 extras**：额外的 `registerModels(...)`、额外 client 导出、项目自定义注释（非 Generated 头）不要删
-- **多应用**：继续使用 CLI 的 `{name}-api.ts` / `{name}-client.ts` 命名，不要把多个 app 的 models 揉进同一个 `api.ts`
+`apiGroup` 是显式 join key：同组 profile 的 AppCode 可以相同或不同，但必须使用同一规范化 `apiDir`；同一 `apiDir` 也只能承载一个显式组。`./src/api`、`src/api`、`src/api/` 会视为同一目录。第二套业务使用独立目录，例如 `src/api/finance`，目录内仍是无前缀的 `api.ts` / `client.ts`。同一目录下多个未配置 `apiGroup` 的历史 profile 继续使用 `[name-]api.ts` / `[name-]client.ts`，不会被静默归并。
 
 ## 认证（不要写进浏览器 client.ts）
 
@@ -137,13 +187,15 @@ export const lovrabetClient = createClient({
 | 字段 | 含义 |
 |------|------|
 | `appCode` | 当前应用 |
-| `configName` | `"default"` 或具名应用名（不含 TS 引号） |
-| `isDefaultConfig` | 默认应用为 `true` |
+| `modelProfile` | 本次刷新的 profile；旧式输出可省略 |
 | `models[]` | `datasetCode` / `tableName` / `name` / `alias` |
 | `sdkRouting` | `{ runtimeDomain?: string }` |
-| `files.api` / `files.client` / `files.sdkConfig` | `{ path, action }`；`action` 为 `created` / `overwritten` / `preserved` / `refreshed` |
-| `needsAgentMerge` | 任一 TypeScript 被 `preserved` 时为 `true`，必须合并 `models` |
-| `apiFilePath` / `clientFilePath` / `sdkConfigPath` | 与 `files.*.path` 相同，兼容路径字段 |
+| `files.api` / `files.client` / `files.sdkConfig` | 稳定入口与 SDK 路由的路径及动作 |
+| `files.modelRegistry` / `files.modelRuntime` | 注册表模式的模型事实与通用选择器路径及动作 |
+| `needsAgentMerge` | 兼容字段；旧式或自定义入口尚未接入注册表时为 `true` |
+| `needsProjectUpgrade` | 注册表事实已刷新，但稳定源码入口缺失或仍为旧结构时为 `true` |
+| `apiFilePath` / `clientFilePath` / `sdkConfigPath` | 稳定入口与 SDK 路由路径 |
+| `modelRegistryPath` / `modelRuntimePath` | 注册表模式下的生成文件路径 |
 | `modelCount` / `datasetCount` | 模型数量 |
 
 多应用时 `data.apps[]` 为上述对象的数组。

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

@@ -18,6 +18,15 @@
 
 生成或更新项目里的 `src/api/api.ts` / `client.ts` 时，先 `rabetbase api pull --format compress`，再遵守 [`sdk-client-generation.md`](sdk-client-generation.md)。浏览器子应用的默认 client 是 Cookie + `...LOVRABET_SDK_CONFIG`，不要把下面的服务端 `accessKey` 示例写进 `src/api/client.ts`。
 
+## 多 profile 的调用边界
+
+CLI 生成的多 profile 注册表用于**同一份代码在不同节点分别运行**：当前 Runtime Domain 必须且只能选中一个 profile，随后业务代码通过同一 alias 使用该 profile 的 `datasetCode`。它不表示一个浏览器实例能同时查询多个节点。
+
+- 不在业务代码中读取 `datasetCodes`、指定另一个 profile，或硬编码任一节点的 DatasetCode。
+- 当前 profile 没有某 alias 时，让 SDK 抛出 `MODEL_NOT_FOUND`；节点独有功能可先检查生成入口导出的 `LOVRABET_PROFILE_NAME`，不得回退默认 profile。
+- 不在浏览器中创建多个跨 Domain client 或转发 Cookie、AccessKey、token。确需跨节点聚合时，由可信服务端或 Backend Function 按明确授权编排。
+- 只需分别验证节点数据时，使用对应项目 profile 和运行态工具逐端验证，不把它实现成业务前端的跨节点调用。
+
 ## 初始化规则
 
 必须使用 `createClient` 命名导出，禁止使用 `new LovrabetClient()`：

package/skills/rabetbase/knowledge/approval-flow/config-json-schema.md

@@ -0,0 +1,290 @@
+# Rabetbase FlowConfig 契约
+
+本文件描述 `rabetbase flow validate/create/update/detail --output` 使用的可移植本地清单。服务端生成的 id、编码、状态和部署信息不属于本地文件。
+
+## 外层结构
+
+```json
+{
+  "flowName": "采购审批",
+  "flowDesc": "采购申请的主管审批",
+  "flowType": "INDEPENDENT_FLOW",
+  "flowJson": {
+    "pageMode": "CUSTOM_PAGE",
+    "startPageId": 10001,
+    "nodes": [],
+    "edges": []
+  }
+}
+```
+
+必填字段：
+
+- `flowName`：非空流程名称。
+- `flowType`：`FORM_FLOW` 或 `INDEPENDENT_FLOW`，不得根据节点或数据集绑定推断。
+- `flowJson.nodes`：非空节点数组。
+- `flowJson.edges`：非空连线数组。
+
+可选字段：`flowDesc`、`datasetCode`、`pageId`。
+
+`flowType` 是产品语义分类，不由节点形状推断：
+
+- `FORM_FLOW`：表单审批流，可以配置 `datasetCode`、`pageId`；人工节点只允许 `taskMode: "APPROVAL"`，禁止 `HANDLE`。
+- `INDEPENDENT_FLOW`：独立工作流，不能配置外层 `datasetCode` 或外层 `pageId`；可以同时使用 `APPROVAL` 和 `HANDLE`。
+
+独立工作流中出现审批节点不会把它变成表单审批流。需要填写、补充材料、执行或确认等人工办理步骤时使用 `INDEPENDENT_FLOW + HANDLE`。
+
+`flowJson.pageMode` 只适用于 `INDEPENDENT_FLOW`：
+
+- `CUSTOM_PAGE`：业务自定义页面，缺省时按此值处理。
+- `PLATFORM_FORM`：服务端的平台表单页面语义；当前 Skill 和 CLI 不支持生成或提交。
+
+`FORM_FLOW` 不得配置 `pageMode`。自定义页面 SDK/OpenAPI 只返回 `INDEPENDENT_FLOW + CUSTOM_PAGE`。
+
+`INDEPENDENT_FLOW + CUSTOM_PAGE` 可选配置正整数 `flowJson.startPageId`，并在 `APPROVAL` 人工节点上可选配置正整数 `pageId`。二者只用于页面跳转，不参与流程执行或业务判断；缺失时调用方自行选择页面。其他流程类型、`PLATFORM_FORM` 或非人工节点不得配置这两个导航字段。
+
+本地 FlowConfig 必须显式填写 `flowType`。CLI 不再利用服务端的历史默认值推断为 `FORM_FLOW`，避免表单审批流和独立工作流混用。
+
+Skill 根据业务逻辑直接生成完整 `nodes + edges` 拓扑，不读取或填写 SmartCode `templateName`。
+
+`appCode` 来自当前 CLI 工作区，远程定义 `id` 来自 `--id`。二者都不落本地文件。
+
+## 规范化
+
+`normalizeFlowConfig` 不修改调用方对象，并对下列旧字段产生 warning 后从规范结果移除：
+
+- 外层：`id`、`appCode`、`templateName`
+- `flowJson`：`flowKey`、`flowCode`、`flowName`、`bindDatasetCode`、`datasetCode`、`appCode`、`pageId`、`templateName`
+- 任意层级值为空的 `metadata`
+
+`flowJson.schemaVersion` 按 SmartCode 规则单独处理：空值或默认值 `approval.simple-flow.v1` 会警告并移除；其他值保留在规范结果中，并由本地校验明确返回 `Unsupported schemaVersion`。这样不会把未知或未来版本静默降级为 v1。
+
+`flow validate --write-normalized` 只写规范结果。校验器从外层元数据创建独立内存副本，临时注入编译上下文；这些值不会污染文件。
+
+## 页面模式
+
+使用 `INDEPENDENT_FLOW + CUSTOM_PAGE` 时：
+
+- 采购申请等业务数据由自定义页面直接读写业务数据集，并按业务状态展示不同页面和操作。
+- 流程只保存路由、办理人、脚本、通知等执行配置；页面通过 SDK 发起或办理任务，成功后自行更新业务状态。
+- 禁止 `flowJson.formSchema`、`flowJson.formDefinitions`、`flowJson.formPermissions`、节点 `form`、节点 `formPermission` 和 `cc.readSources`。
+- `validate/create/update/detail --output` 遇到上述字段会明确报错，不会静默删除或导出丢字段的文件。普通 `detail` 仍可只读查看远端原始定义。
+
+`INDEPENDENT_FLOW + PLATFORM_FORM` 使用平台表单能力，不属于自定义页面 SDK 的返回范围。当前 CLI 只识别该服务端语义用于明确报错，`validate/create/update/detail --output` 均拒绝生成或提交此模式；Skill 必须返回 `NEEDS_DSL_EXTENSION`。普通 `detail` 仍可只读查看远端原始定义。
+
+## 通用节点
+
+```json
+{
+  "id": "managerApprove",
+  "type": "APPROVAL",
+  "name": "主管审批",
+  "position": { "x": 300, "y": 180 }
+}
+```
+
+- 支持 `START`、`END`、`APPROVAL`、`CONDITION`、`SCRIPT`、`NOTIFICATION`。
+- 每个节点都必须有非空 `name`。
+- 每个节点都必须显式提供有限且大于等于 0 的 `position.x/y`。
+- 节点 ID 和边 ID 使用 `[A-Za-z_][A-Za-z0-9_]*`。
+- 节点和边共用一个 BPMN ID 命名空间，任何元素都不能重名。
+
+## 图结构
+
+- 必须且只能有一个 `START`，至少有一个 `END`。
+- `START` 无入边，`END` 无出边；其他节点必须同时满足必要的入边/出边要求。
+- 所有节点必须从 `START` 可达，并且每个可达节点都必须存在一条通往某个 `END` 的路径。
+- 支持自环、回退连线和多节点有向环；环路必须保留能够到达 `END` 的退出路径，不能形成无出口闭环。
+- 相同 `source + target + conditionType` 只能出现一次，即使边 ID 或 expression 不同。
+
+## APPROVAL
+
+```json
+{
+  "id": "managerApprove",
+  "type": "APPROVAL",
+  "name": "主管审批",
+  "pageId": 10002,
+  "position": { "x": 300, "y": 180 },
+  "taskMode": "APPROVAL",
+  "approvalMode": "SINGLE",
+  "sequential": false,
+  "assignee": {
+    "strategy": "FIXED",
+    "userIds": ["82"]
+  },
+  "transferCandidates": {
+    "strategy": "FIXED",
+    "userIds": ["15023", "16001"]
+  }
+}
+```
+
+- `taskMode` 支持 `APPROVAL`、`HANDLE`；省略时按 `APPROVAL`。`FORM_FLOW` 只能使用 `APPROVAL`，`HANDLE` 仅允许出现在 `INDEPENDENT_FLOW`。
+- `pageId` 可省略；仅 `INDEPENDENT_FLOW + CUSTOM_PAGE` 的 `APPROVAL` 人工节点可配置，用于待办、已办和任务详情跳转，不影响节点执行。
+- `approvalMode` 支持 `SINGLE`、`ALL`、`ANY`；省略时按 `SINGLE`。`sequential` 控制多办理人是否顺序执行，默认 `false`。
+- `FIXED` 需要非空有效 `userIds`；`SINGLE + FIXED` 只能有一个不同用户。
+- `ROLE` 需要正整数 `roleId`。
+- `transferCandidates` 可省略；存在时只支持 `FIXED`，且 `userIds` 必须非空，每项为非空字符串或正整数。
+- `taskMode: "APPROVAL"` 必须且只能有一条 `APPROVED` 出边和一条 `REJECTED` 出边，两条边都不能是默认边。
+- `taskMode: "HANDLE"` 必须且只能有一条 `ALWAYS` 出边，不能配置 `defaultFlow` 或 `expression`；办理完成后直接沿该边继续。
+- 只要流程包含决策型 `APPROVAL` 任务，就必须同时存在 `result: "APPROVED"` 和 `result: "REJECTED"` 的 END 节点。只有 `HANDLE` 的流程不要求这两个结果节点。
+
+### HANDLE 后续路由
+
+- `HANDLE` 自身不选择业务分支。自定义页面可在办理请求中的 `variables` 更新业务变量，或通过 `formPatch` 增量更新 `formData`；任务完成后，下游节点读取更新后的值。
+- 路由变量已准备好时使用 `HANDLE → CONDITION`，由 CONDITION 的表达式和默认边决定后续路径。
+- 需要 Backend Function 先计算、校验或归一化路由变量时使用 `HANDLE → SCRIPT → CONDITION`；不需要计算时可省略 SCRIPT。
+- 不允许给 HANDLE 配置多条出边，也不允许通过 `targetNodeId` 让调用方直接选择目标节点。办理节点存在多个业务结果不应判定为 `NEEDS_DSL_EXTENSION`，因为分支职责属于下游 CONDITION。
+
+### 审批超时
+
+`APPROVAL.timeout.enabled=true` 时必须配置正整数 `duration.value` 和 `SECONDS/MINUTES/HOURS/DAYS` 单位：
+
+- `AUTO_APPROVE`、`AUTO_REJECT` 必须中断当前任务，`interrupting` 省略时默认 `true`。
+- `EXECUTE_BFF` 必须配置 `scriptName`，不能中断当前任务，`interrupting` 省略时默认 `false`；可用 `resultVariable` 保存结果。
+- `HANDLE` 超时只支持 `EXECUTE_BFF`。
+
+## CONDITION
+
+```json
+[
+  {
+    "id": "edge_amount_finance",
+    "source": "amountCheck",
+    "target": "financeApprove",
+    "conditionType": "EXPRESSION",
+    "expression": "${formData.amount > 10000}"
+  },
+  {
+    "id": "edge_amount_default",
+    "source": "amountCheck",
+    "target": "approvedEnd",
+    "conditionType": "ALWAYS",
+    "defaultFlow": true
+  }
+]
+```
+
+- CONDITION 至少有两条出边。
+- 必须且只能有一条 `defaultFlow: true`。
+- 默认边必须使用 `ALWAYS`，且不能定义 `expression`。
+- 其余边必须使用 `EXPRESSION`，且必须有非空 `expression`。
+
+表达式直接读取顶层流程变量；例如发起或办理请求中的 `variables.amount` 在表达式中写作 `${amount > 10000}`，`formData` 字段写作 `${formData.amount > 10000}`。生成表达式前先按开发工作流建立变量契约，不猜测变量名或类型。
+
+## SCRIPT
+
+```json
+{
+  "id": "checkPrice",
+  "type": "SCRIPT",
+  "name": "价格校验",
+  "position": { "x": 520, "y": 180 },
+  "scriptName": "checkProductPrice",
+  "resultVariable": "priceCheckResult",
+  "async": {
+    "enabled": true,
+    "retryCount": 3,
+    "retryInterval": { "value": 30, "unit": "SECONDS" }
+  }
+}
+```
+
+- `scriptName` 必填。
+- `resultVariable` 可省略；Runtime 省略时写入默认变量 `scriptResult`。存在时必须符合变量命名规则并在流程内唯一；多个 SCRIPT 或 `EXECUTE_BFF` 超时动作必须显式配置不同的结果变量，避免默认值互相覆盖。
+- 禁止 `formData`、`approved` 和 `approval_sys_` 前缀。
+- 表达式引用某个 `resultVariable` 时，产生该变量的 SCRIPT 必须位于引用边 source 的所有上游路径；SCRIPT 自己的出边可以读取刚写入的结果。
+- `async.enabled=true` 时使用 Flowable 异步 Job；`retryCount` 默认 3、范围 1～10，`retryInterval` 默认 30 秒，也支持 `MINUTES/HOURS/DAYS`。
+- SCRIPT 接收当前流程变量作为顶层 `params`，并额外收到 `params.approvalContext`；因此业务变量 `amount`、表单字段 `formData.amount` 分别通过 `params.amount`、`params.formData.amount` 读取，不使用 `params.variables` 包装。
+
+## 节点默认抄送
+
+APPROVAL 和 END 节点可配置 `cc.recipientUserIds`。APPROVAL 在整个节点办理结束后创建默认只读抄送记录（会签/或签不会按每个办理人重复抄送），END 在到达结果节点后创建。用户 ID 必须是 1～100 个不重复的非空字符串；`visible` 可限制可见表单字段。抄送详情的 `businessVariables` 从流程当前 variables 中读取，并过滤 `approval_sys_*`、`formData` 和 `approved`；当前页面模式不支持 `cc.readSources`。
+
+## NOTIFICATION
+
+```json
+{
+  "id": "notifyApproved",
+  "type": "NOTIFICATION",
+  "name": "发送审批结果通知",
+  "position": { "x": 740, "y": 180 },
+  "config": {
+    "version": "v1",
+    "configCode": "approval_email",
+    "failurePolicy": "CONTINUE",
+    "template": {
+      "title": "审批结果通知",
+      "summary": "${event.initiatorUsername} 发起的申请已经${event.approvalResultName}",
+      "facts": [
+        {
+          "label": "申请金额",
+          "value": "${variables.formData.amount}"
+        }
+      ],
+      "detailMarkdown": "**审批节点：** ${context.nodeName}",
+      "actions": [
+        {
+          "text": "审批详情页",
+          "url": "${context.detailUrl}"
+        }
+      ]
+    },
+    "recipients": [
+      {
+        "type": "USER",
+        "role": "TO",
+        "value": "${event.initiatorUserId}"
+      }
+    ]
+  }
+}
+```
+
+配置规则：
+
+- `version` 可省略或留空，默认 `v1`；当前只支持 `v1`。
+- `configCode` 必须是从 `notification config-list` 选出的固定非空值，不能使用占位符、渠道名、URL、dataset code 或凭据。
+- `failurePolicy` 支持 `CONTINUE`、`FAIL`，默认 `CONTINUE`。
+- `template` 必填；不要输出 `theme` 或 `templateType`。
+- `template.title`、`template.summary` 必须是非空字符串。
+- `template.detailMarkdown` 可选，存在时必须是字符串。
+- `template.facts` 可选，最多 8 项；每项需要非空 `label`、`value`。
+- `template.actions` 可选，最多 2 项；每项需要非空 `text`、`url`。
+- `actions[].url` 必须使用 `http://`、`https://`，或完整受支持占位符，例如 `${context.detailUrl}`。
+
+占位符只允许以下命名空间，且根名称区分大小写：
+
+```text
+${event.xxx}
+${context.xxx}
+${variables.xxx}
+```
+
+不要使用 `{appCode}`、`${appCode}` 或其他未声明根命名空间。模板标题、摘要、facts、detailMarkdown、actions 和收件人 value 都执行该检查。
+
+收件人规则：
+
+- `recipients` 可省略或为空，此时使用渠道配置的默认目标。
+- 显式项的 `type` 支持 `USER`、`ROLE`、`EMAIL`。
+- `value` 必须是非空固定值或受支持占位符。
+- `role` 可选，支持 `TO`、`CC`、`BCC`，默认 `TO`。
+- 非空显式列表至少包含一个 `TO`。
+- `CC`、`BCC` 只对 EMAIL 渠道有效。
+- 显式收件人只用于 EMAIL 或飞书 APP 机器人；钉钉、企业微信、通用 Webhook 和飞书 Webhook 使用渠道默认目标。
+- 飞书显式收件人应使用 `TO`，并符合渠道配置的 `receiveIdType`。
+
+本地 validator 可确定并检查 version、模板必填字段、数量上限、action URL、占位符语法和 recipients 结构。`configCode` 是否存在、渠道是否支持显式收件人、模板变量解析后的真实值仍以服务端为准。
+
+## 本地校验边界
+
+当前本地校验统一由 `rabetbase flow validate` 调用内置 TS validator，覆盖本文明确列出的本地结构、规范化、节点配置、NOTIFICATION 可确定规则和图拓扑规则。Skill 不维护额外的校验脚本。
+
+本地校验不能确认：
+
+- userId、roleId、datasetCode、pageId、scriptName、configCode 是否在目标环境真实存在。
+- `configCode` 对应的当前通知渠道是否支持指定模板或显式收件人。
+- 服务端保存、编译、部署和 Runtime 执行是否成功。
+
+这些结果必须分别通过资源发现命令、服务端 flow 命令响应和 Runtime 验证确认。