npm package: @jasolar/copilot-ai-utils
Description: AI Copilot WebComponent utils.
Latest version: 1.0.9


# 🧠 @jasolar/copilot-ai-utis

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

---

## ✨ 功能特性

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

---

## 📦 安装

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

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

---

## 🚀 使用方式

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

```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 中使用（推荐写法）

```vue
<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 通信

```js
// 宿主发送上下文数据给 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
/* 可通过 CSS 变量覆盖主题 */
ai-copilot {
  --copilot-bg: #f9fafb;
  --copilot-header-bg: #3b82f6;
  --copilot-text-color: #333;
  --copilot-border-radius: 12px;
}
```

---

## 🧠 开发者集成指南

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

```ts
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;
```

---

## 📘 开发调试

```bash
# 本地开发
npm run dev

# 打包产物
npm run build

# 本地预览 IIFE 组件
npm run preview
```

---

## 🧩 示例项目

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

🔗 [https://github.com/jasolar-ai/copilot-ai-demo](#)

---

## 📜 License

[MIT](LICENSE) © 2025 JASOLAR

---

## 💬 联系与反馈

* 作者：liyanwen@jasolar.com
* 邮箱：[liyanwen@jasolar.com](mailto:liyanwen@jasolar.com)
* 反馈 / PR 欢迎提交到 GitHub