# @happyvertical/smrt-agents 中文文档

规范地址：https://npmcn.com/package/%40happyvertical/smrt-agents/

版本：0\.62\.1
npm 元数据更新时间：2026-11-17T07:55:07.121Z
中文译文更新时间：2026-11-17T09:37:51.904Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.6 MB，141 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：15 个
- peer 依赖：svelte ^5\.57\.0
- 首次发布：2026-06-23T01:18:27.855Z
- 最新版本发布：2026-11-17T07:55:06.934Z
- 近 30 天下载量：21878（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：366（近 12 个月 366 个）

## 中文简介

在SMRT生态系统中建立自主行为体的代理框架

## 安装

```sh
npm install @happyvertical/smrt-agents
```

也可以使用：`pnpm add @happyvertical/smrt-agents`、`yarn add @happyvertical/smrt-agents`、`bun add @happyvertical/smrt-agents`

## README

# @ happyvertical/ smrt- 代理服务器

建立自主行为体的代理框架,包括生命周期管理、代理通信、基于利益的发现、时间安排和多租户约束.

## 安装

```bash
pnpm add @happyvertical/smrt-agents
```

## 使用量

```typescript
import { Agent, type AgentOptions } from '@happyvertical/smrt-agents';
import { smrt } from '@happyvertical/smrt-core';
import { getModuleConfig } from '@happyvertical/smrt-config';

@smrt()
class MyAgent extends Agent {
  protected config = getModuleConfig('my-agent', {
    cronSchedule: '0 2 * * *',
    maxRetries: 3,
  });

  itemsProcessed: number = 0;

  constructor(options: AgentOptions = {}) {
    super({
      ...options,
      interests: {
        objects: {
          Meeting: { filter: { status: 'upcoming' } },
          Document: { filter: { 'type in': ['agenda', 'minutes'] } },
        },
      },
    });
  }

  async validate(): Promise<void> {
    if (!this.config.cronSchedule) throw new Error('cronSchedule required');
  }

  async run(): Promise<void> {
    const items = await this.interesting();
    for (const { type, data } of items) {
      this.logger.info(`Processing ${type}: ${data.id}`);
    }
    this.itemsProcessed = items.length;
    await this.save();
  }
}

const agent = new MyAgent({ name: 'my-agent' });
await agent.execute(); // initialize() -> validate() -> run() -> shutdown()
```

如果您正在运行一个单代理的 CLI 或 脚本并想要内置 `SIGTERM`编号 :`SIGINT` 处理、通过 `manageProcessSignals: true` 页:1 建筑师。 多代理主机应该离开,并协调进程 关闭自己.

## 计划方法 Vs 运算符动作

对正则可重复维护路径使用预定代理方法: 每次时刻表起火时应自动完成的工作。 留着 能够安全地重新运行.

当操作人员需要复合的追赶或修复流量时,将它暴露为 明确的方法,例如 `forage()`, (中文(简体) ), `backfill()`,或 `rebuildIndex()` 改为 超载 `run()` 只有手动行为 这些操作者的行动仍然可以 被排列通过 `@happyvertical/smrt-jobs`但它们应该保持区别 从正常的预定循环,所以它保持明显 哪些工作是自动和 工作是一种有意的干预.

## Schema 驱动设置

代理包可以声明便携式非秘密设置而不传输 a 自定义管理员组件。 清单保留了版本的图案和 代理管理员 shell 制作 `AgentSettingsForm` 作为后退.

```typescript
static override uiSlots = {
  notifications: {
    id: 'notifications',
    label: 'Notifications',
    scope: 'persona',
    settingsSchema: {
      version: 1,
      fields: [
        {
          id: 'minimumSeverity',
          label: 'Minimum severity',
          type: 'select',
          options: [
            { value: 'info', label: 'Info' },
            { value: 'urgent', label: 'Urgent only' },
          ],
        },
      ],
    },
  },
} satisfies AgentUISlots;
```

