base

前置条件： 先阅读

../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

   • lookup：

     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

   • +workflow-create

     → 先读 lark-base-workflow-create.md + schema

   • +workflow-update

     → 先读 lark-base-workflow-update.md + schema

   • +workflow-list

     → 先读 lark-base-workflow-list.md + schema

   • +workflow-get

     → 先读 lark-base-workflow-get.md + schema

   • +workflow-enable

     → 先读 lark-base-workflow-enable.md + schema

   • +workflow-disable

     → 先读 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 确认各字段类型的写入值格式
3. 写字段前先看字段属性规范 — 先读 lark-base-shortcut-field-properties.md 确认

   +field-create/+field-update

   的 JSON 结构
4. 筛选查询按视图能力执行 — 先读 lark-base-view-set-filter.md 和 lark-base-record-list.md，通过

   +view-set-filter

   +

   +record-list

   组合完成筛选读取
5. 对记录进行分析（涉及"最高/最低/总计/平均/排名/比较/数量"等分析意图） — 先读 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

lark-cli base +field-create

+field-update

type=lookup

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

lark-cli base +base-create

+base-get

+base-copy

lark-cli base +workflow-list

+workflow-get

lark-cli base +workflow-create

+workflow-update

--json

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

lark-cli base +dashboard-block-list

+dashboard-block-get

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 / 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
• 表单 form-id：通过

  +form-list

  获取；

  +form-create

  返回的

  id

  即

  form-id

  ，可用于

  +form-questions-*

  操作
• workflow 使用方式：在创建或更新 workflow 前，必须仔细阅读 lark-base-workflow-schema.md 了解各触发器和节点组件的结构；同时

  +workflow-list

  返回的不是完整树状结构，若需读取完整结构请使用

  +workflow-get

  。
• data-query 使用方式：使用

  +data-query

  前必须先阅读 lark-base-data-query.md 了解 DSL 结构、支持的字段类型、聚合函数和限制条件；DSL 中的

  field_name

  必须与表字段名精确匹配，构造前先用

  +field-list

  获取真实字段名
• 公式 / lookup 使用方式：构造表达式或 where 条件前，至少先拿当前表结构；跨表时要查找目标表的结构，不允许凭自然语言猜字段名
• 视图重命名确认规则：用户已经明确“把哪个视图改成什么名字”时，

  +view-rename

  直接执行即可，不需要再补一句确认
• 删除确认规则（记录 / 字段 / 表）：如果用户已经明确说要删除，并且目标也明确，

  +record-delete / +field-delete / +table-delete

  可直接执行，不需要再补一次确认；执行时直接带

  --yes

  通过 CLI 的高风险写入校验。只有目标仍有歧义时，再先用

  +record-get / +field-get / +table-get

  或 list 命令确认

Wiki 链接特殊处理（特别关键！）

知识库链接（

/wiki/TOKEN

处理流程

1. 使用

   wiki.spaces.get_node

   查询节点信息

   lark-cli wiki spaces get_node --params '{"token":"<wiki_token>"}'
   

2. 从返回结果中提取关键信息

   • node.obj_type

     ：文档类型（docx/doc/sheet/bitable/slides/file/mindnote）

   • node.obj_token

     ：真实的文档 token（用于后续操作）

   • node.title

     ：文档标题

3. 根据

   obj_type

   选择后续命令

   | obj_type | 说明 | 后续命令 | |----------|------|-----------| |

   docx

   | 新版云文档 |

   drive file.comments.*

   、

   docx.*

   | |

   doc

   | 旧版云文档 |

   drive file.comments.*

   | |

   sheet

   | 电子表格 |

   sheets.*

   | |

   bitable

   | 多维表格 |

   lark-cli base +...

   （优先）；如果 shortcut 不覆盖，再用

   lark-cli base <resource> <method>

   ；不要改走

   lark-cli api /open-apis/bitable/v1/...

   | |

   slides

   | 幻灯片 |

   drive.*

   | |

   file

   | 文件 |

   drive.*

   | |

   mindnote

   | 思维导图 |

   drive.*

   |

4. 把 wiki 解析出的

   obj_token

   当成 Base token 使用
   • 当

     obj_type=bitable

     时，

     node.obj_token

     就是后续

     base

     命令应使用的真实 token。
   • 也就是说：如果原始输入是

     /wiki/...

     链接，不要把

     wiki_token

     直接塞给

     --base-token

     。

