mocode-ai 1.5.11 → 1.5.13

package/README.md

@@ -110,7 +110,7 @@ MoCode isn't a chat box with a coat of paint — it's an agent that actually get
 - **Session persistence** — Every turn is saved automatically; `--resume` / `/resume` picks up a past session.
 - **Skills system** — Scans directories like `~/.mocode/skills/` automatically; each skill's description is injected into the system prompt, and the model calls `use_skill` to load the full instructions only when relevant (progressive disclosure: skim the summary first, load the body only if needed).
 - **Optional desktop pet** — A small floating window (`/pet`) shows a stateful character that mirrors agent activity (idle / thinking / tool running / waiting for human). Works as a separate process over WebSocket; quit it with `/pet quit`. Sits beside the terminal, never blocks it.
-- **Slash commands** — `/exit` `/clear` `/context` `/skills` `/compact` `/resume` `/rollback` `/memory` `/reflect` `/init` `/theme` `/model` `/plan` `/auto` `/pet`, with dropdown filtering as you type.
+- **Slash commands** — `/exit` `/clear` `/cd` `/context` `/skills` `/compact` `/resume` `/rollback` `/memory` `/reflect` `/init` `/theme` `/model` `/plan` `/auto` `/pet`, with dropdown filtering as you type.
 
 ## Documentation
 
@@ -280,6 +280,7 @@ dev_server stop   id=srv-xxxx
 | ---------------- | ---------------------------------------------------------------------------------------------- |
 | `/exit` `/quit`  | Exit MoCode                                                                                    |
 | `/clear`         | Clear history (keeps the system prompt) + clear screen                                         |
