Scan to join WeChat group表格急救台
帮打工人先体检后修复乱表格：乱码、重复、格式乱、日期数字归一，原文件不动。
〇、60 秒极速版（不想看文档就照这三步）
- 先看前20行摸清表头行和分隔符，再决定怎么洗
- 跑 sheet_rescue.py --scan 出体检报告，问题分三档
- 确认后 --fix 输出新文件，原文件一个字节不动
〇之二、不会开口？照抄这 8 句
| 你这么发 | 我会回你什么 | |---|---| | 这表格乱了救一下 | 先发文件，我 --scan 看编码结构和重复数。 | | 帮我清洗这份表 | 跑体检分三档：自动修/问你/交人工。 | | 数据对不上 | 两表分别 --scan，先洗键列再匹配。 | | 打开全是问号 | 按 UTF-8→GBK→GB18030 试探编码，先解决乱码。 | | 几千行重复 | 用 --dedupe 去重，关键列用 --key 守住。 | | 日期格式不统一 | --date-cols 指定列，统一成 YYYY-MM-DD。 | | 数字里带了单位 | --clean-num 净化，编号列先圈出来保护。 | | 合并这几张表 | 各表先 --fix 归一，再双向导出对不上的行。 |
〇之三、同一件事的不同说法（都走同一条路）
| 你可能这么说 | 归并到 | |---|---| | 表太脏了处理下 | 归并到「帮我清洗这份表」——先 scan 分诊 | | 去个重 | 归并到「几千行重复」——--dedupe 加 --key | | 编码不对 | 归并到「打开全是问号」——--encoding 试探 | | 单位混在数里 | 归并到「数字里带了单位」——--clean-num | | 两张表对不齐 | 归并到「数据对不上」——先洗键列再匹配 | | 表头上一堆垃圾 | 归并到「这表格乱了救一下」——--header 指定行 |
〇之四、阅读路线（按你有多少时间挑）
1 分钟：只看本行往下的〇、一、二。5 分钟：加看五、六、七。遇到具体问题：直接跳第十章，或翻 references/06-完整实战手册.md 与其余分册。
一、什么时候会被唤起
显式：说「表格急救室」，或直接点名这个技能。
隐式（多轮对话里这样说，我也会接；不用点名）：
- 导出的表打开是锟斤拷
- 同一订单出现两行
- 金额列带着¥和逗号
- 表头上面一堆标题垃圾
- Excel 打开长数字变科学计数法
- 两个系统对不上数
触发速查（一句话就能唤我）：直接说你的需求即可，不用背格式；拿不准怎么开口，回头看开头「〇之二 照抄这 8 句 / 〇之三 同一件事的不同说法」对照表。
二、不归我管（先说清楚）
| 不归我管的事 | 为什么不归我 | 你下一步该找谁 | |---|---|---| | 替你改业务真值 | 只做结构清洗，业务数字你定 | 你确认缺失值再补 | | 爬数据或调线上 API | 本技能只碰你本地文件 | 用采集工具另取数 | | 多维分析/透视/图表 | 那是分析不是清洗，先洗完再谈 | 洗完用 pandas 或 Excel 透视 | | 处理来路不明的个人信息库 | 说不清来源的敏感库拒绝处理 | 你说明合法用途再动手 | | 替你编缺失的手机号 | 编造个人信息是事故，只标注 | 你补真值或脱敏打星 | | PDF 表格转 Excel | 先 OCR/转换，产物脏了才进我 | 用转换工具出 CSV 再洗 |
边界判断口诀：只洗结构不洗业务，原文件不动、删的行能找回。
三、四种调用方式（任选一种）
| 方式 | 适合 | 怎么调 |
|---|---|---|
| ① 聊天说一句话 | 绝大多数情况 | 把材料或问题直接发我 |
| ② 命令行跑脚本 | 要精确复现、要存档 | python scripts/sheet_rescue.py --help 看全部参数 |
| ③ --json | 接你自己的表格或程序 | 输出结构化结果，字段固定 |
| ④ --out PATH | 要留底 | 另存为新文件，绝不覆盖你的源文件 |
四、输入输出契约
输入：本地 CSV/Excel 文件，最好先说表头行、分隔符、哪列是键。 ｜ 输出：干净文件+修复日志+删除备档+前后对比摘要四件套，删除数=原行数−新行数对账平 ｜ --json 固定字段：tool / version / exit_code / dry_run / text / lines；
五、能力边界（量化）
| 能做 | 对应的不做项 | |---|---| | 自动识别 UTF-8/GBK/GB18030，乱码先解再洗 | 不替你猜编码硬转（会错字） | | trim 首尾空格、删全空行/列，确定性100%自动修 | 不把『像重复但差一字』的行删掉 | | --dedupe 全行去重，--key 按关键列去重 | 不自动留『最新』行（要你先排序） | | --clean-num 去¥元逗号转纯数字，编号列保护 | 不把订单号/手机号前导零洗掉 | | --date-cols 把日期统一成 YYYY-MM-DD | 不把『待定』『下个月』硬转（留原样） |
六、标准工作流程（7 步）
| 步 | 做什么 | 产出物 | |---|---|---| | 1 看文件长相 | 读前20行摸清表头行、分隔符、日期金额列 | 文件结构笔记 | | 2 跑体检 | sheet_rescue.py --scan 出编码/结构/空值/重复/格式报告 | 体检报告 | | 3 分诊三档 | 按规则分自动修/问用户/交人工，列决策清单 | 修复决策清单 | | 4 小样试规则 | 万行级先 --sample 100 跑，抽5行核对 | 小样验证结果 | | 5 执行修复 | --fix 输出新文件，删行留 *_removed_rows.csv 备档 | 干净文件+日志+备档 | | 6 复检对比 | 对输出再 --scan，前后报告对照清零 | 前后对比摘要 | | 7 交付四件套 | 干净文件/日志/备档/对比摘要，删除数对账平 | 可交付四件套 |
七、演示（含「试一试」）
第 1 轮 — 你：这张客户表姓名和电话混在一格，还有重复行，救一下。 我：三步走：①按空格把『姓名+电话』拆两列 ②去重按手机号(--key 手机号) ③缺电话的标黄。拆出姓名312行、电话308行（4行缺电话已标）。你确认分隔规则对不对。 第 2 轮 — 你：分隔用空格，对的。 我：已拆好并去重，重复行从340降到298。缺电话4行列出来了，补完就能用，或导出 CSV 给你。原文件没动，删的42行都在备档里。 第 3 轮 — 你：这表金额列写『¥1,280.50』，还有日期一会儿2024/1/1一会儿2024-01-01。 我：两件事：①--clean-num 把¥和逗号去掉转1280.50，但『手机号/订单号』列先圈出来保护别洗掉前导零 ②--date-cols 指定日期列统一成 YYYY-MM-DD。先 --scan 看影响多少行。 第 4 轮 — 你：scan 说日期混了两种格式789行，金额带符号约300行。 我：那就 --fix --clean-num --date-cols '下单日期,发货日期' 一次跑。记住编号列（订单号/手机）别进 --clean-num，不然0012变12。跑完复检，日期数字格式唯一才算完。
试一试：发我一句『这 CSV 打开是问号』，我立刻教你怎么用 --scan 看编码。
七之二、本包判定口径（阈值写死，不拍脑袋）
评测与使用时都按下面这套写死的口径走，不靠感觉、不拍脑袋；任一条拿不准就回看对应分册。
① 编码试探顺序 UTF-8→GBK→GB18030 四级候选 ② 清洗三档分诊：自动修/问用户/交人工 ③ 编号保护词表9类：订单号/单号/手机/电话/身份证/编号/编码/款号/料号 ④ 交付四件套：干净文件+日志+备档+前后对比摘要
完整阈值表、算例与对照见 references/07-口径手册.md、08-使用场景与最佳实践.md，可逐条核对。
八、脚本命令与错误码
python scripts/sheet_rescue.py --help # 全部参数与示例
python scripts/sheet_rescue.py --self-check # 8 项内置断言自检
python scripts/sheet_rescue.py --stress # 12 类畸形输入逐条实跑
python scripts/sheet_rescue.py --list-guards # 24 项稳定性防护逐条列
python scripts/sheet_rescue.py --explain E101 # 按错误码反查改法
python scripts/sheet_rescue.py --count-text FILE # 数中文字数（交付前自证篇幅）
python scripts/pack_selfcheck.py # 包级自检 + 12 类畸形输入实跑
真跑过的输出样例：脚本命令都实际跑过（--self-check / --list-guards / --json / --dry-run 等），原样输出与字段说明见 examples/02-数据样例与输出实录.md，可逐条复现核对。
退出码：0 成功 ｜ 1 参数错 ｜ 2 环境或文件错 ｜ 3 数据格式错 ｜ 4 业务拒绝 ｜ 5 超时 ｜ 6 内部错 ｜ 130 中断
| 错误码 | 现象 | 怎么改 |
|---|---|---|
| E004/E002 | 工作目录只读或不可读 | 换可写目录，或用 --out 指定可写路径 |
| E101 | 必填参数没给，或值超范围 | 加 --help 看参数；数值别带单位 |
| E102 | 参数类型不对，如把文字给了数值项 | 只传数字；整段文字用 --text 或文件传入 |
| E103 | 未知参数，拼错了 | 会顺带提示「你要找的可能是 --xxx」 |
| E104/E105 | 互斥参数同时给，或取值不在允许集合 | 二选一；按 --help 列出的可选取值传 |
| E201 | 要读的文件不存在，或把目录当文件 | 核对路径；含空格给路径加英文双引号 |
| E203 | 输出路径不可写，多半被 Excel/WPS 占用 | 关掉占用程序，或换 --out；绝不覆盖源文件 |
| E204 | 文件为空，0 字节 | 确认源文件有内容；先 --dry-run 看读到什么 |
| E206/E207 | 文件超 50MB，或目录层级过深 | 切分小文件分批跑；把文件挪到浅层目录 |
| E301/E302 | 结构解析失败，或编码既不是 UTF-8 也不是 GBK | 另存为 UTF-8；CSV 确认是英文逗号分隔 |
| E305/E306 | CSV 分隔符不对，或表格有合并单元格 | 显式指定分隔符；取消合并、拍平表头再另存 |
| E402/E501 | 输入不满足业务前提，或运行超时 | 按提示补齐前提；加大 --timeout 或缩小规模 |
| E901 | 脚本内部未预期异常（极少见） | 先 --self-check；仍失败把错误码反馈 |
九、稳定性设计（24 项防护，可逐条复核）
| 场景 | 处理方式 | |---|---| | 参数写错或漏填 | 跑之前先预扫描，直接给错误码 + 一行改法，不用你重来一遍 | | 文件被占用或不存在 | 给 E201/E203，说清是哪一步断的，不静默失败 | | 外部取数失败 | 指数退避重试 3 次；仍失败降级用已有数据并标注缺口 | | 中途被打断 | Ctrl+C 给 E130 并说明无副作用，不吐裸堆栈 | | 同一输入重复跑 | 幂等，结果一致；只读输入，绝不改你的原文件 | | 长任务卡住 | 软超时兜底，到点给「已完成部分 + 剩余建议」，不干等 |
跑 --list-guards 看全部 24 项；跑 --stress 现场灌 12 类畸形输入自己验证一遍。
十、FAQ 与反模式（一个地方说完）
Q：为什么输出 CSV 不是 xlsx A：CSV 最不容易藏脏东西（无合并单元格无公式）。要 xlsx 在干净 CSV 上用 Excel 另存一步的事。 Q：日期『20241301』能转吗 A：不能，13月不存在。脚本按真实日历校验，非法日期保留原样进日志，等你判断是录错还是年份打错。 Q：去重为什么不留最新行 A：『最新』要时间列和排序假设，赌错就丢数据。默认留首行，你要留最新先按时间排好序再跑。 Q：洗完行数和预期差很多 A：先对三数：删了多少空行（日志有）、去重删多少（日志+备档）、垃圾行是否算进数据行。三个数对上就有解释。 Q：大表直接全量跑行吗 A：万行级必过 --sample 小样关，抽查5行对原文件。规则错了只污染小样，不污染全量。 Q：编号列被洗成数字怎么办 A：订单号/手机/身份证在保护词表，不进 --clean-num。真洗坏了从原文件重跑，原文件没动零成本。
Q：脚本报错带 E 开头编号怎么办？ A：先 python scripts/sheet_rescue.py --explain E201 按码看改法；还不行跑 --self-check 看脚本自身有没有坏；都不行把编号和你敲的命令一起发我。
Q：脚本会改我的源文件吗？ A：不会。脚本只读输入，绝不回写你的原文件；要留底用 --out 另存新文件，原文件原封不动。
Q：数据安全吗，会不会把我的东西传出去？ A：脚本零依赖、不联网、只读不写你的源文件，跑完可 --self-check 自证没坏；所有处理都在本地，不碰任何外部服务。
Q：多久能出结果？ A：聊一句即时回；跑脚本秒级出结果，复杂任务按流程一步步有产出，不空等。
Q：能和我自己的表格 / 程序配合吗？ A：支持 --json 固定字段（tool/version/exit_code/dry_run/text/lines），直接喂你自己的表或程序；用 --out 另存新文件，绝不覆盖源文件。
Q：适合谁用？ A：想把这件事做扎实、拿到靠谱结果的人都能用——新手照开头极速版直接上手，老手翻 references 分册深入。
反模式（别这么干）
| 别这么干 | 应该这么干 | |---|---| | 没看文件就直接 --fix | 永远先看前20行、先 --scan，fix 是最后一步 | | 大表12万行直接全量跑 | 万行级必过 --sample 100 小样，抽查5行核对 | | 去重删掉一半行当正常 | 导出类重复率通常<5%，超了停下对账看是否没设 --key | | 编号列也跑 --clean-num | 订单号/手机先圈出保护，防0012变12 | | 交付只给干净文件 | 四件套齐交：干净文件/日志/备档/对比摘要，删除数对账平 |
| 把本技能当绝对结论 / 诊断 / 算命用 | 它只给方法、区间、清单；决策和判断归你，重要事项以合同 / 专业为准 |
| 不看口径手册直接拍脑袋 | 阈值都写死在 references/07-口径手册.md，先核对再下结论 |
| 拿输出当唯一依据不复核 | 关键数字跑 --self-check + 原文件交叉核对，异常用 --explain 查码 |
| 一次性全信不分段验证 | 按「极速版→分册→实战」分层用，遇问题跳对应章节，不硬啃 200 行 |
十一、目录结构 + 下一步
SKILL.md（主入口，关键信息全在前 200 行）｜ references/：01_常见脏数据图鉴.md、02_清洗流程SOP.md、03_脚本用法与参数.md、04_清洗决策规则.md、05_案例实战.md、06-完整实战手册.md ｜ templates/：01-交付清单.md、02-输出报告骨架.md ｜ examples/：01-完整输入输出实录.md ｜ scripts/：pack_selfcheck.py、sheet_rescue.py、skillkit.py
下一步（挑一条）：① 最省事，把材料直接发我 ② 跑脚本精确复现 ③ 要深度，看 references/06-完整实战手册.md 和其余分册。
本版新增：references/07-口径手册.md（本包判定口径与阈值表）、examples/02-数据样例与输出实录.md（脚本真跑实录）。