@rezti/dsh-rez-suite 0.1.49 → 0.1.51

package/templates/shared/wecomcli-smartsheet/references/smart-sheet-edit.md

@@ -0,0 +1,589 @@
+# 智能表格操作参考
+
+企业微信智能表格的读取与编辑操作，支持读取表格信息与数据、修改表结构（子表/字段）、修改记录、修改视图、修改图表、修改样式。
+
+> **对应 doc_type 值**：`smartsheet`（智能表格）
+>
+> **适用 docid 前缀**：`s3_`
+
+> `docid` 参数名全小写无下划线，其他行为约束见 `SKILL.md`。
+>
+> **警惕数据破坏行为**：
+> 1. 批量删除记录、清空字段、删除子表等不可逆操作，执行前必须确保用户给出了**明确、具体的保留策略**（如"删除 2026 年 3 月之前的所有记录"、"只保留状态为已完成的行"）。若用户描述模棱两可（如"删除全部"、"删掉就好了"、"清一下"），**必须先向用户确认**具体的删除范围与保留条件，不得直接执行
+> 2. 删除最后一个子表/字段/视图固定流程时，由于智能表格至少需要保留一个子表、一个字段、一个视图，所以执行删除操作前必须先用 `wecom-cli smartsheet sheets list`、`wecom-cli smartsheet fields list` 或 `wecom-cli smartsheet records query` 确认对应资源的数量；若只剩 1 个，先用简洁自然语言向用户明确确认是否继续。如果用户明确要求删除/重建/重置/数据不要了，禁止先试探删除，禁止改成清空数据，禁止追问方案。必须先新增一个最小占位资源（子表/字段/视图），再删除目标资源。
+
+---
+
+## 场景导航
+
+根据操作意图，快速定位到对应的接口：
+
+| 用户场景/意图 | 对应命令 | 说明 |
+| --- | --- | --- |
+| 从零新建智能表格并初始化子表字段 | `wecom-cli smartsheet create` | 写操作，接口详见 `references/common.md` |
+| 导入本地/已上传文件为智能表格 | `wecom-cli smartsheet import` | 写操作，接口详见 `references/common.md` |
+| 查看智能表格子表列表 | `wecom-cli smartsheet sheets list` | 读操作，接口说明见 `references/smart-sheet-read.md` |
+| 读取指定子表的行记录数据、按条件筛选数据 | `wecom-cli smartsheet records query` | 读操作，接口说明见 `references/smart-sheet-read.md` |
+| 查询字段列表 | `wecom-cli smartsheet fields list` | 读操作，接口说明见 `references/smart-sheet-read.md` |
+| 查询视图列表 | `wecom-cli smartsheet views list` | 读操作，接口说明见 `references/smart-sheet-read.md` |
+| 查询图表列表 | `wecom-cli smartsheet charts list` | 读操作，接口说明见 `references/smart-sheet-read.md` |
+| 新建/修改/删除子表 | `wecom-cli smartsheet sheets add` / `wecom-cli smartsheet sheets update` / `wecom-cli smartsheet sheets delete` | 写操作，支持新增/修改/删除子表 |
+| 新建/修改/删除字段 | `wecom-cli smartsheet fields add` / `wecom-cli smartsheet fields update` / `wecom-cli smartsheet fields delete` | 写操作，字段操作独立命令 |
+| 新建/修改/删除行记录 | `wecom-cli smartsheet records add` / `wecom-cli smartsheet records update` / `wecom-cli smartsheet records delete` | 写操作，支持新增/修改/删除行记录 |
+| 新增/修改记录返回 `851003` / `no authority` | Webhook 兜底写入 | 停止重试 CLI，完整阅读 `references/smart-sheet-webhook.md` 后按其流程处理 |
+| 新建/修改/删除视图 | `wecom-cli smartsheet views add` / `wecom-cli smartsheet views update` / `wecom-cli smartsheet views delete` | 写操作，支持新增/修改/删除视图 |
+| 新建/修改/删除图表 | `wecom-cli smartsheet charts add` / `wecom-cli smartsheet charts update` / `wecom-cli smartsheet charts delete` | 写操作，支持新增/修改/删除仪表盘图表 |
+---
+
+## 编辑强制规范
+
+1. **写前必读**——执行新增/修改记录前，先 `wecom-cli smartsheet records query` 读取 3-5 条现有记录，对齐用词习惯（如是否采用"动词+名词"结构）和单选/多选字段的已有选项。
+2. **新建字段/子表后必须调整列宽**——新增字段完成后，必须立即按 `references/smart-sheet-view-types.md` 中「新建字段时的列宽判断规则」确定各字段列宽，并调用 `wecom-cli smartsheet views update` 写入。
+3. **优先推荐公式字段**——用户要求新增字段且字段值可由表内其他字段计算/推导得出时：用户未指定类型则直接用 `formula`；用户已指定其他类型则说明公式字段优势并询问意见，不得擅自改变。
+4. **参考文档 vs 目标文档**——用户表达"参考/模仿/按照…格式"时，该文档是结构模板而非写入目标：① 读取参考文档字段结构 → ② 新建智能表格 → ③ 向新表写入数据。
+5. **更新记录必须一次完成**——`wecom-cli smartsheet records update` 对单次更新的记录无数量限制，任何记录更新操作必须一次完成，**严禁**拆分请求。
+
+---
+
+## 接口说明
+
+### 一、子表操作（smartsheet sheets add / update / delete）
+
+> **命令说明**：
+> - `wecom-cli smartsheet sheets add`：新增子表
+> - `wecom-cli smartsheet sheets update`：修改子表名称
+> - `wecom-cli smartsheet sheets delete`：删除子表
+
+#### **前置必读**：创建时初始化字段（推荐）
+
+> ✅ **创建智能表格时，优先使用 `wecom-cli smartsheet create` 一次性初始化子表字段，不要再拆成"先建表、再补字段"两步。**
+
+根据 `wecom-cli smartsheet create` 接口说明（详见 `references/common.md` ），支持在创建阶段同时传入 `sheet_title` 与 `fields`，可直接完成默认子表及字段初始化。
+
+**推荐流程（新建场景）：**
+
+1. 调用 `wecom-cli smartsheet create` 创建智能表格，并同时传入 `sheet_title` + `fields`
+2. 从返回值获取 `docid` 和所有字段的 `field_title`
+3. 按 `references/smart-sheet-view-types.md` 中「新建字段时的列宽判断规则」和「列宽调整接口调用方式」完成列宽写入
+4. 后续如需调整，再调用 `wecom-cli smartsheet sheets update` 做增量修改
+
+**示例（创建时直接初始化字段）：**
+
+```bash
+wecom-cli smartsheet create --json '{"name": "任务跟踪表", "sheet_title": "任务列表", "fields": [{"field_title": "任务名称", "field_type": "text"}, {"field_title": "优先级", "field_type": "single_select", "property_single_select": {"is_quick_add": true, "options": [{"text": "高", "style": 18}, {"text": "中", "style": 20}, {"text": "低", "style": 16}]}}, {"field_title": "负责人", "field_type": "user", "property_user": {"is_multiple": false, "is_notified": true}}]}'
+```
+
+**兜底流程（仅当历史表已创建且未按创建阶段初始化时使用）：**
+
+1. 调用 `wecom-cli smartsheet sheets list` 获取当前子表列表，再调用 `wecom-cli smartsheet fields list` 获取字段列表（含 `field_title`）
+2. 用 `wecom-cli smartsheet fields update` 重命名可复用字段（仅在类型兼容时）
+3. 用 `wecom-cli smartsheet fields delete` 删除多余字段（注意至少保留一个文本类型字段）
+4. 用 `wecom-cli smartsheet fields add` 补充缺失字段
+5. 按 `references/smart-sheet-view-types.md` 中「新建字段时的列宽判断规则」和「列宽调整接口调用方式」对所有新增字段完成列宽写入
+
+根据文档 ID，新建、更新、删除工作表及字段（支持批处理）。
+
+
+```bash
+wecom-cli smartsheet sheets add --json '{...}'
+wecom-cli smartsheet sheets update --json '{...}'
+wecom-cli smartsheet sheets delete --json '{...}'
+```
+
+**请求参数 (JSON 格式传入)：**
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `docid` | string | 是 | 文档 ID |
+| `sheet_title` | string | 是 | 子表名称。`add` 时该字段表示新增子表的名称；`update`/`delete` 时用于定位子表 |
+| `new_sheet_title` | string | 否 | 新子表名称。`update` 修改子表名称时传此字段 |
+| `fields` | Field[] | 否 | 仅 `sheets add` 新增子表时可传，用于同时初始化列 |
+| `sheet_type` | string | 否 | 子表类型，仅 `sheets add` 新增子表时使用，不传则默认为 `smartsheet`，可选值：`smartsheet`、`dashboard` |
+
+**情形分类总览：**
+
+根据命令和参数组合，共分为以下场景：
+
+| 场景 | 命令 | sheet_title | new_sheet_title | sheet_type | fields |
+| --- | --- | --- | --- | --- | --- |
+| 新增子表 | `sheets add` | **必传** | 不传 | 可选（默认 `smartsheet`） | 可选（仅用于初始化列） |
+| 修改子表名称 | `sheets update` | **必传** | **必传** | — | **不传**（字段操作用 `fields` 命令） |
+| 删除子表 | `sheets delete` | **必传** | 不传 | — | **不传** |
+
+> 完整字段类型枚举（20+ 种）及 `property_xxx` 属性定义见 `references/smart-sheet-field-types.md`。
+> **字段操作（新增/修改/删除字段）统一使用 `wecom-cli smartsheet fields` 命令，不通过 `sheets` 命令操作字段（`sheets add` 初始化列除外）。**
+
+#### 场景 1：新增子表
+
+创建新的子表或仪表盘。
+
+> **执行前必须检查重名**：
+> - 子表名称在同一智能表格内不可重复。先调用 `wecom-cli smartsheet sheets list` 获取现有子表列表，确认不存在同名子表。
+> - 同一子表中的字段名称不可重复。执行前必须先确认初始化字段中不包含同名字段。
+
+> 智能表格在全新创建时默认可能会创建几条空记录，请先清理掉。
+
+**参数要求：**
+
+- `sheet_title`：**必传**，子表标题
+- `sheet_type`：可选，默认 `smartsheet`（普通数据表），可选 `dashboard`（仪表盘）
+- `fields`：可选。若传入，则会在**创建子表的同时初始化列**。`sheets add` 新增子表时传 `fields`，效果与「场景2：新增字段」相同，每个 Field 需传 `field_title` + `field_type` + 对应的 `property`（详见 `references/smart-sheet-field-types.md` ）
+
+**示例 1 — 新增普通子表：**
+
+```bash
+wecom-cli smartsheet sheets add --json '{"docid": "s3_xxx", "sheet_title": "需求池"}'
+```
+
+**示例 2 — 新增仪表盘：**
+
+```bash
+wecom-cli smartsheet sheets add --json '{"docid": "s3_xxx", "sheet_title": "数据看板", "sheet_type": "dashboard"}'
+```
+
+**示例 3 — 新增子表并同时初始化字段：**
+
+```bash
+wecom-cli smartsheet sheets add --json '{"docid": "s3_AcDeFg", "sheet_title": "任务跟踪", "fields": [{"field_title": "任务名称", "field_type": "text"}, {"field_title": "优先级", "field_type": "single_select", "property_single_select": {"is_quick_add": true, "options": [{"text": "高", "style": 18}, {"text": "中", "style": 20}, {"text": "低", "style": 16}]}}, {"field_title": "负责人", "field_type": "user", "property_user": {"is_multiple": false, "is_notified": true}}]}'
+```
+
+> ✅ **提示**：新增子表时支持**一步到位**传入 `fields`，无需先建子表再单独调用新增字段。
+
+**创建子表后，必须立即调整列宽（强制）：**
+
+- 若创建时传入了 `fields`：从返回值取得各字段的 `field_title`，按 `references/smart-sheet-view-types.md` 中「新建字段时的列宽判断规则」和「列宽调整接口调用方式」完成列宽写入
+- 若创建时未传入 `fields`：调用 `wecom-cli smartsheet fields list` 取得字段列表和 `field_title`，再按上述规则完成列宽写入
+
+#### 场景 2：修改子表名称
+
+修改已有子表的名称，可同时修改列。
+
+**参数要求：**
+
+- `sheet_title`：**必传**，定位目标子表；修改子表名称时传当前名称，新名称用 `new_sheet_title` 传入
+- `new_sheet_title`：**必传**，新的子表名称
+- `fields`：可选，可同时修改列定义
+
+**示例：**
+
+```bash
+wecom-cli smartsheet sheets update --json '{"docid": "s3_xxx", "sheet_title": "需求池", "new_sheet_title": "需求管理"}'
+```
+
+#### 场景 3：删除子表
+
+删除整个子表。
+
+**参数要求：**
+
+- `sheet_title`：**必传**，要删除的子表名称
+
+> 👆 若只剩最后一个子表，须遵循上方**删除最后一个子表/字段/视图固定流程**。
+
+**示例：**
+
+```bash
+wecom-cli smartsheet sheets delete --json '{"docid": "s3_xxx", "sheet_title": "需求池"}'
+```
+
+---
+
+### 二、字段操作（smartsheet fields add / update / delete）
+
+> - `wecom-cli smartsheet fields add`：新增字段
+> - `wecom-cli smartsheet fields update`：修改字段
+> - `wecom-cli smartsheet fields delete`：删除字段
+
+> 新增字段（`add`）或修改字段名称（`update`）之前必须调用 `wecom-cli smartsheet fields list` 检查是否存在同名字段，字段名称在同一子表内不可重复
+
+```bash
+wecom-cli smartsheet fields add --json '{"docid": "<docid>", "sheet_title": "<子表名称>", "fields": [...]}'
+wecom-cli smartsheet fields update --json '{"docid": "<docid>", "sheet_title": "<子表名称>", "fields": [...]}'
+wecom-cli smartsheet fields delete --json '{"docid": "<docid>", "sheet_title": "<子表名称>", "fields": [{"field_title": "<字段名>"}]}'
+```
+
+**请求参数 (JSON 格式传入)：**
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `docid` | string | 是 | 文档 ID |
+| `sheet_title` | string | 是 | 目标子表名称 |
+| `fields` | Field[] | 是 | 字段列表，结构与 `sheets update` 中的 `fields` 完全相同 |
+
+**Field 字段填写规则：**
+
+| 操作命令 | Field 需传字段 | 说明 |
+| --- | --- | --- |
+| `fields add` | `field_title` + `field_type` + `property_xxx` | 新增字段时必须指定标题、类型，以及对应类型的属性 |
+| `fields update` | `field_title` + `field_type`（必传） + 可选 `new_field_title` / `property_xxx` | 修改字段时必须指定字段名称和字段类型 |
+| `fields delete` | `field_title` | 删除字段时需指定字段名称 |
+
+> 完整字段类型枚举及 `property_xxx` 属性定义见 `references/smart-sheet-field-types.md`。
+
+**新增字段后，必须立即调整列宽（强制）：**
+
+从返回值取得所有新建字段的 `field_title`，按 `references/smart-sheet-view-types.md` 中「新建字段时的列宽判断规则」和「列宽调整接口调用方式」完成列宽写入。
+
+---
+
+### 三、记录操作（smartsheet records add / update / delete）
+
+根据文档 ID 和工作表 ID，新建、更新、删除记录（支持批处理）。
+
+> - `wecom-cli smartsheet records add`：新增记录
+> - `wecom-cli smartsheet records update`：修改记录
+> - `wecom-cli smartsheet records delete`：删除记录
+
+> `wwgroup`（群）不支持 API 写入。写前必读机制见本文件「编辑强制规范」。
+
+```bash
+wecom-cli smartsheet records add --json '{"docid": "<docid>", "sheet_title": "<子表名称>", "records": [{"values": {"<字段名称>": "<字段值>"}}]}'
+wecom-cli smartsheet records update --json '{"docid": "<docid>", "sheet_title": "<子表名称>", "records": [{"record_id": "<记录ID>", "values": {"<字段名称>": "<字段值>"}}]}'
+wecom-cli smartsheet records delete --json '{"docid": "<docid>", "sheet_title": "<子表名称>", "records": [{"record_id": "<记录ID>"}]}'
+```
+
+**请求参数 (JSON 格式传入)：**
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `docid` | string | 是 | 文档 ID |
+| `sheet_title` | string | 是 | 子表名称，用于定位目标子表 |
+| `records` | array | 是 | 行记录列表；单次请求长度为 1~2000，不允许传空；总量超过 2000 时按每批最多 2000 条拆分请求 |
+| `records[].record_id` | string | 否 | 行记录 ID（修改或删除时必填） |
+| `records[].values` | object | 否 | 字段值，key 为字段名称（`field_title`），value 格式取决于字段类型，详见 `references/smart-sheet-record-values.md` |
+
+> - `records add`：records 只传 `values`
+> - `records update`：records 传 `record_id` + `values`
+> - `records delete`：records 只需传 `record_id`
+> - 单次请求的 `records` 数组最多 2000 条。待处理记录总量不限；超过 2000 条时必须拆成多次请求，每批最多 2000 条，直至全部完成
+
+#### Record 值格式示例
+
+| 字段类型 | 值格式 | 示例 |
+| --- | --- | --- |
+| 文本 | 字符串 | `{"品牌": "金士顿"}` |
+| 数字 | 直接数字 | `{"价格": 399}` |
+| 日期 | 标准日期格式字符串 | `{"日期": "YYYY-MM-DD HH:mm:ss"}` |
+| 单选/多选 | `[{"id": "选项ID", "text": "选项文本"}]` | `{"状态": [{"id": "opt_xxx", "text": "进行中"}]}` |
+| 人员 | `[{"userId": "userid", "userName": "姓名"}]`（写入支持仅传其一） | `{"负责人": [{"userName": "张三"}]}` |
+
+**属性枚举值**：必须严格使用 `references/smart-sheet-field-types.md` 中定义的常量。
+
+**字段键名**：必须使用 field_title（字段名称，如 `品牌`），不能使用 field_id（如 `f04Gwj`）。
+
+**请求示例：**
+
+**新增行（使用 `sheet_title` 定位子表，`field_title` 作为 values 的 key）：**
+
+```json
+{
+  "docid": "DOCID",
+  "sheet_title": "任务列表",
+  "records": [
+    {
+      "values": {
+        "任务名称": "新任务A",
+        "预算": 100,
+        "状态": [{ "id": "opt_1", "text": "进行中", "style": 3 }]
+      }
+    }
+  ]
+}
+```
+
+**更新行：**
+
+```json
+{
+  "docid": "DOCID",
+  "sheet_title": "任务列表",
+  "records": [
+    {
+      "record_id": "re9IqD",
+      "values": {
+        "任务名称": "更新后的任务名",
+        "状态": [{ "id": "opt_2", "text": "已完成", "style": 4 }]
+      }
+    }
+  ]
+}
+```
+
+**删除行：**
+
+```json
+{
+  "docid": "DOCID",
+  "sheet_title": "任务列表",
+  "records": [{ "record_id": "re9IqD" }, { "record_id": "rpS0P9" }]
+}
+```
+> 提示：**values** 中的 key 必须是**字段名称**，可通过 `wecom-cli smartsheet fields list` 获取。各字段类型的 value 格式详见 `references/smart-sheet-record-values.md`。
+
+**返回值：**
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `errcode` | int | `0` 表示执行成功 |
+| `records` | array | 写入的行记录列表，每项包含 `record_id` 和 `values` |
+
+#### `851003 no authority` 的 Webhook 兜底
+
+`wecom-cli smartsheet records add` 或 `wecom-cli smartsheet records update` 返回 `errcode: 851003`，或 `errmsg` 包含 `no authority` 时，通常表示企业可见范围超过 10 人，CLI 写入接口受到规模限制。此时：
+
+1. 停止重试 CLI 写入；
+2. 完整阅读 `references/smart-sheet-webhook.md`；
+3. 临时向用户索取目标子表的 Webhook 完整 URL 和「接收外部数据」页面的 schema 示例 JSON；
+4. 使用 Webhook 专用字段格式构造并发送请求；
+5. 写入完成后仍按 `references/smart-sheet-read.md` 读取目标数据进行验证。
+
+仅新增和更新记录使用该兜底。删除记录、结构操作、参数错误、字段错误、文档不存在等场景不应切换 Webhook。Webhook 更新还受额外限制：只能更新此前通过 Webhook 写入的记录，不能更新人工创建或通过普通接口创建的记录。
+
+### 四、视图操作（smartsheet views add / update / delete）
+
+根据文档 ID 和工作表 ID，新建、更新、删除视图，以及调整列宽。
+
+> - `wecom-cli smartsheet views add`：新增视图
+> - `wecom-cli smartsheet views update`：修改视图
+> - `wecom-cli smartsheet views delete`：删除视图
+
+> **新建视图前必须查重**：
+> 1. 先调用 `wecom-cli smartsheet views list --json '{"docid":"<docid>","sheet_title":"<子表名称>","limit":100}'` 获取现有视图。
+> 2. 如果同名视图已存在，优先用简洁自然语言询问用户是否修改该视图；如果用户不同意，则请用户提供新名称，或者询问是否在原名称后追加数字，不得自行决定。
+
+```bash
+wecom-cli smartsheet views add --json '{"docid": "<docid>", "sheet_title": "<子表名称>", "views": [...]}'
+wecom-cli smartsheet views update --json '{"docid": "<docid>", "sheet_title": "<子表名称>", "views": [...]}'
+wecom-cli smartsheet views delete --json '{"docid": "<docid>", "sheet_title": "<子表名称>", "views": [...]}'
+```
+
+> 📖 **完整参数结构（ViewParam、ViewType 枚举、ViewProperty、甘特/日历视图属性、过滤/排序/分组/填色/列宽等）均定义在 `references/smart-sheet-view-types.md`，使用前必须查阅，禁止凭猜测填写。**
+
+**顶层参数：**
+
+**请求参数 (JSON 格式传入)：**
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `docid` | string | 是 | 文档 ID |
+| `sheet_title` | string | 是 | 子表名称，用于定位目标子表 |
+| `views` | ViewParam[] | 否 | 视图信息列表，结构见 `references/smart-sheet-view-types.md` |
+
+**返回值：**
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `errcode` | int | `0` 表示执行成功 |
+| `views` | array | 写入的视图信息列表，每项包含 `view_id`、`view_title`、`view_type`、`property` |
+
+---
+
+### 五、图表操作（smartsheet charts add / update / delete）
+
+根据文档 ID 和工作表 ID，新建、更新、删除图表。
+
+> 无论是新建、更新一个图表还是多个图表，在请求体里传入一个charts数组，传入一个或多个图表。
+> 更新图表时，必须把原有的属性参数，一并传入（后台不支持Partial属性合并）。
+> 图表都有自己的布局位置（layout，由x，y坐标和宽高决定）。在修改图表时，必须确保 layout 不与现有的任意一个图表重叠。
+
+```bash
+wecom-cli smartsheet charts add --json '{"docid": "<docid>", "sheet_title": "<仪表盘名称>", "charts": [{"id": "<图表ID>", "type": "<图表类型>", "datasource": "<数据表名称>", "layout": {"xy": [0, 0], "width_height": [3, 4]}}]}'
+wecom-cli smartsheet charts update --json '{"docid": "<docid>", "sheet_title": "<子表名称>", "charts": [{"id": "<图表ID>", ...}]}'
+wecom-cli smartsheet charts delete --json '{"docid": "<docid>", "sheet_title": "<子表名称>", "charts": [{"id": "<图表ID>"}]}'
+```
+
+**请求参数 (JSON 格式传入)：**
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `docid` | string | 是 | 文档 ID |
+| `sheet_title` | string | 是 | 子表名称（仪表盘名称），用于定位目标子表 |
+| `charts` | Chart[] | 是 | 图表结构列表，【**必须**】查阅 `references/smart-sheet-chart-types.md` 中的 Chart 结构定义，【**禁止**】凭猜测填写图表参数 |
+
+> 完整图表类型定义见 `references/smart-sheet-chart-types.md`，使用前必须查阅。
+
+> **combo 图（组合图/双轴图）的特殊约束**：
+> - `combo` 图的 `series` 必须 **≥ 2 项**，**不能为空数组**（combo 的语义是"柱+线"等多系列组合，单系列或零系列不成立）；
+
+#### 图表创建前的字段校验
+在创建图表时，如果用户指定的字段无法满足需求，应该：
+1. 先校验用户指定的字段类型是否支持该图表类型
+2. 如果不支持，直接告知用户无法执行，说明原因
+3. 提供替代方案并等待用户确认后再执行
+
+**请求示例：**
+
+**新增图表：**
+
+```json
+{
+  "docid": "DOCID",
+  "sheet_title": "数据看板",
+  "charts": [
+    {
+      "title": "月度销售趋势",
+      "type": "line",
+      "datasource": "任务列表",
+      "category": {
+        "field_title": "月份"
+      },
+      "series": [
+        {
+          "field_title": "销售额",
+          "aggregation": "sum"
+        },
+        {
+          "field_title": "利润",
+          "aggregation": "avg"
+        }
+      ],
+      "layout": {
+        "width_height": [3, 4],
+        "xy": [0, 0]
+      }
+    }
+  ]
+}
+```
+
+**更新图表：**
+
+```json
+{
+  "docid": "DOCID",
+  "sheet_title": "数据看板",
+  "charts": [
+    {
+      "id": "cht_001",
+      "title": "年度销售趋势",
+      "type": "bar",
+      "datasource": "任务列表",
+      "category": {
+        "field_title": "季度",
+        "sub_field_title": "区域"
+      },
+      "series": [
+        {
+          "field_title": "销售额",
+          "aggregation": "sum"
+        }
+      ],
+      "layout": {
+        "width_height": [6, 4],
+        "xy": [0, 0]
+      }
+    }
+  ]
+}
+```
+
+**删除图表：**
+
+```json
+{
+  "docid": "DOCID",
+  "sheet_title": "数据看板",
+  "charts": [
+    {
+      "id": "cht_001"
+    }
+  ]
+}
+```
+
+**返回值：**
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `errcode` | int | `0` 表示执行成功 |
+| `charts` | array | 写入的图表信息列表，每项包含 `id`、`title`、`type`、`datasource` 等 |
+
+---
+
+## 典型工作流与示范
+
+以下示例展示常见的智能表格操作流程，供参考。
+
+> **读取类操作的通用流程**：若用户未提供 `docid`，先通过 `wecomcli-doc-manage` 技能的搜索文档接口获取；再调用 `wecom-cli smartsheet sheets list` 获取子表列表，如需字段详情或未返回 `fields`，必须针对具体子表调用 `wecom-cli smartsheet fields list`。
+
+### 示例一：向智能表格新增记录
+
+**用户意图**：「在智能表格 s3_xxx 的"需求池"子表中新增一条记录，标题为"登录优化"，优先级为"高"」
+
+**执行步骤**：
+
+1. 先调用 `wecom-cli smartsheet sheets list` 获取子表列表，确认"需求池"子表存在；
+2. 调用 `wecom-cli smartsheet fields list` 查询"需求池"的字段详情，确认"标题"字段（类型为文本）和"优先级"字段（类型为单选）存在，并取得单选选项 ID；
+3. 调用 `wecom-cli smartsheet records add` 新增记录：
+   ```
+   {"docid": "s3_xxx", "sheet_title": "需求池", "records": [{"values": {"标题": "登录优化", "优先级": [{"id": "opt_xxx", "text": "高"}]}}]}
+   ```
+4. 新增成功后告知用户。
+
+若第 3 步返回 `851003` / `no authority`，不要重复调用 `records add`；改为完整阅读 `references/smart-sheet-webhook.md`，向用户临时索取 Webhook 完整 URL 与 schema 示例 JSON 后走 Webhook 兜底写入。
+
+---
+
+### 示例二：修改表结构
+
+**用户意图**：「把智能表格 s3_xxx 中"需求池"这个子表删除」
+
+**执行步骤**：
+
+1. 先调用 `wecom-cli smartsheet sheets list` 确认"需求池"子表存在：
+   ```
+   {"docid": "s3_xxx"}
+   ```
+2. 调用 `wecom-cli smartsheet sheets delete` 执行删除子表（不传 `fields`）：
+   ```
+   {"docid": "s3_xxx", "sheet_title": "需求池"}
+   ```
+3. 删除成功后告知用户。
+
+---
+
+## 注意事项
+
+> 以下为编辑接口的补充说明；通用安全和交互约束见 `SKILL.md`。
+
+- **创建时一次性初始化字段**：新建智能表格时，优先使用 `wecom-cli smartsheet create` 并同时传入 `sheet_title` + `fields`，避免拆分为"创建后再补字段"
+- **默认字段处理仅作兜底**：仅当历史表已创建且字段不符合需求时，再通过 `wecom-cli smartsheet sheets list` + `wecom-cli smartsheet fields list` + `wecom-cli smartsheet fields update/delete/add` 执行重命名/删除/新增
+- **至少保留一个文本字段**：删除接口要求至少保留一个文本类型字段
+- **字段操作统一用 `fields` 命令**：新增/修改/删除字段一律使用 `wecom-cli smartsheet fields add/update/delete`，不通过 `sheets` 命令操作字段（`sheets add` 初始化列除外）
+- **新增子表可同时创建字段**：`sheets add` 时可传入 `fields` 一步到位
+- **字段添加顺序**：系统按添加顺序排列，建议按业务逻辑顺序依次添加
+- **添加/更新字段必须带属性**：日期、超链接、人员、单选、多选、数字等类型须带 `property_xxx`，仅纯文本无需
+- **人员字段值格式**：`[{"userId": "<userid>"}]` 或者 `[{"userName": "<姓名>"}]`
+- **日期字段值格式**：标准日期字符串 `"YYYY-MM-DD HH:mm:ss"`，非时间戳
+- **单表限制**：单个子表最多 20000 条记录、150 个字段
+- **附件文档默认仅作参考**：用户表达"参考/按上传表头格式"等意图时，默认新建智能表格写入，上传文档仅作结构参考；在未明确写回授权前禁止对上传文档执行写操作
+
+---
+
+## 参数补全
+
+当用户提供的信息不足以完成操作时（如缺少必填参数），**必须用简洁自然语言追问缺失或有歧义的信息；有候选项时在文字中列出，禁止自行猜测默认值。**
+
+### 何时触发？
+
+当用户发起智能表格操作的意图，但以下任一必填信息缺失时，触发参数补全：
+
+| 缺失信息 | 对应接口/字段 | 示例用户表述 |
+| --- | --- | --- |
+| 目标智能表格 | `docid`（所有接口） | "帮我看看智能表格的数据"（没说哪个智能表格）/ "参考xxx附件，转为智能表格"（没说是在原有表格上修改还是新建表格） |
+| 子表 | `sheet_title`（records add/update/delete/query、views add/update/delete、charts add/update/delete） | "帮我加条记录"（没说加到哪个子表） |
+| 操作类型 | 命令动词（sheets/records/views/charts 的 add/update/delete） | "帮我改一下表格"（没说是新增、修改还是删除） |
+| 子表名称 | `sheet_title`（sheets add） | "帮我新建一个子表"（没说叫什么名字） |
+| 字段定义 | `fields`（sheets add 初始化列时） | "帮我加几个字段"（没说加什么字段、什么类型） |
+| 记录内容 | `records[].values`（records add） | "帮我往表里加条数据"（没说加什么内容） |
+
+### 正确做法
+
+1. 分析用户已提供的信息，确定哪些必填参数缺失
+2. **仅对缺失的参数进行提问**（用户已明确的参数不要重复问）
+3. 收到用户回答后，组装完整的入参；四要素唯一确定时直接执行，只有业务规则要求确认的场景再用自然语言明确确认
+
+### 禁止事项
+
+- ❌ 参数缺失时自行猜测默认值（如随意假设目标智能表格、子表、字段类型或记录内容）
+- ❌ 用户已明确的参数还重复提问