@wu529778790/open-im 1.9.3-beta.1 → 1.9.3-beta.11

package/dist/adapters/claude-sdk-adapter.d.ts

@@ -15,5 +15,10 @@ export declare class ClaudeSDKAdapter implements ToolAdapter {
      * 清理所有活跃的 SDK 会话和流
      */
     static destroy(): void;
+    /**
+     * Remove a specific session from the in-memory cache and close it.
+     * Useful when the caller knows a session is corrupted.
+     */
+    static removeSession(sessionId: string): void;
     run(prompt: string, sessionId: string | undefined, workDir: string, callbacks: RunCallbacks, options?: RunOptions): RunHandle;
 }

package/dist/adapters/claude-sdk-adapter.js

@@ -16,6 +16,52 @@ const log = createLogger('ClaudeSDK');
 const activeSessions = new Map();
 // 存储正在进行的流式迭代器，用于中断
 const activeStreams = new Set();
+// 空闲会话清理：跟踪最后使用时间，定期清除超时会话
+const sessionLastUsed = new Map();
+const SESSION_IDLE_TTL_MS = 30 * 60 * 1000; // 30 分钟未使用则清理
+const CLEANUP_INTERVAL_MS = 5 * 60 * 1000; // 每 5 分钟检查一次
+const cleanupInterval = setInterval(() => {
+    const now = Date.now();
+    for (const [id, lastUsed] of sessionLastUsed) {
+        if (now - lastUsed > SESSION_IDLE_TTL_MS) {
+            const session = activeSessions.get(id);
+            if (session) {
+                try {
+                    session.close();
+                }
+                catch { /* ignore */ }
+                activeSessions.delete(id);
+            }
+            sessionLastUsed.delete(id);
+            log.info(`Cleaned up idle session (unused ${Math.round((now - lastUsed) / 60000)}min): ${id}`);
+        }
+    }
+}, CLEANUP_INTERVAL_MS);
+cleanupInterval.unref(); // 不阻止进程退出
+// Lazy cleanup: check idle sessions periodically during getOrCreateSession calls
+let lazyCleanupCounter = 0;
+const LAZY_CLEANUP_INTERVAL = 10;
+let sessionSeq = 0;
+function lazyCleanupIdleSessions() {
+    lazyCleanupCounter++;
+    if (lazyCleanupCounter % LAZY_CLEANUP_INTERVAL !== 0)
+        return;
+    const now = Date.now();
+    for (const [id, lastUsed] of sessionLastUsed) {
+        if (now - lastUsed > SESSION_IDLE_TTL_MS) {
+            const s = activeSessions.get(id);
+            if (s) {
+                try {
+                    s.close();
+                }
+                catch { /* ignore */ }
+                activeSessions.delete(id);
+            }
+            sessionLastUsed.delete(id);
+            log.info(`Lazy cleanup: idle session ${id} (unused ${Math.round((now - lastUsed) / 60000)}min)`);
+        }
+    }
+}
 // Mutex to serialize process.chdir() calls across concurrent users
 let chdirMutex = Promise.resolve();
 function withChdirMutex(fn) {
@@ -44,6 +90,9 @@ function isAssistant(msg) {
 function isResult(msg) {
     return msg.type === 'result';
 }
+function isSessionCorruptionError(msg) {
+    return /session\s*(not found|expired|corrupt)|no\s*conversation\s*found/i.test(msg);
+}
 /**
  * 获取或创建 SDKSession
  * @param sessionId 已有的 sessionId，如果为 undefined 则创建新会话
@@ -53,6 +102,7 @@ function isResult(msg) {
  * @returns SDKSession 对象和实际的 sessionId
  */
 async function getOrCreateSession(sessionId, workDir, model, permissionMode) {
+    lazyCleanupIdleSessions();
     const resolvedModel = model?.trim() || 'claude-opus-4-5';
     const sessionOptions = {
         model: resolvedModel,
@@ -60,7 +110,9 @@ async function getOrCreateSession(sessionId, workDir, model, permissionMode) {
     };
     const baseUrl = process.env.ANTHROPIC_BASE_URL ?? '(default)';
     log.info(`[V2] getOrCreateSession model param=${String(model ?? '')} resolved=${resolvedModel} baseUrl=${baseUrl} workDir=${workDir}`);
-    // Use mutex to serialize process.chdir() calls across concurrent users
+    // NOTE: process.chdir() 是进程级全局副作用，在并发服务器中不理想。
+    // 但 SDK 的 createSession/resumeSession 不接受 cwd 参数，且这些调用是同步的，
+    // 所以 mutex + try/finally 已是最优方案。如果 SDK 未来支持 cwd 选项，应移除 chdir。
     return withChdirMutex(() => {
         let session;
         const originalCwd = process.cwd();
@@ -69,11 +121,19 @@ async function getOrCreateSession(sessionId, workDir, model, permissionMode) {
                 process.chdir(workDir);
             }
             if (sessionId) {
-                // 尝试恢复已有会话
+                // 优先复用内存中已有的 SDKSession，避免每次都启动新进程
+                const existing = activeSessions.get(sessionId);
+                if (existing) {
+                    log.info(`Reusing existing in-memory session: ${sessionId}`);
+                    sessionLastUsed.set(sessionId, Date.now());
+                    return { session: existing, sessionId };
+                }
+                // 内存中没有，尝试通过 resume 恢复（会启动新 CLI 进程）
                 try {
                     log.info(`Attempting to resume session: ${sessionId}`);
                     session = unstable_v2_resumeSession(sessionId, sessionOptions);
                     activeSessions.set(sessionId, session);
+                    sessionLastUsed.set(sessionId, Date.now());
                     log.info(`Successfully resumed session: ${sessionId}`);
                     return { session, sessionId };
                 }
@@ -86,8 +146,9 @@ async function getOrCreateSession(sessionId, workDir, model, permissionMode) {
             session = unstable_v2_createSession(sessionOptions);
             // 新会话的 sessionId 需要从第一个消息中获取
             // 暂时返回 undefined，稍后在 init 消息中获取
-            const tempId = `pending-${Date.now()}`;
+            const tempId = `pending-${++sessionSeq}`;
             activeSessions.set(tempId, session);
+            sessionLastUsed.set(tempId, Date.now());
             log.info(`Created new session (tempId: ${tempId})`);
             return { session, sessionId: tempId };
         }
@@ -104,6 +165,7 @@ export class ClaudeSDKAdapter {
      * 清理所有活跃的 SDK 会话和流
      */
     static destroy() {
+        clearInterval(cleanupInterval);
         for (const stream of activeStreams) {
             try {
                 if (stream && typeof stream.return === 'function') {
@@ -124,6 +186,23 @@ export class ClaudeSDKAdapter {
             }
         }
         activeSessions.clear();
+        sessionLastUsed.clear();
+    }
+    /**
+     * Remove a specific session from the in-memory cache and close it.
+     * Useful when the caller knows a session is corrupted.
+     */
+    static removeSession(sessionId) {
+        const session = activeSessions.get(sessionId);
+        if (session) {
+            try {
+                session.close();
+            }
+            catch { /* ignore */ }
+            activeSessions.delete(sessionId);
+            sessionLastUsed.delete(sessionId);
+            log.info(`Explicitly removed session: ${sessionId}`);
+        }
     }
     run(prompt, sessionId, workDir, callbacks, options) {
         log.info(`[V2] run() entry model=${String(options?.model ?? '')} baseUrl=${process.env.ANTHROPIC_BASE_URL ?? '(default)'}`);
@@ -132,6 +211,8 @@ export class ClaudeSDKAdapter {
         let actualSessionId;
         let pendingTempId; // 记录临时 ID，用于 abort 时清理
         let runSettled = false;
+        let currentStream; // 用于 abort 时立即中断 stream
+        let timeoutHandle;
         const permissionMode = options?.skipPermissions
             ? 'bypassPermissions'
             : options?.permissionMode === 'acceptEdits'
@@ -158,6 +239,7 @@ export class ClaudeSDKAdapter {
                 await session.send(prompt);
                 // 获取响应流
                 const stream = session.stream();
+                currentStream = stream;
                 activeStreams.add(stream);
                 let accumulated = '';
                 let accumulatedThinking = '';
@@ -173,10 +255,15 @@ export class ClaudeSDKAdapter {
                             const newSessionId = msg.session_id;
                             if (newSessionId && newSessionId !== actualSessionId) {
                                 // 更新 sessionId 映射
-                                if (actualSessionId && actualSessionId.startsWith('pending-')) {
-                                    activeSessions.delete(actualSessionId);
+                                // 清理 pending 临时 ID（actualSessionId 尚未赋值时用 pendingTempId）
+                                const idToClean = actualSessionId ?? pendingTempId;
+                                if (idToClean?.startsWith('pending-')) {
+                                    activeSessions.delete(idToClean);
                                 }
                                 activeSessions.set(newSessionId, session);
+                                sessionLastUsed.set(newSessionId, Date.now());
+                                if (idToClean)
+                                    sessionLastUsed.delete(idToClean);
                                 actualSessionId = newSessionId;
                                 log.info(`[V2] Got actual sessionId: ${newSessionId}`);
                                 callbacks.onSessionId?.(newSessionId);
@@ -218,10 +305,20 @@ export class ClaudeSDKAdapter {
                             log.info(`[V2] Result: subtype=${m.subtype}, num_turns=${m.num_turns}, sessionId=${actualSessionId ?? 'unknown'}`);
                             // 检查会话错误
                             if (!success) {
+                                if (timeoutHandle)
+                                    clearTimeout(timeoutHandle);
                                 runSettled = true;
                                 const noConvErr = errs.find((e) => e.includes('No conversation found') || e.includes('session not found'));
                                 if (noConvErr) {
-                                    log.warn(`Session ${actualSessionId} not found, may need to create new one`);
+                                    log.warn(`Session ${actualSessionId} not found, removing from active sessions`);
+                                    if (actualSessionId) {
+                                        activeSessions.delete(actualSessionId);
+                                        sessionLastUsed.delete(actualSessionId);
+                                        try {
+                                            session.close();
+                                        }
+                                        catch { /* ignore */ }
+                                    }
                                     callbacks.onSessionInvalid?.();
                                 }
                                 const errMsg = errs[0] || '未知错误';
@@ -246,6 +343,8 @@ export class ClaudeSDKAdapter {
                                 result.result = accumulated;
                             }
                             runSettled = true;
+                            if (timeoutHandle)
+                                clearTimeout(timeoutHandle);
                             callbacks.onComplete(result);
                             return;
                         }
@@ -254,6 +353,8 @@ export class ClaudeSDKAdapter {
                     if (!streamClosed) {
                         if (accumulated) {
                             log.info('Stream ended without result message, using accumulated text');
+                            if (timeoutHandle)
+                                clearTimeout(timeoutHandle);
                             runSettled = true;
                             callbacks.onComplete({
                                 success: true,
@@ -268,6 +369,8 @@ export class ClaudeSDKAdapter {
                         else {
                             // 流结束但无 result 也无 accumulated：必须触发回调，否则 Promise 永远挂起
                             log.warn('Stream ended with no result and no accumulated text, calling onError to prevent stuck state');
+                            if (timeoutHandle)
+                                clearTimeout(timeoutHandle);
                             runSettled = true;
                             callbacks.onError('AI 响应异常结束（无输出），请重试');
                         }
@@ -290,6 +393,8 @@ export class ClaudeSDKAdapter {
                     return;
                 }
                 runSettled = true;
+                if (timeoutHandle)
+                    clearTimeout(timeoutHandle);
                 const errorObj = err;
                 const msg = errorObj.message || String(err);
                 log.error(`Claude SDK V2 error: ${msg}`);
@@ -302,15 +407,66 @@ export class ClaudeSDKAdapter {
                     activeSessions.delete(errIdToClean);
                     log.info(`Cleaned up pending session after error: ${errIdToClean}`);
                 }
+                // If error suggests a corrupted session, remove it from cache to prevent reuse
+                if (actualSessionId && isSessionCorruptionError(msg)) {
+                    const corrupted = activeSessions.get(actualSessionId);
+                    activeSessions.delete(actualSessionId);
+                    sessionLastUsed.delete(actualSessionId);
+                    if (corrupted) {
+                        try {
+                            corrupted.close();
+                        }
+                        catch { /* ignore */ }
+                    }
+                    log.warn(`Removed corrupted session ${actualSessionId} after error: ${msg}`);
+                    callbacks.onSessionInvalid?.();
+                }
                 callbacks.onError(msg);
             }
         };
-        // 启动会话（不等待）
-        runSession();
+        // 启动会话（不等待），catch 兜底防止 unhandledRejection 导致用户请求挂起
+        runSession().catch((err) => {
+            if (!runSettled) {
+                runSettled = true;
+                if (timeoutHandle)
+                    clearTimeout(timeoutHandle);
+                const msg = err instanceof Error ? err.message : String(err);
+                log.error(`Unhandled runSession error: ${msg}`);
+                callbacks.onError(msg);
+            }
+        });
+        // 强制执行超时
+        if (options?.timeoutMs && options.timeoutMs > 0) {
+            timeoutHandle = setTimeout(() => {
+                if (!runSettled) {
+                    log.warn(`Session timed out after ${options.timeoutMs}ms, aborting`);
+                    abortController.abort();
+                    // 立即中断 stream，不等下一条消息
+                    if (currentStream) {
+                        try {
+                            currentStream.return?.();
+                        }
+                        catch { /* ignore */ }
+                    }
+                    runSettled = true;
+                    callbacks.onError(`AI 响应超时（${Math.round(options.timeoutMs / 1000)}s），请重试`);
+                }
+            }, options.timeoutMs);
+            timeoutHandle.unref();
+        }
         return {
             abort: () => {
                 log.info('Aborting session run');
                 abortController.abort();
+                if (timeoutHandle)
+                    clearTimeout(timeoutHandle);
+                // 立即中断 stream，不等下一条消息
+                if (currentStream) {
+                    try {
+                        currentStream.return?.();
+                    }
+                    catch { /* ignore */ }
+                }
             },
         };
     }

package/dist/config-web-page-i18n.d.ts

@@ -8,6 +8,7 @@ export declare const PAGE_TEXTS: {
         readonly heroKicker: "Local AI bridge";
         readonly langButton: "中文";
         readonly darkModeToggle: "Toggle dark mode";
+        readonly headerToolbarAria: "Bridge: validate, save, start, stop";
         readonly controlCenter: "Control center";
         readonly sidebarNoteTitle: "Local workflow";
         readonly sidebarNoteBody: "Configure at least one platform, save the config, then start the bridge from Service.";
@@ -40,7 +41,13 @@ export declare const PAGE_TEXTS: {
         readonly serviceIdleMeta: "Bridge has not been started yet";
         readonly listSeparator: ", ";
         readonly platformsTitle: "Platforms";
-        readonly platformsHint: "Disabled platforms keep their saved values.";
+        readonly navConfigFiles: "Config files";
+        readonly configFilesTitle: "Config files (JSON)";
+        readonly configFilesHint: "Edit the files on disk directly. Each card has its own Save. Platform / AI forms and Service → Save config still apply.";
+        readonly openImConfigCardHint: "Full open-im configuration. Use Format, then Save. Invalid JSON is rejected.";
+        readonly claudeSettingsCardHint: "Claude SDK environment (ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, ANTHROPIC_MODEL, etc.). Set API access here without shell exports.";
+        readonly claudeJsonShortcutHint: "Edit ~/.claude/settings.json in the sidebar «Config files» section below.";
+        readonly platformsHint: "Follow the setup checklist on Overview first. Disabled platforms still keep saved values.";
         readonly enabled: "Enabled";
         readonly readyState: "Ready";
         readonly setupRequired: "Setup required";
@@ -81,7 +88,7 @@ export declare const PAGE_TEXTS: {
         readonly optional: "Optional";
         readonly commaSeparatedIds: "Comma-separated IDs";
         readonly aiTitle: "AI Tooling";
-        readonly aiHint: "";
+        readonly aiHint: "Pick the default tool first. Claude SDK keys: sidebar Config files → ~/.claude/settings.json. Codex / CodeBuddy need a CLI path here.";
         readonly claudeNote: "Claude credentials are still read from environment variables or ~/.claude/settings.json. This page manages local bridge config, not Claude account auth.";
         readonly aiCommonTitle: "Shared defaults";
         readonly aiCommonHint: "Choose the default AI tool first. Tool-specific fields are shown below.";
@@ -134,6 +141,36 @@ export declare const PAGE_TEXTS: {
         readonly saveBtn: "Save";
         readonly jsonValid: "Valid JSON";
         readonly jsonInvalid: "Invalid JSON: {error}";
+        readonly wizardTitle: "First-time setup";
+        readonly wizardStep1Title: "Connect an IM channel";
+        readonly wizardStep1Desc: "Enable at least one platform below and fill every required field. Use Check config when available.";
+        readonly wizardStep2Title: "Set the default AI tool";
+        readonly wizardStep2Desc: "Claude SDK: edit ~/.claude/settings.json under sidebar Config files. Codex / CodeBuddy: set the CLI path in the AI section.";
+        readonly wizardStep3Title: "Validate and save";
+        readonly wizardStep3Desc: "Click Validate, then Save config. Fix any errors shown in the banner above.";
+        readonly wizardStep4Title: "Start the bridge";
+        readonly wizardStep4Desc: "Open Service and click Start bridge. If it exits, read ~/.open-im/logs.";
+        readonly wizardStatusDone: "Done";
+        readonly wizardStatusTodo: "To do";
+        readonly wizardJumpPlatforms: "Open Platforms";
+        readonly wizardJumpAi: "Open AI";
+        readonly wizardJumpService: "Open Service";
+        readonly validationNoPlatformEnabled: "Enable at least one IM platform and fill its required credentials before saving.";
+        readonly validationPlatformIncomplete: "Platform \"{platform}\" is enabled but these required fields are empty: {fields}";
+        readonly validationAiCodexNoCli: "Default AI is Codex but Codex CLI path is empty. Set it under AI Tooling or change the default tool.";
+        readonly validationAiCodebuddyNoCli: "Default AI is CodeBuddy but CodeBuddy CLI path is empty. Set it under AI Tooling or change the default tool.";
+        readonly onboardingTitle: "Welcome to open-im";
+        readonly onboardingDismiss: "Got it";
+        readonly onboardingReadme: "README (setup)";
+        readonly onboardingBody: "<p><strong>open-im</strong> bridges Telegram, Feishu, QQ, WeWork, DingTalk, and WorkBuddy to Claude / Codex / CodeBuddy on your machine.</p><ol style=\"margin:12px 0 12px 18px;line-height:1.65\"><li>Pick <strong>one</strong> chat app in <strong>Platforms</strong> and paste credentials (see hints under each field).</li><li>Set the <strong>default AI</strong> under AI Tooling; for Claude SDK, put API keys in sidebar <strong>Config files</strong> → <strong>~/.claude/settings.json</strong>.</li><li>Edit <strong>~/.open-im/config.json</strong> in the same <strong>Config files</strong> section when you need raw JSON.</li><li>Use <strong>Validate</strong> then <strong>Save config</strong>, then <strong>Start bridge</strong> under Service.</li><li>CLI alternative: run <code style=\"background:var(--bg-tertiary);padding:2px 6px;border-radius:4px\">open-im init</code> in a terminal.</li></ol>";
+        readonly tipTelegramToken: "From Telegram, open <a href=\"https://t.me/BotFather\" target=\"_blank\" rel=\"noopener\">@BotFather</a> → /newbot → copy the token.";
+        readonly tipFeishuAppId: "Feishu Open Platform → your app → Credentials → App ID.";
+        readonly tipFeishuSecret: "Same page → App Secret (click show / reset if needed).";
+        readonly tipQqAppId: "<a href=\"https://bot.q.qq.com\" target=\"_blank\" rel=\"noopener\">QQ bot console</a> → your bot → App ID.";
+        readonly tipQqSecret: "Same console → App Secret.";
+        readonly tipWeworkCorp: "WeCom admin → app → view Corp ID (or smart-bot Bot ID) and Secret.";
+        readonly tipDingtalkClient: "<a href=\"https://open-dev.dingtalk.com\" target=\"_blank\" rel=\"noopener\">DingTalk Open Platform</a> → internal app → App Key & App Secret.";
+        readonly tipWorkbuddyToken: "Use terminal <code>open-im init</code> for WorkBuddy OAuth, or paste tokens from CodeBuddy login.";
     };
     readonly zh: {
         readonly pageTitle: "open-im 本地控制台";
@@ -144,6 +181,7 @@ export declare const PAGE_TEXTS: {
         readonly heroKicker: "本地 AI 桥接";
         readonly langButton: "EN";
         readonly darkModeToggle: "切换暗黑模式";
+        readonly headerToolbarAria: "桥接：校验、保存、启动、停止";
         readonly controlCenter: "控制中心";
         readonly sidebarNoteTitle: "本地工作流";
         readonly sidebarNoteBody: "至少配置一个平台，保存配置，然后在服务控制区启动桥接。";
@@ -174,7 +212,13 @@ export declare const PAGE_TEXTS: {
         readonly serviceIdleMeta: "桥接服务尚未启动";
         readonly listSeparator: "、";
         readonly platformsTitle: "平台配置";
-        readonly platformsHint: "禁用的平台会保留已保存的值。";
+        readonly navConfigFiles: "配置文件";
+        readonly configFilesTitle: "配置文件（JSON）";
+        readonly configFilesHint: "直接编辑磁盘上的文件，每张卡片有独立保存按钮。平台 / AI 表单与服务区的「保存配置」仍然有效。";
+        readonly openImConfigCardHint: "open-im 完整配置。先格式化再保存；JSON 不合法时无法写入。";
+        readonly claudeSettingsCardHint: "Claude SDK 环境变量（ANTHROPIC_API_KEY、ANTHROPIC_BASE_URL、ANTHROPIC_MODEL 等）。在此配置 API，无需在终端 export。";
+        readonly claudeJsonShortcutHint: "提示：请在左侧栏「配置文件」分区编辑 ~/.claude/settings.json。";
+        readonly platformsHint: "建议先在概览页按引导步骤操作。禁用的平台仍保留已保存的值。";
         readonly enabled: "启用";
         readonly readyState: "已就绪";
         readonly setupRequired: "需要完成配置";
@@ -214,7 +258,7 @@ export declare const PAGE_TEXTS: {
         readonly optional: "可选";
         readonly commaSeparatedIds: "多个 ID 用逗号分隔";
         readonly aiTitle: "AI 工具配置";
-        readonly aiHint: "";
+        readonly aiHint: "先选默认 AI。Claude SDK：左侧栏「配置文件」→ ~/.claude/settings.json。Codex / CodeBuddy 在此填 CLI 路径。";
         readonly claudeNote: "Claude 凭证仍然从环境变量或 ~/.claude/settings.json 读取。这个页面只管理本地桥接配置，不负责 Claude 账号登录。";
         readonly aiCommonTitle: "公共默认配置";
         readonly aiCommonHint: "先选择默认 AI 工具，下方再显示对应的工具专属配置。";
@@ -264,5 +308,35 @@ export declare const PAGE_TEXTS: {
         readonly saveBtn: "保存";
         readonly jsonValid: "JSON 有效";
         readonly jsonInvalid: "JSON 无效：{error}";
+        readonly wizardTitle: "首次使用引导";
+        readonly wizardStep1Title: "接入一个 IM 渠道";
+        readonly wizardStep1Desc: "在下方启用至少一个平台，并填写所有必填项。有条件时用「校验配置」测试凭证。";
+        readonly wizardStep2Title: "设置默认 AI 工具";
+        readonly wizardStep2Desc: "Claude SDK：在左侧栏「配置文件」编辑 ~/.claude/settings.json。Codex / CodeBuddy：在 AI 区填 CLI 路径。";
+        readonly wizardStep3Title: "校验并保存";
+        readonly wizardStep3Desc: "先点「校验」，再点「保存配置」。按顶部提示修复错误。";
+        readonly wizardStep4Title: "启动桥接";
+        readonly wizardStep4Desc: "到「服务」区点「启动桥接」。若马上退出，查 ~/.open-im/logs 日志。";
+        readonly wizardStatusDone: "已完成";
+        readonly wizardStatusTodo: "待完成";
+        readonly wizardJumpPlatforms: "打开平台配置";
+        readonly wizardJumpAi: "打开 AI 配置";
+        readonly wizardJumpService: "打开服务控制";
+        readonly validationNoPlatformEnabled: "保存前请至少启用一个 IM 平台，并填完必填凭证。";
+        readonly validationPlatformIncomplete: "平台「{platform}」已启用，但以下必填项为空：{fields}";
+        readonly validationAiCodexNoCli: "默认 AI 为 Codex，但 Codex CLI 路径为空。请在 AI 区填写，或改默认工具。";
+        readonly validationAiCodebuddyNoCli: "默认 AI 为 CodeBuddy，但 CodeBuddy CLI 路径为空。请在 AI 区填写，或改默认工具。";
+        readonly onboardingTitle: "欢迎使用 open-im";
+        readonly onboardingDismiss: "知道了";
+        readonly onboardingReadme: "README（部署说明）";
+        readonly onboardingBody: "<p><strong>open-im</strong> 在本机把 Telegram、飞书、QQ、企微、钉钉、WorkBuddy 等渠道连到 Claude / Codex / CodeBuddy。</p><ol style=\"margin:12px 0 12px 18px;line-height:1.65\"><li>在<strong>平台配置</strong>选一个聊天应用，按字段下方提示填凭证。</li><li>在<strong>AI 工具配置</strong>设默认 AI；用 Claude SDK 时在左侧<strong>配置文件</strong>分区编辑<strong>~/.claude/settings.json</strong>。</li><li>同一<strong>配置文件</strong>分区可编辑<strong>~/.open-im/config.json</strong>。</li><li>先<strong>校验</strong>再<strong>保存配置</strong>，然后到<strong>服务</strong>启动桥接。</li><li>也可在终端运行 <code style=\"background:var(--bg-tertiary);padding:2px 6px;border-radius:4px\">open-im init</code> 交互配置。</li></ol>";
+        readonly tipTelegramToken: "在 Telegram 搜 <a href=\"https://t.me/BotFather\" target=\"_blank\" rel=\"noopener\">@BotFather</a>，发 /newbot 创建机器人后复制 Token。";
+        readonly tipFeishuAppId: "飞书开放平台 → 应用 → 凭证与基础信息 → App ID。";
+        readonly tipFeishuSecret: "同一页 App Secret（可重置后查看）。";
+        readonly tipQqAppId: "<a href=\"https://bot.q.qq.com\" target=\"_blank\" rel=\"noopener\">QQ 开放平台</a> → 机器人 → App ID。";
+        readonly tipQqSecret: "同一处获取 App Secret。";
+        readonly tipWeworkCorp: "企业微信管理后台 → 应用 → 查省 Corp ID / 智能机器人 Bot ID 与 Secret。";
+        readonly tipDingtalkClient: "<a href=\"https://open-dev.dingtalk.com\" target=\"_blank\" rel=\"noopener\">钉钉开放平台</a> → 企业内部应用 → AppKey / AppSecret。";
+        readonly tipWorkbuddyToken: "建议在终端运行 <code>open-im init</code> 完成 WorkBuddy 授权；或粘贴 CodeBuddy 登录后的 Token。";
     };
 };

package/dist/config-web-page-i18n.js

@@ -8,6 +8,7 @@ export const PAGE_TEXTS = {
         heroKicker: "Local AI bridge",
         langButton: "\u4e2d\u6587",
         darkModeToggle: "Toggle dark mode",
+        headerToolbarAria: "Bridge: validate, save, start, stop",
         controlCenter: "Control center",
         sidebarNoteTitle: "Local workflow",
         sidebarNoteBody: "Configure at least one platform, save the config, then start the bridge from Service.",
@@ -40,7 +41,13 @@ export const PAGE_TEXTS = {
         serviceIdleMeta: "Bridge has not been started yet",
         listSeparator: ", ",
         platformsTitle: "Platforms",
-        platformsHint: "Disabled platforms keep their saved values.",
+        navConfigFiles: "Config files",
+        configFilesTitle: "Config files (JSON)",
+        configFilesHint: "Edit the files on disk directly. Each card has its own Save. Platform / AI forms and Service → Save config still apply.",
+        openImConfigCardHint: "Full open-im configuration. Use Format, then Save. Invalid JSON is rejected.",
+        claudeSettingsCardHint: "Claude SDK environment (ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, ANTHROPIC_MODEL, etc.). Set API access here without shell exports.",
+        claudeJsonShortcutHint: "Edit ~/.claude/settings.json in the sidebar «Config files» section below.",
+        platformsHint: "Follow the setup checklist on Overview first. Disabled platforms still keep saved values.",
         enabled: "Enabled",
         readyState: "Ready",
         setupRequired: "Setup required",
@@ -81,7 +88,7 @@ export const PAGE_TEXTS = {
         optional: "Optional",
         commaSeparatedIds: "Comma-separated IDs",
         aiTitle: "AI Tooling",
-        aiHint: "",
+        aiHint: "Pick the default tool first. Claude SDK keys: sidebar Config files → ~/.claude/settings.json. Codex / CodeBuddy need a CLI path here.",
         claudeNote: "Claude credentials are still read from environment variables or ~/.claude/settings.json. This page manages local bridge config, not Claude account auth.",
         aiCommonTitle: "Shared defaults",
         aiCommonHint: "Choose the default AI tool first. Tool-specific fields are shown below.",
@@ -134,6 +141,36 @@ export const PAGE_TEXTS = {
         saveBtn: "Save",
         jsonValid: "Valid JSON",
         jsonInvalid: "Invalid JSON: {error}",
+        wizardTitle: "First-time setup",
+        wizardStep1Title: "Connect an IM channel",
+        wizardStep1Desc: "Enable at least one platform below and fill every required field. Use Check config when available.",
+        wizardStep2Title: "Set the default AI tool",
+        wizardStep2Desc: "Claude SDK: edit ~/.claude/settings.json under sidebar Config files. Codex / CodeBuddy: set the CLI path in the AI section.",
+        wizardStep3Title: "Validate and save",
+        wizardStep3Desc: "Click Validate, then Save config. Fix any errors shown in the banner above.",
+        wizardStep4Title: "Start the bridge",
+        wizardStep4Desc: "Open Service and click Start bridge. If it exits, read ~/.open-im/logs.",
+        wizardStatusDone: "Done",
+        wizardStatusTodo: "To do",
+        wizardJumpPlatforms: "Open Platforms",
+        wizardJumpAi: "Open AI",
+        wizardJumpService: "Open Service",
+        validationNoPlatformEnabled: "Enable at least one IM platform and fill its required credentials before saving.",
+        validationPlatformIncomplete: "Platform \"{platform}\" is enabled but these required fields are empty: {fields}",
+        validationAiCodexNoCli: "Default AI is Codex but Codex CLI path is empty. Set it under AI Tooling or change the default tool.",
+        validationAiCodebuddyNoCli: "Default AI is CodeBuddy but CodeBuddy CLI path is empty. Set it under AI Tooling or change the default tool.",
+        onboardingTitle: "Welcome to open-im",
+        onboardingDismiss: "Got it",
+        onboardingReadme: "README (setup)",
+        onboardingBody: "<p><strong>open-im</strong> bridges Telegram, Feishu, QQ, WeWork, DingTalk, and WorkBuddy to Claude / Codex / CodeBuddy on your machine.</p><ol style=\"margin:12px 0 12px 18px;line-height:1.65\"><li>Pick <strong>one</strong> chat app in <strong>Platforms</strong> and paste credentials (see hints under each field).</li><li>Set the <strong>default AI</strong> under AI Tooling; for Claude SDK, put API keys in sidebar <strong>Config files</strong> → <strong>~/.claude/settings.json</strong>.</li><li>Edit <strong>~/.open-im/config.json</strong> in the same <strong>Config files</strong> section when you need raw JSON.</li><li>Use <strong>Validate</strong> then <strong>Save config</strong>, then <strong>Start bridge</strong> under Service.</li><li>CLI alternative: run <code style=\"background:var(--bg-tertiary);padding:2px 6px;border-radius:4px\">open-im init</code> in a terminal.</li></ol>",
+        tipTelegramToken: 'From Telegram, open <a href="https://t.me/BotFather" target="_blank" rel="noopener">@BotFather</a> → /newbot → copy the token.',
+        tipFeishuAppId: "Feishu Open Platform → your app → Credentials → App ID.",
+        tipFeishuSecret: "Same page → App Secret (click show / reset if needed).",
+        tipQqAppId: '<a href="https://bot.q.qq.com" target="_blank" rel="noopener">QQ bot console</a> → your bot → App ID.',
+        tipQqSecret: "Same console → App Secret.",
+        tipWeworkCorp: "WeCom admin → app → view Corp ID (or smart-bot Bot ID) and Secret.",
+        tipDingtalkClient: '<a href="https://open-dev.dingtalk.com" target="_blank" rel="noopener">DingTalk Open Platform</a> → internal app → App Key & App Secret.',
+        tipWorkbuddyToken: 'Use terminal <code>open-im init</code> for WorkBuddy OAuth, or paste tokens from CodeBuddy login.',
     },
     zh: {
         pageTitle: "open-im \u672c\u5730\u63a7\u5236\u53f0",
@@ -144,6 +181,7 @@ export const PAGE_TEXTS = {
         heroKicker: "\u672c\u5730 AI \u6865\u63a5",
         langButton: "EN",
         darkModeToggle: "\u5207\u6362\u6697\u9ed1\u6a21\u5f0f",
+        headerToolbarAria: "\u6865\u63a5\uff1a\u6821\u9a8c\u3001\u4fdd\u5b58\u3001\u542f\u52a8\u3001\u505c\u6b62",
         controlCenter: "\u63a7\u5236\u4e2d\u5fc3",
         sidebarNoteTitle: "\u672c\u5730\u5de5\u4f5c\u6d41",
         sidebarNoteBody: "\u81f3\u5c11\u914d\u7f6e\u4e00\u4e2a\u5e73\u53f0\uff0c\u4fdd\u5b58\u914d\u7f6e\uff0c\u7136\u540e\u5728\u670d\u52a1\u63a7\u5236\u533a\u542f\u52a8\u6865\u63a5\u3002",
@@ -174,7 +212,13 @@ export const PAGE_TEXTS = {
         serviceIdleMeta: "\u6865\u63a5\u670d\u52a1\u5c1a\u672a\u542f\u52a8",
         listSeparator: "\u3001",
         platformsTitle: "\u5e73\u53f0\u914d\u7f6e",
-        platformsHint: "\u7981\u7528\u7684\u5e73\u53f0\u4f1a\u4fdd\u7559\u5df2\u4fdd\u5b58\u7684\u503c\u3002",
+        navConfigFiles: "\u914d\u7f6e\u6587\u4ef6",
+        configFilesTitle: "\u914d\u7f6e\u6587\u4ef6\uff08JSON\uff09",
+        configFilesHint: "\u76f4\u63a5\u7f16\u8f91\u78c1\u76d8\u4e0a\u7684\u6587\u4ef6\uff0c\u6bcf\u5f20\u5361\u7247\u6709\u72ec\u7acb\u4fdd\u5b58\u6309\u94ae\u3002\u5e73\u53f0 / AI \u8868\u5355\u4e0e\u670d\u52a1\u533a\u7684\u300c\u4fdd\u5b58\u914d\u7f6e\u300d\u4ecd\u7136\u6709\u6548\u3002",
+        openImConfigCardHint: "open-im \u5b8c\u6574\u914d\u7f6e\u3002\u5148\u683c\u5f0f\u5316\u518d\u4fdd\u5b58\uff1bJSON \u4e0d\u5408\u6cd5\u65f6\u65e0\u6cd5\u5199\u5165\u3002",
+        claudeSettingsCardHint: "Claude SDK \u73af\u5883\u53d8\u91cf\uff08ANTHROPIC_API_KEY\u3001ANTHROPIC_BASE_URL\u3001ANTHROPIC_MODEL \u7b49\uff09\u3002\u5728\u6b64\u914d\u7f6e API\uff0c\u65e0\u9700\u5728\u7ec8\u7aef export\u3002",
+        claudeJsonShortcutHint: "\u63d0\u793a\uff1a\u8bf7\u5728\u5de6\u4fa7\u680f\u300c\u914d\u7f6e\u6587\u4ef6\u300d\u5206\u533a\u7f16\u8f91 ~/.claude/settings.json\u3002",
+        platformsHint: "\u5efa\u8bae\u5148\u5728\u6982\u89c8\u9875\u6309\u5f15\u5bfc\u6b65\u9aa4\u64cd\u4f5c\u3002\u7981\u7528\u7684\u5e73\u53f0\u4ecd\u4fdd\u7559\u5df2\u4fdd\u5b58\u7684\u503c\u3002",
         enabled: "\u542f\u7528",
         readyState: "\u5df2\u5c31\u7eea",
         setupRequired: "\u9700\u8981\u5b8c\u6210\u914d\u7f6e",
@@ -214,7 +258,7 @@ export const PAGE_TEXTS = {
         optional: "\u53ef\u9009",
         commaSeparatedIds: "\u591a\u4e2a ID \u7528\u9017\u53f7\u5206\u9694",
         aiTitle: "AI \u5de5\u5177\u914d\u7f6e",
-        aiHint: "",
+        aiHint: "\u5148\u9009\u9ed8\u8ba4 AI\u3002Claude SDK\uff1a\u5de6\u4fa7\u680f\u300c\u914d\u7f6e\u6587\u4ef6\u300d\u2192 ~/.claude/settings.json\u3002Codex / CodeBuddy \u5728\u6b64\u586b CLI \u8def\u5f84\u3002",
         claudeNote: "Claude \u51ed\u8bc1\u4ecd\u7136\u4ece\u73af\u5883\u53d8\u91cf\u6216 ~/.claude/settings.json \u8bfb\u53d6\u3002\u8fd9\u4e2a\u9875\u9762\u53ea\u7ba1\u7406\u672c\u5730\u6865\u63a5\u914d\u7f6e\uff0c\u4e0d\u8d1f\u8d23 Claude \u8d26\u53f7\u767b\u5f55\u3002",
         aiCommonTitle: "\u516c\u5171\u9ed8\u8ba4\u914d\u7f6e",
         aiCommonHint: "\u5148\u9009\u62e9\u9ed8\u8ba4 AI \u5de5\u5177\uff0c\u4e0b\u65b9\u518d\u663e\u793a\u5bf9\u5e94\u7684\u5de5\u5177\u4e13\u5c5e\u914d\u7f6e\u3002",
@@ -264,5 +308,35 @@ export const PAGE_TEXTS = {
         saveBtn: "\u4fdd\u5b58",
         jsonValid: "JSON \u6709\u6548",
         jsonInvalid: "JSON \u65e0\u6548\uff1a{error}",
+        wizardTitle: "\u9996\u6b21\u4f7f\u7528\u5f15\u5bfc",
+        wizardStep1Title: "\u63a5\u5165\u4e00\u4e2a IM \u6e20\u9053",
+        wizardStep1Desc: "\u5728\u4e0b\u65b9\u542f\u7528\u81f3\u5c11\u4e00\u4e2a\u5e73\u53f0\uff0c\u5e76\u586b\u5199\u6240\u6709\u5fc5\u586b\u9879\u3002\u6709\u6761\u4ef6\u65f6\u7528\u300c\u6821\u9a8c\u914d\u7f6e\u300d\u6d4b\u8bd5\u51ed\u8bc1\u3002",
+        wizardStep2Title: "\u8bbe\u7f6e\u9ed8\u8ba4 AI \u5de5\u5177",
+        wizardStep2Desc: "Claude SDK\uff1a\u5728\u5de6\u4fa7\u680f\u300c\u914d\u7f6e\u6587\u4ef6\u300d\u7f16\u8f91 ~/.claude/settings.json\u3002Codex / CodeBuddy\uff1a\u5728 AI \u533a\u586b CLI \u8def\u5f84\u3002",
+        wizardStep3Title: "\u6821\u9a8c\u5e76\u4fdd\u5b58",
+        wizardStep3Desc: "\u5148\u70b9\u300c\u6821\u9a8c\u300d\uff0c\u518d\u70b9\u300c\u4fdd\u5b58\u914d\u7f6e\u300d\u3002\u6309\u9876\u90e8\u63d0\u793a\u4fee\u590d\u9519\u8bef\u3002",
+        wizardStep4Title: "\u542f\u52a8\u6865\u63a5",
+        wizardStep4Desc: "\u5230\u300c\u670d\u52a1\u300d\u533a\u70b9\u300c\u542f\u52a8\u6865\u63a5\u300d\u3002\u82e5\u9a6c\u4e0a\u9000\u51fa\uff0c\u67e5 ~/.open-im/logs \u65e5\u5fd7\u3002",
+        wizardStatusDone: "\u5df2\u5b8c\u6210",
+        wizardStatusTodo: "\u5f85\u5b8c\u6210",
+        wizardJumpPlatforms: "\u6253\u5f00\u5e73\u53f0\u914d\u7f6e",
+        wizardJumpAi: "\u6253\u5f00 AI \u914d\u7f6e",
+        wizardJumpService: "\u6253\u5f00\u670d\u52a1\u63a7\u5236",
+        validationNoPlatformEnabled: "\u4fdd\u5b58\u524d\u8bf7\u81f3\u5c11\u542f\u7528\u4e00\u4e2a IM \u5e73\u53f0\uff0c\u5e76\u586b\u5b8c\u5fc5\u586b\u51ed\u8bc1\u3002",
+        validationPlatformIncomplete: "\u5e73\u53f0\u300c{platform}\u300d\u5df2\u542f\u7528\uff0c\u4f46\u4ee5\u4e0b\u5fc5\u586b\u9879\u4e3a\u7a7a\uff1a{fields}",
+        validationAiCodexNoCli: "\u9ed8\u8ba4 AI \u4e3a Codex\uff0c\u4f46 Codex CLI \u8def\u5f84\u4e3a\u7a7a\u3002\u8bf7\u5728 AI \u533a\u586b\u5199\uff0c\u6216\u6539\u9ed8\u8ba4\u5de5\u5177\u3002",
+        validationAiCodebuddyNoCli: "\u9ed8\u8ba4 AI \u4e3a CodeBuddy\uff0c\u4f46 CodeBuddy CLI \u8def\u5f84\u4e3a\u7a7a\u3002\u8bf7\u5728 AI \u533a\u586b\u5199\uff0c\u6216\u6539\u9ed8\u8ba4\u5de5\u5177\u3002",
+        onboardingTitle: "\u6b22\u8fce\u4f7f\u7528 open-im",
+        onboardingDismiss: "\u77e5\u9053\u4e86",
+        onboardingReadme: "README\uff08\u90e8\u7f72\u8bf4\u660e\uff09",
+        onboardingBody: "<p><strong>open-im</strong> \u5728\u672c\u673a\u628a Telegram\u3001\u98de\u4e66\u3001QQ\u3001\u4f01\u5fae\u3001\u9489\u9489\u3001WorkBuddy \u7b49\u6e20\u9053\u8fde\u5230 Claude / Codex / CodeBuddy\u3002</p><ol style=\"margin:12px 0 12px 18px;line-height:1.65\"><li>\u5728<strong>\u5e73\u53f0\u914d\u7f6e</strong>\u9009\u4e00\u4e2a\u804a\u5929\u5e94\u7528\uff0c\u6309\u5b57\u6bb5\u4e0b\u65b9\u63d0\u793a\u586b\u51ed\u8bc1\u3002</li><li>\u5728<strong>AI \u5de5\u5177\u914d\u7f6e</strong>\u8bbe\u9ed8\u8ba4 AI\uff1b\u7528 Claude SDK \u65f6\u5728\u5de6\u4fa7<strong>\u914d\u7f6e\u6587\u4ef6</strong>\u5206\u533a\u7f16\u8f91<strong>~/.claude/settings.json</strong>\u3002</li><li>\u540c\u4e00<strong>\u914d\u7f6e\u6587\u4ef6</strong>\u5206\u533a\u53ef\u7f16\u8f91<strong>~/.open-im/config.json</strong>\u3002</li><li>\u5148<strong>\u6821\u9a8c</strong>\u518d<strong>\u4fdd\u5b58\u914d\u7f6e</strong>\uff0c\u7136\u540e\u5230<strong>\u670d\u52a1</strong>\u542f\u52a8\u6865\u63a5\u3002</li><li>\u4e5f\u53ef\u5728\u7ec8\u7aef\u8fd0\u884c <code style=\"background:var(--bg-tertiary);padding:2px 6px;border-radius:4px\">open-im init</code> \u4ea4\u4e92\u914d\u7f6e\u3002</li></ol>",
+        tipTelegramToken: '\u5728 Telegram \u641c <a href="https://t.me/BotFather" target="_blank" rel="noopener">@BotFather</a>\uff0c\u53d1 /newbot \u521b\u5efa\u673a\u5668\u4eba\u540e\u590d\u5236 Token\u3002',
+        tipFeishuAppId: "\u98de\u4e66\u5f00\u653e\u5e73\u53f0 \u2192 \u5e94\u7528 \u2192 \u51ed\u8bc1\u4e0e\u57fa\u7840\u4fe1\u606f \u2192 App ID\u3002",
+        tipFeishuSecret: "\u540c\u4e00\u9875 App Secret\uff08\u53ef\u91cd\u7f6e\u540e\u67e5\u770b\uff09\u3002",
+        tipQqAppId: '<a href="https://bot.q.qq.com" target="_blank" rel="noopener">QQ \u5f00\u653e\u5e73\u53f0</a> \u2192 \u673a\u5668\u4eba \u2192 App ID\u3002',
+        tipQqSecret: "\u540c\u4e00\u5904\u83b7\u53d6 App Secret\u3002",
+        tipWeworkCorp: "\u4f01\u4e1a\u5fae\u4fe1\u7ba1\u7406\u540e\u53f0 \u2192 \u5e94\u7528 \u2192 \u67e5\u7701 Corp ID / \u667a\u80fd\u673a\u5668\u4eba Bot ID \u4e0e Secret\u3002",
+        tipDingtalkClient: '<a href="https://open-dev.dingtalk.com" target="_blank" rel="noopener">\u9489\u9489\u5f00\u653e\u5e73\u53f0</a> \u2192 \u4f01\u4e1a\u5185\u90e8\u5e94\u7528 \u2192 AppKey / AppSecret\u3002',
+        tipWorkbuddyToken: "\u5efa\u8bae\u5728\u7ec8\u7aef\u8fd0\u884c <code>open-im init</code> \u5b8c\u6210 WorkBuddy \u6388\u6743\uff1b\u6216\u7c98\u8d34 CodeBuddy \u767b\u5f55\u540e\u7684 Token\u3002",
     }
 };