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

package/skills/wecomcli-sheet/references/sheet-float-image.md

@@ -0,0 +1,248 @@
+# 浮动图片处理
+
+对**在线表格**子表中的浮动图片执行创建、替换、删除、批量插入与查询。浮动图片是悬浮在表格上的对象，通过锚点单元格定位并返回独立 `image_id`；它不同于 `sheet cells set` / `cells batchset` 中写入单元格的图片。
+
+> **依赖关系**：`sheet` 使用子表 ID 或名称；`anchor` 使用单个纯 A1 单元格，如 `F50`，不包含子表名。图片字段使用可被文档访问的 URL。
+
+## 图片 URL 前置转换
+
+浮动图片的 `image` / `new_image` 字段只接受图片 URL。若源图片是本地文件或 `media_id`，先调用 `wecom-cli sheet images upload` 上传到目标文档空间，获取可用 URL。
+
+上传本地图片时，将本地图片路径作为 string 传入 `file_path`：
+
+### 命令
+
+使用 wecom-cli 工具按照下面格式调用
+
+```
+wecom-cli sheet images upload --json '{"file_path":"/path/to/image.png","docid":"<文档ID>"}'
+```
+
+上传 `media_id` 对应的图片时：
+
+```
+wecom-cli sheet images upload --json '{"media_id":"<media_id>","docid":"<文档ID>"}'
+```
+
+**入参：**
+
+| 字段 | 类型 | 必填 | 说明                                                                    |
+|---|---|---|-----------------------------------------------------------------------|
+| `docid` | string | 是 | 目标在线表格文档 ID                                                           |
+| `file_path` | string | 条件必填 | 本地图片路径；与 `media_id` 二选一                                               |
+| `media_id` | string | 条件必填 | 媒体文件 ID，来自用户消息或 `wecomcli-media` 技能的 `media upload`；与 `file_path` 二选一 |
+
+**出参：**
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `url` | string | 上传后的文件访问 URL；填入 `float image set` 的 `image` 或 `float image update` 的 `new_image` |
+
+> `file_path` 与 `media_id` 不能同时传入。不要把本地路径或 `media_id` 直接填进 `image` / `new_image`。
+
+## 使用场景
+
+| 操作需求 | CLI | 说明 |
+| --- | --- | --- |
+| 在指定位置新增一张浮动图片 | `sheet float image set` | 返回 `image_id`，用于后续替换或删除 |
+| 替换已有浮动图片的图片内容 | `sheet float image update` | 按 `image_id` 替换为 `new_image` |
+| 删除一张浮动图片 | `sheet float image delete` | 按 `image_id` 删除 |
+| 一次插入多张浮动图片 | `sheet float image batchset` | 每张图独立指定 `image`、`anchor`、尺寸 |
+| 查询子表浮动图片 | `sheet float image list` | 获取 `image_id`、锚点和尺寸 |
+
+## 定位前置检查
+
+1. 先确认目标 `docid` 和 `sheet`；用户只给工作簿名时，先通过文档搜索或工作簿信息定位。
+2. 用户描述“放到某列旁边”“放到数据末尾”时，先读取表头或当前数据范围，推导单个 A1 锚点。
+3. 更新或删除前先调用 `float image list` 获取 `image_id`，不要按锚点或返回顺序盲改。
+4. 如果用户要求图片作为记录字段参与排序、筛选或数据处理，优先使用 `sheet-write-cells.md` 的单元格图片能力，不用浮动图片。
+
+## 创建浮动图片 — `wecom-cli sheet float image set`
+
+### 命令
+
+使用 wecom-cli 工具按照下面格式调用
+
+```
+wecom-cli sheet float image set --json '<JSON 参数>'
+```
+
+### 参数
+
+| 字段 | 类型 | 必填 | 默认值 | 语义 |
+|---|---|---|---|---|
+| `docid` | string | 是 | — | 在线表格 ID / URL |
+| `sheet` | string | 是 | — | 子表 ID 或名称 |
+| `image` | string | 是 | — | 图片 URL；若源图片是本地路径或 `media_id`，先通过 `images upload` 换取 URL |
+| `anchor` | string | 是 | — | 图片锚点单元格，纯 A1，如 `F50` |
+| `width` | int | 否 | — | 图片显示宽度，单位 px |
+| `height` | int | 否 | — | 图片显示高度，单位 px |
+
+### 返回
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `anchor` | string | 实际锚点单元格，纯 A1 |
+| `image_id` | string | 新建浮动图片 ID；后续更新 / 删除使用 |
+
+### 示例
+
+```
+wecom-cli sheet float image set --json '{"docid":"e3_AHsALgbHACcCN1HvTa5u7SFefia8Y","sheet":"数据","image":"https://wdoc-76491.picgzc.qpic.cn/x3WIu_1764596460","anchor":"F50","width":320,"height":240}'
+```
+
+### 使用规则
+
+- **锚点是单格**：`anchor` 传 `F50` 这类单个单元格，不要传 `F50:H60`。
+- **保存 `image_id`**：创建成功后记录返回 ID；替换和删除都依赖它。
+- **尽量保持原比例**：如果上传返回的图片 URL 带有 `w` / `h` 参数，或已知原图像素尺寸，指定 `width` / `height` 时优先按原图宽高比换算，避免拉伸变形。用户明确指定宽高时以用户要求为准。
+
+## 更新浮动图片 — `wecom-cli sheet float image update`
+
+### 命令
+
+使用 wecom-cli 工具按照下面格式调用
+
+```
+wecom-cli sheet float image update --json '<JSON 参数>'
+```
+
+### 参数
+
+| 字段 | 类型 | 必填 | 默认值 | 语义 |
+|---|---|---|---|---|
+| `docid` | string | 是 | — | 在线表格 ID / URL |
+| `sheet` | string | 是 | — | 子表 ID 或名称 |
+| `image_id` | string | 是 | — | 要替换的浮动图片 ID |
+| `new_image` | string | 是 | — | 新图片 URL；若源图片是本地路径或 `media_id`，先通过 `images upload` 换取 URL |
+
+### 返回
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `image_id` | string | 被更新的浮动图片 ID |
+
+### 示例
+
+```
+wecom-cli sheet float image update --json '{"docid":"e3_AHsALgbHACcCN1HvTa5u7SFefia8Y","sheet":"数据","image_id":"1106075089","new_image":"https://wdoc-76491.picgzc.qpic.cn/6ddbdae8f"}'
+```
+
+### 使用规则
+
+- **只替换图片内容**：当前开放字段只包含 `new_image`，不要在 update 中同时尝试移动锚点或改尺寸。
+- **先 list 再改**：用户只说“替换 F50 那张图”时，先用 `float image list` 找到对应 `image_id`。
+
+## 删除浮动图片 — `wecom-cli sheet float image delete`
+
+### 命令
+
+使用 wecom-cli 工具按照下面格式调用
+
+```
+wecom-cli sheet float image delete --json '<JSON 参数>'
+```
+
+### 参数
+
+| 字段 | 类型 | 必填 | 默认值 | 语义 |
+|---|---|---|---|---|
+| `docid` | string | 是 | — | 在线表格 ID / URL |
+| `sheet` | string | 是 | — | 子表 ID 或名称 |
+| `image_id` | string | 是 | — | 要删除的浮动图片 ID |
+
+### 返回
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `image_id` | string | 已删除的浮动图片 ID |
+
+### 使用规则
+
+- **按 ID 删除**：删除前先 `float image list` 核对图片锚点和 `image_id`。
+
+## 批量插入浮动图片 — `wecom-cli sheet float image batchset`
+
+### 命令
+
+使用 wecom-cli 工具按照下面格式调用
+
+```
+wecom-cli sheet float image batchset --json '<JSON 参数>'
+```
+
+### 参数
+
+| 字段 | 类型 | 必填 | 默认值 | 语义 |
+|---|---|---|---|---|
+| `docid` | string | 是 | — | 在线表格 ID / URL |
+| `sheet` | string | 是 | — | 子表 ID 或名称 |
+| `images` | array | 是 | — | 要插入的图片数组，元素结构见下方 `images[]` |
+
+`images[]` 对象结构：
+
+| 子字段 | 类型 | 必填 | 默认值 | 语义 |
+|---|---|---|---|---|
+| `image` | string | 是 | — | 图片 URL；若源图片是本地路径或 `media_id`，先通过 `images upload` 换取 URL |
+| `anchor` | string | 是 | — | 图片锚点单元格，纯 A1，如 `H2` |
+| `width` | int | 否 | — | 图片显示宽度，单位 px |
+| `height` | int | 否 | — | 图片显示高度，单位 px |
+
+### 返回
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `results` | array | 批量插入结果数组 |
+| `results[].anchor` | string | 实际锚点单元格，纯 A1 |
+| `results[].image_id` | string | 新建浮动图片 ID |
+
+### 示例
+
+```
+wecom-cli sheet float image batchset --json '{"docid":"e3_AHsALgbHACcCN1HvTa5u7SFefia8Y","sheet":"数据","images":[{"image":"https://wdoc-76491.picgzc.qpic.cn/Iu_1764596460","anchor":"H2","width":200,"height":150},{"image":"https://wdoc-76491.picgzc.qpic.cn/b6ddbdae8f","anchor":"H10","width":200,"height":150}]}'
+```
+
+### 使用规则
+
+- **逐项指定锚点**：每张图片都必须有自己的 `anchor`；不要用一个起始位置让后端自动排布。
+- **尽量保持原比例**：如果上传返回的图片 URL 带有 `w` / `h` 参数，或已知原图像素尺寸，逐张按原图宽高比设置显示尺寸；用户明确指定宽高时以用户要求为准。
+- **批量后保存映射**：保留 `anchor` 到 `image_id` 的映射，便于后续替换或删除。
+- **失败项单独处理**：若回包出现部分失败，按失败项单独重试或向用户说明。
+
+## 查询浮动图片 — `wecom-cli sheet float image list`
+
+### 命令
+
+使用 wecom-cli 工具按照下面格式调用
+
+```
+wecom-cli sheet float image list --json '<JSON 参数>'
+```
+
+### 参数
+
+| 字段 | 类型 | 必填 | 默认值 | 语义 |
+|---|---|---|---|---|
+| `docid` | string | 是 | — | 在线表格 ID / URL |
+| `sheet` | string | 是 | — | 子表 ID 或名称 |
+
+### 返回
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `images` | array | 子表中的浮动图片列表 |
+| `images[].image_id` | string | 浮动图片 ID |
+| `images[].anchor` | string | 图片锚点单元格，纯 A1 |
+| `images[].width` | int | 图片宽度，单位 px |
+| `images[].height` | int | 图片高度，单位 px |
+
+### 使用规则
+
+- **用于定位对象**：更新和删除都先 list，确认 `image_id`、锚点和尺寸。
+- **锚点可能不唯一**：同一锚点可能有多张图片时，结合尺寸、创建上下文或用户描述消歧。
+- **宽高单位统一**：`set` / `batchset` / `list` 的 `width`、`height` 均按 px 理解。
+
+## 能力边界
+
+- 当前 reference 只开放用户表格中列出的字段；不支持移动已有浮动图片、调整已有浮动图片尺寸、分页查询或按区域过滤。
+- 浮动图片通过锚点单元格定位，适合做子表上的悬浮展示对象。需要图片作为单元格内容写入，或需要明确绑定某条记录并按单元格数据处理时，使用 `sheet-write-cells.md` 的单元格图片能力。

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

