weifuwu 0.33.9 → 0.33.11

package/README.md

@@ -1,651 +1,822 @@
 # weifuwu
 
-**AI SaaS full-stack framework** — `(req, ctx) => Response` + `(props, ctx) => JSX`
+**全栈框架 — 后端 `(req, ctx) => Response` + 前端 `(props, ctx) => JSX`**
 
 ```bash
 npm install weifuwu
 ```
 
-One package. Backend + frontend. User system, messaging, RAG knowledge base, AI Agent, CMS, dynamic data storage, reactive frontend. Set env vars and go.
+一个包，无上游依赖。后端提供 HTTP 路由、数据库、中间件；前端提供信号驱动的无 VDOM 响应式框架。
 
 ---
 
-## Core Concept: `ctx`
+## 模块总览
+
+| 模块 | 导出 | 用途 | 依赖 |
+|------|------|------|------|
+| **Router** | `Router` | HTTP 路由 + 中间件链 + WebSocket + GraphQL | — |
+| **serve** | `serve` | HTTP 服务器 | `Router` |
+| **cors** | `cors` | CORS 跨域中间件 | `Router` |
+| **serveStatic** | `serveStatic` | 静态文件服务 | `Router` |
+| **postgres** | `postgres` | PostgreSQL 客户端 → `ctx.sql` | `Router` |
+| **redis** | `redis` | Redis 客户端 → `ctx.redis` | `Router` |
+| **ui** | `ui` | SSR 渲染 + 动态 JS 编译 → `ctx.ui.html/css/js` | `Router` |
+| **graphql** | `router.graphql()` | GraphQL 端点 | `Router` |
+| **client** | 28 个导出 | 前端响应式框架（见下方表格） | — |
+
+**前端 `weifuwu/client` 模块总览：**
+
+| 类别 | 导出 | 用途 |
+|------|------|------|
+| **信号系统** | `signal`, `computed`, `effect`, `batch`, `untrack`, `isSignal` | 响应式状态 |
+| **JSX 运行时** | `jsx`/`jsxs`/`jsxDEV`, `Fragment` | TSX 编译目标 |
+| **控制流** | `Show`, `For` | 条件/列表渲染 |
+| **生命周期** | `onMount`, `onCleanup` | 组件挂载/卸载 |
+| **应用** | `createApp` | 中间件链 + 挂载 |
+| **路由** | `router`, `RouteView`, `lazy` | 嵌套布局 + 代码分割 + 滚动恢复 |
+| **中间件** | `ws`, `api`, `auth` | WebSocket / HTTP 客户端 / 认证状态 |
+| **工具** | `createResource`, `useForm`, `ErrorBoundary`, `createPortal`, `wrap`, `createContext`, `extendCtx`, `domMount` | 异步数据 / 表单 / 错误边界 / Portal |
+| **类型 (19)** | `Signal`, `Component`, `WfuiContext`, `AppMiddleware`, `RouteDef`, `ApiClient`, `AuthClient`, `ResourceState`, `FormReturn`, 等 | — |
 
-**`ctx` 是整个框架的核心模式。** 后端和前端共享同一个理念：通过中间件向 `ctx` 注入能力，组件/handler 直接从 `ctx` 读取。
+---
 
-```
-后端:                                    前端:
-  Request → 中间件链 → Handler            createApp() → 中间件链 → 组件
-              │                                         │
-              ▼                                         ▼
-          ctx.sql                                  ctx.api
-          ctx.user                                 ctx.socket
-          ctx.kb                                   ctx.route
-          ctx.agent                                ctx.user
-          ctx.redis                                ctx.app.navigate
-          ctx.messager                             ctx.provide/inject
-          ctx.cms
-          ctx.base
-          ctx.queue
-          ctx.ui
-```
+## 核心理念：`ctx`
 
-**后端每个请求创建一个 ctx：**
-```ts
-// 中间件注入 → handler 直接使用
-app.get('/api/chat', async (req, ctx) => {
-  const user = ctx.user           // 当前用户（auto-resolve from JWT）
-  const result = await ctx.kb.search(query)      // RAG 知识库
-  return ctx.agent.chatStreamResponse({ messages })  // AI 流式响应
-})
-```
+前后端共享同一模式：**中间件向 `ctx` 注入字段，handler/组件从 `ctx` 读取。**
 
-**前端每个组件通过第二个参数接收 ctx：**
-```tsx
-function ChatPage(_props: {}, ctx: WfuiContext) {
-  ctx.api.get('/api/posts')       // HTTP 客户端
-  ctx.socket.send(data)           // WebSocket
-  ctx.route.path                  // 当前路由
-  ctx.app.navigate('/about')      // 页面导航
-}
 ```
