@fectivnfy112358/minimax-code-web 0.1.0-preview.0 → 0.1.0-preview.3

package/server/assets/skills/lark-tools/cli-skills/lark-base/references/lark-base-record-search.md

@@ -0,0 +1,72 @@
+# base +record-search
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+按关键词检索记录；CLI 侧通过 `--json` 透传请求体。
+
+## 适用场景
+
+- 需要关键词检索记录。
+- 用户已提供明确搜索关键词（`keyword`）。
+- 需要附带 `view_id / select_fields` 控制检索范围与返回字段。
+- 不用于聚合统计。涉及 SUM/AVG/COUNT/MAX/MIN 时改用 `+data-query`。
+
+## 推荐命令
+
+```bash
+lark-cli base +record-search \
+  --base-token XXXXXX \
+  --table-id tblXXX \
+  --json '{"keyword":"Created","search_fields":["Title","fld_owner"],"offset":0,"limit":100}'
+
+lark-cli base +record-search \
+  --base-token XXXXXX \
+  --table-id tblXXX \
+  --json '{"view_id":"vewXXX","keyword":"Alice","search_fields":["Title","Owner"],"select_fields":["Title","Owner","Status"],"offset":0,"limit":50}'
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | Base Token |
+| `--table-id <id_or_name>` | 是 | 表 ID 或表名 |
+| `--json <object>` | 是 | 搜索请求体 JSON（结构要求见下方“JSON 要求”） |
+
+## 返回关键字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `query_context.record_scope` | string | 记录范围：`all_records`（全表）/ `view_filtered_records`（按 `view_id` 限定到视图记录） |
+| `query_context.field_scope` | string | 字段范围：`selected_fields`（显式传 `select_fields`）/ `view_visible_fields`（未传 `select_fields` 且按视图可见字段）/ `all_fields`（未传 `select_fields` 且无视图限制） |
+| `query_context.search_scope` | string | 实际参与搜索的字段集合，格式类似 `fieldTitle(Title), fieldOwner(Owner)` |
+
+## API 入参详情
+
+**HTTP 方法和路径：**
+
+```http
+POST /open-apis/base/v3/bases/:base_token/tables/:table_id/records/search
+```
+
+### JSON 格式要求
+
+| 字段 | 必填 | 类型 | 约束 |
+|------|------|------|------|
+| `view_id` | 否 | string | 传入后仅在该视图范围内搜索，并默认按该视图可见字段返回结果 |
+| `keyword` | 是 | string | 非空，最小长度 `1` |
+| `search_fields` | 是 | string[] | 数组长度 `1-20`；每项是字段 `field_id` 或字段名，代表在这些字段中做关键词搜索 |
+| `select_fields` | 否 | string[] | 数组长度 `<=50`；每项是字段 `field_id` 或字段名 |
+| `offset` | 否 | int | `>=0`，默认 `0` |
+| `limit` | 否 | int | `1-200`，默认 `10` |
+
+## 坑点
+
+- ⚠️ `+record-search` 用于检索，不用于聚合分析；聚合场景使用 `+data-query`。
+- ⚠️ 部分字段不支持搜索（例如 `attachment`、`link`）；传入后通常不会报错，但可能导致无法命中对应记录。
+
+## 参考
+
+- [lark-base-record.md](lark-base-record.md) — record 索引页
+- [lark-base-record-list.md](lark-base-record-list.md) — 分页列表读取
+- [lark-base-data-query.md](lark-base-data-query.md) — 聚合分析

package/server/assets/skills/lark-tools/cli-skills/lark-base/references/lark-base-record-upload-attachment.md

@@ -0,0 +1,51 @@
+# base +record-upload-attachment
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+上传本地文件到当前 Base，并把附件值写入指定记录的附件字段。
+
+## 推荐命令
+
+```bash
+lark-cli base +record-upload-attachment \
+  --base-token app_xxx \
+  --table-id tbl_xxx \
+  --record-id rec_xxx \
+  --field-id fld_attach \
+  --file ./report.pdf
+
+lark-cli base +record-upload-attachment \
+  --base-token app_xxx \
+  --table-id tbl_xxx \
+  --record-id rec_xxx \
+  --field-id "附件" \
+  --file ./report.pdf \
+  --name "Q1-final.pdf"
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | Base Token |
+| `--table-id <id_or_name>` | 是 | 表 ID 或表名 |
+| `--record-id <id>` | 是 | 记录 ID |
+| `--field-id <id_or_name>` | 是 | 附件字段 ID 或字段名 |
+| `--file <path>` | 是 | 本地文件路径，最大 2GB |
+| `--name <name>` | 否 | 写入附件字段时显示的文件名，默认使用本地文件名 |
+
+
+## 工作流
+
+> [!CAUTION]
+> 这是写入操作。用户已经明确要上传到某条记录的某个附件字段时可直接执行；如果 `record-id` 或目标字段仍有歧义，再先确认。
+
+## 坑点
+
+- ⚠️ 目标字段必须是 `attachment` 字段。
+- ⚠️ 记录里的附件 `file_token` 属于 Drive media token；下载时不要走 `lark-cli drive +download`，应使用 `lark-cli docs +media-download --token <file_token> --output <path>`。
+
+## 参考
+
+- [lark-base-record.md](lark-base-record.md) — record 索引页
+- [lark-base-shortcut-record-value.md](lark-base-shortcut-record-value.md) — 记录值格式详解

