@rezti/dsh-rez-suite 0.1.50 → 0.1.52

package/templates/shared/wecomcli-meeting/references/meeting-update.md

@@ -0,0 +1,217 @@
+# 操作参考：更新会议
+
+更新已创建会议的信息，包括主题、时间、参会人、地点等。**写操作**，参数就绪后直接执行。不预先按"是否本人创建"拦截，能否修改由接口返回结果判断。**暂不支持更新周期会议**，识别到周期会议时应告知用户并引导其在企业微信客户端操作（见下文工作流与约束）。
+
+## 命令
+
+```bash
+wecom-cli meeting update --json '{...}'
+```
+
+## 请求参数
+
+| 字段 | 类型 | 必填 | 说明 |
+| ---- | ---- | ---- | ---- |
+| `meeting_id` | string | 是 | 会议 ID（来自 `list`/`search` 返回的 `meeting_id` 字段，长字符串，非 9 位会议号） |
+| `subject` | string | 否 | 新的会议主题 |
+| `begin_time` | string | 否 | 新的开始时间（格式 YYYY-MM-DD HH:mm:ss） |
+| `end_time` | string | 否 | 新的结束时间（格式 YYYY-MM-DD HH:mm:ss） |
+| `add_attendees` | array | 否 | 新增参会人列表，对象数组，格式 `[{"userid": "woxxx"}]` |
+| `remove_attendees` | array | 否 | 移除参会人列表，对象数组，格式 `[{"userid": "woxxx"}]` |
+| `location` | string | 否 | 新的会议地点（文本）。用户给的是**会议室**时须走 `meeting_room_id` 改订（见工作流「会议室变更解析」），不要把会议室名仅写进 `location`；用户给的是**非会议室的普通文本地点**时直接写入 `location` |
+| `meeting_room_id` | string | 否 | 会议室 ID，传入预定（改订）会议室。用户要更换会议室时，须先经 `rooms search`（会议室查询接口定义在 `读取 wecomcli-calendar 技能` 的 [会议室查询参考](../../wecomcli-calendar/references/calendar-meeting-room.md)）查询新会议室状态，确认`status=bookable` 可用后才传入新的 `meeting_room_id`；ID 仅工具链使用，禁止出现在用户回复正文 |
+| `description` | string | 否 | 新的会议备注 |
+
+## 返回字段
+
+| 字段 | 说明 |
+| ---- | ---- |
+| `meeting_id` | 会议 ID |
+| `sub_meeting_id` | 子会议 ID（周期会议时返回） |
+| `subject` | 更新后的会议主题 |
+| `begin_time` | 更新后的开始时间 |
+| `end_time` | 更新后的结束时间 |
+| `attendees` | 更新后的完整参会人列表，扁平对象数组，每项含 `userid` / `name` / `is_external`；内部成员与外部联系人统一用 `userid`，由 `is_external` 区分。展示取 `name`，禁止展示 userid |
+| `attendees_count` | `attendees` 数组元素数量 |
+| `location` | 更新后的会议地点 |
+| `description` | 更新后的会议备注 |
+
+## 约束
+
+- **不预先按"是否本人创建"拦截修改**，直接执行 `update`，能否修改由接口返回结果判断：返回更新后的字段即成功；返回权限类错误则说明当前用户无权修改，告知用户并建议联系会议发起人
+- 只需传入要修改的字段，未传入字段保持原值不变
+- **周期会议不支持更新**：检测到目标会议 `repeat_rule` 非空时，直接告知用户目前暂不支持更新周期会议，引导其在企业微信客户端操作，禁止逐场 `update` 拼凑或改为取消重建等变通方式
+- 修改时间时 `end_time` 必须晚于 `begin_time`
+- **更换会议室**：用户要换会议室时，`meeting_room_id` 必须先经 `rooms search` 查询、确认新会议室 `status=bookable` 可用后才传入；禁止跳过查询凭记忆/猜测直接传，禁止把会议室名仅写进 `location`（那样不会真正占用会议室）。会议室查询接口须 `读取 wecomcli-calendar 技能` 的 [会议室查询参考](../../wecomcli-calendar/references/calendar-meeting-room.md)
+- userid（前缀为 `wo`）不接受姓名直接传入；用户提供的是姓名时通过 `读取 wecomcli-contact 技能` 解析为 userid，禁止把姓名当 userid 拼接，禁止凭记忆或猜测编造
+
+## 工作流
+
+```
+用户发起更新意图
+    |
+    +-- 定位目标会议
+    |   +-- 有关键词 → meeting search（不追问时间）
+    |   +-- 有时间信息 → meeting list 按时间范围查询
+    |   +-- 都没有 → 用文字询问引导用户补全信息
+    |
+    +-- 匹配结果处理
+    |   +-- 唯一匹配 → 继续
+    |   +-- 多条匹配 → 用文字让用户选择：
+    |   |     文字提问："找到多个匹配会议，请选择要修改的一个："
+    |   |     列出候选（如"项目评审 - 4月8日 14:00 / 项目评审 - 4月15日 14:00"，最多 4 条）
+    |   +-- 无匹配 → 建议修改关键词或扩大时间范围重试
+    |
+    +-- 判断是否周期会议（依据 meeting get 返回的 repeat_rule）
+    |   +-- repeat_rule 为空 → 非周期会议，直接收集修改内容，执行更新
+    |   +-- repeat_rule 非空 → 周期会议，终止操作，用文字告知用户："目前暂不支持更新周期会议，请在企业微信客户端对该会议进行修改"，禁止逐场 update 拼凑或改为取消重建
+    |
+    +-- 参会人变更解析（如有）
+|   +-- 上下文中已有合法 userid（`wo` 前缀）→ 直接使用，跳过搜索
+|   +-- 用户提供的是姓名 → 通过 `读取 wecomcli-contact 技能` 批量搜索所有新增/移除的人名
+    |   |   +-- 某关键词唯一匹配 → 直接使用，无需确认
+    |   |   +-- 某关键词多个匹配 → 用文字让用户选择（列出姓名 + 部门）：
+    |   |   |     文字提问："搜索到多个「{姓名}」，请确认要操作哪一位？"
+    |   |   |     列出候选（如"张三 - 产品部 - 产品经理 / 张三 - 技术部 - 前端工程师"，最多 4 条；超出取前 4 条并提示用户可进一步缩小范围）
+    |   |   +-- 某关键词无结果 → 用文字提示用户确认人名是否正确，停止执行
+    |   +-- 汇总全部 userid → 组装 add_attendees / remove_attendees（对象数组 [{"userid": "woxxx"}]）
+    |
+    |   > **关键约束**：只要存在多个候选人，必须等用户选择后才能继续，不得自动选取任何一个。
+    |
+    +-- 会议室变更解析（如用户要换会议室）
+    |   +-- 确定查询时段：用会议起止时间；若本次同时改时间，用改后的新时段
+    |   +-- 读取 wecomcli-calendar 技能的 [会议室查询参考](../../wecomcli-calendar/references/calendar-meeting-room.md) → rooms search 查新会议室状态
+    |   |   +-- target 中有 bookable 项 → 取该项 target[].room.meeting_room_id（多个 bookable 时用文字让用户选）
+    |   |   +-- 指定会议室 target=[]（查无此名）/ 命中项均 unavailable（被占）→ 必须先告知用户"未查到/无法预订你指定的『xxx』会议室"，
+    |   |   |       再用文字让用户决定是否改订其他会议室或换时间；禁止用其他名称会议室静默替代（候选仅 1 个也须用户确认）
+    |   |   +-- 未指定具体会议室（target=[]）：
+    |   |   |   +-- recommendations 多个 → 用文字让用户选（禁止自动取第一个）
+    |   |   |   +-- recommendations 仅 1 个 → 可直接使用
+    |   |   |   +-- recommendations = [] → 告知无可用会议室，引导换楼或换时间
+    |   +-- 拿到用户确认的、可用的 meeting_room_id → 传入 update
+    |   > **关键约束**：新会议室未经 rooms search 确认 bookable 之前，禁止传 meeting_room_id 调 update。
+    |
+    +-- 时间/参会人忙闲检查（改时间或加参会人时必做）[REQUIRED]
+    |   +-- 触发条件：本次修改了 begin_time/end_time，或新增了参会人（add_attendees）
+    |   +-- 查询对象与时段：核心原则是排除"因本会议占用而必然忙碌"的时段，避免自冲突误报 [CRITICAL]
+    |   |     ——【已在本会议中的人】（自己/创建者 + 已有参会人）只查"与本会议当前时段【不重叠】"的时间，【新增参会人】才查完整目标时段。分三种情况：
+    |   |   +-- ① 只加人、不改时间 → 仅对【新增参会人 add_attendees 中的内部成员】查【会议原时段】；
+    |   |   |     绝不把当前用户（自己/创建者）及已有参会人纳入——他们正被本会议占用、必然显示"忙"，是误报
+    |   |   |     （用户本意就是让别人加入自己这个已定时间的会议）
+    |   |   +-- ② 改时间且新旧时段【不重叠】（平移/改期，如 15:00→17:00）→ 对【改后仍需参加的内部成员（含自己）+ 新增内部参会人】查【完整新时段】
+    |   |   |     （新旧无交集，现有参会人查新时段不会撞上本会议原时段，可正常纳入自己/已有参会人）
+    |   |   +-- ③ 改时间且新旧时段【有重叠】（延长/提前等，新时段含部分原时段）→ 分两类查：
+    |   |   |     · 新增内部参会人：查【完整新时段】
+    |   |   |     · 现有内部参会人及自己：只查【新时段去掉与原时段重叠后剩下的增量段】
+    |   |   |       （如 15:00-16:00 延到 15:00-17:00 只查 16:00-17:00；15:00-16:00 提前到 14:00-16:00 只查 14:00-15:00）；
+    |   |   |       增量段为空（如仅缩短时间）则现有参会人及自己无需查
+    |   +-- 按上面裁剪后的查询对象执行；裁剪后查询对象为空、或仅剩外部联系人（wm，忙闲不可查）时才跳过——不要因为"只有自己"就跳过（②/③ 里自己在新时段/增量段内仍要查，避免约到自己已占用的时段）
+    |   +-- 忙闲接口不在本技能 → 读取 wecomcli-calendar 技能的 [忙闲查询参考](../../wecomcli-calendar/references/calendar-freebusy.md)，按上面圈定的查询对象 + 时段调 free list（窗口 ≤ 24h）
+    |   |   +-- 无冲突 → 继续执行 update
+    |   |   +-- 有人占线 → 用文字让用户二选一（禁止自行改期）：
+    |   |   |     文字提问："该时间段{姓名}有冲突，如何处理？（请回复：坚持这个时间 / 换一个时间）"
+    |   |   +-- 接口失败 → 告知忙闲暂不可用，确认时间后继续，不阻塞
+    |
+    +-- 执行 update（不论会议由谁创建，都直接执行，不提前拒绝）→ 依返回结果判断：
+          +-- 返回更新后的字段 → 修改成功，展示更新后的会议摘要
+          +-- 返回权限类错误 → 说明当前用户无权修改该会议，告知用户并建议联系会议发起人
+```
+
+### 异常路径
+
+| 异常情况 | 处理方式 |
+|---------|---------|
+| 接口返回无权修改（非发起人） | 直接执行 update 后依返回判断；返回权限错误时告知用户无权操作，建议联系会议发起人 |
+| 周期会议更新 | 目前暂不支持更新周期会议，告知用户并引导其在企业微信客户端对该会议进行修改 |
+| 修改时间冲突（end ≤ begin） | 提示用户结束时间必须晚于开始时间，请重新输入 |
+| wecomcli-contact 技能搜索无结果 | 提示用户确认人名是否正确，或尝试其他搜索词 |
+| wecomcli-contact 技能返回多个候选人 | 用文字询问用户（列出候选姓名 + 部门），等待用户选择后汇总继续 |
+| 换会议室时新会议室不可用 | `rooms search` 返回 `unavailable`/`not_found`：用文字让用户从 `recommendations` 候选中选，或引导换楼（`expand_to_other_buildings`）/换时间；禁止传不可用的 `meeting_room_id` 调 update |
+| 更新接口返回错误 | 检查参数格式，重新阅读本文档确认用法 |
+
+## 示例请求
+
+**修改普通会议时间和主题**：
+```json
+{
+  "meeting_id": "<meeting_id>",
+  "subject": "产品需求评审（更新）",
+  "begin_time": "2026-04-08 15:00:00",
+  "end_time": "2026-04-08 16:00:00"
+}
+```
+
+**新增/移除参会人**：
+```json
+{
+  "meeting_id": "<meeting_id>",
+  "add_attendees": [{"userid": "woxxxc"}],
+  "remove_attendees": [{"userid": "woxxxb"}]
+}
+```
+
+**更换会议室**（`meeting_room_id` 须先经 `rooms search` 确认新会议室 `status=bookable`）：
+```json
+{
+  "meeting_id": "<meeting_id>",
+  "meeting_room_id": "mrmxxxx"
+}
+```
+
+## 典型场景
+
+### 1. 修改会议时间
+
+```
+用户：把明天下午3点的评审会推迟1小时
+→ 调用 meeting search（keywords=["评审"]）→ 获取 meeting_id
+→ 调用 meeting get → 判断非周期会议（不做是否本人创建的前置拦截）
+→ 组装参数：begin_time="2026-04-08 16:00:00"，end_time="2026-04-08 17:00:00"
+→ 调用 update → 展示更新结果
+```
+
+### 2. 添加参会人
+
+```
+用户：把王五加到明天的评审会
+→ 调用 meeting search → 获取 meeting_id
+→ 通过 wecomcli-contact 技能搜索「王五」→ 返回 2 个候选
+→ 用文字询问：搜索到多个「王五」，请确认要邀请哪一位？（列出：王五 - 市场部 - 市场专员 / 王五 - 技术部 - 前端工程师）
+→ 用户选择后，获得对应 userid
+→ 调用 update，add_attendees=[{"userid": "woxxxe"}]
+→ 展示更新后完整参会人列表
+```
+
+### 3. 修改周期会议（不支持）
+
+```
+用户：下周一的周会改到下午3点，只改这一次
+→ 调用 meeting search（keywords=["周会"]）→ 找到周期会议
+→ 调用 meeting get → repeat_rule 非空（周期会议）
+→ 不调用 update → 告知：目前暂不支持更新周期会议，请在企业微信客户端对该会议进行修改
+```
+
+### 4. 更换会议室
+
+```
+用户：把明天评审会的会议室换到 1608
+→ meeting search/list 拿 meeting_id（及会议起止时间）→ get 拿会议详情（不做是否本人创建的前置拦截）
+→ 读取 wecomcli-calendar 技能的会议室查询参考，用会议时段 + room_keyword="1608" 调 rooms search
+→ target 中有 bookable 项 → 取其 target[].room.meeting_room_id
+→ 调用 update，meeting_room_id="mrmxxxx"
+→ 展示更新后会议摘要（只露会议室 name）
+
+用户：明天的评审会换个会议室
+→ 拿 meeting_id 与时段 → rooms search（未指定具体会议室，target=[]）
+→ recommendations 多个 → 用文字让用户选（展示 name + 楼层 + 容量）
+→ 用户选定后取其 meeting_room_id → update
+```
+
+## 参考
+
+- [wecomcli-meeting](../SKILL.md) — 会议技能主文档
+- [meeting-search](meeting-search.md) — 搜索会议（获取 meeting_id）
+- [meeting-list](meeting-list.md) — 查看会议列表
+- [meeting-cancel](meeting-cancel.md) — 取消会议
+- `读取 wecomcli-calendar 技能` 的 [忙闲查询参考](../../wecomcli-calendar/references/calendar-freebusy.md) — 改时间/加参会人时查共同空闲
+- `读取 wecomcli-calendar 技能` 的 [会议室查询参考](../../wecomcli-calendar/references/calendar-meeting-room.md) — 更换会议室时确认新会议室 `status=bookable`

