mocode-ai 0.4.8 → 0.4.10

package/dist/plan/active.d.ts

@@ -0,0 +1,23 @@
+import type { Plan } from './store.js';
+export interface ActivePlanSnapshot {
+    id: string;
+    title: string;
+    status: Plan['status'];
+    done: number;
+    total: number;
+}
+type Listener = (snap: ActivePlanSnapshot | null) => void;
+/** 取当前活跃 plan(完整对象,工具用)。无 → null。 */
+export declare function getActivePlan(): Plan | null;
+/** 设活跃 plan。同一 id 重复设也走 listener(repl 借此刷 status 行——即使内容未变,显式刷新有助)。 */
+export declare function setActivePlan(plan: Plan | null): void;
+/** 清活跃 plan(plan finish/abandon 后由 repl/todolist 调)。 */
+export declare function clearActivePlan(): void;
+/** 注册活跃 plan 变更监听器。返注销函数(不常用,模式 listener 一次性常驻)。 */
+export declare function onActivePlanChange(cb: Listener): () => void;
+/** 是否有活跃 plan(in_progress 状态)。finished/abandoned 不算「活跃」。 */
+export declare function hasActivePlan(): boolean;
+/** 给 status 行用的极简摘要(避免调用方读 Plan 全字段)。无 → 空串。 */
+/** 状态行 chip 用的短摘要(无 ANSI 颜色,由 layout 上色)。maxWidth 默认 56,留 room 给右段。 */
+export declare function getActivePlanSummary(maxWidth?: number): string;
+export {};

package/dist/plan/index.d.ts

@@ -0,0 +1,13 @@
+export { type Plan, type PlanStep, type PlanStatus, type StepStatus, plansDir, archiveDir, planPath, ensurePlansDir, ensureArchiveDir, newPlanId, parsePlan, serializePlan, readPlan, writePlan, deletePlan, deletePlanAnywhere, updatePlan, listPlans, archivePlan, unarchivePlan, renderPlanForLLM, renderPlanChip, } from './store.js';
+export { type ActivePlanSnapshot, getActivePlan, setActivePlan, clearActivePlan, onActivePlanChange, hasActivePlan, getActivePlanSummary, } from './active.js';
+/**
+ * 拼给 systemPrompt 注入的活跃 plan 摘要段。
+ *  - 无活跃 plan → 空串(repl 直接跳过拼接,systemPrompt 长度不变)。
+ *  - 有 → 紧凑 markdown(目标 + 步骤 checkbox + 进度日志末 5 条),header + 内容。
+ *
+ * 触发:setActivePlan 后由 repl listener 调;也供 buildSystemMessage 直接同步取(repl 入口)。
+ * 上限:超 MAX_ACTIVE_PLAN_CHARS 截到尾部(罕见,plan 文件本身就小)。
+ */
+export declare function buildActivePlanSection(): string;
+/** 注入 systemPrompt 的活跃 plan 摘要上限(字符)。 */
+export declare const MAX_ACTIVE_PLAN_CHARS = 3000;

package/dist/plan/state.d.ts

@@ -0,0 +1,2 @@
+export type { ActivePlanSnapshot } from './active.js';
+export { getActivePlan, setActivePlan, clearActivePlan, onActivePlanChange, hasActivePlan, getActivePlanSummary, } from './active.js';

package/dist/plan/store.d.ts