@@ -0,0 +1,73 @@
+# 公式预计算
+
+对**在线表格**中的公式进行批量试算并返回结果，不修改文档内容。适用于写入公式前的预计算、校验公式语义、检查相对引用在指定锚点下的结果，以及确认数组公式展开结果。
+
+> **依赖关系**：`sheet` 使用子表 ID 或名称；公式必须以 `=` 开头；`anchor` 使用单个纯 A1 单元格，不包含子表名。
+
+## 使用场景
+
+| 操作需求 | CLI | 说明 |
+| --- | --- | --- |
+| 写入前试算公式 | `sheet formulas calculate` | 不落盘，只返回公式结果 |
+| 批量校验公式是否报错 | `sheet formulas calculate` | 通过 `errors`、`eval_error` 和 `cells[].is_error` 判断 |
+
+## 试算公式
+
+### 命令
+
+使用 wecom-cli 工具按照下面格式调用
+
+```
+wecom-cli sheet formulas calculate --json '<JSON 参数>'
+```
+
+### 参数
+
+| 字段 | 类型 | 必填 | 默认值 | 语义 |
+|---|---|---|---|---|
+| `docid` | string | 是 | — | 在线表格 ID / URL，仅支持 sheet 类型文档 |
+| `sheet` | string | 是 | — | 默认子表 ID 或名称；优先按 ID 匹配，未命中按名称匹配 |
+| `formulas` | array | 是 | — | 待试算公式数组，单次 1-100 条；元素结构见下方 `formulas[]` |
+
+`formulas[]` 对象结构：
+
+| 子字段 | 类型 | 必填 | 默认值 | 语义 |
+|---|---|---|---|---|
+| `formula` | string | 是 | — | 公式原文，必须以 `=` 开头，如 `=SUM(A1:A10)` |
+| `anchor` | string | 否 | `A1` | 相对引用的锚点单元格，纯 A1；不传时按 `A1` 计算 |
+| `sheet` | string | 否 | 请求级 `sheet` | 子表 ID 或名称 |
+
+### 返回
+
+| 字段 | 类型 | 说明                                         |
+|---|---|--------------------------------------------|
+| `total` | int | 请求公式总数                                     |
+| `errors` | int | 计算失败的公式条数                                  |
+| `results` | array | 逐条结果，与请求 `formulas` 顺序一致                   |
+| `results[].index` | int32 | 对应请求 `formulas` 的下标，从 0 开始                 |
+| `results[].sheet_id` | string | 实际使用的子表 ID                                 |
+| `results[].anchor` | string | 实际使用的锚点单元格 A1                              |
+| `results[].cells` | array | 结果单元格；数组公式会展开为多个单元格                        |
+| `results[].cells[].address` | string | 结果单元格 A1 地址                                |
+| `results[].cells[].value` | string / number / bool / null | 计算值；公式错误时为错误码字符串                           |
+| `results[].cells[].is_error` | bool | `true` 表示 `value` 为公式错误码，如 `#REF!`、`#DIV/0!` |
+| `results[].eval_error` | string | 整条公式无法评估（语法错误、sheet 不存在等）   |
+
+### 示例
+
+```
+wecom-cli sheet formulas calculate --json '{"docid":"DOCID_EXAMPLE","sheet":"Sheet1","formulas":[{"formula":"=1+2"}]}'
+```
+
+### 使用规则
+
+- **不修改文档**：本命令只试算公式，不写入单元格。用户要把公式真正写进表格时，使用 `sheet-write-cells.md` 中的 `cells set` 或 `cells batchset`。
+- **公式必须带等号**：`formula` 必须以 `=` 开头；不要传裸表达式 `1+2`。
+- **批量上限**：单次 `formulas` 数组为 1-100 条；超过 100 条时分批调用，并按 `index` 对回原请求顺序。
+- **相对引用看锚点**：未传 `anchor` 时按 `A1` 计算；公式包含相对引用时，按用户目标单元格或计划写入位置设置 `anchor`。
+- **错误分两类**：`eval_error` 表示条目级计算失败；`cells[].is_error=true` 表示公式成功计算但结果是公式错误码。
+
+## 能力边界
+
+- 本接口不创建、修改或保存公式；只用于预计算和校验。
+- 不返回依赖单元格清单或完整计算链路。

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

