# @alma-harness/schedule 中文文档

规范地址：https://npmcn.com/package/%40alma-harness/schedule/

版本：0\.41\.0
npm 元数据更新时间：2026-11-04T12:53:16.424Z
中文译文更新时间：2026-11-07T07:49:44.638Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：116 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：1 个
- peer 依赖：@alma-harness/core ^0\.41\.0，@alma-harness/loop ^0\.41\.0，@alma-harness/batch ^0\.41\.0，@alma-harness/execution ^0\.41\.0，@alma-harness/conversation ^0\.41\.0
- 首次发布：2026-09-03T17:14:05.789Z
- 最新版本发布：2026-11-04T12:53:16.169Z
- 近 30 天下载量：2004（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：50（近 12 个月 50 个）

## 中文简介

Alma's clock:什么是到期的,而tick a外部排程器呼叫运行它——没有进程能活下来.

## 安装

```sh
npm install @alma-harness/schedule
```

也可以使用：`pnpm add @alma-harness/schedule`、`yarn add @alma-harness/schedule`、`bun add @alma-harness/schedule`

## README

# @alma-harness/时间表

时钟 [阿尔玛](https://github.com/FabioFernandesCarneiro/alma)作为 勾选:什么是到期的,一个外部调度器为运行它而发出的呼叫。 没有 进程保持活性( spec: clock-tick) .

> **状况:1.0前.** API仍在移动中;见 [路线图](https://npmcn.com/package/docs/architecture.md#12-adoption-roadmap) 为它的位置.

## 它拥有的

-   `createSchedule({ routines, runs, runner })` —— 说 `tick({ now? })` 读取 日常商店,决定什么是到期的, 运行在日常 以FIRE的瞬间作为运行的ID,并报告 `{ at, due, runs, errors }`。 。 。 . `plan(now?)` 答案不运行. `runner` 可能是一个 解决者, `(routine) => RoutineRunner`,用于与特工的部署 每名租户 -- -- `list` 横跨每个范围。 无法成为常规 计划(区打字,坏克龙)是一个条目 `errors`; 其他人 (简体中文) 运行.
-   `register` 编号 : `cancel` ——通过时间表登记:它问跑者 以校验并读取一次调度表,所以不能运行的勾选 登记时拒绝,8点时没人看.
-   现在或现在之前的火力 发生额 `tz` (UTC缺席时), `every` 依托于 例行登记, `at` 一次,当它晚于常规 最后一场比赛。 工作程序,其提交内容尚未打开 每分每分每分 错失的起火不会重放: 故障后每天例行公事 运行一次.
-   `latestFire`, (中文(简体) ), `nextFire`, (中文(简体) ), `validateSchedule` ——纯排程计算. `nextFire(schedule, registeredAt, after)` 返回第一个 ISO 发生 严格在光标后以及在登记时或登记后,或 `undefined` 何时 筋疲力尽了 间歇时间以登记为准。 主机可能排队 此时外部唤醒, 然后重新验证当前配置和使用 土生土长的规划/要求。 该助手不授予执行权; 主机还必须安排失火后恢复的醒觉和待发状态 分批收集.
-   `createGovernedConversationRoutineRunner` 运行触发的对话; `createGovernedBatchRoutineRunner` 提交并收集背景批次. 两者都执行 `RoutineRunner`在工作前提出权利要求 执行常规 限制上限和每日上限,最多一次 保持射击。 遗产 `createRoutineRunner` 财务报告和审定财务报表 `RoutineRunnerConfig` 被删除(规格:去除-legacy-routine-runner).

## 接线

一个终点 调度员调用 Cadence。 云表调度器 分钟对 Cloud Run 服务, 最小的例是形状 它被写入;任何可以调用克龙上URL的都是时钟.

```ts
import { createSchedule } from "@alma-harness/schedule";

const schedule = createSchedule({ routines, runs, runner: (routine) => runnerFor(routine.scope) });
await schedule.register(briefing);

// Node's http, Hono, Express — the product's choice. A shared secret, or
// the platform's OIDC, decides who may tick.
app.post("/tick", async (req, res) => {
  if (req.headers["x-tick-secret"] !== process.env.TICK_SECRET) return res.status(401).end();
  res.json(await schedule.tick());
});
```

## 索偿和追偿

受管跑道需要原子 `RoutineRunStore.claim`保留 `(org, uid, routineId, runId)` 有1个行刑人, 包括分批提交和收集。 待执行的计时计划 `collectRunId`,该自定义跑道包装必须转发:它只收集 如果计划被搁置,就永远不要提交新的报告. 失去的呼叫者返回当前 记录; `running` 可以指: 活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活 转一圈 可能需要数十秒,所以主机请求超时必须允许.

在开工前继续提出索赔。 在叫水槽之前,跑者 还记录已知的会话、转弯、成本和交付散列。 如果一个过程 死亡或持续失败, `running` 永远不会过期或自动 重审,即使执行期限已过。 这是故意的 避免重复于自动恢复。 沉入错误变成 `failed` 而不自动重试:错误可能跟随 成功的外部行动.

与会话、供应商批量和目的地相对应的未解决调节运行 在记录最后结果之前 `record`年龄本身无法证明 原工人已经停止或没有分娩. 记录最终结果不会重放该运行 。 任何替换动作 核对后需要明确的操作者决定; 不删除 要求允许重试。 外部即时交货需要 一分之一的目的地,在这里并没有得到保障.

文本压制只与最后完成的交付相比较。 没有 序列化不同的相片标识或执行一条全球一度平等规则 语句。 每天的上限同样不会在解剖上保留能力 不同的火标识。 保留地 `running` 财务报告和审定财务报表 `submitted`; 删除 完成的记录结束了他们的回放保护。 在 生产; 内存参考仅能活到其过程.

**升级 :** 排出老跑者,运行 `migrateRoutineRunStore` 扩大 结果制约(保存现有记录),部署匹配 核心、时间表和Postgres软件包。 自定义仓库必须执行原子 索赔合同和打电话者必须接受 `running`运行共享 `describeRoutineRunStoreContract` 对抗每个自定义后端。 不混合旧的 仅在交付后用新的索赔协议书写的跑道.

## 永远不能做的事

-   保持计时器。 钟在外;这个包只回答.
-   重放失火,或并行运行常规.
-   持有一个供应商的SDK。 虱子是适配器.

## 财务警报政策

常规可以使用 `budget: { perTurnUsd: { usd: 0.5, onExceeded: "warn" } }`。 。 。 . 转换常规需要匹配的警告策略,且金额不超过 主机阈值( 或主机上没有每圈的上限); 验证拒绝加宽 在声称逃跑之前 一个值得信赖的谈话工厂 组成了精确的缩小 盖子 数字常规盖仍然被挡住.

已知过境点持续存在 `RoutineRun.capsCrossed` 交货前 转到水槽。 每批和持续批量警告都来自 原始管理收据。 重放返回元数据 没有其他电话,充电或交货。 按范围、 运行、 复制主机提醒 和盖子。 频率和重复警卫仍在适用.

运行 `migrateRoutineRunStore` 在部署这些匹配的核心、 循环、 调度之前 和 Postgres 软件包; 它添加 `caps_crossed` 一心奉请已上行.

## 文档

[文件索引](https://npmcn.com/package/docs/README.md) • 妇女 [建筑 第8条](https://npmcn.com/package/docs/architecture.md#8-triggered-turns-and-routines) • 妇女 [常规跑道谱](https://npmcn.com/package/docs/specs/047-routine-runner.md)

阿帕奇 - 2.0

## 管理批次常规

`createGovernedBatchRoutineRunner` 执行 `RoutineRunner` 工作常规, 所以直接传递给 `createSchedule`配置 a `GovernedBatchConfig`编辑器 `caps`, (中文(简体) ), `runs`, (中文(简体) ), `sinks`,只使用同步元数据 `plan`, (中文(简体) ), `runTimeoutMs`, (中文(简体) ), `submissionDeadlineMs` 财务报告和审定财务报表 `onBackgroundError`计划返回模型/价格, 政策/价格/产出版本、控制、消费者、结果保留和懒惰 `loadRequest`。请求必须与没有工具的批量级计划相匹配 信件被替换为原有的常规目标。 仅在上下文加载之后 保留和审计都受此制约。 每跑一跑的常规帽会收缩主机政策.

保留 `batch.configRevision` 不可改变,只要计划,提供者账户, 系统/产出政策或沉积分辨率变化。 待收款项要求 原始修订和完全例行定义. `governedRoutineBatchKey(scope, routineId, runId)` 披露批次中仅记账修复的关联性 ,包括尚未交货时.

范围集资可能重复GET并修复融资. 它从不等待 完成运行的元数据 。 只有永久索赔胜诉者 可能试图交付; 中断提交或交付未经再审。 保留 未清记录和对外对账。 返回前再次读取输出 尊重消除; 外部交货时同时消除仍然是主线. 警告来自受管制的财政收入并保留答案。 关闭失败 理由从不包含原始提供者或槽出错。 Dedupe 只比较了最后一个 成功文本散列;重复答复保留成本。 不同的火花顶 仍然是非原子的。 管理下的对话程序不是这个跑者的一部分.

## 规范的对话程序

`createGovernedConversationRoutineRunner` 手柄通过一个可信任的程序转换常规 同步 `conversation(caps)` 工厂返回 `createConversationRunner` 与 那些完全缩小的帽子。 供应匹配 `policyVersion`, (中文(简体) ), `configRevision`, (中文(简体) ), `resultContractVersion`, (中文(简体) ), `resultRetentionMs`, (中文(简体) ), `maxCalls`, (中文(简体) ), `rootDeadlineMs`, (中文(简体) ), `runTimeoutMs`编辑器 `caps`, (中文(简体) ), `runs`, (中文(简体) ), `sinks` 财务报告和审定财务报表 `onBackgroundError`配置 修订涵盖工厂的供应商账户、提示、价格、工具/简介, 结果政策和沉淀绘图。 工厂只负责配置;不能 读取上下文或执行效果。 普通可变数据由每个跑者复制; 储存、工厂和水槽的执行是可靠的主机能力.

永久性的例行索赔先于工厂和对话。 这个 在懒惰的常规目标之前,对话的承认/根/出保留 所有背景/影响。 没有描述文件,则不能提供未处理的工具。 主要和儿童 费用只来自受管制的收据;在单一汇的尝试中发出警告. `governedRoutineRootKey(scope, routineId, runId)` 暴露了会计关系.

不确定的对话和晚完成保留日常所有权以明确 调和。 在常规元数据丢失后重放根不会授权交付 . 最后内容在写送货元数据后和紧接前进行再检查 下沉访问。 中断、失败或未确认的交货从不重复. 将所有对话结果命名空间和会话登记在去除/保留中; a 外部目的地和同时出行仍需要主机调节.

可执行的构成在内存/ PostgreSQL 的调度测试中直播 在Prumo P1中,会话/根ID使用受管散列作为关联。 无效 常规数据可以在录入前同步丢出; 操作错误暴露 固定元数据,不释放不确定的工作.

## Canonical 常规引用

对话适配器现在引用 `ConversationRunner.runTurn` 与 现有的明确描述符(谱系:canonical-routine-adoption). 遗产 `run` 别名不取名. 条子 `not_admitted/routing_unavailable` 回应 以 `refused`,没有成本,没有对话根。 内容 元数据重放不会重试起火; 已修复的配置可以服务新 开火 不确定的援引、丧失的拒绝承认和中断交货 仍然不能授予新的执行权或权力.

Prumo P1现在在Cononic 运行时间上 兼管常规适配器 财务商店和128区 单独的批量结果命名空间。 其时钟/插件 仍为本地固定装置;不添加过程、实际接收者或生产调度器.

## 常见问题

### @alma-harness/schedule 是什么？

Alma's clock:什么是到期的,而tick a外部排程器呼叫运行它——没有进程能活下来\.

### 如何安装 @alma-harness/schedule？

在项目目录运行 npm install @alma-harness/schedule，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@alma-harness/core（^0\.41\.0）、@alma-harness/loop（^0\.41\.0）、@alma-harness/batch（^0\.41\.0）、@alma-harness/execution（^0\.41\.0）、@alma-harness/conversation（^0\.41\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @alma-harness/schedule 支持 TypeScript 吗？

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

### @alma-harness/schedule 支持 ESM 还是 CommonJS？

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

### @alma-harness/schedule 需要什么版本的 Node\.js？

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

### @alma-harness/schedule 可以商用吗？

@alma-harness/schedule 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @alma-harness/schedule 的下载量有多少？

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

### @alma-harness/schedule 还在维护吗？

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