前端 SDK

快速开始

先在应用后端配置 用户 token 接口，再使用 createNuva() 初始化客户端。

import { createNuva, Message } from "@nuva/sdk";

const nuva = createNuva({
  getAccessToken: async () => {
    const response = await fetch("/api/nuva-token", {
      method: "POST",
      credentials: "same-origin",
      // 按应用的鉴权配置添加 CSRF header。
    });
    if (!response.ok) {
      throw new Error(`Token request failed: ${response.status}`);
    }

    const data: unknown = await response.json();
    if (typeof data !== "object" || data === null ||
        !("token" in data) || typeof data.token !== "string" || !data.token) {
      throw new Error("Invalid token response");
    }
    return data.token;
  },
});

const main = await nuva.sessions.getMain();
const agent = nuva.agent({ sessionId: main.id });
const receipt = await agent.send(Message.text("开始广告创作，请先列出需要的产品资料。"));

每个登录用户复用一个客户端实例。退出或切换账号时调用 nuva.close()，然后为新用户创建实例。服务凭证仅配置在后端。

React 接入

在组件树中挂载 NuvaProvider。调用 useAgent({ sessionId }) 读取消息并发送操作。

import { NuvaProvider, useAgent } from "@nuva/sdk/react";
import type { NuvaClient } from "@nuva/sdk";
import { MessageList } from "./MessageList";

function App({ client, sessionId }: { client: NuvaClient; sessionId: string }) {
  return (
    <NuvaProvider client={client}>
      <Conversation sessionId={sessionId} />
    </NuvaProvider>
  );
}

function Conversation({ sessionId }: { sessionId: string }) {
  const agent = useAgent({ sessionId });
  if (agent.loadStatus === "loading") return <p>加载中…</p>;
  if (agent.loadStatus === "error") return <p role="alert">{agent.error.message}</p>;

  return (
    <>
      {agent.freshness === "stale" && <p>连接中断，正在显示已保存的内容。</p>}
      <MessageList messages={agent.messages.items} agent={agent} />
    </>
  );
}

MessageList 是应用内的消息组件。按 message.content 的顺序渲染内容，并使用 agent.respond() 提交客户端工具结果。

卸载组件只结束本地订阅。已开始的服务端工作继续运行。

消息与引用

发送消息

await agent.send(Message.text("继续修改第二条脚本。"));

await agent.send(
  Message.create()
    .text("修改 ")
    .mention(script)
    .text(" 的开场，保留其他内容。")
);

await agent.send(
  Message.create().replyTo(existingMessage).text("使用这一版。")
);

构建方法返回新的消息值。send() 成功后返回已保存消息的引用；Agent 回复通过消息订阅到达。

{
  "requestId": "request_21",
  "message": {
    "sessionId": "work_product_a",
    "messageId": "message_12"
  }
}

记录引用

将 API 返回的 RecordLink 传入 mention() 或 attach()。revision 指定记录版本。

{
  "ref": { "kind": "script", "id": "script_1", "revision": "1" },
  "label": "脚本 1"
}

接收消息

{
  "ref": { "sessionId": "work_product_a", "messageId": "message_10" },
  "role": "assistant",
  "createdAt": "2026-10-12T18:00:00Z",
  "state": "complete",
  "attachments": [],
  "content": [
    { "id": "part_text", "type": "text", "format": "markdown", "text": "脚本已生成。" },
    {
      "id": "part_script_1",
      "type": "resource",
      "record": {
        "ref": { "kind": "script", "id": "script_1", "revision": "1" },
        "label": "脚本 1"
      }
    }
  ]
}

按 SDK 返回的顺序显示 messages.items。流式更新会合并到原消息；无需自行拼接网络片段。

完整消息示例

客户端工具

问答、许可确认和内容审核通过消息中的 dynamic-tool 交互。使用 toolName 选择处理函数，使用 toolCallId 关联结果。

{
  "type": "dynamic-tool",
  "toolName": "nuva.review",
  "toolCallId": "call_17",
  "state": "input-available",
  "input": {
    "prompt": "请审核这条脚本。批准后将继续制作提示词。",
    "records": [{ "kind": "script", "id": "script_1", "revision": "1" }]
  }
}

提交结果

将收到的工具调用和结果传入 respond()。结果必须符合该工具的 outputSchema。

// part 是消息中 state 为 input-available 的工具调用。
const receipt = await agent.respond(part, {
  decision: "reject",
  text: "先展示产品，再讲困扰。",
});

nuva.review 使用 decision: "approve" | "reject" 和 text。无补充说明时传入空字符串。方法在服务端保存结果后返回：

{
  "requestId": "request_22",
  "call": {
    "type": "dynamic-tool",
    "toolName": "nuva.review",
    "toolCallId": "call_17",
    "state": "output-available",
    "input": {
      "prompt": "请审核这条脚本。批准后将继续制作提示词。",
      "records": [{ "kind": "script", "id": "script_1", "revision": "1" }]
    },
    "output": { "decision": "reject", "text": "先展示产品，再讲困扰。" }
  }
}

后续 Agent 回复继续通过消息订阅到达。仍在等待回应的调用可从历史消息或转发消息中提交。

提交执行错误

无法取得有效结果时调用 fail()。用户拒绝审核应作为正常结果传给 respond()。

await agent.fail(part, {
  code: "EDITOR_UNAVAILABLE",
  message: "脚本编辑器加载失败。",
});

返回值包含 requestId 和状态为 output-error 的 call。

Host call

通过 onHostCall() 订阅已注册的网站交互。将 toolName 映射到应用的页面、编辑器或其他操作。

const unsubscribe = agent.onHostCall((part) => {
  if (part.type === "dynamic-tool") {
    if (part.state !== "input-available") return;
    host.receive(part.toolName, part.input, part);
  } else {
    host.receive(part.data.toolName, part.data.input, part);
  }
});

// 在组件卸载的清理函数中调用 unsubscribe()。

host.receive 是应用提供的处理函数。需要结果的 dynamic-tool 使用 respond() 或 fail() 回传结果。

不要求结果的 host call 使用 data-host-call。按其 input 执行应用操作，无需回传：

{
  "type": "data-host-call",
  "id": "host_19",
  "data": {
    "toolName": "workspace.showScripts",
    "input": {
      "records": [{ "kind": "script", "id": "script_1", "revision": "1" }]
    }
  }
}

Host call 同时保存在消息内容中。历史渲染只展示保存的内容；自动执行时按调用 ID 去重。

在服务端授权配置中启用对应 UI skill。前端处理函数使用该 skill 中注册的方法名和输入格式。

方法参考

query 接受可选的 cursor 和 limit。返回页包含 items 和 nextCursor；nextCursor 为 null 时已到末页。options 接受可选的 requestId。

错误处理

操作失败时 Promise 抛出 NuvaError。读取 code、message、retryable 和可选的 requestId。

命令错误中的 acceptance 为 not_accepted 或 unknown。unknown 表示尚不能确认服务端是否已保存操作。

重试同一操作时复用相同 requestId 和输入。缺省 requestId 由 SDK 生成；发生状态不明的错误时，保留错误中的 requestId。send() 或 respond() 返回成功仅表示该次输入已保存，后续生成结果从消息订阅读取。