Codesys API MCP V1.5

V1.5 是单一高效率版本：公开 MCP 只提供九个 Workflow V2 工具，项目写入只走一条 fast 热路径。

安装、四类客户端配置、Skill 安装、首次连接验证和常见问题请看 MCP 安装配置使用说明。

零启动与按需复用

MCP 服务启动、工具列表、能力搜索、状态读取和离线 Library 查询不会启动 CODESYS，也不会扫描 watcher、IPC 目录或 WMI/CIM 进程。

• startupAutoLaunch=false
• projectRequestOnDemandLaunch=true
• 第一个项目请求才查找同一项目、同一 profile、同一产品版本和兼容协议的唯一 watcher。
• 找不到可复用 watcher 时，该请求最多启动一个 CODESYS/watcher。
• 并发首请求共享一次发现和启动；暖态请求继续复用，新增启动数为零。
• 同项目旧产品版本 watcher 返回 WATCHER_PRODUCT_VERSION_MISMATCH，不伪装版本、不终止旧进程，也不偷偷启动第二个实例。
• Library 只使用进程内缓存或已有精确暖 watcher 更新缓存；冷态无离线索引时快速返回 LIBRARY_OFFLINE_CACHE_UNAVAILABLE，不会启动 noUI CODESYS 或第二控制面。
• workflow 历史、edit-head、decision grant、task-owned authority 和 Router 状态目录都在首次对应请求时才初始化；tools/list 不创建这些目录或密钥。

产品版本唯一来源是 package.json.version。CLI、MCP 状态、launcher、prepared watcher、ready.signal 和命令结果使用同一产品版本；IPC protocolVersion=2 独立演进。

UNKNOWN_DIRTY 锁的生命周期

副作用未知时，当前 MCP 进程会把该工程锁在当前 watcher、session 和 generation 内，阻止同一运行期继续写入。这个锁只存在于内存：

• MCP 进程结束或重启后，旧锁失效；
• CODESYS/watcher 关闭后，旧锁失效；
• session 或 generation 变化后，旧锁失效；
• 历史 workflow 仍保留 UNCERTAIN 审计状态，但不再形成工程级阻塞；
• 旧 plan、decision token、edit session 和 idempotency key 一律不能复用。

重启后再次指定同一个绝对 .project 路径时，MCP 建立新的 direct binding，现场预读后执行新的 fast workflow。历史 project-quarantines 文件只算旧审计残留，新进程不会把它们加载成锁。

九个公开工具

• codesys_capability_search
• codesys_library_search
• codesys_library_get
• codesys_project_inspect
• codesys_object_get
• codesys_workflow_submit
• codesys_workflow_continue
• codesys_workflow_status
• codesys_delivery_export

旧 direct 工具和独立 open/save/compile 工具不公开。历史 development、standard、formal、draft、prepare、验证升级和完整证据模式均已退休；显式传入旧字段会得到结构化、无副作用的拒绝。

唯一写入热路径

真实修改批次固定执行：

1. 一次现场目标预读；
2. 一次原生命令，并在该命令内确认实际效果和最终原生状态；
3. 一次 compile/check_for_errors；
4. 错误数为零时一次确认保存。

警告会返回但不阻止保存。若同一原生命令完整确认目标状态已匹配且 changed=false/applied=false，直接 PASS，编译和保存均为零；确认缺失、歧义或不可读则失败。普通 PASS 不追加写后 canonical readback、重开、CLEAN、retention、MATCH/SHA 证据、结构证明、证据包、仓库构建或规则审计。

创建、删除、重命名、Task、Library 和 Trace 修改必须在同一原生命令内返回目标路径、类型、动作和最终状态。命令无效果、歧义、异常或副作用未知时返回结构化 FAIL、BLOCKED 或 UNCERTAIN；只有已证明无副作用或 SAFE_TO_RETRY 才能重新执行。

codesys_workflow_continue 只接受既有 planId 和必要的单次 decision token，用于同 scope、intent、change、source identity 和 capability 的决策续接；它不重发 ST，也不升级验证等级。

离线软件发布门槛

类型检查、核心单元测试、热路径计数测试、可移植安装和 npm pack/packlist 检查只保护 MCP 软件包完整性，不进入 CODESYS 请求热路径，也不改变运行性能。

V1.5 不重跑或重新宣称 V1.3 的历史性能统计。codesys_delivery_export 只导出 fast-path 源包，不把它升级成 formal PASS。

所有仓库命令先读取 config/environment-lock.json，并通过锁定运行时包装器执行：

& .\tools\invoke-repository-command.ps1 npm run release:check

该命令验证 V1.5 软件包本身；它不会启动或重启 CODESYS。