接入已有 Web 项目

确认接入边界#

本指南适用于能构建成静态 HTML、JavaScript 和 CSS 的前端工程。Trove 会在 WebView 中加载这些资源。React、Vue 都可以使用同一套 SDK，不要求采用专用渲染框架。

Trove 不会自动打包或托管 SSR 服务。请导出静态客户端，或把必要的原生、服务端逻辑放入 Backend。不要把密钥或仅原生环境可用的模块放进浏览器构建产物。

获取匹配版本的 SDK#

当前 SDK 随 CLI 模板分发。在已有工程旁边创建一个独立临时模板：

trove curio init sdk-starter --template web --yes

把 sdk-starter/vendor/ 复制到你的工程。在原有 package.json 的 dependencies 中合并下面这条依赖，保留其他配置，然后执行所用包管理器的安装命令：

{
  "dependencies": {
    "@trove/plugin-sdk": "file:vendor/trove-plugin-sdk-0.1.0.tgz"
  }
}

这是依赖片段，不是完整 package 文件。如果已安装 CLI 生成的版本不同，使用实际生成的文件名。提交 vendor/ 和更新后的锁文件。trove curio init 只创建新目录，不会导入或覆盖已有工程。

添加 Manifest#

在现有工程根目录创建 curio.json。下面是完整的 UI-only 示例，假定你有 npm 的 dev、build 脚本，并输出到 dist/：

{
  "schemaVersion": 1,
  "id": "dev.example.my-web-app",
  "name": "My Web App",
  "version": "0.1.0",
  "engine": { "trove": ">=0.1.0 <1.0.0" },
  "ui": { "entry": "dist/index.html" },
  "development": {
    "ui": {
      "url": "http://127.0.0.1:5173",
      "command": ["npm", "run", "dev"]
    }
  },
  "build": { "command": ["npm", "run", "build"] },
  "package": { "files": ["dist"] }
}

将 ID、名称、输出路径和命令调整为你的项目配置。ui.entry 是本地生产 HTML 文件；development.ui.url 是开发地址。不要把远程网站 URL 填入 ui.entry。

对齐开发地址与资源路径#

使用 Vite 时，把下面配置合并到已有配置中，保留框架插件：

import { defineConfig } from "vite";

export default defineConfig({
  base: "./",
  server: { host: "127.0.0.1", port: 5173, strictPort: true },
  build: { outDir: "dist" },
});

相对资源路径可以让打包后的入口正确解析 JS 和 CSS。打包后检查图片、字体、动态 import 和页面导航。只有一个 HTML 入口的应用可以使用 hash 路由，避免依赖 HTTP 服务的 history fallback。

如果开发服务已在运行，不要再次启动它，直接连接：

trove curio dev --no-start-ui --ui-url http://127.0.0.1:5173

同时开发多个工程时，分配不同固定端口，或采用本地开发中的模板动态端口方案。

在界面中连接 Host#

从事件处理函数或客户端生命周期中调用 SDK，为用户展示加载、成功与失败反馈：

import { trove, TroveError } from "@trove/plugin-sdk";

export async function inspectHost() {
  try {
    await trove.ready();
    return await trove.call("host.runtime", "getHostInfo", {});
  } catch (error) {
    if (error instanceof TroveError) {
      console.error(error.code, error.message, error.traceId);
    }
    throw error;
  }
}

仅导入 SDK 在 Trove 外也是安全的；使用默认客户端或读取其 context 需要 Host。不要在真实原生调用失败时静默返回伪造的成功结果。浏览器测试使用单独配置的 Mock 客户端。

分别验证开发与生产#

1. 在工程中执行 trove curio check，解决 Manifest 与依赖错误。
2. 执行 trove curio dev，确认 UI 正常，并获得真实 Host 响应。
3. 停止开发会话，执行 trove curio pack 和 trove curio install。
4. 保持开发服务器关闭，打开安装版本，检查路由和资源，再执行原生调用。

开发 URL 可访问不能证明安装包可运行。打包与分发说明文件选择和原生运行时的要求。