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

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

@@ -0,0 +1,82 @@
+# api pull
+
+拉取当前 App 下所有数据集（Dataset）的元信息，生成 TypeScript API 客户端代码到 `src/api/` 目录。
+
+生成的代码包含每个 Dataset 的 Model 类，可直接用于 SDK 查询，无需手动调用 HTTP 接口。
+
+## 命令
+
+```bash
+# 拉取并生成 API 代码（默认 ./src/api/）
+rabetbase api pull
+
+# 指定输出目录
+rabetbase api pull --output ./src/generated/api/
+
+# 多应用：默认只解析「项目级」apps；与全局合并配置一起拉取时加 --global
+rabetbase api pull --global
+
+# 多应用模式：指定某个应用
+rabetbase api pull --app order
+rabetbase api pull --appcode app-order-001
+```
+
+## 参数
+
+| 参数 | 说明 |
+|------|------|
+| `--output <dir>` | 输出目录，默认 `./src/api/` |
+| `--global` | 多应用时从「全局+项目」合并配置解析 `apps`（默认仅项目级 `apps`）。若项目配置了 `inherit: false`，见下节 |
+| `--app <name>` | 多应用模式下，指定应用名称 |
+| `--appcode <code>` | 直接指定 appcode，跳过配置查找 |
+
+## 多应用过滤
+
+多应用模式下：
+- **不加 `--app` / `--appcode`**：遍历已配置应用（默认仅 **项目** `.rabetbase.json` 中的 `apps`；若需包含全局里合并进来的应用，加 **`--global`**）
+- **加 `--app <name>`**：仅拉取指定应用
+- **加 `--appcode <code>`**：反查到对应 app profile，使用其 cookie/env/apiDir
+
+## 与 `inherit` 的关系
+
+项目 `.rabetbase.json` 的 `inherit` 字段控制配置合并行为：
+
+- **省略**（默认）：项目主导，仅从全局白名单继承 cookie/accessKey/locale/format/riskLevel/pageSize，不继承 apps/defaultApp/appcode。`--global` 仍可看到全局 apps（多应用列表从双层直接取）。
+- **`true`**：全量合并全局+项目（旧行为，需显式开启）。
+- **`false`**：完全隔离，不继承任何全局字段。
+
+此时：
+
+- **`api pull` 使用的 cookie、apiDir、appcode 等**均来自**项目文件**（默认行为下 cookie/accessKey 仍可从全局白名单继承）。
+- **`--global` 多应用列表**始终从全局+项目双层取 apps，不受 inherit 限制。
+
+## 输出文件
+
+| 文件 | 说明 |
+|------|------|
+| `<prefix>-api.ts` | 数据模型定义（datasetCode → Model 映射） |
+| `<prefix>-client.ts` | SDK 客户端初始化代码 |
+
+默认 `prefix` 为空（单应用），多应用非 default 应用使用应用名作为 prefix。
+
+## 生成标识符
+
+`api pull` 遵循 [`best-practices.md`](../guides/best-practices.md) 的动态标识符原则，确保生成的 TypeScript 标识符合法且稳定。数字开头的 App Namespace 使用 `APP` 领域前缀，运行时 AppCode 保持不变；该前缀不适用于其他代码生成场景。
+
+## 前置条件
+
+- 已完成 `rabetbase auth` 登录
+- 已配置 appcode（单应用或多应用）
+
+## 示例
+
+```bash
+# 单应用：生成到 ./src/api/
+rabetbase api pull
+
+# 多应用 order：生成到 ./src/api/ 并使用 order- 前缀
+rabetbase api pull --app order
+
+# 独立输出目录
+rabetbase api pull --output ./src/generated/api/
+```

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

