findscripter 何时使用
当用户要创建、编辑或分析 .xlsx 工作簿时使用。按任务选库分流：
- 读取/分析数据：用 pandas（
read_excel预览、统计、批量导出）。 - 写公式/格式/财务模型：用 openpyxl（单元格、公式字符串、字体、填充、列宽、多工作表）。
- 凡含公式：openpyxl 只写公式字符串不计算值，必须跑
recalc.py用 LibreOffice 重算并扫错。
不该用的边界：
- 目标是 Word（
.docx）或 PPT（.pptx）→ 用对应文档技能，不用本技能。 - 只需纯文本/一句话答复、无表格结构 → 直接回正文。
- 只想审计/排查已有表的公式错误而非生产新表 → 用
spreadsheet-formula-auditor。 - 更新既有财务模型的特定结构 → 优先
financial-model-updater。
步骤 / 指令
通用工作流：
- 选库：分析用 pandas，公式/格式用 openpyxl。
- 创建/加载：新建
Workbook()或load_workbook(path)。 - 修改：写数据、公式、格式。
- 保存：
wb.save(path)。 - 重算（含公式时必做）：
python recalc.py output.xlsx [timeout_秒]。 - 校验改错：脚本返回 JSON；
status为errors_found时读error_summary定位并修复，再重算，直到零错误。
核心铁律——用公式，不要硬编码计算结果。让 Excel 保持可重算：
- 错：
sheet['B10'] = df['Sales'].sum()（写死 5000） - 对：
sheet['B10'] = '=SUM(B2:B9)' - 对：
sheet['C5'] = '=(C4-C2)/C2'、sheet['D20'] = '=AVERAGE(D2:D19)'
所有合计、百分比、比率、差值同理，源数据变了表能自动重算。
交付硬要求：
- 零公式错误：交付前不得残留
#REF! / #DIV/0! / #VALUE! / #N/A / #NAME?。 - 保留既有模板：改他人文件时，精确沿用其原有格式/样式/约定，模板约定永远压过下列默认规则。
财务模型默认规范（用户或既有模板另有规定则从之）：
- 颜色：蓝字
(0,0,255)=硬输入；黑字=公式计算；绿字(0,128,0)=同簿跨表链接；红字(255,0,0)=外部文件链接；黄底(255,255,0)=需关注的关键假设。 - 数字格式：年份按文本（"2024" 非 "2,024"）；货币
$#,##0且表头标单位（"Revenue ($mm)"）；零显示为-（如$#,##0;($#,##0);-）；百分比默认0.0%；估值倍数0.0x；负数用括号(123)。 - 假设独立成格，公式引用单元格而非写死：用
=B5*(1+$B$6)不用=B5*1.05。 - 硬编码须注明来源（旁注/批注）：
Source: [系统/文档], [日期], [具体引用], [URL]。
公式自检清单：先验 2–3 个引用是否取到正确值再铺开；注意列映射（第 64 列=BL 非 BK）与行偏移（DataFrame 第 5 行=Excel 第 6 行，1 起索引）；用 pd.notna() 防 NaN；用 / 前查分母防 #DIV/0!；跨表引用用 Sheet1!A1 格式；先小范围测再批量；含零/负/极大值边界测试；防意外循环引用。
示例
读取分析（pandas）：
import pandas as pd
df = pd.read_excel('file.xlsx') # 默认首个工作表
all_sheets = pd.read_excel('file.xlsx', sheet_name=None) # 全表为 dict
df.head(); df.info(); df.describe()
df.to_excel('output.xlsx', index=False)
新建带公式与格式（openpyxl）：
from openpyxl import Workbook
from openpyxl.styles import Font, PatternFill, Alignment
wb = Workbook(); sheet = wb.active
sheet['A1'] = 'Hello'; sheet.append(['Row', 'of', 'data'])
sheet['B2'] = '=SUM(A1:A10)'
sheet['A1'].font = Font(bold=True, color='FF0000')
sheet['A1'].fill = PatternFill('solid', start_color='FFFF00')
sheet['A1'].alignment = Alignment(horizontal='center')
sheet.column_dimensions['A'].width = 20
wb.save('output.xlsx')
编辑现有文件（保留公式与格式）：
from openpyxl import load_workbook
wb = load_workbook('existing.xlsx'); sheet = wb.active # 或 wb['SheetName']
sheet['A1'] = 'New Value'
sheet.insert_rows(2); sheet.delete_cols(3)
new = wb.create_sheet('NewSheet'); new['A1'] = 'Data'
wb.save('modified.xlsx')
重算并校验（含公式时必做）：
python recalc.py output.xlsx 30
返回 JSON 形如：
{ "status": "success", "total_errors": 0, "total_formulas": 42,
"error_summary": { "#REF!": { "count": 2, "locations": ["Sheet1!B5"] } } }
注意事项
- 含公式必跑 recalc.py：openpyxl 写的是公式字符串、值为空，不重算交付会让单元格显示空白或旧值。脚本需 LibreOffice（首次运行自动配置）。
- 一律用绝对路径；调用间工作目录可能被重置。
- openpyxl 单元格 1 起索引（row=1,col=1 即 A1）。
- 读计算值用
load_workbook(path, data_only=True)；但以此打开再保存会用值永久覆盖公式，切勿误存。 - 大文件：读用
read_only=True，写用write_only=True。 - pandas 防类型推断坑：
dtype={'id': str}；按列读usecols=[...]；日期用parse_dates=[...]。 - 代码风格：Python 代码精简、少注释少 print；但 Excel 单元格内要给复杂公式/关键假设加批注、注明数据源。
- 处理外部来源文件前确认无加密/权限限制；产物不替代环境内的验证与专家复核，缺输入/边界时先问清。
互见
- requires：无。
- related：
spreadsheet-formula-auditor（专做公式错误审计与排查）、csv-data-cleaner（导出/读入前清洗 CSV 数据）。 - combines_with：
financial-model-updater（更新既有财务模型结构）、financial-statements-generator（生成三大报表后用本技能落表与格式化）。
采编自 sickn33/antigravity-awesome-skills（MIT）。