PowerMill 宏与插件开发 Skill

面向 PowerMill（Autodesk，前身 Delcam）数控编程的宏语言与二次开发。目标：能读懂任意 .mac、
能按需求写出可直接在 PM 里运行的宏、能批量改造已有宏、能对接官方 .NET API 做插件与外部自动化。

何时用

• 需要自动化 PM 里的重复操作（建刀、建边界、改参数、批处理刀路、出 NC、改坐标、统计时间…）。
• 要读懂/修改工作空间里现成的 .mac 宏。
• 要给一批刀路批量改参数、批量改转速进给、批量重命名、批量后处理。
• 要用 C#/.NET 写 PM 插件或外部自动化程序。

核心心智模型（先理解，再动手）

1. 宏 = PM 命令序列。在 PM 里手动点任何一个按钮/填任何对话框，都会向程序发命令。
   把「命令窗口（View > Window > User Interface > Command Window）」+「Home > Macro > Echo Commands」
   打开，操作一遍，窗口里回显的就是宏要写的命令。命令不区分大小写。
2. 命令记录规则：录制只记录你显式改动的值，不记录当前默认值。想要某值，必须在录制时重新输入一次。
   调试时 UNSET MACROFIX 让 PM 直接报语法/宏错误（SET MACROFIX 恢复）。
3. 宏语言是类 C 的脚本：有类型（INT/REAL/STRING/BOOL/ENTITY/对象/各类 LIST）、表达式、运算符、
   IF/SWITCH/WHILE/DO-WHILE/FOREACH、自定义 FUNCTION、内置函数、对话框。
4. entity 是引用：entity('toolpath','名字') 拿到一个对象引用，用 对象.属性 取值
   （tp.Name、tp.Strategy、tool.Diameter、block.Limits.ZMax…），folder('toolpath') 拿一个类型下所有实体的列表。
5. 命令 vs 函数：EDIT PAR 'xxx' 'yyy'、FORM xxx、CREATE xxx 是命令；
   entity()、length()、add_last()、sort() 是函数，用在表达式里。

标准工作流

A. 写一个新宏

1. 确认需求落点：是改激活对象、改选中对象，还是遍历某类型全部对象？决定用 SELECTED / ;（激活）/
   FOREACH ... IN folder('类型') 哪种。
2. 拿命令：能录就录——在 PM 里开 Echo Commands，手点一遍，复制回显命令。
   记不住参数路径时，EDIT PAR 的属性名可在 PM「参数」面板里右键「复制参数路径」得到。
3. 套外壳（几乎每个生产宏都这么开头结尾）：

// 中文注释建议：部分版本对中文敏感，必要时改 ANSI 编码或删中文注释 DIALOGS MESSAGE OFF DIALOGS ERROR OFF GRAPHICS LOCK ... 主体命令 ... GRAPHICS UNLOCK DIALOGS MESSAGE ON DIALOGS ERROR ON