@@ -0,0 +1,95 @@
+# rabetbase app-config
+
+管理当前应用的运行态 app-config key。事实源是平台 app-config 管理面，不是本地 `.rabetbase.json`；本地配置仍用 `rabetbase config` / `rabetbase app` 管理。
+
+`value` 默认按敏感内容处理：`list` 和默认 `get` 不输出明文，`set --dry-run` / `delete --dry-run` 也不输出明文。不要把 app-config value 写入本地配置、缓存、日志或命令参数转发给业务 BFF。
+
+## 命令
+
+```bash
+rabetbase app-config list --format compress
+rabetbase app-config get <key> --format compress
+rabetbase app-config get <key> --reveal --format compress
+rabetbase app-config set <key> --from-env ENV_NAME --dry-run
+rabetbase app-config set <key> --from-env ENV_NAME --yes
+rabetbase app-config delete <key> --dry-run
+rabetbase app-config delete <key> --yes
+```
+
+## list
+
+```bash
+rabetbase app-config list --format compress
+rabetbase app-config list --tags webhook --format compress
+rabetbase app-config list --key vectorengine.apiKey --format compress
+```
+
+输出关注：
+
+- `data.configs[]`
+- `key`
+- `tags`
+- `hasValue`
+- `valueRedacted`
+- `gmtModified`
+
+不会输出 `value`，也不展示服务端预留的 `encrypted` 字段。
+
+## get
+
+```bash
+rabetbase app-config get vectorengine.apiKey --format compress
+```
+
+默认只用于确认 key 是否存在、是否有值、路由 appCode 是否正确。
+
+只有明确需要查看单个 key 明文时才使用：
+
+```bash
+rabetbase app-config get vectorengine.apiKey --reveal --format compress
+```
+
+`--reveal` 只支持单 key，不存在批量 reveal。
+
+## set
+
+`set` 以 key 为主路径，CLI 会先按 key 查询：存在则 update，不存在则 create。用户不需要传服务端 id。
+
+value 来源必须且只能选一种：
+
+```bash
+printf '%s' "$VECTORENGINE_API_KEY" | rabetbase app-config set vectorengine.apiKey --stdin --dry-run
+rabetbase app-config set vectorengine.apiKey --from-env VECTORENGINE_API_KEY --dry-run
+rabetbase app-config set vectorengine.apiKey --file ./secret.txt --dry-run
+```
+
+确认 dry-run 的 `operation`、`selector.appCode`、`selector.key`、`before`、`after` 后，再执行正式写入：
+
+```bash
+rabetbase app-config set vectorengine.apiKey --from-env VECTORENGINE_API_KEY --yes
+```
+
+显式位置参数 `<value>` 可用，但不推荐用于敏感值，因为 shell history 可能记录明文。
+
+## delete
+
+```bash
+rabetbase app-config delete vectorengine.apiKey --dry-run
+rabetbase app-config delete vectorengine.apiKey --yes
+```
+
+删除同样以 key 定位，CLI 内部解析服务端 id 后调用 delete。缺失 key 会报 validation error。
+
+## 安全边界
+
+- `list` 永不批量输出明文 value。
+- 默认 `get` 不输出明文 value。
+- `set/delete --dry-run` 不输出明文 value，也不写入。
+- `set` 的成功/失败输出只报告 key、appCode、operation 和脱敏上下文。
+- 不依赖、不展示、不判断 `encrypted`。
+- 不把运行态 app-config 混入 `rabetbase config`。
+- 当前不把该能力描述为 KMS、密钥托管、自动轮换或后端加密能力。
+
+## 业务消费
+
+rabetbase 负责维护运行态 app-config 管理面。业务代码需要敏感配置时，应由服务端 BFF 上下文通过 `context.appConfig.get(...)` 读取并消费；不要让 Agent 先 `--reveal` value，再把明文作为 `lovrabet bff exec` 参数或脚本参数传入。

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

