mocode-ai 1.3.0 → 1.3.2

package/README.md

@@ -82,6 +82,7 @@ MoCode isn't a chat box with a coat of paint — it's an agent that actually get
 - **Project context (`AGENTS.md`)** — A single project-level memory file at `AGENTS.md` captures both static facts (project description, commands, module list, directory tree) and human/AI-written insights (conventions, architectural decisions, pitfalls). Generate it once with `/init`, then keep it up to date by hand or by asking the agent to refresh it. Loaded automatically into the system prompt on every turn.
 - **Session notepad (notes.md)** — For complex multi-step tasks (≥3 file changes / ≥5 tool calls), the agent maintains a working notepad at `.mocode/sessions/<sessionId>/notes.md` (file-based, survives context compression). It records the execution plan with the dedicated `plan_update` tool — a three-state step machine (`pending`/`in_progress`/`completed`, at most one `in_progress`) that auto-settles to `## Done:` when finished. The active plan is re-injected into the system prompt after compaction and re-synced into context whenever notes.md changes, and a gentle reminder nudges the agent if it goes several tool-steps without updating the plan. A live progress chip in the TUI status bar shows `plan: [title] (3/7) ▸ [current step]`.
 - **Interruptible and reversible** — Ctrl+C interrupts the current turn at any time (kills child processes recursively, rolls history back to before the turn started, leaves no half-finished tool calls). `/rollback` restores file changes from per-turn snapshots, with a per-file keep/undo choice — no git dependency required.
+- **Input safety net** — Long prompts no longer fear a stray Enter: `Ctrl+G` opens an in-TUI composer popup (notepad-style editing — Enter inserts a newline, with soft wrap, selection, copy/cut/paste and undo; Ctrl+S fills the text back into the input box without sending). `Ctrl+R`/`Ctrl+P` fuzzy-search your input history (Enter only fills it back), and the post-send recall window widens to 2 seconds with any-key recall for long inputs.
 - **Sandbox protection** — File reads/writes go through a sandbox that blocks out-of-bounds paths (`../../`, absolute paths outside the root, symlink escapes, etc.), so the agent never touches files outside your working directory.
 
 ## Features

package/README.zh-CN.md

@@ -81,6 +81,7 @@ mocode 不是一个套壳聊天框,而是一个能真正动手干活的 agent:
 - **跨会话长期记忆** — agent 能把项目架构、约定、踩过的坑存成长期记忆,下次会话自动加载;后台还会定期从对话里反思挖掘值得记住的事。记忆可增删改、带召回衰减。
 - **会话记事本(notes.md)** — 复杂多步任务(≥3 处文件改动 / ≥5 步工具调用)时,agent 在 `.mocode/sessions/<sessionId>/notes.md` 维护一个工作记事本(落盘抗压缩),可记录中间发现、设计决策、待验证问题和结构化计划。执行计划由专用 `plan_update` 工具维护——三态步骤机(`pending`/`in_progress`/`completed`,同一时刻至多一个 `in_progress`),全部完成自动结算为 `## Done:`。活跃 plan 在压缩后重注入系统提示、notes.md 一变就重同步进上下文,若连续多步未更新还会有温和提醒。TUI 状态栏实时显示进度 chip:`plan: [标题] (3/7) ▸ [当前步]`。
 - **可中断、可回滚** — Ctrl+C 随时打断当前轮次(树杀子进程,历史还原到本轮开始前,不留残半的工具调用);`/rollback` 按轮次快照恢复文件改动,逐个文件「保留/撤销」,不依赖 git。
