feat: add Electron support for headless exe service

- Add folder selection button in UI
- Add Electron main process with IPC handlers
- Support --port and --docs command line arguments
- Support --headless mode for headless service
- Add portable exe build configuration

electron/main.mjs

@@ -0,0 +1,151 @@
+import { app, BrowserWindow, ipcMain, dialog } from 'electron';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { createServer } from 'http';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+let mainWindow = null;
+let docsPath = '';
+let port = 3001;
+
+const DEFAULT_PORT = 3001;
+
+function parseArgs() {
+  const args = { port: DEFAULT_PORT, docs: null, headless: false };
+  const portIndex = process.argv.indexOf('--port');
+  if (portIndex !== -1 && process.argv[portIndex + 1]) {
+    args.port = parseInt(process.argv[portIndex + 1], 10);
+  }
+  
+  const docsIndex = process.argv.indexOf('--docs');
+  if (docsIndex !== -1 && process.argv[docsIndex + 1]) {
+    args.docs = process.argv[docsIndex + 1];
+  }
+  
+  if (process.argv.includes('--headless')) {
+    args.headless = true;
+  }
+  
+  return args;
+}
+
+const args = parseArgs();
+port = args.port;
+docsPath = args.docs || path.join(process.cwd(), 'src', 'docs');
+
+function getDistPath() {
+  if (app.isPackaged) {
+    return path.join(process.resourcesPath, 'app', 'dist');
+  }
+  return path.join(__dirname, '..', 'dist');
+}
+
+function loadDistServer() {
+  const distPath = getDistPath();
+  const indexPath = path.join(distPath, 'index.html');
+  
+  const server = require('http').createServer((req, res) => {
+    let filePath = path.join(distPath, req.url === '/' ? 'index.html' : req.url);
+    
+    if (!filePath.startsWith(distPath)) {
+      res.writeHead(403);
+      res.end('Forbidden');
+      return;
+    }
+    
+    const ext = path.extname(filePath);
+    const contentTypes = {
+      '.html': 'text/html',
+      '.js': 'application/javascript',
+      '.css': 'text/css',
+      '.json': 'application/json',
+      '.png': 'image/png',
+      '.jpg': 'image/jpeg',
+      '.svg': 'image/svg+xml',
+      '.md': 'text/markdown',
+    };
+    
+    const fs = require('fs');
+    if (fs.existsSync(filePath)) {
+      const contentType = contentTypes[ext] || 'application/octet-stream';
+      res.writeHead(200, { 'Content-Type': contentType });
+      res.end(fs.readFileSync(filePath));
+    } else {
+      res.writeHead(404);
+      res.end('Not Found');
+    }
+  });
+  
+  server.listen(port, () => {
+    console.log(`XCSDD Server running on http://localhost:${port}`);
+    console.log(`Docs path: ${docsPath}`);
+    if (args.headless) {
+      console.log(`Headless mode: enabled`);
+    }
+  });
+  
+  return server;
+}
+
+function createWindow() {
+  if (args.headless) {
+    loadDistServer();
+    return;
+  }
+  
+  loadDistServer();
+  
+  mainWindow = new BrowserWindow({
+    width: 1200,
+    height: 800,
+    webPreferences: {
+      preload: path.join(__dirname, 'preload.mjs'),
+      contextIsolation: true,
+      nodeIntegration: false,
+    },
+  });
+  
+  mainWindow.loadURL(`http://localhost:${port}`);
+  
+  mainWindow.on('closed', () => {
+    mainWindow = null;
+  });
+}
+
+ipcMain.handle('select-folder', async () => {
+  if (!mainWindow) return null;
+  
+  const result = await dialog.showOpenDialog(mainWindow, {
+    properties: ['openDirectory'],
+  });
+  
+  if (result.canceled || result.filePaths.length === 0) {
+    return null;
+  }
+  
+  docsPath = result.filePaths[0];
+  mainWindow.webContents.send('docs-path-changed', docsPath);
+  return docsPath;
+});
+
+ipcMain.handle('get-docs-path', () => {
+  return docsPath;
+});
+
+app.whenReady().then(() => {
+  createWindow();
+  
+  app.on('activate', () => {
+    if (BrowserWindow.getAllWindows().length === 0) {
+      createWindow();
+    }
+  });
+});
+
+app.on('window-all-closed', () => {
+  if (process.platform !== 'darwin') {
+    app.quit();
+  }
+});

electron/preload.mjs

@@ -0,0 +1,9 @@
+import { contextBridge, ipcRenderer } from 'electron';
+
+contextBridge.exposeInMainWorld('electronAPI', {
+  selectFolder: () => ipcRenderer.invoke('select-folder'),
+  getDocsPath: () => ipcRenderer.invoke('get-docs-path'),
+  onDocsPathChanged: (callback: (path: string) => void) => {
+    ipcRenderer.on('docs-path-changed', (_event, path) => callback(path));
+  },
+});

