CAD2GIS MCP Server

CAD2GIS · CAD → GIS for AI agents

把 DWG/DXF 转成可复核的 GIS，并让 AI Agent 检查、编辑 CAD 副本和交付 QGIS 项目。

官方网站 · 九图效果展示 · 安装指南 · 发行版本 · English · 双语 Wiki

CAD2GIS 将源实体、语义映射、几何、拓扑、长度与坐标证据串成可重放流程。 CLI、Python API、审查工作台和 cad2gis-agent MCP 插件使用同一条转换流水线。 适合 CAD/GIS 工程师，以及使用 Codex、Claude Code、Cursor、VS Code 的 Agent 工作流。

0.8.0 能做什么

旁路固定使用 U-C4N/Autocad-MCP 的 MIT 许可 无界面 DXF 引擎，独立安装。它只编辑副本，结果重新进入 CAD2GIS 验收。 详见 CAD 能力与安装。

先看效果

查看九张图的效果、图层与过程。 展示复用既有 Pages 内容；九图仍为 CONDITIONAL，没有验证测量级绝对定位精度。 图纸声明 CRS 或视觉重合，均不能单独证明位置准确。

三步接入 Agent

先安装 uv，使用 Python 3.12：

uv tool install --python 3.12 --force "cad2gis[agent] @ https://github.com/Mola-maker/CAD2GIS/archive/refs/heads/main.zip"
cad2gis-agent-mcp --help
cad2gis doctor --deep --profile full --json

DWG 转换另运行 cad2gis runtime install。DXF 检查不需要 LibreDWG；GIS 转换仍需要 GIS runtime。

Codex：

codex plugin marketplace add Mola-maker/CAD2GIS --ref main
codex plugin add cad2gis-agent@cad2gis

Claude Code：

claude plugin marketplace add Mola-maker/CAD2GIS
claude plugin install cad2gis-agent@cad2gis-tools

其他客户端使用 MCP 配置模板。 让 Agent 从 get_capabilities、get_runtime_status、inspect_source 开始。 可选 CAD 编辑另调用 get_cad_bundle_status，按 旁路参考 安装。

下载与版本

0.8.0 是本次 Python/Agent 源码发行；桌面安装包按其实际版本提供。

Linux 安装要求见 安装说明。预发布请使用明确版本链接。 旧安装包保持其原始许可与验证范围；Apache-2.0 适用于本次新版原创代码。

文档与参与

插件指南 · 贡献指南 · 问题反馈 · 发现与分发渠道 · OSM 匹配 · SVG 与 QGZ · 多分区复核 · Docker

原创代码采用 Apache-2.0，允许商用、修改和分发。 第三方组件与客户图纸保留各自权利，见 NOTICE。 欢迎用合成或可公开分享的图纸提交复现与新工作流；不要在公开 issue 上传客户原图。

---

术语

• APD = As Plan Drawing：建筑工程领域的“按计划图纸”，记录的是 as-planned 设计，不是 as-built 竣工实测；也不是“接入点设备”。
• SF = Subfeeder：光缆/电缆网络中的副馈线 / 分支配电线；文件名中的 - SF 表示该图是网络的 subfeeder 部分。
• 外部语料中 4 张 DWG 是建立算法流程的开发/基线集，后加入的 6 张是 验证集，必须按新图各自 source-bound 处理，不得复用基线规则或数量门禁。

完整定义与两份清单见 docs/GLOSSARY.md。

快速开始

容器部署与本地镜像构建见 Docker 运行说明。

1. 按下方“安装”创建固定运行环境并执行 cad2gis doctor；
2. 安装 plugins/cad2gis-agent，或把对应 clients 模板加入现有智能体；
3. 在 DWG 项目目录中启动智能体，让它先调用 get_capabilities、 get_runtime_status 和 inspect_source；
4. 默认转换执行 OSM 相对匹配和 SVG 图例候选提取；用 cad2gis review 打开结果， 检查图层、标签、长度、拓扑和位置，并复核 SVG 与原图实体的对应关系；
5. 位置需要修正时，添加 CAD → 地图控制点查看人工校正预览，再点击 “二次匹配并生成新结果”。完成后工作台自动加载新 GIS，保留控制点供继续迭代。

