lark-base
飞书多维表格(Base)操作:建表、字段、记录、视图、统计、公式/lookup、表单、仪表盘、应用模式(BaseApp/AppMode 页面与组件)、Workspace 目录、workflow、角色权限、模板中心(多维表格模板分类/列表/搜索);遇到 Base/多维表格/bitable、BaseApp/AppMode、/base/ 或 /app/ 链接时使用。BaseApp 不走 lark-apps;文件导入/导出转 lark-drive,认证/授权转 lark-shared。
larksuite · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add larksuite/cli --skill lark-base技能说明
name: lark-base version: 1.2.21 description: "飞书多维表格(Base)操作:建表、字段、记录、视图、统计、公式/lookup、表单、仪表盘、应用模式(BaseApp/AppMode 页面与组件)、Workspace 目录、workflow、角色权限、模板中心(多维表格模板分类/列表/搜索);遇到 Base/多维表格/bitable、BaseApp/AppMode、/base/ 或 /app/ 链接时使用。BaseApp 不走 lark-apps;文件导入/导出转 lark-drive,认证/授权转 lark-shared。" metadata: requires: bins: ["lark-cli"] cliHelp: "lark-cli base --help"
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 条件结构](re
阅读完整来源 ↗