lark-base

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

base

前置条件： 先阅读
../lark-shared/SKILL.md
。 执行前必做： 执行任何
base
命令前，必须先阅读对应命令的 reference 文档，再调用命令。 命名约定： 仅使用
lark-cli base +...
形式的命令。

Prerequisites: Read
../lark-shared/SKILL.md
first. Mandatory before execution: Before running any
base
command, you must read the corresponding command reference document first, then invoke the command. Naming convention: Only use commands in the form of
lark-cli base +...
.

Agent 快速执行顺序

Agent Quick Execution Sequence

先判断任务类型
- 临时统计 / 聚合分析 →
```
+data-query
```
- 要把结果长期显示在表里 → formula 字段
- 用户明确要 lookup，或确实更适合
```
from/select/where/aggregate
```
  → lookup 字段
- 明细读取 / 导出 →
```
+record-list / +record-get
```
先拿结构，再写命令
- 至少先拿当前表结构：
```
+field-list
```
  或
```
+table-get
```
- 跨表场景必须再查目标表的结构
formula / lookup 有硬门槛
- 先读对应 guide
- 读完 guide 后，再创建对应字段
写记录前先判断字段可写性
- 只写存储字段
- 系统字段 / formula / lookup 默认只读

First determine the task type
- Temporary statistics / aggregate analysis →
```
+data-query
```
- Need to display results in the table long-term → formula field
- User explicitly requests lookup, or it is indeed more suitable for
```
from/select/where/aggregate
```
  → lookup field
- Detail reading / export →
```
+record-list / +record-get
```
Retrieve structure first, then write commands
- At least retrieve the current table structure first:
```
+field-list
```
  or
```
+table-get
```
- For cross-table scenarios, you must also retrieve the structure of the target table
Formula / lookup have hard thresholds
- Read the corresponding guide first
- After reading the guide, create the corresponding field
Determine field writability before writing records
- Only write to storage fields
- System fields / formula / lookup are read-only by default

Agent 禁止行为

Agent Prohibited Behaviors

不要把
```
+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 +...
```

Do not use
```
+record-list
```
as an aggregate analysis engine
Do not create formula / lookup fields without reading the guide first
Do not guess table names, field names, or field references in formula expressions based on natural language
Do not use system fields, formula fields, or lookup fields as the target for
```
+record-upsert
```

Do not switch to

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

for Base scenarios

Do not look for
```
bitable.*
```
just because
```
obj_type=bitable
```
appears in wiki parsing results; continue to use
```
lark-cli base +...
```
in this CLI

Base 基本心智模型

Basic Mental Model of Base

Base 字段分三类
- 存储字段：真实存用户输入的数据，通常适合
```
+record-upsert
```
  写入，例如文本、数字、日期、单选、多选、人员、关联。附件字段例外：对 agent 而言，文件上传必须走
```
+record-upload-attachment
```
  。
- 系统字段：平台自动维护，只读，典型包括创建时间、最后更新时间、创建人、修改人、自动编号。
- 计算字段：通过表达式或跨表规则推导，只读，典型包括 公式字段（formula） 和 查找引用字段（lookup）。
写记录前先判断字段类别 — 只有存储字段可直接写；公式 / lookup / 创建时间 / 更新时间 / 创建人 / 修改人 / 自动编号都应视为只读输出字段，不能拿来做
```
+record-upsert
```
入参。
Base 不只是存表数据，也能内建计算 — 用户提出“统计、比较、排名、文本拼接、日期差、跨表汇总、状态判断”等需求时，不能默认导出数据后手算；要先判断是否应通过
```
+data-query
```
或公式字段在 Base 内完成。

Base fields are divided into three categories
- Storage fields: Store user input data, typically suitable for
```
+record-upsert
```
  writing, such as text, number, date, single-select, multi-select, member, association. Exception for attachment fields: For agents, file upload must go through the
```
+record-upload-attachment
```
  link.
- System fields: Automatically maintained by the platform, read-only, typically including creation time, last update time, creator, modifier, auto-number.
- Calculated fields: Derived via expressions or cross-table rules, read-only, typically including formula fields and lookup fields.
Determine field category before writing records — Only storage fields can be written directly; formula / lookup / creation time / update time / creator / modifier / auto-number should be treated as read-only output fields and cannot be used as parameters for
```
+record-upsert
```
.
Base is not just for storing table data, it can also build-in calculations — When users put forward requirements like "statistics, comparison, ranking, text concatenation, date difference, cross-table summary, status judgment", do not default to exporting data and calculating manually; first determine whether it should be completed within Base via
```
+data-query
```
or formula fields.

