@ 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 | 状态列表:闲置/初始化/运行/错误/下沉 |
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数字 :
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