# @copilotkit/channels-core 中文文档

规范地址：https://npmcn.com/package/%40copilotkit/channels-core/

版本：0\.12\.0
npm 元数据更新时间：2026-10-28T13:38:16.370Z
中文译文更新时间：2026-11-10T18:20:52.408Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：866 kB，306 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：6 个
- peer 依赖：react \>=18，takumi-js ^2\.7\.3
- 首次发布：2026-07-15T20:27:30.898Z
- 最新版本发布：2026-10-28T13:38:15.171Z
- 近 30 天下载量：1191150（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：44（近 12 个月 44 个）

## 中文简介

用于CopilotKit的平台-不可知JSX频道引擎(创建Channel,Thread,PlaendAdapter,ActionStore).

## 安装

```sh
npm install @copilotkit/channels-core
```

也可以使用：`pnpm add @copilotkit/channels-core`、`yarn add @copilotkit/channels-core`、`bun add @copilotkit/channels-core`

## README

# @ copilotkit/ 频道核心

背后支持的平台中立基础 `@copilotkit/channels`。 。 。 . 多数应用应使用包含的电池 `@copilotkit/channels` 软件包; 在建设适配器或有意选择一个平台时直接安装核心.

**频道通过频道跑道运行.** 副驾驶Kit情报部门提供 管理下跑者,可在自由计划中使用: `CopilotRuntime` 开始和拥有 每个频道一旦配置了情报——见下文"运行频道". 在SDK原始人身上建造和操作自己的频道跑道也是 支持路径; 团队选择它自己的状态, 坚持, 货币, 锁上门 复试 和种族条件处理.

## 选择性安装

```sh
pnpm add @copilotkit/channels-core @copilotkit/channels-slack
```

```json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "@copilotkit/channels-core"
  }
}
```

```ts
import { createChannel } from "@copilotkit/channels-core";
import { slack } from "@copilotkit/channels-slack";
```

`createChannel(opts)` 返回 a `Channel`数字 :

