技能定位： 设计图 SVG+MD 双载体记录方法论——把"会画不懂"的矢量 PDF 工程图，转化为大模型能准确理解、指认与复刻的交付物。
项目地址： 无上游项目仓库——本技能为内部方法论，正文与配套脚本、参考文档均位于本仓库
cad/design-drawing-svg-md/。许可证： MIT——本技能为仓库自有方法技能，随仓库以 MIT 分发（见 LICENSE）。
方法来源： 一套钢结构施工图数字化执行方案的固化与泛化；文中数字为示例值或多图实测值，执行时以实际图纸实测为准。
适用输入： 矢量线画 + 无文字层的 PDF 工程图（彩色分层或单色均可）。
包管理器：
pip install pymupdf numpy scipy pillow（PyMuPDF 2.0、2026-10-19；脚本已按新包名import pymupdf，不再使用旧的import fitz别名，截至 2026-10）依赖版本： Python 3.10+（脚本使用
str | None等 3.10 语法）＋ PyMuPDF ＋ NumPy ＋ SciPy ＋ Pillow；实际运行版本由07_validate.py在测量当时写入validate.json，报告读回而非另行探测，保证与交付物同源。脚本资产： 本仓库
scripts/目录附带可直接复跑的泛化脚本——共用库 scripts/common.py、入口配置 scripts/config.example.json、十一阶段脚本01_extract.py…09_verify_deliverables.py（执行顺序与门禁见 reference/pipeline.md）。
概述
MD 是"大模型阅读主线"，SVG 是"高精度几何档案 + 按需切片源"，两者用统一 ID 体系互联，用校验闭环保证一致。
何时使用
- 需要让大模型/Agent 理解一份工程图纸（几何、尺寸、语义、工艺、管理信息）
- 源图为 PDF，且是矢量线画、无文字层（尺寸数字只是 glyph 轮廓路径，直接渲染"会画不会读"）
- 需要对图纸做问答、复刻重绘、改图、核量、生成 BOM 等下游任务
- 图纸会换版（R00→R01），需要可 diff、可追溯的数字化档案
何时不使用
- 源图已有文字层且无需精确几何 → 直接 PDF 文本提取即可
- 只需一张渲染图给人看，无下游智能任务 → 不必建双载体
- 栅格扫描件 → 本技能不覆盖矢量化（OCR/矢量化另案处理）
适用对象
A0 钢结构施工图（无文字层的矢量线画）为典型用例；任何"矢量线画 + 无文字层"的 PDF 工程图均可套用。
环境准备
bash# Python 3.10+ pip install pymupdf numpy scipy pillow # 配置：从样例复制后按本机改路径与图层口径 cd scripts cp config.example.json config.json # 或运行时 --config /path/to/config.json
common.py 的配置解析顺序：命令行 --config <path> / --config=<path> 优先，否则回退脚本同目录的 config.json；两者都找不到时报错退出并提示。config.json 覆盖模块级常量（PDF 目录、页面尺寸与旋转、图号前缀、颜色→层映射、OCG 名单、字形阈值、字体路径），因此同一套脚本可换图复用而无需改代码。
需要按本机改的关键项：
| 配置项 | 说明 |
|---|---|
paths.pdf_dir / paths.out | 源 PDF 目录与输出根目录 |
sheets | 图号列表（含版本后缀，如 … R00），也是命令行传的图号 |
page.w_pt/h_pt/rotation | 页面尺寸与回正方向，A0 竖放为 ccw90、pt_per_mm=2.83465 |
drawing_no_prefixes | 图号前缀，用于从标题栏文本中识别本图 |
layering.color_layer / ocg_* | 颜色兜底映射与 OCG 语义名单，换企业模板时必改 |
fonts.cjk | 中文字体绝对路径，示例值为 C:/Windows/Fonts/simhei.ttf，Linux/macOS 须换成本机字体 |
单图执行入口统一为 python <阶段脚本>.py <图号>，全链顺序（有依赖，乱序会得到零标签字典）：
text01 → 02 → 03(--all / --contact-sheets / --label-sheets) → 03c → 03d → 03b → 05 → 06 → 04 → 07 → 08 → 09
细节与覆写防护见 reference/pipeline.md §2。
核心概念
双载体定位
text原图 PDF（矢量线画 / 无文字层 / 彩色分层） │ 提取（pymupdf.get_drawings + 分层：OCG 语义优先 + 颜色兜底） ▼ MD（魂·阅读主线） ◄── ID 互联（view/dim/balloon/prim-id + crosswalk） ──► SVG（骨·几何档案） 语义/参数/值/工艺/BOM 原生坐标/图层/视图分组/文本 │ │ └──────── 校验闭环（MD 重绘 ⇄ SVG 叠合 ⇄ 原图）──────────────────────┘ └──────── 消费（MD 全文分块 + SVG 按视图切片）────────────────────────┘
三条设计原则
- 单一事实源：每类信息只在一处为"真"，另一处只引用不复制（分工矩阵见下），避免双份漂移。
- ID 互联而非坐标复制：MD 保留局部 mm 参数坐标（可编辑），SVG 保留页面 pt 原生坐标（精确），换算关系写入 crosswalk。
- token 可行：MB 级 SVG 不整份进上下文；MD 为索引，SVG 按
data-view切片按需取。
为什么不只用单一载体
| 载体 | 优势 | 短板 |
|---|---|---|
| 仅 SVG | 像素级可复刻 | 对模型是坐标流——"会画不懂"（无文字层时尺寸数字只是轮廓路径） |
| 仅 MD | 结构语义可读、可编辑 | "看懂画不准"（细节图元易被省略、无法精确指认） |
理解准确性的四个分量
大模型"准确理解" = 几何精度 × 语义完整 × 可指认 × token 可行，缺一不可：
| 分量 | 含义 | 落点 |
|---|---|---|
| 几何精度 | 每条线的位置/类型/参数可复现 | SVG 原生坐标 + MD 参数图元互校 |
| 语义完整 | 每根线"是什么"、每个视图"看的是什么"、工艺与管理要求 | MD 语义层 + SVG data-* 属性 |
| 可指认 | 文档里每句话能定位到原图确切位置 | ID + crosswalk + 布局表 |
| token 可行 | 装得进上下文 | MD 分块读、SVG 按视图切片读 |
载体分工矩阵（单一事实源）
| 信息项 | 事实源 | 另一载体 |
|---|---|---|
| 页面级精确坐标、线宽、图层归属 | SVG | MD 不复制页面坐标 |
| 参数化几何（局部 mm、可改图） | MD | SVG 不存参数，仅存形状 |
| 尺寸/半径/角度/厚度的值 | MD（dims 表） | SVG <text data-value> 作显示层 |
| 视图划分、归属、比例、投影/剖切关系 | MD | SVG data-view 镜像 |
| 弧/长圆孔的参数（R、len、w、orient） | MD | SVG 以 data-params 旁注，不依赖折线近似 |
| 气球↔零件↔BOM、重量/材质 | MD | — |
| 标题栏、技术要求（逐字） | MD | SVG <metadata> 镜像 |
| 功能语义自然语言注解 | MD | — |
| 不清/待确认项 | MD | — |
| 换算关系（旋转/比例/平移） | crosswalk（MD 附录 + SVG metadata 各存一份，脚本同源生成） | — |
| 渲染兼容性约束（不用 crispEdges、剔除纯白背景矩形、OCG 语义优先 + 颜色兜底的分层映射） | SVG（生成时内建） | MD 不复制 |
冲突仲裁： 几何坐标以 SVG 为准；值与语义以 MD 为准；不一致时由校验闭环（流水线步骤 8）产出修正单，人工确认后回写。
ID 体系与 crosswalk 换算链
ID 体系
| ID | 对象 | 出现位置 |
|---|---|---|
V{nn} | 视图 | SVG data-view / MD 章节标题 |
V{nn}-P{mm} | 几何图元 | SVG data-prim-id / MD 图元 JSON |
V{nn}-D{mm} | 尺寸标注 | SVG data-dim-id（线与 text 同号）/ MD dims 表 |
V{nn}-B{mm} | 气球（零件编号） | MD 标注章 |
换算链
MD 参数坐标（x, y）= 视图局部 mm，原点 = 视图 bbox 左下角，X 右 Y 上；s = 2.83465 / 比例分母（pt/mm）：
textX_L = x·s + tx Y_L = −y·s + ty 页面 pt（竖放）：x_p = W − Y_L y_p = X_L
- 回正规则（唯一结论）： 页面内容回正 = 逆时针 90°（ccw90）；pymupdf 调用
page.set_rotation(270)。 - 自检（self_check）： 局部原点 (0,0) 换算后必须落在该视图 bbox 左下角（x_p = bbox 左界、y_p = bbox 下界）。
- s、tx/ty 与各坐标值均为示例值（如 1:20 → s≈0.14173）；实际图纸以配准（流水线步骤 5）实测为准。
- crosswalk 条目 JSON 全文见 reference/md-spec.md。
典型工作流：生产与校验流水线（11 步）
完整职责、脚本执行顺序、关键依赖与门禁矩阵见 reference/pipeline.md；本节只留步骤索引 + 门禁矩阵。文中数字均为多图实测值。语义步骤号 ≠ 执行顺序（如 06 SVG 生成在 04 MD 增补之前执行），执行顺序以 reference/pipeline.md §2 为准。
- 矢量提取 + 分层（
01_extract.py）：pymupdf.get_drawings()按 OCG 语义优先 + 颜色兜底 归六层（颜色→层硬映射对部分图失效）；title-block 靠 OCGlayer==PDM_Title独立成层，否则退化为五层不合规。 - 视图聚类归属（
02_cluster_views.py）：outline + dimension + centerline 空间聚类（排除 thin 层）；视图数是聚类输出、非可预设目标（实测区间 [8,26]）。 - 跨图字形字典（
03/03c/03d）：模板聚类 → 自监督解码 → 视觉逐行对账，跨图合并；视觉识读过双闸门（图号真值 + 转录字符数核对）才入字典。 - 文本恢复（
03b_text_recover.py）：按视图 bbox 高清竖正裁切识读 →<text>+ dim-id 绑定；竖排归一化必须用(x,y) → (1−y, x)（旧式(y, 1−x)缺平移校正、静默降质）。 - 配准（
05_crosswalk.py）：逐视图定尺度/旋转/平移 → crosswalk 的 tx/ty +self_check；比例三档 read/inferred/fallback（实测 read 档全 0，inferred score=0 归 fallback）；V00 整页图框区用frame_scale()页面几何自证 1:1。 - SVG 生成（
06_enhance_svg.py）：按六层 + 视图分组生成增强版 SVG（骨）——data-*属性、<text>尺寸绑定、弧/圆参数旁注、metadata 同源镜像（见 reference/svg-spec.md）。 - MD 增补（
04_build_md.py）：补 ID / 语义注解段 / crosswalk → 重建 MD（三条硬约束见 reference/md-spec.md）。 - 三方互校（
07_validate.py）：MD 重绘 ⇄ SVG 叠合（2px 膨胀容差度量，recall≥0.99 门禁）；绿层值集合 ⇄ dims（绑定率非门禁，未绑定值只入 MD §6）；BOM ⇄ 气球。 - LLM 验收（
08_qa.py）：题库 ≥20 题 + 盲测子代理只读交付物作答，准确率 ≥95% 方交付。 - 独立审计（
spec_audit/final_audit探针）：不复用生成器判定，从交付物 + 源 PDF 重算方案条款。 - 交付物齐套（
09_verify_deliverables.py）：六件套齐套 + 门禁汇总 + 基线对账（见交付物与命名章）。
关键实测结论（多图验证）
- 分层：OCG 语义优先 + 颜色兜底；纠偏只在主色占比 >50% 时触发，逐图落盘
meta.triggers+ 分层审计表。 - 竖排归正式：
(x,y) → (1−y, x)；写错是静默降质（模板虚增 1010→1031、竖排已解行 129→1）。 - 视图数不可预设：是聚类输出（实测 [8,26]），不得为对齐基线数字调参或加机制。
- 绿层绑定率非门禁：上限是字典标签覆盖率（31/1010），未绑定值只入 MD §6 不清项。
- 比例三档 read/inferred/fallback；实测 read 档全 0，
score=0仍叫inferred有误导 → 归fallback。 - 视觉识读双闸门：图号真值（单行转录最长公共子串）+ 转录字符数核对（容差 0）；第一道未过整图不采信。
- 三方互校容差度量：2px 膨胀 + recall/precision/F1，门禁 recall≥0.99；严格 IoU 假性偏低仅参考；precision 不作门禁。
- V00 比例：
frame_scale()页面几何自证 1:1，不打分。 - MD 三条硬约束：单文件 ≤80000 字符、总量类问题须有明文句子可逐字核对、§3 须给 prim-id 区间 + 计数且区间求和 == kept。
门禁矩阵（硬门禁 12 项 vs 基线对账）
| 类别 | 含义 | 项 | 不达标动作 |
|---|---|---|---|
| 硬门禁 | 交付物自洽性与合规性，必须全过 | 计数链四相等、六层齐全（含独立 title-block）、无 UNASSIGNED、recall≥0.99、rms≤0.1pt、载体一致性、self_check 全过、QA≥20 题、五类齐全、QA 自检 100%、盲测≥95%、MD≤80000 字符 | 回相应阶段修正后重跑，不得放行 |
| 基线对账 | 与参照数值比较，只记录并解释 | 逐层图元数、视图数、绑定率、recall/rms 具体数值 | 写清机制差异；禁止为对齐数字调参或加机制 |
验收题库
每图 ≥20 题、覆盖五类；题库与答案单独成 JSON 交付物。验收时仅把交付物（MD + SVG 切片）喂给模型，不喂本技能与方案文档。
| 类别 | 考察点 | 示例题（示例值） |
|---|---|---|
| 结构类 | 总量/材质（BOM） | 本图共几件？总重？件11 数量/材质？ |
| 几何类 | 参数值（dims） | 件11 圆头半径、起吊孔径、斜边角？ |
| 关系类 | 视图关系 | A-A 剖切经过哪些件？V16 是哪个位置的放大？ |
| 工艺类 | 技术要求 | 吊耳底部焊缝高度与无损等级？未注焊缝？ |
| 指认类 | ID→语义定位 | V15-D03 标注的是哪个视图的哪个零件的哪个方向？ |
验收标准： 结构/几何/关系/工艺类准确率 ≥95%，指认类 100%，方视为"大模型已准确理解本图"。
大模型消费策略（token 可行）
- 默认只读 MD：语义、值、关系全在（示例：某 A0 图全文约 7.7 万字符，示例值）；按视图章节分块读，单章约 3–10KB。
- 需要精确坐标时按视图切 SVG：以
data-view="Vxx"抽取该组（单视图通常 10–40KB，示例值），连同 MD 对应章节一起喂。 - 永不整份喂 MB 级 SVG；glyph 路径段（dimension 层数字轮廓）切片时剔除，只留
<text>。 - 重绘/改图任务：以 MD 参数为输入；校验/测量任务：以 SVG 切片为输入。
- 回答"图上一共有几个零件/多重"类总量问题：先读 MD 的 BOM 章，再按需用 SVG 切片核对气球位置。
交付物与命名
| 文件 | 内容 | 事实源角色 |
|---|---|---|
<图号> R<x>.svg（增强版） | 骨：分层 + 视图分组 + 文本恢复 + 参数旁注 + metadata | 几何/图层/页面坐标 |
<图号> R<x>-可复现图纸描述.md | 魂：六层 schema + ID + 语义注解 + crosswalk 附录 | 值/语义/工艺/BOM |
<图号> R<x>_crosswalk.json | view↔svg 组↔换算（MD 附录同份，脚本同源生成） | 换算 |
<图号> R<x>_QA题库.json | 验收题库及答案（≥20 题五类） | — |
<图号> R<x>_修正单.md | 三方互校差异仲裁记录（随版归档） | — |
反向重绘验证.png | 校验产物，随版更新；必须与源渲染同分辨率（示例：scale=2.0≈144DPI），降采样会糊、无法叠合校验 | — |
范围分级（按工期取舍）
| 能力 | 最小版 | 完整版 |
|---|---|---|
| 六层 SVG + MD 六层 schema | 是 | 是 |
| ID 体系 + crosswalk | 是（bbox 级对齐，不做锚点吸附） | 是（含锚点吸附校正） |
| data-view 视图分组 | 是 | 是 |
<text> 文本恢复 | 仅尺寸值 + 视图标签 | + 标题栏/焊缝符号/剖切标记 |
| 弧/长圆 data-params 旁注 | — | 是 |
| 语义注解段 | 每视图 1 句 | 每视图 1–3 句 + 关系句 |
| 三方互校 + LLM 验收 | 值集合核对 | + 叠合差集 + 题库 ≥95% |
| data-view 无 UNASSIGNED（标题栏/图框归 V00） | 是 | 是 |
| crosswalk 记 scale_source + self_check | self_check | + scale_source 三档分级 |
| 叠合用容差度量（recall/precision/F1） | — | 是（recall≥0.99 门禁） |
| 独立于生成器的审计 | — | 是（09 + spec_audit + final_audit，三者互不复用判定） |
估算（实测修正）：最小版 ≈0.5 人日/图；完整版 ≈1.5–2 人日/图（首图含字典冷启动更高，后续图因字典跨图复用递减）。原估「≈1 人日/图」未计入跨图字形字典、多轮盲测答卷维护、独立审计三处增量。
风险与缓解
| 风险 | 缓解 |
|---|---|
| 视图聚类错分/粘连 | 与 MD 布局表互认；粘连视图人工指定 bbox |
| 文本复读误（162°/163° 类，示例） | 双源独立读 + 仲裁；冲突值入 unclear 不臆造 |
| 曲线折线化丢参数 | MD 参数为真 + SVG data-params 双轨 |
| 双载体漂移 | crosswalk/metadata 由脚本从 MD 同源生成，禁手改 |
| 渲染器兼容性（crispEdges 吞细线；无描边纯白填充矩形覆盖全图） | 交付 SVG 不带 shape-rendering=crispEdges；提取时剔除无描边纯白背景矩形；校验与消费固定同一渲染器及版本 |
| 版本变更（R00→R01） | ID 与版本号绑定；换版重跑流水线，diff 出变更单 |
| 反向重绘糊化（降采样） | 重绘固定原分辨率；与叠合校验共用同一渲染器 |
| 渲染库缺 cairo（svglib/reportlab） | 重绘脚本用 PIL 直读 get_drawings() 数据，不走 svglib→PNG 链路 |
| 视图聚类串簇（thin 层横跨全页） | 聚类排除 thin(黄)层，仅用 outline+dimension+centerline |
| BOM 缺失 | 源图标题栏可能不含可填写明细表；降级为记录"BOM 未提供"并列出已识别零件编号，不得臆造材料/重量 |
| 颜色→层硬映射对个别图失效（黄既是 thin 又是 title-block） | OCG 语义优先、颜色兜底；任一色占比 >50% 时触发复核并落 meta.triggers + 分层审计表 |
竖排归正式写错（静默降质：所有 rotate(90) 文本坐标错位，计数类门禁却全过） | 用 self_check 双界断言逐视图验；竖排归一化固定用 (x,y)→(1−y,x) |
| 发丝线严格 IoU 假性偏低（0.12pt 抗锯齿） | 叠合用容差度量（2px 膨胀 + recall/precision/F1）；严格 IoU 仅参考，precision 不作门禁 |
| 为对齐基线数字而调参/加机制 | 基线不吻合先做参数扫描取证，证不可弥合后按「记录并解释」登记，不改机制凑数 |
| 校验由生成器自判（「自己说自己通过」） | 官方 09 之外另立不复用其判定的审计（spec_audit + final_audit）；FAIL 先定性（口径错 / 真缺陷）再动手 |
| metadata 裸 JSON 含中文/特殊字符破坏 XML | 用 <![CDATA[...]]> 包裹 |
最佳实践
- 先跑门禁再读图：任何交付前先过
09_verify_deliverables.py的硬门禁；门禁不过就回对应阶段修正，不放行、不手工补数字。 - 基线只解释不调参：视图数、逐层图元数是聚类与分层的输出。与参照值不符时先做参数扫描取证，证明确属机制差异后登记"记录并解释"，禁止为凑数字加机制。
- 改签名函数必从
01起重跑：glyph sid 由01落盘，后续脚本只读不重算；从中间步骤重跑会让改动静默失效。 - 同源生成，禁手改：crosswalk 与 SVG
<metadata>由脚本从 MD 生成；手改任一份会造成双载体漂移。 - 渲染口径固定：校验、叠合、消费固定同一渲染器与版本，
scale=2.0；反向重绘降采样会糊到无法叠合。 - 不清项显式登记：读不出、冲突的值进 MD 的 unclear 章，不臆造材料/重量；BOM 缺失时降级为"未提供 + 已识别零件编号"。
- 换版走流水线：R00→R01 重跑全链并 diff 出变更单，ID 与版本号绑定，避免只改 MD 不改 SVG。
- 审计独立于生成器：
spec_audit/final_audit从磁盘交付物与源 PDF 重算，FAIL 先定性（口径错还是真缺陷）再动手。
常见问题
| 问题 | 原因与处置 |
|---|---|
| 脚本报"找不到配置" | 未传 --config 且脚本同目录无 config.json；复制 config.example.json 为 config.json 或显式传路径 |
| 分层只有五层 | title-block 没独立成层：确认 OCG 名单里能命中 PDM_Title，否则按 layering.ocg_* 补企业模板的图层名 |
| 字典全零标签 | 执行顺序错。03b 必须在 03c/03d 之后（它读 glyph_labels.json），且 03 要跑 --contact-sheets 才能更新 templates.json |
| 竖排文字坐标整体错位 | 竖排归一化式写成了 (y, 1−x)；正确为 (x,y)→(1−y,x)，并用逐视图 self_check 双界断言拦截 |
| 严格 IoU 只有 0.1 上下 | 发丝线抗锯齿导致的假性偏低；叠合改用 2px 膨胀的 recall/precision/F1，门禁只看 recall≥0.99 |
| 中文字体缺字 | fonts.cjk 还是 Windows 路径；改为本机字体（03d 加载失败会回退位图字体，不致命但行格图标签可能缺字） |
| SVG 里细线消失 | 渲染器吞掉 shape-rendering=crispEdges 的细线；交付 SVG 不带该属性，并剔除无描边的纯白背景矩形 |
| 计数链对不上 | drawings→bg→kept→SVG path→MD prim_ids 五个口径要逐项对账，差异常来自整页白底矩形与 path 合并 |
AI 使用建议
- 推荐工作流模式：AI 助手处理矢量 PDF 工程图时，先按 reference/pipeline.md §2 的顺序跑通十一步流水线（从
01起，乱序会得到零标签字典），任何交付前先过09_verify_deliverables.py的硬门禁，门禁不过就回对应阶段修正，不放行、不手工补数字。 - 关键注意事项：① MD 是阅读主线、SVG 是几何档案，两者用统一 ID + crosswalk 互联，禁止手改同源生成的 crosswalk/metadata；② 竖排归一化固定用
(x,y)→(1−y,x)，写错是静默降质；③ 视图数是聚类输出、不可预设，不得为对齐基线数字调参或加机制；④ 读不出或冲突的值进 unclear 章，不臆造材料/重量。 - 常用代码模式：单图执行统一为
python <阶段脚本>.py <图号>；配置从config.example.json复制为config.json后按本机改路径、图层口径与中文字体。 - token 策略：默认只读 MD（按视图章节分块，单章约 3–10KB），需要精确坐标时按
data-view="Vxx"切 SVG 切片，永不整份喂 MB 级 SVG。 - 验收口径：结构/几何/关系/工艺类准确率 ≥95%、指认类 100%，且硬门禁 12 项全过，方视为"大模型已准确理解本图"。
- 不要臆造：文中比例、图元数、字符数等数字为示例值或多图实测值，执行时以实际图纸实测为准；基线不吻合先做参数扫描取证，按「记录并解释」登记。
相关技能
- libredwg — DWG/DXF 读写与 libredwg-python 映射，有文字层的正式图纸可直接走该路径：../libredwg/SKILL.md
- qcad — DXF 编辑与命令行转换（
qcad -autoclose导出矢量格式）：../qcad/SKILL.md - clipper2 — 多边形布尔与偏移，叠合容差/膨胀类计算的库化替代：../clipper2/SKILL.md
- ifoxcad — AutoCAD .NET 二次开发与图纸数据提取：../ifoxcad/SKILL.md
参考资源
- SVG 规范（骨）： reference/svg-spec.md — 完整 XML 示例、四项增强、data-* 属性速查、渲染兼容性约束
- MD 规范（魂）： reference/md-spec.md — 六层 schema、逐视图章节模板、crosswalk JSON 全文、BOM 降级规则、三条硬约束
- 流水线（十一步）： reference/pipeline.md — 每步职责、脚本执行顺序与覆写防护、门禁矩阵、范围分级
