Blade Agent 前端 SDK

@blade-hq/agent-kit 是 Blade Agent 的前端 SDK。本期只在仓库内使用和验证，不包含 npm 发布说明。

子包

SDK 通过两个子包暴露能力：

• @blade-hq/agent-kit/client：纯网络客户端，提供 BladeClient、REST 资源方法和强类型 Socket.IO 连接。它不依赖 React，适合 Vue 项目、Node.js 服务端脚本和其他第三方集成。
• @blade-hq/agent-kit/react：React 绑定，提供 Provider、Hooks、Stores、组件和内部业务视图。Blade Agent 自带的 apps/web 使用这个子包完成全栈 dogfooding。

安装

仓库内应用通过 pnpm workspace 直接引用：

pnpm install

第三方项目可安装发布包，并按需要选择子包入口：

npm install @blade-hq/agent-kit @tanstack/react-query react react-dom sonner

import { BladeClient } from "@blade-hq/agent-kit/client"
import { BladeClientProvider } from "@blade-hq/agent-kit/react"
import "@blade-hq/agent-kit/style.css"

如果使用 @blade-hq/agent-kit/chat、@blade-hq/agent-kit/session 等预制 React UI，应用入口必须导入 @blade-hq/agent-kit/style.css。只使用 /client 或 hooks 自行渲染 UI 时不需要导入这份样式。

ChatView 自定义渲染

ChatView 默认负责会话数据、Socket.IO 流式更新、历史加载、输入框、技能状态和滚动行为。第三方应用可以只改样式，也可以替换局部渲染。

import { ChatView, type ToolRendererProps } from "@blade-hq/agent-kit/chat"

function BashTool({ toolCall }: ToolRendererProps) {
  return <pre>{toolCall.arguments}</pre>
}

<ChatView
  sessionId={sessionId}
  classNames={{
    root: "bg-white text-slate-950",
    messageListContent: "max-w-4xl",
    userMessage: "text-right",
    assistantText: "text-base leading-7",
    chatInputRoot: "border-t",
  }}
  components={{
    EmptyState: () => <div className="py-16 text-center">开始一个新任务</div>,
    SkillStatusBar: ({ sessionId }) => <div>当前会话：{sessionId}</div>,
  }}
  renderers={{
    tool: {
      Bash: BashTool,
    },
  }}
/>

如果需要完全自建聊天界面，可以直接使用 useChat(sessionId) 和 skillsApi / useSkills()。技能选择、@skill mention、会话技能状态等能力仍由现有 skills API 提供；ChatView 的 components.SkillStatusBar 可替换默认技能状态条，用来接入宿主自己的 Anthropic-style skills 入口或展示方式。

认证

SDK 支持 cookie 会话和 Bearer Token 两种模式。

首方 Web 应用通常使用 cookie 会话：

const client = new BladeClient({ baseUrl: "https://blade.example.com" })

这种模式下，REST 请求始终使用 credentials: "include"，不会发送 Authorization；Socket.IO 连接不发送 token，由浏览器自动携带 cookie。

第三方接入使用 Bearer Token。Token 必须在构造 BladeClient 时注入，不能在单次方法调用时临时传入：

const client = new BladeClient({
  baseUrl: "https://blade.example.com",
  token: "sk-blade-xxx",
})

这种模式下，REST 请求仍然携带 cookie，同时额外发送 Authorization: Bearer sk-blade-xxx；Socket.IO 连接会发送 auth: { token: "sk-blade-xxx" }。当 cookie 和 Bearer Token 同时存在时，由后端按现有规则优先识别 Bearer Token，SDK 不主动二选一。

如果 token 是空字符串，SDK 按 cookie 会话模式处理，不会发送空的 Authorization 或 Socket.IO token。buildAuthedUrl() 只会给同一后端域名追加 ?token=...，用于文件预览等无法自定义请求头的场景；外部绝对 URL 不会被追加 Blade token。

类型生成

SDK 的类型来源以后端为准，生成产物提交到仓库，确保本地安装后可以直接 typecheck。

• REST 类型来自 FastAPI 暴露的 /openapi.json，由 openapi-typescript 生成到 src/client/types/rest.ts。
• Socket.IO 事件类型来自后端 socket_schemas 中的 Pydantic schema，生成到 src/client/types/socket-events.ts。
• src/client/types/index.ts 提供业务侧常用类型别名，避免应用代码直接依赖冗长的 OpenAPI 路径类型。

本地更新类型时，需要先启动后端，再执行：

cd web
pnpm -F @blade-hq/agent-kit gen:types

CI 会重新生成类型并校验 web/packages/agent-kit/src/client/types/ 没有 diff，用来阻止后端 schema 与前端 SDK 类型漂移。