Skip to content

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。

FileKindSize
SKILL.mdskill md24.0 KB
references/lark-base-advanced-permission-and-role.mdmarkdown3.8 KB
references/lark-base-app-block-data-config.mdmarkdown7.8 KB
references/lark-base-app.mdmarkdown15.4 KB
references/lark-base-cell-value.mdmarkdown6.4 KB
references/lark-base-dashboard-block-config.mdmarkdown20.5 KB
references/lark-base-dashboard-block-get-data.mdmarkdown24.4 KB
references/lark-base-dashboard.mdmarkdown16.3 KB
references/lark-base-data-query.mdmarkdown19.2 KB
references/lark-base-field-create.mdmarkdown3.3 KB
references/lark-base-field-extension.mdmarkdown6.8 KB
references/lark-base-field-formula.mdmarkdown54.4 KB
references/lark-base-field-lookup.mdmarkdown18.5 KB
references/lark-base-field-schema.mdmarkdown14.5 KB
references/lark-base-field-update.mdmarkdown6.7 KB
references/lark-base-filter-condition.mdmarkdown7.3 KB
references/lark-base-form-detail.mdmarkdown3.0 KB
references/lark-base-form-questions-create.mdmarkdown9.7 KB
references/lark-base-form-questions-update.mdmarkdown7.2 KB
references/lark-base-form-submit.mdmarkdown7.0 KB
references/lark-base-record-batch-create.mdmarkdown2.1 KB
references/lark-base-record-history-list.mdmarkdown2.7 KB
references/lark-base-record-query-and-analysis-sop.mdmarkdown11.5 KB
references/lark-base-record-upsert.mdmarkdown2.3 KB
references/lark-base-role-config.mdmarkdown21.3 KB
references/lark-base-template-center.mdmarkdown10.0 KB
references/lark-base-view-set-filter.mdmarkdown2.6 KB
references/lark-base-view.mdmarkdown9.2 KB
references/lark-base-workflow-schema.mdmarkdown42.8 KB
references/lark-base-workflow.mdmarkdown30.5 KB

references/lark-base-form-submit.md

View on GitHub
# base +form-submit

> **前置条件:** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。

通过表单分享链接填写并提交多维表格表单。仅支持分享模式(share_token),支持填写普通字段值和上传本地文件作为附件。

> **⚠️ 高风险写操作(high-risk-write):** 本命令会向表单写入并提交数据,属于高风险写操作,必须额外传递 `--yes` 进行确认,否则会返回 `confirmation_required` 错误并退出。当用户明确要求提交且目标表单无歧义时,直接附加 `--yes`,无需再次询问。

## 填写前必读:先获取表单详情

**在调用 `+form-submit` 之前,必须先使用 `+form-detail` 获取表单详情。** 原因如下:

1. **字段类型匹配**:每个题目的 `type` 决定了值的格式(文本、数字、选项、人员、日期等),需根据类型正确构造 `fields` 中的值
2. **必填校验**:通过 `questions[].required` 判断哪些题目为必填项,避免遗漏
3. **显示条件过滤**:部分题目带有 `filter`(显示/隐藏逻辑),需根据用户已填的其他题目值判断该题目是否应该出现——**不应填写被 filter 隐藏的题目**
4. **获取 base_token(附件场景必用)**:`+form-detail` 返回的 `data.base_token` 是该表单所属的多维表格标识。当表单包含附件字段时,提交时必须通过 `--base-token` 传入此值,因为附件需要上传到该 Base 的 Drive Media 中

典型流程:

```bash
# 1️⃣ 先获取表单详情,了解所有题目
lark-cli base +form-detail --share-token <share_token>

# 2️⃣ 根据返回的 questions 列表,按 type 格式化值、检查 required、判断 filter 条件

# 3️⃣ 再提交(高风险写操作,必须带 --yes)
lark-cli base +form-submit \
  --share-token <share_token> \
  --json '{"fields":{...}}' \
  --yes
```

`+form-detail` 的返回中要重点读取 `questions[].type`、`questions[].required`、题目 `filter` 和附件场景所需的 `data.base_token`。

## 命令

```bash
# 基本提交(填写普通字段)
lark-cli base +form-submit \
  --share-token <share_token> \
  --json '{"fields":{"服务评分":5,"评价内容":"服务态度好"}}' \
  --yes

# 带附件提交(需要额外提供 --base-token)
lark-cli base +form-submit \
  --share-token <share_token> \
  --base-token <base_token> \
  --json '{
    "fields": {"服务评分": 5, "评价内容": "好"},
    "attachments": {
      "附件字段名": ["./report.pdf", "./photo.png"],
      "另一个附件字段": ["./doc.docx"]
    }
  }' \
  --yes

# 使用应用身份(bot)
lark-cli base +form-submit \
  --share-token <share_token> \
  --json '{"fields":{...}}' \
  --as bot \
  --yes

# 预览 API 调用(不实际执行,dry-run 无需 --yes)
lark-cli base +form-submit \
  --share-token <share_token> \
  --json '{"fields":{...}}' \
  --dry-run
```

