@weifuwujs/weifuwu 0.9.0

package/README.md

@@ -0,0 +1,605 @@
+# @weifuwujs/weifuwu
+
+一个基于 Node.js 与 Fetch API 的极简、类型安全 Web 框架。
+
+请求处理函数就是 `(req: Request, ctx) => Response | Promise<Response>`，
+没有自定义的请求/响应对象，也没有隐式魔法。
+
+```ts
+import { createApp, json } from '@weifuwujs/weifuwu'
+
+const app = createApp()
+
+app.get('/', () => new Response('Hello weifuwu!'))
+app.get('/users/:id', (req, ctx) => json({ id: ctx.params.id }))
+
+app.listen(3000, () => console.log('http://localhost:3000'))
+```
+
+## 定位
+
+**Node 上最干净的 fetch 全栈内核。**
+
+内核只回答「请求如何流过类型安全的函数管线」，不回答「业务上你该有什么」：
+
+- **管线**：handler / 洋葱中间件 / 类型安全路由 / `app.fetch` 纯函数入口；
+- **实时**：WebSocket 与 HTTP 共用路由、参数与中间件；
+- **数据**：`resource` 内核 + 懒加载 `ctx.sql` / `ctx.redis`；
+- **全栈**：React Router 单端口 SSR + CLI（init / dev / build / start / typegen / routes）；
+- **测试**：`app.request()` 不需要监听端口。
+
+auth / tasks / messages / 单源 API 已全部外迁为独立包（`@weifuwujs/*`），只通过公开的
+`ctx` 与中间件接入；旧子路径将在 0.9 移除，迁移路径见 [docs/migrating.md](./docs/migrating.md)。
+
+## 特性
+
+- **Fetch 原生**：`Request` / `Response` / `Headers` 就是标准 Web API，`app.fetch(request)` 是纯函数入口，方便测试与跨运行时复用。
+- **类型安全的路由参数**：`/users/:id` 会自动推导 `ctx.params.id: string`。
+- **洋葱模型中间件**：`(req, ctx, next) => ...`，可短路、可替换上下文。
+- **上下文类型累积**：`app.use(mw)` 注入的字段会一路传递到后面的 handler。
+- **内核极简**：路由 / 中间件 / 上下文只用 Node 内置模块；WebSocket 基于 `ws`，首次升级时懒加载；业务能力全部外迁为 `@weifuwujs/*` 生态包，内核保持零生态依赖。
+- **WebSocket**：基于 `ws` 的服务端实现（握手 / 分片 / 关闭 / ping-pong 由成熟内核承担），与路由、参数、中间件风格一致。
+- **数据资源**：`resource` 内核 + `./postgres`、`./ioredis` 子路径（懒加载 `ctx.sql` / `ctx.redis`、优雅关闭），见 [docs/data.md](./docs/data.md)。
+- **AI 集成**：用 `resource` 注入模型注册表（`ctx.ai`），`streamText` 流式 Response 直接返回；含 `useChat`、结构化输出、错误映射与 embedding 缓存配方，见 [docs/ai.md](./docs/ai.md)。
+- **内置中间件**：logger、cors、serveStatic。
+- **默认样式管线**：脚手架（`init`）自带 Tailwind CSS v4（`@tailwindcss/vite`），dev/prod 一致；shadcn/ui 接入见 [docs/styling.md](./docs/styling.md)。
+- **原生 TypeScript**：Node 24+ 可直接运行 `.ts` 源码；发布产物为 ESM + `.d.ts`。
+
+## 生态包（可选）
+
+内核之外的业务能力都是独立包，按需安装；它们只依赖内核公开的 `ctx` 与中间件接入，可单独发布与升级。
+
+- **单源 API**：[`@weifuwujs/api`](./packages/api/README.md)——一份类型描述符同时生成 REST 路由与 GraphQL schema。
+- **用户系统**：[`@weifuwujs/auth`](./packages/auth/README.md)——scrypt、会话轮换、防枚举、限流、Origin、无 JS 表单页，memory/sqlite/postgres store + 契约套件。
+- **任务队列**：[`@weifuwujs/tasks`](./packages/tasks/README.md)——至少一次 + 幂等键、指数退避/死信、memory/sqlite/postgres/redis 四驱动 + 契约套件、`weifuwu-tasks work` 独立进程。
+- **站内信**：[`@weifuwujs/messages`](./packages/messages/README.md)——幂等发送、REST 收件箱、WS 实时 + 断线 `since` 补投按 id 去重、memory/sqlite/postgres 契约套件、本地/Redis 可插拔总线。
+
+## 要求
+
+- Node.js **>= 24**（用于原生运行 TypeScript，以及稳定的 Fetch API）。
+
+## React Router 全栈
+
+`@weifuwujs/weifuwu` 内置 React Router v8（framework mode）集成：
+**单进程、单端口**同时提供 RR SSR 页面、weifuwu API 与 WebSocket，
+dev 与 prod 行为一致，路由类型由 RR typegen 生成。
+
+```bash quickstart
+# 1. 生成项目（内置模板：React Router + Tailwind，无需手工拷贝示例）
+npx @weifuwujs/weifuwu init my-app
+cd my-app
+npm install
+
+# 2. 开发：Vite HMR 与 weifuwu API 共用一个端口
+npm run dev          # http://localhost:3000
+
+# 3. 生产：构建 + 启动（同样一个端口）
+npm run build
+npm run start
+
+# 4. 类型：生成 RR 路由类型并检查
+npm run typecheck
+```
+
+接入本身只有一行——把 RR 作为 weifuwu 的 notFound 处理器：
+
+```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()) // 未命中 API 的请求交给 React Router
+```
+
+- 详细设计：[docs/react-router.md](./docs/react-router.md)（单端口 HMR、
+  context bridge、typegen、保留命名空间、dev 降级、env/trustProxy/缓存、部署）
+- 迁移指南：[docs/migrating.md](./docs/migrating.md)（官方 custom-server /
+  纯 weifuwu 两条路径）
+
+<!-- cli -->
+| 命令 | 说明 |
+| --- | --- |
+| `init` | 生成新项目（React Router + Tailwind + weifuwu） |
+| `dev` | 启动开发服务器（Vite + React Router SSR） |
+| `build` | 构建生产产物（react-router build） |
+| `start` | 启动生产服务器 |
+| `typegen` | 生成 React Router 类型 |
+| `routes` | 打印路由表（react-router routes） |
+
+用户系统命令已外迁为 `weifuwu-auth`（`migrate` / `user:list` / `user:disable` / `user:reset-password`）；
+任务队列为 `weifuwu-tasks`（`migrate` / `work` / `list` / `retry` / `prune`）；站内信为 `weifuwu-messages`（`migrate`）。
+见 [packages/auth](./packages/auth/README.md)、[packages/tasks](./packages/tasks/README.md)、[packages/messages](./packages/messages/README.md)。
+
+| 选项 | 说明 |
+| --- | --- |
+| `--port <port>` | 监听端口，默认 3000 |
+| `--host <host>` | 监听地址 |
+| `--root <dir>` | 项目根目录，默认当前目录 |
+| `--trust-proxy` | 信任 `X-Forwarded-Proto` / `X-Forwarded-Host`（反向代理场景） |
+<!-- /cli -->
+
+## 稳定性
+
+公共 API（`exports` 子路径与其具名导出）遵循 [STABILITY.md](./STABILITY.md) 的 semver 与弃用承诺：
+新增为 minor、破坏性变更为 major、弃用至少保留一个完整 minor；Node 支持、peer 范围与安全联系同样在该文件。
+贡献流程与门禁命令见 [CONTRIBUTING.md](./CONTRIBUTING.md)。
+
+## 安装
+
+```bash
+npm install @weifuwujs/weifuwu
+```
+
+## 核心类型
+
+```ts
+export interface Context {
+  params: Record<string, string>
+  query: Record<string, string>
+  [key: string]: unknown // allow arbitrary middleware-injected data
+}
+
+export type Handler<T extends object = Context> = (
+  req: Request,
+  ctx: T,
+) => Response | Promise<Response>
+
+export type Middleware<In extends Context = Context, Out extends In = In> = {
+  (req: Request, ctx: In, next: Handler<Out>): Response | Promise<Response>
+}
+```
+
+## 路由
+
+```ts
+const app = createApp()
+
+app.get('/users/:id', (req, ctx) => json({ id: ctx.params.id }))
+app.post('/users', async (req) => json(await req.json(), { status: 201 }))
+app.put('/users/:id', handler)
+app.patch('/users/:id', handler)
+app.delete('/users/:id', handler)
+app.head('/users/:id', handler)
+app.options('/users/:id', handler)
+
+// 任意方法 / 所有标准方法
+app.on('PURGE', '/cache/:key', handler)
+app.all('/webhook', handler)
+```
+
+路径语法：
+
+| 写法 | 含义 | 示例 |
+| --- | --- | --- |
+| `/users` | 静态路径 | `/users` |
+| `/users/:id` | 命名参数，写入 `ctx.params.id` | `/users/42` |
+| `/files/*` | 通配剩余路径，写入 `ctx.params['*']` | `/files/a/b.txt` |
+| `/files/*rest` | 带名字的通配 | `/files/a/b.txt` → `params.rest` |
+
+匹配优先级为：静态段 > `:param` > `*`。尾斜杠会被归一化（`/a/` 等价于 `/a`）。
+
+自动行为：
+
+- `HEAD` 请求在缺少 `HEAD` 路由时回退到 `GET`，且不发送响应体。
+- 路径存在但方法不匹配时返回 `405`，并带上 `Allow` 头。
+- 未显式注册 `OPTIONS` 时自动返回 `204` + `Allow`。
+
+### 路由分组
+
+```ts
+app.group('/api', (api) => {
+  api.get('/users/:id', (req, ctx) => json(ctx.params.id)) // GET /api/users/:id
+  api.group('/v2', (v2) => {
+    v2.get('/ping', () => new Response('pong')) // GET /api/v2/ping
+  })
+})
+```
+
+分组前缀中的参数也会进入类型：
+
+```ts
+app.group('/api/:version', (api) => {
+  api.get('/users/:id', (req, ctx) => {
+    ctx.params.version // string
+    ctx.params.id // string
+    return json(ctx.params)
+  })
+})
+```
+
+## 中间件
+
+中间件按注册顺序执行，形成洋葱模型：
+
+```ts
+import { logger } from '@weifuwujs/weifuwu/middleware'
+
+const app = createApp()
+  .use(logger())
+  .use(async (req, ctx, next) => {
+    const start = Date.now()
+    const res = await next(req, ctx) // 交给下一层
+    res.headers.set('x-duration', `${Date.now() - start}ms`)
+    return res
+  })
+  .get('/', () => new Response('ok'))
+```
+
+- 不调用 `next` 即可短路（例如鉴权失败直接返回 401）。
+- `next(req, ctx)` 可以传入新的 `req` / `ctx`，实现函数式的上下文替换；不传则沿用当前值。
+- 同一个中间件重复调用 `next` 会返回 500。
+
+### 注入上下文并获得类型
+
+推荐把中间件声明为带 `In` / `Out` 泛型的常量，`Out` 中的字段会累积到后续 handler：
+
+```ts
+import type { Context, Middleware } from '@weifuwujs/weifuwu'
+
+const withUser: Middleware<Context, Context & { user: User }> = async (
+  req,
+  ctx,
+  next,
+) => {
+  const user = await verify(req)
+  return next(req, { ...ctx, user })
+}
+
+const app = createApp().use(withUser)
+
+app.get('/me', (req, ctx) => json(ctx.user)) // ctx.user: User
+```
+
+> **注意**：TypeScript 无法从内联中间件内部对 `next()` 的调用来推断 `Out`。
+> 需要先把中间件赋值给带类型的变量/常量（如上），再传给 `use` / 路由。
+
+路由级中间件同样支持类型累积（最多显式推导两个中间件，更多则回退为不累积类型）：
+
+```ts
+app.get('/admin/:id', withUser, requireAdmin, (req, ctx) => {
+  ctx.params.id // string
+  ctx.user // User
+  return json(ctx.user)
+})
+```
+
+### 路径中间件
+
+```ts
+app.use('/api', authMiddleware)
+```
+
+路径中间件在进入时会剥离前缀（Express 风格），调用 `next()` 时还原；
+因此可以这样挂载静态资源：
+
+```ts
+app.use('/assets', serveStatic('./public')) // /assets/a.png -> ./public/a.png
+```
+
+## 上下文
+
+```ts
+app.get('/search', (req, ctx) => {
+  ctx.params // 路由参数
+  ctx.query // { q: 'hello' }，重复的 key 取第一个值
+  return json({ q: ctx.query.q })
+})
+```
+
+由于 `Context` 带有索引签名，中间件可以注入任意字段而不需要改动框架类型。
+也可以使用声明合并让字段全局可见：
+
+```ts
+declare module '@weifuwujs/weifuwu' {
+  interface Context {
+    user: User
+  }
+}
+```
+
+## 错误处理
+
+`HttpError` 会被自动转换为对应状态的响应（4xx 暴露 message，5xx 不暴露）：
+
+```ts
+import { HttpError } from '@weifuwujs/weifuwu'
+
+app.get('/users/:id', async (req, ctx) => {
+  const user = await db.find(ctx.params.id)
+  if (!user) throw new HttpError(404, 'User not found')
+  return json(user)
+})
+```
+
+自定义错误响应与 404：
+
+```ts
+app.onError((error, req, ctx) => {
+  console.error(error)
+  return json({ error: 'Something went wrong' }, { status: 500 })
+})
+
+app.notFound((req) => json({ error: 'Not Found' }, { status: 404 }))
+```
+
+`onError` 返回 `undefined` 时会退回默认行为；如果 `onError` 自身抛错，
+框架会记录该错误并返回 500。
+
+## 内置中间件
+
+从子路径导入，避免核心包引入 `node:fs`：
+
+```ts
+import { logger, cors, serveStatic } from '@weifuwujs/weifuwu/middleware'
+```
+
+### `logger(options?)`
+
+输出访问日志，默认格式 `GET /path 200 1.2ms`。
+
+| 选项 | 类型 | 说明 |
+| --- | --- | --- |
+| `log` | `(message: string) => void` | 输出函数，默认 `console.log` |
+| `format` | `(info: LogInfo) => string` | 自定义格式 |
+
+`LogInfo` 包含 `method` / `path` / `status` / `duration` / `request` /
+`response`，handler 抛错时还带 `error`（原始错误），可据此做结构化日志：
+
+```ts
+app.use(logger({ format: (info) => JSON.stringify({ ...info, error: undefined, message: info.error instanceof Error ? info.error.message : undefined }) }))
+```
+
+### `cors(options?)`
+
+| 选项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `origin` | `string \| string[] \| (origin) => string \| null` | `'*'` | 允许的来源 |
+| `methods` | `string \| string[]` | 常见方法全集 | `Access-Control-Allow-Methods` |
+| `allowedHeaders` | `string \| string[]` | 回显请求头 | `Access-Control-Allow-Headers` |
+| `exposedHeaders` | `string \| string[]` | — | `Access-Control-Expose-Headers` |
+| `credentials` | `boolean` | `false` | 为 `true` 且 origin 为 `'*'` 时回显 Origin |
+| `maxAge` | `number` | — | 预检缓存秒数 |
+
+预检请求（`OPTIONS` + `Access-Control-Request-Method`）会被直接以 `204` 响应。
+
+### `serveStatic(root, options?)`
+
+| 选项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `index` | `string \| false` | `'index.html'` | 目录默认文件 |
+| `fallback` | `string` | — | 文件不存在时回退（SPA） |
+| `maxAge` | `number` | — | `Cache-Control: max-age` 秒数 |
+| `immutable` | `boolean` | `false` | 追加 `immutable` |
+| `dotfiles` | `'allow' \| 'ignore' \| 'deny'` | `'ignore'` | 点文件处理策略 |
+| `headers` | `Record<string, string>` | — | 附加响应头 |
+| `etag` | `boolean` | `true` | 生成并为匹配请求返回 304 |
+
+未命中文件时调用 `next()`，因此可以与 API 路由共存；同时内置路径穿越防护。
+
+## WebSocket
+
+基于 `ws` 的服务端实现，路由与 HTTP 共用一套路径语法（`/chat/:room`、`*` 通配、分组前缀），
+握手/分片/关闭/ping-pong 由成熟内核承担。
+
+`app.ws(path, ..., factory)` 的终端是一个**工厂**：每连接调用一次，可以异步，返回生命周期回调。
+工厂体就是 open 钩子，闭包就是连接级状态：
+
+```ts
+const app = createApp()
+
+app.ws('/chat/:room', async (socket, ctx) => {
+  const room = ctx.params.room
+  await join(room, socket)                     // 异步初始化安全：期间消息会被缓冲
+
+  const timer = setInterval(() => socket.ping(), 30_000)
+  return {
+    onMessage: (socket, message) => broadcast(room, message.data), // 串行 await，自带背压
+    onClose: () => { clearInterval(timer); leave(room, socket) },  // 恰好一次
+    onError: (socket, error) => log.warn(error),
+  }
+})
+
+app.listen(3000)
+```
+
+框架保证：
+
+- **工厂结算前消息不丢**（缓冲后按序投递），因此 `await` 之后再处理消息是安全的；
+- `onMessage` 按到达顺序串行 await；抛错走 `onError` → `app.onError`，默认以 1011 关闭；
+- `onClose` 恰好一次（正常关闭 / 错误 / terminate），且排在已入队的 `onMessage` 之后；
+- 工厂返回 `void` 表示纯流式模式（自行 `socket.on` / `for await`）；dev 下若既没返回生命周期
+  也没有消息消费者，会给出警告，避免消息被静默丢弃。
+
+```ts
+// 纯流式：自行消费（for await 放在分离任务里，避免阻塞缓冲投递）
+app.ws('/echo', (socket) => {
+  void (async () => {
+    for await (const message of socket) socket.send(message.data)
+  })()
+})
+```
+
+### 连接 API
+
+回调之外，`socket` 仍暴露完整的事件与异步迭代能力（底层逃生口）：
+
+| 成员 | 说明 |
+| --- | --- |
+| `socket.send(data)` | 发送 `string`（文本）或 `Uint8Array`/`ArrayBuffer`（二进制）；返回 `false` 表示缓冲区已满 |
+| `socket.ping(data?)` / `socket.pong(data?)` | 控制帧；收到 ping 默认自动回 pong |
+| `socket.close(code?, reason?)` | 发起关闭握手，超时（默认 5s）后强制断开 |
+| `socket.terminate()` | 立即断开 |
+| `socket.readyState` | `'open'` / `'closing'` / `'closed'` |
+| `socket.protocol` | 协商出的子协议 |
+| `socket.remoteAddress` / `socket.bufferedAmount` | 对端地址 / 待发送字节数 |
+| 事件 | `message` / `close` / `error` / `ping` / `pong`（支持 `on` / `once` / `off`）|
+| `for await (const { data, binary } of socket)` | 异步迭代消息 |
+
+### 中间件与拒绝升级
+
+HTTP 与 WebSocket 共用 `Middleware` 类型；同一个中间件实例可以两处复用
+（结果类型写 `Response | void`），返回 `Response` 即拒绝升级（写回 HTTP 响应）：
+
+```ts
+import type { Context, Middleware } from '@weifuwujs/weifuwu'
+
+const withToken: Middleware<Context, Context & { token: string }, Response | void> =
+  async (req, ctx, next) => {
+    const token = req.headers.get('authorization')
+    if (!token) return new Response('Unauthorized', { status: 401 })
+    return next(req, { ...ctx, token })
+  }
+
+app.get('/me', withToken, (req, ctx) => json(ctx.token))   // HTTP：401 或继续
+app.ws('/secure/:id', withToken, (socket, ctx) => {        // WS：401 拒绝升级或继续
+  ctx.token // string
+  ctx.params.id // string
+  socket.send(ctx.token)
+  return {}
+})
+
+// 全局 WS 中间件（只作用于 upgrade，HTTP 中间件不会自动作用）
+app.wsUse(async (req, ctx, next) => next(req, ctx))
+```
+
+HTTP 专用中间件保持默认（`R = Response`），因此可以直接读取下游响应：
+
+```ts
+const withHeader: Middleware<Context, Context> = async (req, ctx, next) => {
+  const response = await next(req, ctx)
+  response.headers.set('x-trace', '1')
+  return response
+}
+```
+
+### 路由选项
+
+```ts
+app.ws(
+  '/room/:id',
+  {
+    protocols: ['chat.v2'], // 子协议，按客户端优先级挑选
+    maxMessageSize: 1 << 20, // 单条消息上限，默认 4 MiB，超出关闭码 1009
+    autoPong: true, // 自动回 pong，默认 true
+    closeTimeout: 5000, // 关闭握手超时
+    pingInterval: 30_000, // 服务端心跳 ping
+    idleTimeout: 120_000, // 空闲超时
+    headers: { 'x-custom': '1' }, // 追加到 101 响应的头
+  },
+  (socket, ctx) => {
+    socket.send(ctx.params.id)
+    return {}
+  },
+)
+```
+
+### 接入方式
+
+`app.listen()` 与 `serve()` 会自动挂载 `request` + `upgrade`；手动创建 server 时用 `app.attach(server)`：
+
+```ts
+import { createServer } from 'node:http'
+
+const server = createServer()
+app.attach(server) // HTTP + WebSocket
+server.listen(3000)
+```
+
+也可以直接调用 `app.upgrade(request, socket, head)` 自行接入任意 HTTP 服务器。
+
+## 部署到 Node
+
+```ts
+import { createApp } from '@weifuwujs/weifuwu'
+
+const app = createApp().get('/', () => new Response('ok'))
+
+// 方式一：直接监听
+app.listen(3000, () => console.log('ready'))
+
+// 方式二：手动创建 server
+import { createServer } from 'node:http'
+createServer(app.handler).listen(3000)
+
+// 方式三：serve 辅助函数（支持反向代理）
+import { serve } from '@weifuwujs/weifuwu/node'
+serve(app, { port: 3000, trustProxy: true })
+```
+
+- `app.fetch(request)`：纯 Fetch 入口，可用于测试或部署到任意 Fetch 运行时。
+- `app.handler`：Node 的 `(req, res)` 处理函数。
+- `serve` / `app.listen`：创建并启动 `http.Server`。
+- `trustProxy: true` 时会读取 `X-Forwarded-Proto` / `X-Forwarded-Host`。
+
+### 环境变量（CLI）
+
+`weifuwu dev` 与 `weifuwu start` 都会加载 `.env` 系列到 `process.env`，
+真实环境变量优先（文件只补缺）。优先级从低到高：
+
+```
+.env < .env.local < .env.${mode} < .env.${mode}.local
+```
+
+`mode` 由 `NODE_ENV` 决定（dev 默认 `development`，start 默认 `production`）。
+降级模式（Vite 初始化失败）同样适用，与正常启动保持一致。
+
+dev 模式另有一个可选逃生口：
+
+- `WEIFUWU_FS_ALLOW`：逗号分隔的额外文件系统路径，追加进 Vite dev 白名单。
+  仅在依赖被提升到项目根之外（monorepo、`file:` 链接）仍报 403 时使用；正常项目无需设置。
+
+## 测试
+
+`app.request()` 直接走内部 `fetch`，不需要启动端口：
+
+```ts
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { createApp, json } from '@weifuwujs/weifuwu'
+
+test('GET /users/:id', async () => {
+  const app = createApp().get('/users/:id', (req, ctx) => json({ id: ctx.params.id }))
+  const res = await app.request('/users/42')
+  assert.deepEqual(await res.json(), { id: '42' })
+})
+```
+
+## 项目结构
+
+```
+src/
+  types.ts        Handler / Middleware / Context / 类型工具
+  app.ts          App：路由注册、中间件、mount、fetch / upgrade / listen
+  group.ts        路由分组
+  router.ts       路径树路由器
+  compose.ts      洋葱模型组合（HTTP / WebSocket）
+  path.ts         路径工具
+  helpers.ts      json / text / html / redirect / HttpError
+  resources.ts    资源中间件内核（懒初始化 / 单例 / 优雅关闭）
+  postgres.ts     ./postgres：ctx.sql（postgres.js，懒加载）
+  ioredis.ts      ./ioredis：ctx.redis（ioredis，懒加载）
+  env.ts          .env 加载（dev / start 使用）
+  node.ts         Node HTTP 适配（Request/Response <-> IncomingMessage，upgrade）
+  cli.ts          weifuwu CLI：init / dev / build / start / typegen / routes
+  react-router.ts React Router SSR 中间件（虚拟模块加载 build）
+  vite.ts         defineConfig：注册 RR 插件与 SSR 入口
+  middleware/     logger / cors / serveStatic
+  websocket/      基于 ws：握手校验、连接适配、关闭码
+test/             node:test 测试（含类型级断言）
+examples/         basic.ts / rest.ts / websocket.ts / react-router
+templates/        weifuwu init 的工程模板（React Router + Tailwind）
+plan/             计划：plan.md（写作规范）/ websocket.md / react-router.md / engines.md / styling.md / resources.md
+```
+
+## 开发
+
+```bash
+npm test          # node --test，直接运行 TS 测试
+npm run typecheck # 类型检查（含类型级测试）
+npm run build     # 输出 ESM + d.ts 到 dist/
+```
+
+## License
+
+ISC