name: lark-base version: 1.2.0 description: "当需要用 lark-cli 操作飞书多维表格（Base）时调用：适用于建表、字段管理、记录读写、记录分享链接、视图配置、历史查询，以及角色/表单/仪表盘管理/工作流；也适用于把旧的 +table / +field / +record 写法改成当前命令写法。涉及字段设计、公式字段、查找引用、跨表计算、行级派生指标、数据分析需求时也必须使用本 skill。" metadata: requires: bins: ["lark-cli"] cliHelp: "lark-cli base --help"

base

前置条件： 先阅读 `../lark-shared/SKILL.md`。

执行前必做： 执行任何 base 命令前，必须先阅读对应命令的 reference 文档，再调用命令。

命名约定： Base 业务命令仅使用 lark-cli base +... 形式；如需先解析 Wiki 链接，可先调用 lark-cli wiki ...。

分流规则： 如果用户要“把本地文件导入成 Base / 多维表格 / bitable”，第一步不是 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：

• 用户只是做认证、初始化配置、切换 --as user/bot、处理 scope。此时先读 ../lark-shared/SKILL.md。
• 用户只是泛化地讨论“数据分析 / 字段设计”，但并不在 Base 场景中。不要因为提到“统计 / 公式 / lookup”就误触发。

1.2 前置约束

1. 先阅读 `../lark-shared/SKILL.md`。
2. Base 业务命令仅使用 lark-cli base +... 形式的 shortcut 命令；如果输入是 Wiki 链接，可先调用 lark-cli wiki spaces get_node 解析真实 token。
3. 定位到命令后，先读该命令对应的 reference，再执行命令。
4. 如果用户要把本地 Excel / CSV / .base 快照导入成 Base / 多维表格 / bitable，第一步不是 base，而是 lark-cli drive +import --type bitable；导入完成后再回到 lark-cli base +... 做表内操作。
5. 不要在 Base 场景改走 lark-cli api /open-apis/bitable/v1/...。

2. 模块与命令导航

本章按“先选模块，再选命令”的方式组织。先判断用户目标属于哪个大模块，再进入对应子模块，按要求阅读 reference 后执行命令。

2.1 模块地图

2.2 Base 模块

用于管理 Base 本体，或从用户给出的链接进入后续 Base 操作。 模块索引：`references/lark-base-workspace.md`

2.3 表与数据模块

这是最常用的大模块，包含 table / field / record / view 四类子模块。 补充示例：`references/examples.md`，适合需要串联 table / record / view 完整操作链路时再读。

2.3.1 Table 子模块

子模块索引：`references/lark-base-table.md`

2.3.2 Field 子模块

普通字段管理走这里；如果字段类型是 formula 或 lookup，转到下方“公式 / Lookup 模块”。 子模块索引：`references/lark-base-field.md`

2.3.3 Record 子模块

子模块索引：`references/lark-base-record.md`、`references/lark-base-history.md`

2.3.4 View 子模块

子模块索引：`references/lark-base-view.md`

2.4 公式 / Lookup 模块

只要用户诉求涉及派生指标、条件判断、文本处理、日期差、跨表计算、跨表筛选后取值，都要先判断是否进入本模块。

默认优先考虑 formula：适合常规计算、条件判断、文本处理、日期差、跨表聚合，以及需要长期显示在表里的派生结果。 只有当用户明确要求 lookup，或场景天然符合 from / select / where / aggregate 这种固定查找建模时，再使用 lookup。

2.5 数据分析模块

用于一次性分析和临时聚合查询。用户要的是“这次算出来的结果”，而不是把结果沉淀成字段时，优先进入本模块。

进入本模块前先确认几件事：

• +data-query 只做聚合查询（分组、过滤、排序、聚合计算），不用于列出原始记录或逐条明细。
• 调用者必须是目标多维表格的管理员，拥有目标多维表格的 FA（Full Access / 完全访问权限），否则会返回权限错误。
• +data-query 只支持白名单字段类型；formula、lookup、附件、系统字段、关联等字段不能用于 dimensions / measures / filters / sort。

2.6 Workflow 模块

这是高约束模块。执行任何 workflow 命令前，都必须先读对应命令文档和 schema。 模块索引：`references/lark-base-workflow.md`

2.7 Dashboard 模块

当用户提到“仪表盘、dashboard、数据看板、图表、可视化、block、组件、添加组件、创建图表”等关键词时，进入本模块，并先阅读 `lark-base-dashboard.md`。

2.8 表单模块

用于管理表单本体和表单题目。 模块索引：`references/lark-base-form.md`、`references/lark-base-form-questions.md` 表单问题相关操作依赖 form-id；具体获取方式见 form-list 和 form-create 的 reference。

2.9 权限与角色模块

用于启用高级权限，以及管理 Base 自定义角色。 涉及 +advperm-enable / +advperm-disable / +role-* 时，操作用户必须为 Base 管理员，否则会返回权限错误。

