abilities-api-implement

Abilities API 实现 — WooCommerce 扩展操作手册

此技能可一站式将 WooCommerce 扩展从“尚未注册任何能力”推进到“已打开草稿 PR，能力面已验证”。它会读取上游 wp-abilities-audit 生成的审计文档，并依次完成以下阶段：搭建注册器、每项能力单独提交一次、运行集成测试框架、打开 PR。

严格交接——此技能要求提供有效的审计文档；如果找不到或无法解析文档，则会报错退出。

与上游技能的关系

本操作手册中可移植的部分位于 WordPress/agent-skills：

上游技能	职责
wp-abilities-audit	生成此技能所需的审计文档。负责插件系列检测、分组启发式规则和审计架构。
wp-abilities-api	可移植模式——委托辅助函数模式、错误代码词汇表、输入架构注意事项（分页键漂移、架构默认值）和插件系列模式。
wp-abilities-verify	集成测试框架——wp-env 枚举 / 注释 / 执行 / 权限门控检查，以及审计架构验证。

此技能负责其上的 WooCommerce 扩展层：

• 根据 WooCommerce 扩展的命名空间、自动加载布局、测试基类和引导入口搭建注册器。非 Woo 插件系列（Jetpack 系列、通用 WordPress 插件）不在本操作手册的适用范围内——请直接使用上游技能 wp-abilities-api（WordPress/agent-skills），并遵循宿主项目自身的约定。
• WooCommerce 扩展原语——命名空间规则、MCP 暴露方式选择、共享的 woocommerce 分类约定、woocommerce_ability_definition_classes 加载路径，以及必需的 meta.mcp.public / meta.mcp.type 默认值。
• 为便于审查，每项能力采用一次原子提交的约定。
• PR 模板遵循目标仓库自己的 .github/pull_request_template.md，并提供需填写的能力专属部分。
• 审计前置条件检查，用于捕获搭建时反复出现的问题（能力门控漂移、插件系列不匹配、缺少后端控制器）。

概览

给定一份审计文档，此技能会生成：

1. 在扩展的源代码树下新增一个 Abilities_Registrar 类。
2. 每项已注册能力单独进行一次原子提交（先提交参考能力，再提交读取能力，最后提交写入能力）。
3. 覆盖结构、权限和执行路径断言的单元测试。
4. 保存为 Markdown 工件的集成测试框架运行结果。
5. 针对扩展仓库打开一个 PR。

此技能会在推送代码并打开 PR 后停止。它不会向问题跟踪系统或聊天工具发帖，也不会尝试从未完成的运行中恢复——如果运行过程中出现问题，请手动修复，然后从失败阶段重新调用。

仅加载器模式——可依赖的内容

此技能搭建的是 WC 10.9 的 AbilityDefinition + woocommerce_ability_definition_classes 加载器结构。对于运行 WC < 10.9 的商店，注册器会静默地不执行任何操作——不提供 polyfill，也没有备用注册路径。结构性门槛是检查 \Automattic\WooCommerce\Internal\Abilities\AbilitiesLoader 是否存在；发布期间的安全网是各插件的 <plugin_slug>_abilities_enabled 功能标记。

搭建前请阅读 references/wc-1009-dependency.md——其中介绍了为何不提供 polyfill、使 Domain 类可安全部署到 WC < 10.9 商店的延迟自动加载特性，以及对测试环境的影响（WC < 10.9 的 CI 矩阵会通过 markTestSkipped 正常跳过）。

用法

请在扩展的工作树内调用：

/woocommerce:abilities-api-implement <path-to-audit-doc>

如果未传入参数，技能会自动检测 plans/（vault 或扩展本地目录）下最新的 *abilities-audit*.md 文件。

前置条件 — 审计文档必须有效

开始任何脚手架搭建前，先验证由 wp-abilities-audit 生成的审计文档。

现在阅读 references/audit-precondition.md，了解前置条件检查清单。此清单是在 wp-abilities-verify 的规范审计架构验证器之上进行验证，而不是替代它。如果已安装 WordPress/agent-skills 中的 wp-abilities-verify 技能，也请阅读 wp-abilities-verify/references/audit-schema-validation.md，了解规范架构检查；先运行这些检查，再运行 audit-precondition.md 中针对 Woo 扩展的检查。

