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

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

@@ -0,0 +1,32 @@
+# sql detail
+
+根据 SQL code 获取完整查询详情（含 SQL 内容和参数定义）。
+
+## 命令
+
+```bash
+rabetbase sql detail --sqlcode 2305f915-dd48cd4c --format json
+rabetbase sql detail --sqlcode 2305f915-dd48cd4c --verbose --format json
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--sqlcode <code>` | string | 是 | — | SQL code 标识符（格式：`xxxxxxxx-xxxxxxxx`） |
+| `--verbose` | boolean | 否 | — | 返回完整原始对象 |
+| `--format <fmt>` | string | 否 | `pretty` | 输出格式 |
+
+## 输出
+
+返回 SQL 查询的完整信息：sqlCode、sqlName、sqlContent（完整 SQL 文本）、参数列表、目标数据库。
+
+## 提示
+
+- 修改已有 SQL 前必须先用此命令拉取最新内容
+- sqlContent 是完整的 SQL/MyBatis XML 文本
+
+## 参考
+
+- [SKILL.md](../SKILL.md)
+- [sql-creation-workflow.md](../guides/sql-creation-workflow.md)

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

@@ -0,0 +1,34 @@
+# sql exec
+
+执行已保存的 SQL 查询（通过 sqlCode 调用）。
+
+## 命令
+
+```bash
+rabetbase sql exec --sqlcode 2305f915-dd48cd4c --format json
+rabetbase sql exec --sqlcode 2305f915-dd48cd4c --params '{"keyword":"alice"}' --format json
+rabetbase sql exec --sqlcode 2305f915-dd48cd4c --params '{"page":1,"pageSize":20}' --format json
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--sqlcode <code>` | string | 是 | — | SQL code 标识符（格式：`xxxxxxxx-xxxxxxxx`） |
+| `--params <json>` | string | 否 | — | SQL 参数，JSON 格式 |
+| `--format <fmt>` | string | 否 | `pretty` | 输出格式 |
+
+## 输出
+
+返回 SQL 执行结果，包含数据行和执行耗时。
+
+## 提示
+
+- `--params` 的 JSON key 必须匹配 SQL 中的 `#{param}` 占位符名称
+- 可先用 `sql validate` 或 `sql detail` 查看 SQL 需要哪些参数
+- 执行结果仅包含数据，不含分页元信息（分页由 SQL 本身控制）
+
+## 参考
+
+- [SKILL.md](../SKILL.md)
+- [sql-creation-workflow.md](../guides/sql-creation-workflow.md)

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

@@ -0,0 +1,54 @@
+# sql list
+
+列出当前 App 下的自定义 SQL 查询。
+
+## 命令
+
+```bash
+rabetbase sql list --format json
+rabetbase sql list --name getUserList --format json
+rabetbase sql list --sqlcode 2305f915-dd48cd4c --format json
+rabetbase sql list --page 2 --pagesize 20 --format json
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--sqlcode <code>` | string | 否 | — | 按 SQL code 过滤（格式：`xxxxxxxx-xxxxxxxx`） |
+| `--name <name>` | string | 否 | — | 按名称过滤 |
+| `--page <n>` | number | 否 | `1` | 页码 |
+| `--pagesize <n>` | number | 否 | `50` | 每页数量 |
+| `--verbose` | boolean | 否 | — | 返回完整 SQL 对象（含 SQL 内容和参数） |
+| `--format <fmt>` | string | 否 | `pretty` | 输出格式 |
+
+## 多应用过滤
+
+`sql list` 总是查询**当前已经决议到的单个应用**：
+
+- 默认使用当前项目 `defaultApp`
+- 传 `--app <name>` 时，切到指定本地应用名
+- 传 `--appcode <code>` 时，直接使用指定 appcode
+
+```bash
+# 仅列出 order 应用的 SQL
+rabetbase sql list --app order
+
+# 指定 appcode
+rabetbase sql list --appcode app-xxxxxxxx
+```
+
+## 输出
+
+默认返回精简列表（sqlCode, sqlName, description, db）。`--verbose` 返回完整对象含 SQL 内容。
+
+## 提示
+
+- `--name` 是服务端过滤，`--sqlcode` 也是服务端过滤
+- 修改已有 SQL 前先用此命令找到 sqlCode
+- SQL Code 格式为 `{8位hex}-{8位hex}`，如 `2305f915-dd48cd4c`
+
+## 参考
+
+- [SKILL.md](../SKILL.md)
+- [sql-creation-workflow.md](../guides/sql-creation-workflow.md)

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