package/server/assets/skills/lark-tools/cli-skills/lark-base/references/lark-base-record-upsert.md

@@ -0,0 +1,89 @@
+# base +record-upsert
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+创建记录，或在带 `--record-id` 时更新记录。
+
+## 推荐命令
+
+```bash
+lark-cli base +record-upsert \
+  --base-token app_xxx \
+  --table-id tbl_xxx \
+  --json '{"项目名称":"Apollo","状态":"进行中"}' 
+
+lark-cli base +record-upsert \
+  --base-token app_xxx \
+  --table-id tbl_xxx \
+  --record-id rec_xxx \
+  --json '{"项目名称":"Apollo","状态":"进行中","标签":["高优","外部依赖"],"截止日期":"2026-03-24 10:00:00"}'
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | Base Token |
+| `--table-id <id_or_name>` | 是 | 表 ID 或表名 |
+| `--record-id <id>` | 否 | 传入时走更新，不传时走创建 |
+| `--json <body>` | 是 | 记录 JSON 对象 |
+
+## API 入参详情
+
+**HTTP 方法和路径：**
+
+```
+POST /open-apis/base/v3/bases/:base_token/tables/:table_id/records
+```
+
+- 带 `--record-id` 时内部改走 `PATCH /records/:record_id`。
+
+## JSON 值规范
+
+- `--json` 必须是 **JSON 对象**。
+- key 可用字段名或字段 ID，但一次请求里同一字段只用一种标识，避免重复写入冲突。
+- value 必须匹配字段类型；先 `+field-list` 再构造值。
+- 推荐值形状（常用）：
+  - 文本：`"标题"`
+  - 数字：`12.5`
+  - 单选：`"Todo"`
+  - 多选：`["A","B"]`
+  - 复选框：`true`
+  - 人员：`[{"id":"ou_xxx"}]`
+  - 关联记录：`[{"id":"rec_xxx"}]`
+  - 日期：`"YYYY-MM-DD HH:mm:ss"`（如 `"2026-03-24 10:00:00"`）
+- 需要清空字段时优先传 `null`（字段允许清空时）。
+- 公式、查找引用、创建/更新时间、创建/修改人等只读字段不要写入。
+
+**正确（base +record-upsert）**
+
+```json
+{
+  "项目名称": "Apollo",
+  "状态": "进行中",
+  "标签": ["高优", "外部依赖"],
+  "负责人": [{ "id": "ou_xxx" }],
+  "截止日期": "2026-03-24 10:00:00"
+}
+```
+
+## 返回重点
+
+- 创建时返回 `record` 和 `created: true`。
+- 更新时返回 `record` 和 `updated: true`。
+
+## 工作流
+
+
+1. 先确定是新增还是修改。
+
+## 坑点
+
+- ⚠️ `--json` 必须是对象，不支持数组。
+- ⚠️ 有 `--record-id` 就一定走更新；不传就一定走创建，不会自动查重。
+- ⚠️ 这是写入操作，执行前必须确认。
+
+## 参考
+
+- [lark-base-record.md](lark-base-record.md) — record 索引页
+- [lark-base-shortcut-record-value.md](lark-base-shortcut-record-value.md) — shortcut 记录值格式规范（推荐）

package/server/assets/skills/lark-tools/cli-skills/lark-base/references/lark-base-record.md

@@ -0,0 +1,28 @@
+# base record shortcuts
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+record 相关命令索引。
+
+## 命令导航
+
+| 文档 | 命令 | 说明 |
+|------|------|------|
+| [lark-base-record-search.md](lark-base-record-search.md) | `+record-search` | 按关键词和字段范围检索记录 |
+| [lark-base-record-list.md](lark-base-record-list.md) | `+record-list` | 分页列记录 |
+| [lark-base-record-get.md](lark-base-record-get.md) | `+record-get` | 获取单条记录 |
+| [lark-base-record-upsert.md](lark-base-record-upsert.md) | `+record-upsert` | 创建或更新记录 |
+| [lark-base-record-batch-create.md](lark-base-record-batch-create.md) | `+record-batch-create` | 按 `fields/rows` 批量创建记录 |
+| [lark-base-record-batch-update.md](lark-base-record-batch-update.md) | `+record-batch-update` | 批量更新记录 |
+| [lark-base-record-upload-attachment.md](lark-base-record-upload-attachment.md) | `+record-upload-attachment` | 上传本地文件到附件字段并更新记录 |
+| [`../../lark-doc/references/lark-doc-media-download.md`](../../lark-doc/references/lark-doc-media-download.md) | `lark-cli docs +media-download` | 下载 Base 附件到本地（附件的 `file_token` 来自 `+record-get` 的附件字段） |
+| [lark-base-record-delete.md](lark-base-record-delete.md) | `+record-delete` | 删除记录 |
+
+## 说明
+
+- 聚合页只保留目录职责；每个命令的详细说明请进入对应单命令文档。
+- 所有 `+xxx-list` 调用都必须串行执行；若要批量跑多个 list 请求，只能串行执行。
+- `+record-list` 支持重复传参 `--field-id` 做字段筛选。
+- 写记录 JSON 前优先阅读 [lark-base-shortcut-record-value.md](lark-base-shortcut-record-value.md)。
+- 本地文件写入附件字段时，必须使用 `+record-upload-attachment`。
+- 从附件字段下载文件时，用 `lark-cli docs +media-download --token <file_token> --output <path>`，用法见 [`../../lark-doc/references/lark-doc-media-download.md`](../../lark-doc/references/lark-doc-media-download.md)。

package/server/assets/skills/lark-tools/cli-skills/lark-base/references/lark-base-role-create.md

@@ -0,0 +1,89 @@
+# base +role-create
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+> 
+> **前置条件：** 需要base开启了高级权限，如果调用这个接口返回没有开启高级权限，可以参考 [`lark-base-advperm-enable.md`](lark-base-advperm-enable.md) 了解高级权限启用规则。
+
+在指定 Base 中创建一个自定义角色，需传入完整的 AdvPermBaseRoleConfig 作为角色配置。
+
+## 推荐命令
+
+```bash
+# 创建简单角色（仅设置名称和类型）
+lark-cli base +role-create \
+  --base-token VwGhb**************fMnod \
+  --json '{"role_name":"财务审核员","role_type":"custom_role"}'
+
+# 创建角色并配置表权限、字段权限、记录筛选
+lark-cli base +role-create \
+  --base-token VwGhb**************fMnod \
+  --json '{"role_name":"财务审核员","role_type":"custom_role","base_rule_map":{"copy":false,"download":false},"table_rule_map":{"订单表":{"perm":"edit","record_rule":{"record_operations":["add"],"edit_filter_rule_group":{"conjunction":"and","filter_rules":[{"conjunction":"and","filters":[{"field_name":"部门","operator":"is","filter_values":["财务部"]}]}]},"other_record_all_read":true},"field_rule":{"field_perm_mode":"specify","field_perms":{"金额":"edit","备注":"read","密码":"no_perm"}}},"用户表":{"perm":"read_only"}},"dashboard_rule_map":{"销售看板":{"perm":"read_only"}}}'
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | Base Token，27 位字母数字字符串 |
+| `--json <body>` | 是 | AdvPermBaseRoleConfig JSON，包含角色名称、类型、权限配置 |
+
+## API 入参详情
+
+**HTTP 方法和路径：**
+
+```
+POST /open-apis/base/v3/bases/:base_token/roles
+```
+
+**Path 参数：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `base_token` | 是 | Base 的唯一标识，27 位字母数字字符串 |
+
+**Request Body（JSON — AdvPermBaseRoleConfig）：**
+
+> 完整的权限配置结构详见 [role-config.md](role-config.md)
+
+## API 出参详情
+
+**Response：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `code` | int32 | 错误码，0 表示成功 |
+| `message` | string | 错误信息 |
+| `data` | string | 创建成功时为空 |
+
+## 返回值
+
+命令成功后输出 JSON：
+
+```json
+{
+  "ok": true,
+  "data": {
+    "success": true
+  }
+}
+```
+
+## 工作流
+
+
+1. 向用户确认 `--base-token` 和角色配置 JSON
+2. 执行命令
+3. 确认返回 `code: 0` 表示创建成功
+
+## 坑点
+
+- ⚠️ **role_type 必须为 custom_role**：创建接口仅支持 `custom_role`，传其他值会报业务错误
+- ⚠️ **API 路径版本**：本接口使用 `base/v3`，路径必须从原始文档提取，不要用 WebSearch 补全
+- ⚠️ **data 字段是 JSON 字符串**：响应中 `data` 是 string 类型（非 object），需要双重解析
+- ⚠️ **Filter 字段**：`field_name`、`operator`、`filter_values` 由客户端传入，`field_type`、`field_ui_type`、`reference_type` 由服务端 filterFiller 自动补全
+- ⚠️ **前置条件**：Base 必须已开启高级权限，操作用户必须为 Base 管理员
+
+## 参考
+
+- [lark-base](../SKILL.md) — 多维表格全部命令
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

