Files

T

sutong 750f981c7e feat: init media-center skill

资源中心——从多渠道获取资源链接，转存到夸克网盘并整理归档。
- sources/tencent-doc: 腾讯文档读取
- sources/search: 网盘搜索
- storage/quark: 夸克网盘操作
- ref/: 来源 skill 参考归档

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-05-16 18:28:23 +08:00

32 KiB

Raw Blame History

智能表格（SmartSheet）工具完整参考文档

腾讯文档智能表格（SmartSheet）提供了一套完整的表格操作 API，支持对工作表、视图、字段、记录进行增删改查操作。

概念说明

概念	说明
`file_id`	智能表格文档的唯一标识符，每个文档有唯一的 file_id
`sheet_id`	工作表 ID，一个智能表格文档可包含多个工作表
`view_id`	视图 ID，每个工作表可有多个视图（网格视图、看板视图等）
`field_id`	字段 ID，对应表格的列
`record_id`	记录 ID，对应表格的行

层级关系：file_id（文档） → sheet_id（工作表） → view_id（视图） / field_id（字段） / record_id（记录）

工作表（SubSheet）操作

smartsheet.list_tables

功能：列出文档下的所有工作表，返回工作表基本信息列表。

使用场景：

查看一个智能表格文档中有哪些工作表
获取 sheet_id 以便后续操作字段、记录、视图

请求参数：

参数	类型	必填	说明
`file_id`	string	✅	智能表格文档的唯一标识符

返回字段：

字段	类型	说明
`sheets`	array	工作表列表
`sheets[].sheet_id`	string	工作表唯一标识符
`sheets[].title`	string	工作表名称
`sheets[].is_visible`	bool	工作表可见性
`error`	string	错误信息，操作失败时返回
`trace_id`	string	调用链追踪 ID

调用示例：

{
  "file_id": "your_file_id"
}

返回示例：

{
  "sheets": [
    {
      "sheet_id": "sheet_abc123",
      "title": "任务列表",
      "is_visible": true
    },
    {
      "sheet_id": "sheet_def456",
      "title": "已归档",
      "is_visible": false
    }
  ],
  "error": "",
  "trace_id": "trace_xyz"
}

smartsheet.add_table

功能：在文档中新增工作表，支持设置工作表名称和初始配置。

使用场景：

在已有智能表格文档中添加新的工作表（如新增"2024年Q2"工作表）
按业务模块拆分数据到不同工作表

请求参数：

参数	类型	必填	说明
`file_id`	string	✅	智能表格文档的唯一标识符
`properties`	object	✅	工作表属性配置
`properties.sheet_id`	string	✅	工作表名称（注意：此字段实际含义为工作表名称）
`properties.title`	string		工作表标题
`properties.index`	uint32		工作表下标（位置）

返回字段：

字段	类型	说明
`properties`	object	新创建工作表的属性信息
`properties.sheet_id`	string	工作表名称
`properties.title`	string	工作表标题
`properties.index`	uint32	工作表下标
`error`	string	错误信息
`trace_id`	string	调用链追踪 ID

调用示例：

{
  "file_id": "your_file_id",
  "properties": {
    "sheet_id": "新工作表",
    "title": "2024年Q2数据",
    "index": 1
  }
}

smartsheet.delete_table

功能：删除指定的工作表。

使用场景：

删除不再需要的工作表
清理测试数据工作表

请求参数：

参数	类型	必填	说明
`file_id`	string	✅	智能表格文档的唯一标识符
`sheet_id`	string	✅	要删除的工作表 ID

返回字段：

字段	类型	说明
`error`	string	错误信息，操作失败时返回
`trace_id`	string	调用链追踪 ID

调用示例：

{
  "file_id": "your_file_id",
  "sheet_id": "sheet_abc123"
}

视图（View）操作

smartsheet.list_views

功能：列出工作表下的所有视图，返回视图基本信息和配置。

使用场景：

查看工作表有哪些视图（网格视图、看板视图）
获取 view_id 以便按视图筛选记录或字段

请求参数：

参数	类型	必填	说明
`file_id`	string	✅	智能表格文档的唯一标识符
`sheet_id`	string	✅	工作表 ID
`view_ids`	[]string		需要查询的视图 ID 数组，不填则返回全部
`offset`	uint32		分页查询偏移量，默认 0
`limit`	uint32		分页大小，最大 100

