@lovrabet/rabetbase-cli 2.3.16-beta.7 → 2.4.1

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

@@ -0,0 +1,135 @@
+# menu asset-update
+
+更新指定线上微前端菜单的 CDN 资源 URL。
+
+> **风险等级：high-risk-write** — 修改线上菜单运行资源；非交互正式执行必须显式 `--yes`。
+
+## 命令
+
+```bash
+# 交互模式（TTY）
+rabetbase menu asset-update
+
+# 使用 menu list 返回的真实 path 精确预览并更新
+rabetbase menu asset-update --paths "<menu-path>" --params '{"cssUrl":"https://...css"}' --dry-run --format compress
+rabetbase menu asset-update --paths "<menu-path>" --params '{"cssUrl":"https://...css"}' --yes --format compress
+
+# 按菜单 ID 精确更新，并显式切换加载方式
+rabetbase menu asset-update --menu-ids "<menu-id>" --load-mode fetch --params '{"jsUrl":"https://...js"}' --dry-run --format compress
+
+# 明确需要全量发布时显式选择全部
+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` 或其他配置更新命令。
+
+1. **先确认资源现状**，只看已配置资源的菜单：
+
+```bash
+rabetbase menu list --format json --jq '.data.menus[] | select(.resources | length > 0)'
+```
+
+2. **精确选择目标**：
+
+- 优先从 `menu list` 取得稳定 `id` 或 `path`，使用 `--menu-ids` / `--paths`。
+- 只有明确要更新所有已有 resources 的菜单时才使用 `--all`。
+- `--all` 不能与 ID/path 组合；未知 ID/path 会失败，不会静默扩大更新范围。
+
+3. **选择更新模式**：
+
+- 默认 `--mode patch`，只替换传入类型并保留其他资源。
+- 被更新类型已有多个资源时，单个 `jsUrl` / `cssUrl` 无法确定替换目标，patch 会拒绝；`--force` 不绕过该歧义。
+- 同时换 JS + CSS：仍可用 `--mode patch`；只有确实要把菜单 resources 改成传入 URL 的完整集合时，才用 `replace`。
+- 不要用裸 `replace` 做“只换 CSS”，否则可能删除已有 JS；出现 JS 删除 warning 时，除非用户明确要求，否则停止。
+
+4. **必须先 dry-run**，检查 `diffs[]` 的 `before.resources`、`after.resources` 和 `warnings`；显式传 `--load-mode` 时还要核对 before/after `loadScriptMode`：
+
+```bash
+rabetbase menu asset-update --paths "<menu-path>" --params '{"cssUrl":"https://...css"}' --dry-run --format compress
+```
+
+5. **正式执行必须复用 dry-run 的同一组 selector、`--mode` 和 `--params`**：
+
+```bash
+rabetbase menu asset-update --paths "<menu-path>" --params '{"cssUrl":"https://...css"}' --yes --format compress
+```
+
+6. **执行后回查资源现状**：
+
+```bash
+rabetbase menu list --format json --jq '.data.menus[] | select(.resources | length > 0)'
+```
+
+### 常用模板
+
+```bash
+# 只替换 CSS，保留已有 JS
+rabetbase menu asset-update --paths "<menu-path>" --params '{"cssUrl":"https://cdn.example.com/app.css"}' --dry-run --format compress
+rabetbase menu asset-update --paths "<menu-path>" --params '{"cssUrl":"https://cdn.example.com/app.css"}' --yes --format compress
+
+# 只替换 JS，保留已有 CSS
+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"}' --yes --format compress
+
+# 显式更新全部菜单的 JS + CSS
+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"}' --yes --format compress
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--params <json>` | string | 非交互必填 | — | 预填 JS/CSS URL。JSON 格式：`{"jsUrl":"...","cssUrl":"..."}`；至少包含 `jsUrl` 或 `cssUrl` |
+| `--menu-ids <csv>` | string | 至少一个 selector | — | 精确菜单 ID；只接受正安全整数；可与 paths 组合，不可与 all 组合 |
+| `--paths <csv>` | string | 至少一个 selector | — | 精确菜单 path；可与 menu-ids 组合，不可与 all 组合 |
+| `--all` | boolean | 至少一个 selector | `false` | 显式选择所有已有 resources 的菜单；不可与 ID/path 组合 |
+| `--yes` | boolean | 正式执行必填 | — | 跳过高风险确认并更新已选择菜单，必须配合有效 `--params` |
+| `--mode <mode>` | string | 否 | `patch` | `patch` 只在目标唯一时替换传入的同类型资源并保留其他资源；`replace` 将传入 URL 作为完整 `resources` |
+| `--load-mode <mode>` | string | 否 | 保留线上值 | 显式修改为 `import`、`script` 或 `fetch` |
+| `--force` | boolean | 否 | `false` | 允许 `replace` 删除已有 JS 资源；仅用于明确的资源降级/迁移 |
+| `--dry-run` | boolean | 否 | `false` | 输出每个菜单的 before/after resources；显式修改加载方式时同时输出 loadScriptMode diff，不写入 |
+| `--format <fmt>` | string | 否 | `compress` | 输出格式 |
+
+## 执行模式
+
+1. **selector + `--params` + `--dry-run`** — 非交互预览精确目标；全量必须显式 `--all`
+2. **selector + `--params` + `--yes`** — 正式更新精确目标；必须复用 dry-run 参数
+3. **TTY 交互式** — 未给 selector 时展示全部有资源菜单并二次确认；给 selector 时只展示目标
+
+## 输出
+
+- 成功：`✓ Menu asset update completed: N menu(s) updated`
+- 无目标：`! No menus with existing resources found`
+- 部分失败：`! N menu(s) failed`
+- `--dry-run`：返回 `diffs[]`，包含 `id / label / path / before.resources / after.resources / warnings`；显式传 `--load-mode` 时还包含 before/after `loadScriptMode`
+
+## 提示
+
+- 仅更新已配置了资源 URL 且被 selector 命中的菜单
+- 非交互和 dry-run 缺 selector 会被拒绝；`--yes` 不能裸跑；空 `--params` 也会被拒绝
+- 写入采用 read-modify-write：默认只更新 `extend.resources`，保留 `loadScriptMode` 和其他扩展字段
+- 只有显式传 `--load-mode` 才修改加载方式
+- 默认 `patch`；使用 `replace` 时仍会阻止无意删除已有 JS
+- patch 被更新类型已有多个资源时会拒绝，不通过 `--force` 猜测替换目标
+- 典型场景：新版本构建后批量更新 CDN 地址
+- 交互模式会展示受影响菜单的摘要表
+
+## 常见错误
+
+- 跳过 `--dry-run` 直接写入。
+- `--yes` 裸跑、缺 selector 或传空 `--params`。
+- 需要单菜单更新却使用 `--all`。
+- 只想换 CSS 却显式使用 `replace`，导致已有 JS 被删除风险。
+- dry-run 已出现删除 JS warning，仍未取得用户明确确认就继续执行。
+- patch 报告同类型资源不唯一时尝试用 `--force` 绕过；应先确认完整资源集合，只有明确重写时才改用 `replace`。
+- 把资源 URL 修改误判为需要 `menu detail` / `config-update`；资源 URL 变更统一使用 `menu asset-update`。
+
+## 参考
+
+- [SKILL.md](../SKILL.md)
+- [menu list](rabetbase-menu-list.md)
+- [menu external-link-update](rabetbase-menu-external-link-update.md)
+- [menu sync](rabetbase-menu-sync.md)

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

