Trove 底座测试指南

本套件是可安装、可运行的验收材料。以当前 Manifest v1、Wire Protocol v1 和 @trove/plugin-sdk@0.1.0 为基础；插件 ID 均使用 dev.trove.qa.*，不占用正式插件命名空间。

快速验收

按 README 执行 pnpm install --frozen-lockfile、pnpm run pack。
在底座添加本地源 dist/index.json，先安装「01 · Host 能力检查」「02 · 数据隔离对照」「03 · 原生后端检查」。逐一打开，点击「运行常规检查」。
安装「04 · 公共服务提供方」，再安装并打开「05 · 跨插件调用」。提供方没有 UI；调用时才启动。
安装「06 · 可选依赖缺失」，检查缺失服务报错的同时 Host 仍然可调用。
在 Host 检查页按需执行文件选择、确认对话框、通知、剪贴板、快捷键和窗口操作。结果中「已执行 · 请观察」不代表系统效果已经通过人工验收。
使用「保存 JSON 报告」将报告写入本插件的数据目录；结果会显示路径。也可展开「原始报告」查看全部错误码和返回值。

pnpm run pack 会重新构建并覆盖本地生成文件。它不安装插件、不启动桌面应用、不修改官方软件源。源码修改后生成同 ID/版本的新内容，可能被底座的版本不可变校验拒绝；重复开发时先卸载该测试插件，或主动提高版本。

插件矩阵

工程	ID 后缀 / 版本	覆盖与预期
`test-host`	`host` / 1.0.0	无后端 UI；SDK 上下文、Unicode/JSON、32 路并发、服务发现、存储/文件 CRUD、错误码、桌面手动操作
`test-isolation`	`isolation` / 1.0.0	与 host 使用同一个持久化键；读到各自 ID，关闭并重新打开后保留
`test-self`	`self` / 1.0.0	UI 打开时启动后端；`@self`、环境与参数、24 路乱序请求、200 KiB 以上消息、取消/超时、Host 回调、事件
`test-provider`	`provider` / 1.0.0	Backend-only；服务 `dev.trove.qa.provider.probe@1.0.0`；按需启动、20 秒空闲退出
`test-consumer`	`consumer` / 1.0.0	必需依赖 provider 1.x；公开服务调用、事件、输入/输出契约
`test-optional`	`optional` / 1.0.0	可选服务不存在；UI 与 Host 正常，缺失服务调用返回 `service.not_found`
`test-autostart`	`autostart` / 1.0.0	Backend-only；重启底座后应自动运行，公开服务为 `dev.trove.qa.autostart.probe`
`test-upgrade-v1`	`upgrade` / 1.0.0	安装基线，在面板手动写入升级标记
`test-upgrade-v2`	`upgrade` / 1.1.0	同 ID 更新；读取 1.0.0 写入的标记，支持回滚验收
`test-required`	`required` / 1.0.0	故障源：必需服务不存在；当前底座调用时返回 `service.not_found`
`test-incompatible`	`incompatible` / 1.0.0	故障源：要求 provider 2.x；安装 provider 1.x 后调用返回 `service.version_mismatch`
`test-crash`	`crash` / 1.0.0	故障源：按钮让自己的后端 exit 42；观察重启、连续崩溃熔断与手动重试
`test-start-timeout`	`start-timeout` / 1.0.0	故障源：收到 welcome 但不发送 ready；返回 `provider.start_timeout`
`test-bad-handshake`	`bad-handshake` / 1.0.0	故障源：错误会话令牌；Host 拒绝连接，进程启动失败
`test-stubborn`	`stubborn` / 1.0.0	故障源：忽略 shutdown；超过 500 ms 宽限期后应被底座终止

每个工程都有自己的 curio.json。UI 源文件来自 shared/ui/，构建到 dist/ui/；Rust 源码在 shared/backend/，构建产物复制到各包的 backend/probe。生产包包含 SDK、静态资源和所需原生可执行文件，不依赖工作区相邻目录。

生命周期、状态与数据

按需启动：先安装 provider，不进行任何服务调用；在底座看其未启动。打开 consumer 运行检查后应启动；停止调用约 20 秒后退出，再调用得到新 PID。查询 host.services.getStatus 不应启动提供方。
随底座启动：安装 autostart，完全退出并重启 Trove。在进行 info 调用前，用 Host 检查页的「检查随底座启动的服务」确认 Available，或在管理界面确认进程已运行。单纯调用成功不能证明 app-start 生效。
UI 生命周期：重复打开同一插件应聚焦已有窗口；关闭后无失效窗口。重开后读取标记仍存在；退出底座应清理所有测试后端、连接和快捷键。
禁用与卸载：禁用 provider 后 consumer 调用应报告 provider.disabled；启用后恢复。卸载后调用应报告 service.not_found。
崩溃隔离：安装 crash，先读取 PID，再触发崩溃，读取新 PID。短时间连续崩溃三次后应得到 provider.crash_loop。同时操作 Host 与 self 插件，确认未被连带中断；在底座管理页手动重试恢复。
停止无响应进程：打开 stubborn，记录 PID，在底座停止或禁用；约 500 ms 宽限期后该 PID 应消失。
存储隔离：分别运行 host 与 isolation；两者的 qa.namespace-owner 值必须是自己的 ID。后端回调 Host storage 的数据归属后端提供方，不能落到 consumer 的命名空间。

