OpenTest

English | 简体中文

OpenTest 是由 Electron 桌面、Vue 前端、Java 后端及独立安装的测量插件组成的 Windows 应用。宿主提供工程、设备连接、采集、图表、存储和插件管理；业务插件提供测量与分析流程。

本文面向 Windows x64 干净环境，从全新 clone 开始，完成一次本机 WASAPI 麦克风的真实 FFT 测量，并保存、重开结果。步骤以随本文交付的代码为准，宿主和插件应使用匹配的版本；其他开发者本机未提交的改动不会随 clone 获取。

1. 克隆前准备

先取得以下材料。源码仓库不包含账号凭据或用户业务权益证书。

条件	需要取得或检查的内容
Windows x64 与 PowerShell	使用可写的本机开发目录；安装 C++ 构建工具需要管理员权限。
Git	先安装 Git，用 `git --version` 确认可用。
仓库与网络权限	使用版本匹配的 OpenTest 和 OpenTest-Plugins 仓库；还需要访问 npm、GitHub、Node/Electron 下载源及宿主使用的 Maven 仓库。
工作区及 FFT 授权	在线使用需要 Casdoor 应用配置、真实账号、业务授权服务配置及所需 FFT 权益；也可使用允许该测量的有效本机或 USB 离线授权。
真实音频输入	Windows 能识别的内置或 USB 麦克风；在系统隐私设置中允许桌面应用访问麦克风，确认输入电平会随说话变化。

基础开发工具由开发者自行安装，版本与配置要求见第 3 节。仓库提供环境检查和本地 Java 制品准备，原生材料直接随源码管理；详见开发环境与依赖准备。

2. 克隆 OpenTest

将 URL 占位符替换为宿主仓库地址，选择一个新的克隆目录。以下示例使用 D:\WorkSpace\opentest。

$hostDirectory = 'D:\WorkSpace\opentest'
$hostRepository = 'REPLACE_WITH_HOST_REPOSITORY_URL'
New-Item -ItemType Directory -Force -Path (Split-Path -Parent $hostDirectory) | Out-Null
Set-Location (Split-Path -Parent $hostDirectory)
git clone $hostRepository $hostDirectory
Set-Location $hostDirectory

如果团队指定了分支或标签，切换到对应版本。任何命令失败都应先解决，再继续下一步。宿主环境准备、构建和启动命令均在本仓库根目录执行。

OpenTest-Plugins 是独立的插件开发仓库，第 6 步会介绍。宿主环境准备只需本仓库；后续运行 FFT 时需要兼容的 .otplugin 安装包。

3. 准备开发环境、原生库与项目依赖

开发者自行安装工具

仓库不下载或安装基础工具，不修改 PATH、JAVA_HOME、用户包管理器配置或缓存位置。请按下表自行准备，并在新开的普通 PowerShell 中确认工具可用：

工具	要求与配置
Node.js	>=22.14.0，加入 PATH。
pnpm	稳定版 >=10.6.5 且 <11，加入 PATH；安装方式由开发者选择。`packageManager` 保留 10.6.5 作为工具固定版本。
JDK	完整 JDK 21，设置 JAVA_HOME；需要 java 和 javac。
Maven	3.9.x，设置 MAVEN_HOME（兼容 M2_HOME）或加入 PATH。
Python	编译原生模块时需要 Python 3.11 或更新版本，可设置 PYTHON 或 npm_config_python 为解释器完整路径；不纳入 `pnpm deps:check` 校验。
Visual Studio C++ Build Tools	Visual Studio 2022 或 2026 的 C++ x64/x86 编译工具及 Windows SDK 10.0.26100，通过官方安装器安装。
Git	加入 PATH，并能访问所需的 GitHub 仓库。

先执行以下只读检查；Node 尚未安装时需先自行安装，无法运行基于 Node 的检查脚本：

node --version
pnpm deps:check

检查汇总工具缺失或版本不匹配，不自动修复。仅开发前端时可使用 pnpm deps:check --node-only 检查 Node、pnpm 和 Git。

安装项目依赖与原生材料目录

在宿主根目录执行 pnpm install --frozen-lockfile。它安装锁定的 JavaScript 依赖；现有 onlyBuiltDependencies 允许 Electron、esbuild、protobufjs 执行必要的依赖构建脚本。Electron 运行包和 node-gyp 编译头文件仍属于项目依赖。

