evolcore 0.0.28 → 0.0.29-test.0

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

@@ -0,0 +1,395 @@
+/**
+ * launch-consolidation.ts — 拉起一次整理会话
+ *
+ * 两个入口共用这一处实现：
+ *   - ipc.ts：手动 `ec memory consolidate --mode X`
+ *   - index.ts：定时检查（五类候选）、compress / session-new 自动触发
+ *
+ * 流程：序列化上下文文件 → 写一次性触发器 → 交给 TriggerDefinitionManager。
+ * `execution.memoryMode` 会经 session.metadata 透传到渲染层与 ipc 的权限校验。
+ */
+import fs from 'fs';
+import path from 'path';
+import { resolveRoot } from '../../paths.js';
+import { serializeConsolidationContext } from './consolidation-context.js';
+import { normalizeTriggerDefinition } from '../../trigger/validation.js';
+import { formatChannelKey } from '../channel-loader.js';
+import { formatPeerKey } from '../relation/peer-identity.js';
+import { logger } from '../../utils/logger.js';
+/**
+ * 清理当前 agent 的旧整理批次。
+ * 启动新整理时调用，保留最新的一个会话历史用于查看和调试。
+ */
+function cleanupPreviousConsolidationBatches(selfAid) {
+    try {
+        const batchRoot = path.join(resolveRoot(), 'memory', 'consolidation-batches');
+        if (!fs.existsSync(batchRoot))
+            return;
+        // 匹配格式：YYYYMMDDTHHMMSS-<selfAid>-*
+        const escapedAid = selfAid.replace(/\./g, '\\.');
+        const pattern = new RegExp(`^\\d{8}T\\d{6}-${escapedAid}-`);
+        const entries = fs.readdirSync(batchRoot, { withFileTypes: true })
+            .filter(e => e.isDirectory() && pattern.test(e.name))
+            .map(e => ({ name: e.name, path: path.join(batchRoot, e.name) }))
+            .sort((a, b) => b.name.localeCompare(a.name)); // 最新的在前
+        // 保留最新的一个，删除其他
+        for (let i = 1; i < entries.length; i++) {
+            const dir = entries[i];
+            try {
+                fs.rmSync(dir.path, { recursive: true, force: true });
+                logger.debug(`[Memory] 清理前一次整理批次: ${dir.name}`);
+            }
+            catch (e) {
+                logger.warn(`[Memory] 清理前一次整理批次失败 ${dir.name}: ${e?.message}`);
+            }
+        }
+    }
+    catch (e) {
+        logger.warn(`[Memory] 清理整理批次时出错: ${e?.message}`);
+    }
+}
+export function buildDebugTaskContext(input) {
+    const { session } = input;
+    const meta = (session.metadata ?? {});
+    const sessionType = session.sessionType ?? meta.sessionType ?? 'main';
+    let channel = session.channelType || session.channel;
+    let chatType = session.chatType || 'private';
+    let peerId = meta.peerId;
+    let peerKeyId = chatType === 'group'
+        ? (meta.groupId || session.channelId)
+        : (meta.peerId || session.channelId);
+    let threadId = session.threadId || undefined;
+    if (session.channelId?.startsWith('trigger:') && session.selfAID && input.getTrigger) {
+        const triggerId = session.channelId.slice('trigger:'.length);
+        const origin = input.getTrigger(session.selfAID, triggerId)?.origin;
+        if (origin?.channelType) {
+            channel = origin.channelType;
+            chatType = origin.delivery?.chatType ?? 'private';
+            peerId = origin.peerId;
+            peerKeyId = chatType === 'group' ? origin.channelId : (origin.peerId ?? origin.channelId);
+            threadId = origin.threadId;
+        }
+    }
+    return {
+        sessionId: session.id,
+        baseagent: session.baseagent,
+        channel,
+        channelId: session.channelId,
+        chatType,
+        selfAid: session.selfAID,
+        peerId,
+        peerKey: channel && peerKeyId ? formatPeerKey(channel, peerKeyId) : undefined,
+        peerName: meta.peerName,
+        peerType: meta.peerType,
+        threadId,
+        sessionType,
+        memoryMode: meta.memoryMode,
+        memoryScope: meta.memoryScope,
+        consolidationBatchDir: meta.consolidationBatchDir ?? meta.consolidationLogBase,
+        sessionRuntimeDir: input.sessionRuntimeDir,
+    };
+}
+/**
+ * 序列化上下文并直接创建整理会话。
+ * 失败抛错，调用方负责决定是否记录诊断或回传错误。
+ */
+export async function launchConsolidation(channel, params) {
+    const { taskCtx, mode, triggeredBy, ownerAid } = params;
+    const effectiveCtx = params.peerKeyOverride
+        ? { ...taskCtx, peerKey: params.peerKeyOverride }
+        : taskCtx;
+    const selfAid = effectiveCtx.selfAid;
+    if (!selfAid)
+        throw new Error('无法确定当前 agent AID（selfAid 为空）');
+    // 清理旧的整理批次（保留最新的一个历史）
+    cleanupPreviousConsolidationBatches(selfAid);
+    // notes 模式：pending/ → processing/ 快照迁移（在序列化上下文之前执行，声明认领）
+    let memoryDir;
+    if (mode === 'notes') {
+        memoryDir = effectiveCtx.peerKey
+            ? path.join(resolveRoot(), 'agents', selfAid, 'relations', effectiveCtx.peerKey, 'memory')
+            : path.join(resolveRoot(), 'agents', selfAid, 'personal', 'memory');
+        const pendingDir = path.join(memoryDir, 'pending');
+        const processingDir = path.join(memoryDir, 'processing');
+        if (fs.existsSync(processingDir)) {
+            // 上一批还没收尾（会话仍在跑，或 daemon 中途重启丢了收尾），不覆盖、不合并
+            logger.warn(`[Memory] processing/ 已存在，跳过本次迁移（上一批未收尾）: ${processingDir}`);
+        }
+        else if (fs.existsSync(pendingDir)) {
+            try {
+                const count = fs.readdirSync(pendingDir).filter(f => f.endsWith('.md')).length;
+                fs.renameSync(pendingDir, processingDir);
+                // 立即重建空 pending 目录，供主会话后续写 note
+                fs.mkdirSync(pendingDir, { recursive: true });
+                logger.info(`[Memory] pending → processing 快照完成（${count} 条 note）: ${processingDir}`);
+            }
+            catch (e) {
+                // 迁移失败不阻断整理会话启动，整理会话会发现 processing 目录空并输出 NOOP
+                logger.warn(`[Memory] pending → processing 迁移失败: ${e?.message}`);
+            }
+        }
+    }
+    const ctxFile = serializeConsolidationContext({
+        mode,
+        triggeredBy,
+        taskCtx: effectiveCtx,
+        ownerAid,
+        sessionRuntimeDir: effectiveCtx.sessionRuntimeDir,
+        ownerInvolved: params.ownerInvolved,
+        forgetAfterDays: params.forgetAfterDays,
+        scopeOverride: params.scopeOverride,
+    });
+    const baseagent = effectiveCtx.baseagent ?? 'claude';
+    const now = Date.now();
+    const scopeTag = params.scopeOverride ? `-${params.scopeOverride}` : '';
+    const triggerId = `memory-consolidate-${mode}${scopeTag}-${now.toString(36)}`;
+    // 整理会话的渠道信息（origin）：发起时抓取，供反馈时直接投递到原会话渠道。
+    // 用 channelId/peerId/threadId 三要素——不依赖 evolcore sessionId，renew/`/new` 换会话也不影响送达。
+    const feedbackOrigin = effectiveCtx.channel && effectiveCtx.peerId ? {
+        channelKey: formatChannelKey({ type: effectiveCtx.channel, selfAID: selfAid, name: 'main' }),
+        channelId: effectiveCtx.peerId,
+        channelType: effectiveCtx.channel,
+        peerId: effectiveCtx.peerId,
+        session: effectiveCtx.threadId ? 'thread' : 'main',
+        ...(effectiveCtx.threadId ? { threadId: effectiveCtx.threadId } : {}),
+        delivery: { chatType: effectiveCtx.chatType ?? 'private' },
+    } : undefined;
+    // 构造 TriggerDefinition 形状的数据载体。
+    // daemonChannel.converse() 从 ctx.trigger 读 execution.memoryMode / id / name / agentAid。
+    // 不再调 manager.create()——本函数直接创建会话，不进 trigger 系统的调度/持久化。
+    const triggerDef = normalizeTriggerDefinition({
+        $schema_version: 3.1,
+        id: triggerId,
+        agentAid: selfAid,
+        enabled: true,
+        name: triggerId,
+        description: `记忆整理（mode=${mode}${effectiveCtx.peerKey ? `，peerKey=${effectiveCtx.peerKey}` : ''}）`,
+        createdAt: now,
+        updatedAt: now,
+        source: { type: 'once' },
+        execution: {
+            type: 'trigger_session',
+            prompt: [
+                '你正在执行记忆整理任务。',
+                `本次整理模式：${mode}`,
+                `整理上下文文件路径：${ctxFile.filePath}`,
+                '',
+                '请先读取上述上下文文件，再按照注入的整理规范完成本次整理。',
+            ].join('\n'),
+            baseagent,
+            thread: 'by_run',
+            onError: 'retry',
+            noopSentinel: '[[NOOP]]',
+            memoryMode: mode,
+            ...(params.scopeOverride ? { memoryScope: params.scopeOverride } : {}),
+            // 透传到 session.metadata，供 ipc.ts 写 ops 流水、收尾流程读取
+            consolidationBatchDir: ctxFile.batchDir,
+            ...(ctxFile.chatDir ? { consolidationChatDir: ctxFile.chatDir } : {}),
+            ...(memoryDir ? { consolidationMemoryDir: memoryDir } : {}),
+        },
+        // 不使用 trigger 的 feedback 机制；反馈由收尾流程直接调 adapter.send() 投递
+        feedback: { strategy: 'silent' },
+        ...(feedbackOrigin ? { origin: feedbackOrigin } : {}),
+        reliability: {
+            concurrency: 'forbid',
+            missedPolicy: 'run_once',
+            retry: { maxAttempts: 0, backoffMs: 30_000 },
+        },
+    });
+    // normalizeTriggerDefinition 只保留白名单字段，自定义字段在其后补挂。
+    // 反馈目标（发起时渠道三元组）与触发方式，收尾流程据此投递 / 判断是否反馈。
+    if (feedbackOrigin) {
+        triggerDef.execution.feedbackOrigin = feedbackOrigin;
+    }
+    triggerDef.execution.consolidationTriggeredBy = triggeredBy;
+    // 直接创建整理会话并发送第一条消息——不再经 TriggerRuntimeScheduler。
+    // 用 getOrCreateConversationSession + converse，与旧 trigger_session 执行路径同源（见 daemon.ts）。
+    const projectPath = params.projectPath ?? path.join(resolveRoot(), 'agents', selfAid);
+    const runId = `${triggerId}-run`;
+    const session = await channel.getOrCreateConversationSession(triggerDef, projectPath, baseagent, runId);
+    const prompt = triggerDef.execution.prompt;
+    // 不 await：整理会话在后台跑，收尾由 task:completed/error/interrupted 事件驱动
+    void channel.converse(prompt, {
+        trigger: triggerDef,
+        runId,
+        firedAt: now,
+        projectPath,
+        baseagent,
+        session,
+        causation: undefined,
+    }).catch((e) => {
+        logger.warn(`[Memory] 整理会话执行失败（mode=${mode}，session=${session.id}）: ${e?.message}`);
+    });
+    logger.info(`[Memory] 已拉起整理会话（mode=${mode}，triggeredBy=${triggeredBy}，` +
+        `selfAid=${selfAid}${effectiveCtx.peerKey ? `，peerKey=${effectiveCtx.peerKey}` : ''}，` +
+        `session=${session.id}）`);
+    return {
+        triggerId,
+        contextFile: ctxFile.filePath,
+        contextFilePath: ctxFile.contextFilePath,
+        logFile: ctxFile.contextFilePath,
+        batchDir: ctxFile.batchDir,
+        executionSessionId: session.id,
+    };
+}
+/**
+ * 手动 consolidate 用：在超时内轮询等 runner 分配 agentSessionId。
+ * 拿到立即返回；超时返回已拿到的部分，不抛错。
+ *
+ * 会话创建后 executionSessionId 立刻可用，但 agentSessionId 要等 runner 初始化
+ * 并开始第一轮才写入 session 记录，所以这里必须轮询等待。
+ */
+export async function waitForConsolidationSession(opts) {
+    const executionSessionId = opts.executionSessionId;
+    if (!executionSessionId)
+        return {};
+    const deadline = Date.now() + (opts.timeoutMs ?? 10_000);
+    const interval = opts.intervalMs ?? 250;
+    while (true) {
+        try {
+            const agentSessionId = await opts.readAgentSessionId(executionSessionId);
+            if (agentSessionId)
+                return { executionSessionId, agentSessionId };
+        }
+        catch { /* 会话记录写到一半，下一轮再读 */ }
+        if (Date.now() >= deadline)
+            return { executionSessionId };
+        await new Promise(r => setTimeout(r, interval));
+    }
+}
+/** 把 entry 移进 destDir；重名时加时间戳后缀，不覆盖已有文件。 */
+function moveIntoDir(srcPath, destDir, stamp) {
+    const name = path.basename(srcPath);
+    let dest = path.join(destDir, name);
+    if (fs.existsSync(dest)) {
+        if (fs.statSync(srcPath).isDirectory() && fs.statSync(dest).isDirectory()) {
+            // 目录（如 pending/archive/）逐个合并子项
+            for (const child of fs.readdirSync(srcPath))
+                moveIntoDir(path.join(srcPath, child), dest, stamp);
+            fs.rmdirSync(srcPath);
+            return;
+        }
+        const ext = path.extname(name);
+        dest = path.join(destDir, `${path.basename(name, ext)}-${stamp}${ext}`);
+    }
+    fs.renameSync(srcPath, dest);
+}
+/**
+ * 整理会话结束后的收尾，task:completed / task:error / task:interrupted 都走这里。
+ *   - processing/ 里的 note：成功 → archive/notes/，失败 → 归还 pending/（下次重试）
+ *   - processing/ 里的其他条目（如 pending/archive/）原样还回 pending/
+ *   - 成功才写 checkpoint，失败时下次整理仍取同一段增量消息
+ *   - ops 汇总无论成败都写
+ * 幂等：processing/ 不存在时只写汇总。
+ */
+export async function onConsolidationComplete(params) {
+    const now = params.now ?? Date.now();
+    const stamp = new Date(now).toISOString().replace(/[-:]/g, '').slice(0, 15);
+    const result = { moved: 0, checkpointWritten: false };
+    if (params.memoryDir) {
+        const processingDir = path.join(params.memoryDir, 'processing');
+        if (fs.existsSync(processingDir)) {
+            const pendingDir = path.join(params.memoryDir, 'pending');
+            const noteDest = params.success ? path.join(params.memoryDir, 'archive', 'notes') : pendingDir;
+            fs.mkdirSync(noteDest, { recursive: true });
+            fs.mkdirSync(pendingDir, { recursive: true });
+            for (const entry of fs.readdirSync(processingDir)) {
+                const src = path.join(processingDir, entry);
+                const isNote = entry.endsWith('.md') && fs.statSync(src).isFile();
+                moveIntoDir(src, isNote ? noteDest : pendingDir, stamp);
+                if (isNote)
+                    result.moved++;
+            }
+            fs.rmdirSync(processingDir);
+            result.movedTo = noteDest;
+        }
+    }
+    if (params.success && params.chatDir) {
+        const { writeCheckpoint } = await import('./consolidation-context.js');
+        writeCheckpoint(params.chatDir, now);
+        result.checkpointWritten = true;
+    }
+    const { summarizeOpsRecords, appendOpsRecord } = await import('./consolidation-ops-records.js');
+    appendOpsRecord(params.batchDir, summarizeOpsRecords(params.batchDir));
+    logger.info(`[Memory] 整理收尾（${params.success ? '成功' : '失败'}）：归位 ${result.moved} 条 note` +
+        `${result.movedTo ? ` → ${result.movedTo}` : ''}，checkpoint=${result.checkpointWritten}`);
+    return result;
+}
+/** 会话结束后把产出回填到批次任务书。 */
+export function recordConsolidationOutcome(contextFilePath, outcome) {
+    try {
+        fs.appendFileSync(contextFilePath, `\n---\n\n## 本次产出\n\n${outcome}\n`, 'utf-8');
+    }
+    catch { /* ignore */ }
+}
+/**
+ * 整理会话失败/中断时，依据 ops.jsonl 逐条回撤成功的写操作。
+ * 回撤顺序：倒序（最后写的先撤）。
+ *
+ *   create → 删除写入的文件，若有 archivedFiles 将其还原回 consolidated/
+ *   update → 用 prevTags 重写文件（恢复修改前的标签，不改 updatedAt 以外的内容）
+ *   archive → 将文件从 archivedTo 移回 sourceFile
+ */
+export async function rollbackConsolidation(batchDir, selfAid) {
+    const { readRollbackRecords, appendOpsRecord } = await import('./consolidation-ops-records.js');
+    const entries = readRollbackRecords(batchDir);
+    let rolledBack = 0;
+    const errors = [];
+    for (const entry of entries) {
+        try {
+            if (entry.op === 'create') {
+                // 删除写入的文件
+                if (entry.filePath && fs.existsSync(entry.filePath)) {
+                    fs.unlinkSync(entry.filePath);
+                }
+                // 还原被归档的旧文件
+                for (const af of (entry.archivedFiles ?? [])) {
+                    if (af.archivedTo && fs.existsSync(af.archivedTo)) {
+                        const dest = af.source.includes('/') || af.source.includes('\\')
+                            ? af.source
+                            : path.join(path.dirname(af.archivedTo), path.basename(af.archivedTo));
+                        fs.mkdirSync(path.dirname(dest), { recursive: true });
+                        fs.renameSync(af.archivedTo, dest);
+                    }
+                }
+                rolledBack++;
+            }
+            else if (entry.op === 'update') {
+                // 恢复修改前的 tags：读文件、替换 tags 行、重写（不重签名，仅文本恢复）
+                const target = entry.target;
+                if (target && fs.existsSync(target)) {
+                    const raw = fs.readFileSync(target, 'utf-8');
+                    const prevTags = entry.prevTags ?? [];
+                    const tagsLine = prevTags.length > 0 ? `tags: [${prevTags.join(', ')}]` : '';
+                    // 替换 tags: [...] 行；若 prevTags 为空则移除该行
+                    const updated = raw.replace(/^tags: \[.*\]$/m, tagsLine).replace(/^\n$/, '');
+                    fs.writeFileSync(target, updated, 'utf-8');
+                    rolledBack++;
+                }
+            }
+            else if (entry.op === 'archive') {
+                // 将文件从 archivedTo 移回 sourceFile
+                if (entry.archivedTo && entry.sourceFile && fs.existsSync(entry.archivedTo)) {
+                    fs.mkdirSync(path.dirname(entry.sourceFile), { recursive: true });
+                    fs.renameSync(entry.archivedTo, entry.sourceFile);
+                    rolledBack++;
+                }
+            }
+        }
+        catch (e) {
+            const msg = `回撤 ${entry.op} "${entry.target}" 失败: ${e?.message}`;
+            errors.push(msg);
+            logger.warn(`[Memory] ${msg}`);
+        }
+    }
+    appendOpsRecord(batchDir, {
+        ts: new Date().toISOString(),
+        op: 'session-end',
+        success: false,
+        movedNotes: 0,
+        checkpointWritten: false,
+    });
+    logger.info(`[Memory] 回撤完成：回撤 ${rolledBack} 条操作，${errors.length} 个失败`);
+    return { rolledBack, errors };
+}
+export { resolveRoot };