@@ -0,0 +1,54 @@
+# menu delete
+
+按线上菜单 ID 精确删除空 folder、非 folder 叶子菜单，或一个 folder 子树。
+
+> **风险等级：high-risk-write** — 必须先生成删除计划，正式执行必须消费该计划并显式 `--yes`。
+
+## 命令
+
+```bash
+rabetbase menu delete --id "<folder-id>" --expected-children-count 0 --dry-run --plan-out ./menu-delete.plan.json --format compress
+rabetbase menu delete --plan ./menu-delete.plan.json --yes --format compress
+
+rabetbase menu delete --id "<folder-id>" --recursive --dry-run --plan-out ./menu-tree-delete.plan.json --format compress
+rabetbase menu delete --plan ./menu-tree-delete.plan.json --yes --format compress
+```
+
+## Flags
+
+| Flag | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `--id <id>` | number | 计划阶段 | 精确菜单 ID；不接受 label/path 定位 |
+| `--recursive` | boolean | 否 | 计划阶段包含精确 folder ID 下的全部后代，叶子优先 |
+| `--expect-parent-id <id\|root>` | string | 否 | 计划阶段断言当前父级 |
+| `--expect-path <path>` | string | 否 | 计划阶段断言当前 path |
+| `--expected-children-count <n>` | number | 否 | 计划阶段断言直接子节点数量，删除 folder 时推荐为 `0` |
+| `--plan-out <file>` | string | 计划阶段 | 保存可审阅的删除计划 |
+| `--dry-run` | boolean | 计划阶段 | 返回目标快照和影响计划，不写入 |
+| `--plan <file>` | string | 正式执行 | 读取 30 分钟内生成的删除计划 |
+| `--yes` | boolean | 正式执行 | 显式授权删除 |
+
+## 安全规则
+
+- 单目标必须是 `resources=[]` 的空 folder，或任意非 folder 叶子菜单；无 `pageId` 的 link/iframe 等叶子不会产生页面级联。
+- 非空目标必须是 folder，并显式传 `--recursive`；计划必须覆盖完整子树且保持叶子优先、根目录最后。
+- folder 的 resources 必须为空；非 folder 叶子可以保留其资源配置，具有 `pageId` 时页面与 PageSchema 删除由平台现有删除语义处理。
+- 任一计划内 pageId 被计划外菜单引用时返回 `menu_page_shared`，避免平台页面级联影响计划外菜单。
+- expect 条件不一致时返回 `menu_state_drift`，不写入。
+- dry-run 必须同时提供 `--id` 和 `--plan-out`；正式执行以 `--plan` 为唯一目标来源，不再接受 ID、`--recursive` 或 expect 条件。
+- 计划创建后 30 分钟过期，并绑定 `appCode`、`snapshotHash`、完整目标集合和删除顺序；时间字段异常、计划不完整、顺序被修改或任一事实漂移时拒绝写入。
+- dry-run 的 `cascade.pages` 只列出菜单直接绑定的 pageId；平台可能按既有规则继续处理关联 Page/PageSchema，不要把该列表解释为服务端全部级联影响。
+- dry-run 的 `plannedActions` 必须只有一个批量删除动作，`body.idList` 与叶子优先的 `deleteOrder` 完全一致。
+- 正式执行只消费计划一次；批量请求不提供整体事务，错误时可能已有部分 ID 被删除。
+- 请求错误或返回计数与计划数量不一致时不自动重试；结构化结果通过 `absentIds` 和 `remainingIds` 表达回读事实。
+- 成功计数匹配后仍要重新读取 menu list；只有所有计划 ID 均已消失时才报告成功。
+- 出现部分结果或状态未知时，先读取最新菜单事实并生成新计划，禁止再次消费原计划。
+
+## 输出
+
+dry-run 的 `data` 包含 `operation / selector / before / targets / deleteOrder / plannedActions / cascade / snapshotHash / warnings`，计划文件同时记录 `appCode`、有效期、完整目标事实和指纹。`plannedActions` 中的单个批量请求以 `idList` 携带完整 `deleteOrder`。正式执行返回批量确认与写后回查结果；计划过期、快照漂移、计划缺项、计数不一致或其他 blocker 均以结构化失败返回，不会按当前事实重新规划。
+
+## 相关命令
+
+- [menu list](rabetbase-menu-list.md)
+- [菜单异常治理](../guides/menu-anomaly-manual-cleanup.md)

