@gt-fe/eap-runtime 0.0.8

package/dist/server.js

@@ -0,0 +1,161 @@
+/**
+ * @eap/runtime HTTP 服务入口
+ *
+ * Phase 1 独立部署模式：包装 InvokeOrchestrator / StreamOrchestrator 为 REST API。
+ * Phase 2+ 推荐由 hosting-service 内嵌 SDK，本服务可选。
+ *
+ * TODO: Phase 2 将本文件迁移至 dev-tools/cli（作为 `eap dev` 命令实现），
+ *       runtime 包不再包含 HTTP 服务代码，仅作为纯库导出。
+ */
+import { ErrorCodes } from '@gt-fe/eap-contracts';
+import { createServer } from 'node:http';
+import { URL } from 'node:url';
+import { resolveExecutionContext } from './governance/index.js';
+import { createTaskRouteHandlers, createDevRuntime, } from './index.js';
+import { sendErrorJson } from './utils/http-error.js';
+const port = parseInt(process.env.EAP_RUNTIME_PORT ?? process.env.PORT ?? '3000', 10);
+const host = process.env.EAP_RUNTIME_HOST ?? process.env.HOST ?? '0.0.0.0';
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on('data', (chunk) => chunks.push(chunk));
+        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+        req.on('error', reject);
+    });
+}
+function sendJson(res, status, body) {
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(body));
+}
+// 组装运行时依赖（全部委托给 createDevRuntime 工厂，保证 CLI 嵌入模式与 HTTP 模式 DI 一致）
+const devRuntime = createDevRuntime();
+const { invokeOrchestrator, streamOrchestrator, taskService } = devRuntime;
+const { llmProviderKind, governanceKind, sessionStoreKind, messageStoreKind, checkpointKind, storageProfile, foundationConfigured, deploymentContext, toolExecutionMode, } = devRuntime.diagnostics;
+const taskHandlers = createTaskRouteHandlers(taskService);
+const devHttpEnabled = process.env.EAP_DEV_HTTP === '1' || process.env.EAP_DEV_HTTP === 'true';
+const server = createServer(async (req, res) => {
+    const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+    if (req.method === 'GET' && url.pathname === '/health') {
+        sendJson(res, 200, { status: 'ok', timestamp: new Date().toISOString(), devHttp: devHttpEnabled });
+        return;
+    }
+    if (!devHttpEnabled) {
+        sendJson(res, 404, {
+            code: ErrorCodes.PLATFORM_ROUTE_NOT_FOUND,
+            message: 'Runtime HTTP is dev-only. Set EAP_DEV_HTTP=1 for local invoke/stream, or use Hosting.',
+        });
+        return;
+    }
+    if (req.method === 'GET' && url.pathname === '/metrics') {
+        sendJson(res, 200, {
+            mode: 'standalone',
+            checkpointDir: process.env.EAP_CHECKPOINT_DIR ?? '/tmp/eap-checkpoints',
+            foundationUrl: process.env.FOUNDATION_SERVICE_URL ?? 'http://localhost:3100',
+        });
+        return;
+    }
+    const invokeMatch = url.pathname.match(/^\/api\/v1\/agents\/([^/]+)\/invoke$/);
+    if (req.method === 'POST' && invokeMatch) {
+        try {
+            const body = JSON.parse(await readBody(req));
+            const authHeader = req.headers.authorization;
+            const delegationToken = authHeader?.startsWith('Bearer ') ? authHeader.slice(7).trim() : undefined;
+            const userId = req.headers['x-user-id'] ?? body.userId ?? 'anonymous';
+            const agentCode = invokeMatch[1];
+            const executionContext = body.executionContext ??
+                resolveExecutionContext({ agentCode, sessionId: body.sessionId, userId }, userId, { delegationToken });
+            const result = await invokeOrchestrator.execute({
+                agentCode,
+                input: body.input ?? '',
+                sessionId: body.sessionId,
+                userId,
+                config: body.config,
+                executionContext,
+            }, userId);
+            sendJson(res, result.code === 'ok' ? 200 : 500, result);
+        }
+        catch (error) {
+            sendErrorJson(res, error);
+        }
+        return;
+    }
+    const streamMatch = url.pathname.match(/^\/api\/v1\/agents\/([^/]+)\/stream$/);
+    if (req.method === 'POST' && streamMatch) {
+        try {
+            const body = JSON.parse(await readBody(req));
+            const authHeader = req.headers.authorization;
+            const delegationToken = authHeader?.startsWith('Bearer ') ? authHeader.slice(7).trim() : undefined;
+            const userId = req.headers['x-user-id'] ?? body.userId ?? 'anonymous';
+            const agentCode = streamMatch[1];
+            const executionContext = body.executionContext ??
+                resolveExecutionContext({ agentCode, sessionId: body.sessionId, userId }, userId, { delegationToken });
+            await streamOrchestrator.execute({
+                agentCode,
+                input: body.input ?? '',
+                sessionId: body.sessionId,
+                userId,
+                executionContext,
+            }, res, userId);
+        }
+        catch (error) {
+            sendErrorJson(res, error);
+        }
+        return;
+    }
+    const taskStatusMatch = url.pathname.match(/^\/api\/v1\/tasks\/([^/]+)\/status$/);
+    if (req.method === 'GET' && taskStatusMatch) {
+        const result = await taskHandlers.getTaskStatusHandler({ taskId: taskStatusMatch[1] });
+        sendJson(res, result.code === 'ok' ? 200 : result.code === 'runtime.task.not_found' ? 404 : 500, result);
+        return;
+    }
+    const hitlMatch = url.pathname.match(/^\/api\/v1\/tasks\/([^/]+)\/hitl$/);
+    if (req.method === 'POST' && hitlMatch) {
+        const body = JSON.parse(await readBody(req));
+        const taskId = hitlMatch[1];
+        const choice = body.choice ?? 'confirm';
+        const userId = body.userId ?? 'anonymous';
+        try {
+            const result = await devRuntime.resumeHitl(taskId, { choice, userId });
+            const statusCode = result.status === 'waiting_hitl' ? 202 : 200;
+            sendJson(res, statusCode, {
+                code: 'ok',
+                data: {
+                    acknowledged: true,
+                    taskId,
+                    status: result.status,
+                    output: result.output,
+                    hitl: result.hitl,
+                },
+            });
+        }
+        catch (error) {
+            sendErrorJson(res, error);
+        }
+        return;
+    }
+    sendJson(res, 404, {
+        code: ErrorCodes.PLATFORM_ROUTE_NOT_FOUND,
+        message: `Route not found: ${req.method} ${url.pathname}`,
+    });
+});
+server.listen(port, host, () => {
+    console.log(`@eap/runtime HTTP server on ${host}:${port}`);
+    console.log(`Health: http://${host}:${port}/health`);
+    if (devHttpEnabled) {
+        console.log(`Dev HTTP enabled — Invoke: POST http://${host}:${port}/api/v1/agents/{agentCode}/invoke`);
+        // 本地闭环模式自检摘要，方便开发者快速定位环境问题
+        console.log(`  mode: ${foundationConfigured ? 'connected' : 'local-closed-loop'}`);
+        console.log(`  deploymentContext: ${deploymentContext}`);
+        console.log(`  toolExecutionMode: ${toolExecutionMode}`);
+        console.log(`  llmProvider: ${llmProviderKind}`);
+        console.log(`  governance: ${governanceKind}`);
+        console.log(`  storageProfile: ${storageProfile}`);
+        console.log(`  sessionStore: ${sessionStoreKind}`);
+        console.log(`  messageStore: ${messageStoreKind}`);
+        console.log(`  checkpoint: ${checkpointKind}`);
+    }
+    else {
+        console.log('Dev HTTP disabled — only /health exposed (set EAP_DEV_HTTP=1 for local API)');
+    }
+});
+export { server };

