labview-vi-props-skill

name	labview-vi-props-skill
description	通过与目标 LabVIEW 安装位数一致的 cscript/VBScript COM 宿主， 稳定读取和写入 LabVIEW VI 文件的标题 (Title) 与描述 (Description) 属性。
keywords	["LabVIEW","VI Server","ActiveX","cscript","VBScript","32-bit","64-bit","读取 VI 标题","修改 VI 标题","读取 VI 描述","修改 VI 描述","LabVIEW 属性","VI.FP.Title","VI.Description"]
triggers	["读取 VI 标题","修改 VI 标题","读取 VI 描述","修改 VI 描述","LabVIEW VI 属性读写","批量修改 VI 文档"]
runtime	{"language":"python","python":">=3.7"}
platform	windows
dependencies	[]
requirements	["LabVIEW (Windows) 已安装","LabVIEW 已启用 VI Server (ActiveX) 服务器"]
entrypoint	scripts/vi_props.py

labview-vi-props-skill

这个 Skill 的稳定路径已经从“当前 Python 进程直接创建 COM”重构为“Python 入口 做调度，真正的 COM 连接由目标位数对应的 cscript.exe + VBScript worker 执行”。

当前实现的设计目标是：

1. 先识别要命中的 LabVIEW 版本。
2. 再识别对应安装的位数。
3. 用相同位数的脚本宿主启动目标 LabVIEW.exe /Automation。
4. 连接后校验实际命中的 ApplicationDirectory 与 Version。
5. 不再回退到无关的活动 / 默认 LabVIEW.Application。

支持的版本格式包括 2017、17.0、2025.3。

支持的属性

名称	LabVIEW 属性	读	写	说明
Title	VI.FP.Title	✅	✅	前面板窗口标题
Description	VI.Description	✅	✅	VI 属性对话框中的描述

⚠️ VI.Name 是只读的文件名，不在本 Skill 的写入范围内。

工作方式

1. 目标版本识别

• 如果调用方显式给出 labview_version 或 --labview-version，就以该版本为准。
• 否则从目标 VI 文件头读取保存版本。
• 当前通过扫描文件头前 512 字节中的 00 00 00 A0 标记，并解析后续 BCD 版本字节 来识别主次版本。

2. 目标安装定位

• 同时读取 32 位和 64 位注册表视图中的 HKLM\SOFTWARE\National Instruments\LabVIEW\<major.minor>。
• 从每个版本项的 Path 找到对应的 LabVIEW.exe。
• 进一步读取 LabVIEW.exe 的 PE 头，判断安装是 x86 还是 x64。

3. 位数选择规则

• 如果调用方显式给出 labview_bitness 或 --labview-bitness，只在该位数安装里选。
• 如果同一版本同时存在 x86 和 x64，但未显式指定位数，则默认优先当前运行环境架构。
• 在本仓库当前验证环境里，入口 Python 为 64 位，因此 2025 默认会优先命中 x64。
• 如果目标安装是 x86，调度 C:\Windows\SysWOW64\cscript.exe。
• 如果目标安装是 x64，调度 C:\Windows\System32\cscript.exe。

4. COM worker 行为

scripts/vi_props_worker.vbs 会执行以下动作：

1. 只清理“目标 LabVIEW.exe 对应”的残留 /Automation 进程。
2. 启动目标 LabVIEW.exe /Automation。
3. 通过 CreateObject("LabVIEW.Application") 建立 COM 连接。
4. 校验 ApplicationDirectory 与 Version 是否匹配请求目标。
5. 用 GetVIReference 打开目标 VI，执行属性读写。
6. 保存时优先尝试 SaveInstrument，失败后回退到 Save。
7. 通过响应文件把执行结果回传给 Python 调度器。

当前接口

顶层函数

read_title(vi_path, labview_version=None, labview_bitness=None) -> str
read_description(vi_path, labview_version=None, labview_bitness=None) -> str
write_title(vi_path, title, labview_version=None, labview_bitness=None) -> bool
write_description(vi_path, description, labview_version=None, labview_bitness=None) -> bool

• labview_version 可传 2017、17.0、2025.3。
• labview_bitness 可传 x86、x64、32、64。

Handler 语义

LabVIEWVIHandler 仍然保留原有调用形状，但语义已经变化：

• open_vi() 返回的是轻量句柄，不是长期持有的 COM VI 引用。
• 每次 read_* / write_* 调用都会单独启动一次外部 worker。
• 复用 LabVIEWVIHandler 的主要价值是复用目标版本 / 位数配置，以及统一拿到最近一次 连接诊断报告，而不是在当前进程里长期复用 COM Application。

示例：

from scripts.vi_props import LabVIEWVIHandler

with LabVIEWVIHandler(preferred_version="2025", preferred_bitness="x64") as h:
    vi = h.open_vi(r"C:\path\to\test.vi")
    print(h.read_description(vi))
    h.write_description(vi, "Updated by skill")

命令行使用

# 自动按 VI 保存版本命中目标安装
python scripts/vi_props.py read_description "C:\path\to\test.vi"

# 指定版本
python scripts/vi_props.py read_description --labview-version 2017 "C:\path\to\test.vi"

# 指定版本 + 位数
python scripts/vi_props.py read_description --labview-version 2025 --labview-bitness x64 "C:\path\to\test.vi"
python scripts/vi_props.py read_description --labview-version 2025 --labview-bitness x86 "C:\path\to\test.vi"

# 写入属性
python scripts/vi_props.py write_title "C:\path\to\test.vi" --title "新标题"
python scripts/vi_props.py write_description "C:\path\to\test.vi" --description "新描述"

# 输出诊断信息
python scripts/vi_props.py read_description --verbose "C:\path\to\test.vi"

--verbose 会输出：

• 目标 VI 路径
• 请求版本来源（用户指定版本或 VI 保存版本）
• 请求位数（如果有）
• 命中的目标安装
• 实际选择的宿主位数和 cscript.exe
• worker 的连接策略、说明、实际连接版本和目录、尝试次数、保存方法

已验证结果

以下结果来自这台多版本 LabVIEW Windows 机器上的实机验证：

• 仓库中的示例 VI 保存版本为 17.0。
• 不带 --labview-version 时，已自动命中 LabVIEW 2017 x86。
• --labview-version 2017，已命中 LabVIEW 2017 x86。
• --labview-version 2020，已命中 LabVIEW 2020 x64。
• --labview-version 2025 --labview-bitness x64，已命中 LabVIEW 2025 x64。
• --labview-version 2025 --labview-bitness x86，已命中 LabVIEW 2025 x86。
• --labview-version 2025 且不带 --labview-bitness，在当前 64 位 Python 环境下默认命中 x64。

适用边界

• 这个 Skill 只处理 VI Server/ActiveX 可以访问的属性，不处理需要 UI 交互的编辑流程。
• VI 文件头可以提供保存版本，但不能提供 x86/x64 信息；同版本双位数并存时，若调用方有 明确意图，应该显式传 labview_bitness。
• 当前实现强调“精确命中目标安装”，因此遇到目标未安装、位数不匹配或 worker 校验失败时， 会直接报错，而不是悄悄连到别的 LabVIEW 实例。

退出码：

码	含义
0	成功
1	写入失败或 worker 保存失败
2	文件不存在
3	连接 LabVIEW 失败或读取属性失败
4	参数错误或其他未预期错误