mocode-ai 1.3.0 → 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': '（历史已清空，保留系统提示）',
@@ -154,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} 条消息',
@@ -191,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}',
@@ -198,6 +218,7 @@ const zhCN = {
     'permission.dangerTitle': '⚠ 高风险操作: {tool}',
     'permission.confirmTitle': '确认执行: {tool}',
     'permission.dangerWarning': '⚠ 此操作可能产生不可逆副作用，请谨慎确认。',
+    'permission.firstTimeHint': '说明：面板按工具风险等级弹出。「允许」仅放行本次操作；选择会话级/项目级选项后，同类命令不再重复询问。',
     'permission.confirmExecute': '确认执行',
     'permission.allowForever': '以后不再询问此工具',
     'permission.deny': '拒绝',
@@ -318,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',
@@ -365,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)',
@@ -417,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',
@@ -454,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}',
@@ -461,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,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

@@ -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,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 确实可用但没登记进菜单树,单独补上——否则用户照提示打了却仍被判未知。
@@ -882,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);
@@ -890,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();
@@ -930,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;
@@ -939,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。
@@ -1142,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 {
@@ -1188,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();
@@ -1240,6 +1296,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 +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 ')) {
@@ -1457,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)。

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 把窗口冻在原绝对行,
@@ -1360,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;
@@ -1378,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 态:● + 状态文字(无走时)
@@ -1889,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) {

package/dist/ui/prompt.js

@@ -339,12 +339,16 @@ export async function promptWithSlashMenu(opts) {
     function redraw() {
         const { lines } = buildDisplay();
         const cur = cursorDisp();
+        // 空输入引导:缓冲为空时输入框内画 dim ghost 占位(含 /help 提示),让用户知道怎么开始;
+        // 一旦有输入(打字/粘贴/补全)isEmpty 变 false,下一帧占位即消失。
+        const isEmpty = segs.length === 1 && !segs[0].frozen && segs[0].text === '';
         layout.paintInput({
             prompt: opts.prompt,
             lines,
             cursorLine: cur.line,
             cursorCol: cur.col,
             menu: menuLines().length ? { lines: menuLines() } : null,
+            placeholder: isEmpty ? t('prompt.emptyPlaceholder') : undefined,
         });
     }
     /** 鼠标点击输入框:layout 已把"屏 tap 位置"以 (flatIdx, inSegVis) 形式传进来

package/package.json

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