返回字段：

字段	类型	说明
`views`	array	视图列表
`views[].view_id`	string	视图唯一标识符
`views[].view_name`	string	视图名称
`views[].view_type`	string	视图类型，枚举值见下方
`total`	uint32	符合条件的视图总数
`hasMore`	bool	是否还有更多项
`next`	uint32	下一页偏移量
`error`	string	错误信息
`trace_id`	string	调用链追踪 ID

视图类型枚举值：

值	说明
`grid`	网格视图
`kanban`	看板视图

调用示例：

{
  "file_id": "your_file_id",
  "sheet_id": "sheet_abc123",
  "offset": 0,
  "limit": 20
}

smartsheet.add_view

功能：在工作表中新增视图，支持自定义视图名称和类型。

使用场景：

为工作表创建看板视图，按状态分组展示任务
创建多个网格视图，分别展示不同筛选条件的数据

请求参数：

参数	类型	必填	说明
`file_id`	string	✅	智能表格文档的唯一标识符
`sheet_id`	string	✅	工作表 ID
`view_title`	string	✅	视图标题
`view_type`	string		视图类型：grid-网格视图，kanban-看板视图

返回字段：

字段	类型	说明
`view_id`	string	新创建的视图 ID
`view_title`	string	视图标题
`view_type`	string	视图类型
`error`	string	错误信息
`trace_id`	string	调用链追踪 ID

调用示例：

{
  "file_id": "your_file_id",
  "sheet_id": "sheet_abc123",
  "view_title": "按状态分组",
  "view_type": "kanban"
}

smartsheet.delete_view

功能：删除指定的视图，支持批量删除多个视图。

使用场景：

删除不再使用的视图
批量清理多余视图

请求参数：

参数	类型	必填	说明
`file_id`	string	✅	智能表格文档的唯一标识符
`sheet_id`	string	✅	工作表 ID
`view_ids`	[]string	✅	要删除的视图 ID 列表

返回字段：

字段	类型	说明
`error`	string	错误信息
`trace_id`	string	调用链追踪 ID

调用示例：

{
  "file_id": "your_file_id",
  "sheet_id": "sheet_abc123",
  "view_ids": ["view_id1", "view_id2"]
}

字段（Field）操作

smartsheet.list_fields

功能：列出工作表的所有字段，返回字段基本信息和类型配置。

使用场景：

查看工作表有哪些列（字段）及其类型
获取 field_id 以便后续更新或删除字段
在写入记录前，先了解字段结构和类型

请求参数：

参数	类型	必填	说明
`file_id`	string	✅	智能表格文档的唯一标识符
`sheet_id`	string	✅	工作表 ID
`view_id`	string		视图 ID，按视图筛选字段
`field_ids`	[]string		指定字段 ID 数组
`field_titles`	[]string		指定字段标题数组
`offset`	uint32		偏移量，初始值为 0
`limit`	uint32		分页大小，最大 100；不填或为 0 时，总数 >100 返回 100 条，否则返回全部

返回字段：

字段	类型	说明
`total`	uint32	符合条件的字段总数
`has_more`	bool	是否还有更多项
`next`	uint32	下一页偏移量
`fields`	array	字段列表，详见 FieldInfo 结构

FieldInfo 结构：

字段	类型	说明
`field_id`	string	字段唯一 ID
`field_title`	string	字段标题（列名）
`field_type`	string	字段类型，枚举值见下方
`property_*`	object	字段属性，根据 field_type 不同而不同

调用示例：

{
  "file_id": "your_file_id",
  "sheet_id": "sheet_abc123"
}

smartsheet.add_fields

功能：批量新增字段（列），支持同时添加多个不同类型的字段。

使用场景：

为工作表添加新列，如"优先级"（单选）、"截止日期"（日期）、"负责人"（用户）
初始化工作表结构

请求参数：

参数	类型	必填	说明
`file_id`	string	✅	智能表格文档的唯一标识符
`sheet_id`	string	✅	工作表 ID
`fields`	[]FieldInfo	✅	要添加的字段列表

FieldInfo 参数说明：