已有通过验证的项目配置时，可直接运行以下命令。尖括号中的内容是需要替换的 本地路径；每次转换使用新的输出目录。

cad2gis convert "<SOURCE.dwg>" --project "<PROJECT_DIR>" --run-dir "<NEW_RUN_DIR>" --json
cad2gis review "<NEW_RUN_DIR>" --workspace "<REVIEW_DIR>" --port 8765

打开 本地工作台。最终 delivery.gpkg 使用当前匹配坐标， 并记录 relative_osm 来源；人工选点保存时只改变预览，确认二次匹配才生成新 GIS。 OSM 匹配包含单位、投影转换和平移，不自动旋转、拉伸或把缆线改画成道路。 离线道路快照使用 --osm-data "<OVERPASS.json>"；需要显式地点提示时使用 --osm-place "<PLACE_NAME>"。完整参数、分区行为和复现方法见 OSM 标准匹配说明。

convert、auto-convert、MCP 和批量转换默认使用 svg_mode=candidate，在 <NEW_RUN_DIR>/svg-candidates/ 保存 symbols.sqlite3、correspondence.json 和 correspondence.html。SVG 与 GIS 完整生成后一起发布；提取失败时不发布新 run， 已有结果保留。候选只供复核，不会自动替换交付样式。原图需要指定字体时可重复使用 --svg-font-dir "<FONT_DIR>"；显式 --svg-mode off 关闭提取。候选来源、哈希及 人工绑定方式见 SVG 提取说明。

插件是 canonical Python 流水线的薄接入层。没有安装 GIS runtime、DWG reader 或没有授权项目根目录时，插件会失败关闭，而不会输出伪成功 GeoPackage。

下面的命令不需要先克隆仓库。先按操作系统安装同一个可移植 cad2gis-agent-mcp 控制面运行时，再按智能体客户端注册插件。安装命令使用 main.zip 而不是完整 Git 历史，并用 --force 主动替换旧版本；因此它也能修复 指向已删除 worktree 的 editable 安装。

Windows 更新或修复前，先退出正在使用 CAD2GIS 的 MCP 客户端并停止 cad2gis review。运行中的 Python 进程会锁住 uv 工具目录，使 --force 以 os error 32 失败；安装完成后再重启客户端。

1. 安装本地运行时

Windows PowerShell：

winget install --id=astral-sh.uv -e
uv tool install --python 3.12 --force "cad2gis[agent] @ https://github.com/Mola-maker/CAD2GIS/archive/refs/heads/main.zip"
cad2gis runtime install
Get-Command cad2gis-agent-mcp
cad2gis-agent-mcp --help
cad2gis doctor --deep --profile full --json

macOS：

brew install uv
uv tool install --python 3.12 --force "cad2gis[agent] @ https://github.com/Mola-maker/CAD2GIS/archive/refs/heads/main.zip"
cad2gis runtime install
command -v cad2gis-agent-mcp
cad2gis-agent-mcp --help
cad2gis doctor --deep --profile full --json

Linux：

curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
uv tool install --python 3.12 --force "cad2gis[agent] @ https://github.com/Mola-maker/CAD2GIS/archive/refs/heads/main.zip"
cad2gis runtime install  # 无 Homebrew 时从校验过的官方源码构建到用户缓存
command -v cad2gis-agent-mcp
cad2gis-agent-mcp --help
cad2gis doctor --deep --profile full --json

WSL 使用上面的 Linux 命令，但不把 WSL → Windows GUI 作为受支持的 AutoCAD/QGIS 会话控制通道。需要操控 Windows AutoCAD 或 Windows QGIS 桌面会话时，请在 Windows 原生 Codex/CLI 环境中安装运行时。

cad2gis-agent-mcp --help 验证插件实际调用的 console script 可以导入并启动。 cad2gis doctor --deep --profile full --json 会同时检查 MCP 入口、WebUI、 bundled GDAL/OGR、ezdxf 和 LibreDWG。 [agent] extra 的平台 wheel 提供 GDAL/OGR；cad2gis runtime install 把官方 LibreDWG CLI 安装到用户缓存（Windows），在 macOS/Linux 上优先复用 Homebrew， 否则从固定版本、固定 SHA-256 的官方源码进行无 root 构建。源码回退需要系统已有 C 编译器和 make；AutoCAD 与 Conda 都不是默认转换链路的前置条件。

