# AlphaCAM MCP 桥接器 — AI 驱动的 CAM 自动化

通过 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 让 AI 助手直接操作 **AlphaCAM 2016 R1**。

## 概述

本桥接器将 AlphaCAM 2016 R1 的 COM API 封装为 MCP 工具，使 AI 能够实时：
- 创建/读取/修改几何图形（线、圆、矩形、多边形、椭圆）
- 执行加工操作（粗精加工、轮廓铣槽、雕刻、钻孔等）
- 管理刀具和刀具路径
- 处理排版嵌套（Nesting）
- 运行 VBA 宏
- 输出 NC 代码

## 文件说明

| 文件 | 说明 |
|---|---|
| `server.py` | MCP 桥接器主程序（Python），通过 STDIO/SSE 协议与 AI 通信 |
| `alphacam_com.py` | AlphaCAM COM 自动化封装层（含 VBA 模块管理、自动重连） |
| `DOCUMENTATION_INDEX.md` | AlphaCAM 全部 33 个 .chm 文档的索引目录（含分组和转换状态） |
| `chm/` | .chm 文档目录（含指向安装目录的符号链接 + 已转换的 _html 子目录） |
| `tools/` | **CDM 模块的部署与诊断工具**：审计/部署/编译探针、GBK 读源码、数据库查询、排版结构导出、标签配对复演、窗口清理。见 [`tools/README.md`](tools/README.md) |
| `CCC功能/` | VBA 插件合集目录（依边界裁剪、全排版刀具偏移、排版刀具排序） |
| `CDM功能/` | CDM 自动化模块（`modAutoImportNest.bas` v1.9：导入 + 排版 + 标签重生成、`Events.bas` 菜单注册、`Make.bas` 原源码，以及数据库/流程分析文档） |
| `RevNest_source/` | RevNest 反向排版 v1.2 插件完整源码（从 AlphaCAM 提取）——**本地目录，未纳入版本控制** |
| `RevNest_API参考.md` | RevNest 反向排版的 API 参考 |
| `VBA操作问题记录.md` | VBA/COM 操作踩坑与规避手册（含 CDM.arb 损坏、屏幕刷新泄漏、`ReadTextFile` 盲读 CTX、VBA 重写长小数字面量、`Path` 的 rapid 段数据陷阱、MsgBox 关不掉与自动化姿势等） |
| `open_vba_editor.py` | 自动激活/最大化 AlphaCAM 窗口并打开 VBA 编辑器（Alt+F11） |
| `install.bat` | Windows 一键安装脚本 |
| `install_ccc.py` | 把 `CCC功能/` 的模块安装进 AlphaCAM |
| `install_vba.py` | VBA 代码安装脚本 —— ⚠️ 路径**硬编码指向另一个工程**，已失效，仅作留档 |
| `backup_cdm_arb.py` | 一键备份 `CDM.arb`（含 OLE 完整性校验与 `--keep N` 轮转） |
| `make_icons.py` | 生成工具栏 BMP 图标的工具 |
| `update_adoor_mirror.py` | 更新 AdoorEvents 模块：`L0orR1 = 0` 时按竖直中线镜像门型 |
| `SKILL.md` | MCP 技能定义 |
| `requirements.txt` | Python 依赖 |

> **改 CDM 模块请走 `tools/` 的部署闭环**：`running_snapshot.py` 存基线 →
> `component_deploy.py audit`（运行版 / 仓库 / 基线三方比对，不等于其中之一就拒绝写）→
> `deploy`（整体替换 + 读回校验 + 失败回滚）→ `deploy_probe.py`（标记断言 + 全工程编译探针）。
> 比较一律大小写不敏感：VBA 会把成员名归一化（`.Add` → `.add`）。

## 安装

### 前提条件

- Windows 7+ / 10 / 11
- AlphaCAM 2016 R1 已安装
- Python 3.10+（需要 `pywin32` 和 `mcp` 库）

### 快速安装

```bash
# 安装 Python 依赖
pip install -r requirements.txt

# 双击运行 install.bat，或手动注册到 AI 客户端的 MCP 配置
```

### 手动配置

在 AI 客户端的 MCP 配置文件中添加：

```json
{
  "mcpServers": {
    "alphacam-bridge": {
      "command": "python",
      "args": [
        "C:\path\to\server.py",
        "--progid",
        "aroutaps.Application"
      ]
    }
  }
}
```

## MCP 工具清单（69 个）

### 状态与信息（2）
| 工具 | 说明 |
|---|---|
| `get_status` | 检查 AlphaCAM 连接状态、版本、路径 |
| `get_drawing_info` | 获取当前图纸详情（几何数、路径数、图层、操作数） |