分析路径决策

Analysis Path Decision

一次性分析 / 临时查询 → 优先
```
+data-query
```
- 适合：分组统计、SUM / AVG / COUNT / MAX / MIN、条件筛选后聚合。
- 特征：要的是“这次算出来的结果”，不是把结果沉淀成表内字段。
长期复用的派生指标 / 行级计算结果 → 优先公式字段
- 适合：利润率、是否延期、剩余天数、分档标签、跨表汇总后的派生结果。
- 特征：要把结果长期显示在 Base 里，跟随记录自动更新。
显式要求 Lookup，或确实要按 source/select/where/aggregate 建模 → 用 lookup 字段
- 默认仍优先考虑 formula。lookup 只在用户明确要求、或更符合固定查找配置时使用。
原始记录读取 / 明细导出 →
```
+record-list / +record-get
```
- 不要把
```
+record-list
```
  当分析引擎；它负责取明细，不负责聚合计算。

One-time analysis / temporary query → Prioritize
```
+data-query
```
- Suitable for: Group statistics, SUM / AVG / COUNT / MAX / MIN, aggregation after conditional filtering.
- Feature: Needs "results calculated this time", not to沉淀 results as fields in the table.
Long-term reusable derived metrics / row-level calculation results → Prioritize formula fields
- Suitable for: Profit margin, whether delayed, remaining days, grading tags, derived results after cross-table summary.
- Feature: Needs to display results in Base long-term, which update automatically with records.
Explicitly requires Lookup, or indeed suitable for modeling with source/select/where/aggregate → Use lookup fields
- Default to prioritizing formula. Only use lookup when users explicitly request it, or when the configuration is naturally more suitable for lookup.
Raw record reading / detail export →
```
+record-list / +record-get
```
- Do not use
```
+record-list
```
  as an analysis engine; it is responsible for retrieving details, not aggregation calculations.

公式 / Lookup 专项规则

Formula / Lookup Special Rules

涉及 formula / lookup 时，先读 guide，再出命令
- formula：
```
formula-field-guide.md
```
- lookup：
```
lookup-field-guide.md
```
guide 先于创建命令
- 没读对应 guide 前，不要直接创建 formula / lookup 字段
- 读完 guide 后，再补齐对应 JSON 并创建字段
- ```
type=formula
```
  必须提供
```
expression
```
- ```
type=lookup
```
  必须提供
```
from / select / where
```
  ，必要时补
```
aggregate
```
公式字段优先于 lookup 字段
- 只要用户的诉求是“计算 / 条件判断 / 文本处理 / 日期差 / 跨表聚合 / 跨表筛选后取值”，默认优先尝试 formula。
- 只有用户明确说要 lookup，或配置天然更适合 lookup 四元组时，再走 lookup。
表名 / 字段名必须精确匹配
- 公式、lookup、data-query 中出现的表名 / 字段名，必须来自
```
+table-list
```
  /
```
+table-get
```
  /
```
+field-list
```
  的真实返回，禁止凭语义猜测改写。
先拿结构再写表达式
- 公式或 lookup 一律先获取相关表结构，再生成表达式 / 配置；不要直接凭用户口述拼字段名。

When involving formula / lookup, read the guide first, then write commands
- formula:
```
formula-field-guide.md
```
- lookup:
```
lookup-field-guide.md
```
Guide takes precedence over creation commands
- Do not create formula / lookup fields without reading the corresponding guide first
- After reading the guide, complete the corresponding JSON and create the field
- ```
type=formula
```
  must provide
```
expression
```
- ```
type=lookup
```
  must provide
```
from / select / where
```
  , and supplement
```
aggregate
```
  if necessary
Formula fields take precedence over lookup fields
- As long as the user's requirement is "calculation / conditional judgment / text processing / date difference / cross-table aggregation / value retrieval after cross-table filtering", default to trying formula first.
- Only use lookup when users explicitly mention it, or when the configuration is naturally more suitable for the lookup four-tuple.
Table names / field names must match exactly
- Table names / field names used in formulas, lookup, data-query must come from the actual returns of
```
+table-list
```
  /
