Skill 清单
飞书电子表格 Skill 的完整能力清单，涵盖 A-Skill / B-Tool / C-系统能力三层架构。
架构总览
A 层 · Skill
| Skill 名称 | 触发意图 | 包含 Tool |
|---|---|---|
feishu_sheet | 用户涉及飞书电子表格的读写、查询、创建等操作 | create_spreadsheet read_sheet write_sheet get_sheet_info find_in_sheet |
B 层 · Tool
create_spreadsheet
创建新的飞书电子表格。
| 属性 | 值 |
|---|---|
| 功能 | 在指定文件夹下创建空白电子表格 |
| 参数 | title（表格标题，0-255 字符）、folder_token（目标文件夹，可选） |
| 返回 | 表格 spreadsheet_token、URL |
底层 API
| 方法 | 路径 | 权限 scope |
|---|---|---|
POST | /sheets/v3/spreadsheets | sheets:spreadsheet / sheets:spreadsheet:create |
read_sheet
读取电子表格中的数据，支持单范围和多范围批量读取。
| 属性 | 值 |
|---|---|
| 功能 | 按范围读取单个或多个区域的单元格数据 |
| 参数 | spreadsheet_token、range（格式 <sheetId>!<A1:B2>）、ranges（多范围，逗号分隔）、value_render_option、date_time_render_option |
| 返回 | 二维数组形式的单元格值 |
底层 API
| 方法 | 路径 | 权限 scope | 说明 |
|---|---|---|---|
GET | /sheets/v2/spreadsheets/:token/values/:range | sheets:spreadsheet:readonly | 读取单个范围 |
GET | /sheets/v2/spreadsheets/:token/values_batch_get | sheets:spreadsheet:readonly | 读取多个范围（ranges 逗号分隔） |
参数选项
| 参数 | 取值 | 说明 |
|---|---|---|
valueRenderOption | ToString | 将值转为字符串（默认） |
Formula | 返回公式本身 | |
FormattedValue | 返回格式化后的显示值 | |
UnformattedValue | 返回原始值（数字/布尔） | |
dateTimeRenderOption | FormattedString | 日期时间格式化为字符串 |
write_sheet
向电子表格写入数据，覆盖写入、追加、前插、行列管理一站式处理。
| 属性 | 值 |
|---|---|
| 功能 | 向指定范围写入、追加、前插数据，支持批量写入多范围、行列增删及尺寸调整 |
| 参数 | spreadsheet_token、range、values（二维数组）、mode（overwrite / append / prepend / batch / insert_rows / delete_rows） |
| 返回 | updatedRows / updatedColumns / updatedCells / revision |
底层 API
| 方法 | 路径 | 权限 scope | 说明 |
|---|---|---|---|
PUT | /sheets/v2/spreadsheets/:token/values | sheets:spreadsheet | 写入单个范围 |
POST | /sheets/v2/spreadsheets/:token/values_batch_update | sheets:spreadsheet | 写入多个范围 |
POST | /sheets/v2/spreadsheets/:token/values_prepend | sheets:spreadsheet | 前插数据 |
POST | /sheets/v2/spreadsheets/:token/values_append | sheets:spreadsheet | 追加数据 |
POST | /sheets/v2/spreadsheets/:token/dimension_range | sheets:spreadsheet | 增加行列 |
POST | /sheets/v2/spreadsheets/:token/insert_dimension_range | sheets:spreadsheet | 插入行列 |
PUT | /sheets/v2/spreadsheets/:token/dimension_range | sheets:spreadsheet | 更新行高/列宽 |
DELETE | /sheets/v2/spreadsheets/:token/dimension_range | sheets:spreadsheet | 删除行列 |
追加写入选项
| insertDataOption | 行为 |
|---|---|
OVERWRITE | 覆盖已有空行数据 |
INSERT_ROWS | 始终插入新行 |
get_sheet_info
获取电子表格及工作表的元信息。
| 属性 | 值 |
|---|---|
| 功能 | 查询表格基本信息、工作表列表，修改表格属性、增/复制/删工作表 |
| 参数 | spreadsheet_token、properties（修改属性时传入） |
| 返回 | 表格标题、工作表列表（sheetId / title / index / rowCount / columnCount） |
底层 API
| 方法 | 路径 | 权限 scope | 说明 |
|---|---|---|---|
GET | /sheets/v3/spreadsheets/:token | sheets:spreadsheet:readonly | 获取表格信息 |
PATCH | /sheets/v3/spreadsheets/:token | sheets:spreadsheet | 修改表格属性（限 20 次/分钟） |
GET | /sheets/v3/spreadsheets/:token/sheets/query | sheets:spreadsheet:readonly | 获取工作表列表 |
POST | /sheets/v2/spreadsheets/:token/sheets_batch_update | sheets:spreadsheet | 增/复制/删工作表 |
频率限制
PATCH /sheets/v3/spreadsheets/:token 修改属性接口限制 20 次/分钟。
find_in_sheet
在工作表中查找或替换内容。
| 属性 | 值 |
|---|---|
| 功能 | 按关键词在指定工作表中查找单元格位置，或执行批量替换 |
| 参数 | spreadsheet_token、sheet_id、find（查找内容）、replace（替换内容，可选） |
| 返回 | 匹配的单元格位置列表；替换时返回替换数量 |
底层 API
| 方法 | 路径 | 权限 scope | 说明 |
|---|---|---|---|
POST | /sheets/v3/spreadsheets/:token/sheets/:sheet_id/find | sheets:spreadsheet:readonly | 查找 |
POST | /sheets/v3/spreadsheets/:token/sheets/:sheet_id/replace | sheets:spreadsheet | 替换 |
C 层 · 系统能力
| 能力 | 说明 |
|---|---|
| 权限过滤 | 根据 Bot 当前被授予的 scope 自动判断可用 Tool；只读 scope 下屏蔽写入类 Tool |
| 写入确认 | 涉及数据修改的操作（write / replace / 删除行列）执行前向用户确认，防止误操作 |
| Token 自动刷新 | tenant_access_token 过期前自动续期，上层 Tool 无感知 |
飞书 API 权限速查
| Scope | 说明 | 覆盖 Tool |
|---|---|---|
sheets:spreadsheet | 电子表格读写 | create_spreadsheet write_sheet get_sheet_info（修改属性/工作表管理） find_in_sheet（替换） |
sheets:spreadsheet:readonly | 电子表格只读 | read_sheet get_sheet_info（查询） find_in_sheet（查找） |
sheets:spreadsheet:create | 仅创建表格 | create_spreadsheet |
drive:drive | 云空间读写 | create_spreadsheet（指定 folder_token 时需要） |
drive:drive:readonly | 云空间只读 | 文件夹列表查询 |
最小权限原则
Bot 应用申请权限时，优先只申请 sheets:spreadsheet:readonly；仅在明确需要写入时才申请 sheets:spreadsheet。创建表格场景可单独申请 sheets:spreadsheet:create 而非完整读写权限。
关键限制
| 限制项 | 值 | 说明 |
|---|---|---|
| 表格标题长度 | 0-255 字符 | 创建/修改时校验 |
| 修改属性频率 | 20 次/分钟 | PATCH /sheets/v3/spreadsheets/:token |
| Range 格式 | <sheetId>!<A1:B2> | sheetId 为工作表 ID，非表格 token |
| 批量读取 | ranges 参数逗号分隔 | values_batch_get 接口 |
| 追加写入模式 | OVERWRITE / INSERT_ROWS | values_append 的 insertDataOption |
| 值渲染选项 | ToString / Formula / FormattedValue / UnformattedValue | 读取时通过 valueRenderOption 指定 |
| 日期渲染选项 | FormattedString | 读取时通过 dateTimeRenderOption 指定 |
| Token 鉴权 | tenant_access_token / user_access_token | 应用身份与用户身份权限范围不同 |