# @cimulate/copilot-widget 中文文档

规范地址：https://npmcn.com/package/%40cimulate/copilot-widget/

版本：1\.55\.1
npm 元数据更新时间：2026-11-06T21:04:55.293Z
中文译文更新时间：2026-11-09T16:12:37.457Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cimulate/copilot-widget
原文对照：https://npmcn.com/package/%40cimulate/copilot-widget/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：6.5 MB，16 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.15\.0
- 运行依赖：13 个
- peer 依赖：react ^18\.3 \|\| ^19，react-dom ^18\.3 \|\| ^19
- 首次发布：2025-09-03T20:40:20.703Z
- 最新版本发布：2026-11-06T21:04:55.127Z
- 近 30 天下载量：4606（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：183（近 12 个月 170 个）

## 中文简介

模拟副驾驶的前端 SDK

## 安装

```sh
npm install @cimulate/copilot-widget
```

也可以使用：`pnpm add @cimulate/copilot-widget`、`yarn add @cimulate/copilot-widget`、`bun add @cimulate/copilot-widget`

## README

# 副驾驶部件 SDK

Cimulate 的 Copilot Widget SDK 是一个 React 组件库, 允许您将我们的 Copilot 部件嵌入您的应用程序 .

## 安装

> **要求节点++22.1.5.0和npm++10.9.2**

```sh
npm install @cimulate/copilot-widget
```

国家预防机制的东道方必须提供 `react` 财务报告和审定财务报表 `react-dom` (单位:千美元)`^18.3 || ^19`) (中文(简体) ). 公布的无害环境管理文物从东道主进口这些同龄人(没有捆绑)。 CDN/小额供资 `<script>` 安装没有改变, 仍然捆绑 React .

## 套装大小快照

使用 `npm run measure:bundle-sizes` 用于在 gzip 大小之前/之后捕获以优化。 刷新后从此目录中运行全部 `npm run build` 这样 `dist/` 匹配正在测试的代码.

1会话 = 1乘以下 `.tmp/bundle-sizes/<DD-MM-YYYY-HHmmss>/` 与 `bundle-sizes.before.json` 财务报告和审定财务报表 `bundle-sizes.after.json`。 。 。 . `.tmp/` 粘贴 `--diff` 如果您需要持久记录,则将表格输入公关.

```sh
# 1. Baseline (before the change)
npm run build
npm run measure:bundle-sizes -- --before

# 2. Apply the change, rebuild, capture after
npm run build
npm run measure:bundle-sizes -- --after

# 3. Diff the latest session
npm run measure:bundle-sizes -- --diff
```

-   在每次抓获之前建构; stale `dist/` 生成错误的数字.
-   每届更改一次——运行新的 `--before` 每个优化/PR.
-   不要再开始另一个 `--before` 直到你写完 `--after` 编号 : `--diff` 用于当前对; `--after` 赤裸裸的 `--diff` 总是使用 **最新消息** 时间戳目录.
-   明确区分出一对老夫妇:

```sh
npm run measure:bundle-sizes -- --diff \
  .tmp/bundle-sizes/<timestamp>/bundle-sizes.before.json \
  .tmp/bundle-sizes/<timestamp>/bundle-sizes.after.json
```

## 游戏场

### 反演 App 游戏场

```sh
npm start
```

模拟反应环境。 由于Vite通过热模块替换服务源——不需要全面构建,更改在浏览器中即时反映,因此在本地开发上更快. 这是客户最合适的测试游乐场,他们将把部件集成到基于反应的商店前端.

设置在 `src/App.tsx`。可以修改的示例配置 :

```tsx
// Theme definitions
const THEMES: Record<string, ThemeConfig> = {
  sfra: {
    primaryColor: "#0070D2",
    fontFamily: '"Helvetica Neue", Arial, sans-serif',
    backgroundColor: "#F7F7F7",
    // ...
  },
  "storefront-next": {
    primaryColor: "#000000",
    fontFamily: '"Inter", sans-serif',
    backgroundColor: "#FFFFFF",
    // ...
  },
};

// Copilot mode props
<CopilotWidget
  apiKey={apiKey}
  theme={currentTheme}
  logoUrl="https://example.com/logo.png"
  headerText="Cimulate Copilot"
  isDevelopment={true}
/>

// Agentforce/Messaging mode props
<AgentForceWidget
  headerText="Commerce Client"
  disclaimerMarkdown="This is AI, *be careful*."
  isDevelopment={true}
  theme={currentTheme}
  searchConfig={{
    placeholder: "Find me cutting-edge outdoor gear",
    buttonType: "icon",
    buttonIcon: "arrow",
  }}
  messagingConfig={{
    scrt2Url: "",
    orgId: "",
    esDeveloperName: "AgentForce",
  }}
/>
```

> **通讯模式 :** 附录 `?ccDevMode=true` 到页面 URL 强制 `isDevelopment` 在运行时(设置终点+动词记录),不需要重新部署.

