# @agent-assistant/traits 中文文档

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

版本：0\.4\.37
npm 元数据更新时间：2026-10-04T06:34:48.231Z
中文译文更新时间：2026-11-05T22:31:55.481Z
软件包许可：MIT

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

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

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

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

## 中文简介

经验证的SDK代理助理的不可移动特性

## 安装

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

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

## README

# `@agent-assistant/traits`

`@agent-assistant/traits` 是一个用于验证、不可改变的辅助特性数据的 TypeScript- first 叶包.

它定义了一个助手如何呈现自己,以及它喜欢哪种格式的提示. 它不拥有运行时配置,人物a 提示,路由,模型选择,内存,或产品行为.

## API 密码

```typescript
import {
  createTraitsProvider,
  TraitsValidationError,
} from '@agent-assistant/traits';

import type {
  AssistantTraits,
  SurfaceFormattingTraits,
  TraitsProvider,
} from '@agent-assistant/traits';
```

## 数据模型

### `AssistantTraits`

```typescript
interface AssistantTraits {
  voice: string;
  formality: string;
  proactivity: string;
  riskPosture: string;
  domain?: string;
  vocabulary?: string[];
}
```

规则:

-   `voice` 必须是非空字符串。 已知值为 `concise`, (中文(简体) ), `conversational`, (中文(简体) ), `formal`,以及 `technical`。 。 。 .
-   未知 `voice` 值被接受为 `console.warn` 因此产品可以扩展寄存器而不伪造包.
-   `formality` 必须是 `casual`, (中文(简体) ), `professional`,或 `academic`。 。 。 .
-   `proactivity` 必须是 `low`, (中文(简体) ), `medium`,或 `high`。 。 。 .
-   `riskPosture` 必须是 `cautious`, (中文(简体) ), `moderate`,或 `assertive`。 。 。 .
-   `domain`如果存在,则必须是非空字符串.
-   `vocabulary`如果存在,则必须是非空字符串的非空字符串.

### `SurfaceFormattingTraits`

```typescript
interface SurfaceFormattingTraits {
  preferredResponseLength?: number;
  preferRichBlocks?: boolean;
  preferMarkdown?: boolean;
}
```

规则:

-   `preferredResponseLength`如果存在,则必须是正整数.
-   `preferRichBlocks`如果在场, 一定是布尔.
-   `preferMarkdown`如果在场, 一定是布尔.

这些是产品自主格式钩子的提示. 它们不能取代表面能力检查.

### `TraitsProvider`

```typescript
interface TraitsProvider {
  readonly traits: Readonly<AssistantTraits>;
  readonly surfaceFormatting?: Readonly<SurfaceFormattingTraits>;
}
```

消费者应依赖只读提供者的合同,而不是在运行时改变或重建提供者.

## 创建提供者

```typescript
import { createTraitsProvider } from '@agent-assistant/traits';

const traits = createTraitsProvider(
  {
    voice: 'concise',
    formality: 'professional',
    proactivity: 'medium',
    riskPosture: 'moderate',
    domain: 'knowledge-and-workspace',
    vocabulary: ['digest', 'workspace', 'context'],
  },
  {
    preferredResponseLength: 800,
    preferRichBlocks: false,
    preferMarkdown: true,
  },
);
```

`createTraitsProvider` 验证输入、复制、冻结返回的提供者、冻结嵌入的特性对象以及冻结复制的特性 `vocabulary` 阵列.

## 校验错误

```typescript
import { createTraitsProvider, TraitsValidationError } from '@agent-assistant/traits';

try {
  createTraitsProvider({
    voice: 'concise',
    formality: 'semi-formal',
    proactivity: 'medium',
    riskPosture: 'moderate',
  });
} catch (error) {
  if (error instanceof TraitsValidationError) {
    console.error(error.field);
    console.error(error.invalidValue);
    console.error(error.message);
  }
}
```

`TraitsValidationError` 扩展 `Error` 并揭露:

-   `field`: 失败的特性字段名称
-   `invalidValue`: 被拒绝的值
-   `message`:可读解释

## 用法边界

此软件包只拥有特性数据 .

-   没有劳动力个人所有权
-   没有迅速生成
-   没有特定产品的逻辑
-   无云或运行时间服务假设
-   没有动态学习或适应引擎
-   没有从其他中继助理包导入

特质和劳动力是有意分开的。 产品可能将特异性值构成人a提示或合成器输入,但该成分属于本包之外.

## 适应模式

V1 适应层为只读和产品所有:包和产品读作a `TraitsProvider` 并将其值应用到它们自己的格式化或合成逻辑.

格式化用法示例:

```typescript
const traits = runtime.definition.traits;

const useMarkdown =
  caps.supportsMarkdown && (traits?.surfaceFormatting?.preferMarkdown ?? true);

const responseVoice = traits?.traits.voice ?? 'concise';
```

示例合成用法:

```typescript
const traits = context.definition?.traits;

return assembleResponse(results, {
  voice: traits?.traits.voice ?? 'concise',
  formality: traits?.traits.formality ?? 'professional',
});
```

软件包不会生成提示,发送格式化的输出,或者解释超出验证范围的域名词汇.

## 核心整合

`@agent-assistant/core` 可以在 `AssistantDefinition`数字 :

```typescript
const assistant = createAssistant({
  id: 'sage',
  name: 'Sage',
  traits: createTraitsProvider({
    voice: 'concise',
    formality: 'professional',
    proactivity: 'medium',
    riskPosture: 'moderate',
  }),
  capabilities: {
    reply: () => undefined,
  },
});
```

田地可选. 没有特征的助理继续工作不变.

## 地方发展

从 `packages/traits`数字 :

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

这个软件包在孤立状态下可运行,并且具有零运行时间依赖性.

TRATS PACKAGE 缩写

## 常见问题

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

经验证的SDK代理助理的不可移动特性

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

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

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

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

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

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

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

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

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

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

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

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