@@ -0,0 +1,78 @@
+export type StepStatus = 'pending' | 'in_progress' | 'done' | 'skipped' | 'failed';
+export interface PlanStep {
+    /** 1-based 序号(在当前 plan 内稳定,即便中间 add_step 也不重用旧号——见 addStep)。 */
+    id: number;
+    title: string;
+    status: StepStatus;
+}
+export type PlanStatus = 'in_progress' | 'finished' | 'abandoned';
+export interface Plan {
+    id: string;
+    title: string;
+    status: PlanStatus;
+    created: string;
+    updated: string;
+    goal: string;
+    steps: PlanStep[];
+    /** 进度日志条目(时间戳 + 一行说明),append-only。 */
+    log: {
+        at: string;
+        text: string;
+    }[];
+}
+/** plans 目录:<sandboxRoot>/.mocode/plans/。无 sandboxRoot 退到 cwd(防御)。 */
+export declare function plansDir(): string;
+/** 归档目录:<root>/.mocode/plans/archive/。finish 自动归档、用户手动 unarchive 都走这里。 */
+export declare function archiveDir(): string;
+/** 单 plan 文件路径:<root>/.mocode/plans/<id>.md。可选 baseDir:默认 plans,也可指 archive。 */
+export declare function planPath(id: string, baseDir?: string): string;
+/** 确保 plans 目录存在(惰性,工具每次写前调)。 */
+export declare function ensurePlansDir(): void;
+/** 确保归档目录存在(惰性)。 */
+export declare function ensureArchiveDir(): void;
+/** 本地时间戳(无时区后缀),与 filename 的 YYYY-MM-DDTHH-mm-ss 风格一致。
+ *  例:2026-07-04T22:54:51.729(本地时,便于人对读 frontmatter / progress log,
+ *  且与同 plan id 文件名"2026-07-04T22-54-51"对应)。
+ *  不带 Z 后缀 → JS Date 解析会按本地时读(一致 round-trip);
+ *  反例:toISOString() 返 2026-07-04T14:54:51.729Z(UTC),跟用户当地差 8 小时,易误解。 */
+export declare function localIsoTimestamp(d?: Date): string;
+/** plan id:YYYY-MM-DDTHH-mm-ss-xxxxxx(本地时间,文件名安全)。xxxxxx = 4 字节随机 hex(防同秒并发撞)。 */
+export declare function newPlanId(now?: Date): string;
+/**
+ * 解析 plan 文件为 Plan 对象。失败(无 frontmatter / 段缺失 / 坏 checkbox)→ 退化:
+ *  - 无 frontmatter:把整文当 title 段
+ *  - 缺字段:空串 / 空数组
+ *  - 坏 checkbox:跳过该行,不污染好行
+ * 解析成功但 step id 缺序 / 重号:按出现顺序重排为 1..N(保稳定)。
+ */
+export declare function parsePlan(raw: string, fallbackId: string): Plan;
+/** 序列化为 markdown 文本。固定段序:frontmatter → 目标 → 步骤 → 进度日志。 */
+export declare function serializePlan(p: Plan): string;
+/** 读 plan 文件;不存在 → null,坏文件 → fallbackId 最小可用 Plan(不抛,工具契约)。
+ *  可选 baseDir:默认 plans,传 archiveDir() 可读归档。 */
+export declare function readPlan(id: string, baseDir?: string): Plan | null;
+/** 写 plan 文件(atomic:写 .tmp 再 rename)。返回是否成功。 */
+export declare function writePlan(p: Plan): boolean;
+/** 删 plan 文件;不存在静默 ok。可选 baseDir:默认 plans,传 archiveDir() 删归档。 */
+export declare function deletePlan(id: string, baseDir?: string): boolean;
+/**
+ * 原子读-改-写:读 → mutator 改 → 写。mutator 返回 false 视为"无改动",跳过写。
+ * mutator 抛错 → 写失败 → 返 null(不抛,工具契约)。
+ *
+ * mutator 同步:本 store 走同步 fs,mutator 必须同步(返 Promise 视为"无信号"——返原对象);
+ *  设计如此以避免把 fs API 改成 async(同步 fs 在 node 单 tick 原子,无需锁)。
+ */
+export declare function updatePlan(id: string, mutator: (p: Plan) => Plan | false): Plan | null;
+/** 列 plans 目录下所有 plan(按 updated 倒序,最新在前)。解析失败的跳过。
+ *  scope: 'active'(默认)=仅 plans/;'archived'=仅 archive/;'all'=合并(去重按 id)。 */
+export declare function listPlans(scope?: 'active' | 'archived' | 'all'): Plan[];
+/** 把 plans/<id>.md mv 到 plans/archive/<id>.md(atomic rename)。
+ *  源不存在 → false(已归档 / 删了 / 从未存在都算)。 */
+export declare function archivePlan(id: string): boolean;
+/** 把 plans/archive/<id>.md 还原到 plans/<id>.md。源不存在 → false。 */
+export declare function unarchivePlan(id: string): boolean;
+/** 任一处存在就都删(活跃 + 归档)。用于 todolist delete 不关心来源。 */
+export declare function deletePlanAnywhere(id: string): boolean;
+/** 把 Plan 渲成给 LLM 看的紧凑摘要(多行文本)。 */
+export declare function renderPlanForLLM(p: Plan): string;
+export declare function renderPlanChip(p: Plan | null, maxWidth?: number): string;