@@ -0,0 +1,54 @@
+# sql pull
+
+将远端自定义 SQL 同步到本地 **`<项目根>/.rabetbase/sql/<appCode>/<dbName|db-<id>>/`**，并刷新 `.rabetbase/sql.lock.json`。
+
+## 命令
+
+```bash
+rabetbase sql pull --format json
+rabetbase sql pull --sqlcode <xxxxxxxx-xxxxxxxx> --format json
+rabetbase sql pull --name <过滤名> --format json
+rabetbase sql pull --dry-run --format json
+rabetbase sql pull --force --format json
+```
+
+## 参数
+
+| Flag | 说明 |
+|------|------|
+| `--sqlcode` | 仅拉取指定 SQL（格式 `xxxxxxxx-xxxxxxxx`） |
+| `--name` | 按展示名过滤（与 list API 一致） |
+| `--force` | 覆盖与远端不一致的本地文件 |
+| `--dry-run` | 预览目标路径与状态（不写文件） |
+
+## 输出文件
+
+每条 SQL 会写入：
+
+```text
+.rabetbase/sql/<appCode>/<dbName|db-<id>>/<sqlCode>_<sqlName>.sql|xml
+```
+
+文件头部会自动补齐：
+
+- `-- @lovrabet.sqlCode`
+- `-- @lovrabet.sqlName`
+- `-- @lovrabet.dbId`
+- `-- @lovrabet.dbName`
+- `-- @lovrabet.mode`
+- `-- @lovrabet.syncedAt`
+- `-- @lovrabet.description`
+
+正文为远端 `sqlContent`；同时会更新 `.rabetbase/sql.lock.json` 中的 `path / hash / remoteId / version / dbId / sqlName / mode`。
+
+## 行为说明
+
+- 本地文件与远端生成内容完全一致：计入 `skipped: unchanged`
+- 本地存在且与远端不同、未加 `--force`：跳过并提示 `local differs from remote`
+- `--force` 且存在需覆盖的本地文件时：交互模式下会先确认（非交互需显式 `--force`）
+- 即使本地 `status` 为 `unchanged`，若远端后来被平台侧改动，`pull --dry-run` 仍可能提示冲突；这说明是“远端漂移”，不是 CLI 入口故障
+
+## 参考
+
+- [sql-creation-workflow.md](../guides/sql-creation-workflow.md)
+- [SKILL.md](../SKILL.md)

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

@@ -0,0 +1,46 @@
+# sql push
+
+将本地同步目录中的 SQL 文件上传到远端，并刷新 `.rabetbase/sql.lock.json`。
+
+> **风险等级：high-risk-write** — 建议先 `--dry-run` 预览；正式执行需 `--yes` 或交互确认。
+
+## 命令
+
+```bash
+rabetbase sql push --format json
+rabetbase sql push --sqlcode 2305f915-dd48cd4c --dry-run --format json
+rabetbase sql push --sqlcode 2305f915-dd48cd4c --yes --format json
+rabetbase sql push --sqlcode 2305f915-dd48cd4c --force --yes --format json
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--sqlcode <code>` | string | 否 | — | 仅推指定 SQL；不传则扫描当前应用同步目录下的全部 SQL |
+| `--force` | boolean | 否 | — | 即使本地 hash 与 lock 一致也强制推送 |
+| `--dry-run` | boolean | 否 | — | 仅预览会推哪些 SQL |
+| `--yes` | boolean | 否 | — | 跳过高风险确认 |
+| `--format <fmt>` | string | 否 | `compress` | 输出格式 |
+
+## 行为说明
+
+- 以 `.rabetbase/sql.lock.json` 为准，读取本地同步目录中的当前文件
+- 上传前会自动剥离 `@lovrabet` 头注释，只把 SQL/XML 正文发到平台
+- 若本地文件名中的 `sqlName` 变化，推送时会同步更新远端 `sqlName`
+- 若本地文件被移动到新的数据库目录，推送时会按目录名重新解析目标 `dbId`
+- 推送成功后会刷新 lock 中的 `hash / path / sqlName / dbId / version`
+
+## 常见失败
+
+- `missing remote version; run rabetbase sql pull to refresh version info first`
+  - 说明 lock 中缺失乐观锁版本号，先执行 `sql pull`
+- `local SQL is not tracked by sql.lock.json`
+  - 说明这不是已同步资产；先执行 `sql create` 或 `sql pull`
+- `Multiple local SQL files found for sqlCode ...`
+  - 说明同一 `sqlCode` 存在多个本地文件，先清理到只剩一份
+
+## 参考
+
+- [SKILL.md](../SKILL.md)
+- [sql-creation-workflow.md](../guides/sql-creation-workflow.md)

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