原生 C++ 源码与后端运行材料分别存放。运行库及配套的 Windows 默认许可证直接纳入 Git，无需解压或恢复命令：

目录	用途
`apps/native`	原生 C++ 源码和构建工程，与部署使用的后端运行材料分别维护
`apps/backend/crydaq-server/src/main/resources/native/<platform>`	后端运行库、辅助文件及 `native-libs-load-order.txt`
`apps/backend/crydaq-server/src/main/resources/native/<platform>/prd`	对应平台的正式覆盖材料，在暂存目录应用，不改写基础库
`apps/desktop/packages/native-modules/vendor/algorithm-bridge`	桌面算法 DLL，构建时复制至原生模块产物

<platform> 为 windows-amd64、linux-amd64 或 macos-arm64。源码启动按运行平台与架构选择；WSL 配置为启动 Windows Java 时选择 windows-amd64。OPENTEST_NATIVE_MATERIALS_ROOT 指向包含 native/<platform> 的 resources 根目录，正式覆盖材料位于所选平台内部的 prd。每套运行材料使用主清单 native-libs-load-order.txt 及其引用文件。Windows 安装、升级和签名固定选择 windows-amd64，安装后仍将所选运行材料直接放在 resources/backend/native。

Windows 必须提供配套的 native/windows-amd64/License.dat；正式环境还要求 native/windows-amd64/prd/License.dat 及同目录配套的 cry_analyst.dll。两份默认许可证随 Git 跟踪，并与配套运行库一起交付。Linux、macOS 允许没有许可证，若提供则必须是非空普通文件。正式环境必须具备所选平台的配套覆盖材料，不回退到测试材料或其他平台。用户业务权益证书与日志单独管理。首次检出不再需要 Git LFS 或 ZIP。

普通宿主和插件开发者使用预编译核心运行材料与公共 SDK，不需要访问 OpenTest-NativeDriver。Windows 打包独立使用现有 Windows 运行材料与桌面 vendor DLL，不依赖 POSIX 材料。公开 Node addon 仍通过 node-gyp 编译。

Mac/Linux 配套的新算法 SDK 与运行材料尚待提供，这两个平台暂不纳入验收。消费端脚本要求预编译 JNI、Host、算法桥、单位换算库和依赖库；打包检查当前 com.opentest.core.jni 命名空间及 prepareManagedRuntime 标记。材料缺失或过时会报告具体文件，不会回退到私有源码编译。这些检查不代表 POSIX 已可用。

准备命令	实际范围
`pnpm deps:check`	只读检查开发工具及版本
`pnpm install --frozen-lockfile`	安装锁定的 JavaScript 项目依赖
`pnpm prepare:backend-deps`	在 `apps/backend` 执行 `mvn clean install -DskipTests`，构建全部后端模块，编译测试但跳过执行

旧 deps 安装、离线、恢复、校验、工具下载入口以及 prepare:backend-native 已移除。原有工具目录和缓存保留在本机，不自动发现或激活。曾执行旧 env.ps1 时请打开新终端。npm/pnpm 遵循开发者缓存和镜像配置；Maven 遵循 settings/default（通常为 %USERPROFILE%/.m2/repository），旧缓存不自动迁移或删除。

需要编译并安装后端制品到 Maven 本地仓库时，在宿主根目录执行 pnpm prepare:backend-deps，等价于进入 apps/backend 执行 mvn clean install -DskipTests。先停止源码后端，避免同时改写 target。命令直接使用终端配置的 JDK/Maven、Maven settings 和本地仓库，不筛选模块，保留测试编译但跳过测试执行，不读取相邻插件仓库，也不再支持 --plugins-dir。deps:*、build/dev 不隐式调用此命令。需要完整测试验证时，在 apps/backend 直接执行 mvn clean install。

安装包使用的完整 Java 运行时随普通 Git 保存在 vendor/java/windows-x64，独立于开发用 JAVA_HOME，默认打包不依赖 .runtime/release/java 或其他电脑上的文件。版本与更新要求见 Java 材料说明。

依赖工具链的回归检查入口为 pnpm test:dependencies。源码启动从根目录 runtime.env 读取授权环境和服务地址；打包从 packaging.config.json 中选定的模式读取对应设置。

