夜雨聆风
从前期咨询实践中提炼出来的通用方法。
一、缘起与初心
做政府投资项目前期咨询，绕不开各类指引文件——编制规范、技术标准、指标手册，动辄几百页，密密麻麻的表格和规则。
每次遇到这类文件，最自然的想法是：直接让AI帮我查、帮我算。
但实际跑下来问题明显：上下文塞不下、AI会"记错"数字、结果不可追溯。本质矛盾在于——AI需要实时调用精确数据，但专业文档是静态的、碎片的、不结构化的。
换个思路：不是让AI读文件，而是把文件变成AI能反复调用的"技能"。
于是有了"广州-房建估算-2025"这个Skill——把298页政府投资估算指引，变成一套可调用、过程透明、数据可溯源的AI技能。做完之后意识到：这套方法本身可以通用。 任何行业、任何专业PDF，都可以用同样的流程转化。
这就是开源“PDF文档转Skill技能”的来历。
二、实践提炼与打磨
整个过程经历了三轮迭代：
第一轮：能用就行。 提取PDF文字，塞进Markdown文件，写简单调用流程。问题：表格数字被截断，格式混乱，路径写死。核心教训：只管提取，没管质量。
第二轮：数据准确性验证。 加了Python验证脚本，对照PDF原文反查资源文件里的数字。这一轮发现了几处真实的数据提取错误，有一处指标差了近一倍。从此"L1修正项双向验证"成为强制流程。
第三轮：从能用到好用。 数据准确了，但Skill设计本身有问题：适用场景模糊，校验规则缺闭环，还要反复校核。于是引入6维度质量评估（适用性、可操作性、校验完整性、准确性、复用性、一致性），加权平均≥4.0才算合格。
最终定型为v3.1.0，经历7个阶段、3次大版本迭代、59项测试验证。
三、技能主要内容：7阶段工作流
核心是一套标准流程，覆盖从收到PDF到生成可分发包的全过程：
阶段1 → 文档分析 理解结构，设计资源架构，用户确认后再动手阶段2 → 资源文件创建 双工具提取，分层编写结构化Markdown资源文件阶段3 → SKILL.md编写 定义工作流、校验规则、输出格式阶段4 → 质量验证 数据准确性验证 + 8维度功能测试阶段5 → 使用说明与案例 典型案例 + FAQ + 溯源说明阶段6 → 打包前检查复核 完整性+准确性+质量评估，问题修复后才打包阶段7 → 打包分发 生成SkillHub可上传的zip分发包几个核心设计原则：
① 数据硬编码，AI只调用。 所有指标写进资源文件，AI读取文件而非凭记忆补数据——这是防止"AI瞎编数字"的根本方法。
② 来源可溯源，每条数据有出处。 资源文件每张表格标注来自PDF第几页，任何数字都能在原始文件里找到依据。
③ 双工具交叉验证。 fitz提取全文、pdfplumber提取表格，两者互补，消除单工具的提取盲区。
④ 分发版用相对路径。 打包前自动把绝对路径转成resources/相对路径，别人装上就能用。
⑤ 渐进交付，先P0再P1。 先交付最核心内容让用户确认方向，避免做了一大半才发现方向不对。
四、案例应用
以"广州-房建估算-2025"为例：
- 文档：
《广州市本级政府投资项目估算编制指引（2025版）·房屋建筑工程》，298页，287张表格 - 转化结果：
9个资源文件，支持快速/详细两种估算模式
用户提问"帮我估算广州新建二级综合医院，100床，建筑面积6000m²"，Skill执行过程：
判断类型→调用医院专项指标文件 读取指标：100床二级综合医院建安费范围（来源：PDF第89页） 校验：人均面积是否在合理区间 计算并输出估算表，每行数据标注来源
结果可手算验证，每个数字有出处。最终通过8维度59项功能测试、10项PDF原文交叉验证，全部通过。
五、注意事项
适合的文档类型： 含表格/规则/参数、篇幅≥20页、有复用价值的专业文档（工程指引、操作手册、法规汇编、产品参数手册等）。纯叙述性报告、无结构化数据的文档不适合。
几个容易踩的坑：
提取结果不能直接信。 建议抽查10处关键数值与PDF原文对照，OCR扫描版和跨行表格尤其容易出错。
格式规范必须开工前定好。 分隔符、单位、页码格式——这些如果后期才统一，成本极高。
验证脚本FAIL ≠ 数据错误。 fitz有时会把"1100~1200"截成两行，搜索匹配失败，这是工具限制不是数据错误，技能里有"FAIL判断规则表"辅助区分。
大文件用并行Agent。 文档超150页，建议拆分章节并行处理，格式一致性由主Agent统一校验。
写在最后
这个技能解决的是一个具体问题：如何把专业PDF里的结构化知识，转化成AI可以精确调用的可复用技能。
适合的场景：你有一份专业文档，需要反复依据它做判断、计算、生成报告，但文档太长，每次重新喂给AI效率低、结果不稳定。
相关技能请自行在网络检索。
