mocode-ai 0.1.4 → 0.1.6

package/dist/config/index.js

@@ -28,6 +28,8 @@ function loadEnvFiles() {
             process.env[k] = v;
     }
 }
+// 在 loadEnvFiles 回填前捕获:MOCODE_THEME 是否由 shell 设置(决定 /theme 写文件是否下次启动生效)。
+const themeFromShell = process.env.MOCODE_THEME !== undefined;
 loadEnvFiles();
 function requireEnv(key) {
     const v = process.env[key];
@@ -37,42 +39,79 @@ function requireEnv(key) {
     }
     return v;
 }
-const SYSTEM_PROMPT = `你是 mocode,一个终端编码 agent。你以"思考 → 调用工具 → 观察结果 → 再思考"的循环完成编程任务,直到问题解决。面向中文用户,回复用中文。
-
-## 工作流
-- 先理解再动手:不确定需求或代码现状时,先 read_file / grep / glob 探索,不凭空假设。
-- 小步推进:任务拆成可验证的子步骤,每步动手前想清楚改什么、为什么。
-- 改完即验证:用 run_command 跑 typecheck / 测试 / 构建确认有效,未验证不声称完成。
-
-## 工具准则
-- 参数与用法见各工具自带说明;这里只讲选择策略与易踩坑。
-- 改代码前先 read_file 确认实际内容(带行号),不凭记忆猜。
-- 局部改用 edit_file:old_string 须唯一且精确匹配(含缩进/换行),多带上下文行确保唯一;新建或整体重写用 write_file。
-- 找路径用 glob,找内容用 grep;不要用 run_command 拼 cat / sed / find / grep。
-- 若当前目录存在 .codegraph/(已建代码索引),理解/定位代码、查调用链、看改动影响面时必须先 codegraph 再动手:run_command 跑 codegraph explore "<符号或问题>"(一次拿相关符号源码 + 调用路径)或 codegraph node <符号或文件>(单符号源码 + 调用者)。不要逐文件 glob/read_file/grep 去拼凑理解——那是 codegraph 已替你做完的事。仅当 codegraph 找不到、未索引、要看刚改的最新内容、或改单个已知小文件时才用 read_file/grep/glob。详见 use_skill codegraph。
-- run_command 按平台执行(Win 用 cmd、其他用 bash);有副作用的命令(删文件、装包、git push、重置等)执行前先简述意图。
-- 需要训练数据之外的最新信息(新版本、新闻、实时数据、最新 API)时用 web_search 联网搜索,不要凭记忆答可能过时的内容。
-- 要读取某个具体 URL 的内容(搜索结果里的链接、用户给的 URL)时用 web_fetch 抓取;它只抓静态 HTML,JS 渲染页面拿不到正文时改用 web_search(其结果自带清洗后的正文)。
-- 遇到需要用户决策的岔路(多种实现方案、不确定用户意图、需要额外信息才能继续),调 ask_human 列出选项让用户选(用户也可选"自定义输入"自由作答)。不要在任务明确、能自行决定时频繁打扰用户;用户取消后换方案或基于已有信息推进,不原地重复问。
-
-## 失败处理
-- 工具以字符串返回错误(edit_file 未匹配或不唯一、run_command 非零退出码等)。先分析根因,调整后重试,不要原样重发同一条调用。
-- 命令报错时把真实输出读进去再判断,别跳过。
-
-## 安全与边界
-- 不可逆或外向操作(删除、覆盖既有文件、推送、请求外部服务)执行前向用户确认,除非已获明确授权。
-- 只在授权范围内操作;不确定就问,别猜。
-
-## 记忆(跨会话长期事实)
-- 系统提示已注入「记忆索引」(仅 id/标题/摘要)。需要某条正文时调 memory_search(传 id 或关键词)取;memory_list 看全部索引。
-- 遇到非显然、跨会话有用的事实/决策/坑(架构约定、易踩坑、用户偏好、已做决策),用 memory_save 存——只存长期稳定项,不存当前 bug / 临时文件 / 未决 TODO。
-- 发现已存记忆过时或与新事实矛盾,用 memory_update(id, …) 原地纠正(别新建重复条);明确失效的用 memory_forget(id) 归档。
-- 存前先 memory_search 看是否已有同类条,避免重复。宁可少记,不记正确废话。
-- 后台反思 pass 会定期从会话里挖掘并整理记忆(无需你手动),但你主动存的关键事实更可靠。
-
-## 终止与汇报
-- 无需更多工具时立即停止,直接给结论。
-- 如实汇报:成功说成功,失败说卡在哪,跳过的也要说。引用代码用 "path:行号" 格式(如 src/index.ts:42)。保持简洁。`;
+const PLATFORM_NOTE = (() => {
+    if (process.platform === 'win32') {
+        return `## Environment (Windows)
+- 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.
+- Prefer the dedicated tools (read_file/glob/grep) over shell equivalents — they're cross-platform and already wired in.`;
+    }
+    if (process.platform === 'darwin') {
+        return `## Environment (macOS)
+- You are on macOS; run_command runs via bash -c (user default shell may be zsh). BSD coreutils, not GNU.
+- Pitfalls: sed -i needs an empty backup-ext arg (sed -i '' 's/x/y/' file); grep -P unavailable (use grep -E or the grep tool); find/readlink/date are BSD variants; readlink -f unsupported (use realpath, or greadlink -f if GNU coreutils installed via brew).
+- Prefer the dedicated tools (read_file/glob/grep) over shell equivalents — they sidestep BSD/GNU differences.`;
+    }
+    return `## Environment (Linux/Unix)
+- 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.
+
+${PLATFORM_NOTE}
+
+## Workflow
+- Understand before acting: when unsure about requirements or code state, explore first; don't assume.
+- 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.
+
+## 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.
+- 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).
+- 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.
+
+## 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.
+- When a command errors, read the actual output before judging; don't skip it.
+
+## Safety & Boundaries
+- 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.
+
+## 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。
+ */
+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. 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.`;
 export const config = {
     baseURL: requireEnv('LLM_BASE_URL'),
     apiKey: requireEnv('LLM_API_KEY'),
@@ -83,9 +122,15 @@ 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,
+    subAgentMaxSteps: Number(process.env.SUB_AGENT_MAX_STEPS) || 50,
     sessionDir: path.join(process.cwd(), '.mocode', 'sessions'),
     searchApiKey: process.env.ANYSEARCH_API_KEY,
+    sandboxRoot: process.env.SANDBOX_ROOT || undefined,
     searchBaseUrl: process.env.ANYSEARCH_BASE_URL || 'https://api.anysearch.com',
+    theme: process.env.MOCODE_THEME || 'default',
+    themeFromShell,
 };

package/dist/context/classifier.js

@@ -0,0 +1,83 @@
+// Context Classifier:据工具名(强先验)+ 输出形状(启发)+ 兜底,选 ContextKind。
+//
+// 三级信号:
+//  1) 名字强先验(BY_NAME 表,覆盖全部 17 内置工具,确定性强)。
+//  2) 形状启发(为 MCP 工具 / 未来工具 / 未登记工具兜底识别)。
+//  3) 兜底 'passthrough'(不认识 = 不动,零行为变化)。
+//
+// 单一事实源风格(仿 tools/constants.ts 的 READ_TOOL_NAMES / PLAN_DISABLED_TOOLS)。
+// 加新工具:在 BY_NAME 加一行;或靠形状启发自动识别。
+/** 工具名 → ContextKind 的强先验表(覆盖全部 17 内置工具)。 */
+const BY_NAME = {
+    // tree:路径列表 → 缩进树
+    glob: 'tree',
+    // search:file:line 分组
+    grep: 'search',
+    web_search: 'search',
+    // graph:CLI dump → 精炼图
+    codegraph: 'graph',
+    // log:分级 / 折叠 / 尾偏置
+    run_command: 'log',
+    // code:保行号(edit_file 依赖,最敏感)
+    read_file: 'code',
+    // table:列对齐
+    memory_list: 'table',
+    // memory:紧凑卡片
+    memory_search: 'memory',
+    // doc:去噪音保正文
+    web_fetch: 'doc',
+    use_skill: 'doc',
+    // status:一行状态(identity,不动)
+    edit_file: 'status',
+    write_file: 'status',
+    ask_human: 'status',
+    switch_mode: 'status',
+    memory_save: 'status',
+    memory_update: 'status',
+    memory_forget: 'status',
+    // summary:子 agent 摘要(轻量)
+    task: 'summary',
+};
+/**
+ * 形状启发:对未在 BY_NAME 登记的工具输出做模式识别(为 MCP / 未来工具兜底)。
+ * 故意保守:识别不准时回落 passthrough(不动),宁可不少省也不可错改。
+ */
+function classifyByShape(output) {
+    // file:line: content 形(grep 风格)
+    if (/^[^\n:]+:\d+:[^\n]*$/m.test(output))
+        return 'search';
+    // [退出码 N] 前缀(run_command / codegraph 风格)
+    if (/^\[退出码 \d+\]/m.test(output))
+        return 'log';
+    // 路径列表:多行都是含分隔符的相对路径(glob 风格)
+    const lines = output.split('\n').filter((l) => l.trim().length > 0);
+    if (lines.length >= 3 &&
+        lines.every((l) => /^[\w.\-\\/ ]+$/.test(l.trim()) && /[\\/]/.test(l))) {
+        return 'tree';
+    }
+    // JSON 结构化(web_fetch 的 JSON 响应等)→ doc 渲染
+    const trimmed = output.trimStart();
+    if (trimmed.startsWith('{') || trimmed.startsWith('['))
+        return 'doc';
+    return 'passthrough';
+}
+/**
+ * 判定 ContextKind。
+ *  - 有 BY_NAME 强先验 → 用之(内置工具确定性强)。
+ *  - 否则形状启发(MCP / 未来工具)。
+ *  - 都不中 → passthrough(不动)。
+ *
+ * @param toolName 工具名
+ * @param output 工具原始输出(形状启发用;有 BY_NAME 时不读)
+ * @param _args 已解析参数(预留:未来 read_file 的 offset/limit 可影响 code 编码策略;Phase 1 不用)
+ */
+export function classify(toolName, output, _args) {
+    const byName = BY_NAME[toolName];
+    if (byName)
+        return byName;
+    return classifyByShape(output);
+}
+/** 暴露 BY_NAME 副本供调试 / 未来 /context 展示(只读视图)。 */
+export function knownToolKinds() {
+    return { ...BY_NAME };
+}

package/dist/context/encoders/index.js

@@ -0,0 +1,10 @@
+// 内置 encoder 清单。启动期 pipeline 首次调用时经 registerAll 注册到 registry。
+//
+// Phase 1:仅 passthrough(identity)→ 全链路零行为变化(所有 kind 都回落到它)。
+// Phase 2 起逐步加入:tree / search / log / code / table / memory(见各 encoder 文件)。
+//
+// 加 encoder:新建 encoders/xxx.ts 导出 ContextEncoder,在此数组加一行。无需动 agent / llm / core。
+import { passthroughEncoder } from './passthrough.js';
+export const builtinEncoders = [
+    passthroughEncoder,
+];

package/dist/context/encoders/passthrough.js

@@ -0,0 +1,23 @@
+/**
+ * 兜底 encoder:identity,原样返回。
+ *  - classifier 未命中任何 kind(返回 'passthrough')时用。
+ *  - pipeline 总开关关闭(MOCODE_CONTEXT_OPTIMIZE=false)时,所有 kind 都走它 → 行为与改造前逐字节一致。
+ *  - Phase 1 阶段 registry 只注册它 → 全链路零行为变化。
+ *  - 任何 encoder 报错时,pipeline catch 后回落到它(传原 output)。
+ *
+ * 永不抛错:output 可能是任意字符串(含 ANSI / 多行 / 非法 UTF-8 片段),identity 直接返回,无解析风险。
+ */
+export const passthroughEncoder = {
+    kind: 'passthrough',
+    encode({ output }) {
+        return {
+            text: output,
+            meta: {
+                kind: 'passthrough',
+                originalLen: output.length,
+                encodedLen: output.length,
+                note: 'identity (no encoder registered)',
+            },
+        };
+    },
+};

package/dist/context/index.js

@@ -0,0 +1,10 @@
+// context/ barrel:Context Optimization Pipeline。
+//
+// 单一入口 optimizeToolResult(agent/core.ts pushToolResult 调)接管"工具结果进 LLM 前"的表示。
+// 不调 LLM、不碰 Tool Calling schema / executeTool / tool_call_id 配对 / TUI 渲染
+// (叶子级:仅 stdlib + tools/constants + session/compact 的 capToolResultForHistory 兜底 + config 开关)。
+//
+// 见 CLAUDE.md「Context Optimization Pipeline」节。
+export { optimizeToolResult } from './pipeline.js';
+export { classify, knownToolKinds } from './classifier.js';
+export { registerEncoder, registerAll, getEncoder, registeredKinds, } from './registry.js';

package/dist/context/pipeline.js

@@ -0,0 +1,84 @@
+// Context Optimization Pipeline 单一入口。
+//
+// 接管"工具结果进 LLM 前"的表示优化(C1 收口,agent/core.ts pushToolResult 调)。
+// 流程:
+//   1) 解析 argsRaw(失败返 null,encoder 据此降级)。
+//   2) classify(name, output, args) → ContextKind。
+//   3) getEncoder(kind) ?? passthrough → encode(保不变量压缩,纯函数)。
+//   4) capToolResultForHistory(name, text) 作末尾长度裁剪兜底(保 head+标记+tail,与改造前一致)。
+//
+// 不抛错:encoder 报错 → catch 回落原 output + capToolResultForHistory(对齐「调度器永不抛错」)。
+// 兜底零行为变化:未注册 encoder / pipeline 关闭 → passthrough identity → 末尾 cap 与改造前逐字节一致。
+//
+// 兼容:不改 Tool Calling JSON schema、不改 executeTool、不改 tool_call_id 配对、不改 TUI 渲染
+// (hooks.onToolResult 用原始 output,本函数只管进 history 的 content)。
+//
+// 依赖方向:context → {tools/constants, session/compact 的 cap, config};叶子,不反向依赖 llm/agent/tools。
+import { classify } from './classifier.js';
+import { getEncoder, registerAll } from './registry.js';
+import { builtinEncoders } from './encoders/index.js';
+import { passthroughEncoder } from './encoders/passthrough.js';
+import { capToolResultForHistory } from '../session/compact.js';
+import { config } from '../config/index.js';
+import { MAX_HISTORY_RESULT, MAX_SKILL_RESULT, MAX_MEMORY_RESULT, } from '../tools/constants.js';
+let booted = false;
+/** 懒注册内置 encoder(首次调用 optimizeToolResult 时触发,避免模块加载期循环 import)。 */
+function boot() {
+    if (booted)
+        return;
+    registerAll(builtinEncoders);
+    booted = true;
+}
+/** 解析工具 arguments JSON;非法或空返 null(同 agent/core.ts parseArgs 语义,独立实现避免循环依赖)。 */
+function tryParseArgs(raw) {
+    try {
+        return raw.trim() ? JSON.parse(raw) : {};
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 按工具名取软目标 budget(字符)。对齐 capToolResultForHistory 的放宽规则:
+ * use_skill / memory_search 走放宽上限(指令 / 记忆正文须完整);其余走 MAX_HISTORY_RESULT。
+ * 仅作 encoder 软目标;最终裁剪仍由末尾 capToolResultForHistory 兜底,故两处常量偶有漂移不致命。
+ */
+function budgetFor(name) {
+    if (name === 'use_skill')
+        return MAX_SKILL_RESULT;
+    if (name === 'memory_search')
+        return MAX_MEMORY_RESULT;
+    return MAX_HISTORY_RESULT;
+}
+/**
+ * 优化工具结果为进 LLM 的 tool 消息 content。
+ *
+ * @param name 工具名
+ * @param output executeTool 的原始返回字符串
+ * @param argsRaw 工具 arguments 原始 JSON 字符串(tc.arguments,可空;未传则 args=null)
+ * @returns 进 history 的 content 字符串(永不抛错)
+ */
+export function optimizeToolResult(name, output, argsRaw) {
+    boot();
+    // 总开关关闭:完全走老路径,零行为变化(Phase 1 默认 true,但保留紧急回退开关)。
+    if (!config.contextOptimize) {
+        return capToolResultForHistory(name, output);
+    }
+    try {
+        const args = argsRaw != null ? tryParseArgs(argsRaw) : null;
+        const kind = classify(name, output, args);
+        const enc = getEncoder(kind) ?? passthroughEncoder;
+        const { text } = enc.encode({
+            toolName: name,
+            output,
+            args,
+            budget: budgetFor(name),
+        });
+        // 末尾长度裁剪兜底(同改造前):encoder 已更短则 no-op;use_skill/memory_search 的放宽 cap 由此保留。
+        return capToolResultForHistory(name, text);
+    }
+    catch {
+        // encoder 报错(不应发生,纯函数):回落原 output + cap(永不抛错契约)。
+        return capToolResultForHistory(name, output);
+    }
+}

package/dist/context/registry.js

@@ -0,0 +1,30 @@
+// kind → encoder 注册表。单一事实源(仿 tools/registry.ts 的 tools[] 风格)。
+//
+// 内置 encoder 在 encoders/index.ts 的 builtinEncoders 数组声明,启动期 pipeline 首次调用时
+// 经 registerAll 注册(懒注册,避免循环 import 在模块加载期触发)。
+// MCP 工具(未来)可在并入 tools/registry.ts 时调 registerEncoder 注册私有 encoder(后注册覆盖默认)。
+//
+// 未注册的 kind → getEncoder 返 undefined → pipeline 回落 passthrough(identity),零行为变化。
+const encoders = new Map();
+let registered = false;
+/** 注册一个 encoder(后注册覆盖先注册,允许 MCP 覆盖默认)。返回 encoder 自身供链式。 */
+export function registerEncoder(enc) {
+    encoders.set(enc.kind, enc);
+    return enc;
+}
+/** 批量注册(启动期 pipeline 调一次)。幂等:重复调忽略。 */
+export function registerAll(list) {
+    if (registered)
+        return;
+    for (const e of list)
+        registerEncoder(e);
+    registered = true;
+}
+/** 取某 kind 的 encoder;未注册返 undefined(pipeline 回落 passthrough)。 */
+export function getEncoder(kind) {
+    return encoders.get(kind);
+}
+/** 调试:列出已注册 kind。 */
+export function registeredKinds() {
+    return [...encoders.keys()];
+}

package/dist/context/types.js

@@ -0,0 +1,12 @@
+// Context Optimization Pipeline 的类型契约。
+//
+// 设计原则(见 CLAUDE.md context/ 子系统):
+//  - Tool Calling 的 JSON schema 与 executeTool 不动;本层只接管"工具结果进 LLM 前"的表示。
+//  - 不设计统一 DSL,针对不同数据类型各做最优 encoder。
+//  - 所有 encoder 是纯函数(无 LLM 调用 / 无 IO / 无副作用),永不抛错(pipeline 层 try/catch,
+//    失败回落原 output + capToolResultForHistory,对齐 tools/registry.ts「调度器永不抛错」契约)。
+//  - 兜底 encoder = passthrough(identity):未注册 encoder 时行为与改造前逐字节一致。
+//
+// 依赖方向:context 是叶子(仅 stdlib + tools/constants + session/compact 的 cap + config 开关),
+// 不反向依赖 llm / agent / tools 业务,无环。
+export {};

package/dist/index.js

@@ -36,6 +36,16 @@ process.on('unhandledRejection', (e) => {
  */
 async function main() {
     const args = process.argv.slice(2);
+    // --sandbox-root <path>:覆盖沙箱根(文件操作边界)。缺值或以 -- 开头报错退出。
+    const sr = args.indexOf('--sandbox-root');
+    let sandboxRootOverride;
+    if (sr !== -1) {
+        sandboxRootOverride = args[sr + 1];
+        if (!sandboxRootOverride || sandboxRootOverride.startsWith('--')) {
+            console.error('[cli] --sandbox-root 需要一个路径参数');
+            process.exit(1);
+        }
+    }
     // 首跑配置向导:写 ~/.mocode/config。独立模块,不触发 config 校验,故零配置也能跑。
     if (args[0] === 'config') {
         const { runConfigWizard } = await import('./commands/config.js');
@@ -66,12 +76,12 @@ async function main() {
         }
         const updateNotice = checkAndMaybeUpdate();
         const { startRepl } = await import('./repl/index.js');
-        await startRepl(loaded.history, loaded.id, updateNotice);
+        await startRepl(loaded.history, loaded.id, updateNotice, sandboxRootOverride);
     }
     else {
         const updateNotice = checkAndMaybeUpdate();
         const { startRepl } = await import('./repl/index.js');
-        await startRepl(undefined, undefined, updateNotice);
+        await startRepl(undefined, undefined, updateNotice, sandboxRootOverride);
     }
     process.exit(0);
 }

package/dist/llm/index.js

@@ -1,6 +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';
 const client = new OpenAI({
     baseURL: config.baseURL,
     apiKey: config.apiKey,
@@ -16,18 +17,23 @@ export const chatTools = tools.map((t) => ({
     },
 }));
 /**
- * 流式调一次 LLM:增量回调文本 / 思考,内部累加 tool_calls 片段。
- * 思考内容走 delta.reasoning_content(DeepSeek / GLM / Qwen 等推理模型,
- * SDK 类型无此字段,用 as any 取;不支持的模型则无思考,只流文本)。
+ * plan 模式用的受限工具 schema:剔除写盘 / 命令 / 记忆写入类(PLAN_DISABLED_TOOLS),
+ * 模型在 plan 模式下只看得到只读工具 → 调不到会改文件的工具。runAgent 在 plan 模式传给 chat()。
+ */
+export const planChatTools = chatTools.filter((t) => !PLAN_DISABLED_TOOLS.has(t.function.name));
+/**
+ * 流式调一次 LLM:增量回调文本,内部累加 tool_calls 片段。
  * tool_calls 跨 chunk 按 index 累加(id / name / arguments 拼接)。
  * include_usage 时末尾 chunk 携带 usage,先读再 continue(末尾 chunk 无 delta)。
  */
-export async function chat(messages, handlers = {}, signal) {
+export async function chat(messages, handlers = {}, signal, 
+/** 覆盖默认工具 schema;plan 模式传 planChatTools(只读子集),缺省=全量 chatTools。 */
+toolsOverride) {
     // signal 透传给 SDK 第二参(RequestOptions);abort 后 for await 抛错,chat 不 catch,透传 runAgent 处理。
     const stream = await client.chat.completions.create({
         model: config.model,
         messages,
-        tools: chatTools,
+        tools: toolsOverride ?? chatTools,
         stream: true,
         ...(config.maxTokens ? { max_tokens: config.maxTokens } : {}),
         ...(config.includeUsage ? { stream_options: { include_usage: true } } : {}),
@@ -48,10 +54,6 @@ export async function chat(messages, handlers = {}, signal) {
         const delta = chunk.choices[0]?.delta;
         if (!delta)
             continue; // 末尾 usage-only chunk 等无 delta
-        // 思考内容(非标准字段,SDK 类型无)
-        const reasoning = delta.reasoning_content ?? delta.reasoning;
-        if (reasoning)
-            handlers.onThinking?.(reasoning);
         if (delta.content) {
             content += delta.content;
             hasContent = true;

package/dist/memory/index.js

@@ -38,8 +38,8 @@ export function buildMemorySection() {
     return [
         '',
         '',
-        '## 项目记忆(MOCODE.md)',
-        '以下是项目记忆(架构 / 约定 / 命令等跨会话长期事实),据此行动:',
+        '## Project Memory (MOCODE.md)',
+        'The following is project memory (architecture / conventions / commands and other cross-session long-term facts). Act accordingly:',
         mem,
     ].join('\n');
 }

package/dist/memory/reflect.js

@@ -92,17 +92,17 @@ function buildMemorySample() {
         .join('\n---\n');
 }
 const TYPES = 'decision | fact | pitfall | reference | feedback';
-const REFLECT_SYS = `你是 mocode 的记忆反思器。审阅近期会话与现有记忆,产出**仅**值得长期记住的更新。
-严格输出 JSON(无 markdown 代码块、无解释文字):{"saves":[{"type":"...","name":"...","summary":"...","body":"..."}],"updates":[{"id":"...","reason":"...","summary":"...","body":"..."}],"forgets":[{"id":"...","reason":"..."}]}
-空数组合法(无可记则三个数组都空)。
-规则:
-① 只记非显然、跨会话有用的事实/决策/坑;不记当前 bug、临时文件、未决 TODO、易变项;
-② 宁可少记,不记正确废话(如"保持简洁");
-③ updates/forgets 的 id 必须来自下方「现有记忆」列表;不在此列的不要编 id;
-④ saves 的 name 须简洁且与现有不撞;type ∈ {${TYPES}};
-⑤ 若现有记忆与新事实矛盾或过时,update 旧条(改 summary/body)而非新建重复条;
-⑥ forgets 用于明显已失效 / 被新条取代的记忆(归档,非硬删)。`;
-const REFLECT_USER = (transcript, sample) => `## 近期会话\n${transcript}\n\n## 现有记忆\n${sample}\n\n产出 JSON:`;
+const REFLECT_SYS = `You are mocode's memory reflector. Review the recent session and existing memories, producing **only** updates worth remembering long-term.
+Output strictly JSON (no markdown code blocks, no explanatory text): {"saves":[{"type":"...","name":"...","summary":"...","body":"..."}],"updates":[{"id":"...","reason":"...","summary":"...","body":"..."}],"forgets":[{"id":"...","reason":"..."}]}
+Empty arrays are valid (if nothing is worth saving, all three arrays are empty).
+Rules:
+① Only store non-obvious, cross-session-useful facts/decisions/pitfalls; do not store current bugs, temp files, undecided TODOs, or volatile items;
+② Better to store less than to store trivially correct info (e.g. "keep it concise");
+③ ids in updates/forgets must come from the "existing memories" list below; do not fabricate ids not listed there;
+④ names in saves must be concise and not collide with existing ones; type ∈ {${TYPES}};
+⑤ If an existing memory contradicts new facts or is outdated, update the old entry (modify summary/body) rather than creating a duplicate;
+⑥ forgets are for memories clearly stale / superseded by a new entry (archive, not hard-delete).`;
+const REFLECT_USER = (transcript, sample) => `## Recent session\n${transcript}\n\n## Existing memories\n${sample}\n\nProduce JSON:`;
 function parsePlan(content) {
     if (!content)
         return null;

package/dist/memory/store.js

@@ -325,14 +325,14 @@ export function buildMemoryIndexSection() {
     const shown = active.slice(0, MAX_INDEX_ENTRIES);
     const lines = shown.map((e) => `- ${e.id}: ${e.name} — ${e.summary} (${e.type})`);
     const tail = active.length > MAX_INDEX_ENTRIES
-        ? `\n\n…(共 ${active.length} 条,只显前 ${MAX_INDEX_ENTRIES};用 memory_search <id 或关键词> 查更多)`
+        ? `\n\n…(${active.length} total, showing first ${MAX_INDEX_ENTRIES}; use memory_search <id or keyword> for more)`
         : '';
     return [
         '',
         '',
-        '## 记忆索引(按需 memory_search 取详情)',
-        '以下是已保存的记忆条目(标题/摘要)。需要正文时调 memory_search(传 id 或关键词);用 memory_list 看全部,'
-            + 'memory_update 改、memory_forget 忘。本列表为启动快照,会话期间新增的不在此——用 memory_list/memory_search 查最新。',
+        '## Memory Index (retrieve full body via memory_search)',
+        'The following are saved memory entries (title/summary only). Retrieve full body via memory_search (pass id or keyword); use memory_list to see all,'
+            + ' memory_update to modify, memory_forget to archive. This list is a startup snapshot; entries added during the session are not listed here — use memory_list/memory_search to find them.',
         ...lines,
         tail,
     ].join('\n');