@@ -0,0 +1,39 @@
+# sql status
+
+检查本地 SQL 同步目录与 `.rabetbase/sql.lock.json` 的状态。
+
+## 命令
+
+```bash
+rabetbase sql status --format json
+rabetbase sql status --remote --format json
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--remote` | boolean | 否 | — | 额外检查远端存在但本地/lock 都没有的 SQL |
+| `--format <fmt>` | string | 否 | `compress` | 输出格式 |
+
+## 输出分类
+
+| 字段 | 含义 |
+|------|------|
+| `added` | 本地同步目录中存在，但 `sql.lock.json` 尚未跟踪 |
+| `modified` | 本地文件 hash、文件名（`sqlName`）、或相对路径与 lock 不一致 |
+| `missing` | lock 中有条目，但本地文件缺失 |
+| `unchanged` | 本地文件与 lock 一致 |
+| `remoteOnly` | 仅在加 `--remote` 时返回：远端存在，但本地和 lock 都没有 |
+
+## 提示
+
+- 修改文件名会被视为 `sqlName` 变更；`sql push` 时会把新文件名回写远端
+- 把文件移动到新的数据库目录，会在 `sql push` 时尝试按目录名重新绑定 `dbId`
+- `status` 只看本地文件与 lock；若要核对远端是否漂移，可结合 `sql pull --dry-run` 或 `sql detail`
+
+## 参考
+
+- [SKILL.md](../SKILL.md)
+- [sql-creation-workflow.md](../guides/sql-creation-workflow.md)
+

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

@@ -0,0 +1,73 @@
+# sql validate
+
+校验普通 SQL 或 MyBatis XML 内容（类型检测、参数提取、危险语句检查），不实际保存。文件格式默认使用 `.sql`；只有内容实际采用 MyBatis XML 语法时才使用 `.xml`。
+
+## 本地路径约定
+
+从文件校验时，优先使用同步目录下的文件：
+
+```text
+.rabetbase/sql/<appCode>/<dbName|db-<id>>/<sqlCode>_<sqlName>.sql|xml
+```
+
+内联 `--sql` 不受此限。
+
+## 命令
+
+```bash
+# 从文件校验
+rabetbase sql validate --file .rabetbase/sql/app-xxxxxxxx/sample_db/2305f915-dd48cd4c_getUserList.sql --format json
+
+# 仅在内容使用 MyBatis XML 语法时选择 .xml
+rabetbase sql validate --file .rabetbase/sql/app-xxxxxxxx/sample_db/2305f915-dd48cd4c_getUserList.xml --format json
+
+# 内联 SQL 校验
+rabetbase sql validate --sql "SELECT * FROM users WHERE id = #{userId}" --format json
+
+# 带 schema 交叉校验
+rabetbase sql validate --file .rabetbase/sql/app-xxxxxxxx/sample_db/report.sql --schemas datasetCode1,datasetCode2 --format json
+
+# 审计顶层 JOIN 的索引匹配
+rabetbase sql validate --file .rabetbase/sql/app-xxxxxxxx/sample_db/report.sql --schemas datasetCode1,datasetCode2 --check-indexes --format json
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--file <path>` | string | 与 sql 二选一 | — | 默认传 `.sql`；MyBatis XML 内容传 `.xml` |
+| `--sql <content>` | string | 与 file 二选一 | — | 内联 SQL 或 MyBatis XML 内容 |
+| `--schemas <codes>` | string | 否 | — | 逗号分隔的 Dataset code 列表，交叉校验表名 |
+| `--check-indexes` | boolean | 否 | `false` | 使用 Dataset 索引元数据审计顶层 JOIN；必须同时传 `--schemas` |
+| `--format <fmt>` | string | 否 | `compress` | 输出格式 |
+
+## 输出
+
+| 字段 | 说明 |
+|------|------|
+| `valid` | 是否通过校验 |
+| `sqlType` | SQL 类型（SELECT / INSERT / UPDATE / DELETE / DDL / UNKNOWN） |
+| `isSelectOnly` | 是否为纯读查询 |
+| `isDangerous` | 是否包含危险操作 |
+| `tables` | 引用的表名列表 |
+| `parameters` | 提取的 `#{param}` / `#{param, jdbcType=...}` / `${param}` 参数名 |
+| `schemaWarnings` | 表名/Dataset 不匹配的警告（仅 `--schemas` 时） |
+| `joinAudit` | JOIN 索引审计结果（仅 `--check-indexes` 时）；不会修改 `valid` |
+
+## 提示
+
+- SQL 保存前建议先用此命令独立校验
+- 普通 SQL 保持 `.sql`；不要因为校验器支持 MyBatis XML 而改成 `.xml`
+- MyBatis XML 会去除组装标签后做保守静态分析，不执行 OGNL、动态分支或集合展开
+- 受 `<if>` / `<choose>` / `<foreach>` 影响的 JOIN 和无法展开的 `<include>` 返回无法判断，不报告确定的索引缺失或覆盖
+- `--schemas` 可交叉检查 SQL 中引用的表是否在指定 dataset 中存在
+- `--check-indexes` 只审计可安全识别的顶层 JOIN 等值条件，不支持时返回无法判断，不猜测缺索引
+- 空索引元数据返回 `INDEX_METADATA_UNAVAILABLE`；静态审计不能替代数据库执行计划
+- `JOIN_INDEX_MISSING` 仅表示非空索引元数据中没有相关字段；`JOIN_INDEX_NOT_USABLE` 表示相关字段不构成完整最左前缀
+- `JOIN_PREDICATE_UNSUPPORTED` 表示 JOIN 方向、目标或谓词不能安全分析；发现这类 JOIN 时 `checked` 仍为 `true`
+- `sql create` 与 `sql push` 的校验复用同一个 `validateSql()` 核心，不可跳过
+
+## 参考
+
+- [SKILL.md](../SKILL.md)
+- [sql-creation-workflow.md](../guides/sql-creation-workflow.md)

package/skills/rabetbase/references/rabetbase-standard-page-status.md

@@ -0,0 +1,31 @@
+# page standard-page-status
+
+查询某个数据集当前智能列表页（Smart List Page）事实快照。
+
+## 命令
+
+```bash
+rabetbase page standard-page-status --datasetcode 097b7361b76c42bcb12b923fa5a08861 --format json
+rabetbase page standard-page-status --alias order --format json
+```
+
+## 行为说明
+
+- 该命令只返回**页面事实**：
+  - 智能列表页组
+  - 是否完整
+  - 残留页
+  - 菜单事实
+- 它不返回异步任务的执行进度，也不负责表达 job 状态。
+- 这是 `page generate-start` 的前置判定与终态回查依据，属于事实接口，不是任务状态接口。
+
+## 适用场景
+
+- 生成前判断是否允许继续 `generate-start`
+- 生成完成后确认是否真的形成完整智能列表页组
+- 排查为什么当前数据集被判定为 `blocked_*`
+
+## 参考
+
+- [rabetbase-page-generate-start.md](rabetbase-page-generate-start.md)
+- [rabetbase-page-generate-status.md](rabetbase-page-generate-status.md)

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

