高质量了一个 AI 工具 sse-stuntman,Mock SSE 接口

开发过 AI 对话应用的前端都会遇到一个痛点，需要等服务端提供 SSE 流式接口才能继续，而且有些边缘 case 还没法造出。

如果要自己 mock sse 接口就需要做很多事情（比如需禁缓存、禁止 batch 传输、禁止浏览器压缩，设置合适的 sse 请求头），因为 SSE 接口的 mock 方式和普通接口很不一样，需要启动一个 mock 服务器（这些事情现在都可让 sse-stuntman 来做了）。

最近我又开发了一个 AI 应用，发现每次都在做重复的事情，需要专门 Node.js 本地搭建一个 mock sse 服务器。所以干脆把 mock 服务做成一个复用的工具，一行命令就开启 mock，前端代码无需做任何变化。要是能内置不同场景，而且 delay 也可自定义那就更好了，当然场景（即返回内容）也能自定义那就完美了。所以才有此文。

项目地址：

https://www.npmjs.com/package/sse-stuntman

一键启动 mock 服务：

pnpx sse-stuntman

上面的要求 sse-stuntman 都能满足。

具体场景

如图下面是一个典型的 AI 对话应用，采用 SSE 协议。

它期待返回符合 OpenAI 规范的 SSE 流。请求 URL 是：

POST http://localhost:9095/api/my/chat

只需

pnpx sse-stuntman --port 9095 --endpoint-path 'api/my/chat'

就开启了我们业务需要的 mock 接口，且具备打字机效果。

上面的内容来自哪里呢？

开屏日志：

  ╔════════════════════════════════════════════════════════════════════════════════╗  ║   ███████╗████████╗██╗   ██╗███╗   ██╗████████╗███╗   ███╗ █████╗ ███╗   ██╗   ║  ║   ██╔════╝╚══██╔══╝██║   ██║████╗  ██║╚══██╔══╝████╗ ████║██╔══██╗████╗  ██║   ║  ║   ███████╗   ██║   ██║   ██║██╔██╗ ██║   ██║   ██╔████╔██║███████║██╔██╗ ██║   ║  ║   ╚════██║   ██║   ██║   ██║██║╚██╗██║   ██║   ██║╚██╔╝██║██╔══██║██║╚██╗██║   ║  ║   ███████║   ██║   ╚██████╔╝██║ ╚████║   ██║   ██║ ╚═╝ ██║██║  ██║██║ ╚████║   ║  ║   ╚══════╝   ╚═╝    ╚═════╝ ╚═╝  ╚═══╝   ╚═╝   ╚═╝     ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝   ║  ║                                                                                ║  ║                    SSE Stuntman  |  Your AI's Stunt Double                     ║  ╚════════════════════════════════════════════════════════════════════════════════╝  ✓ OpenAI provider ready  ✓ SSE endpoint: http://localhost:9095 (SSE Live Demo. Click to try)  ✓ Mock scenarios: 13 loaded (builtin: 12, custom: 1)  API(s):    POST /api/my/chat  Scenario:  default  (标准对话演示，包含 markdown 列表 / 代码块 / 表格 / 任务列表)  Chunk:     word  Delay:     10ms  (used when scenario has no @delay)  ═══>  🏍️  Waiting for requests...  ═══>  Press Ctrl+C to stop.  → [2026/7/8 09:59:42] mrbfjv39eedf POST /management-service/api/intelligent-qa/chat scenario=default model=null  ← [2026/7/8 10:00:08] mrbfjv39eedf 200 25963ms

从上面开屏日志可以看到

Scenario: default (标准对话演示，包含 markdown 列表 / 代码块 / 表格 / 任务列表)

即来自内置的默认场景。我们可以打开看看：

❯ tree src/scenarios/scenarios├── default.md

我经常使用的功能

我想测试更多场景，比如 mermaid 语法、rust 代码块，甚至边缘 case 429 rate limit，这些都支持，因为已经内置了。如果内置的不满足你的需求你甚至可以自定义。

我们在仔细看看开屏日志：

  ✓ OpenAI provider ready  ✓ SSE endpoint: http://localhost:9095 (SSE Live Demo. Click to try)  ✓ Mock scenarios: 13 loaded (builtin: 12, custom: 1)  API(s):    POST /api/my/chat  Scenario:  default  (标准对话演示，包含 markdown 列表 / 代码块 / 表格 / 任务列表)  Chunk:     word  Delay:     10ms  (used when scenario has no @delay)