-
-这种模式让开发者**无需 import 任何工具函数**，所有能力在 `ctx` 中一站获取。
-
----
-
-## Module Overview
-
-### Backend — 每个模块向 ctx 注入什么
-
-| Module | Import | Injects into `ctx` | Depends on | Purpose |
-|--------|--------|-------------------|------------|---------|
-| `postgres()` | `weifuwu` | `ctx.sql` | `DATABASE_URL` | PostgreSQL client |
-| `redis()` | `weifuwu` | `ctx.redis` | `REDIS_URL` | Redis client |
-| `user()` | `weifuwu` | `ctx.user`, `ctx.userModule` | `postgres()`, `JWT_SECRET` | Auth, JWT, roles |
-| `messager()` | `weifuwu` | `ctx.messager` | `postgres()`, `user()` | IM + AI conversation |
-| `kb()` | `weifuwu` | `ctx.kb` | `postgres()`, `DASHSCOPE_API_KEY` | RAG knowledge base |
-| `agent()` | `weifuwu` | `ctx.agent` | — | LLM chat, tools, streaming |
-| `cms()` | `weifuwu` | `ctx.cms` | `postgres()`, `user()` | Blog, docs, changelog |
-| `base()` | `weifuwu` | `ctx.base` | `postgres()`, `user()` | Dynamic data engine |
-| `queue()` | `weifuwu` | `ctx.queue` | `REDIS_URL` | Job queue + cron |
-| `ui()` | `weifuwu` | `ctx.ui.html/js/css` | — | SSR/SPA rendering |
-
-### Backend Middleware
-
-| Middleware | Injects into `ctx` | Purpose |
-|-----------|-------------------|---------|
-| `cors()` | — | CORS headers |
-| `helmet()` | — | Security headers |
-| `compress()` | — | gzip / brotli / deflate |
-| `rateLimit()` | — | Sliding-window rate limiter |
-| `logger()` | — | Request logging |
-| `upload()` | `ctx.upload` | Multipart file upload |
-| `serveStatic()` | — | Static files |
-| `sandbox()` | — | Filesystem isolation |
-
-### Frontend (`weifuwu/client`) — 每个中间件向 ctx 注入什么
-
-| Import | Type | Injects into `ctx` | Purpose |
-|--------|------|-------------------|---------|
-| `signal()` | function | — | Reactive state container |
-| `computed()` | function | — | Derived signals |
-| `effect()` | function | — | Auto-tracked side effects |
-| `batch()` | function | — | Batch multiple signal writes |
-| `untrack()` | function | — | Read signal without subscribing |
-| `onMount()` | function | — | Component mount callback |
-| `onCleanup()` | function | — | Component unmount callback |
-| `api()` | **middleware** | `ctx.api.get/post/...` | HTTP client |
-| `auth()` | **middleware** | `ctx.user/login/logout` | Auth state management |
-| `socket()` | **middleware** | `ctx.socket.send/onMessage/...` | WebSocket client |
-| `router()` | **middleware** | `ctx.route.path/params/query`, `ctx.app.navigate` | Hash/history router |
-| `createApp()` | function | — | App instance |
-| `<RouteView>` | component | — | Route outlet |
-| `<Show>` | component | — | Conditional rendering |
-| `<For>` | component | — | Keyed list rendering |
-| `<Transition>` | component | — | Animated enter/leave |
-| `<ErrorBoundary>` | component | — | Catch render errors |
-| `<Link>` | component | — | SPA navigation link |
-| `<LoginForm>` | component | — | Login/register form |
-| `<Chat>` | component | — | Real-time messaging |
-| `useForm()` | function | — | Form state management |
-| `useModel()` | function | — | Two-way form binding |
-| `reactiveArray()` | function | — | Reactive array with mut methods |
-| `createResource()` | function | — | Async data (loading/error/data) |
-| `createStyles()` | function | — | Scoped CSS |
-| `createContext()` | function | — | Type-safe provide/inject |
-| `createPortal()` | function | — | Render outside parent DOM |
-| `wrap()` | function | — | Third-party lib integration |
-| `enableDevtools()` | function | — | Dev warnings + browser inspector |
+后端:                               前端:
+  Request → Middleware → Handler     createApp() → Middleware → Component
+             │                                    │
+             ▼                                    ▼
+         ctx.sql                              ctx.ws
+         ctx.redis                            ctx.route
+         ctx.ui                               ctx.api / ctx.auth
+```
 
 ---
 
-## Quick Start
-
-### 完整全栈示例 — ctx 贯穿前后端
+## 快速开始 — 全栈应用
 
-**后端 `server.ts`：**
 ```ts
-import { serve, Router, postgres, user, agent, kb, messager, ui, cors, logger } from 'weifuwu'
-import { openai } from '@ai-sdk/openai'
+// server.ts — 同一个 npm 包
+import { serve, Router, cors, ui } from 'weifuwu'
 
 const app = new Router()
 app.use(cors())
