mocode-ai 1.1.8 → 1.1.9

package/README.md

@@ -8,8 +8,6 @@ A terminal coding agent: give it a goal, and it **completes it autonomously**
 
 MoCode explores your code, reads/writes/edits files, runs shell commands, and searches the web on its own, driving the task forward through a loop of "think → call a tool → observe the result → think again." It works with any OpenAI-compatible endpoint (GLM, DeepSeek, Qwen, local Ollama / vLLM, etc.), runs as a full-screen TUI with streaming output and visible reasoning.
 
-## Architecture
-
 ## Engineering discipline
 
 MoCode keeps code-level control light and leaves task strategy to the agent:
@@ -82,7 +80,7 @@ MoCode isn't a chat box with a coat of paint — it's an agent that actually get
 - **Pressure-driven context compression** — Normal history keeps full tool evidence. At 80% occupancy, one scheduler event runs all enabled cleanup and always follows with a history summary. `/context` shows live usage and `/compact` remains an explicit manual override.
 - **Cross-session long-term memory** — The agent can save project architecture, conventions, and lessons learned as long-term memory, auto-loaded in future sessions. A background process periodically reflects on conversations to mine things worth remembering. Memories can be created, searched, updated, and forgotten, with recall-based decay.
 - **Project context (`MOCODE.md`)** — A single project-level memory file at `MOCODE.md` captures both static facts (project description, commands, module list, directory tree) and human/AI-written insights (conventions, architectural decisions, pitfalls). Generate it once with `/init`, then keep it up to date by hand or by asking the agent to refresh it. Loaded automatically into the system prompt on every turn.
-- **Session notepad (notes.md)** — For complex multi-step tasks (≥3 file changes / ≥5 tool calls), the agent maintains a working notepad at `.mocode/sessions/<sessionId>/notes.md` (file-based, survives context compression). It can record intermediate findings, design decisions, open questions, and structured plans. A live progress chip in the TUI status bar shows `plan: [title] (3/7) ▸ [current step]` when a `## Plan:` section is present. The agent manages the file directly with write_file/edit_file/read_file.
+- **Session notepad (notes.md)** — For complex multi-step tasks (≥3 file changes / ≥5 tool calls), the agent maintains a working notepad at `.mocode/sessions/<sessionId>/notes.md` (file-based, survives context compression). It records the execution plan with the dedicated `plan_update` tool — a three-state step machine (`pending`/`in_progress`/`completed`, at most one `in_progress`) that auto-settles to `## Done:` when finished. The active plan is re-injected into the system prompt after compaction and re-synced into context whenever notes.md changes, and a gentle reminder nudges the agent if it goes several tool-steps without updating the plan. A live progress chip in the TUI status bar shows `plan: [title] (3/7) ▸ [current step]`.
 - **Interruptible and reversible** — Ctrl+C interrupts the current turn at any time (kills child processes recursively, rolls history back to before the turn started, leaves no half-finished tool calls). `/rollback` restores file changes from per-turn snapshots, with a per-file keep/undo choice — no git dependency required.
 - **Sandbox protection** — File reads/writes go through a sandbox that blocks out-of-bounds paths (`../../`, absolute paths outside the root, symlink escapes, etc.), so the agent never touches files outside your working directory.
 
@@ -210,6 +208,7 @@ The agent operates in **the working directory it was launched from** — to have
 | `web_fetch`       | Fetch a URL, cleaning HTML into plain text                                |
 | `use_skill`       | Load the full SKILL.md instructions for a given skill                    |
 | `ask_human`        | Pop up a Q&A panel at decision points; user picks a preset or types freely (blocks until answered) |
+| `plan_update`      | Record/update the session execution plan (the `## Plan:` block in notes.md); three-state steps, at most one in_progress, auto-settles to `## Done:` when all complete |
 | `switch_mode`      | Switch between `plan` (read-only planning) and `auto` (full execution); the agent can call this itself to explore before acting |
 | `sub-agent`        | Spawn a capable isolated worker; read tasks can run concurrently and writes use overlay + ChangeSet safe merge |
 
@@ -221,12 +220,31 @@ The agent operates in **the working directory it was launched from** — to have
 
 The five `memory_*` tools are gated on `MEMORY_ENABLED=true` at startup; toggle at runtime with `/memory_switch` (REPL restart required, by design — see Skills section for the difference between Tier-1 `MOCODE.md` and Tier-2 memory).
 
