ScottDuncanAI/pid-to-kg

管道及仪表流程图（P&ID）转知识图谱

工作由确定性脚本和您共同完成：

• 脚本 负责对页面进行分类（矢量图 vs 扫描图），将其渲染为可读的图块，收集 OCR/文本提示，然后构建、检查、存储和查询图谱。
• 您 负责阅读图纸，并为每张图纸编写一个结构化的提取文件。符号识别和线条追踪属于视觉推理，这也是脚本难以做好的部分。

所有脚本都位于此文件旁边的 scripts/ 目录中。通过其完整路径调用它们（以下命令缩写为 scripts/），并将工作目录保留在用户的当前文件夹中，例如 work/<plant>。

设置。 许多用户是工程师而非程序员，因此请自行处理设置。脚本需要 Python 3.10+。在首次运行之前，使用 pip install -r <skill dir>/scripts/requirements.txt 安装依赖项（如果用户的 Python 环境与其他工作共享，请使用虚拟环境）。如果缺少 Python，请告知用户从 python.org 安装，并在此处停止。

基本原则

• 仅限于 P&ID 页面。 图纸通常位于冗长的许可或设计报告中。如果用户指定了页面，请使用 --pages 参数传递。如果没有指定，且 PDF 页数较多，请探查 PDF，查看页面概览或询问用户，然后使用 --pages 重新运行探查，以便后续步骤跳过报告、图例和非 P&ID 图纸。
• 一个工厂，一个工作目录，一个图谱。 切勿将不同工厂的图纸放在同一工作目录中：这样会导致标签跨不相关的工厂合并。如果用户提供多个工厂，请为每个工厂单独运行整个工作流程。
• 每个图谱一个配置。 如果 PDF 包含同一图纸的两个修订版本（相同标题或区域，标签重叠，例如竣工图和旧草稿），请不要合并它们。询问用户使用哪个修订版本，仅提取该版本，并在报告中记录被排除的页面及原因。QA 会将可能的重复版本标记为 possible_duplicate_revision。从标题栏或印章中记录每张图纸的 issue_status。
• 仅记录图纸上绘制的内容。 切勿为了追求图谱完整性而凭空编造标签、连接或回路。任何不明确的内容都应标记为低 confidence，或放入 unreadable 中。
• QA 循环是必须的，不可省略。 持续重新构建直到没有错误，并对照图纸重新检查每一条警告。

工作流程

将此清单复制到您的笔记中并逐项勾选：

- [ ] 1. 探查：    python scripts/probe_pdf.py <pdf> --work <work> --plant-name "<name>" [--pages 47-60]
- [ ] 2. 渲染：   python scripts/render_pages.py <work>
- [ ] 3. 定向：   打开每个 pages/page_NN/overview_grid.png；如果文字不是正向的，则修正旋转
- [ ] 4. 提示：    python scripts/make_hints.py <work>
- [ ] 5. 提取：   对于每张图纸，编写 <work>/extract/page_NN.json（参考 references/extraction_procedure.md）
- [ ] 6. 构建：    python scripts/build_kg.py <work>
- [ ] 7. QA 循环： 修复所有错误，重新检查每条警告，重新构建（重复）
- [ ] 8. 报告：   总结结果并为用户提出待解决问题

1. 探查

probe_pdf.py 为每页分配一个类别和提取路径，并写入 <work>/manifest.json。使用 --pages 参数时，后续步骤仅渲染和读取这些页面。

类别	含义	路径
vector_text	带有文本层的矢量图	从矢量渲染；使用文本层中的精确文本作为提示
vector_outlined	矢量图，文本绘制为轮廓（无文本层）	高分辨率矢量渲染；OCR 提示
raster	扫描图像	原生分辨率渲染，放大并增强对比度；OCR 提示
raster_with_text	带有 OCR 文本层的扫描图	如同栅格图；文本层作为（不可靠的）提示
hybrid	矢量图与大型图像混合	两种路径

向用户报告探查结果，一行即可，例如“14 张带有轮廓文本的矢量图纸。”

低扫描分辨率会在注释中标记。在这些图纸上，预计会在 unreadable 中记录更多项目。

2–3. 渲染并检查方向

render_pages.py 为每个页面写入以下文件：

• overview.png
• overview_grid.png，显示图块名称
• tiles/ 目录中的重叠图块
• tiles.json，记录哪些图块是空白的

