Browser API 参考

Browser Headless 接入

分发边界

当前未发布 npm。以下 TypeScript 示例适用于仓库 workspace、本地链接或宿主自行构建的源码集成，不表示公共 npm 安装命令可用。

最小 Controller

import { createAgentController } from '@patchbridge-agent/agent';

const controller = createAgentController({ endpoint: '/ai' });
const unsubscribe = controller.subscribe(state => renderAgent(state));

await controller.initialize();
await controller.sendMessage('查询当前告警设备');

unsubscribe();
controller.dispose();

subscribe 注册后立即推送当前不可变快照。View 只调用 Controller 意图，不直接调用 Runtime、ModelClient、ToolClient 或 ConversationClient。

内置 HTTP Client 在边界校验响应形状：会话对象的 conversationId/revision/status 与时间戳字段、详情响应的 context.messages/modelState 必须符合契约类型，否则以明确的 invalid state 错误失败，不进入 Controller 状态与渲染。Widget 渲染会话列表时对所有来自响应的字符串（含 conversationId）做 HTML 实体转义，伪造 id 无法逃逸属性插值。

Controller 公共意图

当前接口包括：

getState()/subscribe()；
initialize()/refreshConversations()/loadConversation()；
startNewConversation()/deleteConversation()；
sendMessage(text, images)；
approveTool()/rejectTool()/abort()/dispose()；
getToolRegistry()/getToolInspectionSource()/getCallTraceSource()；
registerTool()。

Navigation 和 Run 使用独立取消与 generation；旧请求、旧 Execution 和迟到保存结果不能覆盖新状态。

createAgentController 选项

选项	作用
`endpoint`	必填，Agent API 根路径
`engine`	完整替换默认 AgentEngine；不能同时提供 model/runtime
`transport`	Model/Tool/Conversation 默认 Client 共用的 HttpTransport
`model`	替换默认 HttpModel；不能与 engine 同时提供
`runtime.limits.maxModelCalls`	默认 16，整轮模型调用次数
`runtime.limits.maxToolCalls`	默认 32，整轮接受的 Tool Call 总数
`runtime.limits.maxDurationMs`	默认 300000，包含模型、Tool 与确认等待的整轮 Deadline
`runtime.limits.maxModelOutputCharacters`	默认 100000，单次模型聚合的正文、思考和 Tool 参数字符总数
`runtime.limits.maxToolResultCharacters`	默认 100000，单个 Tool 结果回填上限
`runtime.now`	单调毫秒时钟，同时用于 Deadline 边界和性能指标；生产自定义实现不得回退或返回非有限值
`runtime.hooks`	只读生命周期观察者
`runtime.onHookError`	终态 Hook 异常的独立 diagnostics 回调；省略时异常路径写入 `console.error`，不改判已经选定的终态
`runtime.modelInterceptors`	模型调用拦截器
`runtime.toolInterceptors`	Tool 调用拦截器
`toolClient`	替换后端 Tool Client
`toolRegistry`	完整替换 Registry；不能与 toolClient 同时提供
`conversationClient`	替换会话 Client
`storageKey`	上次会话 localStorage key；默认 `patchbridge-agent:last-conversation`
`callTrace`	调用轨迹采集配置；缺省不采集（不创建采集 Hook、不访问 localStorage）。`{ mode: 'memory' }` 仅当前页内存；`{ mode: 'persistent' }` 终态写入 localStorage，可用 `storageKey` 指定键前缀（默认 `patchbridge-agent:call-trace`）

默认 storageKey 不包含用户身份。共享浏览器环境应由宿主提供按应用和用户隔离的 key；这只是 UX/隐私隔离，服务端 owner 校验仍是安全边界。

createAgentController() 中的 runtime.limits 是部分覆盖，只需写需要调整的字段：

const controller = createAgentController({
  endpoint: '/ai',
  runtime: {
    limits: {maxModelCalls: 8, maxDurationMs: 120_000},
  },
});

