结构化编辑
结构化编辑让 omp 能够改写语法,而不是匹配原始文本。对于必须能承受不同空白、注释或格式差异的 codemod 来说,它很有用;而暂存式预览会让超出预期的宽泛匹配在改动落地之前就变得可见。
最小的实用请求就是一句自然语言:
在
src/**/*.ts范围内,把对legacyWrap的调用替换为modernWrap,并保留每一个参数。展示提议的结构化编辑,且仅当它改写的是调用表达式时才应用。
由你来指定结果、范围和安全条件。omp 负责选择并操作编辑机制;你无需自己编写模式,也无需亲自调用编辑工具。
结构化、符号感知,还是文本编辑?
omp 有三种修改代码的相关方式:
- 结构化编辑 匹配语法形状。即使格式不同,它也能找到同一个函数调用形式,并一致地改写大量实例。它适用于 API 迁移、重复的表达式改动、import 形式的更新,或移除某一特定的语句形状。
- 符号感知编辑 沿引用、作用域、import 与再导出追踪某个声明的身份。当你重命名的是一个真正的符号、而不是所有拼写相同的代码时,请提出这种要求。参见代码智能。
- 文本或行编辑 最适合范围小且位置明确的代码、散文、配置,或没有受支持解析器的代码。参见文件与编辑。
结构化匹配是语法感知的,而不是绑定感知的。两个互不相关却都叫 legacyWrap 的函数,在它看来可能完全相同。如果符号身份很重要,请明确说出来:
重命名
src/session.ts中导出的createSession符号,并更新它真正的引用与导入方。不要重命名同名但无关的局部函数。
对于包含相似命名代码的 codemod,请给 omp 足够的上下文来收窄范围:
在
packages/api/src/**/*.ts范围内,只迁移从@acme/legacy导入的legacyWrap调用。不要触碰测试夹具或局部声明的函数。如果无法证明 import 的来源,就停下来并说明这种歧义。
请求并审查 codemod
一份有力的请求应包含:
- 范围 —— 文件、目录或 glob。
- 改动前后的行为 —— 描述代码形状以及必须保留的内容。
- 排除项 —— 生成的代码、夹具、另一个拼写相同的 API,或任何其他边界。
- 决策规则 —— 当预览满足特定条件时才应用,或仅预览后即停。
- 验证 —— 应用之后 omp 应检查的聚焦命令或行为。
例如:
在
packages/client/src/**/*.ts范围内,仅在response可能不存在的地方,把直接的response.data读取转换为可选访问。保留注释与周围的控制流。先预览;如果替换超过 20 处或包含该目录之外的任何文件,则拒绝。应用后,运行客户端的 typecheck。
卡片状态的含义
结构化改写会在触碰磁盘之前先暂存。TUI 会显示受影响的文件、替换数量以及删除/新增的行。
- Proposed 表示预览已生成,但其改动尚未写入。
- Accept 表示 omp 接受了该提议,并会报告实际写入的内容。
- Reject 表示暂存的提议已被丢弃;该提议没有改动任何文件。
这些标签只是报告状态,并不是 shell 命令。用自然语言告诉 omp 你想要什么,例如“仅当每个匹配都在 src/compat 中时才应用”,或“拒绝这个提议,并解释那些意外的测试文件匹配”。
如果要进行明确的两轮审查,可以这样开始:
只预览这个 codemod,不要应用它。
omp 会展示该提议并将其丢弃,而不是让一个旧的待处理 action 一直悬着。审阅完文件与数量之后,请让 omp 带上你的审批条件再次运行同一个 codemod。第二次运行会针对当前工作树生成一份全新的预览。
安全审查
在接受大范围改写之前:
- 对照你的预期核对替换总数与文件数量。
- 展开提议卡片,并从每一种不同的代码形状或包中至少检查一处匹配。
- 警惕拼写相同但互不相关的符号;必要时切换到符号感知的重命名。
- 收窄路径,而不是接受一处意外匹配后再计划修复它。
- 让 omp 检查最终的 diff,并在接受之后运行范围最小且相关的 typecheck 或测试。
- 审查时让无关的未提交改动保持可见。结构化编辑会改动这些文件中被匹配的语法;它不能替代对整个工作树 diff 的检查。
如果预览过期
接受操作会针对当前文件重新执行改写,而不是盲目重放旧的字节。如果预览与接受之间发生了另一次编辑并改变了匹配,omp 会把预览标记为过期,并报告新结果。
结果取决于还有哪些内容仍能匹配:
- 如果不再有任何匹配,则不应用任何替换。
- 如果只有部分预览过的位置仍然匹配,omp 可以先应用这些当前的匹配,再报告接受的结果与预览不同。
- 如果出现了新的匹配,omp 应用的替换可能多于预览所显示的,并会标记数量不一致。
要把过期结果当作错误处理,而不是一次全有或全无的成功事务。检查所报告的文件与当前 diff,然后让 omp 重新读取受影响的代码,生成一份全新的、范围更窄的预览。不要反复接受旧的提议。
歧义与过期不同:即使语义上只打算匹配一处,结构化匹配器也可能合理地找到多处语法相同的代码位置。文件清单与替换数量就是警示。请先细化请求,或改用符号感知编辑,然后再应用。
解决合并冲突
你可以不机械地选边,直接要求想要的结果:
解决
src/session.ts中的冲突。保留我们分支的重试行为,以及传入分支的超时校验。展示最终的 diff,并运行会话测试。
当 omp 读取包含完整 Git 冲突标记的文件时,它会为每个块分配一个会话内引用,例如 conflict://1。你可以把该引用粘贴到后续消息中以消除歧义:
对于
conflict://2,把两边合并起来:保留我们的校验和他们的错误消息。修改之前先重新读取周围的函数。
conflict://1保留我们的,conflict://3保留他们的,并手工合并conflict://4,使两种行为都不丢失。
conflict://* 表示会话中当前登记的全部冲突。请谨慎使用,并说明同一策略是否真的适用于所有冲突:
解决
conflict://*,但逐个独立检查每个块。不要整块选边;在兼容的地方把两种行为都保留下来。
引用只在 omp 读取并登记了标记块之后才会出现。它们属于会话内,旧会话中的 ID 不应复用。如果某个块在登记之后被编辑或已解决,omp 会拒绝拼接它已无法定位的标记区域,并要求重新读取。解决一个块不会使其他无关的已登记块失效。
冲突解决是一种直接的合并操作,而不是结构化编辑提议。对于高风险合并,先让 omp 说明打算如何解决,再请求执行编辑并审查最终的 Git diff。请求中还应当包含对冲突标记的最后一次搜索,以及相关测试。
配置
结构化编辑默认启用。打开 /settings,进入 Tools → Available Tools → AST Edit 即可开启或关闭。对应的设置项是 astEdit.enabled;对于由 shell 管理的配置:
omp config set astEdit.enabled true
omp config set astEdit.enabled false关于配置优先级与文件位置,参见设置。
一次结构化遍历默认最多搜索 1,000 个文件。如果仓库确实很大、需要不同的上限,可在启动 omp 之前设置正的 PI_MAX_AST_FILES 环境变量。通常,面对上限警告,更稳妥的回应是收窄所请求的目录或 glob,而不是调高上限。
受限制的 --tools 列表也可能让结构化编辑不可用,即使该设置已启用。这种情况下,请恢复常规的编辑工具,或让 omp 提供限定范围的替代方案。
局限性
- 结构化编辑理解的是语法,而不是类型、运行时行为或符号归属。在这些方面重要时,请使用代码智能与验证。
- 只有拥有受支持解析器的语言才能被结构化改写。无法干净解析的文件可能会被跳过,并给出解析警告。
- 改写必须把可识别的语法映射为替换语法。需要生成数据、控制流分析或多条协同语句的跨文件变换,更适合用专门的脚本加上人工审查的 diff 来处理。
- 注释与格式不会妨碍语法匹配,但改写仍可能改变被替换节点周围的格式。请审查渲染后的 diff。
- 过大或过于笼统的请求可能触达文件上限,或产生过多无法安全审查的合法匹配。请按包或代码形状拆分它们。
- 合并冲突引用只能识别完整且格式良好的 Git 标记块。不完整或被人为破坏的标记必须当作普通文本来检查。
故障排查
“未进行任何替换”
请让 omp 检查一个具体的例子,并解释它为什么没有匹配。代码可能使用了不同的语法,路径可能收得过窄,也可能符号感知编辑才是更合适的操作。在某个有代表性的用例能正确预览之前,不要扩大到整个仓库。
解析警告
让 omp 找出受影响的文件,并确认它们能按所声明的语言解析。先修复损坏的语法、排除生成或不支持的文件,或在结构化解析不适用时使用范围严密的文本编辑。
匹配过多或意外匹配
拒绝该提议。在请求中加入 import 来源、接收者类型、外层函数、包、文件 glob 或明确的排除项。如果区别在于符号身份,请改为请求基于 LSP 的重命名。
“已达上限”
收窄范围并重新运行。当达到搜索上限时,预览是不完整的,因此它的数量并非整个仓库的总数。
“预览已过期”
检查当前的 diff,因为可能已经应用了部分匹配或一组有变化的匹配。然后让 omp 重新读取文件并创建新预览;只有当新的文件数与替换数符合预期时才接受。
conflict:// 引用未知或已不存在
让 omp 重新读取该冲突文件。这会刷新会话的冲突索引,避免把某个决定应用到标记或周边文件已经发生变化的块上。
