lark-base

# base > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)。 > **执行前必做：** 执行任何 `base` 命令前，必须先阅读对应命令的 reference 文档，再调用命令。 > **命名约定：** 仅使用 `lark-cli base +...` 形式的命令。 ## Agent 快速执行顺序 1. **先判断任务类型** - 临时统计 / 聚合分析 → `+data-query` - 要把结果长期显示在表里 → formula 字段 - 用户明确要 lookup，或确实更适合 `from/select/where/aggregate` → lookup 字段 - 明细读取 / 导出 → `+record-list / +record-get` 2. **先拿结构，再写命令** - 至少先拿当前表结构：`+field-list` 或 `+table-get` - 跨表场景必须再查**目标表**的结构 3. **formula / lookup 有硬门槛** - 先读对应 guide - 读完 guide 后，再创建对应字段 4. **写记录前先判断字段可写性** - 只写存储字段 - 系统字段 / formula / lookup 默认只读 ## Agent 禁止行为 - 不要把 `+record-list` 当聚合分析引擎 - 不要没读 guide 就直接创建 formula / lookup 字段 - 不要凭自然语言猜表名、字段名、公式表达式里的字段引用 - 不要把系统字段、formula 字段、lookup 字段当成 `+record-upsert` 的写入目标 - 不要在 Base 场景改走 `lark-cli api GET /open-apis/bitable/v1/...` - 不要因为 wiki 解析结果里的 `obj_type=bitable` 就去找 `bitable.*`；在本 CLI 里应继续使用 `lark-cli base +...` ## Base 基本心智模型 1. **Base 字段分三类** - **存储字段**：真实存用户输入的数据，通常适合 `+record-upsert` 写入，例如文本、数字、日期、单选、多选、人员、关联。**附件字段例外**：对 agent 而言，文件上传必须走 `+record-upload-attachment`。 - **系统字段**：平台自动维护，只读，典型包括创建时间、最后更新时间、创建人、修改人、自动编号。 - **计算字段**：通过表达式或跨表规则推导，只读，典型包括 **公式字段（formula）** 和 **查找引用字段（lookup）**。 2. **写记录前先判断字段类别** — 只有存储字段可直接写；公式 / lookup / 创建时间 / 更新时间 / 创建人 / 修改人 / 自动编号都应视为只读输出字段，不能拿来做 `+record-upsert` 入参。 3. **Base 不只是存表数据，也能内建计算** — 用户提出“统计、比较、排名、文本拼接、日期差、跨表汇总、状态判断”等需求时，不能默认导出数据后手算；要先判断是否应通过 `+data-query` 或公式字段在 Base 内完成。 ## 分析路径决策 1. **一次性分析 / 临时查询** → 优先 `+data-query` - 适合：分组统计、SUM / AVG / COUNT / MAX / MIN、条件筛选后聚合。 - 特征：要的是“这次算出来的结果”，不是把结果沉淀成表内字段。 2. **长期复用的派生指标 / 行级计算结果** → 优先公式字段 - 适合：利润率、是否延期、剩余天数、分档标签、跨表汇总后的派生结果。 - 特征：要把结果长期显示在 Base 里，跟随记录自动更新。 3. **显式要求 Lookup，或确实要按 source/select/where/aggregate 建模** → 用 lookup 字段 - 默认仍优先考虑 formula。lookup 只在用户明确要求、或更符合固定查找配置时使用。 4. **原始记录读取 / 明细导出** → `+record-list / +record-get` - 不要把 `+record-list` 当分析引擎；它负责取明细，不负责聚合计算。 ## 公式 / Lookup 专项规则 1. **涉及 formula / lookup 时，先读 guide，再出命令** - formula：[`formula-field-guide.md`](references/formula-field-guide.md) - lookup：[`lookup-field-guide.md`](references/lookup-field-guide.md) 2. **guide 先于创建命令** - 没读对应 guide 前，不要直接创建 formula / lookup 字段 - 读完 guide 后，再补齐对应 JSON 并创建字段 - `type=formula` 必须提供 `expression` - `type=lookup` 必须提供 `from / select / where`，必要时补 `aggregate` 3. **公式字段优先于 lookup 字段** - 只要用户的诉求是“计算 / 条件判断 / 文本处理 / 日期差 / 跨表聚合 / 跨表筛选后取值”，默认优先尝试 formula。 - 只有用户明确说要 lookup，或配置天然更适合 lookup 四元组时，再走 lookup。 4. **表名 / 字段名必须精确匹配** - 公式、lookup、data-query 中出现的表名 / 字段名，必须来自 `+table-list` / `+table-get` / `+field-list` 的真实返回，禁止凭语义猜测改写。 5. **先拿结构再写表达式** - 公式或 lookup 一律先获取相关表结构，再生成表达式 / 配置；不要直接凭用户口述拼字段名。 ## Workflow 专项规则 1. **执行任何 workflow 命令前，必须先读两份文档：对应的命令文档 + [lark-base-workflow-schema.md](references/lark-base-workflow-schema.md)** - `+workflow-create` → 先读 [lark-base-workflow-create.md](references/lark-base-workflow-create.md) + schema - `+workflow-update` → 先读 [lark-base-workflow-update.md](references/lark-base-workflow-update.md) + schema - `+workflow-list` → 先读 [lark-base-workflow-list.md](references/lark-base-workflow-list.md) + schema - `+workflow-get` → 先读 [lark-base-workflow-get.md](references/lark-base-workflow-get.md) + schema - `+workflow-enable` → 先读 [lark-base-workflow-enable.md](references/lark-base-workflow-enable.md) + schema - `+workflow-disable` → 先读 [lark-base-workflow-disable.md](references/lark-base-workflow-disable.md) + schema - schema 中定义了所有 StepType 枚举、步骤结构、Trigger/Action/Branch/Loop 的 data 格式、值引用语法等 - 禁止凭自然语言猜测 `type` 值（如把"新增记录"猜成 `CreateTrigger`），必须从 schema 的 StepType 枚举中复制准确的类型名称 2. **创建前确认依赖信息** - 先通过 `+table-list` / `+field-list` 获取真实的表名、字段名 - 禁止凭自然语言猜测表名/字段名填入 workflow 配置 ## 核心规则 1. **只使用原子命令** — 使用 `+table-list / +table-get / +field-create / +record-upsert / +view-set-filter / +record-history-list / +base-get` 这类一命令一动作的写法，不使用旧聚合式 `+table / +field / +record / +view / +history / +workspace` 2. **写记录前先读字段结构** — 先调用 `+field-list` 获取字段结构，再读 [lark-base-shortcut-record-value.md](references/lark-base-shortcut-record-value.md) 确认各字段类型的写入值格式 3. **写字段前先看字段属性规范** — 先读 [lark-base-shortcut-field-properties.md](references/lark-base-shortcut-field-properties.md) 确认 `+field-create/+field-update` 的 JSON 结构 4. **筛选查询按视图能力执行** — 先读 [lark-base-view-set-filter.md](references/lark-base-view-set-filter.md) 和 [lark-base-record-list.md](references/lark-base-record-list.md)，通过 `+view-set-filter` + `+record-list` 组合完成筛选读取 5. **对记录进行分析（涉及"最高/最低/总计/平均/排名/比较/数量"等分析意图）** — 先读 [lark-base-data-query.md](references/lark-base-data-query.md)，通过 `+data-query` 进行数据筛选聚合的服务端计算 6. **聚合分析与取数互斥** — 需要分组统计 / SUM / MAX / AVG / COUNT 时，必须使用 `+data-query`（服务端计算），禁止用 `+record-list` 拉全量记录再手动计算；反之，`+data-query` 不返回原始记录，取数场景仍走 `+record-list / +record-get` 7. **所有 `+xxx-list` 禁止并发调用** — `+table-list / +field-list / +record-list / +view-list / +record-history-list / +role-list` 只能串行执行 8. **批量上限 500 条/次** — 同一表建议串行写入，并在批次间延迟 0.5–1 秒 9. **统一参数名** — 一律使用 `--base-token`，不使用旧 `--app-token` 10. **遇到“公式 / 查找引用 / 派生指标 / 跨表计算”需求，优先走字段方案判断** — 先判断应建 formula / lookup 字段，还是只做一次性 `+data-query` 11. **公式、lookup、系统字段默认视为只读** — 除 `+field-create / +field-update` 维护字段定义外，不要把这些字段作为记录写入目标 12. **改名和删除按明确意图执行** — `+view-rename` 在目标视图和新名称都明确时可直接执行；`+record-delete / +field-delete / +table-delete` 在用户已经明确要求删除且目标明确时也可直接执行，不需要再补一次确认，并且执行删除命令时要主动补上 `--yes`；只有目标不明确时才继续追问 ## 问卷 / 表单提示 - **获取问卷列表**：使用 `+form-list`（先拿 `form-id`） - **获取单个问卷**：使用 `+form-get` - **获取表单 / 问卷问题**：使用 `+form-questions-list` - **删除问卷 / 表单问题**：使用 `+form-questions-delete` - **创建 / 更新问题**：使用 `+form-questions-create / +form-questions-update` ## 意图 → 命令索引 | 意图 | 推荐命令 | 备注 | |------|---------|------| | 列表 / 获取数据表 | `lark-cli base +table-list` / `+table-get` | 原子命令 | | 创建 / 更新 / 删除数据表 | `lark-cli base +table-create` / `+table-update` / `+table-delete` | 一命令一动作 | | 列表 / 获取字段 | `lark-cli base +field-list` / `+field-get` | 原子命令 | | 创建 / 更新字段 | `lark-cli base +field-create` / `+field-update` | 使用 `--json` | | 创建 / 更新公式字段 | `lark-cli base +field-create` / `+field-update` | `type=formula`；先读 formula guide，再创建 / 更新 | | 创建 / 更新 lookup 字段 | `lark-cli base +field-create` / `+field-update` | `type=lookup`；先读 lookup guide，再创建 / 更新，默认先判断 formula 是否更合适 | | 列表 / 获取记录 | `lark-cli base +record-list` / `+record-get` | 原子命令，如果需要`聚合计算`，`分组统计` 推荐走 `+data-query` | | 创建 / 更新记录 | `lark-cli base +record-upsert` | `--table-id [--record-id] --json` | | 聚合分析 / 比较排序 / 求最值 / 筛选统计 | `lark-cli base +data-query` | 不要用 `+record-list` 拉全量数据再手动计算，需使用 `+data-query` 走服务端计算 | | 配置 / 查询视图 | `lark-cli base +view-*` | `list/get/create/delete/get-*/set-*/rename` | | 查看记录历史 | `lark-cli base +record-history-list` | 按表和记录查询变更历史 | | 按视图筛选查询 | `lark-cli base +view-set-filter` + `lark-cli base +record-list` | 组合调用 | | 创建 / 获取 / 复制 Base | `lark-cli base +base-create` / `+base-get` / `+base-copy` | 原子命令 | | 列表 / 获取工作流 | `lark-cli base +workflow-list` / `+workflow-get` | 原子命令 | | 创建 / 更新工作流 | `lark-cli base +workflow-create` / `+workflow-update` | 使用 `--json`，必须阅读 schema | | 启用 / 停用工作流 | `lark-cli base +workflow-enable` / `+workflow-disable` | 一命令一动作 | | 启用 / 停用高级权限 | `lark-cli base +advperm-enable` / `+advperm-disable` | 启用后才能使用自定义角色；停用会使已有角色失效 | | 列表 / 获取角色 | `lark-cli base +role-list / +role-get` | 查看角色摘要或完整配置 | | 创建 / 更新 / 删除角色 | `lark-cli base +role-create / +role-update / +role-delete` | 管理自定义角色权限 | | 列表 / 获取表单 | `lark-cli base +form-list` / `+form-get` | 原子命令 | | 创建 / 更新 / 删除表单 | `lark-cli base +form-create` / `+form-update` / `+form-delete` | 一命令一动作 | | 列表 / 创建 / 更新 / 删除表单问题 | `lark-cli base +form-questions-list` / `+form-questions-create` / `+form-questions-update` / `+form-questions-delete` | 一命令一动作 | | 列表 / 获取仪表盘 | `lark-cli base +dashboard-list` / `+dashboard-get` | 原子命令 | | 创建 / 更新 / 删除仪表盘 | `lark-cli base +dashboard-create` / `+dashboard-update` / `+dashboard-delete` | 一命令一动作 | | 列表 / 获取仪表盘 Block | `lark-cli base +dashboard-block-list` / `+dashboard-block-get` | 原子命令 | | 创建 / 更新 / 删除仪表盘 Block | `lark-cli base +dashboard-block-create` / `+dashboard-block-update` / `+dashboard-block-delete` | 一命令一动作 | ## 操作注意事项 - **Base token 口径统一**：统一使用 `--base-token` - **`+xxx-list` 调用纪律**：`+table-list / +field-list / +record-list / +view-list / +record-history-list / +role-list / +dashboard-list / +dashboard-block-list / +workflow-list` 禁止并发调用；批量执行时只能串行 - **`+record-list` limit 上限**：`--limit` 最大 `200`。需要更多数据时必须用分页（`offset` 递增）分批拉取，禁止单次传超过 `200` - **字段可写性先判断**：存储字段才可写；公式 / lookup / 系统字段默认只读，写记录时应跳过 - **公式能力要主动想到**：用户说“算一下”“生成标签”“判断是否异常”“跨表汇总”“按日期差预警”时，要先判断是否应该建公式字段，而不是只返回手工分析方案 - **lookup 不是默认首选**：lookup 只在用户明确要求或确实更适合固定查找模型时使用；常规计算、跨表聚合和条件判断优先 formula - **附件字段**：如果用户要“上传附件 / 给记录加文件”，只能走 `+record-upload-attachment` 这条链路（读字段 → 读记录 → 上传素材 → 回写记录） - **人员字段 / 用户字段**：调试时注意 `user_id_type` 与执行身份（user / bot）差异 - **history 使用方式**：`+record-history-list` 按 `table-id + record-id` 查询记录历史，不支持整表历史扫描 - **workspace 状态**：已接入 `+base-create / +base-get / +base-copy` - **`+base-create / +base-copy` 结果返回规范**：创建或复制成功后，回复中必须主动返回新 Base 的标识信息。若返回结果里带可访问链接（如 `base.url`），要一并返回 - **`+base-create / +base-copy` 友好性规则**：`--folder-token`、`--time-zone`、复制时的 `--name` 都是可选项。用户没有特别要求时，不要为了这些可选参数额外打断；能直接创建/复制就直接执行 - **`+base-create / +base-copy` 权限处理（bot 创建）**：若 Base 由应用身份（bot）创建，创建或复制成功后默认继续使用 bot 身份为当前可用 user（指当前 CLI 中 auth 模块已登录且可用的用户身份）添加 `full_access`（管理员）权限，并在回复中明确授权结果（成功 / 无可用 user / 授权失败及原因）。若授权未完成，要继续给出后续引导（稍后重试授权或继续用 bot）；owner 转移必须单独确认，禁止擅自执行 - **dashboard 使用方式**：`+dashboard-create` 创建后返回 `dashboard_id`；Block 的 `data_config` 通过 JSON 字符串传入，支持 `@file.json` 读取文件 - **advperm 使用方式**：`+advperm-enable` 启用高级权限后才能管理角色（`+role-*`）；`+advperm-disable` 是高风险操作，停用后已有自定义角色全部失效；操作用户必须为 Base 管理员；先读 [lark-base-advperm-enable.md](references/lark-base-advperm-enable.md) / [lark-base-advperm-disable.md](references/lark-base-advperm-disable.md) - **role 使用方式**：`+role-create` 仅支持 `custom_role`；`+role-update` 采用 Delta Merge（`role_name` 和 `role_type` 必须始终提供）；`+role-delete` 不可逆且仅支持自定义角色；角色配置支持 `base_rule_map`（Base 级复制/下载）、`table_rule_map`（表级权限含记录/字段粒度）、`dashboard_rule_map`（仪表盘权限）、`docx_rule_map`（文档权限）；写角色前先读 [role-config.md](references/role-config.md) - **表单 form-id**：通过 `+form-list` 获取；`+form-create` 返回的 `id` 即 `form-id`，可用于 `+form-questions-*` 操作 - **workflow 使用方式**：在创建或更新 workflow 前，必须仔细阅读 [lark-base-workflow-schema.md](references/lark-base-workflow-schema.md) 了解各触发器和节点组件的结构；同时 `+workflow-list` 返回的不是完整树状结构，若需读取完整结构请使用 `+workflow-get`。 - **data-query 使用方式**：使用 `+data-query` 前必须先阅读 [lark-base-data-query.md](references/lark-base-data-query.md) 了解 DSL 结构、支持的字段类型、聚合函数和限制条件；DSL 中的 `field_name` 必须与表字段名精确匹配，构造前先用 `+field-list` 获取真实字段名 - **公式 / lookup 使用方式**：构造表达式或 where 条件前，至少先拿当前表结构；跨表时要查找目标表的结构，不允许凭自然语言猜字段名 - **视图重命名确认规则**：用户已经明确“把哪个视图改成什么名字”时，`+view-rename` 直接执行即可，不需要再补一句确认