-   `onMention(handler)` 编号 : `onMessage(handler)` - 接收转弯处理器 `{ thread, message }`选中对象 `onMention` 登记时 否则就回到 `onMessage`; 其他内容选择 `onMessage`。 。 。 .
-   `onThreadStarted(handler)` - 对话表面打开(例如Slack) 辅助窗格; 接收 `{ thread, user, actor }`。问候,设置提示 或标题,或运行代理。 没有概念的适配器从不发射.
-   `onWelcome(handler)` 供应商安装或对话激活; 接收 `{ thread, user?, platform }`。无可靠适应器 启动事件永远不会发射.
-   `onInteraction<TValue>(id, handler)` - 明确的越狱操作员 已知行动编号,绕过登记册; `ctx.action.value` 输入 `TValue`。 。 。 .
-   `onInterrupt<TPayload>(eventName, handler)` 处理被俘的特工 中断( LangGraph 风格) `on_interrupt`; 获得 `{ payload, thread, user, actor }` 与 `payload` 类型 `TPayload`。 。 。 .
-   `onCommand(command)` 编号 : `onCommand(name, handler)` 登记斜线命令. 处理者得到 `{ thread, command, text, options, user, actor }`。 。 。 . `text` 这是 生rg; `options` 是已键入,解析的窗体(`defineChannelCommand` 带有 `options` 标准Schema),用于有原生结构的地表 (如"迪斯克". 这是一个直接适应能力:管理Slack和Teams 将主斜线文本作为普通信件内容, 不注册 提供者斜线命令。 转发到支持命令的直接适配器 在别处被忽略 `commands` 内 `CreateChannelOptions`。 。 。 .
-   `tool(t)` 登记a `ChannelTool` (备选案文: `opts.tools`(必须如此) 运行时间激活频道前添加.

`agent` 是可选的。 如果省略, 调用 `thread.runAgent()` 投掷; 供应 a 一个 `AbstractAgent` 或一个 `(threadId) => AbstractAgent` 工厂.

A 类 `Channel` 没有公开 `start()` 编号 : `stop()` - 生命周期为运行时间所有 (见下文).

## 运行频道

在管理路径中,一个频道在宣布时运行 情报配置 `CopilotRuntime`通过 `Channel` 内 `channels`, (中文(简体) ), 然后通过返回的处理器驱动激活 :

```ts
import { createChannel } from "@copilotkit/channels-core";
import { slack } from "@copilotkit/channels-slack";
import { CopilotRuntime, CopilotKitIntelligence } from "@copilotkit/runtime/v2";
import { createCopilotNodeListener } from "@copilotkit/runtime/v2/node";

const channel = createChannel({
  name: "support-bot", // project-unique Intelligence Channel name
  identifyUser: "platform",
  adapters: [slack({ botToken, appToken })],
});

const runtime = new CopilotRuntime({
  intelligence: new CopilotKitIntelligence({
    // apiUrl and wsUrl default to cloud-hosted CopilotKit Intelligence — override
    // both together only for a self-hosted deployment.
    apiKey: process.env.CPK_INTELLIGENCE_API_KEY!, // free tier available
  }),
  channels: [channel],
});

// Creating the listener starts every declared channel's connection.
const listener = createCopilotNodeListener({ runtime });
// Optional: await that activation so a broken config fails startup loudly.
await listener.channels.ready();
// await listener.channels.stop(); // tears them down
```

运行时间也宣布管理Slack和Teams为同名频道名. 开发者拥有的适配器留在适配器阵列中,并可能同时运行 管理适配器。 如果管理的设置不完整, 则配置直接适配器 继续开始时 `listener.channels.status()` 报告 `setup_required` 联 合 国 管理路径 .

## `Thread`

A 类 `Thread` 是交给您的处理器和工具的每个对接手柄 环境。 它接受任何 `Renderable` (JSX或字符串)发布.

```ts
interface Thread {
  readonly platform: string;
  post(ui: Renderable): Promise<MessageRef>;
  update(ref: MessageRef, ui: Renderable): Promise<MessageRef>;
  delete(ref: MessageRef): Promise<void>;
  stream(src: string | AsyncIterable<string>): Promise<MessageRef>;
  runAgent(input?: {
    context?: ContextEntry[];
    tools?: ChannelTool[];
    memory?: MemoryGrant;
  }): Promise<MessageRef | undefined>;
  resume(
    value: unknown,
    options?: {
      memory?: MemoryGrant;
      subject?: "initiator" | "actor";
    },
  ): Promise<MessageRef | undefined>;
  awaitChoice<T = unknown>(
    ui: Renderable,
    options?: {
      answerableBy?: "initiator" | "conversation";
      timeoutMs?: number;
      signal?: AbortSignal;
    },
  ): Promise<T>;
  // Capability-gated (return { ok: false } on surfaces without support):
  setSuggestedPrompts(
    prompts: ReadonlyArray<{ title: string; message: string }>,
    opts?: { title?: string },
  ): Promise<{ ok: boolean; error?: string }>;
  setTitle(title: string): Promise<{ ok: boolean; error?: string }>;
}
```

-   `post` 编号 : `update` 将JSX提交伊朗, **绑定** 每个事件处理器 在树上(将一个内容稳定的id,快照,重写道具) `{ id }`然后把IR交给适配器.
-   `runAgent` 解决对话的代理会话, 创建适配器的 `RunRenderer`,并驱动运行/工具/中断循环。 逐一运行 `tools` 编号 : `context` 仅用于该运行的频道级别默认值之上合并.
-   `resume(value)` 重新进入中断运行 `forwardedProps.command`。 。 。 .
-   `awaitChoice<T>(ui, options?)` 张贴一个拾取器并块到点击一个 由拾取者自己的控制解决(HITL);通过 `T` 键入 返回值。 见 [等待选择](https://npmcn.com/package/%40copilotkit/channels-core/#readme-waiting-for-a-choice)。 。 。 .

### 等待选择

`awaitChoice` 以拾取者自己为 点击控件: 按钮 `value`,选择的匹配选项,或 输入文本。 点击其它任何控件( 先前的卡片, a) stale picker, 一个不相关的选择) 从不回答它, 和一个选定的值 采摘人不提供,被拒绝.

-   `answerableBy` 决定谁可以回答. `"initiator"` (默认,由 `DEFAULT_AWAIT_CHOICE_ANSWERABLE_BY`)只接受提供者账户: 开始转弯,并配以其id; 演员的 `kind` 从来没有被咨询, 所以一个由机器人开始的转弯只能由那个机器人来回答. 当转弯时 演员没有身份,马上拒绝 `ChannelChoiceInitiatorUnknownError` (单位:千美元)`channel_choice_initiator_unknown`) (中文(简体) ). `"conversation"` 在谈话中接受任何人 选择者被张贴 只能通过拾取者自己的控制.
-   `timeoutMs` 绑定等待( 默认) `DEFAULT_AWAIT_CHOICE_TIMEOUT_MS`,一个 小时; `Infinity` 以无所限. 超时时拒绝选择 `ChannelChoiceTimeoutError` (单位:千美元)`channel_choice_timeout`) (中文(简体) ). 有限的暂停 最多必须是2147483647米(2^31-1,约24.8天),是最长的延迟a 计时器;一个较大的一个同时拒绝 `RangeError`。 。 。 .
-   `signal` 中止等待: 选择拒绝 `ChannelChoiceAbortedError` (单位:千美元)`channel_choice_aborted`) (中文(简体) ).

