xlsx

# 工作簿文件处理 本 skill 负责表格文件的读写、结构、公式、格式和显示，不重新决定统计方法、表格内容或报告结论。 ## 1. 确认范围和唯一输入 - Q：只读取回答问题所需的单元格、工作表、公式或文件属性，不创建文件。 - L：锁定唯一输入、目标单元格/区域/工作表、允许修改的对象和不得改动的范围；只核对目标变化、范围外差异和实际引用已改单元格的公式、图表、数据透视表或数据验证规则。 - P：创建或重组工作簿，或者修改共享名称、公式依赖、表格、图表、数据透视表、验证规则、宏或多个工作表；检查所有受影响工作表和共享功能。 - R：用户明确外发、投稿或归档时，在 P 基础上核对完整当前版、可见内容、确认需要保留的隐藏区域、外部链接、宏、重新计算状态和发布要求。 多个同名文件、多个合理当前版、工作表或列定位不唯一时先确认。保留原始文件，只写入用户指定或含义明确的新文件；L 不覆盖唯一原件。 ## 2. 选择文件与工具路径 | 输入或操作 | 执行方式 | 必须保留 | | --- | --- | --- | | `.xlsx` 读写和格式 | 优先使用项目已有且兼容的 `openpyxl`；大批量数据整理可用已有 `pandas` | 工作表顺序、公式、名称、样式、合并区域、图表及未授权对象 | | `.xlsm` | 使用能够保留 VBA 的既有工具；`openpyxl` 读取时设 `keep_vba=True` | VBA 包、控件、外部连接和既有公式；未明确授权时不另存为 `.xlsx` | | `.csv` / `.tsv` | 显式确认编码、分隔符、引号、换行、日期和缺失值规则 | 字段顺序、标识符前导零和原始文本；这两种格式不具备工作表、样式、公式或图表 | | 工作簿内图表 | 本 skill 负责嵌入、位置、引用区域和显示 | 新的统计映射、图型与科学解释由 `publication-figures` 决定 | 不要自行安装、升级或更换 Python、LibreOffice、Excel 或相关包。缺少当前操作所需工具时，说明受影响的功能和用户可选择的准备方式，不静默采用会丢失公式、宏、样式或精度的近似方案。 ## 3. 先确定内容与计算口径 先调用负责表格专业内容的 skill。流行病学与生物统计表使用 `r-biostats` 或既有 Python 主流程及其适用表格规范；本 skill 只把已确认内容正确写入并显示。制作工作簿时同步落实内容结构，不能以文件可打开、重新计算成功或外观整齐代替内容检查。 在写入前选择一种计算口径： - 交互式工作簿：由工作簿承担的派生值使用公式和明确单元格引用，核对依赖、绝对/相对引用、边界行列、除零和循环引用。 - 经验证的统计结果或归档导出：从结果数字唯一来源写入固定值，保留精度和来源；不得在工作簿公式中重新实现统计分析。 - 既有模板：沿用已经确认的公式/固定值结构，除非用户明确要求改变。 只有公式、公式输入、名称、计算设置或其它依赖发生变化时才重新计算。纯文字、批注或格式 L 修改不因工作簿中原本存在公式而触发重新计算。需要重新计算时，仅在兼容的 LibreOffice 已经可用、文件为 `.xlsx`、不存在待更新外部链接且用户给出 workbench 目录时使用： ```text python scripts/recalc.py <输入.xlsx> <输出.xlsx> --work-dir <workbench/runtime> ``` 该脚本使用隔离的 LibreOffice 配置，不写用户级宏或共享设置，也不覆盖输入文件。它不用于 `.xlsm`、外部链接、Excel 专有函数或宏计算；这些情况需要与原工作簿兼容的应用。`soffice` 不可用时只说明缓存公式值尚未刷新，不得自行安装，也不得把静态公式检查称为重新计算完成。 ## 4. 科研表格与模板 - 已验证的父行和分类水平结构在工作表中保持一致。子水平使用单元格的真实缩进属性，不用前导空格，也不把 `row_type`、`indent_level` 等辅助字段显示给读者。 - 统计工作表按复核和阅读问题组织，而不是照搬程序输出。术前、术后或其它时间点可用父级行、子级行和真实缩进分组；同一变量的原始值、分组值或重复编码只在研究目的需要时同时保留。内部检查字段、变量编码、程序状态和模型运行状态不得出现在面向读者的可见工作表中。 - 文件名已含稳定表号和表名时，第 1 行直接写列标题；不重复表题、合并装饰标题行、插入空白分隔行，除非用户或既有模板明确要求。 - 正式统计表把稳定且唯一的 `field_id` 与可重复的显示表头分开；按行键、`field_id` 和列位置逐单元格核对交付表与最终展示数据。多个可见“P 值”合法，重复内部键不合法。 - Excel 复核表可保留便于核对的缩进、分组和适度合并，但不强制模仿 Word 三线表；格式调整不得改变数据、分析分母、缺失显示或字段映射。若工作表作为正式读者表，表头、单位、参考组、`n/事件数`、效应量、95% CI 和 P 值须能独立理解，并如实保留不同指标因缺失产生的不同 `N`。 - 外发模板编辑前列出可见工作表、表格、图表、文本框、批注和明确需要保留的隐藏区域。完成后按内容 skill 提供的必须保留/不得出现要求复核可见文字和指定隐藏区域；不因模板已有就保留过时内部审计文字，也不删除合法品牌、声明、公式或明确不外发的内部工作表。 ## 5. 中性默认格式 保留既有模板。没有模板和用户样式要求时，使用应用默认字体、白底黑字、必要字重、对齐、真实缩进、列宽和冻结窗格建立层级；边框只用于真实表格边界。不自动添加深色表头带、反白文字、彩色首列、总计底色、斑马纹、渐变、仪表盘色块或背景图。数值格式、单位、小数位和缺失显示由内容口径决定，不套用金融模型或其它领域的默认格式。 ## 6. 最少检查与完成条件 每项检查必须对应本次修改可能造成的一种具体错误： - 重新打开目标文件，核对工作表名称/顺序、目标值或公式、数据类型、日期、缺失、前导零、格式和受影响可见区域。 - 公式或依赖变化时，要求受影响依赖链中由本次修改新增的非预期公式错误为零；P/R 再覆盖全部受影响或完整交付范围。与本次修改无关的既有错误单独报告，不冒充新失败。 - `.xlsm` 核对 VBA 包仍存在；CSV/TSV 核对编码、分隔符、字段数和代表性记录；模板核对未授权工作表、公式、名称、图表、批注和隐藏区域未误改。 - 统计表必须同时通过内容 skill 的变量、分母、统计量和字段映射检查，以及本 skill 的文件结构与显示检查；任何一项未验证时只报告部分完成。 L 完成时确认唯一输入与授权范围明确、原文件可恢复、目标修改正确、实际引用位置已核对、范围外差异为零。P/R 只同步实际受影响的内容；未执行的重新计算、宏、外部链接、完整可见内容或发布检查不包装成已通过。