wecomcli-sheet

name	wecomcli-sheet
description	企业微信在线表格文档管理：新建在线表格、导入 CSV/Excel 为在线表格、读取表格信息与数据、修改表格内容、追加行数据、子表管理。当用户提到'表格'、'在线表格'、'excel表格'这些关键词触发，或链接形如 https://doc.weixin.qq.com/sheet/xxx 时触发。文档公共操作请使用 wecomcli-doc-manage；doc文档操作请使用 wecomcli-doc；智能表格内容 CRUD 请使用 wecomcli-smartsheet。

wecom-cli 是插件提供的 tool，不是终端命令：所有操作都通过调用该 tool 完成，参数应使用 args 传入，禁止通过 exec / shell / 终端等命令行方式使用。

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

企业微信在线表格管理

资源型 skill，负责在线表格（sheet）的新建、导入与内容读写及子表管理。

适用范围

适用

• 新建 / 导入企微在线表格
• 读取 / 修改 / 追加在线表格内容
• 添加 / 删除在线表格子表

不适用

• 搜索文档 / 修改文档权限 / 重命名 / 加成员 → 改用 wecomcli-doc-manage
• 用户给的链接是 https://doc.weixin.qq.com/smartsheet/... → 改用 wecomcli-smartsheet
• 若遇到的 docid 以 s3 开头（形如 s3_xxxx）→ 改用 wecomcli-smartsheet

接口路由表

硬规则：第二列是 references/xxx.md 链接的, 命中这一行后先 read 对应 references 文件，再构造命令。

用户意图	参考位置
新建在线表格	见下方「新建在线表格」
导入本地 CSV / Excel 文件为企微在线表格	见下方「导入在线表格」
读取在线表格基础信息与子表列表	见下方「读取在线表格」
读取在线表格子表数据	references/sheet-ranges-get.md
修改在线表格指定区域内容	references/sheet-contents-update.md
在线表格末尾追加一行数据	references/sheet-rows-append.md
添加在线表格子工作表	references/sheet-subsheets-add.md
删除在线表格子工作表	references/sheet-subsheets-delete.md

接口详述

新建在线表格

从零新建一篇企微在线表格：空白，或带初始数据（二维表格数据）。本接口不接受任何文件路径参数——"用本地文件建/导入"走「导入在线表格」。

调用方式

使用 wecom-cli 工具按照下面格式调用

wecom-cli sheet create --json '<JSON 参数>'

参数

字段	类型	必填	默认值	语义
doc_name	string	是	—	表格标题
grid_data	object	否	—	默认子表初始化数据；子结构见下方

grid_data 对象结构：

子字段	类型	必填	默认值	语义
start_row / start_column	int	否	0	起始行 / 列号，从 0 起
rows	array	否	—	各行数据；每项 values 为单元格数组
rows[].values[].cell_value	object	否	—	单元格值，见下方「cell_value 类型选择」
rows[].values[].data_type	string	否	—	枚举：TEXT / NUMBER / LINK / FORMULA

cell_value 类型选择

硬规则：选择 cell_value 形态后，必须同时把同级的 data_type 设置为下表对应值。

形态	对应 data_type	结构	适用场景
text	TEXT	{"text": "<纯文本>"}	纯文本内容（如姓名、说明、标签、编号字符串等）
number	NUMBER	{"number": 123.45}	数值，用于金额、数量、比率等需要参与公式计算或聚合的数据；值为 JSON 数字类型，不加引号
formula	FORMULA	{"formula": "=SUM(A1,A2)"}	任何以 = 开头的公式，包括 =SUM(...)、=A1+B1、=IF(...)、=VLOOKUP(...) 等
link	LINK	{"link": {"url": "<URL>", "text": "<显示文本>"}}	超链接

返回

字段	类型	说明
docid	string	新建表格 ID
url	string	表格访问链接

使用规则

• 何时走 import 而非本接口：用户提到具体文件路径、或明确说"导入 / 用这个文件建"，一律走「导入在线表格」。

导入在线表格

把本地文件（.csv / .xls / .xlsx）导入为企微在线表格。

调用方式

使用 wecom-cli 工具按照下面格式调用

wecom-cli sheet import --json '<JSON 参数>'

参数

字段	类型	必填	默认值	语义
file_name	string	是	—	二进制文件名（含后缀），用于业务判断源文件类型
file_path	string	是	—	源文件的本地绝对路径
passwd	string	否	—	Office 文件加密密码（若有）

返回

字段	类型	说明
docid	string	导入完成后的表格 ID
url	string	导入完成后的访问链接
task_status	string	任务状态枚举，如 succ 成功

读取在线表格

根据 docid 读取在线表格的基础信息，包括工作表列表、文档名称与访问链接。所有后续 sheet * 接口的 sheet_id 都从本接口返回的 sheets[] 中取。

调用方式

使用 wecom-cli 工具按照下面格式调用

wecom-cli sheet get --json '<JSON 参数>'

参数

字段	类型	必填	默认值	语义
docid	string	是	—	在线表格 ID

返回

字段	类型	说明
sheets	array	工作表列表；每项含 sheet_id / title / row_count / column_count / data_range 等基础信息
url	string	文档访问链接
name	string	文档名称

使用规则

• 拿到 sheet_id 后继续读取子表数据是另一个接口，命令字符串、参数名、是否分页等都没有在本节出现，必须先用 read 工具读 references/sheet-ranges-get.md，再据此构造命令。

跨技能依赖

依赖技能	典型协作场景	数据流向
wecomcli-doc-manage	用户只给表格名称/关键词，需搜索获取 docid 后再读写表格；或需要文件级操作（改名、权限等）	wecomcli-doc-manage 的「搜索文档」接口 → 返回 docid → 本 skill 的读取/修改/追加接口

必填参数缺失 / docid 多候选 / 新建 vs 导入等歧义场景，用简洁自然语言仅追问缺失或有歧义的信息；有候选项时在文字中列出供用户选择，不得自行猜测。

docid 使用规则

docid仅cli使用。 最终展示用户时，不应展示 docid，而是使用文档 URL：

[doc_name](doc_url)

docid 是文档的唯一标识符，调用任何文档内容操作技能时均需提供。禁止自造 docid，按以下优先级获取：

1. 从文档链接提取（优先）：用户提供了企微文档 URL 时，直接从 URL 中解析。URL 格式为 https://doc.weixin.qq.com/<type>/<docid>?scode=...，取 /<type>/ 后、? 前的部分即为 docid。
2. 通过文档搜索获取（备选）：用户仅提供文档名称或关键词、未给链接时，先调用 wecomcli-doc-manage 搜索文档，从返回结果中取 docid。
3. 用户直接提供：用户明确给出了完整 docid，可直接使用，无需再提取或搜索。