2. 安装智能体客户端插件

Codex（Windows/macOS/Linux 命令相同）：

codex plugin marketplace add Mola-maker/CAD2GIS --ref main
codex plugin add cad2gis-agent@cad2gis
codex plugin list

Claude Code（Windows/macOS/Linux 命令相同）：

claude plugin marketplace add Mola-maker/CAD2GIS
claude plugin install cad2gis-agent@cad2gis-tools
claude plugin list

Cursor：

# Windows PowerShell
New-Item -ItemType Directory -Force .cursor | Out-Null
Invoke-WebRequest "https://raw.githubusercontent.com/Mola-maker/CAD2GIS/main/plugins/cad2gis-agent/clients/cursor.mcp.json" -OutFile ".cursor/mcp.json"

# macOS / Linux
mkdir -p .cursor
curl -fsSL "https://raw.githubusercontent.com/Mola-maker/CAD2GIS/main/plugins/cad2gis-agent/clients/cursor.mcp.json" -o .cursor/mcp.json

VS Code / GitHub Copilot agent mode：

# Windows PowerShell
New-Item -ItemType Directory -Force .vscode | Out-Null
Invoke-WebRequest "https://raw.githubusercontent.com/Mola-maker/CAD2GIS/main/plugins/cad2gis-agent/clients/vscode.mcp.json" -OutFile ".vscode/mcp.json"

# macOS / Linux
mkdir -p .vscode
curl -fsSL "https://raw.githubusercontent.com/Mola-maker/CAD2GIS/main/plugins/cad2gis-agent/clients/vscode.mcp.json" -o .vscode/mcp.json

Cursor/VS Code 模板通过 ${workspaceFolder} 自动使用当前工作区，无需填写机器 相关的绝对路径；下载后重启客户端。完整模板见 plugins/cad2gis-agent/clients。

3. 验证安装

先验证本地运行时，再验证正在使用的客户端。只使用 Codex 或 Claude Code 其中 一个时，不需要执行另一个客户端的列表命令。

cad2gis-agent-mcp --help
cad2gis doctor --deep --profile full --json
codex plugin list
claude plugin list

重启客户端并新建任务后，再让智能体调用 get_capabilities，确认 MCP 能力和 当前工作区授权目录已加载。完整 GIS 环境还应执行 cad2gis doctor --deep --strict --profile full --json 并确认 selected_profile_ready: true；这同时覆盖转换、MCP 与 Review WebUI。

4. 更新

Windows 上先停止 CAD2GIS MCP/WebUI 进程，再替换运行时。

# 运行时：同一条命令同时负责首次安装、更新和修复悬空 editable 安装
uv tool install --python 3.12 --force "cad2gis[agent] @ https://github.com/Mola-maker/CAD2GIS/archive/refs/heads/main.zip"
cad2gis runtime install

# Codex
codex plugin marketplace upgrade cad2gis
codex plugin add cad2gis-agent@cad2gis

# Claude Code
claude plugin marketplace update cad2gis-tools
claude plugin update cad2gis-agent@cad2gis-tools

若客户端显示 CONNECTION_CLOSED，且 cad2gis 或 cad2gis-agent-mcp 报 ModuleNotFoundError: No module named 'cad2gis'，不要手工修改 uv 的 .pth 或 插件缓存。直接重新执行上面的 uv tool install ... --force，再确认 cad2gis-agent-mcp --help 成功，最后重启客户端并新建任务。

Cursor 与 VS Code / Copilot 使用者请重新下载上面的动态工作区 MCP 模板。

5. 卸载

# Codex
codex plugin remove cad2gis-agent@cad2gis

# Claude Code
claude plugin uninstall cad2gis-agent@cad2gis-tools

# 本地运行时
uv tool uninstall cad2gis

安装、验证、更新、卸载或修改 MCP 配置后，请重启客户端并新建任务，使 skills 和 tools 从新会话边界加载。

架构

