🧠 @jasolar/copilot-ai-utis

一个可嵌入任意 Web 应用（Vue / React / Angular / 原生 JS）的 AI Copilot Web 组件。 基于 CopilotKit 构建，支持上下文注入、宿主交互事件、自定义主题与后端接入。

✨ 功能特性

✅ 跨框架支持 — 可嵌入 Vue2 / Vue3 / React / 原生 JS ✅ 零侵入集成 — 仅需引入 JS 与 CSS 即可工作 ✅ 事件通信机制 — 支持宿主应用与 Copilot 的上下文交互（双向） ✅ 可定制主题 — 支持 light / dark / 自定义颜色方案 ✅ 与 LangGraph / CopilotKit 兼容 — 可配置远程 runtimeUrl ✅ 支持 i18n / 多语言扩展

📦 安装

# 使用 npm
npm install @jasolar/copilot-ai-wc

# 或使用 pnpm / yarn
pnpm add @jasolar/copilot-ai-wc

🚀 使用方式

🧩 1. 在 Vue3 / Vue2 / React / 纯 HTML 中引入

<!-- ① 引入样式 -->
<link rel="stylesheet" href="node_modules/@jasolar/copilot-ai-wc/dist/copilot-wc.css">

<!-- ② 引入 JS -->
<script src="node_modules/@jasolar/copilot-ai-wc/dist/copilot-wc.iife.js"></script>

<!-- ③ 使用组件 -->
<ai-copilot
  theme="light"
  runtimeurl="http://your-server.com/api/copilotkit"
  style="position:fixed;right:20px;bottom:20px;width:360px;height:600px;z-index:9999;"
></ai-copilot>

🧠 2. 在 Vue3 中使用（推荐写法）

<template>
  <div id="app">
    <ai-copilot
      ref="copilot"
      theme="dark"
      runtimeurl="https://copilot-api.yourdomain.com/api/copilotkit"
      @copilot:ready="onCopilotReady"
      @copilot:provide-context="onContext"
    ></ai-copilot>
  </div>
</template>

<script setup>
function onCopilotReady(e) {
  console.log('Copilot Ready:', e.detail);
}

function onContext(e) {
  console.log('Copilot 请求上下文:', e.detail);
}
</script>

<style>
ai-copilot {
  border-radius: 8px;
  overflow: hidden;
  box-shadow: 0 4px 10px rgba(0,0,0,0.15);
}
</style>

⚙️ 参数说明

| 参数名 | 类型 | 默认值 | 说明 | | -------------- | ------------------- | ----------------- | -------------------------------- | | theme | "light" \| "dark" | "light" | Copilot 面板的主题 | | runtimeurl | string | 无 | CopilotKit / LangGraph 后端 API 路径 | | publicapikey | string | 可选 | CopilotKit 公共 API Key | | agent | string | "default_agent" | 指定后端 Agent 名称 | | autofocus | boolean | false | 是否自动聚焦到输入框 | | lang | "zh" \| "en" | "zh" | UI 语言设置 |

🔄 事件交互

| 事件名 | 触发方向 | 说明 | | -------------------------- | ------------ | ------------------- | | copilot:ready | Copilot → 宿主 | 当组件初始化完成时触发 | | copilot:provide-context | Copilot → 宿主 | 请求宿主页面上下文数据 | | copilot:context-response | 宿主 → Copilot | 宿主应用向 Copilot 发送上下文 | | copilot:open | 宿主 → Copilot | 打开 Copilot 面板 | | copilot:close | 宿主 → Copilot | 关闭 Copilot 面板 |

示例：宿主与 Copilot 通信

// 宿主发送上下文数据给 Copilot
const copilot = document.querySelector('ai-copilot');
copilot.dispatchEvent(new CustomEvent('copilot:context-response', {
  detail: {
    data: {
      type: 'chart',
      summary: '检测到折线图，包含近7日销售趋势数据',
      chartId: 'chart_001'
    }
  },
  bubbles: true,
  composed: true
}));

🎨 自定义主题

/* 可通过 CSS 变量覆盖主题 */
ai-copilot {
  --copilot-bg: #f9fafb;
  --copilot-header-bg: #3b82f6;
  --copilot-text-color: #333;
  --copilot-border-radius: 12px;
}

🧠 开发者集成指南

如果你使用 CopilotKit / LangGraph 自建后端，请确保 /api/copilotkit 路由可用，例如：

import { CopilotRuntime, copilotRuntimeNextJSAppRouterEndpoint, ExperimentalEmptyAdapter, langGraphPlatformEndpoint } from "@copilotkit/runtime";

const runtime = new CopilotRuntime({
  remoteEndpoints: [
    langGraphPlatformEndpoint({
      deploymentUrl: process.env.LANGGRAPH_DEPLOYMENT_URL,
      agents: [{ name: 'qwen_mcp_agent' }],
    }),
  ],
});

export const POST = copilotRuntimeNextJSAppRouterEndpoint({
  runtime,
  serviceAdapter: new ExperimentalEmptyAdapter(),
  endpoint: "/api/copilotkit",
}).handleRequest;

📘 开发调试

# 本地开发
npm run dev

# 打包产物
npm run build

# 本地预览 IIFE 组件
npm run preview

🧩 示例项目

你可以参考示例宿主项目（Vue3）：

🔗 https://github.com/jasolar-ai/copilot-ai-demo

📜 License

MIT © 2025 JASOLAR

💬 联系与反馈

• 作者：[email protected]
• 邮箱：[email protected]
• 反馈 / PR 欢迎提交到 GitHub