feat(server): unified scheduled-job registry and scheduler; module timers moved onto it

- modules/schedules: registerScheduledJob({key, defaults, run}) registry; defaults are
  synced into scheduled_job without overriding user-changed enabled/schedule
- scheduler runs only on the io worker, one instance via pg_try_advisory_lock held on a
  dedicated connection; due = enabled and next_run_at reached, or run requested;
  jobs run in parallel, never re-entrant; interval next = finish + period, cron next match;
  run-now does not move next_run_at and merges duplicate requests; skip advances one period;
  history trimmed to the last 50 runs; interrupted runs marked failed on takeover
- agent_check jobs: trigger condition checked first, goal template rendered, runAgent
  enqueued via startRun(trigger=schedule) with allowlist and budget, one run per time slot;
  allowRecover uses the autoInvestigate grant check; results harvested back into the run
  history and optionally reported as an info decision; 3 built-in checks, off by default
- sources-identity (feeds.poll, sites.snapshot, identity.review), acquisition-organize
  (downloads.sync, cache.threshold, downloads.orchestrate, slots.reevaluate,
  subscriptions.search, subscriptions.metadata, library.reconcile) and file-manager
  (trash.purge) register jobs instead of running their own setInterval; default
  intervals unchanged; backup registered as an unconfigured placeholder
- endpoints under /schedules (admin, console session only)

TODO: pi refreshPiTokens and auth-settings session cleanup still own their timers.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

apps/server/src/modules/sources-identity/index.ts

@@ -1,3 +1,4 @@
+import { registerScheduledJob } from "../schedules/registry.ts";
 import type { ServerContext, ServerModule } from "../types.ts";
 import { registerSourcesCapabilities } from "./capabilities.ts";
 import { decisionRoutes } from "./routes/decisions.ts";
@@ -5,7 +6,7 @@ import { identityRoutes } from "./routes/identity.ts";
 import { sourcesRoutes } from "./routes/sources.ts";
 import { workbenchRoutes } from "./routes/workbench.ts";
 import { type RuntimeOverrides, SourcesRuntime } from "./runtime.ts";
-import { schedulerTick } from "./scheduler.ts";
+import { readOnlyReconcile, tickFeeds, tickReviews, tickSnapshots } from "./scheduler.ts";
 import { registerSourcesTasks, sourcesOutboxRoutes } from "./tasks.ts";
 
 /**
@@ -25,8 +26,6 @@ export function createSourcesIdentityModule(overrides: RuntimeOverrides = {}): S
     }
     return rt;
   };
-  let timer: ReturnType<typeof setInterval> | null = null;
-  let ticking: Promise<unknown> | null = null;
 
   return {
     name: "sources-identity",
@@ -45,23 +44,22 @@ export function createSourcesIdentityModule(overrides: RuntimeOverrides = {}): S
     registerCapabilities(registry, ctx) {
       registerSourcesCapabilities(registry, () => runtime(ctx));
     },
+    /** 周期扫描登记到定时任务注册表(schedules 模块的调度器驱动);周期是总扫描频率 */
     start(ctx) {
       const rt = runtime(ctx);
-      const tick = () => {
-        if (ticking) return;
-        ticking = schedulerTick(rt)
-          .catch((err) => ctx.logger.warn({ err }, "sources-identity 调度失败"))
-          .finally(() => {
-            ticking = null;
-          });
-      };
-      timer = setInterval(tick, overrides.schedulerIntervalMs ?? 30_000);
-      tick();
-    },
-    async stop() {
-      if (timer) clearInterval(timer);
-      timer = null;
-      await ticking;
+      const everyMs = overrides.schedulerIntervalMs ?? 30_000;
+      const job = (key: string, name: string, description: string, fn: (rt: SourcesRuntime) => Promise<number>) =>
+        registerScheduledJob(ctx, {
+          key,
+          defaults: { name, description, group: "collect", schedule: { type: "interval", everyMs } },
+          run: async () => {
+            if (await readOnlyReconcile(rt)) return { status: "skipped", summary: "只读对账模式" };
+            return { summary: `${await fn(rt)} 项` };
+          },
+        });
+      job("feeds.poll", "Feed 轮询", "扫描到期的 Feed 并入队抓取(每个 Feed 仍按自己的轮询间隔)", tickFeeds);
+      job("sites.snapshot", "站点快照", "扫描到周期的站点并入队快照", tickSnapshots);
+      job("identity.review", "待识别复查", "到期的待识别条目重新识别", tickReviews);
     },
   };
 }

