weifuwu 0.32.0 → 0.33.0

package/README.md

@@ -1,325 +1,309 @@
 # weifuwu
 
-Web-standard HTTP microframework for Node.js — `(req, ctx) => Response`.
+**AI SaaS 框架** — `(req, ctx) => Response`
 
 ```bash
 npm install weifuwu
 ```
 
+用户系统、即时消息、RAG 知识库、AI Agent、内容管理、动态数据存储。配好环境变量就能跑。
+
+---
+
+## 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
+### 环境变量
 
-```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()` | 注册、登录、JWT、角色 |
+| Messager | `messager()` | `postgres()`, `user()` | 即时消息、AI 对话交互层 |
+| KB | `kb()` | `postgres()` | RAG 知识库、分片、向量搜索 |
+| Agent | `agent()` | — | LLM 对话、工具调用、流式输出 |
+| CMS | `cms()` | `postgres()`, `user()` | 博客、文档、公告 |
+| Base | `base()` | `postgres()`, `user()` | 动态数据存储引擎 |
 
 ### 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
+| 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 |
 
-```ts
-import { postgres, MIGRATIONS_TABLE } from 'weifuwu'
+### Core
 
-const sql = postgres({ url: process.env.DATABASE_URL })
-app.use(sql)  // injects ctx.sql
+| 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 |
 
-const rows = await sql.sql`SELECT * FROM users WHERE id = ${id}`
+### Utilities
 
-// Migrations
-await sql.migrate({
-  '001_init': async (s) => await s`CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT)`,
-})
-```
+| Import | Purpose |
+|--------|---------|
+| `requireRole('admin')` | Middleware: check `ctx.user.role` |
 
-### Redis
+---
 
-```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
+身份认证、注册登录、JWT、密码管理。
 
 ```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)
+// 注册
+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()
+// 登录
+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)
 })
+// 当前用户
+app.get('/api/me', async (req, ctx) => {
+  if (!ctx.user) return new Response('Unauthorized', { status: 401 })
+  return Response.json(ctx.user)
+})
+// 仅管理员
+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 }` | 注册 |
+| `login(email, pw)` | `{ user, token } \| null` | 登录 |
+| `getUserById(id)` | `UserRecord \| null` | 查用户 |
+| `getUserByEmail(email)` | `UserRecord \| null` | 查邮箱 |
+| `updateUser(id, input)` | `UserRecord \| null` | 更新 |
+| `changePassword(id, oldPw, newPw)` | `boolean` | 改密码 |
+| `deleteUser(id)` | `boolean` | 软删除 |
+| `listUsers(inactive?)` | `UserRecord[]` | 用户列表 |
+| `generateToken(user)` | `string` | 签发 JWT |
+| `verifyToken(token)` | `TokenPayload \| null` | 验证 JWT |
+| `refreshToken(token)` | `string \| null` | 刷新 JWT |
 
-### WebSocket Hub
+### ctx.user
 
-```ts
-import { createHub } from 'weifuwu'
+由中间件自动从 `Authorization: Bearer` 或 `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      // 'user' | 'admin' | ...
+  [key: string]: unknown
+}
 ```
 
-### GraphQL
+### requireRole
 
 ```ts
-import { graphql } from 'weifuwu'
+app.get('/admin', requireRole('admin'), handler)
+// 未登录 → 401，角色不匹配 → 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,
-}))
+### 安全
 
-app.mount('/graphql', gql)
-```
+- 密码：scrypt + 随机 32 字节盐
+- 令牌：HMAC SHA-256，7 天过期
 
-### React SSR
+---
 
-> Requires `react >= 19`, `react-dom >= 19` (optional peerDependencies).
+## messager
 
-```bash
-npm install react react-dom
-```
+即时消息 + AI 对话交互层。单聊、群聊、消息持久化、WebSocket 实时推送。
 
 ```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 — 自动加入用户的所有会话
+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` | 创建/复用私聊 |
+| `createGroupConversation(title, userIds)` | `Conversation` | 建群 |
+| `sendMessage(convId, body)` | `Message` | 发消息，自动广播到 `conversation:{id}` 房间 |
+| `getMessages(convId, opts?)` | `Message[]` | 游标分页 |
+| `editMessage(msgId, body)` | `Message \| null` | 编辑（24h 内） |
+| `deleteMessage(msgId)` | `boolean` | 软删除 |
+| `getConversations()` | `Conversation[]` | 会话列表（含未读、最后消息预览） |
+| `getConversation(id)` | `Conversation \| null` | 会话详情 |
+| `markRead(convId)` | `void` | 标记已读 |
+| `getUnreadCount()` | `{ total, byConversation }` | 未读统计 |
+| `addParticipants(convId, userIds)` | `void` | 加人 |
+| `removeParticipant(convId, userId?)` | `boolean` | 退出/踢出 |
 
