mocode-ai 1.2.10 → 1.3.1

package/dist/i18n/index.js

@@ -55,6 +55,10 @@ const zhCN = {
     'commands.upgradeStatus': '显示当前本地版本',
     'help.title': '可用斜杠命令',
     'help.hint': '（› 表示可进入子菜单；→ 后为实际执行命令）',
+    'help.groupFrequent': '常用',
+    'help.groupSession': '会话与记忆',
+    'help.groupConfig': '配置与外观',
+    'help.groupOther': '其他',
     'language.current': '当前语言：{language}',
     'language.changed': '语言已切换为中文。',
     'language.usage': '用法：/language zh-CN|en',
@@ -102,13 +106,23 @@ const zhCN = {
     'prompt.revertFiles': '撤销文件改动{detail}',
     'prompt.revertDetail': '（{count} 个文件恢复到回滚前）',
     'prompt.messagesOnly': '只撤销消息，保留文件改动',
+    'prompt.emptyPlaceholder': '输入消息，按 Enter 开始对话；输入 /help 查看命令…',
+    'welcome.gettingStarted': '快速上手',
+    'welcome.start1': '直接输入消息，按 Enter 发送；Shift+Tab 切换 auto / plan 模式',
+    'welcome.start2': '输入 / 打开命令菜单；输入 /help 查看全部命令',
+    'welcome.start3': '长文本直接粘贴，会折叠成粘贴块',
+    'welcome.capabilities': '我能做什么',
+    'welcome.cap1': '读懂并修改代码：修 bug、重构、写测试、跨文件检索',
+    'welcome.cap2': '运行命令与脚本，根据输出继续排查',
+    'welcome.cap3': '生成文档与图片；/memory 管理记忆，/skills 管理技能',
+    'welcome.try': '试试：「修复 <某个 bug>」或「解释这个仓库的结构」',
     'intervention.custom': '其他（自定义输入）',
     'intervention.defaultChoice': '自动选择默认项',
     'intervention.emptyInput': '自动返回空输入',
     'intervention.nonInteractive': '[介入] {title}（非交互环境，{kind}）',
     'repl.idle': '空闲',
     'repl.loadFailed': '（加载失败）',
-    'repl.resumed': '（已续接会话 {id}）',
+    'repl.resumeAnchor': '已恢复会话 {id} · {count} 条消息 · 当前模型 {model}（/model switch 可切换）',
     'repl.noSessions': '（没有已保存的会话）',
     'repl.noValue': '（无）',
     'repl.historyCleared': '（历史已清空，保留系统提示）',
@@ -122,6 +136,10 @@ const zhCN = {
     'repl.themeList': '可用主题：',
     'repl.themeCurrent': '（当前：{theme}；用 /theme <名称> 切换）',
     'repl.themeChanged': '（已切换主题 {theme}）',
+    'repl.modeCurrent': '当前模式：{mode}；/plan 切到只读探查并产出计划，/auto 切回全工具执行',
+    'repl.unknownCommand': '未知命令：{value}',
+    'repl.didYouMean': '你是不是想输入 {value}？',
+    'repl.unknownCommandHint': '输入 /help 查看全部命令（普通文本直接打字发送，不必加 /）',
     'theme.default': '16 色原版（深底）',
     'theme.light': '浅底终端',
     'theme.solarized': 'Solarized 强调色',
@@ -150,6 +168,7 @@ const zhCN = {
     'banner.disabled': '关闭',
     'status.modeSwitch': 'Shift+Tab 切换',
     'status.history': '历史 ↑{count}（PgDn 回底）',
+    'status.interruptHint': 'Esc / Ctrl+C 中断',
     'status.measured': '实测',
     'status.estimated': '估算',
     'status.messages': '{count} 条消息',
@@ -187,6 +206,11 @@ const zhCN = {
     'repl.visionUnsupported': '当前模型 {model} 不支持视觉输入。',
     'repl.originalError': '原始:{message}',
     'repl.visionHint': '提示:运行 /model 切换到支持视觉的模型（如 gpt-4o / claude-3.5-sonnet / gemini-1.5-pro）。',
+    'repl.llmAuthError': '认证失败：API key 无效或未配置。输入 /model 配置 baseURL / apiKey，或退出后在 .env、~/.mocode/config 设置 MOCODE_LLM_API_KEY（参考 .env.example）。',
+    'repl.llmQuotaError': '请求被限流或配额不足（429）。稍等片刻重试，或输入 /model switch 切换其他模型。',
+    'repl.llmTimeoutError': '请求超时：模型服务响应过慢。可重试，或输入 /model switch 换一个模型。',
+    'repl.llmNetworkError': '网络错误：无法连接 {base}。检查网络连接，或输入 /model 核对 baseURL 配置。',
+    'repl.llmContextError': '上下文超长：输入 /compact 压缩会话后重试。',
     'permission.path': '路径: {value}',
     'permission.command': '命令: {value}',
     'permission.task': '任务: {value}',
@@ -194,6 +218,7 @@ const zhCN = {
     'permission.dangerTitle': '⚠ 高风险操作: {tool}',
     'permission.confirmTitle': '确认执行: {tool}',
     'permission.dangerWarning': '⚠ 此操作可能产生不可逆副作用，请谨慎确认。',
+    'permission.firstTimeHint': '说明：面板按工具风险等级弹出。「允许」仅放行本次操作；选择会话级/项目级选项后，同类命令不再重复询问。',
     'permission.confirmExecute': '确认执行',
     'permission.allowForever': '以后不再询问此工具',
     'permission.deny': '拒绝',
@@ -314,6 +339,10 @@ const en = {
     'commands.upgradeStatus': 'Show current local version',
     'help.title': 'Available slash commands',
     'help.hint': '(› opens a submenu; → shows the command that will run)',
+    'help.groupFrequent': 'Frequently used',
+    'help.groupSession': 'Session & memory',
+    'help.groupConfig': 'Configuration',
+    'help.groupOther': 'Other',
     'language.current': 'Current language: {language}',
     'language.changed': 'Language switched to English.',
     'language.usage': 'Usage: /language zh-CN|en',
@@ -361,13 +390,23 @@ const en = {
     'prompt.revertFiles': 'Revert file changes{detail}',
     'prompt.revertDetail': ' ({count} files restored to before the rollback)',
     'prompt.messagesOnly': 'Roll back messages only; keep file changes',
+    'prompt.emptyPlaceholder': 'Type a message, press Enter to send; /help for commands…',
+    'welcome.gettingStarted': 'Getting started',
+    'welcome.start1': 'Type a message and press Enter; Shift+Tab toggles auto / plan mode',
+    'welcome.start2': 'Type / for the command menu; /help lists all commands',
+    'welcome.start3': 'Paste long text directly — it folds into a paste block',
+    'welcome.capabilities': 'What I can do',
+    'welcome.cap1': 'Read and modify code: fix bugs, refactor, write tests, search across files',
+    'welcome.cap2': 'Run commands and scripts, then keep going based on the output',
+    'welcome.cap3': 'Generate docs and images; /memory manages memory, /skills manages skills',
+    'welcome.try': 'Try: "fix <a bug>" or "explain the structure of this repository"',
     'intervention.custom': 'Other (custom input)',
     'intervention.defaultChoice': 'automatically selected the default',
     'intervention.emptyInput': 'automatically returned empty input',
     'intervention.nonInteractive': '[intervention] {title} (non-interactive; {kind})',
     'repl.idle': 'Idle',
     'repl.loadFailed': '(load failed)',
-    'repl.resumed': '(resumed session {id})',
+    'repl.resumeAnchor': 'Resumed session {id} · {count} messages · model {model} (/model switch to change)',
     'repl.noSessions': '(no saved sessions)',
     'repl.noValue': '(none)',
     'repl.historyCleared': '(history cleared; system prompt kept)',
@@ -381,6 +420,10 @@ const en = {
     'repl.themeList': 'Available themes:',
     'repl.themeCurrent': '(current: {theme}; use /theme <name> to switch)',
     'repl.themeChanged': '(switched theme to {theme})',
+    'repl.modeCurrent': 'Current mode: {mode}; /plan for read-only planning, /auto for full tool access',
+    'repl.unknownCommand': 'Unknown command: {value}',
+    'repl.didYouMean': 'Did you mean {value}?',
+    'repl.unknownCommandHint': 'Run /help for all commands (plain text is sent as-is, no slash needed)',
     'theme.default': 'Original 16-color theme (dark)',
     'theme.light': 'Light terminal',
     'theme.solarized': 'Solarized accents',
@@ -409,6 +452,7 @@ const en = {
     'banner.disabled': 'Disabled',
     'status.modeSwitch': 'Shift+Tab Switch',
     'status.history': 'History ↑{count} (PgDn to bottom)',
+    'status.interruptHint': 'Esc / Ctrl+C to interrupt',
     'status.measured': 'measured',
     'status.estimated': 'estimated',
     'status.messages': '{count} messages',
@@ -446,6 +490,11 @@ const en = {
     'repl.visionUnsupported': 'The current model, {model}, does not support vision input.',
     'repl.originalError': 'Original: {message}',
     'repl.visionHint': 'Tip: run /model and switch to a vision-capable model (for example, gpt-4o, claude-3.5-sonnet, or gemini-1.5-pro).',
+    'repl.llmAuthError': 'Authentication failed: the API key is invalid or not configured. Run /model to set baseURL / apiKey, or set MOCODE_LLM_API_KEY in .env or ~/.mocode/config (see .env.example).',
+    'repl.llmQuotaError': 'Rate limited or quota exhausted (429). Retry in a moment, or run /model switch to use another model.',
+    'repl.llmTimeoutError': 'Request timed out: the model service responded too slowly. Retry, or run /model switch to use another model.',
+    'repl.llmNetworkError': 'Network error: cannot reach {base}. Check your connection, or run /model to verify the baseURL.',
+    'repl.llmContextError': 'Context too long: run /compact to compress the session, then retry.',
     'permission.path': 'Path: {value}',
     'permission.command': 'Command: {value}',
     'permission.task': 'Task: {value}',
@@ -453,6 +502,7 @@ const en = {
     'permission.dangerTitle': '⚠ High-risk operation: {tool}',
     'permission.confirmTitle': 'Confirm execution: {tool}',
     'permission.dangerWarning': '⚠ This operation may have irreversible side effects. Confirm carefully.',
+    'permission.firstTimeHint': "Note: this panel appears based on each tool's risk level. 'Allow' approves only this action; session/project options stop repeated prompts for the same command.",
     'permission.confirmExecute': 'Confirm and run',
     'permission.allowForever': 'Always allow this tool',
     'permission.deny': 'Deny',

package/dist/llm/index.js

@@ -144,6 +144,32 @@ export function isContextLengthError(err) {
         /(input|prompt|context|request).{0,20}too (long|large)|exceeds? the (model|maximum|context)/.test(msg) ||
         /reduce the length|上下文(长度)?(超|过)|超出.*上下文|请求过长|长度超过|token 数?超过/.test(msg));
 }
+export function classifyChatError(msg) {
+    const m = (msg || '').toLowerCase();
+    if (!m)
+        return null;
+    // 上下文超长(复用 transport 层判定,提示 /compact)
+    if (isContextLengthError({ message: msg }))
+        return 'context';
+    // 认证:401 / key 无效缺失
+    if (/\b401\b|unauthorized|forbidden[^\n]*(?:api[ _-]?key|token)/.test(m) ||
+        /(?:invalid|incorrect|missing|no|not[ _-]?(?:provided|configured|valid))[^\n]{0,24}api[ _-]?key/.test(m) ||
+        /api[ _-]?key[^\n]{0,24}(?:invalid|incorrect|missing|not[ _-]?(?:provided|configured|valid))/.test(m) ||
+        /无效的|未配置.{0,8}(?:key|密钥)|(?:密钥|令牌).{0,8}(?:无效|错误)/.test(msg))
+        return 'auth';
+    // 限流 / 配额:429 / rate limit / quota / 余额不足
+    if (/\b429\b|rate[ _-]?limit|insufficient[ _-]?(?:quota|balance|funds)|quota[ _-]?(?:exceeded|exhausted)/.test(m) ||
+        /频率限制|使用量已超出|余额不足|配额(?:不足|已用完|超)/.test(msg))
+        return 'quota';
+    // 超时 / 连接中断
+    if (/\btime(?:d|ed)?[ _-]?out\b|etimedout|econnreset|socket hang up|econnaborted|请求超时/.test(m))
+        return 'timeout';
+    // 网络 / DNS / baseURL 不通
+    if (/\benotfound\b|\beconnrefused\b|\beai_again\b|getaddrinfo|fetch failed|network error|certificate/.test(m) ||
+        /无法连接|网络(?:错误|异常|不可用)|域名解析/.test(msg))
+        return 'network';
+    return null;
+}
 /** 从 OpenAI APIError.headers 解析 Retry-After(秒);不支持或缺失返回 undefined。封顶 RETRY_MAX_MS。 */
 export function getRetryAfterMs(err) {
     const headers = err?.headers;

package/dist/permissions/index.js

@@ -4,6 +4,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { promptIntervention } from '../ui/intervention.js';
 import { config } from '../config/index.js';
+import { readConfigFile, updateConfigKey } from '../config/file.js';
 import { getSandboxRoot } from '../sandbox/index.js';
 import { t } from '../i18n/index.js';
 const PERMISSIONS_PATH = path.join(os.homedir(), '.mocode', 'permissions.json');
@@ -138,14 +139,30 @@ export async function checkPermission(tool, args, signal, options = {}) {
     const denyOption = t('permission.deny');
     const dangerous = getToolRisk(tool) === 'dangerous';
     const choices = [onceOption, sessionOption, projectOption, alwaysOption, denyOption];
+    // 新手首次审批引导:第一次弹出确认面板时附一段说明(每个用户只出现一次,
+    // ~/.mocode/config 的 onboarding_approval_hint 标记;读写失败静默,不阻断审批)。
+    let detail = summarizeArgs(args) + (dangerous ? `\n\n${t('permission.dangerWarning')}` : '');
+    const ONBOARDING_KEY = 'onboarding_approval_hint';
+    try {
+        if (!readConfigFile()[ONBOARDING_KEY]) {
+            detail += `\n\n${t('permission.firstTimeHint')}`;
+            updateConfigKey(ONBOARDING_KEY, '1');
+        }
+    }
+    catch {
+        // 标记读/写失败 → 视为未展示过:多提示一次无害,少提示也只是回归现状。
+    }
     const result = await (options.prompt ?? promptIntervention)({
         type: 'choice',
         title: dangerous
             ? t('permission.dangerTitle', { tool: tool.name })
             : t('permission.confirmTitle', { tool: tool.name }),
-        detail: summarizeArgs(args) + (dangerous ? `\n\n${t('permission.dangerWarning')}` : ''),
+        detail,
         options: choices,
         allowCustom: false,
+        // dangerous 默认落在「拒绝」:面板一弹出就高亮"允许一次"时,用户顺手回车就把命令放出去了。
+        // 放行必须是一次明确的选择(↑↓ 移到某一项,或按数字键),而不是默认项的惯性。
+        defaultIndex: dangerous ? choices.indexOf(denyOption) : 0,
     });
     if (signal?.aborted || result.action === 'cancelled' || result.value === denyOption)
         return 'deny';

package/dist/repl/index.js

@@ -19,7 +19,7 @@ import { promptWithSlashMenu, promptTurnPicker, promptSessionPicker, promptTheme
 import { promptIntervention } from '../ui/intervention.js';
 import { registerToolsExtension } from '../tools/registry.js';
 import { initializeAllMcp, getMcpTools, closeAllMcp } from '../mcp/index.js';
-import { estimateMessagesTokens, reconfigureClient, refreshChatTools, chatTools, estimatePromptTokens, estimateTokens, } from '../llm/index.js';
+import { estimateMessagesTokens, reconfigureClient, refreshChatTools, chatTools, estimatePromptTokens, estimateTokens, classifyChatError, } from '../llm/index.js';
 import { loadImageAttachment, renderChip, MAX_INLINE_BYTES_DEFAULT, } from '../attachments/image.js';
 import { modelSupportsVision } from '../llm/capabilities.js';
 import { computePruneStats } from '../context/relevance.js';
@@ -144,6 +144,87 @@ function slashHelpLines(nodes = buildSlashCommands(), parentPath = '', depth = 0
     }
     return lines;
 }
+/** chat 常见错误类别 → 中文引导文案的 i18n 键(识别不出的错误不走这张表,保留原始诊断)。 */
+const LLM_ERROR_HINT_KEYS = {
+    auth: 'repl.llmAuthError',
+    quota: 'repl.llmQuotaError',
+    timeout: 'repl.llmTimeoutError',
+    network: 'repl.llmNetworkError',
+    context: 'repl.llmContextError',
+};
+/** /help 的分组:按使用场景归组,组内保持菜单树顺序。未列入的顶层命令兜底进「其他」。 */
+const HELP_GROUPS = [
+    { key: 'help.groupFrequent', names: ['/help', '/clear', '/context', '/compact', '/resume', '/model'] },
+    { key: 'help.groupSession', names: ['/sessions', '/rollback', '/memory', '/skills', '/skill', '/init'] },
+    { key: 'help.groupConfig', names: ['/mode', '/subagent', '/fe', '/theme', '/pet', '/image', '/language', '/upgrade'] },
+];
+/**
+ * 菜单树里全部可用命令名(含分支路径与叶子的真实命令),供未知命令纠错建议用。
+ * /quit、/frontend 确实可用但没登记进菜单树,单独补上——否则用户照提示打了却仍被判未知。
+ */
+function knownCommandNames() {
+    const out = [];
+    const walk = (nodes, parent) => {
+        for (const node of nodes) {
+            const path = parent ? `${parent} ${node.name}` : node.name;
+            out.push(path);
+            const actual = node.value?.trim();
+            if (actual)
+                out.push(actual.split(/\s+/)[0]);
+            if (node.children?.length)
+                walk(node.children, path);
+        }
+    };
+    walk(buildSlashCommands(), '');
+    out.push('/quit', '/frontend');
+    return [...new Set(out)];
+}
+/**
+ * 是否"长得像一条斜杠命令":单个前导 / + 词字符(字母开头,可含数字/下划线/连字符)。
+ * 用来把 /hepl 这类拼写错误与 /tmp/foo、/src/index.ts:12:5 这类路径区分开——
+ * 后者在编码 agent 里很常见,同样以 / 开头,绝不能被当成命令拦下。
+ */
+function isCommandShape(cmd) {
+    return /^\/[A-Za-z][\w-]*$/.test(cmd);
+}
+/** Levenshtein 距离(标准 DP)。短命令字符串,直接两行数组滚动即可。 */
+function editDistance(a, b) {
+    if (a === b)
+        return 0;
+    if (!a.length)
+        return b.length;
+    if (!b.length)
+        return a.length;
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const cur = [i];
+        for (let j = 1; j <= b.length; j++) {
+            cur[j] = Math.min(prev[j] + 1, // 删
+            cur[j - 1] + 1, // 插
+            prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev = cur;
+    }
+    return prev[b.length];
+}
+/** 未知命令的纠错建议:返回编辑距离最近且在阈值内的命令名,没有则 null(不要瞎猜)。 */
+export function suggestCommand(input) {
+    // 阈值随长度放宽,但对短命令保持严格:/hepl(5) vs /help 距离 2 → 命中;
+    // /x(2) 不该被建议成任何东西。
+    const threshold = Math.max(1, Math.ceil(input.length / 3));
+    let best = null;
+    let bestDist = Infinity;
+    for (const name of knownCommandNames()) {
+        if (name === input)
+            continue; // 别建议"你自己"(分支节点如 /mode 也在候选里)
+        const d = editDistance(input, name);
+        if (d < bestDist) {
+            bestDist = d;
+            best = name;
+        }
+    }
+    return bestDist <= threshold ? best : null;
+}
 /** 主题名 → 本地化描述。 */
 function themeDescription(name) {
     const key = `theme.${name}`;
@@ -815,6 +896,26 @@ export async function startRepl(initialHistory, sessionId, sandboxRootOverride,
         tools: chatTools.map((tool) => tool.function.name).join(' · '),
         memoryEnabled: isMemoryEnabled(),
     });
+    /**
+     * 欢迎引导块:新会话开场写在内容区(banner 之下),教用户怎么开始 / 能做什么。
+     * 首次提交任何输入(消息或斜杠命令)前由 layout.dismissWelcomeBlock 整块撤掉——
+     * 「一打开就能看见,开始干活就消失」。/clear 清空后重新写一次(回到空会话状态)。
+     */
+    const welcomeLines = () => [
+        '',
+        `  ${ui.accent}${ui.bold}${t('welcome.gettingStarted')}${ui.reset}`,
+        `  ${ui.dim}· ${t('welcome.start1')}${ui.reset}`,
+        `  ${ui.dim}· ${t('welcome.start2')}${ui.reset}`,
+        `  ${ui.dim}· ${t('welcome.start3')}${ui.reset}`,
+        '',
+        `  ${ui.accent}${ui.bold}${t('welcome.capabilities')}${ui.reset}`,
+        `  ${ui.dim}· ${t('welcome.cap1')}${ui.reset}`,
+        `  ${ui.dim}· ${t('welcome.cap2')}${ui.reset}`,
+        `  ${ui.dim}· ${t('welcome.cap3')}${ui.reset}`,
+        '',
+        `  ${ui.dim}${t('welcome.try')}${ui.reset}`,
+        '',
+    ];
     // 开场:按 config.theme 切主题(横幅 / 状态行 / 后续渲染皆用新色),再进 alt screen + 状态基线 + 清内容区。
     // --resume 有历史则渲染对话,否则横幅。
     setTheme(config.theme);
@@ -823,6 +924,10 @@ export async function startRepl(initialHistory, sessionId, sandboxRootOverride,
     layout.clearContent();
     layout.contentMode();
     if (history.some((m) => m.role === 'user')) {
+        // --resume 锚点:先给一行会话摘要(id/消息数/当前模型),新手对恢复状态有定位感,
+        // 再铺历史对话。renderHistory 之后不再追加,锚点恒为恢复内容的第一行。
+        const anchorCount = history.filter((m) => m.role !== 'system').length;
+        layout.contentWrite(`${ui.dim}${t('repl.resumeAnchor', { id: currentSessionId, count: anchorCount, model: config.model })}${ui.reset}\n`);
         renderHistory(history);
         // 强制回尾:同 /resume 命令,renderHistory 展开详情会设 scrollOffset>0,需复位避免闪烁。
         layout.resetScroll();
@@ -863,6 +968,10 @@ export async function startRepl(initialHistory, sessionId, sandboxRootOverride,
             }
         }
     }
+    // 新会话开场:banner 之后写欢迎引导块(--resume 有历史时不写,历史本身就是上下文)。
+    if (!history.some((m) => m.role === 'user')) {
+        layout.writeWelcomeBlock(welcomeLines());
+    }
     /**
      * 切换 agent 模式(Shift+Tab 触发,经 prompt.ts 的 onCycleMode 回调)。
      * cycleMode 翻 agentMode + applyMode 重写 history[0] + refreshStatusBase 设状态行 modeTag;
@@ -872,7 +981,10 @@ export async function startRepl(initialHistory, sessionId, sandboxRootOverride,
         history[0] = { role: 'system', content: buildSystemMessage(planMode) };
     };
     const cycleMode = () => {
-        setAgentMode(getAgentMode() === 'plan' ? 'auto' : 'plan'); // listener 接手 applyMode + refreshStatusBase
+        const prev = getAgentMode();
+        setAgentMode(prev === 'plan' ? 'auto' : 'plan'); // listener 接手 applyMode + refreshStatusBase
+        // Shift+Tab 只有 chip 变化,新手可能没感知:内容区补一行确认(与 /plan / /auto 同文案,复用不新造键)。
+        layout.contentWrite(`${ui.dim}${t(prev === 'plan' ? 'repl.autoChanged' : 'repl.planChanged')}${ui.reset}\n`);
     };
     // 注册模式变更监听器:switch_mode 工具 / cycleMode / /plan / /auto / runTurn 调 setAgentMode 时同步触发,
     // 重写 history[0] 系统提示(切 plan 追加 PLAN_MODE_SUFFIX)+ 刷状态行 modeTag。
@@ -1075,7 +1187,17 @@ export async function startRepl(initialHistory, sessionId, sandboxRootOverride,
                 layout.contentWrite(`${ui.dim}${t('repl.visionHint')}${ui.reset}\n`);
             }
             else {
-                layout.contentWrite(`${ui.red}${t('repl.errorLabel')}${ui.reset} ${msg}\n`);
+                // 常见错误翻译:认证 / 限流 / 超时 / 网络 / 上下文超长 → 中文引导(新手第一堵墙);
+                // 认不出的错误保留原始 provider 诊断,不瞎猜。
+                const kind = classifyChatError(msg);
+                if (kind) {
+                    const key = LLM_ERROR_HINT_KEYS[kind];
+                    layout.contentWrite(`${ui.red}${t('repl.errorLabel')}${ui.reset} ${t(key, { base: config.baseURL, model: config.model })}\n`);
+                    layout.contentWrite(`${ui.dim}${t('repl.originalError', { message: msg })}${ui.reset}\n`);
+                }
+                else {
+                    layout.contentWrite(`${ui.red}${t('repl.errorLabel')}${ui.reset} ${msg}\n`);
+                }
             }
         }
         finally {
@@ -1121,9 +1243,10 @@ export async function startRepl(initialHistory, sessionId, sandboxRootOverride,
         contextState.ephemeralText = undefined;
         lastTurnUsage = undefined; // 续接:旧会话的 token 累计已无意义,清空等下轮覆写
         layout.clearContent();
+        // 锚点行:会话 id / 消息数 / 当前模型,给续接的会话一个定位起点(与 --resume 启动路径同文案)。
+        const anchorCount = history.filter((m) => m.role !== 'system').length;
+        layout.contentWrite(`${ui.dim}${t('repl.resumeAnchor', { id: loaded.id, count: anchorCount, model: config.model })}${ui.reset}\n\n`);
         renderHistory(history);
-        // 末尾 \n\n:与后续用户消息(❯ bubble)之间空一行。
-        layout.contentWrite(`${ui.dim}${t('repl.resumed', { id: loaded.id })}${ui.reset}\n\n`);
         // 强制回尾:renderHistory 展开 mutation 工具详情会经 contentInsertAfter 设置 scrollOffset>0;
         // 先把"已续接会话"提示写入缓冲，再统一回尾重画，避免切换后视口停留在历史顶部。
         layout.resetScroll();
@@ -1150,7 +1273,6 @@ export async function startRepl(initialHistory, sessionId, sandboxRootOverride,
             input = await promptWithSlashMenu({
                 prompt: PROMPT,
                 commands: buildSlashCommands(),
-                queryHistory,
                 onCycleMode: cycleMode,
                 // /rollback 预填优先;否则上一轮运行中 typeahead 打的字 → 预填进输入框,用户可改可发
                 ...(pendingPrefill
@@ -1174,8 +1296,12 @@ export async function startRepl(initialHistory, sessionId, sandboxRootOverride,
         hasSubmittedInput = true;
         if (line === '/exit' || line === '/quit')
             break;
+        // 首次提交任何输入(消息或斜杠命令)→ 撤掉欢迎引导块,不让它出现在工作画面里。
+        layout.dismissWelcomeBlock();
         // RUNNING 态:回显输入 → 底栏改 dim 占位、光标回内容续写位
         const cmd = line.split(/\s+/)[0];
+        // 命令被刻意改写成别的内容后转发给 agent(如 /init)。这类不算"未知命令"。
+        let forwardToAgent = false;
         // 语言命令把视觉分隔放在确认文案之后；避免回显后先空一行、下一条命令却紧贴确认。
         echoInput(input, cmd !== '/language');
         const state = runningStateFor(cmd);
@@ -1183,9 +1309,28 @@ export async function startRepl(initialHistory, sessionId, sandboxRootOverride,
         refreshStatusBase(history);
         layout.enterRunningMode(state.status, placeholder);
         if (line === '/help') {
+            const nodes = buildSlashCommands();
             layout.contentWrite(`${ui.bold}${t('help.title')}${ui.reset}\n`);
             layout.contentWrite(`${ui.dim}${t('help.hint')}${ui.reset}\n`);
-            layout.contentWrite(`${slashHelpLines().join('\n')}\n`);
+            // 按使用场景分组输出,常用置顶;未归组命令(如 /exit)兜底进「其他」。
+            let first = true;
+            for (const group of HELP_GROUPS) {
+                const picked = nodes.filter((n) => group.names.includes(n.name));
+                if (!picked.length)
+                    continue;
+                if (!first)
+                    layout.contentWrite('\n');
+                first = false;
+                layout.contentWrite(`${ui.accent}${ui.bold}${t(group.key)}${ui.reset}\n`);
+                layout.contentWrite(`${slashHelpLines(picked).join('\n')}\n`);
+            }
+            const rest = nodes.filter((n) => !HELP_GROUPS.some((g) => g.names.includes(n.name)));
+            if (rest.length) {
+                if (!first)
+                    layout.contentWrite('\n');
+                layout.contentWrite(`${ui.accent}${ui.bold}${t('help.groupOther')}${ui.reset}\n`);
+                layout.contentWrite(`${slashHelpLines(rest).join('\n')}\n`);
+            }
             continue;
         }
         if (line === '/language' || line.startsWith('/language ')) {
@@ -1217,6 +1362,7 @@ export async function startRepl(initialHistory, sessionId, sandboxRootOverride,
         if (line === '/init') {
             // /init:把 init 指令当 user 输入发给 agent(扫描项目 + 生成 AGENTS.md),fall through 走 runAgent
             joined = buildInitPrompt();
+            forwardToAgent = true; // 不是"没匹配上",别被下方未知命令兜底拦掉
         }
         if (line === '/upgrade' || line.startsWith('/upgrade ')) {
             const arg = line === '/upgrade' ? '' : line.slice('/upgrade '.length).trim().toLowerCase();
@@ -1317,6 +1463,12 @@ export async function startRepl(initialHistory, sessionId, sandboxRootOverride,
             }
             continue;
         }
+        if (line === '/mode') {
+            // /mode:菜单里的分支节点(本身不切换,只挂 /plan 与 /auto)。/help 会把它列出来,
+            // 所以直接敲它必须给点有用的东西——打印当前模式与两个子命令,而不是报未知命令。
+            layout.contentWrite(`${ui.dim}${t('repl.modeCurrent', { mode: getAgentMode() })}${ui.reset}\n`);
+            continue;
+        }
         if (line === '/pet quit') {
             // /pet quit:完全关闭桌宠进程(区别于 /pet 的仅断开本连接)。方案C的 CLI 侧退出入口,
             // 另一入口是桌宠托盘菜单"退出桌宠"(见 packages/pet-app/src/main.ts)。
@@ -1382,6 +1534,7 @@ export async function startRepl(initialHistory, sessionId, sandboxRootOverride,
             layout.clearContent();
             layout.writeBanner(bannerLines(banner()));
             layout.contentWrite(`${ui.dim}${t('repl.historyCleared')}${ui.reset}\n`);
+            layout.writeWelcomeBlock(welcomeLines()); // 回到空会话状态,欢迎引导重新出现
             continue;
         }
         // /image:附加本地图片到下一条 user 消息(支持 /image <path> · /image list · /image clear)。
@@ -2293,6 +2446,19 @@ export async function startRepl(initialHistory, sessionId, sandboxRootOverride,
             }
             continue;
         }
+        // 未知斜杠命令兜底:命令分派是一串独立的 if(…){ …continue },没有 else,
+        // 拼错的 /hepl 会一路走到这里被当成普通 prompt 送给模型——白烧一轮还拿不到任何提示。
+        // 只拦「长得像命令」的输入:单个前导 / + 词字符。像 /tmp/foo/bar、/src/index.ts:12:5 这类
+        // 路径(在编码 agent 里很常见,且同样以 / 开头)必须放行,不能当成拼错的命令。
+        if (isCommandShape(cmd) && !forwardToAgent) {
+            const suggestion = suggestCommand(cmd);
+            layout.contentWrite(`${ui.yellow}${t('repl.unknownCommand', { value: cmd })}${ui.reset}\n`);
+            if (suggestion) {
+                layout.contentWrite(`${ui.dim}${t('repl.didYouMean', { value: suggestion })}${ui.reset}\n`);
+            }
+            layout.contentWrite(`${ui.dim}${t('repl.unknownCommandHint')}${ui.reset}\n`);
+            continue; // 与其他命令一致:回 INPUT 态由循环顶部的 normalizeInputBoundary + enterInputMode 负责
+        }
         const bubbleRows = input.length + 2 + pendingAttachments.length; // N 行 message + 2 行尾随空(含 \n\n 留下的 open current 行) + 每附件 1 行
         const shouldCommit = await awaitPendingRecall(input, pendingAttachments.length, placeholder);
         if (!shouldCommit) {

package/dist/ui/intervention.js

@@ -33,7 +33,10 @@ export async function promptIntervention(req) {
     const startMode = req.type === 'choice' && options.length > 0 ? 'choice' : 'input';
     let mode = startMode;
     // choice:选中下标(0..options.length-1 为各选项,options.length 为"自定义"项)。
-    let selected = 0;
+    // 初始选中项:默认 0(首项);调用方可传 defaultIndex 改。危险操作用它把默认落在「拒绝」上,
+    // 否则面板一弹出就高亮「允许一次」,用户顺手回车就把 rm -rf 放出去了。只认真实选项,不含"自定义"项。
+    const defaultIndex = Math.max(0, Math.min(req.defaultIndex ?? 0, Math.max(0, options.length - 1)));
+    let selected = defaultIndex;
     // input:可编辑文本 + 光标(UTF-16 码元索引;显示位置由 displayWidth 算,见 paintInput)。
     let text = req.seed ?? '';
     let cursor = text.length;

package/dist/ui/layout.js

@@ -552,6 +552,9 @@ export function clearContent() {
     // /theme、/clear、/resume 等命令 clearContent 后紧接 writeBanner 的场景均依赖此重置。
     bannerH = 0;
     bannerRows = [];
+    // 欢迎引导块随 buffer 一起清掉(/clear / /resume 等路径),状态复位后可由 repl 重新写入。
+    welcomeStart = -1;
+    welcomeRows = 0;
     // 清内容区必须同时作废旧菜单擦除坐标:picker(/resume /rollback /theme)把菜单画在内容区底部,
     // 菜单行号缓存在 lastMenuStartRow/lastMenuRows;若不清零,后续 paintInput 会按旧坐标“擦菜单”,
     // 把刚 renderHistory/contentWrite 写好的内容(如“已续接会话”提示)清掉,导致用户要滚动一下才刷新。
@@ -585,6 +588,39 @@ export function rewindContent(rowsToRewind) {
     // repaintViewport 会按新 buffer 重画整片,旧 frame 自然被覆盖。
     repaintViewport();
 }
+// ── 欢迎引导块(新会话开场)──
+// 开场写在内容区(banner 之下),教用户怎么开始;首次提交任何输入(消息或斜杠命令)前
+// 由 dismissWelcomeBlock 整块从 buffer 撤掉——「一打开就能看见,开始干活就消失」。
+let welcomeStart = -1; // 块起点(content.committedRows 口径的绝对行索引)
+let welcomeRows = 0; // 块行数(0 = 屏上无欢迎块)
+/** 写欢迎引导块(每行自洽带色、行宽须 ≤ cols,contentWrite 状态机兜底折行);已在屏上则跳过。 */
+export function writeWelcomeBlock(lines) {
+    if (!active || !ui.isTTY || lines.length === 0)
+        return;
+    if (welcomeRows > 0)
+        return; // 已在屏上,不重复写
+    welcomeStart = content.committedRows();
+    contentWrite(lines.join('\n') + '\n');
+    welcomeRows = content.committedRows() - welcomeStart;
+}
+/** 撤掉欢迎引导块:删 buffer 区间(若已被外部清空/裁掉则只复位状态)+ 续写位前移 + 钳位重画。 */
+export function dismissWelcomeBlock() {
+    if (welcomeRows <= 0)
+        return;
+    const start = welcomeStart;
+    const n = welcomeRows;
+    welcomeRows = 0;
+    welcomeStart = -1;
+    if (start < 0 || start >= content.committedRows())
+        return; // 块已被 clear/trim,无需删
+    content.deleteFrom(start, n);
+    const g = getGeo();
+    contentRow = Math.max(g.contentTop, contentRow - n);
+    contentCol = 1;
+    const maxOff = Math.max(0, content.totalRows() - g.contentBottom);
+    scrollOffset = Math.min(scrollOffset, maxOff);
+    repaintViewport();
+}
 /**
  * 在绝对行索引 after 后插入自洽行(详情展开用)。
  * 滚动回看冻结:scrollOffset>0 时 offset += delta 把窗口冻在原绝对行,
@@ -873,6 +909,13 @@ export function scrollBy(delta) {
     repaintViewport();
     repaint();
 }
+/**
+ * 滚动一格「滚轮量」(WHEEL_LINES 行):dir=+1 看更旧(等同 ↑ / PgUp),dir=-1 看更新(等同 ↓ / PgDn)。
+ * 鼠标滚轮与键盘裸 ↑/↓ 共用同一入口,保证两者行为与步长恒一致。
+ */
+export function scrollWheel(dir) {
+    scrollBy(dir > 0 ? WHEEL_LINES : -WHEEL_LINES);
+}
 /** 清活跃选区(不复制),若原有选区则重画去掉反白。供 ESC / 点击别处 / 退出滚动态等场景调。 */
 export function clearSelection() {
     if (!selection && !inputSelection)
@@ -1153,7 +1196,7 @@ function handleMouseEvent(e) {
     if (e.type === 'wheel') {
         // 滚轮始终可用:面板/picker 期间也允许上下查看 agent 输出,
         // 与 onRunningKey 的 PgUp/PgDn 行为一致;mouseEnabled 仅管选区/拖拽。
-        scrollBy(e.dir * WHEEL_LINES);
+        scrollWheel(e.dir);
         return;
     }
     // 输入行左键点击:即使 mouseEnabled=false(如 intervention 面板期间)也允许定位光标,
@@ -1353,6 +1396,14 @@ function composeSpinnerLine(status, cols) {
     const elapsed = (mode === 'running' && turnStart != null)
         ? fmtElapsed(Date.now() - turnStart)
         : '';
+    // 新手中断提示:每轮开始后前 6 秒,spinner 行尾随一次 dim「(Esc / Ctrl+C 中断)」,
+    // 6 秒后自然消失(不常驻,不打扰老用户)。只在非滚动回看时画,回看态右段让给历史指示。
+    const INTERRUPT_HINT_WINDOW_MS = 6000;
+    const hintActive = !scrolled && mode === 'running' && turnStart != null
+        && Date.now() - turnStart < INTERRUPT_HINT_WINDOW_MS;
+    const hintText = t('status.interruptHint');
+    const hint = hintActive ? `  ${ui.dim}(${hintText})${ui.reset}` : '';
+    const hintW = hintActive ? 4 + displayWidth(hintText) : 0; // 2 缩进 + 左右括号
     // ── 左段:帧 + 状态 + 走时,全部紧跟 ──
     let lead;
     let leadW;
@@ -1371,17 +1422,17 @@ function composeSpinnerLine(status, cols) {
         leadW = 1 + 1 + displayWidth(label) + (elapsed ? 1 + displayWidth(elapsed) : 0);
     }
     else if (hasSpinner) {
-        // spinner 激活(思考中/执行工具…):帧 + 状态 + 走时
+        // spinner 激活(思考中/执行工具…):帧 + 状态 + 走时 (+ 新手中断提示)
         const ePart = elapsed ? ` ${ui.dim}${elapsed}${ui.reset}` : '';
-        lead = `${ui.bold}${ui.accent}${status.spinnerFrame}${ui.reset} ${ui.dim}${status.status}${ui.reset}${ePart}`;
-        leadW = 1 + 1 + displayWidth(status.status) + (elapsed ? 1 + displayWidth(elapsed) : 0);
+        lead = `${ui.bold}${ui.accent}${status.spinnerFrame}${ui.reset} ${ui.dim}${status.status}${ui.reset}${ePart}${hint}`;
+        leadW = 1 + 1 + displayWidth(status.status) + (elapsed ? 1 + displayWidth(elapsed) : 0) + hintW;
     }
     else if (spinning) {
-        // 运行态心跳帧(流式输出中 / 命令态如 /rollback /compact /resume):帧 + 状态文字(优先)或生成中(兜底) + 走时
+        // 运行态心跳帧(流式输出中 / 命令态如 /rollback /compact /resume):帧 + 状态文字(优先)或生成中(兜底) + 走时 (+ 新手中断提示)
         const label = status.status || '生成中';
         const ePart = elapsed ? ` ${ui.dim}${elapsed}${ui.reset}` : '';
-        lead = `${ui.bold}${ui.accent}${RUNNING_FRAMES[runningFrame]}${ui.reset} ${ui.dim}${label}${ui.reset}${ePart}`;
-        leadW = 1 + 1 + displayWidth(label) + (elapsed ? 1 + displayWidth(elapsed) : 0);
+        lead = `${ui.bold}${ui.accent}${RUNNING_FRAMES[runningFrame]}${ui.reset} ${ui.dim}${label}${ui.reset}${ePart}${hint}`;
+        leadW = 1 + 1 + displayWidth(label) + (elapsed ? 1 + displayWidth(elapsed) : 0) + hintW;
     }
     else {
         // INPUT 态:● + 状态文字(无走时)
@@ -1882,6 +1933,12 @@ export function paintInput(view) {
         }
         else {
             text = `${prefix}${line}`;
+            // 空输入引导:INPUT 态缓冲为空时,在首行画 dim ghost 占位(「输入 / 查看命令…」);
+            // 任何按键都会改变缓冲 → 下一帧 isEmpty=false → 占位自然消失,无需额外擦除逻辑。
+            if (!line && view.placeholder && vis.startVis === 0 && i === 0) {
+                const avail = Math.max(0, preGeo.cols - promptW);
+                text = `${prefix}${ui.dim}${truncateDisplay(view.placeholder, avail)}${ui.reset}`;
+            }
             // 输入框反白叠层:仅当 paintInput 不是 dim(运行态 typeahead 不参与选区,避免干扰 IME 气泡),
             // 且该可视段所属的逻辑行落在 inpSel 区间内 → 高亮行内 [colStart,colEnd) 段。
             if (inpSel) {