如果前置条件检查失败，立即停止。不要只搭建一部分脚手架。

执行计划

实现分为六个阶段。每个阶段结束时都会生成一个或多个原子提交。

阶段 I — 搭建协调器和 Domain 文件夹

创建：

• Abilities_Registrar 协调器 — init() 包含功能标志门控和 WC 10.9 加载器门控、空的 ABILITY_CLASSES 常量、append_classes() 过滤器回调、CATEGORY_SLUG = 'woocommerce' 常量，以及 <CanCapHelper>() 能力助手。协调器不会注册分类 — woocommerce slug 由 Woo Core 负责（参见 woo-extension-primitives.md §5）。
• Domain/Abstract<Plugin>Ability — CATEGORY_SLUG 常量（与注册器中的常量保持一致）+ delegate_to_rest_controller()（在阶段 III 的 Shape-2 读取中使用）。如果已知该功能面包含列表形状的能力，现在就添加 paginated-output-envelope.md 中的分页助手；否则，可以等到第一个列表形状的 Domain 类出现时再添加。
• 阶段 I 测试 — 六种情况：功能标志关闭时退出、加载器不存在时退出、加载器存在时接入过滤器、append_classes() 往返、能力助手，以及 $initialized 静态保护下的 init() 幂等性。

将 Abilities_Registrar::init() 接入扩展的引导流程。

功能标志门控。 当 <plugin_slug>_abilities_enabled 过滤器返回 false 时（发布期间的默认值），注册器的 init() 必须提前退出。这样可以在尚未确定最终能力形状时发布注册脚手架。此过滤器按站点单独启用；等功能面稳定后，将默认值切换为 true。

现在阅读 references/registrar-template.md — 其中包含 WooCommerce 扩展类模板、测试基类规则、功能标志模式和引导接入位置。对于此文件所适配的通用机制（调用形状模式、委托助手签名、错误代码词汇），请先阅读 wp-abilities-api 的 references/plugin-family-patterns.md、references/delegate-helper-pattern.md 和 references/error-code-vocabulary.md（如果已安装该技能）。

现在阅读 references/wc-1009-dependency.md — 其中说明加载器门控的原因：为什么协调器的 woo_abilities_loader_available() 检查是结构性门控（而功能标志只是发布安全网），为什么 ABILITY_CLASSES 中的 ::class 常量不会在 WC < 10.9 时自动加载 Domain 类，以及后续阶段中每项能力测试使用 markTestSkipped 模式的原因。

现在阅读 references/woo-extension-primitives.md — 其中记录了审计文档无法单独表达的 WooCommerce 扩展规则：能力命名空间、woocommerce_ability_definition_classes 加载器、是否公开已弃用的 MCP 端点、必需的元数据默认值，以及共享的 woocommerce 分类约定（§5 — 包括使用插件 slug 作为分类的反模式，以及不得重复注册的规则）。这些规则适用于阶段 II–IV 中注册的每项能力。

提交形式： feat(abilities): scaffold Abilities_Registrar coordinator + Domain base。

第二阶段——注册第一个能力（参考模式）

选择最简单、安全的只读操作——通常是无需参数的“get -summary”或“get -statuses”风格能力，无需构造 WP_REST_Request。此提交将建立 Domain 类参考模式，供其余能力照此实现：每个能力对应一个 Domain/<Name>.php 文件，实现 AbilityDefinition，并包含 get_name() / get_registration_args() / execute() 静态方法，然后列入 Abilities_Registrar::ABILITY_CLASSES。

现在阅读 references/first-ability-template.md——其中介绍了注册辅助函数、带防御性检查的执行回调、双状态返回处理，以及两个必需的测试（结构 + 权限）。

替代后端控制器：如果审计中该能力的备注提到替代后端控制器（例如，一个位于 admin 命名空间，另一个位于 reports 命名空间，且两者的输出结构不同），请暂停并与用户确认后再搭建脚手架。

