ai-run-everywhere

一个轻量级 React 组件，让你的 <img> 元素拥有 AI 对话能力。

English

包裹任意图片后，右上角会出现一个悬浮按钮，点击即可弹出居中对话面板。用户输入问题后，组件自动提取图片内容发送给大模型，并实时流式展示回答。

特性

• 零运行时依赖 — React 作为 peerDependency，不引入任何第三方包
• 样式完全隔离 — 选择器前缀 ai-rew-* + Portal 渲染 + all: initial 重置，不会污染宿主也不会被宿主污染
• 流式输出 — 支持 SSE 流式响应，逐字实时展示回复
• 跨域安全 — 通过 fetch + blob URL 提取图片，不触发 canvas taint
• 配置灵活 — 全局配置一次，也可针对单个组件覆盖
• OpenAI 兼容 — 支持任何 OpenAI 兼容 API（通过自定义 baseUrl）
• ESM + CJS 双格式 — 适配所有主流打包工具

安装

npm install @cxy13h/ai-run-everywhere

快速上手

第一步：全局配置

在应用入口处挂载 <AiProvider>，设置 apiKey、baseUrl 和 model：

import { AiProvider, AiWrap } from "@cxy13h/ai-run-everywhere";

function App() {
  return (
    <AiProvider
      apiKey="sk-your-key"
      baseUrl="https://api.openai.com/v1"
      model="gpt-4o-mini"
    >
      <MyPage />
    </AiProvider>
  );
}

第二步：包裹图片

在任意 <img> 外面包一层 <AiWrap>：

<AiWrap>
  <img src="/photo.jpg" alt="产品图" />
</AiWrap>

点击右上角的星星按钮即可开始 AI 对话。

第三步：单组件覆盖配置

每个 <AiWrap> 都可以覆盖全局配置，只对该组件生效：

// 这张图用更高级的模型
<AiWrap model="gpt-4o">
  <img src="/detail.png" alt="详情图" />
</AiWrap>

// 这张图用完全不同的 API
<AiWrap apiKey="sk-another" baseUrl="https://my-proxy.com/v1">
  <img src="/another.jpg" alt="另一张图" />
</AiWrap>

配置优先级：<AiWrap> props > <AiProvider> 全局配置 > 内置默认值

API 参考

<AiProvider>

全局配置组件，在应用入口处挂载一次。

| Prop | 类型 | 默认值 | 说明 | |------|------|--------|------| | apiKey | string | "" | API 密钥 | | baseUrl | string | "https://api.openai.com/v1" | OpenAI 兼容 API 地址 | | model | string | "gpt-4o-mini" | 模型名称 | | systemPrompt | string | 内置默认 | 系统提示词 | | children | ReactNode | — | 子组件 |

<AiWrap>

包裹组件，在任意 <img> 外面包一层即可启用 AI 对话。

| Prop | 类型 | 默认值 | 说明 | |------|------|--------|------| | children | ReactNode | — | 被包裹的 <img> 元素 | | display | string | "inline-block" | 包裹容器的 CSS display | | className | string | "" | 自定义 class | | disabled | boolean | false | 禁用触发按钮 | | trigger | ReactNode | 星星图标 | 自定义触发按钮内容 | | tooltip | string | "Ask AI" | 悬停提示文字 | | apiKey | string | — | 覆盖全局 API key | | baseUrl | string | — | 覆盖全局 baseUrl | | model | string | — | 覆盖全局 model | | systemPrompt | string | — | 覆盖全局 systemPrompt |

环境变量配置示例（Vite 项目）

# .env
VITE_OPENAI_API_KEY=sk-your-key
VITE_API_BASE_URL=https://api.openai.com/v1
VITE_MODEL=gpt-4o-mini

<AiProvider
  apiKey={import.meta.env.VITE_OPENAI_API_KEY}
  baseUrl={import.meta.env.VITE_API_BASE_URL}
  model={import.meta.env.VITE_MODEL}
>
  <App />
</AiProvider>

样式隔离说明

本包通过三重机制确保不影响宿主项目：

1. 选择器前缀 — 所有 CSS 类名以 ai-rew- 开头，不会与宿主冲突
2. Portal 渲染 — 对话面板通过 ReactDOM.createPortal 挂载到 document.body，完全脱离宿主 DOM 树
3. all: initial 重置 — 面板内部先清除所有继承样式再重新设置，宿主的全局 CSS 不会渗入

包裹容器仅设置 position: relative 和 display，不影响子元素布局。

浏览器兼容性

• Chrome 80+
• Firefox 78+
• Safari 14+
• Edge 80+

License

MIT