mocode-ai 0.1.4 → 0.1.6

package/dist/agent/index.js

@@ -1,74 +1,20 @@
-import { readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { chat, } from '../llm/index.js';
-import { executeTool } from '../tools/registry.js';
+// 主 agent:runAgentCore + TUI 渲染 hooks 的薄封装。
+// 循环逻辑(流式 chat → 工具分组执行 → 回灌 / abort 还原 / maybeCompact)全部在 core.ts,
+// 本文件只负责把展示副作用(layout.contentWrite / Spinner / diff / 回滚轮次)注入为 AgentHooks。
+// 行为与重构前的单文件 runAgent 完全一致——这是安全重构,实跑回归验证。
 import { ui } from '../ui/theme.js';
 import { Spinner } from '../ui/spinner.js';
 import { summarizeToolCall, summarizeToolResult, truncateDisplay, fmtElapsed, } from '../ui/render.js';
 import { renderFileChange } from '../ui/diff.js';
 import * as layout from '../ui/layout.js';
 import { beginTurn } from '../rollback/index.js';
-import { maybeCompact, capToolResultForHistory, contextState, } from '../session/index.js';
-const MAX_STEPS = 25; // 防止无限循环
-/** 解析工具 arguments JSON;非法或空返 null(调用方据此降级到普通 preview)。 */
-function parseArgs(raw) {
-    try {
-        return raw.trim() ? JSON.parse(raw) : {};
-    }
-    catch {
-        return null;
-    }
-}
-/** 只读工具集:一轮多个时,连续的只读工具成组 Promise.all 并行(无副作用、互不依赖)。 */
-const READ_TOOL_NAMES = new Set([
-    'read_file',
-    'glob',
-    'grep',
-    'web_search',
-    'web_fetch',
-]);
-/** mutation 工具:写盘 + 在 executeTool 内记回滚 before 快照,必须串行保快照序。 */
-const isMutationTool = (name) => name === 'edit_file' || name === 'write_file';
+import { config } from '../config/index.js';
+import { runAgentCore, isMutationTool, } from './core.js';
 /** 工具调用 ● 头:工具名 + 参数摘要(按 tool_calls 原顺序打印,让用户看到本轮跑哪些工具)。 */
 function writeToolHeader(tc) {
     const summary = summarizeToolCall(tc.name, tc.arguments);
     layout.contentWrite(`  ${ui.brightMagenta}●${ui.reset} ${ui.cyan}${tc.name}${ui.reset}  ${ui.dim}${summary}${ui.reset}\n`);
 }
-/**
- * mutation 执行前读旧内容供 diff:write_file 取整文件旧内容(不存在→null=新建),
- * edit_file 取 old_string 起始行号(供 diff 显示真实文件行号)。读不到则 diff 退化为相对行号。
- * 非 mutation 或参数非法返 { preWriteOld: null, editStartLine: 1 }。失败不阻断。
- */
-function readDiffContext(tc, parsed) {
-    if (!parsed)
-        return { preWriteOld: null, editStartLine: 1 };
-    const p = String(parsed.path ?? '');
-    if (!p)
-        return { preWriteOld: null, editStartLine: 1 };
-    if (tc.name === 'write_file') {
-        try {
-            return { preWriteOld: readFileSync(resolve(p), 'utf8'), editStartLine: 1 };
-        }
-        catch {
-            return { preWriteOld: null, editStartLine: 1 }; // 文件不存在(新建)或不可读
-        }
-    }
-    if (tc.name === 'edit_file') {
-        const oldStr = String(parsed.old_string ?? '');
-        try {
-            const data = readFileSync(resolve(p), 'utf8');
-            const idx = oldStr ? data.indexOf(oldStr) : -1;
-            return {
-                preWriteOld: null,
-                editStartLine: idx >= 0 ? data.slice(0, idx).split('\n').length : 1,
-            };
-        }
-        catch {
-            return { preWriteOld: null, editStartLine: 1 }; // 读不到:diff 退化为相对行号
-        }
-    }
-    return { preWriteOld: null, editStartLine: 1 };
-}
 /** 渲染工具结果:mutation 成功走 diff 块(行号 + 语法高亮,仿 Claude Code);其余走一行 preview。 */
 function writeToolResult(tc, output, parsed, preWriteOld, editStartLine) {
     if (isMutationTool(tc.name) && parsed && !output.startsWith('错误')) {
@@ -89,44 +35,30 @@ function writeToolResult(tc, output, parsed, preWriteOld, editStartLine) {
         }
     }
 }
-/** 回灌 tool 结果到 history(裁到单条上限);tool_call_id 与 assistant.tool_calls 按序配对。 */
-function pushToolResult(history, tc, output) {
-    history.push({
-        role: 'tool',
-        tool_call_id: tc.id,
-        content: capToolResultForHistory(tc.name, output),
-    });
-}
 /**
- * agent 核心循环:
- *  流式调 LLM(onText / onThinking 实时写内容区)→ 有 tool_calls 就执行并回灌
+ * agent 核心循环(主 agent,TUI 渲染版):
+ *  流式调 LLM(onText 实时写内容区)→ 有 tool_calls 就执行并回灌
  *  → 否则流式正文即最终回复。history 在调用间持久,由 REPL 持有。
  *  步前经 session/maybeCompact 自动压缩(接近窗口上限时三层压缩);
  *  工具结果进 history 前经 capToolResultForHistory 裁到单条上限。
  *
  *  所有正文写经 layout.contentWrite(保证落在内容区、跟踪续写位、底栏不被顶);
  *  spinner 经 onFrame 回调刷状态行(layout.drawStatusBar),等待时内容区静止、底栏转圈。
- *  思考段用 layout.beginSegment / eraseSegmentBack 精确按物理行折叠(修预存按 \n 数行漏擦 bug),
- *  原文存入 collapsedThinkings 供 /think N 重打。
+ *  思考期间不写思考内容,只让 spinner 持续转「思考中…」(首个正文 / tool_call token 到达才停)。
+ *
+ *  循环逻辑委托 runAgentCore;本函数只注入 TUI 渲染 hooks(layout + spinner + diff + 回滚轮次)。
+ *  开新轮次(beginTurn)在入口调——core 不依赖 rollback,回滚轮次是主 agent 的展示副作用。
  */
-export async function runAgent(history, userInput, collapsedThinkings = [], signal, 
+export async function runAgent(history, userInput, signal, 
 /** 每步 chat() 返回后回调:repl 据此重算并重画状态行 context 用量条(运行中实时刷新,不冻结在轮首)。 */
 onContextUpdate) {
-    // 中断回滚快照:入口(本 turn push 任何消息前)整段浅拷贝。abort 时 length=0;push(...saved) 还原。
-    // 用 slice() 而非 length:maybeCompact 会原地重建(length=0;push(...rebuilt)),savedLen 会失效。
-    const savedHistory = history.slice();
-    // 本轮计时:从入口到完毕(正常 return / 达上限),供 finally 打 ✻ Worked for 摘要行。
-    // 与 layout 的 turnStart 各自独立(差几毫秒),避免 agent 反向读 layout 状态的耦合。
-    const t0 = Date.now();
-    let done = false; // 正常完毕 / 达上限 true;中断 false(不显摘要)
-    history.push({ role: 'user', content: userInput });
     // 开新轮次(回滚用):首行截断 40,供 /rollback 轮次菜单展示。
     beginTurn(truncateDisplay(userInput.split('\n')[0] ?? '', 40));
-    layout.contentMode(); // 防御性:确保光标在内容续写位(enterRunningMode 已置,这里兜底)
-    // spinner:状态行 + 续写位内联转圈(思考中 / 执行 工具时,内容区不再「干等」)。
-    // 内联帧不进缓冲、停时清掉,随后结果即写在该行——故 spinner 不入历史、PgUp 看不到。
+    layout.contentMode(); // 防御性:运行态光标归输入框光标位供 IME 锚定(enterRunningMode 已置,这里兜底)
+    // spinner:续写位内联转圈(思考中 / 执行 工具时,内容区不再「干等」)。
+    // 只走内联 paintLiveAtCursor——不调 setStatus,状态行不重复 spinner 文字(状态行只显走时,
+    // 由 turnTimer 200ms 续刷);内联帧不进缓冲、停时清掉,随后结果即写在该行——故 spinner 不入历史、PgUp 看不到。
     const spinner = new Spinner((msg, frame) => {
-        layout.setStatus(msg, frame ?? undefined);
         if (frame) {
             layout.paintLiveAtCursor(`  ${ui.brightMagenta}${frame}${ui.reset} ${ui.dim}${msg}…${ui.reset}`);
         }
@@ -134,178 +66,59 @@ onContextUpdate) {
             layout.clearLiveAtCursor();
         }
     });
-    // 本轮流式状态:区分「思考」与「正文」,首个 token 到达即停 spinner。
-    let mode = 'idle';
-    let gotText = false;
+    // lastChar 镜像:core 跟踪流式末字符决定补换行,但 TUI hooks 需读它决定 layout.contentWrite('\n')。
+    // core 的 onTextEnd hook 只在 lastChar !== '\n' 时才调,调后置 '\n';镜像与此同步。
     let lastChar = '';
-    // 折叠用:累计本段思考原文缓冲。
-    let thinkingBuffer = '';
-    /** 把当前还在屏幕上可见的思考段擦掉,换成一行折叠标题;原文入栈。 */
-    const flushThinkCollapsed = () => {
-        if (mode !== 'thinking')
-            return;
-        collapsedThinkings.push(thinkingBuffer);
-        const idx = collapsedThinkings.length;
-        layout.eraseSegmentBack(); // 逐行擦思考段(不用 ED——ED 会清穿底栏)
-        layout.contentWrite(`${ui.dim}▎ 思考 ▸ (${thinkingBuffer.length} 字符, /think ${idx} 展开)${ui.reset}\n`);
-        thinkingBuffer = '';
-        // 之后任何输出按 text 走,不再回到 thinking(避免后续再被错误折叠)
-        mode = 'text';
-    };
-    const onThinking = (s) => {
-        if (mode === 'idle') {
-            spinner.stop();
-            if (lastChar && lastChar !== '\n')
+    const hooks = {
+        onText: (s) => {
+            spinner.stop(); // 任何正文 token 都停 spinner(首 token 停「思考中」;onToolCall 重启后若又来文本则停「生成中」)。未旋转时 stop 为 no-op。
+            layout.contentWriteMd(s); // 正文走 markdown 渲染(代码块高亮 / 标题 / 列表 / 行内 …),见 ui/markdown.ts
+            if (s)
+                lastChar = s[s.length - 1];
+        },
+        onToolCall: (name) => {
+            // 文本/思考已流完,模型转而生成 tool_call 参数(可能很长,如 write_file 整篇内容):
+            // 补换行(让随后的 ● 行与 diff 不黏在正文末尾)+ 启「生成中」内联 spinner,内容区不再干等。
+            if (lastChar && lastChar !== '\n') {
                 layout.contentWrite('\n');
-            layout.beginSegment(); // 思考段起点(标题行)
-            layout.contentWrite(`${ui.dim}▎ 思考${ui.reset}\n`);
-        }
-        else if (mode === 'text') {
-            // 续思考:先把续标题放到新行,再开新段(段起点 = 续标题行,擦除不误伤上文)
+                lastChar = '\n';
+            }
+            if (name)
+                spinner.start(`生成 ${name}…`);
+        },
+        onStepStart: () => spinner.start('思考中'),
+        onChatDone: () => spinner.stop(),
+        onTextEnd: () => {
+            if (lastChar && lastChar !== '\n') {
+                layout.contentWrite('\n');
+                lastChar = '\n';
+            }
+        },
+        onToolHeader: (tc) => writeToolHeader(tc),
+        onToolStart: (name) => spinner.start(`执行 ${name}`),
+        onToolDone: () => spinner.stop(),
+        onToolResult: (tc, output, parsed, preWriteOld, editStartLine) => writeToolResult(tc, output, parsed, preWriteOld, editStartLine),
+        onToolBatchEnd: () => layout.contentWrite('\n'),
+        onNoReply: () => layout.contentWrite(`${ui.dim}(无回复)${ui.reset}\n`),
+        onMaxSteps: () => layout.contentWrite(`  ${ui.yellow}●${ui.reset} ${ui.yellow}达到最大步数(${config.maxSteps}),本轮停止。${ui.reset}\n`),
+        onAbort: () => {
+            spinner.stop();
             if (lastChar && lastChar !== '\n')
                 layout.contentWrite('\n');
-            layout.beginSegment();
-            layout.contentWrite(`${ui.dim}▎ 思考(续)${ui.reset}\n`);
-        }
-        mode = 'thinking';
-        thinkingBuffer += s;
-        layout.contentWrite(`${ui.dim}${s}${ui.reset}`);
-        if (s)
-            lastChar = s[s.length - 1];
-    };
-    const onText = (s) => {
-        flushThinkCollapsed(); // 思考→正文过渡时折叠
-        spinner.stop(); // 任何正文 token 都停 spinner(首 token 停「思考中」;onToolCall 重启后若又来文本则停「生成中」)。未旋转时 stop 为 no-op。
-        mode = 'text';
-        gotText = true;
-        layout.contentWrite(s);
-        if (s)
-            lastChar = s[s.length - 1];
-    };
-    const onToolCall = (name) => {
-        // 文本/思考已流完,模型转而生成 tool_call 参数(可能很长,如 write_file 整篇内容):
-        // 补换行(让随后的 ● 行与 diff 不黏在正文末尾)+ 启「生成中」内联 spinner,内容区不再干等。
-        if (lastChar && lastChar !== '\n') {
-            layout.contentWrite('\n');
-            lastChar = '\n';
-        }
-        if (name)
-            spinner.start(`生成 ${name}…`);
+            layout.contentWrite(`${ui.dim}(已中断)${ui.reset}\n`);
+        },
+        onDone: (elapsedMs) => layout.contentWrite(`  ${ui.dim}✻ Worked for ${fmtElapsed(elapsedMs)}${ui.reset}\n`),
     };
     try {
-        for (let step = 0; step < MAX_STEPS; step++) {
-            // 步前:接近窗口上限时自动压缩(三层)。此时 spinner 已停,通知行干净。
-            await maybeCompact(history);
-            spinner.start('思考中');
-            mode = 'idle';
-            gotText = false;
-            lastChar = '';
-            let result;
-            try {
-                result = await chat(history, { onText, onThinking, onToolCall }, signal);
-            }
-            catch (e) {
-                // 中断(用户运行中 Ctrl+C):停 spinner、补换行、提示、history 还原到本 turn 前、return(不抛)。
-                // abort 只在 await chat() 期生效;tool 执行不可中断,故不会留下未配对的 tool_call_id。
-                if (signal?.aborted ||
-                    (e instanceof Error &&
-                        (e.name === 'AbortError' || e.name === 'APIUserAbortError'))) {
-                    spinner.stop();
-                    if (lastChar && lastChar !== '\n')
-                        layout.contentWrite('\n');
-                    layout.contentWrite(`${ui.dim}(已中断)${ui.reset}\n`);
-                    history.length = 0;
-                    history.push(...savedHistory);
-                    return;
-                }
-                throw e;
-            }
-            contextState.lastUsage = result.usage; // 供 /context 与状态行显示实测 token
-            spinner.stop();
-            // lastUsage 已更新:触发状态行 context 用量条重算+重画,运行中不再冻结在轮首。
-            onContextUpdate?.();
-            if (result.toolCalls.length > 0) {
-                // 思考后直接进入 tool_call(无 text):先把可见的思考段折叠
-                flushThinkCollapsed();
-                // 流式正文末尾补换行(若 onToolCall 已补则 lastChar='\n',此处 no-op);防 ● 行黏在正文行尾
-                if (mode !== 'idle' && lastChar !== '\n')
-                    layout.contentWrite('\n');
-                // 带工具调用的 assistant 消息原样回灌(OpenAI 格式要求)
-                history.push({
-                    role: 'assistant',
-                    content: result.content,
-                    tool_calls: result.toolCalls.map((tc) => ({
-                        id: tc.id,
-                        type: 'function',
-                        function: { name: tc.name, arguments: tc.arguments },
-                    })),
-                });
-                // 工具分组执行(保 tool_calls 原顺序):连续的只读工具(READ_TOOL_NAMES)成组并发——一次性启动全部
-                // executeTool(调用即开始 I/O),再按原顺序逐个 await + 渲染(● 头与 ↳ 结果紧邻,修并行时"全 ● 后全 ↳"分离)。
-                // mutation(write_file/edit_file)及 run_command/use_skill 各为单步串行屏障——mutation 串行保
-                // recordMutation 调用序 = 回滚快照序(executeTool 内写前记 before 快照,同文件多次写需按序)。
-                // 渲染与 history 回灌一律按原顺序;并发只影响执行时序,tool_call_id 仍按序配对。
-                // executeTool 永不抛错(调度器 try/catch 返字符串),故 await 单个 promise 不会抛(永远 resolve 为字符串)。
-                const calls = result.toolCalls;
-                let i = 0;
-                while (i < calls.length) {
-                    if (READ_TOOL_NAMES.has(calls[i].name)) {
-                        // 收集连续只读组(≥1),并发执行:先一次性启动所有(executeTool 调用即开始 I/O),
-                        // 再按原顺序逐个 await + 渲染——● 头与 ↳ 结果紧邻、顺序 = tool_calls 序(修"全 ● 后全 ↳"分离 bug)。
-                        // 异步工具(web_fetch 等)并发跑、总耗时 ≈ 最慢一个;同步工具(glob/grep)map 时已顺序跑完,await 即返。
-                        let j = i;
-                        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));
-                        for (let k = 0; k < batch.length; k++) {
-                            const tc = batch[k];
-                            writeToolHeader(tc);
-                            spinner.start(`执行 ${tc.name}`);
-                            const output = await started[k];
-                            spinner.stop();
-                            writeToolResult(tc, output, null, null, 1); // 只读工具无 diff
-                            pushToolResult(history, tc, output);
-                        }
-                        i = j;
-                    }
-                    else {
-                        // 单步串行(mutation / run_command / use_skill)——逐个执行,保快照序
-                        const tc = calls[i];
-                        writeToolHeader(tc);
-                        const parsed = isMutationTool(tc.name)
-                            ? parseArgs(tc.arguments)
-                            : null;
-                        const { preWriteOld, editStartLine } = readDiffContext(tc, parsed);
-                        spinner.start(`执行 ${tc.name}`);
-                        const output = await executeTool(tc.name, tc.arguments);
-                        spinner.stop();
-                        writeToolResult(tc, output, parsed, preWriteOld, editStartLine);
-                        pushToolResult(history, tc, output);
-                        i++;
-                    }
-                }
-                continue; // 带着工具结果再调一次 LLM
-            }
-            // 思考后既无 tool_call 也无 text(纯思考):兜底折叠
-            flushThinkCollapsed();
-            if (mode !== 'idle' && lastChar !== '\n')
-                layout.contentWrite('\n'); // 流式末尾补换行
-            // 没有工具调用:流式正文即最终回复(已实时打印)
-            if (!gotText)
-                layout.contentWrite(`${ui.dim}(无回复)${ui.reset}\n`);
-            history.push({ role: 'assistant', content: result.content });
-            done = true;
-            return;
-        }
-        layout.contentWrite(`  ${ui.yellow}●${ui.reset} ${ui.yellow}达到最大步数(${MAX_STEPS}),本轮停止。${ui.reset}\n`);
-        done = true;
+        await runAgentCore({
+            history,
+            userInput,
+            signal,
+            onContextUpdate,
+            hooks,
+        });
     }
     finally {
         spinner.stop();
-        // 跑完(正常 / 达上限)在回复末尾打耗时摘要行(仿 Claude Code);中断 done=false 不打。
-        if (done) {
-            layout.contentWrite(`  ${ui.dim}✻ Worked for ${fmtElapsed(Date.now() - t0)}${ui.reset}\n`);
-        }
     }
 }

