# cad-building-showcase 把中国建筑施工图(DWG/DXF,天正 t3/t8 导出为主)自动转成可交互的 3D 展示模型(GLB + 离线单文件 Web viewer),并支持多栋厂区按总平面装配。Agent-led:脚本负责证据与可重复执行,判读权在 Agent;任何门禁失败即停,不静默出错模型。 ## 安装到 Agent CLI `SKILL.md` 自带 frontmatter(`name`/`description`),符合 Anthropic skill 格式;本仓库即 skill 本体,克隆即装。 **Claude Code**(原生 skill 机制,自动发现与触发): ```bash # 全局(所有项目可用) git clone ssh://git.latent.chat/zhengweirong/cad-building-showcase.git \ ~/.claude/skills/cad-building-showcase # 或装进单个项目 git clone ... /.claude/skills/cad-building-showcase ``` 装好后对 Claude Code 说"把这套 DWG 做成 3D 展示模型"即可自动触发,或显式 `/cad-building-showcase`。 **opencode / Codex CLI / 其他 AGENTS.md 系工具**(无 skill 机制,用指令文件指路): ```bash git clone ... tools/cad-building-showcase # 克隆到项目内任意位置(或 git submodule) ``` 然后在项目的 `AGENTS.md`(opencode、Codex 都读它)加一段: ```markdown ## CAD → 3D 展示模型 处理 DWG/DXF 转 3D/Web 展示任务时,必须先完整阅读 tools/cad-building-showcase/SKILL.md 并遵守其中 One-Shot Definition of Done 七条门禁:门禁失败即停下修复,绝不绕过;改动任何脚本后必须跑 `pytest tools/cad-building-showcase/tests/test_contracts.py tools/cad-building-showcase/tests/test_delivery.py` 与 `python3 tools/cad-building-showcase/tests/test_extraction_pipeline.py` 且全绿。 ``` **任何其他 Agent 的兜底用法**:把上面那段话作为任务开场白直接粘给它——skill 的全部约定都在 `SKILL.md` 里,脚本自含 CLI(`--help` 可查),不依赖宿主工具的任何私有机制。 **运行依赖**:Python ≥3.10,核心运行 `pip install -r requirements-core.txt`,交付验证再装 `requirements-delivery.txt`;Node ≥18。可选:libredwg、ODA File Converter、Blender、IfcOpenShell。先运行 `python3 scripts/cad_showcase.py doctor` 检查环境。 **跨平台**:脚本全用 pathlib + 显式 UTF-8 I/O + 子进程 bytes 解码,macOS/Linux/Windows 均可跑。工具发现顺序:Blender = env `BLENDER` → PATH → 平台安装默认(macOS 应用包 / Windows `Program Files\Blender Foundation`);ODA = env `ODA_CONVERTER` → PATH → 平台默认(Windows 含 `Program Files\ODA`)。Windows 建议:设 `PYTHONUTF8=1`(防重定向输出按 GBK 解码)、开启 LongPathsEnabled(中文长文件名的深层 work/ 目录可能触及 260 字符 MAX_PATH);Windows 上 libredwg 少见,DWG 转换以 ODA 为主路径。 ## 用法 入口是 `SKILL.md`(决策树与硬门禁),详细分支按需读取 `references/`。推荐统一 CLI: ```bash python3 scripts/cad_showcase.py inspect --input --work work/ --output outputs//read_report python3 scripts/cad_showcase.py run --dxf-dir --config --source-report --scope-manifest work//scope_manifest.json --out-dir outputs/ --name --backend trimesh --web --offline --resume ``` 核心链路: ``` cad_dxf_report.py 读图报告(警告:多框图纸/缓存XREF/陌生图层方言…) detect_sheet_frames.py 图框检测(图签块定框、网格投票/墙剖面互相关对齐、 多层图名展开、逐框标高梯+层高建议) derive_showcase_spec.py 按 config 提取 building_spec.json(分簇 footprint/楼板/顶盖) audit_showcase_extraction.py 硬门禁审计(楼层对齐+跨层基准、幕墙、框收支表、 面积/层数互证…),FAIL 即退出码 3 spec_to_glb.py GLB 生成;write_offline_viewer.py 离线单文件 viewer(使用 raw GLB) register_site_outlines.py / massing_from_outline.py / assemble_campus.py 总平面配准(点-边ICP)、无图纸楼体量、厂区装配 ``` ## 目录 - `scripts/` 全部流水线脚本(自含 CLI,`--help` 有说明) - `schemas/` extraction config、building spec、variants manifest 的版本化 JSON Schema - `tests/` 契约/交付测试 + 合成 DXF 全链路回归 - `references/` 当前运行规范;历史复盘移到 `docs/history/`,不再作为 Agent 运行上下文 - `assets/` Web 模板与离线 viewer 内联库;离线交付必须通过真实 `file://` 浏览器 smoke `work/`、`outputs/`、源 CAD 均不入库(见 `.gitignore`),由脚本从源数据再生。 ## 验证纪律 ```bash pytest tests/test_contracts.py tests/test_delivery.py python3 tests/test_extraction_pipeline.py ruff format --check scripts tests && ruff check scripts tests npm run check:js ``` 已在四套真实图纸上端到端验证:贝昂科技厂区(基线)、黄桥文体中心、13号地块(双塔+酒店厂区)、27号地块(7栋混合厂区)。历史质量对比见 `docs/history/generalization_test_log.md`。