# @agent-assistant/connectivity 中文文档

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

版本：0\.4\.37
npm 元数据更新时间：2026-10-04T06:38:17.090Z
中文译文更新时间：2026-11-05T20:39:57.123Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：27 kB，8 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-04-13T20:25:31.211Z
- 最新版本发布：2026-10-04T06:38:16.754Z
- 近 30 天下载量：25326（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：59（近 12 个月 59 个）

## 中文简介

为代理助理SDK输入的流程中连接信号

## 安装

```sh
npm install @agent-assistant/connectivity
```

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

## README

# `@agent-assistant/connectivity`

`@agent-assistant/connectivity` 用于内部助理协调的 v1 进程内信号层。 它提供了一个有界限的信号词汇,验证,压制,生命周期管理,受众分辨率悬钩,以及一个升级悬钩,在不将路由所有权交给本套件的情况下可以执行.

## 范围

此软件包拥有 :

-   峡谷 `ConnectivitySignal` 信封和支持类型Script
-   同步 `emit()` 具有验证、ID任务、时间戳、压制和超会话
-   每个线程的内存信号日志 `get()` 财务报告和审定财务报表 `query()`
-   寿命周期过渡 `resolved`, (中文(简体) ), `superseded`,以及 `expired`
-   对象语义 `self`, (中文(简体) ), `coordinator`, (中文(简体) ), `selected`,以及 `all`
-   通过调用 `onSignal()` 财务报告和审定财务报表 `offSignal()`
-   运通可能执行的升级钩接口

此软件包不拥有 :

-   路径决定或模式应用程序
-   协调员的工作任务或综合政策
-   运输、队列或跨进程交付
-   云遥测或持久性
-   v1 目录以外的产品特定信号类

## 安装形状

软件包为 TypeScript- first 并建为 `dist/`。 。 。 .

```ts
import {
  createConnectivityLayer,
  type ConnectivitySignal,
  type EmitSignalInput,
} from '@agent-assistant/connectivity';
```

## 信号模型

v1包括5个信息类和11个信号类:

-   `attention.raise`
-   `confidence.high`
-   `confidence.medium`
-   `confidence.low`
-   `confidence.blocker`
-   `conflict.active`
-   `conflict.resolved`
-   `handoff.ready`
-   `handoff.partial`
-   `escalation.interrupt`
-   `escalation.uncertainty`

`confidence` 数字并绑定为 `0.0..1.0` 当在现相. 人人都需要这样 `confidence.*` 财务报告和审定财务报表 `conflict.*` 信号,对信任信号类执行特定类别范围:

-   `confidence.high`数字 : `0.8..1.0`
-   `confidence.medium`数字 : `0.4..0.79`
-   `confidence.low`数字 : `0.1..0.39`
-   `confidence.blocker`数字 : `0.0`

可选字段在TypeScript中遵循精确的可选属性语义. 奥米 `confidence`, (中文(简体) ), `details`, (中文(简体) ), `replaces`,以及 `expiresAtStep` 当他们不加以适用,而不加以明确通过的时候 `undefined` 数值.

## 常数

该套件有意将运行时间常数目录与工会类型一起输出:

-   `MESSAGE_CLASSES`
-   `MESSAGE_CLASS_TO_SIGNAL_PREFIX`
-   `SIGNAL_AUDIENCES`
-   `SIGNAL_CLASSES`
-   `SIGNAL_EVENTS`
-   `SIGNAL_PRIORITIES`
-   `SIGNAL_STATES`
-   `TERMINAL_STATES`

这些是预定的v1表面的一部分,因此下游软件包可以共享相同的犬类词汇来进行详尽的检查,切换守卫,以及测试固定装置而无需重复本地阵列.

## 核心 API

### `createConnectivityLayer(config?)`

创建线性记忆层.

```ts
const layer = createConnectivityLayer({
  suppressionConfig: { basis: 'step' },
  routingEscalationHook: {
    onEscalation(signal) {
      if (signal.signalClass === 'escalation.uncertainty') {
        return 'deep';
      }
    },
  },
});
```

### `emit(input)`

创建有效的信号, 指定 `id`, (中文(简体) ), `emittedAt`初始时 `state`,然后将其存储在线程日志中.

关键行为 :

-   验证所需字段和类一致性
-   在配置的压制窗口中压制重复
-   绕过压制 `priority='critical'`
-   当摘要变化时绕过对高优先级升级信号的压制
-   取代目标 `replaces` 在存储新信号之前
-   引用路径升级钩 `escalation.interrupt` 财务报告和审定财务报表 `escalation.uncertainty`
-   火灾 `onSignal(signal, 'emitted')` 同步

