@gt-fe/eap-runtime 0.0.8

package/dist/checkpoint/hybrid-checkpoint-saver.d.ts

@@ -0,0 +1,130 @@
+/**
+ * HybridCheckpointSaver — 混合 Checkpoint 存储策略
+ *
+ * 实现定期全量 + 增量的混合存储策略：
+ * - 每 N 次 checkpoint 存一次全量快照
+ * - 其余存增量（state_diff + message_ids）
+ * - 恢复时从最近全量快照 + 后续增量重建
+ *
+ * @see design.md §7.6 Checkpoint 策略
+ * @see checkpoint/contracts/checkpoint-saver.contract.ts
+ */
+import type { ICheckpointSaver } from './contracts/checkpoint-saver.contract.js';
+import type { CheckpointData } from '../graph/contracts/executable-graph.js';
+/**
+ * Checkpoint 类型
+ */
+export type CheckpointType = 'full' | 'incremental';
+/**
+ * 增量 Checkpoint 数据
+ */
+export interface IncrementalCheckpointData {
+    /** Checkpoint ID */
+    checkpointId: string;
+    /** 线程 ID */
+    threadId: string;
+    /** Checkpoint 类型 */
+    type: CheckpointType;
+    /** 状态差异（仅增量） */
+    stateDiff?: Record<string, unknown>;
+    /** 消息 ID 列表（仅增量） */
+    messageIds?: string[];
+    /** 完整状态（仅全量） */
+    fullState?: Record<string, unknown>;
+    /** 元数据 */
+    metadata: {
+        /** 父 Checkpoint ID */
+        parentCheckpointId?: string;
+        /** 当前节点 ID */
+        currentNodeId: string;
+        /** 历史路径 */
+        historyPath: string[];
+        /** 创建时间 */
+        createdAt: string;
+    };
+}
+/**
+ * 混合存储配置
+ */
+export interface HybridCheckpointConfig {
+    /** 全量快照频率（每 N 次 checkpoint） */
+    fullSnapshotFrequency: number;
+    /** 是否启用压缩（state_diff 最小化） */
+    enableCompression: boolean;
+}
+/**
+ * 默认配置
+ */
+export declare const DEFAULT_HYBRID_CONFIG: HybridCheckpointConfig;
+/**
+ * HybridCheckpointSaver — 混合 Checkpoint 存储
+ *
+ * 组合全量和增量存储，优化存储空间和恢复速度。
+ */
+export declare class HybridCheckpointSaver implements ICheckpointSaver {
+    private readonly db;
+    private readonly config;
+    private checkpointCount;
+    private lastFullCheckpointId;
+    constructor(db: ICheckpointSaver, config?: Partial<HybridCheckpointConfig>);
+    /**
+     * 保存 Checkpoint（自动判断全量/增量）
+     */
+    save(threadId: string, data: CheckpointData): Promise<void>;
+    /**
+     * 加载最新 Checkpoint
+     */
+    load(threadId: string): Promise<CheckpointData | null>;
+    /**
+     * 按 Checkpoint ID 加载
+     */
+    loadByCheckpointId(checkpointId: string): Promise<CheckpointData | null>;
+    /**
+     * 列出所有 Checkpoint
+     */
+    list(threadId: string): Promise<CheckpointData[]>;
+    /**
+     * 重建完整状态（从全量快照 + 增量）
+     *
+     * @param threadId - 线程 ID
+     * @param targetCheckpointId - 目标 Checkpoint ID
+     * @returns 重建的 Checkpoint 数据
+     */
+    rebuild(threadId: string, targetCheckpointId: string): Promise<CheckpointData | null>;
+    /**
+     * 获取配置
+     */
+    getConfig(): HybridCheckpointConfig;
+    /**
+     * 获取 Checkpoint 计数
+     */
+    getCheckpointCount(): number;
+    /**
+     * 保存全量快照
+     */
+    private saveFull;
+    /**
+     * 保存增量快照
+     */
+    private saveIncremental;
+    /**
+     * 获取最新的 Checkpoint
+     */
+    private getLatestCheckpoint;
+    /**
+     * 计算状态差异（简单实现）
+     *
+     * 实际应用中可能需要使用 deep-diff 库或自定义 diff 算法。
+     */
+    private calculateDiff;
+    /**
+     * 合并状态（简单实现）
+     *
+     * 实际应用中可能需要使用 deepmerge 库。
+     */
+    private mergeState;
+    /**
+     * Fork: 从指定 Checkpoint 创建新的执行线程
+     */
+    fork(sourceCheckpointId: string, newThreadId: string, overrides?: Record<string, unknown>): Promise<import('../graph/contracts/executable-graph.js').CheckpointData>;
+}