`scope: 'persona'` 持续在 `AgentOptions.personaId`· ; `scope: 'agent'` 使用已保存的代理行标识 。 省略范围选择当前和 否则会保留Agent-row行为 全权证书不应 被建模为设置字段 - 使用特定软件包只写服务器边界 例如 `MessagingSettingsService`。 。 。 .

## API 密码

### 主导出( E)`@happyvertical/smrt-agents`(中文(简体) )

| 导出 | 说明 |
| --- | --- |
| `Agent` | 具有生命周期和兴趣的基干类别 |
| `AgentOptions` | 构造选项类型 |
| `AgentStatusType` | 状态列表:闲置/初始化/运行/错误/下沉 |
| `AgentConfig` | DB- 持久性代理配置模型 |
| `AgentConfigCollection` | 代理连接的收藏 |
| `AgentSchedule` | 基于 Cron 的日程模式`_smrt_agent_schedules`(中文(简体) ) |
| `AgentScheduleCollection` | 代理列表收藏 |
| `ScheduleStatus` | 计划状态类型 |
| `TenantAgent` | 代理对租户与分级分辨率相接 |
| `TenantAgentCollection` | 租户代理的收藏 |
| `TenantAgentStatus` | 租户身份类型 |
| `ResolvedAgentAvailability` | 分级行走后确定可用性 |
| `mergeFilters` | 合并利息过滤器 |
| `normalizeSort` | 将排序表达式规范化 |
| `InterestOptions` | 利息配置类型 |
| `InterestFilter` | 过滤定义类型 |
| `InterestResult` | 发现结果类型 |
| `ObjectInterestConfig` | 对象兴趣配置类型 |
| `ObjectFilter` | 对象过滤器类型 |
| `InterestHandlerFn` | 利息处理器函数类型 |
| `AsyncQualifierFn` | Async 后过滤器修饰类型 |
| `QueryFn` | 查询函数类型 |
| `AgentWithInterestsOptions` | 有权益的代理选项 |
| `createReportDataSurfaceTools` | 主要报告发现、查询、生命周期、钻探和出口工具 |
| `ReportDataSurfaceToolsOptions` | 服务器拥有的报告目录和应用程序主机连接 |
| `createSmrtCollectionDataSurfaceDefinition` | 通用登记册驱动 `SmrtObject` · 收款 `DataSurfaceDefinition` 适配器,并进行外地政策编辑和抵消/校正 |
| `buildDataQuerySchemaForClass` | 纪念 `DataQuerySchema` 来源于 `ObjectRegistry` 任意注册类的字段元数据 |
| `executeSmrtCollectionQuery` | 边界 `DataQueryRequest` 对任意执行 `list`编号 :`count`编号 :`facets`\- 形状收藏 |
| `CreateSmrtCollectionDataSurfaceOptions` | 备选方案 `createSmrtCollectionDataSurfaceDefinition` |
| `SmrtCollectionQueryCollection` | 通用适配器针对 |
| `SmrtCollectionQueryScope` | 通用适配器可信、服务器衍生的范围条件 |
| `SmrtCollectionDataSurfaceAction` | 声明行/块动作目录 `metadata.actionCatalog` |

### 发现摘要

`createDataSurfaceTools({ surfaces, discoverDetail: 'summary' })` 制造 `data.discover` 返回每个可读表面的一个小条目—— `id`, (中文(简体) ), `label` (它的第一个非空行,倒回了id),第一个非空行,即 `description` 以有椭圆形的160个字符和可选字符为界 `rowCountHint` 而不是整个领域,元数据, `supports`,以及 `limits` 释相. 模特儿叫来了 `data.inspect` 一个地表的田地和 运算器,所以 **摘要模式假定主机的允许列表包括 `data.inspect`**; 提供 `data.discover` 财务报告和审定财务报表 `data.query` 无 它应该保持全模式。 默认, `discoverDetail: 'full'`,不变 (无时同字 `rowCountHint` 已设置);目录过滤, 权限 `discover` 审计条目、失败和 `data.query` 行为 两种模式相同,以及 `data.inspect` 总是返回完整描述符.

