脚本类型与使用边界

页面脚本：跟着某一页画面运行

页面脚本来自 HQ VISU Designer 导出的画面包，运行在浏览器当前页面里。它适合页面初始化、当前页变量整理、模板值读取、对象颜色/显隐/文本变化和页面内交互。页面脚本不应该承担服务器定时任务，也不要直接连接数据库。

三类脚本不要混用

页面脚本处理当前画面展示和交互，页面全局脚本处理同一画面包内的公共函数，系统脚本处理服务器侧集成。判断脚本放在哪里时，先看它需要访问的对象：需要 DOM、组件或当前页面变量时放在画面包；需要访问数据库、HTTP、MQTT、定时任务或服务器侧文件时放在 Integration Script。

• 页面脚本运行在浏览器中，适合改文字、颜色、显隐、模板值和当前页变量。
• 页面全局脚本仍然在浏览器中，适合同一画面包多页面复用。
• Integration Script 运行在服务器本机 Python 环境，适合跨系统集成和后台任务。
• 浏览器脚本不应直接连接数据库；系统脚本不应修改浏览器 DOM。
• 写值应走 HQControl 提供的标准方法，保留权限、审计和质量边界。

运行上下文 ctx 能提供什么

Integration Script 执行时会带运行上下文 ctx。定时任务、HTTP 入站、MQTT 入站和 IO 变化触发会把触发来源、入站载荷、触发时间或关联点位放入上下文。脚本应先读取上下文，再决定是否读 Tag、写 Tag 或调用外部系统。

• 定时任务关注触发时间、任务编码和运行窗口。
• HTTP 入站关注请求载荷、调用来源和认证结果。
• MQTT 入站关注 topic、载荷内容和连接状态。
• IO 变化触发关注触发点名、当前值、质量和去抖边界。
• 上下文字段应按触发器类型处理，不要假设所有触发器都有同一组字段。

本地包目录组织方式

项目专用公共代码建议放在脚本工作目录下的 libs、packages 或 site-packages 子目录。这样脚本迁移时只需要带走脚本文件、元数据文件、触发器文件和工作目录下的公共代码。不要把项目公共代码散放到系统 Python 目录，也不要在每次脚本运行时动态安装依赖。

• 小型公共函数可以放在 libs/project_common.py。
• 多个脚本共享的包可以放在 packages/<package-name>/。
• 第三方离线包解压后可放在受控的本地包目录。
• 工作目录变化后，进入 Integration Script 页面确认环境信息和执行记录。
• 迁移项目时，把工作目录和脚本配置一起纳入备份清单。

script-workdir/
  libs/
    project_common.py
  packages/
    field_adapter/
      __init__.py
  site-packages/
    vendor_package/

Python 包安装、更新和降级

集成脚本用的是服务器本机的 Python。要装额外的包时，先在 Integration Script 的“环境信息”里看到脚本实际用的那个 Python 路径，再用那个 Python 执行 pip；装完或改完版本后，重启一次 Integration Script 服务再用。现场不能联网时，优先用安装包内置的离线包，或把包放进脚本工作目录的本地包目录。

• 安装包：用那个 Python 执行 python -m pip install 包名。
• 更新到最新：python -m pip install --upgrade 包名。
• 降级或指定版本：python -m pip install 包名==版本号。
• 一定用“环境信息”里显示的那个 Python，不要随意找一个 python 装，否则脚本里 import 不到。
• 装完或改完版本后，重启 Integration Script 服务再运行脚本。

# 先在“环境信息”看到脚本实际用的 Python 路径，再对它执行：
C:\Python311\python.exe -m pip install requests
C:\Python311\python.exe -m pip install --upgrade requests
C:\Python311\python.exe -m pip install requests==2.31.0

# Linux 同理
/usr/bin/python3 -m pip install --upgrade requests

脚本工作目录如何识别本地包

运行时会自动把脚本缓存目录、脚本工作目录，以及工作目录下的 libs、packages、site-packages 加入 PYTHONPATH。推荐把项目专用公共代码放在这些目录里，由脚本配置页的“工作目录”统一指向。不要在生产脚本中动态安装依赖，也不要直接改数据库、缓存或驱动层绕过 HQControl。