@@ -0,0 +1,40 @@
+# task status
+
+按 `taskId + appCode` 查询平台通用异步任务是否到达终态。该命令不限定业务任务类型。
+
+> **风险等级：read** — 只查询任务，不取消、重启或重提业务请求。
+
+## 命令
+
+```bash
+rabetbase task status --task-id <taskId> --format compress
+```
+
+## Flags
+
+| Flag | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `--task-id <id>` | string | 是 | 异步接口返回的任务 ID |
+| `--appcode <code>` | string | 否 | 任务归属应用；未传时使用当前应用 |
+
+## 输出与决策
+
+| status | `isTerminal` | 动作 |
+|---|---:|---|
+| `PENDING` | `false` | 等待后再查询同一 taskId |
+| `PROCESSING` | `false` | 等待后再查询同一 taskId |
+| `SUCCESS` | `true` | 任务成功；按业务命令的回读步骤验证最终事实 |
+| `FAILED` | `true` | 任务失败；读取 `errorMessage`，不自动重提原业务请求 |
+
+未知 status 返回 `knownStatus=false`，必须人工复核，不推断为成功、失败或终态。
+
+## Agent 编排规则
+
+- `PENDING / PROCESSING` 时执行响应中的 `data.query.command`，始终查询同一个 taskId。
+- 只有 `SUCCESS` 才能按来源业务命令的回读步骤确认最终完成。
+- `FAILED` 时报告 `errorMessage`，不得自动重提来源业务请求。
+- 未知状态进入人工复核，不循环提交来源业务请求。
+
+## 相关命令
+
+- [menu regroup-start](rabetbase-menu-regroup-start.md)

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

@@ -0,0 +1,69 @@
+# rabetbase tenant members-list
+
+按精确 `tenantCode` 列出当前登录账号所属租户的完整人员清单。只读，不要求 App Code。
+
+## 命令
+
+```bash
+rabetbase tenant members-list \
+  --tenant-code tenant-example \
+  --format compress
+```
+
+## 参数
+
+| Flag | 必填 | 说明 |
+|------|------|------|
+| `--tenant-code <code>` | 是 | 精确租户编码；不支持名称猜测 |
+| `--format <compress\|json\|pretty>` | 否 | Agent 优先使用 `compress` |
+
+命令返回全量人员，不提供分页、关键字、状态或角色筛选。
+
+## 安全边界
+
+命令先查询当前账号所属的启用租户关系。只有 `tenantCode` 精确命中时，才继续读取租户人员；未命中会报错，且不请求成员详情。
+
+输出不会包含手机、邮箱、头像、Cookie、Token 或 AccessKey。
+
+## 结构化输出
+
+```json
+{
+  "ok": true,
+  "command": "rabetbase tenant members-list",
+  "risk": "read",
+  "data": {
+    "tenantCode": "tenant-example",
+    "items": [
+      {
+        "userId": 100,
+        "username": "alice",
+        "displayName": "Alice",
+        "role": "ADMIN",
+        "status": "ENABLE"
+      }
+    ],
+    "totalCount": 1
+  }
+}
+```
+
+- `role` 为 `ADMIN` 或 `MEMBER`。
+- 返回服务端目录中的全部状态，包括 `ENABLE` 与 `DISABLE`。
+- `username`、`displayName`、`status` 缺失时为 `null`；不会用 userId 伪造。
+- 结果按 `userId` 升序，同一 userId 只保留一个人员条目。
+
+## 失败路径
+
+- 未登录：先执行 `rabetbase auth login`。
+- 缺少 `--tenant-code`：补充精确租户编码。
+- 租户不属于当前账号：核对编码或切换登录账号；不要尝试枚举其他租户。
+- 租户不存在、网络异常或服务端错误：保留 CLI 结构化错误，不把错误解释为空列表。
+
+合法空租户返回成功，`items: []` 且 `totalCount: 0`。
+
+## 参考
+
+- [应用人员列表](rabetbase-app-members-list.md)
+- [角色查人](rabetbase-role-user-resolve.md)
+- [SKILL.md](../SKILL.md)

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

