mocode-ai 1.5.9 → 1.5.10

package/dist/agent/model-turn.js

@@ -1,4 +1,5 @@
 import { estimatePromptTokens, estimateTokens, isContextLengthError, } from '../llm/index.js';
+import { visionBatch, visionKeep } from '../config/index.js';
 /**
  * 沿 cause 链(≤3 层)取第一个 errno,供 trace 取证。
  * undici 把底层 errno 挂在 cause 上(`TypeError: fetch failed` → cause `read ECONNRESET`),
@@ -33,6 +34,14 @@ export async function runModelTurn(input) {
     onContextUpdate?.();
     let historyRebuilt = false;
     let overflowRetried = false;
+    // 视觉滑动窗口**必须剪在 trim 之前**:contextTrimmer.trim() 拿的是 historyManager.snapshot(),
+    // 若先 trim,预算口径还是未剪的旧数组,80% 压力线照旧被图像撑爆(design-notes/vision-window.md §2.1)。
+    // 只在这一个地方剪;下面的 overflow 重试路径读同一个 snapshot,会自动受益。
+    const visionKeepN = visionKeep();
+    if (visionKeepN > 0 && historyManager.pruneVisionWindow({ keep: visionKeepN, batch: visionBatch(), step })) {
+        rebuildHistoryIndexes();
+        onContextUpdate?.();
+    }
     const compactStartedAt = Date.now();
     const trimResult = await contextTrimmer.trim({
         mode: scheduler ? 'scheduled' : 'fallback',
@@ -98,7 +107,7 @@ export async function runModelTurn(input) {
                 ? '## Post-compaction recovery\n' +
                     'Context was compacted before this request. Recover before doing anything else, in this order:\n' +
                     '1. Read the session summary at the top of the history: `## Completed` is already done — do not redo or re-verify it. `## In Progress` / `## Next Steps` tell you exactly where work stopped and what is next.\n' +
-                    '2. Read `## Session state` below (from notes.md, refreshed every step): the active plan is authoritative — `[x]` steps are finished, resume from the first `[ ]`. A `## Compaction Snapshot` section there is the progress checkpoint written at this compaction.\n' +
+                    '2. Read `## Session state` below (refreshed every step from notes.md / gui-actions.log): the active plan is authoritative — `[x]` steps are finished, resume from the first `[ ]`. A `## Compaction Snapshot` section there is the progress checkpoint written at this compaction. A `## GUI actions` section lists every GUI action already performed with its observed result: do not repeat an action that appears there, unless the latest screenshot contradicts it (then the screenshot wins — treat that line as attempted but unverified).\n' +
                     (sessionStateText
                         ? ''
                         : '(No active plan or snapshot was found in notes.md — reconstruct what is done purely from the summary and treat its `## Completed` as ground truth.)\n') +

package/dist/agent/run-coordinator.js

@@ -11,7 +11,7 @@ import { defaultAgentRuntimeContext } from './runtime-context.js';
 import { runModelTurn } from './model-turn.js';
 import { runToolTurn } from './tool-turn.js';
 import { createTurnLifecycle } from './turn-lifecycle.js';
-import { parseArgs, argumentErrorHint, isParallelTool, isResourceLockedCall, deniedOutcome, readDiffContext, pushToolResult, } from './tool-helpers.js';
+import { parseArgs, argumentErrorHint, isParallelTool, isParallelOrchestrationCall, isResourceLockedCall, deniedOutcome, readDiffContext, pushToolResult, } from './tool-helpers.js';
 import { contextState, summarizeToolArguments } from '../session/index.js';
 import { createBudgetScheduler } from '../session/scheduler.js';
 import { invalidateArtifacts, rehydrateArtifacts } from '../context/index.js';
@@ -522,6 +522,98 @@ export async function runAgentCoreLegacy(opts, historyManager, stages) {
                                         hooks.onToolDone?.();
                                         i = j;
                                     }
+                                    else if (isParallelOrchestrationCall(currentCall.name, ctx.toolRuntime) &&
+                                        !(ctx.getAgentMode() === 'plan' && planDisabledTools.has(currentCall.name))) {
+                                        // 连续编排调用(sub-agent)：按 subAgentConcurrency 分块,块内并发。
+                                        // 权限确认仍严格按原序进行；全部 header 必须先于首个 execute 发出——渲染侧
+                                        // 靠 header 建「组容器批」并逐条追加 └─ 子 agent 行,若边启动边发 header,
+                                        // 先完成的 entry 会让组提前收口,后续 header 会另起一个新组。
+                                        let j = i;
+                                        while (j < calls.length &&
+                                            isParallelOrchestrationCall(calls[j].name, ctx.toolRuntime) &&
+                                            !isToolDeniedForStep(calls[j].name) &&
+                                            !(ctx.getAgentMode() === 'plan' && planDisabledTools.has(calls[j].name)))
+                                            j++;
+                                        const batch = calls.slice(i, j);
+                                        const entries = [];
+                                        for (let k = 0; k < batch.length; k++) {
+                                            const tc = batch[k];
+                                            const parsed = parseArgs(tc.arguments);
+                                            const tool = ctx.toolRuntime.findTool(tc.name);
+                                            const argumentsValid = tool && parsed !== null ? validateToolArguments(tool, parsed).valid : false;
+                                            let denied;
+                                            if (tool && argumentsValid) {
+                                                const perm = await ctx.checkPermission(tool, parsed ?? {}, signal, {
+                                                    prompt: opts.permissionPrompt,
+                                                });
+                                                emitTrace('permission', {
+                                                    source: 'agent_tool',
+                                                    tool: tc.name,
+                                                    decision: perm,
+                                                    argumentHash: tracedCalls[i + k].args.sha256,
+                                                }, {
+                                                    toolCallId: tracedCalls[i + k].toolCallId,
+                                                    ...(tc.id ? { providerToolCallId: tc.id } : {}),
+                                                });
+                                                if (perm === 'deny')
+                                                    denied = deniedOutcome(tc.name);
+                                            }
+                                            entries.push({
+                                                tc,
+                                                parsed,
+                                                diff: { preWriteOld: null, editStartLine: 1 },
+                                                ...(denied ? { denied } : {}),
+                                            });
+                                        }
+                                        for (const entry of entries)
+                                            hooks.onToolHeader?.(entry.tc);
+                                        const firstAllowed = entries.find((entry) => !entry.denied);
+                                        if (firstAllowed)
+                                            hooks.onToolStart?.(firstAllowed.tc.name);
+                                        const concurrency = Math.max(1, ctx.config.subAgentConcurrency);
+                                        for (let chunkStart = 0; chunkStart < entries.length; chunkStart += concurrency) {
+                                            const chunk = entries.slice(chunkStart, chunkStart + concurrency);
+                                            // 块内同时启动(executeToolOutcome 调用即开始 I/O),再按原序 await + 回灌:
+                                            // 完成顺序任意,history 与 trace 顺序始终是原调用序。
+                                            const started = chunk.map((entry) => {
+                                                if (entry.denied)
+                                                    return Promise.resolve(entry.denied);
+                                                const hint = argumentErrorHint(entry.tc.name, runtimeContextState);
+                                                return ctx.toolRuntime.executeToolOutcome(entry.tc.name, entry.tc.arguments, signal, {
+                                                    callId: entry.tc.id,
+                                                    allowedToolNames: currentAllowedToolNames(),
+                                                    delegation: delegationForOrchestrator(),
+                                                    ...(hint ? { argumentErrorHint: hint } : {}),
+                                                    onLockAcquired: (lockedArgs) => {
+                                                        entry.diff = readDiffContext(entry.tc, lockedArgs, ctx.jailResolve);
+                                                    },
+                                                });
+                                            });
+                                            for (let k = 0; k < chunk.length; k++) {
+                                                const entry = chunk[k];
+                                                const outcome = await started[k];
+                                                usageMeter.add(outcome.usage);
+                                                opts.onToolOutcome?.(entry.tc.name, entry.parsed ?? {}, outcome);
+                                                traceToolEnd(entry.tc, i + chunkStart + k, outcome);
+                                                hooks.onToolResult?.(entry.tc, outcome.output, entry.denied ? null : entry.parsed, entry.diff.preWriteOld, entry.diff.editStartLine);
+                                                pushToolResult(history, entry.tc, outcome.output, relprune, lifecycle, scheduler, runtimeContextState, outcome.status === 'success');
+                                                const invalidatedFiles = [
+                                                    ...new Set([...(outcome.changedFiles ?? []), ...(outcome.staleFiles ?? [])]),
+                                                ];
+                                                if (invalidatedFiles.length > 0) {
+                                                    for (const changedFile of invalidatedFiles) {
+                                                        relprune?.observeMutation(history, changedFile);
+                                                        lifecycle?.pushMutation(history, history.length - 1, changedFile);
+                                                    }
+                                                    invalidateArtifacts(runtimeContextState, history, invalidatedFiles);
+                                                    runtimeContextState.lifecycleStats = lifecycle?.stats();
+                                                }
+                                            }
+                                        }
+                                        if (firstAllowed)
+                                            hooks.onToolDone?.();
+                                        i = j;
+                                    }
                                     else if (isResourceLockedCall(currentCall, ctx.toolRuntime) &&
                                         !(ctx.getAgentMode() === 'plan' && planDisabledTools.has(currentCall.name))) {
                                         // 连续文件 mutation：权限确认仍严格按原序进行；全部 preflight 完成后再启动。

package/dist/agent/stages/history-manager.js

@@ -1,3 +1,4 @@
+import { applyVisionWindow, recordVisionWindowPrune } from '../../context/vision-window.js';
 function replaceMessages(backing, messages) {
     const replacement = messages.slice();
     backing.length = 0;
@@ -147,6 +148,18 @@ class DefaultHistoryManager {
         replaceMessages(this.backing, result.messages);
         this.revision++;
     }
+    pruneVisionWindow(opts) {
+        this.assertNoActiveBatch('prune vision window');
+        const result = applyVisionWindow(this.backing, opts);
+        if (!result.changed)
+            return false;
+        replaceMessages(this.backing, result.messages);
+        // 累积埋点放在纯函数模块外部(HistoryManager 这层),单测可用 reset 隔离。
+        recordVisionWindowPrune(result.dropped);
+        // revision++ 必须:snapshot() 用 revision 标识版本,下游(compact / checkpoint)据此判断是否重建。
+        this.revision++;
+        return true;
+    }
     createCheckpoint() {
         return { revision: this.revision, messages: this.backing.slice() };
     }

package/dist/agent/stages/tool-dispatcher.js

@@ -1,4 +1,5 @@
 import { ADD_TOOL_GROUPS_TOOL_NAME } from '../../config/profiles.js';
+import { config } from '../../config/index.js';
 import { t } from '../../i18n/index.js';
 import { checkPermission as defaultCheckPermission } from '../../permissions/index.js';
 import { jailResolve as defaultJailResolve } from '../../sandbox/index.js';
@@ -6,7 +7,7 @@ import { summarizeToolArguments } from '../../session/index.js';
 import { getPlanDisabledTools } from '../../tools/constants.js';
 import { defaultToolRuntime } from '../../tools/registry.js';
 import { validateToolArguments } from '../../tools/validation.js';
-import { deniedOutcome, isParallelTool, isResourceLockedCall, parseArgs, readDiffContext } from '../tool-helpers.js';
+import { deniedOutcome, isParallelTool, isParallelOrchestrationCall, isResourceLockedCall, parseArgs, readDiffContext, } from '../tool-helpers.js';
 const DEFAULT_DEPENDENCIES = {
     toolRuntime: defaultToolRuntime,
     checkPermission: defaultCheckPermission,
@@ -205,6 +206,70 @@ class LegacyCompatibleToolDispatcher {
                 index = end;
                 continue;
             }
+            if (isParallelOrchestrationCall(current.name, toolRuntime) &&
+                !(request.policy.mode === 'plan' && getPlanDisabledTools().has(current.name))) {
+                // 连续编排调用(sub-agent)：按并发上限分块,块内并发。权限确认按原序;全部 header
+                // 必须先于首个 execute——渲染侧靠 header 建组容器批,先收口会让后续 header 另起新组。
+                const concurrency = Math.max(1, request.orchestrationConcurrency ?? config.subAgentConcurrency);
+                let end = index;
+                while (end < calls.length &&
+                    isParallelOrchestrationCall(calls[end].name, toolRuntime) &&
+                    !request.isDenied(calls[end].name) &&
+                    !(request.policy.mode === 'plan' && getPlanDisabledTools().has(calls[end].name)))
+                    end++;
+                const batch = calls.slice(index, end);
+                const entries = [];
+                for (let offset = 0; offset < batch.length; offset++) {
+                    const call = batch[offset];
+                    const parsed = parseArgs(call.arguments);
+                    const tool = toolRuntime.findTool(call.name);
+                    const argumentsValid = tool && parsed !== null ? validateToolArguments(tool, parsed).valid : false;
+                    let denied;
+                    if (tool && argumentsValid) {
+                        const decision = await checkPermission(tool, parsed ?? {}, request.signal, {
+                            prompt: request.permissionPrompt,
+                        });
+                        request.onEvent({ type: 'permission', call, callIndex: index + offset, decision });
+                        if (decision === 'deny')
+                            denied = deniedOutcome(call.name);
+                    }
+                    entries.push({
+                        call,
+                        parsed,
+                        diff: { preWriteOld: null, editStartLine: 1 },
+                        ...(denied ? { denied } : {}),
+                    });
+                }
+                for (const entry of entries)
+                    request.onEvent({ type: 'header', call: entry.call });
+                const firstAllowed = entries.find((entry) => !entry.denied);
+                if (firstAllowed)
+                    request.onEvent({ type: 'start', tool: firstAllowed.call.name });
+                for (let chunkStart = 0; chunkStart < entries.length; chunkStart += concurrency) {
+                    const chunk = entries.slice(chunkStart, chunkStart + concurrency);
+                    // 块内同时启动,再按原序 await + 回灌：完成顺序任意,history/trace 始终是原调用序。
+                    const started = chunk.map((entry) => {
+                        if (entry.denied)
+                            return Promise.resolve(entry.denied);
+                        return execute(entry.call, request.argumentErrorHint(entry.call.name), (lockedArgs) => {
+                            entry.diff = readDiffContext(entry.call, lockedArgs, jailResolve);
+                        });
+                    });
+                    for (let k = 0; k < chunk.length; k++) {
+                        const callIndex = index + chunkStart + k;
+                        const entry = chunk[k];
+                        const outcome = await started[k];
+                        record(callIndex, outcome);
+                        executionEvents(callIndex, entry.parsed, outcome);
+                        resultEvent(callIndex, outcome, entry.denied ? null : entry.parsed, entry.diff);
+                        invalidate(outcome);
+                    }
+                }
+                if (firstAllowed)
+                    request.onEvent({ type: 'done' });
+                index = end;
+                continue;
+            }
             if (isResourceLockedCall(current, toolRuntime) &&
                 !(request.policy.mode === 'plan' && getPlanDisabledTools().has(current.name))) {
                 let end = index;

package/dist/agent/tool-helpers.js

@@ -15,6 +15,7 @@ import { contextState } from '../session/compact.js';
 import { capToolResultForHistory } from '../session/compact.js';
 import { recordArtifact, knownEditTargets } from '../context/index.js';
 import { isToolResultSuccess } from '../context/utils.js';
+import { appendGuiAction } from '../session/gui-actions.js';
 /** 解析工具 arguments JSON;非法或空返 null(调用方据此降级到普通 preview)。 */
 export function parseArgs(raw) {
     try {
@@ -57,9 +58,15 @@ export function isResourceLockedTool(name, toolRuntime = defaultToolRuntime) {
 }
 export function isResourceLockedCall(call, toolRuntime = defaultToolRuntime) {
     // sub-agent 是长时全域操作(嵌套 agent 与主 agent 同权,可写任意文件/跑任意命令),
-    // 不进 mutation 并发批:逐个串行执行,避免两个子 agent 同时改工作区。
+    // 不进 mutation 并发批:那个批的语义是「同文件排队、异文件并发」。
     return call.name !== 'sub-agent' && isResourceLockedTool(call.name, toolRuntime);
 }
+/** 编排类工具(如 sub-agent)：同一轮内连续派发的多个调用按上限成批并行。
+ *  写冲突仍由子 agent 内层工具各自获取的资源锁保护(编排器本身不持锁)。 */
+export function isParallelOrchestrationCall(name, toolRuntime = defaultToolRuntime) {
+    const tool = toolRuntime.findTool(name);
+    return !!tool && toolRuntime.getToolCapabilities(tool).parallelOrchestration === true;
+}
 /** 权限拒绝时的结构化 ToolOutcome(供调度器统一回灌,不抛错中断循环)。 */
 export function deniedOutcome(name) {
     return {
@@ -131,4 +138,9 @@ export function pushToolResult(history, tc, output, pruner, lifecycle, _schedule
     if (lifecycle)
         lifecycle.pushTool(history, messageIndex, succeeded);
     runtimeContextState.lifecycleStats = lifecycle?.stats();
+    // GUI 动作台账(L2):每个 computer 动作往会话目录的 gui-actions.log 追加一行。
+    // 放这里而不是工具内部,是因为工具不该持有会话目录与文件 I/O;写失败静默,
+    // 台账是可观测性,绝不能反过来改变动作结果。
+    if (tc.name === 'computer')
+        appendGuiAction(output);
 }

package/dist/agent/tool-turn.js

@@ -3,6 +3,12 @@ const PLAN_NAG_THRESHOLD = 3;
 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.';
+/**
+ * 工具附件消息的前言。单点常量:视觉滑动窗口(src/context/vision-window.ts)靠它区分
+ * 「工具回灌的屏幕帧」与「用户粘贴的图」——两边各写一份字符串会让识别规则悄悄失效。
+ * 新增附件产出点**必须**复用这一个前言。
+ */
+export const ATTACHMENT_PREAMBLE = 'The view_image tool loaded the following visual input: ';
 /** Owns tool-turn history publication, transaction settlement, plan nag, attachments and checkpoint ordering. */
 export async function runToolTurn(input) {
     const { opts, ctx, historyManager, result, stream, step, maxSteps, planState, turnLifecycle, cancellationLifecycle, terminationPolicy, rebuildHistoryIndexes, dispatch, } = input;
@@ -53,7 +59,7 @@ export async function runToolTurn(input) {
             const content = [
                 {
                     type: 'text',
-                    text: `The view_image tool loaded the following visual input: ${names}. Analyze the attached image content directly.`,
+                    text: `${ATTACHMENT_PREAMBLE}${names}. Analyze the attached image content directly.`,
                 },
                 ...modelAttachments.map((attachment) => ({
                     type: 'image_url',

package/dist/config/index.js

@@ -4,11 +4,14 @@ import path from 'node:path';
 import dotenv from 'dotenv';
 import { getCurrentSessionId } from '../session/state.js';
 import { getNotesFilePath, extractActiveNotesSections } from '../session/notes.js';
+import { buildGuiActionsSection } from '../session/gui-actions.js';
 import { buildWorkDisciplineSection, inferModelFamily } from '../agent/work-discipline.js';
 import { buildValidationCommandsSection } from '../verification/prompt.js';
 import { getActivePresetName, readPreset } from './presets.js';
 import { detectLanguage, setLanguage, t } from '../i18n/index.js';
 import { isProfileName, profileHasGroup } from './profiles.js';
+// 端点常量归协议实现方(jev-client.ts,纯叶子无 import,不引入环);此处只引用不重定义。
+import { DEFAULT_JEV_BASE_URL } from '../tools/jev-client.js';
 /**
  * 按优先级加载配置文件并回填 process.env:
  *   候选(后者覆盖前者,优先级升序):<cwd>/.env(兼容旧用法,最低)→ ~/.mocode/config(全局)→ <cwd>/.mocode/config(项目级覆盖,最高)。
@@ -286,26 +289,32 @@ export function reinjectSessionStateIntoSystem(history) {
     return planChanged || notesChanged;
 }
 /**
- * 构造"会话状态提醒"正文(活跃 `## Plan:` 段 + 活跃笔记段正文),供 agent/core 每步
- * 拼进 requestHistory **末尾**的 ephemeral system 消息。
+ * 构造"会话状态提醒"正文(活跃 `## Plan:` 段 + 活跃笔记段 + GUI 动作台账),供 agent/core
+ * 每步拼进 requestHistory **末尾**的 ephemeral system 消息。
  *
  * 为什么在尾部而不是 history[0](prompt 缓存):plan_update / note_append 是设计上鼓励
  * 高频调用的工具,一旦它们改写系统提示,支持自动前缀缓存的后端(OpenAI / DeepSeek /
  * GLM / Qwen)就会从第一个 token 起全部 miss。放到历史末尾后,前面整段(系统提示 + 全部
- * 已有对话)保持逐字节稳定,只有尾部这一小条随 notes.md 变化。
+ * 已有对话)保持逐字节稳定,只有尾部这一小条随来源文件变化。
  *
- * 纯读函数:不改 history,也不写文件。notes.md 不存在 / 无活跃内容时返回 ''(零开销)。
+ * 台账段同样在尾部 → 抖动免费(anthropic provider 明确"动态 session reminder 不参与缓存
+ * 断点"),所以它可以每步都重写一遍,不需要像图片窗口那样成批淘汰。
+ *
+ * 纯读函数:不改 history,也不写文件。三者皆空时返回 ''(零开销)。
  */
 export function buildSessionStateReminder(sessionId = getCurrentSessionId()) {
     const plan = extractActivePlanSection(sessionId);
     const notes = extractActiveNotesSections(undefined, sessionId);
-    if (!plan && !notes)
+    const guiActions = buildGuiActionsSection(sessionId);
+    if (!plan && !notes && !guiActions)
         return '';
+    const sources = [notes || plan ? 'notes.md' : '', guiActions ? 'gui-actions.log' : ''].filter(Boolean).join(' + ');
     const parts = [
-        '## Session state (current, from notes.md)',
-        'This block mirrors the live session notepad and is refreshed every step; treat it as the authoritative plan/notes state, and ignore any older copy earlier in this conversation.',
+        `## Session state (current, from ${sources})`,
+        'This block mirrors the live session state and is refreshed every step; treat it as authoritative, and ignore any older copy earlier in this conversation.',
         ...(plan ? [plan] : []),
         ...(notes ? [notes] : []),
+        ...(guiActions ? [guiActions] : []),
     ];
     return parts.join('\n\n');
 }
@@ -533,6 +542,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,
+    subAgentConcurrency: Math.max(1, Number(process.env.SUB_AGENT_CONCURRENCY) || 5),
     frontendToolsEnabled: process.env.MOCODE_FRONTEND_TOOLS_ENABLED === 'true',
     computerUseEnabled: process.env.MOCODE_COMPUTER_USE_ENABLED === 'true',
     mcpEnabled: process.env.MOCODE_MCP_ENABLED !== 'false',
@@ -681,6 +691,51 @@ export function updateComputerUseConfig(enabled) {
     config.computerUseEnabled = enabled;
     process.env.MOCODE_COMPUTER_USE_ENABLED = enabled ? 'true' : 'false';
 }
+// ── 视觉历史滑动窗口(Computer Use)───────────────────────────────────────
+//
+// 屏幕帧永驻 history 会让图像 token 二次增长(每次请求都要重发整个 history):
+// 20 步 ≈387k tk、50 步 ≈2.35M tk,长 GUI 任务必然中途 compact 并丢掉视觉 grounding。
+// 滑动窗口按「最近 keep 条 + 成批淘汰 batch 条」把旧帧换成文本占位。详见
+// design-notes/vision-window.md。
+//
+// 这里是 process.env 直读而非 Config 单例:与其它 CU 调优项(MOCODE_CU_MAX_EDGE 等)同款,
+// 每步都在调用点求值,改 .env 后立即生效,不需要重启 REPL。
+/** 窗口保留的屏幕帧条数默认值。 */
+export const DEFAULT_VISION_KEEP = 6;
+/** 单次淘汰条数默认值。1 = 严格窗口(token 最省 / 前缀最不稳)。 */
+export const DEFAULT_VISION_BATCH = 4;
+/**
+ * 保留最近多少条屏幕帧。**0 = 完全关闭窗口**(回退到现状,一键回滚)。
+ *
+ * 空串语义与 `MOCODE_CU_DIFF_THRESHOLD`(src/tools/builtins/computer.ts:49)一致:
+ * **未配置 / 空串 → 回落默认**;显式写 0 才是 0。`Number('') === 0`,直接 Number 判数值
+ * 会让"注释掉这个变量"静默变成关闭窗口。
+ */
+export function visionKeep() {
+    const raw = process.env.MOCODE_CU_VISION_KEEP;
+    if (raw === undefined || raw.trim() === '')
+        return DEFAULT_VISION_KEEP;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        return DEFAULT_VISION_KEEP;
+    return Math.round(parsed);
+}
+/**
+ * 一次淘汰多少条。>=1;非法值回落默认。
+ *
+ * batch 是 **token 与 prompt cache 的权衡**:batch 越大,"两次淘汰之间 history 前缀字节不变"
+ * 的窗口越长,前缀命中率越高,代价是在途多留几张图。判据见文档 §7.2:
+ * 显式 prompt cache(Anthropic 断点)取 6-8;隐式前缀缓存取 4;无缓存取 1。
+ */
+export function visionBatch() {
+    const raw = process.env.MOCODE_CU_VISION_BATCH;
+    if (raw === undefined || raw.trim() === '')
+        return DEFAULT_VISION_BATCH;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed < 1)
+        return DEFAULT_VISION_BATCH;
+    return Math.round(parsed);
+}
 /** MCP 总开关；关闭时下次启动跳过 MCP 配置读取与服务连接。 */
 export function isMcpEnabled() {
     return config.mcpEnabled;
@@ -740,3 +795,48 @@ export function updateLanguageConfig(language) {
     setLanguage(language);
     process.env.MOCODE_LANGUAGE = language;
 }
+/** 当前路由模式;未知值一律回退 llm(保守:保证有可用的路由后端)。 */
+export function getRouterMode() {
+    return process.env.MOCODE_ROUTER_MODE === 'jev' ? 'jev' : 'llm';
+}
+/** /router 的写入口;持久化由调用方写 MOCODE_ROUTER_MODE(见 config/file.ts)。 */
+export function updateRouterMode(mode) {
+    process.env.MOCODE_ROUTER_MODE = mode;
+}
+function readNumberEnv(name, fallback) {
+    const raw = process.env[name];
+    if (raw === undefined || raw.trim() === '')
+        return fallback;
+    const value = Number(raw);
+    return Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : fallback;
+}
+/** 读取 Jev 路由配置(每次调用实时读 env,支持 /router 即时改)。 */
+export function getJevRouterConfig() {
+    return {
+        baseUrl: (process.env.MOCODE_ROUTER_JEV_BASE_URL || DEFAULT_JEV_BASE_URL).replace(/\/+$/, ''),
+        apiKey: process.env.MOCODE_ROUTER_JEV_API_KEY || '',
+        model: process.env.MOCODE_ROUTER_JEV_MODEL || 'jev-latest',
+        confidenceMin: readNumberEnv('MOCODE_ROUTER_CONFIDENCE_MIN', 0.65),
+        confidenceMinMcp: readNumberEnv('MOCODE_ROUTER_CONFIDENCE_MIN_MCP', 0.85),
+    };
+}
+/**
+ * /router 的写入口:把 patch 中的字段写进对应环境变量。
+ * 只改内存/进程环境;持久化由调用方写 ~/.mocode/config(见 config/file.ts)。
+ */
+export function updateJevRouterConfig(patch) {
+    if (patch.baseUrl !== undefined)
+        process.env.MOCODE_ROUTER_JEV_BASE_URL = patch.baseUrl;
+    if (patch.apiKey !== undefined)
+        process.env.MOCODE_ROUTER_JEV_API_KEY = patch.apiKey;
+    if (patch.model !== undefined)
+        process.env.MOCODE_ROUTER_JEV_MODEL = patch.model;
+    if (patch.confidenceMin !== undefined)
+        process.env.MOCODE_ROUTER_CONFIDENCE_MIN = String(patch.confidenceMin);
+    if (patch.confidenceMinMcp !== undefined)
+        process.env.MOCODE_ROUTER_CONFIDENCE_MIN_MCP = String(patch.confidenceMinMcp);
+}
+/** Jev 后端是否已具备最小可用配置(有 key 才可能成功)。 */
+export function isJevRouterConfigured() {
+    return getJevRouterConfig().apiKey.trim() !== '';
+}