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 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,否,单元格值);rows[].values[].data_type(string,否,枚举 TEXT / NUMBER / LINK / FORMULA)。 cell_value 类型选择(硬规则:选择 cell_value 形态后,必须同时把同级的 data_type 设置为对应值):
- text → TEXT:{"text": "<纯文本>"},适用纯文本内容(姓名、说明、标签、编号字符串等)
- number → NUMBER:{"number": 123.45},适用需要参与公式计算或聚合的数据;值为 JSON 数字类型,不加引号
- formula → FORMULA:{"formula": "=SUM(A1,A2)"},适用任何以 = 开头的公式
- link → LINK:{"link": {"url": "<URL>", "text": "<显示文本>"}},适用超链接 返回:docid(新建表格 ID);url(表格访问链接)。 使用规则:用户提到具体文件路径、或明确说“导入 / 用这个文件建”,一律走「导入在线表格」。
【导入在线表格】 把本地文件(.csv / .xls / .xlsx)导入为企微在线表格。 调用方式:wecom-cli sheet import --json '<JSON 参数>' 参数:file_name(string,必填,二进制文件名含后缀,用于业务判断源文件类型);file_path(string,必填,源文件本地绝对路径);passwd(string,否,Office 文件加密密码)。 返回:docid(导入完成后的表格 ID);url(访问链接);task_status(任务状态枚举,如 succ 成功)。
【读取在线表格】 根据 docid 读取在线表格基础信息,包括工作表列表、文档名称与访问链接。所有后续 sheet * 接口的 sheet_id 都从本接口返回的 sheets[] 中取。 调用方式:wecom-cli sheet get --json '<JSON 参数>' 参数:docid(string,必填,在线表格 ID)。 返回:sheets(array,工作表列表,每项含 sheet_id / title / row_count / column_count / data_range 等基础信息);url(文档访问链接);name(文档名称)。 使用规则:拿到 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。 docid 是文档唯一标识符,调用任何文档内容操作技能时均需提供。禁止自造 docid,按以下优先级获取:
- 从文档链接提取(优先):用户提供企微文档 URL 时,直接从 URL 解析。URL 格式为 https://doc.weixin.qq.com/<type>/<docid>?scode=...,取 /<type>/ 后、? 前部分即为 docid。
- 通过文档搜索获取(备选):用户仅提供文档名称或关键词、未给链接时,先调用 wecomcli-doc-manage 搜索文档,从返回结果中取 docid。
- 用户直接提供:用户明确给出完整 docid,可直接使用,无需再提取或搜索。