接口与脚本：向第三方系统提供实时数据，并执行系统侧脚本任务

IO State API 的范围和网络边界

• fullCodes 精确读取完整点名；deviceCodes、tagCodes、areaCodes、objectIdentifiers、groupCodes 和 qualities 按各自维度筛选。
• Key 的功能组、设备组和信号组范围使用 <device-code>.<group-code>，避免跨设备命中同名组。
• 第三方只访问 HQControl 主服务入口；数据库、Redis 和 Integration Script 内部服务不是对外接口。
• 跨网段访问应放在 VPN、专线或 HTTPS 反向代理后；代理 WebSocket 时开启 Upgrade。
• 计算 Tag 第一阶段运行值不在 IO State API 中提供。

Tag Bridge 支持的方法

短脚本可直接调用方法；公共封装使用正式模块名 hqcontrol。读取走 HQControl 已采集状态，不会从 Python 再轮询 PLC；写入仍经过唯一 IO Owner、Tag 控制权限和审计。

• 读取：ReadTag、ReadTags、ReadTagBoolean、ReadTagInteger、ReadTagDouble、ReadTagString、ReadTagJson、ReadTagDateTime。
• 质量：ReadTagQuality、ReadTagQualityGood。
• 写入：WriteTag、WriteTagBoolean、WriteTagInteger、WriteTagDouble、WriteTagString、WriteTagJson、WriteTagDateTime。
• 受管外部访问：HTTPRequest、SQLQuery、SQLExecute。

tag_ref = "hq://io/<io-domain-id>/<device-uid>/<tag-uid>"
tag = ReadTag(tag_ref)

if tag and tag.get("quality") == "good":
    print(tag.get("valueNum"), tag.get("sourceTs"))

步骤 1：新建脚本并选择触发器

1. 进入“Integration Script”，新建语义明确的脚本，填写超时、并发上限和冷却时间。
2. 先编写只读逻辑，使用手动运行或诊断查看输出、异常和最近执行记录。
3. 按来源配置定时、签名 HTTP 入站或 IO 变化触发器；逐项写清输入、质量要求和去抖边界。
4. 涉及写 Tag 或外部副作用时，先在受控目标上验证，再启用自动触发。

步骤 2：声明宿主管理的 HTTP 连接器

下面案例假设脚本由签名 HTTP 入站触发，使用该请求的稳定 ctx["requestId"] 作为幂等键。

1. 在脚本右侧打开“连接器”，添加 HTTP，填写语义明确的名称，例如 production-reporting-api。
2. Origin 只填写 scheme、host 和 port。远端目标必须使用 HTTPS，只有 loopback 目标可使用 HTTP。
3. 设置允许方法、超时、并发、请求体和响应体上限。
4. 普通 Header 不得包含凭据；敏感 Header 映射到 HQCONTROL_CONNECTOR_... 宿主环境变量。

tag_ref = "hq://io/<io-domain-id>/<device-uid>/<tag-uid>"
tag = ReadTag(tag_ref)

if tag and tag.get("quality") == "good":
    response = HTTPRequest(
        "production-reporting-api",
        "POST",
        "/v1/measurements",
        body={
            "tagRef": tag_ref,
            "value": tag.get("valueNum"),
            "sourceTs": tag.get("sourceTs"),
        },
        idempotency_key=ctx["requestId"],
    )
    print(response)

步骤 3：声明宿主管理的 PostgreSQL 连接器

下面案例同样假设由签名 HTTP 入站触发：先按入站 planId 查询计划，再把 Good 质量的测量值写入记录表。

1. 添加 PostgreSQL 连接器，例如 production-reporting-database。
2. DSN 只填写 HQCONTROL_CONNECTOR_... 环境变量名，不在脚本或普通配置中写密码。
3. 设置查询超时、最大行数、响应大小和并发上限。
4. 需要 SQLExecute 时显式开启写入，并为每次执行提供稳定幂等键。

tag_ref = "hq://io/<io-domain-id>/<device-uid>/<tag-uid>"
tag = ReadTag(tag_ref)

rows = SQLQuery(
    "production-reporting-database",
    "select shift_code, target_quantity from production_plan where plan_id = $1",
    [ctx["payload"]["planId"]],
)

if tag and tag.get("quality") == "good":
    result = SQLExecute(
        "production-reporting-database",
        "insert into measurement_log(tag_ref, value_num) values ($1, $2)",
        [tag_ref, tag.get("valueNum")],
        idempotency_key=ctx["requestId"],
    )

Dry-run 和 Debug 不是同一种执行

• Dry-run 阻止 WriteTag*、状态改变型 HTTP 和 SQLExecute。
• Dry-run 中的 ReadTag*、HTTP GET / HEAD 和 SQLQuery 仍会真实读取。
• Debug 使用真实执行语义，会产生 Tag 写入、外部 HTTP 和数据库写入等副作用，运行前必须确认目标和输入。
• Dry-run、Debug 和自动触发都经过同一生产沙箱与连接器策略。

生产运行边界

• 原始 Python 网络访问被沙箱阻断；主动 HTTP、数据库、WebSocket 或消息协议访问必须改用已声明的受管连接器，当前正式连接器类型只有 HTTP 和 PostgreSQL。
• 非 GET / HEAD 的 HTTP 和每个 SQLExecute 都必须提供稳定幂等键。
• 外部副作用已派发但结果不确定时，系统不会自动重试；应按 execution identity 核对目标系统后人工处理。
• 正式运行时不能动态安装依赖。解释器和依赖来自经审计、锁定并验证的发布包。
• 逐脚本 Python、venv 或自定义工作目录不会改变正式解释器；自定义工作目录会被拒绝。