MotionWorks 代码编辑 KphungFROMM/dsh-motionworks-iec-use

MotionWorks Use

一个 DeepSeek Harness 插件，让 AI 代理能够操作正在运行的 Yaskawa MotionWorks IEC 3 Pro IDE——并编辑其代码。

license
platform
node
tools

处理 PLC 项目的代理通常只有两个糟糕的选择：离线读取项目文件（并冒着损坏未记录的二进制格式的风险），或者在 GUI 中到处点击。这个插件为它提供了第三种选择：通过 IDE 自身的自动化 API 驱动 IDE，通过项目容器编辑代码，并获得真实的编译结果。

与 Yaskawa 无关联。 这是一个独立的互操作性工具。
它不附带任何 Yaskawa 项目文件、示例、帮助内容或二进制文件。

目录

- 功能简介
- 无许可证情况下工作
- 要求
- 安装
- 快速开始
- 工具参考
- 工作原理
- 值得了解的 API 事实
- 安全性
- 状态：已验证内容
- 已知限制
- 故障排除
- 贡献
- 许可证

功能简介

让你的代理处理 MotionWorks 项目，它可以：

- 找到它应该与之通信的 IDE，以及其中打开的项目
- 暂存项目副本并在真实 IDE 中打开它
- 读取实时对象模型——POU、语言，以及每个变量及其类型、初始值、IEC 地址和组
- 读取和重写结构化文本主体——这就是“代码”部分
- 添加变量声明
- 编译并报告结果（IsCompiled）
- 读取编译器错误——以图像形式，因为 API 从不将它们作为文本公开
- 查看 IDE——截图，并将错误窗格置于前台

它不是什么

| 不是下载工具 | 它永远不会下载到控制器。不存在这样的工具。 |
| 不是运动工具 | 它永远不会命令运动。不存在这样的工具。 |
| 不是通用 Windows 自动化工具 | 它只会附加到 MotionWorks IEC 3 Pro |
| 不是图形逻辑编辑器 | 梯形图/FBD 主体是专有二进制——参见限制 |
| 不是点击器 | 它通过自动化 API 驱动 IDE，而不是合成输入 |

无许可证情况下工作

使用此插件编辑代码不需要 MotionWorks 许可证。 这是有意为之，因为大多数评估它的人都不会有许可证。

该插件有两部分，只有其中一部分需要 IDE：

| 部分 | 需要已授权的 IDE？ | 工具 |
| 代码——读取、写入、创建、删除、变量 | 否 | mw_ide_stage、mw_code_（10 个工具） |
| IDE — 编译、实时模型、截图、错误 | 是 | mw_ide_（11 个工具） |

代码部分是对项目容器的纯文件 I/O。它在 MotionWorks 关闭、从未安装或未授权的情况下都能工作：

$ mw_ide_stage { source: "C:\Projects\MyMachine" }
$ mw_code_pous # 里面有什么，以及哪些可编辑
$ mw_code_read_st { pou: "Main" }
$ mw_code_write_st { pou: "Main", body: "…", dry_run: false }
$ mw_code_pou_create { name: "Helper", template: "Main" }
$ mw_code_var_add { pou: "Helper", name: "Enable", type: "BOOL" }

许可证所增加的是编译验证——IDE 的编译器及其裁决——外加实时对象模型、错误列表和截图。如果你之后获得了许可证，什么都不会改变：同一个项目、同样的工具，再加上 mw_ide_build。

未授权版本的对话框

未授权的 MotionWorks 会在创建任何窗口之前显示一个模态对话框，而在它被应答之前，IDE 没有任何项目服务——因此 OpenProject 会失败并报 Internal error in 'OpenProject'，这看起来完全像是安装损坏。插件会处理这种情况：

- mw_ide_start 在等待窗口时检测到该对话框并替你点击“Use Trial”，而不是盲目地超时。
- mw_ide_trial 报告对话框的状态，并且可以重试应答它。

如果该对话框是一个激活表单——Activate Online / Activate by Phone / Retry，没有 Use Trial——那么试用期已耗尽，任何自动化都无法继续。这是许可证问题，不是插件缺陷；在获得许可证之前，请使用代码部分。

要求

