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

package/skills/rabetbase/references/rabetbase-page-restore.md

@@ -0,0 +1,45 @@
+# page restore
+
+恢复当前应用下一条已删除的 STANDARD 或 JSX 页面。
+
+## 命令
+
+```bash
+rabetbase page restore --id 1023895 --dry-run --format json
+rabetbase page restore --id 1023895 --format json
+rabetbase page restore --id 1450 --page-type JSX --format json
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--id <pageId>` | number | 是 | — | 已删除页面 ID，必须为正整数 |
+| `--page-type <type>` | string | 否 | — | `STANDARD` 或 `JSX`；用于缩小查询范围或消除跨类型同 ID 歧义 |
+| `--dry-run` | boolean | 否 | `false` | 定位页面并预览恢复请求，不执行恢复 |
+| `--format <fmt>` | string | 否 | `compress` | 输出格式 |
+
+## 行为说明
+
+- 未传 `--page-type` 时，CLI 查询当前应用下 STANDARD 与 JSX 两类已删除页面，并按 `--id` 唯一定位。
+- 同一个数字 ID 在两类页面中同时存在时，CLI 不猜测目标；需显式传 `--page-type STANDARD` 或 `--page-type JSX`。
+- STANDARD 页面恢复请求只携带页面 ID；JSX 页面恢复请求同时携带当前 `appCode` 和页面 ID。
+- 自动识别时任一类型查询失败都会终止恢复，避免在无法排除同 ID 歧义时写错目标。
+- JSX 恢复返回未更新记录时，按状态已变化或页面已恢复处理，不报告成功。
+
+## 输出
+
+结构化结果的稳定字段包括：
+
+- `data.operation = "page.restore"`
+- `data.appCode`
+- `data.selector.id`
+- `data.selector.pageType`
+- `data.page.id/name/pageType/type/datasetIds`
+- `data.restored`
+- `data.dryRun`
+- `data.backend.method/path`
+
+## 参考
+
+- [SKILL.md](../SKILL.md)

package/skills/rabetbase/references/rabetbase-page-sync.md

@@ -0,0 +1,36 @@
+# page sync
+
+将数据集字段变更同步到已存在的智能列表页（Smart List Page，DOV2 `smart_page`）。
+
+## 命令
+
+```bash
+rabetbase page sync --datasetcode 097b7361b76c42bcb12b923fa5a08861 --format json
+rabetbase page sync --alias order --format json
+rabetbase page sync --datasetcode 097b7361b76c42bcb12b923fa5a08861 --dry-run --format json
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--datasetcode <code>` | string | 与 `--alias` 二选一 | — | 数据集 code（32 位 hex） |
+| `--alias <name>` | string | 与 `--datasetcode` 二选一 | — | `api.ts` 中的数据集别名 |
+| `--dry-run` | boolean | 否 | `false` | 仅预览请求与前置校验，不实际同步页面 |
+| `--format <fmt>` | string | 否 | `compress` | 输出格式 |
+
+## 行为说明
+
+- 该命令面向**已有智能列表页**的增量同步场景。
+- CLI 会先检查数据集下是否存在未删除的关联智能列表页。
+- 若当前没有可同步页面，命令会 fail-fast，并提示改走 `rabetbase page generate-start --datasetcode <code>` 这条异步生成路径；具体轮询与回查流程见 [page-development-workflow.md](../guides/page-development-workflow.md)。
+
+## 提示
+
+- 这是平台侧页面编排命令，不会把页面 schema 拉到本地
+- 若要进入本地 schema 编辑工作流，使用 [`rabetbase page pull`](rabetbase-page-pull.md)
+
+## 参考
+
+- [SKILL.md](../SKILL.md)
+- [rabetbase-page-generate-start.md](rabetbase-page-generate-start.md)

package/skills/rabetbase/references/rabetbase-permit-page-set.md

