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

2026-02-07 17:00:52 +08:00
parent 4bbb0c4a16
commit 41e79449ce
2 changed files with 96 additions and 80 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,14 +4,14 @@ Guidelines for AI agents working in this Bun monorepo.

 ## Project Overview

-> **⚠️ This project uses [Bun](https://bun.sh) exclusively as both the JavaScript runtime and package manager. Do NOT use Node.js / npm / yarn / pnpm. All commands start with `bun` — use `bun install` for dependencies and `bun run` / `bun <script>` for scripts. Never use `npm`, `npx`, or `node`.**
+> **This project uses [Bun](https://bun.sh) exclusively as both the JavaScript runtime and package manager. Do NOT use Node.js / npm / yarn / pnpm. All commands start with `bun` — use `bun install` for dependencies and `bun run` / `bun <script>` for scripts. Never use `npm`, `npx`, or `node`.**

 - **Monorepo**: Bun workspaces + Turborepo orchestration
 - **Runtime**: Bun (see `mise.toml` for version) — **NOT Node.js**
 - **Package Manager**: Bun — **NOT npm / yarn / pnpm**
 - **Apps**:
  - `apps/server` - TanStack Start fullstack web app (see `apps/server/AGENTS.md`)
-  - `apps/desktop` - Tauri v2 desktop shell, loads server via sidecar (see `apps/desktop/AGENTS.md`)
+  - `apps/desktop` - Electrobun desktop shell, loads server in native window (see `apps/desktop/AGENTS.md`)
 - **Packages**: `packages/utils`, `packages/tsconfig` (shared configs)

 ## Build / Lint / Test Commands
@@ -27,7 +27,8 @@ bun typecheck      # TypeScript check across monorepo
 ### Server App (`apps/server`)
 ```bash
 bun dev                   # Vite dev server (localhost:3000)
-bun build                 # Production build → .output/
+bun build                 # Production build -> .output/
+bun compile               # Compile to standalone binary
 bun fix                   # Biome auto-fix
 bun typecheck             # TypeScript check

@@ -40,13 +41,11 @@ bun db:studio             # Open Drizzle Studio

 ### Desktop App (`apps/desktop`)
 ```bash
-bun dev                   # Copy sidecar + start Tauri dev
-bun build                 # Copy sidecar + build installer
-
-# Rust (from apps/desktop/src-tauri/)
-cargo check               # Compile check
-cargo clippy              # Linter
-cargo fmt                 # Formatter
+bun dev                   # Start Electrobun dev mode (requires server dev running)
+bun build                 # Build canary release
+bun build:stable          # Build stable release
+bun fix                   # Biome auto-fix
+bun typecheck             # TypeScript check
 ```

 ### Testing
@@ -54,23 +53,17 @@ No test framework configured yet. When adding tests:
 ```bash
 bun test path/to/test.ts              # Run single test file
 bun test -t "pattern"                 # Run tests matching pattern
-cargo test test_name -- --nocapture   # Rust single test with output
 ```

 ## Code Style (TypeScript)

 ### Formatting (Biome)
- **Indent**: 2 spaces
- **Line endings**: LF
- **Quotes**: Single `'`
- **Semicolons**: Omit (ASI)
+- **Indent**: 2 spaces | **Line endings**: LF
+- **Quotes**: Single `'` | **Semicolons**: Omit (ASI)
 - **Arrow parentheses**: Always `(x) => x`

 ### Imports
-Biome auto-organizes. Order:
-1. External packages
-2. Internal `@/*` aliases
-3. Type imports (`import type { ... }`)
+Biome auto-organizes. Order: 1) External packages → 2) Internal `@/*` aliases → 3) Type imports (`import type { ... }`)

 ```typescript
 import { createFileRoute } from '@tanstack/react-router'
@@ -80,10 +73,7 @@ import type { ReactNode } from 'react'
 ```

 ### TypeScript Strictness
- `strict: true`
- `noUncheckedIndexedAccess: true` - array/object access returns `T | undefined`
- `noImplicitOverride: true`
- `verbatimModuleSyntax: true`
+- `strict: true`, `noUncheckedIndexedAccess: true`, `noImplicitOverride: true`, `verbatimModuleSyntax: true`
 - Use `@/*` path aliases (maps to `src/*`)

 ### Naming Conventions
@@ -97,41 +87,19 @@ import type { ReactNode } from 'react'
 | Types/Interfaces | PascalCase | `UserProfile` |

 ### React Patterns
