$npx -y skills add woodfishhhh/EZ_math_model --skill xlsxUse when EZ_math_model needs to read, preview, clean, write, or summarize CSV, XLS, or XLSX attachments and result tables for modeling tasks.
| 1 | # xlsx — 表格数据读写 |
| 2 | |
| 3 | ## 何时使用 |
| 4 | |
| 5 | - 读取 `.xlsx`、`.xls`、`.csv` 附件。 |
| 6 | - 写出 `results/qN_summary.csv` 或 `.xlsx`。 |
| 7 | - 生成 `intake.json.attachments[i].preview`。 |
| 8 | - 大 CSV 需要分块处理。 |
| 9 | |
| 10 | ## 预览契约 |
| 11 | |
| 12 | 输出到 intake preview: |
| 13 | |
| 14 | ```json |
| 15 | { |
| 16 | "shape": [1024, 8], |
| 17 | "columns": ["timestamp", "value"], |
| 18 | "head_3": [{"timestamp": "2024-01-01", "value": 12.3}], |
| 19 | "missing_per_col": {"value": 5} |
| 20 | } |
| 21 | ``` |
| 22 | |
| 23 | ## 优先链路 |
| 24 | |
| 25 | 1. `pandas` 读写和清洗。 |
| 26 | 2. `openpyxl` 写公式或保留 Excel 格式。 |
| 27 | 3. 宿主 `xlsx` skill 处理公式刷新、LibreOffice 重算等高级场景。 |
| 28 | |
| 29 | ## pandas 模板 |
| 30 | |
| 31 | ```python |
| 32 | import pandas as pd |
| 33 | |
| 34 | df = pd.read_excel("attachments/data.xlsx") |
| 35 | preview = { |
| 36 | "shape": list(df.shape), |
| 37 | "columns": df.columns.tolist(), |
| 38 | "head_3": df.head(3).to_dict("records"), |
| 39 | "missing_per_col": {c: int(n) for c, n in df.isna().sum().items() if n > 0}, |
| 40 | } |
| 41 | df.to_csv("results/q1_summary.csv", index=False, encoding="utf-8") |
| 42 | ``` |
| 43 | |
| 44 | CSV 编码尝试顺序:`utf-8` → `gbk` → `gb2312` → `latin-1`。 |
| 45 | |
| 46 | ## 大文件协议 |
| 47 | |
| 48 | - `pd.read_csv(path, chunksize=200_000)`。 |
| 49 | - 提前指定 `dtype`。 |
| 50 | - 必要时抽样 5% 做 EDA。 |
| 51 | - 处理完及时释放分块 DataFrame。 |
| 52 | |
| 53 | ## 失败诊断 |
| 54 | |
| 55 | | 情况 | 处理 | |
| 56 | |---|---| |
| 57 | | 编码全失败 | 写诊断,建议用户提供 utf-8 版 | |
| 58 | | 列名含非法字符 | 生成 ASCII 安全别名并保留 `column_alias.json` | |
| 59 | | 文件超过 1GB | chunksize 分块处理 | |