@@ -0,0 +1,56 @@
+# update
+
+从 npm 更新 rabetbase CLI，并让 CLI 与 Built-in Skill 一体升级。
+
+## 命令策略
+
+- 默认升级入口是 `rabetbase update`。
+- 预览版本使用 `rabetbase update --beta`；精确版本使用 `rabetbase update --version <version>`。
+- 内部发布或故障复现可使用 `npm install -g @lovrabet/rabetbase-cli@<version>`。
+
+## 命令
+
+```bash
+rabetbase update
+rabetbase update --beta
+rabetbase update --version 2.1.8-beta.1
+rabetbase update --help
+```
+
+## 行为
+
+1. 显示当前版本。
+2. 默认解析 npm `latest`；`--beta` 解析 `beta`；`--version` 使用指定完整 semver。
+3. 通过当前包管理器全局安装目标 npm 包。
+4. 新 npm 包的 `postinstall` 调用最新版官方 Skills CLI，以包内本地路径安装同版本 Built-in Skill。
+5. 安装目录由官方 Skills CLI 按已安装 Agent 决定，发起更新的进程验证实际生效路径和版本。
+6. CLI 已是目标版本时，仍以当前 npm 包内文件检查并修复 Skill。
+
+## Flags
+
+| Flag | 说明 |
+|------|------|
+| `--beta` | 安装 npm `beta` dist-tag 指向的版本 |
+| `--version <version>` | 安装指定完整 semver，如 `2.1.8` 或 `2.1.8-beta.1` |
+
+`--beta` 与 `--version` 互斥。CLI 与 Skill 不提供拆分升级模式。
+
+## 前置条件
+
+- CLI 通过 npm 或 bun 全局安装。
+- 能访问 npm registry，以安装 CLI 并获取最新版 `skills` 安装器；Skill 内容仍来自当前 Rabetbase npm 包，不访问外部 Skill 内容源。
+
+## 修复
+
+若 npm 包安装成功但 Skill 校验失败，执行：
+
+```bash
+rabetbase cli-skill install
+rabetbase doctor
+```
+
+如 update 命令本身失败，可精确安装 npm 包；其 `postinstall` 仍会自动安装同版本 Skill：
+
+```bash
+npm install -g @lovrabet/rabetbase-cli@latest
+```

package/skills/rabetbase/references/rabetbase-user-account.md

@@ -0,0 +1,45 @@
+# rabetbase user-account
+
+绑定当前已登录的 Lovrabet 平台用户与钉钉沙箱用户账号。该能力只处理显式提供的钉钉沙箱用户 ID，不负责打开登录流程或自动获取 ID。
+
+## 命令
+
+先预览：
+
+```bash
+rabetbase user-account dingding-sandbox-bind \
+  --ding-talk-user-id <id> \
+  --dry-run \
+  --format compress
+```
+
+确认 ID 后正式绑定：
+
+```bash
+rabetbase user-account dingding-sandbox-bind \
+  --ding-talk-user-id <id> \
+  --yes \
+  --format compress
+```
+
+该命令不需要 `appCode`，但必须使用当前有效的登录 Cookie。不要传入平台 `userId`、`providerId` 或应用编码。
+
+## 输出确认
+
+重点检查以下字段：
+
+- `data.operation = "bind"`
+- `data.selector.providerId = "dingding-sandbox"`
+- `data.selector.dingTalkUserId` 与输入一致
+- 正式执行成功时 `data.after.bound = true`
+- `data.dryRun` 与本次执行模式一致
+
+`before: null` 表示服务端当前没有提供旧绑定查询能力，不代表旧绑定不存在。只有接口明确返回 `data: true` 时，才可将正式绑定视为成功。
+
+## 失败与恢复
+
+- `--ding-talk-user-id` 缺失或只包含空白字符时，CLI 在发起请求前拒绝执行。
+- 登录态无效时，先执行 `rabetbase auth login`，再重新确认目标钉钉用户 ID。
+- 网络超时或响应丢失时，结果可能不确定，不得自动重试。
+- 人工确认登录态和目标 ID 后，只能使用相同的 `--ding-talk-user-id` 显式重试，避免误绑到其他账号。
+- 当前命令不提供绑定查询或解绑能力；需要确认既有绑定时，应通过平台现有查询渠道核实。

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