-```typescript
-// Components: arrow functions (enforced by Biome)
-const MyComponent = ({ title }: { title: string }) => {
-  return <div>{title}</div>
-}
-
-// Routes: TanStack Router file conventions
-export const Route = createFileRoute('/')({
-  component: Home,
-})
-
-// Data fetching: TanStack Query
-const { data } = useSuspenseQuery(orpc.todo.list.queryOptions())
-```
+- Components: arrow functions (enforced by Biome)
+- Routes: TanStack Router file conventions (`export const Route = createFileRoute(...)`)
+- Data fetching: `useSuspenseQuery(orpc.feature.list.queryOptions())`
+- Let React Compiler handle memoization (no manual `useMemo`/`useCallback`)

 ### Error Handling
- Use `try-catch` for async operations
- Throw descriptive errors
+- Use `try-catch` for async operations; throw descriptive errors
 - ORPC: Use `ORPCError` with proper codes (`NOT_FOUND`, `INPUT_VALIDATION_FAILED`)
 - Never use empty catch blocks

-## Code Style (Rust - Tauri)
-
- **Indent**: 4 spaces
- **Naming**: snake_case (functions), PascalCase (types), SCREAMING_SNAKE (consts)
- Use `expect("中文消息")` over `unwrap()`
- Async: `tokio` runtime, `tauri::async_runtime::spawn`
- Run `cargo fmt` and `cargo clippy` before commit
-
 ## Database (Drizzle ORM)

 ```typescript
-import { pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core'
-import { sql } from 'drizzle-orm'
-
 export const myTable = pgTable('my_table', {
  id: uuid().primaryKey().default(sql`uuidv7()`),
  name: text().notNull(),
@@ -143,17 +111,22 @@ export const myTable = pgTable('my_table', {
 ## Environment Variables

 - Use `@t3-oss/env-core` with Zod validation in `src/env.ts`
- Server vars: no prefix
- Client vars: `VITE_` prefix required
+- Server vars: no prefix | Client vars: `VITE_` prefix required
 - Never commit `.env` files

+## Dependency Management
+
+- All versions centralized in root `package.json` `catalog` field
+- Workspace packages use `"catalog:"` — never hardcode versions
+- Internal packages use `"workspace:*"` references
+
 ## Critical Rules

 **DO:**
 - Run `bun fix` before committing
 - Use `@/*` path aliases (not relative imports)
- Let React Compiler handle memoization (no manual `useMemo`/`useCallback`)
 - Include `createdAt`/`updatedAt` on all tables
+- Use `catalog:` for dependency versions

 **DON'T:**
 - Use `npm`, `npx`, `node`, `yarn`, `pnpm` — always use `bun` / `bunx`
@@ -161,7 +134,7 @@ export const myTable = pgTable('my_table', {
 - Use `as any`, `@ts-ignore`, `@ts-expect-error`
 - Commit `.env` files
 - Use empty catch blocks `catch(e) {}`
- Use `unwrap()` in Rust without `expect()`
+- Hardcode dependency versions in workspace packages

 ## Git Workflow

@@ -185,20 +158,21 @@ export const myTable = pgTable('my_table', {
 │   │   │       ├── api/  # ORPC contracts, routers, middlewares
 │   │   │       └── db/   # Drizzle schema
 │   │   └── AGENTS.md
-│   └── desktop/          # Tauri v2 shell (no frontend src)
-│       ├── src-tauri/    # Rust Tauri code
-│       │   ├── src/      # Rust source
-│       │   └── binaries/ # Sidecar binaries
+│   └── desktop/          # Electrobun desktop shell
+│       ├── src/
+│       │   └── bun/
+│       │       └── index.ts       # Main process entry
+│       ├── electrobun.config.ts   # Electrobun configuration
 │       └── AGENTS.md
 ├── packages/
 │   ├── tsconfig/         # Shared TS configs
 │   └── utils/            # Shared utilities
 ├── biome.json            # Linting/formatting config
 ├── turbo.json            # Turbo task orchestration
-└── package.json          # Workspace root
+└── package.json          # Workspace root + dependency catalog
 ```

 ## See Also

 - `apps/server/AGENTS.md` - Detailed TanStack Start / ORPC patterns
- `apps/desktop/AGENTS.md` - Rust / Tauri development guide
+- `apps/desktop/AGENTS.md` - Electrobun desktop development guide