DropFan ⚙️ Cowork / Claude Desktop 执行环境说明（自动注入）
本技能依赖本地
lark-cli（@larksuite/cli，可用command -v lark-cli定位）及其~/.lark-cli登录态（应用密钥存于 macOS keychain）。在 Cowork 中运行任何
lark-cli命令时，必须在本地 macOS 上执行（使用 Desktop Commander 的start_process/interact_with_process，或其它本地 shell 工具），不要用隔离的 Linux 沙箱mcp__workspace__bash——沙箱里没有 lark-cli、也读不到 keychain。 执行前确保 npm 全局 bin 目录（npm prefix -g输出目录下的bin）在 PATH 中。（在 Claude Code 中可忽略本说明，lark-cli 在本机 shell 直接可用。）
base
何时使用
使用本 skill：
- 用户明确提到 Base / 多维表格 / bitable，或给出
/base/链接。 - 用户要在 Base 内建表、改表、管理字段、写记录、查记录、配视图。
- 用户要在 Base 内做公式字段、lookup 字段、跨表计算、派生指标、筛选聚合、TopN、统计分析。
- 用户要管理 Base 表单、仪表盘、workflow、高级权限或角色。
- 用户要把旧 Base 聚合式命令或旧写法迁移到当前
lark-cli base +...shortcut。
不要使用本 skill：
- 只是认证、初始化配置、切换身份、处理 scope 或权限授权恢复，转
lark-shared。 - 把本地文件导入成 Base，或将 Base 导出为本地文件，转
lark-drive。 - 泛化数据分析、字段设计、公式讨论，但没有 Base/多维表格上下文。
使用边界
- Base 业务操作只使用
lark-cli base +...shortcut，不使用旧聚合式+table / +field / +record / +view / +history / +workspace。 - 执行 update 前必须先查当前 shortcut 的
--help或对应 reference。若命令要求完整配置，首次请求必须基于可信的当前配置执行 read-modify-write：只修改用户明确指定的内容，保留其他仍适用的可写配置，并按命令要求的结构提交。若命令支持局部／delta update，按其契约提交最小合法 payload；不得以不完整请求试错补参。 - Base CLI/OpenAPI 当前不支持视图行高、冻结列、列宽等 UI-only 外观设置。遇到这类需求，说明能力边界并停止，不要猜测未文档化参数或改走 raw API。
- 本地文件与 Base 之间的导入/导出转
lark-drive，具体格式、参数、路径限制和仅结构导出规则由lark-drive负责；导入完成后再回到 Base 命令。 - 在线复制 Base 使用
+base-copy，不要绕行导出/导入。 - 认证、初始化、scope、身份切换、权限不足恢复属于
lark-shared；Base 文档只保留会影响 Base 路径选择的权限规则。
先获取 Base Token 和所需 ID
进入任何需要目标 Base 的 shortcut 前，必须先拿到可用的 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-cli base +url-resolve --url "<url>" --as user，用返回的base_token和相关 ID 继续后续命令。 - Base/Wiki URL 的
table=query 参数实际表示当前选中的顶层 block，可能是数据表、仪表盘或 workflow；不要按参数名自行当成table_id。以+url-resolve返回的block_type以及table_id/dashboard_id/workflow_id为准；selection_source=url_query只说明 URL 当前选中了该 block，不代表它覆盖用户明确点名的目标。若用户点名的 dashboard 与block_name不一致，先用+dashboard-list按名称匹配；若只返回中性block_id，按 hint 用+base-block-list确认类型。 - 用户输入 Base 标题、关键词或不确定名称：先运行
lark-cli base +title-resolve --title "<keyword>" --as user；--title传入标题中的短关键词，不超过 30 个字符；过长标题先取最有区分度的短关键词；多候选时先让用户消歧，不要猜。 - 文档嵌入 Base 标签：直接读取
<bitable>/<base_refer>的token作为--base-token，table-id作为--table-id，view-id作为--view-id；孤立 raw token 不走+url-resolve。 - 仍无法定位且用户不是要新建 Base 时，先反问用户要操作哪一个 Base；用户要新建时才用
+base-create。
快速路由
| 用户目标 | 优先命令 | 何时读 reference |
|---|---|---|
| 查 Base 本体 | +base-get |
用返回确认 Base 名称、owner、权限和可继续操作的 token |
| 创建/复制 Base | +base-create / +base-copy |
新建时强烈推荐用 --table-name + --fields 同时配置新 Base 里唯一一个初始数据表的 name 和 schema；写入后报告新 Base 标识和 permission_grant |
| Base 文件导入/导出 | 转 lark-drive |
文件格式、参数、路径限制和仅结构导出规则由 lark-drive 负责；在线复制走 +base-copy |
| 查看 Base 内资源目录 | +base-block-list |
想先了解一个 Base 里有哪些 table/docx/dashboard/workflow/folder 时优先用它；返回 ID 关系和 fewshot 看 --help |
| 管理 Base 内资源目录 | +base-block-create/move/rename/delete |
创建或整理 Base 直接管理的 folder/table/docx/dashboard/workflow；资源内容继续用对应命令 |
| 管理数据表 | +table-list/get/create/update/delete |
处理 table 的列出、详情、创建、重命名和删除 |
| 复制 Base 内单张数据表 | +table-copy / +table-copy-status |
默认只复制结构；只有用户明确要求复制全表、数据、行或记录时才传 --range all；异步任务按返回的 task_id 查询或续等 |
| 列/查/删字段 | +field-list/get/delete/search-options |
写入前用 list/get 确认字段类型、选项、ID；删除前确认目标字段 |
| 创建/更新字段 | +field-create / +field-update |
必读 lark-base-field-json.md；公式读 formula-field-guide.md；lookup 读 lookup-field-guide.md；命令细节读 lark-base-field-create.md / lark-base-field-update.md |
| 读记录明细 | +record-get / +record-list / +record-search |
涉及筛选、排序、Top/Bottom N、聚合、多表关联、全局结论时读 lark-base-data-analysis-sop.md |
| 写记录 | +record-upsert / +record-batch-create / +record-batch-update |
必读 lark-base-record-upsert.md / lark-base-record-batch-create.md / lark-base-record-batch-update.md 和 lark-base-cell-value.md |
| 附件字段 | +record-upload-attachment / +record-download-attachment / +record-remove-attachment |
附件不要伪造成普通 CellValue；上传走本地文件，下载/删除按 file token 或字段定位 |
| 删除记录 / 分享记录链接 / 历史 | +record-delete / +record-share-link-create / +record-history-list |
删除前确认 record；分享链接最多 100 条；历史读 lark-base-record-history-list.md，只查单条记录，不做整表审计 |
| 管理视图 | +view-* |
+view-set-filter 读 lark-base-view-set-filter.md（filter 条件结构见公共协议 lark-base-filter-condition.md）；其余配置先 get 现状，再按返回结构更新 |
| 一次性聚合统计 | +data-query |
必读 lark-base-data-analysis-sop.md 和入口 lark-base-data-query-guide.md；完整 DSL 再读 lark-base-data-query.md |
| 公式字段 | +field-create/update --json '{"type":"formula",...}' |
必读 formula-field-guide.md，读后再加隐藏确认 flag --i-have-read-guide |
| Lookup 字段 | +field-create/update --json '{"type":"lookup",...}' |
必读 lookup-field-guide.md，读后再加隐藏确认 flag --i-have-read-guide |
| 表单提交 | +form-submit |
先读 lark-base-form-detail.md 获取题目、filter 和附件所需 base_token；提交 JSON 读 lark-base-form-submit.md |
| 表单题目创建/更新 | +form-questions-create / +form-questions-update |
Base 内表单按 table 管理；先确定并复用真实 table_id。读 lark-base-form-questions-create.md / lark-base-form-questions-update.md；题目显隐条件 visible_rule 结构见公共协议 lark-base-filter-condition.md |
| Base 内表单管理 | +form-list/get/create/update/delete / +form-questions-list/delete |
缺少或不确定归属时，先用 +table-list 或 +base-block-list 取得真实 table_id；这些命令使用 --base-token + --table-id 并在整个工作流中复用同一 table_id，删除前确认目标表单 |
| 分享表单详情 | +form-detail --share-token <share_token> |
只接受表单分享链接里的 share_token，不要传 --base-token / --form-id；提交前读 lark-base-form-detail.md |
| 仪表盘与组件 | +dashboard-* / +dashboard-block-* |
提到图表/看板/block 时先读 lark-base-dashboard.md；组件 data_config 读 dashboard-block-data-config.md；读取一个或多个图表计算结果用 +dashboard-block-get-data |
| Workflow | +workflow-* |
创建/更新或理解 steps 时读入口 lark-base-workflow-guide.md 和 steps JSON SSOT lark-base-workflow-schema.md；list/get/enable/disable 只处理 workflow ID 与启停状态 |
| 高级权限与角色 | +advperm-* / +role-* |
角色操作先读入口 lark-base-role-guide.md；角色 create/update 或解读完整配置再读权限 JSON SSOT role-config.md；系统角色不可删除；关闭高级权限会影响自定义角色 |
Base 心智模型
- Base 曾用名 Bitable；返回字段、错误或旧文档里的
bitable多为历史兼容，不代表应改走裸 API 或另一套命令。 +base-block-list是查看一个 Base 内资源目录的新入口：它列出这个 Base 直接管理的folder/table/docx/dashboard/workflow，适合先判断 Base 里有什么，再决定走 table、dashboard、workflow 或 docx 命令。base-block只负责资源目录管理，包括创建资源、移动到 folder、重命名和删除；具体资源内容仍走 table/dashboard/workflow 命令。- 新建 Base 时，强烈推荐一次性执行
lark-cli base +base-create --name "<base>" --table-name "<table>" --fields '<field-json-array>'，同时配置新 Base 里唯一一个初始数据表的 name 和 schema；使用--fields前先读 lark-base-field-json.md 或复用+field-create的字段 JSON 形状，不要猜字段属性。 +base-create不传--table-name和--fields时，会创建一个默认 schema 的初始数据表。+table-copy的安全默认值是只复制表结构；用户没有明确要求记录时省略--range，明确要求包含记录时才传--range all。--table-id可直接使用当前 Base 中的表 ID 或表名。- 表、字段、视图、workflow、dashboard block 的名称和 ID 必须来自真实返回，不要凭用户口述猜。
- 存储字段可写；系统字段、
formula、lookup只读；附件字段走专用 attachment 命令。 - 一次性原始记录查询优先用
+record-list/+record-search的 filter/sort；聚合分析优先用+data-query；需要长期显示在表中时，才新增formula/lookup字段。 formula适合常规计算、条件判断、文本/日期处理和长期派生指标；lookup适合明确的跨表查找、筛选后取值或聚合引用。- 写入、分析、公式、lookup、workflow、dashboard 前，先读取真实结构：表、字段、视图、关联表和 dashboard block 名称都以命令返回为准。
- 跨表场景必须读取目标表结构；link 单元格中的关联
record_id只是连接键，最终回答要回查并展示用户可读字段。
身份与权限降级
- 默认显式使用
--as user操作用户资源；只有用户明确要求应用身份时，才直接用--as bot。 +table-copy --wait提交成功后会在 stderr 打印完整task_id；若进程被 Ctrl-C 终止，可用该 ID 和原身份执行+table-copy-status续查，不要重新提交复制。- user 身份报 scope/授权不足，或错误中包含
missing_scopes/hint，先转lark-shared做用户授权恢复，不要直接降级 bot。 - user 身份报资源级无访问且无授权恢复提示时，才可用
--as bot重试一次；bot 仍失败就停止重试并按权限错误处理。 91403或明确不可访问错误不要循环换身份重试。+base-create/+base-copy若用 bot 身份执行，关注返回中的permission_grant，并把用户是否可打开新 Base 告知用户。
查询与统计规则
涉及查询、统计或判断结论时，先阅读 lark-base-data-analysis-sop.md，并遵守：
+record-list的默认页、固定--limit和本地jq只能证明已读取范围内的事实，不能直接支撑全局最值、全量计数、Top/Bottom N、异常识别或分组结论。- 能由 Base 表达的筛选、排序、投影、聚合、分组和限制，应在 Base 云端查询能力中执行；不要先拉原始记录到本地上下文再手工筛选排序。
has_more=true或等价分页信号表示当前结果不是全量；除非用户只要样例/前 N 条，不能基于该页回答全局问题。- 多表查询必须先确认关系字段和连接键；link 单元格里的
record_id是关系键，不是用户可读答案。 - 最终答案必须能追溯到真实表、真实字段、查询范围、筛选/排序/聚合条件和必要的连接键。
- 一次性原始记录查询优先用
+record-list/+record-search的 filter/sort；聚合分析优先用+data-query；要把结果长期显示在表里，才考虑新增formula/lookup字段。 +data-query可返回聚合结果或维度字段行，但维度行按字段组合去重且不返回record_id；需要逐条记录、记录定位或完整行级字段时，再用+record-list/+record-search/+record-get回查。
写入前置规则
- 优先用写入返回确认结果；返回信息不足或任务明确要求核验时，再读回。
- 写记录前先读字段结构；只写存储字段。系统字段、附件字段、
formula、lookup不作为普通记录写入目标。 - 附件上传、下载、删除走专用
+record-*-attachment命令。 - 写字段前先读 lark-base-field-json.md；请求字段类型不在 reference 已支持类型目录中时，说明当前 CLI 不支持并停止，不要猜测未注册的字段 JSON、service 或 schema，也不要用其他字段类型冒充；涉及
formula/lookup时必须读 formula-field-guide.md / lookup-field-guide.md。 - 表名、字段名、视图名、workflow 配置中的名称必须来自真实返回；跨表场景还要读取目标表结构。
- 删除、角色更新、字段更新、表单提交（
+form-submit）等高风险操作遵循 CLI 的 confirmation gate，必须带--yes；目标不明确时先用 get/list 消歧。 - 批量写入单批最多 200 条；连续写同一表时串行执行，遇到
1254291按短暂等待后重试处理。 select字段只支持写入字段中已有的选项；构造 CellValue 前先用+field-list或+field-search-options确认目标选项存在。
表单与视图细节
- Base 内表单 list/get/create/update/delete 和题目管理都属于具体数据表：第一个管理命令前必须已有归属明确的真实
table_id；缺失或归属不明确时才用+table-list或+base-block-list定位，已有真实 ID 时直接复用。后续管理命令始终传同一base_token + table_id。+form-detail是分享表单入口，标识域不同，只使用share_token。 - 表单问题由数据表字段承载，question
id就是field_id。创建问题前先+form-questions-list；除非用户明确要求同名的独立问题，否则标题已存在时优先用+form-questions-update修改必填状态、标题或描述，不要先创建同名问题再删除旧问题。 +form-questions-delete会删除承载问题的数据表字段。主字段问题不可删除；不要把主字段 ID 放入--question-ids，需要修改时使用+form-questions-update。+form-submit是高风险写操作，必须带--yes确认；调用前必须先跑+form-detail，读取questions[].type、required、filter和附件场景需要的base_token；不要填写被 filter 隐藏的问题。+form-questions-update是题目配置全量覆盖，不是 patch；未传字段会回落默认值，传空字符串 /null/ 空数组会直接写入空或清空。更新前先+form-questions-list读取当前题目，把要保留的title/description/required/option_display_mode/visible_rule等字段带回请求。- 表单附件不要写进
fields，放在--json.attachments；提交附件时必须同时传表单所属 Base 的--base-token。 +view-set-filter是唯一保留的 view reference；sort/group/card/timebar/visible-fields 这类配置先用对应 get 命令读现状，保留未修改字段，只替换用户要求变更的配置。- 视图适合持久化、共享和 UI 复用；一次性筛选/排序可先用
+record-list/+record-search的 filter/sort 验证结果，再按需要沉淀为持久视图。
Dashboard / Workflow / Role
- Dashboard 的复杂点是 block 的
data_config，不是 list/get/create/delete 命令参数。创建或更新 block 前先读 dashboard-block-data-config.md，组件必须串行创建；+dashboard-arrange是服务端智能布局，仅在用户明确要求重排/美化、或对本次会话从零新建的仪表盘做收尾整理时执行。+dashboard-block-get-data读取图表最终计算结果，不返回 block 名称、类型、布局或data_config；需要元数据先用+dashboard-block-get。 - Dashboard shortcut 不支持指定组件的
x/y/w/h、精确位置或尺寸，不能把+dashboard-arrange静默当作等价实现。用户只要求一般性重排/美化时可执行一次智能重排；用户要求精确结果时先说明限制并询问是否接受自适应布局，接受后才执行。不要探测 rawlark-cli api、源码或未公开布局参数。 - 创建接口成功返回即表示写入成功；只有结果不确定时才额外执行一次
+dashboard-get或+dashboard-block-list。不要仅为确认创建而逐组件调用+dashboard-block-get-data。 - 用户要读取多个组件的计算结果时，先完整列出组件（
+dashboard-block-list --page-size 100；若has_more=true，继续把返回的page_token传给--page-token，直到has_more=false），再按 lark-base-dashboard-block-get-data.md 在一个 shell 工具调用内串行读取；不要把每个 block 拆成独立模型轮次。 - Workflow 的复杂点是
steps结构。创建、更新或解释完整 workflow 时读入口 lark-base-workflow-guide.md 和 steps JSON SSOT lark-base-workflow-schema.md；enable/disable/list 只需确认 workflow ID、当前启停状态和用户意图。 - Role 的复杂点是权限 JSON。角色操作先读入口 lark-base-role-guide.md；
+role-create只支持自定义角色；+role-update是 delta merge；角色 create/update 或解读完整配置时读权限 JSON SSOT role-config.md。+role-delete只适用于自定义角色，系统角色不可删除；删除角色和关闭高级权限前必须确认目标和影响。
常见恢复
| 错误 / 现象 | 恢复动作 |
|---|---|
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 字段名不存在 |
重新 +field-list，使用真实字段名或字段 ID；注意空格、大小写和跨表字段 |
1254015 字段值类型不匹配 |
先 +field-list，再按 lark-base-cell-value.md 构造 CellValue |
Invalid discriminator value（字段写入缺 type） |
按完整提交规则读取当前字段，只改目标内容后提交；不要只补 type 重试 |
filter 报 value of type array / Only string values |
用 record/view 的 tuple --filter-json（非 +data-query 对象型），value 按字段 type 选标量或数组；见 lark-base-view-set-filter.md |
| 日期 / 人员 / 超链接字段报格式错误 | 日期用 YYYY-MM-DD HH:mm:ss；人员用 [{ "id": "ou_xxx" }]；超链接用 URL 或 markdown link 字符串 |
| formula / lookup 创建失败 | 先读 formula-field-guide.md / lookup-field-guide.md，再按 guide 重建请求 |
ignored_fields / READONLY |
移除只读字段，只写存储字段 |
1254104 |
批量超过 200，分批调用 |
1254291 |
并发写冲突，串行写入并在批次间短暂等待 |
91403 |
无权限访问该 Base，按 lark-shared 权限流程处理，不要盲目重试 |
保留 Reference
- lark-base-data-analysis-sop.md：查询/统计/全局结论的选路 SOP
- lark-base-data-query-guide.md / lark-base-data-query.md：聚合查询入口 fewshot 与 DSL SSOT；
+data-query的filters结构是独立对象 DSL，不使用公共 tuple filter 协议 - lark-base-cell-value.md：记录 CellValue 构造
- lark-base-field-json.md：字段 JSON 构造
- formula-field-guide.md / lookup-field-guide.md：公式与 lookup 字段
- lark-base-field-create.md / lark-base-field-update.md：字段创建/更新命令级补充
- lark-base-record-upsert.md / lark-base-record-batch-create.md / lark-base-record-batch-update.md / lark-base-record-history-list.md：记录写入 JSON 与历史返回解释
- lark-base-view-set-filter.md：视图筛选 JSON
- lark-base-filter-condition.md：视图 filter、记录
--filter-json、表单visible_rule的 tuple 条件结构公共协议 SSOT；不适用于+data-query - lark-base-form-detail.md / lark-base-form-submit.md / lark-base-form-questions-create.md / lark-base-form-questions-update.md：表单详情、提交和复杂 JSON
- lark-base-dashboard.md / dashboard-block-data-config.md / lark-base-dashboard-block-get-data.md：仪表盘、组件配置与图表结果协议
- lark-base-workflow-guide.md / lark-base-workflow-schema.md：workflow 入口与 steps JSON SSOT
- lark-base-role-guide.md / role-config.md：角色入口与权限 JSON SSOT