package.json

@@ -1,12 +1,18 @@
 {
   "name": "xcengine-api-docs",
   "version": "1.0.0",
+  "description": "XCSDD - API Docs & 3D Blueprint Viewer",
+  "author": "XCSDD",
+  "main": "electron/main.mjs",
   "type": "module",
   "scripts": {
     "dev": "vite",
     "build": "tsc -b && vite build",
     "lint": "eslint .",
-    "preview": "vite preview"
+    "preview": "vite preview",
+    "electron:dev": "vite build && electron .",
+    "electron:build": "vite build && electron-builder --win --x64",
+    "electron:start": "electron ."
   },
   "dependencies": {
     "@react-three/drei": "^10.7.7",
@@ -28,6 +34,8 @@
     "@types/three": "^0.183.1",
     "@vitejs/plugin-react": "^6.0.0",
     "autoprefixer": "^10.4.21",
+    "electron": "^33.4.0",
+    "electron-builder": "^25.1.8",
     "eslint": "^9.39.4",
     "eslint-plugin-react-hooks": "^7.0.1",
     "eslint-plugin-react-refresh": "^0.5.2",
@@ -37,5 +45,23 @@
     "typescript": "~5.9.3",
     "typescript-eslint": "^8.56.1",
     "vite": "^8.0.0"
+  },
+  "build": {
+    "appId": "com.xuanchi.xcsdd",
+    "productName": "XCSDD",
+    "directories": {
+      "output": "release"
+    },
+    "files": [
+      "dist/**/*",
+      "electron/**/*",
+      "package.json"
+    ],
+    "win": {
+      "target": "portable"
+    },
+    "portable": {
+      "artifactName": "XCSDD.exe"
+    }
   }
 }

release/win-unpacked/LICENSE.electron.txt

@@ -0,0 +1,21 @@
+Copyright (c) Electron contributors
+Copyright (c) 2013-2020 GitHub Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

release/win-unpacked/vk_swiftshader_icd.json

@@ -0,0 +1 @@
+{"file_format_version": "1.0.0", "ICD": {"library_path": ".\\vk_swiftshader.dll", "api_version": "1.0.5"}}

src/App.tsx

@@ -1,20 +1,62 @@
-import { useState } from 'react';
-import { FileText, Box } from 'lucide-react';
+import { useState, useEffect } from 'react';
+import { FileText, Box, FolderOpen } from 'lucide-react';
 import { ApiDocViewer } from './components/ApiDocViewer';
 import BlueprintPage from './components/blueprint/BlueprintPage';
 import { config } from './config';
 
 type Page = 'docs' | 'blueprint';
 
+declare global {
+  interface Window {
+    electronAPI?: {
+      selectFolder: () => Promise<string | null>;
+      getDocsPath: () => Promise<string>;
+      onDocsPathChanged: (callback: (path: string) => void) => void;
+    };
+  }
+}
+
 function App() {
   const [currentPage, setCurrentPage] = useState<Page>('docs');
+  const [docsPath, setDocsPath] = useState<string>('');
   
+  useEffect(() => {
     document.title = config.projectName;
     
+    if (window.electronAPI) {
+      window.electronAPI.getDocsPath().then(setDocsPath);
+      window.electronAPI.onDocsPathChanged(setDocsPath);
+    }
+  }, []);
+  
+  const handleSelectFolder = async () => {
+    if (window.electronAPI) {
+      const path = await window.electronAPI.selectFolder();
+      if (path) {
+        setDocsPath(path);
+      }
+    }
+  };
+
   return (
     <div className="h-screen flex flex-col">
       <header className="h-12 bg-zinc-900 border-b border-zinc-800 flex items-center px-4 justify-between">
+        <div className="flex items-center gap-3">
           <h1 className="text-sm font-medium text-white">{config.projectName}</h1>
+          {docsPath && (
+            <span className="text-xs text-zinc-500">📁 {docsPath}</span>
+          )}
+        </div>
+        <div className="flex items-center gap-2">
+          {window.electronAPI && (
+            <button
+              onClick={handleSelectFolder}
+              className="flex items-center gap-2 px-3 py-1.5 rounded text-sm text-zinc-400 hover:text-white hover:bg-zinc-800/50"
+              title="选择文档文件夹"
+            >
+              <FolderOpen size={16} />
+            </button>
+          )}
           <nav className="flex gap-1">
             <button
               onClick={() => setCurrentPage('docs')}
@@ -39,6 +81,7 @@ function App() {
               3D 蓝图
             </button>
           </nav>
+        </div>
       </header>
       <main className="flex-1 overflow-hidden">
         {currentPage === 'docs' ? <ApiDocViewer /> : <BlueprintPage />}