apps/server/src/modules/sources-identity/scheduler.ts

@@ -4,6 +4,8 @@ import type { SourcesRuntime } from "./runtime.ts";
 
 // worker 后台调度:按 Feed 轮询策略发 feed.due(outbox → ingestFeed)、按站点快照周期入队 snapshotSite、
 // 按待识别池 next_review_at 入队复查。幂等键按时间槽生成,多 worker 并发也不会重复。
+// 三项分别登记为定时任务(feeds.poll / sites.snapshot / identity.review,由 schedules 模块的调度器驱动,
+// 这里的周期只是总扫描频率,每个 Feed / 站点仍按自己的策略判断是否到期);schedulerTick 依次跑三项(测试用)。
 
 export interface TickResult {
   feedsDue: number;
@@ -14,14 +16,24 @@ export interface TickResult {
 
 const REVIEW_LEASE_MS = 10 * 60_000;
 
-export async function schedulerTick(rt: SourcesRuntime): Promise<TickResult> {
-  const { ctx } = rt;
-  const automation = await ctx.settings.get("automation");
-  // 恢复后只读对账模式:禁止自动写入
-  if (automation.readOnlyReconcile) return { feedsDue: 0, snapshotsDue: 0, reviewsDue: 0, skipped: "read_only" };
-  const now = rt.now();
+/** 恢复后只读对账模式:禁止自动写入 */
+export async function readOnlyReconcile(rt: SourcesRuntime): Promise<boolean> {
+  return (await rt.ctx.settings.get("automation")).readOnlyReconcile;
+}
 
-  // Feed:到期(next_fetch_at 空或已到)且不在退避期、站点(若有)开启
+export async function schedulerTick(rt: SourcesRuntime): Promise<TickResult> {
+  if (await readOnlyReconcile(rt)) return { feedsDue: 0, snapshotsDue: 0, reviewsDue: 0, skipped: "read_only" };
+  return {
+    feedsDue: await tickFeeds(rt),
+    snapshotsDue: await tickSnapshots(rt),
+    reviewsDue: await tickReviews(rt),
+  };
+}
+
+/** Feed:到期(next_fetch_at 空或已到)且不在退避期、站点(若有)开启 → feed.due */
+export async function tickFeeds(rt: SourcesRuntime): Promise<number> {
+  const { ctx } = rt;
+  const now = rt.now();
   const feedsDue = await ctx.db.transaction().execute(async (trx) => {
     const due = await sql<{ id: string; poll_interval_sec: number }>`
       select f.id, f.poll_interval_sec from feed_source f left join site s on s.id = f.site_id
@@ -47,8 +59,13 @@ export async function schedulerTick(rt: SourcesRuntime): Promise<TickResult> {
     }
     return due.rows.length;
   });
+  return feedsDue;
+}
 
-  // 站点快照:开启快照且到周期
+/** 站点快照:开启快照且到周期 → snapshotSite */
+export async function tickSnapshots(rt: SourcesRuntime): Promise<number> {
+  const { ctx } = rt;
+  const now = rt.now();
   const sites = await sql<{ id: string; snapshot_interval_sec: number }>`
     select id, snapshot_interval_sec from site
      where enabled and snapshot_enabled and snapshot_interval_sec is not null
@@ -63,8 +80,13 @@ export async function schedulerTick(rt: SourcesRuntime): Promise<TickResult> {
       { idempotencyKey: `snapshotSite:${s.id}:${slot}`, traceId: randomUUID() },
     );
   }
+  return sites.rows.length;
+}
 
-  // 待识别池复查:到期的先顺延一个租约,避免下个 tick 重复入队
+/** 待识别池复查:到期的先顺延一个租约,避免下个 tick 重复入队 */
+export async function tickReviews(rt: SourcesRuntime): Promise<number> {
+  const { ctx } = rt;
+  const now = rt.now();
   const reviews = await ctx.db.transaction().execute(async (trx) => {
     const rows = await sql<{ id: string; source_release_id: string; attempts: number }>`
       select id, source_release_id, attempts from identity_candidate
@@ -86,5 +108,5 @@ export async function schedulerTick(rt: SourcesRuntime): Promise<TickResult> {
       { idempotencyKey: `review:${r.id}:${r.attempts}`, traceId: randomUUID() },
     );
   }
-  return { feedsDue, snapshotsDue: sites.rows.length, reviewsDue: reviews.length };
+  return reviews.length;
 }