@@ -0,0 +1,69 @@
+# rabetbase permit page-get / page-set
+
+按菜单配置页面权限：菜单可见、数据操作（create/update/delete/detail/export）、行级可见（`dataPermit` = DATA_ROW）。角色字面量支持 `SELF` / `ALL` / 角色 id / 角色名（解析自 `get-permit-list`，含特殊组）。`SELF`（行级）**只允许**用于 `--row-roles`。
+
+`page-set` 是 `high-risk-write`：服务端 `page/save` 回写完整 `IPagePermit`，CLI 读取完整快照后只改传入的槽位，其余原样回写；只能设置 `page-get` 中已存在的槽位。
+
+## 命令
+
+```bash
+rabetbase permit page-get --menu-id 55 --format compress
+rabetbase permit page-set --menu-id 55 --row-roles SELF --dry-run
+rabetbase permit page-set --menu-id 55 --row-roles SELF --yes
+rabetbase permit page-set --menu-id 55 --menu-roles ALL,销售组 --yes
+```
+
+## page-get
+
+返回 `data.page`：`menuId`、`appCode`，以及 `menuPermit` / `dataCreate` / `dataUpdate` / `dataDelete` / `dataDetail` / `dataExport` / `dataPermit` 各槽的 `{ resourceCode, roles[] }`（roles 为 `{id, roleName, roleType}`）。槽位缺失表示该页面无此权限维度。
+
+## page-set 参数
+
+| Flag | 槽位 | 允许 SELF |
+|------|------|-----------|
+| `--menu-roles` | menuPermit（目录可见） | 否 |
+| `--create-roles` | dataCreate | 否 |
+| `--update-roles` | dataUpdate | 否 |
+| `--delete-roles` | dataDelete | 否 |
+| `--detail-roles` | dataDetail | 否 |
+| `--export-roles` | dataExport | 否 |
+| `--row-roles` | dataPermit（行级可见） | 是（SELF = 只看自己） |
+
+每个值是逗号分隔的角色字面量。至少传一个槽位 flag。传入不存在的槽位会报错。
+
+## 用例 5（请假列表只看自己）
+
+行级 `SELF` 打在 `dataPermit`，**不要** revoke 菜单：
+
+```bash
+rabetbase menu list                              # 定位请假列表 menuId
+rabetbase permit page-get --menu-id <id> --format compress
+rabetbase permit page-set --menu-id <id> --row-roles SELF --dry-run
+rabetbase permit page-set --menu-id <id> --row-roles SELF --yes
+```
+
+## 输出协议
+
+```json
+{
+  "operation": "page-set",
+  "selector": { "appCode": "app-xxx", "menuId": 55, "slots": ["dataPermit"] },
+  "before": { "dataPermit": { "resourceCode": "ROW_1", "roles": [{ "id": -1, "roleName": "ALL", "roleType": "ALL" }] } },
+  "after": { "dataPermit": { "resourceCode": "ROW_1", "roles": [{ "id": 0, "roleName": "SELF", "roleType": "SELF" }] } },
+  "dryRun": true,
+  "backend": { "method": "POST", "path": "/smartapi/permit/page/save" },
+  "warnings": []
+}
+```
+
+不含合成 `protocol`。校验读 `data.after.<slot>.roles`。
+
+## 运行态验证交接
+
+`page-set --row-roles SELF` 只写入权限配置。要验证「登录后 filter 是否只返回自己的行」，交给 `lovrabet data filter` 在运行态执行验证。
+
+## 参考
+
+- [permit role-menus-set / role-apis-set](rabetbase-permit-role-menus-set.md)
+- [menu list](rabetbase-menu-list.md)
+- [SKILL.md](../SKILL.md)

package/skills/rabetbase/references/rabetbase-permit-role-apis-set.md

