design-drawing-svg-md git:20260902.9126102A

Immutable. This exact content never changes and is served at /api/v1/blob/df7805d80d5b4377.

---
name: design-drawing-svg-md
description: "Use when converting vector PDF engineering drawings (steel-structure shop drawings, A0 drawings, linework-only PDFs without a text layer) into LLM-consumable dual-carrier records — semantic Markdown reading thread plus layered SVG geometry archive linked by shared IDs and crosswalk."
tags:
  - cad
  - svg
  - markdown
  - pdf
  - steel-structure
  - drawing
  - llm
  - workflow
---

> **技能定位：** 设计图 SVG+MD 双载体记录方法论——把"会画不懂"的矢量 PDF 工程图，转化为大模型能准确理解、指认与复刻的交付物。
>
> **方法来源：** 一套钢结构施工图数字化执行方案（v1.2）的固化与泛化；文中数字均为示例值，执行时以实际图纸实测为准。
>
> **适用输入：** 矢量线画 + 无文字层的 PDF 工程图（彩色分层或单色均可）。本仓库不附带脚本资产，各步骤脚本由执行者按本规范编写。

---

## 概述

**MD 是"大模型阅读主线"，SVG 是"高精度几何档案 + 按需切片源"，两者用统一 ID 体系互联，用校验闭环保证一致。**

### 何时使用

- 需要让大模型/Agent 理解一份工程图纸（几何、尺寸、语义、工艺、管理信息）
- 源图为 PDF，且是矢量线画、无文字层（尺寸数字只是 glyph 轮廓路径，直接渲染"会画不会读"）
- 需要对图纸做问答、复刻重绘、改图、核量、生成 BOM 等下游任务
- 图纸会换版（R00→R01），需要可 diff、可追溯的数字化档案

### 何时不使用

- 源图已有文字层且无需精确几何 → 直接 PDF 文本提取即可
- 只需一张渲染图给人看，无下游智能任务 → 不必建双载体
- 栅格扫描件 → 本技能不覆盖矢量化（OCR/矢量化另案处理）

### 适用对象

A0 钢结构施工图（如 X600S-888301A 6-3/6-6 R00）为典型用例；任何"矢量线画 + 无文字层"的 PDF 工程图均可套用。

---

## 核心概念

### 双载体定位

```
原图 PDF（矢量线画 / 无文字层 / 彩色分层）
   │  提取（fitz.get_drawings + 颜色分层）
   ▼
MD（魂·阅读主线） ◄── ID 互联（view/dim/balloon/prim-id + crosswalk） ──► SVG（骨·几何档案）
语义/参数/值/工艺/BOM                                       原生坐标/图层/视图分组/文本
   │                                                                    │
   └──────── 校验闭环（MD 重绘 ⇄ SVG 叠合 ⇄ 原图）──────────────────────┘
   └──────── 消费（MD 全文分块 + SVG 按视图切片）────────────────────────┘
```

### 三条设计原则

1. **单一事实源**：每类信息只在一处为"真"，另一处只引用不复制（分工矩阵见下），避免双份漂移。
2. **ID 互联而非坐标复制**：MD 保留局部 mm 参数坐标（可编辑），SVG 保留页面 pt 原生坐标（精确），换算关系写入 crosswalk。
3. **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、剔除纯白背景矩形、颜色→图层语义映射） | **SVG**（生成时内建） | MD 不复制 |

**冲突仲裁：** 几何坐标以 SVG 为准；值与语义以 MD 为准；不一致时由校验闭环（流水线步骤 6）产出修正单，人工确认后回写。

---

## 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）：

```
X_L = x·s + tx          Y_L = −y·s + ty
页面 pt（竖放）：x_p = W − Y_L          y_p = X_L
```

- **回正规则（唯一结论）：** 页面内容回正 = 逆时针 90°（ccw90）；fitz 调用 `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](reference/md-spec.md)。

---

## 生产与校验流水线（8 步）

各步骤所需脚本与动作由执行者按本规范编写与执行；〔新〕= 相对基础六层 SVG/六层 MD 的增量环节。文中数字均为示例值。

1. **矢量提取 + 分层**：`fitz.get_drawings()` 按颜色归六层 → 基础 SVG。
2. **视图聚类归属〔新〕**：outline + dimension + centerline 三层做空间连通聚类（必须排除 thin/黄层——图框/标题栏线横跨全页会把所有视图串成单簇）；聚类 eps≈25pt（bbox 扩展相交并查集，示例值）；与 MD 布局表互认，产出 `data-view` 分组与 bbox；详图密集区粘连时人工指定 bbox。
3. **文本恢复〔新〕**：整页渲染（≈144DPI）+ 分区放大后交视觉多模态模型识读（细线 glyph OCR 易碎、不推荐）；绿层掩码裁切作交叉核对；MD 已有值为先验；产出 `<text>` 并与 dim-id 绑定。
4. **MD 增补**：在六层 MD 上补 ID、语义注解段、crosswalk 字段 → 重建 MD。
5. **配准〔新〕**：逐视图固定尺度/旋转后，用对应锚点（视图外框角点/对称轴交点）直接求平移，得 crosswalk 的 tx/ty；CAD 矢量图无采样噪声、无需 RANSAC；并把 MD 的"测量"坐标吸附到 SVG 原生坐标。
6. **三方互校**：MD 重绘 ⇄ SVG 叠合（几何差集）；绿层尺寸值集合 ⇄ MD dims；BOM ⇄ 气球；差异出修正单、人工仲裁后回写。
7. **LLM 验收〔新〕**：题库问答（见下节），仅喂交付物作答，准确率 ≥95% 方交付。
8. **交付物齐套**（见交付物与命名表）。

---

## 验收题库

每图 ≥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% |

估算（示例）：最小版 ≈0.5 人日/图（主要增量为视图分组与文本恢复）；完整版 ≈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 未提供"并列出已识别零件编号，不得臆造材料/重量 |

---

## 参考资源

- **SVG 规范（骨）：** [reference/svg-spec.md](reference/svg-spec.md) — 完整 XML 示例、四项增强、渲染兼容性约束
- **MD 规范（魂）：** [reference/md-spec.md](reference/md-spec.md) — 六层 schema、逐视图章节模板、crosswalk JSON 全文、BOM 降级规则