自动化

自动化是后台任务——即使没人盯着也应当发生的工作。每个自动化是恰好位于 src/automations/+<lower_snake_case>.ts 的一个默认导出；文件名就是规范的自动化 ID。目录是复数——单数的 `automation/`、驼峰命名、缺少 + 前缀以及嵌套文件都会被拒绝。

定义

import { defineAutomation } from '@norbital-ai/bolt/authoring';
import { Effect } from 'effect';
import type { Api } from './$types.js';

export default defineAutomation(
  { schedule: '0 6 * * *' },
  {
    description: 'Counts every active site each morning.',
    // An automation's authority is its own: the policies it acts under, never its trigger's.
    policies: ['daily_sites_digest'],
    handler: (api: Api) =>
      Effect.gen(function* () {
        const sites = yield* api.db.query.sites.findMany({ limit: 250 });
        return { count: sites.length };
      })
  }
);

把这份声明保存为 src/automations/+daily_site_digest.ts 。

触发器

定时 ——自动化部署后按 cron 执行；新构建上线时调度生效
集合事件 ——由集合变更触发的后台工作
手动 ——`{}` 表示不声明任何自动触发；每个自动化仍可手动运行

编写业务工作流，而不是常驻进程。宿主把 handler 准入一个带连续 CPU 时段限制的一次性工作线程。等待模型与数据库设施时保留工作线程和容量槽位，暂停实际 CPU 计量，并在同一次调用内恢复；更多行可从保存的游标在后续调用中继续。成功完成的 dispatch 会记录一次工作线程 CPU；在完成前失败或被终止的 dispatch 目前不会产生计算用量观察。需要写入观察时，若 outbox 无法持久化，计量会 fail-closed。

何时使用自动化

钩子 ——在写入自身的阶段（before / after）内运行；自动化是独立的后台运行，不能加入触发它的写入
远程函数 ——由应用直接调用的请求/响应端点；自动化没有需要应答的调用方
自动化 ——定时摘要、合规检查、重试，以及任何应当独立于用户操作运行的工作；需要判断时在 handler 内使用 `api.infer`

自动化

定义

触发器

执行模型

何时使用自动化