以下路径均相对于 opentest/，本机配置目录已被 Git 忽略。所有占位符都必须替换为当前环境实际签发的值。

New-Item -ItemType Directory -Force -Path .local, apps/desktop/.runtime, apps/backend/.runtime | Out-Null
Copy-Item -LiteralPath apps/desktop/local-settings.example.json -Destination apps/desktop/.runtime/local-settings.json
Copy-Item -LiteralPath runtime.env.example -Destination runtime.env
notepad .\runtime.env

复制 runtime.env.example 为根目录 runtime.env。示例默认选择 production，使用正式授权服务 https://update.opentest.com；源码启动从该文件读取 OPENTEST_LICENSE_ENVIRONMENT 和 OPENTEST_LICENSE_URL。packaging.config.json 中各打包模式默认使用同一服务地址。

保存为 UTF-8，确保文件名为 runtime.env，而非 runtime.env.txt。源码启动的授权环境和服务地址以此文件为准。修改后重启开发服务和桌面。

云账号与业务授权服务

如果使用已获准的离线授权，跳过本小节，按后面的离线替代路径操作。

在线使用需要同时配置桌面公开参数与 Java 认证参数。向身份服务管理员取得匹配的 Casdoor 应用、客户端及已登记回调。克隆本仓库不会启动登录服务或业务授权服务。

编辑 apps/desktop/.runtime/local-settings.json，使用以下结构。图谱使用 vendor/crychart/ 固定制品，无需配置图表运行许可证。

{
  "auth": {
    "serverUrl": "https://identity.example.com",
    "clientId": "REPLACE_WITH_CLIENT_ID",
    "application": "REPLACE_WITH_APPLICATION",
    "organization": "REPLACE_WITH_ORGANIZATION",
    "redirectUrl": "http://127.0.0.1:15021/login/oauth2/code/casdoor",
    "signupUrl": "",
    "forgetPasswordUrl": ""
  },
  "updates": {
    "enabled": false,
    "apiUrl": "",
    "productId": "opentest-framework"
  }
}

创建 UTF-8 文件 apps/backend/.runtime/application-local.properties：

spring.security.oauth2.client.registration.casdoor.client-id=REPLACE_WITH_CLIENT_ID
spring.security.oauth2.client.registration.casdoor.client-secret=REPLACE_WITH_CLIENT_SECRET
spring.security.oauth2.client.registration.casdoor.redirect-uri=http://127.0.0.1:15021/login/oauth2/code/casdoor
spring.security.oauth2.client.provider.casdoor.authorization-uri=https://identity.example.com/login/oauth/authorize
spring.security.oauth2.client.provider.casdoor.token-uri=https://identity.example.com/api/login/oauth/access_token
spring.security.oauth2.client.provider.casdoor.user-info-uri=https://identity.example.com/api/get-account
spring.security.oauth2.client.provider.casdoor.jwk-set-uri=https://identity.example.com/.well-known/jwks

替换身份服务示例主机；源码授权环境和云服务基础地址填写在根目录 runtime.env，打包地址填写在 packaging.config.json 对应模式中。仅登录 Casdoor 不会自动取得 FFT 权益。后端默认的 unconfigured 客户端及回环地址占位值不能提供真实云认证与业务授权。

客户端 ID、已登记回调须与桌面一致；改变 BACKEND_PORT 时同时核对回调。客户端密钥只放后端本机文件或后端进程环境，不放前端 VITE_* 字段或桌面公开 JSON。Properties 值不加 dotenv 示例中的外层引号，反斜杠按 properties 格式需要转义。

只有业务授权服务要求客户端 JWT 认证时，才向后端 properties 文件补充管理员提供的配置：

# Only if required by the business license service:
cloud.client-jwt.enabled=true
cloud.client-jwt.private-key=REPLACE_WITH_SINGLE_LINE_BASE64_PKCS8_RSA_PRIVATE_KEY

该功能默认关闭；应使用服务端信任的材料，不能随意生成一个密钥代替。CASDOOR_SERVER_URL 只设置桌面公开地址，不会设置 Java 提供方 URL。显式进程变量 CASDOOR_CLIENT_ID / CASDOOR_CLIENT_SECRET 可以覆盖后端文件，配置不一致时应检查是否有旧环境变量。

