CAD2GIS

CAD2GIS · AI エージェント向け CAD → GIS

DWG/DXF を確認可能な GIS に変換し、AI エージェントが CAD のコピーを検査・編集して、QGIS プロジェクトを納品できるようにします。

公式サイト · 9 枚の画像による効果紹介 · インストールガイド · リリース · English · バイリンガル Wiki

CAD2GIS は、ソースエンティティ、意味マッピング、ジオメトリ、トポロジ、長さ、座標の証拠を、再実行可能なワークフローでつなぎます。 CLI、Python API、レビュー用ワークベンチ、cad2gis-agent MCP プラグインは、同じ変換パイプラインを使用します。 CAD/GIS エンジニアに加え、Codex、Claude Code、Cursor、VS Code を使うエージェントワークフローにも適しています。

0.8.0 でできること

機能	入口と条件
DWG/DXF ソースの検査	DWG ではマネージド LibreDWG を使用します。DXF は CLI/API/MCP でネイティブに読み込み、エンティティの handle、ブロック、属性、ソースハッシュを保持します
CAD → GeoPackage	意味、単位、CRS を確認してから変換します。ジオメトリ、トポロジ、長さ、位置の受け入れ証拠を出力します
CAD のコピー編集	オプションの独立したオープンソース CAD ランタイムを使用できます。4 つの MCP 入口から、実機テスト済みの CAD ツール 15 個を制御して呼び出します
OSM と GCP の位置合わせ	OSM 相対マッチング、スナップショットの固定、手動コントロールポイント、再マッチングに対応します。絶対精度の確保には、信頼できるコントロールとチェックポイントが必要です
QGIS 納品	GeoPackage、QGZ/QML、SVG 比較資料、検証チェックリストを提供します。独立したレンダリング検証には QGIS ランタイムが必要です
複数エージェントの接続	Codex/Claude Code のリポジトリマーケットプレイス、および Cursor/VS Code の標準 MCP 設定

サイドチャネルでは U-C4N/Autocad-MCP の MIT ライセンスの ヘッドレス DXF エンジンを固定で使用します。これは別途インストールします。コピーのみを編集し、結果は CAD2GIS に戻して受け入れ検査を行います。 詳しくは CAD 機能とインストールを参照してください。

まずは効果を確認

9 枚の画像、レイヤー、処理手順を確認。 紹介内容は既存の Pages コンテンツを再利用しています。9 枚の画像の結果は引き続き CONDITIONAL であり、測量レベルの絶対位置精度は検証されていません。 図面に CRS が記載されていることや、見た目が重なることだけでは、位置の正確さを証明できません。

エージェントへの 3 ステップ接続

まず 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 ランタイムが必要です。

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 設定テンプレートを使用してください。 エージェントには、まず get_capabilities、get_runtime_status、inspect_source を実行させてください。 オプションの CAD 編集では、別途 get_cad_bundle_status を呼び出し、サイドチャネルのリファレンスに従ってインストールしてください。

ダウンロードとバージョン

0.8.0 は今回の Python/Agent ソースリリースです。デスクトップインストーラーは、それぞれの実際のバージョンで提供します。

プラットフォーム	ダウンロード可能なバージョン
Windows x64	0.7.8 インストーラー
Linux x86_64	0.7.0-3 .deb · ポータブルパッケージ
macOS Apple Silicon / Intel	0.7.0 インストーラー

Linux のインストール要件はインストール手順を参照してください。プレリリースには、明示されたバージョンのリンクを使用してください。 旧インストーラーには、元のライセンスと検証範囲が適用されます。Apache-2.0 は今回の新版に含まれる独自コードに適用されます。

ドキュメントと参加

プラグインガイド · 貢献ガイド · 問題の報告 · 発見・配布チャネル · OSM マッチング · SVG と QGZ · 複数地区の検証 · Docker

独自コードは Apache-2.0 を採用しており、商用利用、改変、再配布が可能です。 サードパーティコンポーネントと顧客の図面は、それぞれの権利が適用されます。NOTICEを参照してください。 合成図面または公開共有可能な図面を使った再現例や新しいワークフローの投稿を歓迎します。公開 issue に顧客の元図面をアップロードしないでください。

---

用語

• APD = As Plan Drawing：建築分野における「計画図」です。記録されているのは 計画時点の設計であり、竣工後の実測ではありません。また、「アクセスポイント機器」を意味するものでもありません。
• SF = Subfeeder：光ケーブル／ケーブルネットワークの副フィーダー／分岐配電線です。ファイル名にある - SF は、その図面がネットワークの subfeeder 部分であることを示します。
• 外部コーパスに含まれる DWG 4 枚はアルゴリズムのワークフローを確立するための開発／ベースラインセットで、後から追加された 6 枚は 検証セットです。各図面を個別に source-bound として扱う必要があり、ベースラインのルールや数量のゲートを再利用してはいけません。

完全な定義と 2 つの一覧については、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 は出力しません。

以下のコマンドはリポジトリを先にクローンする必要はありません。まず、各 OS に同じポータブルな cad2gis-agent-mcp 制御プレーンランタイムをインストールし、その後、エージェントクライアントにプラグインを登録します。インストールコマンドでは完全な Git 履歴ではなく main.zip を使用し、--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 エージェントモード：

# 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 は制御プレーンのプランナーであり、座標やジオメトリの生成器ではありません。エンティティの棚卸し、セマンティック候補の提示、根拠の説明、型付き 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/ 是忽略的下载缓存， 只提交核心源码、必要测试配置、文档和小型发布清单。