@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/DbUse/adapters/SqliteAdapter.js

@@ -0,0 +1,157 @@
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import BaseAdapter from './BaseAdapter.js';
+
+/**
+ * SqliteAdapter —— SQLite（better-sqlite3）存储适配器
+ *
+ * 用途：结构化、需要查询/索引/事务的大量记录存储，如任务步骤、执行记录。
+ *
+ * 特性：
+ *   - 同步 API（better-sqlite3 为同步），通过 async 包装保持接口一致
+ *   - 懒加载数据库连接，首次操作时打开
+ *   - 预编译 statement 缓存，提升重复执行性能
+ *   - 支持 upsert（INSERT OR REPLACE）
+ *
+ * 依赖：better-sqlite3（需 npm 安装）
+ *
+ * 注意：better-sqlite3 为同步原生绑定，导入失败时会给出清晰提示。
+ */
+let _Database = null;
+async function loadDatabase() {
+    if (_Database) return _Database;
+    try {
+        const mod = await import('better-sqlite3');
+        _Database = mod.default || mod.Database;
+        return _Database;
+    } catch (err) {
+        throw new Error(
+            '未安装 better-sqlite3。请在项目根目录执行: npm install better-sqlite3'
+        );
+    }
+}
+
+class SqliteAdapter extends BaseAdapter {
+    constructor(options = {}) {
+        super(options);
+        this._dbName = options.dbName || 'store.db';
+        this._db = null;
+        this._stmtCache = new Map();
+        this._ready = null;
+    }
+
+    get type() {
+        return 'sqlite';
+    }
+
+    /**
+     * 懒加载并打开数据库连接。
+     * @returns {Promise<import('better-sqlite3').Database>}
+     */
+    async _ready_() {
+        if (!this._ready) {
+            this._ready = (async () => {
+                const Database = await loadDatabase();
+                await this.ensureDir();
+                const dbPath = this.pathSync(this._dbName);
+                this._db = new Database(dbPath);
+                // 性能优化：WAL 模式 + 同步策略
+                this._db.pragma('journal_mode = WAL');
+                this._db.pragma('synchronous = NORMAL');
+                return this._db;
+            })();
+        }
+        return this._ready;
+    }
+
+    /**
+     * 执行无返回值的 SQL（DDL/DML），可带参数。
+     * @param {string} sql
+     * @param {Array} [params]
+     */
+    async exec(sql, params) {
+        const db = await this._ready_();
+        if (params) {
+            db.prepare(sql).run(...params);
+        } else {
+            db.exec(sql);
+        }
+    }
+
+    /**
+     * 执行查询并返回所有匹配行。
+     * @param {string} sql
+     * @param {Array} [params]
+     * @returns {Promise<Array<object>>}
+     */
+    async all(sql, params = []) {
+        const db = await this._ready_();
+        return db.prepare(sql).all(...params);
+    }
+
+    /**
+     * 执行查询并返回首行。
+     * @param {string} sql
+     * @param {Array} [params]
+     * @returns {Promise<object|undefined>}
+     */
+    async get(sql, params = []) {
+        const db = await this._ready_();
+        return db.prepare(sql).get(...params);
+    }
+
+    /**
+     * upsert：存在则替换，不存在则插入。
+     * 要求表有主键或唯一约束。
+     * @param {string} table
+     * @param {object} row - 列名→值
+     */
+    async upsert(table, row) {
+        const cols = Object.keys(row);
+        const placeholders = cols.map(() => '?').join(', ');
+        const sql = `INSERT OR REPLACE INTO ${table} (${cols.join(', ')}) VALUES (${placeholders})`;
+        const db = await this._ready_();
+        db.prepare(sql).run(...cols.map(c => row[c]));
+        return row;
+    }
+
+    /**
+     * 在事务中执行多个写操作（better-sqlite3 同步事务）。
+     * @param {Function} fn - 接收 db，执行同步操作
+     */
+    async transaction(fn) {
+        const db = await this._ready_();
+        const tx = db.transaction(fn);
+        return tx();
+    }
+
+    async delete(key) {
+        // 语义：删除整个数据库文件
+        try {
+            await this.close();
+            const { promises: fs } = await import('node:fs');
+            await fs.unlink(this.pathSync(this._dbName));
+            return true;
+        } catch (err) {
+            if (err.code === 'ENOENT') return false;
+            throw err;
+        }
+    }
+
+    /** 关闭连接 */
+    async close() {
+        if (this._db) {
+            this._db.close();
+            this._db = null;
+            this._ready = null;
+            this._stmtCache.clear();
+        }
+    }
+
+    // read/write/list 语义不适用于通用 SQLite，由具体 Store 定义表结构
+    async read() { throw new Error('SqliteAdapter 不提供通用 read，请在 Store 层使用 all/get/upsert'); }
+    async write() { throw new Error('SqliteAdapter 不提供通用 write，请在 Store 层使用 exec/upsert'); }
+    async list() { throw new Error('SqliteAdapter 不提供通用 list，请在 Store 层使用 all'); }
+}
+
+export default SqliteAdapter;

