@happyvertical/smrt-agents

中文文档
0.62.1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 2.2万

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

中文使用文档
文档目录13 节
  1. 安装
  2. 使用量
  3. 计划方法 Vs 运算符动作
  4. Schema 驱动设置
  5. API 密码
  6. 主导出( E) @happyvertical/smrt-agents (中文(简体) )
  7. 发现摘要
  8. 报告数据搜索工具
  9. 一般 Smrt 对象收集数据搜索面
  10. 服务器导出( E) @happyvertical/smrt-agents/server (中文(简体) )
  11. UI 导出( U) @happyvertical/smrt-agents/ui (中文(简体) )
  12. Vite 导出( E) @happyvertical/smrt-agents/vite (中文(简体) )
  13. 依赖关系

@ happyvertical/ smrt- 代理服务器

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

安装

pnpm add @happyvertical/smrt-agents

使用量

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 作为后退.

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状态列表:闲置/初始化/运行/错误/下沉
AgentConfigDB- 持久性代理配置模型
AgentConfigCollection代理连接的收藏
AgentSchedule基于 Cron 的日程模式_smrt_agent_schedules(中文(简体) )
AgentScheduleCollection代理列表收藏
ScheduleStatus计划状态类型
TenantAgent代理对租户与分级分辨率相接
TenantAgentCollection租户代理的收藏
TenantAgentStatus租户身份类型
ResolvedAgentAvailability分级行走后确定可用性
mergeFilters合并利息过滤器
normalizeSort将排序表达式规范化
InterestOptions利息配置类型
InterestFilter过滤定义类型
InterestResult发现结果类型
ObjectInterestConfig对象兴趣配置类型
ObjectFilter对象过滤器类型
InterestHandlerFn利息处理器函数类型
AsyncQualifierFnAsync 后过滤器修饰类型
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数字 :

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 排队线条指南,包括 拒绝状态表.

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 共发布 366 个版本,首次发布于 2026/06/23;过去 12 个月发布了 366 个版本。

版本发布日期距今
0.62.1latest2026/11/17今天
0.62.02026/11/17今天
0.61.62026/11/161 天前
0.61.52026/11/161 天前
0.61.42026/11/161 天前
0.61.32026/11/152 天前

关于 @happyvertical/smrt-agents 的常见问题

@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 和提交记录判断。