`DataSurfaceDefinition.rowCountHint` (亦为 `createSmrtCollectionDataSurfaceDefinition()`,报告定义,以及 `@happyvertical/smrt-content`是因为 `createContentListDataSurfaceDefinition()`)为 主机提供大小提示:非负安全整数或单行标签 最多32个字符,例如 `"~2k"`。它从未通过查询计算. 无效的值被省略(参见 `normalizeDataSurfaceRowCountHint()`无 未成功发现:带有控制、格式(bidi、0width、BOM、软)的标签 连字符,标记,或行/段落分隔字符,或无 可见。 有效提示也出现在完整描述中.

显示相同的提示 **每一个能读取表面的校长**,所以这个 不得编码特定租户或本金的计数。 用粗糙的静态 标签(`"thousands"`, (中文(简体) ), `"~2k"`),从来没有一个活的租户总数. 同样 首条非空行 `description` 在每个摘要中都是建模文本 : 保持它没有秘密 内部识别资料 对模型的指示. 提要 `label` 财务报告和审定财务报表 `description`,CR、LF、VT、FF、NEL、U+2028,以及 U+2029 是换行符, 格式字符被删除, 其它控制 字符成为空格。 完整描述符保持主机文本不变.

### 报告数据搜索工具

`createReportDataSurfaceTools()` 合并普通只读数据表面 工具为 `reports.query`, (中文(简体) ), `reports.refresh`, (中文(简体) ), `reports.drilldown`,以及 `reports.export`配置报告构建器和所有运输/行动接合 在服务器上。 查询完全从现场继承权威 `PrincipalRun`;可见命令需要精确的浏览器识别,以及 刷新/出口保留应用程序自主授权和审计主机. 发现保存每个可见报告字段的种类, Where/HAVING 过滤器 范围、能力和现有报告行动。 当 已认证数据库存在,无声可见读取返回 租户 -- -- 安全生命周期 -- -- 生成的新鲜状态(包括 stale或 )). 广告动作被现场过滤 主工具允许列表和有效权限; 动作主机仍然 突变前重新授权.

### 一般 Smrt 对象收集数据搜索面

`createSmrtCollectionDataSurfaceDefinition()` 构建一个 `DataSurfaceDefinition` 任意登记的 `SmrtObject` 收集(活动、广告区、, 时间表、社会账户、会议、任务、......) `Content`数字 :

```typescript
const definition = await createSmrtCollectionDataSurfaceDefinition({
  qualifiedName: '@myapp/events:Event',
  collectionName: 'events', // permission-catalog collection
  collection: async ({ principal }) => getEventsCollection(principal.tenantId),
  scope: ({ principal }) => ({ tenantId: principal.tenantId }),
  actions: [{ id: 'cancel', label: 'Cancel', requiresConfirmation: true }],
});
```

计划来源于 `ObjectRegistry.getAllFields()`数字 : `sensitive` 财务报告和审定财务报表 `readPermission`\- 斜地/非柱地后地 班级配置的租户字段(来自 `@TenantScoped()`; 未瞄准的类获得 完全不排斥或界定租户范围),内部 `_`\- 前缀 字段从未被宣布——相同的实地政策界限 `@happyvertical/smrt-content`'ContentList 适配器执行. 提供主机 `schema` 推翻与同一登记处产生的除外情形相交 设定,所以它只能缩小,永远不扩大,什么是广告。 执行 租户阅读范围和申请 `scope` 进入每个分支 呼叫过滤器( n)`all`编号 :`any`编号 :`not`条件,降为界限 断开- 正常形式 `where` 支持两个部分: 不透明-cursor呼求, 并且从来没有水合 全部收集。 一个明确的, 常规空应用程序 `scope` 拒绝所有行和短路 而不唤取集.

