Lark Base Skill
- Installs
- 492k
- Repo stars
- 18.1k
- Security scans passed
- 2/3
- Repo updated
- Nov 13, 2026
TL;DR
lark-base skill is a larksuite/cli agent skill (version 1.2.1) for Feishu/Lark Base multidimensional table operations via lark-cli base commands.
Install if
Developers building agent-driven workflows over Feishu/Lark Bitable with field design, formulas, aggregations, or cross-table analytics.
Skip if
Skip lark-base for importing local Excel or CSV into a new Base—use lark-drive +import --type bitable first.
npx skills add https://github.com/larksuite/cli --skill lark-baseTry it first through the Skillselion MCP - nothing to install, nothing on disk.
1. Add the remote connector:
claude mcp add --transport http skillselion https://mcp.skillselion.com/mcp2. Ask your agent:
Use Skillselion load_skill to load skill:larksuite/cli#lark-base (Lark Base) and follow it.Try it first through the Skillselion MCP - nothing to install, nothing on disk.
1. Add this URL as a custom connector (Claude.ai, ChatGPT or Cursor):
https://mcp.skillselion.com/mcp2. Ask your agent:
Use Skillselion load_skill to load skill:larksuite/cli#lark-base (Lark Base) and follow it.What lark-base covers
- Handles search, table creation, field management, record CRUD, sharing links, view configuration, and history queries.
- Manages workflows, dashboards, forms, roles, and permissions in Lark Base.
- Converts legacy +table/+field/+record commands into current atomic lark-cli base syntax.
- Enforces reading official reference docs before every base command execution.
- Requires data-analysis SOP review for any query involving filters, aggregation, sorting, Top-N, or cross-table joins.
lark-base by the numbers
| All-time installs | 492,030 (492k) | skills.sh registry |
|---|---|---|
| Repo stars | ★ 18.1k | GitHub |
| Security audit | 2 / 3 scanners passed | skills.sh audit |
| Repo last updated | November 13, 2026 | GitHub |
| Repository | larksuite/cli ↗ | |
Data as of Nov 14, 2026 (Skillselion catalog sync)
What does the Lark Base skill produce?
Created or updated Base tables, fields, records, views, and query results from lark-cli base operations.
- Base table schema
- queried or updated records
- Skill version 1.2.1 in larksuite/cli
- Requires reading lark-base-data-analysis-sop.md before aggregation queries
What files ship with lark-base?
Base
普通 Base 是数据容器,由一棵 Base Block 资源树和 Base 级配置组成。folder、table、docx、dashboard、workflow 都是 Block 类型;Advanced Permission / Role 是 Base 级配置,不属于 Block。Table 是其中承载业务数据的核心 Block。Workspace 是组织 Base 与 BaseApp 的外层容器;BaseApp(AppMode)通过 Page 和组件组织 Base 数据,不是 Base 的别名。
身份选择(优先)
操作 Base 优先使用 --as user;用户明确要求应用身份时使用 --as bot。权限失败按 lark-shared 以原身份修复 scope 或资源 ACL;只有用户明确同意更换操作者时才切换身份。
进入前必做:解析目标实体
开始操作前先确定 base_token 和目标实体类型;上下文已提供 <bitable> / <base_refer> 标签及资源 ID 时直接使用。其余情况按意图选择入口:
- URL 或分享链接:
lark-cli base +url-resolve --url '<url>' --as user。Base URL 根据返回的resource_type/block_type及table_id、view_id、record_id、dashboard_id、workflow_id、docx_token、share_token等坐标进入对应模块;BaseApp/app/URL 返回app_token,并在链接携带时返回workspace_token和page_id。实体类型以解析结果为准。 - Base 标题或关键词:
lark-cli base +title-resolve --title '<keyword>' --as user。单一结果直接取得base_token;多个候选结合标题、所有者和更新时间消歧,仍无法唯一确定时请用户选择。随后按下方 Base Block 资源模型定位目标实体。 - 已有 Base 候选列表: 用户要列出已有 Base 候选,且需要按最近访问、owner、创建人、时间、类型等维度筛选/排序时,转
lark-cli drive +search --doc-types bitable --as user。按标题/关键词定位单个 Base 仍用+title-resolve。常见候选列表命令:
- 最近访问:
lark-cli drive +search --doc-types bitable --sort open_time --opened-since 3m --page-size 20 --as user - 只列我拥有的:加
--mine;如果要列“我创建的”,用--created-by-me。 - 从候选项拿到 URL 或 token 后,再用
+url-resolve或+base-get进入 Base 业务命令。
- BaseApp: 优先使用真实
/app/URL;已有workspace_token时可用+workspace-entity-list --type baseapp定位。两者都没有时请用户补充应用链接或 Workspace,不按名称全局猜测app_token。
读取 Base: Base 信息用 +base-get,资源目录按下方 Base Block 资源模型读取。
写入 Base: 创建新 Base 使用一次 +base-create --name <base-name> --table-name <table-name> --fields '<field-array>' 同时创建 Base、首表和 fields;+base-copy 复制整个 Base;Base 内资源统一按下方 Block 生命周期管理。
Base 模板中心
模板中心是公开的 Base 模板库,不是用户云空间里的已有 Base。用户想用现成模板创建新 Base,且没有指向已有对象的锚点(没有 Base URL、没有“我的/最近访问的表”、没有具体已存在的 Base 名)时,可读取 lark-base-template-center.md 查找模板中心模板;+template-categories 列出公开模板分类,+template-list 按分类列出公开模板,+template-search 按业务关键词搜索公开模板。
Base Block 资源模型
Base
├── Base Block 资源树
│ ├── Table Block
│ │ ├── Field schema
│ │ ├── Records / CellValue
│ │ ├── Views
│ │ └── Forms / Questions
│ ├── Dashboard Block(布局容器)
│ │ └── Dashboard 内部 Blocks(图表、指标卡、文本)
│ ├── Workflow Block
│ │ └── Workflow definition(title、status、steps 执行图)
│ ├── Docx Block → docx_token / lark-doc
│ └── Folder Block → 子 Block
└── Base 级配置
└── Advanced Permission / Roles每个 Base Block 都有 id、type、可修改的 name、所在 Folder 的 parent_id,并在同级目录中具有顺序。+base-block-list 是统一发现入口;+base-block-create 创建 Block,+base-block-rename 修改名称,+base-block-move 通过 --parent-id 调整目录并通过 --before-id / --after-id 调整顺序,+base-block-delete 删除 Block。类型专属内容再由对应模块命令处理。
创建时已经明确类型专属初始内容,可直接使用对应构造命令一次完成:Table 用 +table-create --fields,Dashboard 用 +dashboard-create 设置主题,Workflow 用 +workflow-create --json 提交完整定义;Folder 和 Docx 使用 +base-block-create。
Block 的 id 按类型直接作为对应模块坐标:
| Block type | 模块坐标与内部内容 |
|---|---|
table | id 即 table_id;内部包含 Field、Record、View 和 Form |
dashboard | id 即 dashboard_id;内部包含图表、指标卡和文本等 Dashboard 组件 |
workflow | id 即 workflow_id;内部包含 title、status 和 steps 执行图 |
docx | Block 另带 docx_token;正文由 lark-doc 处理 |
folder | id 是目录 Block ID,也可作为 --parent-id;只组织子 Block |
Table Block(The Core)
Table 本身是 Base Block,也是 Base 的核心数据存储层;Field、Record、View 和 Form 是 Table 内部对象,不是 Base Block。业务数据查询、写入、关联、统计和分析都从 Table 开始。先用 +table-list 定位 Table;字段名和目标已知的普通读取可直接进入 Record 命令,只有写入、筛选或关联等依赖字段类型/schema 的任务才补 +field-list。多表的 +field-list 可以并发执行。基础的 Record / CellValue 读写直接按下方路径;reference 只承载高级分析、完整协议和边界细节。
读取 Table: +table-list 定位表,+table-get 读取详情。Table 专属复制使用 +table-copy,异步状态用 +table-copy-status;schema 和 records 由下方内部对象操作。
Table 下的大多数更新通过异步链路生效,接口成功返回后立即读取可能暂时看不到最新状态。优先以写入成功响应作为操作结果;任务必须确认最终状态时,先完成本轮相关变更,再统一读取验收,避免逐项写后立即读回。
Field
Field 定义列 schema。field_id 是稳定列标识,name 是可修改的展示名称;Formula、Lookup、Link、Select 等属于 Field 类型或能力。
读取 Field: +field-list / +field-get / +field-search-options。写入 Field: 已有 Table 中创建多个字段时,优先向一次 +field-create --json 传字段对象数组;单字段更新和删除用 +field-update / +field-delete。创建和更新分别读取 field-create / field-update,由命令文档继续路由 Field JSON、Formula 和 Lookup 协议。字段插件 用于扩展基础字段能力:按同一行其他字段内容触发 LLM 生成,并写回已有目标字段;当前已确认目标字段支持文本、单选、数字,配置或触发前先读 field-extension。
Record
Record 是 Table 中的一行数据,包含该记录在各个 Field 下的 CellValue。系统 record_id 是表内稳定、非空且唯一的主键,Table 的主字段只是展示字段。
1. 读取记录或单元格
- 已知若干个
record_id:+record-get --record-id <id1> --record-id <id2> - 关键词搜索:
+record-search --keyword <text> --search-field <field>;至少指定一个搜索字段。 - 其余读取:
+record-list;结构化条件和排序分别用--filter-json/--sort-json。
行数较大、需要服务端谓词下推时,--filter-json 使用 tuple condition;最常用的筛选与完整日期范围写法:
{
"logic": "and", // 全部条件成立;任一条件成立改为 "or"
"conditions": [
["状态", "intersects", ["进行中", "暂停"]], // Select 命中任一选项
["标题", "intersects", "urgent"], // 文本包含
["备注", "non_empty"], // 非空;判断为空改用 "empty",两者都不传 value
["金额", ">=", 100], // 数字比较;支持 ==、!=、>、>=、<、<=
["关联项目", "intersects", [{ "id": "recxxx" }]], // Link 包含目标记录
["业务日期", "==", "ExactDate(2026-08-07)"], // 具体一天:按 Base 时区匹配 2026-08-07 当天
["发生时间", ">", "ExactDate(2024-01-31 23:59:59.999)"], // 日期不支持 >=;用 > 前一天最后一毫秒表达含当天的下界
["发生时间", "<", "ExactDate(2024-03-01 00:00:00)"] // 2024 年 2 月范围上界:小于 3 月 1 日零点
]
}完整操作符和各字段取值结构读取 Filter 条件结构。
所有读取都重复传 --field-id 做最小字段投影,并统一写入 NDJSON artifact:--format ndjson --output <path>.ndjson。每行是一条 Record JSON,stdout 摘要包含 records_count 和 has_more 用于分页判断。
# Example: 行数较大时先筛选 Status 包含 Doing 的记录,再导出 20 条作为局部预览
lark-cli base +record-list \
--base-token <base_token> --table-id <table_id> \
--filter-json '{"logic":"and","conditions":[["Status","intersects",["Doing"]]]}' \
--field-id Name --field-id Status --field-id Score --limit 20 \
--format ndjson --output ./records-preview.ndjson --as user
PREVIEW_ROWS=5
head -n "$PREVIEW_ROWS" ./records-preview.ndjson
tail -n "$PREVIEW_ROWS" ./records-preview.ndjson预计记录数少于 500 行时,建议不做谓词下推,直接拉取到本地用 jq 或 Python 处理;行数较大时可用 --filter-json 下推可表达的条件,正则、派生等无法下推的条件继续在本地处理。
# jq:对服务端筛选结果追加名称格式筛选,再投影必要字段
jq -c 'select((.Name // "") | test("^Task-[0-9]+$")) | {record_id, Name}' ./records-preview.ndjson
# Python:按行读取并做简单汇总
python3 - <<'PY'
import json
with open("records-preview.ndjson", encoding="utf-8") as stream:
rows = (json.loads(line) for line in stream if line.strip())
print(sum((row.get("Score") or 0) for row in rows))
PY--limit 的缺省值是 2000,最大值是 2000,通常无需手动指定 limit 参数;支持 --offset 参数;只有 has_more=false 且查询范围符合问题时,才能当作完整结果。大表完整读取、View 范围读取、复杂 JOIN、集合/多值、时序、语义或专业统计分析时,读取 Record 查询与分析 SOP。
2. 新增记录或更新记录单元格
一条 Record 是 {字段名或 field_id: CellValue},常见 CellValue:
{
"标题": "Created from shortcut", // text: string
"待确认": "请 <at user_id=ou_123/> 确认", // text(plain): 人员提及;实际 open_id 用 lark-contact 查询;不发送通知
"官网": "[官网](https://example.com)", // text(url): 裸 URL 或 Markdown link
"联系电话": "13800000000", // text(phone): 合法电话号码字符串
"邮箱": "owner@example.com", // text(email): 合法邮箱字符串
"单选": ["Todo"], // select: array<string>;单选时数组最多一个值;
"标签": ["高优", "外部依赖"], // 多选 select: array<string>;必须是当前字段存在的选项;
"工时": 8, // number: double,不经过格式化的纯数字
"带时区时间": "2026-03-24T10:00:00+08:00", // datetime:带时区,遵循传入的时区
"不带时区时间": "2026-03-24 10:00", // datetime:不带时区,自动按当前 Base 时区转换
"毫秒时间戳": 1774317600000, // datetime:也支持 Unix 毫秒时间戳
"已完成": false, // checkbox: boolean
"负责人": [{ "id": "ou_123" }], // user(multiple=false): 数组最多一个元素
"协作人": [{ "id": "ou_123" }, { "id": "ou_456" }], // user(multiple=true): 数组可包含多个元素
"群聊": [{ "id": "oc_123" }, { "id": "oc_456" }], // group_chat(multiple=true)
"关联任务": [{ "id": "rec456" }], // link: array<{id}>,record_id 来自目标表
"坐标": { "lng": 116.397428, "lat": 39.90923 }, // location: {lng,lat}
"清空": null, // 清空单元格,传 null
"清空数组": [] // 清空数组类单元格,空数组和 null 都可以
}附件使用专用 shortcut 上传、下载或移除。created_at, updated_at, created_by, updated_by, auto_number, formula, lookup 类型字段只读,若误写入单元格会返回 ignored_fields 表示这些字段被静默过滤,其余字段正常写入。
# 新增:成功时返回 record_id_list
lark-cli base +record-batch-create \
--base-token <base_token> --table-id <table_id> \
--json '{"create_records":[{"Name":"Task A","Status":["Todo"]},{"Name":"Task B","Score":20}]}' --as user
# 更新:每条记录只提交要改变的字段
lark-cli base +record-batch-update \
--base-token <base_token> --table-id <table_id> \
--json '{"update_records":{"<record_id_a>":{"Status":["Done"]},"<record_id_b>":{"Score":100}}}' --as user大 payload 可用脚本生成 json 后用 --json @file.json。单批最多 200 条,超过后分批,同一 Table 串行写入;并行可能触发 1254291 并发冲突错误。
3. 其他 Record 操作
+record-delete --base-token <base_token> --table-id <table_id> --record-id <id1> --record-id <id2>删除若干个记录+record-share-link-create --base-token <base_token> --table-id <table_id> --record-id <id1> --record-id <id2>创建记录分享链接+record-history-list查询单条记录的变更事件,读取 历史记录协议- 附件必须使用
+record-upload-attachment/+record-download-attachment/+record-remove-attachment操作。
View
View 共享 Table 的底层记录;没有特殊展示需求时优先使用 grid。读取已有视图用 +view-list / +view-get。
所有 View 编辑前必读 View 类型与生命周期,包括创建、改名、配置修改(筛选、排序、分组、字段显隐、时间条、卡片)和删除。视图选型、适用配置及完整操作示例统一在该 reference 中。
Form
Form 依附于 Table,以 Field 作为题目,每次有效提交会创建一条 Record,适合信息收集、外部填写、条件题目和附件提交。
- 读取 Table 中的表单配置: 使用
+form-list/+form-get读取表单,使用+form-questions-list读取题目配置;这些命令使用表单所属的base_token + table_id。 - 创建或修改 Table 中的表单配置: 使用
+form-create/+form-update/+form-delete管理表单;题目由 Table Field 承载,question ID 对应field_id,创建和更新分别读取 questions create / questions update,删除使用+form-questions-delete。 - 调整表单题目显隐和顺序: Form 在
visible_fields接口中作为 View,form_id传给--view-id。用+view-get-visible-fields读取当前可见题目,再用+view-set-visible-fields提交最终需要展示的完整有序题目 ID 列表;省略当前可见题目会隐藏它,加入已有隐藏 Form 成员会重新展示,空列表会隐藏全部题目。目标只能包含已有 Form 成员;仍显示题目的visible_rule只能引用位于它之前的可见题目。 - 管理表单分享: 使用
+form-share-get/+form-share-update管理启停、访问范围和匿名/登录要求;更新前先读取现状,每次只修改一个字段,布尔值显式传true或false。 - 填写分享表单并提交: 对表单分享链接使用
+url-resolve取得share_token,按 Form detail 执行+form-detail读取真实题目、必填项和显示条件,再按 Form submit 构造字段与附件并执行+form-submit。
表单题目和字段的关系:
+form-questions-create支持两种形态:新建字段题目需要title+type;已有字段题目需要use_existing_field:true+field_id。已有字段题目只是把该字段加入表单,不创建新字段,也不改变已有记录数据;不要给该形态携带type、style、options等字段定义属性。- 创建问题前先
+form-questions-list。若目标标题已经存在,除非用户明确要求同名独立问题,否则优先用+form-questions-update修改题目配置,不要先创建同名问题再删除旧问题。 +form-questions-delete是高风险写操作。默认会删除承载问题的底层 Field 及该字段所有记录数据;只想把题目移出表单并保留字段/数据时必须传--keep-field。保留字段后可用+form-questions-create --questions '[{"use_existing_field":true,"field_id":"<field_id>"}]'加回表单。
Dashboard Block
Dashboard Block 是 Base Block 树中的仪表盘容器,负责承载页面主题、布局和内部组件集合,本身不表示某一项图表数据。使用 +dashboard-list 定位容器,+dashboard-get 读取容器信息,+dashboard-update 修改主题,+dashboard-arrange 统一编排内部组件布局。
管理 Dashboard 分享: 使用 +dashboard-share-get / +dashboard-share-update 管理启停、访问范围和返回源 Base 入口;更新前先读取现状,每次只修改一个字段,显式 false 会被保留。
容器内部的图表、指标卡和文本等组件在 Dashboard API 中也称为 Block,但不属于 Base Block 树。内部 Block 分为三条操作路径:
- 读取配置:
+dashboard-block-list/+dashboard-block-get读取组件类型、布局和data_config;文本组件的正文也属于配置。 - 写入配置:
+dashboard-block-create/+dashboard-block-update/+dashboard-block-delete管理组件,data_config定义数据源、维度、指标、聚合或文本内容。 - 读取内容:
+dashboard-block-get-data读取图表、指标卡等数据组件的计算结果。
操作内部 Block 前先读 Dashboard,由该入口继续路由组件配置和结果协议。
应用模式与 Workspace 心智模型
Workspace 是组织 Base 和 BaseApp 的空间容器;BaseApp 创建时必须归属一个 Workspace。BaseApp 用 Page 组织界面,每个 Page 包含图表、列表或富文本组件;组件通过 data_config 引用 Base 数据,但不会改变 Base、Table、Field 和 Record 的归属关系。Workspace 负责资源归属,App 负责页面和组件,Base 负责数据。
- Workspace: 使用
+workspace-create、+workspace-entity-list和+workspace-move-in创建目录、列出其中的 Base/BaseApp 或移入资源。 - 应用: 使用
+app-create/+app-get;应用查询和创建依赖真实app_token/workspace_token。 - 页面: 使用
+app-page-list/get/create/rename/delete管理 Page。 - 组件: 使用
+app-block-list/get/create/update读写组件配置,使用+app-block-get-data读取组件计算结果。
BaseApp、Workspace、Page 或组件任务开始前完整读取 应用模式与 Workspace;构造组件 data_config 时继续读取 应用组件配置。BaseApp 不走 lark-apps。当前不支持 BaseApp 复制、Page 完整复制、页面图标以及从 Workspace 移出资源;遇到这些目标按 reference 的能力边界处理,不以新建空对象或 Drive 移动冒充。
- BaseApp(应用模式)中的 Page 和组件使用
app_token/page_id/block_id,表、字段和记录仍使用组件所引用 Base 的base_token;不要混用 token 或把 BaseApp 当作 Base 的别名。 - 复用现有 BaseApp block 的
data_config只能作为结构模板,首次 Create/Update 前仍要逐项对齐用户显式要求;用户要求排序时必须显式写group_by[].sort.order或顶层sort.order,不能用旧配置省略的方向或当前get-data结果顺序代替。 - 应用页面的 block 与仪表盘 block 是同一套底层实体,但 ID 体系不通用;按当前模块 reference 选择命令和配置协议。
Workflow Block
Workflow 本身是 Base Block,其内部是一张由 next / children 连接的 steps 执行图;触发器、动作、条件分支和循环都是 step 类型。它适合定时执行、Record 新增或变更联动、消息通知、记录读写和跨系统调用。Workflow 分为三条操作路径:
- 读取配置:
+workflow-list定位流程,+workflow-get读取title、status和完整steps执行图。 - 写入配置:
+workflow-create创建完整定义,+workflow-update更新完整定义;构造或修改配置前读取 Workflow,由该入口继续路由 step 类型和 schema。 - 运行状态控制:
+workflow-enable/+workflow-disable启用或停用已有 Workflow,不修改 steps 执行图。
Advanced Permission(AdvPerm)
AdvPerm 为 Base 开启细粒度权限模式;Role 在此基础上配置 Base、Table、View、Field、Record、Dashboard 和 Docx 等资源的访问能力,适合按团队或职责限制可见范围、编辑能力、复制下载和数据访问规则。
读取 AdvPerm: +base-get 查看 is_advanced,+role-list / +role-get 查看角色。写入 AdvPerm: +advperm-enable / +advperm-disable 启停高级权限,+role-create / +role-update / +role-delete 管理角色。先读 权限与角色,由该入口继续路由权限 JSON 协议。
Docx Block
Docx Block 是组织在 Base 目录中的飞书文档资源,适合把说明、方案和报告与数据表、仪表盘及流程放在同一 Base 中;正文仍使用标准 Docx 数据模型。
从 Base Block 资源目录按 --type docx 定位文档并取得 docx_token;正文读取、创建与编辑使用 lark-doc。
Folder Block
Folder Block 只承担 Base 目录分组和层级组织。用 +base-block-list --parent-id <folder_block_id> 读取直接子项。
通用执行契约
- Update 先确认命令是完整替换还是 delta:完整替换使用可信当前配置做 read-modify-write,delta 只提交目标变更。
- 优先用写入返回确认结果;返回不足以确认或任务明确要求核验时再读回目标。
- 命令具有 confirmation gate 时,确认目标和影响后使用
--yes。
不在本 Skill 范围
- 认证、初始化、scope、身份切换和授权恢复 →
lark-shared - Excel、CSV、
.base等本地文件与 Base 之间的导入/导出转lark-drive;在线复制走+base-copy - Base 内嵌 Docx 的正文编辑 →
lark-doc;电子表格内容操作 →lark-sheets
Base Advanced Permission 与 Role
This is the module entry point for Base advanced permissions and roles. Use it to choose commands and understand safety boundaries. For the permission JSON itself, use Role Permission Schema.
Command selection
| Goal | Command | Notes |
|---|---|---|
| Check advanced permission status | +base-get | Read data.base.is_advanced. There is no +advperm-get command. |
| Enable advanced permissions | +advperm-enable | Required before creating or updating roles. Caller must be a Base admin. |
| Disable advanced permissions | +advperm-disable | High-risk write. Disabling invalidates existing custom roles. |
| Locate roles | +role-list | Returns role summaries. Use +role-get for full config. |
| Inspect one role | +role-get | Use before updating a role or deciding whether a role can be deleted. |
| Create a custom role | +role-create | Supports custom_role only. Read Role Permission Schema before constructing --json. |
| Update a role | +role-update | Delta merge. Read current config first, then send only intended changes. |
| Delete a role | +role-delete | Custom roles only. System roles cannot be deleted. |
Required order
At the start of a role workflow, before the first +role-list, +role-get, +role-create, +role-update, or +role-delete call:
- Run
lark-cli base +base-get --base-token <base_token>and inspectdata.base.is_advanced. - If
is_advancedisfalse, run+advperm-enablebefore the role command. If the user did not authorize enabling advanced permissions, stop and explain the required precondition. - Run the requested role commands only after
is_advancedistrueor+advperm-enablesucceeds. Reuse that confirmed status for later role calls in the same workflow.
Do not probe with +advperm-get: that command is not supported. Do not use an empty +role-list response to infer the advanced permission status; a disabled Base can also return an empty list.
Safety boundaries
- Role operations require advanced permissions to be enabled and the caller to be a Base admin.
+role-createcreates custom roles only.+role-deleteis only for custom roles. System roles such as editor/reader can be configured within supported limits, but cannot be deleted.+role-updateuses delta merge: omitted fields remain unchanged, but identity fields such asrole_nameandrole_typeshould match the current target role.+advperm-disableinvalidates existing custom roles; confirm the target Base and user intent before passing--yes.
Common Fewshots
Use these fewshots for simple role changes. For table, field, record, dashboard, docx, or filter permission details, switch to Role Permission Schema.
Create a custom role that keeps copy/download disabled:
lark-cli base +role-create \
--base-token <base_token> \
--json '{"role_name":"Reviewer","role_type":"custom_role","base_rule_map":{"copy":false,"download":false}}'Rename a role while preserving its type:
lark-cli base +role-update \
--base-token <base_token> \
--role-id <role_id> \
--json '{"role_name":"Finance Reviewer","role_type":"custom_role"}' \
--yesGrant read-only access to one table:
lark-cli base +role-update \
--base-token <base_token> \
--role-id <role_id> \
--json '{"role_name":"Finance Reviewer","role_type":"custom_role","table_rule_map":{"Orders":{"perm":"read_only"}}}' \
--yesJSON SSOT
Use Role Permission Schema for:
AdvPermBaseRoleConfigtop-level structure.base_rule_map,table_rule_map,dashboard_rule_map, anddocx_rule_map.- Table, view, field, record, dashboard, and docx permission values.
- Filter permission JSON.
- Default permission strategy and risk rules.
BaseApp Block data_config
本文件说明 BaseApp 组件 data_config 的 CLI 映射与操作约束,不复制完整字段 Schema。App 图表的每个 data_sources[] 元素复用 Dashboard Block 配置 的字段取值、筛选、分组、排序及规范化规则;区别是 Dashboard 使用扁平单数据源结构,而 App 图表在顶层使用共享的 base_token 和多数据源 data_sources[]。列表组件是 App 独有协议,不复用 Dashboard 图表结构。本文所称“组件协议”是指 CLI 随版本发布的 API 元数据、本文明确列出的约束及实际服务端校验结果。
类型映射
- 图表:
--type column|bar|line|pie|ring|area|combo|scatter|funnel|wordCloud|radar|statistics - 富文本:
--type text(与 Dashboard 文本组件同名同义) - 列表:
--type list --sub-type standard|grouped|collapsible|card|detail - 列表省略
--sub-type时默认standard type/sub_type创建后不可修改
外层请求字段
- Create 只发送
name、type、按需发送的sub_type和data_config。name、type必填;图表和列表的data_config必填,富文本可省略。 - 标准列表未显式指定
--sub-type时,不发送sub_type,由服务端使用standard默认值;其他列表类型必须发送对应sub_type。 - 图表和富文本不得发送
sub_type。 - Update 只发送
name、data_config,且至少提供一个;未传字段保持不变,不允许修改type、sub_type。 - 布局、位置、尺寸、
show_title等展示配置不属于本期公开 Create/Update 请求字段,CLI 不提供或提升这些字段。
列表配置
列表公共数据源字段为单值 base_token 和 table_name。每个列表最多关联一个 Base,且该 Base 必须位于 App 所在的同一 Workspace。
按组件协议,各 subtype 使用以下字段组:
- 公共:
base_token、table_name、filter、sort_by standard/grouped/collapsible:columns、group_bycard:fields、card_configdetail:fields、detail_configcolumns和fields都是可选字段。未指定时 CLI 不发送,由服务端使用产品默认字段。- 只有用户显式指定
columns/fields时才发送;显式传[]表示明确发送空数组,不能作为默认值自动补入。 filter、sort_by、group_by、card_config、detail_config也都是可选字段;未指定时不发送。- 列表 Create 的
data_config必填,其中只有base_token和table_name是顶层必填字段。 - 可选对象一旦传入,其内部必填项仍须满足协议,例如
filter必须包含conjunction和 1~50 项conditions。
不要添加协议未定义的语义校验,尤其不要假设:
- detail/card 必须有 title;
- grouped/collapsible 必须或只能有一个 group_by;
- fields 存在 role 或 visible 属性。
未知顶层字段会被本地校验拒绝;只有确认 CLI 校验与最新协议不一致时才使用 --no-validate。
创建示例
lark-cli base +app-block-create \
--app-token <app_token> --page-id <page_id> \
--name "订单列表" \
--type list --sub-type standard \
--data-config '{"base_token":"<base_token>","table_name":"订单"}'字段的具体对象结构与必填性以 CLI 当前版本的 API 元数据和服务端校验结果为准,不在这里猜测未公开属性。
更新语义
下面是只更新顶层 filter 的示例,适用于协议将 filter 定义在 data_config 顶层的组件(所有列表 subtype 均可使用)。组件类型在创建后不可修改,所以 update 命令不再传 --type。App 图表的 filter 定义在对应的 data_sources[] 元素中;更新图表筛选时必须按图表结构传入完整 data_sources,不能把 filter 提到顶层。
lark-cli base +app-block-update \
--app-token <app_token> --page-id <page_id> --block-id <block_id> \
--data-config '{"filter":{"conjunction":"and","conditions":[{"field_name":"状态","operator":"is","value":"已完成"}]}}'- CLI 只发送用户显式传入的字段。
- 未传字段由服务端保持不变。
- 不为 update 注入 create 默认值,不先读取后拼成全量配置。
- 数组/对象字段的替换粒度以组件协议和服务端校验结果为准。
图表与富文本
App 图表是多数据源结构(ChartDataConfig),与 Dashboard 的扁平单源结构不同。 顶层用一个 base_token(所有数据源共用),table_name / series / count_all / group_by / filter 下沉到每个 data_sources[] 元素里;顶层另有可选的 data_source_mode 和 sort。每个数据源内部各字段的取值逻辑与 Dashboard Block 配置 完全一致(series[].rollup 大写、group_by[].sort 小写等),CLI 对每个 data_sources[] 元素复用同一套规范化与校验。富文本使用 --type text,配置为 {"text":"..."},无数据源;Create 时可省略 data_config,等价于空文本。
text 内容怎么取:text 组件没有
/data接口,走+app-block-get-data会被服务端兜底成通用 500。改用+app-block-get --block-id <widget_id>直接读data_config.text(Markdown 原文)。图表仍走+app-block-get-data --block-id <chart_token>。
顶层参数:
| 参数 | 必填 | 取值 | 说明 |
|---|---|---|---|
base_token | 是 | string | 数据所在 Base 的 token;所有数据源共用同一个值。App 命令不带 --base-token,只能写在 data_config 内 |
data_sources | 是 | ChartDataSourceConfig[] | 有序数组,至少一项 |
data_source_mode | 否 | aggregate / compare | aggregate(默认)在横轴聚合数据源;compare 按数据源拆分系列 |
sort | 否 | `{type: group\ | value\ |
每个 data_sources[] 元素:table_name(必填)、series 与 count_all=true 二选一、group_by(最多 2 项,statistics 不允许)、filter。
{
"base_token": "A2f5boKjfazMzesI9zKbmugTc4T",
"data_sources": [
{
"table_name": "数据表",
"count_all": true,
"group_by": [
{ "field_name": "文本", "mode": "integrated", "sort": { "type": "value", "order": "desc" } }
]
}
]
}对应命令(单数据源计数柱状图):
lark-cli base +app-block-create \
--app-token <app_token> --page-id <page_id> \
--name "文本分布" --type column \
--data-config '{"base_token":"A2f5boKjfazMzesI9zKbmugTc4T","data_sources":[{"table_name":"数据表","count_all":true,"group_by":[{"field_name":"文本","mode":"integrated","sort":{"type":"value","order":"desc"}}]}]}'多数据源示例(两张表各出一条系列,按数据源拆分):
lark-cli base +app-block-create \
--app-token <app_token> --page-id <page_id> \
--name "销售与成本" --type combo \
--data-config '{"base_token":"bas_xxx","data_source_mode":"compare","data_sources":[{"table_name":"销售表","group_by":[{"field_name":"月份","sort":{"type":"group","order":"asc"}}],"series":[{"field_name":"销售额","rollup":"SUM"}]},{"table_name":"成本表","group_by":[{"field_name":"月份","sort":{"type":"group","order":"asc"}}],"series":[{"field_name":"成本","rollup":"SUM"}]}],"sort":{"type":"group","order":"asc"}}'Update 语义:传入 data_sources 即全量替换整个有序数组;修改 base_token 时必须同时传入完整 data_sources。请求不得包含 sub_type(平滑/堆积/百分比等展示变体走产品默认值)。布局、位置、尺寸和展示配置不属于本期公开 Create/Update 协议。其他请求字段以 CLI 当前版本的 API 元数据和服务端校验结果为准。
BaseApp(应用模式)操作指引
先读 `../../lark-shared/SKILL.md`。接口和组件字段以 CLI 当前版本的 API 元数据、组件配置 reference 和服务端校验结果为准;不要从组件名称推断额外约束。
不支持能力:先判断并停止
复制 BaseApp
本期没有 BaseApp 复制命令。用户要复制或克隆既有 BaseApp 时,直接说明当前 CLI 无法完成并停止;不要继续探索浏览器、OpenAPI 或创建类命令等替代通道,也不要发起任何写请求。
+base-copy只支持 Base,不支持 BaseApp;不得向它传入app_token,也不得把复制出的 Base 描述为应用副本。+app-create只创建全新空 BaseApp,不复制既有页面和组件。- 不要使用 Drive copy 或其他 Base shortcut 拼装、模拟或冒充 BaseApp 复制。
创建或归属 PageGroup
当前第一阶段的页面层级能力只支持顶级 Page 节点。PageGroup 的创建、归属设置,以及把现有 Page 移入页面组均不支持。
最终答复必须同时说明上述正向支持范围和负向限制,不能只说 PageGroup 不支持。用户命中这些诉求时,直接说明当前 CLI 无法完成并停止;不要继续探索浏览器、OpenAPI 或普通 Page 命令等替代通道,也不要读取页面后声称能完成分组或发起任何写请求。
从 Workspace 移出或移除资源
当前 CLI 只支持用 +workspace-move-in 把 Base 或 BaseApp 移入 Workspace,不支持从 Workspace 移出或移除资源,也没有 workspace move-out / workspace remove 命令。这类请求必须先完成只读定位,再说明限制并停止,顺序不可调换:
- Workspace URL 含
/base/workspace/<workspace_token>时,提取其中的真实workspace_token,不要把完整 URL 当作命令参数。 - 在同一轮立即执行
lark-cli base +workspace-entity-list --workspace-token <workspace_token> --page-size 30 --as user;若has_more=true,继续分页直到完整。该查询是必要的只读定位步骤,不要把它留成等待用户再次选择的可选项,也不要用--help代替真实查询。 - 用服务端返回的
entities[].name、entity_type、token和url忠实判断目标。名称完全匹配时报告真实对象;没有完全匹配时明确说明不存在精确同名实体,并原样列出可能相关的候选。不得自动去掉或补齐前后缀,也不得仅凭名称相似就声称已经定位目标。用户直接给出 token 时仍要忠实报告该 token 对应的实际名称。 - 定位结果报告完后,明确说明当前 CLI 无法执行 Workspace 移出/移除,并停止,不要发起任何写请求。用户在任一步骤中取消时立即停止,取消后不再调用工具。
lark-cli drive +move 只改变 Base 或 BaseApp 在云盘中的目录位置,不改变其 Workspace 归属,不能作为移出 Workspace 的替代方案。不要继续探索 Drive move/delete、另一个 Workspace 的 +workspace-move-in、浏览器、OpenAPI 或源码来拼装或冒充该操作;只有用户后续明确提出另一项受支持的操作时,才执行新的写入。
Token 与命令
| 对象 | 标识 | 命令 |
|---|---|---|
| Workspace | workspace_token | +workspace-create / +workspace-entity-list / +workspace-move-in |
| BaseApp | app_token | +app-create/get;重命名和删除见下方 |
| Base | base_token | +base-create 返回;表、字段、记录命令使用它 |
| Page | page_id | +app-page-list/get/create/update/delete |
| Block | block_id | +app-block-list/get/create/update |
页面和组件命令使用 app_token;Base 数据命令使用 base_token。+app-block-get-data 使用 app_token + base_token + chart_token:CLI 参数名仍为 --block-id,但必须传组件返回的 chart_token,不能传普通 block_id。请求路径与仪表盘图表数据接口相同。
BaseApp / AppMode 是 Base 域能力。用户提供 /app/ 链接时,先用 +url-resolve;它会返回 app_token,并忠实提取链接实际携带的 workspace_token 与 page_id。直接使用本指引和 lark-cli base +...,不要先尝试 lark-cli apps。
查询应用
lark-cli base +app-get --app-token <app_token>- 没有
lark-cli base +app-list。需要列出某个 Workspace 内的 BaseApp 时,唯一列表入口是:
lark-cli base +workspace-entity-list \
--workspace-token <workspace_token> \
--type baseapp \
--page-size 30- 响应中的
pages是页面摘要。 ref的结构是Base token -> 当前组件引用的 Table 名称数组。需要操作被引用 Base 时,使用ref的 key 作为base_token。ref只描述当前组件已经引用的数据源;没有被组件引用的 Base 不会出现在其中。
查询页面与组件
lark-cli base +app-page-list --app-token <app_token> --page-size 100
lark-cli base +app-block-list \
--app-token <app_token> \
--page-id <page_id> \
--page-size 100+app-get已返回足够的页面摘要时,可直接取得目标page_id;需要完整页面目录或分页确认时再用+app-page-list。+app-page-list返回的某个 Page 若name为空字符串,表示当前用户对该 Page 无权限,不表示 Page 没有标题。报告该权限状态,不要将其page_id用于后续页面或组件读写。- 只需列表摘要时不要逐个调用
+app-block-get复核;仅在用户需要单个组件详情时使用 get。 +app-block-list返回type=unsupported的组件时,只能通过列表摘要识别它的存在。当前 CLI 不支持读取详情、读取计算数据或修改此类组件;不要调用+app-block-get、+app-block-get-data或+app-block-update,这些请求会报错。
创建 Workspace
lark-cli base +workspace-create \
--name "AppMode-空白评测空间" \
--as user创建应用
lark-cli base +app-create \
--name "销售应用" \
--workspace-token <workspace_token> \
--as user+app-create没有--base-token。--workspace-token必填;+app-create只调用 App 创建接口,不创建 Workspace、Base,也不移动资源。--theme-style可选,支持default|cloudBlue|fresh|softLight|future|technology。- 记录输出中的
app_token和workspace_token。
新建应用的默认 Page 复用
+app-create 会同时生成一个系统默认 Page,但创建响应不返回它的 page_id。用户未明确要求其他页面结构时,创建 App 后先读取应用取得该 Page,将其重命名并直接用作用户所需的第一个页面;不要用 +app-page-create 另建第一个页面:
lark-cli base +app-get --app-token <app_token> --as user
lark-cli base +app-page-update \
--app-token <app_token> \
--page-id <default_page_id> \
--name "<page_name>" \
--as user在上述默认流程中,随后在这个 Page 上逐个串行执行 +app-block-create,同一 Page 的多个组件不得并发创建。只有用户确实需要额外页面时,才在复用默认 Page 之后调用 +app-page-create。用户明确要求保留默认 Page、另建独立页面或采用其他页面结构时,按用户要求处理。
若 +app-get 暂时没有返回默认 Page,重新执行 +app-get 或 +app-page-list 获取它,不要创建替代 Page。若创建组件返回布局重叠,先停止同页的其他并发写入,用 +app-block-list 确认已成功组件,再留在原 Page 上串行重试失败步骤;不要通过新建 Page、删除默认 Page 或整页重建来规避冲突。
创建应用的自然语言编排
先根据用户是否指定 Workspace 和现有 Base 选择流程,再调用原子 shortcut:
| 用户提供的信息 | 执行流程 |
|---|---|
| Workspace + 现有 Base | 确认 Base 位于该 Workspace → +app-create;不创建备用 Base |
| Workspace,未指定 Base | +app-create → +base-create 创建空 Base → +workspace-move-in |
| 未指定 Workspace,指定现有 Base | 先确认该 Base 所属 Workspace;能确定时在该 Workspace 执行 +app-create,不能确定时请用户提供 Workspace;不创建备用 Base |
| Workspace 和 Base 都未指定 | +workspace-create → +app-create → +base-create 创建空 Base → +workspace-move-in |
应用模式的列表组件只能引用同一 Workspace 内的一个 Base。用户指定现有 Base 时,不要因为 +app-create 没有接收 base_token 就额外创建 Base;后续在组件 data_config.base_token 中引用该 Base。
多步编排中,每个成功的 shortcut 都会立即产生资源且不自动回滚。后续步骤失败时,明确报告已经成功创建的 Workspace、App 或 Base 及其 token;用户要求继续时,只重试失败步骤,不要重复创建已经成功的资源。
读取图表计算结果
lark-cli base +app-block-get-data \
--app-token <app_token> \
--base-token <base_token> \
--block-id <chart_token>--block-id的值必须取图表组件摘要中的chart_token,不能使用组件的普通block_id。base_token使用当前图表组件data_config.base_token;一个 App 引用多个 Base 时,不要从+app-get ref中任意选择一个 key。page_id不参与请求。- 返回协议与
+dashboard-block-get-data完全一致。
重命名应用
lark-cli drive files patch \
--file-token <app_token> \
--type bitable \
--data '{"new_title":"新名称"}'BaseApp 与 Base 在 Drive 文件接口中都使用 type=bitable。new_title 只更新应用标题,不会重命名它引用的 Base,也不会修改 Page 或 Block。
删除应用
lark-cli drive +delete --file-token <app_token> --type bitable --yes- 删除 BaseApp 应用本体需要切到
lark-drive。 - BaseApp 与 Base 在 Drive 删除接口中都使用
--type bitable;删除 BaseApp 时--file-token传app_token。 - 这是高风险写操作;执行前先确认
app_token来自+app-get或+workspace-entity-list。
Page
本期不支持的 Page 能力
Page 复制和页面图标均不在本期范围。用户提出复制 Page、复制页面、克隆页面、沿用页面图标、设置或修改页面图标等需求时:
- 明确说明当前 CLI 不支持该能力,并确认本次没有执行任何写入。
- 不得调用
+app-page-create冒充完整复制;空 Page 不包含原 Page 的内容、组件或图标。 - 不得尝试使用其他 shortcut 拼装、模拟或声称完成 Page 复制或图标设置。
- 在最终答复中将以下替代能力单独成段说明,但不要自动执行:
可用替代能力(本次未执行):当前 CLI 可以新建一个空 Page,但不会复制原 Page 的内容、组件或图标。如需新建空 Page,请明确告诉我。
只有用户后续明确要求新建空 Page,才可以调用 +app-page-create。
lark-cli base +app-page-list --app-token <app_token>
lark-cli base +app-page-create --app-token <app_token> --name "总览"
lark-cli base +app-page-update --app-token <app_token> --page-id <page_id> --name "经营总览"
lark-cli base +app-page-delete --app-token <app_token> --page-id <page_id> --yes- 对新建 App,用户未明确要求其他页面结构时,必须按新建应用的默认 Page 复用将系统默认 Page 用作用户所需的第一个页面;
+app-page-create只用于用户要求的额外页面。 - 同一 App 内 Page 名称必须唯一。创建或更新名称前,CLI 会读取页面列表;更新时排除当前 Page。
- 同一 Page 内组件名称必须唯一。
+app-block-create会分页读取该 Page 的全部组件并在创建前检查重名。 - 本期没有 Page arrange,也没有 Block delete;Block 的
type/sub_type创建后不可修改。详见本期不支持的能力。
本期不支持的能力
下列能力本期不存在。用户提出时,直接说明不支持并给出可选的替代方向,不要用 Dashboard 或其他域的同名能力顶替。
| 用户诉求 | 本期状态 | 正确动作 |
|---|---|---|
| 自动排版 / 重新布局 / 美化页面组件 | 没有 App page arrange | 直接告知不支持;不要调用 +dashboard-arrange |
| 删除页面组件 | 没有 App block delete | 直接告知不支持,只能在 UI 处理;不要调用 +dashboard-block-delete |
| 修改组件位置 / 大小 / 置顶 | 布局、位置、尺寸不属于公开 Create/Update 协议 | 直接告知不支持;不要用 +app-block-update 做空更新伪装成移动 |
修改已有组件的 type/sub_type | type/sub_type 创建后不可修改 | 先读取当前 Block;无论是否已为目标类型,最终答复都要说明此约束。已匹配时说明无需写入;不匹配时说明只能在 UI 处理;不得调用或承诺用 +app-block-update 修改类型 |
| 修改已存在 App 的主题 | --theme-style 只在 +app-create 时生效 | 直接告知不支持;如确有必要,说明只能新建 App 时指定主题 |
读取或修改 type=unsupported 的组件 | 列表仅用于识别该组件存在,详情读取、计算数据读取和修改均不支持 | 直接告知不支持;不要调用 +app-block-get、+app-block-get-data 或 +app-block-update,这些请求会报错 |
+dashboard-* 命令只作用于 Base 内的仪表盘,dashboard_id 是 blk 开头、组件 ID 是 cht 开头;AppMode 的 pge 页面和 wgt 组件不属于它们的作用域。缺少能力时不要用这些命令试探,包括 --help 和 --dry-run:一次调用就是一次错误的能力归属判断。
列表组件
创建列表时使用 --type list 与 --sub-type standard|grouped|collapsible|card|detail。省略 --sub-type 时默认 standard。
lark-cli base +app-block-create \
--app-token <app_token> \
--page-id <page_id> \
--name "待处理订单" \
--type list \
--sub-type standard \
--data-config '{"base_token":"<base_token>","table_name":"订单"}'data_config.base_token是单值:每个列表最多选择一个 Base。- Base 必须在当前 App 的同一个 Workspace;CLI 写入前校验。
- 完整字段协议读 lark-base-app-block-data-config.md。
更新组件
+app-block-update 只发送显式传入的 data_config 字段。未传字段保持不变;数组或对象字段是否整体替换,以组件配置 reference和服务端校验结果为准。不要为了“补全”先读取并提交全量配置。
常见恢复
| 现象 | 动作 |
|---|---|
status=partial | 告知已完成/失败步骤;用户要求继续时执行 retry.command |
| Page 重名 | 先 +app-page-list,选择唯一名称后重试 |
| 组件重名 | 先 +app-block-list,为该 Page 内的新组件选择唯一名称后重试 |
| 列表 Base 不在同一 Workspace | 用 +workspace-entity-list 核对;选择同 Workspace Base |
| 列表协议校验失败 | 读取组件协议文档;不要推断 title、group_by 数量或 field role |
| Block 类型选错 | 本期无法删除且类型不可改,只能在 UI 处理后重新创建 |
| 用户要 arrange / 删组件 / 调位置 / 改主题 | 按本期不支持的能力直接告知不支持;不要改用 +dashboard-* 命令 |
Base Dashboard Block 配置
Block 的 data_config 字段因 type 不同而变化。本文档是 Dashboard block 扁平单数据源 data_config 的单一事实来源(SSOT),包含组件类型、字段结构、筛选格式、约束和可复制模板。BaseApp 图表的外层结构不同,但每个 data_sources[] 元素复用本文的字段取值、筛选、分组、排序及规范化规则;创建或更新 App 组件时,还必须读取 BaseApp Block data_config 了解共享 base_token、多数据源封装,以及 App 独有的列表组件协议。
支持的组件类型(type 枚举)
| type 值 | 说明 |
|---|---|
column | 柱状图 |
bar | 条形图 |
line | 折线图 |
pie | 饼图 |
ring | 环形图 |
area | 面积图 |
combo | 组合图 |
scatter | 散点图 |
funnel | 漏斗图 |
wordCloud | 词云 |
radar | 雷达图 |
ranking | 排行榜 |
statistics | 指标卡 |
nps | NPS 图 |
text | 文本(支持 Markdown) |
字段类型与操作符速查(AI 决策用)
先用
+field-list/+field-get确认字段type;本节使用当前字段接口里的 canonical 类型名:number、text、select、datetime、checkbox、user。NPS 使用的Rating是 Dashboard 服务端识别的评分字段语义,不属于当前字段操作符速查里的通用筛选类型。
text: is, isNot, contains, doesNotContain, isEmpty, isNotEmpty
number: is, isNot, isGreater, isGreaterEqual, isLess, isLessEqual, isEmpty, isNotEmpty
select(multiple=false): is, isNot, isEmpty, isNotEmpty
select(multiple=true): is, isNot, contains, doesNotContain, isEmpty, isNotEmpty
datetime: is, isGreater, isLess, isEmpty, isNotEmpty
checkbox: is (value: true/false)
user / created_by / updated_by: is, isNot, isEmpty, isNotEmptyisGreaterEqual / isLessEqual 不是全局不支持:它们可用于 number,但不能用于 datetime / created_at / updated_at。日期范围必须用 isGreater / isLess 配合 ExactDate;不要把数字字段的操作符集合套到日期字段上。
data_config 通用结构
| 字段 | 类型 | 说明 |
|---|---|---|
table_name | string | 关联数据表名称 |
series | [{ "field_name": "xxx", "rollup": "SUM" }] | 指标/Y 轴(与 count_all 二选一)。rollup 支持 SUM / MAX / MIN / AVERAGE |
count_all | boolean | COUNTA 聚合,统计所有记录数(与 series 二选一) |
group_by | [{ "field_name": "xxx", "mode": "integrated", "sort": {...} }] | X 轴分组维度。mode 和 sort 的要求因组件类型而异,见下方说明 |
filter | object | 筛选条件 |
filter.conjunction | "and" / "or" | 筛选逻辑 |
filter.conditions | [{ "field_name", "operator", "value" }] | 筛选条件数组,value 类型因字段类型而异(见下方 filter 格式规则) |
category_range | [min, detractorMax, passiveMax, max] | NPS 三段边界,仅 nps 类型支持;首尾必须等于 Rating 字段量程,首尾匹配由服务端按字段元数据校验 |
text 类型特殊结构
text 类型组件用于展示富文本内容,不需要数据源配置(无 table_name、series、group_by、filter)。
| 字段 | 类型 | 说明 |
|---|---|---|
text | string | 必填。支持 Markdown 语法,详见下方说明 |
支持的 Markdown 语法:
| 语法 | 示例 | 效果 |
|---|---|---|
| 一级标题 | # 标题 | 大标题 |
| 二级标题 | ## 标题 | 中标题 |
| 三级标题 | ### 标题 | 小标题 |
| 加粗 | **文字** | 文字 |
| 斜体 | *文字* | 文字 |
| 删除线 | ~~文字~~ | ~~文字~~ |
| 有序列表 | 1. 项目 | 1. 项目 |
| 无序列表 | - 项目 | - 项目 |
注意:以上未提及的 Markdown 语法(如链接、图片、代码块、表格等)均不支持。
group_by 详细说明
mode 枚举
| mode | 含义 | 适用场景 |
|---|---|---|
integrated | 聚合分组(默认) | 绝大部分场景,按字段值分组统计 |
enumerated | 多值拆分统计 | 多选、人员等多值字段,将每个选项/人员拆开独立统计 |
多选、人员等多值字段默认用
enumerated;其他字段默认用integrated。
sort 排序
| sort.type | 含义 | 典型场景 |
|---|---|---|
group | 按横轴值排序 | 按月份升序、按品类名字母序 |
value | 按纵轴值排序 | 按销售额从大到小 |
view | 按数据源记录顺序 | 保持原表行序(不常用) |
sort.order:asc(升序)/ desc(降序)
只要写 sort 对象,就需要明确排序方向。CLI 会把 sort.type 为 group 或 view 且缺少 order 的情况规范化为 order:"asc";sort.type:"value" 必须显式写 order:"asc" 或 order:"desc",因为指标值排序方向会改变业务含义。
如果表中行序就是业务顺序,首次创建 block 时就一次性设置 sort:{"type":"view","order":"asc"} 保留行序,避免创建后再二次更新排序条件。
ranking 排行榜专属契约
排行榜只支持一个分组和一个指标,公开字段固定为 table_name、series/count_all、group_by、filter、limit_size:
group_by必填且长度严格为 1;mode仅支持integrated/enumerated。series长度严格为 1,且与count_all:true二选一;rollup仅支持SUM/MAX/MIN/AVERAGE。- 排序只写在
group_by[0].sort,type只能为value,order为asc/desc。创建时省略排序默认按指标值降序。 limit_size是 Top N,取值为1..500的整数,创建时省略默认10。- 不支持顶层
sort、公开ranking对象或头像开关。
更新 ranking 时,data_config 是顶层 patch:只传 limit_size 只改 Top N;只传 group_by 只替换唯一分组和排序;只传 series 或 count_all:true 只切换指标;只传 filter 只替换筛选。切换 table_name 时必须在同一 patch 提供新的 group_by 以及 series 或 count_all:true;未传 filter 保留原筛选,未传 limit_size 保留原 Top N。
示例 — 柱状图按销售额降序:
{
"table_name": "订单表",
"series": [{ "field_name": "金额", "rollup": "SUM" }],
"group_by": [{ "field_name": "类别", "mode": "integrated", "sort": {"type": "value", "order": "desc"} }]
}filter 格式规则
基本结构:
{
"filter": {
"conjunction": "and",
"conditions": [
{ "field_name": "字段名", "operator": "操作符", "value": "值" }
]
}
}多条件示例(and/or):
{
"filter": {
"conjunction": "and",
"conditions": [
{ "field_name": "状态", "operator": "is", "value": "已完成" },
{ "field_name": "金额", "operator": "isGreater", "value": 1000 }
]
}
}操作符:
| 操作符 | 含义 | 是否需要 value |
|---|---|---|
is | 等于 | 是 |
isNot | 不等于 | 是 |
contains | 包含 | 是 |
doesNotContain | 不包含 | 是 |
isEmpty | 为空 | 否 |
isNotEmpty | 不为空 | 否 |
isGreater | 大于 | 是 |
isGreaterEqual | 大于等于 | 是 |
isLess | 小于 | 是 |
isLessEqual | 小于等于 | 是 |
各字段类型的 value 格式:
| 字段类型 | value 类型 | 适用操作符 | 示例 |
|---|---|---|---|
text | string | is, isNot, contains, doesNotContain, isEmpty, isNotEmpty | {"field_name":"姓名","operator":"contains","value":"张"} |
number | number | is, isNot, isGreater, isGreaterEqual, isLess, isLessEqual, isEmpty, isNotEmpty | {"field_name":"金额","operator":"isGreater","value":0} |
select (multiple=false) | string(选项名) | is, isNot, isEmpty, isNotEmpty | {"field_name":"状态","operator":"is","value":"已完成"} |
select (multiple=true) | string[](选多个)/ string(选单个) | is, isNot, contains, doesNotContain, isEmpty, isNotEmpty | 多选传数组如 ["标签1","标签2"];单选传单个字符串 |
datetime / created_at / updated_at | ["ExactDate", Unix 毫秒时间戳] | is, isGreater, isLess, isEmpty, isNotEmpty | {"field_name":"创建日期","operator":"isGreater","value":["ExactDate",1704038400000]} |
checkbox | boolean | is | {"field_name":"已审核","operator":"is","value":true} |
user / created_by / updated_by | string 或 string[](用户 ID,格式 ou_xxx)。不知道 open_id 时先用 lark-cli contact +search-user --query "<姓名/邮箱/手机号>" --as user 查 id。 | is, isNot, isEmpty, isNotEmpty | {"field_name":"负责人","operator":"is","value":"ou_xxxxxxxxxxxxxxxx"} |
| 所有类型(为空/不为空) | 不需要 value | isEmpty, isNotEmpty | {"field_name":"备注","operator":"isEmpty"} |
value类型因字段而异,可为string | number | boolean | string[] | ["ExactDate", number],需按上表构造。
日期筛选
图表 data_config.filter 筛选 datetime / created_at / updated_at 字段时:
- 有值条件只能使用
is、isGreater或isLess,不得使用isGreaterEqual或isLessEqual。 value必须写成["ExactDate", <Unix 毫秒时间戳>],不得直接传裸时间戳。isEmpty/isNotEmpty不传value。
日期区间示例:
{
"filter": {
"conjunction": "and",
"conditions": [
{
"field_name": "派单日期",
"operator": "isGreater",
"value": ["ExactDate", 1785686400000]
},
{
"field_name": "派单日期",
"operator": "isLess",
"value": ["ExactDate", 1786032000000]
}
]
}
}约束与本地校验
- 必填与互斥
- 图表类型必填:
table_name - text 类型必填:
text - 互斥:
series与count_all二选一,且至少提供其一(仅图表类型) - nps 类型必填:
table_name、长度为 1 的group_by;group_by[0].mode可省略,省略时按integrated处理,显式传入时也只能为integrated;不支持group_by[0].sort和series;count_all可省略,出现时只能为true - text 类型不支持:
series、count_all、group_by、filter - 长度/结构
group_by最多 2 个;每项field_name必填group_by[].sort.type取值group|value|view;order取值asc|desc- 规范化(CLI 自动处理;
--no-validate时不生效,data_config原样透传给后端) series[].rollup自动转成大写(如sum→SUM)group_by[].sort.type/order自动转成小写group_by[].sort.type为group或view且缺少order时,自动补order:"asc";value排序不会自动补方向- 本地校验(可通过
--no-validate跳过) +dashboard-block-create默认对data_config做轻量校验;失败会聚合错误并给出修复建议+dashboard-block-update不带--type,所以不做按组件类型的强校验;但会对可解析的filter条件做轻量校验,包括conjunction、字段引用、operator和必需的value,并与 create 一样拦截非法number_format子字段(见下方 number_format 小节)- 仅需传入合法 JSON;CLI 不会擅自改写你的业务含义
可复制模板
按意图选择模板:
- 比较不同类别数值 → 柱状图 / 条形图
- 看趋势变化 → 折线图 / 面积图
- 看占比分布 → 饼图 / 环形图 / 词云
- 多指标对比 → 组合图
- 看两变量关系 → 散点图
- 看流程转化 → 漏斗图
- 看多维度评分 → 雷达图
- 显示单个指标 → 指标卡(统计数字或记录数)
- 统计满意度评分分布 → NPS 图(一个 Rating 字段 + 可选分段)
- 查看单维度 Top N → 排行榜
最小柱状图:
{
"table_name": "表名",
"series": [{ "field_name": "数值字段", "rollup": "SUM" }],
"group_by": [{ "field_name": "分组字段", "mode": "integrated" }]
}最小饼图/环形图(按分类字段统计行数占比):
{
"table_name": "表名",
"count_all": true,
"group_by": [{ "field_name": "分类字段", "mode": "integrated" }]
}折线图(按月趋势):
{
"table_name": "表名",
"series": [{ "field_name": "金额", "rollup": "SUM" }],
"group_by": [{ "field_name": "月份", "mode": "integrated", "sort": {"type":"group","order":"asc"} }]
}条形图(横向柱状图):
{
"table_name": "表名",
"series": [{ "field_name": "数值字段", "rollup": "SUM" }],
"group_by": [{ "field_name": "分组字段", "mode": "integrated" }]
}面积图(趋势填充):
{
"table_name": "表名",
"series": [{ "field_name": "数值字段", "rollup": "SUM" }],
"group_by": [{ "field_name": "时间字段", "mode": "integrated", "sort": {"type":"group","order":"asc"} }]
}组合图(柱+线等多指标对比):
{
"table_name": "表名",
"series": [
{ "field_name": "指标1", "rollup": "SUM" },
{ "field_name": "指标2", "rollup": "SUM" }
],
"group_by": [{ "field_name": "分类字段", "mode": "integrated" }]
}散点图(两变量相关性):
{
"table_name": "表名",
"series": [{ "field_name": "Y轴字段(数值/指标)", "rollup": "SUM" }],
"group_by": [{ "field_name": "X轴字段(分类/维度)", "mode": "integrated" }]
}漏斗图(流程转化):
先判断用户要看的数值语义:
- 当前数量:统计每个当前状态/阶段下有多少记录,例如“各环节当前数量”“当前阶段分布”。源表有状态/阶段字段时,直接用
count_all:true+group_by。 - 累计数量:统计到达该阶段及其后续阶段(后缀和)的累计数量,例如“流程转化”“从 A 到 B 各环节转化”。此口径假设流程单向、无跳阶/回退、记录不删除;不满足时须用状态变更历史,不能对当前快照累加。如果表中已有累计数量字段或阶段汇总表,直接用该字段画漏斗图;否则先计算累计数量,创建并写入 helper 汇总表后再画图。
当前数量:
{
"table_name": "表名",
"count_all": true,
"group_by": [{ "field_name": "状态字段", "mode": "integrated" }]
}累计数量:
{
"table_name": "流程汇总表名",
"series": [{ "field_name": "累计数量", "rollup": "SUM" }],
"group_by": [{ "field_name": "阶段字段", "mode": "integrated", "sort": {"type":"view","order":"asc"} }]
}如果只有当前状态数据但用户要看流程转化,需要先按业务阶段顺序计算每个阶段的累计数量,再创建 helper 汇总表(如:阶段、累计数量),用 +record-batch-create 一次写入后,按“累计数量”模板创建漏斗图。helper 表行序就是业务顺序时,首次创建 block 时一次性设置好 group_by.sort。
⚠️ 注意:helper 汇总表仅用于源表无法直接聚合出目标形态的场景(如上面的累计数量漏斗图)。只要能在源表上直接用
group_by+rollup(含AVERAGE)算出,就不需要新建 helper 表。
词云(文本频率):
{
"table_name": "表名",
"count_all": true,
"group_by": [{ "field_name": "文本字段", "mode": "integrated" }]
}雷达图(多维度评分):
{
"table_name": "表名",
"series": [
{ "field_name": "维度1", "rollup": "SUM" },
{ "field_name": "维度2", "rollup": "SUM" },
{ "field_name": "维度3", "rollup": "SUM" }
],
"group_by": [{ "field_name": "分类字段", "mode": "integrated" }]
}排行榜(按销售额取 Top 10):
{
"table_name": "订单表",
"series": [{ "field_name": "金额", "rollup": "SUM" }],
"group_by": [{ "field_name": "负责人", "mode": "integrated", "sort": {"type":"value","order":"desc"} }],
"limit_size": 10
}排行榜只更新 Top N:
{"limit_size": 20}指标卡(统计数字):
{
"table_name": "数据表",
"series": [{ "field_name": "数字", "rollup": "SUM" }]
}NPS 图(按 Rating 评分字段统计记录数):
{
"table_name": "问卷结果",
"group_by": [{ "field_name": "满意度评分", "mode": "integrated" }],
"category_range": [0, 6, 8, 10]
}NPS 的 group_by[0].field_name 必须指向 Base 的评分字段(Dashboard 内部识别为 Rating 语义)。调用方可通过 Base 字段详情或界面字段配置确认评分字段的最小值与最大值;CLI 只能做轻量 JSON 校验,字段类型、字段量程、category_range 首尾是否等于评分字段最小值和最大值由服务端按字段元数据校验。
category_range 可省略,服务端会按 Rating 字段自身量程生成默认分段。显式传入时数组长度必须为 4,且首尾必须等于 Rating 字段最小值和最大值。
指标卡(统计记录数):
{
"table_name": "数据表",
"count_all": true
}statistics 指标卡数值格式 number_format(可选)
仅 type: statistics 支持在 data_config 里加可选 number_format,控制数值展示格式与精度;不传时服务端会补 {"formatName":"digital"},precision 保持省略。其它组件类型不支持该字段:create 会被 CLI 直接拒绝(显式 --no-validate 可跳过),避免把后端严格 schema 错误延迟到请求阶段;update 不带 --type,由服务端结合组件现有类型裁决。
formatName(string,可选):必须精确匹配下表 5 个枚举之一,区分大小写(不同于series[].rollup会被自动转成大写,这里不做规范化,DIGITAL会被拒绝)。precision(integer,可选):小数位数,0到9的整数;2.5这类非整数会被本地拒绝。
| formatName | 含义 | 示例(precision=2) |
|---|---|---|
digital | 千分位数字(不传 number_format 时的服务端默认值) | 1,234.56 |
digital_without_separator | 无千分位数字 | 1234.56 |
percentage_rounded | 百分比 | 1,234.56% |
cyn_rounded | 人民币金额 | ¥1,234.56 |
dollar_rounded | 美元金额 | $1,234.56 |
指标卡(金额,保留 2 位小数):
{
"table_name": "订单表",
"series": [{ "field_name": "金额", "rollup": "SUM" }],
"number_format": { "formatName": "dollar_rounded", "precision": 2 }
}更新时
number_format按子字段合并:例如现有{"formatName":"digital","precision":2}时只传{"number_format":{"precision":0}},服务端会保留formatName:"digital"并把精度改为0。其它顶层 key 的更新策略见 lark-base-dashboard.md。
文本组件(Markdown 富文本):
{
"text": "# 🚀 一级标题\n这是一个 **加粗** *斜体* ~~删除线~~ 的示例。\n\n## 📌 二级标题\n1. 有序列表项 1\n2. 有序列表项 2\n\n### 📌 三级标题\n- 无序列表项 1\n- 无序列表项 2"
}注意:text 类型组件不需要
table_name、series、group_by、filter等数据源相关字段。
常见错误与修复
- 同时存在
series与count_all - 现象:后端/本地校验报互斥错误
- 修复:见「关键约束」章节的二选一规则
- 缺少
table_name - 现象:本地校验缺少必填字段
- 修复:指定数据源表名(使用表名,非表 ID)
series[].rollup大小写/取值不合法- 现象:本地校验提示枚举不支持
- 修复:改为
SUM|MAX|MIN|AVERAGE中之一(不区分大小写,CLI 会统一为大写;计数请使用count_all:true) group_by超出 2 个或字段名为空- 修复:保留前 2 个,或补齐
field_name - 排序枚举不合法
- 修复:
group_by.sort.type仅能为group|value|view;order为asc|desc - filter 写法不规范
- 修复:
conjunction取and|or;conditions[].operator必须在本页表格列举的范围内;除isEmpty/isNotEmpty外需提供value
坑点
count_all与series二选一 — 两者不能同时使用- filter
value类型因字段而异 — 文本/单选为 string,数字为 number,日期为毫秒时间戳,多选/人员可为 string[],复选框为 boolean;isEmpty/isNotEmpty不需要 value data_config结构随type变化 — 不同组件类型的字段不同,创建前务必确认类型对应的字段- 表名用 name,不是 ID —
table_name对应的是表名称(如「订单表」),不是table_id
base +dashboard-block-get-data
前置条件: 先阅读 lark-base-dashboard.md 了解 dashboard 整体工作流。
获取仪表盘图表组件(block)的最终计算结果,返回一份适合 AI 直接消费的图表协议 JSON。
这个命令适合以下场景:
- 读取柱状图 / 条形图 / 折线图 / 饼图 / 环形图 / 面积图 / 组合图 / 散点图 / 漏斗图 / 雷达图 / 排行榜 / 词云 / 指标卡的实际计算结果;
- 把图表结果交给 AI 做后续总结、趋势解释、同比/环比说明、异常点提取;
- 在不读取原始记录的前提下,直接消费图表层已经聚合好的结果;
- 验证某个图表当前展示的数据是否符合预期。
[!IMPORTANT] - 本命令返回的是图表结果协议,不是 block 元数据; - 如果你需要
name、type、layout、data_config等配置,请先用+dashboard-block-get; - 文本组件(text)不涉及计算,不适用本命令;
一句话理解
+dashboard-block-get-data = 拿图表“算出来的结果”,而不是拿图表“怎么配置的”。
支持的图表类型
当前支持以下图表类型的数据计算与返回:
二维图表(11 种)
- 柱状图
- 条形图
- 折线图
- 饼图
- 环形图
- 面积图
- 组合图
- 散点图
- 漏斗图
- 雷达图
- 排行榜
特殊类型(2 种)
- 词云
- 指标卡(statistics)
[!CAUTION] 文本组件虽然也属于 dashboard block,但它不产生可计算数据,因此不会返回本协议。
推荐命令
lark-cli base +dashboard-block-get-data \
--base-token bascn***************CtadY \
--block-id chtxxxxxxxx如果你还不知道目标 block 的 ID,典型顺序是:
# 先看仪表盘里有哪些组件
lark-cli base +dashboard-block-list \
--base-token bascn***************CtadY \
--dashboard-id blkxxxxxxxx \
--page-size 100
# 再读取某个组件的最终计算结果
lark-cli base +dashboard-block-get-data \
--base-token bascn***************CtadY \
--block-id chtxxxxxxxx如果用户要读取多个组件,先通过 +dashboard-block-list --page-size 100 取得真实 ID;若返回 has_more=true,继续把本页返回的 page_token 传给 --page-token,直到 has_more=false。收齐目标组件并跳过没有计算结果的文本组件后,再在一个 shell 工具调用内串行执行。每条命令会依次输出一个完整 JSON envelope;不要把每个 block 拆成独立模型轮次。
set -euo pipefail
block_ids=(cht_block_1 cht_block_2)
for block_id in "${block_ids[@]}"; do
lark-cli base +dashboard-block-get-data \
--base-token bascn***************CtadY \
--block-id "$block_id"
done数组中的 ID 必须逐字来自 +dashboard-block-list 返回,不要把名称或未经验证的用户文本作为 shell 代码执行。循环仍然是串行 API 调用,只减少模型往返,不裁剪任何组件结果。
如果你需要先确认组件类型、名称或 data_config,请先执行:
lark-cli base +dashboard-block-get \
--base-token bascn***************CtadY \
--dashboard-id blkxxxxxxxx \
--block-id chtxxxxxxxx参数
| 参数 | 必填 | 说明 |
|---|---|---|
--base-token <token> | 是 | Base Token,标识目标多维表格 |
--block-id <id> | 是 | 图表 Block ID,即目标组件的唯一标识 |
--format <fmt> | 否 | 输出格式,遵循 CLI 全局输出格式规则 |
--dry-run | 否 | 只预览 API 调用,不真正执行 |
[!TIP] 这个命令不需要
--dashboard-id。只要base_token + block_id即可定位并读取图表结果。
返回结构总览
CLI 成功输出使用标准 {ok, identity, data} 信封:
{
"ok": true,
"identity": "user",
"data": {
"dimensions": [],
"measures": [],
"main_data": []
}
}其中 identity 是本次调用实际使用的身份,data 是 CLI 图表协议本体。不同图表类型的 data 结构略有不同:
| 图表类型 | 一定有 | 可能有 |
|---|---|---|
| 二维图表 | dimensions / measures / main_data | 无 |
| 词云 | dimensions / measures / main_data | 无 |
| 指标卡 | dimensions / measures / main_data | comparison_data / trend_data |
协议字段说明
1) dimensions
维度定义数组,告诉你主结果里每个 dim_* key 代表什么字段。
[
{
"field_name": "文本",
"alias": "dim_5bKp"
}
]字段含义:
| 字段 | 说明 |
|---|---|
field_name | 维度字段显示名称 |
alias | 维度别名,在 main_data / trend_data 中作为 key 使用 |
2) measures
指标定义数组,告诉你每个 me_* key 代表什么聚合指标。
[
{
"field_name": "Count",
"aggregation": "count_all",
"alias": "me_Y291bnRfYWxsX0NvdW50"
}
]字段含义:
| 字段 | 说明 |
|---|---|
field_name | 统计该指标时所使用的字段名称;当 aggregation = count_all 时固定为 Count,表示统计记录总数 |
aggregation | 聚合方式,常见值:count_all / count / sum / avg / min / max |
alias | 指标别名,在 main_data / comparison_data / trend_data 中作为 key 使用 |
例如:
- 如果统计“销售额”的求和,则
field_name = 销售额、aggregation = sum - 如果统计记录总数,则
field_name = Count、aggregation = count_all
3) main_data
主结果集。每一行都是一个对象,key 不是字段名本身,而是 dimensions / measures 中声明过的 alias。
[
{
"dim_5bKp": {"value": "A"},
"me_Y291bnRfYWxsX0NvdW50": {"value": 3}
}
]4) comparison_data
仅指标卡可能返回。表示同/环比的两个值,顺序固定为:
- 当前周期值
- 对比周期值
[!NOTE] 原始协议里通常不直接展示周期名称,只提供对应的值。因此解释“同比”还是“环比”、以及比较窗口具体是什么,通常要结合组件配置或 UI 上下文理解。
5) trend_data
仅指标卡可能返回。表示时间序列趋势,每一行通常包含一个时间维度和一个指标值。
alias 规则与读取方式
你不应该把 alias 当成人类可读字段名,而应把它视为结果表里的列 ID。
常见生成规则:
- 维度 alias:
dim_+base64(field_name) - 指标 alias:
me_+base64(aggregation + "_" + field_name)
[!NOTE] 为了便于阅读,本文档中的部分示例会使用简化后的 alias(例如
dim_xxx、me_xxx或较短的示例值),不保证和真实返回值逐字符一致。 在实际读取结果时,应始终以dimensions/measures中声明的 alias 为准,而不要假设所有示例都严格展开成完整编码值。
例如:
{
"dimensions": [
{"field_name": "文本", "alias": "dim_5bKp"}
],
"measures": [
{"field_name": "Count", "aggregation": "count_all", "alias": "me_xxx"}
],
"main_data": [
{
"dim_5bKp": {"value": "A"},
"me_xxx": {"value": 3}
}
]
}应解读为:
dim_5bKp对应字段“文本”,取值是Ame_xxx对应指标count_all(Count),取值是3
[!TIP] 读取结果时,先看
dimensions/measures,再解main_data。不要仅凭 alias 名字猜含义。
各图表类型的协议细节
一、二维图表
适用于:柱状图、条形图、折线图、饼图、环形图、面积图、组合图、散点图、漏斗图、雷达图、排行榜。
排行榜复用同一 dimensions / measures / main_data 协议,不增加专属响应字段。结果的条数和顺序由 block 配置中的 limit_size 与 group_by[0].sort 决定;消费返回时保持 main_data 的服务端顺序,不要再次反转或自行重排。
结构特征
dimensions:通常有1~2个维度- 不分组聚合时:通常 1 个维度
- 开启分组聚合时:通常 2 个维度
measures:指标定义数组main_data:按“维度组合”展开后的行数据
这类数据代表什么
二维图表返回的本质上是一张聚合结果表:
- 每一行代表一个维度值,或一组维度组合;
- 每一个 measure 值代表该维度下算出来的指标结果;
- 如果图表开启了分组聚合,那么每一行表示“主维度 + 分组维度”的一个组合结果;
- 如果图表是折线图、面积图这类带时间轴的图,通常可以把第一维理解为横轴、把 measure 理解为纵轴数值;
- 如果图表是饼图、环形图这类占比图,通常可以把每一行理解为一个扇区对应的分类及其数值。
换句话说,AI 在读取这类结果时,可以把它当作“按某些维度聚合后的统计明细表”,适合进一步做排序、Top N、占比解释、分组对比和趋势总结。
示例 1:普通二维图表(无分组聚合)
{
"dimensions": [
{
"field_name": "文本",
"alias": "dim_5bKp"
}
],
"measures": [
{
"aggregation": "count_all",
"field_name": "Count",
"alias": "me_Y291bnRfYWxsX0NvdW50"
}
],
"main_data": [
{
"dim_5bKp": {"value": "A"},
"me_Y291bnRfYWxsX0NvdW50": {"value": 3}
},
{
"dim_5bKp": {"value": "B"},
"me_Y291bnRfYWxsX0NvdW50": {"value": 2}
},
{
"dim_5bKp": {"value": "C"},
"me_Y291bnRfYWxsX0NvdW50": {"value": 2}
}
]
}可解读为:
- 维度字段是“文本”
- 指标是“按记录总数统计”
- 当“文本”字段为
A时,对应的Count指标值是3 - 当“文本”字段为
B时,对应的Count指标值是2 - 当“文本”字段为
C时,对应的Count指标值是2
示例 2:二维图表(开启分组聚合)
{
"dimensions": [
{
"field_name": "文本",
"alias": "dim_5bKp"
},
{
"field_name": "单选",
"alias": "dim_5aSl"
}
],
"measures": [
{
"aggregation": "count_all",
"field_name": "Count",
"alias": "me_YW91bnR"
}
],
"main_data": [
{
"dim_5bKp": {"value": "A"},
"dim_5aSl": {"value": "a-1"},
"me_YW91bnR": {"value": 2}
},
{
"dim_5bKp": {"value": "A"},
"dim_5aSl": {"value": "a-2"},
"me_YW91bnR": {"value": 1}
},
{
"dim_5bKp": {"value": "B"},
"dim_5aSl": {"value": "b-1"},
"me_YW91bnR": {"value": 1}
},
{
"dim_5bKp": {"value": "C"},
"dim_5aSl": {"value": "c-1"},
"me_YW91bnR": {"value": 2}
}
]
}可解读为:
- 第一维是“文本”,第二维是“单选”,指标是“按记录总数统计”
- 当“文本”字段为
A、且“单选”字段为a-1时,对应的指标值是2 - 当“文本”字段为
A、且“单选”字段为a-2时,对应的指标值是1 - 当“文本”字段为
B、且“单选”字段为b-1时,对应的指标值是1 - 当“文本”字段为
C、且“单选”字段为c-1时,对应的指标值是2 - 如果按“文本”字段汇总,那么“文本”字段为
A时总指标值是3;为B时总指标值是1;为C时总指标值是2
二、词云
结构特征
词云协议仍然沿用 dimensions + measures + main_data 的结构,但语义稍有不同:
dimensions对应被分词的字段;main_data每一行代表一个词;measure的 value 表示按该词分组后计算出来的统计值。
这类数据代表什么
词云返回的不是“原文列表”,而是按词分组后的聚合统计结果:
dimensions定义的是被分词的来源字段;measure对应的是该词在当前图表统计范围内对应的统计值,具体含义取决于聚合方式和指标字段;main_data的每一行都可以理解成“某个词 + 该词对应的统计结果”,其中该维度的具体 value 就是拆分出来的词;- 返回结果通常已经结合图表当前过滤条件、时间范围、数据权限等上下文计算完成。
因此,AI 读取词云数据时,更适合做“关键词排序”“热点词解释”“按词聚合结果分析”“主题归纳”,而不是把它当成逐条文本记录去理解。
示例
{
"dimensions": [
{
"field_name": "文本",
"alias": "dim_5bKp"
}
],
"measures": [
{
"aggregation": "count_all",
"field_name": "Count",
"alias": "me_YW91bnR"
}
],
"main_data": [
{
"dim_5bKp": {"value": "A"},
"me_YW91bnR": {"value": 3}
},
{
"dim_5bKp": {"value": "B"},
"me_YW91bnR": {"value": 2}
},
{
"dim_5bKp": {"value": "C"},
"me_YW91bnR": {"value": 2}
}
]
}可解读为:
- 被统计的分词字段是“文本”
- 当前示例里的 measure 是
count_all(Count),所以这里的统计值可以理解为“按词分组后的记录总数” - 当分词结果为
A时,对应的统计值是3 - 当分词结果为
B时,对应的统计值是2 - 当分词结果为
C时,对应的统计值是2 - 按统计值排序,分词结果
A对应的值最高 - 分词结果
B和C的统计值相同,说明它们处于同一梯队
三、指标卡(statistics)
指标卡除了主值外,还可能包含同/环比与趋势结果,是本命令里结构最特殊的一类。
结构特征
measures:有且仅有一个指标main_data:通常只有一行,表示总指标值comparison_data:可选,表示当前周期值与对比周期值trend_data:可选,表示趋势序列dimensions:可能包含同/环比日期字段、趋势日期字段
这类数据代表什么
指标卡返回的核心是一个主指标摘要,外加可选的比较信息和趋势信息:
main_data表示当前卡片最核心、最醒目的那个主值;它通常是某个表的记录总数,或某个字段的聚合值,本身不带时间周期概念;comparison_data表示用于同/环比展示的两个数值,通常是“当前周期值”和“对比周期值”;它们表示某个时间周期下的记录总数,或某个字段的聚合值;trend_data表示这个指标在一段时间内的变化轨迹,用来支持走势判断;dimensions在指标卡里通常不是拿来做主分组展示,而是给trend_data或同/环比相关日期字段提供语义说明。
例如:
main_data = 7可以理解为当前卡片展示的主数据,比如某张表当前总记录数是7;comparison_data[0] = 6则表示某个比较周期下的当前值,比如“本月记录总数 = 6”;- 因此,
main_data与comparison_data[0]不一定相等,因为两者表达的口径并不完全相同。
因此,AI 在解读指标卡时,应该优先回答这几个问题:
- 当前主值是多少;
- 和对比周期相比是上升、下降还是持平;
- 趋势整体是增长、波动还是下滑;
- 是否存在明显的异常峰值或低谷。
[!NOTE] 当指标卡同时指定同/环比和趋势时,
dimensions中日期维度的顺序是固定的: 1. 第一个元素是趋势对应的日期维度; 2. 第二个元素是同/环比对应的日期维度。另外要注意:
comparison_data自身通常不直接携带日期字段,它只给出“当前周期值 / 对比周期值”。dimensions中的第一个日期维度会直接出现在trend_data中,作为趋势序列的时间列; 第二个日期维度则主要用于补充“该卡片配置了哪类比较相关日期字段”的语义。
示例
{
"dimensions": [
{
"field_name": "日期",
"alias": "dim_ZGF0ZQ"
},
{
"field_name": "日期2",
"alias": "dim_ZGF0ZTI"
}
],
"measures": [
{
"aggregation": "count_all",
"field_name": "Count",
"alias": "me_YW91b"
}
],
"main_data": [
{
"me_YW91b": {"value": 7}
}
],
"comparison_data": [
{
"me_YW91b": {"value": 6}
},
{
"me_YW91b": {"value": 0}
}
],
"trend_data": [
{
"dim_ZGF0ZQ": {"value": "2026-01-15"},
"me_YW91b": {"value": 1}
},
{
"dim_ZGF0ZQ": {"value": "2026-01-17"},
"me_YW91b": {"value": 1}
},
{
"dim_ZGF0ZQ": {"value": "2026-03-22"},
"me_YW91b": {"value": 1}
},
{
"dim_ZGF0ZQ": {"value": "2026-04-24"},
"me_YW91b": {"value": 2}
},
{
"dim_ZGF0ZQ": {"value": "2026-05-01"},
"me_YW91b": {"value": 1}
}
]
}可解读为:
- 当前主指标值 =
7 - 当前主指标值不带时间周期概念,可理解为当前卡片主数据
- comparison_data[0] = 当前周期值
6,例如某个时间周期(如本月)下的统计值 - comparison_data[1] = 对比周期值
0 dimensions[0]对应趋势日期维度,因此实际出现在trend_data里dimensions[1]对应同/环比相关的日期维度,用来补充比较语义- trend_data 展示该指标随时间的变化序列
- 从 comparison_data 看,当前周期相较对比周期是上升的,并且对比周期值为 0
- 从 trend_data 看,这个指标并不是每天都有值,而是在若干离散日期出现
- 趋势序列里的最高点出现在
2026-04-24,值为2 - 其余出现的日期大多为
1,说明整体上有波动,但暂时没有持续快速增长的趋势
[!NOTE]
comparison_data只告诉你“当前值 / 对比值”,不额外标出日期区间文本。如果用户需要完整说明“和上周比”还是“和上月比”,通常要结合组件配置或界面上下文进一步判断。
如何正确解读返回值
建议按下面顺序阅读:
- 先看
dimensions:确认每个dim_*alias 对应哪个字段; - 再看
measures:确认每个me_*alias 是什么聚合方式; - 最后读
main_data/comparison_data/trend_data:把 alias 还原成“字段名 + 指标名”再做解释。
推荐解释模板
如果要把结果转成自然语言,建议不要只“复述数值”,而应尽量覆盖下面几个层次:
- 先解释指标含义:说明 measure 代表“记录总数”“某字段求和”“平均值”等;
- 再给出核心结果:明确当前主值、主要分类、主要组合或主要词项;
- 做排序或 Top N 提炼:指出最高、最低、前几名、同一梯队;
- 补充分组/对比关系:如果有第二维或 comparison_data,就说明比较对象和差异;
- 分析趋势或异常点:如果有时间序列,指出上升、下降、波动、峰值、低谷;
- 最后给一句结论:总结最值得关注的信息。
可参考下面模板:
- 二维图表:
- 基础模板:
按 <维度字段> 统计,当前指标 <指标含义>;其中 <维度值1>=<指标值1>,<维度值2>=<指标值2> ... - 增强模板:
按 <维度字段> 统计,当前指标表示 <指标含义>。从结果看,<Top1维度值> 的值最高,为 <Top1值>;<Top2维度值> 和 <Top3维度值> 紧随其后。若按 Top N 看,前 <N> 项合计贡献了 ...;若看低值项,<低值维度值> 最低,为 <低值>。整体上,<一句总结>
- 分组聚合图表:
- 基础模板:
按 <维度1> 统计,并以 <维度2> 分组,得到 <组合1>=<值1>,<组合2>=<值2> ... - 增强模板:
当前指标表示 <指标含义>。按 <维度1> 拆分后,不同 <维度2> 组之间存在明显差异:例如 <组合1> = <值1>,<组合2> = <值2>。如果按 <维度1> 汇总,<Top1维度1值> 总值最高,为 <汇总值>;如果看组内对比,<某组> 在 <某维度1值> 下表现最强 / 最弱。整体说明 <一句总结>
- 词云:
- 基础模板:
按分词结果统计,当前指标表示 <指标含义>;其中 <词1>=<统计值1>,<词2>=<统计值2> ... - 增强模板:
当前词云反映的是“按词分组后的 <指标含义>”。从结果看,<Top1词> 的值最高,为 <值1>,说明它是当前最突出的关键词;<Top2词>、<Top3词> 处于第二梯队。如果按 Top N 看,主要关注词集中在 <主题A>、<主题B>;如果有多个词数值接近,可归为同一热点层级。整体上,这组词更适合用来总结 <主题/热点/关注点>
- 指标卡:
- 基础模板:
当前主指标值为 <main_data>;当前周期值为 <comparison_data[0]>;对比周期值为 <comparison_data[1]>;趋势上 ... - 增强模板:
当前主指标表示 <指标含义>,主值为 <main_data>。若看周期比较,当前周期值为 <comparison_data[0]>,对比周期值为 <comparison_data[1]>,因此整体表现为 <上升/下降/持平>。若看趋势序列,最高点出现在 <日期>,值为 <峰值>;最低点出现在 <日期>,值为 <低值>;整体走势表现为 <持续增长/阶段波动/明显回落>。如果需要给出结论,可总结为:<一句总结>
[!TIP] 当用户明确要求“帮我分析”“帮我总结”“帮我找异常 / Top N / 趋势”时,优先采用增强模板,而不是只逐条复述原始数值。
常见工作流
场景 1:用户要“拿这个图表当前展示的数据”
# 如果已知 block_id,直接读结果
lark-cli base +dashboard-block-get-data \
--base-token xxx \
--block-id chtxxxxxxxx场景 2:用户说“帮我分析这个图表”,但你还不知道它是什么组件
# 先看组件配置,确认它是不是支持计算的图表类型
lark-cli base +dashboard-block-get \
--base-token xxx \
--dashboard-id blk_xxx \
--block-id chtxxxxxxxx
# 再读最终计算结果
lark-cli base +dashboard-block-get-data \
--base-token xxx \
--block-id chtxxxxxxxx场景 3:用户要找“仪表盘里哪个图的结果异常”
# 先列组件
lark-cli base +dashboard-block-list \
--base-token xxx \
--dashboard-id blk_xxx
# 再针对可疑 block 逐个取结果
lark-cli base +dashboard-block-get-data \
--base-token xxx \
--block-id chtxxxxxxxx何时优先用这个命令
- 用户说“帮我拿这个图表算出来的数据 / 结果 / 指标”
- 用户已经知道
block_id,目标是读取结果而不是看配置 - 用户后续还要让 AI 对图表结果做解释、归纳、比较、总结
- 你只关心图表层的聚合产出,不需要回到底表逐条读记录
何时不要误用
- 想看 block 的
data_config、名称、类型、布局 → 用+dashboard-block-get - 想列出仪表盘里有哪些组件 → 用
+dashboard-block-list - 想修改或新建组件 → 用
+dashboard-block-update/+dashboard-block-create - 想看原始记录明细,而不是图表聚合结果 → 回到
record-* - 目标是文本组件 → 本命令不适用
常见误区
误区 1:把这个命令当成“获取 block 详情”
不是。这个命令不返回:
- block 名称
- block 类型
- layout
data_config- 所属 dashboard 信息
这些都应该通过 +dashboard-block-get 获取。
误区 2:以为它返回的是原始记录
不是。它返回的是图表聚合后的最终结果。如果图表本身做了过滤、分组、聚合、时间窗口限制,返回值反映的是图表视角,不是原始表全量明细。
误区 3:直接把 alias 当真实字段名读
不应该。alias 只是协议里的键,必须结合 dimensions / measures 还原语义。
误区 4:看到指标卡的 comparison_data 就以为已经知道“同比/环比周期文本”
不一定。它只给出比较值,不一定给出周期标签。若要精确解释比较窗口,通常还需要组件配置或 UI 上下文。
dry-run 用途
可用来确认最终会调用的接口路径:
lark-cli base +dashboard-block-get-data \
--base-token bascn_example_token \
--block-id chtxxxxxxxx \
--dry-run \
--format pretty你应能看到类似:
GET /open-apis/base/v3/bases/bascn_example_token/dashboards/blocks/chtxxxxxxxx/data适合在以下场景使用:
- 校验
base_token/block_id是否传对; - 调试 agent 生成的命令;
- 编写自动化测试时确认请求结构。
参考
- lark-base-dashboard.md — dashboard 模块总指引
+dashboard-block-get— 获取 block 元数据- Dashboard Block 配置 — data_config 结构和组件类型说明
Dashboard(仪表盘/数据看板)模块指引
前置条件: 先阅读 `../../lark-shared/SKILL.md` 了解认证、全局参数和安全规则。
Dashboard 是 Base 中的数据可视化看板,可以把表格数据变成组件(图表、指标卡等)进行展示。
核心概念
- Dashboard(仪表盘):容器,包含多个组件
- Block(组件):仪表盘中的单个可视化元素(柱状图、折线图、饼图、指标卡等)
- data_config:组件的数据源配置(表名、字段、分组等)
能力速览
| 你想做什么 | 用这些命令 | 关键文档 |
|---|---|---|
| 创建/删除/改名称 | +dashboard-create/delete/update | 本页下方「仪表盘管理」 |
| 在仪表盘里添加组件 | +dashboard-block-create | 先定位 dashboard、表和字段,再读 Dashboard Block 配置 构造 data_config |
| 修改组件 | +dashboard-block-update | 先读 block 现状,再读 Dashboard Block 配置 决定替换哪些顶层 key |
| 创建/更新时指定组件精确位置大小 | +dashboard-block-create/update --position | 本页下方「精确布局 --position vs +dashboard-arrange」 |
| 查看仪表盘有哪些组件 | +dashboard-get 或 +dashboard-block-list | 本页下方「查看仪表盘」 |
| 读取图表计算结果 | +dashboard-block-get-data | 返回图表最终数据协议;需要 block 元数据先用 +dashboard-block-get |
| 智能重排组件布局 | +dashboard-arrange | 用户明确要求重排,或本次会话新建仪表盘的收尾整理;无法指定 x/y/w/h、精确位置或尺寸 |
精确布局 --position vs +dashboard-arrange
create/update 可选 --position,用 12 列栅格坐标精确指定单个组件的落点与大小:{"x","y","w","h"},x/y 为左上角坐标(>=0),w 为宽度(1..12,且 x+w<=12),h 为高度(>=1)。它与 name/type/data_config 平级挂在请求体顶层。
[!IMPORTANT] - 四个 key 必须齐全且都是数字:
position按整体提交、不做逐字段合并,所以只传{"x":6}表达的不是"只挪位置不改大小",而是一个缺了三项的位置。本地会拒绝残缺对象(含显式null)。 - 坐标取值不做本地校验:越界、负值或重叠坐标会原样发给服务端,由服务端自动重排。调用方仍应优先规划 12 列范围内且不重叠的坐标,避免自动重排改变预期落点。 - 不传--position:create 由服务端自动装箱,update 保持当前布局不变。 - 只有用户明确给出x/y/w/h、具体行列/顺序、每个组件宽高或可直接换算的尺寸比例时才用--position。"调整布局""美化""撑满""铺满"本身不算精确约束,没有组件级坐标或尺寸时优先用+dashboard-arrange整盘编排。 - 命令成功即视为写入成功,一般无需仅为读回位置再调用+dashboard-block-get/+dashboard-block-list;成功响应不代表最终渲染位置已经过读回验证。
statistics 指标卡数值格式
statistics 组件可在 create/update 的 data_config.number_format 中设置 formatName 和 precision。create 会校验组件类型和子字段;update 不接收 --type,只校验 number_format 子字段,再由服务端结合现有 block 类型裁决。枚举、精度范围、更新语义和可复制模板读取 Dashboard Block 配置。
典型场景工作流
场景 1:从 0 到 1 创建仪表盘
从 0 到 1 创建仪表盘时,按用户需求规划组件的类型和数量,并注意以下要点:
- 聚合方式:创建指标卡或分布图时优先把聚合写进
data_config,只有 Top N、字段取值探索、复杂筛选校验或 helper 汇总表场景才先用+data-query。 - Dry-run 边界:已按模板构造的简单指标卡、分布图、趋势图不需要逐个
--dry-run后再真实创建;只有在调试 JSON、检查请求体、复杂自造data_config或处理 API validation 错误时才 dry-run。 - 验证方式:创建接口成功返回即表示写入成功。只有结果不确定时才用一次
+dashboard-get或+dashboard-block-list确认仪表盘和组件存在;不要仅为确认创建而逐组件调用+dashboard-block-get-data。 - 布局方式:用户没有给出组件级坐标或尺寸时,创建完成后用一次
+dashboard-arrange整盘编排即可;只有用户明确给出可执行的精确布局约束时才在 create 中带--position,此时通常不再需要 arrange。
示例:搭建一个销售数据分析仪表盘
# 第 1 步:创建空白仪表盘
lark-cli base +dashboard-create --base-token xxx --name "销售数据分析"
# 记录返回的 dashboard_id
# 第 2 步:获取数据源信息
lark-cli base +table-list --base-token xxx
lark-cli base +field-list --base-token xxx --table-id <table_id>
# 第 3 步:规划应该创建哪些组件(根据用户需求确定组件类型和数量)
# 例如:总销售额(指标卡)、月度趋势(折线图)、负责人 Top N(排行榜)
# 第 4 步:顺序创建每个组件(必须串行执行,不能并发)
# 重要:创建组件前,先确定 dashboard_id、组件 name/type 和真实表字段
# 再阅读 lark-base-dashboard-block-config.md 了解 data_config 结构、组件类型和 filter 规则
# 第 1 个组件
lark-cli base +dashboard-block-create \
--base-token xxx \
--dashboard-id blk_xxx \
--name "总销售额" \
--type statistics \
--data-config '{"table_name":"订单表","series":[{"field_name":"金额","rollup":"SUM"}]}'
# 第 2 个组件(等上一个完成后再执行)
lark-cli base +dashboard-block-create \
--base-token xxx \
--dashboard-id blk_xxx \
--name "月度趋势" \
--type line \
--data-config '{"table_name":"订单表","series":[{"field_name":"金额","rollup":"SUM"}],"group_by":[{"field_name":"月份","mode":"integrated"}]}'
# 继续创建其他组件...
# 排行榜组件:省略 limit_size 和 sort 时分别默认 10、value desc
lark-cli base +dashboard-block-create \
--base-token xxx \
--dashboard-id blk_xxx \
--name "负责人销售额 Top 10" \
--type ranking \
--data-config '{"table_name":"订单表","series":[{"field_name":"金额","rollup":"SUM"}],"group_by":[{"field_name":"负责人"}]}'
# 第 5 步:组件创建完成后,可按需使用 arrange 智能重排(未使用 --position 时可选)
# 默认布局可能不够美观,arrange 会根据组件数量和类型自动优化布局
# 若任一组件使用了显式 --position,跳过此步骤;除非用户明确同意放弃精确布局
# 若用户没有要求美化/重排,也可跳过;这不影响仪表盘和组件是否已创建成功
lark-cli base +dashboard-arrange \
--base-token xxx \
--dashboard-id blk_xxx场景 2:在已有仪表盘上添加新组件
# 第 1 步:列出仪表盘,定位到当前仪表盘
lark-cli base +dashboard-list --base-token xxx
# 获取目标 dashboard_id
# 第 2 步:根据用户诉求规划组件类型和数据源
# 建议先查看当前仪表盘已有组件,避免重复创建,或作为参考
lark-cli base +dashboard-get --base-token xxx --dashboard-id blk_xxx
# 第 3 步:获取数据源信息
lark-cli base +table-list --base-token xxx
lark-cli base +field-list --base-token xxx --table-id <table_id>
# 第 4 步:顺序创建每个新组件(必须串行执行,不能并发)
# 重要:先确定 dashboard_id、组件 name/type 和真实表字段
# 再阅读 lark-base-dashboard-block-config.md 了解 data_config 结构
lark-cli base +dashboard-block-create \
--base-token xxx \
--dashboard-id blk_xxx \
--name "新组件名" \
--type column \
--data-config '{...}'场景 3:编辑已有组件
[!IMPORTANT]
+dashboard-block-update不能修改组件的type(图表类型),只能更新name、data_config和可选的position。 如需更换组件类型,必须先删除再重新创建。
# 第 1 步:列出仪表盘,定位到当前仪表盘
lark-cli base +dashboard-list --base-token xxx
# 第 2 步:列出组件,获取到目标组件
lark-cli base +dashboard-block-list --base-token xxx --dashboard-id blk_xxx
# 获取目标 block_id
# 提示:查看已有组件可作为参考,或检查是否重复创建相似组件
# 第 3 步:获取组件当前详情
lark-cli base +dashboard-block-get --base-token xxx --dashboard-id blk_xxx --block-id chtxxxxxxxx
# 第 4 步:根据用户编辑诉求准备更新
# 如果编辑诉求涉及数据源变更,需要先获取数据源信息
lark-cli base +table-list --base-token xxx
lark-cli base +field-list --base-token xxx --table-id <table_id>
# 第 5 步:执行更新
# 重要:先读取当前 block 的 name/type/data_config
# 再阅读 lark-base-dashboard-block-config.md 了解 data_config 更新规则
lark-cli base +dashboard-block-update \
--base-token xxx \
--dashboard-id blk_xxx \
--block-id chtxxxxxxxx \
--data-config '{...}' \
--position '{...}' # 可选,只在需要调整布局时传
# 排行榜只修改 Top N;不会覆盖分组、指标、筛选或排序
lark-cli base +dashboard-block-update \
--base-token xxx \
--dashboard-id blk_xxx \
--block-id chtxxxxxxxx \
--data-config '{"limit_size":20}'
场景 4:重排仪表盘布局
当用户要求调整布局、重排、美化、撑满或铺满,但没有给出组件级坐标或尺寸时使用。定位仪表盘后用一次 +dashboard-arrange 整盘编排即可(对本次会话从零新建的仪表盘,在建完组件后编排一次)。
[!CAUTION] - 排列结果是服务端智能推荐,不一定完全符合用户预期 -
+dashboard-arrange无法指定x/y/w/h、精确位置或尺寸,排列逻辑是自适应的;只有用户明确给出可执行的组件级坐标、行列或尺寸约束时才改用--position- 不建议在已有仪表盘上自动调用,除非用户明确要求 - 用户只要求一般性重排、美化、撑满或铺满时,用+dashboard-arrange整盘编排 - 编排结果不理想时,可结合用户反馈再调整;不要为了凑效果去探测 rawlark-cli api、源码或未公开布局参数
# 第 1 步:列出仪表盘,定位到目标仪表盘
lark-cli base +dashboard-list --base-token xxx
# 第 2 步:执行智能重排
lark-cli base +dashboard-arrange \
--base-token xxx \
--dashboard-id blk_xxx场景 5:读取仪表盘或组件现状
选择查询方式:
- 想看仪表盘整体结构(含主题、所有组件名称和类型)→ 用 方式 A
- 只想快速查看有哪些组件 → 用 方式 B
- 想看某个组件的详细 data_config 配置 → 用 方式 C
- 想看某个图表/指标卡实际算出来的数据 → 用 方式 D
用户要求读取“全部图表”或“完整仪表盘”时,先用方式 B 分页枚举所有 block:使用 --page-size 100;若返回 has_more=true,继续把本页返回的 page_token 传给 --page-token,直到 has_more=false。收齐后再对每个 block 收口,不能只返回 get-data 成功的子集:
- 图表或指标卡:使用方式 D 读取计算结果。
text:使用方式 C,正文位于data_config.text;text 没有计算结果,但属于完整仪表盘内容。- get-data 返回不支持的图表类型:先用方式 C 读取真实
data_config,确认table_name、维度、指标、聚合与筛选,再按 Record 查询与分析 SOP 使用+data-query重建同口径结果。字段必须来自真实配置和表结构,不得猜测;无法等价重建时明确报告限制,不能静默省略该 block。
# 第 1 步:列出仪表盘,定位到当前仪表盘
lark-cli base +dashboard-list --base-token xxx
# 第 2 步:根据用户诉求查看详情
# 方式 A:查看仪表盘整体情况(包含所有组件列表)
lark-cli base +dashboard-get --base-token xxx --dashboard-id blk_xxx
# 方式 B:列出所有组件
lark-cli base +dashboard-block-list \
--base-token xxx \
--dashboard-id blk_xxx \
--page-size 100
# 方式 C:查看某个组件的详细配置
lark-cli base +dashboard-block-get --base-token xxx --dashboard-id blk_xxx --block-id chtxxxxxxxx
# 方式 D:查看某个图表组件的计算结果(AI 友好的 chart protocol)
lark-cli base +dashboard-block-get-data --base-token xxx --block-id chtxxxxxxxx
# 最后:把获取到的现状信息整理好告诉用户需要读取多个组件的计算结果时,先用方式 B 获取真实 block_id(使用 --page-size 100;若 has_more=true,继续把返回的 page_token 传给 --page-token,直到 has_more=false),再按 lark-base-dashboard-block-get-data.md 的多组件范式,在一个 shell 工具调用内串行读取;不要把每个 block 拆成独立模型轮次。文本组件没有计算结果,应跳过。
组件类型选择
组件 type 决定展示形式:
| 用户想看什么 | 选什么 type | 说明 |
|---|---|---|
| 数据趋势(时间变化) | line | 折线图组件 |
| 类别比较(谁高谁低) | column | 柱状图组件 |
| 占比分布(各部分比例) | pie | 饼图组件 |
| 单个关键指标 | statistics | 指标卡组件 |
| 单维度 Top N 排名 | ranking | 排行榜组件,单分组、单指标 |
| 富文本说明/标题/注释 | text | 文本组件(支持 Markdown) |
详细组件类型和 data_config 完整规则:Dashboard Block 配置
常见问题
Q: 创建组件的命令和 data_config 怎么写? A:
- 先确定
dashboard_id、组件name、组件type和真实表字段 - 再读 Dashboard Block 配置 了解:
- 全部组件类型的可复制模板
- filter 筛选条件格式
- 字段类型与操作符对应表
Q: 为什么组件创建失败了? A: 常见原因:
table_name用了 table_id 而不是表名(必须用表名称,如「订单表」)series和count_all同时存在(必须二选一,互斥)- 字段名拼写错误(必须用
+field-list获取的真实字段名,禁止猜测) - 组件创建并发执行(必须串行,等上一个完成再执行下一个)
Q: 可以一次创建多个组件吗? A: 不可以,必须串行执行。等上一个 +dashboard-block-create 完成后再执行下一个。
Q: 组件的 type 创建后能改吗? A: 不能。+dashboard-block-update 只能修改 name、data_config 和 position,不能修改 type。
Q: 更新组件的命令和 data_config 怎么写? A:
- 先读取当前 block,确认
block_id、当前type和已有data_config - 再读 Dashboard Block 配置 了解 data_config 结构
data_config 更新策略(顶层 key merge):
- 只传入需要修改的顶层字段(如
series、filter) - 未传的顶层字段(如
group_by)自动保留原值 - 但每个传入的字段内部通常是全量替换(如传新
filter会完整覆盖旧filter);number_format例外,按子字段合并,见 Dashboard Block 配置 的 number_format 小节
Q: 查看已有组件有什么用? A: 在「添加新组件」或「编辑组件」前查看已有组件可以:
- 了解当前仪表盘已有哪些可视化
- 避免重复创建相似的组件
- 参考已有组件的 data_config 结构作为模板
Q: 我想直接拿图表算好的结果给 AI 分析,应该用什么? A: 用 +dashboard-block-get-data。它返回图表协议 JSON(常见字段包括 dimensions、measures、main_data,指标卡可能还有 comparison_data、trend_data),不返回 block 名称、类型、布局或 data_config;需要这些元数据时先用 +dashboard-block-get。
写入前检查
- 创建 block 前必须知道
base_token、dashboard_id、组件name/type和data_config。 - 更新 block 前必须知道
base_token、dashboard_id、block_id,并读过当前 block。 data_config中使用表名和字段名,不使用 table_id / field_id;名称必须来自+table-list/+field-list的真实返回。
Base data-query DSL reference
前置路由: Record 查询与分析 SOP | 认证或授权问题: `../../lark-shared/SKILL.md`
限制
- 权限要求(按文档类型分流):
- 普通多维表格:调用者拥有文档的阅读权限即可
- 高级权限多维表格:调用者必须是文档管理员,拥有 FA(Full Access / 完全访问权限)
权限不足时返回权限错误。
推荐命令
# 按字段分组计数
lark-cli base +data-query \
--base-token MAGObxxxxx \
--dsl '{
"datasource": {"type": "table", "table": {"tableId": "tblxxxxxxxx"}},
"dimensions": [{"field_name": "城市", "alias": "dim_city"}],
"measures": [{"field_name": "城市", "aggregation": "count", "alias": "count"}],
"shaper": {"format": "flat"}
}'
# 带过滤条件 + 排序 + 限制条数
lark-cli base +data-query \
--base-token MAGObxxxxx \
--dsl '{
"datasource": {"type": "table", "table": {"tableId": "tblxxxxxxxx"}},
"dimensions": [{"field_name": "城市", "alias": "dim_city"}],
"measures": [{"field_name": "金额", "aggregation": "sum", "alias": "total_amount"}],
"filters": {
"type": 1,
"conjunction": "and",
"conditions": [{"field_name": "城市", "operator": "isNot", "value": [""]}]
},
"sort": [{"field_name": "total_amount", "order": "desc"}],
"pagination": {"limit": 100},
"shaper": {"format": "flat"}
}'
# 使用 tableName(表名)代替 tableId
lark-cli base +data-query \
--base-token MAGObxxxxx \
--dsl '{
"datasource": {"type": "table", "table": {"tableName": "销售数据"}},
"measures": [{"field_name": "金额", "aggregation": "sum", "alias": "total"}],
"shaper": {"format": "flat"}
}'
# 聚合或维度查询后如需读取逐条记录,先让 data-query 返回可回查的业务 key
lark-cli base +data-query \
--base-token MAGObxxxxx \
--dsl '{
"datasource": {"type": "table", "table": {"tableId": "tblxxxxxxxx"}},
"dimensions": [{"field_name": "业务编号", "alias": "biz_key"}],
"measures": [{"field_name": "指标值", "aggregation": "max", "alias": "max_value"}],
"filters": {
"type": 1,
"conjunction": "and",
"conditions": [{"field_name": "状态", "operator": "is", "value": ["有效"]}]
},
"sort": [{"field_name": "max_value", "order": "desc"}],
"pagination": {"limit": 10},
"shaper": {"format": "flat"}
}'参数
| 参数 | 必填 | 说明 |
|---|---|---|
--base-token <token> | 是 | Base Token(base_token) |
--dsl <json> | 是 | LiteQuery Protocol JSON DSL 查询语句。注意,本工具 schema 与 record/view 查询的 schema 不同,需要充分阅读本文档后,编写正确的 DSL,避免与其他场景的 DSL 混淆。 |
如何从链接中解析参数
用户通常会提供如下 URL:
https://example.feishu.cn/base/<base_token>?table=<block_id>不要直接把 URL 中的 table= 当成数据表 ID。它表示当前选中的 Base 顶层块,可能是数据表、仪表盘、工作流、文件夹或文档。先解析链接:
lark-cli base +url-resolve --url "<url>" --as user--base-token:使用返回的base_token- 仅当返回的
block_type为table时,DSL 中的tableId才使用返回的table_id - 如果返回的是其他块类型,按
hint.next_step继续处理;如果只返回中性的block_id,先用+base-block-list确认块类型,再选择实际要查询的数据表
API 入参详情
HTTP 方法和路径:
POST /open-apis/base/v3/bases/:base_token/data/queryPath 参数:
| 参数 | 必填 | 说明 |
|---|---|---|
base_token | 是 | Base Token |
Request Body — DSL 结构:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
datasource | object | 是 | 数据源,包含 type(固定 "table")和 table 对象 |
datasource.table.tableId | string | 二选一 | 目标数据表 ID |
datasource.table.tableName | string | 二选一 | 目标数据表名称 |
dimensions | Dimension[] | 否* | 分组维度字段(GROUP BY) |
measures | Measure[] | 否* | 聚合度量字段 |
filters | FilterGroup | 否 | 过滤条件(WHERE) |
sort | Sort[] | 否 | 排序规则 |
pagination | object | 否 | 限制返回行数,{limit: N},最大 5000 |
shaper | object | 否 | 结果格式,固定 {format: "flat"} |
\*
dimensions和measures至少填写一个。
Dimension 字段:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
field_name | string | 是 | 字段名称 |
alias | string | 否 | 输出列别名,需全局唯一 |
Measure 字段:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
field_name | string | 是 | 字段名称 |
aggregation | string | 是 | 聚合函数:sum、avg、min、max、count、count_all、distinct_count |
alias | string | 否 | 输出列别名,需全局唯一 |
聚合函数适用字段类型:
| 聚合函数 | 适用字段类型 |
|---|---|
sum / avg | number |
min / max | number、datetime |
count | 全字段适用,计数非空值 |
count_all | 全字段适用,计数所有行 |
distinct_count | 全字段适用 |
number包含style.type为progress/currency/rating等所有子类型。
FilterGroup:
{
"filters": {
"type": 1,
"conjunction": "and",
"conditions": [
{"field_name": "城市", "operator": "is", "value": ["北京"]}
]
}
}| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
type | int | 是 | 固定填 1 |
conjunction | string | 否 | 条件组合逻辑:"and" 或 "or",默认 "and" |
conditions | Condition[] | 否 | 条件列表 |
Condition:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
field_name | string | 是 | 字段名称(必须与表中字段名精确匹配) |
operator | string | 是 | 运算符(见下方运算符表) |
value | string[] | 是 | 条件值数组;isEmpty/isNotEmpty 时必须传空数组 [] |
运算符:
| 运算符 | 说明 |
|---|---|
is | 等于 |
isNot | 不等于 |
contains | 包含 |
doesNotContain | 不包含 |
isEmpty | 为空 |
isNotEmpty | 不为空 |
isGreater | 大于 |
isGreaterEqual | 大于等于 |
isLess | 小于 |
isLessEqual | 小于等于 |
各运算符的适用字段类型见下方「按各字段类型筛选时 value 格式详解」。
按各字段类型筛选时 value 格式详解:
text
| 运算符 | value 格式 | 元素个数 | 示例 |
|---|---|---|---|
is / isNot / contains / doesNotContain | ["文本内容"] | 仅 1 个 | ["Hello"] |
isEmpty / isNotEmpty | [] | 0 个 | [] |
不支持
isGreater/isGreaterEqual/isLess/isLessEqual:文本无自然顺序,比较运算无意义。text也覆盖电话、超链接、邮箱、条码字段;通过style.type区分(plain(默认)/phone/url/barcode),运算符集合一致。 当style.type=url时,value 筛选的是链接显示名称,而不是 URL 本身。
number
| 运算符 | value 格式 | 元素个数 | 示例 |
|---|---|---|---|
is / isNot / isGreater / isGreaterEqual / isLess / isLessEqual | ["数字字符串"] | 仅 1 个 | ["23.4"]、["-100"] |
isEmpty / isNotEmpty | [] | 0 个 | [] |
value 必须为合法数字的字符串形式。
number也覆盖货币、进度、评分字段;通过style.type区分(plain(默认)/currency/progress/rating),运算符集合一致,仅 value 解释不同: - 当style.type=progress时,34% 对应 0.34 而不是 34。 - 当style.type=rating时,必须输入整数,代表评分。
auto_number
| 运算符 | value 格式 | 元素个数 | 示例 |
|---|---|---|---|
is / isNot / contains / doesNotContain | ["编号字符串"] | 仅 1 个 | ["00001"] |
isGreater / isGreaterEqual / isLess / isLessEqual | ["编号字符串"] | 仅 1 个 | ["00010"] |
isEmpty / isNotEmpty | [] | 0 个 | [] |
select
| 运算符 | value 格式 | 元素个数 | 示例 |
|---|---|---|---|
is / isNot | ["选项名"] | 仅 1 个 | ["选项A"] |
contains / doesNotContain | ["选项A", "选项B"] | 可多个 | ["选项A", "选项B"] |
isEmpty / isNotEmpty | [] | 0 个 | [] |
不支持
isGreater/isGreaterEqual/isLess/isLessEqual:选项为枚举值,无自然顺序。 通过multiple区分单选(multiple=false,默认)/ 多选(multiple=true)。
user / created_by / updated_by
| 运算符 | value 格式 | 元素个数 | 示例 |
|---|---|---|---|
is / isNot | ["用户ID1", "用户ID2"] | 可多个 | ["ou_aaa", "ou_bbb"] |
contains / doesNotContain | ["用户ID1", "用户ID2"] | 可多个 | ["ou_aaa", "ou_bbb"] |
isEmpty / isNotEmpty | [] | 0 个 | [] |
不支持
isGreater/isGreaterEqual/isLess/isLessEqual:人员无法比大小。 用户 ID 使用open_id(ou_前缀),接口层会自动做 ID 转换。
group_chat
| 运算符 | value 格式 | 元素个数 | 示例 |
|---|---|---|---|
is / isNot | ["群组ID1", "群组ID2"] | 可多个 | ["oc_aaa", "oc_bbb"] |
contains / doesNotContain | ["群组ID1", "群组ID2"] | 可多个 | ["oc_aaa", "oc_bbb"] |
isEmpty / isNotEmpty | [] | 0 个 | [] |
不支持
isGreater/isGreaterEqual/isLess/isLessEqual:群组无法比大小。
link
| 运算符 | value 格式 | 元素个数 | 示例 |
|---|---|---|---|
is / isNot | ["recId1", "recId2"] | 可多个 | ["recAAA", "recBBB"] |
contains / doesNotContain | ["recId1", "recId2"] | 可多个 | ["recAAA", "recBBB"] |
isEmpty / isNotEmpty | [] | 0 个 | [] |
不支持
isGreater/isGreaterEqual/isLess/isLessEqual:关联记录无法比大小。 value 传关联表记录的record_id。 双向关联(创建时设bidirectional=true)也属于link类型,运算符与单向关联一致。
location
| 运算符 | value 格式 | 元素个数 | 示例 |
|---|---|---|---|
is / isNot / contains / doesNotContain | ["地址文本"] | 仅 1 个 | ["北京市朝阳区..."] |
isEmpty / isNotEmpty | [] | 0 个 | [] |
不支持
isGreater/isGreaterEqual/isLess/isLessEqual:地理位置无自然顺序。 location 按full_address字符串筛选,不支持经纬度空间筛选;查城市/片区时优先用contains,避免用is匹配短地址词。
checkbox
| 运算符 | value 格式 | 元素个数 | 示例 |
|---|---|---|---|
is | ["true"] 或 ["false"] | 仅 1 个 | ["true"] |
仅支持
is运算符,不支持其他运算符。
datetime / created_at / updated_at
日期字段仅支持 is、isEmpty、isNotEmpty、isGreater、isLess 五种运算符。
value 使用预定义关键字机制,第一个元素为字符串常量名称:
| 关键字 | 说明 | value 格式 | 支持的运算符 |
|---|---|---|---|
ExactDate | 精确日期 | ["ExactDate", "1773187200000"](毫秒时间戳) | is、isGreater、isLess |
Today | 今天 | ["Today"] | is、isGreater、isLess |
Tomorrow | 明天 | ["Tomorrow"] | is、isGreater、isLess |
Yesterday | 昨天 | ["Yesterday"] | is、isGreater、isLess |
CurrentWeek | 本周 | ["CurrentWeek"] | 仅 is |
LastWeek | 上周 | ["LastWeek"] | 仅 is |
CurrentMonth | 本月 | ["CurrentMonth"] | 仅 is |
LastMonth | 上月 | ["LastMonth"] | 仅 is |
TheLastWeek | 过去七天 | ["TheLastWeek"] | 仅 is |
TheNextWeek | 未来七天 | ["TheNextWeek"] | 仅 is |
TheLastMonth | 过去三十天 | ["TheLastMonth"] | 仅 is |
TheNextMonth | 未来三十天 | ["TheNextMonth"] | 仅 is |
- ExactDate 时区行为:毫秒时间戳在实际筛选时会被转为文档时区当天零点,跨时区场景需注意日期可能偏移一天。
- 范围型关键字(
CurrentWeek、LastWeek、CurrentMonth、LastMonth、TheLastWeek、TheNextWeek、TheLastMonth、TheNextMonth)仅支持is运算符。- 关键字大小写敏感:
ExactDate、Today、CurrentWeek等首字母大写,写错大小写会导致校验失败。
attachment
| 运算符 | value 格式 | 元素个数 | 示例 |
|---|---|---|---|
isEmpty / isNotEmpty | [] | 0 个 | [] |
附件字段仅支持
isEmpty和isNotEmpty,不支持其他运算符。
formula / lookup
公式和查找引用字段的运算符和 value 格式 取决于其结果数据类型,按结果类型参照上方对应字段类型的规则。例如:
- 公式结果为数字 → 按
number规则 - 公式结果为日期 → 按
datetime规则 - 公式结果为单选 → 按
select规则
Sort 字段:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
field_name | string | 是 | 字段名称或 alias |
order | string | 否 | "asc"(默认)或 "desc" |
Pagination 字段:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
limit | int | 否 | 返回记录数上限,必须为正整数,最大 5000;不填时使用系统默认值。不支持 offset |
Shaper 字段:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
format | string | 是 | 固定为 "flat",表示返回扁平化的对象数组 |
CLI 出参详情
CLI 输出标准信封 {ok, identity, data}(失败时为 {ok:false, identity, error})。
成功时:
{"ok": true, "identity": "user", "data": {"main_data": [{"dim_city": {"value": "北京"}, "total_amount": {"value": 12345.00}}, ...]}}失败时:
{"ok": false, "identity": "user", "error": {"type": "api", "subtype": "unknown", "code": 800004006, "message": "...does not exist in table schema", "hint": "...", "log_id": "..."}}Response 字段:
| 字段 | 类型 | 说明 |
|---|---|---|
ok | bool | 是否成功 |
identity | string | 执行身份:user / bot |
data.main_data | []object | 查询结果数组,每个元素为一行数据(成功时) |
error | object | 失败时的 typed 错误,含 type / subtype / code / message / hint / log_id |
每行数据的字段值封装在 CellValue 中:
{
"dim_city": {
"value": "北京"
},
"total_amount": {
"value": 12345.00
}
}value:展示值(人员名称、选项名称、格式化日期等)
返回值
命令成功后输出 data 字段的内容:
{
"main_data": [
{
"dim_city": {"value": "直营"},
"measure_count": {"value": 1}
},
{
"dim_city": {"value": "加盟"},
"measure_count": {"value": 2}
}
]
}工作流
- 确认 base-token 和 table-id
- 先查表结构:执行
lark-cli base +field-list --base-token <base_token> --table-id <table_id> - 从返回的字段列表中获取 field_name(DSL 中使用的字段名称)
- 根据字段信息构造 DSL JSON
- 执行 +data-query
- 解读返回结果:
- 结果在
data.main_data数组中,每个元素代表一行 - 每行对象的 key 为 DSL 中指定的
alias;未指定 alias 时,key 为自动生成的列名 - 每个 value 是 CellValue 对象,实际值在
value字段中,如{"value": "北京"}或{"value": 12345.00} - 失败时结果在
data.error中,包含具体错误码和信息
与记录读取组合
+data-query 可返回聚合结果,也可在只传 dimensions 时返回维度字段行;这些维度行按字段组合去重,不包含 record_id,不能等同于逐条原始记录。需要输出聚合结果对应的原始记录字段、展示值、记录定位信息或关联表字段时,按以下方式组合:
- 用
+data-query在 Base 云端查询服务中完成全局筛选、分组、聚合、排序和 TopN,得到业务 key、分组值或候选字段组合。 - 如果已经拿到候选记录的
record_id,用+record-get读取逐条记录字段。 - 如果拿到的是结构化业务 key(例如编号、状态、日期、金额等),用
+record-list --filter-json做精确过滤后读取;+record-search用于文本展示值关键词。 - 只有候选条件本身是文本展示值关键词时,才使用
+record-search,并用search_fields限定范围、select_fields做投影。 - 若候选记录包含 link 字段,提取关联
record_id后到关联表用+record-get批量读取展示字段。 - 最终回答展示真实业务字段;内部
record_id用于连接或定位。
不要把 data-query pagination.limit 理解为分页扫描;它只限制 Base 云端查询服务返回的聚合结果行数,不支持 offset。需要逐条原始记录时按 Record 查询与分析 SOP 的完整读取或回查路径处理。
坑点
- ⚠️ 必须先查表结构:DSL 的
field_name必须与表中字段名称精确匹配(区分大小写),不能凭猜测构造。先用lark-cli base +field-list --base-token <base_token> --table-id <table_id>获取真实字段名 - ⚠️ 权限要求按文档类型分流:普通多维表格只需文档阅读权限;高级权限多维表格必须是文档管理员(FA / Full Access),否则返回权限错误
- ⚠️ alias 不支持中文:dimensions 和 measures 的 alias 必须使用英文(如
dim_city、total_amount),中文 alias 会导致错误 - ⚠️ API 路径是
base/v3:本接口路径为/open-apis/base/v3/bases/:base_token/data/query,不是bitable/v1。两者完全不同,用错版本号会返回[2200] Internal Error - ⚠️
dimensions和measures至少填一个:两个都不填会返回 DSL 校验错误 - ⚠️
shaper必须为{"format": "flat"}:不填或填其他值会导致结果格式不可预期,建议始终显式指定 - ⚠️ 数据表标识
tableIdvstableName:datasource 中可以用tableId(如tblXXX)或tableName(数据表的用户自定义显示名称),二选一,不要混用 - ⚠️
pagination.limit最大 5000:超过会报错,且不支持 offset,只支持 limit - ⚠️ 所有 alias 必须全局唯一:dimensions 和 measures 之间的 alias 也不能重名
参考
- lark-base — 多维表格全部命令
- lark-shared — 认证和全局参数
- Field Schema — 字段类型与 JSON 结构
base +field-create
前置条件: 先阅读 `../../lark-shared/SKILL.md` 了解认证、全局参数和安全规则。
创建一个或多个字段;同一表的多个字段优先使用一次 JSON 数组输入。
formula / lookup 创建前读取对应 guide;涉及跨表引用时同时读取目标表结构。
推荐命令
lark-cli base +field-create \
--base-token <base_token> \
--table-id <table_id> \
--json '{"name":"预算","type":"number","style":{"type":"plain","precision":2}}'
lark-cli base +field-create \
--base-token <base_token> \
--table-id <table_id> \
--json '{"name":"状态","type":"select","multiple":false,"default_value":["Todo"],"options":[{"name":"Todo","hue":"Blue","lightness":"Lighter"},{"name":"Done","hue":"Green","lightness":"Light"}]}'
# 多个字段复用相同字段 JSON 形状,一次传非空数组
lark-cli base +field-create \
--base-token <base_token> \
--table-id <table_id> \
--json '[{"name":"备注","type":"text"},{"name":"优先级","type":"select","multiple":false,"options":[{"name":"高"},{"name":"低"}]}]'参数
| 参数 | 必填 | 说明 |
|---|---|---|
--base-token <token> | 是 | Base Token |
--table-id <id_or_name> | 是 | 表 ID 或表名 |
--json <body> | 是 | 单个字段 JSON 对象,或多个字段对象组成的非空数组 |
API 入参详情
HTTP 方法和路径:
POST /open-apis/base/v3/bases/:base_token/tables/:table_id/fieldsJSON 值规范
--json接受单个字段 JSON 对象,也接受多个字段对象组成的非空数组;不要再套fields等外层对象。- 数组按顺序创建字段,遇到首个失败即停止且不自动回滚;部分失败时保留
items中的created项,按hint修正后只提交failed和not_attempted项,并保持依赖顺序。 - 每个字段对象最少包含:
name、type。 - 所有字段类型都支持可选
description;支持纯文本,也支持 Markdown 链接,如协作约定可参考[团队字段约定](https://example.com/field-spec)。 - 需要字段默认值时传
default_value,直接使用字段对应 CellValue;datetime/user的动态填充用$slot。完整规则见 Field Schema。 type不同,必填子字段不同:select:multiple控制是否多选,options定义静态选项,dynamic_options_source定义动态选项来源。静态与动态选项配置二选一,不能同时传。link:必须有link_table,可选bidirectional、bidirectional_link_field_name。formula:必须有expression;先读 formula guide,再创建。lookup:必须有from、select、where;先读 lookup guide,再创建。
正确(base +field-create)
{
"name": "状态",
"type": "select",
"multiple": false,
"default_value": ["Todo"],
"options": [
{ "name": "Todo", "hue": "Blue", "lightness": "Lighter" },
{ "name": "Done", "hue": "Green", "lightness": "Light" }
]
}参考
- Field Schema — 字段 JSON 规范(推荐)
- Formula Field — 创建公式必读
- Lookup Field — 创建查找引用必读
base field-extension
字段插件用于扩展基础字段能力,当同行其他单元格更新时,触发 LLM 推理生成新单元格。当前公开支持的插件 ID 只有 builtin_llm_completion,已确认可用于文本、单选、数字字段,让目标字段基于 prompt 和字段引用生成内容,并可手动触发该字段的单元格异步更新任务。
三个命令:
+field-extension-get:读取目标字段当前可识别的插件配置。+field-extension-update:安装、更新或清空目标字段插件配置。+field-extension-update-cells:对已配置字段插件的目标字段发起手动更新任务。
何时使用字段插件
用户明确要让某个已有字段根据其他字段自动生成内容、总结、分类、翻译、提取信息,且目标能力可以用 prompt 表达时,使用字段插件。当前已确认的目标字段类型是文本、单选、数字。
字段插件只能建立在已有字段上,不能创建列 schema。新建字段仍使用 +field-create;修改字段类型、选项、名称等 schema 属性仍使用 +field-update。
推荐命令
# 读取当前插件配置
lark-cli base +field-extension-get \
--base-token <base_token> \
--table-id <table_id> \
--field-id <target_field_id> \
--as user
# 安装或更新 LLM Completion 插件
lark-cli base +field-extension-update \
--base-token <base_token> \
--table-id <table_id> \
--field-id <target_field_id> \
--json '{"extension_id":"builtin_llm_completion","inputs":{"prompt":[{"type":"text","text":"请根据 "},{"type":"field_ref","field":"需求描述"},{"type":"text","text":" 输出一句简洁结论。"}]}}' \
--as user \
--yes
# 清空字段插件配置
lark-cli base +field-extension-update \
--base-token <base_token> \
--table-id <table_id> \
--field-id <target_field_id> \
--json '{}' \
--as user \
--yes
# 按视图范围触发整列更新
lark-cli base +field-extension-update-cells \
--base-token <base_token> \
--table-id <table_id> \
--field-id <target_field_id> \
--type column \
--view-id <view_id> \
--as user \
--yes
# 只更新指定记录
lark-cli base +field-extension-update-cells \
--base-token <base_token> \
--table-id <table_id> \
--field-id <target_field_id> \
--type row \
--record-id <record_id_1> \
--record-id <record_id_2> \
--as user \
--yes工作流
- 定位 Base、Table 和目标 Field。目标 Field 是承载插件输出的已有字段,不是 prompt 中被引用的输入字段。
- 用
+field-extension-get读取当前配置。返回current_extension=null表示未配置、无法识别或存量配置无法转换。 - 构造
+field-extension-update --json。安装或更新时传extension_id=builtin_llm_completion和inputs.prompt;清空时传{}。 - 配置成功后,只有用户明确要立即生成或刷新已有单元格时,才调用
+field-extension-update-cells发起异步生成任务。 - 需要验收结果时,等待任务完成或稍后用记录读取命令抽样查看目标字段单元格;
update_cells只返回任务 ID,不直接返回生成结果。
JSON 结构
通用结构
+field-extension-update --json 的顶层结构是字段插件配置 envelope。不同 extension_id 对应不同的 inputs 结构;不要把某个插件的 inputs 当成所有字段插件的固定结构。
| 字段 | 类型 | 说明 |
|---|---|---|
extension_id | string | 插件 ID。当前公开只支持 builtin_llm_completion |
inputs | object | 插件配置对象,结构由 extension_id 决定 |
清空字段插件配置时传空对象:
{}builtin_llm_completion
当前 builtin_llm_completion 用于让已有字段根据 prompt 生成内容。它的 inputs 结构如下:
| 字段 | 类型 | 说明 |
|---|---|---|
inputs.prompt | PromptSegment[] | 有序 prompt 片段数组 |
prompt[].type | string | text 或 field_ref |
prompt[].text | string | type=text 时必填 |
prompt[].field | string | type=field_ref 时必填,可传当前表的字段 ID 或字段名 |
安装或更新示例:
{
"extension_id": "builtin_llm_completion",
"inputs": {
"prompt": [
{
"type": "text",
"text": "请根据 "
},
{
"type": "field_ref",
"field": "需求描述"
},
{
"type": "text",
"text": " 输出一句简洁的中文结论。"
}
]
}
}field_ref 只能引用当前表中的其他字段,不能引用目标字段自身;附件字段和其他不支持字段不要作为引用字段。
更新单元格
+field-extension-update-cells 有两种范围:
这是异步生成任务,响应只表示任务已创建。单元格越多,生成和写回通常耗时越久;整列更新尤其需要控制范围。
| 范围 | 参数 | 语义 |
|---|---|---|
--type column | 可选 --view-id | 更新目标字段在该视图范围内的单元格;不传 --view-id 时后端使用目标表首视图 |
--type row | 必填一个或多个 --record-id | 只更新这些记录上的目标字段单元格 |
--type row 不要传 --view-id;--type column 不要传 --record-id。
响应只返回:
{
"task_id": "<task_id>"
}返回重点
读取和写配置都返回 current_extension:
- 已配置并可识别时,
current_extension.extension_id表示插件 ID,current_extension.inputs是该插件对应的配置对象。 - 未配置或当前无法识别时,
current_extension为null。
权限和风险
+field-extension-get是只读命令,权限base:field:read。+field-extension-update是高风险写命令,权限base:field:update,会改变目标字段的自动生成配置,执行时必须带--yes。+field-extension-update-cells是高风险写命令,权限base:record:update,会触发目标字段单元格异步写回,执行时必须带--yes。- 用户需要具备管理目标表或目标字段插件的权限才能触发更新任务;如果接口返回权限不足,先按 Base 权限或高级权限角色确认用户权限。
注意事项
- 目标字段必须是当前字段插件已支持的字段类型;当前已确认支持文本、单选、数字字段。不要把字段插件当成任意字段类型都可用的通用能力。
- 写入插件配置后,自动更新会强制开启;当前不提供关闭自动更新的参数。
- 读取接口中的
field_ref.field通常返回字段名称;字段名称不可用时可能返回字段 ID。 +field-extension-update不返回input_schemas。+field-extension-update-cells --type column可能触发大量 AI 生成任务,单元格越多耗时通常越久;除非用户明确要求整列刷新,否则优先按--type row精确更新目标记录。
base +field-update
前置条件: 先阅读 `../../lark-shared/SKILL.md` 了解认证、全局参数和安全规则。
更新一个已有字段。
推荐命令
lark-cli base +field-update \
--base-token <base_token> \
--table-id <table_id> \
--field-id <field_id> \
--json '{"name":"状态","type":"select","multiple":false,"default_value":["Doing"],"options":[{"name":"Todo","hue":"Blue","lightness":"Lighter"},{"name":"Doing","hue":"Orange","lightness":"Light"},{"name":"Done","hue":"Green","lightness":"Light"}]}' \
--yes
参数
| 参数 | 必填 | 说明 |
|---|---|---|
--base-token <token> | 是 | Base Token |
--table-id <id_or_name> | 是 | 表 ID 或表名 |
--field-id <id_or_name> | 是 | 字段 ID 或字段名 |
--json <body> | 是 | 字段属性 JSON 对象 |
--yes | 是 | 确认执行高风险字段更新 |
这是高风险写入操作。
+field-update使用PUT全量字段定义语义;改变字段类型或关键配置可能影响整列已有数据的解释、展示或可用性。CLI 层要求显式传--yes;如果用户已经明确目标和期望更新,可直接执行并带上--yes。
API 入参详情
HTTP 方法和路径:
PUT /open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_idJSON 值规范
--json必须是 JSON 对象,顶层直接传字段定义。- 更新语义是 override 式的完整覆盖
PUT,不是 partial update;先读取当前定义,再提交整个字段需要保留的可写配置,不要只传零散片段。 - 所有字段类型都支持可选
description;支持纯文本,也支持 Markdown 链接。 - 需要字段默认值时传
default_value,直接使用字段对应 CellValue;传null清空。完整规则见 Field Schema。 select更新时:options仍按对象数组传,避免混入无效字段。link更新限制:- 不能把非
link字段改成link,也不能把link改成非link。 - 现有
link字段的bidirectional不能改。 - 更新
auto_number.style.rules会按新规则更新已有记录的编号;规则结构见 Field Schema。
推荐更新示例
{
"name": "状态",
"type": "select",
"multiple": false,
"default_value": ["Doing"],
"options": [
{ "name": "Todo", "hue": "Blue", "lightness": "Lighter" },
{ "name": "Doing", "hue": "Orange", "lightness": "Light" },
{ "name": "Done", "hue": "Green", "lightness": "Light" }
]
}返回重点
- 返回
field和updated: true。 - 按返回的
next_step和verification_hint继续;类型转换涉及已有值时抽样读取记录。
工作流
- 先用
+field-get读取当前定义,只改变目标属性,并把需要保留的其他可写配置完整写回。 formula/lookup类型更新前先阅读对应指南。- 如果这次更新会改变字段
type,先按下方“字段类型变更规则”判断能否执行。如果不修改type,大多数场景都相对安全。
字段类型变更规则
字段类型变更采用白名单机制:只允许白名单转换;未命中白名单时,不建议用 CLI 转换字段类型 除非用户明确知道风险并同意。
允许直接转换 type
先 +field-get / +field-list 看结构,再抽样读值;只有命中以下规则时,转换才是比较安全的。
相对安全
| 目标类型 | 允许的源类型 | 说明 |
|---|---|---|
text | number、select、datetime、created_at、updated_at、location(只保留 full_address)、auto_number、checkbox | 保留字符串表示;丢失原类型语义和结构化能力 |
number | text、number、datetime、created_at、updated_at、checkbox | 保留可解析的数字值;无法解析的值会变空,原文本格式会丢失 |
datetime | text、number、datetime、created_at、updated_at | 保留可解析的时间字符串和时间戳;无法解析的值会变空,原文本格式会丢失 |
select | text -> select、number -> select、single select -> multi select | 只有完全匹配目标选项名的值会转成对应选项;没匹配上的值会被丢弃 |
可执行但会截断 / 重算
select(multi) -> select(single): 只保留第一个值,其余值会被丢弃。user(multi) -> user(single): 只保留第一个人员,其余值会被丢弃。group_chat(multi) -> group_chat(single): 只保留第一个群,其余值会被丢弃。
无状态字段可直接转换
created_at、created_by、updated_at、updated_by、formula、lookup: 这类字段值由系统或计算逻辑生成,不承载独立存储数据;可以执行类型转换,不必担心破坏原始记录值,但仍要做下游读回验证。
一律不要用 CLI 转换
以下场景全部视为黑名单;默认要求用户改到 Web 页面手动完成,或改走“新建字段 + 数据迁移”。
any -> checkboxany -> userany -> group_chatany -> attachmentany -> locationlink类型变更- 任意涉及动态 / 静态选项来源切换的
select类型变更
可例外继续执行的场景
只有在整列数据丢失可接受时,才允许对黑名单场景例外执行。
- 该列为空。
- 正在初始化新建的空表。
- 主字段不能删除,需要通过更新完成初始化。
- 用户明确接受整列数据丢失。
不满足以上条件时,不要转换。
非白名单场景如何处理
- 命中白名单时:建议直接原地转换,再做读回验证。
- 未命中白名单时:先询问用户是否仍要执行转换,并明确说明风险:
- 无状态字段除外;这类字段可以直接转换
- 可能整列变空
- 可能只保留第一个值
- 可能只保留字符串表示,丢失原类型语义和结构化能力
- 可能影响视图 / 筛选 / 排序 / 公式 / lookup / 写入引用
- 如果用户不接受风险:不要执行转换。
坑点
- ⚠️ 这是全量字段属性更新语义,不是 patch。
- ⚠️ 这是高风险写入操作,执行时必须带
--yes。 - ⚠️ 当
type是formula或lookup时,先阅读对应指南再执行。
参考
- 更新前读取当前字段,确认现有
type和具体配置细节,再决定是原地更新还是新建字段迁移。 - Field Schema — 字段 JSON 规范(推荐)
- Formula Field — 更新公式前必读
- Lookup Field — 更新查找引用前必读
base +record-history-list
查询单条记录的变更历史。它返回历史事件,不返回记录当前值,也不支持整表审计扫描。
使用前置
+record-history-list 仅查询单条记录。调用前必须获得能唯一对应用户指定目标、且与 table_id 属于同一张表的 record_id。
如果当前信息无法唯一确定目标记录,先向用户确认,必要时用 +record-list 辅助定位;不得自行选择记录,也不得扩展为批量或整表扫描。需要查询多条记录时,先确认范围,再逐条调用。
用 +record-list 展示候选时,可重复传入 --field-id 做最小投影。字段名包含空格时,需要给完整值加引号,例如 --field-id "Project Owner"。
用户明确指定某个视图的第 N 行时,先用同一 view_id 调用 +record-list,并将 --offset 设为 N-1、--limit 设为 1,再从唯一结果中取得 record_id。视图或排序上下文不明确时仍需先确认。
推荐命令
lark-cli base +record-history-list \
--base-token <base_token> \
--table-id <table_id> \
--record-id <record_id>
lark-cli base +record-history-list \
--base-token <base_token> \
--table-id <table_id> \
--record-id <record_id> \
--page-size 30 \
--max-version <next_max_version>
lark-cli base +record-history-list \
--base-token <base_token> \
--table-id <table_id> \
--record-id <record_id> \
--format pretty返回解释
- 历史条目通常按版本号降序返回,最新在前。
- 每条历史包含版本号、操作人、操作时间、操作类型和字段变更。
- 默认 JSON 中的
create_time是秒级 Unix 时间戳;--format pretty会将其转换为带 UTC 偏移的本地时间,并和操作人、字段变化放在同一行。 field_changes描述字段变更,重点看字段名/字段类型、before和after。--format pretty中空的before或after显示为-;默认 JSON 保留原始值。activity_type常见值:create(创建记录)、update(编辑记录)、delete(删除记录)。
以下字段类型的变化可能不会出现在 field_changes 中:
- 计算字段:
formula、lookup - 系统字段:自动编号、创建时间、创建人、修改时间、修改人
翻页
- 首次请求不传
--max-version。 - 如果返回
has_more=true,取返回中的next_max_version作为下一次请求的--max-version。 --page-size默认 30,最大 50。
注意
table-id和record-id必须来自同一张表。- 这是单条记录历史,不是表级审计;用户明确要求查询多条记录时,先确认目标范围,再按记录串行调用。
Which skills are related to lark-base?
How does lark-base compare?
Pick lark-base for live Bitable CRUD and analytics; use lark-drive when importing local Excel, CSV, or .base snapshots into a new table.
Lark Base skill FAQ
Who is the Lark Base skill for?
Developers building agent-driven workflows over Feishu/Lark Bitable with field design, formulas, aggregations, or cross-table analytics. Skip lark-base for importing local Excel or CSV into a new Base—use lark-drive +import --type bitable first.
When should I use lark-base?
User needs to search Base, manage fields, read/write records, configure views, or run filtered aggregations on Feishu multidimensional tables.
When must lark-base read the data-analysis SOP?
lark-base requires reading references/lark-base-data-analysis-sop.md before any task involving filters, sorting, Top/Bottom N, aggregations, multi-table joins, or query-then-write workflows, so the agent picks record, view, or data-query correctly.
What lark-cli prefix does lark-base use?
lark-base uses only lark-cli base +... business commands for tables, fields, records, views, dashboards, and workflows. Legacy +table, +field, and +record forms should be migrated to the current +command syntax guided by the skill.
Is Lark Base safe to install?
skills.sh reports 2 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.
Add a lark-base badge
Show developers this skill is listed on Skillselion. Paste this into your README.