dsh-crwu-workbench 0.0.10

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

@@ -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`）必须与实际数据列精确对应，不要凭猜测填写
+  - 筛选不支持正则表达式，传入正则会当成普通文本处理

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

@@ -0,0 +1,192 @@
+# 公式写入、回读与错误校验
+
+## 使用场景
+
+用户说"写公式/计算列/辅助列/总计/占比/增长率/查找计算/自动计算/校验公式/检查公式错误"时使用本页。
+
+- 能由表内其他单元格推导的派生值，优先写公式，不要写一次性的静态结果。
+- 写公式前先读表头和 3-5 行样本，确认列含义、数据类型、真实行号和目标范围。
+- 用户明确要求"辅助列"时，需要真实写入辅助列公式；不要只用条件格式或本地计算绕过。
+
+## 当前能力边界
+
+- 写少量或需要单元格对象的公式：使用 `dws sheet range update`。
+- 从 CSV/表格文本批量写公式：使用 `dws sheet csv-put`，RFC 4180 解码后首字符为 `=` 的字段按公式解析。即使传 `--auto-convert=false` 保留其他字段原始文本，公式仍会执行；`'=...` 是普通文本，并在该模式下保留前置单引号。
+- 公式载体：公式写在 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` | 首字符为 `=` 按公式；`--auto-convert=false` 只把其他字段固定为普通文本，不禁用公式；`'=...` 保留为文本；不支持富格式对象 |
+| 查看已写入的公式文本 | `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`。同时要求日期、前导零等非公式字段保持原样时给 `csv-put` 添加 `--auto-convert=false`；公式无需特殊开关。`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` 与辅助列公式的职责边界。

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

@@ -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`