# @copilotkit/bot 中文文档

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

版本：0\.1\.0
npm 元数据更新时间：2026-07-08T20:45:16.296Z
中文译文更新时间：2026-11-10T22:20:38.375Z
软件包许可：MIT

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

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

弃用说明：Renamed — install @copilotkit/channels instead\.

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

- 包体积（解压后）：299 kB，150 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：6 个
- 首次发布：2026-06-10T20:10:59.974Z
- 最新版本发布：2026-06-26T21:30:56.871Z
- 近 30 天下载量：2594（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

用于CopilotKit的平台-不可知JSX机器人引擎(创建Bot,Thread,平台Adapter,ActionStore).

## 安装

```sh
npm install @copilotkit/bot
```

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

## README

# @ copilotkit/ boot (英语)

这个 **平台不可知的机器人引擎**。它拥有所有的东西在一个进货之间 电文和提供的答复——管理人登记、代理人 运行/工具/中断循环, JSX 动作绑定,以及 `PlatformAdapter` 合同——对Slack(或任何其他地表)一无所知。 A 类 边界处的平台适配器插件; `@copilotkit/bot-slack` 这是 混凝土一.

其基础是 `@copilotkit/bot-ui` (JSX运行时间+组件词汇, 为方便起见从这里再出口)和AG-UI(`@ag-ui/client`, (中文(简体) ), `@ag-ui/core`) (中文(简体) ).

## 安装

```sh
pnpm add @copilotkit/bot @copilotkit/bot-ui
# plus a platform adapter, e.g.
pnpm add @copilotkit/bot-slack
```

## 快速启动

```ts
import { createBot } from "@copilotkit/bot";
import { slack } from "@copilotkit/bot-slack"; // a concrete PlatformAdapter

const bot = createBot({
  adapters: [slack({ botToken, appToken })],
  agent: (threadId) => makeAgent(threadId), // AbstractAgent or (threadId) => AbstractAgent
  tools: [...myTools], // BotTool[] forwarded on every runAgent
  context: [...myContext], // ContextEntry[] forwarded on every runAgent
});

bot.onMention(({ thread }) => thread.runAgent());
bot.onMessage(({ thread }) => thread.runAgent());

await bot.start();
```

`createBot(opts)` 返回 a `Bot`数字 :

