mocode-ai 0.1.7 → 0.1.9

package/README.md

@@ -2,21 +2,30 @@
 
 # mocode
 
-一个终端编码 agent:**LLM + tool-call 循环 + 流式输出 + 思考可见**。
+一个终端编码 agent:你给一个目标,它**自主完成**——不需要你逐步指挥。
 
-接任意 OpenAI 兼容接口(GLM、DeepSeek、Qwen、本地 Ollama / vLLM 等),全屏 TUI 交互式 REPL。agent 自主探索代码、读写文件、执行命令、联网搜索,以「思考 → 调用工具 → 观察结果 → 再思考」的循环完成编程任务。
+mocode 自己探索代码、读写改文件、执行命令、联网查资料,以「思考 → 调用工具 → 观察结果 → 再思考」的循环一步步把任务推进到完成。接任意 OpenAI 兼容接口(GLM、DeepSeek、Qwen、本地 Ollama / vLLM 等),全屏 TUI 交互,流式输出、思考过程可见。
+
+## 为什么用 mocode
+
+mocode 不是一个套壳聊天框,而是一个能真正动手干活的 agent:
+
+- **自主多步推进** — 一次对话里连续多步:读代码、改代码、跑测试、根据报错再改……agent 自己决定下一步,中途不用你反复催。遇到卡点会调 `ask_human` 弹面板问你(阻塞到回应)。
+- **只读工具并行执行** — 一轮里连续的只读操作(读文件、grep、glob、codegraph、联网搜索/抓取)自动并发跑,总耗时 ≈ 最慢一个,而不是逐个排队。写文件 / 改文件这类有副作用的操作仍串行,保快照顺序与数据安全。
+- **子 agent 分而治之** — 复杂任务可派生独立子 agent:各自有自己的对话历史(不污染主线),可限定只读工具集和步数上限,并行探查多片代码 / 多个方向,最后只把摘要回灌主线。主线据此决定下一步。
+- **计划 / 执行双模式** — `plan` 模式下只读探查(读代码、查索引、搜索,绝不写盘、不跑命令、不派生子 agent),产出计划;`auto` 模式全量工具放开。agent 还能在两者间自切换——先把陌生代码库摸清,再动手改。
+- **上下文自动压缩** — 接近窗口上限时三层压缩(单条结果裁剪 → 旧工具结果原地微压缩 → 旧对话摘要),长会话也不爆窗口;`/context` 实时显示 token 用量,`/compact` 可手动压缩(能带焦点指令聚焦保留)。
+- **跨会话长期记忆** — agent 能把项目架构、约定、踩过的坑存成长期记忆,下次会话自动加载;后台还会定期从对话里反思挖掘值得记住的事。记忆可增删改、带召回衰减。
+- **可中断、可回滚** — Ctrl+C 随时打断当前轮次(树杀子进程,历史还原到本轮开始前,不留残半的工具调用);`/rollback` 按轮次快照恢复文件改动,逐个文件「保留/撤销」,不依赖 git。
+- **沙箱防护** — 文件读写经沙箱拦截,挡掉越界路径(`../../`、绝对外圈、软链出圈等),不碰工作目录之外的文件。
 
 ## 特性
 
-- **流式输出** — 回复边生成边显示,模型支持 reasoning 时思考过程实时可见,思考段自动折叠(不占屏),`/think N` 按需展开
+- **流式输出 + 思考可见** — 回复边生成边显示;模型支持 reasoning 时思考过程实时可见,思考段自动折叠(不占屏),`/think N` 按需展开
 - **全屏 TUI** — 备用屏(alt screen)+ 固定底栏状态行 + 滚动回看(PgUp/PgDn),运行中可打字(typeahead),下一轮自动预填
-- **16 个内置工具** — 读 / 写 / 改文件、执行命令、glob 找路径、grep 搜内容、codegraph 代码索引、联网搜索、抓取网页、加载 skill、询问用户、5 个跨会话记忆工具(存/搜/列/改/遗忘)
 - **会话持久化** — 每轮自动落盘,`--resume` / `/resume` 续接历史会话
-- **轮次回滚** — `/rollback` 菜单选轮次,删该轮及之后 + 逐个文件「保留/撤销」(快照恢复,不依赖 git)
-- **上下文工程** — 接近窗口上限时自动三层压缩,`/context` 实时显示 token 用量条,`/compact` 手动压缩(可带焦点)
-- **Skills 系统** — 自动扫描 `~/.mocode/skills/` 等目录,description 注入系统提示,模型按需调 `use_skill` 加载完整指令
+- **Skills 系统** — 自动扫描 `~/.mocode/skills/` 等目录,description 注入系统提示,模型按需调 `use_skill` 加载完整指令(渐进式披露:先看简介,任务相关才加载正文)
 - **斜杠命令** — `/exit` `/clear` `/context` `/skills` `/compact` `/resume` `/think` `/rollback`,输入时下拉过滤
