@wecom/wecom-openclaw-plugin 2026.9.15 → 2026.10.19-beta.1

package/skills/wecomcli-sheet/references/sheet-validation.md

@@ -0,0 +1,243 @@
+# 表格数据验证管理
+
+读取、设置、更新或清除指定区域的数据验证规则。数据验证用于限制单元格可输入的值，例如单选下拉、多选下拉、整数范围、日期范围、时间范围或文本长度。
+
+## 使用场景
+
+| 操作需求 | CLI | 说明 |
+| --- | --- | --- |
+| 读取数据验证 | `sheet validation list` | 查询指定区域现有的数据验证设置 |
+| 首次设置或清除数据验证 | `sheet validation set` | 给没有规则的区域创建规则，或用 `validation_type=none` 清除规则 |
+| 修改已有数据验证 | `sheet validation update` | 仅在目标区域已有数据验证规则时使用 |
+| 删除数据验证 | `sheet validation delete` | 兼容删除指定区域的数据验证规则；清除规则优先用 `validation set` |
+
+## 执行路径
+
+1. 先用 `validation list` 查看目标区域是否已有数据验证规则。
+2. 没有规则时，用 `validation set` 首次设置。
+3. 已有规则时，用 `validation update` 修改类型、条件或选项。
+4. 用户要求清除数据验证、去掉下拉时，用 `validation set` 并传 `validation_type=none`。
+
+## `wecom-cli sheet validation list`
+
+读取指定区域的数据验证设置。
+
+### 命令
+
+使用 wecom-cli 工具按照下面格式调用
+
+```
+wecom-cli sheet validation list --json '<JSON>'
+```
+
+### 入参
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `docid` | `string` | 是 | 工作簿定位，支持文档 URL 或 docid |
+| `sheet` | `string` | 是 | 子表 ID 或名称 |
+| `range` | `string` | 是 | 要查询数据验证的带行号 A1 区域，如 `A2:A100`；不支持只写列字母 |
+
+### 出参
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `items` | `ValidationItem[]` | 数据验证规则列表；无规则时为空数组 |
+
+**`ValidationItem` 结构：**
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `validation_type` | `string` | 数据验证类型，如 `list` / `multiple_list` / `whole` |
+| `ranges` | `string[]` | 应用该规则的 A1 区域列表 |
+| `cell_count` | `int32` | 应用该规则的单元格数 |
+| `options` | `string[]` | 下拉类数据验证的纯文本选项；条件类规则没有该字段 |
+| `has_unreadable_condition` | `bool` | 条件类规则通常为 `true`，表示条件存在但不可从 list 回包读出 |
+
+## `wecom-cli sheet validation set`
+
+首次设置或清除指定区域的数据验证规则。目标区域没有数据验证规则时，必须用本命令创建规则；不要直接调用 `validation update`。
+
+### 命令
+
+使用 wecom-cli 工具按照下面格式调用
+
+```
+wecom-cli sheet validation set --json '<JSON>'
+```
+
+### 入参
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `docid` | `string` | 是 | 工作簿定位，支持文档 URL 或 docid |
+| `sheet` | `string` | 是 | 子表 ID 或名称 |
+| `range` | `string` | 是 | 目标区域；区域模式写 `B2:B100`，整列模式写 `A` |
+| `validation_type` | `string` | 是 | 数据验证类型；见下方类型表。清除规则时传 `none` |
+| `styled_options` | `object[]` | 下拉类必填 | 下拉选项；用于 `list` / `multiple_list`，每项可只填文本，也可带颜色 |
+| `strict` | `bool` | 否 | 下拉类是否仅允许输入选项内的值 |
+| `op` | `string` | 条件类必填 | 比较运算符；用于 `whole` / `decimal` / `date` / `time` / `text_length` |
+| `formula1` | `string` | 条件类必填 | 第一个比较值，只接受字面量，不支持公式或单元格引用 |
+| `formula2` | `string` | 范围比较必填 | 第二个比较值；仅 `op=btw` / `op=not_btw` 时使用 |
+| `ignore_rows` | `int32` | 否 | 整列模式下忽略表头前 N 行，如 `1` 表示跳过第 1 行；区域模式不用传 |
+| `dry_run` | `bool` | 否 | 预览不落盘，返回 `applied=false` |
+| `yes` | `bool` | 落盘时必填 | 确认执行设置；`dry_run=true` 时不用传 |
+
+**`styled_options` 元素结构：**
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `text` | `string` | 是 | 选项文本 |
+| `bg_color` | `string` | 否 | 选项背景色，格式 `#RRGGBB` |
+| `text_color` | `string` | 否 | 选项文本颜色，格式 `#RRGGBB` |
+
+### 支持的 `validation_type`
+
+| 类型 | 含义 | 必填字段 | 禁止字段 |
+| --- | --- | --- | --- |
+| `list` | 单选下拉 | 非空 `styled_options` | `op` / `formula1` / `formula2` |
+| `multiple_list` | 多选下拉 | 非空 `styled_options` | `op` / `formula1` / `formula2` |
+| `whole` | 整数校验 | `op` / `formula1`，范围比较还要 `formula2` | `styled_options` |
+| `decimal` | 小数校验 | `op` / `formula1`，范围比较还要 `formula2` | `styled_options` |
+| `date` | 日期校验 | `op` / `formula1`，范围比较还要 `formula2` | `styled_options` |
+| `time` | 时间校验 | `op` / `formula1`，范围比较还要 `formula2` | `styled_options` |
+| `text_length` | 文本长度校验 | `op` / `formula1`，范围比较还要 `formula2` | `styled_options` |
+| `none` | 清除数据验证 | 无 | `styled_options` / `strict` / `op` / `formula1` / `formula2` |
+
+### 支持的 `op`
+
+| `op` | 含义 | 参数要求 |
+| --- | --- | --- |
+| `btw` | 在范围内 | 必须传 `formula1` 和 `formula2` |
+| `not_btw` | 不在范围内 | 必须传 `formula1` 和 `formula2` |
+| `eq` | 等于 | 只传 `formula1` |
+| `ne` | 不等于 | 只传 `formula1` |
+| `gt` | 大于 | 只传 `formula1` |
+| `lt` | 小于 | 只传 `formula1` |
+| `gte` | 大于等于 | 只传 `formula1` |
+| `lte` | 小于等于 | 只传 `formula1` |
+
+### 出参
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `range` | `string` | 实际应用的区域；区域模式如 `B2:B100`，整列模式如 `A` |
+| `applied` | `bool` | 是否已落盘执行；`dry_run=true` 时为 `false` |
+| `validation_type` | `string` | 实际生效的数据验证类型 |
+
+### 示例：设置单选下拉
+
+```
+wecom-cli sheet validation set --json '{
+  "docid": "e3_ABC123",
+  "sheet": "销售",
+  "range": "A2:A100",
+  "validation_type": "list",
+  "styled_options": [
+    {"text": "待处理"},
+    {"text": "进行中"},
+    {"text": "已完成"}
+  ],
+  "strict": true,
+  "yes": true
+}'
+```
+
+### 示例：设置整数范围
+
+```
+wecom-cli sheet validation set --json '{
+  "docid": "e3_ABC123",
+  "sheet": "销售",
+  "range": "D2:D100",
+  "validation_type": "whole",
+  "op": "btw",
+  "formula1": "60",
+  "formula2": "90",
+  "yes": true
+}'
+```
+## `wecom-cli sheet validation update`
+
+修改已有区域的数据验证规则。调用前必须确认目标区域已经存在数据验证规则；如果 `validation list` 查不到规则，先用 `validation set` 创建。
+
+### 命令
+
+使用 wecom-cli 工具按照下面格式调用
+
+```
+wecom-cli sheet validation update --json '<JSON>'
+```
+
+### 入参
+
+`validation update` 的入参和 `validation set` 基本一致，但清除规则不要用 `update`，应改用 `validation set` 且传 `validation_type=none`。
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `docid` | `string` | 是 | 工作簿定位，支持文档 URL 或 docid |
+| `sheet` | `string` | 是 | 子表 ID 或名称 |
+| `range` | `string` | 是 | 目标区域；区域模式写 `B2:B100`，整列模式写 `A` |
+| `validation_type` | `string` | 是 | 新数据验证类型，见 `validation set` 的类型表；不要传 `none` |
+| `styled_options` | `object[]` | 否 | 下拉选项；用于 `list` / `multiple_list`，每项可只填文本，也可带颜色 |
+| `strict` | `bool` | 否 | 下拉类是否仅允许输入选项内的值 |
+| `op` | `string` | 条件类必填 | 比较运算符；用于 `whole` / `decimal` / `date` / `time` / `text_length` |
+| `formula1` | `string` | 条件类必填 | 第一个比较值，只接受字面量，不支持公式或单元格引用 |
+| `formula2` | `string` | 范围比较必填 | 第二个比较值；仅 `op=btw` / `op=not_btw` 时使用 |
+| `ignore_rows` | `int32` | 否 | 整列模式下忽略表头前 N 行，如 `1` 表示跳过第 1 行；区域模式不用传 |
+| `dry_run` | `bool` | 否 | 预览不落盘，返回 `applied=false` |
+| `yes` | `bool` | 落盘时必填 | 确认执行更新；`dry_run=true` 时不用传 |
+
+### 出参
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `range` | `string` | 实际更新的区域；区域模式如 `B2:B100`，整列模式如 `A` |
+| `applied` | `bool` | 是否已落盘执行；`dry_run=true` 时为 `false` |
+| `validation_type` | `string` | 实际应用的数据验证类型 |
+
+## `wecom-cli sheet validation delete`
+
+删除指定区域的数据验证规则。清除下拉或清除普通数据验证时，优先使用 `validation set` 并传 `validation_type=none`。
+
+### 命令
+
+使用 wecom-cli 工具按照下面格式调用
+
+```
+wecom-cli sheet validation delete --json '<JSON>'
+```
+
+### 入参
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `docid` | `string` | 是 | 工作簿定位，支持文档 URL 或 docid |
+| `sheet` | `string` | 是 | 子表 ID 或名称 |
+| `range` | `string` | 是 | 要删除数据验证的 A1 区域，如 `A2:A100` |
+| `yes` | `bool` | 否 | 确认执行删除；兼容旧调用时可省略 |
+
+### 出参
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `range` | `string` | 实际操作的区域 A1 |
+| `applied` | `bool` | 是否成功应用删除操作 |
+
+## 使用约束
+
+- 执行设置、更新或清除前，优先用 `validation list` 查看目标区域现有规则。
+- 目标区域没有数据验证规则时，用 `validation set`；目标区域已有规则且要修改时，用 `validation update`。直接对无规则区域调用 `validation update` 会报错，提示改用 set。
+- 清除数据验证规则时，优先用 `validation set` 并传 `validation_type=none`；`validation delete` 也能删除规则，但返回中没有 `validation_type`。
+- `range` 使用纯 A1 写法，不带子表名；子表通过 `sheet` 单独定位。
+- `validation set` / `validation update` 的区域模式用于精确单元格范围，如 `B2:B100`；整列模式用于让新增行继承规则，如 `B`。
+- `validation list` 只接受带行号区域；整列设置后如需复查，用实际数据区域查询，如 `B2:B100`。
+- 整列模式需要跳过表头时传 `ignore_rows`；区域模式直接把起始行写进 `range`，不用传 `ignore_rows`。
+- `list` / `multiple_list` 必须提供非空 `styled_options`；不要在设置或更新时传 `options`。
+- `styled_options` 可以设置带颜色的选项，但 `validation list` 只返回纯文本 `options`，不返回颜色信息。
+- `strict` 可以随下拉类规则传入，但 `validation list` 不返回 `strict`。
+- 条件类规则必须显式提供完整条件：`op`、`formula1`，以及范围比较所需的 `formula2`。条件类规则的 `validation list` 回包不返回 `op` / `formula1` / `formula2`，只能看到 `has_unreadable_condition=true`。
+- `formula1` / `formula2` 只写字面量；不要写公式、单元格引用或命名区域。
+- 单边比较如 `gt` / `lt` / `gte` / `lte` / `eq` / `ne` 不要传 `formula2`。
+- 设置规则不会自动修正已有不合规数据；如果任务要求保证历史数据合规，设置后还需要读取并复核已有值。
+- 落盘设置或更新必须传 `yes=true`；`dry_run=true` 时不用传 `yes`，且不会落盘。