离线授权替代路径

已获准离线使用时，取得包含所需 FFT 权益的本机绑定授权文件或支持的 USB 授权材料。在首次出现的授权弹窗中选择离线使用 / Offline Use，生成并复制机器码，交由授权管理员签发对应授权，再导入文件并等待成功。离线页面的加密狗认证 / Dongle Auth提供 USB 路径，按所获材料的配置说明操作。仅生成机器码不会授予权限。

用户菜单中的后续登录 / Login只打开云登录弹窗；如果未授权时关闭了首次弹窗，又需要进入离线路径，可重新启动应用，重新显示首次授权弹窗。

有效离线授权可以在未登录云账号时启用工作区和插件管理，但不会绕过 FFT 功能限制。Casdoor 配置是在线路径的要求，使用有效离线授权的工作区无需先完成云登录。

5. 构建并启动宿主

在已配置开发工具的宿主终端逐条执行，前一条成功后再运行后一条：

pnpm build
pnpm start

构建依次处理客户端 SDK、Java 后端、前端及桌面/本机模块；插件安装包单独构建和安装，此命令也不生成 Windows 安装器。宿主 Java 构建使用 -DskipTests，构建成功不代表 Java 测试通过。

等待启动页结束、后端就绪，完成云登录或已获准的离线授权流程。程序外壳可能在授权前已经显示，应继续确认工程和工作区操作可用；已登录账号仍可能缺少 FFT 权益。

以后使用 pnpm start 复用已有构建。正常关闭桌面，并等待它管理的 Java 进程和终端命令退出后，再启动下一实例。

独立开发 Java 后端时，在已激活的宿主终端执行：

pnpm dev:backend           # 执行 Maven clean package 后启动可执行 JAR

每次开发启动固定执行 Maven clean package -DskipTests，先清理旧构建产物，再完整构建可执行 JAR，避免删除或重命名源码后残留的旧类、资源被打入包中。启动器不再计算构建输入或 JAR 的哈希、不维护成功记录、不持有自定义构建锁。

pnpm dev 使用相同的后端构建命令。构建失败或取消时停止启动，启动器不会回退旧 JAR。重建前先停止旧源码后端，同一源码目录的构建应串行执行。原 start:backend 命令已删除；正常 pnpm start 仍使用严格的发行启动流程。

开发入口使用 java -jar 启动生成的 JAR，并显式启用可变已安装内容策略。插件仍只从活动安装目录加载。本机配置、端口检查、日志和退出清理沿用下方设置；等待就绪后使用，Ctrl+C 会停止本次后端。不要与其他入口共用端口。普通 Java 修改仍可能重建多个模块。

项目	根启动命令默认值
前端 / HTTP / gRPC 端口	`19010` / `15021` / `19021`
运行数据	`.runtime/app`（`OPENTEST_RUNTIME_DIR`）
工程与结果	`.runtime/app/projects`（`OPENTEST_PROJECTS_DIR`）
桌面用户配置	`.runtime/app/user-data`
后端控制台日志	`.runtime/app/logs/backend/backend-console.log`
后端服务日志	`.runtime/app/logs/service`

覆盖运行目录后，相关路径随之变化。保留用户配置和工程目录以保留会话与数据。安装版默认使用另一数据根 %LOCALAPPDATA%/OpenTest。

6. 取得并安装 FFT

OpenTest-Plugins 维护 FFT 插件实现、开发材料和构建工具。可用插件、支持的宿主版本及构建方法以该仓库的 README 为准。OpenTest 与插件通过公开 SDK 和 .otplugin 安装包配合。

首次测量可向插件维护者取得兼容的 FFT .otplugin，也可按下方独立开发流程自行构建。包名为 com.opentest.fft-tools-<version>.otplugin，版本以 plugin.json 和本次构建的包元数据为准。当前 FFT 清单声明的宿主范围为 >=2.5.0 <2.6.0；选择插件版本时，应将清单中的 openTestVersion 与宿主版本核对。

在桌面中操作：