-```tsx
-// pages/UserDetail.tsx
-import type { Context } from 'weifuwu'
-import { HttpError } from 'weifuwu'
-import { useServerData } from 'weifuwu/react'
+### 存储
 
-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 张表：`conversations` / `participants` / `messages`。自动建表迁移。
 
-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 对话
 
-- `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 基础架构。messager 管会话和推送，agent 管 LLM 生成。
 
-#### 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 知识库。文档导入 → 自动分片 → DashScope embedding → pgvector 存储 → 语义搜索。
 
-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   ───┘
-```
+// 导入
+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
+// 搜索
+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 }` | 导入 → 分片 → embedding → 存储 |
+| `importDocuments(docs)` | `Document[]` | 批量导入 |
+| `search(query, opts?)` | `SearchResult[]` | 语义搜索（cosine 相似度） |
+| `list()` | `Document[]` | 文档列表 |
+| `get(id)` | `Document \| null` | 文档详情 |
+| `getChunks(documentId)` | `Chunk[]` | 分片列表 |
+| `delete(id)` | `boolean` | 删除文档 + 级联删除分片 |
 
-```tsx
-import { Suspense, use } from 'react'
+### 配置
 
-export default function StreamingPage() {
-  return (
-    <div>
-      <h1>Instant shell</h1>
-      <Suspense fallback={<Spinner />}>
-        <SlowData promise={fetchSlowData()} />
-      </Suspense>
-    </div>
-  )
-}
+```ts
+// 默认：DashScope text-embedding-v4（环境变量 DASHSCOPE_API_KEY）
+app.use(kb())
+
+// 自定义 embedding
+app.use(kb({
+  embed: async (text) => { /* 返回 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:**
+### 与 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.
+### 存储
+
+- `kb_documents` — 原始文档元数据
+- `kb_chunks` — 分片内容 + VECTOR(1536) + TSVECTOR GIN 索引
 
-### AI Agent
+---
 
-> Requires `ai` (Vercel AI SDK). Install with a model provider:
-> ```bash
-> npm install ai @ai-sdk/openai
-> ```
+## agent
+
+AI Agent — LLM 对话、工具调用、RAG、流式输出。
 
 ```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,193 +327,292 @@ app.use(agent({
   maxSteps: 5,
 }))
 
+// 流式对话
 app.post('/api/chat', async (req, ctx) => {
   const { messages } = await req.json()
   return ctx.agent.chatStreamResponse({ messages })
 })
+
+// 非流式对话
+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?)` | 非流式对话，返回文本 |
+| `chatStreamResponse({ messages })` | SSE 流式回复（兼容 `useChat`） |
+
+### 默认模型
+
+- LLM: DeepSeek-V4-Flash（`@ai-sdk/openai` + `baseURL: 'https://api.deepseek.com/v1'`）
+- 环境变量 `DEEPSEEK_MODEL` 可覆盖模型名称
+- 环境变量 `DEEPSEEK_API_KEY` 或 `OPENAI_API_KEY` 为 API 密钥
+
+### 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 回调，自动注入 system prompt |
+| `tools` | 工具定义，自动循环调用（maxSteps） |
+| `sandbox: true` | 与 `ctx.sandbox` 集成（文件读写） |
+| `store` | 对话持久化（save/load） |
+| `agents` | 多 Agent 编排 |
 
-### Auth
+---
 
-```ts
-import { auth } from 'weifuwu'
+## cms
 
-// JWT
-app.use(auth({ jwt: { secret: process.env.JWT_SECRET } }))
+内容管理 — 博客、文档、公告、更新日志。
 
-// Session cookie
-app.use(auth({
-  session: {
-    secret: '...',
-    loadUser: async (data) => db.findUser(data.userId),
-  },
-}))
+```ts
+import { cms, requireRole } from 'weifuwu'
 
-// API key
-app.use(auth({ apiKey: { validate: async (key) => db.findByApiKey(key) } }))
+app.use(postgres())
+app.use(user())
+app.use(cms())
 
-// ctx.user is now available
-app.get('/me', (req, ctx) => {
-  if (!ctx.user) return new Response('Unauthorized', { status: 401 })
-  return Response.json(ctx.user)
+// 公开：已发布的文章
+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)
+})
+
+// 管理端
+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` | 创建（admin） |
+| `get(slug)` | `Content \| null` | 按 slug 获取 |
+| `getById(id)` | `Content \| null` | 按 id 获取 |
+| `update(id, input)` | `Content \| null` | 更新（admin） |
+| `delete(id)` | `boolean` | 删除（admin） |
+| `list(opts?)` | `Content[]` | 列表（游标分页） |
+| `publish(id)` | `Content \| null` | 发布（admin） |
+| `unpublish(id)` | `Content \| null` | 下线（admin） |
+| `listTags()` | `TagWithCount[]` | 标签列表 |
+| `createTag(name)` | `Tag` | 创建标签 |
 
-```ts
-import { sandbox } from 'weifuwu'
+### Features
 
-app.use(sandbox({
-  baseDir: '/tmp/workspaces',
-  timeout: 30000,
-  isolateBy: 'user',  // one directory per ctx.user.id
-}))
+- 内容类型：post / page / doc / changelog（任意字符串）
+- 状态：draft / published / archived
+- Slug：自动生成，同类型唯一
+- 标签：多对多，自动创建
+- 树形：parent_id 支持层级
+- 鉴权：非管理员只能读已发布
 
-// 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
+动态数据存储引擎 — 让用户自定义数据结构（类似 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 })
+// 定义数据结构
+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)
+// 增删改查
+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` | 创建数据库 |
+| `defineTable(baseId, schema)` | `BaseDef` | 加表 |
+| `updateTable(baseId, name, schema)` | `BaseDef \| null` | 改表 |
+| `removeTable(baseId, name)` | `BaseDef \| null` | 删表 |
+| `insert(baseId, table, data)` | `Row` | 插入行 |
+| `getRow(baseId, table, id)` | `Row \| null` | 查行 |
+| `updateRow(baseId, table, id, data)` | `Row \| null` | 改行 |
+| `deleteRow(baseId, table, id)` | `boolean` | 删行 |
+| `query(baseId, table, opts?)` | `Row[]` | 查询（filter/sort/limit/offset） |
+| `search(baseId, table, field, query)` | `Row[]` | 全文搜索 |
+| `similaritySearch(baseId, table, field, vector)` | `Row[]` | 向量搜索 |
+| `list()` / `get(id)` / `getBySlug(slug)` / `delete(id)` | — | 数据库管理 |
+
+### 架构
+
+Fixed Slot：一张 `base_data` 表，预分配 ~120 个物理列：
+
+| 类型 | 列数 | PG 类型 |
+|------|:----:|:--------:|
+| 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（溢出兜底） |
+
+字段名 → 物理列号 的映射存储在 `base_column_map` 表。超出物理列的字段自动溢出到 ext JSONB。
+
+pgvector 自动检测：docker 镜像默认支持。
+
+---
+
+## 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? }
+
+// 中间件 & 挂载
+app.use(middleware)
+app.mount(prefix, router)
+app.plugin(fn)
+app.onError(handler)
+app.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 */ })
 ```
 
+`DATABASE_URL` 环境变量。支持迁移、事务、连接池统计。
+
+---
+
+## Redis
+
+```ts
+import { redis } from 'weifuwu'
+
+const r = redis()
+app.use(r)  // → ctx.redis
+await r.redis.set('key', 'value')
+```
+
+`REDIS_URL` 环境变量，默认 `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             ← 入口，导出所有模块
+├── types.ts             ← Context, Handler, Middleware 定义
+├── core/                ← serve, router, ws, trace, logger
+├── middleware/           ← cors, helmet, compress, rate-limit, upload, static, sandbox
+├── user/                ← 用户系统（CRUD、JWT、requireRole）
+├── messager/            ← 即时消息 + AI 对话交互层
+├── kb/                  ← RAG 知识库（分片、embedding、向量搜索）
+├── ai/                  ← AI Agent（LLM、tools、RAG）
+├── cms/                 ← 内容管理（博客、文档、公告）
+├── base/                ← 动态数据存储引擎（Fixed Slot）
+├── postgres/            ← PostgreSQL 客户端
+├── redis/               ← Redis 客户端
+├── queue/               ← 任务队列 + cron
+├── react/               ← React SSR
+├── 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         # 启动 postgres + redis
+npm run build                # esbuild → dist/
+npm run typecheck            # tsc --noEmit
+npm test                     # 281 tests
 ```