# @agentcomms/events 中文文档

规范地址：https://npmcn.com/package/%40agentcomms/events/

版本：0\.37\.0
npm 元数据更新时间：2026-10-28T22:09:39.964Z
中文译文更新时间：2026-11-06T09:45:08.407Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40agentcomms/events
原文对照：https://npmcn.com/package/%40agentcomms/events/?lang=original
源码仓库：https://github.com/crissmoldovan/agent-communications

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

- 包体积（解压后）：972 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12\.0
- 运行依赖：1 个
- 首次发布：2026-10-13T14:14:14.246Z
- 最新版本发布：2026-10-28T22:09:39.543Z
- 近 30 天下载量：3520（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：28（近 12 个月 28 个）

## 中文简介

事件目录,条件和绘制了代理-通信本地事件排放的模板:异态,没有I/O和Node导入.

## 安装

```sh
npm install @agentcomms/events
```

也可以使用：`pnpm add @agentcomms/events`、`yarn add @agentcomms/events`、`bun add @agentcomms/events`

## README

# @ agentcomms/ 活动

`@agentcomms/events` 代理- 通讯本地事件排放的同位素库: 1 版本 事件目录、指针模式、语义格式、确定性条件、绘图模板和CloudEvents线条 格式. [事件排放设计附录A](https://npmcn.com/package/docs/superpowers/specs/2026-10-05-local-event-emission-design.md#appendix-a-version-1-event-catalogue-normative) 是它的规范契约.

它没有I/O。 相同的构建在节点和浏览器网页视图中运行, 导入否 `node:` 模块,而不建立网络, 文件系统、时钟或随机呼叫。 保密、不可信内容信封、签名和交货属于 使用此库的守护进程; 此软件包报告源域和映射值来源 .

它与0.1.6.0的每期出版物一起出版 [`@agentcomms/events-daemon`](https://npmcn.com/package/%40agentcomms/events-daemon/README.md),则 使用它的地方服务.

## API 密码

从软件包根导入您需要的棋子 。 桶是完整的支持表面;内部模块是 不公开的API.

### JSON 文本和错误

`canonicalJson` 与核心的犬科JSON相同。 它按 UTF-16 代码单位排序对象密钥, 滴入 `undefined` 对象成员并拒绝使用非 JSON 输入 `EventsError`; 否则返回验证符 `Result<T>` 与 关闭 `IssueCode` 数值.

```ts
import { canonicalJson, codePointLength, isJsonValue } from '@agentcomms/events';

const value = { second: undefined, first: ['é'] };
if (isJsonValue(value)) {
  canonicalJson(value); // '{"first":["é"]}'
  codePointLength('🛰'); // 1
}
```

### 事件身份

`eventId` 通过 WebCrypto 获取 D3 的稳定、 账户范围32 特征标识 。 保持它的虚构预想 身份证是这样 `compareEventIdentities` 可以区分重复与理论截断-hash相撞.

```ts
import { eventId, eventIdPreimage } from '@agentcomms/events';

const identity = {
  installationId: 'installation-id',
  accountId: 'account-id',
  eventType: 'gmail.message.received',
  typeVersion: 1,
  dedupeKey: '["provider-occurrence","message","received"]',
};
const preimage = eventIdPreimage(identity);
const id = await eventId(identity);
```

### Unicode、域和语义格式

库将NFC,全大小写折叠和IDNA处理到Unicode 15.1. `toAsciiDomain` 返回 a `Result`; 使用 `isFormat` 用于目录的五种语义格式.

```ts
import { UNICODE_VERSION, caseFold, isFormat, toAsciiDomain } from '@agentcomms/events';

UNICODE_VERSION; // '15.1.0'
caseFold('STRASSE'); // 'strasse'
toAsciiDomain('Bücher.example'); // { ok: true, value: 'xn--bcher-kva.example' }
isFormat('date-time', '2026-10-07T12:00:00Z'); // true
```

### JSON 指针和图案

指针跟随RFC 6901. 图案添加 `{ any: true }` 仅用于数组指数并扩展为混凝土非null 事件中出现的值.

```ts
import { expandPattern, getPointer } from '@agentcomms/events';

const source = { recipients: [{ address: 'recipient@example.test' }] };
getPointer(source, '/recipients/0/address'); // { found: true, value: 'recipient@example.test' }
expandPattern(['recipients', { any: true }, 'address'], source); // ['/recipients/0/address']
```

### 目录和源计划

`CATALOGUE` 精确地包含七个版本1的定义。 一个定义拥有它的Zod计划,元数据模式, 实例,来源 JSON Schema 并命名为不变量.

```ts
import { CATALOGUE, catalogueEntry, sourceSchema, validateEvent } from '@agentcomms/events';

const found = catalogueEntry('gmail.message.received', 1);
if (found.ok) {
  const event = found.value.examples[0];
  validateEvent(found.value, event); // { ok: true, value: event }
  sourceSchema(found.value); // JSON Schema 2020-12 for this exact source type
}
CATALOGUE.length; // 7
```

### 条件

在坚持该定义之前,将一个条件与所选定义相比较。 省略的大小写敏感旗 变得明确 `false`因此,Canonic JSON和工作流程摘要是稳定的.

```ts
import { CATALOGUE, canonicaliseCondition, evaluateCondition } from '@agentcomms/events';

const definition = CATALOGUE[0];
const condition = canonicaliseCondition(definition, { path: '/subject', op: 'contains', value: 'status' });
if (condition.ok) evaluateCondition(definition, condition.value, definition.examples[0]);
```

`canonicaliseAgenticCondition` 检查静态代理形式及其确定性内容-场前过滤器。 没错 不执行法官.

### 测绘和出处

映射干净的,打入的源值;常数从不继承出处. 对映射结果进行分类显示 守护进程在应用它所选择的输出指针前, 哪些输出指针是不信任的, 地址或范围化的手柄 代表权.

```ts
import { CATALOGUE, classifyMapped, compileMapping, evaluateMapping } from '@agentcomms/events';

const definition = CATALOGUE[0];
const mapped = compileMapping(definition, { subject: { $path: '/subject' } });
if (mapped.ok) {
  const value = evaluateMapping(mapped.value, definition.examples[0]);
  classifyMapped(definition, definition.examples[0], value);
}
```

`deliverySchema` 财务报告和审定财务报表 `deliverySchemaId` 描述确切的简单或封装的交货情况。 守护进程 选择该表示及其运输边界;此套件提供了决定性的绘图原始.

### 云端线条格式

在绘图和表述后,守护进程向 `buildCloudEvent`。图书馆来源于 不可超越的类型、主题、时间和犬科 `agentcommsuntrusted` 扩展; `cloudEventBytes` 给 犬形JSON字符串到UTF-8编码用于运输.

```ts
import { CATALOGUE, buildCloudEvent, cloudEventBytes } from '@agentcomms/events';

const definition = CATALOGUE[0];
const event = definition.examples[0];
const envelope = buildCloudEvent(definition, event, {
  deliveryId: 'delivery-id',
  installationId: 'installation-id',
  ruleId: 'rule-id',
  ruleVersion: 1,
  targetId: 'target-id',
  targetVersion: 1,
  data: { subject: event.subject },
  untrusted: ['/subject'],
});
cloudEventBytes(envelope);
```

`TEST_CLOUD_EVENT`, (中文(简体) ), `TEST_CLOUD_EVENT_BYTES` 财务报告和审定财务报表 `JUDGE_TEST_INPUT` 是固定的、只测试的合同值,而不是源 事件,而非调用者配置模板.

### 工作流程文本

`printRuleText` 将工作流程(其文档、代码名称的规则文档)写成一个人可以使用的短文本 读取并编辑,以及 `parseRuleText` 读回完全相同的文件。 打印同一文档总是给 同样的文字。 任何可读形式没有字的字都写作 `raw` JSON代替它,所以没有什么 掉下来了 解析器只检查文本: 当文档提交时, 事件服务仍然检查工作流程, 犬科JSON仍然是批准。 语法在 [src/rule-text/GRAMMAR.md (中文(简体) )](https://npmcn.com/package/%40agentcomms/events/src/rule-text/GRAMMAR.md); 从 0.36.0 开始文档 `workflow`,以及 解析器仍然读取旧的 `rule`从0.33.0起,目标可能是线性问题: `linear issue billing-issues, version 1, in team CUE, label Billing, assigned to me`,其编号,标题和描述在下行.

```ts
import { parseRuleText, printRuleText } from '@agentcomms/events';

const text = printRuleText(ruleDocument);
// workflow invoices, version 4
//
// when a new message arrives in cue/gmail, in the inbox
// match any
//   subject contains "invoice"
//   subject contains "payment"
// …
const parsed = parseRuleText(text);
if (parsed.ok) parsed.doc; // deep-equals ruleDocument
else parsed.errors; // [{ line, column, message }], e.g. 'unknown keyword "thne"; did you mean "then"? …'
```

## Unicode 数据和许可证

生成的表格及其被标注的来源为Unicode 15.1.0. 在仓库检查中, 运行 `pnpm sync:unicode` 从被封存的供应商文件中重新生成已填入的表格。 Unicode 字符数据库 已根据Unicode-3.0获得许可;其完整通知在 [第三层( P)](https://npmcn.com/package/%40agentcomms/events/THIRD_PARTY_LICENSES)。 。 。 .

## 许可证

麻省理工学院. 见 [自由主义](https://npmcn.com/package/%40agentcomms/events/LICENSE) 财务报告和审定财务报表 [第三层( P)](https://npmcn.com/package/%40agentcomms/events/THIRD_PARTY_LICENSES)。 。 。 .

## 常见问题

### @agentcomms/events 是什么？

事件目录,条件和绘制了代理-通信本地事件排放的模板:异态,没有I/O和Node导入\.

### 如何安装 @agentcomms/events？

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

### @agentcomms/events 支持 TypeScript 吗？

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

### @agentcomms/events 支持 ESM 还是 CommonJS？

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

### @agentcomms/events 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.12\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @agentcomms/events 可以商用吗？

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

### @agentcomms/events 的下载量有多少？

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

### @agentcomms/events 还在维护吗？

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