# @agent-assistant/surfaces 中文文档

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

版本：0\.4\.37
npm 元数据更新时间：2026-10-04T06:41:45.874Z
中文译文更新时间：2026-11-05T20:05:57.791Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：46.4 kB，22 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-04-13T08:48:16.398Z
- 最新版本发布：2026-10-04T06:41:45.435Z
- 近 30 天下载量：32122（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：68（近 12 个月 68 个）

## 中文简介

地面连接登记册、入境正常化和代理助理SDK出入境调度

## 安装

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

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

## README

# `@agent-assistant/surfaces`

`@agent-assistant/surfaces` 为Agent Ass助理SDK提供助发表层. 它拥有地表注册,入站正常化,出站调度,格式化钩子,多地表扇出. 它不执行运输协议或产品特定的表面逻辑.

## 责任

-   注册和跟踪 `SurfaceConnection` 记录
-   暴露出一个符合下列条件的单一登记册: `@agent-assistant/core`
-   正常的原始入境有效载荷进入结构 `InboundMessage` 形状核心预期
-   向一地平面发送外出事件, 或者在会话相接的地平面上扇出它们
-   在交付前应用可选的地表格式钩

## 非目标

-   hTTP、 WebSocket、 Slack Events 或桌面 IPC 等运输执行
-   认证、网路验证或供应商SDK关切
-   产品特定格式化公约或UI行为
-   缓冲、重试或下线队列

## 安装

```bash
npm install @agent-assistant/surfaces
```

## 核心概念

`SurfaceConnection` 描述一个已注册的地表,包括其适配器、能力和当前状态.

`SurfaceAdapter` 通过产品代码或运输软件包实施。 适配器只负责连接状态回调和最终有效载荷的交付.

`createSurfaceRegistry()` 返回一个作用为:

-   表面登记册
-   核心进入适配器
-   核心外出适配器

这使得产品将一个注册实例接入运行时间和接力传输层.

## 使用量

```ts
import { createAssistant } from '@agent-assistant/core';
import { createSurfaceRegistry } from '@agent-assistant/surfaces';

const surfaces = createSurfaceRegistry();

const runtime = createAssistant(
  {
    id: 'assistant-1',
    name: 'Assistant',
    capabilities: {
      chat: async (message, context) => {
        await context.runtime.emit({
          surfaceId: message.surfaceId,
          text: `echo:${message.text}`,
        });
      },
    },
  },
  {
    inbound: surfaces,
    outbound: surfaces,
  },
);
```

## 登记表面

```ts
surfaces.register({
  id: 'web-primary',
  type: 'web',
  state: 'registered',
  capabilities: {
    markdown: true,
    richBlocks: false,
    attachments: false,
    streaming: false,
    maxResponseLength: 0,
  },
  adapter: {
    async send(payload) {
      // Deliver payload to your transport layer.
    },
    onConnect(callback) {
      // Store and call when the transport becomes active.
    },
    onDisconnect(callback) {
      // Store and call when the transport becomes inactive.
    },
  },
});
```

当适配器报告连接或断开事件时,登记册会更新 `connection.state` 已经就位.

## 流入流量

中继发源代码将原始事件推入登记册:

```ts
surfaces.receiveRaw('web-primary', {
  messageId: 'msg-1',
  userId: 'user-1',
  text: 'hello',
  capability: 'chat',
});
```

默认常态提取 :

-   `id` 从 `messageId` 或者说 `id`,否则生成UUID
-   `sessionId` 从 `sessionId` 或者说 `session.id`
-   `userId` 从 `userId`, (中文(简体) ), `user.id`,或 `user` 当它是一个字符串
-   `workspaceId` 从 `workspaceId` 或者说 `workspace.id`
-   `text` 从 `text`, (中文(简体) ), `content`,或 `body`
-   `receivedAt` 从 `timestamp` 或者说 `receivedAt`,否则当前时间
-   `capability` 从 `capability` 或者说 `type`,否则 `'chat'`

若为 `userId` 丢失, 信件被丢弃, 错误被记录。 如果文本缺失, 则使用空字符串并记录警告 .

带有非标准接力有效载荷的产品可以将默认正常化逻辑替换为: `normalizationHook`。 。 。 .

## 外出交货

目标交付用途 `send(event)` 和要求 `event.surfaceId`。 。 。 .

```ts
await surfaces.send({
  surfaceId: 'web-primary',
  text: 'Hello from the assistant',
});
```

如果连接有 `formatHook`,钩子接收出局事件和地表能力,并可以返回任何地表特定格式结构. 没有钩子,适配器接收 `event.text` 作为格式化的输出.

适配器失败被包裹 `SurfaceDeliveryError`。 。 。 .

## 虚构

当核心将一个会话解决成一组附着的表面ID时,登记册可以向所有它们交付:

```ts
const result = await surfaces.fanout(
  {
    sessionId: 'session-1',
    text: 'This reaches every attached surface',
  },
  ['web-primary', 'desktop-1'],
);
```

幻想行为 :

-   默认同时发送
-   跳过未知的表面
-   默认跳过不活动表面
-   可以在第一次失败时继续收集失败或中止
-   返回 a `FanoutResult` 具有地表结果的

可配置默认扇出行为 `defaultFanoutPolicy`。 。 。 .

## 软件包边界

此套件为TypeScript-first,运行时光,没有云假设. 它不依赖于特定的运输堆栈,在运行时不导入会话逻辑,也不包含中继运输执行.

## 发展

```bash
npm test
npm run build
```

生平图 插图 缩图

## 常见问题

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

地面连接登记册、入境正常化和代理助理SDK出入境调度

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

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

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

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

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

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

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

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

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

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

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

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