命令名和包名均为 opentest-cli,技能调用为 $opentest。通过 npm(Node.js 包管理器)注册本地链接后,可在任意工作目录运行 opentest-cli。此操作只注册本机入口,不发布到包仓库。
命令行接口(CLI)提供界面联动与独立调用两条路径。界面联动通过桌面进程内通信,调用当前前端的 TypeScript 动作。页面再使用共用的客户端工具包(SDK)访问服务。界面沿用原有状态、校验和运行流程。
CLI 不新增常驻服务。独立模式直接调用 SDK。插件继续在 OpenTest 中加载,CLI 按当前登记的能力选择操作。
需要 Node.js 22.14 或更高版本。开发构建使用仓库已有的 SDK 和构建依赖,不修改根工作区配置。
# 在当前 OpenTest 仓库根目录执行。
cd cli
node tools/build.mjs
npm install --global --offline --ignore-scripts --no-audit --no-fund .
opentest-cli --help
opentest-cli schema --command "provider describe"切换仓库副本或移动目录后,全局入口仍可能指向原目录。请在新的 cli/ 目录重新执行上述安装命令。可用 npm prefix --global 查询安装位置;仅核对版本号不能确认入口来自哪个仓库。未配置本地链接时,可从仓库根目录执行 node cli/bin/opentest-cli.mjs,或使用 Windows 启动脚本 cli/opentest-cli.cmd。二者调用同一入口,构建产物为 cli/dist/opentest-cli.cjs。请单独构建 CLI。根目录构建及桌面安装不会自动注册此命令。
| 参数 | 行为 |
|---|---|
--ui auto |
默认值。发现桌面实例时使用界面联动;没有发现文件时才允许独立路径 |
--ui required |
必须连接桌面。要求界面同步的任务使用此值 |
--ui off |
显式使用独立路径,不保证页面同步 |
--desktop-instance |
多实例时指定实际实例身份,不能与 --ui off 组合 |
桌面已被选中后,通信失败、协议不匹配或页面动作缺失都会返回错误,不转为后台写入。多个实例无法消除歧义时拒绝执行。页面未注册动作、尚未就绪或存在配置冲突时,也不能开始操作。
CLI 已注册界面命令与执行适配。使用前核对当前帮助与页面返回的能力。源代码存在、插件启用和当前页面可操作是三个不同条件。当前安装包未必包含工作区的新通信代码。
SDK 查询默认连接 http://127.0.0.1:5001,独立执行默认使用 127.0.0.1:9090。可通过 --url、--grpc-url 或 OPENTEST_URL、OPENTEST_GRPC_URL 设置地址。需要认证的 SDK 调用显式使用 OPENTEST_SESSION_ID。界面动作使用页面已有权限,不向 CLI 导出桌面会话。选择桌面不会让 SDK 查询自动获得页面身份。
CLI 不读取登录文件,不自动登录或切换账号。知识查询无需连接桌面或服务。
opentest-cli --ui required ui status
opentest-cli --ui required ui project --project "1001"
opentest-cli --ui required ui open --project "1001" --kind measure --dashboard "2001" --provider "<实际 providerId>"
opentest-cli --ui required ui open --project "1001" --kind sequence
opentest-cli --ui required ui open --project "1001" --kind monitor
opentest-cli --ui required ui refresh --scope results --project "1001" --dashboard "2001"
opentest-cli --ui required ui pluginui open 打开指定业务页面。sequence(序列)和 monitor(实时监视)可省略 --dashboard,由页面完成首次创建并返回真实仪表盘编号;显式传入编号时仍须严格匹配。measure(测量)必须指定 --dashboard,不能只凭 --provider 导航。
ui plugin 只打开插件管理窗口,不自动选中、安装或启用插件。ui refresh 接受配置 configuration、结果 results、设备 devices、插件 plugins、工程 project 五类参数;当前五类调用均明确返回不支持。接受参数不表示刷新能力可用。
已有业务命令覆盖以下范围。每项动作能否在界面联动模式下使用,仍须查询当前能力:
- 工程查询、创建、激活、导入和导出。
- 设备、通道、插件状态和活动提供者查询。
- 已安装插件的启用、停用、卸载及待变更撤销。
- 仪表盘首次创建、测量配置计划与提交。
- 序列读取与导出、执行与标准输入控制。
- 结果查询与结构化导出、历史回放及本地知识查询。
opentest-cli doctor
opentest-cli plugin list
opentest-cli provider list
opentest-cli provider describe --provider com.opentest.fft-tools:fft-measure
opentest-cli project list
opentest-cli dashboard get --project "1001" --provider com.opentest.fft-tools:fft-measure参数中的工程与仪表盘编号必须换成实际查询结果。所有业务编号使用字符串。插件查询区分当前生效与等待重启;业务命令不会自动安装插件或重启程序。界面联动中的工程切换由页面完成一次,CLI 不重复调用后台切换接口。
配置流程针对已存在的测量仪表盘。先生成草稿,修改其中的配置字段,再生成并检查计划:
opentest-cli design init --project "1001" --dashboard "2001" --out design.json
# 编辑 design.json 中的 configuration,保留真实身份与版本。
opentest-cli design validate --file design.json
opentest-cli design plan --file design.json --out plan.json
opentest-cli --ui off design apply --plan plan.json当前 design apply 只支持独立 SDK 模式,须显式使用 --ui off。选定桌面后执行该命令会返回不支持,不自动切换路径。提交会重新检查配置摘要、插件快照和配置版本,再保存并读回。
页面当前没有配置写入协议,也没有可用的安全刷新入口。独立保存后只能确认后台读回结果,不能声称页面已同步。未来页面登记安全刷新后,才能显式请求并核对表单。未保存编辑或刷新能力缺失时,应报告限制。
部分成功会保留已完成项。服务没有整体事务或条件写入接口,本地检查不能排除其他客户端同时写入。此版本不编辑序列节点或槽位,也不自动删除配置。
界面联动由当前页面持有运行连接和数据读取器。CLI 负责请求、观察、控制消息与报告,不建立第二条执行连接,也不需要为自身加载测量用本机扩展。
run start 默认在前台等待,不自动导航。先用 ui open 打开目标页面。页面模式不支持启动参数 --file、--box,会在启动前拒绝。序列控制只支持暂停和继续,不支持 reply。
| 页面业务 | 本轮运行范围 |
|---|---|
| FFT、倍频程、声级计、声品质、振动 | 通过测量主页面开始和停止 |
| 序列 | 开始、停止、已有暂停与继续 |
| 实时监视 | 显式开始和停止,不含录制;导航不自动启动 |
| 扫频、声功率 | 可导航,运行返回不支持 |
已在本机安装版完成实时监视、序列和 FFT 的界面联动验证,采集输入来自本机虚拟 ADPro。其他页面的能力不能由这些结果推定。页面自然结束时,业务结论、保存与判定仍为未知,命令返回退出码 7,不能报告测量合格。
页面执行仅依据当前运行的真实 workflowEnd(序列结束事件),或与当前请求匹配的 TOTAL_TASK_STOP(任务停止通知),确认资源释放。仅断流或超时不能确认释放,资源状态保持未知。显式停止并确认释放后,才报告正常停止。
独立执行需要匹配 Node.js 的本机共享数据读取扩展。使用 --native-modules 指定模块目录,或用 --addon 指定扩展文件。独立模式下,CLI 保持执行进程存活并持续读取共享数据,默认不输出曲线。
独立序列执行必须显式指定 --box,使用序列查询返回的箱体或线程编号。编号可能是字符串 "0",不能当作缺失值。batchId 是本次执行的批次编号,由 CLI 每次生成。界面模式仍拒绝启动参数 --box。
opentest-cli --ui required run start --kind measure --dashboard "2001" --duration 6s --run-timeout 2m --stop-timeout 30s --control-stdin --events-file run.ndjson标准输入每行接收一个 JSON 对象,例如 {"commandId":"stop-1","action":"stop"}。使用 --control-stdin 时,输入结束请求正常停止。CLI 异常退出与正常停止不同。界面模式下,页面依既定策略继续或停止;不能据此承诺后端必然独立运行。
桌面通信管道与独立执行进程的控制管道是不同能力。后者的 --control-pipe 和 run events 仍未开放。界面模式支持以下短命令。窗口重载、运行身份变化或失联后,先核对状态;不重复启动,也不接管用户手动运行。
opentest-cli --ui required run status --run "<实际 runId>"
opentest-cli --ui required run stop --run "<实际 runId>"
opentest-cli --ui required run control --run "<实际 runId>" --action pause
opentest-cli --ui required run control --run "<实际 runId>" --action resume暂停和继续可用 --box 指定实际序列箱体。控制回执不证明页面状态已经改变。Ctrl+C 请求一次正常停止。运行等待默认 10 分钟,停止等待默认 30 秒。--duration 从页面报告 running 后开始计时。
执行报告分别给出业务结果、保存状态、资源状态与判定;缺乏依据时保留未知。--require-pass 在未判定或未知时返回 7,在明确不合格时返回 10。运行超时即使完成正常停止,也返回 7。
普通命令默认输出 JSON,执行命令输出逐行 JSON。错误包含稳定的 error.code 和非零退出码。新输出文件拒绝覆盖。result export 导出记录 JSON,不下载波形二进制数据。工程导入、导出请求中的路径由服务端解释。
技能(Skill)指导智能体选择同一套命令,通过 $opentest 调用。源码位于 cli/skills/opentest/SKILL.md,薄启动器为 cli/skills/opentest/scripts/opentest-cli.mjs。已安装技能通过其目录内的 cli-location.json 定位 CLI。切换仓库副本后,请同步更新该文件的 entry,填入新仓库中 cli/bin/opentest-cli.mjs 的绝对路径。
安装器将知识复制到新技能目录,并记录此 CLI 的准确位置。目标目录最后一级必须为 opentest。以下示例在 cli/ 目录中执行:
node tools/install-skill.mjs --destination "D:\agent-skills\opentest"安装器拒绝覆盖已有技能,已安装到本机目录时不重复执行。薄启动器 scripts/opentest-cli.mjs 只定位并调用统一入口。本技能使用已注册的 CLI 动作。要求操作可见窗口控件时,按对应窗口技能执行。
node tools/typecheck.mjs
node tools/test.mjs自动测试使用模拟业务响应、本机临时 HTTP 服务和真实 SDK 工作线程。当前结果以运行上述命令为准。以下为此前安装版的验收记录,新克隆环境仍须安装和验证。当时 49 项命令中,47 项真实调用成功;ui refresh 明确不支持,replay stop 尚未完成真实验证。该次验收使用本机安装版、真实服务与虚拟 ADPro 输入,覆盖以下范围:
| 范围 | 实测结果 |
|---|---|
| 业务命令 | 工程、插件、设计配置、导入导出、执行记录及知识命令已实际执行 |
| 独立序列 | 暂停、继续、自然完成和定时停止通过;连接关闭已确认,保存与资源状态仍为未知 |
| 界面运行 | 实时监视定时停止、序列暂停/查询/继续/停止、FFT 主动停止均通过,并确认资源释放 |
| 自然结束 | 序列结束后确认资源释放;页面业务判定仍未知,退出码为 7 |
| FFT 采集 | 自然采集完成,记录时长约 10.407 秒;已保存的 WAV 波形文件为 1 通道、48 kHz、10.0 秒,主频为 1000 Hz;记录 JSON 导出与服务读回一致 |
| 连续运行 | 最终安装包连续两轮 FFT 主动停止均正常结束、确认资源释放、退出码为 0;顶层及嵌套记录列表均只包含本轮执行记录 |
| 安装与图表 | 本机安装文件 1025 项核对一致,图表实际显示约 1000 Hz 输入;生产构建采用本地未签名包,自动更新关闭 |
五类 ui refresh 均明确不支持。replay stop 尚未完成真实验证:当前 4 输入记录为 LEGACY(常规存储模式),回放直接返回完成,没有活动回放任务的代次编号。WAV 文件存在不表示记录采用 WAV_ONLY(只保存原始波形、查看结果时重算的存储模式)。当前阈值要求业务输入通道数大于 30,不能通过 FFT 执行参数直接切换。