mocode-ai 0.4.8 → 0.4.10

package/dist/project-snapshot/llm-snapshot.js

@@ -0,0 +1,127 @@
+import { spawnAgent } from '../agent/spawn.js';
+/**
+ * 子 agent 系统提示：让 agent 自主探索项目并生成 markdown 快照
+ */
+const SNAPSHOT_LLM_SUFFIX = `You are a project analysis agent. Your task is to explore this project and generate a concise markdown snapshot for an AI coding assistant.
+
+## Your Mission
+Explore the project using available tools (read_file, glob, grep) and generate a structured markdown snapshot that captures:
+- WHAT exists (project description, tech stack, commands, modules, directory structure)
+- WHERE it is (paths, locations)
+
+Do NOT explain WHY or HOW (that's Project Skill's job).
+
+## Exploration Strategy
+1. Read package.json, README.md, tsconfig.json (or equivalent for other languages)
+2. List top-level directories to identify modules
+3. Scan src/ directory structure (depth ≤3, directories only)
+4. Extract key commands from package.json scripts
+5. Identify tech stack from dependencies
+
+## Output Format
+Output a markdown document between these exact delimiters:
+
+\`\`\`snapshot-md
+# Project Snapshot
+
+## Description
+(一句话描述项目，≤80字，中文)
+
+## Tech Stack
+(关键技术栈，逗号分隔，含版本，≤15项)
+
+## Commands
+| Command | Description |
+|---------|-------------|
+| \`npm run build\` | 构建项目 |
+| \`npm test\` | 运行测试 |
+| ... | ... |
+
+## Modules
+- **module-name** — 一句话职责描述（≤20字）
+- **module-name** — 一句话职责描述
+- ...
+
+## Source Tree
+\`\`\`
+src/
+  agent/
+  tools/
+  ui/
+\`\`\`
+\`\`\`snapshot-md
+
+## Rules
+1. **Description**: ≤80字，中文，从 README 和 package.json description 提炼。不要"一个..."开头。
+2. **Tech Stack**: ≤15项，逗号分隔，含版本。格式如 "TypeScript 5.x, Node.js ≥18, openai@^4"。
+3. **Commands**: 5-8个最重要的命令，从 package.json scripts 提取。Description ≤15字。用表格格式。
+4. **Modules**: 每个顶层模块目录一条。职责≤20字，只写 WHAT（做什么）。
+5. **Source Tree**: 只列目录（不列文件），深度≤3，用缩进表示层级，放在代码块中。
+6. 不要包含：设计决策、注意事项、坑点、约定 → 这些是 Skill 的职责。
+7. 总 markdown ≤ 2500 字符。
+8. 使用中文。
+`;
+/**
+ * 生成 LLM 快照（markdown 格式）
+ * @param root 项目根目录
+ * @param signal AbortSignal
+ */
+export async function generateLLMSnapshot(root, signal) {
+    const prompt = `请探索项目 ${root}，生成项目快照（markdown 格式）。
+
+## 探索步骤
+1. 读取 package.json（或等效配置文件）
+2. 读取 README.md
+3. 列出顶层目录，识别模块
+4. 扫描 src/ 目录结构（深度≤3，只列目录）
+5. 从 package.json scripts 提取关键命令
+6. 从 dependencies 识别技术栈
+
+## 输出
+严格按照系统提示的 markdown 格式输出，不要添加额外解释。`;
+    try {
+        const result = await spawnAgent({
+            prompt,
+            systemPromptSuffix: SNAPSHOT_LLM_SUFFIX,
+            tools: ['read_file', 'glob', 'grep'], // 允许探索工具
+            maxSteps: 15, // 给足够的探索步数
+            signal,
+        });
+        if (!result.completed) {
+            return {
+                ok: false,
+                error: '子 agent 未完成（可能中断或超时）',
+                transcript: result.transcript,
+            };
+        }
+        if (!result.summary) {
+            return {
+                ok: false,
+                error: '子 agent 未返回内容',
+                transcript: result.transcript,
+            };
+        }
+        // 从 summary 中提取 markdown
+        const mdMatch = result.summary.match(/```snapshot-md\n([\s\S]*?)\n```snapshot-md/);
+        if (!mdMatch || !mdMatch[1]) {
+            // fallback: 尝试普通 markdown 代码块
+            const fallbackMatch = result.summary.match(/```markdown\n([\s\S]*?)\n```/);
+            if (!fallbackMatch || !fallbackMatch[1]) {
+                return {
+                    ok: false,
+                    error: '无法从子 agent 输出中提取 markdown',
+                    transcript: result.transcript,
+                };
+            }
+            return { ok: true, content: fallbackMatch[1].trim(), transcript: result.transcript };
+        }
+        return { ok: true, content: mdMatch[1].trim(), transcript: result.transcript };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            error: e instanceof Error ? e.message : '未知错误',
+            transcript: '',
+        };
+    }
+}

