lark-base

name	lark-base
description	飞书多维表格（Base）操作：建表、字段、记录、视图、统计、公式/lookup、表单、仪表盘、应用模式（BaseApp/AppMode 页面与组件）、Workspace 目录、workflow、角色权限、模板中心（多维表格模板分类/列表/搜索）；遇到 Base/多维表格/bitable、BaseApp/AppMode、/base/ 或 /app/ 链接时使用。BaseApp 不走 lark-apps；文件导入/导出转 lark-drive，认证/授权由 MCP server 自动处理。

base

何时使用

使用本 skill：

• 用户明确提到 Base / 多维表格 / bitable，或给出 /base/ 链接。
• 用户要在 Base 内建表、改表、管理字段、写记录、查记录、配视图。
• 用户要在 Base 内做公式字段、lookup 字段、跨表计算、派生指标、筛选聚合、TopN、统计分析。
• 用户要管理 Base 表单、仪表盘、workflow、高级权限或角色。
• 用户要用应用模式（BaseApp）：新建应用、管理应用页面、在页面上加图表/列表/富文本组件，或整理 Workspace 目录。
• 用户想"用一个现成模板快速搭一个多维表格"，但没有给出任何已有 Base 的锚点（无 URL、无"我的/最近访问的表"、无具体已存在的 Base 名）：走模板中心。
• 用户明确提到 BaseApp / AppMode / 应用模式 / Workspace 内应用，或给出应用模式的 /app/ 链接（链接可能同时携带 /base/workspace/<workspace_token> 路径信息），并要查询页面或组件；这类应用属于 Base，不走 apps skill。
• 用户要把旧 Base 聚合式命令或旧写法迁移到当前 lark_base_* 工具。

不要使用本 skill：

• 只是认证、初始化配置、切换身份、处理 scope 或权限授权恢复（MCP server 自动处理认证）。
• 把本地文件导入成 Base，或将 Base 导出为本地文件，转 lark_get_skill(domain="drive")。
• 泛化数据分析、字段设计、公式讨论，但没有 Base/多维表格上下文。

使用边界

• BaseApp 复制是明确的停止边界：本期没有 BaseApp 复制工具。识别到复制 / 克隆应用模式的诉求后，直接说明当前工具集无法完成并停止，不要调用 lark_base_base_copy()、lark_base_app_create()、Drive copy 或任何写工具试探、拼装替代方案。
• Base 业务操作只使用 lark_base_* 工具，不使用旧聚合式命令。
• 执行 update 前必须先查当前工具的 schema（lark_discover）或对应 reference。若工具要求完整配置，首次请求必须基于可信的当前配置执行 read-modify-write：只修改用户明确指定的内容，保留其他仍适用的可写配置，并按工具要求的结构提交。若工具支持局部／delta update，按其契约提交最小合法 payload；不得以不完整请求试错补参。
• Base 工具当前不支持视图行高、冻结列、列宽等 UI-only 外观设置。遇到这类需求，说明能力边界并停止，不要猜测未文档化参数或改走 lark_invoke 裸 API。
• 高频：数据分析。 数据表记录用于查询、分析、解析或比较时，先读 lark_get_skill(domain="base", section="record-query-and-analysis-sop")。
• 低频：在线复制。 复制整个 Base 使用 lark_base_base_copy()，复制 Base 内单张数据表使用 lark_base_table_copy()。
• 更低频：文件导入/导出。 本地文件与 Base 之间的导入/导出转 lark_get_skill(domain="drive")；具体格式、参数、路径限制和仅结构导出规则由 drive skill 负责，导入完成后再回到 Base 工具。
• 认证由 MCP server 自动处理；Base 文档只保留会影响 Base 路径选择的权限规则。

应用模式与 Workspace 心智模型

