wok-server 0.4.13 → 0.6.0

package/skills/wok-server-mvc/references/sse.md

@@ -0,0 +1,121 @@
+# Server-Sent Events (SSE)
+
+从 0.4.0 版本开始，MVC 组件内置了 `createSseHandler`，封装了 SSE 协议细节，大幅简化服务端推送实现。
+
+## 内置 SSE Handler
+
+```ts
+import { createSseHandler } from 'wok-server'
+
+await startWebServer({
+  routers: {
+    '/sse': createSseHandler({
+      async handle(ctx) {
+        let counter = 0
+        for (let i = 0; i < 10; i++) {
+          await new Promise<void>(resolve => setTimeout(resolve, 1000))
+          counter++
+          // ctx.send 自动处理 SSE 协议格式
+          ctx.send({ message: '实时更新', count: counter })
+          if (counter >= 10) {
+            break
+          }
+        }
+        // 显式关闭连接（不调用也会在 handle 结束时自动关闭）
+        ctx.close()
+      }
+    })
+  }
+})
+```
+
+### SseContext
+
+`handle` 函数接收的 `ctx` 对象提供以下属性与方法：
+
+| 属性/方法                                | 说明                                                         |
+| :--------------------------------------- | :----------------------------------------------------------- |
+| `ctx.send(data, event?, id?)`           | 发送 SSE 事件，`data` 会被 JSON 序列化。`event` 指定事件名（前端用 `addEventListener` 监听），`id` 设置事件 ID（用于断线重连的 `Last-Event-ID`） |
+| `ctx.close()`                            | 显式结束 SSE 连接。`handle` 结束时连接也会自动关闭           |
+| `ctx.request`                            | 原始 `IncomingMessage`，可读取请求头等信息                   |
+| `ctx.response`                           | 原始 `ServerResponse`，高级场景下使用                         |
+
+### 命名事件
+
+通过 `event` 参数发送命名事件，前端可按事件类型分别处理：
+
+```ts
+createSseHandler({
+  async handle(ctx) {
+    ctx.send({ title: '新消息' }, 'notification')
+    ctx.send({ progress: 50 }, 'progress')
+  }
+})
+```
+
+前端：
+
+```ts
+const es = new EventSource('/sse')
+es.addEventListener('notification', e => {
+  const data = JSON.parse(e.data)
+  console.log('收到通知：', data.title)
+})
+es.addEventListener('progress', e => {
+  const data = JSON.parse(e.data)
+  console.log('进度：', data.progress)
+})
+```
+
+### 断线重连
+
+通过 `id` 参数设置事件 ID，前端断线重连时浏览器会自动发送 `Last-Event-ID` 请求头：
+
+```ts
+createSseHandler({
+  async handle(ctx) {
+    const lastId = ctx.request.headers['last-event-id']
+    // 根据 lastId 确定从何处恢复推送
+    for (const event of events) {
+      ctx.send(event, undefined, event.id)
+    }
+  }
+})
+```
+
+### 连接生命周期
+
+- `handle` 开始执行时，SSE 消息头已发送，连接已建立
+- 客户端断开连接时，`ctx.send()` 调用变为空操作（自动忽略）
+- `handle` 返回或抛异常时，连接自动关闭
+- 手动调用 `ctx.close()` 可提前结束连接
+
+---
+
+## 手动实现（高级用法）
+
+如需完全控制底层行为，仍可在普通路由处理器中手动操作 `response` 对象：
+
+```ts
+await startWebServer({
+  routers: {
+    '/sse': async exchange => {
+      const { response } = exchange
+      response.setHeader('Content-Type', 'text/event-stream')
+      response.setHeader('Cache-Control', 'no-cache')
+      response.setHeader('Connection', 'keep-alive')
+
+      let counter = 0
+      for (let i = 0; i < 10; i++) {
+        await new Promise<void>(resolve => setTimeout(resolve, 1000))
+        counter++
+        response.write(`data: ${JSON.stringify({ message: '实时更新', count: counter })}\n\n`)
+        if (counter >= 10) {
+          break
+        }
+      }
+      response.end()
+    }
+  }
+})
+```

