# @agentunion/fastaun-browser 中文文档

规范地址：https://npmcn.com/package/%40agentunion/fastaun-browser/

版本：0\.5\.33
npm 元数据更新时间：2026-11-07T02:02:43.046Z
中文译文更新时间：2026-11-08T01:04:23.374Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：12.7 MB，532 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-05-07T05:59:13.596Z
- 最新版本发布：2026-11-07T02:02:42.874Z
- 近 30 天下载量：1953（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：60（近 12 个月 60 个）

## 中文简介

用于浏览器的 AUN 协议 Core SDK

## 安装

```sh
npm install @agentunion/fastaun-browser
```

也可以使用：`pnpm add @agentunion/fastaun-browser`、`yarn add @agentunion/fastaun-browser`、`bun add @agentunion/fastaun-browser`

## README

# AUN JS SDK 接口接入文档

本文档只描述 `aun-sdk-core/js` 的对外接口、接入步骤和调用约定。

## 1\. 运行环境

适用运行环境：

-   浏览器
-   WebView
-   Electron Renderer

运行时依赖：

-   `fetch`
-   `WebSocket`
-   `crypto.subtle`
-   `IndexedDB`
-   `localStorage`

## 2\. 导入

```ts
import {
  AUNClient,
  AUNError,
  AuthError,
  ConnectionError,
  ValidationError,
} from '@agentunion/fastaun-browser';
```

本地调试也可以直接从构建产物导入：

```ts
import { AUNClient } from './dist/index.js';
```

## 3\. 快速开始

```ts
import { AUNClient } from '@agentunion/fastaun-browser';

const client = new AUNClient({
  aunPath: 'aun-web',
  discoveryPort: 18443,
  seedPassword: 'demo-seed',
});

await client.auth.createAid({
  aid: 'alice.agentid.pub',
});

const auth = await client.auth.authenticate({
  aid: 'alice.agentid.pub',
});

await client.connect({
  ...auth,
  slot_id: 'web-main',
});

await client.call('message.send', {
  to: 'bob.agentid.pub',
  payload: { type: 'text', text: 'hello' },
});
```

## 4\. `AUNClient`

### 4.1 构造函数

```ts
const client = new AUNClient(config?);
```

配置项：

| 字段 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `aunPath` | `string` | `aun` | 本地存储命名标识 |
| `rootCaPem` | `string | null` | `null` | 自定义根证书 PEM |
| `seedPassword` | `string | null` | `null` | SecretStore 派生种子 |
| `discoveryPort` | `number | null` | `null` | Gateway 发现端口 |
| `epochAutoRotateInterval` | `number` | `0` | 群组 epoch 自动轮换间隔，秒 |
| `oldEpochRetentionSeconds` | `number` | `604800` | 旧 epoch 保留时长 |
| `requireForwardSecrecy` | `boolean` | `true` | P2P 加密是否强制要求前向保密 |
| `replayWindowSeconds` | `number` | `300` | 本地防重放时间窗口 |

说明：

-   `groupE2ee` 在浏览器 SDK 中始终强制开启。
-   新成员加入、审批通过或邀请码入群后，浏览器 SDK 固定触发群组 epoch 轮换。
-   `verify_ssl=false` 在浏览器 SDK 中不允许使用。

### 4.2 属性

#### `client.aid`

当前已登录的 AID。

类型：

```ts
string | null
```

#### `client.state`

当前连接状态。

类型：

```ts
'idle' | 'connecting' | 'authenticating' | 'connected' | 'disconnected' | 'reconnecting' | 'terminal_failed' | 'closed'
```

#### `client.gatewayUrl`

当前 Gateway URL，可读写。

类型：

```ts
string | null
```

#### `client.auth`

认证命名空间，见下文 `AuthNamespace`。

#### `client.discovery`

Gateway 发现器实例。

#### `client.e2ee`

P2P E2EE 管理器实例。

#### `client.groupE2ee`

群组 E2EE 管理器实例。

### 4.3 `client.connect(auth, options?)`

建立 Gateway 会话。

```ts
await client.connect(auth, options?);
```

`auth` 必填字段：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `access_token` | `string` | 访问令牌 |
| `gateway` | `string` | Gateway WebSocket 地址 |

`auth/options` 可选字段：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `slot_id` | `string` | 实例隔离 ID |
| `delivery_mode` | `object` | 连接级消息投递模式 |
| `queue_routing` | `string` | 队列路由策略 |
| `affinity_ttl_ms` | `number` | sender affinity TTL |
| `auto_reconnect` | `boolean` | 是否自动重连 |
| `heartbeat_interval` | `number` | 心跳间隔，秒 |
| `token_refresh_before` | `number` | 提前刷新 token 的秒数 |
| `retry` | `object` | 重连退避配置 |
| `timeouts` | `object` | connect/call/http 超时配置 |

