@rezti/dsh-rez-suite 0.1.49 → 0.1.51

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

@@ -0,0 +1,356 @@
+# 视图类型（ViewType）完整参考
+
+## View（视图结构）
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `view_id` | string | 视图 ID |
+| `view_title` | string | 视图标题 |
+| `view_type` | string (ViewType) | 视图类型，见下方 ViewType 枚举 |
+| `property` | ViewProperty | 视图属性 |
+
+---
+
+## ViewParam（视图操作参数）
+
+统一结构，根据操作指令不同使用不同字段组合：
+
+> - `smartsheet views add` 时：传 `view_title` + `view_type`，甘特视图传 `property_gantt`，日历视图传 `property_calendar`
+> - `smartsheet views update` 时：传 `view_id`，可选传 `view_title` 和 `property`。**不支持修改视图类型**，只能修改同一视图下的标题和属性（如筛选、排序、分组等），不能将一种视图类型改为另一种（例如不能把表格视图改为看板视图）。如需更换视图类型，只能先删除旧视图再新增新视图
+> - `smartsheet views delete` 时：只传 `view_id`。若该子表只剩最后一个视图，须遵循 `references/smart-sheet-edit.md` 顶部**删除最后一个子表/字段/视图固定流程**处理
+
+| 字段 | 类型 | 必须 | 说明 |
+| --- | --- | --- | --- |
+| `view_id` | string | 条件 | 视图 ID（update、delete 时必传） |
+| `view_title` | string | 条件 | 视图标题（add 时必传，update 时可选） |
+| `view_type` | string (ViewType) | 条件 | 视图类型（add 时必传），见下方 ViewType 枚举 |
+| `property` | ViewProperty | 否 | 视图属性（update 时可选） |
+| `property_gantt` | GanttViewProperty | 否 | 甘特视图属性（add 甘特视图时必填） |
+| `property_calendar` | CalendarViewProperty | 否 | 日历视图属性（add 日历视图时必填） |
+| `col_infos` | ViewColInfos[] | 否 | 列宽设置 |
+
+---
+
+## ViewType 枚举
+
+| 参数值 | 说明 |
+| --- | --- |
+| `grid` | 表格视图 |
+| `kanban` | 看板视图 |
+| `gallery` | 画册视图 |
+| `gantt` | 甘特视图 |
+| `calendar` | 日历视图 |
+| `form` | 表单视图 |
+
+---
+
+## 特殊视图属性
+
+### GanttViewProperty（甘特视图属性）
+
+| 参数 | 类型 | 必须 | 说明 |
+| --- | --- | --- | --- |
+| `start_date_field_title` | string | 是 | 时间条起点字段名称，只允许日期类型 |
+| `end_date_field_title` | string | 是 | 时间条终点字段名称，只允许日期类型 |
+
+### CalendarViewProperty（日历视图属性）
+
+| 参数 | 类型 | 必须 | 说明 |
+| --- | --- | --- | --- |
+| `start_date_field_title` | string | 是 | 时间条起点字段名称，只允许日期类型 |
+| `end_date_field_title` | string | 是 | 时间条终点字段名称，只允许日期类型 |
+
+### ViewColInfos（列宽信息）
+
+| 参数 | 类型 | 必须 | 说明 |
+| --- | --- | --- | --- |
+| `field_title` | string | 是 | 字段名称 |
+| `width` | int32 | 是 | 列宽，范围 1～1000 |
+
+#### 列宽调整接口调用方式
+
+通过 `smartsheet views update` 的 `col_infos` 参数设置列宽，调用前须先获取目标视图的 `view_id`：
+
+```bash
+# 1. 获取视图列表，取第一个视图的 view_id
+wecom-cli smartsheet views list --json '{"docid": "<docid>", "sheet_title": "<子表名称>", "limit": 100}'
+
+# 2. 调用 views update 设置列宽（可一次性传入所有字段）
+wecom-cli smartsheet views update --json '{
+  "docid": "<docid>",
+  "sheet_title": "<子表名称>",
+  "type": "update",
+  "views": [{
+    "view_id": "<view_id>",
+    "col_infos": [
+      {"field_title": "任务名称", "width": 280},
+      {"field_title": "优先级", "width": 160},
+      {"field_title": "状态", "width": 120}
+    ]
+  }]
+}'
+```
+
+#### 新建字段时的列宽判断规则
+
+新建字段（含随子表初始化的字段）后，AI 须为每个字段选择合适的列宽档位，最终写入对应的 px 值。共 4 个档位：
+
+| 档位 | 宽度 |
+| --- | --- |
+| `compact` | 120px |
+| `default` | 160px |
+| `wide` | 280px |
+| `extra_wide` | 400px |
+
+**判断依据：字段类型初始档位 + 字段名语义**
+
+**第一步：按字段类型查初始档位**
+
+| 字段类型 | 初始档位 | 备注 |
+| --- | --- | --- |
+| `checkbox` | `compact` | 固定，跳过第二步 |
+| `number` | `compact` | 固定，跳过第二步 |
+| `autonumber` | `compact` | 固定，跳过第二步 |
+| `currency` | `compact` | 固定，跳过第二步 |
+| `percentage` | `compact` | 固定，跳过第二步 |
+| `progress` | `compact` | 固定，跳过第二步 |
+| `phone_number` | `compact` | 固定，跳过第二步 |
+| `barcode` | `compact` | 固定，跳过第二步 |
+| `date_time`（紧凑格式） | `compact` | 固定，跳过第二步 |
+| `created_time`（紧凑格式） | `compact` | 固定，跳过第二步 |
+| `modified_time`（紧凑格式） | `compact` | 固定，跳过第二步 |
+| `date_time`（宽松格式） | `default` | 固定，跳过第二步 |
+| `created_time`（宽松格式） | `default` | 固定，跳过第二步 |
+| `modified_time`（宽松格式） | `default` | 固定，跳过第二步 |
+| `created_user` | `default` | 固定，跳过第二步 |
+| `modified_user` | `default` | 固定，跳过第二步 |
+| `email` | `default` | 固定，跳过第二步 |
+| `single_select` | `compact` | 可调 |
+| `select` | `default` | 可调 |
+| `user` | `default` | 可调 |
+| `attachment` | `default` | 可调 |
+| `image` | `default` | 可调 |
+| `reference` | `default` | 可调 |
+| `two_way_link_records` | `default` | 可调 |
+| `wwgroup` | `default` | 可调 |
+| `formula` | `default` | 可调 |
+| `lookup` | `default` | 可调 |
+| `url` | `wide` | 可调 |
+| `location` | `wide` | 可调 |
+| `text` | `wide` | 可调 |
+
+**第二步：对"可调"类型，按字段名语义决定是否上调**
+
+- 字段名含"描述/备注/说明/详情/内容/原因/摘要/简介/评论/补充" → 上调至 `extra_wide`
+- 字段名含"标题/名称/任务/需求/项目" → 取初始档位与 `wide` 中较大的档位
+- 字段名无明显语义指示 → 保持初始档位
+
+**第三步：列名宽度兜底检查（所有字段，含固定档位）**
+
+估算字段名的渲染宽度：汉字按 24px/字，非汉字按 14px/字符。若估算值超过当前档位宽度，则向上取能容纳的最小档位；最高升至 `extra_wide`（400px）。
+
+> **示例**：字段名"创建时间"（4 汉字）→ 4×24 = 96px，`compact`（120px）够用 → 保持。  
+> 字段名"是否已完成确认"（8 汉字）→ 8×24 = 192px，`compact` 不够 → 升到 `wide`（280px）。  
+> 字段名"status"（6 非汉字）→ 6×14 = 84px，`compact`（120px）够用 → 保持。
+
+---
+
+## ViewProperty（视图属性）
+
+| 参数 | 类型 | 必须 | 说明 |
+| --- | --- | --- | --- |
+| `auto_sort` | bool | 否 | 记录变更后自动重新排序 |
+| `sort_spec` | SortSpec | 否 | 排序设置 |
+| `group_spec` | GroupSpec | 否 | 分组设置 |
+| `filter_spec` | FilterSpec | 否 | 过滤筛选设置，无筛选条件时，必须**完全省略** `filter_spec` 字段；禁止传 `"filter_spec": {}` 或空的 `conditions`。空对象会被后端当作不完整的 FilterSpec 解析，触发“无效的连接符”错误。只有确实需要筛选时，才传完整的 `filter_spec`，且必须包含合法的 `conjunction` 和非空 `conditions`。 |
+| `is_field_stat_enabled` | bool | 否 | 是否使用数据统计 |
+| `field_visibility` | object | 否 | key 为字段名称（`field_title`），value 为布尔值表示是否显示 |
+| `frozen_field_count` | int32 | 否 | 冻结列数量，从首列开始 |
+| `color_config` | ViewColorConfig | 否 | 填色设置 |
+
+### SortSpec（排序设置）
+
+| 参数 | 类型 | 必须 | 说明 |
+| --- | --- | --- | --- |
+| `sort_infos` | SortInfo[] | 否 | 参与排序的字段列表 |
+
+### SortInfo
+
+| 参数 | 类型 | 必须 | 说明 |
+| --- | --- | --- | --- |
+| `field_title` | string | 是 | 字段名称 |
+| `desc` | bool | 否 | 是否降序 |
+
+### GroupSpec（分组设置）
+
+| 参数 | 类型 | 必须 | 说明 |
+| --- | --- | --- | --- |
+| `groups` | GroupInfo[] | 否 | 参与分组的字段列表 |
+
+### GroupInfo
+
+| 参数 | 类型 | 必须 | 说明 |
+| --- | --- | --- | --- |
+| `field_title` | string | 是 | 字段名称 |
+| `desc` | bool | 否 | 是否降序 |
+
+---
+
+## FilterSpec（过滤设置）
+
+| 参数 | 类型 | 必须 | 说明 |
+| --- | --- | --- | --- |
+| `conjunction` | string | 是 | 多个 conditions 之间的组合方式：`and` (条件与) 或 `or` (条件或) |
+| `conditions` | Condition[] | 是 | 判断条件 |
+
+### Condition（判断条件）
+
+> 不同字段类型支持的筛选不同，需根据字段类型实际支持的筛选条件进行组合。
+
+| 参数 | 类型 | 必须 | 说明 |
+| --- | --- | --- | --- |
+| `field_title` | string | 是 | 字段名称 |
+| `field_type` | string | 是 | 字段类型 |
+| `operator` | string (Operator) | 是 | 判断类型，见下方 Operator 枚举 |
+| `string_value` | StringValue | 否 | 文本/网址/电话/邮箱/地理位置/单选/多选等列类型使用。单选/多选支持直接传选项文本，后端会自动匹配并存储对应的选项 ID，不要求一定传 `options[].id` |
+| `number_value` | NumberValue | 否 | 数字/进度/货币/百分数等列类型使用 |
+| `bool_value` | BoolValue | 否 | 复选框列类型使用 |
+| `user_value` | UserValue | 否 | 成员/创建人/编辑人列类型使用 |
+| `date_time_value` | FilterDateTimeValue | 否 | 日期/创建时间/编辑时间列类型使用 |
+
+### StringValue
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `value` | string[] | 字符串值列表 |
+
+### NumberValue
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `value` | double | 数字值 |
+
+### BoolValue
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `value` | bool | 布尔值 |
+
+### UserValue
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `value` | string[] | 成员 userid 列表 |
+
+### FilterDateTimeValue
+
+| 字段 | 类型 | 必须 | 说明 |
+| --- | --- | --- | --- |
+| `type` | string (DateTimeType) | 是 | 日期类型，见下方 DateTimeType 枚举 |
+| `value` | string[] | 是 | 具体日期值，type 为 `detail_date` 时必填，格式为 `YYYY-MM-DD HH:mm:ss`，例如 `["2026-06-01 00:00:00"]` |
+
+---
+
+## 通用枚举值
+
+### Operator（判断类型）
+
+| 参数值 | 说明 |
+| --- | --- |
+| `is` | 等于 |
+| `is_not` | 不等于 |
+| `contains` | 包含 |
+| `does_not_contain` | 不包含 |
+| `is_greater` | 大于/时间晚于 |
+| `is_greater_or_equal` | 大于或等于/时间晚于 |
+| `is_less` | 小于/早于 |
+| `is_less_or_equal` | 小于或等于/时间早于 |
+| `is_empty` | 为空 |
+| `is_not_empty` | 不为空 |
+
+### DateTimeType（日期类型）
+
+| 参数值 | 说明 |
+| --- | --- |
+| `detail_date` | 具体时间 |
+| `today` | 今天 |
+| `tomorrow` | 明天 |
+| `yesterday` | 昨天 |
+| `current_week` | 本周 |
+| `last_week` | 上周 |
+| `current_month` | 本月 |
+| `the_past_7_days` | 过去 7 天内 |
+| `the_next_7_days` | 接下来 7 天内 |
+| `last_month` | 上月 |
+| `the_past_30_days` | 过去 30 天内 |
+| `the_next_30_days` | 接下来 30 天内 |
+
+---
+
+## 填色设置
+
+### ViewColorConfig
+
+| 参数 | 类型 | 必须 | 说明 |
+| --- | --- | --- | --- |
+| `conditions` | ViewColorCondition[] | 是 | 填色条件列表 |
+
+### ViewColorCondition
+
+| 参数 | 类型 | 必须 | 说明 |
+| --- | --- | --- | --- |
+| `id` | string | 否 | 填色 ID，新增时不需要传入，更新时传入 |
+| `type` | string (ViewColorConditionType) | 是 | 填色类型，见下方枚举 |
+| `color` | string (ViewColor) | 是 | 颜色，见下方 ViewColor 枚举 |
+| `condition` | Condition | 是 | 判断条件 |
+
+### ViewColorConditionType
+
+| 参数值 | 说明 |
+| --- | --- |
+| `row` | 行 |
+| `column` | 列 |
+| `cell` | 单元格 |
+
+### ViewColor（颜色值）
+
+| 颜色值 | 描述 |
+| --- | --- |
+| `fillColorGray_5` | 灰色\_5 |
+| `accentBlueLighten_5` | 蓝色\_5 |
+| `chromeCyanLighten_5` | 青色\_5 |
+| `chromeMintLighten_5` | 薄荷色\_5 |
+| `chromeRedLighten_5` | 红色\_5 |
+| `chromeOrangeLighten_5` | 橙色\_5 |
+| `chromeAmberLighten_5` | 琥珀色\_5 |
+| `chromeVioletLighten_5` | 紫色\_5 |
+| `chromePinkLighten_5` | 粉色\_5 |
+| `fillColorGray_4` | 灰色\_4 |
+| `accentBlueLighten_4` | 蓝色\_4 |
+| `chromeCyanLighten_4` | 青色\_4 |
+| `chromeMintLighten_4` | 薄荷色\_4 |
+| `chromeRedLighten_4` | 红色\_4 |
+| `chromeOrangeLighten_4` | 橙色\_4 |
+| `chromeAmberLighten_4` | 琥珀色\_4 |
+| `chromeVioletLighten_4` | 紫色\_4 |
+| `chromePinkLighten_4` | 粉色\_4 |
+| `fillColorGray_3` | 灰色\_3 |
+| `accentBlueLighten_3` | 蓝色\_3 |
+| `chromeCyanLighten_3` | 青色\_3 |
+| `chromeMintLighten_3` | 薄荷色\_3 |
+| `chromeRedLighten_3` | 红色\_3 |
+| `chromeOrangeLighten_3` | 橙色\_3 |
+| `chromeAmberLighten_3` | 琥珀色\_3 |
+| `chromeVioletLighten_3` | 紫色\_3 |
+| `chromePinkLighten_3` | 粉色\_3 |
+
+---
+
+## 其他通用结构
+
+### Sort（排序参数）
+
+| 参数 | 类型 | 必须 | 说明 |
+| --- | --- | --- | --- |
+| `field_title` | string | 是 | 需要排序的字段名称 |
+| `desc` | bool | 否 | 是否降序排序，默认 false |

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

