spreadsheets

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Spreadsheets

电子表格处理

Handle tabular data with exact values, minimal diffs, local privacy, atomic writes, and structural validation.

处理表格数据时保证值精确、差异最小化、本地隐私性、原子写入及结构验证。

Invariants

核心准则

Keep precision-sensitive amounts as strings and compute with
```
decimal.Decimal
```
or DuckDB
```
DECIMAL(38, 18)
```
, never binary floats.
Touch only requested rows, columns, formulas, and formatting. Existing file conventions override house defaults.
For newly authored text tables, prefer TSV, UTF-8 without BOM, LF, one trailing newline, lowercase
```
snake_case
```
headers, ISO dates,
```
.
```
decimals, and
```
-
```
nulls.
Read unknown text tables with BOM-tolerant UTF-8; never write a BOM.
Write in place atomically through a sibling temporary file, validate it, then replace the target.
Escape external cells beginning with
```
=
```
,
```
+
```
, or
```
@
```
; a bare
```
-
```
null is exempt. Formula-prefix cells in trusted authored data are observations, not proof of injection.
Keep transaction, bank, exchange, and tax data local. Redact samples unless raw rows were explicitly requested.

对精度敏感的数值保留为字符串，使用
```
decimal.Decimal
```
或DuckDB
```
DECIMAL(38, 18)
```
进行计算，绝不要使用二进制浮点数。
仅修改指定的行、列、公式和格式。现有文件的约定优先于内部默认规则。
对于新建的文本表格，优先使用TSV格式、无BOM的UTF-8编码、LF换行符、末尾一个换行、小写
```
snake_case
```
表头、ISO日期格式、
```
.
```
作为小数点、
```
-
```
表示空值。
读取未知文本表格时使用兼容BOM的UTF-8编码；写入时绝不添加BOM。
通过同级临时文件实现原子性原地写入，验证临时文件后再替换目标文件。
对以
```
=
```
、
```
+
```
或
```
@
```
开头的外部单元格进行转义；单独的
```
-
```
空值无需转义。可信创作数据中带有公式前缀的单元格属于正常数据，并非注入风险。
交易、银行、汇率和税务数据需保留在本地。除非明确要求原始行数据，否则需对示例数据进行脱敏。

Factual Profiling

事实分析

Resolve helper paths from this

SKILL.md

. Profile unknown data before choosing a transformation tool:

uv run "<skill-dir>/scripts/profile.py" <file> --redact-samples

The JSON output has

schema_version: 2

. It reports structural facts, header quality, cardinality/statistics when qsv is available, frequency facts, formula-prefix cells, workbook metadata, and local tool availability. It contains no tool recommendations and does not infer identifiers from uniqueness. Choose the tool from the requested transformation, provenance, output format, and preservation requirements.

Use

--external-data

only when the cells came from an external or otherwise untrusted source and will be written to a formula-capable consumer. With that flag, formula-prefix cells affect

status

; without it, legitimate formulas such as

=SUM(...)

remain factual observations and do not fail the profile.

从本

SKILL.md

解析辅助路径。在选择转换工具前，先对未知数据进行分析：

uv run "<skill-dir>/scripts/profile.py" <file> --redact-samples

输出的JSON包含

schema_version: 2

，会报告结构信息、表头质量、qsv可用时的基数/统计数据、频率信息、带公式前缀的单元格、工作簿元数据以及本地工具可用性。输出中不包含工具推荐，也不会从唯一性推断标识符。需根据需求的转换操作、来源、输出格式和保留要求选择工具。

仅当单元格来自外部或不可信来源且将写入支持公式的应用时，才使用

--external-data

参数。使用该参数时，带公式前缀的单元格会影响

status

；不使用该参数时，合法公式如

=SUM(...)

会被视为正常数据，不会导致分析失败。

Tool Routing

工具选择指南

Need	Tool
Fast structural preview/validation	`uv run scripts/peek.py <file> --redact-samples`
Factual local quality profile	`uv run scripts/profile.py <file> --redact-samples`
Counts, stats, frequencies, select, dedupe	`qsv`
Joins, pivots, aggregation, conversion	DuckDB with `all_varchar = true`
Exact custom transforms	`uv run` Python, stdlib `csv` , `decimal.Decimal`
Any `.xlsx` / `.xlsm` input or output	Read `references/xlsx.md` first
Exact transformation/validation recipes	Read `references/recipes.md` only when needed

Prefer

qsv --cache-threshold 0