package/server/assets/skills/lark-tools/cli-skills/lark-base/references/lark-base-role-delete.md

@@ -0,0 +1,83 @@
+# base +role-delete
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+>
+> **前置条件：** 需要base开启了高级权限，如果调用这个接口返回没有开启高级权限，可以参考 [`lark-base-advperm-enable.md`](lark-base-advperm-enable.md) 了解高级权限启用规则。
+
+删除指定的自定义角色。系统角色（editor / reader）不可删除。
+
+## 推荐命令
+
+```bash
+lark-cli base +role-delete \
+  --base-token VwGhb**************fMnod \
+  --role-id rolxxxxxx4
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | Base Token，27 位字母数字字符串 |
+| `--role-id <id>` | 是 | 角色 ID，格式 `rol` + 8 位字母数字 |
+
+## API 入参详情
+
+**HTTP 方法和路径：**
+
+```
+DELETE /open-apis/base/v3/bases/:base_token/roles/:role_id
+```
+
+**Path 参数：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `base_token` | 是 | Base 的唯一标识 |
+| `role_id` | 是 | 角色 ID |
+
+无 Query 参数，无 Request Body。
+
+## API 出参详情
+
+**Response：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `code` | int32 | 错误码，0 表示成功 |
+| `message` | string | 错误信息 |
+| `data` | string | 删除成功时为空 |
+
+## 返回值
+
+命令成功后输出 JSON：
+
+```json
+{
+  "ok": true,
+  "data": {
+    "success": true
+  }
+}
+```
+
+## 工作流
+
+> [!CAUTION]
+> 这是**高风险不可逆操作** — 删除后无法恢复，执行前必须向用户二次确认。
+
+1. 建议先用 `+role-list` 确认角色存在
+2. 向用户确认 `--base-token` 和 `--role-id`
+3. 执行命令
+4. 确认返回 `code: 0`
+
+## 坑点
+
+- ⚠️ **仅支持删除自定义角色**：系统角色（editor / reader）不可删除，会报业务错误
+- ⚠️ **不可逆操作**：删除后角色及其关联的成员配置无法恢复
+- ⚠️ **role_id 来源**：可通过 `+role-list` 获取，格式为 `rol` + 8 位字母数字
+
+## 参考
+
+- [lark-base](../SKILL.md) — 多维表格全部命令
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

package/server/assets/skills/lark-tools/cli-skills/lark-base/references/lark-base-role-get.md

@@ -0,0 +1,87 @@
+# base +role-get
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+>
+> **前置条件：** 需要base开启了高级权限，如果调用这个接口返回没有开启高级权限，可以参考 [`lark-base-advperm-enable.md`](lark-base-advperm-enable.md) 了解高级权限启用规则。
+
+获取指定角色的完整配置详情（AdvPermBaseRole），包含表权限、字段权限、记录筛选等全量配置。
+
+## 推荐命令
+
+```bash
+lark-cli base +role-get \
+  --base-token VwGhb**************fMnod \
+  --role-id rolxxxxxx4
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | Base Token，27 位字母数字字符串 |
+| `--role-id <id>` | 是 | 角色 ID，格式 `rol` + 8 位字母数字 |
+| `--format <fmt>` | 否 | 输出格式：json / pretty / table / csv / ndjson |
+
+## API 入参详情
+
+**HTTP 方法和路径：**
+
+```
+GET /open-apis/base/v3/bases/:base_token/roles/:role_id
+```
+
+**Path 参数：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `base_token` | 是 | Base 的唯一标识 |
+| `role_id` | 是 | 角色 ID |
+
+无 Query 参数，无 Request Body。
+
+## API 出参详情
+
+**Response `data` 字段（JSON 字符串，需双重解析）：**
+
+完整的 AdvPermBaseRole 对象（结构详见 [role-config.md](role-config.md)）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `role_id` | string | 角色 ID |
+| `role_name` | string | 角色名称 |
+| `role_type` | string | 角色类型 |
+| `base_rule_map` | map\<string, bool\> | Base 级权限（copy/download） |
+| `table_rule_map` | map\<string, TableRule\> | 数据表权限配置 |
+| `dashboard_rule_map` | map\<string, DashboardRule\> | 仪表盘权限配置 |
+| `docx_rule_map` | map\<string, DocxRule\> | 文档权限配置 |
+
+## 返回值
+
+命令成功后输出完整角色配置 JSON：
+
+```json
+{
+  "ok": true,
+  "data": {
+    "role_id": "rolxxxxxx4",
+    "role_name": "财务审核员",
+    "role_type": "custom_role",
+    "base_rule_map": {"copy": false, "download": false},
+    "table_rule_map": {
+      "订单表": {"perm": "edit", "record_rule": {...}, "field_rule": {...}},
+      "用户表": {"perm": "read_only"}
+    }
+  }
+}
+```
+
+## 坑点
+
+- ⚠️ **与 +role-list 的区别**：`+role-list` 只返回摘要（role_id/name/type），`+role-get` 返回完整的权限配置
+- ⚠️ **data 是 JSON 字符串**：响应 `data` 是 string 类型，需要双重解析
+- ⚠️ **角色不存在时**：data 为空字符串，不会报错
+
+## 参考
+
+- [lark-base](../SKILL.md) — 多维表格全部命令
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

