运行 CAD2GIS-0.7.0-windows-x64-setup.exe（位于 dist/windows/）。
默认安装到 %LOCALAPPDATA%\Programs\CAD2GIS，无需管理员权限；可选桌面快捷方式与「添加命令到用户 PATH」（PATH 项供既有智能体插件使用）。
从开始菜单打开 CAD2GIS：启动本地服务并用系统浏览器打开专用登录链接。

运行库检查（验证命令，逐字）

cad2gis doctor --deep --strict --profile full --json

桌面启动日志：%LOCALAPPDATA%\CAD2GIS\logs · 开发包尚无 Authenticode 生产签名

免安装器的 uv 运行时路径（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

向 Android 提供 HTTPS 服务（逐字，需替换路径/域名/密码）

$env:CAD2GIS_APP_PASSWORD = '<至少12字符的服务密码>' cad2gis-desktop --no-browser --host 0.0.0.0 --port 8765 ` --public-host cad.example.com ` --project-root 'D:\CAD Projects' ` --ssl-certfile 'D:\Certificates\fullchain.pem' ` --ssl-keyfile 'D:\Certificates\privkey.pem'

详见第 10 章 Android 连接

CHAPTER 02 · 安装 · LINUX

DEB、便携包，或一条 uv 命令

出处：docs/INSTALL_LINUX.md（面向 Ubuntu 24.04 x86_64，glibc 2.39+）、README。

.deb 安装 + 校验（逐字）

sha256sum --check SHA256SUMS --ignore-missing sudo apt install ./cad2gis_0.7.0_amd64.deb

打开：应用菜单打开 CAD2GIS，或运行 cad2gis-desktop · 卸载 sudo apt remove cad2gis（不删项目与用户设置）

免管理员便携方式

解压 cad2gis-0.7.0-linux-x86_64.tar.gz 到自有目录，运行解压目录里的 bin/cad2gis-desktop；运行库检查（逐字）：

bin/cad2gis doctor --deep --strict --profile full --json

便携包要求系统已有 libstdc++6、libgomp1、CA 证书与可用字体

安装后完整验证（用安装目录自带 Python，逐字）

/opt/cad2gis/runtime/bin/python3 -I -B packaging/linux/verify_install.py \ --bundle /opt/cad2gis --output tmp/linux-installed-verification

智能体插件环境变量与 MCP 入口（逐字）

export CAD2GIS_PROJECT_ROOTS="$HOME/CAD-projects" cad2gis-agent-mcp --transport stdio

插件位于 /opt/cad2gis/plugins/cad2gis-agent，可执行入口装到 /usr/bin；多个项目根目录用冒号分隔

README 的 uv 路径（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

可选 Redis 缓存。从安装包根目录启动 Compose，并为后端设置 CAD2GIS_REDIS_URL=redis://127.0.0.1:16379/0（默认 TTL 120 秒；未配置时直接用 SQLite）。

CHAPTER 03 · 首个转换

inspect → bootstrap → validate → convert

出处：README「新图纸的推荐流程」。每个新 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

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

使用 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

已有验证通过的项目配置时的最短命令（逐字）

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

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

CHAPTER 04 · OSM 路网匹配

参数、四态与模型约束

出处：docs/OSM_STANDARD_MATCHING.md。动态过程演示见子页 1 · 路网匹配与人工校验。

标准流程只有一条：OSM 自动匹配 → SVG 图例候选提取 → 查看 GIS 与候选 → 人工控制点预览 → 确认后二次匹配 → 自动加载新结果。交付记录 authority: relative_osm、absolute_accuracy_verified: false；地图重合/小残差/高自动分数均不代表测量级绝对精度。

参数表（逐字）

参数	用途
`--matching osm`	默认标准模式：尝试 OSM 相对匹配。
`--matching nominal`	使用原标称坐标兼容流程，保留其现有验证要求。
`--osm-data "<OVERPASS.json>"`	使用离线 Overpass 道路快照。
`--osm-place "<PLACE_NAME>"`	显式指定地点搜索地域，优先于标称坐标推定的在线范围。
`--match-profile "<SAVED_MATCH_PROFILE.json>"`	使用完整、原样保存的匹配记录，重放同一基础坐标操作和匹配平移。
`--gcp-profile "<GCP_PROFILE.json>"`	显式使用已有 GCP 校准流程，仍须满足其训练、检查与精度验证要求。
`--svg-mode candidate`	默认提取原图 SVG 与图例对应候选；不自动应用到交付样式。
`--svg-mode off`	显式关闭 SVG 提取；不传字体目录。
`--svg-font-dir "<FONT_DIR>"`	SVG 提取所用的原图字体目录，可以重复指定。