悬停导航栏更多/设置图标，展开菜单后选择插件管理。
点击加载插件、选择文件，选择取得或自行构建的 FFT .otplugin。独立管理窗口跟随主窗口中英文及主题。
查看详情和校验结果，勾选信任本次插件包后点击加载插件。新安装默认勾选重启后启用；提交后仅登记待生效变更。
完整退出 OpenTest，等待后端停止，再在宿主终端执行 pnpm start，必要时恢复登录或授权。
打开或新建工程，进入测量 / Measure → FFT，确认参数及运行控件出现。仅显示待重启不代表插件已生效。

升级可直接加载同 ID 的更高版本，继承原启用状态，完整重启后替换；拒绝同版本替换及降级。启用、禁用、删除也在重启后生效，支持逐项撤销和全部撤销。禁用或删除保留数据，但生效后全部插件能力（含历史结果查看和导出）均不可用。升级启动失败时，再次完整重启恢复旧版，不回滚业务数据。受管后端提供立即重启，运行中的测量、序列和信号输出会阻止重启；未保存编辑直接丢弃。外部后端模式须手动完整重启后端和桌面。不要修改插件状态文件或重命名安装包绕过版本校验。安装 FFT 不会安装音频驱动，也不会授予功能权益。

参考 OpenTest-Plugins 开发插件

将插件项目克隆到自行选择的位置，按**该项目自己的 README 和 dev-kit/README.md**准备环境。为插件项目准备 Node.js ≥22.14.0、Corepack/pnpm 10.6.5、JDK 21 和 Maven，设置 JAVA_HOME，通过 PATH 或 MAVEN_HOME 提供 Maven。随仓 dev-kit 提供前端 SDK；Java 依赖需先在匹配宿主的 apps/backend 执行 mvn clean install，或在宿主根目录执行 pnpm prepare:backend-deps（编译测试但跳过执行）。执行前先停止源码后端。两边须使用同一 Maven 本地仓库；插件解析公开依赖，不导入宿主私有源码。

git clone https://github.com/crysound/OpenTest-Plugins.git
Set-Location .\OpenTest-Plugins

开发时可参考 OpenTest-Plugins 内的以下位置：

参考位置	参考内容
`plugins/fft-tools/plugin.json`	插件身份、宿主兼容范围、入口和贡献声明
`plugins/fft-tools/frontend/index.ts` 与 `plugins/fft-tools/frontend/src/contributions/`	前端激活、测量工作区及参数编辑器
`plugins/fft-tools/backend/src/`	后端登记、测量提供者及执行处理器
`plugins/fft-tools/backend/src/main/java/com/opentest/plugins/fft/measure/` 与 `plugins/fft-tools/frontend/locales/`	类型化业务配置、提供者执行及国际化资源；清单声明 `configVersion`
`dev-kit/README.md`	公开 SDK 使用、依赖配置与接口边界

准备好该项目的环境后，在插件仓库根目录执行：

node tools/build.mjs fft-tools
Get-ChildItem -LiteralPath .\dist -Filter 'com.opentest.fft-tools-*.otplugin'

该命令校验本项目 dev-kit，通过 Corepack/pnpm 按冻结锁文件安装前端依赖，执行前端类型检查、测试和构建，再执行包含测试的 Java mvn package，输出 dist/com.opentest.fft-tools-<version>.otplugin。首次插件构建需要联网；生成的包按上方步骤通过宿主界面导入。普通插件开发使用随仓匹配的 dev-kit；公开接口变更时，由宿主接口维护者导出更新的材料。

使用活动安装目录开发插件

先通过正常 .otplugin 流程安装插件并完成所需的完整重启。然后在插件仓库根目录创建 Git 忽略的 plugin-development.json：

{
  "runtimeDirectory": "../opentest/.runtime/app"
}

路径可以是绝对路径；相对路径固定按该配置文件所在目录解析。在插件仓库执行 pnpm dev fft-tools 会构建并直接更新 FFT 当前活动的已安装目录；pnpm dev:watch 只构建和投递前端与语言资源。两者都不会安装前端依赖，也不会改写宿主活动插件状态。

宿主使用 pnpm dev 启动，它显式允许可变已安装内容。Java 改动后需重新执行完整插件 pnpm dev 并手动重启后端；前端改动部署成功后需完整刷新页面，不提供插件级热更新。清单或契约改动需要完整插件命令和后端重启。pnpm start 与安装版保持严格校验，会拒绝已修改的包；恢复严格运行需正常卸载并重新安装。

7. 完成真实麦克风测量、保存与重开

