@downcity/agent 1.1.1

package/bin/service/schedule/Runtime.js

@@ -0,0 +1,64 @@
+/**
+ * Service Schedule runtime。
+ *
+ * 关键点（中文）
+ * - 使用轻量轮询驱动到点执行，避免为 MVP 引入复杂定时器注册与恢复逻辑。
+ * - runtime 重启时会把遗留 `running` 任务回退成 `pending`，然后继续补执行。
+ */
+import { ServiceScheduleStore } from "./Store.js";
+import { runDueScheduledJobs } from "./Executor.js";
+const SCHEDULE_POLL_INTERVAL_MS = 200;
+let runtimeState = null;
+/**
+ * 启动持久化调度 runtime。
+ */
+export async function startServiceScheduleRuntime(context) {
+    if (runtimeState)
+        return;
+    const store = new ServiceScheduleStore(context.rootPath);
+    const recovered = store.resetRunningJobsToPending();
+    if (recovered > 0) {
+        context.logger.warn("[schedule] recovered interrupted running jobs", {
+            recovered,
+        });
+    }
+    runtimeState = {
+        timer: null,
+        ticking: false,
+        store,
+        context,
+    };
+    const tick = async () => {
+        if (!runtimeState || runtimeState.ticking)
+            return;
+        runtimeState.ticking = true;
+        try {
+            await runDueScheduledJobs({
+                context: runtimeState.context,
+                store: runtimeState.store,
+            });
+        }
+        finally {
+            if (runtimeState) {
+                runtimeState.ticking = false;
+            }
+        }
+    };
+    await tick();
+    runtimeState.timer = setInterval(() => {
+        void tick();
+    }, SCHEDULE_POLL_INTERVAL_MS);
+}
+/**
+ * 停止持久化调度 runtime。
+ */
+export async function stopServiceScheduleRuntime() {
+    if (!runtimeState)
+        return;
+    if (runtimeState.timer) {
+        clearInterval(runtimeState.timer);
+    }
+    runtimeState.store.close();
+    runtimeState = null;
+}
+//# sourceMappingURL=Runtime.js.map

package/bin/service/schedule/Runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Runtime.js","sourceRoot":"","sources":["../../../src/service/schedule/Runtime.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEpD,MAAM,yBAAyB,GAAG,GAAG,CAAC;AAStC,IAAI,YAAY,GAAuC,IAAI,CAAC;AAE5D;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,OAAqB;IAErB,IAAI,YAAY;QAAE,OAAO;IAEzB,MAAM,KAAK,GAAG,IAAI,oBAAoB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACzD,MAAM,SAAS,GAAG,KAAK,CAAC,yBAAyB,EAAE,CAAC;IACpD,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;QAClB,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,+CAA+C,EAAE;YACnE,SAAS;SACV,CAAC,CAAC;IACL,CAAC;IAED,YAAY,GAAG;QACb,KAAK,EAAE,IAAI;QACX,OAAO,EAAE,KAAK;QACd,KAAK;QACL,OAAO;KACR,CAAC;IAEF,MAAM,IAAI,GAAG,KAAK,IAAI,EAAE;QACtB,IAAI,CAAC,YAAY,IAAI,YAAY,CAAC,OAAO;YAAE,OAAO;QAClD,YAAY,CAAC,OAAO,GAAG,IAAI,CAAC;QAC5B,IAAI,CAAC;YACH,MAAM,mBAAmB,CAAC;gBACxB,OAAO,EAAE,YAAY,CAAC,OAAO;gBAC7B,KAAK,EAAE,YAAY,CAAC,KAAK;aAC1B,CAAC,CAAC;QACL,CAAC;gBAAS,CAAC;YACT,IAAI,YAAY,EAAE,CAAC;gBACjB,YAAY,CAAC,OAAO,GAAG,KAAK,CAAC;YAC/B,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,IAAI,EAAE,CAAC;IACb,YAAY,CAAC,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;QACpC,KAAK,IAAI,EAAE,CAAC;IACd,CAAC,EAAE,yBAAyB,CAAC,CAAC;AAChC,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B;IAC9C,IAAI,CAAC,YAAY;QAAE,OAAO;IAC1B,IAAI,YAAY,CAAC,KAAK,EAAE,CAAC;QACvB,aAAa,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;IACD,YAAY,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IAC3B,YAAY,GAAG,IAAI,CAAC;AACtB,CAAC"}

