@geminilight/mindos 0.2.1 → 0.3.0

package/app/app/api/init/route.ts

@@ -1,56 +1,22 @@
 import { NextRequest, NextResponse } from 'next/server';
-import fs from 'fs';
-import path from 'path';
 import { getMindRoot } from '@/lib/fs';
-
-function copyRecursive(src: string, dest: string) {
-  const stat = fs.statSync(src);
-  if (stat.isDirectory()) {
-    if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
-    for (const entry of fs.readdirSync(src)) {
-      copyRecursive(path.join(src, entry), path.join(dest, entry));
-    }
-  } else {
-    // Skip if file already exists
-    if (fs.existsSync(dest)) return;
-    // Ensure parent directory exists
-    const dir = path.dirname(dest);
-    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-    fs.copyFileSync(src, dest);
-  }
-}
+import { applyTemplate } from '@/lib/template';
 
 export async function POST(req: NextRequest) {
   try {
     const body = await req.json();
     const template = body.template as string;
 
-    if (!['en', 'zh', 'empty'].includes(template)) {
-      return NextResponse.json({ error: 'Invalid template' }, { status: 400 });
-    }
-
-    // Resolve template source directory
-    // templates/ is at the repo root (sibling of app/)
-    const repoRoot = path.resolve(process.cwd(), '..');
-    const templateDir = path.join(repoRoot, 'templates', template);
-
-    if (!fs.existsSync(templateDir)) {
-      return NextResponse.json({ error: `Template "${template}" not found` }, { status: 404 });
-    }
-
     const mindRoot = getMindRoot();
-    if (!fs.existsSync(mindRoot)) {
-      fs.mkdirSync(mindRoot, { recursive: true });
-    }
-
-    copyRecursive(templateDir, mindRoot);
+    applyTemplate(template, mindRoot);
 
     return NextResponse.json({ ok: true, template });
   } catch (e) {
     console.error('[/api/init] Error:', e);
-    return NextResponse.json(
-      { error: e instanceof Error ? e.message : String(e) },
-      { status: 500 },
-    );
+    const msg = e instanceof Error ? e.message : String(e);
+    const status = msg.startsWith('Invalid template') ? 400
+      : msg.includes('not found') ? 404
+      : 500;
+    return NextResponse.json({ error: msg }, { status });
   }
 }

package/app/app/api/settings/route.ts

@@ -112,6 +112,9 @@ export async function POST(req: NextRequest) {
       mindRoot: body.mindRoot ?? current.mindRoot,
       webPassword: resolvedWebPassword,
       authToken: resolvedAuthToken,
+      port: typeof body.port === 'number' ? body.port : current.port,
+      mcpPort: typeof body.mcpPort === 'number' ? body.mcpPort : current.mcpPort,
+      startMode: body.startMode ?? current.startMode,
     };
 
     writeSettings(next);

package/app/app/api/setup/generate-token/route.ts

@@ -0,0 +1,23 @@
+export const dynamic = 'force-dynamic';
+import { NextResponse } from 'next/server';
+import { randomBytes, createHash } from 'crypto';
+
+export async function POST(req: Request) {
+  try {
+    const { seed } = await req.json().catch(() => ({} as { seed?: string }));
+    let raw: string;
+    if (seed && typeof seed === 'string' && seed.trim()) {
+      raw = createHash('sha256').update(seed.trim()).digest('hex').slice(0, 24);
+    } else {
+      raw = randomBytes(12).toString('hex'); // 24 hex chars
+    }
+    // Format as xxxx-xxxx-xxxx-xxxx-xxxx-xxxx
+    const token = raw.match(/.{4}/g)!.join('-');
+    return NextResponse.json({ token });
+  } catch (e) {
+    return NextResponse.json(
+      { error: e instanceof Error ? e.message : String(e) },
+      { status: 500 },
+    );
+  }
+}

package/app/app/api/setup/route.ts

