officecli-xlsx

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OfficeCLI XLSX Skill

Setup

安装配置

officecli

is missing:

macOS / Linux:

curl -fsSL https://d.officecli.ai/install.sh | bash

Windows (PowerShell):

irm https://d.officecli.ai/install.ps1 | iex

Verify with

officecli --version

(open a new terminal if PATH hasn't picked up). If install fails, download a binary from https://github.com/iOfficeAI/OfficeCLI/releases.

如果缺少

officecli

：

macOS / Linux：

curl -fsSL https://d.officecli.ai/install.sh | bash

Windows (PowerShell)：

irm https://d.officecli.ai/install.ps1 | iex

使用

officecli --version

验证安装（若PATH未更新，需打开新终端）。若安装失败，可从https://github.com/iOfficeAI/OfficeCLI/releases下载二进制文件。

⚠️ Help-First Rule

⚠️ 优先求助规则

This skill teaches what good xlsx looks like, not every command flag. When a property name, enum value, or alias is uncertain, consult help BEFORE guessing.

bash

officecli help xlsx                         # List all xlsx elements
officecli help xlsx <element>               # Full element schema (e.g. pivottable, chart, cf)
officecli help xlsx <verb> <element>        # Verb-scoped (e.g. add chart, set cell)
officecli help xlsx <element> --json        # Machine-readable schema

Help reflects the installed CLI version. When this skill and help disagree, help is authoritative.

此技能旨在传授优质xlsx文件的规范，而非所有命令参数。当不确定属性名称、枚举值或别名时，请先查阅帮助文档，切勿猜测。

bash

officecli help xlsx                         # 列出所有xlsx相关元素
officecli help xlsx <element>               # 查看元素完整架构（如pivottable、chart、cf）
officecli help xlsx <verb> <element>        # 按动词范围查看（如add chart、set cell）
officecli help xlsx <element> --json        # 查看机器可读格式的架构

帮助文档与已安装的CLI版本同步。若此技能内容与帮助文档存在冲突，以帮助文档为准。

Shell & Execution Discipline

Shell与执行规范

Shell quoting (zsh / bash). Excel paths contain

[]

, and number formats contain

. Both are shell metacharacters. Rules:

ALWAYS quote element paths:
```
"/Sheet1/row[1]"
```
, not
```
/Sheet1/row[1]
```
.
Use single quotes for any prop value containing
```
$
```
:
```
numFmt='$#,##0'
```
.
For formulas with cross-sheet
```
!
```
references, use
```
batch
```
with a
```
<<'EOF'
```
heredoc (see Known Issues).
```
\n
```
and
```
\t
```
in a prop value ARE interpreted by the CLI —
```
\n
```
is a real in-cell line break (pair with
```
--prop wrapText=true
```
),
```
\t
```
a tab — consistent across xlsx / docx / pptx. Double them (
```
\\n
```
) for a literal backslash-n (rarely wanted). (
```
$
```
is the shell layer above — single-quote it.)

Incremental execution. Run commands one at a time and read each exit code.

officecli

mutates the file on every call; a 50-command script that fails at command 3 will cascade silently. One command → check output → continue.

Shell引号规则（zsh / bash）。Excel路径包含

[]

，数字格式包含

，两者均为Shell元字符。规则如下：

务必为元素路径添加引号：
```
"/Sheet1/row[1]"
```
，而非
```
/Sheet1/row[1]
```
。
若属性值包含
```
$
```
，请使用单引号：
```
numFmt='$#,##0'
```
。
对于包含跨表
```
!
```
引用的公式，使用
```
batch
```
配合
```
<<'EOF'
```
heredoc语法（详见已知问题）。
属性值中的
```
\n
```
和
```
\t
```
会被CLI解析——
```
\n
```
表示单元格内的真实换行（需搭配
```
--prop wrapText=true
```
），
```
\t
```
表示制表符——此规则在xlsx / docx / pptx中通用。若需表示字面意义的反斜杠加n，需写为
```
\\n
```
（极少用到）。（
```
$
```
属于Shell层，需用单引号包裹。）

增量执行。每次仅运行一条命令并查看退出码。

officecli

会在每次调用时修改文件；若一个包含50条命令的脚本在第3条命令失败，后续错误会无声蔓延。应遵循：执行一条命令 → 检查输出 → 继续执行。

Requirements for Outputs

输出要求

Before reaching for a command, know what a good xlsx looks like. These are the deliverable standards every workbook MUST meet.

在执行命令前，需明确优质xlsx文件的标准。以下是所有工作簿必须满足的交付规范。

All Excel files

所有Excel文件通用规范

Zero formula errors. Every delivered workbook MUST have ZERO

#REF!

#DIV/0!

#VALUE!

#NAME?

#N/A

. No exceptions — guard denominators with

IFERROR

IF(x=0,...)

Formulas, not hardcoded values. If a number can be computed from other cells, it is a formula. Hardcoding

where

=SUM(B2:B9)

belongs breaks the contract that the workbook stays live when inputs change. This is the single most important rule in this skill.

Professional font. Use one consistent, professional font across the workbook (Arial / Calibri / Times New Roman). Don't mix four fonts because one sheet came from CSV.

Explicit widths. There is no auto-fit. Any column the user will read MUST have

width

set — default 8.43 chars clips everything. Sensible starts: labels 20-25, numbers 12-15, dates 12, short codes 8-10.

Preserve existing templates. When editing a file that already has a look, match it. Existing conventions override these guidelines.

零公式错误。交付的每个工作簿必须完全没有

#REF!

、

#DIV/0!

、

#VALUE!

、

#NAME?

、

#N/A

错误。无例外——需用

IFERROR

或

IF(x=0,...)

保护分母。

使用公式而非硬编码值。若某个数值可通过其他单元格计算得出，则必须使用公式。在应使用

=SUM(B2:B9)

的位置硬编码

，会破坏工作簿在输入变化时动态更新的约定。这是此技能中最重要的规则。

专业字体。整个工作簿使用统一的专业字体（Arial / Calibri / Times New Roman）。切勿因某张工作表来自CSV就混用四种字体。

明确列宽。不支持自动适配。用户需要查看的任何列必须设置

width

——默认8.43字符会截断内容。合理的初始值：标签列20-25字符，数字列12-15字符，日期列12字符，短编码列8-10字符。

保留现有模板样式。编辑已有样式的文件时，需匹配原有格式。现有约定优先于本指南的规则。

Visual delivery floor (applies to EVERY workbook)

视觉交付底线（适用于所有工作簿）

Before you declare done, run

officecli view "$FILE" html

and Read the returned HTML path to confirm all of these:

No
###
in any cell.
```
###
```
means a column is too narrow for its widest value. Every column the user reads needs an explicit
```
width
```
.
```
###
```
in a delivered file is unfinished work, never "a small visual nit".
No truncated titles. Sheet titles, section headers, long labels must fit. Widen the column or apply
```
wrapText=true
```
on the cell.
No placeholder tokens rendered as data.
```
$fy$24
```
,
```
{var}
```
,
```
<TODO>
```
,
```
xxxx
```
must never appear in a cell, chart title, series name, or legend. These are build-time tokens that escaped replacement.
Pie / doughnut slices have distinct fill colors. If the slices render same-colored, switch to
```
bar
```
/
```
column
```
or set
```
colors=...
```
explicitly.
No empty trailing pages / empty chart anchors.
```
anchor=D2:J18
```
over empty source cells looks like a broken chart.

If any of the above fails, STOP and fix before declaring done.

Print layout. Any sheet the user may print or send as a board pack needs page setup. Default portrait + no fit-to-page splits wide tables and charts mid-way. Pick the fit mode by sheet shape:

bash

undefined

在宣告完成前，运行

officecli view "$FILE" html

并查看返回的HTML路径，确认以下所有要求：

单元格中无
###
。
```
###
```
表示列宽不足以容纳最宽的内容。用户需要查看的每一列都需设置明确的
```
width
```
。交付文件中出现
```
###
```
属于未完成工作，绝非“小视觉瑕疵”。
标题无截断。工作表标题、章节标题、长标签必须完整显示。可加宽列宽或为单元格设置
```
wrapText=true
```
。
无占位符令牌作为数据显示。
```
$fy$24
```
、
```
{var}
```
、
```
<TODO>
```
、
```
xxxx
```
绝不能出现在单元格、图表标题、系列名称或图例中。这些是构建时的令牌，不应遗漏替换。
饼图/环形图切片颜色区分明显。若切片颜色相同，切换为
```
bar
```
/
```
column
```
图表，或显式设置
```
colors=...
```
。
无空尾页/空图表锚点。
```
anchor=D2:J18
```
指向空数据源单元格时，会显示为损坏的图表。

若上述任何一项不满足，请立即停止并修复，再宣告完成。

打印布局。用户可能打印或作为董事会材料发送的工作表，需进行页面设置。默认纵向+未设置适配页面会导致宽表和图表被中途拆分。根据工作表形状选择适配模式：

bash

undefined

Summary / chart / dashboard sheet (small, ≤ ~40 rows): fit to a single page.

摘要/图表/仪表板工作表（内容较少，≤约40行）：适配为单页。

officecli set "$FILE" "/Summary" --prop orientation=landscape --prop fitToPage=true

Tall data table (dozens+ rows): fit WIDTH only, let height paginate naturally.

长数据表（数十行以上）：仅适配宽度，高度自然分页。

fitToPage=true here crushes every row onto one page → unreadable (### dates, 5px rows).

此处使用fitToPage=true会将所有行压缩到一页→内容无法读取（日期显示###，行高5px）。

officecli set "$FILE" "/Data" --prop orientation=landscape --prop fitToPage=1x0


`fitToPage=true` == `1x1` == fit both axes to one page — correct only when the sheet is already short. `1x0` = fit 1 page wide, unlimited pages tall. Trigger: sheet holds a chart, or > 8 columns, or the user's ask mentions print / board / investor.

officecli set "$FILE" "/Data" --prop orientation=landscape --prop fitToPage=1x0


`fitToPage=true` == `1x1` == 同时适配宽高到单页——仅适用于内容已较短的工作表。`1x0` = 适配为1页宽，高度不限。触发场景：工作表包含图表、超过8列，或用户需求提及打印/董事会/投资者。

Financial models only — skip this section if you are building a template, tracker, CSV import, or operational sheet

仅适用于财务模型——若构建模板、追踪器、CSV导入或运营工作表，请跳过本节

Scope: budgets, forecasts, 3-statement models, valuation, any

-heavy analytical workbook. A customer-support tracker or onboarding template does not need this section.

Color coding — industry standard. Five core colors used as a language, not decoration. A reviewer should tell what a cell IS by color alone — before reading the formula.

Color	Role	Example
Blue text `0000FF`	Hardcoded inputs, scenario variables	`font.color=0000FF`
Black text `000000`	ALL formulas and calculations	default
Green text `008000`	Cross-sheet links inside this workbook	`font.color=008000`
Red text `FF0000`	Links to external files / workbooks	`font.color=FF0000`
Yellow fill `FFFF00`	Key assumptions needing review	`fill=FFFF00`

A reviewer should tell what a cell IS just by its color — before reading the formula. This is a communication contract, not a cosmetic preference.

Number formatting — standards, not preferences.

Years are text, not numbers. Format
```
2026
```
not
```
2,026
```
— use
```
numFmt="@"
```
or set
```
type=string
```
.
Currency carries its unit in the header (
```
Revenue ($mm)
```
), not in every cell.
Zeros display as
-
, not
```
0
```
. Use
```
$#,##0;($#,##0);"-"
```
.
Percentages default to one decimal:
```
0.0%
```
.
Negatives use parentheses:
```
(1,234)
```
not
```
-1,234
```
.
Valuation multiples use
```
0.0x
```
format (EV/EBITDA, P/E, etc.).

Assumptions live in cells, not inside formulas.

=B5*(1+$B$6)

is correct;

=B5*1.05

is a bug. Document each blue hardcoded input with an adjacent source note in the next cell or a cell comment:

Source: Company 10-K, FY2024, Page 45, Revenue Note
Source: Bloomberg, 2026-05-02, AAPL US Equity
Source: Management guidance, Q2 2026 earnings call

Any hardcoded number without a source is an undocumented assumption — a reviewer cannot audit it.

适用范围：预算、预测、三表模型、估值、任何以

为主的分析工作簿。客户支持追踪器或入职模板无需遵循本节规则。

颜色编码——行业标准。五种核心颜色作为一种语言使用，而非装饰。审阅者应仅通过颜色就能判断单元格类型——无需查看公式。

颜色	作用	示例
蓝色文本 `0000FF`	硬编码输入、场景变量	`font.color=0000FF`
黑色文本 `000000`	所有公式和计算结果	默认
绿色文本 `008000`	工作簿内的跨表链接	`font.color=008000`
红色文本 `FF0000`	指向外部文件/工作簿的链接	`font.color=FF0000`
黄色填充 `FFFF00`	需要审阅的关键假设	`fill=FFFF00`

审阅者应仅通过颜色就能判断单元格类型——无需查看公式。这是沟通约定，而非 cosmetic 偏好。

数字格式——标准而非偏好。

年份为文本，而非数字。格式应为
```
2026
```
而非
```
2,026
```
——使用
```
numFmt="@"
```
或设置
```
type=string
```
。
货币单位放在表头（如
```
Revenue ($mm)
```
），而非每个单元格中。
零值显示为
-
，而非
```
0
```
。使用格式
```
$#,##0;($#,##0);"-"
```
。
百分比默认保留一位小数：
```
0.0%
```
。
负值使用括号：
```
(1,234)
```
而非
```
-1,234
```
。
估值倍数使用
```
0.0x
```
格式（如EV/EBITDA、P/E等）。

假设存于单元格，而非公式内。

=B5*(1+$B$6)

是正确写法；

=B5*1.05

属于错误。每个蓝色硬编码输入需在相邻单元格或单元格批注中记录来源：

来源：公司10-K报告，2024财年，第45页，收入附注
来源：彭博，2026-05-02，AAPL美国股票
来源：管理层指引，2026年第二季度财报电话会议

任何无来源的硬编码数字均为未记录的假设——审阅者无法审核。

Common Workflow

通用工作流

Six steps. Every non-trivial build follows this shape.

Open/save lifecycle. Use
```
officecli open <file>
```
at the start and
```
officecli save <file>
```
at the end to flush to disk —
```
save
```
only writes and leaves the resident warm for follow-up edits; reach for
```
officecli close <file>
```
only to release the resident on a one-shot handoff. Both are always safe (never error or lose work). For many cells, use
```
batch
```
: ≤ 50 ops/block recommended; tested up to 80+ ops per block on pure value-set payloads with zero failures. Cross-sheet formula batches are the exception — run those non-resident, single heredoc (see Known Issues). Flush only at the non-officecli boundary: officecli's own reads always see your edits; run
```
save
```
/
```
close
```
only before a non-officecli program reads the file (openpyxl/pandas, Excel, a renderer, delivery).
Create or load.
```
officecli create "$FILE"
```
(new) or
```
officecli view "$FILE" outline
```
(existing — get the lay of the land first).
Build incrementally. One command, read the output, continue. After any structural op (new sheet, chart, named range, pivot), run
```
get
```
on it to confirm shape before stacking more on top.
Format. Column widths, number formats, freeze panes, tab colors, header fills. Formatting is not optional polish — per "Requirements for Outputs" it is part of the deliverable.
Save, then reckon with the cache.
```
officecli save <file>
```
writes to disk. Newly-added formulas ship without cached values; when a human opens the file in a spreadsheet app, the app recalculates and populates them. But your downstream
INDEX/MATCH
,
SUMPRODUCT
, or any formula that references an upstream formula will cache whatever the upstream cached at write-time — often
0
or a stale value — and that cached lie survives into non-recalculating readers. After any multi-formula build involving array formulas (
```
SUMPRODUCT
```
,
```
SUMIFS
```
with dynamic criteria) or cross-sheet chains, re-touch every downstream cell (run
```
set
```
again with the same formula) so the engine recomputes its cache from the freshly-cached upstream. ⚠️ Re-touch on cross-sheet chains via resident is unreliable (see Batch / resident caveats) — prefer non-resident
```
set
```
for the re-touch pass. Then
```
officecli get
```
a few downstream cells and eyeball that their
```
cachedValue=
```
is plausible.
```
validate
```
is safe with a resident open and itself flushes pending edits to disk (same as docx / pptx).
QA — assume there are problems. See the QA section. You are not done when your last command exited 0; you are done after one fix-and-verify cycle finds zero new issues.

六个步骤。所有非 trivial 的构建均遵循此流程。

打开/保存生命周期。开始时使用
```
officecli open <file>
```
，结束时使用
```
officecli save <file>
```
将修改写入磁盘——
```
save
```
仅写入文件并保持内存缓存活跃，以便后续编辑；仅在一次性交付时使用
```
officecli close <file>
```
释放内存缓存。两者均安全（不会报错或丢失数据）。处理大量单元格时，使用
```
batch
```
：建议每个块≤50个操作；纯设置值的 payload 测试过支持80+操作/块，无失败。跨表公式批处理除外——需使用非缓存模式，单个 heredoc（详见已知问题）。仅在非officecli边界时刷新：officecli自身的读取始终能看到你的修改；仅在非officecli程序（openpyxl/pandas、Excel、渲染器、交付）读取文件前，运行
```
save
```
/
```
close
```
。
创建或加载。
```
officecli create "$FILE"
```
（新建）或
```
officecli view "$FILE" outline
```
（现有文件——先了解整体结构）。
增量构建。执行一条命令，查看输出，再继续。完成任何结构性操作（新建工作表、图表、命名区域、数据透视表）后，运行
```
get
```
命令确认结构，再进行后续操作。
格式化。设置列宽、数字格式、冻结窗格、标签颜色、表头填充。格式化并非可选的润色——根据“输出要求”，它是交付内容的一部分。
保存，然后处理缓存。
```
officecli save <file>
```
将修改写入磁盘。新增的公式不会附带缓存值；当人类用户在电子表格应用中打开文件时，应用会重新计算并填充缓存值。但下游的
INDEX/MATCH
、
SUMPRODUCT
或任何引用上游公式的公式，会缓存上游写入时的缓存值——通常为
0
或过期值——且该错误缓存会保留到不重新计算的读取器中。完成任何涉及数组公式（
```
SUMPRODUCT
```
、带动态条件的
```
SUMIFS
```
）或跨表链的多公式构建后，重新处理每个下游单元格（再次运行
```
set
```
命令，使用相同公式），让引擎根据上游新缓存的值重新计算其缓存。⚠️ 通过缓存模式重新处理跨表链不可靠（详见批处理/缓存注意事项）——建议使用非缓存模式的
```
set
```
进行重新处理。然后使用
```
officecli get
```
查看几个下游单元格，确认
```
cachedValue=
```
的值合理。
```
validate
```
命令在缓存模式下打开文件时也安全，且会自动将待处理的修改写入磁盘（与docx/pptx相同）。
QA——假设存在问题。详见QA章节。并非最后一条命令执行成功就完成了；需经过一次修复-验证循环，确认未发现新问题，才算完成。

Quick Start

快速入门

Minimal viable xlsx: 3 months of revenue + a total formula + column widths + a currency format. Adapt, don't copy-paste — your file, your data.

bash

officecli create "$FILE"
officecli open "$FILE"
officecli set "$FILE" /Sheet1/A1 --prop value=Month --prop bold=true
officecli set "$FILE" /Sheet1/B1 --prop value=Revenue --prop bold=true
officecli set "$FILE" /Sheet1/A2 --prop value=Jan
officecli set "$FILE" /Sheet1/A3 --prop value=Feb
officecli set "$FILE" /Sheet1/A4 --prop value=Mar
officecli set "$FILE" /Sheet1/B2 --prop value=42000 --prop numFmt='$#,##0'
officecli set "$FILE" /Sheet1/B3 --prop value=45000 --prop numFmt='$#,##0'
officecli set "$FILE" /Sheet1/B4 --prop value=48000 --prop numFmt='$#,##0'
officecli set "$FILE" /Sheet1/A5 --prop value=Total --prop bold=true
officecli set "$FILE" /Sheet1/B5 --prop formula="SUM(B2:B4)" --prop bold=true --prop numFmt='$#,##0'
officecli set "$FILE" "/Sheet1/col[A]" --prop width=12
officecli set "$FILE" "/Sheet1/col[B]" --prop width=15
officecli close "$FILE"
officecli validate "$FILE"

Verified:

validate

returns

no errors found

B5

resolves to

. This is the shape of every build: open → set cells/formulas → format → close → validate.

最简xlsx示例：3个月收入数据 + 总计公式 + 列宽 + 货币格式。请根据你的文件和数据调整，不要直接复制粘贴。

bash

officecli create "$FILE"
officecli open "$FILE"
officecli set "$FILE" /Sheet1/A1 --prop value=Month --prop bold=true
officecli set "$FILE" /Sheet1/B1 --prop value=Revenue --prop bold=true
officecli set "$FILE" /Sheet1/A2 --prop value=Jan
officecli set "$FILE" /Sheet1/A3 --prop value=Feb
officecli set "$FILE" /Sheet1/A4 --prop value=Mar
officecli set "$FILE" /Sheet1/B2 --prop value=42000 --prop numFmt='$#,##0'
officecli set "$FILE" /Sheet1/B3 --prop value=45000 --prop numFmt='$#,##0'
officecli set "$FILE" /Sheet1/B4 --prop value=48000 --prop numFmt='$#,##0'
officecli set "$FILE" /Sheet1/A5 --prop value=Total --prop bold=true
officecli set "$FILE" /Sheet1/B5 --prop formula="SUM(B2:B4)" --prop bold=true --prop numFmt='$#,##0'
officecli set "$FILE" "/Sheet1/col[A]" --prop width=12
officecli set "$FILE" "/Sheet1/col[B]" --prop width=15
officecli close "$FILE"
officecli validate "$FILE"

验证：

validate

no errors found

，

B5

计算结果为

。这是所有构建的流程：打开→设置单元格/公式→格式化→关闭→验证。

CSV / bulk import

CSV / 批量导入

Native
import
command (preferred for CSV/TSV). Fastest path; loads a CSV into a sheet in one call.

--header

sets AutoFilter + freeze pane on row 1. Widths and

numFmt

still need a follow-up pass (per D-12 in Dashboard skill).

bash

officecli import "$FILE" /Sheet1 --file data.csv --header
officecli import "$FILE" /Sheet1 --file data.tsv --format tsv --header
officecli import "$FILE" /Sheet1 --stdin --start-cell B2 < data.csv

Python + batch fallback — use when you need custom type coercion, formula injection, or the CSV lives inside another data pipeline. Recipe for 600-6000+ cells:

python

undefined

原生
import
命令（CSV/TSV首选）。最快的方式；一次调用即可将CSV加载到工作表中。

--header

参数会在第1行设置自动筛选+冻结窗格。仍需后续设置列宽和

numFmt

（详见仪表板技能的D-12）。

bash

officecli import "$FILE" /Sheet1 --file data.csv --header
officecli import "$FILE" /Sheet1 --file data.tsv --format tsv --header
officecli import "$FILE" /Sheet1 --stdin --start-cell B2 < data.csv

Python + batch 备选方案——当需要自定义类型转换、公式注入，或CSV属于其他数据管道时使用。适用于600-6000+单元格的场景：

python

undefined

gen_batch.py — produces batch chunks of 80 value-set ops each

gen_batch.py —— 生成每个块包含80个设置值操作的批处理数据

import csv, json ops = [] with open("data.csv") as f: reader = csv.reader(f) for r, row in enumerate(reader, start=1): for c, val in enumerate(row): col = chr(ord('A') + c) ops.append({"command":"set","path":f"/Data/{col}{r}", "props":{"value": val}}) for i in range(0, len(ops), 80): print(json.dumps(ops[i:i+80]))


```bash
python gen_batch.py | while IFS= read -r chunk; do
  printf '%s\n' "$chunk" | officecli batch "$FILE"
done

Outcome: 648-row retail CSV (6490 cells) loads in ~30s, zero failures. Tune: start at 80 ops/chunk, drop to 40 if any chunk fails. Numeric type inference and formulas come later via targeted

set

— batch in this recipe is pure value injection.


```bash
python gen_batch.py | while IFS= read -r chunk; do
  printf '%s\n' "$chunk" | officecli batch "$FILE"
done

结果：648行零售CSV（6490个单元格）加载耗时约30秒，无失败。调整：初始设置为80操作/块，若任何块失败，降至40操作/块。数值类型推断和公式需后续通过针对性的

set

命令设置——此示例中的batch仅用于纯值注入。

Reading & Analysis

读取与分析

Start wide, then narrow.

outline

first tells you what sheets exist and where the data is; jump into

view

get

query

only once you know where to look.

Open the rendered workbook to eyeball your own work.

```
officecli view $FILE html
```
— Read the returned HTML to audit the rendered output. Each sheet is addressable, charts render inline. Catches
```
###
```
, placeholder leakage, pivot layout, row-height clipping.
```
officecli watch $FILE
```
keeps a live preview running for the human user — they open it at their own discretion. Use when the user wants to watch along; agent self-check uses
```
view html
```
above. Use
```
view html
```
as your first visual check after a batch of edits — fix at source. For final visual verification, the user opens the
```
.xlsx
```
in their Excel / WPS / Numbers viewer.

Orient. Sheets, dimensions, formula counts.

bash

officecli view "$FILE" outline

Extract. Plain text dump for content QA or LLM context; scope with

--start

--end

--cols

for big files.

bash

officecli view "$FILE" text --start 1 --end 50 --cols A,B,C

Other

view

modes worth knowing:

annotated

(cell values + types/formulas + warnings),

stats

(numeric summaries),

issues

(broken formulas, empty sheets, missing refs).

Round-trip dump.

officecli dump "$FILE" [path]

serializes the workbook — or one worksheet (

/Sheet1

/sheet[N]

) — into a replayable batch JSON;

officecli batch new.xlsx --input dump.json

replays it. Use it to learn from an existing workbook's structure or clone/adapt a template instead of reading raw OOXML. Coverage per

dump --help

; subtree dumps don't carry workbook-level resources (settings, named ranges) — the replay target must already define them.

bash

officecli dump "$FILE" -o blueprint.json            # whole workbook
officecli dump "$FILE" /Sheet1 -o sheet.json        # one worksheet
officecli batch new.xlsx --input blueprint.json

Inspect one element. Use XPath-style paths. Always quote — shells glob

[N]

bash

officecli get "$FILE" "/Sheet1/A1"            # one cell
officecli get "$FILE" "/Sheet1/A1:D10"        # range
officecli get "$FILE" "/Sheet1/chart[1]"      # chart
officecli get "$FILE" "/Sheet1/table[1]"      # ListObject
officecli get "$FILE" "/namedrange[1]"        # workbook-level named range

Add

--depth N

to expand children; add

--json

for machine output. Full element list:

officecli help xlsx

Query across the workbook. CSS-like selectors. Use for systematic checks (formula coverage, error cells, empty headers) rather than hand-walking.

bash

officecli query "$FILE" 'cell:has(formula)'       # every formula cell
officecli query "$FILE" 'cell:contains("#REF!")'  # broken references
officecli query "$FILE" 'cell[type=Number]'       # typed filter
officecli query "$FILE" 'Sheet1!B[value!=0]'      # sheet-scoped

Operators:

!=

~=

(contains),

>=

<=

[attr]

(exists).

Merge cells shortcut.

officecli query $FILE merge

mergedrange

— both are aliases for

mergeCell

. Returns every merged range in the workbook without hand-walking

<mergeCell>

entries.

When the data is big enough that a row-walk is useless, reach for Excel's own analytical elements:

Build a pivot table with
```
officecli add
```
(
```
--type pivottable
```
) to group/aggregate without writing 20 SUMIFs. Attach a slicer (
```
--type slicer
```
) to give the reader a filter UI.
Drop a sparkline (
```
--type sparkline
```
) in a row to show per-row trends — cheaper than one line chart per row and they print inline.
```
type
```
is a strict enum: line | column | stacked
(plus aliases
```
winloss
```
/
```
win-loss
```
→
```
stacked
```
). Invalid
```
type=
```
values hard-fail — no silent fallback to
```
line
```
anymore.

Run

officecli help xlsx pivottable

officecli help xlsx slicer

officecli help xlsx sparkline

for the exact prop names.

先全局查看，再聚焦细节。首先使用

outline

命令了解工作表结构和数据位置；明确目标后再使用

view

get

query

命令。

打开渲染后的工作簿查看自己的工作成果。

```
officecli view $FILE html
```
—— 查看返回的HTML路径，审核渲染后的输出。每个工作表均可访问，图表内嵌显示。可发现
```
###
```
、占位符遗漏、数据透视表布局、行高截断等问题。
```
officecli watch $FILE
```
为用户保持实时预览——用户可自行决定是否打开。适用于用户需要实时查看的场景；Agent自检使用上述
```
view html
```
命令。将
```
view html
```
作为批量编辑后的首次视觉检查工具——从源头修复问题。最终视觉验证可让用户在Excel/WPS/Numbers查看器中打开
```
.xlsx
```
文件。

了解结构。查看工作表、维度、公式数量。

bash

officecli view "$FILE" outline

提取内容。纯文本导出，用于内容QA或LLM上下文；处理大文件时，可使用

--start

--end

--cols

参数限定范围。

bash

officecli view "$FILE" text --start 1 --end 50 --cols A,B,C

其他值得了解的

view

模式：

annotated

（单元格值+类型/公式+警告）、

stats

（数值汇总）、

issues

（损坏的公式、空工作表、缺失的引用）。

往返导出。

officecli dump "$FILE" [path]

将工作簿——或单个工作表（

/Sheet1

、

/sheet[N]

）——序列化为可重放的batch JSON；

officecli batch new.xlsx --input dump.json

可重放该JSON。用于学习现有工作簿的结构，或克隆/适配模板，无需读取原始OOXML。覆盖范围详见

dump --help

；子树导出不包含工作簿级资源（设置、命名区域）——重放目标需已定义这些资源。

bash

officecli dump "$FILE" -o blueprint.json            # 整个工作簿
officecli dump "$FILE" /Sheet1 -o sheet.json        # 单个工作表
officecli batch new.xlsx --input blueprint.json

查看单个元素。使用XPath风格的路径。务必添加引号——Shell会解析

[N]

。

bash

officecli get "$FILE" "/Sheet1/A1"            # 单个单元格
officecli get "$FILE" "/Sheet1/A1:D10"        # 单元格范围
officecli get "$FILE" "/Sheet1/chart[1]"      # 图表
officecli get "$FILE" "/Sheet1/table[1]"      # ListObject
officecli get "$FILE" "/namedrange[1]"        # 工作簿级命名区域

添加

--depth N

参数展开子元素；添加

--json

参数获取机器可读输出。完整元素列表：

officecli help xlsx

。

跨工作簿查询。使用类CSS选择器。用于系统性检查（公式覆盖、错误单元格、空表头），而非手动遍历。

bash

officecli query "$FILE" 'cell:has(formula)'       # 所有包含公式的单元格
officecli query "$FILE" 'cell:contains("#REF!")'  # 损坏的引用
officecli query "$FILE" 'cell[type=Number]'       # 按类型筛选
officecli query "$FILE" 'Sheet1!B[value!=0]'      # 工作表范围筛选

运算符：

、

!=

、

~=

（包含）、

>=

、

<=

、

[attr]

（存在）。

合并单元格快捷方式。

officecli query $FILE merge

或

mergedrange

——两者均为

mergeCell

的别名。无需手动遍历

<mergeCell>

条目，即可返回工作簿中的所有合并范围。

当数据量大到手动遍历无意义时，使用Excel自身的分析元素：

使用
```
officecli add
```
（
```
--type pivottable
```
）构建数据透视表，无需编写20个SUMIF函数即可分组/聚合数据。添加切片器（
```
--type slicer
```
）为读者提供筛选UI。
在行中添加迷你图（
```
--type sparkline
```
）显示每行的趋势——比每行一个折线图更简洁，且可内嵌打印。
```
type
```
为严格枚举值：line | column | stacked
（别名
```
winloss
```
/
```
win-loss
```
对应
```
stacked
```
）。无效的
```
type=
```
值会直接失败——不再默认回退到
```
line
```
。

查看

officecli help xlsx pivottable

、

officecli help xlsx slicer

、

officecli help xlsx sparkline

获取准确的属性名称。

Creating & Editing

创建与编辑

Ninety percent of a build is cells, formulas, formatting, and one or two charts. The verbs:

add

(new element),

set

(change a prop),

remove

move

swap

batch

90%的构建工作涉及单元格、公式、格式化和一两个图表。可用动词：

add

（新增元素）、

set

（修改属性）、

remove

、

move

、

swap

、

batch

。

Cells and formulas

单元格与公式

Set a value and its format in one call. Never write

at the start of a formula — the CLI strips it.

bash

officecli set "$FILE" /Sheet1/B5 --prop formula="SUM(B2:B4)" --prop numFmt='$#,##0'
officecli set "$FILE" /Sheet1/C5 --prop formula="B5/A5" --prop numFmt="0.0%"

Structural properties (width, height, freeze, tabColor) live on row / col / sheet nodes:

bash

officecli set "$FILE" "/Sheet1/col[A]" --prop width=20
officecli set "$FILE" "/Sheet1/row[1]" --prop height=22
officecli set "$FILE" "/Sheet1" --prop freeze=A2 --prop tabColor=1F4E79

一次调用即可设置值和格式。公式开头无需写

——CLI会自动去除。

bash

officecli set "$FILE" /Sheet1/B5 --prop formula="SUM(B2:B4)" --prop numFmt='$#,##0'
officecli set "$FILE" /Sheet1/C5 --prop formula="B5/A5" --prop numFmt="0.0%"

结构性属性（宽度、高度、冻结、标签颜色）属于行/列/工作表节点：

bash

officecli set "$FILE" "/Sheet1/col[A]" --prop width=20
officecli set "$FILE" "/Sheet1/row[1]" --prop height=22
officecli set "$FILE" "/Sheet1" --prop freeze=A2 --prop tabColor=1F4E79

Named ranges

命名区域

Prefer named ranges over

$B$6

in formulas. They self-document (

GrowthRate

beats

$B$6

) and they let you move the assumption cell without breaking formulas. Because

ref

values contain both

and

, add them through a batch heredoc:

bash

cat <<'EOF' | officecli batch "$FILE"
[
  {"command":"add","parent":"/","type":"namedrange","props":{"name":"GrowthRate","ref":"Sheet1!$B$6"}}
]
EOF

See

officecli help xlsx namedrange

for the full schema.

Batch JSON does NOT accept shell aliases. Inside batch

props

, always use the full dotted name —

"font.color": "FF0000"

"font.size": 14

, never

"color": "FF0000"

(ambiguous: text vs fill). On a bare cell, even the shell form is rejected:

--prop color=1F4E79

errors with

ambiguous in cell context — use 'font.color' (text) or 'fill' (bg)

. Rule: in any batch JSON or cell prop, write

font.color

fill

explicitly.

parent

should be

"/"

for workbook-level elements and

"/SheetName"

for sheet-scoped; empty string is not equivalent.

在公式中优先使用命名区域，而非

$B$6

。命名区域可自我文档化（

GrowthRate

比

$B$6

更清晰），且移动假设单元格时不会破坏公式。由于

ref

值包含

和

，需通过batch heredoc添加：

bash

cat <<'EOF' | officecli batch "$FILE"
[
  {"command":"add","parent":"/","type":"namedrange","props":{"name":"GrowthRate","ref":"Sheet1!$B$6"}}
]
EOF

查看

officecli help xlsx namedrange

获取完整架构。

Batch JSON不接受Shell别名。在batch的

props

中，必须使用完整的点式名称——

"font.color": "FF0000"

、

"font.size": 14

，而非

"color": "FF0000"

（存在歧义：文本颜色还是填充颜色）。在单个单元格的Shell命令中，

--prop color=1F4E79

也会报错：

ambiguous in cell context — use 'font.color' (text) or 'fill' (bg)

。规则：在任何batch JSON或单元格属性中，需显式写

font.color

fill

。

parent

对于工作簿级元素应为

"/"

，对于工作表级元素应为

"/SheetName"

；空字符串不等效。

Charts

图表

Chart types live under

officecli help xlsx chart

— the enum is long (20+). Pick the right one for the message: column for category comparison, line for time series, pie only when slices are self-evidently proportional, scatter for correlation. Avoid exotic types unless they answer a specific question.

Three ways to feed chart data. Pick one per chart — mixing them at add-time is a common trap.

Form	Shape	When to use
(a) inline `data`	`--prop data="Sales:100,200,300" --prop categories="Jan,Feb,Mar"`	Tiny demo charts, numbers you will not edit. Source of truth lives in the chart XML, not a cell.
(b) 2D `dataRange`	`--prop dataRange="Sheet1!A1:B4"` (first col = categories, first row = header / series name)	Normal case. Must be 2-D — single column fails with "Chart requires data".
(c) dotted per-series	`--prop series1.name=Sales --prop series1.values="Sheet1!B2:B4" --prop series1.categories="Sheet1!A2:A4"`	Multi-series charts where each series points at non-contiguous ranges, or you want explicit series naming. `series1.values` alone (no `categories` ) emits a chart with `1,2,3` as the x-axis.

The single-column trap.

dataRange="Sheet1!B2:B13"

looks like "value column" but the engine rejects it with

Chart requires data

. Either widen the range to include the category column (

A2:B13

), or switch to form (c) with explicit

series1.categories

Move / resize a chart after create:

set chart[N] --prop anchor="F5:N25"

(also

--prop x= --prop y= --prop width= --prop height=

). Series are still immutable — to add/change a series,

officecli remove

the chart and

officecli add

with the full series list. Note

remove chart[1]

shifts

chart[2] → chart[1]

and re-add appends at the end — to preserve chart order, remove all and rebuild in order.

Anchor sizing. No auto-fit. A column chart with 5-6 categories + 2 series needs roughly

A5:L22

(12 cols × 18 rows) to show all labels uncut. Narrower and X-axis labels clip; wider and the chart can split across pages on print/export. If in doubt, start narrow, preview via

view html

(Read the returned HTML path), widen in increments. Page layout (below) is the other half of the fix.

Chart
dataRange
— always prefix with the sheet. Even when the chart lives on the same sheet, write

dataRange="Summary!A17:C22"

, not

A17:C22

. The sheet-less form works inconsistently; the prefixed form is 100% reliable.

officecli adds extended chart types the classic Excel object model lacks:

boxWhisker

waterfall

funnel

histogram

treemap

sunburst

pareto

. Use them when the data calls for them.

NEVER put unreplaced template tokens in chart title / series name / legend / axis title.

$fy$24

{var}

<TODO>

$VAR

{{placeholder}}

render literally in the legend — validate passes, but a CFO sees

$fy$24

where "FY2024" should be. Always bind to final text or a cell reference (

title="FY2024 Revenue"

series1.name="Sheet1!A1"

图表类型详见

officecli help xlsx chart

——枚举值超过20种。根据要传达的信息选择合适的类型：柱状图用于类别比较，折线图用于时间序列，饼图仅适用于切片比例直观的场景，散点图用于相关性分析。除非有特定需求，否则避免使用特殊类型。

三种图表数据输入方式。每个图表仅选一种——添加时混用是常见陷阱。

形式	格式	使用场景
(a) 内联 `data`	`--prop data="Sales:100,200,300" --prop categories="Jan,Feb,Mar"`	小型演示图表，无需编辑的数值。数据源存储在图表XML中，而非单元格。
(b) 二维 `dataRange`	`--prop dataRange="Sheet1!A1:B4"` （第一列为类别，第一行为表头/系列名称）	常规场景。必须为二维——单列会报错“Chart requires data”。
(c) 按系列分点设置	`--prop series1.name=Sales --prop series1.values="Sheet1!B2:B4" --prop series1.categories="Sheet1!A2:A4"`	多系列图表，每个系列指向非连续范围，或需要显式命名系列。仅设置 `series1.values` （无 `categories` ）会生成x轴为 `1,2,3` 的图表。

单列陷阱。

dataRange="Sheet1!B2:B13"

看似是“值列”，但引擎会报错“Chart requires data”。需将范围扩大到包含类别列（

A2:B13

），或切换为形式(c)并显式设置

series1.categories

。

创建后移动/调整图表大小：

set chart[N] --prop anchor="F5:N25"

（也可使用

--prop x= --prop y= --prop width= --prop height=

）。系列创建后不可修改——若要添加/修改系列，需

officecli remove

图表，再

officecli add

完整的系列列表。注意

remove chart[1]

会将

chart[2]

变为

chart[1]

，重新添加会追加到末尾——若要保留图表顺序，需删除所有图表后按顺序重建。

锚点大小。不支持自动适配。包含5-6个类别+2个系列的柱状图，锚点大小约为

A5:L22

（12列×18行），才能完整显示所有标签。锚点过窄会导致X轴标签截断，过宽会导致图表在打印/导出时跨页。若不确定，先设置较小的锚点，通过

view html

预览（查看返回的HTML路径），逐步加宽。页面布局（见下文）是另一部分解决方案。

图表
dataRange
——务必添加工作表前缀。即使图表与数据在同一工作表，也需写

dataRange="Summary!A17:C22"

，而非

A17:C22

。无工作表前缀的写法不稳定，带前缀的写法100%可靠。

officecli支持经典Excel对象模型没有的扩展图表类型：

boxWhisker

、

waterfall

、

funnel

、

histogram

、

treemap

、

sunburst

、

pareto

。当数据需要时使用这些类型。

切勿在图表标题/系列名称/图例/轴标题中保留未替换的模板令牌。

$fy$24

、

{var}

、

<TODO>

、

$VAR

、

{{placeholder}}

会在图例中按字面显示——

validate

会通过，但CFO会看到

$fy$24

而非“FY2024”。始终绑定到最终文本或单元格引用（

title="FY2024 Revenue"

或

series1.name="Sheet1!A1"

）。

Conditional formatting

条件格式

Three common flavors, each with its own prop shape (consult

officecli help xlsx cf

Color scales: cells shaded on a gradient by value —
```
type=colorscale
```
with
```
minColor
```
/
```
midColor
```
/
```
maxColor
```
.
Data bars: in-cell bars showing magnitude —
```
type=databar
```
. Set explicit
```
min
```
/
```
max
```
for consistent scaling across a column; defaults are valid if you omit them.
Formula rules (the
```
formulacf
```
element): highlight row when a condition is true —
```
type=formula
```
with
```
formula="$C2>1000"
```
and a fill/font.

Rule: apply CF sparingly. A workbook where every cell is colored tells the reader nothing.

三种常见类型，每种类型的属性格式不同（查看

officecli help xlsx cf

）：

色阶：单元格根据值以渐变颜色填充——
```
type=colorscale
```
，设置
```
minColor
```
/
```
midColor
```
/
```
maxColor
```
。
数据条：单元格内显示条形图表示数值大小——
```
type=databar
```
。为了在列中保持一致的缩放比例，可显式设置
```
min
```
/
```
max
```
；若省略则使用默认值。
公式规则（
```
formulacf
```
元素）：满足条件时高亮整行——
```
type=formula
```
，设置
```
formula="$C2>1000"
```
和填充/字体样式。

规则：谨慎使用条件格式。每个单元格都着色的工作簿无法为读者提供有效信息。

Data validation

数据验证

Input cells in trackers and templates MUST carry data validation. It's cheap and it stops entire classes of downstream bugs. Three list-source patterns — pick based on where the allowed values live.

(a) Inline list — allowed values are short and fixed in the rule itself.

bash

officecli add "$FILE" /Sheet1 --type validation \
  --prop sqref="C2:C100" --prop type=list \
  --prop formula1="Yes,No,Maybe" \
  --prop showError=true --prop errorTitle="Invalid" --prop error="Select from list"

(b) Named range (preferred for cross-sheet lookups) — allowed values live in another sheet and may grow. Define the named range first, then reference it. Use a batch heredoc because

ref

contains

and

bash

cat <<'EOF' | officecli batch "$FILE"
[
  {"command":"add","parent":"/","type":"namedrange","props":{"name":"StatusList","ref":"Lookups!$A$2:$A$4"}},
  {"command":"add","parent":"/Sheet1","type":"validation","props":{"sqref":"B2:B100","type":"list","formula1":"=StatusList"}}
]
EOF

(c) Direct cross-sheet range — no named range, raw

Lookups!$A$2:$A$4

inside

formula1

. Also needs a batch heredoc to keep

and

intact:

bash

cat <<'EOF' | officecli batch "$FILE"
[
  {"command":"add","parent":"/Sheet1","type":"validation","props":{"sqref":"C2:C100","type":"list","formula1":"Lookups!$A$2:$A$4"}}
]
EOF

If you write the cross-sheet variant as

--prop formula1=...

on the shell, the

gets shell-mangled into

\!

and the dropdown will silently fall back to no list. Verify with

officecli get "$FILE" /Sheet1/validation[N]

—

formula1=

must show a plain

, no backslash.

Other common

type

values:

decimal

whole

date

textLength

custom

. See

officecli help xlsx validation

for operators and the full prop list.

追踪器和模板中的输入单元格必须设置数据验证。成本低且能避免大量下游错误。三种列表来源模式——根据允许值的存储位置选择。

(a) 内联列表——允许值较短且固定在规则中。

bash

officecli add "$FILE" /Sheet1 --type validation \
  --prop sqref="C2:C100" --prop type=list \
  --prop formula1="Yes,No,Maybe" \
  --prop showError=true --prop errorTitle="Invalid" --prop error="Select from list"

(b) 命名区域（跨表查找首选）——允许值存储在另一个工作表中，且可能增长。先定义命名区域，再引用它。由于

ref

包含

和

，需使用batch heredoc：

bash

cat <<'EOF' | officecli batch "$FILE"
[
  {"command":"add","parent":"/","type":"namedrange","props":{"name":"StatusList","ref":"Lookups!$A$2:$A$4"}},
  {"command":"add","parent":"/Sheet1","type":"validation","props":{"sqref":"B2:B100","type":"list","formula1":"=StatusList"}}
]
EOF

(c) 直接跨表范围——不使用命名区域，直接在

formula1

中写

Lookups!$A$2:$A$4

。同样需要batch heredoc来保留

和

：

bash

cat <<'EOF' | officecli batch "$FILE"
[
  {"command":"add","parent":"/Sheet1","type":"validation","props":{"sqref":"C2:C100","type":"list","formula1":"Lookups!$A$2:$A$4"}}
]
EOF

若在Shell中写

--prop formula1=...

，

会被Shell解析为

\!

，下拉列表会无声失效。使用

officecli get "$FILE" /Sheet1/validation[N]

验证——

formula1=

必须显示纯

，无反斜杠。

其他常见的

type

值：

decimal

、

whole

、

date

、

textLength

、

custom

。查看

officecli help xlsx validation

获取运算符和完整属性列表。

Other elements (one-liners)

其他元素（单行命令）

Tables (ListObjects) —
```
add --type table
```
with a range; gives auto-filter + structured refs.
```
officecli help xlsx table
```
.
Comments —
```
add --type comment
```
; use for documenting hardcoded assumptions.
```
officecli help xlsx comment
```
.
Sheet reordering —
```
officecli move
```
, not
```
swap
```
.
```
swap
```
only works on row/cell paths.

表格（ListObjects）——
```
add --type table
```
并设置范围；提供自动筛选+结构化引用。查看
```
officecli help xlsx table
```
。
批注——
```
add --type comment
```
；用于记录硬编码假设。查看
```
officecli help xlsx comment
```
。
工作表重排序——使用
```
officecli move
```
，而非
```
swap
```
。
```
swap
```
仅适用于行/单元格路径。

Chart Axis-by-Role

按角色编辑图表轴

Editing a chart axis in place is cheaper than rebuilding the chart. Address axes by role (

value

= Y,

category

= X), not by index — the XML order isn't stable.

bash

officecli get "$FILE" "/Sheet1/chart[1]/axis[@role=value]"
officecli set "$FILE" "/Sheet1/chart[1]/axis[@role=value]" --prop min=0 --prop max=100000
officecli set "$FILE" "/Sheet1/chart[1]/axis[@role=category]" --prop title="Month"

Safe props:

title

min

max

majorGridlines

visible

labelRotation

就地编辑图表轴比重建图表更高效。按角色（

value

=Y轴，

category

=X轴）寻址轴，而非按索引——XML顺序不稳定。

bash

officecli get "$FILE" "/Sheet1/chart[1]/axis[@role=value]"
officecli set "$FILE" "/Sheet1/chart[1]/axis[@role=value]" --prop min=0 --prop max=100000
officecli set "$FILE" "/Sheet1/chart[1]/axis[@role=category]" --prop title="Month"

安全属性：

title

、

min

、

max

、

majorGridlines

、

visible

、

labelRotation

。

QA (Required)

QA（必填）

Assume there are problems. Your job is to find them.

Your first workbook is almost never correct. Treat QA as a bug hunt, not a confirmation step. If you found zero issues on first inspection, you were not looking hard enough. The formulas look fine until you check two of them against source cells.

假设存在问题。你的任务是找出这些问题。

你的第一个工作簿几乎不可能完全正确。将QA视为漏洞排查，而非确认步骤。若首次检查未发现任何问题，说明你检查得不够仔细。公式看起来没问题直到你将其中两个与源单元格对比。

Minimum cycle before "done"

宣告“完成”前的最小检查周期

```
officecli view "$FILE" issues
```
— empty sheets, broken formulas, missing refs.
```
officecli view "$FILE" annotated
```
(sample ranges) — values + types + warnings.

For every Excel error type, query it:

bash

officecli query "$FILE" 'cell:contains("#REF!")'
officecli query "$FILE" 'cell:contains("#DIV/0!")'
officecli query "$FILE" 'cell:contains("#VALUE!")'
officecli query "$FILE" 'cell:contains("#NAME?")'
officecli query "$FILE" 'cell:contains("#N/A")'

```
officecli validate "$FILE"
```
— safe with a resident open;
```
validate
```
flushes pending edits to disk itself.
Visual pass — walk every sheet via the HTML preview. Run
```
officecli view "$FILE" html
```
and Read the returned HTML path. Each sheet renders with charts inline. Scan for
```
###
```
, truncated titles, placeholder tokens (
```
$fy$24
```
,
```
{var}
```
,
```
<TODO>
```
), sliced charts, white-slice pie charts, empty chart anchors — STOP and fix before declaring done. "validate pass" is not delivery; "the preview looks like a real workbook" is delivery. For human preview, run
```
officecli watch "$FILE"
```
(user opens the live preview at their own discretion) or have them open the
```
.xlsx
```
directly in Excel / WPS / Numbers.
Print layout fix (wide tables / multi-chart sheets). When a sheet holds a chart or a wide table and the user will print it, set per-sheet page layout — but match the fit mode to the sheet's height:
bash
```
# Short summary / chart sheet → fit to one page.
officecli set "$FILE" "/Summary" --prop orientation=landscape --prop fitToPage=true
# Tall data table → fit width only (fitToPage=true would crush all rows onto one unreadable page).
officecli set "$FILE" "/Data" --prop orientation=landscape --prop fitToPage=1x0
```
Outcome: charts/wide tables print without mid-chart splits; tall tables stay readable across natural page breaks. Apply to every sheet that holds a chart or a > 8-column table.
If anything failed, fix, then rerun the full cycle. One fix commonly creates another problem.

officecli view issues

view html

are the structural QA pair:

issues

catches broken formulas and empty sheets;

view html

(Read the returned HTML path) catches

###

, truncation, and token leakage. Chart fill colors / theme tints can vary across viewers — spot-check in the user's target viewer when color fidelity matters.

```
officecli view "$FILE" issues
```
—— 检查空工作表、损坏的公式、缺失的引用。
```
officecli view "$FILE" annotated
```
（抽样范围）—— 查看值+类型+警告。

针对每种Excel错误类型进行查询：

bash

officecli query "$FILE" 'cell:contains("#REF!")'
officecli query "$FILE" 'cell:contains("#DIV/0!")'
officecli query "$FILE" 'cell:contains("#VALUE!")'
officecli query "$FILE" 'cell:contains("#NAME?")'
officecli query "$FILE" 'cell:contains("#N/A")'

```
officecli validate "$FILE"
```
—— 在缓存模式下打开文件时也安全；
```
validate
```
会自动将待处理的修改写入磁盘。
视觉检查——通过HTML预览遍历每个工作表。运行
```
officecli view "$FILE" html
```
并查看返回的HTML路径。每个工作表内嵌显示图表。扫描
```
###
```
、截断的标题、占位符令牌（
```
$fy$24
```
、
```
{var}
```
、
```
<TODO>
```
）、切片错误的图表、白色切片的饼图、空图表锚点——停止并修复后再宣告完成。“validate通过”不等于可交付；“预览看起来像真实的工作簿”才是可交付标准。若需用户预览，可运行
```
officecli watch "$FILE"
```
（用户自行打开实时预览），或让用户直接在Excel/WPS/Numbers中打开
```
.xlsx
```
文件。
修复打印布局（宽表/多图表工作表）。当工作表包含图表或宽表，且用户需要打印时，设置工作表级页面布局——但需根据工作表高度选择适配模式：
bash
```
# 短摘要/图表工作表→适配为单页。
officecli set "$FILE" "/Summary" --prop orientation=landscape --prop fitToPage=true
# 长数据表→仅适配宽度（fitToPage=true会将所有行压缩到一页，无法读取）。
officecli set "$FILE" "/Data" --prop orientation=landscape --prop fitToPage=1x0
```
结果：图表/宽表打印时不会中途拆分；长表在自然分页时保持可读。对所有包含图表或超过8列的工作表应用此设置。
若任何检查失败，修复后重新运行完整检查周期。一次修复通常会引发另一个问题。

officecli view issues

view html

是结构性QA组合：

issues

捕获损坏的公式和空工作表；

view html

（查看返回的HTML路径）捕获

###

、截断、令牌遗漏。图表填充颜色/主题色调在不同查看器中可能不同——当颜色保真度重要时，在用户的目标查看器中抽查。

Formula verification checklist

公式验证清单

Pick 2-3 formulas at random. Run
```
officecli get
```
on each. Confirm the formula string is what you intended and
```
cachedValue=
```
is what you expect — arithmetic in your head.
Cached value sanity on every summary cell. Any cell that aggregates (COUNTA / COUNTIF / SUMPRODUCT / INDEX&MATCH) must have a plausible
```
cachedValue
```
. If a progress tracker shows
```
199 / 199 / 100%
```
on a blank template, the cache is lying — re-touch the formula via
```
set
```
(forces recompute) or manually set a correct cached value. Do NOT ship "validate passes but the numbers are fiction".
Spot-check one cell per numeric column.
```
%
```
columns showing integer
```
0.0%
```
throughout means the denominator is wrong or the numerator is cached stale — investigate one cell, fix the pattern.
Ranges include every row: off-by-one on
```
SUM(B2:B12)
```
when data goes to
```
B13
```
is the most common bug.
Cross-sheet formulas (
```
Sheet1!A1
```
) contain no
```
\!
```
. If
```
officecli get
```
shows
```
Sheet1\!A1
```
, the
```
!
```
was shell-corrupted — delete and re-enter via batch/heredoc.
Named ranges (
```
officecli get "$FILE" "/namedrange[1]"
```
) point at what their names claim.
Every
```
/
```
denominator is guarded —
```
IFERROR(x/y, 0)
```
or
```
IF(y=0, 0, x/y)
```
.
Chart data vs source cells: for every chart with inline data, spot-check data points against
```
officecli get
```
of the source cells.
Chart title / series name / legend contain no unreplaced tokens (
```
$...$
```
,
```
{var}
```
,
```
<TODO>
```
). Grep the chart via
```
officecli get /Sheet1/chart[N]
```
.

随机选择2-3个公式。对每个公式运行
```
officecli get
```
。确认公式字符串符合预期且
```
cachedValue=
```
的值符合你的计算预期。
每个汇总单元格的缓存值合理性。任何聚合单元格（COUNTA/COUNTIF/SUMPRODUCT/INDEX&MATCH）的
```
cachedValue
```
必须合理。若进度追踪器在空白模板中显示
```
199 / 199 / 100%
```
，说明缓存错误——需通过
```
set
```
重新处理公式（强制重新计算），或手动设置正确的缓存值。切勿交付“validate通过但数值虚假”的文件。
抽查每个数值列的一个单元格。若
```
%
```
列全部显示整数
```
0.0%
```
，说明分母错误或分子缓存过期——调查一个单元格，修复整个模式。
范围包含所有行：
```
SUM(B2:B12)
```
而数据到
```
B13
```
，这是最常见的错误。
跨表公式（
```
Sheet1!A1
```
）中无
```
\!
```
。若
```
officecli get
```
显示
```
Sheet1\!A1
```
，说明
```
!
```
被Shell解析损坏——删除并通过batch/heredoc重新输入。
命名区域（
```
officecli get "$FILE" "/namedrange[1]"
```
）指向的位置与名称一致。
每个
```
/
```
分母都有保护——
```
IFERROR(x/y, 0)
```
或
```
IF(y=0, 0, x/y)
```
。
图表数据与源单元格一致：对于每个内联数据的图表，抽查数据点与
```
officecli get
```
获取的源单元格值是否一致。
图表标题/系列名称/图例中无未替换的令牌（
```
$...$
```
、
```
{var}
```
、
```
<TODO>
```
）。通过
```
officecli get /Sheet1/chart[N]
```
查看图表内容。

Template QA

模板QA

When editing a template, check for leftover placeholders — they look like content and slip past

validate

bash

officecli query "$FILE" 'cell:contains("{{")'
officecli query "$FILE" 'cell:contains("xxxx")'
officecli query "$FILE" 'cell:contains("TBD")'

编辑模板时，检查是否有遗留的占位符——它们看起来像内容，且能通过

validate

：

bash

officecli query "$FILE" 'cell:contains("{{")'
officecli query "$FILE" 'cell:contains("xxxx")'
officecli query "$FILE" 'cell:contains("TBD")'

Fresh eyes

换个视角检查

When you finish a workbook, open it fresh. Read

view text

/ HTML preview top-to-bottom as if you are a new reviewer — look for formulas, numbers that look off, formatting inconsistency, missing data.

完成工作簿后，重新打开它。像新审阅者一样从上到下查看

view text

/HTML预览——查找公式、异常数值、格式不一致、缺失数据。

Honest limit

诚实的局限性

validate

catches schema errors, not design errors. A workbook can pass

validate

with every number wrong. The checklist above — especially spot-checking formulas against source cells — is how you catch what validation can't.

validate

捕获架构错误，而非设计错误。工作簿可能通过

validate

但所有数值都错误。上述清单——尤其是将公式与源单元格对比抽查——是捕获验证无法发现的问题的方法。

Known Issues & Pitfalls

已知问题与陷阱

The cross-sheet

trap (short)

跨表

陷阱（简短版）

Shells (bash history expansion, zsh splitting) and CLI arg parsing mangle

Sheet1!A1

into

\!

. A formula containing

\!

is silently broken — it renders as literal text and references nothing.

Fix. Use a batch heredoc with single-quoted delimiter (

<<'EOF'

), which disables all shell expansion:

bash

cat <<'EOF' | officecli batch "$FILE"
[{"command":"set","path":"/Summary/B2","props":{"formula":"Revenue!B13"}}]
EOF

Verify. After writing,

officecli get

the cell;

formula=

must show a plain

with no backslash.

Shell（bash历史扩展、zsh拆分）和CLI参数解析会将

Sheet1!A1

中的

解析为

\!

。包含

\!

的公式会无声损坏——按字面文本显示，不引用任何内容。

修复方法。使用带单引号分隔符的batch heredoc（

<<'EOF'

），禁用所有Shell扩展：

bash

cat <<'EOF' | officecli batch "$FILE"
[{"command":"set","path":"/Summary/B2","props":{"formula":"Revenue!B13"}}]
EOF

验证。写入后，使用

officecli get

查看单元格；

formula=

必须显示纯

，无反斜杠。

CLI bug backlog (short)

CLI bug 待办事项（简短版）

CLI constraints and gaps to work around — not defects in the output file.

Chart series are immutable after create — to add/change a series:
```
remove
```
+
```
add
```
with the full series list. (Position is mutable:
```
set chart[N] --prop anchor=
```
/
```
x/y/width/height
```
.)
```
remove chart[N]
```
shifts subsequent indices down; re-add appends at end.
Cross-sheet formula batches run fine through a resident — a prior "deadlocks even at 3-5 ops" caution no longer reproduces. Pure value-set batches stay reliable at 50-80+ ops too. If you ever hit a hang, fall back to a non-resident one-big-batch or individual
```
set
```
. Multiple resident processes on the same file/machine can still contend — expect non-deterministic hangs if another agent/session holds a resident on the same file.
Conditional formatting naming asymmetry — the element name for
```
--type
```
is
```
conditionalformatting
```
; the path suffix is
```
/cf[N]
```
. Use
```
officecli help xlsx conditionalformatting
```
for schema,
```
/cf[N]
```
for paths.
Sheet
position
prop on add — help says Add processes
```
position
```
, but the prop is often ignored. Reorder with
```
officecli move --index
```
/
```
--after
```
/
```
--before
```
after creating the sheet.
remove /sheet[N]
cascade guard — rejects sheet remove/rename when the sheet is referenced by validation / conditional format / sparkline / hyperlink / named range on another sheet. Remove those dependent elements first, then remove the sheet.
Batch JSON rejects cell
color
alias — inside batch
```
props
```
,
```
"color": "FF0000"
```
errors
```
ambiguous in cell context — use 'font.color' (text) or 'fill' (bg)
```
. The CLI at shell level accepts
```
--prop color=...
```
/
```
--prop size=14
```
as aliases on non-cell elements, but inside batch JSON on a cell always write the full dotted name:
```
"font.color"
```
,
```
"font.size"
```
,
```
"font.name"
```
.

CLI的约束和需要规避的漏洞——并非输出文件的缺陷。

图表系列创建后不可修改——若要添加/修改系列：
```
remove
```
+
```
add
```
完整的系列列表。（位置可修改：
```
set chart[N] --prop anchor=
```
/
```
x/y/width/height
```
。）
```
remove chart[N]
```
会将后续索引下移；重新添加会追加到末尾。
跨表公式批处理在缓存模式下运行正常——之前“3-5个操作就会死锁”的警告不再重现。纯设置值的批处理在50-80+操作时仍可靠。若遇到挂起，可回退到非缓存模式的单一大批处理或单个
```
set
```
命令。同一文件/机器上的多个缓存进程仍可能冲突——若其他Agent/会话持有同一文件的缓存，可能出现非确定性挂起。
条件格式命名不对称——
```
--type
```
对应的元素名称为
```
conditionalformatting
```
；路径后缀为
```
/cf[N]
```
。使用
```
officecli help xlsx conditionalformatting
```
查看架构，使用
```
/cf[N]
```
作为路径。
添加工作表时的
position
属性——帮助文档说明Add会处理
```
position
```
，但该属性常被忽略。创建工作表后，使用
```
officecli move --index
```
/
```
--after
```
/
```
--before
```
重新排序。
remove /sheet[N]
级联保护——当工作表被其他工作表的验证/条件格式/迷你图/超链接/命名区域引用时，拒绝删除/重命名工作表。需先删除这些依赖元素，再删除工作表。
Batch JSON拒绝单元格
color
别名——在batch的
```
props
```
中，
```
"color": "FF0000"
```
会报错
```
ambiguous in cell context — use 'font.color' (text) or 'fill' (bg)
```
。Shell级别的CLI在非单元格元素上接受
```
--prop color=...
```
/
```
--prop size=14
```
作为别名，但在单元格的batch JSON中，必须写完整的点式名称：
```
"font.color"
```
、
```
"font.size"
```
、
```
"font.name"
```
。

Renderer caveats (cross-viewer color fidelity)

渲染器注意事项（跨查看器颜色保真度）

officecli view html

is the right tool for structural QA (overflow, truncation, placeholder leakage, layout) — Read the returned HTML path. Some chart rendering details vary across the viewer the end user opens the file in. Observed divergences:

Pie / doughnut fill colors may collapse to a single theme tint in some viewers (slices look "all white" or "all one color"). The file may be fine in the user's target viewer.
Line chart / column chart series colors may drift from the workbook theme in some viewers.
Form-control checkboxes may render as double-boxed in some viewers.

Before calling a color or chart "broken", open the file in the user's actual target viewer. If it looks correct there, the problem is viewer rendering, not data — do not chase it. The CLI's structural checks (

###

, truncation, placeholder text, layout) remain authoritative.

officecli view html

是结构性QA的正确工具（溢出、截断、占位符遗漏、布局）——查看返回的HTML路径。最终用户打开文件的查看器不同，某些图表渲染细节可能不同。已观察到的差异：

饼图/环形图填充颜色在某些查看器中可能统一为单一主题色调（切片看起来“全白”或“同一种颜色”）。文件在用户的目标查看器中可能显示正常。
折线图/柱状图系列颜色在某些查看器中可能偏离工作簿主题。
表单控件复选框在某些查看器中可能显示为双框。

在判定颜色或图表“损坏”前，先在用户的实际目标查看器中打开文件。若在目标查看器中显示正常，则问题出在查看器渲染，而非数据——无需处理。CLI的结构性检查（

###

、截断、占位符文本、布局）仍为权威标准。

Escape layers (shell quoting is above; these are the extras)

转义层（Shell引号在上；以下是额外层）

is the shell layer (single-quote it, above).

\n

\t

in a prop value ARE interpreted by the CLI into a real newline / tab. Two more layers:

JSON level (batch). Standard JSON escapes —
```
"\n"
```
,
```
"\t"
```
,
```
"\""
```
. A real backslash in the final string is
```
"\\\\"
```
.
Excel level.
```
\n
```
in a cell is a real line break — pair with
```
--prop wrapText=true
```
so Excel shows the wrap. Works in a shell-quoted prop directly (
```
--prop value='a\nb'
```
);
```
"\n"
```
inside batch JSON gives the same. When in doubt,
```
officecli get
```
the cell and compare character-for-character.

属于Shell层（需用单引号包裹，见上文）。属性值中的

\n

\t

会被CLI解析为真实的换行/制表符。还有两层转义：

JSON层（batch）。标准JSON转义——
```
"\n"
```
、
```
"\t"
```
、
```
"\""
```
。最终字符串中的真实反斜杠为
```
"\\\\"
```
。
Excel层。单元格中的
```
\n
```
为真实换行——需搭配
```
--prop wrapText=true
```
让Excel显示换行。可直接在Shell引号的属性中使用（
```
--prop value='a\nb'
```
）；batch JSON中的
```
"\n"
```
效果相同。若不确定，使用
```
officecli get
```
查看单元格并逐字符对比。

Other common pitfalls

其他常见陷阱

Pitfall	Fix
`--name "foo"`	All attrs go through `--prop` : `--prop name="foo"`
Guessing a prop name	`officecli help xlsx <element>` — don't improvise
`--prop color=...` on a cell	Ambiguous — use `font.color` (text) or `fill` (bg). Also applies inside batch JSON: always use full dotted names, never shell aliases
`#FF0000` hex colors	Drop the `#` : `FF0000`
`--index` vs `[N]`	`--index` is 0-based (array); `[N]` paths are 1-based (XPath)
Unquoted `[N]` in zsh/bash	Quote every path: `"/Sheet1/row[1]"`
Sheet name with spaces	Quote full path: `"/My Sheet/A1"`
Year showing as `2,026`	`--prop type=string` or `numFmt="@"`
Modifying a file open in Excel	Close it in Excel first
`swap` not reordering sheets	`swap` is for rows/cells. Use `move --after` / `--before` / `--index` for sheets
Cached values missing after write	New formulas get cached values when a human opens the file; `validate` accepts them either way

陷阱	修复方法
`--name "foo"`	所有属性需通过 `--prop` 设置： `--prop name="foo"`
猜测属性名称	使用 `officecli help xlsx <element>` ——不要自行编造
在单元格上使用 `--prop color=...`	存在歧义——使用 `font.color` （文本）或 `fill` （背景）。同样适用于batch JSON：始终使用完整的点式名称，而非Shell别名
`#FF0000` 十六进制颜色	去掉 `#` ： `FF0000`
`--index` vs `[N]`	`--index` 是0-based（数组）； `[N]` 路径是1-based（XPath）
zsh/bash中未加引号的 `[N]`	为所有路径添加引号： `"/Sheet1/row[1]"`
带空格的工作表名称	为完整路径添加引号： `"/My Sheet/A1"`
年份显示为 `2,026`	使用 `--prop type=string` 或 `numFmt="@"`
修改已在Excel中打开的文件	先在Excel中关闭该文件
`swap` 无法重排序工作表	`swap` 适用于行/单元格。使用 `move --after` / `--before` / `--index` 重排序工作表
写入后缺失缓存值	人类用户打开文件时，新增公式会获取缓存值； `validate` 无论有无缓存值都会通过

officecli-xlsx

Original

Translation

OfficeCLI XLSX Skill

OfficeCLI XLSX Skill

Setup

安装配置

⚠️ Help-First Rule

⚠️ 优先求助规则

Shell & Execution Discipline

Shell与执行规范

Requirements for Outputs

输出要求

All Excel files

所有Excel文件通用规范

Visual delivery floor (applies to EVERY workbook)

视觉交付底线（适用于所有工作簿）

Summary / chart / dashboard sheet (small, ≤ ~40 rows): fit to a single page.

摘要/图表/仪表板工作表（内容较少，≤约40行）：适配为单页。

Tall data table (dozens+ rows): fit WIDTH only, let height paginate naturally.

长数据表（数十行以上）：仅适配宽度，高度自然分页。

fitToPage=true here crushes every row onto one page → unreadable (### dates, 5px rows).

此处使用fitToPage=true会将所有行压缩到一页→内容无法读取（日期显示###，行高5px）。

Financial models only — skip this section if you are building a template, tracker, CSV import, or operational sheet

仅适用于财务模型——若构建模板、追踪器、CSV导入或运营工作表，请跳过本节

Common Workflow

通用工作流

Quick Start

快速入门

CSV / bulk import

CSV / 批量导入

gen_batch.py — produces batch chunks of 80 value-set ops each

gen_batch.py —— 生成每个块包含80个设置值操作的批处理数据

Reading & Analysis

读取与分析

Creating & Editing

创建与编辑

Cells and formulas

单元格与公式

Named ranges

命名区域

Charts

图表

Conditional formatting

条件格式

Data validation

数据验证

Other elements (one-liners)

其他元素（单行命令）

Chart Axis-by-Role

按角色编辑图表轴

QA (Required)

QA（必填）

Minimum cycle before "done"

宣告“完成”前的最小检查周期

Formula verification checklist

公式验证清单

Template QA

模板QA

Fresh eyes

换个视角检查

Honest limit

诚实的局限性

Known Issues & Pitfalls

已知问题与陷阱

The cross-sheet ! trap (short)

跨表!陷阱（简短版）

CLI bug backlog (short)

CLI bug 待办事项（简短版）

Renderer caveats (cross-viewer color fidelity)

渲染器注意事项（跨查看器颜色保真度）

Escape layers (shell quoting is above; these are the extras)

转义层（Shell引号在上；以下是额外层）

Other common pitfalls

其他常见陷阱

The cross-sheet
`!`
trap (short)

跨表
`!`
陷阱（简短版）