chenmingxuan/EP-Hub-Skill
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
chenmingxuan
2026-09-02 11:44:52 +08:00
commit 0c8fa2653e
309 changed files with 57278 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/dingtalk-misc/references/sheet/sheet-batch-operations.md
+55
View File
@@ -0,0 +1,55 @@
# Sheet 批量原子操作
## 使用边界
batch-update 用于多个相互依赖且已确认参数的原子写；range batch-clear 用于跨工作表批量清空。不要把独立命令能完成的一次写拆成 batch，也不要为了减少调用把不相关风险混在一起。
当前 batch-update 只支持以下精确 toolName：`range clear`、`range update`、`merge-cells`、`unmerge-cells`、`range fill`、`range copy-to`、`add-dimension`、`delete-dimension`、`move-dimension`、`update-dimension`、`group-dimension`、`ungroup-dimension`、`set-dropdown`、`delete-dropdown`、`csv-put`、`delete-float-image`。
以下不进入 batch-update：set-style/batch-set-style、table-put/table-get、range read/csv-get、对象 create/update/list、嵌套 batch、需要立即折叠的 group-dimension。样式批量使用独立 range batch-set-style；结构化 table 独立写并独立回读；折叠分组用独立 group-dimension --group-state fold。不要把相似的 CLI leaf 名称猜成受支持 toolName。
## 批量清空
dws sheet range batch-clear --node <NODE_ID> --ranges '["Sheet1!A1:B3","Sheet2!C1:D5"]' --type content --format json
每个范围必须带工作表前缀。type 为 content、format 或 all；all 会同时删除值和格式，属于高风险操作。执行前读最小范围并展示目标，获得明确确认后才执行破坏性清空。默认原子：任一区域失败整批回滚。
## batch-update 结构
dws sheet batch-update --node <NODE_ID> --operations '[
{"toolName":"range clear","input":{"sheet-id":"Sheet1","range":"A1:B3","type":"content"}},
{"toolName":"range update","input":{"sheet-id":"Sheet1","range":"A1","values":[[{"type":"text","text":"hello"}]]}},
{"toolName":"merge-cells","input":{"sheet-id":"Sheet1","range":"A1:B1","merge-type":"mergeAll"}}
]' --format json
每项形如 {"toolName": "...", "input": {...}}：
- toolName 必须逐字取上面的支持清单，不接受 MCP RPC 名或缩写。
- input 键使用 CLI flag 名去掉 --，例如 sheet-id、start-index、merge-type。
- node 只在批次顶层传，不在子操作中重复。
- 子操作按数组顺序执行；依赖前项产生的新 ID 的对象不适合放进同一静态批次。
- 不确定某个 leaf 的字段时只读该 leaf compact Schema，不读取所有 Help。
set-dropdown 的 batch input 仍遵循精确互斥：inline 用 options（颜色只能写 options[].color）；SourceRange 用 source-sheet-id 与 source-range 且二者必须同时出现。options 与 source-range 必须且只能选一个；顶层 colors/source-colors 不支持，SourceRange 颜色也不支持。
默认不加 --continue-on-error，这样任一失败整批回滚。只有用户明确接受部分成功时才加；此时顶层请求可能成功但子项仍有失败，必须按输入索引逐项解析状态、错误和实际结果，失败项不能被成功项掩盖。
## 预检与安全
批次发送前检查：所有 sheetId 来自当前任务；范围无意外重叠；操作顺序满足依赖；删除/清空/移动影响已确认；预计操作数与数组长度一致。不要用 validate 成功替代真实执行，也不要在失败后盲目重发整批。
超时或响应不确定时先回读目标状态：
- 原子模式：判断整批是否已落地，再决定是否重试。
- continue-on-error：只为已证明缺失且可安全重试的项目构造新批次。
- 非幂等操作如 append、insert、move 未确认状态前禁止重放。
## 写后验证
批次成功后按结果类型合并验证，避免逐操作全表读取：
- 值：一次读取覆盖所有受影响值的最小范围；
- 样式/合并/行列：info 或样式读取；
- dropdown/对象：对应 list/get。
预期条数、结果条数或关键状态不一致即失败。只读校验可做有界退避；不得通过重复写“碰碰运气”。最终说明原子/部分模式、成功项、失败项和已验证范围。
.agents/skills/dingtalk-misc/references/sheet/sheet-chart.md
+69
View File
@@ -0,0 +1,69 @@
# Sheet 浮动图表
## 真对象约束
用户要求图表时必须创建 Sheet chart 对象，不能用单元格字符、静态图片或本地绘图冒充。chartId 必须来自本任务 create/list；所有操作复用真实 nodeId、sheetId。
常见映射：分类比较用 column/bar，趋势用 line，构成用 pie/doughnut，两个连续变量关系用 scatter。当前支持的精确类型只有：column、bar、columnStacked、barStacked、line、lineStacked、area、areaStacked、areaPercentStacked、pie、doughnut、scatter、radar。
当前不支持 combo/组合图或双轴组合图。用户要求此类图表时不得发送 `type:"combo"`，也不能谎称已经创建；应说明限制，并在用户接受时改为两个受支持的独立图表。用户已指定其他受支持类型时不擅自替换。
## 创建前
1. csv-get 读取数据范围，确认表头、类别列和系列列。
2. info 查看已用行列与结构。
3. 选择不遮挡数据的 position；宽高为正数。
4. 每个 series/category 的 A1 引用必须位于同一工作表上下文，范围长度匹配。
## 创建与查询
dws sheet chart create --node <NODE_ID> --sheet-id <SHEET_ID> --properties '{
"position":{"row":12,"col":"A"},
"dimensions":{"width":600,"height":400},
"chart":{
"type":"column",
"series":[{"name":"B1","value":["B2:B10"]}],
"category":["A2:A10"],
"title":{"show":true,"text":"销售数据"}
}
}' --format json
properties 顶层必须同时包含 position、dimensions、chart，可选 offset。硬约束：
- position.row 和 position.col 都必填；row 是 0-based 锚点行，col 必须是列字母（如 A、AA），不支持数字列号。
- dimensions.width/height 都必填且为正数。
- chart.type 必须取上面的支持枚举。
- chart.series 必须是非空数组；每项都必须有非空的 value 范围数组。series.name 可引用表头格，category 是类别范围数组。
- series/name/category 使用 A1 表示法；不带工作表前缀时使用 `--sheet-id` 对应工作表。引用跨表数据时显式带工作表前缀，不从当前名称猜测。
复杂轴、图例、颜色等字段只在用户需要时加入，不确定时读取 chart create 的 compact Schema；不得从其他表格产品照搬字段。当前常用配置面：
| 对象 | 已知字段与枚举 |
|---|---|
| `title` | `show:boolean`、`text:string` |
| `legend` | `show:boolean`；`pos` 仅为 `t` / `b` / `l` / `r` / `none` |
| `catAx` / `valAx` | `show:boolean`、`pos:l/t/b/r`、`titleConfig:{show,title}`、`axisMin` / `axisMax` 为 `number` / `null`、`splitLine:boolean`、`minorSplitLine:boolean`、`axisLabel:boolean`、`axisLine:boolean` |
未列出的字段或枚举以精确 leaf Schema 为准，不猜测；更新时仍须先读完整对象再整体回写。
创建后保存返回 chartId，并验证：
dws sheet chart list --node <NODE_ID> --sheet-id <SHEET_ID> --chart-id <CHART_ID> --format json
检查类型、数据范围、标题、位置和尺寸。列表成功但找不到刚创建 ID，不能称为完成。
## 更新是 PUT
chart update 的 properties 为整体覆盖，不是 patch。必须先 list 单个 chart，保留完整 position/dimensions/chart，在本地只改目标字段后整体回写：
dws sheet chart update --node <NODE_ID> --sheet-id <SHEET_ID> --chart-id <CHART_ID> --properties '<完整_PROPERTIES_JSON>' --format json
只提交局部配置会把未传字段恢复默认或删除。更新后再次 list 单个对象并比较关键字段。
## 删除
删除不可恢复。先 list 获取名称、chartId、数据范围和位置，展示摘要并获得明确同意，然后：
dws sheet chart delete --node <NODE_ID> --sheet-id <SHEET_ID> --chart-id <CHART_ID> --yes --format json
最后 list 验证对象消失。非零、坏 JSON、缺失对象或错误 ID 不得当作成功。
.agents/skills/dingtalk-misc/references/sheet/sheet-comment.md
+166
View File
@@ -0,0 +1,166 @@
# sheet comment（表格单元格评论：list / create / reply / update / delete）
> **前置条件（MUST READ）：** 执行本命令前，必须先用 Read 工具读取以下文件：
> 1. [`../sheet.md`](../sheet.md) — 命令路由 + 场景索引 + 意图判断 + 全局约束
>
> **同任务常配合**：`dws aisearch person`（查 `--mention` 用 userId）/ [`sheet-workbook.md`](sheet-workbook.md)（未知工作表名称时先 `list` 确认真实名称）
---
## 适用范围
- 仅支持钉钉在线电子表格（`extension=axls`）。`xlsx` / `xls` / `csv` 等本地表格不支持评论。
- 评论锚定在**单元格位置**：`create` / `list` 通过 `--sheet-id`（工作表 ID 或名称）+ `--range`（单元格坐标）定位；`reply` / `update` / `delete` 通过 `--comment-key` 操作，不依赖单元格位置。
- `create` / `list` 通过单元格位置定位；`reply` / `update` / `delete` 通过前一步返回的 `commentKey` 定位评论线程，不需要重新传单元格位置。
- Agent 只使用命令返回的 `commentKey` 继续回复、更新或删除，不自行构造评论标识。
---
## sheet comment list（查询表格评论列表）
```
Usage:
dws sheet comment list [flags]
Example:
dws sheet comment list --node <SHEET_ID>
dws sheet comment list --node <SHEET_ID> --sheet-id Sheet1 --range A2
dws sheet comment list --node <SHEET_ID> --resolve-status unresolved
dws sheet comment list --node <SHEET_ID> --cursor <TOKEN>
Flags:
--node string 目标表格的标识，支持传入 URL 或 ID (必填)
--limit int 每页返回的评论数量，默认 50，最大 50
--cursor string 分页游标，从上一次请求的返回结果中获取 (首次请求不传)
--resolve-status string 按解决状态过滤: resolved (已解决) / unresolved (未解决)
--sheet-id string 工作表 ID 或名称，如 Sheet1（与 --range 一起指定时按单元格过滤）
--range string 单元格位置，A1 表示法，如 A2、B5:C10（与 --sheet-id 一起指定时按单元格过滤）
```
- 同时传入 `--sheet-id` 和 `--range` 时，仅返回该单元格的评论（服务端按单元格精确过滤）；不传则返回表格全部单元格评论。
---
## sheet comment create（创建单元格评论）
```
Usage:
dws sheet comment create [flags]
Example:
dws sheet comment create --node <SHEET_ID> --sheet-id Sheet1 --range A2 --content "这个数字有问题"
dws sheet comment create --node <SHEET_ID> --sheet-id Sheet1 --range A2 --content "请核实" --mention uid1,uid2
Flags:
--node string 目标表格的标识，支持传入 URL 或 ID (必填)
--sheet-id string 工作表 ID 或名称，如 Sheet1 (必填)
--range string 单元格位置，A1 表示法，仅支持单个单元格，如 A2 (必填)
--content string 评论的文字内容，纯文本 (必填)
--mention string 被 @ 的用户 uid 列表，逗号分隔
```
- 未知工作表名称时，先 `dws sheet list --node <SHEET_ID> --format json` 确认真实名称，禁止臆测 `Sheet1` / `0` / `default`。
---
## sheet comment reply（回复评论）
```
Usage:
dws sheet comment reply [flags]
Example:
dws sheet comment reply --node <SHEET_ID> --comment-key <COMMENT_KEY> --content "已核实"
dws sheet comment reply --node <SHEET_ID> --comment-key <COMMENT_KEY> --content "比心" --emoji
dws sheet comment reply --node <SHEET_ID> --comment-key <COMMENT_KEY> --content "请确认" --mention uid1,uid2
Flags:
--node string 目标表格的标识，支持传入 URL 或 ID (必填)
--content string 回复的文字内容，表情回复时填写表情名称 (必填)
--comment-key string 被回复评论的 commentKey，格式: {13位毫秒时间戳}{32位UUID}，可从 list/create 结果获取 (必填)
--emoji 设为 true 时作为表情贴图回复 (默认 false)
--mention string 被 @ 的用户 uid 列表，逗号分隔
```
- 回复自动归属到被回复评论所在的单元格线程，无需再传 `--sheet-id` / `--range`。
---
## sheet comment update（更新评论）
```
Usage:
dws sheet comment update [flags]
Example:
dws sheet comment update --node <SHEET_ID> --comment-key <COMMENT_KEY> --content "已按最新数据修正"
Flags:
--node string 目标表格的标识，支持传入 URL 或 ID (必填)
--comment-key string 待更新评论的 commentKey，格式: {13位毫秒时间戳}{32位UUID}，可从 list/create 结果获取 (必填)
--content string 更新后的评论文字内容，纯文本 (必填)
```
---
## sheet comment delete（删除评论）
> [强制] 危险操作：删除不可恢复。必须先向用户展示操作摘要并获得明确同意，用户同意后才加 `--yes` 执行。
```
Usage:
dws sheet comment delete [flags]
Example:
dws sheet comment delete --node <SHEET_ID> --comment-key <COMMENT_KEY> --yes
Flags:
--node string 目标表格的标识，支持传入 URL 或 ID (必填)
--comment-key string 待删除评论的 commentKey，格式: {13位毫秒时间戳}{32位UUID}，可从 list/create 结果获取 (必填)
```
## 关键说明
- `--mention` 接受 `userId` 列表（逗号分隔），需要先用 `dws aisearch person --query "<姓名>" --dimension name` 拿到 userId。
- `--comment-key` 是 13 位毫秒时间戳 + 32 位 UUID 的拼接字符串，从 `list` / `create` 返回中提取，用于 `reply` / `update` / `delete`。
- `create` / `list`（按单元格过滤）的 `--sheet-id` 是工作表 ID 或名称；未知时先 `dws sheet list` 确认，禁止臆测。
- `reply` 加 `--emoji` 时 `--content` 填表情名称（如 `比心`、`赞`），不是文字内容。
- `delete` 是不可逆操作；AI Agent 必须先向用户展示操作摘要并获得明确同意，同意后才追加 `--yes`。
## 上下文传递
| 从返回中提取 | 用于 |
|-------------|------|
| `commentList[].commentKey` | `comment reply/update/delete` 的 `--comment-key` |
| `comment create` 的 `commentKey` | `comment reply/update/delete` 的 `--comment-key` |
| [`sheet-workbook.md`](sheet-workbook.md) `sheet list` 的工作表名称 | `comment create/list` 的 `--sheet-id` |
| `dws aisearch person` 的 `userId` | `comment create/reply` 的 `--mention` |
## 常用模板
```bash
# 查看表格全部单元格评论
dws sheet comment list --node <SHEET_ID> --format json
# 仅看某个单元格的评论
dws sheet comment list --node <SHEET_ID> --sheet-id Sheet1 --range A2 --format json
# 仅看未解决的评论
dws sheet comment list --node <SHEET_ID> --resolve-status unresolved --format json
# 在单元格上创建评论（未知工作表名先 sheet list 确认）
dws sheet list --node <SHEET_ID> --format json
dws sheet comment create --node <SHEET_ID> --sheet-id Sheet1 --range A2 --content "这个数字有问题" --format json
# 创建评论 + @人（先 aisearch person 拿 userId）
dws aisearch person --query "张三" --dimension name --format json
dws sheet comment create --node <SHEET_ID> --sheet-id Sheet1 --range A2 --content "请确认" --mention <uid1>,<uid2> --format json
# 文字回复
dws sheet comment reply --node <SHEET_ID> --comment-key <COMMENT_KEY> --content "已核实" --format json
# 表情回复（--content 填表情名称）
dws sheet comment reply --node <SHEET_ID> --comment-key <COMMENT_KEY> --content "比心" --emoji --format json
# 更新评论
dws sheet comment update --node <SHEET_ID> --comment-key <COMMENT_KEY> --content "已按最新数据修正" --format json
# 删除评论（不可逆；必须用户确认后再加 --yes）
dws sheet comment delete --node <SHEET_ID> --comment-key <COMMENT_KEY> --yes --format json
```
## 参考
- [`../sheet.md`](../sheet.md)（如何路由到本命令族）
- [`./sheet-workbook.md`](sheet-workbook.md)（取工作表名称）
- `dws aisearch person`（取 mention 用的 userId，跨产品命令）
.agents/skills/dingtalk-misc/references/sheet/sheet-conditional-format.md
+59
View File
@@ -0,0 +1,59 @@
# Sheet 条件格式
## 边界
条件格式是随单元格值变化的规则对象，不是一次性静态样式。只要求固定外观时进入 sheet-style-format。ruleId 必须来自本任务 create/list；所有操作使用真实 nodeId、sheetId。
若用户明确要求新增“判断结果/是或否”辅助列，必须先写可见辅助列，再基于辅助列创建规则；不能用一步 formulaCondition 隐藏掉用户要求的数据产物。
## 创建前
- 读取最小数据范围，确认首行、空值和数据类型。
- ranges 是 JSON 数组，使用精确 A1 范围，不扩大到无界整列。
- 日期或公式条件要处理空单元格，避免空值被当作 0/日期触发。日期到期示例使用 `=AND(E1<>"",E1<=TODAY())`；相对引用随行变化，只有明确固定比较一个格时才用绝对引用。
- 每条规则的 condition 只能选一种结构。常用精确形态：
- numberCondition：operator=equal/not-equal/greater/greater-equal/less/less-equal/between/not-between；value1 必填，between/not-between 还需 value2。
- textCondition：operator=contains/not-contains/starts-with/ends-with，value 为文本。
- emptyCondition/errorCondition/duplicateCondition：operator 分别取 is-empty/is-not-empty、error/no-error、duplicate/unique。
- formulaCondition：`{"formula":"=A1>100"}`。
- rankCondition：value、isPercent、isBottom；averageCondition：isAbove、andEqual；stdevCondition：value、isAbove、andEqual。
- dataBarCondition：minPoint/maxPoint，各点 type 取 auto/maxmin/number/percent/percentile/formula，可带 value；样式单独用 data-bar-style。
- iconSetCondition：iconSet 数组项包含 criteria `{type,value,gtOrEqual}` 和 icon `{type:"id",value:...}`，可带 showIconOnly。
- colorScaleCondition：criterias 为 2 或 3 项，每项 `{type,value?,color}`。
- cell-style 只使用 backgroundColor、fontColor、bold、italic、strikethrough。“标红/高亮/染色”默认 backgroundColor，只有明确“字体红”才用 fontColor。不确定扩展字段时读 create 的 compact Schema。
## 创建
数值阈值示例：
dws sheet cond-format create --node <NODE_ID> --sheet-id <SHEET_ID> --ranges '["A2:A100"]' --condition '{"numberCondition":{"operator":"greater","value1":"80"}}' --cell-style '{"backgroundColor":"#FFCDD2","fontColor":"#B71C1C","bold":true}' --format json
辅助列示例，分两个阶段：
dws sheet range update --node <NODE_ID> --sheet-id <SHEET_ID> --range "H2:H4" --values '[[{"type":"text","text":"=IF(A2>B2,\"是\",\"否\")"}],[{"type":"text","text":"=IF(A3>B3,\"是\",\"否\")"}],[{"type":"text","text":"=IF(A4>B4,\"是\",\"否\")"}]]' --format json
dws sheet cond-format create --node <NODE_ID> --sheet-id <SHEET_ID> --ranges '["A2:H4"]' --condition '{"formulaCondition":{"formula":"=$H2=\"是\""}}' --cell-style '{"backgroundColor":"#FFECEC"}' --format json
先回读 H2:H4 的公式和值，再创建规则。不要把公式条件视觉正确等同于辅助列已经存在。
数据条样式示例：
--condition '{"dataBarCondition":{"minPoint":{"type":"auto"},"maxPoint":{"type":"auto"}}}' --data-bar-style '{"fill":["#4CAF50","#F44336"],"isGradient":true}'
三色色阶示例：
--condition '{"colorScaleCondition":{"criterias":[{"type":"maxmin","color":"#F44336"},{"type":"percentile","value":"50","color":"#FFEB3B"},{"type":"maxmin","color":"#4CAF50"}]}}'
## 查询、更新、删除
dws sheet cond-format list --node <NODE_ID> --sheet-id <SHEET_ID> --rule-id <RULE_ID> --format json
update 是部分更新：至少传 ranges、condition、cell-style、data-bar-style 之一，未传字段保持不变；传 condition 会替换原条件类型。先 list 单个对象确认当前类型与范围，再只提交用户要求的字段，完成后重新 list。
dws sheet cond-format update --node <NODE_ID> --sheet-id <SHEET_ID> --rule-id <RULE_ID> --condition '{"numberCondition":{"operator":"greater","value1":"90"}}' --format json
删除规则不删除原始数据，但会永久移除视觉规则；规则已不存在时按幂等成功处理。展示 ruleId、范围和条件，得到明确同意后：
dws sheet cond-format delete --node <NODE_ID> --sheet-id <SHEET_ID> --rule-id <RULE_ID> --yes --format json
create/update 后 list 验证 ID、ranges、condition 和样式；delete 后验证规则消失。命令失败、JSON 损坏或列表缺字段不能解释为空规则。
.agents/skills/dingtalk-misc/references/sheet/sheet-dimension-operations.md
+60
View File
@@ -0,0 +1,60 @@
# Sheet 行列操作
## 适用命令
| 目标 | 命令 |
|---|---|
| 在位置前插入 | insert-dimension |
| 删除连续行/列 | delete-dimension |
| 隐藏、显示、调整尺寸 | update-dimension |
| 移动连续行/列 | move-dimension |
| 末尾追加空行/列 | add-dimension |
| 创建/取消分组 | group-dimension / ungroup-dimension |
所有命令前缀均为 dws sheet，并要求当前任务真实 nodeId、sheetId。
## 坐标规则
- dimension 只取 ROWS 或 COLUMNS。
- ROWS 的 position/start-index/end-index/destination-index 使用 1 起始行号字符串，如 "3"。
- COLUMNS 使用列字母，如 "A"、"AB"。
- 这些参数不是 A1 矩形范围，不要传 A1:C5。
- 分组范围必须是整行 "3:7" 或整列 "C:F"；普通矩形无效。
- insert/delete/update/add-dimension 的 length 都是正整数，单次最多 5000。
- position/start-index/range 带工作表前缀时，以前缀解析出的工作表为准并忽略 sheet-id；只在确有跨表坐标需求时使用，避免名称歧义。
## 操作前检查
插入、删除、移动之前先执行：
dws sheet info --node <NODE_ID> --sheet-id <SHEET_ID> --format json
检查 mergedRanges、冻结、隐藏和现有 groups。若合并区域跨过操作位置，先说明影响；必要时明确取消合并，完成结构操作后按原意恢复。删除、移动会改变公式引用、命名范围和后续坐标，下一阶段必须使用更新后的范围。
move-dimension 的 start/end 为包含端点的连续源区间；destination-index 不能落在源区间内。向下/向右移动时目标应大于 end，向上/向左时目标应小于 start。涉及合并单元格的移动可能失败；不得改用“读出、删除、写回”模拟移动，先记录 mergedRanges，必要时取消合并并在操作后恢复。
删除行列属于不可逆结构修改。展示维度、起点、长度及可能影响，获得明确同意后才执行需要的确认参数。
## 精确示例
dws sheet insert-dimension --node <NODE_ID> --sheet-id <SHEET_ID> --dimension ROWS --position "3" --length 2 --format json
dws sheet update-dimension --node <NODE_ID> --sheet-id <SHEET_ID> --dimension COLUMNS --start-index "C" --length 1 --pixel-size 200 --hidden --format json
dws sheet move-dimension --node <NODE_ID> --sheet-id <SHEET_ID> --dimension ROWS --start-index "2" --end-index "4" --destination-index "1" --format json
update-dimension 的尺寸模式：pixel 必须配合非负 `--pixel-size`；standard 恢复默认尺寸且不能同时传 pixel-size；auto 按内容自适应且只支持 ROWS，也不能同时传 pixel-size。只改 hidden 时省略 size-type/pixel-size；只改尺寸时不要顺带提交 hidden。
## 分组
dws sheet group-dimension --node <NODE_ID> --sheet-id <SHEET_ID> --range "3:7" --group-state fold --format json
dws sheet info --node <NODE_ID> --sheet-id <SHEET_ID> --include groups --format json
分组后在 rowGroups/columnGroups 中按 range 验证；collapsed=true 表示折叠。group/ungroup 可进入 batch-update，但 batch 内只使用默认展开；要求创建后立即折叠时单独调用 group-dimension --group-state fold。
group-state 只决定新建分组的初始 expand/fold 状态。当前没有“只修改已有分组 collapsed 状态”的独立命令；不要通过再次 group 猜测为状态更新，也不要从 groups 的 level/depth 推导可写参数。
## 完成条件
结构写响应后必须重新 info；验证行列数量、隐藏/尺寸、mergedRanges 和 groups 与预期一致。若坐标变化，向后续阶段传播新范围，不能继续使用修改前的 A1 地址。
.agents/skills/dingtalk-misc/references/sheet/sheet-dropdown.md
+103
View File
@@ -0,0 +1,103 @@
# 下拉列表 (dropdown)
## 使用场景
### 下拉列表
用户说"设置下拉列表/下拉选项/下拉菜单/添加下拉/配置下拉":
- 设置下拉列表 → `set-dropdown`
- 设置多选下拉 → `set-dropdown --multi-select`
- 引用单元格区域作为候选项 → `set-dropdown --source-sheet-id ... --source-range ...`
用户说"查看下拉列表/获取下拉配置/下拉列表有哪些选项":
- 获取下拉列表配置 → `get-dropdown`
用户说"删除下拉列表/移除下拉/取消下拉/清除下拉":
- 删除下拉列表 → `delete-dropdown`
## 命令详细参考
### 设置下拉列表
```
Usage:
dws sheet set-dropdown [flags]
Example:
# 设置单选下拉列表
dws sheet set-dropdown --node <NODE_ID> --sheet-id <SHEET_ID> --range "A2:A100" \
--options '[{"value":"选项1"},{"value":"选项2"},{"value":"选项3"}]'
# 设置带颜色的多选下拉列表
dws sheet set-dropdown --node <NODE_ID> --sheet-id <SHEET_ID> --range "B2:B50" \
--options '[{"value":"高","color":"#ff0000"},{"value":"中","color":"#ffaa00"},{"value":"低","color":"#00ff00"}]' \
--multi-select
# 引用同一工作簿内另一工作表的区域作为候选项来源
dws sheet set-dropdown --node <NODE_ID> --sheet-id <TARGET_SHEET_ID> --range "C2:C100" \
--source-sheet-id <SOURCE_SHEET_ID> --source-range "T1:T3"
Flags:
--node string 表格文档 ID 或 URL (必填)
--sheet-id string 工作表 ID 或名称 (必填)
--range string 目标单元格范围，A1 表示法，如 A2:A100 (必填)
--options string Inline 下拉选项 JSON 数组，与 --source-range 二选一
--source-sheet-id string SourceRange 来源工作表 ID，与 --source-range 同时指定
--source-range string SourceRange 来源区域，与 --options 二选一；不带工作表前缀
--multi-select 是否允许多选（默认单选）
```
在指定单元格范围内设置下拉列表。Inline 模式直接存储选项；SourceRange 模式引用同一工作簿内的来源区域，可跨工作表，并支持普通区域、整行和整列。
- **用途**：为单元格配置静态选项或区域来源下拉，两种模式都支持多选；颜色仅 Inline 支持。
- **场景**：规范数据输入，如状态选择（完成/进行中/待处理）、优先级（高/中/低）等。
- **注意**：`--options` 与 `--source-range` 必须且只能指定一个。`--source-range` 只写 `T1:T3`、`T:T`、`1:3` 这类 A1 区域，来源工作表通过 `--source-sheet-id` 单独指定；不接受工作表前缀、公式或多区域。SourceRange 颜色写入暂不支持。
- **结构操作行为**：已验证的工作表重命名、在引用前插入行/列、删除引用前的行会自动调整引用并保持 `valid`；已验证的 `move-dimension` 场景会使其变为 `invalid`。列删除、删除整个来源区域或来源工作表等场景未覆盖，不能预设结果；结构操作后先回读 `sourceRangeStatus`，仅在 `invalid` 时重新选择来源并写入。
### 获取下拉列表配置
```
Usage:
dws sheet get-dropdown [flags]
Example:
dws sheet get-dropdown --node <NODE_ID> --sheet-id <SHEET_ID> --range "A2:A100"
dws sheet get-dropdown --node <NODE_ID> --sheet-id <SHEET_ID> --range "A1"
Flags:
--node string 表格文档 ID 或 URL (必填)
--sheet-id string 工作表 ID 或名称 (必填)
--range string 查询范围，A1 表示法，如 A1:A100 (必填)
```
查询指定范围内的下拉列表配置信息。
- **用途**：查看单元格已设置的下拉列表选项和配置。
- **场景**：在修改下拉列表前先查询现有配置；确认下拉列表是否设置成功。
- **返回**：`dataValidations` 按相同配置分组。Inline 组返回 `sourceType:"inline"`、`conditionValues`、`ranges` 和 `options`；SourceRange 组始终返回 `sourceType:"sourceRange"`、`sourceRangeStatus:"valid"/"invalid"`、`enableMultiSelect` 和 `ranges`，仅在 `sourceRangeStatus:"valid"` 时返回 `sourceRange:{sheetId,a1Notation}`。`invalid` 时仍保留配置组，但省略 `sourceRange`，不得依赖旧坐标修复。SourceRange 不会展开候选值，因此不返回 `conditionValues`、`options` 或颜色。范围内无下拉列表时 `hasDropdown` 为 false。
### 删除下拉列表
```
Usage:
dws sheet delete-dropdown [flags]
Example:
dws sheet delete-dropdown --node <NODE_ID> --sheet-id <SHEET_ID> --range "A2:A100"
dws sheet delete-dropdown --node <NODE_ID> --sheet-id <SHEET_ID> --range "B1:D10"
Flags:
--node string 表格文档 ID 或 URL (必填)
--sheet-id string 工作表 ID 或名称 (必填)
--range string 要删除下拉列表的范围，A1 表示法 (必填)
```
删除指定范围内的下拉列表配置，单元格恢复为普通文本格式。
- **用途**：移除不再需要的下拉列表约束。
- **注意**：已填写的单元格值不会被清除；目标范围不存在下拉列表时操作仍返回成功。
## 上下文传递
| 操作 | 从返回中提取 | 用于 |
|------|-------------|------|
| `set-dropdown` | `range` 实际设置范围、`enableMultiSelect` 是否多选；仅 Inline 模式返回 `optionCount` | 确认下拉列表设置成功 |
| `get-dropdown` | `hasDropdown`、`dataValidations`；按 `sourceType` 区分 Inline 与 SourceRange | 查看已有下拉配置 |
| `delete-dropdown` | `range` 实际删除范围 | 确认下拉列表删除完成 |
| `list` | 工作表的 `sheetId` | info / range read / range update / find 的 --sheet-id |
## 注意事项
- ★ **`--sheet-id` 获取规范（强制）**：`sheetId` 未知时必须先通过 `dws sheet list --node <NODE_ID> --format json` 查询，禁止凭空编造（如臆测为 `Sheet1`、`sheet1`、`0`、`default` 等）
- `set-dropdown` 的 Inline 模式使用 `--options`，每个元素包含 `value`（必填）和 `color`（可选，`#RRGGBB`）；SourceRange 模式使用 `--source-sheet-id` + `--source-range`。两种模式均可用 `--multi-select`，并会覆盖目标范围已有下拉
- SourceRange 在已验证的重命名、引用前插入行/列、删除引用前行的场景会自动调整；已验证的 `move-dimension` 会使其变为 `invalid`。其他未覆盖删除/移动场景后先回读，仅 `invalid` 时重新选源写入；颜色写入暂不支持
- `get-dropdown` 查询指定范围内的下拉配置，并按相同配置分组。SourceRange 即使无效也保留一组并以 `sourceRangeStatus:"invalid"` 表示，但省略 `sourceRange`，不回退展开候选值
- `delete-dropdown` 删除指定范围内的下拉列表配置，单元格恢复为普通文本格式。已填写的值不会被清除。目标范围不存在下拉列表时操作仍返回成功
.agents/skills/dingtalk-misc/references/sheet/sheet-export.md
+135
View File
@@ -0,0 +1,135 @@
# 导出 (export)
## 使用场景
### 导出
用户说"导出/下载xlsx/存为Excel/存成表格文件/把表格变成xlsx/导出表格/下载表格/导出为 excel":
- 导出表格 → `export`（单命令会自动等待完成，并可选下载）
- 仅需传 `--node`，可选 `--output` 指定本地文件/目录（不传则返回 downloadUrl）
- 需要落盘到本地 → `dws sheet export --node <NODE_ID> --output <path>`，命令自动下载 xlsx
- 禁止用 `range read` 全量读取后自行拼接 xlsx 来模拟导出；必须使用 `export`，才能保留格式、合并和公式等属性
- 禁止在 AI Agent 侧实现轮询或重试；命令会自动等待结果，最长约 5 分钟
用户说"导出 CSV/存成 csv/导出这个工作表为 csv":
- 导出单个工作表为纯 CSV → `export-csv`（**同步**，不走异步任务；与 `export` 是两条独立命令）
- 用 `--sheet-id` 指定工作表（不传取第一个）、`--range` 限定范围、`--value-render-option` 选取值模式
- 不传 `--output` 时 CSV 正文打印到 stdout，可直接管道处理
## 命令详细参考
### 导出表格为 xlsx（异步任务一站式）
```
Usage:
dws sheet export [flags] # 一站式：提交 → 轮询 → 可选下载
Example:
# 仅导出，返回 downloadUrl（链接有时效性，请尽快下载）
dws sheet export --node <NODE_ID>
dws sheet export --node "https://alidocs.dingtalk.com/i/nodes/<DOC_UUID>"
# 导出并自动下载为本地文件
dws sheet export --node <NODE_ID> --output ./report.xlsx
# --output 为目录时，自动按下载链接中的文件名保存
dws sheet export --node <NODE_ID> --output ./
Flags:
--node string 表格文档 ID 或 URL (必填)
--output string 本地保存路径（可选，支持文件路径或目录）
```
将钉钉在线电子表格导出为 Office xlsx 格式。**单命令一站式**：命令会自动等待导出完成，并在指定 `--output` 时保存到本地。AI Agent 无需拆分步骤或自行轮询；最长等待约 5 分钟，超时后按命令错误处理。
**命令返回**：
- `--output` 未指定：进度日志 + 末尾输出 `jobId` 和 `downloadUrl`（链接有时效性，请尽快下载）
- `--output` 指定为文件路径：下载到该路径并输出 `导出完成: <path>`
- `--output` 指定为已存在目录：自动从 `downloadUrl` 推断文件名并保存到该目录下
**失败处理**：
- 导出任务返回 `FAILED`：命令立即返回错误并附带失败原因，**禁止自动重试 `dws sheet export`**，告知用户稍后再试
- 轮询 30 次仍 `PROCESSING`：命令返回超时错误，告知用户稍后再试
**限制**：仅支持钉钉在线电子表格（axls）→ xlsx。导出钉钉文字文档请使用 `doc` 产品对应的导出工具。
### 导出单个工作表为纯 CSV（同步）
```
Usage:
dws sheet export-csv [flags]
Example:
dws sheet export-csv --node <NODE_ID>
dws sheet export-csv --node <NODE_ID> --sheet-id <SHEET_ID> --output ./data.csv
dws sheet export-csv --node <NODE_ID> --range A1:Z1000 --value-render-option raw_value
Flags:
--node string 表格文档 ID 或 URL (必填)
--sheet-id string 工作表 ID 或名称（不传则第一个工作表）
--range string 导出范围，A1 表示法（不传则整表；大表可用此分块导出）
--value-render-option string 取值模式: formatted_value(默认) / raw_value / formula
--output string 本地保存路径（可选，支持文件路径或目录）；不传则输出到 stdout
--allow-truncated 允许数据被截断时仍然导出。默认截断即报错且不写文件
```
同步读取**单个**工作表并输出 RFC4180 CSV，不走异步导出任务。与 `export` 是两条独立命令：`export` 导整篇工作簿的 xlsx（异步提交+轮询），`export-csv` 只导一个工作表的纯值（一次请求即返回）。不传 `--output` 时 CSV 正文打印到 stdout，可直接管道处理。
**`--output` 落盘是原子替换**：CSV 先写同目录临时文件、成功后再替换目标，写入失败时已有文件保持原样（父目录不存在仍按错误处理，不会自动创建）。`--output` 指向已存在目录时保存为该目录下的 `sheet-export.csv`。
**超大表默认 fail-closed**：数据超出单次读取上限（服务端返回 `hasMore`）时，命令**直接报错并以非 0 退出，既不打印 CSV 也不写文件**（已存在的目标文件不会被截断数据覆盖）。处理方式：
- 用 `--range` 分块导出（如 `--range A1:Z1000`、`A1001:Z2000` …）
- 改用 `dws sheet export` 导出完整表格的 xlsx
- 确认可以接受不完整数据时，显式加 `--allow-truncated`；此时才会照常输出/落盘，并在 stderr 给出「已被截断」警告，成功提示也会写明"数据已截断，不是完整表格"
```bash
# 落盘到本地
dws sheet export-csv --node <NODE_ID> --sheet-id <SHEET_ID> --output ./data.csv
# 输出到 stdout 便于管道处理
dws sheet export-csv --node <NODE_ID> --sheet-id <SHEET_ID>
# 大表分块导出（避免截断；不分块时默认会因截断而报错）
dws sheet export-csv --node <NODE_ID> --sheet-id <SHEET_ID> --range "A1:Z1000" --output ./part1.csv
# 明确接受不完整数据（否则截断即失败）
dws sheet export-csv --node <NODE_ID> --sheet-id <SHEET_ID> --allow-truncated --output ./partial.csv
```
注意：CSV 只写纯值，不保留样式/合并/公式；需要完整属性请用 `dws sheet export` 导 xlsx。只是让 Agent 读取内容（带 `[row=N]` 行号前缀）请用 `dws sheet csv-get`。
## 核心工作流
```bash
# ── 工作流 12: 导出表格为 xlsx（单命令一站式）──
# 场景 A：仅获取下载链接（命令自动等待完成并返回 downloadUrl）
dws sheet export --node <NODE_ID> --format json
# 传入 URL 也可：
# dws sheet export --node "https://alidocs.dingtalk.com/i/nodes/<DOC_UUID>" --format json
# 场景 B：导出并自动下载为本地文件
dws sheet export --node <NODE_ID> --output ./report.xlsx
# 场景 C：下载到目录，自动按链接推断文件名
dws sheet export --node <NODE_ID> --output ./
# 禁止在 Agent 侧实现任何轮询或重试；命令会自动等待结果。
# 若命令返回失败或超时，直接告知用户稍后再试，不要自动重调 dws sheet export。
```
## 上下文传递
| 操作 | 从返回中提取 | 用于 |
|------|-------------|------|
| `export` | `downloadUrl`（未指定 --output）/ `outputPath`（指定 --output） | 直接下发给用户或告知文件已保存到本地；不要再调用其他 export 相关命令 |
| `export` 超时中断 | 错误信息 | 直接报告失败或超时；当前没有独立续查命令，不自动重新提交导出 |
| `export-csv` | CSV 正文（未指定 --output，走 stdout）/ `导出完成: <path>`（指定 --output） | 直接把 CSV 交给下游处理，或告知文件已保存到本地。命令是同步的，无任务/轮询概念 |
## 注意事项
- ★ `export` 仅支持钉钉在线电子表格（axls）→ xlsx；传入钉钉文字文档会报 `invalidRequest.document.typeIllegal`
- ★ `export` 为单命令一站式，会自动等待结果并可选下载；**Agent 不得自行轮询或重试**，命令返回成功后不再调用其他 export 相关命令
- `export` 内置轮询策略：1~5 次间隔 2s、6~10 次间隔 5s、11~20 次间隔 10s、21~30 次间隔 15s，硬上限 30 次（约 5 分钟）；超时后命令返回错误，告知用户稍后再试即可
- ★ `export` 命令返回失败或超时时，**禁止自动重调 `dws sheet export`**；直接告知用户导出失败并建议稍后再试
- `export` 未指定 `--output` 时，返回的 `downloadUrl` 具有时效性，获取后请尽快下载；若用户需要本地文件，优先直接传 `--output` 让 CLI 代为下载
- `export` 的 `--output` 可为文件路径或已存在目录；为目录时自动从 `downloadUrl` 推断文件名，为文件路径时直接按该路径保存
- 用户要求"导出表格/下载 xlsx"时，必须使用 `export` 单命令，禁止用 `range read` 读全量数据后自行拼 xlsx 模拟导出；`export` 会保留格式、合并、公式等属性
- `export-csv` 与 `export` 是两条独立命令：`export-csv` 同步导出**单个**工作表的纯值 CSV，不保留样式/合并/公式；要整篇工作簿或完整属性一律用 `export`
- ★ `export-csv` 遇到数据超出单次读取上限时默认报错、既不输出也不写文件；优先用 `--range` 分块导出，只有用户明确接受不完整数据时才加 `--allow-truncated`
.agents/skills/dingtalk-misc/references/sheet/sheet-filter-view.md
+51
View File
@@ -0,0 +1,51 @@
# Sheet 筛选视图
## 边界与上下文
筛选视图是命名的个人视角，不改变原始数据，也不影响其他协作者；用户只说“筛选”且要求所有人看到时，默认进入全局 `sheet filter`，明确说“筛选视图/个人视图”才进入本阶段。所有命令要求当前任务真实 nodeId、sheetId；filterViewId 必须来自本次 list/create 返回。未知 sheetId 时只调用一次 +list-sheets 并向后复用。
column 是相对筛选视图 range 首列的 0 起始偏移，不是工作表绝对列号。例如视图从 C 列开始，column=0 指 C 列。视图 range 应包含表头行，否则筛选显示和列语义容易错位。
## 命令闭环
列出或查看：
dws sheet filter-view list --node <NODE_ID> --sheet-id <SHEET_ID> --format json
dws sheet filter-view info --node <NODE_ID> --sheet-id <SHEET_ID> --filter-view-id <FILTER_VIEW_ID> --format json
创建带条件的视图：
dws sheet filter-view create --node <NODE_ID> --sheet-id <SHEET_ID> --name "高销售额视图" --range "A1:E100" --criteria '[{"column":0,"filterType":"values","visibleValues":["销售部"]},{"column":2,"filterType":"condition","conditions":[{"operator":"greater","value":"50000"}]}]' --format json
criteria 是数组，支持三类：
- values：visibleValues 指定可见值。
- condition：conditions 最多 2 项，比较值用字符串；conditionOperator 取 and（默认）或 or。operator 必须使用 kebab-case：equal、not-equal、contains、not-contains、starts-with、not-starts-with、ends-with、not-ends-with、greater、greater-equal、less、less-equal。
- color：backgroundColor 与 fontColor 二选一；“标红/高亮”默认指背景色，只有明确说字体颜色时才用 fontColor。
不在上述枚举中的 operator 不得猜测；确有其他需求时只读取 filter-view create/update-criteria 的 compact Schema。
更新单列条件：
dws sheet filter-view update-criteria --node <NODE_ID> --sheet-id <SHEET_ID> --filter-view-id <FILTER_VIEW_ID> --column 2 --filter-criteria '{"filterType":"condition","conditions":[{"operator":"greater","value":"100"}]}' --format json
查看或删除条件：
dws sheet filter-view list-criteria --node <NODE_ID> --sheet-id <SHEET_ID> --filter-view-id <FILTER_VIEW_ID> --format json
dws sheet filter-view get-criteria --node <NODE_ID> --sheet-id <SHEET_ID> --filter-view-id <FILTER_VIEW_ID> --column 2 --format json
dws sheet filter-view delete-criteria --node <NODE_ID> --sheet-id <SHEET_ID> --filter-view-id <FILTER_VIEW_ID> --column 2 --format json
delete-criteria 只清除一列条件并保留视图；对不存在的条件是幂等成功，但仍按删除类操作先确认。get-criteria 查询未设置条件的列会报错；list-criteria 在没有条件时返回空对象，两者不能互换。
update 至少传 name/range/criteria 之一。criteria 只替换数组中明确指定列的条件，未指定列保持不变；update-criteria 精确替换一列。先 info/list-criteria 读取当前状态，只提交用户要求的变化，不能用空 criteria 猜测“清空全部”。
## 删除与验证
delete 会永久删除整个筛选视图及其条件。先展示名称、filterViewId、range，得到明确同意后才加 --yes：
dws sheet filter-view delete --node <NODE_ID> --sheet-id <SHEET_ID> --filter-view-id <FILTER_VIEW_ID> --yes --format json
create/update/update-criteria/delete-criteria 后用 info 或 list-criteria 验证；delete 后用 list 验证对象消失。空列表只有在命令明确成功且 envelope 完整时才是真空结果；非零、坏 JSON 或缺字段必须报错。
.agents/skills/dingtalk-misc/references/sheet/sheet-filter.md
+181
View File
@@ -0,0 +1,181 @@
# 全局筛选 (filter)
## 使用场景
### 筛选视图
用户说"筛选/过滤/只看某些值/只显示满足条件的行/筛选数据/创建筛选/删除筛选/设置筛选条件/清除筛选/排序":
- 查看当前筛选 → `filter get`
- 创建筛选 → `filter create`
- 删除筛选 → `filter delete`
- 批量设置多列条件 → `filter update`
- 清除某一列条件 → `filter clear-criteria`
- 按列排序 → `filter sort`
- **区分全局筛选与筛选视图**：如果用户说"筛选视图"则走 `filter-view` 系列；如果只说"筛选/过滤/只看"则默认走全局 `filter` 系列
- **禁止替代方案**：当用户要求"筛选/只看/仅保留某些行"时，必须通过 `filter create` / `filter update` 创建真实的筛选器。禁止用"删除不符合条件的行"或"新建工作表只放符合条件的行"来代替——这些做法会让原数据丢失或不可恢复
## 命令详细参考
### 获取筛选信息
```
Usage:
dws sheet filter get [flags]
Example:
dws sheet filter get --node <NODE_ID> --sheet-id <SHEET_ID>
dws sheet filter get --node "https://alidocs.dingtalk.com/i/nodes/<DOC_UUID>" --sheet-id "Sheet1"
Flags:
--node string 表格文档 ID 或 URL (必填)
--sheet-id string 工作表 ID 或名称 (必填)
```
获取指定工作表的全局筛选信息，返回筛选范围和各列的筛选条件详情。
- **用途**：查看当前工作表上是否存在全局筛选及其配置。
- **场景**：在修改或删除筛选前，先读取当前筛选配置；创建筛选前先确认是否已存在（每个工作表只能有一个筛选）。
- **区分**：全局筛选（filter）影响所有协作者看到的数据展示；筛选视图（filter-view）是个人化的。
- **返回**：`range`（筛选范围，A1 表示法）和 `columnFilterCriteria`（各列条件，key 为列偏移量）。如果未设置筛选，返回筛选信息为空。
### 创建筛选
```
Usage:
dws sheet filter create [flags]
Example:
# 创建筛选框架（不设条件）
dws sheet filter create --node <NODE_ID> --sheet-id <SHEET_ID> --range "A1:E100"
# 创建筛选并同时设置条件（按值筛选）
dws sheet filter create --node <NODE_ID> --sheet-id <SHEET_ID> --range "A1:E100" --criteria '[{"column":1,"filterType":"values","visibleValues":["北京","上海"]}]'
# 创建筛选并设置条件筛选
dws sheet filter create --node <NODE_ID> --sheet-id <SHEET_ID> --range "A1:E100" --criteria '[{"column":2,"filterType":"condition","conditions":[{"operator":"greater","value":"100"}]}]'
Flags:
--node string 表格文档 ID 或 URL (必填)
--sheet-id string 工作表 ID 或名称 (必填)
--range string 筛选范围，A1 表示法，须包含表头行 (必填)
--criteria string 筛选条件 JSON 数组 (可选)
```
在工作表中创建全局筛选。
- **用途**：为工作表建立筛选器，使数据可按条件过滤展示。
- **约束**：每个工作表只能有一个全局筛选，已存在时会报错。应先 `filter get` 确认不存在后再创建。
- **range 规范**：必须包含表头行（如 `A1:E100`），不能只包含数据行。
- **criteria 格式**：JSON 数组，每个元素含 `column`（列偏移量，从 0 开始）和筛选条件字段。不传则仅创建空筛选框架，后续可通过 `filter update` 设置条件。
### 删除筛选
> **CAUTION:** 不可逆操作 — 执行前必须向用户确认。
```
Usage:
dws sheet filter delete [flags]
Example:
dws sheet filter delete --node <NODE_ID> --sheet-id <SHEET_ID> --yes
Flags:
--node string 表格文档 ID 或 URL (必填)
--sheet-id string 工作表 ID 或名称 (必填)
```
删除工作表的全局筛选。
- **用途**：移除筛选器，所有被隐藏的行将重新显示。
- **不可逆**：删除后所有筛选条件丢失，需重新创建。
- **前置**：工作表没有筛选时调用会报错，应先 `filter get` 确认存在。
### 批量更新筛选条件
```
Usage:
dws sheet filter update [flags]
Example:
# 同时设置多列的筛选条件
dws sheet filter update --node <NODE_ID> --sheet-id <SHEET_ID> --criteria '[{"column":0,"filterType":"values","visibleValues":["已完成","进行中"]},{"column":2,"filterType":"condition","conditions":[{"operator":"greater","value":"50"}]}]'
# 按颜色筛选
dws sheet filter update --node <NODE_ID> --sheet-id <SHEET_ID> --criteria '[{"column":1,"filterType":"color","backgroundColor":"#FF0000"}]'
Flags:
--node string 表格文档 ID 或 URL (必填)
--sheet-id string 工作表 ID 或名称 (必填)
--criteria string 筛选条件 JSON 数组 (必填)
```
批量更新筛选条件，可同时设置多列的筛选条件。
- **用途**：一次性设置或替换多列的筛选条件。
- **前置**：工作表必须已创建筛选（通过 `filter create`）。
- **覆盖式**：指定列的条件会被替换，未指定的列保持不变。如只想修改某一列，建议先 `filter get` 读取现有配置。
- **criteria 格式**：JSON 数组，支持三种 `filterType`：
- `values`：按值筛选，指定 `visibleValues` 数组
- `condition`：按条件筛选，指定 `conditions` 数组（最多 2 个）和可选的 `conditionOperator`（`and`/`or`）
- `color`：按颜色筛选，指定 `backgroundColor` 或 `fontColor`（二选一）
### 清除单列筛选条件
```
Usage:
dws sheet filter clear-criteria [flags]
Example:
# 清除第 2 列（B 列）的筛选条件
dws sheet filter clear-criteria --node <NODE_ID> --sheet-id <SHEET_ID> --column 1
# 清除第 1 列（A 列）的筛选条件
dws sheet filter clear-criteria --node <NODE_ID> --sheet-id <SHEET_ID> --column 0
Flags:
--node string 表格文档 ID 或 URL (必填)
--sheet-id string 工作表 ID 或名称 (必填)
--column number 列偏移量，从 0 开始 (必填)
```
清除筛选中某一列的筛选条件。
- **用途**：移除某列的筛选条件，该列不再参与筛选计算。
- **区分**：仅清除指定列的条件，不删除整个筛选。如需删除整个筛选，使用 `filter delete`。
- **幂等**：指定列没有设置筛选条件时调用不会报错。
### 筛选排序
```
Usage:
dws sheet filter sort [flags]
Example:
# 按第 1 列（A 列）升序排序
dws sheet filter sort --node <NODE_ID> --sheet-id <SHEET_ID> --column 0 --ascending
# 按第 3 列（C 列）降序排序
dws sheet filter sort --node <NODE_ID> --sheet-id <SHEET_ID> --column 2 --ascending=false
Flags:
--node string 表格文档 ID 或 URL (必填)
--sheet-id string 工作表 ID 或名称 (必填)
--column number 排序列偏移量，从 0 开始 (必填)
--ascending 是否升序，默认 true (可选)
```
对筛选范围内的数据按指定列排序。
- **用途**：对数据行按某一列的值进行升序或降序排列。
- **前置**：工作表必须已创建筛选（通过 `filter create`）。
- **注意**：排序会实际改变工作表中数据行的物理顺序，不可撤销。
- **column**：列偏移量从 0 开始，相对于筛选范围首列。
## 上下文传递
| 操作 | 从返回中提取 | 用于 |
|------|-------------|------|
| `filter get` | `range`（筛选范围）、`columnFilterCriteria`（各列条件） | 查看当前筛选配置，确认筛选是否存在 |
| `filter create` | 筛选创建成功的确认 | 确认筛选已建立，后续可通过 `filter update` 设置条件 |
| `filter delete` | 删除成功的确认 | 确认筛选已删除 |
| `filter update` | 更新成功的确认 | 确认条件已设置 |
| `filter clear-criteria` | 清除成功的确认 | 确认指定列的条件已清除 |
| `filter sort` | 排序成功的确认 | 确认排序已完成 |
| `list` | 工作表的 `sheetId` | info / range read / range update / find 的 --sheet-id |
## 注意事项
- ★ **`--sheet-id` 获取规范（强制）**：`sheetId` 未知时必须先通过 `dws sheet list --node <NODE_ID> --format json` 查询，禁止凭空编造（如臆测为 `Sheet1`、`sheet1`、`0`、`default` 等）
- ★ **全局筛选（filter）与筛选视图（filter-view）的区别**：全局筛选影响所有协作者看到的数据展示，每个工作表最多一个；筛选视图是个人化的，互不影响。用户只说"筛选"时默认走 `filter` 系列
- `filter get` 获取工作表的全局筛选信息，返回 `range`（筛选范围）和 `columnFilterCriteria`（各列条件）。无筛选时返回空
- `filter create` 创建全局筛选时 `--range` 必须包含表头行（如 `A1:E100`），不能只包含数据行。每个工作表只能有一个筛选，已存在时报错
- `filter create` 的 `--criteria` 可选，不传则仅创建空筛选框架，后续通过 `filter update` 设置条件
- `filter delete` 删除后所有筛选条件丢失且所有被隐藏行重新显示，不可恢复
- `filter delete` 工作表没有筛选时调用会报错，应先 `filter get` 确认存在
- `filter update` 是覆盖式：指定列的条件会被替换，未指定的列保持不变。如只想修改某一列，建议先 `filter get` 读取现有配置再 patch
- `filter update` 前置：工作表必须已创建筛选
- `filter clear-criteria` 仅清除指定列的条件，不删除整个筛选。指定列无条件时不报错（幂等）
- `filter sort` 会实际改变数据行的物理顺序，不可撤销。前置：工作表必须已创建筛选
- ★ **筛选操作规范**：
- 当用户要求"筛选/只看/仅保留 X"时，**必须**通过 `filter create` / `filter update` 创建真实的筛选器。**禁止**用"删除不符合条件的行"或"新建工作表只放符合条件的行"来代替
- 创建/更新筛选后**必须** `filter get` 回读验证配置正确
- 更新已有筛选前先 `filter get` 读取当前配置，确认目标存在且了解现有条件后再操作
- 筛选条件的列索引（`column`）必须与实际数据列精确对应，不要凭猜测填写
- 筛选不支持正则表达式，传入正则会当成普通文本处理
.agents/skills/dingtalk-misc/references/sheet/sheet-formula.md
+192
View File
@@ -0,0 +1,192 @@
# 公式写入、回读与错误校验
## 使用场景
用户说"写公式/计算列/辅助列/总计/占比/增长率/查找计算/自动计算/校验公式/检查公式错误"时使用本页。
- 能由表内其他单元格推导的派生值，优先写公式，不要写一次性的静态结果。
- 写公式前先读表头和 3-5 行样本，确认列含义、数据类型、真实行号和目标范围。
- 用户明确要求"辅助列"时，需要真实写入辅助列公式；不要只用条件格式或本地计算绕过。
## 当前能力边界
- 写少量或需要单元格对象的公式：使用 `dws sheet range update`。
- 从 CSV/表格文本批量写公式：使用 `dws sheet csv-put`，字段值以 `=` 开头时默认按公式解析；如需写入以 `=` 开头的字面文本，在字段值前加单引号。
- 公式载体：公式写在 cell object 的 `text` 字段中，例如 `{"type":"text","text":"=SUM(B2:B10)"}`。
- 读取公式文本：使用 `dws sheet range read --value-render-option formula`。
- 读取计算结果：使用 `dws sheet range read --value-render-option raw_value` 或默认 `formatted_value`。
- 聚合错误校验：使用 `dws sheet formula-verify`，支持整本表格、单个目标和多个目标。
- `formula-verify` 扫描已经落表的公式计算结果，按 `#ERROR!` / `#NAME?` / `#DIV/0!` 等错误类型汇总；它不判断一个正常数值是否符合业务预期。
- `append` / `table-put` 不作为公式写入协议；需要公式时用 `range update` 或 `csv-put`。
## 命令选择
| 目的 | 命令 | 说明 |
|------|------|------|
| 写入少量或中等范围公式 | `range update` | `--values` 必须是二维 cell object，维度与 `--range` 完全一致 |
| 从 CSV/表格文本批量写公式 | `csv-put` | `=` 开头按公式；前导单引号写入以 `=` 开头的字面文本；不支持富格式对象 |
| 查看已写入的公式文本 | `range read --value-render-option formula` | 确认公式本身是否落表、范围和引用是否正确 |
| 查看公式计算结果 | `range read --value-render-option raw_value` | 用于数值对账、错误值检查 |
| 查看格式化展示结果 | `range read` 或 `csv-get` 默认模式 | 用于用户肉眼看到的展示值检查 |
| 扫描整本表格公式错误 | `formula-verify --node <NODE_ID>` | 不传目标时扫描全部工作表的非空范围 |
| 扫描单个工作表或范围 | `formula-verify --sheet-id ... [--range ...]` | `--range` 只传 A1 范围，不带工作表前缀 |
| 扫描多个目标 | `formula-verify --targets ...` | 必须是非空数组；每项为 `{"sheetId":"...","range":"..."}`，`range` 可省略 |
## 推荐流程
1. 用 `dws sheet list --node <NODE_ID> --format json` 获取真实 `sheetId`。
2. 用 `range read` 或 `csv-get` 读取表头和样本数据，确认目标列与行号。
3. 明确相对引用和绝对引用：向下填充时检查固定汇率、税率、查找表、标题行是否需要 `$` 锁定。
4. 按数据形态写入公式：精确 cell object 用 `range update`，CSV/表格文本用 `csv-put`。`range update` 的矩阵行列数必须与 `--range` 完全一致。
5. 用 `range read --value-render-option formula` 回读公式文本，确认实际公式、范围和引用。
6. 对本次写入目标运行 `formula-verify`；若返回 `partial` / `hasMore=true`，缩小目标或提高 `--max-cells` 后继续扫描，直到结果完整。
7. 用 `range read --value-render-option raw_value` 抽样对账业务数值；正常数值不会被 `formula-verify` 判定为业务计算错误。
8. 若发现错误，先定位依赖单元格、空值、除数为 0、引用范围越界或函数名错误，再重写公式并重新执行文本回读、错误扫描和数值抽样。
## 聚合式公式校验
### 整本表格
不指定 `--sheet-id`、`--range` 或 `--targets` 时，扫描整本表格的全部工作表：
```bash
dws sheet formula-verify --node <NODE_ID> --format json
```
### 单个工作表或范围
`--sheet-id` 支持工作表 ID 或名称；省略 `--range` 时扫描该工作表的非空范围：
```bash
dws sheet formula-verify --node <NODE_ID> --sheet-id <SHEET_ID> --format json
dws sheet formula-verify --node <NODE_ID> --sheet-id <SHEET_ID> \
--range "D2:D100" --format json
```
`--range` 必须和 `--sheet-id` 一起使用，且只传 `D2:D100` 这类 A1 范围，不能传 `Sheet1!D2:D100`。
### 多个目标
```bash
dws sheet formula-verify --node <NODE_ID> \
--targets '[{"sheetId":"Sheet1","range":"D2:D100"},{"sheetId":"Summary"}]' \
--format json
```
`--targets` 也支持 `@targets.json` 和 `-`（stdin）。数组必须至少包含一个目标，不能传 `[]`；每项只允许非空 `sheetId` 和可选的字符串 `range`，`range` 只写 A1 范围且不能带工作表前缀。使用 `--targets` 时不能再传 `--sheet-id` 或 `--range`。
### 扫描限制与自动化
```bash
dws sheet formula-verify --node <NODE_ID> \
--max-locations-per-error 20 --max-cells 30000 --format json
dws sheet formula-verify --node <NODE_ID> --exit-on-error --format json
```
- `--max-locations-per-error` 只限制每类错误返回的 `locations` 和 `samples` 数量，`count` 与 `totalErrors` 仍保留实际扫描到的总数。
- `--max-cells` 是本次调用跨全部 targets 共享的扫描预算；预算不足时返回 `status=partial`、`hasMore=true`。
- `--exit-on-error` 适合 CI/自动化：发现公式错误时打印 JSON 结果并返回非 0；`partial` 结果中已经发现错误时同样返回非 0。
### 结果判定
| 字段 | 含义 |
|------|------|
| `status` | `success` / `errors_found` / `partial` |
| `totalErrors` | 实际扫描到的错误公式单元格总数 |
| `totalFormulas` | 实际扫描到的公式单元格总数 |
| `scannedCells` | 实际扫描的单元格数 |
| `hasMore` | `true` 表示结果不完整，不能据此声称目标范围零错误 |
| `errorSummary` | 按错误类型聚合的 `count`、`locations` 和 `samples` |
| `warningMessage` | `partial` 等情况下的扫描限制提示 |
判定规则：
- `status=success`、`hasMore=false`、`totalErrors=0`：本次目标范围未发现公式错误。
- `status=errors_found`：按 `errorSummary` 修复后重新校验。
- `status=partial` 或 `hasMore=true`：当前结果不完整；缩小 targets/range 或提高 `--max-cells` 后继续校验。
## 写入示例
### 单格公式
```bash
dws sheet range update --node <NODE_ID> --sheet-id <SHEET_ID> --range "D2" \
--values '[[{"type":"text","text":"=B2*C2"}]]' --format json
```
### 整列公式
```bash
dws sheet range update --node <NODE_ID> --sheet-id <SHEET_ID> --range "D2:D5" \
--values '[
[{"type":"text","text":"=B2*C2"}],
[{"type":"text","text":"=B3*C3"}],
[{"type":"text","text":"=B4*C4"}],
[{"type":"text","text":"=B5*C5"}]
]' --format json
```
### 含绝对引用
税率在 `G1` 时，向下填充应锁定税率单元格：
```bash
dws sheet range update --node <NODE_ID> --sheet-id <SHEET_ID> --range "E2:E5" \
--values '[
[{"type":"text","text":"=D2*$G$1"}],
[{"type":"text","text":"=D3*$G$1"}],
[{"type":"text","text":"=D4*$G$1"}],
[{"type":"text","text":"=D5*$G$1"}]
]' --format json
```
## 公式文本与结果回读
### 1. 回读公式文本
```bash
dws sheet range read --node <NODE_ID> --sheet-id <SHEET_ID> --range "D2:D5" \
--value-render-option formula --format json
```
检查点：
- `value` 应返回以 `=` 开头的公式文本。
- 行号、列号、相对引用、绝对引用应与写入计划一致。
- 无公式的单元格在 `formula` 模式下可能回退为原始值，不能把这种回退误判为公式已写入。
### 2. 回读计算结果
```bash
dws sheet range read --node <NODE_ID> --sheet-id <SHEET_ID> --range "D2:D5" \
--value-render-option raw_value --format json
```
检查点：
- 数值结果应与样本手算或本地复算一致。
- 检查结果中是否出现 `#REF!` / `#DIV/0!` / `#VALUE!` / `#NAME?` / `#NULL!` / `#NUM!` / `#N/A`。
- 对大范围公式，至少抽样检查首行、末行、边界行和异常数据行；用户要求全量处理时，应分批回读并断言处理数量。
### 3. 数值正确性边界
`formula-verify` 负责聚合已经落表的公式错误值；`range read` 负责确认实际公式文本和具体计算结果。即使 `formula-verify` 返回 `success`，也仍需对金额、比例、汇率、边界行等关键业务结果做 `raw_value` 抽样对账，因为一个公式可能计算出合法数值但业务逻辑仍然写错。
## 常见错误
- 想用 `csv-put` 写入 `=SUM(...)` 文本却忘记加前导单引号，导致内容被解析为公式。
- 用原始二维数组 `--values '[["=B2*C2"]]'`，而不是 cell object。
- 写整列公式时只写第一行，忘记把 `--range` 和 `--values` 扩成同样行数。
- 复制公式时没有锁定固定引用，例如税率、汇率、查找表范围。
- 没有回读 `formula` 模式，只看写入返回 `success`。
- 只回读展示值，不运行 `formula-verify` 聚合扫描错误。
- 把 `max-locations-per-error` 误解为错误计数上限；它只截断位置和样本。
- 看到 `status=partial` 或 `hasMore=true` 仍声称整本表公式零错误。
- 在 `--range` 中传 `Sheet1!A1:D10`，或把 `--targets` 与 `--sheet-id` 混用。
- 显式传空的 `--targets '[]'`；这不是“无目标”，应改为至少一个目标，整本扫描则完全省略 `--targets`。
## 关联文档
- [sheet-write-data](./sheet-write-data.md)：`range update` 的 `--values` cell object 结构、维度校验、富格式能力。
- [sheet-read-data](./sheet-read-data.md)：`value-render-option` 的 `formatted_value` / `raw_value` / `formula` 读取模式。
- [sheet-conditional-format](./sheet-conditional-format.md)：条件格式中的 `formulaCondition` 与辅助列公式的职责边界。
.agents/skills/dingtalk-misc/references/sheet/sheet-import.md
+76
View File
@@ -0,0 +1,76 @@
# 导入本地表格（import）
## 使用场景
用户说“导入 Excel”“把 xlsx 变成在线表格”“上传本地表格并在线编辑”时，使用 Agent 可发现入口 `dws sheet import create`。它只新建在线电子表格，不覆盖已有表格。旧入口 `dws sheet import` 继续兼容人工调用。
- 支持本地 `xlsx` / `xls`，文件上限 20MB
- `--folder-token` 与 `--workspace` 至少提供一个
- `import create` 会自动上传文件、确认转换并等待结果，Agent 不要自行拆分或重试
- `drive upload` 只上传二进制文件，不会转换为可编辑的在线表格，不能替代本命令
## 命令
```bash
# 导入到指定文件夹
dws sheet import create \
--file ./quote.xlsx \
--folder-token <FOLDER_TOKEN> \
--format json
# 导入到指定知识库，并自定义名称
dws sheet import create \
--file ./report.xls \
--workspace <WORKSPACE_ID> \
--name "月度报表" \
--format json
# 导入超时或中断后续查
dws sheet import get --task-id <TASK_ID> --format json
```
公开参数：
| 命令 | 参数 | 说明 |
|------|------|------|
| `sheet import create` | `--file` | 本地 xlsx/xls 文件（必填） |
| `sheet import create` | `--folder-token` | 目标文件夹 ID 或 URL，与 `--workspace` 至少传一个 |
| `sheet import create` | `--workspace` | 目标知识库 ID 或 URL，与 `--folder-token` 至少传一个 |
| `sheet import create` | `--name`, `-n` | 导入后的名称；默认取文件名并去掉扩展名 |
| `sheet import get` | `--task-id` | 导入任务 ID |
## 返回与续查
成功时返回：
```json
{
"success": true,
"taskId": "<TASK_ID>",
"documentUrl": "<DOCUMENT_URL>",
"documentName": "月度报表",
"documentType": "1",
"nodeId": "<NODE_ID>"
}
```
轮询达到上限时命令以退出码 0 返回业务态，避免 Agent 重复创建文档：
```json
{
"success": false,
"timed_out": true,
"taskId": "<TASK_ID>",
"status": "processing",
"next_command": "dws sheet import get --task-id <TASK_ID>"
}
```
检测到 `timed_out:true` 后，只执行 `next_command` 续查。不要重新执行 `sheet import create`。
## 边界
- 本命令接受的是本地文件路径；它把 xlsx/xls 转换成新的 axls 在线表格
- 已经存在于钉盘或文档中的 xlsx 节点不能直接传给工作表/单元格命令；先用 `drive download` 下载，需要在线编辑时再执行 `sheet import create`
- 向已有在线表格写数据应使用 `range update`、`append`、`csv-put` 或 `table-put`
- md/doc/docx 等文字文档导入使用 `dws doc import`
.agents/skills/dingtalk-misc/references/sheet/sheet-media-image.md
+263
View File
@@ -0,0 +1,263 @@
# 媒体上传与图片 (media & image)
## 使用场景
### 媒体上传
用户说"上传附件/传文件到表格/上传文件到表格/上传到表格":
- 上传附件 → `media-upload`（需表格 ID 或 URL + 本地文件路径）
- 用户指定了上传后的名称 → `media-upload --name "自定义名称"`
- `media-upload` 的 `--name` 参数用于指定附件在表格中显示的名称（不改变本地文件名）；不传时默认使用本地文件名
用户说"写入图片/插入图片/加图片/放图片到单元格/嵌入图片到表格":
- 写入图片 → `write-image`（需表格 ID + 工作表 ID + 单元格范围 + 本地图片路径）
- 禁止使用 `range update` 写入图片；图片对象必须使用 `write-image` 命令
- 用户指定了图片尺寸 → `write-image --width N --height M`
### 浮动图片
用户说"浮动图片/悬浮图片/在表格上放一张图/加个浮动的图":
- 创建浮动图片 → `create-float-image --file <本地图片>`；已有 `resourceUrl` 时可改用 `--src`
- 浮动图片悬浮于单元格之上，不占用单元格内容，与 `write-image`（写入单元格内部的图片）不同
用户说"查看浮动图片/有哪些浮动图片/浮动图片列表":
- 列出所有浮动图片 → `list-float-images`
- 查看某个浮动图片详情 → `get-float-image`
用户说"移动浮动图片/调整浮动图片大小/修改浮动图片/更新浮动图片":
- 更新浮动图片属性 → `update-float-image`（可更新锚点位置、尺寸、偏移量、图片资源路径）
用户说"删除浮动图片/移除浮动图片":
- 删除浮动图片 → `delete-float-image`
关键区分：`write-image`（单元格内嵌图片，占据单元格内容）vs `create-float-image`（浮动图片，悬浮于单元格之上，不占内容）
## 命令详细参考
### 上传附件到表格
```
Usage:
dws sheet media-upload [flags]
Example:
dws sheet media-upload --node <NODE_ID> --file ./report.pdf
dws sheet media-upload --node <NODE_ID> --file ./data.bin --name "数据文件.dat" --mime-type application/octet-stream
Flags:
--node string 目标表格文档的标识，支持传入 URL 或 ID (必填)
--file string 本地文件路径 (必填)
--name string 附件显示名称 (默认使用文件名)
--mime-type string 文件 MIME 类型 (默认根据扩展名推断)
```
### 上传图片并写入表格单元格
```
Usage:
dws sheet write-image [flags]
Example:
dws sheet write-image --node <NODE_ID> --sheet-id <SHEET_ID> --range A1:A1 --file ./chart.png
dws sheet write-image --node <NODE_ID> --sheet-id <SHEET_ID> --range B2:B2 --file ./logo.png --width 200 --height 100
Flags:
--node string 目标表格文档的标识，支持传入 URL 或 ID (必填)
--sheet-id string 工作表 ID 或名称 (必填)
--range string 目标单元格区域地址，如 A1:A1 (必填)
--file string 本地图片文件路径 (必填)
--name string 图片显示名称 (默认使用文件名)
--mime-type string 文件 MIME 类型 (默认根据扩展名推断)
--width int 图片显示宽度 (可选)
--height int 图片显示高度 (可选)
```
### 创建浮动图片
```
Usage:
dws sheet create-float-image [flags]
Example:
# 直接上传本地图片并创建浮动图片
dws sheet create-float-image --node <NODE_ID> --sheet-id <SHEET_ID> \
--file ./chart.png --range A1 --width 400 --height 300
# 高级用法：先上传图片获取 resourceUrl
dws sheet media-upload --node <NODE_ID> --file ./chart.png
# 输出: resourceUrl: /core/api/resources/img/xxxx...
# 再创建浮动图片
dws sheet create-float-image --node <NODE_ID> --sheet-id <SHEET_ID> \
--src "/core/api/resources/img/xxxx..." --range A1 --width 400 --height 300
# 带偏移量
dws sheet create-float-image --node <NODE_ID> --sheet-id <SHEET_ID> \
--src "/core/api/resources/img/xxxx..." --range B2 --width 200 --height 150 --offset-x 10 --offset-y 20
Flags:
--node string 表格文档 ID 或 URL (必填)
--sheet-id string 工作表 ID 或名称 (必填)
--file string 本地图片文件路径，与 --src 二选一
--src string 图片资源路径，通过 media-upload 获取的 resourceUrl，与 --file 二选一
--range string 锚点单元格，A1 表示法，如 A1、B3 (必填)
--width int 图片宽度，像素，正整数 (必填)
--height int 图片高度，像素，正整数 (必填)
--offset-x int 水平偏移量，像素 (默认 0)
--offset-y int 垂直偏移量，像素 (默认 0)
```
浮动图片悬浮于单元格之上，不占用单元格内容，可自由定位和调整大小。
- `--file` 与 `--src` 必须且只能提供一个；`--file` 会在命令内完成凭证获取、文件上传和浮动图片创建
- `--src` 必须是 `media-upload` 返回的 `resourceUrl`（格式为 `/core/api/resources/img/...`），不能直接传外部 URL；需要自定义上传名称/MIME 时使用这个高级两步流程
- `--range` 使用 A1 表示法指定锚点单元格（如 `A1`、`B3`），支持带工作表前缀（如 `Sheet1!A1`）
- `--width` / `--height` 为必填，单位像素，必须为正整数
- `--offset-x` / `--offset-y` 表示相对锚点单元格左上角的偏移量（像素），默认 0，不能为负数
### 获取浮动图片详情
```
Usage:
dws sheet get-float-image [flags]
Example:
dws sheet get-float-image --node <NODE_ID> --sheet-id <SHEET_ID> --float-image-id <FI_ID>
Flags:
--node string 表格文档 ID 或 URL (必填)
--sheet-id string 工作表 ID 或名称 (必填)
--float-image-id string 浮动图片 ID (必填)
```
获取单个浮动图片的详细信息，包括 ID、图片资源路径、锚点位置、尺寸和偏移量。
`--float-image-id` 可通过 `list-float-images` 获取。
### 列出工作表所有浮动图片
```
Usage:
dws sheet list-float-images [flags]
Example:
dws sheet list-float-images --node <NODE_ID> --sheet-id <SHEET_ID>
Flags:
--node string 表格文档 ID 或 URL (必填)
--sheet-id string 工作表 ID 或名称 (必填)
```
列出指定工作表中所有浮动图片，返回 `floatImages` 数组和 `totalCount`。
### 更新浮动图片属性
```
Usage:
dws sheet update-float-image [flags]
Example:
# 移动浮动图片到新位置
dws sheet update-float-image --node <NODE_ID> --sheet-id <SHEET_ID> --float-image-id <FI_ID> --range C5
# 调整尺寸
dws sheet update-float-image --node <NODE_ID> --sheet-id <SHEET_ID> --float-image-id <FI_ID> --width 600 --height 400
# 直接用本地图片替换
dws sheet update-float-image --node <NODE_ID> --sheet-id <SHEET_ID> --float-image-id <FI_ID> \
--file ./replacement.png
# 高级用法：通过已上传的 resourceUrl 替换
dws sheet update-float-image --node <NODE_ID> --sheet-id <SHEET_ID> --float-image-id <FI_ID> \
--src "/core/api/resources/img/xxxx..."
Flags:
--node string 表格文档 ID 或 URL (必填)
--sheet-id string 工作表 ID 或名称 (必填)
--float-image-id string 浮动图片 ID (必填)
--file string 用于替换浮动图片的本地图片路径，与 --src 不能同时使用
--src string 新的图片资源路径，通过 media-upload 获取的 resourceUrl
--range string 新的锚点单元格，A1 表示法
--width int 新的图片宽度，像素
--height int 新的图片高度，像素
--offset-x int 新的水平偏移量，像素
--offset-y int 新的垂直偏移量，像素
```
更新浮动图片的属性，`--file` / `--src` / `--range` / `--width` / `--height` / `--offset-x` / `--offset-y` 至少传入一个；`--file` 与 `--src` 不能同时使用。
`--float-image-id` 可通过 `list-float-images` 获取。
### 删除浮动图片
```
Usage:
dws sheet delete-float-image [flags]
Example:
dws sheet delete-float-image --node <NODE_ID> --sheet-id <SHEET_ID> --float-image-id <FI_ID>
Flags:
--node string 表格文档 ID 或 URL (必填)
--sheet-id string 工作表 ID 或名称 (必填)
--float-image-id string 浮动图片 ID (必填)
```
删除指定的浮动图片，操作不可恢复。`--float-image-id` 可通过 `list-float-images` 获取。
## 核心工作流
```bash
# ── 工作流 9: 上传附件到表格 ──
# 1. 基本用法: 上传本地文件到表格
dws sheet media-upload --node <NODE_ID> --file ./report.pdf -f json
# 2. 自定义附件显示名称 (--name 指定上传后在表格中显示的名称)
dws sheet media-upload --node <NODE_ID> --file ./data.csv --name "销售数据.csv" -f json
# 3. 指定 MIME 类型 (文件扩展名无法推断时)
dws sheet media-upload --node <NODE_ID> --file ./data.bin --name "导出数据.dat" --mime-type application/octet-stream -f json
# 4. 完整流程: 创建表格 → 上传附件
dws sheet create --name "项目资料" -f json
# 提取 nodeId 后:
dws sheet media-upload --node <NODE_ID> --file ./design.pdf -f json
dws sheet media-upload --node <NODE_ID> --file ./timeline.xlsx --name "项目时间线.xlsx" -f json
# ── 工作流 10: 写入图片到表格单元格 ──
# 1. 基本用法: 写入图片到指定单元格
dws sheet write-image --node <NODE_ID> --sheet-id <SHEET_ID> --range A1:A1 --file ./chart.png -f json
# 2. 指定显示尺寸
dws sheet write-image --node <NODE_ID> --sheet-id <SHEET_ID> --range B2:B2 --file ./logo.png --width 200 --height 100 -f json
# 3. 自定义图片名称
dws sheet write-image --node <NODE_ID> --sheet-id <SHEET_ID> --range C3:C3 --file ./photo.jpg --name "产品图.jpg" -f json
# 4. 完整流程: 创建表格 → 写表头 → 写入图片
dws sheet create --name "产品目录" -f json
# 提取 nodeId 后，先用 list 获取真实 sheetId:
dws sheet list --node <NODE_ID> -f json
dws sheet range update --node <NODE_ID> --sheet-id <SHEET_ID> --range "A1:B1" \
--values '[[{"type":"text","text":"产品名称"},{"type":"text","text":"产品图片"}]]' -f json
dws sheet range update --node <NODE_ID> --sheet-id <SHEET_ID> --range "A2:A2" \
--values '[[{"type":"text","text":"MacBook Pro"}]]' -f json
dws sheet write-image --node <NODE_ID> --sheet-id <SHEET_ID> --range B2:B2 --file ./macbook.png --width 150 --height 100 -f json
# ── 工作流 11: 创建或替换浮动图片 ──
# 从本地图片直接创建
dws sheet create-float-image --node <NODE_ID> --sheet-id <SHEET_ID> \
--file ./chart.png --range A1 --width 400 --height 300 -f json
# 从本地图片直接替换已有浮动图
dws sheet update-float-image --node <NODE_ID> --sheet-id <SHEET_ID> \
--float-image-id <FI_ID> --file ./replacement.png -f json
```
## 上下文传递
| 操作 | 从返回中提取 | 用于 |
|------|-------------|------|
| `media-upload` | `resourceId`、`resourceUrl` | 附件已上传到表格；`resourceUrl` 可用于 `create-float-image` 的 `--src` |
| `write-image` | `resourceId` | 图片已写入指定单元格 |
| `create-float-image` | `floatImage`（含 `id`、`src`、`range`、`width`、`height`、`offsetX`、`offsetY`） | `id` 用于后续 get / update / delete 的 `--float-image-id` |
| `get-float-image` | `floatImage`（完整信息） | 查看单个浮动图片详情 |
| `list-float-images` | `floatImages` 数组、`totalCount` | 获取所有浮动图片的 `id`，用于后续操作 |
| `update-float-image` | `floatImage`（更新后的完整信息） | 确认更新结果 |
| `delete-float-image` | `message` | 确认删除完成 |
| `list` | 工作表的 `sheetId` | info / range read / range update / find 的 --sheet-id |
## 注意事项
- ★ **`--sheet-id` 获取规范（强制）**：`sheetId` 未知时必须先通过 `dws sheet list --node <NODE_ID> --format json` 查询，禁止凭空编造（如臆测为 `Sheet1`、`sheet1`、`0`、`default` 等）
- `media-upload` 会自动完成图片上传并返回后续命令需要的资源信息，无需手动拆分步骤
- `write-image` 会自动完成图片上传并写入目标单元格，无需手动拆分步骤
- ★ 向表格单元格中写入图片必须使用 `write-image`，禁止使用 `range update`。`range update` 不支持图片对象
- `write-image` 与 `media-upload` 的区别：`media-upload` 仅上传附件到表格获取 resourceId；`write-image` 在上传后还会将图片写入指定单元格
- `create-float-image --file` 可直接输入本地图片；仅在需要 `--name` / `--mime-type` 覆盖或复用既有资源时，先用 `media-upload` 获取 `resourceUrl` 再传 `--src`
- `create-float-image` 的 `--range` 使用 A1 表示法指定锚点单元格（如 `A1`、`B3`），支持带工作表前缀（如 `Sheet1!A1`）
- `create-float-image` 的 `--width` / `--height` 为必填，单位像素，必须为正整数；`--offset-x` / `--offset-y` 可选，默认 0，不能为负数
- `write-image`（单元格内嵌图片）vs `create-float-image`（浮动图片）：`write-image` 将图片写入单元格内部，占据单元格内容；`create-float-image` 创建悬浮于单元格之上的浮动图片，不占用单元格内容，可自由调整位置和大小
- ★ **浮动图片用 `create-float-image` 不用 `write-image`**：两者用途不同——`write-image` 写入单元格内部，`create-float-image` 创建悬浮于单元格之上的浮动图片；优先直接传 `--file`
- `update-float-image` 的 `--file` / `--src` / `--range` / `--width` / `--height` / `--offset-x` / `--offset-y` 至少必须提供一个，且 `--file` 与 `--src` 不能同时使用
- `list-float-images` 返回 `floatImages` 数组和 `totalCount`，每个元素包含 `id`（用于后续 get / update / delete）
- `delete-float-image` 操作不可恢复，删除后图片将从工作表中移除
.agents/skills/dingtalk-misc/references/sheet/sheet-pivot-table.md
+292
View File
@@ -0,0 +1,292 @@
# 透视表 (pivot-table)
## 真对象硬约束
当用户要求"透视表 / 分组汇总 / 交叉分析 / 按 X 统计 Y"时，**必须**通过 `pivot-table create` 创建真实的透视表对象。**禁止**用 `SUMIFS` / `COUNTIFS` 等普通公式 + `csv-put` 在原表中拼一张"看起来像透视表的汇总表"来代替——静态公式无法随源数据动态更新，且失去交互能力。判断标准：交付后 `pivot-table list` 必须能返回该对象。
## 使用场景
读写透视表对象。本 reference 覆盖 4 个命令：
| 操作需求 | 使用命令 | 说明 |
|---------|---------|------|
| 查看已有透视表 | `pivot-table list` | 获取透视表的结构、数据源和配置 |
| 创建透视表 | `pivot-table create` | 创建透视表对象 |
| 更新透视表 | `pivot-table update` | 更新透视表配置（行/列/值/筛选字段） |
| 删除透视表 | `pivot-table delete` | 删除透视表 |
典型工作流：先读取现有透视表了解配置 -> 执行创建/更新/删除 -> 再次读取验证结果。
## 行/值字段映射（创建前必做）
创建透视表前先识别用户需求中的分组维度和聚合指标，**不要搞反**：
- **rows（行字段）** = 分组维度，即"按什么分组"。例：部门、地区、医生、产品类别
- **values（值字段）** = 聚合指标，即"统计什么数值"。例：销售额（`summarize_by: "sum"`）、订单数（`summarize_by: "count"`）
- **columns（列字段）** = 交叉维度（可选），即"再按什么横向展开"。例：月份、性别
| 用户说 | rows | values | columns |
|--------|------|--------|---------|
| "按部门统计人数" | 部门 | 姓名（`"count"`） | -- |
| "按医生统计费用和结余" | 主管医生 | 费用（`"sum"`）、结余（`"sum"`） | -- |
| "各部门男女人数" | 部门 | 姓名（`"count"`） | 性别 |
**常见配置错误（必须注意）**：
- **数据源范围必须精确**：透视表的数据源范围必须包含表头行，且精确覆盖全部数据行列。范围过大（包含空行/空列）或过小（遗漏数据列）都会导致透视表结果错误
- **行列字段选择要匹配用户意图**：用户说"按商品统计金额" -> 行字段=商品，值字段=金额（`summarize_by: "sum"`）。不要把行列字段搞反
- **聚合类型要匹配**：用户说"统计数量" -> `"count"`；"统计总额" -> `"sum"`；"统计平均" -> `"average"`
- **创建后必须验证**：调用 `pivot-table list` 确认透视表结构正确
## 命令详细参考
### 获取透视表
```
Usage:
dws sheet pivot-table list [flags]
Example:
# 列出所有透视表
dws sheet pivot-table list --node NODE_ID --sheet-id SHEET_ID
# 获取单个透视表详情
dws sheet pivot-table list --node NODE_ID --sheet-id SHEET_ID --pivot-table-id PT_ID
Flags:
--node string 表格文档 ID 或 URL (必填)
--sheet-id string 工作表 ID 或名称 (必填)
--pivot-table-id string 透视表 ID (可选，不传则返回全部)
```
### 创建透视表
```
Usage:
dws sheet pivot-table create [flags]
Example:
# 按部门统计销售额（默认自动新建工作表存放）
dws sheet pivot-table create --node NODE_ID \
--source "'Sheet1'!A1:D100" \
--properties '{
"rows": [{"field": "部门"}],
"values": [{"field": "销售额", "summarize_by": "sum"}],
"show_row_grand_total": true
}'
# 指定放置到已有工作表的特定位置
dws sheet pivot-table create --node NODE_ID \
--source "'Sheet1'!A1:E200" \
--target-sheet-id TARGET_SHEET_ID --target-position "A1" \
--properties '{
"rows": [{"field": "部门"}],
"values": [{"field": "销售额", "summarize_by": "sum"}]
}'
# 通过文件传入配置
dws sheet pivot-table create --node NODE_ID \
--source "'Sheet1'!A1:D50" --properties @pivot.json
Flags:
--node string 表格文档 ID 或 URL (必填)
--source string 数据源区域，A1 表示法含 sheet 前缀 (必填，如 "'Sheet1'!A1:D100")
--properties string 透视表配置 JSON (必填，含 rows/columns/values/filters)
--target-sheet-id string 目标工作表 ID 或名称 (可选，不传则自动新建工作表)
--target-position string 透视表放置位置 (可选，A1 格式单个 cell，如 "B5"，不传默认 A1)
```
### 更新透视表
```
Usage:
dws sheet pivot-table update [flags]
Example:
# 先获取现有配置
dws sheet pivot-table list --node NODE_ID --sheet-id SHEET_ID --pivot-table-id PT_ID
# 修改后回写
dws sheet pivot-table update --node NODE_ID --sheet-id SHEET_ID --pivot-table-id PT_ID \
--properties '{
"rows": [{"field": "部门"}],
"values": [
{"field": "销售额", "summarize_by": "sum"},
{"field": "订单号", "summarize_by": "count", "display_name": "订单数"}
],
"show_row_grand_total": true
}'
Flags:
--node string 表格文档 ID 或 URL (必填)
--sheet-id string 工作表 ID 或名称 (必填)
--pivot-table-id string 透视表 ID (必填，可通过 pivot-table list 获取)
--properties string 透视表配置 JSON (必填)
```
### 删除透视表
```
Usage:
dws sheet pivot-table delete [flags]
Example:
dws sheet pivot-table delete --node NODE_ID --sheet-id SHEET_ID --pivot-table-id PT_ID
Flags:
--node string 表格文档 ID 或 URL (必填)
--sheet-id string 工作表 ID 或名称 (必填)
--pivot-table-id string 透视表 ID (必填，可通过 pivot-table list 获取)
```
> [强制] 危险操作：删除不可恢复。必须先向用户展示操作摘要并获得明确同意，用户同意后才加 `--yes` 执行。
## `--properties` JSON Schema 速查
**顶层字段**：
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `rows` | object[] | 否 | 行字段数组（分组维度），详见下方「rows/columns 字段项」表 |
| `columns` | object[] | 否 | 列字段数组（交叉维度），结构同 rows |
| `values` | object[] | 是 | 值字段数组（聚合指标，至少一项），详见下方「values 字段项」表 |
| `filters` | object[] | 否 | 筛选字段数组，详见下方「filters 字段项」表 |
| `show_row_grand_total` | boolean | 否 | 是否显示行总计，默认 true |
| `show_col_grand_total` | boolean | 否 | 是否显示列总计，默认 true |
| `show_subtotals` | boolean | 否 | 是否显示分类小计，默认 true |
| `repeat_row_labels` | boolean | 否 | 是否显示重复项标签，默认 false |
| `collapse` | object | 否 | 行字段折叠状态：字段名 -> 要折叠的项目列表，如 `{"部门": ["A组", "B组"]}` |
**rows/columns 字段项**：
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `field` | string | 是 | 列名（表头文本），必须与数据源首行的列名完全匹配 |
| `display_name` | string | 否 | 显示名称（不传时使用 field 值） |
**filters 字段项**：
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `field` | string | 是 | 列名（表头文本），必须与数据源首行的列名完全匹配 |
| `display_name` | string | 否 | 显示名称（不传时使用 field 值） |
**values 字段项**：
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `field` | string | 是 | 列名（表头文本），必须与数据源首行的列名完全匹配 |
| `summarize_by` | string | 否 | 聚合方式，默认 sum，详见下方枚举表 |
| `display_name` | string | 否 | 显示名称（不传时自动生成，如"求和 - 销售额"） |
| `show_data_as` | string | 否 | 值显示方式：`normal`/`percent_of_row_total`/`percent_of_col_total`/`percent_of_grand_total` |
**summarize_by 枚举值**：
| 值 | 说明 |
|----|------|
| `sum` | 求和（默认） |
| `count` | 计数 |
| `average` | 平均值 |
| `max` | 最大值 |
| `min` | 最小值 |
| `product` | 乘积 |
| `count_numbers` | 数值计数 |
| `std_dev` | 标准偏差 |
| `std_dev_p` | 总体标准偏差 |
| `var` | 方差 |
| `var_p` | 总体方差 |
| `distinct` | 去重计数 |
| `median` | 中位数 |
## `--source` 数据源格式
- 格式：`'SheetName'!StartCell:EndCell`
- 示例：`'Sheet1'!A1:D100`、`'销售数据'!A1:F500`
- 必须包含表头行（通常从第 1 行开始）
- sheet 名称用单引号包裹（含空格或特殊字符时必须）
- `source` 直接使用上述 A1 表示法，不要改写成其他结构
## 高级功能示例
```bash
# 含折叠 + show_data_as
dws sheet pivot-table create --node <NODE_ID> \
--source "'Sheet1'!A1:E200" \
--properties '{
"rows": [{"field": "部门"}],
"values": [
{"field": "销售额", "summarize_by": "sum"},
{"field": "订单数", "summarize_by": "count", "show_data_as": "percent_of_col_total"}
],
"collapse": {"部门": ["A组"]},
"show_row_grand_total": true
}'
```
> `collapse` / `show_data_as` 为可选字段；仅使用命令文档列出的取值，并按命令返回处理无效配置。
## 核心工作流
```bash
# -- 工作流 1: 创建简单分组汇总 --
# 1. 先查 sheetId
dws sheet list --node <NODE_ID> -f json
# 2. 查看数据范围确认列名和边界
dws sheet csv-get --node <NODE_ID> --sheet-id <SHEET_ID> --range "A1:F5"
# 3. 创建透视表（按部门统计销售额）
dws sheet pivot-table create --node <NODE_ID> \
--source "'Sheet1'!A1:D100" \
--properties '{
"rows": [{"field": "部门"}],
"values": [{"field": "销售额", "summarize_by": "sum"}],
"show_row_grand_total": true
}'
# 4. 验证创建结果（用 create 返回的 targetSheetId 查询）
dws sheet pivot-table list --node <NODE_ID> --sheet-id <TARGET_SHEET_ID>
# -- 工作流 2: 多维度交叉分析 --
dws sheet pivot-table create --node <NODE_ID> \
--source "'Sheet1'!A1:E200" \
--properties '{
"rows": [{"field": "部门"}, {"field": "产品"}],
"columns": [{"field": "季度"}],
"values": [
{"field": "销售额", "summarize_by": "sum"},
{"field": "订单号", "summarize_by": "count", "display_name": "订单数"}
],
"show_row_grand_total": true,
"show_col_grand_total": true,
"show_subtotals": true
}'
# -- 工作流 3: 更新透视表配置 --
# 先获取现有配置
dws sheet pivot-table list --node <NODE_ID> --sheet-id <SHEET_ID> --pivot-table-id <PT_ID>
# 修改后回写（增加一个值字段）
dws sheet pivot-table update --node <NODE_ID> --sheet-id <SHEET_ID> --pivot-table-id <PT_ID> \
--properties '{
"rows": [{"field": "部门"}],
"values": [
{"field": "销售额", "summarize_by": "sum"},
{"field": "利润", "summarize_by": "average", "display_name": "平均利润"}
],
"show_row_grand_total": true
}'
```
## 上下文传递
| 操作 | 从返回中提取 | 用于 |
|------|-------------|------|
| `pivot-table list` | `pivotTables[].id` | 后续 update / delete 的 `--pivot-table-id` |
| `pivot-table list --pivot-table-id` | 完整配置（rows/columns/values/filters/collapse/options） | update 时作为基础配置修改后回写 |
| `pivot-table create` | `pivotTable.id` | 后续 update / delete 的 `--pivot-table-id` |
| `pivot-table create` | `pivotTable.targetSheetId` | 后续 list / update / delete 的 `--sheet-id`（透视表所在工作表） |
| `pivot-table delete` | `message` | 确认删除完成 |
| `sheet list` | 工作表的 `sheetId` | 所有 pivot-table 命令的 `--sheet-id` |
## 注意事项
- [强制] **`--sheet-id` 获取规范**：`sheetId` 未知时必须先通过 `dws sheet list --node <NODE_ID> --format json` 查询，禁止凭空编造（如臆测为 `Sheet1`、`sheet1`、`0`、`default` 等）
- [强制] **创建后必须验证**：透视表创建后必须调用 `pivot-table list` 验证配置是否正确
- [强制] **pivot-table-id 禁止臆测**：必须通过 `pivot-table list` 获取真实的透视表 ID，不可编造
- [强制] **source 必须精确**：数据源范围必须从表头行开始，精确覆盖数据区域，先用 `csv-get` 确认数据边界
- **field 名称必须准确**：rows/columns/values/filters 中的 field 值必须与源数据表头完全一致（区分大小写）
- **透视表自动新建子表**：创建的透视表默认放置在自动新建的子表中，不会覆盖源数据。可通过 `--target-sheet-id` 和 `--target-position` 指定放置到已有工作表
- **不支持修改数据源**：update 仅可修改字段配置和显示选项，不可修改 source
- **折叠状态**：collapse 字段用于控制行字段的展开/折叠，格式为 {字段名: [要折叠的项]}
- **大 JSON 用 @file**：`--properties` 支持 `@文件路径` 读取本地 JSON 文件
.agents/skills/dingtalk-misc/references/sheet/sheet-range-operations.md
+161
View File
@@ -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` 组合写操作，均原子事务
.agents/skills/dingtalk-misc/references/sheet/sheet-read-data.md
+60
View File
@@ -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 证据。只报告已验证范围，不夸大到整张表。
.agents/skills/dingtalk-misc/references/sheet/sheet-revision-changeset.md
+46
View File
@@ -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 时合并。
.agents/skills/dingtalk-misc/references/sheet/sheet-search-replace.md
+120
View File
@@ -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` 的默认行为不同
.agents/skills/dingtalk-misc/references/sheet/sheet-style-format.md
+71
View File
@@ -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 中存在失败项时，明确报告未完成部分。
.agents/skills/dingtalk-misc/references/sheet/sheet-version.md
+84
View File
@@ -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`）回读确认，避免"写返回不等于完成"
.agents/skills/dingtalk-misc/references/sheet/sheet-workbook.md
+59
View File
@@ -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 无法解析或缺失预期对象均为失败，不得当作空列表或成功。
.agents/skills/dingtalk-misc/references/sheet/sheet-write-data.md
+74
View File
@@ -0,0 +1,74 @@
# Sheet 写入数据
## 进入本阶段的条件
仅在任务需要富文本、单元格超链接、数据验证、per-cell 样式、结构化 table 写入，或需要在 csv-put / range update / append 之间选择时读取本文件。普通二维值写入优先遵循上层 sheet.md。
## 选择最短写入路径
| 目标 | 命令 | 关键边界 |
|---|---|---|
| 超过 5 行或 20 个单元格的纯值/公式 | dws sheet csv-put | stdin 优先；最多 2M 字符、30000 单元格；覆盖已有内容必须显式 --allow-overwrite |
| 少量值、富文本、链接、数据验证、逐格样式 | dws sheet range update | --values 必须与目标范围行列数完全一致 |
| 末尾追加同构记录 | dws sheet append | 每一行列数一致；不要先读取并手算最后一行 |
| columns/data/dtypes/formats 协议 | dws sheet table-put | 多工作表用 --sheets；总单元格数含表头不超过 30000 |
所有既有工作表写入都必须使用真实 sheetId。当前上下文没有时只调用一次：
dws sheet +list-sheets --node <NODE_ID> --format json
按完整标题唯一匹配；禁止猜 Sheet1、0、default。后续阶段复用同一个 nodeId、sheetId 和 profile。
## 小范围与富格式写入
dws sheet range update --node <NODE_ID> --sheet-id <SHEET_ID> --range "A1:B2" --values '[[{"type":"text","text":"名称"},{"type":"text","text":"链接"}],[{"type":"text","text":"项目"},{"type":"text","text":"详情","hyperlink":{"type":"path","link":"https://example.com"}}]]' --format json
硬约束：
- 二维数组中的每格必须是 JSON object，不能直接传 string/number/boolean/null。写值时 type 只取 text 或 richText，数字和布尔值也按 text 字符串传递；只改 hyperlink/dataValidation/cellStyles 时可以省略 type，以保留原值。
- 用 {} 跳过单元格并保留原值；清空单个格传 {"type":"text","text":""}，清空整片范围用 range clear。
- 单元格级 hyperlink 与 richText 片段链接不要混用。取消整格链接使用 `hyperlink:{"type":"none"}`；不传 hyperlink 表示保留原链接，不能用 null 猜测清除语义。
- richText 仅在确实需要多片段样式、片段链接、附件或图片时使用；媒体 resourceId/resourceUrl 必须来自本任务 media-upload 的真实返回。
- dataValidation 是三态：不传表示保留原规则；传 `{"dataValidation":{"type":"none"}}` 表示清除；传 `dropdown` 或 `checkbox` 表示写入新规则。dropdown 的 `options` 与 `sourceRange` 必须且只能传一个；sourceRange 使用 `{"sheetId":"真实ID","a1Notation":"A1:A3"}`，不能传猜测名称。
- cellStyles 适合“写值时顺带给少量格设置样式”，也可单独传 `{"cellStyles":{...}}` 只改样式并保留原值；整片统一样式进入 sheet-style-format 阶段。
- 公式以 = 开头；需要字面量等号时前加单引号。
- 单次建议不超过 1000 行、5000 个单元格；总量不得超过当前命令契约的 30000 单元格。超出时按连续不重叠范围拆分，每块分别回读。
- 目标范围与 mergedRanges 冲突时，range update 会返回 `MERGED_CELLS_CONFLICT`。先用 info 定位冲突范围，必要时经用户同意取消合并，写入后再按原意恢复；不能把错误当成空结果。
- SourceRange 下拉在结构移动后必须回读 `sourceRangeStatus`。同一 cell 的值/样式可能已写入，但下拉创建失败时服务端仍可能返回 success=true 并把失败写在 message；必须同时检查 message 和 range read 的 dataValidation。
## 大块纯值写入
优先 stdin，避免大 JSON 和 shell 转义：
dws sheet csv-put --node <NODE_ID> --sheet-id <SHEET_ID> --start-cell A1 --csv - --format json
先比较目标范围是否已有内容。只有用户授权覆盖，或该范围由本任务新建且尚未交付时，才加 --allow-overwrite。达到 30000 单元格上限时按不重叠连续块分批，每块写后只回读该块；不要把截断或部分写入称为成功。
CSV 必须使用 ASCII 英文逗号 `,`；中文逗号 `，` 不会分列，会把整行写进一个单元格。目标区域含合并单元格时 csv-put 会打散合并并写入，这与 range update 的冲突失败语义不同；需要保留合并时先记录 mergedRanges，写完再恢复。csv-put 只承载值和公式，不承载样式、超链接、richText 或 dataValidation。
## 结构化 table 写入
dws sheet table-put --node <NODE_ID> --sheets '{"name":"订单","columns":["订单号","金额"],"data":[["9007199254740993",12.5]],"dtypes":{"订单号":"object","金额":"float64"},"formats":{"订单号":"@","金额":"0.00"}}' --format json
table-put 只有 --sheets 数据入口，接受单个 spec、spec 数组或 `{ "sheets": [...] }`，也可用 @文件和 stdin；不要发明 --columns/--data 等顶层 flag。table-put 不放入 batch-update。
单个 sheet spec 的最小契约：
- name 与 sheetId 二选一；name 不存在时创建同名工作表，sheetId 优先且不得猜测。
- columns 必填、非空、列名去空白后非空且不重复；data 默认空数组，每行宽度必须等于 columns 长度。
- startCell 默认 A1；mode 取 overwrite（默认）或 append。header 在 overwrite 默认 true、append 默认 false；append 到空表且未显式设置时写表头。
- allowOverwrite 默认 true；需要保护已有值时显式 false。不要把 csv-put 的默认 false 套到 table-put。
- dtypes、formats 的键必须来自 columns；单元格值只用 string/number/boolean/null。复用 table-get 时，data 中 `{}` 按空位/null 处理。
- 单表最多 30000 单元格，包含表头。table-put 不支持 dataValidation、hyperlink、richText、附件或单元格图片；这些能力改用 range update/write-image。
商品 ID、订单号、手机号、工号以及超过 2^53-1 的整数必须以 JSON 字符串传入，并在 dtypes/formats 中按列名声明 object 与 @，避免精度损失。写完用 table-get 验证 columns/data/dtypes/formats；table-get 不返回 cellStyles，样式另用 range read 验证。
## 写后验证
写命令成功只证明请求已接收。必须读回最小受影响范围：
dws sheet csv-get --node <NODE_ID> --sheet-id <SHEET_ID> --range "A1:B2" --format json
检查 returnedRange、hasMore、truncationReasons 和关键值。公式先用 value-render-option=formula 确认公式文本，再在需要时用 raw_value 或 formula-verify 验证计算结果。富文本、链接或数据验证使用 range read 获取 per-cell 结构；样式与合并用对应对象读命令。
对“写成功后立即读为空”的一致性延迟，只重试只读校验，采用 0ms、250ms、500ms、1s 的有界退避；不得重放非幂等写入。四次仍不一致则明确失败，不把空结果伪装成成功。