DWG reader (AutoCAD / LibreDWG / source-bound records)
  -> 不可变实体清单与样式、标签、曲线事实
  -> plan-domain 与 geometry-first 场景分区
  -> source-bound AI onboarding（只选择源中已观察到的标识）
  -> 确定性语义编译与精确 census gates
  -> 曲线、几何、拓扑、长度四类独立验证
  -> 单位与基础坐标操作 + 默认 OSM 相对平移匹配
  -> 人工控制点预览 -> 确认后二次匹配，生成新的 GIS 版本
     （显式 GCP 配准与 nominal 兼容路径仍可选）
  -> source.gpkg + evidence.gpkg + delivery.gpkg
  -> QML + evidence graph + run_manifest.json + run_status

AI 是控制平面的规划器，不是坐标或几何生成器。它可以完成实体清点、语义候选、 证据解释和 typed Decision Pack 提议；坐标、曲线、长度、变换参数、残差和交付 均由确定性代码计算和验证。

详细设计：

• ARCHITECTURE.md
• REGISTRATION_AND_SCENE_ARCHITECTURE.md
• LLM_AGENT_ARCHITECTURE.md
• ROBUSTNESS_VALIDATION.md

开发者安装

uv sync --extra agent --extra test
uv run cad2gis runtime install
uv run cad2gis doctor --deep --strict --profile full --json

需要复现传统原生 GIS 开发栈时，env/environment.yml 仍作为可选环境保留：

conda env create -f env/environment.yml
conda activate cad2gis
pip install -e ".[agent,test]"
cad2gis doctor --deep --strict --profile full --json

支持 Python 3.11–3.12。MCP、证据协议和 GeoPackage 交付结构跨 Windows、Linux、 macOS 一致；LibreDWG CLI 是默认 reader，AutoCAD/Core Console 仅是 Windows 上 显式选择的可选回退。安装后可直接使用 cad2gis-agent-mcp 启动 MCP 服务。

Windows 使用 AutoCAD reader：

$env:CAD2GIS_READER_BACKEND = "autocad"

新图纸的推荐流程

每个新 DWG 都必须建立自己的 source-bound profile 和 mapping registry：

cad2gis inspect "<SOURCE.dwg>" --json
cad2gis bootstrap "<SOURCE.dwg>" --project "<PROJECT_DIR>" --json

检查并完成生成的源配置与语义映射后，再验证和转换：

cad2gis validate --project "<PROJECT_DIR>" --json
cad2gis convert "<SOURCE.dwg>" `
  --project "<PROJECT_DIR>" `
  --run-dir "<NEW_RUN_DIR>" `
  --json

convert 和 auto-convert 默认使用 --matching osm。需要沿用标称坐标兼容流程时， 显式选择 --matching nominal；需要应用测量 GCP 配置时，显式传入 --gcp-profile "<GCP_PROFILE.json>"。标准 OSM 模式不会自动启用项目目录中发现的 GCP 文件。有效坐标域、地点提示或离线 OSM 快照提供匹配搜索参考；没有任何地理 参考的本地 CAD 仍需补充定位输入。自动匹配不确定但地域已知时，会保留待人工检查的粗定位。

使用 DeepSeek 自动完成受约束的 onboarding：

$env:DEEPSEEK_API_KEY = "<secret>"
cad2gis auto-convert "<SOURCE.dwg>" `
  --project "<PROJECT_DIR>" `
  --run-dir "<NEW_RUN_DIR>" `
  --provider deepseek `
  --force-bootstrap `
  --json

密钥不会写入项目、日志或 manifest。New API 聚合网关可通过 --provider new-api 及对应环境变量接入。

项目目录与期望产物结构

每张 DWG 对应 baselines/<项目>/ 下的一套 source-bound 产物，本工作区十个基线 即采用该结构：