字段	类型	必填	说明
`field_title`	string	✅	字段标题（列名）
`field_type`	string	✅	字段类型，枚举值见下方
`property_text`	object		文本类型属性（无需额外配置）
`property_number`	object		数字类型属性
`property_checkbox`	object		复选框类型属性
`property_date_time`	object		日期时间类型属性
`property_url`	object		超链接类型属性
`property_select`	object		多选类型属性
`property_single_select`	object		单选类型属性
`property_progress`	object		进度类型属性

返回字段：

字段	类型	说明
`fields`	array	添加成功的字段列表（含 field_id）
`error`	string	错误信息
`trace_id`	string	调用链追踪 ID

调用示例（添加多种类型字段）：

{
  "file_id": "your_file_id",
  "sheet_id": "sheet_abc123",
  "fields": [
      {
        "field_title": "任务名称",
        "field_type": "text",
        "property_text": {}
      },
      {
        "field_title": "优先级",
        "field_type": "singleSelect",
        "property_single_select": {
          "options": [
            { "text": "高", "style": 1 },
            { "text": "中", "style": 3 },
            { "text": "低", "style": 4 }
          ]
        }
      },
      {
        "field_title": "截止日期",
        "field_type": "dateTime",
        "property_date_time": {
          "format": "yyyy-mm-dd",
          "auto_fill": false
        }
      },
      {
        "field_title": "完成进度",
        "field_type": "progress",
        "property_progress": {
          "decimal_places": 0
        }
      },
      {
        "field_title": "是否完成",
        "field_type": "checkbox",
        "property_checkbox": {
          "checked": false
        }
      }
    ]
}

smartsheet.update_fields

功能：批量更新字段属性，支持修改字段名称和配置信息。

使用场景：

修改字段标题（列名）
更新单选/多选字段的选项列表
修改数字字段的精度配置

⚠️ 注意：field_type（字段类型）不允许被更新，但更新时必须传入原字段类型值。

请求参数：

参数	类型	必填	说明
`file_id`	string	✅	智能表格文档的唯一标识符
`sheet_id`	string	✅	工作表 ID
`fields`	[]FieldInfo	✅	要更新的字段列表，必须包含 field_id

返回字段：

字段	类型	说明
`fields`	array	更新成功的字段列表
`error`	string	错误信息
`trace_id`	string	调用链追踪 ID

调用示例（修改字段标题和选项）：

{
  "file_id": "your_file_id",
  "sheet_id": "sheet_abc123",
  "fields": [
      {
        "field_id": "field_id_001",
        "field_title": "任务状态",
        "field_type": "singleSelect",
        "property_single_select": {
          "options": [
            { "text": "待处理", "style": 7 },
            { "text": "进行中", "style": 3 },
            { "text": "已完成", "style": 4 },
            { "text": "已取消", "style": 1 }
          ]
        }
      }
    ]
}

smartsheet.delete_fields

功能：批量删除字段（列），支持同时删除多个字段。

使用场景：

删除不再需要的列
清理冗余字段

请求参数：

参数	类型	必填	说明
`file_id`	string	✅	智能表格文档的唯一标识符
`sheet_id`	string	✅	工作表 ID
`field_ids`	[]string	✅	要删除的字段 ID 数组

返回字段：

字段	类型	说明
`error`	string	错误信息
`trace_id`	string	调用链追踪 ID

调用示例：

{
  "file_id": "your_file_id",
  "sheet_id": "sheet_abc123",
  "field_ids": ["field_id_001", "field_id_002"]
}

记录（Record）操作

smartsheet.list_records

功能：分页列出工作表记录（行），支持排序和按字段筛选。

使用场景：

读取工作表中的数据
按特定字段排序查看数据
分页获取大量数据

请求参数：

参数	类型	必填	说明
`file_id`	string	✅	智能表格文档的唯一标识符
`sheet_id`	string	✅	工作表 ID
`view_id`	string		视图 ID，按视图筛选记录
`record_ids`	[]string		指定记录 ID 数组，精确查询
`field_titles`	[]string		只返回指定字段标题的值，不填则返回全部字段
`sort`	[]Sort		排序配置
`offset`	uint32		偏移量，初始值为 0
`limit`	uint32		分页大小，最大 100；不填或为 0 时，总数 >100 返回 100 条，否则返回全部

