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

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 验证确认。

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

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

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

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

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

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

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

@@ -29,7 +29,7 @@ rabetbase bff create --type HOOK --name beforeFilter --alias appUser --operation
 |------|------|
 | ENDPOINT | `.rabetbase/bff/<appCode>/ENDPOINT/<name>.js` |
 | COMMON | `.rabetbase/bff/<appCode>/COMMON/<name>.js` |
-| HOOK | `.rabetbase/bff/<appCode>/HOOK/<alias-or-datasetCode>/<operationType>/<functionNode>/<name>.js` |
+| HOOK 草稿 | `.rabetbase/bff/<appCode>/HOOK/<alias-or-datasetCode>/<operationType>/<functionNode>/<name>.js` |
 
 Backend Function 源码**仅**应在此目录树内创建与长期维护（与 `bff status` / `bff push` 扫描一致）；不要在本仓库其他路径手写 Backend Function 再尝试推送。
 

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

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

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

@@ -0,0 +1,47 @@
+# bff logs
+
+查询当前 App 的 Backend Function 运行日志，用于开发调试。命令只读，不执行或修改脚本。
+
+## 命令
+
+```bash
+rabetbase bff logs --format compress
+rabetbase bff logs --since 10 --level ERROR --keyword timeout --format compress
+rabetbase bff logs --start-time 1788433200000 --end-time 1788435000000 --limit 500 --format json
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--app <name>` | string | 否 | — | 多应用模式下指定应用名称 |
+| `--appcode <code>` | string | 否 | — | 直接指定 App Code |
+| `--since <minutes>` | number | 否 | `30` | 从结束时间向前查询的分钟数；不能与 `--start-time` 同时使用 |
+| `--start-time <ms>` | number | 否 | — | 查询开始时间，Unix 毫秒时间戳 |
+| `--end-time <ms>` | number | 否 | 当前时间 | 查询结束时间，Unix 毫秒时间戳 |
+| `--level <level>` | string | 否 | — | `DEBUG` / `INFO` / `WARN` / `ERROR` |
+| `--keyword <text>` | string | 否 | — | 对服务端格式化后的整行日志做关键字过滤 |
+| `--limit <count>` | number | 否 | `200` | 最大返回条数，范围 `1-1000` |
+
+## 时间范围
+
+- 未传时间参数时查询最近 30 分钟。
+- `--end-time` 可与 `--since` 配合，查询以指定结束时间为基准的时间窗。
+- 需要精确范围时传 `--start-time`，可同时传 `--end-time`；未传结束时间时使用当前时间。
+- `--since` 与 `--start-time` 互斥，时间戳必须为正整数，开始时间不得晚于结束时间。
+
+## 输出
+
+结构化输出的 `data` 包含：
+
+- `query`：最终发送的 `appCode`、`startTime`、`endTime`、可选过滤条件和 `limit`
+- `count`：本次返回的日志行数
+- `logs`：服务端已格式化的原始日志字符串数组
+
+无结果时先确认 App Code、运行环境和时间范围，再逐步移除 `level` 或 `keyword`。不要把查询不到日志解释为脚本一定未执行。
+
+## 参考
+
+- [backend-function.md](../guides/backend-function.md)
+- [bff detail](rabetbase-bff-detail.md)
+- [bff status](rabetbase-bff-status.md)

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

@@ -25,15 +25,21 @@ rabetbase bff pull --type HOOK --force --format json
 返回：
 - `pulled`
 - `skipped`
+- `conflicts`
 - `failed`
 
-`--dry-run` 时返回预览对象，包含远端脚本、目标 `filePath` 和预期状态（如 `would_pull` / `conflict`）。
+`--dry-run` 时返回预览对象，包含远端脚本、目标 `filePath`、`alias`、`datasetCode`、Hook operation/node 和预期状态（如 `would_pull` / `conflict`）。有已跟踪的旧 HOOK 目录需要迁移时，还会返回 `hookDirectoryMigrations`。
+
+远端脚本列表会自动聚合服务端全部分页；不会只同步第一页。
 
 ## 提示
 
