evolcore 0.0.28 → 0.0.29

package/dist/core/memory/consolidation-context.js

@@ -0,0 +1,505 @@
+/**
+ * consolidation-context.ts — 整理上下文 MD 文档序列化（v3）
+ *
+ * 把一次整理所需的全部信息序列化成 Markdown，写两处：
+ *   - sessionRuntimeDir（会话内读取用，随会话销毁）
+ *   - $EVOLCORE_HOME/memory/consolidation-batches/<批次目录>/（长期留存，供调试）
+ *
+ * 批次目录命名：<YYYYMMDDTHHmmss>-<selfAid>-<mode>/
+ * 批次目录内：context.md（任务书）、ops.jsonl（操作流水）、threads/（话题快照）
+ * checkpoint（consolidation-checkpoint.json）记录上次整理时间，供过滤增量消息用。
+ */
+import fs from 'fs';
+import path from 'path';
+import { resolveRoot, resolvePaths } from '../../paths.js';
+import { DEFAULT_FORGET_AFTER_DAYS, collectCandidates, isDueForReview } from './staleness.js';
+import { chatDirPath } from '../session/session-fs-store.js';
+import { getMemoryArray, getMemoryString, parseMemoryDocument } from './memory-document.js';
+export const CONSOLIDATION_MODES = ['notes', 'generalize', 'promote', 'profile', 'forget'];
+/**
+ * 模式 → 允许写入的作用域（不含 forget）。
+ *
+ * forget 的写入作用域由**触发层级**决定（relation / agent / owner），不走这张表。
+ * ipc.ts 的 assertMemoryWriteSession 从 taskCtx.memoryScope 读取。
+ *
+ * 注：forget 模式同样支持「合并」产出（`create --scope <layer> --replaces ...`），
+ * 因此它的允许作用域是动态的，无法在此静态声明。
+ */
+export const MODE_SCOPE = {
+    notes: 'relation',
+    generalize: 'agent',
+    promote: 'owner',
+    profile: 'relation',
+};
+// 超期判据集中在 staleness.ts；这里做转发，保证 trigger 与 context 用同一套规则
+export { DEFAULT_FORGET_AFTER_DAYS, LONG_TERM_REVIEW_DAYS } from './staleness.js';
+// ── Checkpoint 读写 ──────────────────────────────────────────────────────────
+const CHECKPOINT_FILE = 'consolidation-checkpoint.json';
+/**
+ * Move the pre-0.0.29 consolidation artifact root to its new name. Existing
+ * batches are user data, so conflicts are preserved under a legacy suffix
+ * rather than silently overwritten.
+ */
+export function migrateLegacyConsolidationBatches() {
+    const root = resolveRoot();
+    const legacyRoot = path.join(root, 'memory', 'consolidation-logs');
+    const currentRoot = path.join(root, 'memory', 'consolidation-batches');
+    if (!fs.existsSync(legacyRoot))
+        return;
+    const moveTree = (source, target) => {
+        const stat = fs.lstatSync(source);
+        if (stat.isDirectory()) {
+            fs.mkdirSync(target, { recursive: true });
+            for (const entry of fs.readdirSync(source))
+                moveTree(path.join(source, entry), path.join(target, entry));
+            fs.rmSync(source, { recursive: true, force: true });
+            return;
+        }
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        if (!fs.existsSync(target)) {
+            fs.renameSync(source, target);
+            return;
+        }
+        const conflict = `${target}.legacy-${Date.now()}`;
+        fs.renameSync(source, conflict);
+    };
+    fs.mkdirSync(currentRoot, { recursive: true });
+    for (const entry of fs.readdirSync(legacyRoot)) {
+        moveTree(path.join(legacyRoot, entry), path.join(currentRoot, entry));
+    }
+    fs.rmSync(legacyRoot, { recursive: true, force: true });
+}
+/** 读上次整理时间戳（毫秒）。文件不存在或解析失败返回 0（取全量历史）。 */
+export function readCheckpoint(chatDir) {
+    try {
+        const raw = fs.readFileSync(path.join(chatDir, CHECKPOINT_FILE), 'utf-8');
+        const parsed = JSON.parse(raw);
+        const v = Number(parsed.lastConsolidatedAt);
+        return Number.isFinite(v) ? v : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/** 写整理完成时间戳。由 index.ts 在整理会话完成后调用。 */
+export function writeCheckpoint(chatDir, lastConsolidatedAt) {
+    try {
+        fs.mkdirSync(chatDir, { recursive: true });
+        fs.writeFileSync(path.join(chatDir, CHECKPOINT_FILE), JSON.stringify({ lastConsolidatedAt }, null, 2) + '\n', 'utf-8');
+    }
+    catch { /* 失败静默 */ }
+}
+// ── 作用域解析 ──────────────────────────────────────────────────────────────
+function memoryDirOf(scope, selfAid, peerKey, ownerAid) {
+    const root = resolveRoot();
+    if (scope === 'agent')
+        return path.join(root, 'agents', selfAid, 'personal', 'memory');
+    if (scope === 'relation') {
+        if (!peerKey)
+            throw new Error('relation 作用域需要 peerKey');
+        return path.join(root, 'agents', selfAid, 'relations', peerKey, 'memory');
+    }
+    if (!ownerAid)
+        throw new Error('owner 作用域需要 ownerAid');
+    return path.join(root, 'memory', 'owner', ownerAid);
+}
+function buildScopeContext(scope, input, selfAid, 
+/** 候选来源作用域，默认与本作用域一致 */
+sourceScope) {
+    const memoryDir = memoryDirOf(scope, selfAid, input.taskCtx.peerKey, input.ownerAid);
+    const candidateSourceDir = sourceScope === undefined || sourceScope === scope
+        ? path.join(memoryDir, 'consolidated')
+        : path.join(memoryDirOf(sourceScope, selfAid, input.taskCtx.peerKey, input.ownerAid), 'consolidated');
+    return {
+        scope,
+        selfAid,
+        peerKey: scope === 'relation' ? input.taskCtx.peerKey : undefined,
+        ownerAid: scope === 'owner' ? input.ownerAid : undefined,
+        agentSessionId: scope === 'relation' ? input.taskCtx.sessionId : undefined,
+        baseagent: input.taskCtx.baseagent,
+        pendingDir: path.join(memoryDir, 'pending'),
+        processingDir: path.join(memoryDir, 'processing'),
+        consolidatedDir: path.join(memoryDir, 'consolidated'),
+        indexPath: path.join(memoryDir, 'MEMORY.md'),
+        candidateSourceDir,
+    };
+}
+/**
+ * 按模式解析出需要渲染的作用域上下文。
+ * notes / profile 只看当前关系；generalize 看 agent；promote 看 owner。
+ */
+function resolveScopeContexts(input) {
+    const selfAid = input.taskCtx.selfAid;
+    if (!selfAid)
+        throw new Error('selfAid 未找到，无法确定整理目标');
+    // forget 的可写作用域由触发层级（scopeOverride）决定，不走 MODE_SCOPE 静态表。
+    const scope = input.mode === 'forget'
+        ? input.scopeOverride
+        : MODE_SCOPE[input.mode];
+    if (!scope) {
+        throw new Error(`forget 模式必须提供 scopeOverride（relation / agent / owner）`);
+    }
+    if (scope === 'owner' && !input.ownerAid) {
+        throw new Error('promote 模式需要 ownerAid（当前 agent 未配置 owner）');
+    }
+    // generalize / promote 的输入都在关系级，产出才在 agent / owner 级。
+    const sourceScope = (input.mode === 'generalize' || input.mode === 'promote') ? 'relation' : undefined;
+    return [buildScopeContext(scope, input, selfAid, sourceScope)];
+}
+// ── 候选扫描 ────────────────────────────────────────────────────────────────
+/** 扫 consolidated/ 目录，按判据挑出候选。 */
+function readFmArray(content, key) {
+    return getMemoryArray(parseMemoryDocument(content), key);
+}
+function readFmValue(content, key) {
+    return getMemoryString(parseMemoryDocument(content), key);
+}
+function scanCandidates(consolidatedDir, pick) {
+    if (!fs.existsSync(consolidatedDir))
+        return [];
+    const out = [];
+    for (const f of fs.readdirSync(consolidatedDir)) {
+        if (!f.endsWith('.md'))
+            continue;
+        const fp = path.join(consolidatedDir, f);
+        let content;
+        let mtimeMs;
+        try {
+            content = fs.readFileSync(fp, 'utf-8');
+            mtimeMs = fs.statSync(fp).mtimeMs;
+        }
+        catch {
+            continue;
+        }
+        const tags = readFmArray(content, 'tags');
+        if (!pick({ tags, mtimeMs, content }))
+            continue;
+        out.push({
+            relPath: `consolidated/${f}`,
+            description: readFmValue(content, 'description') ?? f.replace(/\.md$/, ''),
+            tags,
+        });
+    }
+    out.sort((a, b) => a.relPath.localeCompare(b.relPath));
+    return out;
+}
+/** 按模式填充候选清单。 */
+function fillCandidates(ctx, mode, forgetAfterDays) {
+    const source = ctx.candidateSourceDir ?? ctx.consolidatedDir;
+    if (mode === 'generalize') {
+        ctx.candidates = scanCandidates(source, ({ tags }) => tags.includes('to-generalize'));
+    }
+    else if (mode === 'promote') {
+        ctx.candidates = scanCandidates(source, ({ tags }) => tags.includes('to-promote'));
+    }
+    else if (mode === 'profile') {
+        ctx.candidates = scanCandidates(source, () => true);
+    }
+    else if (mode === 'forget') {
+        const now = Date.now();
+        const thresholds = { forgetAfterDays };
+        ctx.candidates = collectCandidates(source, thresholds, now)
+            .filter(info => isDueForReview(info, thresholds, now))
+            .map(info => ({
+            relPath: `consolidated/${info.name}`,
+            description: readFmValue(info.content, 'description') ?? info.name.replace(/\.md$/, ''),
+            tags: info.tags,
+        }));
+    }
+}
+// ── 渲染 ────────────────────────────────────────────────────────────────────
+function renderScopeSection(ctx, mode, threadFiles) {
+    const lines = [];
+    lines.push(`### 作用域：${ctx.scope}`);
+    lines.push('');
+    lines.push(`- selfAid: ${ctx.selfAid}`);
+    if (ctx.peerKey)
+        lines.push(`- peerKey: ${ctx.peerKey}`);
+    if (ctx.ownerAid)
+        lines.push(`- ownerAid: ${ctx.ownerAid}`);
+    if (ctx.baseagent)
+        lines.push(`- baseagent: ${ctx.baseagent}`);
+    lines.push(`- processingDir: ${ctx.processingDir}`);
+    lines.push(`- consolidatedDir: ${ctx.consolidatedDir}`);
+    lines.push(`- indexPath: ${ctx.indexPath}`);
+    lines.push('');
+    if (mode === 'notes') {
+        if (threadFiles && threadFiles.length > 0) {
+            lines.push(`**对话历史**：已按话题切分为 ${threadFiles.length} 个快照文件，见下方"话题快照文件"节。`);
+        }
+        else {
+            lines.push('**对话历史**：无增量消息（checkpoint 之后无新消息，或定时触发无绑定会话）。');
+        }
+        lines.push('');
+        lines.push(`待整理的 note 在 \`${ctx.processingDir}\`（整理开始前已从 pending/ 整体移入，是本次的快照）。`);
+    }
+    else if (ctx.candidates) {
+        lines.push(`**候选记忆（${ctx.candidates.length} 条）** —— 只列路径与描述，按需读正文：`);
+        lines.push('');
+        if (ctx.candidates.length === 0) {
+            lines.push('（无候选）');
+        }
+        else {
+            for (const c of ctx.candidates) {
+                const tags = c.tags.length > 0 ? ` [${c.tags.join(', ')}]` : '';
+                lines.push(`- \`${c.relPath}\`${tags} — ${c.description}`);
+            }
+        }
+    }
+    return lines.join('\n');
+}
+const MODE_TITLE = {
+    notes: '整理 note → 关系级记忆',
+    generalize: '泛化：关系级 → agent 级',
+    promote: '提升：关系级 → owner 级',
+    profile: '生成对端画像',
+    forget: '遗忘：评估超期记忆',
+};
+// ── 話题快照生成 ────────────────────────────────────────────────────────────
+/**
+ * 把 "2026-10-04 13:31:44.957" 精简为 "10-04 13:31:44"：
+ * 去掉年份前缀（YYYY-）和毫秒（.xxx）。时间范围头部保留完整原始值供人参考。
+ */
+function shortTime(time) {
+    // 匹配 "YYYY-MM-DD HH:mm:ss.mmm" 或 "YYYY-MM-DD HH:mm:ss"
+    const m = time.match(/^\d{4}-(\d{2}-\d{2} \d{2}:\d{2}:\d{2})(?:\.\d+)?$/);
+    return m ? m[1] : time;
+}
+/**
+ * 从 messages.jsonl 读取 ts >= sinceMs 的消息，按 threadId 分组，
+ * 每个 thread 写一个 Markdown 快照到 threadsDir/。
+ *
+ * 快照格式优化：
+ *   - 头部标注来源文件路径、会话类型（私聊/群聊）、对端信息
+ *   - 私聊：每行用户消息只显示名字（不重复 AID），群聊：头部建发言人清单，每行只用名字
+ *   - 时间精简：去掉年份前缀和毫秒，节省字节
+ *
+ * 返回生成的文件路径列表（空列表表示无增量消息或读取失败）。
+ */
+function buildThreadSnapshots(historyJsonlPath, sinceMs, threadsDir) {
+    const rawLines = fs.readFileSync(historyJsonlPath, 'utf-8').split('\n');
+    // 第一遍：扫全量行（不限 sinceMs）收集会话元信息
+    let chatType = 'private';
+    let groupId = '';
+    // aid → peerName 映射，用于发言人清单
+    const speakerNames = new Map();
+    for (const line of rawLines) {
+        if (!line.trim())
+            continue;
+        try {
+            const entry = JSON.parse(line);
+            if (typeof entry.chatType === 'string')
+                chatType = entry.chatType;
+            if (typeof entry.groupId === 'string' && entry.groupId)
+                groupId = entry.groupId;
+            // 收集入站发言人 aid → peerName
+            if (entry.dir === 'in') {
+                const from = typeof entry.from === 'string' ? entry.from : '';
+                const peerName = typeof entry.peerName === 'string' ? entry.peerName : '';
+                if (from && peerName && !speakerNames.has(from)) {
+                    speakerNames.set(from, peerName);
+                }
+            }
+        }
+        catch { /* ignore */ }
+    }
+    const groups = new Map();
+    // 第二遍：只取 sinceMs 之后的消息
+    for (let i = 0; i < rawLines.length; i++) {
+        const line = rawLines[i].trim();
+        if (!line)
+            continue;
+        try {
+            const entry = JSON.parse(line);
+            const ts = typeof entry.ts === 'number' ? entry.ts : 0;
+            if (ts < sinceMs)
+                continue;
+            const content = typeof entry.content === 'string' ? entry.content.trim() : '';
+            if (!content)
+                continue;
+            const dir = typeof entry.dir === 'string' ? entry.dir : '';
+            const time = typeof entry.time === 'string' ? entry.time : '';
+            const from = typeof entry.from === 'string' ? entry.from : '';
+            const peerName = typeof entry.peerName === 'string' ? entry.peerName : '';
+            let speaker;
+            if (dir === 'in') {
+                // 用名字代替 AID；名字优先从当前消息取，其次从全量扫描的映射里取
+                const name = peerName || speakerNames.get(from) || from;
+                if (chatType === 'group') {
+                    // 群聊：格式为 "[名字]"，完整 AID 已在头部清单里
+                    speaker = `[${name}]`;
+                }
+                else {
+                    // 私聊：头部已标注对端，行内只用名字
+                    speaker = `[${name}]`;
+                }
+            }
+            else {
+                speaker = '[助手]';
+            }
+            const threadId = typeof entry.threadId === 'string' && entry.threadId ? entry.threadId : 'main';
+            if (!groups.has(threadId))
+                groups.set(threadId, []);
+            groups.get(threadId).push({ lineNo: i + 1, time, speaker, content });
+        }
+        catch { /* 跳过无法解析的行 */ }
+    }
+    if (groups.size === 0)
+        return [];
+    fs.mkdirSync(threadsDir, { recursive: true });
+    const files = [];
+    // 构造头部：来源路径 + 会话类型 + 对端信息
+    const headerBase = [
+        `> 来源：\`${historyJsonlPath}\``,
+    ];
+    if (chatType === 'group') {
+        headerBase.push(`> 会话类型：群聊  `);
+        headerBase.push(`> 群 AID：${groupId}  `);
+        if (speakerNames.size > 0) {
+            headerBase.push(`> 发言人清单：`);
+            for (const [aid, name] of speakerNames) {
+                headerBase.push(`>   - ${name}（${aid}）`);
+            }
+        }
+    }
+    else {
+        // 私聊：找对端 AID（入站消息的 from）
+        const peerAid = speakerNames.size > 0 ? [...speakerNames.keys()][0] : '';
+        const peerName = peerAid ? speakerNames.get(peerAid) ?? peerAid : '';
+        headerBase.push(`> 会话类型：私聊  `);
+        if (peerName)
+            headerBase.push(`> 对端：${peerName}（${peerAid}）  `);
+    }
+    for (const [threadId, msgs] of groups) {
+        const firstTime = msgs[0]?.time ?? '';
+        const lastTime = msgs[msgs.length - 1]?.time ?? '';
+        const mdLines = [
+            `# 话题快照：${threadId}`,
+            '',
+            `> 时间范围：${firstTime} — ${lastTime}  `,
+            ...headerBase,
+            '> 原始 JSONL 行号已标注，需要完整元数据时按行号读取来源文件。',
+            '',
+        ];
+        for (const m of msgs) {
+            // 时间精简：去掉年份和毫秒
+            mdLines.push(`L${m.lineNo} ${shortTime(m.time)} ${m.speaker}: ${m.content.replace(/\n/g, ' ')}`);
+        }
+        const safeName = threadId.replace(/[^a-zA-Z0-9._-]/g, '_');
+        const fp = path.join(threadsDir, safeName + '.md');
+        fs.writeFileSync(fp, mdLines.join('\n'), 'utf-8');
+        files.push(fp);
+    }
+    return files;
+}
+/**
+ * 序列化整理上下文，写会话运行目录与长期批次目录，返回两者路径。
+ */
+export function serializeConsolidationContext(input) {
+    migrateLegacyConsolidationBatches();
+    const scopes = resolveScopeContexts(input);
+    const now = new Date();
+    // 会话内文件名用：去掉所有分隔符，无 T，14 字符（YYYYMMDDHHmmss）
+    const ts = now.toISOString().replace(/[-:T]/g, '').slice(0, 14);
+    const forgetAfterDays = input.forgetAfterDays ?? DEFAULT_FORGET_AFTER_DAYS;
+    for (const ctx of scopes) {
+        fillCandidates(ctx, input.mode, forgetAfterDays);
+    }
+    // ── 批次目录（长期批次）────────────────────────────────────────────────────
+    const batchRoot = path.join(resolveRoot(), 'memory', 'consolidation-batches');
+    const selfAid = input.taskCtx.selfAid ?? 'unknown';
+    // 目录名：YYYYMMDDTHHmmss-<selfAid>-<mode>
+    const prettyTs = now.toISOString().replace(/[-:]/g, '').slice(0, 15);
+    const batchDir = path.join(batchRoot, `${prettyTs}-${selfAid}-${input.mode}`);
+    fs.mkdirSync(batchDir, { recursive: true });
+    // ── 话题快照（notes / compress / session-new 模式，有 peerId 时生成）───────
+    let historyJsonlPath;
+    let threadFiles;
+    let chatDir;
+    if ((input.mode === 'notes' || input.triggeredBy === 'compress' || input.triggeredBy === 'session-new')
+        && input.taskCtx.channel
+        && input.taskCtx.peerId
+        && input.taskCtx.selfAid) {
+        try {
+            const sessionsDir = resolvePaths().sessionsDir;
+            chatDir = chatDirPath(sessionsDir, input.taskCtx.channel, input.taskCtx.peerId, input.taskCtx.selfAid);
+            const rawJsonlPath = path.join(chatDir, 'messages.jsonl');
+            if (fs.existsSync(rawJsonlPath)) {
+                historyJsonlPath = rawJsonlPath;
+                const sinceMs = readCheckpoint(chatDir);
+                const threadsDir = path.join(batchDir, 'threads');
+                try {
+                    const files = buildThreadSnapshots(rawJsonlPath, sinceMs, threadsDir);
+                    if (files.length > 0)
+                        threadFiles = files;
+                }
+                catch { /* 快照生成失败不影响整理 */ }
+            }
+        }
+        catch { /* 找不到历史文件不影响整理 */ }
+    }
+    // ── 渲染任务书 ─────────────────────────────────────────────────────────────
+    const allowedScope = scopes[0]?.scope;
+    const lines = [
+        '# 记忆整理上下文',
+        '',
+        `> 生成时间：${now.toISOString()}  `,
+        `> 整理模式：**${input.mode}**（${MODE_TITLE[input.mode]}）  `,
+        `> triggeredBy: ${input.triggeredBy}  `,
+        `> 允许写入的 scope: ${allowedScope ?? '无（本模式不产生新记忆）'}  `,
+        `> 作用域数量: ${scopes.length}`,
+        '',
+        '---',
+        '',
+        '## 整理目标',
+        '',
+        ...scopes.flatMap(ctx => [renderScopeSection(ctx, input.mode, threadFiles), '', '---', '']),
+    ];
+    if (input.mode === 'notes' && threadFiles && threadFiles.length > 0) {
+        const threadsDir = path.join(batchDir, 'threads');
+        lines.push('## 话题快照文件', '');
+        lines.push(`话题快照目录：\`${threadsDir}\``, '');
+        lines.push('以下文件各对应一个话题，包含本次整理范围内的增量对话（checkpoint 之后）：', '');
+        for (const f of threadFiles) {
+            lines.push(`- \`${path.basename(f)}\``);
+        }
+        lines.push('');
+        lines.push('逐一读取这些文件以了解对话上下文，辅助判断 note 的准确性和遗漏情况。');
+        lines.push('', '---', '');
+    }
+    if (input.mode === 'notes' && historyJsonlPath) {
+        lines.push('## 原始消息流水', '');
+        lines.push(`- 完整 JSONL（按行号随机读取元数据）：\`${historyJsonlPath}\``);
+        lines.push('', '---', '');
+    }
+    if (input.mode === 'promote' && input.ownerInvolved !== undefined) {
+        lines.push('## 权限提示', '');
+        lines.push(input.ownerInvolved
+            ? '本次对话中 owner 本人参与发言，群关系下打 `to-promote` 是被允许的。'
+            : '本次对话中 owner 未参与发言，群关系下的记忆不应打 `to-promote`。');
+        lines.push('', '---', '');
+    }
+    lines.push('请按照本次会话注入的模式手册完成整理。');
+    const text = lines.join('\n');
+    // ── 写会话运行目录（任务书，会话内读取用）────────────────────────────────
+    const tmpDir = input.sessionRuntimeDir && path.isAbsolute(input.sessionRuntimeDir)
+        ? input.sessionRuntimeDir
+        : path.join(resolveRoot(), 'tmp');
+    fs.mkdirSync(tmpDir, { recursive: true });
+    const filePath = path.join(tmpDir, `memory-consolidation-${ts}.md`);
+    fs.writeFileSync(filePath, text, 'utf-8');
+    // ── 写批次目录（长期留存）────────────────────────────────────────────────
+    const contextFilePath = path.join(batchDir, 'context.md');
+    try {
+        fs.writeFileSync(contextFilePath, text, 'utf-8');
+    }
+    catch { /* 批次任务书写入失败不影响整理 */ }
+    return { filePath, batchDir, contextFilePath, scopes, historyJsonlPath, threadFiles, chatDir };
+}
+/** 会话结束后回填本次产出，追加到任务书末尾。 */
+export function recordBatchOutcome(contextFilePath, outcome) {
+    try {
+        fs.appendFileSync(contextFilePath, `\n---\n\n## 本次产出\n\n${outcome}\n`, 'utf-8');
+    }
+    catch { /* ignore */ }
+}

package/dist/core/memory/consolidation-ops-records.js

@@ -0,0 +1,124 @@
+/**
+ * consolidation-ops-records.ts — 整理会话操作记录（v3）
+ *
+ * 记录整理会话内的所有关键事件：
+ *   - session-start / session-end：会话级别的开始/结束记录
+ *   - create / update / archive：每次写操作的结果
+ *   - summary：会话结束时的汇总行
+ *
+ * session-end 写在 onConsolidationComplete 里，失败时可依据 ops.jsonl 逐条回撤。
+ */
+import fs from 'fs';
+import path from 'path';
+/** 向 ops 记录文件追加一条记录。失败静默，不影响主流程。 */
+export function appendOpsRecord(batchDir, entry) {
+    try {
+        const filePath = path.join(batchDir, 'ops.jsonl');
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.appendFileSync(filePath, JSON.stringify(entry) + '\n', 'utf-8');
+    }
+    catch { /* ignore */ }
+}
+/**
+ * 扫描 ops 记录并返回汇总行（未写入文件）。
+ * 供会话结束时追加 summary 条目。
+ */
+export function summarizeOpsRecords(batchDir) {
+    const summary = {
+        ts: new Date().toISOString(),
+        op: 'summary',
+        created: 0,
+        updated: 0,
+        archived: 0,
+        errors: 0,
+    };
+    const filePath = path.join(batchDir, 'ops.jsonl');
+    if (!fs.existsSync(filePath))
+        return summary;
+    try {
+        for (const line of fs.readFileSync(filePath, 'utf-8').split('\n').filter(Boolean)) {
+            const entry = JSON.parse(line);
+            if (entry.op === 'summary' || entry.op === 'session-start' || entry.op === 'session-end' || entry.op === 'feedback-set')
+                continue;
+            if (!entry.ok) {
+                summary.errors++;
+                continue;
+            }
+            if (entry.op === 'create')
+                summary.created++;
+            else if (entry.op === 'update')
+                summary.updated++;
+            else if (entry.op === 'archive')
+                summary.archived++;
+        }
+    }
+    catch { /* ignore */ }
+    return summary;
+}
+/**
+ * 读整理会话写入的反馈文本（`ec memory feedback`）。
+ * 取最后一条 feedback-set；没有则返回 undefined（收尾回退默认模板）。
+ */
+export function readFeedbackText(batchDir) {
+    const filePath = path.join(batchDir, 'ops.jsonl');
+    if (!fs.existsSync(filePath))
+        return undefined;
+    try {
+        const lines = fs.readFileSync(filePath, 'utf-8').split('\n').filter(Boolean);
+        for (let i = lines.length - 1; i >= 0; i--) {
+            const entry = JSON.parse(lines[i]);
+            if (entry.op === 'feedback-set') {
+                const text = entry.text;
+                if (typeof text === 'string' && text.trim())
+                    return text;
+            }
+        }
+    }
+    catch { /* ignore */ }
+    return undefined;
+}
+/**
+ * 收集 ops 记录里所有出现过的作用域及其 memory 根目录。
+ * 供 finishConsolidationSession 决定要对哪几个 scope 重建索引。
+ * 返回 Map<scope, memoryDir>；同一 scope 若出现多次取第一条（目录相同）。
+ */
+export function collectAffectedScopes(batchDir) {
+    const result = new Map();
+    const filePath = path.join(batchDir, 'ops.jsonl');
+    if (!fs.existsSync(filePath))
+        return result;
+    try {
+        for (const line of fs.readFileSync(filePath, 'utf-8').split('\n').filter(Boolean)) {
+            const entry = JSON.parse(line);
+            if (entry.op !== 'create' && entry.op !== 'update' && entry.op !== 'archive')
+                continue;
+            const e = entry;
+            const s = e.scope;
+            if ((s === 'relation' || s === 'agent' || s === 'owner') && e.memoryDir && !result.has(s)) {
+                result.set(s, e.memoryDir);
+            }
+        }
+    }
+    catch { /* ignore */ }
+    return result;
+}
+/**
+ * 读取 ops 记录里所有成功的写操作，按写入顺序倒序返回（最后写的先回撤）。
+ * 只返回 create / update / archive 且 ok=true 的条目。
+ */
+export function readRollbackRecords(batchDir) {
+    const filePath = path.join(batchDir, 'ops.jsonl');
+    if (!fs.existsSync(filePath))
+        return [];
+    try {
+        return fs.readFileSync(filePath, 'utf-8')
+            .split('\n')
+            .filter(Boolean)
+            .map(l => JSON.parse(l))
+            .filter((e) => (e.op === 'create' || e.op === 'update' || e.op === 'archive') && e.ok)
+            .reverse();
+    }
+    catch {
+        return [];
+    }
+}