@@ -0,0 +1,79 @@
+# rabetbase app list
+
+列出应用。
+
+默认列出**本地配置视图**，与 CLI 运行时一致：合并全局 `~/.rabetbase.json`（或同目录下首个匹配的旧名）与**项目**当前目录下的配置文件。
+加 `--remote` 时改为查询**平台目录视图**：当前登录账号在平台上可访问的应用，不读取或修改本地 app 配置。
+
+- **不加 flag**：合并视图（global + project）。
+- **`--global`**：仅列出**全局**文件中的应用。
+- **`--project`**：仅列出**项目**文件中的应用（与 `--global` 互斥）。
+- **`--remote`**：列出当前登录账号在平台上可访问的应用（与 `--global` / `--project` 互斥）。
+
+登记应用用 `workspace add`（默认写项目，`--global` 写全局）。当前工作目录默认应用用 `workspace use` 修改。移除应用用 `workspace remove`，落盘规则见 workspace reference。
+
+## 命令
+
+```bash
+rabetbase app list
+rabetbase app list --global
+rabetbase app list --project
+rabetbase app list --remote
+```
+
+> **说明：** `rabetbase app` 本身只显示 `app` 服务帮助；查看本地配置中的应用请显式执行 `rabetbase app list`。平台目录视图使用 `rabetbase app list --remote`。
+
+## 参数
+
+| Flag | 说明 |
+|------|------|
+| `--global` | 仅全局配置中的应用 |
+| `--project` | 仅项目配置中的应用 |
+| `--remote` | 查询平台目录中的可访问应用；需要登录；不能与 `--global` / `--project` 同用 |
+
+## 结构化输出（`--format json` / `compress`）
+
+本地配置视图中，`data` 为对象（**不是**顶层数组），包含 `items` 与 `meta`：
+
+| 字段 | 说明 |
+|------|------|
+| `items` | 应用条目数组 |
+| `meta` | **合并视图**：`globalPath`、`projectPath`、`defaultApp`（无命名默认时为**有效 appcode**）、`defaultAppSource`（`project` \| `global` \| `null`）。**`--global` / `--project`**：`scope`、`configPath` |
+
+每个 `items[]` 元素除 `name`、`appcode`、`env` 等外，另有：
+
+| 字段 | 说明 |
+|------|------|
+| `named` | `true` — 来自 `apps` 中的命名应用；`false` — 仅顶层 `appcode`/`app` 的**旧版单应用**行（`name` 可能为 `null`） |
+| `definedIn` | `global` / `project` / `both`（合并视图下；单边视图下为对应侧） |
+| `isDefault` | 是否为当前解析出的默认应用 |
+| `isCurrent` | 是否为当前激活应用（合并视图） |
+
+**jq 示例**（只取命名应用名）：`--format json --jq '.data.items[] | select(.named) | .name'`
+
+无任何应用时：`data` 可能为空数组 `[]`（见命令 `message`）。
+
+`--remote` 输出同样是 `{ items, meta }`，但语义不同：
+
+| 字段 | 说明 |
+|------|------|
+| `items` | 平台返回的可访问应用数组，常见字段为 `id`、`appCode`、`appName`、`appDesc` |
+| `meta.source` | 固定为 `platform` |
+
+## 人类可读（`pretty` / `table`）
+
+合并视图：先打印全局/项目配置文件路径、当前 **Default app**（及来源），再列出各应用。`--global` / `--project` 时元信息对应该单层。`--remote` 展示平台目录返回的应用。
+
+## 提示
+
+- 若列表与预期不符，先检查项目或全局 JSON **是否为合法 JSON**（例如尾随逗号会导致该侧配置被忽略）；`rabetbase doctor` 的 **Config JSON** 段可检测语法。
+- 无 `apps` 时显示单应用信息，并提示可用 `workspace add` 迁移到多应用模式。
+- 如果你想知道“本地已经登记了哪些应用”，执行 `rabetbase app list`。
+- 如果你想知道“当前登录账号在平台上还能访问哪些应用”，执行 `rabetbase app list --remote`。
+
+## 参考
+
+- [SKILL.md](../SKILL.md) — 总索引
+- [`.rabetbase.json` 配置参考](rabetbase-config.md) — 合并策略与路径
+- [rabetbase doctor](rabetbase-doctor.md) — 配置与 JSON 诊断
+- [rabetbase workspace](rabetbase-workspace.md) — 工作环境应用配置（绑定/登记/移除）入口

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