```
+table-get
```
  /
```
+field-list
```
  ; guessing and rewriting based on semantics is prohibited.
Retrieve structure first, then write expressions
- For formulas or lookup, always retrieve the relevant table structure first, then generate expressions / configurations; do not directly assemble field names based on user口述.

Workflow 专项规则

Workflow Special Rules

执行任何 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 枚举中复制准确的类型名称
创建前确认依赖信息
- 先通过
```
+table-list
```
  /
```
+field-list
```
  获取真实的表名、字段名
- 禁止凭自然语言猜测表名/字段名填入 workflow 配置

Before executing any workflow command, you must read two documents: the corresponding command document + lark-base-workflow-schema.md
- ```
+workflow-create
```
  → Read lark-base-workflow-create.md + schema first
- ```
+workflow-update
```
  → Read lark-base-workflow-update.md + schema first
- ```
+workflow-list
```
  → Read lark-base-workflow-list.md + schema first
- ```
+workflow-get
```
  → Read lark-base-workflow-get.md + schema first
- ```
+workflow-enable
```
  → Read lark-base-workflow-enable.md + schema first
- ```
+workflow-disable
```
  → Read lark-base-workflow-disable.md + schema first
- The schema defines all StepType enums, step structures, data formats of Trigger/Action/Branch/Loop, value reference syntax, etc.
- Prohibit guessing
```
type
```
  values based on natural language (e.g., guessing "add record" as
```
CreateTrigger
```
  ); must copy the exact type name from the StepType enum in the schema
Confirm dependency information before creation
- First retrieve actual table names and field names via
```
+table-list
```
  /
```
+field-list
```
- Prohibit guessing table names/field names based on natural language and filling them into workflow configurations

核心规则

Core Rules

只使用原子命令 — 使用

+table-list / +table-get / +field-create / +record-upsert / +view-set-filter / +record-history-list / +base-get

这类一命令一动作的写法，不使用旧聚合式

+table / +field / +record / +view / +history / +workspace

写记录前先读字段结构 — 先调用
```
+field-list
```
获取字段结构，再读 lark-base-shortcut-record-value.md 确认各字段类型的写入值格式
写字段前先看字段属性规范 — 先读 lark-base-shortcut-field-properties.md 确认
```
+field-create/+field-update
```
的 JSON 结构
筛选查询按视图能力执行 — 先读 lark-base-view-set-filter.md 和 lark-base-record-list.md，通过
```
+view-set-filter
```
+
```
+record-list
```
组合完成筛选读取
对记录进行分析（涉及"最高/最低/总计/平均/排名/比较/数量"等分析意图） — 先读 lark-base-data-query.md，通过
```
+data-query
```
进行数据筛选聚合的服务端计算
聚合分析与取数互斥 — 需要分组统计 / SUM / MAX / AVG / COUNT 时，必须使用
```
+data-query
```
（服务端计算），禁止用
```
+record-list
```
拉全量记录再手动计算；反之，
```
+data-query
```
不返回原始记录，取数场景仍走
```
+record-list / +record-get
```

所有
+xxx-list
禁止并发调用 —

+table-list / +field-list / +record-list / +view-list / +record-history-list / +role-list

只能串行执行

批量上限 500 条/次 — 同一表建议串行写入，并在批次间延迟 0.5–1 秒
统一参数名 — 一律使用
```
--base-token
```
，不使用旧
```
--app-token
```
遇到“公式 / 查找引用 / 派生指标 / 跨表计算”需求，优先走字段方案判断 — 先判断应建 formula / lookup 字段，还是只做一次性
```
+data-query
```
公式、lookup、系统字段默认视为只读 — 除
```
+field-create / +field-update
```
维护字段定义外，不要把这些字段作为记录写入目标
改名和删除按明确意图执行 —
```
+view-rename
```
在目标视图和新名称都明确时可直接执行；
```
+record-delete / +field-delete / +table-delete
```
在用户已经明确要求删除且目标明确时也可直接执行，不需要再补一次确认，并且执行删除命令时要主动补上
```
--yes
```
；只有目标不明确时才继续追问

Only use atomic commands — Use commands like

+table-list / +table-get / +field-create / +record-upsert / +view-set-filter / +record-history-list / +base-get

