Lark Sheets

sheets (v3)

CRITICAL — 开始前 MUST 先用 Read 工具读取 [../lark-shared/SKILL.md](../lark-shared/SKILL.md)，其中包含认证、权限处理

快速决策

• 按标题或关键词找云空间里的表格文件，先用 lark-cli docs +search。
• docs +search 会直接返回 SHEET 结果，不要把它误解成只能搜文档 / Wiki。
• 已知 spreadsheet URL / token 后，再进入 sheets +info、sheets +read、sheets +find 等对象内部操作。

核心概念

文档类型与 Token

飞书开放平台中，不同类型的文档有不同的 URL 格式和 Token 处理方式。在进行文档操作（如添加评论、下载文件等）时，必须先获取正确的 file_token。

文档 URL 格式与 Token 处理

| URL 格式 | 示例 | Token 类型 | 处理方式 | |----------|---------------------------------------------------------|-----------|----------| | /docx/ | https://example.larksuite.com/docx/doxcnxxxxxxxxx | file_token | URL 路径中的 token 直接作为 file_token 使用 | | /doc/ | https://example.larksuite.com/doc/doccnxxxxxxxxx | file_token | URL 路径中的 token 直接作为 file_token 使用 | | /wiki/ | https://example.larksuite.com/wiki/wikcnxxxxxxxxx | wiki_token | ⚠️ 不能直接使用，需要先查询获取真实的 obj_token | | /sheets/ | https://example.larksuite.com/sheets/shtcnxxxxxxxxx | file_token | URL 路径中的 token 直接作为 file_token 使用 | | /drive/folder/ | https://example.larksuite.com/drive/folder/fldcnxxxx | folder_token | URL 路径中的 token 作为文件夹 token 使用 |

Wiki 链接特殊处理（关键！）

知识库链接（/wiki/TOKEN）背后可能是云文档、电子表格、多维表格等不同类型的文档。不能直接假设 URL 中的 token 就是 file_token，必须先查询实际类型和真实 token。

处理流程

1. 使用 wiki.spaces.get_node 查询节点信息

``bash lark-cli wiki spaces get_node --params '{"token":"wiki_token"}' ``

1. 从返回结果中提取关键信息

• node.obj_type：文档类型（docx/doc/sheet/bitable/slides/file/mindnote）
• node.obj_token：真实的文档 token（用于后续操作）
• node.title：文档标题

1. 根据 obj_type 使用对应的 API

| obj_type | 说明 | 使用的 API | |----------|------|-----------| | docx | 新版云文档 | drive file.comments.*、docx.* | | doc | 旧版云文档 | drive file.comments.* | | sheet | 电子表格 | sheets.* | | bitable | 多维表格 | bitable.* | | slides | 幻灯片 | drive.* | | file | 文件 | drive.* | | mindnote | 思维导图 | drive.* |

查询示例

# 查询 wiki 节点
lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'

返回结果示例：

{
   "node": {
      "obj_type": "docx",
      "obj_token": "xxxx",
      "title": "标题",
      "node_type": "origin",
      "space_id": "12345678910"
   }
}

资源关系

Wiki Space (知识空间)
└── Wiki Node (知识库节点)
    ├── obj_type: docx (新版文档)
    │   └── obj_token (真实文档 token)
    ├── obj_type: doc (旧版文档)
    │   └── obj_token (真实文档 token)
    ├── obj_type: sheet (电子表格)
    │   └── obj_token (真实文档 token)
    ├── obj_type: bitable (多维表格)
    │   └── obj_token (真实文档 token)
    └── obj_type: file/slides/mindnote
        └── obj_token (真实文档 token)

Drive Folder (云空间文件夹)
└── File (文件/文档)
    └── file_token (直接使用)

操作流程（重要）：

1. create — 创建筛选

• 用于首次创建筛选
• ⚠️ range 必须覆盖所有需要筛选的列（如 B1:E200）
• 如果已有筛选存在，再用 create 会覆盖整个筛选

1. update — 更新筛选

• 用于在已有筛选上添加/更新指定列的条件
• 只需指定 col 和 condition，不需要 range

1. delete — 删除筛选

1. get — 获取筛选状态

多列筛选示例：

创建媒体名称(B列)和情感分析(E列)的双重筛选：

# 1. 删除现有筛选（如有）
lark-cli sheets spreadsheet.sheet.filters delete \
  --params '{"spreadsheet_token":"","sheet_id":""}'

# 2. 创建第一个筛选，range 覆盖所有要筛选的列
lark-cli sheets spreadsheet.sheet.filters create \
  --params '{"spreadsheet_token":"","sheet_id":""}' \
  --data '{"col":"B","condition":{"expected":["xx"],"filter_type":"multiValue"},"range":"!B1:E200"}'

# 3. 添加第二个筛选条件
lark-cli sheets spreadsheet.sheet.filters update \
  --params '{"spreadsheet_token":"","sheet_id":""}' \
  --data '{"col":"E","condition":{"expected":["xx"],"filter_type":"multiValue"}}'

常见错误：

• Wrong Filter Value：筛选已存在，需要先 delete 再 create
• Excess Limit：update 时重复添加同一列条件

Shortcuts（推荐优先使用）

Shortcut 是对常用操作的高级封装（lark-cli sheets + [flags]）。有 Shortcut 的操作优先使用。

| Shortcut | 说明 | |----------|------| | [+info](references/lark-sheets-info.md) | View spreadsheet and sheet information | | [+read](references/lark-sheets-read.md) | Read spreadsheet cell values | | [+write](references/lark-sheets-write.md) | Write to spreadsheet cells (overwrite mode) | | [+append](references/lark-sheets-append.md) | Append rows to a spreadsheet | | [+find](references/lark-sheets-find.md) | Find cells in a spreadsheet | | [+create](references/lark-sheets-create.md) | Create a spreadsheet (optional header row and initial data) | | [+export](references/lark-sheets-export.md) | Export a spreadsheet (async task polling + optional download) |

API Resources

lark-cli schema sheets..   # 调用 API 前必须先查看参数结构
lark-cli sheets   [flags] # 调用 API

> 重要：使用原生 API 时，必须先运行 schema 查看 --data / --params 参数结构，不要猜测字段格式。

spreadsheets

• create — 创建电子表格
• get — 获取电子表格信息
• patch — 修改电子表格属性

spreadsheet.sheet.filters

• create — 创建筛选
• delete — 删除筛选
• get — 获取筛选
• update — 更新筛选

spreadsheet.sheets

• find — 查找单元格

权限表

| 方法 | 所需 scope | |------|-----------| | spreadsheets.create | sheets:spreadsheet:create | | spreadsheets.get | sheets:spreadsheet.meta:read | | spreadsheets.patch | sheets:spreadsheet.meta:write_only | | spreadsheet.sheet.filters.create | sheets:spreadsheet:write_only | | spreadsheet.sheet.filters.delete | sheets:spreadsheet:write_only | | spreadsheet.sheet.filters.get | sheets:spreadsheet:read | | spreadsheet.sheet.filters.update | sheets:spreadsheet:write_only | | spreadsheet.sheets.find | sheets:spreadsheet:read |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ejjcc
• Source: ejjcc/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.