wp-phpstan

wp-phpstan 技能概览

wp-phpstan 适用于你需要让 PHPStan 在 WordPress 代码库里真正“好用”，而不只是“勉强跑起来”的场景。它面向插件、主题和站点开发者，目标是更干净的静态分析、更少的误报，以及一条可操作的旧代码修复路径，尤其适合那些本来就有历史问题的项目。

它的核心工作是配置和修复：连接 phpstan.neon，处理 baseline，加载 WordPress stubs，以及在 PHPStan 无法推断运行时行为时补充 WordPress 语义的类型标注。

wp-phpstan 最适合什么场景

在以下情况下使用 wp-phpstan 技能：

• 在 WordPress 仓库中搭建或更新 PHPStan
• 减少因 WordPress 核心符号缺失导致的报错
• 管理 phpstan-baseline.neon，同时不掩盖新的回归问题
• 修复动态 WordPress 模式，例如 hooks、REST 请求和查询结果
• 处理可选的第三方插件类，例如 WooCommerce 或 ACF

wp-phpstan 为什么不一样

通用的 PHPStan 提示词往往会忽略 WordPress 的特有约束：运行时加载的类、hook 回调、插件依赖，以及与线上站点并不一致的分析环境。wp-phpstan 的价值在于它会优先处理这些边界情况，尤其是 stub 加载和有针对性的忽略规则。

什么时候不该用它

如果你只是想快速问一个 PHPStan 命令怎么写，这个技能可能有点“用力过猛”。它最有价值的时机，是当分析质量已经重要到足以影响安装选择、baseline 策略和类型标注方案的时候。

如何使用 wp-phpstan 技能

安装并验证该技能

对于 wp-phpstan install，请从 WordPress agent skills 仓库添加这个技能：

npx skills add WordPress/agent-skills --skill wp-phpstan

安装后，先读 SKILL.md，再看配套参考文档和检查脚本。这个仓库的结构就是为了解答最影响采用效果的问题：PHPStan 实际看到了什么、忽略了什么、哪些问题应该补类型而不是直接压掉。

给技能提供正确的输入

在请求修复之前，wp-phpstan 技能最需要项目上下文。建议先提供：

• wp-project-triage 的输出
• 是否允许修改 Composer 开发依赖
• 是否允许更新 baseline
• 你想修改的具体 PHPStan 报错或配置文件

弱一些的提示词：“帮我修复 WordPress 插件里的 PHPStan。”

更强的提示词：“请用 wp-phpstan 检查我插件当前的 PHPStan 配置，确认是否已加载 szepeviktor/phpstan-wordpress，并提出最小化的配置改动，修复未知的 WordPress 函数，但不要使用大范围忽略。只有在已有的历史遗留错误上才允许修改 baseline。”

建议的工作流和文件

要高效使用 wp-phpstan，按仓库自己的决策路径走：

1. 用 scripts/phpstan_inspect.mjs 检查当前设置
2. 查看主配置和 baseline 文件
3. 阅读 references/configuration.md
4. 阅读 references/third-party-classes.md
5. 当问题是类型推断而不是配置时，再看 references/wordpress-annotations.md

如果你想最快得到可用结果，可以先预览这些文件：

• SKILL.md
• references/configuration.md
• references/third-party-classes.md
• references/wordpress-annotations.md
• scripts/phpstan_inspect.mjs

实用的提示词写法

好的提示词会告诉技能：哪些内容是固定的，哪些是可调整的，以及你希望它输出什么。比如：

• “帮我审查这个 WordPress 插件的 phpstan.neon，看看我应该加 stubs、收紧 ignoreErrors，还是更新 baseline。”
• “把这个 REST controller 的注解改写一下，让 PHPStan 能理解请求结构。”
• “我的分析环境里没有 WooCommerce；请为这些缺失类提出一个范围尽量小的 stub/ignore 策略。”

这类细节能帮助 wp-phpstan 在配置改动、注解补充和依赖变更之间做出正确选择。

wp-phpstan 技能 FAQ

wp-phpstan 只适用于 WordPress 插件吗？

不是。wp-phpstan 同样适合主题，以及带有自定义代码的 WordPress 站点。只要 PHPStan 需要理解 WordPress 的运行时行为，它就有用。

我需要先安装 Composer 和 PHPStan 吗？

需要。这个技能默认你的流程是基于 Composer 的 PHPStan 工作流。如果仓库不用 Composer，或者 PHPStan 根本不在工具链里，这个技能就不太适合。

这比自己写一个自定义提示词更好吗？

通常是的，前提是你在意可复用的安装和配置决策。自定义提示词也许能解决单个报错，但 wp-phpstan 在 baseline、stubs 和 WordPress 专属类型处理上，能给你更完整的工作流。

什么时候应该避免大范围忽略？

当类或函数其实是存在的，只是缺了 stub、autoload 有问题，或者分析环境和真实运行环境不一致时，不要用大范围忽略。只有在确认依赖链真实存在、而且无法干净修复之后，才使用有针对性的忽略。

如何改进 wp-phpstan 技能

先说清楚 PHPStan 的真实失败模式

wp-phpstan 要想给出好结果，最好先判断失败类型，再去求修复：

• 未知的 WordPress 核心函数 → stubs 或配置问题
• 历史遗留噪音 → baseline 工作流
• 动态请求数据 → @phpstan-param 或可复用的类型别名
• 可选插件 API → 定向 stubs 或窄范围忽略

如果你只贴一长串错误列表，技能很可能会优化“症状”，而不是“病因”。

说明分析边界

告诉技能它能改什么，结果会更好。你可以明确说明：

• 能不能改 composer.json？
• 能不能添加开发依赖？
• 能不能改 phpstan.neon？
• 能不能重新生成 baseline？

这些权限会决定 wp-phpstan 应该优先走代码修复、配置修复，还是依赖修复。

尽量给具体输入，不要只给笼统目标

输入越具体，输出通常越好。比如请提供：

• 当前 PHPStan 级别
• 分析哪些目录
• CI 里是否包含 WordPress core
• 具体是哪个插件或哪个类在报缺失符号错误

这样 wp-phpstan 才能为后端开发工作推荐合适的安装和使用路径，而不是丢给你一份泛泛的 PHPStan 清单。

按“配置 → 注解”顺序迭代

一份好的 wp-phpstan guide 通常会按这个顺序推进：

1. 先确认 stubs 和发现机制是否正常
2. 再收窄 excludes 和 ignores
3. 然后为 WordPress 特有的动态类型补注解
4. 最后只对已接受的历史技术债更新 baseline

这个顺序能让分析保持足够严格，继续捕捉新问题，同时又能在 WordPress 的动态模型阻碍推断时减少误报。