package/skills/wecomcli-sheet/references/sheet-workbook.md

@@ -0,0 +1,271 @@
+# 工作簿与子表管理
+
+从零新建一篇企微在线表格，导入本地 CSV / Excel 文件为企微在线表格，读取整个在线表格工作簿，并管理其中子表的新增、删除、重命名、复制和顺序。
+
+| 命令                              | 风险 | 用途 |
+|---------------------------------|---|---|
+| `wecom-cli doc create`          | 创建 | 从零新建一篇在线表格 |
+| `wecom-cli doc import`        | 文件写入 | 导入本地文件为在线表格 |
+| `wecom-cli sheet workbook get`  | 只读 | 获取工作簿中的全部子表 |
+| `wecom-cli sheet subsheets create` | 结构写入 | 新增子表 |
+| `wecom-cli sheet subsheets remove`  | 高风险写入 | 删除子表 |
+| `wecom-cli sheet subsheets rename`  | 结构写入 | 重命名子表 |
+| `wecom-cli sheet subsheets copy`    | 结构写入 | 复制子表 |
+| `wecom-cli sheet subsheets move`    | 结构写入 | 调整子表顺序 |
+| `wecom-cli sheet subsheets visible` | 结构写入 | 显示或隐藏子表 |
+
+## 通用规则
+
+- 结构性写入、高风险写入均支持 `dry_run`。需要预览时先传 `"dry_run":true`，确认后再正式执行。
+
+## 新建在线表格
+
+新建企微在线表格时，先按用户需求创建一个本地 `.xlsx`，完成质量校验后，再通过`doc import`导入为企微在线表格。
+
+### 标准流程
+- 使用 `openpyxl` 创建本地 `.xlsx`。本地文件只写入子表名称、单元格值和公式，并将工作表已用区域内的所有单元格统一设置为水平居中、垂直居中。
+- 导入前只校验本地 `.xlsx` 是否存在且非空、能否正常打开，以及工作表名称、数量、关键数据和公式是否正确。校验不通过时先修复本地文件，不得导入未验证产物。
+- 调用下方「导入在线表格」的 `wecom-cli doc import`，把已校验的 `.xlsx` 导入为企微在线表格，并确认 `task_status` 为成功状态。
+- 向用户返回企微在线表格 URL。除非用户明确要求，否则禁止返回或向用户暴露本地 `.xlsx` 中间文件。
+
+### 使用规则
+- 新建流程适用于从零创建表格，以及用户对当前任务中刚创建的表格不满意并提出修改意见的情况；后者即使表述为“修改”，也应按新建流程重新生成。仅当操作对象是此前已存在的企微在线表格时，才使用读取、修改、追加、子表管理等在线接口，禁止重新生成 XLSX 后覆盖导入。
+
+## 导入在线表格
+
+把本地文件（`.csv` / `.xls` / `.xlsx`）导入为企微在线表格。
+
+### 命令
+
+使用 wecom-cli 工具按照下面格式调用
+
+```
+wecom-cli doc import --json '<JSON 参数>'
+```
+
+### 参数
+
+| 字段          | 类型 | 必填 | 默认值 | 语义                      |
+|-------------|---|---|---|-------------------------|
+| `doc_type`  | string | 是 | — | 导入文档类型，固定为`sheet`       |
+| `file_name` | string | 是 | — | 二进制文件名（含后缀），用于业务判断源文件类型 |
+| `file_path` | string | 是 | — | 源文件的本地绝对路径              |
+| `passwd`    | string | 否 | — | Office 文件加密密码（若有）       |
+
+### 返回
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `docid` | string | 导入完成后的表格 ID |
+| `url` | string | 导入完成后的访问链接 |
+| `task_status` | string | 任务状态枚举，如 `succ` 成功 |
+
+## 获取工作簿信息
+
+列出工作簿中的全部子表，返回子表 ID、名称和行列范围，是后续子表操作的探测入口。
+
+### 命令
+
+使用 wecom-cli 工具按照下面格式调用
+
+```
+wecom-cli sheet workbook get --json '<JSON 参数>'
+```
+
+### 参数
+
+| 字段 | 类型 | 必填 | 默认值 | 语义 |
+|---|---|---|---|---|
+| `docid` | string | 是 | — | 在线表格 ID 或 URL |
+
+### 返回
+
+| 字段                      | 类型       | 说明                                     |
+|-------------------------|----------|----------------------------------------|
+| `sheets`                | object[] | 子表列表                                   |
+| `sheets[].sheet_id`     | string   | 子表 ID        |
+| `sheets[].name`        | string   | 子表名称                                   |
+| `sheets[].range`        | string   | 子表实际数据范围；空表返回 `A1:A1`                    |
+
+### 使用规则
+
+- 工作簿内存在同名子表、用户只描述了模糊名称，或后续操作具有破坏性时，应先通过本接口拿到 `sheet_id` 再操作。
+- **`A1:A1` 需读取确认**：该范围既可能表示空表，也可能表示只有 A1 单元格有内容；不得仅凭 `range` 判定为空表，应使用 `cells get` 读取 `A1:A1` 后确认。
+
+## 新增子表
+
+### 命令
+
+使用 wecom-cli 工具按照下面格式调用
+
+```
+wecom-cli sheet subsheets create --json '<JSON 参数>'
+```
+
+### 参数
+
+| 字段 | 类型 | 必填 | 默认值 | 语义                |
+|---|---|---|---|-------------------|
+| `docid` | string | 是 | — | 在线表格 ID 或 URL     |
+| `name` | string | 否 | 引擎生成默认名 | 子表名称，长度不超过 31 个字符 |
+| `position` | int | 否 | 追加到末尾 | 插入位置，1-based      |
+| `dry_run` | bool | 否 | `false` | `true` 时仅预览，不落盘   |
+
+### 返回
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `sheet_id` | string | 新建子表 ID |
+| `name` | string | 实际子表名称 |
+| `position` | int | 实际插入位置，1-based |
+
+### 示例
+
+```
+wecom-cli sheet subsheets create --json '{"docid":"e3_ABC123","name":"2026汇总","position":2}'
+```
+
+### 使用规则
+
+- 需要空白子表时使用本接口；已有模板且需要继承结构与格式时优先使用 `sheet subsheets copy`。
+
+## 删除子表
+
+### 命令
+
+使用 wecom-cli 工具按照下面格式调用
+
+```
+wecom-cli sheet subsheets remove --json '<JSON 参数>'
+```
+
+### 参数
+
+| 字段         | 类型 | 必填 | 默认值 | 语义              |
+|------------|---|---|---|-----------------|
+| `docid`    | string | 是 | — | 在线表格 ID 或 URL   |
+| `sheet` | string | 是 | — | 待删除子表 ID        |
+| `yes` | bool | 是 | — | 确认执行（缺省拒绝）      |
+| `dry_run`  | bool | 否 | `false` | `true` 时仅预览，不落盘 |
+
+### 返回
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `sheet_id` | string | 已删除子表 ID |
+| `name` | string | 已删除子表名称 |
+
+## 重命名子表
+
+### 命令
+
+使用 wecom-cli 工具按照下面格式调用
+
+```
+wecom-cli sheet subsheets rename --json '<JSON 参数>'
+```
+
+### 参数
+
+| 字段         | 类型 | 必填 | 默认值 | 语义 |
+|------------|---|---|---|---|
+| `docid`    | string | 是 | — | 在线表格 ID 或 URL |
+| `sheet` | string | 是 | — | 子表 ID |
+| `name`     | string | 是 | — | 新名称，长度不超过 31 个字符 |
+| `dry_run`  | bool | 否 | `false` | `true` 时仅预览，不落盘 |
+
+### 返回
+
+| 字段         | 类型 | 说明 |
+|------------|---|---|
+| `sheet_id` | string | 子表 ID |
+| `name` | string | 重命名后的名称 |
+
+## 复制子表
+
+新复制的子表，默认放在源子表的右侧
+
+### 命令
+
+使用 wecom-cli 工具按照下面格式调用
+
+```
+wecom-cli sheet subsheets copy --json '<JSON 参数>'
+```
+
+### 参数
+
+| 字段                | 类型 | 必填 | 默认值 | 语义 |
+|-------------------|---|---|---|---|
+| `docid`           | string | 是 | — | 在线表格 ID 或 URL |
+| `sheet` | string | 是 | — | 源子表 ID |
+| `name`        | string | 否 | 引擎生成默认名 | 副本名称 |
+| `dry_run`         | bool | 否 | `false` | `true` 时仅预览，不落盘 |
+
+### 返回
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `sheet_id` | string | 新副本的子表 ID |
+
+## 移动子表顺序
+
+### 命令
+
+使用 wecom-cli 工具按照下面格式调用
+
+```
+wecom-cli sheet subsheets move --json '<JSON 参数>'
+```
+
+### 参数
+
+| 字段         | 类型 | 必填 | 默认值 | 语义 |
+|------------|---|---|---|---|
+| `docid`    | string | 是 | — | 在线表格 ID 或 URL |
+| `sheet` | string | 是 | — | 子表 ID |
+| `position`   | int | 是 | — | 目标位置，1-based |
+| `dry_run`  | bool | 否 | `false` | `true` 时仅预览，不落盘 |
+
+## 显示或隐藏子表 — `wecom-cli sheet subsheets visible`
+
+设置指定子表显示或隐藏。隐藏子表不会删除内容，适合收起辅助计算表、中间过程表或暂不展示的历史表。
+
+### 命令
+
+使用 wecom-cli 工具按照下面格式调用
+
+```
+wecom-cli sheet subsheets visible --json '<JSON 参数>'
+```
+
+### 参数
+
+| 字段 | 类型 | 必填 | 默认值 | 语义 |
+|---|---|---|---|---|
+| `docid` | string | 是 | — | 在线表格 ID 或 URL |
+| `sheet` | string | 是 | — | 子表 ID 或名称 |
+| `visible` | bool | 是 | — | `true` 表示显示，`false` 表示隐藏 |
+| `dry_run` | bool | 否 | `false` | `true` 时仅预览，不落盘 |
+
+### 返回
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `sheet_id` | string | 子表 ID |
+| `visible` | bool | 当前可见状态 |
+
+### 示例
+
+```
+wecom-cli sheet subsheets visible --json '{"docid":"e3_ABC123","sheet":"销售","visible":false}'
+```
+
+### 使用规则
+
+- **隐藏不是删除**：用户说“先收起来/隐藏辅助表/不要展示给使用者”时使用本命令；不要用删除子表代替隐藏。
+- **先确认目标子表**：隐藏前调用 `workbook get` 获取稳定 `sheet_id`，避免隐藏错同名或相似名称子表。
+- **谨慎隐藏关键表**：隐藏源数据、公式依赖表或唯一入口表前，先向用户确认影响。
+- **不能隐藏最后一个可见子表**：实测隐藏最后一个可见子表会失败，错误信息为 `cannot hide the last visible sheet`。
+- **dry-run 响应同形**：`dry_run:true` 的响应结构与正式执行一致，但不落盘。
+- **无法只读回读**：实测 `workbook get` 的 `sheets[]` 不返回 `visible` 字段。写后只能以 `subsheets visible` 响应确认。