@wagemule/daemon 0.1.0 → 0.1.3

package/dist/skills/larksuite/lark-base/references/lark-base-record-history-list.md

@@ -0,0 +1,86 @@
+# base +record-history-list
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+查询指定记录的变更历史。当前可执行命令为 `+record-history-list`，无 `+history-list` 别名。
+
+## 推荐命令
+
+```bash
+# 查询最新一页历史
+lark-cli base +record-history-list \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --record-id <record_id>
+
+# 指定分页大小，带游标翻页
+lark-cli base +record-history-list \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --record-id <record_id> \
+  --page-size 30 \
+  --max-version 123456
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | Base Token |
+| `--table-id <id_or_name>` | 是 | 表 ID |
+| `--record-id <id>` | 是 | 记录 ID |
+| `--page-size <n>` | 否 | 每页条数，默认 `30`，最大 `50` |
+| `--max-version <n>` | 否 | 翻页游标，取上一页返回的 `next_max_version` 值 |
+
+## API 入参详情
+
+**HTTP 方法和路径：**
+
+```
+GET /open-apis/base/v3/bases/:base_token/record_history
+```
+
+- Query 参数：`table_id`、`record_id`、`page_size`、`max_version`。
+
+## 返回重点
+
+- 返回记录历史条目列表（按版本号降序，最新在前），而不是记录当前值。
+- 每条历史包含：版本号(`rev`)、操作人(`operator`)、操作时间(`create_time`，**秒级** Unix 时间戳)、操作类型(`activity_type`)、字段变更列表(`field_changes`)。
+- 字段变更包含：字段 ID、字段名、字段类型、变更前值(`before`)、变更后值(`after`)。
+- 适合定位谁改了这条记录、什么时候改的、改了哪些字段。
+
+### activity_type 取值
+
+| 值 | 含义 |
+|------|------|
+| `create` | 记录创建 |
+| `update` | 记录编辑 |
+| `delete` | 记录删除 |
+
+### 不出现在历史中的字段类型
+
+以下字段类型的变更**不会**出现在 `field_changes` 中：
+- **计算字段**：公式(formula)、查找引用(lookup)
+- **系统字段**：自动编号、创建时间、创建人、修改时间、修改人
+
+## 翻页工作流
+
+1. **首次请求**：不传 `--max-version`，获取最新一页。
+2. **判断是否有下一页**：检查返回的 `has_more` 字段。
+3. **翻页**：若 `has_more = true`，取返回的 `next_max_version` 值，传入下一次请求的 `--max-version`。
+4. **终止**：当 `has_more = false` 时停止。
+
+## 工作流
+
+1. 先确认 `table-id` 和 `record-id` 都来自同一张表。
+2. 先查最新一页，再按翻页工作流向前翻页。
+
+## 坑点
+
+- ⚠️ `+record-history-list` 属于 `+xxx-list`，禁止并发调用；批量执行时只能串行。
+- ⚠️ 当前不支持整表历史扫描，只支持单条记录历史。
+
+## 参考
+
+- [lark-base-history.md](lark-base-history.md) — history 索引页
+- [lark-base-record.md](lark-base-record.md) — record 索引页

package/dist/skills/larksuite/lark-base/references/lark-base-record-share-link-create.md

@@ -0,0 +1,72 @@
+# base +record-share-link-create
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+为一条或多条记录生成分享链接（单次调用最多传入 100 条，内部调用批量接口）。
+
+## 推荐命令
+
+```bash
+# 单条记录
+lark-cli base +record-share-link-create \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --record-ids <record_id>
+
+# 多条记录（使用 "," 分隔）
+lark-cli base +record-share-link-create \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --record-ids rec001,rec002,rec003
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | Base Token |
+| `--table-id <id>` | 是 | 表 ID |
+| `--record-ids <ids...>` | 是 | 记录 ID 列表，逗号分隔或重复使用该标志，最多 100 条 |
+
+## API 入参详情
+
+**HTTP 方法和路径：**
+
+```http
+POST /open-apis/base/v3/bases/:base_token/tables/:table_id/records/share_links/batch
+```
+
+**请求体：**
+
+```json
+{
+  "record_ids": ["rec001", "rec002", "rec003"]
+}
+```
+
+> CLI 会自动对 `--record-ids` 去重后再调用接口。
+
+## 返回重点
+
+- 成功时直接返回接口 `data` 字段内容，包含 `record_share_links` 映射（key 为 record_id，value 为分享链接）。结构如下：
+
+```json
+{
+  "record_share_links": {
+    "rec001": "https://example.feishu.cn/record/TW2wrdbkoeoYXYcwvyIczJ2ZnFb"
+  }
+}
+```
+
+- 若部分记录 ID 无权限/不存在，则 `record_share_links` 中只会包含有效记录对应的分享链接
+- 若全部记录 ID 都无权限/不存在，则会返回错误信息 `records do not exist or no read permission`
+
+## 坑点
+
+- ⚠️ 单次最多 100 条记录，超出会被 CLI 校验拦截。
+- ⚠️ 重复的 record_id 会在调用前自动去重。
+- ⚠️ `--record-ids` 为空时会被校验拦截。
+
+## 参考
+
+- [lark-base-record.md](lark-base-record.md) — record 索引页