package/skills/rabetbase/references/rabetbase-menu-external-link-create.md

@@ -0,0 +1,63 @@
+# menu external-link-create
+
+创建一个外部网站链接菜单。使用产品打开方式选择应用内嵌入或新窗口打开，不要求使用者理解服务端菜单类型。
+
+> **风险等级：write** — 创建一个新入口，不覆盖既有菜单；建议先 dry-run，正式执行不要求显式 `--yes`。
+
+## 命令
+
+```bash
+rabetbase menu external-link-create \
+  --label "帮助中心" \
+  --url "https://help.example.com" \
+  --open-mode new-window \
+  --dry-run \
+  --format compress
+
+rabetbase menu external-link-create \
+  --label "帮助中心" \
+  --url "https://help.example.com" \
+  --open-mode new-window \
+  --format compress
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--label <label>` | string | 是 | — | 菜单名称 |
+| `--open-mode <embedded\|new-window>` | string | 是 | — | `embedded` 应用内嵌入；`new-window` 新窗口打开 |
+| `--url <https-url>` | string | 是 | — | 无内嵌用户名密码的绝对 HTTPS URL |
+| `--parent-id <id\|root>` | string | 否 | `root` | 父节点必须是当前 App 中已有的 folder |
+| `--sort <n>` | number | 否 | 同级末尾 | `0..2147483647` 的整数 |
+| `--visible` | boolean | 否 | `true` | 是否显示菜单；隐藏菜单传 `--visible=false` |
+| `--appcode <code>` | string | 否 | 配置解析 | 显式指定 App Code |
+| `--dry-run` | boolean | 否 | `false` | 输出创建计划，不写入 |
+
+## 安全与输出
+
+- `embedded` 映射为服务端 `type=iframe`；`new-window` 映射为服务端 `type=link`。HTML `_self` 表示在当前浏览上下文导航，不等同于应用内嵌入，因此不是本命令参数。
+- URL 必须使用 HTTPS，且不能包含 URL userinfo。
+- URL 查询参数属于菜单配置，不按参数名拦截或脱敏。
+- URL 是可审计的菜单事实，dry-run、成功、结构化失败结果和 `menu list` 均按输入或线上值原样输出。
+- 依赖原始异常等不可信错误文本仍会清洗，错误码只使用稳定白名单。
+- 创建请求不发送 `path`，平台负责生成非空 path。
+- 正式写入前重新读取菜单快照；任一菜单事实漂移都会阻断本次写入。
+
+## 响应丢失
+
+创建请求不自动重试。响应丢失后，只有同时满足以下条件才返回恢复成功：
+
+1. 回查到唯一匹配的菜单；
+2. 该 ID 在写入前快照中不存在；
+3. ID 是正安全整数；
+4. parent、type、label、URL、visible、sort 和非空 path 全部一致。
+
+无法唯一确认时，执行错误中返回的 `verification.lookupCommand`，核对线上事实后再决定下一步，不要直接重提创建。
+
+## 参考
+
+- [menu list](rabetbase-menu-list.md)
+- [menu external-link-update](rabetbase-menu-external-link-update.md)
+- [menu group-create](rabetbase-menu-group-create.md)
+- [SKILL.md](../SKILL.md)

