# AutoCAD-Control-Engineering

用于 AI/Agent 控制 AutoCAD 的 MCP Host、原生 .NET 插件扩展，以及从参考图生成、
校核和交付电气图的可复用示例。采用固定 upstream、事务写入、保存重开和几何回读。

[![checks](https://github.com/gujiu502/AutoCAD-Control-Engineering/actions/workflows/ci.yml/badge.svg)](https://github.com/gujiu502/AutoCAD-Control-Engineering/actions/workflows/ci.yml)

**先看：[绘图规则](docs/CAD_DRAWING_RULES.md) · [复用指南](docs/REUSE_GUIDE.md) ·
[早期问题与防复发检查](docs/KNOWN_FAILURES.md) · [原稿与成图对比](docs/comparison/README.md)**

## 原稿与实际 CAD 成图

选用第三张住宅电气图。左侧为原始照片，右侧为已在 AutoCAD 保存并重开的可编辑成图预览。

| 原始照片 | CAD 成图 |
| --- | --- |
| ![第三张原始照片](docs/comparison/03_original.jpg) | ![第三张 CAD 成图](docs/comparison/03_redrawn.png) |

下载示例：[DWG](examples/electrical/03_house_electrical_layout.dwg)、
[DXF](examples/electrical/03_house_electrical_layout.dxf)、
[矢量 PDF](examples/electrical/03_house_electrical_layout.pdf)。
这个对比 PDF 是无模板 A3 成图；以下完整演示会另外生成带模板的 A4 打印版。
公开模板的个人字段已清空，原始照片和符号仍保留其各自来源信息。

## 快速运行

Windows 上安装 Git、uv、Python 3.12+ 与 .NET SDK 8+：

```powershell
git clone --recurse-submodules https://github.com/gujiu502/AutoCAD-Control-Engineering.git
cd AutoCAD-Control-Engineering
powershell -ExecutionPolicy Bypass -File scripts/setup.ps1
powershell -ExecutionPolicy Bypass -File scripts/test.ps1 -Upstream
powershell -ExecutionPolicy Bypass -File scripts/build.ps1
powershell -ExecutionPolicy Bypass -File scripts/demo-electrical.ps1
```

演示默认 **headless**，无需启动 AutoCAD。生成三张可编辑 DXF、统一图框 block 和三份
A4 横向矢量 PDF，最终文件在新建的 `workspace/output/demo-*/delivery/`。
已有输出目录拒绝复用，避免覆盖上一份成品。

```mermaid
flowchart LR
    A[原稿坐标与指定符号] --> B[墙门与接线检查]
    B --> C[完整成图等比放入模板]
    C --> D[统一 A3 图框 block]
    D --> E[A4 横向 PDF 至少 10 mm 白边]
    D --> F[显式 native 保存 DWG 重开回读]
```

这三份生成器是根据原稿人工识别后编码的确定性示例，**不是任意照片自动识别器**。
复用到新图时，需提供该图的坐标、器件、门与回路关系，并修改对应验收条件。
具体参数、完整阶段和新图适配流程见 [REUSE_GUIDE.md](docs/REUSE_GUIDE.md)。

## 真正使用 AutoCAD

插件面向完整 Windows AutoCAD 2025/2026 的 R25 API。先编译并在 AutoCAD 中加载本项目
扩展 DLL，然后执行：

```powershell
powershell -ExecutionPolicy Bypass -File scripts/doctor.ps1
powershell -ExecutionPolicy Bypass -File scripts/demo-electrical.ps1 -Backend native
# 本地显式 opt-in 原生测试：新建 scratch 文档，不编辑原活动图纸几何
powershell -ExecutionPolicy Bypass -File scripts/test.ps1 -Native
```

原生演示在最后阶段输出真正 DWG，重新打开、导出 DXF，再比较完整图形和图框块。
没有 native worker 时明确失败，不静默回退到 DXF。
生产安装脚本要求有效 Authenticode 签名并保留旧 bundle；开发 NETLOAD 方法见复用指南。
不降低 SECURELOAD、不改 TRUSTEDPATHS、不用键盘鼠标模拟画图。

编译时可设置 `build.ps1 -AutoCADDir <安装目录>`；未提供安装目录时使用固定 Autodesk
`AutoCAD.NET 25.0.1` NuGet 引用，不将 Autodesk runtime DLL 打进插件包。
运行版本要求参见 [Autodesk .NET compatibility](https://help.autodesk.com/cloudhelp/2026/ENU/AutoCAD-Customization/files/GUID-A6C680F2-DE2E-418A-A182-E4884073338A.htm)。

## MCP 接入与安全边界

```powershell
powershell -ExecutionPolicy Bypass -File scripts/configure-mcp.ps1 -Backend native
uv run --frozen python -m autocad_control --backend native
# 无 AutoCAD 时必须明确选择：
uv run --frozen python -m autocad_control --backend headless
uv run --frozen python examples/run_plan.py --backend headless
```

项目配置文件 `.mcp.local.json` 中的 server 条目可加入标准 stdio MCP 客户端；脚本不修改
全局客户端设置。stdout 仅传输协议，日志进入 `workspace/logs`。

每个写请求先读取最新 `document.get_active`，携带 session/document/revision。
Host 写入串行；native 使用 DocumentLock 和 Transaction；锁定图层拒写。
严格校验 schema、有限数值、WCS XY / z=0 / mm，非 mm 图纸返回 UNIT_MISMATCH。
输出限制在 `workspace/output`，保存默认是副本，输入文件只读打开。
计划不是整份原子事务：失败时先前成功步骤保留；通过 checkpoint 恢复，不盲目重放未知写入。

## 防止早期绘图问题复发

| 要求 | 已落地的检查 |
| --- | --- |
| 原稿布局与指定符号一致 | 102 个人工识别对照点、器件位置回归，以及逐图视觉对照 |
| 回路是真虚线，端头接开关 | 线型、起始墨迹、端点、重复线段检查；断接负例 |
| 贴墙、墙角闭合、门弧不穿墙 | 墙/器件边界、门扇与完整弧线检查；错误门弧负例 |
| 避开无关符号、文字和门区 | 回路碰撞检查；不相连交叉明确表达；穿符号负例 |
| 调速器不乱放、不旁路 | 原稿位置与串入对应风扇回路检查；旁路负例 |
| 图框 block 不改变图形 | 同名块定义、插入、单位比例、边界及递归展开几何比较 |
| A4 有 1 cm 白边且不裁图 | 页尺寸、四边留白、矢量路径数量、渲染查看和 100% 打印设置 |
| clone 后可以重跑 | 可配置路径、随仓库提供脱敏模板、固定依赖/补丁、完整 headless 管线测试 |

具体错误、处理办法和仍然存在的验证边界见 [KNOWN_FAILURES.md](docs/KNOWN_FAILURES.md)。
自动测试覆盖已知错误，无法代替原稿视觉核对，也不证明电气施工符合规范。

## A4 打印与 BatchPlot

CAD 模型中沿用 A3 模板，外框/右侧图签线格为同名 `SKM3_A3_FRAME` 块，三个插入均为
420×297 mm、比例 1、旋转 0。支持按块选范围的 BatchPlot 可使用该块名；图签文字可单独编辑。
尚未在第三方 BatchPlot 插件中执行批量打印验收。

最终 PDF 使用 A4 横向，至少 10 mm 白边：等比例缩小后上下 10 mm、左右约 14.16 mm。
打印选择 **A4 / 实际大小 / 100%**。PDF 从同一矢量几何生成，当前不是 AutoCAD 原生 Plot。

## 当前能力与限制

| 能力 | 状态 |
| --- | --- |
| 文档 inspect/new/open/save copy，图层 CRUD/锁定 | 已实现 |
| line/circle/arc/polyline/rectangle/text/mtext，实体 get/list/count/erase/move | 已实现 |
| selection.query、checkpoint、DXF 导出、CADPlan、stdio MCP | 已实现 |
| DXF audit 与 PNG | 仅 headless；native 不宣称支持 |
| 三图重绘、图框块、A4 PDF | 独立确定性脚本；不是新增通用 native block/Plot tool |
| Undo/Redo、复杂 trim/extend/offset/fillet/chamfer、通用块/属性、标注 | 后续阶段 |
| 完整 3D、自动图片识别/自然语言 Planner、APS、完整 DWG AUDIT | 后续阶段 |

GitHub Actions 检查普通/headless测试、upstream测试和插件编译，**不在云端运行 AutoCAD**。
历史本地真实 native 证据与最新检查记录在 [IMPLEMENTATION_STATUS.md](work/IMPLEMENTATION_STATUS.md)。
本次全新克隆验证记录见 [VALIDATION.md](docs/VALIDATION.md)。
编译成功不证明真实 AutoCAD 可运行，旧的 native 成功记录也不能代替新机器的验收。

## 结构与上游

```text
python/autocad_control/       MCP Host、严格契约、队列和 CADPlan
src/AutoCADControl.Plugin/    本项目 Managed .NET 扩展
upstream/autocad-mcp/         固定 upstream 子模块
patches/                     生命周期、管道、进程发现集成补丁
scripts/                     安装、检查、出图和打印入口
assets/                      用户符号、脱敏图框、原稿对照点
tests/                       headless、stdio、绘图/打印回归和显式 native 测试
docs/                        规则、复用指南、问题记录、对比图
examples/electrical/         第三张图的可编辑 DWG/DXF/PDF/PNG
workspace/                   本地运行产物与日志，Git 忽略
```

复用 [beiming183-cloud/AutoCAD-MCP](https://github.com/beiming183-cloud/AutoCAD-MCP)，
固定 commit `11f7c47e5038796a20451b38b23032e625b5aa26`，通过子模块和补丁集成。
这是独立派生工程，并非 upstream 仓库中自动可用的相同工具集合。
代码采用 [MIT](LICENSE)，保留 upstream 许可；素材来源与范围见 [assets/README.md](assets/README.md)。

原始规格顺序：`00_MASTER_SPEC.md` → `01_ARCHITECTURE.md` → `02_TOOL_API.md` →
`03_IMPLEMENTATION_PLAN.md` → `04_TEST_PLAN.md` → `05_AGENTS.md`。
这些文件描述完整目标，不代表所有目标已实现。Agent 实际执行还需读取根目录 [AGENTS.md](AGENTS.md)。