package/templates/shared/wecomcli-sheet/references/sheet-contents-update.md

@@ -0,0 +1,47 @@
+# 修改表格内容 — `wecom-cli sheet contents update`
+
+修改**在线表格**指定区域的内容与格式，通过 `grid_data` 指定写入的起始位置与各单元格数据。
+
+## 命令
+
+```bash
+wecom-cli sheet contents update --json '<JSON 参数>'
+```
+
+## 参数
+
+| 字段 | 类型 | 必填 | 默认值 | 语义 |
+|---|---|---|---|---|
+| `docid` | string | 是 | — | 在线表格 ID |
+| `sheet_id` | string | 是 | — | 工作表 ID；通过 `sheet get` 获取 |
+| `grid_data` | object | 是 | — | 写入区域的数据 |
+| `grid_data.start_row` | int | 是 | — | 起始行号，从 0 起 |
+| `grid_data.start_column` | int | 是 | — | 起始列号，从 0 起 |
+| `grid_data.rows` | array | 是 | — | 各行数据 |
+
+`grid_data.rows[].values[]` 对象结构：
+
+| 子字段 | 类型 | 说明 |
+|---|---|---|
+| `cell_value` | object | 单元格值，见下方「cell_value 类型选择」 |
+| `data_type` | string | 与 `cell_value` 对应的数据类型 |
+| `cell_format` | object | 单元格样式；传空对象 `{}` 表示默认样式 |
+
+### cell_value 类型选择
+
+| 形态 | 结构 | 适用场景 |
+|---|---|---|
+| `text` | `{"text": "<纯文本>"}` | 纯文本内容（如姓名、说明、标签、编号字符串等） |
+| `number` | `{"number": 123.45}` | 数值，用于金额、数量、比率等需要参与公式计算或聚合的数据；值为 JSON 数字类型，不加引号 |
+| `formula` | `{"formula": "=SUM(A1,A2)"}` | 任何以 `=` 开头的公式，包括 `=SUM(...)`、`=A1+B1`、`=IF(...)`、`=VLOOKUP(...)` 等 |
+| `link` | `{"link": {"url": "<URL>", "text": "<显示文本>"}}` | 超链接 |
+
+## 返回
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `grid_data` | object | 写入的数据，结构与入参 `grid_data` 一致 |
+
+## 使用规则
+
+- **格式与已有内容对齐**：向已有内容的表格追加数据时，新行的样式应尽量与现有表格保持一致，避免出现字体、字号、对齐、边框、底色等风格突兀的行。