package/dist/core/memory/memory-admin.js

@@ -0,0 +1,234 @@
+/**
+ * memory-admin.ts — `/memory` 斜杠命令的记忆查看与维护
+ *
+ * 只做文件层面的读写，权限判定由调用方（slash-handler）负责：
+ *  - 查看：概览、pending note、MEMORY.md 索引、consolidated / archive 列表、单条正文
+ *  - 维护：撤销 note、归档 / 恢复正式记忆、重建索引
+ *
+ * 整理（拉起整理会话）不在这里，由 daemon 注入的 launcher 完成。
+ */
+import fs from 'fs';
+import path from 'path';
+import { resolveScopeDirs, archiveMemory, dropMemoryNote, listMemoryNotes } from './memory-writer.js';
+import { rebuildIndex, DEFAULT_INDEX_MAX_BYTES } from './index-manager.js';
+import { refreshMemoryMeta, readMemoryMeta } from './index-manager.js';
+import { parseSignatureBlock, verifyMemoryFile } from './memory-signature.js';
+import { readFmArray, readFmValue, readUpdatedAtMs, reviewWindowDays, DEFAULT_FORGET_AFTER_DAYS } from './staleness.js';
+export const MEMORY_SCOPES = ['relation', 'agent', 'owner'];
+const SLUG_RE = /^[a-zA-Z0-9][a-zA-Z0-9-]{0,63}$/;
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** 单条正文回显上限，避免刷屏 */
+const MAX_SHOW_CHARS = 4000;
+function ctxOf(target) {
+    return { selfAid: target.selfAid, peerKey: target.peerKey };
+}
+export function scopeDirs(target, scope) {
+    return resolveScopeDirs(scope, ctxOf(target), target.ownerAid);
+}
+export function isMemoryScope(value) {
+    return !!value && MEMORY_SCOPES.includes(value);
+}
+function assertSlug(slug) {
+    if (!SLUG_RE.test(slug))
+        throw new Error(`slug 格式非法：只允许字母、数字、连字符，长度 1-64，当前值: "${slug}"`);
+}
+function countMd(dir) {
+    try {
+        return fs.readdirSync(dir).filter(f => f.endsWith('.md')).length;
+    }
+    catch {
+        return 0;
+    }
+}
+function fmtDate(ms) {
+    if (!ms)
+        return '-';
+    return new Date(ms).toISOString().slice(0, 16).replace('T', ' ');
+}
+/** 去掉签名块，只留正文（含 frontmatter） */
+function stripSignature(content) {
+    return parseSignatureBlock(content).payload.trimEnd();
+}
+// ── 查看 ────────────────────────────────────────────────────────────────────
+/** 概览：各作用域条数、pending 数、索引大小、最近更新时间。 */
+export function memoryOverview(target, scopes) {
+    const mc = target.memoryConfig;
+    const indexMax = mc?.indexMaxBytes ?? DEFAULT_INDEX_MAX_BYTES;
+    const lines = ['🧠 记忆概览'];
+    if (mc?.enableRelation === false)
+        lines.push('⚠️ 记忆系统已停用（memory.enableRelation=false）');
+    for (const scope of scopes) {
+        let dirs;
+        try {
+            dirs = scopeDirs(target, scope);
+        }
+        catch (e) {
+            lines.push(`\n[${scope}] 不可用：${e?.message || String(e)}`);
+            continue;
+        }
+        const disabled = (scope === 'agent' && mc?.enableAgent === false) || (scope === 'owner' && mc?.enableOwner === false);
+        const meta = readMemoryMeta(dirs.memoryDir);
+        const consolidated = countMd(dirs.consolidatedDir);
+        const archived = countMd(path.join(dirs.memoryDir, 'archive', 'consolidated'));
+        const indexPath = path.join(dirs.memoryDir, 'MEMORY.md');
+        const indexBytes = fs.existsSync(indexPath) ? fs.statSync(indexPath).size : 0;
+        lines.push(`\n[${scope}]${disabled ? '（已停用）' : ''}`);
+        if (scope === 'relation') {
+            lines.push(`  关系: ${target.peerKey}`);
+            lines.push(`  待整理 note: ${countMd(path.join(dirs.memoryDir, 'pending'))}` +
+                (fs.existsSync(path.join(dirs.memoryDir, 'processing')) ? '（有一批正在整理）' : ''));
+        }
+        if (scope === 'owner')
+            lines.push(`  owner: ${target.ownerAid}`);
+        lines.push(`  正式记忆: ${consolidated}  已归档: ${archived}`);
+        lines.push(`  索引: ${indexBytes}/${indexMax} 字节`);
+        if (meta) {
+            const flags = [meta.hasToGeneralize ? '待泛化' : '', meta.hasToPromote ? '待提升' : '', meta.profileSlug ? `画像=${meta.profileSlug}` : '']
+                .filter(Boolean).join('，');
+            if (flags)
+                lines.push(`  标记: ${flags}`);
+            lines.push(`  最老记忆: ${fmtDate(meta.oldestMtimeMs)}  元数据刷新: ${fmtDate(meta.updatedAt)}`);
+        }
+    }
+    return lines.join('\n');
+}
+/** consolidated/（或 archive/consolidated/）下的记忆列表。 */
+export function listMemoryFiles(target, scope, archived = false, now = Date.now()) {
+    const dirs = scopeDirs(target, scope);
+    const dir = archived ? path.join(dirs.memoryDir, 'archive', 'consolidated') : dirs.consolidatedDir;
+    if (!fs.existsSync(dir))
+        return [];
+    const forgetAfterDays = target.memoryConfig?.forgetAfterDays ?? DEFAULT_FORGET_AFTER_DAYS;
+    const out = [];
+    for (const f of fs.readdirSync(dir).filter(n => n.endsWith('.md')).sort()) {
+        const fp = path.join(dir, f);
+        let content;
+        let mtimeMs;
+        try {
+            content = fs.readFileSync(fp, 'utf-8');
+            mtimeMs = fs.statSync(fp).mtimeMs;
+        }
+        catch {
+            continue;
+        }
+        const tags = readFmArray(content, 'tags');
+        const updatedAtMs = readUpdatedAtMs(content) ?? mtimeMs;
+        const windowMs = reviewWindowDays(tags, { forgetAfterDays }) * DAY_MS;
+        out.push({
+            slug: f.replace(/\.md$/, ''),
+            description: readFmValue(content, 'description') ?? '',
+            tags,
+            mtimeMs,
+            updatedAtMs,
+            signed: !!parseSignatureBlock(content).fields,
+            reviewInDays: Math.floor((updatedAtMs + windowMs - now) / DAY_MS),
+        });
+    }
+    out.sort((a, b) => b.updatedAtMs - a.updatedAtMs);
+    return out;
+}
+export function formatMemoryFiles(scope, files, archived = false) {
+    const title = `📚 ${scope} ${archived ? '已归档记忆' : '正式记忆'}（${files.length}）`;
+    if (files.length === 0)
+        return `${title}\n（暂无）`;
+    const lines = [title];
+    for (const f of files) {
+        const tags = f.tags.length ? ` [${f.tags.join(',')}]` : '';
+        const review = archived ? '' : f.reviewInDays < 0 ? '  ⏳待审查' : `  ${f.reviewInDays}天后审查`;
+        lines.push(`- ${f.slug}${tags}${f.signed ? '' : '  ⚠️未签名'}${review}`);
+        if (f.description)
+            lines.push(`  ${f.description}`);
+        lines.push(`  更新于 ${fmtDate(f.updatedAtMs)}`);
+    }
+    return lines.join('\n');
+}
+/** MEMORY.md 原文。 */
+export function readMemoryIndex(target, scope) {
+    const dirs = scopeDirs(target, scope);
+    const indexPath = path.join(dirs.memoryDir, 'MEMORY.md');
+    if (!fs.existsSync(indexPath))
+        return `📑 ${scope} 索引\n（尚未生成，可用 /memory reindex ${scope} 重建）`;
+    return `📑 ${scope} 索引（MEMORY.md）\n${fs.readFileSync(indexPath, 'utf-8').trimEnd()}`;
+}
+/** 单条正式记忆正文 + 验签结果。 */
+export async function showMemoryFile(target, scope, slug, archived = false) {
+    assertSlug(slug);
+    const dirs = scopeDirs(target, scope);
+    const dir = archived ? path.join(dirs.memoryDir, 'archive', 'consolidated') : dirs.consolidatedDir;
+    const fp = path.join(dir, `${slug}.md`);
+    if (!fs.existsSync(fp))
+        throw new Error(`找不到记忆: ${scope}/${archived ? 'archive/' : ''}${slug}`);
+    const content = fs.readFileSync(fp, 'utf-8');
+    let verify;
+    try {
+        const r = await verifyMemoryFile(content, target.selfAid);
+        verify = r.status === 'verified' ? '✅ 签名有效' : r.status === 'unsigned' ? '⚠️ 未签名' : `❌ 签名无效（${r.reason ?? 'unknown'}）`;
+    }
+    catch (e) {
+        verify = `⚠️ 无法验签（${e?.message || String(e)}）`;
+    }
+    let body = stripSignature(content);
+    if (body.length > MAX_SHOW_CHARS)
+        body = `${body.slice(0, MAX_SHOW_CHARS)}\n…（已截断）`;
+    return `📄 ${scope}/${archived ? 'archive/' : ''}${slug}  ${verify}\n${body}`;
+}
+/** 当前关系的 pending note 列表。 */
+export async function formatPendingNotes(target) {
+    const { notes } = await listMemoryNotes({ taskCtx: ctxOf(target), memoryConfig: target.memoryConfig });
+    if (notes.length === 0)
+        return '📝 待整理 note（0）\n（暂无）';
+    const lines = [`📝 待整理 note（${notes.length}）`];
+    for (const n of notes) {
+        const tags = n.tags.length ? ` [${n.tags.join(',')}]` : '';
+        lines.push(`- ${n.slug}${tags}  ${n.updatedAt ? fmtDate(Date.parse(n.updatedAt)) : ''}`);
+        if (n.firstLine)
+            lines.push(`  ${n.firstLine}`);
+    }
+    return lines.join('\n');
+}
+/** 单条 pending note 原文。 */
+export function showPendingNote(target, slug) {
+    assertSlug(slug);
+    const fp = path.join(scopeDirs(target, 'relation').memoryDir, 'pending', `${slug}.md`);
+    if (!fs.existsSync(fp))
+        throw new Error(`找不到 note: ${slug}`);
+    let body = fs.readFileSync(fp, 'utf-8').trimEnd();
+    if (body.length > MAX_SHOW_CHARS)
+        body = `${body.slice(0, MAX_SHOW_CHARS)}\n…（已截断）`;
+    return `📝 note/${slug}\n${body}`;
+}
+// ── 维护 ────────────────────────────────────────────────────────────────────
+/** 重建某作用域的 MEMORY.md 并刷新 _meta.json。 */
+export async function reindexScope(target, scope) {
+    const dirs = scopeDirs(target, scope);
+    const r = await rebuildIndex(dirs.consolidatedDir, path.join(dirs.memoryDir, 'MEMORY.md'), scope, path.join(dirs.memoryDir, 'archive', 'invalid'), undefined, // 与 ipc 一致：验签门控尚未开启
+    target.memoryConfig?.indexMaxBytes ?? DEFAULT_INDEX_MAX_BYTES);
+    refreshMemoryMeta(dirs.memoryDir);
+    return { indexed: r.indexed };
+}
+/** 撤销一条 pending note（移入 pending/archive/）。 */
+export async function dropNote(target, slug) {
+    assertSlug(slug);
+    const r = await dropMemoryNote({ taskCtx: ctxOf(target), target: slug, memoryConfig: target.memoryConfig });
+    return r.filePath;
+}
+/** 归档一条正式记忆并重建索引。 */
+export async function archiveMemoryFile(target, scope, slug) {
+    assertSlug(slug);
+    await archiveMemory({ taskCtx: ctxOf(target), scope, ownerAid: target.ownerAid, targets: [slug] });
+    await reindexScope(target, scope);
+}
+/** 把已归档记忆恢复回 consolidated/ 并重建索引。同名已存在时拒绝，不覆盖。 */
+export async function restoreMemoryFile(target, scope, slug) {
+    assertSlug(slug);
+    const dirs = scopeDirs(target, scope);
+    const src = path.join(dirs.memoryDir, 'archive', 'consolidated', `${slug}.md`);
+    const dest = path.join(dirs.consolidatedDir, `${slug}.md`);
+    if (!fs.existsSync(src))
+        throw new Error(`找不到已归档记忆: ${scope}/${slug}`);
+    if (fs.existsSync(dest))
+        throw new Error(`正式记忆中已存在同名文件: ${scope}/${slug}，未恢复`);
+    fs.mkdirSync(dirs.consolidatedDir, { recursive: true });
+    fs.renameSync(src, dest);
+    await reindexScope(target, scope);
+}