直接 new DefaultAgentRuntime(model, options) 不是部分覆盖入口； options.limits 必须同时提供上表五项安全正整数，且 maxDurationMs 不得超过 2147483647。这一差异用来防止高级宿主直接组装 Runtime 时无意遗漏关键资源边界。

HttpTransport

import type { HttpTransport } from '@patchbridge-agent/agent';

const transport: HttpTransport = {
  async request(url, init) {
    const headers = new Headers(init.headers);
    headers.set('X-CSRF-TOKEN', readCsrfToken());
    return fetch(url, {
      ...init,
      headers,
      credentials: 'same-origin',
    });
  },
};

const controller = createAgentController({ endpoint: '/ai', transport });

默认 FetchHttpTransport 使用同源 fetch，并在未指定时设置 credentials='same-origin'。GET 网络失败自动重试一次；非幂等请求不自动重试。模型流只在尚未交付任何框架事件的网络失败时重连一次；一旦交付事件就不重试。

默认 Widget

元素、属性与事件

主元素：<patchbridge-agent>。

类型	名称	当前行为
HTML 属性	`endpoint`	默认 /ai；运行中变化会重建 Controller
HTML 属性	`title`	默认“AI 助手”；运行中变化只按当前状态快照重绘视图，不重建 Controller
HTML 属性	`login-url`	登录跳转，默认 /login；运行中变化只重绘视图，不重建 Controller
HTML 属性	`theme`	默认主题；none 只保留结构/交互基础样式
JS 属性	`httpTransport`	注入 Transport；变化重建 Controller
JS 属性	`runtimeOptions`	配置默认 Runtime；变化重建 Controller
只读 getter	`toolRegistry`	当前 Controller 的唯一 Registry，未启动时为 null
方法	`registerTool(tool)`	注册页面 Tool并返回 Registration

属性变化的影响范围按依赖等级区分：endpoint 改变基础设施依赖，整体重建 Controller；title 与 login-url 只影响视图，用当前 Controller 的只读快照重绘。元素未连接期间的变化不保存快照，重连后的首次订阅按新属性完整绘制。

每次 Controller 装配或重建后派发 patchbridge-agent-ready：

bubbles=true；
composed=true；
detail.toolRegistry；
detail.toolInspectionSource；
detail.callTraceSource。

每个 Widget 实例装配一个主 Controller；Inspector 和 Call Trace 只消费该 Controller 的只读 Source，不创建第二份 Registry 或领域状态。

runtimeOptions 是 JavaScript 属性，不是 HTML 字符串属性；其 limits 与 Headless 工厂一样支持部分覆盖：

const widget = document.querySelector('patchbridge-agent');
widget.runtimeOptions = {
  limits: {maxModelCalls: 8, maxDurationMs: 120_000},
};

运行中替换该属性会取消旧 Execution 并完整重建 Controller；宿主必须按新的 patchbridge-agent-ready 事件重新挂载页面 Tool 和只读调试视图。

四个 Starter Bundle

{basePath} 默认是 /ai：

HTTP 路径	classpath 资源
`{basePath}/assets/patchbridge-agent.js`	`META-INF/patchbridge-agent/patchbridge-agent.js`
`{basePath}/assets/patchbridge-agent-webmcp-adapter.js`	`META-INF/patchbridge-agent/patchbridge-agent-webmcp-adapter.js`
`{basePath}/assets/patchbridge-agent-tool-inspector.js`	`META-INF/patchbridge-agent/patchbridge-agent-tool-inspector.js`
`{basePath}/assets/patchbridge-agent-call-trace.js`	`META-INF/patchbridge-agent/patchbridge-agent-call-trace.js`

样式扩展

Widget 提供三层稳定入口：

--patchbridge-agent-* CSS Variables 调整颜色、字体、间距、尺寸和圆角；
::part() 覆盖 panel、header、message、composer、input、send-button、reasoning、max-tokens-notice 等语义节点；
theme="none" 移除参考视觉主题。

不要依赖 Shadow DOM 内部 class。需要改变 DOM 或交互结构时，使用 Headless Controller 自建 View。

FilesExpand file tree

browser-api.md

Latest commit

History