PLC 代码注释与交叉引用 Pro

面向自动化工程师、电气调试、产线维护。接手别人留下的博图/SCL 工程时，三件事最耗时间：看懂 SCL 代码、理清变量被谁用、把变量表补上中文注释。这个技能三件事一起干：

• SCL 代码逐行注释：免费，直接粘贴代码即可
• 变量交叉引用表：免费，告诉你每个变量在哪些块/网络被读、被写
• 变量表标准化中文对照表：¥0.05/次，30+ 工控词根映射，输出可直接回填博图/Excel

功能说明

1. SCL 代码注释（免费）：把你贴的 SCL/ST 代码逐段加中文注释——行内注释解释"这行在干什么"，段末注释解释"这一段在工艺上是什么步骤"。不改变任何代码逻辑，只加注释。
2. 交叉引用表（免费）：从你贴的代码或变量清单里提取全部变量，输出"变量名 × 出现位置 × 读/写 × 推测用途"四列表。改造前摸底、删变量前查依赖都靠它。
3. 变量表标准化注释（付费 ¥0.05/次）：调用 30+ 工控词根映射接口（运行/停止/故障/复位/自动/手动/点动/回零/限位/急停/使能/阀/泵/风机/电机/输送/传感器/温度/压力/液位/定时器等），单次最多 100 条，输出 JSON + 可直接粘贴回博图/Excel 的对照表。识别不了的自定义业务词会明确标注"（未识别，请人工确认）"，不瞎编。
4. 安全兜底：涉及安全回路变量（急停、安全门、光栅等）的注释，强制附加"注释仅供参考，安全功能必须按原图纸核对"警示。

适用场景

• 接手离职同事留下的博图工程，SCL 代码没有一行注释
• 改造前摸底：要知道某个变量被哪些块用到，改了会影响谁
• 变量表全是 Motor1_Run、Valve3_Open 这类英文，要补中文注释
• 审计别人的程序：变量命名是否符合规范、有没有定义了没用的死变量
• 写程序交接文档：需要"变量 × 用途 × 位置"的对照表
• 梯形图看不懂，想把网络里的变量先翻译成中文再读逻辑

不适用场景

• 不能直接改你的工程文件：本技能输出的是注释文本和对照表，回填博图需要你手动粘贴或导入，不能上传 .ap1x 工程让本技能直接改。
• 安全功能核对：急停/安全门/光栅等安全回路的最终解释以原图纸和安全手册为准，本技能注释不能作为安全验收依据。
• 非结构化文本：手写扫描件、照片里的程序无法处理，请先转成文本。
• 超大工程：单次处理上限约 500 行代码或 100 个变量，更大的工程请分块贴。

使用方法

三种用法，按需选：

• SCL 注释（免费）：直接贴代码，说「给这段 SCL 加注释」
• 交叉引用（免费）：贴代码或变量清单，说「列一下这些变量的交叉引用」
• 变量表对照（付费）：贴变量名列表（逗号/换行分隔），说「生成中文注释对照表」——先给你看前 5 条免费预览，满意再付 ¥0.05 拿全表

也可以一句话组合：「帮我把这段程序整理成能交接的文档」——会依次输出注释版代码 + 交叉引用表，再询问要不要付费对照表。

参数说明

• mode=csv 时付费结果额外输出逗号分隔三列（变量名, 中文注释, 数据类型猜测），可直接粘贴进 Excel。
• 未给 mode 时默认 json。

触发示例

示例 1
> 用户：给这段 SCL 加注释：IF "Motor1_Start" AND NOT "Motor1_Run" THEN "Motor1_Cmd" := TRUE; END_IF;
> 输出（免费）：逐行中文注释版代码，解释"启动按钮按下且电机未运行 → 发出运行命令"，并标注这是典型自锁启动逻辑的前半段。

示例 2
> 用户：这些变量帮我列交叉引用：Motor1_Run, Valve3_Open, Fault_Light
> 输出（免费）：四列交叉引用表——每个变量在哪个块/网络出现、被读还是被写、推测用途；定义了但没被引用的变量会标"疑似死变量"。

示例 3
> 用户：Motor1_Run,Valve3_Open,Emergency_Stop,Fault_Light,Conv1_FWD 这些生成中文注释
> 输出：先免费给前 5 条预览（如 Motor1_Run → 1号电机-运行/启动）→ 询问是否付 ¥0.05 拿完整对照表（含 CSV 回填格式）。

免费输出格式（SCL 注释 + 交叉引用，每次必给）

【SCL 注释版】
<原代码行>  // <中文注释：这行在干什么>
...
(* ===== 段落注释：<这一段在工艺上是什么步骤> ===== *)

【交叉引用表】
| 变量名 | 出现位置 | 读/写 | 推测用途 |
|---|---|---|---|
| Motor1_Run | OB1/Network2 | 读 | 1号电机运行反馈 |
...
【提示】标准化中文对照表（30+ 词根映射，可回填博图/Excel）需付费接口，¥0.05/次。

付费输出格式（调用 API 后，¥0.05/次）

{
  "count": 5,
  "mode": "json",
  "results": [
    {"var": "Motor1_Run",     "comment": "1号电机-运行/启动"},
    {"var": "Valve3_Open",    "comment": "3号阀-开/打开"},
    {"var": "Emergency_Stop", "comment": "急停"},
    {"var": "Fault_Light",    "comment": "故障/报警-指示灯"},
    {"var": "Conv1_FWD",      "comment": "1号输送带-正转"}
  ]
}

