用途
Spreadsheets 是一个处理表格数据的 Agent 技能，当 CSV、TSV 或 Excel（.xlsx）是主要输入或输出时使用。它面向文本表格 schema 的设计与审查，以及表格数据的检视、转换、校验、格式转换和重新计算等任务。
主要原则
技能强调若干不变量：
- 精度敏感的金额保持为字符串，并使用 decimal.Decimal 或 DuckDB DECIMAL(38, 18) 计算，不使用二进制浮点数。
- 只触碰被要求的行、列、公式和格式。既有文件约定优先于通用默认约定。
- 新编写的文本表格优先采用 TSV、UTF-8 无 BOM、LF、结尾一个换行、小写 snake_case 表头、ISO 日期、点号小数和 - 表示空值。
- 读取未知文本表格时使用兼容 BOM 的 UTF-8，写入时不写 BOM。
- 通过同级临时文件原子写入，校验后再替换目标。
- 对外部单元格中以 =、+ 或 @ 开头的内容进行转义；单独的 - 空值除外。可信来源数据中的公式前缀单元格属于事实观察，不构成注入证明。
- 交易、银行、交易所和税务数据视为用户所有；在内部报告中可按规定使用未脱敏样本，对外披露或用户要求时使用 --redact-samples。
事实性画像
在未知数据上先做画像，再选择转换工具：
uv run "<skill-dir>/scripts/profile.py" <file>
输出 JSON 的 schema_version 为 2，报告结构事实、表头质量、qsv 可用时的基数与统计、频次事实、公式前缀单元格、工作簿元数据和本地工具可用性。它不包含工具推荐，也不从唯一性推断标识符。工具选择应基于所请求的转换、数据来源、输出格式和保留要求。仅当单元格来自外部或不可信来源且将写入支持公式的消费者时使用 --external-data；该标志下公式前缀单元格会影响状态，否则合法的 =SUM(...) 等公式仍属事实观察，不会导致画像失败。
工具路由
| 需求 | 工具 |
|---|---|
| 快速结构预览/校验 | uv run "<skill-dir>/scripts/peek.py" <file> |
| 事实性本地质量画像 | uv run "<skill-dir>/scripts/profile.py" <file> |
| 计数、统计、频次、选择、去重 | qsv |
| 连接、透视、聚合、转换 | DuckDB，all_varchar = true |
| 精确自定义转换 | uv run Python、stdlib csv、decimal.Decimal |
| 新建文本表格或有意变更 schema | 先阅读 references/text-table-design.md |
| 任何 .xlsx/.xlsm 输入或输出 | 先阅读 references/xlsx.md |
| 精确转换/校验配方 | 仅在需要时阅读 references/recipes.md |
支持时优先使用 qsv --cache-threshold 0。当 qsv 标准输出需要保持 TSV 时使用 -o out.tsv，否则标准输出默认 CSV。
工作流程
- 新建文本表格或有意变更 schema 时，阅读 references/text-table-design.md，记录预期的表格接口与迁移范围。
- 用 peek.py 检视。当基数、公式前缀、元数据或可用工具重要时，追加 profile.py。无形状变更的编辑保存 peek JSON；有意的行或 schema 变更记录预期宽度与不变量。
- 根据来源和输出上下文判断公式前缀单元格是否危险。选择能保留值与格式的最小工具，避免不必要的 pandas；若使用则将所有列按字符串加载。
- 原子地应用转换。对于含合法重复行的幂等追加，使用多重集差异而非集合去重。
- 校验：
- 形状未变：peek.py --strict --expect-like <before-report>。
- 形状改变：peek.py --strict --expect-columns <n>，加上任务特定的计数与键校验。
- 自编规范 TSV：追加 --house。
- 公式：uv run "<skill-dir>/scripts/recalc.py" <file.xlsx>，并要求成功。
- 报告路径、行/列影响、校验结果，以及无法保留的工作簿特性。
输出约定
面向人的输出中，仅在写入和必要校验通过后以 ### 📊 Spreadsheet — ✅ updated 开头；只读工作使用 ### 📊 Spreadsheet — 🔎 inspected, no files written；必要校验失败时使用 ### 📊 Spreadsheet — ⛔ not deliverable。仅在实质性支持报告时附上画像 JSON，JSON、单元格、表头、公式、路径、命令与诊断信息保持不加修饰。
生成的财务产物
生成的财务表格和报告视为输出产物。编辑前先确定其源输入以及项目提供的校验与再生成命令，只编辑源、校验源，然后重新生成受影响的输出。不要手工编辑生成的表格或报告。除非原始行实质性支持任务或被要求，财务输出限于计数和文件引用。将财务数据发送到 Agent 工作区之外前，执行外部披露审查。
完成标准
完成需要所请求的产物、有意的差异、适用时的原子替换，以及结构性和领域校验证据。新建或变更的文本表格 schema 还需要定义表格接口，并完整迁移受影响的生产者、消费者、现有行、生成产物和校验器。