package/dist/skills/larksuite/lark-base/references/lark-base-record-upload-attachment.md

@@ -0,0 +1,50 @@
+# base +record-upload-attachment
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+上传本地文件到当前 Base，并把附件值写入指定记录的附件字段。
+
+## 推荐命令
+
+```bash
+lark-cli base +record-upload-attachment \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --record-id <record_id> \
+  --field-id <field_id> \
+  --file ./report.pdf
+
+lark-cli base +record-upload-attachment \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --record-id <record_id> \
+  --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 索引页

package/dist/skills/larksuite/lark-base/references/lark-base-record-upsert.md

@@ -0,0 +1,64 @@
+# base +record-upsert
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+创建记录，或在带 `--record-id` 时更新记录。
+
+## 推荐命令
+
+```bash
+# 创建记录
+lark-cli base +record-upsert --base-token <base_token> --table-id <table_id> \
+  --json '{"项目名称":"Apollo","状态":"进行中"}'
+
+# 更新记录
+lark-cli base +record-upsert --base-token <base_token> --table-id <table_id> --record-id <record_id> \
+  --json '{"项目名称":"Apollo","状态":"完成","完成时间":"2026-03-24 10:00:00"}'
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | Base Token |
+| `--table-id <id_or_name>` | 是 | 表 ID 或表名 |
+| `--record-id <id>` | 否 | 传入时走更新，不传时走创建 |
+| `--json <body>` | 是 | 字段写入对象，类型 `Map<FieldNameOrID, CellValue>` |
+
+## API
+
+- 创建：`POST /open-apis/base/v3/bases/:base_token/tables/:table_id/records`
+- 更新：带 `--record-id` 时改走 `PATCH /records/:record_id`
+
+## `--json` 结构
+
+- `--json` 必须是 **JSON object map**，形状是 `Map<FieldNameOrID, CellValue>`。
+- key 是字段名或字段 ID；value 是该字段的 `CellValue`。
+- 一次请求里同一字段只用一种标识，避免重复写入冲突。
+- 写入前先 `+field-list` 确认字段类型和字段名/ID。
+- CellValue 统一看 [lark-base-cell-value.md](lark-base-cell-value.md)。
+
+```json
+{
+  "项目名称": "Apollo",
+  "状态": "进行中",
+  "完成时间": "2026-03-24 10:00:00"
+}
+```
+
+## 返回重点
+
+- 创建时返回 `record` 和 `created: true`。
+- 更新时返回 `record` 和 `updated: true`。
+- 如果写入了 `formula / lookup / created_at / updated_at / created_by / updated_by` 等只读字段，返回里可能出现 `ignored_fields`，这些字段不会被更新。
+
+## 坑点
+
+- 有 `--record-id` 就一定更新；不传就一定创建，不会自动查重或按业务键 upsert。
+- select 写入未知选项时平台可能自动新增选项；如果不是要新增选项，先用 `+field-list` / `+field-search-options` 确认真实选项名。
+- 这是写入操作，执行前必须确认目标表和字段。
+
+## 参考
+
+- [lark-base-record.md](lark-base-record.md) — record 索引页
+- [lark-base-cell-value.md](lark-base-cell-value.md) — CellValue 格式规范

package/dist/skills/larksuite/lark-base/references/lark-base-record.md

@@ -0,0 +1,29 @@
+# base record shortcuts
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+record 相关命令索引。
+
+## 命令导航
+
+| 文档 | 命令 | 说明 |
+|------|------|------|
+| [lark-base-data-analysis-sop.md](lark-base-data-analysis-sop.md) | `+record-get` / `+record-search` / `+record-list` / `+data-query` / 视图筛选排序 | 数据查询与分析统一选路、筛选排序投影、聚合后回查明细 SOP |
+| [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` | 删除一条或多条记录 |
+| [lark-base-record-share-link-create.md](lark-base-record-share-link-create.md) | `+record-share-link-create` | 生成记录分享链接（支持单条或批量，最多 100 条）|
+
+## 说明
+
+- 读取记录前优先阅读 [lark-base-data-analysis-sop.md](lark-base-data-analysis-sop.md)，它合并了 `record / view / data-query` 的选路、分页、投影、聚合后回查明细和 link 关联读取。
+- 聚合页只保留目录职责；写入、删除、历史等命令的详细说明请进入对应单命令文档。
+- 所有 `+xxx-list` 调用都必须串行执行；若要批量跑多个 list 请求，只能串行执行。
+- `+record-list` 支持重复传参 `--field-id` 做字段筛选。
+- `+record-get` 支持重复 `--record-id` 或 `--json '{"record_id_list":[...]}'` 批量读取；也支持重复传参 `--field-id` 裁剪返回字段，避免返回全字段。
+- 写记录 JSON 前优先阅读 [lark-base-cell-value.md](lark-base-cell-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/dist/skills/larksuite/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/dist/skills/larksuite/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/dist/skills/larksuite/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/dist/skills/larksuite/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) — 认证和全局参数