mocode-ai 0.4.9 → 0.5.0

package/dist/tools/builtins/project-skill-update.js

@@ -1,4 +1,4 @@
-import { readProjectSkill, writeProjectSkill, appendProjectSkill, } from '../../project-skill/index.js';
+import { readProjectSkill, writeProjectSkillWithCompression, appendProjectSkillWithCompression, } from '../../project-skill/index.js';
 /**
  * 项目专属 Skill 更新工具。
  * 支持三种操作:
@@ -18,7 +18,33 @@ export const projectSkillUpdateTool = {
         'Use this to record architectural patterns, naming conventions, common pitfalls, ' +
         'and key decisions specific to this project. The skill persists across sessions and ' +
         'is injected into the system prompt when MOCODE_PROJECT_SKILL=true. ' +
-        'Actions: "read" (view current content), "write" (replace all), "append" (add to end).',
+        'Actions: "read" (view current content), "write" (replace all), "append" (add to end). ' +
+        '\n\n' +
+        '## Skill 维护指南\n' +
+        'Skill 专注 Snapshot 无法自动提供的洞察知识（why/how/gotchas）。Snapshot 已提供文件结构和静态文件内容——Skill 不要重复这些信息。\n' +
+        '\n' +
+        '**Skill 该写什么（Snapshot 不能替代的）**：\n' +
+        '- 设计决策的 why（为什么这样设计、取舍是什么）\n' +
+        '- 模块行为和职责描述（怎么工作、数据流、调用链）\n' +
+        '- 常见坑点和解决方案（踩过的坑、非直觉行为、边界条件）\n' +
+        '- 项目约定（命名规范、代码风格、测试策略）\n' +
+        '- 开发流程（构建/测试/部署命令及注意事项）\n' +
+        '- 关键 API 的使用限制和特殊行为\n' +
+        '\n' +
+        '**Skill 不该写什么（交给 Snapshot）**：\n' +
+        '- 文件列表和目录结构（Snapshot 自动扫描 src 树）\n' +
+        '- 静态文件内容摘要（依赖、编译器选项等 → package.json / tsconfig.json）\n' +
+        '\n' +
+        '**何时更新**：发现新架构模式、踩坑后总结、学到新约定、完成重要重构、用户纠正理解时。\n' +
+        '\n' +
+        '**注意事项**：\n' +
+        '- 保持精简，硬上限 4000 字符（约 1000 token）\n' +
+        '- 写可操作的内容，避免空泛描述\n' +
+        '- 用具体路径和例子（不要写"有多个模块"，要写"src/agent 负责 agent 循环"）\n' +
+        '- 定期整理，删除过时信息\n' +
+        '- 更新前建议先 `read` 看一下现有内容，避免重复\n' +
+        '\n' +
+        '**自动压缩**：内容超限时会自动调用 LLM 压缩（最多 3 次），无需手动精简。',
     risk: 'safe',
     parameters: {
         type: 'object',
@@ -35,9 +61,10 @@ export const projectSkillUpdateTool = {
         },
         required: ['action'],
     },
-    execute: async (args) => {
+    execute: async (args, ctx) => {
         const action = String(args.action ?? '').trim();
         const content = String(args.content ?? '');
+        const signal = ctx?.signal;
         switch (action) {
             case 'read': {
                 const current = readProjectSkill();
@@ -50,21 +77,25 @@ export const projectSkillUpdateTool = {
                 if (!content.trim()) {
                     return 'Error: "write" action requires non-empty content parameter.';
                 }
-                const result = writeProjectSkill(content);
+                const result = await writeProjectSkillWithCompression(content, 3, signal);
                 if (!result.ok) {
                     return `Error: ${result.error}`;
                 }
-                return 'Project skill updated successfully (full replacement).';
+                return result.compressed
+                    ? 'Project skill updated successfully (full replacement, auto-compressed to fit limit).'
+                    : 'Project skill updated successfully (full replacement).';
             }
             case 'append': {
                 if (!content.trim()) {
                     return 'Error: "append" action requires non-empty content parameter.';
                 }
-                const result = appendProjectSkill(content);
+                const result = await appendProjectSkillWithCompression(content, 3, signal);
                 if (!result.ok) {
                     return `Error: ${result.error}`;
                 }
-                return 'Project skill updated successfully (appended).';
+                return result.compressed
+                    ? 'Project skill updated successfully (appended, auto-compressed to fit limit).'
+                    : 'Project skill updated successfully (appended).';
             }
             default:
                 return `Error: Unknown action "${action}". Use "read", "write", or "append".`;

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

@@ -1,8 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { MAX_FILE_LINES } from '../constants.js';
-import { lookupSnapshotFile } from '../../project-snapshot/index.js';
-import { config } from '../../config/index.js';
 /** 默认单次 read_file 拉取的行数。刻意压低,逼 LLM 分块读大文件,
  * 配合 description 中的 PAGINATION IS MANDATORY 引导。
  * 300 行 ≈ 一个屏幕的源码量,够定位一段逻辑而不至于吃光上下文。 */