| 操作系统 | Windows。Mwt.exe 是一个 32 位 Windows 应用；在其他任何地方都无法工作。 |
| MotionWorks IEC 3 Pro | 已安装并已授权。试用版可用，但试用许可证只允许一个实例。 |
| DeepSeek Harness | 带有一个你可以编辑的配置文件（默认为 profiles\desktop）。 |
| Node | ≥ 20。 |
| Python | 你不需要安装它。 代码引擎仅使用标准库，插件会自动发现 AryaAI 已附带的解释器。可用 MW_PYTHON 覆盖。 |

安装

要求： Windows、MotionWorks IEC 3 Pro、Node ≥ 20。

代码引擎需要 Python，但你不必安装它：该引擎仅使用标准库（win32com 是在单个函数内部延迟导入的），并且插件会自动发现 AryaAI 已附带的解释器。MW_PYTHON 可覆盖它；MW_SRC 可将引擎指向另一棵目录树以用于开发。

使用插件管理器

通过 harness 自带的插件管理器安装它，而不是手动安装——它会管理配置文件的依赖和锁文件，而加载器实际读取的正是这些：

plugin_manager install_bundle file:C:\path\to\your\clone

或使用 UI 中的等效操作（Settings → Plugins）。将它指向本仓库的一个克隆，或者指向已发布的包（一旦它存在）。

这一步就能使该包可被解析，并将其记录为配置文件依赖项，并将其作为捆绑包启用。然后重启 DSH——捆绑包在启动时读取，因此这些工具不会出现在安装它们的会话中。

DSH 无法热加载捆绑包；无法在正在运行的会话中激活捆绑包。

不要手动接线

手动创建指向 profiles\\node_modules\ 的联接看起来可行——包能解析，node -e "import(...)" 也能正常加载——但这不是 DSH 解析捆绑包的方式，而且它会主动破坏安装：pnpm 无法管理它不拥有的路径，因此在联接上安装会失败，报错如下

[ERR_PNPM_EPERM] rename '…\dsh-motionworks-iec-use_tmp_…' -> '…\dsh-motionworks-iec-use'

这向用户呈现为“插件启动失败”。如果你已经这样做了，请删除该联接，然后通过插件管理器安装。

内置捆绑包（dsh-better-sidebar、dshmarket、……）根本不在配置文件的 node_modules 中——它们随应用一起发布。只有第三方和本地捆绑包才会安装到配置文件中。

如果你想让智能体了解该工作流，请将 SKILL.md 复制到项目的 .dsh/skills/motionworks-iec-use/SKILL.md。插件提供工具；技能提供流程。

快速开始

在写入代码时，IDE 必须处于关闭状态——它会缓存项目状态并重写整个文件，因此在 IDE 运行时进行的外部编辑会被丢弃。这一单一约束塑造了整个循环：

stage → read → close IDE → write → reopen → build → read errors

在实践中，一个会话看起来像这样：

// 1. Copy the project somewhere safe. Only copies are ever touched.
mw_ide_stage { source: "C:\\Projects\\MyMachine" }

// 2. What is in it, and what is actually editable?
mw_code_pous // 6 POUs — 3 ST (editable), 3 LD (not) mw_code_unsupported // names the ones that CANNOT be edited

// 3. Read the code you are about to change.
mw_code_read_st { pou: "Initialize" }
// → Axis1.AxisNum := UINT#1;
// Axis2.AxisNum := UINT#2;

// 4. Preview the change. dry_run defaults to TRUE — nothing is written yet.
mw_code_write_st { pou: "Initialize", body: "...", dry_run: true }

// 5. Apply it. Backs the file up first, verifies the sibling streams are unchanged.
mw_code_write_st { pou: "Initialize", body: "...", dry_run: false }

// 6. Compile it and read the verdict.
mw_ide_start
mw_ide_open { path: "\\MyMachine.mwt" }
mw_ide_build // { accepted, settled, is_compiled }

// 7. If it failed, look at what the compiler said.
mw_ide_errors // → a PNG path; read it with your image tool

工具参考

IDE 工具（COM）——需要正在运行且已授权的 IDE