package/server/assets/skills/lark-tools/cli-skills/lark-base/references/lark-base-role-list.md

@@ -0,0 +1,81 @@
+# base +role-list
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+>
+> **前置条件：** 需要base开启了高级权限，如果调用这个接口返回没有开启高级权限，可以参考 [`lark-base-advperm-enable.md`](lark-base-advperm-enable.md) 了解高级权限启用规则。。
+
+获取指定 Base 下所有角色的摘要信息列表（包括系统角色和自定义角色），返回 role_id / role_name / role_type。
+
+## 推荐命令
+
+```bash
+lark-cli base +role-list --base-token VwGhb**************fMnod
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | Base Token，27 位字母数字字符串 |
+| `--format <fmt>` | 否 | 输出格式：json / pretty / table / csv / ndjson |
+
+## API 入参详情
+
+**HTTP 方法和路径：**
+
+```
+GET /open-apis/base/v3/bases/:base_token/roles
+```
+
+**Path 参数：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `base_token` | 是 | Base 的唯一标识 |
+
+无 Query 参数，无 Request Body。
+
+## API 出参详情
+
+**Response `data` 字段（JSON 字符串，需双重解析）：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `base_roles` | []string | AIBaseRoleRef 的 JSON 字符串数组 |
+| `total` | int32 | 角色总数 |
+
+**AIBaseRoleRef 结构：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `role_id` | string | 角色 ID，如 `rolxxxxxx1` |
+| `role_name` | string | 角色名称 |
+| `role_type` | string | 角色类型：`editor` / `reader` / `custom_role` |
+
+## 返回值
+
+命令成功后输出 JSON：
+
+```json
+{
+  "ok": true,
+  "data": {
+    "base_roles": [
+      "{\"role_id\":\"rolxxxxxx1\",\"role_name\":\"技术管理员\",\"role_type\":\"custom_role\"}",
+      "{\"role_id\":\"rolxxxxxx2\",\"role_name\":\"编辑者\",\"role_type\":\"editor\"}"
+    ],
+    "total": 4
+  }
+}
+```
+
+## 坑点
+
+- ⚠️ **data 是 JSON 字符串**：响应 `data` 是 string 类型，内部 `base_roles` 数组的每个元素也是 JSON 字符串，需要多层解析
+- ⚠️ **返回摘要信息**：此接口只返回 role_id / role_name / role_type，不含完整权限配置。要获取完整配置请用 `+role-get`
+- ⚠️ **包含系统角色**：返回结果包含  editor / reader 两个系统角色
+
+## 参考
+
+- [lark-base](../SKILL.md) — 多维表格全部命令
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

package/server/assets/skills/lark-tools/cli-skills/lark-base/references/lark-base-role-update.md

@@ -0,0 +1,94 @@
+# base +role-update
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+>
+> **前置条件：** 需要base开启了高级权限，如果调用这个接口返回没有开启高级权限，可以参考 [`lark-base-advperm-enable.md`](lark-base-advperm-enable.md) 了解高级权限启用规则。
+
+更新指定角色的权限配置。
+
+## 推荐命令
+
+```bash
+# 仅修改角色名称
+lark-cli base +role-update \
+  --base-token VwGhb**************fMnod \
+  --role-id rolxxxxxx4 \
+  --json '{"role_name":"高级审核员","role_type":"custom_role"}'
+
+# 修改某个表的权限（其他表不受影响）
+lark-cli base +role-update \
+  --base-token VwGhb**************fMnod \
+  --role-id rolxxxxxx4 \
+  --json '{"role_name":"财务审核员","role_type":"custom_role","table_rule_map":{"订单表":{"perm":"read_only"}}}'
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | Base Token，27 位字母数字字符串 |
+| `--role-id <id>` | 是 | 角色 ID，格式 `rol` + 8 位字母数字 |
+| `--json <body>` | 是 | 增量 AdvPermBaseRoleConfig JSON，仅含需变更的字段 |
+
+## API 入参详情
+
+**HTTP 方法和路径：**
+
+```
+PUT /open-apis/base/v3/bases/:base_token/roles/:role_id
+```
+
+**Path 参数：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `base_token` | 是 | Base 的唯一标识 |
+| `role_id` | 是 | 角色 ID |
+
+**Request Body（JSON — 增量 AdvPermBaseRoleConfig）：**
+
+> 完整的权限配置结构详见 [role-config.md](role-config.md)，**更新时需要在原始配置上修改，传入的role配置信息尽量完整**。
+
+## API 出参详情
+
+**Response：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `code` | int32 | 错误码，0 表示成功 |
+| `message` | string | 错误信息 |
+| `data` | string | 更新成功时为空 |
+
+## 返回值
+
+命令成功后输出 JSON：
+
+```json
+{
+  "ok": true,
+  "data": {
+    "success": true
+  }
+}
+```
+
+## 工作流
+
+> [!CAUTION]
+> 这是**高危写入操作** — 执行前必须向用户确认，需要 `--yes` 标志。
+
+1. 建议先用 `+role-get` 获取当前配置，确认变更范围
+2. 向用户确认 `--base-token`、`--role-id` 和变更 JSON，对于变化的部分可以高亮提示用户
+3. 执行命令
+4. 确认返回 `code: 0`
+
+## 坑点
+
+- ⚠️ **Delta Merge 语义**：仅传入需变更的字段即可，未传入的保持不变。例如只传 `table_rule_map` 中某个表的 perm，其他表不受影响
+- ⚠️ **role_name 和 role_type 必填**：即使不修改也必须传入当前值
+- ⚠️ **body 不能为 nil**：PUT 请求必须传 body，否则服务端返回错误
+
+## 参考
+
+- [lark-base](../SKILL.md) — 多维表格全部命令
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数