where supported. When qsv stdout must remain TSV, use

-o out.tsv

; stdout otherwise defaults to CSV.

需求	工具
快速结构预览/验证	`uv run scripts/peek.py <file> --redact-samples`
本地数据质量事实分析	`uv run scripts/profile.py <file> --redact-samples`
计数、统计、频率、筛选、去重	`qsv`
关联、透视、聚合、格式转换	启用 `all_varchar = true` 的DuckDB
精确自定义转换	`uv run` Python、标准库 `csv` 、 `decimal.Decimal`
任何 `.xlsx` / `.xlsm` 输入或输出	先阅读 `references/xlsx.md`
精确转换/验证方案	仅在需要时阅读 `references/recipes.md`

在支持的情况下优先使用

qsv --cache-threshold 0

。当qsv的标准输出需保持TSV格式时，使用

-o out.tsv

；否则标准输出默认为CSV格式。

Workflow

工作流程

Inspect with
```
peek.py --redact-samples
```
; add
```
profile.py
```
when cardinality, formula prefixes, metadata, or available tooling matters. For a no-shape-change edit, save the peek JSON. For intentional row/schema changes, record the expected width and invariants.
Decide whether formula-prefix cells are dangerous from provenance and output context. Decide the smallest tool that preserves values and formatting. Avoid pandas unless necessary; if used, load every column as strings.
Apply the transformation atomically. For idempotent appends with legitimate duplicate rows, use multiset difference rather than set deduplication.

Validate:

unchanged shape:

peek.py --strict --expect-like <before-report>

;

changed shape:
```
peek.py --strict --expect-columns <n>
```
plus task-specific counts/keys;
authored house TSV: add
```
--house
```
;
formulas:
```
uv run scripts/recalc.py <file.xlsx>
```
and require success.

Report paths, row/column effects, validation, and any workbook features that could not be preserved.

For human output, lead with

### 📊 Spreadsheet — ✅ updated

only after the write and required validation pass, or

### 📊 Spreadsheet — 🔎 inspected, no files written

for read-only work. On required validation failure, use

### 📊 Spreadsheet — ⛔ not deliverable

. Do not paste private profile JSON or decorate cells, headers, formulas, paths, commands, or diagnostics.

使用
```
peek.py --redact-samples
```
检查数据；当基数、公式前缀、元数据或可用工具相关信息重要时，补充使用
```
profile.py
```
。对于无结构变化的编辑，保存peek输出的JSON。对于有意修改行/ schema的操作，记录预期的宽度和核心准则。
根据数据来源和输出场景判断带公式前缀的单元格是否存在风险。选择能保留值和格式的最小工具。除非必要，避免使用pandas；若必须使用，需将所有列加载为字符串。
以原子方式应用转换操作。对于幂等追加且允许重复行的场景，使用多重集差集而非集合去重。
验证：
- 无结构变化：
```
peek.py --strict --expect-like <before-report>
```
  ；
- 有结构变化：
```
peek.py --strict --expect-columns <n>
```
  加上任务特定的计数/键；
- 符合内部规范的TSV：添加
```
--house
```
  参数；
- 公式：运行
```
uv run scripts/recalc.py <file.xlsx>
```
  并确保执行成功。
报告文件路径、行/列影响、验证结果以及所有无法保留的工作簿特性。

对于面向人类的输出，仅在写入操作和必要验证通过后，以

### 📊 电子表格 — ✅ 更新完成

开头；对于只读操作，使用

### 📊 电子表格 — 🔎 已检查，未写入任何文件

。若必要验证失败，使用

### 📊 电子表格 — ⛔ 无法交付

。请勿粘贴隐私性的分析JSON，也不要对单元格、表头、公式、路径、命令或诊断信息进行装饰。

prb-finance

Never hand-edit generated

.pool.tsv

.annual.tsv

, or Markdown reports. After source edits, run

just tsv-check

, then

just cli::write-changed

. Cap private output to counts and file references unless raw rows were requested.

Completion requires the requested artifact, an intentional diff, atomic replacement where applicable, and structural plus domain validation evidence.

绝不要手动编辑生成的

.pool.tsv

、

.annual.tsv

或Markdown报告。源文件编辑完成后，运行

just tsv-check

，再执行

just cli::write-changed

。除非明确要求原始行数据，否则私有输出仅包含计数和文件引用。

任务完成需包含请求的产物、明确的差异、适用场景下的原子替换，以及结构和领域验证的证据。