3. 多维表格通用知识

飞书多维表格英文名是 Base，曾用名 Bitable；因此旧文档、返回字段、参数名或错误信息里出现 bitable 多属历史兼容，不代表应改用另一套命令体系。

3.1 字段分类与可写性

3.2 任务选路心智模型

3.3 表名、字段名与表达式引用

1. 表名、字段名必须精确匹配真实返回，来源应是 +table-list / +table-get / +field-list。
2. 不要凭自然语言猜名称，不要自行改写用户口述中的表名、字段名。
3. formula / lookup / data-query / workflow 中出现的名称同样必须精确匹配；表达式引用、where 条件、DSL 字段名、workflow 配置都遵守同一规则。
4. 跨表场景必须额外读取目标表结构，不能只看当前表。

3.4 Token 与链接

这是高优先级章节。只要用户输入里出现链接、token，或报错涉及 baseToken / wiki_token / obj_token，都应优先回到这里检查。

3.5 身份选择与权限降级策略

多维表格通常属于用户的个人或团队资源。默认应优先使用 `--as user`（用户身份）执行所有 Base 操作，始终显式指定身份。

• `--as user`（推荐）：以当前登录用户身份操作其有权访问的 Base。执行前先完成用户授权：

lark-cli auth login --domain base

• `--as bot`（降级）：仅当 user 身份权限不足、且 bot 身份确实拥有目标 Base 的访问权限时，才降级使用。bot 看不到用户私有资源，行为以应用身份执行。

执行规则：

1. 所有操作默认先用 --as user。
2. 若 user 身份返回权限错误，先判断是否为不可重试错误码（如 91403）。若是，立即停止，不做任何重试或降级，直接按 lark-shared 权限不足处理流程引导用户解决。
3. 非不可重试错误码时，检查错误响应中是否包含 permission_violations / hint 等提权引导信息：

• 有提权引导：按 lark-shared 权限不足处理流程，先引导用户完成 user 身份提权（auth login --scope）；确认提权成功后，以 --as user 重试。
• 无提权引导（如资源级无访问权限、非 scope 不足）：切换到 --as bot 重试一次。

1. 若 bot 身份仍然返回权限错误，立即停止重试，根据错误响应按 lark-shared 流程引导用户解决（引导去开发者后台开通 scope 或确认资源访问权限）。
2. 只有在用户明确要求"用应用身份 / bot 身份操作"，才跳过 user 直接使用 --as bot。

4. 执行规则

4.1 标准执行顺序

1. 先判断任务属于哪个模块，选对命令族。
2. 如果用户给了链接，先解析 token，不要把 wiki token、完整 URL 或其他对象 ID 误当成 base_token。
3. 先拿结构，再写命令，避免猜表名、字段名、表达式引用。
4. 定位到命令后，先读对应 reference，再执行命令。
5. 执行命令，并按返回结果判断下一步。
6. 回复时返回关键结果和后续可继续操作的信息，方便 agent 链式执行下一步。

4.2 不可违反规则

1. 先拿结构，再写命令；至少先拿当前表结构，跨表时还要拿目标表结构。
2. 不要猜表名、字段名、表达式引用，一律以真实返回为准。
3. 只使用原子命令；不要回退到旧的聚合式 +table / +field / +record / +view / +history / +workspace。
4. 写记录前先读字段结构；先 +field-list，再按 `lark-base-cell-value.md` 构造 CellValue。
5. 写字段前先看字段属性规范；先读 lark-base-shortcut-field-properties.md，再构造 +field-create / +field-update 的 JSON。
6. 只写可写字段；系统字段、附件字段、formula、lookup 默认不作为普通记录写入目标。
7. 聚合分析与取数分流；统计走 +data-query，关键词检索走 +record-search，明细走 +record-list / +record-get。
8. 筛选查询按视图能力执行；先用 +view-set-filter 配置筛选，再结合 +record-list 读取。
9. Base 场景不要改走裸 API，不要切去 lark-cli api /open-apis/bitable/v1/...。
10. 统一使用 --base-token，不使用旧 --app-token。
11. workflow 场景先读 schema，不要凭自然语言猜 type。
12. dashboard 场景先读 guide；提到图表、看板、block 就先进入 dashboard 模块。
13. 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。
• 删除目标仍有歧义时，先用 +record-get / +field-get / +table-get 或相应 list 命令确认。
• +base-create / +base-copy 成功后，回复中必须主动返回新 Base 的标识信息；若结果带可访问链接，也应一并返回。
• 若 Base 由 bot 身份创建或复制，shortcut 会自动尝试为当前 CLI 用户补授 full_access，并在输出中返回 permission_grant；agent 不需要再手动编排单独授权。owner 转移必须单独确认，禁止擅自执行。

5. 常见错误与恢复