给 Cursor 接口上下文，应按任务裁剪

dev.to · AI#Cursor#上下文工程#接口开发

Editor brief · 编辑速览

文章指出，整份 OpenAPI 文档会让无关 schema 挤占上下文，增加接口误用和关键字段遗漏的风险。建议提供当前任务所需的最小规范片段，或使用从规范生成的定向工具。

文章思维导图

Knowledge map

拖拽缩放

AI deep read

AI 深度解读

把整份 OpenAPI 文档塞给 Cursor，看起来是在补足 API 知识，实际可能挤掉当前任务更需要的代码和约束。作者主张：完整规范留在本地作为权威来源，交给 AI 的则是按任务生成的工具或规范切片。

这篇短文的价值，在于把「多给上下文」改成了「给最小完整上下文」。不过，原文没有提供性能测试或错误率对照，工具配置和命令也需要核实，适合当作工作流建议阅读。

作者认为，大型 OpenAPI 文档中的大量 schema 与当前任务无关。让模型同时阅读这些内容，会降低有效信息的占比：它可能选中其他服务的操作，漏掉真正相关的字段，也可能没有足够空间容纳代码和后续推理。

可以把它理解成查数据库：需要一行数据，却先把所有表搬进工作区。资料齐全，不代表眼前的任务更容易完成。

这里需要区分两个问题：上下文窗口能否装下，以及模型能否准确使用。作者认为，更大的窗口能缓解容量压力，却不能自动消除无关信息的干扰。

目标应该是提供最小但完整的任务上下文。

「完整」同样重要。只给一个接口路径，却漏掉请求体引用的 schema，也会逼着模型猜字段。裁剪不是单纯追求短，而是保留完成任务所需的定义及其依赖。

作者提出的第一条路线，是从 OpenAPI 规范生成 MCP server，让模型按需调用操作。MCP 可以理解为向 AI 提供工具的一套接入方式；模型需要订单数据时调用订单工具，不必事先阅读所有服务的契约。

原文用 ./openapi.yaml 作为来源，只暴露 getOrder、listOrders、createOrder、captureOrder 四个操作。选择依据是团队实际使用的工作流，后续再按需要扩展。

这个方案减少了模型需要预先持有的信息，也把部分交互变成结构化调用。作者进一步声称，工具会返回经过验证的结构化响应，但没有说明具体生成器、验证规则或实现方式。因此，不能把「接入 MCP」直接等同于「请求和响应都已正确校验」。

跨多个服务的任务，也沿用这个思路：按需调用工具，避免一开始就载入每个服务的全部 schema。不过，工具描述、参数和返回结果仍然会占用上下文；原文没有量化最终能省多少。

如果只是一次性开发，为此搭建工具服务可能成本过高。作者的第二条路线，是从规范中提取相关 paths，以及这些路径引用的 component schemas，再由打包工具自动解析引用。

原文给出的命令意图，是生成订单接口的最小契约。下面保留输入中的原样写法：

openapi-cli bundle \ --spec ./openapi.yaml \ --paths /v1/orders \ --output /tmp/orders-slice.yaml

要核对的是这一行中的 --paths /v1/orders：它表达了裁剪目标，但原文没有交代 openapi-cli 的具体实现、版本及参数支持情况，而且输入把反斜杠与后续参数排在同一行，不能直接当作可执行的 Shell 命令复制。

比命令本身更重要的是生成关系：完整的 ./openapi.yaml 保持权威地位，/tmp/orders-slice.yaml 在任务开始时从它生成。不要另维护一份手写简化版，否则很容易在字段变更后失去同步。

这里的本地优先流程，是把完整规范留在本地，再按需派生工具或切片。它能否保持最新，仍取决于上游规范是否及时更新，以及生成过程是否覆盖了相关引用。

我赞同把上下文当作有限预算，尤其是仓库里同时存在多个服务契约时。把与订单页面无关的接口全部交给模型，确实缺少明确收益；围绕任务选择操作和依赖，至少能让输入范围更容易检查。

但作者没有给出规范体积、模型版本、任务样本、token 消耗或成功率，也没有展示 Cursor 的实际失败案例。「整份规范降低质量」在这篇文章里属于经验判断，不能据此断言所有模型、所有任务都会变差。

两条路线也不必强行统一。偶尔生成一个页面或修改请求参数，规范切片更轻便；团队长期让 agent 调用同一批接口，工具化才更有复用价值。原文也没有比较它们与编辑器按需搜索规范的效果，不能据此判定后者更差。

文章属于 Powerduck 与 Cursor 的比较系列，但这部分没有产品对照数据，支撑不了选型结论。