mocode-ai 0.4.0 → 0.4.2

package/dist/context/relevance.js

@@ -0,0 +1,284 @@
+// Relevance Pruner:read_file 相关性裁剪(纯静态分析,零 LLM 调用)。
+//
+// 场景(用户描述):
+//   1) read foo.ts → 后来又 read foo.ts → 旧结果无价值 → 替换为存根
+//   2) read foo.ts → edit foo.ts → read foo.ts → 中间那次 read 之前的所有旧 read
+//      在 mutation 之后已失效 → 替换为存根
+//
+// 与现有子系统的关系:
+//   - Context Optimization Pipeline(`pipeline.ts`):单条上限 + 类型化编码。本层在其外,
+//     在 pushToolResult 出口再做一次"跨条"裁剪。
+//   - drop_context(`session/drop.ts`):agent 主动剔除已知无关的旧 tool 结果。本层是被动自动,
+//     不需要 agent 调;两者并存不冲突。
+//   - compact(`session/compact.ts`):阈值触发的整体微压缩+摘要。本层只裁"明确失效"的旧 read,
+//     不触发摘要;门槛更低、零成本。
+//
+// 不变量(对齐 drop_context / compact):
+//   - 只改 .content,不删消息、不动 tool_call_id、不动 tool_calls 数组结构。
+//   - 当前轮保护区:不剔除"最后一个 user 消息及其之后"的 read_file 结果(agent 本轮还在用,
+//     剔除会破坏正在进行的推理)。实现复用 drop.ts 的 lastUserIndex 思路。
+//   - 幂等:已 stub(含「已过时」标记)不重复 stub,避免反复重写同一条消息。
+//   - 永不抛错(对齐「调度器永不抛错」契约);无匹配 / 解析失败 / 异常 → 静默 no-op。
+//   - TUI 渲染(hooks.onToolResult)用原始 output,与本层解耦——屏上看全量,LLM 看裁剪后版。
+//
+// 零行为变化兜底:开关 `config.contextRelprune` 关闭时,pipeline 路径完全不调本模块。
+/** stub 标记前缀(供幂等判定)。drop_context 用的是「⌦[已剔除:与当前任务无关]」,
+ *  本层用「⌦[已过时:同 path 已有新 read / 已被 mutation 覆写]」,区分两类剔除来源。 */
+const STUB_PREFIX = '⌦[已过时:同 path 已有新 read / 已被 mutation 覆写]';
+/** 解析工具 arguments(只关心 path);非法返 null。 */
+function extractPath(argsRaw) {
+    if (!argsRaw)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(argsRaw);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const p = parsed.path;
+    if (typeof p !== 'string' || !p)
+        return null;
+    return p;
+}
+/** 从 history 末尾向前找最后一个 user 消息的索引;无 user 返 -1。
+ *  复用 drop.ts 的思路:user 及其之后的 tool 结果视为当前轮保护区。
+ *  在本层里,read_file tool 消息若落在 user 之后,本轮还在用,不能 stub。
+ *  注:history[0] 是 system,user 不会落在 0;若 user 就在末尾(即 0 user 之后),
+ *  protectedFrom=0 时整段历史都不可 stub(实际不会发生:pushToolResult 必在 user 之后)。 */
+function lastUserIndex(history) {
+    for (let i = history.length - 1; i >= 1; i--) {
+        if (history[i].role === 'user')
+            return i;
+    }
+    return -1;
+}
+/** 取 tool 消息对应的工具名(从紧邻的前导 assistant.tool_calls 按 tool_call_id 配对找)。
+ *  返回 null 表示找不到(孤儿 tool,极少见),本层保守不动。 */
+function toolNameOf(history, idx) {
+    const tcId = history[idx].tool_call_id;
+    if (!tcId)
+        return null;
+    for (let j = idx - 1; j >= 1; j--) {
+        const m = history[j];
+        if (m.role !== 'assistant')
+            continue;
+        const tcs = m.tool_calls;
+        if (!tcs)
+            continue;
+        const hit = tcs.find((tc) => tc?.id === tcId);
+        if (hit)
+            return hit.function?.name ?? null;
+    }
+    return null;
+}
+/** 把 content 拍平成字符串(对齐 drop.ts)。 */
+function toText(content) {
+    if (content == null)
+        return '';
+    if (typeof content === 'string')
+        return content;
+    try {
+        return JSON.stringify(content);
+    }
+    catch {
+        return String(content);
+    }
+}
+/**
+ * 维护「path → 该 path 所有 read_file tool 消息的 history index」映射。
+ *  - observePush:把刚 push 的 read_file tool 消息登记,并把同 path 的"更早" read 全部 stub。
+ *  - observeMutation:把该 mutation path 的"在 mutation 之前的" read 全部 stub。
+ *
+ * 设计:每个 agent 会话(每个 runAgentCore 实例)持有一个 pruner。会话结束/换 plan 时
+ * 可新建;不持久化(history 重建时索引自然过期)。
+ *
+ * 零依赖:仅依赖 ChatMessage 形状;不 import llm / tools / agent。
+ */
+export class RelevancePruner {
+    /** path → [history index, ...]  按插入序;最新在末尾。 */
+    readByPath = new Map();
+    /** 把刚 push 的消息通知 pruner。
+     *  - 只处理 tool 消息(role==='tool')。
+     *  - 只关心 read_file:登记 + 反向 stub 同 path 旧 read。
+     *  - 非 read_file 的 tool 消息:无操作(本层只管 read_file)。
+     *  - 非 tool 消息(assistant / user / system):无操作。
+     */
+    observePush(history, msg) {
+        try {
+            if (msg.role !== 'tool')
+                return;
+            const m = msg;
+            const tcId = m.tool_call_id;
+            if (!tcId)
+                return;
+            const idx = history.length - 1;
+            if (idx < 1 || history[idx] !== msg)
+                return; // 防御:必须刚 push 到末尾
+            const name = toolNameOf(history, idx);
+            if (name !== 'read_file')
+                return;
+            const content = toText(msg.content);
+            if (content.startsWith(STUB_PREFIX))
+                return; // 已是存根(防御)
+            // 从前导 assistant.tool_calls 找对应 tc.arguments(精确 path 来源)。
+            // 退化方案:从消息内容首行解析路径(read_file 输出形如 `\n     1\t...`,无 path;
+            // 故必须从 args 取)。找不到则保守不动。
+            let path = null;
+            for (let j = idx - 1; j >= 1; j--) {
+                const mm = history[j];
+                if (mm.role !== 'assistant')
+                    continue;
+                const tcs = mm.tool_calls;
+                if (!tcs)
+                    continue;
+                const hit = tcs.find((tc) => tc?.id === tcId);
+                if (hit) {
+                    path = extractPath(hit.function?.arguments);
+                    break;
+                }
+            }
+            if (!path)
+                return;
+            // 先 stub 旧 read(同 path,idx 之前),再登记新 idx。
+            this.stubPriorReads(history, path, idx);
+            // 登记新 idx
+            const list = this.readByPath.get(path);
+            if (list)
+                list.push(idx);
+            else
+                this.readByPath.set(path, [idx]);
+        }
+        catch {
+            /* 永不抛错 */
+        }
+    }
+    /**
+     * 把该 mutation path 的"在 mutation 之前的" read 全部 stub。
+     * 通常用于 edit_file / write_file 工具:mutation 之后,之前的 read_file(p) 内容
+     * 已失效(已不再是文件当前状态),模型后续若依赖旧 read 来 edit_file 会失败,但 edit_file
+     * 的 old_string 来自模型记忆/后读,不依赖旧 read 结果文本。
+     *
+     * 调用时机:agent/core.ts 在 mutation 工具调用的 pushToolResult 之后立即调;
+     * 此时 history 末尾就是 mutation 的 tool 消息,prior reads 指 < idx。
+     */
+    observeMutation(history, path) {
+        try {
+            if (!path)
+                return;
+            const idx = history.length - 1;
+            if (idx < 1)
+                return;
+            // mutation 之前的所有同 path read → stub
+            this.stubPriorReads(history, path, idx);
+            // 该 path 的 read 索引全部作废(mutation 之后再 read 会重新登记)
+            this.readByPath.delete(path);
+        }
+        catch {
+            /* 永不抛错 */
+        }
+    }
+    /**
+     * 把 history 里 "path 同 + index < beforeIdx + 不在当前轮保护区" 的所有 read_file
+     * tool 消息替换为存根(只改 .content,不动 id / 数组结构)。
+     *
+     * 实现:
+     *  - 用 readByPath[path] 直接拿到所有 index(已登记过),筛 < beforeIdx 的 stub。
+     *  - 同时扫一遍 [1, beforeIdx) 区间找未登记的(防御:索引可能漏登;不依赖索引也能 stub,
+     *    保证正确性。索引只用于"避免重复扫全表"的优化)。
+     *  - protectedFrom = lastUserIndex(history):user 之后一律不动。
+     *  - 幂等:已是 STUB_PREFIX 的跳过。
+     */
+    stubPriorReads(history, path, beforeIdx) {
+        const STUB_PREFIX_LOCAL = STUB_PREFIX;
+        const guard = lastUserIndex(history);
+        // protectedFrom = 最后一个 user index(若 >0);user 之后(>= guard)的 read 永不动。
+        // protectedFrom=0 表示无 user(history 只有 system),整段都可 stub。
+        const protectedFrom = guard > 0 ? guard : 0;
+        const stubOne = (i) => {
+            if (i >= beforeIdx)
+                return;
+            if (i >= protectedFrom && protectedFrom > 0)
+                return; // 当前轮保护区
+            const m = history[i];
+            if (!m || m.role !== 'tool')
+                return;
+            const content = toText(m.content);
+            if (content.startsWith(STUB_PREFIX_LOCAL))
+                return; // 幂等
+            const name = toolNameOf(history, i);
+            if (name !== 'read_file')
+                return;
+            // 校验 tool_call_id 配对(防御:孤儿子消息不动)
+            const tcId = m.tool_call_id;
+            if (!tcId)
+                return;
+            const stub = `${STUB_PREFIX_LOCAL} read_file(${path}) ${content.length} 字符 → 已被新 read / mutation 替代 · id …${tcId.slice(-6)}⌫`;
+            m.content = stub;
+        };
+        // 1) 用 Map 索引(快路径)
+        const indexed = this.readByPath.get(path);
+        if (indexed) {
+            for (const i of indexed)
+                stubOne(i);
+        }
+        // 2) 全表扫一遍(防御:索引可能漏登 / 历史来自 resume)
+        //    仅扫 [1, beforeIdx) 且不在保护区内的 range,成本可控。
+        const scanEnd = Math.min(beforeIdx, protectedFrom > 0 ? protectedFrom : beforeIdx);
+        for (let i = 1; i < scanEnd; i++) {
+            stubOne(i);
+        }
+    }
+}
+/** 默认单例:每个 agent 循环一个。runAgentCore 入口 new 一个,后续 observe 共享。 */
+export function createRelevancePruner() {
+    return new RelevancePruner();
+}
+/** 解析一条 stub 字符串,提取原 content 长度(若可解析)。失败返 null。 */
+function parseStubOriginalLen(stub) {
+    // 格式:⌦[已过时:同 path 已有新 read / 已被 mutation 覆写] read_file(<path>) <N> 字符 → ...
+    const m = / read_file\([^)]+\) (\d+) 字符 /.exec(stub);
+    if (!m)
+        return null;
+    const n = Number(m[1]);
+    return Number.isFinite(n) && n >= 0 ? n : null;
+}
+/**
+ * 扫 history,统计被相关性裁剪 stub 的 read_file tool 消息(条数 + 原字节数)。
+ * 供 /context 渲染统计行用(让用户直观看到「prune 帮了多少」)。
+ * 永不抛错(对齐本模块契约);history 为空 / 无 stub 时返零值。
+ *
+ * 注意:stub 后只剩 stub 字符串(原 content 已丢失),故只能从 stub 字符串里 parse
+ * 原字节数,误差 = stub 时记录的 content.length(精确);token 估算走 estimateTokens。
+ */
+export function computePruneStats(history) {
+    let stubbed = 0;
+    let originalChars = 0;
+    let stubChars = 0;
+    for (const m of history) {
+        if (m.role !== 'tool')
+            continue;
+        const c = toText(m.content);
+        if (!c.startsWith(STUB_PREFIX))
+            continue;
+        stubbed++;
+        stubChars += c.length;
+        const orig = parseStubOriginalLen(c);
+        if (orig != null)
+            originalChars += orig;
+    }
+    // token 估算:用 estimateTokens(懒导入,避免循环依赖 llm)
+    // 这里偷懒:走粗略 chars/4(中文混合下会过估,安全侧)
+    // 准确应调 estimateTokens,但 /context 已经是粗算,误差可接受
+    const originalTokens = Math.ceil(originalChars / 4);
+    const stubTokens = Math.ceil(stubChars / 4);
+    return {
+        stubbed,
+        originalChars,
+        originalTokens,
+        stubChars,
+        freedTokens: Math.max(0, originalTokens - stubTokens),
+    };
+}

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,13 @@ 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) => !PLAN_DISABLED_TOOLS.has(t.function.name));
+export const planChatTools = chatTools.filter((t) => !getPlanDisabledTools().has(t.function.name));
 /**
  * 流式调一次 LLM:增量回调文本,内部累加 tool_calls 片段。
  * tool_calls 跨 chunk 按 index 累加(id / name / arguments 拼接)。

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 '';

package/dist/memory/store.js

@@ -315,8 +315,15 @@ export function gcMemories() {
 /**
  * active 条目按 updatedAt 降序,封顶 MAX_INDEX_ENTRIES,只注 id/name/summary/type。
  * 无 active 返空串(零行为变化)。body 不注入——按需 memory_search 取。
+ *
+ * memoryEnabled=false 时(记忆子系统总开关关闭)直接返空串:Memory Index 段
+ * 不进系统提示,LLM 看不到工具使用提示;配合 tools/builtins 屏蔽 memory_* 工具,
+ * 实现「关闭时零侵入」(默认行为)。传参由 repl 的 buildSystemMessage 在拼装前调
+ * isMemoryEnabled() 注入(本文件是叶子,避免直接引 config 起环)。
  */
