weifuwu 0.32.1 → 0.33.1

package/README.md

@@ -1,325 +1,309 @@
 # weifuwu
 
-Web-standard HTTP microframework for Node.js — `(req, ctx) => Response`.
+**AI SaaS framework** — `(req, ctx) => Response`
 
 ```bash
 npm install weifuwu
 ```
 
+User system, instant messaging, RAG knowledge base, AI Agent, CMS, dynamic data storage. Configure environment variables and go.
+
+---
+
+## Quick Start
+
 ```ts
-import { serve, Router } from 'weifuwu'
+import { serve, Router, postgres, user, kb, agent, messager } from 'weifuwu'
+import { openai } from '@ai-sdk/openai'
 
 const app = new Router()
-app.get('/', () => new Response('Hello'))
-serve(app, { port: 3000 })
-```
-
-## Exports
+app.use(postgres())
+app.use(user())
+app.use(kb())
+app.use(messager())
+app.use(agent({
+  model: openai('deepseek-v4-flash', { baseURL: 'https://api.deepseek.com/v1' }),
+  knowledge: { search: async (q, ctx) => ctx.kb.search(q) },
+}))
 
-### Core
+app.post('/api/chat', async (req, ctx) => {
+  const { messages } = await req.json()
+  return ctx.agent.chatStreamResponse({ messages })
+})
 
-| Export | Description |
-|---|---|
-| `serve(app, opts?)` | Start HTTP server. Returns `Server` with `port`, `hostname`, `ready`, `close()`. |
-| `Router` | Trie-based HTTP router with WebSocket support and `plugin()` method. |
-| `HttpError` | `new HttpError(message, status)`. Throw to return that status code. |
-| `DEFAULT_MAX_BODY` | `10 * 1024 * 1024` (10MB). |
+serve(app, { port: 3000 })
+```
 
-### Router API
+### Environment Variables
 
-```ts
-const app = new Router()
+| Variable | Default | Used by |
+|----------|---------|---------|
+| `DATABASE_URL` | `postgres://root:123456@localhost:5432/demo` | `postgres()` |
+| `REDIS_URL` | `redis://localhost:6379` | `redis()` |
+| `JWT_SECRET` | — | `user()` |
+| `DASHSCOPE_API_KEY` | — | `kb()` (embedding) |
+| `DEEPSEEK_API_KEY` / `OPENAI_API_KEY` | — | `agent()` (LLM) |
+| `DEEPSEEK_MODEL` | `deepseek-v4-flash` | `agent()` |
 
-// HTTP methods
-app.get(path, ...handlers)
-app.post / put / delete / patch / head / options(path, ...handlers)
-app.all(path, ...handlers)    // any method
+---
 
-// WebSocket
-app.ws(path, ...middlewares, handler)
-// handler: { open?, message?, close?, error? }
+## Modules
 
-// Middleware & mounting
-app.use(middleware)           // global middleware
-app.mount(prefix, router)     // sub-router at prefix
-app.plugin(fn)                // extension: (app) => { app.get(), app.use(), ... }
-app.onError(handler)          // error handler: (error, req, ctx) => Response
-app.routes()                  // debug: list all registered routes
-
-// Path params
-app.get('/users/:id', (req, ctx) => {
-  ctx.params.id   // string
-  ctx.query.search // from ?search=...
-})
-```
+| Module | Import | Dependency | Purpose |
+|--------|--------|-----------|---------|
+| User | `user()` | `postgres()` | Auth, JWT, roles |
+| Messager | `messager()` | `postgres()`, `user()` | IM + AI conversation layer |
+| KB | `kb()` | `postgres()` | RAG knowledge base |
+| Agent | `agent()` | — | LLM chat, tool calling, streaming |
+| CMS | `cms()` | `postgres()`, `user()` | Blog, docs, changelog |
+| Base | `base()` | `postgres()`, `user()` | Dynamic data engine |
 
 ### Middleware
 
-| Export | Description |
-|---|---|
-| `cors(opts?)` | CORS headers. `origin`, `methods`, `headers`, `credentials`, `maxAge`. |
-| `helmet(opts?)` | Security headers: CSP, HSTS, X-Frame-Options, X-Content-Type-Options, etc. |
-| `compress(opts?)` | gzip / brotli / deflate response compression. |
-| `rateLimit(opts?)` | Sliding-window rate limiter. `windowMs`, `max`, `keyGenerator`, Redis backend. |
-| `logger(opts?)` | Request logging. `format: 'short' | 'combined' | 'json'`. |
-| `upload(opts?)` | Multipart file upload via `req.formData()`. Injects `ctx.parsed`. |
-| `serveStatic(root, opts?)` | Static file handler. `cacheControl`, `index`. |
-| `sandbox(opts?)` | Filesystem isolation for agent operations. `baseDir`, `timeout`, `isolateBy`. |
-| `auth(opts?)` | Authentication: JWT, session cookies, API keys. Injects `ctx.user`. |
-
-### Tracing
-
-| Export | Description |
-|---|---|
-| `currentTraceId()` | Current request's trace ID (AsyncLocalStorage). |
-| `currentTrace()` | Current trace context `{ traceId, startTime }`. |
-| `runWithTrace(id, fn)` | Run `fn` in a trace context. Auto-generates UUID if id is null. |
-| `traceElapsed()` | Milliseconds since trace start. |
-| `trace(opts?)` | Middleware that injects `ctx.trace`. |
-
-### Postgres
-
-```ts
-import { postgres, MIGRATIONS_TABLE } from 'weifuwu'
+| Import | Purpose |
+|--------|---------|
+| `cors()` | CORS headers |
+| `helmet()` | Security headers |
+| `compress()` | gzip / brotli / deflate |
+| `rateLimit()` | Sliding-window rate limiter |
+| `logger()` | Request logging |
+| `upload()` | Multipart file upload |
+| `serveStatic()` | Static files |
+| `sandbox()` | Filesystem isolation |
 