匹配状态四态（逐字表）

状态	含义与下一步
`matched`	自动网络匹配通过相对匹配门槛，或已计算人工平移；仍需核对地理对应关系。
`coarse`	地域可用，但道路不足、网络拟合较弱或存在多解；保留粗定位以供人工校正。
`unavailable`	缺少可用匹配输入或可匹配路线；有可信标称坐标时可查看其结果，本地 CAD 需补充定位输入。
`abstained`	自动候选未获接受；查看诊断并补充参考，不应把候选解释为已确认匹配。

互斥规则。--matching nominal 不能与 OSM 输入混用；--match-profile 不能同时传入新 --osm-data、--osm-place 或 --gcp-profile。不要手动编辑匹配记录（摘要绑定源文件、CRS、单位、基础操作、版本与道路快照，改动导致校验失败）。

匹配模型说明。基础坐标操作（单位、必要投影转换、Web Mercator 比例）+ 一个总平移；不自动旋转、不拉伸/仿射/橡皮片变形、不沿 OSM 道路逐点吸附缆线；每轮迭代均从原始 CAD 坐标重新计算。独立图框分别匹配，分区控制点平移不应用到其他图框。服务配置环境变量：CAD2GIS_NOMINATIM_URL、CAD2GIS_OVERPASS_URL、CAD2GIS_OSM_USER_AGENT；公共 Nominatim 要求 ≤1 请求/秒。OSM 数据需保留 © OpenStreetMap contributors 署名及 ODbL 信息。

CHAPTER 05 · SVG 符号提取

candidate 模式：三产物，不自动应用

出处：docs/OPTIONAL_SYMBOL_ASSETS.md。真实符号画廊与内嵌证据见子页 2 · SVG 提取与渲染。

SVG 提取是标准转换流程的一部分，默认 candidate 模式。convert、auto-convert、Python convert_project、MCP run_conversion/auto_onboard_and_convert 与批量入口都在 <run>/svg-candidates/ 生成三个产物：

symbols.sqlite3（候选数据库：SVG、SHA-256、原图 SHA、实体 handle、定义依赖与诊断；symbol_id 主键）
correspondence.json（JSON 报告）
correspondence.html（并排复核页）

候选与 GIS 完整生成后原子发布；提取失败不发布半成品 run，已有 run 保留。候选不自动应用到交付 QML 或 GIS 业务数据；reviewed 模式尚未开放。

独立运行（不依赖转换，逐字）

python -m cad2gis.symbol_assets extract --source drawing.dwg --selection selection.json --output symbol-review-v1 python -m cad2gis.symbol_assets qml --store symbol-review-v1/symbols.sqlite3 --symbol-id pole-source-candidate --output pole-candidate.qml --size-mm 6

也可用 tools/extract_svg_symbols.py，或安装后的 cad2gis-symbols

选择配置示例（必须绑定实际源文件 SHA-256 与实际 handle）

{ "source_sha256": "<DWG 文件的完整 SHA-256>", "symbols": [ {"symbol_id": "pole-source-candidate", "label": "原图杆型候选", "handles": ["<实际 handle>"]} ] }

脚本拒绝错误源 SHA、找不到的 handle、重复 ID、覆盖已有输出和被修改的 SVG · 缺字体 Linux 环境提供 --font-dir /path/to/fonts（可重复）；无字体时拒绝提取含文字的符号

人工绑定到 QGZ（逐字，需 PyQGIS 环境）

python tools/package_qgis_standalone.py --project delivery/EMR29619/delivery.qgz --output EMR29619-standard.qgz python tools/package_qgis_standalone.py --project delivery/EMR29619/delivery.qgz --output EMR29619-with-SVG.qgz --store source-symbols/symbols.sqlite3 --bindings bindings.json --delivery-manifest delivery/delivery-manifest.json

[{"layer": "PTECH", "source_handle": "7943", "symbol_id": "ptech-7943"}]

cad2gis-svg-delivery --baseline <完整交付目录> --assets <候选目录> --output <新目录> python tools/verify_qgis_standalone.py --project output.qgz --output verification

