yangxuan/openclaw-config

Fork 0

Files

T

yangxuan c7ff34d012 auto backup 2026-07-02 11:00

2026-07-02 11:00:05 +08:00

14 KiB

Raw Blame History

在线电子表格 (sheet) 命令参考

适用范围（重要）

sheet 产品仅支持钉钉在线电子表格（contentType=ALIDOC、extension=axls），不支持上传的 xlsx / xls / xlsm / csv 等本地表格文件。

文件类型	处理方式
在线电子表格（`axls`）	走 `sheet` 全部命令（读/写/筛选/合并/导出等服务端原子操作）
`xlsx` / `xls` / `xlsm` / `csv` 等本地表格文件	必须用 `dws doc download --node <ID> --output <路径>` 先下载到本地再用本地工具解析，禁止调用任何 `sheet` 子命令
想把在线表格导出为 xlsx	用 `dws sheet submit_export_job` 提交导出任务 → 拿到 `jobId` → `dws sheet query_export_job` 轮询直到 `finished` → 用返回的 `downloadUrl` 下载

用户直接粘贴 alidocs URL 时，先用 dws doc info --node <URL> --format json 确认 contentType=ALIDOC 且 extension=axls 后再走 sheet；否则转 dws doc download。

命名风格说明（v1.0.25 envelope 现状）

