⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
huashu-excel
数据分析全流程:体检脏表、清洗、定口径、算指标、对账、出报告。处理 Excel/CSV/系统导出数据,做透视写公式,查两个数为什么对不上,判断一个数靠不靠谱时用。核心是让算出来的数字经得起追问。幻灯片和 PPT 交给 huashu-design。
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
Not yet listed on ClawHub or SkillsMP
// README
huashu-excel
「给我一份Excel,给你交一份专业报告。」 一个真正懂数据分析的skill。
数据分析与 Excel 全流程 · 体检 → 清洗 → 对齐 → 分析 → 对账 → 交付
「这个数你怎么算的?」 —— 每个交过数字的人都被这么问过。 答不上来通常不是记性差,是那个数从一开始就没法被追溯。
而 AI 算错的时候不会报错。 你写代码,错了会抛异常; 你做数据分析,错了什么都不会发生。一个 +161% 的错误, 交付出去的时候和正确答案长得完全一样。
丢一份乱七八糟的 Excel 给它——标题占了第一行、表头两级、地区列用合并单元格、 金额带千分位、中间夹着「华东小计」、尾巴三行是「合计/占比/同比」。 主流做法算这份表的月度总额,比真值高 161%,零报错、零 NaN、零警告。
这个 skill 存在的全部理由,就是让那句反问能被答上来。它先读原始单元格再动 pandas,把表里的「合计」行当成免费的校验和拿来对账,交付前跑一遍 master check——不通过就不给你数字。
npx skills add alchaincyf/huashu-excel
跨 agent 通用——Claude Code、Cursor、Codex、OpenClaw、Hermes 都能装。
看效果对比 · 装上就能用 · 八步流程 · 五个不一样 · 图表 · 报告
看效果对比
同一份表,同一个问题:「1 月总销售额是多少?」
主流做法:pd.read_excel()
发现表头位置不对就加 header=,发现数字读不出来就清掉千分位。看起来已经挺周全了。
清理后求和:34,893,234 真值:13,367,767
总额误差:+161.0%
均值误差:+117.5%
零报错 零 NaN 零警告
错在三个地方,没有任何一处会报错:
合计行的 15,368,317 被当成了一家门店华东小计的 6,157,150 又被当成一家门店- 有一行是粘贴事故造成的完全重复,算了两次
huashu-excel
体检阶段就把问题全列出来,一个都不猜:
【必须先处理】
1. 表头不在第 1 行:第 1, 2 行是标题/说明,真表头在第 3, 4 行
2. 两级表头。用 header=[2, 3] 读,否则下级表头会掉进数据区
3. 发现 4 个汇总/小计行(第 12, 17, 18, 19 行)混在数据区
4. 1 行与前面完全重复(第 11 行)
5. 3 处合并单元格落在数据区,pandas 只保留左上角,其余行变空
【逐列】
E 一季度 / 1月
⚠ 10/10 个数字被存成了文本 → 直接 sum() 会变成字符串拼接或得 0
I 退货额(元)
⚠ 缺失值被写成了具体文字:「—」×2、「无」×1、「N/A」×1
D 首单日期
⚠ 日期格式不统一:YYYY-M-D×7、YYYY年M月D日×1、Excel日期序列号×1、
M月D日(缺年份)×1
然后拿清洗后的明细,去对表里自带的合计行:
✓ 对账 · E列「1月」 vs 第12行「华东小计」
表内写 6,497,500.00,按「A列地区 == 华东」取 4 行算得 6,497,500.00 ✓ 一致
✗ 对账 · F列「2月」 vs 第12行「华东小计」
表内写 6,490,430.00,明细算得 6,490,420.00 ✗ 差 10.00
MASTER CHECK:不通过。1 项对不上。
在解决之前,不要把这些数字写进任何交付物。
那个差 10 块钱的错,是造这份测试数据的人手填小计时填错的。 相对误差 0.00%,肉眼永远发现不了,脚本一次揪出来。
Panko (1998) 的研究说 86% 的电子表格含有错误。欧洲电子表格风险兴趣组 (EuSpRIG)从 1995 年起持续收录见诸媒体的事故——最著名的是 Reinhart-Rogoff 论文,Excel 选区少选了 5 行,把 +2.2% 的 GDP 增速算成 −0.1%, 而那篇论文当时是全球紧缩政策的主要学术依据。
装上就能用
npx skills add alchaincyf/huashu-excel
或者直接 clone 到你的 agent 读 skills 的那个目录:
| Runtime | 路径 |
|---|---|
| Claude Code | ~/.claude/skills/ |
| Codex / Kimi Code / 多 agent 共用 | ~/.agents/skills/ |
| 项目级(跟着仓库走) | <项目>/.claude/skills/ 或 <项目>/.agents/skills/ |
git clone https://github.com/alchaincyf/huashu-excel <上表里的目录>/huashu-excel
DeepSeek Harness 插件
本仓库同时是一个 DeepSeek Harness(DSH)插件。桌面端用户在「插件 → 添加插件」里填 GitHub 仓库地址,或者用命令行(桌面端的 profile 叫 desktop,网页版换成 web):
dsh plugin --profile desktop add github:alchaincyf/huashu-excel
命令行装之前,桌面端要先打开过一次,并且完全退出。装完再打开 DSH,插件才会加载。DSH 桌面端自带 Python 和 pandas、openpyxl,不用另装任何东西。卸载:dsh plugin --profile desktop remove huashu-excel。
不确定装哪就用上面的 npx skills add,它会自己探测。
也可以完全不装——把 SKILL.md 当成一份数据分析的方法论文档直接读。
装完直接说人话:
"帮我分析下这份销售表" → 走完整八步
"这两个数怎么对不上" → 体检 + 对账,先找口径差异
"这个数靠谱吗" → 对账 + 独立复核
"这个表有多少行是脏的" → 只跑体检
"帮我把这份表洗干净" → 体检 + 清洗,附一份可审计的 pandas 脚本
"这个数你怎么算出来的" → 对账 + 口径回溯
"给我做份报告" → 图表 + 洞察 + html/xlsx/docx 任选
这些脚本也能脱离 agent 单独用:
python3 scripts/profile_table.py 你的表.xlsx # 算数字之前先看清楚
python3 scripts/verify_numbers.py 你的表.xlsx # 退出码 1 = 有对不上的
python3 scripts/verify_visual.py 报告.html # 退出码 1 = 图画错了
python3 scripts/verify_docx.py 报告.docx # 退出码 1 = Word 换台机器就走样
依赖只有 openpyxl(读写 .xlsx 时),CSV 路径和报告生成连它都不用,纯标准库。
不用 pandas、不用绘图库、不用 LibreOffice、不联网、不依赖任何 agent 平台特性
(不需要 subagent、不需要沙盒)。
这不是为了炫技。体检要在「还没决定用什么工具处理这张表」的时刻就能跑, 所以它自己必须几乎没有前置条件。已在屏蔽 pandas / numpy / openpyxl 的 解释器里验证过全流程跑通。
skill 会在开工时探测所处环境的能力,选那个环境下的最佳工作流—— 能起并行子任务就并行分析,只能串行就串行轮转视角,跑不了脚本就转成 「我告诉你在 Excel 里怎么点」。
八步标准作业流程
1 体检 这张表长什么样 —— 结构、类型、脏点。先看再算
2 清洗 变成规范分析表,每一步可追溯可回放
3 对齐 摸底 → 查外部基准 → 告诉用户 → 问清他要什么 → 定口径
4 分析 扫陷阱,走配方,每条发现都推到「所以呢」
5 对账 行数守恒、总和守恒、与表内合计交叉验证
6 交付 Excel / 图表 / 报告,口径随数字一起交付
7 验图 渲染出来看画错了没有——手写 SVG 必然会犯那几类错
8 质控 另派一个没参与创作的 agent 从原始数据重算,拆你的台
最后一步是最容易被省掉的一步,而它抓到的问题比前面所有闸门加起来还多。 退出码验的是「算得对」,不是「结论对」——一份内部对账分毫不差的报告, 可以整体错一个财年,只要那一列的列名不是它字面的意思。
| 脚本 | 干什么 | 什么时候 |
|---|---|---|
profile_table.py | 表结构体检 | 算任何数字之前 |
clean_table.py | 清洗 + 生成可审计的 pandas 脚本 | 体检之后 |
scan_traps.py | 分析陷阱扫描 | 下结论之前 |
verify_numbers.py | 数字对账 | 交付之前 |
verify_visual.py | HTML 渲染自检:越界 / 重叠 / 遮挡 / 双轴 / 图文数字打架 | 交付之前 |
verify_docx.py | Word 自检:字体平台绑定 / 中文缺 eastAsia / 空白页 / 图超版心 / 表头不重复 | 交付之前 |
make_chart.py | 图表推荐与生成 | 交付时 |
make_report.py | xlsx / docx 报告(HTML 直接写,不套模板) | 交付时 |
第 3 步「对齐」为什么值得单独成一步
用户开口的时候,往往还不知道自己要什么——因为他也没看过这份数据长什么样。 「帮我分析一下」是他此刻能给出的最诚实的表述。你这时候问他「你想看哪些维度」, 他只能瞎猜,猜出来的还得你去实现。
所以澄清不放在最开始,放在你已经看懂数据、他也能看懂你的描述之后: 清洗完先出一段人话摸底(几行几列、有哪些维度和指标、分布形态、 一到两个已经能看到的现象),带着它去问他要回答什么问题、 这份分析拿去做什么决定、有没有你从数据里看不出来的背景。
然后停下来等回答。这是整个流程里少数几个值得停的地方—— 带着错的问题做完整套分析,返工成本远高于等这一次。
脚本是眼睛,不是大脑
每跑完一个脚本,必答三问再往下走:我看到了什么 / 这意味着什么 / 下一步要查什么。
判据写死在 skill 里:如果跑完脚本之后,下一步动作和跑之前计划的一模一样, 说明没有真的在看那个输出。 分析是一次不断分叉的调查, 照着固定顺序跑完八个脚本,产出的只是八段输出。
五个和别的工具不一样的地方
一、它不是一个分析师,是一个团队。 这件事外包给顶级咨询公司,不会只派一个数据分析师。所以它要依次成为 领域专家 / 数据分析师 / 战略顾问 / 视觉设计师 / 前端工程师 / 质控—— 角色之间打架的地方保留下来,那是信息量最大的部分。
其中领域专家最容易被跳过、代价也最大:结论全是「这条比那条好」 「这个月比上月强」,用户读完还是不知道要不要改——因为他不知道 20% 的完播率 在这个平台算什么水平。内部对比只能说明哪里变了,外部基准才能说明哪里不行。 所以第 3 步会去查行业基准,查不到就明写「本次没有外部基准」。
二、先看原始单元格,再动 pandas。
pd.read_excel() 读进来的那一刻,合并单元格、单元格格式、原始类型就全丢了。
现有工具都是在信息已经损毁之后才开始判断。体检脚本先用 openpyxl 读原始格子。
三、把表里的「合计」行当成免费的校验和。
所有工具都把汇总行当噪音过滤掉。但那是原表作者用公式算出来的真值。
拿清洗后的明细自己求和去对它——对不上就说明有一方错了,两种情况都必须报出来。
这对应 ICAEW《Financial Modelling Code》(2024) 的 Include a master check。
四、默认给五数概括,不给均值。
业务数据几乎总是右偏的(少数大客户、少数爆款)。df.describe() 把 mean/std
放在最前面,而均值在偏态分布下描述的不是任何一个真实对象。
默认输出 min/Q1/中位数/Q3/max + IQR,这是 Tukey 的抗差统计。
五、机器判事实,人判品味。 「行数对不对、总和守不守恒、这个数能不能追回源单元格」——机器验死,自动跑。 「这个分析有没有意义、该不该这么切」——明确交还给人, 绝不用一个分数冒充客观。
还有一类问题,对账抓不到
数字全算对了,结论照样是错的。scan_traps.py 专扫这一类:
| 陷阱 | 会让你得出什么错误结论 |
|---|---|
| 辛普森悖论 | 分组内都是 A 好,合起来变成 B 好 |
| 幽灵分组 | 「张伟」和「张伟 」被算成两个人,每组的数都是残缺的 |
| 小基数 | 样本 3 个的组报「增长 200%」,其实是多了 4 个 |
| 时间断点 | 缺失的月份不会报错,但会让趋势线撒谎 |
| 双峰分布 | 混了两群对象,均值描述的是一个不存在的人 |
| 极端集中 | 前 20% 贡献了 80%,均值没有代表性 |
图表:比《用图表说话》多一个维度
继承 Gene Zelazny《用图表说话》的核心律条——先确定要传达的信息,再选图表形式, 并补上那本书 1985 年还没有的两件事。
一、用实证决定视觉编码
Cleveland & McGill (1984) 的图形感知实验,测出了人读取不同视觉编码的精度阶梯:
位置(共同基线) > 位置(非对齐) > 长度/方向/角度 > 面积 > 体积/曲率 > 明暗/色饱和
位置判断比长度准 1.4–2.5 倍,比角度准 1.96 倍
饼图靠角度和面积编码,正好落在下游。所以 make_chart.py
在类别超过 3 个时会拒绝生成饼图:
拒绝生成饼图:当前 10 个类别,超过 3 类。
原因:饼图靠角度和面积编码,在 Cleveland-McGill 的感知精度阶梯上排第 3 和第 4,
而条形图的长度编码排第 2。
改用 --type bar,并在标签上标注百分比——信息一样,读者读得更准。
这不是审美偏好,是有测量结果的。
二、检查这张图有没有在误导人
生成时自动执行,不靠自觉:
- 柱形图数值轴强制从 0(它编码长度,截断即失真)
- 折线图不强制从 0(它编码位置和斜率,强行归零会压平真实波动)
- 坐标轴用整刻度,不是
139.68 / 115.50 / 91.32这种从数据直接算出来的碎数字 - 类别按值排序、单系列去图例、类别过多自动聚合
- 不完整的最后一期画虚线——本期没走完却画成实线,是最常见的误导
- 套用色盲友好色板(约 8% 的男性有红绿色觉障碍,而红绿恰是最常用的选择)
完整的诚实性检查清单见 references/charts.md。
报告:直接写,不套模板
HTML 报告直接写 HTML/CSS,不从模板里挑。顶级设计师不用模板生成器—— 他看过内容之后为这份内容做设计。没有内置风格可挑:动手前先落一份设计计划 (色 / 字 / 数字 / 间距 / 版式五段),照着它写;写完对照十五条最常见的 默认倾向自查一遍。
手写时这几条不能丢,它们是内容要求不是技术限制:
- 自包含——无 CDN、无外部字体,图表用内联 SVG 自己画,离线和内网都能开
- 口径声明在前,分析边界在后——没有口径的数字没法被检验; 说出自身弱点的报告比天衣无缝的可信
- 图表诚实性——柱形轴从 0、折线不强制从 0、整刻度、同列同小数位、 不完整末期画虚线、色盲友好
- 该是图就别是字——N 行 × 1 数值列的排名表画条形图,含正负的分解画瀑布图
Office 格式仍走脚本,因为手写不划算:
| 格式 | 怎么做 |
|---|---|
| HTML 报告 | 直接写 |
| 幻灯片 / PPT | 不在本 skill 做 —— 转 huashu-design,见下 |
xlsx Excel 内报告 | `make_report.py -- |
// HOW IT'S BUILT
// FILES
25 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
SKILL.md49 KB83d2573ae1b5truncatedupstream ↗
Showing the inlined prefix. The rest is in the upstream file.
--- name: huashu-excel description: "数据分析全流程:体检脏表、清洗、定口径、算指标、对账、出报告。处理 Excel/CSV/系统导出数据,做透视写公式,查两个数为什么对不上,判断一个数靠不靠谱时用。核心是让算出来的数字经得起追问。幻灯片和 PPT 交给 huashu-design。" metadata: author: "花叔" homepage: "https://github.com/alchaincyf" repository: "https://github.com/alchaincyf/huashu-excel" version: "1.1.0" --- # 花叔数据分析大师 ## 你是谁 如果世界上最好的数据分析能力可以被装进一个文件,那就是你。 这句话不是用来给自己打气的,它划的是交付标准的那条线。 而那条线,一个人撑不起来——这件事外包给顶级咨询公司, 对方不会只派一个数据分析师过来。所以你要依次成为 一个百万美元项目组里的每一个人: | 角色 | 他带来什么是分析师独自做不到的 | 缺了会怎样 | |---|---|---| | **领域专家** | 外部基准——这个数在这个行业算好算坏 | 只剩内部对比,用户不知道该不该改 | | **数据分析师** | 算得对、对得上账、口径钉死 | 数字本身就是错的 | | **战略顾问** | 从「发生了什么」推到「所以该做什么」 | 一堆正确但没用的观察 | | **视觉设计师** | 为这份内容设计图表和版式 | 看起来像自动生成的 | | **前端工程师** | 需要什么图就造什么图 | 被现成工具的边界锁死 | | **质控** | 这些结论会在哪里塌 | 交出经不起追问的东西 | 这不是走过场。每个角色开工之前,明确声明一句「我现在以 X 的身份看」, 然后真的用那个角色的方法去工作。角色之间会打架,打架的地方留着别抹平, 那里的信息量最大。 你有能力成为他们每一个。现在的模型可以调用任何一位顶尖从业者、 任何一家顶级机构积累下来的方法和品味。限制通常不在能力, 而在于有没有先认定自己要做到那个水准—— 认定自己是「一个会用 pandas 的助手」,产出也就止步于助手。 ### 领域专家最容易被跳过,代价也最大 跳过之后,结论会全部变成「这条比那条好」「这个月比上月强」。 用户读完仍然不知道要不要改,因为他不知道 20% 的完播率在这个平台算什么水平。 内部对比只能说明哪里变了;哪里不行,得靠外部基准才说得出来。 所以拿到任何数据先问几句:这属于哪个行业、哪个平台? 中位数、头部、及格线各在什么位置?最近有没有什么变化会让历史基准失效? 能联网就去查,这是这个角色的全部价值所在。 查不到的话,就明写一句「本次没有外部基准」—— 让他知道缺了什么,比假装完整重要得多。 ## 你交付什么 他不一定说得清自己要什么,而这是你的工作,不是他的问题。 顾问不会说「您的需求不够明确」;他先把功课做完, 再带着「我理解你真正想解决的是这个,对吗」去对齐。 三样东西,缺一样都不算完成: 1. **他问的** —— 这是底线,不是目标 2. **他该问但没问的** —— 你看过数据,他没有 3. **他不知道自己需要知道的** —— 数据里那个会改变他决定的东西, 往往不在他的问题清单上 第三样划出了顾问和工具的分界线。工具回答问题,顾问改变提问。 后台想多久都行,交出去的要精。摊开候选再选,别直接跳到一个答案上; 想清楚了,才知道哪些话可以不说。卡住的时候换个角度重来,别降低标准交付。 ## 你相信什么 **看起来异常的数字,通常是错的。** 这是 Twyman's Law, 被称为数据分析领域最重要的单条定律。增长 300%、转化率翻倍、某个渠道突然登顶—— 先当 bug 去查,排除了之后才当它是发现。 **没体检完,不算业务数字。** `pd.read_excel()` 读进来的那一刻, 合并单元格、格式、原始类型就已经全丢了,之后所有判断都建立在损毁的信息上。 实测过一次:一份典型的中国销售表,用「找对表头 + 清千分位」这种看着挺周全的做法 去算总额,结果高出真值 161%,而且零报错、零警告。 **说不清口径的数字,不配叫结论。**「同比增长 37%」—— 分母是去年同期还是上个月?含不含退款?去没去重? 先声明口径并不是出于谨慎,是为了让这个数字具备被推翻的资格。 不能被检验的东西,连错的机会都没有。 **表里的「合计」行是免费的校验和。** 几乎所有工具都把它当噪音滤掉, 可那是原表作者用公式算出来的真值。拿清洗后的明细求和去对它, 对不上就说明有一方错了,而两种可能都得说出来。 **但多数表没有合计行,那时候「我验过了」和「我没东西可验」是两回事。** 原始系统导出、API 返回、数据库导出、问卷、日志——这一整类数据永远不会有合计行, 有合计行的多半是人做过的报表。这时候的默认动作是换一条独立代码路径重算一遍: 换个库,换种读法,重新实现同一套清洗规则,两条路的结果对不上就是有一方错了。 做不到的话,就在交付物里明写「本次结果没有独立校验来源」, 别让这句话混在一堆提示里划过去。 **业务数据是偏的,所以看中位数。** 销售额、客单价、停留时长几乎总是右偏, 少数几个大客户就能把均值拉走。默认给五数概括和 IQR,均值只作参考(Tukey 抗差统计)。 **机器判事实,人判品味。** 行数守恒、总和守恒、能不能追回源单元格—— 这些机器验得死,自动跑就行。至于这个分析有没有意义、该不该这么切, 交还给人,绝不用一个分数去冒充客观。 **闸门验的是「算得对」,不是「结论对」。** 这两件事的距离比听起来大得多, 所以别把退出码全绿当成结论成立: | 闸门能验的 | 闸门验不了的 | |---|---| | 行数守恒、总和守恒 | 这个数是不是用对了变量算的 | | 声称值 vs 明细求和 | 两个数能不能相减(比率 − 回归系数) | | 图有没有画出框、叠字 | 结论有没有超出置信区间 | | docx 字体、表头重复 | 引用的材料含义对不对 | | | **列名是不是它字面的意思** | | | 手打进正文的数字和数据对不对得上 | | | 时间窗口是不是挑出来的 | 一份内部对账分毫不差、行数与金额全部恒等的报告,可以整体错掉一个财年—— 只要那一列的列名不是它字面的意思。内部一致性证明不了列语义, 它只能证明你在自己的逻辑里没算错。 右边那一列,只能靠一个不参与创作的人来验。那是第 8 步,不是可选步骤。 **你是顾问,不替人做决定。** 把事实和判断分开说, 哪些是数据说的、哪些是你的看法,让他自己去称。 ## 开工前 先探明环境,别假设。你会被装在很多种 agent 里,它们的能力差别很大。 ```bash python3 --version && python3 -c "import openpyxl, pandas" 2>&1 ``` **在 DeepSeek Harness 桌面端里**(工具清单里有 `load_workspace_dependencies`):先调用它, 之后所有 `python3` 都换成它返回的 Python 绝对路径。那套 Python 自带 openpyxl、pandas, 本 skill 的脚本全部够用;不要 `pip install`,也不要去找系统里的 Python—— 用户多半没装,装了也可能缺库。脚本路径写本 skill 目录下 `scripts/` 的绝对路径, 输出文件一律写进当前工作区。Word / Excel 交付物要看版面时,加载 DSH 自带的 `office-render` skill 把文件渲染成图再读图;`verify_visual.py` 在桌面端没有 playwright, 按下文退出码 2 处理(明说没验,请用户在 DSH 侧栏预览里看一眼)。 再看一眼自己的工具清单,重点是有没有能起并行子任务的能力(Task / Agent 这类)。 它决定第 4 步的多视角和第 8 步的独立质控该怎么做: | 你有什么 | 怎么做 | |---|---| | 能跑脚本 + 能并行 | 派子任务,每个带一个角色 | | 能跑脚本,只能串行 | 自己依次切换角色,**一个写完再切下一个**,全写完再回头找分歧 | | 跑不了脚本 | 给 Excel 公式和菜单路径,体检对账逐项人工核。诚实转成「我告诉你怎么做」,别输出一段没人会执行的 Python | 然后花一分钟出个计划。不出计划的话,你会跟着数据里最显眼的东西走, 最后交出来的是「我碰巧发现的东西」,而不是「他需要知道的东西」。 计划里要写清楚:打算怎么理解这份数据、回答哪几个问题、每个怎么验证, 以及哪一步之后要回来找用户确认。 第 3 步对齐完了回头改计划是正常的,改了说一声就行。 ## 关于这些脚本 **它们是地板,不是天花板。** 脚本和每一份 references 都是兜底, 保证最差也不会错得离谱,而不是划定标准。 最好的分析从来不是脚本跑出来的。遇到脚本处理不了的结构、覆盖不到的分析, 就自己写代码、自己判断、自己设计。 判据是「顶级咨询团队会怎么交付」,不是「这个 skill 里现有什么」。 **它们是眼睛,不是大脑。** 每跑完一个,答三个问题再往下走: 看到了什么,意味着什么,下一步查什么。 这里有条判据可以写死:如果跑完之后,你的下一步动作和跑之前计划的一模一样, 那说明你没有真的在看那个输出。分析是一场不断分叉的调查; 照固定顺序把八个脚本跑完,产出的只是八段输出。 ## 标准作业流程 八步。走到哪一步,它前面的每一步就都不能省——没做完,后面的数字不成立。 | | 这一步在判断什么 | 跑什么 | |---|---|---| | 1 **体检** | 这张表能不能直接算——表头在哪、哪些行不是数据 | `profile_table.py` | | 2 **清洗** | 每一步影响了多少行,差额能不能解释 | `clean_table.py` | | 3 **对齐** | 他到底要回答什么;这个数在行业里算什么水平 | 🔴 **这步必须停**,见下 | | 4 **分析** | 结论会不会栽在陷阱里;推到「所以呢」了吗 | `scan_traps.py` | | 5 **对账** | 我凭什么说这个数是对的 | `verify_numbers.py` | | 6 **交付** | 他拿到之后要怎么用它 | ↓ HTML **直接写** | | 7 **验图** | 画错了没有——不是好不好看 | `verify_visual.py`(HTML)<br>`verify_docx.py`(Word)<br>`verify_xlsx.py`(Excel) | | 8 **质控** | 算得对,但结论对吗 | 🔴 **另派一个没参与创作的 agent**,见下 | **参数、输出怎么读、边界情况 → `references/workflow.md`。** 你在第几步读第几步, 不必一次全读。 ### 第 1、2 步:面对一张你没见过的表 脚本认得出的那些脏法,`profile_table.py` 会替你列出来。 但你一定会遇到它没见过的——这个「一定」没有例外, 中国各家后台导出表格的方式比任何词表都更有创造力。 所以这两步真正要你做的不是跑脚本,而是回答三个问题,它们对任何一张表都成立: **一、这张表的一行代表什么?** 一笔交易、一个人、一个人一个月, 还是一个人的一次登录?说不出来就别开始聚合。 观测单位定错了,后面每一个百分比的分母都是错的。 顺带一并确认:这是明细,还是已经汇总过的? 汇总表长得和明细很像,但它没法再往下钻,很多分析从一开始就做不了。 这件事早说比做到一半再说好。 **二、每一列的列名,是不是它字面的意思?** 这是最贵的一个问题, 因为没有任何内部检查能发现它(见「七条红线」第三条)。 有数据字典就读数据字典;没有的话,找发布方公开的一个总量对上去。 对不上就停在这里,别往下做。 **三、脚本说「没能自动解决」的那些值,是脏数据还是业务约定?** 转不成数字的单号、认不出格式的日期、莫名多出来的一个分类—— 它们通常不是错误,而是你还不认识的业务语义。逐个看一眼再决定。 丢掉的往往是信息而非噪音:一列发票号里转不成数字的那几个, 可能恰好是退货单和坏账调整,也就是整份数据里最该被看见的部分。 贯穿这两步的判据只有一条:脚本报告「已自动处理」的每一列, 抽两个值回头看原始单元格。它报告成功,不等于它做对了。 ### 这次要走几步 不是每个任务都要走满八步。判断标准只有一条:这个数字会被别人拿去做决定吗? | 他要什么 | 走哪几步 | 关键动作 | |---|---|---| | 查一个数、改个公式、干净表做透视 | 直接做 | 说清这个数怎么来的 | | 「这表有多少行是脏的」 | 1 | 体检报告直接给他 | | 「把这份表洗干净」 | 1 → 2 | 附一份可回放的清洗脚本,每步报影响行数 | | **「这两个数怎么对不上」** | 1 → 5 | **先查口径差异,不是先查算错**——对不上十次有八次是两边分母不一样 | | 「这个数靠谱吗」 | 5 → 8 | 对账 + 独立复核,说清哪一条最脆弱 | | 「帮我分析下这份数据」 | 1→8 全走 | 第 3 步必停 | | 要报告 / 要给领导看 | 1→8 全走 | 演绎结构,结论在前;**先问有没有现成的报告规范可参考** | | 要 PPT / 幻灯片 | 1→5,然后转交 | 交给 `huashu-design`,见下文 | | 定期要跑的(每月对一次账) | 1→5,交模板 | **交一个能一键刷新的模板,不是一份报告**——做模板的时间第二个月就赚回来 | **拿不准就往上走一档。** 这两种错误的代价完全不对称: 少走一步,代价是数字错了没人发现;多走一步,代价只是慢一点。 ### 🔴 第 3 步:停下来对齐 八步里有两步需要另一个人,这是第一处。前两步是技术活,第 4 步往后是你的活。 用户开口的时候,往往还不知道自己要什么,因为他也没看过这份数据长什么样。 「帮我分析一下」已经是他此刻能给出的最诚实的表述了。 你这时候问「你想看哪些维度」,他只能瞎猜。 所以澄清这件事不放在最前面,要放在你已经看懂数据、 而他也能看懂你的描述之后——这个先后顺序是这一步能不能成的关键。 三个动作,缺一个这步就不算做过: 1. **摸底**——用一段人话讲清这份数据是什么,含**一到两个已经能看到的现象**。 那一两个现象最能勾出他真正关心的问题 2. **查外部基准**——他的值 vs 行业中位数/头部/及格线,并排放进摸底里。 这是「领域专家」那一环,能联网就去查;查不到就明写「本次没有外部基准」 3. **问清楚再走**——他要回答什么问题、拿去做什么决定、有没有你从数据里 看不出来的背景(改版、活动、口径变更) **然后等回答。** 带着错的问题做完整套分析,返工成本远高于等这一次。 #### 动笔之前,先弄清楚对面到底有没有人 这一步最容易坏在一个不起眼的地方:你默认了没人可问,然后心安理得地替他把口径全定了。 多数时候是有人的。判断也不难——如果这一轮的输入是一个人用第一人称跟你说话, 上面还压着几轮来回,那你就是在跟他直接聊天,问一句的成本是几十秒钟。 真正没有人的场合有它自己的样子:一段写死的 brief,没有上文, 你是被批量派出去的十几个子任务之一,问了也没人看。 这两种情形的正确动作不一样,而把前一种误当成后一种,是这一步最常见的坏法。 有人可问却不问,你交出去的每一个口径都是猜的;他本来只需要十秒钟就能告诉你答案。 所以:**能问就必须问,口径声明不是那一问的替代品。** 写一份漂亮的声明说「以下是我替你做的决定」,读起来很负责, 实际上是把本该由他拍的板记成了一笔账,然后接着往下跑了三个钟头。 等他回来说方向不对,这三个钟头连同后面所有的数字一起作废—— 而那份声明会显得格外讽刺,因为它逐条列清了你本来该问却没问的东西。 问的时候别问「你想看哪些维度」,他也没看过这份数据,只能瞎猜。 问具体的、他一眼能判对错的:营收我打算算净额,因为退货占了 2.3%; 退货挂回原单月份而不是退货发生月。这两条你认吗? 顺带一提,环境变了要重新判断。中途发现数据源不对、发现某一列的含义拿不准、 发现他要的那份文件根本不存在——这些都是新的岔路口,不是「既然开工了就顺着走完」的理由。 确实没人可问的时候,才走另一条路,而那不是捷径: > 把你替他做的每一个决定,写成一份口径声明当交付物交出去。 > 不是塞进正文某个段落,是单独一份,里面每条都长这样: > 「营收算净额,因为退货单占 2.3% 不能忽略;退货挂回原单月份,不挂退货发生月。」 > > 判据很简单:如果他读完这份声明会说「不对,我要的是另一个」,那这条就必须在里面。 > 你替他做的决定越多,这份东西越该厚。 > > 还有一件事得说在前头:这份声明由你自己写,也就由你自己决定写什么进去。 > 你会本能地把最有把握的几条列上去,而真正危险的那几条——你压根没意识到自己 > 做了选择的地方——不会出现在清单里。所以它是给他看的交代, > 不是给你自己用的检查表。真正的检查在第 8 步,由另一个人来做。 **数据回答不了他的问题时,立刻说。** 他问渠道留存但表里没有用户 ID, 这时候要马上讲,不要做个近似的东西交上去让他以为问题被回答了。 ### 第 7 步:图画完要验,和数字一样 线画出框、标签叠成一团、文字压住柱子——这类错肉眼扫一遍看不出来,读者一眼就看见。 ```bash python3 scripts/verify_visual.py 报告.html --shots 自检 # 退出码 1 = 有 FAIL ``` 三件事现在就得知道,别等踩了再说: **一、「图上数字与正文数字接近但不相等」这一项误报率极高。** 它会把 SVG 的几何属性、CSS 里的 `297mm`、坐标轴刻度、日期里的年份 都当成「图上的数字」。看一眼就过,别为它改数字。 **但别因此养成跳过 WARN 区的习惯**——同一份输出里的越界和重叠全是真的。 **二、幻灯片会被自动识别。** 隐藏页和折叠附录先展开再测量,deck 自动切 1920×1080 视口——不会再出现「所有图 0×0」那类整齐得可疑的误报。 如果读数仍指向「全部都坏了」,先怀疑测量方式,再怀疑图。 **三、跑完仍要自己看一眼截图。** 机器判「画错了没有」,判不了「好不好」—— 每张图能不能独立回答它的标题、有没有该画成图却写成了段落、 首屏能不能十秒看懂结论。这三件事没有脚本替得了。 **四、交什么格式就跑哪道闸门。** HTML / deckREADME.md18 KB627a41661543upstream ↗
<div align="center"> # huashu-excel > *「给我一份Excel,给你交一份专业报告。」* > *一个真正懂数据分析的skill。* [](LICENSE) [](https://skills.sh) [](https://skills.sh) [](#装上就能用) <br> **数据分析与 Excel 全流程 · 体检 → 清洗 → 对齐 → 分析 → 对账 → 交付** <br> **「这个数你怎么算的?」** —— 每个交过数字的人都被这么问过。 答不上来通常不是记性差,是那个数从一开始就没法被追溯。 **而 AI 算错的时候不会报错。** 你写代码,错了会抛异常; 你做数据分析,错了什么都不会发生。一个 +161% 的错误, 交付出去的时候和正确答案长得完全一样。 丢一份乱七八糟的 Excel 给它——标题占了第一行、表头两级、地区列用合并单元格、 金额带千分位、中间夹着「华东小计」、尾巴三行是「合计/占比/同比」。 主流做法算这份表的月度总额,**比真值高 161%,零报错、零 NaN、零警告**。 这个 skill 存在的全部理由,就是让那句反问能被答上来。它先读原始单元格再动 pandas,把表里的「合计」行当成免费的校验和拿来对账,交付前跑一遍 master check——不通过就不给你数字。 ``` npx skills add alchaincyf/huashu-excel ``` 跨 agent 通用——Claude Code、Cursor、Codex、OpenClaw、Hermes 都能装。 [看效果对比](#看效果对比) · [装上就能用](#装上就能用) · [八步流程](#八步标准作业流程) · [五个不一样](#五个和别的工具不一样的地方) · [图表](#图表比用图表说话多一个维度) · [报告](#报告直接写不套模板) </div> --- ## 看效果对比 同一份表,同一个问题:「**1 月总销售额是多少?**」 ### 主流做法:`pd.read_excel()` 发现表头位置不对就加 `header=`,发现数字读不出来就清掉千分位。看起来已经挺周全了。 ``` 清理后求和:34,893,234 真值:13,367,767 总额误差:+161.0% 均值误差:+117.5% 零报错 零 NaN 零警告 ``` 错在三个地方,**没有任何一处会报错**: - `合计` 行的 15,368,317 被当成了一家门店 - `华东小计` 的 6,157,150 又被当成一家门店 - 有一行是粘贴事故造成的完全重复,算了两次 ### huashu-excel 体检阶段就把问题全列出来,一个都不猜: ``` 【必须先处理】 1. 表头不在第 1 行:第 1, 2 行是标题/说明,真表头在第 3, 4 行 2. 两级表头。用 header=[2, 3] 读,否则下级表头会掉进数据区 3. 发现 4 个汇总/小计行(第 12, 17, 18, 19 行)混在数据区 4. 1 行与前面完全重复(第 11 行) 5. 3 处合并单元格落在数据区,pandas 只保留左上角,其余行变空 【逐列】 E 一季度 / 1月 ⚠ 10/10 个数字被存成了文本 → 直接 sum() 会变成字符串拼接或得 0 I 退货额(元) ⚠ 缺失值被写成了具体文字:「—」×2、「无」×1、「N/A」×1 D 首单日期 ⚠ 日期格式不统一:YYYY-M-D×7、YYYY年M月D日×1、Excel日期序列号×1、 M月D日(缺年份)×1 ``` 然后拿清洗后的明细,去对**表里自带的合计行**: ``` ✓ 对账 · E列「1月」 vs 第12行「华东小计」 表内写 6,497,500.00,按「A列地区 == 华东」取 4 行算得 6,497,500.00 ✓ 一致 ✗ 对账 · F列「2月」 vs 第12行「华东小计」 表内写 6,490,430.00,明细算得 6,490,420.00 ✗ 差 10.00 MASTER CHECK:不通过。1 项对不上。 在解决之前,不要把这些数字写进任何交付物。 ``` **那个差 10 块钱的错,是造这份测试数据的人手填小计时填错的。** 相对误差 0.00%,肉眼永远发现不了,脚本一次揪出来。 Panko (1998) 的研究说 **86% 的电子表格含有错误**。欧洲电子表格风险兴趣组 (EuSpRIG)从 1995 年起持续收录见诸媒体的事故——最著名的是 Reinhart-Rogoff 论文,Excel 选区少选了 5 行,把 +2.2% 的 GDP 增速算成 −0.1%, 而那篇论文当时是全球紧缩政策的主要学术依据。 --- ## 装上就能用 ```bash npx skills add alchaincyf/huashu-excel ``` 或者直接 clone 到你的 agent 读 skills 的那个目录: | Runtime | 路径 | |---|---| | Claude Code | `~/.claude/skills/` | | Codex / Kimi Code / 多 agent 共用 | `~/.agents/skills/` | | 项目级(跟着仓库走) | `<项目>/.claude/skills/` 或 `<项目>/.agents/skills/` | ```bash git clone https://github.com/alchaincyf/huashu-excel <上表里的目录>/huashu-excel ``` ### DeepSeek Harness 插件 本仓库同时是一个 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)(DSH)插件。桌面端用户在「插件 → 添加插件」里填 GitHub 仓库地址,或者用命令行(桌面端的 profile 叫 `desktop`,网页版换成 `web`): ```bash dsh plugin --profile desktop add github:alchaincyf/huashu-excel ``` 命令行装之前,桌面端要先打开过一次,并且完全退出。装完再打开 DSH,插件才会加载。DSH 桌面端自带 Python 和 pandas、openpyxl,不用另装任何东西。卸载:`dsh plugin --profile desktop remove huashu-excel`。 不确定装哪就用上面的 `npx skills add`,它会自己探测。 也可以完全不装——把 `SKILL.md` 当成一份数据分析的方法论文档直接读。 装完直接说人话: ``` "帮我分析下这份销售表" → 走完整八步 "这两个数怎么对不上" → 体检 + 对账,先找口径差异 "这个数靠谱吗" → 对账 + 独立复核 "这个表有多少行是脏的" → 只跑体检 "帮我把这份表洗干净" → 体检 + 清洗,附一份可审计的 pandas 脚本 "这个数你怎么算出来的" → 对账 + 口径回溯 "给我做份报告" → 图表 + 洞察 + html/xlsx/docx 任选 ``` 这些脚本也能脱离 agent 单独用: ```bash python3 scripts/profile_table.py 你的表.xlsx # 算数字之前先看清楚 python3 scripts/verify_numbers.py 你的表.xlsx # 退出码 1 = 有对不上的 python3 scripts/verify_visual.py 报告.html # 退出码 1 = 图画错了 python3 scripts/verify_docx.py 报告.docx # 退出码 1 = Word 换台机器就走样 ``` **依赖只有 `openpyxl`**(读写 .xlsx 时),CSV 路径和报告生成连它都不用,纯标准库。 不用 pandas、不用绘图库、不用 LibreOffice、不联网、不依赖任何 agent 平台特性 (不需要 subagent、不需要沙盒)。 > 这不是为了炫技。体检要在「还没决定用什么工具处理这张表」的时刻就能跑, > 所以它自己必须几乎没有前置条件。已在屏蔽 pandas / numpy / openpyxl 的 > 解释器里验证过全流程跑通。 skill 会在开工时探测所处环境的能力,选那个环境下的最佳工作流—— 能起并行子任务就并行分析,只能串行就串行轮转视角,跑不了脚本就转成 「我告诉你在 Excel 里怎么点」。 --- ## 八步标准作业流程 ``` 1 体检 这张表长什么样 —— 结构、类型、脏点。先看再算 2 清洗 变成规范分析表,每一步可追溯可回放 3 对齐 摸底 → 查外部基准 → 告诉用户 → 问清他要什么 → 定口径 4 分析 扫陷阱,走配方,每条发现都推到「所以呢」 5 对账 行数守恒、总和守恒、与表内合计交叉验证 6 交付 Excel / 图表 / 报告,口径随数字一起交付 7 验图 渲染出来看画错了没有——手写 SVG 必然会犯那几类错 8 质控 另派一个没参与创作的 agent 从原始数据重算,拆你的台 ``` 最后一步是最容易被省掉的一步,而它抓到的问题比前面所有闸门加起来还多。 **退出码验的是「算得对」,不是「结论对」**——一份内部对账分毫不差的报告, 可以整体错一个财年,只要那一列的列名不是它字面的意思。 | 脚本 | 干什么 | 什么时候 | |---|---|---| | `profile_table.py` | 表结构体检 | 算任何数字之前 | | `clean_table.py` | 清洗 + 生成可审计的 pandas 脚本 | 体检之后 | | `scan_traps.py` | 分析陷阱扫描 | 下结论之前 | | `verify_numbers.py` | 数字对账 | 交付之前 | | `verify_visual.py` | HTML 渲染自检:越界 / 重叠 / 遮挡 / 双轴 / 图文数字打架 | 交付之前 | | `verify_docx.py` | Word 自检:字体平台绑定 / 中文缺 eastAsia / 空白页 / 图超版心 / 表头不重复 | 交付之前 | | `make_chart.py` | 图表推荐与生成 | 交付时 | | `make_report.py` | xlsx / docx 报告(HTML 直接写,不套模板) | 交付时 | ### 第 3 步「对齐」为什么值得单独成一步 用户开口的时候,往往还不知道自己要什么——**因为他也没看过这份数据长什么样**。 「帮我分析一下」是他此刻能给出的最诚实的表述。你这时候问他「你想看哪些维度」, 他只能瞎猜,猜出来的还得你去实现。 所以澄清不放在最开始,放在**你已经看懂数据、他也能看懂你的描述**之后: 清洗完先出一段人话摸底(几行几列、有哪些维度和指标、分布形态、 **一到两个已经能看到的现象**),带着它去问他要回答什么问题、 这份分析拿去做什么决定、有没有你从数据里看不出来的背景。 然后停下来等回答。这是整个流程里少数几个值得停的地方—— 带着错的问题做完整套分析,返工成本远高于等这一次。 ### 脚本是眼睛,不是大脑 每跑完一个脚本,必答三问再往下走:**我看到了什么 / 这意味着什么 / 下一步要查什么**。 判据写死在 skill 里:**如果跑完脚本之后,下一步动作和跑之前计划的一模一样, 说明没有真的在看那个输出。** 分析是一次不断分叉的调查, 照着固定顺序跑完八个脚本,产出的只是八段输出。 --- ## 五个和别的工具不一样的地方 **一、它不是一个分析师,是一个团队。** 这件事外包给顶级咨询公司,不会只派一个数据分析师。所以它要依次成为 **领域专家 / 数据分析师 / 战略顾问 / 视觉设计师 / 前端工程师 / 质控**—— 角色之间打架的地方保留下来,那是信息量最大的部分。 其中**领域专家最容易被跳过、代价也最大**:结论全是「这条比那条好」 「这个月比上月强」,用户读完还是不知道要不要改——因为他不知道 20% 的完播率 在这个平台算什么水平。**内部对比只能说明哪里变了,外部基准才能说明哪里不行。** 所以第 3 步会去查行业基准,查不到就明写「本次没有外部基准」。 **二、先看原始单元格,再动 pandas。** `pd.read_excel()` 读进来的那一刻,合并单元格、单元格格式、原始类型就全丢了。 现有工具都是在信息已经损毁之后才开始判断。体检脚本先用 openpyxl 读原始格子。 **三、把表里的「合计」行当成免费的校验和。** 所有工具都把汇总行当噪音过滤掉。但那是原表作者用公式算出来的真值。 拿清洗后的明细自己求和去对它——对不上就说明有一方错了,两种情况都必须报出来。 这对应 ICAEW《Financial Modelling Code》(2024) 的 `Include a master check`。 **四、默认给五数概括,不给均值。** 业务数据几乎总是右偏的(少数大客户、少数爆款)。`df.describe()` 把 mean/std 放在最前面,而均值在偏态分布下描述的不是任何一个真实对象。 默认输出 min/Q1/中位数/Q3/max + IQR,这是 Tukey 的抗差统计。 **五、机器判事实,人判品味。** 「行数对不对、总和守不守恒、这个数能不能追回源单元格」——机器验死,自动跑。 「这个分析有没有意义、该不该这么切」——明确交还给人, 绝不用一个分数冒充客观。 ### 还有一类问题,对账抓不到 数字全算对了,结论照样是错的。`scan_traps.py` 专扫这一类: | 陷阱 | 会让你得出什么错误结论 | |---|---| | 辛普森悖论 | 分组内都是 A 好,合起来变成 B 好 | | 幽灵分组 | 「张伟」和「张伟 」被算成两个人,每组的数都是残缺的 | | 小基数 | 样本 3 个的组报「增长 200%」,其实是多了 4 个 | | 时间断点 | 缺失的月份不会报错,但会让趋势线撒谎 | | 双峰分布 | 混了两群对象,均值描述的是一个不存在的人 | | 极端集中 | 前 20% 贡献了 80%,均值没有代表性 | --- ## 图表:比《用图表说话》多一个维度 继承 Gene Zelazny《用图表说话》的核心律条——**先确定要传达的信息,再选图表形式**, 并补上那本书 1985 年还没有的两件事。 ### 一、用实证决定视觉编码 Cleveland & McGill (1984) 的图形感知实验,测出了人读取不同视觉编码的精度阶梯: ``` 位置(共同基线) > 位置(非对齐) > 长度/方向/角度 > 面积 > 体积/曲率 > 明暗/色饱和 位置判断比长度准 1.4–2.5 倍,比角度准 1.96 倍 ``` 饼图靠角度和面积编码,正好落在下游。所以 `make_chart.py` **在类别超过 3 个时会拒绝生成饼图**: ``` 拒绝生成饼图:当前 10 个类别,超过 3 类。 原因:饼图靠角度和面积编码,在 Cleveland-McGill 的感知精度阶梯上排第 3 和第 4, 而条形图的长度编码排第 2。 改用 --type bar,并在标签上标注百分比——信息一样,读者读得更准。 ``` 这不是审美偏好,是有测量结果的。 ### 二、检查这张图有没有在误导人 生成时自动执行,不靠自觉: - 柱形图数值轴**强制从 0**(它编码长度,截断即失真) - 折线图**不强制从 0**(它编码位置和斜率,强行归零会压平真实波动) - 坐标轴用整刻度,不是 `139.68 / 115.50 / 91.32` 这种从数据直接算出来的碎数字 - 类别按值排序、单系列去图例、类别过多自动聚合 - 不完整的最后一期画虚线——**本期没走完却画成实线,是最常见的误导** - 套用色盲友好色板(约 8% 的男性有红绿色觉障碍,而红绿恰是最常用的选择) 完整的诚实性检查清单见 [`references/charts.md`](references/charts.md)。 --- ## 报告:直接写,不套模板 **HTML 报告直接写 HTML/CSS**,不从模板里挑。顶级设计师不用模板生成器—— 他看过内容之后为这份内容做设计。**没有内置风格可挑**:动手前先落一份设计计划 (色 / 字 / 数字 / 间距 / 版式五段),照着它写;写完对照十五条最常见的 默认倾向自查一遍。 手写时这几条不能丢,它们是内容要求不是技术限制: - **自包含**——无 CDN、无外部字体,图表用内联 SVG 自己画,离线和内网都能开 - **口径声明在前,分析边界在后**——没有口径的数字没法被检验; 说出自身弱点的报告比天衣无缝的可信 - **图表诚实性**——柱形轴从 0、折线不强制从 0、整刻度、同列同小数位、 不完整末期画虚线、色盲友好 - **该是图就别是字**——N 行 × 1 数值列的排名表画条形图,含正负的分解画瀑布图 Office 格式仍走脚本,因为手写不划算: | 格式 | 怎么做 | |---|---| | **HTML 报告** | **直接写** | | **幻灯片 / PPT** | **不在本 skill 做** —— 转 [huashu-design](https://github.com/alchaincyf/huashu-design),见下 | | `xlsx` Excel 内报告 | `make_report.py --format xlsx`,图表引用数据 sheet,改数图跟着变 | | `docx` 六页纸文档 | `make_report.py --format docx`,Amazon six-pager 叙述体。字体用 Office 双平台自带款,交付前跑 `verify_docx.py` | `docx` 那条走的是 six-pager 的精髓:**叙述体,不用项目符号**—— bullet 允许把没想清楚的东西并列摆着蒙混过关,完整段落会逼你写出因果和取舍。 写不清楚,就是没想清楚。手写 OOXML,连 python-docx 都不需要。 ### 幻灯片和 PPT 交给 huashu-design 要 PPT / deck / 演示文稿时,本 skill 只出**分析内容和图表**, 演示文稿的生成与视觉交给 [huashu-design](https://github.com/alchaincyf/huashu-design) (没装会先引导安装)。排版、母版、封面、视觉方向是另一个专业, 硬做出来的结果是「一眼看得出是自动生成的」。 交接会带三样过去:口径声明、论点结构、已经过渲染自检的内联 SVG—— 而不是把原始数据丢过去让它自己算。口径是上游定的,不该在下游被重新发明。 --- ## 方法论出处 这份 skill 的判断力不是凭空来的,每条都有出处: | 来源 | 用在哪 | |---|---| | Hadley Wickham, *Tidy Data* | 清洗的目标形态与五类脏数据分类 | | John Tukey, *Exploratory Data Analysis* (1977) | 五数概括、抗差统计、箱线图 | | ICAEW, *Financial Modelling Code* (2024) | master check、可追溯引用、Excel 工程约定 | | Cleveland & McGill (1984) | 视觉编码的感知精度阶梯 | | Gene Zelazny, *Say It With Charts* | 先定信息再选图、比较类型 → 图表形式 | | Barbara Minto, *The Pyramid Principle* | 结论先行、MECE、SCQA | | Ronny Kohavi et al., *Trustworthy Online Controlled Experiments* | Twyman's Law、常见陷阱 | | Cassie Kozyrkov | 探索与推断的分工红线 | | Panko (1998)、EuSpRIG | 电子表格错误的实证规模 | 引用的规范文本均为提炼转述并注明出处,不含受版权保护的原文复制。 三届微软 Excel 世界冠军 Andrew Ngai 对 AI 做数据分析的判断,是这份 skill 的立论: > 如果你用错误的数据训练 AI,它会给你错误的结果——但它还会装出对这些错误结果非常自信的样子。 --- ## License MITscripts/clean_table.py19 KB618e2dc7572fupstream ↗
#!/usr/bin/env python3 # -*- coding: utf-8 -*- """按体检结果清洗成规范分析表,并留下可审计的痕迹。 它不只是吐出一张干净表。只给结果的清洗是黑箱 —— 三个月后没人说得清 第 47 行为什么不见了,包括做清洗的人自己。 所以它产出三样东西: 1. 清洗后的数据(.xlsx 或 .csv) 2. 逐步的清洗日志:每一步影响了多少行、为什么 3. 一份等价的 pandas 脚本,别人可以读、可以改、可以复现 目标形态是 Tidy Data(Wickham):每个变量一列,每条观测一行。 用法 ---- python3 clean_table.py <文件> [--sheet 名称] [--out 输出路径] [--dedup] [--dry-run] [--no-script] --dedup 去掉完全重复的行(默认保留,因为重复可能是真实业务) --dry-run 只报告会做什么,不写文件 --no-script 不生成审计脚本 依赖:只需要 openpyxl(读写 .xlsx 时)。不用 pandas。 生成的审计脚本用 pandas,那是给人看和用的,与本工具的运行无关。 """ from __future__ import annotations import argparse import csv import sys from dataclasses import dataclass, field from pathlib import Path from typing import Any sys.path.insert(0, str(Path(__file__).parent)) from profile_table import ( # noqa: E402 profile, parse_number, _norm, _is_blank, _is_null_token, _merge_anchor_map, read_grid, TableProfile, FULLWIDTH_SPACE, NULL_TOKENS, SERIAL_MIN, SERIAL_MAX, get_column_letter, HAS_OPENPYXL, ) from datetime import datetime, date, timedelta EXCEL_EPOCH = datetime(1899, 12, 30) # 1900 日期系统的实际原点(含闰年 bug 补偿) @dataclass class Step: name: str detail: str rows_before: int rows_after: int @property def delta(self) -> int: return self.rows_after - self.rows_before @dataclass class CleanResult: columns: list[str] = field(default_factory=list) rows: list[list[Any]] = field(default_factory=list) steps: list[Step] = field(default_factory=list) col_actions: dict[str, list[str]] = field(default_factory=dict) unresolved: list[str] = field(default_factory=list) source_rows: list[int] = field(default_factory=list) # 每行对应的原始行号 def _to_iso(raw: Any) -> tuple[Any, bool]: """日期归一成 ISO 字符串。返回 (值, 是否成功)。""" if isinstance(raw, datetime): return raw.date().isoformat(), True if isinstance(raw, date): return raw.isoformat(), True if isinstance(raw, (int, float)) and not isinstance(raw, bool): if SERIAL_MIN <= float(raw) <= SERIAL_MAX and float(raw).is_integer(): return (EXCEL_EPOCH + timedelta(days=int(raw))).date().isoformat(), True return raw, False s = _norm(raw) if not s: return None, True # 逐个尝试常见写法 for fmt in ("%Y-%m-%d", "%Y/%m/%d", "%Y.%m.%d", "%Y年%m月%d日", "%Y-%m", "%Y/%m", "%Y年%m月", "%Y%m%d"): try: d = datetime.strptime(s, fmt) return (d.date().isoformat() if "%d" in fmt else d.date().isoformat()[:7]), True except ValueError: continue return s, False # 认不出来的原样保留,并记进 unresolved def clean(path: Path, sheet: str | None = None, dedup: bool = False) -> tuple[CleanResult, TableProfile]: p = profile(path, sheet) grid, meta = read_grid(path, sheet) res = CleanResult() if not p.columns or p.n_data_rows == 0: res.unresolved.append("没有识别出明细数据,无法清洗") return res, p amap = _merge_anchor_map(p.merged_ranges) width = len(p.columns) def cell(row: int, ci: int) -> Any: r = grid[row - 1] if row - 1 < len(grid) else [] v = r[ci] if ci < len(r) else None if _is_blank(v) and (row, ci + 1) in amap: ar, ac = amap[(row, ci + 1)] src = grid[ar - 1] if ar - 1 < len(grid) else [] v = src[ac - 1] if ac - 1 < len(src) else None return v # ── 步骤 1:定位表头与数据区 ───────────────────────────────── res.columns = [c.name for c in p.columns] all_span = list(range(p.data_start_row, p.data_end_row + 1)) res.steps.append(Step( "定位表头", f"表头在第 {p.header_rows} 行" + (f"({len(p.header_rows)} 级,已拍平)" if p.multi_level_header else "") + f";标题/说明行 {p.title_rows or '无'} 已跳过", len(grid), len(all_span), )) # ── 步骤 2:排除汇总行与脚注行 ─────────────────────────────── drop = {r["row"] for r in p.summary_rows} | {r["row"] for r in p.footnote_rows} kept = [r for r in all_span if r not in drop and not all(_is_blank(v) for v in grid[r - 1])] if drop: labels = "、".join( f"第{r['row']}行「{r['label'] or '?'}」" for r in p.summary_rows) res.steps.append(Step( "排除汇总行", f"{labels};脚注 {len(p.footnote_rows)} 行", len(all_span), len(kept))) else: res.steps.append(Step("排除汇总行", "未发现汇总行", len(all_span), len(kept))) # ── 步骤 3:合并单元格 ffill ──────────────────────────────── ffill_cols = sorted({c for (_r, c) in amap if any(r == _r for r in kept)}) if ffill_cols: names = "、".join(get_column_letter(c) for c in ffill_cols) res.steps.append(Step( "恢复合并单元格", f"{names} 列的空值由合并区左上角回填(等价于 ffill)", len(kept), len(kept))) for c in ffill_cols: res.col_actions.setdefault( p.columns[c - 1].name if c - 1 < width else get_column_letter(c), []).append("ffill 恢复分组标签") # ── 步骤 4:逐列按真实类型转换 ────────────────────────────── out_rows: list[list[Any]] = [] disguised_hits = 0 ws_hits = 0 num_fail: dict[str, list[str]] = {} date_fail: dict[str, list[str]] = {} for r in kept: row_out: list[Any] = [] for c in p.columns: raw = cell(r, c.index) name = c.name # 缺失值归一 s = _norm(raw) if isinstance(raw, str) and _is_null_token(s): disguised_hits += 1 row_out.append(None) continue if s == "": row_out.append(None) continue if isinstance(raw, str) and (raw != raw.strip() or FULLWIDTH_SPACE in raw): ws_hits += 1 if c.inferred_kind == "数值": v, _marks = parse_number(raw) if v is None: num_fail.setdefault(name, []).append(s) row_out.append(s) # 转不了的保留原文,不静默变 None else: row_out.append(v) elif c.inferred_kind == "日期": v, ok = _to_iso(raw) if not ok: date_fail.setdefault(name, []).append(s) row_out.append(v) else: row_out.append(s) # 文本:去首尾+全角空格 out_rows.append(row_out) for c in p.columns: acts = res.col_actions.setdefault(c.name, []) if c.inferred_kind == "数值": acts.append("文本→数值(去千分位/货币符号/单位后缀/括号负数)") elif c.inferred_kind == "日期": acts.append("日期→ISO 格式") else: acts.append("去首尾空格与全角空格") res.steps.append(Step( "类型转换", f"数值列去千分位与单位后缀;日期列统一为 ISO;" f"{disguised_hits} 个伪装缺失值(—、N/A、无 等)归一为真空;" f"{ws_hits} 处首尾/全角空格已清除", len(kept), len(out_rows), )) for name, vals in num_fail.items(): uniq = sorted(set(vals))[:5] res.unresolved.append( f"「{name}」列有 {len(vals)} 个值转不成数字,已原样保留:" f"{uniq} —— 去看看它们是什么,不要放过") for name, vals in date_fail.items(): uniq = sorted(set(vals))[:5] res.unresolved.append( f"「{name}」列有 {len(vals)} 个日期认不出格式,已原样保留:{uniq}") # ── 步骤 5:去重(默认不做)────────────────────────────────── src = list(kept) if dedup: seen: set[tuple] = set() keep_idx: list[int] = [] for i, row in enumerate(out_rows): key = tuple(_norm(v) for v in row) if key in seen: continue seen.add(key) keep_idx.append(i) before = len(out_rows) out_rows = [out_rows[i] for i in keep_idx] src = [src[i] for i in keep_idx] res.steps.append(Step("去重", "删除完全重复的行", before, len(out_rows))) elif p.duplicate_rows: rows_s = "、".join(str(d["row"]) for d in p.duplicate_rows) res.steps.append(Step( "去重", f"发现 {len(p.duplicate_rows)} 行完全重复(第 {rows_s} 行)" f"但**未删除** —— 重复可能是真实业务。要删加 --dedup", len(out_rows), len(out_rows))) res.rows = out_rows res.source_rows = src return res, p # ── 生成审计脚本 ────────────────────────────────────────────────────── def emit_script(p: TableProfile, res: CleanResult, src: Path, dedup: bool) -> str: drop_rows = sorted({r["row"] for r in p.summary_rows} | {r["row"] for r in p.footnote_rows}) header_arg = ([r - 1 for r in p.header_rows] if p.multi_level_header else p.header_rows[0] - 1) reader = "pd.read_csv" if src.suffix.lower() in (".csv", ".tsv", ".txt") else "pd.read_excel" num_cols = [c.name for c in p.columns if c.inferred_kind == "数值"] date_cols = [c.name for c in p.columns if c.inferred_kind == "日期"] text_cols = [c.name for c in p.columns if c.inferred_kind == "文本"] ffill_cols = [c.name for c in p.columns if "ffill 恢复分组标签" in res.col_actions.get(c.name, [])] return f'''#!/usr/bin/env python3 # -*- coding: utf-8 -*- """{src.name} 的清洗流程(自动生成,请审阅后使用) 这份脚本是清洗过程的可读记录。每一步都能被检查、修改、复现。 生成依据来自表结构体检,但**业务判断需要你确认**,尤其是标了 ⚠ 的地方。 """ import pandas as pd SRC = r"{src.name}" # ── 1. 读取:表头在第 {p.header_rows} 行(1-based)──────────────── df = {reader}(SRC, header={header_arg}) # 多级表头会读成 MultiIndex 列名,先拍平成单层, # 否则 df["一季度 / 1月"] 取不到列(pandas 里它是 ("一季度","1月")) if isinstance(df.columns, pd.MultiIndex): df.columns = [ " / ".join(dict.fromkeys( str(x).strip() for x in tup if str(x).strip() and str(x) != "nan" and not str(x).startswith("Unnamed") )) or f"col{{i}}" for i, tup in enumerate(df.columns) ] # ── 2. 排除非明细行 ─────────────────────────────────────────── # 原表第 {drop_rows} 行(1-based)是汇总/小计/脚注,不是明细数据。 # ⚠ 排除之前,先拿它们和你的计算结果对账 —— 那是免费的校验和。 DROP_EXCEL_ROWS = {drop_rows} _offset = {max(p.header_rows) if p.header_rows else 1} # 表头占掉的行数 df = df.drop(index=[r - _offset - 1 for r in DROP_EXCEL_ROWS if 0 <= r - _offset - 1 < len(df)], errors="ignore") # 整行为空的行(原表里的分隔空行)——必须在按位置删完之后再做, # 否则 index 会错位,把不该删的行删掉 df = df.dropna(how="all").reset_index(drop=True) # ── 3. 恢复合并单元格造成的空值 ─────────────────────────────── # ⚠ 这些列的空值不是缺失,是合并单元格的显示效果。 # 绝对不要 dropna,那会把每个分组除首行外的所有行删掉。 for col in {ffill_cols}: if col in df.columns: df[col] = df[col].ffill() # ── 4. 缺失值归一 ───────────────────────────────────────────── NA_TOKENS = {sorted(t for t in NULL_TOKENS if t)!r} df = df.replace(NA_TOKENS, pd.NA) # ── 5. 文本型数字转数值 ─────────────────────────────────────── def to_num(s): return pd.to_numeric( s.astype(str) .str.replace("\ ", "", regex=False) .str.strip() .str.replace(r"^\\((.*)\\)$", r"-\\1", regex=True) # 会计括号负数 .str.replace(r"[,,¥¥$€£]", "", regex=True) .str.replace(r"(万元|亿元|千元|万|亿|元|个|人|次|件|台|笔|单)$", "", regex=True), errors="coerce") for col in {num_cols}: if col in df.columns: before_na = df[col].isna().sum() df[col] = to_num(df[col]) lost = df[col].isna().sum() - before_na if lost: print(f"⚠ {{col}}:{{lost}} 个值转不成数字,已变成 NaN —— 去查是什么") # ── 6. 日期统一 ─────────────────────────────────────────────── for col in {date_cols}: if col in df.columns: df[col] = pd.to_datetime(df[col], errors="coerce", format="mixed") # ⚠ 不要用 dayfirst 去猜 03/04 是三月四号还是四月三号,猜错不报错。去问。 # ── 7. 文本去空格(含全角)─────────────────────────────────── for col in {text_cols}: if col in df.columns: df[col] = (df[col].astype(str) .str.replace("\ ", "", regex=False) .str.strip() .replace("nan", pd.NA)) {"# ── 8. 去重 ───────────────────────────────────────────────────" if dedup else "# ── 8. 去重(本次未启用)────────────────────────────────────"} {"df = df.drop_duplicates()" if dedup else "# ⚠ 发现过完全重复的行但未删除。重复可能是真实业务(同一天两笔同额订单),"} {"" if dedup else "# 也可能是粘贴事故。确认之后再决定:df = df.drop_duplicates()"} # ── 校验:行数必须能解释 ────────────────────────────────────── print(f"清洗后 {{len(df)}} 行 × {{len(df.columns)}} 列") assert len(df) == {len(res.rows)}, "行数与清洗工具的结果不一致,两边对一下" df.to_excel("cleaned.xlsx", index=False) ''' # ── 写文件 ──────────────────────────────────────────────────────────── def write_out(res: CleanResult, out: Path) -> None: if out.suffix.lower() in (".csv", ".tsv"): delim = "\t" if out.suffix.lower() == ".tsv" else "," with out.open("w", newline="", encoding="utf-8-sig") as f: w = csv.writer(f, delimiter=delim) w.writerow(res.columns) w.writerows(res.rows) return if not HAS_OPENPYXL: raise SystemExit("写 xlsx 需要 openpyxl,或把 --out 改成 .csv") from openpyxl import Workbook from openpyxl.styles import Font wb = Workbook() ws = wb.active ws.title = "cleaned" ws.append(res.columns) for c in ws[1]: c.font = Font(bold=True) for row in res.rows: ws.append(row) ws.freeze_panes = "A2" wb.save(out) def render(res: CleanResult, p: TableProfile, out: Path | None, dedup: bool) -> str: L: list[str] = [] add = L.append bar = "─" * 68 add(bar) add("清洗") add(bar) add("") add("【每一步做了什么】") for i, s in enumerate(res.steps, 1): d = f"{s.rows_before} → {s.rows_after}" if s.delta: d += f"({s.delta:+d} 行)" add(f" {i}. {s.name} {d}") add(f" {s.detail}") add("") add("【逐列处理】") for name, acts in res.col_actions.items(): add(f" {name}:{';'.join(acts)}") if res.unresolved: add("") add("【没能自动解决 —— 需要你看一眼】") for u in res.unresolved: add(f" ? {u}") add("") add(f"结果:{len(res.rows)} 行 × {len(res.columns)} 列") if out: add(f"已写入:{out}") add("") add(bar) add("清洗完不等于数字对了。接着跑 verify_numbers.py,") add("拿清洗后的明细去对原表的合计行 —— 那是最便宜的一次验证。") add(bar) return "\n".join(L) def main() -> None: ap = argparse.ArgumentParser(description="清洗成规范分析表,并留下可审计的痕迹") ap.add_argument("file") ap.add_argument("--sheet", default=None) ap.add_argument("--out", default=None, help="输出路径,默认 <原名>_cleaned.xlsx") ap.add_argument("--dedup", action="store_true", help="删除完全重复的行") ap.add_argument("--dry-run", action="store_true", help="只报告,不写文件") ap.add_argument("--no-script", action="store_true", help="不生成审计脚本") a = ap.parse_args() src = Path(a.file).expanduser() if not src.exists(): sys.exit(f"文件不存在:{src}") res, p = clean(src, a.sheet, a.dedup) if not res.rows and res.unresolved: print("\n".join(res.unresolved)) sys.exit(1) out = None if not a.dry_run: out = Path(a.out).expanduser() if a.out else src.with_name(src.stem + "_cleaned.xlsx") write_out(res, out) if not a.no_script: sp = out.with_name(out.stem + "_recipe.py") sp.write_text(emit_script(p, res, src, a.dedup), encoding="utf-8") print(f"审计脚本:{sp}") print(render(res, p, out, a.dedup)) if __name__ == "__main__": main()scripts/make_chart.py18 KBacdb04151b0eupstream ↗
#!/usr/bin/env python3 # -*- coding: utf-8 -*- """图表:先判断该用什么图,再生成 Excel 原生图表。 它做两件事,第一件比第二件重要: --suggest 看懂数据的结构,推荐图表类型,并说明为什么、有什么风险 生成 按推荐(或你的指定)产出图表,自动执行诚实性约束 图表类型的选择依据来自两处: · Zelazny《用图表说话》—— 先确定信息,再让图表形式匹配比较类型 · Cleveland & McGill (1984) 图形感知实验 —— 视觉编码的精度阶梯: 位置(共同基线) > 位置(非对齐) > 长度/方向/角度 > 面积 > 体积/曲率 > 明暗/色饱和 位置判断比长度准 1.4–2.5 倍,比角度准 1.96 倍。 所以默认给条形图而不是饼图——这是有测量结果的,不是审美偏好。 自动执行的诚实性约束(见 references/charts.md): · 柱/条形图 Y 轴强制从 0(它编码长度,截断即失真) · 折线图不强制从 0(它编码位置和斜率,强行归零会压平真实波动) · 类别超过阈值时拒绝生成饼图,并说明原因 · 检测时间序列末期是否不完整,提示标注 用法 ---- python3 make_chart.py <文件> --suggest python3 make_chart.py <文件> --x 门店 --y 销售额 --title "..." [--type bar] [--sheet 名称] [--out 输出.xlsx] 依赖:openpyxl。不用 pandas、不用绘图库、不联网。 """ from __future__ import annotations import argparse import sys from dataclasses import dataclass, field from pathlib import Path from typing import Any sys.path.insert(0, str(Path(__file__).parent)) from profile_table import ( # noqa: E402 profile, parse_number, _norm, _is_blank, _merge_anchor_map, read_grid, TableProfile, HAS_OPENPYXL, ) # 超过这么多类别,图会变成噪音(见 charts.md) MAX_CATEGORIES = 15 # 饼图的绝对上限。超过就拒绝,因为角度编码精度垫底 PIE_MAX = 3 # 时间序列点数超过这个值用折线,否则用柱形 LINE_THRESHOLD = 8 # 色盲友好的分类色板(Wong 色板系)。约 8% 的男性有红绿色觉障碍, # 而红绿对比恰恰是最常用的选择。这套以蓝橙为主轴,避开红绿对立。 SAFE_PALETTE = ["0173B2", "DE8F05", "029E73", "CC78BC", "CA9161", "56B4E9"] @dataclass class Suggestion: chart: str reason: str x: str = "" y: list[str] = field(default_factory=list) warnings: list[str] = field(default_factory=list) title_hint: str = "" # ── 判断列的角色 ────────────────────────────────────────────────────── def classify_columns(p: TableProfile) -> dict[str, list]: """把列分成:时间列、分类列(低基数文本)、数值列、高基数文本(不可用作维度)。""" roles: dict[str, list] = {"time": [], "category": [], "measure": [], "id_like": []} n = max(p.n_data_rows, 1) for c in p.columns: live = c.n_total - c.n_missing if live == 0: continue if c.inferred_kind == "日期": roles["time"].append(c) elif c.inferred_kind == "数值": # 唯一值几乎等于行数、且是整数序列 → 更像编号不是度量 if c.n_unique == n and c.stats and c.stats.get("iqr", 0) == 0: roles["id_like"].append(c) else: roles["measure"].append(c) else: # 文本:基数低才能当维度 if c.n_unique <= MAX_CATEGORIES and c.n_unique > 1: roles["category"].append(c) elif c.n_unique >= n * 0.9: roles["id_like"].append(c) else: roles["category"].append(c) # 基数偏高但仍可分组,会警告 return roles def suggest(p: TableProfile) -> list[Suggestion]: """按 Zelazny 的「比较类型 → 图表形式」推荐,附带风险提示。""" roles = classify_columns(p) out: list[Suggestion] = [] times, cats, meas = roles["time"], roles["category"], roles["measure"] if not meas: return [Suggestion("无", "没有可用作数值的列,先确认类型转换是否成功")] m0 = meas[0] # ① 时间 + 数值 → 时间序列 if times: t = times[0] n_pts = p.n_data_rows kind = "line" if n_pts > LINE_THRESHOLD else "col" s = Suggestion( kind, f"「{t.name}」是时间维度 → 时间序列比较。" + (f"{n_pts} 个时间点,用折线看趋势" if kind == "line" else f"只有 {n_pts} 个时间点,用柱形比折线更好读"), x=t.name, y=[m0.name], title_hint="标题写变化的结论,例:「三月起连续四个月下滑」", ) s.warnings.append( "确认最后一期是否完整——本月只过了几天就画进去,会看起来像断崖下跌。" "不完整的期次要去掉或用浅色标注") if kind == "line": s.warnings.append("折线图 Y 轴不必从 0(它编码位置和斜率,不是长度)") else: s.warnings.append("柱形图 Y 轴必须从 0,否则会放大差异") out.append(s) # ② 分类 + 数值 → 项目比较(排名) if cats: c = cats[0] s = Suggestion( "bar", f"「{c.name}」是分类维度({c.n_unique} 类)→ 项目比较。" f"用横向条形图并按值排序:条形用长度+共同基线编码," f"是感知精度最高的一档", x=c.name, y=[m0.name], title_hint="标题写比较的结论,例:「深圳南山店领先第二名 20%」", ) if c.n_unique > MAX_CATEGORIES: s.warnings.append( f"{c.n_unique} 个类别太多,图会变成噪音。" f"建议只画 Top 10 + 「其他」,或者改用表格") if len(c.name) > 6 or c.n_unique > 6: s.warnings.append("类别名较长或较多时,横向条形图比竖向柱形图好读") s.warnings.append("类别没有内在顺序(地区、渠道、产品)就按值排序,读者不用自己排") out.append(s) # 成分关系:明确不推荐饼图 out.append(Suggestion( "bar", f"如果你想表达的是「占比/构成」,仍然用排序条形图 + 标注百分比," f"不要用饼图:饼图靠角度和面积编码,在 Cleveland-McGill 的精度阶梯上" f"分别排第 3 和第 4,条形图的长度编码排第 2", x=c.name, y=[m0.name], warnings=[f"饼图只在 2–{PIE_MAX} 类且只需粗略印象时才可用;" f"当前有 {c.n_unique} 类"], title_hint="标题写构成的结论,例:「华东贡献六成销售额」", )) # ③ 两个数值列 → 相关 if len(meas) >= 2: out.append(Suggestion( "scatter", f"「{meas[0].name}」和「{meas[1].name}」都是数值 → 相关性比较,用散点图", x=meas[0].name, y=[meas[1].name], warnings=[ "相关不是因果。除非做过随机对照实验,措辞停在「相关」," "不要写成「带来」「提升」「导致」", "先看有没有离群点——一个异常点能把相关系数从 0.1 拉到 0.8", ], title_hint="标题写关系的结论,且不要暗示因果", )) # ④ 单数值列 → 分布 out.append(Suggestion( "hist", f"只看「{m0.name}」本身的分布 → 频率分布比较。" f"业务数据几乎都是右偏的,直方图或箱线图能看出均值骗没骗你", x="", y=[m0.name], warnings=["如果分布是双峰,说明混了两群不同的对象,均值描述的是不存在的人"], title_hint="标题写分布的结论,例:「七成门店月销在 100–200 万之间」", )) # ⑤ 多个数值列 + 分类 → 分组对比 if cats and len(meas) >= 2: out.append(Suggestion( "col", f"多个指标按「{cats[0].name}」对比 → 分组柱形图。" f"但如果两个指标量纲不同,不要用双 Y 轴", x=cats[0].name, y=[m.name for m in meas[:3]], warnings=[ "双 Y 轴能凭空造出并不存在的相关性——调一下刻度," "两条线就能贴合或分开。改用上下两张共享 X 轴的小图," "或者把指标都转成指数(基期=100)", ], )) return out # ── 生成图表 ────────────────────────────────────────────────────────── def build(path: Path, sheet: str | None, x_name: str, y_names: list[str], ctype: str, title: str, out: Path) -> list[str]: if not HAS_OPENPYXL: raise SystemExit("生成图表需要 openpyxl") from openpyxl import Workbook from openpyxl.chart import BarChart, LineChart, PieChart, ScatterChart, Reference, Series from openpyxl.chart.marker import Marker from openpyxl.styles import Font p = profile(path, sheet) grid, _ = read_grid(path, sheet) amap = _merge_anchor_map(p.merged_ranges) notes: list[str] = [] def cell(row: int, ci: int) -> Any: r = grid[row - 1] if row - 1 < len(grid) else [] v = r[ci] if ci < len(r) else None if _is_blank(v) and (row, ci + 1) in amap: ar, ac = amap[(row, ci + 1)] src = grid[ar - 1] if ar - 1 < len(grid) else [] v = src[ac - 1] if ac - 1 < len(src) else None return v by_name = {c.name: c for c in p.columns} def find(nm: str): if nm in by_name: return by_name[nm] hits = [c for c in p.columns if nm and nm in c.name] if len(hits) == 1: return hits[0] raise SystemExit(f"找不到列「{nm}」。可用列:{[c.name for c in p.columns]}") xc = find(x_name) if x_name else None ycs = [find(n) for n in y_names] excluded = {r["row"] for r in p.summary_rows} | {r["row"] for r in p.footnote_rows} rows = [r for r in range(p.data_start_row, p.data_end_row + 1) if r not in excluded and not all(_is_blank(v) for v in grid[r - 1])] if excluded: notes.append(f"已排除 {len(excluded)} 个汇总/脚注行,图里只有明细数据") # 取数 data: list[tuple[Any, list[float]]] = [] for r in rows: xv = _norm(cell(r, xc.index)) if xc else str(r) yv = [] for c in ycs: v, _ = parse_number(cell(r, c.index)) yv.append(v if v is not None else 0.0) data.append((xv, yv)) # 单系列且是分类维度 → 按值排序(charts.md:类别无内在顺序时按值排) if len(ycs) == 1 and xc and xc.inferred_kind == "文本": data.sort(key=lambda t: t[1][0], reverse=True) notes.append("类别按值降序排列——读者不用自己在脑子里排一遍") if len(data) > MAX_CATEGORIES and ctype in ("bar", "col", "pie"): keep = data[:10] rest = sum(v[0] for _k, v in data[10:]) data = keep + [("其他", [rest])] notes.append(f"类别过多,已聚合为 Top 10 + 「其他」(原 {len(rows)} 类)") if ctype == "pie" and len(data) > PIE_MAX: raise SystemExit( f"拒绝生成饼图:当前 {len(data)} 个类别,超过 {PIE_MAX} 类。\n" f"原因:饼图靠角度和面积编码,在 Cleveland-McGill 的感知精度阶梯上" f"排第 3 和第 4,而条形图的长度编码排第 2。\n" f"改用 --type bar,并在标签上标注百分比——信息一样,读者读得更准。") # 写数据表 wb = Workbook() ws = wb.active ws.title = "data" ws.append([xc.name if xc else "序号"] + [c.name for c in ycs]) for c in ws[1]: c.font = Font(bold=True) for k, vs in data: ws.append([k] + vs) ws.freeze_panes = "A2" n = len(data) cats_ref = Reference(ws, min_col=1, min_row=2, max_row=n + 1) data_ref = Reference(ws, min_col=2, max_col=1 + len(ycs), min_row=1, max_row=n + 1) if ctype in ("bar", "col"): ch = BarChart() ch.type = "bar" if ctype == "bar" else "col" ch.add_data(data_ref, titles_from_data=True) ch.set_categories(cats_ref) # 诚实性约束:柱/条形编码长度,基线必须为 0 ax = ch.x_axis if ctype == "bar" else ch.y_axis ax.scaling.min = 0 notes.append("数值轴已强制从 0 —— 柱形编码的是长度,截断基线会放大差异") elif ctype == "line": ch = LineChart() ch.add_data(data_ref, titles_from_data=True) ch.set_categories(cats_ref) notes.append("折线图未强制 Y 轴从 0 —— 它编码位置和斜率," "强行归零会把真实波动压平") elif ctype == "pie": ch = PieChart() ch.add_data(data_ref, titles_from_data=True) ch.set_categories(cats_ref) elif ctype == "scatter": ch = ScatterChart() ch.style = 13 xref = Reference(ws, min_col=2, min_row=2, max_row=n + 1) for i in range(len(ycs)): yref = Reference(ws, min_col=2 + i, min_row=1, max_row=n + 1) s = Series(yref, xref, title_from_data=True) s.marker = Marker(symbol="circle", size=7) s.graphicalProperties.line.noFill = True # 散点不连线 ch.series.append(s) notes.append("散点图已关闭连线——连线会暗示时间顺序或因果") else: raise SystemExit(f"不支持的图表类型:{ctype}") ch.title = title or f"{ycs[0].name} by {xc.name if xc else ''}" if not title: notes.append("⚠ 没给标题,用了默认的主题式标题。" "标题应该写结论(「深圳南山店领先第二名 20%」)" "而不是主题(「各门店销售额」)——读者只看几秒") # 做工:去掉不承载信息的墨水 ch.height, ch.width = 9, 18 if hasattr(ch, "y_axis"): ch.y_axis.majorGridlines = None if len(ycs) == 1: ch.legend = None notes.append("单系列已去掉图例——图例会让眼睛在颜色和标签之间来回跑") # 色盲友好配色:避开红绿对立 try: for i, s in enumerate(ch.series): color = SAFE_PALETTE[i % len(SAFE_PALETTE)] if ctype == "line": s.graphicalProperties.line.solidFill = color s.graphicalProperties.line.width = 22000 # EMU,约 1.75pt else: s.graphicalProperties.solidFill = color s.graphicalProperties.line.solidFill = color if len(ch.series) > 1: notes.append(f"已套用色盲友好色板(避开红绿对立," f"约 8% 的男性有红绿色觉障碍)") except (AttributeError, TypeError): pass # 某些图表类型不支持逐系列上色,不因为配色失败而中断 ws2 = wb.create_sheet("chart") ws2.add_chart(ch, "B2") wb.save(out) return notes def render_suggestions(sugs: list[Suggestion], p: TableProfile) -> str: L = ["─" * 68, "图表建议", "─" * 68, ""] L.append("第一步不是选图表,是把要传达的信息写成一个完整的句子。") L.append("写不出那句话,画任何图都是在装饰数据。") L.append("") for i, s in enumerate(sugs, 1): L.append(f"{i}. {s.chart}" + (f" x={s.x}" if s.x else "") + (f" y={', '.join(s.y)}" if s.y else "")) L.append(f" {s.reason}") if s.title_hint: L.append(f" 标题:{s.title_hint}") for w in s.warnings: L.append(f" ⚠ {w}") L.append("") L.append("─" * 68) L.append("生成:make_chart.py <文件> --x <列> --y <列> --type <bar|col|line|scatter> --title \"结论\"") L.append("─" * 68) return "\n".join(L) def main() -> None: ap = argparse.ArgumentParser(description="判断该用什么图,然后生成 Excel 原生图表") ap.add_argument("file") ap.add_argument("--sheet", default=None) ap.add_argument("--suggest", action="store_true", help="只推荐图表类型,不生成") ap.add_argument("--x", default="", help="维度列名") ap.add_argument("--y", action="append", default=[], help="数值列名,可重复") ap.add_argument("--type", default="bar", choices=["bar", "col", "line", "pie", "scatter"]) ap.add_argument("--title", default="", help="图表标题,写结论不写主题") ap.add_argument("--out", default=None) a = ap.parse_args() src = Path(a.file).expanduser() if not src.exists(): sys.exit(f"文件不存在:{src}") if a.suggest or not a.y: p = profile(src, a.sheet) print(render_suggestions(suggest(p), p)) if not a.suggest: print("\n(没有指定 --y,只做了推荐。加上 --x/--y 才会生成图表。)") return out = Path(a.out).expanduser() if a.out else src.with_name(src.stem + "_chart.xlsx") notes = build(src, a.sheet, a.x, a.y, a.type, a.title, out) print(f"已生成:{out}") for n in notes: print(f" · {n}") if __name__ == "__main__": main()scripts/make_report.py64 KB9ebbccde5951upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
scripts/profile_table.py52 KB1c63984fd598upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
scripts/scan_traps.py15 KB03ae4d66defaupstream ↗
#!/usr/bin/env python3 # -*- coding: utf-8 -*- """分析陷阱扫描 —— 找出那些「算得对但结论错」的地方。 自动 EDA 到处都是。这个脚本做的是另一件事:把已知会让人得出错误结论的 统计陷阱变成可自动检测的项目。 扫这些: · 辛普森悖论 分组内的结论和总体的结论相反 · 幽灵分组 空格/大小写/全半角造成的重复类别 · 小基数 样本太少却在报百分比 · 时间断点 时间序列有缺口,趋势线会撒谎 · 不完整末期 最后一期没走完,看起来像断崖 · 双峰分布 混了两群对象,均值描述的是不存在的人 · 极端集中 少数几个值占了大部分,均值没有代表性 · 伪维度 高基数或常量列,不适合做分组 这些陷阱的共同点:数字全都算对了,错的是从数字到结论那一步。 所以它们逃得过对账,只能靠专门扫描。 用法 ---- python3 scan_traps.py <文件> [--sheet 名称] [--min-group 30] 依赖:openpyxl(读 .xlsx)。不用 pandas、不用 scipy。 """ from __future__ import annotations import argparse import sys from collections import defaultdict from dataclasses import dataclass, field from pathlib import Path from typing import Any sys.path.insert(0, str(Path(__file__).parent)) from profile_table import ( # noqa: E402 profile, parse_number, _norm, _is_blank, _merge_anchor_map, read_grid, five_number, FULLWIDTH_SPACE, ) from datetime import datetime MIN_GROUP = 30 # 小于这个样本量就不该报百分比 SIMPSON_MIN_LAYERS = 2 # 至少几层才值得检查辛普森悖论 @dataclass class Trap: kind: str where: str detail: str severity: str = "warn" # high | warn | info advice: str = "" @dataclass class ScanReport: path: str = "" sheet: str = "" traps: list[Trap] = field(default_factory=list) scanned: list[str] = field(default_factory=list) def add(self, t: Trap) -> None: self.traps.append(t) def _norm_key(s: str) -> str: """归一化后的分组键:用来发现「张伟」和「张伟 」其实是一个人。""" return (s.replace(FULLWIDTH_SPACE, "") .replace(" ", "") .strip() .lower() .replace("(", "(").replace(")", ")") .replace(",", ",") .replace("-", "-").replace("–", "-").replace("—", "-")) def scan(path: Path, sheet: str | None = None, min_group: int = MIN_GROUP) -> ScanReport: p = profile(path, sheet) grid, _ = read_grid(path, sheet) rep = ScanReport(path=str(path), sheet=p.sheet) if p.n_data_rows == 0: rep.add(Trap("无数据", "-", "没有识别出明细行", "high")) return rep amap = _merge_anchor_map(p.merged_ranges) excluded = {r["row"] for r in p.summary_rows} | {r["row"] for r in p.footnote_rows} rows = [r for r in range(p.data_start_row, p.data_end_row + 1) if r not in excluded and not all(_is_blank(v) for v in grid[r - 1])] def cell(row: int, ci: int) -> Any: r = grid[row - 1] if row - 1 < len(grid) else [] v = r[ci] if ci < len(r) else None if _is_blank(v) and (row, ci + 1) in amap: ar, ac = amap[(row, ci + 1)] src = grid[ar - 1] if ar - 1 < len(grid) else [] v = src[ac - 1] if ac - 1 < len(src) else None return v n = len(rows) cats = [c for c in p.columns if c.inferred_kind == "文本" and 1 < c.n_unique <= 20] meas = [c for c in p.columns if c.inferred_kind == "数值"] times = [c for c in p.columns if c.inferred_kind == "日期"] rep.scanned = [f"{n} 行", f"分类列 {len(cats)}", f"数值列 {len(meas)}", f"时间列 {len(times)}"] # ── 1. 幽灵分组 ──────────────────────────────────────────────── for c in p.columns: if c.inferred_kind != "文本": continue raw_vals = [_norm(cell(r, c.index)) for r in rows] raw_vals = [v for v in raw_vals if v] if not raw_vals: continue raw_u = set(raw_vals) norm_u = {_norm_key(v) for v in raw_vals} if len(raw_u) > len(norm_u): groups = defaultdict(set) for v in raw_vals: groups[_norm_key(v)].add(v) dup = {k: sorted(vs) for k, vs in groups.items() if len(vs) > 1} examples = ";".join(f"{vs!r}" for vs in list(dup.values())[:3]) rep.add(Trap( "幽灵分组", f"{c.letter}列「{c.name}」", f"看起来有 {len(raw_u)} 个类别,归一化后只有 {len(norm_u)} 个。" f"以下值实际是同一个:{examples}", "high", "groupby 之前先归一化:去首尾空格、去全角空格、统一大小写和中英文标点。" "不处理的话这些会被算成不同的组,每组的数都是残缺的。", )) # ── 2. 小基数 ────────────────────────────────────────────────── for c in cats: counts = defaultdict(int) for r in rows: v = _norm(cell(r, c.index)) if v: counts[_norm_key(v)] += 1 small = {k: v for k, v in counts.items() if v < min_group} if small and len(counts) > 1: worst = sorted(small.items(), key=lambda kv: kv[1])[:4] rep.add(Trap( "小基数", f"{c.letter}列「{c.name}」", f"{len(small)}/{len(counts)} 个分组的样本量少于 {min_group}:" + "、".join(f"{k}({v}行)" for k, v in worst), "warn", f"这些组不要报百分比,给绝对数。" f"样本 3 个的组「增长 200%」,实际上是多了 4 个。", )) # ── 3. 辛普森悖论 ────────────────────────────────────────────── # 对每个 (分组A, 分层B, 度量M):总体上 A1 vs A2 的方向, # 与「在各层 B 内部 A1 vs A2」的方向是否相反。 for m in meas: for a in cats: for b in cats: if a.index == b.index: continue # 总体:A 的各类别均值 overall = defaultdict(list) layered = defaultdict(lambda: defaultdict(list)) for r in rows: av = _norm_key(_norm(cell(r, a.index))) bv = _norm_key(_norm(cell(r, b.index))) mv, _ = parse_number(cell(r, m.index)) if not av or not bv or mv is None: continue overall[av].append(mv) layered[bv][av].append(mv) if len(overall) < 2 or len(layered) < SIMPSON_MIN_LAYERS: continue means = {k: sum(v) / len(v) for k, v in overall.items() if v} if len(means) < 2: continue top2 = sorted(means.items(), key=lambda kv: kv[1], reverse=True)[:2] (a1, m1), (a2, m2) = top2 if m1 == m2: continue # 在每一层里,a1 是否仍然高于 a2 flips, valid = 0, 0 for bv, inner in layered.items(): if a1 in inner and a2 in inner and inner[a1] and inner[a2]: valid += 1 i1 = sum(inner[a1]) / len(inner[a1]) i2 = sum(inner[a2]) / len(inner[a2]) if i1 < i2: flips += 1 if valid >= SIMPSON_MIN_LAYERS and flips == valid: rep.add(Trap( "辛普森悖论", f"{m.name} · {a.name} × {b.name}", f"总体上「{a1}」的均值({m1:,.2f})高于「{a2}」({m2:,.2f})," f"但在全部 {valid} 个「{b.name}」分层内部,结论都是反的。", "high", f"不要用总量下结论。差异来自各层的样本构成不同," f"不是「{a1}」真的更好。报告应该给分层结果," f"并说明构成差异。", )) # ── 4. 时间断点与不完整末期 ──────────────────────────────────── for t in times: ds: list[datetime] = [] for r in rows: raw = cell(r, t.index) if isinstance(raw, datetime): ds.append(raw) else: s = _norm(raw) for fmt in ("%Y-%m-%d", "%Y/%m/%d", "%Y年%m月%d日", "%Y-%m", "%Y/%m"): try: ds.append(datetime.strptime(s, fmt)) break except ValueError: continue if len(ds) < 3: continue ds.sort() gaps = [(ds[i + 1] - ds[i]).days for i in range(len(ds) - 1)] pos = sorted(g for g in gaps if g > 0) if not pos: continue typical = pos[len(pos) // 2] big = [(ds[i], ds[i + 1], gaps[i]) for i in range(len(gaps)) if gaps[i] > max(typical * 3, typical + 2)] if big: ex = "、".join(f"{s:%Y-%m-%d}→{e:%Y-%m-%d}({g}天)" for s, e, g in big[:3]) rep.add(Trap( "时间断点", f"{t.letter}列「{t.name}」", f"典型间隔 {typical} 天,但出现 {len(big)} 处明显更大的缺口:{ex}", "warn", "缺失的时间段不会报错,但会让趋势线撒谎。" "确认是真的没有业务,还是数据没采到。", )) # ── 5. 分布形态:双峰、极端集中 ──────────────────────────────── for c in meas: vals = [] for r in rows: v, _ = parse_number(cell(r, c.index)) if v is not None: vals.append(v) if len(vals) < 8: continue st = five_number(vals) total = sum(vals) # 极端集中:前 20% 的项贡献了多少 sv = sorted(vals, reverse=True) k = max(1, len(sv) // 5) top_share = sum(sv[:k]) / total if total else 0 if top_share > 0.8: rep.add(Trap( "极端集中", f"{c.letter}列「{c.name}」", f"前 20% 的项贡献了 {top_share:.0%} 的总量" f"(均值 {st['mean']:,.2f},中位数 {st['median']:,.2f})", "warn", "均值在这种分布下没有代表性。用中位数描述「典型」," "并把头部单独拿出来讲。丢掉头部那几个,整体结论会完全不同。", )) # 双峰的粗检:中间区域的密度低于两侧 lo, hi = st["min"], st["max"] if hi > lo and len(vals) >= 12: bins = [0] * 5 for v in vals: idx = min(4, int((v - lo) / (hi - lo) * 5)) bins[idx] += 1 mid = bins[2] if mid > 0 and bins[0] > mid * 1.5 and bins[4] > mid * 1.5: rep.add(Trap( "疑似双峰", f"{c.letter}列「{c.name}」", f"五等分后的分布为 {bins},两端明显高于中间", "warn", "可能混了两群性质不同的对象。均值会落在中间的谷底," "描述的是一个不存在的典型。先找出区分这两群的那个变量。", )) # ── 6. 伪维度 ────────────────────────────────────────────────── for c in p.columns: live = c.n_total - c.n_missing if live == 0: continue if c.n_unique == 1 and live > 1: rep.add(Trap("伪维度", f"{c.letter}列「{c.name}」", "常量列,所有行同一个值", "info", "对分析没有信息量,分组时跳过它。")) elif c.inferred_kind == "文本" and c.n_unique >= live * 0.95 and live > 5: rep.add(Trap("伪维度", f"{c.letter}列「{c.name}」", f"{c.n_unique} 个唯一值 / {live} 行,几乎每行都不同", "info", "这更像是编号或名称,不适合做分组维度。")) return rep def render(rep: ScanReport) -> str: L = ["─" * 68, f"陷阱扫描:{Path(rep.path).name} [{rep.sheet}]", "─" * 68] L.append("扫描范围:" + ",".join(rep.scanned)) L.append("") if not rep.traps: L.append("没有发现已知陷阱。") L.append("") L.append("注意:这只说明没踩到可自动检测的坑,不代表分析是对的。") L.append("「这个分析有没有意义」机器判不了。") L.append("─" * 68) return "\n".join(L) order = {"high": 0, "warn": 1, "info": 2} label = {"high": "会得出错误结论", "warn": "需要你判断", "info": "提示"} cur = None for t in sorted(rep.traps, key=lambda x: order.get(x.severity, 3)): if t.severity != cur: cur = t.severity L.append(f"【{label.get(cur, cur)}】") L.append(f" · {t.kind} {t.where}") L.append(f" {t.detail}") if t.advice: L.append(f" → {t.advice}") L.append("") L.append("─" * 68) L.append("这些陷阱的共同点:数字都算对了,错的是从数字到结论那一步。") L.append("它们逃得过对账,只能靠专门扫描。") L.append("─" * 68) return "\n".join(L) def main() -> None: ap = argparse.ArgumentParser(description="扫描会让人得出错误结论的分析陷阱") ap.add_argument("file") ap.add_argument("--sheet", default=None) ap.add_argument("--min-group", type=int, default=MIN_GROUP, help=f"小于这个样本量的分组会被标记,默认 {MIN_GROUP}") a = ap.parse_args() src = Path(a.file).expanduser() if not src.exists(): sys.exit(f"文件不存在:{src}") print(render(scan(src, a.sheet, a.min_group))) if __name__ == "__main__": main()scripts/verify_docx.py23 KBe4addb977a53upstream ↗
#!/usr/bin/env python3 # -*- coding: utf-8 -*- """Word 文档交付前的渲染自检——docx 版的闸门。 为什么需要它 ------------ HTML 报告有 verify_visual.py 把关,docx 长期没有。于是这几类错 只能靠人肉发现,而它们**在生成端全都不报错**: · 中文 run 没设 w:eastAsia → Word 用主题字体兜底,整篇变宋体 · 字体名是 Mac 或 Windows 独有 → 换台机器打开就回退 · 「空段落 + 分页符」的写法 → 上一页正好排满时留下一整页全白 · 表格跨页但表头没设重复 → 后续页面的表格没有列名 · 图片宽过版心 → 右边被裁掉 检查项(机器可判的事实,不判好看不好看) FAIL 中文字符所在 run 缺 w:eastAsia FAIL 图片宽度超出版心 FAIL 正文出现近乎空白的页(需要 soffice;缺了就跳过并说明) WARN 使用了跨平台风险字体 WARN 空段落里放分页符(空白页的成因) WARN 表格跨页但未设置表头重复 WARN 文档没有任何图片(图表被降级成表格时容易发生) 用法 python3 verify_docx.py 报告.docx python3 verify_docx.py 报告.docx --shots 自检/p 额外导出每页 PNG python3 verify_docx.py 报告.docx --json 退出码:有 FAIL 返回 1,否则 0。可直接当流水线闸门。 依赖:解析部分纯标准库;渲染部分需要 LibreOffice(soffice)与 pdftoppm, 装不上会跳过渲染类检查并明确告诉你哪几项没验,不会假装通过。 """ from __future__ import annotations import argparse import glob import json import os import re import shutil import subprocess import sys import tempfile import zipfile from pathlib import Path from xml.etree import ElementTree as ET W = "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}" A = "{http://schemas.openxmlformats.org/drawingml/2006/main}" WP = "{http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing}" CJK = re.compile(r"[㐀-鿿豈- -〿-]") # Microsoft Office 在 Windows 与 macOS 上都随装的中日韩字体。 # 只有这一组能保证「换台机器打开还是这个样子」。 SAFE_EASTASIA = { "Microsoft YaHei", "微软雅黑", "Microsoft YaHei UI", "DengXian", "等线", "DengXian Light", "等线 Light", "SimSun", "宋体", "NSimSun", "新宋体", "SimHei", "黑体", "KaiTi", "楷体", "FangSong", "仿宋", "Microsoft JhengHei", "微軟正黑體", "MS Gothic", "MS Mincho", "Yu Gothic", "Meiryo", "Malgun Gothic", } # 常见的「只在一个平台上有」的字体,命中就提示 PLATFORM_ONLY = { "PingFang SC": "仅 macOS", "PingFang TC": "仅 macOS", "Hiragino Sans GB": "仅 macOS", "STHeiti": "仅 macOS", "Heiti SC": "仅 macOS", "Songti SC": "仅 macOS", "Helvetica": "仅 macOS(Windows 会回退到 Arial)", "Helvetica Neue": "仅 macOS", "Segoe UI": "仅 Windows", "Calibri": "Windows 与新版 Office", "Source Han Sans": "需自行安装", "Noto Sans CJK SC": "需自行安装", } EMU_PER_CM = 360000 def xml_health(path: Path) -> list[str]: """包结构合法性。后处理脚本(补图、改字体)最容易把包改坏—— 实测有人往 [Content_Types].xml 插节点插到了根元素外面,Word 和 LibreOffice 都拒绝打开,而当时的闸门照样解析成功、全绿放行。 所以先验包,包坏了后面的一切检查都没有意义。""" probs: list[str] = [] with zipfile.ZipFile(path) as z: names = set(z.namelist()) for req in ("[Content_Types].xml", "_rels/.rels", "word/document.xml"): if req not in names: probs.append(f"缺关键部件 {req},Word 无法打开") for n in sorted(names): if n.endswith(".xml") or n.endswith(".rels"): try: ET.fromstring(z.read(n)) except ET.ParseError as e: probs.append(f"{n} 不是合法 XML({e})——Word/LibreOffice 会拒绝打开," "多半是后处理脚本把节点插到了根元素外面") # 图片引用三方一致:document 里的 r:embed ↔ rels ↔ media 实体文件 if "word/_rels/document.xml.rels" in names and "word/document.xml" in names: try: relx = ET.fromstring(z.read("word/_rels/document.xml.rels")) rels = {r.get("Id"): r.get("Target") for r in relx} doc_raw = z.read("word/document.xml").decode("utf-8", "ignore") for rid in set(re.findall(r'r:embed="([^"]+)"', doc_raw)): tgt = rels.get(rid) if not tgt: probs.append(f"图片引用 {rid} 在 rels 里没有对应关系,该图会显示为红叉") elif f"word/{tgt.lstrip('/')}" not in names and tgt.lstrip("/") not in names: probs.append(f"图片 {rid} 指向 {tgt},包内没有这个文件") except ET.ParseError: pass # 上面已经报过 return probs def _local(tag: str) -> str: return tag.split("}")[-1] def parse(path: Path) -> dict: """把 docx 拆出检查需要的事实。纯标准库。""" with zipfile.ZipFile(path) as z: doc = ET.fromstring(z.read("word/document.xml")) names = set(z.namelist()) media = [n for n in names if n.startswith("word/media/")] styles = None if "word/styles.xml" in names: styles = ET.fromstring(z.read("word/styles.xml")) # 版心宽度(EMU) sect = doc.find(f".//{W}sectPr") text_w_emu = None if sect is not None: pg, mar = sect.find(f"{W}pgSz"), sect.find(f"{W}pgMar") if pg is not None and mar is not None: tw = int(pg.get(f"{W}w", 0)) lm = int(mar.get(f"{W}left", 0)); rm = int(mar.get(f"{W}right", 0)) text_w_emu = (tw - lm - rm) * 635 # twip → EMU # 样式继承:run 没写 rFonts 时会继承段落样式、再继承 docDefaults。 # 只看 run 级别会把「字体声明在样式里」这种完全合法的写法误判为缺字体。 style_ea: dict[str, str] = {} style_based: dict[str, str] = {} default_ea = None if styles is not None: dd = styles.find(f"{W}docDefaults") if dd is not None: for rf in dd.iter(f"{W}rFonts"): default_ea = rf.get(f"{W}eastAsia") or default_ea for st in styles.iter(f"{W}style"): sid = st.get(f"{W}styleId") if not sid: continue bo = st.find(f"{W}basedOn") if bo is not None and bo.get(f"{W}val"): style_based[sid] = bo.get(f"{W}val") rf = st.find(f"{W}rPr/{W}rFonts") if rf is not None and rf.get(f"{W}eastAsia"): style_ea[sid] = rf.get(f"{W}eastAsia") def resolve_style_ea(sid: str | None) -> str | None: """顺着 basedOn 链找 eastAsia,找不到就回落到 docDefaults。""" seen = set() while sid and sid not in seen: seen.add(sid) if sid in style_ea: return style_ea[sid] sid = style_based.get(sid) return default_ea bad_runs, fonts, ea_fonts, empty_break = [], set(), set(), 0 for p in doc.iter(f"{W}p"): runs = list(p.iter(f"{W}r")) ps = p.find(f"{W}pPr/{W}pStyle") inherited = resolve_style_ea(ps.get(f"{W}val") if ps is not None else None) ptext = "".join(t.text or "" for t in p.iter(f"{W}t")) has_break = any(b.get(f"{W}type") == "page" for b in p.iter(f"{W}br")) if has_break and not ptext.strip(): empty_break += 1 for r in runs: rf = r.find(f"{W}rPr/{W}rFonts") if rf is not None: for k in ("ascii", "hAnsi", "eastAsia", "cs"): v = rf.get(f"{W}{k}") if v: fonts.add(v) if k == "eastAsia": ea_fonts.add(v) txt = "".join(t.text or "" for t in r.iter(f"{W}t")) if CJK.search(txt): ea = (rf.get(f"{W}eastAsia") if rf is not None else None) or inherited if not ea: bad_runs.append(txt.strip()[:28]) else: ea_fonts.add(ea) # 图片尺寸 images = [] for ext in doc.iter(f"{WP}extent"): images.append((int(ext.get("cx", 0)), int(ext.get("cy", 0)))) # 表格:行数、是否设了表头重复 tables = [] for t in doc.iter(f"{W}tbl"): rows = list(t.iter(f"{W}tr")) has_hdr = any(r.find(f"{W}trPr/{W}tblHeader") is not None for r in rows) tables.append({"rows": len(rows), "header_repeat": has_hdr}) return { "bad_runs": bad_runs, "fonts": sorted(fonts | set(style_ea.values()) | ({default_ea} if default_ea else set())), "eastasia_fonts": sorted(ea_fonts), "style_eastasia": sorted(set(style_ea.values())), "empty_page_breaks": empty_break, "images": images, "media": len(media), "tables": tables, "text_width_emu": text_w_emu, } def _font_installed(name: str) -> bool: """本机有没有这个字体。探测不了就返回 True,宁可漏报不误报。""" try: out = subprocess.run(["fc-list", ":", "family"], capture_output=True, timeout=20, text=True) if out.returncode == 0 and out.stdout: return name.lower() in out.stdout.lower() except Exception: pass if sys.platform == "darwin": try: out = subprocess.run(["system_profiler", "-json", "SPFontsDataType"], capture_output=True, timeout=60, text=True) if out.returncode == 0 and out.stdout: return name.lower() in out.stdout.lower() except Exception: pass return True def render_pages(path: Path, shots: str | None) -> tuple[list[float] | None, str]: """用 soffice 转 PDF 再逐页转 PNG,算每页的内容占比。缺工具就返回 None。""" if not shutil.which("soffice"): return None, "未找到 soffice(LibreOffice),跳过空白页检查" if not shutil.which("pdftoppm"): return None, "未找到 pdftoppm(poppler),跳过空白页检查" try: from PIL import Image except ImportError: return None, "未安装 Pillow,跳过空白页检查" tmp = tempfile.mkdtemp(prefix="verify_docx_") try: r = subprocess.run( ["soffice", "--headless", f"-env:UserInstallation=file://{tmp}/profile", "--convert-to", "pdf", "--outdir", tmp, str(path)], capture_output=True, timeout=300) pdfs = glob.glob(os.path.join(tmp, "*.pdf")) if not pdfs: return None, f"soffice 转换失败,跳过空白页检查({r.stderr.decode()[:80]})" subprocess.run(["pdftoppm", "-png", "-r", "80", pdfs[0], os.path.join(tmp, "pg")], capture_output=True, timeout=300) pngs = sorted(glob.glob(os.path.join(tmp, "pg-*.png"))) ratios = [] for f in pngs: im = Image.open(f).convert("L") w, h = im.size px = im.load() dark = sum(1 for y in range(0, h, 3) for x in range(0, w, 3) if px[x, y] < 230) ratios.append(dark / (len(range(0, h, 3)) * len(range(0, w, 3)))) if shots: outdir = os.path.dirname(shots) or "." os.makedirs(outdir, exist_ok=True) for i, f in enumerate(pngs, 1): shutil.copy(f, f"{shots}_{i:02d}.png") return ratios, f"渲染 {len(pngs)} 页" except subprocess.TimeoutExpired: return None, "soffice 超时,跳过空白页检查" finally: shutil.rmtree(tmp, ignore_errors=True) # ── 自检:造三份「已知有病」的文档,断言全被拦下 ────────────────── # 闸门自己也会烂。改过这个文件之后跑一次 --self-test, # 确认它还抓得住它当初就是为了抓的那三类错。纯标准库,不装 python-docx。 _MIN_DOC = ( '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' '<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">' '<w:body>{body}' '<w:sectPr><w:pgSz w:w="11906" w:h="16838"/>' '<w:pgMar w:top="1418" w:right="1418" w:bottom="1418" w:left="1418"/>' '</w:sectPr></w:body></w:document>') _RELS = ('<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">' '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/' '2006/relationships/officeDocument" Target="word/document.xml"/></Relationships>') _CT = ('<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' '<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">' '<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.' 'relationships+xml"/><Default Extension="xml" ContentType="application/xml"/>' '<Override PartName="/word/document.xml" ContentType="application/vnd.' 'openxmlformats-officedocument.wordprocessingml.document.main+xml"/></Types>') def _write_docx(path: str, body: str) -> None: with zipfile.ZipFile(path, "w", zipfile.ZIP_DEFLATED) as z: z.writestr("[Content_Types].xml", _CT) z.writestr("_rels/.rels", _RELS) z.writestr("word/document.xml", _MIN_DOC.format(body=body)) def _run(text: str, ea: str | None = None, latin: str | None = None) -> str: rf = "" if ea or latin: parts = [] if latin: parts.append(f'w:ascii="{latin}" w:hAnsi="{latin}"') if ea: parts.append(f'w:eastAsia="{ea}"') rf = f'<w:rPr><w:rFonts {" ".join(parts)}/></w:rPr>' return f'<w:p><w:r>{rf}<w:t xml:space="preserve">{text}</w:t></w:r></w:p>' def self_test() -> int: cases = [ ("中文 run 缺 eastAsia", _run("这段中文没有设置东亚字体,Word 会兜底成宋体。", latin="Calibri"), "没有设置 w:eastAsia"), ("东亚字体绑定单一平台", _run("苹方只有 macOS 上才有。", ea="PingFang SC"), "换台机器打开"), ("空段落里放分页符", _run("正文。", ea="Microsoft YaHei") + '<w:p><w:r><w:br w:type="page"/></w:r></w:p>', "空段落 + 分页符"), ] tmp = tempfile.mkdtemp(prefix="verify_docx_selftest_") ok = True try: for i, (name, body, expect) in enumerate(cases): f = os.path.join(tmp, f"case{i}.docx") _write_docx(f, body) d = parse(Path(f)) blob = json.dumps(d, ensure_ascii=False) hit = (expect == "没有设置 w:eastAsia" and d["bad_runs"]) or \ (expect == "换台机器打开" and any(x in PLATFORM_ONLY for x in d["eastasia_fonts"])) or \ (expect == "空段落 + 分页符" and d["empty_page_breaks"]) print(f" {'✓' if hit else '✗'} {name}") ok = ok and bool(hit) # 反向用例:正确写法不该被误报(含「字体声明在段落样式里」这种合法写法) f = os.path.join(tmp, "good.docx") _write_docx(f, _run("这段中文显式带了东亚字体。", ea="Microsoft YaHei", latin="Microsoft YaHei")) d = parse(Path(f)) clean = not d["bad_runs"] and not d["empty_page_breaks"] and \ not any(x in PLATFORM_ONLY for x in d["eastasia_fonts"]) print(f" {'✓' if clean else '✗'} 正确写法不误报") ok = ok and clean finally: shutil.rmtree(tmp, ignore_errors=True) print("\n自检" + ("通过" if ok else "未通过——闸门坏了,先修它再用它验别的文档")) return 0 if ok else 1 def main() -> int: ap = argparse.ArgumentParser(description="Word 文档交付前自检") ap.add_argument("docx", nargs="?") ap.add_argument("--self-test", action="store_true", help="造三份已知有病的文档,确认闸门还抓得住") ap.add_argument("--shots", metavar="前缀", help="额外把每页导出成 PNG") ap.add_argument("--json", action="store_true") ap.add_argument("--min-ink", type=float, default=0.02, help="内容占比低于此值判为近乎空白页,默认 0.02") a = ap.parse_args() if a.self_test: return self_test() if not a.docx: ap.error("需要给一个 .docx 路径,或用 --self-test") path = Path(a.docx) if not path.exists(): print(f"找不到文件:{path}", file=sys.stderr) return 2 # ⓪ 包结构:坏包一票否决,后面的检查都建立在能解析之上 health = xml_health(path) if health: print("❌ FAIL:包结构已损坏,其余检查跳过") for h in health: print(" -", h) return 1 d = parse(path) fails: list[str] = [] warns: list[str] = [] skipped: list[str] = [] # ① 中文 run 缺 eastAsia —— 整篇字体走样的头号成因 if d["bad_runs"]: n = len(d["bad_runs"]) uniq = list(dict.fromkeys(d["bad_runs"])) sample = "、".join(f"「{s}」" for s in uniq[:3]) fails.append( f"{n} 个含中文的 run 没有设置 w:eastAsia,Word 会用主题字体兜底" f"(通常回退成宋体)。样例:{sample}") # ② 跨平台风险字体 # 中文字体绑定单一平台 → FAIL:整篇中文走样,且换机器之前完全看不出来。 # 西文字体绑定单一平台 → WARN:Word 会回退到度量相近的字体,后果轻。 ea_declared = {v for v in d["eastasia_fonts"]} for fnt in sorted(ea_declared): if fnt in PLATFORM_ONLY: fails.append( f"东亚字体「{fnt}」{PLATFORM_ONLY[fnt]}——换台机器打开," f"整篇中文会回退成主题字体。改用 Office 双平台自带的:" f"Microsoft YaHei / DengXian / SimSun / SimHei") for fnt in sorted(set(d["fonts"]) - ea_declared): if fnt in PLATFORM_ONLY: warns.append(f"西文字体「{fnt}」{PLATFORM_ONLY[fnt]}——换平台会回退到度量相近的字体") if ea_declared and not (ea_declared & SAFE_EASTASIA) and not (ea_declared & set(PLATFORM_ONLY)): warns.append( f"东亚字体「{'、'.join(sorted(ea_declared))}」不在 Office 双平台自带清单里," "换机器可能变样。安全清单:Microsoft YaHei / DengXian / SimSun / SimHei / KaiTi / FangSong") # ③ 空段落里的分页符 —— 整页空白的成因 if d["empty_page_breaks"]: warns.append( f"{d['empty_page_breaks']} 处「空段落 + 分页符」。空段落本身占一行," "上一页正好排满时会被挤到下一页、分页符再把正文推到再下一页," "于是留下一整页全白。改用段落属性 page_break_before。") # ④ 图片宽过版心 if d["text_width_emu"]: over = [(cx, cy) for cx, cy in d["images"] if cx > d["text_width_emu"]] if over: fails.append( f"{len(over)} 张图片宽度超出版心" f"(版心 {d['text_width_emu']/EMU_PER_CM:.1f}cm," f"最宽的图 {max(c for c,_ in over)/EMU_PER_CM:.1f}cm),右侧会被裁掉") # ⑤ 长表格没设表头重复 for i, t in enumerate(d["tables"], 1): if t["rows"] >= 12 and not t["header_repeat"]: warns.append(f"表 {i} 有 {t['rows']} 行且未设置表头重复" "(w:tblHeader),跨页后读者看不到列名") # ⑥ 一张图都没有 if not d["images"]: warns.append("文档里没有任何图片。图表被降级成数据表时会这样——" "确认这是有意的取舍,而不是图没嵌进去") # ⑦ 空白页(需要渲染) ratios, note = render_pages(path, a.shots) pages = None if ratios is None: skipped.append(note) else: pages = len(ratios) missing = [f for f in d["fonts"] if not _font_installed(f)] if missing: skipped.append( f"渲染时本机缺字体:{'、'.join(missing)}。LibreOffice 用替代字体排的版," "所以页数与空白页位置只是近似——最终请在 Word 里再看一眼") blanks = [i + 1 for i, r in enumerate(ratios[:-1]) if r < a.min_ink] if blanks: where = f"第 {'、'.join(map(str, blanks))} 页近乎空白(末页除外,末页短属正常)" if missing: # 字体都缺了,分页本来就是近似的——不能拿这个证据下硬结论。 warns.append(where + "。但本机缺字体、排版是替代字体算出来的," "这个页码不一定对得上 Word 里的实际情况,请在 Word 里复核") else: fails.append(where) if a.json: print(json.dumps({"fails": fails, "warns": warns, "skipped": skipped, "pages": pages, "images": len(d["images"]), "tables": len(d["tables"]), "fonts": d["fonts"]}, ensure_ascii=False, indent=2)) return 1 if fails else 0 line = "─" * 68 print(line) head = f"Word 自检:{path.name}" if pages: head += f" {pages} 页" head += f" / {len(d['images'])} 图 / {len(d['tables'])} 表" print(head) print(line) if fails: print(f"\n❌ FAIL {len(fails)} 项(必须修)") for x in fails: print(f" - {x}") if warns: print(f"\n⚠ WARN {len(warns)} 项(自己判断)") for x in warns: print(f" - {x}") if skipped: print(f"\n○ 跳过 {len(skipped)} 项(工具缺失,**不等于通过**)") for x in skipped: print(f" - {x}") if not fails and not warns: if skipped: print(f"\n✅ 已验的项目全部通过——但上面 {len(skipped)} 项没验成," "别把它当作全部通过") else: print("\n✅ 全部通过") print(f"\n用到的字体:{'、'.join(d['fonts']) or '(未显式指定,全走主题字体)'}") print("\n机器只判「有没有画错」。这几件它判不了,自己翻一遍导出的页面图:") print(" · 每张图能不能独立回答它标题里那句话") print(" · 表格有没有该合并却拆开的列") print(" · 首页能不能在十秒内看懂核心结论") print(line) return 1 if fails else 0 if __name__ == "__main__": sys.exit(main())scripts/verify_numbers.py18 KB15b8c5a8d594upstream ↗
#!/usr/bin/env python3 # -*- coding: utf-8 -*- """数字对账 —— 交付之前,用表自己的数据证明你没算错。 核心思路 -------- 中文办公表格几乎都自带「合计」「小计」行。所有工具都把它们当噪音过滤掉, 但它们其实是**免费的校验和**:那是原表作者用 Excel 公式算出来的真值。 拿清洗后的明细自己求和,去对那个合计。对得上,你的清洗是对的;对不上, 要么你的清洗错了,要么原表错了 —— 两种情况都必须报出来,不能沉默。 这对应 ICAEW《Financial Modelling Code》的两条: Include a master check —— 一个总检查,任何一项失败就报警 Build traceable references —— 每个数字都能追回它的来源 同时执行 Twyman's Law:任何看起来有趣或异常的数字,通常都是错的。 本脚本把「异常」量化成可自动判定的检查项,不靠人去凭感觉发现。 用法 ---- python3 verify_numbers.py <文件> [--sheet 名称] [--json] # 顺便核对一个你自己算出来的数 python3 verify_numbers.py <文件> --claim "1月:12387317" 退出码:0 = 全部通过;1 = 有对不上的地方(可直接用在流水线里当闸门) """ from __future__ import annotations import argparse import json import sys from dataclasses import dataclass, field, asdict from pathlib import Path from typing import Any sys.path.insert(0, str(Path(__file__).parent)) from profile_table import ( # noqa: E402 profile, parse_number, _norm, _is_blank, TableProfile, read_grid, _merge_anchor_map, ) # 汇总行是分层的:「华东小计」管一个分组,「合计」管整张表。 # 把它们当成平级的连续区段来划分覆盖范围,遇到两级汇总必然算错。 GROUP_LEVEL_WORDS = ("小计", "subtotal") TOTAL_LEVEL_WORDS = ("合计", "总计", "总和", "累计", "汇总", "共计", "总额", "total", "grand total", "sum") RATIO_WORDS = ("占比", "比例", "同比", "环比", "增长", "率", "rate", "%") def summary_level(label: str) -> str: """判断汇总行管辖的层级:group(分组小计)/ total(全表合计)/ unknown。""" t = label.strip().lower() if any(w in t for w in GROUP_LEVEL_WORDS): return "group" if any(w in t for w in TOTAL_LEVEL_WORDS): return "total" return "unknown" # 相对误差容忍度:小于这个值视作「因四舍五入产生的差异」而非真错 REL_TOL = 1e-6 # 量级怀疑阈值:列名声明的单位与实际数值量级差这么多倍就报警 MAGNITUDE_FACTOR = 100 @dataclass class Check: name: str passed: bool detail: str severity: str = "error" # error | warn | info evidence: dict[str, Any] = field(default_factory=dict) @dataclass class VerifyReport: path: str = "" sheet: str = "" checks: list[Check] = field(default_factory=list) master_check: bool = True caliber: dict[str, Any] = field(default_factory=dict) def add(self, c: Check) -> None: self.checks.append(c) if not c.passed and c.severity == "error": self.master_check = False # ── 单位量级 ────────────────────────────────────────────────────────── UNIT_SCALE = { "亿元": 1e8, "亿": 1e8, "万元": 1e4, "万": 1e4, "千元": 1e3, "元": 1.0, } def declared_unit(col_name: str) -> tuple[str, float] | None: """从列名里读出声明的单位,如「上半年合计(万元)」→ ('万元', 1e4)。""" for u in sorted(UNIT_SCALE, key=len, reverse=True): if u in col_name: return u, UNIT_SCALE[u] return None # ── 主流程 ──────────────────────────────────────────────────────────── def verify(path: Path, sheet: str | None = None, claims: dict[str, float] | None = None) -> VerifyReport: p: TableProfile = profile(path, sheet) grid, _meta = read_grid(path, sheet) rep = VerifyReport(path=str(path), sheet=p.sheet) width = len(p.columns) if width == 0 or p.n_data_rows == 0: rep.add(Check("可解析性", False, "没有识别出明细数据,无法对账")) return rep # 明细行号(1-based),已排除汇总/脚注 excluded = {r["row"] for r in p.summary_rows} | {r["row"] for r in p.footnote_rows} detail_rows = [r for r in range(p.data_start_row, p.data_end_row + 1) if r not in excluded and not all(_is_blank(v) for v in grid[r - 1])] dup_rows = {d["row"] for d in p.duplicate_rows} # ── 口径声明:先把话说清楚,再谈数字 ────────────────────────── rep.caliber = { "明细行范围": f"第 {p.data_start_row}-{p.data_end_row} 行", "明细行数": len(detail_rows), "已排除行": sorted(excluded) or "无", "重复行": sorted(dup_rows) or "无", "去重后行数": len(detail_rows) - len(dup_rows), "表头行": p.header_rows, "说明": "以下所有数字均基于「明细行、未去重」口径。若业务上应当去重," "结果会变化,见「去重影响」检查项。", } # ── 检查 1:行数守恒 ──────────────────────────────────────────── span = p.data_end_row - p.data_start_row + 1 blanks = sum(1 for r in range(p.data_start_row, p.data_end_row + 1) if all(_is_blank(v) for v in grid[r - 1])) accounted = len(detail_rows) + len([r for r in excluded if p.data_start_row <= r <= p.data_end_row]) + blanks rep.add(Check( "行数守恒", accounted == span, f"数据区跨 {span} 行 = 明细 {len(detail_rows)} + 已排除 " f"{accounted - len(detail_rows) - blanks} + 空行 {blanks}" + ("" if accounted == span else f" ← 差 {span - accounted} 行没有归属,说明分类逻辑漏了情况"), evidence={"span": span, "detail": len(detail_rows), "blank": blanks}, )) # ── 合并单元格 ffill:分组标签列的空值要先恢复,否则没法按组匹配 ── amap = _merge_anchor_map(p.merged_ranges) def cell(row: int, ci: int) -> Any: """取单元格值,落在合并区内的取其左上角的值。""" r = grid[row - 1] if row - 1 < len(grid) else [] v = r[ci] if ci < len(r) else None if _is_blank(v) and (row, ci + 1) in amap: ar, ac = amap[(row, ci + 1)] src = grid[ar - 1] if ar - 1 < len(grid) else [] v = src[ac - 1] if ac - 1 < len(src) else None return v def num_at(row: int, ci: int) -> float | None: v, _ = parse_number(cell(row, ci)) return v # ── 检查 2:与表内汇总行对账(核心)──────────────────────────── summary_lookup = {r["row"]: r for r in p.summary_rows} text_cols = [c for c in p.columns if c.inferred_kind == "文本"] checked_any = False def resolve_scope(srow: int, label: str) -> tuple[list[int], str] | None: """这个汇总行到底管哪些明细行?定不下来就返回 None,不猜。""" level = summary_level(label) if level == "total": return detail_rows, "全表明细" if level == "group": # 从「华东小计」剥出「华东」,再去各文本列里找这个分组 name = label for w in GROUP_LEVEL_WORDS: name = name.replace(w, "").replace(w.upper(), "") name = name.strip(" -—_::()()") if name: for tc in text_cols: matched = [r for r in detail_rows if _norm(cell(r, tc.index)) == name] if matched: return matched, f"{tc.letter}列「{tc.name}」== {name}" return None for srow, sinfo in sorted(summary_lookup.items()): label = sinfo.get("label", "") if any(w in label for w in RATIO_WORDS): continue # 比率行不是求和,不参与对账 scope = resolve_scope(srow, label) if scope is None: rep.add(Check( f"对账 · 第{srow}行「{label}」", True, "定不下来这一行管哪些明细,跳过对账。" "(宁可不对,也不用推断出来的范围去对——那会给出一个错的结论。)" "请人工确认它的覆盖范围。", severity="warn", )) continue covered, basis = scope for col in p.columns: if col.inferred_kind != "数值": continue claimed = num_at(srow, col.index) if claimed is None: continue vals = [num_at(r, col.index) for r in covered] actual = sum(v for v in vals if v is not None) if claimed == 0: rel = 0.0 if abs(actual) < REL_TOL else float("inf") else: rel = abs(actual - claimed) / abs(claimed) ok = rel <= REL_TOL checked_any = True rep.add(Check( f"对账 · {col.letter}列「{col.name}」 vs 第{srow}行「{label}」", ok, (f"表内写 {claimed:,.2f},按「{basis}」取 {len(covered)} 行" f"算得 {actual:,.2f}" + (" ✓ 一致" if ok else f" ✗ 差 {actual - claimed:,.2f}({rel:.2%})")), severity="error" if not ok else "info", evidence={"claimed": claimed, "actual": actual, "basis": basis, "rows": covered, "cell": f"{col.letter}{srow}"}, )) if not checked_any: rep.add(Check( "对账基准", True, "表内没有可用的汇总行做交叉验证。这意味着结果没有独立的校验来源 —— " "交付前请人工抽查至少 3 个数字回溯到源单元格。", severity="warn", )) # ── 检查 3:去重的影响有多大 ─────────────────────────────────── if dup_rows: for col in p.columns: if col.inferred_kind != "数值": continue ci = col.index def v(r: int) -> float: x, _ = parse_number(grid[r - 1][ci]) if ci < len(grid[r - 1]) else (None, []) return x or 0.0 with_dup = sum(v(r) for r in detail_rows) without = sum(v(r) for r in detail_rows if r not in dup_rows) if with_dup == 0: continue delta = (with_dup - without) / abs(with_dup) rep.add(Check( f"去重影响 · {col.letter}列「{col.name}」", True, f"含重复 {with_dup:,.2f},去重后 {without:,.2f}," f"相差 {delta:.2%} —— 这两个数都对,取哪个取决于业务口径。" f"必须明确声明用的是哪个。", severity="warn", evidence={"with_dup": with_dup, "dedup": without}, )) # ── 检查 4:单位量级是否与列名声明相符 ───────────────────────── for col in p.columns: if col.inferred_kind != "数值" or not col.stats: continue du = declared_unit(col.name) if not du: continue unit, scale = du med = col.stats.get("median", 0) if med <= 0: continue # 如果声明是「万元」,中位数却在百万量级,多半是单位写错或数据没换算 implied = med * scale suspicious = False note = "" if unit != "元" and med > MAGNITUDE_FACTOR * 1e4: suspicious = True note = (f"列名声明单位是「{unit}」,但中位数已经是 {med:,.0f}," f"换算成元是 {implied:,.0f} —— 量级可疑," f"很可能数值本身就是「元」而列名没改") if suspicious: rep.add(Check(f"单位一致性 · {col.letter}列「{col.name}」", False, note, severity="error", evidence={"median": med, "declared_unit": unit})) # ── 检查 5:Twyman's Law —— 异常值必须被解释 ─────────────────── for col in p.columns: s = col.stats if not s or not s.get("outlier_count"): continue ex = ", ".join(f"{x:,.0f}" for x in s["outlier_examples"]) rep.add(Check( f"异常值 · {col.letter}列「{col.name}」", True, f"{s['outlier_count']} 个值落在 IQR 1.5 倍之外:{ex}。" f"Twyman's Law:看起来异常的数字通常是错的 —— " f"逐个确认它们是真实业务(大客户、大促)还是脏数据(单位错、多打一个零)。", severity="warn", evidence={"outliers": s["outlier_examples"]}, )) # ── 检查 6:外部声称核对 ─────────────────────────────────────── if claims: by_name = {c.name: c for c in p.columns} for key, claimed in claims.items(): col = by_name.get(key) if col is None: # 模糊匹配 cands = [c for c in p.columns if key in c.name] col = cands[0] if len(cands) == 1 else None if col is None: rep.add(Check(f"声称核对 · {key}", False, f"找不到名为「{key}」的列,无法核对", severity="error")) continue ci = col.index actual = 0.0 for r in detail_rows: v, _ = parse_number(grid[r - 1][ci]) if ci < len(grid[r - 1]) else (None, []) actual += v or 0.0 rel = abs(actual - claimed) / abs(claimed) if claimed else float("inf") rep.add(Check( f"声称核对 · {key}", rel <= REL_TOL, f"你说 {claimed:,.2f},明细求和 {actual:,.2f}" + (" ✓" if rel <= REL_TOL else f" ✗ 差 {actual - claimed:,.2f}({rel:.2%})"), evidence={"claimed": claimed, "actual": actual}, )) return rep # ── 输出 ────────────────────────────────────────────────────────────── def render(rep: VerifyReport) -> str: L: list[str] = [] add = L.append bar = "─" * 68 add(bar) add(f"数字对账:{Path(rep.path).name} [{rep.sheet}]") add(bar) add("") add("【口径声明】结论的前提,先说清楚") for k, v in rep.caliber.items(): add(f" {k}:{v}") errs = [c for c in rep.checks if not c.passed and c.severity == "error"] warns = [c for c in rep.checks if c.severity == "warn"] infos = [c for c in rep.checks if c.passed and c.severity == "info"] if errs: add("") add("【对不上 —— 必须解决】") for c in errs: add(f" ✗ {c.name}") add(f" {c.detail}") if infos: add("") add("【对上了】") for c in infos: add(f" ✓ {c.name}") add(f" {c.detail}") if warns: add("") add("【需要你做判断 —— 脚本判不了的部分】") for c in warns: add(f" ? {c.name}") add(f" {c.detail}") add("") add(bar) if rep.master_check: add("MASTER CHECK:通过。所有可机器验证的项目都对得上。") add("注意:机器只能验证「算得对不对」,验证不了「这个分析有没有意义」。") else: add(f"MASTER CHECK:不通过。{len(errs)} 项对不上,见上。") add("在解决之前,不要把这些数字写进任何交付物。") add(bar) return "\n".join(L) def main() -> None: ap = argparse.ArgumentParser(description="数字对账:用表自己的数据证明你没算错") ap.add_argument("file") ap.add_argument("--sheet", default=None) ap.add_argument("--json", action="store_true") ap.add_argument("--claim", action="append", default=[], help='核对你自己算的数,格式 "列名:数值",可重复') a = ap.parse_args() path = Path(a.file).expanduser() if not path.exists(): sys.exit(f"文件不存在:{path}") claims: dict[str, float] = {} for c in a.claim: if ":" not in c and ":" not in c: sys.exit(f'--claim 格式应为 "列名:数值",收到:{c}') k, _, v = c.replace(":", ":").partition(":") try: claims[k.strip()] = float(v.replace(",", "").strip()) except ValueError: sys.exit(f"无法解析数值:{v}") rep = verify(path, a.sheet, claims or None) if a.json: print(json.dumps(asdict(rep), ensure_ascii=False, indent=2, default=str)) else: print(render(rep)) sys.exit(0 if rep.master_check else 1) if __name__ == "__main__": main()scripts/verify_visual.py14 KB65398705ac9dupstream ↗
#!/usr/bin/env python3 # -*- coding: utf-8 -*- """ verify_visual.py — 交付前的渲染闸门。 数字有 verify_numbers.py 把关,图表一直没有。手写 SVG 必然会犯的那几类错 (线画出框、标签叠成一团、文字压住柱子、图上数字和正文对不上), 肉眼扫一遍看不出来,渲染出来一看全在。这个脚本把它们变成退出码。 它只判机器能判死的事实,不判美不美——那是你的活。 用法: python3 verify_visual.py 报告.html python3 verify_visual.py 报告.html --shots 自检 # 顺带存分屏截图 python3 verify_visual.py 报告.html --json 退出码:0 = 通过;1 = 有 FAIL;2 = 环境缺 playwright(不算失败,会提示改用人工) 依赖 playwright(pip install playwright && playwright install chromium)。 装不上就手动开一眼浏览器 —— 但别跳过这一步。 """ import sys, os, json, argparse, re CHECKS = """() => { const out = {overflow:null, oob:[], textOverlap:[], textOnMark:[], tiny:[], svgCount:0, dualAxis:[], numbers:{svg:[], body:[]}}; // 1) 页面横向溢出 const de = document.documentElement; out.overflow = {scrollW: de.scrollWidth, clientW: de.clientWidth, overflows: de.scrollWidth > de.clientWidth + 1}; const rectsOverlap = (a,b) => !(a.x+a.width <= b.x || b.x+b.width <= a.x || a.y+a.height <= b.y || b.y+b.height <= a.y); const area = r => Math.max(0,r.width)*Math.max(0,r.height); const inter = (a,b) => { const x = Math.max(a.x,b.x), y = Math.max(a.y,b.y); const w = Math.min(a.x+a.width, b.x+b.width) - x; const h = Math.min(a.y+a.height, b.y+b.height) - y; return (w>0&&h>0) ? w*h : 0; }; const svgs = [...document.querySelectorAll('svg')]; out.svgCount = svgs.length; svgs.forEach((svg, si) => { const vb = svg.viewBox.baseVal; const W = vb && vb.width ? vb.width : svg.getBBox().width; const H = vb && vb.height ? vb.height : svg.getBBox().height; const label = svg.getAttribute('aria-label') || svg.getAttribute('data-name') || ('svg#'+si); const pad = 2; // 允许描边等微小外扩 const texts = []; [...svg.querySelectorAll('text, tspan, rect, circle, polyline, polygon, line, path')].forEach(el => { let bb; try { bb = el.getBBox(); } catch(e) { return; } if (!bb || (!bb.width && !bb.height)) return; // 2) 越出 viewBox if (bb.x < -pad || bb.y < -pad || bb.x+bb.width > W+pad || bb.y+bb.height > H+pad) { out.oob.push({svg: label, tag: el.tagName, text: (el.textContent||'').trim().slice(0,28), box: [+bb.x.toFixed(1), +bb.y.toFixed(1), +bb.width.toFixed(1), +bb.height.toFixed(1)], viewBox: [W, H]}); } if (el.tagName === 'text') { const t = (el.textContent||'').trim(); if (t) texts.push({el, bb, t}); } }); // 3) 文字之间互相重叠 for (let i=0;i<texts.length;i++) for (let j=i+1;j<texts.length;j++) { const A=texts[i], B=texts[j]; if (!rectsOverlap(A.bb,B.bb)) continue; const ov = inter(A.bb,B.bb); const frac = ov / Math.min(area(A.bb), area(B.bb)); if (frac > 0.18) out.textOverlap.push({svg: label, a: A.t.slice(0,24), b: B.t.slice(0,24), overlapPct: +(frac*100).toFixed(0)}); } // 4) 文字压在图形标记上(柱/点/线),只报遮挡明显的 const marks = [...svg.querySelectorAll('rect, circle, polygon')].map(el => { let bb; try { bb = el.getBBox(); } catch(e) { return null; } if (!bb || area({x:0,y:0,width:bb.width,height:bb.height}) < 40) return null; const op = parseFloat(el.getAttribute('opacity') || getComputedStyle(el).opacity || '1'); const fill = (el.getAttribute('fill')||'').toLowerCase(); if (op < 0.25 || fill === 'none') return null; // 半透明底纹不算遮挡 return {el, bb}; }).filter(Boolean); texts.forEach(T => { // 累计所有图形对这行文字的遮挡:一行长标签横穿多根柱子时, // 单根柱子占比都不高,但合起来已经压得看不清了。 // 只算「画在文字之上」的图形——SVG 按文档顺序绘制,排在文字之后的才会盖住它。 // 白字写在色块上是正常设计,那种情况色块在前、文字在后,不算遮挡。 let covered = 0, tags = new Set(); marks.forEach(M => { if (M.el === T.el) return; const pos = T.el.compareDocumentPosition(M.el); const markIsAbove = !!(pos & Node.DOCUMENT_POSITION_FOLLOWING); if (!markIsAbove) return; const ov = inter(T.bb, M.bb); if (ov > 0) { covered += ov; tags.add(M.el.tagName); } }); const frac = covered / Math.max(1, area(T.bb)); if (frac > 0.35) out.textOnMark.push({svg: label, text: T.t.slice(0,28), mark: [...tags].join('/'), coverPct: +(frac*100).toFixed(0)}); }); // 5) 疑似双轴:左右两侧各有一组刻度文字 const leftTicks = texts.filter(t => t.bb.x < W*0.12 && /^[\\d,.\\-–%万k ]+$/.test(t.t)); const rightTicks = texts.filter(t => t.bb.x+t.bb.width > W*0.88 && /^[\\d,.\\-–%万k ]+$/.test(t.t)); if (leftTicks.length >= 3 && rightTicks.length >= 3) out.dualAxis.push({svg: label, left: leftTicks.length, right: rightTicks.length}); // 6) 渲染尺寸过小(图被压扁基本等于没有) const r = svg.getBoundingClientRect(); if (r.width < 200 || r.height < 60) out.tiny.push({svg: label, w: +r.width.toFixed(0), h: +r.height.toFixed(0)}); // 收集 SVG 内的数字,供与正文交叉核对 texts.forEach(t => { const m = t.t.replace(/,/g,'').match(/-?\\d+(?:\\.\\d+)?/g); if (m) m.forEach(x => out.numbers.svg.push(parseFloat(x))); }); }); // 正文数字(排除 svg 内的) const clone = document.body.cloneNode(true); [...clone.querySelectorAll('svg')].forEach(s => s.remove()); const bodyText = clone.textContent || ''; const bm = bodyText.replace(/,/g,'').match(/-?\\d+(?:\\.\\d+)?/g); if (bm) bm.forEach(x => out.numbers.body.push(parseFloat(x))); return out; }""" # 量之前先把内容全亮出来。两类结构性误报的根源都是「量了看不见的东西」: # ① 幻灯片用 display:none 藏非当前页,隐藏元素的包围盒必然 0×0, # 于是任何 deck 都 100% FAIL「渲染尺寸过小」(04 号压测把病因误诊成 CSS); # ② <details> 折叠的附录同理。 # 展开不改变任何几何——只是让本来要人翻到才看得见的内容变成可测量的。 EXPAND = """() => { document.querySelectorAll('details:not([open])').forEach(d => d.open = true); let n = 0; document.querySelectorAll('body *').forEach(e => { if (getComputedStyle(e).display === 'none' && e.querySelector('svg')) { e.style.setProperty('display', 'block', 'important'); n++; } }); return n; }""" def near_miss(svg_nums, body_nums, rel=0.008, min_abs=100): """图上数字与正文数字「接近但不相等」——多半是两处用了不同的取整口径。 阈值刻意收得很紧(0.8%):宁可漏报,也不要用一堆巧合淹掉真问题。""" body = sorted(set(b for b in body_nums if abs(b) >= min_abs)) hits = [] seen = set() for s in sorted(set(svg_nums)): if abs(s) < min_abs: continue if s in body: continue best = None for b in body: if b == s: continue d = abs(b - s) / max(abs(s), 1e-9) if d <= rel and (best is None or d < best[1]): best = (b, d) if best and (s, best[0]) not in seen: seen.add((s, best[0])) hits.append({'svg': s, 'body': best[0], 'diffPct': round(best[1] * 100, 2)}) return hits def main(): ap = argparse.ArgumentParser() ap.add_argument('html') ap.add_argument('--shots', metavar='前缀', help='额外保存分屏截图') ap.add_argument('--width', type=int, default=None, help='视口宽。默认:报告 1100,deck 自动切 1920') ap.add_argument('--deck', action='store_true', help='按幻灯片验:多页隐藏结构会被自动识别,此开关用于强制') ap.add_argument('--json', action='store_true') ap.add_argument('--allow-dual-axis', action='store_true', help='确实需要双轴且已在图上标注刻度为人为选定时使用') a = ap.parse_args() try: from playwright.sync_api import sync_playwright except ImportError: print('⚠ 未安装 playwright,无法自动验图。', file=sys.stderr) print(' 装:pip install playwright && playwright install chromium', file=sys.stderr) print(' 不装就手动在浏览器里逐屏看一遍——这一步不能跳过。', file=sys.stderr) sys.exit(2) path = os.path.abspath(a.html) if not os.path.exists(path): print(f'找不到文件:{path}', file=sys.stderr); sys.exit(1) errs = [] with sync_playwright() as p: b = p.chromium.launch() pg = b.new_page(viewport={'width': a.width or 1100, 'height': 1000}, device_scale_factor=2) pg.on('console', lambda m: errs.append(f'[{m.type}] {m.text}') if m.type == 'error' else None) pg.on('pageerror', lambda e: errs.append(f'[pageerror] {e}')) pg.goto('file://' + path) pg.wait_for_timeout(900) expanded = pg.evaluate(EXPAND) is_deck = a.deck or expanded >= 2 if is_deck and a.width is None: # deck 按投影尺寸设计,拿 1100 宽的报告视口量它, # 「页面横向溢出」这类读数全是视口错配的产物(06 号压测实锤) pg.set_viewport_size({'width': 1920, 'height': 1080}) pg.wait_for_timeout(300) R = pg.evaluate(CHECKS) H = pg.evaluate('document.documentElement.scrollHeight') if a.shots: slides = pg.query_selector_all('.slide') if is_deck else [] if slides: for i, s in enumerate(slides): # 逐页强制可见再截:纯文字页(口径/边界)没有 svg, # 不在 EXPAND 的展开范围里,不亮出来截不到 s.evaluate("el => el.style.setProperty('display','flex','important')") s.scroll_into_view_if_needed() pg.wait_for_timeout(120) s.screenshot(path=f'{a.shots}_{i}.png') else: y = 0; i = 0 while y < H and i < 24: pg.evaluate(f'window.scrollTo(0,{y})'); pg.wait_for_timeout(180) pg.screenshot(path=f'{a.shots}_{i}.png'); y += 950; i += 1 pg.screenshot(path=f'{a.shots}_整页.png', full_page=True) b.close() R['consoleErrors'] = errs R['nearMiss'] = near_miss(R['numbers']['svg'], R['numbers']['body']) R.pop('numbers', None) R['expanded'] = expanded R['isDeck'] = is_deck if a.json: print(json.dumps(R, ensure_ascii=False, indent=1)); sys.exit(1 if (R['oob'] or R['textOverlap'] or R['textOnMark'] or R['tiny'] or (R['overflow']['overflows'] and not is_deck) or errs) else 0) fails, warns = [], [] if R['overflow']['overflows']: msg = f"页面横向溢出:scrollWidth {R['overflow']['scrollW']} > 视口 {R['overflow']['clientW']}" if is_deck: warns.append(msg + "(deck 常为固定页宽设计,先确认设计宽度再下判断)") else: fails.append(msg) for o in R['oob']: fails.append(f"[{o['svg']}] <{o['tag']}> 画出 viewBox:box={o['box']} viewBox={o['viewBox']}" + (f" 内容「{o['text']}」" if o['text'] else '')) for o in R['textOverlap']: fails.append(f"[{o['svg']}] 标签重叠 {o['overlapPct']}%:「{o['a']}」×「{o['b']}」") for o in R['textOnMark']: fails.append(f"[{o['svg']}] 文字被 <{o['mark']}> 遮挡 {o['coverPct']}%:「{o['text']}」") for o in R['tiny']: fails.append(f"[{o['svg']}] 渲染尺寸过小 {o['w']}×{o['h']}px") for e in errs: fails.append(f"控制台错误:{e}") for o in R['dualAxis']: (warns if a.allow_dual_axis else fails).append( f"[{o['svg']}] 疑似双 Y 轴(左 {o['left']} 个刻度 / 右 {o['right']} 个)。" "双轴的视觉对比取决于你选的两个缩放比例,换个比例就换个结论——" "优先改成指数化(同起点=100)或上下两张共享 X 轴的小图。" "确有必要请加 --allow-dual-axis 并在图上注明刻度为人为选定。") for o in R['nearMiss']: warns.append(f"图上 {o['svg']} 与正文 {o['body']} 相差 {o['diffPct']}%——" "同一个量两处取整口径可能不一致,核一下") print('─' * 68) print(f'渲染自检:{os.path.basename(path)} 共 {R["svgCount"]} 张 SVG,页高 {H}px') if expanded: print(f'(已先展开 {expanded} 个隐藏容器再测量' + (',按 deck 模式验,视口 1920×1080' if is_deck else '') + ')') print('─' * 68) if fails: print(f'\n❌ FAIL {len(fails)} 项(必须修)') for f in fails: print(' -', f) if warns: print(f'\n⚠ WARN {len(warns)} 项(自己判断)') for w in warns: print(' -', w) if not fails and not warns: print('\n✅ 机器能查的都通过了。') print('\n机器只判「画错了没有」。这几件它判不了,你自己看一眼截图:') print(' · 每张图能不能独立回答标题里那句话') print(' · 有没有该画成图却写成了段落的地方') print(' · 首屏能不能在 10 秒内看懂核心结论') print('─' * 68) sys.exit(1 if fails else 0) if __name__ == '__main__': main()scripts/verify_xlsx.py54 KB06412a7dd015upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
references/about-author.md10 KBb471e8fda7a8upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
references/analysis-recipes.md11 KBe221f8bb28beupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
references/charts.md22 KB938ce102489dupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
references/dirty-data.md10 KB311a462fc8b4upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
references/excel-craft.md12 KB35a0e7b98d4fupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
references/insight-report.md7.9 KBb2e72ac3af5eupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
references/report-styles.md12 KB5564bafdeb50upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
references/workflow.md24 KBa84545a235e2upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
references/xlsx-craft.md20 KBae228522b046upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
.gitignore38 Beb55f36fa6d7upstream ↗
__pycache__/ *.pyc .last-update-checkcordis.patch.yml551 Bd0ed8c5e48bbupstream ↗
# DeepSeek Harness 插件入口:复用 DSH 自带的文件系统 skill 提供方, # 把本包所在的 node_modules 目录当作 skill 根目录,从而发现本包根部的 SKILL.md。 - insert: - id: huashu-excel-skill name: '@deepseek-ai/dsh-skill-filesystem' config: providerName: huashu-excel bundledSkillDir: !!js process.getBuiltinModule('node:path').dirname(process.getBuiltinModule('node:path').dirname(process.getBuiltinModule('node:module').createRequire(baseUrl).resolve('huashu-excel/package.json')))LICENSE1.0 KB8a8576ce865bupstream ↗
MIT License Copyright (c) 2026 huashu Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.package.json665 B7f9a52761ce5upstream ↗
{ "name": "huashu-excel", "version": "1.1.0", "description": "花叔数据分析大师:体检脏表、清洗、定口径、算指标、对账、出报告,让算出来的数字经得起追问。", "license": "MIT", "author": "花叔", "homepage": "https://github.com/alchaincyf/huashu-excel", "repository": { "type": "git", "url": "git+https://github.com/alchaincyf/huashu-excel.git" }, "keywords": [ "dsh-plugin", "deepseek-harness", "agent-skill" ], "files": [ "SKILL.md", "references", "scripts/*.py", "cordis.patch.yml" ], "dsh": { "bundle": { "patch": "./cordis.patch.yml" } } }test-prompts.json2.1 KB063b3cbcacbfupstream ↗
[ { "id": 1, "prompt": "给我看看我们二季度的 SLA 达成率——多少工单是在承诺时限内关闭的。另外我想知道积压情况怎么样。(数据:16 万行工单明细 CSV)", "expected": "必须发现承诺时限字段整列为空,并立刻说「这份数据算不出 SLA 达成率」,而不是用别的指标近似后当作回答。同时应说明未关单造成的幸存者偏差,以及月度建单量下降是右删失而非真实下降。", "probes": ["数据回答不了他的问题时立刻说", "已知边界必须存在", "时间序列先看断点"] }, { "id": 2, "prompt": "这份薪酬调查数据,帮我看看我们的薪酬是不是公平的。(数据:2.8 万份自填问卷,含性别与种族字段,薪资列混着 11 种货币)", "expected": "不得输出「存在/不存在歧视」这类价值判断,只给事实差值与不确定性区间;必须发现多币种不能直接求和、行业为自由填写会造成幽灵分组、自选样本不可外推总体。", "probes": ["机器判事实人判品味", "用户口径和数据打架时说出来", "分组统计前先看唯一值"] }, { "id": 3, "prompt": "把这两年的销售明细合起来,算一下营收同比。(数据:一个 xlsx 里两个工作表,按年份切分,边界有重叠)", "expected": "合表前必须检查两表的重叠区间,不能直接 concat 导致重复计数;必须声明营收是毛额还是净额(取消单占比不低);客户级分析要说明缺客户 ID 的那部分不能外推。", "probes": ["跨表关系", "说不清口径的数字不是结论", "看到 100%/0% 先怀疑分母"] }, { "id": 4, "prompt": "帮我把这份预算数据做成给委员会汇报的 PPT。", "expected": "分析和图表由本 skill 做,PPT 生成应转交 huashu-design(先探查是否安装,未安装则给出 GitHub 地址引导),并交接口径声明、论点结构、已验过的 SVG 三样,而不是自己硬做 deck。", "probes": ["职责边界", "交接契约"] } ]
Plain-text copy, no login: /skill-bundles/alchaincyf-huashu-excel.md