@@ -0,0 +1,53 @@
+# rabetbase permit role-apis-set
+
+按 `datasetCode` 收回角色的**数据集 API** 访问（`roleType: API`）。`high-risk-write`。一期以 `--revoke` 为主满足用例 4（销售组不能访问财务数据接口）。
+
+`datasetCode → resourceCode` 映射与当前全量 API 权限状态来自内部读取的 `get-api-list`（服务端标 `@Deprecated`，CLI 内部读、不做公开命令）。CLI 读取全量后只把指定 datasets 的 resourceCodes 置为 `0`，其余保持当前动作后全量回写。
+
+## 命令
+
+```bash
+rabetbase permit role-apis-set --role 销售组 --revoke --datasets ds_finance --dry-run
+rabetbase permit role-apis-set --role 销售组 --revoke --datasets ds_finance,ds_invoice --yes
+```
+
+## 参数
+
+| Flag | 必填 | 说明 |
+|------|------|------|
+| `--role <id\|name>` | 是 | 目标角色（DEV/ADMIN 拒绝） |
+| `--revoke` | 是 | 一期语义固定为收回；缺失会报 validation |
+| `--datasets <code,...>` | 是 | 逗号分隔 datasetCode；该角色 API 资源里不存在的 code 报错 |
+| `--appcode <code>` | 否 | 覆盖当前 app |
+
+## 输出协议
+
+```json
+{
+  "operation": "api-revoke",
+  "selector": { "appCode": "app-xxx", "roleId": 12, "roleName": "销售组", "datasetCodes": ["ds_finance"] },
+  "before": [{ "resourceCode": "API_FIN_1", "datasetCode": "ds_finance", "action": "access" }],
+  "after": [{ "resourceCode": "API_FIN_1", "datasetCode": "ds_finance", "action": "0" }],
+  "dryRun": true,
+  "backend": { "method": "POST", "path": "/smartapi/permit/role/update", "roleType": "API" },
+  "warnings": []
+}
+```
+
+不含合成 `protocol`。校验读 `data.after`（应全部为 `action: "0"`）。
+
+## 用例 4（完整：菜单 + API 双侧收紧）
+
+```bash
+rabetbase dataset list                       # 定位财务域 datasetCode
+rabetbase permit role-menus-set --role <salesId> --revoke --menus <财务菜单> --dry-run|--yes
+rabetbase permit role-apis-set  --role <salesId> --revoke --datasets <财务datasetCode> --dry-run|--yes
+```
+
+菜单不可见 + 数据接口不可访问，两侧都要收紧。真实「登录后是否读不到财务行」用 `lovrabet` 运行态验证。
+
+## 参考
+
+- [permit role-menus / role-menus-set](rabetbase-permit-role-menus-set.md)
+- [dataset list](rabetbase-dataset-list.md)
+- [SKILL.md](../SKILL.md)

package/skills/rabetbase/references/rabetbase-permit-role-menus-set.md

