@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-advperm-disable.md

@@ -0,0 +1,83 @@
+# base +advperm-disable
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+停用指定 Base 的高级权限。停用后自定义角色等高级权限功能将不可用。
+
+## 推荐命令
+
+```bash
+# 停用高级权限
+lark-cli base +advperm-disable \
+  --base-token VwGhbYCXQaYGMzsWlEZcBbfMnod
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | Base Token，27 位字母数字字符串 |
+
+## API 入参详情
+
+**HTTP 方法和路径：**
+
+```
+PUT /open-apis/base/v3/bases/:base_token/advperm/enable?enable=false
+```
+
+**Path 参数：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `base_token` | 是 | Base 的唯一标识，27 位字母数字字符串 |
+
+**Query 参数：**
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `enable` | 是 | bool | 固定为 `false`，表示停用高级权限 |
+
+## API 出参详情
+
+**Response：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `code` | int32 | 错误码，0 表示成功 |
+| `message` | string | 错误信息 |
+| `data` | string | 成功时为空 |
+
+## 返回值
+
+命令成功后输出 JSON：
+
+```json
+{
+  "ok": true,
+  "data": {
+    "success": true
+  }
+}
+```
+
+## 工作流
+
+> [!CAUTION]
+> 这是**高风险写入操作** — 停用高级权限会影响所有已配置的自定义角色，执行前必须向用户确认。
+
+1. 向用户确认 `--base-token`，并提醒停用会影响已有角色配置
+2. 执行命令
+3. 确认返回 `code: 0` 表示停用成功
+
+## 坑点
+
+- ⚠️ **操作用户必须为 Base 管理员**：非管理员调用会返回权限错误
+- ⚠️ **停用影响已有角色**：停用高级权限后，已创建的自定义角色将失效
+- ⚠️ **API 路径版本**：本接口使用 `base/v3`，路径必须从原始文档提取，不要用 WebSearch 补全
+- ⚠️ **data 字段是 JSON 字符串**：响应中 `data` 是 string 类型（非 object），需要双重解析
+
+## 参考
+
+- [lark-base](../SKILL.md) — 多维表格全部命令
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

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

@@ -0,0 +1,80 @@
+# base +advperm-enable
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+启用指定 Base 的高级权限。启用后可使用自定义角色等高级权限功能。
+
+## 推荐命令
+
+```bash
+# 启用高级权限
+lark-cli base +advperm-enable \
+  --base-token VwGh**************Mnod
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | Base Token，27 位字母数字字符串 |
+
+## API 入参详情
+
+**HTTP 方法和路径：**
+
+```
+PUT /open-apis/base/v3/bases/:base_token/advperm/enable?enable=true
+```
+
+**Path 参数：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `base_token` | 是 | Base 的唯一标识，27 位字母数字字符串 |
+
+**Query 参数：**
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `enable` | 是 | bool | 固定为 `true`，表示启用高级权限 |
+
+## API 出参详情
+
+**Response：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `code` | int32 | 错误码，0 表示成功 |
+| `message` | string | 错误信息 |
+| `data` | string | 成功时为空 |
+
+## 返回值
+
+命令成功后输出 JSON：
+
+```json
+{
+  "ok": true,
+  "data": {
+    "success": true
+  }
+}
+```
+
+## 工作流
+
+1. 向用户确认 `--base-token`
+2. 执行命令
+3. 确认返回 `code: 0` 表示启用成功
+
+## 坑点
+
+- ⚠️ **操作用户必须为 Base 管理员**：非管理员调用会返回权限错误
+- ⚠️ **API 路径版本**：本接口使用 `base/v3`，路径必须从原始文档提取，不要用 WebSearch 补全
+- ⚠️ **data 字段是 JSON 字符串**：响应中 `data` 是 string 类型（非 object），需要双重解析
+- ⚠️ **启用后才能管理角色**：`+role-create / +role-update / +role-delete` 等角色操作需要先启用高级权限
+
+## 参考
+
+- [lark-base](../SKILL.md) — 多维表格全部命令
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

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