如果安装了 OCR，则会自动检测方向。始终在 overview_grid.png 上确认方向。如果主要图形文本不是正向的，请使用明确的旋转角度（顺时针）重新渲染该页面：render_pages.py <work> --pages N --rotation 90。

标题栏有时会与图形本身旋转方向不同。以图形标签为准，而不是标题栏。

4. 提示

make_hints.py 写入 hints/page_NN.json。每个文件包含候选标签及其页面位置，这些信息来自文本层或 OCR。它们只是提示：OCR 可能会误读，并且会遗漏内容。在提取过程中无需读取提示文件。QA 会使用它们来标记您可能遗漏的标签。如果未安装 OCR，则跳过此步骤；请在最终报告中注明。

5. 提取每张图纸

这是工作的核心。请严格按照 references/extraction_procedure.md 进行操作。它涵盖了：

• 阅读顺序：先看概览，然后查看每个非空白图块，最后查看放大的裁剪区域
• 如何建模管线、三通、支管、信号和跨页连接器
• 置信度校准
• 保存前需要执行的自我检查清单

参考资料（需要时阅读）：

• references/isa_5_1.md：仪表字母代码、气泡符号、信号线类型
• references/symbol_guide.md：设备和阀门符号如何映射到 kind 值
• references/ontology.md：图谱的节点和边类型及其推导方式
• references/schema/extraction.schema.json：页面文件的精确 JSON 模式

编写 extract/page_NN.json 并在开始下一张图纸之前保存，这样长任务上下文窗口内最多只保留一张图纸。如果图纸很多，并且您的环境支持子代理，您可以并行提取图纸。为每个子代理提供程序文件及其自己的页面目录。

6–7. 构建和 QA 循环

build_kg.py 验证每个页面文件，并在出现模式错误时停止并显示精确消息。然后，它将以下文件写入 <work>/kg/：

• graph.json
• graph.duckdb
• summary.md
• qa_report.md

仔细处理 qa_report.md：

• 错误，例如 unresolved_reference，是页面文件中的错误。修复它们并重新构建。
• 警告 指出需要重新检查的图块。再次查看这些图块，或使用 crop.py 获取放大视图，如果图纸显示不同内容，则修正提取。常见警告：
  • instrument_not_located：传感器没有 measures
  • equipment_not_connected
  • unmatched_off_page
  • possible_missed_tags：OCR 标签未出现在您的提取中
  • tiles_not_reviewed
• 如果在图纸上确认无误，则保留该警告。示例：一个跨页连接器，但其对应的另一图纸未提供；或 OCR 误读。在您的报告中列出这些内容。

在没有错误且每条警告都已检查完毕后停止。

python scripts/crop.py <work> --page 5 --bbox 0.40 0.20 0.55 0.35   # 某区域的放大视图

8. 报告

告知用户：

• 输出文件的位置
• 关键统计信息（设备数量、仪表数量、回路数量）
• 从 summary.md 中提取的两到三个示例流程路径和回路
• 仍然存在的不确定之处

指出 qa_report.md 包含详细信息。明确说明该图谱是机器提取的，在用于设计、操作或安全分析之前需要经过工程审查。

使用图谱

• summary.md 是紧凑、令牌高效的 LLM 上下文：提供设备级流程、包含位置的仪表表以及回路表。
• graph.json 是规范图谱，任何工具都可以读取。
• graph.duckdb 用于 SQL。其视图包括 equipment、equipment_flow、instruments、loops 和 signals，表宏包括 upstream(id) 和 downstream(id)。

使用 kg_query.py 回答问题；当输出将被其他工具消费时，添加 --json：

python scripts/kg_query.py <work>/kg downstream 660-TK-001 --equipment
python scripts/kg_query.py <work>/kg upstream FV-0502
python scripts/kg_query.py <work>/kg path 660-TK-001 660-TK-004
python scripts/kg_query.py <work>/kg instruments --on 660-PP-011
python scripts/kg_query.py <work>/kg loop FIC-0502
python scripts/kg_query.py <work>/kg sql "SELECT * FROM equipment_flow"

要评估某张图纸的提取质量，请手动将其检查为一个小型金标准文件（格式见 scripts/eval_kg.py），然后运行 python scripts/eval_kg.py <work>/kg gold.json：它会报告标签、流程和回路的精确率/召回率，以及仪表位置。

要将图谱迁移到其他工具：python scripts/export.py <work>/kg graphml 生成一个适用于 yEd、Gephi 或 NetworkX 的文件，而 python scripts/export.py <work>/kg neo4j 生成 CSV 文件以及一个 Cypher 导入脚本。