前言¶
改 block.json、换保存结构、加动态渲染，很容易在编辑器里看到「Invalid block」、属性存不住，或在 WordPress 7.0 的 iframe 编辑器里样式对不上。区块开发牵涉元数据、序列化、资源作用域和 deprecation 链，步骤顺序错了，问题往往要回头拆。
下面介绍 WordPress 官方 Agent Skills 里的 wp-block-development：按固定流程做新建、注册、渲染和迁移，并指向仓库内 reference 文档与脚本。
这是什么¶
wp-block-development 是 WordPress agent-skills 仓库中的 Skill，面向 Gutenberg 区块从脚手架到上线的完整工作流。
官方描述覆盖：block.json 元数据、register_block_type / register_block_type_from_metadata、attributes 与序列化、supports、动态渲染（render.php / render_callback）、deprecations 迁移、viewScript 与 viewScriptModule，以及 @wordpress/scripts、@wordpress/create-block 的构建与测试。
兼容性（SKILL 元数据）： 目标 WordPress 7.0+（PHP 7.4.0+）；基于文件系统的 Agent，需要 bash 与 node；部分流程依赖 WP-CLI。
核心功能¶
资料中列出的能力如下，均对应 SKILL 中的 Procedure 与 references。
| 方向 | 内容 |
|---|---|
| 项目定位 | 配合 wp-project-triage 的 detect_wp_project.mjs，用 list_blocks.mjs 扫描含 block.json 的区块根目录 |
| 新建区块 | 推荐 @wordpress/create-block 脚手架；需要 Interactivity API 时用 interactive 模板 |
| apiVersion 3 | WordPress 6.9+ 在 schema 上强制 apiVersion 3；为 iframe 编辑器（WordPress 7.0）准备样式与脚本作用域 |
| 区块模型 | 静态（save() + 稳定序列化）、动态（render / render_callback）、前端交互（优先 viewScriptModule，Interactivity 用 wp-interactivity-api） |
| 元数据与安全修改 | block.json 字段说明见 references/block-json.md；改 name 会破坏兼容；改保存结构需 deprecated |
| 服务端注册 | PHP 元数据注册，便于翻译、条件加载与动态渲染（references/registration.md） |
| 编辑 / 保存 / 渲染 | useBlockProps、useBlockProps.save()、get_block_wrapper_attributes()；内嵌块用 useInnerBlocksProps() |
| 属性与序列化 | 确认 comment / HTML / context 来源；避免已废弃的 meta source（references/attributes-and-serialization.md） |
| 迁移 | deprecated 从新到旧、save 与可选 migrate（references/deprecations.md） |
| 工具链 | 沿用仓库已有的 @wordpress/scripts、wp-env 等（references/tooling-and-testing.md） |
验证清单： 插入器可插入；保存重载无 Invalid block；前端输出符合静态或动态预期；编辑器与前端资源加载正确；跑 triage 推荐的 lint / build / test。
排错入口： references/debugging.md，以及属性、deprecation 相关 reference。
安装与启用¶
通过 officialskills.sh 公布的命令安装到本地 Skills 环境：
npx skills add https://github.com/WordPress/agent-skills --skill wp-block-development
也可把 Skill 目录链接交给支持 Agent Skills 的编码助手，由其按项目约定安装：
https://github.com/WordPress/agent-skills/tree/trunk/skills/wp-block-development
安装后，Agent 按 SKILL.md 的 Procedure 执行；仓库内 references/ 与 scripts/ 为配套说明与脚本，无需单独「配置文件」字段（资料未给出 Cursor / Codex CLI / Claude Code 的差异说明，此处不展开）。
典型用法¶
使用前准备：仓库根路径、目标载体（插件 / 主题 / 整站）、区块命名空间与 block.json 路径、目标 WordPress 版本区间（尤其涉及 module / viewScriptModule）。整站仓库需明确区块落在哪个插件或主题。
0）定位区块¶
先做项目分诊，再列出区块目录：
node skills/wp-project-triage/scripts/detect_wp_project.mjs
node skills/wp-block-development/scripts/list_blocks.mjs
确认要改的目录即为包含 block.json 的区块根。
1）新建区块（可选）¶
用 @wordpress/create-block 脚手架，阅读 references/creating-new-blocks.md。脚手架完成后再次运行 list_blocks.mjs 确认路径，再继续元数据与注册。
2）升级到 apiVersion 3¶
在 block.json 中设置 apiVersion: 3（自 v2 迁移通常只改该字段，但需在启用 iframe 编辑器的本地环境验证）。确保样式句柄写在 block.json 中，避免 iframe 内样式缺失；注意第三方脚本对 window 的作用域。细节见 references/block-json.md。
3）改元数据并注册¶
按静态 / 动态 / 交互模型实现 edit / save / render，服务端优先 register_block_type_from_metadata。动态块见 references/dynamic-rendering.md；容器块见 references/inner-blocks.md。
4）改保存结构时加 deprecation¶
若调整已发布内容中的 markup 或属性：
- 在
deprecated中从新版本到旧版本依次声明； - 为旧版提供
save，必要时用migrate规范化 attributes。
详见 references/deprecations.md，可避免保存后出现 Invalid block。
5）构建与本地验证¶
使用项目已有的 npm script（@wordpress/scripts）或 wp-env 做本地 WordPress 与 E2E，参见 references/tooling-and-testing.md。
适用场景与注意¶
适合：
- 新建或维护插件 / 主题中的 Gutenberg 区块；
- 修复 block invalid、不保存、属性不持久化；
- 为静态块增加
render.php或服务端render_callback； - 规划 apiVersion 2 → 3，适配 WordPress 7.0 编辑器 iframe；
- 容器块与 Inner Blocks 的包装属性与迁移。
限制与注意：
- 目标环境为 WordPress 7.0+；旧版本行为以官方 Developer Resources 与 Gutenberg 文档为准（SKILL 中的 Escalation 节）。
- 部分步骤依赖 WP-CLI 与 node 脚本，纯手动改文件而不跑 list / triage 时，Agent 仍可按 reference 指引，但定位成本更高。
name视为稳定 API；未配 deprecation 就改保存 HTML，是资料中明确列出的常见坑。
结尾¶
wp-block-development 把区块开发拆成可核对的分步流程：先扫 block.json、选对静态或动态模型、安全改元数据、用 deprecation 兜住历史内容，并用仓库内 reference 对齐注册与序列化。它是 WordPress 在 Agent Skills 生态里针对核心编辑体验的一条官方路径。
