mocode-ai 1.6.0 → 1.6.2

package/dist/i18n/index.js

@@ -27,7 +27,7 @@ const zhCN = {
     'commands.subagentOff': '禁止 orchestration',
     'commands.subagentStatus': '查看 orchestration gate',
     'commands.fe': '浏览器调试/桌面观察自动路由 gate',
-    'commands.feOn': '允许按需路由 browser/dev_server/screenshot',
+    'commands.feOn': '允许按需路由 browser/screenshot',
     'commands.feOff': '禁止 browser-debug/desktop-observe',
     'commands.feStatus': '查看前端能力 gate',
     'commands.cu': 'Computer Use 自动路由 gate（高危）',
@@ -46,8 +46,10 @@ const zhCN = {
     'commands.modelShow': '显示当前模型配置',
     'commands.modelUse': '按名称应用预设',
     'commands.modelDelete': '删除指定预设',
-    'commands.router': '工具预路由后端（LLM / Jev）',
-    'commands.routerStatus': '显示当前预路由后端与配置',
+    'commands.router': '工具预路由开关与后端（LLM / Jev）',
+    'commands.routerStatus': '显示当前预路由开关、后端与配置',
+    'commands.routerOn': '开启工具预路由（默认）',
+    'commands.routerOff': '关闭工具预路由（仅保留默认工具簇）',
     'commands.routerLlm': '用主 LLM 做预路由（默认）',
     'commands.routerJev': '用 Jev systemone API 做预路由',
     'commands.routerTest': '探测 Jev 端点连通性',
@@ -232,6 +234,7 @@ const zhCN = {
     'toolSummary.emptyFile': '(空文件)',
     'toolSummary.noMatches': '(无匹配)',
     'toolSummary.noOutput': '(无输出)',
+    'toolSummary.imageAttached': '图片已作为视觉输入附加',
     'toolError.unknown': '错误:未知工具 "{name}"',
     'toolError.invalidJson': '错误:工具 {name} 的 arguments 不是合法 JSON: {arguments}',
     'toolError.execution': '错误:工具 {name} 执行失败: {message}',
@@ -291,8 +294,8 @@ const zhCN = {
     'fe.status': 'Browser/desktop 自动路由：{state}',
     'fe.stateOn': '允许',
     'fe.stateOff': '禁止',
-    'fe.changedOn': '已允许按需路由 browser-debug / desktop-observe；view_image 始终属于公共工具。',
-    'fe.changedOff': '已禁止 browser-debug / desktop-observe；后续路由不会暴露 browser / dev_server / screenshot。',
+    'fe.changedOn': '已允许按需路由 browser-debug / desktop-observe；图片读取(read_file)始终属于公共工具。',
+    'fe.changedOff': '已禁止 browser-debug / desktop-observe；后续路由不会暴露 browser / screenshot（dev_server 不受此开关影响，始终可路由）。',
     'fe.usage': '用法：/fe on|off|status',
     'cu.status': 'Computer-control 自动路由：{state}',
     'cu.stateOn': '允许',
@@ -351,12 +354,17 @@ const zhCN = {
     'upgrade.pkgName': '包名：mocode-ai',
     'upgrade.failed': '[upgrade] 失败：{message}',
     'upgrade.usage': '/upgrade 用法：\n  /upgrade              升级到最新版本\n  /upgrade now          同 /upgrade\n  /upgrade check        检查当前版本与最新版本差异\n  /upgrade status       显示当前本地版本',
-    'router.status': '工具预路由后端：{mode}',
+    'router.toggleStatus': '工具预路由：{state}',
+    'router.stateOn': '开启',
+    'router.stateOff': '关闭（仅保留默认工具簇）',
+    'router.status': '预路由后端：{mode}',
     'router.modeLlm': 'LLM（与主 Agent 同一后端，默认）',
     'router.modeJev': 'Jev（TypeSafe systemone API）',
     'router.jevConfig': '端点 {baseUrl} · 模型 {model} · key {key} · 阈值 {min}/{minMcp}',
     'router.source': '来源 {env}（{path}）',
-    'router.usage': '/router 用法：\n  /router                 显示当前后端与配置\n  /router llm             用主 LLM 做预路由（默认）\n  /router jev             用 Jev systemone API 做预路由\n  /router base <url>      设置 Jev 端点（本地兼容层可指向 localhost）\n  /router key <key>       设置 Jev API key\n  /router model <name>    设置 Jev 模型名（默认 jev-latest）\n  /router min <0-1>       设置通用出簇阈值（默认 0.65）\n  /router min-mcp <0-1>   设置 mcp 专用阈值（默认 0.85）\n  /router test            探测 Jev 端点连通性',
+    'router.usage': '/router 用法：\n  /router                 显示开关、后端与配置\n  /router on              开启预路由（默认）\n  /router off             关闭预路由（仅保留默认工具簇）\n  /router llm             用主 LLM 做预路由（默认）\n  /router jev             用 Jev systemone API 做预路由\n  /router base <url>      设置 Jev 端点（本地兼容层可指向 localhost）\n  /router key <key>       设置 Jev API key\n  /router model <name>    设置 Jev 模型名（默认 jev-latest）\n  /router min <0-1>       设置通用出簇阈值（默认 0.65）\n  /router min-mcp <0-1>   设置 mcp 专用阈值（默认 0.85）\n  /router test            探测 Jev 端点连通性',
+    'router.enabledOn': '已开启工具预路由（下一轮生效）',
+    'router.enabledOff': '已关闭工具预路由：不再执行逐轮路由调用，仅保留默认工具簇（下一轮生效）',
     'router.changed': '已切换预路由后端 → {mode}（下一轮生效）',
     'router.set': '已设置 {field} = {value}（下一轮生效）',
     'router.invalid': '参数无效：{detail}',
@@ -395,7 +403,7 @@ const en = {
     'commands.subagentOff': 'Block orchestration',
     'commands.subagentStatus': 'Show orchestration gate',
     'commands.fe': 'Browser-debug and desktop-observe routing gate',
-    'commands.feOn': 'Allow browser/dev_server/screenshot routing',
+    'commands.feOn': 'Allow browser/screenshot routing',
     'commands.feOff': 'Block browser-debug and desktop-observe',
     'commands.feStatus': 'Show frontend capability gate',
     'commands.cu': 'Computer Use automatic-routing gate (high-risk)',
@@ -414,8 +422,10 @@ const en = {
     'commands.modelShow': 'Show current model configuration',
     'commands.modelUse': 'Apply a preset by name',
     'commands.modelDelete': 'Delete a preset',
-    'commands.router': 'Tool pre-routing backend (LLM / Jev)',
-    'commands.routerStatus': 'Show current pre-routing backend and config',
+    'commands.router': 'Tool pre-routing switch and backend (LLM / Jev)',
+    'commands.routerStatus': 'Show pre-routing switch, backend, and config',
+    'commands.routerOn': 'Enable tool pre-routing (default)',
+    'commands.routerOff': 'Disable tool pre-routing (keep default groups only)',
     'commands.routerLlm': 'Route with the main LLM (default)',
     'commands.routerJev': 'Route with the Jev systemone API',
     'commands.routerTest': 'Probe Jev endpoint connectivity',
@@ -598,6 +608,7 @@ const en = {
     'toolSummary.emptyFile': '(empty file)',
     'toolSummary.noMatches': '(no matches)',
     'toolSummary.noOutput': '(no output)',
+    'toolSummary.imageAttached': 'Image attached as visual input',
     'toolError.unknown': 'Error: unknown tool "{name}"',
     'toolError.invalidJson': 'Error: arguments for tool {name} are not valid JSON: {arguments}',
     'toolError.execution': 'Error: tool {name} failed: {message}',
@@ -657,8 +668,8 @@ const en = {
     'fe.status': 'Browser/desktop automatic routing: {state}',
     'fe.stateOn': 'allowed',
     'fe.stateOff': 'blocked',
-    'fe.changedOn': 'Automatic routing may now select browser-debug / desktop-observe; view_image remains a common tool.',
-    'fe.changedOff': 'Browser-debug / desktop-observe are blocked; browser / dev_server / screenshot will not be exposed.',
+    'fe.changedOn': 'Automatic routing may now select browser-debug / desktop-observe; image reading (read_file) remains a common tool.',
+    'fe.changedOff': 'Browser-debug / desktop-observe are blocked; browser / screenshot will not be exposed (dev_server is unaffected and stays routable).',
     'fe.usage': 'Usage: /fe on|off|status',
     'cu.status': 'Computer-control automatic routing: {state}',
     'cu.stateOn': 'allowed',
@@ -717,12 +728,17 @@ const en = {
     'upgrade.pkgName': 'Package: mocode-ai',
     'upgrade.failed': '[upgrade] failed: {message}',
     'upgrade.usage': 'Usage: /upgrade\n  /upgrade              Upgrade to latest\n  /upgrade now          Same as /upgrade\n  /upgrade check        Check current vs latest\n  /upgrade status       Show current local version',
-    'router.status': 'Tool pre-routing backend: {mode}',
+    'router.toggleStatus': 'Tool pre-routing: {state}',
+    'router.stateOn': 'on',
+    'router.stateOff': 'off (default groups only)',
+    'router.status': 'Pre-routing backend: {mode}',
     'router.modeLlm': 'LLM (same backend as the main agent; default)',
     'router.modeJev': 'Jev (TypeSafe systemone API)',
     'router.jevConfig': 'endpoint {baseUrl} · model {model} · key {key} · thresholds {min}/{minMcp}',
     'router.source': 'Source {env} ({path})',
-    'router.usage': 'Usage: /router\n  /router                 Show backend and config\n  /router llm             Route with the main LLM (default)\n  /router jev             Route with the Jev systemone API\n  /router base <url>      Set the Jev endpoint (point at localhost for a local compat server)\n  /router key <key>       Set the Jev API key\n  /router model <name>    Set the Jev model name (default jev-latest)\n  /router min <0-1>       Set the general activation threshold (default 0.65)\n  /router min-mcp <0-1>   Set the mcp-specific threshold (default 0.85)\n  /router test            Probe Jev endpoint connectivity',
+    'router.usage': 'Usage: /router\n  /router                 Show switch, backend, and config\n  /router on              Enable pre-routing (default)\n  /router off             Disable pre-routing (keep default groups only)\n  /router llm             Route with the main LLM (default)\n  /router jev             Route with the Jev systemone API\n  /router base <url>      Set the Jev endpoint (point at localhost for a local compat server)\n  /router key <key>       Set the Jev API key\n  /router model <name>    Set the Jev model name (default jev-latest)\n  /router min <0-1>       Set the general activation threshold (default 0.65)\n  /router min-mcp <0-1>   Set the mcp-specific threshold (default 0.85)\n  /router test            Probe Jev endpoint connectivity',
+    'router.enabledOn': 'Tool pre-routing enabled (takes effect next turn)',
+    'router.enabledOff': 'Tool pre-routing disabled: no per-turn routing call, default tool groups only (takes effect next turn)',
     'router.changed': 'Pre-routing backend switched → {mode} (takes effect next turn)',
     'router.set': 'Set {field} = {value} (takes effect next turn)',
     'router.invalid': 'Invalid argument: {detail}',

package/dist/repl/commands/image.js

@@ -10,7 +10,7 @@
 import * as layout from '../../ui/layout.js';
 import { ui } from '../../ui/theme.js';
 import { config } from '../../config/index.js';
-import { loadImageAttachment, renderChip, MAX_INLINE_BYTES_DEFAULT } from '../../attachments/image.js';
+import { loadImageAttachmentWithDownscale, renderChip, MAX_INLINE_BYTES_DEFAULT } from '../../attachments/image.js';
 import { modelSupportsVision } from '../../llm/capabilities.js';
 import { unhandled, next } from './types.js';
 export const imageCommands = [
@@ -52,7 +52,7 @@ export const imageCommands = [
             return next();
         }
         const maxBytes = config.maxImageBytes ?? MAX_INLINE_BYTES_DEFAULT;
-        const r = await loadImageAttachment(arg, { maxBytes });
+        const r = await loadImageAttachmentWithDownscale(arg, { maxBytes });
         if (!r.ok) {
             layout.contentWrite(`${ui.red}[image] ${r.reason}${ui.reset}\n`);
             return next();
@@ -60,6 +60,11 @@ export const imageCommands = [
         if (!ctx.attachments.list().find((a) => a.id === r.att.id)) {
             ctx.attachments.push(r.att);
         }
+        // 用户粘/挂的高 DPI 截图超限时会被降采样:必须说出来,否则用户以为发的是原图,
+        // 之后模型「看不清小字」时无从归因。
+        if (r.downscaledFrom) {
+            layout.contentWrite(`  ${ui.yellow}⚠ 原图 ${r.downscaledFrom.width}×${r.downscaledFrom.height} 超过内联上限,已降采样后附加(磁盘原图不变)。${ui.reset}\n`);
+        }
         layout.contentWrite(`  ${ui.dim}${renderChip(r.att)} — will attach to next message${ui.reset}\n`);
         // 提前警告(不阻断附加):当前模型已知不支持视觉(如 MiniMax M2.x / gpt-3.5 等)时,
         // 附加时就提示,而不是等发送后才在 catch 块里翻译 API 报错——减少一轮无意义请求。

package/dist/repl/commands/router.js

@@ -15,12 +15,13 @@
 import * as layout from '../../ui/layout.js';
 import { ui } from '../../ui/theme.js';
 import { t } from '../../i18n/index.js';
-import { getRouterMode, updateRouterMode, getJevRouterConfig, updateJevRouterConfig, isJevRouterConfigured, } from '../../config/index.js';
+import { getRouterMode, updateRouterMode, getJevRouterConfig, updateJevRouterConfig, isJevRouterConfigured, isToolRoutingEnabled, updateToolRoutingEnabled, } from '../../config/index.js';
 import { writeConfigKeys, CONFIG_PATH } from '../../config/file.js';
 import { probeJev } from '../../tools/jev-client.js';
 import { maskKey } from '../commands.js';
 import { unhandled, next } from './types.js';
 const ROUTER_ENV_KEYS = {
+    enabled: 'MOCODE_ROUTER_ENABLED',
     mode: 'MOCODE_ROUTER_MODE',
     baseUrl: 'MOCODE_ROUTER_JEV_BASE_URL',
     apiKey: 'MOCODE_ROUTER_JEV_API_KEY',
@@ -38,6 +39,9 @@ export const routerCommands = [
         const sub = (spaceIndex === -1 ? rest : rest.slice(0, spaceIndex)).toLowerCase();
         const arg = spaceIndex === -1 ? '' : rest.slice(spaceIndex + 1).trim();
         const showStatus = () => {
+            const enabled = isToolRoutingEnabled();
+            const stateLabel = t(enabled ? 'router.stateOn' : 'router.stateOff');
+            layout.contentWrite(`${enabled ? ui.green : ui.yellow}${t('router.toggleStatus', { state: stateLabel })}${ui.reset}\n`);
             const mode = getRouterMode();
             const label = mode === 'jev' ? t('router.modeJev') : t('router.modeLlm');
             layout.contentWrite(`${ui.accent}${t('router.status', { mode: label })}${ui.reset}\n`);
@@ -56,6 +60,14 @@ export const routerCommands = [
             showStatus();
             return next();
         }
+        // /router on | /router off —— 预路由总开关。off = 跳过每轮路由调用,只保留默认簇。
+        if (sub === 'on' || sub === 'off') {
+            const enabled = sub === 'on';
+            updateToolRoutingEnabled(enabled);
+            writeConfigKeys({ [ROUTER_ENV_KEYS.enabled]: enabled ? 'true' : 'false' });
+            layout.contentWrite(`${ui.green}${t(enabled ? 'router.enabledOn' : 'router.enabledOff')}${ui.reset}\n`);
+            return next();
+        }
         // /router llm | /router jev —— 切换后端
         if (sub === 'llm' || sub === 'jev') {
             const mode = sub === 'jev' ? 'jev' : 'llm';

package/dist/repl/commands/system.js

@@ -17,40 +17,60 @@ import { buildSlashCommands, slashHelpLines, HELP_GROUPS } from '../commands.js'
 import { startRunningListener, stopRunningListener } from '../running-input.js';
 import { checkVersion, fetchLatestVersion, getCurrentVersion, runUpgradeForeground } from '../../commands/upgrade.js';
 import { unhandled, next, exit, forward } from './types.js';
+import fs from 'node:fs';
+import path from 'node:path';
 /**
- * /init 指令:发给 agent 扫描项目并生成 AGENTS.md。已存在则让 agent 读后更新(不丢失事实)。写完供 memory 子系统下轮加载。
+ * /init 指令:发给 agent 扫描项目并生成 AGENTS.md。整体重写(非增量追加),预算分配制:
+ * 总长 ≤4000 字且 ≤ 旧文件字数(代码侧动态注入具体数字),装不下的高价值事实进
+ * .mocode/agents-draft.md 草稿而非硬塞,消除「删事实 vs 守预算」两难。写完供 memory 子系统下轮加载。
  *
- * 函数化(非 const):.codegraph/ 索引是否存在的探测放在调用瞬间,没索引时不提 codegraph,
+ * 函数化(非 const):.codegraph/ 索引与旧文件字数的探测放在调用瞬间,没索引时不提 codegraph,
  * 避免 LLM 调出失败。/init 是冷启动动作,IO 开销可忽略。
  */
 function buildInitPrompt() {
     const cg = hasCodegraphIndex()
         ? '- 若有 .codegraph/:用 use_skill 加载 codegraph skill 后用 run_command 调 codegraph explore "<架构或入口符号>" 一次拿相关源码+调用路径,别逐文件读！！！\n'
         : '';
+    // 动态注入旧文件字数:具体数字的遵循率远高于抽象原则(「≤4000」);首次生成时无旧文件则只约束绝对上限。
+    let oldSizeNote = '';
+    try {
+        const old = fs.readFileSync(path.join(process.cwd(), 'AGENTS.md'), 'utf8');
+        if (old.trim())
+            oldSizeNote = `旧 AGENTS.md 为 ${old.length} 字(新文件净字数必须 ≤ ${Math.min(4000, old.length)}:既守 4000 上限也守零和,超出即继续删低价值条目直到达标)。`;
+    }
+    catch {
+        // 无旧文件:首次生成,只受 4000 字绝对上限约束。
+    }
     return `分析当前项目(process.cwd()),生成 AGENTS.md 项目记忆文件,供 mocode 后续会话自动加载——目标是让后续会话无需重新摸索就能上手。
 
 先探查(尽量少调用拿全貌):
 ${cg}- read_file package.json(或 Cargo.toml/pyproject.toml/go.mod 等):scripts、依赖、入口、模块类型。
 - glob 顶层目录;read_file 入口文件 + 各子系统 index.ts/README。
-- 若 AGENTS.md 已存在:read_file 读它,在其基础上更新(补缺、修正过时),不丢已有准确事实。
+- 若 AGENTS.md 已存在:read_file 读它。**整体重写,不是增量追加**——不要把旧文当底稿做增量,从下面的预算出发重新分配每一条;以当前代码为准,过时/弱事实直接删,准确且仍高价值的可沿用。
+- 若 .mocode/agents-draft.md 存在:read_file 读它,把草稿里的稳定事实合入对应章节,完成后用 write_file 覆盖为空(或删除该文件)。
 
 AGENTS.md 按以下结构写(每节简短,只写稳定、非显然的事实):
 ## 项目
 一两句:是什么、技术栈、运行环境。
 ## 命令
-install / dev / build / test / typecheck / lint 等——从 package.json scripts 提炼,写原样命令行(如 \`npm run typecheck\`);没有的注明"无测试"/"无 lint"。
+install / dev / build / test / typecheck / lint 等——从 package.json scripts 提炼,写原样命令行(如 \`npm run build\`);没有的注明"无测试"/"无 lint"。
 ## 目录结构
-顶层各目录与子系统职责,一句话/个;不逐文件列。
+顶层各目录与子系统职责,一句话/个;不逐文件列。此节系统提示不会常驻注入(按需 read_file),够用即可。
 ## 约定
 从代码与现有文档提炼的硬约定:模块系统(ESM?)、命名、错误处理、工具/函数契约、易踩坑点。只写非显然、会让人踩坑的;不写"保持简洁"这种正确废话。
 ## 扩展点
-加工具/命令/provider/模块的接缝(改哪个文件、加在哪)。
+加工具/命令/provider/模块的接缝(改哪个文件、加在哪)。此节同样不常驻注入,保持简短。
+
+预算(硬上限,按字分配,参考):
+- 总长 ≤ 4000 字${oldSizeNote ? `,且 ${oldSizeNote}` : '(首次生成)'}。参考分配:项目 ≤200、命令 ≤650、目录结构 ≤400、约定 ≤2000、扩展点 ≤400。
+- **预算装不下但确有高价值的事实不丢**:write_file(append=true) 追加到 \`.mocode/agents-draft.md\`(一行一条,注明所属章节),下次 /init 再评估合入。禁止为了塞进预算牺牲准确性,也禁止超预算硬塞。
 
 硬要求:
 - 从实际代码提炼,引用具体文件名/命令/符号;不编造、不泛泛。
-- 总长 ≤ 3000 字;只写后续会话有用的稳定事实,不写易变项(当前 bug、临时文件、未决 TODO)。
-- 用 write_file 写入项目根 AGENTS.md。
-- 写完简述:写了哪几节 + 从代码里发现的 2-3 条非显然关键约定(供用户校验)。`;
+- 只写后续会话有用的稳定事实,不写易变项(当前 bug、临时文件、未决 TODO)。
+- 写入前 run_command \`wc -m AGENTS.md\` 不可用(文件还没写);改用你草稿的字数估算,并按 ${oldSizeNote ? '上述净删目标' : '4000 字上限'}自查,超了先删再写。
+- 用 write_file 写入项目根 AGENTS.md;**写完立即 read_file AGENTS.md 复查实际字数**,超限则编辑收窄后重写,直到达标。
+- 最终简述必须含对账三件套(供用户验收,缺一不可):①新旧字数对比(旧 X → 新 Y,无旧文件写"首建 Y");②删掉的条目清单(标题级);③新增的条目清单(标题级)+ 从代码里发现的 2-3 条非显然关键约定。`;
 }
 export const systemCommands = [
     (ctx) => {

package/dist/repl/commands/tool-group.js

@@ -47,7 +47,7 @@ export const toolGroupCommands = [
         return next();
     },
     // /fe|/frontend [status|on|off] — browser-debug + desktop-observe 的兼容 gate。
-    // view_image 是 common 工具，不受此开关影响。
+    // 图片读取(read_file 魔数分流)是 common 工具,不受此开关影响。
     (ctx) => {
         const { line } = ctx;
         const isFe = line === '/fe' || line.startsWith('/fe ') || line === '/frontend' || line.startsWith('/frontend ');

package/dist/repl/commands.js

@@ -94,6 +94,8 @@ export function buildSlashCommands() {
             desc: d('commands.router'),
             children: [
                 { name: 'status', value: '/router', desc: d('commands.routerStatus') },
+                { name: 'on', value: '/router on', desc: d('commands.routerOn') },
+                { name: 'off', value: '/router off', desc: d('commands.routerOff') },
                 { name: 'llm', value: '/router llm', desc: d('commands.routerLlm') },
                 { name: 'jev', value: '/router jev', desc: d('commands.routerJev') },
                 { name: 'test', value: '/router test', desc: d('commands.routerTest') },

package/dist/runtime/dev-server-manager.js

@@ -13,6 +13,7 @@ import { mkdir, open, stat } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { filterEnv, getSandboxRoot, isCommandDenied, jailResolve } from '../sandbox/index.js';
+import { defaultShellKind, shellSpawnSpec } from './shell.js';
 export class DevServerManagerError extends Error {
     code;
     constructor(code, message) {
@@ -194,10 +195,11 @@ export async function startDevServer(opts) {
     }
     let child;
     try {
-        child = spawn(IS_WINDOWS ? 'cmd.exe' : 'bash', IS_WINDOWS ? ['/d', '/s', '/c', command] : ['-c', command], {
+        const spec = shellSpawnSpec(opts.shell ?? defaultShellKind(), command);
+        child = spawn(spec.file, spec.args, {
             cwd,
             env: filterEnv(process.env),
-            windowsVerbatimArguments: IS_WINDOWS,
+            windowsVerbatimArguments: spec.windowsVerbatimArguments,
             windowsHide: true,
             stdio: ['ignore', 'pipe', 'pipe'],
         });

package/dist/runtime/shell.js

@@ -0,0 +1,153 @@
+// shell 选择器:run_command / dev_server 共用的「命令 → spawn 规格」映射。
+//
+// 为什么存在:两处硬编码(win32 → cmd.exe,其余 → bash)让 Windows 上的模型只能用 cmd 语法,
+// 而 LLM 的训练分布压倒性偏 POSIX/pwsh——`&&` 链、`$VAR`、单引号转义在 cmd 里语义不同甚至报错;
+// 非交互 cmd 还有 `timeout /t` 直接失败这类暗坑。给模型一个显式 shell 参数,把选择权交出去。
+//
+// 默认 shell 的选择是**保守**的(刻意):
+// - Windows 默认仍是 cmd.exe,与改动前逐字节一致 —— 不静默翻转所有 Windows 用户的默认解释器,
+//   现有 prompt / skill / codegraph 的 .cmd 调用都假设 cmd,翻默认是产品级破坏性变更,须显式拍板。
+// - 想用 bash/powershell:逐调用传 shell 参数,或设全局 MOCODE_SHELL=bash|powershell|cmd。
+//
+// Windows 的 Git Bash 探测(Git Bash 优先于 PATH 上的裸 bash,排除 WSL):
+// - WSL 的 System32\bash.exe 也在 PATH 上,但它进的是 Linux 发行版:路径 /mnt/f/…、工具链、
+//   甚至被安全策略拦截(wsl.exe 黑名单)都与 Windows 原生预期不符,绝不能当 bash 解析结果。
+// - 只认 Git for Windows 风格的 bash.exe(常见安装路径 + PATH 上非 System32 的命中)。
+// - 仅在**显式请求 shell=bash** 时才探测(懒求值 + 缓存):cmd 默认路径不付这个同步 IO 成本。
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+export const SHELL_KINDS = ['cmd', 'powershell', 'bash'];
+const IS_WINDOWS = process.platform === 'win32';
+/** Git for Windows 的常见固定安装位(不依赖 PATH 顺序)。 */
+const GIT_BASH_CANDIDATES = [
+    'C:\\Program Files\\Git\\bin\\bash.exe',
+    'C:\\Program Files\\Git\\usr\\bin\\bash.exe',
+    'C:\\Program Files (x86)\\Git\\bin\\bash.exe',
+    `${process.env.LOCALAPPDATA ?? ''}\\Programs\\Git\\bin\\bash.exe`,
+];
+/** PATH 命中里要排除的目录片段:WSL bash 住在 System32,语义完全不同;
+ *  WindowsApps 目录下是 wsl 存根的应用执行别名,同样不能当 bash 解析。 */
+const WSL_BASH_HINTS = ['system32', 'sysnative', 'windowsapps'];
+function findWindowsBash() {
+    for (const candidate of GIT_BASH_CANDIDATES) {
+        if (candidate && existsSync(candidate))
+            return candidate;
+    }
+    // PATH 探测:手工拆分而不是 where.exe —— 需要看到完整路径才能排除 System32(WSL)。
+    // 先看 PATH 上的 git.exe(Git for Windows 的 <root>\cmd\git.exe):由 git 根反推
+    // <root>\bin\bash.exe。自定义安装位(如 D:\Git)不在上面的候选表里,但 git 在 PATH 上
+    // 是极普遍形态 —— 从 git 推 bash 比枚举安装目录鲁棒得多。
+    const pathVar = process.env.PATH ?? process.env.Path ?? '';
+    for (const dir of pathVar.split(';')) {
+        if (!dir)
+            continue;
+        if (WSL_BASH_HINTS.some((hint) => dir.toLowerCase().includes(hint)))
+            continue;
+        if (!existsSync(join(dir, 'git.exe')))
+            continue;
+        const gitRoot = resolve(dir, '..');
+        for (const candidate of [join(gitRoot, 'bin', 'bash.exe'), join(gitRoot, 'usr', 'bin', 'bash.exe')]) {
+            if (existsSync(candidate))
+                return candidate;
+        }
+    }
+    // 兜底:PATH 上直接出现的 bash.exe(排除 System32/WindowsApps 后,多为与 git 同目录布局)。
+    for (const dir of pathVar.split(';')) {
+        if (!dir)
+            continue;
+        if (WSL_BASH_HINTS.some((hint) => dir.toLowerCase().includes(hint)))
+            continue;
+        const candidate = join(dir, 'bash.exe');
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+let cachedWindowsBash;
+/** Windows 上的 Git Bash 可执行文件路径;探不到返回 null。结果缓存。 */
+export function windowsGitBash() {
+    if (!IS_WINDOWS)
+        return null;
+    if (cachedWindowsBash === undefined)
+        cachedWindowsBash = findWindowsBash();
+    return cachedWindowsBash;
+}
+/** 测试/嵌入方显式重置探测缓存(例如单测里想模拟两种环境)。 */
+export function resetShellDetectionCache() {
+    cachedWindowsBash = undefined;
+}
+/**
+ * 平台默认 shell(**保守**,刻意不翻转既有行为):
+ * - Windows:cmd.exe(与改动前逐字节一致)。MOCODE_SHELL 显式指定可整体切换。
+ *   —— 不自动探到 Git Bash 就当默认:那会给所有 Windows 用户做静默的破坏性解释器变更,
+ *   现有 prompt/skill/codegraph 的 .cmd 调用都假设 cmd,翻默认须产品级显式拍板。
+ *   想用 bash 的用户:逐调用传 shell=bash(此时才懒探测 Git Bash 路径),或设 MOCODE_SHELL=bash。
+ * - 其余平台:bash(与旧硬编码一致);MOCODE_SHELL 只在落到真实 shell(bash/powershell)时生效,
+ *   cmd 在 Unix 无意义,忽略。
+ */
+export function defaultShellKind() {
+    const forced = parseShellKind(process.env.MOCODE_SHELL);
+    if (IS_WINDOWS)
+        return forced ?? 'cmd';
+    return forced === 'bash' || forced === 'powershell' ? forced : 'bash';
+}
+/** 解析模型/用户传入的 shell 值;大小写无关,别名 sh→bash、pwsh/powershell.exe→powershell。非法值返回 null。 */
+export function parseShellKind(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const value = raw.trim().toLowerCase();
+    if (!value)
+        return null;
+    if (value === 'cmd' || value === 'cmd.exe')
+        return 'cmd';
+    if (value === 'bash' || value === 'sh')
+        return 'bash';
+    if (value === 'powershell' || value === 'pwsh' || value === 'powershell.exe' || value === 'pwsh.exe') {
+        return 'powershell';
+    }
+    return null;
+}
+/**
+ * 把 shell 种类 + 单行命令映射成 spawn 规格。
+ *
+ * bash on Windows:优先用探测到的 Git Bash 绝对路径;调用方显式 shell=bash 而探测失败时
+ * 仍按裸 'bash' spawn(交给 PATH 解析,包括 WSL——用户显式选择就尊重,失败会由
+ * spawn error 显式报出,不静默换 shell)。
+ */
+export function shellSpawnSpec(kind, command) {
+    switch (kind) {
+        case 'cmd':
+            return { file: 'cmd.exe', args: ['/d', '/s', '/c', command], windowsVerbatimArguments: true };
+        case 'powershell':
+            // -NoProfile:不执行用户 profile,启动快且行为可复现;-NonInteractive:禁交互提示;
+            // -Command:单行命令串(与 cmd /c 心智一致)。
+            return {
+                file: IS_WINDOWS ? 'powershell.exe' : 'pwsh',
+                args: ['-NoProfile', '-NonInteractive', '-Command', command],
+                windowsVerbatimArguments: false,
+            };
+        case 'bash': {
+            const bashPath = IS_WINDOWS ? (windowsGitBash() ?? 'bash') : 'bash';
+            return { file: bashPath, args: ['-c', command], windowsVerbatimArguments: false };
+        }
+    }
+}
+/** 平台默认 shell 的可执行文件名(用于系统提示里的 PLATFORM_NOTE 措辞)。 */
+export function defaultShellLabel() {
+    const kind = defaultShellKind();
+    if (kind === 'bash')
+        return IS_WINDOWS ? 'Git Bash (POSIX)' : 'bash';
+    if (kind === 'powershell')
+        return 'PowerShell';
+    return 'cmd.exe';
+}
+/** 供 run_command / dev_server 的 description 复用的 shell 参数说明(单一事实源,防漂移)。
+ *  默认值不在文案里烘焙静态答案:真实默认由 defaultShellKind()(运行时读 env)决定,
+ *  shell.ts 模块求值时 config 链路未必已把 ~/.mocode/config 回填进 env,静态串会与
+ *  系统提示(MOCODE_SHELL 分支)自相矛盾。改为 getter,取用时才求值。
+ *  平台默认:Windows=cmd、其余=bash;MOCODE_SHELL 可翻转。 */
+export const shellParamDescription = () => 'Shell to run the command in: cmd | powershell | bash (default: ' +
+    defaultShellLabel() +
+    '). Pick the shell whose syntax the command is written in; do not mix (e.g. no %VAR% in bash, no $VAR in cmd).';
+/** 兼容旧引用:初始化即求值的快照(不追踪 MOCODE_SHELL 翻转;新代码用 shellParamDescription())。 */
+export const SHELL_PARAM_DESCRIPTION = shellParamDescription();

package/dist/skills/builtin-skills.js

@@ -20,7 +20,7 @@ run_command({ command: "codegraph node <symbol-or-path>" })
 
 注意:
 
-- Windows 上 \`codegraph\` 是 .cmd,必须走 cmd.exe /c 包装(run_command 内部已处理,直接传 \`codegraph ...\` 即可)。
+- Windows 上 \`codegraph\` 是 .cmd:cmd 默认下直接传 \`codegraph ...\` 即可;若默认 shell 是 bash(MOCODE_SHELL=bash),Git Bash 同样能按裸名解析 .cmd(\`bash -c "codegraph --version"\` 实测可用),解析不到就显式 \`shell: "cmd"\`。
 - 单次查询 ≤ 60s 超时,模型按需重试/换 query。
 
 ## 何时用

package/dist/tools/builtins/ask-human.js

@@ -111,10 +111,9 @@ export const askHumanTool = {
     name: 'ask_human',
     description: [
         'Ask the user a question and wait for their response.',
-        ' CHOICES: pass 2-4 concrete options via `options`, each as { label, description? }.',
+        ' CHOICES: pass 2-4 concrete options via `options`, each as { label, description? }; every non-empty option requires a non-empty `label`.',
         ' FREE-TEXT: pass `options: []` when the answer cannot be reduced to choices (e.g. "paste the error message").',
-        ' Every non-empty option requires a non-empty `label`; never emit [{}], omit label, or omit `options`.',
-        ' DO NOT call when the task is clear and you can pick a sensible default.',
+        ' DO NOT call when the task is clear and a sensible default exists.',
     ].join(' '),
     parameters: {
         type: 'object',

package/dist/tools/builtins/dev-server.js

@@ -1,4 +1,5 @@
 import { DevServerManagerError, getDevServerStatus, readDevServerLogs, startDevServer, stopDevServer, } from '../../runtime/dev-server-manager.js';
+import { shellParamDescription, parseShellKind } from '../../runtime/shell.js';
 function result(status, code, payload) {
     return { status, code, retryable: false, output: JSON.stringify(payload, null, 2) };
 }
@@ -20,11 +21,14 @@ function failure(error) {
 }
 export const devServerTool = {
     name: 'dev_server',
-    description: 'Manage long-running background processes such as a frontend dev server. Unlike run_command, ' +
-        'the process keeps running across tool calls, so you can start a server, then inspect it with the browser tool.\n' +
+    description: 'Run ANY long-running background process that must outlive this tool call: a dev server, an inference/model ' +
+        'service, a watcher, a log tail, a queue consumer. The process keeps running across tool calls, so you can ' +
+        'start it, poll it, inspect its output, and stop it later — foreground run_command blocks and is killed at ' +
+        'its timeout, so it cannot host such a process (do NOT work around that with `start /b`, `nohup`, `&` or ' +
+        'detached spawns: you lose the logs and the handle).\n' +
         'Actions: start (needs command; optional readyUrl or readyPattern to wait until it actually serves), ' +
-        'status (all servers, or one by id), logs (tail output; pass offset for incremental reads), stop (terminate the process tree).\n' +
-        'Always stop servers you started once you are done verifying.',
+        'status (all processes, or one by id), logs (tail output; pass offset for incremental reads), stop (terminate the process tree).\n' +
+        'Always stop processes you started once you are done verifying.',
     risk: 'dangerous',
     parameters: {
         type: 'object',
@@ -34,8 +38,11 @@ export const devServerTool = {
                 enum: ['start', 'status', 'logs', 'stop'],
                 description: 'Operation to perform',
             },
-            id: { type: 'string', description: 'Server id returned by start (required for logs/stop)' },
-            command: { type: 'string', description: 'Command to run for action=start, e.g. "npm run dev"' },
+            id: { type: 'string', description: 'Process id returned by start (required for logs/stop)' },
+            command: {
+                type: 'string',
+                description: 'Command to run for action=start, e.g. "npm run dev" or "python -m laya_play.serve --port 8765"',
+            },
             cwd: { type: 'string', description: 'Working directory inside the workspace (default: workspace root)' },
             readyUrl: {
                 type: 'string',
@@ -46,6 +53,7 @@ export const devServerTool = {
                 description: 'Wait until server output matches this case-insensitive regex, e.g. "ready in|listening on"',
             },
             timeoutMs: { type: 'integer', description: 'Readiness wait budget in ms (default 30000, max 180000)' },
+            shell: { type: 'string', enum: ['cmd', 'powershell', 'bash'], description: shellParamDescription() },
             offset: { type: 'integer', description: 'Byte offset for action=logs (default: tail)' },
             limit: { type: 'integer', description: 'Max bytes for action=logs (default 8000, max 64000)' },
         },
@@ -59,12 +67,21 @@ export const devServerTool = {
                 const command = optionalString(args, 'command');
                 if (!command)
                     return invalid('action=start requires a non-empty command.');
+                // shell 非法值显式报错,不静默回落:模型以为在 powershell 里起服务却落到 cmd,
+                // 语法差异导致的启动失败极难归因。
+                let shell = null;
+                if (args.shell !== undefined) {
+                    shell = parseShellKind(args.shell);
+                    if (!shell)
+                        return invalid(`Invalid shell "${String(args.shell)}". Use cmd, powershell, or bash.`);
+                }
                 const started = await startDevServer({
                     command,
                     cwd: optionalString(args, 'cwd'),
                     readyUrl: optionalString(args, 'readyUrl'),
                     readyPattern: optionalString(args, 'readyPattern'),
                     ...(args.timeoutMs === undefined ? {} : { timeoutMs: Number(args.timeoutMs) }),
+                    ...(shell ? { shell } : {}),
                     ...(ctx?.signal ? { signal: ctx.signal } : {}),
                 });
                 return result('success', 'OK', started);

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

@@ -13,23 +13,15 @@ function conflict(path, details) {
 }
 export const editFileTool = {
     name: 'edit_file',
-    description: `Replace content in a file transactionally. Supports two modes:
+    description: `Replace content in a file transactionally. Two modes:
 
-**String replacement mode (default):** Provide old_string that occurs exactly once in the file. The old_string must be copied verbatim from a fresh read_file output — do NOT reconstruct from memory, summaries, or grep output, as these lose whitespace/indentation details. Common failure modes: trailing whitespace, tabs vs spaces, indentation changes, line-ending mismatches (CRLF vs LF).
+**String replacement (default):** old_string must occur EXACTLY once, copied verbatim from a fresh read_file output — never reconstruct from memory, summaries, or grep output (whitespace/indentation/line-ending details are lost there).
 
-**Line-range mode:** Provide line_start and line_end (1-based, inclusive) instead of old_string. Use this when the exact text is hard to reproduce or when replacing a large block.
+**Line-range:** line_start/line_end (1-based, inclusive) instead of old_string — for large blocks, repeated patterns, or hard-to-reproduce text.
 
-expected_hash is required (sha256 from read_file artifact header) and must match the current file hash. If the file changed after your read, the edit is rejected. Recovery: call read_file again on the same path and copy both the new hash and exact text.
+expected_hash (sha256 from read_file artifact header) is required and must match the current file; changed-since-read edits are rejected — re-read and retry with the new hash.
 
-**When to use which mode:**
-- String replacement: small, unique text fragments (function signatures, config keys, error messages)
-- Line-range: large blocks, repeated patterns, or when whitespace precision is critical
-
-**Anti-patterns (will fail):**
-- old_string reconstructed from memory or a summary
-- old_string copied from a previous tool call that may be stale
-- old_string that appears multiple times (add more context to make it unique)
-- expected_hash from a different file or an old read_file call`,
+Anti-patterns (will fail): old_string from memory/summary/stale call; multiple occurrences (add context to disambiguate); hash from another file or old read.`,
     risk: 'confirm',
     parameters: {
         type: 'object',

package/dist/tools/builtins/glob.js

@@ -4,8 +4,8 @@ import { getSandboxRoot, isInsideRoot } from '../../sandbox/index.js';
 // ---------- glob ----------
 export const globTool = {
     name: 'glob',
-    description: 'Find files matching a glob pattern (e.g. **/*.ts). Auto-excludes node_modules/.git.' +
-        ' For architecture or call chains, prefer loading the `codegraph` skill (use_skill).',
+    description: 'Find files matching a glob pattern (e.g. **/*.ts). Auto-excludes node_modules/.git. ' +
+        'For architecture or call chains, prefer the codegraph skill.',
     parameters: {
         type: 'object',
         properties: {