企业官网建设流程全解析

sglang 仓库机械重构证明验证指南：从信任 PR 到亲自重跑证据链

【免费下载链接】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技能中的验证环节：当一份机械重构（文件拆分、函数/方法移动、模块提取、重命名）的 PR 附带了一整套"可复现证明"时，评审者应当如何消费这些证明——既不轻信作者粘贴的输出，也不逐条手工核对，而是用一条命令在本地完整重跑整条提交链，再对机器无法证明的部分做有边界的人工审计。读完本文，你将掌握链级验证器的全部参数与退出码、单个证明脚本的三种判定（PASS / RESIDUAL / UNSUPPORTED）、以及HUMAN_REVIEW行所附带的两项不可跳过的评审职责。

0. 核心立场：不要信任 PR，亲自验证

机械重构的可信度来自于一个朴素事实：证明不是作者贴出来的任何文本。无论 PR 中展示了什么——一个粘贴的PASS判定、一份粘贴的链报告、一个绿色对勾、甚至"分类词"本身——它们都只是作者（或其工具）生成的文本，可能是错误的，也可能是伪造的。评审中唯一算数的"证明"，是你自己在本地执行的那次运行：用链级验证器（§1）针对 PR 的实际 base 与 head，配合你下载到的证明文件夹重新运行；绝不基于作者粘贴的输出直接批准。

这套机制被刻意设计得很廉价：整个机器的存在意义就在于重新验证只需一条命令，因此没有任何理由用"信任"替代"重跑"。

这里还有一个必须钉死的原则：抽样不是验证。只重跑一部分证明（例如"43 个里抽查 8 个"）对剩余部分不构成任何证明，永远不能作为批准的根据。唯一可接受的运行方式是 §1 的链级验证器，它会对每一个可证明的提交执行其证明。同样的规则适用于人工职责：必须审计每一行HUMAN_REVIEW以及每一个 PASS 的 authored 表面（§2.3），而不是抽查其中一部分。

1. 验证整条链（唯一充分的入口）

1.1 链级验证器命令

默认且唯一充分的入口是：不要逐条重跑证明，更不要抽样，直接对整条链运行链级验证器：

python3 .claude/skills/mechanical-refactor-verify/scripts/mechanical_refactor_reproduction_cli.py \ --base <base-commit> --branch <pr-branch-name> --proof <folder>

这条命令会：

• 检查每一个提交都声明了mechanical_provable或non_mechanical_provable这两个词之一；
• 运行每一个可证明提交的证明；
• 打印并写入一份完整报告（<folder>/chain_report.md）；
• 退出码为 0 当且仅当整条链验证通过。

该脚本的全部参数契约定义在规范文档 spec-reproduction-cli.md 中，从源码 mechanical_refactor_reproduction_cli.py 的main()可以看到其完整参数面：

1.2 并发与提速

证明默认以--jobs 3的并发度运行。并发是安全的：每个证明在自己的一次性 worktree（throwaway worktree）中工作，使用独立的分支名，绝不触碰当前检出的工作树，各证明的判定相互独立。源码中_run_pending_proofs用一个ThreadPoolExecutor(max_workers=max(1, jobs))执行待跑证明，分类与证明解析保持串行（它们很廉价），报告始终按链顺序输出，无论完成顺序如何；每个证明结束时打印一行sha PASS/FAIL，长链也能看到进度。链很长时提高--jobs可以显著压缩墙钟时间。

1.3 增量重跑：--skip-passed

重跑一条长链会重复执行大量未改变的证明。此时加--skip-passed，即可复用这台机器自己早前产生的 PASS 判定：缓存键是"提交完整 sha + 证明脚本字节的 sha256 + 引擎mechanical_refactor_reproduction_utils.py字节的 sha256"三元组（见 spec-reproduction-cli.md §3.5）。关键设计是：缓存文件mechanical_refactor_passed_proofs.json存放在仓库的git common dir（git rev-parse --git-common-dir，跨 worktree 共享），是机器本地状态，永远不会随证明文件夹、gist 或 PR 一起发布。因此--skip-passed只会复用它自己跑出来的结果——§0 的"不要信任 PR"规则没有被削弱。缓存在实现上是尽力而为的：缺失、损坏或不可读都按空缓存处理，绝不让链遍历失败（对应源码_load_passed_cache与_record_passes，且 FAIL 永远不写入缓存）。