package/dist/session/compression-middleware.d.ts

@@ -0,0 +1,126 @@
+/**
+ * CompressionMiddleware — 压缩中间件
+ *
+ * 在 Session 加载历史消息时自动触发压缩。
+ * 集成到 SessionContextService 或独立使用。
+ *
+ * @see message-compression.service.ts 压缩接口
+ * @see session-context.service.ts 会话上下文
+ */
+import type { MessageRecord, IMessageRepository } from './session.service.js';
+import type { ILLMProvider } from '../graph/nodes/llm-node.js';
+import type { CompressionConfig, IMessageCompressionService } from '../memory/message-compression.service.js';
+import type { ICompressionRepository } from '../memory/compression/compression.repository.js';
+/**
+ * 压缩中间件配置
+ */
+export interface CompressionMiddlewareConfig {
+    /** 是否启用自动压缩（默认 true） */
+    enabled: boolean;
+    /** 压缩配置 */
+    compressionConfig?: Partial<CompressionConfig>;
+    /** 是否保存压缩记录（默认 true） */
+    saveRecord?: boolean;
+    /** 是否持久化压缩后的消息（默认 true） */
+    persistCompressed?: boolean;
+    /** 是否标记原始消息为已压缩（默认 true） */
+    markOriginals?: boolean;
+    /** LLM 配置（用于摘要生成） */
+    llmConfig?: {
+        /** LLM 提供者 */
+        provider?: ILLMProvider;
+        /** 模型名称 */
+        model?: string;
+        /** 温度参数 */
+        temperature?: number;
+        /** 最大输出 Token 数 */
+        maxTokens?: number;
+        /** 是否使用精简 Prompt */
+        concise?: boolean;
+    };
+}
+/**
+ * 默认配置
+ */
+export declare const DEFAULT_MIDDLEWARE_CONFIG: CompressionMiddlewareConfig;
+/**
+ * CompressionMiddleware — 压缩中间件
+ *
+ * 在加载历史消息时自动检查并执行压缩。
+ */
+export declare class CompressionMiddleware {
+    private readonly compression;
+    private readonly repository?;
+    private readonly messageRepository?;
+    private readonly config;
+    constructor(config?: Partial<CompressionMiddlewareConfig>, compression?: IMessageCompressionService, repository?: ICompressionRepository, messageRepository?: IMessageRepository);
+    /**
+     * 处理消息列表（自动压缩）
+     *
+     * @param messages - 原始消息列表
+     * @param context - 上下文信息（用于审计）
+     * @returns 处理后的消息列表
+     */
+    processMessages(messages: MessageRecord[], context: {
+        sessionId: string;
+        taskId?: string;
+        userId: string;
+    }): Promise<MessageRecord[]>;
+    /**
+     * 检查是否需要压缩（不执行）
+     */
+    checkCompression(messages: MessageRecord[]): {
+        needsCompression: boolean;
+        currentTokens: number;
+        currentRounds: number;
+    };
+    /**
+     * 获取配置
+     */
+    getConfig(): CompressionMiddlewareConfig;
+    /**
+     * MessageRecord 转 GraphMessage
+     */
+    private toGraphMessages;
+    /**
+     * GraphMessage 转 MessageRecord
+     */
+    private toMessageRecords;
+    /**
+     * 提取摘要内容
+     */
+    private extractSummary;
+    /**
+     * 保存压缩记录
+     */
+    private saveCompressionRecord;
+    /**
+     * 持久化压缩后的消息
+     */
+    private persistCompressedMessages;
+    /**
+     * 标记原始消息为已压缩
+     *
+     * 通过在 metadata 中添加 compressed 标记，避免重复压缩。
+     */
+    private markOriginalMessages;
+}
+/**
+ * 创建压缩中间件
+ *
+ * @param config - 配置
+ * @param repository - 压缩记录存储（可选）
+ * @param messageRepository - 消息存储（可选，用于持久化压缩后的消息）
+ * @returns CompressionMiddleware 实例
+ */
+export declare function createCompressionMiddleware(config?: Partial<CompressionMiddlewareConfig>, repository?: ICompressionRepository, messageRepository?: IMessageRepository): CompressionMiddleware;
+/**
+ * 创建带 LLM 摘要能力的压缩中间件
+ *
+ * @param provider - ILLMProvider 实例
+ * @param config - 配置
+ * @param repository - 压缩记录存储（可选）
+ * @param messageRepository - 消息存储（可选）
+ * @returns CompressionMiddleware 实例
+ */
+export declare function createCompressionMiddlewareWithLLM(provider: ILLMProvider, config?: Partial<CompressionMiddlewareConfig>, repository?: ICompressionRepository, messageRepository?: IMessageRepository): CompressionMiddleware;

