dsh-crwu-workbench 0.0.10

package/skills/dws/dingtalk-misc/references/sheet/sheet-range-operations.md

@@ -0,0 +1,161 @@
+# 区域操作
+
+## 使用场景
+
+用户说"清空/清除区域/擦除内容/清除格式":
+- 清除区域 → `range clear`
+- 仅清除值 → `range clear --type content`（默认）
+- 仅清除格式 → `range clear --type format`
+- 全部清除 → `range clear --type all`
+- 请勿用 `range update` 写入空字符串来模拟清空，`range clear` 更简洁且支持按类型清除
+
+用户说"排序/给数据排序/按某列排序/升序/降序":
+- 区域排序 → `range sort`
+- **排序前必须先 `range read` 前 3-5 行**：读取排序范围的前几行（如范围是 A1:D100 则读 A1:D5），对比首行与后续行的模式来判断是否有表头：
+  - 首行全文本 + 后续行含数字/日期 → 有表头，加 `--has-header`
+  - 首行与后续行模式一致（都是数字或都是文本） → 无表头，不加
+  - 首行值语义像列标题（如"姓名""金额""日期"）且与后续行明显不同 → 有表头
+  禁止不读就排——表头误排入数据是不可撤销的破坏性操作
+- 请勿用 `range read` 读取数据后客户端排序再 `range update` 写回，`range sort` 是服务端原子操作
+
+用户说"自动填充/填充序列/向下填充/拖拽填充/序列递增":
+- 自动填充 → `range fill`
+- 请勿用 `range read` 读取源数据后手动计算规律再 `range update` 写入，`range fill` 支持服务端智能填充
+
+用户说"批量清除/批量操作/一次执行多个写操作/原子批量/先清除再写入":
+- 批量清除多个区域 → `range batch-clear`
+- 组合多个不同写操作 → `batch-update`
+- 详见 [sheet-batch-operations](./sheet-batch-operations.md)
+
+用户说"复制区域/把这块数据复制到/复制到另一个工作表":
+- 复制区域 → `range copy-to`
+- 跨工作表 → `range copy-to --target-sheet-id Sheet2` 或 `--target-range "Sheet2!A1"`
+- 请勿用 `range read` + `range update` 读取再写入来模拟复制，`range copy-to` 是原子操作，保留公式引用调整
+
+用户说"移动区域/把数据移到/剪切粘贴/移到另一个工作表":
+- 移动区域 → `range move-to`
+- 跨工作表 → `range move-to --target-sheet-id Sheet2` 或 `--target-range "Sheet2!A1"`
+- 请勿用 `range read` + `range update` + `range clear` 读取-写入-清空来模拟移动，`range move-to` 是原子操作
+
+## 命令详细参考
+
+### 清除区域
+```
+Usage:
+  dws sheet range clear [flags]
+Example:
+  dws sheet range clear --node <NODE_ID> --sheet-id <SHEET_ID> --range "A1:B3"
+  dws sheet range clear --node <NODE_ID> --sheet-id <SHEET_ID> --range "A1:B3" --type format
+  dws sheet range clear --node <NODE_ID> --sheet-id <SHEET_ID> --range "A1:B3" --type all
+Flags:
+      --node string            表格文档 ID 或 URL (必填)
+      --sheet-id string        工作表 ID 或名称 (必填)
+      --range string           清除范围，A1 表示法 (必填)
+      --type string            清除类型: content(仅值,默认) / format(仅格式) / all(全部)
+```
+
+### 区域排序
+```
+Usage:
+  dws sheet range sort [flags]
+Example:
+  dws sheet range sort --node <NODE_ID> --sheet-id <SHEET_ID> --range "A1:D10" \
+    --sort-keys '[{"column":"A","ascending":true}]'
+  dws sheet range sort --node <NODE_ID> --sheet-id <SHEET_ID> --range "A1:D10" \
+    --sort-keys '[{"column":"A","ascending":true},{"column":"C","ascending":false}]' --has-header
+Flags:
+      --node string            表格文档 ID 或 URL (必填)
+      --sheet-id string        工作表 ID 或名称 (必填)
+      --range string           排序范围，A1 表示法 (必填)
+      --sort-keys string       排序规则 JSON 数组 (必填)
+      --has-header             首行是否为表头（不参与排序）
+```
+
+`--sort-keys` 格式：`[{"column":"A","ascending":true}]`，`column` 使用字母列名（如 "A"、"B"、"AA"）。多级排序按数组顺序优先级递减。
+
+### 区域自动填充
+```
+Usage:
+  dws sheet range fill [flags]
+Example:
+  dws sheet range fill --node <NODE_ID> --sheet-id <SHEET_ID> \
+    --source-range "A1:A5" --target-range "A6:A20"
+  dws sheet range fill --node <NODE_ID> --sheet-id <SHEET_ID> \
+    --source-range "A1:A5" --target-range "A6:A20" --fill-type copy
+Flags:
+      --node string            表格文档 ID 或 URL (必填)
+      --sheet-id string        工作表 ID 或名称 (必填)
+      --source-range string    源数据范围，A1 表示法 (必填)
+      --target-range string      目标填充范围，A1 表示法 (必填)
+      --fill-type string       填充类型: series(序列,默认) / copy(复制) / onlystyle(仅格式) / withoutstyle(仅值)
+```
+
+目标范围须与源范围在行或列维度对齐（不支持对角填充）。
+
+### 复制区域
+```
+Usage:
+  dws sheet range copy-to [flags]
+Example:
+  dws sheet range copy-to --node <NODE_ID> --sheet-id <SHEET_ID> \
+    --source-range "A1:C5" --target-range "D1"
+  dws sheet range copy-to --node <NODE_ID> --sheet-id <SHEET_ID> \
+    --source-range "A1:C5" --target-range "A1" --target-sheet-id "Sheet2"
+  dws sheet range copy-to --node <NODE_ID> --sheet-id <SHEET_ID> \
+    --source-range "A1:C5" --target-range "D1" --paste-type values
+Flags:
+      --node string            表格文档 ID 或 URL (必填)
+      --sheet-id string        源工作表 ID 或名称 (必填)
+      --source-range string    源范围，A1 表示法 (必填)
+      --target-range string    目标位置，A1 表示法 (必填)
+      --target-sheet-id string 目标工作表 ID 或名称（可选，不传则复制到同一工作表）
+      --paste-type string      粘贴类型: values(仅值) / formulas(仅公式) / formats(仅格式) / all(全部,默认)
+```
+
+支持跨工作表复制，两种方式指定目标工作表：
+- `--target-sheet-id "Sheet2"` 显式指定
+- `--target-range "Sheet2!A1"` 在目标范围中携带工作表前缀
+
+源和目标范围不能重叠（同表时）。
+
+### 移动区域
+```
+Usage:
+  dws sheet range move-to [flags]
+Example:
+  dws sheet range move-to --node <NODE_ID> --sheet-id <SHEET_ID> \
+    --source-range "A1:C5" --target-range "D1"
+  dws sheet range move-to --node <NODE_ID> --sheet-id <SHEET_ID> \
+    --source-range "A1:C5" --target-range "A1" --target-sheet-id "Sheet2"
+Flags:
+      --node string            表格文档 ID 或 URL (必填)
+      --sheet-id string        源工作表 ID 或名称 (必填)
+      --source-range string    源范围，A1 表示法 (必填)
+      --target-range string    目标位置，A1 表示法 (必填)
+      --target-sheet-id string 目标工作表 ID 或名称（可选，不传则移动到同一工作表）
+```
+
+支持跨工作表移动，两种方式指定目标工作表：
+- `--target-sheet-id "Sheet2"` 显式指定
+- `--target-range "Sheet2!A1"` 在目标范围中携带工作表前缀
+
+源和目标范围不能重叠（同表时）。移动后源区域将被清空。
+
+## 上下文传递
+
+| 操作 | 从返回中提取 | 用于 |
+|------|-------------|------|
+| `list` | 工作表的 `sheetId` | range clear / range sort / range fill / range copy-to / range move-to 的 --sheet-id |
+
+> **批量操作**（`range batch-clear` / `batch-update`）已拆分至 [sheet-batch-operations](./sheet-batch-operations.md)，含写入边界 + 回读校验规范、典型组合场景示例等。
+
+## 注意事项
+
+- ★ **`--sheet-id` 获取规范（强制）**：`sheetId` 未知时必须先通过 `dws sheet list --node <NODE_ID> --format json` 查询真实的 `sheetId` / 工作表名称后再调用，禁止凭空编造（如臆测为 `Sheet1`、`sheet1`、`0`、`default` 等）；用户仅给出工作表名称时，也应通过 `list` 校验该名称是否存在，避免名称大小写或拼写不一致导致失败
+- ★ **清空区域用 `range clear` 不用 `range update`**：`range clear` 支持按类型（值/格式/全部）清除，比手动构造全空数组更简洁可靠
+- ★ **复制区域用 `range copy-to` 不用 `range read` + `range update`**：原子操作，保留公式引用自动调整，支持跨工作表
+- ★ **移动区域用 `range move-to` 不用 `range read` + `range update` + `range clear`**：原子操作，源区域自动清空，支持跨工作表
+- ★ **排序用 `range sort` 不用 `range read` + 客户端排序 + `range update`**：服务端原子操作，支持多级排序
+- ★ **排序前必须 `range read` 前几行判断表头**：读取排序范围前 3-5 行，对比首行与后续行的数据模式（类型、语义）来判断是否有表头。禁止不读就排，表头被排入数据不可撤销
+- ★ **填充用 `range fill` 不用 `range read` + 手动计算 + `range update`**：服务端智能填充，支持序列递增、公式扩展等
+- ★ **批量操作详见 [sheet-batch-operations](./sheet-batch-operations.md)**：`range batch-clear` 多区域清除、`batch-update` 组合写操作，均原子事务