• Workspace 是组织 Base 和 BaseApp 的空间容器；BaseApp 创建时必须归属一个 Workspace，workspace_token 标识这个容器。
• BaseApp（应用模式）不是 Base 的别名。它用 Page 组织界面，每个 Page 再包含图表、列表或富文本 Block；app_token、page_id、block_id 分别标识这三层对象。
• Base 保存表、字段和记录等数据。BaseApp 的组件通过 data_config 引用 Base 中的数据，但引用关系不会把 Base 变成 App 的子对象。
• App 的列表组件最多引用一个 Base，而且该 Base 必须与 App 位于同一 Workspace；App 图表的多个数据源也共用一个 base_token。
• Workspace 负责资源归属，App 负责页面和组件，Base 负责数据。按操作对象选择 lark_base_workspace_*、lark_base_app_* 或 Base 数据工具，不要混用 token。

先获取 Base Token 和所需 ID

进入任何需要目标 Base 的工具前，必须先拿到可用的 base_token，以及当前任务需要的 table_id / view_id / record_id / form_id / dashboard_id / workflow_id 等真实 ID；不要把完整 URL、wiki token、workspace token 或孤立 raw token 直接当作 base_token。

• 用户输入 URL 或分享链接：先调用 lark_base_url_resolve(url="<url>")。Base URL 返回 base_token 和相关 ID；BaseApp /app/ URL 返回 app_token，并在原链接携带时返回 workspace_token 和 page_id。
• 用户要查询既有 BaseApp，但当前输入和当前会话可信工具返回中都没有真实 /app/ 链接或 app_token，也没有可供 lark_base_workspace_entity_list(type="baseapp") 定位的 workspace_token：无需调用任何工具；先明确说明当前任务没有提供应用链接或 Workspace 信息、无法可靠定位目标 BaseApp，再请用户补充并停止。不要在此前后调用 apps skill 的工具、lark_base_title_resolve()、Drive 搜索或其他全局名称发现，不要默认选择同名候选，也不要把 base_token 当作 app_token。
• Base/Wiki URL 的 table= query 参数实际表示当前选中的顶层 block，可能是数据表、仪表盘或 workflow；不要按参数名自行当成 table_id。以 lark_base_url_resolve() 返回的 block_type 以及 table_id / dashboard_id / workflow_id 为准；selection_source=url_query 只说明 URL 当前选中了该 block，不代表它覆盖用户明确点名的目标。若用户点名的 dashboard 与 block_name 不一致，先用 lark_base_dashboard_list() 按名称匹配；若只返回中性 block_id，按 hint 用 lark_base_base_block_list() 确认类型。
• 用户输入 Base 标题、关键词或不确定名称：先调用 lark_base_title_resolve(title="<keyword>")；title 传入标题中的短关键词，不超过 30 个字符；过长标题先取最有区分度的短关键词；多候选时先让用户消歧，不要猜。
• 用户要列出已有 Base 候选，且需要按最近访问、owner、创建人、时间、类型等维度筛选/排序：转 lark_drive_search(doc_types="bitable")。按标题/关键词定位单个 Base 仍用 lark_base_title_resolve()。常见候选列表写法：
  • 最近访问：lark_drive_search(doc_types="bitable", sort="open_time", opened_since="3m", page_size="20")
  • 只列我拥有的：加 mine=true；要列"我创建的"用 created_by_me=true。
  • 从候选项拿到 URL 或 token 后，再用 lark_base_url_resolve() 或 lark_base_base_get() 进入 Base 业务工具。
• 文档嵌入 Base 标签：直接读取 <bitable> / <base_refer> 的 token 作为 base_token，table-id 作为 table_id，view-id 作为 view_id；孤立 raw token 不走 lark_base_url_resolve()。
• 仍无法定位且用户不是要新建 Base 时，先反问用户要操作哪一个 Base；用户要新建时才用 。

Base 模板中心

模板中心是公开的 Base 模板库，不是用户云空间里的已有 Base。用户想用现成模板创建新 Base，且没有指向已有对象的锚点（没有 Base URL、没有"我的/最近访问的表"、没有具体已存在的 Base 名）时，先读 lark_get_skill(domain="base", section="template-center") 查找模板中心模板：lark_base_template_categories() 列出公开模板分类，lark_base_template_list() 按分类列出公开模板，lark_base_template_search() 按业务关键词搜索公开模板。选定模板后用 lark_base_base_copy(base_token="<模板 token>") 复制成用户自己的新 Base。