@@ -0,0 +1,74 @@
+# base +base-copy
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+复制一个已有 Base；可选只复制结构，不复制内容。
+
+## 推荐命令
+
+```bash
+lark-cli base +base-copy \
+  --base-token app_xxx \
+  --name "Copied Base"
+
+lark-cli base +base-copy \
+  --base-token app_xxx \
+  --name "Copied Base" \
+  --folder-token fld_xxx \
+  --time-zone Asia/Shanghai \
+  --without-content
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | 源 Base Token |
+| `--name <name>` | 否 | 新 Base 名称 |
+| `--folder-token <token>` | 否 | 目标文件夹 token |
+| `--time-zone <tz>` | 否 | 时区，如 `Asia/Shanghai` |
+| `--without-content` | 否 | 只复制结构，不复制内容 |
+
+## API 入参详情
+
+**HTTP 方法和路径：**
+
+```
+POST /open-apis/base/v3/bases/:base_token/copy
+```
+
+## 返回重点
+
+- 返回 `base`。
+- CLI 会额外标记 `copied: true`。
+- 回复结果时，必须主动返回新 Base 的可访问链接：
+  - 优先使用返回结果中的 `base.url`
+  - 同时返回新 Base 的 token；字段名以实际返回为准，常见为 `base_token` 或 `app_token`
+  - 如果本次返回没有 `url`，至少返回新 Base 的名称和 token
+
+> [!IMPORTANT]
+> 如果 Base 是**以应用身份（bot）复制**出来的，shortcut 会在复制成功后自动尝试为当前 CLI 用户添加该 Base 的 `full_access`（管理员）权限，并在输出中附带 `permission_grant` 字段。
+>
+> `permission_grant.status` 语义如下：
+> - `granted`：当前 CLI 用户已获得该 Base 的管理员权限
+> - `skipped`：Base 已复制成功，但没有可授权的当前 CLI 用户，或复制结果缺少可授权 token
+> - `failed`：Base 已复制成功，但自动授权失败；结果中会包含失败原因，用户可稍后重试授权，或继续使用应用身份（bot）处理该 Base
+>
+> 回复复制结果时，除 `base token` 和可访问链接外，还必须明确告知用户 `permission_grant` 的结果。
+>
+> **仍然不要擅自执行 owner 转移。** 如果用户需要把 owner 转给自己，必须单独确认。
+
+## 工作流
+
+> [!CAUTION]
+> 这是**写入操作** — 执行前必须向用户确认。
+
+1. 先确认源 Base Token。
+2. `--name`、`--folder-token`、`--time-zone` 都是可选项；用户没要求时不要为这些可选参数额外追问。
+3. 只要结构时，显式传 `--without-content`。
+4. 复制成功后，整理并返回：新 Base 名称、token，以及响应中已有的可访问链接。
+
+## 参考
+
+- [lark-base-workspace.md](lark-base-workspace.md) — base / workspace 索引页
+- [lark-base-base-create.md](lark-base-base-create.md) — 创建全新 Base

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

@@ -0,0 +1,68 @@
+# base +base-create
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+创建一个新的 Base；可选指定父文件夹和时区。
+
+## 推荐命令
+
+```bash
+lark-cli base +base-create \
+  --name "New Base"
+
+lark-cli base +base-create \
+  --name "项目管理" \
+  --folder-token fld_xxx \
+  --time-zone Asia/Shanghai
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--name <name>` | 是 | 新 Base 名称 |
+| `--folder-token <token>` | 否 | 目标文件夹 token |
+| `--time-zone <tz>` | 否 | 时区，如 `Asia/Shanghai` |
+
+## API 入参详情
+
+**HTTP 方法和路径：**
+
+```
+POST /open-apis/base/v3/bases
+```
+
+## 返回重点
+
+- 返回 `base`。
+- CLI 会额外标记 `created: true`。
+- 回复结果时，必须主动返回新 Base 的可访问链接：
+  - 优先使用返回结果中的 `base.url`
+  - 同时返回新 Base 的 token；字段名以实际返回为准，常见为 `base_token` 或 `app_token`
+  - 如果本次返回没有 `url`，至少返回新 Base 的名称和 token
+
+> [!IMPORTANT]
+> 如果 Base 是**以应用身份（bot）创建**的，shortcut 会在创建成功后自动尝试为当前 CLI 用户添加该 Base 的 `full_access`（管理员）权限，并在输出中附带 `permission_grant` 字段。
+>
+> `permission_grant.status` 语义如下：
+> - `granted`：当前 CLI 用户已获得该 Base 的管理员权限
+> - `skipped`：Base 已创建成功，但没有可授权的当前 CLI 用户，或创建结果缺少可授权 token
+> - `failed`：Base 已创建成功，但自动授权失败；结果中会包含失败原因，用户可稍后重试授权，或继续使用应用身份（bot）处理该 Base
+>
+> 回复创建结果时，除 `base token` 和可访问链接外，还必须明确告知用户 `permission_grant` 的结果。
+>
+> **仍然不要擅自执行 owner 转移。** 如果用户需要把 owner 转给自己，必须单独确认。
+
+## 工作流
+
+> [!CAUTION]
+> 这是**写入操作** — 执行前必须向用户确认。
+
+1. 先确认 Base 名称。
+2. `--folder-token`、`--time-zone` 都是可选项；用户没要求时不要为此额外追问。
+3. 创建成功后，整理并返回：Base 名称、token，以及响应中已有的可访问链接。
+
+## 参考
+
+- [lark-base-workspace.md](lark-base-workspace.md) — base / workspace 索引页
+- [lark-base-base-copy.md](lark-base-base-copy.md) — 复制 Base

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

@@ -0,0 +1,39 @@
+# base +base-get
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+读取一个 Base 的详情。
+
+## 推荐命令
+
+```bash
+lark-cli base +base-get \
+  --base-token app_xxx
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | Base Token |
+
+## API 入参详情
+
+**HTTP 方法和路径：**
+
+```
+GET /open-apis/base/v3/bases/:base_token
+```
+
+## 返回重点
+
+- 返回 `base`，通常包含 `base_token / name / url` 等信息。
+
+## 坑点
+
+- ⚠️ 先确认传入的是 `base_token`，不是 `workspace_token`。
+- ⚠️ 如果最初输入来自 `/wiki/...`，不要直接把 `wiki_token` 当 `--base-token`；若报 `param baseToken is invalid` / `base_token invalid`，先用 `lark-cli wiki spaces get_node` 取 `node.obj_token`，再重试 `+base-get`。
+
+## 参考
+
+- [lark-base-workspace.md](lark-base-workspace.md) — base 索引页

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

