AGENTS.md

1# LobeHub Development Guidelines
2 
3Guidelines for using AI coding agents in this opensource LobeHub repository.
4 
5## Tech Stack
6 
7- Next.js 16 + React 19 + TypeScript
8- SPA inside Next.js with `react-router-dom`
9- `@lobehub/ui`, antd, and antd-style for UI implementation
10- react-i18next for i18n; zustand for state management
11- SWR for data fetching; TRPC for type-safe backend
12- Drizzle ORM with PostgreSQL; Vitest for testing
13 
14## Agent Skills
15 
16`AGENTS.md` owns repository-wide architecture and workflow. Keep detailed implementation rules in skills so they have one source of truth.
17 
18- **React and TSX**: Before editing components, component state, render boundaries, or memoization, read [`.agents/skills/react/SKILL.md`](.agents/skills/react/SKILL.md). It owns component selection, styling, state locality, and render-performance rules.
19 
20## Project Structure
21 
22```plaintext
23lobehub/
24├── apps/
25│   ├── desktop/            # Electron desktop app
26│   ├── cli/                # LobeHub CLI
27│   └── server/             # Backend service (Hono app + server routers/services)
28├── packages/               # Shared packages (@lobechat/*)
29│   ├── database/           # Database schemas, models, repositories
30│   ├── agent-runtime/      # Agent runtime
31│   ├── locales/            # i18n source: packages/locales/src/default/
32│   ├── env/                # env schemas (@/envs/* → packages/env/src/*)
33│   └── ...
34├── src/
35│   ├── app/                # Next.js App Router (route shell + auth)
36│   │   ├── (backend)/      # Backend route shells
37│   │   ├── spa/            # SPA HTML template service
38│   │   └── spa-auth/       # Auth HTML shell (SSR)
39│   ├── routes/             # SPA page segments (thin — delegate to features/)
40│   │   ├── (main)/ (mobile)/ (desktop)/ (popup)/
41│   │   ├── auth/           # Auth page segments (signin, signup, …)
42│   │   ├── onboarding/ share/
43│   ├── spa/                # SPA entry points and router config
44│   │   ├── entry.{web,mobile,desktop,popup}.tsx
45│   │   └── router/         # React Router configuration
46│   ├── store/              # Zustand stores
47│   ├── services/           # Client services
48│   ├── libs/               # Shared client/server helpers for the app shell
49│   └── ...
50└── e2e/                    # E2E tests (Cucumber + Playwright)
51```
52 
53## SPA Routes and Features
54 
55SPA-related code is grouped under `src/spa/` (entries + router) and `src/routes/` (page segments). We use a **roots vs features** split: route trees only hold page segments; business logic and UI live in features.
56 
57- **`src/spa/`** – SPA entry points (`entry.web.tsx`, `entry.mobile.tsx`, `entry.desktop.tsx`, `entry.popup.tsx`) and React Router config (`router/`, with `desktopRouter.config.*`, `mobileRouter.config.tsx`, `popupRouter.config.tsx`). Keeps router config next to entries to avoid confusion with `src/routes/`.
58 
59- **`src/routes/` (roots)**\
60  Only page-segment files: `_layout/index.tsx`, `index.tsx` (or `page.tsx`), and dynamic segments like `[id]/index.tsx`. Keep these **thin**: they should only import from `@/features/*` and compose layout/page, with no business logic or heavy UI.
61 
62- **`src/features/`**\
63  Business components by **domain** (e.g. `Pages`, `PageEditor`, `Home`). Put layout chunks (sidebar, header, body), hooks, and domain-specific UI here. Each feature exposes an `index.ts` (or `index.tsx`) with clear exports.
64 
65When adding or changing SPA routes:
66 
671. In `src/routes/`, add only the route segment files (layout + page) that delegate to features.
682. Implement layout and page content under `src/features/<Domain>/` and export from there.
693. In route files, use `import { X } from '@/features/<Domain>'` (or `import Y from '@/features/<Domain>/...'`). Do not add new `features/` folders inside `src/routes/`.
704. **Register shared desktop content routes once:** add common Web/Electron paths, nesting, metadata, lazy loaders, and `preloadId` values in `src/spa/router/desktopRouter.shared.tsx`. The thin `desktopRouter.config.tsx` and `desktopRouter.config.desktop.tsx` files contain only runtime differences: Web mounts the content tree directly, while Electron keeps slim root stubs and mounts the same tree in per-tab memory routers through `src/spa/router/tabRouter.tsx`. Add code to a platform adapter only when the route is genuinely platform-specific. `desktopRouter.sync.test.tsx` guards the shared behavior and explicit differences — keep it passing.
71 
72See the **spa-routes** skill for the full convention and file-division rules.
73 
74## Development
75 
76### Starting the Dev Environment
77 
78```bash
79# SPA dev mode (frontend only, proxies API to localhost:3010)
80bun run dev:spa
81 
82# Full-stack dev (Next.js + Vite SPA concurrently)
83bun run dev
84 
85# Standalone Hono backend service
86pnpm --filter @lobechat/server dev
87```
88 
89### Backend Architecture
90 
91- Backend runtime code lives under `apps/server/src` and is imported through `@/server/*`.
92- `src/app/(backend)` contains Next.js route shells. Do not add backend business logic there.
93- Web shell helpers belong under `src/libs/*` or the relevant `src/app` segment, not under `src/server`.
94 
95After `dev:spa` starts, the terminal prints a **Debug Proxy** URL:
96 
97```plaintext
98Debug Proxy: https://app.lobehub.com/_dangerous_local_dev_proxy?debug-host=http%3A%2F%2Flocalhost%3A9876
99```
100 
101Open this URL to develop locally against the production backend (app.lobehub.com). The proxy page loads your local Vite dev server's SPA into the online environment, enabling HMR with real server config.
102 
103### Git Workflow
104 
105- **Branch strategy**: `canary` is the development branch (cloud production); `main` is the release branch (periodically cherry-picks from canary)
106- New branches should be created from `canary`; PRs should target `canary`
107- Use rebase for `git pull`
108- Commit messages: prefix with gitmoji
109- Branch format: `<type>/<feature-name>`
110 
111### Package Management
112 
113- `pnpm` for dependency management
114- `bun` to run npm scripts
115- `bunx` for executable npm packages
116 
117### Quality Check
118 
119```bash
120bun run check [changed-files...]
121```
122 
123- Every bug fix must include a corresponding regression test that fails before the fix and passes after it. **Skip** when the fix is pure style/CSS (selector, hover, mask, spacing, color) and the only practical assertion would be source-string matching on the stylesheet — that is not a regression test worth shipping.
124- No selector = **lint + test in a single pass** — run it once; don't fire a separate pass per selector. `--lint` / `--test` / `--type` narrow scope and are composable within one run. Default files = all working-tree changes (staged + unstaged + untracked); explicit paths override.
125- `--lint` auto-fixes the given files and prints the applied fixes as a diff, so you can review what changed.
126- `--test` auto-discovers the related tests for the given source files and runs them under the nearest owning vitest config (e.g. `packages/database`) — no need to `cd` into packages.
127- `--type` runs the full type-check. NEVER run `bun run test` — the full suite takes \~10 minutes.
128- To run tests manually (e.g. a single file or unusual flags), `cd` into the owning package first: `cd packages/database && bunx vitest run --silent='passed-only' '[file-path]'`.
129 
130### i18n
131 
132- Add keys to a namespace file under `packages/locales/src/default/` (e.g. `agent.ts`, `auth.ts`)
133- Ship en-US and zh-CN by hand in the same PR: author the English source in `packages/locales/src/default/*.ts`, mirror it to `locales/en-US/`, and hand-translate `locales/zh-CN/`.
134- Leave all other locales to the daily CI workflow (`.github/workflows/auto-i18n.yml`), which runs `bun run i18n` and opens an automated translation PR. Missing locale keys fall back to English until that PR is merged.
135- Run `bun run i18n` manually only when the translated locales are needed immediately instead of waiting for the daily workflow. It is slow and requires `OPENAI_API_KEY`; don't hand-translate the generated locales.
136 
137### Code Style
138 
139- When a single file grows beyond \~800 lines, consider splitting it into multiple files (extract sub-components, hooks, helpers, or types). Smaller, focused files are friendly to humans and agents.
140 
141### Code Review
142 
143Before reviewing a PR / diff / branch change, read the **deep-review** skill. Ordinary review requests use its light mode (inline review against the dimension quick checklists); the full multi-subagent deep mode runs only on explicit invocation.
144 
145When designing or reviewing user-facing flows (empty/loading/error states, confirmations, async feedback, button hierarchy, lists at scale, pickers), follow LobeHub's design values in [`DESIGN.md`](./DESIGN.md) — Natural / Meaningful / Certainty / Growth (自然 / 意义感 / 确定性 / 成长).
146