-export function buildMemoryIndexSection() {
+export function buildMemoryIndexSection(memoryEnabled = true) {
+    if (!memoryEnabled)
+        return '';
     const active = loadAll()
         .filter((e) => e.status === 'active')
         .sort((a, b) => (b.updatedAt || '').localeCompare(a.updatedAt || ''));

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, PLAN_MODE_SUFFIX, updateModelConfig, isModelConfigured } from '../config/index.js';
+import { config, updateModelConfig, isModelConfigured, updateMemoryConfig, isMemoryEnabled, buildBasePrompt, getPlanModeSuffix, } from '../config/index.js';
 import { updateConfigKey, writeConfigKeys, CONFIG_PATH } from '../config/file.js';
 import { runAgent } from '../agent/index.js';
 import { getAgentMode, setAgentMode, onModeChange } from '../agent/mode.js';
@@ -16,7 +16,7 @@ import { promptIntervention } from '../ui/intervention.js';
 import { tools } from '../tools/registry.js';
 import { estimateMessagesTokens, reconfigureClient, } from '../llm/index.js';
 import { loadImageAttachment, renderChip, MAX_INLINE_BYTES_DEFAULT, } from '../attachments/image.js';
-import { compactHistory, contextState, newSessionId, saveSession, loadSession, listSessions, } from '../session/index.js';
+import { manualCompact, contextState, newSessionId, saveSession, loadSession, listSessions, } from '../session/index.js';
 import { listTurns, planRollback, applyRollback, persistSnapshots, loadSnapshots, rebuildFromHistory, resetState, } from '../rollback/index.js';
 import { listSkills, effectiveSystemPrompt, } from '../skills/index.js';
 import { buildMemorySection, buildMemoryIndexSection, kickoffReflection, drainMemoryBackground, getLastReflectResult, clearLastReflectResult, snapshotTranscript, formatReflectResult, loadAll, } from '../memory/index.js';
@@ -35,9 +35,11 @@ const SLASH_COMMANDS = [
     { name: '/compact', desc: '压缩历史(可带焦点 /compact …)' },
     { name: '/resume', desc: '续接已保存的会话' },
     { name: '/rollback', desc: '菜单选轮次回滚(↑↓·Enter)' },
-    { name: '/memory', desc: '记忆库:条目计数与近期索引' },
-    { name: '/reflect', desc: '手动触发后台记忆反思 pass' },
-    { name: '/init', desc: '扫描项目生成 MOCODE.md 项目记忆' },
+    { name: '/memory', desc: '记忆库:条目计数与近期索引(关闭时提示先开 /memory_switch)' },
+    { name: '/memory_switch', desc: '切换记忆子系统开关(无参=切换;/on 或 /off 显式;持久化 MEMORY_ENABLED)' },
+    { name: '/memory_status', desc: '查看记忆子系统当前开关与原理' },
+    { name: '/reflect', desc: '手动触发后台记忆反思 pass(需先开启记忆)' },
+    { name: '/init', desc: '扫描项目生成 MOCODE.md 项目记忆(需先开启记忆)' },
     { name: '/theme', desc: '切换颜色主题(↑↓·Enter)' },
     { name: '/model', desc: '配置大模型(baseURL/key/model/窗口)' },
     { name: '/plan', desc: '切到 plan 模式(只读探查+产出计划)' },
@@ -141,14 +143,15 @@ function renderContextBarInline(history) {
     const pctCol = pct >= config.compactThreshold ? ui.yellow : ui.cyan;
     return `${ui.gray}[${pctCol}${bar}${ui.reset}] ${pctCol}${Math.round(pct * 100)}%${ui.reset} ${ui.dim}${k(est)}/${k(win)}${ui.reset}`;
 }
-/** 状态行基线:模型 / context / cwd / 模式标识 / 活跃 plan chip。repl 在轮次边界、切模式、plan 变更时调。 */
-function refreshStatusBase(history) {
+/** 状态行基线:模型 / context / cwd / 模式标识 / 活跃 plan chip / 本轮 token。repl 在轮次边界、切模式、plan 变更时调。 */
+function refreshStatusBase(history, lastTurnUsage) {
     layout.setStatusBase({
         model: config.model,
         contextBar: renderContextBarInline(history),
         cwd: process.cwd(),
         modeTag: getAgentMode() === 'plan' ? 'plan' : 'auto',
         planSummary: hasActivePlan() ? getActivePlanSummary(process.stdout.columns ?? 80) : '',
+        lastTurnUsage,
     });
 }
 /** 命令 → 运行态状态文字 + 底栏 dim 占位。 */
@@ -174,6 +177,10 @@ function runningStateFor(cmd) {
             return { status: '配模型', placeholder: '配置中…' };
         case '/pet':
             return { status: '桌宠', placeholder: '处理中…' };
+        case '/memory_switch':
+            return { status: '切记忆开关', placeholder: '切换中…' };
+        case '/memory_status':
+            return { status: '查记忆状态', placeholder: '…' };
         default:
             // 输入框留空(运行中可 typeahead 打字,dim 回显);运行状态由内联 spinner 承载(思考中/执行…),
             // 状态行只显走时——故常态 status 留空,不塞「处理」这种与内联重复的泛标签。
@@ -408,13 +415,17 @@ 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());
-    // 构造系统提示:auto 用 base;plan 在 config.systemPrompt 后追加 PLAN_MODE_SUFFIX。
+    // 构造系统提示:auto 用 base;plan 在 base 后追加按当前开关现拼的 plan suffix。
     // 切模式时 applyMode 重算 history[0](history[0] 恒 system,compaction 保它,不破坏)。
     // 活跃 plan 摘要拼在 memory 段后(systemPrompt 的尾段),todo 工具变更后 listener 重写 history[0]。
-    const buildSystemMessage = (planMode) => effectiveSystemPrompt(config.systemPrompt +
-        (planMode ? PLAN_MODE_SUFFIX : '') +
+    //
+    // 与开关联动:① base 用 buildBasePrompt() 取代 config.systemPrompt(后者是启动时一次性
+    // 求值的常量,运行时 /memory_switch 不会刷新);② plan suffix 走 getPlanModeSuffix() 现拼;
+    // ③ buildMemorySection 内已自决 ;④ buildMemoryIndexSection 显式传 isMemoryEnabled() 关闭段。
+    const buildSystemMessage = (planMode) => effectiveSystemPrompt(buildBasePrompt() +
+        (planMode ? getPlanModeSuffix() : '') +
         buildMemorySection() +
-        buildMemoryIndexSection() +
+        buildMemoryIndexSection(isMemoryEnabled()) +
         buildActivePlanSection());
     // 有预加载(--resume)则用它,并把 history[0] 刷成当前 system prompt(config 可能已变);
     // 否则新会话只塞 system 提示(默认 auto)。
@@ -434,6 +445,9 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null,
     let currentSessionId = sessionId;
     // 反思 cadence 计数:每 reflectEveryN 轮 fire-and-forget 一次后台反思 pass。
     let turnCount = 0;
+    // 本轮 token 累计:runAgent 返回后写入,供底栏模式 chip 右边显示。undefined=无实测
+    // (后端不开 include_usage / 后端失败时)。
+    let lastTurnUsage;
     const toolsLine = tools.map((t) => t.name).join(' · ');
     const banner = () => ({
         model: config.model,
@@ -598,10 +612,14 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null,
             setAgentMode(planMode ? 'plan' : 'auto');
             // 运行中每步 chat() 返回后刷新状态行 context 用量条(用 fresh lastUsage / 估算),
             // 否则整轮冻结在轮首 refreshStatusBase 的值,「执行 grep」时 2k/1000k 不动。
-            await runAgent(history, userInput, signal, () => {
+            const result = await runAgent(history, userInput, signal, () => {
                 refreshStatusBase(history);
                 layout.drawStatusBar();
             });
+            // 本轮 token 累计(底栏模式 chip 右边显示)。undefined = 后端不开 include_usage。
+            lastTurnUsage = result.usage;
+            refreshStatusBase(history, lastTurnUsage); // 即时刷状态行显示本轮 token chip
+            layout.drawStatusBar();
             ok = !signal.aborted; // 中断(Ctrl+C)→ runAgent 已还原 history,ok=false 不弹审批
             // 成功轮次自动落盘(崩溃也保住上一轮);新会话首轮分配 id
             if (!currentSessionId)
@@ -770,6 +788,7 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null,
             currentSessionId = undefined; // 下轮起新会话文件
             turnCount = 0; // 反思 cadence 重新计数
             contextState.lastUsage = undefined;
+            lastTurnUsage = undefined; // 清空旧轮的 token 累计
             pendingAttachments = []; // 一并清空待发图片
             layout.clearContent();
             layout.contentWrite(bannerString(banner()));
@@ -867,16 +886,69 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null,
             continue;
         }
         if (line === '/compact' || line.startsWith('/compact ')) {
-            const focus = line.startsWith('/compact ')
-                ? line.slice('/compact '.length).trim()
-                : undefined;
-            const r = await compactHistory(history, {
-                window: config.contextWindowTokens,
-                threshold: config.compactThreshold,
-                focus,
-            });
-            if (r.reason === 'noop') {
-                layout.contentWrite(`${ui.dim}(无需压缩:没有可压缩的旧消息)${ui.reset}\n`);
+            // /compact 可选语法:/compact [focus]  或  /compact --force [focus]
+            // --force:即便 oldGroups 空(history 全在保护区)也强行把早期消息降级压一次。
+            const rest = line.slice('/compact'.length).trim();
+            let force = false;
+            let focus;
+            if (rest === '--force')
+                force = true;
+            else if (rest.startsWith('--force ')) {
+                force = true;
+                focus = rest.slice('--force '.length).trim() || undefined;
+            }
+            else if (rest)
+                focus = rest;
+            // 走调度器路径:与自动每步压缩完全一致——五区按 ROI 压(cold tools 优先 → history 摘要最后)。
+            // focus 透传到 compact_history action 的 LLM 摘要 prompt。
+            // 返回 SchedulerRunLog 给 UI 显示决策;退化路径(开关关时)在 manualCompact 内部走 compactHistory。
+            const log = await manualCompact(history, focus, { force });
+            const d = log.compactDetail;
+            if (!d) {
+                // 兜底(旧调用):只显示 old 文案
+                if (!log.compactHistoryCalled) {
+                    layout.contentWrite(`${ui.dim}(无需压缩:没有可压缩的旧消息)${ui.reset}\n`);
+                }
+                else if (focus) {
+                    layout.contentWrite(`${ui.dim}(带焦点压缩:${focus})${ui.reset}\n`);
+                }
+                continue;
+            }
+            // 详细文案:按 reason 分类
+            const reason = d.reason;
+            const before = d.estimateBefore;
+            const after = d.estimateAfter;
+            const proto = d.protectedRatio !== undefined ? `保护区占比 ${(d.protectedRatio * 100).toFixed(0)}%` : '';
+            const oldCt = d.oldGroupCount !== undefined ? `旧区组数 ${d.oldGroupCount}` : '';
+            const focusNote = focus ? `焦点:${focus}` : '';
+            const stats = [proto, oldCt].filter(Boolean).join(' · ');
+            if (reason === 'microcompact') {
+                layout.contentWrite(`${ui.cyan}✓ 微压缩:${ui.reset} ${before} → ${after} tokens${stats ? `  (${ui.dim}${stats}${ui.reset})` : ''}\n`);
+            }
+            else if (reason === 'summarize') {
+                layout.contentWrite(`${ui.cyan}✓ LLM 摘要:${ui.reset} ${before} → ${after} tokens${focusNote ? `  (${ui.dim}${focusNote}${ui.reset})` : ''}\n`);
+            }
+            else if (reason === 'noop-empty') {
+                layout.contentWrite(`${ui.dim}(history 太短,只有 system 提示,无可压旧区)${ui.reset}\n`);
+            }
+            else if (reason === 'noop-protected') {
+                layout.contentWrite(`${ui.dim}(无可压旧区:全部在保护区 system + 当前轮)${ui.reset}${stats ? `  ${ui.dim}(${stats})${ui.reset}` : ''}\n`);
+                layout.contentWrite(`${ui.dim}提示:/compact --force 强行把早期对话压成摘要${ui.reset}\n`);
+            }
+            else if (reason === 'noop-ml-only') {
+                layout.contentWrite(`${ui.dim}(LLM 摘要失败,且无超大单条可微压;可能是后端不可用)${ui.reset}\n`);
+                layout.contentWrite(`${ui.dim}回退:只跑了 keep-current 结构,history 未变${ui.reset}\n`);
+            }
+            else if (reason === 'noop-shrunk-too-large') {
+                layout.contentWrite(`${ui.yellow}● 上下文已超阈但无可压缩项(全在保护区),建议 /clear 或缩短输入。${ui.reset}\n`);
+                if (stats)
+                    layout.contentWrite(`${ui.dim}(${stats})${ui.reset}\n`);
+            }
+            else if (reason === 'noop-noold-noop') {
+                layout.contentWrite(`${ui.dim}(无需压缩:没有可压缩的旧消息,且不在手动触发)${ui.reset}\n`);
+            }
+            else {
+                layout.contentWrite(`${ui.dim}(reason=${reason},${before} → ${after} tokens)${ui.reset}\n`);
             }
             continue;
         }
@@ -918,6 +990,7 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null,
             if (!loadSnapshots(loaded.id))
                 rebuildFromHistory(history);
             contextState.lastUsage = undefined;
+            lastTurnUsage = undefined; // /resume:旧会话的 token 累计已无意义,清空等下轮覆写
             layout.clearContent();
             renderHistory(history);
             layout.contentWrite(`${ui.dim}(已续接会话 ${loaded.id})${ui.reset}\n`);
@@ -1153,6 +1226,78 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null,
             await rollbackFlow();
             continue;
         }
+        if (line === '/memory_switch' ||
+            line.startsWith('/memory_switch ') ||
+            line === '/memory_status' ||
+            line.startsWith('/memory_status ')) {
+            // /memory_switch — 记忆子系统总开关。无参切换 on/off;/memory_switch on 或 /off 显式;
+            // /memory_switch true|false|1|0|yes|no 等同义。/memory_status 只读查询(不写盘)。
+            //
+            // 设计原则:
+            //  - 单一来源 isMemoryEnabled():工具表(builtins)、系统提示词(Memory Index 段 + 工具使用说明)、
+            //    plan-mode 提示(tools/constants.ts)三处都从这里查。
+            //  - 当前会话的 tool list 是模块初始化时的快照(/memory_switch 不重算 builtinTools)——已发出
+            //    请求的工具列表不会被回滚。要"完全生效"需要重启 REPL。但 buildSystemMessage 每次 chat 现拼,
+            //    所以系统提示词和 plan suffix 会在「下一轮 chat」即时反映新值。
+            //  - 持久化字段 MEMORY_ENABLED,默认值 false(新用户零侵入)。
+            try {
+                if (line === '/memory_status' || line.startsWith('/memory_status ')) {
+                    const on = isMemoryEnabled();
+                    layout.contentWrite(`${ui.cyan}记忆子系统:${ui.reset} ${on ? `${ui.green}开启` : `${ui.yellow}关闭`}${ui.reset}\n`);
+                    layout.contentWrite(`${ui.dim}  单一来源 isMemoryEnabled()(${config.memoryEnabled});` +
+                        `持久化 ${ui.cyan}MEMORY_ENABLED${ui.dim};` +
+                        `配置文件 ${CONFIG_PATH}${ui.reset}\n`);
+                    layout.contentWrite(`${ui.dim}  关闭时:memory_*_save/_search/_list/_update/_forget 五个工具整体不进工具表;` +
+                        `buildBasePrompt() 不含「## Memory」段;` +
+                        `plan-mode 提示词里也不出现 memory_* 工具名。${ui.reset}\n`);
+                    layout.contentWrite(`${ui.dim}  切换后下次新建 system message 即时反映;当前会话工具表需重启 REPL 才完整重算。${ui.reset}\n`);
+                    continue;
+                }
+                // /memory_switch(无参=on/off 切换;有参=按值设)
+                const arg = line.startsWith('/memory_switch ')
+                    ? line.slice('/memory_switch '.length).trim().toLowerCase()
+                    : '';
+                let nextEnabled;
+                if (arg === '') {
+                    nextEnabled = !isMemoryEnabled();
+                }
+                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}/memory_switch 用法:${ui.reset}\n` +
+                        `  /memory_switch             切换(开↔关)\n` +
+                        `  /memory_switch on|off      显式设值\n` +
+                        `  /memory_switch status      等同 /memory_status\n`);
+                    continue;
+                }
+                const prev = isMemoryEnabled();
+                if (nextEnabled === prev) {
+                    layout.contentWrite(`${ui.dim}(已是 ${nextEnabled ? '开启' : '关闭'},未变更 — 持久化字段未写入)${ui.reset}\n`);
+                    continue;
+                }
+                updateMemoryConfig(nextEnabled);
+                // 写盘:mode 文件 values,/~/.mocode/config;writeConfigKeys 不会动其它键(主题 / 模型等)
+                updateConfigKey('MEMORY_ENABLED', nextEnabled ? 'true' : 'false');
+                const note = nextEnabled
+                    ? `${ui.green}已开启记忆子系统${ui.reset} — memory_save/search/list/update/forget 进入工具表;` +
+                        `Memory Index 段会在下次拼 system message 时注入。工具表本身的快照需要重启 REPL 才完整刷新。`
+                    : `${ui.yellow}已关闭记忆子系统${ui.reset} — 五个 memory_* 工具将在下次拼 system message 时从工具表过滤;` +
+                        `Memory Index 段不再出现;plan-mode 提示词里的 memory_* 字样消失。重启 REPL 后工具表完全不出现。`;
+                layout.contentWrite(`${note}\n`);
+                layout.contentWrite(`${ui.dim}(写入 ${CONFIG_PATH}:MEMORY_ENABLED=${nextEnabled ? 'true' : 'false'};${ui.reset}` +
+                    (process.env.MEMORY_ENABLED
+                        ? `${ui.dim}同 session shell 未 export,文件写入即时生效)${ui.reset}\n`
+                        : `${ui.dim}下次启动仍生效)${ui.reset}\n`));
+            }
+            catch (e) {
+                layout.contentWrite(`${ui.red}/memory_switch 失败:${ui.reset} ${e.message}\n`);
+            }
+            continue;
+        }
         const initialPlan = getAgentMode() === 'plan'; // 轮首模式(在 runTurn 之前读)
         const ok = await runTurn(joined, initialPlan, placeholder);
         // plan 轮正常结束(未中断 / 未抛错)→ 看轮末模式决定: