widget (Chatrium)

Chatrium小部件

Chatrium Logo

您的AI对话空间

一个现代的、可定制的聊天小部件，支持语音输入和MCP（模型通信协议）工具集成，用于与人工智能助手交互。

奥克伍德 是一个人工智能对话工具家族。这个包裹(@chatrium/widget)提供核心React聊天小部件组件。

特性

• 语音输入：免提信息的语音转文本功能
• MCP集成：内置对模型通信协议工具和资源的支持
• MCP资源：全面支持上下文数据（静态）和实时数据（动态）资源
• 可定制的用户界面：多种定位选项和组件可见性设置
• 多语言支持：支持自定义区域设置的本地化
• 工具集成：内置具有DOM操作功能的审阅表单工具
• 上下文管理：自动将资源加载到AI上下文中，以增强理解
• 响应式设计：适用于台式机和移动设备

安装

npm install @chatrium/widget

从源头构建

要从源代码构建小部件以进行自定义或贡献，请执行以下操作：

git clone https://github.com/chatrium/widget.git
cd widget
npm install
npm run build

编译后的资产将在 dist/ 目录，可以集成到您的项目中。

统一应用架构

与需要单独后端服务的传统人工智能集成不同，此小部件作为 独立解决方案 哪里：

• MCP服务器直接在浏览器中运行
• 工具处理程序在应用程序上下文中执行
• 聊天客户端和语音界面共享同一运行时
• 所有组件通过内部协议进行通信

该架构提供：

• 零外部依赖：不需要后端基础设施
• 无缝DOM集成：工具可以直接操纵页面元素
• 实时执行：无网络延迟的即时反馈
• 简化部署：单个JavaScript包集成

这使得它成为一个非常强大但简单的解决方案，可以在任何web应用程序中以最少的集成工作自动化工作流。

用法

快速开始

JavaScript（创建React应用程序）

npm install @chatrium/widget

// src/App.js
import { ChatWidget, useMCPServer } from "@chatrium/widget";
import { TOOLS } from "./mcp_tools";

function App() {
  useMCPServer(TOOLS);
  
  return (
    

      
    

  );
}

export default App;

TypeScript（创建React应用程序）

npm install @chatrium/widget

// src/App.tsx
import React from 'react';
import { ChatWidget, useMCPServer } from "@chatrium/widget";
import { TOOLS } from "./mcp_tools";

function App(): JSX.Element {
  useMCPServer(TOOLS);
  
  return (
    

      
    

  );
}

export default App;

工具定义（TypeScript）：

// src/mcp_tools.ts
interface Tool {
  function: {
    name: string;
    description: string;
    parameters: {
      type: string;
      properties: Record;
      required?: string[];
    };
  };
  handler: (args: any) => Promise | any;
}

export const TOOLS: Tool[] = [
  {
    function: {
      name: "exampleTool",
      description: "Example tool description",
      parameters: {
        type: "object",
        properties: {
          param1: { 
            type: "string", 
            description: "Parameter description" 
          }
        },
        required: ["param1"]
      }
    },
    handler: async (args: { param1: string }) => {
      // Tool implementation
      return { success: true, result: args.param1 };
    }
  }
];

Vite（JavaScript+JSX）

npm install @chatrium/widget

// src/App.jsx
import { ChatWidget, useMCPServer } from "@chatrium/widget";
import { TOOLS } from "./mcp_tools";

function App() {
  useMCPServer(TOOLS);
  
  return (
    
  );
}

export default App;

环境变量（.env）：

VITE_OPENAI_API_KEY=your-api-key
VITE_OPENAI_BASE_URL=http://127.0.0.1:1234/v1

快速（TypeScript+TSX）

npm install @chatrium/widget

// src/App.tsx
import { ChatWidget, useMCPServer } from "@chatrium/widget";
import { TOOLS } from "./mcp_tools";

function App(): JSX.Element {
  useMCPServer(TOOLS);
  
  return (
    
  );
}

export default App;

Vite配置说明： 该小部件与Vite一起开箱即用。不需要额外的配置。

Next.js（应用路由器-TypeScript）

npm install @chatrium/widget