模板中心是独立的公开数据集，lark_drive_search() 搜不到它；用户要"我的/最近访问/已有 Base"不要走模板中心。

快速路由

用户目标	优先工具	何时读 reference
查 Base 本体	lark_base_base_get()	用返回确认 Base 名称、owner、权限和可继续操作的 token
创建/复制 Base	lark_base_base_create() / lark_base_base_copy()	新建时强烈推荐用 table_name + fields 同时配置新 Base 里唯一一个初始数据表的 name 和 schema；写入后报告新 Base 标识和 permission_grant
Base 文件导入/导出	转 lark_get_skill(domain="drive")	文件格式、参数、路径限制和仅结构导出规则由 drive skill 负责；在线复制走 lark_base_base_copy()
找模板 / 用模板搭新 Base	lark_base_template_categories() / lark_base_template_list() / lark_base_template_search() → lark_base_base_copy()	用户想用现成模板建新 Base 且没有已有 Base 锚点时先读 lark_get_skill(domain="base", section="template-center")；模板 token 是复制入参，lark_drive_search() 搜不到模板中心
列出已有 Base 候选	lark_drive_search(doc_types="bitable")	需要按最近访问、owner、创建人、时间维度筛选/排序时用它；按标题定位单个 Base 仍用 lark_base_title_resolve()
查看 Base 内资源目录	lark_base_base_block_list()	想先了解一个 Base 里有哪些 table/docx/dashboard/workflow/folder 时优先用它；返回 ID 关系和 fewshot 看 lark_discover(query="base.base-block.list")
管理 Base 内资源目录	lark_base_base_block_create/move/rename/delete	创建或整理 Base 直接管理的 folder/table/docx/dashboard/workflow；资源内容继续用对应工具
管理数据表	lark_base_table_list/get/create/update/delete	处理 table 的列出、详情、创建、重命名和删除；lark_base_table_create() 必须传 fields 一次性定义表结构，字段 JSON 读 lark_get_skill(domain="base", section="field-schema")
复制 Base 内单张数据表	lark_base_table_copy() / lark_base_table_copy_status()	在线复制单张数据表；复制范围和异步任务参数查看工具 schema（lark_discover(query="base.table-copy")）
列/查/删字段	lark_base_field_list/get/delete/search_options	写入前用 list/get 确认字段类型、选项、ID；删除前确认目标字段

Base 心智模型

• Base 曾用名 Bitable；返回字段、错误或旧文档里的 bitable 多为历史兼容，不代表应改走裸 API 或另一套命令。
• lark_base_base_block_list() 是查看一个 Base 内资源目录的新入口：它列出这个 Base 直接管理的 folder/table/docx/dashboard/workflow，适合先判断 Base 里有什么，再决定走 table、dashboard、workflow 或 docx 工具。
• lark_base_base_block_* 只负责资源目录管理，包括创建资源、移动到 folder、重命名和删除；具体资源内容仍走 table/dashboard/workflow 工具。
• 新建 Base 时，强烈推荐一次性执行 lark_base_base_create(name="<base>", table_name="<table>", fields='<field-json-array>')，同时配置新 Base 里唯一一个初始数据表的 name 和 schema；使用 fields 前先读 lark_get_skill(domain="base", section="field-schema") 或复用 lark_base_field_create() 的字段 JSON 形状，不要猜字段属性。
• lark_base_base_create() 不传 table_name 和 fields 时，会创建一个默认 schema 的初始数据表。
• lark_base_table_copy() 用于在线复制 Base 内的数据表，table_id 可使用当前 Base 中的表 ID 或表名；复制范围等参数查看工具 schema。
• lark_base_table_copy(wait=true) 会阻塞等待复制任务完成；调用超时或中断后不要重新提交复制，先用返回或上一次结果里的 task_id 执行 lark_base_table_copy_status(task_id="<TASK_ID>") 续查。
• 表、字段、视图、workflow、dashboard block 的名称和 ID 必须来自真实返回，不要凭用户口述猜。
• formula 适合常规计算、条件判断、文本/日期处理和长期派生指标；lookup 适合明确的跨表查找、筛选后取值或聚合引用。
• 写入、公式、lookup、workflow、dashboard 前，先读取真实结构：表、字段、视图、关联表和 dashboard block 名称都以工具返回为准。