package/skills/dws/dingtalk-misc/references/sheet/sheet-read-data.md

@@ -0,0 +1,60 @@
+# Sheet 读取数据
+
+## 读取路径
+
+| 需求 | 首选 | 结果形态 |
+|---|---|---|
+| Agent 快速查看值、低 token | dws sheet csv-get | CSV 文本加范围/截断元数据 |
+| 必须完整且截断即失败 | dws sheet +read | 严格完整读取 |
+| columns/data/dtypes/formats | dws sheet table-get | typed table/dataframe |
+| 需要公式、富文本、链接、验证等逐格结构 | dws sheet range read | per-cell JSON |
+| 合并、冻结、分组和尺寸 | dws sheet info | 工作表结构 |
+
+当前没有 sheetId 时只执行一次 +list-sheets，并把真实 sheetId 传播到后续阶段。不要为不需要 sheetId 的命令额外探活。
+
+## CSV 快速读取
+
+    dws sheet csv-get       --node <NODE_ID> --sheet-id <SHEET_ID> --range "A1:H200"       --format json
+
+返回契约必须按字段解释：
+
+- csv 每行带 `[row=N]` 定位前缀，该前缀不是单元格数据；真正 CSV 内容仍按 RFC 4180 解析。
+- `rowIndices[i]` 是第 i 个返回行的真实行号，`colIndices[j]` 是第 j 列的真实列字母。后续定位单元格必须使用这两个映射，禁止通过 CSV 中逗号数量推算列号。
+- `resolvedRange` 是未显式传 range 时服务端解析出的完整目标范围；`returnedRange` 是本次实际完整返回的范围，两者不能混用。
+
+读取成功后必须检查：
+
+- returnedRange 是否覆盖请求范围；
+- hasMore 是否为 false；
+- truncationReasons 是否为空；
+- 返回行列数是否符合预期。
+
+csv-get 单次最多 30000 单元格，并受 maxChars 约束。hasMore=true、范围缩短或出现截断原因时，只能说“当前块已读取”，不能说全量完成；按 returnedRange 的下一行构造下一块，保证无遗漏、无重叠并设置页数/块数上限。`max_cells` 不能靠增大 maxChars 解决。需要失败关闭时直接用 +read，避免由 Agent 手工实现完整性判断。
+
+`forbidden.document.sizeOverLimit` 表示工作簿整体无法装载，不是范围过大或空结果；缩小 range 不能修复。应建议创建更小副本或拆分工作簿，不得不断缩小范围绕过。
+
+csv-get 不返回合并单元格结构。合并区域的非左上角为空不能推导“没有内容”，需要 info 的 mergedRanges 配合解释。
+
+## 渲染选项
+
+- formatted_value：面向展示，可能包含格式化日期、货币或百分比。
+- raw_value：需要计算值或保留数值语义时使用。
+- formula：需要确认写入的公式文本时使用。
+
+公式验证通常分两次：先 formula 确认文本，再 raw_value 或 formula-verify 检查计算。不要把展示字符串当作原始数值，也不要把公式字符串当计算结果。
+
+## typed table 与逐格读取
+
+table-get 用于后续明确需要 columns、data、dtypes、formats 的处理链；普通问答不应为了“结构化”增加 token。默认首行作为表头，确实没有表头时才用 `--no-header`；返回 data 中 `{}` 表示空位，不是待执行的单元格对象。table-get 不返回逐格超链接、验证或样式元数据。
+
+range read 只在 CSV 无法承载的 per-cell 信息确实需要时调用，并尽量缩小范围和返回配置。其 cells 与 `rowIndices`/`colIndices` 对齐，可返回 value/formula/richText/hyperlink/dataValidation/cellStyles 等逐格结构；不能用它推断 mergedRanges。
+
+    dws sheet table-get --node <NODE_ID> --sheet-id <SHEET_ID> --range "A1:D100" --format json
+
+    dws sheet range read --node <NODE_ID> --sheet-id <SHEET_ID> --range "A1:B5" --format json
+
+如果命令返回非零、统一 envelope 的 ok=false、JSON 解析失败、条数不一致或分页游标不前进，立即失败。只有明确成功且终止状态成立时，空数组/空 CSV 才代表真实空结果。
+
+## 读取完成条件
+
+最终答复前确认：profile 一致；ID 来自当前任务；所有块都已覆盖；无 hasMore、截断、重复块或游标停滞；涉及结构时另有 info/object list 证据。只报告已验证范围，不夸大到整张表。