### VBA 与插件（9）
| 工具 | 说明 |
|---|---|
| `run_vba_macro` | 运行 VBA 宏（支持传参） |
| `run_vba_line` | 直接执行一行 VBA 代码（自动创建临时模块） |
| `list_vba_modules` | 列出 VBA 项目中所有模块名称和类型 |
| `get_vba_code` | 读取指定 VBA 模块的完整源代码 |
| `install_vba_module` | 安装 VBA 模块（从源码，覆盖同名模块） |
| `delete_vba_module` | **删除 VBA 模块**（按名称清理多余模块） |
| `load_addin` | 加载插件 DLL / VBA 项目 |
| `enable_addin` | 启用/禁用插件 |
| `list_addins` | 列出已加载的全部插件 |

### 路径信息与变换（3）
| 工具 | 说明 |
|---|---|
| `get_path_info` | 读取路径详细信息（包围盒、元素数、前10个元素的端点坐标） |
| `move_path` | 移动路径（局部 MoveL 或全局 MoveG） |
| `rotate_path` | 旋转路径（指定角度和中心点） |

### 文件操作（7）
| 工具 | 说明 |
|---|---|
| `new_drawing` | 新建空白图纸 |
| `open_drawing` | 打开 `.amd` 文件 |
| `open_dxf` | 打开 DXF/DWG 文件 |
| `open_step` | 打开 STEP 文件 |
| `open_stl` | 打开 STL 文件 |
| `save_drawing` | 保存图纸（可另存为） |
| `output_nc` | 输出 NC 代码到文件 |

### 几何创建（7）
| 工具 | 说明 |
|---|---|
| `create_rectangle` | 创建矩形（指定两角点） |
| `create_circle` | 创建圆（指定直径和圆心） |
| `create_circle_3pts` | 创建圆（指定三点） |
| `create_line` | 创建直线（指定两端点） |
| `create_polygon` | 创建正多边形（指定边数/半径） |
| `create_ellipse` | 创建椭圆（指定长/短轴） |
| `create_text` | 创建文字标注 |

### 几何查询（1）
| 工具 | 说明 |
|---|---|
| `get_all_geometries` | 列出全部几何的完整信息（类型、范围、属性） |

### 查询列表（3）
| 工具 | 说明 |
|---|---|
| `list_geometries` | 列出所有几何图形 |
| `list_operations` | 列出所有操作 |
| `list_toolpaths` | 列出所有刀具路径 |

### 删除（2）
| 工具 | 说明 |
|---|---|
| `delete_selected` | 删除选中的几何 |
| `delete_all_geometries` | 删除全部几何（保留刀具路径） |

### 裁剪（1）
| 工具 | 说明 |
|---|---|
| `trim_with_boundary` | 以边界裁剪线段 |

### 加工操作（1）
| 工具 | 说明 |
|---|---|
| `run_machining` | 执行加工（粗精加工、轮廓铣槽、雕刻、钻孔、啄钻、攻丝、镗孔），完整控制进给/转速/深度 |

### 刀具（2）
| 工具 | 说明 |
|---|---|
| `select_tool` | 从库中选择刀具 |
| `get_current_tool` | 获取当前刀具信息 |

### 工作平面与图层（3）
| 工具 | 说明 |
|---|---|
| `create_workplane` | 创建工作平面 |
| `set_workplane` | 设置当前工作平面 |
| `create_layer` | 创建或获取图层（可设颜色） |

### 视图控制（5）
| 工具 | 说明 |
|---|---|
| `view_zoom_extents` | 缩放全图适应屏幕 |
| `view_zoom_window` | 框选窗口缩放 |
| `view_set_direction` | 设置 3D 视角方向（俯视/前视/等轴测等） |
| `lock_acam` | 禁用屏幕刷新（批量操作时加速） |
| `unlock_acam` | 恢复屏幕刷新（可选缩放全图） |

### 材料（1）
| 工具 | 说明 |
|---|---|
| `get_material` | 获取当前图纸材料信息（名称、密度、进给、转速等） |

### 路径操作（5）
| 工具 | 说明 |
|---|---|
| `mirror_path` | 沿直线镜像路径（几何/刀具路径） |
| `offset_path` | 偏置封闭路径（左/右侧，指定距离） |
| `copy_temporary_store` | 复制路径为临时几何，可镜像后存储 |
| `get_path_attributes` | 读取路径的用户属性 |
| `set_path_attribute` | 设置路径的用户属性 |