package/dist/project-snapshot/static-files.js

@@ -0,0 +1,87 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * 静态项目文件白名单 + 扫描逻辑。
+ * 这些文件通常是项目元信息，变动频率低、体积小、跨 session 稳定。
+ */
+/** 静态文件白名单（文件名或模式） */
+const STATIC_FILE_PATTERNS = [
+    // 文档
+    /^README(\.[a-z]+)?(\.[a-z]+)?$/i, // README, README.md, README.zh-CN.md
+    'CHANGELOG.md',
+    'CONTRIBUTING.md',
+    'LICENSE',
+    'LICENSE.md',
+    'LICENSE.txt',
+    // Node.js
+    'package.json',
+    'tsconfig.json',
+    'jsconfig.json',
+    // Python
+    'pyproject.toml',
+    'setup.py',
+    'setup.cfg',
+    'requirements.txt',
+    'Pipfile',
+    // Go
+    'go.mod',
+    // Rust
+    'Cargo.toml',
+    // 环境变量模板
+    '.env.example',
+    '.env.template',
+];
+/**
+ * 判断文件名是否匹配白名单
+ */
+function matchesPattern(filename) {
+    for (const p of STATIC_FILE_PATTERNS) {
+        if (typeof p === 'string') {
+            if (filename === p)
+                return true;
+        }
+        else {
+            if (p.test(filename))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * 扫描项目根目录，收集匹配白名单的静态文件。
+ * 只扫顶层（不递归），避免 node_modules 等大目录。
+ * @param root 项目根目录（绝对路径）
+ * @returns key = 相对路径（正斜杠），val = { mtime, content }
+ */
+export function scanStaticFiles(root) {
+    const result = {};
+    let items;
+    try {
+        items = readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return result;
+    }
+    for (const item of items) {
+        if (!item.isFile())
+            continue;
+        if (!matchesPattern(item.name))
+            continue;
+        const absPath = path.join(root, item.name);
+        try {
+            const stat = statSync(absPath);
+            // 体积限制：单文件 > 64KB 跳过（避免 README 巨长拖慢快照）
+            if (stat.size > 64 * 1024)
+                continue;
+            const content = readFileSync(absPath, 'utf8');
+            result[item.name] = {
+                mtime: stat.mtimeMs,
+                content,
+            };
+        }
+        catch {
+            // 读取失败：跳过
+        }
+    }
+    return result;
+}

package/dist/repl/index.d.ts

@@ -0,0 +1,22 @@
+import { type ChatMessage } from '../llm/index.js';
+/**
+ * 把会话历史渲染成静态文本进内容区(回滚 / 续接 / --resume 后复显上下文,仿 Claude Code):
+ * user→❯ 回显、assistant→正文(+ tool_calls 折叠成 ● 摘要行)、tool→↳ 结果预览;system 跳过。
+ * 思考段不持久(history 只存正文),故无思考折叠。渲染后续写位在末尾,紧接 enterInputMode 画输入框。
+ * 内容长于屏时 viewport 显尾(最近轮次),PgUp 可看更早——与流式态一致。
+ * user 多模态:用 textOf 取 text parts;若侧 channel messageAttachments 有原文件名则追加 chip 行
+ * (避免 base64 解码不可逆,旧 session 没侧 channel 时只显文本,文件名 fallback 到 image/* mime)。
+ *
+ * 折叠策略:遇到 assistant + tool_calls 不立即打 ● 行,而是累积到 batchEntries;
+ * 跟随的连续 tool 消息按 tool_call_id 反查填 resultSummary;遇下一个非 tool 消息(或末尾)时,
+ * 用 batch.writeSummaryOnly 出单行摘要(与实时 runAgent 同一渲染器,UI 一致)。
+ * 回放默认全折叠;用户可鼠标点击摘要行展开(由 BatchRenderer 接管,见 ui/batch.ts)。
+ */
+export declare function renderHistory(history: ChatMessage[]): void;
+/**
+ * 交互式 REPL:全屏 TUI(alt screen + 固定底栏)。INPUT 态底栏=状态行+输入框(raw mode 等按键);
+ * 提交后 enterRunningMode(底栏改 dim 占位、光标回内容续写位),命令分发与 runAgent 的流式输出经
+ * contentWrite 落入内容区(滚动区域内自动滚动,底栏不动)。history 由本模块持有,在轮次间持久;
+ * agent 只读取并追加(+ 经 session/ 压缩)。每轮成功结束后自动落盘,退出后可用 --resume / /resume 续接。
+ */
+export declare function startRepl(initialHistory?: ChatMessage[], sessionId?: string, updateNotice?: string | null, sandboxRootOverride?: string): Promise<void>;

package/dist/repl/index.js

@@ -1,7 +1,7 @@
 import readline from 'node:readline/promises';
 import { emitKeypressEvents } from 'node:readline';
 import { stdin, stdout } from 'node:process';
-import { config, updateModelConfig, isModelConfigured, updateMemoryConfig, isMemoryEnabled, buildBasePrompt, getPlanModeSuffix, } from '../config/index.js';
+import { config, updateModelConfig, isModelConfigured, updateMemoryConfig, isMemoryEnabled, isProjectSkillEnabled, isProjectSnapshotEnabled, updateProjectSkillConfig, updateSnapshotConfig, buildBasePrompt, getPlanModeSuffix, } from '../config/index.js';
 import { updateConfigKey, writeConfigKeys, CONFIG_PATH } from '../config/file.js';
 import { deletePreset, getPreset, isValidPresetName, listPresets, migrateCurrentToPreset, savePreset, } from '../config/presets.js';
 import { runAgent } from '../agent/index.js';
@@ -24,6 +24,7 @@ import { listTurns, planRollback, applyRollback, persistSnapshots, loadSnapshots
 import { listSkills, effectiveSystemPrompt, } from '../skills/index.js';
 import { buildMemorySection, buildMemoryIndexSection, kickoffReflection, drainMemoryBackground, getLastReflectResult, clearLastReflectResult, snapshotTranscript, formatReflectResult, loadAll, } from '../memory/index.js';
 import { buildActivePlanSection, onActivePlanChange, hasActivePlan, getActivePlanSummary, } from '../plan/index.js';
+import { buildSnapshot, clearSnapshotCache } from '../project-snapshot/index.js';
 /**
  * readline 的 prompt 必须是纯文本(无 ANSI):readline 按字符数算光标位置,
  * 颜色码会让光标错位、编辑时漂移。颜色只用在直接 stdout.write 的横幅 / 工具行 / 回复。
@@ -41,6 +42,8 @@ const SLASH_COMMANDS = [
     { name: '/rollback', desc: '菜单选轮次回滚(↑↓·Enter)' },
     { name: '/memory', desc: '记忆库:条目计数与近期索引(关闭时提示先开 /memory_switch)' },
     { name: '/memory_switch', desc: '切换记忆子系统开关(无参=切换;/on 或 /off 显式;持久化 MEMORY_ENABLED)' },
+    { name: '/project_skill', desc: '项目专属 Skill 开关 + 查看/初始化(无参=切换;/on·/off·/view·/init)' },
+    { name: '/snapshot', desc: '切换项目快照开关(无参=切换;/on·/off·/status;持久化 MOCODE_PROJECT_SNAPSHOT)' },
     { name: '/memory_status', desc: '查看记忆子系统当前开关与原理' },
     { name: '/reflect', desc: '手动触发后台记忆反思 pass(需先开启记忆)' },
     { name: '/init', desc: '扫描项目生成 MOCODE.md 项目记忆(需先开启记忆)' },
@@ -49,6 +52,7 @@ const SLASH_COMMANDS = [
     { name: '/model switch', desc: '↑↓·Enter 在已配置预设间切换' },
     { name: '/model list', desc: '列出已经配置的模型' },
     { name: '/model delete <name>', desc: '删除已配置的模型' },
+    { name: '/snapshot_refresh', desc: '刷新项目快照(重新扫描静态文件,重新生成 LLM 摘要)' },
     { name: '/plan', desc: '切到 plan 模式(只读探查+产出计划)' },
     { name: '/auto', desc: '切回 auto 模式(全工具执行)' },
     { name: '/pet', desc: '开关桌宠(独立悬浮窗,展示 agent 状态动画)' },
@@ -175,6 +179,8 @@ function runningStateFor(cmd) {
             return { status: '回滚', placeholder: '选择轮次…' };
         case '/init':
             return { status: '初始化', placeholder: '生成 MOCODE.md…' };
+        case '/snapshot_refresh':
+            return { status: '刷新快照', placeholder: '扫描项目文件中…' };
         case '/plan':
             return { status: '切 plan', placeholder: '…' };
         case '/auto':
@@ -191,6 +197,10 @@ function runningStateFor(cmd) {
             return { status: '切记忆开关', placeholder: '切换中…' };
         case '/memory_status':
             return { status: '查记忆状态', placeholder: '…' };
+        case '/project_skill':
+            return { status: '项目 Skill', placeholder: '处理中…' };
+        case '/snapshot':
+            return { status: '切快照开关', placeholder: '切换中…' };
         default:
             // 输入框留空(运行中可 typeahead 打字,dim 回显);运行状态由内联 spinner 承载(思考中/执行…),
             // 状态行只显走时——故常态 status 留空,不塞「处理」这种与内联重复的泛标签。
@@ -518,8 +528,10 @@ export function renderHistory(history) {
                     break;
                 }
             }
-            if (target)
+            if (target) {
                 target.resultSummary = preview;
+                target.fullOutput = output;
+            }
             // 不直接写屏——等 flushBatch 时出单行摘要
             continue;
         }
@@ -538,6 +550,12 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null,
     // 沙箱根:文件操作边界。优先级 --sandbox-root > SANDBOX_ROOT env > process.cwd()。
     // 纯边界记录(不 chdir),jail.ts 内部 resolve。子 agent 同进程继承全局 root。
     setSandboxRoot(sandboxRootOverride ?? config.sandboxRoot ?? process.cwd());
+    // 项目快照：sandboxRoot 设定后异步构建（完全由 LLM 生成）。
+    // 构建失败不阻断 REPL：snapshot 内部 catch 所有异常。
+    if (config.projectSnapshotEnabled) {
+        // 异步触发 LLM 快照生成（不阻塞 REPL 启动）
+        buildSnapshot().catch(() => { });
+    }
     // 构造系统提示:auto 用 base;plan 在 base 后追加按当前开关现拼的 plan suffix。
     // 切模式时 applyMode 重算 history[0](history[0] 恒 system,compaction 保它,不破坏)。
     // 活跃 plan 摘要拼在 memory 段后(systemPrompt 的尾段),todo 工具变更后 listener 重写 history[0]。
@@ -1135,6 +1153,40 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null,
             }
             continue;
         }
+        if (line === '/snapshot_refresh') {
+            if (!config.projectSnapshotEnabled) {
+                layout.contentWrite(`${ui.dim}(项目快照功能已关闭,MOCODE_PROJECT_SNAPSHOT=false)${ui.reset}\n`);
+                continue;
+            }
+            // buildSnapshot 是异步操作(完全由 LLM 生成)，显示进度提示
+            layout.contentWrite(`${ui.dim}正在重新生成项目快照 (LLM 分析中)...${ui.reset}\n`);
+            try {
+                // 清除缓存，强制重新生成
+                clearSnapshotCache();
+                const result = await buildSnapshot(undefined, true);
+                if (result.snapshot) {
+                    layout.contentWrite(`${ui.cyan}✓ 项目快照已刷新${ui.reset} (${result.snapshot.builtAt})\n`);
+                    layout.contentWrite(`${ui.dim}已生成 markdown 快照，注入到系统提示词中${ui.reset}\n`);
+                    // 刷新 history[0]：buildSnapshotSection 内部 loadSnapshot() 会拿到新快照，
+                    // buildSystemMessage 重新拼 system prompt，快照段落就更新了。
+                    history[0] = { role: 'system', content: buildSystemMessage(getAgentMode() === 'plan') };
+                    layout.contentWrite(`${ui.dim}(system prompt 已同步刷新)${ui.reset}\n`);
+                }
+                else {
+                    layout.contentWrite(`${ui.red}✗ 快照生成失败${ui.reset}: ${result.error || '未知错误'}\n`);
+                    if (result.transcript) {
+                        layout.contentWrite(`${ui.dim}--- 子 agent 日志 ---${ui.reset}\n`);
+                        layout.contentWrite(`${ui.dim}${result.transcript}${ui.reset}\n`);
+                        layout.contentWrite(`${ui.dim}--- 日志结束 ---${ui.reset}\n`);
+                    }
+                }
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                layout.contentWrite(`${ui.red}[错误]${ui.reset} 刷新快照失败: ${msg}\n`);
+            }
+            continue;
+        }
         if (line === '/sessions') {
             // /sessions:浏览全部已保存会话(慢路径,readdir+全量 JSON.parse,目录 N 大时会有可感知卡顿)。
             // 默认走 /resume(仅最近 10 条,瞬开);要翻历史续接更早的会话才用这条。
@@ -1665,6 +1717,220 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null,
             }
             continue;
         }
+        if (line === '/project_skill' ||
+            line.startsWith('/project_skill ')) {
+            // /project_skill — 项目专属 Skill 总开关 + 查看/编辑。
+            // 用法:
+            //   /project_skill              切换 on/off
+            //   /project_skill on|off       显式开关
+            //   /project_skill view         查看当前内容
+            //   /project_skill edit         打开编辑器修改
+            try {
+                const arg = line.startsWith('/project_skill ')
+                    ? line.slice('/project_skill '.length).trim().toLowerCase()
+                    : '';
+                // /project_skill view — 查看当前内容
+                if (arg === 'view') {
+                    const enabled = isProjectSkillEnabled();
+                    layout.contentWrite(`${ui.cyan}项目专属 Skill:${ui.reset} ${enabled ? `${ui.green}开启` : `${ui.yellow}关闭`}${ui.reset}\n`);
+                    if (enabled) {
+                        const { readProjectSkill } = await import('../project-skill/index.js');
+                        const content = readProjectSkill();
+                        if (content) {
+                            layout.contentWrite(`${ui.dim}--- 内容 ---${ui.reset}\n${content}\n${ui.dim}--- 结束 ---${ui.reset}\n`);
+                        }
+                        else {
+                            layout.contentWrite(`${ui.dim}(尚未创建,可用 /project_skill init 生成初始内容)${ui.reset}\n`);
+                        }
+                    }
+                    else {
+                        layout.contentWrite(`${ui.dim}(功能已关闭,用 /project_skill on 开启)${ui.reset}\n`);
+                    }
+                    continue;
+                }
+                // /project_skill init — 扫描项目并生成/优化 skill
+                if (arg === 'init') {
+                    if (!isProjectSkillEnabled()) {
+                        layout.contentWrite(`${ui.yellow}⚠ 项目专属 Skill 尚未开启${ui.reset}，请先运行 ${ui.cyan}/project_skill on${ui.reset}\n`);
+                        continue;
+                    }
+                    const { readProjectSkill, writeProjectSkill } = await import('../project-skill/index.js');
+                    const existing = readProjectSkill();
+                    if (existing) {
+                        layout.contentWrite(`${ui.cyan}⏳ 正在深度探索项目并优化现有 skill...${ui.reset}\n`);
+                    }
+                    else {
+                        layout.contentWrite(`${ui.cyan}⏳ 正在深度探索项目（子 agent 将使用工具扫描代码、架构、配置等）...${ui.reset}\n`);
+                    }
+                    layout.contentWrite(`${ui.dim}提示: 按 Ctrl+C 可中断${ui.reset}\n\n`);
+                    // 派生子 agent 深度探索项目
+                    const { generateInitialSkill } = await import('../project-skill/initializer.js');
+                    const result = await generateInitialSkill(existing ?? undefined, currentAbort?.signal);
+                    // 显示探索过程日志
+                    if (result.transcript) {
+                        layout.contentWrite(`${ui.dim}--- 探索过程 ---${ui.reset}\n`);
+                        layout.contentWrite(result.transcript);
+                        layout.contentWrite(`${ui.dim}--- 探索结束 ---${ui.reset}\n\n`);
+                    }
+                    if (result.ok && result.content) {
+                        const writeResult = writeProjectSkill(result.content);
+                        if (writeResult.ok) {
+                            layout.contentWrite(`${ui.green}✓ 项目 Skill 已生成${ui.reset}\n`);
+                            layout.contentWrite(`${ui.dim}内容预览:${ui.reset}\n${result.content.slice(0, 500)}${result.content.length > 500 ? '...' : ''}\n`);
+                            layout.contentWrite(`\n${ui.dim}文件: ${ui.cyan}.mocode/project-skill.md${ui.reset} (${result.content.length} 字符)\n`);
+                            layout.contentWrite(`${ui.dim}下次启动时会自动注入到系统提示词。Agent 也会在开发过程中持续更新。${ui.reset}\n`);
+                            layout.contentWrite(`${ui.dim}提示: 可用 ${ui.cyan}/project_skill view${ui.reset} 查看完整内容，或手动编辑文件完善。${ui.dim}${ui.reset}\n`);
+                        }
+                        else {
+                            layout.contentWrite(`${ui.red}✗ 写入失败:${ui.reset} ${writeResult.error}\n`);
+                        }
+                    }
+                    else {
+                        layout.contentWrite(`${ui.red}✗ 探索失败:${ui.reset} ${result.error}\n`);
+                        if (result.transcript) {
+                            layout.contentWrite(`${ui.dim}子 agent 输出了部分内容（见上方），但未能生成完整的 skill 文档。${ui.reset}\n`);
+                        }
+                    }
+                    continue;
+                }
+                // 开关切换
+                let nextEnabled;
+                if (arg === '') {
+                    nextEnabled = !isProjectSkillEnabled();
+                }
+                else if (['on', 'true', '1', 'yes', 'y', 'enable', 'enabled'].includes(arg)) {
+                    nextEnabled = true;
+                }
+                else if (['off', 'false', '0', 'no', 'n', 'disable', 'disabled'].includes(arg)) {
+                    nextEnabled = false;
+                }
+                else {
+                    layout.contentWrite(`${ui.yellow}/project_skill 用法:${ui.reset}\n` +
+                        `  /project_skill             切换(开↔关)\n` +
+                        `  /project_skill on|off      显式设值\n` +
+                        `  /project_skill view        查看当前内容\n` +
+                        `  /project_skill init        扫描项目生成/优化 skill（可重复运行）\n`);
+                    continue;
+                }
+                const prev = isProjectSkillEnabled();
+                if (nextEnabled === prev) {
+                    layout.contentWrite(`${ui.dim}(已是 ${nextEnabled ? '开启' : '关闭'},未变更 — 持久化字段未写入)${ui.reset}\n`);
+                    continue;
+                }
+                updateProjectSkillConfig(nextEnabled);
+                updateConfigKey('MOCODE_PROJECT_SKILL', nextEnabled ? 'true' : 'false');
+                const note = nextEnabled
+                    ? `${ui.green}已开启项目专属 Skill${ui.reset} — project_skill_update 工具进入工具表;` +
+                        `项目 Skill 内容会在下次拼 system message 时注入。工具表快照需重启 REPL 才完整刷新。`
+                    : `${ui.yellow}已关闭项目专属 Skill${ui.reset} — project_skill_update 工具将在下次拼 system message 时从工具表过滤;` +
+                        `项目 Skill 内容不再注入。重启 REPL 后工具表完全不出现。`;
+                layout.contentWrite(`${note}\n`);
+                layout.contentWrite(`${ui.dim}(写入 ${CONFIG_PATH}:MOCODE_PROJECT_SKILL=${nextEnabled ? 'true' : 'false'};${ui.reset}` +
+                    (process.env.MOCODE_PROJECT_SKILL
+                        ? `${ui.dim}同 session shell 未 export,文件写入即时生效)${ui.reset}\n`
+                        : `${ui.dim}下次启动仍生效)${ui.reset}\n`));
+            }
+            catch (e) {
+                layout.contentWrite(`${ui.red}/project_skill 失败:${ui.reset} ${e.message}\n`);
+            }
+            continue;
+        }
+        if (line === '/snapshot' ||
+            line.startsWith('/snapshot ')) {
+            // /snapshot — 项目快照总开关。无参切换 on/off;/on 或 /off 显式;/status 只读。
+            //
+            // 设计原则(与 /project_skill / /memory_switch 对齐):
+            //  - 单一来源 config.projectSnapshotEnabled(被 buildSnapshotSection() 现拼 +
+            //    read_file 工具每次 execute 现读);改完下一轮 chat 的 system prompt 即时反映。
+            //  - 持久化字段 MOCODE_PROJECT_SNAPSHOT,默认值 true(默认开启,启动 lazy build)。
+            //  - 关闭时:system prompt 不注入快照段,read_file 不查 cache 直接走真实 readFile。
+            //  - 开启时:若还没有 snapshot.json,主动 buildProjectSnapshot() 一次(仿 startRepl
+            //    655-658 的 lazy build 模式),否则 buildSnapshotSection() 会因 loadSnapshot=null
+            //    返空串,用户感知不到自己刚打开的开关已经生效。
+            try {
+                const arg = line.startsWith('/snapshot ')
+                    ? line.slice('/snapshot '.length).trim().toLowerCase()
+                    : '';
+                // /snapshot status — 只读查询
+                if (arg === 'status') {
+                    const on = isProjectSnapshotEnabled();
+                    layout.contentWrite(`${ui.cyan}项目快照:${ui.reset} ${on ? `${ui.green}开启` : `${ui.yellow}关闭`}${ui.reset}\n`);
+                    layout.contentWrite(`${ui.dim}  单一来源 config.projectSnapshotEnabled(${on ? 'true' : 'false'});` +
+                        `持久化 ${ui.cyan}MOCODE_PROJECT_SNAPSHOT${ui.dim};` +
+                        `配置文件 ${CONFIG_PATH}${ui.reset}\n`);
+                    layout.contentWrite(`${ui.dim}  关闭时:buildBasePrompt() 不含「## Project Snapshot」段;` +
+                        `read_file 工具直接走真实 readFile,不走 snapshot cache。${ui.reset}\n`);
+                    layout.contentWrite(`${ui.dim}  切换后下次 chat 即时反映(本轮已发出的请求不会回滚)。${ui.reset}\n`);
+                    continue;
+                }
+                // /snapshot(无参=切换;有参=按值设)
+                let nextEnabled;
+                if (arg === '') {
+                    nextEnabled = !isProjectSnapshotEnabled();
+                }
+                else if (['on', 'true', '1', 'yes', 'y', 'enable', 'enabled'].includes(arg)) {
+                    nextEnabled = true;
+                }
+                else if (['off', 'false', '0', 'no', 'n', 'disable', 'disabled'].includes(arg)) {
+                    nextEnabled = false;
+                }
+                else {
+                    layout.contentWrite(`${ui.yellow}/snapshot 用法:${ui.reset}\n` +
+                        `  /snapshot                  切换(开↔关)\n` +
+                        `  /snapshot on|off           显式设值\n` +
+                        `  /snapshot status           查看当前状态\n`);
+                    continue;
+                }
+                const prev = isProjectSnapshotEnabled();
+                if (nextEnabled === prev) {
+                    layout.contentWrite(`${ui.dim}(已是 ${nextEnabled ? '开启' : '关闭'},未变更 — 持久化字段未写入)${ui.reset}\n`);
+                    continue;
+                }
+                updateSnapshotConfig(nextEnabled);
+                updateConfigKey('MOCODE_PROJECT_SNAPSHOT', nextEnabled ? 'true' : 'false');
+                // 开启时异步 build 一次,避免 buildSnapshotSection 因 loadSnapshot=null 返空串。
+                let built = false;
+                if (nextEnabled) {
+                    try {
+                        clearSnapshotCache();
+                        const result = await buildSnapshot();
+                        if (result.snapshot) {
+                            built = true;
+                        }
+                        else {
+                            layout.contentWrite(`${ui.yellow}⚠ 快照构建失败:${ui.reset} ${result.error || '未知错误'} ` +
+                                `${ui.dim}(开关已切换,系统提示词中的快照段将为空,稍后可用 /snapshot_refresh 重试)${ui.reset}\n`);
+                        }
+                    }
+                    catch (e) {
+                        layout.contentWrite(`${ui.yellow}⚠ 快照构建失败:${ui.reset} ${e.message} ` +
+                            `${ui.dim}(开关已切换,系统提示词中的快照段将为空,稍后可用 /snapshot_refresh 重试)${ui.reset}\n`);
+                    }
+                }
+                // 刷新 history[0] 使 system prompt 立即反映新值(仿 /snapshot_refresh)。
+                history[0] = { role: 'system', content: buildSystemMessage(getAgentMode() === 'plan') };
+                const note = nextEnabled
+                    ? `${ui.green}已开启项目快照${ui.reset} — ` +
+                        `system prompt 将在下次 chat 注入「## Project Snapshot」段;` +
+                        `read_file 工具优先走 snapshot cache(mtime 校验失败时回退真实 readFile)。`
+                    : `${ui.yellow}已关闭项目快照${ui.reset} — ` +
+                        `system prompt 不再注入「## Project Snapshot」段;` +
+                        `read_file 工具直接走真实 readFile,不再查 cache。`;
+                let extra = '';
+                if (nextEnabled && built) {
+                    extra = `${ui.dim}(已构建快照;如需刷新用 /snapshot_refresh)${ui.reset}\n`;
+                }
+                layout.contentWrite(`${note}\n${extra}`);
+                layout.contentWrite(`${ui.dim}(写入 ${CONFIG_PATH}:MOCODE_PROJECT_SNAPSHOT=${nextEnabled ? 'true' : 'false'};` +
+                    (process.env.MOCODE_PROJECT_SNAPSHOT
+                        ? `${ui.dim}同 session shell 已 export MOCODE_PROJECT_SNAPSHOT,文件写入下次启动仍以 shell 值为准;取消 shell 设置后生效)${ui.reset}\n`
+                        : `${ui.dim}下次启动仍生效)${ui.reset}\n`));
+            }
+            catch (e) {
+                layout.contentWrite(`${ui.red}/snapshot 失败:${ui.reset} ${e.message}\n`);
+            }
+            continue;
+        }
         const bubbleRows = input.length + 2 + pendingAttachments.length; // N 行 message + 2 行尾随空(含 \n\n 留下的 open current 行) + 每附件 1 行
         const shouldCommit = await awaitPendingRecall(input, pendingAttachments.length, placeholder);
         if (!shouldCommit) {

package/dist/rollback/index.d.ts

@@ -0,0 +1,79 @@
+import type { ChatMessage } from '../llm/index.js';
+/**
+ * 回滚子系统:`/rollback` 菜单(↑/↓)选轮次 → 选中第 X 轮 = 删该轮及之后 + 预填该轮 user 输入(仿 Claude Code
+ * rewind,Enter 重新跑);撤销被删轮次的文件改动(逐个「保留/撤销」询问)。
+ *
+ * 语义:选中下标 picked(0-based,= 第 picked+1 轮)→ `planRollback(picked)` 保 1..picked(删 picked+1 轮及之后),
+ * 预填 userTexts[picked](= 第 picked+1 轮 user 输入)。**不是**保 1..picked+1——选中第 X 轮即"从第 X 轮重跑"。
+ *
+ * 撤销方案 = 落盘快照(不用 git):write_file/edit_file 执行前由 executeTool 调
+ * recordMutation,把 before 内容存入快照(按轮次 turnId 打标)。回滚到第 n 轮时,
+ * 对每条选「撤销」的路径,恢复 turnId > cutoffTurnId 的最小 turnId 快照的 before
+ * (= 所选轮末状态;before===null = 当时不存在 → 删文件)。同文件多轮改动也能
+ * 精确回到所选轮边界,不误伤更早轮次。
+ *
+ * 快照 + 轮次日志随 saveSession 落盘到 <sessionDir>/<id>.snapshots.json,/resume 读回
+ * → 重启后仍可撤销。叶子模块:运行时只依赖 config(+ node:fs/path);ChatMessage
+ * 用 import type 擦除,不拉 llm 运行时;不反向依赖任何业务。
+ *
+ * v1 偏离 / 局限:
+ * - 撤销粒度 = 路径(非逐条 tool_call)——快照只能整路径回到轮末,无法只撤一条 edit。
+ * - run_command 不撤销(shell 可任意改文件,无法跟踪)。
+ * - 跨 /resume 后若文件被外部改过,恢复会用 before 覆盖(边缘情况,不处理)。
+ * - 快照文件随大文件多次改动膨胀;/clear 重置;日后可按「turn 已不可回滚」裁剪。
+ */
+export interface Turn {
+    turnId: number;
+    firstLine: string;
+}
+export interface Snapshot {
+    turnId: number;
+    path: string;
+    before: string | null;
+}
+export interface FileChange {
+    path: string;
+    ops: string[];
+    snapshotAvailable: boolean;
+}
+export interface RollbackPlan {
+    n: number;
+    cutoffIndex: number;
+    cutoffTurnId: number;
+    changes: FileChange[];
+}
+/** agent:runAgent 入口调——开新轮次。firstLine 已由调用方截断到 40。 */
+export declare function beginTurn(firstLine: string): void;
+/** tools/registry:write_file/edit_file 执行前调——记 before 快照(在 tool.execute 之前读)。 */
+export declare function recordMutation(p: string): void;
+/** 列出当前可回滚的轮次(1-based 序号由调用方显示)。 */
+export declare function listTurns(): Turn[];
+/**
+ * 规划回滚到第 n 轮(1-based):算截断点 + 被删轮次里涉及的文件改动(按 path 去重)。
+ * 调用方据 changes 逐 path 问保留 / 撤销;snapshotAvailable=false 的项无法撤销。
+ */
+export declare function planRollback(n: number, history: ChatMessage[]): RollbackPlan;
+/**
+ * 执行回滚:原地截断 history 到 cutoffIndex + 按选择恢复文件 + 裁剪 turns/snapshots。
+ * revertPaths 为选「撤销」的相对路径集合。返回删除消息数 + 撤销文件列表。
+ */
+export declare function applyRollback(plan: RollbackPlan, history: ChatMessage[], revertPaths: Set<string>): {
+    deletedMsgs: number;
+    revertedFiles: string[];
+};
+/** compact 摘要成功后调:按存活轮次数裁剪(M = 新 history 里 user 消息数)。 */
+export declare function pruneAfterCompaction(history: ChatMessage[]): void;
+/** /clear 调:清空全部状态。 */
+export declare function resetState(): void;
+/**
+ * 无 snapshots 文件时(/resume 旧会话)从 history 重建 turns(扫 user 消息,1..M,
+ * 无快照 → 那些轮次的文件改动不可撤销)。turnIdCounter = M,后续新轮次从 M+1 续。
+ */
+export declare function rebuildFromHistory(history: ChatMessage[]): void;
+/** 随 saveSession 调:把 turns + snapshots 落盘(turns 为空则跳过,不写空文件)。 */
+export declare function persistSnapshots(id: string): void;
+/**
+ * /resume / --resume 加载会话后调:读回 turns + snapshots。成功返 true(状态已覆盖);
+ * 失败 / 无文件返 false,调用方应改调 rebuildFromHistory(history) 兜底。
+ */
+export declare function loadSnapshots(id: string): boolean;

package/dist/sandbox/command.d.ts

@@ -0,0 +1,3 @@
+/** 返回 env 浅拷贝,删敏感键。 */
+export declare function filterEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function isCommandDenied(cmd: string): string | null;