带有扫描器宣布的闭合集的字段——类型脚本 `enum` 或者说 字符串/ 数字字形联盟类型, 作为注册字段的 `enum` —— 说 把这些成员当作数据库 `values` (# 4381),这样 `data.inspect` 财务报告和审定财务报表 `data.discover` 让他们看看。 因为ORM不验证 eums在保存, 存储行可能早于声明或逃避声明,所以衍生值是 默认咨询`valuesEnforced: false` 和过滤器 其他价值观继续发挥作用。 设定 `enforceDerivedValues: true` 一旦存储 已知数据相符; `data.query` 然后拒绝在 设置和描述报告 `valuesEnforced: true`。数值仅来自 声明,从不从行。 核心界限外的声明(更多) 超过100个成员、成员过长或不安全、类型不匹配) 数值,因为部分清单应为完整:咨询表面 日志a `@happyvertical/logger` 警告时指定类别和字段,并使用 `enforceDerivedValues: true` 计程车的投出。 井田从不携带 数值。 A 类 `schema` 覆盖它自己宣布 `values` (除非设定) `valuesEnforced: false`) (中文(简体) ).

光标不透明, 并绑定到精确的查询: 它们编码 `{ binding, offset }`时 `binding` 指纹 常规请求( filter, s排序, )加上合并的租户/申请范围,因此从a 不同查询、过滤、排序或租户被拒绝,而不是默默拒绝 应用不当. `facets` 支持收藏形状的默认值 (单位:千美元)`typeof collection.facets === 'function'` 静态收藏; `true` 对于一个有决心的,必须设置 `facets: false` 如果解决了 收藏缺乏 `facets()`) (中文(简体) ). 因为 `SmrtCollectionQueryCollection` 实值 结构,适配器不能读取主机收藏的自有行限制上限- 设定 `maxPageLimit` 检测到在盖子上或下方,或被夹住的页 通过结果警告而不是纠正报告。 见 `src/smrt-collection-data-surface.ts` 合同全文 `docs/data-surface-conformance.md` 用于综合清单.

### 服务器导出( E)`@happyvertical/smrt-agents/server`(中文(简体) )

`createDataSurfaceActionAdapter()` 提供纯服务器预览并被确认 用于 `smrt-ui` 数据表面行动合同。 浏览器 选择和动作有效载荷是提示,绝不是权威:每个动作声明 其输入验证器、确认政策、主要工具/RBAC操作,新鲜 授权和行资格检查,以及前景或注入背景 执行.

预览发布一个短命的不透明符号 绑在本金,租户, 表面/动作、选择、查询指纹和修订。 应用验证 对确认要求的行动具有约束力并重复其主要约束性检查 在返回已接受、跳过和失败的行结果之前。 已宣布的行动 与 `confirmation: 'none'` 可用一能键直接适用 其他应用程序必须包括其当前预览符号。 呼叫者必须提供耐用 共享 `DataSurfaceActionStateStore` 有原子代号 和一能操作. `createSqlDataSurfaceActionStateStore()` 使用应用程序迁移的 s -m -r -t 数据库; 符号消耗和应用保留一起进行,同时 预览符和预订所有者非目录作为散列存储 。 一个 孤儿保留从未到期或自动重复,因为 外部影响可能不明。 宿主只能调节到终端 结果通过 `reconcileIdempotency()` 在配置的活授权之后 callback接受确切请求指纹和保留的证据 时间戳. `InMemoryDataSurfaceActionStateStore` 用于单一进程测试 只能用绳子.

`createJobsDataSurfaceBackgroundQueue()` 将一个版本信封粘入 `@happyvertical/smrt-jobs`信封中包含请求和一个非秘密 主要参考文献,绝不允许提供快照或确认机密. 在每个工人流程中登记同样的稳定处理器ID,并配置 用这个适配器 `backgroundHandlerId` 和仅一个服务器 `deferredEnvelopeSigningKey` 至少32个字节。 密钥认证 并从未添加到工作有效载荷中。 工人接生电话 `adapter.executeDeferred()`,它再次解决了当前的主要权威 在变异之前。 原画 `job.run()` 仍然可以调用 进程内队列适配器.