### 排版信息（3）
| 工具 | 说明 |
|---|---|
| `has_nesting` | 检查当前图纸是否包含排版信息 |
| `get_nesting_info` | 获取排版详情（Sheet、零件、实例数据） |
| `get_sheet_extents` | 获取全部排版 Sheet 的全局范围 |

### 操作排序（2）
| 工具 | 说明 |
|---|---|
| `order_operations_all` | 按排版 Sheet 顺序自动排序所有刀具路径 |
| `order_manual` | 手动指定顺序重排几何/刀具路径 |


### 后处理器（1）
| 工具 | 说明 |
|---|---|
| `select_post` | 选择后处理器 |

### API 文档（5）
| 工具 | 说明 |
|---|---|
| `list_docs` | 列出文档来源目录及分类，**含 CHM 索引状态**（显示全部 33 个 .chm 已转换/待转换状态） |
| `search_docs` | 按关键词搜索，**支持 CHM 描述搜索 + 内容片段预览 + 60 秒缓存** |
| `read_doc` | 读取指定文档页全文（支持 max_len 控制 token 消耗） |
| `chm_to_html` | 单文件转换：将 `.chm` 编译帮助文件转换为 HTML |
| `chm_to_html_all` | **批量转换**：一键转换全部未处理的 20 个 .chm 文件到 `chm/{Key}_html/` |

> 文档搜索自动检测 AlphaCAM 安装目录，覆盖 **tempacamapi**（VBA API）、**ACAM3**（3D 模块）、**ACAM4**（4 轴模块）等所有已提取的 HTML 文档。
>
> CHM 索引系统注册了 **33 个唯一 .chm 帮助文件**，包括 CDM（橱柜设计模块）、APM、ModuleWorks 5 轴加工等。搜索时会同时匹配 CHM 描述和已解压的 HTML 内容。
>
> 使用 `chm_to_html_all` 可一键解压全部 .chm，解压后的 `_html` 目录自动纳入文档搜索路径。

### 实用工具（6）
| 工具 | 说明 |
|---|---|
| `set_undo_point` | 设置撤销点 |
| `zoom_all` | 缩放全图 |
| `run_workflow` | 批量执行多步骤工作流 |
| `list_layers` | 列出所有图层（颜色、可见性） |
| `close_drawing` | 关闭当前图纸（不保存） |
| `shell_command` | 执行系统命令或脚本 |

## VBA 插件功能

> **关于 .arb 文件**：AlphaCAM 的插件以 `.arb`（Add-in Resource Bundle）格式发布，它是一个包含 VBA 源码、窗体、图标和菜单定义的资源包。**.arb 文件必须先被 AlphaCAM 加载（通过菜单或 `load_addin` 工具）**，然后才能通过 `list_vba_modules` 列出模块、通过 `get_vba_code` 读取源码。MCP 无法直接解析 .arb 文件格式，必须经由 AlphaCAM 的 VBA 编辑器接口间接读取。

`CCC功能/` 目录包含 VBA 工具（通过 AlphaCAM 菜单栏 "CCC功能" 访问）：

| 文件 | 功能 |
|---|---|
| `Events.bas` | 插件入口，注册"CCC功能"菜单 |
| `modTrim.bas` | **依边界裁剪** — 选择边界和线段，将线段超出边界的部分裁剪 |
| `modOffset.bas` | **全排版刀具偏移** — 按刀具名称选择，整体偏移 X/Y/Z |
| `modSort.bas` | **排版刀具排序** — 按加工方式+刀具分组，拖拽调整加工顺序 |
| `modMirror.bas` | **反面镜像** — 自动镜像排版 Sheet 几何生成反面（X 轴或 Y 轴镜像） |
| `modRamp.bas` | **斜角下刀**（v2.0）— 把切断刀路重建成带斜向下刀的刀路：斜坡**锚定在轮廓末端**，使吃刀负载在闭合点归零（板件在负载最小处被切离）；可选**微连接（留连接点）**与**小件降档降速**。小条范围填 `0` = 处理全部闭合刀路。见 [`开料小板件吸附与斜下刀算法分析.md`](开料小板件吸附与斜下刀算法分析.md) |
| `modTest.bas` | 通用测试入口（CCC 菜单「【测试】」：显示选中刀路的包围盒/中心） |
| `frmToolOffset.txt` / `frmToolSort.txt` / `frmRamp.txt` | 各对话框的窗体定义（AlphaCAM 不支持导入 .frm，控件需手工添加） |

### CDM 橱柜门自动化

`CDM功能/` 目录包含 CDM（Cabinet Door Manufacturing）自动化模块：

| 文件 | 功能 |
|---|---|
| `modAutoImportNest.bas` | **自动化生产排版**：导入 CSV 门板数据 → `g_Make_Master` 批量生产+排版；菜单入口弹 `frmAutoNest` 窗体，支持"只导入订单"；v1.10 起窗体可选材料并覆盖 CSV 材料列 |
| `frmAutoNest.txt` | 自动化生产排版窗体代码（手动创建窗体后粘贴，含"只导入订单"勾选框、v1.10 材料下拉） |
| `Events.bas` | CDM 工程菜单注册（含 "自动化生产排版" 按钮） |

自动化流程（已在 CDM 工程中运行验证）：

```
菜单 → CDM → 自动化生产排版（弹出 frmAutoNest 窗体，CSV 路径 + 材料记忆回填）
  → 选择/输入 CSV 文件 + 选择材料（v1.10，下拉自 AD_MATERIALS）→ 确定
  → 客户名"自动化生产"（自动创建）
  → 创建订单（重名直接取消）
  → 逐行导入门板明细（材料 = 窗体选中的那个，忽略 CSV 材料列）
     ├── 门型已存在 → 用其 UserStyle（900/930）
     │     930 门型（如平板PETA）→ 复制 UserStyleName + UserValue_0~6
     │     正确加载用户样式宏（AD_OnePanelSquare 等）
     └── 新门型 → 创建为 900 标准镶板门
  → 勾选"只导入订单，不生产排版"？
     ├── 是 → 仅导入订单，流程结束
     └── 否 → g_Make_Master 批量生产 + 排版 + NC 输出
```

> **关键技术点**：930 用户自定义门型的几何由 VBA 宏生成，导入时必须复制
> `StyleName=UserStyleName`（宏项目名）和 `UserValue_0~6`（宏参数），否则报"无法连接用户定义的宏"。
>
> **材料来源（v1.10）**：窗体上的材料下拉列出 `AD_MATERIALS` 全部材料，**选中的材料对整批生效、
> 忽略 CSV 第 13 列**；模块形参 `sMaterialOverride` 为空时才回退到旧的逐行 CSV 取材料。
> 无论哪条路径，材料都必须已存在于材料库 —— 只校验、绝不自动建档。

### 🧩 VBA 窗体/控件编程（VBIDE 对象模型）

通过 COM 访问 AlphaCAM 内置 VBA **扩展对象模型（VBIDE）**，可以编程创建/修改窗体控件、
读写窗体代码，**无需手工拖拽控件**：

```
链路: Application.VBE → VBProjects → VBComponents("窗体名")
        ├─ .Designer            （窗体设计器 → 控件集合）
        │     └─ .Controls.Add(ProgID, 名称)   ← 添加控件
        └─ .CodeModule          （窗体代码）
              ├─ .Lines / .DeleteLines / .AddFromString
```

```python
proj = com._get_vba_project()
comp = proj.VBComponents('frmAutoNest')
d = comp.Designer

# 添加 CheckBox 并设置属性（ProgID 来自 Microsoft Forms 2.0 库）
cb = d.Controls.Add('Forms.CheckBox.1', 'chkOnlyImport')
cb.Caption = '只导入订单，不生产排版'
cb.Left = 78; cb.Top = 54; cb.Width = 200; cb.Height = 18

# 替换窗体代码（先备份，失败回滚）
cm = comp.CodeModule
backup = cm.Lines(1, cm.CountOfLines)
cm.DeleteLines(1, cm.CountOfLines)
cm.AddFromString(code)
```

要点：

- 常用控件 ProgID：`Forms.CheckBox.1` / `Forms.TextBox.1` / `Forms.CommandButton.1` / `Forms.Label.1` / `Forms.ListBox.1`
- **顺序关键**：先 `Controls.Add` 添加控件，再更新引用该控件的代码；反过来会编译报"找不到方法或数据成员"
- 可读取现有控件坐标（`c.Left` / `c.Top` / `c.Width`）来定位新控件，无需猜测布局
- 前提：AlphaCAM 运行中、目标工程未锁定（未保护）
- 受限：AlphaCAM VBA 不支持导入 `.frm` 设计文件，**窗体本体需先在 VBA 编辑器中手动创建一次**（之后的设计与代码均可全自动）

### RevNest 反向排版

`RevNest_source/` 目录包含从 AlphaCAM 2016 R1 `ReverseNest.arb` 插件提取的完整源码，
实现排版零件的反面镜像生成。详见 [`RevNest_API参考.md`](RevNest_API参考.md)。