提交格式：feat(abilities): add <plugin-slug>/<ability-name> ability。

第三阶段——注册其余只读能力

能力 #2 合并后，在提取任何辅助函数之前，先为每个剩余的只读能力选择合适的路径。

Woo 扩展覆盖层的结构偏好：

结构	模式	使用时机
3 — 共享服务	能力、REST 和 UI 都调用同一个共享服务类（<PluginNamespace>\Internal\Service\<Thing>_Service——与 \Internal\Abilities 命名空间同级，而非其子命名空间）	**默认选项。**写操作（第四阶段）必须使用。只读操作也默认使用此方案：共享领域/服务辅助函数采用 UI 和 REST 控制器已有的相同代码路径，能力层则为 Agent 使用整理输出。
2 — 委托给 REST	能力构建 WP_REST_Request，并通过 delegate_to_rest_controller 辅助函数调用 rest_do_request()	经明确审查的例外方案，仅适用于低风险只读操作。只有在确认后端控制器没有副作用，且 REST 处理器不会添加能力将原样继承的传输层产物（信封结构、_links、嵌入式超媒体、由标头派生的字段），并且控制器所依赖的请求上下文辅助函数（current_user_can 路径、is_admin()、did_action、基于标头的行为）在 REST 请求生命周期之外表现相同时，才可接受。
1 — 重新实现	能力自带 SQL / 验证逻辑	**避免使用。**必然出现实现偏差。

为什么结构 3 是 Woo 扩展的默认方案（而不只是“首选”）：

• **REST 输出包含传输层产物。**控制器会针对 HTTP 整理输出——信封键、_links、嵌入式超媒体、指向下一页/上一页的链接。能力层需要的是经过整理的数据，而不是传输层结构；结构 3 让能力可以调用领域辅助函数，并自行组装面向 Agent 的结构。
• **请求上下文辅助函数在 REST 之外表现不同。**nonce 验证背后的 current_user_can 检查、is_admin() 分支、did_action('rest_api_init') 守卫、基于标头的权限解析——这些在 REST 下通常会通过，在 CLI / cron / Agent 调用下却会失效。结构 2 会在不知情的情况下继承所有这些问题。
• **指标陷阱。**后端控制器通常会发出分析事件、触发 WP 钩子或派发通知。每次由 Agent 驱动的结构 2 调用都会污染这些计数器——仪表板会将 Agent 记录成“调用过此端点的人类用户”。结构 3 让能力可以直接调用领域辅助函数，并发出带有自身能力标记的副作用（也可以不产生副作用）。
• 首次调用的 REST 引导开销。rest_do_request() 会调用 rest_get_server()，后者会延迟实例化 WP_REST_Server，并在每个请求中触发一次 rest_api_init。在 REST 请求生命周期内，这项开销会被分摊；在生命周期之外（CLI、cron、非 REST MCP 传输、Agent 工作流），首次调用委托能力时则必须承担全部引导开销。

搭建脚手架时的决策顺序：

1. 是否已有域名／服务辅助类可执行此操作？→ 采用形态 3，调用它。
2. 审计的 side_effects 字段是否声明了任何非空副作用（遥测钩子、审计日志、通知、缓存写入、锁获取）？→ 采用形态 3；如果尚无服务，则提取一个。
3. 该能力是否主要在 REST 之外调用？→ 采用形态 3。
4. REST 处理程序是否会生成传输产物，或依赖请求上下文辅助函数（见上文“为何默认采用形态 3”）？→ 采用形态 3。
5. 以上情况均不符合，且读取操作确实风险较低 → 可以将形态 2 作为经过明确审查的例外方案。请在 PR 的“给审阅者的备注”中注明权衡和已验证的前提条件。

对于仅限加载器的模式，delegate_to_rest_controller() 是 Abstract<Plugin>Ability 上的 protected static 方法（本地抽象基类，见 registrar-template.md）。领域类以 self::delegate_to_rest_controller(...) 的方式调用它。

对于形态 2，规范的辅助函数实现、签名、双响应形态解包方式，以及零参数能力的两异常规则都在上游：