package/dist/checkpoint/hybrid-checkpoint-saver.js

@@ -0,0 +1,211 @@
+/**
+ * HybridCheckpointSaver — 混合 Checkpoint 存储策略
+ *
+ * 实现定期全量 + 增量的混合存储策略：
+ * - 每 N 次 checkpoint 存一次全量快照
+ * - 其余存增量（state_diff + message_ids）
+ * - 恢复时从最近全量快照 + 后续增量重建
+ *
+ * @see design.md §7.6 Checkpoint 策略
+ * @see checkpoint/contracts/checkpoint-saver.contract.ts
+ */
+/**
+ * 默认配置
+ */
+export const DEFAULT_HYBRID_CONFIG = {
+    fullSnapshotFrequency: 10,
+    enableCompression: true,
+};
+// ─────────────────────────────────────────────
+// HybridCheckpointSaver
+// ─────────────────────────────────────────────
+/**
+ * HybridCheckpointSaver — 混合 Checkpoint 存储
+ *
+ * 组合全量和增量存储，优化存储空间和恢复速度。
+ */
+export class HybridCheckpointSaver {
+    db;
+    config;
+    checkpointCount = 0;
+    lastFullCheckpointId = null;
+    constructor(db, config) {
+        this.db = db;
+        this.config = { ...DEFAULT_HYBRID_CONFIG, ...config };
+    }
+    /**
+     * 保存 Checkpoint（自动判断全量/增量）
+     */
+    async save(threadId, data) {
+        this.checkpointCount++;
+        // 判断是否需要全量快照
+        const isFullSnapshot = this.checkpointCount % this.config.fullSnapshotFrequency === 0
+            || this.lastFullCheckpointId === null;
+        if (isFullSnapshot) {
+            // 全量快照
+            await this.saveFull(threadId, data);
+            this.lastFullCheckpointId = data.checkpointId;
+        }
+        else {
+            // 增量快照
+            await this.saveIncremental(threadId, data);
+        }
+    }
+    /**
+     * 加载最新 Checkpoint
+     */
+    async load(threadId) {
+        return this.db.load(threadId);
+    }
+    /**
+     * 按 Checkpoint ID 加载
+     */
+    async loadByCheckpointId(checkpointId) {
+        return this.db.loadByCheckpointId(checkpointId);
+    }
+    /**
+     * 列出所有 Checkpoint
+     */
+    async list(threadId) {
+        return this.db.list(threadId);
+    }
+    /**
+     * 重建完整状态（从全量快照 + 增量）
+     *
+     * @param threadId - 线程 ID
+     * @param targetCheckpointId - 目标 Checkpoint ID
+     * @returns 重建的 Checkpoint 数据
+     */
+    async rebuild(threadId, targetCheckpointId) {
+        // 获取所有 Checkpoint
+        const checkpoints = await this.db.list(threadId);
+        if (checkpoints.length === 0) {
+            return null;
+        }
+        // 找到目标 Checkpoint
+        const targetIndex = checkpoints.findIndex((cp) => cp.checkpointId === targetCheckpointId);
+        if (targetIndex === -1) {
+            return null;
+        }
+        // 向前找到最近的全量快照
+        let fullSnapshotIndex = targetIndex;
+        while (fullSnapshotIndex >= 0) {
+            const cp = checkpoints[fullSnapshotIndex];
+            // 全量快照有完整的 state
+            if (cp.state && Object.keys(cp.state).length > 0) {
+                break;
+            }
+            fullSnapshotIndex--;
+        }
+        if (fullSnapshotIndex < 0) {
+            // 没有找到全量快照，返回目标 Checkpoint（可能是全量的）
+            return checkpoints[targetIndex];
+        }
+        // 从全量快照开始重建
+        const fullSnapshot = checkpoints[fullSnapshotIndex];
+        let currentState = { ...fullSnapshot.state };
+        // 应用后续的增量更新
+        for (let i = fullSnapshotIndex + 1; i <= targetIndex; i++) {
+            const incremental = checkpoints[i];
+            // 合并增量状态（简单合并，实际可能需要更复杂的 diff/patch 逻辑）
+            currentState = this.mergeState(currentState, incremental.state);
+        }
+        return {
+            ...checkpoints[targetIndex],
+            state: currentState,
+        };
+    }
+    /**
+     * 获取配置
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * 获取 Checkpoint 计数
+     */
+    getCheckpointCount() {
+        return this.checkpointCount;
+    }
+    // ─────────────────────────────────────────────
+    // Private
+    // ─────────────────────────────────────────────
+    /**
+     * 保存全量快照
+     */
+    async saveFull(threadId, data) {
+        // 全量快照直接保存
+        await this.db.save(threadId, data);
+    }
+    /**
+     * 保存增量快照
+     */
+    async saveIncremental(threadId, data) {
+        // 获取上一个 Checkpoint 的状态
+        const previousCheckpoint = await this.getLatestCheckpoint(threadId);
+        // 计算 state diff（简单实现：只保存变化的部分）
+        const stateDiff = previousCheckpoint
+            ? this.calculateDiff(previousCheckpoint.state, data.state)
+            : data.state;
+        // 保存增量（使用原始接口，但标记为增量）
+        const incrementalData = {
+            ...data,
+            state: stateDiff,
+        };
+        await this.db.save(threadId, incrementalData);
+    }
+    /**
+     * 获取最新的 Checkpoint
+     */
+    async getLatestCheckpoint(threadId) {
+        const checkpoints = await this.db.list(threadId);
+        return checkpoints.length > 0 ? checkpoints[checkpoints.length - 1] : null;
+    }
+    /**
+     * 计算状态差异（简单实现）
+     *
+     * 实际应用中可能需要使用 deep-diff 库或自定义 diff 算法。
+     */
+    calculateDiff(previous, current) {
+        const diff = {};
+        for (const key of Object.keys(current)) {
+            if (JSON.stringify(previous[key]) !== JSON.stringify(current[key])) {
+                diff[key] = current[key];
+            }
+        }
+        return diff;
+    }
+    /**
+     * 合并状态（简单实现）
+     *
+     * 实际应用中可能需要使用 deepmerge 库。
+     */
+    mergeState(base, overlay) {
+        return { ...base, ...overlay };
+    }
+    /**
+     * Fork: 从指定 Checkpoint 创建新的执行线程
+     */
+    async fork(sourceCheckpointId, newThreadId, overrides) {
+        const source = await this.loadByCheckpointId(sourceCheckpointId);
+        if (!source) {
+            throw new Error(`Source checkpoint not found: ${sourceCheckpointId}`);
+        }
+        const now = new Date().toISOString();
+        const { randomUUID } = await import('node:crypto');
+        const newData = {
+            checkpointId: randomUUID(),
+            threadId: newThreadId,
+            currentNodeId: source.currentNodeId,
+            historyPath: source.historyPath,
+            state: overrides ? { ...source.state, ...overrides } : source.state,
+            createdBy: 'fork',
+            createdAt: now,
+            updatedBy: 'fork',
+            updatedAt: now,
+            isDeleted: false,
+        };
+        await this.save(newThreadId, newData);
+        return newData;
+    }
+}