• 目前返回格式是 OpenAI，支持两种 OpenAI 和 Anthropic。
• http://localhost:9095 直接打开是内置的演示界面，大家可以试试这里不详述
• 目前有 13 个场景，内置 12 个，自定义 1 个。可以通过 pnpm sse-stuntman --list 查看
• 默认场景是 default：标准对话演示，包含 markdown 列表 / 代码块 / 表格 / 任务列表

• Chunk: word 表示逐词输出：还支持 "sentence", "char", "line" 和 "paragraph" 可通过 --chunk-strategy <name> 切换
• Delay: 10ms 表示 token 输出间隔 10ms，可通过 --default-delay 参数调整。后面used when scenario has no @delay 的意思如果在场景里面写了 @delay 指令则指令优先级更高。

接下来会介绍我经常使用的场景 echo 和自定义场景。

切换场景 --scenario

假设我们想切换到内置的马丁路德金的著名演讲《我有一个梦想》：

pnpx sse-stuntman --scenario english-i-have-a-dream

效果：

这次我们试试 curl 看看原始返回：

❯ curl -N -X POST http://localhost:9095/api/my/chat \    -H "Content-Type: application/json" \    -d '{"messages":[{"role":"user","content":"# Hello\n\nYour **markdown** here"}],"stream": true}'

data: {"id":"64c2308c-3b5d-4db2-968d-c8a9801b5f90","object":"chat.completion.chunk","created":1783478346,"model":"gpt-4o","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}data: {"id":"64c2308c-3b5d-4db2-968d-c8a9801b5f90","object":"chat.completion.chunk","created":1783478346,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":"#"},"finish_reason":null}]}data: {"id":"64c2308c-3b5d-4db2-968d-c8a9801b5f90","object":"chat.completion.chunk","created":1783478346,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":" "},"finish_reason":null}]}data: {"id":"64c2308c-3b5d-4db2-968d-c8a9801b5f90","object":"chat.completion.chunk","created":1783478346,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":"I"},"finish_reason":null}]}data: {"id":"64c2308c-3b5d-4db2-968d-c8a9801b5f90","object":"chat.completion.chunk","created":1783478346,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":" "},"finish_reason":null}]}data: {"id":"64c2308c-3b5d-4db2-968d-c8a9801b5f90","object":"chat.completion.chunk","created":1783478346,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":"Have"},"finish_reason":null}]}data: {"id":"64c2308c-3b5d-4db2-968d-c8a9801b5f90","object":"chat.completion.chunk","created":1783478346,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":" "},"finish_reason":null}]}data: {"id":"64c2308c-3b5d-4db2-968d-c8a9801b5f90","object":"chat.completion.chunk","created":1783478346,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":"a"},"finish_reason":null}]}data: {"id":"64c2308c-3b5d-4db2-968d-c8a9801b5f90","object":"chat.completion.chunk","created":1783478346,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":" "},"finish_reason":null}]}data: {"id":"64c2308c-3b5d-4db2-968d-c8a9801b5f90","object":"chat.completion.chunk","created":1783478346,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":"Dream"},"finish_reason":null}]}...

可见返回了 OpenAI 格式数据。

自定义场景 create-scenario

假设我们想自定义返回值，那就可以自定义一个场景，暂且将场景名取为 temp。

可通过 create-scenario 子命令新增一个自定义场景：

pnpx sse-stuntman create-scenario temp

打开看看 temp 内容

code ~/.sse-stuntman/scenarios/temp.md

<!-- @desc: 这是一个自定义场景 "temp" --># temp在这里编写你的场景内容。<!-- @delay: 100 -->支持 **markdown** 语法、代码块、表格等。

其实没什么神奇的就是一个普通的 markdown 文件，但是夹杂一些 sse-stuntman 自定义指令：

• @desc 是元信息，描述场景是干什么的，帮助你自己记忆用的。可在 --list 的时候展示。
• @delay 自定义 token 间的输出时延。这个指令很有用，可以模仿真实业务，因为大模型在输出的时候并不会一直匀速输出，时快时慢的效果就可以通过该指令实现。这个指令让时延具备颗粒度更细的控制。

当然这些指令都可选。你怎么写 markdown 就怎么写场景。

