mocode-ai 0.4.1 → 0.4.3

package/dist/agent/core.js

@@ -7,7 +7,7 @@
 import { readFileSync } from 'node:fs';
 import { chat, planChatTools, } from '../llm/index.js';
 import { executeTool } from '../tools/registry.js';
-import { PLAN_DISABLED_TOOLS } from '../tools/constants.js';
+import { getPlanDisabledTools } from '../tools/constants.js';
 import { getAgentMode, setAgentMode } from './mode.js';
 import { maybeCompact, contextState, dropContextFromHistory } from '../session/index.js';
 import { createBudgetScheduler } from '../session/scheduler.js';
@@ -25,6 +25,24 @@ function parseArgs(raw) {
         return null;
     }
 }
+/**
+ * Thrashing 检测:同一工具 + 完全相同 arguments 在本轮重复 ≥ THRASH_THRESHOLD 次,
+ * 返一段提示(注入到工具结果尾部),引导模型换思路而不是再试一次。
+ * 阈值 3 = "试过两次同样的调用还没好,该停了"。指纹 = `${name}\\x00${args}`
+ * (直接拼,不哈希——避免热路径开销;args 长度本身有限,内存压力可忽略)。
+ * null 表示未触发,不污染输出。
+ */
+const THRASH_THRESHOLD = 3;
+function thrashHint(name, args, count) {
+    if (count < THRASH_THRESHOLD)
+        return null;
+    return (`\n\n[hint] This is call #${count} of \`${name}\` with identical arguments — ` +
+        'either failing or returning the same content. STOP retrying and switch strategy:\n' +
+        '- read_file / glob → path likely wrong; call `glob` to discover paths, or `ask_human`\n' +
+        '- run_command → Windows path-escaping issue; use `read_file` / `glob` with absolute paths instead\n' +
+        '- edit_file → old_string mismatch; re-read the file to find the exact text\n' +
+        '- otherwise → re-read the tool description; the argument shape may be wrong');
+}
 /** 只读工具集:一轮多个时,连续的只读工具成组 Promise.all 并行(无副作用、互不依赖)。 */
 const READ_TOOL_NAMES = new Set([
     'read_file',
@@ -125,6 +143,31 @@ export async function runAgentCore(opts) {
     // 本轮计时:从入口到完毕(正常 return / 达上限),供 finally 打 ✻ Worked for 摘要行。
     const t0 = Date.now();
     let done = false; // 正常完毕 / 达上限 true;中断 false(不显摘要)
+    // 本轮 token 累计:每步 chat() 返回后把 result.usage 累加,供 onDone 摘要行 + AgentRunResult.usage
+    // 透传给 repl(显示在底栏模式 chip 右边)。未开启 include_usage 或全失败时为 undefined。
+    let turnUsage;
+    const addUsage = (u) => {
+        if (!u)
+            return;
+        turnUsage = turnUsage
+            ? {
+                promptTokens: turnUsage.promptTokens + u.promptTokens,
+                completionTokens: turnUsage.completionTokens + u.completionTokens,
+                totalTokens: turnUsage.totalTokens + u.totalTokens,
+                cachedTokens: turnUsage.cachedTokens + u.cachedTokens,
+                reasoningTokens: turnUsage.reasoningTokens + u.reasoningTokens,
+            }
+            : u;
+    };
+    // Thrashing 检测:本轮内同 (name, args) 累计次数。≥3 在工具结果尾部追加 hint(见 thrashHint)。
+    // 只在 runAgentCore 内,turn 结束自然 GC;不跨 turn 持久(下一轮重新计数,避免误把历史判为 thrashing)。
+    const recentToolCalls = new Map();
+    const recordAndHint = (name, args) => {
+        const fp = `${name}\x00${args}`;
+        const c = (recentToolCalls.get(fp) ?? 0) + 1;
+        recentToolCalls.set(fp, c);
+        return thrashHint(name, args, c);
+    };
     history.push({ role: 'user', content: userInput });
     // drop_context 工具的上下文剔除回调:闭包捕获 history,原地剔除无关旧 tool 结果。
     // 保护由 dropContextFromHistory 内部保证:history[0](system)+ 当前轮(最后 user 及其后)永不剔除。
@@ -210,6 +253,7 @@ export async function runAgentCore(opts) {
                 throw e;
             }
             contextState.lastUsage = result.usage; // 供 /context 与状态行显示实测 token
+            addUsage(result.usage); // 本轮累计:onDone 摘要行 + AgentRunResult.usage 透传
             hooks.onChatDone?.(); // 主 agent:spinner.stop()
             // lastUsage 已更新:触发状态行 context 用量条重算+重画,运行中不再冻结在轮首。
             onContextUpdate?.();
@@ -252,7 +296,9 @@ export async function runAgentCore(opts) {
                             const output = await started[k];
                             hooks.onToolDone?.();
                             hooks.onToolResult?.(tc, output, null, null, 1); // 只读工具无 diff
-                            pushToolResult(history, tc, output, relprune, lifecycle, scheduler);
+                            // Thrashing:history 里附 hint(UI 已用干净 output 渲染,避免屏幕噪声)
+                            const hint = recordAndHint(tc.name, tc.arguments);
+                            pushToolResult(history, tc, hint ? `${output}${hint}` : output, relprune, lifecycle, scheduler);
                         }
                         i = j;
                     }
@@ -272,7 +318,9 @@ export async function runAgentCore(opts) {
                             hooks.onToolHeader?.(tc);
                             const err = `错误:计划模式下禁用工具 ${tc.name}(仅读探查,不改动文件 / 不跑命令)`;
                             hooks.onToolResult?.(tc, err, null, null, 1);
-                            pushToolResult(history, tc, err, relprune, lifecycle, scheduler);
+                            // Thrashing:同上
+                            const hint = recordAndHint(tc.name, tc.arguments);
+                            pushToolResult(history, tc, hint ? `${err}${hint}` : err, relprune, lifecycle, scheduler);
                             i++;
                             continue;
                         }
@@ -291,7 +339,9 @@ export async function runAgentCore(opts) {
                             const tc = batch[k];
                             const output = await started[k];
                             hooks.onToolResult?.(tc, output, null, null, 1); // task 结果是摘要,无 diff
-                            pushToolResult(history, tc, output, relprune, lifecycle, scheduler);
+                            // Thrashing:同上
+                            const hint = recordAndHint(tc.name, tc.arguments);
+                            pushToolResult(history, tc, hint ? `${output}${hint}` : output, relprune, lifecycle, scheduler);
                         }
                         hooks.onToolDone?.();
                         i = j;
@@ -301,11 +351,13 @@ export async function runAgentCore(opts) {
                         const tc = calls[i];
                         // plan 模式防御 backstop:schema 已剔除这些工具,正常不会进这里;防后端幻觉调用——
                         // 不执行,直接返错回灌(让模型看到「plan 模式禁用」并停止),绝不写盘 / 跑命令。
-                        if (getAgentMode() === 'plan' && PLAN_DISABLED_TOOLS.has(tc.name)) {
+                        if (getAgentMode() === 'plan' && getPlanDisabledTools().has(tc.name)) {
                             hooks.onToolHeader?.(tc);
                             const err = `错误:计划模式下禁用工具 ${tc.name}(仅读探查,不改动文件 / 不跑命令)`;
                             hooks.onToolResult?.(tc, err, null, null, 1);
-                            pushToolResult(history, tc, err, relprune, lifecycle, scheduler);
+                            // Thrashing:同上
+                            const hint = recordAndHint(tc.name, tc.arguments);
+                            pushToolResult(history, tc, hint ? `${err}${hint}` : err, relprune, lifecycle, scheduler);
                             i++;
                             continue;
                         }
@@ -318,7 +370,9 @@ export async function runAgentCore(opts) {
                         const output = await executeTool(tc.name, tc.arguments, signal, { skipRollback, dropContext });
                         hooks.onToolDone?.();
                         hooks.onToolResult?.(tc, output, parsed, preWriteOld, editStartLine);
-                        pushToolResult(history, tc, output, relprune, lifecycle, scheduler);
+                        // Thrashing:同上(history 附 hint,UI 干净)
+                        const hint = recordAndHint(tc.name, tc.arguments);
+                        pushToolResult(history, tc, hint ? `${output}${hint}` : output, relprune, lifecycle, scheduler);
                         // 相关性裁剪 mutation 通知:edit_file/write_file 后,该 path 之前的所有 read_file
                         // 结果已失效(已不再是文件当前状态)→ stub 为存根。pruner 内部 try/catch + 幂等。
                         // 非 mutation 工具(run_command/use_skill/memory_* 等)此处 path="" 不触发。
@@ -346,16 +400,16 @@ export async function runAgentCore(opts) {
                 hooks.onNoReply?.();
             history.push({ role: 'assistant', content: result.content });
             done = true;
-            return { completed: true, finalText: result.content };
+            return { completed: true, finalText: result.content, usage: turnUsage };
         }
         hooks.onMaxSteps?.();
         done = true;
-        return { completed: true, finalText: null };
+        return { completed: true, finalText: null, usage: turnUsage };
     }
     finally {
         // 跑完(正常 / 达上限)在回复末尾打耗时摘要行(仿 Claude Code);中断 done=false 不打。
         if (done) {
-            hooks.onDone?.(Date.now() - t0);
+            hooks.onDone?.(Date.now() - t0, turnUsage);
         }
     }
 }

package/dist/agent/index.js

@@ -110,15 +110,19 @@ onContextUpdate) {
                 layout.contentWrite('\n');
             layout.contentWrite(`${ui.dim}(已中断)${ui.reset}\n`);
         },
-        onDone: (elapsedMs) => layout.contentWrite(`  ${ui.dim}✻ Worked for ${fmtElapsed(elapsedMs)}${ui.reset}\n`),
+        onDone: (elapsedMs, usage) => {
+            const tok = formatTurnTokens(usage);
+            layout.contentWrite(`  ${ui.dim}✻ Worked for ${fmtElapsed(elapsedMs)}${tok}${ui.reset}\n`);
+        },
     };
     // 桌宠状态广播:与 TUI hooks 并列注入,互不干扰(petHooks 只调 bridge.sendState,不写屏;
     // 未 /pet 连接时 sendState 内部 no-op)。仅主 agent 走这里——子 agent(spawn.ts)不引用 createPetHooks,
     // 故子 agent 永不广播桌宠状态。
     const petHooks = createPetHooks();
     const combinedHooks = mergeHooks(hooks, petHooks);
+    let result;
     try {
-        await runAgentCore({
+        result = await runAgentCore({
             history,
             userInput,
             signal,
@@ -129,6 +133,7 @@ onContextUpdate) {
     finally {
         spinner.stop();
     }
+    return result;
 }
 /** 把两组 AgentHooks 合并为一组:每个方法依次调用两侧已定义的实现(顺序不保证跨方法一致,
  *  但同一事件内先 a 后 b)。用于把桌宠状态广播 hooks 与 TUI 渲染 hooks 并列挂载,互不影响。 */
@@ -145,3 +150,36 @@ function mergeHooks(a, b) {
     }
     return merged;
 }
+/** 摘要行后追加的本轮 token 文本。
+ *  例(无 cache):
+ *    `  ·  1.5k tokens (↑ 1.2k ↓ 0.3k)`
+ *  例(命中 cache,DeepSeek 类折扣计费):
+ *    `  ·  72k tokens (↑ 8k ↓ 3k) · ↻ 61k cached`
+ *  例(CoT 模型 + cache):
+ *    `  ·  72k tokens (↑ 8k ↓ 3k) · ↻ 61k cached · reasoning 1.2k`
+ *
+ *  设计要点:
+ *  - 括号里 ↑ 显示**计费 prompt**(= 全量 - cached),不是后端报的 raw prompt,
+ *    否则用户看到 69k 会按全价估成本,实际只花了 5-9k 的 $。
+ *  - ↻ 显示 cache 命中(白嫖部分),让用户一眼看到优化效果(系统 prompt 越长、对话越长越显著)。
+ *  - reasoning 是 completion 的子集(已含在 ↓ 里),仅作信息;不二次计入成本。
+ *  - 总数 total 不变 —— 是数学意义上的"流过的 token",反映 LLM 实际工作量。
+ *  关闭 include_usage / 全失败 → usage=undefined → 不输出(保持原摘要行长度)。 */
+function formatTurnTokens(usage) {
+    if (!usage)
+        return '';
+    const total = usage.totalTokens;
+    if (!total)
+        return '';
+    const fmt = (n) => (n < 1000 ? `${n}` : `${(n / 1000).toFixed(total >= 10000 ? 0 : 1)}k`);
+    const cached = usage.cachedTokens;
+    const reasoning = usage.reasoningTokens;
+    const billablePrompt = usage.promptTokens - cached;
+    const extras = [];
+    if (cached > 0)
+        extras.push(`↻ ${fmt(cached)} cached`);
+    if (reasoning > 0)
+        extras.push(`reasoning ${fmt(reasoning)}`);
+    const extrasStr = extras.length > 0 ? ` · ${extras.join(' · ')}` : '';
+    return `  ·  ${fmt(total)} tokens (↑ ${fmt(billablePrompt)} ↓ ${fmt(usage.completionTokens)})${extrasStr}`;
+}

package/dist/agent/spawn.js

@@ -15,19 +15,19 @@
 //  - 逻辑隔离(回滚):skipRollback=true,子 agent 的 write_file/edit_file 改动不进主回滚快照链,
 //    主 /rollback 不撤销子 agent 改动(靠 git 兜底)。子 agent 与主 agent 共享 cwd(文件改动可见)。
 import { chatTools } from '../llm/index.js';
-import { config } from '../config/index.js';
+import { config, isMemoryEnabled } from '../config/index.js';
 import { effectiveSystemPrompt } from '../skills/index.js';
 import { buildMemorySection, buildMemoryIndexSection } from '../memory/index.js';
 import { ui } from '../ui/theme.js';
 import { runAgentCore } from './core.js';
 import { summarizeToolCall, summarizeToolResult, truncateDisplay } from '../ui/render.js';
 /** 子 agent 系统提示后缀:角色与约束。 */
-const SUBAGENT_SUFFIX = `
-
-## ⛯ SUB-AGENT MODE (you are a sub-agent)
-You are a sub-agent spawned by the main agent to handle an isolated sub-task. You have your own conversation history (independent of the main thread).
-- Focus solely on the assigned sub-task. Do NOT attempt to call the "task" tool (no recursive spawning).
-- Use the tools available to you to complete the sub-task.
+const SUBAGENT_SUFFIX = `
+
+## ⛯ SUB-AGENT MODE (you are a sub-agent)
+You are a sub-agent spawned by the main agent to handle an isolated sub-task. You have your own conversation history (independent of the main thread).
+- Focus solely on the assigned sub-task. Do NOT attempt to call the "task" tool (no recursive spawning).
+- Use the tools available to you to complete the sub-task.
 - When done, your final text reply will be returned to the main agent as a summary — make it concise and actionable: what you did, key findings, files changed, and any issues. The main agent will decide the next step based on your summary.`;
 /**
  * 派生一个子 agent 执行独立子任务。
@@ -44,9 +44,13 @@ You are a sub-agent spawned by the main agent to handle an isolated sub-task. Yo
 export async function spawnAgent(opts) {
     const maxSteps = opts.maxSteps ?? config.subAgentMaxSteps ?? 50;
     // 构造子 agent 系统提示:复用主 agent 组装链 + 子 agent 角色后缀 + 自定义后缀。
+    // config.systemPrompt 是 getter(每次访问现拼 buildBasePrompt,反映 isMemoryEnabled),
+    // 所以这里直接读 config.systemPrompt 即可;buildMemoryIndexSection 显式按 isMemoryEnabled() 传参,
+    // 关闭时该段不进。注意:不能从 spawn.ts 直接 import buildBasePrompt —— 这会
+    // 拉起 config → llm → registry → builtins → task → spawn 形成循环求值死锁。
     const systemPrompt = effectiveSystemPrompt(config.systemPrompt +
         buildMemorySection() +
-        buildMemoryIndexSection() +
+        buildMemoryIndexSection(isMemoryEnabled()) +
         SUBAGENT_SUFFIX +
         (opts.systemPromptSuffix ? `\n\n${opts.systemPromptSuffix}` : ''));
     // 工具子集:白名单过滤。无白名单 = 全量 chatTools,但始终剔除 task(防递归派生)。
@@ -102,7 +106,12 @@ export async function spawnAgent(opts) {
         onToolBatchEnd: () => writeBuf('\n'),
         onNoReply: () => writeBuf(`${ui.dim}(无回复)${ui.reset}\n`),
         onMaxSteps: () => writeBuf(`  ● 达到最大步数(${maxSteps}),子 agent 停止。\n`),
-        onDone: (elapsedMs) => writeBuf(`  ✻ 子 agent 耗时 ${(elapsedMs / 1000).toFixed(1)}s\n`),
+        onDone: (elapsedMs, usage) => {
+            const tok = usage && usage.totalTokens
+                ? `  · ${usage.totalTokens} tokens${usage.cachedTokens ? ` ↻${usage.cachedTokens} cached` : ''}`
+                : '';
+            writeBuf(`  ✻ 子 agent 耗时 ${(elapsedMs / 1000).toFixed(1)}s${tok}\n`);
+        },
         // onStepStart / onChatDone / onToolStart / onToolDone / onAbort:子 agent 静默,无需 spinner / 中断渲染。
         // abort 还原(history 还原 + 模式还原)由 core 的 abortRestore 处理,hooks 只管展示。
     };

package/dist/config/index.js

@@ -59,6 +59,7 @@ const PLATFORM_NOTE = (() => {
 - You are on Windows; run_command runs commands via cmd.exe (/c). Unix shell builtins are NOT available here.
 - Windows equivalents: which→where, cat→type, ls→dir, rm→del/rd, cp→copy, mv→move. cmd.exe uses %VAR% (not $VAR); pipes (|) and redirects (>, >>) work, but no $(...) command substitution or backticks.
 - head/tail/find/grep/sed have no cmd.exe equivalent — use the dedicated tools (read_file for head/tail, glob for find, grep for grep), or invoke PowerShell via run_command if you need more.
+- **Avoid \`run_command\` for file ops on Windows**: cmd /c re-parses paths with backslashes / spaces / quotes — fragile, and ~half of "agent can't find file" failures trace back to this. Use the dedicated tools (read_file/glob/grep) which take absolute Windows paths natively, no shell involved. In particular, NEVER \`dir\` / \`ls\` / \`Test-Path\` / \`if exist\` / \`python -c "os.path.exists(...)"\` — those waste turns on escaping. Use \`glob\` to list, and just call \`read_file\` to test existence (returns ENOENT as a clean error string). If you must shell out, use forward slashes (\`C:/foo/bar\`).
 - Prefer the dedicated tools (read_file/glob/grep) over shell equivalents — they're cross-platform and already wired in.`;
     }
     if (process.platform === 'darwin') {
@@ -71,27 +72,91 @@ const PLATFORM_NOTE = (() => {
 - You are on ${process.platform}; run_command runs via bash -c. GNU coreutils — standard POSIX/GNU shell syntax is safe.
 - Still prefer the dedicated tools (read_file/glob/grep) over hand-rolled shell where they fit — they avoid quoting pitfalls and are already wired in.`;
 })();
-const SYSTEM_PROMPT = `You are mocode, a terminal coding agent. You complete programming tasks through a "think → call tool → observe result → think again" loop until the problem is solved. Reply to the user in Chinese.
+/**
+ * 基础系统提示的"记忆段落":开 isMemoryEnabled() 时才拼。
+ * 默认关(新用户零侵入):这段 + 工具表里的 5 个 memory_* + 系统提示尾部的 Memory Index
+ * 都不出现;打开 /memory_switch 后下一次新建 system message 才注入。
+ */
+const SYSTEM_PROMPT_MEMORY_SECTION = `
+## Memory (cross-session long-term facts)
+- A "memory index" (id/title/summary only) is injected into the system prompt. Retrieve full body via memory_search (pass id or keyword); use memory_list to see the entire index.
+- Store non-obvious, cross-session-useful facts/decisions/pitfalls (architecture conventions, gotchas, user preferences, decisions made) with memory_save — only long-term stable items, not current bugs / temp files / undecided TODOs.
+- If an existing memory is outdated or contradicts new facts, correct it in-place with memory_update(id, …) (don't create a duplicate); archive clearly-stale ones with memory_forget(id).
+- Before saving, memory_search to check for an existing similar entry to avoid duplicates. Better to store less than to store trivially correct information.
+- A background reflection pass periodically mines and organizes memories from the session (no manual action needed), but key facts you proactively save are more reliable.`;
+/**
+ * plan 模式追加到系统提示末尾的指令(切到 plan 模式时由 repl 拼进 history[0])。
+ * 与 SYSTEM_PROMPT 同语种(英文),指示:只读探查、产出步骤化计划、不执行、审批后回 auto。
+ *
+ * memoryEnabled=false 时:memory_save/update/forget 三个写工具名字 + "memory-write tools" 这
+ * 句都不出现,且 read-only 列表里的 memory_search/memory_list 也移除——避免提示词里出现
+ * 根本不存在的工具名引起 LLM 调不到。
+ */
+function buildPlanModeSuffix() {
+    if (!isMemoryEnabled()) {
+        return `
+
+## ⛯ PLAN MODE (active now)
+You are in PLAN mode: investigate and design only — do NOT execute or change anything.
+- Your editing / command tools (write_file, edit_file, run_command) have been REMOVED from your tool list. Use only the read-only tools available to you (read_file, glob, grep, codegraph, web_search, web_fetch, use_skill, ask_human) to investigate.
+- Research thoroughly: locate the relevant code, trace call paths, and understand existing patterns and conventions before designing. Your FIRST action for code exploration should be the codegraph tool (explore/node) when a .codegraph/ index exists — not read_file/grep. Use read_file/grep only to fill gaps codegraph leaves.
+- Then produce a clear, actionable implementation plan: files to change (with paths), what to change in each and why, the ordered steps, edge cases to handle, and how to verify (typecheck / tests / build). Be specific enough to execute against.
+- When the plan is complete and ready for review, you MUST call the \`ask_human\` tool to surface the plan to the user for approval — do NOT just output the plan as plain text and STOP. ask_human renders a real interactive selection panel inside the TUI; plain-text approval questions in your reply are hard to see and easy to miss.
+- Pass the \`ask_human\` tool a concise plan summary (goal + files/areas to change + key risks + verification) and these three options so the user can decide in one click:
+    1. "按计划执行 (switch to auto and implement)"  — user approves; you then call \`switch_mode("auto")\` IN THE SAME turn and proceed.
+    2. "继续细化方案 (stay in plan, refine)"          — user wants more detail / alternatives; stay in plan, iterate, and re-ask via \`ask_human\` when ready.
+    3. "取消 / 暂不执行 (abort)"                       — user wants to stop; STOP, do NOT call \`switch_mode\`.
+- This applies to BOTH paths: whether the user said "先 plan 再 auto" (autonomous) or entered plan mode manually (via /plan or Shift+Tab) for safety review. The single rule is: never silently self-switch and never silently STOP — always route through \`ask_human\` so the user has an explicit chance to approve, refine, or cancel.
+- Do NOT in your text reply ask rhetorical confirmation questions like "shall I proceed? / 是否同意 / 需要你确认吗" — that bypasses the panel and forces the user to type free-text feedback, which is strictly worse than picking from the 3 options. ask_human is the only sanctioned approval channel in plan mode.
+- Note: the REPL may still show its own approval prompt (\`promptIntervention\`) as a defense-in-depth fallback if you somehow STOP without calling ask_human — do not rely on it; the primary path is ask_human.`;
+    }
+    return `
+
+## ⛯ PLAN MODE (active now)
+You are in PLAN mode: investigate and design only — do NOT execute or change anything.
+- Your editing / command / memory-write tools (write_file, edit_file, run_command, memory_save, memory_update, memory_forget) have been REMOVED from your tool list. Use only the read-only tools available to you (read_file, glob, grep, codegraph, web_search, web_fetch, use_skill, ask_human, memory_search, memory_list) to investigate.
+- Research thoroughly: locate the relevant code, trace call paths, and understand existing patterns and conventions before designing. Your FIRST action for code exploration should be the codegraph tool (explore/node) when a .codegraph/ index exists — not read_file/grep. Use read_file/grep only to fill gaps codegraph leaves.
+- Then produce a clear, actionable implementation plan: files to change (with paths), what to change in each and why, the ordered steps, edge cases to handle, and how to verify (typecheck / tests / build). Be specific enough to execute against.
+- When the plan is complete and ready for review, you MUST call the \`ask_human\` tool to surface the plan to the user for approval — do NOT just output the plan as plain text and STOP. ask_human renders a real interactive selection panel inside the TUI; plain-text approval questions in your reply are hard to see and easy to miss.
+- Pass the \`ask_human\` tool a concise plan summary (goal + files/areas to change + key risks + verification) and these three options so the user can decide in one click:
+    1. "按计划执行 (switch to auto and implement)"  — user approves; you then call \`switch_mode("auto")\` IN THE SAME turn and proceed.
+    2. "继续细化方案 (stay in plan, refine)"          — user wants more detail / alternatives; stay in plan, iterate, and re-ask via \`ask_human\` when ready.
+    3. "取消 / 暂不执行 (abort)"                       — user wants to stop; STOP, do NOT call \`switch_mode\`.
+- This applies to BOTH paths: whether the user said "先 plan 再 auto" (autonomous) or entered plan mode manually (via /plan or Shift+Tab) for safety review. The single rule is: never silently self-switch and never silently STOP — always route through \`ask_human\` so the user has an explicit chance to approve, refine, or cancel.
+- Do NOT in your text reply ask rhetorical confirmation questions like "shall I proceed? / 是否同意 / 需要你确认吗" — that bypasses the panel and forces the user to type free-text feedback, which is strictly worse than picking from the 3 options. ask_human is the only sanctioned approval channel in plan mode.
+- Note: the REPL may still show its own approval prompt (\`promptIntervention\`) as a defense-in-depth fallback if you somehow STOP without calling ask_human — do not rely on it; the primary path is ask_human.`;
+}
+/** 兼容旧名字:repl 的 buildSystemMessage 仍引 PLAN_MODE_SUFFIX(变量)。运行时按需现拼。 */
+export function buildBasePrompt() {
+    const autoAllToolsLine = isMemoryEnabled()
+        ? '- Default is AUTO mode: you research and execute with all tools (read/edit/run_command/memory/web/skills).'
+        : '- Default is AUTO mode: you research and execute with all tools (read/edit/run_command/web/skills).';
+    const memorySection = isMemoryEnabled() ? SYSTEM_PROMPT_MEMORY_SECTION : '';
+    const planLine = isMemoryEnabled()
+        ? '- For complex or multi-step tasks, the user may switch to PLAN mode (Shift+Tab): your editing/command/memory-write tools are then removed from your tool list, and you must research with read-only tools only and produce a step-by-step plan (no execution). On approval the session returns to auto mode to execute the plan.'
+        : '- For complex or multi-step tasks, the user may switch to PLAN mode (Shift+Tab): your editing/command tools are then removed from your tool list, and you must research with read-only tools only and produce a step-by-step plan (no execution). On approval the session returns to auto mode to execute the plan.';
+    return `You are mocode, a terminal coding agent. You complete programming tasks through a "think → call tool → observe result → think again" loop until the problem is solved. Reply to the user in Chinese.
 
 ${PLATFORM_NOTE}
 
+## Step / Turn Economy (read this first — saves LLM calls)
+- **Minimize turns**: each user message costs at least one LLM call, and history grows every step until threshold-triggered compact fires (extra call). If a request contains ≥2 independent sub-goals (e.g. "改 X 然后再优化 Y"), ask the user to split them into separate turns rather than chaining both in one go. State this politely: "这条包含 N 个独立目标,建议拆成 N 次对话,以避免上下文膨胀。"
+- **Batch read-only tools in parallel**: in a single assistant turn, emit multiple tool_calls together — consecutive read-only tools (read_file, glob, grep, codegraph, web_search, web_fetch) auto-execute in parallel. Do NOT call them serially across turns when you could emit them together in one turn. This is the single biggest step-saver.
+- **Decide before reading**: do not read files "just to see"; plan the 2-3 file paths you actually need, then emit them as one batched tool_calls turn.
+- **Don't repeat failed calls**: if the same tool call fails or returns the same content 3 times in this turn, switch strategy (use a different tool, ask the user, or re-read the tool description) — don't keep retrying the same shape.
+
 ## Workflow
 - Understand before acting: when unsure about requirements or code state, explore first; don't assume.
 - **Code exploration first action**: before reading files with read_file or searching with grep, check if a .codegraph/ index exists. If it does, use the codegraph tool (explore for questions/features, node for a specific symbol) as your FIRST step — it returns source + call paths in one shot. Only fall back to read_file/grep when codegraph misses, you need just-changed content, or you're editing a known small file. Build the index with \`codegraph init\` if none exists.
 - Small steps: break tasks into verifiable sub-steps. Before each step, think clearly about what to change and why.
 - Verify after change: run typecheck / tests / build via run_command to confirm it works. Never claim done without verification.
 
-## Step / Turn Economy (read this — saves LLM calls)
-- **Minimize turns**: each user message costs at least one LLM call, and history grows every step until threshold-triggered compact fires (extra call). If a request contains ≥2 independent sub-goals (e.g. "改 X 然后再优化 Y"), ask the user to split them into separate turns rather than chaining both in one go. State this politely: "这条包含 N 个独立目标,建议拆成 N 次对话,以避免上下文膨胀。"
-- **Batch read-only tools in parallel**: in a single assistant turn, emit multiple tool_calls together — consecutive read-only tools (read_file, glob, grep, codegraph, web_search, web_fetch) auto-execute in parallel. Do NOT call them serially across turns when you could emit them together in one turn. This is the single biggest step-saver.
-- **Decide before reading**: do not read files "just to see"; plan the 2-3 file paths you actually need, then emit them as one batched tool_calls turn.
-
 ## Tool Guidelines
 - See each tool's own description for parameters and usage; this section covers selection strategy and pitfalls only.
 - **Prefer codegraph for code exploration**: when understanding/locating code, tracing call chains, or assessing impact of changes, if a .codegraph/ index exists, use the codegraph tool first (explore to query by question, node to look up a single symbol) — it returns relevant source + call paths in one shot, more accurate and economical than piecing together via read_file/grep. Fall back to read_file / grep / glob only when codegraph is unavailable (no index), misses, you need to see just-changed content, or you're editing a single known small file. Build the index first with \`codegraph init\` if none exists.
 - Before editing code, read_file to confirm actual content (with line numbers); don't guess from memory.
 - For local edits use edit_file: old_string must be unique and match exactly (including indentation/newlines); include surrounding context lines to ensure uniqueness. Use write_file for new files or full rewrites.
-- Use glob to find file paths, grep to search content; don't use run_command to pipe cat / sed / find / grep.
+- Use glob to find file paths, grep to search content. **Don't use run_command for file-level checks** (existence / listing / type) — those have no clean cmd.exe equivalent and Windows path escaping fails often. Use \`glob\` to list, and just call \`read_file\` to test existence (returns ENOENT as a clean error string). The earlier rule against \`run_command\` for cat/sed/find/grep still applies.
 - run_command runs per platform (cmd on Windows, bash elsewhere); state intent before running commands with side effects (deleting files, installing packages, git push, resets, etc.).
 - Use web_search for information beyond training data (new versions, news, real-time data, latest APIs); don't answer potentially outdated info from memory.
 - Use web_fetch to read a specific URL (a link from search results, or a URL given by the user); it only fetches static HTML — if a JS-rendered page yields no body, switch to web_search (its results include cleaned body text).
@@ -116,16 +181,9 @@ ${PLATFORM_NOTE}
 - Confirm with the user before irreversible or outward-facing operations (delete, overwrite existing files, push, request external services), unless explicitly authorized.
 - Operate only within authorized scope; when unsure, ask — don't guess.
 
-## Memory (cross-session long-term facts)
-- A "memory index" (id/title/summary only) is injected into the system prompt. Retrieve full body via memory_search (pass id or keyword); use memory_list to see the entire index.
-- Store non-obvious, cross-session-useful facts/decisions/pitfalls (architecture conventions, gotchas, user preferences, decisions made) with memory_save — only long-term stable items, not current bugs / temp files / undecided TODOs.
-- If an existing memory is outdated or contradicts new facts, correct it in-place with memory_update(id, …) (don't create a duplicate); archive clearly-stale ones with memory_forget(id).
-- Before saving, memory_search to check for an existing similar entry to avoid duplicates. Better to store less than to store trivially correct information.
-- A background reflection pass periodically mines and organizes memories from the session (no manual action needed), but key facts you proactively save are more reliable.
-
-## Plan vs Auto modes
-- Default is AUTO mode: you research and execute with all tools (read/edit/run_command/memory/web/skills).
-- For complex or multi-step tasks, the user may switch to PLAN mode (Shift+Tab): your editing/command/memory-write tools are then removed from your tool list, and you must research with read-only tools only and produce a step-by-step plan (no execution). On approval the session returns to auto mode to execute the plan.
+${memorySection}
+${autoAllToolsLine}
+${planLine}
 
 ## Working notepad (todolist) — checklist for complex tasks
 - For **complex multi-step tasks** (≥3 file changes OR ≥5 tool calls expected OR user says "先计划再执行" / "plan then do" / "按步骤来"), call the \`todolist\` tool FIRST to write a plan to \`.mocode/plans/<id>.md\`, then execute step by step, calling \`todolist update\` to mark progress. For trivial single-step tasks, skip it and just execute.
@@ -137,25 +195,30 @@ ${PLATFORM_NOTE}
 ## Termination & Reporting
 - Stop immediately when no more tools are needed; give conclusions directly.
 - Report honestly: say success when successful, say where you're stuck when failing, and mention anything skipped. Reference code in "path:line" format (e.g., src/index.ts:42). Keep it concise.`;
+}
 /**
- * plan 模式追加到系统提示末尾的指令(切到 plan 模式时由 repl 拼进 history[0])。
- * 与 SYSTEM_PROMPT 同语种(英文),指示:只读探查、产出步骤化计划、不执行、审批后回 auto。
+ * plan 模式追加到系统提示末尾的指令。
+ * 历史曾是 `export const PLAN_MODE_SUFFIX`(顶层字面量);现改为按 isMemoryEnabled()
+ * 动态拼:false 时不出现 memory_* 工具名,避免 LLM 想调不存在的工具。
+ *
+ * 注意:已改为 getter(每次访问现拼),让运行时切 /memory_switch 后立即生效。
+ * 旧 import `PLAN_MODE_SUFFIX` 路径不变;repl 推荐改用 getPlanModeSuffix()(语义更清晰)。
+ * 不能直接 `export const PLAN_MODE_SUFFIX = buildPlanModeSuffix()`:
+ * 该表达式在模块初始化时立即求值,而 buildPlanModeSuffix 内部读 config,config 还未求值 → TDZ。
  */
-export const PLAN_MODE_SUFFIX = `
-
-## ⛯ PLAN MODE (active now)
-You are in PLAN mode: investigate and design only — do NOT execute or change anything.
-- Your editing / command / memory-write tools (write_file, edit_file, run_command, memory_save, memory_update, memory_forget) have been REMOVED from your tool list. Use only the read-only tools available to you (read_file, glob, grep, codegraph, web_search, web_fetch, use_skill, ask_human, memory_search, memory_list) to investigate.
-- Research thoroughly: locate the relevant code, trace call paths, and understand existing patterns and conventions before designing. Your FIRST action for code exploration should be the codegraph tool (explore/node) when a .codegraph/ index exists — not read_file/grep. Use read_file/grep only to fill gaps codegraph leaves.
-- Then produce a clear, actionable implementation plan: files to change (with paths), what to change in each and why, the ordered steps, edge cases to handle, and how to verify (typecheck / tests / build). Be specific enough to execute against.
-- Present the plan as your final reply and STOP, unless the user explicitly asked you to "plan first then execute" / "先 plan 再 auto" / autonomous execution: in that case, after presenting the plan, call the switch_mode tool with mode="auto" to switch back to auto mode WITHIN THE SAME TURN and continue implementing the plan yourself (your write/edit/command/memory-write tools become available again immediately). The user will see no approval prompt because you self-switched.
-- If the user entered plan mode manually (via /plan or Shift+Tab) for a safety review and did NOT ask for autonomous execution, do NOT call switch_mode — present the plan and STOP. Do NOT ask the user for confirmation or approval in your text reply (e.g. "is this plan OK?", "shall I proceed?", "需要你确认") — the REPL automatically shows an approval prompt after you STOP, so asking in text is redundant and forces the user to answer twice. Just present the plan and end your reply.`;
+export function getPlanModeSuffix() {
+    return buildPlanModeSuffix();
+}
 export const config = {
     baseURL: requireEnv('LLM_BASE_URL'),
     apiKey: requireEnv('LLM_API_KEY'),
     model: process.env.LLM_MODEL || 'gpt-4o-mini',
     maxTokens: process.env.MAX_TOKENS ? Number(process.env.MAX_TOKENS) : undefined,
-    systemPrompt: SYSTEM_PROMPT,
+    // 用 getter 而非 buildBasePrompt() 立即求值:因为本对象字面量求值时 buildBasePrompt 读 config.memoryEnabled,
+    // 而 config 还没完成初始化(TDZ)。Getter 让每次访问都现拼,运行时 /memory_switch 立即生效。
+    get systemPrompt() {
+        return buildBasePrompt();
+    },
     contextWindowTokens: Number(process.env.CONTEXT_WINDOW_TOKENS) || 128000,
     compactThreshold: Number(process.env.COMPACT_THRESHOLD) || 0.85,
     includeUsage: process.env.LLM_STREAM_USAGE !== 'false',
@@ -165,6 +228,7 @@ export const config = {
     contextLifecycle: process.env.MOCODE_LIFECYCLE !== 'false',
     contextBudget: process.env.MOCODE_BUDGET_SCHEDULER !== 'false',
     autoReflect: process.env.AUTO_REFLECT !== 'false',
+    memoryEnabled: process.env.MEMORY_ENABLED === 'true',
     reflectEveryN: Number(process.env.REFLECT_EVERY_N) || 5,
     maxSteps: Number(process.env.MAX_STEPS) || 200,
     subAgentMaxSteps: Number(process.env.SUB_AGENT_MAX_STEPS) || 50,
@@ -205,3 +269,26 @@ export function updateModelConfig(opts) {
         process.env.CONTEXT_WINDOW_TOKENS = String(opts.contextWindowTokens);
     }
 }
+/**
+ * 记忆子系统总开关:单一来源。/memory_switch、/memory_status、buildSystemPrompt、
+ * tools/builtins/index.ts、tools/constants.ts 的 plan-mode 列表都从这里查。
+ * 默认 false(新用户零侵入)。
+ */
+export function isMemoryEnabled() {
+    return config.memoryEnabled;
+}
+/**
+ * 切换记忆子系统开关(/memory_switch on|off 调)。
+ * - 更新 config 单例字段(其它模块下次调 isMemoryEnabled() 即拿新值)。
+ * - 同步 process.env.MEMORY_ENABLED(下次启动 loadEnvFiles 不被文件回填)。
+ * 持久化(写 ~/.mocode/config 的 MEMORY_ENABLED 键)由调用方走 writeConfigKeys。
+ *
+ * 注:开关切换对当前会话的 tool list / 已拼好的 systemPrompt 不会自动重算 —
+ * 工具表在 REPL 启动时构建,systemPrompt 在每轮 chat() 拼时按 isMemoryEnabled()
+ * 现查现拼(关掉时该轮拼出来的 prompt 即不带 memory_* 段)。所以切换在「下一轮
+ * agent 调用」起即时生效,本轮已发出的请求不会回滚。
+ */
+export function updateMemoryConfig(enabled) {
+    config.memoryEnabled = enabled;
+    process.env.MEMORY_ENABLED = enabled ? 'true' : 'false';
+}

package/dist/llm/index.js

@@ -1,7 +1,7 @@
 import OpenAI from 'openai';
 import { config } from '../config/index.js';
 import { tools } from '../tools/registry.js';
-import { PLAN_DISABLED_TOOLS } from '../tools/constants.js';
+import { getPlanDisabledTools } from '../tools/constants.js';
 /**
  * LLM 调用重试策略:
  *   可重试  →  429 (rate limit) / 5xx (server) / APIConnectionError / Node 网络错 (ETIMEDOUT 等)
@@ -155,10 +155,75 @@ export const chatTools = tools.map((t) => ({
     },
 }));
 /**
- * plan 模式用的受限工具 schema:剔除写盘 / 命令 / 记忆写入类(PLAN_DISABLED_TOOLS),
+ * plan 模式用的受限工具 schema:剔除写盘 / 命令 / 记忆写入类(getPlanDisabledTools())。
  * 模型在 plan 模式下只看得到只读工具 → 调不到会改文件的工具。runAgent 在 plan 模式传给 chat()。
+ *
+ * 注意:planChatTools 是顶层 const(模块初始化时一次性求值);若运行时 /memory_switch 关闭
+ * 记忆,这里仍是按当前 isMemoryEnabled() 算出的快照——重启 REPL 才完全生效。
+ */
+export const planChatTools = chatTools.filter((t) => !getPlanDisabledTools().has(t.function.name));
+/**
+ * 多 provider 兼容的 cache / reasoning 字段提取。
+ * 不同后端报 cached 字段名差异巨大,这里按"最常见的几种"顺序 probe,
+ * 首个合法非负数字即用(0 也算合法 —— cache miss 是合法状态,不是"无数据")。
+ * 字段全缺 → 0,UI 不会显示任何额外标注(零行为变化)。
+ *
+ * 已实测 / 字段名已知:
+ *   - OpenAI / Azure / 多数 OpenAI 兼容中转:
+ *       prompt_tokens_details.cached_tokens
+ *   - DeepSeek(含 R1):
+ *       prompt_cache_hit_tokens(扁平,顶层)
+ *   - Anthropic Claude:
+ *       cache_read_input_tokens
+ *   - Moonshot Kimi / GLM-4.6 / Qwen:同 OpenAI 标准
+ *   - Ollama / 本地 vLLM / 其它:无 usage details → 0(零行为变化)
+ *
+ * reasoning 字段(CoT 模型):
+ *   - OpenAI o1 / DeepSeek R1 / GLM-Z1:
+ *       completion_tokens_details.reasoning_tokens
+ *   - 其它(个别):reasoning_tokens(顶层)
  */
-export const planChatTools = chatTools.filter((t) => !PLAN_DISABLED_TOOLS.has(t.function.name));
+export function extractUsageExtras(usage) {
+    if (!usage || typeof usage !== 'object')
+        return { cachedTokens: 0, reasoningTokens: 0 };
+    const u = usage;
+    // cached probe 顺序:OpenAI 标准 → DeepSeek 扁平 → Anthropic → 杂项兜底
+    const cachedCandidates = [
+        readPath(u, ['prompt_tokens_details', 'cached_tokens']),
+        u.prompt_cache_hit_tokens,
+        u.cache_read_input_tokens,
+        u.cached_tokens,
+        u.prompt_tokens_cached,
+    ];
+    // reasoning probe 顺序:OpenAI 标准 → 扁平兜底
+    const reasoningCandidates = [
+        readPath(u, ['completion_tokens_details', 'reasoning_tokens']),
+        u.reasoning_tokens,
+    ];
+    return {
+        cachedTokens: firstNumber(cachedCandidates) ?? 0,
+        reasoningTokens: firstNumber(reasoningCandidates) ?? 0,
+    };
+}
+/** 从对象按路径读嵌套字段(每段都做 null/undefined 检查,任一断即返 undefined)。 */
+function readPath(obj, path) {
+    let cur = obj;
+    for (const k of path) {
+        if (cur == null || typeof cur !== 'object')
+            return undefined;
+        cur = cur[k];
+    }
+    return cur;
+}
+/** 从候选数组里取第一个合法非负有限数字(0 算合法 —— cache miss 不是"无数据")。
+ * 顺序敏感:数组里前面的 provider 优先(如 OpenAI 标准报 0 时,不会 fallback 到 DeepSeek 字段)。 */
+function firstNumber(arr) {
+    for (const v of arr) {
+        if (typeof v === 'number' && Number.isFinite(v) && v >= 0)
+            return v;
+    }
+    return undefined;
+}
 /**
  * 流式调一次 LLM:增量回调文本,内部累加 tool_calls 片段。
  * tool_calls 跨 chunk 按 index 累加(id / name / arguments 拼接)。
@@ -219,10 +284,13 @@ async function chatOnce(messages, handlers, signal, toolsOverride) {
     for await (const chunk of stream) {
         // usage:末尾 chunk(choices 可能为空)在 include_usage 时携带;先读再 continue。
         if (chunk.usage) {
+            const extras = extractUsageExtras(chunk.usage);
             usage = {
                 promptTokens: chunk.usage.prompt_tokens,
                 completionTokens: chunk.usage.completion_tokens,
                 totalTokens: chunk.usage.total_tokens,
+                cachedTokens: extras.cachedTokens,
+                reasoningTokens: extras.reasoningTokens,
             };
         }
         const delta = chunk.choices?.[0]?.delta;

package/dist/memory/index.js

@@ -2,6 +2,7 @@
 // Tier-2:store.ts(叶子,node:fs)做 JSONL CRUD/GC/索引段;reflect.ts(→llm,同 session/)做后台反思 pass。
 // 被 repl 依赖(注入 systemPrompt + 轮末触发反思 + 退出 drain)。Tier-1 仅依赖 discover.ts。
 import { loadMemoryFiles } from './discover.js';
+import { isMemoryEnabled } from '../config/index.js';
 export { buildMemoryIndexSection, loadAll, gcMemories, } from './store.js';
 export { kickoffReflection, drainMemoryBackground, getLastReflectResult, clearLastReflectResult, snapshotTranscript, formatReflectResult, runReflection, } from './reflect.js';
 /** system 消息中 memory 段的字符上限(防过大占窗口——system 在 history[0],compactHistory 不压缩)。 */
@@ -30,8 +31,14 @@ export function loadMemory() {
     }
     return cache;
 }
-/** 拼进系统提示的 memory 段;无 memory 返空串(零行为变化)。 */
+/**
+ * 拼进系统提示的 memory 段(Tier-1 MOCODE.md);无 memory 返空串(零行为变化)。
+ * 记忆子系统总开关关闭(isMemoryEnabled()==false)直接返空串:
+ * 提示词、Memory Index 段都不进 — 配合 tools/builtins 把 memory_* 工具屏蔽。
+ */
 export function buildMemorySection() {
+    if (!isMemoryEnabled())
+        return '';
     const mem = loadMemory();
     if (!mem)
         return '';