给任意网站嵌入 AI 对话界面？Persona.js 用 VanillaJS 实现轻量方案

最简启动代码，创建一个带流式响应的 AI 对话窗口：

import { initAgentWidget, DEFAULT_WIDGET_CONFIG } from '@runtypelabs/persona';

initAgentWidget({
  target: '#chat',
  config: {
    ...DEFAULT_WIDGET_CONFIG,
    apiUrl: 'https://your-ai-backend.com/chat'
  }
});

这段代码在你的页面上创建一个浮动的 AI 聊天窗口，支持流式输出（SSE）、工具调用展示和 Markdown 渲染——不需要 React、Vue 或任何框架。

核心功能拆解

1. 流式 SSE 协议——后端无关的通信层

Persona.js 使用标准 Server-Sent Events 协议与后端通信。这意味着你可以用任意语言（Python、Go、Node.js）或框架（FastAPI、Hono、Express）编写 AI 后端。

一个兼容的 Hono 后端示例：

import { Hono } from 'hono';
import { stream } from 'hono/streaming';

const app = new Hono();

app.post('/chat', async (c) => {
  const { messages } = await c.req.json();
  
  return stream(c, async (stream) => {
    // 模拟 AI 流式响应
    for (const chunk of ['你好', '！', '我是', 'AI', '助手']) {
      await stream.write(`data: ${JSON.stringify({ content: chunk })}\n\n`);
    }
    await stream.write(`data: [DONE]\n\n`);
  });
});

export default app;

2. WebMCP 原生支持——让 AI 读取页面上下文

Persona.js 内置了 WebMCP（Web Machine Communication Protocol）支持，这是 Persona 区别于其他 Agent UI 库的最大亮点。

WebMCP 允许 AI 对话直接读取当前页面注册的工具，实现「页面即上下文」的能力。启用方式极其简单：

import { initAgentWidget, DEFAULT_WIDGET_CONFIG } from '@runtypelabs/persona';

initAgentWidget({
  target: '#chat',
  config: {
    ...DEFAULT_WIDGET_CONFIG,
    apiUrl: '/api/chat',
    webmcp: { enabled: true }
  }
});

WebMCP 启用后，Persona 会自动捕获页面上通过 document.modelContext 注册的工具，在每次请求时发送给 AI 后端，执行返回的 webmcp: 调用并返回结果。

3. 主题系统与样式隔离

Persona.js 通过 useShadowDom 选项实现样式隔离，这意味着：

• 不会污染宿主页面的 CSS：你页面的样式表和 Persona 的样式完全隔离
• 自带完整主题系统：通过 theme 配置和 colorScheme 控制外观

import { initAgentWidget, DEFAULT_WIDGET_CONFIG } from '@runtypelabs/persona';

initAgentWidget({
  target: '#chat-container',
  useShadowDom: true,
  config: {
    ...DEFAULT_WIDGET_CONFIG,
    apiUrl: '/api/chat',
    colorScheme: 'dark',
    theme: {
      semantic: { colors: { accent: '#6366f1' } }
    }
  }
});

4. 工具调用可视化与审批门

Agent 执行过程中的工具调用不再是黑盒。Persona.js 内置了工具调用展示功能，以及可选的审批门（Approval Gates）：

import { initAgentWidget, DEFAULT_WIDGET_CONFIG } from '@runtypelabs/persona';

initAgentWidget({
  target: document.body,
  useShadowDom: true,
  config: {
    ...DEFAULT_WIDGET_CONFIG,
    apiUrl: '/api/chat',
    // 审批门：要求特定工具需用户批准
    approval: {
      require: true,  // 所有工具调用都需要用户确认
      timeout: 30000  // 30秒后超时自动拒绝
    }
  }
});

5. 语音 I/O 与多模态内容

支持语音输入输出和图片、代码工件等多媒体内容的渲染。对于需要无障碍访问或移动端优先的场景，这是一个加分项。

横向对比：主流 Agent UI 库一览

注意事项

• WebMCP 依赖浏览器支持：WebMCP 目前需要最新版 Chrome（120+）或合适的 polyfill。在旧版浏览器中，WebMCP 工具会自动降级，但不影响基础聊天功能。
• SSE 后端必须运行：Persona.js 的核心通信依赖 SSE 端点。如果你的 AI 后端不支持流式输出，可以使用 Hono 或 Express 搭建一个简单的 SSE 代理。
• useShadowDom 启用样式隔离：Persona.js 支持通过 useShadowDom: true 启用 Shadow DOM 样式隔离，确保组件样式不污染宿主页面 CSS。你也可以通过 CSS 自定义属性（CSS Custom Properties）覆盖默认主题。
• npm 包名注意：安装时使用 @runtypelabs/persona，而非 persona——后者是另一个不相关的 npm 包。
• 社区尚在早期：26⭐ 说明项目仍处于早期阶段，API 可能在未来版本中有变化。建议锁定版本号。

结语

Persona.js 填补了一个被忽视的空白——不依赖 React/Vue、不需要重构现有项目、用最轻量的方式给网站加上 AI 对话界面。如果你的团队需要在多个技术栈的产品中统一 AI 交互体验，或者你只是一个想快速给个人项目加个 AI 助手的独立开发者，它都值得一试。

• GitHub：runtypelabs/persona（MIT 许可）
• 在线演示：persona-chat.dev
• npm：npm install @runtypelabs/persona