package/skills/dws/dingtalk-misc/references/sheet/sheet-revision-changeset.md

@@ -0,0 +1,46 @@
+# Sheet revision 与 changeset
+
+## 产品语义
+
+revision-get / changeset-get 用于编辑审计和前向语义变化，不是历史快照，也不能 revert。需要保存、列出或恢复在线历史版本时进入 sheet-version 阶段。changeset 不能代替当前值回读。
+
+## 获取区间
+
+    dws sheet revision-get --node <NODE_ID_OR_URL> --format json
+
+从成功 envelope 的 data.revision 读取整数。要观察后续变化，保存该 revision，再执行：
+
+    dws sheet changeset-get       --node <NODE_ID_OR_URL>       --start-revision <START>       --end-revision <END>       --format json
+
+省略 end-revision 表示查询到请求开始时固定下来的最新 revision。参数硬约束：
+
+- start/end 都是非负整数，revision 0 是合法空工作簿基线。
+- 查询区间是 `(startRevision, endRevision]`：不包含 start，包含 end；start=end 合法并返回空 changesets。
+- 单次跨度最多 20，即 end-start<=20。更大范围必须拆成首尾连续、无遗漏无重叠的分段；任一段失败或不完整，都不能宣称整个跨度完整。
+- start/end 必须来自当前文档、当前 profile 的真实返回；不要使用时间戳、猜测值或另一个文档的 revision。
+
+## 解读顺序
+
+1. 先看请求区间和返回终点，确认没有查询错文档或区间。
+2. 查看 detailsStatus 与 containsIncompleteChanges。
+3. 按 changesets 顺序读取事件类型，再读取每项 changes。
+4. 结合 targets 的 role、range/relative offset 判断来源、目标和受影响区域。
+5. 最后回读当前范围，确认最终状态。
+
+detailsStatus=COMPLETE 且 containsIncompleteChanges=false 才能把明细称为完整。PARTIAL、UNAVAILABLE、缺失明细或未知变更类型都应明确标注“审计信息不完整”，不能当作无变化。
+
+## 关键字段
+
+- 事件类型常见 EDIT、UNDO、STATE_RESET。UNDO 表示撤销事件，不代表简单删除上一条；STATE_RESET 可能使此前增量解释失效。
+- isSelfEdit=false 只表示不是当前请求用户提交，不能据此归因到某个其他用户、系统或自动化。
+- STATE_RESET 的 targetStatus=UNAVAILABLE 时不得猜 targetRevision；即使目标已知，也必须回读当前工作簿。
+- changes 描述单元格、范围、工作表、行列、分组、数据验证等语义变化。
+- targets 中 SOURCE、DESTINATION、AFFECTED 是角色，不是最终值；相对偏移必须结合该 change 的基准解释。
+- 字段为 null、缺失和显式 clear 含义不同，不能统一归为“空”。
+- changeset 记录操作语义，后续编辑、撤销或重置可能已经改变最终状态。
+
+## 错误与完成条件
+
+非零退出、ok=false、坏 JSON、revision 类型错误、区间不一致或 incomplete 状态均不得伪装成空 changesets。只有明确成功、完整并覆盖请求区间时，空 changesets 才能解释为该区间未返回可见变化。
+
+最终报告应区分：观察区间、完整性、发生过的操作、以及当前回读状态。涉及关键数据时，用 csv-get/range read 回读最小范围；涉及结构对象时用 info 或对应 list/get。分段结果只在所有段连续、完整且终点覆盖目标 end 时合并。

