常见问题排查
定位连接失败、服务缺失、开发会话冲突和打包错误。
核对日期：2026 年 9 月 11 日
本页目录
终端找不到 trove#
在 Trove 开发页面安装或检查命令行工具，打开新终端，确认当前选择的可执行文件：
command -v trove
trove --version
trove --help
Shell 命令可能指向应用包内部。重新构建另一个本地二进制，不会更新该应用包。先确认注册目标，再判断 CLI 与 Host 是否同一构建。若另一个 Host 可执行文件占用了数据目录，正常退出那个 Host，再使用目标构建重试。
Host Bridge 不可用#
bridge.host_unavailable 表示页面没有 Host 注入的桥接。通过 trove dev 或 Trove 中已安装的 Curio 打开页面。普通浏览器只渲染 UI，不提供原生 API；浏览器测试请显式创建 Mock 客户端。
bridge.reloaded、bridge.disconnected 表示客户端连接已结束。取消过时的 UI 工作，并建立新的页面或客户端连接。对已显式 disconnect 的客户端再次调用 ready，不能恢复它。
开发无法启动#
trove check --json
trove --verbose dev
| 现象 | 检查与恢复 |
|---|---|
| 初始化拒绝目录 | new 要求新目录，空目录也不例外；更换路径或按已有项目指南接入 |
| 缺少依赖 | 使用工程选择的包管理器安装，保留 SDK vendor 包 |
| UI 服务等待超时 | 对齐 Manifest URL 和实际端口；动态端口必须读取 TROVE_DEV_PORT |
| 地址被占用 | 停止遗留 UI 进程或换端口；已有服务用 --no-start-ui --ui-url ... 连接 |
| Curio ID 已运行 | 结束该 Curio 的旧开发会话，独立工程使用不同 ID |
| Host 可执行文件冲突 | 检查 CLI 注册和运行中的 Host，不同可执行文件不能静默接管数据目录 |
不要通过删除用户数据规避开发冲突。Ctrl-C 只停止当前 CLI 会话，不会退出所有 Host 会话。
请求与服务错误#
| Code | 含义与下一步 |
|---|---|
request.invalid_params | 检查 Contract 中的参数名、类型和必需字段 |
request.invalid_options | 检查 timeoutMs 为有限数字且在 SDK 范围内 |
request.timeout | 查看提供方日志和耗时，只有可安全重复的操作才重试 |
request.cancelled | 请求已取消，结束 UI 加载状态，不展示成功结果 |
service.not_found | 查询已注册服务，安装或启动目标提供方 |
service.method_not_found | 通过 describe 检查方法是否缺失或仍在规划中 |
service.version_mismatch | 对齐声明的兼容范围与已安装服务版本 |
service.contract_violation | 对照 JSON Contract 检查参数、结果与事件 |
provider.disconnected | Backend 连接结束，检查进程输出与生命周期 |
self.unavailable | 缺少操作所需的 Curio 或 Backend 上下文 |
host.storage.value_too_large / host.storage.quota_exceeded | 大型数据改用文件，或减少存储内容 |
保留 TroveError 的 code、message 和可用的 traceId。retryable 为 true 不代表自动重试。实现功能前查看 Host 能力状态，避免调用规划接口。
开发正常，安装后失败#
对齐 ui.entry 与构建输出，将依赖资源放入 package.files。使用相对资源路径，检查动态 import，在开发服务停止时测试安装版。生产 Manifest 不保留 development.ui.url。
Backend 入口必须是目标平台的真实可执行文件，检查权限、架构和运行依赖。pack --dry-run 不能证明尚未构建的产物有效，应实际执行 pack 并确认成功。
下载返回登录页时，让 Release 附件可以匿名访问。Git 认证只覆盖软件源索引与仓库，不会转发到 HTTP 包下载。
准备有用的复现信息#
记录 Host/CLI 版本、macOS 版本与架构、Curio ID/版本、失败命令、预期与实际行为。复制调试控制台的相关筛选输出，附上能复现的最小 Manifest 或请求，去除密钥和个人数据。
在新的开发会话中重试最小失败步骤。测试与调试解释日志限制，以及 Mock、原生接入与安装包验证的区别。
生成客户端与套件更新#
bindings.stale 表示输出缺失或与契约不一致。先运行 trove generate，修复它报告的导出、契约或路径错误，再运行 trove check。不要通过手改生成文件解决。
kit.modified 表示同版本 vendor 套件被本地修改，CLI 会拒绝覆盖。先保留所需修改并恢复明确的套件版本，再运行 trove kit 和工程包管理器的安装命令。业务逻辑应放在工程源码中。
旧 SDK 升级请按迁移步骤处理公开导入和生成客户端。
运行时没有输出#
先在调试区核对当前 Curio、Run ID、开发或安装来源和产物。终端与底座读取相同的运行日志；重新运行会替换旧 Run 的内存视图，没有磁盘历史。
Host 只能读取进程已经写出的内容。C/C++ 库将 stdout 缓冲到进程退出时，会导致操作时无日志、关闭时集中出现。应在产生日志的位置使用行缓冲或显式 flush；仅在 Host 侧刷新界面无法解决源端缓冲。正常停止会留出有限排空时间，强制终止无法保证取得未 flush 的内容。
输出中的设备名称来自插件或其依赖，日志采集不会验证型号。应核对设备返回的产品信息，不能只凭通用 VID/PID 映射判定具体型号。
Curio 引用不可用#
| 现象 | 排查 |
|---|---|
| curio.not_installed | 用的是 Curio ID 而非服务子命名空间？安装提供者或开启其开发会话 |
| curio.disabled | 在 Host 启用提供者 |
| curio.no_public_services | 仅私有 Backend 不可跨插件调用；提供者需声明 services.provides |
| service.version_mismatch | 对齐已安装服务版本和消费方 requires 范围 |
| curio.ambiguous_api | 检查公开服务树的名称冲突，尤其 then/events 和方法与子服务重名 |
| 方法类型为 unknown | 设置 bindings.services[].curio，运行 trove generate，确认生成的 .d.ts 被 tsconfig 包含 |
| get 成功但调用失败 | get 不启动进程；检查启动日志、ready、超时及调用时的安装状态 |
UI 不弹出是正常行为；跨插件仅调用 Backend。公开后端默认可在窗口关闭后继续运行，因此日志也可继续输出。开发会话关闭仍会结束该次开发运行。