which perform one action per command, instead of the old aggregate-style

+table / +field / +record / +view / +history / +workspace

Read field structure before writing records — First call
```
+field-list
```
to retrieve field structure, then read lark-base-shortcut-record-value.md to confirm the write value format for each field type
Check field property specifications before writing fields — First read lark-base-shortcut-field-properties.md to confirm the JSON structure for
```
+field-create/+field-update
```
Execute filter queries according to view capabilities — First read lark-base-view-set-filter.md and lark-base-record-list.md, and complete filter reading via the combination of
```
+view-set-filter
```
+
```
+record-list
```
Analyze records (involving analysis intentions like "highest/lowest/total/average/ranking/comparison/quantity") — First read lark-base-data-query.md, and perform server-side calculation of data filtering and aggregation via
```
+data-query
```
Aggregation analysis and data retrieval are mutually exclusive — When group statistics / SUM / MAX / AVG / COUNT are needed, must use
```
+data-query
```
(server-side calculation); prohibit pulling all records with
```
+record-list
```
and then calculating manually; conversely,
```
+data-query
```
does not return raw records, so data retrieval scenarios still use
```
+record-list / +record-get
```

All
+xxx-list
commands are prohibited from concurrent calls —

+table-list / +field-list / +record-list / +view-list / +record-history-list / +role-list

can only be executed serially

Batch limit: 500 items per time — It is recommended to write to the same table serially, with a 0.5–1 second delay between batches
Unified parameter name — Always use
```
--base-token
```
, do not use the old
```
--app-token
```
For requirements involving "formula / lookup reference / derived metric / cross-table calculation", prioritize field scheme judgment — First determine whether to create formula / lookup fields, or just perform a one-time
```
+data-query
```
Formula, lookup, and system fields are read-only by default — Except for maintaining field definitions via
```
+field-create / +field-update
```
, do not use these fields as record writing targets
Execute renaming and deletion according to explicit intentions —
```
+view-rename
```
can be executed directly when both the target view and new name are clear;
```
+record-delete / +field-delete / +table-delete
```
can also be executed directly when the user has clearly requested deletion and the target is clear, no need for additional confirmation, and
```
--yes
```
must be actively added when executing the delete command; only continue to ask questions when the target is unclear

问卷 / 表单提示

Form / Questionnaire Tips

获取问卷列表：使用
```
+form-list
```
（先拿
```
form-id
```
）
获取单个问卷：使用
```
+form-get
```
获取表单 / 问卷问题：使用
```
+form-questions-list
```
删除问卷 / 表单问题：使用
```
+form-questions-delete
```

创建 / 更新问题：使用

+form-questions-create / +form-questions-update

Get questionnaire list: Use
```
+form-list
```
(get
```
form-id
```
first)
Get single questionnaire: Use
```
+form-get
```
Get form / questionnaire questions: Use
```
+form-questions-list
```
Delete questionnaire / form questions: Use
```
+form-questions-delete
```

Create / update questions: Use

+form-questions-create / +form-questions-update

意图 → 命令索引

Intent → Command Index

意图	推荐命令	备注
列表 / 获取数据表	`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`	一命令一动作

