lark-base · diff

v1.2.4 to v1.2.23

248 added, 138 removed. Audit A to A.

---
name: lark-base
- version: 1.2.4
- description: "飞书多维表格(Base)操作:建表、字段、记录、视图、统计、公式/lookup、表单、仪表盘、workflow、角色权限;遇到 Base/多维表格/bitable 或 /base/ 链接时使用。文件导入/导出转 lark-drive,认证/授权转 lark-shared。"
+ version: 1.2.23
+ description: "飞书多维表格(Base)操作:建表、字段、记录、视图、统计、公式/lookup、表单、仪表盘、应用模式(BaseApp/AppMode 页面与组件)、Workspace 目录、workflow、角色权限、模板中心(多维表格模板分类/列表/搜索);遇到 Base/多维表格/bitable、BaseApp/AppMode、/base/ 或 /app/ 链接时使用。BaseApp 不走 lark-apps;文件导入/导出转 lark-drive,认证/授权转 lark-shared。"
metadata:
requires:
bins: ["lark-cli"]
cliHelp: "lark-cli base --help"
---
<!-- cowork-exec-note -->
> **⚙️ Cowork / Claude Desktop 执行环境说明(自动注入)**
>
> 本技能依赖本地 `lark-cli`(`@larksuite/cli`,可用 `command -v lark-cli` 定位)及其 `~/.lark-cli` 登录态(应用密钥存于 macOS keychain)。
>
> 在 Cowork 中运行任何 `lark-cli` 命令时,**必须在本地 macOS 上执行**(使用 Desktop Commander 的 `start_process` / `interact_with_process`,或其它本地 shell 工具),**不要用隔离的 Linux 沙箱** `mcp__workspace__bash`——沙箱里没有 lark-cli、也读不到 keychain。
> 执行前确保 npm 全局 bin 目录(`npm prefix -g` 输出目录下的 `bin`)在 PATH 中。
>
> (在 Claude Code 中可忽略本说明,lark-cli 在本机 shell 直接可用。)
- # base
+ # 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 的别名。
- 使用本 skill:
+ ## 身份选择(优先)
- - 用户明确提到 Base / 多维表格 / bitable,或给出 `/base/` 链接。
- - 用户要在 Base 内建表、改表、管理字段、写记录、查记录、配视图。
- - 用户要在 Base 内做公式字段、lookup 字段、跨表计算、派生指标、筛选聚合、TopN、统计分析。
- - 用户要管理 Base 表单、仪表盘、workflow、高级权限或角色。
- - 用户要把旧 Base 聚合式命令或旧写法迁移到当前 `lark-cli base +...` shortcut。
+ 操作 Base 优先使用 `--as user`;用户明确要求应用身份时使用 `--as bot`。权限失败按 `lark-shared` 以原身份修复 scope 或资源 ACL;只有用户明确同意更换操作者时才切换身份。
- 不要使用本 skill:
+ ## 进入前必做:解析目标实体
- - 只是认证、初始化配置、切换身份、处理 scope 或权限授权恢复,转 `lark-shared`。
- - 把本地文件导入成 Base,或将 Base 导出为本地文件,转 `lark-drive`。
- - 泛化数据分析、字段设计、公式讨论,但没有 Base/多维表格上下文。
+ 开始操作前先确定 `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 业务命令。
+ 4. **BaseApp:** 优先使用真实 `/app/` URL;已有 `workspace_token` 时可用 `+workspace-entity-list --type baseapp` 定位。两者都没有时请用户补充应用链接或 Workspace,不按名称全局猜测 `app_token`。
- - Base 业务操作只使用 `lark-cli base +...` shortcut,不使用旧聚合式 `+table / +field / +record / +view / +history / +workspace`。
- - 执行 update 前必须先查当前 shortcut 的 `--help` 或对应 reference。若命令要求完整配置,首次请求必须基于可信的当前配置执行 read-modify-write:只修改用户明确指定的内容,保留其他仍适用的可写配置,并按命令要求的结构提交。若命令支持局部/delta update,按其契约提交最小合法 payload;不得以不完整请求试错补参。
- - Base CLI/OpenAPI 当前不支持视图行高、冻结列、列宽等 UI-only 外观设置。遇到这类需求,说明能力边界并停止,不要猜测未文档化参数或改走 raw API。
- - 本地文件与 Base 之间的导入/导出转 `lark-drive`,具体格式、参数、路径限制和仅结构导出规则由 `lark-drive` 负责;导入完成后再回到 Base 命令。
- - 在线复制 Base 使用 `+base-copy`,不要绕行导出/导入。
- - 认证、初始化、scope、身份切换、权限不足恢复属于 `lark-shared`;Base 文档只保留会影响 Base 路径选择的权限规则。
+ **读取 Base:** Base 信息用 `+base-get`,资源目录按下方 Base Block 资源模型读取。
- ## 先获取 Base Token 和所需 ID
+ **写入 Base:** 创建新 Base 使用一次 `+base-create --name <base-name> --table-name <table-name> --fields '<field-array>'` 同时创建 Base、首表和 fields;`+base-copy` 复制整个 Base;Base 内资源统一按下方 Block 生命周期管理。
- 进入任何需要目标 Base 的 shortcut 前,必须先拿到可用的 `base_token`,以及当前任务需要的 `table_id` / `view_id` / `record_id` / `form_id` / `dashboard_id` / `workflow_id` 等真实 ID;不要把完整 URL、wiki token、workspace token 或孤立 raw token 直接当作 `--base-token`。
+ ## Base 模板中心
- - 用户输入 URL 或分享链接:先运行 `lark-cli base +url-resolve --url "<url>" --as user`,用返回的 `base_token` 和相关 ID 继续后续命令。
- - Base/Wiki URL 的 `table=` query 参数实际表示当前选中的顶层 block,可能是数据表、仪表盘或 workflow;不要按参数名自行当成 `table_id`。以 `+url-resolve` 返回的 `block_type` 以及 `table_id` / `dashboard_id` / `workflow_id` 为准;`selection_source=url_query` 只说明 URL 当前选中了该 block,不代表它覆盖用户明确点名的目标。若用户点名的 dashboard 与 `block_name` 不一致,先用 `+dashboard-list` 按名称匹配;若只返回中性 `block_id`,按 hint 用 `+base-block-list` 确认类型。
- - 用户输入 Base 标题、关键词或不确定名称:先运行 `lark-cli base +title-resolve --title "<keyword>" --as user`;`--title` 传入标题中的短关键词,不超过 30 个字符;过长标题先取最有区分度的短关键词;多候选时先让用户消歧,不要猜。
- - 文档嵌入 Base 标签:直接读取 `<bitable>` / `<base_refer>` 的 `token` 作为 `--base-token`,`table-id` 作为 `--table-id`,`view-id` 作为 `--view-id`;孤立 raw token 不走 `+url-resolve`。
- - 仍无法定位且用户不是要新建 Base 时,先反问用户要操作哪一个 Base;用户要新建时才用 `+base-create`。
+ 模板中心是公开的 Base 模板库,不是用户云空间里的已有 Base。用户想用现成模板创建新 Base,且没有指向已有对象的锚点(没有 Base URL、没有“我的/最近访问的表”、没有具体已存在的 Base 名)时,可读取 [lark-base-template-center.md](references/lark-base-template-center.md) 查找模板中心模板;`+template-categories` 列出公开模板分类,`+template-list` 按分类列出公开模板,`+template-search` 按业务关键词搜索公开模板。
- ## 快速路由
+ ## Base Block 资源模型
- | 用户目标 | 优先命令 | 何时读 reference |
- |---|---|---|
- | 查 Base 本体 | `+base-get` | 用返回确认 Base 名称、owner、权限和可继续操作的 token |
- | 创建/复制 Base | `+base-create` / `+base-copy` | 新建时强烈推荐用 `--table-name` + `--fields` 同时配置新 Base 里唯一一个初始数据表的 name 和 schema;写入后报告新 Base 标识和 `permission_grant` |
- | Base 文件导入/导出 | 转 `lark-drive` | 文件格式、参数、路径限制和仅结构导出规则由 `lark-drive` 负责;在线复制走 `+base-copy` |
- | 查看 Base 内资源目录 | `+base-block-list` | 想先了解一个 Base 里有哪些 table/docx/dashboard/workflow/folder 时优先用它;返回 ID 关系和 fewshot 看 `--help` |
- | 管理 Base 内资源目录 | `+base-block-create/move/rename/delete` | 创建或整理 Base 直接管理的 folder/table/docx/dashboard/workflow;资源内容继续用对应命令 |
- | 管理数据表 | `+table-list/get/create/update/delete` | 处理 table 的列出、详情、创建、重命名和删除 |
- | 复制 Base 内单张数据表 | `+table-copy` / `+table-copy-status` | 默认只复制结构;只有用户明确要求复制全表、数据、行或记录时才传 `--range all`;异步任务按返回的 `task_id` 查询或续等 |
- | 列/查/删字段 | `+field-list/get/delete/search-options` | 写入前用 list/get 确认字段类型、选项、ID;删除前确认目标字段 |
- | 创建/更新字段 | `+field-create` / `+field-update` | 必读 [lark-base-field-json.md](references/lark-base-field-json.md);公式读 [formula-field-guide.md](references/formula-field-guide.md);lookup 读 [lookup-field-guide.md](references/lookup-field-guide.md);命令细节读 [lark-base-field-create.md](references/lark-base-field-create.md) / [lark-base-field-update.md](references/lark-base-field-update.md) |
- | 读记录明细 | `+record-get` / `+record-list` / `+record-search` | 涉及筛选、排序、Top/Bottom N、聚合、多表关联、全局结论时读 [lark-base-data-analysis-sop.md](references/lark-base-data-analysis-sop.md) |
- | 写记录 | `+record-upsert` / `+record-batch-create` / `+record-batch-update` | 必读 [lark-base-record-upsert.md](references/lark-base-record-upsert.md) / [lark-base-record-batch-create.md](references/lark-base-record-batch-create.md) / [lark-base-record-batch-update.md](references/lark-base-record-batch-update.md) 和 [lark-base-cell-value.md](references/lark-base-cell-value.md) |
- | 附件字段 | `+record-upload-attachment` / `+record-download-attachment` / `+record-remove-attachment` | 附件不要伪造成普通 CellValue;上传走本地文件,下载/删除按 file token 或字段定位 |
- | 删除记录 / 分享记录链接 / 历史 | `+record-delete` / `+record-share-link-create` / `+record-history-list` | 删除前确认 record;分享链接最多 100 条;历史读 [lark-base-record-history-list.md](references/lark-base-record-history-list.md),只查单条记录,不做整表审计 |
- | 管理视图 | `+view-*` | `+view-set-filter` 读 [lark-base-view-set-filter.md](references/lark-base-view-set-filter.md)(filter 条件结构见公共协议 [lark-base-filter-condition.md](references/lark-base-filter-condition.md));其余配置先 get 现状,再按返回结构更新 |
- | 一次性聚合统计 | `+data-query` | 必读 [lark-base-data-analysis-sop.md](references/lark-base-data-analysis-sop.md) 和入口 [lark-base-data-query-guide.md](references/lark-base-data-query-guide.md);完整 DSL 再读 [lark-base-data-query.md](references/lark-base-data-query.md) |
- | 公式字段 | `+field-create/update --json '{"type":"formula",...}'` | 必读 [formula-field-guide.md](references/formula-field-guide.md),读后再加隐藏确认 flag `--i-have-read-guide` |
- | Lookup 字段 | `+field-create/update --json '{"type":"lookup",...}'` | 必读 [lookup-field-guide.md](references/lookup-field-guide.md),读后再加隐藏确认 flag `--i-have-read-guide` |
- | 表单提交 | `+form-submit` | 先读 [lark-base-form-detail.md](references/lark-base-form-detail.md) 获取题目、filter 和附件所需 `base_token`;提交 JSON 读 [lark-base-form-submit.md](references/lark-base-form-submit.md) |
- | 表单题目创建/更新 | `+form-questions-create` / `+form-questions-update` | Base 内表单按 table 管理;先确定并复用真实 `table_id`。读 [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);题目显隐条件 `visible_rule` 结构见公共协议 [lark-base-filter-condition.md](references/lark-base-filter-condition.md) |
- | Base 内表单管理 | `+form-list/get/create/update/delete` / `+form-questions-list/delete` | 缺少或不确定归属时,先用 `+table-list` 或 `+base-block-list` 取得真实 `table_id`;这些命令使用 `--base-token + --table-id` 并在整个工作流中复用同一 `table_id`,删除前确认目标表单 |
- | 分享表单详情 | `+form-detail --share-token <share_token>` | 只接受表单分享链接里的 `share_token`,不要传 `--base-token` / `--form-id`;提交前读 [lark-base-form-detail.md](references/lark-base-form-detail.md) |
- | 仪表盘与组件 | `+dashboard-*` / `+dashboard-block-*` | 提到图表/看板/block 时先读 [lark-base-dashboard.md](references/lark-base-dashboard.md);组件 `data_config` 读 [dashboard-block-data-config.md](references/dashboard-block-data-config.md);读取一个或多个图表计算结果用 `+dashboard-block-get-data` |
- | Workflow | `+workflow-*` | 创建/更新或理解 steps 时读入口 [lark-base-workflow-guide.md](references/lark-base-workflow-guide.md) 和 steps JSON SSOT [lark-base-workflow-schema.md](references/lark-base-workflow-schema.md);list/get/enable/disable 只处理 workflow ID 与启停状态 |
- | 高级权限与角色 | `+advperm-*` / `+role-*` | 角色操作先读入口 [lark-base-role-guide.md](references/lark-base-role-guide.md);角色 create/update 或解读完整配置再读权限 JSON SSOT [role-config.md](references/role-config.md);系统角色不可删除;关闭高级权限会影响自定义角色 |
+ ```text
+ 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 心智模型
+ 每个 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。类型专属内容再由对应模块命令处理。
- - Base 曾用名 Bitable;返回字段、错误或旧文档里的 `bitable` 多为历史兼容,不代表应改走裸 API 或另一套命令。
- - `+base-block-list` 是查看一个 Base 内资源目录的新入口:它列出这个 Base 直接管理的 `folder/table/docx/dashboard/workflow`,适合先判断 Base 里有什么,再决定走 table、dashboard、workflow 或 docx 命令。
- - `base-block` 只负责资源目录管理,包括创建资源、移动到 folder、重命名和删除;具体资源内容仍走 table/dashboard/workflow 命令。
- - 新建 Base 时,强烈推荐一次性执行 `lark-cli base +base-create --name "<base>" --table-name "<table>" --fields '<field-json-array>'`,同时配置新 Base 里唯一一个初始数据表的 name 和 schema;使用 `--fields` 前先读 [lark-base-field-json.md](references/lark-base-field-json.md) 或复用 `+field-create` 的字段 JSON 形状,不要猜字段属性。
- - `+base-create` 不传 `--table-name` 和 `--fields` 时,会创建一个默认 schema 的初始数据表。
- - `+table-copy` 的安全默认值是只复制表结构;用户没有明确要求记录时省略 `--range`,明确要求包含记录时才传 `--range all`。`--table-id` 可直接使用当前 Base 中的表 ID 或表名。
- - 表、字段、视图、workflow、dashboard block 的名称和 ID 必须来自真实返回,不要凭用户口述猜。
- - 存储字段可写;系统字段、`formula`、`lookup` 只读;附件字段走专用 attachment 命令。
- - 一次性原始记录查询优先用 `+record-list` / `+record-search` 的 filter/sort;聚合分析优先用 `+data-query`;需要长期显示在表中时,才新增 `formula` / `lookup` 字段。
- - `formula` 适合常规计算、条件判断、文本/日期处理和长期派生指标;`lookup` 适合明确的跨表查找、筛选后取值或聚合引用。
- - 写入、分析、公式、lookup、workflow、dashboard 前,先读取真实结构:表、字段、视图、关联表和 dashboard block 名称都以命令返回为准。
- - 跨表场景必须读取目标表结构;link 单元格中的关联 `record_id` 只是连接键,最终回答要回查并展示用户可读字段。
+ 创建时已经明确类型专属初始内容,可直接使用对应构造命令一次完成:Table 用 `+table-create --fields`,Dashboard 用 `+dashboard-create` 设置主题,Workflow 用 `+workflow-create --json` 提交完整定义;Folder 和 Docx 使用 `+base-block-create`。
- ## 身份与权限降级
+ Block 的 `id` 按类型直接作为对应模块坐标:
- - 默认显式使用 `--as user` 操作用户资源;只有用户明确要求应用身份时,才直接用 `--as bot`。
- - `+table-copy --wait` 提交成功后会在 stderr 打印完整 `task_id`;若进程被 Ctrl-C 终止,可用该 ID 和原身份执行 `+table-copy-status` 续查,不要重新提交复制。
- - user 身份报 scope/授权不足,或错误中包含 `missing_scopes` / `hint`,先转 `lark-shared` 做用户授权恢复,不要直接降级 bot。
- - user 身份报资源级无访问且无授权恢复提示时,才可用 `--as bot` 重试一次;bot 仍失败就停止重试并按权限错误处理。
- - `91403` 或明确不可访问错误不要循环换身份重试。
- - `+base-create` / `+base-copy` 若用 bot 身份执行,关注返回中的 `permission_grant`,并把用户是否可打开新 Base 告知用户。
+ | Block type | 模块坐标与内部内容 |
+ |---|---|
+ | `table` | `id` 即 `table_id`;内部包含 Field、Record、View 和 Form |
+ | `dashboard` | `id` 即 `dashboard_id`;内部包含图表、指标卡和文本等 Dashboard 组件 |
+ | `workflow` | `id` 即 `workflow_id`;内部包含 title、status 和 steps 执行图 |
+ | `docx` | Block 另带 `docx_token`;正文由 `lark-doc` 处理 |
+ | `folder` | `id` 是目录 Block ID,也可作为 `--parent-id`;只组织子 Block |
- ## 查询与统计规则
+ ## Table Block(The Core)
- 涉及查询、统计或判断结论时,先阅读 [lark-base-data-analysis-sop.md](references/lark-base-data-analysis-sop.md),并遵守:
+ Table 本身是 Base Block,也是 Base 的核心数据存储层;Field、Record、View 和 Form 是 Table 内部对象,不是 Base Block。业务数据查询、写入、关联、统计和分析都从 Table 开始。先用 `+table-list` 定位 Table;字段名和目标已知的普通读取可直接进入 Record 命令,只有写入、筛选或关联等依赖字段类型/schema 的任务才补 `+field-list`。多表的 `+field-list` 可以并发执行。基础的 Record / CellValue 读写直接按下方路径;reference 只承载高级分析、完整协议和边界细节。
- 1. `+record-list` 的默认页、固定 `--limit` 和本地 `jq` 只能证明已读取范围内的事实,不能直接支撑全局最值、全量计数、Top/Bottom N、异常识别或分组结论。
- 2. 能由 Base 表达的筛选、排序、投影、聚合、分组和限制,应在 Base 云端查询能力中执行;不要先拉原始记录到本地上下文再手工筛选排序。
- 3. `has_more=true` 或等价分页信号表示当前结果不是全量;除非用户只要样例/前 N 条,不能基于该页回答全局问题。
- 4. 多表查询必须先确认关系字段和连接键;link 单元格里的 `record_id` 是关系键,不是用户可读答案。
- 5. 最终答案必须能追溯到真实表、真实字段、查询范围、筛选/排序/聚合条件和必要的连接键。
- 6. 一次性原始记录查询优先用 `+record-list` / `+record-search` 的 filter/sort;聚合分析优先用 `+data-query`;要把结果长期显示在表里,才考虑新增 `formula` / `lookup` 字段。
- 7. `+data-query` 可返回聚合结果或维度字段行,但维度行按字段组合去重且不返回 `record_id`;需要逐条记录、记录定位或完整行级字段时,再用 `+record-list` / `+record-search` / `+record-get` 回查。
+ **读取 Table:** `+table-list` 定位表,`+table-get` 读取详情。Table 专属复制使用 `+table-copy`,异步状态用 `+table-copy-status`;schema 和 records 由下方内部对象操作。
- ## 写入前置规则
+ Table 下的大多数更新通过异步链路生效,接口成功返回后立即读取可能暂时看不到最新状态。优先以写入成功响应作为操作结果;任务必须确认最终状态时,先完成本轮相关变更,再统一读取验收,避免逐项写后立即读回。
- - 优先用写入返回确认结果;返回信息不足或任务明确要求核验时,再读回。
- - 写记录前先读字段结构;只写存储字段。系统字段、附件字段、`formula`、`lookup` 不作为普通记录写入目标。
- - 附件上传、下载、删除走专用 `+record-*-attachment` 命令。
- - 写字段前先读 [lark-base-field-json.md](references/lark-base-field-json.md);请求字段类型不在 reference 已支持类型目录中时,说明当前 CLI 不支持并停止,不要猜测未注册的字段 JSON、service 或 schema,也不要用其他字段类型冒充;涉及 `formula` / `lookup` 时必须读 [formula-field-guide.md](references/formula-field-guide.md) / [lookup-field-guide.md](references/lookup-field-guide.md)。
- - 表名、字段名、视图名、workflow 配置中的名称必须来自真实返回;跨表场景还要读取目标表结构。
- - 删除、角色更新、字段更新、表单提交(`+form-submit`)等高风险操作遵循 CLI 的 confirmation gate,必须带 `--yes`;目标不明确时先用 get/list 消歧。
- - 批量写入单批最多 200 条;连续写同一表时串行执行,遇到 `1254291` 按短暂等待后重试处理。
- - `select` 字段只支持写入字段中已有的选项;构造 CellValue 前先用 `+field-list` 或 `+field-search-options` 确认目标选项存在。
+ ### Field
- ## 表单与视图细节
+ Field 定义列 schema。`field_id` 是稳定列标识,`name` 是可修改的展示名称;Formula、Lookup、Link、Select 等属于 Field 类型或能力。
- - Base 内表单 list/get/create/update/delete 和题目管理都属于具体数据表:第一个管理命令前必须已有归属明确的真实 `table_id`;缺失或归属不明确时才用 `+table-list` 或 `+base-block-list` 定位,已有真实 ID 时直接复用。后续管理命令始终传同一 `base_token + table_id`。`+form-detail` 是分享表单入口,标识域不同,只使用 `share_token`。
- - 表单问题由数据表字段承载,question `id` 就是 `field_id`。创建问题前先 `+form-questions-list`;除非用户明确要求同名的独立问题,否则标题已存在时优先用 `+form-questions-update` 修改必填状态、标题或描述,不要先创建同名问题再删除旧问题。
- - `+form-questions-delete` 会删除承载问题的数据表字段。主字段问题不可删除;不要把主字段 ID 放入 `--question-ids`,需要修改时使用 `+form-questions-update`。
- - `+form-submit` 是高风险写操作,必须带 `--yes` 确认;调用前必须先跑 `+form-detail`,读取 `questions[].type`、`required`、`filter` 和附件场景需要的 `base_token`;不要填写被 filter 隐藏的问题。
- - `+form-questions-update` 是题目配置全量覆盖,不是 patch;未传字段会回落默认值,传空字符串 / `null` / 空数组会直接写入空或清空。更新前先 `+form-questions-list` 读取当前题目,把要保留的 `title` / `description` / `required` / `option_display_mode` / `visible_rule` 等字段带回请求。
- - 表单附件不要写进 `fields`,放在 `--json.attachments`;提交附件时必须同时传表单所属 Base 的 `--base-token`。
- - `+view-set-filter` 是唯一保留的 view reference;sort/group/card/timebar/visible-fields 这类配置先用对应 get 命令读现状,保留未修改字段,只替换用户要求变更的配置。
- - 视图适合持久化、共享和 UI 复用;一次性筛选/排序可先用 `+record-list` / `+record-search` 的 filter/sort 验证结果,再按需要沉淀为持久视图。
+ **读取 Field:** `+field-list` / `+field-get` / `+field-search-options`。**写入 Field:** 已有 Table 中创建多个字段时,优先向一次 `+field-create --json` 传字段对象数组;单字段更新和删除用 `+field-update` / `+field-delete`。创建和更新分别读取 [field-create](references/lark-base-field-create.md) / [field-update](references/lark-base-field-update.md),由命令文档继续路由 Field JSON、Formula 和 Lookup 协议。`字段插件` 用于扩展基础字段能力:按同一行其他字段内容触发 LLM 生成,并写回已有目标字段;当前已确认目标字段支持文本、单选、数字,配置或触发前先读 [field-extension](references/lark-base-field-extension.md)。
- ## Dashboard / Workflow / Role
+ ### Record
- - Dashboard 的复杂点是 block 的 `data_config`,不是 list/get/create/delete 命令参数。创建或更新 block 前先读 [dashboard-block-data-config.md](references/dashboard-block-data-config.md),组件必须串行创建;`+dashboard-arrange` 是服务端智能布局,仅在用户明确要求重排/美化、或对本次会话从零新建的仪表盘做收尾整理时执行。`+dashboard-block-get-data` 读取图表最终计算结果,不返回 block 名称、类型、布局或 `data_config`;需要元数据先用 `+dashboard-block-get`。
- - Dashboard shortcut 不支持指定组件的 `x/y/w/h`、精确位置或尺寸,不能把 `+dashboard-arrange` 静默当作等价实现。用户只要求一般性重排/美化时可执行一次智能重排;用户要求精确结果时先说明限制并询问是否接受自适应布局,接受后才执行。不要探测 raw `lark-cli api`、源码或未公开布局参数。
- - 创建接口成功返回即表示写入成功;只有结果不确定时才额外执行一次 `+dashboard-get` 或 `+dashboard-block-list`。不要仅为确认创建而逐组件调用 `+dashboard-block-get-data`。
- - 用户要读取多个组件的计算结果时,先完整列出组件(`+dashboard-block-list --page-size 100`;若 `has_more=true`,继续把返回的 `page_token` 传给 `--page-token`,直到 `has_more=false`),再按 [lark-base-dashboard-block-get-data.md](references/lark-base-dashboard-block-get-data.md) 在一个 shell 工具调用内串行读取;不要把每个 block 拆成独立模型轮次。
- - Workflow 的复杂点是 `steps` 结构。创建、更新或解释完整 workflow 时读入口 [lark-base-workflow-guide.md](references/lark-base-workflow-guide.md) 和 steps JSON SSOT [lark-base-workflow-schema.md](references/lark-base-workflow-schema.md);enable/disable/list 只需确认 workflow ID、当前启停状态和用户意图。
- - Role 的复杂点是权限 JSON。角色操作先读入口 [lark-base-role-guide.md](references/lark-base-role-guide.md);`+role-create` 只支持自定义角色;`+role-update` 是 delta merge;角色 create/update 或解读完整配置时读权限 JSON SSOT [role-config.md](references/role-config.md)。`+role-delete` 只适用于自定义角色,系统角色不可删除;删除角色和关闭高级权限前必须确认目标和影响。
+ Record 是 Table 中的一行数据,包含该记录在各个 Field 下的 CellValue。系统 `record_id` 是表内稳定、非空且唯一的主键,Table 的主字段只是展示字段。
- ## 常见恢复
+ #### 1. 读取记录或单元格
- | 错误 / 现象 | 恢复动作 |
- |---|---|
- | `param baseToken is invalid` / `base_token invalid` | 检查是否把 wiki token、workspace token 或完整 URL 当成了 `--base-token`;按入口规则重新获取真实 `base_token` |
- | `not found` 且输入来自 Wiki 链接 | 优先检查是否把 wiki token 当成 base token,不要立刻改走裸 API |
- | `1254045` 字段名不存在 | 重新 `+field-list`,使用真实字段名或字段 ID;注意空格、大小写和跨表字段 |
- | `1254015` 字段值类型不匹配 | 先 `+field-list`,再按 [lark-base-cell-value.md](references/lark-base-cell-value.md) 构造 CellValue |
- | `Invalid discriminator value`(字段写入缺 `type`) | 按完整提交规则读取当前字段,只改目标内容后提交;不要只补 `type` 重试 |
- | filter 报 `value of type array` / `Only string values` | 用 record/view 的 tuple `--filter-json`(非 `+data-query` 对象型),value 按字段 type 选标量或数组;见 [lark-base-view-set-filter.md](references/lark-base-view-set-filter.md) |
- | 日期 / 人员 / 超链接字段报格式错误 | 日期用 `YYYY-MM-DD HH:mm:ss`;人员用 `[{ "id": "ou_xxx" }]`;超链接用 URL 或 markdown link 字符串 |
- | formula / lookup 创建失败 | 先读 [formula-field-guide.md](references/formula-field-guide.md) / [lookup-field-guide.md](references/lookup-field-guide.md),再按 guide 重建请求 |
- | `ignored_fields` / `READONLY` | 移除只读字段,只写存储字段 |
- | `1254104` | 批量超过 200,分批调用 |
- | `1254291` | 并发写冲突,串行写入并在批次间短暂等待 |
- | `91403` | 无权限访问该 Base,按 `lark-shared` 权限流程处理,不要盲目重试 |
+ - 已知若干个 `record_id`:`+record-get --record-id <id1> --record-id <id2>`
+ - 关键词搜索:`+record-search --keyword <text> --search-field <field>`;至少指定一个搜索字段。
+ - 其余读取:`+record-list`;结构化条件和排序分别用 `--filter-json` / `--sort-json`。
- ## 保留 Reference
+ 行数较大、需要服务端谓词下推时,`--filter-json` 使用 tuple condition;最常用的筛选与完整日期范围写法:
- - [lark-base-data-analysis-sop.md](references/lark-base-data-analysis-sop.md):查询/统计/全局结论的选路 SOP
- - [lark-base-data-query-guide.md](references/lark-base-data-query-guide.md) / [lark-base-data-query.md](references/lark-base-data-query.md):聚合查询入口 fewshot 与 DSL SSOT;`+data-query` 的 `filters` 结构是独立对象 DSL,不使用公共 tuple filter 协议
- - [lark-base-cell-value.md](references/lark-base-cell-value.md):记录 CellValue 构造
- - [lark-base-field-json.md](references/lark-base-field-json.md):字段 JSON 构造
- - [formula-field-guide.md](references/formula-field-guide.md) / [lookup-field-guide.md](references/lookup-field-guide.md):公式与 lookup 字段
- - [lark-base-field-create.md](references/lark-base-field-create.md) / [lark-base-field-update.md](references/lark-base-field-update.md):字段创建/更新命令级补充
- - [lark-base-record-upsert.md](references/lark-base-record-upsert.md) / [lark-base-record-batch-create.md](references/lark-base-record-batch-create.md) / [lark-base-record-batch-update.md](references/lark-base-record-batch-update.md) / [lark-base-record-history-list.md](references/lark-base-record-history-list.md):记录写入 JSON 与历史返回解释
- - [lark-base-view-set-filter.md](references/lark-base-view-set-filter.md):视图筛选 JSON
- - [lark-base-filter-condition.md](references/lark-base-filter-condition.md):视图 filter、记录 `--filter-json`、表单 `visible_rule` 的 tuple 条件结构公共协议 SSOT;不适用于 `+data-query`
- - [lark-base-form-detail.md](references/lark-base-form-detail.md) / [lark-base-form-submit.md](references/lark-base-form-submit.md) / [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):表单详情、提交和复杂 JSON
- - [lark-base-dashboard.md](references/lark-base-dashboard.md) / [dashboard-block-data-config.md](references/dashboard-block-data-config.md) / [lark-base-dashboard-block-get-data.md](references/lark-base-dashboard-block-get-data.md):仪表盘、组件配置与图表结果协议
- - [lark-base-workflow-guide.md](references/lark-base-workflow-guide.md) / [lark-base-workflow-schema.md](references/lark-base-workflow-schema.md):workflow 入口与 steps JSON SSOT
- - [lark-base-role-guide.md](references/lark-base-role-guide.md) / [role-config.md](references/role-config.md):角色入口与权限 JSON SSOT
+ ```jsonc
+ {
+ "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 条件结构](references/lark-base-filter-condition.md)。
+
+ 所有读取都重复传 `--field-id` 做最小字段投影,并统一写入 NDJSON artifact:`--format ndjson --output <path>.ndjson`。每行是一条 Record JSON,stdout 摘要包含 `records_count` 和 `has_more` 用于分页判断。
+
+ ```bash
+ # 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` 下推可表达的条件,正则、派生等无法下推的条件继续在本地处理。
+
+ ```bash
+ # 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](references/lark-base-record-query-and-analysis-sop.md)。
+
+ #### 2. 新增记录或更新记录单元格
+
+ 一条 Record 是 `{字段名或 field_id: CellValue}`,常见 CellValue:
+
+ ```jsonc
+ {
+ "标题": "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)
+ "关联任务": [{ "id": "rec456" }], // link: array<{id}>,record_id 来自目标表
+ "坐标": { "lng": 116.397428, "lat": 39.90923 }, // location: {lng,lat}
+ "清空": null, // 清空单元格,传 null
+ "清空数组": [] // 清空数组类单元格,空数组和 null 都可以
+ }
+ ```
+
+ 附件使用专用 shortcut 上传、下载或移除。created_at, updated_at, created_by, updated_by, auto_number, formula, lookup 类型字段只读,若误写入单元格会返回 `ignored_fields` 表示这些字段被静默过滤,其余字段正常写入。
+
+ ```bash
+ # 新增:成功时返回 record_id_list
+ lark-cli base +record-batch-create \
+ --base-token <base_token> --table-id <table_id> \
+ --json '{"create_records":[{"Name":"Task A","Status":["Todo"]},{"Name":"Task B","Score":20}]}' --as user
+
+ # 更新:每条记录只提交要改变的字段
+ lark-cli base +record-batch-update \
+ --base-token <base_token> --table-id <table_id> \
+ --json '{"update_records":{"<record_id_a>":{"Status":["Done"]},"<record_id_b>":{"Score":100}}}' --as user
+ ```
+
+ 大 payload 可用脚本生成 json 后用 `--json @file.json`。单批最多 200 条,超过后分批,同一 Table 串行写入;并行可能触发 `1254291` 并发冲突错误。
+
+ #### 3. 其他 Record 操作
+
+ - `+record-delete --base-token <base_token> --table-id <table_id> --record-id <id1> --record-id <id2>` 删除若干个记录
+ - `+record-share-link-create --base-token <base_token> --table-id <table_id> --record-id <id1> --record-id <id2>` 创建记录分享链接
+ - `+record-history-list` 查询单条记录的变更事件,读取 [历史记录协议](references/lark-base-record-history-list.md)
+ - 附件必须使用 `+record-upload-attachment` / `+record-download-attachment` / `+record-remove-attachment` 操作。
+
+ ### View
+
+ View 共享 Table 的底层记录;没有特殊展示需求时优先使用 `grid`。读取已有视图用 `+view-list` / `+view-get`。
+
+ **所有 View 编辑前必读 [View 类型与生命周期](references/lark-base-view.md)**,包括创建、改名、配置修改(筛选、排序、分组、字段显隐、时间条、卡片)和删除。视图选型、适用配置及完整操作示例统一在该 reference 中。
+
+ ### Form
+
+ Form 依附于 Table,以 Field 作为题目,每次有效提交会创建一条 Record,适合信息收集、外部填写、条件题目和附件提交。
+
+ 1. **读取 Table 中的表单配置:** 使用 `+form-list` / `+form-get` 读取表单,使用 `+form-questions-list` 读取题目配置;这些命令使用表单所属的 `base_token + table_id`。
+ 2. **创建或修改 Table 中的表单配置:** 使用 `+form-create` / `+form-update` / `+form-delete` 管理表单;题目由 Table Field 承载,question ID 对应 `field_id`,创建和更新分别读取 [questions create](references/lark-base-form-questions-create.md) / [questions update](references/lark-base-form-questions-update.md),删除使用 `+form-questions-delete`。
+ 3. **调整表单题目显隐和顺序:** Form 在 `visible_fields` 接口中作为 View,`form_id` 传给 `--view-id`。用 `+view-get-visible-fields` 读取当前可见题目,再用 `+view-set-visible-fields` 提交最终需要展示的完整有序题目 ID 列表;省略当前可见题目会隐藏它,加入已有隐藏 Form 成员会重新展示,空列表会隐藏全部题目。目标只能包含已有 Form 成员;仍显示题目的 `visible_rule` 只能引用位于它之前的可见题目。
+ 4. **管理表单分享:** 使用 `+form-share-get` / `+form-share-update` 管理启停、访问范围和匿名/登录要求;更新前先读取现状,每次只修改一个字段,布尔值显式传 `true` 或 `false`。
+ 5. **填写分享表单并提交:** 对表单分享链接使用 `+url-resolve` 取得 `share_token`,按 [Form detail](references/lark-base-form-detail.md) 执行 `+form-detail` 读取真实题目、必填项和显示条件,再按 [Form submit](references/lark-base-form-submit.md) 构造字段与附件并执行 `+form-submit`。
+
+ 表单题目和字段的关系:
+
+ - `+form-questions-create` 支持两种形态:新建字段题目需要 `title` + `type`;已有字段题目需要 `use_existing_field:true` + `field_id`。已有字段题目只是把该字段加入表单,不创建新字段,也不改变已有记录数据;不要给该形态携带 `type`、`style`、`options` 等字段定义属性。
+ - 创建问题前先 `+form-questions-list`。若目标标题已经存在,除非用户明确要求同名独立问题,否则优先用 `+form-questions-update` 修改题目配置,不要先创建同名问题再删除旧问题。
+ - `+form-questions-delete` 是高风险写操作。默认会删除承载问题的底层 Field 及该字段所有记录数据;只想把题目移出表单并保留字段/数据时必须传 `--keep-field`。保留字段后可用 `+form-questions-create --questions '[{"use_existing_field":true,"field_id":"<field_id>"}]'` 加回表单。
+
+ ## Dashboard Block
+
+ Dashboard Block 是 Base Block 树中的仪表盘容器,负责承载页面主题、布局和内部组件集合,本身不表示某一项图表数据。使用 `+dashboard-list` 定位容器,`+dashboard-get` 读取容器信息,`+dashboard-update` 修改主题,`+dashboard-arrange` 统一编排内部组件布局。
+
+ **管理 Dashboard 分享:** 使用 `+dashboard-share-get` / `+dashboard-share-update` 管理启停、访问范围和返回源 Base 入口;更新前先读取现状,每次只修改一个字段,显式 `false` 会被保留。
+
+ 容器内部的图表、指标卡和文本等组件在 Dashboard API 中也称为 Block,但不属于 Base Block 树。内部 Block 分为三条操作路径:
+
+ 1. **读取配置:** `+dashboard-block-list` / `+dashboard-block-get` 读取组件类型、布局和 `data_config`;文本组件的正文也属于配置。
+ 2. **写入配置:** `+dashboard-block-create` / `+dashboard-block-update` / `+dashboard-block-delete` 管理组件,`data_config` 定义数据源、维度、指标、聚合或文本内容。
+ 3. **读取内容:** `+dashboard-block-get-data` 读取图表、指标卡等数据组件的计算结果。
+
+ 操作内部 Block 前先读 [Dashboard](references/lark-base-dashboard.md),由该入口继续路由组件配置和结果协议。
+
+ ## 应用模式与 Workspace 心智模型
+
+ Workspace 是组织 Base 和 BaseApp 的空间容器;BaseApp 创建时必须归属一个 Workspace。BaseApp 用 Page 组织界面,每个 Page 包含图表、列表或富文本组件;组件通过 `data_config` 引用 Base 数据,但不会改变 Base、Table、Field 和 Record 的归属关系。Workspace 负责资源归属,App 负责页面和组件,Base 负责数据。
+
+ 1. **Workspace:** 使用 `+workspace-create`、`+workspace-entity-list` 和 `+workspace-move-in` 创建目录、列出其中的 Base/BaseApp 或移入资源。
+ 2. **应用:** 使用 `+app-create` / `+app-get`;应用查询和创建依赖真实 `app_token` / `workspace_token`。
+ 3. **页面:** 使用 `+app-page-list/get/create/rename/delete` 管理 Page。
+ 4. **组件:** 使用 `+app-block-list/get/create/update` 读写组件配置,使用 `+app-block-get-data` 读取组件计算结果。
+
+ BaseApp、Workspace、Page 或组件任务开始前完整读取 [应用模式与 Workspace](references/lark-base-app.md);构造组件 `data_config` 时继续读取 [应用组件配置](references/lark-base-app-block-data-config.md)。BaseApp 不走 `lark-apps`。当前不支持 BaseApp 复制、Page 完整复制、页面图标以及从 Workspace 移出资源;遇到这些目标按 reference 的能力边界处理,不以新建空对象或 Drive 移动冒充。
+
+ - BaseApp(应用模式)中的 Page 和组件使用 `app_token` / `page_id` / `block_id`,表、字段和记录仍使用组件所引用 Base 的 `base_token`;不要混用 token 或把 BaseApp 当作 Base 的别名。
+ - 复用现有 BaseApp block 的 `data_config` 只能作为结构模板,首次 Create/Update 前仍要逐项对齐用户显式要求;用户要求排序时必须显式写 `group_by[].sort.order` 或顶层 `sort.order`,不能用旧配置省略的方向或当前 `get-data` 结果顺序代替。
+ - 应用页面的 block 与仪表盘 block 是同一套底层实体,但 ID 体系不通用;按当前模块 reference 选择命令和配置协议。
+
+ ## Workflow Block
+
+ Workflow 本身是 Base Block,其内部是一张由 `next` / `children` 连接的 steps 执行图;触发器、动作、条件分支和循环都是 step 类型。它适合定时执行、Record 新增或变更联动、消息通知、记录读写和跨系统调用。Workflow 分为三条操作路径:
+
+ 1. **读取配置:** `+workflow-list` 定位流程,`+workflow-get` 读取 `title`、`status` 和完整 `steps` 执行图。
+ 2. **写入配置:** `+workflow-create` 创建完整定义,`+workflow-update` 更新完整定义;构造或修改配置前读取 [Workflow](references/lark-base-workflow.md),由该入口继续路由 step 类型和 schema。
+ 3. **运行状态控制:** `+workflow-enable` / `+workflow-disable` 启用或停用已有 Workflow,不修改 steps 执行图。
+
+ ## Advanced Permission(AdvPerm)
+
+ AdvPerm 为 Base 开启细粒度权限模式;Role 在此基础上配置 Base、Table、View、Field、Record、Dashboard 和 Docx 等资源的访问能力,适合按团队或职责限制可见范围、编辑能力、复制下载和数据访问规则。
+
+ **读取 AdvPerm:** `+base-get` 查看 `is_advanced`,`+role-list` / `+role-get` 查看角色。**写入 AdvPerm:** `+advperm-enable` / `+advperm-disable` 启停高级权限,`+role-create` / `+role-update` / `+role-delete` 管理角色。先读 [权限与角色](references/lark-base-advanced-permission-and-role.md),由该入口继续路由权限 JSON 协议。
+
+ ## Docx Block
+
+ Docx Block 是组织在 Base 目录中的飞书文档资源,适合把说明、方案和报告与数据表、仪表盘及流程放在同一 Base 中;正文仍使用标准 Docx 数据模型。
+
+ 从 Base Block 资源目录按 `--type docx` 定位文档并取得 `docx_token`;正文读取、创建与编辑使用 `lark-doc`。
+
+ ## Folder Block
+
+ Folder Block 只承担 Base 目录分组和层级组织。用 `+base-block-list --parent-id <folder_block_id>` 读取直接子项。
+
+ ## 通用执行契约
+
+ - Update 先确认命令是完整替换还是 delta:完整替换使用可信当前配置做 read-modify-write,delta 只提交目标变更。
+ - 优先用写入返回确认结果;返回不足以确认或任务明确要求核验时再读回目标。
+ - 命令具有 confirmation gate 时,确认目标和影响后使用 `--yes`。
+
+ ## 不在本 Skill 范围
+
+ - 认证、初始化、scope、身份切换和授权恢复 → `lark-shared`
+ - Excel、CSV、`.base` 等本地文件与 Base 之间的导入/导出转 `lark-drive`;在线复制走 `+base-copy`
+ - Base 内嵌 Docx 的正文编辑 → `lark-doc`;电子表格内容操作 → `lark-sheets`