@@ -0,0 +1,64 @@
+# rabetbase app members-list
+
+列出当前解析应用的完整人员清单，并将服务端角色分组整理为按 userId 去重的人员视图。只读，需要认证和 App Code。
+
+## 命令
+
+```bash
+rabetbase app members-list --format compress
+rabetbase app members-list --appcode app-example --format compress
+```
+
+应用选择遵循 CLI 统一规则：显式 `--appcode`、`--app` 或当前工作区默认应用。命令返回全量人员，不提供分页、关键字、状态或角色筛选。
+
+## 结构化输出
+
+```json
+{
+  "ok": true,
+  "command": "rabetbase app members-list",
+  "risk": "read",
+  "data": {
+    "appCode": "app-example",
+    "items": [
+      {
+        "userId": 100,
+        "username": "alice",
+        "displayName": "Alice",
+        "status": "ACTIVE",
+        "roles": [
+          {
+            "roleId": 2,
+            "roleName": "开发者",
+            "roleType": "DEV",
+            "membershipStatus": "ACTIVE"
+          }
+        ]
+      }
+    ],
+    "totalCount": 1
+  }
+}
+```
+
+- `membershipStatus` 为 `ACTIVE`（正式成员）或 `PENDING`（待加入成员）。
+- 同一用户只要存在一个 ACTIVE 角色，顶层 `status` 即为 `ACTIVE`；全部角色待加入时为 `PENDING`。
+- 人员按 `userId` 升序；角色按 `roleId` 升序，同角色下 ACTIVE 排在 PENDING 前。
+- `username`、`displayName` 缺失时为 `null`；不会用 userId 伪造。
+- 不输出头像、手机、邮箱、Cookie、Token 或 AccessKey。
+
+## 失败路径
+
+- 未登录：先执行 `rabetbase auth login`。
+- 缺少 App Code：在工作区绑定应用，或显式传 `--appcode` / `--app`。
+- 当前账号无应用权限：保留服务端权限错误，不把错误解释为空列表。
+- 网络异常或服务端错误：保留 CLI 结构化错误。
+
+合法空应用返回成功，`items: []` 且 `totalCount: 0`。
+
+## 参考
+
+- [租户人员列表](rabetbase-tenant-members-list.md)
+- [应用列表](rabetbase-app-list.md)
+- [角色列表](rabetbase-role-list.md)
+- [SKILL.md](../SKILL.md)

package/skills/rabetbase/references/rabetbase-auth-login.md

@@ -0,0 +1,53 @@
+# auth login
+
+通过浏览器完成 OAuth 登录，并把登录态 cookie 写入本机配置目录。
+
+## 命令
+
+```bash
+# 交互式登录：CLI 会询问是否开始登录，并自动打开浏览器
+rabetbase auth login
+
+# 非交互 Agent 登录：不打开本机浏览器，打印授权链接给用户
+rabetbase auth login --yes
+
+# 查看帮助
+rabetbase auth login --help
+```
+
+## Agent 执行规则
+
+- 在非交互环境、Coding Agent、CI 或无法打开浏览器的终端中，使用 `rabetbase auth login --yes`。
+- 命令会启动本地回调服务，并打印登录 URL；Agent 应把该 URL 原样发给用户，让用户在自己的浏览器中打开并完成授权。
+- 登录 URL 有效期为 **10 分钟**。过期后重新执行 `rabetbase auth login --yes` 获取新链接。
+- 不要让 Agent 自己访问登录 URL，也不要要求用户提供账号密码或 cookie。
+- 如果命令提示已有有效 session，则无需重复登录。
+
+## 行为
+
+1. 检查本机是否已有有效 session。
+2. 无有效 session 时启动本地 OAuth 回调服务。
+3. 交互式模式会自动打开浏览器；非交互 `--yes` 模式只打印登录 URL。
+4. 用户授权成功后，CLI 保存 cookie 并输出登录成功。
+5. 10 分钟内未完成授权时，登录服务退出，需要重新执行命令。
+
+## 常见错误
+
+```text
+Browser login cannot run in non-interactive mode.
+```
+
+说明当前环境是非交互模式，但没有传 `--yes`。改用：
+
+```bash
+rabetbase auth login --yes
+```
+
+## 后续
+
+登录完成后，通常继续执行：
+
+```bash
+rabetbase app list --remote --format compress
+rabetbase app list --format compress
+```

