@yvhitxcel/opencode-remote 0.16.0 → 0.16.2

package/dist/core/notifications.js

@@ -101,6 +101,17 @@ export const TEMPLATES = {
         details: 'Changes were automatically rejected.',
     }),
 };
+// Task completion notification with timing
+export function formatTaskCompletion(taskName, startTime, extra) {
+    const elapsed = Date.now() - startTime;
+    const seconds = Math.floor(elapsed / 1000);
+    const timeStr = seconds >= 60 ? `${Math.floor(seconds / 60)}分${seconds % 60}秒` : `${seconds}秒`;
+    const lines = [`✅ 任务完成: ${taskName}`, '', `⏱️ 耗时: ${timeStr}`];
+    if (extra?.files && extra.files > 0) lines.push(`📄 修改文件: ${extra.files} 个`);
+    if (extra?.iterations && extra.iterations > 0) lines.push(`🔄 迭代次数: ${extra.iterations}`);
+    return lines.join('\n');
+}
+
 // Split message for Telegram's 4096 char limit
 export function splitMessage(text, maxLength = 4000) {
     if (text.length <= maxLength) {

package/dist/core/router.js

@@ -1,6 +1,18 @@
 // Message router - full command definitions shared across all platforms
 import { registry } from './registry.js';
 import { initOpenCode, listProviders, updateGlobalModel, checkConnection, resumeSession, shareSession } from '../opencode/client.js';
+import { formatTaskCompletion } from './notifications.js';
+
+const demoModeMap = new Map();
+
+export function setDemoMode(threadId, enabled) {
+    if (enabled) demoModeMap.set(threadId, true);
+    else demoModeMap.delete(threadId);
+}
+
+export function isDemoMode(threadId) {
+    return demoModeMap.has(threadId);
+}
 
 export const COMMAND_ALIASES = {
     start: ['start'],
@@ -25,6 +37,34 @@ export const COMMAND_ALIASES = {
     agents: ['agents'],
     model: ['model'],
     expert: ['expert', 'z', 'Z', 'review'],
+    tutorial: ['tutorial', 'guide', 'walkthrough'],
+    demo: ['demo', 'sandbox', 'preview'],
+};
+
+export const DEMO_RESPONSES = {
+    start: '🚀 准备就绪，发送消息给 OpenCode 开始工作\n\n💡 这是演示模式，所有命令显示模拟输出',
+    get help() { return getHelpText(); },
+    status: '✅ OpenCode 在线\n✅ 七牛云 已配置\n✅ 会话: abc12345\n📁 项目目录: /home/user/my-project',
+    reset: '🔄 会话已重置，下次发送消息将创建新会话',
+    restart: '🔄 重启信号已发送，bot 即将重启...',
+    sessions: '📂 最近会话:\n\n1. Telegram 会话 (2分钟前)\n2. 微信开发会话 (15分钟前)\n3. 专家评审 (1小时前)',
+    delsessions: '🗑️ 选择要删除的会话（回复编号）：\n\n1. Telegram 会话\n2. 微信开发会话\n\n回复编号删除',
+    loop: '🔄 循环任务已启动\n指令: 智能模式\n限制: 最多10次迭代或30分钟\n\n发送 /loop off 停止',
+    diagnose: '🔍 诊断报告\n\nOpenCode: ✅\n七牛云: ✅\nTelegram: ✅\n飞书: ❌ 未配置\n会话: ✅',
+    refresh: '✅ 会话已刷新',
+    copy: '📋 最新回复:\n\n这是 AI 的示例回复内容，演示 /copy 命令的功能。',
+    revert: '↩️ 已撤销最近的消息\n\n发送 /revert undo 恢复',
+    upload: '⬆️ 用法: /upload <文件路径>\n\n当前项目构建产物:\n📦 build/app.apk (12.5 MB)',
+    delete: '🗑️ 用法: /delete <key>\n\n示例: /delete uploads/1234567890-app.apk',
+    model: '🧠 可用模型:\n\nOpenAI (openai):\n  gpt-4o\n  gpt-4o-mini\n  o3-mini\n\nAnthropic (anthropic):\n  claude-sonnet-4-20250514\n\n用法: /model <provider/model>',
+    agents: '🤖 可用 AI Agent:\n\n✅ opencode\n✅ claude-code\n✅ codex\n❌ copilot\n\n切换: /oc /cc /cx /copilot',
+    oc: '✅ 已切换到 OpenCode\n\n💬 发送消息给 OpenCode 开始工作',
+    cc: '✅ 已切换到 Claude Code',
+    cx: '✅ 已切换到 Codex',
+    copilot: '✅ 已切换到 GitHub Copilot',
+    edit: '✏️ 用法: /edit <消息编号>\n\n选择要修改的消息，然后发送修正后的内容。',
+    expert: '🧠 专家评审模式已启动\n\n14 位 AI 专家正在分析您的项目...\n\n架构师、安全研究员、测试工程师、VC/投资人等角色将依次给出评审意见。',
+    tutorial: '📚 教程已启动\n发送 /tutorial 1 开始第1步',
 };
 
 export const EXPERT_SYSTEM_PROMPT = `你是一个专家评审系统。用户消息含触发词（z/c/叫全部专家/专家点评）时启动评审，前后可带具体问题则聚焦该问题。
@@ -134,6 +174,8 @@ const COMMAND_HELP = {
     agents: '查看 Agent',
     model: '切换模型',
     expert: '专家评审(z/叫全部专家)',
+    tutorial: '交互式教程(step-by-step 上手)',
+    demo: '沙箱模式(无需配置体验全部命令)',
 };
 
 const COMMAND_MAP = {};
@@ -249,13 +291,107 @@ async function getSessionMessages(sessionId) {
     return result.data || [];
 }
 
+export const TUTORIAL_STEPS = [
+    {
+        step: 1,
+        title: '💬 发送第一条消息',
+        desc: '直接发一条消息给 bot，比如："帮我写一个 Hello World 程序"\nAI 会自动接收并在你的电脑上执行。',
+        action: '现在试试：输入 "你好" 或 "帮我写一个 Python 程序"',
+    },
+    {
+        step: 2,
+        title: '📊 查看状态',
+        desc: '发送 /status 查看 OpenCode 是否在线、当前会话信息、运行中的任务。',
+        action: '试试：发送 /status',
+    },
+    {
+        step: 3,
+        title: '📋 复制 AI 回复',
+        desc: 'AI 回复了长篇代码？用 /copy 一键复制最新 AI 回复的内容。',
+        action: '试试：发送 /copy',
+    },
+    {
+        step: 4,
+        title: '🤖 切换 AI 模型',
+        desc: '不同模型擅长不同任务。用 /model 查看可用模型，/model provider/model 切换。',
+        action: '试试：发送 /model 查看列表',
+    },
+    {
+        step: 5,
+        title: '🧠 召唤专家评审',
+        desc: '发送 /z 启动专家评审模式，14 位 AI 专家分析你的项目，自动出修复方案并执行。',
+        action: '试试：发送 /z，然后发送 z',
+    },
+    {
+        step: 6,
+        title: '🔄 循环任务',
+        desc: '让 AI 持续工作。发送 /loop 启动循环任务，AI 会反复推进项目。\n停止：/loop off',
+        action: '试试：发送 /loop 检查测试覆盖率',
+    },
+    {
+        step: 7,
+        title: '🔍 系统诊断',
+        desc: '出问题了？/diagnose 一键检查 OpenCode、七牛云、各平台连接状态。',
+        action: '试试：发送 /diagnose',
+    },
+    {
+        step: 8,
+        title: '🎉 全部搞定',
+        desc: '你已经掌握了所有核心功能！\n下一步建议：\n• /help 查看全部 22 条命令\n• 设置你的项目目录并开始真正的开发\n• 尝试多 Agent 切换：/cc 用 Claude Code，/cx 用 Codex',
+        action: '',
+    },
+];
+
+function getTutorialText(step) {
+    const s = TUTORIAL_STEPS[step - 1];
+    if (!s) return getTutorialText(1);
+    let msg = `📚 教程 · 第 ${s.step}/${TUTORIAL_STEPS.length} 步\n━━━━━━━━━━━━━━━━\n\n${s.title}\n\n${s.desc}\n\n`;
+    if (s.action) msg += `👉 ${s.action}`;
+    msg += `\n\n回复 /tutorial${step < TUTORIAL_STEPS.length ? ` 继续第${step + 1}步\n发送 /tutorial ${step + 1}` : ''} 进入下一步`;
+    return msg;
+}
+
 export async function routeMessage(parsed, ctx) {
+    const threadId = ctx.threadId;
+    if (demoModeMap.has(threadId) && parsed.type === 'command' && DEMO_RESPONSES[parsed.command]) {
+        return DEMO_RESPONSES[parsed.command];
+    }
     switch (parsed.type) {
         case 'command': {
             switch (parsed.command) {
                 case 'help':
                     return getHelpText();
 
+                case 'tutorial': {
+                    const stepNum = parseInt(parsed.arg, 10);
+                    const step = !isNaN(stepNum) && stepNum >= 1 && stepNum <= TUTORIAL_STEPS.length ? stepNum : 1;
+                    return getTutorialText(step);
+                }
+
+                case 'demo': {
+                    const arg = (parsed.arg || '').trim().toLowerCase();
+                    if (arg === 'off' || arg === 'exit' || arg === 'stop') {
+                        setDemoMode(threadId, false);
+                        return '⏹️ 已退出沙箱模式\n\n现在所有命令将正常连接 OpenCode 执行。';
+                    }
+                    setDemoMode(threadId, true);
+                    let msg = '🎮 **沙箱模式已启动**\n\n';
+                    msg += '在此模式下，所有命令返回模拟输出，无需连接 OpenCode。\n\n';
+                    msg += '可用命令:\n';
+                    const groups = [
+                        ['🟢 常用', ['/help', '/start', '/status', '/reset']],
+                        ['🔄 任务', ['/loop', '/refresh', '/diagnose']],
+                        ['🤖 AI', ['/model', '/agents', '/oc', '/cc']],
+                        ['📂 会话', ['/sessions', '/delsessions', '/copy', '/revert']],
+                        ['⬆️ 文件', ['/upload', '/delete']],
+                    ];
+                    for (const [title, cmds] of groups) {
+                        msg += `\n${title}\n  ${cmds.join('  ')}\n`;
+                    }
+                    msg += '\n试试发送上面的命令体验效果！\n发送 /demo off 退出沙箱模式';
+                    return msg;
+                }
+
                 case 'agents': {
                     const agents = registry.listAgents();
                     const lines = ['🤖 可用 AI Agent:'];
@@ -411,8 +547,10 @@ export async function routeMessage(parsed, ctx) {
                     if (!agent) return '❌ OpenCode agent not found';
                     const available = await agent.isAvailable().catch(() => false);
                     if (!available) return '❌ OpenCode 不可用';
+                    const taskStart = Date.now();
                     const response = await agent.sendPrompt(ctx.threadId || 'expert-review', EXPERT_SYSTEM_PROMPT + '\n\n用户问题：' + (parsed.arg || '请评审当前项目'), []);
-                    return response || '无响应';
+                    const notification = response ? '' : `\n\n${formatTaskCompletion('专家评审', taskStart)}`;
+                    return (response || '无响应') + notification;
                 }
 
                 default:

package/dist/feishu/commands.js

@@ -3,7 +3,7 @@ import { splitMessage } from '../core/notifications.js';
 import { EMOJI } from '../core/types.js';
 import { initOpenCode, createSession, sendMessage, checkConnection, abortSession, resumeSession, revertSessionMessage, unrevertSession, listProviders, updateGlobalModel } from '../opencode/client.js';
 import { claimOwnership } from '../core/auth.js';
-import { COMMAND_ALIASES, detectCommand, getHelpText } from '../core/router.js';
+import { COMMAND_ALIASES, detectCommand, getHelpText, DEMO_RESPONSES, setDemoMode, isDemoMode } from '../core/router.js';
 import { registry } from '../core/registry.js';
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
 import { join, basename } from 'path';
@@ -78,6 +78,18 @@ async function handleCommand(adapter, ctx, command, arg, openCodeSessions) {
         case 'help':
             await adapter.reply(ctx.threadId, getHelpText());
             return true;
+        case 'tutorial': {
+            const { TUTORIAL_STEPS } = await import('../core/router.js');
+            const stepNum = parseInt(arg, 10);
+            const step = !isNaN(stepNum) && stepNum >= 1 && stepNum <= TUTORIAL_STEPS.length ? stepNum : 1;
+            const s = TUTORIAL_STEPS[step - 1];
+            let msg = `📚 教程 · 第 ${s.step}/${TUTORIAL_STEPS.length} 步\n━━━━━━━━━━━━━━━━\n\n${s.title}\n\n${s.desc}\n\n`;
+            if (s.action) msg += `👉 ${s.action}`;
+            msg += `\n\n回复 /tutorial${step < TUTORIAL_STEPS.length ? ` 继续第${step + 1}步` : ''} 进入下一步`;
+            const msgs = splitMessage(msg);
+            for (const m of msgs) await adapter.reply(ctx.threadId, m);
+            return true;
+        }
         case 'agents': {
             const agents = registry.listAgents();
             const lines = ['🤖 可用 AI Agent:'];
@@ -548,6 +560,21 @@ async function handleCommand(adapter, ctx, command, arg, openCodeSessions) {
 
 
 
+        case 'demo': {
+            const argText = (arg || '').trim().toLowerCase();
+            if (argText === 'off' || argText === 'exit' || argText === 'stop') {
+                setDemoMode(ctx.threadId, false);
+                await adapter.reply(ctx.threadId, '⏹️ 已退出沙箱模式');
+                return true;
+            }
+            setDemoMode(ctx.threadId, true);
+            let msg = '🎮 沙箱模式已启动\n\n在此模式下所有命令返回模拟输出，无需连接 OpenCode。\n\n';
+            msg += '试试发送: /help /status /model /agents /loop /copy\n';
+            msg += '发送 /demo off 退出';
+            await adapter.reply(ctx.threadId, msg);
+            return true;
+        }
+
         case 'diagnose': {
             const { checkConnection } = await import('../opencode/client.js');
             const diag = ['🔍 诊断报告\n'];

package/dist/opencode/client.js

@@ -398,6 +398,7 @@ export async function sendMessage(session, message, callbacks) {
         let responseText = '';
         let hasToolActivity = false;
         let idleSince = 0; // 最后一次收到新内容的时间戳
+        let lastStatus = '';
 
         while (Date.now() - startTime < TIMEOUT_MS) {
             await new Promise(r => setTimeout(r, POLL_INTERVAL));
@@ -454,6 +455,7 @@ export async function sendMessage(session, message, callbacks) {
                 if (latestStatus === 'thinking' || latestStatus === 'pending_tool') {
                     idleSince = Date.now();
                 }
+                if (latestStatus) lastStatus = latestStatus;
                 if (latestStatus && latestStatus !== lastReportedStatus) {
                     lastReportedStatus = latestStatus;
                     console.log(`[AI状态] ${latestStatus}`);

package/dist/plugins/agents/claude-code/index.js

@@ -2,6 +2,13 @@
 import { spawn } from 'child_process';
 import { platform } from 'os';
 
+const LIUV_CRASH_PATTERNS = [
+    'Assertion failed',
+    'UV_HANDLE_CLOSING',
+    'src\\win\\async.c',
+    'libuv',
+];
+
 export class ClaudeCodeAgentAdapter {
     name = 'claude-code';
     aliases = ['cc', 'claude'];
@@ -19,9 +26,7 @@ export class ClaudeCodeAgentAdapter {
         const projectDir = options.projectDir;
         const contextualPrompt = this.buildContextualPrompt(prompt, history);
 
-        // 构建命令参数
         const args = ['--print', contextualPrompt];
-        // `cwd` is set via spawn opts below, no need for --project flag
 
         return this.callClaude(args, projectDir);
     }
@@ -32,13 +37,40 @@ export class ClaudeCodeAgentAdapter {
         return `Previous:\n${historyText}\n\n${prompt}`;
     }
 
+    isCrashNoise(line) {
+        return LIUV_CRASH_PATTERNS.some(p => line.includes(p));
+    }
+
+    extractErrorMessage(stdout, stderr, code) {
+        // 先检查 stdout：--print 模式把错误也输出到 stdout
+        const stdoutLines = stdout.trim().split('\n').map(l => l.trim()).filter(Boolean);
+        const stdoutErrors = stdoutLines.filter(l => !this.isCrashNoise(l));
+        if (stdoutErrors.length > 0) {
+            return stdoutErrors.join('\n');
+        }
+
+        // 再检查 stderr
+        const stderrLines = stderr.trim().split('\n').map(l => l.trim()).filter(Boolean);
+        const stderrReal = stderrLines.filter(l => !this.isCrashNoise(l));
+        if (stderrReal.length > 0) {
+            return stderrReal.join('\n');
+        }
+
+        // 如果全是崩溃噪音，尝试从任一流中找 Error 关键词
+        const all = [...stdoutLines, ...stderrLines];
+        const firstRelevant = all.find(l => /Error|error|ERROR|^\d{3}/.test(l));
+        if (firstRelevant) return firstRelevant;
+
+        // 兜底
+        return `进程异常退出 (code: ${code})`;
+    }
+
     callClaude(args, projectDir) {
         return new Promise((resolve) => {
             const opts = {
                 stdio: ['ignore', 'pipe', 'pipe'],
                 shell: true,
             };
-            // 如果指定了项目目录，在该目录下执行
             if (projectDir) {
                 opts.cwd = projectDir;
             }
@@ -57,7 +89,17 @@ export class ClaudeCodeAgentAdapter {
             proc.on('close', (code) => {
                 clearTimeout(timeout);
                 console.log(`[claude-code] Process exited with code ${code}, stdout=${stdout.length} bytes, stderr=${stderr.length} bytes`);
-                resolve(code === 0 ? stdout.trim() : `❌ Claude Code 错误: ${stderr}`);
+
+                if (code === 0) {
+                    resolve(stdout.trim());
+                    return;
+                }
+
+                const errorMsg = this.extractErrorMessage(stdout, stderr, code);
+                console.log(`[claude-code] Process failed, raw stderr:\n${stderr.trim().slice(-1000)}`);
+                console.log(`[claude-code] Error detail:\n${errorMsg}`);
+
+                resolve(`❌ Claude Code 错误 (exit code ${code}): ${errorMsg}`);
             });
             proc.on('error', (err) => {
                 clearTimeout(timeout);

package/dist/plugins/agents/codex/index.js

@@ -2,6 +2,13 @@
 import { spawn } from 'child_process';
 import { platform } from 'os';
 
+const CRASH_PATTERNS = [
+    'Assertion failed',
+    'UV_HANDLE_CLOSING',
+    'src\\win\\async.c',
+    'libuv',
+];
+
 export class CodexAgentAdapter {
     name = 'codex';
     aliases = ['cx'];
@@ -25,6 +32,16 @@ export class CodexAgentAdapter {
         const historyText = history.map(msg => `[${msg.role}]: ${msg.content}`).join('\n\n');
         return `Context:\n${historyText}\n\n${prompt}`;
     }
+
+    extractErrorMessage(stdout, stderr) {
+        const lines = [...stdout.trim().split('\n'), ...stderr.trim().split('\n')]
+            .map(l => l.trim()).filter(Boolean)
+            .filter(l => !CRASH_PATTERNS.some(p => l.includes(p)));
+        if (lines.length > 0) return lines.join('\n');
+        const first = [...stdout.trim().split('\n'), ...stderr.trim().split('\n')]
+            .find(l => /Error|error|ERROR|^\d{3}/.test(l));
+        return first || null;
+    }
     
     callCodex(prompt) {
         return new Promise((resolve) => {
@@ -37,7 +54,12 @@ export class CodexAgentAdapter {
             proc.stdout?.on('data', (data) => { stdout += data.toString(); });
             proc.stderr?.on('data', (data) => { stderr += data.toString(); });
             proc.on('close', (code) => {
-                resolve(code === 0 ? stdout.trim() : `❌ Codex 错误: ${stderr}`);
+                if (code === 0) {
+                    resolve(stdout.trim());
+                } else {
+                    const detail = this.extractErrorMessage(stdout, stderr);
+                    resolve(`❌ Codex 错误${detail ? `: ${detail}` : ''}`);
+                }
             });
         });
     }

package/dist/plugins/agents/copilot/index.js

@@ -2,6 +2,13 @@
 import { spawn } from 'child_process';
 import { platform } from 'os';
 
+const CRASH_PATTERNS = [
+    'Assertion failed',
+    'UV_HANDLE_CLOSING',
+    'src\\win\\async.c',
+    'libuv',
+];
+
 export class CopilotAgentAdapter {
     name = 'copilot';
     aliases = ['copilot-cli', 'copilot'];
@@ -25,6 +32,16 @@ export class CopilotAgentAdapter {
         const historyText = history.map(msg => `[${msg.role}]: ${msg.content}`).join('\n\n');
         return `Context:\n${historyText}\n\n${prompt}`;
     }
+
+    extractErrorMessage(stdout, stderr) {
+        const lines = [...stdout.trim().split('\n'), ...stderr.trim().split('\n')]
+            .map(l => l.trim()).filter(Boolean)
+            .filter(l => !CRASH_PATTERNS.some(p => l.includes(p)));
+        if (lines.length > 0) return lines.join('\n');
+        const first = [...stdout.trim().split('\n'), ...stderr.trim().split('\n')]
+            .find(l => /Error|error|ERROR|^\d{3}/.test(l));
+        return first || null;
+    }
     
     callCopilot(prompt) {
         return new Promise((resolve) => {
@@ -37,7 +54,12 @@ export class CopilotAgentAdapter {
             proc.stdout?.on('data', (data) => { stdout += data.toString(); });
             proc.stderr?.on('data', (data) => { stderr += data.toString(); });
             proc.on('close', (code) => {
-                resolve(code === 0 ? stdout.trim() : `❌ Copilot 错误: ${stderr}`);
+                if (code === 0) {
+                    resolve(stdout.trim());
+                } else {
+                    const detail = this.extractErrorMessage(stdout, stderr);
+                    resolve(`❌ Copilot 错误${detail ? `: ${detail}` : ''}`);
+                }
             });
         });
     }

package/dist/plugins/agents/opencode/index.js

@@ -2,6 +2,13 @@
 import { spawn } from 'child_process';
 import { platform } from 'os';
 
+const CRASH_PATTERNS = [
+    'Assertion failed',
+    'UV_HANDLE_CLOSING',
+    'src\\win\\async.c',
+    'libuv',
+];
+
 export class OpenCodeAgentAdapter {
     name = 'opencode';
     aliases = ['oc', 'opencodeai'];
@@ -28,17 +35,28 @@ export class OpenCodeAgentAdapter {
         return `Previous conversation:\n${historyText}\n\nCurrent request: ${prompt}`;
     }
     
+    extractErrorMessage(stdout, stderr) {
+        const lines = [...stdout.trim().split('\n'), ...stderr.trim().split('\n')]
+            .map(l => l.trim()).filter(Boolean)
+            .filter(l => !CRASH_PATTERNS.some(p => l.includes(p)));
+
+        if (lines.length > 0) return lines.join('\n');
+        const first = [...stdout.trim().split('\n'), ...stderr.trim().split('\n')]
+            .find(l => /Error|error|ERROR|^\d{3}/.test(l));
+        return first || null;
+    }
+
     callOpenCode(prompt) {
         return new Promise((resolve) => {
             const proc = spawn('opencode', ['run', '--format', 'json', prompt], {
                 stdio: ['ignore', 'pipe', 'pipe'],
                 shell: true,
             });
-            
+
             let stdout = '';
             let stderr = '';
             let fullText = '';
-            
+
             proc.stdout?.on('data', (data) => {
                 stdout += data.toString();
                 const lines = stdout.split('\n');
@@ -51,12 +69,16 @@ export class OpenCodeAgentAdapter {
                     } catch {}
                 }
             });
-            
+
             proc.stderr?.on('data', (data) => { stderr += data.toString(); });
-            
+
             proc.on('close', (code) => {
                 if (code !== 0) {
-                    resolve(`❌ OpenCode 错误。请运行 \`opencode auth login\` 配置认证。`);
+                    const detail = this.extractErrorMessage(stdout, stderr);
+                    const hint = detail
+                        ? `: ${detail}`
+                        : '。请运行 `opencode auth login` 配置认证。';
+                    resolve(`❌ OpenCode 错误${hint}`);
                 } else {
                     resolve(fullText || '完成');
                 }

package/dist/telegram/adapter.js

@@ -29,10 +29,30 @@ export class TelegramAdapter {
 
     onMessage(handler) { this.messageHandler = handler; }
 
-    async sendMessage(threadId, text) {
+    async sendMessage(threadId, text, opts = {}) {
         if (!this.bot) throw new Error('Telegram adapter not started');
         const chunks = splitMessage(text, { maxLength: 4000, addContinuationMarker: false });
-        for (const chunk of chunks) await this.bot.api.sendMessage(threadId, chunk, { parse_mode: 'Markdown' });
+        for (const chunk of chunks) await this.bot.api.sendMessage(threadId, chunk, { parse_mode: 'Markdown', ...opts });
+    }
+
+    async sendCommandMenu(threadId, title) {
+        if (!this.bot) return;
+        const groups = [
+            ['🟢 常用', ['/help', '/status', '/start', '/reset']],
+            ['🔄 任务', ['/loop', '/refresh', '/restart']],
+            ['🤖 AI', ['/model', '/agents', '/oc', '/cc']],
+            ['🧠 专家', ['/tutorial', '/z', '/diagnose']],
+            ['📂 会话', ['/sessions', '/delsessions', '/copy', '/revert']],
+            ['⬆️ 文件', ['/upload', '/delete']],
+        ];
+        const keyboard = [];
+        for (const [, cmds] of groups) {
+            const row = cmds.map(cmd => ({ text: cmd, callback_data: `cmd:${cmd.slice(1)}` }));
+            keyboard.push(row);
+        }
+        await this.bot.api.sendMessage(threadId, title || '📱 选择指令：', {
+            reply_markup: { inline_keyboard: keyboard },
+        });
     }
 
     async sendTyping(threadId, isTyping) {

package/dist/telegram/bot.js

@@ -44,6 +44,15 @@ export async function startBot() {
         }
     });
 
+    telegramAdapter.bot.on('callback_query:data', async (ctx) => {
+        if (!ctx.callbackQuery.data.startsWith('cmd:')) return;
+        const cmd = ctx.callbackQuery.data.slice(4);
+        try {
+            await ctx.answerCallbackQuery({ text: `执行: /${cmd}` });
+            const msg = await telegramAdapter.bot.api.sendMessage(ctx.chat.id, `/${cmd}`);
+        } catch (e) { console.error('[Telegram] callback error:', e.message); }
+    });
+
     telegramAdapter.bot.start().catch((err) => {
         if (telegramAdapter.isRunning) console.error('[Telegram] Polling error:', err);
     });
@@ -85,6 +94,7 @@ export async function startBot() {
                 }
                 opencodeSessionId = session.sessionId;
 
+                const taskStart = Date.now();
                 const response = await sendToOpenCode(session, parsed.prompt, {
                     onTextDelta: () => {},
                     onEvent: (event) => {
@@ -101,6 +111,8 @@ export async function startBot() {
                         if (chunk.trim()) await telegramAdapter.sendMessage(message.threadId, chunk);
                     }
                 }
+                const { formatTaskCompletion } = await import('../core/notifications.js');
+                await telegramAdapter.sendMessage(message.threadId, formatTaskCompletion('AI 任务', taskStart));
                 return;
             }
 
@@ -111,7 +123,12 @@ export async function startBot() {
 
             await telegramAdapter.sendTyping(message.threadId, false);
             if (typeof result === 'string') {
-                await telegramAdapter.sendMessage(message.threadId, result);
+                if (parsed.type === 'command' && (parsed.command === 'help' || parsed.command === 'start')) {
+                    await telegramAdapter.sendMessage(message.threadId, result);
+                    await telegramAdapter.sendCommandMenu(message.threadId, '📱 快速选择指令：');
+                } else {
+                    await telegramAdapter.sendMessage(message.threadId, result);
+                }
             } else if (result) {
                 let full = '';
                 for await (const chunk of result) full += chunk;

package/dist/weixin/commands.js

@@ -1,4 +1,4 @@
-import { detectCommand, COMMAND_ALIASES, getHelpText } from '../core/router.js';
+import { detectCommand, COMMAND_ALIASES, getHelpText, DEMO_RESPONSES, setDemoMode, isDemoMode } from '../core/router.js';
 import { getOrCreateSession, saveSessionMapping, sessionManager } from '../core/session.js';
 import { splitMessage } from '../core/notifications.js';
 import { initOpenCode, checkConnection, abortSession, resumeSession, revertSessionMessage, unrevertSession, listProviders, updateGlobalModel } from '../opencode/client.js';
@@ -93,6 +93,18 @@ async function handleCommand(adapter, ctx, command, arg, openCodeSessions) {
         case 'help':
             await adapter.reply(ctx.threadId, getHelpText());
             return true;
+        case 'tutorial': {
+            const { TUTORIAL_STEPS } = await import('../core/router.js');
+            const stepNum = parseInt(arg, 10);
+            const step = !isNaN(stepNum) && stepNum >= 1 && stepNum <= TUTORIAL_STEPS.length ? stepNum : 1;
+            const s = TUTORIAL_STEPS[step - 1];
+            let msg = `📚 教程 · 第 ${s.step}/${TUTORIAL_STEPS.length} 步\n━━━━━━━━━━━━━━━━\n\n${s.title}\n\n${s.desc}\n\n`;
+            if (s.action) msg += `👉 ${s.action}`;
+            msg += `\n\n回复 /tutorial${step < TUTORIAL_STEPS.length ? ` 继续第${step + 1}步` : ''} 进入下一步`;
+            const msgs = splitMessage(msg);
+            for (const m of msgs) await adapter.reply(ctx.threadId, m);
+            return true;
+        }
                 case 'status': {
                     const connected = await checkConnection();
                     const running = session.taskStartTime ? Math.round((Date.now() - session.taskStartTime) / 1000) : 0;
@@ -698,6 +710,21 @@ async function handleCommand(adapter, ctx, command, arg, openCodeSessions) {
 
 
 
+        case 'demo': {
+            const argText = (arg || '').trim().toLowerCase();
+            if (argText === 'off' || argText === 'exit' || argText === 'stop') {
+                setDemoMode(ctx.threadId, false);
+                await adapter.reply(ctx.threadId, '⏹️ 已退出沙箱模式');
+                return true;
+            }
+            setDemoMode(ctx.threadId, true);
+            let msg = '🎮 沙箱模式已启动\n\n在此模式下所有命令返回模拟输出，无需连接 OpenCode。\n\n';
+            msg += '试试发送: /help /status /model /agents /loop /copy\n';
+            msg += '发送 /demo off 退出';
+            await adapter.reply(ctx.threadId, msg);
+            return true;
+        }
+
         case 'diagnose': {
             const { checkConnection } = await import('../opencode/client.js');
             const diag = ['🔍 诊断报告\n'];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yvhitxcel/opencode-remote",
-  "version": "0.16.0",
+  "version": "0.16.2",
   "description": "🤖 AI 专家团队随时待命！只需输入 /z，自动分析项目、诊断问题、给出改进方案。支持微信/飞书/Telegram 远程控制 OpenCode、Claude Code、Codex、Copilot。手机也能搞开发。",
   "type": "module",
   "bin": {