5. 如果已经报了 token 错，再回退检查 wiki

   • 如果命令返回

     param baseToken is invalid

     、

     base_token invalid

     、

     not found

     ，并且用户最初给的是

     /wiki/...

     链接或

     wiki_token

     ，优先怀疑“把 wiki token 当成了 base token”。
   • 这时不要改走

     bitable/v1

     API；应立即重新执行

     lark-cli wiki spaces get_node

     ，确认

     obj_type=bitable

     后，改用

     node.obj_token

     重新执行

     lark-cli base +...

     。

查询示例

# 查询 wiki 节点
lark-cli wiki spaces get_node --params '{"token":"Pgrr***************UnRb"}'

返回结果示例：

{
  "node": {
    "obj_type": "docx",
    "obj_token": "UAJ***************E9nic",
    "title": "ai friendly 测试 - 1 副本",
    "node_type": "origin",
    "space_id": "6946843325487906839"
  }
}

Base 链接解析规则

/base/{token}

--base-token

/wiki/{token}

wiki.spaces.get_node

node.obj_token

URL 参数提取

https://{domain}/base/{base-token}?table={table-id}&view={view-id}

• /base/{token}

  →

  --base-token

• ?table={id}

  →

  --table-id

• ?view={id}

  →

  --view-id

禁止事项

• 禁止将完整 URL 直接作为

  --base-token

  参数传入
• 禁止将 wiki_token 直接作为

  --base-token

常见错误速查

{text, link}

[{id:"ou_xxx"}]

user_id_type

+field-list

param baseToken is invalid

base_token invalid

base_token

/wiki/...

lark-cli wiki spaces get_node

obj_token

obj_type=bitable

node.obj_token

--base-token

bitable/v1

formula-field-guide.md

lookup-field-guide.md

参考文档

• lark-base-shortcut-field-properties.md —

  +field-create/+field-update

  JSON 规范（推荐）
• role-config.md — 角色权限配置详解
• lark-base-shortcut-record-value.md —

  +record-upsert

  值格式规范（推荐）
• formula-field-guide.md — formula 字段写法、函数约束、CurrentValue 规则、跨表计算模式（强烈推荐）
• lookup-field-guide.md — lookup 字段配置规则、where/aggregate 约束、与 formula 的取舍
• lark-base-view-set-filter.md — 视图筛选配置
• lark-base-record-list.md — 记录列表读取与分页
• lark-base-advperm-enable.md —

  +advperm-enable

  启用高级权限
• lark-base-advperm-disable.md —

  +advperm-disable

  停用高级权限
• lark-base-role-list.md —

  +role-list

  列出角色
• lark-base-role-get.md —

  +role-get

  获取角色详情
• lark-base-role-create.md —

  +role-create

  创建角色
• lark-base-role-update.md —

  +role-update

  更新角色
• lark-base-role-delete.md —

  +role-delete

  删除角色
• lark-base-dashboard.md — dashboard 命令索引（每个命令已拆到独立文档）
• lark-base-dashboard-block.md — dashboard block 命令索引（每个命令已拆到独立文档）
• dashboard-block-data-config.md — Block data_config 结构、图表类型、filter 规则
• lark-base-workflow.md — workflow 命令索引
• lark-base-workflow-schema.md —

  +workflow-create/+workflow-update

  JSON body 数据结构详解，包含触发器及各类节点的配置规则（强烈推荐）
• lark-base-data-query.md —

  +data-query

  聚合分析（DSL 结构、支持字段类型、聚合函数）
• examples.md — 完整操作示例（建表、导入、筛选、更新）

命令分组

执行前必做： 从下表定位到命令后，务必先阅读对应命令的 reference 文档，再调用命令。

table commands

+table-list / +table-get / +table-create / +table-update / +table-delete

field commands

+field-list / +field-get / +field-create / +field-update / +field-delete / +field-search-options

record commands

+record-list / +record-get / +record-upsert / +record-upload-attachment / +record-delete

view commands

+view-list / +view-get / +view-create / +view-delete / +view-get-* / +view-set-* / +view-rename

data-query commands

+data-query

history commands

+record-history-list

base / workspace commands

+base-create / +base-get / +base-copy

advperm commands

+advperm-enable / +advperm-disable

role commands

+role-list / +role-get / +role-create / +role-update / +role-delete

form commands

+form-list / +form-get / +form-create / +form-update / +form-delete

form questions commands

+form-questions-list / +form-questions-create / +form-questions-update / +form-questions-delete

workflow commands

+workflow-list / +workflow-get / +workflow-create / +workflow-update / +workflow-enable / +workflow-disable

dashboard commands

+dashboard-list / +dashboard-get / +dashboard-create / +dashboard-update / +dashboard-delete

dashboard block commands

+dashboard-block-list / +dashboard-block-get / +dashboard-block-create / +dashboard-block-update / +dashboard-block-delete