如果已安装 WordPress/agent-skills 的 wp-abilities-api skill，请现在阅读其 references/delegate-helper-pattern.md。 否则，references/registrar-template.md 中的模板提供了一个自包含的辅助函数，它会构建 WP_REST_Request、调用 rest_do_request()，并解包 WP_REST_Response 和原始数组这两种返回形态。

对于分页参数，一些后端控制器使用不同的键（例如使用 pagesize，而非 per_page）：

如果已安装 wp-abilities-api skill，请现在阅读其 references/input-schema-gotchas.md（“分页键不一致”一节）。 否则，检测方法是：在后端控制器的 get_collection_params()（或同等方法）中搜索 pagesize、page_size 或其他非 per_page 分页键，并在能力边界处进行转换，而不是将非标准键传入能力的输入架构。

提交格式：

• 提取服务（形态 3）：refactor(<plugin>): extract <Thing>_Service for shared business logic。
• 提取辅助函数（形态 2）：refactor(abilities): extract delegate_to_rest_controller helper。
• 每项能力：feat(abilities): add <plugin-slug>/<ability-name> ability。

第 IV 阶段 — 注册写入能力

如果审计发现任何写入能力，应在完成所有读取能力后再落地。**首轮批次默认只读。**添加写入能力会扩大面向 Agent 的操作范围；以下规范可避免批次脚手架意外扩大范围。

明确的写入门槛 — 添加任何写入能力前，逐项审查以下四点：

1. **行为。**该操作确实会改变状态（关闭终端、退款、作废、产生下游影响的状态更改），而不是伪装成 POST 的变更型 GET，也不是伪装成读取操作的 setter。请对照审计文档中的 intent 和 use_case_fit 字段。
2. **权限门槛。**权限必须在审计的 permission.source 中记录的规范来源处实施（领域／服务／管理员操作层，而不只是 REST 控制器的 permission_callback）。该能力的 permission_callback 应查询此规范来源，而不是想当然地照搬 REST 回调。请交叉参阅上游文档：wp-abilities-audit/references/capability-gate-tracing.md。
3. **服务路径。**必须采用形态 3（第 III 阶段的表格）。该操作必须已有共享服务类，或在此写入能力的提交之前，通过一个已落地的 refactor() 提交提取共享服务类。
4. **注解。**每个值都应反映实际行为，而不是从读取能力中复制粘贴：明确设置 readonly: false、destructive: <true|false>、idempotent: <true|false>。验证技能的对抗性检查会发现不实之处；最好一开始就如实设置。

如果上述任何一项审查发现未知之处，应暂停编写能力，而不是猜测。写入能力是最容易因草率落地而造成严重损害的范围。

现在阅读 references/write-ability-template.md — 该文档介绍了写入能力的领域类形态（必须采用形态 3，即使用共享服务，不能把 HTTP 方法作为参数；写入能力绝不能使用抽象基类的 delegate_to_rest_controller()）、必需输入验证模式，以及架构默认值陷阱。对于可移植的输入架构和架构默认值陷阱，如果已安装 wp-abilities-api，请参阅其中的 references/input-schema-gotchas.md。

提交形式： feat(abilities): add <plugin-slug>/<ability-name> ability。

第 V 阶段 — 集成测试框架

启动 wp-env，枚举能力，验证注解，执行读取操作， 测试写入输入验证，并确认权限门槛。将输出保存为 Markdown 文件，供 PR 使用。

**两个验证级别。**冒烟级别用于发现引导和严重错误回归；高置信度级别则针对每项能力实际将在生产环境中遇到的数据形态进行测试。两者都通过公开的能力边界（wp_get_ability( $name )->execute( $input )）执行，而不是调用注册器的静态方法。