package/skills/dws/dingtalk-misc/references/sheet/sheet-search-replace.md

@@ -0,0 +1,120 @@
+# 搜索与替换
+
+## 使用场景
+
+用户说"搜索/查找/找单元格/搜内容/精确搜索/精确匹配/完全匹配/全字匹配":
+- 搜索单元格 → `find`
+- 精确匹配（只匹配完全等于的，不匹配包含的） → `find --match-entire-cell`
+- 正则搜索 → `find --use-regexp`
+- 搜索公式 → `find --match-formula`
+- 不要用 `range read` 读取全量数据后在客户端过滤来替代 `find`，必须使用 `find` 命令的服务端搜索能力
+
+用户说"替换/查找替换/全局替换/批量替换/把A替换成B/把所有的X改成Y":
+- 查找替换 → `replace`
+- 精确匹配后替换（只替换内容完全等于的单元格） → `replace --match-entire-cell`
+- 正则替换 → `replace --use-regexp`
+- 替换公式文本（改公式源码而非显示值） → `replace --match-formula`
+- 删除匹配内容 → `replace --replacement ""`
+- 请勿用 `find` + `range update`、`range read` + `range update` 等组合来模拟替换，`replace` 是服务端原子操作，效率更高且返回替换计数
+
+## 命令详细参考
+
+### 在工作表中搜索单元格内容
+```
+Usage:
+  dws sheet find [flags]
+Example:
+  # 基本搜索
+  dws sheet find --node <NODE_ID> --sheet-id <SHEET_ID> --find "销售额"
+
+  # 在指定范围内搜索
+  dws sheet find --node <NODE_ID> --sheet-id <SHEET_ID> --find "合计" --range "A1:D100"
+
+  # 正则表达式搜索（不区分大小写）
+  dws sheet find --node <NODE_ID> --sheet-id <SHEET_ID> --find "^total" --use-regexp --match-case=false
+
+  # 精确匹配整个单元格内容
+  dws sheet find --node <NODE_ID> --sheet-id <SHEET_ID> --find "完成" --match-entire-cell
+
+  # 搜索公式文本
+  dws sheet find --node <NODE_ID> --sheet-id <SHEET_ID> --find "SUM" --match-formula
+Flags:
+      --node string         表格文档 ID 或 URL (必填)
+      --sheet-id string     工作表 ID 或名称 (必填)
+      --find string         搜索文本 (必填)
+      --range string        搜索范围，A1 表示法 (如 A1:D10)
+      --match-case          区分大小写 (默认 true)
+      --match-entire-cell   精确匹配整个单元格内容
+      --use-regexp          启用正则表达式搜索
+      --match-formula       搜索公式文本而非显示值
+      --include-hidden      包含隐藏单元格
+```
+
+### 全局查找替换
+```
+Usage:
+  dws sheet replace [flags]
+Example:
+  dws sheet replace --node <NODE_ID> --sheet-id <SHEET_ID> --find "旧文本" --replacement "新文本"
+  dws sheet replace --node <NODE_ID> --sheet-id <SHEET_ID> --find "待处理" --replacement "已完成" --match-entire-cell
+  dws sheet replace --node <NODE_ID> --sheet-id <SHEET_ID> --find "\\d{4}" --replacement "****" --use-regexp
+  dws sheet replace --node <NODE_ID> --sheet-id <SHEET_ID> --find "旧" --replacement "新" --range "A1:D100"
+  dws sheet replace --node <NODE_ID> --sheet-id <SHEET_ID> --find "临时" --replacement ""
+Flags:
+      --node string            表格文档 ID 或 URL (必填)
+      --sheet-id string        工作表 ID 或名称 (必填)
+      --find string            查找文本 (必填)
+      --replacement string     替换文本 (必填，可为空字符串表示删除)
+      --range string           替换范围，A1 表示法 (如 A1:D100)
+      --match-case             区分大小写 (默认 false)
+      --match-entire-cell      完整单元格匹配
+      --use-regexp             启用正则表达式匹配
+      --match-formula          在公式文本中查找替换（默认 false，替换公式源码而非显示值）
+      --include-hidden         包含隐藏行/列
+```
+
+返回被替换的单元格数量。`--replacement` 可以为空字符串，表示删除匹配内容。
+
+## 核心工作流
+
+```bash
+# ── 工作流: 搜索表格数据 ──
+
+# 1. 获取工作表列表
+dws sheet list --node <NODE_ID> --format json
+
+# 2. 基本搜索 — 在指定工作表中查找文本
+dws sheet find --node <NODE_ID> --sheet-id <SHEET_ID> --find "销售额" --format json
+
+# 3. 在指定范围内搜索
+dws sheet find --node <NODE_ID> --sheet-id <SHEET_ID> --find "合计" --range "A1:D100" --format json
+
+# 4. 正则搜索（不区分大小写）
+dws sheet find --node <NODE_ID> --sheet-id <SHEET_ID> --find "^total" --use-regexp --match-case=false --format json
+
+# 5. 精确匹配整个单元格
+dws sheet find --node <NODE_ID> --sheet-id <SHEET_ID> --find "完成" --match-entire-cell --format json
+
+# 6. 搜索公式文本
+dws sheet find --node <NODE_ID> --sheet-id <SHEET_ID> --find "SUM" --match-formula --format json
+```
+
+## 上下文传递
+
+| 操作 | 从返回中提取 | 用于 |
+|------|-------------|------|
+| `list` | 工作表的 `sheetId` | find / replace 的 --sheet-id |
+| `find` | `matchedCells` 中的 `a1Notation` | 定位目标单元格，用于 range read / range update |
+| `replace` | `replaceCount` 被替换的单元格数量 | 确认替换结果 |
+
+## 注意事项
+
+- ★ **`--sheet-id` 获取规范（强制）**：`sheetId` 未知时必须先通过 `dws sheet list --node <NODE_ID> --format json` 查询真实的 `sheetId` / 工作表名称后再调用，禁止凭空编造（如臆测为 `Sheet1`、`sheet1`、`0`、`default` 等）；用户仅给出工作表名称时，也应通过 `list` 校验该名称是否存在，避免名称大小写或拼写不一致导致失败
+- ★ **搜索用 `find` 不用 `range read`**：`find` 是服务端搜索，禁止用 `range read` 全量读取后客户端过滤
+- ★ **替换用 `replace` 不用 `range update`**：`replace` 是服务端原子操作，返回替换计数
+- `find` 返回匹配单元格的地址（A1 表示法）和值，无匹配时返回空数组
+- `find` 的 `--match-entire-cell` 用于精确匹配：只返回单元格内容完全等于搜索文本的结果，不会匹配包含该文本的单元格（例如搜索"苹果"时，只匹配"苹果"，不匹配"苹果手机""苹果汁"等）。用户说"精确搜索/完全匹配/只搜等于XX的"时必须使用此参数
+- `find` 的 `--match-case` 默认为 true（区分大小写），设为 false 可忽略大小写
+- `find` 的 `--use-regexp` 启用后，`--find` 参数作为正则表达式处理
+- `replace` 的 `--find` 不能为空字符串，`--replace` 可以为空字符串（表示删除匹配内容）
+- `replace` 的 `--match-case` 默认为 false（不区分大小写），与 `find` 的默认行为不同

