脚本类型与使用边界

浏览器页面脚本：只处理当前画面

页面脚本随 HQ VISU Designer 导出的画面在浏览器中运行，适合页面初始化、当前页变量、对象颜色 / 显隐 / 文本和交互。它不承担服务器定时任务，也不直接连接数据库或 PLC。

Integration Script：受控的服务器侧集成

Integration Script 在 HQControl 管理的隔离执行环境中运行，适合本地计算、定时或事件任务、Tag 桥接、签名 HTTP 入站，以及通过受管 HTTP / PostgreSQL 连接器访问外部系统。它不操作浏览器 DOM，也不直接取得宿主网络和数据库凭据。

按访问对象选择层级

• 需要 DOM、组件或当前页变量：使用页面脚本。
• 需要独立项目页面、历史、报警、当前用户或受控 Tag 读写：使用自写页 SDK。
• 需要定时、签名入站、IO 变化触发或受管外部连接：使用 Integration Script。
• 任何写值都走 HQControl 标准方法，保留权限、唯一 IO Owner 和审计边界。

直接方法与 hqcontrol 模块

简短脚本直接调用 ReadTag、WriteTag、HTTPRequest 等注入方法即可；需要组织公共函数时使用正式模块名 hqcontrol。两种写法都使用同一短期 Invocation 能力，不能绕过沙箱。

• 直接方法适合短脚本和少量读写。
• hqcontrol.get_tag(name) 读取一个 Tag 对象。
• hqcontrol.get_tags(...) 按显式范围批量读取。
• hqcontrol.set_tag_value(name, value, options) 通过宿主写入。
• 批量读取应设置范围和数量上限，避免一次读取过多点位。

import hqcontrol

tag = hqcontrol.get_tag("<device-code>.<tag-code>")
print(tag)

result = hqcontrol.set_tag_value(
    "<device-code>.<writable-tag-code>",
    12,
    {"valueType": "number", "reason": "approved process adjustment"},
)
print(result)

正式解释器与依赖合同

正式执行固定使用发布包内经验证的 Python 解释器和锁定依赖。运行时不允许动态安装包；逐脚本 Python、venv 和自定义工作目录不会改变正式解释器，自定义工作目录会被拒绝。需要新增依赖时，应把依赖纳入发布包的审计、锁定、构建和验证流程。

• 不能用运行时安装依赖作为正式交付步骤。
• 不能通过换解释器、工作目录或本地包目录扩大脚本能力。
• 不能直接使用原始网络库或数据库驱动访问外部系统。
• 外部访问只使用脚本明确声明的受管 HTTP / PostgreSQL 连接器。

上线验收

• 先用只读逻辑和 Dry-run 验证输入、质量、查询范围和错误输出。
• 再在受控验证目标上用 Debug 验证真实副作用。
• 核对超时、并发、冷却、触发器、连接器 revision、幂等键和最近执行记录。
• 模拟远端超时或结果不确定，确认任务不会自动重放副作用。
• 最后启用自动触发，并从 Tag / 外部目标 / 审计记录三处核对结果。