@@ -31,21 +29,7 @@ export const readFileTool = {
         const offset = Number(args.offset ?? 1);
         // 无论 LLM 传多大,单次硬钳到 MAX_FILE_LINES,杜绝「绕过分页引导一把全拿」。
         const limit = Math.min(Number(args.limit ?? DEFAULT_READ_LIMIT), MAX_FILE_LINES);
-        // 项目快照 cache hit：mtime 校验通过则直接返回，省磁盘读
-        let data;
-        if (config.projectSnapshotEnabled) {
-            const absPath = resolve(path);
-            const cached = lookupSnapshotFile(absPath);
-            if (cached) {
-                data = cached.content;
-            }
-            else {
-                data = await readFile(absPath, 'utf8');
-            }
-        }
-        else {
-            data = await readFile(resolve(path), 'utf8');
-        }
+        const data = await readFile(resolve(path), 'utf8');
         const lines = data.split(/\r?\n/);
         const start = Math.max(0, offset - 1);
         const end = Math.min(lines.length, start + limit);

package/dist/tools/builtins/todolist.js

@@ -20,18 +20,38 @@ export const todolistTool = {
     name: 'todolist',
     description: [
         'Maintain a working "notepad" plan in .mocode/plans/<id>.md (file-based, survives context compression).',
-        'For complex multi-step tasks (≥3 file changes or ≥5 tool calls expected, OR user says "先计划再执行" / "plan then do"), CALL THIS FIRST to write the plan, then update each step as you go.',
-        'For simple single-step tasks, skip it and just execute.',
+        '',
+        '## PREREQUISITES (before create)',
+        'Research first: explore codebase (read-only tools) → clarify with user (ask_human) → have concrete steps.',
+        'Do NOT create prematurely — if you haven\'t done research and confirmation, stop and do that first.',
+        '',
+        '## WHEN TO USE / NOT USE',
+        'ONLY for genuinely complex tasks: ≥3 file changes, ≥5 tool calls across phases, multi-phase features,',
+        'or user explicitly requests ("先计划再执行" / "plan then do").',
+        'Skip for: single-file edits, bug fixes, quick lookups, ≤3 focused tool calls. If in doubt, just execute.',
+        '',
+        '## STEP GRANULARITY (4-5 steps max)',
+        'Each step = one meaningful execution unit (a phase, not a single tool call).',
+        'GOOD: "调研现有架构 → 设计新接口 → 实现核心逻辑 → 编写测试 → 集成验证"',
+        'BAD: "打开文件A → 修改函数X → 保存文件A → 运行测试" (too fine-grained, just do it)',
+        '',
+        '## UPDATE WORKFLOW',
+        'Update in real-time after completing each step (one step = one update, or batch_update for 2-3 at once).',
+        'Do NOT batch all updates at the end — update as you go so the chip reflects real progress.',
+        'All steps done/skipped → plan auto-finishes, archives, and chip disappears.',
+        '',
+        '## LIFECYCLE',
         'Single plan per session: create refuses if an in-progress plan already exists — finish or abandon it first.',
-        'Lifecycle: finish AUTO-ARCHIVES the plan to .mocode/plans/archive/ (history preserved, active dir stays clean). To revisit, call list with scope=archived or unarchive. Use delete to permanently remove a plan (any location).',
-    ].join(''),
+        'finish(plan_status="finished") auto-archives to .mocode/plans/archive/; use plan_status="abandoned" to abandon.',
+        'To revisit: list with scope=archived, or unarchive to bring back to active. delete permanently removes.',
+    ].join('\n'),
     parameters: {
         type: 'object',
         properties: {
             action: {
                 type: 'string',
-                enum: ['create', 'read', 'update', 'add_step', 'finish', 'list', 'delete', 'unarchive'],
-                description: 'create=新计划;read=读当前活跃;update=改步骤状态;add_step=追加步骤;finish=收尾(自动归档);list=列计划;delete=永久删除;unarchive=从归档还原到活跃',
+                enum: ['create', 'read', 'update', 'batch_update', 'add_step', 'finish', 'list', 'delete', 'unarchive'],
+                description: 'create=新计划;read=读当前活跃;update=改步骤状态;batch_update=批量改多个步骤状态;add_step=追加步骤;finish=收尾(自动归档);list=列计划;delete=永久删除;unarchive=从归档还原到活跃',
             },
             title: { type: 'string', description: 'create 必填:计划标题' },
             goal: { type: 'string', description: 'create 可选:目标描述(写进「目标」段)' },
@@ -49,9 +69,21 @@ export const todolistTool = {
                 enum: ['pending', 'in_progress', 'done', 'skipped', 'failed'],
                 description: 'update 必填:目标状态',
             },
+            updates: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        step_id: { type: 'number', description: '步骤编号' },
+                        status: { type: 'string', enum: ['pending', 'in_progress', 'done', 'skipped', 'failed'], description: '目标状态' },
+                    },
+                    required: ['step_id', 'status'],
+                },
+                description: 'batch_update 必填:批量更新数组,每项含 step_id 和 status',
+            },
             note: {
                 type: 'string',
-                description: 'update / finish 可选:追加到进度日志的一行说明(可空)',
+                description: 'update / batch_update / finish 可选:追加到进度日志的一行说明(可空)',
             },
             plan_status: {
                 type: 'string',
@@ -77,13 +109,14 @@ export const todolistTool = {
                 case 'create': return doCreate(args);
                 case 'read': return doRead();
                 case 'update': return doUpdate(args);
+                case 'batch_update': return doBatchUpdate(args);
                 case 'add_step': return doAddStep(args);
                 case 'finish': return doFinish(args);
                 case 'list': return doList(args);
                 case 'delete': return doDelete(args);
                 case 'unarchive': return doUnarchive(args);
                 default:
-                    return `错误:未知 action「${action}」,合法值:create / read / update / add_step / finish / list / delete / unarchive。`;
+                    return `错误:未知 action「${action}」,合法值:create / read / update / batch_update / add_step / finish / list / delete / unarchive。`;
             }
         }
         catch (e) {
@@ -175,9 +208,92 @@ function doUpdate(args) {
     if (!updated.steps.some((s) => s.id === stepId)) {
         return `错误:找不到 step_id=${stepId}(plan 共 ${updated.steps.length} 步)。`;
     }
+    // 自动完成:所有步骤都 done/skipped 时自动 finish + 归档 + 清 chip(LLM 常漏调 finish)
+    const allDone = updated.steps.length > 0
+        && updated.steps.every((s) => s.status === 'done' || s.status === 'skipped');
+    if (allDone && updated.status === 'in_progress') {
+        updated.status = 'finished';
+        updated.log.push({ at: localIsoTimestamp(), text: '自动完成:所有步骤已完成' });
+        if (!writePlan(updated)) {
+            setActivePlan(updated);
+            return renderSuccess('update', updated) + '\n⚠ 自动 finish 写盘失败';
+        }
+        const archived = archivePlan(updated.id);
+        clearActivePlan();
+        const archivedNote = archived
+            ? '(已自动归档到 plans/archive/)'
+            : '(⚠ 归档失败,plan 仍留在 plans/)';
+        return renderSuccess('update', updated) + `\n✓ 自动完成:所有步骤已完成 ${archivedNote}`;
+    }
     setActivePlan(updated);
     return renderSuccess('update', updated);
 }
+function doBatchUpdate(args) {
+    const cur = getActivePlan();
+    if (!cur)
+        return '错误:无活跃 plan 可 batch_update。先 create。';
+    const updates = args.updates;
+    if (!Array.isArray(updates) || updates.length === 0) {
+        return '错误:batch_update 必填 updates(非空数组,每项含 step_id 和 status)。';
+    }
+    // 验证所有更新项
+    for (const u of updates) {
+        const sid = Number(u.step_id);
+        const st = String(u.status ?? '');
+        if (!Number.isFinite(sid) || sid < 1) {
+            return `错误:updates 中某项 step_id 非法「${u.step_id}」,需 >=1 整数。`;
+        }
+        if (!VALID_STATUS.has(st)) {
+            return `错误:updates 中某项 status 非法「${st}」,合法:pending / in_progress / done / skipped / failed。`;
+        }
+    }
+    const note = String(args.note ?? '').trim();
+    const updated = updatePlan(cur.id, (p) => {
+        for (const u of updates) {
+            const sid = Number(u.step_id);
+            const st = String(u.status);
+            const step = p.steps.find((s) => s.id === sid);
+            if (step) {
+                step.status = st;
+                p.log.push({ at: new Date().toISOString(), text: `step ${sid} → ${st}` });
+            }
+        }
+        if (note)
+            p.log.push({ at: new Date().toISOString(), text: note });
+        return p;
+    });
+    if (!updated)
+        return '错误:batch_update 写盘失败。';
+    // 检查所有 step_id 是否存在
+    const missingIds = [];
+    for (const u of updates) {
+        const sid = Number(u.step_id);
+        if (!updated.steps.some((s) => s.id === sid))
+            missingIds.push(sid);
+    }
+    if (missingIds.length > 0) {
+        return `错误:batch_update 找不到 step_id=${missingIds.join(', ')}(plan 共 ${updated.steps.length} 步)。`;
+    }
+    // 自动完成:所有步骤都 done/skipped 时自动 finish + 归档 + 清 chip(LLM 常漏调 finish)
+    const allDone = updated.steps.length > 0
+        && updated.steps.every((s) => s.status === 'done' || s.status === 'skipped');
+    if (allDone && updated.status === 'in_progress') {
+        updated.status = 'finished';
+        updated.log.push({ at: localIsoTimestamp(), text: '自动完成:所有步骤已完成' });
+        if (!writePlan(updated)) {
+            setActivePlan(updated);
+            return renderSuccess('batch_update', updated) + '\n⚠ 自动 finish 写盘失败';
+        }
+        const archived = archivePlan(updated.id);
+        clearActivePlan();
+        const archivedNote = archived
+            ? '(已自动归档到 plans/archive/)'
+            : '(⚠ 归档失败,plan 仍留在 plans/)';
+        return renderSuccess('batch_update', updated) + `\n✓ 自动完成:所有步骤已完成 ${archivedNote}`;
+    }
+    setActivePlan(updated);
+    return renderSuccess('batch_update', updated);
+}
 function doAddStep(args) {
     const cur = getActivePlan();
     if (!cur)

package/dist/ui/batch.js

@@ -26,6 +26,8 @@ const MUTATION_TOOLS = new Set(['write_file', 'edit_file']);
 function isMutationTool(name) {
     return MUTATION_TOOLS.has(name);
 }
+/** 展开时完整输出的最大行数;超出截断,避免巨型输出撑爆 viewport。 */
+const MAX_EXPAND_LINES = 200;
 /** 通知 buffer 整体清空(clearContent / exitAltScreen / 新一轮 turn)——本模块状态同步归零。 */
 export function reset() {
     batches.clear();
@@ -45,8 +47,9 @@ export function recordCall(id, name, callSummary) {
         return;
     b.entries.push({ name, callSummary, resultSummary: '', diffBlock: null });
 }
-/** 记一条工具结果(diff 块或单行 preview);agent 在 onToolResult 时调,匹配最后一条未填的 entry。 */
-export function recordResult(id, name, resultSummary, diffBlock) {
+/** 记一条工具结果(diff 块或单行 preview);agent 在 onToolResult 时调,匹配最后一条未填的 entry。
+ *  fullOutput:工具原始完整输出(纯文本),展开时显示;mutation 工具的 diff 块已自含无需传。 */
+export function recordResult(id, name, resultSummary, diffBlock, fullOutput) {
     const b = batches.get(id);
     if (!b || b.entries.length === 0)
         return;
@@ -55,6 +58,7 @@ export function recordResult(id, name, resultSummary, diffBlock) {
         if (b.entries[i].name === name && !b.entries[i].resultSummary) {
             b.entries[i].resultSummary = resultSummary;
             b.entries[i].diffBlock = diffBlock;
+            b.entries[i].fullOutput = fullOutput;
             return;
         }
     }
@@ -63,17 +67,18 @@ export function recordResult(id, name, resultSummary, diffBlock) {
     if (!last.resultSummary) {
         last.resultSummary = resultSummary;
         last.diffBlock = diffBlock;
+        last.fullOutput = fullOutput;
     }
 }
 // ── 摘要行文本生成 ──
 /** 把 entry 列表压缩成一行摘要(Claude Code 风格)。 */
 function buildSummaryLine(entries) {
     if (entries.length === 0) {
-        return `  ${ui.brightMagenta}●${ui.reset} ${ui.dim}No tools${ui.reset}`;
+        return `  ${ui.bold}${ui.accent}●${ui.reset} ${ui.dim}No tools${ui.reset}`;
     }
     if (entries.length === 1) {
         const e = entries[0];
-        return `  ${ui.brightMagenta}●${ui.reset} ${ui.cyan}${e.name}${ui.reset}  ${ui.dim}${e.callSummary}${ui.reset}`;
+        return `  ${ui.bold}${ui.accent}●${ui.reset} ${ui.accent}${e.name}${ui.reset}  ${ui.dim}${e.callSummary}${ui.reset}`;
     }
     // N>1:同类合并 "read_file 3, glob 1, grep 1"
     const counts = new Map();
@@ -82,7 +87,7 @@ function buildSummaryLine(entries) {
     const parts = [];
     for (const [n, c] of counts)
         parts.push(`${n} ${c}`);
-    return `  ${ui.brightMagenta}●${ui.reset} ${ui.dim}Ran ${entries.length} tools · ${parts.join(', ')}${ui.reset}`;
+    return `  ${ui.bold}${ui.accent}●${ui.reset} ${ui.dim}Ran ${entries.length} tools · ${parts.join(', ')}${ui.reset}`;
 }
 // ── 展开/折叠 ──
 /** 把 batch 的详情行展开成自洽行数组(供 layout.contentInsertAfter 走 mid-buffer 插入)。
@@ -91,7 +96,7 @@ function buildSummaryLine(entries) {
 function buildExpandedLines(entries, indent = '    ') {
     const lines = [];
     for (const e of entries) {
-        lines.push(`${indent}${ui.brightMagenta}●${ui.reset} ${ui.cyan}${e.name}${ui.reset}  ${ui.dim}${e.callSummary}${ui.reset}\x1B[0m`);
+        lines.push(`${indent}${ui.bold}${ui.accent}●${ui.reset} ${ui.accent}${e.name}${ui.reset}  ${ui.dim}${e.callSummary}${ui.reset}\x1B[0m`);
         if (e.diffBlock) {
             // diff 块多行文本(由 renderFileChange 渲染);按 \n 拆成物理行,
             // 每行单独入 rows[]。行末 reset 由本函数统一追加(若原行已带 reset,终端合并即可)。
@@ -104,6 +109,18 @@ function buildExpandedLines(entries, indent = '    ') {
                 lines.push(line.endsWith('\x1B[0m') ? line : line + '\x1B[0m');
             }
         }
+        else if (e.fullOutput) {
+            // 完整工具输出(纯文本):按行展开,每行缩进 + dim 样式;长输出截断到 MAX_EXPAND_LINES 行
+            const rawLines = e.fullOutput.split('\n');
+            const truncated = rawLines.length > MAX_EXPAND_LINES;
+            const displayLines = truncated ? rawLines.slice(0, MAX_EXPAND_LINES) : rawLines;
+            for (const line of displayLines) {
+                lines.push(`${indent}${ui.gray}${line}${ui.reset}\x1B[0m`);
+            }
+            if (truncated) {
+                lines.push(`${indent}${ui.dim}… (${rawLines.length - MAX_EXPAND_LINES} more lines)${ui.reset}\x1B[0m`);
+            }
+        }
         else if (e.resultSummary) {
             lines.push(`${indent}${ui.gray}↳ ${e.resultSummary}${ui.reset}\x1B[0m`);
         }

package/dist/ui/content.js

@@ -136,6 +136,60 @@ export function lineAt(abs) {
     const all = snapshot();
     return abs >= 0 && abs < all.length ? all[abs] : null;
 }
+/**
+ * 找「绝对行索引 < absStart 的最近一条用户消息」的文本(用于滚动回看时的「我刚发的
+ * 请求」sticky banner)。算法:从 absStart - 1 往上扫,识别「用户气泡行」(由 repl
+ * formatUserMessage 写入,剥 SGR 后首字符 = ❯);再从此行往下吞连续的同类行
+ * 收集多行消息,join('\n')。
+ *
+ * 检测 user-bubble 行靠「剥 SGR 后以 ❯ 开头」而非 userBg SGR 前缀:rowStartSgr 继承自
+ * 上一行末(可能残留 dim/cyan),且 bubble 起手有 userBg 包裹,直接 startsWith(userBg)
+ * 在残留 rowStartSgr 场景会漏判。剥光所有 SGR 后 → 首字符稳定为 ❯ (repl.PROMPT)。
+ *
+ * 返回的文本已经剥离 ANSI + 提示符,可直接给 banner 渲染(再做截断 / 折叠)。
+ * absStart ≤ 0 返 null(没东西在视口上方)。
+ */
+export function lastUserMessageBefore(absStart) {
+    if (absStart <= 0)
+        return null;
+    const all = snapshot();
+    const SGR = /\x1B\[[0-9;]*m/g;
+    const isUserBubbleRow = (row) => {
+        // 剥光 SGR 后首字符 = ❯(repl.PROMPT 首字)→ 是 user bubble;
+        // agent 行首字符可能是 ● / ╭ / │ / 数字 / 字母,绝不会撞 ❯。
+        const visible = row.replace(SGR, '');
+        return visible.startsWith('❯');
+    };
+    // 1) 从 absStart - 1 往上扫,找第一条 user bubble 行(最近的 user-bubble 的最后一行)
+    let bubbleEnd = -1;
+    for (let i = Math.min(absStart, all.length) - 1; i >= 0; i--) {
+        if (isUserBubbleRow(all[i])) {
+            bubbleEnd = i;
+            break;
+        }
+    }
+    if (bubbleEnd < 0)
+        return null;
+    // 2) 往上找气泡起点(连续 user-bubble 行块 = 同一条 user 消息)
+    let bubbleStart = bubbleEnd;
+    while (bubbleStart - 1 >= 0 && isUserBubbleRow(all[bubbleStart - 1])) {
+        bubbleStart--;
+    }
+    // 3) 收文本:按显示字符剥 SGR + 续行/末填充空格 + 首行 prompt
+    //    首行剥前导 '❯ ' 序列 → banner 自己再加回 [banner_prompt] + <text>;
+    //    一次剥光所有重复的 ❯(防止用户手敲 prompt / 多重回显 → 出现 '❯ ❯ ...' 双提示符)。
+    const joinedText = all
+        .slice(bubbleStart, bubbleEnd + 1)
+        .map((raw, idx) => {
+        let stripped = raw.replace(SGR, '');
+        if (idx === 0)
+            stripped = stripped.replace(/^(?:❯\s*)+/, ''); // 剥光所有前导 ❯(含每个后面的可选空格)
+        return stripped.trimEnd();
+    })
+        .join('\n')
+        .replace(/\n+$/, '');
+    return joinedText || null;
+}
 /**
  * 在绝对行索引 after(0-based,已 commit)之后插入 N 条自洽行。
  * 用于「折叠摘要行下展开明细」——把详情行在已写入摘要行后面塞入缓冲,
@@ -198,3 +252,45 @@ export function deleteFrom(startIdx, n) {
         segMark.rowIdx -= actual;
     }
 }
+/**
+ * 在绝对行索引 startIdx(0-based,已 commit)起**等长替换**为新行(lines.length 必须等于
+ * 原区间行数;调用方负责等长,以维持 banner 等「顶部固定行」语义不变)。
+ *
+ * 用途:layout.writeBanner / rewriteBanner 把 buffer [0, bannerH) 替换为新的自洽行,
+ * repaintViewport 自然从 rows[] 头部读出新版 banner,无需 layout 介入。
+ *
+ * 不动 hasCurrent(行已 commit);若 segMark 在替换区间内,segMark.rowIdx 减至 startIdx
+ * (段起点被覆盖)。segMark 在区间前方不动(不在此类用法出现)。
+ *
+ * 长度不一致直接报错并 no-op(避免静默错位):允许调用方传不同长度时改用 insertAfter + deleteFrom。
+ */
+export function replaceHead(startIdx, lines) {
+    if (!Number.isInteger(startIdx) || startIdx < 0) {
+        throw new Error(`replaceHead: startIdx 必须 ≥ 0 整数,实得 ${startIdx}`);
+    }
+    if (lines.length === 0)
+        return; // 空替换 = no-op(0 行删 0 行)
+    if (hasCurrent) {
+        rows.push(rowStartSgr + curRaw + '\x1B[0m');
+        curRaw = '';
+        rowStartSgr = curSgr;
+        hasCurrent = false;
+    }
+    const committed = rows.length;
+    if (startIdx >= committed) {
+        throw new Error(`replaceHead: startIdx=${startIdx} 超出已 commit 行数 ${committed}(调用方必须保证等长替换且 startIdx 在 buffer 内)`);
+    }
+    const end = Math.min(startIdx + lines.length, committed);
+    const actualOld = end - startIdx;
+    if (actualOld !== lines.length) {
+        throw new Error(`replaceHead: 行数不匹配(startIdx=${startIdx},新区间 ${actualOld} 行 ≠ 新行 ${lines.length} 行)`);
+    }
+    // splice 等长替换:rows.length 不变,segMark 若在区间前方不受影响,区间内被覆盖时平移到 startIdx
+    rows.splice(startIdx, lines.length, ...lines);
+    if (segMark) {
+        const m = segMark.rowIdx;
+        if (m >= startIdx && m < end) {
+            segMark.rowIdx = startIdx; // 段起点被覆盖 → 重锚到区间头
+        }
+    }
+}

package/dist/ui/diff.js

@@ -215,7 +215,7 @@ export function renderFileChange(opts) {
     const pathDisp = path; // 路径原样展示(不做截断,长路径由 contentWrite 折行)
     const verb = oldStr === null ? 'Create' : 'Update';
     // 头行:Update(path) / Create(path)
-    const head = `${HEAD_INDENT}${ui.brightMagenta}${verb}${ui.reset}${ui.gray}(${ui.reset}${ui.cyan}${pathDisp}${ui.reset}${ui.gray})${ui.reset}`;
+    const head = `${HEAD_INDENT}${ui.bold}${ui.accent}${verb}${ui.reset}${ui.gray}(${ui.reset}${ui.accent}${pathDisp}${ui.reset}${ui.gray})${ui.reset}`;
     // 新建:整文件作 + 行,行号从 1
     if (oldStr === null) {
         const lines = splitLines(newStr);

package/dist/ui/intervention.js

@@ -1,7 +1,7 @@
 import readline from 'node:readline';
 import { stdin, stderr } from 'node:process';
 import { ui } from './theme.js';
-import { displayWidth, truncateDisplay, wrapByDisplayWidth } from './render.js';
+import { displayWidth, truncateDisplay, visColToCharCol, wrapByDisplayWidth } from './render.js';
 import * as layout from './layout.js';
 import * as mouse from './mouse.js';
 import { Spinner } from './spinner.js';
@@ -92,8 +92,8 @@ export async function promptIntervention(req) {
                 break;
             // 选中项:▸ 与正文均 cyan+bold(去 dim),未选中项保持 dim——选中行整体高亮。
             const isSel = idx === selected;
-            const color = isSel ? `${ui.cyan}${ui.bold}` : ui.dim;
-            const marker = isSel ? `${ui.cyan}${ui.bold}▸${ui.reset}` : ' ';
+            const color = isSel ? `${ui.accent}${ui.bold}` : ui.dim;
+            const marker = isSel ? `${ui.accent}${ui.bold}▸${ui.reset}` : ' ';
             // 数字前缀:只标真实选项(1-9,与 onKeyChoice 的数字直选对应);"自定义"项不占号。
             const numStr = idx < options.length ? `${idx + 1}. ` : '';
             const prefixWidth = 2 + numStr.length; // marker(1)+空格(1)+numStr
@@ -132,6 +132,28 @@ export async function promptIntervention(req) {
         lines.push(`${ui.dim}Enter 提交 · Esc ${cameFromChoice ? '返回选项' : '取消'} · Ctrl+C 取消${ui.reset}`);
         return lines;
     }
+    /** 鼠标左键点击输入框 → 把 cursor 移到点击位置(与 prompt.ts 的 applyExternalCursor 同源逻辑)。
+     *  intervention 的 input 只有一行 text(无 chip / 多行),算法简化:flatIdx=0,段内 visCol → charCol。 */
+    function applyExternalCursor(_flatIdx, inSegVis) {
+        if (mode !== 'input')
+            return; // choice 模式下点击输入框不移动光标(无文本可定位)
+        // 把屏幕 visCol 映射到 text 的字符偏移:wrapByDisplayWidth 复刻 paintInput 的折行,
+        // visColToCharCol 把显示列反推到字符索引(处理 CJK 全角字符)。
+        const g = layout.getGeo();
+        const promptW = displayWidth('❯ ');
+        const W = Math.max(1, g.cols - promptW);
+        const segs = wrapByDisplayWidth(text, W);
+        // _flatIdx 由 layout 端算出(点击落在哪段),这里用它定位段;越界兜底末段。
+        const seg = segs[Math.min(_flatIdx, segs.length - 1)] ?? '';
+        const inChar = visColToCharCol(seg, inSegVis);
+        // 累加前面段的字符数 → text 中的绝对偏移。
+        let offset = 0;
+        for (let i = 0; i < Math.min(_flatIdx, segs.length); i++)
+            offset += segs[i].length;
+        offset += inChar;
+        cursor = Math.max(0, Math.min(offset, text.length));
+        redraw();
+    }
     function redraw() {
         if (mode === 'choice') {
             const hint = '↑↓ 选择 · Enter 确认 · 数字键直选 · Esc 取消';
@@ -163,6 +185,7 @@ export async function promptIntervention(req) {
     /** 退出:摘自己的监听 + 恢复快照监听 + 擦菜单恢复内容区。不 setRawMode(false)/pause stdin(运行态由 repl 接管)。 */
     function cleanup() {
         layout.setMouseEnabled(true); // 恢复鼠标框选(面板期间禁,防拖拽覆盖菜单)
+        layout.setCursorChangeHandler(null); // 注销光标变更处理器
         emitter.removeListener('keypress', onKey);
         for (const l of savedListeners)
             emitter.on('keypress', l);
@@ -183,6 +206,8 @@ export async function promptIntervention(req) {
             layout.resetScroll();
         else
             layout.repaintViewport();
+        // 恢复走时计时器(RUNNING 态):面板期间 stopTurnTimer 停了心跳,退出后恢复状态行 200ms 刷新。
+        layout.startTurnTimerIfRunning();
     }
     function onKey(_str, key) {
         if (resolved || !key)
@@ -310,8 +335,10 @@ export async function promptIntervention(req) {
     return new Promise((res, rej) => {
         resolve = res;
         try {
-            // 进入面板:停 spinner(避免 onFrame 覆盖)+ 禁鼠标框选(防拖拽 viewport 重画覆盖菜单)+ 回尾(若用户正滚动回看)
+            // 进入面板:停 spinner(避免 onFrame 覆盖)+ 停走时计时器(避免 drawStatusBar 200ms 心跳
+            // 把真光标拉到 runningCaretPos 覆盖 paintInput 的正确光标位)+ 禁鼠标框选(防拖拽 viewport 重画覆盖菜单)+ 回尾(若用户正滚动回看)
             Spinner.pauseCurrent();
+            layout.stopTurnTimer();
             layout.setMouseEnabled(false);
             layout.resetScroll();
             // 快照现有 keypress 监听(运行态的 onRunningKey)并摘掉,挂自己的 onKey
@@ -328,6 +355,7 @@ export async function promptIntervention(req) {
             }
             stdin.resume();
             emitter.on('keypress', onKey);
+            layout.setCursorChangeHandler(applyExternalCursor); // 鼠标左键单击输入框 → 移光标到点击位
             redraw();
         }
         catch (e) {