# @copilotkit/learning 中文文档

规范地址：https://npmcn.com/package/%40copilotkit/learning/

版本：1\.86\.0
npm 元数据更新时间：2026-11-11T06:12:33.796Z
中文译文更新时间：2026-11-11T06:14:48.474Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40copilotkit/learning
原文对照：https://npmcn.com/package/%40copilotkit/learning/?lang=original
项目主页：https://github.com/CopilotKit/CopilotKit#readme
源码仓库：https://github.com/CopilotKit/CopilotKit

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

- 包体积（解压后）：563 kB，38 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2026-10-02T17:46:33.621Z
- 最新版本发布：2026-11-11T06:12:33.456Z
- 近 30 天下载量：921611（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：52（近 12 个月 52 个）

## 中文简介

作为 AG-UI CUSTOM 事件在浏览器中抓取点击、页面更改和网络元数据

## 安装

```sh
npm install @copilotkit/learning
```

也可以使用：`pnpm add @copilotkit/learning`、`yarn add @copilotkit/learning`、`bun add @copilotkit/learning`

## README

# 校对:soup

抓取页面上下文,导航,点击,形成编辑,网络请求,开发者事件作为AG-UI `CUSTOM` 事件。 使用认证的核心集成将事件发送到 CopilotKit Intelligence .

抓取保留了原始URL,查询字符串,散列,页面标题,裁判员,元素文本,属性,以及默认的活控制值. 网络活动包括浏览器可见的请求和响应头和身体快照. 每张身体快照都有4个KiB限制,并有不完全或不可用内容的明确状态. 只有密码和证书被替换为 `[redacted]`,在浏览器中:

-   密码字段的值 : `type="password"`,在会话中较早有过的字段(show-password toggers),带有证书键的字段为 `name`,以及 `autocomplete` `current-password`, (中文(简体) ), `new-password`,或 `one-time-code`。 。 。 .
-   输入到密码字段的值,无论出现在身体快照,URL,或元素属性(最后20个4个或4个以上字符的值,保存在内存中直到停止,也当输入捕获被关闭时).
-   证书密钥的值, 如 `password`, (中文(简体) ), `secret`, (中文(简体) ), `api_key`, (中文(简体) ), `access_token`, (中文(简体) ), `authorization`, (中文(简体) ), `cookie`, (中文(简体) ), `jwt`,或 `token` 在JSON中,以URL编码,以及 `FormData` 机构, `key: value` 文本,查询字符串,散列,和元素属性,包括JSON字符串内部的嵌入到四个深等. 布尔斯和 `null` 留下来.
-   命名为证书的元素属性( E)`data-api-key`, (中文(简体) ), `data-token`) (中文(简体) ).
-   名称为证书密钥的信头的值( X)`authorization`, (中文(简体) ), `cookie`, (中文(简体) ), `x-api-key`, (中文(简体) ), `x-csrf-token`,加,加,加,加,加 `x-amz-security-token`, (中文(简体) ), `private-token`,以及 `x-token`。 。 。 .
-   URL 用户名和密码 (`https://user:pass@host`),在被捕获的文本中被删除.

在4个KiB限制适用之前,Redaction运行在一机构的前16个KiB上. 其它的都被活捉了 二进制正体, 手建多段文本, XML, 单引号对象, 百分位编码 JSON 内在形式值, OAuth `code=` 数值、路径符号和密码小于4个字符不编辑。 见 [获取的数据](https://docs.copilotkit.ai/intelligence/captured-data) 对于匹配的规则和限制.

使用 `capture`, (中文(简体) ), `beforeSend`, (中文(简体) ), `ignoreUrls`,以及 `data-copilotkit-ignore` 你的应用排除。 堕落者 `routes` 选项不再遮盖或转换路径.

点击事件还包括 `target.label`,是单击控件的简短、清洁的名称。 自动学习向模型显示此名称 。 它来自第一个 `aria-labelledby`, (中文(简体) ), `aria-label`,提交文件、按钮、重置或图像输入的标题, `title` (仅控制),以及按其内容命名的控件的文本:按钮,链接到 `href`, (中文(简体) ), `summary`,以及诸如 `tab`, (中文(简体) ), `menuitem`,或 `option`。在控件计数器中显示图像 `alt`, (中文(简体) ), `aria-label`,或 `<title>`,没有自己名称的单击图标则取自周围控件的名称。 控件文本在看起来像单独的字段时不使用, 如卡片: 超过80个字符, 包含标题、 列表、 表格、 字段, 或多个段落, 或分成两个 `div`s, 持有文本, 直接或通过内含元素, 或三个带文本的兄弟姐妹。 ARIA自动完成建议, 以及任何建议 `aria-labelledby`, (中文(简体) ), `aria-label`, (中文(简体) ), `title`,文本则全部被忽略 `aria-labelledby` 指向建议清单的其他地方则不提姓名。 使用 `data-copilotkit-action` 说出一个建议 容器、可编辑内容、文本排入网络组件以及 `<label>` 本地复选框或收音机按钮(使用 `aria-label` 或者说 `data-copilotkit-action` )从不提交文本;脚本、样式、模板和隐藏内容被跳过。 隐形字符被删除,密码和证书成为 `[redacted]`, URL 语句 `[url]`电子邮件 `[email]`,以及 JWT 或其他类似符号的字符串 `[redacted]`。其他名称被切为 80 个字符 `…`,以及 `label` 未留下名称时,则省略。 原始内容 `text`, (中文(简体) ), `attributes`,数值不变. `data-copilotkit-action` 在 `target.action`添加 `data-copilotkit-ignore`,或删除标签 `beforeSend`数字 :

```ts
beforeSend: (event) => {
  if (event.name === "click") delete (event.value.target as { label?: string }).label;
  return event;
},
```

见 [单击标签](https://docs.copilotkit.ai/intelligence/captured-data#click-labels) 全部规则.

每个字段将文本编辑合并,并在暂停300 ms后记录。 提交或退出字段, 按 Enter 外部输入方法组成, 点击、 导航、 发布开发者事件, 或停止抓取, 先记录待编辑 。 发财 `input` 财务报告和审定财务报表 `change` 用于同一编辑的通知生成一个记录;随后的用户编辑可以再次记录同一数值。 复选框和选择的更改仍为即时 。 见 [窗体编辑时间](https://docs.copilotkit.ai/intelligence/captured-data#form-edit-timing) 组成和交付行为.

## 认证轨迹

使用 Core 连接捕获到 CopilotKit Intelligence 。 实验性整合的目标是加入和批量API [情报1569号](https://github.com/CopilotKit/Intelligence/pull/1569)。 。 。 .

```ts
import { CopilotKitCore } from "@copilotkit/core";

const copilotkit = new CopilotKitCore({
  runtimeUrl: "/api/copilotkit",
  runtimeTransport: "single",
  learning: {
    onError: ({ code }) => console.warn("Trajectory capture:", code),
  },
});

const result = await copilotkit.startTrajectory();
if (result.status === "started") {
  copilotkit.emitTrajectoryEvent("deal.approved", { dealId: "deal-1" });
}

// Stop on consent withdrawal or when capture is no longer needed.
copilotkit.stopTrajectory();
```

省略一个 `trajectoryId` 生成一个 UUID。 在运行时认证后开始成功,凤凰频道加入. 运行时解决服务器上的用户. 浏览器提供的身份和容器ID被忽略. 设置 `learningContainerIds` 在浏览器抓取配置中产生警告;该选项仅适用于自定义汇.

要给已有的学习空间分配认证的捕获, 请配置服务器上的运行时间 :

```ts
const intelligence = new CopilotKitIntelligence({
  apiKey: process.env.CPK_INTELLIGENCE_API_KEY!,
  getTrajectoryLearningContainerIds: ({ trajectoryId, user }) => {
    // Use the verified application user to choose existing Spaces.
    return ["expense-review"];
  },
});
```

选择器接受同步或同步结果. 返回时 `[]` 没有明确要求新的任务。 返回时 `null` 或者说 `undefined` 从连接请求中删除任务。 每一个联系都增加了成员;这些结果都没有取消现有的成员,在情报部门被取消的成员仍然被取消。 保持结果稳定跨重联. 选择器不需要代理运行或串行,链接到的串行空间不会添加轨迹. 浏览器选择"轨迹ID";用户来自"运行时". 情报证实,所选的空间属于API密钥的项目.

任务问题从不停止捕捉. 如果选中的空间不存在, 运行时会记录一条警告, 并记录轨迹和空间ID, 并连接, 包括存在的空间 。 选择者有5秒钟的期限,可选择的第二秒 `AbortSignal` 在请求结束或最后期限到期时取消工作的理由。 回调错误、 无效结果或最后期限过期记录服务器错误, 而轨道连接则没有任务 。 处理指定事件需要有一个智能后端,并启用用于自动学习的轨迹输入.

抓取包括页面上下文,导航,点击,形成编辑,网络请求,以及开发者事件. 道路保持不变。 当运行时间启动代理运行时, Core 发送 `thread.linked` 和运行的 `threadId`每条线都有一次 运行时间在运行开始前创建线索,因此"情报"可以存储链接. 点击线索上下文和代理事件被推迟用于此连接路径.

核心发送凤凰 `events` 信件为 `{ events, dropped }`在两秒钟后,50个事件,或批量超过64个KiB。 每个事件必须符合16 KiB,包括序列元数据. 尺寸使用序列化的UTF-8 JSON. 网关回复方式 `{ highestSeq, accepted, rejected }`。该收据确认Redis接受,而不是Postgres承诺。 后相投影同步进行. 收据没有注明个别被拒绝的事件.

开发者事件接受任何JSON值. 核心增加数 `seq` 改为对象值。 它能包裹平面和阵列, `null`,以及已经包含的对象 `seq` 作为 `{ data: value, seq }`,保存开发者的数据.

Core 实例寿命的序列数增加,包括重新连接和停止/启动。 它们从核心实例的创建时间开始,以微秒计,而不是以0为单位,所以在重新装入一页后再重用一个 Trapjection ID的新核心实例在前几个段落之上继续. 网关每轨迹存储一次, 并承认重复被接受, 因此, 如果一个新的 Core 实例在前一个 的 ID 运行到 自己 开始之前, 大致在 1000 毫秒 内( 上一个 1000 个实例 使用的 seqs ) 启动时, 仍然会丢失作为重复的事件 。 当您不需要继续一个核心实例时, 请为每个核心实例选择一个新的 Trajectory UUID .

断开时抓取暂停 。 重新连接请求新的证书 。 恢复过程中释放的开发者事件数 `dropped`;其内容没有被缓冲. Core 保留一个批次等待收件和一个被限制的队列;它不会重发失败的批次 。 已知客户损失通过下列方式报告 `dropped`。服务器拒绝已被 Gateway 计算。 丢失的收据报告 `PERSISTENCE_UNKNOWN` 结束 `onError`,因为服务器可能保存了批次。 一个 `unauthorized` 或者说 `trajectory_mismatch` 回复停止抓取并重新连接尝试 .

停止取消等待启动并重新连接 。 它试图在没有等待收据的情况下进行最后排队批次,然后不等待就断开。 停止并不能保证最后一批被保存. 一批人仍在等待接收报告 `PERSISTENCE_UNKNOWN`包括正常停留期间.

如果一个开始或一个既定的抓取以一个错误结束,则没有 `onError` 设置, Core 记录一个带有错误代码的控制台警告和一个设置提示, 如缺失 `runtimeUrl`,没有 `intelligence`,或缺失 `identifyUser`每个结果每个核心实例都警告一次。 服务器错误消息从未在浏览器中显示 。 设置 `onError` 替换警告。 停止和可收回的连接损失不发出警告.

### 反应

抓取需要配置一个运行时间 `intelligence` 财务报告和审定财务报表 `identifyUser`,并启用了带有轨迹的项目。 然后在提供者中打开抓取:

```tsx
<CopilotKitProvider runtimeUrl="/api/copilotkit" learning>
  {children}
</CopilotKitProvider>
```

`learning` 开始捕捉 对于选项,通过对象,例如 `learning={{ onError }}`。 。 。 . `learning={false}` 或移除道具关闭捕获,符合同意开关: `learning={hasConsent}`。 。 。 .

捕获从上架后开始。 无 `learning.trajectoryId`,提供者生成轨迹标识。 ID在回放时保持不变,React BreatMode效果回放,重联,选项更改. 关闭抓取 并再次启动 新的轨迹 与新的ID。 卸载提供者停止捕获 。 读取活动 ID 从 `copilotkit.trajectoryId`,或订阅 `onTrajectoryChanged`。 。 。 .

设定 `learning.trajectoryId` 用自己的身份证代替.

要决定自己何时开始捕获,设定 `autoStart: false`。提供者配置抓取并等待您的应用程序调用 `copilotkit.startTrajectory()`数字 :

```tsx
<CopilotKitProvider
  runtimeUrl="/api/copilotkit"
  learning={{ autoStart: false }}
>
  {children}
</CopilotKitProvider>
```

与 `autoStart: false`,提供者忽略 `learning.trajectoryId` 并登录控制台警告。 将ID传递给 `startTrajectory({ trajectoryId })` 换句话说.

更早的版本等待着 `startTrajectory()` 当物体没有时 `trajectoryId`,例如 `learning={{ onError }}`。这些物体现在在挂起后开始捕获。 添加 `autoStart: false` 以保持手动启动.

## 自定义批量汇

原画 `createCollector` API支持一个实验性的自托管自定义批量槽,具有相同的浏览器捕获默认. 它不认证或连接到 Gateway .

```ts
import { createCollector, httpSink } from "@copilotkit/learning";

const collector = createCollector({
  sink: httpSink("/api/learning-events"),
});

collector.start({ trajectoryId: crypto.randomUUID() });
```

加上自定义沉入,通过 `learning` 改为 `CopilotKitProvider` 换句话说 Core添加线索上下文并释放代理和工具事件. 除非 `capture.agentText` 实值 `false`。这些添加属于自定义-沉积集成,而不是独立的浏览器抓取.

事件序列数在采集器或核心实例的寿命期间增加,包括跨站/起动周期.

文档 : [https://docs.copilotkit.ai/ 情报/抓取-互动](https://docs.copilotkit.ai/intelligence/capture-interactions)

## 常见问题

### @copilotkit/learning 是什么？

作为 AG-UI CUSTOM 事件在浏览器中抓取点击、页面更改和网络元数据

### 如何安装 @copilotkit/learning？

在项目目录运行 npm install @copilotkit/learning，或使用 pnpm add / yarn add / bun add。

### @copilotkit/learning 支持 TypeScript 吗？

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

### @copilotkit/learning 支持 ESM 还是 CommonJS？

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

### @copilotkit/learning 需要什么版本的 Node\.js？

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

### @copilotkit/learning 可以商用吗？

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

### @copilotkit/learning 的下载量有多少？

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

### @copilotkit/learning 还在维护吗？

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