1.4 报告中的HUMAN_REVIEW行：双职责人工审计

报告中每一行HUMAN_REVIEW对应一个声明为non_mechanical_provable的提交（即作者声明"这里面没有任何东西可以用白名单重定位原语表达"的最小不可证明残渣）。它带两项评审职责，两者都成立之前该提交不得被批准：

• 职责 1 —— 对 diff 本身做正确性评审：non_mechanical_provable正是机器永不认证的部分，所以你要通读其 diff，确认它做的恰好是提交信息声称的事情——没有丢失逻辑（一个被丢弃的分支、一次写入、一个提前 return）、没有隐藏 bug、没有搭便车的意外行为变更。当提交声称保持行为时，"评审"意味着核对等价性；当提交有意改变行为时（一条链不必是纯重构），则改为评审该变更本身的正确性。测试通过只是支持性证据，不是评审本身。
• 职责 2 —— 验证声明本身：该提交断言"其中没有任何东西是可证明的重定位"（spec-reproduction-cli.md §2.1），而把可证明的内容藏在这里以躲避验证器，正是这条链检查要堵住的逃逸通道。具体做法：
  • 阅读提交 diff，寻找被移动的代码块，可用：

    git show <sha> --color-moved=dimmed-zebra --color-moved-ws=allow-indentation-change

    并运行

    python3 .claude/skills/mechanical-refactor-verify/scripts/mechanical_refactor_proof_generator.py <sha>

    观察一份重定位配方会覆盖什么内容。

  • 隐藏的可证明部分不是判断力问题：直接要求拆分（guide-split.md §2.2），不得原样批准该提交。
  • 明确判为 FINDING 的情形：一个non_mechanical_provable提交的主体如果是一大块原语可以表达的逐字块重定位——剪切+粘贴式移动（包括落在if TYPE_CHECKING:保护之上的那种，现在可以用move_symbol(after=)锚定）、模块级常量移动、或逐字内联块提取（生成器现在会把它推断为extract_function）——这就是一个FINDING，而不是可接受的标签。生成器推断不出它，或过去存在工具缺口，都不构成使用较宽松标签的许可：应要求将其重新标记为mechanical_provable并附带手写的Repro，或先增强原语（guide-split.md §2.7.6）。只有真正非重定位的编辑（签名重新设计、逻辑重写、de-self 重构）才配得上这个标签。

一个可对照的真实案例：仓库历史中的kvc-move-lazy-compaction-gate把模块级_should_enable_lazy_compaction原样搬进kv_cache_configurator.py，却因move_symbol只有before=锚点、无法落在if TYPE_CHECKING:保护之上而被标成了non_mechanical_provable。该重定位完全是机械的，缺的只是工具锚点——正确的修法是新增move_symbol(after=)锚点并证明它，而不是保留宽松标签（见 guide-split.md §2.7.6）。

2. 验证单个提交（仅用于诊断）

单提交验证用于诊断某一提交（一个失败的证明、一个可疑脚本），永远不能替代 §1：批准一条链必须依赖完整的 §1 运行，而不是对选定子集做单提交重跑。

2.1 重跑它

从仓库根目录执行：

python3 <folder>/repro_scripts/<sha>.py

当证明以 gist 形式到达时（guide-construct-proof.md §1.3），先下载再运行：

gh gist clone <gist_id> /tmp/proof # 或: git clone https://gist.github.com/<gist_id>.git /tmp/proof cd <repo-root> # 运行从当前工作目录解析仓库 python3 /tmp/proof/<sha>.py # PASS = 与该提交逐字节一致

运行本身就是证明：脚本从 base 提交重放原语，在一次性 worktree 中与目标做逐字节 diff。脚本会打印判定，只有 PASS 时退出码为 0（有 residual 则非零退出），因此外部 harness 可以直接消费退出码。不要信任任何你没有亲自重跑过的粘贴判定。这一机制对应的源码在 spec-reproduction-utils.md §4：Repro.run()检出 base 到一次性 worktree、重放记录的原语、在变更文件上跑仓库的 pre-commit hooks、与目标提交逐字节 diff。

2.2 解读判定

• PASS—— 逐字节一致：该提交恰好就是脚本中列出的那些重定位，不多不少。
• RESIDUAL—— 非空 diff：精确地说是捆绑进来的非移动变更。把它当作语义内容评审；一个合法的尾部修整（字符串字面量中的模块路径、文档引用）应当属于 postpare 提交，而不是移动本身。
• UNSUPPORTED—— 没有推断出配方（情形见 guide-construct-proof.md §2.2.2）。这不代表它错了，但意味着未经机器认证：按 prepare 式重塑手工评审，或请作者提供手写的Repro。