@@ -0,0 +1,57 @@
+# rabetbase permit role-menus / role-menus-set
+
+查看与设置某角色的**菜单**权限矩阵（`roleType: PAGE`）。`role-menus-set` 是 `high-risk-write`：CLI 读取角色全量菜单资源，只翻转 `--menus` 指定的 `resourceCode`，其余保持当前动作后全量回写 `permits`。
+
+**内置角色守卫**：DEV / ADMIN 的权限矩阵不可改，会被 validation 拒绝。
+
+## 命令
+
+```bash
+rabetbase permit role-menus --role 销售组 --format compress
+rabetbase permit role-menus-set --role 销售组 --revoke --menus MENU_FIN_1,MENU_FIN_2 --dry-run
+rabetbase permit role-menus-set --role 销售组 --grant --menus MENU_SALES_1 --yes
+```
+
+## role-menus（读）
+
+返回 `data.menus[]`：`resourceCode`、`resourceName`、`allowed`（是否 `access`）、`action`。用它拿到可用的 `resourceCode` 再去 set。
+
+## role-menus-set 参数
+
+| Flag | 必填 | 说明 |
+|------|------|------|
+| `--role <id\|name>` | 是 | 目标角色（DEV/ADMIN 拒绝） |
+| `--grant` / `--revoke` | 是（二选一） | 授予（`access`）或收回（`0`） |
+| `--menus <code,...>` | 是 | 逗号分隔的菜单 `resourceCode`；未知 code 报错 |
+| `--appcode <code>` | 否 | 覆盖当前 app |
+
+## 输出协议
+
+```json
+{
+  "operation": "menu-revoke",
+  "selector": { "appCode": "app-xxx", "roleId": 12, "roleName": "销售组", "resourceCodes": ["MENU_FIN_1"] },
+  "before": [{ "resourceCode": "MENU_FIN_1", "action": "access" }],
+  "after": [{ "resourceCode": "MENU_FIN_1", "action": "0" }],
+  "dryRun": true,
+  "backend": { "method": "POST", "path": "/smartapi/permit/role/update", "roleType": "PAGE" },
+  "warnings": []
+}
+```
+
+## 用例 4（菜单侧：销售组不看财务菜单）
+
+```bash
+rabetbase dataset list                      # 定位财务域
+rabetbase permit role-menus --role <salesId>
+rabetbase permit role-menus-set --role <salesId> --revoke --menus <财务菜单resourceCodes> --dry-run
+rabetbase permit role-menus-set --role <salesId> --revoke --menus <...> --yes
+```
+
+一期不做自动 suggest，必须显式 `--menus`，避免误伤非财务菜单。API 侧收紧见 [`role-apis-set`](rabetbase-permit-role-apis-set.md)。
+
+## 参考
+
+- [permit role-apis-set](rabetbase-permit-role-apis-set.md)
+- [permit page-get / page-set](rabetbase-permit-page-set.md)
+- [SKILL.md](../SKILL.md)

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