package/dist/session/compression-middleware.js

@@ -0,0 +1,230 @@
+/**
+ * CompressionMiddleware — 压缩中间件
+ *
+ * 在 Session 加载历史消息时自动触发压缩。
+ * 集成到 SessionContextService 或独立使用。
+ *
+ * @see message-compression.service.ts 压缩接口
+ * @see session-context.service.ts 会话上下文
+ */
+import { SlidingWindowCompression } from '../memory/compression/sliding-window.compression.js';
+import { createSummarize } from '../memory/compression/llm-summarize.js';
+/**
+ * 默认配置
+ */
+export const DEFAULT_MIDDLEWARE_CONFIG = {
+    enabled: true,
+    saveRecord: true,
+    persistCompressed: true,
+    markOriginals: true,
+};
+// ─────────────────────────────────────────────
+// CompressionMiddleware
+// ─────────────────────────────────────────────
+/**
+ * CompressionMiddleware — 压缩中间件
+ *
+ * 在加载历史消息时自动检查并执行压缩。
+ */
+export class CompressionMiddleware {
+    compression;
+    repository;
+    messageRepository;
+    config;
+    constructor(config, compression, repository, messageRepository) {
+        this.config = { ...DEFAULT_MIDDLEWARE_CONFIG, ...config };
+        // 如果未提供 compression 实例，创建默认的
+        if (compression) {
+            this.compression = compression;
+        }
+        else {
+            // 创建摘要函数（优先使用 ILLMProvider）
+            const summarize = createSummarize({
+                provider: this.config.llmConfig?.provider,
+                model: this.config.llmConfig?.model,
+                temperature: this.config.llmConfig?.temperature,
+                maxTokens: this.config.llmConfig?.maxTokens,
+                concise: this.config.llmConfig?.concise,
+            });
+            this.compression = new SlidingWindowCompression(this.config.compressionConfig, summarize);
+        }
+        this.repository = repository;
+        this.messageRepository = messageRepository;
+    }
+    /**
+     * 处理消息列表（自动压缩）
+     *
+     * @param messages - 原始消息列表
+     * @param context - 上下文信息（用于审计）
+     * @returns 处理后的消息列表
+     */
+    async processMessages(messages, context) {
+        if (!this.config.enabled) {
+            return messages;
+        }
+        // 转换为 GraphMessage 格式进行检查
+        const graphMessages = this.toGraphMessages(messages);
+        // 检查是否需要压缩
+        const checkResult = this.compression.checkCompression(graphMessages);
+        if (!checkResult.needsCompression) {
+            return messages;
+        }
+        // 执行压缩
+        const startTime = Date.now();
+        const compressedMessages = await this.compression.compress(graphMessages);
+        const duration = Date.now() - startTime;
+        // 转换回 MessageRecord 格式
+        const compressedRecords = this.toMessageRecords(compressedMessages, messages);
+        // 持久化压缩后的消息
+        if (this.config.persistCompressed && this.messageRepository) {
+            await this.persistCompressedMessages(compressedRecords, context);
+        }
+        // 标记原始消息为已压缩
+        if (this.config.markOriginals && this.messageRepository) {
+            await this.markOriginalMessages(messages, context.userId);
+        }
+        // 保存压缩记录
+        if (this.config.saveRecord && this.repository) {
+            await this.saveCompressionRecord({
+                sessionId: context.sessionId,
+                taskId: context.taskId ?? null,
+                originalMessageCount: messages.length,
+                compressedMessageCount: compressedRecords.length,
+                originalTokens: checkResult.currentTokens,
+                compressedTokens: this.compression.estimateTokens(compressedMessages),
+                strategy: 'sliding-window',
+                summaryContent: this.extractSummary(compressedMessages),
+                createdBy: context.userId,
+                createdAt: new Date().toISOString(),
+            });
+        }
+        console.log(`[CompressionMiddleware] Compressed ${messages.length} → ${compressedRecords.length} messages ` +
+            `(${checkResult.currentTokens} → ${this.compression.estimateTokens(compressedMessages)} tokens, ` +
+            `${duration}ms)`);
+        return compressedRecords;
+    }
+    /**
+     * 检查是否需要压缩（不执行）
+     */
+    checkCompression(messages) {
+        const graphMessages = this.toGraphMessages(messages);
+        return this.compression.checkCompression(graphMessages);
+    }
+    /**
+     * 获取配置
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    // ─────────────────────────────────────────────
+    // Private
+    // ─────────────────────────────────────────────
+    /**
+     * MessageRecord 转 GraphMessage
+     */
+    toGraphMessages(messages) {
+        return messages.map((m) => ({
+            role: m.role,
+            content: m.content,
+            toolCalls: m.toolCalls,
+        }));
+    }
+    /**
+     * GraphMessage 转 MessageRecord
+     */
+    toMessageRecords(compressed, original) {
+        const now = new Date().toISOString();
+        const firstOriginal = original[0];
+        return compressed.map((m, index) => ({
+            id: `compressed-${Date.now()}-${index}`,
+            sessionId: firstOriginal?.sessionId ?? '',
+            taskId: firstOriginal?.taskId ?? null,
+            correlationId: firstOriginal?.correlationId ?? null,
+            role: m.role,
+            content: m.content,
+            toolCalls: m.toolCalls ?? null,
+            tokenCount: 0, // 会在后续计算
+            createdBy: 'system',
+            createdAt: now,
+            updatedBy: 'system',
+            updatedAt: now,
+            isDeleted: false,
+        }));
+    }
+    /**
+     * 提取摘要内容
+     */
+    extractSummary(messages) {
+        const summaryMessage = messages.find((m) => m.role === 'system' && m.content.includes('对话历史摘要'));
+        return summaryMessage?.content ?? '';
+    }
+    /**
+     * 保存压缩记录
+     */
+    async saveCompressionRecord(record) {
+        try {
+            await this.repository?.save(record);
+        }
+        catch (error) {
+            console.error('[CompressionMiddleware] Failed to save compression record:', error);
+        }
+    }
+    /**
+     * 持久化压缩后的消息
+     */
+    async persistCompressedMessages(messages, context) {
+        if (!this.messageRepository)
+            return;
+        try {
+            for (const message of messages) {
+                await this.messageRepository.save(message);
+            }
+        }
+        catch (error) {
+            console.error('[CompressionMiddleware] Failed to persist compressed messages:', error);
+        }
+    }
+    /**
+     * 标记原始消息为已压缩
+     *
+     * 通过在 metadata 中添加 compressed 标记，避免重复压缩。
+     */
+    async markOriginalMessages(messages, userId) {
+        // 注意：当前 IMessageRepository 接口没有 update 方法
+        // 这里只是记录日志，实际实现需要扩展接口
+        console.log(`[CompressionMiddleware] Would mark ${messages.length} messages as compressed (not implemented)`);
+    }
+}
+// ─────────────────────────────────────────────
+// 工厂函数
+// ─────────────────────────────────────────────
+/**
+ * 创建压缩中间件
+ *
+ * @param config - 配置
+ * @param repository - 压缩记录存储（可选）
+ * @param messageRepository - 消息存储（可选，用于持久化压缩后的消息）
+ * @returns CompressionMiddleware 实例
+ */
+export function createCompressionMiddleware(config, repository, messageRepository) {
+    return new CompressionMiddleware(config, undefined, repository, messageRepository);
+}
+/**
+ * 创建带 LLM 摘要能力的压缩中间件
+ *
+ * @param provider - ILLMProvider 实例
+ * @param config - 配置
+ * @param repository - 压缩记录存储（可选）
+ * @param messageRepository - 消息存储（可选）
+ * @returns CompressionMiddleware 实例
+ */
+export function createCompressionMiddlewareWithLLM(provider, config, repository, messageRepository) {
+    const llmConfig = {
+        provider,
+        model: config?.llmConfig?.model ?? 'DeepSeek-V4-Pro',
+        temperature: config?.llmConfig?.temperature ?? 0.3,
+        maxTokens: config?.llmConfig?.maxTokens ?? 1024,
+        concise: config?.llmConfig?.concise ?? false,
+    };
+    return new CompressionMiddleware({ ...config, llmConfig }, undefined, repository, messageRepository);
+}