-- 默认会保护本地未同步改动，冲突时进入 `skipped: local unsynced changes`
+- 默认会保护本地未同步改动，冲突时进入 `conflicts`，包含受审阅约束的 `nextAction`
+- `conflicts[].code=BFF_LOCAL_UNSYNCED` 表示本地脚本自上次 pull 后已修改；先审阅，再在本地版本应成为事实来源时执行 `nextAction.command` 精确推送更新远端。不要把它报告为失败或用 `--force` 覆盖内容
 - `--dry-run` 不会改本地文件，也不会写 lock
-- `HOOK` 落盘目录依赖 alias / datasetCode 解析
+- HOOK 一级目录优先使用 `api.ts` 模型中的 alias；没有 alias 时使用 Dataset code
+- 挂载关系中有明确 Dataset code、但当前 SDK 模型没有 alias 时，仍按原始 Dataset code 下载，不阻断其他脚本；push 更新已有脚本时仍须回读确认脚本身份、版本与挂载关系
+- pull 会将 lock 跟踪的旧表名或过期 alias 目录迁到当前 SDK alias；当前没有 alias 时迁到 Dataset code。若目标目录已存在、旧目录已被另一 Dataset alias 复用且含未跟踪脚本，或本地文件系统无法安全迁移，命令会停止且不覆盖本地脚本
 - 拉取后建议立刻跑一次 `bff status`
 
 ## 参考

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

@@ -28,12 +28,15 @@ rabetbase bff push --type HOOK --name beforeFilter --format json
 返回：
 - `uploaded`
 - `skipped`
+- `conflicts`
 - `failed`
 
 常见 `skipped` 原因：
 - `unchanged`
 
-`--dry-run` 时返回预览对象，包含本地 `filePath`、目标模式（`create` / `update`）和预期状态（如 `unchanged` / `would_push`）。
+`--dry-run` 时返回预览对象，包含本地 `filePath`、`alias`、`datasetCode`、Hook operation/node、warning、目标模式（`create` / `update`）和预期状态（如 `unchanged` / `would_push`）。
+
+`conflicts[].code=BFF_REMOTE_VERSION_CHANGED` 或 `BFF_REMOTE_VERSION_MISSING` 表示本地 lock 不能安全更新远端脚本。保留本地脚本，先执行 `nextAction.command` 的 `bff detail` 取得远端源码，审阅并合并后再重试；只在明确放弃本地修改时才考虑 `--force`。这类同步分歧不进入 `failed`，其 `nextAction` 仅供审阅后执行。
 
 ## 推送前检查
 
@@ -53,7 +56,12 @@ rabetbase bff push --type HOOK --name beforeFilter --format json
 - 推送前先跑 `bff status`
 - `--dry-run` 不会上传远端，也不会改 lock
 - 精确推单个函数时用 `--type + --name`
-- HOOK 推送依赖数据集 alias / datasetCode 和 operationType/functionNode
+- HOOK 优先从 SDK alias 目录解析 Dataset；没有 alias 时 Dataset code 目录保持可读
+- 正式上传仍使用平台真实 Dataset ID，目录名不会替代远端 Dataset 身份
+- 已有 HOOK 的 Dataset 元数据缺失时，CLI 回读脚本 ID、应用、名称、类型、版本及唯一挂载关系；全部与本地 lock 匹配才允许按脚本 ID 更新且不重绑，返回 `EXISTING_HOOK_BINDING_PRESERVED` warning；新建 HOOK 不走此路径
+- 无法解析或查不到目标 Dataset 的 HOOK 单独进入 `failed`，其余可确认目标的脚本继续上传；部分失败时命令返回 `ok: false`，必须检查 `uploaded` 与 `failed`，不要整批盲目重试
+- 预演中无法确认目标的脚本显示 `status: failed` 与 `error`，不会上传或更改 lock
+- alias 与 Dataset code 命名空间碰撞、Dataset 映射漂移或同一 Dataset 出现多个本地目录会在首次远端写入前阻断
 - HOOK 可挂载 `DB_TABLE` 或 `METADATA` 数据集；METADATA 不支持 SQL / aggregate 路径，脚本中使用平台返回的标准数据操作
 - 推送成功只代表脚本配置已同步到平台；如需确认最终运行效果，使用运行验证（例如 `lovrabet bff exec --name <functionName> --params '<json>' --format compress`）
 - 管理态已同步但运行态仍旧版本时，按传播延迟 / 缓存延迟处理：等待后重试，必要时对目标脚本精确执行 `--force` 推送；仍不生效时记录平台运行态缓存风险

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

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

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

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