+The four frontend tools — `browser`, `dev_server`, `screenshot`, `view_image` — are **off by default** (they depend on the Playwright binary, spawn long-lived processes, or capture the desktop). Enable the whole cluster at runtime with `/fe on`; the model only sees them once enabled. Toggle with `/fe on|off|status`.
+
+### Frontend / UI loop
+
+`dev_server` + `browser` form a loop of "start it → open the page → see the rendered result":
+
+```
+dev_server start  command="npm run dev"  readyUrl="http://localhost:5173"
+browser    open  →  navigate  →  click / fill  →  screenshot
+dev_server stop   id=srv-xxxx
+```
+
+- `dev_server` processes survive across tool calls (`run_command` can't — it tree-kills children on timeout or when the turn is interrupted). Readiness waiting supports `readyUrl` (loopback only) or `readyPattern` (matches startup logs); logs go to `.mocode/dev-servers/<id>.log` and support incremental reads via `offset`.
+- `browser` page sessions also persist across calls; screenshots feed back to the model through the multimodal channel, along with recent console output, page errors, and failed requests.
+- Safe defaults: `browser` only allows `http/https` on `localhost / 127.0.0.1 / ::1`, rejecting `file:` and credentialed URLs; set `MOCODE_BROWSER_ALLOW_REMOTE=true` to reach remote hosts. `dev_server` runs arbitrary commands and shares `run_command`'s `dangerous` risk class — requires user confirmation before execution.
+- Both are disabled in plan mode; on exit mocode tree-kills background processes and closes the browser.
+- The browser binary is not bundled with the npm package; run `npx playwright install chromium` before first use.
+
 ## Slash commands
 
 | Command           | Purpose                                                              |
 | ------------------ | ----------------------------------------------------------------------- |
 | `/exit` `/quit`     | Exit MoCode                                                          |
 | `/clear`            | Clear history (keeps the system prompt) + clear screen               |
+| `/image`            | Attach a local image to the next message; supports `attach <path>` / `list` / `clear` |
 | `/context`          | Show a context usage bar (tokens / message count, estimated or measured) |
 | `/skills`           | List discovered skills                                               |
 | `/compact`          | Compress history (optionally with a focus hint: `/compact …`)        |
@@ -241,6 +259,7 @@ The five `memory_*` tools are gated on `MEMORY_ENABLED=true` at startup; toggle
 | `/plan`             | Switch to plan mode (read-only exploration + plan output, approve to switch to auto) |
 | `/auto`             | Switch back to auto mode (full toolset execution)                     |
 | `/pet`              | Toggle the optional desktop pet (floating window mirroring agent state) |
+| `/fe`               | Toggle the frontend tool cluster `browser` / `dev_server` / `screenshot` / `view_image` on/off (off by default) |
 | `/pet skin`         | Pick a pet skin (↑↓ · Enter)                                          |
 | `/pet quit`         | Fully shut down the pet process (not just disconnect)                 |
 

package/README.zh-CN.md

@@ -60,8 +60,6 @@ mocode 不会在任务结束时暗中启动验证瀑布。agent 可以根据任
 
 <p align="center"><img src="./assets/architecture/pet-bridge-zh-CN.svg" alt="MoCode 桌宠桥:hooks、事件帧、Electron 客户端" width="100%"></p>
 
-## 为什么用 mocode
-
 ## 工程化纪律
 
 mocode 把代码层控制保持得尽量轻，把任务策略交给 agent：
@@ -81,7 +79,7 @@ mocode 不是一个套壳聊天框,而是一个能真正动手干活的 agent:
 - **计划 / 执行双模式** — `plan` 模式下只读探查(读代码、查索引、搜索,绝不写盘、不跑命令、不派生子 agent),产出计划;`auto` 模式全量工具放开。agent 还能在两者间自切换——先把陌生代码库摸清,再动手改。
 - **统一压力驱动压缩** — 正常 history 保留完整工具证据；达到 80% 后由一次调度事件运行所有已启用的清理，并始终继续 history 摘要。`/context` 显示实时用量，`/compact` 仍是用户显式覆盖。
 - **跨会话长期记忆** — agent 能把项目架构、约定、踩过的坑存成长期记忆,下次会话自动加载;后台还会定期从对话里反思挖掘值得记住的事。记忆可增删改、带召回衰减。
-- **会话记事本(notes.md)** — 复杂多步任务(≥3 处文件改动 / ≥5 步工具调用)时,agent 在 `.mocode/sessions/<sessionId>/notes.md` 维护一个工作记事本(落盘抗压缩),可记录中间发现、设计决策、待验证问题和结构化计划。TUI 状态栏实时显示进度 chip:`plan: [标题] (3/7) ▸ [当前步]`(当存在 `## Plan:` 段时)。agent 直接用 write_file/edit_file/read_file 管理此文件。
+- **会话记事本(notes.md)** — 复杂多步任务(≥3 处文件改动 / ≥5 步工具调用)时,agent 在 `.mocode/sessions/<sessionId>/notes.md` 维护一个工作记事本(落盘抗压缩),可记录中间发现、设计决策、待验证问题和结构化计划。执行计划由专用 `plan_update` 工具维护——三态步骤机(`pending`/`in_progress`/`completed`,同一时刻至多一个 `in_progress`),全部完成自动结算为 `## Done:`。活跃 plan 在压缩后重注入系统提示、notes.md 一变就重同步进上下文,若连续多步未更新还会有温和提醒。TUI 状态栏实时显示进度 chip:`plan: [标题] (3/7) ▸ [当前步]`。
 - **可中断、可回滚** — Ctrl+C 随时打断当前轮次(树杀子进程,历史还原到本轮开始前,不留残半的工具调用);`/rollback` 按轮次快照恢复文件改动,逐个文件「保留/撤销」,不依赖 git。
 - **沙箱防护** — 文件读写经沙箱拦截,挡掉越界路径(`../../`、绝对外圈、软链出圈等),不碰工作目录之外的文件。
 
@@ -213,6 +211,7 @@ agent 工作在**启动时所在的工作目录**——想让它操作某个项
 | `web_fetch`     | 抓取指定 URL,HTML 清洗成纯文本                                     |
 | `use_skill`     | 加载某 skill 的完整 SKILL.md 指令                                |
 | `ask_human`     | 决策点弹终端问答面板,用户选预设项或自由输入(阻塞至回应)                            |
+| `plan_update`   | 记录/更新会话执行计划(notes.md 的 `## Plan:` 段);三态步骤机,同一时刻至多一个 in_progress,全部完成自动结算为 `## Done:` |
 | `switch_mode`   | 在 `plan`(只读规划)与 `auto`(全量执行)间切换;agent 可自行调用,先探查再动手       |
 | `sub-agent`     | 派生具备完整能力的隔离子 Agent；只读任务可并发，写任务通过 overlay + ChangeSet 安全合并 |
 
@@ -238,6 +237,8 @@ dev_server stop   id=srv-xxxx
 - 两者在 plan 模式下均被禁用;mocode 退出时会树杀后台进程并关闭浏览器。
 - 浏览器二进制不随 npm 包分发,首次使用前需 `npx playwright install chromium`。
 
+这 4 个前端工具 —— `browser`、`dev_server`、`screenshot`、`view_image` —— **默认关闭**(依赖 Playwright 二进制、会拉起长驻进程或截取桌面)。运行时用 `/fe on` 整体开启,开启后模型才看得到;用 `/fe on|off|status` 切换。
+
 5 个 `memory_*` 工具受启动时 `MEMORY_ENABLED=true` 总开关控制;运行时切换用 `/memory_switch`(需重启 REPL,刻意为之,见下「项目记忆」小节区分 Tier-1 / Tier-2)。
 
 ## 斜杠命令
@@ -261,6 +262,7 @@ dev_server stop   id=srv-xxxx
 | `/plan`         | 切到 plan 模式(只读探查 + 产出计划,审批后切 auto 执行)              |
 | `/auto`         | 切回 auto 模式(全量工具执行)                                  |
 | `/pet`          | 开关桌宠(独立悬浮窗,镜像 agent 状态动画)                          |
+| `/fe`           | 切换前端工具簇 `browser` / `dev_server` / `screenshot` / `view_image` 的开关(默认关闭) |
 | `/pet skin`     | 选桌宠皮肤(↑↓ · Enter)                                  |
 | `/pet quit`     | 完全关闭桌宠进程(而非仅断开本连接)                                 |
 

package/dist/agent/core.js

@@ -5,6 +5,7 @@
 // 与 index.ts 的关系:index.ts 的 runAgent = runAgentCore + TUI hooks 薄封装(行为不变)。
 // spawn.ts 的 spawnAgent = runAgentCore + 静默 hooks(子 agent)。
 import { readFileSync } from 'node:fs';
+import { getNotesMtime } from '../session/notes.js';
 import { chat, estimatePromptTokens, planChatTools, chatTools, } from '../llm/index.js';
 import { executeToolOutcome, getToolCapabilities, isFileMutationTool, tools, } from '../tools/registry.js';
 import { checkPermission } from '../permissions/index.js';
@@ -17,13 +18,19 @@ import { createBudgetScheduler } from '../session/scheduler.js';
 import { recordArtifact, invalidateArtifacts, rehydrateArtifacts, } from '../context/index.js';
 import { createRelevancePruner } from '../context/relevance.js';
 import { isToolResultSuccess } from '../context/utils.js';
-import { config } from '../config/index.js';
+import { config, extractActivePlanSection, reinjectActivePlanIntoSystem } from '../config/index.js';
 import { t } from '../i18n/index.js';
 import { jailResolve } from '../sandbox/index.js';
 import { createLifecycleEngine } from '../context/lifecycle.js';
 import { getTokenCalibration, updateTokenCalibration, } from '../context/token-calibration.js';
 import { getCurrentTurnId, getCurrentTurnMutationState } from '../rollback/index.js';
 import { getCurrentSessionId } from '../session/state.js';
+/** nag 提醒阈值:连续 N 个"执行了工具但没更新 notes.md"的步后提醒一次(对齐 Claude Code TodoWrite 的 3 轮)。 */
+const PLAN_NAG_THRESHOLD = 3;
+/** nag 提醒文本:注入到当前步第一条 tool_result 内容前(与最新工具输出同批被模型看到,而非单独一条易被冲淡)。 */
+const PLAN_NAG_TEXT = '[mocode] Reminder: you have an active plan in notes.md but have not updated it recently. ' +
+    'If you finished a step, call plan_update to check it off (keep at most one in_progress); ' +
+    'if the whole plan is done, let plan_update settle it to ## Done:. If the plan changed scope, update it to match reality.';
 /** 解析工具 arguments JSON;非法或空返 null(调用方据此降级到普通 preview)。 */
 function parseArgs(raw) {
     try {
@@ -176,6 +183,10 @@ export async function runAgentCore(opts) {
     let done = false; // 正常完毕 / 达上限 true;中断 false(不显摘要)
     let traceStatus = 'error';
     let toolCallCount = 0;
+    // A+B(plan 可靠性):跨步计数"执行了工具但没改动 notes.md"的连续步数。
+    // 本步写了 notes.md(plan_update 或直接 write/edit)→ 清零并重同步 history[0];
+    // 否则累计,达阈值则在当前步 tool_result 前注入 nag 提醒。
+    let stepsSincePlanTouch = 0;
     // 本轮 token 累计:每步 chat() 返回后把 result.usage 累加,供 onDone 摘要行 + AgentRunResult.usage
     // 透传给 repl(显示在底栏模式 chip 右边)。未开启 include_usage 或全失败时为 undefined。
     let turnUsage;
@@ -315,6 +326,8 @@ export async function runAgentCore(opts) {
                         runtimeContextState.lifecycleStats = lifecycle.stats();
                     }
                     rehydrateArtifacts(runtimeContextState, history);
+                    // ② compact 后把活跃 plan 重注入系统提示，避免 agent 因上下文压缩丢失执行计划。
+                    reinjectActivePlanIntoSystem(history);
                 }
                 hooks.onStepStart?.(); // 主 agent:spinner.start('思考中')
                 mode = 'idle';
@@ -450,6 +463,10 @@ export async function runAgentCore(opts) {
                             function: { name: tc.name, arguments: tc.arguments },
                         })),
                     });
+                    // A+B:记录本步第一条 tool_result 的下标 + 执行前 notes.md 的 mtime,
+                    // 工具全部执行完后据此判断"本步是否改动了 notes.md"(重同步 / nag)。
+                    const toolResultStartIdx = history.length;
+                    const notesMtimeBefore = getNotesMtime();
                     // Record interstitial narration for observability only. It never changes tool output
                     // or injects instructions back into the model context.
                     const narration = result.content?.trim() ?? '';
@@ -733,6 +750,25 @@ export async function runAgentCore(opts) {
                             i++;
                         }
                     }