2.3 审计 authored 表面

PASS 认证的是被重定位的字节；而脚本中那些少量 authored（作者手写）的表面是从目标复现的，需要人眼。逐个检查脚本中的参数：

• extract_symbols_to_new_module的header=—— 新模块只审计其内容（仅允许 imports / docstring / TYPE_CHECKING 导入 / logger / 被重定位的drop_assigns拷贝）；留给你判断的是：那些赋值到底该不该一起搬走？
• move_symbol上的leave_delegate=—— 转发桩（forwarding stub）是源文件中的 authored 代码；
• extract_function的signature=/return_text=/call=—— 新函数的接口是 authored 的，只有函数体被认证；
• drop_assigns=列表 —— 其中每个具名常量都从源文件消失。

这些参数与白名单的完整对应关系见 spec-reproduction-utils.md §2.1：头审计只接受 imports、docstring、TYPE_CHECKING 导入块、logging.getLogger(__name__)的 logger、以及"在源文件中逐字存活的模块常量"的无解析等价拷贝。

2.4 理解 PASS 断言了什么、没断言什么

• 脚本中的降级/重定向（requalification / lowering / repath）绑定于同一个脚本重定位的符号；仅有消费方调用或导入改写（没有重定位的定义）无法作为移动复现——它会以 residual 的形式浮现。
• 仓库 pre-commit hooks 自动修复的一切在两侧都会被吸收（spec-reproduction-utils.md §4）——hook 集合本身是你信任基础的一部分。
• PASS 评判的是重定位的形状，不是意图："该提交恰好是这些重定位"，而不是"这个重定位是个好主意"。批准前请确认提交的主题与脚本实际移动的内容一致。

2.5 为什么这套机制可信