package/dist/project-skill/index.js

@@ -0,0 +1,180 @@
+/**
+ * 项目专属 Skill — 跨 session 持久化的项目开发知识。
+ *
+ * 每个项目可维护一个专属 skill 文件(.mocode/project-skill.md)，
+ * 记录开发约定、架构决策、常见坑点等。开关启用后:
+ *   1. 每次启动时内容注入系统提示词(buildProjectSkillSection)
+ *   2. Agent 可通过 project_skill_update 工具动态更新
+ *   3. 随着项目开发，skill 越来越了解项目，开发效率越来越高
+ *
+ * 存储位置: <cwd>/.mocode/project-skill.md
+ * 开关: MOCODE_PROJECT_SKILL 环境变量，默认 false(零侵入)
+ *
+ * 与现有功能的关系:
+ *   - 通用 skill(SKILLS_DIRS): 按需加载(use_skill);项目 skill: 始终注入
+ *   - memory: 碎片化 fact/decision; 项目 skill: 结构化知识总结
+ *   - snapshot: 静态文件缓存(只读); 项目 skill: 动态知识(可写)
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync } from 'node:fs';
+import path from 'node:path';
+/** 项目 skill 文件路径 */
+function skillPath() {
+    return path.join(process.cwd(), '.mocode', 'project-skill.md');
+}
+/** 备份文件路径 */
+function backupPath() {
+    return path.join(process.cwd(), '.mocode', 'project-skill.md.bak');
+}
+/** 读取项目 skill 内容。不存在/读失败 → null */
+export function readProjectSkill() {
+    const p = skillPath();
+    if (!existsSync(p))
+        return null;
+    try {
+        const content = readFileSync(p, 'utf8').trim();
+        return content || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 内容硬上限(字符数)。超限拒绝写入，防止系统提示词膨胀。从 6000 降至 4000，与快照互补后内容更精简。 */
+const MAX_SKILL_CHARS = 4000;
+/**
+ * 写入/更新项目 skill。先备份旧内容再写新内容。
+ * 返回 { ok, error? }: ok=false 时 error 说明原因(超限/IO 失败)。
+ */
+export function writeProjectSkill(content) {
+    const trimmed = content.trim();
+    if (trimmed.length > MAX_SKILL_CHARS) {
+        return {
+            ok: false,
+            error: `内容超过上限(${trimmed.length}/${MAX_SKILL_CHARS} 字符)。请精简后重试。`,
+        };
+    }
+    const p = skillPath();
+    const dir = path.dirname(p);
+    try {
+        // 备份旧内容(如果有)
+        if (existsSync(p)) {
+            copyFileSync(p, backupPath());
+        }
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(p, trimmed + '\n', 'utf8');
+        return { ok: true };
+    }
+    catch (e) {
+        return { ok: false, error: `写入失败: ${e.message}` };
+    }
+}
+/**
+ * 追加内容到项目 skill 末尾(以 \n\n 分隔)。
+ * 同样受 MAX_SKILL_CHARS 限制。
+ */
+export function appendProjectSkill(addition) {
+    const existing = readProjectSkill() ?? '';
+    const trimmed = addition.trim();
+    if (!trimmed)
+        return { ok: false, error: '追加内容为空' };
+    const separator = existing ? '\n\n' : '';
+    const merged = existing + separator + trimmed;
+    return writeProjectSkill(merged);
+}
+/**
+ * 调用 LLM 压缩内容。超限时自动精简，保留关键信息。
+ * 返回压缩后的内容，失败返回 null。
+ */
+export async function compressContent(content, signal) {
+    try {
+        // 动态导入避免循环依赖
+        const { chat } = await import('../llm/index.js');
+        const messages = [
+            {
+                role: 'system',
+                content: 'You are a technical writer. Compress the following project skill content to fit within ' +
+                    `${MAX_SKILL_CHARS} characters while preserving the most important information. ` +
+                    'Keep concrete examples, paths, and actionable insights. Remove redundancy and verbose explanations. ' +
+                    'Output ONLY the compressed content, no explanations.',
+            },
+            { role: 'user', content },
+        ];
+        const result = await chat(messages, {}, signal);
+        const compressed = result.content?.trim();
+        if (!compressed)
+            return null;
+        return compressed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 写入时自动压缩：超限则调用 LLM 压缩，最多尝试 maxAttempts 次。
+ * 返回 { ok, error?, compressed? }，compressed 标记是否经过压缩。
+ */
+export async function writeProjectSkillWithCompression(content, maxAttempts = 3, signal) {
+    let current = content;
+    let compressed = false;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        const result = writeProjectSkill(current);
+        if (result.ok) {
+            return { ok: true, compressed };
+        }
+        // 非超限错误直接返回
+        if (!result.error?.includes('内容超过上限')) {
+            return result;
+        }
+        // 超限时调用 LLM 压缩
+        const compressedContent = await compressContent(current, signal);
+        if (!compressedContent) {
+            return {
+                ok: false,
+                error: `压缩失败: ${result.error}`,
+            };
+        }
+        current = compressedContent;
+        compressed = true;
+    }
+    // 多次压缩后仍超限
+    const finalCheck = writeProjectSkill(current);
+    if (finalCheck.ok) {
+        return { ok: true, compressed: true };
+    }
+    return {
+        ok: false,
+        error: `经过 ${maxAttempts} 次压缩仍超限: ${finalCheck.error}`,
+    };
+}
+/**
+ * 追加时自动压缩：合并后超限则调用 LLM 压缩，最多尝试 maxAttempts 次。
+ */
+export async function appendProjectSkillWithCompression(addition, maxAttempts = 3, signal) {
+    const existing = readProjectSkill() ?? '';
+    const trimmed = addition.trim();
+    if (!trimmed)
+        return { ok: false, error: '追加内容为空' };
+    const separator = existing ? '\n\n' : '';
+    const merged = existing + separator + trimmed;
+    return writeProjectSkillWithCompression(merged, maxAttempts, signal);
+}
+/**
+ * 生成系统提示词注入段。
+ * 开关关闭或文件不存在 → 空串(零行为变化)。
+ *
+ * 精简版：只注入 skill 内容本身，维护指南移到 project_skill_update 工具描述中。
+ */
+export function buildProjectSkillSection() {
+    const content = readProjectSkill();
+    if (!content)
+        return '';
+    return [
+        '',
+        '',
+        '## Project Skill (project-specific knowledge)',
+        'The following is project-specific knowledge maintained across sessions. Use it as context for all tasks in this project.',
+        '',
+        '<project-skill>',
+        content,
+        '</project-skill>',
+    ].join('\n');
+}

package/dist/project-skill/initializer.js

@@ -0,0 +1,178 @@
+/**
+ * 项目 Skill 初始化器 - 派生子 agent 带工具深度探索项目，生成高质量的初始 skill
+ */
+import { spawnAgent } from '../agent/spawn.js';
+/**
+ * 子 agent 的系统提示后缀：角色与输出格式约束
+ */
+const SKILL_INIT_SUFFIX = `You are a project exploration agent. Your task is to deeply understand this project and generate a concise "Project Skill" document.
+
+## ⚠️ Complementary to Snapshot — CRITICAL
+The following information is ALREADY provided by Project Snapshot — **do NOT repeat**:
+- ✗ Project one-liner description (快照已有)
+- ✗ Module names and file locations (快照 srcTree 已有)
+- ✗ Tech stack names and versions (快照 techStack 已有)
+- ✗ Build/test commands (快照 keyCommands 已有)
+- ✗ File lists and directory structure (快照 srcTree 已有)
+
+**Your job is to capture INSIGHTS only:**
+- **WHY** — design decisions, trade-offs, reasons for choosing X over Y
+- **HOW** — module behaviors, data flows, call chains, non-obvious interactions
+- **GOTCHAS** — pitfalls, edge cases, non-intuitive behaviors
+- **CONVENTIONS** — naming patterns, code style, unwritten rules
+
+## Exploration Strategy
+1. Use \`codegraph\` to trace call chains and understand module interactions
+2. Read core modules to understand **behaviors** (not just names)
+3. Look for complex logic, error handling patterns, unusual configs
+4. Identify naming conventions, common abstractions
+
+## Output Format
+Output the skill document between these exact delimiters:
+
+\`\`\`skill-start
+## 架构要点
+### 核心模块及职责
+- **\`path/to/module\`** — 行为描述（做什么 + 怎么做）
+...
+
+### 关键设计决策
+- 决策：原因
+...
+
+## 项目约定
+- 约定（具体的，有例子的）
+...
+
+## 开发流程
+- 命令 + 注意事项/坑点（命令本身快照已有，这里只写注意什么）
+...
+
+## 常见坑点
+- 坑：解法
+...
+\`\`\`skill-end
+
+## Rules — MUST FOLLOW
+1. 禁止列出文件名清单或目录结构
+2. 禁止列出依赖名和版本
+3. 禁止写项目概述/一句话描述
+4. 禁止只写命令本身（快照已有），只写注意事项
+5. 每个模块描述必须包含行为（做什么 + 怎么协作），不只是名称
+6. **总长度目标 3000-4000 字符，硬上限 4000**
+7. 写可操作的内容，用具体路径和例子
+8. 如果某个 section 没有实质内容，省略它
+`;
+/**
+ * 生成初始项目 Skill（使用子 agent 深度探索）
+ * @param existingSkill 已有的 skill 内容（如果有，子 agent 会在其基础上优化）
+ * @param signal AbortSignal
+ */
+export async function generateInitialSkill(existingSkill, signal) {
+    const hasExisting = !!existingSkill;
+    let prompt;
+    if (hasExisting) {
+        prompt = `以下是当前的项目 Skill 内容，请深度探索项目并优化/完善它：
+
+\`\`\`markdown
+${existingSkill}
+\`\`\`
+
+## 优化方向
+1. 补充缺失的信息（架构要点、设计决策、调用链等）
+2. 修正过时或不准确的内容
+3. 让描述更具体（用实际路径和例子）
+4. 删除冗余或空泛的描述
+5. 如果发现新的坑点或约定，添加进去
+
+记住：保持精简，总长度控制在 4000-5000 字符。输出完整的优化后版本。`;
+    }
+    else {
+        prompt = `请深度探索当前项目，生成一份项目专属 Skill 文档。
+
+## 探索步骤
+1. 先用 glob 扫描项目结构（**/*.ts, **/*.json 等）
+2. 读取 package.json、README.md、tsconfig.json 等关键文件
+3. 用 codegraph 或 grep 找到主入口、核心模块、关键接口
+4. 理解架构模式、数据流向、调用关系
+5. 识别命名约定、代码风格、测试策略
+6. 找出可能的坑点（复杂配置、特殊依赖、构建陷阱）
+
+## 输出
+探索完成后，将完整的 skill 文档输出在 \`\`\`skill-start 和 \`\`\`skill-end 之间。
+
+记住：内容要精简、可操作、有具体路径和例子。总长度控制在 4000-5000 字符。`;
+    }
+    try {
+        const result = await spawnAgent({
+            prompt,
+            systemPromptSuffix: SKILL_INIT_SUFFIX,
+            tools: ['read_file', 'glob', 'grep', 'codegraph'],
+            maxSteps: 30,
+            signal,
+        });
+        if (!result.completed) {
+            return {
+                ok: false,
+                error: '子 agent 未完成（可能中断或超时）',
+                transcript: result.transcript,
+            };
+        }
+        if (!result.summary) {
+            return {
+                ok: false,
+                error: '子 agent 未返回内容',
+                transcript: result.transcript,
+            };
+        }
+        // 从 summary 中提取 skill 内容
+        const skillMatch = result.summary.match(/```skill-start\n([\s\S]*?)\n```skill-end/);
+        if (!skillMatch || !skillMatch[1]) {
+            // 如果没有找到 delimiters，尝试从最后一段 markdown 代码块提取
+            const codeBlockMatch = result.summary.match(/```(?:markdown|md)?\n([\s\S]*?)\n```/);
+            if (codeBlockMatch && codeBlockMatch[1]) {
+                return {
+                    ok: true,
+                    content: codeBlockMatch[1].trim(),
+                    transcript: result.transcript,
+                };
+            }
+            // 如果连代码块都没有，直接用 summary（但去掉开头的探索日志）
+            const lines = result.summary.split('\n');
+            const skillStartIdx = lines.findIndex((l) => l.startsWith('## '));
+            if (skillStartIdx > 0) {
+                return {
+                    ok: true,
+                    content: lines.slice(skillStartIdx).join('\n').trim(),
+                    transcript: result.transcript,
+                };
+            }
+            return {
+                ok: false,
+                error: '无法从子 agent 输出中提取 skill 内容',
+                transcript: result.transcript,
+            };
+        }
+        const content = skillMatch[1].trim();
+        // 检查长度
+        if (content.length > 6000) {
+            return {
+                ok: false,
+                error: `生成内容过长 (${content.length} 字符)，请手动精简后重试`,
+                transcript: result.transcript,
+            };
+        }
+        return {
+            ok: true,
+            content,
+            transcript: result.transcript,
+        };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            error: e instanceof Error ? e.message : '未知错误',
+            transcript: '',
+        };
+    }
+}

package/dist/project-snapshot/index.js

@@ -0,0 +1,85 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { getSandboxRoot } from '../sandbox/root.js';
+/** 内存缓存：当前 session 的快照（避免重复 IO） */
+let currentSnapshot = null;
+/** 计算 sandboxRoot 的 hash，用作目录名（避免路径特殊字符） */
+export function hashRoot(root) {
+    return createHash('sha256').update(root).digest('hex').slice(0, 16);
+}
+/** 快照存储目录 */
+function snapshotDir() {
+    const root = getSandboxRoot() ?? process.cwd();
+    return path.join(process.cwd(), '.mocode', 'projects', hashRoot(root));
+}
+/** 快照文件路径 */
+function snapshotPath() {
+    return path.join(snapshotDir(), 'snapshot.md');
+}
+/** 从磁盘加载快照（不存在/损坏返 null） */
+export function loadSnapshot() {
+    if (currentSnapshot)
+        return currentSnapshot;
+    const p = snapshotPath();
+    if (!existsSync(p))
+        return null;
+    try {
+        const content = readFileSync(p, 'utf8');
+        // 从 markdown 文件头部的 YAML front matter 提取元数据
+        const match = content.match(/^---\nroot: (.+)\nbuiltAt: (.+)\nversion: (\d+)\n---\n\n([\s\S]+)$/);
+        if (!match)
+            return null;
+        const snap = {
+            version: parseInt(match[3]),
+            root: match[1],
+            builtAt: match[2],
+            content: match[4],
+        };
+        currentSnapshot = snap;
+        return snap;
+    }
+    catch {
+        return null;
+    }
+}
+/** 获取当前快照（内存缓存优先，然后磁盘） */
+export function getSnapshot() {
+    return currentSnapshot ?? loadSnapshot();
+}
+export async function buildSnapshot(signal, force = false) {
+    // 检查缓存：已有快照且不强制刷新，直接返回
+    if (!force) {
+        const cached = getSnapshot();
+        if (cached)
+            return { snapshot: cached };
+    }
+    const root = getSandboxRoot() ?? process.cwd();
+    // 动态导入避免循环依赖
+    const { generateLLMSnapshot } = await import('./llm-snapshot.js');
+    const result = await generateLLMSnapshot(root, signal);
+    if (!result.ok || !result.content) {
+        return {
+            snapshot: null,
+            error: result.error || 'LLM 未返回有效结果',
+            transcript: result.transcript,
+        };
+    }
+    const snap = {
+        version: 1,
+        root,
+        builtAt: new Date().toISOString(),
+        content: result.content,
+    };
+    // 落盘为 markdown 格式，带 YAML front matter
+    const dir = snapshotDir();
+    mkdirSync(dir, { recursive: true });
+    const mdContent = `---\nroot: ${snap.root}\nbuiltAt: ${snap.builtAt}\nversion: ${snap.version}\n---\n\n${snap.content}`;
+    writeFileSync(snapshotPath(), mdContent, 'utf8');
+    currentSnapshot = snap;
+    return { snapshot: snap };
+}
+/** 清除内存缓存（强制下次重新加载） */
+export function clearSnapshotCache() {
+    currentSnapshot = null;
+}