指南
页面定制、鉴权、流式与重连、artifact 与部署
定制自己的页面
需要定制应用时,可参考仓库内的 apps/web,按需复用 SDK 功能入口、React hooks 和 chat-ui 组件。
数据接入见 SDK 与 Kit 数据接入,组件用法见组件总览。
在 Kit 仓库根目录执行以下命令,可将组件及其声明依赖复制到已有项目:
pnpm kit:add chat --dir /path/to/my-agent-app目标项目需要自行配置 React、Tailwind 与 Kit 依赖;组件复制命令不安装 npm 依赖。
鉴权与 Identity
- 数据面:
IdentityProvider解析subjectId(v1:anon cookie / JWT);会话读写按 subject 过滤, 越权返回404(不泄露存在性)。 - 控制面:v1
ADMIN_TOKENbearer;RBAC/企业 IdP(OIDC/企业 SSO)为二期能力。
流式与重连
- 客户端用
fetch+ReadableStream读 SSE(不用 EventSource:要带 Authorization、要可控重连)。 - 重连:指数退避(500ms×2^n,上限 15s,±20% jitter,8 次),带最后
after续传;404全量重建;401/403不重连;ping 超时(45s 无帧)判定静默断流。 - 去重按
event_id幂等;无 id 的帧用稳定合成 id(仅本地)。
Artifact 与文件
下载一律 GET /api/kit/files/:fileId/download(server 代理,屏蔽过期预签名 URL);
体验页使用 <a download> 保存文件;嵌入其他宿主时可通过 saveFile 注入自定义保存能力。
部署
- 本地:
pnpm dev;生产:pnpm build后node apps/server/dist/bin.js+ 静态托管apps/web/dist、apps/console/dist。 - 反代场景:server 的
/api/config返回空apiBaseUrl(同源语义);跨域直连用KIT_PUBLIC_BASE_URL+KIT_CORS_ORIGINS白名单。