sheet 产品的命令 cli_name 当前同时存在两种风格——这是 envelope schema 还在演进中、CLIAliases (#246) 重命名尚未完成的过渡态：

kebab-case (~17 个)：add-dimension、merge-cells、filter-view update-criteria 等，与 dws 其它产品风格一致
snake_case (~12 个)：copy_sheet、submit_export_job、set_filter_criteria 等，envelope 原始名直透出来

调用时以 dws sheet --help 输出为准——本文档与 envelope schema 同步，未来命名收敛后会同步更新。所有命令的最终参数名以 dws sheet <cmd> --help 和 dws schema sheet.<canonical_path> 为准。

命令总览（按功能分组）

工作表 (Worksheet) 级

命令	canonical	用途
`dws sheet create`	`sheet.create_workspace_sheet`	在知识库中创建一个新的钉钉表格文档
`dws sheet new`	`sheet.create_sheet`	在已有钉钉表格文档中新建一张工作表
`dws sheet list`	`sheet.get_all_sheets`	列出指定文档的所有工作表
`dws sheet info`	`sheet.get_sheet`	获取指定工作表详情
`dws sheet copy_sheet`	`sheet.copy_sheet`	复制工作表（同文档内）
`dws sheet update_sheet`	`sheet.update_sheet`	更新工作表元信息（如改名）

区域 (Range) 读写

命令	canonical	用途
`dws sheet range read`	`sheet.get_range`	读取指定区域的单元格内容
`dws sheet range update`	`sheet.update_range`	写入/更新指定区域的单元格
`dws sheet append`	`sheet.append_rows`	在工作表末尾追加若干行

行列 (Dimension)

命令	canonical	用途
`dws sheet add-dimension`	`sheet.add_dimension`	在末尾追加空行或空列
`dws sheet insert-dimension`	`sheet.insert_dimension`	在指定位置插入空行/空列
`dws sheet delete-dimension`	`sheet.delete_dimension`	删除指定位置起的若干行/列
`dws sheet move-dimension`	`sheet.move_dimension`	移动行/列到指定位置
`dws sheet update-dimension`	`sheet.update_dimension`	更新行/列属性（显隐、行高/列宽）

单元格合并

命令	canonical	用途
`dws sheet merge-cells`	`sheet.merge_cells`	合并指定范围的单元格（`mergeAll`/`mergeRows`/`mergeColumns`）
`dws sheet unmerge-cells`	`sheet.unmerge_range`	取消指定范围的合并

查找/替换

命令	canonical	用途
`dws sheet find`	`sheet.find_cells`	在工作表中搜索单元格内容（支持正则/整格匹配/隐藏）
`dws sheet replace`	`sheet.replace_all`	全局查找替换

筛选视图 (Filter View) — 命名视图、按列条件、不影响表本身

命令	canonical	用途
`dws sheet filter-view create`	`sheet.create_filter_view`	创建筛选视图
`dws sheet filter-view list`	`sheet.get_filter_views`	列出工作表的所有筛选视图
`dws sheet filter-view update`	`sheet.update_filter_view`	更新筛选视图（名称/范围/条件）
`dws sheet filter-view delete`	`sheet.delete_filter_view`	删除整个筛选视图
`dws sheet filter-view update-criteria`	`sheet.set_filter_view_criteria`	设置/更新视图内某列的筛选条件
`dws sheet filter-view delete-criteria`	`sheet.clear_filter_view_criteria`	清除视图内某列的筛选条件

表级筛选 (Filter) — 直接作用于工作表本身的临时筛选

命令	canonical	用途
`dws sheet create_filter`	`sheet.create_filter`	在工作表上创建筛选器
`dws sheet get_filter`	`sheet.get_filter`	获取当前筛选器配置
`dws sheet update_filter`	`sheet.update_filter`	更新筛选器条件
`dws sheet delete_filter`	`sheet.delete_filter`	删除筛选器
`dws sheet set_filter_criteria`	`sheet.set_filter_criteria`	设置某列的筛选条件
`dws sheet clear_filter_criteria`	`sheet.clear_filter_criteria`	清除某列的筛选条件
`dws sheet sort_filter`	`sheet.sort_filter`	对筛选范围按指定列排序

图片

命令	canonical	用途
`dws sheet write-image`	`sheet.write_image`	将已上传的图片资源写入指定单元格

导出（两步原子，v1.0.25 没有合并的 `export` 命令）

命令	canonical	用途
`dws sheet submit_export_job`	`sheet.submit_export_job`	提交导出任务，返回 `jobId`
`dws sheet query_export_job`	`sheet.query_export_job`	轮询导出任务状态，完成后返回 `downloadUrl`

v1.0.25 envelope 暴露的是这两个原子动作。要完整完成"导出 → 下载"流程需要 client 侧轮询 + 调 downloadUrl。CLIToolOverride.Pipeline (#247) 提供了底层编排能力，但当前 envelope 还没把这两个动作 Pipeline 化成一条 dws sheet export 总命令。

通用必填参数

绝大多数 sheet 命令都需要：

--node <NODE_ID> —— 钉钉表格文档的 nodeId 或 https://alidocs.dingtalk.com/i/nodes/<DOC_UUID> URL（alias 来自 nodeId）
--sheet-id <SHEET_ID> —— 工作表 ID（alias 来自 sheetId），从 dws sheet list 拿

例外：

create 只需要 --name（在知识库创建文档时不需要 nodeId）
list / info / range read 只需要 --node
submit_export_job 只需要 --node + --export-format（无 sheet-id）
query_export_job 只需要 --job-id

常用命令示例

创建文档 + 新建工作表

# 在知识库下创建一个钉钉表格文档
dws sheet create --name "销售数据" --workspace <WS_ID> --format json
# 返回的 nodeId 用于后续操作

# 在已有文档中新建一张工作表
dws sheet new --node <NODE_ID> --name "Q1 数据" --format json

读写区域

# 读 A1:D10
dws sheet range read --node <NODE_ID> --sheet-id <SHEET_ID> --range "A1:D10" --format json

# 写入 5x4 区域（values 是二维 JSON 数组）
dws sheet range update --node <NODE_ID> --sheet-id <SHEET_ID> --range "A1:D5" \
  --values '[["姓名","岗位","入职","薪资"],["张三","研发","2024-01","30000"]]' \
  --format json

# 追加行
dws sheet append --node <NODE_ID> --sheet-id <SHEET_ID> \
  --values '[["李四","产品","2025-03","28000"]]' \
  --format json

行列操作

# 在第 5 行处插入 2 个空行
dws sheet insert-dimension --node <NODE_ID> --sheet-id <SHEET_ID> \
  --dimension rows --position 4 --length 2 --format json

# 末尾追加 3 列
dws sheet add-dimension --node <NODE_ID> --sheet-id <SHEET_ID> \
  --dimension columns --length 3 --format json

# 删除第 10-12 行
dws sheet delete-dimension --node <NODE_ID> --sheet-id <SHEET_ID> \
  --dimension rows --position 9 --length 3 --format json

# 隐藏 B 列（startIndex=1, length=1）
dws sheet update-dimension --node <NODE_ID> --sheet-id <SHEET_ID> \
  --dimension columns --start-index 1 --length 1 --hidden true --format json

合并/取消合并

# 合并 A1:C1
dws sheet merge-cells --node <NODE_ID> --sheet-id <SHEET_ID> \
  --range "A1:C1" --merge-type mergeAll --format json

# 取消合并
dws sheet unmerge-cells --node <NODE_ID> --sheet-id <SHEET_ID> \
  --range "A1:C1" --format json

查找/替换

# 查找
dws sheet find --node <NODE_ID> --sheet-id <SHEET_ID> \
  --find "TODO" --use-regexp false --match-case false --format json

# 全局替换
dws sheet replace --node <NODE_ID> --sheet-id <SHEET_ID> \
  --find "TODO" --replacement "DONE" --format json

筛选视图（推荐：可命名、不破坏原表）

# 创建筛选视图（范围必须包含表头行）
dws sheet filter-view create --node <NODE_ID> --sheet-id <SHEET_ID> \
  --name "未完成项" --range "A1:E100" --format json
# 返回的 filterViewId 用于后续 update/delete/criteria 操作

# 列出所有筛选视图
dws sheet filter-view list --node <NODE_ID> --sheet-id <SHEET_ID> --format json

# 给视图的某一列设置筛选条件（column 是相对视图范围首列的 0-based 偏移）
dws sheet filter-view update-criteria --node <NODE_ID> --sheet-id <SHEET_ID> \
  --filter-view-id <FV_ID> --column 2 \
  --filter-criteria '{"conditions":[{"type":"TEXT_CONTAINS","values":["pending"]}]}' \
  --format json

# 清除某列的筛选条件（不删除视图本身）
dws sheet filter-view delete-criteria --node <NODE_ID> --sheet-id <SHEET_ID> \
  --filter-view-id <FV_ID> --column 2 --format json

# 删除整个筛选视图
dws sheet filter-view delete --node <NODE_ID> --sheet-id <SHEET_ID> \
  --filter-view-id <FV_ID> --format json

表级筛选（snake_case 系列，直接作用于工作表本身）

# 创建筛选器（一张表只有一个，再次 create 会替换）
dws sheet create_filter --node <NODE_ID> --sheet-id <SHEET_ID> \
  --range "A1:E100" --format json

# 给某列加筛选条件
dws sheet set_filter_criteria --node <NODE_ID> --sheet-id <SHEET_ID> \
  --column 0 --filter-criteria '{...}' --format json

# 按指定列排序
dws sheet sort_filter --node <NODE_ID> --sheet-id <SHEET_ID> --field 0 --format json

# 删除筛选器
dws sheet delete_filter --node <NODE_ID> --sheet-id <SHEET_ID> --format json

复制工作表

dws sheet copy_sheet --node <NODE_ID> --sheet-id <SHEET_ID> --format json
# 返回新工作表 ID

写入图片

# 已有图片资源 ID 和 URL（通过 drive 或 doc 上传得到）后写入单元格
dws sheet write-image --node <NODE_ID> --sheet-id <SHEET_ID> \
  --range "B2:B2" --resource-id <RES_ID> --resource-url <RES_URL> \
  --width 200 --height 100 --format json

导出 xlsx（两步流程）

# Step 1: 提交导出任务
JOB=$(dws sheet submit_export_job --node <NODE_ID> --export-format xlsx --format json --jq '.result.jobId')

# Step 2: 轮询任务状态（建议 sleep + 重试）
dws sheet query_export_job --job-id "$JOB" --format json
# 直到返回 status=finished + downloadUrl

# Step 3: 下载（用 curl / dws doc download / 其它工具拉 downloadUrl）

易混淆点

区分	说明
`dws sheet create` vs `dws sheet new`	`create` 在知识库新建一个文档（返回新 nodeId）；`new` 在已有文档中新建一张工作表（需 nodeId）
`dws sheet filter-view *` vs `dws sheet create_filter`/`set_filter_criteria` 等	filter-view 是命名视图，多个并存、不影响表本身；filter 是表级唯一筛选器，直接作用于工作表显示
`filter-view update-criteria` vs `filter-view delete-criteria`	update 是设置/覆盖列条件；delete 是清除列条件（视图本身保留）；要删整个视图用 `filter-view delete`
`dws sheet submit_export_job` + `query_export_job` vs `dws sheet export`	后者不存在于 v1.0.25 envelope。需 client 端自己轮询，或基于 Pipeline (#247) 在 envelope 侧 PR 一条总命令
`dws sheet write-image` vs `range update`	write-image 写入图片（需 resourceId + resourceUrl）；range update 写入文本/数字/公式
`range update` vs `append`	range update 指定区域覆盖；append 在末尾追加行
online axls vs 本地 xlsx	sheet 全部命令只认 axls；本地 xlsx 必须先 `doc download` 再用本地工具解析

危险操作（必须先向用户确认）

命令	风险
`delete-dimension`	删除行/列（含数据），不可恢复
`filter-view delete`	删除整个筛选视图
`delete_filter`	删除表级筛选器
`replace`	全局替换可能影响大量单元格
`unmerge-cells`	取消合并可能丢失部分单元格内容（钉钉行为依赖合并模式）
`update_sheet`	更新工作表元信息（如改名）

执行前先 --dry-run 预览，并向用户展示操作摘要 + 拿到明确同意，再加 --yes 提交。

何时不要用 sheet

用户给的是 xlsx / xls / xlsm / csv 本地文件 → 用 dws doc download 下载后本地解析
用户给的是 AI 表格（不是在线电子表格）→ 用 dws aitable record query 等
用户给的是富文本/普通文档 → 用 dws doc read

权威参考

列出所有 sheet 工具：dws schema | jq '.products[] | select(.id=="sheet") | .tools[] | "\(.group) \(.cli_name)"' -r
看某个命令的完整 JSON Schema：dws schema sheet.<canonical_path>（如 dws schema sheet.update_range）
看某个命令的 flag 别名映射：dws schema sheet.<canonical_path> --jq '.tool.flag_overlay'
看必填字段：dws schema sheet.<canonical_path> --jq '.tool.required'
命令的人读视图：dws sheet <cmd> --help

14 KiB Raw Blame History Unescape Escape

在线电子表格 (sheet) 命令参考

适用范围（重要）

命名风格说明（v1.0.25 envelope 现状）

命令总览（按功能分组）

工作表 (Worksheet) 级

区域 (Range) 读写

行列 (Dimension)

单元格合并

查找/替换

筛选视图 (Filter View) — 命名视图、按列条件、不影响表本身

表级筛选 (Filter) — 直接作用于工作表本身的临时筛选

图片

导出（两步原子，v1.0.25 没有合并的 export 命令）

通用必填参数

常用命令示例

创建文档 + 新建工作表

读写区域

行列操作

合并/取消合并

查找/替换

筛选视图（推荐：可命名、不破坏原表）

表级筛选（snake_case 系列，直接作用于工作表本身）

复制工作表

写入图片

导出 xlsx（两步流程）

易混淆点

危险操作（必须先向用户确认）

何时不要用 sheet

权威参考

14 KiB

Raw Blame History

导出（两步原子，v1.0.25 没有合并的 `export` 命令）