使用实际麦克风输入，不使用输出/回环通道、已有文件或模拟源。首次检查只需一路输入。

确认 Windows 已启用麦克风，输入电平随说话变化，并允许桌面应用访问。在 OpenTest 中按需刷新设备列表，找到该真实 WASAPI 设备。设备名称因机器而异，不要求必须是 Realtek。
从工程菜单选择新建工程 / New Project，例如 First FFT，或打开第 6 步创建的工程。
在工程通道面板选择 ＋ / 硬件配置 / Hardware Configuration，在弹窗中再选 ＋ / 新增通道 / Add Channels，展开麦克风设备，勾选至少一路物理输入，点击提交 / Submit。确认输入已经加入工程且在线。
在 Measure → FFT 的输入通道 / Input Channels中再次选中该通道。加入工程和选为 FFT 输入是两个步骤。保留基础默认 FFT 参数，将停止方式 / Stop Method设为手动 / Manual；采样格式以实际设备支持为准，支持时可使用 48 kHz。首次检查不启用高级授权模式。
点击开始 / Start，在麦克风附近说话，观察实时频谱响应，采集约六秒。无需启用扬声器输出或信号发生器。只有空网格、许可证报错或运行立即失败，都不算通过。
点击一次停止 / Stop，等待控件恢复就绪，测试数据 / Test Data中出现新记录。正常停止会保存已采结果，此流程无需另找“保存”按钮。记下工程和本次记录或时间。
选中新记录并检查 FFT 图表。正常退出 OpenTest，等待后端结束，再用 pnpm start 重启，打开同一工程，在测试数据中选中同一条已保存记录，确认无需新采集即可显示其频谱。

首次运行只有满足以下全部条件才算完成：

桌面与后端按预期配置启动，工作区已获授权。
完整重启后 FFT 已登记，频谱图正常显示。
真实麦克风数据产生会变化的频谱。
正常停止后保存结果，完整重启后仍能回读。
桌面及其管理的后端正常退出。

现有插件验收辅助脚本会检查持久化记录、麦克风 WAV 非零采样、已保存 FFT 数据和历史渲染。它依赖已准备的验收会话及工程，不能代替上述环境配置和界面安装流程。本文提供操作方法，不代表你的设备已通过实测；麦克风冒烟检查也不能证明仪器级校准精度。

使用专用采集设备时，先安装厂商驱动、连接设备、刷新发现，再绑定其真实输入。仅安装 ASIO 驱动不表示硬件已经在线，设备专项校准和性能验收应另外执行。

8. 日常开发与故障排查

完成首次准备后，在已配置开发工具的终端执行：

pnpm dev

该命令启动前端源码服务、通过 Maven clean package -DskipTests 构建并运行可执行 JAR 的 Java 后端及桌面源码入口，并准备必要 SDK/本机模块产物，无需先做完整构建。独立命令 pnpm dev:frontend、pnpm dev:backend、pnpm dev:desktop 需要分别使用已配置工具的终端；关闭独立桌面不会关闭独立后端。本文首次测量仍按 build/start 路线进行。

后端加载插件后等待前端登记，超过两分钟只记录提示；后端启动或重启就绪后，完整刷新页面即可继续登记，开发与生产遵循相同规则。实际激活失败或超时仍进入恢复流程。dev、dev:desktop 默认打开 DevTools，显式 OPEN_DEVTOOLS=false 可关闭；其他入口默认关闭。

仅用浏览器开发前端时，由于没有 Electron 认证桥，还需基于 apps/frontend/.env.example 在 apps/frontend/.env.local 配置公开认证参数；此模式不提供桌面设备与插件能力。OPENTEST_ENV_FILE、OPENTEST_LOCAL_SETTINGS_PATH、OPENTEST_BACKEND_CONFIG 可指定其他本机配置文件，跨终端建议使用绝对路径。

