vite-plugin-ai-mock 0.1.4 → 1.0.0

package/README.md

@@ -8,12 +8,13 @@
 [![CI](https://img.shields.io/github/actions/workflow/status/quanzhiyuan/vite-plugin-ai-mock/ci.yml?label=CI)](https://github.com/quanzhiyuan/vite-plugin-ai-mock/actions)
 [![license](https://img.shields.io/npm/l/vite-plugin-ai-mock)](./LICENSE)
 
-A standalone Vite plugin for AI scene mocking. Returns streaming data in JSON format, simulating various AI scenarios.
+A standalone Vite plugin for AI scene mocking. Supports both JSON and TypeScript mock files, returning SSE streaming or JSON responses to simulate various AI scenarios.
 
-- Reads mock files from `mock/ai/*.json`
+- Reads mock files from `mock/*.json` or `mock/*.ts`
 - Returns SSE streaming response by default
 - Use `?transport=json` to get JSON format response
 - Supports 11 streaming scenarios with request parameters
+- TypeScript mock files support dynamic data and full middleware control — **hot-reloaded without server restart**
 
 ## Install
 
@@ -33,19 +34,20 @@ pnpm add vite-plugin-ai-mock -D
 project/
 ├── mock/
 │   └── ai/
-│       ├── chat.json
+│       ├── chat.json        ← JSON mock
+│       ├── sessions.ts      ← TypeScript mock
 │       └── default.json
 ├── src/
 └── vite.config.ts
+```
 
+**Request Example**
 
-
-
-
-
-
-
-
+```ts
+// SSE streaming (default)
+const res = await fetch("/api/chat");
+// JSON response
+const json = await fetch("/api/chat?transport=json");
 ```
 
 </td>
@@ -60,14 +62,14 @@ import { aiMockPlugin } from "vite-plugin-ai-mock";
 export default defineConfig({
   plugins: [
     aiMockPlugin({
-      dataDir: "mock/ai",
-      endpoint: "/api/mock/ai",  // /api/mock/ai/chat → chat.json
+      dataDir: "mock",
+      endpoint: "/api", // /api/chat → chat.json
     }),
   ],
 });
 ```
 
-**mock/ai/chat.json**
+**mock/chat.json**
 
 ```json
 {
@@ -86,6 +88,75 @@ export default defineConfig({
 
 > 💡 See full examples: [examples](https://github.com/quanzhiyuan/vite-plugin-ai-mock/tree/main/examples) (includes Ant Design X, Assistant UI, Lobe Chat integrations)
 
+## TypeScript Mock Files
+
+In addition to `.json` files, mock files can be written in TypeScript. `.ts` takes priority over `.json` when both exist.
+
+Three export patterns are supported:
+
+### Pattern 1 — Static default export (same as JSON)
+
+```ts
+// mock/ai/chat.ts
+export default {
+  chunks: [
+    { id: "1", data: { delta: "Hello" } },
+    { id: "2", data: { delta: " World" } },
+  ],
+};
+```
+
+### Pattern 2 — Factory function (called per request)
+
+The function receives the incoming request and can return dynamic data. Supports `async`.
+
+```ts
+// mock/ai/chat.ts
+import type { Connect } from "vite";
+
+export default (req: Connect.IncomingMessage) => {
+  const url = new URL(req.url ?? "/", "http://localhost");
+  const lang = url.searchParams.get("lang") ?? "en";
+  return {
+    chunks: [
+      { id: "1", data: { delta: lang === "zh" ? "你好" : "Hello" } },
+    ],
+  };
+};
+```
+
+### Pattern 3 — Handler (full middleware control)
+
+Replaces the need to write a separate `configureServer` plugin. Receives `(req, res, next)` and handles the response directly — ideal for dynamic routes like session create/delete.
+
+```ts
+// mock/ai/session.ts
+import type { MockRequestHandler } from "vite-plugin-ai-mock";
+
+const sessions = new Set<string>();
+
+export const handler: MockRequestHandler = (req, res) => {
+  if (req.method === "POST") {
+    const id = `sess-${Date.now()}`;
+    sessions.add(id);
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ status: "success", data: { session_id: id } }));
+    return;
+  }
+  if (req.method === "DELETE") {
+    const id = (req.url ?? "").split("/").pop() ?? "";
+    sessions.delete(id);
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ status: "success" }));
+    return;
+  }
+  res.statusCode = 405;
+  res.end();
+};
+```
+
+**Hot reload**: TypeScript mock files are loaded via Vite's `ssrLoadModule`. Any edit is picked up on the next request — **no server restart required**.
+
 ## Scenarios (11)
 
 1. Normal completion (default)
@@ -114,20 +185,20 @@ Scenarios can be configured in two ways, in order of precedence:
 Append parameters directly to the request URL, useful for debugging a single endpoint:
 
 ```
