Scalar Mock Server Agent Skill用 skills CLI 为 Coding Agent 安装 OpenAPI Mock 服务器构建与排障技能【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar本文基于 Scalar 仓库中的 Mock Server Agent Skill 文档 展开介绍如何通过skillsCLI 为 Cursor、Codex 等 coding agent 安装可复用的 Mock Server 技能并结合仓库内的技能源文件 .agents/skills/mock-server/SKILL.md 与 mock server 包源码深入讲解该技能覆盖的createMockServer()配置、x-handler动态请求处理、x-seed数据播种、认证处理以及 Docker 运行排障五大能力。读完本文你可以让 AI 编程助手直接具备搭建、定制和调试scalar/mock-server的上下文知识。什么是 Mock Server SkillAgent Skill 是一类面向 coding agent 的可复用知识包它以带有 frontmatter 元数据的 Markdown 文件形式存在安装后 agent 在处理相关任务时会自动加载其中的领域知识。Scalar 在仓库的 .agents/skills/mock-server/SKILL.md 中内置了这样一个技能其 frontmatter 声明了技能名称与用途--- name: mock-server description: Build, customize, and troubleshoot OpenAPI mock servers with scalar/mock-server, including x-handler, x-seed, authentication, and Docker. ---该技能的定位是当 agent 需要根据 OpenAPI 描述文档生成真实感 API 响应、编写自定义请求行为、播种初始数据或搭建基于 Docker 的 mock 环境时提供构建、定制与排障的完整参考。技能本身还标注了运行前提——scalar/mock-server包要求 Node.jspackage engine22主 API 为createMockServer(options)。Scalar 同时还内置了另一个技能 scalar-docs对应文档见 Scalar Docs Agent Skill用于管理 Scalar 文档站点配置可与 Mock Server 技能搭配安装。安装 Mock Server Skill技能通过skillsCLI 安装直接从 GitHub 仓库拉取无需克隆整个项目npx skills add scalar/scalar --skill mock-server安装到指定 Agent--agent参数可以重复出现用于把技能同时写入多个 agent 的配置目录。文档给出的 Cursor 与 Codex 示例npx skills add scalar/scalar \ --skill mock-server \ --agent cursor \ --agent codex与 Scalar Docs 技能一起安装如果你同时用 agent 维护scalar.config.jsonScalar 文档站点的配置文件可以安装两个技能npx skills add scalar/scalar --skill scalar-docs npx skills add scalar/scalar --skill mock-server全局安装加--global参数后技能对所有项目生效而不是只作用于当前工作区npx skills add scalar/scalar --skill mock-server --global技能覆盖的核心能力官方文档明确列出mock-server技能包含以下五类指导内容使用document与onRequest搭建createMockServer()使用x-handler扩展实现动态请求处理使用x-seed扩展完成启动时数据播种处理 OpenAPI 操作中的认证使用 Docker 运行和排障scalar/mock-server。以下逐条展开内容均出自技能源文件 .agents/skills/mock-server/SKILL.md可对照阅读。1. createMockServer() 搭建与选项技能给出的最快启动方式是 Scalar CLInpx scalar/cli document mock openapi.json --watch编程式集成示例与 Mock Server 入门文档 中的用法一致import { serve } from hono/node-server import { createMockServer } from scalar/mock-server const app await createMockServer({ document: ./openapi.yaml, onRequest({ context, operation }) { console.log(context.req.method, context.req.path, operation.operationId) }, }) serve({ fetch: app.fetch, port: 3000 })createMockServer()选项要点技能文件中逐一列出必需至少其一documentOpenAPI 描述文档可以是 URL、文件路径或对象specificationdocument的弃用别名。可选onRequest({ context, operation })每个请求被处理前的回调validateRequest设为false时始终返回 mock 响应不再以422拒绝违反契约的请求默认truelogger传false可静默启动时打印的认证说明或传(line) void将日志重定向到测试 logger、文件、缓冲区默认输出到控制台。技能还描述了服务启动时的内置行为序列处理并加载 OpenAPI 描述文档执行x-seed播种幂等仅当集合为空时播种为声明的 security schemes 注册认证路由为每个 path method 注册操作路由在/openapi.json与/openapi.yaml暴露源文档。从源码结构看这一序列对应 packages/mock-server/src 下的模块化实现create-mock-server.ts 负责装配set-up-authentication-routes.ts 与 handle-authentication.ts 负责认证路由respond-with-openapi-document.ts 负责暴露文档端点行为与技能描述一致。2. x-handler动态请求处理在操作的x-handler扩展中编写 JavaScript可以取代静态 example 生成动态响应。handler 运行时提供以下辅助对象store内存持久化支持list、get、create、update、delete、clearfaker生成真实感测试数据req请求数据body、params、query、headersres按状态码索引的响应示例res[200]、res[404]…。状态码约定store.get()/store.update()找到返回200未找到返回404store.create()返回201store.delete()删除成功204未找到404store.list()返回200返回null/undefined触发404文档中若提供了responses.404示例/模式则使用它。完整用法见 Custom Request Handlers 文档实现与测试可参考 execute-handler.ts 和 x-handler.test.ts。3. x-seed启动时数据播种在components.schemas.SchemaName上使用x-seed扩展服务启动时自动填充初始数据。可用辅助函数seed.count(n, factory)按工厂函数生成 n 条seed(array)整数组播种seed(factory)单项快捷方式另可访问faker、store与schema。关键规则schema 的 key 名即集合名——components.schemas.Pets上的x-seed播种到Pets集合。播种是幂等的仅当集合为空时执行。更多细节见 Data Seeding 文档实现与测试位于 execute-seed.ts 与 x-seed.test.ts。4. OpenAPI 操作中的认证在 OpenAPI 文档中声明securitySchemes如httpbearer、apiKey后mock server 会校验请求认证启动时打印认证说明可用logger: false静默并注册认证相关路由包括授权页与 token 端点见 respond-with-authorize-page.ts 与 respond-with-token.ts。受保护操作在凭据不匹配时返回文档中定义的未授权响应。技能提示的排障思路核对securitySchemes声明与请求凭据是否匹配。5. Docker 运行与排障技能收录的 Docker 运行命令docker run -p 3000:3000 scalarapi/mock-server --url https://api.example.com/openapi.yaml文档来源的优先级从高到低--url URL命令行参数OPENAPI_DOCUMENT环境变量文档内容OPENAPI_DOCUMENT_URL环境变量文档 URL挂载到/docs卷的文件。常用路由mock 端点来自 OpenAPI paths、/scalar内置 API 参考 UI、/openapi.json与/openapi.yaml描述文档。完整的四种配置方式与示例见 Docker 文档 及镜像仓库 packages/mock-server/docker/README.md。技能文件末尾附了一份排障清单是 agent 调试 mock 环境时的检查顺序确认 OpenAPI 描述文档有效且可访问确认至少配置了一种文档来源document、--url、环境变量或挂载文件播种数据缺失时检查x-seed是否写在 schema key 上、启动时集合是否为空受保护路由返回未授权时核对securitySchemes与请求凭据自定义逻辑失败时检查x-handler运行时错误handler 异常会返回500并携带错误详情;对于未处理的500error为Internal Server Error读取响应中的operation对象——它指明失败的 HTTP 方法与 OpenAPI 路径文档声明了operationId时也会一并给出。作为 MCP 使用 Scalar Docs除了文件系统形式的技能Scalar 还提供 MCP 接入方式使用https://scalar.com/mcp端点可以把 Scalar Documentation 作为 MCP server 添加到你的 agent 工具中让 agent 通过 MCP 协议直接检索文档内容与本地安装的技能形成互补。相关文档索引资源路径本文对应文档documentation/guides/mock-server/agent-skills.mdmock-server 技能源文件.agents/skills/mock-server/SKILL.mdscalar-docs 技能源文件.agents/skills/scalar-docs/SKILL.mdScalar Docs Agent Skill 文档documentation/guides/docs/configuration/agent-skills.mdMock Server 入门documentation/guides/mock-server/getting-started.md自定义请求处理器documentation/guides/mock-server/custom-request-handler.md数据播种documentation/guides/mock-server/data-seeding.mdDocker 指南documentation/guides/mock-server/docker.mdmock-server 包入口packages/mock-server/src/index.ts安装完成后coding agent 即携带上述全部上下文遇到“按 OpenAPI 文档起一个 mock 服务”“加动态 handler”“预置测试数据”“容器化 mock 环境”这类任务时可直接按技能中的选项说明、状态码约定与排障清单给出可运行的方案而不需要额外检索文档。【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考