Sort 排序配置：

字段	类型	必填	说明
`field_title`	string	✅	需要排序的字段标题
`desc`	bool		是否降序，默认 false（升序）

返回字段：

字段	类型	说明
`total`	uint32	符合条件的记录总数
`has_more`	bool	是否还有更多项
`next`	uint32	下一页偏移量
`records`	array	记录列表，详见 RecordInfo 结构
`error`	string	错误信息
`trace_id`	string	调用链追踪 ID

RecordInfo 结构：

字段	类型	说明
`record_id`	string	记录唯一 ID
`field_values`	array	字段值列表，每个元素为 FieldValueEntry，包含 `field`（字段标题）和对应的值（oneof）

FieldValueEntry 结构：

字段	类型	说明
`field`	string	字段标题（必填）
`number_value`	double	数字类型的值，用于数字、进度、货币、百分数等字段
`string_value`	string	字符串类型的值，用于日期(毫秒级unix时间戳)、电话、邮箱等字段
`bool_value`	bool	布尔类型的值，用于复选框字段
`text_value`	TextValueList	文本类型的值列表，用于文本字段
`url_value`	UrlValueList	超链接类型的值列表，用于超链接字段
`option_value`	OptionValueList	选项类型的值列表，用于多选、单选字段
`image_value`	ImageIDValueList	图片类型的值列表，用于图片字段
`auto_number_value`	AutoNumberValue	自动编号类型的值，用于自动编号字段
`reference_value`	StringValueList	关联记录ID列表，用于关联字段

⚠️ 注意：field 之外的值字段为 oneof 关系，每个 FieldValueEntry 只能设置其中一个值字段。

调用示例：

{
  "file_id": "your_file_id",
  "sheet_id": "sheet_abc123",
  "field_titles": ["任务名称", "优先级", "截止日期"],
  "sort": [
    { "field_title": "截止日期", "desc": false }
  ],
  "offset": 0,
  "limit": 50
}

smartsheet.add_records

功能：批量添加记录（行），支持同时添加多条记录数据。

使用场景：

批量导入数据到工作表
添加新任务、新条目
从其他数据源同步数据

请求参数：

参数	类型	必填	说明
`file_id`	string	✅	智能表格文档的唯一标识符
`sheet_id`	string	✅	工作表 ID
`records`	[]AddRecord	✅	要添加的记录列表

AddRecord 结构：

字段	类型	必填	说明
`field_values`	[]FieldValueEntry	✅	字段值列表，每个元素包含 `field`（字段标题）和对应的值（oneof），格式见下方

返回字段：

字段	类型	说明
`records`	array	添加成功的记录列表（含 record_id）
`error`	string	错误信息
`trace_id`	string	调用链追踪 ID

调用示例：

{
  "file_id": "your_file_id",
  "sheet_id": "sheet_abc123",
  "records": [
      {
        "field_values": [
          {"field": "任务名称", "text_value": {"items": [{"text": "完成需求文档", "type": "text"}]}},
          {"field": "优先级", "option_value": {"items": [{"text": "高"}]}},
          {"field": "截止日期", "string_value": "1720000000000"},
          {"field": "完成进度", "number_value": 30},
          {"field": "是否完成", "bool_value": false}
        ]
      },
      {
        "field_values": [
          {"field": "任务名称", "text_value": {"items": [{"text": "代码评审", "type": "text"}]}},
          {"field": "优先级", "option_value": {"items": [{"text": "中"}]}},
          {"field": "截止日期", "string_value": "1720086400000"},
          {"field": "完成进度", "number_value": 0},
          {"field": "是否完成", "bool_value": false}
        ]
      }
    ]
}

smartsheet.update_records

功能：批量更新记录，支持修改多条记录的字段值。

使用场景：

更新任务状态、进度
修改记录中的某些字段值
批量修改多条数据

请求参数：

参数	类型	必填	说明
`file_id`	string	✅	智能表格文档的唯一标识符
`sheet_id`	string	✅	工作表 ID
`records`	[]RecordInfo	✅	要更新的记录列表，必须包含 record_id

RecordInfo 参数说明：