package/skills/dws/dingtalk-misc/references/sheet/sheet-style-format.md

@@ -0,0 +1,71 @@
+# Sheet 样式、数字格式与合并
+
+## 三层职责
+
+| 需求 | 路径 |
+|---|---|
+| 写少量值时给每格不同样式 | range update 的 cellStyles |
+| 给一个区域统一或二维设置样式 | range set-style |
+| 多区域原子设置样式 | range batch-set-style |
+| 改单个 richText 片段外观 | richText 子项 style |
+
+不要为了样式重写已有值。值与样式可分阶段：先写值并回读，再设置样式并验证。
+
+`sheet create-with-data --styles` 的顶层单项只接受 `name`、`cell_styles`、`row_sizes`、`col_sizes`、`cell_merges`；未知键会在创建前拒绝。每项至少包含一种样式操作，且数据写入后的样式阶段按上述顺序执行、不是原子事务。
+
+## 区域样式
+
+    dws sheet range set-style       --node <NODE_ID> --sheet-id <SHEET_ID> --range "A1:D1"       --bg-color "#FFF2CC" --font-weight bold --h-align center       --word-wrap autoWrap --format json
+
+只有需要逐格不同值时才用相应的二维 JSON flag，且数组维度必须与 range 一致。颜色使用有效十六进制；不要猜不在当前 compact Schema 中的枚举。
+
+可直接使用的统一值参数包括 bg-color、font-size、h-align、v-align、font-color、font-weight、word-wrap、number-format、font-style、font-line、font-family、border-styles-json；逐格不同只对 bg/font-size/h-align/v-align/font-color/font-weight 使用对应 `*-json` 二维矩阵。关键枚举：h-align=left/center/right/general，v-align=top/middle/bottom，word-wrap=overflow/clip/autoWrap，font-weight=bold/normal，font-style=normal/italic，font-line=none/underline/line-through。
+
+边框 JSON 只接受 top/bottom/left/right 四个边，每边只接受 style 和可选 color：
+
+    --border-styles-json '{"top":{"style":"solid","color":"#000000"},"bottom":{"style":"medium"}}'
+
+style 使用 solid/medium/thick/dashed/dotted/double/hair/none 等当前枚举；粗细包含在 style 中，不要发明 width。
+
+批量同样式：
+
+    dws sheet range batch-set-style       --node <NODE_ID>       --ranges '["Sheet1!A1:D1","Sheet2!A1:D1"]'       --font-weight bold --format json
+
+--ranges 每项必须带工作表前缀，最多 100 项。不同区域不同样式用 --batch 配置文件。默认严格事务，任一失败整批回滚；只有用户明确接受部分成功才用 --continue-on-error，且必须逐项报告并验证，不能把 partial 称为成功。
+
+`--ranges` 与 `--batch` 必须二选一。ranges 模式用命令行样式应用到所有范围；batch 模式的样式只从本地 JSON 文件读取，不能同时传任何命令行样式参数。batch 文件是数组，每项必须含 sheetId、range，可带与命令行同语义的 camelCase 字段，例如：
+
+    [
+      {"sheetId":"Sheet1","range":"A1:B3","bgColor":"#FFF2CC","fontWeight":"bold","borderStylesJson":"{\"bottom\":{\"style\":\"solid\"}}"},
+      {"sheetId":"Sheet2","range":"C1:C5","numberFormat":"¥#,##0.00"}
+    ]
+
+每个区域必须满足 rows<=1000、cells<=30000；最多 100 个区域，所有区域累计不得超过 200000 单元格。超出时按独立批次拆分，不能把拆分后的多次调用描述为一次原子事务。
+
+## 常用 number-format
+
+| 目标 | code |
+|---|---|
+| 数字形态 ID、订单号、手机号、工号 | @ |
+| 整数 / 两位小数 | 0 / 0.00 |
+| 千分位 | #,##0 或 #,##0.00 |
+| 人民币 / 美元 | ¥#,##0.00 / $#,##0.00 |
+| 百分比 | 0% 或 0.00% |
+| 日期 | yyyy-mm-dd |
+| 日期时间 | yyyy-mm-dd hh:mm:ss |
+
+数字格式只影响展示，不修复已经以浮点数损失精度的长 ID。此类值必须先以字符串写入并配合 @。
+
+## 合并与取消合并
+
+    dws sheet merge-cells       --node <NODE_ID> --sheet-id <SHEET_ID>       --range "A1:C3" --merge-type mergeRows --format json
+
+merge-type 为 mergeAll（默认）、mergeRows 或 mergeColumns。合并只保留各合并块左上角的值；若其它格已有内容，先读并向用户说明数据丢失风险。不要用合并模拟视觉居中。
+
+    dws sheet unmerge-cells       --node <NODE_ID> --sheet-id <SHEET_ID>       --range "A1:C3" --format json
+
+合并或取消后用 info 的 mergedRanges 验证。行列操作可能破坏合并边界，应在进入 dimension 阶段前传播当前 mergedRanges。
+
+## 完成条件
+
+样式命令成功后，使用能够返回样式结构的最小范围读取；合并使用 info。验证关键字段而非整表回读。失败、回读不一致或 continue-on-error 中存在失败项时，明确报告未完成部分。

