CAD2GIS

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 " " --workspace " " --port 8765

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

convert、auto-convert、MCP 和批量转换默认使用 svg_mode=candidate，在 /svg-candidates/ 保存 symbols.sqlite3、correspondence.json 和 correspondence.html。SVG 与 GIS 完整生成后一起发布；提取失败时不发布新 run， 已有结果保留。候选只供复核，不会自动替换交付样式。原图需要指定字体时可重复使用 --svg-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 " " --project " " --json

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

cad2gis validate --project "<PROJECT_DIR>" --json

cad2gis convert "<SOUR