@geminilight/mindos 0.5.17 → 0.5.19

package/app/components/settings/KnowledgeTab.tsx

@@ -1,7 +1,7 @@
 'use client';
 
-import { useState, useSyncExternalStore } from 'react';
-import { Copy, Check, RefreshCw, Trash2 } from 'lucide-react';
+import { useState, useEffect, useCallback, useSyncExternalStore } from 'react';
+import { Copy, Check, RefreshCw, Trash2, Sparkles } from 'lucide-react';
 import type { SettingsData } from './types';
 import { Field, Input, EnvBadge, SectionLabel } from './Primitives';
 import { apiFetch } from '@/lib/api';
@@ -16,6 +16,38 @@ export function KnowledgeTab({ data, setData, t }: KnowledgeTabProps) {
   const env = data.envOverrides ?? {};
   const k = t.settings.knowledge;
 
+  // Guide state toggle
+  const [guideActive, setGuideActive] = useState<boolean | null>(null);
+  const [guideDismissed, setGuideDismissed] = useState(false);
+
+  useEffect(() => {
+    fetch('/api/setup')
+      .then(r => r.json())
+      .then(d => {
+        const gs = d.guideState;
+        if (gs) {
+          setGuideActive(gs.active);
+          setGuideDismissed(!!gs.dismissed);
+        }
+      })
+      .catch(() => {});
+  }, []);
+
+  const handleGuideToggle = useCallback(() => {
+    const newDismissed = !guideDismissed;
+    setGuideDismissed(newDismissed);
+    // If re-enabling, also ensure active is true
+    const patch: Record<string, boolean> = { dismissed: newDismissed };
+    if (!newDismissed) patch.active = true;
+    fetch('/api/setup', {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ guideState: patch }),
+    })
+      .then(() => window.dispatchEvent(new Event('guide-state-updated')))
+      .catch(() => setGuideDismissed(!newDismissed)); // rollback on failure
+  }, [guideDismissed]);
+
   const origin = useSyncExternalStore(
     () => () => {},
     () => `${window.location.protocol}//${window.location.hostname}`,
@@ -158,6 +190,36 @@ export function KnowledgeTab({ data, setData, t }: KnowledgeTabProps) {
           )}
         </div>
       </Field>
+
+      {/* Getting Started Guide toggle */}
+      {guideActive !== null && (
+        <div className="border-t border-border pt-5">
+          <SectionLabel>{t.guide?.title ?? 'Getting Started'}</SectionLabel>
+          <div className="flex items-center justify-between py-2">
+            <div className="flex items-center gap-2">
+              <Sparkles size={14} style={{ color: 'var(--amber)' }} />
+              <div>
+                <div className="text-sm text-foreground">{t.guide?.showGuide ?? 'Show getting started guide'}</div>
+              </div>
+            </div>
+            <button
+              type="button"
+              role="switch"
+              aria-checked={!guideDismissed}
+              onClick={handleGuideToggle}
+              className={`relative inline-flex h-5 w-9 shrink-0 cursor-pointer rounded-full border-2 border-transparent transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring ${
+                !guideDismissed ? 'bg-amber-500' : 'bg-muted'
+              }`}
+            >
+              <span
+                className={`pointer-events-none inline-block h-4 w-4 rounded-full bg-white shadow-sm transition-transform ${
+                  !guideDismissed ? 'translate-x-4' : 'translate-x-0'
+                }`}
+              />
+            </button>
+          </div>
+        </div>
+      )}
     </div>
   );
 }

package/app/components/settings/McpTab.tsx

@@ -29,6 +29,12 @@ interface AgentInfo {
   hasProjectScope: boolean;
   hasGlobalScope: boolean;
   preferredTransport: 'stdio' | 'http';
+  // Snippet generation fields
+  format: 'json' | 'toml';
+  configKey: string;
+  globalNestedKey?: string;
+  globalPath: string;
+  projectPath?: string | null;
 }
 
 interface SkillInfo {
@@ -66,19 +72,72 @@ function CopyButton({ text, label }: { text: string; label: string }) {
   );
 }
 