Intent	Recommended Command	Remarks
List / Get data tables	`lark-cli base +table-list` / `+table-get`	Atomic command
Create / Update / Delete data tables	`lark-cli base +table-create` / `+table-update` / `+table-delete`	One action per command
List / Get fields	`lark-cli base +field-list` / `+field-get`	Atomic command
Create / Update fields	`lark-cli base +field-create` / `+field-update`	Use `--json`
Create / Update formula fields	`lark-cli base +field-create` / `+field-update`	`type=formula` ; Read formula guide first, then create / update
Create / Update lookup fields	`lark-cli base +field-create` / `+field-update`	`type=lookup` ; Read lookup guide first, then create / update; Default to judging whether formula is more suitable
List / Get records	`lark-cli base +record-list` / `+record-get`	Atomic command; For `aggregate calculation` or `group statistics` , it is recommended to use `+data-query`
Create / Update records	`lark-cli base +record-upsert`	`--table-id [--record-id] --json`
Aggregate analysis / Comparison sorting / Get min/max / Filter statistics	`lark-cli base +data-query`	Do not use `+record-list` to pull all records and then calculate manually; use `+data-query` instead
Configure / Query views	`lark-cli base +view-*`	`list/get/create/delete/get-/set-/rename`
View record history	`lark-cli base +record-history-list`	Query record history by table and record
Filter query by view	`lark-cli base +view-set-filter` + `lark-cli base +record-list`	Combined call
Create / Get / Copy Base	`lark-cli base +base-create` / `+base-get` / `+base-copy`	Atomic command
List / Get workflows	`lark-cli base +workflow-list` / `+workflow-get`	Atomic command
Create / Update workflows	`lark-cli base +workflow-create` / `+workflow-update`	Use `--json` ; Must read schema
Enable / Disable workflows	`lark-cli base +workflow-enable` / `+workflow-disable`	One action per command
Enable / Disable advanced permissions	`lark-cli base +advperm-enable` / `+advperm-disable`	Advanced permissions must be enabled to use custom roles; Disabling will invalidate existing roles
List / Get roles	`lark-cli base +role-list / +role-get`	View role summary or complete configuration
Create / Update / Delete roles	`lark-cli base +role-create / +role-update / +role-delete`	Manage custom role permissions
List / Get forms	`lark-cli base +form-list` / `+form-get`	Atomic command
Create / Update / Delete forms	`lark-cli base +form-create` / `+form-update` / `+form-delete`	One action per command
List / Create / Update / Delete form questions	`lark-cli base +form-questions-list` / `+form-questions-create` / `+form-questions-update` / `+form-questions-delete`	One action per command
List / Get dashboards	`lark-cli base +dashboard-list` / `+dashboard-get`	Atomic command
Create / Update / Delete dashboards	`lark-cli base +dashboard-create` / `+dashboard-update` / `+dashboard-delete`	One action per command
List / Get dashboard Blocks	`lark-cli base +dashboard-block-list` / `+dashboard-block-get`	Atomic command
Create / Update / Delete dashboard Blocks	`lark-cli base +dashboard-block-create` / `+dashboard-block-update` / `+dashboard-block-delete`	One action per command

操作注意事项

Operation Notes

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 命令确认

Unified Base token specification: Use
```
--base-token
```
uniformly

Discipline for
+xxx-list
calls: Concurrent calls to

+table-list / +field-list / +record-list / +view-list / +record-history-list / +role-list / +dashboard-list / +dashboard-block-list / +workflow-list

are prohibited; must execute serially during batch execution

