用途：在技能激活期间，所有 PHP 写入都应使用 php-ast-edit。PHP 片段是构造输入，工具解析后修改 AST 并打印结果；事务被拒绝后不要退回文本修改，应检查错误并修正原因。
首次使用：先解析可执行文件，依次尝试仓库 bin/php-ast-edit、项目 vendor/bin/php-ast-edit、已安装的 php-ast-edit，或本技能的 scripts/php-ast-edit 包装器。需要时运行 help。缺少解析器需安装引擎，而非反复重试编辑。现有文件默认使用保留格式的打印，无需先做规范化；doctor 解释可选规范配置，并非每次编辑的前提。
工作流：用常规搜索或 LSP 定位代码。优先使用命名目标，如 {"select":"method:Checkout::submit"}；其他选择器包括 class:、interface:、trait:、enum:、function:、property:Foo::$items、const:Foo::LIMIT。名称有歧义会被拒绝。仅在名称无法标识目标（如方法体内的表达式）时使用 inspect，并保留其 ref 与 sha256。将相关编辑（含多文件）放入一个 apply 事务；依赖已读快照时需包含文件 sha256，ref 与坐标绑定该快照。出现 STALE_SOURCE 后应重新读取并评估，切勿移除保护强行执行。设置顶层 "report": "compact" 可让每个验证结果只返回一次。
提供紧凑且有效的片段。命名空间 PHP 中需导入或限定外部类型，例如 JSON 内的 \DateTimeImmutable。不要花 token 复现缩进。阅读 effects、diff、所有警告与验证结果；parsed 仅表示解析成功，legacy valid 含义同样有限。compact 报告中按每个文件的 checkIds 查看顶层 verify。检查 lint 与项目验证命令是否运行；验证失败即使文件已写入也需修复。只运行尚未执行的必要检查。审阅预期 diff，编辑本应改变它；不要以干净的 Git diff 作为编辑成功条件。局部编辑避免全仓库格式化。
最小事务示例：{"report":"compact","files":[{"path":"src/Registry.php","edits":[{"target":{"select":"class:Registry"},"operation":"add_member","php":"public function register(string $name): void {}"}]}]}，命令为 php-ast-edit apply --input edits.json。省略 report 或设为 "full" 保留旧版逐文件 verify 布局；报告模式只改变呈现，checksPassed: null 表示未运行检查。
选择窄操作：空成员/方法体/参数列表用 insert_into 加 property 与 position，或 add_member 等简写，无需兄弟锚点。替换任意节点用 replace_node，改槽位用 replace_child。新文件用 mode: create，含 <?php 的完整 PHP，默认 expectAbsent 保护。删除用 mode: delete 加快照哈希。局部变量重命名用 rename_variable，作用于外层方法/函数/闭包，带 from 与 to；不安全的绑定冲突会被拒绝，动态变量行为无法完全静态解析。方法重命名用 rename_method 加 to，需检查未解析接收者与继承限制，它不会更新项目中所有调用方；仅改声明可用 set_name。PHP 字面量内的 SQL/HTML/JSON 用 set_string 作用于其 Scalar_String 节点。可用 php-ast-edit contexts --operation rename_variable 获取紧凑参数帮助。
限制：不要将 AST、解析器通过或宿主 lint 通过等同于应用行为正确。需要跨文件符号解析时，应使用项目感知的重构工具。参考资料包括操作（完整 schema、选择器、保护、parseAs、报告）、格式化（保留布局、可选规范化）与强制执行（可选 hook 及其限制）。