Client 请求
createKitClient 的配置、身份、数据面 API、附件与错误处理
显式接入自己的后端
新项目使用 createKitClient({ request, operations }) 配置实际接口;这是 Web 示例使用的同一入口。
operations 表示可选的接口调用映射,不是后端内部操作系统。每项包含 buildRequest 和 mapResponse,
Request 负责 HTTP 与错误映射;Client 复用现有 DTO 和方法签名。supports(name) 用于能力判断,
缺少的配置不会自动请求 Kit Server。旧 { baseUrl } 方式仍保留 Kit 固定路由兼容。
以下示例采用另一组 URL、POST 搜索与 { result } 响应;请求头、路径和参数由应用配置:
import { type ClientOperations, createKitClient } from "@openagentpack/kit-sdk/providers/kit";
import type { RequestClient } from "@openagentpack/kit-sdk/request";
// 只配置后端支持的功能。未配置的操作不会调用 Kit 路由。
export function createDataClient(request: RequestClient) {
const result = async <T>(response: Response): Promise<T> => (await response.json()).result;
const json = (value: unknown) => ({
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(value),
});
const operations: ClientOperations = {
agents: { buildRequest: () => ({ path: "/catalog" }), mapResponse: result },
agent: { buildRequest: ([slug]) => ({ path: `/catalog/${encodeURIComponent(slug)}` }), mapResponse: result },
sessionAgents: { buildRequest: () => ({ path: "/conversation-groups" }), mapResponse: result },
sessions: {
buildRequest: ([query]) => ({ path: "/conversations/search", init: json(query ?? {}) }),
mapResponse: result,
},
session: { buildRequest: ([id]) => ({ path: `/conversations/${encodeURIComponent(id)}` }), mapResponse: result },
createSession: { buildRequest: ([input]) => ({ path: "/conversations", init: json(input) }), mapResponse: result },
renameSession: {
buildRequest: ([id, title]) => ({
path: `/conversations/${encodeURIComponent(id)}/title`,
init: json({ title }),
}),
mapResponse: result,
},
sessionPlan: {
buildRequest: ([id, action]) => ({
path: `/conversations/${encodeURIComponent(id)}/preview`,
init: json({ action }),
}),
mapResponse: result,
},
archiveSession: {
buildRequest: ([id, confirmation]) => ({
path: `/conversations/${encodeURIComponent(id)}/archive`,
init: json(confirmation),
}),
mapResponse: result,
},
deleteSession: {
buildRequest: ([id, confirmation]) => ({
path: `/conversations/${encodeURIComponent(id)}/remove`,
init: json(confirmation),
}),
mapResponse: result,
},
uploadFile: {
buildRequest: ([file]) => {
const form = new FormData();
form.append("attachment", new Blob([file.bytes as BlobPart], { type: file.mimeType }), file.name);
return { path: "/attachments", init: { method: "POST", body: form } };
},
mapResponse: result,
},
fileStatus: {
buildRequest: ([id]) => ({ path: `/attachments/${encodeURIComponent(id)}/status` }),
mapResponse: result,
},
downloadFile: {
buildRequest: ([id, input]) => ({
path: `/attachments/${encodeURIComponent(id)}/content?conversation=${encodeURIComponent(input?.sessionId ?? "")}`,
}),
mapResponse: (response) => response,
},
usageLimits: { buildRequest: () => ({ path: "/account/limits" }), mapResponse: result },
};
return createKitClient({ request, operations });
}目录、上传、首次发送及产物组件绑定见 组件交互与后端调用。
createKitClient 来自 @openagentpack/kit-sdk/providers/kit,提供可配置的数据面调用;{ baseUrl } 兼容模式封装 Kit Server API,
可独立于 React 和 UI 组件使用。它负责请求与响应转换;对话订阅和发送编排由
useChat 或 Controller 负责。
底层 HTTP 统一由 Request 执行,SSE 字节处理由 Stream 执行。Client 使用现有数据方法与 DTO;独立 Request 不包含 这些业务方法、Kit 协议头和控制帧策略。
何时使用
- 在 React 之外调用 Kit Server:脚本、测试或自行编排订阅与发送的宿主。
- 需要 hooks 未覆盖的数据面方法:事件历史、归档删除计划、文件上传下载。
- 需要注入身份头、替换 fetch 实现,或排查协议版本与请求错误。
使用说明
初始化与运行时配置
configBaseUrl 由部署配置或宿主注入,指向提供 /api/config 的服务,不能假设它与页面同源。
先读取配置并校验协议主版本,再使用返回的 apiBaseUrl 创建业务 Client。
import { createKitClient, type KitClientOptions } from "@openagentpack/kit-sdk/providers/kit";
export async function createConfiguredClient(
configBaseUrl: string,
headersFor: (apiBaseUrl: string) => KitClientOptions["headers"],
) {
// 公开配置请求不携带身份;只有确认最终目标后才选择该目标的令牌。
const config = await createKitClient({ baseUrl: configBaseUrl }).config();
const baseUrl = config.apiBaseUrl || configBaseUrl;
return createKitClient({
// 空串表示沿用配置服务的来源,跨域部署时不能退回页面来源。
baseUrl,
headers: headersFor(baseUrl),
});
}Client 自动添加 x-kit-protocol-version。当前 Session 流、消息和审批使用 Kit 协议 2.x,
主版本不兼容应停止初始化并同步升级前后端。
成员登录与恢复
体验页在 createMemberAuthController 配置中传入 createChatProvider(request),
通过公开 标准事件工厂 填写业务接口。
Controller 提供的 RequestClient 绑定本次登录的固定应用身份;返回的 Provider 出现在
useMemberAuth(controller).chatProvider,页面显式交给 useChat。
同一身份复用同一实例;退出、到期、HTTP/SSE 鉴权失败使旧 Provider 失效。
该配置可选,已有默认 Client 接入保持兼容。
默认 Kit Server 必须登录。client.auth.login({username,password}) 获取 8 小时有效的成员
令牌;client.auth.me() 校验当前身份;client.auth.logout() 撤销当前登录。直接调用这些
方法不会替你存储令牌或清理 UI,默认体验页使用 createMemberAuthController + useMemberAuth
管理整个身份生命周期。
宿主提供按完整 apiBaseUrl(包括路径前缀)隔离的 MemberSessionStorage;只保存
{access_token, expires_at},不保存密码。默认 Web 使用 sessionStorage。配置缺少 auth 时
按 member 模式处理,不能静默开放匿名访问。以下示例的 Controller 应在启动时创建一次,
storage 由宿主实现。示例代码与 Skill 同源生成。
import {
createMemberAuthController,
type MemberAuthController,
type MemberAuthOptions,
} from "@openagentpack/kit-sdk/auth";
import { useMemberAuth } from "@openagentpack/kit-sdk/auth/hooks";
import { KitProvider } from "@openagentpack/kit-sdk/providers/kit/react";
import type { FormEvent, ReactNode } from "react";
// 公开配置解析出最终 API URL 后调用一次。宿主存储按带路径前缀的完整 URL 隔离,
// 只保存会话令牌及有效期。
export function createLogin(options: MemberAuthOptions) {
return createMemberAuthController(options);
}
export function MemberRoot({ controller, children }: { controller: MemberAuthController; children: ReactNode }) {
const auth = useMemberAuth(controller);
if (auth.status === "checking") return <p>正在恢复登录…</p>;
if (auth.status === "error") {
return (
<section>
<p role="alert">{auth.error}</p>
<button type="button" onClick={() => void auth.retry()}>
重试
</button>
</section>
);
}
if (!auth.client) {
const submit = async (event: FormEvent<HTMLFormElement>) => {
event.preventDefault();
const form = event.currentTarget;
const data = new FormData(form);
try {
await auth.login({
username: String(data.get("username") ?? ""),
password: String(data.get("password") ?? ""),
});
} catch {
// 控制器在快照中提供可安全展示的错误。
} finally {
const password = form.elements.namedItem("password");
if (password instanceof HTMLInputElement) password.value = "";
}
};
return (
<form onSubmit={submit}>
<label>
用户名 <input name="username" autoComplete="username" required disabled={auth.pending} />
</label>
<label>
密码{" "}
<input name="password" type="password" autoComplete="current-password" required disabled={auth.pending} />
</label>
{auth.error && <p role="alert">{auth.error}</p>}
<button type="submit" disabled={auth.pending}>
登录
</button>
</form>
);
}
return (
<KitProvider key={auth.generation} client={auth.client}>
<header>
{auth.member?.display_name}
{auth.member && (
<button type="button" onClick={() => void auth.logout()}>
退出登录
</button>
)}
</header>
{children}
</KitProvider>
);
}status 包含 checking、signed-out、signed-in、anonymous 和 error。只在获得 client 后挂载
业务页面,并以 generation 为 key 重建页面。退出、过期、HTTP 401 或 SSE unauthorized
会取消旧身份请求和订阅;网络恢复失败 / 退出撤销失败显示重试,403 配额错误不会误退出。
React hook 管理 start / dispose;非 React 宿主自行调用 start、subscribe 并在卸载时 dispose。
dispose 取消客户端工作但不撤销登录;显式 logout 才撤销服务端令牌。
取消覆盖等待响应头与读取正文两个阶段:即使自定义 fetchImpl 忽略 signal,旧请求也会
结束,迟到响应的正文会被取消。这里不会额外增加网络超时或自动重试。
连接 React
初始化完成后,将同一个 Client 实例传给 KitProvider,不要在每次渲染时重新创建实例。
这里的 children 是你的业务页面,使用默认 Client 的 Hooks 在此 Provider 内运行。
自建后端可通过 ChatProvider 直接接入 useChat,
无需创建完整 KitClient,也无需 KitProvider;本页 Client 方法仍访问 Kit Server。
import type { ReactNode } from "react";
import type { KitClient } from "@openagentpack/kit-sdk/providers/kit";
import { KitProvider } from "@openagentpack/kit-sdk/providers/kit/react";
export function KitRoot({ client, children }: { client: KitClient; children: ReactNode }) {
return <KitProvider client={client}>{children}</KitProvider>;
}上传与挂载附件
上传成功只获得文件引用,等 fileStatus 返回 available: true 后再提交。默认 Kit Server
的体验会话支持两种用法:
- 新建会话:将文件引用作为
files传给client.createSession({ agentSlug, files }), 服务端会在返回会话前挂载文件。 - 已有会话:将文件引用作为
attachments传给chat.send(text, { attachments }), 服务端先挂载再发送;发送失败时尝试卸载本次新增的挂载。
可以用 useAttachments 统一上传和扫描,用 useComposer 处理首次发送与已有会话的发送。
见组件交互与后端调用。
文件选择、粘贴、移除和上传状态由调用方组合
Sender 与 Attachments 管理。
使用 await client.downloadFile(fileId, { sessionId }) 下载 Artifact,再由宿主保存 Response
中的字节;本人上传文件可以省略 sessionId。服务端检查文件归属,只允许挂载本人上传。
旧数据库升级时,会从历史会话挂载索引补齐唯一原身份的文件归属;存在跨身份歧义或没有
索引证据的旧文件需要重新上传。已有匿名附件不会自动归到新成员。
fileDownloadUrl() 只生成地址,不附加身份头;成员登录下不能把它直接当作可用的裸下载链接。
Provider 的预签名 URL 不下发给浏览器。
代码演示
上传状态、历史附件和宿主能力
上传受理后通过 fileStatus(fileId) 读取扫描状态;失败、超时或 available=false
时保留草稿并提供重试,服务端仍执行扫描与归属校验。轮询复用
packages/sdk/src/files/attachments.ts,页面通过公开的 useAttachments 管理上传状态。
历史会话的业务接口可返回 message_files,
通过 chat.setMessageFiles(entries) 补充附件气泡;不改变 SessionEvent 合同。
| API | 导入入口 | 用途 |
|---|---|---|
useAttachments(options?) | @openagentpack/kit-sdk/files/hooks | 管理上传、扫描轮询、失败与待发送附件状态 |
resolveApiBaseUrl(queryApi?, config?) | @openagentpack/kit-sdk/config | 按宿主注入、查询参数和运行时配置解析后端地址 |
uploadSizeRejectionReason(size) / uploadTypeRejectionReason(name) | @openagentpack/kit-sdk/protocol | 上传前拒绝原因;最终限制由后端执行 |
sleep(ms, signal?) | @openagentpack/kit-sdk/chat | 示例业务的可取消等待,不包含自动写请求重试策略 |
文件选择、保存、剪贴板和主题能力由应用提供。Web 示例在 apps/web/src/lib/host.ts
通过 resolveHostCapabilities() 读取壳注入与浏览器兜底实现,再用 createArtifactHost()
装配产物预览与保存能力。这些函数属于应用接入层;自建项目按
@openagentpack/kit-sdk/files 的 ArtifactHost 合同提供实现,传给
@openagentpack/kit-sdk/files/hooks 的 useArtifactActions({ host, ... })。
订阅与游标续传
三个场景观察同一订阅入口:首订按 reset → event* → ready 重建,after=1:8 无 reset 续传,
游标失效触发 reset。不要写成 await client.stream(...); await client.sendMessage(...):
这会一直等到连接关闭;需要发送与订阅协同时,用
Controller。
API
createKitClient(options)
| 选项 | 类型 | 作用 |
|---|---|---|
baseUrl | string | Kit Server 地址;所有路径在此地址后拼接 |
headers | () => Record<string, string> | Promise<Record<string, string>> | 每次 HTTP 请求和 SSE 建连时读取身份头 |
fetchImpl | typeof fetch | 注入宿主 fetch、Cookie 策略或测试替身;默认 globalThis.fetch |
成员令牌或 JWT 模式下,headers 可返回 { Authorization: "Bearer <Kit 身份令牌>" };它是终端用户
访问 Kit 的身份,不能填入 BAILIAN_API_KEY 或 Provider 凭据。跨域 Cookie 身份需要按部署
要求注入携带 credentials: "include" 的 fetch,并配置服务端 CORS;Client 不自动开启它。
数据面方法
| 方法 | 用途 |
|---|---|
config() | 读取配置并检查协议主版本 |
auth.login(body) / auth.me() / auth.logout() | 成员登录、恢复当前身份、撤销当前令牌 |
agents() / agent(slug) | 查询当前身份可见的 Agent 目录与详情 |
plaza({ category?, q? }) | 查询广场、精选与热门条目、分类和统计 |
quota() / quotaRequests() | 查询当前身份的月度用量、额度及提额申请历史 |
createQuotaRequest({ requestedCredits, reason? }) | 显式提交提额申请;审批与额度生效需继续查询 |
sessions({ agentSlug?, limit?, pageToken? }) | 查询会话索引,返回 sessions 和 nextPageToken |
createSession({ agentSlug, title?, files? }) | 新建会话,可在创建时挂载已上传附件 |
session(id) / renameSession(id, title) | 查询详情、修改标题 |
sendMessage(id, { text, client_message_id? }) | 提交消息;返回提交结果,不等待完整回答 |
interrupt(id) | 请求停止 Provider 执行 |
toolApprovals(id) / submitToolApproval(id, decision) | 查询待办、提交单项审批决定 |
events(id, { afterId?, limit?, pageToken? }) | 读取事件历史,返回 data 和 next_page_token |
stream(id, options) | 订阅一次 SSE 连接;回调与游标见下方,自动重连由 Controller 负责 |
sessionPlan(id, action) | 获取 archive / delete 的计划与确认令牌 |
archiveSession(id, confirmation) / deleteSession(id, confirmation) | 显式确认后携带 plan_id、confirm_token 执行 |
uploadFile(file) / downloadFile(fileId, { sessionId?, signal? }) | 带当前身份上传 / 下载文件;下载返回 Response |
fileStatus(fileId) | 读取 { file_id, status, available },available=true 后才提交附件 |
usageLimits({ days? }, signal?) | 本地成员日/月 Token 和执行时长限额;非本地成员明确返回 null |
fileDownloadUrl(fileId) | 仅生成代理 URL,不执行鉴权请求 |
直接调用 sendMessage 不会替你建立前端订阅或管理乐观消息。对话页面优先使用 useChat,
以便在订阅就绪后发送、维护输入状态并处理重连。Kit 管理端的 AdminClient、成员用量和
Operation 恢复属于 Console 应用接入层,不作为 SDK 导出;前端调用状态可复用
通用调用状态。管理身份与体验页成员身份独立,接口合同见接口总览。
stream(id, options)
订阅一次 SSE 连接:字节分帧由 Stream 完成,这里在原始帧之上交付 Kit 协议头、
控制帧与有效帧超时。stream 不自动重连,也不维护消息列表。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
after | 续传上次成功消费的传输游标,视为不透明字符串 | string | null | - |
signal | 取消订阅;调用方处理取消产生的异常 | AbortSignal | - |
onEvent | 接收 SDK SessionEvent 累计快照及本次传输游标 | (event, cursor?) => void | - |
onReset | 开始重建事件集合 | () => void | - |
onReady | 回放完成 | ({ sessionId, replayed, cursor? }) => void | - |
onDone | 流正常关闭,不替代业务执行状态 | ({ status, lastEventId }) => void | - |
onPing | 收到保活时间戳 | (t: number) => void | - |
快照与游标
- Kit Server 默认先订阅上游并缓冲实时事件,再回放完整分页历史:首次重建按
reset → event* → ready交付,core 在ready原子切换历史并保留未确认的本地乐观消息。 - 同一
event_id的后续帧可能是更新后的完整快照:交给 Store 更新快照再渲染,不能见重复 ID 就丢弃,也不能重复追加累计文本。 - 业务
event_id与 SSEid是两个字段:after用 SSEid续传,历史 API 的afterId用 业务事件游标。 - 一轮结束以主会话
idle且无requires_action确认;等待审批、子线程结束、单条消息完成或 浏览器断线都不代表 Turn 结束,UI 以归并后的phase/turnRunning为准。 - Controller 对网络错误、意外 EOF、45 秒无有效帧与可重试流错误做带游标退避重连,游标失效走
reset重建;认证、协议冲突等不可重试错误停止恢复。重连只恢复订阅,不重发用户消息与审批。 connection === "connected"只描述浏览器到 Kit 的连接;上游恢复期间中间文本可能暂时变化, 最终以 Provider 完成快照收敛,不承诺逐 token 无损回放。
详细事件合同见仓库 docs/protocol.md。
错误与确认
HTTP 错误响应和流内错误使用 KitError(从 @openagentpack/kit-sdk/protocol 导入),含
code、message、status 和 retryable;网络层也可能抛出原生异常。调用方应捕获错误,
保留草稿并展示失败原因。retryable 不表示可以自动重发消息或审批。
归档、删除必须先取得 plan,向用户展示计划,再经 AlertDialog 显式确认后执行。
不要把 sessionPlan() 与 deleteSession() 串成无人工确认的自动调用。详细状态码与
确认约束见接口总览。
本地成员会话删除由服务端协调停止、用量采集和持久化。错误详情可区分停止、采集、删除与
本地收尾阶段;用量保存失败时会话保留,执行可能已经停止。deletion_uncertain=true
表示远端删除结果待核实,不能当作已经失败而继续发送;提示用户重新获取计划并确认重试。
该保护跨重试和服务重启保留。已发出中断但删除未完成时,也不能凭一次 idle 查询恢复发送;
删除报网络错误后 GET 仍存在不能证明旧 DELETE 已被拒绝。
该机制不新增 ChatProvider 方法,也不要求组件自己保存统计。