Lark Base

Base

普通 Base 是数据容器，由一棵 Base Block 资源树和 Base 级配置组成。folder、table、docx、dashboard、workflow 都是 Block 类型；Advanced Permission / Role 是 Base 级配置，不属于 Block。Table 是其中承载业务数据的核心 Block。Workspace 是组织 Base 与 BaseApp 的外层容器；BaseApp（AppMode）通过 Page 和组件组织 Base 数据，不是 Base 的别名。

身份选择（优先）

操作 Base 优先使用 --as user；用户明确要求应用身份时使用 --as bot。权限失败按 lark-shared 以原身份修复 scope 或资源 ACL；只有用户明确同意更换操作者时才切换身份。

进入前必做：解析目标实体

开始操作前先确定 base_token 和目标实体类型；上下文已提供 <bitable> / <base_refer> 标签及资源 ID 时直接使用。其余情况按意图选择入口：

1. URL 或分享链接： lark-cli base +url-resolve --url '<url>' --as user。Base URL 根据返回的 resource_type / block_type 及 table_id、view_id、record_id、dashboard_id、workflow_id、docx_token、share_token 等坐标进入对应模块；BaseApp /app/ URL 返回 app_token，并在链接携带时返回 workspace_token 和 page_id。实体类型以解析结果为准。
2. Base 标题或关键词： lark-cli base +title-resolve --title '<keyword>' --as user。单一结果直接取得 base_token；多个候选结合标题、所有者和更新时间消歧，仍无法唯一确定时请用户选择。随后按下方 Base Block 资源模型定位目标实体。
3. 已有 Base 候选列表： 用户要列出已有 Base 候选，且需要按最近访问、owner、创建人、时间、类型等维度筛选/排序时，转 lark-cli drive +search --doc-types bitable --as user。按标题/关键词定位单个 Base 仍用 +title-resolve。常见候选列表命令：

• 最近访问：lark-cli drive +search --doc-types bitable --sort open_time --opened-since 3m --page-size 20 --as user
• 只列我拥有的：加 --mine；如果要列“我创建的”，用 --created-by-me。
• 从候选项拿到 URL 或 token 后，再用 +url-resolve 或 +base-get 进入 Base 业务命令。

1. BaseApp： 优先使用真实 /app/ URL；已有 workspace_token 时可用 +workspace-entity-list --type baseapp 定位。两者都没有时请用户补充应用链接或 Workspace，不按名称全局猜测 app_token。

读取 Base： Base 信息用 +base-get，资源目录按下方 Base Block 资源模型读取。

写入 Base： 创建新 Base 使用一次 +base-create --name <base-name> --table-name <table-name> --fields '<field-array>' 同时创建 Base、首表和 fields；+base-copy 复制整个 Base；Base 内资源统一按下方 Block 生命周期管理。

Base 模板中心

模板中心是公开的 Base 模板库，不是用户云空间里的已有 Base。用户想用现成模板创建新 Base，且没有指向已有对象的锚点（没有 Base URL、没有“我的/最近访问的表”、没有具体已存在的 Base 名）时，可读取 lark-base-template-center.md 查找模板中心模板；+template-categories 列出公开模板分类，+template-list 按分类列出公开模板，+template-search 按业务关键词搜索公开模板。

Base Block 资源模型

Base
├── Base Block 资源树
│   ├── Table Block
│   │   ├── Field schema
│   │   ├── Records / CellValue
│   │   ├── Views
│   │   └── Forms / Questions
│   ├── Dashboard Block（布局容器）
│   │   └── Dashboard 内部 Blocks（图表、指标卡、文本）
│   ├── Workflow Block
│   │   └── Workflow definition（title、status、steps 执行图）
│   ├── Docx Block → docx_token / lark-doc
│   └── Folder Block → 子 Block
└── Base 级配置
    └── Advanced Permission / Roles

每个 Base Block 都有 id、type、可修改的 name、所在 Folder 的 parent_id，并在同级目录中具有顺序。+base-block-list 是统一发现入口；+base-block-create 创建 Block，+base-block-rename 修改名称，+base-block-move 通过 --parent-id 调整目录并通过 --before-id / --after-id 调整顺序，+base-block-delete 删除 Block。类型专属内容再由对应模块命令处理。

创建时已经明确类型专属初始内容，可直接使用对应构造命令一次完成：Table 用 +table-create --fields，Dashboard 用 +dashboard-create 设置主题，Workflow 用 +workflow-create --json 提交完整定义；Folder 和 Docx 使用 +base-block-create。

Block 的 id 按类型直接作为对应模块坐标：

Table Block（The Core）

Table 本身是 Base Block，也是 Base 的核心数据存储层；Field、Record、View 和 Form 是 Table 内部对象，不是 Base Block。业务数据查询、写入、关联、统计和分析都从 Table 开始。先用 +table-list 定位 Table；字段名和目标已知的普通读取可直接进入 Record 命令，只有写入、筛选或关联等依赖字段类型/schema 的任务才补 +field-list。多表的 +field-list 可以并发执行。基础的 Record / CellValue 读写直接按下方路径；reference 只承载高级分析、完整协议和边界细节。

读取 Table： +table-list 定位表，+table-get 读取详情。Table 专属复制使用 +table-copy，异步状态用 +table-copy-status；schema 和 records 由下方内部对象操作。

Table 下的大多数更新通过异步链路生效，接口成功返回后立即读取可能暂时看不到最新状态。优先以写入成功响应作为操作结果；任务必须确认最终状态时，先完成本轮相关变更，再统一读取验收，避免逐项写后立即读回。

Field