字段	类型	必填	说明
`record_id`	string	✅	记录 ID，标识要更新哪条记录
`field_values`	[]FieldValueEntry	✅	要更新的字段值列表，每个元素包含 `field`（字段标题）和对应的值

返回字段：

字段	类型	说明
`error`	string	错误信息
`trace_id`	string	调用链追踪 ID

调用示例：

{
  "file_id": "your_file_id",
  "sheet_id": "sheet_abc123",
  "records": [
      {
        "record_id": "record_id_001",
        "field_values": [
          {"field": "完成进度", "number_value": 100},
          {"field": "是否完成", "bool_value": true},
          {"field": "优先级", "option_value": {"items": [{"text": "高"}]}}
        ]
      }
    ]
}

smartsheet.delete_records

功能：批量删除记录（行），支持同时删除多条指定的记录。

使用场景：

删除已完成或过期的任务记录
清理测试数据
批量删除多条记录

请求参数：

参数	类型	必填	说明
`file_id`	string	✅	智能表格文档的唯一标识符
`sheet_id`	string	✅	工作表 ID
`record_ids`	[]string	✅	要删除的记录 ID 列表

返回字段：

字段	类型	说明
`error`	string	错误信息
`trace_id`	string	调用链追踪 ID

调用示例：

{
  "file_id": "your_file_id",
  "sheet_id": "sheet_abc123",
  "record_ids": ["record_id_001", "record_id_002", "record_id_003"]
}

枚举值参考

字段类型（field_type）

枚举值	类型名称	对应 property 字段	说明
`text`	文本	`property_text`	普通文本，无需额外配置
`number`	数字	`property_number`	整数或浮点数
`checkbox`	复选框	`property_checkbox`	布尔值 true/false
`dateTime`	日期	`property_date_time`	毫秒时间戳字符串
`image`	图片	`property_image`	图片 ID 数组
`url`	超链接	`property_url`	URL 数组
`select`	多选	`property_select`	选项数组（可多选）
`createdUser`	创建人	`property_user`	系统自动填充，无需配置
`modifiedUser`	最后编辑人	`property_modified_user`	系统自动填充，无需配置
`createdTime`	创建时间	`property_created_time`	系统自动填充，无需配置
`modifiedTime`	最后编辑时间	`property_modified_time`	系统自动填充，无需配置
`progress`	进度	`property_progress`	整数或浮点数（百分比）
`phoneNumber`	电话	`property_phone_number`	字符串，无需额外配置
`email`	邮件	`property_email`	字符串，无需额外配置
`singleSelect`	单选	`property_single_select`	选项数组（只能单选）
`reference`	关联	-	关联其他记录，值为 record_id 字符串数组
`autoNumber`	自动编号	-	系统自动生成编号，无需手动配置
`currency`	货币	-	浮点数，表示货币金额
`percentage`	百分比	-	浮点数，如 0.75 表示 75%

视图类型（view_type）

枚举值	说明
`grid`	网格视图 - 传统表格形式
`kanban`	看板视图 - 按列分组展示

选项颜色（style）

枚举值	颜色
`1`	红色
`2`	橘黄色
`3`	蓝色
`4`	绿色
`5`	紫色
`6`	粉色
`7`	灰色
`8`	白色

超链接展示样式（UrlFieldProperty.type）

枚举值	说明
`0`	未知
`1`	文字
`2`	图标文字

字段值格式参考

在 add_records 和 update_records 中，field_values 是一个 FieldValueEntry 数组，每个元素包含 field（字段标题）和一个 oneof 值字段。根据字段类型选择对应的值字段：