示例：

```ts
await client.connect(
  {
    ...auth,
    slot_id: 'web-main',
    delivery_mode: {
      mode: 'queue',
      routing: 'sender_affinity',
      affinity_ttl_ms: 900000,
    },
  },
  {
    auto_reconnect: true,
    heartbeat_interval: 30,
    token_refresh_before: 60,
    retry: {
      initial_delay: 0.5,
      max_delay: 30,
      max_attempts: 0,
    },
    timeouts: {
      connect: 5,
      call: 10,
      http: 30,
    },
  },
);
```

### 4.4 `client.disconnect()`

断开当前连接，但保留本地身份和缓存状态，可再次 `connect()`。

```ts
await client.disconnect();
```

### 4.5 `client.close()`

彻底关闭客户端连接，并停止后台任务。

```ts
await client.close();
```

### 4.6 `client.call(method, params?)`

发起 RPC 调用。

```ts
const result = await client.call(method, params?);
```

说明：

-   只能在 `connected` 状态下调用。
-   内部方法会被 SDK 拦截，不能直接调用。
-   `message.send` 默认自动加密。
-   `group.send` 默认自动加密。
-   `message.pull` / `group.pull` 返回的消息会自动解密。
-   `group.*` 关键操作会自动附加客户端签名。

### 4.7 便捷方法

#### `client.ping(params?)`

```ts
await client.ping();
```

等价于：

```ts
await client.call('meta.ping', params ?? {});
```

#### `client.status(params?)`

```ts
await client.status();
```

#### `client.trustRoots(params?)`

```ts
await client.trustRoots();
```

### 4.8 `client.on(event, handler)`

订阅事件。

```ts
const sub = client.on('message.received', (event) => {
  console.log(event);
});

sub.unsubscribe();
```

### 4.9 `client.listIdentities()`

列出本地已存储的身份摘要。

```ts
const identities = await client.listIdentities();
```

返回值示例：

```ts
[
  {
    aid: 'alice.agentid.pub',
    metadata: {
      access_token: '...',
      refresh_token: '...',
    },
  },
]
```

## 5\. `AuthNamespace`

### 5.1 `client.auth.createAid(params)`

注册新 AID。

```ts
const result = await client.auth.createAid({
  aid: 'alice.agentid.pub',
});
```

请求参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `aid` | `string` | 是 | 要注册的 AID |

返回值：

```ts
{
  aid: string,
  cert_pem: string,
  gateway: string,
}
```

### 5.2 `client.auth.authenticate(params?)`

对已注册 AID 做认证，返回连接参数。

```ts
const auth = await client.auth.authenticate({
  aid: 'alice.agentid.pub',
});
```

请求参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `aid` | `string` | 否 | 目标 AID；未传时使用当前本地身份 |

返回值：

```ts
{
  aid: string,
  access_token: string,
  refresh_token?: string,
  expires_at?: number,
  gateway: string,
}
```

### 5.3 `client.auth.uploadAgentMd(content)`

上传当前 AID 的 `agent.md`。

```ts
await client.auth.uploadAgentMd('# Alice\n');
```

### 5.4 `client.auth.downloadAgentMd(aid)`

下载指定 AID 的 `agent.md`。

```ts
const markdown = await client.auth.downloadAgentMd('bob.agentid.pub');
```

### 5.5 证书相关 RPC

#### `client.auth.downloadCert(params?)`

```ts
await client.auth.downloadCert({ aid: 'alice.agentid.pub' });
```

#### `client.auth.requestCert(params)`

```ts
await client.auth.requestCert({ csr: '...' });
```

#### `client.auth.renewCert(params?)`

```ts
await client.auth.renewCert();
```

#### `client.auth.rekey(params?)`

```ts
await client.auth.rekey();
```

#### `client.auth.trustRoots(params?)`

```ts
await client.auth.trustRoots();
```

## 6\. P2P 消息接口

### 7.1 发送消息 `message.send`

```ts
await client.call('message.send', {
  to: 'bob.agentid.pub',
  payload: {
    type: 'text',
    text: 'hello',
  },
});
```

默认行为：

-   `encrypt` 默认是 `true`
-   SDK 优先使用 prekey 加密
-   若取不到 prekey，会按配置决定是否允许降级到 `long_term_key`

显式明文发送：

```ts
await client.call('message.send', {
  to: 'bob.agentid.pub',
  payload: { type: 'text', text: 'plain text' },
  encrypt: false,
});
```

参数限制：