• **级别 1 — 冒烟执行（合成输入）。**确认每项读取操作都返回 OK 或词汇表中的 WP_Error；每项写入操作在缺少输入时都返回 ability_invalid_input 或插件的 <plugin_slug>_missing_<field> 错误码。可发现 PHP 致命错误、未引导的服务、注册失败以及写入输入验证缺漏。
• **级别 2 — 高置信度验证（有代表性的种子数据）。**对于审计文档中声明了非 null seed_data_needs 的每项能力，优先采用此级别。根据该字段为插件填充真实的数据，以有代表性的输入（真实 ID、真实 slug，而非合成占位符）调用能力，并断言：(a) 符合文档说明的输出形态；(b) 符合隐私约定（能力未承诺提供的敏感字段不得出现）；(c) 对真实记录的权限行为正确（匿名用户被拒绝、订阅者被拒绝、预期角色获准）。级别 2 能发现 ID 错误却返回了其他记录、缓存的哨兵值被返回、权限门槛对合成 ID 放行但对真实 ID 不放行、过滤与未过滤标签不一致，以及能力继承自控制器字段导致精选输出发生偏移等问题。 当某项能力的 seed_data_needs: null 时，Level 2 会报告 pending (ask the implementer) 并继续执行——这与审计架构实现就绪字段中 WARN 而非 FAIL 的处理方式相吻合。

使用 WordPress/agent-skills 中的 wp-abilities-verify 技能——这是集成测试框架的可移植权威版本。其 references/runtime-harness.md 中的 Check 3 定义了规范的 Level 1 / Level 2 划分；其他检查涵盖注释正确性、权限往返、架构 lint，以及只读但会写入的检测器。该技能生成的产物格式正是此 PR 模板所呈现的格式。

关键门槛——只读但会写入的检测器。 审计中的每项 readonly: true 能力都必须通过验证技能的对抗式 annotation-correctness 检查 （参见 wp-abilities-verify/references/annotation-correctness.md）。 某项能力声称 readonly: true，却调用 $wpdb->update、update_option、 wp_insert_*，或通过非 GET HTTP 方法委托操作，这就是单元测试无法 发现的错误类别——mock 看起来和真正执行写入的对象完全一样。 该检测器未通过时，绝不允许 PASS。 如果检测器标记了某项能力， 要么修正注释（设置 readonly: false），要么修正回调，使其真正只读。

如果未安装 wp-abilities-verify，则改为手动运行测试框架： 通过 wp eval 'print_r( array_keys( wp_get_abilities() ) );' 列举能力， 抽查注释并通过 WP-CLI 执行行为测试，同时将命令和输出记录到产物文件中。

将集成测试框架纳入插件自身的测试套件，而不只是生成一次性的 PR 产物。 wp-abilities-verify 的运行会生成附在 PR 上的产物；插件内的 PHPUnit 测试则在之后每次 CI 运行中证明公开契约。现在就阅读 references/test-the-public-contract.md——其中介绍了六个契约维度（权限、 输入、注释、精选输出、隐私、执行行为），插件内的测试 MUST 通过 wp_get_ability() 进行断言，而不是直接调用注册器的静态方法。

产物： plans/<YYYY-MM-DD>-<plugin-slug>-abilities-harness-output.md。

提交形式： 如果测试框架发现了 bug，就用一个小型独立提交修复 （例如 fix(abilities): ...）。测试框架输出文件本身不会提交到扩展仓库—— 它存放在用户的 plans 目录中，并在 PR 正文中引用。

Phase V.5 — 测量 token 成本

每组能力都应附带 token 成本数值。暂定预算为 MCP tools/list 中每个插件约 2,000 个 token。

**如果已安装 wp-abilities-measure 技能，**则针对刚注册的能力集运行该技能，并记录两个数值：