| 工具 | 参数 | 作用 |
| mw_ide_status | — | 哪个 IDE 处于活动状态、其版本，以及是否打开了项目。请先调用此项。 |
| mw_ide_start | exe? | 启动 Mwt.exe，检测并应答许可证对话框。关闭后需要执行此操作。 |
| mw_ide_trial | attempt? | 报告许可证/试用对话框，或尝试应答它。 |
| mw_ide_close | — | 关闭并等待直到它真正消失。任何写入之前都必须执行。 |
| mw_ide_open | path | 在真实 IDE 中打开一个已暂存的项目。 |
| mw_ide_pous | — | 带语言代码的实时 POU 列表。 |
| mw_ide_variables | pou? | IDE 的实时变量模型：类型、初始值、IEC 地址、组。 |
| mw_ide_make | — | Compile(1) = adeCtMake。 |
| mw_ide_build | — | Compile(2) = adeCtBuild，然后给出判定结果。这是验证步骤。 |
| mw_ide_errors | pane? | 激活一个输出窗格（Errors、Warnings、……）并捕获它。 |
| mw_ide_screenshot | — | 捕获 IDE 窗口。 |

代码工具 — 无需 IDE，无需许可证

| 工具 | 参数 | 作用 |
| mw_ide_stage | source | 将项目复制到插件自己的 stage/ 中。仅复制——绝不移动或删除。 |
| mw_code_pous | project? | 从文件中获取 POU，带有 has_st_body——即可编辑性测试。 |
| mw_code_read_st | pou、project? | 某个 POU 的 ST 主体及其声明。 |
| mw_code_write_st | pou、body、project?、dry_run?、run_lint? | 重写 ST 主体。dry_run 默认为 true。 |
| mw_code_pou_create | name、template、project?、dry_run? | 通过克隆现有 POU 来创建 POU。 |
| mw_code_pou_delete | name、force?、project?、dry_run? | 删除 POU、其任务分配和注册表项（已归档）。 |
| mw_code_var_add | name、type、pou?、section?、address?、initial_value?、description?、project?、dry_run? | 添加变量声明。 |
| mw_code_var_edit | name、pou?、new_name?、type?、address?、initial_value?、description?、dry_run? | 就地编辑声明。 |
| mw_code_var_delete | name、pou?、force?、dry_run? | 删除声明（在仍被引用时拒绝执行）。 |
| mw_code_unsupported | project? | 列出无法安全编辑的 POU。 |

project 默认为最新的已暂存项目，并且每个代码工具都会拒绝 stage/ 之外的路径。

工作原理

有两个效应器，这是核心设计决策——它是由测量结果强制的，而非出于偏好。