package/templates/shared/wecomcli-sheet/references/sheet-ranges-get.md

@@ -0,0 +1,45 @@
+# 读取子表数据 — `wecom-cli sheet ranges get`
+
+根据 `docid`、`sheet_id` 读取**在线表格**指定子表的全部数据。可通过 `mode` 参数选择返回结构化的表格数据（含格式信息），或返回 CSV（内容或文件路径）。
+
+## 命令
+
+```bash
+wecom-cli sheet ranges get --json '<JSON 参数>'
+```
+
+## 参数
+
+| 字段 | 类型 | 必填 | 默认值 | 语义 |
+|---|---|---|---|---|
+| `docid` | string | 是 | — | 在线表格 ID |
+| `sheet_id` | string | 是 | — | 工作表 ID；通过 `sheet get` 获取 |
+| `mode` | string | 否 | `"default"` | 返回格式选择：`"default"` 返回结构化 `grid_data`（含单元格格式）；填 `"csv"` 返回 CSV（内容或文件路径） |
+| `range` | string | 条件必填 | — | 当 `mode="default"` 时**必填**，表示要读取的区域，形如 `"A1:A100"`；取值可从 `sheet get` 返回的 `sheets[].data_range` 拿到。`mode="csv"` 时忽略此字段 |
+
+### `mode` 如何选择
+
+默认一律使用 `"default"`，包括普通的读取、查看、展示数据等场景。此时必须同时传 `range`，返回 `grid_data`（含单元格值、格式、数据类型等完整信息）。
+仅当用户明确表达需要对数据做统计、计算、聚合分析（例如"求和/平均/分组统计/透视/跑数据分析"等）时，才填 `"csv"`，便于直接把数据交给计算流程。
+
+## 返回
+
+### `mode` 为 `"default"`（默认）
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `grid_data` | object | 结构化表格数据，包含每个单元格的值（`cell_value`）、格式（`cell_format`，如字体、字号、颜色、对齐方式）和数据类型（`data_type`） |
+
+### `mode` 为 `"csv"`
+
+回包可能是以下两种形式之一（取决于数据大小）：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `content` | string | CSV 内容（直接返回） |
+| `file_path` | string | CSV 文件落盘后的绝对路径 |
+
+## 使用规则
+
+- `mode="csv"` 且返回 `file_path` 时：必须再用 `read` 工具读取该文件内容，才能展示给用户或继续做分析。
+- `mode="csv"` 且返回 `content` 时：可直接消费，无需再次读取文件。