-- **Ctrl+C 中断** — 运行中随时中断当前 agent 轮次(不退进程)
 
 ## 安装
 
@@ -49,6 +58,8 @@ npm start
 mocode config
 ```
 
+也可直接 `mocode` 进入 REPL 后用 `/model` 命令配置(交互选后端预设 + 逐项填写,即时生效 + 持久化)。未配置时 REPL 仍能打开,会提示你跑 `/model`。
+
 也可手写配置文件。mocode 按以下优先级加载(后者覆盖前者,仅回填未设置的环境变量;shell 里 `export` 的永远最优先):
 
 1. `~/.mocode/config` — 全局(`mocode config` 写此文件)
@@ -120,6 +131,8 @@ agent 工作在**启动时所在的工作目录**——想让它操作某个项
 | `web_fetch` | 抓取指定 URL,HTML 清洗成纯文本 |
 | `use_skill` | 加载某 skill 的完整 SKILL.md 指令 |
 | `ask_human` | 决策点弹终端问答面板,用户选预设项或自由输入(阻塞至回应) |
+| `switch_mode` | 在 `plan`(只读规划)与 `auto`(全量执行)间切换;agent 可自行调用,先探查再动手 |
+| `task` | 派生子 agent 执行独立子任务(独立历史、可受限工具集、可设步数上限);连续多个自动并行,只回摘要 |
 | `memory_save` | 存一条跨会话长期记忆(标题进索引,正文按需取) |
 | `memory_search` | 按关键词搜记忆正文,命中即提升召回计数(影响遗忘衰减) |
 | `memory_list` | 列记忆索引(id/标题/摘要,无正文) |
@@ -138,6 +151,7 @@ agent 工作在**启动时所在的工作目录**——想让它操作某个项
 | `/resume` | 续接已保存的会话 |
 | `/think` | 展开折叠思考段(`/think N`) |
 | `/rollback` | 菜单选轮次回滚(↑↓ · Enter) |
+| `/model` | 配置大模型(baseURL / apiKey / model / 上下文窗口),即时生效 + 持久化 |
 
 输入 `/` 触发下拉菜单,继续打字过滤;Esc 取消。
 
@@ -165,26 +179,6 @@ mocode 自动扫描以下目录的 skill(每个 skill 是 `<name>/SKILL.md`,带
 
 skill 的 `description` 注入系统提示(渐进式披露第①层),模型只在任务相关时调 `use_skill` 加载完整正文(第②层)。用 `/skills` 查看已发现的 skill。
 
-## 结构
-
-```
-src/
-├── index.ts              # 入口:装配 + 启动 REPL + --resume 续接
-├── repl/index.ts         # 全屏 TUI、斜杠命令、运行态交互、Ctrl+C 中断
-├── agent/index.ts        # tool-call 循环(调 LLM→执行工具→回灌→再调,≤200 步)
-├── llm/index.ts          # OpenAI 兼容客户端 + 工具格式转换 + chat() 流式
-├── tools/                # types / constants / registry + builtins/(一工具一文件)
-│   └── builtins/         # read-file write-file edit-file run-command glob grep
-│                          # codegraph web-search web-fetch use-skill ask-human memory-*
-├── config/index.ts       # 读配置、校验必填项、系统提示词
-├── skills/               # discover(扫描)+ index(缓存/拼系统提示)
-├── session/              # 落盘/续接 + compact(三层压缩)+ token 估算
-├── memory/               # MOCODE.md 加载 + 跨会话记忆存储 + 后台反思
-├── rollback/             # 轮次快照 + /rollback 菜单 + 文件撤销
-├── ui/                   # theme(颜色)render(横幅/摘要)layout(全屏布局)spinner prompt
-└── agents/ commands/ mcp/ permissions/   # 未来子系统(agents/mcp/permissions 为空骨架)
-```
-
 ## 类型检查
 
 ```bash

package/dist/agent/core.js

@@ -9,7 +9,8 @@ import { chat, planChatTools, } from '../llm/index.js';
 import { executeTool } from '../tools/registry.js';
 import { PLAN_DISABLED_TOOLS } from '../tools/constants.js';
 import { getAgentMode, setAgentMode } from './mode.js';
-import { maybeCompact, capToolResultForHistory, contextState, } from '../session/index.js';
+import { maybeCompact, contextState, dropContextFromHistory } from '../session/index.js';
+import { optimizeToolResult } from '../context/index.js';
 import { config } from '../config/index.js';
 import { jailResolve } from '../sandbox/index.js';
 /** 解析工具 arguments JSON;非法或空返 null(调用方据此降级到普通 preview)。 */
@@ -67,12 +68,16 @@ function readDiffContext(tc, parsed) {
     }
     return { preWriteOld: null, editStartLine: 1 };
 }
-/** 回灌 tool 结果到 history(裁到单条上限);tool_call_id 与 assistant.tool_calls 按序配对。 */
+/** 回灌 tool 结果到 history:经 Context Optimization Pipeline 编码(tree/search/log/...)后裁到单条上限。
+ *  tool_call_id 与 assistant.tool_calls 按序配对。未注册 encoder 时回落 capToolResultForHistory(零行为变化)。
+ *  TUI 渲染(hooks.onToolResult)用原始 output,与此解耦——屏上看全量,LLM 看编码后紧凑版。 */
 function pushToolResult(history, tc, output) {
     history.push({
         role: 'tool',
         tool_call_id: tc.id,
-        content: capToolResultForHistory(tc.name, output),
+        // optimizeToolResult:classifier 选 encoder → encode(保不变量压缩)→ capToolResultForHistory 兜底。
+        // tc.arguments 透传给 encoder(上下文感知编码,如 read_file 的 offset/limit)。永不抛错。
+        content: optimizeToolResult(tc.name, output, tc.arguments),
     });
 }
 /**
@@ -80,7 +85,7 @@ function pushToolResult(history, tc, output) {
  *  流式调 LLM(经 hooks.onText 实时渲染)→ 有 tool_calls 就分组执行并回灌
  *  → 否则流式正文即最终回复。history 在调用间持久,由调用方持有。
  *  步前经 session/maybeCompact 自动压缩(接近窗口上限时三层压缩);
- *  工具结果进 history 前经 capToolResultForHistory 裁到单条上限。
+ *  工具结果进 history 前经 Context Optimization Pipeline(optimizeToolResult:类型化编码 + 长度裁剪)。
  *
  *  中断语义:signal 经 executeTool(name, args, signal) 串进工具;run_command/web_fetch 等 abort 即时杀
  *  (树杀子进程 / 取消 fetch),循环顶 if(signal.aborted) 兜底还原。不会留下未配对的 tool_call_id。
@@ -102,6 +107,10 @@ export async function runAgentCore(opts) {
     const t0 = Date.now();
     let done = false; // 正常完毕 / 达上限 true;中断 false(不显摘要)
     history.push({ role: 'user', content: userInput });
+    // drop_context 工具的上下文剔除回调:闭包捕获 history,原地剔除无关旧 tool 结果。
+    // 保护由 dropContextFromHistory 内部保证:history[0](system)+ 当前轮(最后 user 及其后)永不剔除。
+    // 子 agent 也在自己的 history 上操作(子 agent 独立 history);skipRollback 不影响此行为。
+    const dropContext = (filter) => dropContextFromHistory(history, filter);
     // 本轮流式状态:首个正文 token 到达即停 spinner(思考期间 spinner 持续转「思考中…」,不写思考内容)。
     let mode = 'idle';
     let gotText = false;
@@ -197,7 +206,7 @@ export async function runAgentCore(opts) {
                         while (j < calls.length && READ_TOOL_NAMES.has(calls[j].name))
                             j++;
                         const batch = calls.slice(i, j);
-                        const started = batch.map((tc) => executeTool(tc.name, tc.arguments, signal, { skipRollback }));
+                        const started = batch.map((tc) => executeTool(tc.name, tc.arguments, signal, { skipRollback, dropContext }));
                         for (let k = 0; k < batch.length; k++) {
                             const tc = batch[k];
                             hooks.onToolHeader?.(tc);
@@ -233,7 +242,7 @@ export async function runAgentCore(opts) {
                         while (j < calls.length && calls[j].name === 'task')
                             j++;
                         const batch = calls.slice(i, j);
-                        const started = batch.map((tc) => executeTool(tc.name, tc.arguments, signal, { skipRollback }));
+                        const started = batch.map((tc) => executeTool(tc.name, tc.arguments, signal, { skipRollback, dropContext }));
                         // 先批量打印所有头 + 启 spinner(多 task 并发,spinner 只显一个,但 ● 头都打出来)
                         for (const tc of batch) {
                             hooks.onToolHeader?.(tc);
@@ -268,7 +277,7 @@ export async function runAgentCore(opts) {
                             : null;
                         const { preWriteOld, editStartLine } = readDiffContext(tc, parsed);
                         hooks.onToolStart?.(tc.name);
-                        const output = await executeTool(tc.name, tc.arguments, signal, { skipRollback });
+                        const output = await executeTool(tc.name, tc.arguments, signal, { skipRollback, dropContext });
                         hooks.onToolDone?.();
                         hooks.onToolResult?.(tc, output, parsed, preWriteOld, editStartLine);
                         pushToolResult(history, tc, output);

package/dist/commands/config.js

@@ -9,7 +9,7 @@ function ask(rl, q) {
  * 首跑配置向导:交互填 LLM_BASE_URL / LLM_API_KEY / LLM_MODEL,写 ~/.mocode/config。
  * 只交互三键、保留文件里其它键(MAX_TOKENS / CONTEXT_WINDOW_TOKENS / MOCODE_THEME 等)。
  * prompt 全纯文本(readline 光标按字符算,不能含 ANSI)。
- * 由 index.ts 在 `mocode config` 时动态加载,故不 import config/index.ts(避免缺配置时 requireEnv
+ * 由 index.ts 在 `mocode config` 时动态加载,故不 import config/index.ts(避免触发 config 单例初始化 / loadEnvFiles,
  * 直接退出);只 import config/file.ts(纯 I/O 叶子,无 env 校验 / process.exit)。
  */
 export async function runConfigWizard() {

package/dist/config/file.js

@@ -5,7 +5,7 @@ import dotenv from 'dotenv';
 /**
  * ~/.mocode/config 全局 dotenv 配置的读写叶子(纯 node:fs / node:os / node:path + dotenv)。
  *
- * 独立于 `config/index.ts`——**不**触发 requireEnv / process.exit,故 `commands/config.ts`
+ * 独立于 `config/index.ts`——**不**触发 config 单例初始化 / loadEnvFiles,故 `commands/config.ts`
  * (首跑向导,刻意不 import config/index.ts)与 `repl/index.ts`(`/theme` 持久化)都能安全共享。
  * 主题等 UI 偏好走 `updateConfigKey` 单键写;向导多键一次性写走 `writeConfigKeys`。
  */

package/dist/config/index.js

@@ -30,14 +30,26 @@ function loadEnvFiles() {
 }
 // 在 loadEnvFiles 回填前捕获:MOCODE_THEME 是否由 shell 设置(决定 /theme 写文件是否下次启动生效)。
 const themeFromShell = process.env.MOCODE_THEME !== undefined;
+// 在 loadEnvFiles 回填前捕获:哪些 LLM 键由 shell 设置(决定 /model 写文件是否下次启动生效)。
+// 仿 themeFromShell 模式:shell export 的环境变量在 loadEnvFiles 中不被回填(优先级最高),
+// 故 /model 写入 ~/.mocode/config 的同名键下次启动会被 shell 值覆盖——据此给 dim 警告。
+const LLM_ENV_KEYS = ['LLM_BASE_URL', 'LLM_API_KEY', 'LLM_MODEL', 'CONTEXT_WINDOW_TOKENS'];
+const llmKeysFromShell = LLM_ENV_KEYS.filter((k) => process.env[k] !== undefined);
 loadEnvFiles();
+/**
+ * 取环境变量;缺则返回空字符串(不退出)。
+ * 历史上缺 LLM_BASE_URL/LLM_API_KEY 会 process.exit(1),但 /model 命令已能在 REPL 内配置模型,
+ * 故首次未配置也应让 REPL 起来,由开场提示引导用户跑 /model。发消息时 chat() 会抛错被 runTurn catch,不崩。
+ */
 function requireEnv(key) {
-    const v = process.env[key];
-    if (!v) {
-        console.error(`\n[config] 缺少 ${key}。运行 \`mocode config\` 初始化,或在 ~/.mocode/config / <cwd>/.env 中设置(参考 .env.example)。\n`);
-        process.exit(1);
-    }
-    return v;
+    return process.env[key] || '';
+}
+/**
+ * 模型是否已配置(baseURL + apiKey 非空)。REPL 开场据此决定是否提示 /model。
+ * 未配置时 config.model 仍回退 'gpt-4o-mini',但发消息会因 baseURL/apiKey 空而失败——由 runTurn catch 友好提示。
+ */
+export function isModelConfigured() {
+    return !!config.baseURL && !!config.apiKey;
 }
 const PLATFORM_NOTE = (() => {
     if (process.platform === 'win32') {
@@ -76,6 +88,7 @@ ${PLATFORM_NOTE}
 - 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).
 - Call ask_human when you hit a decision point requiring user input (multiple implementation approaches, unclear intent, or needing extra info to proceed) — list options for the user to pick (they can also choose "custom input" to answer freely). Don't call it frequently when the task is clear and you can decide yourself; if the user cancels, switch approach or proceed with available info — don't re-ask the same question.
+- **Drop irrelevant context** (use sparingly): call drop_context to stub-replace tool results in history that are BOTH (a) irrelevant to the current task AND (b) large (the freed tokens must clearly exceed the ~300 tokens the call itself costs — roughly only worth it when targeting ≥2 bulky results, e.g. wide grep/read sweeps that returned mostly-irrelevant hits). The call itself adds a tool-call round-trip, so don't call it for one small result or when you're near done. It preserves tool_call_id pairing (only content changes); the system prompt and current turn are never dropped. Use filters (toolNames / contains) to target precisely.
 
 ## Failure Handling
 - Tools return errors as strings (edit_file no match or non-unique, run_command non-zero exit, etc.). Analyze the root cause, adjust, then retry — don't resend the same call verbatim.
@@ -111,7 +124,7 @@ You are in PLAN mode: investigate and design only — do NOT execute or change a
 - Research thoroughly: locate the relevant code, trace call paths, and understand existing patterns and conventions before designing. Prefer codegraph when a .codegraph/ index exists.
 - 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; the user will approve via a prompt and execution happens in a follow-up turn.`;
+- 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 const config = {
     baseURL: requireEnv('LLM_BASE_URL'),
     apiKey: requireEnv('LLM_API_KEY'),
@@ -122,6 +135,7 @@ export const config = {
     compactThreshold: Number(process.env.COMPACT_THRESHOLD) || 0.85,
     includeUsage: process.env.LLM_STREAM_USAGE !== 'false',
     autoCompact: process.env.AUTO_COMPACT !== 'false',
+    contextOptimize: process.env.MOCODE_CONTEXT_OPTIMIZE !== 'false',
     autoReflect: process.env.AUTO_REFLECT !== 'false',
     reflectEveryN: Number(process.env.REFLECT_EVERY_N) || 5,
     maxSteps: Number(process.env.MAX_STEPS) || 200,
@@ -132,4 +146,31 @@ export const config = {
     searchBaseUrl: process.env.ANYSEARCH_BASE_URL || 'https://api.anysearch.com',
     theme: process.env.MOCODE_THEME || 'default',
     themeFromShell,
+    llmKeysFromShell,
 };
+/**
+ * 运行时更新模型相关配置(/model 命令调)。
+ * - 更新 config 对象字段(即时生效:chat() 读 config.model,reconfigureClient 读 config.baseURL/apiKey)。
+ * - 同步 process.env(保持内存一致:其他读 process.env 的路径也拿到新值;且使新值在下次启动的
+ *   loadEnvFiles 中被视为"已设",不被文件回填覆盖——即"优先拿这里的")。
+ * 持久化(写 ~/.mocode/config)由调用方走 writeConfigKeys,此处只管内存 + env。
+ * 重建 OpenAI 客户端(baseURL/apiKey 是构造时固化的实例字段)由调用方走 reconfigureClient。
+ */
+export function updateModelConfig(opts) {
+    if (opts.model !== undefined) {
+        config.model = opts.model;
+        process.env.LLM_MODEL = opts.model;
+    }
+    if (opts.baseURL !== undefined) {
+        config.baseURL = opts.baseURL;
+        process.env.LLM_BASE_URL = opts.baseURL;
+    }
+    if (opts.apiKey !== undefined) {
+        config.apiKey = opts.apiKey;
+        process.env.LLM_API_KEY = opts.apiKey;
+    }
+    if (opts.contextWindowTokens !== undefined) {
+        config.contextWindowTokens = opts.contextWindowTokens;
+        process.env.CONTEXT_WINDOW_TOKENS = String(opts.contextWindowTokens);
+    }
+}

package/dist/context/classifier.js

@@ -7,7 +7,7 @@
 //
 // 单一事实源风格(仿 tools/constants.ts 的 READ_TOOL_NAMES / PLAN_DISABLED_TOOLS)。
 // 加新工具:在 BY_NAME 加一行;或靠形状启发自动识别。
-/** 工具名 → ContextKind 的强先验表(覆盖全部 17 内置工具)。 */
+/** 工具名 → ContextKind 的强先验表(覆盖全部 18 内置工具)。 */
 const BY_NAME = {
     // tree:路径列表 → 缩进树
     glob: 'tree',
@@ -32,6 +32,7 @@ const BY_NAME = {
     write_file: 'status',
     ask_human: 'status',
     switch_mode: 'status',
+    drop_context: 'status',
     memory_save: 'status',
     memory_update: 'status',
     memory_forget: 'status',

package/dist/context/encoders/_util.js

@@ -0,0 +1,40 @@
+// encoder 共享小工具(非 encoder,纯函数)。供 graph/doc/summary 等复用。
+// log/code 各有专属逻辑(log 用重复行折叠;code 用前缀感知空行检测),不在此。
+/** 去 ANSI CSI 序列(颜色 / 光标 / 清屏等)。语义无损:颜色码不含信息。 */
+export function stripAnsi(s) {
+    return s.replace(/\x1b\[[0-9;]*[A-Za-z]/g, '');
+}
+/**
+ * 折叠连续空行(只含空白字符的行)≥ threshold → 单个空行。
+ * 用于 prose / source dump(web_fetch / use_skill / task / codegraph):HTML→文本与 markdown 常留多余空行,
+ * 多空行与单空行语义等价,折叠无损。默认 threshold=3(只动真正过量的空行,常见 ≤2 空行不动)。
+ *
+ * 注意:用 `.trim() === ''` 判空——故 read_file 的 `     2\t`(行号前缀 + tab,trim 后剩 `2`)不会被
+ * 视作空行。read_file 的空行折叠见 code encoder(前缀感知)。
+ */
+export function collapseBlankRuns(text, threshold = 3) {
+    const lines = text.split('\n');
+    const out = [];
+    let i = 0;
+    while (i < lines.length) {
+        if (lines[i].trim() === '') {
+            let j = i;
+            while (j < lines.length && lines[j].trim() === '')
+                j++;
+            const run = j - i;
+            if (run >= threshold) {
+                out.push(''); // 单个空行
+            }
+            else {
+                for (let k = 0; k < run; k++)
+                    out.push(lines[i]);
+            }
+            i = j;
+        }
+        else {
+            out.push(lines[i]);
+            i++;
+        }
+    }
+    return out.join('\n');
+}

package/dist/context/encoders/code.js

@@ -0,0 +1,77 @@
+/**
+ * Code Encoder(read_file):折叠连续空行(≥3 → 1,保留首空行行号前缀)。
+ *
+ * 输入:read_file 返回的 `     N\t<content>` 行(6 宽右对齐行号 + tab + 内容),可能带尾部
+ *  `... (N 行未显示,共 M 行)`。
+ * 输出:连续 ≥3 个空行(行号前缀 + 空 content)折叠为 1 个(保留首行前缀,丢后续空行);其余逐字保留。
+ *
+ * 不变量(离线脚本断言):
+ *  - 所有非空 content 行逐字保留(前缀 + 内容不变)→ edit_file 的 old_string 按内容匹配仍可用。
+ *  - content 行的行号前缀不变 → LLM 看到的行号与文件一致。
+ *  - 仅空行(前缀 + tab + 空 content)被折叠,且仅 ≥3 连续时;≤2 空行原样(常见,不动)。
+ *  - 尾部标记 `... (...)` 不匹配行号前缀,原样保留。
+ *
+ * ⚠️ 残余风险(可接受、可恢复):若 LLM 编辑一个含 ≥3 连续空行的区域,它看到的空行数比文件实际少,
+ *   old_string 的空行数可能不匹配 → edit_file 返"未找到" → LLM 重读重试(系统提示已要求编辑前 read_file)。
+ *   真实代码极少 ≥3 连续空行(linter 通常强制 ≤2),故实际几乎不触发。出问题可设
+ *   MOCODE_CONTEXT_OPTIMIZE=false 全局回退,或调高阈值。
+ *
+ * 不做长度裁剪(cap 兜底);不动行号前缀;不删 content 行;不改内容(含尾随空白)。
+ * 空行判定用前缀感知(前缀 + tab + 空 content),不能用 trim——read_file 空行 `     2\t` trim 后剩 `2`。
+ */
+const LINE_RE = /^(\s*\d+)\t(.*)$/;
+function isBlankCodeLine(l) {
+    const m = LINE_RE.exec(l);
+    return m ? m[2] === '' : false;
+}
+export const codeEncoder = {
+    kind: 'code',
+    encode({ output }) {
+        const lines = output.split('\n');
+        const out = [];
+        let i = 0;
+        let collapsedRuns = 0;
+        while (i < lines.length) {
+            if (isBlankCodeLine(lines[i])) {
+                let j = i;
+                while (j < lines.length && isBlankCodeLine(lines[j]))
+                    j++;
+                const run = j - i;
+                if (run >= 3) {
+                    out.push(lines[i]); // 保留首空行(含其行号前缀)
+                    collapsedRuns++;
+                }
+                else {
+                    for (let k = 0; k < run; k++)
+                        out.push(lines[i]);
+                }
+                i = j;
+            }
+            else {
+                out.push(lines[i]);
+                i++;
+            }
+        }
+        if (collapsedRuns === 0) {
+            return {
+                text: output,
+                meta: {
+                    kind: 'code',
+                    originalLen: output.length,
+                    encodedLen: output.length,
+                    note: 'no ≥3 blank runs → passthrough',
+                },
+            };
+        }
+        const text = out.join('\n');
+        return {
+            text,
+            meta: {
+                kind: 'code',
+                originalLen: output.length,
+                encodedLen: text.length,
+                note: `collapsed ${collapsedRuns} blank runs (≥3 → 1)`,
+            },
+        };
+    },
+};

package/dist/context/encoders/doc.js

@@ -0,0 +1,28 @@
+import { collapseBlankRuns } from './_util.js';
+/**
+ * Doc Encoder(web_fetch / use_skill):折叠连续空行(≥3 → 1)。
+ *
+ * 输入:
+ *  - web_fetch 的 `URL (HTTP ...)\n\n<body>`(HTML→文本,常留多余空行)。
+ *  - use_skill 的 `# Skill: name\n\n<body>`(SKILL.md 正文,frontmatter 已剥离)。
+ * 输出:空行折叠;正文 / 指令逐字保留。
+ *
+ * 不变量:URL 前缀行 / Skill 标题行保留;正文文本逐字保留(仅折叠空行——markdown / HTML 多空行与
+ *  单空行语义等价,无损)。use_skill 走放宽 cap(MAX_SKILL_RESULT)保指令完整——本 encoder 在 cap 前先
+ *  折叠空行,减少被 cap 截断的风险。
+ */
+export const docEncoder = {
+    kind: 'doc',
+    encode({ output }) {
+        const text = collapseBlankRuns(output, 3);
+        return {
+            text,
+            meta: {
+                kind: 'doc',
+                originalLen: output.length,
+                encodedLen: text.length,
+                note: text !== output ? 'blank runs collapsed' : 'no change',
+            },
+        };
+    },
+};

package/dist/context/encoders/graph.js

@@ -0,0 +1,31 @@
+import { stripAnsi, collapseBlankRuns } from './_util.js';
+/**
+ * Graph Encoder(codegraph):去 ANSI + 折叠连续空行(≥3 → 1)。
+ *
+ * 输入:codegraph CLI 返回的 `[退出码 N]\n<源码 + 调用路径>`(可能含 ANSI 颜色、多余空行)。
+ * 输出:去 ANSI + 空行折叠;结构(调用路径块、源码段)不动。
+ *
+ * 不变量:退出码行保留;源码与调用路径文本逐字保留(仅去颜色码 + 折叠空行);不删内容行。
+ * 保守:不重构调用路径 / 不去重源码(codegraph CLI 输出格式未稳定,需先采样真实输出定不变量,留后续)。
+ */
+export const graphEncoder = {
+    kind: 'graph',
+    encode({ output }) {
+        const stripped = stripAnsi(output);
+        const text = collapseBlankRuns(stripped, 3);
+        const hadAnsi = /\x1b/.test(output);
+        const hadBlanks = text !== stripped;
+        const note = [hadAnsi ? 'ANSI stripped' : '', hadBlanks ? 'blank runs collapsed' : '']
+            .filter(Boolean)
+            .join(', ') || 'no change';
+        return {
+            text,
+            meta: {
+                kind: 'graph',
+                originalLen: output.length,
+                encodedLen: text.length,
+                note,
+            },
+        };
+    },
+};

package/dist/context/encoders/index.js

@@ -1,10 +1,32 @@
 // 内置 encoder 清单。启动期 pipeline 首次调用时经 registerAll 注册到 registry。
 //
-// Phase 1:仅 passthrough(identity)→ 全链路零行为变化(所有 kind 都回落到它)。
-// Phase 2 起逐步加入:tree / search / log / code / table / memory(见各 encoder 文件)。
+// Phase 1:passthrough(identity 兜底)→ 全链路零行为变化。
+// Phase 2:tree / search / log / table / memory(高价值低风险)。
+// Phase 2.5:code / graph / doc / summary(覆盖剩余有 encoder 的 kind)。
+//   - code(read_file):仅折叠 ≥3 连续空行,行号保真(edit_file 依赖)。
+//   - graph(codegraph)/ doc(web_fetch, use_skill)/ summary(task):去 ANSI + 折叠空行,保守不重构结构。
+//   - status(edit/write/ask_human/switch_mode/mem 增删改)无 encoder:本就是一行,无需编码。
 //
 // 加 encoder:新建 encoders/xxx.ts 导出 ContextEncoder,在此数组加一行。无需动 agent / llm / core。
 import { passthroughEncoder } from './passthrough.js';
+import { treeEncoder } from './tree.js';
+import { searchEncoder } from './search.js';
+import { logEncoder } from './log.js';
+import { tableEncoder } from './table.js';
+import { memoryEncoder } from './memory.js';
+import { codeEncoder } from './code.js';
+import { graphEncoder } from './graph.js';
+import { docEncoder } from './doc.js';
+import { summaryEncoder } from './summary.js';
 export const builtinEncoders = [
     passthroughEncoder,
+    treeEncoder,
+    searchEncoder,
+    logEncoder,
+    tableEncoder,
+    memoryEncoder,
+    codeEncoder,
+    graphEncoder,
+    docEncoder,
+    summaryEncoder,
 ];

package/dist/context/encoders/log.js

@@ -0,0 +1,52 @@
+/**
+ * Log Encoder(run_command):去 ANSI 颜色码 + 折叠连续重复行(≥3 → 单行 + [×N])。
+ *
+ * 输入:run_command 返回的 `[退出码 N]\n<合并 stdout+stderr>`,可能含 ANSI(tsc --pretty / 测试框架)、
+ *  重复行(构建 / 编译日志)、尾部 `...(输出已截断)`、`[已中断]` / `[超时,已终止]` 前缀。
+ * 输出:去 ANSI CSI 序列 + 连续重复行折叠;行顺序不变(退出码头恒在首、错误行与尾部原位保留)。
+ *
+ * 不变量(离线脚本断言):退出码行 `[退出码 N]` / `[已中断]` / `[超时,已终止]` 保留;
+ *  重复行以 `[×N]` 标注计数(语义不丢——LLM 仍知该行重复 N 次);ANSI 去除语义无损(颜色码不含信息)。
+ * 不做长度裁剪(由 pipeline 末尾 capToolResultForHistory 兜底 head+标记+tail,与改造前一致)。
+ * run ≤2 原样保留(常见输出不必标注,避免噪音);run ≥3 才折叠(真正的大规模重复才省)。
+ */
+const ANSI_RE = /\x1b\[[0-9;]*[A-Za-z]/g;
+export const logEncoder = {
+    kind: 'log',
+    encode({ output }) {
+        // 去 ANSI CSI 序列(颜色 / 光标 / 清屏等),保留所有可见文本。
+        const stripped = output.replace(ANSI_RE, '');
+        const lines = stripped.split('\n');
+        // 折叠连续重复行:run ≥3 → 单行 + [×N];run ≤2 原样。
+        const out = [];
+        let i = 0;
+        let collapsedRuns = 0;
+        while (i < lines.length) {
+            let j = i;
+            while (j < lines.length && lines[j] === lines[i])
+                j++;
+            const run = j - i;
+            if (run >= 3) {
+                out.push(`${lines[i]}  [×${run}]`);
+                collapsedRuns++;
+            }
+            else {
+                for (let k = 0; k < run; k++)
+                    out.push(lines[i]);
+            }
+            i = j;
+        }
+        const text = out.join('\n');
+        return {
+            text,
+            meta: {
+                kind: 'log',
+                originalLen: output.length,
+                encodedLen: text.length,
+                note: collapsedRuns > 0
+                    ? `ANSI stripped, ${collapsedRuns} dup runs collapsed`
+                    : 'ANSI stripped',
+            },
+        };
+    },
+};

package/dist/context/encoders/memory.js

@@ -0,0 +1,63 @@
+/**
+ * Memory Encoder(memory_search):去掉 `recalled N` 召回计数噪音(遗忘系统内部用,非 LLM 推理所需)。
+ *
+ * 输入:memory_search 返回的条目卡,每张:`# [id] name (type, recalled N)\nsummary: ...\n\nbody`,
+ *  多张以 `\n\n---\n\n` 分隔。
+ * 输出:头部 `# [id] name (type)`(丢 `, recalled N`);summary/body 原样。
+ *
+ * 不变量(离线脚本断言):id/name/type/summary/body 全保留;仅 `recalled N` 被省略。
+ *  正则锚定整行 `# [id] ... (type, recalled N)`,group1 贪婪捕获到 `(\w+` 为止,name 含 ` (` 也不影响。
+ *  不匹配的行原样返回(防误伤 body 正文里的 `#` 标题等)。
+ */
+const HEADER_RE = /^(# \[[^\]]+\] .+ \(\w+), recalled \d+\)$/;
+export const memoryEncoder = {
+    kind: 'memory',
+    encode({ output }) {
+        if (output.startsWith('(无匹配记忆')) {
+            return {
+                text: output,
+                meta: {
+                    kind: 'memory',
+                    originalLen: output.length,
+                    encodedLen: output.length,
+                    note: 'no matches → passthrough',
+                },
+            };
+        }
+        const lines = output.split('\n');
+        const out = [];
+        let changed = 0;
+        for (const l of lines) {
+            const m = HEADER_RE.exec(l);
+            if (m) {
+                // m[1] = "# [id] name (type";补 ")" 收尾,丢 ", recalled N"
+                out.push(`${m[1]})`);
+                changed++;
+            }
+            else {
+                out.push(l);
+            }
+        }
+        if (changed === 0) {
+            return {
+                text: output,
+                meta: {
+                    kind: 'memory',
+                    originalLen: output.length,
+                    encodedLen: output.length,
+                    note: 'no recalled headers → passthrough',
+                },
+            };
+        }
+        const text = out.join('\n');
+        return {
+            text,
+            meta: {
+                kind: 'memory',
+                originalLen: output.length,
+                encodedLen: text.length,
+                note: `dropped recalled count from ${changed} entries`,
+            },
+        };
+    },
+};