mocode-ai 0.4.9 → 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/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, isProjectSkillEnabled, updateProjectSkillConfig, 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,7 +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 as buildProjectSnapshot } from '../project-snapshot/index.js';
+import { buildSnapshot, clearSnapshotCache } from '../project-snapshot/index.js';
 /**
  * readline 的 prompt 必须是纯文本(无 ANSI):readline 按字符数算光标位置,
  * 颜色码会让光标错位、编辑时漂移。颜色只用在直接 stdout.write 的横幅 / 工具行 / 回复。
@@ -43,6 +43,7 @@ const SLASH_COMMANDS = [
     { 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 项目记忆(需先开启记忆)' },
@@ -51,7 +52,7 @@ const SLASH_COMMANDS = [
     { name: '/model switch', desc: '↑↓·Enter 在已配置预设间切换' },
     { name: '/model list', desc: '列出已经配置的模型' },
     { name: '/model delete <name>', desc: '删除已配置的模型' },
-    { name: '/refresh_snapshot', desc: '刷新项目快照(重新扫描静态文件,更新缓存)' },
+    { name: '/snapshot_refresh', desc: '刷新项目快照(重新扫描静态文件,重新生成 LLM 摘要)' },
     { name: '/plan', desc: '切到 plan 模式(只读探查+产出计划)' },
     { name: '/auto', desc: '切回 auto 模式(全工具执行)' },
     { name: '/pet', desc: '开关桌宠(独立悬浮窗,展示 agent 状态动画)' },
@@ -178,7 +179,7 @@ function runningStateFor(cmd) {
             return { status: '回滚', placeholder: '选择轮次…' };
         case '/init':
             return { status: '初始化', placeholder: '生成 MOCODE.md…' };
-        case '/refresh_snapshot':
+        case '/snapshot_refresh':
             return { status: '刷新快照', placeholder: '扫描项目文件中…' };
         case '/plan':
             return { status: '切 plan', placeholder: '…' };
@@ -198,6 +199,8 @@ function runningStateFor(cmd) {
             return { status: '查记忆状态', placeholder: '…' };
         case '/project_skill':
             return { status: '项目 Skill', placeholder: '处理中…' };
+        case '/snapshot':
+            return { status: '切快照开关', placeholder: '切换中…' };
         default:
             // 输入框留空(运行中可 typeahead 打字,dim 回显);运行状态由内联 spinner 承载(思考中/执行…),
             // 状态行只显走时——故常态 status 留空,不塞「处理」这种与内联重复的泛标签。
@@ -525,8 +528,10 @@ export function renderHistory(history) {
                     break;
                 }
             }
-            if (target)
+            if (target) {
                 target.resultSummary = preview;
+                target.fullOutput = output;
+            }
             // 不直接写屏——等 flushBatch 时出单行摘要
             continue;
         }
@@ -545,13 +550,11 @@ 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 设定后立即构建/加载（同步，小文件几十 ms）。
-    // 构建失败不阻断 REPL：snapshot 内部 catch 所有异常，此处再兜一层。
+    // 项目快照：sandboxRoot 设定后异步构建（完全由 LLM 生成）。
+    // 构建失败不阻断 REPL：snapshot 内部 catch 所有异常。
     if (config.projectSnapshotEnabled) {
-        try {
-            buildProjectSnapshot();
-        }
-        catch { /* ignore */ }
+        // 异步触发 LLM 快照生成（不阻塞 REPL 启动）
+        buildSnapshot().catch(() => { });
     }
     // 构造系统提示:auto 用 base;plan 在 base 后追加按当前开关现拼的 plan suffix。
     // 切模式时 applyMode 重算 history[0](history[0] 恒 system,compaction 保它,不破坏)。
@@ -1150,24 +1153,33 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null,
             }
             continue;
         }
