wok-server 0.7.1 → 0.8.0

package/skills/wok-server-api-rules/SKILL.md

@@ -242,6 +242,119 @@ await startWebServer({
 
 ---
 
+## 规则 5：MySQL 更新方法传参——利用框架自动忽略 `undefined`
+
+wok-server MySQL 组件会自动忽略值为 `undefined` 的字段，**不要**手动构建 `updateData` 对象：
+
+```ts
+// ❌ 啰嗦，不推荐
+const updateData: Partial<Knowledge> = {}
+if (body.name !== undefined) updateData.name = body.name
+if (body.desc !== undefined) updateData.desc = body.desc
+
+await session.updateOne(tableKnowledge, where, updateData)
+
+// ✅ 简洁直观，推荐
+await session.updateOne(tableKnowledge, where, {
+  name: body.name,
+  desc: body.desc,
+  question_prompt: body.question_prompt
+})
+```
+
+---
+
+## 规则 6：MySQL 更新接口参数必填性——与实体类保持一致
+
+更新接口中出现的字段，其必填性应与实体类一致。实体中必填的字段，在更新接口中不应设为可选：
+
+```ts
+// ❌ 不推荐：name 在实体中是必填，这里却设成了可选
+interface UpdateForm {
+  id: string
+  name?: string
+  desc?: string
+}
+
+// ✅ 推荐：出现的字段与实体类保持一致的必填性
+interface UpdateForm {
+  id: string
+  name: string
+  desc?: string
+}
+```
+
+---
+
+## 规则 7：Entity 状态字段约束——禁止 `string`，必须使用联合类型
+
+Entity 中的**状态字段禁止使用 `string` 类型**，必须使用**联合类型**精确约束所有合法值：
+
+```ts
+// ❌ 错误：使用 string 类型，没有任何约束
+interface ChatbotSession {
+  status: string  // 任何字符串都可以通过编译
+}
+
+// ✅ 正确：使用联合类型，精确约束
+interface ChatbotSession {
+  /**
+   * 会话状态
+   */
+  status: '临时' | '活跃'
+}
+
+interface Chatbot {
+  /**
+   * 状态
+   */
+  status: '未发布' | '已发布'
+}
+```
+
+**为什么必须这样做**：联合类型提供编译期检查，`string` 类型允许任何值，一旦写错（如 `'temprary'` vs `'临时'`）不会报错，运行时难以排查。
+
+**检查方法**：定义或修改 Entity 时，检查每个 `status` 字段，确保它是联合类型而非 `string`。
+
+---
+
+## 规则 8：API Response 接口中枚举/联合类型必须引用实体类型
+
+在 API 的 Response 接口中定义字段时：
+- **枚举/联合类型字段**（如 `status`、`type`）**必须引用实体的类型定义**，禁止手写字面量值或使用 `number`/`string`
+- **原始类型字段**（如 `number`、`string`、`boolean`）直接用原始类型，不要过度引用
+
+```ts
+// ❌ 错误：手写字面量值，与实体定义脱节
+interface Resp {
+  status?: number  // number 无法约束合法值
+  learning_task?: {
+    type: '视频' | '文档' | '考试'  // 实体变了这里不会同步
+  }
+}
+
+// ❌ 错误：原始类型也去引用实体，过度设计
+interface Resp {
+  duration: LearningTask['duration']  // duration 本来就是 number，没必要
+}
+
+// ✅ 正确：枚举/联合类型引用实体，原始类型直接用
+import { User } from '../../user'
+import { LearningTask } from '../learning_task/learning-task'
+
+interface Resp {
+  status?: User['status']              // 引用实体的联合类型
+  learning_task?: {
+    type: LearningTask['type']         // 引用实体的联合类型
+    duration: number                   // 原始类型直接用
+  }
+}
+```
+
+**为什么**：联合类型的手写字面量会与实体定义脱节。当实体新增/修改合法值时，Response 接口不会被同步更新，导致类型泄露。引用实体类型确保两者始终一致。
+
+---
+
 ## 附录 A：ServerExchange 速查表
 
 所有路由 handler 和拦截器都通过 `ServerExchange` 与请求/响应交互。以下是其完整方法列表，禁止使用表中未列出的方法。

package/skills/wok-server-code-navigation/SKILL.md

@@ -11,143 +11,217 @@ metadata:
 
 ## 概述
 
-面对一个 wok-server 项目时，按以下路径快速理解项目结构、定位目标代码。核心原则：**项目按功能划分目录，路由集中配置，每个接口/拦截器独立一个文件**。
+面对一个基于 wok-server 的项目时，按以下路径快速理解项目结构、定位目标代码。核心原则：**项目按功能划分目录，路由集中配置，每个接口/拦截器独立一个文件**。
 
-## 项目入口 — main.ts
+## 通用
 
-入口文件在 `src/main.ts`，包含：
+### 找到后端代码位置
 
-1. 全局初始化（如 `Date.prototype.toJSON`、`enableMysql()`）
-2. `startWebServer()` 调用，配置 routers 和 interceptors
-3. 任务调度（`scheduleWithFixedDelay` 等）
+一个项目可能前后端分离，也可能前端项目合并在同一个仓库。按以下顺序排查：
 
-**所以 `main.ts` 是读懂项目的第一个文件**。从这里可以看到所有路由映射和拦截器链。
+#### 1. 检查根目录
 
-## 路由定位决策树
+查看项目根目录是否有 `package.json`：
 
+```bash
+ls package.json
 ```
-要找一个接口的处理逻辑？
-  → 打开 src/main.ts（或 src/router.ts）
-  → 找到路由对象中对应路径的 key
-  → 看它的 value（通常是 import 的 handler 函数）
-  → Ctrl/Cmd + 点击跳转到 handler 文件
+
+如果有，搜索其中是否依赖了 `wok-server`：
+
+```bash
+grep -o '"wok-server"' package.json
 ```
 
-路由集中在一个地方，所以**搜路由路径就能找到对应 handler 的 import**。
+如果匹配，说明根目录就是后端项目，后端代码就在根目录。
+
+#### 2. 检查 backend / server 目录
 
-## 文件定位速查表
+如果根目录没有 `package.json` 或没有安装 wok-server，查找 `backend/` 或 `server/` 子目录：
 
-| 想找什么                 | 去哪里找                                                       |
-| ------------------------ | -------------------------------------------------------------- |
-| 入口、路由注册、启动逻辑 | `src/main.ts`                                                  |
-| 路由配置（大项目）       | `src/router.ts` 或 `src/router/` 目录                          |
-| 某个接口的处理逻辑       | `src/{功能名}/{接口名}.ts`（如 `src/user/create-user.ts`）     |
-| 拦截器                   | `src/{功能名}/{拦截器名}-interceptor.ts` 或 `src/exception.ts` |
-| 数据库实体与表定义       | `src/{功能名}/{功能名}.ts`（如 `user/user.ts`）                |
-| MySQL 迁移脚本           | `db_migration/` 目录                                           |
-| 环境变量                 | 项目根目录 `.env`                                              |
+```bash
+ls backend/package.json
+```
 
-## 目录结构速览
+搜索其中是否依赖了 `wok-server`。例如一个前后端分离的项目，后端代码可能在 `backend/` 目录：
 
 ```
-根目录
-  ├── db_migration/          # MySQL 迁移文件
+backend/
+  ├── package.json      # 包含 "wok-server": "^0.5.0"
   ├── src/
-  │   ├── auth/              # 授权功能
-  │   │   ├── auth.ts               # 实体配置（表结构）
-  │   │   ├── auth-interceptor.ts   # 授权拦截器
-  │   │   ├── create-auth.ts        # 创建授权接口
-  │   │   └── index.ts              # 包入口，聚合导出
-  │   ├── user/              # 用户功能
-  │   │   ├── user.ts
-  │   │   ├── create-user.ts
-  │   │   └── index.ts
-  │   ├── exception.ts       # 全局异常定义 + 异常拦截器
-  │   ├── router.ts          # 路由集中配置（大项目）
-  │   └── main.ts            # 入口文件（小项目路由也在这里）
-  ├── .env
-  ├── package.json
-  └── tsconfig.json
+  ├── db-migration/
+  └── docker/
 ```
 
-## 阅读项目的步骤
+#### 3. 如果以上都行不通
 
-### 第一步：看 main.ts
+- 搜索项目中的 `wok-server` 关键词（如 `from 'wok-server'`）
+- 搜索 `startWebServer` 函数调用，这是 wok-server 的入口 API
+- 搜索 `createJsonHandler`、`Table<`、`Routers` 等 wok-server 特有类型
 
-打开 `src/main.ts`，关注三个区域：
+> **确定了后端代码目录后**，后续所有文件路径都相对于该目录（以下称为**项目根目录**）。
 
-1. **顶部 import** — 了解项目用了哪些 wok-server 功能模块（MySQL？MongoDB？Task？）
-2. **startWebServer() 调用** — 了解有哪些路由和拦截器
-3. **任务调度调用** — 了解有哪些定时任务
+### 真实项目结构示例
 
-### 第二步：看路由表
+一个典型 wok-server 中型项目的目录结构（仅作参考，实际项目可能不同）：
 
-从 `main.ts` 的 routers 对象中找到你关心的路径，跳转到对应 handler。
+```
+backend/
+  ├── db-migration/              # MySQL 迁移文件
+  └── src/
+      ├── main.ts                # 入口文件
+      ├── exception.ts           # 全局异常定义 + 异常拦截器
+      ├── router/
+      │   ├── json-handler.ts    # 自定义 handler 工厂（二次封装）
+      │   └── rules/             # 按业务模块拆分的路由规则
+      │       ├── index.ts       # 聚合所有模块路由
+      │       ├── contact.ts     # 联系人模块路由
+      │       └── order.ts       # 订单模块路由
+      ├── contact/               # 联系人业务模块
+      │   ├── contact.ts         # 数据实体 & 表定义
+      │   ├── contact-service.ts # 业务逻辑层
+      │   ├── bs-contact-create.ts
+      │   ├── bs-contact-get.ts
+      │   ├── field/             # 子功能：自定义字段
+      │   └── log/               # 子功能：操作日志
+      ├── order/                 # 订单模块
+      ├── auth/                  # 授权模块
+      ├── redis/                 # Redis 基础设施（项目扩展）
+      └── ali-oss/               # OSS 基础设施（项目扩展）
+```
 
-### 第三步：看拦截器链
+### 搜索技巧
 
-从 `main.ts` 的 interceptors 数组了解请求处理流程。典型链路：
+如果以上方法定位不到文件，全文搜索以下关键词：
 
-```
-请求 → globalErrorInterceptor → authInterceptor → handler
-```
+1. **路由路径字符串** — 一定能找到 handler 的 import 来源（因为 wok-server 路由使用完整路径作为 key）
+2. `createJsonHandler` —— 列出直接使用内置工厂的 JSON 接口
+3. `create.*Handler` —— 发现自定义封装的 handler 工厂及使用位置
+4. `Table<` —— 列出所有数据表定义
+5. `Interceptor` —— 列出所有拦截器
+6. `schedule` —— 列出所有定时任务
+7. `from 'wok-server'` —— 列出所有使用 wok-server API 的文件
 
-### 第四步：按需看业务目录
+## MVC（路由 / 拦截器 / Handler）
 
-根据 handler 文件所在的目录，查看同目录下的：
+### 项目入口 — main.ts
 
-- `{功能}.ts` — 了解数据实体结构
-- `{功能}-interceptor.ts` — 了解功能级拦截逻辑
-- 其他 handler 文件 — 了解该功能的完整接口
+入口文件在 `src/main.ts`，包含以下典型结构（以真实项目为例）：
 
-## 常见查找场景
+```ts
+// 1. 全局初始化
+Date.prototype.toJSON = function () { return this.getTime() as any }
+process.on('uncaughtException', err => getLogger().error('未捕获的异常', err))
+
+// 2. 启用基础设施
+await enableRedis()       // 项目扩展的，非框架内置
+await enableMysql()       // wok-server 框架自带的
+await enableAliOss()      // 项目扩展的，非框架内置
+
+// 3. 启动 Web 服务 —— 配置路由和拦截器
+await startWebServer({
+  interceptors: [globalErrorInterceptor],
+  routers: { '/': homepage, ...routers }
+})
+
+// 4. 定时任务
+scheduleWithFixedDelay(30, 30, new MessageQueueTask({...}))
+scheduleDailyTask(3, 0, new CorpFileCleanTask())
+```
+
+**所以 `main.ts` 是读懂项目的第一个文件**。从它可以看到：
+- 项目用了哪些基础设施（框架自带的如 `enableMysql()`，项目扩展的如 `enableRedis()`、`enableAliOss()`）
+- **拦截器链**：`interceptors` 数组定义了请求处理流程，例如 `请求 → globalErrorInterceptor → handler`
+- **路由入口**：`routers` 对象指明了路由配置的位置
+- **定时任务**：`scheduleWithFixedDelay`、`scheduleDailyTask` 等
 
-### 场景 1：我要改一个接口的逻辑
+### 从接口路径定位 handler（最可靠的方法）
 
-1. 从路由路径反查 handler 文件（搜路径字符串）
-2. 打开 handler 文件，找到 `handle()` 函数体
-3. 修改逻辑
+wok-server 的路由配置使用接口完整路径作为 key，所以**在 `src/` 目录下搜索接口路径字符串，就能直接定位到 handler 的 import 位置**。不需要依赖固定的文件名或目录结构。
+
+```
+要找一个接口的处理逻辑？
+  → 在 src/ 目录下搜索接口完整路径（如 '/bs/contact/create'）
+  → 找到匹配的路由配置位置
+  → 在该行看到 handler 的 import 来源
+  → Ctrl/Cmd + 点击跳转到 handler 文件
+```
 
-### 场景 2：我要新增一个接口
+#### 关键原则
 
-1. 在对应功能目录下新建 `xxx.ts`
-2. 用 `createJsonHandler` 或其他工厂函数创建 handler
-3. 在 `src/main.ts` 或 `src/router.ts` 中注册路由
+- **最可靠的方式**：从 `startWebServer()`（在 `src/main.ts`）的 `routers` 属性出发，这是路由配置的入口锚点，永远有效。
+- **不要依赖固定的文件或目录名**：项目可能将路由写在 `src/main.ts`、`src/router.ts` 或 `src/router/rules/` 目录下，具体位置取决于项目规模。
+- **wok-server 路由使用完整路径作为 key**，不会分散配置，所以搜索路径字符串一定能找到。
 
-### 场景 3：我要查某个表的结构
+例如搜索 `/bs/contact/create` 就能在路由文件中找到：
 
-1. 找 `src/{功能名}/{功能名}.ts`（如 `user/user.ts`）
-2. 查看 `Table` 对象定义（表名、列、ID 字段等）
+```ts
+'/bs/contact/create': bsContactCreate,  // ← 直接看到 handler 名及其 import 来源
+```
 
-### 场景 4：项目可能封装了自定义 Handler
+路由文件的形态取决于项目规模：
 
-wok-server 内置的 handler 工厂函数（`createJsonHandler`、`createUploadHandler`、`createSseHandler`、`restful`）在真实项目中经常被二次封装。例如：
+- **小型项目**：路由可能直接写在 `src/main.ts` 里
+- **中型项目**：每个业务模块一个路由文件，通过 `...` 展开符合并导出
 
 ```ts
-// 项目可能定义了 createAuthJsonHandler，在 createJsonHandler 基础上注入用户信息
-export function createAuthJsonHandler<Req, Resp>(opts) {
-  return createJsonHandler<Req, Resp>({
-    ...opts,
-    async handle(body, exchange) {
-      const auth = new Auth(exchange) // 增加 auth 信息
-      return opts.handle(body, exchange, auth)
-    }
-  })
+// router/rules/contact.ts
+export const contactRouters: Routers = {
+  '/bs/contact/create': bsContactCreate,
+  '/bs/contact/delete': bsContactDelete,
+  '/bs/contact/get': bsContactGet,
+  // ...
 }
 ```
 
-**面对一个项目时，先搜索以下关键词，判断项目是否有自定义封装：**
 
-- 搜 `createJsonHandler` —— 如果没有匹配，说明项目可能用了自定义封装
-- 搜 `create.*Handler` 或 `create.*Json` —— 发现自定义的 handler 工厂函数
-- 搜 `from 'wok-server'` 中的 `createJsonHandler` —— 确认哪些文件直接用了内置版本
-- 后续搜索接口文件时，用自定义函数名而非内置名
+## MySQL
 
-### 场景 5：找不到目标文件？
+### 通过 SQL 迁移文件了解全局业务
+
+SQL 迁移文件记录了完整的建表语句，可以从中了解项目涉及的所有业务表。查找方式如下：
+
+1. 打开项目根目录下的 `.env` 文件
+2. 查看 `MYSQL_VERSION_CONTROL_ENABLED` 变量是否为 `true`
+3. 如果为 `true`，再看 `MYSQL_VERSION_CONTROL_DIR` 变量配置的迁移文件目录（如未设置，默认为 `db_migration`）
+4. 如果 `.env` 不存在或 `MYSQL_VERSION_CONTROL_ENABLED` 不为 `true`，说明项目没有使用版本控制，即没有 SQL 迁移文件
+
+通过迁移文件的建表语句，可以看到每个表的完整字段定义、索引、外键等，比实体 `interface` 更全面，有助于先对项目业务有个大致的了解。
+
+### 通过实体文件查表结构
+
+知道表名查配置，最快的方式是搜索 `tableName`，但不同项目的代码格式化风格可能不同（空格、引号），建议用正则搜索提高容错：
+
+```
+搜索正则可匹配 tableName\s*:\s*['"]表名['"]
+```
+
+例如搜索 `tableName:\s*['"]contact['"]`（注意正则中 `\s*` 可以匹配任意数量的空格，`['"]` 可以匹配单引号或双引号），找到匹配位置后，确认满足以下两个条件就是表的配置：
+
+1. 该 `tableName` 所属的常量声明是 `Table<表类型>` 类型，例如 `export const tableContact: Table<Contact>`
+2. `Table` 导入自 `wok-server`（即 `import { Table } from 'wok-server'`）
+
+满足这两点，就找到了完整的表配置，从中可以看到表名、主键 ID、字段列表、时间戳配置等信息。
+
+示例代码结构：
+
+```ts
+import { Table } from 'wok-server'
+
+export interface Contact {
+  id: string
+  corp_id: string
+  name: string
+  // ...
+}
+
+export const tableContact: Table<Contact> = {
+  tableName: 'contact',   // ← 搜这个字符串找到这里
+  id: 'id',               // 主键字段
+  columns: ['corp_id', 'name', /* ... */],
+  createdDate: { type: 'date', column: 'create_at' },
+  updatedDate: { type: 'date', column: 'update_at' }
+}
+```
 
-1. **首先检查路由注册** — 搜路由路径字符串，定位 handler 的 import 来源
-2. 全文搜索 `createJsonHandler` —— 列出直接使用内置工厂的 JSON 接口
-3. 全文搜索 `create.*Handler` —— 发现自定义封装的 handler 工厂及使用位置
-4. 全文搜索 `Table<` —— 列出所有数据表定义
-5. 全文搜索 `Interceptor` —— 列出所有拦截器
-6. 全文搜索 `schedule` —— 列出所有定时任务
+业务逻辑层通常在 `src/{功能名}/{功能名}-service.ts`。

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

@@ -106,7 +106,6 @@ export const tableUser: Table<User> = {
 
 | 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         |
@@ -115,6 +114,21 @@ export const tableUser: Table<User> = {
 
 实体字段类型必须与数据库列类型匹配对应的 JS 原生类型，否则查询结果会不正确。可空字段在实体中也定义为可选（`?`）。
 
+> **⚠️ `boolean` 类型安全警告**
+>
+> MySQL 的 `BOOLEAN` 实际是 `TINYINT(1)`，驱动返回 `0`/`1`（number），**不是** `true`/`false`。
+> 实体类中将字段声明为 `boolean` 会导致 `===` 全等比较出现 bug，且手写 SQL 查询同样存在此问题。
+>
+> 框架**不提供**类型自动映射。最安全的做法是使用 `0 | 1` 类型，与数据库真实返回值保持一致：
+>
+> ```ts
+> export interface User {
+>   is_active: 0 | 1  // 推荐
+> }
+> ```
+>
+> `0 | 1` 在条件判断中与 `boolean` 行为一致，仅在 `=== true/false` 时有差异。
+
 ---
 
 ## CRUD 操作
@@ -197,17 +211,9 @@ await manager.insertMany(tableUser, [
   { id: 'im001', nickname: '张飞' },
   { id: 'im002', nickname: '关羽' }
 ])
-
-// 插入时使用表达式（InsertValue）
-await manager.insert(tableUser, {
-  id: 'in002',
-  nickname: '小红',
-  balance: ['expr', '?? * ?', ['score', 2]],
-  createAt: ['now']
-})
 ```
 
-支持三种表达式：`['now']`（NOW()）、`['set', value]`（解决元组冲突）、`['expr', sql, values?]`（自定义 SQL）。
+`insert` 要求传入完整的实体对象，必填字段必须存在，返回的对象是真实的 `T` 类型。
 
 ### Upsert
 

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

@@ -1,15 +1,17 @@
 # MySQL 版本管理
 
-开启 `MYSQL_VERSION_CONTROL_ENABLED=true`，在 `db_migration/` 目录下创建 SQL 文件，文件名为纯数字：
+开启 `MYSQL_VERSION_CONTROL_ENABLED=true`，在 `db_migration/` 目录下创建 SQL 文件，文件名必须以数字开头，数字后可加描述文字：
 
 ```
 db_migration/
-  1.sql        # 版本号从 1 开始，必须连续递增
-  2.sql
-  3.sql
+  1.sql                 # 等价于版本号 1
+  2_init.sql            # 等价于版本号 2
+  3_add_user_index.sql  # 等价于版本号 3
 ```
 
-文件名必须是纯数字 + `.sql` 后缀（如 `1.sql`、`2.sql`），非数字前缀会导致 `parseInt` 失败而抛异常。编号必须从 1 开始连续递增，不连续也会抛异常。
+版本号必须从 1 开始连续递增。文件名示例：`1.sql`、`2_init.sql`、`3_add_user_index.sql`。不支持 `v1.sql` 或 `init_v1.sql` 这类不以数字开头的命名。
+
+> **⚠️ 重复版本号校验**：如果有两个文件解析出版本号相同（如 `1_init.sql` 和 `1_create_table.sql` 都对应版本 1），启动时会抛异常，并明确指出冲突的文件路径。
 
 启动时自动在事务中检测当前版本，顺序执行未执行的 SQL 并更新版本号。
 

package/src/http-client/index.ts

@@ -1,6 +1,5 @@
-import { IncomingHttpHeaders, request as requestHttp, Agent as HttpAgent } from 'http'
-import { request as requestHttps, Agent as HttpsAgent } from 'https'
-import { URL } from 'url'
+import { Agent as HttpAgent, IncomingHttpHeaders, request as requestHttp } from 'http'
+import { Agent as HttpsAgent, request as requestHttps } from 'https'
 
 /**
  * 请求选项.
@@ -141,7 +140,7 @@ export function doRequest(opts: HttpRequestOpts): Promise<HttpResponseInfo> {
  * @param opts
  */
 export async function postJson<T>(
-  opts: Pick<HttpRequestOpts, 'url' | 'query' | 'headers' | 'timeout'> & { body: any }
+  opts: Pick<HttpRequestOpts, 'url' | 'query' | 'headers' | 'timeout' | 'agent'> & { body: unknown }
 ): Promise<T> {
   const headers = Object.assign({}, opts.headers || {}, {
     'Content-Type': 'application/json; charset=utf-8'
@@ -153,7 +152,8 @@ export async function postJson<T>(
     timeout: opts.timeout,
     method: 'POST',
     body: JSON.stringify(opts.body),
-    followRedirect: false
+    followRedirect: false,
+    agent: opts.agent
   })
   if (res.status !== 200) {
     if (res.body.byteLength < 1024) {
@@ -178,7 +178,7 @@ export async function postJson<T>(
  * @param opts
  */
 export async function getJson<T>(
-  opts: Pick<HttpRequestOpts, 'url' | 'query' | 'headers' | 'timeout'>
+  opts: Pick<HttpRequestOpts, 'url' | 'query' | 'headers' | 'timeout' | 'agent'>
 ): Promise<T> {
   const res = await doRequest({
     url: opts.url,
@@ -186,7 +186,8 @@ export async function getJson<T>(
     headers: opts.headers,
     timeout: opts.timeout,
     method: 'GET',
-    followRedirect: true
+    followRedirect: true,
+    agent: opts.agent
   })
   if (res.status !== 200) {
     if (res.body.byteLength < 1024) {

package/src/lock/index.ts

@@ -14,6 +14,9 @@ export interface LockInfo {
 /**
  * 锁管理器，主要用于将不确定的顺序且有冲突的异步操作顺序执行，
  * 防止异步流程庞大穿插执行造成的数据混乱和错误，常见于请求的处理。
+ *
+ * ⚠️ 注意：这是一个本地内存锁，仅在当前进程内生效，不支持分布式场景。
+ * 如果需要在多进程、多服务器环境下使用，请使用 Redis 等分布式锁方案。
  */
 class ServerLockManager {
   /**
@@ -23,7 +26,7 @@ class ServerLockManager {
 
   constructor() {
     // 定期清理，将过期的信息移除，防止内存泄漏
-    setTimeout(() => {
+    setInterval(() => {
       const keysToBeDeleted: string[] = []
       const now = Date.now()
       for (const entry of this.lockMap.entries()) {
@@ -144,7 +147,7 @@ class ServerLockManager {
    */
   private sleep() {
     return new Promise<void>((resolve, reject) => {
-      setTimeout(resolve, 0)
+      setTimeout(resolve, 50)
     })
   }
 }

package/src/mvc/config.ts

@@ -41,6 +41,11 @@ export interface WebConfig {
    * pem 格式证书私钥文件路径
    */
   tlsKey: string
+  /**
+   * 请求体最大大小（字节），超出返回 413 Payload Too Large。
+   * 默认 10MB，设置为 0 表示不限制。
+   */
+  maxBodySize: number
 }
 
 export function getConfig() {
@@ -54,7 +59,8 @@ export function getConfig() {
       corsAllowOrigin: '*',
       tlsEnable: false,
       tlsKey: '',
-      tlsCert: ''
+      tlsCert: '',
+      maxBodySize: 10 * 1024 * 1024
     },
     'SERVER',
     {
@@ -64,7 +70,8 @@ export function getConfig() {
       corsAllowOrigin: [notBlank()],
       corsAllowHeaders: [notBlank()],
       corsAllowMethods: [notBlank()],
-      tlsEnable: [notNull()]
+      tlsEnable: [notNull()],
+      maxBodySize: [notNull(), min(0)]
     }
   )
 }