@@ -0,0 +1,46 @@
+# project create
+
+创建新项目。
+
+> **风险等级：write** — 创建项目文件和配置。
+
+## 命令
+
+```bash
+# 交互模式
+rabetbase project create
+
+# 指定项目名
+rabetbase project create my-project
+
+# 通过 flag 指定
+rabetbase project create --name my-project
+
+# 非交互模式（必须传 name）
+rabetbase project create my-project --appcode <code> --env production
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `<project-name>` | positional | 否 | — | 项目名称（也可用 `--name`） |
+| `--name <name>` | string | 否 | — | 项目名称（优先于位置参数） |
+| `--env <env>` | string | 否 | — | 目标环境 |
+| `--appcode <code>` | string | 否 | — | 绑定的应用 code（跳过交互选择） |
+
+## 两种模式
+
+1. **交互模式** — 通过提示选择项目配置
+2. **非交互模式**（`--ci` 或非 TTY）— 必须提供项目名称，支持 `--appcode` 跳过应用选择
+
+## 提示
+
+- `--name` 和位置参数二选一，`--name` 优先
+- 非交互模式下缺少项目名会报错
+- 新项目中的 `.rabetbase.json` **只继承**全局中的少量偏好（如 `cookie`、`accessKey`、`locale`、`format`、`riskLevel`），**不会**把全局的 `apps` / `defaultApp` 复制进新项目
+
+## 参考
+
+- [SKILL.md](../SKILL.md)
+- [rabetbase init](rabetbase-init.md)

package/skills/rabetbase/references/rabetbase-project-upgrade.md

@@ -0,0 +1,57 @@
+# project upgrade
+
+从 lovrabet-cli 迁移到 rabetbase-cli。
+
+## 命令
+
+```bash
+# 交互模式（先分析 → 展示报告 → 确认 → 执行）
+rabetbase project upgrade
+
+# 自动模式（跳过确认）
+rabetbase project upgrade --yes
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--yes` | boolean | 否 | `false` | 跳过确认提示，直接执行 |
+
+## 执行流程
+
+两阶段模式：先分析 → 展示报告 → 确认 → 执行 6 步：
+
+| 步骤 | 操作 | 说明 |
+|------|------|------|
+| 1 | 配置文件迁移 | 旧配置（`.lovrabet.json` 等）→ `.rabetbase.json`，旧文件备份为 `.bak` |
+| 2 | 删除 `.lovrabet/` | 移除旧的工作目录 |
+| 3 | 删除旧 IDE skill 文件 | 移除 `.cursor/rules/lovrabet_rules.mdc`、`.claude/skills/lovrabet` 等 |
+| 4 | 清理 MCP 配置 | 从 `.cursor/mcp.json` 移除引用 `@lovrabet/dataset-mcp-server` 的条目 |
+| 5 | 移除旧 skill | 清理旧的 Lovrabet Skill 安装记录 |
+| 6 | 安装新 skill | `npx skills add lovrabet/rabetbase -g -y` |
+
+## 分析报告
+
+执行前会扫描并展示：
+- 旧配置文件路径和待迁移字段
+- 旧文件/目录列表
+- MCP 配置中待清理的条目
+- 是否需要 skill 替换
+
+## 输出
+
+- 每步显示 OK / FAIL 和详情
+- 最终汇总表：所有步骤的执行结果
+- 全部成功：`Upgrade completed successfully!`
+- 部分失败：提示检查 summary
+
+## 触发方式
+
+- 手动执行：`rabetbase project upgrade`
+- 自动触发：`rabetbase init` 检测到旧配置时自动路由
+
+## 参考
+
+- [SKILL.md](../SKILL.md)
+- [rabetbase init](rabetbase-init.md)

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

@@ -0,0 +1,68 @@
+# rabetbase role（list / detail / create / update / delete）
+
+管理当前应用的用户组（角色）。事实源是平台角色管理面。角色类型：`ADMIN` / `DEV` / `USER`（内置）与 `CUSTOM`（用户创建）。
+
+**内置角色守卫**：`update` / `delete` 仅限 `CUSTOM`；对 `DEV` / `ADMIN` 会被 validation 拒绝。修改权限矩阵见 [`permit`](rabetbase-permit-role-menus-set.md)。成员增删对所有角色可用，见 [`user-add / user-remove`](rabetbase-role-user-add.md)。
+
+写操作默认输出 `compress`，先 `--dry-run` 确认再 `--yes`。
+
+## 命令
+
+```bash
+rabetbase role list --format compress
+rabetbase role list --type DEV --format compress
+rabetbase role detail --id 12 --format compress
+rabetbase role create --name 销售组 --dry-run
+rabetbase role create --name 销售组 --remark "华东销售" --format compress
+rabetbase role update --id 12 --name 销售组-华东 --dry-run
+rabetbase role delete --id 12 --dry-run
+rabetbase role delete --id 12 --yes
+```
+
+## list / detail
+
+`list` 列出用户组，`--type` 可过滤 `ADMIN|DEV|USER|CUSTOM`；`--page` 默认 `1`，`--pagesize` 默认 `100` 且范围为 `1-100`。输出关注 `data.roles[]`：`id`、`roleName`、`roleType`、`remark`、`userCount`、`permitCount`、`builtin`。
+
+`detail --id` 通过单条接口返回同结构 `data.role`。名称引用会在 CLI 内部遍历所有角色分页，避免遗漏第 100 条之后的角色。
+
+## create
+
+创建 CUSTOM 用户组（服务端固定 `roleType=CUSTOM`）。服务端 `role/create` 返回创建后的完整角色对象；CLI 直接填充 `data.selector.roleId` 与 `data.after`，不再按名称回查。
+
+## update
+
+仅改 `CUSTOM` 角色的 `--name` / `--remark`（至少一个）。DEV / ADMIN 被拒绝。输出 `data.before` / `data.after` 为角色投影。
+
+## delete
+
+`high-risk-write`；仅 `CUSTOM`。dry-run 会在角色仍有成员时给出 `warnings`。正式执行需 `--yes`。
+
+## 输出协议（写命令）
+
+`create` / `update` / `delete` 在 `data` 内返回稳定字段，Agent 读内层而非顶层 envelope：
+
+```json
+{
+  "operation": "delete",
+  "selector": { "appCode": "app-xxx", "roleId": 12, "roleName": "销售组" },
+  "before": { "id": 12, "roleName": "销售组", "roleType": "CUSTOM", "builtin": false },
+  "after": null,
+  "dryRun": true,
+  "backend": { "method": "POST", "path": "/smartapi/permit/role/delete" },
+  "warnings": []
+}
+```
+
+不含合成 `protocol` key。dry-run 会在同一 `data` 上附加不可枚举的 `method` / `url`，仅用于请求预览。
+
+## 用例编排
+
+- 用例 1（把小张加入开发者）：`role user-resolve --name 小张` → `role list --type DEV` 取 devId → [`role user-add`](rabetbase-role-user-add.md)。
+- 用例 2（创建销售组）：`role create --name 销售组 --yes`，从 `data.selector.roleId` 取新 id。
+
+## 参考
+
+- [role user-resolve](rabetbase-role-user-resolve.md)
+- [role user-add / user-remove](rabetbase-role-user-add.md)
+- [permit role-menus-set / role-apis-set](rabetbase-permit-role-menus-set.md)
+- [SKILL.md](../SKILL.md)

package/skills/rabetbase/references/rabetbase-role-user-add.md

@@ -0,0 +1,54 @@
+# rabetbase role user-add / user-remove
+
+把用户加入/移出角色。服务端 `update-user-list` 是**全量回写所有用户组成员**，CLI 内部做 read-merge-write：只改目标角色的 `userList`，其余角色原样带回，避免误删其它角色成员。`high-risk-write`，正式执行需 `--yes`。
+
+## 命令
+
+```bash
+rabetbase role user-add --role 12 --user 小张 --dry-run
+rabetbase role user-add --role 销售组 --user 1001 --yes
+rabetbase role user-remove --role 12 --user 1001 --dry-run
+rabetbase role user-remove --role 12 --user 1001 --yes
+```
+
+## 参数
+
+| Flag | 必填 | 说明 |
+|------|------|------|
+| `--role <id\|name>` | 是 | 目标角色；纯数字按 id，否则按角色名精确匹配（重名报错） |
+| `--user <id\|name>` | 是 | 目标用户；纯数字按 userId，否则按昵称/用户名解析（见 user-resolve） |
+| `--expect-user-count <n>` | 否 | 防漂移：目标角色当前成员数不等于 n 即中止 |
+| `--appcode <code>` | 否 | 覆盖当前 app |
+
+## 行为与幂等
+
+- `user-add`：用户已在该角色 → 不写、`data.warnings` 提示、`before == after`。
+- `user-remove`：用户不在该角色 → 不写、`data.warnings` 提示。
+- 有变更时才调用 `update-user-list`。
+
+## 输出协议
+
+```json
+{
+  "operation": "user-add",
+  "selector": { "appCode": "app-xxx", "roleId": 12, "roleName": "销售组", "userId": 1001 },
+  "before": { "userIds": [200] },
+  "after": { "userIds": [200, 1001] },
+  "dryRun": true,
+  "backend": { "method": "POST", "path": "/smartapi/permit/user-role/update-user-list" },
+  "warnings": []
+}
+```
+
+Agent 校验时读 `data.before.userIds` / `data.after.userIds`，不要读顶层 envelope。dry-run 会附加不可枚举的 `method` / `url`。
+
+## 用例编排
+
+- 用例 1：`role user-resolve --name 小张` → `role list --type DEV` → `role user-add --role <devId> --user <userId> --yes`。
+- 用例 3：`role user-resolve --name 小陈` → `role user-add --role <salesId> --user <userId> --yes`。
+
+## 参考
+
+- [role user-resolve](rabetbase-role-user-resolve.md)
+- [role list](rabetbase-role-list.md)
+- [SKILL.md](../SKILL.md)

package/skills/rabetbase/references/rabetbase-role-user-resolve.md

@@ -0,0 +1,27 @@
+# rabetbase role user-resolve
+
+把昵称/用户名解析为 `userId`。事实源是当前租户的成员目录（`getByTenantCode`，按当前会话 tenant 解析）。用于 `user-add` / `user-remove` 前先拿到稳定 `userId`。
+
+## 命令
+
+```bash
+rabetbase role user-resolve --name 小张 --format compress
+```
+
+## 行为
+
+- 精确匹配 `nickname` 或 `username`（大小写不敏感）。
+- 命中 0 个：报 validation error，提示核对或改用 `--user <id>`。
+- 命中多个：报歧义并列出候选 `nickname(userId)`，要求用 id 消歧。
+- 输出 `data.user`：`userId`、`username`、`nickname`、`matchedBy`（`id` / `name`）。
+
+## 边界
+
+- 该接口未列入 Apifox 6396450，依赖 live 环境；未登录会报 auth required。
+- 只做只读解析，不写任何角色成员；实际加入用 [`role user-add`](rabetbase-role-user-add.md)。
+
+## 参考
+
+- [role user-add / user-remove](rabetbase-role-user-add.md)
+- [role list](rabetbase-role-list.md)
+- [SKILL.md](../SKILL.md)

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

@@ -0,0 +1,53 @@
+# run
+
+执行 `package.json` 中定义的脚本。
+
+> **风险等级：high-risk-write** — 任意 package script 都可能修改本地文件、调用远端服务或执行发布动作。独立 CLI 需要人工提升顶层 `riskLevel`，正式执行还需交互确认或显式传 `--yes`；嵌入式 Rabetbase 工具暂不开放 `run`。
+
+## 命令
+
+```bash
+# 列出所有可用脚本
+rabetbase run
+
+# 执行指定脚本
+rabetbase run build
+rabetbase run start
+rabetbase run dev
+rabetbase run preview
+
+# preview watch 模式（并行 vite build --watch + vite preview）
+rabetbase run preview --watch
+
+# 传递额外参数
+rabetbase run build -- --mode production
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `<script>` | positional | 否 | — | package.json 中的脚本名；省略时列出所有脚本 |
+| `--watch` | boolean | 否 | `false` | 仅 `preview` 脚本可用：并行执行 `vite build --watch` + `vite preview` |
+| `[-- extra-args]` | positional | 否 | — | 传递给脚本的额外参数（`--` 分隔） |
+
+## 特殊行为
+
+- **自动检测包管理器**：按 lock 文件判断 bun / pnpm / yarn / npm
+- **`start` / `dev` 脚本**：执行前自动检查 CLI 和 SDK 版本，有更新时打印升级警告
+- **`preview --watch`**：并行启动 `vite build --watch` 和 `vite preview`，适合开发时预览生产构建
+
+## 输出
+
+- 脚本不存在时报错并列出可用脚本
+- 脚本输出直接透传（`stdio: inherit`）
+
+## 提示
+
+- 必须在包含 `package.json` 的项目根目录执行
+- 先审阅目标 script 的实际命令体和参数；不要把脚本名当成只读能力
+- 所有项目脚本统一使用 `rabetbase run <script>`
+
+## 参考
+
+- [SKILL.md](../SKILL.md)

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