-const sql = postgres({ url: process.env.DATABASE_URL })
-app.use(sql)  // injects ctx.sql
+### Core
 
-const rows = await sql.sql`SELECT * FROM users WHERE id = ${id}`
+| Import | Purpose |
+|--------|---------|
+| `serve(app, opts?)` | Start HTTP server |
+| `Router` | Trie-based router + WebSocket |
+| `HttpError` | `throw new HttpError(msg, 404)` |
+| `trace()` | Request tracing |
+| `postgres()` | PostgreSQL client (`ctx.sql`) |
+| `redis()` | Redis client (`ctx.redis`) |
+| `queue()` | Job queue + cron |
+| `createHub()` | WebSocket pub/sub |
 
-// Migrations
-await sql.migrate({
-  '001_init': async (s) => await s`CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT)`,
-})
-```
+### Utilities
 
-### Redis
+| Import | Purpose |
+|--------|---------|
+| `requireRole('admin')` | Middleware: check `ctx.user.role` |
 
-```ts
-import { redis } from 'weifuwu'
+---
 
-const r = redis({ url: process.env.REDIS_URL })
-app.use(r)  // injects ctx.redis
-await r.redis.set('key', 'value')
-```
+## user
 
-### Queue & Cron
+Auth, registration, JWT, password management, roles.
 
 ```ts
-import { queue } from 'weifuwu'
+import { user, requireRole } from 'weifuwu'
 
-const q = queue()
-app.use(q)  // injects ctx.queue
+app.use(postgres())
+app.use(user({ secret: process.env.JWT_SECRET }))
 