+                    // A(事件驱动重同步):本步若改动了 notes.md,把最新 plan 块刷回 history[0],
+                    // 让模型上下文镜像当前勾选态(不再停留在轮首的旧副本)。只在 mtime 变化时触发,零额外 churn。
+                    // B(nag 提醒):连续 N 步有工具活动但没更新 plan,在当前步第一条 tool_result 前注入提醒。
+                    const notesMtimeAfter = getNotesMtime();
+                    if (notesMtimeAfter !== notesMtimeBefore) {
+                        reinjectActivePlanIntoSystem(history);
+                        stepsSincePlanTouch = 0;
+                    }
+                    else {
+                        stepsSincePlanTouch += 1;
+                        if (stepsSincePlanTouch >= PLAN_NAG_THRESHOLD) {
+                            const activePlan = extractActivePlanSection();
+                            const firstToolMsg = history[toolResultStartIdx];
+                            if (activePlan && firstToolMsg && firstToolMsg.role === 'tool' && typeof firstToolMsg.content === 'string') {
+                                firstToolMsg.content = `${PLAN_NAG_TEXT}\n\n${firstToolMsg.content}`;
+                            }
+                            stepsSincePlanTouch = 0;
+                        }
+                    }
                     if (modelAttachments.length > 0) {
                         const names = modelAttachments.map((attachment) => attachment.name).join(', ');
                         const content = [

package/dist/agent/index.js

@@ -117,9 +117,9 @@ function flushToolBatch(expandSingleEntry = false) {
     batch.endBatch(id, layout);
     if (expandSingleEntry)
         batch.expandSingleEntryFully(id, layout);
-    // 普通摘要只有一个“当前空行”，再 break 一次把它提交为分隔空行。
-    // mutation 自动展开时 content.insertAfter 已先把该当前空行提交到 rows；若这里仍补 \n，
-    // diff 后就会固定出现两条空白行。
+    // 普通批：endBatch 留了 1 个 hasCurrent 空行，break 一次把它提交为分隔空行。
+    // mutation 自动展开：expandSingleEntryFully 自己补 separator (\n)，这里不能再补 \n，
+    // 不然 diff 后面就会出现两条空白行。
     if (!expandSingleEntry)
         layout.contentWrite('\n');
 }

package/dist/agent/spawn.js

@@ -68,6 +68,8 @@ export async function spawnAgent(opts) {
     const requested = opts.tools?.length ? new Set(opts.tools) : null;
     const readOnly = new Set(['read_file', 'glob', 'grep', 'web_search', 'web_fetch', 'use_skill', 'memory_search', 'memory_list']);
     toolsOverride = chatTools.filter((tool) => tool.function.name !== 'sub-agent' &&
+        // plan_update 直写主会话 notes.md(不走 overlay),子代理不应改动主计划——统一排除。
+        tool.function.name !== 'plan_update' &&
         (!requested || requested.has(tool.function.name)) &&
         (mode === 'write' || readOnly.has(tool.function.name)));
     // 独立 history(子 agent 自己持有,不共享主对话)。

package/dist/config/index.js

@@ -2,8 +2,8 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import dotenv from 'dotenv';
-import { getSandboxRoot } from '../sandbox/root.js';
 import { getCurrentSessionId } from '../session/state.js';
+import { getNotesFilePath } from '../session/notes.js';
 import { buildWorkDisciplineSection, inferModelFamily } from '../agent/work-discipline.js';
 import { detectLanguage, setLanguage, t, } from '../i18n/index.js';
 /**
@@ -89,11 +89,8 @@ const PLATFORM_NOTE = (() => {
  * 这样比纯目录列表更显眼，降低 agent 在长上下文里扫过去就忘了的概率。
  */
 export function buildNotepadSection(sessionId = getCurrentSessionId()) {
-    if (!sessionId)
-        return '';
-    const root = getSandboxRoot() ?? process.cwd();
-    const p = path.join(root, '.mocode', 'sessions', sessionId, 'notes.md');
-    if (!fs.existsSync(p))
+    const p = getNotesFilePath(sessionId);
+    if (!p || !fs.existsSync(p))
         return '';
     try {
         const content = fs.readFileSync(p, 'utf8').trim();
@@ -133,6 +130,55 @@ export function buildNotepadSection(sessionId = getCurrentSessionId()) {
         return '';
     }
 }
+/**
+ * 抽取 notes.md 中**唯一活跃**的 `## Plan:` 段原文（含标题行到下一个 `## ` 之前）。
+ * 用于 compact 后把计划重注入系统提示，避免 agent 因上下文压缩丢失执行计划。
+ * 已结算（`## Done:`）或无 plan 时返回 null。
+ */
+export function extractActivePlanSection(sessionId = getCurrentSessionId()) {
+    const p = getNotesFilePath(sessionId);
+    if (!p || !fs.existsSync(p))
+        return null;
+    try {
+        const normalized = fs.readFileSync(p, 'utf8').replace(/\r\n?/g, '\n');
+        const lines = normalized.split('\n');
+        const start = lines.findIndex((l) => /^## Plan:\s*.+$/.test(l));
+        if (start < 0)
+            return null;
+        const endOffset = lines.slice(start + 1).findIndex((l) => /^##\s/.test(l));
+        const end = endOffset < 0 ? lines.length : start + 1 + endOffset;
+        return lines.slice(start, end).join('\n').trimEnd();
+    }
+    catch {
+        return null;
+    }
+}
+/** compact 重注入用的幂等标记：history[0] 中夹住活跃 plan 块，重复注入只替换不累积。 */
+const ACTIVE_PLAN_MARKER = '\n\n<!-- mocode:active-plan -->\n';
+/**
+ * 把活跃 `## Plan:` 段重注入系统提示（history[0]）。compact 后调用：
+ * 若 notes.md 有活跃 plan，则覆盖旧标记块写入最新内容；若无，则清掉残留标记块。
+ * 直接改 history[0].content（compact 不破坏 index 0），幂等，返回是否改动。
+ */
+export function reinjectActivePlanIntoSystem(history) {
+    const sys = history[0];
+    if (!sys || sys.role !== 'system' || typeof sys.content !== 'string')
+        return false;
+    let content = sys.content;
+    const markerIdx = content.indexOf(ACTIVE_PLAN_MARKER);
+    if (markerIdx >= 0) {
+        content = content.slice(0, markerIdx).replace(/\s+$/, '');
+    }
+    const plan = extractActivePlanSection();
+    if (!plan) {
+        if (markerIdx < 0)
+            return false;
+        sys.content = content;
+        return true;
+    }
+    sys.content = `${content}${ACTIVE_PLAN_MARKER}${plan}\n`;
+    return true;
+}
 const SYSTEM_PROMPT_MEMORY_SECTION = `
 ## Memory (cross-session facts)
 - The prompt may contain a title/summary index; retrieve details with memory_search or inspect all with memory_list.
@@ -221,31 +267,30 @@ ${buildCodegraphSection()}
 - **No flattery / no preamble in conclusions**: skip "Sure", "好的", "我已经完成了" and similar no-information prefixes — jump straight to substance.
 - 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.
 ${t('assistant.languageInstruction')}`;
-    // 动态段(置于末尾):memory 索引 + notepad 目录与使用说明。
-    // 按需注入(#13):仅当有内容才拼对应标题/说明,避免空标题与无文件时的模板噪声。
-    //   - "## Project context" 仅当 memorySection/notepadSection 非空;
-    //   - notepad 使用说明仅当 notes.md 文件存在(notepadSection 非空)—
-    //     无文件时连 marker 都不拼,既省 token 也让前缀缓存更稳。core 切片
-    //     回退到 MARKER_DYNAMIC_SECTION 或整段(见 buildMocodeCorePrompt)。
+    // 动态段(置于末尾):memory 索引 + notepad 索引 + notepad 使用说明。
+    // 按需注入(#13):有内容的索引才拼对应标题,避免空标题噪声。
+    //   - "## Project context" 仅当 memorySection/notepadSection 非空(notepad 索引依赖 notes.md 存在);
+    //   - notepad 使用说明**无条件**注入:否则会陷入"说明依赖 notes.md 存在 → 模型不知要建 → 文件永不存在"的鸡生蛋循环,功能对模型不可见。说明放在 prompt 末尾,不影响 staticBody 的前缀缓存。
     const dynamicParts = [];
     const ctxContent = `${memorySection}${notepadSection}`.trimEnd();
     if (ctxContent) {
         dynamicParts.push(`## Project context (dynamic reference)\n${ctxContent}`);
     }
-    if (notepadSection) {
-        dynamicParts.push(`## Session Notepad (\`.mocode/sessions/${sessionId ?? '<id>'}/notes.md\`)\n` +
-            'Use this compact, persistent working surface for tasks with at least three steps or context-loss risk; skip it for simple work.\n\n' +
-            'Keep at most one active plan:\n' +
-            '```\n' +
-            '## Plan: <title>\n' +
-            'Goal: <outcome>\n' +
-            '### Steps\n' +
-            '- [ ] 1. <verifiable step>\n' +
-            '### Progress\n' +
-            '- <completed phase and evidence>\n' +
-            '```\n' +
-            'Update checkboxes and Progress after each completed phase. Before the final reply, reconcile the plan with actual work, then rename it to `## Done:` or remove it. Keep other notes concise and session-specific; use memory for stable cross-session facts.');
-    }
+    dynamicParts.push(`## Session Notepad (\`.mocode/sessions/${sessionId ?? '<id>'}/notes.md\`)\n` +
+        'Use this compact, persistent working surface for tasks with at least three steps or context-loss risk; skip it for simple work.\n\n' +
+        'Record and update the execution plan with the `plan_update` tool (preferred over editing checkboxes by hand); it keeps at most one active plan as a `## Plan:` section:\n' +
+        '```\n' +
+        '## Plan: <title>\n' +
+        'Goal: <outcome>\n' +
+        '### Steps\n' +
+        '- [ ] 1. <self-contained step: target file/symbol, the change, and how to verify>\n' +
+        '### Progress\n' +
+        '- <completed/total>\n' +
+        '```\n' +
+        'Keep at most one step in_progress, and mark a step completed as soon as its work is done — do not batch updates to the end of the turn. ' +
+        'Write each step so a teammate who lost the conversation could pick it up cold: name the file or symbol, the exact change, and the verification, so the plan survives context compaction. ' +
+        'plan_update creates notes.md for you when the task warrants it; read_file the full notes.md whenever you need to recover context after compaction. ' +
+        'When every step is completed, plan_update settles the plan to `## Done:` automatically. Keep other notes concise and session-specific; use memory for stable cross-session facts.');
     return `${staticBody}\n\n${dynamicParts.join('\n\n')}`;
 }
 /** 静态主体结束 + 会话私有段起点标记,供 buildMocodeCorePrompt 稳健切片(#17)。 */
@@ -312,6 +357,7 @@ export const config = {
     maxSteps: Number(process.env.MAX_STEPS) || 1000,
     subAgentEnabled: process.env.MOCODE_SUBAGENT_ENABLED === 'true',
     subAgentMaxSteps: Number(process.env.SUB_AGENT_MAX_STEPS) || Number(process.env.MAX_STEPS) || 1000,
+    frontendToolsEnabled: process.env.MOCODE_FRONTEND_TOOLS_ENABLED === 'true',
     sessionDir: path.join(process.cwd(), '.mocode', 'sessions'),
     searchApiKey: process.env.ANYSEARCH_API_KEY,
     sandboxRoot: process.env.SANDBOX_ROOT || undefined,
@@ -360,6 +406,15 @@ export function updateSubAgentConfig(enabled) {
     config.subAgentEnabled = enabled;
     process.env.MOCODE_SUBAGENT_ENABLED = enabled ? 'true' : 'false';
 }
+/** 前端工具簇总开关；默认 false，关闭时 browser/dev_server/screenshot/view_image 不进入模型工具表。 */
+export function isFrontendToolsEnabled() {
+    return config.frontendToolsEnabled;
+}
+/** 运行时切换前端工具簇；工具 schema 刷新与持久化由 REPL 调用方完成。 */
+export function updateFrontendToolsConfig(enabled) {
+    config.frontendToolsEnabled = enabled;
+    process.env.MOCODE_FRONTEND_TOOLS_ENABLED = enabled ? 'true' : 'false';
+}
 /**
  * 记忆子系统总开关:单一来源。/memory_switch、/memory_status、buildSystemPrompt、
  * tools/builtins/index.ts、tools/constants.ts 的 plan-mode 列表都从这里查。

package/dist/i18n/index.js

@@ -23,6 +23,10 @@ const zhCN = {
     'commands.subagentOn': '开启子 Agent',
     'commands.subagentOff': '关闭子 Agent',
     'commands.subagentStatus': '查看子 Agent 状态',
+    'commands.fe': '前端工具簇开关 browser/dev_server/screenshot/view_image（默认关闭）',
+    'commands.feOn': '开启前端工具簇',
+    'commands.feOff': '关闭前端工具簇',
+    'commands.feStatus': '查看前端工具簇状态',
     'commands.theme': '切换颜色主题（↑↓·Enter）',
     'commands.model': '模型配置与预设管理',
     'commands.modelConfigure': '配置新模型（向导）',
@@ -211,6 +215,12 @@ const zhCN = {
     'subagent.changedOn': '已开启子 Agent；sub-agent 将从下一次模型请求起可用。',
     'subagent.changedOff': '已关闭子 Agent；sub-agent 已从模型工具表移除。',
     'subagent.usage': '用法：/subagent on|off|status',
+    'fe.status': '前端工具簇：{state}',
+    'fe.stateOn': '开启',
+    'fe.stateOff': '关闭',
+    'fe.changedOn': '已开启前端工具簇；browser / dev_server / screenshot / view_image 将从下一次模型请求起可用。',
+    'fe.changedOff': '已关闭前端工具簇；browser / dev_server / screenshot / view_image 已从模型工具表移除。',
+    'fe.usage': '用法：/fe on|off|status',
     'plan.ready': '计划已就绪',
     'plan.approvalDetail': '切换到 auto 模式按上述计划执行？（plan 模式只读探查，执行需切 auto）',
     'plan.execute': '切 auto 执行',
@@ -265,6 +275,10 @@ const en = {
     'commands.subagentOn': 'Enable sub-agents',
     'commands.subagentOff': 'Disable sub-agents',
     'commands.subagentStatus': 'Show sub-agent status',
+    'commands.fe': 'Frontend tools: browser/dev_server/screenshot/view_image (disabled by default)',
+    'commands.feOn': 'Enable frontend tools',
+    'commands.feOff': 'Disable frontend tools',
+    'commands.feStatus': 'Show frontend tools status',
     'commands.theme': 'Switch color theme (↑↓·Enter)',
     'commands.model': 'Model configuration and presets',
     'commands.modelConfigure': 'Configure a new model (wizard)',
@@ -453,6 +467,12 @@ const en = {
     'subagent.changedOn': 'Sub-agents enabled; sub-agent will be available from the next model request.',
     'subagent.changedOff': 'Sub-agents disabled; sub-agent has been removed from the model tool list.',
     'subagent.usage': 'Usage: /subagent on|off|status',
+    'fe.status': 'Frontend tools: {state}',
+    'fe.stateOn': 'enabled',
+    'fe.stateOff': 'disabled',
+    'fe.changedOn': 'Frontend tools enabled; browser / dev_server / screenshot / view_image will be available from the next model request.',
+    'fe.changedOff': 'Frontend tools disabled; browser / dev_server / screenshot / view_image have been removed from the model tool list.',
+    'fe.usage': 'Usage: /fe on|off|status',
     'plan.ready': 'Plan ready',
     'plan.approvalDetail': 'Switch to auto mode and execute the plan above? (Plan mode is read-only; execution requires auto mode.)',
     'plan.execute': 'Switch to auto and execute',

package/dist/llm/index.js

@@ -1,7 +1,7 @@
 import OpenAI from 'openai';
-import { config, isSubAgentEnabled } from '../config/index.js';
+import { config, isSubAgentEnabled, isFrontendToolsEnabled } from '../config/index.js';
 import { tools } from '../tools/registry.js';
-import { getPlanDisabledTools } from '../tools/constants.js';
+import { getPlanDisabledTools, FRONTEND_TOOLS } from '../tools/constants.js';
 import { ThinkTagFilter } from './think-filter.js';
 // 强制关闭第三方调试日志泄漏:openai SDK 在 process.env.DEBUG === 'true' 时用裸
 // console.log 把请求/响应直写 stdout,会污染 TUI 输入框(并泄露 headers/URL)。
@@ -159,10 +159,14 @@ export function __setChatCreateImpl(impl) {
 export const chatTools = [];
 export const planChatTools = [];
 export function refreshChatTools() {
-    // sub-agent 常驻内部 registry，运行时开关只控制模型可见 schema，因而 on/off 可即时生效。
-    const visibleTools = isSubAgentEnabled()
-        ? tools
-        : tools.filter((tool) => tool.name !== 'sub-agent');
+    // sub-agent 与前端工具簇常驻内部 registry，运行时开关只控制模型可见 schema，因而 on/off 可即时生效。
+    const visibleTools = tools.filter((tool) => {
+        if (tool.name === 'sub-agent')
+            return isSubAgentEnabled();
+        if (FRONTEND_TOOLS.has(tool.name))
+            return isFrontendToolsEnabled();
+        return true;
+    });
     const next = visibleTools.map((t) => ({
         type: 'function',
         function: {

package/dist/repl/index.js

@@ -1,7 +1,7 @@
 import readline from 'node:readline/promises';
 import { emitKeypressEvents } from 'node:readline';
 import { stdin, stdout } from 'node:process';
-import { config, updateModelConfig, isModelConfigured, updateMemoryConfig, isMemoryEnabled, isSubAgentEnabled, updateSubAgentConfig, updateLanguageConfig, languageFromShell, buildBasePrompt, getPlanModeSuffix, hasCodegraphIndex, DEFAULT_CONTEXT_WINDOW_TOKENS, } from '../config/index.js';
+import { config, updateModelConfig, isModelConfigured, updateMemoryConfig, isMemoryEnabled, isSubAgentEnabled, updateSubAgentConfig, isFrontendToolsEnabled, updateFrontendToolsConfig, updateLanguageConfig, languageFromShell, buildBasePrompt, getPlanModeSuffix, hasCodegraphIndex, reinjectActivePlanIntoSystem, DEFAULT_CONTEXT_WINDOW_TOKENS, } from '../config/index.js';
 import { getLanguage, normalizeLanguage, t, } from '../i18n/index.js';
 import { DEFAULT_BUDGET_POLICY } from '../context/budget.js';
 import { updateConfigKey, writeConfigKeys, CONFIG_PATH } from '../config/file.js';
@@ -72,6 +72,13 @@ function buildSlashCommands() {
                 { name: 'status', value: '/subagent status', desc: d('commands.subagentStatus') },
             ],
         },
+        {
+            name: '/fe', desc: d('commands.fe'), children: [
+                { name: 'on', value: '/fe on', desc: d('commands.feOn') },
+                { name: 'off', value: '/fe off', desc: d('commands.feOff') },
+                { name: 'status', value: '/fe status', desc: d('commands.feStatus') },
+            ],
+        },
         { name: '/theme', desc: d('commands.theme') },
         {
             name: '/model', desc: d('commands.model'), children: [
@@ -1469,6 +1476,9 @@ export async function startRepl(initialHistory, sessionId, sandboxRootOverride,
             // focus 透传到 compact_history action 的 LLM 摘要 prompt。
             // 返回 SchedulerRunLog 给 UI 显示决策;退化路径(开关关时)在 manualCompact 内部走 compactHistory。
             const log = await manualCompact(history, focus, { force });
+            // ② compact 后把活跃 plan 重注入系统提示（history[0]），避免 agent 因上下文压缩丢失执行计划。
+            if (log.compactHistoryCalled)
+                reinjectActivePlanIntoSystem(history);
             const d = log.compactDetail;
             appendCurrentSessionRuntimeEvent('compact', {
                 source: 'manual',
@@ -2012,6 +2022,44 @@ export async function startRepl(initialHistory, sessionId, sandboxRootOverride,
             layout.contentWrite(`${enabled ? ui.green : ui.yellow}${t(enabled ? 'subagent.changedOn' : 'subagent.changedOff')}${ui.reset}\n`);
             continue;
         }
+        if (line === '/fe' ||
+            line.startsWith('/fe ') ||
+            line === '/frontend' ||
+            line.startsWith('/frontend ')) {
+            // /fe — 前端工具簇总开关(browser / dev_server / screenshot / view_image)。
+            // 无参切换 on/off;有参 on|off 显式;status 只读。设计同 /subagent:单一来源
+            // isFrontendToolsEnabled();关闭时 4 个工具不进模型 schema(refreshChatTools 过滤)、
+            // 运行时 getRuntimeDisabledTools 兜底拦截、plan 模式 getPlanDisabledTools 也剔除。默认 false。
+            const raw = line.startsWith('/fe ')
+                ? line.slice('/fe '.length)
+                : line.startsWith('/frontend ')
+                    ? line.slice('/frontend '.length)
+                    : line === '/frontend'
+                        ? ''
+                        : line.slice('/fe'.length);
+            const arg = raw.trim().toLowerCase();
+            if (arg === '' || arg === 'status') {
+                const enabled = isFrontendToolsEnabled();
+                const state = t(enabled ? 'fe.stateOn' : 'fe.stateOff');
+                layout.contentWrite(`${ui.accent}${t('fe.status', { state })}${ui.reset}\n` +
+                    `${ui.dim}MOCODE_FRONTEND_TOOLS_ENABLED=${enabled ? 'true' : 'false'} · ${CONFIG_PATH}${ui.reset}\n`);
+                continue;
+            }
+            if (arg !== 'on' && arg !== 'off') {
+                layout.contentWrite(`${ui.yellow}${t('fe.usage')}${ui.reset}\n`);
+                continue;
+            }
+            const enabled = arg === 'on';
+            if (enabled !== isFrontendToolsEnabled()) {
+                updateFrontendToolsConfig(enabled);
+                updateConfigKey('MOCODE_FRONTEND_TOOLS_ENABLED', enabled ? 'true' : 'false');
+                refreshChatTools();
+                history[0] = { role: 'system', content: buildSystemMessage(getAgentMode() === 'plan') };
+                layout.rewriteBanner(bannerLines(banner()));
+            }
+            layout.contentWrite(`${enabled ? ui.green : ui.yellow}${t(enabled ? 'fe.changedOn' : 'fe.changedOff')}${ui.reset}\n`);
+            continue;
+        }
         if (line === '/memory_switch' ||
             line.startsWith('/memory_switch ') ||
             line === '/memory_status' ||

package/dist/session/notes.js

@@ -0,0 +1,107 @@
+// session/notes.ts - Session Notepad(notes.md)的 plan 状态单一事实源。
+// 负责:canonical 文件路径、plan 结构化模型、markdown 渲染、以及"只替换活跃 ## Plan: 段、
+// 保留其它笔记段"的写入。被 plan_update 工具、agent core(事件驱动重同步/nag)、
+// config(notepad 索引 / compact 重注入)共用,避免路径与段解析逻辑散落多处。
+import fs from 'node:fs';
+import path from 'node:path';
+import { getSandboxRoot } from '../sandbox/root.js';
+import { getCurrentSessionId } from './state.js';
+/** 单个活跃 plan 允许的最大步骤数(防无限膨胀,对齐 Claude Code TodoWrite 的 20 上限)。 */
+export const PLAN_MAX_STEPS = 20;
+/** 当前会话 notes.md 的绝对路径;无会话时返 null。 */
+export function getNotesFilePath(sessionId = getCurrentSessionId()) {
+    if (!sessionId)
+        return null;
+    const root = getSandboxRoot() ?? process.cwd();
+    return path.join(root, '.mocode', 'sessions', sessionId, 'notes.md');
+}
+/** notes.md 的 mtime(ms),不存在或不可读返 null。供 core 判断"本步是否改动了 notes.md"。 */
+export function getNotesMtime(sessionId = getCurrentSessionId()) {
+    const p = getNotesFilePath(sessionId);
+    if (!p)
+        return null;
+    try {
+        return fs.statSync(p).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 把 plan 渲染为 canonical markdown 段(不含首尾多余空行)。
+ * 复选框格式 `- [ ] N.` / `- [x] N.` 与 repl 状态栏 chip 的计数正则严格对齐;
+ * in_progress 步骤追加 ` ◀ 当前` 后缀(仍计为未完成),让 compact 重注入后模型能直接续上。
+ * 全部完成时标题写为 `## Done:`(自动结算),extractActivePlanSection 随之返回 null。
+ */
+export function renderPlanSection(plan) {
+    const allDone = plan.steps.length > 0 && plan.steps.every((s) => s.status === 'completed');
+    const header = allDone ? `## Done: ${plan.title}` : `## Plan: ${plan.title}`;
+    const lines = [header];
+    if (plan.goal)
+        lines.push(`Goal: ${plan.goal}`);
+    lines.push('', '### Steps');
+    plan.steps.forEach((s, i) => {
+        const box = s.status === 'completed' ? '[x]' : '[ ]';
+        const suffix = s.status === 'in_progress'
+            ? `  ◀ ${(s.activeForm ?? '').trim() || 'current'}`
+            : '';
+        lines.push(`- ${box} ${i + 1}. ${s.content}${suffix}`);
+    });
+    const done = plan.steps.filter((s) => s.status === 'completed').length;
+    lines.push('', '### Progress', `- ${done}/${plan.steps.length} steps complete`);
+    return lines.join('\n');
+}
+/** 读取当前活跃 `## Plan:` 段的标题;无活跃 plan 返 null。 */
+export function readActivePlanTitle(sessionId = getCurrentSessionId()) {
+    const p = getNotesFilePath(sessionId);
+    if (!p)
+        return null;
+    try {
+        const normalized = fs.readFileSync(p, 'utf8').replace(/\r\n?/g, '\n');
+        const headerLine = normalized.split('\n').find((l) => /^## Plan:\s*.+$/.test(l));
+        return headerLine?.match(/^## Plan:\s*(.+)$/)?.[1].trim() ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 把 plan 写入 notes.md:替换已有活跃 `## Plan:` 段(原位),否则插到文件顶部;
+ * 其它所有笔记段(findings / Open Questions / 已结算 ## Done:)原样保留。
+ * 文件不存在则创建(含父目录)。返回 { path, settled } 或 { error }。
+ */
+export function writePlanToNotes(plan, sessionId = getCurrentSessionId()) {
+    const p = getNotesFilePath(sessionId);
+    if (!p)
+        return { error: 'no active session' };
+    const section = renderPlanSection(plan);
+    let existing = '';
+    try {
+        existing = fs.readFileSync(p, 'utf8').replace(/\r\n?/g, '\n');
+    }
+    catch {
+        existing = '';
+    }
+    let next;
+    const lines = existing.split('\n');
+    const start = lines.findIndex((l) => /^## Plan:\s*.+$/.test(l));
+    if (start >= 0) {
+        const endOffset = lines.slice(start + 1).findIndex((l) => /^##\s/.test(l));
+        const end = endOffset < 0 ? lines.length : start + 1 + endOffset;
+        const before = lines.slice(0, start).join('\n').replace(/\s+$/, '');
+        const after = lines.slice(end).join('\n').replace(/^\s+/, '');
+        next = [before, section, after].filter((s) => s.length > 0).join('\n\n') + '\n';
+    }
+    else {
+        const rest = existing.trim();
+        next = rest ? `${section}\n\n${rest}\n` : `${section}\n`;
+    }
+    try {
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(p, next, 'utf8');
+    }
+    catch (e) {
+        return { error: e instanceof Error ? e.message : String(e) };
+    }
+    return { path: p, settled: plan.steps.length > 0 && plan.steps.every((s) => s.status === 'completed') };
+}

package/dist/tools/builtins/index.js

@@ -12,6 +12,7 @@ import { webSearchTool } from './web-search.js';
 import { webFetchTool } from './web-fetch.js';
 import { useSkillTool } from './use-skill.js';
 import { askHumanTool } from './ask-human.js';
+import { planUpdateTool } from './plan-update.js';
 import { memorySaveTool } from './memory-save.js';
 import { memorySearchTool } from './memory-search.js';
 import { memoryListTool } from './memory-list.js';
@@ -60,6 +61,9 @@ const CAPABILITIES = {
     web_fetch: { effect: 'network', concurrency: 'parallel', supportsAbort: true },
     use_skill: { effect: 'read', concurrency: 'serial' },
     ask_human: { effect: 'read', concurrency: 'serial' },
+    // plan_update 只写内部 notes.md(session 工作面),不作为用户代码 mutation 追踪/回滚/diff;
+    // 串行即可(调用不频繁),固定资源键让并发调用排队。
+    plan_update: { effect: 'write', concurrency: 'serial', resources: () => ['session-notepad'] },
     memory_save: { effect: 'write', concurrency: 'serial', resources: memoryResource },
     memory_search: { effect: 'write', concurrency: 'serial', resources: memoryResource },
     memory_list: { effect: 'read', concurrency: 'serial', resources: memoryResource },
@@ -91,6 +95,7 @@ const rawBuiltinTools = [
     webFetchTool,
     useSkillTool,
     askHumanTool,
+    planUpdateTool,
     ..._memoryTools,
     subAgentTool,
 ];

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

@@ -0,0 +1,144 @@
+import { PLAN_MAX_STEPS, readActivePlanTitle, renderPlanSection, writePlanToNotes, } from '../../session/notes.js';
+const VALID_STATUSES = ['pending', 'in_progress', 'completed'];
+function err(message) {
+    return { status: 'error', code: 'INVALID_ARGUMENTS', retryable: false, output: `错误:${message}` };
+}
+/** 归一化模型常见的 status 变体,降低调用摩擦(无损兼容,不补造业务值)。 */
+function normalizeStatus(raw) {
+    const s = String(raw ?? 'pending').trim().toLowerCase();
+    if (['in_progress', 'in-progress', 'inprogress', 'doing', 'current', 'active', 'wip'].includes(s))
+        return 'in_progress';
+    if (['completed', 'complete', 'done', 'finished', 'checked'].includes(s))
+        return 'completed';
+    if (['pending', 'todo', 'to-do', 'open', 'not_started', 'not-started'].includes(s))
+        return 'pending';
+    return s;
+}
+export const planUpdateTool = {
+    name: 'plan_update',
+    description: 'Record and update the session execution plan (the `## Plan:` block in `.mocode/sessions/<id>/notes.md`). ' +
+        'Use for any task with 3+ steps or context-loss risk. This REPLACES the whole plan each call, so always pass the full steps array. ' +
+        'Rules: at most one step may be in_progress; mark a step completed as soon as its work is done — do not batch updates to end of turn. ' +
+        'Write each step self-contained enough to survive context compaction: name the target file/symbol, the change, and how to verify. ' +
+        'When every step is completed the plan auto-settles to `## Done:`. Creates notes.md if missing. Safe to call in PLAN mode (writes only the session notepad, never project files).',
+    risk: 'safe',
+    parameters: {
+        type: 'object',
+        properties: {
+            title: {
+                type: 'string',
+                description: 'Plan title. Required when creating a plan; omit on update to keep the current title.',
+            },
+            goal: {
+                type: 'string',
+                description: 'One-line outcome / definition of done (optional).',
+            },
+            steps: {
+                type: 'array',
+                description: `Full replacement step list (1-${PLAN_MAX_STEPS}). At most one step may be in_progress.`,
+                items: {
+                    type: 'object',
+                    properties: {
+                        content: {
+                            type: 'string',
+                            description: 'Self-contained step: target file/symbol, the change, and how to verify it.',
+                        },
+                        status: {
+                            type: 'string',
+                            enum: ['pending', 'in_progress', 'completed'],
+                            description: 'pending | in_progress | completed',
+                        },
+                        active_form: {
+                            type: 'string',
+                            description: 'Optional present-continuous label shown while in_progress (e.g. "Rewriting parser").',
+                        },
+                    },
+                    required: ['content', 'status'],
+                    additionalProperties: false,
+                },
+            },
+        },
+        required: ['steps'],
+        additionalProperties: false,
+    },
+    // 兼容模型的字段命名偏差:activeForm→active_form;step 用 text/task/description 代替 content。
+    normalizeArguments(args) {
+        if (args.activeForm !== undefined && args.active_form === undefined) {
+            args.active_form = args.activeForm;
+            delete args.activeForm;
+        }
+        if (Array.isArray(args.steps)) {
+            for (const s of args.steps) {
+                if (!s || typeof s !== 'object')
+                    continue;
+                const step = s;
+                if (step.content === undefined) {
+                    for (const alt of ['text', 'task', 'description', 'title']) {
+                        if (typeof step[alt] === 'string') {
+                            step.content = step[alt];
+                            break;
+                        }
+                    }
+                }
+                if (step.activeForm !== undefined && step.active_form === undefined) {
+                    step.active_form = step.activeForm;
+                    delete step.activeForm;
+                }
+                if (step.status !== undefined)
+                    step.status = normalizeStatus(step.status);
+            }
+        }
+    },
+    async execute(args) {
+        const rawSteps = Array.isArray(args.steps) ? args.steps : null;
+        if (!rawSteps || rawSteps.length === 0)
+            return err('steps 不能为空(至少 1 步)。');
+        if (rawSteps.length > PLAN_MAX_STEPS)
+            return err(`steps 最多 ${PLAN_MAX_STEPS} 条,当前 ${rawSteps.length} 条——请合并或拆分阶段。`);
+        const steps = [];
+        let inProgressCount = 0;
+        for (let i = 0; i < rawSteps.length; i++) {
+            const raw = rawSteps[i];
+            const content = String(raw?.content ?? '').trim();
+            if (!content)
+                return err(`第 ${i + 1} 步 content 为空。`);
+            const status = normalizeStatus(raw?.status);
+            if (!VALID_STATUSES.includes(status)) {
+                return err(`第 ${i + 1} 步 status 非法:"${String(raw?.status)}"(仅 pending/in_progress/completed)。`);
+            }
+            if (status === 'in_progress')
+                inProgressCount++;
+            const activeForm = typeof raw?.active_form === 'string' && raw.active_form.trim()
+                ? raw.active_form.trim()
+                : undefined;
+            steps.push({ content, status, ...(activeForm ? { activeForm } : {}) });
+        }
+        if (inProgressCount > 1) {
+            return err(`同一时刻只能有一个 in_progress 步骤,当前 ${inProgressCount} 个——请把其余改回 pending。`);
+        }
+        // title:新建必填;更新时缺省则沿用当前活跃 plan 的标题。
+        let title = typeof args.title === 'string' ? args.title.trim() : '';
+        if (!title) {
+            const existing = readActivePlanTitle();
+            if (!existing)
+                return err('新建 plan 需要提供 title(更新已有 plan 时可省略)。');
+            title = existing;
+        }
+        const goal = typeof args.goal === 'string' && args.goal.trim() ? args.goal.trim() : undefined;
+        const plan = { title, ...(goal ? { goal } : {}), steps };
+        const result = writePlanToNotes(plan);
+        if ('error' in result) {
+            return { status: 'error', code: 'EXECUTION_ERROR', retryable: false, output: `错误:写入 notes.md 失败: ${result.error}` };
+        }
+        const done = steps.filter((s) => s.status === 'completed').length;
+        const rendered = renderPlanSection(plan);
+        const settledNote = result.settled ? '已全部完成,自动结算为 `## Done:`。' : '';
+        return {
+            status: 'success',
+            code: 'OK',
+            retryable: false,
+            // plan_update 写内部 notes.md,不作为用户代码 mutation 上报 changedFiles。
+            output: `已更新执行计划 "${title}"(${done}/${steps.length} 完成)${settledNote}\n\n${rendered}`,
+        };
+    },
+};

package/dist/tools/constants.js

@@ -1,5 +1,5 @@
 /** 工具共享的截断 / 上限 / 忽略规则。 */
-import { isMemoryEnabled, isSubAgentEnabled } from '../config/index.js';
+import { isMemoryEnabled, isSubAgentEnabled, isFrontendToolsEnabled } from '../config/index.js';
 export const MAX_FILE_LINES = 2000;
 export const MAX_OUTPUT = 20000;
 export const MAX_RESULTS = 100;
@@ -23,6 +23,18 @@ export const GC_DAYS = 90;
 /** memory_search 结果(召回的记忆正文)的放宽上限:指令性内容,中截破坏语义,对齐 use_skill。 */
 export const MAX_MEMORY_RESULT = 64000;
 export const IGNORE = ['**/node_modules/**', '**/.git/**'];
+// ── 前端工具簇(默认关闭,显式开启)─────────────────────────────────────────
+/**
+ * 前端开发相关工具簇:browser / dev_server 依赖 playwright 二进制且拉起长驻进程,
+ * screenshot 抓整个桌面(隐私敏感),view_image 仅视觉模型有用。这 4 个默认不进入
+ * 模型工具表,由 isFrontendToolsEnabled() 单一来源控制;/fe on|off 切换。
+ */
+export const FRONTEND_TOOLS = new Set([
+    'browser',
+    'dev_server',
+    'screenshot',
+    'view_image',
+]);
 // ── plan 模式(只读规划,不执行)──────────────────────────────────────────────
 /**
  * plan 模式下从工具 schema 里剔除的工具(模型根本看不到 → 调不到):
@@ -50,15 +62,30 @@ export const PLAN_DISABLED_TOOLS = new Set([
  * 调用方(agent/core 串行分支、llm/planChatTools)每次 chat 时调本函数拿当前值。
  */
 export function getPlanDisabledTools() {
-    if (isMemoryEnabled())
-        return PLAN_DISABLED_TOOLS;
-    const next = new Set(PLAN_DISABLED_TOOLS);
-    next.delete('memory_save');
-    next.delete('memory_update');
-    next.delete('memory_forget');
+    const next = isMemoryEnabled()
+        ? new Set(PLAN_DISABLED_TOOLS)
+        : (() => {
+            const n = new Set(PLAN_DISABLED_TOOLS);
+            n.delete('memory_save');
+            n.delete('memory_update');
+            n.delete('memory_forget');
+            return n;
+        })();
+    // 前端工具簇关闭时,plan 模式 schema 也一并剔除(与 auto 模式一致)。
+    if (!isFrontendToolsEnabled()) {
+        for (const name of FRONTEND_TOOLS)
+            next.add(name);
+    }
     return next;
 }
 /** auto/plan 共用的运行时功能开关防线；关闭时即使模型幻觉调用也不得执行。 */
 export function getRuntimeDisabledTools() {
-    return isSubAgentEnabled() ? new Set() : new Set(['sub-agent']);
+    const disabled = new Set();
+    if (!isSubAgentEnabled())
+        disabled.add('sub-agent');
+    if (!isFrontendToolsEnabled()) {
+        for (const name of FRONTEND_TOOLS)
+            disabled.add(name);
+    }
+    return disabled;
 }

package/dist/ui/batch.js

@@ -249,6 +249,9 @@ export function expandSingleEntryFully(id, layout) {
         ...buildEntryDetailLines(b.entries[0], entryDetailIndent(b.entries, 0)),
     ];
     layout.contentInsertAfter(b.summaryAbsIdx, lines);
+    // 修复：contentInsertAfter 不再 commit was-current（避免 collapse 后留孤儿空行）；
+    // mutation 路径不再由 flushToolBatch 写 \n separator，所以这里手动补一个 \n。
+    layout.contentWrite('\n');
     expandedBatches.add(id);
     b.expandedEntries.add(0);
     absLineToEntry.set(b.summaryAbsIdx + 1, { batchId: id, entryIndex: 0 });

package/dist/ui/content.js

@@ -227,18 +227,21 @@ export function lastUserMessageBefore(absStart) {
  * 若 segMark 活跃且插入点在 segMark.rowIdx 之前,则 segMark.rowIdx 跟着平移(否则
  * 流式 md 段活跃期间展开/折叠 batch 后,下一个 md chunk 的 setLines 截断到错误位置)。
  *
- * 后置条件:插入后 hasCurrent=false(新空行不由本函数建立);调用方须自行决定续写位
- * (BatchRenderer 在插入后调 layout.contentWrite 续写,新 \n 自然在详情块后建新行)。
+ * 后置条件:插入后 hasCurrent 保持不变(若进来时 hasCurrent=true，则仍为 true),
+ * curRaw 也保持不变 —— cursor 概念上跟到 inserted block 末尾,后续 contentWrite 自然续写。
+ * 关键:不再"先 commit 当前行到 rows 末尾再 splice",那样会在 rows 末尾留下
+ * 一条 was-current 孤儿空行,在后续 collapse 删除 inserted lines 时无法被对称清掉,
+ * 导致下一段文本与该批之间多出 1 行视觉空白(用户报告:「展开又关闭工具信息后
+ * 下面空两行」)。现在 leave cursor 不动，由调用方按需补 separator。
+ * 例外：expandSingleEntryFully (mutation 自动展开) 在调用本函数后
+ * 主动 layout.contentWrite('\n') 写 separator blank,
+ * 因为 mutation 不走 flushToolBatch 的 \n。
  */
 export function insertAfter(after, lines) {
     if (lines.length === 0)
         return;
-    if (hasCurrent) {
-        rows.push(rowStartSgr + curRaw + '\x1B[0m');
-        curRaw = '';
-        rowStartSgr = curSgr;
-        hasCurrent = false;
-    }
+    // 修复:不再提交 was-current 行到 rows 末尾(避免后续 collapse 后留孤儿空白)。
+    // cursor 留在原位置(指向 spliced block 之后);调用方按需显式 contentWrite('\n') 补 separator。
     const committed = rows.length;
     // after 是绝对行索引;若超过 committed(例如快照时 hasCurrent=true),钳到末尾
     const target = after < 0 ? 0 : Math.min(after + 1, committed);
@@ -254,19 +257,19 @@ export function insertAfter(after, lines) {
 /**
  * 从绝对行索引 startIdx(0-based,已 commit)起删 n 行。
  * 用于「已展开明细折回摘要」——把详情行从中段裁掉,保留摘要行和后续内容。
- * startIdx 越界或 n <= 0 直接 no-op。hasCurrent 时先 commit(同 insertAfter)。
+ * startIdx 越界或 n <= 0 直接 no-op。
  *
- * 后置条件:删除后 hasCurrent=false。后续 layout.contentWrite 自然续写。
+ * 不动当前行(同 insertAfter 修复后的语义):cursor 概念上仍指向 spliced
+ * 区间后的同一绝对位置(若 startIdx+1+lines 数 ≥ 新 rows.length,curRaw
+ * 代表的就是 spliced 区间内的逻辑行,内容保留)。
+ * 后置条件:hasCurrent 与 curRaw 与调用前一致。
  */
 export function deleteFrom(startIdx, n) {
     if (n <= 0)
         return;
-    if (hasCurrent) {
-        rows.push(rowStartSgr + curRaw + '\x1B[0m');
-        curRaw = '';
-        rowStartSgr = curSgr;
-        hasCurrent = false;
-    }
+    // 修复：保持与 insertAfter 对称——不动 hasCurrent/curRaw，避免 splice 后
+    // 把 was-current 空行当成普通行 commit 变成孤儿（与 insertAfter 的孤儿
+    // bug 是同一个根因的两个对称面）。
     const committed = rows.length;
     if (startIdx >= committed)
         return;

package/dist/ui/layout.js

@@ -83,11 +83,12 @@ let statusText = '';
 let spinnerFrame;
 let turnStart = null; // RUNNING 态起点(Date.now());INPUT 态为 null。composeStatus 据此拼走时。
 let turnTimer = null; // 走时刷新计时器(独立于 spinner):流式期间 spinner 停转,由它续刷状态行。
-// 运行态状态行 chip 心跳帧(♥/♡ 明灭)。turnTimer 每 tick 推进一帧,让状态行前导符在 agent
-// 运行时跳动——agent 的 spinner 走内容区续写位(paintLiveAtCursor),不调 setStatus,
-// 故状态行 chip 靠 turnTimer 独立驱动。INPUT 态 runningFrame=-1,composeStatus 退回静态 ●。
+/** 当前 plan chip 占用脚栏行数(1 或 2)。composePlanLines 每次重算后写入。
+ *  驱动 paintInput setRegion(fh) 动态撑高脚栏;drawStatusBar 据此画 1/2 行 plan,
+ *  与 spinner/上线/输入/下线/model 行的 +1/+2/+3/+4/+5 偏移天然一致(contentBottom 自动重算)。 */
+let planRows = 1;
+let runningFrame = -1; // 运行态状态行 chip 心跳帧(♥/♡ 明灭);INPUT 态 -1 退回静态 ●
 const RUNNING_FRAMES = ['♥', '♡'];
-let runningFrame = -1;
 // 运行态用户打字时暂停流式物理写:流式每个 token 要 cup 到 contentRow 写入,IME 候选窗逐光标移动跟踪会跟过去;
 // 用户打字期间只喂缓冲、不物理写,光标留输入框;停手 USER_ACTIVE_PAUSE_MS 后 flush 重画缓冲内容。
 let userActiveUntil = 0; // 打字活跃截止时刻(Date.now()+PAUSE);0=未活跃
@@ -179,12 +180,12 @@ export function setRegion(fh) {
         contentRow = g.contentBottom; // 底栏撑高挤掉内容:钳到新区底
     return g;
 }
-/** 运行态真光标(隐藏)的归位点 = 输入框光标位:行 = 动态 contentBottom+4(resize 安全)。
+/** 运行态真光标(隐藏)的归位点 = 输入框光标位:行 = 动态 contentBottom+3+planRows(resize 安全)。
  *  非 dim 运行态(与空闲态同色、可任意位置编辑)→ 归当前编辑位,供 IME 锚定气泡到光标处;
  *  dim 占位(空 + placeholder)兼容态→ 归输入框起点。供 IME 锚定。 */
 function runningCaretPos() {
     const g = getGeo();
-    const row = g.contentBottom + 4;
+    const row = g.contentBottom + 3 + planRows;
     if (lastView && !lastView.dim) {
         const promptW = displayWidth(lastView.prompt);
         const line = lastView.lines[lastView.cursorLine] ?? '';
@@ -956,8 +957,8 @@ function clearInputSelection() {
 /** 屏行是否落在底栏输入行范围内(paintInput 的 firstInputRow..firstInputRow+inputRowsAvail-1)。 */
 function isInputRow(row) {
     const g = getGeo();
-    const firstInputRow = g.contentBottom + 4;
-    const inputRowsAvail = Math.max(0, g.footerH - 5);
+    const firstInputRow = g.contentBottom + 3 + planRows;
+    const inputRowsAvail = Math.max(0, g.footerH - 4 - planRows);
     return row >= firstInputRow && row < firstInputRow + inputRowsAvail;
 }
 /** 右键单击输入行(未拖动的 press→release):读剪贴板 + 回调 pasteHandler 贴入。异步但不阻塞其他事件。 */
@@ -1023,8 +1024,8 @@ function inputScreenToInputPos(screenRow, screenCol) {
         return null;
     const g = getGeo();
     const promptW = displayWidth(lastView.prompt);
-    const firstInputRow = g.contentBottom + 4;
-    const inputRowsAvail = Math.max(0, g.footerH - 5);
+    const firstInputRow = g.contentBottom + 3 + planRows;
+    const inputRowsAvail = Math.max(0, g.footerH - 4 - planRows);
     // 输入框可视区的 (visRow, visCol) 屏幕坐标 → 0-based。
     // 点到可视区末行之下(空白区)→ 落到最末可视行(光标归最后一段);isInputRow 已挡可视区之上的点击。
     const visRow = Math.max(0, Math.min(screenRow - firstInputRow, Math.max(0, inputRowsAvail - 1)));
@@ -1454,34 +1455,62 @@ function formatLiveUsageChip(u) {
     return `${ui.dim}↑ ${fmt(billable)} ↓ ${fmt(u.completionTokens)}${cacheTag}${ui.reset}`;
 }
 /** spinner 行上方的「虚拟空行」(contentBottom+1)。
- *  - 有活跃 plan:显「plan: <summary> ▸ N. step」整行左对齐(yellow + dim)
+ *  - 有活跃 plan:显「plan: <summary> ▸ N. step」整行左对齐(yellow)
  *  - 无活跃 plan:空(保留原分隔视觉,避免内容贴输入区)
+ *  - 过长(> cols):始终**截断保 1 行 + "…"**,不撑高脚栏、不拆 2 行——
+ *    步进式任务标题/current step 通常是自然语言,即使切「 ▸ 」拆 2 行,第 2 行也大概率仍超长
+ *    (实测「第三步:实现核心业务模块。…」本身就比 cols 长),拆完依然覆盖 spinner/输入区,得不偿失。
+ *    截断 + "…" 一行内永远不溢出,脚栏恒 6 行,spinner/输入/下线/model 行偏移稳定。
  *  这行在 DECSTBM 滚动区外([1, contentBottom]),稳定不滚。 */
-function composePlanLine(status, cols) {
+function composePlanLines(status, cols) {
     const plan = (status.planSummary ?? '').trim();
-    if (!plan)
-        return ''; // 无 plan:画空,等 paint 路径 clearLine
-    // 整行左对齐,不留右段(plan 自带进度信息,不需要 cwd)
-    return `${ui.yellow}${plan}${ui.reset}`;
+    if (!plan) {
+        planRows = 1;
+        return [];
+    }
+    const w = displayWidth(stripAnsi(plan));
+    if (w <= cols) {
+        planRows = 1;
+        return [`${ui.yellow}${plan}${ui.reset}`];
+    }
+    // 溢出:截断为 1 行 + "…" 后缀(留 1 列空间给省略号)。
+    planRows = 1;
+    return [`${ui.yellow}${truncateDisplay(plan, Math.max(1, cols - 1))}…${ui.reset}`];
 }
 /** 画状态行(plan 行 + spinner 行 + model 行,三行)。RUNNING 态 spinner 频繁调。
- *  行号(footerH=6):
- *    plan 行     = contentBottom+1  (活跃 plan 时显 chip;无则空)
- *    spinner 行  = contentBottom+2  (● 空闲 / ⠹ 思考中… / etc)
- *    上线        = contentBottom+3  (画在 paintInput)
- *    输入行      = contentBottom+4
- *    下线        = contentBottom+5
- *    model 行    = rows              (屏底:auto + ctx + cwd) */
+ *  行号(footerH=6 当 plan 单行;footerH=7 当 plan 撑 2 行):
+ *    plan 行     = contentBottom+1          (单行)
+ *    plan 第 2 行 = contentBottom+2          (双行,可选)
+ *    spinner 行  = contentBottom+1+planRows  (● 空闲 / ⠹ 思考中… / etc)
+ *    上线        = contentBottom+2+planRows  (画在 paintInput)
+ *    输入行      = contentBottom+3+planRows
+ *    下线        = contentBottom+4+planRows
+ *    model 行    = rows                       (屏底:auto + ctx + cwd) */
 export function drawStatusBar(status) {
     if (!active || !base)
         return;
     const s = status ?? { ...base, status: statusText, spinnerFrame };
     const g = getGeo();
-    const planRow = g.contentBottom + 1;
-    const spinnerRow = g.contentBottom + 2;
+    const planLines = composePlanLines(s, g.cols);
+    const planRow1 = g.contentBottom + 1;
+    const spinnerRow = g.contentBottom + 1 + planRows;
     const modelRow = g.rows; // 屏底:model 行
-    // 一次写入:三行 cup+clear+内容,末尾 cup 回续写位/输入框光标
-    let out = cup(planRow, 1) + esc.clearLine + composePlanLine(s, g.cols) +
+    // plan 可能占 1 或 2 行(过长自动撑开);spinner/model 行随之平移。
+    // 一次写入:plan 1/2 行 + spinner 行 + model 行,末尾 cup 回续写位/输入框光标。
+    let planBuf = '';
+    for (let i = 0; i < planLines.length; i++) {
+        planBuf += cup(planRow1 + i, 1) + esc.clearLine + planLines[i];
+    }
+    // 计划行从 2 行降到 1 行时,清掉残留的第 2 行(撑高后回退不留尾巴)。
+    if (planRows === 1 && g.footerH > 6) {
+        planBuf += cup(planRow1 + 1, 1) + esc.clearLine;
+    }
+    // plan 从非空变成空(已结算为 ## Done:/ notes 里无活跃 ## Plan: 段)时,清掉残留的 plan 行 1。
+    // 否则上轮渲染的「plan: 标题 (N/M) ▸ 当前步」会卡在底栏「虚拟空行」位置直到下一次重启 REPL。
+    if (planLines.length === 0) {
+        planBuf += cup(planRow1, 1) + esc.clearLine;
+    }
+    let out = planBuf +
         cup(spinnerRow, 1) + esc.clearLine + composeSpinnerLine(s, g.cols) +
         cup(modelRow, 1) + esc.clearLine + composeModelLine(s, g.cols);
     if (mode === 'running') {
@@ -1743,7 +1772,7 @@ export function paintInput(view) {
             startVis: 0,
         }
         : windowInputVis(view.lines, view.cursorLine, view.cursorCol, preGeo.cols, promptW, preGeo.rows);
-    const needFooterH = 5 + vis.inputRows; // 1 虚拟空 + 1 spinner 行 + 1 上线 + 输入行 + 1 下线 + 1 model 行
+    const needFooterH = 5 + vis.inputRows + (planRows - 1); // 1 虚拟空 + 1 spinner 行 + 1 上线 + 输入行 + 1 下线 + 1 model 行 + plan 多出的行数
     let g = preGeo;
     if (needFooterH !== footerH) {
         // setRegion 自己 write(DECSTBM + 清行 + 归位):先把已累积的擦除 flush 出去保序(擦除用的是旧几何的
@@ -1764,23 +1793,35 @@ export function paintInput(view) {
     // 2c. 虚拟空行(内容区与状态栏之间的视觉间隔,属底栏非内容):
     //     - 无活跃 plan:清空保留作分隔(原设计)
     //     - 有活跃 plan:渲染 plan chip(整帧重画时也要更新,避免 listener 漏触发后残留)
+    //     - plan 过长:占 2 行(planRows=2),spinner/上线/输入行随之整体下移 1 行
+    //     paintInput 与 drawStatusBar 共享同一 planRows 模块态,setRegion 已据此把脚栏撑高。
     {
-        const plan = (base.planSummary ?? '').trim();
-        buf += cup(g.contentBottom + 1, 1) + esc.clearLine;
-        if (plan)
-            buf += `${ui.yellow}${plan}${ui.reset}`;
+        const planBuf = composePlanLines(base, preGeo.cols);
+        for (let i = 0; i < planBuf.length; i++) {
+            buf += cup(g.contentBottom + 1 + i, 1) + esc.clearLine + planBuf[i];
+        }
+        // 计划行从 2 行降到 1 行(plan 当前很短):清掉残留的第 2 行,不留尾巴。
+        if (planBuf.length < planRows && planRows === 2) {
+            buf += cup(g.contentBottom + 2, 1) + esc.clearLine;
+            planRows = 1;
+        }
+        // plan 从非空变成空(已结算/无活跃段)时,清掉残留的 plan 行 1。
+        // 上面 for 循环在 planBuf.length===0 时不写任何 cup,需要显式清一行回到「虚拟空行」。
+        if (planBuf.length === 0) {
+            buf += cup(g.contentBottom + 1, 1) + esc.clearLine;
+        }
     }
     // 3. 状态行:spinner 行 + model 行(两行式底栏)
-    const spinnerRow = g.contentBottom + 2; // +1 虚拟空行(plan 行),+2 spinner 行
+    const spinnerRow = g.contentBottom + 1 + planRows; // plan 占 planRows 行(1 或 2),spinner 紧跟其后
     const modelRow = g.rows; // 屏底:model 行
     const status = { ...base, status: statusText, spinnerFrame };
     buf += cup(spinnerRow, 1) + esc.clearLine + composeSpinnerLine(status, g.cols);
     buf += cup(modelRow, 1) + esc.clearLine + composeModelLine(status, g.cols);
     // 3b. 上线(输入框顶):满屏宽细线 ─(cyan),框住输入区上边界
-    buf += cup(g.contentBottom + 3, 1) + esc.clearLine + ui.accent + '─'.repeat(g.cols) + ui.reset;
-    // 4. 输入行(g.contentBottom+4 .. rows-1)——按可视行画,首行带 prompt、其余缩进 promptW
-    const firstInputRow = g.contentBottom + 4;
-    const inputRowsAvail = g.footerH - 5; // 去掉虚拟空/spinner行/上线/下线/model行,留输入行
+    buf += cup(g.contentBottom + 2 + planRows, 1) + esc.clearLine + ui.accent + '─'.repeat(g.cols) + ui.reset;
+    // 4. 输入行(g.contentBottom+3+planRows .. rows-1)——按可视行画,首行带 prompt、其余缩进 promptW
+    const firstInputRow = g.contentBottom + 3 + planRows;
+    const inputRowsAvail = vis.inputRows; // 脚栏总高 - 1(spinner) - 1(上 sep) - 1(下 sep) - 1(model) - planRows
     const indent = ' '.repeat(promptW);
     // 光标:不画反白块/假光标——输入框走终端真光标(WT / VSCode 终端默认竖线/闪烁块,
     // 各终端表现略不同但都贴合 IME 候选气泡且不再"挡住字符")。真光标位置由下方第 6 步 cup 写。
@@ -1919,7 +1960,7 @@ export function paintRunningInput(text, cursor, placeholder) {
     if (!active || !base)
         return;
     const g = getGeo();
-    const inputRow = g.contentBottom + 4; // 运行态 footerH 恒 6(单行,无 setRegion)
+    const inputRow = g.contentBottom + 3 + planRows; // 运行态 footerH 随 plan 行数动态(6 或 7)
     const promptW = displayWidth('❯ ');
     const contentW = Math.max(1, g.cols - promptW);
     let outLine;
@@ -1976,7 +2017,10 @@ export function enterInputMode(status = t('repl.idle')) {
             repaintViewport();
     }
     if (active && base) {
-        setRegion(6); // 1 虚拟空 + 1 spinner行 + 1 上线 + 1 输入 + 1 下线 + 1 model行(两行式底栏)
+        // 先按当前 base.planSummary 重算 planRows(可能从上次会话残留 stale 值),再据此 setRegion
+        // 撑出正确脚栏高;否则 plan 撑 2 行时 setRegion(6) 会把 spinner 挤到 plan 第 2 行位置。
+        composePlanLines(base, (getGeo()).cols);
+        setRegion(4 + planRows + 1); // 1 虚拟空 + 1 spinner行 + 1 上线 + 1 输入 + 1 下线 + 1 model行 + plan 多出的行
         paintInput({
             prompt: '❯ ',
             lines: [''],
@@ -1996,7 +2040,10 @@ export function enterRunningMode(status, placeholder) {
     resetScroll(); // 若上轮 INPUT 滚动过(未打字回底),新轮回尾
     lockScrollToBottom(); // 轮首短时锁:吸收发消息前后残留滚轮事件,保 agent 输出从底部开始(锁过期或轮末 enterInputMode 解)
     if (active && base) {
-        setRegion(6); // 1 虚拟空 + 1 spinner行 + 1 上线 + 1 输入 + 1 下线 + 1 model行
+        // 先按当前 base.planSummary 重算 planRows(可能从上次会话残留 stale 值),再据此 setRegion
+        // 撑出正确脚栏高;否则 plan 撑 2 行时 setRegion(6) 会把 spinner 挤到 plan 第 2 行位置。
+        composePlanLines(base, (getGeo()).cols);
+        setRegion(4 + planRows + 1); // 1 虚拟空 + 1 spinner行 + 1 上线 + 1 输入 + 1 下线 + 1 model行 + plan 多出的行
         paintInput({
             prompt: '❯ ',
             lines: [''],
@@ -2021,7 +2068,11 @@ export function enterAltScreen() {
     applyTerminalBackground();
     stdout.write(esc.mouseOn); // 完整鼠标追踪(按下/拖动/释放/滚轮)→ mouse.swallow 重组 → handleMouseEvent
     mouse.setHandler(handleMouseEvent);
-    setRegion(6); // 1 虚拟空 + 1 spinner行 + 1 上线 + 1 输入 + 1 下线 + 1 model行(两行式底栏)
+    // 进入 alt screen 前 base 可能已设了 planSummary;按当前 planSummary 重算 planRows,
+    // 让首次 setRegion 撑出正确脚栏高(否则 plan 撑 2 行时会被 spinner 行覆盖)。
+    if (base)
+        composePlanLines(base, (getGeo()).cols);
+    setRegion(4 + planRows + 1); // 1 虚拟空 + 1 spinner行 + 1 上线 + 1 输入 + 1 下线 + 1 model行 + plan 多出的行
     contentRow = 1;
     contentCol = 1;
     segmentStartRow = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mocode-ai",
-  "version": "1.1.8",
+  "version": "1.1.9",
   "description": "终端编码 agent:LLM + tool-call 循环 + 流式输出(含思考)+ 16 个工具,接任意 OpenAI 兼容后端。",
   "type": "module",
   "bin": {