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 证据。只报告已验证范围，不夸大到整张表。

4.0 KiB Raw Blame History Unescape Escape