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

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

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

initAgentWidget({
  target: '#chat',
  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 { createAgentExperience } from '@runtypelabs/persona';

createAgentExperience(document.getElementById('app'), {
  apiUrl: '/api/chat',
  webmcp: { enabled: true }
});

3. 主题系统与样式隔离

Persona.js 的 UI 渲染通过插件系统的 Shadow DOM 安全样式实现样式隔离，这意味着：

• 不会污染宿主页面的 CSS：你页面的样式表和 Persona 的样式完全隔离
• 自带完整主题系统：通过 config.theme 配置自定义颜色、圆角、字体

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

initAgentWidget({
  target: '#chat-container',
  config: {
    apiUrl: '/api/chat',
    theme: {
      mode: 'dark',
      accent: '#6366f1'
    }
  }
});

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

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

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

initAgentWidget({
  target: document.body,
  config: {
    apiUrl: '/api/chat',
    features: {
      toolCalls: true,
      approvalGates: true,
      artifacts: true
    }
  }
});

当 AI 准备执行高风险操作（如写入数据库、发送邮件）时，审批门会弹出确认对话框，用户手动批准后才会执行。

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

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

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

initAgentWidget({
  target: document.body,
  config: {
    apiUrl: '/api/chat',
    features: {
      voice: {
        input: true,
        output: true
      }
    }
  }
});

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

注意事项

• WebMCP 依赖浏览器支持：WebMCP 目前需要最新版 Chrome（120+）或合适的 polyfill。在旧版浏览器中，WebMCP 工具会自动降级，但不影响基础聊天功能。
• SSE 后端必须运行：Persona.js 的核心通信依赖 SSE 端点。如果你的 AI 后端不支持流式输出，可以使用 Hono 或 Express 搭建一个简单的 SSE 代理。
• 插件系统与样式隔离：Persona.js 的插件系统提供了 Shadow DOM 安全样式辅助工具，确保自定义 UI 不污染全局样式。你也可以通过 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