谈话有一个待决的选择:一个更新的 `awaitChoice` 那边 拒绝年长者 `ChannelChoiceSupersededError` (单位:千美元)`channel_choice_superseded`) (中文(简体) ). 如果点击的控件是自己的 `onClick` 抛出, 选择拒绝错误。 一旦一个选择解决了,它的拾取者 控制不运行或回答任何东西.

## 工具上下文( C)

A 类 `ChannelTool` 作为前端工具转发给代理;其处理器运行于 代理调用时的频道。 处理者 `ctx` 携带 `thread`,所以一个 工具可以使 JSX (`ctx.thread.post(<Card .../>)`)或运行代理进一步.

```ts
interface ChannelTool<Schema extends ObjectSchema = ObjectSchema> {
  name: string;
  description: string;
  parameters: Schema; // any Standard Schema (Zod/Valibot/ArkType/…)
  handler(args, ctx: ChannelToolContext): Promise<unknown> | unknown;
}
```

定义一个与未购买 `defineChannelTool`,从而推断出参数类型 从 `parameters`数字 :

```ts
defineChannelTool({
  name: "read_thread",
  description: "Read the messages in the current conversation.",
  parameters: z.object({}),
  async handler(_args, { thread }) {
    return await thread.getMessages();
  },
});
```

`parameters` (a Standard Schema)转换为JSON Schema,用于LLM和 回来的路上验证过了. `ChannelToolContext` 实值 `{ thread, message?, user?, signal?, platform }` ——一个单一的共享类型,没有每个适应器通用. 仅通过能力配置实现平台专用电能 `thread` 方法(例如:. `thread.getMessages()`, (中文(简体) ), `thread.lookupUser(query)`, (中文(简体) ), `thread.postFile(...)`),所以一个工具在平面上保持可移植.

A 类 `ContextEntry` 实值 `{ description: string; value: string }` 知识 折叠到每个代理的系统上下文 `runAgent`。 。 。 .

## 代理组件

`defineChannelComponent` 将服务器授权的 JSX 函数转换为代理 工具。 它的标准Schema 验证工具前的参数 `render` 运行。 成 法 上下文提供源 `platform` 和运行 `AbortSignal`。 。 。 .