+record-list
limit upper limit: The maximum value of
```
--limit
```
is
```
200
```
. When more data is needed, must use pagination (increment
```
offset
```
) to pull in batches; passing more than
```
200
```
at a time is prohibited
Determine field writability first: Only storage fields can be written; formula / lookup / system fields are read-only by default and should be skipped when writing records
Proactively consider formula capabilities: When users say "calculate" "generate tags" "judge abnormality" "cross-table summary" "alert by date difference", first determine whether formula fields should be created instead of only returning manual analysis solutions
Lookup is not the default first choice: Lookup is only used when users explicitly request it or it is indeed more suitable for fixed lookup models; formula is prioritized for regular calculations, cross-table aggregation and conditional judgments
Attachment fields: If users want to "upload attachments / add files to records", only use the
```
+record-upload-attachment
```
link (read field → read record → upload material → write back record)
Member fields / User fields: Pay attention to the difference between
```
user_id_type
```
and execution identity (user / bot) during debugging
History usage:
```
+record-history-list
```
queries record history by
```
table-id + record-id
```
, and does not support full-table history scanning
Workspace status: Integrated with
```
+base-create / +base-get / +base-copy
```
Result return specification for
+base-create / +base-copy
: After successful creation or copying, the identification information of the new Base must be actively returned in the reply. If the return result contains an accessible link (such as
```
base.url
```
), it should also be returned together
Friendliness rules for
+base-create / +base-copy
:
```
--folder-token
```
,
```
--time-zone
```
, and
```
--name
```
during copying are optional parameters. Do not interrupt the process for these optional parameters when users have no special requirements; execute creation/copy directly if possible
Permission handling for
+base-create / +base-copy
(bot creation): If the Base is created by an application identity (bot), after successful creation or copying, continue to use the bot identity to add
```
full_access
```
(administrator) permission to the currently available user (referring to the user identity that has logged in and is available in the auth module of the current CLI), and clearly state the authorization result (success / no available user / authorization failure and reason) in the reply. If authorization is not completed, provide subsequent guidance (retry authorization later or continue using bot); owner transfer must be confirmed separately, unauthorized execution is prohibited
Dashboard usage:
```
+dashboard-create
```
returns
```
dashboard_id
```
after creation;
```
data_config
```
of Block is passed in via JSON string, and supports reading files via
```
@file.json
```
Advperm usage: Advanced permissions must be enabled via
```
+advperm-enable
```
to manage roles (
```
+role-*
```
);
```
+advperm-disable
```
is a high-risk operation, and all existing custom roles will become invalid after disabling; the operating user must be a Base administrator; read lark-base-advperm-enable.md / lark-base-advperm-disable.md first
Role usage:
```
+role-create
```
only supports
```
custom_role
```
;
```
+role-update
```
uses Delta Merge (
```
role_name
```
and
```
role_type
```
must always be provided);
```
+role-delete
```
is irreversible and only supports custom roles; role configuration supports
```
base_rule_map
```
(Base-level copy/download),
```
table_rule_map
```
(table-level permissions including record/field granularity),
```
dashboard_rule_map
```
(dashboard permissions),
```
docx_rule_map
```
(document permissions); read role-config.md before writing roles
Form form-id: Obtained via
```
+form-list
```
; The
```
id
```
returned by
```
+form-create
```
is
```
form-id
```
, which can be used for
```
+form-questions-*
```
operations
Workflow usage: Before creating or updating a workflow, you must carefully read lark-base-workflow-schema.md to understand the structure of each trigger and node component; meanwhile,
```
+workflow-list
```
does not return the complete tree structure, so use
```
+workflow-get
```
if you need to read the complete structure.
Data-query usage: Before using
```
+data-query
```
, you must read lark-base-data-query.md to understand the DSL structure, supported field types, aggregation functions and restrictions;
```
field_name
```
in DSL must match the table field name exactly, retrieve real field names with
```
+field-list
```
before constructing
Formula / lookup usage: Before constructing expressions or where conditions, at least retrieve the current table structure first; for cross-table scenarios, retrieve the structure of the target table; guessing field names based on natural language is not allowed
View rename confirmation rule: When the user has clearly specified "which view to rename to what name",
```
+view-rename
```
can be executed directly without additional confirmation
Delete confirmation rule (records / fields / tables): If the user has clearly stated to delete and the target is clear,
```
+record-delete / +field-delete / +table-delete
```
can be executed directly without additional confirmation; add
```
--yes
```
directly when executing to pass the CLI's high-risk write check. Only use
```
+record-get / +field-get / +table-get
```
or list commands to confirm when the target is ambiguous

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

Special Handling of Wiki Links (Extremely Critical!)

知识库链接（

/wiki/TOKEN

）背后可能是云文档、电子表格、多维表格等不同类型的文档。不能直接假设 URL 中的 token 就是 file_token，必须先查询实际类型和真实 token。

Knowledge base links (

/wiki/TOKEN

) may correspond to different document types such as cloud documents, spreadsheets, multidimensional tables, etc. Do not directly assume that the token in the URL is the file_token; you must first query the actual type and real token.

处理流程

Processing Flow

使用
wiki.spaces.get_node
查询节点信息

bash

lark-cli wiki spaces get_node --params '{"token":"&lt;wiki_token&gt;"}'

从返回结果中提取关键信息
- ```
node.obj_type
```
  ：文档类型（docx/doc/sheet/bitable/slides/file/mindnote）
- ```
node.obj_token
```
  ：真实的文档 token（用于后续操作）
- ```
node.title
```
  ：文档标题
根据
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.*
```
|
把 wiki 解析出的
obj_token
当成 Base token 使用
- 当
```
obj_type=bitable
```
  时，
```
node.obj_token
```
  就是后续
```
base
```
  命令应使用的真实 token。
- 也就是说：如果原始输入是
```
/wiki/...
```
  链接，不要把
```
wiki_token
```
  直接塞给
```
--base-token
```
  。
如果已经报了 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 +...
```
  。

Query node information using
wiki.spaces.get_node

bash

lark-cli wiki spaces get_node --params '{"token":"&lt;wiki_token&gt;"}'