+/* ── Config Snippet Generator ─────────────────────────────────── */
+
+function generateConfigSnippet(
+  agent: AgentInfo,
+  status: McpStatus,
+  token?: string,
+): { snippet: string; path: string } {
+  const isRunning = status.running;
+
+  // Determine entry (stdio vs http)
+  const stdioEntry: Record<string, unknown> = { type: 'stdio', command: 'mindos', args: ['mcp'] };
+  const httpEntry: Record<string, unknown> = { url: status.endpoint };
+  if (token) httpEntry.headers = { Authorization: `Bearer ${token}` };
+  const entry = isRunning ? httpEntry : stdioEntry;
+
+  // TOML format (Codex)
+  if (agent.format === 'toml') {
+    const lines: string[] = [`[${agent.configKey}.mindos]`];
+    if (isRunning) {
+      lines.push(`type = "http"`);
+      lines.push(`url = "${status.endpoint}"`);
+      if (token) {
+        lines.push('');
+        lines.push(`[${agent.configKey}.mindos.headers]`);
+        lines.push(`Authorization = "Bearer ${token}"`);
+      }
+    } else {
+      lines.push(`command = "mindos"`);
+      lines.push(`args = ["mcp"]`);
+      lines.push('');
+      lines.push(`[${agent.configKey}.mindos.env]`);
+      lines.push(`MCP_TRANSPORT = "stdio"`);
+    }
+    return { snippet: lines.join('\n'), path: agent.globalPath };
+  }
+
+  // JSON with globalNestedKey (VS Code project-level uses flat key)
+  if (agent.globalNestedKey) {
+    // project-level: flat key structure
+    const projectSnippet = JSON.stringify({ [agent.configKey]: { mindos: entry } }, null, 2);
+    return { snippet: projectSnippet, path: agent.projectPath ?? agent.globalPath };
+  }
+
+  // Standard JSON
+  const snippet = JSON.stringify({ [agent.configKey]: { mindos: entry } }, null, 2);
+  return { snippet, path: agent.globalPath };
+}
+
 /* ── MCP Server Status ─────────────────────────────────────────── */
 