场景没啥神秘的，放到 home 目录 ~/.sse-stuntman/scenarios 下的 markdown 文件就是一个“场景”。理解了这个，那么立马就知道还有一种方式可以创建场景，即手动在该目录下新增 md 后缀的文件就行。so easy。

好的设计就是没有设计。Good Design is invisible design

好的设计，让人察觉不到刻意。Great design goes unnoticed

当然 create-scenario 命令的小贴心是帮你写入了默认模板，以及自动打开场景目录。

建议第一次使用的小伙伴用。

echo 模式

这是我引以为傲的一个设计。什么是 echo 模式：

Echo user messages as streaming markdown response — send any markdown as the last user message and see it streamed back.

将用户消息以流式 Markdown 响应回显。

从字面意义理解就是你输入什么大模型就输出什么。

有什么用呢？用处大着嘞。你想测试某种 markdown 输出，但是内置场景没有，但是你又不想自定义场景，就可以用这个模式。

试试看:

启动 echo 模式 --scenario echo

❯ pnpx sse-stuntman\  --port 3003\  --endpoint-path 'api/reasoning_api_server/v1/controlled/chat/completions'\  --scenario echo --separator '\r\n\r\n'...API(s):     POST /api/reasoning_api_server/v1/controlled/chat/completionsScenario:   echo  (🔥 Echo user messages as streaming markdown response — send any markdown as the last user message and see it streamed back)Separator:  CRLF_CRLF...

在输入框输入：

## `..Default::default()` 从 JavaScript 角度理解### Rust 的 `..Default::default()` 是什么？这是 Rust 的**结构体更新语法**（Struct Update Syntax），结合 `Default` trait：\```rustlet config = ReviewConfig {    max_tokens: cli.max_tokens,    max_file_tokens: cli.max_file_tokens,    ..Default::default()  // 剩余字段使用 Default::default() 的默认值};\```**含义：** 创建一个 `ReviewConfig` 实例，只指定 `max_tokens` 和 `max_file_tokens`，其他字段使用 `Default::default()` 提供的默认值。### JavaScript 等价理解\```jsconst config = {    ...DEFAULT_CONFIG,  // 相当于 ..Default::default()    max_tokens: cli.maxTokens,  // 覆盖    max_file_tokens: cli.maxFileTokens  // 覆盖}\```### 总结**`..Default::default()` = 默认值合并**- **Rust**：编译时检查，类型安全- **JavaScript**：运行时合并对象，使用 `...` 或 `Object.assign()`两者都是：**先填充默认值，再用指定值覆盖**。

可见我们的输入被原封不动输出了，这样我们就可以测试任意内容，而无需自定义场景。

@input 指令 Make AI Mock Live

再介绍一个和 echo 模式相关的一个指令 @input，如果自定义场景中存在 @input 会原封不动替换成用户的输入。

比如你的在 ~/.sse-stuntman/scenarios 新增了 input.md 文件（文件名随便）：

你问的这个问题> **<!-- @input -->**违背 AI 道德规范，我无法回答。

启动 see-stuntman:

❯ pnpx sse-stuntman --scenario input

输入任何文字，大模型将输出如下：

你问的这个问题> **用户输入**违背 AI 道德规范，我无法回答。

提示：可以存在多个 @input。

最后看看 sse-stuntman 的一些卖点：

特性

• ✨ 零依赖 — 充分使用 Node.js 内置模块
• 🎯 OpenAI 兼容 — POST /v1/chat/completions，标准 SSE 格式，主流前端 SDK 直接对接。也支持 Anthropic
• ⏱ 灵活时序控制 — 每条消息间隔通过指令可设置不同速度，模拟真实业务效果
• 💥 全面错误模拟 — 429 / 400 / 500 / 超时断连 / 空响应，覆盖真实异常
• 🖥 内置 Web UI — 浏览器打开首页即可演示流式输出
• 📝 场景即 Markdown — 内置 13 个场景。用 .md 文件描述 AI 输出内容和节奏，可读可版本控制，场景文件可放入代码库
• 📂 自定义场景 — 默认 ~/.sse-stuntman/scenarios/ 放 .md 文件自动生效，支持自定义目录，场景可纳入 git 管理
• 🎤 自定义输入 — 把请求消息内容注入场景流，用 @input 指令让静态场景"活"起来
• 🌐 CORS 全开 — 浏览器直接跨域调用

License

MIT © 2026 legend80s^[1]

参考资料