# @ariestools/actor-engine 中文文档

规范地址：https://npmcn.com/package/%40ariestools/actor-engine/

版本：2\.0\.0
npm 元数据更新时间：2026-09-18T19:56:35.650Z
中文译文更新时间：2026-11-06T19:06:56.803Z
软件包许可：LGPL-3\.0-only

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

原始 npm 页面：https://www.npmjs.com/package/%40ariestools/actor-engine
原文对照：https://npmcn.com/package/%40ariestools/actor-engine/?lang=original
项目主页：https://ariestools.ai/
源码仓库：https://github.com/ariestools/actor-kit

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

- 包体积（解压后）：253 kB，41 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：4 个
- peer 依赖：zod ^4\.4
- 首次发布：2026-09-18T19:56:35.082Z
- 最新版本发布：2026-09-18T19:56:35.415Z
- 近 30 天下载量：3775（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 1 个）

## 中文简介

主机不可知演员和提供者引擎:配置编译、提供者解析、提供、监督和会话

## 安装

```sh
npm install @ariestools/actor-engine
```

也可以使用：`pnpm add @ariestools/actor-engine`、`yarn add @ariestools/actor-engine`、`bun add @ariestools/actor-engine`

## README

# @ riestools/ 演员引擎

主机-不可知论演员和提供者引擎.

引擎解析一个系统配置,解析一个提供者图, 设置一个定位器,构建每个演员 有自己的演员配置和 相同的提供者实例,通过限制的每个参与者视图来配置和解析,并返回一个像素可中止的会话. 它不知道哪个表面驱动它:主机包,如浏览器- kit 和 cli-kit 供应生命周期适配器,必要时提供不同的监督 政策.