`createDataSurfaceActionRouteHandlers()` 有线SvelteKit( 或任何网络) `Request`编号 :`Response`() 通往适配器的路由:它解决每 请求,解析正文,并将每个拒绝理由映射到 HTTP 状态. `resolveBulkExplicitIds()` 将浏览器提供的锚行 id 扩展为 a 完整批量选择服务器侧面( 例如“ 每一个参考相片 ” )),所以一个一能键覆盖了整个集. 见 [`docs/data-surface-sveltekit-wiring.md`](https://npmcn.com/package/docs/data-surface-sveltekit-wiring.md) 排队线条指南,包括 拒绝状态表.

### UI 导出( U)`@happyvertical/smrt-agents/ui`(中文(简体) )

| 导出 | 说明 |
| --- | --- |
| `AgentUIRegistry` | 代理人管理面板的单子登记簿 |
| `createUIRegistry` | 用于UI登记册的工厂 |
| `AgentUISlot` | 用户界面槽定义类型 |
| `AgentUISlots` | 用户界面插槽地图 |
| `AgentSettingsSchema` | 版本倒置设置形式合同 |
| `AgentAdminRoute` | 管理路由元数据(路径、组件、负载) |
| `AgentAdminExport` | 代理管理员模块导出形状 |
| `AgentAdminNavItem` | 管理边栏的导航项目 |
| `AgentAdminRootProps` | 管理根组件的道具 |
| `AdminPanelBaseProps` | 管理面板组件的道具 |
| `AgentManifestInfo` | 代理显示元数据 |
| `AgentRouteLoadContext` | 正常的 SvelteKit 负载上下文 |
| `AgentRouteLoadFn` | 服务器加载函数类型 |
| `AgentUIComponentRegistry` | 组成部分登记册类型 |
| `ComponentType` | 一般组件类型 |

### Vite 导出( E)`@happyvertical/smrt-agents/vite`(中文(简体) )

| 导出 | 说明 |
| --- | --- |
| `vitePluginAgentRoutes` | 虚拟插件 `virtual:smrt-agent-registrations` |
| `AgentRoutesPluginOptions` | 插件选项类型 |

## 依赖关系

-   `@happyvertical/smrt-core` - ORM基础课程
-   `@happyvertical/smrt-config` -- 配置管理
-   `@happyvertical/smrt-tenancy` - 多租户背景
-   `@happyvertical/ai` -- AI 客户端 (SDK)
-   `@happyvertical/files` - 文件系统公用设施(SDK)
-   `@happyvertical/utils` -- -- 共享公用事业
-   `@happyvertical/smrt-ui` -- UI 运行时间( i18n 客户端、 原始客户端、 模块注册) `./svelte` 组件,包括剂-剂壳`AgentAdminPanel`, (中文(简体) ), `AgentAdminTabs`, (中文(简体) ), `AgentSettingsShell`从1589年的smrt-svelte搬到这里
-   端点( 可选) : `svelte`

## 常见问题

### @happyvertical/smrt-agents 是什么？

在SMRT生态系统中建立自主行为体的代理框架

### 如何安装 @happyvertical/smrt-agents？

在项目目录运行 npm install @happyvertical/smrt-agents，或使用 pnpm add / yarn add / bun add。

### @happyvertical/smrt-agents 支持 TypeScript 吗？

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

### @happyvertical/smrt-agents 支持 ESM 还是 CommonJS？

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

### @happyvertical/smrt-agents 可以商用吗？

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

### @happyvertical/smrt-agents 的下载量有多少？

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

### @happyvertical/smrt-agents 还在维护吗？

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

