简介
API 的构建方式正在发生转变。二十年来，操作者是在图形界面中点击的人，而 API 契约的消费者是阅读文档的人。如今这两端都在变化：
- 操作者越来越多地是把意图转化为行动的 AI 助手；
- 消费者越来越多地是通过 MCP 把 API 当作工具调用的 AI 智能体。
定义了上一个时代的工具——API 客户端、规范查看器、请求集合——都是为坐在键盘前的人打造的。Powerduck 则为这个时代而生。它不是一个更好用的 API 客户端，也不是一个更漂亮的规范查看器，而是一个从一份 OpenAPI 文件出发的 AI 原生平台。
核心：一份本地 OpenAPI 文件
一切都始于你仓库中的一个普通 openapi.yaml——开放、可版本控制、人和 AI 都能阅读。它不是专有数据库，也不需要云账号。
one local openapi.yaml
|
you + AI -> design debug test mock docs data-model
|
MCP tools
|
any AI coding agent
那一份文件就是契约。每个工作流都从它读取，同一份文件还可以通过 MCP 交给任何 AI 编程智能体——因此你、内置助手以及每个外部智能体都共享同一个事实来源。当设计、调试、测试、Mock 和文档都读取同一份文件时，"让各工具保持同步"就不再是一项任务。这是设计带来的结果，而非目标本身。
Powerduck 支持 OpenAPI 3.2，并通过就地升级来读取已有的 3.0、3.1 文档（以及 Swagger 2.0）。非 HTTP API——SSE、WebSocket、GraphQL、gRPC 和 MCP——通过 x-protocol 扩展建模在普通的路径项上，而不是被强行塞进仅支持 REST 的形态。
你如何与 AI 协作
- 打开一个 YAML，助手会立即建议你可以用它做什么；
- 用平实的语言陈述结果——"创建订单相关接口""准备测试数据""运行结账流程并给我一份报告"——助手会选择合适的工具并提出改动；
- 每一项改动都以可审阅的卡片呈现；在你批准之前不会应用任何内容；
- 当你细化某个 API 时，助手会停留在该 API 上，只改动你要求的部分，而不会在整个文档中漂移；
- 可接入任何兼容 OpenAI 的模型。在桌面端，提示词和密钥永远不会离开你的机器。
默认本地优先
Powerduck 在你的机器上运行，打开并保存真实文件，可离线工作，并让 API 密钥和提示词远离浏览器。云是用于分享和发布的可选扩展，从不是开始使用的前提。
使用 Powerduck 的三种方式
| 形态 | 它是什么 | 最适合 |
|---|---|---|
| 桌面客户端 | 一个本地优先的 Electron 应用，内置 AI 助手和完整的 API 工作区 | 希望一切都在自己机器上、离线工作、密钥和提示词保留在本地的工程师 |
| Powerduck Cloud | 用于 OAS 托管、在线文档和托管 MCP 的云服务 | 与他人共享 API、发布稳定链接，以及无需运行任何程序即可提供 MCP |
| 开源库 | 可组合的 @powerduck/* npm 包 | 构建你自己的工具、CI 流水线或嵌入式组件 |
三种形态共享相同的引擎：桌面客户端和云端都由开源库组装而成，因此无论你在本地运行、通过网络调用还是直接引入包，同一个能力的表现都一致。
桌面客户端
桌面客户端完全在你的机器上运行。它打开并编辑磁盘上的真实文件，通过本地进程发送请求，运行本地 Mock，并让你的 AI 提示词和 API 密钥远离浏览器控制台。模型完全由你配置，每个提议的改动在应用前都以可审阅的卡片呈现。
Powerduck Cloud
Powerduck Cloud 把同样的工作流搬到线上。添加文件、Git 仓库或 URL；选择要暴露哪些操作；然后获得渲染文档的稳定链接和托管的 MCP 端点。访问可以用查看密码或 MCP 访问密钥保护，付费计划增加了 Git 同步、自定义域名和更高的额度。
开源库
这些库是底层引擎：OpenAPI 解析器与升级器、多协 议 CLI、代码生成器、MCP 服务器、请求运行器、cURL 与 Postman 转换器，以及可嵌入的编辑器。每个包都在 npm 上独立发布，带有自己的安装指南和 API 参考——底层技术细节都在这里。
对你意味着什么
- 你指挥结果，而不是点击。 描述目标，助手通过可审阅的步骤完成工作。
- 你的 API 天然面向智能体就绪。 生成文档的同一份契约也生成 MCP 工具，因此 AI 智能体从第一天起就能正确调用你的 API。
- 没有漂移。 设计、调试、测试、Mock 和文档都读取同一份文件。
- 所有协议集中一处。 HTTP、SSE、WebSocket、GraphQL、gRPC 和 MCP 存在于单一规范中，而不是六个工具里。
- 无锁定。 自带模型，桌面端密钥保留在本地，并拥有仓库中那份普通的 YAML。