-/api/mock/ai/default?scenario=jitter
-/api/mock/ai/default?firstChunkDelayMs=1000&errorAt=3
+/api/default?scenario=jitter
+/api/default?firstChunkDelayMs=1000&errorAt=3
 ```
 
 ```ts
 // Default returns SSE streaming response
-const response = await fetch("/api/mock/ai/default?firstChunkDelayMs=4800", {
+const response = await fetch("/api/default?firstChunkDelayMs=4800", {
   method: "POST",
   headers: { "Content-Type": "application/json" },
   body: JSON.stringify({}),
 });
 
 // Use ?transport=json to get JSON format
-const jsonResponse = await fetch("/api/mock/ai/default?transport=json");
+const jsonResponse = await fetch("/api/default?transport=json");
 ```
 
 **2. Plugin option `defaultScenario` (global)**
@@ -150,9 +221,26 @@ aiMockPlugin({
 
 When `defaultScenario` is not set, the `normal` scenario is used (no delay, completes normally).
 
+**3. Plugin option `jsonApis` (specify JSON-returning APIs)**
+
+Configure in `vite.config.ts` to specify which API paths should return JSON format instead of SSE:
+
+```ts
+aiMockPlugin({
+  endpoint: "/api",
+  jsonApis: [
+    "/api/config", // exact match
+    "/api/history", // exact match
+    /^\/api\/static\/.*/, // regex match
+  ],
+});
+```
+
+Precedence: `?transport=json` / `?transport=sse` > `jsonApis` config > default SSE
+
 ## Mock file format
 
-Each file is a JSON object with a `chunks` array. Every chunk maps to one SSE event:
+Each mock file is a JSON object (or TypeScript module) with a `chunks` array. Every chunk maps to one SSE event:
 
 | Field     | Type   | Description                                                     |
 | --------- | ------ | --------------------------------------------------------------- |
@@ -175,18 +263,18 @@ Each file is a JSON object with a `chunks` array. Every chunk maps to one SSE ev
 
 ### Real-world format examples
 
-The `data` field can mirror any real API response. The package ships with ready-to-use examples in `mock/ai/` — copy them into your project as a starting point:
+The `data` field can mirror any real API response. The package ships with ready-to-use examples in `mock/` — copy them into your project as a starting point:
 
-| File                             | Provider            |
-| -------------------------------- | ------------------- |
-| `mock/ai/openai.json`            | OpenAI / compatible |
-| `mock/ai/claude.json`            | Anthropic Claude    |
-| `mock/ai/gemini.json`            | Google Gemini       |
-| `mock/ai/deepseek.json`          | DeepSeek            |
-| `mock/ai/deepseek-reasoner.json` | DeepSeek Reasoner   |
-| `mock/ai/qwen.json`              | Qwen (Alibaba)      |
-| `mock/ai/qwen-thinking.json`     | Qwen Thinking       |
-| `mock/ai/doubao.json`            | Doubao (ByteDance)  |
+| File                        | Provider            |
+| --------------------------- | ------------------- |
+| `mock/openai.json`          | OpenAI / compatible |
+| `mock/claude.json`          | Anthropic Claude    |
+| `mock/gemini.json`          | Google Gemini       |
+| `mock/deepseek.json`        | DeepSeek            |
+| `mock/deepseek-reasoner.json` | DeepSeek Reasoner |
+| `mock/qwen.json`            | Qwen (Alibaba)      |
+| `mock/qwen-thinking.json`   | Qwen Thinking       |
+| `mock/doubao.json`          | Doubao (ByteDance)  |
 
 **OpenAI / compatible** (`openai.json`) — `data` ends with `"[DONE]"` string:
 
@@ -278,7 +366,7 @@ import { DefaultChatTransport } from "ai";
 
 const { messages, sendMessage, status } = useChat({
   transport: new DefaultChatTransport({
-    api: "/api/mock/ai/chat",
+    api: "/api/chat",
   }),
 });
 ```
@@ -295,10 +383,10 @@ const { messages, sendMessage, status } = useChat({
 
 ```ts
 // string (default)
-endpoint: "/api/mock/ai";
-// /api/mock/ai              → file = "default"
-// /api/mock/ai/chat         → file = "chat"
-// /api/mock/ai/i18n/zh-CN   → file = "i18n/zh-CN" (nested directory)
+endpoint: "/api";
+// /api              → file = "default"
+// /api/chat         → file = "chat"
+// /api/i18n/zh-CN   → file = "i18n/zh-CN" (nested directory)
 
 // RegExp
 endpoint: /^\/api\/ai\/.*/;
@@ -308,11 +396,11 @@ endpoint: /^\/api\/ai\/.*/;
 endpoint: ["/api/chat", /^\/v2\/ai\/.*/];
 ```
 
-Nested directories are supported. For example, `/api/mock/ai/i18n/zh-CN` maps to `mock/ai/i18n/zh-CN.json`.
+Nested directories are supported. For example, `/api/i18n/zh-CN` maps to `mock/i18n/zh-CN.json`.
 
-- `/api/mock/ai`
-- `/api/mock/ai/<file>`
-- `/api/mock/ai/<dir>/<file>` (nested)
+- `/api`
+- `/api/<file>`
+- `/api/<dir>/<file>` (nested)
 - `?file=<file>` or `?file=<dir>/<file>`
 
 ## Test
@@ -333,4 +421,73 @@ pnpm build
 pnpm release:npm
 ```
 
-`prepublishOnly` will automatically run build, tests and typecheck..
+`prepublishOnly` will automatically run build, tests and typecheck.
+
+## Configuration Options
+
+### Plugin Options `AiMockPluginOptions`
+
+| Option            | Type                                       | Default          | Description                                                                               |
+| ----------------- | ------------------------------------------ | ---------------- | ----------------------------------------------------------------------------------------- |
+| `dataDir`         | `string`                                   | `"mock"`         | Directory for mock files (`.json` or `.ts`), relative to project root                    |
+| `endpoint`        | `string \| RegExp \| (string \| RegExp)[]` | `"/api"`         | API path to intercept, supports string, RegExp, or array                                  |
+| `defaultScenario` | `DefaultScenarioConfig`                    | `undefined`      | Global default scenario config, can be overridden by URL params                           |
+| `jsonApis`        | `(string \| RegExp)[]`                     | `undefined`      | List of API paths that should return JSON format (applies to both `.json` and `.ts` files)|
+
+### Scenario Config `DefaultScenarioConfig`
+
+| Option              | Type           | Default        | Description                                                                                                                                                   |
+| ------------------- | -------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `scenario`          | `ScenarioName` | `undefined`    | Preset scenario name: `normal`, `first-delay`, `jitter`, `disconnect`, `timeout`, `error`, `malformed`, `duplicate`, `out-of-order`, `reconnect`, `heartbeat` |
+| `firstChunkDelayMs` | `number`       | `0`            | Delay before sending first chunk (ms)                                                                                                                         |
+| `minIntervalMs`     | `number`       | `200`          | Minimum interval between chunks (ms)                                                                                                                          |
+| `maxIntervalMs`     | `number`       | `700`          | Maximum interval between chunks (ms)                                                                                                                          |
+| `disconnectAt`      | `number`       | `-1`           | Disconnect at chunk N (-1 to disable)                                                                                                                         |
+| `stallAfter`        | `number`       | `-1`           | Stop sending after chunk N (-1 to disable)                                                                                                                    |
+| `stallMs`           | `number`       | `30000`        | Wait time after stalling (ms)                                                                                                                                 |
+| `errorAt`           | `number`       | `-1`           | Send error event at chunk N (-1 to disable)                                                                                                                   |
+| `errorMessage`      | `string`       | `"mock_error"` | Error event message content                                                                                                                                   |
+| `malformedAt`       | `number`       | `-1`           | Send malformed data at chunk N (-1 to disable)                                                                                                                |
+| `duplicateAt`       | `number`       | `-1`           | Send duplicate chunk at N (-1 to disable)                                                                                                                     |
+| `outOfOrder`        | `boolean`      | `false`        | Shuffle chunk order (swaps chunks 2 and 3)                                                                                                                    |
+| `heartbeatMs`       | `number`       | `0`            | Heartbeat interval (ms), 0 to disable                                                                                                                         |
+| `reconnect`         | `boolean`      | `false`        | Enable reconnect mode, use with `lastEventId`                                                                                                                 |
+
+### URL Parameters
+
+In addition to scenario config params, the following URL-only params are supported:
+
+| Param             | Type                | Default     | Description                                                  |
+| ----------------- | ------------------- | ----------- | ------------------------------------------------------------ |
+| `file`            | `string`            | `"default"` | Mock file name (without `.json` extension)                   |
+| `transport`       | `"sse" \| "json"`   | `"sse"`     | Response format: `sse` for streaming, `json` for direct JSON |
+| `httpErrorStatus` | `number`            | `0`         | Return specified HTTP error status (e.g., 401, 500)          |
+| `includeDone`     | `"true" \| "false"` | `"true"`    | Whether to send `done` event at stream end                   |
+| `lastEventId`     | `string`            | `undefined` | Last event ID for reconnection, resumes after this ID        |
+
+### Full Configuration Example
+
+```ts
+import { defineConfig } from "vite";
+import { aiMockPlugin } from "vite-plugin-ai-mock";
+
+export default defineConfig({
+  plugins: [
+    aiMockPlugin({
+      // Mock file directory
+      dataDir: "mock",
+      // API path to intercept
+      endpoint: "/api",
+      // Global default scenario
+      defaultScenario: {
+        scenario: "jitter",
+        firstChunkDelayMs: 500,
+        minIntervalMs: 100,
+        maxIntervalMs: 800,
+      },
+      // APIs that return JSON format
+      jsonApis: ["/api/config", /^\/api\/static\/.*/],
+    }),
+  ],
+});
+```

package/README.zh-CN.md

@@ -1,13 +1,14 @@
 # vite-plugin-ai-mock
 
-一个用于 AI 场景模拟的独立 Vite 插件。可以返回 JSON 格式的流式数据，模拟不同的 AI 场景。
+一个用于 AI 场景模拟的独立 Vite 插件。支持 JSON 和 TypeScript 两种 mock 文件格式，返回 SSE 流式或 JSON 响应，模拟不同的 AI 场景。
 
 > [English](./README.md) | 中文
 
-- 从 `mock/ai/*.json` 读取 mock 文件
+- 从 `mock/*.json` 或 `mock/*.ts` 读取 mock 文件
 - 默认返回 SSE 流式响应
 - 使用 `?transport=json` 获取 JSON 格式响应
 - 支持 11 种流式场景，通过请求参数控制
+- TypeScript mock 文件支持动态数据和完整中间件控制——**修改后无需重启服务**
 
 ## 安装
 
@@ -27,19 +28,20 @@ pnpm add vite-plugin-ai-mock -D
 project/
 ├── mock/
 │   └── ai/
-│       ├── chat.json
+│       ├── chat.json        ← JSON mock
+│       ├── sessions.ts      ← TypeScript mock
 │       └── default.json
 ├── src/
 └── vite.config.ts
+```
 
+**请求示例**
 
-
-
-
-
-
-
-
+```ts
+// SSE 流式响应（默认）
+const res = await fetch("/api/chat");
+// JSON 响应
+const json = await fetch("/api/chat?transport=json");
 ```
 
 </td>
@@ -54,14 +56,14 @@ import { aiMockPlugin } from "vite-plugin-ai-mock";
 export default defineConfig({
   plugins: [
     aiMockPlugin({
-      dataDir: "mock/ai",
-      endpoint: "/api/mock/ai",  // /api/mock/ai/chat → chat.json
+      dataDir: "mock",
+      endpoint: "/api",  // /api/chat → chat.json
     }),
   ],
 });
 ```
 
-**mock/ai/chat.json**
+**mock/chat.json**
 
 ```json
 {
@@ -80,6 +82,75 @@ export default defineConfig({
 
 > 💡 查看完整示例：[examples](https://github.com/quanzhiyuan/vite-plugin-ai-mock/tree/main/examples)（包含 Ant Design X、Assistant UI、Lobe Chat 等集成示例）
 
+## TypeScript Mock 文件
+
+除 `.json` 外，mock 文件可以用 TypeScript 编写。当同名 `.ts` 和 `.json` 文件同时存在时，`.ts` 优先。
+
+支持三种 export 模式：
+
+### 模式一 — 静态 default export（等同于 JSON）
+
+```ts
+// mock/ai/chat.ts
+export default {
+  chunks: [
+    { id: "1", data: { delta: "你好" } },
+    { id: "2", data: { delta: "世界" } },
+  ],
+};
+```
+
+### 模式二 — 工厂函数（每次请求都会调用）
+
+函数接收请求对象，可返回动态数据。支持 `async`。
+
+```ts
+// mock/ai/chat.ts
+import type { Connect } from "vite";
+
+export default (req: Connect.IncomingMessage) => {
+  const url = new URL(req.url ?? "/", "http://localhost");
+  const lang = url.searchParams.get("lang") ?? "en";
+  return {
+    chunks: [
+      { id: "1", data: { delta: lang === "zh" ? "你好" : "Hello" } },
+    ],
+  };
+};
+```
+
+### 模式三 — Handler（完全控制 req/res）
+
+替代在 `vite.config.ts` 中单独编写 `configureServer` 插件。接收 `(req, res, next)`，直接控制响应——适用于会话创建/删除等动态路由。
+
+```ts
+// mock/ai/session.ts
+import type { MockRequestHandler } from "vite-plugin-ai-mock";
+
+const sessions = new Set<string>();
+
+export const handler: MockRequestHandler = (req, res) => {
+  if (req.method === "POST") {
+    const id = `sess-${Date.now()}`;
+    sessions.add(id);
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ status: "success", data: { session_id: id } }));
+    return;
+  }
+  if (req.method === "DELETE") {
+    const id = (req.url ?? "").split("/").pop() ?? "";
+    sessions.delete(id);
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ status: "success" }));
+    return;
+  }
+  res.statusCode = 405;
+  res.end();
+};
+```
+
+**热更新**：TypeScript mock 文件通过 Vite 的 `ssrLoadModule` 加载。每次修改后，下一个请求即可生效，**无需重启开发服务器**。
+
 ## 场景（11 种）
 
 1. 正常完成（默认）
@@ -108,20 +179,20 @@ export default defineConfig({
 直接在请求 URL 上附加参数，适合临时调试单个接口：
 
 ```
-/api/mock/ai/default?scenario=jitter
-/api/mock/ai/default?firstChunkDelayMs=1000&errorAt=3
+/api/default?scenario=jitter
+/api/default?firstChunkDelayMs=1000&errorAt=3
 ```
 
 ```ts
 // 默认返回 SSE 流式响应
-const response = await fetch("/api/mock/ai/default?firstChunkDelayMs=4800", {
+const response = await fetch("/api/default?firstChunkDelayMs=4800", {
   method: "POST",
   headers: { "Content-Type": "application/json" },
   body: JSON.stringify({}),
 });
 
 // 使用 ?transport=json 获取 JSON 格式
-const jsonResponse = await fetch("/api/mock/ai/default?transport=json");
+const jsonResponse = await fetch("/api/default?transport=json");
 ```
 
 **2. 插件选项 `defaultScenario`（全局生效）**
@@ -144,9 +215,26 @@ aiMockPlugin({
 
 不配置 `defaultScenario` 时，默认使用 `normal` 场景（无延迟，正常完成）。
 
+**3. 插件选项 `jsonApis`（指定返回 JSON 格式的 API）**
+
+在 `vite.config.ts` 中配置，指定哪些 API 路径返回 JSON 格式而不是 SSE 格式：
+
+```ts
+aiMockPlugin({
+  endpoint: "/api",
+  jsonApis: [
+    "/api/config",           // 精确匹配
+    "/api/history",          // 精确匹配
+    /^\/api\/static\/.*/,    // 正则匹配
+  ],
+});
+```
+
+优先级：`?transport=json` / `?transport=sse` > `jsonApis` 配置 > 默认 SSE
+
 ## Mock 文件格式
 
-每个文件是一个包含 `chunks` 数组的 JSON 对象，每个 chunk 对应一条 SSE 事件：
+每个 mock 文件（JSON 或 TypeScript）包含一个 `chunks` 数组，每个 chunk 对应一条 SSE 事件：
 
 | 字段      | 类型   | 说明                                                |
 | --------- | ------ | --------------------------------------------------- |
@@ -169,18 +257,18 @@ aiMockPlugin({
 
 ### 主流格式示例
 
-`data` 字段可以完整模拟真实 API 的响应结构。npm 包内置了以下示例文件（位于 `mock/ai/`），可直接复制到项目中使用：
+`data` 字段可以完整模拟真实 API 的响应结构。npm 包内置了以下示例文件（位于 `mock/`），可直接复制到项目中使用：
 
-| 文件                             | 提供商            |
-| -------------------------------- | ----------------- |
-| `mock/ai/openai.json`            | OpenAI / 兼容格式 |
-| `mock/ai/claude.json`            | Anthropic Claude  |
-| `mock/ai/gemini.json`            | Google Gemini     |
-| `mock/ai/deepseek.json`          | DeepSeek          |
-| `mock/ai/deepseek-reasoner.json` | DeepSeek Reasoner |
-| `mock/ai/qwen.json`              | 通义千问（阿里）  |
-| `mock/ai/qwen-thinking.json`     | 通义千问 Thinking |
-| `mock/ai/doubao.json`            | 豆包（字节跳动）  |
+| 文件                        | 提供商            |
+| --------------------------- | ----------------- |
+| `mock/openai.json`          | OpenAI / 兼容格式 |
+| `mock/claude.json`          | Anthropic Claude  |
+| `mock/gemini.json`          | Google Gemini     |
+| `mock/deepseek.json`        | DeepSeek          |
+| `mock/deepseek-reasoner.json` | DeepSeek Reasoner |
+| `mock/qwen.json`            | 通义千问（阿里）  |
+| `mock/qwen-thinking.json`   | 通义千问 Thinking |
+| `mock/doubao.json`          | 豆包（字节跳动）  |
 
 **OpenAI / 兼容格式**（`openai.json`）——最后一条 `data` 为字符串 `"[DONE]"`：
 
@@ -272,7 +360,7 @@ import { DefaultChatTransport } from "ai";
 
 const { messages, sendMessage, status } = useChat({
   transport: new DefaultChatTransport({
-    api: "/api/mock/ai/chat",
+    api: "/api/chat",
   }),
 });
 ```
@@ -289,10 +377,10 @@ const { messages, sendMessage, status } = useChat({
 
 ```ts
 // string（默认）
-endpoint: "/api/mock/ai";
-// /api/mock/ai              → file = "default"
-// /api/mock/ai/chat         → file = "chat"
-// /api/mock/ai/i18n/zh-CN   → file = "i18n/zh-CN"（多层级目录）
+endpoint: "/api";
+// /api              → file = "default"
+// /api/chat         → file = "chat"
+// /api/i18n/zh-CN   → file = "i18n/zh-CN"（多层级目录）
 
 // RegExp
 endpoint: /^\/api\/ai\/.*/;
@@ -302,11 +390,11 @@ endpoint: /^\/api\/ai\/.*/;
 endpoint: ["/api/chat", /^\/v2\/ai\/.*/];
 ```
 
-支持多层级目录。例如 `/api/mock/ai/i18n/zh-CN` 会映射到 `mock/ai/i18n/zh-CN.json`。
+支持多层级目录。例如 `/api/i18n/zh-CN` 会映射到 `mock/i18n/zh-CN.json`。
 
-- `/api/mock/ai`
-- `/api/mock/ai/<file>`
-- `/api/mock/ai/<dir>/<file>`（多层级）
+- `/api`
+- `/api/<file>`
+- `/api/<dir>/<file>`（多层级）
 - `?file=<file>` 或 `?file=<dir>/<file>`
 
 ## 测试
@@ -328,3 +416,75 @@ pnpm release:npm
 ```
 
 `prepublishOnly` 会自动执行构建、测试和类型检查。
+
+## 配置选项
+
+### 插件配置 `AiMockPluginOptions`
+
+| 选项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `dataDir` | `string` | `"mock"` | mock 文件目录（支持 `.json` 和 `.ts`），相对于项目根目录 |
+| `endpoint` | `string \| RegExp \| (string \| RegExp)[]` | `"/api"` | 拦截的 API 路径，支持字符串、正则或数组 |
+| `defaultScenario` | `DefaultScenarioConfig` | `undefined` | 全局默认场景配置，可被 URL 参数覆盖 |
+| `jsonApis` | `(string \| RegExp)[]` | `undefined` | 指定返回 JSON 格式的 API 路径（对 `.json` 和 `.ts` 均生效）|
+
+### 场景配置 `DefaultScenarioConfig`
+
+| 选项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `scenario` | `ScenarioName` | `undefined` | 预设场景名：`normal`、`first-delay`、`jitter`、`disconnect`、`timeout`、`error`、`malformed`、`duplicate`、`out-of-order`、`reconnect`、`heartbeat` |
+| `firstChunkDelayMs` | `number` | `0` | 首个数据块发送前的延迟时间（毫秒） |
+| `minIntervalMs` | `number` | `200` | 数据块之间的最小间隔时间（毫秒） |
+| `maxIntervalMs` | `number` | `700` | 数据块之间的最大间隔时间（毫秒） |
+| `disconnectAt` | `number` | `-1` | 在第 N 个数据块处断开连接（-1 为不断开） |
+| `stallAfter` | `number` | `-1` | 在第 N 个数据块后停止发送（-1 为不停止） |
+| `stallMs` | `number` | `30000` | 停止发送后等待的时间（毫秒） |
+| `errorAt` | `number` | `-1` | 在第 N 个数据块处发送错误事件（-1 为不发送） |
+| `errorMessage` | `string` | `"mock_error"` | 错误事件的消息内容 |
+| `malformedAt` | `number` | `-1` | 在第 N 个数据块处发送格式错误的数据（-1 为不发送） |
+| `duplicateAt` | `number` | `-1` | 在第 N 个数据块处发送重复数据（-1 为不发送） |
+| `outOfOrder` | `boolean` | `false` | 是否打乱数据块顺序（交换第 2、3 块） |
+| `heartbeatMs` | `number` | `0` | 心跳间隔时间（毫秒），0 为不发送心跳 |
+| `reconnect` | `boolean` | `false` | 是否启用重连模式，配合 `lastEventId` 使用 |
+
+### URL 参数
+
+除了上述场景配置参数外，还支持以下 URL 专用参数：
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `file` | `string` | `"default"` | 指定 mock 文件名（不含 `.json` 后缀） |
+| `transport` | `"sse" \| "json"` | `"sse"` | 响应格式：`sse` 流式响应，`json` 直接返回 JSON |
+| `httpErrorStatus` | `number` | `0` | 返回指定 HTTP 状态码错误（如 401、500） |
+| `includeDone` | `"true" \| "false"` | `"true"` | 是否在流结束时发送 `done` 事件 |
+| `lastEventId` | `string` | `undefined` | 断线重连时的最后事件 ID，从该 ID 之后继续发送 |
+
+### 完整配置示例
+
+```ts
+import { defineConfig } from "vite";
+import { aiMockPlugin } from "vite-plugin-ai-mock";
+
+export default defineConfig({
+  plugins: [
+    aiMockPlugin({
+      // mock 文件目录
+      dataDir: "mock",
+      // 拦截的 API 路径
+      endpoint: "/api",
+      // 全局默认场景
+      defaultScenario: {
+        scenario: "jitter",
+        firstChunkDelayMs: 500,
+        minIntervalMs: 100,
+        maxIntervalMs: 800,
+      },
+      // 返回 JSON 格式的 API 列表
+      jsonApis: [
+        "/api/config",
+        /^\/api\/static\/.*/,
+      ],
+    }),
+  ],
+});
+```