字段类型	使用的 oneof 值字段	示例
文本（text）	`text_value`	`{"field": "标题", "text_value": {"items": [{"text": "内容", "type": "text"}]}}`
数字（number）	`number_value`	`{"field": "数量", "number_value": 42}`
复选框（checkbox）	`bool_value`	`{"field": "已完成", "bool_value": true}`
日期（dateTime）	`string_value`	`{"field": "日期", "string_value": "1720000000000"}`
图片（image）	`image_value`	`{"field": "封面", "image_value": {"items": [{"image_id": "图片id"}]}}`
超链接（url）	`url_value`	`{"field": "链接", "url_value": {"items": [{"text": "链接文字", "type": "url", "link": "https://..."}]}}`
多选（select）	`option_value`	`{"field": "标签", "option_value": {"items": [{"text": "选项1"}, {"text": "选项2"}]}}`
进度（progress）	`number_value`	`{"field": "进度", "number_value": 75}`
电话（phoneNumber）	`string_value`	`{"field": "电话", "string_value": "13800138000"}`
邮件（email）	`string_value`	`{"field": "邮箱", "string_value": "user@example.com"}`
单选（singleSelect）	`option_value`	`{"field": "状态", "option_value": {"items": [{"text": "选项文字"}]}}`
关联（reference）	`reference_value`	`{"field": "关联", "reference_value": {"items": ["record_id_1", "record_id_2"]}}`
自动编号（autoNumber）	`auto_number_value`	`{"field": "编号", "auto_number_value": {"seq": "1", "text": "编号内容"}}`
货币（currency）	`number_value`	`{"field": "金额", "number_value": 99.99}`
百分比（percentage）	`number_value`	`{"field": "占比", "number_value": 0.75}`

TextValueList 结构

{
  "items": [
    {"text": "文本内容", "type": "text"}
  ]
}

UrlValueList 结构

{
  "items": [
    {"text": "链接显示文字", "type": "url", "link": "https://example.com"}
  ]
}

OptionValueList 结构

{
  "items": [
    {"id": "选项ID（可选）", "text": "选项文字", "style": "3"}
  ]
}

ImageIDValueList 结构

{
  "items": [
    {"image_id": "图片ID"}
  ]
}

StringValueList 结构（关联字段）

{
  "items": ["record_id_1", "record_id_2"]
}

AutoNumberValue 结构

{
  "seq": "1",
  "text": "编号内容"
}

⚠️ 注意：写入记录时，单选/多选字段的 text 必须与字段属性中已定义的选项文字完全匹配，否则可能写入失败。

字段属性（Property）详细说明

NumberFieldProperty（数字字段属性）

{
  "decimal_places": 2,
  "use_separate": true
}

字段	类型	说明
`decimal_places`	uint32	小数点位数（精度）
`use_separate`	bool	是否使用千位符（如 1,000）

CheckboxFieldProperty（复选框字段属性）

{
  "checked": false
}

字段	类型	说明
`checked`	bool	新增记录时是否默认勾选

DateTimeFieldProperty（日期时间字段属性）

{
  "format": "yyyy-mm-dd",
  "auto_fill": false
}

字段	类型	说明
`format`	string	日期格式，支持格式见下方
`auto_fill`	bool	新建记录时是否自动填充当前时间

支持的日期格式：

格式字符串	示例
`yyyy"年"m"月"d"日"`	2018 年 4 月 20 日
`yyyy-mm-dd`	2018-04-20
`yyyy/m/d`	2018/4/20
`m"月"d"日"`	4 月 20 日
`[$-804]yyyy"年"m"月"d"日" dddd`	2018 年 4 月 20 日星期五
`yyyy"年"m"月"d"日" hh:mm`	2018 年 4 月 20 日 14:00
`yyyy-mm-dd hh:mm`	2018-04-20 14:00
`m/d/yyyy`	4/20/2018
`d/m/yyyy`	20/4/2018

UrlFieldProperty（超链接字段属性）

{
  "type": 1
}

字段	类型	说明
`type`	uint32	展示样式：0-未知，1-文字，2-图标文字

SelectFieldProperty（多选字段属性）

{
  "options": [
    { "id": "opt_001", "text": "选项A", "style": 3 },
    { "id": "opt_002", "text": "选项B", "style": 4 }
  ],
  "is_multiple": true,
  "is_quick_add": false
}

字段	类型	说明
`options`	[]Option	选项列表
`is_multiple`	bool	是否多选（系统参数，用户无需设置）
`is_quick_add`	bool	是否允许填写时新增选项（系统参数，用户无需设置）

SingleSelectFieldProperty（单选字段属性）

结构与 SelectFieldProperty 相同，但只允许单选。

ProgressFieldProperty（进度字段属性）

{
  "decimal_places": 0
}

字段	类型	说明
`decimal_places`	uint32	小数位数

典型工作流示例