package/dist/session/file-message.repository.d.ts

@@ -0,0 +1,25 @@
+/**
+ * FileMessageRepository — Message 文件持久化（dev profile）
+ *
+ * 每个 session 一个 JSON 数组文件：{baseDir}/{sessionId}.messages.json
+ * 与 FileSessionRepository 配套，支持 eap chat 进程重启后恢复多轮上下文。
+ */
+import type { MessageRecord } from './session.service.js';
+import type { IFullMessageRepository } from './message.service.js';
+export interface FileMessageRepositoryOptions {
+    /** 存储目录；建议与 Session 同根或旁路子目录 */
+    baseDir: string;
+}
+export declare class FileMessageRepository implements IFullMessageRepository {
+    private readonly baseDir;
+    constructor(options: FileMessageRepositoryOptions);
+    save(message: MessageRecord): Promise<void>;
+    saveMany(messages: MessageRecord[]): Promise<void>;
+    findBySessionId(sessionId: string, limit?: number, offset?: number): Promise<MessageRecord[]>;
+    findByTaskId(taskId: string): Promise<MessageRecord[]>;
+    markAsCompressed(messageIds: string[], compressedBy: string, compressedAt: string): Promise<void>;
+    private getFilePath;
+    private ensureDir;
+    private readAll;
+    private writeAll;
+}