package/bin/service/schedule/Schema.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Service Schedule SQLite schema。
+ *
+ * 关键点（中文）
+ * - 使用 Drizzle 定义本地调度任务表。
+ * - 仅保留 MVP 所需字段：任务目标、执行时间、状态与错误摘要。
+ */
+/**
+ * 调度任务表。
+ */
+export declare const scheduledJobsTable: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "scheduled_jobs";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "id";
+            tableName: "scheduled_jobs";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, object>;
+        serviceName: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "service_name";
+            tableName: "scheduled_jobs";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, object>;
+        actionName: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "action_name";
+            tableName: "scheduled_jobs";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, object>;
+        payloadJson: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "payload_json";
+            tableName: "scheduled_jobs";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, object>;
+        runAtMs: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "run_at_ms";
+            tableName: "scheduled_jobs";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, object>;
+        status: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "status";
+            tableName: "scheduled_jobs";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, object>;
+        error: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "error";
+            tableName: "scheduled_jobs";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, object>;
+        createdAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "created_at";
+            tableName: "scheduled_jobs";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, object>;
+        updatedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "updated_at";
+            tableName: "scheduled_jobs";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, object>;
+    };
+    dialect: "sqlite";
+}>;
+//# sourceMappingURL=Schema.d.ts.map

package/bin/service/schedule/Schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Schema.d.ts","sourceRoot":"","sources":["../../../src/service/schedule/Schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;GAEG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAoB9B,CAAC"}

package/bin/service/schedule/Schema.js