生成后必须退出进程再独立复验（可加 --font /path/to/font.ttf）· 实现亦随核心包发布：python -m cad2gis.qgis_package / qgis_verify / svg_delivery，安装命令为 cad2gis-qgis-package / cad2gis-qgis-verify / cad2gis-svg-delivery

CHAPTER 06 · 审查与 GCP 微调

六步操作流与 0.01 m 步长

出处：README「Web 配准、坐标传送与审查」、OSM_STANDARD_MATCHING §2、UPGRADE_0_6_0「第一次使用」。交互演示见子页 1 · 路网匹配与人工校验。

启动审查工作台（逐字）

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

打开 http://127.0.0.1:8765/ · 界面提供 ?demo=1 合成交互模式（不读取/上传真实 DWG）

逐步操作（逐字转录）

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

微调与撤销。选中控制点后可按 0.01 / 0.1 / 1 m 向东、西、南、北微调，并撤销或恢复最初选点；保存控制点后先看预览与残差，再生成新的 GIS run。0.01 m 是操作步长，不是厘米级绝对精度承诺。

关键说明。保存控制点只更新审查工作区与预览；预览由服务端用正式匹配变换计算；转换期间控制点编辑被锁定；过期匹配版本提交会被要求刷新；失败时保留当前结果与控制点。OSM 控制点精度类别固定为 RELATIVE_OSM_REFERENCE_ONLY。

CHAPTER 07 · 二次匹配

冻结本轮 → 正式转换 → 新目录不覆盖

出处：OSM_STANDARD_MATCHING §3。

确认预览后点击 「二次匹配并生成新结果」。服务冻结本轮人工点与匹配记录，检查源文件、原始配置和当前匹配版本，再运行正式转换。

成功后工作台自动加载新 GIS，显示新匹配版本，保留人工点供下一轮修改。
已发布 run 不可覆盖；每次转换使用新目录，保留前一版结果与来源记录。
二次匹配沿用本轮 SVG 模式和字体目录，为新 GIS 重新生成候选，候选与新数据库哈希绑定一起更新；新 run SVG 提取失败时当前 GIS 与旧候选保留。
控制台显示本次匹配配置路径、结果位置和可复制的转换命令；重开同一审查工作区可恢复当前匹配结果。

分区。用 cad2gis review "<PARTITION_RUN_DIR>" 打开某个已有分区；该分区二次匹配只发布该区域新交付。

CHAPTER 08 · QGIS 交付

publish-match 与固定六文件

出处：README「QGIS 交付」。首开验证截图见子页 2 与子页 4。

发布复核版交付（逐字）

# 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"

版本目录名取自 osm_matching.revision（r2、r3……）；已存在版本目录被拒绝，不覆盖旧版本。
需要能 import qgis.core 的解释器，依次尝试 --qgis-python、环境变量 CAD2GIS_QGIS_PYTHON、当前解释器、/usr/bin/python3。
可用 --osm-data "[SCOPE=]PATH" 复用已复核的 Overpass JSON 快照。

交付包固定六文件

文件	说明
`delivery.gpkg`	与对应 run 字节完全一致
`delivery.qgz`	QGIS 工程
`delivery.review.json`	审查记录
`osm-basemap.gpkg`	OSM 底图快照
`view-with-source-SVG.qgz`	内嵌源 SVG 视图
`view-with-source-SVG.review.json`	SVG 视图审查记录

在 QGIS 中打开。直接拖入 delivery.gpkg，或通过「数据源管理器 → GeoPackage」连接；加载随包 QML 后恢复 CAD 图层颜色、线型、点符号和标签。成功 run 包含：source.gpkg、evidence.gpkg、delivery.gpkg、QML 与 style manifest、evidence graph 与视觉索引、run_manifest.json。

CHAPTER 09 · MCP 智能体

50 个工具，先读能力再动手

出处：README「MCP 与主流智能体」、「1. 安装本地运行时 / 2. 安装智能体客户端插件」。

传输方式（逐字）

# 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，网络部署必须增加认证反向代理

客户端插件安装（逐字）

# Codex codex plugin marketplace add Mola-maker/CAD2GIS --ref main codex plugin add cad2gis-agent@cad2gis codex plugin list # Claude Code claude plugin marketplace add Mola-maker/CAD2GIS claude plugin install cad2gis-agent@cad2gis-tools claude plugin list