工作流一：从零创建表

步骤 1：获取文档的工作表列表
  → smartsheet.list_tables（获取 sheet_id）

步骤 2：为工作表添加字段
  → smartsheet.add_fields（添加：任务名称、优先级、负责人、截止日期、状态、进度）

步骤 3：批量添加任务记录
  → smartsheet.add_records（写入多条任务数据）

步骤 4：删除默认空行和默认列
  → smartsheet.list_records（获取建表时自动生成的空行 record_id 列表）
  → smartsheet.delete_records（传入空行 record_ids，批量删除默认空行）
  → smartsheet.list_fields（获取建表时自动生成的默认列 field_id 列表）
  → smartsheet.delete_fields（传入默认列 field_ids，批量删除默认列）

步骤 5：（可选）创建看板视图
→ smartsheet.add_view（view_type="kanban"，按状态分组）

工作流二：查询并更新任务状态

步骤 1：列出工作表
  → smartsheet.list_tables（获取 sheet_id）

步骤 2：查询记录
  → smartsheet.list_records（获取 record_id 和当前字段值）

步骤 3：更新指定记录
  → smartsheet.update_records（传入 record_id 和新的字段值）

工作流三：读取数据并分析

步骤 1：列出工作表
  → smartsheet.list_tables

步骤 2：了解字段结构
  → smartsheet.list_fields（了解有哪些列及其类型）

步骤 3：分页读取所有记录
  → smartsheet.list_records（offset=0, limit=100）
  → 若 has_more=true，继续请求下一页（offset=100）

步骤 4：处理数据
  → 根据 field_values 中的数据进行统计分析

工作流四：清理过期数据

步骤 1：列出工作表
  → smartsheet.list_tables

步骤 2：查询需要删除的记录
  → smartsheet.list_records（获取目标 record_id 列表）

步骤 3：批量删除记录
  → smartsheet.delete_records（传入 record_ids 数组）

📌 提示：所有操作都需要先获取 file_id（智能表格文档 ID）和 sheet_id（工作表 ID）。可通过 manage.search_file 搜索文档获取 file_id，再通过 smartsheet.list_tables 获取 sheet_id。

注意事项

前置条件：所有 smartsheet.* 工具都需要 file_id 和 sheet_id，操作前先调用 smartsheet.list_tables 获取 sheet_id
图片字段写入：向图片类型字段（field_type=image）写入数据时，需先调用 upload_image 工具上传图片获取 image_id，再以 [{"image_id": "xxx"}] 格式填入字段值
字段类型不可变：update_fields 时 field_type 不能修改，但必须传入原值；支持的字段类型详见字段类型枚举表
记录字段值格式：不同字段类型的值格式不同，详见上方"字段值格式参考"章节

32 KiB Raw Blame History Unescape Escape

智能表格（SmartSheet）工具完整参考文档

目录

概念说明

工作表（SubSheet）操作

smartsheet.list_tables

smartsheet.add_table

smartsheet.delete_table

视图（View）操作

smartsheet.list_views

smartsheet.add_view

smartsheet.delete_view

字段（Field）操作

smartsheet.list_fields

smartsheet.add_fields

smartsheet.update_fields

smartsheet.delete_fields

记录（Record）操作

smartsheet.list_records

smartsheet.add_records

smartsheet.update_records

smartsheet.delete_records

枚举值参考

字段类型（field_type）

视图类型（view_type）

选项颜色（style）

超链接展示样式（UrlFieldProperty.type）

字段值格式参考

TextValueList 结构

UrlValueList 结构

OptionValueList 结构

ImageIDValueList 结构

StringValueList 结构（关联字段）

AutoNumberValue 结构

字段属性（Property）详细说明

NumberFieldProperty（数字字段属性）

CheckboxFieldProperty（复选框字段属性）

DateTimeFieldProperty（日期时间字段属性）

UrlFieldProperty（超链接字段属性）

SelectFieldProperty（多选字段属性）

SingleSelectFieldProperty（单选字段属性）

ProgressFieldProperty（进度字段属性）

典型工作流示例

工作流一：从零创建表

工作流二：查询并更新任务状态

工作流三：读取数据并分析

工作流四：清理过期数据

注意事项

32 KiB

Raw Blame History