身份与权限

MCP server 自动使用用户身份执行所有 Base 操作（authentication is handled automatically by the MCP server）。

如果操作返回权限错误，直接告知用户权限不足，建议用户在飞书开发者后台确认资源访问权限。

写入前置规则

• 优先用写入返回确认结果；返回信息不足或任务明确要求核验时，再读回。
• 严格区分动作语义：用户要求"新增/创建"时，必须用本轮 create 返回的对象、ID 或数量确认完成，不能把已有资源算作本轮新增；目标已存在时按具体工具或 guide 的同名契约处理，不得自行改写用户语义。复合创建任务对每类资源只做一次必要盘点；只有工具明确返回逐项结果时才优先使用批量创建，并继续配置本轮返回的 ID。
• 写记录前先读字段结构；只写存储字段。系统字段、附件字段、formula、lookup 不作为普通记录写入目标。
• 附件上传、下载、删除走专用 lark_base_record_*_attachment 命令。
• 除上述简单 text fast path 外，写字段前先读 lark_get_skill(domain="base", section="field-schema")；请求字段类型不在 reference 已支持类型目录中时，说明当前工具不支持并停止，不要猜测未注册的字段 JSON 或 schema，也不要用其他字段类型冒充；涉及 formula / lookup 时必须读 lark_get_skill(domain="base", section="field-formula") / lark_get_skill(domain="base", section="field-lookup")。
• 表名、字段名、视图名、workflow 配置中的名称必须来自真实返回；跨表场景还要读取目标表结构。
• 删除、角色更新、字段更新、表单提交（lark_base_form_submit()）等高风险操作遵循 confirmation gate（_confirm=true）；目标不明确时先用 get/list 消歧。
• 真正的 batch 写工具遵守各自文档的单批上限；lark_base_field_create() 的字段数组是顺序单项请求，按调用方超时而非固定条数拆分；连续写同一表时串行执行，遇到 1254291 按短暂等待后重试处理。
• select 字段只支持写入字段中已有的选项；构造 CellValue 前先用 lark_base_field_list() 或 lark_base_field_search_options() 确认目标选项存在。

表单与视图细节

• Base 内表单 list/get/create/update/delete 和题目管理都属于具体数据表：第一个管理工具调用前必须已有归属明确的真实 table_id；缺失或归属不明确时才用 lark_base_table_list() 或 lark_base_base_block_list() 定位，已有真实 ID 时直接复用。后续管理调用始终传同一 base_token + table_id。
• 表单问题由数据表字段承载，question id 就是 field_id。创建问题前先 lark_base_form_questions_list()；除非用户明确要求同名的独立问题，否则标题已存在时优先用 lark_base_form_questions_update() 修改必填状态、标题或描述，不要先创建同名问题再删除旧问题。
• lark_base_form_questions_create() 支持两种形态：新建字段题目需要 title + type；已有字段题目需要 use_existing_field:true + field_id。已有字段题目只是把该字段加入表单，不创建新字段，也不改变已有记录数据；不要给该形态携带 type、style、options 等字段定义属性。要把表里已有字段加进表单时，先用 lark_base_field_list() 确认真实字段 ID 和类型。
• lark_base_form_questions_delete() 是高风险写操作，默认会删除承载问题的底层字段及该字段所有记录数据；只想把题目移出表单并保留字段/数据时必须传 keep_field=true。保留字段后可用 lark_base_form_questions_create(questions='[{"use_existing_field":true,"field_id":"<field_id>"}]') 加回表单。主字段问题不能删除，用 lark_base_form_questions_update() 修改。
• 表单分享启停、访问范围和匿名/登录要求用 lark_base_form_share_get() / lark_base_form_share_update() 管理；更新前先读现状，每次调用只修改一个字段，布尔值显式传 true 或 false。
• lark_base_form_submit() 是高风险写操作，必须带 _confirm=true 确认；调用前必须先跑 lark_base_form_detail()，读取 questions[].type、required、filter 和附件场景需要的 base_token；不要填写被 filter 隐藏的问题。
• lark_base_form_questions_update() 是题目配置全量覆盖，不是 patch；未传字段会回落默认值，传空字符串 / null / 空数组会直接写入空或清空。更新前先 lark_base_form_questions_list() 读取当前题目，把要保留的 title / description / required / option_display_mode / visible_rule 等字段带回请求。
• 表单附件不要写进 fields，放在 json 的 attachments 中；提交附件时必须同时传表单所属 Base 的 base_token。
• lark_base_view_set_filter() 是唯一保留的 view reference；sort/group/card/timebar/visible-fields 这类配置先用对应 get 命令读现状，保留未修改字段，只替换用户要求变更的配置。