-q.process('email', async (job) => {
-  await sendEmail(job.payload.to)
+// Register
+app.post('/api/register', async (req, ctx) => {
+  const result = await ctx.userModule.register(await req.json())
+  return Response.json(result)
 })
-
-q.cron('cleanup', '0 3 * * *', async () => {
-  await cleanupOldSessions()
+// Login
+app.post('/api/login', async (req, ctx) => {
+  const { email, password } = await req.json()
+  const result = await ctx.userModule.login(email, password)
+  if (!result) return new Response('Unauthorized', { status: 401 })
+  return Response.json(result)
 })
+// Current user
+app.get('/api/me', async (req, ctx) => {
+  if (!ctx.user) return new Response('Unauthorized', { status: 401 })
+  return Response.json(ctx.user)
+})
+// Admin only
+app.get('/api/admin/users', requireRole('admin'), async (req, ctx) => {
+  return Response.json(await ctx.userModule.listUsers())
+})
+```
 
-await q.add('email', { to: 'user@example.com' })
-await q.add('remind', {}, { delay: 60_000 })
-await q.add('report', {}, { schedule: '0 9 * * 1' })
+### ctx.userModule API
 
-q.run()  // start processing
-```
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `register(input)` | `{ user, token }` | Register |
+| `login(email, pw)` | `{ user, token } \| null` | Login |
+| `getUserById(id)` | `UserRecord \| null` | Get by ID |
+| `getUserByEmail(email)` | `UserRecord \| null` | Get by email |
+| `updateUser(id, input)` | `UserRecord \| null` | Update |
+| `changePassword(id, oldPw, newPw)` | `boolean` | Change password |
+| `deleteUser(id)` | `boolean` | Soft delete |
+| `listUsers(inactive?)` | `UserRecord[]` | List users |
+| `generateToken(user)` | `string` | Issue JWT |
+| `verifyToken(token)` | `TokenPayload \| null` | Verify JWT |
+| `refreshToken(token)` | `string \| null` | Refresh JWT |
 
-### WebSocket Hub
+### ctx.user
 
-```ts
-import { createHub } from 'weifuwu'
+Auto-resolved from `Authorization: Bearer` or `token` cookie.
 
-const hub = createHub()
-app.ws('/chat', {
-  open(ws, ctx) {
-    ctx.ws.join('lobby')
-    ctx.ws.json({ type: 'join' })
-  },
-  message(ws, ctx, data) {
-    ctx.ws.sendRoom('lobby', { text: data.toString() })
-  },
-})
+```ts
+interface User {
+  id: string
+  name: string
+  email: string
+  role: string
+  [key: string]: unknown
+}
 ```
 
-### GraphQL
+### requireRole
 
 ```ts
-import { graphql } from 'weifuwu'
+app.get('/admin', requireRole('admin'), handler)
+// No auth → 401, wrong role → 403
+```
 
-const gql = graphql((req, ctx) => ({
-  schema: `
-    type Query {
-      hello: String
-      user(id: ID!): User
-    }
-    type User {
-      id: ID
-      name: String
-    }
-  `,
-  resolvers: {
-    Query: {
-      hello: () => 'world',
-      user: (_, { id }) => ctx.sql`SELECT * FROM users WHERE id = ${id}`.then(r => r[0]),
-    },
-  },
-  graphiql: true,
-}))
+### Security
 
-app.mount('/graphql', gql)
-```
+- Password: scrypt + 32-byte random salt
+- Token: HMAC SHA-256, 7 day expiry
 
-### React SSR
+---
 
-> Requires `react >= 19`, `react-dom >= 19` (optional peerDependencies).
+## messager
 
-```bash
-npm install react react-dom
-```
+Instant messaging + AI conversation layer. Direct/group chat, message persistence, WebSocket push.
 
 ```ts
-// server.ts — the only file you need
-import { serve, Router } from 'weifuwu'
-import { react } from 'weifuwu/react'
+import { messager } from 'weifuwu'
 
-const app = new Router()
-  .use(trace())
-  .use(logger())
-  .plugin(react({
-    pages: {
-      '/':          './pages/Home.tsx',
-      '/users':     './pages/Users.tsx',
-      '/users/:id': './pages/UserDetail.tsx',
-    },
-    layout:   './layouts/Root.tsx',
-    notFound: './pages/NotFound.tsx',
-    tailwind: { entry: './styles/input.css' },
-  }))
+app.use(postgres())
+app.use(user())
+app.use(messager())
 
-app.get('/api/hello', () => Response.json({ message: 'hi' }))
-serve(app, { port: 3000 })
+// WebSocket — auto-join all user conversations
+app.ws('/ws', {
+  async open(ws, ctx) {
+    for (const c of await ctx.messager.getConversations()) {
+      ctx.ws.join(`conversation:${c.id}`)
+    }
+  },
+})
+
+// REST API
+app.post('/api/messages', async (req, ctx) => {
+  const { conversationId, body } = await req.json()
+  const msg = await ctx.messager.sendMessage(conversationId, body)
+  return Response.json(msg, { status: 201 })
+})
+
+app.get('/api/conversations/:id/messages', async (req, ctx) => {
+  const url = new URL(req.url)
+  return Response.json(await ctx.messager.getMessages(ctx.params.id, {
+    before: url.searchParams.get('before') || undefined,
+    limit: parseInt(url.searchParams.get('limit') || '50'),
+  }))
+})
 ```
 
-**One `react()` call handles:** SSR rendering, routing, data loading, Tailwind CSS, client bundle auto-generation, and error pages. No `client.ts`, `routes.ts`, or manual middleware setup needed.
+### ctx.messager API
 
-#### Page components
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `createDirectConversation(userId)` | `Conversation` | Create/reuse DM |
+| `createGroupConversation(title, userIds)` | `Conversation` | Create group |
+| `sendMessage(convId, body)` | `Message` | Send, auto-broadcast to `conversation:{id}` room |
+| `getMessages(convId, opts?)` | `Message[]` | Cursor pagination |
+| `editMessage(msgId, body)` | `Message \| null` | Edit (24h window) |
+| `deleteMessage(msgId)` | `boolean` | Soft delete |
+| `getConversations()` | `Conversation[]` | List with unread + last message |
+| `getConversation(id)` | `Conversation \| null` | Get detail |
+| `markRead(convId)` | `void` | Mark as read |
+| `getUnreadCount()` | `{ total, byConversation }` | Unread stats |
+| `addParticipants(convId, userIds)` | `void` | Add members |
+| `removeParticipant(convId, userId?)` | `boolean` | Leave / kick |
 
-```tsx
-// pages/UserDetail.tsx
-import type { Context } from 'weifuwu'
-import { HttpError } from 'weifuwu'
-import { useServerData } from 'weifuwu/react'
+### Storage
 
-export async function loader(ctx: Context) {
-  const user = await db.find(ctx.params.id)
-  if (!user) throw new HttpError('Not found', 404)
-  return { user }
-}
+3 tables: `conversations` / `participants` / `messages`. Auto-migration.
 
-export default function UserDetailPage() {
-  const { user } = useServerData<{ user: User }>()
-  return (
-    <div>
-      <title>{`${user.name} — My App`}</title>
-      <h1>{user.name}</h1>
-      <p>{user.email}</p>
-    </div>
-  )
-}
-```
+### AI Conversations
 
-- `export async function loader(ctx)` — runs on the server, returns data for `useServerData()`
-- `throw new HttpError('Not found', 404)` — renders the NotFound page with correct status
-- `<title>` auto-hoists to `<head>` via React 19
-- `export default` is auto-detected; named exports work too
+messager + agent = ChatGPT foundation. Messager handles sessions + push, agent handles LLM generation.
 
-#### Layout with shared data
+---
 
-```tsx
-// layouts/Root.tsx
-export async function loader(ctx: Context) {
-  return { currentUser: await getCurrentUser(ctx) }
-}
+## kb
 
-export function Root({ children }: { children: ReactNode }) {
-  const { currentUser } = useServerData()
-  return (
-    <>
-      <nav>
-        <a href="/">Home</a>
-        <a href="/users">Users</a>
-        <span>{currentUser?.name}</span>
-      </nav>
-      <main>{children}</main>
-    </>
-  )
-}
-```
+RAG knowledge base. Import docs → auto-chunk → DashScope embedding → pgvector storage → semantic search.
 
-Layout `loader` data merges with page data. Page loader overrides same keys.
+```ts
+import { kb } from 'weifuwu'
 
-#### Data flow
+app.use(postgres())
+app.use(kb())
 
-```
-layout loader  ──┐
-                  ├──→  merge → useServerData()  ──→  Layout + Page
-page loader   ───┘
-```
+// Import
+app.post('/api/kb/import', async (req, ctx) => {
+  const { title, content } = await req.json()
+  const result = await ctx.kb.importText(title, content)
+  return Response.json(result, { status: 201 })
+})
 
-#### Client-side SPA
+// Search
+app.post('/api/kb/search', async (req, ctx) => {
+  const { query } = await req.json()
+  return Response.json(await ctx.kb.search(query, { limit: 5 }))
+})
+```
 
-Every page is automatically code-split into a separate chunk. On first visit the server renders HTML and the client hydrates. Subsequent navigations intercept `<a>` clicks, `import()` the page chunk, and fetch fresh server data — all automatic, zero config.
+### ctx.kb API
 
-#### Streaming SSR
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `importText(title, text, opts?)` | `{ document, chunks }` | Import → chunk → embed → store |
+| `importDocuments(docs)` | `Document[]` | Batch import |
+| `search(query, opts?)` | `SearchResult[]` | Semantic search (cosine) |
+| `list()` | `Document[]` | List documents |
+| `get(id)` | `Document \| null` | Get document |
+| `getChunks(documentId)` | `Chunk[]` | Get chunks |
+| `delete(id)` | `boolean` | Delete + cascade chunks |
 
-```tsx
-import { Suspense, use } from 'react'
+### Configuration
 
-export default function StreamingPage() {
-  return (
-    <div>
-      <h1>Instant shell</h1>
-      <Suspense fallback={<Spinner />}>
-        <SlowData promise={fetchSlowData()} />
-      </Suspense>
-    </div>
-  )
-}
+```ts
+// Default: DashScope text-embedding-v4 (env: DASHSCOPE_API_KEY)
+app.use(kb())
+
+// Custom embedding
+app.use(kb({
+  embed: async (text) => { /* return number[] */ },
+  dimensions: 1536,
+  chunkSize: 512,    // tokens
+  chunkOverlap: 64,
+}))
 ```
 
-`<Suspense>` boundaries stream to the browser as data resolves.
-
-| Feature | Description |
-|---|---|
-| `react({ pages, layout, notFound, tailwind })` | One call: SSR + routing + client bundle + error handling |
-| `export async function loader(ctx)` | Server-side data loading, auto-detected by the framework |
-| `useServerData<T>()` | Type-safe access to loader data in any component |
-| `Link` | `<a>` that does SPA navigation on the client |
-| `ErrorBoundary` | Catches render errors on server and client |
-| `<title>`, `<meta>` | Auto-hoisted to `<head>` via React 19 |
-| `<Suspense>` | Streaming SSR, works out of the box |
-| `client: false` | Disable client JS for static SSR only |
-
-**Import paths:**
+### Integration with Agent
 
 ```ts
-// Server-side
-import { react, Link, ErrorBoundary, useServerData } from 'weifuwu'
-
-// Client-side (for custom advanced setups)
-import { createBrowserRouter, hydrate, navigate } from 'weifuwu/react/client'
+app.use(agent({
+  model: openai('deepseek-v4-flash', { baseURL: 'https://api.deepseek.com/v1' }),
+  knowledge: {
+    search: async (query, ctx) => ctx.kb.search(query),
+  },
+}))
 ```
 
-See [examples/react-ssr/](examples/react-ssr/) for the full demo.
+### Storage
+
+- `kb_documents` — document metadata
+- `kb_chunks` — chunk content + VECTOR(1536) + TSVECTOR GIN index
 
-### AI Agent
+---
 
-> Requires `ai` (Vercel AI SDK). Install with a model provider:
-> ```bash
-> npm install ai @ai-sdk/openai
-> ```
+## agent
+
+AI Agent — LLM chat, tool calling, RAG, streaming.
 
 ```ts
 import { agent } from 'weifuwu'
@@ -328,17 +312,10 @@ import { tool } from 'ai'
 import { z } from 'zod'
 
 app.use(agent({
-  model: openai('gpt-4o'),
+  model: openai('deepseek-v4-flash', { baseURL: 'https://api.deepseek.com/v1' }),
   system: 'You are a helpful assistant.',
   knowledge: {
-    // RAG — search a knowledge base before each response
-    search: async (query, ctx) => {
-      const { embeddings } = await embedModel.doEmbed({ values: [query] })
-      return ctx.sql`
-        SELECT content, 1 - (embedding <=> ${embeddings[0]}::vector) AS score
-        FROM docs ORDER BY embedding <=> ${embeddings[0]}::vector LIMIT 3
-      `
-    },
+    search: async (query, ctx) => ctx.kb.search(query),
   },
   tools: {
     getWeather: tool({
@@ -350,198 +327,293 @@ app.use(agent({
   maxSteps: 5,
 }))
 
+// Streaming
 app.post('/api/chat', async (req, ctx) => {
   const { messages } = await req.json()
   return ctx.agent.chatStreamResponse({ messages })
 })
+
+// Non-streaming
+app.post('/api/chat/sync', async (req, ctx) => {
+  const { prompt } = await req.json()
+  const text = await ctx.agent.chat(prompt)
+  return Response.json({ text })
+})
 ```
 
-**`agent()` handles:** multi-turn conversations, automatic tool-calling loops (maxSteps), knowledge retrieval (RAG) injected into the system prompt, and SSE streaming compatible with `useChat` from `@ai-sdk/react`.
+### ctx.agent API
+
+| Method | Description |
+|--------|-------------|
+| `chat(prompt, opts?)` | Non-streaming, returns text |
+| `chatStreamResponse({ messages })` | SSE stream (compatible with `useChat`) |
+
+### Default Model
+
+- LLM: DeepSeek-V4-Flash (via `@ai-sdk/openai` + `baseURL: 'https://api.deepseek.com/v1'`)
+- Override with `DEEPSEEK_MODEL` env
+- API key via `DEEPSEEK_API_KEY` or `OPENAI_API_KEY` env
+
+### Features
 
 | Feature | Description |
-|---|---|
-| `ctx.agent.chat(prompt, opts?)` | Non-streaming chat with tool calling and RAG |
-| `ctx.agent.chatStreamResponse({ messages })` | SSE streaming response (useChat-compatible) |
-| `knowledge.search` | User-defined RAG callback — query any data source via `ctx` |
-| `tools` | Tool definitions (from `ai` package). Executed in automatic loops |
-| `agents` | Named sub-agents with different models/tools |
-| `sandbox: true` | Auto-integrate with `ctx.sandbox` for file operations |
-| `store` | Session persistence (save/load conversation history) |
+|---------|-------------|
+| `knowledge.search` | RAG callback, auto-injected into system prompt |
+| `tools` | Tool definitions, auto-loop (maxSteps) |
+| `sandbox: true` | Integrates with `ctx.sandbox` |
+| `store` | Session persistence (save/load) |
+| `agents` | Multi-agent orchestration |
 
-### Auth
+---
 
-JWT extraction priority: `cookie` → `Authorization: Bearer` → `?access_token=`. All callbacks receive `ctx` so `ctx.sql` is directly available.
+## cms
 
-```ts
-import { auth } from 'weifuwu'
+Content management — blog, docs, changelog.
 
-// JWT — cookie, header, or ?access_token=
-app.use(auth({ jwt: { secret: process.env.JWT_SECRET } }))
+```ts
+import { cms, requireRole } from 'weifuwu'
 
-// Session cookie — loadUser gets ctx
-app.use(auth({
-  session: {
-    secret: '...',
-    loadUser: async (data, ctx) => ctx.sql`SELECT * FROM users WHERE id = ${data.userId}`,
-  },
-}))
+app.use(postgres())
+app.use(user())
+app.use(cms())
 
-// API key — header or ?api_key=
-app.use(auth({ apiKey: {
-  query: 'api_key',
-  validate: async (key, ctx) => ctx.sql`SELECT * FROM users WHERE api_key = ${key}`,
-} }))
+// Public
+app.get('/api/posts', async (req, ctx) => {
+  return Response.json(await ctx.cms.list({ type: 'post', status: 'published' }))
+})
+app.get('/api/posts/:slug', async (req, ctx) => {
+  const post = await ctx.cms.get(ctx.params.slug)
+  if (!post) return new Response('Not found', { status: 404 })
+  return Response.json(post)
+})
 
-// ctx.user is now available
-app.get('/me', (req, ctx) => {
-  if (!ctx.user) return new Response('Unauthorized', { status: 401 })
-  return Response.json(ctx.user)
+// Admin
+app.post('/api/admin/posts', requireRole('admin'), async (req, ctx) => {
+  const post = await ctx.cms.create(await req.json())
+  return Response.json(post, { status: 201 })
+})
+app.patch('/api/admin/posts/:id', requireRole('admin'), async (req, ctx) => {
+  const post = await ctx.cms.update(ctx.params.id, await req.json())
+  if (!post) return new Response('Not found', { status: 404 })
+  return Response.json(post)
 })
 ```
 
-Supports JWT (HS256 via cookie or Authorization header), signed session cookies with `loadUser` callback, and API key validation. All are optional — requests proceed without a user identity unless handlers enforce it.
+### ctx.cms API
 
-### Sandbox
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `create(input)` | `Content` | Create (admin) |
+| `get(slug)` | `Content \| null` | Get by slug |
+| `getById(id)` | `Content \| null` | Get by ID |
+| `update(id, input)` | `Content \| null` | Update (admin) |
+| `delete(id)` | `boolean` | Delete (admin) |
+| `list(opts?)` | `Content[]` | List with cursor |
+| `publish(id)` | `Content \| null` | Publish (admin) |
+| `unpublish(id)` | `Content \| null` | Unpublish (admin) |
+| `listTags()` | `TagWithCount[]` | List tags |
+| `createTag(name)` | `Tag` | Create tag |
 
-```ts
-import { sandbox } from 'weifuwu'
+### Features
 
-app.use(sandbox({
-  baseDir: '/tmp/workspaces',
-  timeout: 30000,
-  isolateBy: 'user',  // one directory per ctx.user.id
-}))
+- Types: post / page / doc / changelog (any string)
+- Status: draft / published / archived
+- Slug: auto-generated, unique per type
+- Tags: many-to-many, auto-created
+- Tree: parent_id for hierarchy
+- Auth: non-admin users see published only
 
-// ctx.sandbox provides isolated file + exec operations
-await ctx.sandbox.writeFile('hello.txt', 'world')
-const content = await ctx.sandbox.readFile('hello.txt')
-const { stdout } = await ctx.sandbox.exec('ls -la')
-await ctx.sandbox.destroy()  // clean up workspace
-```
+---
 
-All file paths are validated — escapes (`../`) are rejected. `exec()` enforces timeout and sets `HOME` to the workspace directory. When `isolateBy: 'user'` is set, each user gets their own directory under `baseDir`.
+## base
 
-### Types
+Dynamic data storage engine — let users define their own data structures (like Airtable).
 
-| Export | Description |
-|---|---|
-| `Context` | `{ params, query, mountPath?, [key: string] }` |
-| `Handler<T>` | `(req: Request, ctx: T) => Response \| Promise<Response>` |
-| `Middleware` | `(req, ctx, next) => Response \| Promise<Response>` |
-| `WebSocketHandler` | `{ open?, message?, close?, error? }` |
-| `HttpError` | `Error` subclass with `.status: number` |
-| `Closeable` | `{ close(): Promise<void> }` |
-| `Server` | `{ close, port, hostname, ready }` |
-| `ServeOptions` | `{ port, hostname, signal, maxBodySize, timeout, keepAliveTimeout, headersTimeout, shutdown }` |
+```ts
+import { base } from 'weifuwu'
 
-## Handler / Middleware patterns
+app.use(postgres())
+app.use(user())
+app.use(base())
 
-```ts
-// Handler — standard Web API
-app.get('/api/data', (req, ctx) => {
-  const q = ctx.query.q
-  return Response.json({ q })
+// Define schema
+app.post('/api/bases', async (req, ctx) => {
+  const b = await ctx.base.create(await req.json())
+  return Response.json(b, { status: 201 })
 })
 
-// Async
-app.get('/db/users', async (req, ctx) => {
-  const rows = await ctx.sql`SELECT * FROM users`
-  return Response.json(rows)
+// CRUD
+app.post('/api/bases/:id/:table', async (req, ctx) => {
+  const row = await ctx.base.insert(ctx.params.id, ctx.params.table, await req.json())
+  return Response.json(row, { status: 201 })
 })
 
-// Throwing HttpError
-app.get('/item/:id', (req, ctx) => {
-  const item = db.get(ctx.params.id)
-  if (!item) throw new HttpError('Not found', 404)
-  return Response.json(item)
+app.get('/api/bases/:id/:table', async (req, ctx) => {
+  const url = new URL(req.url)
+  return Response.json(await ctx.base.query(ctx.params.id, ctx.params.table, {
+    filter: url.searchParams.get('filter') ? JSON.parse(url.searchParams.get('filter')!) : undefined,
+    limit: parseInt(url.searchParams.get('limit') || '50'),
+  }))
 })
+```
 
-// Middleware
-app.use(async (req, ctx, next) => {
-  const start = Date.now()
-  const res = await next(req, ctx)
-  console.log(`${req.method} ${req.url} ${Date.now() - start}ms`)
-  return res
-})
+### ctx.base API
 
-// Error handler
-app.onError((err, req, ctx) => {
-  if (err instanceof HttpError) {
-    return Response.json({ error: err.message }, { status: err.status })
-  }
-  return new Response('Internal error', { status: 500 })
-})
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `create({ name, tables })` | `BaseDef` | Create database |
+| `defineTable(baseId, schema)` | `BaseDef` | Add table |
+| `updateTable(baseId, name, schema)` | `BaseDef \| null` | Update table |
+| `removeTable(baseId, name)` | `BaseDef \| null` | Remove table |
+| `insert(baseId, table, data)` | `Row` | Insert row |
+| `getRow(baseId, table, id)` | `Row \| null` | Get row |
+| `updateRow(baseId, table, id, data)` | `Row \| null` | Update row |
+| `deleteRow(baseId, table, id)` | `boolean` | Delete row |
+| `query(baseId, table, opts?)` | `Row[]` | Query (filter/sort/limit/offset) |
+| `search(baseId, table, field, query)` | `Row[]` | Full-text search |
+| `similaritySearch(baseId, table, field, vector)` | `Row[]` | Vector search |
+| `list()` / `get(id)` / `getBySlug(slug)` / `delete(id)` | — | Manage databases |
+
+### Architecture
+
+Fixed Slot: a single `base_data` table with ~120 physical columns:
+
+| Type | Count | PG Type |
+|------|:-----:|:--------:|
+| text001..064 | 64 | TEXT |
+| number001..032 | 32 | DOUBLE PRECISION |
+| date001..008 | 8 | TIMESTAMPTZ |
+| vector001..004 | 4 | VECTOR(1536) |
+| search001..004 | 4 | TEXT |
+| ext | 1 | JSONB (overflow) |
+
+Field name → physical column mapping stored in `base_column_map`. Fields beyond the physical columns overflow to ext JSONB.
+
+pgvector auto-detected (included in docker image).
+
+---
+
+---
+
+## Router
+
+```ts
+const app = new Router()
+
+// HTTP
+app.get(path, ...handlers)
+app.post / put / delete / patch / head / options(path, ...handlers)
+app.all(path, ...handlers)
+
+// WebSocket
+app.ws(path, ...middlewares, handler)
+// handler: { open?, message?, close?, error? }
+
+// Middleware & mounting
+app.use(middleware)
+app.mount(prefix, router)
+app.plugin(fn)
+app.onError(handler)
+app.routes()  // debug: list all routes
 ```
 
-## Complete example
+---
+
+## Middleware
 
 ```ts
-import { serve, Router, cors, helmet, compress, logger, trace, rateLimit, postgres, redis, auth, sandbox, HttpError } from 'weifuwu'
-import { agent } from 'weifuwu/agent'
-import { react } from 'weifuwu/react'
-import { openai } from '@ai-sdk/openai'
+import { cors, helmet, compress, rateLimit, logger, upload, serveStatic, sandbox } from 'weifuwu'
+
+app.use(cors({ origin: '*' }))
+app.use(helmet())
+app.use(compress())
+app.use(rateLimit({ max: 100 }))
+app.use(logger({ format: 'short' }))
+app.use(upload())
+app.use(serveStatic('./public'))
+app.use(sandbox({ baseDir: '/tmp/workspaces' }))
+```
 
-const app = new Router()
-  .use(trace())
-  .use(logger())
-  .use(cors())
-  .use(helmet())
-  .use(compress())
-  .use(postgres())
-  .use(redis())
-  .use(auth({ jwt: { secret: process.env.JWT_SECRET! } }))
-  .use(sandbox({ isolateBy: 'user' }))
-  .use(agent({
-    model: openai('gpt-4o'),
-    system: 'You are a helpful assistant.',
-    knowledge: {
-      search: async (q, ctx) => ctx.sql`...`,
-    },
-    sandbox: true,
-  }))
-  .plugin(react({ pages: { '/': './Chat.tsx' }, layout: './Layout.tsx', tailwind: {} }))
+---
 
-app.post('/api/chat', async (req, ctx) => {
-  if (!ctx.user) return new Response('Unauthorized', { status: 401 })
-  const { messages } = await req.json()
-  return ctx.agent.chatStreamResponse({ messages })
-})
+## Postgres
 
-serve(app, { port: 3000 })
+```ts
+import { postgres } from 'weifuwu'
+
+const sql = postgres()
+app.use(sql)  // → ctx.sql
+
+await sql.sql`SELECT * FROM users WHERE id = ${id}`
+await sql.sql.begin(async (sql) => { /* transaction */ })
+```
+
+Reads `DATABASE_URL` env. Supports migrations, transactions, connection pool stats.
+
+---
+
+## Redis
+
+```ts
+import { redis } from 'weifuwu'
+
+const r = redis()
+app.use(r)  // → ctx.redis
+await r.redis.set('key', 'value')
+```
+
+Reads `REDIS_URL` env (default: `redis://localhost:6379`).
+
+---
+
+## Queue & Cron
+
+```ts
+import { queue } from 'weifuwu'
+
+const q = queue()
+app.use(q)  // → ctx.queue
+
+q.process('email', async (job) => { await sendEmail(job.payload) })
+q.cron('cleanup', '0 3 * * *', () => cleanup())
+await q.add('email', { to: 'user@example.com' })
+await q.add('remind', {}, { delay: 60_000 })
+q.run()
 ```
 
+---
+
 ## Project Structure
 
 ```
-weifuwu/
-├── package.json
-├── tsconfig.json
-├── docker-compose.yml      ← postgres + redis for tests
-├── scripts/
-│   ├── build.mjs
-│   └── release.mjs
-├── src/
-│   ├── index.ts
-│   ├── types.ts
-│   ├── core/               ← serve, router, ws, trace, logger
-│   ├── middleware/          ← cors, helmet, compress, rate-limit, static, upload
-│   ├── ai/                  ← AI + agent middleware
-│   ├── postgres/
-│   ├── redis/
-│   ├── react/              ← react SSR (render, navigation, client)
-│   ├── queue/              ← cron, index, types
-│   ├── graphql.ts
-│   ├── hub.ts
-│   └── test/               ← 131 tests (18 files)
-├── examples/
-│   └── react-ssr/          ← full SPA demo
-└── dist/
+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 (chunking, embedding, vector search)
+├── ai/                  ← AI Agent (LLM, tools, RAG)
+├── cms/                 ← Content management (blog, docs, changelog)
+├── base/                ← Dynamic data engine (Fixed Slot)
+├── postgres/            ← PostgreSQL client
+├── redis/               ← Redis client
+├── queue/               ← Job queue + cron
+├── graphql.ts           ← GraphQL
+├── hub.ts               ← WebSocket hub
+└── test/                ← 281 tests
+
+docker-compose.yml       ← postgres (pgvector) + redis
 ```
 
+---
+
 ## Development
 
 ```bash
-npm run build          # esbuild → dist/index.js
-npm run typecheck      # tsc --noEmit
-npm test              # 131 tests (requires docker compose)
+docker compose up -d         # Start postgres + redis
+npm run build                # esbuild → dist/
+npm run typecheck            # tsc --noEmit
+npm test                     # 281 tests
 ```