时间戳批量转换 · 秒/毫秒与时区 Pro
> 定位：批量把 Unix 时间戳转成可读日期，或把日期转成时间戳；自动识别秒/毫秒，可指定时区偏移。本地执行、零出网。触发：时间戳转换、unix时间戳、时间戳转日期、日期转时间戳。
> 本地运行声明：核心引擎随包本地执行（scripts/main.py），只读处理目标、不修改源文件；用户文件内容不上传；唯一出网目标 = 官方 402 计费端点，仅用于按次计费验付。计费经官方 402 通道按次结算。
一、触发关键词
时间戳转换 / unix时间戳 / 时区转换 / 日期转换
二、能力清单
时间戳→日期（自动判 10 位秒/13 位毫秒）；日期→时间戳（秒与毫秒同时给）；支持 --p tz_offset 指定时区（默认东八）；批量最多 5000 个值
三、怎么用
python scripts/main.py 时间戳.txt --p mode=to_datetime --p tz_offset=8 --payment-proof <凭证>
python scripts/main.py 日期.txt --p mode=to_timestamp --payment-proof <凭证>
参数：--p key=value（业务参数，可多次）｜--out <csv>｜--manifest <csv>｜--recursive｜--payment-proof <凭证>
四、样例（输入 → 输出）
$ python scripts/main.py ts.txt --p mode=to_datetime
[OK] ts.txt mode=to_datetime ok=2
汇总：共 1 件，成功 1，失败 0，跳过 0
五、结果与统计
- 逐件一行结果 + 末行汇总
共 N 件，成功 a，失败 b，跳过 c --manifest可导出 CSV 台账；不指定则不写任何文件- 退出码：全部成功 0；有失败 1；用法错 2；未携付款凭证 3
六、常见问题与排查（FAQ）
Q1 怎么区分秒和毫秒？
按位数自动判：≥13 位当毫秒，否则当秒。个别 11-12 位的异常值会被当秒，结果里会标注 unit。
Q2 时区怎么设？
--p tz_offset=8 表示东八区（默认）；西五区用 -5。范围 -12..14。
Q3 日期格式支持哪些？
支持 YYYY-MM-DD HH:MM:SS、YYYY-MM-DD HH:MM、YYYY-MM-DD 及斜杠变体。其他格式请先规范化。
Q4 转换失败的行会怎样？
逐条标记 ok=false + 原因，不影响其他行；汇总给出成功数。
Q5 能处理 1970 年以前的负数时间戳吗？
可以，负数按秒解释，超出可表示范围会报错。
Q6 一次能转多少？
单次最多 5000 个值，超过请分批。
七、最佳实践
- 先小样再全量：拿 1 个文件跑通、看结果结构，再整批。
--manifest留台账：批量场景存一份 CSV，日后可回溯处理过哪些件。- 看汇总行：失败/跳过不为 0 就翻上面的明细，别只看成功数。
- 源文件安全：本件不修改源文件；输出另写。
- 参数写错会怎样：
--p的键值写错会直接报中文错误并跳过该件，不会产出半成品。
八、功能边界（不支持项）
不做 cron 表达式解析；不做时区数据库查询（只按固定偏移）；不解析自然语言日期（如“下周三”）
九、计费与结算契约（官方 402 计费通道 · 按次结算）
- 本件按次计费 ¥0.99/次，经官方 402 计费通道按次结算；请求未携有效付款凭证时返回 402 与本次账单（含金额、订单号、官方支付地址）。
- 买家完成支付后携付款凭证重试同一调用，计费端点验付通过后履约；请求体含由真实参数派生的确定性序号，同参数重试命中同一订单（幂等），不重复计费。
- 唯一出网目标 = 官方 402 计费端点；仅用于按次计费验付；请求体只含结构化参数摘要，不含用户文件内容。
十、按次权益与交付说明
- 单次调用即完整功能：不存在功能阉割的"试用态"。
- 按次调用不交付明文：不交付脚本源码与内部实现；需源码级交付请走高档件通道。
- 调用计数口径：一次调用传入多个文件仍计 1 次；参数错误未产出结果不计次；重复执行 N 遍各计 N 次。
十一、更新承诺与版本变更
自交付日起 12 个月内修复 Bug（复现用例由使用者提供）。
v1.0.0 首发：功能如上；本地执行、零出网、只读不改源文件。
十二、中→高 CTA
> 需要跨字段处理、结构化解析或带联网校验的场景 → 高档件。
十三、四防声明
- 防泄露：无密钥、无私有数据、无后门；引擎随包本地执行，包内无支付调用脚本，除唯一出网目标外无任何出网调用。
- 防转发：请从官方渠道获取；转发请保留本声明。
- 防破解：无服务端依赖；篡改重打包与本源件指纹不符。
- 防抄袭：原创性指纹由开发方留存备查，不随包发布（AS-IS）。
十四、免责与责任
本工具仅提供操作辅助与流程指引，不承诺任何效果或收益；因使用本工具产生的任何直接或间接损失，责任由使用者自行承担；在法律允许的最大范围内，开发者不以任何方式承担责任（法律强制规定的责任除外）。按现状（AS-IS）提供，输出结果请抽查后再用于下游。