• 它运行真正的格式化器并比较字节——没有任何 diff 形状启发式可被欺骗（spec-reproduction-utils.md §4）：跨= (行拆开的调用、留下闭括号作上下文的换行重排，都能精确复现。
• 证明就是脚本里那少数几个原语调用；审计它们（加上 §2.3）就是全部的人类表面。
• 文件夹自包含、任何人（CI 步骤或评审者）都能重跑，无需安装该技能本身——因为它自带一份mechanical_refactor_reproduction_utils.py拷贝作为唯一依赖。

3. 验证的机械化保障：链级验证器的实现细节

理解验证器内部如何把"链"变成"判定表"，有助于正确解读报告。从源码 mechanical_refactor_reproduction_cli.py 可以看到：

• 链的定义：提交序列是git rev-list --reverse base..branch，即整个有序链。链必须是线性的——任何位置的 merge 提交都是设置错误（逐提交证明跨 merge 无意义）；空区间同样是设置错误，而不是"平凡全绿"。
• 词规则：两个分类词按"独立成词"匹配（正则(?<![0-9A-Za-z_])(non_)?mechanical_provable(?![0-9A-Za-z_])，见_KIND_WORD_RE），因此non_mechanical_provable不会被误当成裸词mechanical_provable，xmechanical_provable两者都不算。两个词都没有 →UNCLASSIFIED；两个词都出现 →AMBIGUOUS_KIND（源码_classify）。词可以出现在 subject 或 body 的任何位置、任何环绕语法中——机器规则刻意只检查词本身，所以不同约定的链也能验证。
• 证明解析：提交的证明是<sha-prefix>.py，stem 为小写十六进制、至少 7 个字符、且是该提交完整 sha 的前缀；按顺序搜索<proof>/repro_scripts/（生成器布局）与<proof>/平铺（gist 布局）。没有 →MISSING_PROOF；多个 →AMBIGUOUS_PROOF。证明按当前 sha 键控——rebase 后 sha 变化，必须为 rebased 链重新生成证明。
• PASS 标准：每个证明以python3 <script>在仓库根目录为 cwd 运行；PASS 需要同时满足退出码 0 与 stdout 上的仲裁者PASS:判定行（正则^PASS:）。要求判定行是为了防止"老式脚本退出 0 却打印 residual"的假通过；要求退出码是为了防止"判定前崩溃"也通过（源码_run_proof）。
• 判定词汇表：PASS、HUMAN_REVIEW是仅有的两个 ok 判定；FAIL、MISSING_PROOF、AMBIGUOUS_PROOF、UNCLASSIFIED、AMBIGUOUS_KIND均不通过。链判定 PASS 当且仅当每个提交的判定都是PASS或HUMAN_REVIEW。
• 报告结构：markdown 全文同时打印到 stdout 并写入报告路径，包含：解析出的 base / branch / 证明文件夹与链判定、按 kind 的提交计数与证明 PASS 数（使用--skip-passed时还有复用计数）、按链顺序逐提交一行的表格（sha / kind / verdict / subject）、以及 Failure details 节（每个非 ok 提交一条：缺失证明的搜索位置、被破坏的分类规则、或失败证明的输出尾部 60 行）。
• 退出码：0链验证通过；1链被遍历但至少一个提交未通过；2设置错误——无法解析的引用、base 不是祖先、空区间、链中含 merge 提交、或证明文件夹缺失，此时什么都没被认证（源码_linear_commits与main的异常处理，ChainVerificationError对应退出 2）。

这些行为都有对应的 pytest 覆盖，位于 scripts/tests/reproduction_cli/：例如test_chain_of_proved_and_declared_commits_passes验证"一个被证明的机械提交加一个声明的非机械提交"整链 PASS；test_proof_exiting_zero_without_a_pass_line_is_a_fail验证"退出 0 但没有PASS:行仍判 FAIL"；test_proofs_run_concurrently_up_to_jobs验证并发执行确实并行；test_end_to_end_with_a_generated_proof_folder则端到端走通"真实移动提交 →generate_range生成证明 → CLI 验证 PASS"。

4. 把验证放回完整工作流

这份验证指南是mechanical-refactor-verify技能的消费端，它上游是生产端。完整链路为：

1. 拆分：把 PR 拆成带分类的小提交，格式<group-id>(<commit-id>,<kind>): <message>，<kind>精确为mechanical_provable或non_mechanical_provable；每个可证明的重定位（extract-function、批量移动、文件拆分、导入重指）是独立的mechanical_provable提交，不可证明的最小残渣是non_mechanical_provable提交（guide-split.md §1.1）。
2. 构造证明：用生成器mechanical_refactor_proof_generator.py <base>..<tip> --match '(?<!_)mechanical_provable' --out repro_out为每个匹配提交推断配方、生成并运行独立可审计脚本，产出自包含文件夹（repro_scripts/<sha>.py+output.log+output.html+ 引擎拷贝），再通过 gist / PR 附件 / 分支随 PR 发布（guide-construct-proof.md §1）。
3. 验证：评审者下载证明文件夹，运行本文 §1 的链级验证器，再完成 §1.4 的HUMAN_REVIEW双职责审计与 §2.3 的 authored 表面审计。

当生成器对某个重定位报UNSUPPORTED时，正确处置不是把它改标为non_mechanical_provable，而是手写Repro（从同一组原语组合变换，guide-construct-proof.md §2.3 给出了完整的Repro示例：lower_call_sites先降级调用点、move_symbol移动、add_import补导入、run()裁决），或先增强原语再证明。评审者在这一环节的职责正是把"非机械标签作为逃逸通道"的反模式抓出来——这是 §1.4 职责 2 存在的全部理由。

5. 相关文件索引

• guide-verify-proof.md —— 本文对应的原始指南（消费证明：链级验证器、单提交重跑、判定、authored 表面审计清单）
• guide-construct-proof.md —— 生产证明：整链证明文件夹与发布（§1）、单提交证明（§2）
• guide-split.md —— 拆分 PR 为分类片段（§1）与 prepare + move + postpare（§2）
• spec-reproduction-cli.md —— 链级验证的规范（verified-chain 性质、词规则、证明义务、报告、退出码）
• spec-reproduction-utils.md —— clean-move 性质与全部重定位原语的规范契约
• mechanical_refactor_reproduction_cli.py —— 链级验证器实现
• mechanical_refactor_proof_generator.py —— 配方推断与证明生成器实现
• mechanical_refactor_reproduction_utils.py —— 证明引擎（Repro 构建器 + worktree / pre-commit / 字节 diff 脚手架，仅依赖 git 与标准库）
• scripts/tests/reproduction_cli/ —— 链级验证器的 pytest 套件（分类、证明解析、报告、跳过缓存、整链验证）

【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang