<!-- AUTH_BOUNDARY -->

授权边界

本技能仅在自身定义范围内行动；任何超出本技能定义范围的操作（含发布、购买、安装依赖、修改账号、删除/破坏性操作）均须由你在独立、显式授权下另行发起。真实权限边界由工具层（工具白名单 / 权限模式 / 沙箱）强制；本条仅作默认行为定调与契约说明，不构成安全控制。

> 执行细节（0 个章节 / 4 个代码块）已外置，执行前照读：references/implementation-details.md（grep: 实现细节）

zfl-eval-external-tool

把"这工具对我有用没"从拍脑袋变成实证结论。与 zfl-absorb-article-insight（文献源是方法论文章→落地 SSOT）分工：本文献源是一个外部工具/库/技术组件，判定范式是"能力冗余 + 分布验证 + 实测"，不是"范式佐证"。

能力矩阵速查

3 分钟快速上手（Quick Start）

1. 抓全文：wechat-article-extractor（公众号）/ WebFetch（其余），落盘精读，记卖点 + 前提假设
2. 查冗余：python scripts/eval_external_tool.py grep-redundancy <kw1,kw2> --skills-dir ~/.workbuddy/skills → 命中后读真代码确认粒度
3. 验分布：python scripts/eval_external_tool.py probe-pdf <真实样本目录> → 实测占比 vs 文章前提
4. 分三档：init <工具名> 生成工作台 JSON 填 t0/t1/t2 → report <json> 出三栏报告（T2 自动进人工确认栏）
5. 决策 + 尾附"待用户拍板项"

> 脚本用法详见 FAQ Q10；常见卡点（抓全文失败/样本不足/pip 镜像/发布门禁）见 references/FAQ.md。

何时用

• 用户发来一个工具/库的文章链接或产品页（如 Rust CLI、OCR 引擎、PDF 解析器），问"这对我有帮助没/值得接入吗"。
• 评估某个外部组件是否值得吸收进 zfl-* 技能（替代现有模块 or 新增能力）。
• 不适用：文章是方法论/观点类（要落地 SSOT）→ 用 zfl-absorb-article-insight；文献源是已有技能包/zip → 用 zfl-skill-absorb-audit。

工作流（6 步，实证优先）

1. 抓全文 — 公众号用 wechat-article-extractor，其余用 WebFetch。落盘精读，不凭摘要/标题拍脑袋。记录作者自述的"卖点"和"前提假设"（如"54% PDF 不需 OCR"）。
2. 查能力冗余（读代码，不凭记忆） — 在自有技能目录 grep 该工具声称解决的能力是否已有实现。例：工具说"先分类再路由省 OCR"→ grep classify_pdf_pages / pdfplumber / extract_text 看自有管线是否已有同类。读真代码确认粒度（逐页 vs 整文档），而非凭"我记得有"。→ 脚本：grep-redundancy（自动检索+跳过噪声目录，命中≠成立，仍须读代码终判）
   - 补强（2026-09-18）：判"生态没有 X 能力 / 这是重复造轮子"时，除 grep 外再跑 ~/.workbuddy/skills/zfl-skill-factory/scripts/enumerate_skill_tree.py --covered "<关键词>"（覆盖度实证，含套件 references/ 与子技能）与 --gap-check <候选清单>（真缺口/弱覆盖/伪缺口）。@see zfl-common/references/anti-memory-checks.md（反「清单记忆」机械前置对照表 SSOT）。教训：凭清单记忆判缺口会出伪缺口（2026-09-18 判 6 处 → 4 处伪）。
3. 用真实样本验证文章前提 — 文章假设（如"X% 场景适用/省 Y 成本"）必须用自己的真实样本统计。写探针脚本（PyMuPDF/fitz 逐页判定），跑自有真实文件池，出实测占比。文章自夸未实测→不可采信。→ 脚本：probe-pdf（PDF 类逐页文本/扫描判定；非 PDF 类写等价探针）
4. 实测坐实（若有增量） — 用真实文件跑现有链路或新代码，出实锤表（每个文件判了什么、命中/缺失什么）。不谈理论。
5. 确定/不确定分三档（核心纪律，见下方"T0/T1/T2"）— 给用户的结论必须标"确定到什么程度"，绝不混一档喊 100%。→ 脚本：report（填 t0/t1/t2 → 生成三栏报告；T2 结构上强制进人工确认栏，铁律代码化）
6. 决策 —
   - 不吸收：能力冗余（自有更细）+ 分布错配（真实样本不满足文章前提）→ 零价值，仅作外部佐证。
   - 加增量：确有缺口 → 写代码 → 受管 venv 实测 → 回归测试（必须用受管 venv）→ 五源对齐 → five_source_check 门禁 → 发布。
   - 吸收：极少，外部工具完全替代自有模块的才考虑（须真机回归验证不降质）。

确定/不确定三档（T0/T1/T2）—— 给结论前必分

• T0｜代码行为级（绝对确定）：程序确实做了 X（看产物头部有闸块、回归测试在合成输入上 PASS、classifier 调了某函数）。只证明"代码做了该做的"，不证明结果对。
• T1｜机制/逻辑级（高确定，有前提）：pdfplumber 抽数字页=对文本层忠实（前提：该 PDF 文本层是真实文本）；闸能区分付款单/非付款单（前提：靠关键词命中）。前提没验证就是不确定的。
• T2｜真实保真/分布级（不确定，需真值或更大样本）：某 PDF 数字页"100% 保真"、"管线健康"、"文章零价值"、"文本型占比 10%"。这些没有真值对照或大样本，不能宣称 100%。

> 给用户写结论时用此模板：先列 T0（代码确实跑了什么），再列 T1（机制成立的前提），最后列 T2（哪些必须人工确认/需更大样本）。绝不允许把 T2 写进"确定"栏——这是 2026-08-31 实战里 AI 自己越界被用户揪出的坑。

铁律（防越界）：
- ⚠️ 抽文本层 ≠ 抽真值：数字 PDF 文本层可能本身是 OCR 层/乱码层，classifier 的"≥N 字符/页"阈值会把错字满屏的 OCR 层误判为数字页直提 → 错误当原文。与扫描页"无真值"同性质问题。详见 PF-259。
- ⚠️ 回归测试通过（合成输入）≠ 真实数据正确：合成样本逻辑正确，不证明真实文件还原对。
- ⚠️ 小样本分布前提确定性降级：若文章价值判定依赖"分布错配"腿且样本仅数文件，该腿从"确定"降级为"小样本推测"。

边界 / 坑（踩过才写进来）

• 跑类 ocr-helper 技能测试必须用受管 venv（$HOME/.workbuddy/binaries/python/envs/default/Scripts/python.exe，含 pdfplumber 0.11.x）——系统 python 缺 pdfplumber 会让数字页直提档静默降级（报 FAIL 是环境噪声非缺陷）。受管 venv 缺依赖时 pip 用国内镜像装：-i https://pypi.tuna.tsinghua.edu.cn/simple（详见 FAQ Q6）。
• 改技能后回归测试 import 姿势须对齐官方包导入约定（from _lib import core，非顶层 import core）——新增相对导入会暴露测试脚本的技术债。
• 写 CHANGELOG 金额/版本类示例规避 | X.Y | 独立表格单元——会被 five_source_check.py 版本号正则误判为"最新版本号"，污染 cl 源。写成 | 金额 | 或内联文本。
• 外部工具"未正式 release / 未实测 / 作者自述未运行"的断言不可采信——先实测再吸收。
• 不超出用户授权顺手补相邻修复——如选 A 修 extract_amount 仅当用户明确授权；否则标"待决策"留尾巴。
• 数字页按设计跳过强制校验（保真档）——产物无闸块是正确行为，非异常。
• 发布前门禁若报 mj(线上基线) 落后：本地领先非 over-bump 时属 PF-020 预期 FAIL，发布后由 publish_to_skillhub.py 回写 _skillhub_meta.json；只有 cl/fm/meta/vf 四源不一致才是真错误。

@see（单一真源，不要维护第三份副本）

• zfl-absorb-article-insight — 方法论/观点类文章（落地 SSOT），本技能只处理工具/库类，分工清晰别混用。
• zfl-skill-absorb-audit — 吸收已有技能包的对抗审计（文献源是 zip/技能，不是文章或工具）。
• zfl-skill-factory — 加增量后的升版本/发布门禁（align_versions.py + five_source_check.py + publish_to_skillhub.py）。
• PF-259 — 数字页文本层≠真值盲点（$HOME/.workbuddy/lessons/pitfalls.md），本技能 T2 档的核心依据。
• zfl-ocr-helper — 本技能首次实战案例：pdf-inspector 文章经实证判定零价值，反加字段级校验闸 v2.12.4 发布（详见今日工作日志 2026-08-31）。
• references/eval-checklist.md — 6 步工作流展开成可对照核查清单 + 结论三档写法模板。
• references/FAQ.md — 常见问题集中问答（技能选择/执行卡点/结论纪律/脚本用法/发布坑，含 pip 镜像配置）。
• scripts/eval_external_tool.py — 配套 CLI（init/grep-redundancy/probe-pdf/report/selftest），T2 禁入确定栏门禁代码化，改完跑 selftest 回归。
• zfl-common/scripts/grep_redundancy.py — 能力冗余检索公共标准件（单一真源）：本技能 grep-redundancy 子命令为薄壳调用（不维护第二份副本）；zfl-absorb-skill / zfl-skill-absorb-audit 亦复用同源。

约束与红线

• 不凭记忆判冗余：能力是否已有必须 grep 真代码确认（读粒度、看是否接兜底引擎），禁止"我记得有/应该已有"式假设。
• 不凭文章自夸判分布：文章声称的"X% 适用 / 省 Y 成本"必须自有真实样本实测，作者自述"未实测/未正式 release"的断言不可采信。
• T2 严禁入"确定"栏：凡无真值对照或无大样本的统计结论，只能进 T2（需人工确认），不得写进"确定（可放心用）"——这是 2026-08-31 实战里 AI 越界被用户揪出的坑。
• 错误处理：① 抓全文失败 → 换 WebFetch/wechat-article-extractor 重试，不臆造内容；② 真实样本不足 → 明确标"小样本推测"而非下确定论；③ 实测异常 → 闸块/降级静默跳过主流程、绝不阻断交付；④ 受管 venv 缺失 → 先修复环境再跑，不得用系统 python 顶替（会让数字页直提静默降级、报假 FAIL）。
• 超出用户授权不顺手补相邻修复：如修 extract_amount 仅当用户明确授权；否则留"待决策"尾巴。

端到端示例（pdf-inspector 实战浓缩，真实可运行）

> 用户问"这篇 Firecrawl pdf-inspector 文章对我有帮助没"。

① 抓全文
→ 记录卖点："先分类再路由省 54% OCR 成本"（作者自述未实测）。

② 查能力冗余（读代码）
→ 命中 core.classify_pdf_pages（逐页 pdfplumber 直取），粒度比 pdf-inspector 整文档分类更细且已接 MinerU/Tesseract 兜底 → 能力冗余腿成立。

③ 真实样本验证前提

逐页判定：单页≥20字符=数字页，否则=扫描页；跑自有真实 PDF 池出占比

→ 实测 30 页中数字页 3 页（10%），远低于文章 54% → 分布错配腿（小样本推测，T2）。

④ 实测坐实
→ 混合文档数字页直取 100% 保真 + 扫描页 MinerU 还原付款单表格全字段 → 产物头部注入 ⚠️ 字段级校验闸 块。

⑤ 三档结论（模板见 references/eval-checklist.md）：
- T0：闸门代码确实写块进产物、回归 14/14 PASS（代码行为确定）
- T1：数字页对文本层忠实（前提：文本层真实）；闸能区分付款单/非付款单（前提：关键词命中）
- T2：数字页"100% 保真真实内容"、文本型占比 10%、文章零价值判定——均须人工确认/更大样本

⑥ 决策：不吸收（能力冗余 + 分布错配）→ 反促 ocr-helper 加字段闸 v2.12.4 发布。

输出格式

给用户的结论必须是一个三栏表，结构固定：

尾附待用户拍板项（吸收 / 加增量 / 不吸收；强信号集等），不谈空理论。

成功标准

本技能执行到什么程度算"完成"（做到以下才算好）：

• 已抓全文（非摘要）并提炼文章前提假设；
• 已 grep 真代码确认能力冗余或证伪，未凭记忆；
• 若文章依赖分布前提，已用自有真实样本实测并出占比；
• 若有代码增量，已在受管 venv 实测 + 回归 PASS + 五源对齐 + five_source_check 通过；
• 给用户的结论已分 T0/T1/T2 三档，且 T2 未出现在"确定"栏；
• 输出含实锤表（每个真实文件判了什么），非纯理论叙述。

输出前自检清单（输出给用户前必过的 5 项）

• [ ] 是否凭记忆判了冗余？→ 须 grep 真代码佐证，不得"我记得有"
• [ ] "确定"栏里有没有 T2 项（无真值/小样本的结论）？→ 有则移出确定栏
• [ ] OCR/提取类实测是否用的受管 venv（非系统 python）？→ 否则数字页直提静默降级
• [ ] 若加了代码增量，是否跑回归 + 五源对齐 + five_source_check？→ 未过门禁不发布
• [ ] 三档结论是否用 report 子命令生成（T2 结构门禁）？→ 手写报告须自查 T2 未进确定栏
• [ ] CHANGELOG 金额/版本示例是否含 | X.Y | 独立表格单元？→ 有则会被 five_source_check 误判为版本号，改 | 金额 |