package/skills/wok-server-mvc/references/static-files.md

@@ -0,0 +1,47 @@
+# 静态文件
+
+通过 `startWebServer` 的 `static` 参数设置静态文件目录映射，将文件系统目录映射到请求路径。
+
+## 基本配置
+
+```ts
+await startWebServer({
+  static: {
+    '/a': { dir: '/path/to/files', cacheAge: 300 },
+    '/a/b': { dir: '/path/to/other', cacheAge: 150 },
+    '/b': { dir: 'static', cacheAge: 0 }
+  },
+  routers: {}
+})
+```
+
+| 参数      | 说明                                             |
+| :-------- | :----------------------------------------------- |
+| `dir`     | 映射的文件目录，支持绝对路径和相对路径（相对进程当前目录） |
+| `cacheAge` | 缓存时间（秒），大于 0 则生成 `Cache-Control` 消息头   |
+
+## 路径匹配规则
+
+- 仅支持**前缀匹配**，不支持通配符。例如 `/a/demo.html` 匹配 `/a` 路径配置。
+- 路径配置有**优先级**：更详细的路径优先匹配。例如访问 `/a/b/music.mp3` 会匹配 `/a/b` 而非 `/a`。
+- 匹配失败不会降级尝试：如果 `/a/b` 目录下找不到文件，不会再去 `/a` 目录查找。
+- 支持**主页自动映射**：访问 `/a/b/c` 时，会先找文件 `c`，找不到则尝试目录 `c` 下的 `index.html`。
+
+## 服务器端缓存
+
+从 0.3.0 版本开始，支持静态文件服务器端缓存。通过以下环境变量配置：
+
+| 环境变量                           | 说明                                          | 默认值 |
+| :--------------------------------- | :-------------------------------------------- | :----- |
+| `SERVER_STATIC_CACHE_ENABLE`       | 是否启用服务器缓存                            | false  |
+| `SERVER_STATIC_CACHE_MAX_AGE`      | 服务器缓存时间（秒）                          | 600    |
+| `SERVER_STATIC_CACHE_MAX_FILE_SIZE` | 最大可缓存的文件大小，支持语义化格式（如 10m、100k） | 10m    |
+| `SERVER_STATIC_CACHE_MAX_SIZE`     | 缓存最大空间，超出后清理，支持语义化格式      | 100m   |
+
+0.3.2 版本新增 `removeServerStaticCache` 函数，可主动清除指定路径的静态文件缓存：
+
+```ts
+import { removeServerStaticCache } from 'wok-server'
+
+removeServerStaticCache('/assets/index.js')
+```

package/skills/wok-server-mvc/references/upload.md