package/skills/rabetbase/references/rabetbase-menu-external-link-update.md

@@ -0,0 +1,74 @@
+# menu external-link-update
+
+按精确 ID 原地更新一个既有 `iframe` 或 `link` 叶子菜单的 URL。只修改 URL，不删除重建菜单。
+
+> **风险等级：high-risk-write** — 会改变线上菜单实际打开地址；必须先 dry-run，正式执行显式传 `--yes`。
+
+## 命令
+
+```bash
+rabetbase menu external-link-update \
+  --id "<menu-id>" \
+  --url "https://admin.example.com/new-page?hideShell=true" \
+  --expect-url "https://admin.example.com/old-page?hideShell=true" \
+  --expect-parent-id "<folder-id|root>" \
+  --dry-run \
+  --format compress
+
+rabetbase menu external-link-update \
+  --id "<menu-id>" \
+  --url "https://admin.example.com/new-page?hideShell=true" \
+  --expect-url "https://admin.example.com/old-page?hideShell=true" \
+  --expect-parent-id "<folder-id|root>" \
+  --yes \
+  --format compress
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--id <id>` | number | 是 | — | 既有菜单的精确正整数 ID |
+| `--url <https-url>` | string | 是 | — | 新的绝对 HTTPS URL，不允许 URL userinfo |
+| `--expect-url <current-url>` | string | 是 | — | 真正需要写入时精确断言当前 URL；允许断言历史非 HTTPS 地址 |
+| `--expect-parent-id <id\|root>` | string | 是 | — | 始终断言当前父级 |
+| `--appcode <code>` | string | 否 | 配置解析 | 显式指定 App Code |
+| `--dry-run` | boolean | 否 | `false` | 输出精确 URL patch，不写入 |
+| `--yes` | boolean | 正式执行必填 | — | 明确确认高风险写入 |
+
+## 目标边界
+
+- 目标类型只能是 `iframe` 或 `link`。
+- 目标必须没有子菜单，且平台 path 非空。
+- 命令一次只处理一个 ID，不支持 label/path 模糊定位或批量 URL patch。
+- 服务端请求体严格为 `{ id, appCode, url }`，不发送 label、type、path、parentId、sort、visible、extend 或权限字段。
+
+## 并发与幂等
+
+1. `--expect-parent-id` 始终校验，包括 no-op。
+2. 当当前 URL 不等于目标 URL、真正需要写入时，当前 URL 必须匹配 `--expect-url`。
+3. 当当前 URL 已等于目标 URL 时，返回成功 no-op；此时允许 `--expect-url` 仍是旧 URL。
+4. 写入前重新读取完整菜单快照；任一菜单事实漂移都会阻断写入。
+5. 写后回读并确认 URL 已生效，同时 ID、label、type、path、parentId、sort、visible 保持不变。
+
+## 响应丢失
+
+更新请求永不自动重试。发生超时、连接重置等响应丢失时：
+
+- 回读确认目标 URL 和全部不变量后，返回成功并标记 `recovered=true`。
+- 回读仍是旧 URL、目标缺失或回读失败时，返回 `menu_update_recovery_required`，并提供 `verification.lookupCommand`。
+- 回读发现目标 URL 已生效但其他菜单字段改变时，返回验证失败，要求人工核对。
+
+## 常见错误
+
+- 用 `menu asset-update` 修改 iframe URL；该命令只管理微前端 JS/CSS resources。
+- 用 `external-link-create` 新建后删除旧菜单；这会改变 ID、path 及其权限关联。
+- response loss 后直接重发写请求；应先执行错误中的 lookup 命令。
+- 省略 `--expect-url` 或 `--expect-parent-id`，失去并发保护。
+
+## 参考
+
+- [menu list](rabetbase-menu-list.md)
+- [menu external-link-create](rabetbase-menu-external-link-create.md)
+- [menu asset-update](rabetbase-menu-asset-update.md)
+- [SKILL.md](../SKILL.md)