> **注意**：该目录是提取来的第三方插件源码，**未纳入版本控制**（`.gitignore` 已排除），
> 全新 clone 里不会有它；本地需要时从 `ReverseNest.arb` 重新提取。

## 操作规范

### 🪟 窗口管理（最高优先级）

| 规则 | 说明 |
|---|---|
| ✅ **允许** 调整图形视图窗口 | `view_zoom_extents`、`view_zoom_window`、`view_set_direction`、`zoom_all` |
| ❌ **禁止** 改变主窗口大小 | 绝不设置 `Width` / `Height` |
| ❌ **禁止** 移动主窗口位置 | 绝不设置 `Left` / `Top` |
| ❌ **禁止** 改变主窗口状态 | 绝不设置 `WindowState`（最大化/最小化/还原） |
| ⚠️ `Visible` 仅按需设置 | 仅在连接时根据 `ALPHACAM_VISIBLE` 环境变量设置一次 |
| 🛡️ 释放 COM 时不改窗口 | `_cleanup()` 不会设置 `Visible` 或任何窗口属性 |

所有视图缩放/方向操作均通过 `Drawing.ViewWindow` 进行，不影响主窗口布局。

### 🔌 连接规范

| 规则 | 说明 |
|---|---|
| 自动重连 | COM 断开后指数退避重连（最多 5 次，间隔 1s→2s→4s→8s→16s） |
| 僵尸检测 | `_check_alive()` 双层探测（Name + ActiveDrawing），防止误判 |
| 状态回调 | 连接状态变化通过 `set_state_callback()` 通知 |
| 多实例支持 | 通过 `--progid` 参数指定不同 ProgID 切换实例 |
| VBA 工程定位 | `_get_vba_project()` 自动定位：ActiveVBProject → CDM 工程 → 首个工程 |

### 🖥️ VBA 编辑器自动化

用户已授权 AI 在需要时自动打开 VBA 编辑器：

| 操作 | 方式 |
|---|---|
| 激活+最大化窗口 | `open_vba_editor.py`（user32 SetForegroundWindow + ShowWindow SW_MAXIMIZE） |
| 打开 VBA 编辑器 | 发送 Alt+F11 快捷键 |
| 读取/写入模块 | 直接通过 `get_vba_code` / `install_vba_module`，无需打开编辑器 |

### 📐 几何操作规范

| 类型 | 空间 |
|---|---|
| 几何图元 | 在工作平面（Workplane）坐标系中创建 |
| 图形视图 | 可通过 `view_*` 工具缩放/平移/旋转视角，不影响实际坐标 |
| 图层 | 通过 `create_layer` 创建和命名图层，支持 RGB 颜色设置 |

## 日常维护

### 🗄️ 备份 CDM.arb（推荐定期执行）

`CDM.arb` 是 AlphaCAM 的 CDM 插件资源包（OLE 复合文档），**包含全部 VBA 工程源码、窗体与 `Licom/OptionID` 配置**。
AlphaCAM 退出/保存时把内存 VBA 工程写回该文件，**若期间崩溃可能损坏**（`OptionID` 流丢失 →
下次启动报"取得选项ID失败 / 无法打开CDM / Error loading CDM Processing"，CDM 功能全丢）。

一键备份：

```bash
python backup_cdm_arb.py             # 备份到 backup/CDM.arb_<时间戳>.bak
python backup_cdm_arb.py --keep 10   # 只保留最近 10 份
```

脚本自动：复制 `StartUp\CDM\CDM.arb` → `backup/`，用 olefile 校验 `Licom/OptionID` 流完整性，
AlphaCAM 运行中会警告（内存最新改动可能未落盘）。

**崩溃后快速恢复**：
1. 关闭 AlphaCAM
2. 从最近可用的备份恢复：`copy backup\CDM.arb_xxx.bak <StartUp>\CDM\CDM.arb`
3. 重启 AlphaCAM；若恢复版本不含近期代码，用 `install_vba_module` 重装
   `CDM功能/modAutoImportNest.bas` + `CDM功能/Events.bas`，并按
   `CDM功能/frmAutoNest_手动创建.md` 重建 `frmAutoNest` 窗体（详见 `VBA操作问题记录.md` §7.4）

> 已存档版本：`backup/CDM.arb_20260814_ok.bak`（8/14 含全部自动化功能 + OptionID 完好的可用版）

- GitHub: https://github.com/cczzyy-cn/AlphacamMCP
- 问题反馈: https://github.com/cczzyy-cn/AlphacamMCP/issues