-   `onMention(handler)` 编号 : `onMessage(handler)` - 接收转弯处理器 `{ thread, message }`. (提及首选:如果提及 处理器已注册, 全部转换路径; 否则信件处理器 开火。 )
-   `onThreadStarted(handler)` - 对话表面打开(例如Slack) 辅助窗格; 接收 `{ thread, user? }`。问候,设置提示 或标题,或运行代理。 没有概念的适配器从不发射.
-   `onInteraction<TValue>(id, handler)` - 明确的越狱操作员 已知行动编号,绕过登记册; `ctx.action.value` 输入 `TValue`。 。 。 .
-   `onInterrupt<TPayload>(eventName, handler)` 处理被俘的特工 中断( LangGraph 风格) `on_interrupt`; 获得 `{ payload, thread }` 与 `payload` 类型 `TPayload`。 。 。 .
-   `onCommand(command)` 编号 : `onCommand(name, handler)` 登记斜线命令. 处理者得到 `{ thread, command, text, options, user }`。 。 。 . `text` 这是 生rg; `options` 是已键入,解析的窗体(`defineBotCommand` 带有 `options` 标准Schema),用于有原生结构的地表 (如"迪斯克". 转发到支持命令并忽略的适配器 在其他地方——也通过前方 `commands` 内 `CreateBotOptions`。 。 。 .
-   `tool(t)` 登记a `BotTool` (备选案文: `opts.tools`(必须如此) 之前添加 `start()`。 。 。 .
-   `start()` 编号 : `stop()` ——把适配器抬上/下.

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

## `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?: BotTool[];
  }): Promise<MessageRef | undefined>;
  resume(value: unknown): Promise<MessageRef | undefined>;
  awaitChoice<T = unknown>(ui: Renderable): 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` 仅用于该运行的bot 级别默认值之上合并.
-   `resume(value)` 重新进入中断运行 `forwardedProps.command`。 。 。 .
-   `awaitChoice<T>(ui)` 在此插入一个拾取器并块到交互 对话框将它解决到被点击的控件值( HITL); 通过 `T` 改为 键入返回的值.

## 工具上下文( C)

A 类 `BotTool` 作为前端工具转发给代理;其处理器运行于 代理称它为"机器人" 处理者 `ctx` 携带 `thread`,所以一个 工具可以使 JSX (`ctx.thread.post(<Card .../>)`)或运行代理进一步.

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

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

```ts
defineBotTool({
  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和 回来的路上验证过了. `BotToolContext` 实值 `{ thread, message?, user?, signal?, platform }` ——一个单一的共享类型,没有每个适应器通用. 仅通过能力配置实现平台专用电能 `thread` 方法(例如:. `thread.getMessages()`, (中文(简体) ), `thread.lookupUser(query)`, (中文(简体) ), `thread.postFile(...)`),所以一个工具在平面上保持可移植.

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

## 动作系统

内部JSX处理者受内容约束. 每个交互式节点都有一个 **内容稳定、不透明** 薄荷id - `mintId(componentName, path, props)` =: `"ck:" + sha1(name | path | stableStringify(props)).slice(0,16)`只有 不透明代号(加上任何小 `bind()` (ags) 印有当地标志;否 道具,PII,或秘密通过线.

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

默认 `ActionStore` 实值 `InMemoryActionStore` 联合国 `Map` 可选 (原始内容存档于2018-10-21). TTL. 它在重启时丢失:在重启后,单击旧按钮可降解为 a 一个 `ActionExpiredError` (“此动作已过期 ” ) `createBot` swallow. **持久动作需要外部存储( 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` (收到 `BotNode[]` 转换成原生有效载荷 `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.onThreadStarted(...)` 发出"对话" 打开"生命周期事件。 Slash 命令也带有容量: 适配器向前 通过 `sink.onCommand(IncomingCommand)`,并可能执行 `registerCommands(specs)` 在前面公布机器人宣布的命令 (例如Discord的应用程序命令 API);省略的适配器被跳过. 见 `@copilotkit/bot-slack` (c) 全面执行《公约》.

## 出口

`createBot`, (中文(简体) ), `Bot`, (中文(简体) ), `CreateBotOptions`, (中文(简体) ), `BotHandler`, (中文(简体) ), `ThreadStartHandler`· ; `Thread`; 数据 `PlatformAdapter` 边界类型(`RunRenderer`, (中文(简体) ), `IngressSink`, (中文(简体) ), `IncomingTurn`, (中文(简体) ), `InteractionEvent`, (中文(简体) ), `IncomingCommand`, (中文(简体) ), `IncomingThreadStart`, (中文(简体) ), `SurfaceCapabilities`, (中文(简体) ), `ReplyTarget`, (中文(简体) ), `ConversationStore`, (中文(简体) ), `AgentSession`, (中文(简体) ), `CapturedToolCall`, (中文(简体) ), `CapturedInterrupt`, (中文(简体) ), `UserQuery`(三); `ActionStore` 编号 : `InMemoryActionStore` 编号 : `ActionSnapshot` 编号 : `ActionRegistry` 编号 : `ActionExpiredError`· ; `BotTool` 编号 : `BotToolContext` 编号 : `defineBotTool` 编号 : `BotCommand` 编号 : `CommandContext` 编号 : `CommandSpec` 编号 : `defineBotCommand` 编号 : `ContextEntry` 编号 : `AgentToolDescriptor` 编号 : `ObjectSchema` 和工具辅助工具 (单位:千美元)`toAgentToolDescriptors`, (中文(简体) ), `parseToolArgs`, (中文(简体) ), `stringifyHandlerResult`(三); `mintId` 编号 : `stableStringify`· ; `runAgentLoop`;加上再出口 `@copilotkit/bot-ui` 词汇.

## 常见问题

### @copilotkit/bot 是什么？

用于CopilotKit的平台-不可知JSX机器人引擎\(创建Bot,Thread,平台Adapter,ActionStore\)\.注意：该包已被作者标记为弃用——Renamed — install @copilotkit/channels instead\.

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

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

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

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

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

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

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

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

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

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

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

最新版本 0\.1\.0 发布于 2026/06/27（4 个月前）；至今共发布 4 个版本，其中过去 12 个月发布了 4 个；首次发布于 2026/06/11。作者已将其标记为弃用，新项目建议寻找替代方案。