### `resolve(signalId)`

将信号移动到 `resolved`它对于已经解开的信号和投出 `expired` 或者说 `superseded` 信号.

### `get(signalId)` 财务报告和审定财务报表 `query(query)`

`get()` 返回单个信号或 `null`。 。 。 . `query()` 读取有过滤器的线程切片,用于源、类、优先级、状态和时间界限。 默认, `query()` 仅返回 `emitted` 财务报告和审定财务报表 `active` 信号.

### `advanceStep(threadId)`

增加线步计数器. 信号 `expiresAtStep <= currentStep` 变成 `expired`,以及 `onSignal(signal, 'expired')` 每人点火.

### `registerSelectedResolver(resolver)`

登记用于 `audience='selected'`。解析器在发射时被引用。 连通性计算观众结果,但不提供或坚持接受者.

### `onSignal(callback)` 编号 : `offSignal(callback)`

登记或删除同步回调,用于:

-   `emitted`
-   `superseded`
-   `resolved`
-   `expired`

如果一个回调投放,错误会被记录下来,以后的回调仍然运行.

## 生命周期和一致性

信号通过 :

```text
emitted -> active -> superseded
                  -> expired
                  -> resolved
```

`active` 至少经过一个 `onSignal` 新发射信号的召回起火。 在v1中同源性会有意地保持轻量级: 包会给予协调它需要的原始人来汇合一线程而无需自己取得协调所有权.

这些原始人是:

-   `replaces` 当一个更新的信号过时了一个更古老的信号时
-   `resolve()` 合并或仲裁后明确关闭
-   `advanceStep()` 加号 `expiresAtStep` 暂时信号
-   `query()` 冲突、升级和当前信任状态

## 取缔

复制检测使用逻辑密钥 :

```text
threadId + source + signalClass + audience
```

复制只当已存在的信号仍然是非终端时才会被压制.

支持的压制模式 :

-   `basis: 'step'` `advanceStep()` 重新设置压制窗口
-   `basis: 'time'` 使用滑动 `windowMs`,默认为 `5000`

## 运行边界

连通性只暴露出本地的路由钩接口:

```ts
interface RoutingEscalationHook {
  onEscalation(signal: ConnectivitySignal): 'cheap' | 'fast' | 'deep' | void;
}
```

钩子类型由 `@agent-assistant/connectivity` 消费者并不需要 `@agent-assistant/routing` 已安装,仅用于输入此软件包。 routing仍然可以执行相同的结构合同. 连接不存储返回模式,不选择路由模式,也不导入路由执行. 钩子是存在的,因此通路可以对升级信号作出反应而不会模糊包的所有权.

## 示例

```ts
import { createConnectivityLayer } from '@agent-assistant/connectivity';

const layer = createConnectivityLayer();

layer.onSignal((signal, event) => {
  console.log(event, signal.signalClass, signal.summary);
});

const confidence = layer.emit({
  threadId: 'thread-42',
  source: 'specialist:reviewer',
  audience: 'coordinator',
  messageClass: 'confidence',
  signalClass: 'confidence.high',
  priority: 'normal',
  confidence: 0.92,
  summary: 'Review completed with stable evidence',
});

layer.emit({
  threadId: 'thread-42',
  source: 'specialist:reviewer',
  audience: 'selected',
  messageClass: 'handoff',
  signalClass: 'handoff.ready',
  priority: 'normal',
  summary: 'Downstream writer can synthesize the reviewed draft',
});

layer.resolve(confidence.id);
```

## 发展

走进去 `packages/connectivity`数字 :

```sh
npm install
npm test
npm run build
```

测试套件涵盖预定的第一个工作流程:

-   收缩注意力
-   审查者冲突
-   专家分发
-   阻塞器不确定路径升级

连接 连接 模拟

## 常见问题

### @agent-assistant/connectivity 是什么？

为代理助理SDK输入的流程中连接信号

### 如何安装 @agent-assistant/connectivity？

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

### @agent-assistant/connectivity 支持 TypeScript 吗？

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

### @agent-assistant/connectivity 支持 ESM 还是 CommonJS？

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

### @agent-assistant/connectivity 可以商用吗？

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

### @agent-assistant/connectivity 的下载量有多少？

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

### @agent-assistant/connectivity 还在维护吗？

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