DOCS / 03 · TERMINAL & CLI

终端与 CLI

一条命令安装，一条命令体检，四条命令完成首个转换。下面是一台真实的终端：四章剧场演示完整使用旅程；其后是本仓库全部公开命令的逐字总表与七参数卡。

命令逐字转录自仓库文档（README / INSTALL_WINDOWS / INSTALL_LINUX / OSM_STANDARD_MATCHING / OPTIONAL_SYMBOL_ASSETS），尖括号 <...> 为需替换的本地路径/值；终端输出为真实流程的精简重放，未虚构任何能力。

§1 · 终端剧场

四章：从安装到智能体

打字机重放真实命令流。可播放 / 暂停 / 倍速 / 章节跳转。CH2 收尾的 run_status: CONDITIONAL 是全站最重要的一个词。

§2 · 命令参考总表

全部公开命令，七组逐字收录

这是「最完整使用说明」的命令层。每条命令逐字转录，出处挂在组标题后。

① 安装 · Windows（README「1. 安装本地运行时」/ INSTALL_WINDOWS）

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

免安装器的 uv 运行时路径 · 安装包自带 Python 3.12、GIS 库与 LibreDWG，无需先装 Python/uv/AutoCAD/Conda/QGIS

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

安装器方式的运行库检查 · 桌面启动日志：%LOCALAPPDATA%\CAD2GIS\logs

② 安装 · Linux（INSTALL_LINUX / README）

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

.deb 安装 + 校验（Ubuntu 24.04 x86_64，glibc 2.39+）· 卸载 sudo apt remove cad2gis 不删项目与用户设置

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

免管理员便携方式的运行库检查 · 便携包要求系统已有 libstdc++6、libgomp1、CA 证书与可用字体

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

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

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

README 的 uv 路径（Linux）

③ 转换（README「新图纸的推荐流程」/ OSM_STANDARD_MATCHING）

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

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

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

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

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

使用 DeepSeek 自动完成受约束的 onboarding · 密钥不写入项目、日志或 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

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

④ OSM 参数（OSM_STANDARD_MATCHING）

cad2gis convert "<SOURCE.dwg>" --project "<PROJECT_DIR>" --run-dir "<OFFLINE_RUN_DIR>" --osm-data "<OVERPASS.json>" --json

离线道路快照：接收已保存的 Overpass JSON · 道路匹配无需在线 OSM，但 Web 工作台 OSM 栅格底图仍需浏览器联网

cad2gis convert "<SOURCE.dwg>" --project "<PROJECT_DIR>" --run-dir "<PLACE_RUN_DIR>" --osm-place "<PLACE_NAME>" --json

显式地点提示：地点应足够具体；地点中心只提供粗定位

cad2gis convert "<SOURCE.dwg>" --project "<PROJECT_DIR>" --run-dir "<NOMINAL_RUN_DIR>" --matching nominal --json

标称坐标兼容流程

cad2gis convert "<SOURCE.dwg>" --project "<PROJECT_DIR>" --run-dir "<REPLAY_RUN_DIR>" --match-profile "<SAVED_MATCH_PROFILE.json>" --json

匹配记录重放

⑤ SVG（OPTIONAL_SYMBOL_ASSETS）

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

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

人工绑定到 QGZ（需 PyQGIS 环境，如 Windows 的 python-qgis.bat）

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

候选目录接入完整交付 + 生成后必须退出进程再独立复验（可加 --font /path/to/font.ttf）

⑥ 审查发布（README / OSM_STANDARD_MATCHING §2–§3）

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

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

# 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……）；已存在版本目录被拒绝，不覆盖旧版本

⑦ MCP（README「MCP 与主流智能体」）

# 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，重启客户端

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

目录授权：MCP 只能访问客户端工作区或显式授权根目录中的文件（Linux 用冒号分隔）

§3 · 参数卡

七个参数，两条互斥规则

参数表逐字转录自 OSM_STANDARD_MATCHING。convert 和 auto-convert 默认使用 --matching osm。

参数	用途
`--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 提取所用的原图字体目录，可以重复指定。

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

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