@@ -0,0 +1,176 @@
+# 智能表格 Webhook 真实场景示例
+
+仅在需要构造 Webhook payload 时按需阅读。示例中的字段 ID 都是占位符，实际请求必须使用用户提供的 schema 中的字段 ID。
+
+## 场景一：记录 Bug（文本、单选、成员、图片）
+
+```json
+{
+  "add_records": [
+    {
+      "values": {
+        "fABCD1": "登录页在 Safari 浏览器下加载后白屏，其他浏览器正常。",
+        "fABCD2": [{"text": "前端"}],
+        "fABCD3": [{"text": "严重"}],
+        "fABCD4": [{"user_id": "wangwu"}],
+        "fABCD5": [{"title": "safari-bug-screenshot.png", "image_base64": "iVBORw0KGgo..."}]
+      }
+    }
+  ]
+}
+```
+
+图片只传纯 base64，不带 `data:image/...;base64,` 前缀。
+
+## 场景二：记录任务（文本、日期、成员、单选、空图片）
+
+```json
+{
+  "add_records": [
+    {
+      "values": {
+        "fTITLE": "完成支付模块单元测试，覆盖率达到 80%",
+        "fDUEDATE": "1742400000000",
+        "fOWNER": [{"user_id": "lisi"}],
+        "fSTATUS": [{"text": "未开始"}],
+        "fIMAGE": []
+      }
+    }
+  ]
+}
+```
+
+成员字段：
+
+- 有 userid 时使用 `[{"user_id":"账号名"}]`。
+- 只有姓名时可使用 `["张三"]`，但无法匹配时不会写入；可先通过 `wecomcli-contact` 查询 userid。
+- 暂不指定时使用 `[]`。
+
+图片字段暂无图片时使用 `[]`。文件附件字段不受 Webhook 支持，应跳过而不是用空数组尝试写入。
+
+## 场景三：批量新增多条记录
+
+```json
+{
+  "add_records": [
+    {
+      "values": {
+        "fCUST_NAME": "张伟",
+        "fCOMPANY": "北京某科技有限公司",
+        "fSTAGE": [{"text": "跟进中"}],
+        "fSOURCE": [{"text": "展会"}]
+      }
+    },
+    {
+      "values": {
+        "fCUST_NAME": "陈静",
+        "fCOMPANY": "上海某贸易有限公司",
+        "fSTAGE": [{"text": "初步接触"}],
+        "fSOURCE": [{"text": "冷呼"}]
+      }
+    },
+    {
+      "values": {
+        "fCUST_NAME": "刘洋",
+        "fCOMPANY": "广州某制造有限公司",
+        "fSTAGE": [{"text": "已成交"}],
+        "fSOURCE": [{"text": "老客户转介绍"}]
+      }
+    }
+  ]
+}
+```
+
+超过 100 条时先按 `SKILL.md` 取得用户确认；每批不超过 500 条，并遵守频率限制。
+
+## 场景四：更新一条 Webhook 记录
+
+```json
+{
+  "update_records": [
+    {
+      "record_id": "REC_20250301",
+      "values": {
+        "fSTATUS": [{"text": "已完成"}],
+        "fPROGRESS": 100
+      }
+    }
+  ]
+}
+```
+
+只能更新此前通过 Webhook 写入的记录。人工创建或通过普通接口创建的记录无法使用此方式更新。
+
+## 场景五：批量更新 Webhook 记录
+
+```json
+{
+  "update_records": [
+    {"record_id": "REC_001", "values": {"fSTATUS": [{"text": "已通过"}], "fAPPROVER": [{"user_id": "manager_a"}]}},
+    {"record_id": "REC_002", "values": {"fSTATUS": [{"text": "已通过"}], "fAPPROVER": [{"user_id": "manager_a"}]}},
+    {"record_id": "REC_003", "values": {"fSTATUS": [{"text": "已通过"}], "fAPPROVER": [{"user_id": "manager_a"}]}}
+  ]
+}
+```
+
+## 场景六：销售订单（多种字段类型）
+
+```json
+{
+  "add_records": [
+    {
+      "values": {
+        "fCUSTOMER": "北京某科技有限公司",
+        "fPRODUCT": [{"text": "企业版"}],
+        "fAMOUNT": 58000,
+        "fSIGN_DATE": "1741622400000",
+        "fSALES": [{"user_id": "zhaoliu"}],
+        "fCONTRACT": [{"text": "合同文件", "link": "https://doc.example.com/contract/2025-001"}]
+      }
+    }
+  ]
+}
+```
+
+## 场景七：会议纪要（文本、日期、链接）
+
+```json
+{
+  "add_records": [
+    {
+      "values": {
+        "fMEETING_TITLE": "支付模块需求评审会",
+        "fDATE": "1741622400000",
+        "fPARTICIPANTS": "产品、开发、测试",
+        "fSUMMARY": "确定优先开发支付模块，目标 3 月底完成联调，4 月初上线。",
+        "fDOC_LINK": [{"text": "评审文档", "link": "https://doc.example.com/meeting/20250310"}]
+      }
+    }
+  ]
+}
+```
+
+## 场景八：同一请求新增并更新
+
+```json
+{
+  "add_records": [
+    {
+      "values": {
+        "fTITLE": "用户反馈收集与分析",
+        "fSTATUS": [{"text": "未开始"}],
+        "fPRIORITY": [{"text": "高"}]
+      }
+    }
+  ],
+  "update_records": [
+    {
+      "record_id": "REC_OLD_001",
+      "values": {
+        "fSTATUS": [{"text": "已完成"}],
+        "fPROGRESS": 100
+      }
+    }
+  ]
+}
+```

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