+| `/cd`            | Switch workspace (`/cd <path>`; bare `/cd` shows current, `/cd -` returns). Old session is saved to the old workspace, the new one starts like `/clear` |
 | `/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                                                                         |

package/README.zh-CN.md

@@ -109,7 +109,7 @@ mocode 不是一个套壳聊天框,而是一个能真正动手干活的 agent:
 - **会话持久化** — 每轮自动落盘,`--resume` / `/resume` 续接历史会话
 - **Skills 系统** — 自动扫描 `~/.mocode/skills/` 等目录,description 注入系统提示,模型按需调 `use_skill` 加载完整指令(渐进式披露:先看简介,任务相关才加载正文)
 - **可选桌宠** — 独立悬浮窗(`/pet`)显示一个小角色,镜像 agent 活动(空闲 / 思考 / 跑工具 / 等人工),独立进程走 WebSocket,`/pet quit` 完全关闭。挂在终端外,绝不挡终端。
-- **斜杠命令** — `/exit` `/clear` `/context` `/skills` `/compact` `/resume` `/rollback` `/memory` `/reflect` `/init` `/theme` `/model` `/plan` `/auto` `/pet`,输入时下拉过滤
+- **斜杠命令** — `/exit` `/clear` `/cd` `/context` `/skills` `/compact` `/resume` `/rollback` `/memory` `/reflect` `/init` `/theme` `/model` `/plan` `/auto` `/pet`,输入时下拉过滤
 
 ## 使用文档
 
@@ -271,6 +271,7 @@ dev_server stop   id=srv-xxxx
 | ---------------- | ------------------------------------------------------------------- |
 | `/exit` `/quit`  | 退出 mocode                                                         |
 | `/clear`         | 清空历史(保留系统提示)+ 清屏                                        |
+| `/cd`            | 切换工作空间(`/cd <路径>`；`/cd` 看当前、`/cd -` 回上一个)。旧会话落盘到原工作区,新工作区按 /clear 重开 |
 | `/image`         | 附加本地图片到下一条消息；支持 `list` / `clear`                     |
 | `/context`       | 显示上下文用量条(token / 消息数 / 估算或实测)                       |
 | `/skills`        | 列出已发现的 skill                                                  |

package/dist/i18n/index.js

@@ -4,6 +4,9 @@ const zhCN = {
     'commands.help': '查看所有命令',
     'commands.exit': '退出 mocode（同 /quit）',
     'commands.clear': '清空历史（保留系统提示）',
+    'commands.cd': '切换工作空间（新工作区按 /clear 重开会话）',
+    'commands.cdTo': '切换到指定目录（支持 ~ 与相对路径）',
+    'commands.cdPrev': '回到上一个工作空间',
     'commands.context': '显示上下文用量条',
     'commands.skills': '列出已发现的 skill',
     'commands.compact': '压缩历史（可带焦点 /compact …）',
@@ -66,6 +69,15 @@ const zhCN = {
     'commands.upgradeNow': '立即升级',
     'commands.upgradeCheck': '检查当前版本与最新版本差异',
     'commands.upgradeStatus': '显示当前本地版本',
+    'workspace.current': '当前工作空间：{root}',
+    'workspace.usage': '/cd 用法：\n  /cd                 显示当前工作空间\n  /cd <路径>          切换到该目录（支持 ~ 与相对路径）\n  /cd -               回到上一个工作空间',
+    'workspace.missing': '目录不存在：{root}',
+    'workspace.notDir': '不是目录：{root}',
+    'workspace.noPrevious': '还没有上一个工作空间（先用 /cd <路径> 切换一次）。',
+    'workspace.same': '已经在该工作空间：{root}',
+    'workspace.switched': '工作空间已切换 → {root}',
+    'workspace.cleared': '会话已按 /clear 重开；旧会话留在 {root}',
+    'workspace.projectConfigHint': '注：项目级 .env / .mocode/config 仅在启动时加载，切换后不重载；如需生效请重启 mocode。MCP 连接同理。',
     'help.title': '可用斜杠命令',
     'help.hint': '（› 表示可进入子菜单；→ 后为实际执行命令）',
     'help.groupFrequent': '常用',
@@ -90,6 +102,7 @@ const zhCN = {
     'running.plan': '切 plan',
     'running.auto': '切 auto',
     'running.clear': '清空',
+    'running.workspace': '切工作空间',
     'running.theme': '切主题',
     'running.chooseTheme': '选择主题…',
     'running.model': '配模型',
@@ -204,6 +217,10 @@ const zhCN = {
     'agent.toolsRunning': '正在探索',
     'agent.toolsComplete': '探索',
     'agent.toolsFailed': '探索失败',
+    /** 单次工具调用 = 1「步」的计数单位(中文量词;英文用 countN)。 */
+    'agent.steps': '{count} 步',
+    /** 摘要行分项间的最小视觉分隔符(不占宽度,纯前景色点)。 */
+    'agent.stepSep': '·',
     'agent.changes': '文件变更',
     'agent.files': '{count} 个文件',
     'agent.changeAdded': '  新增',
@@ -355,6 +372,9 @@ const en = {
     'commands.help': 'Show all commands',
     'commands.exit': 'Exit mocode (same as /quit)',
     'commands.clear': 'Clear history (keep system prompt)',
+    'commands.cd': 'Switch workspace (new workspace restarts the session like /clear)',
+    'commands.cdTo': 'Switch to a directory (supports ~ and relative paths)',
+    'commands.cdPrev': 'Return to the previous workspace',
     'commands.context': 'Show context usage',
     'commands.skills': 'List discovered skills',
     'commands.compact': 'Compact history (optional focus: /compact …)',
@@ -417,6 +437,15 @@ const en = {
     'commands.upgradeNow': 'Upgrade now',
     'commands.upgradeCheck': 'Check current vs latest version',
     'commands.upgradeStatus': 'Show current local version',
+    'workspace.current': 'Current workspace: {root}',
+    'workspace.usage': '/cd usage:\n  /cd                 Show the current workspace\n  /cd <path>          Switch to that directory (supports ~ and relative paths)\n  /cd -               Return to the previous workspace',
+    'workspace.missing': 'Directory does not exist: {root}',
+    'workspace.notDir': 'Not a directory: {root}',
+    'workspace.noPrevious': 'No previous workspace yet (switch once with /cd <path>).',
+    'workspace.same': 'Already in that workspace: {root}',
+    'workspace.switched': 'Workspace switched → {root}',
+    'workspace.cleared': 'Session restarted like /clear; the old session stays in {root}',
+    'workspace.projectConfigHint': 'Note: project-level .env / .mocode/config is loaded at startup and is not reloaded after a switch — restart mocode for it to take effect. MCP connections behave the same way.',
     'help.title': 'Available slash commands',
     'help.hint': '(› opens a submenu; → shows the command that will run)',
     'help.groupFrequent': 'Frequently used',
@@ -441,6 +470,7 @@ const en = {
     'running.plan': 'Plan mode',
     'running.auto': 'Auto mode',
     'running.clear': 'Clear',
+    'running.workspace': 'Workspace',
     'running.theme': 'Theme',
     'running.chooseTheme': 'Choose a theme…',
     'running.model': 'Model',
@@ -555,6 +585,8 @@ const en = {
     'agent.toolsRunning': 'Exploring',
     'agent.toolsComplete': 'Exploration',
     'agent.toolsFailed': 'Exploration failed',
+    'agent.steps': '{count} step(s)',
+    'agent.stepSep': '·',
     'agent.changes': 'Changes',
     'agent.files': '{count} file(s)',
     'agent.changeAdded': '  Added',

package/dist/repl/commands/registry.js

@@ -1,5 +1,6 @@
 import { unhandled } from './types.js';
 import { systemCommands } from './system.js';
+import { workspaceCommands } from './workspace.js';
 import { modeCommands } from './mode.js';
 import { petCommands } from './pet.js';
 import { imageCommands } from './image.js';
@@ -20,6 +21,7 @@ import { toolGroupCommands } from './tool-group.js';
  */
 export const commandHandlers = [
     ...systemCommands,
+    ...workspaceCommands,
     ...modeCommands,
     ...petCommands,
     ...imageCommands,

package/dist/repl/commands/workspace.js

@@ -0,0 +1,92 @@
+/**
+ * 工作区命令组:/cd
+ *
+ * `/cd <path>` 切换工作空间(等同 shell 的 cd,但同步移动沙箱边界与会话落盘目录),
+ * `/cd` 无参显示当前工作区,`/cd -` 回到上一个工作区。
+ *
+ * 切换的语义按用户拍板的结果:**等同 /clear**——旧会话先落盘到原工作区,再在新工作区开新会话,
+ * 屏幕历史清空、重新回到空会话状态。理由:跨项目的对话上下文混在一条 history 里会让
+ * compaction 与 rollback 快照互相污染(旧项目的文件快照对新项目毫无意义),不如干净切开。
+ * 与 /clear 的差异只有两点:① 切换前先 save(旧会话完整留在原工作区,不丢最后一轮);
+ * ② history[0] 用新工作区重算(AGENTS.md 等按新工作区重新导入)。
+ *
+ * 底层改写集中在 src/workspace/index.ts(chdir + 沙箱根 + sessionDir 三处一起改),
+ * 本文件只负责解析输入、提示、重置 REPL 状态。
+ */
+import * as layout from '../../ui/layout.js';
+import { ui } from '../../ui/theme.js';
+import { bannerLines } from '../../ui/render.js';
+import { t } from '../../i18n/index.js';
+import { getAgentMode } from '../../agent/mode.js';
+import { getWorkspaceRoot, resolveWorkspaceTarget, switchWorkspaceRoot } from '../../workspace/index.js';
+import { unhandled, next } from './types.js';
+/** 解析失败原因 → 提示文案的 i18n 键。 */
+const ERROR_KEYS = {
+    missing: 'workspace.missing',
+    'not-dir': 'workspace.notDir',
+    'no-previous': 'workspace.noPrevious',
+    empty: 'workspace.usage',
+};
+export const workspaceCommands = [
+    (ctx) => {
+        if (ctx.line !== '/cd' && !ctx.line.startsWith('/cd '))
+            return unhandled();
+        const arg = ctx.line === '/cd' ? '' : ctx.line.slice('/cd '.length).trim();
+        // 无参:只报当前工作区(沙箱根 == 工作区根),不改任何状态。
+        if (!arg) {
+            layout.contentWrite(`${ui.dim}${t('workspace.current', { root: getWorkspaceRoot() })}${ui.reset}\n`);
+            layout.contentWrite(`${ui.dim}${t('workspace.usage')}${ui.reset}\n\n`);
+            return next();
+        }
+        const target = resolveWorkspaceTarget(arg);
+        if (!target.ok) {
+            const key = ERROR_KEYS[target.error];
+            layout.contentWrite(`${ui.yellow}${t(key, { root: target.root })}${ui.reset}\n\n`);
+            return next();
+        }
+        // 已经是当前工作区:什么都不用做(不触发 /clear,避免误清历史)。
+        if (pathEqual(target.root, getWorkspaceRoot())) {
+            layout.contentWrite(`${ui.dim}${t('workspace.same', { root: target.root })}${ui.reset}\n\n`);
+            return next();
+        }
+        // ① 切前落盘:旧会话完整留在原工作区(/clear 不保存,切换必须保存,否则最后一轮丢失)。
+        //    无 user 消息时 save 内部会跳过空会话,不会产生垃圾 session 文件。
+        if (ctx.state.currentSessionId) {
+            try {
+                ctx.runtime.session.save(ctx.history, ctx.state.currentSessionId, ctx.state.queryHistory, ctx.state.lastToolGroups);
+            }
+            catch {
+                // 落盘失败不阻断切换:会话是附加价值,工作区本身必须切过去。
+            }
+        }
+        // ② 改进程级状态(cwd + 沙箱根 + sessionDir)。
+        const result = switchWorkspaceRoot(target.root);
+        // ③ 重置 REPL 状态(与 /clear 对齐)——新工作区 = 新会话。
+        ctx.history.length = 1;
+        ctx.history[0] = { role: 'system', content: ctx.buildSystemMessage(getAgentMode() === 'plan') };
+        ctx.state.currentSessionId = ctx.runtime.session.clear();
+        ctx.state.turnCount = 0;
+        ctx.state.lastTurnUsage = undefined;
+        ctx.state.queryHistory = [];
+        ctx.state.lastToolGroups = [];
+        ctx.contextState.lastUsage = undefined;
+        ctx.contextState.lifecycleStats = undefined;
+        ctx.contextState.ephemeralText = undefined;
+        ctx.contextState.activeTools = undefined;
+        ctx.contextState.promptAnchor = undefined; // 新工作区不得沿用旧会话的实测锚点
+        ctx.attachments.clear();
+        // ④ 重画:banner 里的 cwd 已随 chdir 变新值;状态行基线同步刷新(底栏目录显示)。
+        layout.clearContent();
+        layout.writeBanner(bannerLines(ctx.banner()));
+        ctx.refreshStatusBase(ctx.history);
+        layout.contentWrite(`${ui.cyan}${t('workspace.switched', { root: result.root })}${ui.reset}\n`);
+        layout.contentWrite(`${ui.dim}${t('workspace.cleared', { root: result.previous })}${ui.reset}\n`);
+        layout.contentWrite(`${ui.dim}${t('workspace.projectConfigHint')}${ui.reset}\n\n`);
+        layout.writeWelcomeBlock(ctx.welcomeLines());
+        return next();
+    },
+];
+/** 同目录判定:Windows 大小写不敏感 + 尾部分隔符差异(path.resolve 已归一,故只比大小写)。 */
+function pathEqual(a, b) {
+    return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+}

package/dist/repl/commands.js

@@ -12,6 +12,14 @@ export function buildSlashCommands() {
         { name: '/help', desc: d('commands.help') },
         { name: '/exit', desc: d('commands.exit') },
         { name: '/clear', desc: d('commands.clear') },
+        {
+            name: '/cd',
+            desc: d('commands.cd'),
+            children: [
+                { name: '<path>', value: '/cd ', submit: false, desc: d('commands.cdTo') },
+                { name: '-', value: '/cd -', desc: d('commands.cdPrev') },
+            ],
+        },
         { name: '/context', desc: d('commands.context') },
         { name: '/skills', desc: d('commands.skills') },
         { name: '/skill', desc: '执行某个 skill(/skill <name> [args-json])' },
@@ -162,7 +170,7 @@ export const LLM_ERROR_HINT_KEYS = {
 };
 /** /help 的分组:按使用场景归组,组内保持菜单树顺序。未列入的顶层命令兜底进「其他」。 */
 export const HELP_GROUPS = [
-    { key: 'help.groupFrequent', names: ['/help', '/clear', '/context', '/compact', '/resume', '/model'] },
+    { key: 'help.groupFrequent', names: ['/help', '/clear', '/cd', '/context', '/compact', '/resume', '/model'] },
     { key: 'help.groupSession', names: ['/sessions', '/rollback', '/memory', '/skills', '/skill', '/init'] },
     {
         key: 'help.groupConfig',

package/dist/repl/status-bar.js

@@ -188,6 +188,8 @@ export function runningStateFor(cmd) {
             return { status: t('running.auto'), placeholder: '…' };
         case '/clear':
             return { status: t('running.clear'), placeholder: '…' };
+        case '/cd':
+            return { status: t('running.workspace'), placeholder: t('running.switching') };
         case '/theme':
             return { status: t('running.theme'), placeholder: t('running.chooseTheme') };
         case '/model':

package/dist/session/store.js

@@ -3,6 +3,7 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { config, getActiveModel } from '../config/index.js';
+import { getWorkspaceRoot } from '../workspace/index.js';
 import { isToolRouteGroupName } from '../config/profiles.js';
 import { truncateDisplay } from '../ui/render.js';
 import { getDefaultCurrentSessionId, setCurrentSessionId as setDefaultCurrentSessionId, withCurrentSessionIdProvider, } from './state.js';
@@ -49,14 +50,28 @@ function firstUserOf(history) {
  * `<sessionsRoot>/<id>/session.json`, with `<sessionsRoot>/<id>.json` as a read fallback.
  */
 export class SessionStore {
-    workspaceRoot;
+    /**
+     * 会话归属的工作区根。**动态**:默认实例用 provider 读 workspace root,
+     * 这样 /cd 切换工作区后不必重建 store(重建会丢 currentSessionId 等进程级绑定)。
+     */
+    get workspaceRoot() {
+        return this.workspaceRootProvider();
+    }
+    workspaceRootProvider;
     sessionsRootProvider;
     getModel;
     currentSessionIdProvider;
     currentSessionIdSetter;
     currentSessionId;
     constructor(options = {}) {
-        this.workspaceRoot = path.resolve(options.workspaceRoot ?? process.cwd());
+        if (typeof options.workspaceRoot === 'function') {
+            const provider = options.workspaceRoot;
+            this.workspaceRootProvider = () => path.resolve(provider());
+        }
+        else {
+            const fixedWorkspace = path.resolve(options.workspaceRoot ?? process.cwd());
+            this.workspaceRootProvider = () => fixedWorkspace;
+        }
         if (typeof options.sessionsRoot === 'function') {
             const provider = options.sessionsRoot;
             this.sessionsRootProvider = () => path.resolve(provider());
@@ -202,7 +217,8 @@ export class SessionStore {
 /** 旧函数 API 的进程级兼容实例；session root 每次读取 config，保留测试和运行时切换语义。 */
 export const defaultSessionStore = new SessionStore({
     sessionsRoot: () => config.sessionDir,
-    workspaceRoot: process.cwd(),
+    // 动态读工作区根:/cd 切走后本实例仍归属新工作区(见 src/workspace/index.ts)。
+    workspaceRoot: () => getWorkspaceRoot(),
     getModel: getActiveModel,
     getCurrentSessionId: getDefaultCurrentSessionId,
     setCurrentSessionId: (id) => setDefaultCurrentSessionId(id, process.cwd()),

package/dist/ui/batch.js

@@ -13,13 +13,13 @@
  */
 import { ui } from './theme.js';
 import { t } from '../i18n/index.js';
-import { truncateAnsi } from './render.js';
+import { truncateAnsi, fmtElapsed } from './render.js';
+import { isScrolled, repaintContentLine } from './layout-internal/scroll.js';
+import { replaceLine } from './content.js';
 /** entry 是否已拿到结果。历史回放构造的 entry 无 done 字段,退化按内容判定。 */
 function isEntryDone(e) {
     return e.done === true || !!e.resultSummary || !!e.diffBlock || !!e.failed;
 }
-/** 子 agent 运行中的专属图标:与完成态的实心 ● 区分,也区别于父层「探索」运行态的 ◇。 */
-const RUNNING_GLYPH = '◐';
 const batches = new Map();
 /** 绝对行索引 → 所属 batch id(仅记录 summary 行;用于鼠标点击反查)。
  *  buffer 行数变化时本表可能漂移——但只在 insertAfter/deleteFrom 后由本模块同步更新,
@@ -72,6 +72,8 @@ export function reset() {
     expandedBatches.clear();
     callToBatch.clear();
     groupChildIndexByCall.clear();
+    // 扫光心跳随运行态批自停:batch 全清后 hasRunningBatch 必为 false。
+    syncSweepTimer();
 }
 /** 新建一个 batch(在 agent 拿到第一条 onToolHeader 时调)。返回 id。
  *  label 可选:自定义摘要行标签(子 agent 批用),缺省按完成态取 agent.tools*。
@@ -94,6 +96,9 @@ export function beginBatch(label, opts) {
         groupChildIndex: opts?.groupChildIndex,
         running: opts?.running ?? false,
     });
+    // 运行态批 → 扫光心跳开始(在 beginBatch 就置 running 的路径也能启动)。
+    if (opts?.running)
+        syncSweepTimer();
     return id;
 }
 /** 登记 tool_call id → 所属 batch。结果回填按 id 归位(并行时 currentBatchId 会漂移),
@@ -120,6 +125,8 @@ export function recordCall(id, name, callSummary, callId) {
     b.entries.push({ name, callSummary, resultSummary: '', diffBlock: null });
     if (callId && b.groupParent)
         groupChildIndexByCall.set(callId, b.entries.length - 1);
+    // 新增 entry = 本批重新「在飞」→ 扫光心跳起(此前收口时可能已停)。
+    syncSweepTimer();
 }
 /** 查询某 sub-agent 调用在所属组容器批 entries 中的序号(供 spawn.ts 建子批时定锚点)。 */
 export function getGroupChildIndex(callId) {
@@ -183,43 +190,224 @@ export function recordResult(id, name, resultSummary, diffBlock, fullOutput, fai
     }
 }
 // ── 摘要行文本生成 ──
-/** 把 entry 列表压缩成一行摘要。 */
+/**
+ * 运行态「符号即进度」字形:符号本身编码 completed/total,不必旁读数字。
+ *
+ * 全部取自 U+25A0–25FF Geometric Shapes——与 `●`(U+25CF)同块。本模块已实测记录过
+ * 「本机等宽字体对 Geometric Shapes 按 1 列渲染、对 Box Drawing 按 2 列」(见下方
+ * CARET_COLLAPSED 注释),故此族是本终端里唯一有实测依据的安全符号集。
+ * 按 1/4 档进阶:◇(0) ◔(1/4) ◑(1/2) ◕(3/4) ◆(满)。档位边界与 total 无关,
+ * 故 total 增长时档位不会回退(填满 3/5 与 3/9 同取 ◑)。
+ */
+const STEP_GLYPHS = ['◇', '◔', '◑', '◕', '◆'];
+/** 收尾态字形:全成 ◆(实心=落定,与运行态的 ◇◔◑◕ 同族)、部分失败 !、全失败 ×。 */
+const DONE_GLYPH = '◆';
+const PARTIAL_FAIL_GLYPH = '!';
+const ALL_FAIL_GLYPH = '×';
+/** 耗时色阶(ms):≥30s 转黄(该留意),≥60s 转红(已超常规阈值)。 */
+const ELAPSED_WARN_MS = 30_000;
+const ELAPSED_ALERT_MS = 60_000;
+/** 扫光:高亮带宽度(字符数)。标签很短(4 字),带宽 3 既能看出"扫"又不整行同时亮。 */
+const SWEEP_BAND = 3;
+/** 扫光心跳间隔(ms):约 17fps,每拍推进 1 字符,4 字标签一个来回约 0.5s。 */
+const SWEEP_TICK_MS = 60;
+/**
+ * 运行态摘要行的扫光帧号。**逐帧只改前景 SGR,不增删字符**——可见宽度恒定,
+ * `sanitizeRow` / `truncateAnsi` 的列宽钳制与 buffer 行索引全部不受影响。
+ *
+ * 这是本方案能落在纯字符串层的前提:换成背景色块或增删字符都会让「一条逻辑行 =
+ * 一条物理行」的模型失效,进而打乱 repaintViewport 的 CUP 寻址。
+ */
+let _sweepFrame = 0;
+let _sweepTimer = null;
+/**
+ * 最近一次 showLiveBatch 收到的 layout —— 仅用于**判断**当前是否有可用 UI 通道
+ * (`_sweepLayout != null`)。扫光落屏走 `content.replaceLine` + `repaintContentLine` 单行路径,
+ * 不走 layout 方法:contentWrite 那版末尾会整屏 repaintViewport,16fps 逐帧调会持续闪。
+ * 存 layout 而不自己 import 判断 TUI 是否激活,是沿用「agent 侧注入」的既有形态。
+ */
+let _sweepLayout = null;
+/**
+ * 批是否「在飞」(需要扫光与实时耗时)。判据是**已收口即落定**:
+ * `endBatch` 必设 finishedAt,故先看它 —— 否则任何「endBatch 了但 running 标志残留」
+ * 的路径会让扫光永远转下去(实测:探针手动置 running 后收口,扫光仍在写)。
+ * 收口标志优先于 running,是因为 running 在语义上只描述"这一批还没落定"。
+ * `recordCall` 会把 finishedAt 清回 undefined(允许累计探索后再追加工具),重新在飞时自然复活。
+ */
+function isBatchLive(b) {
+    if (b.finishedAt != null)
+        return false;
+    if (b.running)
+        return true;
+    return b.entries.length > 0 && !b.entries.every(isEntryDone);
+}
+/** 是否有在飞批——扫光只服务它们。 */
+function hasLiveBatch() {
+    for (const b of batches.values())
+        if (isBatchLive(b))
+            return true;
+    return false;
+}
+/** 扫光可用性:TUI(非 TTY 输出纯文本,不能塞动画转义)+ 有在飞批 + 有可写回的 layout。 */
+function sweepEnabled() {
+    return ui.isTTY && _sweepLayout != null && hasLiveBatch();
+}
+/**
+ * 同步扫光心跳开关(建批/收批时调)。心跳随最后一个运行态批结束自停,不常驻空转。
+ */
+export function syncSweepTimer() {
+    if (!sweepEnabled()) {
+        if (_sweepTimer) {
+            clearInterval(_sweepTimer);
+            _sweepTimer = null;
+        }
+        return;
+    }
+    _sweepTimer ??= (() => {
+        const timer = setInterval(() => {
+            if (!sweepEnabled()) {
+                syncSweepTimer();
+                return;
+            }
+            // 滚动回看时冻结视口:写回该行会画出不含最新帧的窗口、造成闪烁。帧号照常推进,回底后不跳帧。
+            if (isScrolled()) {
+                _sweepFrame++;
+                return;
+            }
+            _sweepFrame++;
+            const layout = _sweepLayout;
+            if (!layout)
+                return;
+            for (const b of batches.values()) {
+                if (b.summaryAbsIdx < 0)
+                    continue;
+                if (!isBatchLive(b))
+                    continue; // 已落定的批:耗时为定值,重画纯属浪费
+                const line = truncateAnsi(buildSummaryLine(b, true), maxCols);
+                // ① 直接写缓冲(不经过 layout.contentReplaceLine —— 那一版末尾会整屏 repaintViewport,
+                //    16fps 下让运行中的列表持续闪,正是用户反馈的观感问题);
+                // ② 只重画这一行。两步都是 O(1)-ish,与内容区长度无关。
+                replaceLine(b.summaryAbsIdx, line);
+                repaintContentLine(b.summaryAbsIdx, line);
+            }
+        }, SWEEP_TICK_MS);
+        timer.unref?.();
+        return timer;
+    })();
+}
+/**
+ * 计算本帧高亮带覆盖的字符区间 `[start, end)`(纯函数,导出供帧推进/带宽测试)。
+ *
+ * head 在一个周期内 0 → n → 0:扫进(0..n)后扫回(n..2n),使带子从右端出去、从左端
+ * 回来而无跳变(单向回绕会让"扫到底"瞬间跳回左边,读成闪烁)。
+ */
+export function sweepBandRange(charCount, frame, band = SWEEP_BAND) {
+    if (charCount <= 0)
+        return [0, 0];
+    const cycle = charCount * 2;
+    const pos = ((frame % cycle) + cycle) % cycle; // 帧号负数也安全(不要依赖调用方已归一)
+    const head = pos <= charCount ? pos : cycle - pos;
+    const w = Math.min(band, charCount);
+    // end 由 head 推得,而 head 可等于 charCount(带子探到串尾之外一格)。
+    // 必须钳到 charCount:否则本函数会返回越界区间,「每个字符都被扫到」等不变量随之失准。
+    return [Math.max(0, Math.min(head - w + 1, charCount - 1)), Math.min(head + 1, charCount)];
+}
+/**
+ * 按帧给文本套扫光(纯函数,导出供「可见宽度不变量」测试)。
+ *
+ * **只改前景 SGR、不增删字符**是硬约束:调用方(sanitizeRow / truncateAnsi)按字符列宽
+ * 钳制行宽,一旦这里动了可见字符,「一条逻辑行 = 一条物理行」的模型就会失效,
+ * 进而打乱 repaintViewport 的 CUP 寻址。故本函数只做 SGR 开合,输出宽度恒等于输入。
+ *
+ * 颜色只在**状态切换处**写出(连续同色字符共用一个 SGR),避免逐字符刷 SGR 撑大输出。
+ */
+export function sweepRender(text, base, hi, frame) {
+    const chars = [...text];
+    const [start, end] = sweepBandRange(chars.length, frame);
+    let out = '';
+    let cur = '';
+    for (let i = 0; i < chars.length; i++) {
+        const want = i >= start && i < end ? hi : base;
+        if (want !== cur) {
+            out += want;
+            cur = want;
+        }
+        out += chars[i];
+    }
+    // 收尾回常态色:调用方随后会补 reset,但这里显式闭合可让本函数的输出自成一段
+    // (测试/history 回放等直接消费返回值的场景不必再关心尾色)。
+    return cur === base ? out : `${out}${base}`;
+}
+/**
+ * 给标签文本渲染扫光高亮。`base` 是标签的常态色(运行态 accent / 失败态 red 等),
+ * 高亮带扫过的字符临时换成 `ui.sweepHighlight`。
+ *
+ * 中文按**字符**而非列推进:按列推进需要把列偏移折算回字符边界,折算后相邻帧会落在
+ * 同一字符上、视觉上「卡一拍」;按字推进牺牲严格等速,换取每帧必有可见位移。
+ */
+function sweepText(text, base) {
+    if (!sweepEnabled())
+        return text;
+    return sweepRender(text, base, ui.sweepHighlight, _sweepFrame);
+}
+/**
+ * 单行摘要。结构(全部单行、行内样式,不改行数):
+ *   `  ◆  探索  ·  5 步 · 16.8s   run_command ×2  glob ×1`
+ * 分项之间用 dim 的 `·` 分隔(比裸空格更有"字段感"),工具名去引号、单次调用不带计数。
+ */
 function buildSummaryLine(record, live = false) {
     const prefix = record.indent ?? '';
     const entries = record.entries;
     if (entries.length === 0) {
         return `${prefix}  ${ui.dim}│${ui.reset} ${ui.bold}${ui.accent}◇${ui.reset} ${ui.dim}No tools${ui.reset}`;
     }
-    // N>1:同类合并 "read_file 3, glob 1, grep 1"
-    const counts = new Map();
-    for (const e of entries)
-        counts.set(e.name, (counts.get(e.name) ?? 0) + 1);
-    const parts = [];
-    for (const [n, c] of counts)
-        parts.push(`${n} ${c}`);
     const completed = entries.filter(isEntryDone).length;
     const failedCount = entries.filter((e) => e.failed).length;
-    // 工具本身完成就立即显示完成态，不等待整轮正文流完/onDone。
-    // 单项失败不代表整批失败：执行中优先展示进度；完成后区分部分失败与全部失败。
     const finished = completed >= entries.length;
     const allFailed = finished && failedCount === entries.length;
     const partiallyFailed = finished && failedCount > 0 && !allFailed;
-    const symbol = record.running ? RUNNING_GLYPH : !finished ? '◇' : allFailed ? '×' : partiallyFailed ? '!' : '●';
-    const color = record.running
-        ? ui.accent
-        : !finished
-            ? ui.accent
-            : allFailed
-                ? ui.red
-                : partiallyFailed
-                    ? ui.yellow
-                    : ui.green;
-    const label = !finished ? t('agent.toolsRunning') : allFailed ? t('agent.toolsFailed') : t('agent.toolsComplete');
-    const progress = live && !finished ? `  ${completed}/${entries.length}` : `  ${entries.length}`;
-    const elapsedMs = record.finishedAt ? record.finishedAt - record.startedAt : 0;
-    const elapsed = record.finishedAt ? `  ${elapsedMs < 100 ? '<0.1s' : `${(elapsedMs / 1000).toFixed(1)}s`}` : '';
-    const displayLabel = record.label ?? label;
-    return `${prefix}  ${ui.bold}${color}${symbol}${ui.reset} ${displayLabel}${progress}${elapsed}  ${ui.dim}${parts.join('  ')}${ui.reset}`;
+    const running = !finished || record.running;
+    // 符号即进度:运行态按 completed/total 取档(子 agent 批额外 +1 档以示"整个 agent 还在跑")。
+    const stepIdx = Math.min(4, Math.floor((completed / entries.length) * 5));
+    const symbol = running
+        ? STEP_GLYPHS[Math.min(4, record.running ? stepIdx + 1 : stepIdx)]
+        : allFailed
+            ? ALL_FAIL_GLYPH
+            : partiallyFailed
+                ? PARTIAL_FAIL_GLYPH
+                : DONE_GLYPH;
+    const color = running ? ui.accent : allFailed ? ui.red : partiallyFailed ? ui.yellow : ui.accent;
+    const labelText = record.label ?? (running ? t('agent.toolsRunning') : allFailed ? t('agent.toolsFailed') : t('agent.toolsComplete'));
+    // 扫光只挂在**执行中**刷新的那一帧(live):收尾定稿(endBatch, live=false)后标签应静止落定。
+    const labelSeg = running && live ? sweepText(labelText, color) : labelText;
+    // 步数:运行态用主题色强调进度,收尾退回灰(信息已结算,不抢主色)。
+    const stepsSeg = running
+        ? `${ui.accent}${t('agent.steps', { count: entries.length })}${ui.reset}`
+        : `${ui.dim}${t('agent.steps', { count: entries.length })}${ui.reset}`;
+    // 耗时色阶 ≥30s 黄 / ≥60s 红:长步骤自己跳出来,不再和 6.3s 等重。
+    // 在飞态显**实时**耗时(而非等到收尾才出一个死数字):工具阻塞几十秒时,
+    // 「这一行还在走」本身就是最重要的信息(实测场景:单条 run_command 干等 78s,
+    // 期间摘要行只有静态的计数 1,用户无法判断是卡死还是在跑)。
+    const liveElapsed = !record.finishedAt && running;
+    const elapsedMs = record.finishedAt
+        ? record.finishedAt - record.startedAt
+        : liveElapsed
+            ? Date.now() - record.startedAt
+            : 0;
+    const elapsedColor = elapsedMs >= ELAPSED_ALERT_MS ? ui.red : elapsedMs >= ELAPSED_WARN_MS ? ui.yellow : ui.dim;
+    const elapsedSeg = record.finishedAt || liveElapsed
+        ? ` ${ui.dim}·${ui.reset} ${elapsedColor}${elapsedMs < 100 ? '<0.1s' : fmtElapsed(elapsedMs)}${ui.reset}`
+        : '';
+    // 工具分项:同类合并;单次调用不带计数(「run_command 1」的尾 1 是纯噪声),多次才写 ×N。
+    const counts = new Map();
+    for (const e of entries)
+        counts.set(e.name, (counts.get(e.name) ?? 0) + 1);
+    const tools = [...counts].map(([n, c]) => (c > 1 ? `${n} ×${c}` : n));
+    const toolsSeg = tools.length ? `   ${ui.dim}${tools.join('  ')}${ui.reset}` : '';
+    // 符号与标签之间只留 1 空格:Geometric Shapes 字形窄于字符格(左右各约 0.2 列),
+    // 再叠 3 空格会读出「符号孤立在左」的疏离感(实测:3 空格时光学间距≈3.2 列)。
+    const head = `${ui.bold}${color}${symbol}${ui.reset} ${ui.bold}${color}${labelSeg}${ui.reset} ${stepsSeg}${elapsedSeg}`;
+    return `${prefix}${head}${toolsSeg}`;
 }
 // ── 展开/折叠 ──
 /** 把 batch 的详情行展开成自洽行数组(供 layout.contentInsertAfter 走 mid-buffer 插入)。
@@ -337,6 +525,8 @@ export function endBatch(id, layout) {
     if (!b)
         return;
     b.finishedAt ??= Date.now();
+    // 本批收口 → 摘要行变「落定」态(◆ + 定值耗时),不再扫光。若无其它在飞批则心跳自停。
+    syncSweepTimer();
     if (b.summaryAbsIdx >= 0) {
         layout.contentReplaceLine?.(b.summaryAbsIdx, buildSummaryLine(b));
         // 点击命中在 showLiveBatch 首次落盘时即已登记(运行态可展开);这里幂等重登,
@@ -376,6 +566,8 @@ export function showLiveBatch(id, layout) {
     const b = batches.get(id);
     if (!b)
         return;
+    // 登记 layout:扫光逐帧重画要靠它把新帧写回摘要行(见 _sweepLayout 注释)。
+    _sweepLayout = layout;
     const summary = buildSummaryLine(b, true);
     if (b.summaryAbsIdx < 0) {
         // 子批:摘要行插到父批已渲染块的正下方(而非 buffer 末尾),
@@ -428,6 +620,8 @@ export function showLiveBatch(id, layout) {
     }
     // 展开态的运行态同步:已渲染 entry 的结果回填原位替换 + 新 entry 追加。
     syncLiveExpanded(b, layout);
+    // 本批可能在飞(新 entry 刚入、结果未回)→ 确保扫光心跳在跑;已收口则由上一句的判定自停。
+    syncSweepTimer();
 }
 /** 展开态 batch 的运行态同步(每次 showLiveBatch 后调):不展开/未落盘时 no-op。 */
 function syncLiveExpanded(b, layout) {
@@ -800,11 +994,13 @@ export function setBatchLabel(id, label) {
     if (b)
         b.label = label;
 }
-/** 设置/清除运行态标志:running=true 时摘要行用「运行中」专属图标,收尾时置 false。 */
+/** 设置/清除运行态标志:running=true 时摘要行用「运行中」专属图标,收尾时置 false。
+ *  同时驱动扫光心跳——置位即开(若尚未开),清除后若无其它运行态批则自停。 */
 export function setBatchRunning(id, running) {
     const b = batches.get(id);
     if (b)
         b.running = running;
+    syncSweepTimer();
 }
 /** history 回放支持 ── */
 /** 把已构造好的 BatchEntry[] 落成可切换摘要行(用于 renderHistory 回放)。

package/dist/ui/layout-internal/core.js

@@ -32,7 +32,7 @@ import { contentWrite, contentInsertAfter, contentDeleteFrom, contentReplaceLine
 export { isTuiActive, getGeo, setRegion, contentMode, isStreamingPaused } from './screen.js';
 export { drawStatusBar, setStatus, stopTurnTimer, startTurnTimerIfRunning, paintLiveAtCursor, clearLiveAtCursor, setLiveUsage, setStatusBase, } from './statusbar.js';
 export { paintInput, paintRunningInput, repaint } from './input-paint.js';
-export { isScrolled, repaintViewport, scrollBy, scrollWheel, resetScroll, lockScrollToBottom, unlockScroll, isScrollLocked, } from './scroll.js';
+export { isScrolled, repaintViewport, repaintContentLine, scrollBy, scrollWheel, resetScroll, lockScrollToBottom, unlockScroll, isScrollLocked, } from './scroll.js';
 export { contentWrite, writeBanner, rewriteBanner, bannerHeight, contentWriteMd, contentWriteMdOnce, clearContent, rewindContent, writeWelcomeBlock, dismissWelcomeBlock, contentInsertAfter, contentDeleteFrom, totalRows, isLastContentRowBlank, normalizeMutationBoundary, normalizeInputBoundary, contentReplaceLine, notifyContentReset, } from './content-write.js';
 // ── 裸 console 防御 ──
 // 第三方库(如 openai SDK)可能用 console.log 直写 stdout,在 RUNNING 态会落到光标所在的底栏

package/dist/ui/layout-internal/scroll.js

@@ -29,6 +29,38 @@ export function viewportAbsStart() {
 export function screenRowToAbsLine(row) {
     return viewportAbsStart() + (row - 1);
 }
+/**
+ * 只重画**一条**已提交内容行(单行 CUP + clearLine + 行文本 + 光标归位)。
+ *
+ * 与 repaintViewport 的区别是「写多少」:后者把整个内容区 h 行全刷一遍。批量摘要行的
+ * 动态刷新(如扫光逐帧换 SGR)若走整屏重画,在 16fps 下会让运行中的列表持续闪 ——
+ * 这正是用户实测反馈的观感问题。单行重画只碰目标行,无闪烁且开销恒定。
+ *
+ * 前置条件:调用方保证该行**当前在视口内**(offset=0 的实时尾屏天然满足)且行宽已钳到
+ * cols(identity: 行内只换 SGR,可见宽度不变)。滚动回看态一律不走这里:那里应由上层
+ * 直接跳过刷新(冻结视口),而非在这里猜屏幕映射。
+ */
+export function repaintContentLine(absIdx, line) {
+    if (!state.active)
+        return;
+    const g = getGeo();
+    const row = absIdx - viewportAbsStart() + 1;
+    if (row < 1 || row > g.contentBottom)
+        return; // 不在视口内:不猜映射,交由上层处理
+    // 已提交行自带完整 SGR 前缀(breakRow 落盘的是 `rowStartSgr + curRaw + reset`,见 content.ts),
+    // 故单行重画无需补前缀,只需按当前列宽钳宽(窄窗兜底,防 auto-wrap 破坏「一行=一物理行」)。
+    const text = truncateAnsi(line, g.cols);
+    let out = cup(row, 1) + esc.clearLine + text;
+    // 与 repaintViewport 同约定:运行态光标归输入框(供 IME 锚定),INPUT 态归续写位。
+    if (state.mode === 'running') {
+        const c = runningCaretPos();
+        out += cup(c.row, c.col);
+    }
+    else {
+        out += cup(state.scrollOffset === 0 ? state.contentRow : g.contentBottom, state.scrollOffset === 0 ? state.contentCol : 1);
+    }
+    stdout.write(out);
+}
 /**
  * 重画内容区 viewport:按 scrollOffset 取缓冲尾窗,逐行 cup+clearline+rowtext 映射到屏 1..contentBottom。
  * offset=0 即尾窗(== 实时屏,resize / 回尾时用)。清行含 contentBottom——顺带擦 WT 边距漏影(状态行重复)。

package/dist/ui/theme.js

@@ -29,6 +29,7 @@ const DEFAULT = {
     brightCyan: '\x1B[38;2;86;182;194m',
     brightMagenta: '\x1B[38;2;198;120;221m',
     accent: '\x1B[38;2;86;182;194m', // 与 cyan 同源(One Dark):logo/标题/输入框顶线/选中项统一承载
+    sweepHighlight: '\x1B[38;2;130;225;240m', // 亮青:深底上扫过 accent 文字时跳出
     userBg: '\x1B[48;2;72;78;90m', // 统一灰白用户消息底(黑底终端可见)
     // diff 行底色:One Dark bg #282c34 上加 ~14% 亮度的对应色,够辨识但不刺眼
     addBg: '\x1B[48;2;44;62;42m', // 偏暗绿(One Dark green(152,195,121)暗化)
@@ -53,6 +54,7 @@ const THEMES = {
         brightCyan: '\x1B[38;2;42;161;152m',
         brightMagenta: '\x1B[38;2;108;113;196m',
         accent: '\x1B[38;2;38;139;210m', // Solarized blue:浅底下更醒目的强调
+        sweepHighlight: '\x1B[38;2;108;113;196m', // Solarized violet:浅底上比蓝更深一档才看得出「扫过」
         userBg: '\x1B[48;2;72;78;90m', // 统一灰白用户消息底(黑底终端可见)
         // diff 行底色:Solarized Light base2(238,232,213)上贴同色族浅 tint,
         // 比直接用 base1 更柔,跟深 fg(red/green)对比充足
@@ -70,6 +72,7 @@ const THEMES = {
         brightCyan: '\x1B[38;2;147;161;161m',
         brightMagenta: '\x1B[38;2;108;113;196m',
         accent: '\x1B[38;2;42;161;152m', // Solarized cyan(深底版):暗底上跳出
+        sweepHighlight: '\x1B[38;2;120;215;205m', // 亮青:同族提亮
         userBg: '\x1B[48;2;72;78;90m', // 统一灰白用户消息底(黑底终端可见)
         // diff 行底色:Solarized Dark base03(0,43,54)上加对应色族暗 tint
         addBg: '\x1B[48;2;20;50;38m',
@@ -86,6 +89,7 @@ const THEMES = {
         brightCyan: '\x1B[38;2;142;192;124m',
         brightMagenta: '\x1B[38;2;211;134;155m',
         accent: '\x1B[38;2;250;189;47m', // Gruvbox yellow(主题色)
+        sweepHighlight: '\x1B[38;2;255;235;150m', // 浅黄:深红底上扫过黄字提亮
         userBg: '\x1B[48;2;72;78;90m', // 统一灰白用户消息底(黑底终端可见)
         // diff 行底色:Gruvbox dark bg(40,40,40)上贴暗 bg0_a 风格
         addBg: '\x1B[48;2;40;55;30m',
@@ -102,6 +106,7 @@ const THEMES = {
         brightCyan: '\x1B[38;2;136;192;208m',
         brightMagenta: '\x1B[38;2;180;142;173m',
         accent: '\x1B[38;2;136;192;208m', // Nord 浅冰蓝(主题色)
+        sweepHighlight: '\x1B[38;2;190;230;240m', // 更亮的冰蓝:Nord polar night 上跳出
         userBg: '\x1B[48;2;72;78;90m', // 统一灰白用户消息底(黑底终端可见)
         // diff 行底色:Nord polar night(46,52,64)上贴对应色族暗 tint
         addBg: '\x1B[48;2;46;66;52m',
@@ -121,6 +126,7 @@ const THEMES = {
         brightCyan: '\x1B[38;2;160;220;220m',
         brightMagenta: '\x1B[38;2;245;165;215m',
         accent: '\x1B[38;2;255;170;60m', // 南瓜橙(主题主色:logo/标题/输入框顶线/选中项)
+        sweepHighlight: '\x1B[38;2;255;225;165m', // 浅杏橙:深暖底上扫过提亮
         userBg: '\x1B[48;2;72;78;90m', // 统一灰白用户消息底(黑底终端可见)
         // diff 行底色:暖深棕底上贴对应色族暗 tint,跟 fg 配对柔和可辨
         addBg: '\x1B[48;2;55;70;35m',
@@ -139,6 +145,7 @@ const THEMES = {
         brightCyan: '\x1B[38;2;170;220;220m',
         brightMagenta: '\x1B[38;2;250;160;200m',
         accent: '\x1B[38;2;230;90;150m', // 玫粉(主题主色)
+        sweepHighlight: '\x1B[38;2;255;175;210m', // 亮玫粉:深紫底上扫过提亮
         userBg: '\x1B[48;2;72;78;90m', // 统一灰白用户消息底(黑底终端可见)
         // diff 行底色:深紫底贴对应色族暗 tint,绿暗化偏橄榄、红暗化偏紫红
         addBg: '\x1B[48;2;50;60;42m',
@@ -157,6 +164,7 @@ const THEMES = {
         brightCyan: '\x1B[38;2;140;230;210m',
         brightMagenta: '\x1B[38;2;210;170;230m',
         accent: '\x1B[38;2;80;210;140m', // 翡翠绿(主题主色)
+        sweepHighlight: '\x1B[38;2;170;245;205m', // 亮翡翠:深绿底上扫过提亮
         userBg: '\x1B[48;2;72;78;90m', // 统一灰白用户消息底(黑底终端可见)
         // diff 行底色:深绿底贴对应色族暗 tint,绿暗化偏深绿、红暗化偏暗红
         addBg: '\x1B[48;2;30;55;40m',
@@ -175,6 +183,7 @@ const THEMES = {
         brightCyan: '\x1B[38;2;170;210;200m',
         brightMagenta: '\x1B[38;2;240;180;210m',
         accent: '\x1B[38;2;255;200;80m', // 琥珀金黄(主题主色)
+        sweepHighlight: '\x1B[38;2;255;240;175m', // 浅金:深棕底上扫过提亮
         userBg: '\x1B[48;2;72;78;90m', // 统一灰白用户消息底(黑底终端可见)
         // diff 行底色:深棕底贴对应色族暗 tint,绿暗化偏橄榄、红暗化偏暗棕红
         addBg: '\x1B[48;2;50;55;25m',
@@ -193,6 +202,7 @@ const THEMES = {
         brightCyan: '\x1B[38;2;180;230;230m',
         brightMagenta: '\x1B[38;2;210;180;250m',
         accent: '\x1B[38;2;180;150;230m', // 薰衣草紫(主题主色)
+        sweepHighlight: '\x1B[38;2;225;210;255m', // 淡紫白:深紫底上扫过提亮
         userBg: '\x1B[48;2;72;78;90m', // 统一灰白用户消息底(黑底终端可见)
         // diff 行底色:深紫底贴对应色族暗 tint,绿暗化偏冷绿、红暗化偏冷紫红
         addBg: '\x1B[48;2;38;46;42m',
@@ -211,6 +221,7 @@ const THEMES = {
         brightCyan: '\x1B[38;2;170;225;215m',
         brightMagenta: '\x1B[38;2;250;170;210m',
         accent: '\x1B[38;2;255;120;100m', // 珊瑚红(主题主色)
+        sweepHighlight: '\x1B[38;2;255;185;165m', // 浅珊瑚:深棕红底上扫过提亮
         userBg: '\x1B[48;2;72;78;90m', // 统一灰白用户消息底(黑底终端可见)
         // diff 行底色:深棕红底贴对应色族暗 tint,绿暗化偏橄榄、红暗化偏暗棕红
         addBg: '\x1B[48;2;50;55;30m',
@@ -297,6 +308,9 @@ export const ui = {
     get accent() {
         return color('accent');
     },
+    get sweepHighlight() {
+        return color('sweepHighlight');
+    },
     get userBg() {
         return color('userBg');
     },

package/dist/workspace/index.js

@@ -0,0 +1,89 @@
+/**
+ * 工作区(workspace)切换的**唯一入口**:进程级单例的集中改写。
+ *
+ * 为什么需要这个模块:
+ * 「当前工作区」在 mocode 里不是一个变量,而是散落在几处进程级单例上的状态——
+ *   1. `process.cwd()`:memory 存储、skill 扫描、AGENTS.md、rollback 默认实例都直接读它;
+ *   2. sandboxRoot(sandbox/root.ts):文件操作边界(jail / 工具 cwd / run_command cwd / 权限判定);
+ *   3. `config.sessionDir`:会话落盘目录(启动时按 cwd 算好的固定值)。
+ * 只改其中任意一个都会留下「半个工作区」——比如只 setSandboxRoot 不 chdir,
+ * 文件读写走新目录而 memory / skill / AGENTS.md 还读旧目录。所以这里一次性改全部三处,
+ * 且顺序固定(先 chdir 后改 config,避免中途失败留下不一致)。
+ *
+ * 依赖方向:本模块只依赖 config 与 sandbox/root 两个叶子,不 import session/repl/agent,
+ * 避免出现环;session store 反过来**读**本模块(见 session/store.ts 的 workspaceRoot provider)。
+ *
+ * 未覆盖(有意):项目级 `.env` / `.mocode/config` 只在启动时加载一次,切换后不重新加载
+ * ——否则切个目录就可能把模型/baseURL 换掉,比不重载更危险。命令层会提示「如需生效请重启」。
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { config } from '../config/index.js';
+import { getSandboxRoot, setSandboxRoot } from '../sandbox/root.js';
+/** 当前工作区根(绝对路径)。沙箱根优先,未初始化回退 process.cwd()。 */
+export function getWorkspaceRoot() {
+    return getSandboxRoot() ?? process.cwd();
+}
+/**
+ * 上一个工作区根,供 `/cd -` 来回切换。模块级单例(一个进程只有一个 REPL 主循环),
+ * 与 sandboxRoot 同生命周期;切换失败时不更新,保证 `-` 永远指向一个真实去过的目录。
+ */
+let previousRoot = null;
+/** 展开 `~`(仅前缀,仅 POSIX/Windows 通用形式);其余原样返回。 */
+function expandHome(input) {
+    if (input === '~')
+        return os.homedir();
+    if (input.startsWith('~/') || input.startsWith('~\\'))
+        return path.join(os.homedir(), input.slice(2));
+    return input;
+}
+/**
+ * 解析切换目标:支持 `~`、相对路径(相对当前工作区根)、`-`(上一个工作区)。
+ * 只做解析与存在性校验,**不改任何状态**——调用方据此决定提示文案。
+ */
+export function resolveWorkspaceTarget(input) {
+    const raw = input.trim();
+    if (!raw)
+        return { ok: false, error: 'empty', root: '' };
+    if (raw === '-') {
+        if (!previousRoot)
+            return { ok: false, error: 'no-previous', root: '' };
+        if (!isDirectory(previousRoot))
+            return { ok: false, error: 'missing', root: previousRoot };
+        return { ok: true, root: previousRoot };
+    }
+    // 相对路径按当前工作区根解析(而非 cwd):--sandbox-root 启动时两者可能不同,
+    // 用户在 TUI 里看到的"当前目录"就是工作区根,相对路径必须与之对齐。
+    const root = path.resolve(getWorkspaceRoot(), expandHome(raw));
+    if (!fs.existsSync(root))
+        return { ok: false, error: 'missing', root };
+    if (!isDirectory(root))
+        return { ok: false, error: 'not-dir', root };
+    return { ok: true, root };
+}
+function isDirectory(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 切换工作区:chdir + 沙箱根 + 会话目录,三处一起改。
+ *
+ * 返回切换前后路径供命令层提示。调用方(命令层)负责保存旧会话、开新会话、重画 banner。
+ */
+export function switchWorkspaceRoot(root) {
+    const previous = getWorkspaceRoot();
+    const abs = path.resolve(root);
+    // ① chdir 让所有直接读 process.cwd() 的消费者(memory / skill / AGENTS.md / rollback 默认实例)跟随;
+    // ② setSandboxRoot 移动文件操作边界(jail、glob/grep/run_command 的 cwd、权限判定);
+    // ③ sessionDir 是启动时按 cwd 算死的固定值,必须显式改写,否则会话仍落进旧工作区。
+    process.chdir(abs);
+    setSandboxRoot(abs);
+    config.sessionDir = path.join(abs, '.mocode', 'sessions');
+    previousRoot = previous;
+    return { previous, root: abs };
+}

package/package.json

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