┌──────────────────────── DSH host (index.js) ────────────────────────┐
│ │
│ req.json / res.json req.json / res.json │
▼ ▼ │
┌───────────────────┐ ┌──────────────────────┐ │
│ 32-bit PowerShell │ │ Python (stdlib) │ │
│ bridge │ │ code engine │ │
└─────────┬─────────┘ └──────────┬───────────┘ │
│ COM │ CFB container read/write │
▼ ▼ │
┌───────────────────┐ ┌──────────────────────┐ │
│ Mwt.exe │ │ /POE/** │ │
│ (the live IDE) │ │ (the code) │ │
└───────────────────┘ └──────────────────────┘ │

COM 拥有 IDE。 MotionWorks 注册了一个进程外自动化服务器 Ade.Application.550，而被驱动的正是它。它必须由 32 位客户端驱动 —— Mwt.exe 是一个 32 位的 LocalServer32，而 64 位客户端根本无法创建它的对象。因此需要 PowerShell 桥接。

容器写入器拥有代码 —— 因为自动化 API 无法触及代码。所有三种候选 COM 途径都已尝试过，并且都被封死：

| 途径 | 结果 |
| _Pou 上的正文访问器 | 不存在 —— 35 个成员，没有一个叫 Source/Body/Text |
| ExecuteCommand(CommandId) 来驱动菜单 | 一个桩 —— "The method or operation is not implemented" |
| iec_61131-3_file_export / _import 提供程序 | 无类型的 IDispatch；Execute() 返回 OK 并写入 0 个文件 |

所以代码就在它所在之处被编辑：CFB 容器。写入器只触碰文本形式的 .STB/.VB 流，先备份，并在报告成功之前验证未受影响的同级流逐字节完全相同。

为什么传输方式是文件，而不是管道

受限的测试环境无法打开命名管道，因此管道式子进程会以 EPERM 失败。两个桥接都通过 req.json/res.json 并配合 stdio: 'ignore' 来交换 JSON，这在任何沙箱模式下都能工作。请求被重命名到位，回复则根据 id 进行匹配，因此过期的应答绝不会被误认为当前应答。

值得了解的 API 事实

这些是针对真实安装（自动化版本 1.19）实测得出的，并纠正了若干广泛流传的错误假设。它们被记录在此，因为重新发现它们的代价高昂 —— 也因为其中至少有一条常被错误地陈述。

AdeCompileType 并非网上所说的那样

1 adeCtMake 2 adeCtBuild 3 adeCtPatch 4 adeCtWorksheet 5 adeCtDataTypes

被频繁重复的 "1 = Build，2 = Rebuild" 是错误的。1 是 Make，2 是 Build —— 而且根本不存在 Rebuild 编译类型。Rebuild 是一个 IDE 命令（adeCmdBuildRebuildProject = 36570），而由于 ExecuteCommand 是一个桩，Rebuild 无法以编程方式触达。

其他实测行为

- ApplicationState 不是忙闲指示器。 位 2（adeASCompiling）在一次明显仍在运行的构建开始 0 秒时读作 "idle"。可靠的完成信号是反复重新发起编译，直到 IDE 接受它 —— 忙碌的编译器会以 "Operation not possible while compiler is running." 拒绝。
- 当 Mwt.exe 处于……时，IDE 会将自己命名为 MULTIPROG - 直接启动，这正是自动化所做的事情。按前缀将标题与两个名称进行匹配。
- 启动时会创建带有相同标题的小型辅助窗口，因此窗口搜索必须选择最大的匹配项——否则“截图”会静默返回一个 426×166 的细条。
- 缓存的 COM 代理比 IDE 存活得更久。 在关闭 → 重新打开后，它会失败并返回 0x800706BA，直到连接被探测并断开。
- OpenProject(Name, ConfirmConvert) 接受两个参数。 只传一个会失败，并提示 “找不到重载”。
- POU 语言代码： 1 IL, 2 ST, 3 FBD, 4 LD, 5 SFC, 6 MSFC, 7 FFLD。
- 接口大小： _Application 102 个成员，_Project 43，_Pou 35，_Variable 44，_Variables 16，_VariableGroups 13。
- 编译错误文本不会被暴露。 OutputWindows 集合有 Activate/Clear/AddEntry，但没有读取访问器，因此获取消息的唯一途径是激活该窗格并捕获它。

完整的类型库转储位于 docs/tlb_dump.txt 和 docs/tlb_enums.txt，以及生成它们的脚本。

安全性

这些是在代码中强制执行的不变量——不是愿望。

- 绝不下载到控制器。绝不命令运动。 两者都不存在任何工具、桥接动词或辅助标志。
- 代码工具只接触插件自己的 stage/。 每个路径都经过暂存保护，因此无法打开真实项目树进行编辑。
- mw_ide_stage 只复制。 它从不移动、重命名或删除源文件。
- 写入默认 dry_run: true——第一次调用始终是预览。
- 每次写入前都会备份，如果无法写入备份，则会拒绝写入。
- 每次写入都会验证其同级项未更改，并报告数量。
- 写入时 IDE 必须关闭。 否则引擎会拒绝，因为 IDE 的缓存状态会丢弃该编辑。
- 图形化 LD/FBD 主体会被拒绝，绝不猜测。
- 没有任何操作会隐式调用 Quit。 你的 IDE 会保持原样。

状态：已验证的内容

| 能力 | 状态 |
| 检测活动 IDE | 已验证 |
| 在真实 IDE 中暂存并打开项目 | 已验证 |
| 读取活动 POU + 变量模型 | 已验证（示例中有 6 个 POU、49 个变量） |
| 读取并重写 ST 主体 | 已验证——往返返回的内容与写入内容完全一致 |
| 写入安全性（备份 + 同级验证） | 已验证 |
| 编译并读取判定结果 | 已验证——判定结果已读取；请参阅下面的注意事项 |
| 捕获编译器错误 | 已验证（仅图像） |
| 在无 IDE 且无许可证的情况下完成整个编码工作流 | 已验证——暂存、读取、写入 ST、创建/删除 POU、添加/编辑/删除变量、往返 |
| 自包含 | 已验证——从全新克隆开始即可通过，无需外部路径 |
| 成功编译 | ❌ 从未观察到 |
先说最要紧的、诚实的提醒： 到目前为止每一次构建运行都失败了，而原因不是代码。

两个独立的环境问题，都不在插件本身：

1. 示例需要这台机器上没有的库。 它引用了 RotaryKnife_ASP_v350（以及 DataTypes/Math/Yaskawa/PLCopen_Toolbox_v350 和 Cam_Toolbox_v340），而本机只安装了 v374/v375。每一个无法解析的类型都可追溯到缺失的 ASP：RotaryKnifeStruct、BlendStruct、 CamSyncStruct、ProductBufferStruct、RotaryKnife、RotaryKnifeCamGen、 RotaryKnife_Registration。编辑 @LIBRARY.LST 重新指向它们也无济于事——IDE 在打开时会重写该文件。
2. 这台机器上的 IDE 没有可用的许可证。 它要求激活，因此它永远不会初始化其项目服务，OpenProject 会失败并报 0x80044000 Internal error in 'OpenProject'（已在 IDE 自带的 error.rpt 中确认）。

所以 is_compiled 至今只被观察到为 false。构建动词分别报告 accepted、settled 和 is_compiled，正是为了确保“已编译但失败”绝不会与“从未运行”混淆。

如果你能获得一次干净的构建，那就是新信息——请开一个 issue。

已知限制

| 限制 | 原因 | 变通方法 |
| 无法编写梯形图 / 功能块图主体 | 专有二进制格式，没有公开语法 | 移植一个已知可用的主体；mw_code_unsupported 会指出它们 |
| 编译错误仅以图像形式呈现 | OutputWindows 没有读取访问器 | 使用 mw_ide_errors，然后读取 PNG |
| 无法调用重新构建 | 它是一个命令，而 ExecuteCommand 是桩实现 | 使用 mw_ide_build（Compile(2)） |
| 未暴露 mw_code_var_edit / _delete | 目前只接入了 var_add | 引擎其实两者都有——见路线图 |
| 仅限 Windows | Mwt.exe 是 32 位 Windows 程序 | 无 |
| 试用许可证只允许一个实例 | Yaskawa 许可机制 | 在启动另一个之前关闭 IDE |
| 尚无 POU 创建 / 删除工具 | 尚未接入 | 引擎的 pou_writer 已内置并准备就绪 |

路线图，大致按价值排序： 暴露 var_edit/var_delete，接入 POU 创建/删除/重命名/移动/语言转换（这些在内置引擎和 COM 中都已可用），然后调查上面的库解析问题。

故障排除

| 症状 | 含义 |
| 工具未出现 | DSH 未重启。捆绑包在启动时加载。 |
| no running MotionWorks IDE window; refusing to instantiate | 正确且有意为之。在没有活动 IDE 的情况下实例化 COM 会启动第二个 IDE。请使用 mw_ide_start。 |
| CO_E_SERVER_EXEC_FAILURE（0x80080005） | COM 激活被阻止。在受限的测试环境中，桥接必须从沙箱外部启动——插件会自行处理这一点，所以如果你看到它，请检查 bridge/bridge.log。 |
| The RPC server is unavailable（0x800706BA） | 某个 COM 代理比它的 IDE 存活得更久。应当会自愈；如果没有，请停止并重启桥接。 |
| IdeRunning: MotionWorks is running … | 在 IDE 打开的情况下尝试了写入。请先调用 mw_ide_close。 |
| 首次实际写入时出现 WinError 5 | 备份目录不可写。插件将其指向自身的 backups/ —— 如果你看到此错误，说明该路径不可写。 |
| “截图”很小 | 窗口搜索匹配到了辅助窗口。不应发生；搜索会选取最大的窗口。 |
| 写入显示 applied: false | dry_run 生效了。这是默认行为，不是失败。 |

每个桥接请求和回复都会记录到 bridge/bridge.log —— 出问题时，这个文件是首先要读的。

贡献

参见 CONTRIBUTING.md。它首先讲了两件否则会让你浪费一下午的事：为什么不通过 COM 编辑代码（这样你就不会把双执行器设计“简化”掉），以及你绝不能削弱的五条安全不变量。

node test/verify.mjs # 结构性测试 —— 不需要 IDE
node test/selfcontained.mjs # 无外部路径 —— 不需要 IDE
node test/verbs.mjs # 实时 COM 动词 —— 需要运行中的 IDE
node test/code_loop.mjs # 完整循环 —— 需要 IDE + 你自己的项目

实时测试从 MW_SAMPLE_PROJECT 获取项目，因此本仓库不附带示例项目，也不应添加任何示例项目。

许可证

MIT © 2026 Kim Phung。

与 Yaskawa Electric Corporation 无关联、未获其认可或赞助。“Yaskawa”、“MotionWorks”和“MULTIPROG”是其各自所有者的商标，此处仅用于描述本软件与之互操作的对象。