# @connectifi/agent-web 中文文档

规范地址：https://npmcn.com/package/%40connectifi/agent-web/

版本：3\.1\.103
npm 元数据更新时间：2025-08-12T13:09:57.002Z
中文译文更新时间：2026-11-10T15:37:02.083Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：665 kB，27 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2022-09-08T13:16:06.875Z
- 最新版本发布：2025-08-12T13:09:56.724Z
- 近 30 天下载量：41589（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：170（近 12 个月 0 个）

## 中文简介

连接ifi 代理的简单网络执行

## 安装

```sh
npm install @connectifi/agent-web
```

也可以使用：`pnpm add @connectifi/agent-web`、`yarn add @connectifi/agent-web`、`bun add @connectifi/agent-web`

## README

# 连接ifi - 代理网络

这个模块为所有网络客户端,包括桌面集成平台,electronjs,和香草浏览器提供了Connefi代理的基本执行. 它会与任何 [Connectifi 互通服务](https://connectifi.co/) 端点并暴露一个被瞄准的FDC3 api. 默认情况下,代理将生成UX用于标准界面函数,如取色和意向解析等. 也可以是无头跑.

## 装入

在您的应用程序中安装模块 :

```bash
npm i @connectifi/agent-web
```

包含在您的捆绑中

```ts
import {createAgent} from '@connectifi/agent-web';
```

要绕过捆绑,您也可以从 unpkg.com 中加载代理并直接用作脚本模块 :

```html
<script type="module" >
  import { createAgent } from "https://unpkg.com/@connectifi/agent-web/";

  createAgent(
        `https://[ME].connectifi.app`,
        `$[appName]@$[directoryName]`,
      )
      .then((fdc3) => {
          // do fdc3 things...
      });
</script>