package/skills/dws/dingtalk-misc/references/sheet/sheet-version.md

@@ -0,0 +1,84 @@
+# 历史版本 (version)
+
+## 使用场景
+
+管理钉钉在线电子表格的历史版本快照。当用户说"保存版本/存个快照/看历史版本/版本列表/回滚到某个版本/恢复到之前的表格"时使用。
+
+- 手动保存当前表格为一个版本快照 → `version save`
+- 查看表格的历史版本列表 → `version list`（别名 `ls`）。返回不含版本名称；列表项包含 `version`、`type`、`userId`、`createTime`、`updateTime`、`editorList` 等服务端字段
+- 把表格回滚到指定历史版本或已确认的精确 revision → `version revert`（危险操作，默认需二次确认）
+
+三个命令统一用 `--node` 指定表格文档（ID 或 URL）。默认从 `version list` 选择稳定的历史版本。用户明确要求恢复到某个精确 revision 时，也可把已从同一工作簿真实查询结果确认的 revision 传给 `--version`，即使它没有出现在版本列表中。禁止猜测版本号或 revision。
+
+## 命令详细参考
+
+### 保存表格版本快照
+```
+Usage:
+  dws sheet version save [flags]
+Example:
+  dws sheet version save --node SHEET_ID
+
+Flags:
+      --node string   表格文档 ID 或 URL (必填)
+```
+手动为当前在线电子表格生成一个历史版本快照，便于后续查看或回滚。
+
+### 查看表格历史版本列表
+```
+Usage:
+  dws sheet version list [flags]
+  dws sheet version ls [flags]
+Example:
+  dws sheet version list --node SHEET_ID
+  dws sheet version list --node SHEET_ID --limit 10
+
+Flags:
+      --node string     表格文档 ID 或 URL (必填)
+      --limit int       返回版本数量上限 (可选)
+      --cursor string   分页游标 (可选，游标分页)
+```
+返回表格的历史版本列表；顶层包含 `versions`、`nextCursor`、`hasMore`，列表项不含 `name`。回滚前先从列表项拿到真实 `version`（版本号）。
+
+### 回滚表格到指定版本
+```
+Usage:
+  dws sheet version revert [flags]
+Example:
+  dws sheet version revert --node SHEET_ID --version 3
+
+Flags:
+      --node string    表格文档 ID 或 URL (必填)
+      --version int    目标历史版本或已确认 revision (必填，通常从 version list 获取)
+```
+把表格回滚到指定历史版本或精确 revision。**危险操作**：会覆盖当前内容，默认要求二次确认。本文不提供带 `--yes` 的可复制示例；执行器只有在当前流程中向用户展示完整目标参数和覆盖风险、并获得明确确认后，才可动态追加全局 `--yes`。
+
+`version list` 只列选定的保存或回滚点，并不包含每一个 revision。未列入版本列表的 revision 只有在服务端仍可恢复时才能回滚成功；过旧或内容不可用时应直接报告失败，禁止改猜相邻 revision 重试。
+
+### 精确 revision 回滚
+
+只有用户明确要求恢复到某个 revision 时才走此流程：
+
+1. 用 `revision-get` 记录回滚前的当前 revision。
+2. 目标 revision 必须来自同一工作簿的真实查询结果，或由用户明确提供；不要根据次数、时间或相邻版本推算。
+3. 向用户展示工作簿、目标 revision 以及“当前内容将被覆盖”的风险，然后停止并等待明确确认；确认前禁止调用回滚工具，也禁止预先添加全局 `--yes`。
+4. 只有用户对当前展示的参数明确确认后，执行器才可对同一条命令动态追加全局 `--yes` 并执行；任一参数发生变化都必须重新确认。
+5. 用 `csv-get`、`range read` 或其他对应读取命令回读所需内容。
+6. 需要审计回滚事件时，用回滚前后的 revision 查询 `changeset-get`，确认出现 `STATE_RESET`，且 `reset.targetRevision` 等于目标 revision。
+
+## 上下文传递
+
+| 操作 | 从返回中提取 | 用于 |
+|------|-------------|------|
+| `version list` | `version`（版本号） | 作为 `version revert --version` 的入参 |
+| `revision-get` / `changeset-get` | 已确认属于同一工作簿的 `revision` | 用户明确要求精确恢复时，作为 `version revert --version` 的入参 |
+| `version save` | 版本快照结果 | 确认已生成快照 |
+| `version revert` | 回滚结果 | 确认回滚完成，回读表格内容验证 |
+
+## 注意事项
+
+- ★ 回滚 `version revert` 会**覆盖当前表格内容**，属危险操作；确认前禁止调用工具。只有用户对当前完整参数明确确认后，执行器才可动态追加全局 `--yes`；任一参数变化都必须重新确认
+- ★ 默认从 `version list` 选择历史版本；只有用户明确要求精确 revision 时，才使用同一工作簿真实查询结果中已确认的 revision
+- ★ 未列入版本列表的 revision 不保证仍可恢复；失败时直接说明，不猜测其他 revision，不自动重试
+- ★ `version list` 返回的 `version` 可作为 `changeset-get` 的 start/end 锚点，但相邻历史版本之间可能包含多个 revision。需要查看逐次变更时读 [sheet-revision-changeset](./sheet-revision-changeset.md)
+- 回滚后应用独立读命令（`csv-get` / `range read`）回读确认，避免"写返回不等于完成"

