mocode-ai 1.7.9 → 1.7.11

package/dist/session/compact-archive.js

@@ -0,0 +1,232 @@
+// compact-archive.ts — 压缩旧区原文的归档渲染器。
+//
+// 目的:compactHistory 成功摘要后旧区消息会被整体丢弃(连 session.json 也被
+// 压缩后的 history 覆盖)。这里把旧区渲染成 grep 友好的 Markdown 段文件,落盘到
+// `<session>/compacted/seg-NNN.md`,模型事后可用现有 grep/read_file 回捞精确原文,
+// 不新增任何工具。
+//
+// 设计约束:
+//  - 纯函数,不碰文件系统(落盘/编号/淘汰在 SessionStore)。
+//  - 每个 seg 文件首行是单行 HTML 注释元数据(自描述,index.md 可随时重建)。
+//  - 图片不归档(base64 无检索价值且体积爆炸),只留占位,与 stripImagesForSummary 同口径。
+//  - 消息按 history 原时序;turn 序号按非空 user 消息递增,方便模型按回合定位。
+/** 压缩归档子目录名(相对会话目录)。 */
+export const COMPACTED_DIRNAME = 'compacted';
+/** 段索引文件名。 */
+export const ARCHIVE_INDEX_FILE = 'index.md';
+/** seg 文件名:seg-001.md … seg-999.md(超出也不报错,只是不补零)。 */
+export function segmentFileName(seq) {
+    return `seg-${String(seq).padStart(3, '0')}.md`;
+}
+export const SEGMENT_FILE_RE = /^seg-(\d+)\.md$/;
+/** push-time 被 capToolResultForHistory 截断的工具完整结果,按 tool_call_id 单存。 */
+export function resultBlobFileName(toolCallId) {
+    // call id 理论上安全(toolu_xxx / call-N),仍做一次白名单清洗防路径穿越。
+    const safe = toolCallId.replace(/[^A-Za-z0-9_.-]/g, '_').slice(0, 120) || 'unknown';
+    return `result-${safe}.txt`;
+}
+export const RESULT_BLOB_FILE_RE = /^result-.+\.txt$/;
+/** retention 归档时打包进 gz 的 compacted/ 资产白名单(其余临时文件不带走)。 */
+export function isCompactedAssetName(name) {
+    return SEGMENT_FILE_RE.test(name) || RESULT_BLOB_FILE_RE.test(name) || name === ARCHIVE_INDEX_FILE;
+}
+function asToolCalls(m) {
+    const tcs = m.tool_calls;
+    if (!Array.isArray(tcs))
+        return [];
+    return tcs;
+}
+/** 多模态 content 拍平:text 拼接;image_url 留占位;其余形状 JSON 化(与摘要器同口径)。 */
+function messageText(content) {
+    if (content == null)
+        return '';
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content)) {
+        const parts = [];
+        for (const p of content) {
+            if (p && typeof p === 'object') {
+                const part = p;
+                if (part.type === 'text')
+                    parts.push(part.text ?? '');
+                else if (part.type === 'image_url') {
+                    const url = part.image_url?.url ?? '';
+                    const mime = url.startsWith('data:') ? url.slice(5, url.indexOf(';')) : 'image';
+                    parts.push(`[图片已剥离: ${mime}]`);
+                }
+                else {
+                    parts.push(`[${part.type ?? 'content'} part]`);
+                }
+            }
+            else {
+                parts.push(String(p ?? ''));
+            }
+        }
+        return parts.join('');
+    }
+    try {
+        return JSON.stringify(content);
+    }
+    catch {
+        return String(content);
+    }
+}
+const PATH_KEYS = new Set(['path', 'file', 'filePath', 'filename', 'dir', 'directory']);
+const MAX_META_FILES = 8;
+const MAX_FIRST_USER_CHARS = 60;
+function collectFilesFromArgs(argsRaw, sink) {
+    if (!argsRaw || sink.length >= MAX_META_FILES)
+        return;
+    let parsed;
+    try {
+        parsed = JSON.parse(argsRaw);
+    }
+    catch {
+        return;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return;
+    for (const [k, v] of Object.entries(parsed)) {
+        if (typeof v !== 'string' || !PATH_KEYS.has(k))
+            continue;
+        const norm = v.replace(/\\/g, '/').replace(/^\.\//, '');
+        if (norm && !sink.includes(norm))
+            sink.push(norm);
+        if (sink.length >= MAX_META_FILES)
+            break;
+    }
+}
+function oneLine(text, max) {
+    const line = text.replace(/\s+/g, ' ').trim();
+    return line.length > max ? `${line.slice(0, max)}…` : line;
+}
+/**
+ * 把一段旧区消息渲染成 Markdown 段。输出同时包含文件全文与元数据,
+ * 调用方负责把返回的 { markdown, meta } 一起落盘。
+ */
+export function renderCompactedSegment(seq, messages, archivedAt = new Date().toISOString()) {
+    const file = segmentFileName(seq);
+    const tools = [];
+    const files = [];
+    let turns = 0;
+    let firstUser = '';
+    // tool_call_id → tool 名(tool 消息自身不带工具名,靠前导 assistant 配对)。
+    const callNames = new Map();
+    for (const m of messages) {
+        if (m.role !== 'assistant')
+            continue;
+        for (const tc of asToolCalls(m)) {
+            const name = tc.function?.name;
+            if (tc.id && name)
+                callNames.set(tc.id, name);
+            if (name && !tools.includes(name))
+                tools.push(name);
+            collectFilesFromArgs(tc.function?.arguments, files);
+        }
+    }
+    const blocks = [];
+    for (const m of messages) {
+        if (m.role === 'user') {
+            const text = messageText(m.content);
+            if (text.trim()) {
+                turns++;
+                if (!firstUser)
+                    firstUser = oneLine(text, MAX_FIRST_USER_CHARS);
+            }
+            blocks.push(`### [turn ${turns}] user\n${text.trim()}`);
+            continue;
+        }
+        if (m.role === 'system') {
+            // 上一代摘要的叙述段(pin 除外):内容会随本代重新压缩,归档里标记出处。
+            blocks.push(`### [prior-summary] system\n${messageText(m.content).trim()}`);
+            continue;
+        }
+        if (m.role === 'tool') {
+            const id = m.tool_call_id ?? '';
+            const name = (id && callNames.get(id)) || '';
+            const label = [`### [turn ${turns}] tool_result`, id && `call=${id}`, name && `tool=${name}`]
+                .filter(Boolean)
+                .join(' ');
+            blocks.push(`${label}\n${messageText(m.content).trim()}`);
+            continue;
+        }
+        // assistant:正文一个块,每个 tool_call 一个块(参数是 grep 的高频目标,独立成块)。
+        const text = messageText(m.content).trim();
+        if (text)
+            blocks.push(`### [turn ${turns}] assistant\n${text}`);
+        for (const tc of asToolCalls(m)) {
+            const name = tc.function?.name;
+            const label = [`### [turn ${turns}] assistant call`, tc.id && `call=${tc.id}`, name && `tool=${name}`]
+                .filter(Boolean)
+                .join(' ');
+            const args = (tc.function?.arguments ?? '').trim();
+            blocks.push(`${label}\n${args ? `args: ${args}` : '(no args)'}`);
+        }
+    }
+    const body = blocks.join('\n\n') + '\n';
+    const baseMeta = {
+        seq,
+        file,
+        archivedAt,
+        messages: messages.length,
+        turns,
+        tools,
+        files,
+        firstUser,
+    };
+    const heading = `# 已压缩历史段 ${file}\n\n`;
+    // chars 是淘汰策略的依据,需含 header 自身:先估后定(header 只差 chars 一个数字位)。
+    const measure = (chars) => `<!-- mocode-archive ${JSON.stringify({ ...baseMeta, chars })} -->\n\n`;
+    let chars = measure(0).length + heading.length + body.length;
+    let header = measure(chars);
+    if (header.length !== measure(0).length) {
+        // 数字位数变化(9→10)的罕见情况,再定标一次即收敛。
+        chars = header.length + heading.length + body.length;
+        header = measure(chars);
+    }
+    const meta = { ...baseMeta, chars };
+    return { markdown: `${header}${heading}${body}`, meta };
+}
+/** 从 seg 文件内容解析首行元数据;损坏/旧格式返 null。 */
+export function parseSegmentMeta(markdown) {
+    const nl = markdown.indexOf('\n');
+    const first = (nl >= 0 ? markdown.slice(0, nl) : markdown).trim();
+    const m = /^<!-- mocode-archive (\{.*\}) -->$/.exec(first);
+    if (!m)
+        return null;
+    try {
+        const meta = JSON.parse(m[1]);
+        if (typeof meta.seq === 'number' && typeof meta.file === 'string')
+            return meta;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 由全部段元数据重建 index.md。模型读它决定去哪段 grep;确定性输出,
+ * 不经过摘要器(避免漏写)。relativeDir 是相对 cwd 的 POSIX 路径,
+ * 直接写给模型/grep 用。
+ */
+export function renderArchiveIndex(metas, relativeDir) {
+    const sorted = [...metas].sort((a, b) => a.seq - b.seq);
+    const lines = [
+        '# 已压缩历史索引(compacted history index)',
+        '',
+        '本目录是历次上下文压缩前的原始消息(用户原话、assistant 决策、工具参数与完整结果)。',
+        `路径:\`${relativeDir}/\``,
+        '需要精确原文(报错、命令/测试输出、旧决策)时,不要凭摘要猜也不要急着重跑:',
+        `1. 用 grep 搜索并把 glob 限定在 \`${relativeDir}/**\`(.mocode 在 .gitignore 里,必须 glob 限定才搜得到);`,
+        '2. 按命中行号用 read_file 的 offset/limit 精读对应 seg 文件。',
+        '',
+    ];
+    for (const m of sorted) {
+        const tools = m.tools.length ? m.tools.join(', ') : '-';
+        const files = m.files.length ? m.files.join(', ') : '-';
+        const first = m.firstUser ? m.firstUser.replace(/\|/g, '/') : '(无 user 消息)';
+        lines.push(`- [${m.file}](${m.file}) · ${m.archivedAt} · ${m.turns} turns · ${m.messages} msgs · 工具 ${tools} · 文件 ${files} · 首句:${first}`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}

package/dist/session/compact.js

@@ -160,6 +160,8 @@ const ANY_HEADING_RE = /^ {0,3}##\s+\S/;
 const PRIOR_NARRATIVE_LABEL = '[prior summary — 上一代摘要的叙述部分:与下方新内容合并压缩,不要重复罗列细节]';
 /** 尾部 provenance 块:解析时剥掉,重建时按当次 older 重算(否则跨代累积并重复)。 */
 const ARTIFACT_REFS_RE = /\n*\[artifact refs:[^\]]*\]\s*$/;
+/** 尾部归档指针:同理按当次压缩重算(指向最新 seg),跨代不累积进叙述/Key Facts。 */
+const ARCHIVED_REFS_RE = /\n*\[archived:[^\]]*\]\s*$/;
 /** Key Facts 累计预算(字符):窗口比例换算 + 上下限——小窗口留得住初始约束,
  *  大窗口也不会让索引段膨胀成正文。 */
 export function keyFactsBudgetChars(window) {
@@ -172,7 +174,7 @@ export function keyFactsBudgetChars(window) {
  * older 重算,不该跨代累积。无 Key Facts 段时 rest 为全文、keyFacts 为空。
  */
 export function splitSummaryText(raw) {
-    let text = (raw ?? '').replace(ARTIFACT_REFS_RE, '').trim();
+    let text = (raw ?? '').replace(ARCHIVED_REFS_RE, '').replace(ARTIFACT_REFS_RE, '').trim();
     if (text.startsWith(SUMMARY_MARKER)) {
         const nl = text.indexOf('\n');
         text = (nl < 0 ? '' : text.slice(nl + 1)).trim();
@@ -874,10 +876,25 @@ export async function compactHistory(history, opts) {
             if (snapshot)
                 writeCompactionSnapshot(snapshot);
         }
+        // 旧区原文归档(仅主 agent):摘要成功后这些消息将被整体丢弃且 session.json
+        // 随后被覆盖——落盘 compacted/seg-NNN.md,模型事后靠 grep/read_file 回捞精确原文。
+        // best-effort:失败只丢回捞能力,绝不阻塞压缩。
+        let archivedPath = null;
+        if (state === contextState) {
+            try {
+                archivedPath = getActiveSessionStore().archiveCompactedMessages(getCurrentSessionId() ?? '', older);
+            }
+            catch {
+                archivedPath = null;
+            }
+        }
         const body = [parsed.rest, pinnedFacts ? `## Key Facts\n${pinnedFacts}` : ''].filter(Boolean).join('\n\n');
+        const archivedRef = archivedPath
+            ? `\n\n[archived: ${archivedPath} — 被压缩内容的精确原文;更早段见同目录 index.md]`
+            : '';
         const summaryMsg = {
             role: 'system',
-            content: `${SUMMARY_MARKER}\n${body}${provenance}`,
+            content: `${SUMMARY_MARKER}\n${body}${provenance}${archivedRef}`,
         };
         // 原地重建:[systemPrompt, summaryMsg, ...kept]
         const systemMsg = history[0];

package/dist/session/persist.js

@@ -11,9 +11,10 @@ export function newSessionId() {
 export function saveSession(history, id, queryHistory = [], lastToolGroups = []) {
     return defaultSessionStore.save(history, id, queryHistory, lastToolGroups);
 }
-/** 加载会话；不存在或损坏时返回 null。 */
-export function loadSession(id) {
-    return defaultSessionStore.load(id);
+/** 加载会话；不存在或损坏时返回 null。restoreAssets=true 时(resume)把归档 gz
+ *  内嵌的 compacted 资产写回磁盘;列表/检索等只读场景保持默认不产生写盘副作用。 */
+export function loadSession(id, opts) {
+    return defaultSessionStore.load(id, opts);
 }
 /** 列出最近会话，按 createdAt 降序。 */
 export function listSessions(limit) {

package/dist/session/retention.js

@@ -12,6 +12,7 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
 import path from 'node:path';
 import { gzipSync, gunzipSync } from 'node:zlib';
+import { COMPACTED_DIRNAME, isCompactedAssetName } from './compact-archive.js';
 import { TextSearchIndex } from '../context/text-search.js';
 import { config } from '../config/index.js';
 import { runReflection, snapshotTranscript } from '../memory/index.js';
@@ -174,15 +175,45 @@ export function planRetention(sessionsRoot, policy = DEFAULT_RETENTION_POLICY, n
     return { items, bytesReclaimable: items.reduce((s, i) => s + i.sizeBytes, 0) };
 }
 // ── 执行 ─────────────────────────────────────────────────────────────────
-/** 归档单个会话:读 session.json → gzip → 写 index → 删原目录。失败抛错由调用方统一处理。 */
+/** 收集 <id>/compacted/ 下白名单资产为 relPath → utf8;无/读失败返空对象。 */
+function readCompactedAssets(sessionsRoot, id) {
+    const dir = path.join(sessionsRoot, id, COMPACTED_DIRNAME);
+    const assets = {};
+    let names;
+    try {
+        names = readdirSync(dir, { withFileTypes: true })
+            .filter((e) => e.isFile())
+            .map((e) => e.name);
+    }
+    catch {
+        return assets;
+    }
+    for (const name of names) {
+        if (!isCompactedAssetName(name))
+            continue;
+        try {
+            assets[`${COMPACTED_DIRNAME}/${name}`] = readFileSync(path.join(dir, name), 'utf8');
+        }
+        catch {
+            // 单个资产读失败不拖垮归档。
+        }
+    }
+    return assets;
+}
+/** 归档单个会话:读 session.json(+compacted 资产)→ gzip → 写 index → 删原目录。失败抛错由调用方统一处理。 */
 function archiveSession(sessionsRoot, id, now) {
     const paths = retentionPaths(sessionsRoot);
     const dir = path.join(sessionsRoot, id);
     const sessionPath = path.join(dir, 'session.json');
     const record = JSON.parse(readFileSync(sessionPath, 'utf8'));
+    // 把压缩归档资产(seg/index/截断原文 blob)内嵌进 gz,避免 rmSync 目录时永久丢失
+    // ——否则 30 天后 resume,历史回捞链整体消失。purge 时随 gz 一起删。
+    const assets = readCompactedAssets(sessionsRoot, id);
+    if (Object.keys(assets).length > 0)
+        record.compactedAssets = assets;
     mkdirSync(paths.archiveDir, { recursive: true });
     const gzPath = path.join(paths.archiveDir, `${id}.json.gz`);
-    writeFileSync(gzPath + '.tmp', gzipSync(readFileSync(sessionPath)));
+    writeFileSync(gzPath + '.tmp', gzipSync(Buffer.from(JSON.stringify(record), 'utf8')));
     renameSync(gzPath + '.tmp', gzPath);
     upsertArchiveIndex(paths.indexPath, {
         id: record.id,

package/dist/session/store.js

@@ -3,8 +3,9 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { gzipSync } from 'node:zlib';
 import path from 'node:path';
-import { MAX_TRACE_BYTES, MAX_TRACE_ROTATIONS } from '../tools/constants.js';
+import { MAX_TRACE_BYTES, MAX_TRACE_ROTATIONS, MAX_COMPACTED_ARCHIVE_BYTES } from '../tools/constants.js';
 import { loadArchivedSession, readArchiveIndex, retentionPaths } from './retention.js';
+import { COMPACTED_DIRNAME, isCompactedAssetName, parseSegmentMeta, renderArchiveIndex, renderCompactedSegment, resultBlobFileName, RESULT_BLOB_FILE_RE, SEGMENT_FILE_RE, } from './compact-archive.js';
 import { config, getActiveModel } from '../config/index.js';
 import { getWorkspaceRoot } from '../workspace/index.js';
 import { isToolRouteGroupName } from '../config/profiles.js';
@@ -46,6 +47,14 @@ function firstUserOf(history) {
     }
     return '';
 }
+/** compacted/ 总量上限:MOCODE_MAX_COMPACTED_BYTES 覆盖(供测试/小盘),非法值回退默认。 */
+function envMaxCompactedBytes() {
+    const raw = process.env.MOCODE_MAX_COMPACTED_BYTES;
+    if (!raw)
+        return MAX_COMPACTED_ARCHIVE_BYTES;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 0 ? n : MAX_COMPACTED_ARCHIVE_BYTES;
+}
 /**
  * Runtime-local session persistence and identity.
  *
@@ -240,6 +249,175 @@ export class SessionStore {
             }
         }
     }
+    /**
+     * 压缩归档:把本次压缩丢弃的旧区消息渲染成 `compacted/seg-NNN.md`,
+     * 并重建 `compacted/index.md`。best-effort——这是压缩的增值能力,不是用户数据主副本
+     * (session.json 仍是主副本),任何失败静默降级,绝不阻塞压缩。
+     *
+     * 编号:扫描已有 seg-NNN.md 取 max+1(外部删除/重命名后仍单调)。
+     * 淘汰:全部 seg 总量超 MAX_COMPACTED_ARCHIVE_BYTES 时,从最老段硬删并重建 index。
+     * 目录缓存失真时与 appendTrace 同模式:清缓存重试一次。
+     *
+     * @returns 段相对路径(供摘要写指针);失败返 null。
+     */
+    archiveCompactedMessages(sessionId, messages) {
+        if (!sessionId || messages.length === 0)
+            return null;
+        const dir = path.join(this.sessionsRoot, sessionId, COMPACTED_DIRNAME);
+        const budget = envMaxCompactedBytes();
+        for (let attempt = 0; attempt < 2; attempt++) {
+            try {
+                this.ensureDir(dir);
+                const seq = this.nextSegmentSeq(dir);
+                const { markdown, meta } = renderCompactedSegment(seq, messages);
+                writeFileSync(path.join(dir, meta.file), markdown, 'utf8');
+                this.pruneCompacted(dir, budget);
+                // 新增了一个 seg,index 必须重建才能列全(prune 是否删旧段不影响这一点;
+                // result blob 不走这里,故不需要每次写 blob 都重建)。
+                this.rebuildCompactedIndex(sessionId, dir);
+                return `.mocode/sessions/${sessionId}/${COMPACTED_DIRNAME}/${meta.file}`;
+            }
+            catch {
+                this.invalidateEnsuredDir(dir);
+                if (attempt === 1)
+                    return null;
+            }
+        }
+        return null;
+    }
+    /**
+     * push-time 截断兜底:工具完整结果在进 history 前被 capToolResultForHistory 裁掉时,
+     * 把**完整原文**另存为 `compacted/result-<toolCallId>.txt`,供事后 grep/read_file 回捞。
+     * best-effort,写失败静默(绝不阻塞工具回灌);纳入与段相同的总量预算淘汰。
+     *
+     * @returns 全文相对路径(供 history 截断内容留指针);失败返 null。
+     */
+    archiveToolResult(sessionId, toolCallId, fullOutput) {
+        if (!sessionId || !toolCallId || !fullOutput)
+            return null;
+        const dir = path.join(this.sessionsRoot, sessionId, COMPACTED_DIRNAME);
+        const fileName = resultBlobFileName(toolCallId);
+        for (let attempt = 0; attempt < 2; attempt++) {
+            try {
+                this.ensureDir(dir);
+                writeFileSync(path.join(dir, fileName), fullOutput, 'utf8');
+                this.pruneCompacted(dir, envMaxCompactedBytes());
+                return `.mocode/sessions/${sessionId}/${COMPACTED_DIRNAME}/${fileName}`;
+            }
+            catch {
+                this.invalidateEnsuredDir(dir);
+                if (attempt === 1)
+                    return null;
+            }
+        }
+        return null;
+    }
+    /**
+     * resume 归档会话时,把 gz 内嵌的 compacted 资产(seg/index/截断原文 blob)写回磁盘,
+     * 恢复历史回捞链。best-effort:任何坏条目跳过。防 zip-slip:只接受 compacted/ 下
+     * 白名单单层文件名。
+     */
+    restoreCompactedAssets(id, record) {
+        const assets = record.compactedAssets;
+        if (!assets || typeof assets !== 'object')
+            return;
+        const dir = path.join(this.sessionsRoot, id, COMPACTED_DIRNAME);
+        for (const [relPath, content] of Object.entries(assets)) {
+            if (typeof content !== 'string')
+                continue;
+            const base = relPath.startsWith(`${COMPACTED_DIRNAME}/`) ? relPath.slice(COMPACTED_DIRNAME.length + 1) : null;
+            if (!base || base.includes('/') || base.includes('\\') || !isCompactedAssetName(base))
+                continue;
+            try {
+                this.ensureDir(dir);
+                writeFileSync(path.join(dir, base), content, 'utf8');
+            }
+            catch {
+                this.invalidateEnsuredDir(dir);
+            }
+        }
+    }
+    /** 扫描 seg-NNN.md 取下一个编号;损坏文件名跳过。 */
+    nextSegmentSeq(dir) {
+        let max = 0;
+        for (const name of this.listDirNames(dir)) {
+            const m = SEGMENT_FILE_RE.exec(name);
+            if (m)
+                max = Math.max(max, Number(m[1]));
+        }
+        return max + 1;
+    }
+    /**
+     * compacted/ 全目录(seg 段 + result blob)统一字节预算淘汰:
+     * 超 MAX_COMPACTED_ARCHIVE_BYTES 时从最老文件(mtime,再按名)硬删。
+     * 唯一豁免 = 编号最大的那个 seg(始终保住最近一代压缩的完整回捞入口);
+     * index.md 不占删除候选(段变更后重建)。
+     *
+     * @returns 是否有 seg 被删(调用方据此重建 index)。
+     */
+    pruneCompacted(dir, budget) {
+        if (!(budget > 0))
+            return false;
+        const newestSeq = this.listDirNames(dir).reduce((max, name) => {
+            const m = SEGMENT_FILE_RE.exec(name);
+            return m ? Math.max(max, Number(m[1])) : max;
+        }, 0);
+        const candidates = this.listDirNames(dir)
+            .filter((name) => SEGMENT_FILE_RE.test(name) || RESULT_BLOB_FILE_RE.test(name))
+            .map((name) => {
+            const m = SEGMENT_FILE_RE.exec(name);
+            const st = statSync(path.join(dir, name));
+            return { name, size: st.size, mtimeMs: st.mtimeMs, seq: m ? Number(m[1]) : null };
+        })
+            // 最老在前:blob 与跨类型文件按 mtime;同刻按名,保证确定性。
+            .sort((a, b) => a.mtimeMs - b.mtimeMs || (a.name < b.name ? -1 : 1));
+        let total = candidates.reduce((s, e) => s + e.size, 0);
+        let removedSeg = false;
+        for (const e of candidates) {
+            if (total <= budget)
+                break;
+            if (e.seq !== null && e.seq === newestSeq)
+                continue; // 永不删最新段
+            try {
+                unlinkSync(path.join(dir, e.name));
+            }
+            catch {
+                break; // 删不动就停止淘汰,避免死循环
+            }
+            total -= e.size;
+            if (e.seq !== null)
+                removedSeg = true;
+        }
+        return removedSeg;
+    }
+    /** 仅凭现存 seg 文件重建 index.md(段被外部增删后也一致)。 */
+    rebuildCompactedIndex(sessionId, dir) {
+        const metas = [];
+        for (const name of this.listDirNames(dir)) {
+            if (!SEGMENT_FILE_RE.test(name))
+                continue;
+            try {
+                const meta = parseSegmentMeta(readFileSync(path.join(dir, name), 'utf8'));
+                if (meta)
+                    metas.push(meta);
+            }
+            catch {
+                // 单个段损坏不拖垮索引。
+            }
+        }
+        const relativeDir = `.mocode/sessions/${sessionId}/compacted`;
+        writeFileSync(path.join(dir, 'index.md'), renderArchiveIndex(metas, relativeDir), 'utf8');
+    }
+    listDirNames(dir) {
+        try {
+            return readdirSync(dir, { withFileTypes: true })
+                .filter((e) => e.isFile())
+                .map((e) => e.name);
+        }
+        catch {
+            return [];
+        }
+    }
     /** 读取 <id>/usage.jsonl 全部记录;文件不存在或损坏行跳过。 */
     readUsage(id) {
         const file = path.join(this.sessionsRoot, id, 'usage.jsonl');
@@ -308,14 +486,20 @@ export class SessionStore {
             }
         }
     }
-    load(id) {
+    load(id, opts) {
         const currentPath = this.sessionPath(id);
         const legacyPath = path.join(this.sessionsRoot, `${id}.json`);
         const source = existsSync(currentPath) ? currentPath : legacyPath;
         // 活会话与 legacy 单文件都没有:回退从归档 gz 取回(30-90 天的会话仍可 resume)。
         if (!existsSync(source)) {
             const archived = loadArchivedSession(this.sessionsRoot, id);
-            return archived ?? null;
+            if (!archived)
+                return null;
+            // 仅 resume 显式要求时把 gz 内嵌的 compacted 资产写回磁盘(load 也被会话列表等
+            // 只读路径调用,不能在那些场景产生写盘副作用)。
+            if (opts?.restoreAssets)
+                this.restoreCompactedAssets(id, archived);
+            return archived;
         }
         try {
             const rec = JSON.parse(readFileSync(source, 'utf8'));

package/dist/tools/builtins/grep.js

@@ -160,7 +160,8 @@ export const grepTool = {
     name: 'grep',
     description: 'Search file contents by regex (recursive; powered by ripgrep: respects .gitignore, skips binaries).\n' +
         'Output: per-file header "<path>: N matches, lines [l1, l2, ...]" plus rendered lines with ORIGINAL INDENTATION kept.\n' +
-        'Pass context=2..5 to include neighbouring lines inline (like ripgrep -C) instead of following each hit with a read_file round-trip. Hard wall 120s; narrow the glob if a tree contains network mounts. Use read_file when you need a whole region or exact edit text.',
+        'Pass context=2..5 to include neighbouring lines inline (like ripgrep -C) instead of following each hit with a read_file round-trip. Hard wall 120s; narrow the glob if a tree contains network mounts. Use read_file when you need a whole region or exact edit text.\n' +
+        'Note: .mocode/ is gitignored; to search session data (e.g. .mocode/sessions/<id>/compacted archived history) you MUST narrow glob to that path, e.g. glob=".mocode/sessions/**".',
     parameters: {
         type: 'object',
         properties: {
@@ -200,7 +201,9 @@ export const grepTool = {
             controller.abort();
         }, GREP_TIMEOUT_MS);
         try {
-            const result = await runRipgrep({ pattern, glob, context }, controller.signal);
+            // glob 显式限定到 .mocode(gitignore 内)时放开 VCS ignore,否则 rg 零文件退出。
+            const noIgnoreVcs = glob === '.mocode/**' || glob.startsWith('.mocode/');
+            const result = await runRipgrep({ pattern, glob, context, noIgnoreVcs }, controller.signal);
             switch (result.status) {
                 case 'regex_error':
                     return `错误:非法正则 ${pattern}: ${result.message}`;

package/dist/tools/builtins/memory-graph.js

@@ -1,4 +1,5 @@
 import { addTriple, graphStats, neighborsOf, pathBetween } from '../../memory/graph.js';
+import { formatRecallStats } from '../../memory/recall-stats.js';
 // ---------- memory_graph ----------
 // 知识图谱维护工具:邻居遍历(1-3 跳,可 relation 过滤)、两点最短路径、手工加三元组、看图统计。
 // 关键词搜索已并入 memory_search(条目 + 图谱事实一次返回),本工具不再提供 search。
@@ -55,6 +56,7 @@ export const memoryGraphTool = {
                 `实体 ${s.entities} 条边(active ${s.edgesActive} / 已失效 ${s.edgesInvalid})`,
                 `project: ${s.byScope.project.entities} 实体, ${s.byScope.project.edges} 边`,
                 `global:  ${s.byScope.global.entities} 实体, ${s.byScope.global.edges} 边`,
+                formatRecallStats(),
             ].join('\n');
         }
         if (action === 'neighbors') {

package/dist/tools/builtins/memory-search.js

@@ -1,13 +1,14 @@
 import { searchEntries } from '../../memory/store.js';
-import { searchGraph } from '../../memory/graph.js';
+import { searchGraphFacts } from '../../memory/graph.js';
+import { recordRecallSearch } from '../../memory/recall-stats.js';
 // ---------- memory_search ----------
 // 唯一记忆搜索入口:关键词搜记忆正文(多词子串匹配,name 权重最高)+ 知识图谱事实段
-// (命中实体的 active 边)。命中条目即 bump recallCount(遗忘衰减依据)。
-// 结果走 capToolResultForHistory 的放宽上限(同 use_skill,保正文完整)。
+// (CJK 分词加权、边级相关度 + 一跳邻接,跨 global/project 两 scope)。命中条目即 bump
+// recallCount(遗忘衰减依据)。结果走 capToolResultForHistory 的放宽上限(同 use_skill)。
 const GRAPH_FACTS_LIMIT = 10;
 export const memorySearchTool = {
     name: 'memory_search',
-    description: 'Search memory entries by keyword (substring match), returning full body. Also surfaces knowledge-graph facts (active edges) for entities matching the query.',
+    description: 'Search memory entries by keyword (substring match), returning full body. Also surfaces knowledge-graph facts (active edges across project + global), ranked by CJK-aware term overlap on entity names/aliases/relation/fact, plus one-hop neighbor edges for context.',
     parameters: {
         type: 'object',
         properties: {
@@ -37,23 +38,28 @@ export const memorySearchTool = {
         const entryText = r
             .map((e) => `# [${e.id}] ${e.name} (${e.type}, recalled ${e.recallCount})\nsummary: ${e.summary}\n\n${e.body}`)
             .join('\n\n---\n\n');
-        // 知识图谱事实段:命中实体的 active 边(容错:图坏了不连累条目搜索)。
+        // 知识图谱事实段:边级相关度检索(容错:图坏了不连累条目搜索)。
         let graphText = '';
+        let graphHit = false;
         try {
-            const g = searchGraph(query, 8);
-            if (g.edges.length > 0) {
-                const lines = g.edges
-                    .slice(0, GRAPH_FACTS_LIMIT)
-                    .map((e) => `${e.src} --[${e.relation}]--> ${e.dst}${e.fact ? ` (${e.fact})` : ''}`);
-                const more = g.edges.length > GRAPH_FACTS_LIMIT
-                    ? `\n…(共 ${g.edges.length} 条,其余用 memory_graph action=neighbors 展开)`
-                    : '';
-                graphText = `\n\n## 知识图谱事实\n${lines.join('\n')}${more}`;
+            const hits = searchGraphFacts(query, { scope: 'all', limit: GRAPH_FACTS_LIMIT, neighbors: 4 });
+            graphHit = hits.length > 0;
+            if (graphHit) {
+                const lines = hits.map((h) => {
+                    const src = h.srcEntity?.name ?? h.edge.src;
+                    const dst = h.dstEntity?.name ?? h.edge.dst;
+                    const fact = h.edge.fact ? ` (${h.edge.fact})` : '';
+                    const tag = h.viaNeighbor ? ' [neighbor]' : '';
+                    const scopeTag = h.edge.scope === 'global' ? '[global]' : '[project]';
+                    return `${scopeTag} ${src} --[${h.edge.relation}]--> ${dst}${fact}${tag}`;
+                });
+                graphText = `\n\n## 知识图谱事实\n${lines.join('\n')}`;
             }
         }
         catch {
             // 静默:图谱段是增强,失败只降级为纯条目结果
         }
+        recordRecallSearch(graphHit); // 埋点:pull 召回使用情况(写盘失败静默)
         if (!entryText && !graphText)
             return `(无匹配记忆:query="${query}")`;
         if (!entryText)