重命名从 `@ariestools/actor-system`,它仍为被消耗的别名 一个释放。 见 [那个包](https://npmcn.com/package/%40ariestools/actor-system) 用于移民表.

`startActorEngine(options)` 在编译前返回控件。 订阅 安全粗糙的靴子事件, 读取不可更改的界限 `snapshot()` 记录,等待 `whenReady()`,并调用手柄的同能 `stop()` 加入清理甚至 发射时正在获取资源。 在获取期间请求停站 然后在下一个合作社 收回获得的资源 检查点没有启动后提供商或演员。 不是强迫的 中止任意工厂代码或中断已经运行的监管呼叫 . 自定义的提供商应该呼叫他们提供的 `checkActive` 在购置之间; 发射装置在建造演员之前也要检查 编译失败仍可通过 手柄。 事件带有固定的阶段/结果代码、顺序和不降级 通过毫秒,从不配置或原始错误消息。 两个都扔了 并且拒绝观察者, 默认提供方记录实际 提供方购置/处置;发射方记录 一弹一弹 完成事件表明其开始顺序,包括 失败的获取和回滚 。 资源ID是公共图表标签(从未) 机密; 不支持的字符或标签超过128个字符被编辑. 自定义提供方收到相同的选项 `diagnostics` 记者和可以使用 `traceActorEngineResource` 围绕自有业务。 主诊断汇构成 ,不能替换操作结果/错误。 内建监督记录驻地起动、待命和停站; 海关监管政策通过同一可选观察者接缝报告. 汇编后, `snapshot().plan` 获取前保留一个安全图表. `describeActorEnginePlan(compiled)` 独立披露同一投影: 节点、所需/可选边、绑定和没有可选能力 单独的遗漏数和每个收藏的可配置约束。 从来没有 包括作者/已解决的配置或工厂。 编译失败 保留事件而不假装已解决的图表存在. `renderActorEngineBoot(snapshot, 'text' | 'tree' | 'json')` 做同样的 安全的地方记录,保存缺失的图表和校正指标。 没错 不查询定位器、收集错误或传送遥测.

默认内存提供器给每个供应商工厂一个被冻结的定位器 外表上仅限于供货商宣称的依赖性 未申报 `getInstance` 财务报告和审定财务报表 `tryGetInstance` 请求拒绝 `ActorEngineDependencyAccessError`;别名不能允许额外访问. 表面没有登记或销毁方法,只载有 标准仪器上下文。 调查期间仍然可以进行 供应商的处置,并在其后被撤销,包括失败的创建和 倒转. 已经返回的提供者对象不会被撤销 。 自定义 提供者可以使用 `createActorEngineDependencyScope` 同一边界. 每个演员工厂都只接收演员的外表 依赖性,包括当主机使用自定义提供器时. 演员访问 幸存的停止钩, 在提供者发布前被取消, 关闭失败 工厂建设或一发完成。 一个居民的 `whenStopped()` 解决方案还取消了其范围,而兄弟般的行为者和提供商仍然保留 活着. `requireResidentTerminationSignals: true` 拒绝没有这个条件的居民 结构信号; 兼容性发射保留了系统排水吊销 演员没有它。 会议保留了可信任的 拥有者定位器. 特定主机的定位扩展必须如实提供 提供方,而不是通过行为者来联系.

宣告可选边距 `optionalDependencies`。汇编选择符合条件 一次执行和记录缺失,未配置的可选能力 内 `resolution.absentOptionalDependencies`。模糊性、周期性、无效 约束和所需的过渡性依赖仍然失败。 宣布缺席 可选查找返回 `undefined` 结束 `tryGetInstance`; 没有运行时间查找 选择新的提供者。 汇编的依赖性申报是不可改变的快照.

```ts
import {
  ActorEngineCatalog,
  createActorEngineProviderRegistry,
  launchActorEngine,
} from '@ariestools/actor-engine'

const actorRegistry = new ActorEngineCatalog()
const providerRegistry = createActorEngineProviderRegistry()

const session = await launchActorEngine({
  actorRegistry,
  config,
  providerRegistry,
})

await session.stop()
```

需要在其中检查、验证或再利用已解决计划的主机 运行时间可以将编译与运行时间获取分开:

```ts
import {
  compileActorEngine,
  launchCompiledActorEngine,
  sequentialActorEngineSupervision,
} from '@ariestools/actor-engine'

const compiled = compileActorEngine({
  actorRegistry,
  config,
  providerRegistry,
})

// No provider has been created and no actor has been constructed or started.
console.log(compiled.providerSystem.resolution)

const session = await launchCompiledActorEngine({
  actorRegistry,
  compiled,
  supervision: sequentialActorEngineSupervision,
})
```

`parallelActorEngineSupervision` 是默认,支持动态 管弦乐. `sequentialActorEngineSupervision` 开始演员并加入他们的 在注册顺序中准备,然后倒转或倒转 秩序。 秩序。 没有结构准备状态表面的行为者被视为已做好准备 这两种政策都存在.

编译对象保留已安装的声明和提供者描述符,所以 它是一种运行时的工艺品,而不是结构化-整流线格式。 浏览器 域名通过 : 其主机适配器,然后将这些值绑定在本地登记册上.

本地运行时间主机可以设置 `requireResidentFailureSignals: true` 所以每个 居民演员必须曝光 `whenFailed()`。 。 。 . `session.whenTerminal()` 种族 指定供应商和主机/运输故障源并拒绝 a 一个 `ActorEngineTerminalFailureError` 保存资源类型、资源 身份证,稳定代码, 和原始原因。 年长者 `whenFailed()` 方法仍为 一个原始的- error相容信号.

## 监督你自己塑造的演员

建立自己行为者的东道主——而不是从一个化身中发动他们 和目录——通过同样的政策监督它们:

```ts
import { launchActors, sequentialActorEngineSupervision } from '@ariestools/actor-engine'

const session = await launchActors(actors, {
  supervision: sequentialActorEngineSupervision,
})

await session.whenTerminal().catch(handleFailure)
await session.stop()
```

`createParallelActorEngineSupervision({ orchestrator })` 监督 管弦乐家 呼叫者已经拥有。 那这个政策就只能阻止它 将管弦乐团的生命周期留给主人.

## 常见问题

### @ariestools/actor-engine 是什么？

主机不可知演员和提供者引擎:配置编译、提供者解析、提供、监督和会话

### 如何安装 @ariestools/actor-engine？

在项目目录运行 npm install @ariestools/actor-engine，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：zod（^4\.4）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @ariestools/actor-engine 支持 TypeScript 吗？

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

### @ariestools/actor-engine 支持 ESM 还是 CommonJS？

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

### @ariestools/actor-engine 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @ariestools/actor-engine 可以商用吗？

@ariestools/actor-engine 使用 LGPL-3\.0-only 许可。弱 Copyleft：作为库被调用时通常不要求开源你自己的代码，但修改库本身需以 LGPL 开源；前端打包合并后的适用边界存在不同理解。以上为概括，不构成法律意见，请以许可原文为准。

### @ariestools/actor-engine 的下载量有多少？

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

### @ariestools/actor-engine 还在维护吗？

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