wecomcli-sheet

SKILL.md 节选

# 企业微信在线表格管理

> 执行任何 `wecom-cli` 命令前，必须先读取并完成 `wecomcli-shared` 技能的公共前置检查。

资源型 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-ranges-get.md) |
| 修改在线表格指定区域内容 | [references/sheet-contents-update.md](references/sheet-contents-update.md) |
| 在线表格末尾追加一行数据 | [references/sheet-rows-append.md](references/sheet-rows-append.md) |
| 添加在线表格子工作表 | [references/sheet-subsheets-add.md](references/sheet-subsheets-add.md) |
| 删除在线表格子工作表 | [references/sheet-subsheets-delete.md](references/sheet-subsheets-delete.md) |

## 接口详述

### 新建在线表格

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

#### 命令

```bash
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`）导入为企微在线表格。

#### 命令

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

#### 参数

| 字段          | 类型 | 必填 | 默认值 | 语义 |
|-------------|---|---|---|---|

SKILL.md 不止这些内容，安装后可阅读全文。

技能包内容

共 6 个文件，合计 14.7 KiB