// app/components/ChatWidgetWrapper.tsx
'use client';

import { ChatWidget, useMCPServer } from "@chatrium/widget";
import { TOOLS } from "./mcp_tools";

export default function ChatWidgetWrapper() {
  useMCPServer(TOOLS);
  
  return (
    
  );
}

// app/page.tsx
import ChatWidgetWrapper from './components/ChatWidgetWrapper';

export default function Home() {
  return (
    
      
My App

      
    
  );
}

重要提示： 小部件必须包装在客户端组件中 'use client' 指令，因为它使用浏览器API（语音识别、事件监听器）。

环境变量（.env.local）：

NEXT_PUBLIC_OPENAI_API_KEY=your-api-key
NEXT_PUBLIC_OPENAI_BASE_URL=http://127.0.0.1:1234/v1

Next.js（页面路由器-TypeScript）

// pages/_app.tsx
import type { AppProps } from 'next/app';
import '../styles/globals.css';

export default function App({ Component, pageProps }: AppProps) {
  return ;
}

// pages/index.tsx
import dynamic from 'next/dynamic';

const ChatWidgetWrapper = dynamic(
  () => import('../components/ChatWidgetWrapper'),
  { ssr: false }
);

export default function Home() {
  return (
    
      
My App

      
    
  );
}

注： 使用 dynamic 进口与 ssr: false 以防止小部件在服务器端呈现，因为它依赖于浏览器特定的API。

基本实施

import {ChatWidget, useMCPServer} from "@chatrium/widget";
import {TOOLS} from "./mcp_tools";

function App() {
  useMCPServer(TOOLS);
  
  return (
    

      
    

  );
}

自定义配置

外部MCP服务器（WSS和HTTPS SSE）

外部MCP服务器支持 工具和资源.通过WebSocket或服务器发送事件连接到远程服务器：

来自外部服务器的工具和资源：

• 工具 以限定名称公开： files.readFile, audit.logEvent
• 资源 使用合格的URI公开： files_resource://path/to/file, audit_resource://logs
• AI可以无缝地从外部服务器访问工具和资源

连接说明：

• 对于WebSocket(type: "ws")，浏览器不支持自定义标头；通过查询参数或子协议传递令牌。
• 对于SSE(type: "http-stream")，POST请求支持标头（也接受 "sse" 为了向后兼容性）。
• 环境变量替换格式： ${VAR_NAME} 或 ${VAR_NAME:-default_value}
• 使用 allowedTools 将特定工具列入白名单（优先于 blockedTools)
• 使用 blockedTools 将特定工具列入黑名单（允许所有其他工具）

规格符合性：

• 支持两种符合规范的方法(resources/list, resources/read)以及传统方法(mcp.resources.list, mcp.resources.read)
• 如果不支持规范方法，则自动回退到旧方法
• 来自外部服务器的资源根据其 cachePolicy 注释（如果提供）

工具筛选

控制AI可用的工具：

• allowedTools：如果提供，则只有这些工具可用（优先）
• blockedTools：如果提供时没有允许的工具，则除这些工具外的所有工具都将可用
• 工具名称必须使用限定格式： "serverId.toolName" 对于外部服务器
• 通过注册的内部工具 useMCPServer 直接使用他们的名字

向后兼容

老人 externalServers 仍然支持数组格式，但已弃用：

// Deprecated format (still works)

迁移： 替换 externalServers 阵列与 mcpServers 对象格式，以更好地符合MCP标准。

MCP工具开发

工具定义结构

MCP工具遵循OpenAI的函数调用规范，具有增强的web自动化功能。每个工具包括：

1. 函数架构：使用JSON模式描述工具的界面
2. 处理程序实现：调用时执行的JavaScript函数

export const TOOLS = [
  {
    function: {
      name: "toolName",
      description: "Clear description of what the tool does",
      parameters: {
        type: "object",
        properties: {
          // Parameter definitions with validation
        },
        required: ["requiredParameters"]
      }
    },
    handler: async (args) => {
      // Implementation logic with full DOM access
      // Can interact with page elements, APIs, etc.
    }
  }
];

MCP工具的主要特征