• 插件 <plugin-slug>/* 命名空间的 tools/list token 成本（所有共享该扩展能力 ID 前缀的能力；参见 woo-extension-primitives.md §1）。
• 每项能力的平均值。

预算门槛。 如果插件的 tools/list 超过约 2,000 个 token：

1. 在创建 PR 前暂停。该插件的能力范围过大。
2. 正确的重新设计方向是投影层（例如，改用 STRAP / facade / 嵌套发现的形式来呈现能力给 MCP），而不是注册层。先重塑注册方式，会在测量结果告诉我们哪种形式有效之前，就把能力范围锁定在某种粒度上。
3. 投影层重新设计后重新测量。如果仍超出预算，说明应先发布更精简的 MVP，并推迟这些能力。

未安装 wp-abilities-measure 时的备用方案。 手动估算： 通过 wp eval 将插件的 tools/list 载荷导出为 JSON，然后使用任意 分词器统计 token 数。在 PR 正文中将此数值标记为暂定值，以便评审者了解 测量下限。

PR 正文中的“Coverage numbers”部分必须包含 token 成本数值。

第六阶段 — 推送并创建 PR

向扩展的默认分支创建 PR。

现在阅读 references/pr-template.md——其中包含参数化 PR 正文模板，以及一条规则：先阅读扩展仓库自身的 .github/pull_request_template.md，并填写其中的必填部分，而不是覆盖它们。

第六阶段.1 — 添加 AGENTS.md 漂移防护

在扩展的 AGENTS.md 中添加一句话（放在现有的“在此区域工作”或“更改 X 时”部分下；如果没有此类部分，则新建一个）：

更改已注册能力背后的代码路径时，请检查是否需要更新注册信息（注解、架构、描述）。

这是一个成本低的人为闭环防护措施，可避免能力与其底层服务 / REST 控制器之间发生无声漂移。将其作为独立提交提交：

chore(agents): note ability-registration audit when changing controller code

歧义处理 — 何时暂停

遇到以下情况时，请先暂停并询问用户，然后再继续：

• 审计中的任何 proposed_abilities 条目的 backing: null。
• 任何拟议能力的 Notes 中提到了备选的 backing 控制器。
• 审计中的 plugin_family 与根据 CWD 自动检测到的类别不同。
• 审计中声明的能力门控与在脚手架生成时重新读取基础 REST 控制器后解析出的结果不同。
• 审计中的 route_registration_line / callback_line 提示，无法在当前分支中匹配到对应的 (class, callback_name) 组合（提示可能已漂移；以重新 grep 的结果为准）。

此列表中的每一项都需要暂停并交由操作者处理——没有安全的自动解决方式。

错误代码词汇

执行回调返回的每个 WP_Error 都必须使用标准化词汇，以便 Agent 构建不依赖字符串匹配的重试逻辑。该词汇由上游定义：

如果已安装 WordPress/agent-skills 中的 wp-abilities-api skill，请现在阅读其 references/error-code-vocabulary.md。 否则，本 skill 的模板中使用的最低错误代码集合如下：

• <plugin_slug>_invalid_input — 输入未通过验证（对应 Abilities API 自身的 ability_invalid_input）。
• <plugin_slug>_missing_<field> — 回调运行时缺少某个必填字段，且未进行架构验证（例如直接调用）。
• <plugin_slug>_not_found — 引用的资源（订单、产品等）不存在。
• <plugin_slug>_permission_denied — 权限检查未通过，但此时 permission_callback 已经通过（这种情况很少见，通常表示回调重新检查了依赖数据的权限门控）。

与扩展现有的 WP_Error 代码惯例和文本域保持一致。如果扩展在其他地方已使用 <plugin_slug>_rest_* 或 woocommerce_<ext>_rest_* 代码，请沿用该前缀，而不要另创命名空间。

完成标准

宣布完成前，请逐项检查清单：

• 所有提交均为原子提交——不要求每个提交只涉及一个文件，但每个提交必须对应一项逻辑变更。
• 每个已注册能力都有各自的功能提交。
• 在本地使用扩展自身的测试命令运行单元测试，且全部通过（请参阅扩展的 AGENTS.md 或 composer.json/package.json 中的脚本）。
• 新文件通过 PHPCS（或扩展的 lint 命令）检查。
• 集成测试框架的输出已保存到 plans/<YYYY-MM-DD>-<plugin-slug>-abilities-harness-output.md（如果已安装 wp-abilities-verify，则使用它；否则采用手动回退方案）。
• PR 正文已填写扩展自身的 .github/pull_request_template.md 中要求的部分。
• PR 已创建，并在终端输出中附有链接。

清单全部通过后，向用户报告 PR URL。