# CadAgent

**Repository Path**: xiaoke799/CadAgent

## Basic Information

- **Project Name**: CadAgent
- **Description**: AutoCAD .NET 插件 + WPF 聊天面板：CAD 智能体。支持自然语言指挥 AutoCAD 画图、标注、查询，含自动更新。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 1
- **Created**: 2026-07-16
- **Last Updated**: 2026-09-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CAD 智能体（CadAgent）

一个 **C# + AutoCAD .NET** 开发的 CAD 二次开发工程师型智能体：在 CAD 中加载后，用自然语言指令驱动大模型拆解成 CAD 原子操作并直接执行，内置 **WPF 聊天面板**（PaletteSet 侧边栏）。核心是**自动化画图**——既能「读图 / 查尺寸 / 量算」，也能「绘图 / 编辑 / 删除 / 覆盖 DWG」。

> 本工程是**原生 CAD .NET 插件**，全部自研；同时支持 AutoCAD、中望 ZWCAD、浩辰 GstarCAD 多宿主加载。

## 核心能力一览

- **自然语言画图 / 读图**：100 个内置 CAD 工具，覆盖几何、标注、填充、块、图层、数据导入、查询量算、图纸智能分析、脚本加载、学习能力等。
- **五条执行降级链兜底**：`.NET API → send_command → run_lisp → run_vba → run_com`，没有专用工具的命令也能落地。
- **通用模型库 + 三角色路由**：模型配置从「四槽位」升级为「通用模型档案库 + 主/辅/轻三角色」，支持多厂商混用、本地模型、按能力自动路由，并内置省 token 的上下文压缩开关。
- **MCP 双向能力**：
  - **出站**：动态接入外部 MCP 工具服务器（借工具）；
  - **入站**：对外暴露命名管道服务，**让同机其他智能体直接调用本机 CAD 能力**（默认只读子集，可开「完全访问」开关暴露全部工具）。
- **插件体系**：领域能力以 `IPlugin` 插件形式热加载（ALC 隔离），内置测绘/道路/结构/水利 4 个领域插件。
- **领域技能**：`skills/*.md` 指令文件注入 system 提示，框架不含任何领域专有知识，增删即生效。
- **多模态看图纸**：截图 CAD 图面 + 指定上下文（点/对象/句柄），发给视觉模型一起推理。
- **安全防护 + 长会话稳定**：危险命令分层拦截、模糊指令预检、防死循环；运行隔离、上下文压缩、磁盘记忆、L3 命令队列崩溃可续。

## 工程与架构

```
CadAgent.slnx
├── src/CadAgent.Core/           (netstandard2.0;net8.0，不引用 CAD，可独立编译/单测)
│   ├── LLM/OpenAiClient.cs         OpenAI 兼容 /chat/completions（SSE 流式 + 思考参数发射）
│   ├── LLM/McpClient.cs            MCP 客户端（stdio/HTTP/SSE，JSON-RPC 2.0）
│   ├── Config/ModelProfile.cs      通用模型档案 + 内置厂商预置（模型库载体）
│   ├── Config/Settings.cs          配置读取（模型库 / MCP / 入站完全访问开关等）
│   ├── Agent/ToolDefinitions.cs     100 个 CAD 工具的 JSON Schema 与只读/全部目录
│   ├── Agent/CadAgentLoop.cs        有状态主循环（history + 压缩 + 记忆 + 编排 + 裁判）
│   ├── Agent/CompositeToolExecutor  组合执行器（按优先级尝试 内置→MCP→降级链）
│   ├── Agent/Planner.cs / GoalReviewer.cs   通用分步编排 + 目标裁判
│   ├── Agent/ContextCompressor.cs   上下文压缩（超预算浓缩旧轮次）
│   ├── Agent/InstructionGate.cs     指令预检网关（模糊指令规格化）
│   ├── Agent/SkillLoader.cs         技能加载（注入 system 提示）
│   ├── Agent/FileMemoryStore.cs     磁盘记忆（MEMORY.md 规范 + checkpoint.json 对话）
│   ├── Plugins/PluginHost.cs        插件宿主（ALC 隔离加载 + GatedExecutor 门控）
│   ├── Mcp/InboundMcpServer.cs      入站 MCP 服务端（命名管道）
│   ├── Mcp/InboundMcpDispatcher.cs  入站工具路由（只读/完全访问目录）
│   ├── Safety/CadCommandGuard.cs    危险命令分层拦截（CRITICAL/HIGH）
│   ├── Safety/DoomLoopDetector.cs   防死循环（连续告警终止）
│   └── Logging/                     文件日志（异步、按日期轮转）
│
├── src/CadAgent.AutoCAD/        (net48;net8.0-windows，引用 CAD 托管 API)
│   ├── CadAgentApplication.cs       IExtensionApplication（插件入口）
│   ├── CadTools.*.cs                CAD 工具实现（Database/Transaction 驱动）
│   ├── AcadHelpers.cs               取文档/开事务/清场/锁世界系
│   ├── ChatPalette.cs / ChatView.xaml    WPF 面板（自动隐藏 + 停靠）
│   ├── ChatViewModel.*.cs            MVVM + 模型库 + MCP + 入站开关 + 用量
│   ├── CadHealthMonitor.cs          L3 进程健康监控（配合命令队列）
│   ├── skills/                      技能指令目录（markdown）
│   └── appsettings.json             配置模板（密钥勿入库）
│
├── src/CadAgent.Host.Common/     多宿主公共抽象（ICadHost / 宿主探测 / 产品 Id）
├── src/CadAgent.Host.GstarCAD/   浩辰宿主适配
├── src/CadAgent.Host.Zwcad/      中望宿主适配
├── src/CadAgent.Plugin.Survey/   测绘插件（四/七参数、高斯正反算）
├── src/CadAgent.Plugin.Road/     道路插件（平/竖曲线、土石方）
├── src/CadAgent.Plugin.Structure/ 结构插件（梁柱板、基础、配筋）
├── src/CadAgent.Plugin.Water/    水利插件（渠道、涵洞、坝、消力池）
├── src/CadAgent.Tests/           核心库单元测试（322 用例）
└── src/CadAgent.AutoCAD.Tests/   宿主层单元测试（49 用例）
```