+- **输入安全网** — 长 prompt 不再怕误按 Enter:`Ctrl+G` 弹出 TUI 内「输入面板」(记事本式编辑,Enter=换行、软换行、选区、复制/剪切/粘贴、撤销,Ctrl+S 填回输入框不自动发送);`Ctrl+R`/`Ctrl+P` 模糊搜索历史输入(Enter 只回填不发送);长文本误发后撤回窗口自动放宽到 2 秒且任意键可撤回。
 - **沙箱防护** — 文件读写经沙箱拦截,挡掉越界路径(`../../`、绝对外圈、软链出圈等),不碰工作目录之外的文件。
 
 ## 特性

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,29 @@ const zhCN = {
     'prompt.revertFiles': '撤销文件改动{detail}',
     'prompt.revertDetail': '（{count} 个文件恢复到回滚前）',
     'prompt.messagesOnly': '只撤销消息，保留文件改动',
+    'prompt.emptyPlaceholder': '输入消息，按 Enter 开始对话；输入 /help 查看命令…',
+    'prompt.confirmSendHint': '再按一次 Enter 发送 · 其它键继续编辑',
+    'composer.title': '输入面板',
+    'composer.pos': '{row}/{total} 行 · {col} 列 · {chars} 字',
+    'composer.hint': 'Enter 换行 · Ctrl+S 回填 · Esc 取消 · Ctrl+Z 撤销 · Ctrl+C/X/V 复制/剪切/粘贴 · Ctrl+A 全选',
+    'history.hint': '输入过滤 · ↑↓ 选择 · Enter 填入输入框 · Ctrl+Enter 直接发送 · Esc 取消',
+    'history.empty': '（无匹配的历史输入）',
+    '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': '（历史已清空，保留系统提示）',
@@ -127,7 +147,7 @@ const zhCN = {
     'repl.didYouMean': '你是不是想输入 {value}？',
     'repl.unknownCommandHint': '输入 /help 查看全部命令（普通文本直接打字发送，不必加 /）',
     'theme.default': '16 色原版（深底）',
-    'theme.light': '浅底终端',
+    'theme.light': 'Solarized 浅色系',
     'theme.solarized': 'Solarized 强调色',
     'theme.gruvbox': 'Gruvbox 暖色',
     'theme.nord': 'Nord 冷色',
@@ -154,10 +174,11 @@ const zhCN = {
     'banner.disabled': '关闭',
     'status.modeSwitch': 'Shift+Tab 切换',
     'status.history': '历史 ↑{count}（PgDn 回底）',
+    'status.interruptHint': 'Esc / Ctrl+C 中断',
     'status.measured': '实测',
     'status.estimated': '估算',
     'status.messages': '{count} 条消息',
-    'agent.sending': '发送中…  (Esc / Ctrl+C 撤回)',
+    'agent.sending': '发送中…  (任意键 / Esc / Ctrl+C 撤回)',
     'agent.thinking': '思考中',
     'agent.generating': '生成 {tool}',
     'agent.executing': '执行 {tool}',
@@ -191,6 +212,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}',
@@ -198,6 +224,7 @@ const zhCN = {
     'permission.dangerTitle': '⚠ 高风险操作: {tool}',
     'permission.confirmTitle': '确认执行: {tool}',
     'permission.dangerWarning': '⚠ 此操作可能产生不可逆副作用，请谨慎确认。',
+    'permission.firstTimeHint': '说明：面板按工具风险等级弹出。「允许」仅放行本次操作；选择会话级/项目级选项后，同类命令不再重复询问。',
     'permission.confirmExecute': '确认执行',
     'permission.allowForever': '以后不再询问此工具',
     'permission.deny': '拒绝',
@@ -318,6 +345,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',
@@ -365,13 +396,29 @@ 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…',
+    'prompt.confirmSendHint': 'Press Enter again to send · any other key keeps editing',
+    'composer.title': 'Composer',
+    'composer.pos': '{row}/{total} lines · col {col} · {chars} chars',
+    'composer.hint': 'Enter Newline · Ctrl+S Fill input · Esc Cancel · Ctrl+Z Undo · Ctrl+C/X/V Copy/Cut/Paste · Ctrl+A Select all · Shift+Arrows Select',
+    'history.hint': 'Type to filter · ↑↓ Select · Enter Fill input · Ctrl+Enter Send · Esc Cancel',
+    'history.empty': '(no matching history)',
+    '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)',
@@ -390,7 +437,7 @@ const en = {
     '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.light': 'Light Solarized palette',
     'theme.solarized': 'Solarized accents',
     'theme.gruvbox': 'Warm Gruvbox colors',
     'theme.nord': 'Cool Nord colors',
@@ -417,10 +464,11 @@ 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',
-    'agent.sending': 'Sending…  (Esc / Ctrl+C to recall)',
+    'agent.sending': 'Sending…  (any key / Esc / Ctrl+C to recall)',
     'agent.thinking': 'Thinking',
     'agent.generating': 'Generating {tool}',
     'agent.executing': 'Running {tool}',
@@ -454,6 +502,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}',
@@ -461,6 +514,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,12 +139,25 @@ 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 默认落在「拒绝」:面板一弹出就高亮"允许一次"时,用户顺手回车就把命令放出去了。

package/dist/repl/index.js

@@ -10,7 +10,7 @@ import { runAgent } from '../agent/index.js';
 import { getAgentMode, setAgentMode, onModeChange } from '../agent/mode.js';
 import { togglePet, killPetProcess, listSkins, setSkin, sendState } from '../pet/bridge.js';
 import { setSandboxRoot } from '../sandbox/root.js';
-import { ui, setTheme, getTheme, listThemes, themeExists, applyTerminalBackground } from '../ui/theme.js';
+import { ui, setTheme, getTheme, listThemes, themeExists } from '../ui/theme.js';
 import { bannerLines, displayWidth, padEndDisplay, summarizeToolCall, summarizeToolResult } from '../ui/render.js';
 import * as layout from '../ui/layout.js';
 import * as mouse from '../ui/mouse.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';
@@ -35,6 +35,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { getSandboxRoot } from '../sandbox/root.js';
 import { setCurrentSessionId, getCurrentSessionId } from '../session/state.js';
+import { collectQueryHistory } from '../session/query-history.js';
 import { checkVersion, fetchLatestVersion, getCurrentVersion, runUpgradeForeground, } from '../commands/upgrade.js';
 /**
  * readline 的 prompt 必须是纯文本(无 ANSI):readline 按字符数算光标位置,
@@ -144,6 +145,20 @@ 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 确实可用但没登记进菜单树,单独补上——否则用户照提示打了却仍被判未知。
@@ -443,7 +458,21 @@ let pendingPrefill = null; // /rollback 选中后预填的 user 输入(下轮 IN
 // 500ms 内 Ctrl+C / Esc → 整条用户气泡从内容区擦掉 + 原行 prefilled 回输入框(可改可再发);
 // 期间再按 Enter 立即推进 / 时间到自然推进 → 走原流程 enterRunningMode + runTurn。
 // attachmentsCount 记 pendingAttachments 当时长度——撤回时 attachments 保留(用户意图未变,只是改字)。
+// 短单行:500ms(不拖慢日常)。长文本:MOCODE_RECALL_MS,默认 2000ms —— 人发现"误发了"通常要 1-3 秒,
+// 500ms 根本来不及反应,只能事后 /rollback。
 const PENDING_RECALL_MS = 500;
+const PENDING_RECALL_LONG_MS = 2000;
+/** 长输入阈值:与 prompt.ts 的二次确认阈值保持一致(≥2 行 或 ≥120 码点)。 */
+const LONG_INPUT_CHARS = 120;
+/** 按输入长度决定撤回窗口:长 prompt 给更宽的补救时间,短单行仍走 500ms。 */
+function recallWindowMs(input) {
+    const joined = input.join('\n');
+    const long = input.length >= 2 || [...joined].length >= LONG_INPUT_CHARS;
+    if (!long)
+        return PENDING_RECALL_MS;
+    const env = Number(process.env.MOCODE_RECALL_MS);
+    return Number.isFinite(env) && env >= 0 ? env : PENDING_RECALL_LONG_MS;
+}
 let pendingRecall = null;
 let pendingTimer = null;
 // agent 模式状态已提到 src/agent/mode.ts(共享叶子:switch_mode 工具可写、agent 每步读、repl 注册 onModeChange 监听器)。
@@ -674,15 +703,19 @@ function awaitPendingRecall(input, attachmentsCount, placeholder) {
                 finalize(false);
                 return;
             }
-            // 立即 commit
+            // 确认立即发送:Enter / Return
             if (key.name === 'enter' || key.name === 'return') {
                 finalize(true);
                 return;
             }
-            // 其他键忽略
+            // 其它任何键 → 撤回。
+            // 旧实现把非 Enter 键"忽略"掉:误按 Enter 后人的第一反应是狂敲键盘 / 按空格 / 按退格,
+            // 这一串输入被静默丢弃,白白错过补救窗口。撤回窗口期间输入框尚未接管键盘,
+            // 这些键本来也不会进输入框,吞掉它们没有任何收益 —— 全部当作撤回信号更有用。
+            finalize(false);
         };
         emitter.on('keypress', onPendingKey);
-        pendingTimer = setTimeout(() => finalize(true), PENDING_RECALL_MS);
+        pendingTimer = setTimeout(() => finalize(true), recallWindowMs(input));
         pendingTimer.unref?.();
     });
 }
