From 4343c69f2ab3e601f43f457cf67f5c7386264d35 Mon Sep 17 00:00:00 2001 From: "zhouyue.z" Date: Thu, 9 Apr 2026 20:27:55 +0800 Subject: [PATCH 1/5] docs: reorganize lark-base skill guidance --- skills/lark-base/SKILL.md | 608 ++++++++++++++++++++------------------ 1 file changed, 321 insertions(+), 287 deletions(-) diff --git a/skills/lark-base/SKILL.md b/skills/lark-base/SKILL.md index 23f4abc87..a58b43973 100644 --- a/skills/lark-base/SKILL.md +++ b/skills/lark-base/SKILL.md @@ -14,293 +14,327 @@ metadata: > **执行前必做：** 执行任何 `base` 命令前，必须先阅读对应命令的 reference 文档，再调用命令。 > **命名约定：** 仅使用 `lark-cli base +...` 形式的命令。 -## Agent 快速执行顺序 - -1. **先判断任务类型** - - 临时统计 / 聚合分析 → `+data-query` - - 要把结果长期显示在表里 → formula 字段 - - 用户明确要 lookup，或确实更适合 `from/select/where/aggregate` → lookup 字段 - - 明细读取 / 导出 → `+record-list / +record-get` -2. **先拿结构，再写命令** - - 至少先拿当前表结构：`+field-list` 或 `+table-get` - - 跨表场景必须再查**目标表**的结构 -3. **formula / lookup 有硬门槛** - - 先读对应 guide - - 读完 guide 后，再创建对应字段 -4. **写记录前先判断字段可写性** - - 只写存储字段 - - 系统字段 / formula / lookup 默认只读 - -## Agent 禁止行为 - -- 不要把 `+record-list` 当聚合分析引擎 -- 不要没读 guide 就直接创建 formula / lookup 字段 -- 不要凭自然语言猜表名、字段名、公式表达式里的字段引用 -- 不要把系统字段、formula 字段、lookup 字段当成 `+record-upsert` 的写入目标 -- 不要在 Base 场景改走 `lark-cli api GET /open-apis/bitable/v1/...` -- 不要因为 wiki 解析结果里的 `obj_type=bitable` 就去找 `bitable.*`；在本 CLI 里应继续使用 `lark-cli base +...` - -## Base 基本心智模型 - -1. **Base 字段分三类** - - **存储字段**：真实存用户输入的数据，通常适合 `+record-upsert` 写入，例如文本、数字、日期、单选、多选、人员、关联。**附件字段例外**：对 agent 而言，文件上传必须走 `+record-upload-attachment`。 - - **系统字段**：平台自动维护，只读，典型包括创建时间、最后更新时间、创建人、修改人、自动编号。 - - **计算字段**：通过表达式或跨表规则推导，只读，典型包括 **公式字段（formula）** 和 **查找引用字段（lookup）**。 -2. **写记录前先判断字段类别** — 只有存储字段可直接写；公式 / lookup / 创建时间 / 更新时间 / 创建人 / 修改人 / 自动编号都应视为只读输出字段，不能拿来做 `+record-upsert` 入参。 -3. **Base 不只是存表数据，也能内建计算** — 用户提出“统计、比较、排名、文本拼接、日期差、跨表汇总、状态判断”等需求时，不能默认导出数据后手算；要先判断是否应通过 `+data-query` 或公式字段在 Base 内完成。 - -## 分析路径决策 - -1. **一次性分析 / 临时查询** → 优先 `+data-query` - - 适合：分组统计、SUM / AVG / COUNT / MAX / MIN、条件筛选后聚合。 - - 特征：要的是“这次算出来的结果”，不是把结果沉淀成表内字段。 -2. **长期复用的派生指标 / 行级计算结果** → 优先公式字段 - - 适合：利润率、是否延期、剩余天数、分档标签、跨表汇总后的派生结果。 - - 特征：要把结果长期显示在 Base 里，跟随记录自动更新。 -3. **显式要求 Lookup，或确实要按 source/select/where/aggregate 建模** → 用 lookup 字段 - - 默认仍优先考虑 formula。lookup 只在用户明确要求、或更符合固定查找配置时使用。 -4. **原始记录读取 / 明细导出** → `+record-list / +record-get` - - 不要把 `+record-list` 当分析引擎；它负责取明细，不负责聚合计算。 - -## 公式 / Lookup 专项规则 - -1. **涉及 formula / lookup 时，先读 guide，再出命令** - - formula：[`formula-field-guide.md`](references/formula-field-guide.md) - - lookup：[`lookup-field-guide.md`](references/lookup-field-guide.md) -2. **guide 先于创建命令** - - 没读对应 guide 前，不要直接创建 formula / lookup 字段 - - 读完 guide 后，再补齐对应 JSON 并创建字段 - - `type=formula` 必须提供 `expression` - - `type=lookup` 必须提供 `from / select / where`，必要时补 `aggregate` -3. **公式字段优先于 lookup 字段** - - 只要用户的诉求是“计算 / 条件判断 / 文本处理 / 日期差 / 跨表聚合 / 跨表筛选后取值”，默认优先尝试 formula。 - - 只有用户明确说要 lookup，或配置天然更适合 lookup 四元组时，再走 lookup。 -4. **表名 / 字段名必须精确匹配** - - 公式、lookup、data-query 中出现的表名 / 字段名，必须来自 `+table-list` / `+table-get` / `+field-list` 的真实返回，禁止凭语义猜测改写。 -5. **先拿结构再写表达式** - - 公式或 lookup 一律先获取相关表结构，再生成表达式 / 配置；不要直接凭用户口述拼字段名。 - -## Workflow 专项规则 - -1. **执行任何 workflow 命令前，必须先读两份文档：对应的命令文档 + [lark-base-workflow-schema.md](references/lark-base-workflow-schema.md)** - - `+workflow-create` → 先读 [lark-base-workflow-create.md](references/lark-base-workflow-create.md) + schema - - `+workflow-update` → 先读 [lark-base-workflow-update.md](references/lark-base-workflow-update.md) + schema - - `+workflow-list` → 先读 [lark-base-workflow-list.md](references/lark-base-workflow-list.md) + schema - - `+workflow-get` → 先读 [lark-base-workflow-get.md](references/lark-base-workflow-get.md) + schema - - `+workflow-enable` → 先读 [lark-base-workflow-enable.md](references/lark-base-workflow-enable.md) + schema - - `+workflow-disable` → 先读 [lark-base-workflow-disable.md](references/lark-base-workflow-disable.md) + schema - - schema 中定义了所有 StepType 枚举、步骤结构、Trigger/Action/Branch/Loop 的 data 格式、值引用语法等 - - 禁止凭自然语言猜测 `type` 值（如把"新增记录"猜成 `CreateTrigger`），必须从 schema 的 StepType 枚举中复制准确的类型名称 - -2. **创建前确认依赖信息** - - 先通过 `+table-list` / `+field-list` 获取真实的表名、字段名 - - 禁止凭自然语言猜测表名/字段名填入 workflow 配置 - -## Dashboard（仪表盘/数据看板）模块 -**当用户提到 "仪表盘、dashboard、数据看板、图表、可视化、block、组件、添加组件、创建图表" 等仪表盘相关的关键词时，必须阅读** [lark-base-dashboard.md](references/lark-base-dashboard.md) 这个指引文档，了解仪表盘模块的命令和能力后再进行后续操作。 - -## 核心规则 - -1. **只使用原子命令** — 使用 `+table-list / +table-get / +field-create / +record-upsert / +view-set-filter / +record-history-list / +base-get` 这类一命令一动作的写法，不使用旧聚合式 `+table / +field / +record / +view / +history / +workspace` -2. **写记录前先读字段结构** — 先调用 `+field-list` 获取字段结构，再读 [lark-base-shortcut-record-value.md](references/lark-base-shortcut-record-value.md) 确认各字段类型的写入值格式 -3. **写字段前先看字段属性规范** — 先读 [lark-base-shortcut-field-properties.md](references/lark-base-shortcut-field-properties.md) 确认 `+field-create/+field-update` 的 JSON 结构 -4. **筛选查询按视图能力执行** — 先读 [lark-base-view-set-filter.md](references/lark-base-view-set-filter.md) 和 [lark-base-record-list.md](references/lark-base-record-list.md)，通过 `+view-set-filter` + `+record-list` 组合完成筛选读取 -5. **对记录进行分析（涉及"最高/最低/总计/平均/排名/比较/数量"等分析意图）** — 先读 [lark-base-data-query.md](references/lark-base-data-query.md)，通过 `+data-query` 进行数据筛选聚合的服务端计算 -6. **聚合分析与取数互斥** — 需要分组统计 / SUM / MAX / AVG / COUNT 时，必须使用 `+data-query`（服务端计算），禁止用 `+record-list` 拉全量记录再手动计算；反之，`+data-query` 不返回原始记录，取数场景仍走 `+record-list / +record-get` -7. **所有 `+xxx-list` 禁止并发调用** — `+table-list / +field-list / +record-list / +view-list / +record-history-list / +role-list` 只能串行执行 -8. **批量上限 500 条/次** — 同一表建议串行写入，并在批次间延迟 0.5–1 秒 -9. **统一参数名** — 一律使用 `--base-token`，不使用旧 `--app-token` -10. **遇到“公式 / 查找引用 / 派生指标 / 跨表计算”需求，优先走字段方案判断** — 先判断应建 formula / lookup 字段，还是只做一次性 `+data-query` -11. **公式、lookup、系统字段默认视为只读** — 除 `+field-create / +field-update` 维护字段定义外，不要把这些字段作为记录写入目标 -12. **改名和删除按明确意图执行** — `+view-rename` 在目标视图和新名称都明确时可直接执行；`+record-delete / +field-delete / +table-delete` 在用户已经明确要求删除且目标明确时也可直接执行，不需要再补一次确认，并且执行删除命令时要主动补上 `--yes`；只有目标不明确时才继续追问 - -## 问卷 / 表单提示 - -- **获取问卷列表**：使用 `+form-list`（先拿 `form-id`） -- **获取单个问卷**：使用 `+form-get` -- **获取表单 / 问卷问题**：使用 `+form-questions-list` -- **删除问卷 / 表单问题**：使用 `+form-questions-delete` -- **创建 / 更新问题**：使用 `+form-questions-create / +form-questions-update` - -## 意图 → 命令索引 - -| 意图 | 推荐命令 | 备注 | -|------|---------|------| -| 列表 / 获取数据表 | `lark-cli base +table-list` / `+table-get` | 原子命令 | -| 创建 / 更新 / 删除数据表 | `lark-cli base +table-create` / `+table-update` / `+table-delete` | 一命令一动作 | -| 列表 / 获取字段 | `lark-cli base +field-list` / `+field-get` | 原子命令 | -| 创建 / 更新字段 | `lark-cli base +field-create` / `+field-update` | 使用 `--json` | -| 创建 / 更新公式字段 | `lark-cli base +field-create` / `+field-update` | `type=formula`；先读 formula guide，再创建 / 更新 | -| 创建 / 更新 lookup 字段 | `lark-cli base +field-create` / `+field-update` | `type=lookup`；先读 lookup guide，再创建 / 更新，默认先判断 formula 是否更合适 | -| 列表 / 获取记录 | `lark-cli base +record-list` / `+record-get` | 原子命令，如果需要`聚合计算`，`分组统计` 推荐走 `+data-query` | -| 创建 / 更新记录 | `lark-cli base +record-upsert` | `--table-id [--record-id] --json` | -| 聚合分析 / 比较排序 / 求最值 / 筛选统计 | `lark-cli base +data-query` | 不要用 `+record-list` 拉全量数据再手动计算，需使用 `+data-query` 走服务端计算 | -| 配置 / 查询视图 | `lark-cli base +view-*` | `list/get/create/delete/get-*/set-*/rename` | -| 查看记录历史 | `lark-cli base +record-history-list` | 按表和记录查询变更历史 | -| 按视图筛选查询 | `lark-cli base +view-set-filter` + `lark-cli base +record-list` | 组合调用 | -| 创建 / 获取 / 复制 Base | `lark-cli base +base-create` / `+base-get` / `+base-copy` | 原子命令 | -| 列表 / 获取工作流 | `lark-cli base +workflow-list` / `+workflow-get` | 原子命令 | -| 创建 / 更新工作流 | `lark-cli base +workflow-create` / `+workflow-update` | 使用 `--json`，必须阅读 schema | -| 启用 / 停用工作流 | `lark-cli base +workflow-enable` / `+workflow-disable` | 一命令一动作 | -| 启用 / 停用高级权限 | `lark-cli base +advperm-enable` / `+advperm-disable` | 启用后才能使用自定义角色；停用会使已有角色失效 | -| 列表 / 获取角色 | `lark-cli base +role-list / +role-get` | 查看角色摘要或完整配置 | -| 创建 / 更新 / 删除角色 | `lark-cli base +role-create / +role-update / +role-delete` | 管理自定义角色权限 | -| 列表 / 获取表单 | `lark-cli base +form-list` / `+form-get` | 原子命令 | -| 创建 / 更新 / 删除表单 | `lark-cli base +form-create` / `+form-update` / `+form-delete` | 一命令一动作 | -| 列表 / 创建 / 更新 / 删除表单问题 | `lark-cli base +form-questions-list` / `+form-questions-create` / `+form-questions-update` / `+form-questions-delete` | 一命令一动作 | -| 创建/管理仪表盘及图表 | `+dashboard-* / +dashboard-block-*` | **必须先读** [lark-base-dashboard.md](references/lark-base-dashboard.md) | - - -## 操作注意事项 - -- **Base token 口径统一**：统一使用 `--base-token` -- **`+xxx-list` 调用纪律**：`+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`；仅当 `has_more=true` 且用户明确需要更多数据（如“全部导出/全量明细/继续下一页”）时再继续翻页。用户只要样例或前 N 条时，不要继续拉全量 -- **字段可写性先判断**：存储字段才可写；公式 / lookup / 系统字段默认只读，写记录时应跳过 -- **公式能力要主动想到**：用户说“算一下”“生成标签”“判断是否异常”“跨表汇总”“按日期差预警”时，要先判断是否应该建公式字段，而不是只返回手工分析方案 -- **lookup 不是默认首选**：lookup 只在用户明确要求或确实更适合固定查找模型时使用；常规计算、跨表聚合和条件判断优先 formula -- **附件字段**：如果用户要“上传附件 / 给记录加文件”，只能走 `+record-upload-attachment` 这条链路（读字段 → 读记录 → 上传素材 → 回写记录） -- **人员字段 / 用户字段**：调试时注意 `user_id_type` 与执行身份（user / bot）差异 -- **history 使用方式**：`+record-history-list` 按 `table-id + record-id` 查询记录历史，不支持整表历史扫描 -- **workspace 状态**：已接入 `+base-create / +base-get / +base-copy` -- **`+base-create / +base-copy` 结果返回规范**：创建或复制成功后，回复中必须主动返回新 Base 的标识信息。若返回结果里带可访问链接（如 `base.url`），要一并返回 -- **`+base-create / +base-copy` 友好性规则**：`--folder-token`、`--time-zone`、复制时的 `--name` 都是可选项。用户没有特别要求时，不要为了这些可选参数额外打断；能直接创建/复制就直接执行 -- **`+base-create / +base-copy` 权限处理（bot 创建）**：若 Base 由应用身份（bot）创建，创建或复制成功后默认继续使用 bot 身份为当前可用 user（指当前 CLI 中 auth 模块已登录且可用的用户身份）添加 `full_access`（管理员）权限，并在回复中明确授权结果（成功 / 无可用 user / 授权失败及原因）。若授权未完成，要继续给出后续引导（稍后重试授权或继续用 bot）；owner 转移必须单独确认，禁止擅自执行 -- **advperm 使用方式**：`+advperm-enable` 启用高级权限后才能管理角色（`+role-*`）；`+advperm-disable` 是高风险操作，停用后已有自定义角色全部失效；操作用户必须为 Base 管理员；先读 [lark-base-advperm-enable.md](references/lark-base-advperm-enable.md) / [lark-base-advperm-disable.md](references/lark-base-advperm-disable.md) -- **role 使用方式**：`+role-create` 仅支持 `custom_role`；`+role-update` 采用 Delta Merge（`role_name` 和 `role_type` 必须始终提供）；`+role-delete` 不可逆且仅支持自定义角色；角色配置支持 `base_rule_map`（Base 级复制/下载）、`table_rule_map`（表级权限含记录/字段粒度）、`dashboard_rule_map`（仪表盘权限）、`docx_rule_map`（文档权限）；写角色前先读 [role-config.md](references/role-config.md) -- **表单 form-id**：通过 `+form-list` 获取；`+form-create` 返回的 `id` 即 `form-id`，可用于 `+form-questions-*` 操作 -- **workflow 使用方式**：在创建或更新 workflow 前，必须仔细阅读 [lark-base-workflow-schema.md](references/lark-base-workflow-schema.md) 了解各触发器和节点组件的结构；同时 `+workflow-list` 返回的不是完整树状结构，若需读取完整结构请使用 `+workflow-get`。 -- **data-query 使用方式**：使用 `+data-query` 前必须先阅读 [lark-base-data-query.md](references/lark-base-data-query.md) 了解 DSL 结构、支持的字段类型、聚合函数和限制条件；DSL 中的 `field_name` 必须与表字段名精确匹配，构造前先用 `+field-list` 获取真实字段名 -- **公式 / lookup 使用方式**：构造表达式或 where 条件前，至少先拿当前表结构；跨表时要查找目标表的结构，不允许凭自然语言猜字段名 -- **视图重命名确认规则**：用户已经明确“把哪个视图改成什么名字”时，`+view-rename` 直接执行即可，不需要再补一句确认 -- **删除确认规则（记录 / 字段 / 表）**：如果用户已经明确说要删除，并且目标也明确，`+record-delete / +field-delete / +table-delete` 可直接执行，不需要再补一次确认；执行时直接带 `--yes` 通过 CLI 的高风险写入校验。只有目标仍有歧义时，再先用 `+record-get / +field-get / +table-get` 或 list 命令确认 - -## Wiki 链接特殊处理（特别关键！） - -知识库链接（`/wiki/TOKEN`）背后可能是云文档、电子表格、多维表格等不同类型的文档。**不能直接假设 URL 中的 token 就是 file_token**，必须先查询实际类型和真实 token。 - -### 处理流程 - -1. **使用 `wiki.spaces.get_node` 查询节点信息** - ```bash - lark-cli wiki spaces get_node --params '{"token":"<wiki_token>"}' - ``` - -2. **从返回结果中提取关键信息** - - `node.obj_type`：文档类型（docx/doc/sheet/bitable/slides/file/mindnote） - - `node.obj_token`：**真实的文档 token**（用于后续操作） - - `node.title`：文档标题 - -3. **根据 `obj_type` 选择后续命令** - - | obj_type | 说明 | 后续命令 | - |----------|------|-----------| - | `docx` | 新版云文档 | `drive file.comments.*`、`docx.*` | - | `doc` | 旧版云文档 | `drive file.comments.*` | - | `sheet` | 电子表格 | `sheets.*` | - | `bitable` | 多维表格 | `lark-cli base +...`（优先）；如果 shortcut 不覆盖，再用 `lark-cli base `；**不要**改走 `lark-cli api /open-apis/bitable/v1/...` | - | `slides` | 幻灯片 | `drive.*` | - | `file` | 文件 | `drive.*` | - | `mindnote` | 思维导图 | `drive.*` | - -4. **把 wiki 解析出的 `obj_token` 当成 Base token 使用** - - 当 `obj_type=bitable` 时，`node.obj_token` 就是后续 `base` 命令应使用的真实 token。 - - 也就是说：如果原始输入是 `/wiki/...` 链接，不要把 `wiki_token` 直接塞给 `--base-token`。 - -5. **如果已经报了 token 错，再回退检查 wiki** - - 如果命令返回 `param baseToken is invalid`、`base_token invalid`、`not found`，并且用户最初给的是 `/wiki/...` 链接或 `wiki_token`，优先怀疑“把 wiki token 当成了 base token”。 - - 这时不要改走 `bitable/v1` API；应立即重新执行 `lark-cli wiki spaces get_node`，确认 `obj_type=bitable` 后，改用 `node.obj_token` 重新执行 `lark-cli base +...`。 - -### 查询示例 - -```bash -# 查询 wiki 节点 -lark-cli wiki spaces get_node --params '{"token":"Pgrr***************UnRb"}' -``` - -返回结果示例： -```json -{ - "node": { - "obj_type": "docx", - "obj_token": "UAJ***************E9nic", - "title": "ai friendly 测试 - 1 副本", - "node_type": "origin", - "space_id": "6946843325487906839" - } -} -``` - -## Base 链接解析规则 -| 链接类型 | 格式 | 处理方式 | -|---------|------|---------| -| 直接 Base 链接 | `/base/{token}` | 直接提取作为 `--base-token` | -| Wiki 知识库链接 | `/wiki/{token}` | 先调用 `wiki.spaces.get_node`，取 `node.obj_token` | -### URL 参数提取 -``` -https://{domain}/base/{base-token}?table={table-id}&view={view-id} -``` -- `/base/{token}` → `--base-token` -- `?table={id}` → `--table-id` -- `?view={id}` → `--view-id` -### 禁止事项 -- **禁止**将完整 URL 直接作为 `--base-token` 参数传入 -- **禁止**将 wiki_token 直接作为 `--base-token` - -## 常见错误速查 - -| 错误码 | 含义 | 解决方案 | -|--------|------|----------| -| 1254064 | 日期格式错误 | 用毫秒时间戳，非字符串 / 秒级 | -| 1254068 | 超链接格式错误 | 用 `{text, link}` 对象 | -| 1254066 | 人员字段错误 | 用 `[{id:"ou_xxx"}]`，并确认 `user_id_type` | -| 1254045 | 字段名不存在 | 检查字段名（含空格、大小写） | -| 1254015 | 字段值类型不匹配 | 先 `+field-list`，再按类型构造 | +## 1. 何时使用本 Skill + +### 1.1 触发条件 + +| 场景 | 是否应使用本 Skill | 说明 | +|------|-------------------|------| +| 用户明确要操作飞书多维表格 / Base | 是 | 本 skill 的主场景 | +| 用户要建表、改表、查表、删表 | 是 | 进入表与数据模块 | +| 用户要管理字段、记录、视图 | 是 | 进入表与数据模块 | +| 用户要做公式字段、lookup 字段、派生指标、跨表计算 | 是 | 进入公式 / Lookup 模块 | +| 用户要做临时统计、聚合分析、比较排序、求最值 | 是 | 进入数据分析模块 | +| 用户要管理 workflow、dashboard、表单、角色权限 | 是 | 进入对应模块 | +| 用户给出 `/base/{token}` 链接 | 是 | 先解析链接，再进入对应模块 | +| 用户给出 `/wiki/{token}` 链接，且最终解析为 `bitable` | 是 | 先解析 wiki，再继续走 `lark-cli base +...` | +| 用户要把旧的 Base 聚合式写法改成当前原子命令写法 | 是 | 例如把旧 `+table / +field / +record / +view / +history / +workspace` 改写成当前命令 | +| 用户只是做认证、初始化配置、切换 `--as user/bot`、处理 scope | 否 | 先读 `../lark-shared/SKILL.md` | +| 用户只是泛化地讨论“数据分析 / 字段设计”，但并不在 Base 场景中 | 否 | 不要因为提到“统计 / 公式 / lookup”就误触发 | + +### 1.2 前置约束 + +| 项目 | 规则 | +|------|------| +| 共享前置 | 先阅读 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) | +| 命令形态 | 仅使用 `lark-cli base +...` 形式的 shortcut 命令 | +| reference 使用方式 | 定位到命令后，先读该命令对应的 reference，再执行命令 | +| 禁止路线 | 不要在 Base 场景改走 `lark-cli api /open-apis/bitable/v1/...` | + +## 2. 模块与命令导航 + +本章按“先选模块，再选命令”的方式组织。先判断用户目标属于哪个大模块，再进入对应子模块，按要求阅读 reference 后执行命令。 + +### 2.1 模块地图 + +| 大模块 | 处理什么问题 | 包含的小模块 / 能力 | +|------|-------------|-------------------| +| Base 模块 | 管理 Base 本体，或从链接进入 Base 场景 | `base-create / base-get / base-copy`，Base / Wiki 链接解析 | +| 表与数据模块 | 管理 Base 内部结构与日常数据操作 | `table / field / record / view` | +| 公式 / Lookup 模块 | 处理派生字段、条件判断、跨表计算、固定查找引用 | `formula / lookup` 字段创建与更新 | +| 数据分析模块 | 做一次性筛选、分组、聚合分析 | `data-query` | +| Workflow 模块 | 管理自动化流程 | `workflow-list / get / create / update / enable / disable` | +| Dashboard 模块 | 管理仪表盘和图表组件 | `dashboard-* / dashboard-block-*` | +| 表单模块 | 管理表单和表单题目 | `form-* / form-questions-*` | +| 权限与角色模块 | 管理高级权限和自定义角色 | `advperm-* / role-*` | + +### 2.2 Base 模块 + +用于管理 Base 本体，或从用户给出的链接进入后续 Base 操作。 +模块索引：[`references/lark-base-workspace.md`](references/lark-base-workspace.md) + +| 命令 / 输入 | 用途 / 何时使用 | 必读 reference | 路由提醒 | +|-------------|------------------|----------------|----------| +| `+base-create` | 创建新的 Base | [`lark-base-base-create.md`](references/lark-base-base-create.md)、[`lark-base-workspace.md`](references/lark-base-workspace.md) | 写入操作；执行前先读 reference | +| `+base-get` | 获取 Base 信息 | [`lark-base-base-get.md`](references/lark-base-base-get.md)、[`lark-base-workspace.md`](references/lark-base-workspace.md) | 适合确认 Base 本体信息，不替代表/字段结构读取 | +| `+base-copy` | 复制已有 Base | [`lark-base-base-copy.md`](references/lark-base-base-copy.md)、[`lark-base-workspace.md`](references/lark-base-workspace.md) | 写入操作；执行前先读 reference | + +### 2.3 表与数据模块 + +这是最常用的大模块，包含 `table / field / record / view` 四类子模块。 +补充示例：[`references/examples.md`](references/examples.md)，适合需要串联 table / record / view 完整操作链路时再读。 + +#### 2.3.1 Table 子模块 + +子模块索引：[`references/lark-base-table.md`](references/lark-base-table.md) + +| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 | +|------|------------------|----------------|----------| +| `+table-list` | 列出当前 Base 内的数据表 | [`lark-base-table-list.md`](references/lark-base-table-list.md) | `+xxx-list` 只能串行执行 | +| `+table-get` | 获取单个表的详情 | [`lark-base-table-get.md`](references/lark-base-table-get.md) | 适合删除/修改前确认目标 | +| `+table-create` | 创建数据表 | [`lark-base-table-create.md`](references/lark-base-table-create.md) | 一次性建表场景可用 | +| `+table-update` | 更新表信息 | [`lark-base-table-update.md`](references/lark-base-table-update.md) | 修改前先确认目标表 | +| `+table-delete` | 删除数据表 | [`lark-base-table-delete.md`](references/lark-base-table-delete.md) | 用户已明确目标时可直接执行并带 `--yes` | + +#### 2.3.2 Field 子模块 + +普通字段管理走这里；如果字段类型是 `formula` 或 `lookup`，转到下方“公式 / Lookup 模块”。 +子模块索引：[`references/lark-base-field.md`](references/lark-base-field.md) + +| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 | +|------|------------------|----------------|----------| +| `+field-list` | 列出字段结构 | [`lark-base-field-list.md`](references/lark-base-field-list.md) | 写记录、写字段、做分析前常先读它；只能串行执行 | +| `+field-get` | 获取单个字段详情 | [`lark-base-field-get.md`](references/lark-base-field-get.md) | 适合删除/更新前确认目标 | +| `+field-create` | 创建普通字段 | [`lark-base-field-create.md`](references/lark-base-field-create.md)、[`lark-base-shortcut-field-properties.md`](references/lark-base-shortcut-field-properties.md) | 写字段前先看字段属性规范；如果类型是 `formula / lookup`，先转去读对应 guide | +| `+field-update` | 更新普通字段属性 | [`lark-base-field-update.md`](references/lark-base-field-update.md)、[`lark-base-shortcut-field-properties.md`](references/lark-base-shortcut-field-properties.md) | 写字段前先看字段属性规范；如果类型是 `formula / lookup`，先转去读对应 guide | +| `+field-delete` | 删除字段 | [`lark-base-field-delete.md`](references/lark-base-field-delete.md) | 用户已明确目标时可直接执行并带 `--yes` | +| `+field-search-options` | 查询字段可选项 | [`lark-base-field-search-options.md`](references/lark-base-field-search-options.md) | 适合单选/多选等选项型字段 | + +#### 2.3.3 Record 子模块 + +子模块索引：[`references/lark-base-record.md`](references/lark-base-record.md) + +| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 | +|------|------------------|----------------|----------| +| `+record-list` | 读取记录明细、样例、分页导出 | [`lark-base-record-list.md`](references/lark-base-record-list.md) | 不用于聚合分析；`--limit` 最大 `200`；仅在用户明确需要时继续翻页；只能串行执行 | +| `+record-get` | 获取单条记录详情 | [`lark-base-record-get.md`](references/lark-base-record-get.md) | 适合目标记录已明确时使用 | +| `+record-upsert` | 创建或更新记录 | [`lark-base-record-upsert.md`](references/lark-base-record-upsert.md)、[`lark-base-shortcut-record-value.md`](references/lark-base-shortcut-record-value.md) | 写前先 `+field-list`；只写存储字段；附件不要走这里 | +| `+record-upload-attachment` | 给已有记录上传附件 | [`lark-base-record-upload-attachment.md`](references/lark-base-record-upload-attachment.md) | 附件上传专用链路，不要用 `+record-upsert` 伪造附件值 | +| `+record-delete` | 删除记录 | [`lark-base-record-delete.md`](references/lark-base-record-delete.md) | 用户已明确目标时可直接执行并带 `--yes` | +| `+record-history-list` | 查询某条记录的变更历史 | [`lark-base-record-history-list.md`](references/lark-base-record-history-list.md) | 按 `table-id + record-id` 查询，不支持整表历史扫描；只能串行执行 | + +#### 2.3.4 View 子模块 + +子模块索引：[`references/lark-base-view.md`](references/lark-base-view.md) + +| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 | +|------|------------------|----------------|----------| +| `+view-list` | 列出视图 | [`lark-base-view-list.md`](references/lark-base-view-list.md) | 只能串行执行 | +| `+view-get` | 获取视图详情 | [`lark-base-view-get.md`](references/lark-base-view-get.md) | 适合查看已有视图配置 | +| `+view-create` | 创建视图 | [`lark-base-view-create.md`](references/lark-base-view-create.md) | 先确认表和视图类型 | +| `+view-delete` | 删除视图 | [`lark-base-view-delete.md`](references/lark-base-view-delete.md) | 删除前先确认目标 | +| `+view-get-filter` | 读取筛选配置 | [`lark-base-view-get-filter.md`](references/lark-base-view-get-filter.md) | 适合先看配置再修改 | +| `+view-set-filter` | 配置筛选条件 | [`lark-base-view-set-filter.md`](references/lark-base-view-set-filter.md)、[`lark-base-record-list.md`](references/lark-base-record-list.md) | 常与 `+record-list` 组合，用于按视图筛选读取 | +| `+view-get-sort` | 读取排序配置 | [`lark-base-view-get-sort.md`](references/lark-base-view-get-sort.md) | 适合先看配置再修改 | +| `+view-set-sort` | 配置排序 | [`lark-base-view-set-sort.md`](references/lark-base-view-set-sort.md) | 字段名必须来自真实结构 | +| `+view-get-group` | 读取分组配置 | [`lark-base-view-get-group.md`](references/lark-base-view-get-group.md) | 适合先看配置再修改 | +| `+view-set-group` | 配置分组 | [`lark-base-view-set-group.md`](references/lark-base-view-set-group.md) | 字段名必须来自真实结构 | +| `+view-get-card` | 读取卡片视图配置 | [`lark-base-view-get-card.md`](references/lark-base-view-get-card.md) | 适合先看配置再修改 | +| `+view-set-card` | 配置卡片视图 | [`lark-base-view-set-card.md`](references/lark-base-view-set-card.md) | 适合卡片展示场景 | +| `+view-get-timebar` | 读取时间轴配置 | [`lark-base-view-get-timebar.md`](references/lark-base-view-get-timebar.md) | 适合先看配置再修改 | +| `+view-set-timebar` | 配置时间轴视图 | [`lark-base-view-set-timebar.md`](references/lark-base-view-set-timebar.md) | 适合时间线展示场景 | +| `+view-rename` | 重命名视图 | [`lark-base-view-rename.md`](references/lark-base-view-rename.md) | 用户已明确新名字时可直接执行 | + +### 2.4 公式 / Lookup 模块 + +只要用户诉求涉及派生指标、条件判断、文本处理、日期差、跨表计算、跨表筛选后取值，都要先判断是否进入本模块。 + +默认优先考虑 `formula`：适合常规计算、条件判断、文本处理、日期差、跨表聚合，以及需要长期显示在表里的派生结果。 +只有当用户明确要求 `lookup`，或场景天然符合 `from / select / where / aggregate` 这种固定查找建模时，再使用 `lookup`。 + +| 命令 / 能力 | 用途 / 何时使用 | 必读 reference | 路由提醒 | +|-------------|------------------|----------------|----------| +| `+field-create`（`type=formula`） | 创建公式字段 | [`formula-field-guide.md`](references/formula-field-guide.md)、[`lark-base-field-create.md`](references/lark-base-field-create.md)、[`lark-base-shortcut-field-properties.md`](references/lark-base-shortcut-field-properties.md) | 没读 guide 前不要直接创建 | +| `+field-update`（`type=formula`） | 更新公式字段 | [`formula-field-guide.md`](references/formula-field-guide.md)、[`lark-base-field-update.md`](references/lark-base-field-update.md)、[`lark-base-shortcut-field-properties.md`](references/lark-base-shortcut-field-properties.md) | 先拿当前表结构 | +| `+field-create`（`type=lookup`） | 创建 lookup 字段 | [`lookup-field-guide.md`](references/lookup-field-guide.md)、[`lark-base-field-create.md`](references/lark-base-field-create.md)、[`lark-base-shortcut-field-properties.md`](references/lark-base-shortcut-field-properties.md) | 没读 guide 前不要直接创建 | +| `+field-update`（`type=lookup`） | 更新 lookup 字段 | [`lookup-field-guide.md`](references/lookup-field-guide.md)、[`lark-base-field-update.md`](references/lark-base-field-update.md)、[`lark-base-shortcut-field-properties.md`](references/lark-base-shortcut-field-properties.md) | 跨表时还要拿目标表结构 | + +### 2.5 数据分析模块 + +用于一次性分析和临时聚合查询。用户要的是“这次算出来的结果”，而不是把结果沉淀成字段时，优先进入本模块。 + +| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 | +|------|------------------|----------------|----------| +| `+data-query` | 做分组统计、SUM / AVG / COUNT / MAX / MIN、条件筛选后的聚合分析 | [`lark-base-data-query.md`](references/lark-base-data-query.md) | 字段名必须精确匹配真实字段名；不要用 `+record-list` 拉全量再手算；`+data-query` 不返回原始记录 | + +### 2.6 Workflow 模块 + +这是高约束模块。执行任何 workflow 命令前，都必须先读对应命令文档和 schema。 +模块索引：[`references/lark-base-workflow.md`](references/lark-base-workflow.md) + +| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 | +|------|------------------|----------------|----------| +| `+workflow-list` | 列出 workflow | [`lark-base-workflow-list.md`](references/lark-base-workflow-list.md)、[`lark-base-workflow-schema.md`](references/lark-base-workflow-schema.md) | 只返回摘要，不是完整树结构；只能串行执行 | +| `+workflow-get` | 获取完整 workflow 结构 | [`lark-base-workflow-get.md`](references/lark-base-workflow-get.md)、[`lark-base-workflow-schema.md`](references/lark-base-workflow-schema.md) | 需要完整结构时用它，不要只看 `+workflow-list` | +| `+workflow-create` | 创建 workflow | [`lark-base-workflow-create.md`](references/lark-base-workflow-create.md)、[`lark-base-workflow-schema.md`](references/lark-base-workflow-schema.md) | 先读 schema；禁止凭自然语言猜 `type`；先确认真实表名和字段名 | +| `+workflow-update` | 更新 workflow | [`lark-base-workflow-update.md`](references/lark-base-workflow-update.md)、[`lark-base-workflow-schema.md`](references/lark-base-workflow-schema.md) | 先读 schema；禁止凭自然语言猜 `type`；先确认真实表名和字段名 | +| `+workflow-enable` | 启用 workflow | [`lark-base-workflow-enable.md`](references/lark-base-workflow-enable.md)、[`lark-base-workflow-schema.md`](references/lark-base-workflow-schema.md) | 启用前先确认目标 workflow | +| `+workflow-disable` | 停用 workflow | [`lark-base-workflow-disable.md`](references/lark-base-workflow-disable.md)、[`lark-base-workflow-schema.md`](references/lark-base-workflow-schema.md) | 停用前先确认目标 workflow | + +### 2.7 Dashboard 模块 + +当用户提到“仪表盘、dashboard、数据看板、图表、可视化、block、组件、添加组件、创建图表”等关键词时，进入本模块，并先阅读 [`lark-base-dashboard.md`](references/lark-base-dashboard.md)。 + +| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 | +|------|------------------|----------------|----------| +| `+dashboard-list` | 列出仪表盘 | [`lark-base-dashboard-list.md`](references/lark-base-dashboard-list.md)、[`lark-base-dashboard.md`](references/lark-base-dashboard.md) | 进入仪表盘语义后先读 guide；只能串行执行 | +| `+dashboard-get` | 获取仪表盘详情 | [`lark-base-dashboard-get.md`](references/lark-base-dashboard-get.md)、[`lark-base-dashboard.md`](references/lark-base-dashboard.md) | 适合查看已有看板配置 | +| `+dashboard-create` | 创建仪表盘 | [`lark-base-dashboard-create.md`](references/lark-base-dashboard-create.md)、[`lark-base-dashboard.md`](references/lark-base-dashboard.md) | 先明确看板目标和展示场景 | +| `+dashboard-update` | 更新仪表盘 | [`lark-base-dashboard-update.md`](references/lark-base-dashboard-update.md)、[`lark-base-dashboard.md`](references/lark-base-dashboard.md) | 更新前先读取当前配置 | +| `+dashboard-delete` | 删除仪表盘 | [`lark-base-dashboard-delete.md`](references/lark-base-dashboard-delete.md)、[`lark-base-dashboard.md`](references/lark-base-dashboard.md) | 删除前先确认目标 | +| `+dashboard-block-list` | 列出图表组件 | [`lark-base-dashboard-block-list.md`](references/lark-base-dashboard-block-list.md)、[`lark-base-dashboard.md`](references/lark-base-dashboard.md) | 只能串行执行 | +| `+dashboard-block-get` | 获取单个 block 详情 | [`lark-base-dashboard-block-get.md`](references/lark-base-dashboard-block-get.md)、[`lark-base-dashboard.md`](references/lark-base-dashboard.md)、[`dashboard-block-data-config.md`](references/dashboard-block-data-config.md) | 适合查看图表配置细节 | +| `+dashboard-block-create` | 创建图表组件 | [`lark-base-dashboard-block-create.md`](references/lark-base-dashboard-block-create.md)、[`lark-base-dashboard.md`](references/lark-base-dashboard.md)、[`dashboard-block-data-config.md`](references/dashboard-block-data-config.md) | 涉及 `data_config`、图表类型、filter 时要读 block config 文档 | +| `+dashboard-block-update` | 更新图表组件 | [`lark-base-dashboard-block-update.md`](references/lark-base-dashboard-block-update.md)、[`lark-base-dashboard.md`](references/lark-base-dashboard.md)、[`dashboard-block-data-config.md`](references/dashboard-block-data-config.md) | 涉及 `data_config`、图表类型、filter 时要读 block config 文档 | +| `+dashboard-block-delete` | 删除图表组件 | [`lark-base-dashboard-block-delete.md`](references/lark-base-dashboard-block-delete.md)、[`lark-base-dashboard.md`](references/lark-base-dashboard.md) | 删除前先确认目标 | + +### 2.8 表单模块 + +用于管理表单本体和表单题目。 +表单问题相关操作依赖 `form-id`；具体获取方式见 `form-list` 和 `form-create` 的 reference。 + +| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 | +|------|------------------|----------------|----------| +| `+form-list` | 列出表单 | [`lark-base-form-list.md`](references/lark-base-form-list.md) | 可用来获取 `form-id` | +| `+form-get` | 获取单个表单 | [`lark-base-form-get.md`](references/lark-base-form-get.md) | 适合查看已有表单配置 | +| `+form-create` | 创建表单 | [`lark-base-form-create.md`](references/lark-base-form-create.md) | 创建后可继续进入表单问题相关操作 | +| `+form-update` | 更新表单 | [`lark-base-form-update.md`](references/lark-base-form-update.md) | 更新前先确认目标表单 | +| `+form-delete` | 删除表单 | [`lark-base-form-delete.md`](references/lark-base-form-delete.md) | 删除前先确认目标 | +| `+form-questions-list` | 列出表单题目 | [`lark-base-form-questions-list.md`](references/lark-base-form-questions-list.md) | 适合查看已有题目结构 | +| `+form-questions-create` | 创建题目 | [`lark-base-form-questions-create.md`](references/lark-base-form-questions-create.md) | 先确认 `form-id` | +| `+form-questions-update` | 更新题目 | [`lark-base-form-questions-update.md`](references/lark-base-form-questions-update.md) | 先确认 `form-id` 和题目目标 | +| `+form-questions-delete` | 删除题目 | [`lark-base-form-questions-delete.md`](references/lark-base-form-questions-delete.md) | 删除前先确认题目目标 | + +### 2.9 权限与角色模块 + +用于启用高级权限，以及管理 Base 自定义角色。 +涉及 `+advperm-enable / +advperm-disable / +role-*` 时，操作用户必须为 Base 管理员，否则会返回权限错误。 + +| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 | +|------|------------------|----------------|----------| +| `+advperm-enable` | 启用高级权限 | [`lark-base-advperm-enable.md`](references/lark-base-advperm-enable.md) | 管理角色前必须先启用 | +| `+advperm-disable` | 停用高级权限 | [`lark-base-advperm-disable.md`](references/lark-base-advperm-disable.md) | 高风险操作；停用后已有自定义角色全部失效 | +| `+role-list` | 列出角色 | [`lark-base-role-list.md`](references/lark-base-role-list.md)、[`role-config.md`](references/role-config.md) | 只能串行执行 | +| `+role-get` | 获取角色详情 | [`lark-base-role-get.md`](references/lark-base-role-get.md)、[`role-config.md`](references/role-config.md) | 适合查看完整权限配置 | +| `+role-create` | 创建自定义角色 | [`lark-base-role-create.md`](references/lark-base-role-create.md)、[`role-config.md`](references/role-config.md) | 仅支持 `custom_role`；写角色前先读 `role-config.md` | +| `+role-update` | 更新角色 | [`lark-base-role-update.md`](references/lark-base-role-update.md)、[`role-config.md`](references/role-config.md) | 采用 Delta Merge；`role_name` 和 `role_type` 即使不改也必须传当前值 | +| `+role-delete` | 删除角色 | [`lark-base-role-delete.md`](references/lark-base-role-delete.md)、[`role-config.md`](references/role-config.md) | 不可逆，且仅支持自定义角色 | + +## 3. 多维表格通用知识 + +飞书多维表格英文名是 `Base`，曾用名 `Bitable`；因此旧文档、返回字段、参数名或错误信息里出现 `bitable` 多属历史兼容，不代表应改用另一套命令体系。 + +### 3.1 字段分类与可写性 + +| 字段类型 | 含义 | 能否直接作为 `+record-upsert` 写入目标 | 说明 | +|----------|------|----------------------------------------|------| +| 存储字段 | 真实存用户输入的数据 | 可以 | 常见如文本、数字、日期、单选、多选、人员、关联 | +| 附件字段 | 存储文件附件 | 不能直接按普通字段写 | 上传附件必须走 `+record-upload-attachment` | +| 系统字段 | 平台自动维护 | 不可以 | 常见如创建时间、更新时间、创建人、修改人、自动编号 | +| `formula` 字段 | 通过表达式计算 | 不可以 | 只读输出字段 | +| `lookup` 字段 | 通过跨表规则查找引用 | 不可以 | 只读输出字段 | + +### 3.2 任务选路心智模型 + +| 用户诉求 | 优先方案 | 不要误走 | +|---------|----------|----------| +| 一次性分析 / 临时统计 | `+data-query` | 不要用 `+record-list` 拉全量后手算 | +| 要把结果长期显示在表里 | `formula` 字段 | 不要只给一次性手工分析结果 | +| 用户明确要求 lookup，或天然是固定查找配置 | `lookup` 字段 | 不要默认先上 lookup；先判断 formula 是否更合适 | +| 读取原始记录明细 / 导出 | `+record-list / +record-get` | 不要拿 `+data-query` 当取数命令 | +| 上传附件到记录 | `+record-upload-attachment` | 不要用 `+record-upsert` 伪造附件值 | +| 基于视图做筛选读取 | `+view-set-filter` + `+record-list` | 不要跳过视图筛选直接猜条件 | + +### 3.3 表名、字段名与表达式引用 + +| 规则 | 说明 | +|------|------| +| 表名、字段名必须精确匹配真实返回 | 必须来自 `+table-list / +table-get / +field-list` 的结果 | +| 不要凭自然语言猜名称 | 不要自行改写用户口述中的表名、字段名 | +| `formula / lookup / data-query / workflow` 中的名称同样必须精确匹配 | 表达式引用、where 条件、DSL 字段名、workflow 配置都遵守同一规则 | +| 跨表场景必须额外读取目标表结构 | 不能只看当前表 | + +### 3.4 Token 与链接 + +这是高优先级章节。只要用户输入里出现链接、token，或报错涉及 `baseToken` / `wiki_token` / `obj_token`，都应优先回到这里检查。 + +| 输入类型 | 正确处理方式 | 说明 | +|---------|--------------|------| +| 直接 Base 链接 `/base/{token}` | 直接提取 token 作为 `--base-token` | 不要把完整 URL 直接作为 `--base-token` | +| Wiki 链接 `/wiki/{token}` | 先 `wiki.spaces.get_node`，再取 `node.obj_token` | 不要把 `wiki_token` 直接当 `--base-token` | +| URL 中的 `?table={id}` | 先按前缀判断对象类型 | `tbl` 开头表示数据表 ID，可作为 `--table-id`；`blk` 开头表示仪表盘 block ID；`wkf` 开头表示 workflow ID；`ldx` 开头表示内嵌文档 ID，不要一律当成 `--table-id` | +| URL 中的 `?view={id}` | 提取为 `--view-id` | 适合直接定位视图 | + +| `wiki.spaces.get_node` 返回的 `obj_type` | 后续路线 | 说明 | +|----------------------------------------|----------|------| +| `bitable` | 优先走 `lark-cli base +...` | 如果 shortcut 不覆盖，再用 `lark-cli base `；不要改走 `lark-cli api /open-apis/bitable/v1/...` | +| `docx` | 转到文档 / Drive 相关 skill | 不继续使用本 skill 的 Base 命令 | +| `doc` | 转到文档 / Drive 相关 skill | 不继续使用本 skill 的 Base 命令 | +| `sheet` | 转到 Sheets 相关 skill | 不继续使用本 skill 的 Base 命令 | +| `slides` | 转到 Drive 相关 skill | 不继续使用本 skill 的 Base 命令 | +| `file` | 转到 Drive 相关 skill | 不继续使用本 skill 的 Base 命令 | +| `mindnote` | 转到 Drive 相关 skill | 不继续使用本 skill 的 Base 命令 | + +### 3.5 执行身份与人员字段 + +| 场景 | 提醒 | +|------|------| +| 人员字段 / 用户字段 | 注意 `user_id_type` 与执行身份（user / bot）差异 | +| bot 身份 | bot 看不到用户私有资源；行为以应用身份执行 | +| user 身份 | 依赖用户授权和 scope；更适合操作用户资源 | + +## 4. 执行规则 + +### 4.1 标准执行顺序 + +1. 先判断任务属于哪个模块，选对命令族。 +2. 如果用户给了链接，先解析 token，不要把 wiki token、完整 URL 或其他对象 ID 误当成 `base_token`。 +3. 先拿结构，再写命令，避免猜表名、字段名、表达式引用。 +4. 定位到命令后，先读对应 reference，再执行命令。 +5. 执行命令，并按返回结果判断下一步。 +6. 回复时返回关键结果和后续可继续操作的信息，方便 agent 链式执行下一步。 + +### 4.2 不可违反规则 + +1. 仅使用 `lark-cli base +...` shortcut 命令，不使用旧聚合式 `+table / +field / +record / +view / +history / +workspace`。 +2. 先拿结构，再写命令；至少先拿当前表结构，跨表时还要拿目标表结构。 +3. 不要猜表名、字段名、表达式引用，一律以真实返回为准。 +4. 写记录前先读字段结构；先 `+field-list`，再按字段类型构造写入值。 +5. 写字段前先看字段属性规范；先读 `lark-base-shortcut-field-properties.md`，再构造 `+field-create / +field-update` 的 JSON。 +6. 只写可写字段；系统字段、`formula`、`lookup` 默认只读。 +7. 聚合分析与取数分流；统计走 `+data-query`，明细走 `+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`，只有用户明确需要更多数据时再继续翻页。 +- 批量写入时，单批建议不超过 `500` 条。 +- 连续写入同一表时，建议串行写入，批次间延迟 `0.5–1` 秒。 + +### 4.4 确认与回复规则 + +- 视图重命名时，用户已明确“把哪个视图改成什么名字”时，`+view-rename` 直接执行即可。 +- 删除记录 / 字段 / 表时，如果用户已经明确说要删除，且目标明确，`+record-delete / +field-delete / +table-delete` 可直接执行，并带 `--yes`。 +- 删除目标仍有歧义时，先用 `+record-get / +field-get / +table-get` 或相应 list 命令确认。 + +## 5. 常见错误与恢复 + +| 错误 / 现象 | 含义 | 恢复动作 | +|-------------|------|----------| +| `1254064` | 日期格式错误 | 用毫秒时间戳，非字符串 / 秒级 | +| `1254068` | 超链接格式错误 | 用 `{text, link}` 对象 | +| `1254066` | 人员字段错误 | 用 `[{id:"ou_xxx"}]`，并确认 `user_id_type` | +| `1254045` | 字段名不存在 | 检查字段名（含空格、大小写） | +| `1254015` | 字段值类型不匹配 | 先 `+field-list`，再按类型构造 | | `param baseToken is invalid` / `base_token invalid` | 把 wiki token、workspace token 或其他 token 当成了 `base_token` | 如果输入来自 `/wiki/...`，先用 `lark-cli wiki spaces get_node` 取真实 `obj_token`；当 `obj_type=bitable` 时，用 `node.obj_token` 作为 `--base-token` 重试，不要改走 `bitable/v1` | +| `not found` 且用户给的是 wiki 链接 | 常见于把 wiki token 当成 base token | 优先回退检查 wiki 解析，而不是改走 `bitable/v1` | | formula / lookup 创建失败 | 指南未读或结构不合法 | 先读 `formula-field-guide.md` / `lookup-field-guide.md`，再按 guide 重建请求 | | 系统字段 / 公式字段写入失败 | 只读字段被当成可写字段 | 改为写存储字段，计算结果交给 formula / lookup / 系统字段自动产出 | -| 1254104 | 批量超 500 条 | 分批调用 | -| 1254291 | 并发写冲突 | 串行写入 + 批次间延迟 | - -## 参考文档 - -- [lark-base-shortcut-field-properties.md](references/lark-base-shortcut-field-properties.md) — `+field-create/+field-update` JSON 规范（推荐） -- [role-config.md](references/role-config.md) — 角色权限配置详解 -- [lark-base-shortcut-record-value.md](references/lark-base-shortcut-record-value.md) — `+record-upsert` 值格式规范（推荐） -- [formula-field-guide.md](references/formula-field-guide.md) — formula 字段写法、函数约束、CurrentValue 规则、跨表计算模式（强烈推荐） -- [lookup-field-guide.md](references/lookup-field-guide.md) — lookup 字段配置规则、where/aggregate 约束、与 formula 的取舍 -- [lark-base-view-set-filter.md](references/lark-base-view-set-filter.md) — 视图筛选配置 -- [lark-base-record-list.md](references/lark-base-record-list.md) — 记录列表读取与分页 -- [lark-base-advperm-enable.md](references/lark-base-advperm-enable.md) — `+advperm-enable` 启用高级权限 -- [lark-base-advperm-disable.md](references/lark-base-advperm-disable.md) — `+advperm-disable` 停用高级权限 -- [lark-base-role-list.md](references/lark-base-role-list.md) — `+role-list` 列出角色 -- [lark-base-role-get.md](references/lark-base-role-get.md) — `+role-get` 获取角色详情 -- [lark-base-role-create.md](references/lark-base-role-create.md) — `+role-create` 创建角色 -- [lark-base-role-update.md](references/lark-base-role-update.md) — `+role-update` 更新角色 -- [lark-base-role-delete.md](references/lark-base-role-delete.md) — `+role-delete` 删除角色 -- [lark-base-dashboard.md](references/lark-base-dashboard.md) — dashboard 模块工作流指引 -- [dashboard-block-data-config.md](references/dashboard-block-data-config.md) — Block data_config 结构、图表类型、filter 规则 -- [lark-base-workflow.md](references/lark-base-workflow.md) — workflow 命令索引 -- [lark-base-workflow-schema.md](references/lark-base-workflow-schema.md) — `+workflow-create/+workflow-update` JSON body 数据结构详解，包含触发器及各类节点的配置规则（强烈推荐） -- [lark-base-data-query.md](references/lark-base-data-query.md) — `+data-query` 聚合分析（DSL 结构、支持字段类型、聚合函数） -- [examples.md](references/examples.md) — 完整操作示例（建表、导入、筛选、更新） - -## 命令分组 - -> **执行前必做：** 从下表定位到命令后，务必先阅读对应命令的 reference 文档，再调用命令。 - -| 命令分组 | 说明 | -|----------|------| -| [`table commands`](references/lark-base-table.md) | `+table-list / +table-get / +table-create / +table-update / +table-delete` | -| [`field commands`](references/lark-base-field.md) | `+field-list / +field-get / +field-create / +field-update / +field-delete / +field-search-options` | -| [`record commands`](references/lark-base-record.md) | `+record-list / +record-get / +record-upsert / +record-upload-attachment / +record-delete` | -| [`view commands`](references/lark-base-view.md) | `+view-list / +view-get / +view-create / +view-delete / +view-get-* / +view-set-* / +view-rename` | -| [`data-query commands`](references/lark-base-data-query.md) | `+data-query` | -| [`history commands`](references/lark-base-history.md) | `+record-history-list` | -| [`base / workspace commands`](references/lark-base-workspace.md) | `+base-create / +base-get / +base-copy` | -| [`advperm commands`](references/lark-base-advperm-enable.md) | `+advperm-enable / +advperm-disable` | -| [`role commands`](references/lark-base-role-list.md) | `+role-list / +role-get / +role-create / +role-update / +role-delete` | -| [`form commands`](references/lark-base-form-create.md) | `+form-list / +form-get / +form-create / +form-update / +form-delete` | -| [`form questions commands`](references/lark-base-form-questions-create.md) | `+form-questions-list / +form-questions-create / +form-questions-update / +form-questions-delete` | -| [`workflow commands`](references/lark-base-workflow.md) | `+workflow-list / +workflow-get / +workflow-create / +workflow-update / +workflow-enable / +workflow-disable` | -| [`dashboard / dashboard-block commands`](references/lark-base-dashboard.md) | `+dashboard-list / +dashboard-get / +dashboard-create / +dashboard-update / +dashboard-delete / +dashboard-block-list / +dashboard-block-get / +dashboard-block-create / +dashboard-block-update / +dashboard-block-delete` | +| `1254104` | 批量超 500 条 | 分批调用 | +| `1254291` | 并发写冲突 | 串行写入 + 批次间延迟 | From 3d1c4e2baf1b4894015940c0ba167e941f8e5496 Mon Sep 17 00:00:00 2001 From: "zhouyue.z" Date: Thu, 9 Apr 2026 21:59:54 +0800 Subject: [PATCH 2/5] docs: condense lark-base command tables --- skills/lark-base/SKILL.md | 94 +++++++++++++-------------------------- 1 file changed, 30 insertions(+), 64 deletions(-) diff --git a/skills/lark-base/SKILL.md b/skills/lark-base/SKILL.md index a58b43973..38be66342 100644 --- a/skills/lark-base/SKILL.md +++ b/skills/lark-base/SKILL.md @@ -63,8 +63,8 @@ metadata: 用于管理 Base 本体，或从用户给出的链接进入后续 Base 操作。 模块索引：[`references/lark-base-workspace.md`](references/lark-base-workspace.md) -| 命令 / 输入 | 用途 / 何时使用 | 必读 reference | 路由提醒 | -|-------------|------------------|----------------|----------| +| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 | +|------|------------------|----------------|----------| | `+base-create` | 创建新的 Base | [`lark-base-base-create.md`](references/lark-base-base-create.md)、[`lark-base-workspace.md`](references/lark-base-workspace.md) | 写入操作；执行前先读 reference | | `+base-get` | 获取 Base 信息 | [`lark-base-base-get.md`](references/lark-base-base-get.md)、[`lark-base-workspace.md`](references/lark-base-workspace.md) | 适合确认 Base 本体信息，不替代表/字段结构读取 | | `+base-copy` | 复制已有 Base | [`lark-base-base-copy.md`](references/lark-base-base-copy.md)、[`lark-base-workspace.md`](references/lark-base-workspace.md) | 写入操作；执行前先读 reference | @@ -80,11 +80,8 @@ metadata: | 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 | |------|------------------|----------------|----------| -| `+table-list` | 列出当前 Base 内的数据表 | [`lark-base-table-list.md`](references/lark-base-table-list.md) | `+xxx-list` 只能串行执行 | -| `+table-get` | 获取单个表的详情 | [`lark-base-table-get.md`](references/lark-base-table-get.md) | 适合删除/修改前确认目标 | -| `+table-create` | 创建数据表 | [`lark-base-table-create.md`](references/lark-base-table-create.md) | 一次性建表场景可用 | -| `+table-update` | 更新表信息 | [`lark-base-table-update.md`](references/lark-base-table-update.md) | 修改前先确认目标表 | -| `+table-delete` | 删除数据表 | [`lark-base-table-delete.md`](references/lark-base-table-delete.md) | 用户已明确目标时可直接执行并带 `--yes` | +| `+table-list / +table-get` | 列出数据表，或获取单个表详情 | [`lark-base-table-list.md`](references/lark-base-table-list.md)、[`lark-base-table-get.md`](references/lark-base-table-get.md) | `+table-list` 只能串行执行；`+table-get` 适合删除/修改前确认目标 | +| `+table-create / +table-update / +table-delete` | 创建、更新或删除数据表 | [`lark-base-table-create.md`](references/lark-base-table-create.md)、[`lark-base-table-update.md`](references/lark-base-table-update.md)、[`lark-base-table-delete.md`](references/lark-base-table-delete.md) | 创建适合一次性建表；更新前先确认目标表；删除时用户已明确目标可直接执行并带 `--yes` | #### 2.3.2 Field 子模块 @@ -93,11 +90,8 @@ metadata: | 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 | |------|------------------|----------------|----------| -| `+field-list` | 列出字段结构 | [`lark-base-field-list.md`](references/lark-base-field-list.md) | 写记录、写字段、做分析前常先读它；只能串行执行 | -| `+field-get` | 获取单个字段详情 | [`lark-base-field-get.md`](references/lark-base-field-get.md) | 适合删除/更新前确认目标 | -| `+field-create` | 创建普通字段 | [`lark-base-field-create.md`](references/lark-base-field-create.md)、[`lark-base-shortcut-field-properties.md`](references/lark-base-shortcut-field-properties.md) | 写字段前先看字段属性规范；如果类型是 `formula / lookup`，先转去读对应 guide | -| `+field-update` | 更新普通字段属性 | [`lark-base-field-update.md`](references/lark-base-field-update.md)、[`lark-base-shortcut-field-properties.md`](references/lark-base-shortcut-field-properties.md) | 写字段前先看字段属性规范；如果类型是 `formula / lookup`，先转去读对应 guide | -| `+field-delete` | 删除字段 | [`lark-base-field-delete.md`](references/lark-base-field-delete.md) | 用户已明确目标时可直接执行并带 `--yes` | +| `+field-list / +field-get` | 列出字段结构，或获取单个字段详情 | [`lark-base-field-list.md`](references/lark-base-field-list.md)、[`lark-base-field-get.md`](references/lark-base-field-get.md) | 写记录、写字段、做分析前常先读 `+field-list`；`+field-list` 只能串行执行；`+field-get` 适合删除/更新前确认目标 | +| `+field-create / +field-update / +field-delete` | 创建、更新或删除普通字段 | [`lark-base-field-create.md`](references/lark-base-field-create.md)、[`lark-base-field-update.md`](references/lark-base-field-update.md)、[`lark-base-field-delete.md`](references/lark-base-field-delete.md)、[`lark-base-shortcut-field-properties.md`](references/lark-base-shortcut-field-properties.md) | 写字段前先看字段属性规范；如果类型是 `formula / lookup`，先转去读对应 guide；删除时用户已明确目标可直接执行并带 `--yes` | | `+field-search-options` | 查询字段可选项 | [`lark-base-field-search-options.md`](references/lark-base-field-search-options.md) | 适合单选/多选等选项型字段 | #### 2.3.3 Record 子模块 @@ -106,12 +100,10 @@ metadata: | 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 | |------|------------------|----------------|----------| -| `+record-list` | 读取记录明细、样例、分页导出 | [`lark-base-record-list.md`](references/lark-base-record-list.md) | 不用于聚合分析；`--limit` 最大 `200`；仅在用户明确需要时继续翻页；只能串行执行 | -| `+record-get` | 获取单条记录详情 | [`lark-base-record-get.md`](references/lark-base-record-get.md) | 适合目标记录已明确时使用 | +| `+record-list / +record-get` | 读取记录明细、样例、分页导出，或获取单条记录详情 | [`lark-base-record-list.md`](references/lark-base-record-list.md)、[`lark-base-record-get.md`](references/lark-base-record-get.md) | `+record-list` 不用于聚合分析；`--limit` 最大 `200`；仅在用户明确需要时继续翻页；只能串行执行；`+record-get` 适合目标记录已明确时使用 | | `+record-upsert` | 创建或更新记录 | [`lark-base-record-upsert.md`](references/lark-base-record-upsert.md)、[`lark-base-shortcut-record-value.md`](references/lark-base-shortcut-record-value.md) | 写前先 `+field-list`；只写存储字段；附件不要走这里 | | `+record-upload-attachment` | 给已有记录上传附件 | [`lark-base-record-upload-attachment.md`](references/lark-base-record-upload-attachment.md) | 附件上传专用链路，不要用 `+record-upsert` 伪造附件值 | -| `+record-delete` | 删除记录 | [`lark-base-record-delete.md`](references/lark-base-record-delete.md) | 用户已明确目标时可直接执行并带 `--yes` | -| `+record-history-list` | 查询某条记录的变更历史 | [`lark-base-record-history-list.md`](references/lark-base-record-history-list.md) | 按 `table-id + record-id` 查询，不支持整表历史扫描；只能串行执行 | +| `+record-delete / +record-history-list` | 删除记录，或查询某条记录的变更历史 | [`lark-base-record-delete.md`](references/lark-base-record-delete.md)、[`lark-base-record-history-list.md`](references/lark-base-record-history-list.md) | 删除时用户已明确目标可直接执行并带 `--yes`；历史查询按 `table-id + record-id`，不支持整表扫描；`+record-history-list` 只能串行执行 | #### 2.3.4 View 子模块 @@ -119,21 +111,13 @@ metadata: | 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 | |------|------------------|----------------|----------| -| `+view-list` | 列出视图 | [`lark-base-view-list.md`](references/lark-base-view-list.md) | 只能串行执行 | -| `+view-get` | 获取视图详情 | [`lark-base-view-get.md`](references/lark-base-view-get.md) | 适合查看已有视图配置 | -| `+view-create` | 创建视图 | [`lark-base-view-create.md`](references/lark-base-view-create.md) | 先确认表和视图类型 | -| `+view-delete` | 删除视图 | [`lark-base-view-delete.md`](references/lark-base-view-delete.md) | 删除前先确认目标 | -| `+view-get-filter` | 读取筛选配置 | [`lark-base-view-get-filter.md`](references/lark-base-view-get-filter.md) | 适合先看配置再修改 | -| `+view-set-filter` | 配置筛选条件 | [`lark-base-view-set-filter.md`](references/lark-base-view-set-filter.md)、[`lark-base-record-list.md`](references/lark-base-record-list.md) | 常与 `+record-list` 组合，用于按视图筛选读取 | -| `+view-get-sort` | 读取排序配置 | [`lark-base-view-get-sort.md`](references/lark-base-view-get-sort.md) | 适合先看配置再修改 | -| `+view-set-sort` | 配置排序 | [`lark-base-view-set-sort.md`](references/lark-base-view-set-sort.md) | 字段名必须来自真实结构 | -| `+view-get-group` | 读取分组配置 | [`lark-base-view-get-group.md`](references/lark-base-view-get-group.md) | 适合先看配置再修改 | -| `+view-set-group` | 配置分组 | [`lark-base-view-set-group.md`](references/lark-base-view-set-group.md) | 字段名必须来自真实结构 | -| `+view-get-card` | 读取卡片视图配置 | [`lark-base-view-get-card.md`](references/lark-base-view-get-card.md) | 适合先看配置再修改 | -| `+view-set-card` | 配置卡片视图 | [`lark-base-view-set-card.md`](references/lark-base-view-set-card.md) | 适合卡片展示场景 | -| `+view-get-timebar` | 读取时间轴配置 | [`lark-base-view-get-timebar.md`](references/lark-base-view-get-timebar.md) | 适合先看配置再修改 | -| `+view-set-timebar` | 配置时间轴视图 | [`lark-base-view-set-timebar.md`](references/lark-base-view-set-timebar.md) | 适合时间线展示场景 | -| `+view-rename` | 重命名视图 | [`lark-base-view-rename.md`](references/lark-base-view-rename.md) | 用户已明确新名字时可直接执行 | +| `+view-list / +view-get` | 列出视图，或获取视图详情 | [`lark-base-view-list.md`](references/lark-base-view-list.md)、[`lark-base-view-get.md`](references/lark-base-view-get.md) | `+view-list` 只能串行执行；`+view-get` 适合查看已有视图配置 | +| `+view-create / +view-delete / +view-rename` | 创建、删除或重命名视图 | [`lark-base-view-create.md`](references/lark-base-view-create.md)、[`lark-base-view-delete.md`](references/lark-base-view-delete.md)、[`lark-base-view-rename.md`](references/lark-base-view-rename.md) | 创建前先确认表和视图类型；删除前先确认目标；用户已明确新名字时可直接重命名 | +| `+view-get-filter / +view-set-filter` | 读取或配置筛选条件 | [`lark-base-view-get-filter.md`](references/lark-base-view-get-filter.md)、[`lark-base-view-set-filter.md`](references/lark-base-view-set-filter.md)、[`lark-base-record-list.md`](references/lark-base-record-list.md) | 常与 `+record-list` 组合，用于按视图筛选读取 | +| `+view-get-sort / +view-set-sort` | 读取或配置排序 | [`lark-base-view-get-sort.md`](references/lark-base-view-get-sort.md)、[`lark-base-view-set-sort.md`](references/lark-base-view-set-sort.md) | 字段名必须来自真实结构 | +| `+view-get-group / +view-set-group` | 读取或配置分组 | [`lark-base-view-get-group.md`](references/lark-base-view-get-group.md)、[`lark-base-view-set-group.md`](references/lark-base-view-set-group.md) | 字段名必须来自真实结构 | +| `+view-get-card / +view-set-card` | 读取或配置卡片视图 | [`lark-base-view-get-card.md`](references/lark-base-view-get-card.md)、[`lark-base-view-set-card.md`](references/lark-base-view-set-card.md) | 适合卡片展示场景 | +| `+view-get-timebar / +view-set-timebar` | 读取或配置时间轴视图 | [`lark-base-view-get-timebar.md`](references/lark-base-view-get-timebar.md)、[`lark-base-view-set-timebar.md`](references/lark-base-view-set-timebar.md) | 适合时间线展示场景 | ### 2.4 公式 / Lookup 模块 @@ -142,8 +126,8 @@ metadata: 默认优先考虑 `formula`：适合常规计算、条件判断、文本处理、日期差、跨表聚合，以及需要长期显示在表里的派生结果。 只有当用户明确要求 `lookup`，或场景天然符合 `from / select / where / aggregate` 这种固定查找建模时，再使用 `lookup`。 -| 命令 / 能力 | 用途 / 何时使用 | 必读 reference | 路由提醒 | -|-------------|------------------|----------------|----------| +| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 | +|------|------------------|----------------|----------| | `+field-create`（`type=formula`） | 创建公式字段 | [`formula-field-guide.md`](references/formula-field-guide.md)、[`lark-base-field-create.md`](references/lark-base-field-create.md)、[`lark-base-shortcut-field-properties.md`](references/lark-base-shortcut-field-properties.md) | 没读 guide 前不要直接创建 | | `+field-update`（`type=formula`） | 更新公式字段 | [`formula-field-guide.md`](references/formula-field-guide.md)、[`lark-base-field-update.md`](references/lark-base-field-update.md)、[`lark-base-shortcut-field-properties.md`](references/lark-base-shortcut-field-properties.md) | 先拿当前表结构 | | `+field-create`（`type=lookup`） | 创建 lookup 字段 | [`lookup-field-guide.md`](references/lookup-field-guide.md)、[`lark-base-field-create.md`](references/lark-base-field-create.md)、[`lark-base-shortcut-field-properties.md`](references/lark-base-shortcut-field-properties.md) | 没读 guide 前不要直接创建 | @@ -164,12 +148,9 @@ metadata: | 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 | |------|------------------|----------------|----------| -| `+workflow-list` | 列出 workflow | [`lark-base-workflow-list.md`](references/lark-base-workflow-list.md)、[`lark-base-workflow-schema.md`](references/lark-base-workflow-schema.md) | 只返回摘要，不是完整树结构；只能串行执行 | -| `+workflow-get` | 获取完整 workflow 结构 | [`lark-base-workflow-get.md`](references/lark-base-workflow-get.md)、[`lark-base-workflow-schema.md`](references/lark-base-workflow-schema.md) | 需要完整结构时用它，不要只看 `+workflow-list` | -| `+workflow-create` | 创建 workflow | [`lark-base-workflow-create.md`](references/lark-base-workflow-create.md)、[`lark-base-workflow-schema.md`](references/lark-base-workflow-schema.md) | 先读 schema；禁止凭自然语言猜 `type`；先确认真实表名和字段名 | -| `+workflow-update` | 更新 workflow | [`lark-base-workflow-update.md`](references/lark-base-workflow-update.md)、[`lark-base-workflow-schema.md`](references/lark-base-workflow-schema.md) | 先读 schema；禁止凭自然语言猜 `type`；先确认真实表名和字段名 | -| `+workflow-enable` | 启用 workflow | [`lark-base-workflow-enable.md`](references/lark-base-workflow-enable.md)、[`lark-base-workflow-schema.md`](references/lark-base-workflow-schema.md) | 启用前先确认目标 workflow | -| `+workflow-disable` | 停用 workflow | [`lark-base-workflow-disable.md`](references/lark-base-workflow-disable.md)、[`lark-base-workflow-schema.md`](references/lark-base-workflow-schema.md) | 停用前先确认目标 workflow | +| `+workflow-list / +workflow-get` | 列出 workflow，或获取完整 workflow 结构 | [`lark-base-workflow-list.md`](references/lark-base-workflow-list.md)、[`lark-base-workflow-get.md`](references/lark-base-workflow-get.md)、[`lark-base-workflow-schema.md`](references/lark-base-workflow-schema.md) | `+workflow-list` 只返回摘要且只能串行执行；需要完整结构时用 `+workflow-get` | +| `+workflow-create / +workflow-update` | 创建或更新 workflow | [`lark-base-workflow-create.md`](references/lark-base-workflow-create.md)、[`lark-base-workflow-update.md`](references/lark-base-workflow-update.md)、[`lark-base-workflow-schema.md`](references/lark-base-workflow-schema.md) | 先读 schema；禁止凭自然语言猜 `type`；先确认真实表名和字段名 | +| `+workflow-enable / +workflow-disable` | 启用或停用 workflow | [`lark-base-workflow-enable.md`](references/lark-base-workflow-enable.md)、[`lark-base-workflow-disable.md`](references/lark-base-workflow-disable.md)、[`lark-base-workflow-schema.md`](references/lark-base-workflow-schema.md) | 启用或停用前先确认目标 workflow | ### 2.7 Dashboard 模块 @@ -177,16 +158,10 @@ metadata: | 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 | |------|------------------|----------------|----------| -| `+dashboard-list` | 列出仪表盘 | [`lark-base-dashboard-list.md`](references/lark-base-dashboard-list.md)、[`lark-base-dashboard.md`](references/lark-base-dashboard.md) | 进入仪表盘语义后先读 guide；只能串行执行 | -| `+dashboard-get` | 获取仪表盘详情 | [`lark-base-dashboard-get.md`](references/lark-base-dashboard-get.md)、[`lark-base-dashboard.md`](references/lark-base-dashboard.md) | 适合查看已有看板配置 | -| `+dashboard-create` | 创建仪表盘 | [`lark-base-dashboard-create.md`](references/lark-base-dashboard-create.md)、[`lark-base-dashboard.md`](references/lark-base-dashboard.md) | 先明确看板目标和展示场景 | -| `+dashboard-update` | 更新仪表盘 | [`lark-base-dashboard-update.md`](references/lark-base-dashboard-update.md)、[`lark-base-dashboard.md`](references/lark-base-dashboard.md) | 更新前先读取当前配置 | -| `+dashboard-delete` | 删除仪表盘 | [`lark-base-dashboard-delete.md`](references/lark-base-dashboard-delete.md)、[`lark-base-dashboard.md`](references/lark-base-dashboard.md) | 删除前先确认目标 | -| `+dashboard-block-list` | 列出图表组件 | [`lark-base-dashboard-block-list.md`](references/lark-base-dashboard-block-list.md)、[`lark-base-dashboard.md`](references/lark-base-dashboard.md) | 只能串行执行 | -| `+dashboard-block-get` | 获取单个 block 详情 | [`lark-base-dashboard-block-get.md`](references/lark-base-dashboard-block-get.md)、[`lark-base-dashboard.md`](references/lark-base-dashboard.md)、[`dashboard-block-data-config.md`](references/dashboard-block-data-config.md) | 适合查看图表配置细节 | -| `+dashboard-block-create` | 创建图表组件 | [`lark-base-dashboard-block-create.md`](references/lark-base-dashboard-block-create.md)、[`lark-base-dashboard.md`](references/lark-base-dashboard.md)、[`dashboard-block-data-config.md`](references/dashboard-block-data-config.md) | 涉及 `data_config`、图表类型、filter 时要读 block config 文档 | -| `+dashboard-block-update` | 更新图表组件 | [`lark-base-dashboard-block-update.md`](references/lark-base-dashboard-block-update.md)、[`lark-base-dashboard.md`](references/lark-base-dashboard.md)、[`dashboard-block-data-config.md`](references/dashboard-block-data-config.md) | 涉及 `data_config`、图表类型、filter 时要读 block config 文档 | -| `+dashboard-block-delete` | 删除图表组件 | [`lark-base-dashboard-block-delete.md`](references/lark-base-dashboard-block-delete.md)、[`lark-base-dashboard.md`](references/lark-base-dashboard.md) | 删除前先确认目标 | +| `+dashboard-list / +dashboard-get` | 列出仪表盘，或获取仪表盘详情 | [`lark-base-dashboard-list.md`](references/lark-base-dashboard-list.md)、[`lark-base-dashboard-get.md`](references/lark-base-dashboard-get.md)、[`lark-base-dashboard.md`](references/lark-base-dashboard.md) | 进入仪表盘语义后先读 guide；`+dashboard-list` 只能串行执行 | +| `+dashboard-create / +dashboard-update / +dashboard-delete` | 创建、更新或删除仪表盘 | [`lark-base-dashboard-create.md`](references/lark-base-dashboard-create.md)、[`lark-base-dashboard-update.md`](references/lark-base-dashboard-update.md)、[`lark-base-dashboard-delete.md`](references/lark-base-dashboard-delete.md)、[`lark-base-dashboard.md`](references/lark-base-dashboard.md) | 创建前先明确看板目标和展示场景；更新前先读取当前配置；删除前先确认目标 | +| `+dashboard-block-list / +dashboard-block-get` | 列出图表组件，或获取单个 block 详情 | [`lark-base-dashboard-block-list.md`](references/lark-base-dashboard-block-list.md)、[`lark-base-dashboard-block-get.md`](references/lark-base-dashboard-block-get.md)、[`lark-base-dashboard.md`](references/lark-base-dashboard.md)、[`dashboard-block-data-config.md`](references/dashboard-block-data-config.md) | `+dashboard-block-list` 只能串行执行；查看配置细节时读 block config 文档 | +| `+dashboard-block-create / +dashboard-block-update / +dashboard-block-delete` | 创建、更新或删除图表组件 | [`lark-base-dashboard-block-create.md`](references/lark-base-dashboard-block-create.md)、[`lark-base-dashboard-block-update.md`](references/lark-base-dashboard-block-update.md)、[`lark-base-dashboard-block-delete.md`](references/lark-base-dashboard-block-delete.md)、[`lark-base-dashboard.md`](references/lark-base-dashboard.md)、[`dashboard-block-data-config.md`](references/dashboard-block-data-config.md) | 涉及 `data_config`、图表类型、filter 时要读 block config 文档；删除前先确认目标 | ### 2.8 表单模块 @@ -195,15 +170,10 @@ metadata: | 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 | |------|------------------|----------------|----------| -| `+form-list` | 列出表单 | [`lark-base-form-list.md`](references/lark-base-form-list.md) | 可用来获取 `form-id` | -| `+form-get` | 获取单个表单 | [`lark-base-form-get.md`](references/lark-base-form-get.md) | 适合查看已有表单配置 | -| `+form-create` | 创建表单 | [`lark-base-form-create.md`](references/lark-base-form-create.md) | 创建后可继续进入表单问题相关操作 | -| `+form-update` | 更新表单 | [`lark-base-form-update.md`](references/lark-base-form-update.md) | 更新前先确认目标表单 | -| `+form-delete` | 删除表单 | [`lark-base-form-delete.md`](references/lark-base-form-delete.md) | 删除前先确认目标 | +| `+form-list / +form-get` | 列出表单，或获取单个表单 | [`lark-base-form-list.md`](references/lark-base-form-list.md)、[`lark-base-form-get.md`](references/lark-base-form-get.md) | `+form-list` 可用来获取 `form-id`；`+form-get` 适合查看已有表单配置 | +| `+form-create / +form-update / +form-delete` | 创建、更新或删除表单 | [`lark-base-form-create.md`](references/lark-base-form-create.md)、[`lark-base-form-update.md`](references/lark-base-form-update.md)、[`lark-base-form-delete.md`](references/lark-base-form-delete.md) | 创建后可继续进入表单问题相关操作；更新或删除前先确认目标表单 | | `+form-questions-list` | 列出表单题目 | [`lark-base-form-questions-list.md`](references/lark-base-form-questions-list.md) | 适合查看已有题目结构 | -| `+form-questions-create` | 创建题目 | [`lark-base-form-questions-create.md`](references/lark-base-form-questions-create.md) | 先确认 `form-id` | -| `+form-questions-update` | 更新题目 | [`lark-base-form-questions-update.md`](references/lark-base-form-questions-update.md) | 先确认 `form-id` 和题目目标 | -| `+form-questions-delete` | 删除题目 | [`lark-base-form-questions-delete.md`](references/lark-base-form-questions-delete.md) | 删除前先确认题目目标 | +| `+form-questions-create / +form-questions-update / +form-questions-delete` | 创建、更新或删除题目 | [`lark-base-form-questions-create.md`](references/lark-base-form-questions-create.md)、[`lark-base-form-questions-update.md`](references/lark-base-form-questions-update.md)、[`lark-base-form-questions-delete.md`](references/lark-base-form-questions-delete.md) | 先确认 `form-id`；更新或删除前先确认题目目标 | ### 2.9 权限与角色模块 @@ -212,13 +182,9 @@ metadata: | 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 | |------|------------------|----------------|----------| -| `+advperm-enable` | 启用高级权限 | [`lark-base-advperm-enable.md`](references/lark-base-advperm-enable.md) | 管理角色前必须先启用 | -| `+advperm-disable` | 停用高级权限 | [`lark-base-advperm-disable.md`](references/lark-base-advperm-disable.md) | 高风险操作；停用后已有自定义角色全部失效 | -| `+role-list` | 列出角色 | [`lark-base-role-list.md`](references/lark-base-role-list.md)、[`role-config.md`](references/role-config.md) | 只能串行执行 | -| `+role-get` | 获取角色详情 | [`lark-base-role-get.md`](references/lark-base-role-get.md)、[`role-config.md`](references/role-config.md) | 适合查看完整权限配置 | -| `+role-create` | 创建自定义角色 | [`lark-base-role-create.md`](references/lark-base-role-create.md)、[`role-config.md`](references/role-config.md) | 仅支持 `custom_role`；写角色前先读 `role-config.md` | -| `+role-update` | 更新角色 | [`lark-base-role-update.md`](references/lark-base-role-update.md)、[`role-config.md`](references/role-config.md) | 采用 Delta Merge；`role_name` 和 `role_type` 即使不改也必须传当前值 | -| `+role-delete` | 删除角色 | [`lark-base-role-delete.md`](references/lark-base-role-delete.md)、[`role-config.md`](references/role-config.md) | 不可逆，且仅支持自定义角色 | +| `+advperm-enable / +advperm-disable` | 启用或停用高级权限 | [`lark-base-advperm-enable.md`](references/lark-base-advperm-enable.md)、[`lark-base-advperm-disable.md`](references/lark-base-advperm-disable.md) | 管理角色前必须先启用；停用是高风险操作，会使已有自定义角色失效 | +| `+role-list / +role-get` | 列出角色，或获取角色详情 | [`lark-base-role-list.md`](references/lark-base-role-list.md)、[`lark-base-role-get.md`](references/lark-base-role-get.md)、[`role-config.md`](references/role-config.md) | `+role-list` 只能串行执行；`+role-get` 适合查看完整权限配置 | +| `+role-create / +role-update / +role-delete` | 创建、更新或删除角色 | [`lark-base-role-create.md`](references/lark-base-role-create.md)、[`lark-base-role-update.md`](references/lark-base-role-update.md)、[`lark-base-role-delete.md`](references/lark-base-role-delete.md)、[`role-config.md`](references/role-config.md) | `+role-create` 仅支持 `custom_role`；`+role-update` 采用 Delta Merge，`role_name` 和 `role_type` 即使不改也必须传当前值；`+role-delete` 不可逆 | ## 3. 多维表格通用知识 From 145c0e602a84d1e41caef859b80bd0f402e75252 Mon Sep 17 00:00:00 2001 From: "zhouyue.z" Date: Thu, 9 Apr 2026 22:13:50 +0800 Subject: [PATCH 3/5] docs: tighten lark-base shared guidance --- skills/lark-base/SKILL.md | 58 ++++++++++++++++++--------------------- 1 file changed, 27 insertions(+), 31 deletions(-) diff --git a/skills/lark-base/SKILL.md b/skills/lark-base/SKILL.md index 38be66342..271dda3e6 100644 --- a/skills/lark-base/SKILL.md +++ b/skills/lark-base/SKILL.md @@ -18,28 +18,28 @@ metadata: ### 1.1 触发条件 -| 场景 | 是否应使用本 Skill | 说明 | -|------|-------------------|------| -| 用户明确要操作飞书多维表格 / Base | 是 | 本 skill 的主场景 | -| 用户要建表、改表、查表、删表 | 是 | 进入表与数据模块 | -| 用户要管理字段、记录、视图 | 是 | 进入表与数据模块 | -| 用户要做公式字段、lookup 字段、派生指标、跨表计算 | 是 | 进入公式 / Lookup 模块 | -| 用户要做临时统计、聚合分析、比较排序、求最值 | 是 | 进入数据分析模块 | -| 用户要管理 workflow、dashboard、表单、角色权限 | 是 | 进入对应模块 | -| 用户给出 `/base/{token}` 链接 | 是 | 先解析链接，再进入对应模块 | -| 用户给出 `/wiki/{token}` 链接，且最终解析为 `bitable` | 是 | 先解析 wiki，再继续走 `lark-cli base +...` | -| 用户要把旧的 Base 聚合式写法改成当前原子命令写法 | 是 | 例如把旧 `+table / +field / +record / +view / +history / +workspace` 改写成当前命令 | -| 用户只是做认证、初始化配置、切换 `--as user/bot`、处理 scope | 否 | 先读 `../lark-shared/SKILL.md` | -| 用户只是泛化地讨论“数据分析 / 字段设计”，但并不在 Base 场景中 | 否 | 不要因为提到“统计 / 公式 / lookup”就误触发 | +以下场景应使用本 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 前置约束 -| 项目 | 规则 | -|------|------| -| 共享前置 | 先阅读 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) | -| 命令形态 | 仅使用 `lark-cli base +...` 形式的 shortcut 命令 | -| reference 使用方式 | 定位到命令后，先读该命令对应的 reference，再执行命令 | -| 禁止路线 | 不要在 Base 场景改走 `lark-cli api /open-apis/bitable/v1/...` | +1. 先阅读 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)。 +2. 仅使用 `lark-cli base +...` 形式的 shortcut 命令。 +3. 定位到命令后，先读该命令对应的 reference，再执行命令。 +4. 不要在 Base 场景改走 `lark-cli api /open-apis/bitable/v1/...`。 ## 2. 模块与命令导航 @@ -213,12 +213,10 @@ metadata: ### 3.3 表名、字段名与表达式引用 -| 规则 | 说明 | -|------|------| -| 表名、字段名必须精确匹配真实返回 | 必须来自 `+table-list / +table-get / +field-list` 的结果 | -| 不要凭自然语言猜名称 | 不要自行改写用户口述中的表名、字段名 | -| `formula / lookup / data-query / workflow` 中的名称同样必须精确匹配 | 表达式引用、where 条件、DSL 字段名、workflow 配置都遵守同一规则 | -| 跨表场景必须额外读取目标表结构 | 不能只看当前表 | +1. 表名、字段名必须精确匹配真实返回，来源应是 `+table-list / +table-get / +field-list`。 +2. 不要凭自然语言猜名称，不要自行改写用户口述中的表名、字段名。 +3. `formula / lookup / data-query / workflow` 中出现的名称同样必须精确匹配；表达式引用、where 条件、DSL 字段名、workflow 配置都遵守同一规则。 +4. 跨表场景必须额外读取目标表结构，不能只看当前表。 ### 3.4 Token 与链接 @@ -228,7 +226,7 @@ metadata: |---------|--------------|------| | 直接 Base 链接 `/base/{token}` | 直接提取 token 作为 `--base-token` | 不要把完整 URL 直接作为 `--base-token` | | Wiki 链接 `/wiki/{token}` | 先 `wiki.spaces.get_node`，再取 `node.obj_token` | 不要把 `wiki_token` 直接当 `--base-token` | -| URL 中的 `?table={id}` | 先按前缀判断对象类型 | `tbl` 开头表示数据表 ID，可作为 `--table-id`；`blk` 开头表示仪表盘 block ID；`wkf` 开头表示 workflow ID；`ldx` 开头表示内嵌文档 ID，不要一律当成 `--table-id` | +| URL 中的 `?table={id}` | 先按前缀判断对象类型 | `tbl` 开头表示数据表 `table-id`，可作为 `--table-id`；`blk` 开头表示仪表盘 `dashboard-ID`；`wkf` 开头表示 `workflow-ID`；`ldx` 开头表示内嵌文档，不要一律当成 `--table-id` | | URL 中的 `?view={id}` | 提取为 `--view-id` | 适合直接定位视图 | | `wiki.spaces.get_node` 返回的 `obj_type` | 后续路线 | 说明 | @@ -243,11 +241,9 @@ metadata: ### 3.5 执行身份与人员字段 -| 场景 | 提醒 | -|------|------| -| 人员字段 / 用户字段 | 注意 `user_id_type` 与执行身份（user / bot）差异 | -| bot 身份 | bot 看不到用户私有资源；行为以应用身份执行 | -| user 身份 | 依赖用户授权和 scope；更适合操作用户资源 | +- 人员字段 / 用户字段：注意 `user_id_type` 与执行身份（user / bot）差异。 +- bot 身份：bot 看不到用户私有资源；行为以应用身份执行。 +- user 身份：依赖用户授权和 scope；更适合操作用户资源。 ## 4. 执行规则 From 23e92ab1ffcb3d4c844742244b7ad153fb9d330d Mon Sep 17 00:00:00 2001 From: "zhouyue.z" Date: Thu, 9 Apr 2026 22:35:31 +0800 Subject: [PATCH 4/5] docs: refine lark-base routing guidance --- skills/lark-base/SKILL.md | 42 ++++++++++++++++++++++----------------- 1 file changed, 24 insertions(+), 18 deletions(-) diff --git a/skills/lark-base/SKILL.md b/skills/lark-base/SKILL.md index 271dda3e6..2f3dd6a2f 100644 --- a/skills/lark-base/SKILL.md +++ b/skills/lark-base/SKILL.md @@ -96,11 +96,11 @@ metadata: #### 2.3.3 Record 子模块 -子模块索引：[`references/lark-base-record.md`](references/lark-base-record.md) +子模块索引：[`references/lark-base-record.md`](references/lark-base-record.md)、[`references/lark-base-history.md`](references/lark-base-history.md) | 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 | |------|------------------|----------------|----------| -| `+record-list / +record-get` | 读取记录明细、样例、分页导出，或获取单条记录详情 | [`lark-base-record-list.md`](references/lark-base-record-list.md)、[`lark-base-record-get.md`](references/lark-base-record-get.md) | `+record-list` 不用于聚合分析；`--limit` 最大 `200`；仅在用户明确需要时继续翻页；只能串行执行；`+record-get` 适合目标记录已明确时使用 | +| `+record-list / +record-get` | 读取记录明细、样例、分页导出，或获取单条记录详情 | [`lark-base-record-list.md`](references/lark-base-record-list.md)、[`lark-base-record-get.md`](references/lark-base-record-get.md) | `+record-list` 不用于聚合分析；如果要统计而不是列出原始记录，请使用 `+data-query`；`--limit` 最大 `200`；仅在用户明确需要时继续翻页；只能串行执行；`+record-get` 适合目标记录已明确时使用 | | `+record-upsert` | 创建或更新记录 | [`lark-base-record-upsert.md`](references/lark-base-record-upsert.md)、[`lark-base-shortcut-record-value.md`](references/lark-base-shortcut-record-value.md) | 写前先 `+field-list`；只写存储字段；附件不要走这里 | | `+record-upload-attachment` | 给已有记录上传附件 | [`lark-base-record-upload-attachment.md`](references/lark-base-record-upload-attachment.md) | 附件上传专用链路，不要用 `+record-upsert` 伪造附件值 | | `+record-delete / +record-history-list` | 删除记录，或查询某条记录的变更历史 | [`lark-base-record-delete.md`](references/lark-base-record-delete.md)、[`lark-base-record-history-list.md`](references/lark-base-record-history-list.md) | 删除时用户已明确目标可直接执行并带 `--yes`；历史查询按 `table-id + record-id`，不支持整表扫描；`+record-history-list` 只能串行执行 | @@ -137,9 +137,15 @@ metadata: 用于一次性分析和临时聚合查询。用户要的是“这次算出来的结果”，而不是把结果沉淀成字段时，优先进入本模块。 +进入本模块前先确认几件事： + +- `+data-query` 只做聚合查询（分组、过滤、排序、聚合计算），不用于列出原始记录或逐条明细。 +- 调用者必须是目标多维表格的管理员，拥有目标多维表格的 FA（Full Access / 完全访问权限），否则会返回权限错误。 +- `+data-query` 只支持白名单字段类型；`formula`、`lookup`、附件、系统字段、关联等字段不能用于 `dimensions / measures / filters / sort`。 + | 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 | |------|------------------|----------------|----------| -| `+data-query` | 做分组统计、SUM / AVG / COUNT / MAX / MIN、条件筛选后的聚合分析 | [`lark-base-data-query.md`](references/lark-base-data-query.md) | 字段名必须精确匹配真实字段名；不要用 `+record-list` 拉全量再手算；`+data-query` 不返回原始记录 | +| `+data-query` | 做分组统计、SUM / AVG / COUNT / MAX / MIN、条件筛选后的聚合分析 | [`lark-base-data-query.md`](references/lark-base-data-query.md) | 字段名必须精确匹配真实字段名；不要用 `+record-list` 拉全量再手算；`+data-query` 不返回原始记录；使用前先确认权限和字段类型是否受支持 | ### 2.6 Workflow 模块 @@ -166,6 +172,7 @@ metadata: ### 2.8 表单模块 用于管理表单本体和表单题目。 +模块索引：[`references/lark-base-form.md`](references/lark-base-form.md)、[`references/lark-base-form-questions.md`](references/lark-base-form-questions.md) 表单问题相关操作依赖 `form-id`；具体获取方式见 `form-list` 和 `form-create` 的 reference。 | 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 | @@ -197,8 +204,8 @@ metadata: | 存储字段 | 真实存用户输入的数据 | 可以 | 常见如文本、数字、日期、单选、多选、人员、关联 | | 附件字段 | 存储文件附件 | 不能直接按普通字段写 | 上传附件必须走 `+record-upload-attachment` | | 系统字段 | 平台自动维护 | 不可以 | 常见如创建时间、更新时间、创建人、修改人、自动编号 | -| `formula` 字段 | 通过表达式计算 | 不可以 | 只读输出字段 | -| `lookup` 字段 | 通过跨表规则查找引用 | 不可以 | 只读输出字段 | +| `formula` 字段 | 通过表达式计算 | 不可以 | 只读字段 | +| `lookup` 字段 | 通过跨表规则查找引用 | 不可以 | 只读字段 | ### 3.2 任务选路心智模型 @@ -258,19 +265,18 @@ metadata: ### 4.2 不可违反规则 -1. 仅使用 `lark-cli base +...` shortcut 命令，不使用旧聚合式 `+table / +field / +record / +view / +history / +workspace`。 -2. 先拿结构，再写命令；至少先拿当前表结构，跨表时还要拿目标表结构。 -3. 不要猜表名、字段名、表达式引用，一律以真实返回为准。 -4. 写记录前先读字段结构；先 `+field-list`，再按字段类型构造写入值。 -5. 写字段前先看字段属性规范；先读 `lark-base-shortcut-field-properties.md`，再构造 `+field-create / +field-update` 的 JSON。 -6. 只写可写字段；系统字段、`formula`、`lookup` 默认只读。 -7. 聚合分析与取数分流；统计走 `+data-query`，明细走 `+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 前不要直接创建或更新。 +1. 先拿结构，再写命令；至少先拿当前表结构，跨表时还要拿目标表结构。 +2. 不要猜表名、字段名、表达式引用，一律以真实返回为准。 +3. 写记录前先读字段结构；先 `+field-list`，再按字段类型构造写入值。 +4. 写字段前先看字段属性规范；先读 `lark-base-shortcut-field-properties.md`，再构造 `+field-create / +field-update` 的 JSON。 +5. 只写可写字段；系统字段、`formula`、`lookup` 默认只读。 +6. 聚合分析与取数分流；统计走 `+data-query`，明细走 `+record-list / +record-get`。 +7. 筛选查询按视图能力执行；先用 `+view-set-filter` 配置筛选，再结合 `+record-list` 读取。 +8. Base 场景不要改走裸 API，不要切去 `lark-cli api /open-apis/bitable/v1/...`。 +9. 统一使用 `--base-token`，不使用旧 `--app-token`。 +10. workflow 场景先读 schema，不要凭自然语言猜 `type`。 +11. dashboard 场景先读 guide；提到图表、看板、block 就先进入 dashboard 模块。 +12. formula / lookup 场景先读 guide；没读 guide 前不要直接创建或更新。 ### 4.3 并发、分页与批量限制 From b72d70ce7e607f962026e2fb923919bcbe67f105 Mon Sep 17 00:00:00 2001 From: "zhouyue.z" Date: Fri, 10 Apr 2026 11:00:33 +0800 Subject: [PATCH 5/5] Merge origin/main into docs/lark-base-skill-structure --- skills/lark-base/SKILL.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/skills/lark-base/SKILL.md b/skills/lark-base/SKILL.md index b8287be92..fa76d63df 100644 --- a/skills/lark-base/SKILL.md +++ b/skills/lark-base/SKILL.md @@ -237,14 +237,12 @@ metadata: | URL 中的 `?table={id}` | 先按前缀判断对象类型 | `tbl` 开头表示数据表 `table-id`，可作为 `--table-id`；`blk` 开头表示仪表盘 `dashboard-ID`；`wkf` 开头表示 `workflow-ID`；`ldx` 开头表示内嵌文档，不要一律当成 `--table-id` | | URL 中的 `?view={id}` | 提取为 `--view-id` | 适合直接定位视图 | -| `wiki.spaces.get_node` 返回的 `obj_type` | 后续路线 | 说明 | -|----------------------------------------|----------|------| +| `lark-cli wiki spaces get_node` 返回的 `obj_type` | 后续路线 | 说明 | +|-----------------------------------------------|----------|------| | `bitable` | 优先走 `lark-cli base +...` | 如果 shortcut 不覆盖，再用 `lark-cli base `；不要改走 `lark-cli api /open-apis/bitable/v1/...` | | `docx` | 转到文档 / Drive 相关 skill | 不继续使用本 skill 的 Base 命令 | -| `doc` | 转到文档 / Drive 相关 skill | 不继续使用本 skill 的 Base 命令 | | `sheet` | 转到 Sheets 相关 skill | 不继续使用本 skill 的 Base 命令 | | `slides` | 转到 Drive 相关 skill | 不继续使用本 skill 的 Base 命令 | -| `file` | 转到 Drive 相关 skill | 不继续使用本 skill 的 Base 命令 | | `mindnote` | 转到 Drive 相关 skill | 不继续使用本 skill 的 Base 命令 | ### 3.5 执行身份与人员字段