Persona.js 完全指南：零框架依赖的 AI 聊天组件，用 VanillaJS 为任何网站添加 Agent 对话能力

概述

Persona.js 是一个开源（MIT）、可主题化的 AI 聊天组件库，完全用 TypeScript 编写，零框架依赖——不要求 React、Vue、Svelte 或任何前端框架。它通过 VanillaJS 渲染，初始包体积经过精心优化，可以嵌入到任何现代网站中。

由 Runtype 团队开发，Persona.js 支持 SSE 流式响应、WebMCP 页面工具、语音 I/O、多模态内容、工具调用可视化、审批门控、Artifact 渲染以及插件系统。它的核心设计理念是「bring your own backend」——你可以对接任何 SSE 兼容的后端。

架构与设计

Persona.js 的代码库分为两个主要包和一个示例应用：

后端无关设计：Persona.js 定义了一套 SSE 协议，任何后端（Vercel AI SDK、OpenAI Agents SDK、LangGraph.js、Anthropic Claude Agent SDK 等）只要符合该协议即可无缝对接。仓库中预置了覆盖 Next.js、Hono、Express、SvelteKit 等多个平台的后端适配器示例。

WebMCP 原生支持：Persona.js 原生支持 WebMCP（Web Model Context Protocol），允许 AI Agent 调用浏览器端的页面工具——例如读取页面 DOM、操作表单、获取选中文本等。这是它与传统 AI 聊天组件最大的差异化能力。

安装方式

方式一：npm 安装（推荐）

npm install @runtypelabs/persona
npm install @runtypelabs/persona-proxy  # 可选
pnpm add @runtypelabs/persona

然后在项目中导入使用：

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

const widget = createWidget({
  target: '#root',
  endpoint: '/api/chat',
});

注意：@runtypelabs/persona 是纯 ESM 包，无 UMD 构建产物。如果需要无打包工具的环境中使用，参考官方仓库的 examples/echo-script-tag 示例。

方式二：本地开发（含热重载）

corepack enable
pnpm install
pnpm dev

启动后代理运行在 http://localhost:43111，演示应用在 http://localhost:5173。需要 Node.js 20+。

核心功能详解

流式聊天（Streaming Chat）

Persona.js 基于 SSE 实现消息流式传输，内置多种流解析器（纯文本、JSON、XML、正则）。支持可配置的流式动画效果——打字机模式、逐字浮现、逐词淡入、擦除效果等。

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

const widget = createWidget({
  target: '#root',
  endpoint: '/api/chat',
  stream: {
    typewriter: true,      // 打字机动画
    wordFade: false,
  }
});

语音输入与输出

利用 Web Speech API 实现语音转文字，可选 Runtype 的 WebSocket 语音服务（支持打断和语音活动检测）。TTS 默认使用浏览器 Web Speech API，也可通过 textToSpeech.createEngine 接入自定义引擎。

多模态内容

支持文本、图片（PNG/JPEG/GIF/WebP/SVG）和文档（PDF/DOCX/TXT/CSV/JSON/Excel）的发送与显示，可配置允许的文件类型、大小限制和预览方式。

工具调用与审批门控

工具调用以可展开的气泡形式展示——名称、状态、参数、结果一目了然。支持紧凑显示、分组、加载动画。审批门控（human-in-the-loop）提供友好的审批界面——用户可以展开技术细节查看后再批准或拒绝。

内置两个本地客户端工具（不依赖后端）：

• ask_user_question：在 UI 中直接向用户提问
• suggest_replies：提供快捷回复建议

Artifact 侧边栏

支持在桌面端以可拖拽的分屏布局、移动端以抽屉形式展示 Markdown 和组件内容。可配置工具栏预设、复制行为和外观。

主题与样式

内置亮色和暗色两种主题。完整的设计 Token 系统覆盖调色板、语义颜色和组件级别样式。支持 CSS 变量覆盖。内置插件提供无障碍、减少动画、高对比度和品牌定制能力。

const widget = createWidget({
  target: '#root',
  theme: {
    preset: 'dark',
    tokens: {
      primary: '#0d9488',
      background: '#1a1a2e',
    }
  }
});

事件流检查器（开发者工具）

内置实时事件捕获面板，支持搜索/过滤、时间戳、可展开的载荷查看和吞吐量诊断。通过 features.showEventStreamToggle 启用，开发和调试阶段非常实用。

插件系统

Persona.js 的插件系统提供 14 个渲染钩子，覆盖启动器、头部、输入框、消息列表、推理气泡、工具调用、审批面板等所有 UI 层面。你可以编写自己的插件来定制任何 UI 层的行为和外观。

常见问题排查

Q：SSE 连接不稳定怎么办？

检查后端适配器是否正确实现了 Persona SSE 协议。建议从 examples/echo-hono 开始调试——这是一个零依赖的回声服务器，不需要 API 密钥即可验证连接。

Q：Script 标签安装后组件不渲染？

确认容器元素在 DOM 中已存在。可以使用 document.addEventListener('DOMContentLoaded', ...) 确保 DOM 就绪后再调用 createWidget()。

Q：如何与已有的 React/Vue 应用集成？

Persona.js 设计为可与任何框架共存。在你的 React 组件中挂载一个