name: artifact_spreadsheet
metadata: { "includeInPrompt": false }
description: Create, read, edit, fix, or clean spreadsheet files (.xlsx, .xlsm, .csv, .tsv). Use whenever a build task's artifact kind is spreadsheet, or the task names a spreadsheet file and wants something done to it or produced from it, including restructuring messy tabular data into a proper workbook. Covers openpyxl generation, formulas and recalculation, editing existing workbooks, and the validation gates. Not for tasks whose deliverable is a document, report, or web page that merely contains a table.
Spreadsheet artifacts / 电子表格工件
An xlsx is generated with the preinstalled openpyxl library from a
generator script. Keep the generator under .src/: it is the editable
source for future revisions, and the binary is always regenerated from it.
xlsx 由预装的 openpyxl 库通过一个生成脚本产生。把生成脚本保存在 .src/ 下：它是日后修订时可编辑的源文件，二进制文件始终由它重新生成。
| Task | Path |
|---|---|
| Create, or edit with formulas and formatting | openpyxl |
| Quick look at an existing sheet | muse.read (converted to markdown, paged); it carries no cell coordinates, so never plan edits from it |
| Read a workbook's model (formulas AND their values) | two load_workbook passes; see /opt/hatch/skills/artifacts/spreadsheet/references/formulas.md |
| Bulk or messy tabular data in or out | Python csv from the standard library; pip install --break-system-packages pandas when a task genuinely needs it |
| Design, structure, number formats, model conventions | /opt/hatch/skills/artifacts/spreadsheet/references/visual.md |
| Formulas, recalculation, editing existing workbooks | /opt/hatch/skills/artifacts/spreadsheet/references/formulas.md |
| 任务 | 路径 |
|---|---|
| 创建工作簿，或带公式和格式进行编辑 | openpyxl |
| 快速查看既有工作表 | muse.read（转换为 markdown，分页）；它不含单元格坐标，绝不要据此规划编辑 |
| 读取工作簿的模型（公式及其值） | 两次 load_workbook 加载；参见 /opt/hatch/skills/artifacts/spreadsheet/references/formulas.md |
| 批量或杂乱的表格数据导入/导出 | 标准库的 Python csv；任务确实需要时再 pip install --break-system-packages pandas |
| 设计、结构、数字格式、模型约定 | /opt/hatch/skills/artifacts/spreadsheet/references/visual.md |
| 公式、重新计算、编辑既有工作簿 | /opt/hatch/skills/artifacts/spreadsheet/references/formulas.md |
Requirements on every delivered workbook:
对每个交付工作簿的要求：
- Set a non-empty
workbook.properties.titleand a human-readable
filename. Data enters the workbook from the build's gathered content
only; a value you do not have is a blank cell or a question, never an
invented number.
设置非空的workbook.properties.title和人类可读的文件名。数据只能来自构建所汇集的内容；你没有的值就留成空白单元格或向用户提问，绝不可编造数字。 - Write formulas, never precomputed results:
sheet["B10"] = "=SUM(B2:B9)",
not the Python-computed total. The sheet must recalculate when its
inputs change.
写公式，而不是预先算好的结果：sheet["B10"] = "=SUM(B2:B9)"，而不是用 Python 算出的总和。工作表必须在输入变化时能够重新计算。 - Follow the user's spec literally: their exact tab names, exact column
headers, and the formula they spelled out. A redesign that computes
something else fails, however elegant.
严格照用户的规格执行：完全一致的标签页名称、完全一致的列标题，以及他们明确给出的公式。任何计算出另一种结果的重新设计都算失败，无论多么优雅。 - Zero formula errors at delivery: run the recalculation gate below and
fix what it names.
交付时公式错误必须为零：运行下文的重新计算关卡，并修复它点名的问题。 - Document assumptions and hardcoded numbers where the reader will see
them (a cell comment or an adjacent labeled cell), citing the real
source when one exists and saying plainly when the number came from the
user.
在读者能看到的位置（单元格批注或相邻的带标签单元格）记录假设和硬编码的数字；有真实来源时注明来源，数字来自用户时也如实说明。 - A workbook created for someone to fill in gets a short legend naming
the cells to edit and one example row of realistic values; never add an
example row to a file you were asked to edit.
为他人填写而创建的工作簿要附一段简短图例，指出需编辑的单元格，并给出一行符合实际的示例值；对被要求编辑的文件，绝不要添加示例行。
Scripts / 脚本
| Script | What it does |
|---|---|
/opt/hatch/skills/artifacts/scripts/recalc_xlsx.py |
Recalculates the workbook in place through headless LibreOffice and reports every formula-error cell as JSON; mandatory whenever the file contains formulas. errors_found exits 0: read the JSON, not the exit code |
/opt/hatch/skills/artifacts/scripts/validate_xlsx.py |
Opens the workbook read-back: zip integrity, sheet parts, populated-cell counts; do not deliver a link while it fails. A csv output gets no reader check |
| 脚本 | 作用 |
|---|---|
/opt/hatch/skills/artifacts/scripts/recalc_xlsx.py |
通过无头 LibreOffice 就地重新计算工作簿，并以 JSON 报告每个公式出错单元格；文件含公式时为必跑步骤。errors_found 的退出码是 0：请读 JSON，不要看退出码 |
/opt/hatch/skills/artifacts/scripts/validate_xlsx.py |
回读打开工作簿：zip 完整性、工作表部件、非空单元格计数；校验失败期间不要交付链接。csv 输出不做读取检查 |
Verification / 验证
Run recalc_xlsx.py (when formulas exist), then validate_xlsx.py, then
follow /opt/hatch/skills/artifacts/testing/SKILL.md. A clean recalculation proves
the formulas evaluate, not that they are right: spot-check two or three
formulas pull the values you expect before building out a grid.
先运行 recalc_xlsx.py（存在公式时），再运行 validate_xlsx.py，然后遵循 /opt/hatch/skills/artifacts/testing/SKILL.md。重新计算通过只能证明公式可以求值，不能证明公式是对的：在铺开整个网格之前，先抽检两三个公式是否取到你期望的值。