mocode-ai 0.1.8 → 0.1.10

package/dist/repl/index.js

@@ -1,19 +1,18 @@
 import readline from 'node:readline/promises';
 import { emitKeypressEvents } from 'node:readline';
 import { stdin, stdout } from 'node:process';
-import { config, PLAN_MODE_SUFFIX } from '../config/index.js';
-import { updateConfigKey } from '../config/file.js';
+import { config, PLAN_MODE_SUFFIX, updateModelConfig, isModelConfigured } 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';
 import { setSandboxRoot } from '../sandbox/root.js';
 import { ui, setTheme, getTheme, listThemes, themeExists } from '../ui/theme.js';
 import { bannerString, displayWidth, padEndDisplay, summarizeToolCall, summarizeToolResult } from '../ui/render.js';
 import * as layout from '../ui/layout.js';
-import * as mouse from '../ui/mouse.js';
 import { promptWithSlashMenu, promptTurnPicker, promptSessionPicker, promptThemePicker, promptRevertChoice, } from '../ui/prompt.js';
 import { promptIntervention } from '../ui/intervention.js';
 import { tools } from '../tools/registry.js';
-import { estimateMessagesTokens, } from '../llm/index.js';
+import { estimateMessagesTokens, reconfigureClient, } from '../llm/index.js';
 import { compactHistory, 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';
@@ -36,6 +35,7 @@ const SLASH_COMMANDS = [
     { name: '/reflect', desc: '手动触发后台记忆反思 pass' },
     { name: '/init', desc: '扫描项目生成 MOCODE.md 项目记忆' },
     { name: '/theme', desc: '切换颜色主题(↑↓·Enter)' },
+    { name: '/model', desc: '配置大模型(baseURL/key/model/窗口)' },
     { name: '/plan', desc: '切到 plan 模式(只读探查+产出计划)' },
     { name: '/auto', desc: '切回 auto 模式(全工具执行)' },
 ];
@@ -47,6 +47,23 @@ const THEME_DESCRIPTIONS = {
     gruvbox: 'Gruvbox 暖色',
     nord: 'Nord 冷色',
 };
+/** /model 预设后端:选一个预填 baseURL,仍可逐项改。base_url 取自 README 常见表。 */
+const MODEL_PRESETS = [
+    { label: 'GLM(智谱)', baseURL: 'https://open.bigmodel.cn/api/v3', model: 'glm-4.6', window: 128000 },
+    { label: 'DeepSeek', baseURL: 'https://api.deepseek.com', model: 'deepseek-chat', window: 64000 },
+    { label: 'Qwen(阿里)', baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1', model: 'qwen-plus', window: 128000 },
+    { label: '本地 Ollama', baseURL: 'http://localhost:11434/v1', model: 'qwen2.5:7b', window: 32768 },
+    { label: '本地 vLLM', baseURL: 'http://localhost:8000/v1', model: 'default', window: 32768 },
+    { label: '自定义 base_url', baseURL: '', model: '', window: 128000 },
+];
+/** apiKey 脱敏:只露末 4 位,前面打星号(显示用,绝不把明文 key 写进内容区)。 */
+function maskKey(k) {
+    if (!k)
+        return '(未设置)';
+    if (k.length <= 8)
+        return '****';
+    return `${'='.repeat(Math.min(k.length - 4, 20))}${k.slice(-4)}`;
+}
 /**
  * /init 指令:发给 agent 扫描项目并生成 MOCODE.md(对标 Claude Code /init 生成 CLAUDE.md,
  * 但 mocode 读 MOCODE.md)。已存在则让 agent 读后更新(不丢失事实)。写完供 memory 子系统下轮加载。
@@ -95,7 +112,7 @@ function renderContextBar(history) {
     const pct = Math.min(1, est / win);
     const W = 10;
     const filled = Math.round(pct * W);
-    const bar = filled === 0 ? ' '.repeat(W) : '█'.repeat(filled) + '░'.repeat(W - filled);
+    const bar = '█'.repeat(filled) + '░'.repeat(W - filled);
     const src = contextState.lastUsage ? '实测' : '估算';
     const k = (n) => `${Math.round(n / 1000)}k`;
     const pctCol = pct >= config.compactThreshold ? ui.yellow : ui.cyan;
@@ -111,7 +128,7 @@ function renderContextBarInline(history) {
     const pct = Math.min(1, est / win);
     const W = 10;
     const filled = Math.round(pct * W);
-    const bar = filled === 0 ? ' '.repeat(W) : '█'.repeat(filled) + '░'.repeat(W - filled);
+    const bar = '█'.repeat(filled) + '░'.repeat(W - filled);
     const k = (n) => `${Math.round(n / 1000)}k`;
     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}`;
@@ -144,6 +161,8 @@ function runningStateFor(cmd) {
             return { status: '清空', placeholder: '…' };
         case '/theme':
             return { status: '切主题', placeholder: '选择主题…' };
+        case '/model':
+            return { status: '配模型', placeholder: '配置中…' };
         default:
             // 输入框留空(运行中可 typeahead 打字,dim 回显);运行状态由内联 spinner 承载(思考中/执行…),
             // 状态行只显走时——故常态 status 留空,不塞「处理」这种与内联重复的泛标签。
@@ -163,15 +182,8 @@ let pendingPrefill = null; // /rollback 选中后预填的 user 输入(下轮 IN
 function onRunningKey(_str, key) {
     if (!key)
         return;
-    // SGR 鼠标滚轮:readline 把 \x1B[<btn;col;rowM 拆成多 fragment,经 mouse.consumeMouse 重组;
-    // 滚轮 → scrollBy(±5)(不调 setUserActive——与键盘滚动一致;流式 flushTimer 在 scrollOffset>0 时不重画,安全)。
-    const _m = mouse.consumeMouse(key.sequence ?? '');
-    if (_m.suppress) {
-        if (_m.wheel)
-            layout.scrollBy(_m.wheel * 5);
-        return;
-    }
-    // 滚动回看键(优先;不触发回尾):PgUp/PgDn 翻页,↑/↓ 每次 5 行(键盘;鼠标滚轮已由上方守卫处理)。
+    // 滚动回看键(优先;不触发回尾):PgUp/PgDn 翻页,↑/↓ 每次 5 行(键盘 + alt 屏内鼠标滚轮转发的
+    // \x1B[A/\x1B[B,经 DECSET 1007 转发,与键盘 ↑/↓ 同序列,天然共用此分支)。
     // 运行态无输入光标,↑/↓ 无其他用途,直接作滚动。
     if (key.name === 'pageup' ||
         key.name === 'pagedown' ||
@@ -396,6 +408,10 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null,
         // 自更新提示:开场静态段(进 INPUT 态前),dim 一行,不与流式 / 输入争用。
         layout.contentWrite(`  ${ui.gray}↳ ${updateNotice}${ui.reset}\n`);
     }
+    if (!isModelConfigured()) {
+        // 未配置 baseURL/apiKey:醒目提示引导 /model(不退出,REPL 仍可用;发消息会失败但不崩)。
+        layout.contentWrite(`${ui.yellow}  ⚠ 未配置大模型。输入 ${ui.cyan}/model${ui.yellow} 配置 baseURL / apiKey / model(即时生效),或退出后运行 ${ui.cyan}mocode config${ui.yellow} 走向导。${ui.reset}\n`);
+    }
     layout.contentWrite(`${ui.dim}  /plan · /auto · Shift+Tab 切换模式(plan:只读探查 + 产出计划,审批后切 auto 执行)${ui.reset}\n`);
     /**
      * 切换 agent 模式(Shift+Tab 触发,经 prompt.ts 的 onCycleMode 回调)。
@@ -772,6 +788,179 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null,
             }
             continue;
         }
+        if (line === '/model' || line.startsWith('/model ')) {
+            // /model:运行时配置大模型(baseURL/apiKey/model/contextWindowTokens)。
+            // 即时生效(updateModelConfig 改内存 + env,reconfigureClient 重建 OpenAI 实例)+ 持久化(writeConfigKeys 写 ~/.mocode/config)。
+            // 仿 /theme:promptIntervention 弹菜单/输入 → 改 config → refreshStatusBase 刷底栏 → clearContent+banner 重显横幅 → dim 警告(shell env 覆盖)。
+            const arg = line.startsWith('/model ') ? line.slice('/model '.length).trim() : '';
+            // /model list:显示当前四项配置(apiKey 脱敏)。
+            if (arg === 'list' || arg === 'show') {
+                layout.contentWrite(`${ui.dim}当前模型配置:${ui.reset}\n`);
+                layout.contentWrite(`  ${ui.cyan}baseURL${ui.reset}  ${config.baseURL}\n`);
+                layout.contentWrite(`  ${ui.cyan}apiKey ${ui.reset}  ${maskKey(config.apiKey)}\n`);
+                layout.contentWrite(`  ${ui.cyan}model  ${ui.reset}  ${config.model}\n`);
+                layout.contentWrite(`  ${ui.cyan}窗口   ${ui.reset}  ${config.contextWindowTokens} tokens\n`);
+                layout.contentWrite(`${ui.dim}(配置文件: ${CONFIG_PATH})${ui.reset}\n`);
+                continue;
+            }
+            // 1) 选 provider 预设(预填 baseURL,后续仍可逐项改)。
+            let preset;
+            try {
+                const res = await promptIntervention({
+                    type: 'choice',
+                    title: '选择后端预设(预填 baseURL,后续可改)',
+                    detail: '选一个会预填 baseURL/model/窗口,之后逐项确认。选「自定义」全部手填。',
+                    options: MODEL_PRESETS.map((p) => p.label),
+                });
+                if (res.action === 'cancelled') {
+                    continue;
+                }
+                const idx = MODEL_PRESETS.findIndex((p) => p.label === res.value);
+                if (idx === -1) {
+                    continue;
+                }
+                preset = MODEL_PRESETS[idx];
+            }
+            catch {
+                continue; // Ctrl+C
+            }
+            // 1.5) 一键应用确认:非「自定义」预设(带预填值)给直接应用入口,免连按 4 次回车。
+            //      直接应用 = 用预设 model/baseURL/window + 保留当前 apiKey(等价于下方逐项链连按回车)。
+            //      逐项修改 / 自定义输入(promptIntervention choice 自动追加的「其他」项 submitted)→ 回落 4 步链。
+            //      「自定义」预设字段空,跳过确认直接进链。
+            let quickApply = false;
+            if (preset.model || preset.baseURL) {
+                try {
+                    const res = await promptIntervention({
+                        type: 'choice',
+                        title: `应用 ${preset.label}?`,
+                        detail: `model   ${preset.model}\nbaseURL ${preset.baseURL}\napiKey  ${maskKey(config.apiKey)}(直接应用=保留当前)\n窗口    ${preset.window}`,
+                        options: ['直接应用', '逐项修改'],
+                    });
+                    if (res.action === 'cancelled') {
+                        continue;
+                    }
+                    if (res.action === 'selected' && res.value === '直接应用') {
+                        quickApply = true;
+                    }
+                    // 其余(逐项修改 / 自定义输入 submitted)→ quickApply 保持 false,走下方逐项链
+                }
+                catch {
+                    continue; // Ctrl+C
+                }
+            }
+            // 2) 收集 baseURL / apiKey / model / contextWindowTokens。
+            //    quickApply:直接取预设值 + 当前 apiKey;否则逐项 input(预填 preset 值,回车=采纳;apiKey 不预填明文,回车=保留旧值)。
+            let baseURL;
+            let apiKey;
+            let model;
+            let window;
+            if (quickApply) {
+                baseURL = preset.baseURL;
+                apiKey = config.apiKey;
+                model = preset.model;
+                window = preset.window;
+            }
+            else {
+                // baseURL
+                {
+                    const res = await promptIntervention({
+                        type: 'input',
+                        title: 'LLM_BASE_URL',
+                        detail: 'OpenAI 兼容 API 端点。回车采纳预填值。',
+                        seed: preset.baseURL || config.baseURL,
+                    });
+                    if (res.action === 'cancelled') {
+                        continue;
+                    }
+                    baseURL = (res.value ?? '').trim() || preset.baseURL || config.baseURL;
+                }
+                if (!baseURL) {
+                    layout.contentWrite(`${ui.yellow}baseURL 不能为空,已取消。${ui.reset}\n`);
+                    continue;
+                }
+                // apiKey(不预填明文:回车=保留旧值,输入新值=覆盖)
+                {
+                    const res = await promptIntervention({
+                        type: 'input',
+                        title: 'LLM_API_KEY',
+                        detail: `回车保留当前 ${maskKey(config.apiKey)};输入新值则覆盖。`,
+                        seed: '',
+                    });
+                    if (res.action === 'cancelled') {
+                        continue;
+                    }
+                    const v = (res.value ?? '').trim();
+                    apiKey = v || config.apiKey;
+                }
+                if (!apiKey) {
+                    layout.contentWrite(`${ui.yellow}apiKey 不能为空,已取消。${ui.reset}\n`);
+                    continue;
+                }
+                // model
+                {
+                    const res = await promptIntervention({
+                        type: 'input',
+                        title: 'LLM_MODEL',
+                        detail: '模型名(须支持 function calling)。回车采纳预填值。',
+                        seed: preset.model || config.model,
+                    });
+                    if (res.action === 'cancelled') {
+                        continue;
+                    }
+                    model = (res.value ?? '').trim() || preset.model || config.model;
+                }
+                if (!model) {
+                    layout.contentWrite(`${ui.yellow}model 不能为空,已取消。${ui.reset}\n`);
+                    continue;
+                }
+                // contextWindowTokens
+                {
+                    const res = await promptIntervention({
+                        type: 'input',
+                        title: 'CONTEXT_WINDOW_TOKENS',
+                        detail: '模型上下文窗口(须对齐真实模型;GLM≈128k,DeepSeek-V3≈64k)。回车采纳预填值。',
+                        seed: String(preset.window || config.contextWindowTokens),
+                    });
+                    if (res.action === 'cancelled') {
+                        continue;
+                    }
+                    const v = (res.value ?? '').trim();
+                    const n = Number(v);
+                    if (!v || !Number.isFinite(n) || n <= 0) {
+                        // 非法输入:保留旧值,不阻断(用 preset.window 或当前值兜底)
+                        window = preset.window || config.contextWindowTokens;
+                    }
+                    else {
+                        window = Math.floor(n);
+                    }
+                }
+            }
+            // 3) 应用:内存 config + env(updateModelConfig)→ 持久化(writeConfigKeys)→ 重建 client(reconfigureClient)。
+            updateModelConfig({ model, baseURL, apiKey, contextWindowTokens: window });
+            writeConfigKeys({
+                LLM_BASE_URL: baseURL,
+                LLM_API_KEY: apiKey,
+                LLM_MODEL: model,
+                CONTEXT_WINDOW_TOKENS: String(window),
+            });
+            reconfigureClient();
+            // 4) 刷新 UI:底栏模型名 + 重显横幅(banner() 闭包实时读 config,自动反映新值)。
+            refreshStatusBase(history);
+            layout.clearContent();
+            if (history.some((m) => m.role === 'user')) {
+                renderHistory(history);
+            }
+            else {
+                layout.contentWrite(bannerString(banner()));
+            }
+            layout.contentWrite(`${ui.dim}(已切换模型 → ${model} @ ${baseURL})${ui.reset}\n`);
+            // 5) dim 警告:shell export 的 LLM 键下次启动会覆盖文件值。
+            if (config.llmKeysFromShell.length > 0) {
+                layout.contentWrite(`${ui.dim}(shell 环境变量已设 ${config.llmKeysFromShell.join(' / ')},文件写入下次启动被其覆盖;取消该 shell 设置后生效)${ui.reset}\n`);
+            }
+            continue;
+        }
         if (line === '/rollback' || line.startsWith('/rollback ')) {
             // /rollback:打开轮次菜单(↑/↓ 选,Enter 回滚到该轮并预填其输入,再 Enter 重新跑)。
             // 忽略任何数字参数(原「输数字选回滚」已删,统一走菜单)。无快照的旧轮次(/resume 重建)文件改动不可撤销。

package/dist/session/drop.js

@@ -0,0 +1,135 @@
+// 运行中上下文剔除(drop_context 工具的核心):把历史里无关的 tool 结果替换为存根。
+//
+// 与 compact 的区别:compact 是阈值触发的整体压缩(微截 + 摘要),drop_context 是 agent 主动、
+// 精准剔除"已判定无关"的具体 tool 结果——agent 检索到大量无关信息后主动调用,释放上下文。
+//
+// 不变量(对齐 compact.ts):
+//  - 永不动 history[0](system prompt)。
+//  - 永不动当前轮:从末尾向前找到最后一个 user 消息,该 user 及其之后的 tool 结果一律保留
+//    (agent 本轮还在用,踢了会丢失正在进行的上下文)。
+//  - tool_call_id 配对:只改 tool 消息的 content,不删消息、不动 tool_calls 数组结构、不改 id。
+//  - 原地修改 history(同 compact:length=0;push 重建,repl 持有同一引用)。
+//  - 永不抛错(对齐「调度器永不抛错」契约);无匹配 / 无可剔除 → 返 dropped=0。
+import { messageTokens, estimateTokens, } from '../llm/index.js';
+/** 把消息 content 拍平成字符串(OpenAI 可能 string / null / 多模态数组)。 */
+function toText(content) {
+    if (content == null)
+        return '';
+    if (typeof content === 'string')
+        return content;
+    try {
+        return JSON.stringify(content);
+    }
+    catch {
+        return String(content);
+    }
+}
+/**
+ * 从 history 末尾向前找最后一个 user 消息的索引;无 user 返 -1。
+ * 用于划定"当前轮保护区"——该 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 配对找)。 */
+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;
+}
+/**
+ * 剔除历史里命中的旧 tool 结果(原地修改 history)。
+ *
+ * 筛选(各维度 AND 组合):
+ *  - toolNames:只剔除这些工具名的结果(空 = 不限)
+ *  - contains:只剔除内容包含所有这些词(AND、大小写不敏感)的结果(空 = 不限)
+ *
+ * 保护:history[0](system)+ 当前轮(最后一个 user 及其之后)永不剔除。
+ * 已是存根的 tool 消息(含「已剔除」标记)不重复剔除(幂等)。
+ *
+ * 永不抛错;无匹配返 dropped=0。
+ */
+export function dropContextFromHistory(history, filter) {
+    const toolNames = filter.toolNames && filter.toolNames.length > 0
+        ? new Set(filter.toolNames)
+        : null;
+    const contains = filter.contains && filter.contains.length > 0
+        ? filter.contains.map((s) => s.toLowerCase())
+        : null;
+    // 当前轮保护区:最后一个 user 及其之后一律保留(agent 还在用)。
+    const guard = lastUserIndex(history);
+    // guard <= 0 表示无 user 或 user 就是 history[0](不会):整段历史都可剔除(除 history[0])。
+    const protectedFrom = guard > 0 ? guard : 0; // < protectedFrom 的才可剔除(即 [1, protectedFrom)
+    const items = [];
+    let freedTokens = 0;
+    const STUB_PREFIX = '⌦[已剔除:与当前任务无关]';
+    for (let i = 1; i < protectedFrom; i++) {
+        const m = history[i];
+        if (m.role !== 'tool')
+            continue;
+        const content = toText(m.content);
+        // 幂等:已是存根(含标记)不重复剔除。
+        if (content.startsWith(STUB_PREFIX))
+            continue;
+        // 维度 1:工具名
+        const tname = toolNameOf(history, i);
+        if (toolNames && (!tname || !toolNames.has(tname)))
+            continue;
+        // 维度 2:内容关键词(AND)
+        if (contains) {
+            const lower = content.toLowerCase();
+            if (!contains.every((kw) => lower.includes(kw)))
+                continue;
+        }
+        // 命中 → 替换为存根(保 tool_call_id 不动,只改 content)
+        const before = messageTokens(m);
+        const id = m.tool_call_id ?? '';
+        const stub = `${STUB_PREFIX} 原 ${tname ?? 'tool'} 结果(${content.length} 字符,约 ${before} tokens)${id ? ` · id …${id.slice(-6)}` : ''}⌫`;
+        m.content = stub;
+        const after = messageTokens(m);
+        freedTokens += Math.max(0, before - after);
+        items.push({
+            toolName: tname ?? 'tool',
+            toolCallId: id.slice(-6),
+        });
+    }
+    return {
+        dropped: items.length,
+        freedTokens,
+        items,
+    };
+}
+/** 给 drop_context 工具结果格式化人类可读摘要(回灌给 agent)。 */
+export function formatDropResult(r) {
+    if (r.dropped === 0) {
+        return '未剔除任何工具结果(无匹配的旧 tool 消息,或均在当前轮保护区内不可剔除)。';
+    }
+    const lines = [
+        `已剔除 ${r.dropped} 条无关工具结果,释放约 ${r.freedTokens} tokens。`,
+        '被剔除项(已替换为存根,tool_call_id 配对不变):',
+    ];
+    for (const it of r.items) {
+        lines.push(`  - ${it.toolName} (id …${it.toolCallId})`);
+    }
+    lines.push('这些结果在后续上下文中仅保留存根标记,不再占用篇幅。');
+    return lines.join('\n');
+}
+// 供 drop_context 工具估算用(避免直接 import llm 的公开 API 造成耦合,这里重导出)。
+export { estimateTokens };

package/dist/session/index.js

@@ -5,4 +5,5 @@
  * 依赖方向:session → {llm(摘要复用 chat), config, ui};llm 不反向依赖 session。
  */
 export { compactHistory, maybeCompact, capToolResultForHistory, truncateMid, contextState, } from './compact.js';
+export { dropContextFromHistory, formatDropResult, } from './drop.js';
 export { newSessionId, saveSession, loadSession, listSessions, sessionDir, } from './persist.js';

package/dist/tools/builtins/ask-human.js

@@ -3,10 +3,10 @@ import { promptIntervention } from '../../ui/intervention.js';
 export const askHumanTool = {
     name: 'ask_human',
     description: [
-        'Call this tool when you hit a decision point during a task that requires human input — it pops up a question panel in the terminal for the user to choose.',
-        'Use when: multiple implementation approaches need a user decision, user intent is unclear and needs clarification, or extra info is needed to proceed.',
-        'Blocks until the user responds; the user can pick a preset option or choose "custom input" to answer freely; the result is returned as the tool result.',
-        'Do not call frequently when the task is clear and you can decide yourself — it interrupts the user. When options is omitted or empty, it becomes free-text input instead.',
+        'Ask the user for input at a decision point (blocks until they respond).',
+        ' Use when: multiple approaches need a user decision, intent is unclear, or extra info is needed.',
+        ' Don\'t call when the task is clear and you can decide — it interrupts the user.',
+        ' Options (2-6) let the user pick; omit/empty for free-text input. Their answer is returned as the result.',
     ].join(''),
     parameters: {
         type: 'object',

package/dist/tools/builtins/codegraph.js

@@ -50,9 +50,11 @@ function runCodegraph(args) {
 }
 export const codegraphTool = {
     name: 'codegraph',
-    description: 'Preferred tool for understanding/locating code, tracing call chains, and assessing the impact of changes in repos with a code index (.codegraph/).' +
-        ' Returns relevant symbol source + call paths in one shot — more accurate and economical than piecing together via read_file/grep.' +
-        ' Returns a hint when .codegraph/ is absent (build it first with `codegraph init`).',
+    description: 'FIRST CHOICE for understanding/locating code, tracing call chains, or assessing the impact of changes — use this before read_file/grep when a .codegraph/ index exists.' +
+        ' Returns symbol source + call paths in one shot — more accurate and economical than piecing together read_file/grep.' +
+        ' When to use: starting any code exploration; locating a symbol; understanding how a feature works; seeing what calls a function or what a change affects.' +
+        ' When NOT to use: no .codegraph/ index (build it first with `codegraph init`); reading a file you just edited; editing a single known small file — in those cases go straight to read_file/edit_file.' +
+        ' Fallback: if codegraph misses or the result is incomplete, then use read_file/grep/glob to fill the gaps.',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/drop-context.js

@@ -0,0 +1,68 @@
+// ---------- drop_context ----------
+/**
+ * 运行中上下文剔除工具:agent 检索到大量无关信息后,主动把历史里无关的 tool 结果替换为存根,
+ * 释放上下文空间(保 tool_call_id 配对不变量,只改 content)。
+ *
+ * 与 compact 的区别:compact 是阈值触发的整体压缩(微截 + 摘要);drop_context 是 agent 主动、
+ * 精准剔除"已判定无关"的具体 tool 结果。
+ *
+ * 保护:history[0](system)与当前轮(最后一个 user 及其之后)永不剔除——agent 还在用。
+ * 已是存根的不重复剔除(幂等)。永不抛错。
+ *
+ * 筛选(各维度 AND 组合,全部可选;不传 = 剔除所有可剔除的旧 tool 结果):
+ *  - toolNames:只剔除这些工具名的结果(如 ["grep","read_file"])
+ *  - contains:只剔除内容包含所有这些词(AND、大小写不敏感)的结果
+ *
+ * plan 模式不禁用:纯上下文管理,无文件 / 命令副作用。
+ */
+export const dropContextTool = {
+    name: 'drop_context',
+    description: [
+        'Drop (stub-replace) irrelevant OLDER tool results from history to free context.',
+        'COST-AWARE: ~300-token round-trip; only call if freed tokens clearly exceed it — i.e. MULTIPLE bulky results (e.g. a wide grep/read sweep of mostly-irrelevant hits), not a single small one or near done.',
+        'Never dropped: system prompt and the CURRENT turn (last user message onward). Idempotent. Filters AND-combine; omit both = drop all droppable. Returns dropped count, freed tokens, tool names.',
+    ].join(' '),
+    parameters: {
+        type: 'object',
+        properties: {
+            toolNames: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Only drop results from these tool names (e.g. ["grep","read_file"]). Empty/omitted = no tool-name filter.',
+            },
+            contains: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Only drop results whose content contains ALL of these keywords (AND, case-insensitive). Empty/omitted = no content filter.',
+            },
+        },
+        required: [],
+    },
+    async execute(args, ctx) {
+        const dropContext = ctx?.dropContext;
+        if (!dropContext) {
+            // 无注入(理论上不会:runAgentCore 总注入)。降级:不改 history,告知 agent。
+            return '错误:上下文剔除回调不可用(未由 agent 循环注入),无法剔除。';
+        }
+        const filter = {};
+        if (Array.isArray(args.toolNames)) {
+            filter.toolNames = args.toolNames
+                .filter((v) => typeof v === 'string' && v.length > 0)
+                .map((v) => String(v));
+        }
+        if (Array.isArray(args.contains)) {
+            filter.contains = args.contains
+                .filter((v) => typeof v === 'string' && v.length > 0)
+                .map((v) => String(v));
+        }
+        const result = dropContext(filter);
+        return result.dropped === 0
+            ? '未剔除任何工具结果(无匹配的旧 tool 消息,或均在当前轮保护区内不可剔除)。'
+            : [
+                `已剔除 ${result.dropped} 条无关工具结果,释放约 ${result.freedTokens} tokens。`,
+                '被剔除项(已替换为存根,tool_call_id 配对不变):',
+                ...result.items.map((it) => `  - ${it.toolName} (id …${it.toolCallId})`),
+                '这些结果在后续上下文中仅保留存根标记,不再占用篇幅。',
+            ].join('\n');
+    },
+};

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

@@ -3,7 +3,7 @@ import { resolve } from 'node:path';
 // ---------- edit_file ----------
 export const editFileTool = {
     name: 'edit_file',
-    description: 'Make a precise string replacement in a file. old_string must occur exactly once in the file and match exactly (including indentation/newlines). Use write_file for new files.',
+    description: 'Replace a string in a file. old_string must occur exactly once and match exactly (including indentation/newlines). Use write_file for new files.',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/glob.js

@@ -4,8 +4,8 @@ import { getSandboxRoot, isInsideRoot } from '../../sandbox/index.js';
 // ---------- glob ----------
 export const globTool = {
     name: 'glob',
-    description: 'Find file paths matching a glob pattern (e.g. **/*.ts). Returns a list of matches (auto-excludes node_modules / .git).' +
-        ' Note: when understanding code architecture/call chains, if a .codegraph/ index exists, prefer the codegraph tool over piecing together via glob one file at a time.',
+    description: 'Find files matching a glob pattern (e.g. **/*.ts). Auto-excludes node_modules/.git.' +
+        ' For architecture/call chains, prefer codegraph.',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/grep.js

@@ -5,8 +5,8 @@ import { getSandboxRoot, isInsideRoot, jailResolve } from '../../sandbox/index.j
 // ---------- grep ----------
 export const grepTool = {
     name: 'grep',
-    description: 'Search file contents by regex, returning file:line: matched lines. Recursively searches the current directory by default (excluding node_modules/.git). Optional glob to restrict file types.' +
-        ' Note: when understanding code architecture/call chains, if a .codegraph/ index exists, prefer the codegraph tool over piecing together via grep one file at a time.',
+    description: 'Search file contents by regex, returning file:line: matched lines. Recursively searches cwd excluding node_modules/.git. Optional glob restricts file types.' +
+        ' For architecture/call chains, prefer codegraph.',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/index.js

@@ -10,6 +10,7 @@ import { useSkillTool } from './use-skill.js';
 import { askHumanTool } from './ask-human.js';
 import { codegraphTool } from './codegraph.js';
 import { switchModeTool } from './switch-mode.js';
+import { dropContextTool } from './drop-context.js';
 import { memorySaveTool } from './memory-save.js';
 import { memorySearchTool } from './memory-search.js';
 import { memoryListTool } from './memory-list.js';
@@ -33,6 +34,7 @@ export const builtinTools = [
     useSkillTool,
     askHumanTool,
     switchModeTool, // plan↔auto 自切(两模式都可见,不进 PLAN_DISABLED_TOOLS;副作用控制工具→串行分支)
+    dropContextTool, // 运行中剔除无关 tool 结果(上下文管理,无副作用;两模式都可见,串行分支)
     memorySaveTool,
     memorySearchTool,
     memoryListTool,

package/dist/tools/builtins/memory-forget.js

@@ -3,7 +3,7 @@ import { forgetEntry } from '../../memory/store.js';
 // 遗忘:默认归档(archived,从索引/默认搜索隐藏,可复活);mode=delete 硬删。pinned 拒删。
 export const memoryForgetTool = {
     name: 'memory_forget',
-    description: 'Forget a memory entry: by default archives (archived, hidden from index and default search, can be revived via memory_update); mode=delete hard-deletes. Pinned entries cannot be deleted (first memory_update pinned=false to unpin).',
+    description: 'Forget a memory entry: default archive (hidden, revivable via memory_update); mode=delete hard-deletes. Pinned entries can\'t be deleted (unpin first).',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/memory-list.js

@@ -3,7 +3,7 @@ import { listEntries } from '../../memory/store.js';
 // 列索引(id/name/summary,无正文、不 bump recall)。用于浏览有哪些、拿 id 再 memory_search 取正文。
 export const memoryListTool = {
     name: 'memory_list',
-    description: 'List the memory index (id/name/summary, no body). Defaults to active. Get an id, then use memory_search to retrieve the full body.',
+    description: 'List the memory index (id/name/summary, no body). Get an id, then use memory_search for the full body.',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/memory-save.js

@@ -4,7 +4,7 @@ import { saveEntry } from '../../memory/store.js';
 // 撞库(name→id 已存在)拒绝,引导用 memory_update。
 export const memorySaveTool = {
     name: 'memory_save',
-    description: 'Save a long-term memory entry (cross-session). Store only non-obvious, long-term-useful facts/decisions/pitfalls. The title goes into the startup index; retrieve full body on demand via memory_search.',
+    description: 'Save a cross-session long-term memory entry. Store only non-obvious, useful facts/decisions/pitfalls. Title enters the startup index; retrieve body via memory_search.',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/memory-search.js

@@ -4,7 +4,7 @@ import { searchEntries } from '../../memory/store.js';
 // 结果走 capToolResultForHistory 的放宽上限(同 use_skill,保正文完整)。
 export const memorySearchTool = {
     name: 'memory_search',
-    description: 'Search memory entries by keyword (multi-word substring match, ranked by relevance), returning full body of matching entries. A hit bumps recall count (affects forgetting decay).',
+    description: 'Search memory entries by keyword (substring match), returning full body.',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/memory-update.js

@@ -3,7 +3,7 @@ import { updateEntry } from '../../memory/store.js';
 // 原地改一条记忆(id 不变)。反思的弱意义:干活时发现事实变了/过时即纠正。
 export const memoryUpdateTool = {
     name: 'memory_update',
-    description: 'Update a memory entry in place (id unchanged). Use when facts changed / correcting outdated info / updating summary or body / toggling pinned. Get id from memory_list or memory_search.',
+    description: 'Update a memory entry in place (id unchanged). Use when facts changed / correcting outdated info / toggling pinned. Get id from memory_list or memory_search.',
     parameters: {
         type: 'object',
         properties: {