package/dist/agent/mode.js

@@ -0,0 +1,46 @@
+/**
+ * agent 模式的共享状态(零依赖纯叶子)。
+ *
+ * 把 `agentMode` 从 repl 的模块变量提到这里,让三方都能用、且不破坏依赖单向:
+ *  - `tools/builtins/switch-mode.ts` 写它(setAgentMode)——LLM 在 agent 循环里自切 plan↔auto。
+ *  - `agent/index.ts` 每步读它(getAgentMode)——决定 chat() 用全量 chatTools 还是 planChatTools 只读子集,
+ *    以及串行分支的 plan 防御 backstop。这样 LLM 中途切模式后,下一次 chat() 立即看到新工具集。
+ *  - `repl/index.ts` 读写它 + 注册 onModeChange 监听器(做 applyMode 重写 history[0] + refreshStatusBase
+ *    刷状态行 modeTag)。
+ *
+ * 依赖方向无环:本模块不 import 任何业务模块。`agent/index → tools/registry → tools/builtins/switch-mode
+ * → agent/mode` 链终点是本叶子,不回到 agent/index。`tools → agent/mode` 与既有 `tools → ui`(ask-human)、
+ * `tools → rollback`(registry)同性质——都是引叶子。
+ *
+ * listener 同步触发:setAgentMode 在变更模式后同步调 listener(无 async)。switch_mode 工具在 executeTool
+ * 内调 setAgentMode → listener 同步 applyMode(重写 history[0])+ refreshStatusBase;execute 返回字符串后,
+ * agent 串行分支继续,下一步 chat() 读到新模式 + 新系统提示,一致。
+ */
+let currentMode = 'auto';
+let listener = null;
+/** 当前 agent 模式。auto=全工具执行;plan=只读探查 + 产出计划(写盘/命令/记忆写入工具被 schema 剔除)。 */
+export function getAgentMode() {
+    return currentMode;
+}
+/**
+ * 设置 agent 模式。同模式 no-op(不触发 listener)。变更时同步触发 onModeChange 注册的监听器
+ * (repl 在 startRepl 注册:applyMode 重写 history[0] + refreshStatusBase 刷状态行)。
+ * 返回之前的模式,供调用方(如 runAgent 中断恢复)还原。
+ */
+export function setAgentMode(m) {
+    const prev = currentMode;
+    if (prev === m)
+        return prev;
+    currentMode = m;
+    try {
+        listener?.(m);
+    }
+    catch {
+        // listener 不应抛(applyMode/refreshStatusBase 都不抛);兜底,不阻断工具执行。
+    }
+    return prev;
+}
+/** 注册模式变更监听器(单一,后注册覆盖先注册)。repl 在 startRepl 启动时注册一次。 */
+export function onModeChange(cb) {
+    listener = cb;
+}

package/dist/agent/spawn.js

@@ -0,0 +1,123 @@
+// 子 agent 封装:runAgentCore + 静默 hooks。独立 history / 可受限工具子集 / 低步数上限。
+// 供 task 工具(主 agent 派生子任务)调用——子 agent 的最终摘要回灌主 history。
+//
+// 与主 agent 的区别:
+//  - 不写主屏(layout.contentWrite):中间过程(流式正文 / 工具头 / diff)缓冲到内部字符串,
+//    结束返回给 task 工具(task 把它当 tool 结果回灌主 history,主 agent 据此继续)。
+//  - 独立 history:不共享主对话,避免子任务的工具噪声污染主上下文。
+//  - 系统提示复用主 agent 组装链(config.systemPrompt + memory 段 + skills 段)+ 子 agent 角色后缀。
+//  - 工具子集:按白名单从 chatTools 过滤;无白名单 = 全量(但 task 工具调用方通常会限定只读)。
+//  - 不调 beginTurn(不进主回滚链);但文件 mutation 仍经 executeTool→recordMutation,
+//    归入当前主轮次(语义:子 agent 的改动属于当前主轮,可随 /rollback 一起撤销)。
+//  - 步数上限默认更低(config.subAgentMaxSteps ?? 50),防子任务失控耗尽配额。
+//  - 中断透传:opts.signal(主 agent 的 abort signal)透传给 runAgentCore → chat/executeTool,
+//    主 Ctrl+C 树杀子 agent(chat 流式 abort + run_command/web_fetch 即时取消)。
+//  - 逻辑隔离(回滚):skipRollback=true,子 agent 的 write_file/edit_file 改动不进主回滚快照链,
+//    主 /rollback 不撤销子 agent 改动(靠 git 兜底)。子 agent 与主 agent 共享 cwd(文件改动可见)。
+import { chatTools } from '../llm/index.js';
+import { config } from '../config/index.js';
+import { effectiveSystemPrompt } from '../skills/index.js';
+import { buildMemorySection, buildMemoryIndexSection } from '../memory/index.js';
+import { ui } from '../ui/theme.js';
+import { runAgentCore } from './core.js';
+import { summarizeToolCall, summarizeToolResult, truncateDisplay } from '../ui/render.js';
+/** 子 agent 系统提示后缀:角色与约束。 */
+const SUBAGENT_SUFFIX = `
+
+## ⛯ SUB-AGENT MODE (you are a sub-agent)
+You are a sub-agent spawned by the main agent to handle an isolated sub-task. You have your own conversation history (independent of the main thread).
+- Focus solely on the assigned sub-task. Do NOT attempt to call the "task" tool (no recursive spawning).
+- Use the tools available to you to complete the sub-task.
+- When done, your final text reply will be returned to the main agent as a summary — make it concise and actionable: what you did, key findings, files changed, and any issues. The main agent will decide the next step based on your summary.`;
+/**
+ * 派生一个子 agent 执行独立子任务。
+ *
+ * 行为:
+ *  - 构造独立 history:[{system: 主系统提示 + SUBAGENT_SUFFIX + 自定义后缀}, {user: prompt}]
+ *  - 工具子集:按 opts.tools 白名单过滤 chatTools;无白名单 = 全量。
+ *  - 静默 hooks:流式正文 / 工具头 / 结果缓冲到 transcript;不写主屏(layout)。
+ *  - 返回 { summary, completed, transcript }。summary 给 task 工具回灌主 history。
+ *
+ * 中断:opts.signal 透传给子 runAgentCore——主 Ctrl+C 树杀子 agent(chat abort + 工具 abort)。
+ * 子 agent 跑在主 signal 下,主 abort 即子 abort;子 agent 的 abortRestore 还原子 history + 模式。
+ */
+export async function spawnAgent(opts) {
+    const maxSteps = opts.maxSteps ?? config.subAgentMaxSteps ?? 50;
+    // 构造子 agent 系统提示:复用主 agent 组装链 + 子 agent 角色后缀 + 自定义后缀。
+    const systemPrompt = effectiveSystemPrompt(config.systemPrompt +
+        buildMemorySection() +
+        buildMemoryIndexSection() +
+        SUBAGENT_SUFFIX +
+        (opts.systemPromptSuffix ? `\n\n${opts.systemPromptSuffix}` : ''));
+    // 工具子集:白名单过滤。无白名单 = 全量 chatTools,但始终剔除 task(防递归派生)。
+    let toolsOverride;
+    if (opts.tools && opts.tools.length > 0) {
+        const allow = new Set(opts.tools);
+        toolsOverride = chatTools.filter((t) => allow.has(t.function.name) && t.function.name !== 'task');
+    }
+    else {
+        toolsOverride = chatTools.filter((t) => t.function.name !== 'task');
+    }
+    // 独立 history(子 agent 自己持有,不共享主对话)。
+    // 只塞 system;user 消息由 runAgentCore 的 userInput 参数 push(与主 agent 一致)。
+    const history = [
+        { role: 'system', content: systemPrompt },
+    ];
+    // 静默 hooks:缓冲中间过程到 transcript,不写主屏。
+    let transcript = '';
+    const buf = [];
+    const writeBuf = (s) => {
+        buf.push(s);
+        transcript += s;
+    };
+    let lastChar = '';
+    const hooks = {
+        onText: (s) => {
+            writeBuf(s); // 缓冲流式正文(无 markdown 渲染,原始文本)
+            if (s)
+                lastChar = s[s.length - 1];
+        },
+        onToolCall: (name) => {
+            if (lastChar && lastChar !== '\n') {
+                writeBuf('\n');
+                lastChar = '\n';
+            }
+            // 子 agent 静默:不启 spinner(name 参数仅主 agent 用)
+        },
+        onToolHeader: (tc) => {
+            const summary = summarizeToolCall(tc.name, tc.arguments);
+            writeBuf(`  ● ${tc.name}  ${summary}\n`);
+        },
+        onToolResult: (tc, output) => {
+            const preview = summarizeToolResult(tc.name, output);
+            if (preview)
+                writeBuf(`  ↳ ${preview}\n`);
+        },
+        onTextEnd: () => {
+            if (lastChar && lastChar !== '\n') {
+                writeBuf('\n');
+                lastChar = '\n';
+            }
+        },
+        onToolBatchEnd: () => writeBuf('\n'),
+        onNoReply: () => writeBuf(`${ui.dim}(无回复)${ui.reset}\n`),
+        onMaxSteps: () => writeBuf(`  ● 达到最大步数(${maxSteps}),子 agent 停止。\n`),
+        onDone: (elapsedMs) => writeBuf(`  ✻ 子 agent 耗时 ${(elapsedMs / 1000).toFixed(1)}s\n`),
+        // onStepStart / onChatDone / onToolStart / onToolDone / onAbort:子 agent 静默,无需 spinner / 中断渲染。
+        // abort 还原(history 还原 + 模式还原)由 core 的 abortRestore 处理,hooks 只管展示。
+    };
+    const result = await runAgentCore({
+        history,
+        userInput: opts.prompt,
+        signal: opts.signal, // 主 Ctrl+C 树杀子 agent(chat abort + 工具 abort)
+        hooks,
+        maxSteps,
+        toolsOverride,
+        skipRollback: true, // 逻辑隔离:子 agent 文件改动不进主回滚快照链,主 /rollback 不撤销(靠 git 兜底)
+    });
+    return {
+        summary: result.finalText,
+        completed: result.completed,
+        transcript: truncateDisplay(transcript, 20000), // 防过大;调试用,回灌主 history 的是 summary 不是 transcript
+    };
+}