package/templates/shared/wecomcli-sheet/references/sheet-rows-append.md

@@ -0,0 +1,45 @@
+# 追加一行数据 — `wecom-cli sheet rows append`
+
+向**在线表格**的指定子工作表末尾自动追加一行数据，无需指定行号——数据将写到最末一行之后。
+
+## 命令
+
+```bash
+wecom-cli sheet rows append --json '<JSON 参数>'
+```
+
+## 参数
+
+| 字段 | 类型 | 必填 | 默认值 | 语义 |
+|---|---|---|---|---|
+| `docid` | string | 是 | — | 在线表格 ID |
+| `sheet_id` | string | 是 | — | 工作表 ID；通过 `sheet get` 获取 |
+| `row` | object | 是 | — | 追加的一行数据 |
+| `row.values` | array | 是 | — | 单元格数组，按列顺序排列 |
+
+`row.values[]` 对象结构：
+
+| 子字段 | 类型 | 说明 |
+|---|---|---|
+| `cell_value` | object | 单元格值，见下方「cell_value 类型选择」|
+| `cell_format` | object | 单元格样式；传空对象 `{}` 表示默认样式 |
+
+### cell_value 类型选择
+
+| 形态 | 结构 | 适用场景 |
+|---|---|---|
+| `text` | `{"text": "<纯文本>"}` | 纯文本内容（如姓名、说明、标签、编号字符串等） |
+| `number` | `{"number": 123.45}` | 数值，用于金额、数量、比率等需要参与公式计算或聚合的数据；值为 JSON 数字类型，不加引号 |
+| `formula` | `{"formula": "=SUM(A1,A2)"}` | 任何以 `=` 开头的公式，包括 `=SUM(...)`、`=A1+B1`、`=IF(...)`、`=VLOOKUP(...)` 等 |
+| `link` | `{"link": {"url": "<URL>", "text": "<显示文本>"}}` | 超链接 |
+
+## 返回
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `row` | object | 写入的行数据，结构与入参 `row` 一致 |
+
+## 使用规则
+
+- **逐行写入场景**：本接口会自动定位到子表最末一行之后追加；批量写不同区域请用 `sheet contents update`。
+- **格式与已有内容对齐**：向已有内容的表格追加数据时，新行的样式应尽量与现有表格保持一致，避免出现字体、字号、对齐、边框、底色等风格突兀的行。

