# @agent-assistant/core 中文文档

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

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

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

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

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

- 包体积（解压后）：20.9 kB，8 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@agent-assistant/traits \>=0\.1\.0
- 首次发布：2026-04-13T08:47:54.312Z
- 最新版本发布：2026-10-04T06:40:15.567Z
- 近 30 天下载量：10572（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：68（近 12 个月 68 个）

## 中文简介

代理助理SDK的助理定义、生命周期和运行时间构成

## 安装

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

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

## README

# `@agent-assistant/core`

`@agent-assistant/core` 是代理助理SDK的根组成包。 它定义了助理合同,创造了运行时间,向能力处理器发送了正常的入境信息,并通过注入的适配器发送出出行事件.

包是TypeScript-first,没有云假设,也不执行会话,表面,内存,路由,或产品逻辑. 这些关切将留在后面的一揽子方案中,并通过此处界定的抽象合同加以整合.

## 它拥有什么

-   `AssistantDefinition` 助理身份、能力、钩子、运行时间限制和特征
-   `createAssistant()` 以注入出入境适配器构建运行时间
-   `AssistantRuntime` 生命周期方法: `start()`, (中文(简体) ), `stop()`, (中文(简体) ), `dispatch()`, (中文(简体) ), `emit()`, (中文(简体) ), `register()`, (中文(简体) ), `get()`,以及 `status()`
-   用钩子支持发送能力、超时处理和货币限制
-   外出目标 `surfaceId` 或通过抽象会话子系统扇出会话
-   储存、冻结和曝光 `TraitsProvider` 在运行时间定义上(储存和曝光——从不解释)

## 它不拥有的东西

-   中继传输、HTTP服务器、套接字或表面正常化
-   届会创建或届会生命周期规则
-   内存持续或检索
-   模式路线、政策执行或协调逻辑
-   特定产品的提示、工作流程或适配器

## 安装

```bash
npm install
```

从软件包目录 :

```bash
cd packages/core
npm install
npm test
npm run build
```

## 公共 API

```ts
import {
  AssistantDefinitionError,
  OutboundEventError,
  createAssistant,
  type AssistantDefinition,
  type InboundMessage,
  type OutboundEvent,
} from "@agent-assistant/core";
```

### `createAssistant(definition, adapters)`

创建一个 `AssistantRuntime` 从一个有效的助手定义和两个注入适配器:

-   `inbound.onMessage(handler)` 财务报告和审定财务报表 `inbound.offMessage(handler)` 将正常的输入信息连接到核心
-   `outbound.send(event)` 发送有针对性的出境信息
-   `outbound.fanout(event, surfaceIds)` 可选, 可用时用于会话扇出

运行时间创建于 `created` 状态。 打电话 `start()` 在发送消息之前.

## 运行时行为

### 生命周期

-   `start()` 启动时为同位素
-   `stop()` 停止后为同位素
-   无法重新启动已停止的运行时间
-   `status()` 返回准备状态、启动时间、已登记的子系统、已登记的能力和飞行中处理器的计算

### 调度

-   `dispatch(message)` 运行发送前 `onMessage` 钩子定义时
-   返回时 `false` 从 `onMessage` 不引用能力而丢弃信件
-   缺失的能力不会从 `dispatch()`;它们通过报告 `onError`
-   能力故障和超时报告 `onError`
-   货币受下列因素的限制: `constraints.maxConcurrentHandlers` 和 FIFO 顺序的额外发送队列

### 释放

-   `emit({ surfaceId, text })` 执行目标发送
-   `emit({ sessionId, text })` 解决已注册的 `sessions` 子系统与粉丝出 `attachedSurfaces`
-   `emit()` 掷出 `OutboundEventError` 当两个 `surfaceId` 也没有 `sessionId` 当前

Core保存会议摘要。 运行时间期望在字符串密钥下注册的子系统 `sessions` 用于:

```ts
runtime.register("sessions", {
  async getSession(sessionId: string) {
    return {
      attachedSurfaces: ["surface-a", "surface-b"],
    };
  },
});
```

或:

```ts
runtime.register("sessions", {
  async get(sessionId: string) {
    return {
      attachedSurfaces: ["surface-a", "surface-b"],
    };
  },
});
```

## 示例

```ts
import { createAssistant, type InboundMessage } from "@agent-assistant/core";

const runtime = createAssistant(
  {
    id: "assistant-1",
    name: "Example Assistant",
    capabilities: {
      reply: async (message: InboundMessage, context) => {
        context.log.info("handling inbound message");
        await context.runtime.emit({
          surfaceId: message.surfaceId,
          text: `Echo: ${message.text}`,
        });
      },
    },
  },
  {
    inbound: {
      onMessage(handler) {
        void handler;
      },
      offMessage(handler) {
        void handler;
      },
    },
    outbound: {
      async send(event) {
        console.log("send", event);
      },
    },
  },
);

await runtime.start();
```

## 特质

`AssistantDefinition` 接受可选选项 `traits` 类型字段 `TraitsProvider` 从 `@agent-assistant/traits`核心储存和在装配过程中冻结供应商。 它不读取、不分出或不解释任何特性值.

```ts
import { createTraitsProvider } from "@agent-assistant/traits";
import { createAssistant } from "@agent-assistant/core";

const runtime = createAssistant(
  {
    id: "sage-assistant",
    name: "Sage",
    traits: createTraitsProvider(
      { voice: "concise", formality: "professional", proactivity: "medium", riskPosture: "moderate" },
      { preferMarkdown: true, preferredResponseLength: 800 },
    ),
    capabilities: {
      reply: async (message, context) => {
        // Capability handlers access traits as read-only data
        const voice = context.runtime.definition.traits?.traits.voice;
        const preferMarkdown = context.runtime.definition.traits?.surfaceFormatting?.preferMarkdown;
        // Surface formatting decisions live here — not in core
        void voice; void preferMarkdown;
      },
    },
  },
  adapters,
);
```

`traits` 是可选的。 现有没有特征的定义不作修改.

`@agent-assistant/traits` 是同级依赖。 不使用特质的消费者不需要安装.

## 发展

-   `npm test` 运行WF-1、WF-2、WF-4和WF-5核心工作流程的孤立Vitest套件
-   `npm run build` 发射 `dist/` 声明和 Java 脚本通过 `tsc`

核心( P)

## 常见问题

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

代理助理SDK的助理定义、生命周期和运行时间构成

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

在项目目录运行 npm install @agent-assistant/core，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@agent-assistant/traits（\>=0\.1\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

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

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

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

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

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

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

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

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

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

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