### HTML / CDN 集成游戏场

```sh
npm run preview
```

最常见的整合方法,因为它是框架不可知性的. 部件的任何更改都应该在这个操场上测试. 当地发展速度较慢,因为它必须生产出一个完整的三件文物(主捆绑,副驾驶分捆绑,发短信分捆绑),并且需要在每个变化上重建.

设置在 `public/index.html`。可以修改的示例配置 :

```html
<script>
  // Widget injection with configuration
  injectCopilotWidget({
    elementId: "root",
    apiKey: "INSERT_YOUR_API_KEY_HERE",
    componentConfig: { isOpen: true, options: { dialogPosition: "bottom-right" } },
    isDevelopment: true,
    mode: "copilot",
    theme: {
      primaryColor: "#000000",
      fontFamily: '"Inter", sans-serif',
      backgroundColor: "#FFFFFF",
    },
    headerText: "Commerce Client",
    searchConfig: {
      placeholder: "Find me cutting-edge outdoor gear",
      buttonType: "icon",
      buttonIcon: "arrow",
    },
  });

  // Event handlers for programmatic control
  const { eventHandlers } = window["cimulate-copilot-widget"];

  eventHandlers.search.updateSearchQuery("running shoes");
  eventHandlers.components.setWidgetType("modal"); // "chat" | "dialog" | "modal"
  eventHandlers.components.toggleWidgetOpen(true);
  eventHandlers.pdp.setPdpContext({ productId: "product-123" });
  eventHandlers.browse.setBrowseContext({ categoryId: "outdoor-gear" });

  // Messaging mode: submit a query from a storefront search bar or embedded question
  const { sendMessage, eventHandlers: messagingHandlers } = window.CimulateMessaging;
  sendMessage("running shoes");
  messagingHandlers.components.toggleWidgetOpen(true);
</script>
```

### 通讯页面上下文

消息集成通过通用的页面折叠式API提供规范的产品详细页 (PDP) 或搜索结果页 (SRP) 存储前端状态:

```ts
import { eventHandlers } from "@cimulate/copilot-widget/messaging";

eventHandlers.pageContext.set({
  type: "pdp",
  id: "product-123",
  display: {
    name: "Deep Cleansing Foam",
    imageUrl: "https://store.example.com/products/foam.jpg",
  },
});

eventHandlers.pageContext.set({
  type: "srp",
  query: "running shoes",
  refinements: [{ name: "color", values: ["blue"] }],
  minPrice: 50,
  maxPrice: 150,
});

const current = eventHandlers.pageContext.get();

eventHandlers.pageContext.clear();
```

`refinements`, (中文(简体) ), `minPrice`,以及 `maxPrice` 对 SRP 上下文是可选的。 部件省略了空的改进和未定义的价格界限 。 PDP和SRP的背景是相互排斥的.

种子页面上下文一次(形状与 `eventHandlers.pageContext.set`,通过 `messagingConfig.initialPageContext` 与 `enablePageContext: true`。之后的运行时间更新仍然通过事件处理器进行.

```tsx
<AgentForceWidget
  mode="messaging"
  messagingConfig={{
    enablePageContext: true,
    initialPageContext: {
      type: "srp",
      query: "running shoes",
      refinements: [{ name: "color", values: ["blue"] }],
      minPrice: 50,
      maxPrice: 150,
    },
    // existing SCRT2 fields...
  }}
/>
```

与 `messagingConfig.enablePageContext`,部件当shop发送短信并重用它进行重试和会话恢复时,将页面上下文抓取。 每个 PDP 或 SRP 上下文切换后的第一个文本消息都会在用户泡上方获得一个分割符. 更改页面从不单独发送消息 。 文件上传不包含页面上下文或创建分隔符.

可选的 PDP `display` 字段设置产品芯片和分割符的名称和图像。 SRP上下文显示可移动芯片并带有搜索图标和 `Search: "query"`;其分隔符使用相同的标签. 一次只显示一个上下文芯片. 删除芯片可以清除页面上下文, 因此下一个信件没有上下文或分隔符 。 芯片仍然可见,用于同一产品或搜索查询上的后期消息. 设置 SRP 上下文替换了 PDP 芯片,而设置 PDP 上下文替换了 SRP 芯片.

### 通讯卡

消息集成 推动当前篮子 `eventHandlers.cart.update`。仅从邮件条目中调用它 : `window.CimulateMessaging.eventHandlers.cart.update(cart)` 或以下输入的国家预防机制。 副驾驶的条目没有曝光.

```ts
import { eventHandlers } from "@cimulate/copilot-widget/messaging";

eventHandlers.cart.update({
  id: "cart-1",
  currencyCode: "USD",
  subtotal: 90,
  total: 90,
  items: [
    {
      itemId: "line-1",
      productId: "SKU-1",
      name: "Men's Rovereto Running Shoes",
      imageUrl: "https://store.example.com/products/shoes.jpg",
      quantity: 1,
      itemSubtotal: 90,
      originalSubtotal: 90,
      variants: [{ lbl: "Color", type: "color", value: "Black / White" }],
    },
  ],
});
```

对象为全篮子(`CartDetails`),不是数量分贝. 一个空的 `items` 数组表示空推车。 无有效载荷 `items` 数组被忽略 。 部件挂起前的呼叫被忽略 .

在部件被挂起后, 在页面加载时, 在部件外的shop 更改篮子后, 在恢复对话后再次调用它 。 聊天中最新的推车消息 更新到那个篮子。 旧的手推车信息保持不变 电话没发出 `cimulate:cart-update`下一个代理推车的结果与那个篮子比较.

## 勾起和承诺前钩

Lint 和 npm 脚本本地格式化 :

```sh
npm run lint       # prettier --check + eslint
npm run lint:fix   # prettier --write + eslint --fix
```

ESLint 执行来自 `AGENTS.md` 通过两项当地规则(`local/banner-comments`, (中文(简体) ), `local/redundant-identifier-comment` 内 `eslint-rules/`) (中文(简体) ).

承诺前的钩子( A)`.pre-commit-config.yaml`)在副驾驶-widget文件上运行更漂亮的+eslint,在格式化/lint出错时失败了承诺. 用同样的 [`pre-commit`](https://pre-commit.com/) 框架作为 Python 次级项目(见 [文件/开发/开发-工作流程](https://npmcn.com/package/docs/development/development-workflow.md)) (中文(简体) ).

`npm run start` 财务报告和审定财务报表 `npm run preview` 自动为您安装此钩子( 通过 `scripts/ensure-precommit.sh`),只要 `pre-commit` 工具在您的路径上。 如果你看到一个 `pre-commit' is NOT installed` 在启动 dev 服务器时警告, 安装此工具, 它会在下一个启动时自动连接 :

```sh
brew install pre-commit   # macOS (recommended — avoids pyenv/venv shim issues)
pip install pre-commit    # any platform
```

要手动设置钩子( 或者如果你不使用 Dev 服务器), 请从此目录中运行一次 :

```sh
cd javascript/copilot-widget
brew install pre-commit   # or: pip install pre-commit
pre-commit install
```

钩子只是编了文件, 所以在别处存在的问题不会阻碍你的承诺.

## 发布流程

该项目遵循基于干线的开发——所有更改直接合并到 `master`。该软件包使用语义化版本;将版本打入 `package.json` 在合并之前。 注意倒向相容性,因为客户现有的执行依赖于公共API.

出版由 **构建并发布 Javascript 软件包** GitHub 动作工作流程 (`.github/workflows/build-and-publish-js.yaml`) (中文(简体) ).

**触发 :** 推动 `master` 变动情况 `javascript/` (仅运行于 `copilot-widget`) (中文(简体) ).

**步骤 :**

1.  安装依赖关系
2.  运行测试( R)`npm run test`(中文(简体) )
3.  构建( E)`npm run build`(中文(简体) )
4.  发布到 npm (`npm publish --access public`(中文(简体) )
5.  将UMD捆绑和CSS上传到Google Cloud存储桶,用于CDN的发件,由软件包版本提供:
    
    ```
    <bucket>/copilot-widget/<version>/*.umd.js
    <bucket>/copilot-widget/<version>/*.css
    ```
    

## 创建共线

对照本地版本的 SDK 依赖性开发, 使用 `npm link`数字 :

### 副驾驶

```sh
# In javascript/copilot-sdk
npm install
npm run build
npm link

# In javascript/copilot-widget
npm link @cimulate/copilot-sdk
```

### 代理服务器

```sh
# In javascript/agentforce-sdk
npm install
npm run build
npm link

# In javascript/copilot-widget
npm link @cimulate/agentforce-sdk
```

打开并恢复登记版本:

```sh
npm unlink @cimulate/copilot-sdk
npm unlink @cimulate/agentforce-sdk
npm install
```

## 常见问题

### @cimulate/copilot-widget 是什么？

模拟副驾驶的前端 SDK

### 如何安装 @cimulate/copilot-widget？

在项目目录运行 npm install @cimulate/copilot-widget，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.3 \|\| ^19）、react-dom（^18\.3 \|\| ^19）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cimulate/copilot-widget 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cimulate/copilot-widget 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cimulate/copilot-widget 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.15\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cimulate/copilot-widget 可以商用吗？

@cimulate/copilot-widget 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cimulate/copilot-widget 的下载量有多少？

根据 npm 官方下载统计，@cimulate/copilot-widget 在 2026/10/10 – 2026/11/08 这 30 天内被下载 4,606 次，日均约 154 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cimulate/copilot-widget 还在维护吗？

最新版本 1\.55\.1 发布于 2026/11/07（2 天前）；至今共发布 183 个版本，其中过去 12 个月发布了 170 个；首次发布于 2025/09/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。