Wecomcli Smartsheet

企业微信智能表格管理

wecom-cli 是企业微信提供的命令行程序，所有操作通过执行 wecom-cli 命令完成。

管理企业微信智能表格的结构（子表、字段/列）和数据（记录）。所有接口支持通过 docid 或 url 二选一定位文档。

调用方式

通过 wecom-cli 调用，品类为 doc：

wecom-cli doc <tool_name> '<json_params>'

返回格式说明

所有接口返回 JSON 对象，包含以下公共字段：

当 errcode 不为 0 时，说明接口调用失败，可重试 1 次；若仍失败，将 errcode 和 errmsg 展示给用户。

---

一、智能表格结构管理

smartsheet_get_sheet

查询文档中所有子表信息，返回 sheet_id、title、类型等。

# 通过 docid 查询
wecom-cli doc smartsheet_get_sheet '{"docid": "DOCID"}'
# 通过 url 查询
wecom-cli doc smartsheet_get_sheet '{"url": "https://doc.weixin.qq.com/smartsheet/xxx"}'

# 智能表格其他接口的 docid/url 传入以此类推

smartsheet_add_sheet

添加空子表。新子表不含视图、记录和字段，需通过其他接口补充。

wecom-cli doc smartsheet_add_sheet '{"docid": "DOCID", "properties": {"title": "新子表"}}'

注意：新建智能表格文档默认已含一个子表，仅需多个子表时调用。

smartsheet_update_sheet

修改子表标题。需提供 sheet_id 和新 title。

wecom-cli doc smartsheet_update_sheet '{"docid": "DOCID", "properties":{"sheet_id":"SHEET_ID", "title":"新子表"}}'

smartsheet_delete_sheet

永久删除子表，操作不可逆。

wecom-cli doc smartsheet_delete_sheet '{"docid": "DOCID", "sheet_id": "SHEETID"}'

smartsheet_get_fields

查询子表的所有字段信息，返回 field_id、field_title、field_type。

wecom-cli doc smartsheet_get_fields '{"docid": "DOCID", "sheet_id": "SHEETID"}'

smartsheet_add_fields

向子表添加一个或多个字段。单个子表最多 150 个字段。

wecom-cli doc smartsheet_add_fields '{"docid": "DOCID", "sheet_id": "SHEETID", "fields": [{"field_title": "任务名称", "field_type": "FIELD_TYPE_TEXT"}]}'

在添加字段前，请先参阅所有字段类型和定义 字段类型参考。

注意：如果是首次创建表并调用这个方法添加字段的情况下，调用本接口前，你必须确认已完成以下操作，否则会多出一个无用的默认列：

1. 已调用 smartsheet_get_fields 查看子表现有字段（新子表会自带一个默认文本字段）

2. 已调用 smartsheet_update_fields 将该默认字段重命名为你需要的第一个字段名 然后在本接口中只传入剩余的字段（不包含第一个字段）。

smartsheet_update_fields

更新字段标题。只能改名，不能改类型（field_type 必须传原始类型）。field_title 不能更新为原值。

wecom-cli doc smartsheet_update_fields '{"docid": "DOCID", "sheet_id": "SHEETID", "fields": [{"field_id": "FIELDID", "field_title": "新标题", "field_type": "FIELD_TYPE_TEXT"}]}'

smartsheet_delete_fields

删除一列或多列字段，操作不可逆。field_id 可通过 smartsheet_get_fields 获取。

wecom-cli doc smartsheet_delete_fields '{"docid": "DOCID", "sheet_id": "SHEETID", "field_ids": ["FIELDID"]}'

---

二、智能表格数据管理

smartsheet_get_records

查询子表全部记录。

• 通过 docid：

wecom-cli doc smartsheet_get_records '{"docid": "DOCID", "sheet_id": "SHEETID"}'

• 或通过 URL：

wecom-cli doc smartsheet_get_records '{"url": "https://doc.weixin.qq.com/smartsheet/xxx", "sheet_id": "SHEETID"}'

参见 API 详情。

smartsheet_add_records 添加一行或多行记录(不带图片或文件)

添加一行或多行记录，单次建议 500 行内。

调用前必须先了解目标表的字段类型（通过 smartsheet_get_fields），重点关注 field_type。对于单选/多选（Option）字段，需注意匹配已有选项的 id。

wecom-cli doc smartsheet_add_records '{"docid": "DOCID", "sheet_id": "SHEETID", "records": [{"values": {"任务名称": [{"type": "text", "text": "完成需求文档"}], "优先级": [{"text": "高"}]}}]}'

各字段类型的值格式参见 单元格值格式参考。

+smartsheet_add_records_auto_file 添加一行或多行记录(带图片或文件)

添加一行或多行记录，单次建议 500 行内。与 smartsheet_add_records 不同之处在于，可支持本地路径传入图片、文件。对于需要添加带图片或文件的记录，请使用此接口。传入后台后，后台将自动存储并转换为image_url。

wecom-cli doc +smartsheet_add_records_auto_file '{"docid":"DOCID","sheet_id":"SHEETID","records":[{"values":{"图片":[{"image_path":"/path/to/image.jpg"}],"文件":[{"file_path":"/path/to/file.txt"}]}}]}'

smartsheet_update_records 更新记录(不带图片或文件)

更新一行或多行记录，单次建议在 500 行内。需提供 record_id（通过 smartsheet_get_records 获取）。支持通过 key_type 指定 values 的 key 使用字段标题或字段 ID：

• CELL_VALUE_KEY_TYPE_FIELD_TITLE：key 为字段标题
• CELL_VALUE_KEY_TYPE_FIELD_ID：key 为字段 ID

wecom-cli doc smartsheet_update_records '{"docid": "DOCID", "sheet_id": "SHEETID", "key_type": "CELL_VALUE_KEY_TYPE_FIELD_TITLE", "records": [{"record_id": "RECORDID", "values": {"任务名称": [{"type": "text", "text": "更新后的内容"}]}}]}'

注意：创建时间、最后编辑时间、创建人、最后编辑人字段不可更新。

+smartsheet_update_records_auto_file 更新记录(更新图片或文件字段)

更新一行或多行记录，单次建议在 500 行内。与 smartsheet_update_records 不同之处在于，可支持本地路径传入图片、文件。对于需要更新记录中的图片或文件，请使用此接口。传入后台后，后台将自动存储并转换为image_url。

wecom-cli doc +smartsheet_update_records_auto_file '{"docid": "DOCID", "sheet_id": "SHEETID", "key_type": "CELL_VALUE_KEY_TYPE_FIELD_TITLE", "records": [{"record_id": "RECORDID", "values": {"values":{"图片":[{"image_path":"/path/to/image.jpg"}],"文件":[{"file_path":"/path/to/file.txt"}]}}}]}'

smartsheet_delete_records

删除一行或多行记录，单次必须在 500 行内。操作不可逆。record_id 通过 smartsheet_get_records 获取。极速版智能表格不支持此接口。

wecom-cli doc smartsheet_delete_records '{"docid": "DOCID", "sheet_id": "SHEETID", "record_ids": ["RECORDID1", "RECORDID2"]}'

---

典型工作流

智能表格结构操作

1. 了解表结构 →

wecom-cli doc smartsheet_get_sheet '{"docid": "DOCID"}'

→

wecom-cli doc smartsheet_get_fields '{"docid": "DOCID", "sheet_id": "SHEETID"}'

2. 创建表结构 → smartsheet_add_sheet 添加子表 → smartsheet_add_fields 定义列 3. 修改表结构 → smartsheet_update_fields 改列名 / smartsheet_delete_fields 删列

智能表格数据操作

1. 读取数据 →

wecom-cli doc smartsheet_get_records '{"docid":"DOCID","sheet_id":"SHEETID"}'

2. 写入数据 → 先 smartsheet_get_fields 了解列类型 → 若涉及成员（USER）字段，先通过 wecomcli-contact 的 get_userlist 查找人员 userid → smartsheet_add_records 写入 3. 更新数据 → 先 smartsheet_get_records 获取 record_id → 若涉及成员（USER）字段，先通过 wecomcli-contact 的 get_userlist 查找人员 userid → smartsheet_update_records 更新 4. 删除数据 → 先 smartsheet_get_records 确认 record_id → smartsheet_delete_records 删除

注意：成员（USER）类型字段需要填写 user_id，不能直接使用姓名。必须先通过 wecomcli-contact 技能的 get_userlist 接口按姓名查找到对应的 userid 后再使用。

单元格值格式参考

smartsheet_add_records、+smartsheet_add_records_auto_file 仅支持字段标题作为key。 smartsheet_update_records、+smartsheet_update_records_auto_file 支持通过 key_type 参数指定使用字段标题（CELL_VALUE_KEY_TYPE_FIELD_TITLE）或字段 ID（CELL_VALUE_KEY_TYPE_FIELD_ID）。

各字段类型的值格式

1. 文本 (FIELD_TYPE_TEXT)

必须使用数组格式，外层方括号不可省略：

"字段标题": [{"type": "text", "text": "内容"}]

2. 数字 (NUMBER) / 货币 (CURRENCY) / 百分比 (PERCENTAGE) / 进度 (PROGRESS)

直接传数字：

"金额": 100,
"完成率": 0.6,
"进度": 80

3. 复选框 (CHECKBOX)

直接传布尔值：

"已完成": true

4. 单选 (SINGLE_SELECT) / 多选 (SELECT)

必须使用数组格式，不能直接传字符串：

"优先级": [{"text": "高"}],
"标签": [{"text": "紧急", "style": 17}, {"text": "重要", "style": 12}]

已存在的选项应通过 id 匹配（id 可从 smartsheet_get_fields 返回中获取），新增选项时不填 id。可附带 style（颜色 1-27），对照表如下：

5. 日期时间 (DATE_TIME)

传日期时间字符串，系统自动按东八区转换：

"截止日期": "2026-01-15 14:30:00",
"创建日期": "2026-01-15"

支持格式：YYYY-MM-DD HH:mm:ss、YYYY-MM-DD HH:mm、YYYY-MM-DD

6. 手机号 (PHONE_NUMBER) / 邮箱 (EMAIL) / 条码 (BARCODE)

直接传字符串：

"电话": "13800138000",
"邮箱": "test@example.com"

7. 成员 (USER)

数组格式，需传 user_id。user_id 不是姓名，必须先通过 wecomcli-contact 技能查找目标人员的 userid，再填入此处。

具体步骤：先

wecom-cli contact get_userlist '{}'

获取通讯录成员列表，在返回结果中按姓名/别名筛选出目标人员，取其 userid 值填入。

"负责人": [{"user_id": "zhangsan"}]

多个成员：

"负责人": [{"user_id": "zhangsan"}, {"user_id": "lisi"}]

8. 超链接 (URL)

数组格式，目前仅支持一个链接：

"参考链接": [{"type": "url", "text": "官网", "link": "https://example.com"}]

9. 图片 (IMAGE)

数组格式，支持传入本地路径：

"封面": [{"image_path": "/path/to/img.png"}]

10. 地理位置 (LOCATION)

数组格式：

"地点": [{"source_type": 1, "id": "地点ID", "latitude": "39.9", "longitude": "116.3", "title": "北京"}]

11. 文件

数组格式：

"文件": [{"file_path": "/path/to/img.png"}]

完整添加记录示例

{
    "docid": "DOCID",
    "sheet_id": "SHEETID",
    "records": [{
        "values": {
            "任务名称": [{"type": "text", "text": "完成需求文档"}],
            "优先级": [{"text": "高"}],
            "截止日期": "2026-03-20",
            "完成进度": 30,
            "已完成": false
        }
    }]
}

智能表格字段类型参考

支持的字段类型

添加字段示例

{
    "docid": "DOCID",
    "sheet_id": "SHEETID",
    "fields": [
        { "field_title": "任务名称", "field_type": "FIELD_TYPE_TEXT" },
        { "field_title": "优先级", "field_type": "FIELD_TYPE_SINGLE_SELECT" },
        { "field_title": "截止日期", "field_type": "FIELD_TYPE_DATE_TIME" },
        { "field_title": "完成进度", "field_type": "FIELD_TYPE_PROGRESS" }
    ]
}

更新字段注意事项

• smartsheet_update_fields 只能更新字段标题，不能更改字段类型
• field_type 必须传字段当前的原始类型
• field_title 不能更新为原值（即不能传与当前相同的标题）

smartsheet_get_records API

查询智能表格中指定子表的记录信息，支持分页读取。支持通过 docid 或文档 URL 定位文档，二者传入其一即可。

技能定义

{
  "name": "smartsheet_get_records",
  "description": "查询智能表格中指定子表的记录信息。支持分页查询（cursor + limit），不填 cursor 从第一行开始。支持通过 docid 或文档 URL 定位文档，二者传入其一即可。",
  "inputSchema": {
    "properties": {
      "cursor": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "description": "查询游标，不填代表从第一行记录开始查询",
        "title": "Cursor"
      },
      "docid": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "description": "文档的 docid，与 url 二选一传入",
        "title": "Docid"
      },
      "limit": {
        "anyOf": [
          {
            "type": "integer"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "description": "分页大小，每页返回多少条数据；当不填写该参数或将该参数设置为 0 时，如果总数大于 1000，一次性返回 1000 行记录，当总数小于 1000 时，返回全部记录；limit 最大值为 1000",
        "title": "Limit"
      },
      "sheet_id": {
        "description": "子表的 sheet_id，用于指定要查询的智能表格中的哪个子表",
        "title": "Sheet Id",
        "type": "string"
      },
      "url": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "description": "文档的访问链接，与 docid 二选一传入",
        "title": "Url"
      }
    },
    "required": [
      "sheet_id"
    ],
    "title": "smartsheet_get_recordsArguments",
    "type": "object"
  }
}

参数说明

请求示例

以传入docid为例：

{
    "docid": "DOCID",
    "sheet_id": "123Abc"
}

以传url为例：

{
    "url": "https://doc.weixin.qq.com/smartsheet/xxx",
    "sheet_id": "123Abc"
}

响应示例（含分页）

{
    "errcode": 0,
    "errmsg": "ok",
    "total": 100,
    "has_more": true,
    "next_cursor": "mock_cursor_token",
    "records": [
        {
            "record_id": "rec_001",
            "create_time": "1700000000000",
            "update_time": "1700000000000",
            "values": {
                "成员": [
                    {"user_id": "real.user001", "id_type": 1}
                ],
                "序号": [
                    {"text": "1", "type": "text"}
                ],
                "附件": [
                    {
                        "doc_type": 2,
                        "file_ext": "xlsx",
                        "file_type": "Wedrive",
                        "file_url": "https://drive.weixin.qq.com/s?k=MOCK_TOKEN",
                        "name": "report.xlsx",
                        "size": 12345
                    }
                ]
            },
            "creator_name": "张三",
            "updater_name": "张三"
        },
        {
            "record_id": "rec_002",
            "create_time": "1700000000000",
            "update_time": "1700000000000",
            "values": {
                "截图": [
                    {
                        "height": 1080,
                        "id": "img_mock_id",
                        "image_url": "https://wdcdn.qpic.cn/mocked_path?w=1920&h=1080",
                        "title": "screenshot_001",
                        "width": 1920
                    }
                ],
                "序号": [
                    {"text": "2", "type": "text"}
                ]
            },
            "creator_name": "张三",
            "updater_name": "李四"
        }
    ]
}

响应数据结构

• total: 总记录数（integer）
• has_more: 是否还有更多数据（boolean）
• next_cursor: 下一页游标，用于分页（string，仅当 has_more 为 true 时存在）
• records: 记录数组

分页查询

# 第一页
wecom-cli doc smartsheet_get_records '{"docid": "DOCID", "sheet_id": "SHEETID"}'

# 下一页（使用上一条的 next_cursor）
wecom-cli doc smartsheet_get_records '{"docid": "DOCID", "sheet_id": "SHEETID", "cursor": "上一条的 next_cursor 值"}'