Cursor / VS Code：下载 plugins/cad2gis-agent/clients 下的 cursor.mcp.json / vscode.mcp.json 到 .cursor/mcp.json / .vscode/mcp.json（模板用 ${workspaceFolder}，无需绝对路径），重启客户端

使用要点

服务暴露 get_capabilities，智能体先读取转换边界、transport 和精度声明，再调用 inspection、onboarding、conversion、evidence、repair、review 工具；转换完成后调用 audit_run 校验每个产物 SHA-256、GeoPackage 图层计数与 manifest census。

目录授权（需要授权工作区外数据目录时，逐字）

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

边界。MCP 只能访问客户端工作区或显式授权根目录中的文件。Python convert_project 与 MCP run_conversion 同样提供 matching、osm_data、osm_place、match_profile 参数，并与 auto_onboard_and_convert 共享 svg_mode、svg_font_dirs；两个 MCP 转换工具返回 svg_candidates。

CHAPTER 10 · Android 连接

手机是客户端，不是转换器

出处：docs/CONNECT_ANDROID.md。Android 安装包是服务器客户端——手机负责登录、浏览图纸和查看审查地图；DWG 读取、OSM 匹配、SVG 提取与二次匹配由 Windows/Linux 服务端执行。

1 · 准备服务端

管理员准备手机可达域名、与域名匹配且被 Android 系统信任的 HTTPS 证书、≥12 字符服务密码；可用同一局域网，不要求公共云。Linux 启动示例（逐字）：

export CAD2GIS_APP_PASSWORD='替换为至少12字符的服务密码' cad2gis-desktop --no-browser --host 0.0.0.0 --port 8765 \ --public-host cad.example.com \ --project-root '/srv/cad-projects' \ --ssl-certfile '/etc/cad2gis/fullchain.pem' \ --ssl-keyfile '/etc/cad2gis/privkey.pem'

服务只访问 --project-root 指定目录（可重复）；--public-host 必须与手机地址主机名一致

2 · 安装并连接手机

安装 CAD2GIS-0.4.0-android-dev.apk（开发测试签名）→ 打开应用点「服务器」填 https://cad.example.com:8765 → 用服务密码登录。要求 Android 8.0+ 与 Android System WebView 83+。

3 · 使用匹配结果

标准转换生成 OSM 相对匹配与 SVG 候选；人工控制点先预览，确认二次匹配才生成新 GIS，原结果保留。

常见异常。地址须为 HTTPS 服务根地址；证书错误不跳过（只信任系统证书）；无图纸则把 DWG 放入管理员授权目录；切换服务器会清除旧登录状态（正常行为）。

版本命名说明。APK 文档版本 0.4.0 与桌面 0.7.0 存在命名差异，以 repo 实际交付 0.7.0 为准。

CHAPTER 11 · 术语

读图之前先读词

出处：README「术语」、docs/GLOSSARY.md（项目权威术语表）。图纸层名与要素类的完整定义以 GLOSSARY 为准。

术语	含义
APD	As Plan Drawing（按计划图纸）：记录 as-planned 设计，非 as-built 竣工实测；APD 几何是权威设计计划，精度声明须区分「计划图纸」与「地面验证」。
SF	Subfeeder（副馈线/分支配电线）；文件名 `- SF` 后缀表示该图是网络的 subfeeder 部分。
FTTH	Fibre To The Home（光纤到户）。
BOITE	交付要素类：分线盒。
SITE	交付要素类：站点围封。
PTECH	交付要素类：杆/支撑设施。
IMB / CABLE / ZPM / ZNRO	九图交付中出现的图纸层名/要素类名；权威定义见仓库 docs/GLOSSARY.md，本手册不另行转译。

CONDITIONAL。全部交付的精度声明永久封顶 CONDITIONAL / not independently verified：通过源几何/拓扑/长度门禁不授权任何绝对地图精度声明；authority: relative_osm、absolute_accuracy_verified: false；地图重合、小残差、高自动分数均不代表测量级绝对精度。直到测量级控制点出现，这个词不会变。

语料划分原则。开发/基线集（4 DWG）与验证集（6 DWG）的语料划分属内部研发约定；面向用户只有一条原则：每张新图独立建 source-bound 配置，不得复用基线规则或数量门禁。