Dashboard / Workflow / Role

• Dashboard 的复杂点是 block 的 data_config，不是 list/get/create/delete 命令参数。创建或更新 block 前先读 lark_get_skill(domain="base", section="dashboard-block-config")，组件必须串行创建；lark_base_dashboard_arrange() 是服务端智能整盘编排，用户没有给出组件级坐标或尺寸时，用它做重排、美化、撑满这类诉求，或对本次会话从零新建的仪表盘做一次收尾整理。lark_base_dashboard_block_get_data() 读取图表最终计算结果，不返回 block 名称、类型、布局或 data_config；需要元数据先用 lark_base_dashboard_block_get()。用户要求"全部/完整"仪表盘内容时不得跳过 text 或不支持直接取数的 block，按 lark_get_skill(domain="base", section="dashboard") 的完整读取分支恢复。
• 组件精确布局用 lark_base_dashboard_block_create() / lark_base_dashboard_block_update() 的可选 position（12 列栅格 {"x","y","w","h"}，四个 key 必须齐全且为数字，整体提交不做逐字段合并）。只有用户明确给出组件级坐标、行列顺序、每个组件宽高或可直接换算的尺寸比例时才用 position；"调整布局""美化""撑满""铺满"本身不算精确约束，这类诉求用一次 lark_base_dashboard_arrange() 整盘编排。坐标取值不做本地校验，越界或重叠会由服务端自动重排，所以调用方应自己规划 12 列内不重叠的坐标。任一组件用了显式 position 时不要再 arrange，除非用户明确同意放弃精确布局。不要改用 lark_invoke 探测裸 API、源码或未公开布局参数。
• statistics 指标卡可在 data_config.number_format 里设 formatName（digital / digital_without_separator / percentage_rounded / cyn_rounded / dollar_rounded，区分大小写）和 precision（0-9 整数）。create 会按组件类型本地校验；update 不接收 type，只校验 number_format 子字段，再由服务端结合现有 block 类型裁决。number_format 是 data_config 顶层 key merge 的例外，按子字段合并。枚举与模板读 lark_get_skill(domain="base", section="dashboard-block-config")。
• 仪表盘分享启停、访问范围、返回源 Base 入口和智能分析用 lark_base_dashboard_share_get() / lark_base_dashboard_share_update() 管理；更新前先读现状，每次调用只修改一个字段，显式 false 会被保留。
• 创建接口成功返回即表示写入成功；只有结果不确定时才额外执行一次 lark_base_dashboard_get() 或 lark_base_dashboard_block_list()。不要仅为确认创建而逐组件调用 lark_base_dashboard_block_get_data()。
• 用户要读取多个组件的计算结果时，先完整列出组件（lark_base_dashboard_block_list(base_token="xxx", dashboard_id="blk_xxx", page_size="100")；若 has_more=true，继续把返回的 page_token 传给 page_token 参数，直到 has_more=false），再按 在同一轮里连续串行调用，逐个读取；不要把每个 block 拆成独立模型轮次。