package/vendor/Server/DbUse/index.js

@@ -0,0 +1,160 @@
+/**
+ * DbUse —— 统一持久化存储入口
+ *
+ * 分层架构（高内聚低耦合）：
+ *
+ *   ┌──────────────────────────────────────────────────────────┐
+ *   │  入口层  index.js                                        │
+ *   │  对外统一导出：createStorage() 工厂 + 各 Store 类          │
+ *   ├──────────────────────────────────────────────────────────┤
+ *   │  Store 层  stores/                                       │
+ *   │  业务语义：SessionStore / TaskStepStore / ...             │
+ *   │  只依赖适配器接口，不感知存储格式                          │
+ *   ├──────────────────────────────────────────────────────────┤
+ *   │  Manager  StorageManager.js                              │
+ *   │  工厂/注册表：统一根目录、按 (type,subDir) 复用适配器实例   │
+ *   ├──────────────────────────────────────────────────────────┤
+ *   │  Adapter 层  adapters/                                   │
+ *   │  存储格式实现：Json / Jsonl / Sqlite / File (+ Base)      │
+ *   │  互不依赖，新增格式只需加子类                             │
+ *   └──────────────────────────────────────────────────────────┘
+ *
+ * 目录布局（workspace 根下 db/，自动创建）：
+ *   db/
+ *     ├── Session/              # Session 对话存档（jsonl + meta.json）
+ *     │   ├── <sid>.jsonl
+ *     │   └── <sid>.meta.json
+ *     ├── TaskStep/             # 任务步骤存档（SQLite）
+ *     │   └── store.db
+ *     └── Artifacts/            # 任务产物文件（原始文件，按需）
+ *
+ * 使用示例：
+ *   import { createStorage } from './DbUse/index.js';
+ *   const storage = createStorage();
+ *   const sessionStore = storage.sessionStore();
+ *   const taskStepStore = storage.taskStepStore();
+ *
+ * 扩展方式：
+ *   - 新增业务存储：在 stores/ 下新建 Store，通过 manager.get(type, subDir) 取适配器
+ *   - 新增存储格式：在 adapters/ 下继承 BaseAdapter，注册到 StorageManager._ADAPTERS
+ */
+
+import StorageManager from './StorageManager.js';
+import SessionStore from './stores/SessionStore.js';
+import TaskStepStore from './stores/TaskStepStore.js';
+import TaskExecutionStore from './stores/TaskExecutionStore.js';
+import TaskRegistryStore from './stores/TaskRegistryStore.js';
+import MessageArchive from './MessageArchive.js';
+
+export { StorageManager, SessionStore, TaskStepStore, TaskExecutionStore, TaskRegistryStore, MessageArchive };
+export { default as BaseAdapter } from './adapters/BaseAdapter.js';
+export { default as JsonAdapter } from './adapters/JsonAdapter.js';
+export { default as JsonlAdapter } from './adapters/JsonlAdapter.js';
+export { default as SqliteAdapter } from './adapters/SqliteAdapter.js';
+export { default as FileAdapter } from './adapters/FileAdapter.js';
+
+/**
+ * 子域名称常量，避免散落的魔法字符串。
+ */
+export const SubDirs = Object.freeze({
+    SESSION: 'Session',
+    TASK_STEP: 'TaskStep',
+    TASK: 'task',
+    TASK_REGISTRY: 'TaskRegistry',
+    ARTIFACTS: 'Artifacts'
+});
+
+/**
+ * 创建统一的存储门面，组合各 Store 并共享同一 StorageManager。
+ *
+ * @param {object} [options]
+ * @param {string} [options.rootDir] - 存储根目录绝对路径（默认 workspace 根/db）
+ * @param {number} [options.stallThresholdMs] - Session 卡死判定阈值
+ * @returns {{
+ *   manager: StorageManager,
+ *   sessionStore: () => SessionStore,
+ *   taskStepStore: () => TaskStepStore,
+ *   taskExecStore: () => TaskExecutionStore,
+ *   taskRegistryStore: () => TaskRegistryStore,
+ *   messageArchive: () => MessageArchive,
+ *   file: (subDir?: string) => import('./adapters/FileAdapter.js').default,
+ *   json: (subDir: string) => import('./adapters/JsonAdapter.js').default,
+ *   jsonl: (subDir: string) => import('./adapters/JsonlAdapter.js').default,
+ *   sqlite: (subDir: string) => import('./adapters/SqliteAdapter.js').default,
+ *   close: () => Promise<void>
+ * }}
+ */
+export function createStorage(options = {}) {
+    const manager = new StorageManager(options);
+    const stallThresholdMs = options.stallThresholdMs;
+
+    // 懒初始化的 Store 实例（首次调用时创建，复用同一适配器实例）
+    let _sessionStore, _taskStepStore, _taskExecStore, _taskRegistryStore, _messageArchive;
+
+    return {
+        manager,
+
+        /** Session 对话存档（jsonl 消息流 + meta） */
+        sessionStore() {
+            if (!_sessionStore) {
+                _sessionStore = new SessionStore({
+                    jsonl: manager.jsonl(SubDirs.SESSION),
+                    json: manager.json(SubDirs.SESSION),
+                    stallThresholdMs
+                });
+            }
+            return _sessionStore;
+        },
+
+        /** 任务步骤存档（SQLite） */
+        taskStepStore() {
+            if (!_taskStepStore) {
+                _taskStepStore = new TaskStepStore({
+                    sqlite: manager.sqlite(SubDirs.TASK_STEP)
+                });
+            }
+            return _taskStepStore;
+        },
+
+        /** 任务执行记录（JSON 文件，db/task/{taskId}/stepid_{stepId}.json） */
+        taskExecStore() {
+            if (!_taskExecStore) {
+                _taskExecStore = new TaskExecutionStore({
+                    json: manager.json(SubDirs.TASK)
+                });
+            }
+            return _taskExecStore;
+        },
+
+        /** 任务注册表（SQLite，db/TaskRegistry/registry.db，供历史列表分页查询） */
+        taskRegistryStore() {
+            if (!_taskRegistryStore) {
+                _taskRegistryStore = new TaskRegistryStore({
+                    sqlite: manager.sqlite(SubDirs.TASK_REGISTRY, { dbName: 'registry.db' })
+                });
+            }
+            return _taskRegistryStore;
+        },
+
+        /** MessageArchive 兼容门面（供 CLI 适配器直接使用） */
+        messageArchive() {
+            if (!_messageArchive) {
+                _messageArchive = new MessageArchive({ manager, stallThresholdMs });
+            }
+            return _messageArchive;
+        },
+
+        // 适配器直接访问（供自定义 Store 使用）
+        json: (subDir) => manager.json(subDir),
+        jsonl: (subDir) => manager.jsonl(subDir),
+        sqlite: (subDir) => manager.sqlite(subDir),
+        file: (subDir = SubDirs.ARTIFACTS) => manager.file(subDir),
+
+        /** 关闭所有存储（释放数据库连接等） */
+        async close() {
+            await manager.closeAll();
+        }
+    };
+}
+
+export default { createStorage, StorageManager, SessionStore, TaskStepStore, MessageArchive, SubDirs };