@@ -0,0 +1,62 @@
+# 文件上传
+
+## 二进制（Binary）上传
+
+二进制上传即 `application/octet-stream` 格式的上传，请求正文仅为文件内容，不包含其他信息。由 `createUploadHandler` 函数创建路由处理器，响应 JSON 格式。
+
+这种形式的优势是简单、性能高——服务器端拿到请求正文即是文件，无需解析。但额外参数只能通过 QueryString 或 Header 传递，且一次只能传一个文件。
+
+```ts
+import { createUploadHandler } from 'wok-server'
+
+interface Resp {
+  url: string
+}
+
+export const uploadAvatar = createUploadHandler<Resp>({
+  async handle(body, exchange) {
+    const userId = exchange.query.getStr('userId') as string
+    if (body.byteLength > 2 * 1024 * 1024) {
+      throw new BusinessException('文件大小不得超过 2MB')
+    }
+    const key = `users/${userId}/avatar`
+    await oss.putObject(key, body)
+    return { url: oss.getUrl(key) }
+  }
+})
+```
+
+如需更高自由度（如不返回 JSON），使用普通路由处理器，通过 `exchange.bodyBuffer()` 读取请求正文：
+
+```ts
+export const uploadAvatar: RouterHandler = async exchange => {
+  const file = await exchange.bodyBuffer()
+  const query = exchange.parseQueryString()
+  const userId = query.getStr('userId')
+  // 校验参数和存储文件等流程省略...
+}
+```
+
+## multipart/form-data 格式上传
+
+组件目前尚未内置对 multipart/form-data 类型请求的处理，可通过第三方库（如 formidable）解析。
+
+```ts
+import formidable from 'formidable'
+
+await startWebServer({
+  routers: {
+    '/cover': async exchange => {
+      const form = formidable({})
+      const [fields, files] = await form.parse(exchange.request)
+      // todo 继续业务处理
+    }
+  }
+})
+```
+
+### 注意事项
+
+- 使用了第三方库读取 `request` 内容后，不能再使用 `exchange` 中的 `bodyXxx` 系列方法，调用时会抛出异常。
+- 同样，调用了 `bodyXxx` 系列方法后也不能再用第三方库读取内容，否则将读取不到完整内容或引发异常。
+- `bodyXxx` 系列方法之间可以重复调用，不会产生错误。例如调用 `bodyText()` 后再调用 `bodyJson()` 是允许的。

package/skills/wok-server-mvc/references/websocket.md

@@ -0,0 +1,30 @@
+# WebSocket
+
+MVC 组件本身未内置 WebSocket 处理，但通过 `startWebServer` 的 `preHandler` 参数可整合支持原生 `http` 模块的 WebSocket 库（如 socket.io）。
+
+`preHandler` 在服务启动前执行，接收原生 `http.Server` 实例，可在此时挂载 WebSocket 服务。
+
+```ts
+import { Server } from 'socket.io'
+
+await startWebServer({
+  routers: {
+    // 路由配置省略...
+  },
+  preHandler: async server => {
+    const io = new Server(server)
+    io.of('/chat').on('connection', socket => {
+      socket.on('message', data => {
+        /* 处理自定义事件 */
+      })
+      socket.on('disconnect', () => {
+        /* 连接断开处理 */
+      })
+    })
+  }
+})
+```
+
+### 注意事项
+
+- WebSocket 路径（如 `/chat`）与路由路径不会冲突。客户端以 HTTP 协议请求时走路由处理，以 WebSocket 协议请求时走 socket.io 处理。但不推荐使用相同的路径。

package/skills/wok-server-mysql/SKILL.md