```tsx
import { createChannel, defineChannelComponent } from "@copilotkit/channels";
import { z } from "zod";

const Approval = defineChannelComponent({
  name: "show_approval",
  description: "Post an approval request.",
  parameters: z.object({ title: z.string() }),
  render: ({ title }, { platform, signal }) => (
    <Card title={`${title} (${platform})`}>
      <Button key="approve" value="approve" onClick={approve}>
        Approve
      </Button>
    </Card>
  ),
});

const channel = createChannel({
  name: "approvals",
  components: [Approval],
});
```

当代理打电话 `show_approval`,频道将发送的消息作为 单独的提供者消息并返回一个简短的工具确认。 经纪人 然后继续运行。 组件定义中的交互式节点需要稳定, 独有的JSX密钥. 频道用源平台和动作存储这些密钥 值,所以点击或反应可以在重启后恢复同一处理器. 遗产 `components: { Name: Component }` 登记仍在使用位置 恢复旧的快照.

## 动作系统

每一个实现的交互式节点都获得新鲜 **随机、不透明** 动作编号 (单位:千美元)`mintActionId()`数字 : `"ck:"` +128 随机位,基数64url. 只有不透明的代号 (加上任何小额) `bind()` (ags)是印在地上;没有道具,PII, 或秘密传到线上.