package/vendor/Server/DbUse/stores/SessionStore.js

@@ -0,0 +1,279 @@
+import { promises as fs } from 'node:fs';
+import { nowCST } from '../../library/cstTime.js';
+
+/**
+ * SessionStore —— Session 对话消息存档与卡死检测
+ *
+ * 组合两个适配器：
+ *   - JsonlAdapter (subDir=Session)：消息流（append-only）
+ *   - JsonAdapter  (subDir=Session)：元信息 meta.json
+ *
+ * 职责：
+ *   1. 追加归档消息（带去重）
+ *   2. 维护 meta（lastResponseAt / lastMessageId / status / archivedCount）
+ *   3. 轮询时记录检查，计算停滞时长，判定 stalled（卡死）
+ *   4. 读取已归档消息/元信息
+ *
+ * 这是原 MessageArchive 的业务逻辑迁入，存储细节下沉到适配器层。
+ */
+class SessionStore {
+    /**
+     * @param {object} options
+     * @param {import('../adapters/JsonlAdapter.js').default} options.jsonl - 消息流适配器
+     * @param {import('../adapters/JsonAdapter.js').default} options.json  - 元信息适配器
+     * @param {number} [options.stallThresholdMs] - 卡死判定阈值，默认 5 分钟
+     */
+    constructor(options = {}) {
+        this.jsonl = options.jsonl;
+        this.json = options.json;
+        if (!this.jsonl || !this.json) {
+            throw new Error('SessionStore 需要 jsonl 与 json 适配器');
+        }
+        this.stallThresholdMs = options.stallThresholdMs ?? 5 * 60 * 1000;
+    }
+
+    // ─── 元信息 ────────────────────────────────────────────────────────────────
+
+    async readMeta(sessionId) {
+        const meta = await this.json.read(`${sessionId}.meta`);
+        return meta ?? this._defaultMeta(sessionId);
+    }
+
+    async writeMeta(sessionId, meta) {
+        return this.json.write(`${sessionId}.meta`, meta);
+    }
+
+    async patchMeta(sessionId, patch) {
+        const meta = await this.readMeta(sessionId);
+        const next = { ...meta, ...patch };
+        await this.writeMeta(sessionId, next);
+        return next;
+    }
+
+    _defaultMeta(sessionId) {
+        return {
+            sessionId,
+            title: null,
+            cliType: null,
+            createdAt: nowCST(),
+            status: 'idle',
+            lastMessageId: null,
+            lastResponseAt: null,
+            lastCheckAt: null,
+            archivedCount: 0
+        };
+    }
+
+    // ─── 消息归档 ──────────────────────────────────────────────────────────────
+
+    /**
+     * 读取已归档消息的 ID 集合（用于去重）。
+     * @param {string} sessionId
+     * @returns {Promise<Set<string>>}
+     */
+    async _readArchivedIds(sessionId) {
+        const messages = await this.jsonl.read(sessionId);
+        const ids = new Set();
+        for (const msg of messages) {
+            if (msg.id != null) ids.add(String(msg.id));
+        }
+        return ids;
+    }
+
+    /**
+     * 追加一条消息（带去重）。
+     *
+     * 去重策略：先检查 meta.lastMessageId（快速路径），
+     * 再读取已归档 ID 集合做完整检查（防止非末尾消息重复）。
+     *
+     * 注意：批量归档请用 appendMessages（O(N) 批量优化），
+     * 本方法每次调用都会读取整个 jsonl 做去重，逐条调用为 O(N²)。
+     *
+     * @param {string} sessionId
+     * @param {object} message
+     * @param {object} [opts]
+     * @param {string} [opts.dedupeKey] - 自定义去重键（默认用 message.id）
+     * @returns {Promise<{appended: boolean, seq: number, message: object}>}
+     */
+    async appendMessage(sessionId, message, opts = {}) {
+        const meta = await this.readMeta(sessionId);
+        const dedupeKey = String(opts.dedupeKey ?? message.id ?? '');
+
+        // 快速路径：与 lastMessageId 相同则跳过
+        if (dedupeKey && meta.lastMessageId === dedupeKey) {
+            return { appended: false, seq: meta.archivedCount, message };
+        }
+
+        // 完整检查：读取已归档 ID 集合，防止非末尾消息重复
+        if (dedupeKey) {
+            const archivedIds = await this._readArchivedIds(sessionId);
+            if (archivedIds.has(dedupeKey)) {
+                return { appended: false, seq: meta.archivedCount, message };
+            }
+        }
+
+        const seq = (meta.archivedCount || 0) + 1;
+        const record = { seq, ...message, archivedAt: nowCST() };
+        await this.jsonl.append(sessionId, record);
+
+        // 直接写 meta（避免 patchMeta 内部重复 readMeta）
+        const next = {
+            ...meta,
+            archivedCount: seq,
+            lastMessageId: dedupeKey || meta.lastMessageId
+        };
+        if (message.role === 'assistant') {
+            next.lastResponseAt = record.archivedAt;
+        }
+        await this.writeMeta(sessionId, next);
+
+        return { appended: true, seq, message: record };
+    }
+
+    /**
+     * 批量追加消息（带去重）。
+     *
+     * 优化：只读取 1 次 meta + 1 次 jsonl 做全量去重，
+     * 过滤后用 appendBatch 一次性写入，再 patch 1 次 meta。
+     * 复杂度 O(N) 而非逐条 appendMessage 的 O(N²)。
+     *
+     * @param {string} sessionId
+     * @param {Array<object>} messages
+     * @returns {Promise<{appended: number, skipped: number}>}
+     */
+    async appendMessages(sessionId, messages) {
+        if (!messages.length) return { appended: 0, skipped: 0 };
+
+        // 1. 读 meta 一次
+        const meta = await this.readMeta(sessionId);
+
+        // 2. 读已归档 ID 集合一次
+        const archivedIds = await this._readArchivedIds(sessionId);
+
+        // 3. 内存中去重，收集新消息
+        const newMessages = [];
+        for (const msg of messages) {
+            const dedupeKey = String(msg.id ?? '');
+            if (dedupeKey && (meta.lastMessageId === dedupeKey || archivedIds.has(dedupeKey))) {
+                continue; // 跳过重复
+            }
+            if (dedupeKey) archivedIds.add(dedupeKey); // 防止本批次内重复
+            newMessages.push(msg);
+        }
+
+        if (newMessages.length === 0) {
+            return { appended: 0, skipped: messages.length };
+        }
+
+        // 4. 构造记录（seq 连续递增）
+        let seq = meta.archivedCount || 0;
+        const now = nowCST();
+        const records = newMessages.map(msg => {
+            seq++;
+            return { seq, ...msg, archivedAt: now };
+        });
+
+        // 5. 批量写入 jsonl（一次 I/O）
+        await this.jsonl.appendBatch(sessionId, records);
+
+        // 6. 写 meta 一次
+        const next = { ...meta, archivedCount: seq };
+        const lastRecord = records[records.length - 1];
+        const lastDedupeKey = String(lastRecord.id ?? '');
+        if (lastDedupeKey) {
+            next.lastMessageId = lastDedupeKey;
+        }
+        // lastResponseAt 取最后一条 assistant 消息的 archivedAt
+        const lastAssistant = [...records].reverse().find(r => r.role === 'assistant');
+        if (lastAssistant) {
+            next.lastResponseAt = lastAssistant.archivedAt;
+        }
+        await this.writeMeta(sessionId, next);
+
+        return { appended: records.length, skipped: messages.length - records.length };
+    }
+
+    // ─── 读取 ──────────────────────────────────────────────────────────────────
+
+    async readMessages(sessionId) {
+        return this.jsonl.read(sessionId);
+    }
+
+    async readLastMessage(sessionId) {
+        const msgs = await this.readMessages(sessionId);
+        return msgs.length > 0 ? msgs[msgs.length - 1] : null;
+    }
+
+    async listSessions() {
+        const metas = [];
+        const items = await this.json.list();
+        for (const { key, data } of items) {
+            if (key.endsWith('.meta')) {
+                metas.push(data);
+            }
+        }
+        return metas.sort((a, b) =>
+            (b.createdAt || '').localeCompare(a.createdAt || '')
+        );
+    }
+
+    // ─── 卡死检测 ──────────────────────────────────────────────────────────────
+
+    /**
+     * 记录一次轮询检查并计算停滞时长。
+     *
+     * 注意：本方法只更新 lastCheckAt / lastResponseAt / status，
+     *       **不更新 lastMessageId**（那是 appendMessage 的职责）。
+     *       这样在 checkSessionStatus 中先 recordCheck 后 appendMessage 时，
+     *       appendMessage 仍能正确检测重复。
+     *
+     * @param {string} sessionId
+     * @param {object} [current]
+     * @param {string} [current.lastMessageId] - 当前最新消息 ID（用于对比判断是否有新消息）
+     * @param {string} [current.status]
+     * @returns {Promise<object>} { status, stallDurationMs, stalled, hasNewMessage, meta }
+     */
+    async recordCheck(sessionId, current = {}) {
+        const now = Date.now();
+        const meta = await this.readMeta(sessionId);
+        const nowCstStr = nowCST(now);
+
+        const currentId = current.lastMessageId ?? null;
+        const hasNewMessage = currentId != null && currentId !== meta.lastMessageId;
+
+        const patch = { lastCheckAt: nowCstStr };
+        // 有新消息时刷新 lastResponseAt（用于停滞计时），
+        // 但不更新 lastMessageId —— 交给 appendMessage 负责
+        if (hasNewMessage) {
+            patch.lastResponseAt = nowCstStr;
+        }
+        if (current.status) {
+            patch.status = current.status;
+        }
+        const next = await this.patchMeta(sessionId, patch);
+
+        const lastRespMs = next.lastResponseAt ? Date.parse(next.lastResponseAt) : null;
+        const stallDurationMs = lastRespMs != null ? (now - lastRespMs) : null;
+        const stalled =
+            (current.status === 'running') &&
+            stallDurationMs != null &&
+            stallDurationMs >= this.stallThresholdMs;
+
+        return {
+            status: stalled ? 'stalled' : (current.status || next.status || 'unknown'),
+            stallDurationMs,
+            stalled,
+            hasNewMessage,
+            meta: next
+        };
+    }
+
+    async deleteSession(sessionId) {
+        await Promise.all([
+            this.jsonl.delete(sessionId),
+            this.json.delete(`${sessionId}.meta`)
+        ]);
+    }
+}
+
+export default SessionStore;