> `CadAgent.Core` 与 CAD 完全解耦，工具语义改动无需动 LLM 代码；AutoCAD 工程只负责把 Core 的指令落到具体 CAD 对象上。

## 执行降级链（五级兜底）

当某操作没有专用 .NET 工具时，按优先级逐级降级，保证「说得出口的命令都能落地」：

```
① .NET API（Database/Transaction 直写）
   ↓ 无专用工具
② send_command（发送命令行，_. 前缀避语言包、_ 前缀避选项弹窗）
   ↓ 命令不直观
③ run_lisp（让模型产出 AutoLISP，经进程内求值）
   ↓ 仍不行
④ run_vba（VBA 宏通道）
   ↓ 最后兜底
⑤ run_com（COM 自动化）
```

配套「执行后自检」`verify_drawing`：异常后 `AUDIT`（修复）→ `PURGE`（清理）→ `REGENALL`（刷新）。

每步 CAD 写操作使用独立事务，单工具原子可撤销；完整 CAD 引用下可再用 `BeginUndoMark/EndUndoMark` 把「一次对话多步」合并为一个逻辑撤销步。

## 模型库（通用档案库 + 三角色路由）

模型配置已从「四槽位」重构为**通用模型档案库**：

- **一条档案 = 一个端点**（厂商 / 地址 / 密钥 / 模型名）+ 能力开关（视觉 / 思考 / 工具 / 语音 / 流式）+ token 上限 + 思考参数。
- 库里可放任意多条档案，支持**多厂商混用**、**本地模型**（Ollama / LM Studio / vLLM，通常无需密钥）接入。
- 内置常见厂商预置（`BuiltInModels.Seed`）：OpenAI、通义千问、智谱 GLM、豆包、小米 MiMo、DeepSeek、Kimi、MiniMax、百度千帆、本地模型等，首次启动播种，不覆盖用户已编辑的同 Id 档案。
- 支持按当前（Endpoint + Key）查询账号**真实可用模型**并加入下拉。

**三角色**各自引用库中的某条档案 Id，由路由按任务类型分发：

| 角色 | 用途 | 典型配置 |
|---|---|---|
| 主（推理/对话） | 常规问答、规划、绘图推理 | 能力强、支持工具的中大模型 |
| 辅（代码/编排） | 复杂代码与多步工具编排 | 工具调用强、推理稳的模型 |
| 轻（Light） | 上下文压缩、轻量闲聊 | 小模型 / 本地模型，省 token |

- **上下文压缩开关**：超预算时把最旧轮次经「轻」角色浓缩为摘要（temperature 0），history 有界，长会话不膨胀。
- **密钥存储**：勾选「记住」后用 **Windows DPAPI（当前用户作用域）** 加密落盘（`enc::<Base64>`），复制到其他机器/账户无法解密；环境变量 `CAD_AGENT_API_KEY` 仍优先。

## 工具集（100 个，自然语言可驱动）

- **几何**：直线 / 圆 / 圆弧 / 多段线 / 矩形 / 多边形 / 点 / 样条 / 圆环 / 椭圆 / 面域
- **修改**：移动 / 复制 / 旋转 / 镜像 / 偏移 / 修剪 / 延伸 / 打断 / 合并 / 圆角 / 倒角 / 缩放 / 拉伸 / 阵列 / 对齐
- **标注与文字**：对齐标注 / 线性标注 / 引线 / 单行文字 / 多行文字 / 文字样式
- **填充与块**：Hatch 填充 / 插入块 / 写块 / 外部参照
- **图层与结构**：新建图层 / 设当前层 / 列图层 / 块属性 / 外部参照列表 / 图纸信息 / 图纸树 / 样式列表
- **查询与量算**：按句柄选实体 / 实体信息 / 边界盒 / 批量扫描 / 测量 / 图纸差异 / 选区差异
- **图纸智能分析**：图纸识别 / 图纸树 / 量算核对 / 方向识别 / 截图
- **脚本加载（带安全扫描）**：`load_lisp_file`（.lsp）/ `run_script`（.scr）/ `load_vba_file`（.bas/.dvb）—— 路径校验 + 危险函数/命令扫描 + 1MB 大小限制
- **学习能力**：执行反馈统计 / 错误纠正记忆 / 模式库查询
- **参数化模板**：`parametric_design`（JSON 数据驱动，40 个模板覆盖道路/建筑/结构/水利）
- **逃生与自检**：万能 `send_command` / `run_lisp` / `run_vba` / `run_com` / `verify_drawing` / `screenshot_cad`
- **检索**：`lookup_command`（命令图谱）/ `lookup_lisp`（LISP 函数库）

## MCP：既能借工具，也能被其他智能体调用

### 出站 MCP（借外部工具）

`McpClient` 动态启动外部 MCP 服务器（stdio / HTTP / SSE），自动 `tools/list` 发现工具，工具名以 `mcp_<server>_` 前缀与内置工具共存于组合执行器。连接失败不影响内置工具（优雅降级）。

```json
{
  "MCP_SERVERS": {
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\docs"], "enabled": true }
  }
}
```

### 入站 MCP（被同机其他智能体调用）—— 本项目的对外能力出口

内置 `InboundMcpServer` 通过**命名管道** `\\.\pipe\cadagent-mcp` 对外暴露本机 CAD 工具：

- **自动启动**：首次对话时静默启动（无需面板显式操作），`Dispose` 时关闭。
- **默认只读子集**：外部智能体默认只能「看图纸、查尺寸、读结构、量算」，**不能改图 / 删物 / 覆盖 DWG**。
- **完全访问开关**：设置区「允许外部智能体完全调用」勾选后，经管道可调用**全部本机 CAD/插件工具**（绘图/编辑/删除/覆盖），供同机可信智能体完全驱动。切换开关后下次 `tools/list` 自动反映新集合（catalog 为动态 `Func`），无需重启。
- **安全边界**：完全访问仍只暴露**本机自有工具**（`IsCadTool` 守卫过滤 `mcp_` 前缀的外部工具），**绝不回环转发出站借来的工具**；管道 ACL 限定当前用户 + SYSTEM。
- 设置区实时显示状态（模式 · 暴露工具数 · 管道路径）。

## 插件体系

领域能力通过插件扩展，与主程序**运行时隔离**：

- `IPlugin`：Id / Name / Version / Tools / Executor / Initialize / Shutdown。
- `PluginHost`：扫描插件目录，经 **ALC（AssemblyLoadContext）隔离**加载，用 `GatedExecutor` 门控，状态持久化于 `plugins_state.json`。
- **4 个内置领域插件**（纯计算，不依赖 CAD 宿主 API）：
  | 插件 | Id | 工具数 | 能力 |
  |---|---|---|---|
  | `CadAgent.Plugin.Survey` | `cadagent.survey` | 4 | 四/七参数变换、高斯正反算 |
  | `CadAgent.Plugin.Road` | `cadagent.road` | 3 | 平曲线要素、竖曲线要素、土石方量 |
  | `CadAgent.Plugin.Structure` | `cadagent.structure` | 3 | 梁柱板配筋、基础、截面校核 |
  | `CadAgent.Plugin.Water` | `cadagent.water` | 3 | 渠道、涵洞、坝、消力池水力计算 |

新增领域插件只需实现 `IPlugin` 并放入插件目录，重启面板生效。

## 领域技能（skills/ 按需注入）

领域知识以 **`skills/*.md`** 形式提供，运行时注入 system 提示，由 LLM 据此组合现有工具。框架不含任何领域专有代码，增删技能文件即生效。

技能文件为纯自然语言指令（触发条件 + 标准流程 + 常用操作 + 注意事项），零侵入、可扩展。内置 9 个技能：`SKILL.md`（通用绘图）、`surveying.md`（测绘）、`architecture.md`（建筑）、`mechanical.md`（机械）、`electrical.md`（电气）、`piping.md`（管道）、`road.md`（道路）、`structure.md`（结构）、`water.md`（水利）；`skills_state.json` 控制各技能开/关。

## 多模态（让 AI 直接「看」图）

- **📸 截图**：截取当前 CAD 主窗口为图片，作为视觉上下文随指令发出。
- **🎯 指定上下文**：选「点 / 对象 / 句柄」去图里拾取，返回 WCS 坐标 / 实体类型+句柄+图层+包围盒 / 句柄解析，并自动附带截图；后续指令据此精准操作（如「把刚才选的圆放大 2 倍」）。
- `screenshot_cad` 工具开放给模型，推理中可自行截图查看图纸（需视觉模型）。

## 安全防护

| 护栏 | 位置 | 说明 |
|---|---|---|
| 危险命令分层拦截 | `CadCommandGuard` | 对 `send_command`/LISP 字符串做 CRITICAL/HIGH 分级拦截（如清库、退出、格式化类命令） |
| 指令预检网关 | `InstructionGate` | 模糊/不完整指令自动规格化；`EnableClarification` 默认开，必要时反问澄清 |
| 防死循环 | `DoomLoopDetector` | 检测重复工具调用，连续告警达阈值后终止，防止模型空转刷 API |
| 危险操作确认 | `delete_entity` 等 | 写/删操作需显式 `confirm=true` |

## 长会话稳定性（治卡死 / 膨胀 / 丢上下文）

1. **运行隔离（治卡死）**：整个主循环放进后台线程，LLM 推理/压缩/记忆读写脱离 UI 线程；CAD 工具执行封送回主线程，主线程不被长操作冻住。
2. **上下文压缩（治膨胀）**：`ContextCompressor` 超预算时把最旧轮次浓缩为摘要，history 有界。
3. **持久化记忆（去进程依赖）**：`FileMemoryStore` 把记忆落盘——`MEMORY.md`（项目规范，每次会话注入，出的图天然合规）+ `checkpoint.json`（每轮对话历史，**CAD 崩溃或重载后可恢复上下文**）。
4. **L3 进程韧性**：`FileCommandQueue`（磁盘持久化命令队列，SessionId 区分本会话/孤儿）+ `CadHealthMonitor`，CAD 崩溃后命令可重放，外部入站调用也可持久化追踪。

## 目标裁判 + 通用编排

- **目标裁判 `GoalReviewer`**：模型给出最终文本时，以「用户目标 + 全部工具结果」独立复核（temperature 0，关 tools），发现遗漏自动续作（最多 2 次防死循环）；评审失败保守放行，绝不阻断任务。
- **通用分步编排 `Planner`**：勾选「分步编排」后，先把目标分解为有序步骤（≤8 步），逐步执行且每步自带阶段裁判，全部完成后整体复核。规划失败退化为单步 ReAct（增强而非必需）。

## 界面与交互

- 面板为 **PaletteSet 侧边栏**：支持**自动隐藏**（图钉按钮收成一条）、**首次默认右侧停靠**，可拖到左侧或浮动（AutoCAD 自动记忆位置）。
- 「⚙ 设置」区涵盖：模型库（厂商 / 档案 / 三角色 / 查询模型）、API 密钥（DPAPI 加密）、用量统计、技能开关、**入站 MCP 完全访问开关与状态**。

## 多宿主支持

同一套逻辑可加载到不同 CAD 平台，由 `CadAgent.Host.*` 适配层隔离差异：