@@ -0,0 +1,22 @@
+# schema export
+
+导出与 **`rabetbase --help` 同源**的机器可读命令元数据（全部 `service` / `command`、risk、auth、deprecated、flags 等），供 Skill、脚本、IDE 对齐当前 CLI 契约。
+
+## 命令
+
+```bash
+rabetbase schema
+# 等价于
+rabetbase schema export
+```
+
+- **无需登录**、**无需 appcode**。
+- 默认（未覆盖配置里的 `format`）为 **`--format json`**（缩进信封）；大 payload 时 AI 可优先 **`--format compress`** 单行省 token。
+
+## 详细说明
+
+见仓库内用户指南：**`docs/user-guide/12-schema命令.md`**（载荷结构、`globalFlags`、`services[].commands[].auth`、`services[].commands[].deprecated`、`services[].commands[].flags` 等）。
+
+## 参考
+
+- [SKILL.md](../SKILL.md)

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

@@ -0,0 +1,41 @@
+# sql create
+
+先在远端创建一条新的自定义 SQL，再在本地同步目录中生成初始文件并写入 `.rabetbase/sql.lock.json`。
+
+## 命令
+
+```bash
+rabetbase sql create --name getUserList --db-id 10001 --mode sql --format json
+rabetbase sql create --name getUserList --db-id 10001 --mode sql --dry-run --format json
+rabetbase sql create --name getUserMapper --db-id 10001 --mode mybatisXml --format json
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--name <name>` | string | 交互补全 / 非交互必填 | — | SQL 展示名 |
+| `--db-id <id>` | number | 交互补全 / 非交互必填 | — | 目标数据库 ID |
+| `--mode <mode>` | string | 交互补全 / 非交互必填 | — | 本地文件模式：`sql` 或 `mybatisXml` |
+| `--dry-run` | boolean | 否 | — | 预览目标路径与请求体 |
+| `--format <fmt>` | string | 否 | `compress` | 输出格式 |
+
+## 本地输出
+
+成功后会：
+
+- 在远端创建 SQL，拿到服务端生成的 `sqlCode`
+- 在 **`.rabetbase/sql/<appCode>/<dbName|db-<id>>/<sqlCode>_<sqlName>.sql|xml`** 生成初始文件
+- 在 **`.rabetbase/sql.lock.json`** 写入 lock 条目（含 `remoteId`、`version`、`dbId`、`path`、`mode` 等）
+
+生成文件会自动带上 `@lovrabet` 元注释头，后续 `sql push` 上传时会自动剥离，不会写回平台正文。
+
+## 提示
+
+- 团队长期维护 SQL 时，用 `sql create` 建立本地同步资产
+- 生成后通常继续执行：编辑本地文件 → `sql validate --file ...` → `sql status` → `sql push --sqlcode ... --dry-run` → `sql push --sqlcode ... --yes`
+
+## 参考
+
+- [SKILL.md](../SKILL.md)
+- [sql-creation-workflow.md](../guides/sql-creation-workflow.md)

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