package/skills/dws/dingtalk-misc/references/sheet/sheet-workbook.md

@@ -0,0 +1,59 @@
+# Sheet 工作簿与工作表
+
+## 本阶段范围
+
+用于创建工作簿、列出/新增/重命名/复制/删除工作表，以及冻结、隐藏、顺序、网格线和结构信息。值读写留在上层 sheet.md；样式、行列和对象操作进入各自阶段。
+
+## 最短命令表
+
+| 目标 | 命令 |
+|---|---|
+| 创建空工作簿 | dws sheet create --name <NAME> --format json |
+| 创建并写初始数据 | dws sheet create-with-data --name <NAME> --values <2D_JSON> --format json |
+| 列出工作表 | dws sheet +list-sheets --node <NODE_ID> --format json |
+| 工作表结构详情 | dws sheet info --node <NODE_ID> --sheet-id <SHEET_ID> --format json |
+| 新建工作表 | dws sheet new |
+| 改名、隐藏、排序、冻结 | dws sheet update |
+| 复制工作表 | dws sheet copy |
+| 删除工作表 | dws sheet delete-sheet |
+| 显示/隐藏网格线 | dws sheet show-gridline / hide-gridline |
+
+有初始数据时用 create-with-data，它已经包含创建、默认工作表探活、写入和回读；不要再额外 list 一次。空表才用 create。
+
+create-with-data 的成功率契约：
+
+- `--values` 与 `--sheets` 必须且只能提供一个；只有空表需求才改用 create。
+- values 是非空二维 JSON，只含 string/number/boolean/null，最多 30000 单元格且编码后不超过 2M 字符。
+- sheets 每项必须用 camelCase，只接受 name/columns/data/dtypes/formats/cellStyles/startCell/mode/header/allowOverwrite；创建阶段不接受 sheetId。name、columns 必填，data 每行宽度必须等于 columns，dtypes/formats 键必须来自 columns。
+- `--styles` 顶层使用 `{"styles":[...]}`；配 sheets 时样式项数量、顺序和 name 必须一一对应，配 values 时只能有一项。执行顺序是 cell_styles、row_sizes、col_sizes、cell_merges，整体非原子。
+- 所有 JSON、枚举和预算都在创建前校验。若后续探活/写入/样式失败，错误中的已创建 nodeId 必须保留并报告，用于续做或经确认后清理；不能再次 create 产生重复文档。
+
+## ID 与上下文
+
+- create / create-with-data 返回的 nodeId 是后续唯一文档标识，立即复用；不要从 URL 字符串截取或从历史任务复用。
+- --folder / --workspace 接受 Drive fileId UUID 或可解析的 alidocs URL，不接受数字 dentryId。
+- 需要 sheetId 时优先复用 create-with-data 探活返回值；上下文没有才执行一次 +list-sheets。
+- 用户给的是工作表名称也要按完整标题唯一匹配；禁止猜 Sheet1、sheet1、0、default。
+- info 返回 mergedRanges、冻结、尺寸、隐藏和可选 groups 等结构信息；CSV 空格不能代替结构查询。`--include` 按需取 row_heights、col_widths、groups；同时检查 nonEmptyRange、默认行高列宽和隐藏行列，避免为了完整结构无界输出。
+
+## 常见闭环
+
+    dws sheet +list-sheets --node <NODE_ID> --format json
+    dws sheet new --node <NODE_ID> --name "明细" --format json
+    dws sheet +list-sheets --node <NODE_ID> --title "明细" --format json
+
+更新工作表属性前，先从 list/info 读取当前状态；只提交用户要求变更的字段。复制后使用响应返回的新 sheetId，不按名称猜测。重命名、移动顺序或删除可能使后续名称/位置引用失效，必须把新状态传播给下一阶段。
+
+update 至少传 name/index/hidden/frozen-row-count/frozen-column-count/tab-color 之一。name 最长 100 字符且不能含 `/ \\ ? * [ ] :`；index 从 0 开始；冻结数不得越过实际行列边界；不能隐藏所有工作表。tab-color 使用 `#RRGGBB`，显式空字符串表示清除颜色。copy 的 index 也从 0 开始；未给 name 时由系统生成，必须使用返回的新 sheetId。
+
+## 删除与验证
+
+delete-sheet 会永久删除目标工作表。执行前展示 nodeId、sheetId/标题和影响范围，得到明确同意后才加 --yes。隐藏工作表必须先取消隐藏；不能删除最后一个可见工作表。不要删除工作簿中未确认的同名表，也不要把“删除整个在线文件”误路由到 delete-sheet。
+
+所有结构修改都用匹配的读操作验证：
+
+- new/copy/update/delete-sheet：+list-sheets；
+- 冻结、隐藏、尺寸、合并：info；
+- 网格线：info 或命令返回的明确状态。
+
+响应非零、JSON 无法解析或缺失预期对象均为失败，不得当作空列表或成功。