# @cloudhal/schedules 中文文档

规范地址：https://npmcn.com/package/%40cloudhal/schedules/

版本：0\.6\.5
npm 元数据更新时间：2026-11-08T22:23:04.613Z
中文译文更新时间：2026-11-10T03:30:00.825Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：485 kB，55 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：3 个
- peer 依赖：vitest \>=3\.0\.0
- 首次发布：2026-10-20T10:49:56.328Z
- 最新版本发布：2026-11-08T22:23:04.308Z
- 近 30 天下载量：4889（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 26 个）

## 中文简介

Cloudhal时间表(RFC-0008):时间模型,RRULE子集及其句子,发布(pin, close, rl1: 散列,作曲,冲突,状态机器),自动化和运行状态,纹饰和预算核算,调度器和runDue,以及SQLite/D1 st

## 安装

```sh
npm install @cloudhal/schedules
```

也可以使用：`pnpm add @cloudhal/schedules`、`yarn add @cloudhal/schedules`、`bun add @cloudhal/schedules`

## README

# @ cloudhal/ 时间表

Cloudhal网站的预定出版和自动化([RFC-0008 (英语)](https://npmcn.com/package/docs/rfcs/0008-schedules.md), (中文(简体) ), [ADR-0023 (英语)](https://npmcn.com/package/docs/adr/0023-schedules.md):时间模型,RRULE子集,发布被固定到精确的节点版本,自动化和运行状态,花纹和预算核算,以及调度器的 `runDue` 与它的 D1/SQLite 商店.

这里的一切 **工人安全**: 任何条目均不只导入节点。 唯一的时间进入点是 `temporal-polyfill/implementation` (从未是本地或全球的) `Temporal`永远 `Temporal.Now`; Biome拒绝其他条目,并进行测试扫描存储器. `now` 总是注射.

| 条目 | 什麽 |
| --- | --- |
| `@cloudhal/schedules` | 时间模型 重现 发布模型 自动化/运行状态机器 纹身 预算, `TickMeter`,则 `Scheduler` 接口, `runDue`, (中文(简体) ), `createScheduler`。除此之外,没有存储依赖性 `SqlDriver` 类型. |
| `@cloudhal/schedules/engine` | 免费部分:发布模式,运行IDs,即时帮助者, `TickMeter`, (中文(简体) ), `releaseFinishStatements`,调度器的类型. `@cloudhal/core-ts` 通过它应用发布,所以网站Worker从不捆绑时区库. |
| `@cloudhal/schedules/time` | 仅是时间模型; `@cloudhal/core-ts/time` 重新出口(一项执行). |
| `@cloudhal/schedules/recurrence` | 仅RRULE子集(平面,验证,扩展,预设,句子). |
| `@cloudhal/schedules/sql` | `SqlScheduleStore` 结束 `SqlDriver` 用于移徙 `0017_schedules`。 。 。 . |
| `@cloudhal/schedules/testing` | `describeScheduleStoreConformance`, (中文(简体) ), `describeSchedulerConformance`, (中文(简体) ), `fakeReleaseExecutor`, (中文(简体) ), `countingDriver`, (中文(简体) ), `expectContract*` (vitest) (英语). |

## 时间(第9节)

-   `resolveLocalTime("2026-11-02T09:00", "Europe/Istanbul")` → `{ at: "2026-11-02T06:00:00.000Z", offset: "+03:00" }`。在 DST 空隙内的时间移动到下一个有效时间(`adjusted: "dst-gap"`); 重复的时间决定了它的第一个瞬间(D2).
-   `recomputeExecuteAt(when)` ——永远不早:用今天的tzdata重新解决了所储存的一时钟时间,而只有瞬间才会在后期移动(s`adjusted: "tzdata"`) (中文(简体) ).
-   `isTimeZone`, (中文(简体) ), `toLocalDateTime`, (中文(简体) ), `zoneOffset`, (中文(简体) ), `latenessSeconds`, (中文(简体) ), `canonicalInstant` (存储的形式是 `Date#toISOString()`) (中文(简体) ).

## 重复(第9.3、D3节)

`parseRule`, (中文(简体) ), `formatRule`, (中文(简体) ), `validateRecurrence` (最少1小时,最多24天), `occurrences`, (中文(简体) ), `nextOccurrence`, (中文(简体) ), `occurrencesBetween`, (中文(简体) ), `presetRule`编号 :`presetOf`, (中文(简体) ), `presetMinuteOffset`. 差距发生点向前移动,而不是被放弃(记录显示偏离RFC 5545§3.3.10);属性测试将扩展器与 `rrule-temporal` 排除了这种差别.

句子是数据 : `describeRecurrence(rec)` 返回时 `{ key, times, days?, weekdays?, monthDays?, n?, count?, until? }`· ; `renderRecurrence(sentence, "en" | "tr")` 让它与 `RECURRENCE_MESSAGES` ("每月第二个星期二上午9:07" /"Her ayın ikinci salısı"09:07").

## 释放(第6节)

-   `pinItems`, (中文(简体) ), `dependencyClosure` (与 `referencedNodeIds` 作为默认提取器, `composeRelease` (第1节): `nodes(S) = nodes(L) − ids + targets`, (中文(简体) ), `releaseConflicts` 页:1, `missingDependency`, (中文(简体) ), `planRelease`。 。 。 .
-   `RELEASE_TRANSITIONS`, (中文(简体) ), `HOLDING_STATES`, (中文(简体) ), `TERMINAL_RELEASE_STATES`, (中文(简体) ), `releaseWhen` (领先时间,地平线), `baseApprovalVerdict` (D5、D9级), `isPastLateLimit` 财务报告和审定财务报表 `nextRetryAt` (一小时规则和退后), `orderReleases` 财务报告和审定财务报表 `releaseOverlaps` (D15) (英语).

### 标识符 (表)

```
rl1   = "rl1:" + hex(SHA-256(utf8(lines.join("\n"))))
lines = ["site <siteId>"] + per item, sorted by node id (code-unit order):
        "<set|remove> <nodeId> <nodeKind> <targetRev>:<targetHash>|- <baseRev>:<baseHash>|-"

runId = "run_" + Crockford-base32(first 100 bits of SHA-256(utf8(subjectId + "\n" + occurrenceAt.toISOString())))
```

时间还没到 `rl1:` (D4)批准请求 `args_hash` 覆盖 `approvalArgs(releaseId, when)`. 释放和自动化标识是随机的(`rel_`编号 :`aut_` + 20克罗克福德字符; 租赁符是任意的每个索赔.

## 自动化(第5.3和11节)

`AUTOMATION_TRANSITIONS`, (中文(简体) ), `RUN_TRANSITIONS`, (中文(简体) ), `accountRunResult` (三次失败暂停,一次违反预算暂停), `dueOccurrences` (只有最近丢失的事件运行), `runWindow`, (中文(简体) ), `runEndsAt`, (中文(简体) ), `killSwitchPauses`编号 :`killSwitchResumes`; 纹 (`checkRunCall`, (中文(简体) ), `afterRunCall`, (中文(简体) ), `forbiddenUntrustedScopes`, (中文(简体) ), `untrustedEffectiveScopes`)预算(`checkRunBudget`, (中文(简体) ), `budgetLeft`, (中文(简体) ), `withinDailyWriteCap`) (中文(简体) ).

## 排程器(第8节)

```ts
import { createScheduler, TICK_BUDGETS, TickMeter } from "@cloudhal/schedules";
import { SqlScheduleStore } from "@cloudhal/schedules/sql";

const scheduler = createScheduler({
  openStore: (meter) => new SqlScheduleStore(meter.wrap(d1Driver)),
  newMeter: (budget) => new TickMeter(budget),
  releases: releaseExecutor({ graph, schedules }), // `@cloudhal/core-ts/releases`
  builtins, systemJobs, checkApproval, wake: "minute",
});
await scheduler.runDue(new Date(controller.scheduledTime), TICK_BUDGETS.free, "cron");
```

在实践中,每打一个电话 `runScheduledTick` 从 `@cloudhal/core-ts/releases`,用于构建图表、此商店、执行器和系统工作 `TickMeter`。 。 。 . `runClaimedRelease` 跑步结束 一个呼叫者声称自己(一个人的"现在的波兰"), `SqlScheduleStore.claimManualRun`) (中文(简体) ).

`runDue` 声称每起事件都带有一个比较和擦拭和新的租赁标志,以后每写在那个标志上时都有警卫,所以同时出现的勾勾产生一种效果(S3)。 按时间顺序(D15),每个地点一次放出一次,最多迟到一个小时(S8),进行回放并收回租约. `SqlScheduleStore.releaseFinishStatements(…, guard)` 给 `publishRelease` 声明,结束发布 附加到自己的 守卫批量.

对于API和MCP(推出步骤7-8),商店也有 `automationByKey`, (中文(简体) ), `openAgentRun`, (中文(简体) ), `readyAgentRun`, (中文(简体) ), `openManualWindow`, (中文(简体) ), `recordRunCall`, (中文(简体) ), `endAgentRunAs`, (中文(简体) ), `updateAutomation`, (中文(简体) ), `deleteAutomation`, (中文(简体) ), `retitleRelease` 财务报告和审定财务报表 `releaseLateness`。调度器 `checkApproval` 实值 `createReleaseApprovalCheck` 从 `@cloudhal/mcp-server/schedules` (由 `@cloudhal/api` 与 `releaseRights`) (中文(简体) ).

## 内建自动化设备(第11.1节,推出步骤9)

`createBuiltinRunner(sources)` 这是 `BuiltinRunner` 从事五项工作; `@cloudhal/core-ts/automations` 执行 `BuiltinSources` 超过站点图表(`graphBuiltinRunner`),以及 `runScheduledTick` 默认使用。 每份工作都是按固定步骤进行的——最多每分一分 `BUILTIN_STEP_COST[job]` 声明——并保持其立场 `automations.cursor`,因此一个大站点跨出数个滴答,它们之间的相撞继续同样的跑道. 调查结果(运行时只有JSON,最多200;计数准确)带有稳定代码:

| 任务 | 步骤 | 查找代码 | 计数 |
| --- | --- | --- | --- |
| `broken-links` | 50页活页,条目,名词和菜单;后为周行404行(taints: `broken_links`(中文(简体) ) | `broken-internal-link`, (中文(简体) ), `broken-media-reference`, (中文(简体) ), `broken-menu-target`, (中文(简体) ), `link-to-gated-content`, (中文(简体) ), `not-found-path` (带有方向调整) `proposal`(中文(简体) ) | 每个代码, `broken-links`, (中文(简体) ), `nodes-scanned`, (中文(简体) ), `links-checked` |
| `stale-content` | 200个条目的页面(仅程序字段) | `stale-entry` (最古老的第一时间) | `stale-entries`, (中文(简体) ), `entries-scanned` |
| `feed-check` | `/rss.xml`,则 `/sitemap.xml` (图: `feed_check`(中文(简体) ) | `feed-unreachable`, (中文(简体) ), `feed-invalid`, (中文(简体) ), `feed-item-incomplete`, (中文(简体) ), `feed-future-date`, (中文(简体) ), `feed-missing-entry`, (中文(简体) ), `feed-gated-node` (大门自查), `feed-asset-not-live` | 每个代码, `documents-checked`, (中文(简体) ), `feed-problems`, (中文(简体) ), `feed-errors` |
| `weekly-digest` | 一个 | `digest-published`, (中文(简体) ), `digest-scheduled`, (中文(简体) ), `digest-attention`, (中文(简体) ), `digest-open-findings` (各节) | `published`, (中文(简体) ), `scheduled`, (中文(简体) ), `needs-attention`, (中文(简体) ), `open-findings` |
| `cleanup` | 保留批次直至无保留, 然后提醒 | `stale-draft` | `runs-deleted`, (中文(简体) ), `releases-deleted`, (中文(简体) ), `findings-trimmed`, (中文(简体) ), `leases-cleared`, (中文(简体) ), `stale-runs-closed`, (中文(简体) ), `stale-drafts` |

每个内置运行也记录 `counts.steps` 财务报告和审定财务报表 `counts.statements` (预算使用情况). 读取访问者文本或获取的文档的一步返回 `taint`;运行运行立即被标记. `RunDueDeps.notify` (单位:千美元)`ScheduleNotifier`获得 `automation-findings`, (中文(简体) ), `automation-digest`, (中文(简体) ), `automation-failed` 财务报告和审定财务报表 `automation-paused` 运行结束后; Studio的通知来源于运行行 `@cloudhal/api`一个人的"现在跑"是 `SqlScheduleStore.startBuiltinNow`(单位:千美元) `manual` 运行此分钟, 接下来的勾选步骤, 之后自动化会返回到它的时间表 。 没有种子自动化:人们在 Studio(D7)中创造出种子.

每个路径的报表(按 `TickMeter`,工人自由预算40:

| 路径 | 发言 |
| --- | --- |
| 闲置勾选 | 1 (当心跳到期时,每5分钟) |
| 已公布, 未执行 | 第9条 |
| 发布, `publishRelease` 形状( 4 读取 + 8 个报表批次) | 第 18 条 |
| 出版发行 `runScheduledTick` 与真实 `publishRelease` (核心套房,没有资产blobs) | 页:1 |
| 未发行 | 第7条 |
| 回收释放(租赁期满或瞬间出错) | 第13条 |
| 内建步骤(索赔,二项声明,完成) | 第8条 |
| 内置步骤来刺穿跑道( 还要做) | 10个 |
| `broken-links` 勾选( core-ts 套接字: 活节点的一页) | 9-10岁 |
| `stale-content` 勾选 | 8-9 (中文(简体) ) |
| `feed-check` 勾选 | 第9条 |
| `weekly-digest` 勾选 | 第13条 |
| `cleanup` 勾选(保留批次/提醒草案) | 17 第8条 |
| 代理任务发生记录 | 6个 |
| 关闭代理任务窗口 | 第8条 |
| 第一勾选注册系统任务 | 3个 |
| 系统工作运行(加上工作本身) | 6个 |

## 常见问题

### @cloudhal/schedules 是什么？

Cloudhal时间表\(RFC-0008\):时间模型,RRULE子集及其句子,发布\(pin, close, rl1: 散列,作曲,冲突,状态机器\),自动化和运行状态,纹饰和预算核算,调度器和runDue,以及SQLite/D1 st

### 如何安装 @cloudhal/schedules？

在项目目录运行 npm install @cloudhal/schedules，或使用 pnpm add / yarn add / bun add。

### @cloudhal/schedules 支持 TypeScript 吗？

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

### @cloudhal/schedules 支持 ESM 还是 CommonJS？

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

### @cloudhal/schedules 需要什么版本的 Node\.js？

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

### @cloudhal/schedules 可以商用吗？

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

### @cloudhal/schedules 的下载量有多少？

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

### @cloudhal/schedules 还在维护吗？

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