lark-base

Files (88)

• SKILL.md
• dashboard-block-data-config.md · references/
• examples.md · references/
• formula-field-guide.md · references/
• lark-base-advperm-disable.md · references/
• lark-base-advperm-enable.md · references/
• lark-base-base-copy.md · references/
• lark-base-base-create.md · references/
• lark-base-base-get.md · references/
• lark-base-dashboard-block-create.md · references/
• lark-base-dashboard-block-delete.md · references/
• lark-base-dashboard-block-get.md · references/
• lark-base-dashboard-block-list.md · references/
• lark-base-dashboard-block-update.md · references/
• lark-base-dashboard-block.md · references/
• lark-base-dashboard-create.md · references/
• lark-base-dashboard-delete.md · references/
• lark-base-dashboard-get.md · references/
• lark-base-dashboard-list.md · references/
• lark-base-dashboard-update.md · references/
• lark-base-dashboard.md · references/
• lark-base-data-query.md · references/
• lark-base-field-create.md · references/
• lark-base-field-delete.md · references/
• lark-base-field-get.md · references/
• lark-base-field-list.md · references/
• lark-base-field-search-options.md · references/
• lark-base-field-update.md · references/
• lark-base-field.md · references/
• lark-base-form-create.md · references/
• lark-base-form-delete.md · references/
• lark-base-form-get.md · references/
• lark-base-form-list.md · references/
• lark-base-form-questions-create.md · references/
• lark-base-form-questions-delete.md · references/
• lark-base-form-questions-list.md · references/
• lark-base-form-questions-update.md · references/
• lark-base-form-questions.md · references/
• lark-base-form-update.md · references/
• lark-base-form.md · references/
• lark-base-history.md · references/
• lark-base-record-delete.md · references/
• lark-base-record-get.md · references/
• lark-base-record-history-list.md · references/
• lark-base-record-list.md · references/
• lark-base-record-upload-attachment.md · references/
• lark-base-record-upsert.md · references/
• lark-base-record.md · references/
• lark-base-role-create.md · references/
• lark-base-role-delete.md · references/
• lark-base-role-get.md · references/
• lark-base-role-list.md · references/
• lark-base-role-update.md · references/
• lark-base-shortcut-field-properties.md · references/
• lark-base-shortcut-record-value.md · references/
• lark-base-table-create.md · references/
• lark-base-table-delete.md · references/
• lark-base-table-get.md · references/
• lark-base-table-list.md · references/
• lark-base-table-update.md · references/
• …and 28 more

SKILL.md (first lines)

# base

> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)。
> **执行前必做：** 执行任何 `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 配置

## 核心规则

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` |

From jonymei/lark-cli, MIT.

More from jonymei/lark-cli