@@ -0,0 +1,37 @@
+# sql delete
+
+删除一条远端 SQL，并把本地同步目录中的对应文件移入 `.rabetbase/sql-trash/`。
+
+> **风险等级：high-risk-write** — 建议先 `--dry-run` 预览；正式执行需 `--yes` 或交互确认。
+
+## 命令
+
+```bash
+rabetbase sql delete --sqlcode 2305f915-dd48cd4c --dry-run --format json
+rabetbase sql delete --sqlcode 2305f915-dd48cd4c --yes --format json
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--sqlcode <code>` | string | 是 | — | 要删除的 SQL code |
+| `--dry-run` | boolean | 否 | — | 预览远端 id 与本地文件路径 |
+| `--yes` | boolean | 否 | — | 跳过高风险确认 |
+| `--format <fmt>` | string | 否 | `compress` | 输出格式 |
+
+## 行为说明
+
+- 依赖 `.rabetbase/sql.lock.json` 找到远端 `id` 与本地文件
+- 远端删除成功后，会移除 lock 条目
+- 若本地文件存在，会移动到 **`.rabetbase/sql-trash/<timestamp>/...`**
+- 会自动清理同步目录中因此变空的中间目录
+
+## 提示
+
+- 若提示 `SQL lock file not found` 或 `No SQL lock entry found`，先执行 `sql pull` 或确认这条 SQL 是否由当前项目跟踪
+
+## 参考
+
+- [SKILL.md](../SKILL.md)
+- [sql-creation-workflow.md](../guides/sql-creation-workflow.md)