package/dist/commands/config.js

@@ -1,31 +1,19 @@
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
 import * as readline from 'node:readline';
-import dotenv from 'dotenv';
-/** ~/.mocode/config:全局配置(与 ~/.mocode/skills 同目录,任意终端 / 任意目录生效)。 */
-const CONFIG_PATH = path.join(os.homedir(), '.mocode', 'config');
+import { CONFIG_PATH, readConfigFile, writeConfigKeys } from '../config/file.js';
 function ask(rl, q) {
     return new Promise((resolve) => {
         rl.question(q, (ans) => resolve(ans.trim()));
     });
 }
-/** 读已有配置(没有则空对象),用于回填默认值与保留其它键。 */
-function readExisting() {
-    try {
-        return dotenv.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
-    }
-    catch {
-        return {};
-    }
-}
 /**
  * 首跑配置向导:交互填 LLM_BASE_URL / LLM_API_KEY / LLM_MODEL,写 ~/.mocode/config。
- * 只交互三键、保留文件里其它键(MAX_TOKENS / CONTEXT_WINDOW_TOKENS 等)。prompt 全纯文本(readline 光标按字符算,不能含 ANSI)。
- * 由 index.ts 在 `mocode config` 时动态加载,故不 import config/index.ts(避免缺配置时 requireEnv 直接退出)。
+ * 只交互三键、保留文件里其它键(MAX_TOKENS / CONTEXT_WINDOW_TOKENS / MOCODE_THEME 等)。
+ * prompt 全纯文本(readline 光标按字符算,不能含 ANSI)。
+ * 由 index.ts 在 `mocode config` 时动态加载,故不 import config/index.ts(避免缺配置时 requireEnv
+ * 直接退出);只 import config/file.ts(纯 I/O 叶子,无 env 校验 / process.exit)。
  */
 export async function runConfigWizard() {
-    const cur = readExisting();
+    const cur = readConfigFile();
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     console.log(`mocode 配置向导 — 写入 ${CONFIG_PATH}(Ctrl+C 取消)\n`);
     const baseURLIn = await ask(rl, `LLM_BASE_URL${cur.LLM_BASE_URL ? ` [${cur.LLM_BASE_URL}]` : ''}(如 https://open.bigmodel.cn/api/v3): `);
@@ -46,16 +34,10 @@ export async function runConfigWizard() {
     const model = modelIn || cur.LLM_MODEL || 'gpt-4o-mini';
     rl.close();
     // 合并:保留其它键,只覆盖三键。
-    const merged = {
-        ...cur,
+    writeConfigKeys({
         LLM_BASE_URL: baseURL,
         LLM_API_KEY: apiKey,
         LLM_MODEL: model,
-    };
-    const body = Object.entries(merged)
-        .map(([k, v]) => `${k}=${v}`)
-        .join('\n');
-    fs.mkdirSync(path.dirname(CONFIG_PATH), { recursive: true });
-    fs.writeFileSync(CONFIG_PATH, `${body}\n`, 'utf8');
+    });
     console.log(`\n已写入 ${CONFIG_PATH}。现在运行 \`mocode\` 即可启动(任意目录、任意终端)。`);
 }

package/dist/config/file.js

@@ -0,0 +1,48 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import dotenv from 'dotenv';
+/**
+ * ~/.mocode/config 全局 dotenv 配置的读写叶子(纯 node:fs / node:os / node:path + dotenv)。
+ *
+ * 独立于 `config/index.ts`——**不**触发 requireEnv / process.exit,故 `commands/config.ts`
+ * (首跑向导,刻意不 import config/index.ts)与 `repl/index.ts`(`/theme` 持久化)都能安全共享。
+ * 主题等 UI 偏好走 `updateConfigKey` 单键写;向导多键一次性写走 `writeConfigKeys`。
+ */
+/** ~/.mocode/config:全局配置(与 ~/.mocode/skills 同目录,任意终端 / 任意目录生效)。 */
+export const CONFIG_PATH = path.join(os.homedir(), '.mocode', 'config');
+/** 读已有配置(没有则空对象),用于回填默认值与保留其它键。 */
+export function readConfigFile() {
+    try {
+        return dotenv.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * 读-合并-写:把 entries 覆盖进 ~/.mocode/config,保留文件里其它键。
+ * mkdirSync 兜底(首跑无 ~/.mocode)。不吞 I/O 异常——向导路径让其抛(与历史行为一致);
+ * UI 偏好路径用 `updateConfigKey`(自带 try/catch 静默)。
+ */
+export function writeConfigKeys(entries) {
+    const merged = { ...readConfigFile(), ...entries };
+    const body = Object.entries(merged)
+        .map(([k, v]) => `${k}=${v}`)
+        .join('\n');
+    fs.mkdirSync(path.dirname(CONFIG_PATH), { recursive: true });
+    fs.writeFileSync(CONFIG_PATH, `${body}\n`, 'utf8');
+}
+/**
+ * 单键持久化(主题等 UI 偏好):写失败静默——下次启动读不到则回退默认,不阻断 REPL。
+ * 注意:shell env 设了同名键时,`config/index.ts` 的 loadEnvFiles 只 backfill undefined 的
+ * process.env,故文件写对**下次启动**可能被 shell 盖——调用方据此给 dim 警告。
+ */
+export function updateConfigKey(key, value) {
+    try {
+        writeConfigKeys({ [key]: value });
+    }
+    catch {
+        // 写失败不阻断(UI 偏好)
+    }
+}