package/dist/session/file-message.repository.js

@@ -0,0 +1,78 @@
+/**
+ * FileMessageRepository — Message 文件持久化（dev profile）
+ *
+ * 每个 session 一个 JSON 数组文件：{baseDir}/{sessionId}.messages.json
+ * 与 FileSessionRepository 配套，支持 eap chat 进程重启后恢复多轮上下文。
+ */
+import { join } from 'node:path';
+import { readFile, writeFile, mkdir, access } from 'node:fs/promises';
+export class FileMessageRepository {
+    baseDir;
+    constructor(options) {
+        this.baseDir = options.baseDir;
+    }
+    async save(message) {
+        await this.ensureDir();
+        const messages = await this.readAll(message.sessionId);
+        const idx = messages.findIndex((m) => m.id === message.id);
+        if (idx >= 0) {
+            messages[idx] = { ...message };
+        }
+        else {
+            messages.push({ ...message });
+        }
+        messages.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+        await this.writeAll(message.sessionId, messages);
+    }
+    async saveMany(messages) {
+        for (const message of messages) {
+            await this.save(message);
+        }
+    }
+    async findBySessionId(sessionId, limit, offset) {
+        let messages = (await this.readAll(sessionId)).filter((m) => !m.isDeleted);
+        const start = offset ?? 0;
+        if (limit !== undefined) {
+            messages = messages.slice(start, start + limit);
+        }
+        else if (start > 0) {
+            messages = messages.slice(start);
+        }
+        return messages.map((m) => ({ ...m }));
+    }
+    async findByTaskId(taskId) {
+        // 文件布局按 session；扫描成本高，dev 下按需线性扫描目录不值得——此处返回空并由调用方用 session 查询
+        void taskId;
+        return [];
+    }
+    async markAsCompressed(messageIds, compressedBy, compressedAt) {
+        // 文件实现：在匹配消息上写入 updatedBy/updatedAt（无独立 compressed 字段）
+        const idSet = new Set(messageIds);
+        // 无全局索引：无法枚举全部 session；压缩中间件在 memory/pg 场景更常用
+        void idSet;
+        void compressedBy;
+        void compressedAt;
+    }
+    getFilePath(sessionId) {
+        return join(this.baseDir, `${sessionId}.messages.json`);
+    }
+    async ensureDir() {
+        await mkdir(this.baseDir, { recursive: true });
+    }
+    async readAll(sessionId) {
+        const filePath = this.getFilePath(sessionId);
+        try {
+            await access(filePath);
+            const content = await readFile(filePath, 'utf-8');
+            const parsed = JSON.parse(content);
+            return Array.isArray(parsed) ? parsed : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    async writeAll(sessionId, messages) {
+        await this.ensureDir();
+        await writeFile(this.getFilePath(sessionId), JSON.stringify(messages, null, 2), 'utf-8');
+    }
+}

package/dist/session/file-session.repository.d.ts

@@ -0,0 +1,72 @@
+/**
+ * FileSessionRepository — Session 持久化文件存储实现
+ *
+ * 基于本地 JSON 文件实现 ISessionRepository 接口。
+ * 适用于生产环境中的会话信息存储，支持审计字段和软删除。
+ *
+ * 文件结构：
+ * - 每个 Session 存储为独立的 JSON 文件
+ * - 文件路径：{baseDir}/{sessionId}.json
+ * - 支持索引文件用于快速查询
+ *
+ * @see design.md §1.3 数据模型 — sessions 表
+ * @see session.service.ts ISessionRepository 接口定义
+ */
+import type { SessionRecord, ISessionRepository } from './session.service.js';
+/**
+ * FileSessionRepository 配置选项
+ */
+export interface FileSessionRepositoryOptions {
+    /** 存储目录路径 */
+    baseDir: string;
+    /** 是否启用索引文件（默认 true） */
+    enableIndex?: boolean;
+    /** 文件扩展名（默认 '.json'） */
+    fileExtension?: string;
+}
+export declare class FileSessionRepository implements ISessionRepository {
+    private readonly baseDir;
+    private readonly enableIndex;
+    private readonly fileExtension;
+    private readonly indexFile;
+    constructor(options: FileSessionRepositoryOptions);
+    /**
+     * 保存 Session 到 JSON 文件
+     */
+    save(session: SessionRecord): Promise<void>;
+    /**
+     * 从 JSON 文件加载 Session
+     * Excludes soft-deleted records
+     */
+    findById(id: string): Promise<SessionRecord | null>;
+    /**
+     * 更新 Session 文件
+     */
+    update(session: SessionRecord): Promise<void>;
+    /**
+     * 软删除 Session
+     */
+    softDelete(id: string, deletedBy: string): Promise<void>;
+    /**
+     * 列出所有 Session（从索引文件）
+     * Excludes soft-deleted records
+     */
+    listAll(): Promise<SessionRecord[]>;
+    /**
+     * 按 userId 查询 Session
+     * Excludes soft-deleted records
+     */
+    findByUserId(userId: string): Promise<SessionRecord[]>;
+    /**
+     * 获取 Session 文件路径
+     */
+    private getFilePath;
+    /**
+     * 确保目录存在
+     */
+    private ensureDir;
+    /**
+     * 更新索引文件
+     */
+    private updateIndex;
+}