package/skills/rabetbase/references/rabetbase-menu-group-create.md

@@ -0,0 +1,33 @@
+# menu group-create
+
+创建一个空菜单分组。group 是命令领域名称，线上持久化类型为 `folder`。
+
+## 命令
+
+```bash
+rabetbase menu group-create --label "用户管理" --parent-id "<parent-folder-id>" --sort 10 --dry-run --format compress
+rabetbase menu group-create --label "用户管理" --parent-id "<parent-folder-id>" --sort 10 --format compress
+```
+
+## Flags
+
+| Flag | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `--label <label>` | string | 是 | folder 名称 |
+| `--parent-id <id\|root>` | string | 否 | 父 folder；默认 root |
+| `--sort <n>` | number | 否 | 非负整数；默认目标父级同级末尾 |
+| `--dry-run` | boolean | 预览时 | 返回创建计划，不写入 |
+
+## 事实约束
+
+- 指定父级时，父级必须存在且 `type=folder`。
+- 创建结果必须为 `type=folder`，并保留平台生成的非空 `path`。
+- `resources` 必须为空且 `childrenCount=0`；命令通过 `menu list` 回查这些最终事实。
+- dry-run 只展示一次 folder 创建请求。
+- 创建请求成功但后续回查失败时，错误输出会返回已创建的菜单 ID 和 path。该分组可能仍在线上；先用 `menu list` 按 ID 核对，不要直接重试创建。
+
+## 相关命令
+
+- [menu group-update](rabetbase-menu-group-update.md)
+- [menu regroup-start](rabetbase-menu-regroup-start.md)
+- [menu list](rabetbase-menu-list.md)

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

@@ -0,0 +1,38 @@
+# menu group-update
+
+按 ID 修改现有 folder 的名称或 sort，不调整父级。修改任意菜单类型的名称时使用 `menu rename`。
+
+## 命令
+
+```bash
+rabetbase menu group-update --id "<folder-id>" --label "客户管理" --sort 20 --dry-run --format compress
+rabetbase menu group-update --id "<folder-id>" --label "客户管理" --sort 20 --format compress
+```
+
+至少提供 `--label`、`--sort` 之一。
+
+## Flags
+
+| Flag | 类型 | 说明 |
+|---|---|---|
+| `--id <id>` | number | 精确 folder ID |
+| `--label <label>` | string | 新名称，不能是空字符串 |
+| `--sort <n>` | number | 新 sort，非负整数 |
+| `--expect-parent-id <id\|root>` | string | 断言当前父级 |
+| `--expect-path <path>` | string | 断言当前 path |
+| `--expected-children-count <n>` | number | 断言直接子节点数 |
+| `--dry-run` | boolean | 输出 before/after，不写入 |
+
+## 安全规则
+
+- 目标必须为 `type=folder`。
+- 命令只修改 label 和 sort，不修改 parentId 或 path。
+- expect 条件漂移时不写入。
+- 写入后自动 menu list 回查 label 和 sort。
+
+## 相关命令
+
+- [menu rename](rabetbase-menu-rename.md)
+- [menu group-create](rabetbase-menu-group-create.md)
+- [menu regroup-start](rabetbase-menu-regroup-start.md)
+- [menu list](rabetbase-menu-list.md)

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