@@ -0,0 +1,315 @@
+---
+name: wok-server-mysql
+description: wok-server MySQL 组件使用指南，提供单表 CRUD、多数据源、版本管理和事务的完整支持。
+license: MIT
+metadata:
+  author: Peak Tai
+  email: peaktai@qq.com
+---
+
+# wok-server MySQL 组件
+
+## 概述
+
+MySQL 组件基于 [mysql2](https://www.npmjs.com/package/mysql2) 封装，提供便捷的单表操作。支持：实体映射 CRUD、多数据源、SQL 版本管理、事务、慢查询告警。
+
+## 源码与类型定义
+
+安装 `wok-server` 后，可通过以下路径查看源码与类型定义：
+
+- 源码目录：`node_modules/wok-server/src/mysql/`
+- 类型定义：`node_modules/wok-server/types/` （引用 mysql 组件的 `.d.ts` 文件）
+
+核心源码文件：
+
+| 文件               | 说明                               |
+| :----------------- | :--------------------------------- |
+| `index.ts`         | 模块入口，`enableMysql`/`getMysqlManager` |
+| `config.ts`        | 配置定义与默认值                    |
+| `table-info.ts`    | `Table<T>` 表映射接口               |
+| `manager/`         | 管理器层：`BaseMysqlManager`、`MysqlManager`、`MysqlTxSession` |
+| `manager/ops/`     | 各操作的 SQL 生成与执行             |
+| `manager/ops/criteria.ts` | `MysqlCriteria` 条件构建器    |
+| `migration.ts`     | SQL 文件版本管理                    |
+| `exception.ts`     | `MysqlException` 异常类             |
+
+---
+
+## 环境变量
+
+| 环境变量                       | 说明                 | 默认值       |
+| :----------------------------- | :------------------- | :----------- |
+| `MYSQL_HOST`                   | 主机名               | localhost    |
+| `MYSQL_PORT`                   | 端口号               | 3306         |
+| `MYSQL_USER`                   | 用户名               | root         |
+| `MYSQL_PASSWORD`               | 密码                 | 123456       |
+| `MYSQL_DATABASE`               | 数据库名             | example      |
+| `MYSQL_CHARSET`                | 字符集               | utf8mb4      |
+| `MYSQL_CONNECTION_LIMIT`       | 最大连接数           | 10           |
+| `MYSQL_MAX_IDLE`               | 最大闲置连接数       | 10           |
+| `MYSQL_IDLE_TIMEOUT`           | 闲置超时（ms）       | 60000        |
+| `MYSQL_CONNECT_TIMEOUT`        | 连接超时（ms）       | 10000        |
+| `MYSQL_DEBUG`                  | 调试模式，输出 SQL   | false        |
+| `MYSQL_SLOW_SQL_WARN`          | 慢查询警告           | true         |
+| `MYSQL_SLOW_SQL_MS`            | 慢查询阈值（ms）     | 200          |
+| `MYSQL_TIMEZONE`               | 时区                 | +08:00       |
+| `MYSQL_VERSION_CONTROL_ENABLED`| 版本管理开启         | false        |
+| `MYSQL_VERSION_CONTROL_DIR`    | 迁移文件目录         | db_migration |
+| `MYSQL_TRANSACTION_TIMEOUT`    | 事务超时（ms）       | 5000         |
+| `MYSQL_TRANSACTION_STRICT`     | 事务严格模式         | true         |
+| `MYSQL_MAX_OPS_IN_STRICT_TX`   | 严格事务最大操作次数 | 10           |
+
+---
+
+## 初始化
+
+```ts
+import { enableMysql, getMysqlManager } from 'wok-server'
+
+await enableMysql()
+const manager = getMysqlManager()
+```
+
+多数据源（如读写分离等高级用法）见[参考文档](./references/multi-datasource.md)。
+
+---
+
+## 实体类配置
+
+表映射配置由 `Table<T>` 接口定义，字段分三部分：主键、普通列、时间列，三者不允许重叠。
+
+```ts
+import { Table } from 'wok-server'
+
+export interface User {
+  id: string
+  nickname: string
+  hobby?: string
+  create_at?: number
+  update_at?: number
+}
+
+export const tableUser: Table<User> = {
+  tableName: 'user',
+  id: 'id',
+  columns: ['nickname', 'hobby'],
+  createdDate: { type: 'number', column: 'create_at' },
+  updatedDate: { type: 'number', column: 'update_at' }
+}
+```
+
+`createdDate` 和 `updatedDate` 配置的字段由框架自动管理：`insert`/`insertMany` 时自动填入创建时间和更新时间，`update`/`partialUpdate`/`updateMany` 时自动更新 `updatedDate` 字段。业务代码中不需要手动设置这两个字段的值。
+
+> **⚠️ 重要：框架不支持字段名称映射。** 实体类型的字段名必须和数据库列名一模一样。比如数据库列名是 `entry_date`，实体字段不能写为 `entryDate` 或 `entryDate` 再用装饰器映射，必须是 `entry_date: Date`。如果之前用惯了其他 ORM 框架，很容易在这里习惯性写成驼峰而掉坑，务必注意。
+
+### 类型映射规则
+
+| JS 类型        | MySQL 字段类型                                                        |
+| :------------- | :------------------------------------------------------------------- |
+| `boolean`      | TINYINT                                                              |
+| `number`       | TINYINT, SMALLINT, INT, MEDIUMINT, YEAR, FLOAT, DOUBLE, BIGINT       |
+| `Date`         | TIMESTAMP, DATE, DATETIME                                             |
+| `Buffer`       | TINYBLOB, MEDIUMBLOB, LONGBLOB, BLOB, BINARY, VARBINARY, BIT         |
+| `string`       | CHAR, VARCHAR, TINYTEXT, MEDIUMTEXT, LONGTEXT, TEXT, ENUM, SET, DECIMAL, TIME |
+| `object`/`array` | JSON                                                                |
+
+实体字段类型必须与数据库列类型匹配对应的 JS 原生类型，否则查询结果会不正确。可空字段在实体中也定义为可选（`?`）。
+
+---
+
+## CRUD 操作
+
+所有操作以 `Table<T>` 为第一个参数。
+
+### 查询
+
+```ts
+const user = await manager.findById(tableUser, '001')           // 按 ID 查
+const users = await manager.findByIdIn(tableUser, ['001','002'])  // 批量 ID 查
+const list = await manager.findAll(tableUser)                   // ⚠️ 全表，危险
+```
+
+### 条件查询
+
+使用 `MysqlCriteria` 构建条件，默认 AND 关系：
+
+```ts
+const user = await manager.findFirst(tableUser, c =>
+  c.like('nickname', 'ff0%').gt('balance', 75).lt('balance', 77)
+)
+```
+
+**链式条件方法**：`eq`、`neq`、`gt`、`gte`、`lt`、`lte`、`like`、`notLike`、`between`、`in`、`notIn`、`isNull`、`isNotNull`、`or`、`and`。
+
+### 复杂查询
+
+```ts
+const list = await manager.find({
+  table: tableUser,
+  criteria: c => c.between('balance', 700, 800).like('id', 'find%'),
+  offset: 1,
+  limit: 10,
+  orderBy: [['balance', 'asc']]
+})
+```
+
+### 分页
+
+```ts
+const page = await manager.paginate({
+  table: tableUser,
+  criteria: c => c.like('id', 'pg0%'),
+  pn: 2, pz: 5,
+  orderBy: [['balance', 'asc'], ['id', 'asc']]
+})
+// { total: number, list: T[] }
+```
+
+### 插入
+
+```ts
+const newUser = await manager.insert(tableUser, { id: 'in001', nickname: '小明' })
+await manager.insertMany(tableUser, [
+  { id: 'im001', nickname: '张飞' },
+  { id: 'im002', nickname: '关羽' }
+])
+```
+
+### 更新
+
+```ts
+// 完整更新（需要完整文档）
+await manager.update(tableUser, { id: 'xxx', nickname: '王五' })
+
+// 局部更新（使用元组语法：['inc', 22] 表示 +22，[null] 表示置空）
+await manager.partialUpdate(tableUser, { id: 'pu000', balance: ['inc', 22] })
+
+// 批量更新
+await manager.updateMany(tableUser, c => c.like('nickname', 'um%'), { balance: ['inc', 2] })
+```
+
+### 删除
+
+```ts
+await manager.deleteById(tableUser, 'd0001')
+await manager.deleteMany({ table: tableUser, criteria: { status: 'DISABLED' }, limit: 100 })
+await manager.deleteOne(tableUser, { id: 'only_one' })
+```
+
+**⚠️ `deleteMany` 是危险操作**，建议严格限制条件并设置 `limit` 参数。
+
+### 自定义 SQL
+
+```ts
+// 查询
+const list = await manager.query<{ author: string; book: string }>(
+  'select u.nickname as author, b.name as book from ?? u left join ?? b on u.id=b.author_id where b.id is not null',
+  ['user', 'book']
+)
+
+// 修改
+const affected = await manager.modify(`update user set nickname='无名' where nickname='佚名'`)
+```
+
+### 全部方法
+
+| 方法           | 说明                         | 危险 |
+| :------------- | :--------------------------- | :--- |
+| `findById`     | 按 id 查询                   |      |
+| `findByIdIn`   | 批量 id 查询                 |      |
+| `findFirst`    | 查第一条符合条件的           |      |
+| `find`         | 条件查询，支持 offset/limit  | ⚠️   |
+| `findSelect`   | 条件查询，指定返回列         | ⚠️   |
+| `findAll`      | 全表查询                     | ⚠️   |
+| `existsBy`     | 条件判断存在                 |      |
+| `existsById`   | id 判断存在                  |      |
+| `count`        | 统计数量                     | ⚠️   |
+| `paginate`     | 分页查询                     | ⚠️   |
+| `insert`       | 插入单条                     |      |
+| `insertMany`   | 批量插入                     |      |
+| `update`       | 完整更新                     |      |
+| `partialUpdate`| 局部更新                     |      |
+| `updateOne`    | 更新第一条相等条件           |      |
+| `updateMany`   | 批量更新                     | ⚠️   |
+| `deleteById`   | 按 id 删除                   |      |
+| `deleteOne`    | 删除第一条相等条件           |      |
+| `deleteMany`   | 批量删除                     | ⚠️   |
+| `query`        | 自定义 SQL 查询              |      |
+| `modify`       | 自定义 SQL 修改              |      |
+
+---
+
+## JSON 类型支持
+
+在实体中直接定义 JSON 字段对应的 TS 类型即可，框架自动解析：
+
+```ts
+interface Question {
+  id: string
+  options: { title: string; correct?: boolean }[]
+}
+
+export const tableQuestion: Table<Question> = {
+  tableName: 'question', id: 'id', columns: ['options']
+}
+```
+
+条件查询支持 `json_extract` 和 `json_length`，使用元组代替列名：
+
+```ts
+await manager.findFirst(tableQuestion, c =>
+  c.eq(['json_extract', 'question_setter', '$.id'], 'x333')
+)
+await manager.findFirst(tableQuestion, c =>
+  c.gt(['json_length', 'options'], 3)
+)
+```
+
+---
+
+## 事务
+
+```ts
+await manager.tx(async session => {
+  await session.partialUpdate(tableAccount, { id: accId, balance: ['inc', -amount] })
+  await session.insert(tableOrder, { id: orderId, amount })
+}, { timeout: 3000 })
+```
+
+事务操作**必须使用 `session` 对象**，直接调用 `manager` 的方法不会在事务中生效。
+
+选项：
+- `timeout`：超时时间（ms），超时后自动回滚并抛出 `MysqlException`
+- `isolationLevel`：隔离级别（`REPEATABLE READ` 等）
+- `accessMode`：读写模式（`READ WRITE` / `READ ONLY`）
+
+### 严格模式
+
+`MYSQL_TRANSACTION_STRICT=true` 时启用严格模式，限制事务中的操作次数（`MYSQL_MAX_OPS_IN_STRICT_TX`，默认 10 次）。超限抛出 `MysqlException`。
+
+---
+
+## 内部实现要点
+
+### 连接管理
+
+`enableMysql` 注册配置 → 可选迁移 → 创建 `Pool` → 构建 `MysqlManager` → 存入 `managerMap`。进程退出前自动关闭连接池。
+
+### 查询流程
+
+`MysqlManager` 从连接池获取连接 → `Promise.race` 超时竞速 → 执行 SQL → 释放连接。
+
+### 慢查询
+
+所有 CRUD 操作（除自定义 SQL）自动计时，超过 `MYSQL_SLOW_SQL_MS` 时输出 WARN 日志。
+
+### Migration 实现
+
+版本管理的完整使用说明见[参考文档](./references/version-control.md)。
+
+---
+
+## 参考
+
+- [多数据源（读写分离等高级用法）](./references/multi-datasource.md)
+- [版本管理](./references/version-control.md)

package/skills/wok-server-mysql/references/multi-datasource.md

@@ -0,0 +1,76 @@
+# MySQL 多数据源
+
+## 启用多数据源
+
+```ts
+await enableMysql()          // 默认，以 MYSQL_ 为前缀
+await enableMysql('d2')      // 自定义，以 D2_ 为前缀
+
+const mgr1 = getMysqlManager()      // 默认
+const mgr2 = getMysqlManager('d2')  // d2
+```
+
+名称必须以英文字母开头，由字母数字下划线组成，不超过 32 位。环境变量前缀自动转换为大写。
+
+环境变量配置示例：
+
+```bash
+# 默认 enableMysql()，前缀 MYSQL_
+MYSQL_HOST=localhost
+MYSQL_PORT=3306
+MYSQL_USER=test
+MYSQL_PASSWORD=abc123
+MYSQL_DATABASE=test1
+
+# enableMysql('d2')，前缀 D2_
+D2_HOST=localhost
+D2_PORT=3306
+D2_USER=test2
+D2_PASSWORD=abcdefg
+D2_DATABASE=test2
+```
+
+---
+
+## 技巧：读写分离
+
+实体类的表配置（`Table<T>`）与数据库实例没有强制绑定关系，同一套表配置可以给多个 `MysqlManager` 使用。利用这个特性和多数据源，可以实现读写分离。
+
+```ts
+import { enableMysql, getMysqlManager } from 'wok-server'
+import { tableUser } from './user'
+
+// 主库（读写）
+await enableMysql('master')
+// 只读库
+await enableMysql('slave')
+
+const masterMgr = getMysqlManager('master')
+const slaveMgr = getMysqlManager('slave')
+
+// 写操作使用主库
+const newUser = await masterMgr.insert(tableUser, { id: '001', nickname: 'jack' })
+
+// 读操作使用只读库
+const user = await slaveMgr.findById(tableUser, '001')
+```
+
+环境变量分别配置两个源：
+
+```bash
+# 主库
+MASTER_HOST=master-db.example.com
+MASTER_PORT=3306
+MASTER_USER=writer
+MASTER_PASSWORD=xxx
+MASTER_DATABASE=mydb
+
+# 只读库
+SLAVE_HOST=slave-db.example.com
+SLAVE_PORT=3306
+SLAVE_USER=reader
+SLAVE_PASSWORD=xxx
+SLAVE_DATABASE=mydb
+```
+
+在 `main.ts` 入口中分别初始化后，将两个 manager 导出，业务模块按读写需求选择使用即可。

package/skills/wok-server-mysql/references/version-control.md

@@ -0,0 +1,22 @@
+# MySQL 版本管理
+
+开启 `MYSQL_VERSION_CONTROL_ENABLED=true`，在 `db_migration/` 目录下创建 SQL 文件，文件名为纯数字：
+
+```
+db_migration/
+  1.sql        # 版本号从 1 开始，必须连续递增
+  2.sql
+  3.sql
+```
+
+文件名必须是纯数字 + `.sql` 后缀（如 `1.sql`、`2.sql`），非数字前缀会导致 `parseInt` 失败而抛异常。编号必须从 1 开始连续递增，不连续也会抛异常。
+
+启动时自动在事务中检测当前版本，顺序执行未执行的 SQL 并更新版本号。
+
+版本信息存储在 `db_version` 表（单行 `key='db_version'`，`version` 列）。
+
+> **⚠️ 注意事项：开销非常高的 SQL 不能放在版本管理中执行。** 比如在大表上创建/修改索引这类操作，执行耗时长且会锁表，可能阻塞线上服务。此类操作应单独在线上手动执行，不要放入迁移文件。
+
+## 实现细节
+
+使用独立的 `multipleStatements` 连接在事务中执行：读取当前版本 → 筛选待执行版本 → 逐个执行 SQL 并更新 `db_version` → 提交。出错需手动在数据库中修复后重新启动。