Pinvou/pinvou-agent / pinvou3-app/src-tauri/resources/common/bundle/lark-skills/lark-base
lark-base
Verified【何时用:仅当用户明确指向飞书/Lark(发到飞书、飞书文档等)时使用;泛指做个文档或PPT或表格或方案默认走本地工具,不要误用飞书】飞书多维表格(Base)操作:建表、字段、记录、视图、统计、公式/lookup、表单、仪表盘、BaseApp 应用模式(页面与组件)、Workspace 目录、workflow、角色权限、模板中心(模板分类/列表/搜索);遇到 Base/多维表格/bitable、BaseApp、/base/ 或 /app/ 链接时使用。BaseApp 不走 lark-apps;导入转 lark-drive,认证转 lark-shared。
references/lark-base-app-block-data-config.md
View on GitHub# BaseApp Block `data_config`
本文件说明 BaseApp 组件 `data_config` 的 CLI 映射与操作约束,不复制完整字段 Schema。App 图表的每个 `data_sources[]` 元素复用 [Dashboard Block 配置](lark-base-dashboard-block-config.md) 的字段取值、筛选、分组、排序及规范化规则;区别是 Dashboard 使用扁平单数据源结构,而 App 图表在顶层使用共享的 `base_token` 和多数据源 `data_sources[]`。列表组件是 App 独有协议,不复用 Dashboard 图表结构。本文所称“组件协议”是指 CLI 随版本发布的 API 元数据、本文明确列出的约束及实际服务端校验结果。
## 类型映射
- 图表:`--type column|bar|line|pie|ring|area|combo|scatter|funnel|wordCloud|radar|statistics`
- 富文本:`--type text`(与 Dashboard 文本组件同名同义)
- 列表:`--type list --sub-type standard|grouped|collapsible|card|detail`
- 列表省略 `--sub-type` 时默认 `standard`
- `type/sub_type` 创建后不可修改
## 外层请求字段
- Create 只发送 `name`、`type`、按需发送的 `sub_type` 和 `data_config`。`name`、`type` 必填;图表和列表的 `data_config` 必填,富文本可省略。
- 标准列表未显式指定 `--sub-type` 时,不发送 `sub_type`,由服务端使用 `standard` 默认值;其他列表类型必须发送对应 `sub_type`。
- 图表和富文本不得发送 `sub_type`。
- Update 只发送 `name`、`data_config`,且至少提供一个;未传字段保持不变,不允许修改 `type`、`sub_type`。
- 布局、位置、尺寸、`show_title` 等展示配置不属于本期公开 Create/Update 请求字段,CLI 不提供或提升这些字段。
## 列表配置
列表公共数据源字段为单值 `base_token` 和 `table_name`。每个列表最多关联一个 Base,且该 Base 必须位于 App 所在的同一 Workspace。
按组件协议,各 subtype 使用以下字段组:
- 公共:`base_token`、`table_name`、`filter`、`sort_by`
- `standard/grouped/collapsible`:`columns`、`group_by`
- `card`:`fields`、`card_config`
- `detail`:`fields`、`detail_config`
- `columns` 和 `fields` 都是可选字段。未指定时 CLI 不发送,由服务端使用产品默认字段。
- 只有用户显式指定 `columns` / `fields` 时才发送;显式传 `[]` 表示明确发送空数组,不能作为默认值自动补入。
- `filter`、`sort_by`、`group_by`、`card_config`、`detail_config` 也都是可选字段;未指定时不发送。
- 列表 Create 的 `data_config` 必填,其中只有 `base_token` 和 `table_name` 是顶层必填字段。
- 可选对象一旦传入,其内部必填项仍须满足协议,例如 `filter` 必须包含 `conjunction` 和 1~50 项 `conditions`。
不要添加协议未定义的语义校验,尤其不要假设:
- detail/card 必须有 title;
- grouped/collapsible 必须或只能有一个 group_by;
- fields 存在 role 或 visible 属性。
未知顶层字段会被本地校验拒绝;只有确认 CLI 校验与最新协议不一致时才使用 `--no-validate`。
## 创建示例
```bash
lark-cli base +app-block-create \
--app-token <app_token> --page-id <page_id> \
--name "订单列表" \
--type list --sub-type standard \
--data-config '{"base_token":"<base_token>","table_name":"订单"}'
```
字段的具体对象结构与必填性以 CLI 当前版本的 API 元数据和服务端校验结果为准,不在这里猜测未公开属性。
## 更新语义
下面是只更新顶层 `filter` 的示例,适用于协议将 `filter` 定义在 `data_config` 顶层的组件(所有列表 subtype 均可使用)。组件类型在创建后不可修改,所以 update 命令不再传 `--type`。App 图表的 `filter` 定义在对应的 `data_sources[]` 元素中;更新图表筛选时必须按图表结构传入完整 `data_sources`,不能把 `filter` 提到顶层。
```bash
lark-cli base +app-block-update \
--app-token <app_token> --page-id <page_id> --block-id <block_id> \
--data-config '{"filter":{"conjunction":"and","conditions":[{"field_name":"状态","operator":"is","value":"已完成"}]}}'
```
- CLI 只发送用户显式传入的字段。
- 未传字段由服务端保持不变。
- 不为 update 注入 create 默认值,不先读取后拼成全量配置。
- 数组/对象字段的替换粒度以组件协议和服务端校验结果为准。
## 图表与富文本
**App 图表是多数据源结构(`ChartDataConfig`),与 Dashboard 的扁平单源结构不同。** 顶层用一个 `base_token`(所有数据源共用),`table_name` / `series` / `count_all` / `group_by` / `filter` 下沉到每个 `data_sources[]` 元素里;顶层另有可选的 `data_source_mode` 和 `sort`。每个数据源内部各字段的取值逻辑与 [Dashboard Block 配置](lark-base-dashboard-block-config.md) 完全一致(`series[].rollup` 大写、`group_by[].sort` 小写等),CLI 对每个 `data_sources[]` 元素复用同一套规范化与校验。富文本使用 `--type text`,配置为 `{"text":"..."}`,无数据源;Create 时可省略 `data_config`,等价于空文本。
> **text 内容怎么取**:text 组件没有 `/data` 接口,走 `+app-block-get-data` 会被服务端兜底成通用 500。改用 `+app-block-get --block-id <widget_id>` 直接读 `data_config.text`(Markdown 原文)。图表仍走 `+app-block-get-data --block-id <chart_token>`。
顶层参数:
| 参数 | 必填 | 取值 | 说明 |
|-|-|-|-|
| `base_token` | 是 | `string` | 数据所在 Base 的 token;所有数据源共用同一个值。App 命令不带 `--base-token`,只能写在 data_config 内 |
| `data_sources` | 是 | `ChartDataSourceConfig[]` | 有序数组,至少一项 |
| `data_source_mode` | 否 | `aggregate` / `compare` | `aggregate`(默认)在横轴聚合数据源;`compare` 按数据源拆分系列 |
| `sort` | 否 | `{type: group\|value\|record, order?: asc\|desc}` | 顶层排序;`statistics` 不允许 |
每个 `data_sources[]` 元素:`table_name`(必填)、`series` 与 `count_all=true` 二选一、`group_by`(最多 2 项,`statistics` 不允许)、`filter`。
```json
{
"base_token": "A2f5boKjfazMzesI9zKbmugTc4T",
"data_sources": [
{
"table_name": "数据表",
"count_all": true,
"group_by": [
{ "field_name": "文本", "mode": "integrated", "sort": { "type": "value", "order": "desc" } }
]
}
]
}
```
对应命令(单数据源计数柱状图):
```bash
lark-cli base +app-block-create \
--app-token <app_token> --page-id <page_id> \
--name "文本分布" --type column \
--data-config '{"base_token":"A2f5boKjfazMzesI9zKbmugTc4T","data_sources":[{"table_name":"数据表","count_all":true,"group_by":[{"field_name":"文本","mode":"integrated","sort":{"type":"value","order":"desc"}}]}]}'
```
多数据源示例(两张表各出一条系列,按数据源拆分):
```bash
lark-cli base +app-block-create \
--app-token <app_token> --page-id <page_id> \
--name "销售与成本" --type combo \
--data-config '{"base_token":"bas_xxx","data_source_mode":"compare","data_sources":[{"table_name":"销售表","group_by":[{"field_name":"月份","sort":{"type":"group","order":"asc"}}],"series":[{"field_name":"销售额","rollup":"SUM"}]},{"table_name":"成本表","group_by":[{"field_name":"月份","sort":{"type":"group","order":"asc"}}],"series":[{"field_name":"成本","rollup":"SUM"}]}],"sort":{"type":"group","order":"asc"}}'
```
Update 语义:传入 `data_sources` 即全量替换整个有序数组;修改 `base_token` 时必须同时传入完整 `data_sources`。请求不得包含 `sub_type`(平滑/堆积/百分比等展示变体走产品默认值)。布局、位置、尺寸和展示配置不属于本期公开 Create/Update 协议。其他请求字段以 CLI 当前版本的 API 元数据和服务端校验结果为准。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |