wecom-smartsheet

企业微信智能表格管理

wecom_mcp 是一个 MCP tool，所有操作通过调用该 tool 完成。

⚠️ 前置条件：首次调用 wecom_mcp 前，必须按 wecom-preflight 技能执行前置条件检查，确保工具已加入白名单。

资源型技能，负责智能表格（/smartsheet/*，doc_type=10）的新建、结构（子表、字段/列）与数据（记录）管理。所有接口支持通过 docid 或 url 二选一定位文档。

调用方式

通过 wecom_mcp tool 调用，品类名为 doc：

使用 wecom_mcp tool 调用 wecom_mcp call doc <tool_name> '<json_params>' 调用指定技能

智能表格各接口的 docid/url 二选一传入即可，以下示例以 docid 为主，URL 传入方式以此类推。

返回格式说明

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

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

特殊错误码

接口路由表

硬规则：第二列是 references/xxx.md 链接的，命中这一行后先 read 对应 references 文件，再构造命令。写入/读取记录前，先用 smartsheet_get_sheet 拿到目标子表的 sheet_id，并用 smartsheet_get_fields 了解字段类型。

---

一、新建智能表格

create_doc — 新建智能表格

从零新建一篇企微智能表格（doc_type=10）：空白。创建成功后返回 docid 和 url。

使用 wecom_mcp tool 调用 wecom_mcp call doc create_doc '{"doc_type": 10, "doc_name": "任务跟踪表"}'

参数

注意事项

• 新建智能表格文档默认已含一个子表，可通过 smartsheet_get_sheet 查询其 sheet_id，仅需多个子表时才调用 smartsheet_add_sheet。
• docid 仅在创建时返回，后续无法再获取，务必保存。

---

二、智能表格结构管理

smartsheet_get_sheet — 查询子表

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

• 通过 docid：使用 wecom_mcp tool 调用 wecom_mcp call doc smartsheet_get_sheet '{"docid": "DOCID"}'
• 通过 URL：使用 wecom_mcp tool 调用 wecom_mcp call doc smartsheet_get_sheet '{"url": "https://doc.weixin.qq.com/smartsheet/xxx"}'

smartsheet_add_sheet — 添加子表

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

使用 wecom_mcp tool 调用 wecom_mcp call doc smartsheet_add_sheet '{"docid": "DOCID", "properties": {"title": "新子表"}}'

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

smartsheet_update_sheet — 修改子表标题

需提供 sheet_id 和新 title。

使用 wecom_mcp tool 调用 wecom_mcp call doc smartsheet_update_sheet '{"docid": "DOCID", "properties": {"sheet_id": "SHEET_ID", "title": "新子表"}}'

smartsheet_delete_sheet — 删除子表

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

使用 wecom_mcp tool 调用 wecom_mcp call doc smartsheet_delete_sheet '{"docid": "DOCID", "sheet_id": "SHEETID"}'

smartsheet_get_fields — 查询字段

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

使用 wecom_mcp tool 调用 wecom_mcp call doc smartsheet_get_fields '{"docid": "DOCID", "sheet_id": "SHEETID"}'

smartsheet_add_fields — 添加字段

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

使用 wecom_mcp tool 调用 wecom_mcp call 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_mcp tool 调用 wecom_mcp call 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_mcp tool 调用 wecom_mcp call doc smartsheet_delete_fields '{"docid": "DOCID", "sheet_id": "SHEETID", "field_ids": ["FIELDID"]}'

---

三、智能表格数据管理

smartsheet_get_records — 查询记录

查询子表全部记录。

• 通过 docid：使用 wecom_mcp tool 调用 wecom_mcp call doc smartsheet_get_records '{"docid": "DOCID", "sheet_id": "SHEETID"}'
• 或通过 URL：使用 wecom_mcp tool 调用 wecom_mcp call doc smartsheet_get_records '{"url": "https://doc.weixin.qq.com/smartsheet/xxx", "sheet_id": "SHEETID"}'

参见 API 详情。

smartsheet_add_records — 添加记录（不带图片或文件）

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

调用前必须先了解目标表的字段类型（通过 smartsheet_get_fields），并查看单元格值格式参考，了解做法后再实施。对于单选/多选（Option）字段，需注意匹配已有选项的 id。

使用 wecom_mcp tool 调用 wecom_mcp call doc smartsheet_add_records '{"docid": "DOCID", "sheet_id": "SHEETID", "records": [{"values": {"任务名称": [{"type": "text", "text": "完成需求文档"}], "优先级": [{"text": "高"}]}}]}'

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

⚠️ 图片（IMAGE）/ 文件（ATTACHMENT）字段：必须且只能直接在 cell value 中传入本地路径（image_path / file_path），格式见下方示例。严禁调用 upload_doc_image、upload_doc_file 或任何上传接口，严禁进行 base64 编码——无论文件大小、无论 API 返回何种错误，均不得绕过此规则。若 image_path / file_path 方式返回错误，应直接将错误码和错误信息告知用户，不得尝试其他上传方式。

图片字段示例："封面": [{"image_path": "/path/to/img.png", "title": "图片标题"}] 文件字段示例："文件": [{"file_path": "/path/to/file.pdf"}]

⚠️ 若返回 errcode: 851003 或 errmsg 包含 no authority，无文档权限。在编辑场景，通常是因为机器人不允许编辑由企业成员创建的文档。在智能表格写入场景下，若该报错发生在 smartsheet_add_records / smartsheet_update_records，可引导用户走 Webhook 兜底方案，详见 webhook-fallback.md。注意 Webhook 只能更新通过 Webhook 写入的记录，人工创建的记录无法更新。

smartsheet_add_records_auto_file — 添加记录（带图片或文件）

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

使用 wecom_mcp tool 调用 wecom_mcp call 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 — 更新记录（不带图片或文件）

调用前必须先了解目标表的字段类型（通过 smartsheet_get_fields），并查看单元格值格式参考，了解做法后再实施。

更新一行或多行记录，单次建议在 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_mcp tool 调用 wecom_mcp call 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": "更新后的内容"}]}}]}'

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

⚠️ 图片（IMAGE）/ 文件（ATTACHMENT）字段：必须且只能直接在 cell value 中传入本地路径（image_path / file_path），格式见下方示例。严禁调用 upload_doc_image、upload_doc_file 或任何上传接口，严禁进行 base64 编码——无论文件大小、无论 API 返回何种错误，均不得绕过此规则。若 image_path / file_path 方式返回错误，应直接将错误码和错误信息告知用户，不得尝试其他上传方式。

图片字段示例："封面": [{"image_path": "/path/to/img.png", "title": "图片标题"}] 文件字段示例："文件": [{"file_path": "/path/to/file.pdf"}]

⚠️ 若返回 errcode: 851003 或 errmsg 包含 no authority，无文档权限。在编辑场景，通常是因为机器人不允许编辑由企业成员创建的文档。在智能表格写入场景下，若该报错发生在 smartsheet_add_records / smartsheet_update_records，可引导用户走 Webhook 兜底方案，详见 webhook-fallback.md。注意 Webhook 只能更新通过 Webhook 写入的记录，人工创建的记录无法更新。

smartsheet_update_records_auto_file — 更新记录（更新图片或文件字段）

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

使用 wecom_mcp tool 调用 wecom_mcp call doc smartsheet_update_records_auto_file '{"docid": "DOCID", "sheet_id": "SHEETID", "key_type": "CELL_VALUE_KEY_TYPE_FIELD_TITLE", "records": [{"record_id": "RECORDID", "values": {"图片":[{"image_path":"/path/to/image.jpg"}],"文件":[{"file_path":"/path/to/file.txt"}]}}]}'

smartsheet_delete_records — 删除记录

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

使用 wecom_mcp tool 调用 wecom_mcp call doc smartsheet_delete_records '{"docid": "DOCID", "sheet_id": "SHEETID", "record_ids": ["RECORDID1", "RECORDID2"]}'

---

典型工作流

新建并搭建表结构

1. 新建智能表格 → 使用 wecom_mcp tool 调用 wecom_mcp call doc create_doc '{"doc_type": 10, "doc_name": "项目任务表"}'，保存返回的 docid
2. 了解默认子表 → smartsheet_get_sheet 拿到默认子表的 sheet_id → smartsheet_get_fields 查看默认字段
3. 搭建列 → 先 smartsheet_update_fields 改默认字段名，再 smartsheet_add_fields 补充其余字段

智能表格结构操作

1. 了解表结构 → 使用 wecom_mcp tool 调用 wecom_mcp call doc smartsheet_get_sheet '{"docid": "DOCID"}' → 使用 wecom_mcp tool 调用 wecom_mcp call 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_mcp tool 调用 wecom_mcp call doc smartsheet_get_records '{"docid":"DOCID","sheet_id":"SHEETID"}'
2. 写入数据 → 先 smartsheet_get_fields 了解列类型 → 若涉及成员（USER）字段，先通过 wecom-contact 的 get_userlist 查找人员 userid → smartsheet_add_records 写入
3. 更新数据 → 先 smartsheet_get_records 获取 record_id → 若涉及成员（USER）字段，先通过 wecom-contact 的 get_userlist 查找人员 userid → smartsheet_update_records 更新
4. 写入失败 fallback → 第 2/3 步返回 errcode: 851003 / no authority，无文档权限。在编辑场景，通常是因为机器人不允许编辑由企业成员创建的文档。在智能表格写入场景下，若该报错发生在 smartsheet_add_records / smartsheet_update_records，可引导用户走 Webhook 兜底方案，详见 webhook-fallback.md。注意 Webhook 只能更新通过 Webhook 写入的记录，人工创建的记录无法更新
5. 若涉及**图片（IMAGE）或文件（ATTACHMENT）**字段，必须且只能直接在 cell value 中传入本地路径（image_path / file_path）。严禁调用 upload_doc_image、upload_doc_file 或任何上传接口，严禁进行 base64 编码——无论文件大小、无论 API 返回何种错误，均不得绕过此规则。若返回错误，直接将错误码和错误信息告知用户，不得尝试其他上传方式。传入格式参考 单元格值格式参考。
6. 删除数据 → 先 smartsheet_get_records 确认 record_id → smartsheet_delete_records 删除

跨技能依赖

注意：成员（USER）类型字段需要填写 user_id，不能直接使用姓名。必须先通过 wecom-contact 技能的 get_userlist 接口按姓名查找到对应的 userid 后再使用。 注意：图片（IMAGE）或文件（ATTACHMENT）字段必须且只能直接在 cell value 中传入本地路径（image_path / file_path）。严禁调用 upload_doc_image、upload_doc_file 或任何上传接口，严禁进行 base64 编码——无论文件大小、无论 API 返回何种错误，均不得绕过此规则。若返回错误，直接将错误码和错误信息告知用户，不得尝试其他上传方式。格式参考 单元格值格式参考。