共享库跨技能统一迁移（zfl-sharedlib-unify）
把"统一共享库"从一句口号变成可复现、有门禁的工程动作。本技能不替你写具体接入代码，而是给出不翻车的标准流程与三道闸。
核心纪律（一句话）
> 统一 = 融合（换引擎），不是替换（删封装）；先真机回归对照，不达标不接主路径。
五步流程
① 实证摸清接口（读代码，不凭记忆）
- 读共享库的
SKILL.md+references/code-api.md+ 核心模块，钉死：对外暴露的入口（函数/CLI/模块路径）、能力边界、返回值结构（是文件路径还是字符串？ 这决定要不要适配层）。 - 读目标技能当前实现（grep
mineru|tesseract|paddleocr|pdfplumber|ocr_等），确认它真的在重复造轮子，还是只声明了依赖没接（#声明不等于接线，见 PF-454）。 - 输出：接口契约表（入参/出参/返回形态）。
② 钉死 import 范式（防相对导入坑）
- 共享库若是包结构（含
from .xxx import相对导入），必须注入父目录再from _lib.<mod> import，不能注入_lib目录后from <mod> import（必ImportError）。 - 详见 PF-519。落地前跑隔离 import 探针（
py_compile+ 真 import，不依赖任何后端）验证范式可跑。
import os, sys
_OH_PARENT = r"C:~/.workbuddy/skills/zfl-ocr-helper" # 父目录，不是 _lib 本身
if _OH_PARENT not in sys.path:
sys.path.insert(0, _OH_PARENT)
from _lib.core import process_pdf_auto, clean_ocr_text # 正确范式
③ 判薄封装还是删除（看 anti_bypass 约束）
- 先查目标技能有没有
references/*anti_bypass*.md或"强制调用某封装层/禁止 ad-hoc 绕过/三级置信度/防绕过自检"类硬约束。 - 有约束 → 薄封装：保留业务封装层（函数签名/返回形状/合规逻辑），仅把内部引擎调用换成共享库（新增
--engine xxx桥接分支，默认不切换）。详见 PF-520。 - 无约束 → 可替换：确认该层纯属转发、无合规资产，才删封装直接调共享库（agent 编排驱动的技能通常改 SKILL.md 指令层而非代码）。
④ 真机回归对照（不达标不接）
- 同一批真实样本跑 旧路径 vs 新路径，比对：提取成功率 / 关键字段命中率 / 字符级差异。
- 阻断合并条件：新路径任一项下降、或引入旧路径没有的新错误类型 → 不接主路径（旧引擎保持默认，新引擎仅对照分支）。详见 PF-521。
- 样本须覆盖五型：纯数字 PDF / 纯扫描件 / 混合 / 含曲线图 / 含表格。
- 回归 harness 须负样本自证（PF-516）：断言用正则复刻真实清洗逻辑，naive
replace漏残留空格会假绿。
⑤ 收口 + 沉淀
- 达标后翻默认开关，补 SKILL.md 说明 + CHANGELOG；未达标则保留对照分支、记录降级原因待修。
- 把本次发现的通用坑沉淀到
~/.workbuddy/lessons/pitfalls.md（先查重，能进既有编号不造新号）。
已验证的真实模板（worked example）
- 方案与纠偏：
..\_zfl_OCR统一迁移方案_20260920.md - 桥接层（零侵入、已 SMOKE_PASS）：
zfl-telecom-completion-audit/scripts/ocr_helper_bridge.py+ocr_helper_bridge_smoke.py - 回归 harness 模板：
..\_ocr_unify_regression.py（复用 zfl-skill-up-bridge 的"加载_lib→跑样本→比字段"骨架）
关联 PF
- PF-519 相对导入致
from core失效 →from _lib.core - PF-520 anti_bypass 技能须薄封装非删除
- PF-521 统一迁移须真机回归对照、不达标不接
- PF-454 / PF-517 声明不等于接线；PF-516 验证脚本须可验证；PF-449 声明≠接线
适用边界
本技能管"跨技能共享库统一迁移"这一工程动作。单技能内部回归用 zfl-skill-self-test；审计规则调优的对比回归用 zfl-contrastive-regression；技能→网页迁移退化自查用 zfl-skill-migration-audit。
约束与错误处理
- 本技能仅处理其声明范围内的任务，不越界执行未授权操作。
- 错误处理：输入不合法时返回明确错误说明，不静默跳过；依赖缺失时降级提示并给出替代路径。
不适用场景
- 不适用于需要实时交互或外部 API 调用的场景。
- 不适用于超出本技能声明范围的任务类型。
自检与成功标准
- 成功标准：输出满足任务声明的全部要求，关键信息完整无遗漏，视为完成。
- 输出前自检：核对输出是否覆盖全部要求项、数据是否准确、格式是否符合规范。
