wp-rest-api

wp-rest-api 技能概览

wp-rest-api 的用途

wp-rest-api 技能能帮你更少靠猜地处理 WordPress REST 端点：创建路由、暴露内容类型、校验参数、塑造响应，以及修复认证或权限失败的问题。它最适合你在真实的 plugin、theme 或 mu-plugin 中，需要一份实用的 wp-rest-api API Development 指南，而不是一条泛泛的提示词的时候。

适合谁使用

如果你正在添加或排查 register_rest_route()、WP_REST_Controller、register_rest_field、register_meta、show_in_rest，或者 REST schema / validation 逻辑，就适合用 wp-rest-api 技能。对于需要快速判断仓库是否支持你的端点工作、以及该如何安全推进的开发者来说，它非常合适。

它有什么不同

这个技能聚焦的是 WordPress 特有、且经常会卡住落地的约束：permission_callback、nonce 或 application password 认证、路由命名空间、context=edit、_fields，以及基于 schema 的校验。wp-rest-api 的核心价值在于，它会在你开始写代码之前先把你引到正确的 REST 模式上，从而减少权限错误、客户端回归和错误的响应结构。

如何使用 wp-rest-api 技能

安装并确认适用范围

使用 npx skills add WordPress/agent-skills --skill wp-rest-api 安装 wp-rest-api 技能。编辑之前，先确认自己处在正确的仓库根目录，并找出实际的 plugin/theme 入口文件。如果项目是完整站点代码库，就要把范围缩小到真正拥有该端点的那个单独组件。

收集最少但关键的输入

想让 wp-rest-api install 结果更好，最好提供：目标 namespace 和 version、route path、预期 HTTP method、认证方式，以及 WordPress 最低版本。弱一点的请求是“加一个端点”。更强的请求会像这样：my-plugin/v1/orders，只给已认证编辑者使用，只返回 order ID、status 和 total，校验 page 与 per_page，并支持 ?_fields= 以提升客户端性能。

先读对文件

先看 SKILL.md，然后再检查 references/routes-and-endpoints.md、references/authentication.md、references/schema.md、references/responses-and-fields.md、references/discovery-and-params.md 和 references/custom-content-types.md。这些文件会告诉你这个技能期望如何串起路由、权限、schema 和内容暴露，比盲目翻仓库更有用。

按实用工作流推进

先用这个技能梳理现有 REST 用法，再决定实现路径：自定义路由、controller class，还是暴露已有类型。构建提示词时要围绕目标资源形态，而不只是端点名字。比如，要说明响应是否公开还是仅编辑态可见、是否复用 core fields，以及数据来自 post meta、CPT 还是计算逻辑。这样模型才有足够上下文，输出真正可用的 wp-rest-api usage 结果。

wp-rest-api 技能常见问题

这只适合自定义路由吗？

不是。wp-rest-api 技能同样适用于通过 show_in_rest 暴露 CPT 和 taxonomy、添加自定义字段或 meta，以及调整已有端点的响应行为。如果你只需要一个一次性的 fetch 示例，普通提示词可能就够了；但如果你需要路由设计或兼容性检查，这个技能会更合适。

什么情况下不该用 wp-rest-api？

如果你的任务和 WordPress REST 内部机制无关，或者你是在只消费一个已经稳定 API 的客户端应用里工作，那就没必要用它。它也不适合服务器代码无法修改、你只需要文档或请求示例的场景。

它适合新手吗？

适合，只要你能编辑 WordPress PHP 文件，并能清楚描述自己想要的资源即可。新手最容易踩的坑是把认证和权限说得太含糊，最后导致路由看起来能用，但对未登录用户、编辑者或外部客户端却失败。

它和通用提示词比有什么区别？

通用提示词也许能给你代码，但当你需要 WordPress 特有的护栏时，wp-rest-api 更有用：必需的 permission_callback、schema 校验、响应塑形和路由发现。也正因为如此，当你在意的是可靠性而不只是语法时，这个技能更适合做安装决策。

如何改进 wp-rest-api 技能

给模型资源形态，不只是目标

最有价值的改进，是把端点应该返回什么、谁可以调用说清楚。写明对象类型、字段、写入权限，以及任何特殊筛选条件。比如：return published products with \id`, `name`, `price`, and `stock_status`; allow authenticated managers to update `stock_status` only.这样可以让wp-rest-api` 技能输出精度高得多。

先把失败上下文说出来

如果你是在排错，请直接给出具体症状：401、403、404、缺少 nonce、namespace 错误，还是 schema 无效。也要说明路由是公开访问、cookie 认证，还是使用 application passwords。这样模型才能区分是认证失败、路由注册问题，还是数据结构问题。

在提示词里用上仓库细节

把仓库里已有的相关文件、controller class 或 post type 直接点出来。如果代码里已经有 show_in_rest、rest_base 或 meta registration，也要说明。最好的 wp-rest-api guide 输出，通常来自锚定现有架构的提示词，而不是要求从零实现一套全新的东西。

从校验迭代到润色

拿到第一版结果后，每次只要求一个小范围改进：更严格的 schema、更好的权限检查、用 _fields 精简响应，或者兼容 non-pretty permalinks 的路由。如果输出质量还是不理想，就把提示词收紧到具体请求和预期 JSON 结构；这通常比让它生成一个“更好”的端点更有效。