@@ -0,0 +1,125 @@
+# 版本历史管理
+
+查询**在线表格工作簿级别**的当前版本号与历史版本，并将整个工作簿还原到指定历史版本。
+
+| 命令 | 风险 | 用途 |
+|---|---|---|
+| `wecom-cli sheet version get` | 只读 | 获取当前文档版本号 |
+| `wecom-cli sheet version list` | 只读 | 查询文档历史版本 |
+| `wecom-cli sheet version rollback` | 高风险写入 | 将整个工作簿还原到指定历史版本，并生成一个新版本 |
+
+## 通用规则
+
+- **版本作用于整个工作簿**：版本查询与回滚均以 `docid` 为操作对象，不能只回滚某个子表或单元格区域。
+- **先查询再回滚**：执行回滚前，先调用 `version get` 获取当前版本，再调用 `version list` 确认目标版本确实存在，并向用户说明当前版本与目标版本。
+- **明确目标版本**：用户未指定版本号、版本号不存在或存在多个语义候选时，先列出历史版本供用户选择，禁止猜测。
+- **回滚会生成新版本**：回滚不会把当前版本号直接改成目标历史版本号，而是以目标版本内容生成一个新的当前版本。
+
+## 获取当前版本号
+
+获取指定在线表格当前的文档版本号。
+
+### 命令
+
+使用 wecom-cli 工具按照下面格式调用
+
+```
+wecom-cli sheet version get --json '<JSON 参数>'
+```
+
+### 参数
+
+| 字段 | 类型 | 必填 | 默认值 | 语义 |
+|---|---|---|---|---|
+| `docid` | string | 是 | — | 在线表格 ID 或 URL |
+
+### 返回
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `version` | int | 当前文档版本号 |
+
+### 使用规则
+
+- 回滚前必须读取当前版本号，用于确认操作起点。
+- 回滚后再次调用本接口；返回版本号应与回滚响应中的 `new_version` 一致。
+
+## 查询历史版本
+
+分页查询指定在线表格的历史版本，返回版本号、修改时间和修改人。
+
+### 命令
+
+使用 wecom-cli 工具按照下面格式调用
+
+```
+wecom-cli sheet version list --json '<JSON 参数>'
+```
+
+### 参数
+
+| 字段 | 类型 | 必填 | 默认值 | 语义                                  |
+|---|---|---|---|-------------------------------------|
+| `docid` | string | 是 | — | 在线表格 ID 或 URL                       |
+| `limit` | int | 否 | — | 单页返回数量                              |
+| `cursor` | string | 否 | `""` | 分页游标；首次传空字符串，后续传上一页返回的 `next_cursor` |
+
+### 返回
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `versions` | object[] | 历史版本列表 |
+| `versions[].version` | int | 历史版本号 |
+| `versions[].modify_time` | string | 该版本的修改时间，格式示例：`2026-09-21 20:00:00` |
+| `versions[].modifier` | string | 该版本的修改人名称 |
+| `note` | string | 接口提示信息 |
+| `next_cursor` | string | 下一页游标；为空字符串时表示没有下一页 |
+
+### 示例
+
+```
+wecom-cli sheet version list --json '{"docid":"DOCID_EXAMPLE","limit":20,"cursor":""}'
+```
+
+### 使用规则
+
+- **按游标翻页**：只要 `next_cursor` 非空，就把它作为下一次请求的 `cursor` 继续查询；`next_cursor` 为空时停止。
+
+## 还原指定版本
+
+将指定在线表格的全部内容还原到某个历史版本。执行后保留原版本历史，并生成一个新的当前版本。
+
+### 命令
+
+使用 wecom-cli 工具按照下面格式调用
+
+```
+wecom-cli sheet version rollback --json '<JSON 参数>'
+```
+
+### 参数
+
+| 字段 | 类型 | 必填 | 默认值 | 语义 |
+|---|---|---|---|---|
+| `docid` | string | 是 | — | 在线表格 ID 或 URL |
+| `version` | int | 是 | — | 要还原到的历史版本号；必须来自 `version list` 的实际返回 |
+| `yes` | bool | 是 | — | 回滚确认；必须显式传 `true` |
+
+### 返回
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `previous_version` | int | 回滚前的当前版本号 |
+| `new_version` | int | 回滚操作生成的新版本号 |
+| `rollback_to` | int | 本次还原所依据的历史版本号 |
+
+### 示例
+
+```
+wecom-cli sheet version rollback --json '{"docid":"DOCID_EXAMPLE","version":12,"yes":true}'
+```
+
+### 使用规则
+
+- **高风险操作**：回滚影响整个工作簿。只有用户明确要求把目标文档回滚到具体版本时，才传 `"yes":true`；仅要求“看看历史版本”时不得回滚。
+- **响应一致性检查**：确认 `previous_version` 等于回滚前 `version get` 的结果，`rollback_to` 等于用户指定版本，且 `new_version` 为回滚后 `version get` 返回的当前版本。

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