baselines/<project>/
├── config/                        # 源绑定与语义映射，人工评审后冻结
│   ├── source_profile.json        # 源配置：CRS/CGEOCS、GEODATA 配准、单位与图层门槛
│   ├── mapping_registry.json      # 图层/实体 → 要素类映射与元素计数门禁
│   ├── spatial_regions.json       # 独立分区契约（如 Manado 的 EMR 面板）；无分区时缺省
│   ├── osm_anchor.json            # 可选：地点锚点，供缺少地理坐标的图纸定位
│   ├── matching-manual-gcp.json   # 可选：冻结的人工匹配 revision 记录
│   └── .osm-cache/                # 可选：Overpass 路网快照缓存（内容寻址命名）
├── run/                           # 标准转换 run；不存放任何 QGZ
│   ├── source.gpkg                # 原生 CAD 事实快照
│   ├── evidence.gpkg              # 证据层
│   ├── delivery.gpkg              # 交付几何与属性（权威字节，打包后字节不变）
│   ├── osm_matching.json          # OSM 匹配记录：status/revision/translation/search_bbox
│   ├── run_manifest.json          # 运行状态与全部产物的 SHA-256
│   ├── qgis/styles/*.qml          # 每图层 QML 与 style_manifest.json
│   ├── svg-candidates/            # 源 SVG 候选：correspondence.{json,html}、selection.json、
│   │                              # manifest.json、index.html、symbols/、symbols.sqlite3
│   ├── reasoning/                 # cad_scene_graph.json、evidence_graph.json.gz、
│   │                              # evidence_index.sqlite3、visual/（分块渲染与命中索引）
│   └── <PARTITION>/               # 独立分区 run：delivery.gpkg、partition_manifest.json、qgis/
├── run.review/                    # 使用 Web 工作台后才出现
│   ├── review.sqlite3             # 人工控制点 revision store
│   ├── matching-active.json       # 当前生效匹配版本的指针
│   └── matching/r<N>-<uuid>/      # 每轮二次匹配：match-profile.json、controls.json、run/
└── delivery/                      # 便携交付包，QGZ 与其 GeoPackage 成组存放
    ├── <6 个文件>                 # 标准 run 的交付
    ├── r<N>/<6 个文件>            # 人工复核 revision 的交付（cad2gis publish-match）
    └── <PARTITION>/<6 个文件>     # 分区交付，与主体同构

交付包固定为六个文件：delivery.gpkg、delivery.qgz、delivery.review.json、 osm-basemap.gpkg、view-with-source-SVG.qgz、view-with-source-SVG.review.json。 delivery.gpkg 与对应 run 的字节完全一致，QML/SVG 只是呈现层，不改写数据库值与几何精度。 原始 DWG 不进入项目目录，保存在仓库 raw/ 下；run/ 与 run.review/ 永不存放 QGZ 交付文件。

长度语义

CABLE_SEGMENT 同时保留三种不同含义的长度：

• source_native_length_m：DWG 源曲线长度；
• measurement_native_m：匹配到的独立 DWG DIMENSION 数值；当 DWG 标注文本存在时使用渲染后的标注值（例如黄色整数 50 m），而不是 act_measurement 的未舍入小数；
• source_cad_length_m：CABLE_SEGMENT 的名义源长度——有 DIMENSION 时等于标注值，无 DIMENSION 时回退为不可变 CAD 曲线长度；
• delivery_grid_length_m / geodesic_length_m：坐标转换后的网格与椭球长度。

没有 DIMENSION 时，线段仍然具有可靠的 CAD 曲线长度，measurement_state=cad_geometry_only， 但 QGIS 中不显示任何长度标签：原图没有标注的跨度不会被补上系统发明的文字。 尺寸匹配采用：

1. 精确线段端点；
2. 尺寸端点与缆线端点落在同一对唯一支撑设施上。

第二种规则解决真实 CAD 中尺寸延伸线与缆线端点存在偏移的问题，并保留完整 rule/provenance。

Web 配准、坐标传送与审查

cad2gis review "<RUN_DIR>" --workspace "<REVIEW_DIR>" --port 8765

打开 http://127.0.0.1:8765/：

1. 右图先显示当前已应用的 GIS 匹配结果，与 OSM 底图对照；
2. 左图点击 CAD 实体，系统吸附到真实几何；右图点击同一位置，或输入 EPSG:4326 经度/纬度；
3. 保存至少两个位置不同的训练点后查看人工平移校正预览。独立检查点只评估残差， 不参与拟合；足够且分布合理的检查点有助于识别局部偏差；
4. 确认预览后点击“二次匹配并生成新结果”，由正式转换管线创建新的 GIS；
5. 完成后自动加载新结果，保留控制点；可继续修改、预览和再次匹配；
6. 复核版交付用 cad2gis publish-match "<新RUN_DIR>" 发布，见 QGIS 交付。

工作台会显示本次保存的匹配配置和可复制转换命令。每轮从原始 CAD 坐标及同一 基础坐标操作重新计算总平移，避免反复叠加前一轮偏移。独立图框分别匹配； 从某个分区发起的人工校正只生成该分区的新交付。失败时继续保留当前结果和控制点。

界面还提供 ?demo=1 合成交互模式，用于公开展示图层开关、CAD 几何吸附和 坐标传送，不读取或上传真实 DWG，也不会伪装成已执行转换。例如： http://127.0.0.1:8765/?demo=1。真实产物仍必须由本地 CLI/MCP 流水线生成。

公开的合成演示由 GitHub Pages 发布： ULTRA CAD2GIS Web Demo。该页面只含 demo-fixture.js 中的合成对象；真实 CAD/GIS 处理仍在本地运行。

左侧 ToC 将源事实、语义映射、空间配准、独立校验和 GIS 交付分开显示；右侧 “证据 / 控制台 / AI 协作”标签只记录有效审查动作，并提供目标坐标、转换命令和 受约束 AI 提示词的复制功能。

人工选点只写独立 revision store 并更新预览；确认二次匹配会创建新的 run， 原始 CAD 与之前的 delivery GeoPackage 保持不变。OSM 控制点的精度类别固定为 RELATIVE_OSM_REFERENCE_ONLY；若要证明绝对精度，必须替换为测量或权威控制点。 复制或归档 run 后，服务只接受 SHA-256 与 manifest 完全一致的同目录产物；若 原 DWG 或绑定配置不可用，则允许查看已有结果，二次转换需先恢复对应输入。

MCP 与主流智能体

MCP 服务支持标准 stdio 和 Streamable HTTP：

# stdio（通常由智能体自动启动）
cad2gis-agent-mcp --transport stdio

# 本机 Streamable HTTP
python -m cad2gis.agent_mcp `
  --transport streamable-http `
  --host 127.0.0.1 `
  --port 8768

HTTP endpoint 为 http://127.0.0.1:8768/mcp。默认只允许本机 loopback； 网络部署必须增加认证反向代理。

Claude Code、Cursor、VS Code/GitHub Copilot、Codex 和通用 HTTP 客户端模板位于 plugins/cad2gis-agent/clients。服务暴露 get_capabilities，智能体可先读取转换边界、transport 和精度声明，再调用 inspection、onboarding、conversion、evidence、repair 与 review 工具。 转换完成后调用 audit_run，可校验每个产物的 SHA-256、实际 GeoPackage 图层 计数与 manifest census 是否一致，并单独报告源 DWG 是否仍可重放。

MCP 只能访问客户端工作区或显式授权根目录中的文件。通常无需配置；只有需要授权 工作区外的数据目录时才设置：

$env:CAD2GIS_PROJECT_ROOTS = "D:\survey-data;D:\shared-cad"

QGIS 交付

需要排查底图偏移时，可使用独立的 QGIS / OSM 复核入口， 为工程加入离线参考底图并生成真实 QGIS 快照。原图坐标标注约束的可选校正只应用于复核工程显示，不改写原始数据库或长度，也不代替测量控制点验收。

复核版交付（delivery/r<N>/）

Web 工作台二次匹配产生的新 run 不是标准 run，其便携交付按版本发布在项目 delivery/ 下，标准 run 的交付仍在 delivery/ 根，两者互不覆盖：

# RUN_DIR 位于 <PROJECT_DIR>/run.review/matching/r<N>-<uuid>/run 时自动推导交付目录
cad2gis publish-match "<RUN_DIR>"

# 其他位置需显式指定
cad2gis publish-match "<RUN_DIR>" --delivery-root "<PROJECT_DIR>/delivery"

• 版本目录名取自该 run 的 osm_matching.revision（r2、r3……）；已存在的版本目录会被拒绝，不覆盖旧版本。
• 每个版本目录与标准交付同构：delivery.gpkg（与 run 字节一致）、delivery.qgz、 delivery.review.json、osm-basemap.gpkg、view-with-source-SVG.qgz、 view-with-source-SVG.review.json；分区图纸的面板交付位于 delivery/r<N>/<分区>/。
• SVG 符号绑定取自 run 的 svg-candidates；OSM 底图按各 scope 的要素范围获取， 也可用 --osm-data "[SCOPE=]PATH" 复用已复核的 Overpass JSON 快照（离线环境或分区各一份）。
• 该步骤需要能 import qgis.core 的解释器，依次尝试 --qgis-python、环境变量 CAD2GIS_QGIS_PYTHON、当前解释器、/usr/bin/python3。
• 转换 run 与 review 工作区都不存放 QGZ 交付文件：发布过程在系统临时目录完成组装， 成功后原子改名入库，失败即清理，不留半成品。

成功 run 包含：

• source.gpkg
• evidence.gpkg
• delivery.gpkg
• QML 与 style manifest
• evidence graph 与视觉索引
• run_manifest.json

在 QGIS 中可直接拖入 delivery.gpkg，或通过“数据源管理器 → GeoPackage”连接。 加载随包生成的 QML 后可恢复 CAD 图层颜色、线型、点符号和标签。

精度边界

系统分别报告：

• reader/source record fidelity；
• geometry/curve fidelity；
• topology 与 cable segment conservation；
• CAD 曲线长度与独立 DIMENSION 覆盖；
• nominal CRS transformation；
• OSM 相对匹配状态、版本、来源与人工校正残差；
• GCP train residual 与独立 check-point 精度。

$INSUNITS 是块插入缩放提示，不自动等同于 WCS 坐标单位。当 DWG 的 CGEOCS 明确绑定投影 CRS 时，其线性轴单位控制 WCS→米的尺度，避免把 UTM 坐标错误缩小 1000 倍。

外部 E:\branch_CAD2GIS\APD_test 仅是兼容性压力输入，不是训练集、规则模板或 准确率真值。同理，外部语料中新增的 6 张 APD（As Plan Drawing）验证图也必须 各自建立 source-bound profile，不得沿用四张开发基线图的规则或数量门禁。 没有 authoritative GCP 的结果必须保持 CONDITIONAL 或 not independently verified。

验证

python -m pip install -e ".[agent,test]"
python -m pytest -q

$env:CAD2GIS_FULL_DWG_TESTS = "1"
python -m pytest tests/test_apd_test_compatibility.py -q

仓库 CI 在 Ubuntu/Python 3.11、Ubuntu/Python 3.12、Windows/Python 3.12 和 macOS/Python 3.12 上安装 agent 依赖与锁版 LibreDWG runtime， 再分别执行安装、锁版 Ruff、Python 编译、WebDemo JavaScript 语法、MCP/插件 契约和完整 pytest 回归。Pages CD 会重新验证浏览器契约，使用 scripts/build_pages.py 构建 _site。合成演示与用户授权的派生九图演示分开校验。 九图、QGZ 和 SVG 复验包来自 docs/derived-release.json 指定的 Release，下载后检查 大小、SHA256、目录边界和完整文件清单；原始 DWG/DXF 不进入公开站点。

仓库目录：

• src/cad2gis/：唯一生产实现、CLI、reader、MCP、review server
• tests/：自动化契约与回归测试
• baselines/：source-bound 基线配置；大型 GeoPackage/清单证据可作为外部语料挂载
• 原始 DWG 与生成输出放在仓库外，通过显式路径或批量输入契约挂载
• experiment/config/：APD reviewed 兼容配置，不含原始图纸
• plugins/cad2gis-agent/：智能体插件和 MCP 客户端模板
• docs/：架构、鲁棒性、可移植性、术语与对账说明
• env/：固定 GIS 运行环境

本地重建包含九图的 Pages：先运行 python scripts/fetch_derived_release.py，再运行 python scripts/build_pages.py --output _site。pages-delivery/ 是忽略的下载缓存， 只提交核心源码、必要测试配置、文档和小型发布清单。