SGLang 机械重构验证规范解析用忠实重放原语与字节级 diff 证明纯搬迁提交【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang导读本文是 SGLang 仓库内.claude/skills/mechanical-refactor-verify技能体系中规范级文档spec-reproduction-utils.md的深度解读它以源码真相源source of truth的姿态定义了**纯搬迁clean move**属性、14 个忠实重放原语faithful relocation primitive的契约以及重放 字节级 diff仲裁器arbiter的语义。读完本文你将掌握如何把一次文件拆分、函数移动、模块抽取、改名这类机械重构从靠肉眼 review转变为任何人、任何时候都能一键重跑并得到 PASS/RESIDUAL 结论的机器可验证过程并能在 SGLang 仓库对应的 Python 实现中找到每个概念的落点。1. 规范文档的定位谁是真相源spec-reproduction-utils.md是整套mechanical-refactor-verify技能中单提交证明层面的规范源头与之配套的文件分工如下均位于仓库 .claude/skills/mechanical-refactor-verify/ 目录下spec-reproduction-utils.md本文解读对象定义纯搬迁属性§2、每个原语的契约§3与字节级 diff 仲裁器语义§4spec-reproduction-cli.md链条验证规范定义提交分类词规则、证明义务、报告与退出码guide-split.md如何把一次改动拆成 prepare move postpare 三阶段guide-construct-proof.md如何生成/手写证明guide-verify-proof.md如何审阅证明guide-modify-skill.md如何修改本技能自身。规范明确了一条铁律模块、其测试、各指南均以此文件为准一旦出现分歧此文件胜出this file wins。也就是说仓库中的实现 scripts/mechanical_refactor_reproduction_utils.py 是规范的执行者而本文件是它唯一的事实依据。2. 核心属性什么是纯搬迁clean move规范的基石是一条可证明的属性定义一个提交是clean move当且仅当它所做的每一个改动都是按相同顺序被搬迁relocated的代码——允许整块一次统一缩进平移uniform indentation shift——外加一小类固定的搬迁副产物move artifacts除此之外别无其他。等价表述该提交只能由 §3 的原语组合重放出来。规范还点出了机制上的关键设计——白名单§2.1恰好是原语能做的事黑名单§2.2是原语拒绝做的事任何白名单之外的动作都会以残余 diffresidual diff的形式浮出水面而不是被悄悄吞掉。从实现看这个属性由 mechanical_refactor_reproduction_utils.py 顶部的模块 docstring 复述每个原语只做搬迁忠实的编辑AST 定位、按原始源码文本拼接、永不重新生成代码所以格式化后的字节匹配就能证明提交恰好等于那次搬迁。verify_mechanical_refactor()同文件第 83 行起是该属性的最小落地在一次性 worktree 检出 base 提交 → 运行 transform → 对变更文件跑 pre-commit → 与目标提交做字节级 diff。2.1 白名单允许的全部搬迁规范列出的可证明搬迁包括按序搬迁的行整块允许一次统一的前导缩进平移如从模块级移入类体整体缩进 4 空格从分散位置收集 def/class 到新模块每个定义逐字剪切、在经过审计的作者化头audited authored header下组装。头审计只接受import、docstring、TYPE_CHECKING导入块、logging.getLogger(__name__)记录器、从源中实际删除的赋值drop_assigns的 unparse 等价副本、或在源中原样幸存的模块常量的 unparse 等价副本——例如_is_hip is_hip()这类可重推导样板因为同一语句仍留在源文件中故可证非虚构。每个被删除的赋值必须重新出现在头中否则直接抛错而非认证被抽取函数的函数体内联块逐字搬入新 defdef签名、可选的return、替换用的call是作者化的。仅当函数体原样移动时才忠实de-self、控制流重构、簿记合并都属于语义改动须先进独立提交import 语句新增、删除、改路径单行或带括号均可直接按目标实现全新模块的语句逐字搬入保留换行包裹形式新模块迁移可加from __future__ import annotations单侧staticmethod/classmethod方法 ↔ 自由函数从被移动定义上删掉self类型注解如把staticmethod def foo(self: Target)搬入Target变成def foo(self)调用点重新限定requalificationOwner.foo(x)→foo(x)符号与参数字节不变只去掉限定符而Old.foo(x)→New.foo(x)的宿主替换不是原语会作为残余浮现调用点降级loweringOwner.method(receiver, rest)→receiver.method(rest)接收者从参数列表移到调用者位置删除被搬空的源文件除 docstring、import、TYPE_CHECKING块外别无他物delete_file拒绝删除任何其他内容空行变化忽略见 §2.3。2.2 黑名单以下情况不是clean move规范明确拒绝的包括被移动块内行序重排不搬迁任何定义的语句级重排它改变求值顺序是需要人工确认的整形而非可认证的搬迁非统一的缩进变化可能改变 Python 语义行尾空白、内部空白变化或行合并/拆分被重新限定调用中参数的改动对本提交未移动符号的调用重写除删self注解外的签名变化被移动符号的改名哪怕只是_foo→foo的可见性翻转向已有模块作者化脚手架或常量logger、模块常量、TYPE_CHECKING守卫、重推导的_flag compute_flag()——注意新模块的头允许从目标作者化已有模块的函数体不是写新代码的地方从源搬迁的常量不是作者化由move_assign认证被抽取函数中函数体改动de-self、控制流重构、合并簿记。整形工作改名、新脚手架、语句重排、改动抽取函数体应归属 guide-split.md 的 prepare/postpare 阶段证明系统会把它报告为残余绝不认证。2.3 空行为何被忽略空行永不改变 Python 行为PEP 8 分隔空行在搬迁中合法塌缩。实现上格式化器会同时归一化重放侧与目标侧所以纯空行差异到不了字节 diff 层。规范同时声明了一个前提假设目标提交本身是 pre-commit 干净的凡是过了本仓库 hooks 的提交都满足跳过了格式化器的目标可能显示出空行残余——这正是规范留给人眼确认的部分。3. 忠实重放原语全契约规范的 §3 逐一规定了每个原语的契约。每个原语只做搬迁忠实的编辑——AST 定位、按原始源码文本拼接、从不重新生成never regenerated因此格式化后字节匹配即可证明提交恰好就是那次搬迁。以下是完整契约并标注了仓库实现中的落点均在 mechanical_refactor_reproduction_utils.pyRepro类方法。move_symbol(name, *, src, dst, into_class, from_class, dedent, drop_self_annotation, before, after, leave_delegate, delegate_name)实现见第 952 行剪切一个def或整个class含其方法及其装饰器去掉其自身携带的staticmethod/classmethod统一缩进平移负dedent即缩进进入类体粘贴位置四种类末尾、模块级、命名兄弟before之上、或顶层符号after之下——after可以是兄弟 def/class 或模块级赋值目标用于把 def 落到紧随其后的if TYPE_CHECKING:守卫之前该守卫自身没有可命名锚点before与after互斥同名 def 必须给from_class消歧名字含糊或锚点缺失即抛错leave_delegate会在源文件中作者化一个转发桩原签名头 一行return self.attr.name(...)async 方法加await——需像任何头一样接受审计。实现细节印证_find_unique_def第 150 行用from_class限定查找范围并在多处命中时抛错_def_span第 205 行把装饰器行也纳入剪切范围_def_header_end第 182 行用 tokenize 而非括号深度判断签名冒号位置避免字符串默认值中的括号干扰leave_delegate分支还会校验对staticmethod/classmethod方法做委托时必须带self注解否则无从转发并只在注解名等于目标类时才丢弃self注解如 mixin 的self: ModelRunner属于幸存的头保留。extract_to_new_module(src, dst, *, symbols, future_import)实现见第 1133 行剪切源文件连续尾部被移动的 def/class 加其前导脚手架import、TYPE_CHECKING守卫、仅名字目标的赋值任何可执行尾语句会终止剪切is_scaffolding之外的语句即停当移动需要时前置from __future__ import annotationsfuture_importTrue默认开启。extract_symbols_to_new_module(src, dst, *, symbols, header, order, drop_assigns)实现见第 1204 行从分散位置剪切指定 def/class在经审计的header§2.1下组装新模块drop_assigns从源中删除被搬迁的模块级常量链式赋值A B 1保留幸存绑定实现按目标名过滤后以原值文本重建语句见第 1277-1290 行头审计同样接受在源中幸存的模块常量的 unparse 等价副本如_is_hip is_hip()双模块保留因为同一语句仍在源中可证order必须是symbols的一个排列第 1233 行断言按目标中的顺序拼接。extract_function(src, dst, *, name, signature, body, body_indent, call, return_text, before, into_class)实现见第 1337 行逐字剪切内联body必须唯一命中且起始于行边界第 1388-1392 行断言在作者化signature下重新缩进——多行字符串内部保持精确字节_multiline_string_interior_lines第 343 行把字符串内部行排除在重缩进之外因为改动它们会改变字面量值原块替换为作者化call只有当函数体原样移动时才忠实de-self、控制流重构、簿记合并必须先作为独立语义提交见 guide-split.md。move_assign(name, *, src, dst, before)实现见第 878 行从src逐字剪切绑定name的模块级赋值粘贴到dst模块级放在命名兄弟before之上否则放在尾部 import 之后用途让模块常量与读取它的代码一起搬迁。lower_call_sites(name, owner, *, paths)实现见第 425 行Owner.m(receiver, rest)→receiver.m(rest)按原始参数字节拼接字面量拼写、注释、魔法尾逗号全部幸存嵌套匹配调用全部重写——实现采用每轮重写一个匹配调用并重新解析的循环_rewrite_matching_calls第 255 行保证嵌套匹配不会被覆盖。requalify_call_sites(name, owner, *, paths)实现见第 451 行Owner.m(args)→m(args)只改动限定符 span。route_call_sites_through_field(name, *, field, paths, owner)实现见第 481 行recv.m(args)→recv.field.m(args)当m移动到经self.field可达的协作者对象上时这是move_symbol(leave_delegate...)的调用侧对偶已路由经field的调用被跳过以保证收敛owner把改写限定到某个精确接收者。remove_import(rel, import_text, *, in_function)实现见第 519 行函数级或模块级整语句匹配且带 token 边界import os不会误中import os.path分号连接的同一行也只删除匹配的 import实现用simple_stmt_lines区分独行/共享行见第 547-603 行。remove_imported_name(rel, *, module, name, asname)实现见第 609 行从from m import a, b或纯import x中删一个名字直接实现丢失的导入本仓库 ruff 无 F811展开的带括号 import 中独占一行的名字当幸存 2 个名字或 import 带注释时原地删除该行——括号、魔法尾逗号、注释全保留格式化器保持多行而扁平重建会丢魔法逗号并塌缩目标本是多行的 import唯一幸存名字无注释时默认塌缩为单行格式化器不会让一个名字保持展开若目标保留了唯一幸存者的展开形式其魔法逗号保留传keep_explodedTrue——这是提交作者的抉择无法从源码推断与其他文本共享一行的名字总是重建删除唯一名字则移除整个语句。add_imported_name(rel, *, module, name, asname)实现见第 695 行remove_imported_name的对偶向已有from module import a, b加一个名字。当目标是扩展现有行而非新增语句时使用它import 排序器不会让新语句跨过一个夹在中间的非 import 语句完成合并如两个 import 块之间的模块级赋值带注释的 import 被拒绝重建会丢注释名字已存在则响亮失败。add_import(rel, import_stmt, *, after)实现见第 737 行由 import 排序器定位无既有 import 时落在模块 docstring 之下aftersubstr把新语句插到文本含该子串的顶层 import 语句正下方——用于语句把 import 拆成独立 isort 区块如两个块之间夹着_is_hip is_hip()而默认位置会落错块的情形子串未匹配任何顶层 import 即抛错。add_typechecking_import(rel, import_stmt)实现见第 788 行追加到目标文件的if TYPE_CHECKING:块内不存在时在尾部模块 import 之后创建该块排序器排序块内语句单独的pass占位符块的唯一语句会被删除——填充空块使其占位符冗余。repath_import(rel, *, old_module, new_module, name)实现见第 842 行原地重写函数级from old import … name …含相对导入的路径模块级改路径由 add/remove 排序器完成实现以top_level {id(node) for node in tree.body}排除模块级 import。delete_file(path)实现见第 1449 行删除被搬迁掏空的源模块拒绝仍含 docstring、import、TYPE_CHECKING块、裸模块logger之外任何内容的文件——删除活代码不是搬迁实现用ast.unparse(stmt)列表校验剩余语句第 1466-1487 行。跨切保证cross-cutting guaranteesCRLF 源文件逐字节往返合成行跟随文件换行风格_newline_style第 79 行列运算按 UTF-8 字节精确_byte_slice第 224 行非 ASCII 文本不会使重写偏移——这是 AST 的col_offset按字节计数的必然要求。4. 仲裁器重放 字节级 diff规范 §4 定义了Repro.run()以及更低层的verify_mechanical_refactor的四步流程在一次性 worktree中检出 base 提交按记录顺序重放原语self.ops依次执行Repro.run()第 1493 行起对变更文件运行仓库真实的 pre-commit hookspre-commit run --files ...仅对--diff-filterACMR检出的变更文件与目标提交做字节级 diff——空 diff 即证明非空 diff 作为**残余residual**返回恰好就是该搬迁未解释的部分。run()返回残余 diff 字符串空串 干净重放无论成败都会在finally中清理 worktree 与分支第 1525-1529 行。verify_mechanical_refactor则直接以进程退出码 1 表示 FAIL 并打印 diff第 123-127 行。4.1 为什么要跑真实格式化器规范强调了运行真实格式化器的两点性质无 diff 形状启发式可骗跨 (行拆开的调用、重排后把右括号留作上下文的重流都能被真实格式化器精确重现显式取舍pre-commit hooks 自动修复的内容在两侧都被吸收如 ruff F401 删除一个不再使用的 import。hook 引入的变化搭字节匹配的便车因此 hook 集合本身属于受信任基座的一部分——这是设计上承认并接受的边界。5. 原语之上的三件套生成器、链验证器与测试规范虽是真相源其效力由仓库中的配套模块兑现均在 .claude/skills/mechanical-refactor-verify/scripts/ 下mechanical_refactor_proof_generator.py1554 行从提交 diff 与 base 态 AST推断重放配方为每个mechanical_provable提交产出/运行独立、可审计的脚本给出PASS/RESIDUAL/UNSUPPORTED三档判定mechanical_refactor_reproduction_cli.py537 行链验证器分类base..branch中每个提交从证明文件夹运行每个可证明提交的证明并输出全链报告其契约在 spec-reproduction-cli.mdscripts/tests/pytest 套件按模块分目录——reproduction_utils/覆盖证明引擎含test_move_symbol.py、test_extract_function.py、test_remove_imported_name.py、test_delete_file.py等十余个文件、proof_generator/覆盖生成器、reproduction_cli/覆盖链验证器。三个模块共同兑现规范的一条核心设计proof engine 自包含仅依赖 git 与标准库模块 docstring 明言使得证明文件夹可以脱离技能环境独立运行与审计。6. 从规范到工作流一次完整的可验证重构把规范落到日常重构流程正确的姿势是详见 guide-split.md、guide-construct-proof.md、guide-verify-proof.md拆分把一次重构拆成可选 prepare语义整形标注non_mechanical_provable 纯搬迁 move标注mechanical_provable 可选 postpare提交主题遵循group-id(commit-id,kind): message格式构造证明用生成器对范围产出证明文件夹——python3 .claude/skills/mechanical-refactor-verify/scripts/mechanical_refactor_proof_generator.py base..tip --match (?!_)mechanical_provable --out repro_out产物为repro_scripts/sha.py、output.log/output.html与 utils 副本生成器报UNSUPPORTED时按 guide-construct-proof.md 手写Repro验证审阅方亲自运行链验证器python3 .claude/skills/mechanical-refactor-verify/scripts/mechanical_refactor_reproduction_cli.py --base base --branch branch --proof folder对HUMAN_REVIEW行逐一人工审计——正如 guide-verify-proof.md 开头所强调不要信任 PR亲自验证抽样抽查不算验证。结语spec-reproduction-utils.md的价值在于把这次重构对不对从不可复现的主观判断转化为可重放、可字节对比、可审计的客观过程白名单圈定可证明的搬迁面黑名单划出必须交给人眼的语义改动原语契约保证每一步都是 AST 定位的忠实拼接仲裁器用真实格式化器 空 diff 给出最终裁决。对 SGLang 这样拥有庞大 Python 代码库、高频进行模块拆分与重构的项目而言这套机制让机械改动真正成为工程上可追踪、可复核的资产。【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 SGLang 机械重构验证规范解析：用忠实重放原语与字节级 diff 证明“纯搬迁“提交
SGLang 机械重构验证规范解析用忠实重放原语与字节级 diff 证明纯搬迁提交【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang导读本文是 SGLang 仓库内.claude/skills/mechanical-refactor-verify技能体系中规范级文档spec-reproduction-utils.md的深度解读它以源码真相源source of truth的姿态定义了**纯搬迁clean move**属性、14 个忠实重放原语faithful relocation primitive的契约以及重放 字节级 diff仲裁器arbiter的语义。读完本文你将掌握如何把一次文件拆分、函数移动、模块抽取、改名这类机械重构从靠肉眼 review转变为任何人、任何时候都能一键重跑并得到 PASS/RESIDUAL 结论的机器可验证过程并能在 SGLang 仓库对应的 Python 实现中找到每个概念的落点。1. 规范文档的定位谁是真相源spec-reproduction-utils.md是整套mechanical-refactor-verify技能中单提交证明层面的规范源头与之配套的文件分工如下均位于仓库 .claude/skills/mechanical-refactor-verify/ 目录下spec-reproduction-utils.md本文解读对象定义纯搬迁属性§2、每个原语的契约§3与字节级 diff 仲裁器语义§4spec-reproduction-cli.md链条验证规范定义提交分类词规则、证明义务、报告与退出码guide-split.md如何把一次改动拆成 prepare move postpare 三阶段guide-construct-proof.md如何生成/手写证明guide-verify-proof.md如何审阅证明guide-modify-skill.md如何修改本技能自身。规范明确了一条铁律模块、其测试、各指南均以此文件为准一旦出现分歧此文件胜出this file wins。也就是说仓库中的实现 scripts/mechanical_refactor_reproduction_utils.py 是规范的执行者而本文件是它唯一的事实依据。2. 核心属性什么是纯搬迁clean move规范的基石是一条可证明的属性定义一个提交是clean move当且仅当它所做的每一个改动都是按相同顺序被搬迁relocated的代码——允许整块一次统一缩进平移uniform indentation shift——外加一小类固定的搬迁副产物move artifacts除此之外别无其他。等价表述该提交只能由 §3 的原语组合重放出来。规范还点出了机制上的关键设计——白名单§2.1恰好是原语能做的事黑名单§2.2是原语拒绝做的事任何白名单之外的动作都会以残余 diffresidual diff的形式浮出水面而不是被悄悄吞掉。从实现看这个属性由 mechanical_refactor_reproduction_utils.py 顶部的模块 docstring 复述每个原语只做搬迁忠实的编辑AST 定位、按原始源码文本拼接、永不重新生成代码所以格式化后的字节匹配就能证明提交恰好等于那次搬迁。verify_mechanical_refactor()同文件第 83 行起是该属性的最小落地在一次性 worktree 检出 base 提交 → 运行 transform → 对变更文件跑 pre-commit → 与目标提交做字节级 diff。2.1 白名单允许的全部搬迁规范列出的可证明搬迁包括按序搬迁的行整块允许一次统一的前导缩进平移如从模块级移入类体整体缩进 4 空格从分散位置收集 def/class 到新模块每个定义逐字剪切、在经过审计的作者化头audited authored header下组装。头审计只接受import、docstring、TYPE_CHECKING导入块、logging.getLogger(__name__)记录器、从源中实际删除的赋值drop_assigns的 unparse 等价副本、或在源中原样幸存的模块常量的 unparse 等价副本——例如_is_hip is_hip()这类可重推导样板因为同一语句仍留在源文件中故可证非虚构。每个被删除的赋值必须重新出现在头中否则直接抛错而非认证被抽取函数的函数体内联块逐字搬入新 defdef签名、可选的return、替换用的call是作者化的。仅当函数体原样移动时才忠实de-self、控制流重构、簿记合并都属于语义改动须先进独立提交import 语句新增、删除、改路径单行或带括号均可直接按目标实现全新模块的语句逐字搬入保留换行包裹形式新模块迁移可加from __future__ import annotations单侧staticmethod/classmethod方法 ↔ 自由函数从被移动定义上删掉self类型注解如把staticmethod def foo(self: Target)搬入Target变成def foo(self)调用点重新限定requalificationOwner.foo(x)→foo(x)符号与参数字节不变只去掉限定符而Old.foo(x)→New.foo(x)的宿主替换不是原语会作为残余浮现调用点降级loweringOwner.method(receiver, rest)→receiver.method(rest)接收者从参数列表移到调用者位置删除被搬空的源文件除 docstring、import、TYPE_CHECKING块外别无他物delete_file拒绝删除任何其他内容空行变化忽略见 §2.3。2.2 黑名单以下情况不是clean move规范明确拒绝的包括被移动块内行序重排不搬迁任何定义的语句级重排它改变求值顺序是需要人工确认的整形而非可认证的搬迁非统一的缩进变化可能改变 Python 语义行尾空白、内部空白变化或行合并/拆分被重新限定调用中参数的改动对本提交未移动符号的调用重写除删self注解外的签名变化被移动符号的改名哪怕只是_foo→foo的可见性翻转向已有模块作者化脚手架或常量logger、模块常量、TYPE_CHECKING守卫、重推导的_flag compute_flag()——注意新模块的头允许从目标作者化已有模块的函数体不是写新代码的地方从源搬迁的常量不是作者化由move_assign认证被抽取函数中函数体改动de-self、控制流重构、合并簿记。整形工作改名、新脚手架、语句重排、改动抽取函数体应归属 guide-split.md 的 prepare/postpare 阶段证明系统会把它报告为残余绝不认证。2.3 空行为何被忽略空行永不改变 Python 行为PEP 8 分隔空行在搬迁中合法塌缩。实现上格式化器会同时归一化重放侧与目标侧所以纯空行差异到不了字节 diff 层。规范同时声明了一个前提假设目标提交本身是 pre-commit 干净的凡是过了本仓库 hooks 的提交都满足跳过了格式化器的目标可能显示出空行残余——这正是规范留给人眼确认的部分。3. 忠实重放原语全契约规范的 §3 逐一规定了每个原语的契约。每个原语只做搬迁忠实的编辑——AST 定位、按原始源码文本拼接、从不重新生成never regenerated因此格式化后字节匹配即可证明提交恰好就是那次搬迁。以下是完整契约并标注了仓库实现中的落点均在 mechanical_refactor_reproduction_utils.pyRepro类方法。move_symbol(name, *, src, dst, into_class, from_class, dedent, drop_self_annotation, before, after, leave_delegate, delegate_name)实现见第 952 行剪切一个def或整个class含其方法及其装饰器去掉其自身携带的staticmethod/classmethod统一缩进平移负dedent即缩进进入类体粘贴位置四种类末尾、模块级、命名兄弟before之上、或顶层符号after之下——after可以是兄弟 def/class 或模块级赋值目标用于把 def 落到紧随其后的if TYPE_CHECKING:守卫之前该守卫自身没有可命名锚点before与after互斥同名 def 必须给from_class消歧名字含糊或锚点缺失即抛错leave_delegate会在源文件中作者化一个转发桩原签名头 一行return self.attr.name(...)async 方法加await——需像任何头一样接受审计。实现细节印证_find_unique_def第 150 行用from_class限定查找范围并在多处命中时抛错_def_span第 205 行把装饰器行也纳入剪切范围_def_header_end第 182 行用 tokenize 而非括号深度判断签名冒号位置避免字符串默认值中的括号干扰leave_delegate分支还会校验对staticmethod/classmethod方法做委托时必须带self注解否则无从转发并只在注解名等于目标类时才丢弃self注解如 mixin 的self: ModelRunner属于幸存的头保留。extract_to_new_module(src, dst, *, symbols, future_import)实现见第 1133 行剪切源文件连续尾部被移动的 def/class 加其前导脚手架import、TYPE_CHECKING守卫、仅名字目标的赋值任何可执行尾语句会终止剪切is_scaffolding之外的语句即停当移动需要时前置from __future__ import annotationsfuture_importTrue默认开启。extract_symbols_to_new_module(src, dst, *, symbols, header, order, drop_assigns)实现见第 1204 行从分散位置剪切指定 def/class在经审计的header§2.1下组装新模块drop_assigns从源中删除被搬迁的模块级常量链式赋值A B 1保留幸存绑定实现按目标名过滤后以原值文本重建语句见第 1277-1290 行头审计同样接受在源中幸存的模块常量的 unparse 等价副本如_is_hip is_hip()双模块保留因为同一语句仍在源中可证order必须是symbols的一个排列第 1233 行断言按目标中的顺序拼接。extract_function(src, dst, *, name, signature, body, body_indent, call, return_text, before, into_class)实现见第 1337 行逐字剪切内联body必须唯一命中且起始于行边界第 1388-1392 行断言在作者化signature下重新缩进——多行字符串内部保持精确字节_multiline_string_interior_lines第 343 行把字符串内部行排除在重缩进之外因为改动它们会改变字面量值原块替换为作者化call只有当函数体原样移动时才忠实de-self、控制流重构、簿记合并必须先作为独立语义提交见 guide-split.md。move_assign(name, *, src, dst, before)实现见第 878 行从src逐字剪切绑定name的模块级赋值粘贴到dst模块级放在命名兄弟before之上否则放在尾部 import 之后用途让模块常量与读取它的代码一起搬迁。lower_call_sites(name, owner, *, paths)实现见第 425 行Owner.m(receiver, rest)→receiver.m(rest)按原始参数字节拼接字面量拼写、注释、魔法尾逗号全部幸存嵌套匹配调用全部重写——实现采用每轮重写一个匹配调用并重新解析的循环_rewrite_matching_calls第 255 行保证嵌套匹配不会被覆盖。requalify_call_sites(name, owner, *, paths)实现见第 451 行Owner.m(args)→m(args)只改动限定符 span。route_call_sites_through_field(name, *, field, paths, owner)实现见第 481 行recv.m(args)→recv.field.m(args)当m移动到经self.field可达的协作者对象上时这是move_symbol(leave_delegate...)的调用侧对偶已路由经field的调用被跳过以保证收敛owner把改写限定到某个精确接收者。remove_import(rel, import_text, *, in_function)实现见第 519 行函数级或模块级整语句匹配且带 token 边界import os不会误中import os.path分号连接的同一行也只删除匹配的 import实现用simple_stmt_lines区分独行/共享行见第 547-603 行。remove_imported_name(rel, *, module, name, asname)实现见第 609 行从from m import a, b或纯import x中删一个名字直接实现丢失的导入本仓库 ruff 无 F811展开的带括号 import 中独占一行的名字当幸存 2 个名字或 import 带注释时原地删除该行——括号、魔法尾逗号、注释全保留格式化器保持多行而扁平重建会丢魔法逗号并塌缩目标本是多行的 import唯一幸存名字无注释时默认塌缩为单行格式化器不会让一个名字保持展开若目标保留了唯一幸存者的展开形式其魔法逗号保留传keep_explodedTrue——这是提交作者的抉择无法从源码推断与其他文本共享一行的名字总是重建删除唯一名字则移除整个语句。add_imported_name(rel, *, module, name, asname)实现见第 695 行remove_imported_name的对偶向已有from module import a, b加一个名字。当目标是扩展现有行而非新增语句时使用它import 排序器不会让新语句跨过一个夹在中间的非 import 语句完成合并如两个 import 块之间的模块级赋值带注释的 import 被拒绝重建会丢注释名字已存在则响亮失败。add_import(rel, import_stmt, *, after)实现见第 737 行由 import 排序器定位无既有 import 时落在模块 docstring 之下aftersubstr把新语句插到文本含该子串的顶层 import 语句正下方——用于语句把 import 拆成独立 isort 区块如两个块之间夹着_is_hip is_hip()而默认位置会落错块的情形子串未匹配任何顶层 import 即抛错。add_typechecking_import(rel, import_stmt)实现见第 788 行追加到目标文件的if TYPE_CHECKING:块内不存在时在尾部模块 import 之后创建该块排序器排序块内语句单独的pass占位符块的唯一语句会被删除——填充空块使其占位符冗余。repath_import(rel, *, old_module, new_module, name)实现见第 842 行原地重写函数级from old import … name …含相对导入的路径模块级改路径由 add/remove 排序器完成实现以top_level {id(node) for node in tree.body}排除模块级 import。delete_file(path)实现见第 1449 行删除被搬迁掏空的源模块拒绝仍含 docstring、import、TYPE_CHECKING块、裸模块logger之外任何内容的文件——删除活代码不是搬迁实现用ast.unparse(stmt)列表校验剩余语句第 1466-1487 行。跨切保证cross-cutting guaranteesCRLF 源文件逐字节往返合成行跟随文件换行风格_newline_style第 79 行列运算按 UTF-8 字节精确_byte_slice第 224 行非 ASCII 文本不会使重写偏移——这是 AST 的col_offset按字节计数的必然要求。4. 仲裁器重放 字节级 diff规范 §4 定义了Repro.run()以及更低层的verify_mechanical_refactor的四步流程在一次性 worktree中检出 base 提交按记录顺序重放原语self.ops依次执行Repro.run()第 1493 行起对变更文件运行仓库真实的 pre-commit hookspre-commit run --files ...仅对--diff-filterACMR检出的变更文件与目标提交做字节级 diff——空 diff 即证明非空 diff 作为**残余residual**返回恰好就是该搬迁未解释的部分。run()返回残余 diff 字符串空串 干净重放无论成败都会在finally中清理 worktree 与分支第 1525-1529 行。verify_mechanical_refactor则直接以进程退出码 1 表示 FAIL 并打印 diff第 123-127 行。4.1 为什么要跑真实格式化器规范强调了运行真实格式化器的两点性质无 diff 形状启发式可骗跨 (行拆开的调用、重排后把右括号留作上下文的重流都能被真实格式化器精确重现显式取舍pre-commit hooks 自动修复的内容在两侧都被吸收如 ruff F401 删除一个不再使用的 import。hook 引入的变化搭字节匹配的便车因此 hook 集合本身属于受信任基座的一部分——这是设计上承认并接受的边界。5. 原语之上的三件套生成器、链验证器与测试规范虽是真相源其效力由仓库中的配套模块兑现均在 .claude/skills/mechanical-refactor-verify/scripts/ 下mechanical_refactor_proof_generator.py1554 行从提交 diff 与 base 态 AST推断重放配方为每个mechanical_provable提交产出/运行独立、可审计的脚本给出PASS/RESIDUAL/UNSUPPORTED三档判定mechanical_refactor_reproduction_cli.py537 行链验证器分类base..branch中每个提交从证明文件夹运行每个可证明提交的证明并输出全链报告其契约在 spec-reproduction-cli.mdscripts/tests/pytest 套件按模块分目录——reproduction_utils/覆盖证明引擎含test_move_symbol.py、test_extract_function.py、test_remove_imported_name.py、test_delete_file.py等十余个文件、proof_generator/覆盖生成器、reproduction_cli/覆盖链验证器。三个模块共同兑现规范的一条核心设计proof engine 自包含仅依赖 git 与标准库模块 docstring 明言使得证明文件夹可以脱离技能环境独立运行与审计。6. 从规范到工作流一次完整的可验证重构把规范落到日常重构流程正确的姿势是详见 guide-split.md、guide-construct-proof.md、guide-verify-proof.md拆分把一次重构拆成可选 prepare语义整形标注non_mechanical_provable 纯搬迁 move标注mechanical_provable 可选 postpare提交主题遵循group-id(commit-id,kind): message格式构造证明用生成器对范围产出证明文件夹——python3 .claude/skills/mechanical-refactor-verify/scripts/mechanical_refactor_proof_generator.py base..tip --match (?!_)mechanical_provable --out repro_out产物为repro_scripts/sha.py、output.log/output.html与 utils 副本生成器报UNSUPPORTED时按 guide-construct-proof.md 手写Repro验证审阅方亲自运行链验证器python3 .claude/skills/mechanical-refactor-verify/scripts/mechanical_refactor_reproduction_cli.py --base base --branch branch --proof folder对HUMAN_REVIEW行逐一人工审计——正如 guide-verify-proof.md 开头所强调不要信任 PR亲自验证抽样抽查不算验证。结语spec-reproduction-utils.md的价值在于把这次重构对不对从不可复现的主观判断转化为可重放、可字节对比、可审计的客观过程白名单圈定可证明的搬迁面黑名单划出必须交给人眼的语义改动原语契约保证每一步都是 AST 定位的忠实拼接仲裁器用真实格式化器 空 diff 给出最终裁决。对 SGLang 这样拥有庞大 Python 代码库、高频进行模块拆分与重构的项目而言这套机制让机械改动真正成为工程上可追踪、可复核的资产。【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考