常规检查只清理自己创建的临时文件/键。qa.namespace-owner 与固定的 qa.backend-roundtrip 保留供人工检查，报告和升级标记也会保留。存储大小限制测试使用超过 1 MiB 的值；不会填满整个存储配额。剪贴板按钮会替换系统剪贴板；快捷键使用 Cmd+Shift+Option+F9，等待最多 15 秒，并在结束时注销。系统通知是否可见需人工确认。

升级与回滚

常规软件源同时包含 1.0.0 与 1.1.0；默认安装可能直接选到最新版。要测试完整路径，先手动安装基线包：

"$TROVE_BIN" curio install dist/packages/dev.trove.qa.upgrade-1.0.0.curio --no-input

打开插件，点击「写入升级基线标记」，记录 token，再安装更新：

"$TROVE_BIN" curio install dist/packages/dev.trove.qa.upgrade-1.1.0.curio --no-input

运行中更新应正确暂存或切换，不混用两个版本的 UI 资源。关闭并重新打开后应显示 1.1.0，标记仍由 1.0.0 写入、token 不变。使用底座的版本切换/回滚操作回到 1.0.0，验证数据继续保留。卸载时分别验证保留数据和删除数据，再重装读取。

故意无效的安装材料

dist/invalid/cases.json 列出每个 .curio 和应返回的错误码。覆盖 22 种情况：

JSON 损坏、未知字段、schemaVersion 不支持、保留 ID、非法版本、引擎不兼容。
UI 缺失、UI/Backend 均未声明、Manifest 路径越界、覆盖保留环境变量。
没有后端却提供服务、服务命名空间错误、后端/契约文件缺失、契约版本不一致、非法 JSON Schema。
ZIP 路径越界、绝对路径、反斜杠路径、大小写碰撞、符号链接、损坏压缩包。

dist/invalid/source-cases.json 列出 4 种合法索引携带异常下载元数据的情况：SHA-256 错误、大小错误、目标架构不匹配、索引与包身份不一致。它们不加入常规软件源。

无效安装应有明确错误，已安装列表和当前版本不变化，staging 清理完成。不要将所有 .curio 不加区分地批量安装；dist/packages/ 才是结构合法的测试包。

自动验证

export TROVE_BIN=/absolute/path/to/app/target/debug/trove
export TROVE_APP_DIR=/absolute/path/to/app
# 可选：复用现有 Cargo 缓存；默认使用 dist/host-target。
export TROVE_QA_TARGET_DIR=/absolute/path/to/app/target
pnpm run verify

验证流程：

编译 tools/host-check.rs，链接指定 app 仓库的真实 PackageManager、ServiceBus、BackendSupervisor 和 Unix Gateway，禁用桌面特性。
用 Trove CLI 的 protocol test 检查后端的握手、分片接收、并发请求 ID、结构化错误和优雅退出。
在 /tmp/trove-qa-* 创建隔离数据目录，安装真实包；验证无效材料、软件源本地/HTTP 下载、持久化、升级/回滚和卸载。
通过测试桥将真实生产 SDK 连接至真实 Service Bus。直接运行 shared/ui/checks.js 中的检查；后端走真实 Unix socket 和原生子进程，不使用 mock 服务。
默认策略下检查实际行为，再单独开启严格契约模式验证参数和返回值；随后恢复默认模式。测试取消清理、服务禁用、启动超时、认证失败、空闲退出、强制停止、崩溃隔离/熔断。
写入 dist/verification.json，失败时非零退出；正常结束时停止测试 HTTP 服务、后端进程，删除隔离目录。不会触碰用户的 Trove 安装注册表或现有插件数据。

首次编译可能需要较长时间。自动结果不等于桌面 WebView/系统交互的完整验收；真实 WebView 注入、窗口视觉、系统权限、快捷键触发、通知展示、app-start 的应用启动调度仍应按上文手动检查。

当前能力边界

当前底座默认未调用 strict_contracts(true)。公共服务的无效返回值可能直接透传，因此 consumer 面板的「公共服务返回值契约」会报告失败；这是能力探针，不能将其误判成自动通过。验证脚本把默认策略列为观察项，严格模式断言单独标注，不修改底座源码。
必需依赖与可选依赖目前都在服务调用阶段暴露缺失；不要预设安装器或打开窗口时一定拦截。两个插件用于观察和比较这一行为。
以实际已注册服务为准。规范草案中的 host.process、host.screen、host.keychain、辅助功能、文件 watch 等未被本套件宣称为已实现；没有用模拟服务填补这些能力。
macOS 原生构建按当前架构出包；另一架构需在对应机器重新构建。自动测试覆盖目标架构拒绝，不验证跨架构二进制执行、签名、公证、真实公网 TLS、断电原子性或系统资源耗尽。
dist/ 中本地索引包含绝对 file:// 地址；移动仓库后重新打包生成索引。HTTP 源由 pnpm run serve 动态改写为本机地址，仅监听 127.0.0.1。

10 KiB Raw Blame History Unescape Escape