@lovrabet/rabetbase-cli 2.5.4-beta.4 → 2.5.4

package/skills/rabetbase/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: rabetbase
-version: 2.5.4-beta.4
-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, approval flows and workflows, 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, creating or designing an approval flow, workflow, business process, or multi-step approval, menu, notification, knowledge base, kb search, Agent Context Rules, RULES.md, DATABASE.md, rule list/get/set, role, file/OCR, or related development workflows."
+version: 2.5.4
+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, host frontend integration, frontend subapp resources, SQL, Backend Functions, approval flows and workflows, 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, host frontend integration, subapp resource versions, SQL, BFF, creating or designing an approval flow, workflow, business process, or multi-step approval, 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:
     bins: ["rabetbase"]
@@ -66,7 +66,7 @@ Agent 负责把已授权的目标推进到可验证的结果：主动获取事
    - 需要管理不同数据库连接之间的 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` 恢复任务事实
+   - 仅在管理员明确要求独立部署首次初始化、历史回填或同步故障恢复时，读取 [`deployment sync-all`](references/rabetbase-deployment-sync-all.md)
    - DBAgent 增量分析默认先执行一次异步差异刷新：调用 `db diff-refresh-start`，保存 traceId，并用 `db diff-refresh-status` 查询同一任务到终态；成功后按原始意图执行 `db diff --all`（差异表）或 `db tables`（全部表）。无论 `tableCount` 大小都执行刷新；只有用户明确表示“不需要分析”“不刷新”或“只看现有结果”时才跳过异步刷新，并说明结果可能不是最新事实
    - 需要查看全部表（含无差异表）或主动重新分析既有表时，用 `db tables`；它固定聚合全表分页。`db diff --all` 只聚合全部差异分页
    - DB 增量分析先对完整 `toAnalyzeTables` 执行 `db analyze-batch-plan`；它生成的是本地批次方案，不是服务端 `planId`，也不会创建任务。再严格按批次顺序启动；每批独立保存 `planId`（即 `analyze-start` 返回值），当前批次到达已知终态前不得启动下一批
@@ -79,15 +79,16 @@ Agent 负责把已授权的目标推进到可验证的结果：主动获取事
    - 推荐路径：查现有(`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 工作流严格分步**
+4. **Backend Function 工作流**
    - 跨数据库连接的业务查询、关联筛选或聚合，先读 [跨库 BFF 查询与拼接](guides/cross-database-bff.md)，确认完整键、执行顺序、各端授权和结果完整性