-function ServerStatus({ status, t }: { status: McpStatus | null; t: any }) {
+function ServerStatus({ status, agents, t }: { status: McpStatus | null; agents: AgentInfo[]; t: any }) {
   const m = t.settings?.mcp;
+  const [selectedAgent, setSelectedAgent] = useState<string>('');
+
+  // Auto-select first installed or first detected agent
+  useEffect(() => {
+    if (agents.length > 0 && !selectedAgent) {
+      const first = agents.find(a => a.installed) ?? agents.find(a => a.present) ?? agents[0];
+      if (first) setSelectedAgent(first.key);
+    }
+  }, [agents, selectedAgent]);
+
   if (!status) return null;
 
-  const configSnippet = JSON.stringify({
-    mcpServers: {
-      mindos: status.running
-        ? { url: status.endpoint }
-        : { type: 'stdio', command: 'mindos', args: ['mcp'] },
-    },
-  }, null, 2);
+  const currentAgent = agents.find(a => a.key === selectedAgent);
+  const snippetResult = currentAgent ? generateConfigSnippet(currentAgent, status) : null;
 
   return (
     <div className="space-y-3">
@@ -123,8 +182,48 @@ function ServerStatus({ status, t }: { status: McpStatus | null; t: any }) {
 
       <div className="flex items-center gap-2 pl-11">
         <CopyButton text={status.endpoint} label={m?.copyEndpoint ?? 'Copy Endpoint'} />
-        <CopyButton text={configSnippet} label={m?.copyConfig ?? 'Copy Config'} />
       </div>
+
+      {/* Quick Setup — agent-specific config snippet */}
+      {agents.length > 0 && (
+        <div className="pl-11 pt-2 space-y-2.5">
+          <div className="flex items-center gap-2">
+            <span className="text-xs text-muted-foreground font-medium">
+              ── {m?.quickSetup ?? 'Quick Setup'} ──
+            </span>
+          </div>
+
+          <div className="flex items-center gap-2">
+            <span className="text-xs text-muted-foreground shrink-0">{m?.configureFor ?? 'Configure for'}</span>
+            <select
+              value={selectedAgent}
+              onChange={e => setSelectedAgent(e.target.value)}
+              className="text-xs px-2 py-1 rounded-md border border-border bg-background text-foreground outline-none focus-visible:ring-1 focus-visible:ring-ring"
+            >
+              {agents.map(a => (
+                <option key={a.key} value={a.key}>
+                  {a.name}{a.installed ? ` ✓` : a.present ? ` ·` : ''}
+                </option>
+              ))}
+            </select>
+          </div>
+
+          {snippetResult && (
+            <>
+              <div className="flex items-center gap-2">
+                <span className="text-xs text-muted-foreground shrink-0">{m?.configPath ?? 'Config path'}</span>
+                <span className="text-xs font-mono text-foreground">{snippetResult.path}</span>
+              </div>
+
+              <pre className="text-xs font-mono bg-muted/50 border border-border rounded-lg p-3 overflow-x-auto whitespace-pre">
+                {snippetResult.snippet}
+              </pre>
+
+              <CopyButton text={snippetResult.snippet} label={m?.copyConfig ?? 'Copy Config'} />
+            </>
+          )}
+        </div>
+      )}
     </div>
   );
 }
@@ -633,7 +732,7 @@ export function McpTab({ t }: McpTabProps) {
     <div className="space-y-6">
       {/* MCP Server Status — prominent card */}
       <div className="rounded-xl border p-4" style={{ borderColor: 'var(--border)', background: 'var(--card)' }}>
-        <ServerStatus status={mcpStatus} t={t} />
+        <ServerStatus status={mcpStatus} agents={agents} t={t} />
       </div>
 
       {/* Agent Install — collapsible */}

package/app/components/setup/StepAI.tsx

@@ -45,8 +45,16 @@ export default function StepAI({ state, update, s }: StepAIProps) {
             <ApiKeyInput
               value={state.provider === 'anthropic' ? state.anthropicKey : state.openaiKey}
               onChange={v => update(state.provider === 'anthropic' ? 'anthropicKey' : 'openaiKey', v)}
-              placeholder={state.provider === 'anthropic' ? 'sk-ant-...' : 'sk-...'}
+              placeholder={
+                (state.provider === 'anthropic' ? state.anthropicKeyMask : state.openaiKeyMask)
+                || (state.provider === 'anthropic' ? 'sk-ant-...' : 'sk-...')
+              }
             />
+            {(state.provider === 'anthropic' ? state.anthropicKeyMask : state.openaiKeyMask) && !(state.provider === 'anthropic' ? state.anthropicKey : state.openaiKey) && (
+              <p className="text-xs mt-1" style={{ color: 'var(--muted-foreground)' }}>
+                {s.apiKeyExisting ?? 'Existing key configured. Leave blank to keep it.'}
+              </p>
+            )}
           </Field>
           <Field label={s.model}>
             <Input

package/app/components/setup/index.tsx

@@ -129,9 +129,11 @@ export default function SetupWizard() {
     provider: 'anthropic',
     anthropicKey: '',
     anthropicModel: 'claude-sonnet-4-6',
+    anthropicKeyMask: '',
     openaiKey: '',
     openaiModel: 'gpt-5.4',
     openaiBaseUrl: '',
+    openaiKeyMask: '',
     webPort: 3000,
     mcpPort: 8787,
     authToken: '',
@@ -172,8 +174,10 @@ export default function SetupWizard() {
           webPassword: data.webPassword || prev.webPassword,
           provider: (data.provider === 'anthropic' || data.provider === 'openai') ? data.provider : prev.provider,
           anthropicModel: data.anthropicModel || prev.anthropicModel,
+          anthropicKeyMask: data.anthropicApiKey || '',
           openaiModel: data.openaiModel || prev.openaiModel,
           openaiBaseUrl: data.openaiBaseUrl ?? prev.openaiBaseUrl,
+          openaiKeyMask: data.openaiApiKey || '',
         }));
         // Generate a new token only if none exists yet
         if (!data.authToken) {

package/app/components/setup/types.ts

@@ -14,9 +14,11 @@ export interface SetupState {
   provider: 'anthropic' | 'openai' | 'skip';
   anthropicKey: string;
   anthropicModel: string;
+  anthropicKeyMask: string;   // masked existing key from server (display only)
   openaiKey: string;
   openaiModel: string;
   openaiBaseUrl: string;
+  openaiKeyMask: string;      // masked existing key from server (display only)
   webPort: number;
   mcpPort: number;
   authToken: string;

package/app/hooks/useAskModal.ts

@@ -0,0 +1,46 @@
+'use client';
+
+import { useSyncExternalStore, useCallback } from 'react';
+
+/**
+ * Lightweight pub/sub store for cross-component AskModal control.
+ * Replaces KeyboardEvent dispatch pattern with typed, testable API.
+ * No external dependencies (no zustand needed).
+ */
+
+interface AskModalState {
+  open: boolean;
+  initialMessage: string;
+  source: 'user' | 'guide' | 'guide-next';  // who triggered the open
+}
+
+let state: AskModalState = { open: false, initialMessage: '', source: 'user' };
+const listeners = new Set<() => void>();
+
+function emit() { listeners.forEach(l => l()); }
+function subscribe(listener: () => void) {
+  listeners.add(listener);
+  return () => { listeners.delete(listener); };
+}
+function getSnapshot() { return state; }
+
+export function openAskModal(message = '', source: AskModalState['source'] = 'user') {
+  state = { open: true, initialMessage: message, source };
+  emit();
+}
+
+export function closeAskModal() {
+  state = { open: false, initialMessage: '', source: 'user' };
+  emit();
+}
+
+export function useAskModal() {
+  const snap = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  return {
+    open: snap.open,
+    initialMessage: snap.initialMessage,
+    source: snap.source,
+    openWith: useCallback((message: string, source: AskModalState['source'] = 'user') => openAskModal(message, source), []),
+    close: useCallback(() => closeAskModal(), []),
+  };
+}

package/app/lib/agent/stream-consumer.ts

@@ -138,7 +138,9 @@ export async function consumeUIMessageStream(
           case 'tool-output-available': {
             const tc = toolCalls.get(chunk.toolCallId as string);
             if (tc) {
-              tc.output = typeof chunk.output === 'string' ? chunk.output : JSON.stringify(chunk.output);
+              tc.output = chunk.output != null
+                ? (typeof chunk.output === 'string' ? chunk.output : JSON.stringify(chunk.output))
+                : '';
               tc.state = 'done';
               changed = true;
             }
@@ -148,7 +150,7 @@ export async function consumeUIMessageStream(
           case 'tool-input-error': {
             const tc = toolCalls.get(chunk.toolCallId as string);
             if (tc) {
-              tc.output = (chunk.errorText as string) ?? 'Error';
+              tc.output = (chunk.errorText as string) ?? (chunk.error as string) ?? 'Tool error';
               tc.state = 'error';
               changed = true;
             }

package/app/lib/agent/tools.ts

@@ -4,6 +4,7 @@ import {
   searchFiles, getFileContent, getFileTree, getRecentlyModified,
   saveFileContent, createFile, appendToFile, insertAfterHeading, updateSection,
   deleteFile, renameFile, moveFile, findBacklinks, gitLog, gitShowFile, appendCsvRow,
+  getMindRoot,
 } from '@/lib/fs';
 import { assertNotProtected } from '@/lib/core';
 import { logAgentOp } from './log';
@@ -21,7 +22,13 @@ export function assertWritable(filePath: string): void {
   assertNotProtected(filePath, 'modified by AI agent');
 }
 
-/** Helper: wrap a tool execute fn with agent-op logging */
+/**
+ * Wrap a tool execute fn with agent-op logging.
+ * Catches ALL exceptions and returns an error string — never throws.
+ * This is critical: an unhandled throw from a tool execute function kills
+ * the AI SDK stream and corrupts the session message state, causing
+ * "Cannot read properties of undefined" on every subsequent request.
+ */
 function logged<P extends Record<string, unknown>>(
   toolName: string,
   fn: (params: P) => Promise<string>,
@@ -31,12 +38,12 @@ function logged<P extends Record<string, unknown>>(
     try {
       const result = await fn(params);
       const isError = result.startsWith('Error:');
-      logAgentOp({ ts, tool: toolName, params, result: isError ? 'error' : 'ok', message: result.slice(0, 200) });
+      try { logAgentOp({ ts, tool: toolName, params, result: isError ? 'error' : 'ok', message: result.slice(0, 200) }); } catch { /* logging must never kill the stream */ }
       return result;
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e);
-      logAgentOp({ ts, tool: toolName, params, result: 'error', message: msg.slice(0, 200) });
-      throw e;
+      try { logAgentOp({ ts, tool: toolName, params, result: 'error', message: msg.slice(0, 200) }); } catch { /* swallow — logging must never kill the stream */ }
+      return `Error: ${msg}`;
     }
   };
 }
@@ -47,12 +54,19 @@ export const knowledgeBaseTools = {
   list_files: tool({
     description: 'List files in the knowledge base as an indented tree. Directories beyond `depth` show "... (N items)". Pass `path` to list only a subdirectory, or `depth` to control how deep to expand (default 3).',
     inputSchema: z.object({
-      path: z.string().optional().describe('Optional subdirectory to list (e.g. "Projects/Products"). Omit to list everything.'),
-      depth: z.number().min(1).max(10).optional().describe('Max tree depth to expand (default 3). Directories deeper than this show item count only.'),
+      path: z.string().nullish().describe('Optional subdirectory to list (e.g. "Projects/Products"). Omit to list everything.'),
+      depth: z.number().min(1).max(10).nullish().describe('Max tree depth to expand (default 3). Directories deeper than this show item count only.'),
     }),
     execute: logged('list_files', async ({ path: subdir, depth: maxDepth }) => {
       try {
         const tree = getFileTree();
+
+        // Empty tree at root level → likely a misconfigured mindRoot
+        if (tree.length === 0 && !subdir) {
+          const root = getMindRoot();
+          return `(empty — no .md or .csv files found under mind_root: ${root})`;
+        }
+
         const limit = maxDepth ?? 3;
         const lines: string[] = [];
         function walk(nodes: Array<{ name: string; type: string; children?: unknown[] }>, depth: number) {
@@ -114,9 +128,9 @@ export const knowledgeBaseTools = {
 
   get_recent: tool({
     description: 'Get the most recently modified files in the knowledge base.',
-    inputSchema: z.object({ limit: z.number().min(1).max(50).default(10).describe('Number of files to return') }),
+    inputSchema: z.object({ limit: z.number().min(1).max(50).nullish().describe('Number of files to return (default 10)') }),
     execute: logged('get_recent', async ({ limit }) => {
-      const files = getRecentlyModified(limit);
+      const files = getRecentlyModified(limit ?? 10);
       return files.map(f => `- ${f.path} (${new Date(f.mtime).toISOString()})`).join('\n');
     }),
   }),
@@ -142,12 +156,12 @@ export const knowledgeBaseTools = {
     description: 'Create a new file. Only .md and .csv files are allowed. Parent directories are created automatically.',
     inputSchema: z.object({
       path: z.string().describe('Relative file path (must end in .md or .csv)'),
-      content: z.string().default('').describe('Initial file content'),
+      content: z.string().nullish().describe('Initial file content'),
     }),
     execute: logged('create_file', async ({ path, content }) => {
       try {
         assertWritable(path);
-        createFile(path, content);
+        createFile(path, content ?? '');
         return `File created: ${path}`;
       } catch (e: unknown) {
         return `Error: ${e instanceof Error ? e.message : String(e)}`;
@@ -283,11 +297,11 @@ export const knowledgeBaseTools = {
     description: 'Get git commit history for a file. Shows recent commits that modified this file.',
     inputSchema: z.object({
       path: z.string().describe('Relative file path'),
-      limit: z.number().min(1).max(50).default(10).describe('Number of commits to return'),
+      limit: z.number().min(1).max(50).nullish().describe('Number of commits to return (default 10)'),
     }),
     execute: logged('get_history', async ({ path, limit }) => {
       try {
-        const commits = gitLog(path, limit);
+        const commits = gitLog(path, limit ?? 10);
         if (commits.length === 0) return `No git history found for: ${path}`;
         return commits.map(c => `- \`${c.hash.slice(0, 7)}\` ${c.date} — ${c.message} (${c.author})`).join('\n');
       } catch (e: unknown) {

package/app/lib/fs.ts

@@ -59,7 +59,15 @@ function ensureCache(): FileTreeCache {
   if (isCacheValid()) return _cache!;
   const root = getMindRoot();
   const tree = buildFileTree(root);
-  const allFiles = buildAllFiles(root);
+  // Extract all file paths from the tree to avoid a second full traversal.
+  const allFiles: string[] = [];
+  function collect(nodes: FileNode[]) {
+    for (const n of nodes) {
+      if (n.type === 'file') allFiles.push(n.path);
+      else if (n.children) collect(n.children);
+    }
+  }
+  collect(tree);
   _cache = { tree, allFiles, timestamp: Date.now() };
   return _cache;
 }

package/app/lib/i18n.ts

@@ -253,6 +253,9 @@ export const messages = {
         skillLangZh: '中文',
         selectDetected: 'Select Detected',
         clearSelection: 'Clear',
+        quickSetup: 'Quick Setup',
+        configureFor: 'Configure for',
+        configPath: 'Config path',
       },
       save: 'Save',
       saved: 'Saved',
@@ -320,6 +323,7 @@ export const messages = {
       aiProviderHint: 'Choose your preferred AI service.',
       aiSkip: 'Skip — configure later',
       apiKey: 'API Key',
+      apiKeyExisting: 'Existing key configured. Leave blank to keep it.',
       model: 'Model',
       baseUrl: 'Base URL',
       baseUrlHint: 'Optional. For proxies or OpenAI-compatible APIs.',
@@ -418,6 +422,55 @@ export const messages = {
       welcomeLinkAskAI: 'Ask AI',
       welcomeLinkMCP: 'MCP Settings',
     },
+    guide: {
+      title: 'Get Started with MindOS',
+      showGuide: 'Show getting started guide',
+      close: 'Close',
+      skip: 'Skip',
+      kb: {
+        title: 'Explore your knowledge base',
+        cta: 'Start',
+        fullDesc: 'Your knowledge base has 6 areas — try clicking one:',
+        dirs: {
+          profile: 'Who you are, preferences, goals',
+          notes: 'Daily capture: ideas, meetings, todos',
+          connections: 'Your network of people',
+          workflows: 'Reusable process SOPs',
+          resources: 'Structured data: product lists, tool lists',
+          projects: 'Project plans and progress',
+        },
+        instructionHint: 'Click INSTRUCTION.md to see how AI agents behave.',
+        emptyDesc: 'Your knowledge base has 3 core files:',
+        emptyFiles: {
+          instruction: 'INSTRUCTION.md — Rules that all AI agents follow',
+          readme: 'README.md — Directory index and navigation',
+          config: 'CONFIG.json — Machine-readable preferences',
+        },
+        emptyHint: 'Create your own folder structure anytime.',
+        progress: (n: number) => `Browsed ${n}/1 file`,
+        done: 'Done',
+      },
+      ai: {
+        title: 'Chat with AI',
+        cta: 'Start',
+        prompt: 'Read my knowledge base and help me write a self-introduction into Profile.',
+        promptEmpty: 'Help me design a knowledge base folder structure that fits my needs',
+      },
+      sync: {
+        title: 'Set up sync',
+        optional: 'Optional',
+        cta: 'Configure',
+      },
+      done: {
+        title: "You're all set!",
+        titleFinal: "You've mastered MindOS essentials!",
+        steps: [
+          { hint: 'Next: try saving an article →', prompt: 'Help me save the key points from this article into MindOS.' },
+          { hint: 'Next: try using your KB in another Agent →', prompt: 'Help me start coding based on the plan in MindOS.' },
+          { hint: 'Next: try turning experience into a reusable SOP →', prompt: 'Help me distill this conversation into a reusable workflow in MindOS.' },
+        ],
+      },
+    },
   },
   zh: {
     common: {
@@ -671,6 +724,9 @@ export const messages = {
         skillLangZh: '中文',
         selectDetected: '选择已检测',
         clearSelection: '清除',
+        quickSetup: '快速配置',
+        configureFor: '配置目标',
+        configPath: '配置路径',
       },
       save: '保存',
       saved: '已保存',
@@ -738,6 +794,7 @@ export const messages = {
       aiProviderHint: '选择你偏好的 AI 服务。',
       aiSkip: '跳过 — 稍后配置',
       apiKey: 'API 密钥',
+      apiKeyExisting: '已配置密钥。留空即保持不变。',
       model: '模型',
       baseUrl: '接口地址',
       baseUrlHint: '可选。用于代理或 OpenAI 兼容 API。',
@@ -837,6 +894,55 @@ export const messages = {
       welcomeLinkAskAI: '问 AI',
       welcomeLinkMCP: 'MCP 设置',
     },
+    guide: {
+      title: '开始使用 MindOS',
+      showGuide: '显示新手引导',
+      close: '关闭',
+      skip: '跳过',
+      kb: {
+        title: '探索你的知识库',
+        cta: '开始',
+        fullDesc: '你的知识库有 6 个区域，试试点开看看：',
+        dirs: {
+          profile: '你是谁、偏好、目标',
+          notes: '日常捕捉：想法、会议、待办',
+          connections: '你的人脉关系网',
+          workflows: '可复用的工作流程 SOP',
+          resources: '结构化数据：产品库、工具库',
+          projects: '项目计划和进展',
+        },
+        instructionHint: '点击 INSTRUCTION.md 看看 AI 的行为规则。',
+        emptyDesc: '你的知识库有 3 个核心文件：',
+        emptyFiles: {
+          instruction: 'INSTRUCTION.md — 所有 AI Agent 遵循的规则',
+          readme: 'README.md — 目录索引和导航',
+          config: 'CONFIG.json — 机器可读的配置偏好',
+        },
+        emptyHint: '你可以随时创建自己的目录结构。',
+        progress: (n: number) => `已浏览 ${n}/1 个文件`,
+        done: '完成',
+      },
+      ai: {
+        title: '和 AI 对话',
+        cta: '开始',
+        prompt: '读一下我的知识库，帮我把自我介绍写进 Profile。',
+        promptEmpty: '帮我设计一个适合我的知识库目录结构',
+      },
+      sync: {
+        title: '配置同步',
+        optional: '可选',
+        cta: '设置',
+      },
+      done: {
+        title: '你已准备好使用 MindOS',
+        titleFinal: '你已掌握 MindOS 核心用法',
+        steps: [
+          { hint: '下一步：试试把一篇文章存进来 →', prompt: '帮我把这篇文章的要点整理到 MindOS 里。' },
+          { hint: '下一步：试试在另一个 Agent 里调用知识库 →', prompt: '帮我按 MindOS 里的方案开始写代码。' },
+          { hint: '下一步：试试把经验沉淀为 SOP →', prompt: '帮我把这次对话的经验沉淀到 MindOS，形成可复用的工作流。' },
+        ],
+      },
+    },
   },
 } as const;
 

package/app/lib/mcp-agents.ts

@@ -13,6 +13,10 @@ export interface AgentDef {
   global: string;
   key: string;
   preferredTransport: 'stdio' | 'http';
+  /** Config file format: 'json' (default) or 'toml'. */
+  format?: 'json' | 'toml';
+  /** For agents whose global config nests under a parent key (e.g. VS Code: mcp.servers). */
+  globalNestedKey?: string;
   /** CLI binary name for presence detection (e.g. 'claude'). Optional. */
   presenceCli?: string;
   /** Data directories for presence detection. Any one existing → present. */
@@ -174,6 +178,31 @@ export const MCP_AGENTS: Record<string, AgentDef> = {
       '~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/',
     ],
   },
+  'vscode': {
+    name: 'VS Code',
+    project: '.vscode/mcp.json',
+    global: process.platform === 'darwin'
+      ? '~/Library/Application Support/Code/User/settings.json'
+      : '~/.config/Code/User/settings.json',
+    key: 'servers',
+    globalNestedKey: 'mcp.servers',
+    preferredTransport: 'stdio',
+    presenceDirs: [
+      '~/Library/Application Support/Code/',
+      '~/.config/Code/',
+    ],
+    presenceCli: 'code',
+  },
+  'codex': {
+    name: 'Codex',
+    project: null,
+    global: '~/.codex/config.toml',
+    key: 'mcp_servers',
+    format: 'toml',
+    preferredTransport: 'stdio',
+    presenceCli: 'codex',
+    presenceDirs: ['~/.codex/'],
+  },
 };
 
 /* ── MindOS MCP Install Detection ──────────────────────────────────────── */