@@ -0,0 +1,60 @@
+# rabetbase workspace
+
+配置当前工作环境使用哪些 Lovrabet 应用。它是面向工作空间的推荐入口，一切「改我的配置」的写操作都在这里。
+
+> **边界**：`workspace` 负责所有「配置我的工作环境」的写操作——绑定目录默认应用（`init` / `use`），以及登记/移除应用清单（`add` / `remove`）。默认写当前项目 `.rabetbase.json`；`add` / `remove` 支持 `--global`（全局视作一个大工作空间）；`init` / `use` 只写当前目录。纯事实查询「有哪些 app」用 [`app list`](rabetbase-app-list.md)。
+
+**选型**：首次安装全局引导用 `rabetbase init`；当前目录还没绑定默认 app → `workspace init`（始终写 `defaultApp`）；已有配置只再登记 profile → `workspace add`；切换默认 → `workspace use`。
+
+## 命令
+
+```bash
+rabetbase workspace init --appcode <code> [--env daily|production]
+rabetbase workspace init --app <name> --appcode <code>
+rabetbase workspace use --app <name>
+rabetbase workspace use --app <name> --appcode <code>
+rabetbase workspace add <name> --appcode <code> [--global]
+rabetbase workspace remove <name> [--global]
+```
+
+## 参数
+
+| Flag | 说明 |
+|------|------|
+| `--app <name>` | 工作空间里的应用名，如 `crm`、`order` |
+| `--appcode <code>` | 应用 App Code；不知道本地应用名时可直接使用 |
+| `--env <env>` | 写入该 app profile 的环境：`daily` / `production` |
+| `--apiDir <dir>` | 写入该 app profile 的 API 目录 |
+| `--defaultFormat <format>` | 写入该 app profile 的默认输出格式 |
+| `--pageSize <n>` | 写入该 app profile 的分页大小 |
+| `--riskLevel <level>` | 写入该 app profile 的风险等级 |
+| `--locale <locale>` | 写入该 app profile 的地区设置 |
+
+`add` / `remove` 用位置参数 `<name>` 指定应用名；`add` 必带 `--appcode <code>`，两者都支持 `--global`（写/删全局清单，全局视作一个大工作空间），其余 profile flags 与上表一致。
+
+## 行为
+
+- `workspace init --appcode app-xxx`：用 appcode 作为应用名，写入 `apps.app-xxx` 和 `defaultApp`。
+- `workspace init --app crm --appcode app-xxx`：用业务名 `crm` 绑定 appcode，写入 `apps.crm` 和 `defaultApp`。
+- `workspace use --app crm`：切换当前目录默认应用；如果 `crm` 只存在于全局配置，会复制非敏感 profile 字段到当前目录。
+- `workspace use --app crm --appcode app-xxx`：直接在当前目录新增或更新 `crm`，并设为默认应用。
+- `workspace add crm --appcode app-xxx`：登记应用 profile（默认写当前项目，`--global` 写全局）；当前无 `defaultApp` 时首个自动设为默认。已存在则更新。
+- `workspace remove crm`：移除本地应用 profile。默认按「项目优先、其次全局」定位要删的那一层，`--global` 强制删全局；若删的是当前 `defaultApp`，自动切到剩余的第一个；若该应用在项目与全局都有定义，只删单侧并在结果里提示另一侧仍存在。
+
+`workspace init` / `workspace use` 不会从全局配置复制 `cookie` / `accessKey` 到项目文件。若当前项目文件里原本已有这些字段，更新应用时会保留它们。
+
+## 输出
+
+结构化输出会包含：
+
+- `data.operation`：`workspace.init` 或 `workspace.use`
+- `data.configPath`：实际写入的配置文件
+- `data.app` / `data.appcode`
+- `data.credentialsWritten`：固定表示本命令是否写入凭证
+
+`add` / `remove` 返回单行 `message`（如 `Added app "crm" ...` / `Removed app "crm" ...`），移除时若涉及默认应用切换或另一侧仍有定义会在同一 `message` 里说明。
+
+## 参考
+
+- [rabetbase app list](rabetbase-app-list.md) — 查看本地或平台应用列表（只读事实）
+- [`.rabetbase.json` 配置参考](rabetbase-config.md) — 配置文件结构