- **AutoCAD 2026**（主目标）
- **中望 ZWCAD 2024+**（`CadAgent.Host.Zwcad` + `forZWCAD.bundle`）
- **浩辰 GstarCAD 2024+**（`CadAgent.Host.GstarCAD` + `forGstarCAD.bundle`）

AutoCAD 托管 API 引用通过 NuGet 包 `ChristianDimitri.Autodesk.AutoCAD` 获得，无需本机安装 ObjectARX SDK（仅编译期引用程序集，运行时由对应 CAD 提供）。

## 环境前提

- **.NET 8 SDK**（net8.0；net48 目标需 .NET Framework 4.8 开发包）
- 任一受支持 CAD：**AutoCAD 2026** / **ZWCAD 2024+** / **GstarCAD 2024+**
- 支持任意 OpenAI 兼容国产大模型（DeepSeek / 智谱 / 通义 / Kimi / 豆包 等）

## 编译

```bash
dotnet build CadAgent.slnx -c Release
```

产物（net8.0-windows）：`src/CadAgent.AutoCAD/bin/Release/net8.0-windows/CadAgent.AutoCAD.dll`
（net48 目标另有 `bin/Release/net48/CadAgent.AutoCAD.dll`）

> 若 AutoCAD 工程编译报与 `_wpftmp` 临时副本相关的假阳性错误，清理该工程 `obj/bin` 后重建即可。

## 配置大模型

推荐用环境变量（密钥不入库）：

```bash
set CAD_AGENT_API_BASE=https://api.deepseek.com/v1
set CAD_AGENT_API_KEY=sk-你的密钥
set CAD_AGENT_MODEL=deepseek-chat
```

也可在 `appsettings.json` 填写（优先级低于环境变量）。面板「设置 → 模型」区还可通过厂商下拉快速选预置、查询真实可用模型、配置三角色路由。

## 加载与部署

**方式 A：NETLOAD（调试）**
1. 启动 CAD，打开一张图；
2. 命令行 `NETLOAD` 选中 `CadAgent.AutoCAD.dll`；
3. 输入 `CADAI` 打开面板。

**方式 B：.bundle 自动加载（启动即加载）**
把编译产物与 `PackageContents.xml` 放入插件目录：

```
%APPDATA%/Autodesk/ApplicationPlugins/CadAgent.for2025-2027.bundle/
├── PackageContents.xml
└── Contents/
    ├── CadAgent.AutoCAD.dll
    ├── CadAgent.Core.dll
    ├── (Host.* / Plugin.* 按需)
    └── appsettings.json
```

`deploy/` 下提供三套模板：`for2025-2027.bundle`（AutoCAD）、`forGstarCAD.bundle`、`forZWCAD.bundle`。放置后 CAD 启动即自动加载，命令行 `CADAI` 随时唤出面板。

## 扩展

- **新 CAD 工具**：`ToolDefinitions.cs` 加 `Def(...)` + `CadTools.*.cs` 的 `Dispatch` switch 加分支（事务写实体），Core 与 CAD 解耦。
- **新插件**：实现 `IPlugin` 放入插件目录，ALC 隔离加载。
- **新技能**：在 `skills/` 加 `.md` 文件，重启面板生效。
- **新模型**：面板「模型库」添加档案（填厂商/地址/密钥/能力开关），或在 `BuiltInModels` 增预置。

## 测试

`src/CadAgent.Tests`（322 用例）覆盖工具目录、降级链、MCP 入站只读/完全访问不变量、模型路由、稳定性、学习能力、参数化模板引擎、道路/结构/水利/测绘数学等；`src/CadAgent.AutoCAD.Tests`（49 用例）覆盖消息项、主题助手、脚本加载安全扫描。**合计 371 用例全过**。

```bash
dotnet test src/CadAgent.Tests/CadAgent.Tests.csproj -c Debug
dotnet test src/CadAgent.AutoCAD.Tests/CadAgent.AutoCAD.Tests.csproj -c Debug
```

## 合规与红线

- 框架代码与内置工具均为自研/基于公开教材与通用公式独立实现；**不引用、不复制任何第三方专有工程或内部项目代码**，不出现真实项目名/内部文档引用。
- 插件与技能仅承载领域通用知识（如公开测量公式），不捆绑受版权保护的资料。
- 入站 MCP 默认只读，完全访问需显式开启且仅限本机可信环境。