@weifuwujs/weifuwu 0.9.0

package/docs/ai.md

@@ -0,0 +1,175 @@
+# AI 集成：`ctx.ai` 与 AI SDK
+
+weifuwu 不封装 AI SDK。AI SDK（[`ai`](https://ai-sdk.dev)）是**无状态函数库**
+（`generateText` / `streamText` / `embedMany` / `ToolLoopAgent`），没有连接、没有生命周期。
+因此 `ctx.ai` 的最佳形态是**用 `resource` 注入模型注册表**：
+
+- 模型与 key 集中一处，按环境切换，测试可替换（`ai/test` 的 mock 模型）；
+- `generateText` / `streamText` 等函数保持原生 import，享受 SDK 全部能力与类型；
+- 懒初始化：只有真正用到模型时才创建 provider。
+
+## 安装
+
+```bash
+npm i ai zod @ai-sdk/openai   # provider 按需选择：@ai-sdk/anthropic、@ai-sdk/google 等
+```
+
+任何 OpenAI 兼容端点（DeepSeek、Qwen 等）都可通过 `createOpenAI({ baseURL })` 接入；
+Vercel AI Gateway 也可直接用模型字符串（如 `'openai/gpt-4o-mini'`）。
+
+## 配方（完整可编译）
+
+```ts ai
+import { createApp, HttpError, json, resource } from '@weifuwujs/weifuwu'
+import { redis } from '@weifuwujs/weifuwu/ioredis'
+import {
+  convertToModelMessages,
+  embedMany,
+  generateText,
+  Output,
+  streamText,
+} from 'ai'
+import type { EmbeddingModel, LanguageModel, UIMessage } from 'ai'
+import { openai } from '@ai-sdk/openai'
+import { z } from 'zod'
+
+// 1) 模型注册表：懒初始化、可注入、可测试替换
+const ai = resource('ai', () => ({
+  model: openai(process.env.AI_MODEL ?? 'gpt-4o-mini') as LanguageModel,
+  embed: openai.textEmbeddingModel(
+    process.env.AI_EMBED_MODEL ?? 'text-embedding-3-small',
+  ) as EmbeddingModel,
+}))
+
+// 2) 上游错误 → HTTP 语义：RetryError 解包、429 透传 retry-after、认证失败脱敏
+function toHttpError(error: unknown): HttpError {
+  let current: unknown = error
+  for (let depth = 0; depth < 3 && current instanceof Error; depth += 1) {
+    const status = (current as { statusCode?: unknown }).statusCode
+    if (typeof status === 'number') {
+      if (status === 401 || status === 403) {
+        return new HttpError(502, '模型服务认证失败')
+      }
+      if (status === 429) {
+        const retryAfter = (
+          current as { responseHeaders?: Record<string, string> }
+        ).responseHeaders?.['retry-after']
+        return new HttpError(429, '请求过于频繁，请稍后重试', {
+          headers:
+            retryAfter === undefined ? undefined : { 'retry-after': retryAfter },
+        })
+      }
+      return new HttpError(502, '模型服务异常')
+    }
+    current = (current as { lastError?: unknown }).lastError
+  }
+  throw error
+}
+
+const app = createApp()
+  .use(ai)
+  .use(redis()) // 可选：embedding 缓存
+  // 文本 / 结构化输出：进入响应前失败 → 标准 HTTP 错误
+  .post('/api/extract', async (req, ctx) => {
+    const { text } = (await req.json()) as { text: string }
+    try {
+      const { output } = await generateText({
+        model: ctx.ai.model,
+        output: Output.object({
+          schema: z.object({ title: z.string(), tags: z.array(z.string()) }),
+        }),
+        prompt: `提取标题与标签：\n${text}`,
+      })
+      return json(output)
+    } catch (error) {
+      throw toHttpError(error)
+    }
+  })
+  // useChat：UI 消息流（客户端见下）
+  .post('/api/chat', async (req, ctx) => {
+    const { messages } = (await req.json()) as { messages: UIMessage[] }
+    return streamText({
+      model: ctx.ai.model,
+      messages: await convertToModelMessages(messages),
+      onError: ({ error }) => console.error('[ai]', error),
+    }).toUIMessageStreamResponse()
+  })
+  // 纯文本流：curl / fetch / SSE 客户端都能直接用
+  .post('/api/completion', async (req, ctx) => {
+    const { prompt } = (await req.json()) as { prompt: string }
+    return streamText({
+      model: ctx.ai.model,
+      prompt,
+      onError: ({ error }) => console.error('[ai]', error),
+    }).toTextStreamResponse()
+  })
+  // embedding + 缓存：相同输入不再调模型
+  .post('/api/embed', async (req, ctx) => {
+    const { text } = (await req.json()) as { text: string }
+    const key = `embed:${encodeURIComponent(text)}`
+    const cached = await ctx.redis.get(key)
+    if (cached !== null) return json({ vector: JSON.parse(cached) })
+    const { embeddings } = await embedMany({ model: ctx.ai.embed, values: [text] })
+    const vector = embeddings[0]
+    await ctx.redis.set(key, JSON.stringify(vector), 'EX', 3600)
+    return json({ vector })
+  })
+
+export default app
+```
+
+## 前端：`useChat` 对接
+
+React Router 应用里（`app/routes/chat.tsx`）：
+
+```tsx
+import { useChat } from '@ai-sdk/react'
+import { DefaultChatTransport } from 'ai'
+
+export default function Chat() {
+  const { messages, sendMessage, status } = useChat({
+    transport: new DefaultChatTransport({ api: '/api/chat' }),
+  })
+
+  return (
+    <form
+      onSubmit={(event) => {
+        event.preventDefault()
+        const input = event.currentTarget.elements.namedItem('prompt')
+        if (!(input instanceof HTMLInputElement)) return
+        sendMessage({ text: input.value })
+        input.value = ''
+      }}
+    >
+      {messages.map((message) => (
+        <article key={message.id}>
+          <b>{message.role}</b>
+          {message.parts.map((part, index) =>
+            part.type === 'text' ? <p key={index}>{part.text}</p> : null,
+          )}
+        </article>
+      ))}
+      <input name="prompt" disabled={status === 'streaming'} />
+    </form>
+  )
+}
+```
+
+流式 Response 是 weifuwu 的原生形态：handler 直接 `return` 流即可，不需要 adapter。
+
+## 必须知道的几件事
+
+- **重试与 `RetryError`**：AI SDK 默认 `maxRetries: 2`，且遵守 `retry-after`——上游限流时
+  请求可能挂十几秒，最终抛出的 `RetryError` 包着 `APICallError`。上面的 `toHttpError`
+  会自动解包；API 路由里通常建议 `maxRetries: 0`（把重试留给客户端），或显式设置预算。
+- **流开始后不能改状态码**：`streamText` 一旦开始输出，错误只能走流内（`onError` /
+  UI 消息流的 error part）。所以"状态码映射"只对进入流之前的失败生效，
+  这也是上面对 `/api/extract` 用 try/catch、对流式路由用 `onError` 的原因。
+- **key 只在服务端**：不要放进 loader 返回值或客户端组件；`ctx.ai` 本来就只在 handler 里。
+- **限流 / 配额**：用 `ctx.redis` 的 `INCR` + `EXPIRE` 就是最小可用实现（见
+  [docs/data.md](./docs/data.md)）。
+- **测试不需要 key**：`ai/test` 的 `MockLanguageModelV4` / `MockEmbeddingModelV4`
+  可完全离线断言文本、用量、流式分块；provider 真链路也可以起一个本地
+  OpenAI 兼容 mock（SSE）后用 `createOpenAI({ baseURL })` 指向它。
+- **`ctx.ai` 不封装函数**：不做 `ctx.ai.text()` 之类的门面，避免绑定 SDK 版本节奏；
+  新能力（`ToolLoopAgent`、`Output`、`useChat`）随 `npm i ai` 直接可用。

package/docs/data.md

@@ -0,0 +1,81 @@
+# 数据资源：`ctx.sql` 与 `ctx.redis`
+
+`resource()` 是懒初始化的共享资源中间件：首个请求时创建、进程内单例、
+`app.close()` 时清理。官方提供两个子路径：
+
+| 子路径 | 注入 | 默认连接串 | 关闭动作 |
+| --- | --- | --- | --- |
+| `@weifuwujs/weifuwu/postgres` | `ctx.sql`（postgres.js） | `DATABASE_URL` | `sql.end()` |
+| `@weifuwujs/weifuwu/ioredis` | `ctx.redis`（ioredis） | `REDIS_URL` | `quit()`（等 `end` 事件） |
+
+两者都是 `peerDependencies`（optional）：不用就不会安装、不会加载，
+根入口也不受牵连。
+
+## 快速开始
+
+```bash
+npm i postgres ioredis
+
+# 本地服务（仓库自带 compose：pg18 + redis7）
+docker compose up -d
+# postgres://root:123456@127.0.0.1:5432/demo
+# redis://127.0.0.1:6379
+```
+
+```ts db
+import { createApp, json } from '@weifuwujs/weifuwu'
+import { postgres } from '@weifuwujs/weifuwu/postgres'
+import { redis } from '@weifuwujs/weifuwu/ioredis'
+
+const app = createApp()
+  .use(postgres()) // ctx.sql，默认读 DATABASE_URL
+  .use(redis()) // ctx.redis，默认读 REDIS_URL
+  .get('/users', async (req, ctx) => {
+    const cached = await ctx.redis.get('users')
+    if (cached) return json(JSON.parse(cached))
+
+    const rows =
+      await ctx.sql<{ id: number; name: string }[]>`select id, name from users`
+    await ctx.redis.set('users', JSON.stringify(rows), 'EX', 30)
+    return json(rows)
+  })
+
+export default app
+```
+
+也可以显式传连接串与 options：
+
+```ts
+app.use(postgres('postgres://user:pass@host:5432/db', { max: 10 }))
+app.use(redis('redis://host:6379', { lazyConnect: true }))
+```
+
+## 生命周期
+
+- **懒创建**：首个请求才连接（此时 `.env` 已加载）；并发首请求只建一个连接。
+- **失败不缓存**：首次建连失败 → 500（原始错误进 `onError` / 日志），下次请求重试。
+- **优雅关闭**：`app.close()` 或 CLI 的 `SIGINT` / `SIGTERM` → 按 LIFO 执行清理。
+  ioredis 的连接不会吊住进程（有 SIGTERM e2e 钉住）。
+- **手动控制**：`const db = postgres(); db.peek()` / `await db.load()` / `await db.close()`。
+
+## 自定义资源
+
+```ts
+import { createApp, resource } from '@weifuwujs/weifuwu'
+
+const mailer = resource('mailer', () => createMailer(), {
+  close: (client) => client.close(),
+})
+
+const app = createApp().use(mailer) // ctx.mailer
+```
+
+## 说明与坑
+
+- **事务不自动包裹**：需要时在 handler 里用 `ctx.sql.begin(...)`，避免中间件隐式行为。
+- **池/重连策略沿用客户端默认**：通过 options 透传（如 `{ max: 10 }`、`{ lazyConnect: true }`）。
+- **关闭语义**：`await app.close()` 返回时，redis 连接已到 `end` 状态（v6 的 `quit()`
+  本身在 `end` 事件之前 resolve，weifuwu 等事件，1s 兜底）。
+- **守卫**：根入口不静态加载 `postgres` / `ioredis`（`test/root-entry.test.ts` 用
+  ESM resolve 钩子证明）。
+- **测试**：`test/db.test.ts` 连真库；服务不可达时显式 skip。先 `docker compose up -d`。

package/docs/migrating.md

@@ -0,0 +1,116 @@
+# 迁移到 weifuwu 全栈
+
+两条路径：**A. 从官方 `node-custom-server` 模板迁移**（Express 适配器 →
+weifuwu 单端口）；**B. 从纯 weifuwu 迁移**（加 React Router 页面层）。
+
+## A. 从官方 `node-custom-server` 模板迁移
+
+官方模板用 Express（`@react-router/express`）做自定义服务器，且 dev 的 HMR
+跑在独立端口。weifuwu 不需要 Express，dev/prod 同一个端口。
+
+| 官方模板 | weifuwu |
+| --- | --- |
+| `server.js` + `server/app.ts` | `app/server.ts`（默认导出 App，CLI 负责 listen） |
+| `@react-router/express` 适配器 | `@weifuwujs/weifuwu/react-router` 的 `reactRouter()` |
+| `vite.config.ts` 手写插件/中间件 | `defineConfig()`（自动注册 RR 插件与 SSR 入口） |
+| `react-router dev/build/start` | `weifuwu dev/build/start` |
+| HMR 独立端口（24678） | 同一端口（`server.ws.server`） |
+
+步骤：
+
+1. 保留 `app/`（路由、`root.tsx`）与 `react-router.config.ts`；
+2. 删除 `server.js`、`server/app.ts` 以及 express / `@react-router/express`
+   依赖；
+3. 新建 `app/server.ts`：
+
+```ts migration-after
+import { createApp, json } from '@weifuwujs/weifuwu'
+import { reactRouter } from '@weifuwujs/weifuwu/react-router'
+
+export default createApp()
+  .get('/api/health', () => json({ ok: true }))
+  .notFound(reactRouter())
+```
+
+4. `vite.config.ts`：
+
+```ts
+import { defineConfig } from '@weifuwujs/weifuwu/vite'
+
+export default defineConfig({})
+```
+
+5. `package.json`：
+
+```json
+{
+  "scripts": {
+    "dev": "weifuwu dev",
+    "build": "weifuwu build",
+    "start": "weifuwu start",
+    "typegen": "weifuwu typegen",
+    "typecheck": "weifuwu typegen && tsc -p tsconfig.json"
+  }
+}
+```
+
+6. 需要把 weifuwu 中间件注入 RR loader 时，加
+   `reactRouter({ getLoadContext })`（写法见
+   [react-router.md](./react-router.md#context-bridgeweifuwu-中间件--rr-loader)）。
+
+更省事的做法：`npx @weifuwujs/weifuwu init my-app` 生成骨架，
+再把原来的 `app/` 拷进去。
+
+## B. 从纯 weifuwu 迁移
+
+迁移前的服务入口通常长这样：
+
+```js
+// server.js（node server.js 启动）
+import { createApp, json } from '@weifuwujs/weifuwu'
+
+const app = createApp().get('/api/health', () => json({ ok: true }))
+app.listen(3000)
+```
+
+步骤：
+
+1. 用 `npx @weifuwujs/weifuwu init my-app` 生成工程骨架，把现有路由
+   （`.get/.post/...` 与中间件）搬进 `app/server.ts`；
+2. 去掉 `app.listen(...)`，改为**默认导出 App**；在末尾加
+   `.notFound(reactRouter())` 接管页面；
+3. 把页面组件放进 `app/routes/`，在 `app/routes.ts` 注册；
+4. `npm run dev` 验证 API 与页面同端口可用；`npm run typecheck`
+   会先跑 typegen 再检查类型（单独生成用 `npm run typegen`）。
+
+## C. 从 0.8 全家桶迁到 0.9 内核 + 生态包
+
+0.8 内置的用户系统 / 任务队列 / 站内信 / 单源 API 已外迁为独立包；**0.9 起旧子路径与子命令不再提供
+（硬切断，无 shim）**。迁移 = 换导入 + 换 bin，业务代码只需改动 `ctx` 注入处。
+
+导入映射：
+
+| 0.8（内置子路径） | 0.9（独立包） |
+| --- | --- |
+| `@weifuwujs/weifuwu/auth` | `@weifuwujs/auth` |
+| `@weifuwujs/weifuwu/tasks` | `@weifuwujs/tasks` |
+| `@weifuwujs/weifuwu/messages` | `@weifuwujs/messages` |
+| `@weifuwujs/weifuwu/api` | `@weifuwujs/api` |
+
+bin 映射（`weifuwu` 子命令 → 独立 bin，参数不变）：
+
+| 0.8 | 0.9 |
+| --- | --- |
+| `weifuwu auth migrate` / `user:list` / `user:disable` / `user:reset-password` | `weifuwu-auth migrate` / `user:list` / `user:disable` / `user:reset-password` |
+| `weifuwu tasks migrate` / `work` / `list` / `retry` / `prune` | `weifuwu-tasks migrate` / `work` / `list` / `retry` / `prune` |
+| `weifuwu messages migrate` | `weifuwu-messages migrate` |
+
+`init --auth` / `init --messages` 叠加旗标已删除：`init` 只生成内核骨架，叠加能力按各包 README 接入。
+store 选项（`--store`）随命令移动到对应包 bin（如 `weifuwu-tasks migrate --store postgres`）。
+
+## 迁移后自检
+
+- `npm run typegen && npx tsc -p tsconfig.json` → 0 error；
+- `npm run dev` 与 `npm run build && npm run start` 行为一致；
+- `/api/health` 与一条页面路由都能访问；
+- 反代场景加 `--trust-proxy`，见 [react-router.md](./react-router.md#运维)。

package/docs/react-router.md

@@ -0,0 +1,187 @@
+# React Router 全栈集成
+
+weifuwu 把 React Router v8（framework mode）作为**页面层**接入，自身提供
+API/WebSocket/中间件层。目标是：一个进程、一个端口，dev 与 prod 行为一致。
+
+## 架构
+
+```
+请求 ──▶ weifuwu HTTP server ──分支──▶ weifuwu 路由（/api、/ws、静态文件）
+                                   └──▶ 未命中 ──▶ reactRouter() ──▶ RR SSR/数据加载
+```
+
+- `app/server.ts` **默认导出 weifuwu App**，只描述应用，不负责 `listen`；
+  进程与端口由 `weifuwu` CLI 拥有。
+- RR 挂载点为 `app.notFound(reactRouter())`：weifuwu 中间件在外圈对页面
+  同样生效；未命中的请求（含所有页面 URL）交给 RR。
+- 构建时 `react-router build` 的 SSR 入口就是 `app/server.ts`，
+  `build/server/index.js` 即 weifuwu 应用。
+
+## 接入
+
+```ts
+import { createApp, json } from '@weifuwujs/weifuwu'
+import { reactRouter } from '@weifuwujs/weifuwu/react-router'
+
+export default createApp()
+  .get('/api/health', () => json({ ok: true }))
+  .notFound(reactRouter())
+```
+
+Vite 侧使用预设（自动注册 RR 插件、设置 SSR 入口、把 weifuwu 内联进
+SSR bundle）：
+
+```ts
+import { defineConfig } from '@weifuwujs/weifuwu/vite'
+
+export default defineConfig({})
+```
+
+## 表单与动作（无 JS 可用）
+
+原生 `<form method="post">` 提交时，**React Router 的 index 路由不处理 POST**
+（用 `react-router dev` 官方 dev server 同样返回 405：`route "root"` 没有
+`action`）。因此表单动作要挂在**有 path 的路由上**：
+
+```ts
+// app/routes.ts
+export default [
+  index('routes/home.tsx'),
+  route('actions/submit', 'routes/submit-action.tsx'), // action 端点
+] satisfies RouteConfig
+```
+
+```tsx
+// 页面：原生表单提交到动作端点
+<Form method="post" action="/actions/submit">…</Form>
+```
+
+动作端点按 **POST-redirect-GET** 收尾（成功回列表页；失败用
+`?error=` 回列表页，保证无 JS 也能看到错误）：
+
+```tsx
+export async function action({ request }: Route.ActionArgs) {
+  const form = await request.formData()
+  try {
+    await doSomething(form)
+  } catch (error) {
+    return redirect(`/?error=${encodeURIComponent(String(error))}`)
+  }
+  return redirect('/')
+}
+```
+
+weifuwu 只在路由**完全未匹配**时才把请求交给 RR 兜底处理器：POST 到
+框架已注册的 GET 路径（如 `/api/health`）仍返回 405，语义不变。
+
+## 单端口 HMR
+
+`weifuwu dev` 用 Vite `middlewareMode` + `server.ws.server`，把 Vite HMR
+挂在 weifuwu 的 HTTP server 上；upgrade 按协议分流（`vite-hmr`/`vite-ping`
+给 Vite，其余给应用 WebSocket）。因此不需要 RR 默认的 24678 端口。
+
+## context bridge（weifuwu 中间件 → RR loader）
+
+weifuwu 的 `Context` 与 RR 的 loader context 是两套对象，用
+`RouterContextProvider` 显式桥接：
+
+```ts
+import { createContext } from 'react-router'
+import type { Middleware } from '@weifuwujs/weifuwu'
+import { RouterContextProvider } from 'react-router'
+
+type AppContext = Context & { greeting: string }
+
+const withGreeting: Middleware<Context, AppContext> = async (req, ctx, next) =>
+  next(req, { ...ctx, greeting: 'hello' })
+
+export default createApp()
+  .use(withGreeting)
+  .notFound(
+    reactRouter<AppContext>({
+      getLoadContext(_request, ctx) {
+        const loadContext = new RouterContextProvider()
+        loadContext.set(greetingContext, ctx.greeting)
+        return loadContext
+      },
+    }),
+  )
+```
+
+loader 里用 `context.get(greetingContext)` 读取（见
+`examples/react-router/app/`）。
+
+## 类型：`+types` 与 typegen
+
+- RR typegen 生成 `.react-router/types/**`；路由模块用
+  `import type { Route } from './+types/<route>'`，配合
+  `Route.LoaderArgs` / `Route.ComponentProps` / `Route.ErrorBoundaryProps`。
+- `weifuwu dev` 内置 typegen watch（RR 插件自带），文件变更即时更新类型。
+- CI/一次性检查：`weifuwu typegen && tsc -p tsconfig.json`
+  （模板的 `npm run typecheck` 即此命令）。
+- tsconfig 需要 `rootDirs: [".", "./.react-router/types"]`；
+  若源码用 Node 原生 `.ts` 导入，再加 `allowImportingTsExtensions`。
+
+## dev 派发与保留命名空间
+
+dev 请求先判断 Vite 命名空间，其余 **app-first**（与 prod 顺序一致）：
+
+- Vite 保留：`/@*`、`/app/**`、`/node_modules/**`、`/.vite/**`、`/__*`，
+  以及 `public/` 下**已存在**的文件；
+- 其余（API、WebSocket、页面 URL）由 weifuwu App 处理，未命中再进 RR。
+
+因此不要把你的 weifuwu 路由放在上述保留前缀下。
+
+## 故障降级
+
+若 RR/Vite 配置损坏（例如 `routes.ts` 语法错误）导致 `createServer` 失败：
+
+- `weifuwu dev` **进程不退出**，进入降级模式：`public/` 静态文件继续由
+  内置静态中间件提供，weifuwu 路由经 Node 原生 import 加载 `app/server.ts`
+  继续服务；
+- 此时 RR 页面不可用（依赖 Vite 管线）；
+- dev 下会安装 `unhandledRejection` 护栏（仅记录日志，避免 RR typegen
+  watcher 的未处理异常杀进程）。修好配置后建议重启 dev。
+
+## 运维
+
+### `.env`
+
+`weifuwu start` 会加载（真实环境变量优先，文件只补缺）：
+
+```
+.env  <  .env.local  <  .env.${NODE_ENV}  <  .env.${NODE_ENV}.local
+```
+
+dev 下的 `.env` 由 RR/Vite 的 dotenv 负责。
+
+### 反向代理（trustProxy）
+
+`weifuwu start --trust-proxy`（或 dev 同参数）后，`X-Forwarded-Proto` /
+`X-Forwarded-Host` 会参与构造 `request.url`（forwarded-host 优先于 Host）。
+未开启时这两个头被忽略，避免伪造。也可在代码里用
+`toNodeHandler(app, { trustProxy: true })`。
+
+### 静态缓存
+
+生产静态策略（`weifuwu start`）：
+
+- `build/client/assets/**`（带 hash）：`Cache-Control: public, max-age=31536000, immutable`；
+- 其余 `build/client/**`（如 `robots.txt`）：`public, max-age=3600`。
+
+## 部署检查清单
+
+1. `weifuwu build` 产出 `build/client` 与 `build/server`；
+2. `NODE_ENV=production weifuwu start`（同端口同时服务页面与 API）；
+3. 反代时加 `--trust-proxy`，并按需设置 `.env.production`；
+4. 健康检查 `/api/health`（不要只探页面）。
+
+## 已知限制
+
+- `app/server.ts` 顶层副作用会在 dev HMR 时重跑：长生命周期资源
+  （连接池等）请放独立模块。
+- `unhandledRejection` 护栏会吞掉（并记录）dev 下所有未处理异步错误。
+- 降级模式下 RR 页面不可用。
+- **index 路由不处理 POST**：表单动作要挂在有 path 的路由上，见"表单与动作"。
+- POST 到框架已注册的路径（GET 路由）返回 405，不会落到 RR 兜底处理器
+  （避免 API 路径的 405 语义被页面渲染覆盖）。

package/docs/styling.md

@@ -0,0 +1,69 @@
+# 样式与 UI
+
+## Tailwind CSS（`weifuwu init` 默认）
+
+`init` 生成的工程已接好 Tailwind CSS v4，无需额外配置：
+
+| 文件 | 作用 |
+| --- | --- |
+| `app/app.css` | `@import 'tailwindcss';`（在模块图内，才会被 Vite 处理） |
+| `app/root.tsx` | `import './app.css'`，`<Links />` 输出样式表 |
+| `vite.config.ts` | `defineConfig({ plugins: [tailwindcss()] })` |
+
+- 自定义主题：直接在 `app/app.css` 里用 v4 的 `@theme` / `@custom-variant`，
+  不需要 `tailwind.config.js`。
+- 动态拼接的类名（如 `` `bg-${color}-500` ``）不会被探测到，属于 Tailwind
+  通用限制；枚举映射或安全名单处理。
+- Vite 降级模式下（`weifuwu dev` 启动失败转为纯 Node）页面无样式，
+  与「降级模式下 RR 页面不可用」是同一类边界。
+
+## shadcn/ui（官方路径，一条命令）
+
+模板已满足 shadcn 的前置条件：Tailwind v4、TypeScript、`~/*` 别名
+（`tsconfig.json` 的 `paths` + weifuwu 在 dev/prod 两侧的解析器，
+见 `src/vite.ts` 的 `weifuwu:tilde-app-alias`）。
+
+```bash
+weifuwu init my-app && cd my-app && npm install
+
+# 初始化（交互式；非交互：-y -b radix -p nova）
+npx shadcn@latest init
+
+# 添加组件
+npx shadcn@latest add button
+```
+
+实测（`shadcn@4.21.0`，`-y -b radix -p nova --no-monorepo`）：
+
+- `init` 正确识别并沿用 `~/components`、`~/lib/utils` 别名，生成
+  `components.json` 与 `app/lib/utils.ts`，并把主题变量追加进 `app/app.css`
+  （`@import "shadcn/tailwind.css"`、`@theme inline`、`:root` 变量）——
+  这是 shadcn 的正常行为。
+- `add button` 后渲染组件，`weifuwu build` / `weifuwu start` 通过，
+  组件用到的 utility 出现在构建 CSS 里，SSR 输出的页面包含组件。
+
+注意事项：
+
+- `components.json` 的 aliases 用 `~/...`（weifuwu 已支持）；不要改成 `@/`，
+  否则需要自己补 alias 配置。
+- 不要改 `vite.config.ts`：Tailwind 插件已经在了。
+- 组件代码归你所有（这正是 shadcn 的模型）。weifuwu **不** 预置任何组件或
+  主题；升级组件用 `npx shadcn@latest add <name> --reinstall` 等官方命令。
+- CLI 的 preset / 参数会随版本演进（例如 preset 名称），以 `npx shadcn@latest init --help`
+  为准。
+
+### 兼容性测试
+
+- 离线回归：`test/init.test.ts` 的「shadcn 形态的组件可构建并渲染」用例，
+  验证 `~/` 解析、`cn()` 形态、组件 utility 进 CSS、SSR 渲染。
+- 真 CLI e2e（需网络，默认跳过）：
+
+  ```bash
+  SHADCN_E2E=1 node --test test/shadcn.test.ts
+  ```
+
+## 其他 UI 方案
+
+Tailwind 只是构建管线，不是设计系统：用自研组件、其他组件库
+（自行 `npm install`）都可以；不想要样式管线时删掉 `app/app.css` 与
+`vite.config.ts` 里的 `tailwindcss()` 即可。