@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-form-questions-update.md

@@ -0,0 +1,92 @@
+# base +form-questions-update
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+批量更新多维表格表单/问卷中的问题（标题、描述、是否必填）。
+
+## 命令
+
+```bash
+# 更新一个问题的标题
+lark-cli base +form-questions-update \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --form-id <form_id> \
+  --questions '[{"id":"q_001","title":"您的真实姓名是？"}]'
+
+# 同时更新多个问题
+lark-cli base +form-questions-update \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --form-id <form_id> \
+  --questions '[
+    {"id":"q_001","title":"姓名（必填）","required":true},
+    {"id":"q_002","title":"联系方式","required":false}
+  ]'
+  
+# 更新问题描述（纯文本）
+lark-cli base +form-questions-update \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --form-id <form_id> \
+  --questions '[{"id":"q_001","description":"请填写您的真实姓名"}]'
+# 更新问题描述（含链接）
+lark-cli base +form-questions-update \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --form-id <form_id> \
+  --questions '[{"id":"q_001","description":"更多说明请参考[帮助文档](https://example.com/help)"}]'  
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | 多维表格 App token（base_token） |
+| `--table-id <id>` | 是 | 数据表 ID |
+| `--form-id <id>` | 是 | 表单 ID |
+| `--questions <json>` | 是 | 问题更新 JSON 数组，最多 10 个（见下方格式） |
+| `--format` | 否 | 输出格式：json（默认）\| pretty \| table \| ndjson \| csv |
+| `--as` | 否 | 身份：user（默认）\| bot |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+## `--questions` 格式
+
+每个问题对象必须包含 `id`，其余字段按需传入：
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `id` | **是** | 问题 ID（field_id），不可修改 |
+| `title` | 否 | 新的问题标题 |
+| `description` | 否 | 新的问题描述（纯文本或 Markdown 链接，如 `[文本](https://example.com)`） |
+| `required` | 否 | 是否必填 |
+| `option_display_mode` | 否 | 选项展示方式（仅 `select` 有效）：`0`=下拉，`1`=纵向（默认），`2`=横向 |
+
+## 输出格式
+
+返回更新后的问题列表：
+
+```json
+{
+  "ok": true,
+  "data": {
+    "items": [
+      {"id": "q_001", "title": "姓名（必填）", "required": true}
+    ]
+  }
+}
+```
+
+## 工作流
+
+> [!CAUTION]
+> 这是**写入操作** — 执行前必须向用户确认。
+
+1. 先用 `+form-questions-list` 获取现有问题及其 `id`
+2. 构造包含 `id` 的更新数组
+3. 执行命令并报告更新结果
+
+## 参考
+
+- [lark-base](../SKILL.md) — 多维表格全部命令
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

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

@@ -0,0 +1,23 @@
+# base form questions shortcuts
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+form questions 相关命令索引。
+
+## 命令导航
+
+| 文档 | 命令 | 说明 |
+|------|------|------|
+| [lark-base-form-questions-list.md](lark-base-form-questions-list.md) | `+form-questions-list` | 列出表单问题 |
+| [lark-base-form-questions-create.md](lark-base-form-questions-create.md) | `+form-questions-create` | 创建表单问题 |
+| [lark-base-form-questions-update.md](lark-base-form-questions-update.md) | `+form-questions-update` | 更新表单问题 |
+| [lark-base-form-questions-delete.md](lark-base-form-questions-delete.md) | `+form-questions-delete` | 删除表单问题 |
+
+## 相关
+
+- [lark-base-form.md](lark-base-form.md) — 表单管理
+
+## 说明
+
+- 聚合页只保留目录职责；每个命令的详细说明请进入对应单命令文档。
+- 所有 `+xxx-list` 调用都必须串行执行；若要批量跑多个 list 请求，只能串行执行。

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

@@ -0,0 +1,82 @@
+# base +form-update
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+更新多维表格数据表中指定表单的名称或描述。
+
+## 命令
+
+```bash
+# 更新表单名称
+lark-cli base +form-update \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --form-id <form_id> \
+  --name "新表单名称"
+
+# 更新描述（纯文本）
+lark-cli base +form-update \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --form-id <form_id> \
+  --description "新的描述内容"
+
+# 更新描述（含链接）
+lark-cli base +form-update \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --form-id <form_id> \
+  --description "新描述，[了解更多](https://example.com)"
+
+# 同时更新名称和描述
+lark-cli base +form-update \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --form-id <form_id> \
+  --name "新表单名称" \
+  --description "新的描述内容"
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | 多维表格 App token（base_token） |
+| `--table-id <id>` | 是 | 数据表 ID |
+| `--form-id <id>` | 是 | 表单 ID |
+| `--name <name>` | 否 | 新的表单名称 |
+| `--description <string>` | 否 | 新的表单描述（纯文本或 Markdown 链接，如 `[文本](https://example.com)`） |
+| `--format` | 否 | 输出格式：json（默认）\| pretty \| table \| ndjson \| csv |
+| `--as` | 否 | 身份：user（默认）\| bot |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+> `--name` 和 `--description` 至少传一个，否则无实际变更。
+
+## 输出格式
+
+返回更新后的表单信息：
+
+```json
+{
+  "ok": true,
+  "data": {
+    "id": "vewX58te9D",
+    "name": "新表单名称",
+    "description": "新的描述内容"
+  }
+}
+```
+
+## 工作流
+
+> [!CAUTION]
+> 这是**写入操作** — 执行前必须向用户确认。
+
+1. 确认 `form_id`（可通过 `+form-list` 获取）
+2. 确认要修改的字段
+3. 执行命令并报告更新后的值
+
+## 参考
+
+- [lark-base](../SKILL.md) — 多维表格全部命令
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

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

@@ -0,0 +1,24 @@
+# base form shortcuts
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+form 相关命令索引。
+
+## 命令导航
+
+| 文档 | 命令 | 说明 |
+|------|------|------|
+| [lark-base-form-list.md](lark-base-form-list.md) | `+form-list` | 分页列出表单 |
+| [lark-base-form-get.md](lark-base-form-get.md) | `+form-get` | 获取表单详情 |
+| [lark-base-form-create.md](lark-base-form-create.md) | `+form-create` | 创建表单 |
+| [lark-base-form-update.md](lark-base-form-update.md) | `+form-update` | 更新表单 |
+| [lark-base-form-delete.md](lark-base-form-delete.md) | `+form-delete` | 删除表单 |
+
+## 相关
+
+- [lark-base-form-questions.md](lark-base-form-questions.md) — 表单问题（表单字段）管理
+
+## 说明
+
+- 聚合页只保留目录职责；每个命令的详细说明请进入对应单命令文档。
+- 所有 `+xxx-list` 调用都必须串行执行；若要批量跑多个 list 请求，只能串行执行。

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

@@ -0,0 +1,16 @@
+# base history shortcuts
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+history 相关命令索引。
+
+## 命令导航
+
+| 文档 | 命令 | 说明 |
+|------|------|------|
+| [lark-base-record-history-list.md](lark-base-record-history-list.md) | `+record-history-list` | 按 `table-id + record-id` 查询记录变更历史 |
+
+## 说明
+
+- 聚合页只保留目录职责；每个命令的详细说明请进入对应单命令文档。
+- 所有 `+xxx-list` 调用都必须串行执行；若要批量跑多个 list 请求，只能串行执行。

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

@@ -0,0 +1,76 @@
+# base +record-batch-create
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+批量创建记录。
+
+## 适用场景（重点）
+
+- 适合大量创建写入场景，例如导入 CSV / Excel、外部系统一次性写入新数据。
+- 当输入是长表格或长文本数据时，先按 [lark-base-shortcut-record-value.md](lark-base-shortcut-record-value.md) 做字段映射和类型规范化，再组装 `fields + rows` 调用本命令写入。
+
+## 推荐命令
+
+```bash
+lark-cli base +record-batch-create \
+  --base-token XXXXXX \
+  --table-id tblXXX \
+  --json '{"fields":["标题","状态"],"rows":[["任务 A","Open"],["任务 B","Done"]]}'
+```
+
+```bash
+lark-cli base +record-batch-create \
+  --base-token XXXXXX \
+  --table-id tblXXX \
+  --json @batch-create.json
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | Base Token |
+| `--table-id <id_or_name>` | 是 | 表 ID 或表名 |
+| `--json <body>` | 是 | 批量创建请求体，必须是 JSON 对象。支持直接传 JSON 字符串，或 `@<file_path>` 从文件读取 |
+
+## API 入参详情
+
+**HTTP 方法和路径：**
+
+```http
+POST /open-apis/base/v3/bases/:base_token/tables/:table_id/records/batch_create
+```
+
+## `--json` 结构
+
+对象形态：`{"fields":[...],"rows":[...]}`。
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `fields` | `string[]` | 是 | 字段 ID 或字段名数组 |
+| `rows` | `any[][]` | 是 | 二维数组，每一行按 `fields` 同序给值；单次最多 200 行 |
+
+## 返回重点
+
+`data` 为多行二维数组，与 `+record-list` 返回的多行数据结构一致（按 `fields` 列顺序对齐）。
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `fields` | `string[]` | 返回的字段名数组 |
+| `field_id_list` | `string[]` | 返回的字段 ID 数组 |
+| `record_id_list` | `string[]` | 新创建记录 ID 列表 |
+| `data` | `any[][]` | 与 `fields` 对齐的多行数据 |
+| `ignored_fields` | `array` | 可选，表示被忽略的字段信息 |
+
+## 坑点
+
+- ⚠️ `--json` 必须是对象。
+- ⚠️ 写 `rows` 前必须先阅读 [lark-base-shortcut-record-value.md](lark-base-shortcut-record-value.md)，按字段类型填值，禁止按自然语言猜测 value 结构。
+- ⚠️ `fields` 与 `rows` 列顺序必须一一对应。
+- ⚠️ 空单元格可以显式用 `null` 填充。
+- ⚠️ 单次最多 200 行，超出需分批写入。
+
+## 参考
+
+- [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-batch-update.md

@@ -0,0 +1,71 @@
+# base +record-batch-update (batch update)
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+批量更新记录（将同一份 `patch` 批量应用到一批 `record_id_list`）。
+
+## 推荐命令
+
+```bash
+lark-cli base +record-batch-update \
+  --base-token XXXXXX \
+  --table-id tblXXX \
+  --json '{"record_id_list":["recXXX"],"patch":{"field_id_or_name":"value"}}'
+```
+
+```bash
+lark-cli base +record-batch-update \
+  --base-token XXXXXX \
+  --table-id tblXXX \
+  --json @batch-update.json
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | Base Token |
+| `--table-id <id_or_name>` | 是 | 表 ID 或表名 |
+| `--json <body>` | 是 | 批量更新请求体，必须是 JSON 对象。支持直接传 JSON 字符串，或 `@<file_path>` 从文件读取 |
+
+## 生成 `patch` 前必看
+
+- 先阅读 [lark-base-shortcut-record-value.md](lark-base-shortcut-record-value.md)，按字段类型构造 `patch` 的 value，避免类型不匹配。
+
+## API 入参详情
+
+**HTTP 方法和路径：**
+
+```http
+POST /open-apis/base/v3/bases/:base_token/tables/:table_id/records/batch_update
+```
+
+## `--json` 结构
+
+对象形态：`{"record_id_list":[...],"patch":{...}}`。
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `record_id_list` | `string[]` | 是 | 要更新的记录 ID 列表（单次最多 200 条） |
+| `patch` | `object` | 是 | 同一份字段更新对象，会应用到 `record_id_list` 内所有记录 |
+
+## 返回重点
+
+返回结构如下（其中 `update` 可与 `+record-list` 的单行字段对象结构对齐）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `record_id_list` | `string[]` | 本次更新到的记录 ID 列表 |
+| `update` | `object` | 本次应用的字段更新结果；可能为空对象 |
+| `ignored_fields` | `{id,name,reason}[]` | 可选，被忽略字段信息 |
+
+## 坑点
+
+- ⚠️ `--json` 必须是对象。
+- ⚠️ 该接口是“同值批量更新”：同一请求内所有 `record_id_list` 都会应用同一份 `patch`。
+- ⚠️ `record_id_list` 最大 200 条，超过会被接口校验拒绝。
+- ⚠️ 命令不会自动做字段/行映射转换，传什么就发什么。
+
+## 参考
+
+- [lark-base-record.md](lark-base-record.md) — record 索引页

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

@@ -0,0 +1,51 @@
+# base +record-delete
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+删除一条记录。
+
+## 推荐命令
+
+```bash
+lark-cli base +record-delete \
+  --base-token app_xxx \
+  --table-id tbl_xxx \
+  --record-id rec_xxx \
+  --yes
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | Base Token |
+| `--table-id <id_or_name>` | 是 | 表 ID 或表名 |
+| `--record-id <id>` | 是 | 记录 ID |
+
+## API 入参详情
+
+**HTTP 方法和路径：**
+
+```
+DELETE /open-apis/base/v3/bases/:base_token/tables/:table_id/records/:record_id
+```
+
+## 返回重点
+
+- 返回 `deleted: true` 和 `record_id`。
+
+## 工作流
+
+> 这是**高风险写入操作**。CLI 层要求显式传 `--yes`；如果用户已经明确要求删除且目标明确，直接执行并带上 `--yes`，不要再补一次确认。
+
+1. 建议先用 `+record-get` 确认目标记录。
+2. 只有当目标记录仍不明确时，才继续追问；如果删除意图和目标都明确，直接执行。
+
+## 坑点
+
+- ⚠️ 高风险写操作，删除后不可恢复。
+- ⚠️ 忘记带 `--yes` 会被 CLI 拦截。
+
+## 参考
+
+- [lark-base-record.md](lark-base-record.md) — record 索引页

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

@@ -0,0 +1,38 @@
+# base +record-get
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+获取单条记录，可选裁剪输出字段。
+
+## 推荐命令
+
+```bash
+lark-cli base +record-get \
+  --base-token app_xxx \
+  --table-id tbl_xxx \
+  --record-id rec_xxx
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | Base Token |
+| `--table-id <id_or_name>` | 是 | 表 ID 或表名 |
+| `--record-id <id>` | 是 | 记录 ID |
+
+## API 入参详情
+
+**HTTP 方法和路径：**
+
+```
+GET /open-apis/base/v3/bases/:base_token/tables/:table_id/records/:record_id
+```
+
+## 返回重点
+
+- 成功时直接返回接口 `data` 字段内容。
+
+## 参考
+
+- [lark-base-record.md](lark-base-record.md) — record 索引页

package/server/assets/skills/lark-tools/cli-skills/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 app_xxx \
+  --table-id tbl_xxx \
+  --record-id rec_xxx
+
+# 指定分页大小，带游标翻页
+lark-cli base +record-history-list \
+  --base-token app_xxx \
+  --table-id tbl_xxx \
+  --record-id rec_xxx \
+  --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/server/assets/skills/lark-tools/cli-skills/lark-base/references/lark-base-record-list.md

@@ -0,0 +1,83 @@
+# base +record-list
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+分页列出一张表里的记录；可按视图过滤，也可按字段裁剪返回列。
+
+> 默认优先使用 `+record-list`；仅当用户提供明确搜索关键词时，才使用 [lark-base-record-search.md](lark-base-record-search.md)。
+
+## 返回关键字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `has_more` | boolean | 是否还有下一页数据；`true` 表示可继续翻页，`false` 表示已到末页 |
+| `query_context.record_scope` | string | 记录范围：`all_records`（全表）或 `view_filtered_records`（按视图过滤） |
+| `query_context.field_scope` | string | 字段范围：`selected_fields`（显式传 `--field-id`）/ `view_visible_fields`（未传 `--field-id` 且按视图可见字段）/ `all_fields`（未传 `--field-id` 且无视图限制） |
+
+## 字段返回优先级
+
+- `query_context.field_scope` 的优先级为：`selected_fields`（explicit `--field-id`） > `view_visible_fields`（view visible fields） > `all_fields`（table all fields）。
+
+## 按需翻页规则
+
+1. 先执行一次 `+record-list` 获取首批结果。
+2. 检查返回的 `has_more`。
+3. 仅当同时满足以下条件时才继续翻页：
+   - `has_more = true`
+   - 用户问题需要更多数据（例如“全部导出”“统计全量明细”“继续加载下一页”）
+4. 若用户只要部分结果（例如“先看前 20 条”“先给示例数据”），即使 `has_more = true` 也不继续翻页。
+5. 继续翻页时，`offset` 按已读取数量递增，直到满足用户需求或 `has_more = false`。
+
+## 推荐命令
+
+```bash
+lark-cli base +record-list \
+  --base-token XXXXXX \
+  --table-id tblXXX \
+  --offset 0 \
+  --limit 100
+
+lark-cli base +record-list \
+  --base-token XXXXXX \
+  --table-id tblXXX \
+  --view-id vewXXX \
+  --field-id fldStatus \
+  --field-id 项目名称 \
+  --offset 0 \
+  --limit 50
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | Base Token |
+| `--table-id <id_or_name>` | 是 | 表 ID 或表名 |
+| `--view-id <id>` | 否 | 视图 ID；传入后只读该视图结果 |
+| `--field-id <id_or_name>` | 否 | 字段 ID 或字段名；可重复传入多个 `--field-id` 裁剪返回列 |
+| `--offset <n>` | 否 | 分页偏移，默认 `0` |
+| `--limit <n>` | 否 | 分页大小，默认 `100`，范围 `1-200`（最大 `200`，超过会报错） |
+
+## API 入参详情
+
+**HTTP 方法和路径：**
+
+```
+GET /open-apis/base/v3/bases/:base_token/tables/:table_id/records
+```
+
+- 查询参数会附带 `view_id / field_id(repeatable) / offset / limit`。
+
+
+## 坑点
+
+- ⚠️ `+record-list` 禁止并发调用；批量拉多个视图或多张表时必须串行。
+- ⚠️ `--limit` 最大 `200`，不要传超过 `200` 的值。
+- ⚠️ 分页时优先根据返回的 `has_more` 判断是否继续请求，不要盲目预拉全量数据。
+- ⚠️ `--field-id` 接受字段 ID 或字段名。
+- ⚠️ 复杂筛选优先落到视图里，再用 `--view-id` 读取。
+
+## 参考
+
+- [lark-base-record.md](lark-base-record.md) — record 索引页
+- [lark-base-view-set-filter.md](lark-base-view-set-filter.md) — 配筛选