package/skills/rabetbase/references/rabetbase-auth-logout.md

@@ -0,0 +1,29 @@
+# auth logout
+
+退出登录，删除本地认证 cookie。
+
+> **风险等级：write** — 删除认证文件。
+
+## 命令
+
+```bash
+rabetbase auth logout
+```
+
+## 参数
+
+无。
+
+## 输出
+
+- 已登录：`✓ Logged out`
+- 未登录：`! Not logged in`
+
+## 提示
+
+- 删除的是本地 cookie 文件，不影响其他设备
+- 退出后需重新 `rabetbase auth` 才能使用 API 命令
+
+## 参考
+
+- [SKILL.md](../SKILL.md)

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

@@ -0,0 +1,59 @@
+# bff create
+
+在本地脚手架创建一个新的 BFF 脚本文件。
+
+## 命令
+
+```bash
+rabetbase bff create --type ENDPOINT --name getUserList --description "获取用户列表" --format json
+rabetbase bff create --type COMMON --name normalizePayload --format json
+rabetbase bff create --type HOOK --name beforeFilter --alias appUser --operation-type filter --function-node before --format json
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--type <type>` | string | 是 | — | 脚本类型：`COMMON` / `ENDPOINT` / `HOOK` |
+| `--name <name>` | string | 是 | — | 函数名（合法 JS 标识符） |
+| `--description <desc>` | string | 否 | — | 脚本描述 |
+| `--alias <alias>` | string | HOOK 时推荐 | — | 数据集 alias |
+| `--datasetcode <code>` | string | HOOK 兜底 | — | 数据集编码 |
+| `--operation-type <op>` | string | HOOK 必填 | — | 如 `getOne` / `filter` / `create` |
+| `--function-node <node>` | string | HOOK 必填 | — | `before` / `after` |
+| `--format <fmt>` | string | 否 | `pretty` | 输出格式 |
+
+## 本地路径
+
+| 类型 | 路径 |
+|------|------|
+| 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` |
+
+BFF 源码**仅**应在此目录树内创建与长期维护（与 `bff status` / `bff push` 扫描一致）；不要在本仓库其他路径手写 BFF 再尝试推送。
+
+## 脚手架边界
+
+`bff create` 只创建本地脚本模板，不会替你确认数据集字段、必填字段、枚举值或运行时 API 语义。编辑脚本前先按需阅读：
+
+- [`backend-function.md`](../guides/backend-function.md)：`context.client`、模型键、返回值、事务、消息通知扩展、禁止事项
+- [`data-api-guidelines.md`](../guides/data-api-guidelines.md)：字段、枚举、外键、性能规则
+
+创建可由 CLI 调用的通知型 BFF 时使用 `ENDPOINT`，并先用 [`rabetbase notification config-list`](rabetbase-notification-config-list.md) 确认当前应用真实的通知 `configCode`。纯通知 ENDPOINT 不需要虚构数据集；脚本只通过 `context.client.extension.execute("notification", "send", ...)` 使用 `configCode`、`audiences`、`message`，不得写渠道地址或密钥。
+
+## 提示
+
+- `HOOK` 非交互场景建议优先传 `--alias`
+- 如果 alias 解析失败，再用 `--datasetcode`
+- `HOOK` 可以挂载 `DB_TABLE` 或 `METADATA` 数据集；可用 operation 以后端返回为准
+- `METADATA` 数据集不支持 SQL / aggregate 路径，脚本里应使用标准数据操作
+- 涉及数据集读写时，先执行 `rabetbase dataset detail --code <code> --format compress` 获取当前字段事实
+- 创建后先跑 `rabetbase bff status --format json` 确认本地状态
+
+## 参考
+
+- [SKILL.md](../SKILL.md)
+- [bff-creation-workflow.md](../guides/bff-creation-workflow.md)
+- [backend-function.md](../guides/backend-function.md)
+- [data-api-guidelines.md](../guides/data-api-guidelines.md)

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

@@ -0,0 +1,42 @@
+# bff delete
+
+删除远端 BFF 脚本，并把本地文件移到 `.rabetbase/bff-trash/`。
+
+> **风险等级：high-risk-write** — 必须显式 `--yes`。
+
+## 命令
+
+```bash
+rabetbase bff delete --yes --target ENDPOINT/getUserList --format json
+rabetbase bff delete --yes --target getUserList --format json
+rabetbase bff delete --target ENDPOINT/getUserList --dry-run --format json
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--target <target>` | string | 是 | — | 完整 lockKey（推荐）或短函数名 |
+| `--dry-run` | boolean | 否 | — | 仅预览删除目标、远端 ID 和本地 trash 路径 |
+| `--yes` | boolean | 是 | — | 跳过高风险确认 |
+| `--format <fmt>` | string | 否 | `pretty` | 输出格式 |
+
+## 目标匹配规则
+
+- 传完整 lockKey 时，精确匹配
+- 只传短名时：
+  - 0 个匹配 → 失败
+  - 1 个匹配 → 执行删除
+  - 多个匹配 → 失败并要求使用完整 lockKey
+
+## 提示
+
+- 这是破坏性操作，会删远端并清理本地 lock
+- `--dry-run` 不会删远端、不会改 lock、不会移动本地文件
+- 本地文件不会直接硬删，而是移入 `.rabetbase/bff-trash`
+- 实际执行前建议先用 `bff status` / `bff list` 确认目标
+
+## 参考
+
+- [SKILL.md](../SKILL.md)
+- [conflict-detection.md](../guides/conflict-detection.md)

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

@@ -0,0 +1,38 @@
+# bff detail
+
+根据 ID 获取 BFF 脚本详情（含完整脚本内容）。
+
+## 命令
+
+```bash
+rabetbase bff detail --id 42 --format json
+rabetbase bff detail --id 42 --verbose --format json
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--id <id>` | number | 是 | — | BFF 脚本 ID（从 `bff list` 获取） |
+| `--verbose` | boolean | 否 | — | 返回完整原始对象 |
+| `--format <fmt>` | string | 否 | `pretty` | 输出格式 |
+
+## 输出
+
+返回 BFF 脚本的完整信息：id、functionName、scriptContent（完整脚本源码）、scriptType、description。
+
+## 使用边界
+
+`bff detail` 用于确认远端事实和取得最新源码。长期维护仍应在 `.rabetbase/bff/<appCode>/...` 同步目录中进行；不要把 `scriptContent` 复制到任意目录后再期望 `bff status` / `bff push` 识别。
+
+## 提示
+
+- 修改已有 BFF 前必须先用此命令拉取最新内容（平台是 source of truth）
+- scriptContent 是完整的 JavaScript 源码
+- 需要落本地维护时，优先用 `rabetbase bff pull --format json` 同步到规范目录
+
+## 参考
+
+- [SKILL.md](../SKILL.md)
+- [bff-creation-workflow.md](../guides/bff-creation-workflow.md)
+- [backend-function.md](../guides/backend-function.md)

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

@@ -0,0 +1,61 @@
+# bff list
+
+列出当前 App 下的 BFF 脚本。
+
+## 命令
+
+```bash
+rabetbase bff list --format json
+rabetbase bff list --type COMMON --format json
+rabetbase bff list --name getUserInfo --format json
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--app <name>` | string | 否 | — | 多应用模式下指定应用名称 |
+| `--appcode <code>` | string | 否 | — | 直接指定 appcode |
+| `--type <type>` | string | 否 | `ENDPOINT` | 脚本类型：`ENDPOINT` / `COMMON` |
+| `--name <name>` | string | 否 | — | 按脚本名过滤 |
+| `--verbose` | boolean | 否 | — | 返回完整脚本对象 |
+| `--format <fmt>` | string | 否 | `pretty` | 输出格式 |
+
+## 多应用过滤
+
+多应用模式下：
+- 不加 `--app` / `--appcode`：遍历所有已配置应用，依次列出各应用的 BFF
+- 加 `--app <name>`：仅列出指定应用的 BFF
+- 加 `--appcode <code>`：反查到对应 app profile，使用其 cookie/env
+
+```bash
+# 仅列出 order 应用的 BFF
+rabetbase bff list --app order
+
+# 指定 appcode
+rabetbase bff list --appcode app-xxxxxxxx
+```
+
+## 输出
+
+默认返回精简列表（id, functionName, description, scriptType）。`--verbose` 返回完整对象。
+
+## BFF 脚本类型
+
+| 类型 | 用途 | 说明 |
+|------|------|------|
+| ENDPOINT | 独立业务端点，前端通过 `client.bff.execute()` 调用 | 默认类型 |
+| COMMON | 公共函数，供其他 BFF 脚本 import 复用 | 需 `--type COMMON` 查询 |
+| HOOK | 挂在标准数据接口前后执行 | 通过数据集详情查看 |
+
+## 提示
+
+- 写 BFF 前先查公共函数列表（`--type COMMON`），看是否有可复用函数
+- 复用 COMMON 前用 `bff detail --id <id>` 确认入参、返回值和副作用，不要按函数名猜契约
+- 修改已有 BFF 前必须先用此命令找到脚本 ID
+
+## 参考
+
+- [SKILL.md](../SKILL.md)
+- [bff-creation-workflow.md](../guides/bff-creation-workflow.md)
+- [backend-function.md](../guides/backend-function.md)

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

@@ -0,0 +1,42 @@
+# bff pull
+
+把远端 BFF 脚本同步到本地 `.rabetbase/bff/<appCode>/...`。
+
+## 命令
+
+```bash
+rabetbase bff pull --format json
+rabetbase bff pull --type ENDPOINT --format json
+rabetbase bff pull --dry-run --format json
+rabetbase bff pull --type HOOK --force --format json
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--type <type>` | string | 否 | — | 仅拉指定类型：`COMMON` / `ENDPOINT` / `HOOK` |
+| `--force` | boolean | 否 | — | 强制覆盖本地未同步改动 |
+| `--dry-run` | boolean | 否 | — | 仅预览将要拉取的远端脚本与目标本地路径 |
+| `--format <fmt>` | string | 否 | `pretty` | 输出格式 |
+
+## 输出
+
+返回：
+- `pulled`
+- `skipped`
+- `failed`
+
+`--dry-run` 时返回预览对象，包含远端脚本、目标 `filePath` 和预期状态（如 `would_pull` / `conflict`）。
+
+## 提示
+
+- 默认会保护本地未同步改动，冲突时进入 `skipped: local unsynced changes`
+- `--dry-run` 不会改本地文件，也不会写 lock
+- `HOOK` 落盘目录依赖 alias / datasetCode 解析
+- 拉取后建议立刻跑一次 `bff status`
+
+## 参考
+
+- [SKILL.md](../SKILL.md)
+- [conflict-detection.md](../guides/conflict-detection.md)