gjm
6143bb9ab2
支持直接审查 PDF 与位图图纸，全链路离线（不连 CAD、不连 8080 端口）。 渲染在内存内完成，复用既有墨迹热力图 + 自适应瓦片规划。 - 新增 dwg_review/sources.py - detect_source / plan_file / collect 统一入口 - PdfReader：pypdfium2 惰性导入，页序即图框序，处理 /Rotate 与 crop 边距 - ImageReader：世界单位 = 源像素，snap_box 整数对齐保证窗口与像素严格一致 - ink_grid：纯 PIL 灰度阈值 → 占用网格（不引入 numpy） - ReviewContext.create(connect_cad=False)：离线时 client/tools 均为 None - 全链路 ctx.tools is None 守卫：review 只读子循环 / inspect_region / annotator / checks 的窗口类检查 / 绘图区最大化 - checklist.build_system_prompt(allow_tools=False, offline=True)：离线提示词 - __main__：位置参数 source，按扩展名自动判定源类型并决定是否连 CAD - config 新增 8 个常量（PDF_MAX_PAGES / 文本最小字数 / 各源缩放上限 / 墨迹阈值等） - tiling.content_predicate 与 heatmap.cell_box 提升为公开函数 验证： - pytest 457 passed - verify_pdf_source.py：PDF 23/23、图片 9/9（不需 CAD），含实测瓦片字高像素与 旋转映射自检（文本区墨迹 0.311 vs 忽略 /Rotate 反向对照 0.145） - 真实 LLM 端到端：20 页 HVAC 图纸前 3 页跑通，结论具体可核验且未编造 handle 已知局限：页边线在墨迹网格里会把整页连成单簇，瓦片常退化为整页象限（CAD 侧 靠 drop_oversized 丢图框块，离线侧暂无等价手段），留待后续打磨。
126 lines
8.4 KiB
Markdown
126 lines
8.4 KiB
Markdown
---
|
||
name: 环境与外部资源
|
||
description: CadProject 的构建/运行要点、CAD SDK 路径、测试分层（pytest 快层 + verify_* 慢层）等外部资源指引
|
||
type: reference
|
||
---
|
||
|
||
# 环境与外部资源
|
||
|
||
## 构建
|
||
|
||
- 系统：**CMake + vcpkg + Visual Studio 生成器**，通过 CMake Presets 区分 CAD 版本。
|
||
- 产物：`bin/<Config>-<TAG>/` 与 `lib/<Config>-<TAG>/`。
|
||
- 命令：`cmake --preset R230` → `cmake --build --preset R230 --config Debug`。
|
||
- 可用 preset：`R180`–`R260`（AutoCAD，ARX 18–26）、`Z2023`–`Z2026`（ZWCAD，ZRX）。
|
||
- 前置：需要 `VCPKG_ROOT`；必需 cache 变量 `CAD_SDK_ROOT`、`DEP_LIB_ROOT`、`DEP_INC_ROOT`、
|
||
`CAD_SDK_VERSION`（AutoCAD 还需 `CAD_SDK_SUBVERSION`）。
|
||
|
||
## CAD SDK 路径
|
||
|
||
- AutoCAD：仓库同级 `../envi-code/Arx`
|
||
- ZWCAD：仓库同级 `../envi-code/Zrx`
|
||
- 在 `cmakepresets.json` 的 `CAD_SDK_ROOT` 中配置。
|
||
|
||
## 运行 / 联调
|
||
|
||
- 先启动 **已加载插件的 CAD**，确认 `127.0.0.1:8080` 在监听。
|
||
- 脚本通过 TCP 连接 `127.0.0.1:8080` 收发 JSON-RPC。
|
||
|
||
## 测试（两层，互不替代）
|
||
|
||
**快层 —— pytest 离线单元测试**（`tests/`，假 LLM + 假基座，无需 CAD、不联网、秒级）：
|
||
|
||
- `pip install -r requirements-dev.txt` → `python -m pytest`。
|
||
- 配置：`pytest.ini`（`testpaths = tests`）、根 `conftest.py`（加 `sys.path` + `RENDER_WAIT=0` / `REPORT_DIR=tmp` fixture）。
|
||
- 陷阱：`dwg_review.config` 常量导入期定值，改 `os.environ` 无效，须 `monkeypatch.setattr(config, ...)`。
|
||
|
||
**慢层 —— 端到端冒烟脚本**（根目录 `verify_*.py`，需 CAD 在线且 `127.0.0.1:8080` 监听）：
|
||
|
||
| 脚本 | 作用 |
|
||
| --- | --- |
|
||
| `verify_mcp_frame.py` | 基座最小集：分帧 / id / isError 映射 |
|
||
| `verify_mcp_tcp_hardening.py` | TCP 收发路径加固（超长帧 / 粘包 / 半关闭） |
|
||
| `verify_mcp_fault_injection.py` | 工具异常保护（类型错误不再崩 CAD） |
|
||
| `verify_stdio_bridge.py` | stdio ↔ TCP 桥（协议协商 / 转发 / 通知） |
|
||
| `verify_annotate.py` | 批注工具运行时验证（绘制/校验/改属性/清理）；`--keep` 保留批注 |
|
||
| `verify_heatmap.py` | 实体分布热力图（占用网格 + 聚类 + PNG），**不耗 token**，缓存 bbox JSON 供离线调参 |
|
||
| `verify_vlm_resolution_offline.py` | **离线**（纯 PIL 合成）标定 VLM 读图下限 `R_text`/`R_line`，`--dry-run` 只出图 |
|
||
| `verify_text_resolution.py` | **CAD 实测**标定（临时加字 + 平行线，测完 `delete_entities` 清理）；`--keep` 保留 |
|
||
| `verify_drawing_area.py` | 绘图区最大化验收：基线 → `set_drawing_area(max)` → `restore`，断言窗口矩形/最大化态/绘图区尺寸全回位（实测 3.68×） |
|
||
| `verify_review_maximized.py` | 审查全链路验收：在 `collect`/`review_frame` 入口各采一次窗口矩形，断言**取证与审查两阶段都在最大化态**、结束精确还原；并统计子循环 zoom/截图次数 + 记录 LLM 实际调用的取证工具（含虚拟工具 `inspect_region`） |
|
||
| `verify_collisions.py` | `find_collisions` 验收：工具注册 / 全模型与逐图框粗筛 / **容器过滤**（图框块剔除）/ `min_overlap` 阈值 / 分页 / `narrow` 细筛 / `--inject` 注入干涉正例（画 2 个深重叠矩形 → 应报出 ratio≈0.902 → 清理）。**只读**（`--inject` 段除外，会自动清理） |
|
||
| `verify_pdf_source.py` | **PDF / 图片离线源验收（不需要 CAD）**：离线上下文断言 / 页序 / evidence 同形 / 图片窗口在图框内 / **实测瓦片字高像素达标** / **旋转映射自检**（文本区墨迹 vs 忽略 `/Rotate` 反向对照）/ `--dump` 导出目视包 / `--llm` 追加真实 `python -m dwg_review` 端到端 |
|
||
|
||
> 历史：根目录 `test.py` / `test_autoagent.py` / `countOfCircle.py` / `agent_loop.py` /
|
||
> `dwg_review_agent.py` 五个遗留调试脚本已于 2026-10-14 删除（前三个含硬编码 API Key，
|
||
> 后两个是重复实现）。`test_screenshot.png` 是 `test_autoagent.py` 的残留产物。
|
||
|
||
## Python 运行时依赖（2026-10-16 起）
|
||
|
||
- 仓库根新增 **`requirements.txt`**（运行时）与 `requirements-dev.txt`（仅 pytest）。
|
||
- `openai>=1.0`（LLM 客户端，Key 走环境变量 `DEEPSEEK_API_KEY`）
|
||
- `Pillow>=10.0`（截图下采样、墨迹分析、离线标定）
|
||
- `pypdfium2>=4.30`（PDF 源适配：内存渲染 + 带 bbox 抽文本）
|
||
- 选它而非 PyMuPDF：**许可证干净**（Apache-2.0/BSD vs AGPL-3.0）、
|
||
wheel 为 `py3-none-<platform>`（**与 Python 版本无关**，实测 Python 3.14.5 直接可用）、体积小（~4MB）。
|
||
- 实测环境：Python **3.14.5**，`pypdfium2 5.14.0`（`py3-none-win_amd64`）。
|
||
|
||
## 两个构建目标
|
||
|
||
| 目标 | 产物 | 作用 |
|
||
| --- | --- | --- |
|
||
| `src/cad_mcp_frame` | `cad_mcp_frame.arx`（ZWCAD 下 `.zrx`） | MCP **基座**：起 TCP、解析配置、路由执行 |
|
||
| `src/cad_mcp_plugins` | `cad_mcp_plugins.dll` | 示例 **C++ 工具插件**，ABI 动态加载 |
|
||
|
||
## 三种工具后端（`backend.type`）
|
||
|
||
- `lisp_inline`：`{占位符}` 替换后 `sendStringToExecute`（**异步**）。
|
||
- `lisp_file`：`(load "文件" nil)` 后执行 `call_template`。
|
||
- `c++_dll`：`LoadLibrary`（**同一 DLL 只加载一次**）+ 工厂/销毁函数（**同步**，可返回图像）。
|
||
版本校验与「写库需文档锁」两个坑见 [MCP 基座 c++_dll 加载与执行的坑](project_mcp_frame_dll_loader.md)。
|
||
|
||
## 工具语义坑：`query_entities` 的两个 filter（2026-10-15 实测）
|
||
|
||
- **`type_filter` 必须是「数组」**（精确类型名列表，如 `["TEXT"]`）。
|
||
传**字符串**会被**静默忽略**——`typeMatches` 对「非数组」一律 `return true`（全通过），
|
||
于是你以为筛了文字，实际把 LINE 等全带回来了（踩过：标定脚本因此把窗口中心算到无文字处）。
|
||
- **`layer_filter` 是「字符串 + 通配」**（`wildcardMatch`），**不是**列表。
|
||
传列表会被忽略 → 通配为空 → **匹配所有图层**（清理类操作慎用）。
|
||
- 另有 `space`（模型/图纸空间）、`limit`（**硬钳 1..1000**）、`offset`（分页）。
|
||
- 相关工具返回体：`add_text` / `add_line` 等返回 `{"ok":true,"count":1,"created":[{handle,layer,type}]}`
|
||
—— 句柄在 **`created`** 键下（不是 `items`）。
|
||
|
||
## 远程仓库
|
||
|
||
- 现状（2026-10-08 起）：`CadProject` 已从「某仓库的子目录」**独立为单独仓库**。
|
||
- `origin` = `ssh://git@39.107.55.179:222/gjm/cad-agent.git`
|
||
- 当前分支 `home-ai-dev`；服务器只保留 `main`，采用 **PR 流程**
|
||
（`home-ai-dev` → `main`，合并后源分支被删除，故本地 `home-ai-dev` 的 upstream 显示 `[gone]`）。
|
||
- 历史已被重写/重新初始化（哈希全新）。
|
||
- 历史参考（旧）：`new-start.git` = `ssh://gjm@47.93.46.28:1216/srv/git/new-start.git`
|
||
- **SSH 密钥（2026-10-08 变更）**：服务器已改用新密钥
|
||
`~/.ssh/id_ed25519_guojianming`（注释 `guojianming.go@gmail.com`）；
|
||
旧密钥 `~/.ssh/id_ed25519`（`deploy@aly-db`）已被服务器移除，会 `Permission denied (publickey)`。
|
||
本仓库已设置 `git config core.sshCommand "ssh -i ~/.ssh/id_ed25519_guojianming -o IdentitiesOnly=yes"`。
|
||
换机器时需补该配置或加入 `~/.ssh/config`。
|
||
|
||
## 真实测试图纸
|
||
|
||
**CAD 源（2026-10-15）**
|
||
|
||
- 图纸：`e:\desktop\agent_test.dwg`（用户制作的真实 Plant 3D 图纸：3 个图框 A0/A1/A2，
|
||
86 个实体：`AECDBEWFITTING` 40 / `AECDBEWPIPE` 29 / `AECDBEWEQUIPMENT` 14 / `INSERT` 3）。
|
||
- **启动方式**：`acad.exe /p SHS-ENVI2026 e:\desktop\agent_test.dwg`
|
||
—— 必须带 `/p SHS-ENVI2026` profile，否则**自定义实体无法显示**（该 profile 自动加载
|
||
用户写的显示插件）。
|
||
- 实测：`python -m dwg_review --frames 1` 端到端可跑通并出报告。
|
||
|
||
**PDF 源（2026-10-16）**
|
||
|
||
- 图纸：`E:\desktop\05 暖通专业图纸.pdf`（**20 页**，A3/A4 混排，`/Rotate 90`）。
|
||
页 0 = 封面（仅一行标题字）；页 1 = 图纸目录（**有文本层**，43 个文本矩形）；
|
||
页 2 起 = 真实施工图（**0 个文本矩形**，文字全是 SHX 描边）。
|
||
- 实测：`python -m dwg_review "E:\desktop\05 暖通专业图纸.pdf" --frames 3`（**离线、不连 CAD**）
|
||
端到端跑通，VLM 报出设备标注叠压、定位尺寸缺失、材料表空白等具体问题。
|
||
- 图片源样本：由该 PDF 第 3 页渲染的 `out/verify_pdf_source/page2.png`（2717×1945，测试产物）。
|