package/templates/shared/wecomcli-sheet/references/sheet-subsheets-add.md

@@ -0,0 +1,26 @@
+# 添加子工作表 — `wecom-cli sheet subsheets add`
+
+向**在线表格**添加一个新的子工作表。
+
+## 命令
+
+```bash
+wecom-cli sheet subsheets add --json '<JSON 参数>'
+```
+
+## 参数
+
+| 字段 | 类型 | 必填 | 默认值 | 语义 |
+|---|---|---|---|---|
+| `docid` | string | 是 | — | 在线表格 ID |
+| `sheet` | object | 是 | — | 子表信息 |
+| `sheet.title` | string | 是 | — | 工作表名称 |
+| `sheet.row_count` | int | 否 | — | 表格总行数 |
+| `sheet.column_count` | int | 否 | — | 表格总列数 |
+| `index` | int | 否 | — | 插入位置：`0` 表示插入到最后，`1` 表示插入到第一个位置 |
+
+## 返回
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `sheet` | object | 新增的子表信息；含 `sheet_id`（唯一标识）/ `title` / `row_count` / `column_count` / `data_range`（新建时为空） |

package/templates/shared/wecomcli-sheet/references/sheet-subsheets-delete.md

@@ -0,0 +1,20 @@
+# 删除子工作表 — `wecom-cli sheet subsheets delete`
+
+根据 `docid` 与 `sheet_id` 删除**在线表格**的指定子工作表。
+
+## 命令
+
+```bash
+wecom-cli sheet subsheets delete --json '<JSON 参数>'
+```
+
+## 参数
+
+| 字段 | 类型 | 必填 | 默认值 | 语义 |
+|---|---|---|---|---|
+| `docid` | string | 是 | — | 在线表格 ID |
+| `sheet_id` | string | 是 | — | 要删除的工作表 ID；通过 `sheet get` 获取 |
+
+## 返回
+
+删除成功返回空对象。

