Cli lark-base
当需要用 lark-cli 操作飞书多维表格（Base）时调用：适用于建表、字段管理、记录读写、视图配置、历史查询，以及角色/表单/仪表盘管理/工作流；也适用于把旧的 +table / +field / +record 写法改成当前命令写法。涉及字段设计、公式字段、查找引用、跨表计算、行级派生指标、数据分析需求时也必须使用本 skill。
install
source · Clone the upstream repo
git clone https://github.com/larksuite/cli
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/larksuite/cli "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/lark-base" ~/.claude/skills/larksuite-cli-lark-base && rm -rf "$T"
manifest:
skills/lark-base/SKILL.mdsource content
base
前置条件： 先阅读
。 执行前必做： 执行任何../lark-shared/SKILL.md命令前，必须先阅读对应命令的 reference 文档，再调用命令。 命名约定： Base 业务命令仅使用base形式；如需先解析 Wiki 链接，可先调用lark-cli base +...。 分流规则： 如果用户要“把本地文件导入成 Base / 多维表格 / bitable”，第一步不是lark-cli wiki ...，而是base；导入完成后再回到lark-cli drive +import --type bitable做表内操作。lark-cli base +...
1. 何时使用本 Skill
1.1 触发条件
以下场景应使用本 skill：
- 用户明确要操作飞书多维表格 / Base。
- 用户要建表、改表、查表、删表，或管理字段、记录、视图。
- 用户要做公式字段、lookup 字段、派生指标、跨表计算。
- 用户要做临时统计、聚合分析、比较排序、求最值。
- 用户要管理 workflow、dashboard、表单、角色权限。
- 用户给出
链接。/base/{token} - 用户给出
链接，且最终解析为/wiki/{token}
。bitable - 用户要把旧的 Base 聚合式写法改成当前原子命令写法，例如把旧
改写成当前命令。+table / +field / +record / +view / +history / +workspace
以下场景不应使用本 skill：
- 用户只是做认证、初始化配置、切换
、处理 scope。此时先读--as user/bot
。../lark-shared/SKILL.md - 用户只是泛化地讨论“数据分析 / 字段设计”，但并不在 Base 场景中。不要因为提到“统计 / 公式 / lookup”就误触发。
1.2 前置约束
- 先阅读
。../lark-shared/SKILL.md - Base 业务命令仅使用
形式的 shortcut 命令；如果输入是 Wiki 链接，可先调用lark-cli base +...
解析真实 token。lark-cli wiki spaces get_node - 定位到命令后，先读该命令对应的 reference，再执行命令。
- 如果用户要把本地 Excel / CSV 导入成 Base / 多维表格 / bitable，第一步不是
，而是base
；导入完成后再回到lark-cli drive +import --type bitable
做表内操作。lark-cli base +... - 不要在 Base 场景改走
。lark-cli api /open-apis/bitable/v1/...
2. 模块与命令导航
本章按“先选模块，再选命令”的方式组织。先判断用户目标属于哪个大模块，再进入对应子模块，按要求阅读 reference 后执行命令。
2.1 模块地图
| 大模块 | 处理什么问题 | 包含的小模块 / 能力 |
|---|---|---|
| Base 模块 | 管理 Base 本体，或从链接进入 Base 场景 | |
| 表与数据模块 | 管理 Base 内部结构与日常数据操作 | |
| 公式 / Lookup 模块 | 处理派生字段、条件判断、跨表计算、固定查找引用 | |
| 数据分析模块 | 做一次性筛选、分组、聚合分析 | |
| Workflow 模块 | 管理自动化流程 | |
| Dashboard 模块 | 管理仪表盘和图表组件 | |
| 表单模块 | 管理表单和表单题目 | |
| 权限与角色模块 | 管理高级权限和自定义角色 | |
2.2 Base 模块
用于管理 Base 本体，或从用户给出的链接进入后续 Base 操作。
模块索引：references/lark-base-workspace.md
| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 |
|---|---|---|---|
| 创建新的 Base | | 写入操作；执行前先读 reference； |
| 获取 Base 信息 | | 适合确认 Base 本体信息，不替代表/字段结构读取 |
| 复制已有 Base | | 写入操作；执行前先读 reference；复制成功后应主动返回新 Base 标识信息 |
2.3 表与数据模块
这是最常用的大模块，包含
table / field / record / view补充示例：
references/examples.md2.3.1 Table 子模块
子模块索引：references/lark-base-table.md
| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 |
|---|---|---|---|
| 列出数据表，或获取单个表详情 | | |
| 创建、更新或删除数据表 | | 创建适合一次性建表；更新前先确认目标表；删除时用户已明确目标可直接执行并带 |
2.3.2 Field 子模块
普通字段管理走这里；如果字段类型是
formulalookup子模块索引：
references/lark-base-field.md| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 |
|---|---|---|---|
| 列出字段结构，或获取单个字段详情 | | 写记录、写字段、做分析前常先读 |
| 创建、更新或删除普通字段 | | 写字段前先看字段属性规范；如果类型是 |
| 查询字段可选项 | | 适合单选/多选等选项型字段 |
2.3.3 Record 子模块
子模块索引：
、references/lark-base-record.mdreferences/lark-base-history.md
| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 |
|---|---|---|---|
| 按关键词检索记录、读取记录明细 / 分页导出，或获取单条记录详情 | | 默认优先 |
| 创建、更新或批量写入记录 | | 写前先 |
| 给已有记录上传附件 | | 附件上传专用链路，不要用 |
| 下载 Base 附件文件到本地 | | Base 附件的 |
| 删除记录，或查询某条记录的变更历史 | | 删除时用户已明确目标可直接执行并带 |
2.3.4 View 子模块
子模块索引：references/lark-base-view.md
| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 |
|---|---|---|---|
| 列出视图，或获取视图详情 | | |
| 创建、删除或重命名视图 | | 创建前先确认表和视图类型；删除前先确认目标；用户已明确新名字时可直接重命名 |
| 读取或配置筛选条件 | | 常与 |
| 读取或配置排序 | | 字段名必须来自真实结构 |
| 读取或配置分组 | | 字段名必须来自真实结构 |
| 读取或配置视图可见字段 | | 用于控制视图中的字段顺序与可见性；字段名必须来自真实结构 |
| 读取或配置卡片视图 | | 适合卡片展示场景 |
| 读取或配置时间轴视图 | | 适合时间线展示场景 |
2.4 公式 / Lookup 模块
只要用户诉求涉及派生指标、条件判断、文本处理、日期差、跨表计算、跨表筛选后取值，都要先判断是否进入本模块。
默认优先考虑
formula只有当用户明确要求
lookupfrom / select / where / aggregatelookup| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 |
|---|---|---|---|
| 创建公式字段 | | 没读 guide 前不要直接创建 |
| 更新公式字段 | | 先拿当前表结构 |
| 创建 lookup 字段 | | 没读 guide 前不要直接创建 |
| 更新 lookup 字段 | | 跨表时还要拿目标表结构 |
2.5 数据分析模块
用于一次性分析和临时聚合查询。用户要的是“这次算出来的结果”，而不是把结果沉淀成字段时，优先进入本模块。
进入本模块前先确认几件事：
只做聚合查询（分组、过滤、排序、聚合计算），不用于列出原始记录或逐条明细。+data-query- 调用者必须是目标多维表格的管理员，拥有目标多维表格的 FA（Full Access / 完全访问权限），否则会返回权限错误。
只支持白名单字段类型；+data-query
、formula
、附件、系统字段、关联等字段不能用于lookup
。dimensions / measures / filters / sort
| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 |
|---|---|---|---|
| 做分组统计、SUM / AVG / COUNT / MAX / MIN、条件筛选后的聚合分析 | | 字段名必须精确匹配真实字段名；不要用 |
2.6 Workflow 模块
这是高约束模块。执行任何 workflow 命令前，都必须先读对应命令文档和 schema。
模块索引：references/lark-base-workflow.md
| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 |
|---|---|---|---|
| 列出 workflow，或获取完整 workflow 结构 | | |
| 创建或更新 workflow | | 先读 schema；禁止凭自然语言猜 |
| 启用或停用 workflow | | 启用或停用前先确认目标 workflow； |
2.7 Dashboard 模块
当用户提到“仪表盘、dashboard、数据看板、图表、可视化、block、组件、添加组件、创建图表”等关键词时，进入本模块，并先阅读
。lark-base-dashboard.md
| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 |
|---|---|---|---|
| 列出仪表盘，或获取仪表盘详情 | | 进入仪表盘语义后先读 guide； |
| 创建、更新或删除仪表盘 | | 创建前先明确看板目标和展示场景；更新前先读取当前配置；删除前先确认目标 |
| 列出图表组件，或获取单个 block 详情 | | |
| 创建、更新或删除图表组件 | | 涉及 |
2.8 表单模块
用于管理表单本体和表单题目。
模块索引：
、references/lark-base-form.mdreferences/lark-base-form-questions.md
表单问题相关操作依赖
form-idform-listform-create| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 |
|---|---|---|---|
| 列出表单，或获取单个表单 | | |
| 创建、更新或删除表单 | | 创建后可继续进入表单问题相关操作；更新或删除前先确认目标表单 |
| 列出表单题目 | | 适合查看已有题目结构 |
| 创建、更新或删除题目 | | 先确认 |
2.9 权限与角色模块
用于启用高级权限，以及管理 Base 自定义角色。
涉及
+advperm-enable / +advperm-disable / +role-*| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 |
|---|---|---|---|
| 启用或停用高级权限 | | 管理角色前必须先启用；停用是高风险操作，会使已有自定义角色失效 |
| 列出角色，或获取角色详情 | | |
| 创建、更新或删除角色 | | |
3. 多维表格通用知识
飞书多维表格英文名是
BaseBitablebitable3.1 字段分类与可写性
| 字段类型 | 含义 | 能否直接作为 | 说明 |
|---|---|---|---|
| 存储字段 | 真实存用户输入的数据 | 可以 | 常见如文本、数字、日期、单选、多选、人员、关联 |
| 附件字段 | 存储文件附件 | 不应直接按普通字段写 | 上传附件走 |
| 系统字段 | 平台自动维护 | 不可以 | 常见如创建时间、更新时间、创建人、修改人、自动编号 |
| 通过表达式计算 | 不可以 | 只读字段 |
| 通过跨表规则查找引用 | 不可以 | 只读字段 |
3.2 任务选路心智模型
| 用户诉求 | 优先方案 | 不要误走 |
|---|---|---|
| 一次性分析 / 临时统计 | | 不要用 |
| 要把结果长期显示在表里 | | 不要只给一次性手工分析结果 |
| 用户明确要求 lookup，或天然是固定查找配置 | | 不要默认先上 lookup；先判断 formula 是否更合适 |
| 读取原始记录明细 / 关键词检索 / 导出 | | 不要拿 |
| 上传附件到记录 | | 不要用 |
| 下载记录里的附件文件 | | |
| 基于视图做筛选读取 | | 不要跳过视图筛选直接猜条件 |
| 本地 Excel / CSV 导入为 Base | | 不要误走 |
3.3 表名、字段名与表达式引用
- 表名、字段名必须精确匹配真实返回，来源应是
。+table-list / +table-get / +field-list - 不要凭自然语言猜名称，不要自行改写用户口述中的表名、字段名。
中出现的名称同样必须精确匹配；表达式引用、where 条件、DSL 字段名、workflow 配置都遵守同一规则。formula / lookup / data-query / workflow- 跨表场景必须额外读取目标表结构，不能只看当前表。
3.4 Token 与链接
这是高优先级章节。只要用户输入里出现链接、token，或报错涉及
baseTokenwiki_tokenobj_token| 输入类型 | 正确处理方式 | 说明 |
|---|---|---|
直接 Base 链接 | 直接提取 token 作为 | 不要把完整 URL 直接作为 |
Wiki 链接 | 先 | 不要把 |
URL 中的 | 先按前缀判断对象类型 | |
URL 中的 | 提取为 | 适合直接定位视图 |
| 后续路线 | 说明 |
|---|---|---|
| 优先走 | 如果 shortcut 不覆盖，再用 |
| 转到文档 / Drive 相关 skill | 不继续使用本 skill 的 Base 命令 |
| 转到 Sheets 相关 skill | 不继续使用本 skill 的 Base 命令 |
| 转到 Drive 相关 skill | 不继续使用本 skill 的 Base 命令 |
| 转到 Drive 相关 skill | 不继续使用本 skill 的 Base 命令 |
3.5 身份选择与权限降级策略
多维表格通常属于用户的个人或团队资源。默认应优先使用
（用户身份）执行所有 Base 操作，始终显式指定身份。--as user
（推荐）：以当前登录用户身份操作其有权访问的 Base。执行前先完成用户授权：--as user
lark-cli auth login --domain base
（降级）：仅当 user 身份权限不足、且 bot 身份确实拥有目标 Base 的访问权限时，才降级使用。bot 看不到用户私有资源，行为以应用身份执行。--as bot
执行规则：
- 所有操作默认先用
。--as user - 若 user 身份返回权限错误，先判断是否为不可重试错误码（如
）。若是，立即停止，不做任何重试或降级，直接按91403
权限不足处理流程引导用户解决。lark-shared - 非不可重试错误码时，检查错误响应中是否包含
/permission_violations
等提权引导信息：hint- 有提权引导：按
权限不足处理流程，先引导用户完成 user 身份提权（lark-shared
）；确认提权成功后，以auth login --scope
重试。--as user - 无提权引导（如资源级无访问权限、非 scope 不足）：切换到
重试一次。--as bot
- 有提权引导：按
- 若 bot 身份仍然返回权限错误，立即停止重试，根据错误响应按
流程引导用户解决（引导去开发者后台开通 scope 或确认资源访问权限）。lark-shared - 只有在用户明确要求"用应用身份 / bot 身份操作"，才跳过 user 直接使用
。--as bot
补充说明：
- 人员字段 / 用户字段：注意
与执行身份（user / bot）差异。user_id_type
4. 执行规则
4.1 标准执行顺序
- 先判断任务属于哪个模块，选对命令族。
- 如果用户给了链接，先解析 token，不要把 wiki token、完整 URL 或其他对象 ID 误当成
。base_token - 先拿结构，再写命令，避免猜表名、字段名、表达式引用。
- 定位到命令后，先读对应 reference，再执行命令。
- 执行命令，并按返回结果判断下一步。
- 回复时返回关键结果和后续可继续操作的信息，方便 agent 链式执行下一步。
4.2 不可违反规则
- 先拿结构，再写命令；至少先拿当前表结构，跨表时还要拿目标表结构。
- 不要猜表名、字段名、表达式引用，一律以真实返回为准。
- 只使用原子命令；不要回退到旧的聚合式
。+table / +field / +record / +view / +history / +workspace - 写记录前先读字段结构；先
，再按字段类型构造写入值。+field-list - 写字段前先看字段属性规范；先读
，再构造lark-base-shortcut-field-properties.md
的 JSON。+field-create / +field-update - 只写可写字段；系统字段、附件字段、
、formula
默认不作为普通记录写入目标。lookup - 聚合分析与取数分流；统计走
，关键词检索走+data-query
，明细走+record-search
。+record-list / +record-get - 筛选查询按视图能力执行；先用
配置筛选，再结合+view-set-filter
读取。+record-list - Base 场景不要改走裸 API，不要切去
。lark-cli api /open-apis/bitable/v1/... - 统一使用
，不使用旧--base-token
。--app-token - workflow 场景先读 schema，不要凭自然语言猜
。type - dashboard 场景先读 guide；提到图表、看板、block 就先进入 dashboard 模块。
- formula / lookup 场景先读 guide；没读 guide 前不要直接创建或更新。
4.3 并发、分页与批量限制
禁止并发调用，只能串行执行。+table-list / +field-list / +record-list / +view-list / +record-history-list / +role-list / +dashboard-list / +dashboard-block-list / +workflow-list
分页时，+record-list
最大--limit
；先拉首批并检查200
，只有用户明确需要更多数据时再继续翻页。has_more- 批量写入时，单批不超过
条。200 - 连续写入同一表时，必须串行写入，批次间延迟
秒。0.5–1
4.4 确认与回复规则
- 视图重命名时，用户已明确“把哪个视图改成什么名字”时，
直接执行即可。+view-rename - 删除记录 / 字段 / 表时，如果用户已经明确说要删除，且目标明确，
可直接执行，并带+record-delete / +field-delete / +table-delete
。--yes - 删除目标仍有歧义时，先用
或相应 list 命令确认。+record-get / +field-get / +table-get
成功后，回复中必须主动返回新 Base 的标识信息；若结果带可访问链接，也应一并返回。+base-create / +base-copy- 若 Base 由 bot 身份创建或复制，shortcut 会自动尝试为当前 CLI 用户补授
，并在输出中返回full_access
；agent 不需要再手动编排单独授权。owner 转移必须单独确认，禁止擅自执行。permission_grant
5. 常见错误与恢复
| 错误 / 现象 | 含义 | 恢复动作 |
|---|---|---|
| 日期格式错误 | 用毫秒时间戳，非字符串 / 秒级 |
| 超链接格式错误 | 用 |
| 人员字段错误 | 用 |
| 字段名不存在 | 检查字段名（含空格、大小写） |
| 字段值类型不匹配 | 先 |
| 把 wiki token、workspace token 或其他 token 当成了 | 如果输入来自 |
| 常见于把 wiki token 当成 base token | 优先回退检查 wiki 解析，而不是改走 |
| formula / lookup 创建失败 | 指南未读或结构不合法 | 先读 |
| 系统字段 / 公式字段写入失败 | 只读字段被当成可写字段 | 改为写存储字段，计算结果交给 formula / lookup / 系统字段自动产出 |
| 批量超 200 条 | 分批调用 |
| 并发写冲突 | 串行写入 + 批次间延迟 |
| 无权限访问该 Base | 不要重试。按 |