@@ -0,0 +1,144 @@
+# menu list
+
+查询当前 App 的线上菜单事实。
+
+> **风险等级：read** — 只读查询，不修改平台菜单配置。
+
+## 命令
+
+```bash
+# AI / 脚本优先
+rabetbase menu list --format compress
+
+# 人类阅读
+rabetbase menu list --format json
+
+# 按 path 片段过滤（替换占位符）
+rabetbase menu list --format json --jq '.data.menus[] | select(.path | contains("<path-fragment>"))'
+
+# 按 label 片段过滤（替换占位符）
+rabetbase menu list --format json --jq '.data.menus[] | select(.label | contains("<label-fragment>"))'
+
+# 仅查看配置了资源 URL 的菜单
+rabetbase menu list --format json --jq '.data.menus[] | select(.resources | length > 0)'
+
+# 查看最近更新人和更新时间
+rabetbase menu list --format compress --jq '.data.menus[] | {id, label, path, updateUserId, updateUserName, updateTime}'
+
+# 排查 extend.resources 原始形态
+rabetbase menu list --verbose --format json
+```
+
+如需找出重复 path、根级重名等异常菜单并生成平台手动删除清单，先按 [`menu-anomaly-manual-cleanup`](../guides/menu-anomaly-manual-cleanup.md) 执行。清单中的 `<appBaseUrl>` 由当前 `rabetbase` 环境解析：production 为 `https://app.lovrabet.com/app/<appCode>`，daily 为 `https://daily.lovrabet.com/web-app/app/<appCode>`。
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--appcode <code>` | string | 否 | 配置解析 | 显式指定 App Code，覆盖配置文件 |
+| `--verbose` | boolean | 否 | `false` | 每个菜单项额外返回 `extend` 排障字段 |
+| `--format <fmt>` | string | 否 | `compress` | 输出格式 |
+| `--jq <expr>` | string | 否 | — | 对最终 JSON 信封执行 jq；仅配合 `json` / `compress` |
+
+`menu list` 不提供 `--path` / `--label` / `--resources-only` 等领域筛选 flag。需要过滤时使用 `--jq`。
+
+## 输出
+
+`json` / `compress` 信封的 `data` 包含全量 `snapshotHash`：
+
+```json
+{
+  "total": 1,
+  "snapshotHash": "sha256:<hex>",
+  "menus": [
+    {
+      "id": 21,
+      "parentId": null,
+      "depth": 0,
+      "label": "Example Menu",
+      "path": "/example-page",
+      "url": "https://example.com/example-page?hideShell=true",
+      "type": "procode",
+      "visible": true,
+      "sort": 0,
+      "childrenIds": [],
+      "childrenCount": 0,
+      "pageId": null,
+      "pageType": "",
+      "resources": [
+        "https://cdn.example.com/app.js"
+      ],
+      "updateUserId": "user-1",
+      "updateUserName": "张三",
+      "updateTime": "2026-08-02T12:00:00Z"
+    }
+  ]
+}
+```
+
+默认菜单项只返回稳定字段：
+
+- `id`
+- `parentId`
+- `depth`
+- `label`
+- `path`
+- `url`
+- `type`
+- `visible`
+- `sort`
+- `resources`
+- `childrenIds`
+- `childrenCount`
+- `pageId`
+- `pageType`
+- `updateUserId`
+- `updateUserName`
+- `updateTime`
+
+`--verbose` 只额外返回 `extend`，不返回服务端原始 `raw`。
+
+## 字段约定
+
+- `menus[]` 顺序是 DFS 前序：父节点在前，子节点紧随其后，兄弟节点按 `sort` 升序。
+- 字符串字段缺失时返回空字符串。
+- 布尔 / 数值字段缺失时返回 `null`。
+- 最近更新人和更新时间直接取线上菜单事实；字段缺失时返回 `null`，不回退为创建人或本地 Git 用户。
+- folder 的 `path` 可能由平台生成；`menu list` 按线上事实原样返回。
+- `url` 是可审计的菜单事实，按线上值原样返回，并参与快照哈希和写后核验。
+- `extend.resources` 会被归一化为 `resources: string[]`。
+- `extend.resources` 为 JSON 字符串、数组、异常字符串或缺失值时，命令都不会因为资源字段解析失败而失败。
+
+## 适用场景
+
+- 查询当前 App 已有哪些线上菜单。
+- 确认菜单路径、层级和可见状态。
+- 查看菜单最近更新人和更新时间，辅助确认菜单整理的协作对象。
+- 查看菜单是否已配置 CDN 资源 URL。
+- 审计重复 path、根级 label 重复、孤儿父节点等菜单异常，并生成平台人工处理清单。
+- 修改菜单名称前确认 `id/label`；所有菜单类型统一使用 `menu rename`。
+- 修改 iframe/link 页面 URL 前确认 `id/url/parentId`；写入入口使用 `menu external-link-update`。
+- 修改微前端 JS/CSS 资源前确认当前 resources；写入入口使用 `menu asset-update`。
+- 提供稳定的菜单事实入口，避免使用底层数据源查询菜单配置。
+
+## 不负责
+
+- 不做本地 `src/pages` 与线上菜单 diff；这类对比使用 `menu sync`。
+- 不做智能列表页菜单审计；dataset-scoped 页面事实使用 `page standard-page-status`。
+- 不修改外链 URL；使用 `menu external-link-update`，并带旧 URL 与父级断言。
+- 不修改菜单资源；更新 JS / CSS 资源 URL 使用 `menu asset-update`，并先执行 dry-run。
+- 不修改菜单；改名使用 `menu rename`，空 folder 删除使用计划化的 `menu delete`，分组生命周期使用 `group-create/group-update/regroup-start`，写操作都必须先 dry-run。
+
+## 参考
+
+- [menu sync](rabetbase-menu-sync.md)
+- [menu external-link-create](rabetbase-menu-external-link-create.md)
+- [menu external-link-update](rabetbase-menu-external-link-update.md)
+- [menu rename](rabetbase-menu-rename.md)
+- [menu asset-update](rabetbase-menu-asset-update.md)
+- [menu delete](rabetbase-menu-delete.md)
+- [menu group-create](rabetbase-menu-group-create.md)
+- [menu group-update](rabetbase-menu-group-update.md)
+- [menu regroup-start](rabetbase-menu-regroup-start.md)
+- [task status](rabetbase-task-status.md)
+- [SKILL.md](../SKILL.md)

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

@@ -0,0 +1,54 @@
+# rabetbase menu move
+
+## Use when
+
+把当前 App 中一个已有的非 folder 叶子菜单移动到已有 folder 或根级，或者在当前父级内调整该叶子的 sort。
+
+## Read before writing
+
+```bash
+rabetbase menu list --format compress
+```
+
+从返回事实中读取源菜单 `id`、当前 `parentId`、`type`、`childrenCount`、`sort`，以及目标 folder 的 `id` 和 `type`。源必须是 `childrenCount=0` 的非 folder 菜单，数字形式的目标父级必须是 folder；根级使用 `root`。
+
+## Preview
+
+```bash
+rabetbase menu move --id "<menu-id>" --parent-id "<folder-id|root>" --expect-parent-id "<current-folder-id|root>" --dry-run --format compress
+```
+
+检查 `data.before.parentId`、`data.after.parentId`、`data.after.sort` 和 `data.plannedActions[].body`。跨父级且未传 `--sort` 时默认追加到目标同级末尾；同一父级未传 `--sort` 时返回 no-op。
+
+## Execute
+
+```bash
+rabetbase menu move --id "<menu-id>" --parent-id "<folder-id|root>" --expect-parent-id "<current-folder-id|root>" --format compress
+```
+
+每次只执行一个源菜单。前一项只有在 `data.verification.matchesRequestedState=true` 后才处理下一项；首个失败立即停止。
+
+## Stable result fields
+
+- `data.operation="move"`
+- `data.selector.id`、`data.selector.parentId`
+- `data.before.parentId`、`data.before.sort`
+- `data.after.parentId`、`data.after.sort`
+- `data.succeeded[].updated`、`data.succeeded[].skipped`
+- `data.verification.matchesRequestedState`
+- `data.snapshotHash` 仅用于观察和排障，不作为再次执行的输入
+
+## Failure handling
+
+- `menu_state_drift`：当前父级与 `--expect-parent-id` 不一致；重新读取菜单并重新 dry-run。
+- `menu_move_source_not_leaf`：源不是非 folder 叶子；选择正确的源 ID。
+- `menu_parent_not_folder`：数字目标不是 folder；重新读取目标事实。
+- `menu_verification_failed`：写请求可能已经生效，但最终事实未确认；先执行 `menu list`，不要直接重试写入。
+- 其他写入失败同样先读取最新菜单事实，再决定是否生成新的 dry-run。
+
+## Boundaries
+
+- 命令只修改源菜单的 `parentId` 和 `sort`，不修改 label、path、url、visible、resources 或 extend。
+- `--expect-parent-id` 是 CLI 写前检查，不是服务端原子 compare-and-set。
+- 其他菜单的名称、资源或审计字段变化不阻断当前移动。
+- 新建目录并归组继续使用 `menu regroup-start`；修改 folder 名称或 sort 使用 `menu group-update`。

package/skills/rabetbase/references/rabetbase-menu-regroup-start.md

@@ -0,0 +1,45 @@
+# menu regroup-start
+
+提交一个异步任务：新建根级 folder，并将一组精确的非 folder 叶子菜单放入其中。命令返回重新分组任务的 `taskId/status`。
+
+> **风险等级：high-risk-write** — 必须先 dry-run，正式执行必须显式 `--yes`。
+
+## 命令
+
+```bash
+rabetbase menu regroup-start --label "业务管理" --menu-ids "<menu-id-1>,<menu-id-2>" --dry-run --format compress
+rabetbase menu regroup-start --label "业务管理" --menu-ids "<menu-id-1>,<menu-id-2>" --yes --format compress
+rabetbase task status --task-id "<task-id>" --format compress
+```
+
+## Flags
+
+| Flag | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `--label <label>` | string | 是 | 新建根 folder 名称；不能与现有根 folder 同名 |
+| `--menu-ids <ids>` | string | 是 | 逗号分隔的精确叶子菜单 ID，最多 100 个 |
+| `--dry-run` | boolean | 预览时 | 返回当前快照、before/after 和请求体，不写入 |
+| `--yes` | boolean | 正式执行时 | 显式授权重新分组 |
+
+## 状态流
+
+1. 命令校验精确 ID、叶子类型、重复 ID、根 folder 同名冲突和快照漂移。
+2. 服务端接受请求并返回异步重新分组任务。
+3. 命令收到有效 `taskId` 即视为提交成功；随后尝试回读 `menu list`。分组暂不可见或回读失败时返回 `groupingApplied="unconfirmed"`，不将任务误判为失败。
+4. `PENDING / PROCESSING` 继续查询同一 taskId；`SUCCESS / FAILED` 是终态。
+
+> **Agent 完成口径：** 有效 `taskId + PENDING/PROCESSING` 表示任务提交成功，但不表示重新分组完成。必须执行返回的 `data.query.command`，查询同一个 taskId 到 `SUCCESS / FAILED`。保留初始响应的 `data.verification.lookupCommand`；无论初始响应已是 `SUCCESS`，还是后续查询到 `SUCCESS`，都必须执行该只读命令并确认最终菜单事实。回读仍未确认时只重试只读查询，不得重提 `regroup-start`。
+
+## 安全规则
+
+- 请求非幂等：每次被接受都会新建一个根 folder。
+- 提交失败、超时或任务长期非终态时不自动重提；有 taskId 时只查询原任务，没有 taskId 时先用 `menu list` 检查是否已经分组。
+- 只允许非 folder 叶子菜单；既有 folder 层级调整仍由平台处理。
+- 命令不暴露通用 `menuGroups` JSON 透传，每次只编排一个新分组。
+
+## 相关命令
+
+- [task status](rabetbase-task-status.md)
+- [menu list](rabetbase-menu-list.md)
+- [menu group-create](rabetbase-menu-group-create.md)
+- [menu group-update](rabetbase-menu-group-update.md)