# @corto-ai/integrations-messenger 中文文档

规范地址：https://npmcn.com/package/%40corto-ai/integrations-messenger/

版本：0\.0\.12
npm 元数据更新时间：2026-11-04T02:47:51.035Z
中文译文更新时间：2026-11-10T20:02:01.888Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40corto-ai/integrations-messenger
原文对照：https://npmcn.com/package/%40corto-ai/integrations-messenger/?lang=original

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

- 包体积（解压后）：137 kB，159 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-06-04T21:39:36.342Z
- 最新版本发布：2026-11-04T02:47:50.868Z
- 近 30 天下载量：10465（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：35（近 12 个月 35 个）

## 中文简介

`@corto-ai/integrations-messenger` 为主机应用程序和嵌入式集成之间的通信提供消息服务.

## 安装

```sh
npm install @corto-ai/integrations-messenger
```

也可以使用：`pnpm add @corto-ai/integrations-messenger`、`yarn add @corto-ai/integrations-messenger`、`bun add @corto-ai/integrations-messenger`

## README

# @corto-ai/整合信使

`@corto-ai/integrations-messenger` 为主机应用程序和嵌入式集成之间的通信提供消息服务.

此软件包目前处于早期开发阶段并正在被发布到npm,以支持内部/dev工作流程.

## 预定用途

这个软件包的用意是为团队在CORTO平台上添加应用程序(例如基于iframe的集成).

## 状态

-   早期发展
-   API 在 dev 发布之间可能更改
-   文件将逐步扩充

## 安装

```bash
npm install @corto-ai/integrations-messenger
```

## 能力

-   **握手身份( I)** - 每一个窗口(主机或集成)都有独特的注册 `id`. Nested 窗口自动与他们的家长握手,这样在任何动作发出前双方都知道他们和谁说话.
-   **原始消息检查** - 一旦握手完成,特定来源的信息只有在来自在握手期间观察到的源头时才会被接受,防止来自出乎意料的源头的信息.
-   **请求/答复行动** -- 为以下动作打入的助手,每个助手都有: `send{{Action}}` (呼叫方)和 `handle{{Action}}` (执行方)一收到匹配的响应就解决的对子.
-   **流程/pubsub通知** - 基于频道的通知动作,可以反复发送或处理,有助于随着时间的推移推动多个更新,而不是单一的请求/答复.
-   **跨嵌入式框架自动转发** - 如果一个窗口没有为动作注册的处理器,则消息会自动向上/向下传输到iframe树上,所以多层次的嵌入不需要每个关卡来执行每个动作.
-   **可选调试日志** - 通过 `withLogging: true` 改为 `init` 在整合时记录握手和向控制台传递活动.

## 使用量

### 初始化

每个使用此软件包的窗口 -- -- 主机和嵌入式集成都一样 -- -- 必须调用 `init` 第一条:

```ts
import messenger from '@corto-ai/integrations-messenger';

await messenger.init({ id: 'my-integration-app' });
```

-   `id` 需要并且必须是窗口调用的唯一 `init`。 。 。 .
-   `parentRef` 是可选的,默认为 `window.parent`。只有在页面没有与其直接父端通信的情况下,才会覆盖它.
-   `withLogging` 可选,并允许控制台日志用于调试握手/留言流.
-   如果窗口被嵌入( 它) `parentRef` 没有 `window` 本身, `init` 还踢出与父母的握手. `init` 一旦设置完成,就解决;与父手握手会同步完成.

在 Iframe 中嵌入集成物的主机应用程序也必须调用 `registerChild` 并提到iframe的 `contentWindow` 和同样的 `id` 儿童传给 `init`数字 :

```ts
messenger.registerChild(iframe.contentWindow, 'my-integration-app');
```

`registerChild` 听听那个孩子的握手声 一旦完成就决定了 在Iframe自己之前叫它吧 `init` 呼叫运行,否则握手可能会被错过.

### 行动

`messenger.actions` 所有支持的实体/流动的行动都影响到:

| 组 | 行动 | 说明 |
| --- | --- | --- |
| `matter` | `sendOpenMatter` 编号 : `handleOpenMatter` | 打开一个问题 `matterId`。 。 。 . |
| `matter` | `sendOpenChatSession` 编号 : `handleOpenChatSession` | 打开一个特定的聊天会话( O)`sessionId`) 关于一个问题. |
| `matter` | `sendOpenAgentSession` 编号 : `handleOpenAgentSession` | 打开特定的代理会话( O)`sessionId`) 关于一个问题. |
| `matter` | `sendOpenDetails` 编号 : `handleOpenDetails` | 打开细节视图 . |
| `matter` | `sendOpenEdit` 编号 : `handleOpenEdit` | 打开一个事项的编辑视图. |
| `matter` | `sendOpenDocumentStatus` 编号 : `handleOpenDocumentStatus` | 为某个事项打开文档状态视图. |
| `matter` | `sendOpenPrompt` 编号 : `handleOpenPrompt` | 打开一个特定的提示 (E)`promptId`) 关于一个问题. |
| `matter` | `sendOpenPromptLibrary` 编号 : `handleOpenPromptLibrary` | 打开快取库处理一个事项 . |
| `matter` | `sendPreviewDocument` 编号 : `handlePreviewDocument` | 预览文档 `documentId` 或者说 `presignedUrl`。 。 。 . `documentName` 需要时间. |
| `matter` | `sendSetFullscreen` 编号 : `handleSetFullscreen` | 显示/隐藏物质导航和列表. 在主机应用程序中自动清除导航 |
| `contact` | `sendOpenContact` 编号 : `handleOpenContact` | 打开联系人 `contactId`。 。 。 . |
| `contact` | `sendOpenEditContact` 编号 : `handleOpenEditContact` | 打开联系人的编辑视图. |
| `settings` | `sendOpenSettings` 编号 : `handleOpenSettings` | 打开主机应用程序的设置 . |
| `branding` | `sendGetBranding` 编号 : `handleGetBranding` | 请求活动品牌和标志 URL, 或通过可选选项 `brandName` 以请求特定品牌代替活动品牌. |
| `auth` | `sendExchangeTokenRequest` 编号 : `handleExchangeTokenRequest` | 交换a `clientId` 为了一个认证的标志. |
| `auth` | `sendUserDataRequest` 编号 : `handleUserDataRequest` | 向主机请求当前用户的数据( 目前返回) `userId`) (中文(简体) ). |
| `pubsub` | `sendNotificationRequest` 编号 : `handleNotificationRequest` | 订阅(或公布)a `channel`,支持随时间推移的多个响应. |
| `pubsub` | `sendStatusRequest` 编号 : `handleStatusRequest` | 订阅主机信号R中枢连接状态( S)`Connected`, (中文(简体) ), `Reconnecting`, (中文(简体) ), `Disconnected`,而其他枢纽州. |
| `window` | `sendUpdateUrl` 编号 : `handleUpdateUrl` | 更新主机应用程序中的 URL _不导航_. 用于支持集成内部的路由/更新 |
| `window` | `sendOpenModal` 编号 : `handleOpenModal` | 打开一个可以用于托管集成iframes的模式覆盖. 添加给根目标源的路径. |
| `window` | `sendCloseModal` 编号 : `handleCloseModal` | 关闭先前打开的以 `sendOpenModal` 命令 |
| `window` | `sendOpenConfirmation` 编号 : `handleOpenConfirmation` | 打开确认对话框。 支持自定义 `title`, (中文(简体) ), `message`, (中文(简体) ), `confirmLabel`,以及 `cancelLabel`,并返回用户是否确认. |
| `window` | `sendOpenToast` 编号 : `handleOpenToast` | 打开祝酒词作为 `success`, (中文(简体) ), `error`, (中文(简体) ), `info` 或者说 `warning` 类型。 支持自定义 `title`, (中文(简体) ), `message`,以及 `override` 到详细配置。 点击动作按钮时,会返回回复. |
| `window` | `sendSetUnsavedChanges` 编号 : `handleSetUnsavedChanges` | 在父应用程序上设置标记。 当真实时, 如果用户试图导航或关闭标签, 我们将弹出一个确认模式, 它将连接导航并允许用户取消 |
| `integrations` | `sendGetList` 编号 : `handleGetList` | 返回与主机应用程序集成的集成 ID、 标签和 appName 列表 。 拟与 `integrations.sendOpen` 以触发一个集成 |
| `integrations` | `sendOpen` 编号 : `handleOpen` | 打开所提供的集成。 确定同一背景(ex/Global - > Global, matter - > matter)的优先顺序,如果未提供任何物质,则从Global - > matter中导航时失败。 通过的任何参数 `extraParams` 将在目标集成的url中附加. |