常见恢复

错误 / 现象	恢复动作
param baseToken is invalid / base_token invalid	检查是否把 wiki token、workspace token 或完整 URL 当成了 base_token；按入口规则重新获取真实 base_token
not found 且输入来自 Wiki 链接	优先检查是否把 wiki token 当成 base token，不要立刻改走裸 API
1254045 字段名不存在	重新 lark_base_field_list()，使用真实字段名或字段 ID；注意空格、大小写和跨表字段
1254015 字段值类型不匹配	先 lark_base_field_list()，再按 lark_get_skill(domain="base", section="cell-value") 构造 CellValue
Invalid discriminator value（字段写入缺 type）	按完整提交规则读取当前字段，只改目标内容后提交；不要只补 type 重试
filter 报 value of type array / Only string values	用 record/view 的 tuple filter_json（非 lark_base_data_query 对象型），value 按字段 type 选标量或数组；见 lark_get_skill(domain="base", section="view-set-filter")
日期 / 人员 / 超链接字段报格式错误	日期用 YYYY-MM-DD HH:mm；人员用 [{ "id": "ou_xxx" }]；超链接用 URL 或 markdown link 字符串
formula / lookup 创建失败	先读 lark_get_skill(domain="base", section="field-formula") / lark_get_skill(domain="base", section="field-lookup")，再按 guide 重建请求
ignored_fields / READONLY	移除只读字段，只写存储字段
1254104	批量超过 200，分批调用
1254291	并发写冲突，串行写入并在批次间短暂等待

保留 Reference

• lark_get_skill(domain="base", section="record-query-and-analysis-sop")：所有数据表记录查询和分析的统一入口；依次选择 jq、Python 或 Cloud
• lark_get_skill(domain="base", section="data-analysis-python-stdlib") / lark_get_skill(domain="base", section="data-analysis-pandas")：统一数据分析 SOP 选定 Python 实现后按需读取的同场景示例
• lark_get_skill(domain="base", section="record-query-and-analysis-cloud-sop")：统一 SOP 判定 jq 与 Python 路径均不适用时的云端查询 SOP
• lark_get_skill(domain="base", section="data-query")：Cloud SOP 选定 lark_base_data_query() 后读取 fewshot 与完整 DSL 协议；其 filters 使用独立对象 DSL
• lark_get_skill(domain="base", section="cell-value")：记录 CellValue 构造
• lark_get_skill(domain="base", section="field-schema")：字段 JSON 构造
• lark_get_skill(domain="base", section="field-formula") / lark_get_skill(domain="base", section="field-lookup")：公式与 lookup 字段
• lark_get_skill(domain="base", section="field-create") / lark_get_skill(domain="base", section="field-update")：字段创建/更新命令级补充
• lark_get_skill(domain="base", section="record-batch-create") / lark_get_skill(domain="base", section="record-batch-update") / lark_get_skill(domain="base", section="record-history-list")：记录写入 JSON 与历史返回解释
• lark_get_skill(domain="base", section="view-set-filter")：视图筛选 JSON
• lark_get_skill(domain="base", section="filter-condition")：视图 filter、记录 filter_json、表单 visible_rule 的 tuple 条件结构公共协议 SSOT
• lark_get_skill(domain="base", section="form-detail") / lark_get_skill(domain="base", section="form-submit") / lark_get_skill(domain="base", section="form-questions-create") / lark_get_skill(domain="base", section="form-questions-update")：表单详情、提交和复杂 JSON
• lark_get_skill(domain="base", section="template-center")：模板中心分类/列表/搜索，以及用模板 token 复制成新 Base
• lark_get_skill(domain="base", section="dashboard") / lark_get_skill(domain="base", section="dashboard-block-config") / lark_get_skill(domain="base", section="dashboard-block-get-data")：仪表盘、组件配置与图表结果协议
• lark_get_skill(domain="base", section="app") / lark_get_skill(domain="base", section="app-block-data-config")：应用模式（Workspace / 应用 / 页面 / 组件）入口与组件配置 SSOT