每一个动作都与它被张贴到的对话和平台相接. A 类 点击只在从同一对话中到达时发出,并且 平台(`ActionRegistry.dispatch(id, ctx, { conversationKey, platform })`, (中文(简体) ), 都取自入侵事件 `ActionScopeMismatchError`。 。 。 . `<Message onReaction>` 处理器是相同的范围 就是这样.

点击时 `ActionRegistry` 将处理器从热的记忆中解开 缓存; 在错过时 **水合物** 从中装入快照 `ActionStore`,用被冻结的道具将命名的部件重置,以及 重行取取取取取者道.

仅以名称注册的组件(`createChannel({ components })`,或 `ActionRegistry.registerComponent(name, fn)`)为再水合:贴出 `<Component />` 元素以它注册的名称绑定。 一个名字 准确识别一个组件,因此将其登记为另一个组件,或 一个组件在两个名字下,抛出。 未注册的元素 函数绑定内行, 如平面树: 一旦其进程内缓存条目为 ,点击它报告 `ActionExpiredError`A级 函数本身 `name` 从未使用,因为两个函数可以共享.

保留为 `actionRetentionMs` (违约7天, `DEFAULT_ACTION_RETENTION_MS`每个存储的快照都是用TTL写的, 并最多持有 `DEFAULT_MAX_HOT_ACTIONS` 他们中的10 000人驱逐了最近使用最少的人.

默认 `ActionStore` 实值 `InMemoryActionStore` 联合国 `Map` 可选 (原始内容存档于2018-10-21). TTL. 它在重启时丢失:在重启后,单击旧按钮可降解为 a 一个 `ActionExpiredError`。 。 。 . `createChannel` 在警告时 平台有本地的麻黄信息,告诉点击器“此动作有 过期". 点击一个从未有过动作的控制( 链接按钮, a) 按钮没有处理器)带有倒置的id而不是薄荷 `ck:` 编号, 被悄悄地忽略(调试日志) . **持久动作需要外部存储( Redis / DB) —— 不运入 v一.** 执行 `ActionStore` 接口( e)`put` 编号 : `get` 编号 : `delete`和 传为: `actionStore` 使动作在重新启动后幸存.

## 写入 a `PlatformAdapter`

瞄准新地表,执行 `PlatformAdapter` 从这个包裹。 这个 引擎通过 `IngressSink` 您将接收 `start(sink)` (单位:千美元)`sink.onTurn(IncomingTurn)` 编号 : `sink.onInteraction(InteractionEvent)` 编号 : `sink.onCommand(IncomingCommand)` 编号 : `sink.onThreadStarted(IncomingThreadStart)`(中文(简体) ) 穿过你 `post` 编号 : `update` 编号 : `stream` 编号 : `delete` (收到 `ChannelNode[]` 转换成原生有效载荷 `render`) (中文(简体) ). 您还提供 `createRunRenderer(target)` (AG-UI公司) `RunRenderer`: 流的订阅者 输入,加上用于被捕获工具调用的访问器,并中断运行启动 逐一读取 `runAgent`, (中文(简体) ), `decodeInteraction(raw)` (内在活动 + 不透明) `InteractionEvent`, (中文(简体) ), `lookupUser`页:1 `conversationStore` (单位:千美元)`getOrCreate` → `AgentSession`)和表面 `capabilities` 编号 : `ackDeadlineMs`可选能力方法,例如 `getMessages(target)` 财务报告和审定财务报表 `postFile(target, args)` 备份匹配 `thread` 表面时的方法 支持它们——同样 `setSuggestedPrompts(target, prompts, opts?)` 财务报告和审定财务报表 `setThreadTitle(target, title)` 回来 `thread.setSuggestedPrompts` 编号 : `thread.setTitle`, (中文(简体) ), `sink.onWelcome(...)` 发射可靠装置或 激活事件,以及 `sink.onThreadStarted(...)` 发出"对话" 打开"生命周期事件。 直接适应器斜线命令也是能力定型的:一个适应器向前 通过 `sink.onCommand(IncomingCommand)`,并可能执行 `registerCommands(specs)` 在前面发布频道宣布的命令 (例如Discord的应用程序命令 API);省略的适配器被跳过. 如果在您发布的信息上点击( 或反应) 键入到不同的 `conversationKey` 而不是贴出它的转弯(点击一键) 顶级消息通过该消息自己的 ts 执行 `postedConversationKey(target, posted, kind)` 因此,发动机瞄准 消息的动作到键 `decodeInteraction` 将报告. 见 `@copilotkit/channels-slack` (c) 全面执行《公约》.

## 出口

`createChannel`, (中文(简体) ), `Channel`, (中文(简体) ), `CreateChannelOptions`, (中文(简体) ), `ChannelHandler`, (中文(简体) ), `WelcomeHandler`, (中文(简体) ), `ThreadStartHandler`· ; `Thread`; 数据 `PlatformAdapter` 边界类型(`RunRenderer`, (中文(简体) ), `IngressSink`, (中文(简体) ), `IncomingTurn`, (中文(简体) ), `InteractionEvent`, (中文(简体) ), `IncomingCommand`, (中文(简体) ), `IncomingWelcome`, (中文(简体) ), `IncomingThreadStart`, (中文(简体) ), `SurfaceCapabilities`, (中文(简体) ), `ReplyTarget`, (中文(简体) ), `ConversationStore`, (中文(简体) ), `AgentSession`, (中文(简体) ), `CapturedToolCall`, (中文(简体) ), `CapturedInterrupt`, (中文(简体) ), `UserQuery`(三); `ActionStore` 编号 : `InMemoryActionStore` 编号 : `ActionSnapshot` 编号 : `ActionRegistry` 编号 : `ActionExpiredError`· ; `ChannelTool` 编号 : `ChannelToolContext` 编号 : `defineChannelTool` 编号 : `ChannelCommand` 编号 : `CommandContext` 编号 : `CommandSpec` 编号 : `defineChannelCommand` 编号 : `ContextEntry` 编号 : `AgentToolDescriptor` 编号 : `ObjectSchema` 和工具辅助工具 (单位:千美元)`toAgentToolDescriptors`, (中文(简体) ), `parseToolArgs`, (中文(简体) ), `stringifyHandlerResult`(三); `mintId` 编号 : `stableStringify`· ; `runAgentLoop`;加上再出口 `@copilotkit/channels-ui` 词汇.

## 常见问题

### @copilotkit/channels-core 是什么？

用于CopilotKit的平台-不可知JSX频道引擎\(创建Channel,Thread,PlaendAdapter,ActionStore\)\.

### 如何安装 @copilotkit/channels-core？

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

### @copilotkit/channels-core 支持 TypeScript 吗？

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

### @copilotkit/channels-core 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @copilotkit/channels-core 可以商用吗？

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

### @copilotkit/channels-core 的下载量有多少？

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

### @copilotkit/channels-core 还在维护吗？

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