package/templates/shared/wecomcli-smartpage/references/data-driven-pages.md

@@ -0,0 +1,50 @@
+# 数据驱动页面搭建指引
+
+本文档汇总**依赖智能文档内置数据表**的页面搭建流程，覆盖两大场景：
+
+- **系统/图表页面**：任务系统、数据看板、项目跟踪等，页面上的图表/视图需要绑定内置表字段。
+- **表单页面**：数据录入、信息收集，提交按钮通过 `ADDRECORD` 公式把控件值写入数据表。
+
+两类场景的**共性铁律**：**必须先让内置表的子表与字段就位，再追加引用它们的页面内容**。否则图表会渲染失败、按钮会因引用不存在的字段而无法落库。
+
+---
+
+## 场景一：搭建含数据源的系统/图表页面
+
+**适用**：任务系统、数据看板、项目跟踪页等需要图表/视图绑定数据的页面。
+
+**与「从零创建智能文档」路径 A/B 的区别**：页面引用了数据，必须先让内置表的字段/视图就位，再写引用这些字段的图表组件。
+
+### 执行步骤
+
+1. **确定目标文档**：
+   - *新建文档*：走 [`SKILL.md`](../SKILL.md) 「路径 B：先创建空白再追加内容」先建空文档，记录 `docid`。智能文档已自动绑定内置数据源，**勿另建独立智能表格**。
+   - *已有文档新增图表页*：`smartpage pages update` 直接建页，无需重复创建文档。
+2. **获取内置数据源**：`smartpage databases get` 拿到 `database_info.id` 与 `database_info.tables[].id`/`.name`，后续图表按子表 ID 绑定。
+3. **配置数据表结构**：委托 `wecomcli-smartsheet` 完成子表创建、字段定义、数据初始化。
+4. **写入页面内容**：字段就位后，用 `smartpage pages append` / `overwrite`（见 [`smartpage-edit.md`](smartpage-edit.md)）写入图表组件 MDX（见 [`mdx-syntax.md`](mdx-syntax.md)）。**切勿用 `smartpage import` / `create` 写内容**，否则会新建无数据表的文档。
+
+---
+
+## 场景二：创建表单页面（数据录入 / 信息收集）
+
+**核心特征**：提交按钮通过 `ADDRECORD` 公式把控件值写入数据表，因此**必须先让目标子表与字段就位**，再追加包含控件和按钮的页面内容；否则按钮会因引用的字段不存在而无法落库。
+
+### 执行步骤
+
+1. **确定目标文档与页面**：
+   - *新建文档*：`smartpage create` 创建空白智能文档，记录 `docid` 和默认首页。
+   - *已有文档*：`smartpage pages update` 新建一个页面用于放置表单。
+2. **获取内置数据表**：`smartpage databases get` 取 `database_info.id` 与 `database_info.tables[]`，后续配置字段和按钮公式的引用依据。
+3. **委托 `wecomcli-smartsheet` 补子表与字段**：在上一步拿到的内置表上创建子表（如「报名表」）并定义字段。字段类型需与控件匹配：文本字段对应 `<input>`，单选/多选字段对应 `<select>`。
+4. **重命名表单页面**：`smartpage pages update` 将目标页面改为有意义的名称（如「报名表单页」）——该名称将用于 `ADDRECORD` 公式中引用控件值。引用格式为 `[页面名.控件名]`，**必须与页面名完全一致**，**不得使用文档名称**；跳过此步将导致按钮因公式错误无法使用。
+5. **追加表单页面内容**：`smartpage pages get` 拿到 `page_id` 后，`smartpage pages append` 将表单 MDX 追加到该页面。控件与按钮写法参考 [`mdx-syntax.md`](mdx-syntax.md) 中 `<input>` / `<select>` / `<button>` 章节，`formulaString` 中 `ADDRECORD` 的写法参考 [`formula/pageblock.md`](formula/pageblock.md)。
+
+---
+
+## 通用约束
+
+- **数据源来源唯一**：智能文档创建后自带内置数据源，通过 `smartpage databases get` 获取，不要委托 `wecomcli-smartsheet` 另建独立智能表格。
+- **字段先行、内容后置**：无论图表还是表单按钮，只要 MDX 中引用了字段，就必须在写页面内容前完成字段定义。
+- **控件与字段类型匹配**：表单场景下，`<input>` ↔ 文本字段、`<select>` ↔ 单选/多选字段；错配会导致落库失败。
+- **公式引用格式**：`ADDRECORD` 公式中的引用为 `[页面名.控件名]`，页面名必须与 `smartpage pages update` 后的实际名称完全一致。