• 类型安全参数：基于JSON模式的自动验证
• 完全DOM访问：处理程序可以直接操纵页面元素
• 异步执行：支持异步操作
• 错误处理：自动向AI报告错误
• 情境感知：访问当前页面状态和用户交互

示例：查看表单自动化工具

export const REVIEW_TOOLS = [
  {
    function: {
      name: "fillReviewForm",
      description: "Fills product review form with provided details",
      parameters: {
        type: "object",
        properties: {
          name: { type: "string", description: "Reviewer's name" },
          stars: { 
            type: "integer", 
            minimum: 1, 
            maximum: 5,
            description: "Rating from 1-5 stars"
          },
          review: { type: "string", description: "Review text content" }
        },
        required: ["name", "stars"]
      }
    },
    handler: fillReviewForm
  },
  {
    function: {
      name: "clickSubmitReview",
      description: "Clicks review form submit button",
      parameters: { type: "object", properties: {} }
    },
    handler: clickSubmitReview
  },
  {
    function: {
      name: "clearReviewForm",
      description: "Resets all fields in the review form",
      parameters: { type: "object", properties: {} }
    },
    handler: clearReviewForm
  }
];

实施工具处理程序

处理程序函数接收经过验证的参数，并可以与DOM交互：

function fillReviewForm({ name, stars, review }) {
  document.querySelector('#review-name').value = name;
  document.querySelector(`#star-rating [data-stars="${stars}"]`).click();
  if (review) document.querySelector('#review-text').value = review;
}

function clickSubmitReview() {
  document.querySelector('#review-submit').click();
}

MCP资源开发

什么是MCP资源？

MCP资源 只读数据端点 为AI助手提供上下文。与执行操作的工具不同，资源提供的信息有助于人工智能了解应用程序的状态、配置和可用数据。

资源类型

静态资源 -不经常变化的上下文数据：

• 产品目录
• 配置设置
• 常见问题解答/帮助内容
• 参考数据

动态资源 -根据应用程序状态更新的实时数据：

• 表单字段值
• 用户会话信息
• 性能统计
• 页面快照

资源定义结构

export const RESOURCES = [
  {
    uri: "resource://example/product-catalog",
    name: "product-catalog",              // ID/slug (machine-readable)
    title: "Product Catalog",             // Display name (human-readable)
    description: "List of available products with prices and availability",
    mimeType: "application/json",
    handler: async () => {
      // Return resource data
      return {
        products: [
          { id: 1, name: "Smart Watch", price: 299.99, inStock: true },
          { id: 2, name: "Wireless Headphones", price: 199.99, inStock: true }
        ]
      };
    },
    annotations: {
      audience: ["user", "assistant"],    // Who can use this resource
      priority: 0.8,                       // Importance (0.0-1.0)
      cachePolicy: "static",               // "static" or "dynamic"
      lastModified: "2025-01-15T10:00:00Z" // ISO 8601 timestamp
    }
  }
];

关键资源字段

• uri （必需）：资源的唯一标识符（符合RFC3986）
• name （必填）：机器可读ID/slug
• title （可选）：人类可读的显示名称
• description （可选）：AI理解的详细说明
• mimeType （可选）：内容类型（默认：“application/json”）
• size （可选）：大小（以字节为单位）
• handler （必需）：返回资源数据的异步函数
• annotations （可选）：资源行为的元数据

注释说明

annotations: {
  // Who should see/use this resource
  audience: ["user", "assistant"],  // or just ["assistant"] for AI-only data
  
  // How important is this resource (0.0 = optional, 1.0 = required)
  priority: 0.8,
  
  // How should this resource be cached?
  cachePolicy: "static",   // "static" = load once into AI context
                          // "dynamic" = read on-demand when needed
  
  // When was this resource last updated?
  lastModified: "2025-01-15T10:00:00Z"  // ISO 8601 format
}

资源如何与人工智能协同工作

静态资源：

• 初始化时预加载到AI的系统提示中
• 提供即时上下文，无需调用工具
• 最适合在对话过程中保持不变的参考数据
• 限制大小以防止提示溢出（每个资源5KB，总共20KB）

动态资源：

• 暴露为 readMCPResource 工具
• AI可以在需要时请求当前数据
• 最适合经常变化的州
• 始终返回新数据

按URI模式划分的静态资源（启发式）

当资源由外部MCP服务器提供并且不包括 annotations.cachePolicy，小部件仅将URI包含内置模式的那些视为静态(configuration, catalog, faq, config, settings等等）。要将其他资源标记为静态（例如用户指令文档），请传递 staticResourcePatterns prop：URI子字符串数组。当聊天打开时，URI包含这些子字符串之一（不区分大小写）的任何资源都将被加载到系统提示符中一次。

示例：资源 mcp://mik-api/instruction，set staticResourcePatterns={['instruction']} 因此其内容在启动时加载到上下文中：

示例：完整资源集

// src/mcp_resources.js
export const RESOURCES = [
  // Static: Product catalog
  {
    uri: "resource://app/products",
    name: "products",
    title: "Product Catalog",
    description: "Available products with pricing",
    mimeType: "application/json",
    handler: async () => ({
      products: [
        { id: 1, name: "Item A", price: 99.99 },
        { id: 2, name: "Item B", price: 149.99 }
      ]
    }),
    annotations: {
      audience: ["assistant"],
      priority: 0.9,
      cachePolicy: "static",
      lastModified: "2025-01-15T10:00:00Z"
    }
  },
  
  // Dynamic: Current form state
  {
    uri: "resource://app/form-state",
    name: "form-state",
    title: "Current Form State",
    description: "Real-time form field values and validation",
    mimeType: "application/json",
    handler: async () => {
      const nameInput = document.querySelector('#name');
      const emailInput = document.querySelector('#email');
      return {
        fields: {
          name: nameInput?.value || "",
          email: emailInput?.value || ""
        },
        isValid: nameInput?.value && emailInput?.value
      };
    },
    annotations: {
      audience: ["assistant"],
      priority: 0.95,
      cachePolicy: "dynamic",
      lastModified: new Date().toISOString()  // Always current
    }
  }
];

利用资源

import { ChatWidget, useMCPServer } from "@chatrium/widget";
import { TOOLS } from "./mcp_tools";
import { RESOURCES } from "./mcp_resources";

function App() {
  // Register both tools and resources
  useMCPServer(TOOLS, RESOURCES);
  
  return (
    
  );
}

MCP资源的好处

1. 增强的AI上下文：AI可以立即访问您的应用程序的数据
2. 减少快速工程：无需在提示中手动描述数据
3. 实时数据访问：动态资源始终返回当前状态
4. 标准化协议：遵循MCP 2025-06-18规范
5. 性能优化：自动大小限制和缓存策略

内部MCP服务器集成

使用您的工具和资源定义初始化MCP服务器：

// Tools only
useMCPServer(TOOLS);

// Tools and resources
useMCPServer(TOOLS, RESOURCES);

// Resources only
useMCPServer([], RESOURCES);

API配置

LLM配置（v2.0中的重大更改）

新格式（v2.0+）： 小部件现在使用 llmConfigs 阵列用于LLM配置，替换单个道具。这使得多个LLM配置能够自动回退。

llmConfigs={[
  {
    modelName: "gpt-4o-mini",        // AI model name
    baseUrl: "https://api.openai.com/v1", // API endpoint URL
    apiKey: "your-api-key",          // Authentication key
    temperature: 0.5,                // Generation temperature (0.0-2.0)
    maxContextSize: 32000,           // Maximum context tokens
    maxToolLoops: 5,                 // Max tool execution cycles
    systemPromptAddition: null,      // Optional system prompt addition
    validationOptions: null,         // Response validation options
    toolsMode: "api"                 // 'api' (standard) or 'prompt' (legacy)
  }
]}

LLM配置属性

中的每个配置对象 llmConfigs 阵列支持：

• 模型名称 （字符串）：AI模型标识符（默认值：“gpt-4o-mini”）
• baseUrl （字符串）：API端点URL（默认值：'http://127.0.0.1:1234/v1')
• apiKey （string|null）：API访问的身份验证密钥
• 温度 （数字）：发电温度0.0-2.0（默认值：0.5）
• maxContextSize （number）：令牌中的最大上下文大小（默认值：32000）
• maxToolLoops （数字）：最大刀具执行周期（默认值：5）
• SystemPromptEdition （string | null）：其他系统提示文本
• 验证选项 （对象|null）：响应验证配置
• 工具模式 （string）：工具集成模式（默认：“api”）

- 'api'：标准模式-通过OpenAI API传递的工具 tools 仅限参数（建议用于GPT-4、Claude和其他现代型号） - 'prompt'：传统模式-通过系统提示中列出的API参数AND传递的工具（与需要提示中描述的工具的旧/自定义模型兼容）

自动回退

当提供多种配置时，如果发生错误，小部件会自动按顺序尝试每种配置：

llmConfigs={[
  {
    modelName: "gpt-4o",
    baseUrl: "https://primary-api.com/v1",
    apiKey: "primary-key"
  },
  {
    modelName: "gpt-3.5-turbo",
    baseUrl: "https://backup-api.com/v1",
    apiKey: "backup-key"
  }
]}

• 如果第一个配置失败，则自动切换到第二个配置
• 请求成功后，重置回第一个（主）配置
• 仅当所有配置都失败时显示错误
• 将回退消息记录到控制台进行调试

迁移指南（v1.x→ v2.0)

旧格式（v1.x-已弃用）：

新格式（v2.0+）：

迁移步骤：

1. 将所有与法学硕士相关的道具包裹在 llmConfigs 数组
2. 将以下道具移动到config对象中：

- modelName, baseUrl, apiKey - temperature, maxContextSize, maxToolLoops - systemPromptAddition, validationOptions, toolsMode

1. 从小部件级别删除单个道具
2. 可选地向阵列添加回退配置

系统提示

该小部件使用本地化的系统提示，指导人工智能如何正确使用工具。提示因 toolsMode:

标准模式(toolsMode: 'api'):

You are a browser assistant. You can perform actions on web pages using strictly defined tools.

Rules:
1. All actions are performed ONLY through tool calls.
2. If there is not enough information - clarify with the user.
3. Respond in [language based on locale].
4. When requesting a tool, use standard tool_calls only.

传统模式(toolsMode: 'prompt'):

You are a browser assistant. You can perform actions on web pages using strictly defined tools.

Available tools:
[List of available tools with descriptions]

Rules:
1. All actions are performed ONLY through tool calls.
2. If there is not enough information - clarify with the user.
3. Respond in [language based on locale].
4. When requesting a tool, use format: [{"name": "tool_name", "arguments": {...}}]

系统提示会自动本地化 en, ru，以及 zh 区域设置，如果需要，可以进行自定义

小部件配置

定位

可用职位：

• top-left
• top-right
• bottom-left
• bottom-right （默认）

零部件可见性

• showComponents：控制哪些组件可见

- 'both' （默认）：同时显示聊天和语音按钮 - 'chat'：仅显示聊天按钮 - 'voice'：仅显示语音按钮

小部件尺寸

• expandedWidth：扩展聊天小部件的宽度（默认值：350）

- 接受：数字（像素）、“350px”、“50%”（转换为50vw视口宽度）或“50vw”

• expandedHeight：扩展聊天小部件的高度（默认值：400）

- 接受：数字（像素）、“400px”、“80%”（转换为80vh视口高度）或“80vh”

上下文管理

上下文大小是根据LLM配置配置的 llmConfigs 阵列（请参阅上面的API配置部分）：

• 当谈话超过 maxContextSize 限制，最旧的消息将被自动排除在发送到LLM之外
• 系统消息（第一条消息）始终保留
• 排除的消息在UI中仍然可见，但会变暗并标记为警告图标
• 将鼠标悬停在排除的消息上会显示一个工具提示，说明它们不会被发送到AI助手
• 令牌计数：如果已安装，则使用精确的tiktoken（cl100k_base），否则将回退到近似计数（每个令牌约3.5个字符）
• 备注：为了准确计数令牌，请安装 js-tiktoken 作为可选依赖关系： npm install js-tiktoken （~21MB）。如果没有它，小部件将使用近似计数，大小约为20MB。

工具执行控制

工具执行限制是根据LLM配置配置的 llmConfigs 阵列（请参阅上面的API配置部分）：

• maxToolLoops 控制人工智能助手在一次对话中调用工具的次数
• 防止无限循环和过多的API调用
• 每个周期：AI调用工具→ 工具执行→ 人工智能处理结果→ （必要时重复）
• 当达到限制时，对话以错误消息结束
• 建议范围：3-10，具体取决于任务的复杂性

助理定制

• assistantName：显示AI助手消息的名称（默认：“AI”）
• chatTitle：聊天标题中显示的标题（默认：“AI助手聊天”）
• greeting：聊天打开时显示欢迎消息

工具配置

• toolsSchema：自定义工具模式数组（如果提供，则覆盖MCP工具）
• 工具相关设置(toolsMode, validationOptions)在中按LLM配置 llmConfigs 数组

MCP资源

• staticResourcePatterns （字符串数组，可选）：用于启发式静态资源检测的URI子字符串。如果资源的URI（不区分大小写）包含这些子字符串中的任何一个，则该资源将被视为静态的，并在聊天打开时加载到系统提示符中。当资源来自外部MCP服务器时使用 annotations.cachePolicy示例： staticResourcePatterns={['instruction']} 使 mcp://mik-api/instruction 启动时加载到上下文中。

调试模式

• debug （布尔值，默认值： false)：启用详细的控制台日志记录

启用后，将以下内容记录到浏览器控制台：

• MCP协议：客户端初始化、服务器连接、工具/资源加载
• LLM API调用：请求参数、响应元数据、流状态
• 工具执行：带参数的工具调用、执行结果、错误
• 回退事件：配置切换、重试尝试、成功/失败状态

例子：

调试输出格式：

[Debug] MCP Client: Initializing...
[Debug] MCP Client: Protocol initialized
[Debug] MCP Client: Internal tools loaded { count: 3, tools: ['tool1', 'tool2', 'tool3'] }
[Debug] OpenAI API Request: { model: 'gpt-4o-mini', messageCount: 5, toolsCount: 3 }
[Debug] Executing Tool Calls: { count: 1, tools: ['getTool'] }
[Debug] Tool Call: getTool { id: 'call_123', args: {...} }
[Debug] Tool Result: getTool { id: 'call_123', success: true }
[Debug] OpenAI API Response: { model: 'gpt-4o-mini', finishReason: 'stop', contentLength: 145 }

注： 调试模式仅用于开发。在生产环境中禁用，以降低控制台噪音并提高性能。

本地化

支持的语言

该小部件内置了以下本地化功能：

• 英语 (en)
• 俄语 (ru)
• 中文 (zh)

使用设置语言环境 locale 道具：

自定义本地化

您可以添加自定义翻译或覆盖现有翻译：

const customLocales = {
  fr: {
    // Chat widget labels
    openChat: "Ouvrir le chat",
    voiceInput: "Entrée vocale",
    stopRecording: "Arrêter l'enregistrement",
    voiceNotSupported: "Reconnaissance vocale non prise en charge",
    clearChat: "Effacer le chat",
    collapseChat: "Réduire le chat",
    
    // Message placeholders and status
    enterMessage: "Tapez votre message...",
    speaking: "En train de parler...",
    thinking: "réfléchit...",
    user: "Utilisateur",
    tool: "Outil",
    error: "Erreur",
    greetingTitle: "Bienvenue",
    
    // Tool execution messages
    callingToolGeneric: "Exécution de l'outil...",
    
    // Error messages (voice recognition)
    noSpeech: "Aucun son détecté",
    audioCapture: "Erreur de capture audio",
    notAllowed: "Microphone non autorisé",
    notSupported: "Reconnaissance vocale non prise en charge",
    network: "Erreur réseau",
    unknown: "Erreur inconnue"
  }
};

注： 自定义区域设置与内置翻译合并，因此您只需指定要覆盖或添加的键

样式

小部件使用 CSS模块 对于作用域样式，确保与应用程序的样式没有冲突。

内置功能

• 渐变背景
• 流畅的动画和过渡
• 响应式阴影
• 移动友好型设计
• Markdown渲染支持（标题、列表、代码块、表格、复选框）

