wp-interactivity-api

wp-interactivity-api 技能概览

这个技能能做什么

wp-interactivity-api 技能可以帮助你构建或排查 WordPress Interactivity API 功能，而不必靠猜 directive、store 结构，或者 server/client 的连接方式。它最适合处理 data-wp-* 标记、@wordpress/interactivity、viewScriptModule 或 wp_interactivity_*() 函数相关问题时使用，能把一个“交互坏了”的场景，带到可落地的修复路径上。

适合哪些人

如果你在 WordPress 的 block、theme 或 plugin 中做 Frontend Development，并且需要一个能顺利通过首屏渲染的交互式 UI，就应该使用 wp-interactivity-api skill。当你已经有一个 repo，想追踪为什么 hydration 失败、为什么某个 directive 没有触发，或者如何正确搭建一个新的交互区域时，它尤其合适。

为什么值得安装

它的核心价值是提升决策速度：告诉你该搜什么、哪些输入最关键，以及如何区分基于 block、theme 层和 plugin 增强这几种做法。相比通用 prompt，wp-interactivity-api guide 更能贴合实际，因为它反映了 WordPress 6.9+ 的真实约束，以及这套 API 的实际接线方式。

如何使用 wp-interactivity-api 技能

正确安装并限定使用范围

先从目录入口使用 wp-interactivity-api install 模式，然后在具备 bash 和 Node 的、可访问文件系统的 agent session 中应用这个技能。仓库说明里提到它兼容 WordPress 6.9+，部分工作流还需要 WP-CLI；如果你的环境不能检查项目文件，或者不能运行 WordPress 命令，结果会明显变弱。

提供正确的起始输入

wp-interactivity-api usage 在你提供以下信息时效果最好：

• repo root
• wp-project-triage 的排查结果
• 受影响的范围：frontend、editor，或两者都有
• WordPress 版本，以及任何 module/build 约束

弱一点的提问是：“修复 Interactivity API。”
更强的提问是：“排查为什么这个 block 在 frontend 上 data-wp-on--click 不触发，WordPress 6.9，已启用 module scripts，附上 triage 结果，且问题只在 navigation 之后出现。”

先读这些文件

先看 SKILL.md，然后打开：

• references/directives-quickref.md：查看 directive 名称和搜索锚点
• references/debugging.md：查看失败排查清单
• references/server-side-rendering.md：查看 PHP 侧设置和 hydration 规则

如果你正在判断这个技能是否适合当前任务，这三个文件比单看 repo tree 更快暴露真实工作流。

按照实用流程推进

这个技能围绕一个简单的顺序组织：

1. 通过搜索 data-wp-interactive、@wordpress/interactivity 和 viewScriptModule 找出已有用法
2. 确认 store 命名空间，以及 markup 是否期待同名
3. 验证 server-rendered context 和初始状态
4. 检查渲染后的 HTML 里是否同时存在 root element、view script module 和事件 directive
5. 逐步缩小范围，直到定位到坏掉的 directive 或 state 路径

对于新的 interactive block，优先使用官方 scaffold template，而不是从零凭空搭结构。

wp-interactivity-api 技能 FAQ

这个技能只是用来排错吗？

不是。wp-interactivity-api skill 同时覆盖构建和排查两类工作。它尤其适合你需要决定：是通过 block 的 viewScriptModule 加入交互，还是在 plugin 中增强已有 markup，或者以仍能正确 hydration 的方式为 theme 层接入行为。

它和普通 prompt 有什么不同？

普通 prompt 经常会跳过真正决定成败的 WordPress 细节：directive 命名、store 命名空间是否匹配、server-side context，以及 WordPress 6.9 的行为变化。这个技能把这些检查内置进流程里，能减少无效尝试，并帮助 agent 优先读对文件。

适合新手吗？

适合，只要你能说明目标，并把 agent 指向正确的 repo 区域。它不是从零学习整个 API 的教程，但它能帮新手避开最常见的踩坑：interactive root 缺失、namespace 不匹配、以及用了错误的渲染路径。

什么情况下不该用它？

如果是 WordPress Interactivity API 之外的无关 JavaScript UI 工作，或者功能完全静态、不需要 server-rendered directives，就不要用它。如果你无法检查真实的 repo 文件，它也不太适合，因为这个技能依赖于与仓库相关的 markup 以及 PHP/JS 集成细节。

如何改进 wp-interactivity-api 技能

提供更精确的源上下文

最好的结果来自同时给出当前的 block、theme 或 plugin 范围，以及你希望审查的具体 directive 或 function。把 data-wp-interactive、data-wp-context 附近的代码片段，还有对应的 store 命名空间一起带上，这样 agent 就能直接对照意图和实现，而不是靠猜。

说明失败模式，而不只是症状

对 wp-interactivity-api skill 来说，“按钮没反应”太笼统了。更好的输入会明确可观察到的故障和预期行为，比如：“click handler 已经绑定，但 server render 之后 state 没有更新”，或者“首次加载 hydration 正常，但 client-side navigation 后失败”。这样更容易区分是 directive 问题、state 初始化问题，还是 module 加载问题。

先让它输出仓库阅读结果，再继续迭代

一个好的 wp-interactivity-api guide 工作流应该让它先给出：

• 最可能的根因
• 下一步需要精确检查的文件
• 最小化代码改动
• 任何 WordPress 6.9 兼容性风险

然后基于第一次结果继续迭代。如果问题和 server rendering 有关，就把相关 PHP 和渲染后的 HTML 一起提供出来；如果问题和事件处理有关，就带上 directive markup 和 store actions 文件。这样这个技能就不只是搜索助手，而是可以真正用于实现落地的检查清单。