-   - 查现有 → 确认字段或通知配置 → 查公共函数 → 本地创建(`bff create`) → 检查状态(`bff status`) → 先预览(`--dry-run`) → 再拉取/推送/删除；运行行为异常时用 `bff logs` 按时间、级别和关键字查询日志
+   - 创建或修改 Backend Function 时，按 [BFF 工作流](guides/bff-creation-workflow.md)复用有效事实、按需查询并完成必要验证；运行行为异常时用 `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` 已完成
+   - 推送成功只证明平台保存；需要确认运行效果时，按 [BFF 运行验证](guides/bff-creation-workflow.md#9-运行态-smoke按需)执行，不把保存成功当作运行验证通过
+   - 已确认独立部署并需验证、出现平台到业务环境的同步疑点或明确需要独立部署同步功能时，读取[独立部署指南](guides/independent-deployment.md)；正常开发和 push 不查询或展示 `vipDeploy`
 5. **页面体系选择**
    - 数据列表页（Data List Page）是数据集驱动的结构化页面组，用于数据查看、维护和模型验证，不等同于最终业务工作台
-   - 自定义页面（Custom Page）是完整代码文件驱动的独立页面，用于工作台、看板、门户和复杂业务交互；当前 React JSX 只是渲染实现，不是页面产品类型
+   - 自定义页面（Custom Page）是完整代码文件驱动的平台页面，用于工作台、看板、门户和复杂业务交互；当前 React JSX 只是渲染实现，不是页面产品类型
    - 图表、统计卡片和数据大屏使用自定义页面与白名单内的 ECharts
    - 页面体系不明确时，先向用户确认；不要为同一目标同时创建数据列表页与自定义页面
 6. **数据列表页（Data List Page，page）工作流**
@@ -102,7 +103,7 @@ Agent 负责把已授权的目标推进到可验证的结果：主动获取事
    - 恢复已删除页面：先读 [`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. **自定义页面工作流**
-   - 自定义页面与数据列表页是两类独立页面能力，不混用两类页面的命令
+   - 自定义页面与数据列表页是两类平台页面产品，不混用两类页面的命令
    - 创建、修改或发布前，必须先阅读 [`custom-page-workflow.md`](guides/custom-page-workflow.md)，再按其中的编排读取对应原子命令 reference
    - 编写 JSX、CSS 或词包前，必须阅读 [`generation-standards.md`](knowledge/custom-page/generation-standards.md)；选择 UI 组件时阅读 [`components.md`](knowledge/components.md)
    - 自定义页面需要发起、查询或办理独立工作流时，必须完整阅读 [`custom-page-flow-sdk.md`](guides/custom-page-flow-sdk.md) 的返回对象字段字典和页面组合规则；生成时间线 UI 还必须阅读 [`custom-page-flow-timeline-display.md`](guides/custom-page-flow-timeline-display.md)，中文页面保留“处理人 / 处理结果 / 处理说明 / 处理时间”等可见字段标题。页面使用 `useSdkClient()` 提供的当前登录态客户端调用无参数 `client.flow()`；不手动传 `appCode`、`operatorUserId`、AccessKey 或 Cookie，也不根据字段名猜测列表、详情、时间线、审批记录、抄送或批量结果的展示语义
@@ -149,6 +150,12 @@ Agent 负责把已授权的目标推进到可验证的结果：主动获取事
    - 平台上有，本地没有：说明还没登记到本地配置，可用 `rabetbase workspace add`
    - 本地有，平台上查不到：说明当前账号可能无权限，或本地配置已过时，应先核对权限与 appcode
 
+## 页面开发与宿主前端集成
+
+一个宿主应用可以集成多个前端子应用，以及多个平台页面。平台页面包括数据列表页（DATA_LIST）和自定义页面（CUSTOM）。按实际创建、集成与发布方式选择入口：子应用使用 appName 关联共享资源；平台页面走页面流程，无需额外绑定 appName；仅在明确需要调整菜单资源时使用 `menu asset-update`。具体命令选择见[宿主前端集成指南](guides/host-frontend-integration.md)。
+
+前端子应用共享资源属于宿主的前端集成配置，菜单通过 appName 关联，使用 [`menu subapp-assets-status`](references/rabetbase-menu-subapp-assets-status.md) 核查、[`menu subapp-assets-update`](references/rabetbase-menu-subapp-assets-update.md) 更新。前端 `appName` 与业务 appCode 相互独立；这两个命令将 CLI 选中的应用作为菜单宿主：支持 `--appcode` / `--app` 覆盖，也支持工作区默认应用或唯一应用；多应用未选定目标时提示选择。资源优先级为子应用共享资源优先、菜单资源回退；执行前阅读[宿主前端集成指南](guides/host-frontend-integration.md)，确定标识来源及工程对应关系，再按命令 reference 核查或更新。
+
 ## 菜单异步重新分组（`menu regroup-start`）
 
 执行前先阅读 [`menu regroup-start`](references/rabetbase-menu-regroup-start.md) 与 [`task status`](references/rabetbase-task-status.md)。该流程的完成口径不是“任务已提交”，而是异步重新分组任务到达明确终态：
@@ -362,8 +369,10 @@ const result = await client.bff.execute<DashboardData>({
 | 创建外部网站链接菜单 | [`rabetbase menu external-link-create`](references/rabetbase-menu-external-link-create.md) | `write`；显式选择 `embedded` 或 `new-window`，仅接受 HTTPS；建议先 dry-run，正式执行不要求 `--yes` |
 | 原地更新既有外链 URL | [`rabetbase menu external-link-update`](references/rabetbase-menu-external-link-update.md) | `write`；精确单 ID、URL-only；必须带旧 URL 与父级断言，先 dry-run，再复用参数正式执行 |
 | 修改任意类型菜单名称 | [`rabetbase menu rename`](references/rabetbase-menu-rename.md) | 精确单 ID、label-only；使用 `--expect-label` 防漂移，先 dry-run 并检查 before/after |
-| 同步本地微前端路由到平台 | [`rabetbase menu sync`](references/rabetbase-menu-sync.md) | 扫描 `src/pages` 创建缺失的 `procode` 菜单；不上传构建产物；正式执行前先 `--dry-run` |
-| 修改微前端菜单资源 URL | [`rabetbase menu asset-update`](references/rabetbase-menu-asset-update.md) | `write`；用 ID/path 精确选目标或显式 `--all`，默认 patch 且保留加载模式，先 dry-run 再复用参数正式执行 |
+| 注册前端子应用页面与菜单 | [`菜单树注册流程`](references/rabetbase-menu-sync.md) | 默认由 Agent 读取现有分组、规划并预演菜单树、引用共享资源、创建后回读；原有 `menu sync` 交互及批量路径保留兜底 |
+| 核查子应用资源版本 | [`rabetbase menu subapp-assets-status`](references/rabetbase-menu-subapp-assets-status.md) | 使用选中的菜单宿主与指定前端子应用，只读核查共享资源、菜单回退资源及优先级 |
+| 更新子应用共享资源 | [`rabetbase menu subapp-assets-update`](references/rabetbase-menu-subapp-assets-update.md) | `write`；按明确的 URL 列表更新指定菜单宿主中的一个既有子应用资源项，先 dry-run 获取配置摘要，正式写入时带回摘要并回读管理端 |
+| 修改平台页面或菜单兜底资源 URL | [`rabetbase menu asset-update`](references/rabetbase-menu-asset-update.md) | `write`；用 ID/path 精确选目标或显式 `--all`，默认 patch 且保留加载模式，先 dry-run 再复用参数正式执行 |
 | 查看/管理开发角色 | [`rabetbase role list/detail/update/delete`](references/rabetbase-role-list.md) | 角色类型为 ADMIN/DEV/OWNER/CUSTOM；仅 CUSTOM 可改/删；当前不提供 create；输出 `scope: dev` |
 | 解析昵称/用户名到 userId | [`rabetbase role user-resolve`](references/rabetbase-role-user-resolve.md) | 基于租户成员目录；重名时列出候选 ID，再把选中的 ID 传给 `role user-add/user-remove --user <id>` |
 | 查询租户人员列表 | [`rabetbase tenant members-list --tenant-code <code>`](references/rabetbase-tenant-members-list.md) | 先校验当前账号所属租户，再返回全量人员；不分页、不输出邮箱/手机号/头像 |
@@ -469,7 +478,7 @@ const result = await client.bff.execute<DashboardData>({
 | 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` |
+| app commands | [`detail`](references/rabetbase-app-detail.md)（按需读取平台 `vipDeploy`，不缓存到配置）/ [`list`](references/rabetbase-app-list.md)（只读应用事实；平台目录用 `list --remote`）/ [`members-list`](references/rabetbase-app-members-list.md)（应用人员及角色归属）。登记/移除应用改用 `workspace add` / `workspace remove` |
 | dataset commands | [`list`](references/rabetbase-dataset-list.md) / [`detail`](references/rabetbase-dataset-detail.md) / [`delete`](references/rabetbase-dataset-delete.md) / [`restore`](references/rabetbase-dataset-restore.md) / [`user-deleted-field-list`](references/rabetbase-dataset-user-deleted-field-list.md) / [`field-restore`](references/rabetbase-dataset-field-restore.md) / [`generate-start/status`](references/rabetbase-dataset-generate.md) / [`rename`](references/rabetbase-dataset-rename.md) / [`field-update`](references/rabetbase-dataset-field-update.md) / [`extend-update`](references/rabetbase-dataset-extend-update.md) / [`business-group-update`](references/rabetbase-dataset-business-group-update.md) / [`operations`](references/rabetbase-dataset-operations.md) / [`relations`](references/rabetbase-dataset-relations.md) / [`relation-audit`](references/rabetbase-dataset-relation-audit.md) / [`relation-create/update/delete`](references/rabetbase-dataset-relation-mutations.md) |
 | Data List Page commands | [`generate-start`](references/rabetbase-page-generate-start.md) / [`generate-status`](references/rabetbase-page-generate-status.md) / [`data-list-status`](references/rabetbase-data-list-status.md) / [`relation-audit`](references/rabetbase-page-relation-binding.md) / [`sync`](references/rabetbase-page-sync.md) / [`pull`](references/rabetbase-page-pull.md) / [`push`](references/rabetbase-page-push.md) |
 | Custom Page commands | [`create`](references/rabetbase-page-create.md) / [`custom-list`](references/rabetbase-page-custom-list.md) / [`custom-detail`](references/rabetbase-page-custom-detail.md) / [`custom-update`](references/rabetbase-page-custom-update.md) / [`custom-publish`](references/rabetbase-page-custom-publish.md) |
@@ -517,7 +526,7 @@ const result = await client.bff.execute<DashboardData>({
 
 | 错误类型           | 含义                                                       | 解决方案                                                   |
 | ------------------ | ---------------------------------------------------------- | ---------------------------------------------------------- |
-| `auth_required`    | 未登录                                                     | 执行 `rabetbase auth`                                      |
+| `auth_required`    | 当前请求缺少或未通过认证 | 先确认失败接口与身份；只有开发者侧认证失败才处理 `rabetbase auth`，不能据此判断浏览器业务会话 |
 | `config_missing`   | 未配置 appcode                                             | `rabetbase workspace init --appcode <code>` 或传 `--appcode` |
 | `flag_missing`     | 缺少必填参数                                               | 检查 reference 文档确认必填 flags                          |
 | `validation_error` | 输入校验失败                                             | 按实际诊断查证内容或参数；修复确认的错误，不迎合误报删改必要语义 |

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

@@ -193,15 +193,10 @@ rabetbase dataset detail --code <datasetCode> --format compress \
 本地文件是主工作副本：
 
 * 新建时用 `rabetbase bff create`
-* 修改时直接编辑 `.rabetbase/bff/<appCode>/...`
+* 修改前按 [BFF 工作流](bff-creation-workflow.md#3-获取本轮平台基线)取得本轮最新平台基线、保留并合并本地改动，再编辑 `.rabetbase/bff/<appCode>/...`
 * 需要远端最新内容时先 `rabetbase bff pull`
 
-如果 Backend Function 行为与预期不符，或 `push` 显示 `unchanged` 但效果没变，先确认远端实际运行的是哪份代码：
-
-* `rabetbase bff detail --id <id> --format json`
-* 必要时再 `rabetbase bff pull --format json` 同步远端到本地
-
-先确认“远端现在是什么”，再决定是否继续改本地、查页面或查锁状态。
+如果 Backend Function 行为与预期不符，或 `push` 显示 `unchanged` 但效果没变，先区分平台保存事实与目标环境的运行事实。平台保存内容未知或出现远端变化证据时，用 `rabetbase bff detail --id <id> --format json` 核对；已有明确保存结果时不反复读取。`detail` 只返回平台保存的源码，不能证明业务环境实际执行了同一版本。独立部署或存在平台到业务环境同步疑点时，按[独立部署指南](independent-deployment.md)定位，运行验证按 [BFF 工作流](bff-creation-workflow.md#9-运行态-smoke按需)执行。
 
 需要定位运行时输入、分支或异常时，用只读日志查询缩小范围：
 

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

@@ -4,22 +4,26 @@
 
 ## 核心原则
 
-平台是唯一 source of truth。修改已有脚本时，从平台拉取最新内容。
+同一平台、同一应用的同一 BFF，以平台数据库中最新成功保存的内容及版本为远端基线。Git 分支不隔离该资源，其他开发者从不同分支执行 `bff push` 也可能更新它；`git pull` 不能替代获取平台最新基线。
+
+每轮修改已有脚本前，先获取平台最新源码及版本，与本地改动比较、必要时合并，不能直接覆盖未提交修改。正式 push 继续使用版本冲突保护，防止覆盖获取基线后其他开发者或分支提交到平台的更新。
+
+同一应用、连接和资源下，已确认且仍有效的需求与依赖事实可以复用；源码基线仅复用本轮修改开始前已从平台取得的最新内容，不能用上一轮或历史会话中的源码代替。本轮编辑和测试期间不因每次本地修改重复拉取；出现远端变化证据、真实冲突或写入结果未知时，按对应规则重新核对。按任务影响选择步骤，不按改动行数或文件数量省略必要验证。遵守项目工作目录约定，不通过更换目录或配置绕过冲突。
 
 ## 工作流
 
 ```
-速查公共函数 → 确认需求 → 校验字段 → [按需]查平台 → 编写本地脚本 → 自检 → status → dry-run → push/pull → [按需]运行态 smoke
+确认需求与已有事实 → [按需]发现资源及校验依赖 → 确认平台基线 → 编写本地脚本 → 自检与相关测试 → status → dry-run → push → [按需]运行态 smoke
 ```
 
-### 0. 速查公共函数
-执行 `rabetbase bff list --type COMMON --format json` 查看已有公共函数。如有可复用的工具函数，先用 `rabetbase bff detail --id <id> --format json` 确认入参、返回值和副作用，避免按名称猜测。
+### 0. 速查公共函数（按需）
+新建能力或需要寻找可复用依赖时，执行 `rabetbase bff list --type COMMON --format json`。对拟复用但契约尚未确认的函数，用 `rabetbase bff detail --id <id> --format json` 确认入参、返回值和副作用；已有有效依赖事实且本次不改变依赖时不重复发现。
 
 ### 1. 确认需求
-写码前必须明确：类型（ENDPOINT/HOOK/COMMON）、函数名、入参、返回结构，以及是否涉及数据集或消息通知。缺失则先问用户。通知型 Backend Function 还必须确认当前应用已有的 `configCode`、接收对象、标题/摘要和是否允许执行真实发送；不能用示例编码代替真实配置。
+写码前必须明确：类型（ENDPOINT/HOOK/COMMON）、函数名、入参、返回结构，以及是否涉及数据集或消息通知。先复用已确认事实，无法从现有上下文确认的业务决策再问用户。通知型 Backend Function 还必须确认当前应用已有的 `configCode`、接收对象、标题/摘要和是否允许执行真实发送；不能用示例编码代替真实配置。
 
 ### 2. 校验依赖事实
-Backend Function 涉及数据集时，执行 `rabetbase dataset detail --code <数据集编码> --format json`（或 `compress`）确认字段名、类型、必填字段、枚举值、关联关系。禁止凭经验猜字段名，禁止把 Demo 或历史案例里的字段、表名、枚举值复制到当前脚本。
+Backend Function 涉及数据集时，核对本次依赖的字段名、类型、必填字段、枚举值、关联关系。事实缺失、依赖变化或已有证据不再有效时，执行 `rabetbase dataset detail --code <数据集编码> --format json`（或 `compress`）；已确认且未变化的事实直接复用。禁止凭经验猜字段名，禁止把 Demo 或历史案例里的字段、表名、枚举值复制到当前脚本。
 
 不读写数据集的纯消息通知 ENDPOINT 可以不依赖数据集；业务明确要求在数据集操作执行前发送预通知或告警时使用 Before HOOK；作为数据集操作成功后副作用的通知，只有响应结果已包含通知所需字段时才使用 After HOOK。三者都必须按 [`backend-function.md`](backend-function.md) 的“消息通知扩展”核对 `configCode`、`audiences` 和 `message`。先执行以下只读命令获取当前应用的 EMAIL 配置：
 
@@ -45,12 +49,12 @@ rabetbase dataset detail --code <数据集编码> --format compress \
 
 涉及跨连接读取或拼接时，先读 [跨库 BFF 查询与拼接](cross-database-bff.md)，确认完整键、基数、目标字段用途、各端授权和读取预算。业务关系说明与平台登记事实分别核对；冲突时报告差异，不能自动采用平台关系。复合键不能拆成独立的单字段 Relation。
 
-### 3. 查平台（按需）
+### 3. 获取本轮平台基线
 * 新建 → 跳过
-* 修改已有 → 执行 `rabetbase bff list --format json`（ENDPOINT 或 COMMON） + `rabetbase bff detail --id <id> --format json` 取 `id` 和最新内容
-* 不确定 → 查一下
+* 修改已有 → 已知 ID 时执行 `rabetbase bff detail --id <id> --format json` 获取最新源码及版本；ID 未知时先 list 定位。本轮已通过 detail 或 pull 取得同一目标最新基线时不重复读取。需要更新本地副本时按冲突规则 pull 或合并，不覆盖未审阅的本地改动
+* 目标不确定 → 先 list 定位，再读取所选资源详情
 
-命中同名脚本时，停下问用户：修改还是另起新名。
+新建时命中同名脚本且用户意图不明确，再确认修改还是另起新名；用户已明确要求修改目标函数时直接继续。
 
 ### 4. 编写脚本（规范路径）
 新建脚本应使用 **`rabetbase bff create`**，在 **`.rabetbase/bff/<appCode>/...`** 下生成脚手架后再编辑（路径与 `bff status` / `bff push` 一致）。**不要**在 `src/` 或仓库任意目录手写 Backend Function 再期望被 CLI 识别。
@@ -59,6 +63,8 @@ rabetbase dataset detail --code <数据集编码> --format compress \
 通知需要在数据集 `create` / `update` / `delete` 执行前明确预告，并且通知失败应阻止本次操作时，选择 Before HOOK；通知由数据集操作成功触发，且响应结果已包含通知所需字段时，选择 After HOOK；响应结果不包含通知所需字段时，选择能在写入前读取并暂存必要字段、在成功后发送通知的受控 `ENDPOINT`。三者都使用 `await context.client.extension.execute("notification", "send", ...)`，并由 runtime 注入可信 `appCode` 和当前用户；不要把 `appCode`、渠道地址或密钥作为外部参数透传。
 
 ### 5. 自检
+按变更影响运行相关行为测试，覆盖本次目标及受影响的既有约束；涉及权限、写入或外部副作用时验证相关入口。测试证据必须对应最终待推送内容及依赖，合并后内容变化须重跑受影响测试。
+
 * 方法名正确
 * 单条查询用 `getOne`
 * `DB_TABLE` 优先使用 `context.client.models.byTable("<物理表名>")`；同名表存在多个 dblink 时补 `{ dblinkId: <已确认 ID> }`
@@ -99,8 +105,12 @@ rabetbase dataset detail --code <数据集编码> --format compress \
 * 同步分歧进入 `conflicts`；逐项审阅 `lockKey`、`code` 和 `nextAction`，不要将它们说成失败
 * 失败项进入 `failed`
 
+push 失败或响应丢失时，按[写入结果与恢复动作](conflict-detection.md#写入结果与恢复动作)处理。
+
 ### 9. 运行态 smoke（按需）
-`rabetbase bff push` 只证明脚本配置已同步到平台管理侧。若本轮需求要求确认最终运行效果，应显式进入运行验证，例如在已安装并配置运行 CLI 的环境中执行：
+`rabetbase bff push` 的成功保存结果只证明对应脚本配置已写入平台。若需求要求确认运行效果，核对目标应用后执行验证；非独立部署应用沿用平台内的普通验证流程。已确认独立部署，或出现平台到业务环境的同步疑点时，读取[独立部署指南](independent-deployment.md)。
+
+通过目标浏览器请求验证，或在运行 CLI 已配置到对应业务环境、认证与权限适用、函数契约及参数已确认且副作用获准后执行：
 
 ```bash
 lovrabet bff exec --appcode <appCode> --name <functionName> --params '<json>' --format compress
@@ -111,8 +121,6 @@ lovrabet bff exec --appcode <appCode> --name <functionName> --params '<json>' --
 * `lovrabet bff detail` 只确认运行契约和版本，不返回脚本源码；通知参数必须来自本地已审查脚本或明确业务契约，不能按函数名猜
 * 通知执行超时或客户端未拿到结果时，先按“状态未知”处理；不得自动重试，避免重复发送
 * `lovrabet` CLI 不可用、未配置或无权限时，明确记录“运行态 smoke 未执行”，不要把它写成 `rabetbase` 验证已通过
-* 管理态已同步但运行态仍返回旧版本时，优先按传播延迟 / 缓存延迟处理：等待后重试；必要时再对目标脚本执行一次精确 `bff push --force --type <type> --name <name>`
-* 多次重试仍旧版本时，记录平台运行态缓存风险并上报；不要通过修改 Skill、配置文件或另建脚本来掩盖
 
 ### 10. 本地文件
 脚本内容直接保存在本地文件中，纳入 Git 管理。路径遵循 `.rabetbase/bff/<appCode>/` 目录约定（详见 `backend-function.md`）：
@@ -135,18 +143,11 @@ lovrabet bff exec --appcode <appCode> --name <functionName> --params '<json>' --
 * 不要假装成功
 * 已成功推送的其他脚本不会自动回滚
 
-## 本地文件
-
-正常流程：先在本地创建/修改，再通过 `push` 同步远端，路径同 Step 10（`.rabetbase/bff/<appCode>/` 下）。
-例外场景：
-* 用户主动要求"同步平台最新到本地" → 从平台拉取 → 覆盖本地（`bff pull`）
-* 用户要求删除脚本 → `bff delete --yes --target ...`
-
-修改已有脚本时，从平台拉取最新内容。
+## 验证与收尾
 
-## 修改已有脚本
+优先消费 CLI 返回的保存及锁更新结果。最终内容通过相关测试、平台保存结果明确、本地同步状态正确且本次要求的运行验证完成后，报告结果并结束。无法完成的环节明确标为未验证，不把保存成功当成运行验收成功。
 
-`rabetbase bff list --format json` → `rabetbase bff detail --id <id> --format json` 拉最新内容 → 如需覆盖本地则 `bff pull` → 修改本地文件 → `bff status` → `bff push`
+仅在内容、依赖、配置或目标变化，出现冲突、失败、未知结果或新风险时，追加能解决该问题的检查。没有新证据时不重复同内容测试、远端回读或 push；这不限制对真实失败的继续调查。
 
 ## Backend Function 语义差异
 

package/skills/rabetbase/guides/host-frontend-integration.md

@@ -0,0 +1,62 @@
+# 宿主前端集成
+
+按用户目标和已有对象选择流程。已有 pageId 且页面产品类型明确时，直接进入对应页面工作流；类型未知时先读取页面事实。处理前端子应用接入或资源版本时，再确定宿主与 appName；CLI 通过 `--app-name` 显式接收标识，不自动从当前工程推导。
+
+## 产品对象与操作入口
+
+`appCode` 唯一标识一个应用；该应用承载前端集成时称为“宿主应用”。确定目标 `appCode` 后即确定宿主，无需在该 appCode 下再选择另一个宿主实体。应用权限也直接归属于这个 appCode；同一应用可以集成多个以 `appName` 区分的前端子应用。
+
+一个宿主应用可以集成多个前端子应用，以及多个平台页面。平台页面包括数据列表页（DATA_LIST）和自定义页面（CUSTOM）；前端子应用是拥有自身工程、构建资源和页面路由的集成单位。菜单承载导航、路由及资源关联，不要求每个菜单都属于某个子应用。
+
+| 产品对象 | 定位与操作入口 |
+| --- | --- |
+| 前端子应用 | 按宿主 appCode + appName 定位共享资源；需要注册本地页面路由时使用 `menu sync`，保留菜单分组与绑定 |
+| 数据列表页（DATA_LIST） | `page generate-start` 发起异步生成，生成流程自动创建菜单入口；通过 `page generate-status` 跟进任务，以 `page data-list-status` 核对页面组及对应菜单，无需额外绑定 appName 或用 `menu sync` 注册菜单 |
+| 自定义页面（CUSTOM） | `page create` 同时创建页面与菜单入口；后续按 pageId 使用 `page custom-update` 保存、`page custom-publish` 发布，无需额外绑定 appName 或用 `menu sync` 注册菜单 |
+
+平台页面的完整工作流分别见[数据列表页开发](page-development-workflow.md)和[自定义页面开发](custom-page-workflow.md)。自定义页面的创建来源、完整文件更新与发布核验分别见 [`page create`](../references/rabetbase-page-create.md)、[`page custom-update`](../references/rabetbase-page-custom-update.md)、[`page custom-publish`](../references/rabetbase-page-custom-publish.md)。仅在明确需要调整菜单资源配置时，按 [`menu asset-update`](../references/rabetbase-menu-asset-update.md) 精确维护对应菜单；这不属于每次页面发布的必做步骤。
+
+数据列表页的生成与核验见 [`page generate-start`](../references/rabetbase-page-generate-start.md)、[`page generate-status`](../references/rabetbase-page-generate-status.md)、[`page data-list-status`](../references/rabetbase-data-list-status.md)。任务提交成功不代表页面和菜单已就绪；生成后核对完整页面组及对应菜单事实，不把菜单可见性等同于菜单是否存在，也不要求每个辅助页面都有可见菜单。预期菜单入口缺失时报告并核查，不自动用 `menu sync` 补建。
+
+根据已有页面产品类型、菜单绑定、工程部署方式和用户目标选择流程。PageSchema 是数据列表页的页面描述技术，JSX 是自定义页面的实现技术，不作为额外产品类别；文件类型、页面数量、目录或包名也不能单独决定是否属于子应用。未绑定 appName 可能是尚未接入的子应用，应结合已有事实判断。归属明确时继续对应流程，不明确时只澄清本次目标的集成方式。平台页面不为使用共享资源而自动改造成子应用，也不强制补 appName。
+
+子应用共享资源属于宿主的前端集成配置，菜单通过 appName 关联。同一宿主中的多个子应用分别使用各自的 appName；更新一个子应用时保留其他子应用与平台页面的配置。资源优先级判断仅适用于关联该子应用的菜单：共享资源优先，菜单资源回退；不扩展到宿主中的所有页面。`menu sync` 负责子应用本地路由注册，不替代平台页面的创建、内容更新与发布。
+
+## 子应用标识与来源
+
+`appName` 是同一宿主内稳定的前端子应用标识：宿主 `extend.assets[].appName` 与关联菜单 `extend.appName` 精确匹配。版本升级沿用该标识，只更新资源 URL。子应用访问的业务 appCode、CLI 应用 profile 和 `.rabetbase.json` 的 `defaultApp` 都不是该标识。
+
+1. 沿用 CLI 的应用选择确定宿主：支持默认应用、唯一应用以及 `--appcode` / `--app` 覆盖。默认应用与目标宿主不同才覆盖，不要求每次显式传宿主。
+2. 用户已提供准确标识时，用该值查询共享资源并核对关联菜单；用户只给了业务名称时，先定位真实标识。
+3. 未提供标识时，用 `menu list --verbose` 读取 `extend.appName`，结合当前工程的页面路由、已知部署资源及用户提供的对应关系，定位属于本工程的菜单绑定。已知宿主共享配置中的标识也可作为候选。仅宿主内候选唯一、名称相似或单个路径相同，不足以证明属于当前工程。
+4. 有明确对应关系且标识唯一时，沿用平台已有值。多个候选、来源冲突或无法建立工程对应关系时，展示候选和来源，请用户选择；不要自行改名或覆盖绑定。一个工程包含多个子应用时按本次目标分别定位。
+5. 首次接入且没有已有绑定时，可参考工程现有命名提出候选，由用户确定标识；用户已明确指定时无需重复确认。`package.json.name`、目录名及构建目录中的名称只是线索，不作为平台标识的自动默认值；包名改变也不自动修改已有绑定。
+
+```bash
+# 读取标识必须带 --verbose；将占位符替换为已确定的宿主与标识
+rabetbase menu list --appcode <host-appcode> --verbose --format json
+rabetbase menu subapp-assets-status --appcode <host-appcode> --app-name <app-name> --format json
+```
+
+执行前说明已定位的宿主、标识及其来源，例如：“已定位宿主 A 下的子应用 store-app，标识来自当前工程对应菜单的绑定；本次更新它的共享资源 URL。”已有授权和明确对应关系时继续执行，无需重复确认。
+
+## 子应用资源版本核验
+
+1. 用户只提供版本号时，先从用户提供的完整 URL、项目已有发布记录或构建上传结果中确认该版本对应的完整资源 URL 列表；版本号本身不是资源地址。不要仅凭 `package.json.version`、目录名称或替换旧 URL 中的版本字符串构造目标 URL。查不到可信对应关系时，说明缺少哪一版本的资源地址并请用户补充，暂不写入。
+2. 用户指定“从 A 升到 B”时，先按共享资源优先、关联菜单资源回退的规则读取当前配置，并核对它与 A 的资源 URL 对应。当前配置已经等于 B 的完整 URL 列表时，报告配置已匹配，无需重复写入；当前配置与 A 不符、当前采用菜单回退且各关联菜单版本不一致，或无法确认 A 时，展示实际配置和差异，先澄清起点，不把预演指纹当成 A 版本已核验的证明。
+3. 检测环境与本地发布版本是否一致时，比较实际发布资源的完整 URL 列表，并注明来源。本地包版本或源码版本不足以证明发布产物一致；没有可信发布资源地址时，报告“缺少发布资源依据，无法判断”，仍可列出已读取的共享配置和菜单回退配置。
+4. 结论区分“资源 URL 配置一致”“CDN 文件内容已验证”“目标宿主加载已验证”。仅查询或更新管理端配置时只确认第一项，不能据此声称发布内容或实际加载版本已验证。
+
+## 查询结果与后续操作
+
+- `data.appName` 是输入 `--app-name` 去除首尾空白后的回显，不表示已匹配到配置。`sharedConfigured` 表示存在对应共享配置条目，`boundMenus` 表示关联菜单数量；共享资源是否可用还要检查 `sharedResources` 是否非空。
+- 有菜单绑定但没有共享配置时，沿用菜单中的标识，引导在宿主中配置共享资源，并保留原有菜单资源。`menu subapp-assets-update` 只更新已有条目；首次建立条目需使用平台已有配置入口，配置后再查询核对，不把更新命令当作创建命令。
+- 没有共享条目且没有关联菜单时，报告“该宿主下未找到此标识的共享配置或菜单绑定”，核对目标或按首次接入处理；不能凭回显报告已找到子应用。
+- 检测子应用版本先比较非空共享资源，其次比较关联菜单资源；共享配置缺失时可以如实报告菜单当前配置，不自动写入或切换到逐菜单更新。数据列表页和自定义页面按各自页面流程核查，需要菜单资源时单独核查该菜单。
+- 注册子应用页面时，将已确定的同一标识传给 `menu sync --params` 中的 `appName`，按现有菜单树保留分组；回读绑定时使用 `menu list --verbose`。共享资源更新和菜单注册分别按下列 reference 预演、执行和核验。
+
+## 命令契约
+
+- [查询共享资源](../references/rabetbase-menu-subapp-assets-status.md)
+- [更新已有共享资源](../references/rabetbase-menu-subapp-assets-update.md)
+- [注册菜单及保留原有操作路径](../references/rabetbase-menu-sync.md)

package/skills/rabetbase/guides/independent-deployment.md

@@ -0,0 +1,45 @@
+# 独立部署：开发、验证与排障
+
+## 何时读取
+
+仅在已确认独立部署并需要运行验证、出现平台到业务环境的同步疑点，或明确需要独立部署同步功能时读取。非独立部署应用只在 Lovrabet 平台内开发与验证，沿用普通工作流，不引入独立业务库或日常到线上的流程。
+
+正常开发、绑定项目和正常 push 不查询或展示 `vipDeploy`。出现异常时，先确认平台是否保存、实际验证目标及失败步骤；已有证据定位其他原因时，不追加能力查询。
+
+## 按需确认同步能力
+
+需要判断显式同步能力时，用 [`app detail`](../references/rabetbase-app-detail.md) 读取 `app/getOne` 的 `vipDeploy`；选择器、输出与错误契约见命令参考。不从本地同名字段、CLI Domain、`rabetbase.domain-routing.json` 的 `mode` 或前端是否嵌入平台推断标识，也不用 `workspace init/use` 查询它。
+
+- `true` 允许考虑显式同步功能，但不是故障证据、完成证明或执行授权；实际操作仍须满足对应权限与前提。
+- `false` 不推荐显式同步恢复；`null` 或查询失败表示能力未确认。继续目标核对、平台回读及失败请求定位，不把未知当成关闭，也不回退本地值。
+- 同一轮、同应用和平台连接复用查询结果；切换目标或结果可能变化时，仅在仍需要该事实的情况下重查。
+
+`vipDeploy` 不提供业务环境地址、发布顺序或登录状态。保存后的自动同步由 `enableAutoSync` 及直连状态另行决定，不能由该标识的 true/false 推断自动同步是否开启；具体部署链路须另行确认。
+
+## 确认连接与项目链路
+
+无论应用是否独立部署，`rabetbase` 始终使用 `.rabetbase.json` 及现有配置解析机制访问 Lovrabet 平台服务端，沿用开发者认证；`vipDeploy` 仅用于 Agent 引导，不改变请求目标或认证方式，也不读取 `.lovrabet.json` 连接业务服务。`lovrabet` 使用 `.lovrabet.json` 对应的业务连接和业务账号 AccessKey。核对执行目录、所选应用和各 CLI 实际生效的配置，包括参数、环境变量等覆盖，并与页面实际请求目标对应。相同 AppCode 或 `env` 不证明连接同一环境，`env=production` 也不单独表示企业业务线上。
+
+从项目已确认的部署约定获取同步目标和后续发布步骤。若项目明确“平台只连接业务日常，日常验证通过后按既有发布流程同步业务线上”，push 后先验证日常，线上单独核对发布。其他项目按各自约定处理，不猜环境数量、域名用途或发布顺序。已知事实一致时直接继续；信息缺失或冲突时先补齐，不切换另一环境试验，不复制两侧凭据或改写配置来消除错误。
+
+## 按实际环节定位
+
+| 已确认的事实 | 下一步 |
+|---|---|
+| push 失败或响应丢失，平台保存结果未知 | 按[写入结果与恢复动作](conflict-detection.md#写入结果与恢复动作)先回读；确认未保存后解决原因，遵循原有冲突保护恢复必要的精确 push。后续步骤失败不抹去平台已保存事实 |
+| 平台内容已新，独立业务目标库内容仍旧 | 核对平台到目标库的同步记录及同一资源的保存版本或内容；再次 push 不能替代这段同步的故障定位 |
+| 仅页面表现或运行态返回版本仍旧，目标库保存内容未知 | 先确认请求目标及同一资源的目标保存事实，不能直接判定同步失败；缺少读取权限时明确该事实尚未确认 |
+| 平台及目标库内容均已新，执行结果仍旧 | 转查请求目标、加载或执行行为；执行结果旧不证明存储旧，缓存只是待证实原因之一，不据此重推或补偿同步。本指南不展开缓存处理 |
+| 日常已新，线上仍旧，且项目有这段发布流程 | 核对既有日常到线上发布记录及线上目标内容；不能据此判定平台保存或平台到日常同步失败，也不用平台补偿同步替代线上发布 |
+
+没有目标保存证据时，明确“目标库是否收到新内容尚未确认”，交由有权限的人核查；不只查平台就宣布运行端已生效，也不凭标识假定双库同步。
+
+显式任务的查询范围与结果解释见 [`deployment sync-all`](../references/rabetbase-deployment-sync-all.md#查询任务)。仅在确认属于初始化、回填或同步故障恢复且获授权时考虑该命令，遵循其能力、权限和安静窗口要求，不自动发起补偿。
+
+## 认证、运行验证与反馈
+
+认证失败先定位该请求的环境、接口及实际凭据，并确认目标确实提供所需研发接口；不能从业务运行域名推导另一套研发管理连接。平台开发者凭据、各业务环境的 CLI AccessKey、浏览器会话分别核验；同一账号也不代表 CLI 与浏览器会话同时有效。业务 CLI 认证失败只处理对应连接与凭据；只有正确平台开发接口明确认证失败才处理 `rabetbase` 登录，只有页面实际请求明确会话失效才引导该页面重新登录。404、权限不足和旧版本均不能直接归因为登录过期，不反复生成登录链接。
+
+使用目标浏览器请求，或已连接同一业务环境且具备相应权限的 `lovrabet` 验证。BFF 的契约、参数、副作用及授权要求沿用[运行态 smoke](bff-creation-workflow.md#9-运行态-smoke按需)；无法执行时如实报告未验证。
+
+Agent 负责区分上下文，无需要求用户先理解认证架构。只报告项目实际存在的环节及证据，例如“平台已保存，业务日常验证通过；线上更新需核对既有发布流程”，或“业务 CLI 的验证请求未通过认证，尚不能据此判断页面登录状态”。

package/skills/rabetbase/guides/troubleshooting.md

@@ -14,6 +14,14 @@
 
 ---
 
+## 认证错误
+
+先定位失败请求及其所用凭据。只有开发者侧接口明确认证失败才处理 `rabetbase` 登录；其他请求失败不能推出开发者或浏览器会话失效，404、权限不足和旧版本也不能直接当作登录过期。
+
+## 独立部署应用：平台已保存但运行未生效
+
+已确认独立部署，或平台保存后出现业务同步疑点时，按[独立部署指南](independent-deployment.md)处理。非独立部署应用沿用普通排查，不预设独立业务库或后续线上发布。
+
 ## 诊断肌肉记忆（强制）
 
 ### 1. 听到"查不到数据"、"空数组"
@@ -55,7 +63,7 @@
 * ❌ 错误排查方向：建议用户重装各种库
 * ✅ **强制动作**：
   * 建议用户检查 `.rabetbase.json` 中的 `appcode` 是否正确
-  * 建议用户在终端执行 `rabetbase auth` 检查是否未登录或 Cookie 过期
+  * 先定位失败请求及错误类别；只有开发者侧接口明确认证失败，才检查开发者凭据。`Dataset not found` 本身不是未登录的证据
   * 帮用户执行 `rabetbase dataset list --format json` 确认该环境到底有哪些可用数据集
 
 ---

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

@@ -0,0 +1,31 @@
+# rabetbase app detail
+
+按需读取所选应用的独立部署数据同步能力标识 `vipDeploy`。风险等级为 `read`，需要当前开发者凭据及应用访问权限。
+
+```bash
+rabetbase app detail --format compress
+rabetbase app detail --app <name> --format compress
+rabetbase app detail --appcode <code> --format compress
+```
+
+不传选择器时使用当前应用；`--app` 临时选择已配置 profile，`--appcode` 指定 AppCode。多 profile 对应同一 AppCode 时使用 `--app` 消除歧义。沿用所选应用的既有平台连接及开发者凭据，不根据业务域名猜测平台地址。
+
+## 输出
+
+`data` 只包含 `vipDeploy`：
+
+| 值 | 含义 |
+|---|---|
+| `true` | 平台允许进入该应用的显式独立部署数据同步流程，仍需满足对应权限和参数要求 |
+| `false` | 平台未开启该能力，显式同步接口跳过执行；不推荐使用同步恢复功能 |
+| `null` | 请求成功，但返回字段缺失或不是可识别的布尔值，尚未确认 |
+
+例如：`"data":{"vipDeploy":true}`。
+
+平台应用详情是唯一事实来源。每次执行读取一次，不透出整个扩展对象，也不返回其他部署配置。不会读取本地 `vipDeploy`，不会写 `.rabetbase.json`、改变默认应用或刷新本地缓存。手工配置的同名字段不参与判断。
+
+网络、权限或认证失败正常返回错误，不以本地值兜底，也不转换成 `false` 或 `null`。
+
+## 使用场景
+
+按需查询的触发条件、结果处理及部署排查统一见[独立部署指南](../guides/independent-deployment.md)。

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

@@ -27,7 +27,7 @@ rabetbase bff detail --id 42 --verbose --format json
 
 ## 提示
 
-- 修改已有 Backend Function 前必须先用此命令拉取最新内容（平台是 source of truth）
+- 每轮修改已有 Backend Function 前必须取得平台最新基线；本轮已通过 detail 或 pull 获取时不重复读取，具体遵循 [BFF 工作流](../guides/bff-creation-workflow.md#3-获取本轮平台基线)
 - scriptContent 是完整的 JavaScript 源码
 - 需要落本地维护时，优先用 `rabetbase bff pull --format json` 同步到规范目录
 

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

@@ -63,8 +63,8 @@ rabetbase bff push --type HOOK --name beforeFilter --format json
 - 预演中无法确认目标的脚本显示 `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` 推送；仍不生效时记录平台运行态缓存风险
+- 推送成功只代表脚本配置已同步到平台；需要运行验证时，按[创建流程的运行验证步骤](../guides/bff-creation-workflow.md#9-运行态-smoke按需)确认目标、权限及函数副作用后执行
+- 已确认独立部署并需验证，或出现平台到业务环境的同步疑点时，读取[独立部署指南](../guides/independent-deployment.md)；普通 push 不额外查询部署标识
 
 ## 参考
 

package/skills/rabetbase/references/rabetbase-data-list-status.md

@@ -18,6 +18,7 @@ rabetbase page data-list-status --alias order --format json
   - 菜单事实
 - 它不返回异步任务的执行进度，也不负责表达 job 状态。
 - 这是 `page generate-start` 的前置判定与终态回查依据，属于事实接口，不是任务状态接口。
+- 数据列表页生成流程会自动创建菜单入口。生成后核对页面组及其对应的 `hasMenu`、`menuPath`、`menuVisible`：菜单存在与是否可见是不同事实，不要求每个辅助页面都有可见菜单。预期入口缺失时报告并核查，不自动使用 `menu sync` 补建或绑定子应用 appName。
 
 ## 适用场景
 

package/skills/rabetbase/references/rabetbase-deployment-sync-all.md

@@ -1,6 +1,6 @@
 # rabetbase deployment sync-all
 
-研发资源保存后的增量同步由服务端自动处理。`deployment sync` 已移除，`bff push` 与 `sql push` 也不再追加客户端同步请求。
+`sync-all` 提交应用范围的显式补偿任务。自动同步与项目后续发布步骤的区别见[独立部署指南](../guides/independent-deployment.md)。`deployment sync` 已移除，`bff push` 与 `sql push` 不追加客户端同步请求。
 
 `sync-all` 是管理员补偿工具，仅用于以下场景：
 
@@ -13,7 +13,9 @@
 ## 使用前确认
 
 - 已完成 rabetbase 认证，并明确目标应用的 `appCode`。
+- 已按[独立部署指南](../guides/independent-deployment.md)确认平台同步的实际目标及本次操作所处环节。
 - 已确认属于初始化、回填或恢复场景，而不是普通资源保存或发布。
+- [`app detail`](rabetbase-app-detail.md) 已确认 `vipDeploy=true`，并具备相应权限与执行授权；未确认能力时不提交任务。
 - 应用已停止编辑，当前处于安静窗口，避免全量任务与服务端自动增量同步并行。
 - 已准备在任务结束后执行独立的业务验收。
 
@@ -51,6 +53,8 @@ rabetbase deployment sync-status --job-id <jobId> --format compress
 rabetbase deployment sync-jobs --appcode <appCode> --format compress
 ```
 
+这些查询用于显式提交的同步任务，不包含保存后自动产生的增量同步任务；不能用空列表判断自动同步是否运行或失败。
+
 只根据 `isTerminal` 判断是否为已知终态；若为 `null`，保留服务端状态并交给用户判断。逐项资源类型和 action 是服务端开放字符串，不建立枚举闭集，也不因新值自动重提。
 
 任务成功只表示服务端完成了当前支持范围内的 UPSERT。目标端额外记录不会被删除，且任务明细可能受服务端保留上限影响，因此完成后仍需按业务事实验收。

package/skills/rabetbase/references/rabetbase-menu-asset-update.md

@@ -1,8 +1,10 @@
 # menu asset-update
 
-更新指定线上微前端菜单的 CDN 资源 URL。
+更新指定线上菜单自身的 CDN 资源 URL。宿主可同时集成多个前端子应用和平台页面（数据列表页、自定义页面）。平台页面按其配置与发布流程管理，需要菜单资源时，该资源是正常加载配置，无需绑定 appName；本命令不修改页面内容或代替页面发布。绑定有效子应用共享资源时，支持该机制的宿主优先加载对应子应用的共享资源，菜单资源才作为兜底。
 
-> **风险等级：write** — 修改线上菜单运行资源；建议先 dry-run，正式执行复用相同参数并移除 `--dry-run`。
+仅在明确需要调整菜单资源时，平台页面才按菜单 ID/path 使用本命令。例如，自定义页面通过 [`page create`](rabetbase-page-create.md) 同时创建页面与菜单，后续按 pageId 使用 [`page custom-update`](rabetbase-page-custom-update.md)、[`page custom-publish`](rabetbase-page-custom-publish.md) 保存和发布，无需额外绑定 appName 或用 `menu sync` 注册菜单。前端子应用先用 `rabetbase menu subapp-assets-status --appcode <host-appcode> --app-name <name>` 核查，升级使用 `menu subapp-assets-update`；只有明确维护菜单自身的兜底配置时才使用本命令。
+
+> **风险等级：write** — 修改菜单自身的资源配置；建议先 dry-run，正式执行复用相同参数并移除 `--dry-run`。
 
 ## 命令
 
@@ -17,13 +19,13 @@ rabetbase menu asset-update --paths "<menu-path>" --params '{"cssUrl":"https://.
 # 按菜单 ID 精确更新，并显式切换加载方式
 rabetbase menu asset-update --menu-ids "<menu-id>" --load-mode fetch --params '{"jsUrl":"https://...js"}' --dry-run --format compress
 
-# 明确需要全量发布时显式选择全部
+# 仅当明确要更新当前宿主所有已有 resources 的菜单时使用，不用于子应用版本升级
 rabetbase menu asset-update --all --params '{"jsUrl":"https://...js","cssUrl":"https://...css"}' --dry-run --format compress
 ```
 
 ## 高频 SOP：修改菜单资源 URL
 
-修改菜单中的 JS / CSS 资源 URL 是 `menu asset-update` 的主路径，不需要 `menu detail` 或其他配置更新命令。
+修改菜单自己的 JS / CSS 资源 URL 使用 `menu asset-update`：包括平台页面的正常资源配置，以及明确维护的子应用菜单兜底配置。不需要 `menu detail` 或其他配置更新命令。
 
 1. **先确认资源现状**，只看已配置资源的菜单：
 
@@ -73,7 +75,7 @@ rabetbase menu asset-update --paths "<menu-path>" --params '{"cssUrl":"https://c
 rabetbase menu asset-update --menu-ids "<menu-id>" --params '{"jsUrl":"https://cdn.example.com/app.js"}' --dry-run --format compress
 rabetbase menu asset-update --menu-ids "<menu-id>" --params '{"jsUrl":"https://cdn.example.com/app.js"}' --format compress
 
-# 显式更新全部菜单的 JS + CSS
+# 显式更新当前宿主全部已有 resources 的菜单，不限定为某个子应用
 rabetbase menu asset-update --all --params '{"jsUrl":"https://cdn.example.com/app.js","cssUrl":"https://cdn.example.com/app.css"}' --dry-run --format compress
 rabetbase menu asset-update --all --params '{"jsUrl":"https://cdn.example.com/app.js","cssUrl":"https://cdn.example.com/app.css"}' --format compress
 ```
@@ -113,7 +115,7 @@ rabetbase menu asset-update --all --params '{"jsUrl":"https://cdn.example.com/ap
 - 只有显式传 `--load-mode` 才修改加载方式
 - 默认 `patch`；使用 `replace` 时仍会阻止无意删除已有 JS
 - patch 被更新类型已有多个资源时会拒绝，不通过 `--force` 猜测替换目标
-- 典型场景：新版本构建后批量更新 CDN 地址
+- 典型场景：更新选定平台页面的 CDN 地址，或明确维护菜单兜底 URL；前端子应用升级优先更新共享资源
 - 交互模式会展示受影响菜单的摘要表
 
 ## 常见错误
@@ -124,7 +126,7 @@ rabetbase menu asset-update --all --params '{"jsUrl":"https://cdn.example.com/ap
 - 只想换 CSS 却显式使用 `replace`，导致已有 JS 被删除风险。
 - dry-run 已出现删除 JS warning，仍未取得用户明确确认就继续执行。
 - patch 报告同类型资源不唯一时尝试用 `--force` 绕过；应先确认完整资源集合，只有明确重写时才改用 `replace`。
-- 把资源 URL 修改误判为需要 `menu detail` / `config-update`；资源 URL 变更统一使用 `menu asset-update`。
+- 修改菜单自己的资源 URL 时误用 `menu detail` / `config-update`；此类变更使用 `menu asset-update`。同名子应用共享资源版本另行管理。
 
 ## 参考
 

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

@@ -119,7 +119,7 @@ rabetbase menu list --verbose --format json
 - 修改菜单名称前确认 `id/label`；所有菜单类型统一使用 `menu rename`。
 - 显示或隐藏菜单前确认 `id/path/visible`；批量写入统一使用 `menu visibility-update`。
 - 修改 iframe/link 页面 URL 前确认 `id/url/parentId`；写入入口使用 `menu external-link-update`。
-- 修改微前端 JS/CSS 资源前确认当前 resources；写入入口使用 `menu asset-update`。
+- 前端子应用优先用 `menu subapp-assets-status` 核查共享资源，升级使用 `menu subapp-assets-update`；平台页面或明确维护的菜单兜底资源使用 `menu asset-update`。
 - 提供稳定的菜单事实入口，避免使用底层数据源查询菜单配置。
 
 ## 不负责
@@ -127,7 +127,7 @@ rabetbase menu list --verbose --format json
 - 不做本地 `src/pages` 与线上菜单 diff；这类对比使用 `menu sync`。
 - 不做数据列表页菜单审计；dataset-scoped 页面事实使用 `page data-list-status`。
 - 不修改外链 URL；使用 `menu external-link-update`，并带旧 URL 与父级断言。
-- 不修改菜单资源；更新 JS / CSS 资源 URL 使用 `menu asset-update`，并先执行 dry-run。
+- 不修改资源；共享子应用与独立菜单资源分别使用对应更新命令，并先执行 dry-run。
 - 不修改菜单；显示隐藏使用 `menu visibility-update`，改名使用 `menu rename`，空 folder 删除使用计划化的 `menu delete`，分组生命周期使用 `group-create/group-update/regroup-start`，写操作都必须先 dry-run。
 
 ## 参考

package/skills/rabetbase/references/rabetbase-menu-subapp-assets-status.md

@@ -0,0 +1,19 @@
+# menu subapp-assets-status
+
+只读核查指定菜单宿主中一个前端子应用的共享资源、关联菜单及回退资源。
+
+查询需要目标宿主应用的应用开发者或应用管理员权限；更新共享资源需要该应用的应用管理员权限。系统管理员、所属租户管理员沿用平台现有权限规则。“宿主”只表示目标应用，不是独立权限角色；其他业务应用的权限不能替代目标宿主应用的权限。
+
+```bash
+rabetbase menu subapp-assets-status --app-name store-app --format json
+```
+
+`--app-name` 必填，去除首尾空白后精确匹配宿主 `extend.assets[].appName` 和菜单 `extend.appName`。CLI 不从包名、目录名或应用 profile 自动推导该值；标识来源与冲突处理见[宿主前端集成指南](../guides/host-frontend-integration.md)。菜单宿主沿用 CLI 的应用选择：可用 `--appcode` / `--app` 指定，否则使用工作区默认应用或唯一应用；多应用未选定目标时提示选择。`defaultApp` 是默认应用上下文，在本命令中作为菜单宿主。前端子应用访问哪些业务 appCode 是独立关系，不根据业务应用列表遍历或批量操作。默认应用与目标宿主不同时，用参数覆盖。
+
+输出 `data.appCode` 是本次查询的菜单宿主，`data.appName` 是输入标识去除首尾空白后的回显，即使未匹配到配置也会返回。`sharedConfigured` 表示同名共享配置条目是否存在，`boundMenus` 表示关联菜单数量；条目存在不代表资源非空。`sharedResources` 返回该子应用共享资源；`menus[].menuFallbackResources` 返回每个关联菜单自己的资源。菜单回退资源格式异常时，该值及 `fallbackDiffers` 为 `null`，`menuFallbackError` 返回原因，不阻断有效共享资源的核查；无共享资源可用时，该菜单的 `preferredResourcesIfSupported` 也为 `null`，应报告无法判断，不能当成版本一致或空资源。
+
+检测资源版本时，先读取子应用共享资源；共享资源非空时优先使用，否则逐菜单使用回退资源。按 `menus[].preferredSourceIfSupported` 和 `preferredResourcesIfSupported` 与目标资源 URL 比较。`staleMenuFallbacks` 只表示菜单回退配置与共享资源有差异，不代表当前优先资源版本不一致。没有关联菜单时仍可核查 `sharedResources`，但不能据此声称页面已挂载。
+
+比较本地发布版本时，先按[资源版本核验](../guides/host-frontend-integration.md#子应用资源版本核验)取得可信发布记录或构建上传结果中的完整资源 URL 列表；不能仅凭 `package.json.version` 判断发布一致。缺少资源对应关系时报告无法判断，并展示已查到的配置。URL 列表相同只表示配置一致。
+
+`hostCapabilityVerified=false` 表示未验证目标宿主的加载能力；优先级字段描述支持共享资源的宿主。不同宿主版本可能只支持菜单资源，发布前需核实目标宿主的加载行为。本命令不校验 CDN 文件内容，不更新配置；URL 一致不能代替发布验证。