vite-plugin-ai-mock 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,207 @@
+# vite-plugin-ai-mock
+
+> English | [中文](./README.zh-CN.md)
+
+A standalone Vite plugin for AI scene mocking. Returns streaming data in JSON format, simulating various AI scenarios.
+
+- Reads mock files from `mock/ai/*.json`
+- Auto returns SSE when request is SSE (`Accept: text/event-stream` or `?transport=sse`)
+- Returns JSON for non-SSE calls
+- Supports 11 streaming scenarios with request parameters
+
+## Install
+
+```bash
+npm i vite-plugin-ai-mock -D
+```
+
+## Usage
+
+```ts
+import { defineConfig } from "vite";
+import { aiMockPlugin } from "vite-plugin-ai-mock";
+
+export default defineConfig({
+  plugins: [
+    aiMockPlugin({
+      dataDir: "mock/ai",
+      endpoint: "/api/ai/mock",
+    }),
+  ],
+});
+```
+
+## Scenarios (11)
+
+1. Normal completion (default)
+2. First chunk delay: `firstChunkDelayMs=1800` or `scenario=first-delay`
+3. Jitter: `minIntervalMs=100&maxIntervalMs=1500` or `scenario=jitter`
+4. Mid-stream disconnect: `disconnectAt=3` or `scenario=disconnect`
+5. Timeout/no response: `stallAfter=2&stallMs=30000` or `scenario=timeout`
+6. Stream error event: `errorAt=2&errorMessage=xxx` or `scenario=error`
+7. Malformed chunk: `malformedAt=2` or `scenario=malformed`
+8. Duplicate chunk: `duplicateAt=2` or `scenario=duplicate`
+9. User cancel: client aborts request (server handles `close`)
+10. Reconnect/resume: `reconnect=true&lastEventId=1` or `scenario=reconnect`
+11. Heartbeat: `heartbeatMs=2500` or `scenario=heartbeat`
+
+Extra:
+
+- HTTP error injection: `httpErrorStatus=401`
+- Skip done event: `includeDone=false`
+
+## Scenario Configuration
+
+Scenarios can be configured in two ways, in order of precedence:
+
+**1. URL parameters (per-request)**
+
+Append parameters directly to the request URL, useful for debugging a single endpoint:
+
+```
+/api/ai/mock/default?scenario=jitter
+/api/ai/mock/default?firstChunkDelayMs=1000&errorAt=3
+```
+
+**2. Plugin option `defaultScenario` (global)**
+
+Configure in `vite.config.ts` to apply to all mock requests. URL parameters take precedence and override this:
+
+```ts
+aiMockPlugin({
+  defaultScenario: {
+    scenario: "jitter",        // Use a preset scenario name
+    // Individual options override the preset's corresponding values:
+    firstChunkDelayMs: 500,
+    minIntervalMs: 100,
+    maxIntervalMs: 800,
+    errorAt: 3,
+    errorMessage: "custom_error",
+  },
+});
+```
+
+When `defaultScenario` is not set, the `normal` scenario is used (no delay, completes normally).
+
+## Mock file format
+
+Each file is a JSON object with a `chunks` array. Every chunk maps to one SSE event:
+
+| Field     | Type   | Description                                                     |
+| --------- | ------ | --------------------------------------------------------------- |
+| `id`      | string | SSE `id:` field, used for reconnect resume                      |
+| `event`   | string | SSE `event:` field (default: `message`)                         |
+| `data`    | any    | Payload — object/array is JSON-serialized, string is sent as-is |
+| `delayMs` | number | Per-chunk delay override (ms)                                   |
+
+`default.json` is loaded when no file is specified. You can customize it with any `data` shape to match your own API format:
+
+```json
+{
+  "chunks": [
+    { "id": "1", "event": "message", "data": { "delta": "Hello" } },
+    { "id": "2", "event": "message", "data": { "delta": ", " } },
+    { "id": "3", "event": "message", "data": { "delta": "world!" } }
+  ]
+}
+```
+
+### Real-world format examples
+
+The `data` field can mirror any real API response. Built-in examples are available in `mock/ai/`:
+
+**OpenAI / compatible** (`openai.json`) — `data` ends with `"[DONE]"` string:
+
+```json
+{
+  "id": "1",
+  "event": "message",
+  "data": {
+    "id": "chatcmpl-001",
+    "object": "chat.completion.chunk",
+    "choices": [
+      { "index": 0, "delta": { "content": "Hello" }, "finish_reason": null }
+    ]
+  }
+}
+```
+
+**Anthropic Claude** (`claude.json`) — uses distinct `event` types:
+
+```json
+{
+  "id": "3",
+  "event": "content_block_delta",
+  "data": {
+    "type": "content_block_delta",
+    "index": 0,
+    "delta": { "type": "text_delta", "text": "Hello" }
+  }
+}
+```
+
+**Google Gemini** (`gemini.json`) — all events share the same `message` event type:
+
+```json
+{
+  "id": "1",
+  "event": "message",
+  "data": {
+    "candidates": [
+      {
+        "content": { "parts": [{ "text": "Hello" }], "role": "model" },
+        "finishReason": null
+      }
+    ]
+  }
+}
+```
+
+## Endpoint
+
+`endpoint` accepts a `string`, `RegExp`, or `(string | RegExp)[]`.
+
+| Type                   | `fileFromPath` extraction                                          |
+| ---------------------- | ------------------------------------------------------------------ |
+| `string`               | Strips the path prefix                                             |
+| `RegExp`               | Always `""`, relies on `?file=`                                    |
+| `(string \| RegExp)[]` | Tries each in order; first match wins and follows its type's rules |
+
+```ts
+// string (default)
+endpoint: "/api/ai/mock";
+// /api/ai/mock        → file = "default"
+// /api/ai/mock/chat   → file = "chat"
+// /api/ai/mock/deepseek   → file = "deepseek"
+
+// RegExp
+endpoint: /^\/api\/ai\/.*/;
+// relies on ?file= to pick the mock file
+
+// array
+endpoint: ["/api/chat", /^\/v2\/ai\/.*/];
+```
+
+- `/api/ai/mock`
+- `/api/ai/mock/<file>`
+- `?file=<file>`
+
+## Test
+
+```bash
+npm test
+```
+
+## Build
+
+```bash
+npm run build
+```
+
+## Publish
+
+```bash
+npm run release:npm
+```
+
+`prepublishOnly` will automatically run build, tests and typecheck..