Field 定义列 schema。field_id 是稳定列标识，name 是可修改的展示名称；Formula、Lookup、Link、Select 等属于 Field 类型或能力。

读取 Field： +field-list / +field-get / +field-search-options。写入 Field： 已有 Table 中创建多个字段时，优先向一次 +field-create --json 传字段对象数组；单字段更新和删除用 +field-update / +field-delete。创建和更新分别读取 field-create / field-update，由命令文档继续路由 Field JSON、Formula 和 Lookup 协议。字段插件 用于扩展基础字段能力：按同一行其他字段内容触发 LLM 生成，并写回已有目标字段；当前已确认目标字段支持文本、单选、数字，配置或触发前先读 field-extension。

Record

Record 是 Table 中的一行数据，包含该记录在各个 Field 下的 CellValue。系统 record_id 是表内稳定、非空且唯一的主键，Table 的主字段只是展示字段。

1. 读取记录或单元格

• 已知若干个 record_id：+record-get --record-id <id1> --record-id <id2>
• 关键词搜索：+record-search --keyword <text> --search-field <field>；至少指定一个搜索字段。
• 其余读取：+record-list；结构化条件和排序分别用 --filter-json / --sort-json。

行数较大、需要服务端谓词下推时，--filter-json 使用 tuple condition；最常用的筛选与完整日期范围写法：

{
  "logic": "and", // 全部条件成立；任一条件成立改为 "or"
  "conditions": [
    ["状态", "intersects", ["进行中", "暂停"]], // Select 命中任一选项
    ["标题", "intersects", "urgent"], // 文本包含
    ["备注", "non_empty"], // 非空；判断为空改用 "empty"，两者都不传 value
    ["金额", ">=", 100], // 数字比较；支持 ==、!=、>、>=、<、<=
    ["关联项目", "intersects", [{ "id": "recxxx" }]], // Link 包含目标记录
    ["业务日期", "==", "ExactDate(2026-08-07)"], // 具体一天：按 Base 时区匹配 2026-08-07 当天
    ["发生时间", ">", "ExactDate(2024-01-31 23:59:59.999)"], // 日期不支持 >=；用 > 前一天最后一毫秒表达含当天的下界
    ["发生时间", "<", "ExactDate(2024-03-01 00:00:00)"] // 2024 年 2 月范围上界：小于 3 月 1 日零点
  ]
}

完整操作符和各字段取值结构读取 Filter 条件结构。

所有读取都重复传 --field-id 做最小字段投影，并统一写入 NDJSON artifact：--format ndjson --output <path>.ndjson。每行是一条 Record JSON，stdout 摘要包含 records_count 和 has_more 用于分页判断。

# Example: 行数较大时先筛选 Status 包含 Doing 的记录，再导出 20 条作为局部预览
lark-cli base +record-list \
  --base-token <base_token> --table-id <table_id> \
  --filter-json '{"logic":"and","conditions":[["Status","intersects",["Doing"]]]}' \
  --field-id Name --field-id Status --field-id Score --limit 20 \
  --format ndjson --output ./records-preview.ndjson --as user

PREVIEW_ROWS=5
head -n "$PREVIEW_ROWS" ./records-preview.ndjson
tail -n "$PREVIEW_ROWS" ./records-preview.ndjson

预计记录数少于 500 行时，建议不做谓词下推，直接拉取到本地用 jq 或 Python 处理；行数较大时可用 --filter-json 下推可表达的条件，正则、派生等无法下推的条件继续在本地处理。

# jq：对服务端筛选结果追加名称格式筛选，再投影必要字段
jq -c 'select((.Name // "") | test("^Task-[0-9]+$")) | {record_id, Name}' ./records-preview.ndjson

# Python：按行读取并做简单汇总
python3 - <<'PY'
import json

with open("records-preview.ndjson", encoding="utf-8") as stream:
    rows = (json.loads(line) for line in stream if line.strip())
    print(sum((row.get("Score") or 0) for row in rows))
PY

--limit 的缺省值是 2000，最大值是 2000，通常无需手动指定 limit 参数；支持 --offset 参数；只有 has_more=false 且查询范围符合问题时，才能当作完整结果。大表完整读取、View 范围读取、复杂 JOIN、集合/多值、时序、语义或专业统计分析时，读取 Record 查询与分析 SOP。

2. 新增记录或更新记录单元格

一条 Record 是 {字段名或 field_id: CellValue}，常见 CellValue：

{
  "标题": "Created from shortcut", // text: string
  "官网": "[官网](https://example.com)", // text(url): 裸 URL 或 Markdown link
  "联系电话": "13800000000", // text(phone): 合法电话号码字符串
  "邮箱": "owner@example.com", // text(email): 合法邮箱字符串
  "单选": ["Todo"], // select: array<string>；单选时数组最多一个值；
  "标签": ["高优", "外部依赖"], // 多选 select: array<string>；必须是当前字段存在的选项；
  "工时": 8, // number: double，不经过格式化的纯数字
  "带时区时间": "2026-03-24T10:00:00+08:00", // datetime：带时区，遵循传入的时区
  "不带时区时间": "2026-03-24 10:00", // datetime：不带时区，自动按当前 Base 时区转换
  "毫秒时间戳": 1774317600000, // datetime：也支持 Unix 毫秒时间戳
  "已完成": false, // checkbox: boolean
  "负责人": [{ "id": "ou_123" }], // user(multiple=false): 数组最多一个元素
  "协作人": [{ "id": "ou_123" }, { "id": "ou_456" }], // user(multiple=true): 数组可包含多个元素
  "群聊": [{ "id": "oc_123" }, { "id": "oc_456" }], // group_chat(multiple=true)