@@ -0,0 +1,169 @@
+# 智能表格 Webhook 兜底写入
+
+本文档是 `wecom-cli smartsheet records add` / `wecom-cli smartsheet records update` 的 fallback 参考。当 CLI 因企业规模限制无法写入智能表格时，通过企业微信智能表格 Webhook 直接写入数据。
+
+> **格式隔离**：本文的字段值格式只适用于 Webhook，与 CLI `records add` / `records update` 使用的 `references/smart-sheet-record-values.md` 格式不同。文本、链接、图片、日期等写法均可能不同，禁止混用。
+
+## 一、Fallback 触发流程
+
+### 何时切换到 Webhook
+
+先走 CLI 正常链路。仅在以下情况切换：
+
+- 优先判据：CLI 返回 `errcode: 851003`，或 `errmsg` 包含 `no authority`。这通常意味着企业可见范围超过 10 人，CLI 写入接口被限制。
+- 或错误信息明确指向企业规模、可见范围或成员数超限。
+- 参数错误、字段错误、文档不存在等其他错误不切换 Webhook，应按原错误排查。
+- 仅 `records add` 与 `records update` 支持此兜底；删除记录或修改表结构不走 Webhook。
+
+### 向用户临时索取两项信息
+
+触发切换后，每次对话内临时获取，用完即弃，不写入文件、配置、日志说明或其他持久化位置：
+
+1. **Webhook 完整 URL**
+   - 在智能表格右上角菜单选择「接收外部数据」→ 选择目标工作表 → 开启 → 复制。
+   - 格式形如 `https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/webhook?key=XXXXXX`。
+   - URL 相当于目标表的写入密钥；用户可关闭「接收外部数据」使其失效，不得在回复中回显完整 URL 或 key。
+2. **schema 示例 JSON**
+   - 从同一「接收外部数据」页面复制。
+   - 内容包含字段 ID 到字段名的映射（`schema`），以及各字段的 Webhook 写入格式示例（`add_records`）。
+
+示例：
+
+```json
+{
+  "schema": {
+    "fABCD1": "任务名称",
+    "fABCD2": "状态",
+    "fABCD3": "负责人",
+    "fABCD4": "截止日期"
+  },
+  "add_records": [
+    {
+      "values": {
+        "fABCD1": "示例任务",
+        "fABCD2": [{"text": "未开始"}],
+        "fABCD3": [{"user_id": ""}],
+        "fABCD4": "1742400000000"
+      }
+    }
+  ]
+}
+```
+
+可使用以下话术：
+
+> CLI 写入接口返回了 `851003 no authority`，通常是企业可见范围超过 10 人导致的限制。请把目标表的 Webhook 地址和「接收外部数据」页面的示例 JSON 发我，我会通过 Webhook 写入；这些信息仅在本轮使用，不会保存到本地。
+
+## 二、构建并发送请求
+
+### 字段匹配
+
+从用户提供的 `schema` 将自然语言字段名映射到字段 ID：
+
+- 可基于近义词匹配，例如「标题」对应标题、名称或主题，「状态」对应状态或阶段，「处理人」对应负责人或责任人。
+- 匹配不唯一时先向用户确认，禁止猜测字段。
+- `values` 的 key 必须使用 schema 中真实存在的字段 ID。
+
+需要更多 payload 示例时，按需阅读 `smart-sheet-webhook-examples.md`。
+
+### 日期处理
+
+用户输入「今天」「明天」「3 月 15 日」或 `2025-03-01 09:00` 等自然语言日期时，根据当前日期及时区换算为毫秒时间戳字符串，例如 `"1742400000000"`。Webhook 不接受 CLI 使用的可读日期字符串。
+
+### 请求结构
+
+Webhook 是标准 HTTP 接口，不经过 `wecom-cli`。使用当前环境可用的 HTTP 客户端发送请求：
+
+| 项 | 值 |
+| --- | --- |
+| Method | `POST` |
+| URL | 用户提供的 Webhook 完整 URL（含 `?key=XXX`） |
+| Header | `Content-Type: application/json` |
+| Body | 包含 `add_records` 和/或 `update_records` 的 JSON 对象 |
+
+不要把包含 Webhook URL 的命令写入脚本或仓库文件，也不要把完整 URL 输出给用户。
+
+仅新增：
+
+```json
+{
+  "add_records": [
+    {"values": {"fABCD1": "...", "fABCD2": [{"text": "..."}]}}
+  ]
+}
+```
+
+仅更新：
+
+```json
+{
+  "update_records": [
+    {"record_id": "REC_xxx", "values": {"fABCD2": [{"text": "已完成"}]}}
+  ]
+}
+```
+
+Webhook 只能更新此前通过 Webhook 写入的记录，人工创建或通过普通接口创建的记录无法更新。
+
+同一请求同时新增和更新：
+
+```json
+{
+  "add_records": [{"values": {"fABCD1": "..."}}],
+  "update_records": [{"record_id": "REC_xxx", "values": {"fABCD2": [{"text": "已完成"}]}}]
+}
+```
+
+### 结果处理
+
+- Webhook 返回成功后，按 `references/smart-sheet-read.md` 读取目标数据，确认真实状态与预期一致。
+- 向用户简洁说明已通过 Webhook 写入；遵守 `SKILL.md` 的交互规范，不在回复中暴露内部 ID。
+- 返回非 0 `errcode` 时按下方错误码处理，不盲目重试。
+
+## 三、Webhook 字段值格式
+
+| 字段类型 | value 示例 | 说明 |
+| --- | --- | --- |
+| 文本 | `"产品登录页白屏"` 或 `[{"type":"text","text":"产品登录页白屏"}]` | 简单字符串更简洁 |
+| 数字 / 货币 | `58000` | 使用数字，不加引号 |
+| 进度 / 百分数 | `30` | `30` 表示 30%；不要传 `0.3` |
+| 复选框 | `true` / `false` | JSON 布尔值 |
+| 日期 | `"1740806400000"` | 毫秒时间戳字符串 |
+| 成员 | `[{"user_id":"lisi"}]`、`["张三"]` 或 `[]` | 优先使用 userid；不指定时传空数组 |
+| 单选 | `[{"text":"已完成"}]` | 选项文本必须与表格预设完全一致 |
+| 多选 | `[{"text":"前端"},{"text":"后端"}]` | 每个选项一个对象 |
+| 链接 | `[{"text":"需求文档","link":"https://doc.example.com"}]` | 数组格式 |
+| 地理位置 | `[{"latitude":"31.23040","longitude":"121.47370","source_type":1,"title":"上海市徐汇区"}]` | 最多一条 |
+| 图片 | `[{"title":"screenshot.png","image_base64":"iVBORw0KGgo..."}]` | 只传纯 base64，不带 `data:image/...;base64,` 前缀 |
+| 电话 / 邮箱 / 条码 | `"13800138000"` | 字符串 |
+
+## 四、不支持的字段
+
+以下字段由系统维护或结构特殊，Webhook 写入时跳过，不要因为这些字段中止整次写入：
+
+公式、自动编号、查找引用、关联字段、创建人、最后编辑人、创建时间、最后编辑时间、群聊、文件附件。
+
+## 五、频率与批量限制
+
+- 单工作表不超过 3000 条/分钟。
+- 单文档不超过 10000 条/分钟。
+- 数据量大时分批发送，每批不超过 500 条。
+- 同时遵守 `SKILL.md` 中超过 100 条写入前必须获得用户确认的规则。
+
+## 六、常见错误码
+
+| errcode | 原因 | 处理方式 |
+| --- | --- | --- |
+| `2023033` | 图片 base64 带有 `data:image/...;base64,` 前缀 | 去掉前缀，只传纯 base64 |
+| `40014` | Webhook key 无效或已过期 | 请用户重新从「接收外部数据」获取 Webhook 地址 |
+| `45033` | 超出频率限制 | 降低速率或缩小批次 |
+| `-100035` | testapi 域名不稳定或超时 | 改用正式域名 `qyapi.weixin.qq.com` |
+| `2023001` | 字段 ID 不存在 | 对照用户提供的 schema 检查字段 ID |
+| `2023010` | 单选或多选的值不在预设列表 | 确认选项文本完全一致，包括大小写 |
+| `2023012` | 更新时 record_id 不存在或不可更新 | 只更新此前通过 Webhook 写入的记录 |
+
+## 七、参考文件
+
+- 真实场景示例：`smart-sheet-webhook-examples.md`
+
+仅在需要示例时阅读，避免每次加载无关内容。