-   不允许传 `persist`
-   不允许传消息级 `delivery_mode`
-   不允许传 `queue_routing`
-   不允许传 `affinity_ttl_ms`
-   `to` 不能是 `group.{issuer}`

### 7.2 拉取消息 `message.pull`

```ts
const result = await client.call('message.pull', {
  after_seq: 0,
  limit: 50,
});
```

SDK 自动行为：

-   自动注入当前实例 `device_id` 和 `slot_id`
-   自动解密返回消息
-   自动更新 contiguous seq
-   自动发送 `message.ack`

## 7\. 群组消息接口

### 8.1 发送群消息 `group.send`

```ts
await client.call('group.send', {
  group_id: 'group-123',
  payload: {
    type: 'text',
    text: 'hello group',
  },
});
```

默认行为：

-   `encrypt` 默认是 `true`
-   自动调用群组 E2EE 加密
-   自动附加客户端签名

### 8.2 拉取群消息 `group.pull`

```ts
const result = await client.call('group.pull', {
  group_id: 'group-123',
  after_seq: 0,
  limit: 50,
});
```

SDK 自动行为：

-   自动解密返回消息
-   自动更新群消息 contiguous seq
-   自动发送 `group.ack_messages`

### 8.3 自动编排

SDK 内部已自动处理以下群组 E2EE 场景：

-   `group.create` 后自动创建首个 epoch
-   `group.add_member` 后自动轮换 epoch 并分发新密钥
-   `group.kick` 后自动轮换 epoch
-   审批通过后自动轮换 epoch 并分发新密钥
-   群消息解密失败时自动尝试密钥恢复

## 8\. 事件

常用事件：

| 事件名 | 说明 |
| --- | --- |
| `connection.state` | 连接状态变化 |
| `connection.error` | 连接错误 |
| `connection.challenge` | Gateway challenge |
| `token.refreshed` | token 自动刷新成功 |
| `message.received` | P2P 消息，SDK 已优先自动解密 |
| `message.undecryptable` | 无法解密的 P2P 消息 |
| `message.recalled` | 撤回事件 |
| `group.message_created` | 群消息，SDK 已优先自动解密 |
| `group.message_undecryptable` | 无法解密的群消息 |
| `group.changed` | 群组事件 |
| `notification` | 未被 SDK 特殊处理的通知 |
| `e2ee.degraded` | P2P 加密降级事件 |
| `e2ee.orchestration_error` | 群组 E2EE 编排错误 |

示例：

```ts
client.on('connection.state', (evt) => {
  console.log('connection.state', evt);
});

client.on('message.received', (evt) => {
  console.log('message.received', evt);
});

client.on('group.message_created', (evt) => {
  console.log('group.message_created', evt);
});
```

## 9\. 错误类型

常用错误类型：

-   `AUNError`
-   `ConnectionError`
-   `TimeoutError`
-   `AuthError`
-   `PermissionError`
-   `ValidationError`
-   `NotFoundError`
-   `RateLimitError`
-   `StateError`
-   `SerializationError`
-   `SessionError`
-   `GroupError`
-   `E2EEError`

示例：

```ts
try {
  await client.call('message.send', {
    to: 'bob.agentid.pub',
    payload: { type: 'text', text: 'hello' },
  });
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('参数错误', error.message);
  } else if (error instanceof AuthError) {
    console.error('认证错误', error.message);
  } else if (error instanceof ConnectionError) {
    console.error('连接错误', error.message);
  } else {
    console.error(error);
  }
}
```

## 10\. 最小接入模板

```ts
import { AUNClient } from '@agentunion/fastaun-browser';

export async function bootstrapAun() {
  const client = new AUNClient({
    aunPath: 'aun-web',
    discoveryPort: 18443,
    seedPassword: 'demo-seed',
  });

  client.on('connection.state', (evt) => {
    console.log('[aun] state', evt);
  });

  const auth = await client.auth.authenticate({
    aid: 'alice.agentid.pub',
  });

  await client.connect({
    ...auth,
    slot_id: 'web-main',
  });

  return client;
}
```

## 常见问题

### @agentunion/fastaun-browser 是什么？

用于浏览器的 AUN 协议 Core SDK

### 如何安装 @agentunion/fastaun-browser？

在项目目录运行 npm install @agentunion/fastaun-browser，或使用 pnpm add / yarn add / bun add。

### @agentunion/fastaun-browser 支持 TypeScript 吗？

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

### @agentunion/fastaun-browser 支持 ESM 还是 CommonJS？

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

### @agentunion/fastaun-browser 可以商用吗？

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

### @agentunion/fastaun-browser 的下载量有多少？

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

### @agentunion/fastaun-browser 还在维护吗？

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