@@ -0,0 +1,81 @@
+export const dynamic = 'force-dynamic';
+import { NextRequest, NextResponse } from 'next/server';
+import fs from 'fs';
+import os from 'os';
+import { readSettings, writeSettings, ServerSettings } from '@/lib/settings';
+import { applyTemplate } from '@/lib/template';
+
+function expandHome(p: string): string {
+  if (p.startsWith('~/')) return p.replace('~', os.homedir());
+  if (p === '~') return os.homedir();
+  return p;
+}
+
+export async function POST(req: NextRequest) {
+  try {
+    const body = await req.json();
+    const { mindRoot, template, port, mcpPort, authToken, webPassword, ai } = body;
+
+    // Validate required fields
+    if (!mindRoot || typeof mindRoot !== 'string') {
+      return NextResponse.json({ error: 'mindRoot is required' }, { status: 400 });
+    }
+
+    const resolvedRoot = expandHome(mindRoot.trim());
+
+    // Validate ports
+    const webPort = typeof port === 'number' ? port : 3000;
+    const mcpPortNum = typeof mcpPort === 'number' ? mcpPort : 8787;
+    if (webPort < 1024 || webPort > 65535) {
+      return NextResponse.json({ error: `Invalid web port: ${webPort}` }, { status: 400 });
+    }
+    if (mcpPortNum < 1024 || mcpPortNum > 65535) {
+      return NextResponse.json({ error: `Invalid MCP port: ${mcpPortNum}` }, { status: 400 });
+    }
+
+    // Apply template if mindRoot doesn't exist or is empty
+    const dirExists = fs.existsSync(resolvedRoot);
+    let dirEmpty = true;
+    if (dirExists) {
+      try {
+        const entries = fs.readdirSync(resolvedRoot).filter(e => !e.startsWith('.'));
+        dirEmpty = entries.length === 0;
+      } catch { /* treat as empty */ }
+    }
+
+    if (template && (!dirExists || dirEmpty)) {
+      applyTemplate(template, resolvedRoot);
+    } else if (!dirExists) {
+      fs.mkdirSync(resolvedRoot, { recursive: true });
+    }
+
+    // Read current running port for portChanged detection
+    const current = readSettings();
+    const currentPort = current.port ?? 3000;
+
+    // Build config
+    const config: ServerSettings = {
+      ai: ai ?? current.ai,
+      mindRoot: resolvedRoot,
+      port: webPort,
+      mcpPort: mcpPortNum,
+      authToken: authToken ?? current.authToken,
+      webPassword: webPassword ?? '',
+      startMode: current.startMode,
+      setupPending: false,  // clear the flag
+    };
+
+    writeSettings(config);
+
+    return NextResponse.json({
+      ok: true,
+      portChanged: webPort !== currentPort,
+    });
+  } catch (e) {
+    console.error('[/api/setup] Error:', e);
+    return NextResponse.json(
+      { error: e instanceof Error ? e.message : String(e) },
+      { status: 500 },
+    );
+  }
+}

package/app/app/page.tsx