```

## 使用量

该模块暴露出一个单一功能: _创建代理_ 返回一个以标准解决的承诺 [FDC3 2.0 API (英语)](https://fdc3.finos.org/docs/api/ref/DesktopAgent) (Desktop Agent)在成功连接到指定的接口服务后. 该函数需要3个参数:

-   _间歇_ - Connectifi服务的 URL 该应用程序的目标
-   _应用_ - FDC3应用软件 **必须** 格式为 _应用程序Name_@_目录Name_ (见下文安全模式)
-   _配置_ - 代理的可选配置,包括下列道具:
    -   _日志_ - 用于记录代理输出的回调功能
    -   _无头_ - 无头模式运行代理的布尔旗(它只会连接并曝光FDC3 API)
    -   _道具_ - 为代理人配置UI的属性集合
        -   _图标Src_ - 覆盖标志图像

**说明**: 如果您需要 FDC3 1.2 界面, 您可以使用 [1.3.2版本](https://www.npmjs.com/package/@connectifi/agent-web/v/1.3.2) 本单元.

简单创建示例

```ts

    const fdc3Session = await createAgent('https://platform.connectifi.app, 'myApp@myDirectory');

    //then use the standard FDC3 api
    const listener = await fdc3Session.addContextListener('fdc3.instrument', handleContext);

```

使用日志的示例

```ts
const logThat = (...params: any) => {
  console.log('logThat', ...params);
  const paramString = [...params].reduce((acc, p) => {
    acc += ` ${typeof p === 'object' ? JSON.stringify(p) : p}`;
    return acc;
  });
  const newLog = `${new Date().toISOString()} - ${paramString}`;
  setLogs((prevLogs) => [...prevLogs, newLog]);
};

const fdc3Session = await createAgent(
  'https://platform.connectictifi.app',
  'myApp@myDirectory',
  {logger: logThat}
);

//then use the standard FDC3 api...
```

设置自定义标志的示例

```ts
const fdc3Session = await createAgent(
  'https://platform.connectifi.app',
  'myApp@myDirectory',
  {
    props: {
      logoSrc: 'https://mylogo.png',
    },
  }
);

//then use the standard FDC3 api...
```

**注释 :** 如果设置自定义标识,如果该标识是:

-   超过 HTTPS
-   平方圆
-   png 格式
-   透明背景的白色/ 灯光

## 与现有的FDC3模式相结合

通过FDC3 API的范围界定,Connectifi代理提供了典型的FDC3功能的超集. 支持桌面容器使用的FDC3全球模式也很简单.

### 创建 fdc3 全球对象

```ts
const fdc3Global = async () => {
  //create the agent and assign to the window
  window.fdc3 = await createAgent(
    'https://platform.connectifi.app',
    'myApp@myDirectory'
  );

  //fire the fdc3Ready event
  document.dispatchEvent(new CustomEvent('fdc3Ready', {}));
};
```

### 装入预装

使用上述代码,在任何以Electronjs为主的项目中将全球宣言作为预装脚本进行包装就简单了.

## 与 fdc3 全球实例连接

设置时 `bridgeGlobal` 配置旗为真,代理将与其环境中全球公布的FDC3对象相接. 沟通行为将:

-   如果一个连接系统/用户频道被加入或离开,桥将加入或离开同一id的全球系统/用户频道(如果存在的话)
-   如果通过当前连接的信道收到上下文, 桥将执行 `fdc3.broadcast` 在同样背景下的全球化问题
-   若为 `raiseIntent` 或者说 `raiseIntentForContext` 在Connefi范围内,代理也会从FDC3全球环境中获得相关的意向,并在解析器中显示为"本地"意向.

**注释 :** 这个特征是一个在进行中的工作,行为的细微变化将继续与支持在不同FDC3环境中的桥梁相伴而来.

## 自定义代理

Connectifi代理可以使用传入构造器的配置对象完全定制. 这个 _代理图形_ 接口 :

```ts
export interface AgentConfig {
  props?: FabProps;
  headless?: boolean;
  logLevel?: LogLevel;
  bridgeGlobal?: boolean;
  logger?: (...params: any) => void;

  onFDC3Ready?: (fdc3: DesktopAgent) => void;
  onSessionStarted?: (directory: DirectoryProps, username?: string) => void;
  onSessionError?: (errorMessage: string) => void;
  onSessionAuthRequired?: (directory: DirectoryProps) => void;
  onSignedIn?: (username: string) => void;
  onSignedOut?: () => void;
  onChannelJoined?: (channelId: string) => void;
  onChannelLeft?: () => void;
  onConnected?: (initialConnect: boolean) => void;
  onDisconnected?: (nextConnect?: number) => void;
  onWorkingChanged?: (workInProgress: boolean) => void;
  handleIntentResolution?: (
    message: IntentResolutionMessage,
    callback: ResolveCallback,
    closeCallback: CloseCallback,
  ) => void;
  handleOpen?: (message: ConnectifiOpenMessage) => void;
}
```

-   道具
    -   这些是配置代理提供的默认 " FAB " UX 的 UI 特性( 参见 _UI 推进_ (见下文)
-   无头
    -   如果设置为 _真实_ - 代理商不会提供默认UI.
-   日志级别
    -   记录可以设置为“ 调试 ” 、“ info” 或“ silent”
-   全球桥梁
    -   实验特性: 如果设置为 _真实_ - 代理将附加在 window.fdc3 对象上(例如如果运行在桌面容器中), 并加入到其中, 以便意图解析和播放上下文 .
-   日志
    -   指定用于输出日志语句的自定义函数.

### UI 推进

```ts
logoSrc?: string;
position?: ValidPositions;
loginStyle?: LoginStyles;
```

-   标志Src - 为 FAB 中显示的标志定义自定义位置
-   位置 - 'tl', 'ml', 'bl', 'r', 'm', 或 'br' 。 将 FAB 定位在屏幕的上、下、中、右/左/中.

### UI 回调

```ts
  logger?: (...params: any) => void;
    
  onFDC3Ready?: (fdc3: DesktopAgent) => void;
  onSessionStarted?: (directory: DirectoryProps, username?: string) => void;
  onSessionError?: (errorMessage: string) => void;
  onSessionAuthRequired?: (directory: DirectoryProps) => void;
  onSignedIn?: (username: string) => void;
  onSignedOut?: () => void;
  onChannelJoined?: (channelId: string) => void;
  onChannelLeft?: () => void;
  onConnected?: (initialConnect: boolean) => void;
  onDisconnected?: (nextConnect?: number) => void;
  onWorkingChanged?: (workInProgress: boolean) => void;
  handleIntentResolution?: (
    message: IntentResolutionMessage,
    callback: ResolveCallback,
    closeCallback: CloseCallback,
  ) => void;
  handleOpen?: (message: ConnectifiOpenMessage) => void;

```

#### 手提式自动解析

当一个模棱两可的意向结果列表被推向了应用程序,供终端用户解决时,就叫作这个. 调用后将获得IntentSecretMessage的数据结构,同时提供调用后调用(ResolveCallback),当一个用户在应用程序上选择了解决用意的调用.

```tsx
export interface IntentResolutionMessage {
  resolutionType: ResolutionType;
  context: Context;
  data: AppIntentResult | AppIntentResult[];
  bridgeData?: AppIntent | AppIntent[];
}
```

意图解析信息具有以下属性:

-   分辨率Type - " intent-resolver " 或 " context-resolver " 取决于分辨率是否来自 _**********意图**********_ 或者说 ************提高关联性************ 电话.
-   上下文 - FDC3 与意图相关的上下文对象
-   数据 - 单一结果(\`intent-resolver'类型)或结果清单(\`context-resolver')。 见 _应用程序结果_ 见下文.
-   bridgeData - 一个可选结果集,来自已桥接的 fdc3 全球背景( Desktop Agent) 如果 _全球桥梁_ 属性设定为真实。 见 _应用程序结果_ 见下文.

************应用程序结果************

```ts
export interface AppIntentResult {
  intent: IntentMetadata;
  apps: Array<ConnectifiAppMetadata>;
}
```

```ts
export interface ConnectifiAppMetadata extends AppMetadata {
  type: IntentResultType;
  id: string;
  url: string;
  instanceTitle: string;
  intents: Array<ConnectifiAppIntent>;
  proximity: number;
  useragent: string;
  browser?: string;
  device?: string;
  os?: string;
  lastUpdate: number;
}
```

AppIntentResult将标准FDC3 IntentMetadata类型与ConnectifiAppMetadata类型组合起来. (即意图与应用结果相匹配). 这个 _连接ifiAppMetadata 数据_ type 是标准 FDC3 AppMetadata 类型的扩展,它提供了一些额外的属性,用于帮助用户在应用程序间分解. 例如:

-   相近 - 从0开始 - 从启动解析器的应用程序中显示相对设备和应用相近的编号. 例如,如果目标应用在同一个设备上,并且运行在与发起者相同的应用程序(如Chrome)中,相近为0. 评分的用意是帮助对列表进行排序,顺序是最接近用户当前工作的后方的应用程序.
-   浏览器 - 应用程序运行中的浏览器类型指标
-   设备 - 应用程序运行的设备指示器
-   os - 应用程序运行的OS 指示器
-   用户代理 - 应用程序的原始用户代理字符串

#### 频道

加入频道时调用 。 争论是 **编号** 已连接.

#### 频道左侧

离开时调用 CurrentChannel 执行 。 即用户离开当前频道但不加入另一个频道.

#### 打开

后调用 _[fdc3. 打开](http://fdc3.open/)_ 或者一个意图解决。 在此情况下,服务会向客户端发送信息,请求其启动特定应用. 消息格式如下:

```ts
export interface ConnectifiOpenMessage {
  name?: string;
  url?: string;
  pendingId: string;
}
```

何处 _名称_ 是目录中应用程序的名称, _url 密码_ 是启动的url(用于网络应用程序),以及 _待决文件_ 是非ce,可以让新推出的应用程序检索任何预期意图/文本数据。 注:名称和url是可选的,取决于所推出的应用程序的类型.

一个典型的手柄 Open 看起来像这样:

```ts
const handleOpen = (message : ConnectifiOpenMessage ) => {
     if (data.url && data.pendingId) {
        window.open(data.url, data.pendingId as string);
      }
}
```

此处注意使用 **********待决文件********** 作为 _名称_ 用于新窗口 - 这是 Agent 拾取的会话 - 它会自动使用窗口的名称来获取新应用程序的待处理状态 。 其他模式可以并且将会被用于非浏览器客户端. 另请注意,对于大多数浏览器 [_窗口。打开_](http://window.open/) 电话必须足够接近最终用户点击工作。 因此,如果你正在构建没有机会让终端用户在应用程序启动前点击某个东西的工作流程 - 您需要在浏览器的流程中构建一些机制(向用户介绍链接等) .

#### 工作报告草稿 已更改

代理开始或停止"工作"或"忙"时打电话. 布尔参数是当前状态.

#### 签名

在用户成功签入目录后调用. 将传递用户名/ 标识符作为参数 .

#### 已签名

用户签名后呼叫.

#### 已连接

当套接字连接建立时调用 .

#### 已断开

当套接字连接被丢弃时调用 。 将会通过自动重联时间(以毫秒计)作为参数.

#### 会议开始

当连接ifi代理已建立与服务和目录的会话时调用 .

#### 会议

当连接ifi代理无法为服务和目录建立会话时调用 。 错误消息会显示是哪个 。 这是一个致命的错误.

#### 会议授权

当用户无法连接到目录时调用, 因为无法认证 。 传出目录名称作为参数.

#### 错误

当用户无法连接到目录时调用, 因为无法认证 。 传出目录名称作为参数.

## 处理连接状态

Connectifi被设计为在包括移动设备在内的任何地方运行,其中连接中断是常见的. 该代理公司为缓解潜在的连接问题提供了一些工具.

### 自动重接

如果连接被丢弃,代理将自动管理重联. 在默认的 UI 中, Toast 也会向终端用户建议连接状态和任何再连接尝试.

### 连接出错

使用FDC3 2.0,所有FDC3 API都是Async. 与 Connectifi 连接, 任何 API 呼叫, 以类型错误拒绝连接 `ConnectionError.NoConnectionAvailable`。这个错误可以处理并用来触发对用户的通知、记录和/或关键事件的排队.

### 在Connect / 在断线回调中

以上概述的这些回调可以用来在连接状态周围创建自定义 UX. _注:_ 无法提供这些设备来管理重新连接的逻辑,因为代理商自己负责

## 警卫

代理机提供全码隔离,并自身安全连接回服务端. 一个代理连接到控制接口安全配置的目录 。 有3个基本安全级别:

-   _打开_ - 任何应用程序都可以连接到端点 - 这只推荐给开发.
-   _应用_ - 必须验证一个应用程序的身份并将其注册到目录上才能连接.
-   _严格_ - 应用程序的身份必须有效,属于目录,用户必须经过认证才能连接.

这一模式允许在参与互通的对应方不易受到偷窥、跨站点描述攻击和未经授权的应用程序进入桌面总线的数据泄漏时,提供强有力的安全.

## 解决问题

Connectifi是完全的网络,所以所有相同的工具和方法,你用来排除一个Webapp申请代理. 登录员回调还可以为检查和诊断客户端上的任何问题提供更大的灵活性. 一些基准项目需要检查是否与代理人有问题:

-   接口服务的 URL 是否正确 ?
-   您是否有正确的( 对大小写敏感) 和完全合格的 _应用程序Name @ directoryName_ 您正在连接的目录的标识符 ?
-   您的应用程序在目录中注册了吗 ? 注册来源是否与您正在连接的来源相匹配 ?
-   你在用那个吗 [FDC3 2.0 API (英语)](https://fdc3.finos.org/docs/api/ref/DesktopAgent) 在你的应用程序?

## 下一步

如果你还没和康涅菲合作 我们想听听你的消息 请给我们留言 [信息@ connectifi.co](mailto://info@connectifi.co)。 。 。 .

接下来我们给特工的路线图是:

-   本地客户端和语言支持
-   默认 UX 的更多改进
-   UX 更大的配置性

## 常见问题

### @connectifi/agent-web 是什么？

连接ifi 代理的简单网络执行

### 如何安装 @connectifi/agent-web？

在项目目录运行 npm install @connectifi/agent-web，或使用 pnpm add / yarn add / bun add。

### @connectifi/agent-web 支持 TypeScript 吗？

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

### @connectifi/agent-web 支持 ESM 还是 CommonJS？

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

### @connectifi/agent-web 可以商用吗？

@connectifi/agent-web 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @connectifi/agent-web 的下载量有多少？

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

### @connectifi/agent-web 还在维护吗？

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