主题定制

您可以使用以下命令自定义小部件的外观 theme 道具：

所有主题属性都是可选的，如果未指定，将恢复为默认值。

自定义组件

为了完全控制UI，您可以提供一个自定义组件：

}
/>

您的自定义组件将接收所有小部件道具和状态作为道具，允许您在利用小部件逻辑的同时构建一个完全自定义的界面

浏览器支持

• Chrome 60+
• 火狐55+
• Safari 12+
• 边缘79+

发展

项目结构

src/
├── index.js                      # Main export file
├── lib/
│   ├── ChatWidget/
│   │   ├── ChatWidget.js         # Main chat widget component
│   │   ├── ChatWidget.module.css # CSS modules for styling
│   │   └── locales/              # Widget UI translations
│   │       ├── index.js
│   │       ├── en.js
│   │       ├── ru.js
│   │       └── zh.js
│   ├── locales/
│   │   └── openai/               # System prompt translations
│   │       ├── index.js
│   │       ├── en.js
│   │       ├── ru.js
│   │       └── zh.js
│   ├── mcp_core.js               # MCP protocol implementation (tools & resources)
│   ├── useMCPClient.js           # React hook for MCP client
│   ├── useMCPServer.js           # React hook for MCP server
│   ├── useOpenAIChat.js          # Chat logic and OpenAI integration
│   └── voiceInput.js             # Voice recognition module
└── examples/                      # Example implementations (not included in build)
    ├── mcp_tools_en.js           # Example MCP tools
    ├── mcp_resources_en.js       # Example MCP resources (new in v1.5.0)
    └── ...

构建系统

该项目使用Rollup与自动版本注入捆绑在一起：

• 版本和存储库URL：自动注射 package.json 在构建过程中使用 @rollup/plugin-replace
• CSS模块：使用基于哈希的类名进行隔离的作用域样式
• 多种输出格式：CommonJS、ES模块和UMD，以实现最大兼容性
• 摇树优化：ES模块构建中的死代码消除
• 压缩：与Terser优化生产捆绑

生成配置: rollup.config.cjs

// Version and repository URL are automatically replaced from package.json
replace({
  preventAssignment: true,
  values: {
    __APP_VERSION__: JSON.stringify(pkg.version),
    __REPO_URL__: JSON.stringify(pkg.repository.url)
  }
})

关键组件

• 聊天小部件：主UI组件
• 使用openaichat：聊天逻辑和消息处理
• 语音输入：语音识别模块

- 带有干净API的隔离语音识别逻辑 - 防止重复邮件传递 - 处理所有语音识别API边缘情况

• MCP核心：工具和资源通信的协议实施
• MCP工具：内置DOM操作工具
• MCP资源：AI上下文的只读数据端点（v1.5.0中的新功能）

- 静态资源：预加载的上下文数据 - 动态资源：实时按需数据 - 符合MCP 2025-06-18的规范

• 使用MCP客户端/服务器：用于MCP集成的React挂钩

贡献

1. 分叉存储库
2. 创建功能分支(git checkout -b feature/AmazingFeature)
3. 提交您的更改(git commit -m 'Add some AmazingFeature')
4. 推到分支(git push origin feature/AmazingFeature)
5. 打开拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

品牌指南

有关使用Chatrium品牌、徽标和视觉标识的信息，请参阅我们的 品牌指南.

察殿生态系统

奥克伍德 是一系列用于构建AI驱动的对话界面的工具：

• @聊天室/小部件 （此包）-带有语音输入和MCP集成的React聊天小部件
• @聊天室/服务器 _（即将推出）_ -后端MCP服务器实现
• @聊天室/cli _（即将推出）_ -Chatrium开发的命令行工具
• @聊天室/工具 _（即将推出）_ -可重复使用的MCP工具集

支持

有关问题和功能请求，请使用 .

链接

• NPM包: https://www.npmjs.com/package/@聊天室/小部件
• GitHub组织: https://github.com/chatrium
• 小部件库: https://github.com/chatrium/widget
• 文档: https://github.com/chatrium/widget#readme
• 品牌指南: 品牌_指南.md