mode=csv 时附追加输出：

变量名,中文注释,类型推测
Motor1_Run,1号电机-运行/启动,Bool
Valve3_Open,3号阀-开/打开,Bool
Emergency_Stop,急停,Bool
Fault_Light,故障/报警-指示灯,Bool
Conv1_FWD,1号输送带-正转,Bool

示例输出（完整样例）

用户输入：

IF "Start_PB" AND NOT "Motor1_Run" THEN
    "Motor1_Cmd" := TRUE;
END_IF;
"Valve3_Open" := "Step_No" = 3 AND "Pressure_OK";

免费输出（不收费）：

【SCL 注释版】
IF "Start_PB" AND NOT "Motor1_Run" THEN          // 启动按钮按下 且 1号电机未在运行
    "Motor1_Cmd" := TRUE;                        // 发出电机运行命令（典型启停自锁的前半段）
END_IF;                                          // 自锁保持通常在下一网络由 Run 反馈完成
"Valve3_Open" := "Step_No" = 3 AND "Pressure_OK"; // 工步走到第3步 且 压力正常 → 打开3号阀

【交叉引用表】
| 变量名     | 出现位置      | 读/写 | 推测用途           |
|---|---|---|---|
| Start_PB   | 行1           | 读    | 启动按钮（输入）   |
| Motor1_Run | 行1           | 读    | 1号电机运行反馈    |
| Motor1_Cmd | 行2           | 写    | 1号电机命令（输出）|
| Valve3_Open| 行4           | 写    | 3号阀开命令（输出）|
| Step_No    | 行4           | 读    | 工步计数器         |
| Pressure_OK| 行4           | 读    | 压力正常信号       |

【死变量检查】无（全部变量均有引用）
【安全提示】本段无急停/安全门类变量。若后续涉及，注释仅供参考，安全功能必须按原图纸核对。
【提示】需要标准化中文对照表（30+ 词根映射、可回填博图/Excel）请走付费接口，¥0.05/次。

付费输出（调用后）：见上方「付费输出格式」JSON + CSV 两段，共 5 条，其中 Conv1_FWD → 1号输送带-正转 这类词根组合由接口的 30+ 词根表映射，保证同词根多处注释一致。

权限与安全

• 收款方式：支付宝 AI 按量付费（A2M 协议），每次成功调用 ¥0.05，由用户在支付宝 App 内授权付款，首次使用需开通 Agent 支付。未付款不返回付费对照表，也不会静默扣费。
• 不索取任何凭据：本技能不需要你的 PLC 工程密码、博图账号、任何密钥。任何要求你提供上述信息的"客服"都不是本技能。
• 代码只用于本次分析：你粘贴的 SCL 代码仅在当前会话内用于生成注释与交叉引用，付费接口只上传变量名列表（vars 参数），不上传代码本体、IP、工艺配方。
• 注释仅供参考：输出为建议注释，回填前请人工过一遍——它省的是敲键盘和读代码的时间，不是替代工程师对工艺的判断。
• 付费放弃处理：402 后用户放弃支付，免费部分照常给全，付费对照表不提供，不做降级编造。

调用流程（必须完整走完四步）

第一步：请求资源（无凭证首调，预期返回 402）

GET https://gk-diagnose-308980-8-1461759720.sh.run.tcloudbase.com/api/plc-annotate?vars=<变量名列表,逗号分隔>&mode=<json|csv|tat>

• vars：变量名列表，逗号分隔，单次最多 100 条。
• mode：可选，默认 json。

第二步：处理 402 响应

收到 HTTP 402 时，从响应头提取 Payment-Needed（Base64url 编码的账单）并原样保存到仅当前用户可访问的安全文件。不得解码改写账单内容。

第三步：发起支付

读取 alipay-payment-skill，按其 402-buyer-pay 流程将账单交给支付宝收银：

alipay-bot 402-buyer-pay --session-id '<当前会话ID>' --file '<账单安全文件>' \
  --resource-url '<第一步的完整URL>' \
  --intent-summary '原始请求：为 PLC 变量表生成标准化中文注释对照表' --method GET

向用户展示收银二维码/链接，由用户在支付宝 App 内授权付款（首次使用需开通 Agent 支付）。

第四步：付款后取回结果（必须执行）

用户付款后，带 Payment-Proof 重放第一步的同一 URL，从响应读 Payment-Validation 确认履约成功，拿到 {"count": N, "results": [...]} 后按 mode 整理输出。全程不向用户暴露支付链接、二维码原文、交易号等中间过程。

异常与错误处理

注意事项

• 先免后付：SCL 注释与交叉引用永远免费且必须先给；变量表对照表先给前 5 条预览，用户确认再发起付费，不得跳过预览直接收费。
• 诚实标注：接口识别不了的自定义业务词（如 KLJ_01）返回「（未识别，请人工确认）」，本技能不编造含义，由人补。
• 词根一致性：同一词根在不同批次调用中注释保持一致（如 FWD 恒为"正转"），跨批次的少量差异属接口词根表更新。
• cURL 直调：任何 HTTP 客户端均可完成第一步与第四步；支付编排必须交给 alipay-payment-skill 的 402-buyer-pay，不要自行实现支付。
• 关联技能：故障排查请用同作者的「工控故障排查诊断 Pro」（slug=gk-diagnose-pay），术语映射请用 /api/term-map 对应技能。