-app.use(logger())
-app.use(postgres())                    // → ctx.sql
-app.use(user())                        // → ctx.user, ctx.userModule
-app.use(kb())                          // → ctx.kb
-app.use(agent({
-  model: openai('deepseek-v4-flash', { baseURL: 'https://api.deepseek.com/v1' }),
-  knowledge: { search: async (q, ctx) => ctx.kb.search(q) },
-}))                                     // → ctx.agent
-app.use(messager())                    // → ctx.messager
-app.use(ui())                          // → ctx.ui
-
-// 业务 API — ctx 中所有能力可直接使用
-app.post('/api/chat', async (req, ctx) => {
-  const { messages } = await req.json()
-  return ctx.agent.chatStreamResponse({ messages })
+app.use(ui())
+
+// REST API
+app.get('/api/posts', async (req, ctx) => {
+  const posts = [{ id: 1, title: 'Hello' }]
+  return Response.json(posts)
 })
 
-app.post('/api/messages', async (req, ctx) => {
-  const msg = await ctx.messager.sendMessage(ctx.params.conversationId, req.body)
-  return Response.json(msg, { status: 201 })
+// WebSocket
+app.ws('/ws', {
+  open(ws) { ws.send(JSON.stringify({ type: 'system', body: 'connected' })) },
+  message(ws, ctx, data) {
+    const msg = JSON.parse(data.toString())
+    ws.send(JSON.stringify({ type: 'echo', body: msg.body }))
+  },
 })
 
-// 客户端编译（无需本地构建步骤）
+// SPA 入口 — 动态编译前端（零构建步骤）
+app.get('/', async (req, ctx) => ctx.ui.html`
+  <!DOCTYPE html>
+  <html><body><div id="root"></div>
+  <script src="/static/app.js"></script></body></html>
+`)
 app.get('/static/app.js', async (req, ctx) => ctx.ui.js('./src/main.tsx'))
 
 serve(app, { port: 3000 })
 ```
 
-**前端 `src/main.tsx` — ctx 驱动组件：**
 ```tsx
-import { signal, createApp, api, auth, socket, router, RouteView, LoginForm, Link } from 'weifuwu/client'
-import type { WfuiContext } from 'weifuwu/client'
+// src/main.tsx — 前端
+import {
+  signal, computed, Show, For, ErrorBoundary, createPortal, wrap,
+  createApp, router, RouteView, lazy,
+  ws, api, auth, useForm, createResource,
+} from 'weifuwu/client'
+import type { WfuiContext, RouteDef } from 'weifuwu/client'
+
+const app = createApp()
+app.use(api({ baseURL: '' }))
+app.use(auth())
+app.use(ws())
+app.use(router({
+  routes: [
+    { path: '/', component: Home },
+    {
+      path: '/dashboard',
+      layout: DashboardLayout,
+      children: [
+        { path: '/overview', component: lazy(() => import('./Overview')) },
+        { path: '/settings', component: lazy(() => import('./Settings')) },
+      ],
+    },
+  ],
+  mode: 'hash',
+  scrollRestoration: true,
+}))
+app.mount('#root', AppShell)
 
 function AppShell(_props: {}, ctx: WfuiContext) {
-  if (!ctx.isAuthenticated) return <LoginForm />
   return (
     <div>
-      <nav><Link to="/chat">Chat</Link></nav>
+      <nav>{/* ... */}</nav>
       <main><RouteView /></main>
     </div>
   )
 }
-
-const app = createApp()
-app.use(api())                        // → ctx.api.get/post/...
-app.use(auth())                       // → ctx.user/login/logout
-app.use(socket())                     // → ctx.socket.send/onMessage
-app.use(router({ routes }))           // → ctx.route.path/params/query
-app.mount('#root', AppShell)
-```
-
-**`tsconfig.json`：**
-```json
-{ "jsx": "react-jsx", "jsxImportSource": "weifuwu/client" }
 ```
 
 ---
 
-## Environment Variables
+## 后端
 
-| Variable | Default | Used by |
-|----------|---------|---------|
-| `DATABASE_URL` | `postgres://root:123456@localhost:5432/demo` | `postgres()` |
-| `REDIS_URL` | `redis://localhost:6379` | `redis()`, `queue()` |
-| `JWT_SECRET` | — | `user()` |
-| `DASHSCOPE_API_KEY` | — | `kb()` (embedding) |
-| `DEEPSEEK_API_KEY` / `OPENAI_API_KEY` | — | `agent()` (LLM) |
-| `DEEPSEEK_MODEL` | `deepseek-v4-flash` | `agent()` |
+### Router
 
----
+```ts
+const app = new Router()
+
+// HTTP 方法
+app.get(path, ...handlers)
+app.post / put / delete / patch / head / options(path, ...handlers)
+app.all(path, ...handlers)
 
-## Backend Modules
+// WebSocket / GraphQL
+app.ws(path, handler)
+app.graphql('/graphql', handler)
 
-### postgres
-```ts
-import { postgres } from 'weifuwu'
-const sql = postgres()
-app.use(sql)  // → ctx.sql
-await ctx.sql`SELECT * FROM users WHERE id = ${id}`
-await ctx.sql.begin(async (sql) => { /* transaction */ })
-```
-| Method | Description |
-|--------|-------------|
-| `ctx.sql\`...\`` | Tagged template SQL |
-| `ctx.sql.begin(fn)` | Transaction |
-| `sql.close()` | Close pool |
-
-### redis
-```ts
-import { redis } from 'weifuwu'
-const r = redis()
-app.use(r)  // → ctx.redis
-await ctx.redis.set('key', 'value')
-await ctx.redis.get('key')
-redis.close()
+// 中间件
+app.use(middleware)
+app.mount(prefix, subRouter)
+app.onError(handler)
+
+// 调试
+app.routes()  // 列出所有路由
 ```
-Reads `REDIS_URL` env (default: `redis://localhost:6379`).
 
-### user
+| 方法 | 参数 | 说明 |
+|------|------|------|
+| `get/post/put/delete/patch/head/options` | `(path, ...handlers)` | 注册 HTTP 路由 |
+| `all` | `(path, ...handlers)` | 匹配所有方法 |
+| `ws` | `(path, handler)` | WebSocket 端点 |
+| `graphql` | `('/path', handler)` | GraphQL 端点 |
+| `use` | `(middleware)` | 全局中间件 |
+| `mount` | `(prefix, subRouter)` | 子路由挂载 |
+| `onError` | `(handler)` | 全局错误处理 |
+| `routes` | `()` | 返回路由列表数组 |
+
+### serve — HTTP 服务器
+
 ```ts
-import { user, requireRole } from 'weifuwu'
-app.use(postgres())
-app.use(user({ secret: process.env.JWT_SECRET }))
-// → ctx.user (UserRecord | undefined), ctx.userModule
+const srv = serve(app, { port: 3000 })
+await srv.stop()   // 程序化停止
+// Ctrl+C / SIGTERM — 自动关闭所有连接后退出
+```
 
-// ctx.user 由 Authorization Bearer token 或 token cookie 自动解析
-app.get('/api/me', async (req, ctx) => {
-  if (!ctx.user) return new Response('Unauthorized', { status: 401 })
-  return Response.json(ctx.user)  // ctx.user.name / .email / .role
-})
+| 选项 | 默认 | 说明 |
+|------|------|------|
+| `port` | `0` | 监听端口 |
+| `hostname` | `'0.0.0.0'` | 监听地址 |
+| `maxBodySize` | `10MB` | 请求体上限 |
+| `timeout` | `30000` | Socket 超时 (ms) |
+| `shutdown` | `true` | 是否注册 SIGTERM/SIGINT 处理 |
+
+### cors — CORS 中间件
+
+```ts
+app.use(cors({
+  origin: ['https://example.com'],
+  credentials: true,
+}))
 ```
-| `ctx.userModule.*` | Returns | Description |
-|--------------------|---------|-------------|
-| `register(input)` | `{ user, token }` | Register |
-| `login(email, pw)` | `{ user, token } \| null` | Login |
-| `getUserById(id)` | `UserRecord \| null` | Get by ID |
-| `updateUser(id, input)` | `UserRecord \| null` | Update |
-| `changePassword(id, oldPw, newPw)` | `boolean` | Change password |
-| `deleteUser(id)` | `boolean` | Soft delete |
-| `listUsers(inactive?)` | `UserRecord[]` | List users |
-| `verifyToken(token)` | `TokenPayload \| null` | Verify JWT |
 
-`requireRole('admin')` — guard middleware. No auth → 401, wrong role → 403.
+### serveStatic — 静态文件
 
-### messager
 ```ts
-import { messager } from 'weifuwu'
-app.use(postgres())
-app.use(user())
-app.use(messager())  // → ctx.messager
-```
-| `ctx.messager.*` | Returns | Description |
-|------------------|---------|-------------|
-| `sendMessage(convId, body)` | `Message` | Send + WebSocket broadcast |
-| `getMessages(convId, opts?)` | `Message[]` | Cursor pagination |
-| `getConversations()` | `Conversation[]` | List with unread |
-| `createDirectConversation(userId)` | `Conversation` | Create/reuse DM |
-| `createGroupConversation(title, userIds)` | `Conversation` | Create group |
-| `editMessage(msgId, body)` | `Message \| null` | Edit (24h) |
-| `deleteMessage(msgId)` | `boolean` | Soft delete |
-| `markRead(convId)` | `void` | Mark as read |
-
-### kb — Knowledge Base
+app.use(serveStatic('./public', { prefix: '/assets' }))
+```
+
+| 选项 | 默认 | 说明 |
+|------|------|------|
+| `prefix` | `''` | URL 前缀 |
+| `index` | `'index.html'` | 默认首页 |
+
+### postgres — PostgreSQL
+
 ```ts
-import { kb } from 'weifuwu'
 app.use(postgres())
-app.use(kb())  // → ctx.kb
+// → ctx.sql`SELECT * FROM users`
+
+app.use(postgres({ url: 'postgres://user:pass@host:5432/db' }))
+// 默认读取 DATABASE_URL 环境变量
 ```
-| `ctx.kb.*` | Returns | Description |
-|------------|---------|-------------|
-| `importText(title, text)` | `{ document, chunks }` | Import → chunk → embed |
-| `search(query, opts?)` | `SearchResult[]` | Semantic search |
-| `list()` | `Document[]` | List documents |
-| `get(id)` | `Document \| null` | Get document |
-| `delete(id)` | `boolean` | Delete + cascade chunks |
 
-### agent
+| 选项 | 默认 | 说明 |
+|------|------|------|
+| `url` | `DATABASE_URL` | 连接字符串 |
+| `migrations` | `'./migrations'` | 迁移文件目录 |
+
+依赖：需要 `postgres` npm 包。实现 `close(): Promise<void>`。
+
+### redis — Redis
+
 ```ts
-import { agent } from 'weifuwu'
-import { openai } from '@ai-sdk/openai'
-import { tool } from 'ai'
-import { z } from 'zod'
-
-app.use(agent({
-  model: openai('deepseek-v4-flash', { baseURL: 'https://api.deepseek.com/v1' }),
-  system: 'You are a helpful assistant.',
-  knowledge: { search: async (q, ctx) => ctx.kb.search(q) },
-  tools: {
-    getWeather: tool({
-      description: 'Get weather for a city',
-      parameters: z.object({ city: z.string() }),
-      execute: async ({ city }) => ({ temp: 22, unit: 'C' }),
-    }),
-  },
-  maxSteps: 5,
-}))  // → ctx.agent
+app.use(redis())
+// → ctx.redis.get('key')
+// → ctx.redis.set('key', 'value')
+// 默认读取 REDIS_URL 环境变量
 ```
-| `ctx.agent.*` | Description |
-|--------------|-------------|
-| `chat(prompt, opts?)` | Non-streaming, returns text |
-| `chatStreamResponse({ messages })` | SSE stream (useChat compatible) |
 
-### cms
+依赖：需要 `ioredis` npm 包。实现 `close(): Promise<void>`。
+
+### ui — SSR + SPA 渲染
+
 ```ts
-import { cms, requireRole } from 'weifuwu'
-app.use(postgres())
-app.use(user())
-app.use(cms())  // → ctx.cms
+app.use(ui())
+
+// SSR 页面
+app.get('/blog/:slug', async (req, ctx) => ctx.ui.html`
+  <!DOCTYPE html>
+  <html><body><h1>${post.title}</h1></body></html>
+`)
+
+// 动态 JS 编译（esbuild，零构建步骤）
+app.get('/app.js', async (req, ctx) => ctx.ui.js('./src/main.tsx'))
+
+// CSS 编译（PostCSS + Tailwind）
+app.get('/style.css', async (req, ctx) => ctx.ui.css('./src/style.css'))
 ```
-| `ctx.cms.*` | Returns | Description |
-|-------------|---------|-------------|
-| `create(input)` | `Content` | Create (admin) |
-| `get(slug)` | `Content \| null` | Get by slug |
-| `list(opts?)` | `Content[]` | List with filters |
-| `publish(id)` / `unpublish(id)` | `Content \| null` | Toggle status |
 
-### base — Dynamic Data Engine
+| 方法 | 用途 |
+|------|------|
+| `ctx.ui.html\`...\`` | 渲染 HTML 模板（转义变量防 XSS） |
+| `ctx.ui.html.unsafe(str)` | 插入原始 HTML |
+| `ctx.ui.js(entryPath)` | 动态编译 TSX → JS bundle |
+| `ctx.ui.css(entryPath)` | 编译 CSS (PostCSS + Tailwind) |
+
+### graphql — GraphQL
+
 ```ts
-app.use(base())  // → ctx.base
-ctx.base.create({ name, tables })
-ctx.base.insert(baseId, table, data)
-ctx.base.query(baseId, table, { filter, limit })
+app.graphql(async (req, ctx) => ({
+  schema: `type Query { hello: String }`,
+  resolvers: { Query: { hello: () => 'world' } },
+  graphiql: true,
+}))
 ```
 
-### queue
+### WebSocket
+
 ```ts
-const q = queue()
-app.use(q)
-q.process('email', async (job) => { ... })
-q.cron('cleanup', '0 3 * * *', () => ...)
-await q.add('email', { to: 'user@example.com' })
-q.run()
+app.ws('/ws', {
+  open(ws, ctx) { ws.send('connected') },
+  message(ws, ctx, data) { /* data: string | Buffer */ },
+  close(ws, ctx) { /* cleanup */ },
+  error(ws, ctx, err) { /* log */ },
+})
 ```
 
-### ui — SSR & SPA
+### 错误处理
+
 ```ts
-app.use(ui())  // → ctx.ui
-// SSR page
-app.get('/blog/:slug', async (req, ctx) => ctx.ui.html`<!DOCTYPE html>...`)
-// Dynamic JS compilation (no build step)
-app.get('/static/app.js', async (req, ctx) => ctx.ui.js('./src/main.tsx'))
-// CSS with Tailwind v4 support
-app.get('/static/style.css', async (req, ctx) => ctx.ui.css('./public/style.css'))
+app.onError((err, req, ctx) => {
+  if (err instanceof HttpError) {
+    return new Response(err.message, { status: err.status })
+  }
+  console.error(err)
+  return new Response('Internal Server Error', { status: 500 })
+})
 ```
 
----
+| 类/常量 | 说明 |
+|---------|------|
+| `HttpError` | HTTP 错误 `new HttpError(msg, status)` |
+| `DEFAULT_MAX_BODY` | 默认请求体上限 10MB |
+| `MIGRATIONS_TABLE` | Postgres 迁移表名 |
 
-## Frontend — weifuwu/client
+### 后端类型
 
-Reactive frontend framework. Zero virtual DOM, zero external dependencies.
+`Context`, `Handler`, `Middleware`, `ErrorHandler`, `WebSocket`, `WebSocketHandler`, `ServeOptions`, `Server`, `CORSOptions`, `ServeStaticOptions`, `PostgresOptions`, `PostgresClient`, `PostgresInjected`, `RedisOptions`, `RedisClient`, `RedisInjected`, `GraphQLOptions`, `GraphQLHandler`
 
-### Core APIs
+---
 
-```tsx
-// Signal — reactive state
-const count = signal(0)
-const doubled = computed(() => count.value * 2)
-effect(() => console.log('count:', count.value))
+## 前端 (`weifuwu/client`)
 
-// Batch — merge multiple writes
-batch(() => { a.value = 1; b.value = 2 })
+**2750 行源码，28 个运行时导出 + 19 个类型，零外部依赖。**
 
-// Untrack — read without subscribing
-effect(() => { console.log(untrack(() => theme.value)) })
+构建配置（esbuild）：
+```js
+esbuild.build({
+  jsx: 'automatic',
+  jsxImportSource: 'weifuwu/client',
+  bundle: true,
+})
+```
 
-// Lifecycle
-onMount(() => { init(); return () => cleanup() })
-onCleanup(() => clearInterval(id))
+### 信号系统
+
+```tsx
+const count = signal(0)                    // 创建
+const doubled = computed(() => count.value * 2)  // 衍生
+effect(() => console.log('count:', count.value))  // 副作用
+batch(() => { a.value = 1; b.value = 2 })         // 批量更新
+untrack(() => theme.value)                // 不追踪依赖
+isSignal(value)                           // 类型判断
 ```
 
-### Reactive Array
+| 函数 | 签名 | 说明 |
+|------|------|------|
+| `signal` | `<T>(initial: T) => Signal<T>` | 响应式数据容器 |
+| `computed` | `<T>(fn: () => T) => Signal<T>` | 衍生值，自动缓存 |
+| `effect` | `(fn: () => void) => dispose()` | 自动追踪依赖，变化时重跑 |
+| `batch` | `(fn: () => void) => void` | 合并多次写入为一次通知 |
+| `untrack` | `<T>(fn: () => T) => T` | 读取信号但不追踪依赖 |
+| `isSignal` | `(value: unknown) => value is Signal` | 判断是否为 Signal |
+
+### JSX 运行时
 
 ```tsx
-const items = reactiveArray([1, 2, 3])
-items.push(4)        // [1, 2, 3, 4]
-items.pop()          // [1, 2, 3]
-items.remove(1)      // [1, 3]
-items.clear()        // []
-items.sort()
-items.reverse()
+// 自动由 esbuild 调用（无需手动导入）
+<div class="foo">hello</div>
+<Fragment>...</Fragment>
 ```
 
-### Control Flow
+| 导出 | 说明 |
+|------|------|
+| `jsx` / `jsxs` / `jsxDEV` | JSX 编译目标 |
+| `Fragment` | `<></>` 片段组件 |
+
+**Signal 属性自动绑定：** `<input value={signalVal} />` — 信号变化时只更新对应 DOM 属性。
+
+### 控制流
 
 ```tsx
-// Show — conditional rendering
-<Show when={isLoggedIn} fallback={<LoginPage />}>
+<Show when={isLoggedIn} fallback={<Login />}>
   <Dashboard />
 </Show>
 
-// For — keyed list rendering
-<For each={todos} keyBy="id">
-  {(todo) => <TodoItem todo={todo} />}
+<For each={items} keyBy="id">
+  {(item) => <div>{item.name}</div>}
 </For>
+```
 
-// Transition — animated enter/leave
-<Transition show={isOpen} name="fade">
-  <Modal />
-</Transition>
+| 组件 | 属性 | 说明 |
+|------|------|------|
+| `Show` | `when: boolean \| Signal<boolean>`, `fallback?`, `children?` | 条件渲染，Signal 响应式切换 |
+| `For` | `each: T[] \| Signal<T[]>`, `children: (item, index) => Node`, `keyBy?` | 列表渲染，支持 keyed 复用 |
 
-// ErrorBoundary — catch render errors
-<ErrorBoundary fallback={(e) => <p>{e.message}</p>} onError={reportError}>
-  {() => <Dashboard />}
-</ErrorBoundary>
+### 生命周期
+
+```tsx
+onMount(() => {
+  init()
+  return () => cleanup()  // 自动清理
+})
+onCleanup(() => clearInterval(id))
 ```
 
-### Form Handling
+| 函数 | 说明 |
+|------|------|
+| `onMount(fn)` | 组件挂载后执行，返回函数在卸载时自动清理 |
+| `onCleanup(fn)` | 组件卸载时执行 |
+
+### 应用
 
 ```tsx
-// useForm — validation + submit
-const form = useForm({
-  initial: { email: '', password: '' },
-  validate: { email: (v) => !v && '必填' },
-  validateOnInit: true,
-})
-<input {...form.field('email')} placeholder="邮箱" />
-<button onClick={() => form.submit(data => ctx.login(data))}>登录</button>
+const app = createApp()
+app.use(middleware1)
+app.use(middleware2)
+await app.mount('#root', AppShell)
+```
+
+| 方法 | 说明 |
+|------|------|
+| `use(mw)` | 注册中间件，返回 `this` 支持链式 |
+| `mount(selector, RootComponent)` | 挂载到 DOM |
+| `hydrate(selector, Component, props?)` | 在 SSR 内容上附加组件 |
+| `ctx` | 当前上下文 |
 
-// useModel — two-way binding (shorter)
-const name = signal('')
-const agreed = signal(false)
-<input {...useModel(name)} placeholder="姓名" />
-<input type="checkbox" {...useModel(agreed)} /> 同意
+### 路由
+
+```tsx
+// 路由定义
+const routes: RouteDef[] = [
+  { path: '/', component: HomePage },
+  {
+    path: '/dashboard',
+    layout: DashboardLayout,    // 嵌套布局
+    children: [
+      { path: '/overview', component: Overview },  // 子路由
+      { path: '/settings', component: Settings },
+    ],
+  },
+  { path: '/user/:id', component: UserPage, title: '用户' },
+]
+
+// 注册路由中间件
+app.use(router({
+  routes,
+  notFound: NotFound,
+  mode: 'hash',                // 'hash' | 'history'
+  scrollRestoration: true,
+}))
+
+// 路由出口 — 根层级和嵌套层级用同一个组件
+function AppShell() {
+  return <main><RouteView /></main>   // 根出口
+}
+function DashboardLayout() {
+  return (
+    <div class="flex">
+      <Sidebar />
+      <main><RouteView /></main>      // 嵌套出口（同一组件）
+    </div>
+  )
+}
 ```
 
-### Async Data
+| RouteDef 字段 | 类型 | 说明 |
+|---------------|------|------|
+| `path` | `string` | 路由路径，支持 `/:param` |
+| `component` | `Component` | 路由组件 |
+| `layout` | `Component` | 嵌套布局（渲染 `<RouteView />` 显示子路由）|
+| `children` | `RouteDef[]` | 子路由（与 layout 配合使用）|
+| `auth` | `boolean` | 是否需要登录 |
+| `title` | `string` | 页面标题（自动设置 `document.title`）|
+| `loader` | `(ctx) => Promise<data>` | 数据预取 → `ctx.route.data` |
+| `transition` | `string` | 页面切换过渡动画 CSS class 前缀 |
+
+| RouterOptions | 默认 | 说明 |
+|---------------|------|------|
+| `mode` | `'hash'` | 路由模式 |
+| `notFound` | — | 404 组件 |
+| `scrollRestoration` | `true` | 历史模式时恢复滚动位置 |
+| `transition` | — | 全局过渡动画 |
+
+**`ctx.route` 注入：**
 
 ```tsx
-const [posts, { loading, error, refetch }] = createResource(
-  () => ctx.api.get('/api/posts'),
-  { retry: 2, timeout: 5000 },  // optional
-)
+ctx.route.path       // '/user/42'
+ctx.route.params     // { id: '42' }
+ctx.route.query      // { tab: 'profile' }
+ctx.route.component  // 当前路由组件
+ctx.route.data       // loader 返回的数据
+ctx.route.loading    // loader 是否加载中
+ctx.app.navigate('/path')
+```
+
+### 代码分割
+
+```tsx
+const AdminPage = lazy(() => import('./pages/AdminPage'), {
+  fallback: () => <div>加载中...</div>,
+})
 
-<Show when={loading}><Skeleton /></Show>
-<Show when={error}><Error /></Show>
-<For each={posts}>{(post) => <PostCard post={post} />}</For>
+const routes = [
+  { path: '/admin', component: AdminPage },
+]
 ```
 
-### Scoped CSS
+需 esbuild `splitting: true` + `outdir`。
+
+### 中间件
+
+#### ws — WebSocket 客户端
 
 ```tsx
-const s = createStyles({
-  card: 'background: white; border-radius: 8px; padding: 16px;',
-  title: 'font-size: 18px; color: #333;',
+app.use(ws({ url: '/ws' }))
+
+// 组件中：
+onMount(() => {
+  const unsub = ctx.ws.onMessage((data) => { ... })
+  onCleanup(() => unsub())
 })
-<div class={s.card}><h2 class={s.title}>...</h2></div>
+ctx.ws.send({ type: 'chat', body: 'hello' })
+<Show when={ctx.ws.isConnected}>🟢 已连接</Show>
 ```
 
-### Type-Safe Context
+| `ctx.ws` | 类型 | 说明 |
+|----------|------|------|
+| `send` | `(data: unknown) => void` | 发送消息 |
+| `onMessage` | `(handler) => dispose()` | 注册消息监听 |
+| `isConnected` | `Signal<boolean>` | 连接状态信号 |
+
+| 选项 | 默认 | 说明 |
+|------|------|------|
+| `url` | `'/ws'` | WebSocket 地址 |
+| `reconnectInterval` | `3000` | 重连间隔 (ms) |
+| `maxReconnect` | `10` | 最大重连次数 |
+
+#### api — HTTP 客户端
 
 ```tsx
-const ThemeCtx = createContext<string>('theme')
-ThemeCtx.provide(ctx, 'dark')     // 提供
-const theme = ThemeCtx.inject(ctx) // string | null
+app.use(api({ baseURL: '/api' }))
+
+// 组件中：
+await ctx.api.get<User[]>('/users')
+await ctx.api.post<User>('/users', body)
+await ctx.api.put<User>('/users/1', body)
+await ctx.api.patch<User>('/users/1', body)
+await ctx.api.delete('/users/1')
 ```
 
-### Third-Party Integration
+| `ctx.api` | 签名 | 说明 |
+|-----------|------|------|
+| `get` | `<T>(url, opts?) => Promise<T>` | GET 请求 |
+| `post` | `<T>(url, body?, opts?) => Promise<T>` | POST 请求 |
+| `put` | `<T>(url, body?, opts?) => Promise<T>` | PUT 请求 |
+| `patch` | `<T>(url, body?, opts?) => Promise<T>` | PATCH 请求 |
+| `delete` | `<T>(url, opts?) => Promise<T>` | DELETE 请求 |
+
+| 选项 | 说明 |
+|------|------|
+| `baseURL` | API 基础路径 |
+| `headers` | 默认请求头 |
+| `onRequest` | 请求拦截器 `({url, init}) => {url, init}` |
+| `onResponse` | 响应拦截器 `(res) => Promise<T>` |
+
+错误类型：`ApiError` — 包含 `status` 和 `body`。
+
+#### auth — 认证状态管理
 
 ```tsx
-const PieChart = wrap('div', (el, props, ctx) => {
-  const chart = echarts.init(el)
-  chart.setOption({ series: [{ type: 'pie', data: props.data }] })
-  effect(() => chart.setOption(...))
-  return () => chart.dispose()
+app.use(auth())
+
+// 组件中：
+<Show when={ctx.auth.isLoggedIn} fallback={<Login />}>
+  <span>{ctx.auth.user.value?.name}</span>
+  <button onClick={() => ctx.auth.logout()}>退出</button>
+</Show>
+
+// 登录
+ctx.auth.login('jwt-token', { id: 1, name: 'Alice' })
+// 退出
+ctx.auth.logout()
+```
+
+| `ctx.auth` | 类型 | 说明 |
+|-----------|------|------|
+| `token` | `Signal<string \| null>` | 当前 token |
+| `user` | `Signal<AuthUser \| null>` | 当前用户 |
+| `isLoggedIn` | `Signal<boolean>` | 是否已登录（computed）|
+| `login` | `(token, user) => void` | 存储 token + 用户到 localStorage |
+| `logout` | `() => void` | 清除 token + 用户 |
+| `setUser` | `(user) => void` | 更新用户信息 |
+| `authorizationHeader` | `Signal<string \| null>` | `'Bearer xxx'` 或 `null` |
+
+| 选项 | 默认 | 说明 |
+|------|------|------|
+| `storage` | `localStorage` | 存储方式 |
+| `tokenKey` | `'weifuwu_token'` | token 存储 key |
+| `userKey` | `'weifuwu_user'` | 用户信息存储 key |
+
+### 工具
+
+#### useForm — 表单管理
+
+```tsx
+const form = useForm({
+  initial: { name: '', email: '' },
+  validate: {
+    name: (v) => !v ? '请输入姓名' : null,
+    email: [
+      (v) => !v ? '请输入邮箱' : null,
+      (v) => !v.includes('@') ? '邮箱格式错误' : null,
+    ],
+  },
+  onSubmit: async (values) => {
+    await ctx.api.post('/users', values)
+  },
 })
-<Dashboard><PieChart data={salesData} /></Dashboard>
+
+// JSX：
+<form onSubmit={form.handleSubmit}>
+  <input {...form.field('name')} />
+  <span>{form.errors.value.name}</span>
+  <button disabled={form.submitting}>提交</button>
+</form>
 ```
 
-### Pre-built Components
+| 返回值 | 类型 | 说明 |
+|--------|------|------|
+| `values` | `Signal<T>` | 表单值 |
+| `errors` | `Signal<Partial<Record<keyof T, string\|null>>>` | 验证错误 |
+| `submitting` | `Signal<boolean>` | 提交状态 |
+| `touched` | `Signal<Partial<Record<keyof T, boolean>>>` | 触碰字段 |
+| `handleSubmit` | `(e: Event) => void` | 提交处理（绑定到 `<form>`）|
+| `field` | `(name) => { value, onInput, error }` | 字段绑定对象 |
+| `setValue` | `(name, value) => void` | 设字段值 |
+| `reset` | `() => void` | 重置表单 |
+| `validateAll` | `() => boolean` | 触发全部验证 |
+
+#### createResource — 异步数据
 
 ```tsx
-import { LoginForm, Chat, Link } from 'weifuwu/client'
+const [data, { loading, error, refetch }] = createResource(
+  () => fetch('/api/posts').then(r => r.json()),
+  { initialValue: [] }
+)
 
-<LoginForm />       // 登录/注册（自动切换模式）
-<Chat conversationId="123" />  // 实时消息聊天
-<Link to="/about">关于</Link>   // SPA 导航（支持右键新标签页）
+// JSX：
+<Show when={loading}><p>加载中...</p></Show>
+<Show when={error}><p>错误: {error.value?.message}</p></Show>
+<Show when={computed(() => !loading.value && !error.value)}>
+  <For each={data}>{(item) => <div>{item.title}</div>}</For>
+</Show>
 ```
 
-### Router
+| 返回值 | 类型 | 说明 |
+|--------|------|------|
+| `data` (元组第一项) | `Signal<T \| undefined>` | 数据信号 |
+| `loading` | `Signal<boolean>` | 加载状态 |
+| `error` | `Signal<Error \| undefined>` | 错误信号 |
+| `refetch` | `() => void` | 手动重新加载 |
+
+#### ErrorBoundary — 错误捕获
 
 ```tsx
-const routes: RouteDef[] = [
-  { path: '/', component: HomePage, title: 'Home' },
-  { path: '/post/:id', component: PostPage,
-    loader: async (ctx) => ({ post: await ctx.api.get(`/api/posts/${ctx.route.params.id}`) }),
-  },
-]
+<ErrorBoundary
+  fallback={(e) => <p>出错了: {e.message}</p>}
+  onError={(e) => console.error(e)}
+>
+  {() => <Dashboard />}   {/* 必须用 thunk */}
+</ErrorBoundary>
+```
 
-app.use(router({ routes, notFound: NotFound, mode: 'hash', transition: 'page' }))
-// ctx.route.path / .params / .query / .data / .loading
+#### createPortal — 渲染到指定位置
 
-// 路由出口
-function AppShell() { return <main><RouteView /></main> }
+```tsx
+<Show when={showModal}>
+  {createPortal(<Modal />, document.body)}
+</Show>
 ```
 
-### DevTools
+#### wrap — 封装三方库为组件
 
-```ts
-import { enableDevtools } from 'weifuwu/client'
-if (import.meta.env.DEV) enableDevtools()
+```tsx
+const Chart = wrap('div', (el, props: { data: any }, ctx) => {
+  const chart = echarts.init(el)
+  chart.setOption(props.data)
+  effect(() => chart.setOption(props.data))
+  return () => chart.dispose()  // 卸载时自动清理
+})
 
-// 浏览器控制台：
-// __wefu__.inspect()     → 查看所有 signal
-// __wefu__.warnings()    → 切换开发警告
+// 使用：
+<Chart data={salesData} />
 ```
 
----
+#### createContext / extendCtx — 上下文扩展
 
-## From React to weifuwu/client
+```tsx
+// 类型安全的 provide/inject
+const ThemeCtx = createContext<string>('theme')
+ThemeCtx.provide(ctx, 'dark')
+const theme = ThemeCtx.inject(ctx)  // 'dark' | null
+
+// 中间件注入
+function myMiddleware(): AppMiddleware {
+  return (ctx) => extendCtx(ctx, { myField: 'hello' })
+}
+```
+
+### React 对照表
 
 | React | weifuwu/client |
 |-------|----------------|
 | `useState(0)` | `signal(0)` |
-| `useMemo(() => a * 2, [a])` | `computed(() => a.value * 2)` |
-| `useEffect(() => {...}, [])` | `effect(() => {...})` + `onCleanup(() => {...})` |
-| `{condition && <X/>}` | `<Show when={condition}><X/></Show>` |
-| `{items.map(i => <X/>)}` | `<For each={items}>{(i) => <X/>}</For>` |
-| `className={...}` | `class={...}` |
-| Context Provider | `ctx.provide(key, val)` / `createContext()` |
-| `useNavigate()` | `ctx.app.navigate(path)` |
+| `useMemo(() => a*2, [a])` | `computed(() => a.value * 2)` |
+| `useEffect(() => f, [])` | `onMount(f)` |
+| `useEffect(() => f, [dep])` | `effect(f)` |
+| `{cond && <X/>}` | `<Show when={cond}><X/></Show>` |
+| `{arr.map(i => <X/>)}` | `<For each={arr}>{(i) => <X/>}</For>` |
+| `Suspense` | `<Show when={!loading}>` |
+| `ErrorBoundary` | `<ErrorBoundary>` |
+| `createPortal` | `createPortal` |
+| `useNavigate()` | `ctx.app.navigate()` |
 | `useParams()` | `ctx.route.params` |
-| `fetch / axios` | `ctx.api.get/post/...` |
-| WebSocket | `ctx.socket.send/onMessage` |
+| `useFormik()` | `useForm()` |
+| `axios.get()` | `ctx.api.get()` |
+| `useSWR()` | `createResource()` |
+| `React.lazy()` | `lazy()` |
+| `useContext()` | `createContext()` |
+
+### 前端类型
 
-**What you DON'T need:**
-- No hooks rules — no `use` prefix, no rules-of-hooks
-- No virtual DOM — JSX creates real DOM directly
-- No dependency arrays — `effect()` auto-tracks
-- No state management library — signal is the state management
-- No Context.Provider component — just `ctx.provide/inject`
+`Signal`, `Component`, `WfuiContext`, `AppMiddleware`, `RouteDef`, `ApiClient`, `ApiOptions`, `ApiRequestOptions`, `AuthClient`, `AuthUser`, `AuthOptions`, `ResourceOptions`, `ResourceState`, `FormOptions`, `FormReturn`, `FormFieldBindings`, `FormValidators`, `LazyComponentOptions`, `LazyStatus`
 
 ---
 
-## Utils
+## 全栈模式
 
-| Import | Purpose |
-|--------|---------|
-| `requireRole('admin')` | Middleware factory: check `ctx.user.role` |
-| `createHub()` | WebSocket pub/sub |
-| `HttpError` | `throw new HttpError(msg, 404)` |
-| `trace()` | Request tracing |
+### 认证流程
 
----
+```ts
+// 后端
+app.post('/api/login', async (req, ctx) => {
+  const { email } = await req.json()
+  return Response.json({
+    token: 'jwt_' + Math.random().toString(36),
+    user: { id: 1, name: email.split('@')[0], email },
+  })
+})
 
-## Router (Backend)
+// 前端
+app.use(api({ baseURL: '' }))
+app.use(auth())
 
-```ts
-const app = new Router()
-app.get(path, ...handlers)
-app.post / put / delete / patch / head / options(path, ...handlers)
-app.all(path, ...handlers)
-app.ws(path, ...handler)          // WebSocket
-app.use(middleware)                // Global middleware
-app.mount(prefix, router)         // Sub-router
-app.plugin(fn)                    // Plugin
-app.onError(handler)              // Error handler
-app.routes()                      // Debug: list all routes
+// 登录
+const res = await ctx.api.post('/api/login', { email, password })
+ctx.auth.login(res.token, res.user)
 ```
 
----
+### 异步数据 + SSR
 
-## Project Structure
+```ts
+// 后端 — 同路径既支持 SSR 也支持 API
+app.get('/api/posts', async (req, ctx) => {
+  return Response.json(posts)
+})
 
+// 前端 — 客户端获取
+const [posts, { loading }] = createResource(
+  () => ctx.api.get('/api/posts')
+)
 ```
-src/
-├── index.ts              ← Entry, exports all modules
-├── types.ts              ← Context, Handler, Middleware types
-├── core/                 ← serve, router, ws, trace, logger
-├── middleware/           ← cors, helmet, compress, rate-limit, upload, static, sandbox
-├── user/                 ← User system (CRUD, JWT, requireRole)
-├── messager/             ← IM + AI conversation layer
-├── kb/                   ← RAG knowledge base
-├── ai/                   ← AI Agent (LLM, tools, RAG)
-├── cms/                  ← Content management
-├── base/                 ← Dynamic data engine
-├── postgres/             ← PostgreSQL client
-├── redis/                ← Redis client
-├── queue/                ← Job queue + cron
-├── graphql.ts            ← GraphQL
-├── hub.ts                ← WebSocket hub
-├── ui/                   ← ctx.ui.html / ctx.ui.js / ctx.ui.css
-├── client/               ← Frontend framework
-│   ├── index.ts          ← Exports all client APIs (33 exports)
-│   ├── signal.ts         ← Signal / effect / computed / batch / untrack
-│   ├── jsx-runtime.ts    ← JSX → DOM + types + Show/For/wrap/ErrorBoundary/Portal/Transition
-│   ├── app.ts            ← createApp / hydrate / middleware chain
-│   ├── router.ts         ← Route matching / RouteView / loader / transition
-│   ├── types.ts          ← WfuiContext / RouteDef / createContext
-│   ├── lib/
-│   │   ├── form.ts       ← useForm (validated forms)
-│   │   ├── model.ts      ← useModel (two-way binding)
-│   │   ├── resource.ts   ← createResource (async data)
-│   │   ├── css.ts        ← createStyles (scoped CSS)
-│   │   └── dev.ts        ← enableDevtools (dev warnings)
-│   ├── middleware/
-│   │   ├── api.ts        ← HTTP client → ctx.api
-│   │   ├── auth.ts       ← Auth → ctx.user/login/logout
-│   │   └── ws.ts         ← WebSocket → ctx.socket
-│   └── components/
-│       ├── LoginForm.tsx  ← Login/register
-│       ├── Chat.tsx       ← Real-time chat
-│       ├── Link.tsx       ← SPA navigation
-│       └── Transition.tsx ← Animated enter/leave
-└── test/                 ← 66 unit tests + 10 benchmarks
-
-apps/demo/                ← Full-stack demo
-├── server.ts             ← weifuwu server (user, kb, agent, messager 未演示)
-├── src/main.tsx          ← SPA + SSR hydrate demo pages
-├── public/               ← style.css (Tailwind + transition classes)
-└── tsconfig.json
-
-docker-compose.yml        ← postgres (pgvector) + redis
+
+### 嵌套布局 + 代码分割
+
+```tsx
+const routes = [
+  {
+    path: '/dashboard',
+    layout: DashboardLayout,   // 侧边栏等 UI 保持挂载
+    children: [
+      { path: '/overview', component: lazy(() => import('./Overview')) },
+      { path: '/settings', component: lazy(() => import('./Settings')) },
+    ],
+  },
+]
 ```
 
 ---
 
-## Development
+## 环境变量
+
+| 变量 | 默认 | 说明 |
+|------|------|------|
+| `DATABASE_URL` | `postgres://root:123456@localhost:5432/demo` | Postgres 连接字符串 |
+| `REDIS_URL` | `redis://localhost:6379` | Redis 连接字符串 |
+
+---
+
+## Demo
 
 ```bash
-docker compose up -d         # Start postgres + redis
-npm run build                # esbuild → dist/
-npm run typecheck            # tsc --noEmit
-npm test                     # Run all tests
+cd apps/demo
+node server.ts
+# http://localhost:3000
 ```
 
+Demo 包含：嵌套布局、signal 待办列表、useForm 表单、createResource 数据请求、api + auth 认证、WebSocket 实时通信。
+
 ---
 
-## Performance (Client Benchmarks)
+## 项目结构
 
-| Operation | Throughput |
-|-----------|-----------|
-| Signal creation | ~10,000 ops/ms |
-| Signal read/write | ~9,600 ops/ms |
-| Notify 10,000 effects | ~2,600 ops/ms |
-| batch merge 10,000 writes | ~0.6ms |
-| JSX div creation | ~200 ops/ms |
-| For render 10,000 items | ~109 ops/ms |
+```
+src/
+├── index.ts             入口，导出所有后端模块
+├── types.ts             Context, Handler, Middleware 等类型
+├── core/                Router, serve, WebSocket upgrade
+├── middleware/           cors, serveStatic
+├── postgres/            PostgreSQL 客户端
+├── redis/               Redis 客户端
+├── ui/                  SSR 渲染 + 动态编译
+├── graphql.ts           GraphQL
+├── client/
+│   ├── index.ts         前端导出入口
+│   ├── signal.ts        响应式系统
+│   ├── jsx-runtime.ts   JSX → DOM, Show/For/ErrorBoundary/Portal
+│   ├── router.ts        路由中间件 + RouteView
+│   ├── app.ts           createApp 应用实例
+│   ├── resource.ts      createResource 异步数据
+│   ├── form.ts          useForm 表单
+│   ├── lazy.ts          组件懒加载
+│   ├── types.ts         前端类型
+│   └── middleware/
+│       ├── ws.ts        WebSocket 客户端
+│       ├── api.ts       HTTP 客户端
+│       └── auth.ts      认证状态管理
+├── test/                测试
+apps/demo/               全栈 demo
+```
+
+```bash
+npm run build       # esbuild → dist/
+npm run typecheck   # tsc --noEmit
+npm test            # 运行所有测试
+```