@@ -1,7 +1,12 @@
+import { redirect } from 'next/navigation';
+import { readSettings } from '@/lib/settings';
 import { getRecentlyModified } from '@/lib/fs';
 import HomeContent from '@/components/HomeContent';
 
 export default function HomePage() {
+  const settings = readSettings();
+  if (settings.setupPending) redirect('/setup');
+
   let recent: { path: string; mtime: number }[] = [];
   try {
     recent = getRecentlyModified(15);

package/app/app/setup/page.tsx

@@ -0,0 +1,9 @@
+import { redirect } from 'next/navigation';
+import { readSettings } from '@/lib/settings';
+import SetupWizard from '@/components/SetupWizard';
+
+export default function SetupPage() {
+  const settings = readSettings();
+  if (!settings.setupPending) redirect('/');
+  return <SetupWizard />;
+}

package/app/components/SetupWizard.tsx

@@ -0,0 +1,479 @@
+'use client';
+
+import { useState, useEffect, useCallback } from 'react';
+import { useRouter } from 'next/navigation';
+import { Sparkles, Globe, BookOpen, FileText, Copy, Check, RefreshCw, Loader2, ChevronLeft, ChevronRight, AlertTriangle } from 'lucide-react';
+import { useLocale } from '@/lib/LocaleContext';
+import { Field, Input, Select, ApiKeyInput } from '@/components/settings/Primitives';
+
+type Template = 'en' | 'zh' | 'empty' | '';
+
+interface SetupState {
+  mindRoot: string;
+  template: Template;
+  provider: 'anthropic' | 'openai' | 'skip';
+  anthropicKey: string;
+  anthropicModel: string;
+  openaiKey: string;
+  openaiModel: string;
+  openaiBaseUrl: string;
+  webPort: number;
+  mcpPort: number;
+  authToken: string;
+  webPassword: string;
+}
+
+const TEMPLATES: Array<{
+  id: Template;
+  icon: React.ReactNode;
+  dirs: string[];
+}> = [
+  { id: 'en', icon: <Globe size={18} />, dirs: ['Profile/', 'Connections/', 'Notes/', 'Workflows/', 'Resources/', 'Projects/'] },
+  { id: 'zh', icon: <BookOpen size={18} />, dirs: ['画像/', '关系/', '笔记/', '流程/', '资源/', '项目/'] },
+  { id: 'empty', icon: <FileText size={18} />, dirs: ['README.md', 'CONFIG.json', 'INSTRUCTION.md'] },
+];
+
+const TOTAL_STEPS = 5;
+
+export default function SetupWizard() {
+  const { t } = useLocale();
+  const router = useRouter();
+  const s = t.setup;
+
+  const [step, setStep] = useState(0);
+  const [state, setState] = useState<SetupState>({
+    mindRoot: '~/MindOS',
+    template: 'en',
+    provider: 'anthropic',
+    anthropicKey: '',
+    anthropicModel: 'claude-sonnet-4-6',
+    openaiKey: '',
+    openaiModel: 'gpt-5.4',
+    openaiBaseUrl: '',
+    webPort: 3000,
+    mcpPort: 8787,
+    authToken: '',
+    webPassword: '',
+  });
+  const [tokenCopied, setTokenCopied] = useState(false);
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState('');
+  const [portChanged, setPortChanged] = useState(false);
+
+  // Generate token on mount
+  useEffect(() => {
+    fetch('/api/setup/generate-token', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: '{}' })
+      .then(r => r.json())
+      .then(data => { if (data.token) setState(prev => ({ ...prev, authToken: data.token })); })
+      .catch(() => {});
+  }, []);
+
+  const update = useCallback(<K extends keyof SetupState>(key: K, val: SetupState[K]) => {
+    setState(prev => ({ ...prev, [key]: val }));
+  }, []);
+
+  const generateToken = async (seed?: string) => {
+    try {
+      const res = await fetch('/api/setup/generate-token', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ seed: seed || undefined }),
+      });
+      const data = await res.json();
+      if (data.token) update('authToken', data.token);
+    } catch { /* ignore */ }
+  };
+
+  const copyToken = () => {
+    navigator.clipboard.writeText(state.authToken);
+    setTokenCopied(true);
+    setTimeout(() => setTokenCopied(false), 2000);
+  };
+
+  const handleComplete = async () => {
+    setSubmitting(true);
+    setError('');
+    try {
+      const payload = {
+        mindRoot: state.mindRoot.startsWith('~')
+          ? state.mindRoot  // server will resolve
+          : state.mindRoot,
+        template: state.template || undefined,
+        port: state.webPort,
+        mcpPort: state.mcpPort,
+        authToken: state.authToken,
+        webPassword: state.webPassword,
+        ai: state.provider === 'skip' ? undefined : {
+          provider: state.provider,
+          providers: {
+            anthropic: { apiKey: state.anthropicKey, model: state.anthropicModel },
+            openai: { apiKey: state.openaiKey, model: state.openaiModel, baseUrl: state.openaiBaseUrl },
+          },
+        },
+      };
+      const res = await fetch('/api/setup', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(payload),
+      });
+      const data = await res.json();
+      if (!res.ok) throw new Error(data.error || `HTTP ${res.status}`);
+      if (data.portChanged) setPortChanged(true);
+      else router.push('/');
+    } catch (e) {
+      setError(e instanceof Error ? e.message : String(e));
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  const canNext = () => {
+    if (step === 0) return state.mindRoot.trim().length > 0;
+    if (step === 2) return state.webPort >= 1024 && state.webPort <= 65535 && state.mcpPort >= 1024 && state.mcpPort <= 65535;
+    return true;
+  };
+
+  const maskKey = (key: string) => {
+    if (!key) return '(not set)';
+    if (key.length <= 8) return '•••';
+    return key.slice(0, 6) + '•••' + key.slice(-3);
+  };
+
+  // Step indicator dots
+  const StepDots = () => (
+    <div className="flex items-center gap-2 mb-8">
+      {s.stepTitles.map((title: string, i: number) => (
+        <div key={i} className="flex items-center gap-2">
+          {i > 0 && <div className="w-8 h-px" style={{ background: i <= step ? 'var(--amber)' : 'var(--border)' }} />}
+          <button
+            onClick={() => i < step && setStep(i)}
+            className="flex items-center gap-1.5"
+            disabled={i > step}
+          >
+            <div
+              className="w-6 h-6 rounded-full text-xs font-medium flex items-center justify-center transition-colors"
+              style={{
+                background: i === step ? 'var(--amber)' : i < step ? 'var(--amber)' : 'var(--muted)',
+                color: i <= step ? 'white' : 'var(--muted-foreground)',
+                opacity: i <= step ? 1 : 0.5,
+              }}
+            >
+              {i + 1}
+            </div>
+            <span
+              className="text-xs hidden sm:inline"
+              style={{ color: i === step ? 'var(--foreground)' : 'var(--muted-foreground)', opacity: i <= step ? 1 : 0.5 }}
+            >
+              {title}
+            </span>
+          </button>
+        </div>
+      ))}
+    </div>
+  );
+
+  // Step 1: Knowledge Base
+  const Step1 = () => (
+    <div className="space-y-6">
+      <Field label={s.kbPath} hint={s.kbPathHint}>
+        <Input
+          value={state.mindRoot}
+          onChange={e => update('mindRoot', e.target.value)}
+          placeholder={s.kbPathDefault}
+        />
+      </Field>
+      <div>
+        <label className="text-sm text-foreground font-medium mb-3 block">{s.template}</label>
+        <div className="grid grid-cols-1 sm:grid-cols-3 gap-3">
+          {TEMPLATES.map(tpl => (
+            <button
+              key={tpl.id}
+              onClick={() => update('template', tpl.id)}
+              className="flex flex-col items-start gap-2 p-4 rounded-xl border text-left transition-all duration-150"
+              style={{
+                background: state.template === tpl.id ? 'var(--amber-subtle, rgba(200,135,30,0.08))' : 'var(--card)',
+                borderColor: state.template === tpl.id ? 'var(--amber)' : 'var(--border)',
+              }}
+            >
+              <div className="flex items-center gap-2">
+                <span style={{ color: 'var(--amber)' }}>{tpl.icon}</span>
+                <span className="text-sm font-medium" style={{ color: 'var(--foreground)' }}>
+                  {t.onboarding.templates[tpl.id as 'en' | 'zh' | 'empty'].title}
+                </span>
+              </div>
+              <div
+                className="w-full rounded-lg px-2.5 py-1.5 text-[11px] leading-relaxed"
+                style={{ background: 'var(--muted)', fontFamily: "'IBM Plex Mono', monospace", color: 'var(--muted-foreground)' }}
+              >
+                {tpl.dirs.map(d => <div key={d}>{d}</div>)}
+              </div>
+            </button>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+
+  // Step 2: AI Provider
+  const Step2 = () => (
+    <div className="space-y-5">
+      <Field label={s.aiProvider} hint={s.aiProviderHint}>
+        <Select value={state.provider} onChange={e => update('provider', e.target.value as SetupState['provider'])}>
+          <option value="anthropic">Anthropic</option>
+          <option value="openai">OpenAI</option>
+          <option value="skip">{s.aiSkip}</option>
+        </Select>
+      </Field>
+      {state.provider !== 'skip' && (
+        <>
+          <Field label={s.apiKey}>
+            <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-...'}
+            />
+          </Field>
+          <Field label={s.model}>
+            <Input
+              value={state.provider === 'anthropic' ? state.anthropicModel : state.openaiModel}
+              onChange={e => update(state.provider === 'anthropic' ? 'anthropicModel' : 'openaiModel', e.target.value)}
+            />
+          </Field>
+          {state.provider === 'openai' && (
+            <Field label={s.baseUrl} hint={s.baseUrlHint}>
+              <Input
+                value={state.openaiBaseUrl}
+                onChange={e => update('openaiBaseUrl', e.target.value)}
+                placeholder="https://api.openai.com/v1"
+              />
+            </Field>
+          )}
+        </>
+      )}
+    </div>
+  );
+
+  // Step 3: Ports
+  const Step3 = () => (
+    <div className="space-y-5">
+      <Field label={s.webPort} hint={s.portHint}>
+        <Input
+          type="number"
+          min={1024}
+          max={65535}
+          value={state.webPort}
+          onChange={e => update('webPort', parseInt(e.target.value, 10) || 3000)}
+        />
+      </Field>
+      <Field label={s.mcpPort} hint={s.portHint}>
+        <Input
+          type="number"
+          min={1024}
+          max={65535}
+          value={state.mcpPort}
+          onChange={e => update('mcpPort', parseInt(e.target.value, 10) || 8787)}
+        />
+      </Field>
+      <p className="text-xs flex items-center gap-1.5" style={{ color: 'var(--muted-foreground)' }}>
+        <AlertTriangle size={12} />
+        {s.portRestartWarning}
+      </p>
+    </div>
+  );
+
+  // Step 4: Security
+  const Step4 = () => {
+    const [seed, setSeed] = useState('');
+    const [showSeed, setShowSeed] = useState(false);
+
+    return (
+      <div className="space-y-5">
+        <Field label={s.authToken} hint={s.authTokenHint}>
+          <div className="flex gap-2">
+            <Input value={state.authToken} readOnly className="font-mono text-xs" />
+            <button
+              onClick={copyToken}
+              className="flex items-center gap-1 px-3 py-2 text-xs rounded-lg border border-border hover:bg-muted transition-colors shrink-0"
+              style={{ color: 'var(--foreground)' }}
+            >
+              {tokenCopied ? <Check size={14} /> : <Copy size={14} />}
+              {tokenCopied ? s.copiedToken : s.copyToken}
+            </button>
+            <button
+              onClick={() => generateToken()}
+              className="flex items-center gap-1 px-3 py-2 text-xs rounded-lg border border-border hover:bg-muted transition-colors shrink-0"
+              style={{ color: 'var(--foreground)' }}
+            >
+              <RefreshCw size={14} />
+            </button>
+          </div>
+        </Field>
+
+        <div>
+          <button
+            onClick={() => setShowSeed(!showSeed)}
+            className="text-xs underline"
+            style={{ color: 'var(--muted-foreground)' }}
+          >
+            {s.authTokenSeed}
+          </button>
+          {showSeed && (
+            <div className="mt-2 flex gap-2">
+              <Input
+                value={seed}
+                onChange={e => setSeed(e.target.value)}
+                placeholder={s.authTokenSeedHint}
+              />
+              <button
+                onClick={() => { if (seed.trim()) generateToken(seed); }}
+                className="px-3 py-2 text-xs rounded-lg border border-border hover:bg-muted transition-colors shrink-0"
+                style={{ color: 'var(--foreground)' }}
+              >
+                {s.generateToken}
+              </button>
+            </div>
+          )}
+        </div>
+
+        <Field label={s.webPassword} hint={s.webPasswordHint}>
+          <Input
+            type="password"
+            value={state.webPassword}
+            onChange={e => update('webPassword', e.target.value)}
+            placeholder="(optional)"
+          />
+        </Field>
+      </div>
+    );
+  };
+
+  // Step 5: Review
+  const Step5 = () => {
+    const rows: [string, string][] = [
+      [s.kbPath, state.mindRoot],
+      [s.template, state.template || '—'],
+      [s.aiProvider, state.provider],
+      ...(state.provider !== 'skip' ? [
+        [s.apiKey, maskKey(state.provider === 'anthropic' ? state.anthropicKey : state.openaiKey)] as [string, string],
+        [s.model, state.provider === 'anthropic' ? state.anthropicModel : state.openaiModel] as [string, string],
+      ] : []),
+      [s.webPort, String(state.webPort)],
+      [s.mcpPort, String(state.mcpPort)],
+      [s.authToken, state.authToken || '—'],
+      [s.webPassword, state.webPassword ? '••••••••' : '(none)'],
+    ];
+
+    return (
+      <div className="space-y-5">
+        <p className="text-sm" style={{ color: 'var(--muted-foreground)' }}>{s.reviewHint}</p>
+        <div className="rounded-xl border overflow-hidden" style={{ borderColor: 'var(--border)' }}>
+          {rows.map(([label, value], i) => (
+            <div
+              key={i}
+              className="flex items-center justify-between px-4 py-3 text-sm"
+              style={{
+                background: i % 2 === 0 ? 'var(--card)' : 'transparent',
+                borderTop: i > 0 ? '1px solid var(--border)' : undefined,
+              }}
+            >
+              <span style={{ color: 'var(--muted-foreground)' }}>{label}</span>
+              <span className="font-mono text-xs" style={{ color: 'var(--foreground)' }}>{value}</span>
+            </div>
+          ))}
+        </div>
+
+        {error && (
+          <div className="p-3 rounded-lg text-sm text-red-500" style={{ background: 'rgba(239,68,68,0.1)' }}>
+            {s.completeFailed}: {error}
+          </div>
+        )}
+
+        {portChanged && (
+          <div className="space-y-3">
+            <div className="p-3 rounded-lg text-sm flex items-center gap-2" style={{ background: 'rgba(200,135,30,0.1)', color: 'var(--amber)' }}>
+              <AlertTriangle size={14} />
+              {s.portChanged}
+            </div>
+            <a
+              href="/"
+              className="inline-flex items-center gap-1 px-4 py-2 text-sm rounded-lg transition-colors"
+              style={{ background: 'var(--amber)', color: 'white' }}
+            >
+              {s.completeDone} &rarr;
+            </a>
+          </div>
+        )}
+      </div>
+    );
+  };
+
+  const steps = [Step1, Step2, Step3, Step4, Step5];
+  const CurrentStep = steps[step];
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center overflow-y-auto" style={{ background: 'var(--background)' }}>
+      <div className="w-full max-w-xl mx-auto px-6 py-12">
+        {/* Header */}
+        <div className="text-center mb-8">
+          <div className="inline-flex items-center gap-2 mb-2">
+            <Sparkles size={18} style={{ color: 'var(--amber)' }} />
+            <h1
+              className="text-2xl font-semibold tracking-tight"
+              style={{ fontFamily: "'IBM Plex Mono', monospace", color: 'var(--foreground)' }}
+            >
+              MindOS
+            </h1>
+          </div>
+        </div>
+
+        {/* Step dots */}
+        <div className="flex justify-center">
+          <StepDots />
+        </div>
+
+        {/* Step title */}
+        <h2 className="text-lg font-semibold mb-5" style={{ color: 'var(--foreground)' }}>
+          {s.stepTitles[step]}
+        </h2>
+
+        {/* Step content */}
+        <CurrentStep />
+
+        {/* Navigation */}
+        <div className="flex items-center justify-between mt-8 pt-6" style={{ borderTop: '1px solid var(--border)' }}>
+          <button
+            onClick={() => setStep(step - 1)}
+            disabled={step === 0}
+            className="flex items-center gap-1 px-4 py-2 text-sm rounded-lg border border-border hover:bg-muted transition-colors disabled:opacity-30 disabled:cursor-not-allowed"
+            style={{ color: 'var(--foreground)' }}
+          >
+            <ChevronLeft size={14} />
+            {s.back}
+          </button>
+
+          {step < TOTAL_STEPS - 1 ? (
+            <button
+              onClick={() => setStep(step + 1)}
+              disabled={!canNext()}
+              className="flex items-center gap-1 px-4 py-2 text-sm rounded-lg transition-colors disabled:opacity-30 disabled:cursor-not-allowed"
+              style={{ background: 'var(--amber)', color: 'white' }}
+            >
+              {s.next}
+              <ChevronRight size={14} />
+            </button>
+          ) : (
+            <button
+              onClick={handleComplete}
+              disabled={submitting || portChanged}
+              className="flex items-center gap-1 px-5 py-2 text-sm font-medium rounded-lg transition-colors disabled:opacity-50"
+              style={{ background: 'var(--amber)', color: 'white' }}
+            >
+              {submitting && <Loader2 size={14} className="animate-spin" />}
+              {submitting ? s.completing : portChanged ? s.completeDone : s.complete}
+            </button>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}

package/app/lib/i18n.ts

@@ -186,6 +186,52 @@ export const messages = {
       { keys: ['Esc'], description: 'Cancel edit / close modal' },
       { keys: ['@'], description: 'Attach file in Ask AI' },
     ],
+    setup: {
+      stepTitles: ['Knowledge Base', 'AI Provider', 'Ports', 'Security', 'Review'],
+      // Step 1
+      kbPath: 'Knowledge base path',
+      kbPathHint: 'Absolute path to your notes directory.',
+      kbPathDefault: '~/MindOS',
+      template: 'Starter template',
+      templateSkip: 'Skip (directory already has files)',
+      // Step 2
+      aiProvider: 'AI Provider',
+      aiProviderHint: 'Choose your preferred AI service.',
+      aiSkip: 'Skip — configure later',
+      apiKey: 'API Key',
+      model: 'Model',
+      baseUrl: 'Base URL',
+      baseUrlHint: 'Optional. For proxies or OpenAI-compatible APIs.',
+      // Step 3
+      webPort: 'Web UI port',
+      mcpPort: 'MCP server port',
+      portHint: 'Valid range: 1024–65535',
+      portRestartWarning: 'Port changes take effect after server restart.',
+      // Step 4
+      authToken: 'Auth Token',
+      authTokenHint: 'Bearer token for MCP / API clients. Auto-generated.',
+      authTokenSeed: 'Custom seed (optional)',
+      authTokenSeedHint: 'Enter a passphrase to derive a deterministic token.',
+      generateToken: 'Generate',
+      copyToken: 'Copy',
+      copiedToken: 'Copied!',
+      webPassword: 'Web UI Password',
+      webPasswordHint: 'Optional. Protect browser access with a password.',
+      // Step 5
+      reviewTitle: 'Review Configuration',
+      reviewHint: 'Verify your settings before completing setup.',
+      keyMasked: (key: string) => key.slice(0, 6) + '•••' + key.slice(-3),
+      portChanged: 'Port changed — please restart the server for it to take effect.',
+      // Buttons
+      back: 'Back',
+      next: 'Next',
+      complete: 'Complete Setup',
+      skip: 'Skip',
+      // Status
+      completing: 'Saving...',
+      completeDone: 'Setup complete!',
+      completeFailed: 'Setup failed. Please try again.',
+    },
   },
   zh: {
     common: {
@@ -372,6 +418,52 @@ export const messages = {
       { keys: ['Esc'], description: '取消编辑 / 关闭弹窗' },
       { keys: ['@'], description: '在 AI 对话中添加附件' },
     ],
+    setup: {
+      stepTitles: ['知识库', 'AI 服务商', '端口', '安全', '确认'],
+      // Step 1
+      kbPath: '知识库路径',
+      kbPathHint: '笔记目录的绝对路径。',
+      kbPathDefault: '~/MindOS',
+      template: '初始模板',
+      templateSkip: '跳过（目录已有文件）',
+      // Step 2
+      aiProvider: 'AI 服务商',
+      aiProviderHint: '选择你偏好的 AI 服务。',
+      aiSkip: '跳过 — 稍后配置',
+      apiKey: 'API 密钥',
+      model: '模型',
+      baseUrl: '接口地址',
+      baseUrlHint: '可选。用于代理或 OpenAI 兼容 API。',
+      // Step 3
+      webPort: 'Web UI 端口',
+      mcpPort: 'MCP 服务端口',
+      portHint: '有效范围：1024–65535',
+      portRestartWarning: '端口修改需重启服务后生效。',
+      // Step 4
+      authToken: 'Auth Token',
+      authTokenHint: 'MCP / API 客户端使用的 Bearer Token，自动生成。',
+      authTokenSeed: '自定义种子（可选）',
+      authTokenSeedHint: '输入口令短语生成确定性 Token。',
+      generateToken: '生成',
+      copyToken: '复制',
+      copiedToken: '已复制！',
+      webPassword: '网页访问密码',
+      webPasswordHint: '可选。设置后浏览器访问需要登录。',
+      // Step 5
+      reviewTitle: '确认配置',
+      reviewHint: '完成设置前请确认以下信息。',
+      keyMasked: (key: string) => key.slice(0, 6) + '•••' + key.slice(-3),
+      portChanged: '端口已变更 — 请重启服务以使其生效。',
+      // Buttons
+      back: '上一步',
+      next: '下一步',
+      complete: '完成设置',
+      skip: '跳过',
+      // Status
+      completing: '保存中...',
+      completeDone: '设置完成！',
+      completeFailed: '设置失败，请重试。',
+    },
   },
 } as const;
 

package/app/lib/settings.ts

@@ -21,12 +21,12 @@ export interface AiConfig {
 export interface ServerSettings {
   ai: AiConfig;
   mindRoot: string;   // empty = use env var / default
-  // Fields managed by CLI only (not edited via GUI, preserved on write)
   port?: number;
   mcpPort?: number;
   authToken?: string;
   webPassword?: string;
   startMode?: 'dev' | 'start' | 'daemon';
+  setupPending?: boolean;  // true → / redirects to /setup
 }
 
 const DEFAULTS: ServerSettings = {
@@ -108,6 +108,9 @@ export function readSettings(): ServerSettings {
       webPassword: typeof parsed.webPassword === 'string' ? parsed.webPassword : undefined,
       authToken:   typeof parsed.authToken   === 'string' ? parsed.authToken   : undefined,
       mcpPort:     typeof parsed.mcpPort     === 'number' ? parsed.mcpPort     : undefined,
+      port:        typeof parsed.port        === 'number' ? parsed.port        : undefined,
+      startMode:   typeof parsed.startMode   === 'string' ? parsed.startMode as ServerSettings['startMode'] : undefined,
+      setupPending: parsed.setupPending === true ? true : undefined,
     };
   } catch {
     return { ...DEFAULTS, ai: { ...DEFAULTS.ai, providers: { ...DEFAULTS.ai.providers } } };
@@ -123,6 +126,14 @@ export function writeSettings(settings: ServerSettings): void {
   const merged: Record<string, unknown> = { ...existing, ai: settings.ai, mindRoot: settings.mindRoot };
   if (settings.webPassword !== undefined) merged.webPassword = settings.webPassword;
   if (settings.authToken   !== undefined) merged.authToken   = settings.authToken;
+  if (settings.port        !== undefined) merged.port        = settings.port;
+  if (settings.mcpPort     !== undefined) merged.mcpPort     = settings.mcpPort;
+  if (settings.startMode   !== undefined) merged.startMode   = settings.startMode;
+  // setupPending: false/undefined → remove the field (cleanup); true → set it
+  if ('setupPending' in settings) {
+    if (settings.setupPending) merged.setupPending = true;
+    else delete merged.setupPending;
+  }
   fs.writeFileSync(SETTINGS_PATH, JSON.stringify(merged, null, 2) + '\n', 'utf-8');
 }
 

package/app/lib/template.ts

@@ -0,0 +1,45 @@
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Recursively copy `src` to `dest`, skipping files that already exist in dest.
+ */
+export function copyRecursive(src: string, dest: string) {
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src)) {
+      copyRecursive(path.join(src, entry), path.join(dest, entry));
+    }
+  } else {
+    // Skip if file already exists
+    if (fs.existsSync(dest)) return;
+    const dir = path.dirname(dest);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.copyFileSync(src, dest);
+  }
+}
+
+/**
+ * Apply a built-in template (en / zh / empty) to the given directory.
+ * Returns true on success, throws on error.
+ */
+export function applyTemplate(template: string, destDir: string): void {
+  if (!['en', 'zh', 'empty'].includes(template)) {
+    throw new Error(`Invalid template: ${template}`);
+  }
+
+  // templates/ is at the repo root (sibling of app/)
+  const repoRoot = path.resolve(process.cwd(), '..');
+  const templateDir = path.join(repoRoot, 'templates', template);
+
+  if (!fs.existsSync(templateDir)) {
+    throw new Error(`Template "${template}" not found at ${templateDir}`);
+  }
+
+  if (!fs.existsSync(destDir)) {
+    fs.mkdirSync(destDir, { recursive: true });
+  }
+
+  copyRecursive(templateDir, destDir);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geminilight/mindos",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "MindOS — Human-Agent Collaborative Mind System. Local-first knowledge base that syncs your mind to all AI Agents via MCP.",
   "keywords": [
     "mindos",

package/scripts/setup.js

@@ -26,7 +26,7 @@ import { homedir, tmpdir, networkInterfaces } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline';
 import { pipeline } from 'node:stream/promises';
-import { execSync } from 'node:child_process';
+import { execSync, spawn } from 'node:child_process';
 import { randomBytes, createHash } from 'node:crypto';
 import { createConnection } from 'node:net';
 
@@ -41,6 +41,14 @@ const T = {
   title:          { en: '🧠 MindOS Setup', zh: '🧠 MindOS 初始化' },
   langHint:       { en: '  ← → switch language / 切换语言    ↑ ↓ navigate    Enter confirm', zh: '  ← → switch language / 切换语言    ↑ ↓ 上下切换    Enter 确认' },
 
+  // mode selection
+  modePrompt:     { en: 'Setup mode', zh: '配置方式' },
+  modeOpts:       { en: ['CLI — terminal wizard', 'GUI — browser wizard (recommended)'], zh: ['CLI — 终端向导', 'GUI — 浏览器向导（推荐）'] },
+  modeVals:       ['cli', 'gui'],
+  guiStarting:    { en: '⏳ Starting server for GUI setup...', zh: '⏳ 正在启动服务...' },
+  guiReady:       { en: (url) => `🌐 Complete setup in browser: ${url}`, zh: (url) => `🌐 在浏览器中完成配置: ${url}` },
+  guiOpenFailed:  { en: (url) => `  Could not open browser automatically. Open this URL manually:\n  ${url}`, zh: (url) => `  无法自动打开浏览器，请手动访问：\n  ${url}` },
+
   // step labels
   step:           { en: (n, total) => `Step ${n}/${total}`, zh: (n, total) => `步骤 ${n}/${total}` },
   stepTitles:     {
@@ -493,11 +501,95 @@ async function applyTemplate(tpl, mindDir) {
   }
 }
 
+// ── GUI Setup ─────────────────────────────────────────────────────────────────
+
+function openBrowser(url) {
+  try {
+    const platform = process.platform;
+    if (platform === 'darwin') {
+      execSync(`open "${url}"`, { stdio: 'ignore' });
+    } else if (platform === 'linux') {
+      // Check for WSL
+      const isWSL = existsSync('/proc/version') &&
+        readFileSync('/proc/version', 'utf-8').toLowerCase().includes('microsoft');
+      if (isWSL) {
+        execSync(`cmd.exe /c start "${url}"`, { stdio: 'ignore' });
+      } else {
+        execSync(`xdg-open "${url}"`, { stdio: 'ignore' });
+      }
+    } else {
+      execSync(`cmd.exe /c start "${url}"`, { stdio: 'ignore' });
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function startGuiSetup() {
+  // Ensure ~/.mindos directory exists
+  mkdirSync(MINDOS_DIR, { recursive: true });
+
+  // Read or create config, set setupPending
+  let config = {};
+  try { config = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8')); } catch { /* ignore */ }
+  config.setupPending = true;
+  writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n');
+
+  // Find a free port
+  const port = await findFreePort(3000);
+  if (config.port === undefined) {
+    config.port = port;
+    writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n');
+  }
+  const usePort = config.port || port;
+
+  write(c.yellow(t('guiStarting') + '\n'));
+
+  // Start the server in the background
+  const cliPath = resolve(__dirname, '../bin/cli.js');
+  const child = spawn(process.execPath, [cliPath, 'start'], {
+    detached: true,
+    stdio: 'ignore',
+    env: { ...process.env, PORT: String(usePort) },
+  });
+  child.unref();
+
+  // Wait for the server to be ready
+  const { waitForHttp } = await import('../bin/lib/gateway.js');
+  const ready = await waitForHttp(usePort, { retries: 60, intervalMs: 1000, label: 'MindOS' });
+
+  if (!ready) {
+    write(c.red('\n✘ Server failed to start.\n'));
+    process.exit(1);
+  }
+
+  const url = `http://localhost:${usePort}/setup`;
+  console.log(`\n${c.green(tf('guiReady', url))}\n`);
+
+  const opened = openBrowser(url);
+  if (!opened) {
+    console.log(c.dim(tf('guiOpenFailed', url)));
+  }
+
+  process.exit(0);
+}
+
 // ── Main ──────────────────────────────────────────────────────────────────────
 
 async function main() {
   console.log(`\n${c.bold(t('title'))}\n\n${c.dim(t('langHint'))}\n`);
 
+  // ── Mode selection: CLI or GUI ───────────────────────────────────────────
+  const mode = await select('modePrompt', 'modeOpts', 'modeVals');
+
+  if (mode === 'gui') {
+    await startGuiSetup();
+    return;
+  }
+
+  // ── CLI mode continues below ─────────────────────────────────────────────
+
   // ── Early overwrite check ─────────────────────────────────────────────────
   if (existsSync(CONFIG_PATH)) {
     let existing = {};