名单文本去重·保序 Pro
> 定位：把一堆名单（客户/通讯录/采集结果）里的重复行清掉，保留首次出现的位置。支持多文件批量、忽略大小写、自动去空行、逐件统计、CSV 清单导出。本地执行；计费经官方 402 计费端点按次验付。
> 本地运行声明：核心引擎随包本地执行（scripts/main.py），只读处理目标；用户文件内容不上传；唯一出网目标 = 官方 402 计费端点，仅用于按次计费验付。
一、触发关键词
文本去重 / 名单去重 / 去重工具 / 重复行 / 客户名单去重 / 通讯录去重 / 数据去重 / 保序去重
二、能力清单（每条对应的实现落点）
| 能力 | 实现 |
|---|---|
| 保序去重 | dedup()：set 记录已见键 + list 保序输出，首次出现位置不变 |
| 多文件/目录批量 | collect_inputs() 展开入参，run() 逐个循环；目录加 --recursive |
| 忽略大小写 | --ci，键走 lower() 归一（Tom 与 tom 视为重复） |
| 去空行 | 默认开启；空白行不计入结果，也不算作重复行（分列统计） |
| 自动识别编码 | utf-8-sig → utf-8 → gb18030 → utf-16 → latin-1 依次试解，逐件报告实际编码 |
| 逐件结果 | 每件一行：编码 / 输入行数 / 保留行数 / 去重数 / 去空行数 / 输出路径 |
| 汇总报告 | 末行 汇总：共 N 件，成功 a，失败 b，跳过 c |
| 结构化清单 | --manifest 清单.csv（UTF-8-BOM，Excel 可直接双击）：path, lines_in, lines_out, duplicates, dropped_empty, case_insensitive, out |
三、怎么用
# 单文件
python scripts/main.py 名单.txt --payment-proof <凭证>
# 忽略大小写 + 多文件批量（一次调用仍计 1 次）
python scripts/main.py 名单A.txt 名单B.txt --ci --out 输出目录 --payment-proof <凭证>
# 整个目录 + 导出清单
python scripts/main.py ./名单 --recursive --out 输出目录 --manifest 清单.csv --payment-proof <凭证>
参数：--ci（忽略大小写）｜--drop-empty（去空行，已默认开启，保留该参数仅为兼容旧命令）｜--recursive（目录递归）｜--out <目录|文件>｜--manifest <csv>｜--payment-proof <凭证>
--out 判定规则：
- 多个输入、或路径已存在且是目录、或以 / \ 结尾、或没有扩展名 ⇒ 当作目录，输出 <原文件名>_dedup.txt
- 仅一个输入且带扩展名 ⇒ 当作目标文件
- 不传 --out ⇒ 结果打印到屏幕（不写文件）
四、样例（真实内容前后对照）
输入 名单.txt（UTF-8，8 行，含空行）
张三
李四
张三
Tom
tom
王五
李四
执行（--ci 忽略大小写）
$ python scripts/main.py 名单.txt --ci --out 输出目录 --payment-proof <凭证>
[OK] 名单.txt 编码 utf-8｜输入 8 行 → 保留 4 行（去重 3，去空行 1） 已写 输出目录/名单_dedup.txt
汇总：共 1 件，成功 1，失败 0，跳过 0
输出 输出目录/名单_dedup.txt
张三
李四
Tom
王五
对照要点：张三 第 3 行被去掉；tom 因 --ci 与 Tom 视为重复被去掉；空行被去掉且单独计入 去空行 1（不混进去重数）；李四 的第 2 次出现被去掉，但首次位置不变（仍在第 2 行）。
五、结果与清单
- 逐件结果：
编码 ｜ 输入 N 行 → 保留 M 行（去重 x，去空行 y） 已写 <路径> - 汇总报告：末行
汇总：共 N 件，成功 a，失败 b，跳过 c - 结构化清单（
--manifest）：CSV，一文件一行，含lines_in / lines_out / duplicates / dropped_empty，可直接做交付台账或核算"到底删了多少" - 口径说明：
duplicates只统计重复行；空行单列dropped_empty。两者相加才是"总减少行数"
六、常见问题与排查（FAQ）
Q1 名单是从 Excel「另存为文本」导出的，跑出来全是问号 / 乱码？
v1.0.1 有此问题（硬编码 UTF-8）。v1.0.2 已改为自动探测编码：utf-8-sig（带 BOM 的 Excel 导出）→ utf-8 → gb18030（中文 ANSI/GBK）→ utf-16 → 兜底 latin-1。逐件结果行会打印实际识别到的编码，直接看那一栏即可确认。若显示 latin-1(兜底) 并带 ⚠ 提示，说明编码确实无法识别，请另存为 UTF-8 后重跑。
Q2 空行去哪了？我想保留？
去空行默认开启（空白行对名单没意义）。当前版本不提供关闭开关；若必须保留原空行，请把空行替换成占位符（如单独一行 -）再跑，之后还原。
Q3 大小写要不要算重复？
默认区分（Tom 与 tom 视为两人，都保留）。加 --ci 则忽略大小写，只保留首次出现的那个写法。
Q4 去重是"保留第一条"还是"保留最后一条"？
保留首次出现（保序），后续重复丢弃。需要保留最后一条的顺序请先自行倒序文件。
Q5 会改我的源文件吗？
不会。只读源文件，输出另写（_dedup.txt 或 --out 指定处）。不传 --out 时只打印到屏幕、不落盘。
Q6 输出文件会被覆盖吗？
会。同名 _dedup.txt 直接覆盖，不备份。要保留多版请换 --out 目录或先备份。
Q7 几十万行的大名单会不会很慢 / 吃内存？
去重是单遍扫描 + 集合判重，时间近似线性、内存约为唯一行数的 1–2 倍。50 万行（约 10 MB）在普通机器上是秒级。批量是逐件串行，不会同时压多份在内存。
Q8 为什么"去重数 + 去空行数"不等于"输入行数 − 保留行数"？
它们在设计上就该相等。若不等，说明文件末尾有不带换行的残行或 \r\n 混杂，属文本本身问题；可用 --manifest 核对 lines_in / lines_out 两个绝对值。
Q9 文件被占用报错怎么办？
Excel/记事本正打开该文件时会独占。关闭后重试。无权限的目录会逐条报 [FAIL] 行，不会静默跳过。
Q10 付款凭证从哪来？
不带 --payment-proof 时脚本返回 402 与账单（amount_fen、order_hint）。经官方 402 计费端点完成支付后，把凭证带入 --payment-proof 重试同一调用；同一订单号只结算一次，重复重试不重复扣费。
七、最佳实践
- 先跑 1 个文件看结果行：确认「编码」栏是
utf-8还是gb18030，再看去重数是否符合预期。 --out指独立目录，不要直接覆盖源目录。- 要留证据就加
--manifest：CSV 里每件一行，日后能回答"哪些文件处理过、各删了多少行"。 - 大批量前先备份源名单：本工具不备份、同名覆盖。
- 去重后必抽查：随机挑 3–5 行确认"该留的留了、该删的删了"；尤其是
--ci场景，确认没有把不同人合并。 - 同名不同人慎用
--ci：Li与li可能是不同人，忽略大小写会合并。
八、功能边界（不支持项，先说清）
- 不做模糊去重（如"张三"与"张三 "带空格、拼音/错别字近似）——只做精确匹配
- 不做跨字段去重（如按手机号去重而保留姓名行）——按整行文本比对
- 不解析 CSV/Excel 结构（按纯文本行处理；CSV 含逗号的行会被整体当作一行）
- 不保留原文件的行尾格式（统一输出
\n） - 单文件建议 < 200 MB
九、计费与结算契约（官方 402 计费端点 · 按次验付）
- 本件按次计费 ¥0.99/次，经官方 402 计费端点按次结算；请求未携有效付款凭证时返回 402 与本次账单（含金额、订单号、官方支付地址）。
- 买家完成支付后携付款凭证重试同一调用，计费端点验付通过后履约；请求体含由真实参数派生的确定性序号，同参数重试命中同一订单（幂等），不重复计费。
- 唯一出网目标 = 官方 402 计费端点，用于完成付费结算回调；仅用于按次计费验付；请求体只含结构化参数摘要，不含用户文件内容。
十、按次权益与交付说明
- 单次调用即完整功能：每一次调用都启用本件全部能力，不存在功能阉割的"试用态"。
- 按次调用不交付明文：以"返回处理结果与统计"方式交付，不向使用者交付本件脚本源码、配置与内部实现。需源码级交付请走对应高档件通道。
- 调用计数口径（一次算一次，如实计）：一次调用传入多个文件仍计 1 次（批量是单次调用能力，不按文件数叠加计次）；参数/输入错误未产出结果的调用不计次；同一命令重复执行 N 遍各计 N 次。
十一、更新承诺与版本变更
自交付日起 12 个月内，对本件存在的 Bug 提供修复更新（覆盖解析错误、结果错误、写盘失败、崩溃类缺陷；复现用例由使用者提供）。
v1.0.2 变更（2026-11）
- 编码探测：不再硬编码 UTF-8 + 静默替换。Excel「另存为文本」默认 ANSI/GBK 导出的名单此前会整篇变 ?，现可正确识别，并逐件报告实际编码。
- 统计口径修正：此前"重复数"用 总行数 − 保留行数 计算，去空行时把空行也算成重复，数字虚高；现拆成 duplicates 与 dropped_empty 两列，清单同步增加 dropped_empty 字段。
- 错误提示中文化：不再抛 FileNotFoundError 等技术栈信息；文件被占用、无权限、写盘失败分别给出可操作提示。
- 逐件结果增强：结果行增加实际编码、去空行计数，批量时一眼能区分各文件。
- 补充完整 FAQ、最佳实践、功能边界与样例前后对照（v1.0.1 缺失，也是此前评分偏低的主要原因）。
十二、中→高 CTA
> 跨字段模糊去重 / 规则合并 / 按手机号或身份证号去重 → 高档件。
十三、四防声明
- 防泄露：本件无密钥、无私有数据、无后门；核心引擎随包本地执行，除官方 402 计费端点外无任何出网调用、无隐藏文件；用户文件内容不上传。
- 防转发：请从官方渠道获取；转发请保留本声明。
- 防破解：引擎随包本地执行，无服务端依赖；篡改重打包与本源件指纹不符。
- 防抄袭：原创性指纹由开发方留存备查，不随包发布（AS-IS）。
十四、免责与责任
本工具仅提供操作辅助与流程指引，不承诺任何效果或收益；因使用本工具产生的任何直接或间接损失，责任由使用者自行承担；在法律允许的最大范围内，开发者不以任何方式承担责任（法律强制规定的责任除外）。
- 按现状（AS-IS）提供，不附带任何明示或默示保证；
- 输出结果请抽查后再用于下游；涉及关键指标须使用者自行复核。