@@ -0,0 +1,83 @@
+# base +dashboard-arrange
+
+> **前置条件：** 先阅读 [lark-base-dashboard.md](lark-base-dashboard.md) 了解整体工作流
+
+自动重新排列仪表盘组件布局。服务端根据组件数量和类型进行智能布局优化。
+
+## 使用场景
+
+| 场景 | 说明 |
+|------|------|
+| **从 0 到 1 搭建后** | 使用 `+dashboard-create` 和 `+dashboard-block-create` 创建仪表盘后，默认布局可能不够工整美观，推荐使用本命令做一次整体重排 |
+| **用户明确要求** | 用户主动要求对已有仪表盘进行布局重排或美化时 |
+
+> [!CAUTION]
+> - **不建议**在已有仪表盘上自动调用此命令，除非用户明确要求
+> - 排列结果是**服务端智能推荐**，不一定完全符合用户预期
+> - 无法指定具体位置（如"第一排放 A，第二排放 B"），排列逻辑是**自适应**的
+
+## 推荐命令
+
+```bash
+# 基础用法
+lark-cli base +dashboard-arrange \
+  --base-token xxx \
+  --dashboard-id blk_xxx
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | Base Token |
+| `--dashboard-id <id>` | 是 | 仪表盘 ID |
+| `--user-id-type <type>` | 否 | 用户 ID 类型：open_id / union_id / user_id |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+## 返回示例
+
+```json
+{
+  "dashboard_id": "blk_xxx",
+  "name": "数据分析",
+  "blocks": [
+    {
+      "block_id": "chtbxxxx",
+      "block_name": "总销售额",
+      "block_type": "statistics",
+      "layout": {
+        "x": 0,
+        "y": 0,
+        "w": 6,
+        "h": 6
+      }
+    },
+    {
+      "block_id": "chtbcrxxxx",
+      "block_name": "月度趋势",
+      "block_type": "column",
+      "layout": {
+        "x": 6,
+        "y": 0,
+        "w": 6,
+        "h": 6
+      }
+    }
+  ],
+  "arranged": true
+}
+```
+
+## 返回重点
+
+| 字段 | 说明 |
+|------|------|
+| `blocks[].layout` | 重排后的布局信息，包含 x/y/w/h |
+| `arranged` | 是否重排成功 |
+
+> [!CAUTION]
+> 这是**写入操作** — 执行前必须向用户确认。
+
+## 参考
+
+- [lark-base-dashboard.md](lark-base-dashboard.md) — dashboard 模块指引

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

@@ -0,0 +1,108 @@
+# base +dashboard-block-create
+
+> **前置条件：** 先阅读 [lark-base-dashboard.md](lark-base-dashboard.md) 了解整体工作流
+> **关键：** 创建前必须阅读 [dashboard-block-data-config.md](dashboard-block-data-config.md) 了解组件类型和 data_config 结构
+
+在仪表盘中创建一个组件（Block）。
+
+## 关键约束
+
+- **`type` 创建后不可修改**，创建时务必选对
+- **`data_config` 结构随 `type` 变化**，不同组件类型字段不同，**⚠️ 必须阅读 [dashboard-block-data-config.md](dashboard-block-data-config.md) 了解如何构造**
+- **组件创建必须串行执行**，不能并发
+
+## 推荐命令
+
+```bash
+# 简单示例：创建一个指标卡（统计记录数）
+lark-cli base +dashboard-block-create \
+  --base-token xxx \
+  --dashboard-id blk_xxx \
+  --name "总记录数" \
+  --type statistics \
+  --data-config '{"table_name":"订单表","count_all":true}'
+
+# 文本组件示例（Markdown 富文本）
+lark-cli base +dashboard-block-create \
+  --base-token xxx \
+  --dashboard-id blk_xxx \
+  --name "说明文字" \
+  --type text \
+  --data-config '{"text":"# 标题\n## 副标题\n**加粗** *斜体* ~~删除~~\n1. 列表1\n2. 列表2"}'
+
+# 复杂配置用文件传入
+lark-cli base +dashboard-block-create \
+  --base-token xxx \
+  --dashboard-id blk_xxx \
+  --name "销售额趋势" \
+  --type line \
+  --data-config @config.json
+```
+
+完整流程参考 [lark-base-dashboard.md](lark-base-dashboard.md) 的「场景 1：从 0 到 1 创建仪表盘」
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | Base Token |
+| `--dashboard-id <id>` | 是 | 仪表盘 ID（从 `+dashboard-list/get` 获取） |
+| `--name <name>` | **是** | 组件名称（允许重名） |
+| `--type <type>` | **是** | 组件类型，见下方枚举值。**不同 type 对应不同的 data_config 结构**，常用：`column`(柱状图)、`line`(折线图)、`pie`(饼图)、`statistics`(指标卡)、`text`(文本) |
+| `--data-config <json>` | 否 | 数据配置 JSON，**结构随 type 变化**。**⚠️ 必须阅读 [dashboard-block-data-config.md](dashboard-block-data-config.md) 了解如何构造**。创建时会做本地校验，更新时由后端校验 |
+| `--user-id-type <type>` | 否 | 用户 ID 类型，filter 涉及人员字段时使用 |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+### type 枚举值
+
+| 值 | 说明 |
+|----|------|
+| `column` | 柱状图 |
+| `bar` | 条形图 |
+| `line` | 折线图 |
+| `pie` | 饼图 |
+| `ring` | 环形图 |
+| `area` | 面积图 |
+| `combo` | 组合图 |
+| `scatter` | 散点图 |
+| `funnel` | 漏斗图 |
+| `wordCloud` | 词云 |
+| `radar` | 雷达图 |
+| `statistics` | 指标卡 |
+| `text` | 文本（支持 Markdown） |
+
+## 返回示例
+
+```json
+{
+  "block": {
+    "block_id": "chtxxxxxxxx",
+    "name": "总记录数",
+    "type": "statistics",
+    "data_config": {
+      "table_name": "电商交易明细",
+      "count_all": true
+    }
+  },
+  "created": true
+}
+```
+
+## 返回重点
+
+| 字段 | 说明 |
+|------|------|
+| `block.block_id` | 组件 ID，后续编辑/删除需要用到，务必记录 |
+| `block.name` | 组件名称 |
+| `block.type` | 组件类型 |
+| `block.data_config` | 实际创建的数据配置（可能包含后端自动添加的默认值）|
+| `created` | 是否创建成功 |
+
+> [!CAUTION]
+> 这是**写入操作** — 执行前必须向用户确认。
+
+
+## 参考
+
+- [lark-base-dashboard.md](lark-base-dashboard.md) — dashboard 模块指引
+- [dashboard-block-data-config.md](dashboard-block-data-config.md) — data_config 结构、图表类型、filter 规则

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

@@ -0,0 +1,46 @@
+# base +dashboard-block-delete
+
+> **前置条件：** 先阅读 [lark-base-dashboard.md](lark-base-dashboard.md) 了解整体工作流。
+
+删除仪表盘中的一个组件（Block），不可恢复。
+
+## 推荐命令
+
+```bash
+lark-cli base +dashboard-block-delete \
+  --base-token bascn***************CtadY \
+  --dashboard-id blkxxx \
+  --block-id chtxxxxxxxx
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | Base Token |
+| `--dashboard-id <id>` | 是 | 仪表盘 ID |
+| `--block-id <id>` | 是 | Block ID |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+## 返回示例
+
+```json
+{
+  "block_id": "chtxxxxxxxx",
+  "deleted": true
+}
+```
+
+## 返回重点
+
+| 字段 | 说明 |
+|------|------|
+| `block_id` | 被删除的组件 ID |
+| `deleted` | 是否删除成功 |
+
+> [!CAUTION]
+> 这是**写入操作**且**不可逆** — 执行前必须向用户确认。
+
+## 参考
+
+- [lark-base-dashboard.md](lark-base-dashboard.md) — dashboard 模块指引

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