@@ -882,6 +915,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);
@@ -890,6 +943,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();
@@ -930,6 +987,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;
@@ -939,7 +1000,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。
@@ -1142,7 +1206,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 {
@@ -1188,9 +1262,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();
@@ -1218,6 +1293,9 @@ export async function startRepl(initialHistory, sessionId, sandboxRootOverride,
                 prompt: PROMPT,
                 commands: buildSlashCommands(),
                 onCycleMode: cycleMode,
+                // Ctrl+R / Ctrl+P 历史搜索候选源:惰性工厂——当前会话内存 queryHistory + 最近落盘会话,
+                // 聚合要读盘,只有面板真正打开(Ctrl+R/P)才求值,平常轮次零开销
+                history: () => collectQueryHistory(queryHistory).map((e) => e.text),
                 // /rollback 预填优先;否则上一轮运行中 typeahead 打的字 → 预填进输入框,用户可改可发
                 ...(pendingPrefill
                     ? { initialLines: pendingPrefill }
@@ -1240,6 +1318,8 @@ 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)。这类不算"未知命令"。
@@ -1251,9 +1331,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 ')) {
@@ -1457,6 +1556,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)。
@@ -1802,7 +1902,6 @@ export async function startRepl(initialHistory, sessionId, sandboxRootOverride,
             // 切:setTheme → 重算状态行(新色)→ 清内容重绘(历史 / 横幅,镜像启动 + /resume)→ 确认 → 持久化。
             // markdown MEMO 按 themeVersion 自动失效,故 renderHistory 取新色;状态栏 / 输入框由 continue 回 INPUT 态时读 getter 刷。
             setTheme(name);
-            applyTerminalBackground();
             refreshStatusBase(history);
             layout.clearContent();
             if (history.some((m) => m.role === 'user')) {

package/dist/session/query-history.js

@@ -0,0 +1,45 @@
+import { listSessions, loadSession } from './persist.js';
+/** 当前会话条目的 sessionId 标记。 */
+export const CURRENT_SESSION = 'current';
+export function collectQueryHistory(current, opts = {}) {
+    const maxSessions = Math.max(0, opts.maxSessions ?? 20);
+    const maxEntries = Math.max(1, opts.maxEntries ?? 500);
+    const seen = new Set();
+    const out = [];
+    const push = (raw, sessionId, at) => {
+        if (out.length >= maxEntries)
+            return;
+        const text = raw.trim();
+        if (!text || seen.has(text))
+            return;
+        seen.add(text);
+        out.push({ text, sessionId, at });
+    };
+    // 当前会话:数组末尾最新 → 倒序,让"刚发的"排最前。
+    for (let i = current.length - 1; i >= 0; i--)
+        push(current[i] ?? '', CURRENT_SESSION, '');
+    if (out.length < maxEntries && maxSessions > 0) {
+        // listSessions 已按 createdAt 降序(最新在前);损坏文件内部跳过。
+        for (const meta of listSessions(maxSessions)) {
+            let rec;
+            try {
+                rec = loadSession(meta.id);
+            }
+            catch {
+                continue;
+            }
+            const qh = rec?.queryHistory;
+            if (!qh?.length)
+                continue;
+            for (let i = qh.length - 1; i >= 0; i--)
+                push(qh[i] ?? '', meta.id, meta.createdAt ?? '');
+            if (out.length >= maxEntries)
+                break;
+        }
+    }
+    return out;
+}
+/** 取展示用首行(多行 query 折叠成一行;换行符显示为 ␊)。 */
+export function historyFirstLine(text) {
+    return text.split('\n')[0] ?? '';
+}