package/dist/checkpoint/in-memory-checkpoint-saver.d.ts

@@ -0,0 +1,14 @@
+/**
+ * InMemoryCheckpointSaver — 测试用内存 Checkpoint 存储
+ */
+import type { ICheckpointSaver } from './contracts/checkpoint-saver.contract.js';
+import type { CheckpointData } from '../graph/contracts/executable-graph.js';
+export declare class InMemoryCheckpointSaver implements ICheckpointSaver {
+    private readonly byThread;
+    private readonly byId;
+    save(threadId: string, data: CheckpointData): Promise<void>;
+    load(threadId: string): Promise<CheckpointData | null>;
+    loadByCheckpointId(checkpointId: string): Promise<CheckpointData | null>;
+    list(threadId: string): Promise<CheckpointData[]>;
+    fork(checkpointId: string, newThreadId: string): Promise<CheckpointData>;
+}

package/dist/checkpoint/in-memory-checkpoint-saver.js

@@ -0,0 +1,46 @@
+/**
+ * InMemoryCheckpointSaver — 测试用内存 Checkpoint 存储
+ */
+export class InMemoryCheckpointSaver {
+    byThread = new Map();
+    byId = new Map();
+    async save(threadId, data) {
+        const list = this.byThread.get(threadId) ?? [];
+        const idx = list.findIndex((c) => c.checkpointId === data.checkpointId);
+        if (idx >= 0) {
+            list[idx] = data;
+        }
+        else {
+            list.push(data);
+        }
+        this.byThread.set(threadId, list);
+        this.byId.set(data.checkpointId, data);
+    }
+    async load(threadId) {
+        const list = this.byThread.get(threadId);
+        if (!list || list.length === 0)
+            return null;
+        return list[list.length - 1] ?? null;
+    }
+    async loadByCheckpointId(checkpointId) {
+        return this.byId.get(checkpointId) ?? null;
+    }
+    async list(threadId) {
+        return [...(this.byThread.get(threadId) ?? [])];
+    }
+    async fork(checkpointId, newThreadId) {
+        const source = await this.loadByCheckpointId(checkpointId);
+        if (!source) {
+            throw new Error(`Checkpoint not found: ${checkpointId}`);
+        }
+        const forked = {
+            ...source,
+            checkpointId: `cp-fork-${Date.now()}`,
+            threadId: newThreadId,
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+        };
+        await this.save(newThreadId, forked);
+        return forked;
+    }
+}