现象	检查或处理
PowerShell 禁止脚本执行	组织策略允许时可手动执行 `Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass`，仅作用于当前进程；机器级策略可能优先。
找不到宿主工具命令	按第 3 节自行安装并配置工具，运行 `pnpm deps:check`；检查 PATH、JAVA_HOME 和 MAVEN_HOME。
找不到插件构建工具	按插件项目自己的 README 检查 Node/Corepack、`JAVA_HOME`，以及通过 PATH 或 `MAVEN_HOME` 提供的 Maven。
原生材料缺失	检查 `native/windows-amd64`、其 `prd` 覆盖目录及各自配套的默认 `License.dat`，同时核对桌面 vendor 目录和显式路径覆盖。
npm Git 依赖失败	检查仓库地址、GitHub 访问权限、网络连接和 Git 认证。
`node-gyp`/C++ 编译失败	检查 MSVC、Windows SDK、是否按要求重启，以及当前启用的 Python 3.11 或更新版本。
Java 依赖下载失败	检查 Maven settings、实际本地仓库及远端访问；开发、完整构建与依赖准备默认遵循同一配置，显式仓库覆盖除外。
图表空白	检查 CRYChart 制品与构建完整性记录、容器尺寸、实际数据和浏览器控制台；可运行 `pnpm test:chart:browser` 验证宿主绘图链路。
登录或 FFT 授权失败	检查两侧 Casdoor 配置、已登记回调、业务服务与权益，或离线授权有效性。
无麦克风或无法开始	检查 Windows 权限、设备发现、输入在线状态、工程绑定、FFT 输入选择和功能授权。
看不到插件	检查安装包兼容版本、导入成功、桌面及后端完整重启和后端日志。
插件 dev-kit 摘要不匹配	检查前端材料与锁文件匹配，修复本地变化前先比较原始字节；Java 依赖通过 Maven install 提供。不修改摘要、不导出不相关的 kit。
端口冲突或后端超时	检查 `19010`、`15021`、`19021`、原生材料及后端日志；关闭冲突实例，或在根环境文件设置 `FRONTEND_PORT`、`BACKEND_PORT`、`GRPC_PORT`；改变 HTTP 端口时同步回调。
停止后没有可读结果	等待保存完成，检查错误与后端日志；失败/取消的运行或仅在内存中的图表不能证明已持久保存。

目录与进一步阅读

目录	职责
`apps/frontend`	Vue 界面、工程、工作区、图表及前端插件宿主
`apps/backend`	Java 服务、授权、设备、算法和持久化
`apps/desktop`	Electron、受管理后端生命周期及本机模块
`apps/native`	原生 C++ 源码与构建工程；后端运行材料在 `apps/backend` 下维护
`sdks/client/typescript`	客户端 API、协议类型、HTTP/gRPC 及桌面共享内存访问
`sdks/plugin`	公开插件 SDK 材料
`tools`	构建、启动、交付及依赖准备
`tests/acceptance`	真实桌面验收辅助脚本

Setup、Measure、Report 是宿主工作区。FFT 源码及构建工具由 OpenTest-Plugins 维护，可用插件及兼容的宿主版本以该仓库为准。Monitor 由宿主内置。宿主构建不会自动构建或安装外置插件。

许可协议

本仓库的 OpenTest 自有代码及组件采用 OpenTest Community License 1.0，详见中文协议与英文协议。中英文解释不一致时，以中文版本为准。第三方组件遵循各自许可证；免费许可范围及需要商业许可的场景以协议正文为准。

Navigation Menu

Repository navigation

README.zh-CN.md

README.zh-CN.md

OpenTest

1. 克隆前准备

2. 克隆 OpenTest

3. 准备开发环境、原生库与项目依赖

开发者自行安装工具

安装项目依赖与原生材料目录

云账号与业务授权服务

离线授权替代路径

5. 构建并启动宿主

6. 取得并安装 FFT

参考 OpenTest-Plugins 开发插件

使用活动安装目录开发插件

7. 完成真实麦克风测量、保存与重开

8. 日常开发与故障排查

目录与进一步阅读

许可协议

FilesExpand file tree

README.zh-CN.md

Latest commit

History

README.zh-CN.md

File metadata and controls

OpenTest

1. 克隆前准备

2. 克隆 OpenTest

3. 准备开发环境、原生库与项目依赖

开发者自行安装工具

安装项目依赖与原生材料目录

云账号与业务授权服务

离线授权替代路径

5. 构建并启动宿主

6. 取得并安装 FFT

参考 OpenTest-Plugins 开发插件

使用活动安装目录开发插件

7. 完成真实麦克风测量、保存与重开

8. 日常开发与故障排查

目录与进一步阅读

许可协议