先确认 Script 服务可用。代码管理需超级管理员及 integration:manage；Run Test 另需 integration:execute；Python 模块管理另需 system:view 和 system:manage。按顺序完成计算、依赖安装、事件调用与 Tag 读写练习。
先确认 Script 服务可用。代码管理需超级管理员及 integration:manage；Run Test 另需 integration:execute；Python 模块管理另需 system:view 和 system:manage。按顺序完成计算、依赖安装、事件调用与 Tag 读写练习。
位置：配置中心 → script → 代码（Code）。先创建项目，再添加文件。
Project/
├── scripts/
│ ├── __init__.py
│ └── main.py
└── common/
├── __init__.py
└── scaling.py完成标志 两个文件均可选中，路径正确。下方目录仅说明文件结构。
如果结果不一致
将输入量程 0–100 换算为 0–10。
# common/scaling.py
def scale_linear(value, input_min, input_max, output_min, output_max):
if input_max == input_min:
raise ValueError("Input range must not be zero")
return output_min + (value - input_min) * (output_max - output_min) / (input_max - input_min)
完成标志 保存后无输出；下一步由 main.py 调用。
事件调用 main(ctx)；代码页通过 __main__ 分支调用同一函数。
# scripts/main.py
from ..common.scaling import scale_linear
def main(ctx):
value = scale_linear(float(ctx.get("raw", 50)), 0, 100, 0, 10)
print("Scaled value:", value)
return {"scaled": value}
if __name__ == "__main__":
main({"raw": 50})
完成标志 首次输出 Scaled value: 5.0，状态为 Completed；修改输入后输出 2.5。
如果结果不一致
scripts/main.py 使用 from ..common.scaling import scale_linear。若文件位于 scripts/controls/main.py，应使用三个点返回项目包根。绝对导入必须使用项目清单中的实际 package 名称。
完成标志 修改并保存 scaling.py 后，重新运行 main.py 验证结果。跨项目复用须安装依赖，不能直接引用另一项目路径。
依赖按项目安装，不共享准备机或服务器系统 Python 的包。Python 模块页需上述系统设置权限。
完成标志 按已确认的项目运行目标选择内置模块或兼容 Wheel。
内置模块无需下载。其他依赖在匹配目标 OS、CPU 架构和 Python 3.13 的准备机上，按批准的精确版本下载。下列命令仅在准备机执行。
# Run on a preparation machine matching the target OS and CPU, with Python 3.13.
# Replace the version placeholders with your approved exact versions.
python -m pip download --only-binary=:all: --dest ./wheelhouse "psycopg[binary]==<approved-version>" "PyMySQL==<approved-version>"
python -m pip hash "<wheel-file>"
# Optional local verification in a disposable preparation environment:
python -m venv ./dependency-check
# Use dependency-check/bin/python (Linux) or dependency-check\Scripts\python.exe (Windows):
<venv-python> -m pip install --no-index --find-links=./wheelhouse "psycopg[binary]==<approved-version>" "PyMySQL==<approved-version>"
<venv-python> -c "import psycopg, pymysql; print('Dependencies ready')"完成标志 内置模块已列入预览，或目录已有所需 .whl。离线检查应输出 Dependencies ready；仍须在目标项目验证。
优先使用与目标一致的准备环境。必须交叉下载时，明确指定 --platform、--python-version 3.13、--implementation cp、--abi cp313 和 --only-binary=:all:；平台标签必须匹配目标运行环境，不能仅凭 Linux 名称推定 glibc/musl 兼容性。
完成标志 预览列出预期变更，无兼容性、版本或缺失依赖错误。项目运行环境尚未改变。
核对预览后提交。新项目可先安装模块供代码页运行；已有运行版本时，检查通过后应用新版本。
# scripts/check_dependencies.py
import sys
from importlib.metadata import version
import psycopg
import pymysql
if __name__ == "__main__":
print("Python:", sys.version.split()[0])
print("psycopg:", version("psycopg"))
print("PyMySQL:", version("PyMySQL"))
print("Dependencies ready")
完成标志 控制台显示 Python 3.13、实际安装的一个或两个包的版本，以及 Dependencies ready。
如果结果不一致
模块列表仅影响当前项目。更新、删除均先显示变更预览，确认后才安装或应用。
位置：Settings → Python → Python 模块 → 高级项目配置 → 项目运行配置。将已验证的 main(ctx) 登记为事件入口。
完成标志 应用后，“选择脚本”应出现该入口；未出现时核对保存结果和 target。
事件每 60 秒触发一次，动作选择计算脚本。绑定完成前保持事件停用。
完成标志 记录显示事件执行成功；详情中的返回结果为 {scaled: 5.0}，输出包含 Scaled value: 5.0。main(ctx) 默认 raw=50，无需额外输入。
如果结果不一致
复制本地点位 TagRef，直接替换 tags.read(...) 中的 URI 并运行。Run Test 仅从读取调用的字面量授予范围，变量不适用。对照 Tag 测试核对值与质量。tags.read_many([...]) 每次最多 256 个不重复输入，须逐项检查 ok。
# scripts/read_value.py
from hqcontrol import tags
def main(ctx):
response = tags.read("hq://io/<io-domain-id>/<device-uid>/<tag-uid>")
if not response or response.get("ok") is not True:
raise RuntimeError("Tag read failed")
snapshot = response["value"]
if not tags.is_good_quality(snapshot):
raise RuntimeError("Tag quality is not good")
print("Value:", snapshot.get("value"), "Quality:", snapshot.get("quality"))
return {"value": snapshot.get("value")}
if __name__ == "__main__":
main({})
完成标志 输出目标值和 good 质量；缺值或质量异常时保留错误状态。
工作台也提供无需导入的 ReadTagBoolean、ReadTagInteger、ReadTagDouble、ReadTagString、ReadTagJson、ReadTagDateTime、ReadTagQuality 和对应 WriteTag 方法。Run Test 中每次读取的首个参数都应直接填写本地点位名称字面量；变量形式不授予读取范围。ReadTagQuality 将状态归为 good/bad；需要详细质量和时间戳时使用 tags.read。
if ReadTagQuality("<device-code>.<tag-code>") != "good":
raise RuntimeError("Tag quality is not good")
print(ReadTagDouble("<device-code>.<tag-code>", 0.0))
calculated = ReadCalculatedTag("<calculated-tag-code>", None)
if calculated is None:
raise RuntimeError("Calculated value is unavailable")
print(calculated)保存为 common/tag_control.py。函数从完整读取响应取得 TagRef 和 expected 快照，写入一次并核对状态。0–100 须改为设备允许范围。Run Test 不授予写权限，仅由具备目标读写范围的正式动作调用。
# common/tag_control.py
from hqcontrol import tags
def write_setpoint(read_response, value):
if isinstance(value, bool) or not isinstance(value, (int, float)) or not 0 <= value <= 100:
raise ValueError("Setpoint must be a number between 0 and 100")
if not read_response or read_response.get("ok") is not True:
raise RuntimeError("Cannot read the target Tag")
tag_ref = read_response.get("tagRef")
if not isinstance(tag_ref, str) or not tag_ref.startswith("hq://io/"):
raise RuntimeError("Read response has no physical TagRef")
snapshot = read_response["value"]
if not tags.is_good_quality(snapshot):
raise RuntimeError("Target quality is not good")
result = tags.write(tag_ref, float(value), value_type="number",
reason="Approved setpoint update", expected=snapshot)
if (result.get("accepted") is not True or result.get("status") != "done"
or result.get("outcomeUncertain") is True
or result.get("operatorVerificationRequired") is True
or result.get("transportOnly") is True):
raise RuntimeError("Verify command " + str(result.get("commandId")) +
"; status=" + str(result.get("status")) +
"; accepted=" + str(result.get("accepted")))
return result
完成标志 保存完成；调用 write_setpoint 时才写入。
此入口仅供正式动作使用，Run Test 不授予写入范围。触发上下文须含目标 TagRef，并满足权限、设备和运行条件。
# scripts/write_setpoint.py
from hqcontrol import tags
from ..common.tag_control import write_setpoint
def main(ctx):
response = tags.read("hq://io/<io-domain-id>/<device-uid>/<tag-uid>")
return write_setpoint(response, 12.5)
完成标志 函数仅在 accepted=true、status=done 且无不确定或人工核查标识时返回，仍须核对后续正常采集值。proxied 等其他状态保留 commandId 核查，不重复写入。
位置：配置中心 → script → 状态。概览与工作进程用于查看服务和执行资源；单次执行详情仍在“记录”中查看。
完成示例后，控制台应输出 5.0，依赖版本与安装清单一致，读取质量为 good。写入结果需结合命令状态和后续采集值确认。
common/ 中的函数由 scripts/ 相对导入，无需作为第三方模块安装；跨项目共享再构建 Wheel。
选择项目后先核对运行环境；添加内置模块或上传 Wheel 时，都在当前项目中检查并安装。
网页导入是常用入口；服务器离线目录位于高级配置，检查目录后仍须确认安装。