scan2pan-yk · 扫描件端到端上云管线
> 一句话：把一份原始图像/扫描 PDF，变成「档案级可用」的增强件，三件套（原图+产物+result.json）落百度网盘，且远程字节校验通过才算完成。
>
> 方法来源：经 95 份真实材料验证的归档工作流（约 64 条实测坑位），已剥离全部档案数据。
0. 环境自检（硬性首步，缺任一即报缺并停止，禁止半跑）
| 依赖 | 检查方式 | 缺失处置 |
|---|---|---|
| Python3 + Pillow/numpy | python3 -c "import PIL, numpy" |
提示用户 venv 安装；PEP 668 环境禁止系统级 pip |
| Node.js（MCP 调用器） | node --version |
提示安装 |
| 夸克 API Key | 环境变量 QUARK_AI_API_KEY 或同目录 config.json |
引导用户申请，切勿代填 |
| bypy 授权态 | python3 -m bypy list 返回 0 |
引导用户浏览器授权，token 存 ~/.bypy/ |
任一不通 → 只报缺什么、怎么配，不调用任何计费接口。
1. 接口契约
// 输入
{
"input": "图.jpg | 扫描.pdf | 目录/",
"purpose": "证件卡 | 文档 | 票据 | 图片", // 缺省 auto
"outdir": "./_out", // 须先创建
"upload": true, // 是否上云三件套
"desc": "内容概况" // 前缀用，10字内
}
一键入口：
python3 scripts/run_pipeline.py --input "图.jpg" --outdir "./_out" \
--purpose 文档 --desc "检测报告单"
python3 scripts/run_pipeline.py --input "图.jpg" --outdir "./_out" --cloud no # 0计费预检
分步入口（调参/排障时）：probe.py 体检 → prepare.py 预处理 → call_mcp.js 夸克调用 → verify.py 核验 → pan_backup.py 上云校验。
输出（outdir 内）：enhanced/ 增强件、result.json 总报告（含计费快照）、run.log。
2. 管线纪律（按序执行）
① 源件体检（免费，probe.py）
- 判件体（扫描件/拍摄件/文档类）、估 DPI、量四缘留白、核纸幅比例、读 EXIF、算锐度。
- EXIF Orientation 不可信：一律剥除，按存储像素判断方向。
- 载荷安全线 1.4MB：超限先压缩（长边 ≤800px、JPEG q85）再上云。
② 预处理（免费，prepare.py）
- 可选旋正 → 剥 EXIF → 压缩 → 生成
@args.json（base64）。 - 大 base64 必须走 @args.json 文件传参：命令行上限约 32KB，直接传必截断。
- 含防伪底纹/网纹的文档不转 JPEG（破坏细密网纹）：用
--keep-format。
③ 夸克增强（唯一计费环节，call_mcp.js）
- 工具选择（详见 docs/工具选择表.md）：
- 文字类文档 →
scan_image_to_pdf（矢量重建路线） - 证件卡类（含人像/国徽）→
scan_certificate_invoice_enhance - MCP Streamable HTTP 三步握手（initialize → initialized → tools/call）。
- 返回图像与原始响应 JSON 双落盘（成本纪律：结果可复用，永不重调）。
- 每次调用的响应必须落盘复用；网关 504 → 换路重试，不盲发。
- 返回碎片/人像丢失 = 用错工具 → 换
scan_certificate_invoice_enhance重调（多一次计费，记入报告）。 - 多页批件 → 按页序命名 P1/P2/P3。
④ 分档核验（免费，verify.py 单一代码源，禁止复刻口径）
- 对比增强前后：几何变化率 + 锐度比。
- A（几何 ≤2.0%）通过 ｜ B（2.0%~5.0%）可接受须标注交付 ｜ C（>5.0%）需人工确认。
- C 档先判成因：拍摄件纸张天然倾斜/褶皱 → 几何超警戒属正常，如实交付不重跑（防重复计费）；真处理异常才回炉。
- 几何超限绝不拉伸修正——增强工具几何变化逐件不同，拉伸会毁掉比例证据。
- 校验位/字段对不上 → 先用免费
scan_general_ocr+ 放大目视做三方独立读数，再考虑证件本身瑕疵。
⑤ 三件套上云（免费，pan_backup.py）
- 三件套：原图 + 产物（enhanced/ 最终件）+ result.json。
- 命名前缀：
{YYYYMMDD-HHMM}-{10字概况}，时间取 result.json 的 run_at；--prefix可覆盖（补传场景）。 - 只走网盘
我的应用数据/bypy/（apps/bypy/）。 - 未上云件（上游决定不调夸克）产物位=源件副本，照传三件套并在汇报注明。
⑥ 远程字节校验（免费，pan_backup.py 内置）
> 核心教训：「上传完成 ≠ 文件在」——本条来自真实丢库事故。
- 上传后必须 bypy list 远端，比对文件名 + 字节数。
- 不一致 → 自动重传一次 → 复验；仍不一致 → 告警退出（退出码 1），静默成功不算成功。
3. 敏感件与隐私红线
- 敏感件提示：身份证、护照、病历、银行凭证等，上云即等于交给第三方云服务（夸克/百度网盘）。调用方未明确授权时，选本地路径或先确认。
- 不落持久副本：处理完即交回结果，不在工作区保留输入图像长期副本。
- 不臆测：所有输出字段必须来自实测（像素、字节、md5、算术）；判断不了的写「需人工确认」。
- 源件一律只读，不替换不删除。
4. 失败与回退（速查）
| 现象 | 原因 | 处置 |
|---|---|---|
| HTTP 413 | 载荷超限 | 回 ① 压缩到长边 ≤800px、JPEG q85 |
| 增强后内容躺倒 | EXIF 误用/源件未摆正 | 按存储像素重新摆正后重调 |
| 几何变化率 >5% | 拍摄角度残余/纸张非标 | 如实写入报告，绝不拉伸 |
| bypy 401/失效 | token 过期 | 重新浏览器授权 |
| 远端校验失败 | 网盘侧丢失/同步延迟 | 重传→复验→人工查回收站 |
更多坑位见 docs/坑位摘要.md；工具选择细则见 docs/工具选择表.md。
5. 计费透明表
| 环节 | 计费 |
|---|---|
| 体检 / 预处理 / 核验 / 上云 / 远程校验 | 本地免费 |
| 夸克 MCP 增强（每图每次） | 按次计费，调用前向调用方说明 |
scan_general_ocr 免费读数 |
实测响应无计费字段，仍建议定期核账 |
6. 本技能不做什么
- 不做档案分类、命名规范、索引台账——那是下游归档的职责，本管线止步于「可用件 + 云端可校验副本」。
- 不判断文书法律效力，不做关系推断。
- 不同时发多次计费调用：同一图存在已落盘响应时禁止重调。
