base
前置条件： 先阅读 [../lark-shared/SKILL.md](../lark-shared/SKILL.md)。
执行前必做： 执行任何 base 命令前，必须先阅读对应命令的 reference 文档，再调用命令。
命名约定： 仅使用 lark-cli base +... 形式的命令。
Agent 快速执行顺序
- 先判断任务类型
- 临时统计 / 聚合分析 →
+data-query - 要把结果长期显示在表里 → formula 字段
- 用户明确要 lookup，或确实更适合
from/select/where/aggregate→ lookup 字段 - 明细读取 / 导出 →
+record-list / +record-get - 先拿结构，再写命令
- 至少先拿当前表结构：
+field-list或+table-get - 跨表场景必须再查目标表的结构
- formula / lookup 有硬门槛
- 先读对应 guide
- 读完 guide 后，再创建对应字段
- 写记录前先判断字段可写性
- 只写存储字段
- 系统字段 / 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 基本心智模型
- Base 字段分三类
- 存储字段：真实存用户输入的数据，通常适合
+record-upsert写入，例如文本、数字、日期、单选、多选、人员、关联。附件字段例外：对 agent 而言，文件上传必须走+record-upload-attachment。 - 系统字段：平台自动维护，只读，典型包括创建时间、最后更新时间、创建人、修改人、自动编号。
- 计算字段：通过表达式或跨表规则推导，只读，典型包括 公式字段（formula） 和 查找引用字段（lookup）。
- 写记录前先判断字段类别 — 只有存储字段可直接写；公式 / lookup / 创建时间 / 更新时间 / 创建人 / 修改人 / 自动编号都应视为只读输出字段，不能拿来做
+record-upsert入参。 - Base 不只是存表数据，也能内建计算 — 用户提出“统计、比较、排名、文本拼接、日期差、跨表汇总、状态判断”等需求时，不能默认导出数据后手算；要先判断是否应通过
+data-query或公式字段在 Base 内完成。
分析路径决策
- 一次性分析 / 临时查询 → 优先
+data-query - 适合：分组统计、SUM / AVG / COUNT / MAX / MIN、条件筛选后聚合。
- 特征：要的是“这次算出来的结果”，不是把结果沉淀成表内字段。
- 长期复用的派生指标 / 行级计算结果 → 优先公式字段
- 适合：利润率、是否延期、剩余天数、分档标签、跨表汇总后的派生结果。
- 特征：要把结果长期显示在 Base 里，跟随记录自动更新。
- 显式要求 Lookup，或确实要按 source/select/where/aggregate 建模 → 用 lookup 字段
- 默认仍优先考虑 formula。lookup 只在用户明确要求、或更符合固定查找配置时使用。
- 原始记录读取 / 明细导出 →
+record-list / +record-get - 不要把
+record-list当分析引擎；它负责取明细，不负责聚合计算。
公式 / Lookup 专项规则
- 涉及 formula / lookup 时，先读 guide，再出命令
- formula：[
formula-field-guide.md](references/formula-field-guide.md) - lookup：[
lookup-field-guide.md](references/lookup-field-guide.md) - guide 先于创建命令
- 没读对应 guide 前，不要直接创建 formula / lookup 字段
- 读完 guide 后，再补齐对应 JSON 并创建字段
type=formula必须提供expressiontype=lookup必须提供from / select / where，必要时补aggregate- 公式字段优先于 lookup 字段
- 只要用户的诉求是“计算 / 条件判断 / 文本处理 / 日期差 / 跨表聚合 / 跨表筛选后取值”，默认优先尝试 formula。
- 只有用户明确说要 lookup，或配置天然更适合 lookup 四元组时，再走 lookup。
- 表名 / 字段名必须精确匹配
- 公式、lookup、data-query 中出现的表名 / 字段名，必须来自
+table-list/+table-get/+field-list的真实返回，禁止凭语义猜测改写。 - 先拿结构再写表达式
- 公式或 lookup 一律先获取相关表结构，再生成表达式 / 配置；不要直接凭用户口述拼字段名。
Workflow 专项规则
- 执行任何 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 枚举中复制准确的类型名称
- 创建前确认依赖信息
- 先通过
+table-list/+field-list获取真实的表名、字段名 - 禁止凭自然语言猜测表名/字段名填入 workflow 配置
核心规则
- 只使用原子命令 — 使用
+table-list / +table-get / +field-create / +record-upsert / +view-set-filter / +record-history-list / +base-get这类一命令一动作的写法，不使用旧聚合式+table / +field / +record / +view / +history / +workspace - 写记录前先读字段结构 — 先调用
+field-list获取字段结构，再读 [lark-base-shortcut-record-value.md](references/lark-base-shortcut-record-value.md) 确认各字段类型的写入值格式 - 写字段前先看字段属性规范 — 先读 [lark-base-shortcut-field-properties.md](references/lark-base-shortcut-field-properties.md) 确认
+field-create/+field-update的 JSON 结构 - 筛选查询按视图能力执行 — 先读 [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组合完成筛选读取 - 对记录进行分析（涉及"最高/最低/总计/平均/排名/比较/数量"等分析意图） — 先读 [lark-base-data-query.md](references/lark-base-data-query.md)，通过
+data-query进行数据筛选聚合的服务端计算 - 聚合分析与取数互斥 — 需要分组统计 / SUM / MAX / AVG / COUNT 时，必须使用
+data-query（服务端计算），禁止用+record-list拉全量记录再手动计算；反之，+data-query不返回原始记录，取数场景仍走+record-list / +record-get - 所有
+xxx-list禁止并发调用 —+table-list / +field-list / +record-list / +view-list / +record-history-list / +role-list只能串行执行 - 批量上限 500 条/次 — 同一表建议串行写入，并在批次间延迟 0.5–1 秒
- 统一参数名 — 一律使用
--base-token，不使用旧--app-token - 遇到“公式 / 查找引用 / 派生指标 / 跨表计算”需求，优先走字段方案判断 — 先判断应建 formula / lookup 字段，还是只做一次性
+data-query - 公式、lookup、系统字段默认视为只读 — 除
+field-create / +field-update维护字段定义外，不要把这些字段作为记录写入目标 - 改名和删除按明确意图执行 —
+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 | 一命令一动作 | | 列表 / 获取仪表盘 | lark-cli base +dashboard-list / +dashboard-get | 原子命令 | | 创建 / 更新 / 删除仪表盘 | lark-cli base +dashboard-create / +dashboard-update / +dashboard-delete | 一命令一动作 | | 列表 / 获取仪表盘 Block | lark-cli base +dashboard-block-list / +dashboard-block-get | 原子命令 | | 创建 / 更新 / 删除仪表盘 Block