docs: 更新 AGENTS.md 适配 Electrobun 替代 Tauri

apps/desktop/AGENTS.md

@@ -1,15 +1,16 @@
 # AGENTS.md - Desktop App Guidelines
 
-Electrobun desktop shell - loads the server app in a native window.
+Electrobun desktop shell — loads the server app in a native window.
 
 > **⚠️ This project uses Bun — NOT Node.js / npm. All commands use `bun`. Never use `npm`, `npx`, or `node`.**
 
 ## Architecture
 
 - **Type**: Electrobun desktop application
-- **Design**: Bun main process + system webview (or CEF)
+- **Design**: Bun main process + CEF renderer (Chromium Embedded Framework)
 - **Dev mode**: Connects to `localhost:3000` (requires server dev running)
 - **Prod mode**: Embeds server bundle and starts local HTTP server
+- **Config**: `electrobun.config.ts` — app metadata, build entrypoint, platform options
 
 ## Commands
 
@@ -18,8 +19,14 @@ Electrobun desktop shell - loads the server app in a native window.
 bun dev                    # Start Electrobun dev mode
 
 # Build
-bun build                  # Build canary release
-bun build:stable           # Build stable release
+bun build                  # Build canary release (current platform)
+bun build:all              # Build canary release (all platforms)
+bun build:stable           # Build stable release (current platform)
+bun build:stable:all       # Build stable release (all platforms)
+
+# Code Quality
+bun fix                    # Biome auto-fix (lint + format)
+bun typecheck              # TypeScript check
 ```
 
 ## Directory Structure
@@ -28,20 +35,39 @@ bun build:stable           # Build stable release
 apps/desktop/
 ├── src/
 │   └── bun/
-│       └── index.ts       # Electrobun main process entry
-├── electrobun.config.ts   # Electrobun configuration
+│       └── index.ts       # Main process entry (BrowserWindow + server wait)
+├── electrobun.config.ts   # App name, identifier, version, build config
 ├── package.json
-└── tsconfig.json
+├── tsconfig.json          # Extends @furtherverse/tsconfig/bun.json
+└── turbo.json             # Build output config
 ```
 
 ## Development Workflow
 
-1. **Start server dev first**: `cd ../server && bun dev`
-2. **Start Electrobun**: `bun dev` (from apps/desktop/)
-3. Electrobun connects to localhost:3000
+1. **Start server dev first**: `bun dev` from `apps/server/`
+2. **Start Electrobun**: `bun dev` from `apps/desktop/`
+3. Desktop app polls `localhost:3000` until server responds, then opens window
 
 ## Electrobun Patterns
 
+### Config (`electrobun.config.ts`)
+
+```typescript
+import type { ElectrobunConfig } from 'electrobun'
+
+export default {
+  app: {
+    name: 'MyApp',
+    identifier: 'com.example.myapp',
+    version: '0.1.0',
+  },
+  build: {
+    bun: { entrypoint: 'src/bun/index.ts' },
+    linux: { bundleCEF: true },
+  },
+} satisfies ElectrobunConfig
+```
+
 ### BrowserWindow
 
 ```typescript
@@ -50,16 +76,30 @@ import { BrowserWindow } from 'electrobun/bun'
 new BrowserWindow({
   title: 'My App',
   url: 'http://localhost:3000',
-  frame: {
-    x: 100,
-    y: 100,
-    width: 1200,
-    height: 800,
-  },
+  frame: { x: 100, y: 100, width: 1200, height: 800 },
+  renderer: 'cef',
 })
 ```
 
-### Events
+### Server Readiness Check
+
+```typescript
+// Poll server before opening window — don't block indefinitely
+async function waitForServer(url: string, timeoutMs = 30000): Promise<boolean> {
+  const start = Date.now()
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const response = await fetch(url, { method: 'HEAD' })
+      if (response.ok) return true
+    } catch {
+      await Bun.sleep(100)
+    }
+  }
+  return false
+}
+```
+
+### Application Events
 
 ```typescript
 import Electrobun from 'electrobun/bun'
@@ -73,10 +113,12 @@ Electrobun.events.on('will-quit', () => {
 
 **DO:**
 - Run server dev before desktop dev
-- Use `catalog:` for dependencies
-- Handle server startup gracefully
+- Use `catalog:` for dependency versions
+- Wait for server readiness before opening BrowserWindow
+- Handle server timeout gracefully (exit with helpful error message)
 
 **DON'T:**
 - Use `npm`, `npx`, `node`, `yarn`, `pnpm` — always use `bun` / `bunx`
 - Hardcode dependency versions (use catalog)
-- Block main thread during server wait
+- Block main thread with synchronous waits
+- Use `unwrap()`-style patterns without error handling