-        if (line === '/refresh_snapshot') {
+        if (line === '/snapshot_refresh') {
             if (!config.projectSnapshotEnabled) {
                 layout.contentWrite(`${ui.dim}(项目快照功能已关闭,MOCODE_PROJECT_SNAPSHOT=false)${ui.reset}\n`);
                 continue;
             }
-            // buildProjectSnapshot 是同步操作(扫顶层小文件,几十 ms),不需要 spinner
+            // buildSnapshot 是异步操作(完全由 LLM 生成)，显示进度提示
+            layout.contentWrite(`${ui.dim}正在重新生成项目快照 (LLM 分析中)...${ui.reset}\n`);
             try {
-                const snap = buildProjectSnapshot();
-                const fileCount = Object.keys(snap.files).length;
-                const moduleCount = snap.structure.modules.length;
-                const configCount = snap.structure.configFiles.length;
-                layout.contentWrite(`${ui.cyan}✓ 项目快照已刷新${ui.reset}: ${fileCount} 个静态文件 · ${moduleCount} 个模块 · ${configCount} 个配置文件\n`);
-                layout.contentWrite(`${ui.dim}文件: ${Object.keys(snap.files).join(', ')}${ui.reset}\n`);
-                layout.contentWrite(`${ui.dim}模块: ${snap.structure.modules.join(', ')}${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`);
+                // 清除缓存，强制重新生成
+                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);
@@ -1823,6 +1835,102 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null,
             }
             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/tools/builtins/project-skill-update.js

@@ -1,4 +1,4 @@
-import { readProjectSkill, writeProjectSkill, appendProjectSkill, } from '../../project-skill/index.js';
+import { readProjectSkill, writeProjectSkillWithCompression, appendProjectSkillWithCompression, } from '../../project-skill/index.js';
 /**
  * 项目专属 Skill 更新工具。
  * 支持三种操作:
@@ -18,7 +18,33 @@ export const projectSkillUpdateTool = {
         'Use this to record architectural patterns, naming conventions, common pitfalls, ' +
         'and key decisions specific to this project. The skill persists across sessions and ' +
         'is injected into the system prompt when MOCODE_PROJECT_SKILL=true. ' +
-        'Actions: "read" (view current content), "write" (replace all), "append" (add to end).',
+        'Actions: "read" (view current content), "write" (replace all), "append" (add to end). ' +
+        '\n\n' +
+        '## Skill 维护指南\n' +
+        'Skill 专注 Snapshot 无法自动提供的洞察知识（why/how/gotchas）。Snapshot 已提供文件结构和静态文件内容——Skill 不要重复这些信息。\n' +
+        '\n' +
+        '**Skill 该写什么（Snapshot 不能替代的）**：\n' +
+        '- 设计决策的 why（为什么这样设计、取舍是什么）\n' +
+        '- 模块行为和职责描述（怎么工作、数据流、调用链）\n' +
+        '- 常见坑点和解决方案（踩过的坑、非直觉行为、边界条件）\n' +
+        '- 项目约定（命名规范、代码风格、测试策略）\n' +
+        '- 开发流程（构建/测试/部署命令及注意事项）\n' +
+        '- 关键 API 的使用限制和特殊行为\n' +
+        '\n' +
+        '**Skill 不该写什么（交给 Snapshot）**：\n' +
+        '- 文件列表和目录结构（Snapshot 自动扫描 src 树）\n' +
+        '- 静态文件内容摘要（依赖、编译器选项等 → package.json / tsconfig.json）\n' +
+        '\n' +
+        '**何时更新**：发现新架构模式、踩坑后总结、学到新约定、完成重要重构、用户纠正理解时。\n' +
+        '\n' +
+        '**注意事项**：\n' +
+        '- 保持精简，硬上限 4000 字符（约 1000 token）\n' +
+        '- 写可操作的内容，避免空泛描述\n' +
+        '- 用具体路径和例子（不要写"有多个模块"，要写"src/agent 负责 agent 循环"）\n' +
+        '- 定期整理，删除过时信息\n' +
+        '- 更新前建议先 `read` 看一下现有内容，避免重复\n' +
+        '\n' +
+        '**自动压缩**：内容超限时会自动调用 LLM 压缩（最多 3 次），无需手动精简。',
     risk: 'safe',
     parameters: {
         type: 'object',
@@ -35,9 +61,10 @@ export const projectSkillUpdateTool = {
         },
         required: ['action'],
     },
-    execute: async (args) => {
+    execute: async (args, ctx) => {
         const action = String(args.action ?? '').trim();
         const content = String(args.content ?? '');
+        const signal = ctx?.signal;
         switch (action) {
             case 'read': {
                 const current = readProjectSkill();
@@ -50,21 +77,25 @@ export const projectSkillUpdateTool = {
                 if (!content.trim()) {
                     return 'Error: "write" action requires non-empty content parameter.';
                 }
-                const result = writeProjectSkill(content);
+                const result = await writeProjectSkillWithCompression(content, 3, signal);
                 if (!result.ok) {
                     return `Error: ${result.error}`;
                 }
-                return 'Project skill updated successfully (full replacement).';
+                return result.compressed
+                    ? 'Project skill updated successfully (full replacement, auto-compressed to fit limit).'
+                    : 'Project skill updated successfully (full replacement).';
             }
             case 'append': {
                 if (!content.trim()) {
                     return 'Error: "append" action requires non-empty content parameter.';
                 }
-                const result = appendProjectSkill(content);
+                const result = await appendProjectSkillWithCompression(content, 3, signal);
                 if (!result.ok) {
                     return `Error: ${result.error}`;
                 }
-                return 'Project skill updated successfully (appended).';
+                return result.compressed
+                    ? 'Project skill updated successfully (appended, auto-compressed to fit limit).'
+                    : 'Project skill updated successfully (appended).';
             }
             default:
                 return `Error: Unknown action "${action}". Use "read", "write", or "append".`;

package/dist/tools/builtins/read-file.js

@@ -1,8 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { MAX_FILE_LINES } from '../constants.js';
-import { lookupSnapshotFile } from '../../project-snapshot/index.js';
-import { config } from '../../config/index.js';
 /** 默认单次 read_file 拉取的行数。刻意压低,逼 LLM 分块读大文件,
  * 配合 description 中的 PAGINATION IS MANDATORY 引导。
  * 300 行 ≈ 一个屏幕的源码量,够定位一段逻辑而不至于吃光上下文。 */
@@ -31,21 +29,7 @@ export const readFileTool = {
         const offset = Number(args.offset ?? 1);
         // 无论 LLM 传多大,单次硬钳到 MAX_FILE_LINES,杜绝「绕过分页引导一把全拿」。
         const limit = Math.min(Number(args.limit ?? DEFAULT_READ_LIMIT), MAX_FILE_LINES);
-        // 项目快照 cache hit：mtime 校验通过则直接返回，省磁盘读
-        let data;
-        if (config.projectSnapshotEnabled) {
-            const absPath = resolve(path);
-            const cached = lookupSnapshotFile(absPath);
-            if (cached) {
-                data = cached.content;
-            }
-            else {
-                data = await readFile(absPath, 'utf8');
-            }
-        }
-        else {
-            data = await readFile(resolve(path), 'utf8');
-        }
+        const data = await readFile(resolve(path), 'utf8');
         const lines = data.split(/\r?\n/);
         const start = Math.max(0, offset - 1);
         const end = Math.min(lines.length, start + limit);

package/dist/tools/builtins/todolist.js

@@ -20,18 +20,38 @@ export const todolistTool = {
     name: 'todolist',
     description: [
         'Maintain a working "notepad" plan in .mocode/plans/<id>.md (file-based, survives context compression).',
-        'For complex multi-step tasks (≥3 file changes or ≥5 tool calls expected, OR user says "先计划再执行" / "plan then do"), CALL THIS FIRST to write the plan, then update each step as you go.',
-        'For simple single-step tasks, skip it and just execute.',
+        '',
+        '## PREREQUISITES (before create)',
+        'Research first: explore codebase (read-only tools) → clarify with user (ask_human) → have concrete steps.',
+        'Do NOT create prematurely — if you haven\'t done research and confirmation, stop and do that first.',
+        '',
+        '## WHEN TO USE / NOT USE',
+        'ONLY for genuinely complex tasks: ≥3 file changes, ≥5 tool calls across phases, multi-phase features,',
+        'or user explicitly requests ("先计划再执行" / "plan then do").',
+        'Skip for: single-file edits, bug fixes, quick lookups, ≤3 focused tool calls. If in doubt, just execute.',
+        '',
+        '## STEP GRANULARITY (4-5 steps max)',
+        'Each step = one meaningful execution unit (a phase, not a single tool call).',
+        'GOOD: "调研现有架构 → 设计新接口 → 实现核心逻辑 → 编写测试 → 集成验证"',
+        'BAD: "打开文件A → 修改函数X → 保存文件A → 运行测试" (too fine-grained, just do it)',
+        '',
+        '## UPDATE WORKFLOW',
+        'Update in real-time after completing each step (one step = one update, or batch_update for 2-3 at once).',
+        'Do NOT batch all updates at the end — update as you go so the chip reflects real progress.',
+        'All steps done/skipped → plan auto-finishes, archives, and chip disappears.',
+        '',
+        '## LIFECYCLE',
         'Single plan per session: create refuses if an in-progress plan already exists — finish or abandon it first.',
-        'Lifecycle: finish AUTO-ARCHIVES the plan to .mocode/plans/archive/ (history preserved, active dir stays clean). To revisit, call list with scope=archived or unarchive. Use delete to permanently remove a plan (any location).',
-    ].join(''),
+        'finish(plan_status="finished") auto-archives to .mocode/plans/archive/; use plan_status="abandoned" to abandon.',
+        'To revisit: list with scope=archived, or unarchive to bring back to active. delete permanently removes.',
+    ].join('\n'),
     parameters: {
         type: 'object',
         properties: {
             action: {
                 type: 'string',
-                enum: ['create', 'read', 'update', 'add_step', 'finish', 'list', 'delete', 'unarchive'],
-                description: 'create=新计划;read=读当前活跃;update=改步骤状态;add_step=追加步骤;finish=收尾(自动归档);list=列计划;delete=永久删除;unarchive=从归档还原到活跃',
+                enum: ['create', 'read', 'update', 'batch_update', 'add_step', 'finish', 'list', 'delete', 'unarchive'],
+                description: 'create=新计划;read=读当前活跃;update=改步骤状态;batch_update=批量改多个步骤状态;add_step=追加步骤;finish=收尾(自动归档);list=列计划;delete=永久删除;unarchive=从归档还原到活跃',
             },
             title: { type: 'string', description: 'create 必填:计划标题' },
             goal: { type: 'string', description: 'create 可选:目标描述(写进「目标」段)' },
@@ -49,9 +69,21 @@ export const todolistTool = {
                 enum: ['pending', 'in_progress', 'done', 'skipped', 'failed'],
                 description: 'update 必填:目标状态',
             },
+            updates: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        step_id: { type: 'number', description: '步骤编号' },
+                        status: { type: 'string', enum: ['pending', 'in_progress', 'done', 'skipped', 'failed'], description: '目标状态' },
+                    },
+                    required: ['step_id', 'status'],
+                },
+                description: 'batch_update 必填:批量更新数组,每项含 step_id 和 status',
+            },
             note: {
                 type: 'string',
-                description: 'update / finish 可选:追加到进度日志的一行说明(可空)',
+                description: 'update / batch_update / finish 可选:追加到进度日志的一行说明(可空)',
             },
             plan_status: {
                 type: 'string',
@@ -77,13 +109,14 @@ export const todolistTool = {
                 case 'create': return doCreate(args);
                 case 'read': return doRead();
                 case 'update': return doUpdate(args);
+                case 'batch_update': return doBatchUpdate(args);
                 case 'add_step': return doAddStep(args);
                 case 'finish': return doFinish(args);
                 case 'list': return doList(args);
                 case 'delete': return doDelete(args);
                 case 'unarchive': return doUnarchive(args);
                 default:
-                    return `错误:未知 action「${action}」,合法值:create / read / update / add_step / finish / list / delete / unarchive。`;
+                    return `错误:未知 action「${action}」,合法值:create / read / update / batch_update / add_step / finish / list / delete / unarchive。`;
             }
         }
         catch (e) {
@@ -175,9 +208,92 @@ function doUpdate(args) {
     if (!updated.steps.some((s) => s.id === stepId)) {
         return `错误:找不到 step_id=${stepId}(plan 共 ${updated.steps.length} 步)。`;
     }
+    // 自动完成:所有步骤都 done/skipped 时自动 finish + 归档 + 清 chip(LLM 常漏调 finish)
+    const allDone = updated.steps.length > 0
+        && updated.steps.every((s) => s.status === 'done' || s.status === 'skipped');
+    if (allDone && updated.status === 'in_progress') {
+        updated.status = 'finished';
+        updated.log.push({ at: localIsoTimestamp(), text: '自动完成:所有步骤已完成' });
+        if (!writePlan(updated)) {
+            setActivePlan(updated);
+            return renderSuccess('update', updated) + '\n⚠ 自动 finish 写盘失败';
+        }
+        const archived = archivePlan(updated.id);
+        clearActivePlan();
+        const archivedNote = archived
+            ? '(已自动归档到 plans/archive/)'
+            : '(⚠ 归档失败,plan 仍留在 plans/)';
+        return renderSuccess('update', updated) + `\n✓ 自动完成:所有步骤已完成 ${archivedNote}`;
+    }
     setActivePlan(updated);
     return renderSuccess('update', updated);
 }
+function doBatchUpdate(args) {
+    const cur = getActivePlan();
+    if (!cur)
+        return '错误:无活跃 plan 可 batch_update。先 create。';
+    const updates = args.updates;
+    if (!Array.isArray(updates) || updates.length === 0) {
+        return '错误:batch_update 必填 updates(非空数组,每项含 step_id 和 status)。';
+    }
+    // 验证所有更新项
+    for (const u of updates) {
+        const sid = Number(u.step_id);
+        const st = String(u.status ?? '');
+        if (!Number.isFinite(sid) || sid < 1) {
+            return `错误:updates 中某项 step_id 非法「${u.step_id}」,需 >=1 整数。`;
+        }
+        if (!VALID_STATUS.has(st)) {
+            return `错误:updates 中某项 status 非法「${st}」,合法:pending / in_progress / done / skipped / failed。`;
+        }
+    }
+    const note = String(args.note ?? '').trim();
+    const updated = updatePlan(cur.id, (p) => {
+        for (const u of updates) {
+            const sid = Number(u.step_id);
+            const st = String(u.status);
+            const step = p.steps.find((s) => s.id === sid);
+            if (step) {
+                step.status = st;
+                p.log.push({ at: new Date().toISOString(), text: `step ${sid} → ${st}` });
+            }
+        }
+        if (note)
+            p.log.push({ at: new Date().toISOString(), text: note });
+        return p;
+    });
+    if (!updated)
+        return '错误:batch_update 写盘失败。';
+    // 检查所有 step_id 是否存在
+    const missingIds = [];
+    for (const u of updates) {
+        const sid = Number(u.step_id);
+        if (!updated.steps.some((s) => s.id === sid))
+            missingIds.push(sid);
+    }
+    if (missingIds.length > 0) {
+        return `错误:batch_update 找不到 step_id=${missingIds.join(', ')}(plan 共 ${updated.steps.length} 步)。`;
+    }
+    // 自动完成:所有步骤都 done/skipped 时自动 finish + 归档 + 清 chip(LLM 常漏调 finish)
+    const allDone = updated.steps.length > 0
+        && updated.steps.every((s) => s.status === 'done' || s.status === 'skipped');
+    if (allDone && updated.status === 'in_progress') {
+        updated.status = 'finished';
+        updated.log.push({ at: localIsoTimestamp(), text: '自动完成:所有步骤已完成' });
+        if (!writePlan(updated)) {
+            setActivePlan(updated);
+            return renderSuccess('batch_update', updated) + '\n⚠ 自动 finish 写盘失败';
+        }
+        const archived = archivePlan(updated.id);
+        clearActivePlan();
+        const archivedNote = archived
+            ? '(已自动归档到 plans/archive/)'
+            : '(⚠ 归档失败,plan 仍留在 plans/)';
+        return renderSuccess('batch_update', updated) + `\n✓ 自动完成:所有步骤已完成 ${archivedNote}`;
+    }
+    setActivePlan(updated);
+    return renderSuccess('batch_update', updated);
+}
 function doAddStep(args) {
     const cur = getActivePlan();
     if (!cur)