@@ -0,0 +1,26 @@
+/**
+ * Service Schedule SQLite schema。
+ *
+ * 关键点（中文）
+ * - 使用 Drizzle 定义本地调度任务表。
+ * - 仅保留 MVP 所需字段：任务目标、执行时间、状态与错误摘要。
+ */
+import { index, integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
+/**
+ * 调度任务表。
+ */
+export const scheduledJobsTable = sqliteTable("scheduled_jobs", {
+    id: text("id").primaryKey(),
+    serviceName: text("service_name").notNull(),
+    actionName: text("action_name").notNull(),
+    payloadJson: text("payload_json").notNull(),
+    runAtMs: integer("run_at_ms").notNull(),
+    status: text("status").notNull(),
+    error: text("error"),
+    createdAt: integer("created_at").notNull(),
+    updatedAt: integer("updated_at").notNull(),
+}, (table) => ({
+    statusRunAtIdx: index("scheduled_jobs_status_run_at_idx").on(table.status, table.runAtMs),
+    runAtIdx: index("scheduled_jobs_run_at_idx").on(table.runAtMs),
+}));
+//# sourceMappingURL=Schema.js.map

package/bin/service/schedule/Schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Schema.js","sourceRoot":"","sources":["../../../src/service/schedule/Schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAE5E;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,WAAW,CAC3C,gBAAgB,EAChB;IACE,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE;IAC3B,WAAW,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC,OAAO,EAAE;IAC3C,UAAU,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC,OAAO,EAAE;IACzC,WAAW,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC,OAAO,EAAE;IAC3C,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC,OAAO,EAAE;IACvC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE;IAChC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC,OAAO,EAAE;IAC1C,SAAS,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC,OAAO,EAAE;CAC3C,EACD,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACV,cAAc,EAAE,KAAK,CAAC,kCAAkC,CAAC,CAAC,EAAE,CAC1D,KAAK,CAAC,MAAM,EACZ,KAAK,CAAC,OAAO,CACd;IACD,QAAQ,EAAE,KAAK,CAAC,2BAA2B,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC;CAC/D,CAAC,CACH,CAAC"}

package/bin/service/schedule/Store.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Service Schedule 持久化存储。
+ *
+ * 关键点（中文）
+ * - 使用项目内 SQLite 持久化 one-shot service action 调度任务。
+ * - 当前模块只维护“当前状态”，不维护额外审计事件流。
+ */
+import type { CreateScheduledJobInput, ScheduledJobRecord, ScheduledJobStatus } from "../../shared/types/ServiceSchedule.js";
+/**
+ * Service Schedule Store。
+ */
+export declare class ServiceScheduleStore {
+    private readonly sqlite;
+    private readonly db;
+    constructor(projectRoot: string);
+    /**
+     * 初始化表结构。
+     */
+    private ensureSchema;
+    /**
+     * 关闭数据库连接。
+     */
+    close(): void;
+    /**
+     * 创建调度任务。
+     */
+    createJob(input: CreateScheduledJobInput): ScheduledJobRecord;
+    /**
+     * 获取单个任务。
+     */
+    getJobById(jobId: string): ScheduledJobRecord | null;
+    /**
+     * 列出指定状态的任务。
+     */
+    listJobsByStatus(statuses: ScheduledJobStatus[]): ScheduledJobRecord[];
+    /**
+     * 列出任务。
+     *
+     * 说明（中文）
+     * - 默认按 `runAtMs` 升序返回，便于排查“接下来会执行什么”。
+     * - 可选状态过滤与数量限制，避免一次输出过多记录。
+     */
+    listJobs(params?: {
+        status?: ScheduledJobStatus;
+        limit?: number;
+    }): ScheduledJobRecord[];
+    /**
+     * 列出已到点且待执行的任务。
+     */
+    listDuePendingJobs(nowMs: number): ScheduledJobRecord[];
+    /**
+     * 启动恢复时，把历史 `running` 回退到 `pending`。
+     */
+    resetRunningJobsToPending(): number;
+    /**
+     * 将任务标记为执行中。
+     *
+     * 关键点（中文）
+     * - 仅允许从 `pending` 进入 `running`，避免重复领取。
+     */
+    markJobRunning(jobId: string): boolean;
+    /**
+     * 将任务标记为成功。
+     */
+    markJobSucceeded(jobId: string): boolean;
+    /**
+     * 将任务标记为失败。
+     */
+    markJobFailed(jobId: string, error: string): boolean;
+    /**
+     * 将任务标记为取消。
+     */
+    markJobCancelled(jobId: string): boolean;
+    /**
+     * 取消待执行任务。
+     *
+     * 关键点（中文）
+     * - 仅允许取消 `pending`，避免打断已经开始执行的任务。
+     */
+    cancelPendingJob(jobId: string): boolean;
+    /**
+     * 统一写入终态。
+     */
+    private updateTerminalStatus;
+    /**
+     * 行转业务对象。
+     */
+    private toJobRecord;
+    /**
+     * 安全解析 payload JSON。
+     */
+    private parsePayloadJson;
+}
+//# sourceMappingURL=Store.d.ts.map

package/bin/service/schedule/Store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Store.d.ts","sourceRoot":"","sources":["../../../src/service/schedule/Store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH,OAAO,KAAK,EACV,uBAAuB,EACvB,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,mCAAmC,CAAC;AAO3C;;GAEG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAE3C,OAAO,CAAC,QAAQ,CAAC,EAAE,CAA6B;gBAEpC,WAAW,EAAE,MAAM;IAS/B;;OAEG;IACH,OAAO,CAAC,YAAY;IAwBpB;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,SAAS,CAAC,KAAK,EAAE,uBAAuB,GAAG,kBAAkB;IA4B7D;;OAEG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI;IAOpD;;OAEG;IACH,gBAAgB,CAAC,QAAQ,EAAE,kBAAkB,EAAE,GAAG,kBAAkB,EAAE;IAStE;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,MAAM,CAAC,EAAE,kBAAkB,CAAC;QAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,kBAAkB,EAAE;IAqBxB;;OAEG;IACH,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,EAAE;IAavD;;OAEG;IACH,yBAAyB,IAAI,MAAM;IAanC;;;;;OAKG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAiBtC;;OAEG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAOxC;;OAEG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAQpD;;OAEG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAOxC;;;;;OAKG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAiBxC;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAgB5B;;OAEG;IACH,OAAO,CAAC,WAAW;IAcnB;;OAEG;IACH,OAAO,CAAC,gBAAgB;CAOzB"}

package/bin/service/schedule/Store.js

@@ -0,0 +1,266 @@
+/**
+ * Service Schedule 持久化存储。
+ *
+ * 关键点（中文）
+ * - 使用项目内 SQLite 持久化 one-shot service action 调度任务。
+ * - 当前模块只维护“当前状态”，不维护额外审计事件流。
+ */
+import fs from "fs-extra";
+import Database from "better-sqlite3";
+import path from "node:path";
+import { and, asc, desc, eq, inArray, lte } from "drizzle-orm";
+import { drizzle } from "drizzle-orm/better-sqlite3";
+import { scheduledJobsTable } from "./Schema.js";
+import { generateId } from "../../shared/utils/Id.js";
+import { getDowncityScheduleDbPath } from "../../config/Paths.js";
+/**
+ * Service Schedule Store。
+ */
+export class ServiceScheduleStore {
+    sqlite;
+    db;
+    constructor(projectRoot) {
+        const dbPath = getDowncityScheduleDbPath(projectRoot);
+        fs.ensureDirSync(path.dirname(dbPath));
+        this.sqlite = new Database(dbPath);
+        this.sqlite.pragma("journal_mode = WAL");
+        this.db = drizzle(this.sqlite);
+        this.ensureSchema();
+    }
+    /**
+     * 初始化表结构。
+     */
+    ensureSchema() {
+        this.sqlite.exec(`
+      CREATE TABLE IF NOT EXISTS scheduled_jobs (
+        id TEXT PRIMARY KEY NOT NULL,
+        service_name TEXT NOT NULL,
+        action_name TEXT NOT NULL,
+        payload_json TEXT NOT NULL,
+        run_at_ms INTEGER NOT NULL,
+        status TEXT NOT NULL,
+        error TEXT,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL
+      );
+    `);
+        this.sqlite.exec(`
+      CREATE INDEX IF NOT EXISTS scheduled_jobs_status_run_at_idx
+      ON scheduled_jobs(status, run_at_ms);
+    `);
+        this.sqlite.exec(`
+      CREATE INDEX IF NOT EXISTS scheduled_jobs_run_at_idx
+      ON scheduled_jobs(run_at_ms);
+    `);
+    }
+    /**
+     * 关闭数据库连接。
+     */
+    close() {
+        this.sqlite.close();
+    }
+    /**
+     * 创建调度任务。
+     */
+    createJob(input) {
+        const now = Date.now();
+        const id = `sched_${generateId()}`;
+        const payloadJson = JSON.stringify(input.payload ?? null);
+        this.db.insert(scheduledJobsTable).values({
+            id,
+            serviceName: String(input.serviceName || "").trim(),
+            actionName: String(input.actionName || "").trim(),
+            payloadJson,
+            runAtMs: Math.trunc(input.runAtMs),
+            status: "pending",
+            error: null,
+            createdAt: now,
+            updatedAt: now,
+        }).run();
+        return {
+            id,
+            serviceName: String(input.serviceName || "").trim(),
+            actionName: String(input.actionName || "").trim(),
+            payload: input.payload ?? null,
+            runAtMs: Math.trunc(input.runAtMs),
+            status: "pending",
+            createdAt: now,
+            updatedAt: now,
+        };
+    }
+    /**
+     * 获取单个任务。
+     */
+    getJobById(jobId) {
+        const row = this.db.select().from(scheduledJobsTable)
+            .where(eq(scheduledJobsTable.id, String(jobId || "").trim()))
+            .get();
+        return row ? this.toJobRecord(row) : null;
+    }
+    /**
+     * 列出指定状态的任务。
+     */
+    listJobsByStatus(statuses) {
+        if (statuses.length === 0)
+            return [];
+        const rows = this.db.select().from(scheduledJobsTable)
+            .where(inArray(scheduledJobsTable.status, statuses))
+            .orderBy(asc(scheduledJobsTable.runAtMs))
+            .all();
+        return rows.map((row) => this.toJobRecord(row));
+    }
+    /**
+     * 列出任务。
+     *
+     * 说明（中文）
+     * - 默认按 `runAtMs` 升序返回，便于排查“接下来会执行什么”。
+     * - 可选状态过滤与数量限制，避免一次输出过多记录。
+     */
+    listJobs(params) {
+        const limit = typeof params?.limit === "number" && Number.isFinite(params.limit)
+            ? Math.max(1, Math.trunc(params.limit))
+            : 100;
+        const status = params?.status;
+        const query = this.db.select().from(scheduledJobsTable);
+        const rows = typeof status === "string" && status
+            ? query
+                .where(eq(scheduledJobsTable.status, status))
+                .orderBy(asc(scheduledJobsTable.runAtMs), desc(scheduledJobsTable.createdAt))
+                .limit(limit)
+                .all()
+            : query
+                .orderBy(asc(scheduledJobsTable.runAtMs), desc(scheduledJobsTable.createdAt))
+                .limit(limit)
+                .all();
+        return rows.map((row) => this.toJobRecord(row));
+    }
+    /**
+     * 列出已到点且待执行的任务。
+     */
+    listDuePendingJobs(nowMs) {
+        const rows = this.db.select().from(scheduledJobsTable)
+            .where(and(eq(scheduledJobsTable.status, "pending"), lte(scheduledJobsTable.runAtMs, Math.trunc(nowMs))))
+            .orderBy(asc(scheduledJobsTable.runAtMs))
+            .all();
+        return rows.map((row) => this.toJobRecord(row));
+    }
+    /**
+     * 启动恢复时，把历史 `running` 回退到 `pending`。
+     */
+    resetRunningJobsToPending() {
+        const now = Date.now();
+        const result = this.db.update(scheduledJobsTable)
+            .set({
+            status: "pending",
+            updatedAt: now,
+            error: null,
+        })
+            .where(eq(scheduledJobsTable.status, "running"))
+            .run();
+        return Number(result.changes || 0);
+    }
+    /**
+     * 将任务标记为执行中。
+     *
+     * 关键点（中文）
+     * - 仅允许从 `pending` 进入 `running`，避免重复领取。
+     */
+    markJobRunning(jobId) {
+        const result = this.db.update(scheduledJobsTable)
+            .set({
+            status: "running",
+            updatedAt: Date.now(),
+            error: null,
+        })
+            .where(and(eq(scheduledJobsTable.id, String(jobId || "").trim()), eq(scheduledJobsTable.status, "pending")))
+            .run();
+        return Number(result.changes || 0) > 0;
+    }
+    /**
+     * 将任务标记为成功。
+     */
+    markJobSucceeded(jobId) {
+        return this.updateTerminalStatus({
+            jobId,
+            status: "succeeded",
+        });
+    }
+    /**
+     * 将任务标记为失败。
+     */
+    markJobFailed(jobId, error) {
+        return this.updateTerminalStatus({
+            jobId,
+            status: "failed",
+            error,
+        });
+    }
+    /**
+     * 将任务标记为取消。
+     */
+    markJobCancelled(jobId) {
+        return this.updateTerminalStatus({
+            jobId,
+            status: "cancelled",
+        });
+    }
+    /**
+     * 取消待执行任务。
+     *
+     * 关键点（中文）
+     * - 仅允许取消 `pending`，避免打断已经开始执行的任务。
+     */
+    cancelPendingJob(jobId) {
+        const result = this.db.update(scheduledJobsTable)
+            .set({
+            status: "cancelled",
+            updatedAt: Date.now(),
+            error: null,
+        })
+            .where(and(eq(scheduledJobsTable.id, String(jobId || "").trim()), eq(scheduledJobsTable.status, "pending")))
+            .run();
+        return Number(result.changes || 0) > 0;
+    }
+    /**
+     * 统一写入终态。
+     */
+    updateTerminalStatus(params) {
+        const result = this.db.update(scheduledJobsTable)
+            .set({
+            status: params.status,
+            updatedAt: Date.now(),
+            error: params.error ? String(params.error) : null,
+        })
+            .where(eq(scheduledJobsTable.id, String(params.jobId || "").trim()))
+            .run();
+        return Number(result.changes || 0) > 0;
+    }
+    /**
+     * 行转业务对象。
+     */
+    toJobRecord(row) {
+        return {
+            id: row.id,
+            serviceName: row.serviceName,
+            actionName: row.actionName,
+            payload: this.parsePayloadJson(row.payloadJson),
+            runAtMs: row.runAtMs,
+            status: row.status,
+            ...(typeof row.error === "string" && row.error ? { error: row.error } : {}),
+            createdAt: row.createdAt,
+            updatedAt: row.updatedAt,
+        };
+    }
+    /**
+     * 安全解析 payload JSON。
+     */
+    parsePayloadJson(input) {
+        try {
+            return JSON.parse(String(input || "null"));
+        }
+        catch {
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=Store.js.map

package/bin/service/schedule/Store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Store.js","sourceRoot":"","sources":["../../../src/service/schedule/Store.ts"],"names":[],"mappings":"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"}

package/bin/service/schedule/Time.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Service Schedule 时间解析工具。
+ *
+ * 关键点（中文）
+ * - 统一解析 `--delay` / `--time` 对应的调度时间。
+ * - 输出统一毫秒时间戳，供 command 层与持久化层复用。
+ */
+/**
+ * 解析绝对执行时间。
+ *
+ * 支持格式（中文）
+ * - Unix 时间戳秒/毫秒
+ * - ISO 时间字符串（必须显式带时区）
+ */
+export declare function parseScheduleTimeOptionOrThrow(value: string, fieldName: string): number;
+/**
+ * 解析 command 层调度输入并归一化为绝对毫秒时间戳。
+ *
+ * 说明（中文）
+ * - `delayMs` 与 `time` 只能二选一。
+ * - 未传时返回 `undefined`，表示立即执行。
+ */
+export declare function parseScheduledRunAtMsOrThrow(params: {
+    delay?: string | number | undefined;
+    time?: string | number | undefined;
+}): number | undefined;
+/**
+ * 规范化 API/存储层传入的 runAtMs。
+ */
+export declare function normalizeRunAtMsOrThrow(value: string | number | undefined, fieldName: string): number;
+//# sourceMappingURL=Time.d.ts.map