@@ -0,0 +1,180 @@
+# 保护区域管理
+
+对**在线表格**中的保护区域执行新增、查询、更新、删除。用户要求“锁定表头 / 保护公式区 / 限制别人编辑某块区域”时，优先使用本文件中的真实保护能力，禁止用静态样式、提示文字或隐藏列来冒充权限控制。
+
+本文覆盖以下 CLI：
+
+| 命令 | 风险 | 用途 |
+|---|---|---|
+| `wecom-cli sheet protects add` | 结构写入 | 新增受保护区域 |
+| `wecom-cli sheet protects update` | 高风险写入 | 按 ID 修改保护区域范围 |
+| `wecom-cli sheet protects delete` | 高风险写入 | 按 ID 删除保护区域 |
+| `wecom-cli sheet protects list` | 只读 | 查询子表内保护区域清单 |
+
+> **适用边界**：仅支持普通 `sheet` 类型子表，不支持智能表。`sheet` 使用子表 ID 或名称；`range` 一律使用纯 A1，不包含子表名。
+
+> **通用口径**：结构性写入可先传 `dry_run: true` 预览，预览不代表已经执行。更新和删除保护区域必须显式传 `yes: true`。
+
+## 新增保护区域 — `wecom-cli sheet protects add`
+
+新增一个受保护区域。当前 CLI 要求显式传入 `range`。
+
+### 命令
+
+使用 wecom-cli 工具按照下面格式调用
+
+```
+wecom-cli sheet protects add --json '<JSON 参数>'
+```
+
+### 参数
+
+| 字段 | 类型 | 必填 | 默认值 | 语义 |
+|---|---|---|---|---|
+| `docid` | string | 是 | — | 在线表格 ID / URL |
+| `sheet` | string | 是 | — | 子表 ID 或名称，必须是普通 `sheet` 类型 |
+| `range` | string | 是 | — | 保护区域，纯 A1，如 `A1:C1` |
+| `name` | string | 否 | — | 保护区域备注名 |
+| `dry_run` | bool | 否 | `false` | `true` 时仅预览，不落盘 |
+
+### 返回
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `protect_range_id` | string | 新保护区域 ID；后续 `protects update` / `protects delete` 使用 |
+| `range` | string | 实际生效区域，纯 A1 |
+
+### 示例
+
+```
+wecom-cli sheet protects add --json '{"docid":"e3_ABC123","sheet":"销售","range":"A1:C1","name":"表头保护","dry_run":true}'
+```
+
+### 使用规则
+
+- **必须传范围**：实测省略 `range` 会返回“字段 'range' 必填且不能为空”。当前 CLI 不支持通过省略 `range` 来保护整张子表；若用户要求整表保护，应先确认可用范围再传显式 A1 区域。
+
+## 更新保护区域 — `wecom-cli sheet protects update`
+
+按 `protect_range_id` 修改保护范围。`range` 是替换语义，不是增量扩展。
+
+### 命令
+
+使用 wecom-cli 工具按照下面格式调用
+
+```
+wecom-cli sheet protects update --json '<JSON 参数>'
+```
+
+### 参数
+
+| 字段 | 类型 | 必填 | 默认值 | 语义 |
+|---|---|---|---|---|
+| `docid` | string | 是 | — | 在线表格 ID / URL |
+| `sheet` | string | 是 | — | 保护区域所在子表 ID 或名称 |
+| `protect_range_id` | string | 是 | — | 目标保护区域 ID；由 `protects add` / `protects list` 获得 |
+| `range` | string | 是 | — | 新保护区域，纯 A1，替换原范围 |
+| `yes` | bool | 是 | — | 确认执行；必须显式传 `true` |
+| `dry_run` | bool | 否 | `false` | `true` 时仅预览，不落盘 |
+
+### 返回
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `protect_range_id` | string | 保护区域 ID |
+| `range` | string | 更新后区域，纯 A1 |
+
+### 示例
+
+```
+wecom-cli sheet protects update --json '{"docid":"e3_ABC123","sheet":"销售","protect_range_id":"protect_001","range":"A1:D1","yes":true,"dry_run":true}'
+```
+
+### 使用规则
+
+- **先 list 再改**：更新前调用 `protects list` 定位 `protect_range_id`，不要根据数组位置或记忆中的旧 ID 修改。
+- **替换语义**：新 `range` 会覆盖原保护范围。扩大或缩小保护区都可能影响协作权限，先 `dry_run` 再正式执行。
+- **名称不能更新**：当前协议只声明修改保护范围，没有声明更新 `name` 的字段；实测额外传 `name` 会成功但被静默忽略，不要承诺可改备注名，也不要传未声明字段。
+- **写后回读**：正式更新后再次调用 `protects list`，确认目标 ID 的区域已变更。
+
+## 删除保护区域 — `wecom-cli sheet protects delete`
+
+按 `protect_range_id` 删除指定保护区域。
+
+### 命令
+
+使用 wecom-cli 工具按照下面格式调用
+
+```
+wecom-cli sheet protects delete --json '<JSON 参数>'
+```
+
+### 参数
+
+| 字段 | 类型 | 必填 | 默认值 | 语义 |
+|---|---|---|---|---|
+| `docid` | string | 是 | — | 在线表格 ID / URL |
+| `sheet` | string | 是 | — | 保护区域所在子表 ID 或名称 |
+| `protect_range_id` | string | 是 | — | 目标保护区域 ID |
+| `yes` | bool | 是 | — | 删除确认；必须显式传 `true` |
+| `dry_run` | bool | 否 | `false` | `true` 时仅预览，不落盘 |
+
+### 返回
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `protect_range_id` | string | 已删除的保护区域 ID |
+
+### 示例
+
+```
+wecom-cli sheet protects delete --json '{"docid":"e3_ABC123","sheet":"销售","protect_range_id":"protect_001","yes":true,"dry_run":true}'
+```
+
+### 使用规则
+
+- **删除不可逆**：先调用 `protects list` 核对目标 ID 与范围，再传 `dry_run: true` 预览。
+- **禁止按区域盲删**：若多个保护区域范围相近或相交，应列出候选让用户确认，最终按稳定 `protect_range_id` 删除。
+
+## 查询保护区域 — `wecom-cli sheet protects list`
+
+列出指定子表中的全部保护区域。
+
+### 命令
+
+使用 wecom-cli 工具按照下面格式调用
+
+```
+wecom-cli sheet protects list --json '<JSON 参数>'
+```
+
+### 参数
+
+| 字段 | 类型 | 必填 | 默认值 | 语义 |
+|---|---|---|---|---|
+| `docid` | string | 是 | — | 在线表格 ID / URL |
+| `sheet` | string | 是 | — | 子表 ID 或名称，必须是普通 `sheet` 类型 |
+
+### 返回
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `protect_ranges` | array | 保护区域清单；无保护区域时当前实测可能缺失该字段 |
+| `protect_ranges[].protect_range_id` | string | 保护区域 ID |
+| `protect_ranges[].range` | string | 保护区域，纯 A1 |
+
+### 示例
+
+```
+wecom-cli sheet protects list --json '{"docid":"e3_ABC123","sheet":"销售"}'
+```
+
+### 使用规则
+
+- **不返回名称**：返回值没有 `name`，不能按备注名直接定位；用 `range` 辅助识别，用 `protect_range_id` 执行更新或删除。
+- **操作前置**：更新和删除保护区域前必须先通过本命令拿到当前 ID 与范围。
+
+## 能力边界
+
+- 当前 CLI 不支持通过省略 `range` 创建整表保护；`protects add` 必须传显式 A1 区域。
+- 当前协议没有声明保护区域的成员、角色、例外编辑者或密码字段；不要自行构造权限明细参数。