4. 加健壮性：IF NOT entity_exists(...) { MESSAGE ERROR "..."; MACRO ABORT ALL }。
5. 加交互（按需）：INPUT / QUERY / INPUT CHOICE / INPUT ENTITY / FILESELECT / MACRO PAUSE。
6. 调试：UNSET MACROFIX；花括号配对；{ 前留空格；ELSEIF 不拆写；数字用小数点 . 不是逗号；
   赋值左侧必须带 $。按 ESC 中断循环。

B. 改造已有宏

1. 先按 <references/recipes.md> 的模式识别它在做什么（遍历？选中？模板导入？后处理？）。
2. 定位要改的变量/命令行，保持原有外壳（DIALOGS/GRAPHICS）不动。
3. 只改请求的模块，保留其余命令；改完给一条最小可运行验证路径。

C. 批量处理（最常见的生产诉求）

模式固定：取集合 → 遍历 → 逐个激活 → 改参数 → 重算/提交。见 <references/recipes.md> 的「批量模板」。

语法速查

// 注释用双斜杠
// —— 变量 ——（赋值左侧必须带 $；变量名不区分大小写；必须先用类型声明）
INT i = 5
REAL d = 12.5
STRING s = "hello"
BOOL ok = 1
STRING LIST names = {}                 // 空列表
INT LIST a = {1,2,3}
REAL ARRAY v[] = {0,0,1}               // 固定数组
ENTITY tp = entity('toolpath','1')     // 实体引用
OBJECT blk = block                     // 参数对象集合

// —— 表达式/运算符 ——
// 算术 + - * / ；比较 == != < <= > >= ；逻辑 AND OR NOT
// 优先级见 references/macro-language.md（NOT > 比较 > AND > OR）
$s = "D" + string(i) + "R0"            // 字符串拼接
$v = Tool.Diameter * 0.6               // 直接用 PM 参数参与表达式

// —— 控制流 ——
IF cond { } ELSEIF cond { } ELSE { }
SWITCH $x { CASE 0 ... BREAK  CASE 1 ... BREAK  DEFAULT ... }
WHILE cond { }
DO { } WHILE cond
FOREACH item IN folder('toolpath') { }
FOREACH item IN list { }
BREAK / CONTINUE / RETURN

// —— 函数 ——
FUNCTION Main() { ... }
FUNCTION Sub(STRING LIST lst, output STRING msg) { $msg = ... RETURN }
CALL Sub($lst, $msg)

// —— 交互 ——
STRING s = INPUT "提示语"                       // 输入框
BOOL y = QUERY "是否继续?"                       // 是/否
INT c = INPUT CHOICE $stringlist "请选择"        // 单选
STRING t = INPUT ENTITY tool "选一把刀"          // 选实体
ENTITY LIST l = INPUT ENTITY MULTIPLE toolpath "多选刀路"
STRING f = FILESELECT "选择文件"
MACRO PAUSE "请选择局部位置"                     // 暂停等待用户操作
MESSAGE INFO|WARN|ERROR "文本"
INFOBOX ...                                    // 富文本信息窗（见 recipes）

// —— PM 命令族（示例）——
FORM BLOCK / EDIT BLOCK RESET / BLOCK ACCEPT
CREATE TOOL ; ENDMILL / RENAME TOOL ; "D1" / EDIT TOOL "D1" DIAMETER "10" / TOOL ACCEPT
ACTIVATE TOOLPATH $name
EDIT PAR 'Stepover' 'Tool.Diameter*0.6'
EDIT PAR CREATE REAL "clearance"
RESET SELECTED TOOLPATH FEEDRATE
IMPORT TEMPLATE ENTITY TOOLPATH "xxx.ptf"
PROCESS TPLINKS / LEADS ACCEPT
MACRO "其他.mac"    // 宏中调宏，可带参数
DoCommand $cmdstring  // 把字符串当命令执行（见下）

DoCommand（动态命令，字符串拼好后执行）：

STRING $cmd = 'CURVEEDITOR TEXT SET_TEXT "' + $text + '"'
DoCommand $cmd

关键陷阱（踩过的坑）

• 中文：部分 PM 版本含中文会报错或乱码；宏文件建议存 ANSI，或先删中文注释再运行。
  （实测语料：gbk/ANSI 2660 个、utf-8 2612 个、latin-1 1459 个，三种编码并存——约 61% 非 UTF-8，印证「宏建议存 ANSI」。）
• 刀具类型两种写法并存：endmill/end_mill、ballnosed/ball_nosed、
  tipradiused/tip_radiused。判断时必须 IF c.type=='endmill' OR c.type=='end_mill'，否则漏判一半。
• $ 前缀：赋值左侧必须有 $（$x = 5 对，x = 5 错）；读取时 $ 可省。
• 局部变量覆盖 PM 参数：REAL Stepover = 10 之后，宏内所有 Stepover 都用 10，
  EDIT PAR "Stepover" ... 也改的是这个局部变量，不是 PM 参数。要改 PM 参数就别用同名局部变量。
• 列表输出要加 par：PRINT PAR "aa"。
• folder() 参数区分大小写，且只接受实体类型名：
  MachineTool / NCProgram / Toolpath / Tool / Boundary / Pattern / Featureset / Workplane / Level / Model / StockModel / Group。
• \r：命令回显里出现的 \r 直接忽略即可。
• ; 与 #：命令里 ; 常表示「激活对象」，# 表示「当前对象」（如 ACTIVATE TOOLPATH #）。
• entity 列表：entity list / entity('...') 返回的是引用，能取全部属性；extract() 可从集合提字段。
• ${表达式}：命令参数位置可用 ${} 直接插表达式（EDIT BOUNDARY $x OFFSET ${-offset}）。
• apply() / join()：现场高频使用（224 / 369 次）但不在官方 PDF，属版本相关，跨版本先试。
• ERROR 变量：判断变量是否有效（现场用 2352 次），比 entity_exists 更底层。

参考文档（按需加载，不要一次全读）

两条主路径（按需求选）

路径 A — 把高频小操作变成按钮/快捷键（现场 75% 的宏都是一行命令）

写一行命令宏 → 绑到工具栏按钮或快捷键 → 加进 Macro Paths

读 references/ui-customization.md。三条绑定通道：快速访问工具栏按钮、
键盘快捷键、资源管理器右键自定义菜单；另有启动宏 pmuser.mac 设默认参数。

路径 B — 写套餐级大宏（数百到 3000+ 行）

外部配置 + Main 调度 + 子函数模块 + 状态持久化 + 全程守卫

读 references/advanced-macro-design.md。核心是 FUNCTION/CALL（含 output 引用参数）、
apply()/join()/position() 解析配置、SWITCH 套餐分发、MACRO 宏传参。

两条路径可以叠加：大宏做好后，同样可以绑成按钮；按钮点开的也可以是一个套餐菜单。

写完宏先跑预检

python scripts/check_macro.py 你的宏.mac
python scripts/check_macro.py --dir 某个宏目录

只做语法预检（不理解 PM 语义），能挡掉大部分「一运行就报错」的低级问题。

参考资源（联网）

• Autodesk 宏编程指南（PDF）：https://www.autodesk.com/sites/default/files/file_downloads/PM_Macro_Programming_Guide.pdf
• 离线帮助与宏/插件文档：Autodesk 支持站点 powermill-2024-offline-help-and-macros-and-plugin-documentation
• 在线帮助（变量/命令/函数）：https://help.autodesk.com/view/PWRM/2026/ENU/
• 官方 API 仓库：https://github.com/Autodesk/PowerShapeAndPowerMillAPI（NuGet：PowerMill / PowerShape）
• 设置自定义启动宏（pmuser.mac）：放在 C:\Program Files\Autodesk\PowerMillxxxxx\lib\macro 或用户 pmill 目录下

交付要求

• 产出 .mac 时给完整可运行内容，带最小注释；说明放到 PM 里怎么跑（资源管理器 > 宏 > 运行）。
• 未验证的内容标注「未执行」，并给出在 PM 里验证的具体命令。
• 批量宏必须先做「空集合/未激活」的健壮性判断，避免误改整个项目。