@@ -0,0 +1,57 @@
+# base +dashboard-block-get
+
+> **前置条件：** 先阅读 [lark-base-dashboard.md](lark-base-dashboard.md) 了解整体工作流。
+
+获取仪表盘中单个组件的详情（包含 data_config 完整配置）。常用于：1) 查看组件的完整配置；2) 编辑组件前了解当前配置。
+
+## 推荐命令
+
+```bash
+lark-cli base +dashboard-block-get \
+  --base-token bascn***************CtadY \
+  --dashboard-id blkxxx \
+  --block-id chtxxxxxxxx
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | Base Token |
+| `--dashboard-id <id>` | 是 | 仪表盘 ID |
+| `--block-id <id>` | 是 | Block ID |
+| `--user-id-type <type>` | 否 | 用户 ID 类型：open_id / union_id / user_id |
+| `--format <fmt>` | 否 | 输出格式 |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+## 返回示例
+
+```json
+{
+  "block": {
+    "block_id": "chtxxxxxxxx",
+    "name": "柱状图",
+    "type": "column",
+    "data_config": {
+      "table_name": "电商交易明细",
+      "series": [{"field_name": "营销费用", "rollup": "SUM"}],
+      "group_by": [{"field_name": "品类", "mode": "integrated"}]
+    },
+    "layout": {"x": 0, "y": 0, "w": 6, "h": 4}
+  }
+}
+```
+
+## 返回重点
+
+| 字段 | 说明                            |
+|------|-------------------------------|
+| `block.block_id` | 组件 ID                         |
+| `block.name` | 组件名称                          |
+| `block.type` | 组件类型（如 `column`/`line`/`pie`） |
+| `block.data_config` | 数据配置（新建/编辑组件时可基于此字段修改）        |
+| `block.layout` | 布局信息（只读，x/y/w/h 坐标和尺寸）        |
+
+## 参考
+
+- [lark-base-dashboard.md](lark-base-dashboard.md) — dashboard 模块指引

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

@@ -0,0 +1,53 @@
+# base +dashboard-block-list
+
+> **前置条件：** 先阅读 [lark-base-dashboard.md](lark-base-dashboard.md) 了解整体工作流。
+
+分页列出仪表盘中的所有组件（Block）。常用于：1) 查看仪表盘有哪些组件；2) 获取组件 ID 和类型用于后续编辑/删除。
+
+## 推荐命令
+
+```bash
+lark-cli base +dashboard-block-list \
+  --base-token bascn***************CtadY \
+  --dashboard-id blkxxx
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | Base Token |
+| `--dashboard-id <id>` | 是 | 仪表盘 ID |
+| `--page-size <n>` | 否 | 每页数量，默认 20，最大 100 |
+| `--page-token <token>` | 否 | 分页标记 |
+| `--format <fmt>` | 否 | 输出格式：json / pretty / table / csv / ndjson |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+## 返回示例
+
+```json
+{
+  "items": [
+    {"block_id": "chtxxxxxxxx", "name": "图表", "type": "column"},
+    {"block_id": "chtxxxxxxxx", "name": "总利润", "type": "statistics"}
+  ],
+  "total": 4,
+  "has_more": false
+}
+```
+
+## 返回重点
+
+| 字段 | 说明 |
+|------|------|
+| `items` | 组件列表，每项包含 `block_id`（ID）、`name`（名称）、`type`（类型）|
+| `total` | 组件总数 |
+| `has_more` | 是否有更多组件（为 `true` 时需用 `page_token` 继续获取）|
+
+## 坑点
+
+- `+dashboard-block-list` 禁止并发调用；批量执行时只能串行。
+
+## 参考
+
+- [lark-base-dashboard.md](lark-base-dashboard.md) — dashboard 模块指引