package/dist/checkpoint/index.d.ts

@@ -0,0 +1,16 @@
+export * from './contracts/index.js';
+export { RedisCheckpointSaver } from './redis-checkpoint-saver.js';
+export type { RedisCheckpointSaverOptions } from './redis-checkpoint-saver.js';
+export { CompositeCheckpointSaver } from './composite-checkpoint-saver.js';
+export { restoreCheckpoint } from './restore-checkpoint.js';
+export { createCheckpointData, serializeCheckpoint, deserializeCheckpoint, } from './checkpoint-serializer.js';
+export type { CreateCheckpointParams } from './checkpoint-serializer.js';
+export { FileCheckpointSaver } from './file-checkpoint-saver.js';
+export { InMemoryCheckpointSaver } from './in-memory-checkpoint-saver.js';
+export { MongoCheckpointSaver } from './mongo-checkpoint-saver.js';
+export type { IMongoCollection, CheckpointDocument } from './mongo-checkpoint-saver.js';
+export { PostgresCheckpointSaver } from './pg-checkpoint-saver.js';
+export type { IPgPool } from './pg-checkpoint-saver.js';
+export { HybridCheckpointSaver } from './hybrid-checkpoint-saver.js';
+export type { HybridCheckpointConfig, CheckpointType, IncrementalCheckpointData, } from './hybrid-checkpoint-saver.js';
+export { DEFAULT_HYBRID_CONFIG } from './hybrid-checkpoint-saver.js';

package/dist/checkpoint/index.js

@@ -0,0 +1,13 @@
+// Checkpoint — 状态快照持久化模块
+export * from './contracts/index.js';
+export { RedisCheckpointSaver } from './redis-checkpoint-saver.js';
+export { CompositeCheckpointSaver } from './composite-checkpoint-saver.js';
+export { restoreCheckpoint } from './restore-checkpoint.js';
+export { createCheckpointData, serializeCheckpoint, deserializeCheckpoint, } from './checkpoint-serializer.js';
+export { FileCheckpointSaver } from './file-checkpoint-saver.js';
+export { InMemoryCheckpointSaver } from './in-memory-checkpoint-saver.js';
+export { MongoCheckpointSaver } from './mongo-checkpoint-saver.js';
+export { PostgresCheckpointSaver } from './pg-checkpoint-saver.js';
+// 混合 Checkpoint 策略
+export { HybridCheckpointSaver } from './hybrid-checkpoint-saver.js';
+export { DEFAULT_HYBRID_CONFIG } from './hybrid-checkpoint-saver.js';

package/dist/checkpoint/mongo-checkpoint-saver.d.ts

@@ -0,0 +1,38 @@
+/**
+ * MongoCheckpointSaver — MongoDB 存储
+ * 适用场景：NoSQL 存储需求
+ *
+ * 使用接口抽象，不引入 mongodb 依赖。
+ */
+import type { ICheckpointSaver } from './contracts/checkpoint-saver.contract.js';
+import type { CheckpointData } from '../graph/contracts/executable-graph.js';
+/** MongoDB collection 抽象接口 */
+export interface IMongoCollection<T> {
+    insertOne(doc: T): Promise<{
+        insertedId: unknown;
+    }>;
+    findOne(filter: Record<string, unknown>): Promise<T | null>;
+    find(filter: Record<string, unknown>): {
+        sort(s: Record<string, unknown>): {
+            toArray(): Promise<T[]>;
+        };
+    };
+    deleteOne(filter: Record<string, unknown>): Promise<{
+        deletedCount: number;
+    }>;
+}
+export interface CheckpointDocument extends CheckpointData {
+    _id?: unknown;
+}
+export declare class MongoCheckpointSaver implements ICheckpointSaver {
+    private readonly collection;
+    constructor(collection: IMongoCollection<CheckpointDocument>);
+    save(threadId: string, data: CheckpointData): Promise<void>;
+    load(threadId: string): Promise<CheckpointData | null>;
+    loadByCheckpointId(checkpointId: string): Promise<CheckpointData | null>;
+    list(threadId: string): Promise<CheckpointData[]>;
+    /**
+     * Fork: 从指定 Checkpoint 创建新的执行线程
+     */
+    fork(sourceCheckpointId: string, newThreadId: string, overrides?: Record<string, unknown>): Promise<import('../graph/contracts/executable-graph.js').CheckpointData>;
+}

package/dist/checkpoint/mongo-checkpoint-saver.js

@@ -0,0 +1,56 @@
+/**
+ * MongoCheckpointSaver — MongoDB 存储
+ * 适用场景：NoSQL 存储需求
+ *
+ * 使用接口抽象，不引入 mongodb 依赖。
+ */
+export class MongoCheckpointSaver {
+    collection;
+    constructor(collection) {
+        this.collection = collection;
+    }
+    async save(threadId, data) {
+        await this.collection.insertOne({ ...data, threadId });
+    }
+    async load(threadId) {
+        const docs = await this.collection
+            .find({ threadId })
+            .sort({ createdAt: -1 })
+            .toArray();
+        return docs[0] ?? null;
+    }
+    async loadByCheckpointId(checkpointId) {
+        return this.collection.findOne({ checkpointId });
+    }
+    async list(threadId) {
+        return this.collection
+            .find({ threadId })
+            .sort({ createdAt: 1 })
+            .toArray();
+    }
+    /**
+     * Fork: 从指定 Checkpoint 创建新的执行线程
+     */
+    async fork(sourceCheckpointId, newThreadId, overrides) {
+        const source = await this.loadByCheckpointId(sourceCheckpointId);
+        if (!source) {
+            throw new Error(`Source checkpoint not found: ${sourceCheckpointId}`);
+        }
+        const now = new Date().toISOString();
+        const { randomUUID } = await import('node:crypto');
+        const newData = {
+            checkpointId: randomUUID(),
+            threadId: newThreadId,
+            currentNodeId: source.currentNodeId,
+            historyPath: source.historyPath,
+            state: overrides ? { ...source.state, ...overrides } : source.state,
+            createdBy: 'fork',
+            createdAt: now,
+            updatedBy: 'fork',
+            updatedAt: now,
+            isDeleted: false,
+        };
+        await this.save(newThreadId, newData);
+        return newData;
+    }
+}

package/dist/checkpoint/pg-checkpoint-saver.d.ts

@@ -0,0 +1,59 @@
+/**
+ * PostgresCheckpointSaver — PostgreSQL 存储（主存储）
+ *
+ * 使用接口抽象，不引入 pg 依赖。参数占位符用 $1/$2 替代 MySQL 的 ?。
+ * 支持审计字段和软删除。
+ *
+ * @see design.md §1.3 checkpoints 数据模型
+ * @see checkpoint-saver.contract.ts ICheckpointSaver 接口定义
+ */
+import type { ICheckpointSaver } from './contracts/checkpoint-saver.contract.js';
+import type { CheckpointData } from '../graph/contracts/executable-graph.js';
+/** pg Pool 抽象接口 */
+export interface IPgPool {
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<{
+        rows: T[];
+    }>;
+}
+export declare class PostgresCheckpointSaver implements ICheckpointSaver {
+    private readonly pool;
+    constructor(pool: IPgPool);
+    /**
+     * 持久化 Checkpoint（INSERT or UPDATE）
+     */
+    save(threadId: string, data: CheckpointData): Promise<void>;
+    /**
+     * 加载指定 thread 的最新 Checkpoint
+     * Excludes soft-deleted records
+     */
+    load(threadId: string): Promise<CheckpointData | null>;
+    /**
+     * 按 checkpointId 加载特定 Checkpoint
+     * Excludes soft-deleted records
+     */
+    loadByCheckpointId(checkpointId: string): Promise<CheckpointData | null>;
+    /**
+     * 列出指定 thread 的所有 Checkpoint
+     * Excludes soft-deleted records
+     */
+    list(threadId: string): Promise<CheckpointData[]>;
+    /**
+     * Soft delete checkpoint
+     */
+    softDelete(checkpointId: string, deletedBy: string): Promise<void>;
+    /**
+     * Fork：从指定 Checkpoint 创建新的执行线程
+     *
+     * 用于用户调试场景，从某个 Checkpoint 恢复执行，支持修改参数后重新执行。
+     *
+     * @param sourceCheckpointId - 源 Checkpoint ID
+     * @param newThreadId - 新线程 ID
+     * @param overrides - 覆盖的参数（可选）
+     * @returns 新的 CheckpointData
+     */
+    fork(sourceCheckpointId: string, newThreadId: string, overrides?: Record<string, unknown>): Promise<CheckpointData>;
+    /**
+     * 将 PostgreSQL 行数据转换为 CheckpointData
+     */
+    private toCheckpointData;
+}