LadDoc：JSON 格式的 PLC 梯形图文档

一句话定义

LadDoc（Ladder Documentation）是汇智网为 PLC 梯形图定义的 JSON 格式文档：它只描述逻辑——触点、并联、比较、线圈、块调用——不描述坐标、线号与元件编号。这套规范早期文档里也叫 LAD-IR，指的是同一件东西。

它存在的理由是那条断掉的路：梯形图是二维图形，AI 只能输出文本。LadDoc 把图压成可生成、可校验、可 diff 的文档，再由生成器把文档变回博途认识的 SimaticML。

• 一份文档 = 一个块 —— 块（FC / FB / OB）下面分网络，网络下面分梯级，梯级里是一串元素；层次与博途里看到的一致。
• 同一份文档 = 同一份块 —— 线号与元件编号由生成器按网络分配，不由模型填写；逻辑不变，产物一个字都不变，所以能 diff、能进版本库。
• 零 issue 才产出 —— 生成前强制校验：只要有一条 issue 就返回问题清单、不产出 XML，避免把“看起来合理但博途拒绝导入”的块交出去。

一个自锁网络：文档与梯形图对照

下面是直接启动（DOL）FC 的第一个网络 Run command：启动或已运行（自锁），串停机、急停、过载三道“信号正常”，再串一个故障常闭点。左边是这份文档生成的块渲染出来的样子。

对着图读三处就够：并联就是 parallel 加一个 branches 数组，汇合点不需要画、不需要编号；“停机”在逻辑里是常开点，因为 Stop_OK 表示“信号正常”而不是“按钮按下”；反相是 negated 字段，不是另一个元素——校验器因此不需要猜这个常闭点是安全点还是逻辑点。

{
  "title": "Run command",
  "rungs": [
    { "items": [
      { "kind": "parallel", "branches": [
        { "items": [{ "kind": "contact", "operand": { "scope": "global", "path": ["Start_Btn"] } }] },
        { "items": [{ "kind": "contact", "operand": { "scope": "global", "path": ["MotorRun"] } }] }
      ]},
      { "kind": "contact", "operand": { "scope": "global", "path": ["Stop_OK"] } },
      { "kind": "contact", "operand": { "scope": "global", "path": ["EStop_OK"] } },
      { "kind": "contact", "operand": { "scope": "global", "path": ["Overload_OK"] } },
      { "kind": "contact", "operand": { "scope": "global", "path": ["MotorFault"] }, "negated": true },
      { "kind": "output", "coils": [
        { "kind": "coil", "operand": { "scope": "global", "path": ["MotorRun"] } }
      ]}
    ]}
  ]
}

它不做什么

• 不声明数据对象：DB、UDT、标签表不在文档里，逻辑只按名字引用。所以不需要现成工程就能写、能校验；反过来它也不负责创建这些对象。
• 不渲染：把块画成 PNG 是梯形图渲染服务的事——渲染不改变逻辑，只改变你看它的方式。
• 不碰工程：文档不连接博途、不读不写项目。把块导入工程、编译、下载、跑仿真，是网关与仿真服务的职责。

分工：LadDoc 规范与指令目录由 TiaLink 内置（Agent 不用猜 XML 该长什么样），LadDoc 服务负责校验与确定性生成，导入与编译验证由 TiaLink 完成。责任分开的好处是失败可归因——块导不进去是校验没拦住，编译过但时序不对是逻辑错了，图看着对但行为不对与渲染无关。

接着看

LadDoc Cloud（校验 + 生成服务） TiaLink（内置 LadDoc 规范，负责导入与编译） 梯形图渲染（SimaticML → PNG，免装博途） 为什么是 JSON：博客长文