package/README.zh-CN.md

@@ -0,0 +1,207 @@
+# vite-plugin-ai-mock
+
+一个用于 AI 场景模拟的独立 Vite 插件。可以返回 JSON 格式的流式数据，模拟不同的 AI 场景。
+
+> [English](./README.md) | 中文
+
+- 从 `mock/ai/*.json` 读取 mock 文件
+- 当请求为 SSE（`Accept: text/event-stream` 或 `?transport=sse`）时自动返回 SSE
+- 非 SSE 请求返回 JSON
+- 支持 11 种流式场景，通过请求参数控制
+
+## 安装
+
+```bash
+npm i vite-plugin-ai-mock -D
+```
+
+## 使用
+
+```ts
+import { defineConfig } from "vite";
+import { aiMockPlugin } from "vite-plugin-ai-mock";
+
+export default defineConfig({
+  plugins: [
+    aiMockPlugin({
+      dataDir: "mock/ai",
+      endpoint: "/api/ai/mock",
+    }),
+  ],
+});
+```
+
+## 场景（11 种）
+
+1. 正常完成（默认）
+2. 首包延迟：`firstChunkDelayMs=1800` 或 `scenario=first-delay`
+3. 抖动：`minIntervalMs=100&maxIntervalMs=1500` 或 `scenario=jitter`
+4. 中途断开：`disconnectAt=3` 或 `scenario=disconnect`
+5. 超时/无响应：`stallAfter=2&stallMs=30000` 或 `scenario=timeout`
+6. 流错误事件：`errorAt=2&errorMessage=xxx` 或 `scenario=error`
+7. 格式错误的数据块：`malformedAt=2` 或 `scenario=malformed`
+8. 重复数据块：`duplicateAt=2` 或 `scenario=duplicate`
+9. 用户取消：客户端中止请求（服务端处理 `close`）
+10. 重连/续传：`reconnect=true&lastEventId=1` 或 `scenario=reconnect`
+11. 心跳：`heartbeatMs=2500` 或 `scenario=heartbeat`
+
+额外参数：
+
+- HTTP 错误注入：`httpErrorStatus=401`
+- 跳过完成事件：`includeDone=false`
+
+## 场景配置
+
+场景有两种配置方式，优先级由高到低：
+
+**1. URL 参数（仅对当前请求生效）**
+
+直接在请求 URL 上附加参数，适合临时调试单个接口：
+
+```
+/api/ai/mock/default?scenario=jitter
+/api/ai/mock/default?firstChunkDelayMs=1000&errorAt=3
+```
+
+**2. 插件选项 `defaultScenario`（全局生效）**
+
+在 `vite.config.ts` 中配置，对所有 mock 请求生效，可被 URL 参数覆盖：
+
+```ts
+aiMockPlugin({
+  defaultScenario: {
+    scenario: "jitter", // 使用预设场景名
+    // 也可单独配置参数，会覆盖预设场景的对应值：
+    firstChunkDelayMs: 500,
+    minIntervalMs: 100,
+    maxIntervalMs: 800,
+    errorAt: 3,
+    errorMessage: "custom_error",
+  },
+});
+```
+
+不配置 `defaultScenario` 时，默认使用 `normal` 场景（无延迟，正常完成）。
+
+## Mock 文件格式
+
+每个文件是一个包含 `chunks` 数组的 JSON 对象，每个 chunk 对应一条 SSE 事件：
+
+| 字段      | 类型   | 说明                                                |
+| --------- | ------ | --------------------------------------------------- |
+| `id`      | string | SSE `id:` 字段，用于断线重连续传                    |
+| `event`   | string | SSE `event:` 字段（默认：`message`）                |
+| `data`    | any    | 数据载体——对象/数组会被 JSON 序列化，字符串原样发送 |
+| `delayMs` | number | 单个 chunk 的延迟时间覆盖（毫秒）                   |
+
+`default.json` 是未指定文件时加载的默认文件，`data` 字段可自由定义，用于匹配你自己的 API 格式：
+
+```json
+{
+  "chunks": [
+    { "id": "1", "event": "message", "data": { "delta": "Hello" } },
+    { "id": "2", "event": "message", "data": { "delta": ", " } },
+    { "id": "3", "event": "message", "data": { "delta": "world!" } }
+  ]
+}
+```
+
+### 主流格式示例
+
+`data` 字段可以完整模拟真实 API 的响应结构，内置示例文件位于 `mock/ai/`：
+
+**OpenAI / 兼容格式**（`openai.json`）——最后一条 `data` 为字符串 `"[DONE]"`：
+
+```json
+{
+  "id": "1",
+  "event": "message",
+  "data": {
+    "id": "chatcmpl-001",
+    "object": "chat.completion.chunk",
+    "choices": [
+      { "index": 0, "delta": { "content": "Hello" }, "finish_reason": null }
+    ]
+  }
+}
+```
+
+**Anthropic Claude**（`claude.json`）——通过不同 `event` 类型区分生命周期：
+
+```json
+{
+  "id": "3",
+  "event": "content_block_delta",
+  "data": {
+    "type": "content_block_delta",
+    "index": 0,
+    "delta": { "type": "text_delta", "text": "Hello" }
+  }
+}
+```
+
+**Google Gemini**（`gemini.json`）——所有事件统一使用 `message` 事件类型：
+
+```json
+{
+  "id": "1",
+  "event": "message",
+  "data": {
+    "candidates": [
+      {
+        "content": { "parts": [{ "text": "Hello" }], "role": "model" },
+        "finishReason": null
+      }
+    ]
+  }
+}
+```
+
+## 接口地址
+
+`endpoint` 支持 `string`、`RegExp` 或 `(string | RegExp)[]`。
+
+| 类型                   | `fileFromPath` 提取方式                |
+| ---------------------- | -------------------------------------- |
+| `string`               | 去掉路径前缀                           |
+| `RegExp`               | 始终为 `""`，依赖 `?file=` 参数        |
+| `(string \| RegExp)[]` | 按序匹配，第一个命中者按其类型规则处理 |
+
+```ts
+// string（默认）
+endpoint: "/api/ai/mock";
+// /api/ai/mock        → file = "default"
+// /api/ai/mock/chat   → file = "chat"
+// /api/ai/mock/deepseek   → file = "deepseek"
+
+// RegExp
+endpoint: /^\/api\/ai\/.*/;
+// 依赖 ?file= 参数选取 mock 文件
+
+// 数组
+endpoint: ["/api/chat", /^\/v2\/ai\/.*/];
+```
+
+- `/api/ai/mock`
+- `/api/ai/mock/<file>`
+- `?file=<file>`
+
+## 测试
+
+```bash
+npm test
+```
+
+## 构建
+
+```bash
+npm run build
+```
+
+## 发布
+
+```bash
+npm run release:npm
+```
+
+`prepublishOnly` 会自动执行构建、测试和类型检查。