# @woodenhorse/runtime-client

框架无关 SDK，浏览器及 Node.js 22+，不导入平台源码。官方入口中的模板只需：

```js
import {createRuntimeClient} from '@woodenhorse/runtime-client';
const client = createRuntimeClient({
  baseURL:'https://agents.ipboxs.com',projectId:'PROJECT_UUID'
});
const session = await client.bootstrap();
const context = await client.context();
for await (const event of client.send(session.conversationId,'你好')) {
  if(event.type==='delta') console.log(event.content);
}
```

宿主通过 widget `data-data='{"userId":"example","authToken":"HOST_TOKEN"}'` 或官方入口 `#data=<编码 JSON>` 传入可选任意 JSON。没有 data 即为空上下文，正常聊天。SDK 从可信宿主页取得连接和 data，bootstrap 自动提交；平台把完整 context 提供给 AI 回复和连接器规划，模板自行决定展示和链接用途。字段没有平台固定业务含义，不自动授予登录身份。宿主应知悉 data 中的 token 也会提供给选定的 AI 服务。

独立运行可在构造参数中传 `data`，SDK 自动建立访客连接；需要平台签名身份时可另传 `getToken({signal})`，每次请求调用。官方宿主页按项目和标签页保存8小时访客连接，刷新恢复，data 改变则隔离新连接。SDK 本身不访问浏览器存储。显式平台签名 token 不存储。请求使用 credentials:omit、redirect:error，不自动重放消息或业务调用。

context 固定在 conversationId，变更开启新会话，新建会话使用入口数据，历史会话保留各自快照。`messages(id)`、`deleteConversation` 更新 SDK 当前选择；`client.context()` 返回所选会话的数据。SDK 的 `connector(id,input)` 自动附带当前 conversationId，服务器验证归属后使用上下文认证。调用前先 bootstrap 或打开会话。

连接器按用途和 schema 配置；AI 从 context 匹配参数。认证头和 POST requestValues 支持 `<data.path>` 宿主路径及 `<NAME>` 服务端环境变量。平台不规定客户登录和查询接口。requiresIdentity 默认 false；上游自行验证其认证，依赖平台签名身份的接口显式开启。环境变量 Secret 不返回模板或模型，宿主 data 则由用户明确提供给两者。缺少某连接器参数不会阻断聊天。

`await client.voiceInput({signal})` 通过可信宿主页录音转写，返回 `{text}` 供用户确认，不自动发送。原生录音可 `client.transcribe(pcm)`，格式16kHz 单声道 signed16 PCM。取消流使用 AbortController；中断后读取历史确认保存状态。

SDK 可复制或 npm pack 安装。完整接口和开发发布流程见 [Runtime API](https://agents.ipboxs.com/docs/runtime-api.md) 与 [开发指南](https://agents.ipboxs.com/docs/agent-development.md)。开发凭证和项目 API Key 不进入静态模板。

模板自定义链接示例（字段和目标由模板决定）：

```js
const data = await client.context();
const url = new URL('https://customer.example/profile');
if (data && typeof data === 'object' && typeof data.userId === 'string') {
  url.searchParams.set('ref', data.userId);
}
link.href = url.href;
```

`send` 可选 `interactionGoals: [{id, description}]`：由项目模型结合最近对话选择当前展示目标，结果在 `saved.cards[].interactionGoal`，历史保留。模板仅处理自己实现的ID；这不是业务执行或授权。无匹配/失败不产生卡。见 Runtime API 文档。