## 参数

| 参数 | 必填 | 说明 |
|------|------|------|
| `--share-token <token>` | 是 | 表单分享 Token(必填),从表单分享链接中提取 |
| `--base-token <token>` | 条件必填 | Base token;**当 `--json` 包含 `attachments` 时必须提供**,用于将附件上传到 Base Drive Media |
| `--json <json>` | 是 | JSON 对象,包含 `"fields"`(普通字段值)和 `"attachments"`(附件上传),详见下方说明 |
| `--yes` | 是 | 确认高风险写操作。本命令为 high-risk-write,不带 `--yes` 会返回 `confirmation_required` |
| `--format` | 否 | 输出格式:json(默认)\| pretty \| table \| ndjson \| csv |
| `--as` | 否 | 身份:user(默认)\| bot |
| `--dry-run` | 否 | 预览 API 调用,不执行 |

### --json 结构说明

`--json` 是一个 JSON 对象,包含两个部分:

#### fields(普通字段)

`fields` 中的常见单元格值按下方示例构造(与主 skill 一致):

```json
{
  "文本字段": "Hello World",
  "电话字段": "13800000000",
  "超链接字段": "https://example.com",
  "数字字段": 12.5,
  "单选字段": ["选项A"],
  "多选字段": ["选项A", "选项B"],
  "时间字段": "2026-04-27 14:30:00",
  "复选框字段": true,
  "人员字段": [{ "id": "ou_7094d131420c8749632145f08fbf114a" }],
  "关联字段": [{ "id": "recXXXXXXXXXXXX" }],
  "地理位置字段": { "lng": 116.397428, "lat": 39.90923 }
}
```

> **注意:附件类型字段不要写在 `fields` 里。** `fields` 中不包含附件,附件有独立的填写方式,见下方「attachments(附件上传)」章节。

> 自动编号、公式、创建/修改人、创建/修改时间等系统字段会自动填入,无需手动传入。

#### attachments(附件上传)

**附件字段的填写方式与 `fields` 中的普通单元格完全不同**,不能在 `fields` 里传 `file_token` 或其他附件格式。必须将附件字段单独放在 `--json` 的顶层 `attachments` 对象中,值为**本地文件路径数组**(不是 token):

```json
{
  "attachments": {
    "附件字段名": ["./report.pdf", "./photo.png"],
    "另一个附件字段": ["./doc.docx"]
  }
}
```

CLI 收到路径后会自动完成以下流程:
1. 校验所有文件(存在性、大小 ≤2GB、常规文件)
2. 并行上传到 Base Drive Media(并发上限 5,跨字段重复路径自动去重)
3. 获取 `file_token` 后合并到最终表单提交内容中

> Record 写入时附件走独立的 `+record-upload-attachment` 命令;`+form-submit` 则在 `attachments` 中传本地路径,由 CLI 自动上传。

### 从分享链接提取 share-token

用户提供形如以下格式的表单分享链接时:

```
https://www.example.com/share/base/form/shrbcvST8eZy0vk8zjVZ1CAXNye
```

**提取方式:** 取 URL 路径最后一段作为 `--share-token`。

以上述链接为例:

- `share-token` = `shrbcvST8eZy0vk8zjVZ1CAXNye`

```bash
lark-cli base +form-submit \
  --share-token shrbcvST8eZy0vk8zjVZ1CAXNye \
  --json '{"fields":{...}}' \
  --yes
```

## 输出格式

| 字段 | 类型 | 说明 |
|------|------|------|
| `can_submit_again` | bool | 是否可以再次填写 |

```json
{
  "ok": true,
  "data": {
    "can_submit_again": true
  }
}
```

## 提示

- **本命令为高风险写操作(high-risk-write),必须额外传递 `--yes` 确认**,否则返回 `confirmation_required` 并以非零码退出;`--dry-run` 预览除外
- 本命令仅支持通过表单分享链接(share_token)提交,不支持通过 base_token + table_id + view_id 方式提交
- **当 `--json` 包含 `attachments` 时,必须额外提供 `--base-token`**,因为附件上传到 Base Drive Media 需要指定目标 Base
- 附件字段只需在 `--json.attachments` 中提供本地路径即可,CLI 自动完成校验、并行上传、Token 获取和合并写入
- 限流:单应用 20 QPS,单用户 5 QPS
- 权限要求:`base:form:update`;使用 attachments 时还需 `docs:document.media:upload`

## 参考

- [lark-base](../SKILL.md) — 多维表格全部命令
- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数
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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall
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: 108kUpdated Claude CodeCodexVerifiedInstall
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: 108kUpdated Claude CodeCodexVerifiedInstall