Extract key information from the return result
- ```
node.obj_type
```
  : Document type (docx/doc/sheet/bitable/slides/file/mindnote)
- ```
node.obj_token
```
  : Real document token (used for subsequent operations)
- ```
node.title
```
  : Document title
Select subsequent commands based on
obj_type
| obj_type | Description | Subsequent Commands | |----------|------|-----------| |
```
docx
```
| New version cloud document |
```
drive file.comments.*
```
、
```
docx.*
```
| |
```
doc
```
| Old version cloud document |
```
drive file.comments.*
```
| |
```
sheet
```
| Spreadsheet |
```
sheets.*
```
| |
```
bitable
```
| Multidimensional table |
```
lark-cli base +...
```
(priority); if shortcut does not cover, use
```
lark-cli base <resource> <method>
```
; Do not switch to
```
lark-cli api /open-apis/bitable/v1/...
```
| |
```
slides
```
| Slides |
```
drive.*
```
| |
```
file
```
| File |
```
drive.*
```
| |
```
mindnote
```
| Mind map |
```
drive.*
```
|
Use
obj_token
parsed from wiki as Base token
- When
```
obj_type=bitable
```
  ,
```
node.obj_token
```
  is the real token that should be used for subsequent
```
base
```
  commands.
- That is: If the original input is a
```
/wiki/...
```
  link, do not directly use
```
wiki_token
```
  as
```
--base-token
```
  .
If token error occurs, fallback to check wiki
- If the command returns
```
param baseToken is invalid
```
  ,
```
base_token invalid
```
  ,
```
not found
```
  , and the user initially provided a
```
/wiki/...
```
  link or
```
wiki_token
```
  , first suspect that "wiki token is used as base token".
- At this time, do not switch to
```
bitable/v1
```
  API; immediately re-execute
```
lark-cli wiki spaces get_node
```
  , confirm
```
obj_type=bitable
```
  , then re-execute
```
lark-cli base +...
```
  using
```
node.obj_token
```
  .

查询示例

Query Example

bash

undefined

bash

undefined

查询 wiki 节点

Query wiki node

lark-cli wiki spaces get_node --params '{"token":"Pgrr***************UnRb"}'


返回结果示例：
```json
{
  "node": {
    "obj_type": "docx",
    "obj_token": "UAJ***************E9nic",
    "title": "ai friendly 测试 - 1 副本",
    "node_type": "origin",
    "space_id": "6946843325487906839"
  }
}

lark-cli wiki spaces get_node --params '{"token":"Pgrr***************UnRb"}'


Return result example：
```json
{
  "node": {
    "obj_type": "docx",
    "obj_token": "UAJ***************E9nic",
    "title": "ai friendly test - 1 copy",
    "node_type": "origin",
    "space_id": "6946843325487906839"
  }
}

Base 链接解析规则

Base Link Parsing Rules

链接类型	格式	处理方式
直接 Base 链接	`/base/{token}`	直接提取作为 `--base-token`
Wiki 知识库链接	`/wiki/{token}`	先调用 `wiki.spaces.get_node` ，取 `node.obj_token`

Link Type	Format	Handling Method
Direct Base link	`/base/{token}`	Extract directly as `--base-token`
Wiki knowledge base link	`/wiki/{token}`	Call `wiki.spaces.get_node` first, then take `node.obj_token`

URL 参数提取

URL Parameter Extraction

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

```
/base/{token}
```
→
```
--base-token
```
```
?table={id}
```
→
```
--table-id
```
```
?view={id}
```
→
```
--view-id
```

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

```
/base/{token}
```
→
```
--base-token
```
```
?table={id}
```
→
```
--table-id
```
```
?view={id}
```
→
```
--view-id
```

禁止事项

Prohibited Items

禁止将完整 URL 直接作为
```
--base-token
```
参数传入
禁止将 wiki_token 直接作为
```
--base-token
```

Prohibit directly passing the complete URL as the
```
--base-token
```
parameter
Prohibit directly using wiki_token as
```
--base-token
```

常见错误速查

Quick Check of Common Errors

错误码	含义	解决方案
1254064	日期格式错误	用毫秒时间戳，非字符串 / 秒级
1254068	超链接格式错误	用 `{text, link}` 对象
1254066	人员字段错误	用 `[{id:"ou_xxx"}]` ，并确认 `user_id_type`
1254045	字段名不存在	检查字段名（含空格、大小写）
1254015	字段值类型不匹配	先 `+field-list` ，再按类型构造
`param baseToken is invalid` / `base_token invalid`	把 wiki token、workspace token 或其他 token 当成了 `base_token`	如果输入来自 `/wiki/...` ，先用 `lark-cli wiki spaces get_node` 取真实 `obj_token` ；当 `obj_type=bitable` 时，用 `node.obj_token` 作为 `--base-token` 重试，不要改走 `bitable/v1`
formula / lookup 创建失败	指南未读或结构不合法	先读 `formula-field-guide.md` / `lookup-field-guide.md` ，再按 guide 重建请求
系统字段 / 公式字段写入失败	只读字段被当成可写字段	改为写存储字段，计算结果交给 formula / lookup / 系统字段自动产出
1254104	批量超 500 条	分批调用
1254291	并发写冲突	串行写入 + 批次间延迟

Error Code	Meaning	Solution
1254064	Incorrect date format	Use millisecond timestamp instead of string / second-level timestamp
1254068	Incorrect hyperlink format	Use `{text, link}` object
1254066	Member field error	Use `[{id:"ou_xxx"}]` , and confirm `user_id_type`
1254045	Field name does not exist	Check field name (including spaces, case)
1254015	Field value type mismatch	Call `+field-list` first, then construct according to type
`param baseToken is invalid` / `base_token invalid`	Wiki token, workspace token or other tokens are used as `base_token`	If the input comes from a `/wiki/...` link or `wiki_token` , first use `lark-cli wiki spaces get_node` to retrieve the real `obj_token` ; when `obj_type=bitable` , use `node.obj_token` as `--base-token` to retry, do not switch to `bitable/v1` API
Formula / lookup creation failed	Guide not read or structure is invalid	Read `formula-field-guide.md` / `lookup-field-guide.md` first, then rebuild the request according to the guide
Failed to write to system fields / formula fields	Read-only fields are treated as writable	Switch to writing storage fields, and let formula / lookup / system fields automatically generate calculation results
1254104	Batch exceeds 500 items	Call in batches
1254291	Concurrent write conflict	Write serially + add delay between batches

参考文档

Reference Documents

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 — 完整操作示例（建表、导入、筛选、更新）

lark-base-shortcut-field-properties.md — JSON specification for
```
+field-create/+field-update
```
(recommended)
role-config.md — Detailed explanation of role permission configuration
lark-base-shortcut-record-value.md — Value format specification for
```
+record-upsert
```
(recommended)
formula-field-guide.md — Formula field syntax, function constraints, CurrentValue rules, cross-table calculation mode (highly recommended)
lookup-field-guide.md — Lookup field configuration rules, where/aggregate constraints, trade-off with formula
lark-base-view-set-filter.md — View filter configuration
lark-base-record-list.md — Record list reading and pagination
lark-base-advperm-enable.md —
```
+advperm-enable
```
to enable advanced permissions
lark-base-advperm-disable.md —
```
+advperm-disable
```
to disable advanced permissions
lark-base-role-list.md —
```
+role-list
```
to list roles
lark-base-role-get.md —
```
+role-get
```
to get role details
lark-base-role-create.md —
```
+role-create
```
to create roles
lark-base-role-update.md —
```
+role-update
```
to update roles
lark-base-role-delete.md —
```
+role-delete
```
to delete roles
lark-base-dashboard.md — Dashboard command index (each command has been split into independent documents)
lark-base-dashboard-block.md — Dashboard block command index (each command has been split into independent documents)
dashboard-block-data-config.md — Block data_config structure, chart types, filter rules
lark-base-workflow.md — Workflow command index
lark-base-workflow-schema.md — Detailed explanation of JSON body data structure for
```
+workflow-create/+workflow-update
```
, including configuration rules for triggers and various nodes (highly recommended)
lark-base-data-query.md —
```
+data-query
```
aggregate analysis (DSL structure, supported field types, aggregation functions)
examples.md — Complete operation examples (table creation, import, filter, update)

命令分组

Command Groups

执行前必做： 从下表定位到命令后，务必先阅读对应命令的 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`

Mandatory before execution: After locating the command from the table below, be sure to read the corresponding command reference document first, then invoke the command.

Command Group	Description
`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`