全体 `matter`, (中文(简体) ), `contact`,以及 `settings` 动作接受可选 `newTab` 显示主机的旗帜应在新标签中打开目标,以及 `matter` 动作还接受可选 `matterId` 超越上面所说的.

对于每项行动 `send...` 函数用于嵌入式集成调用,请主机应用程序执行一些动作或返回一些数据。 匹配 `handle...` 函数意在由主机应用程序执行:它注册一个接收请求的回调,并返回要发送的回调.

```typescript
// in the host application
await messenger.init({ id: 'host' });

messenger.registerChild(iframe.contentWindow, 'child');

messenger.actions.matter.handleOpenChatSession(async ({ matterId, sessionId }) => {
  try {
    await someService.openSession(matterId, sessionId);
    return { success: true };
  } catch (err) {
    return { success: false, error: err.message };
  }
});

// in the embedded integration
await messenger.init({ id: 'child' });

const response = await messenger.actions.matter.sendOpenChatSession({
  matterId: '123',
  sessionId: 'abc'
});

if (response.success) {
  // happy path
} else {
  // sad path
}
```

#### 流动( pubsub)

`pubsub` 通知与其他行动不同:而不是一次以单一答复解决, `sendNotificationRequest` 财务报告和审定财务报表 `handleNotificationRequest` 能够多次为同一人发回电 `channel`,两个都用 `remove()` 函数以停止监听.

```typescript
// listen for notifications on a channel
const handle = messenger.actions.pubsub.sendNotificationRequest({ channel: 'documents' }, (notification) => {
  console.log('received', notification.data);
});

// later, stop listening
handle.remove();

const statusHandle = messenger.actions.pubsub.sendStatusRequest(({ status }) => {
  console.log(status);
});

statusHandle.remove();
```

#### 模块通信

如上文所述 `window.sendOpenModal` 命令允许集成触发模式上覆并显示其应用程序中的自定义模式。 值得一提的是,这一新模式 **无法与父应用程序联系**相反,Modals应与其兄弟之间的融合(即打开模式的融合)通过 [广播频道API](https://developer.mozilla.org/en-US/docs/Web/API/Broadcast_Channel_API)。这样,他们就可以通知兄弟们可能需要的用户互动,包括关闭模式.

### 转发

为了支持多层次的iframe筑巢,包内固有的有一个"前向"的机械师:对于任何动作,如果在给定的窗口中没有定义处理器,则消息会继续上下到iframe树上取. 这是默认启用的, 不需要选入 .

在孩子应用程序中添加处理器可以阴影同一动作在父应用程序中的处理,因为只有在处理器没有定义时才会转发. 如果你不确定你是否应该为某个动作执行一个处理器,不要——让它转发给主机.

## 演示仓库

我们已经建立了一个 [演示仓库](https://bitbucket.org/docorto/developer-integration-demo/src/develop/) 作为如何使用此软件包的例子.

## 发展

这个库由CORTO维护,并作为常规软件包发布工作流程的一部分发布.

详情请访问 [https://www.docorto.ai 互联网档案馆的存檔,存档日期2011-12-02](https://www.docorto.ai/)。 。 。 .

## 许可证

许可证细节将记录在这一软件包向稳定释放方向移动时.

## 常见问题

### @corto-ai/integrations-messenger 是什么？

@corto-ai/integrations-messenger 为主机应用程序和嵌入式集成之间的通信提供消息服务\.

### 如何安装 @corto-ai/integrations-messenger？

在项目目录运行 npm install @corto-ai/integrations-messenger，或使用 pnpm add / yarn add / bun add。

### @corto-ai/integrations-messenger 支持 TypeScript 吗？

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

### @corto-ai/integrations-messenger 支持 ESM 还是 CommonJS？

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

### @corto-ai/integrations-messenger 可以商用吗？

@corto-ai/integrations-messenger 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @corto-ai/integrations-messenger 的下载量有多少？

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

### @corto-ai/integrations-messenger 还在维护吗？

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