执行摘要

本次PR更新了SGLang项目的测试编写指南，明确禁止在模块级别直接修改sys.modules来模拟依赖，因为这种操作在pytest导入所有测试文件时会导致跨测试污染。文档建议使用patch.dict作为类装饰器或配合start/stop方法进行清理，确保测试隔离性。这是对测试开发规范的重要澄清，影响所有编写单元测试的开发者，但无代码变更，风险较低。

功能与动机

为什么做：根据review评论，现有文档中关于使用setUpModule配合patch.dict的建议存在缺陷：1) setUpModule在模块导入后执行，如果依赖在顶层导入时触发，补丁会太晚；2) 需要显式清理以避免污染。本次修改旨在提供更安全、更可靠的测试依赖模拟方法，防止跨测试污染问题。

实现拆解

修改了两个关键文档文件：

关键代码逻辑更新：

• 在SKILL.md中，将“See test/registered/unit/README.md for details and examples.”扩展为“Do not modify sys.modules at module level — use patch.dict (as a class decorator or with start/stop) to ensure cleanup and avoid cross-test pollution.”
• 在README.md中，新增段落强调避免模块级sys.modules修改，并推荐patch.dict配合清理。

评论区精华

review中只有一个评论者gemini-code-assist[bot]提供了技术反馈：

“The recommendation to use setUpModule with patch.dict has two significant drawbacks:

1. Import Timing: setUpModule runs after the module is imported. If the test file has top-level imports that trigger the dependency, the patch will be applied too late. 2. Cleanup: patch.dict inside setUpModule requires explicit start() and stop() (or addModuleCleanup) to prevent the very pollution this rule aims to avoid.”

评论者建议使用patch.dict作为类装饰器是更好的替代方案。PR作者接受了建议，更新了文档以明确禁止模块级sys.modules修改。

未解决的疑虑：评论者询问现有maybe_stub_sgl_kernel()模块级调用是否仍是推荐做法，但未得到明确回答。

风险与影响

风险分析：

1. 文档变更风险：新指南可能过于严格，影响现有测试编写模式，但这是最佳实践的澄清。
2. 理解风险：开发者可能误解新指南，错误应用patch.dict导致测试失败。
3. 兼容性风险：现有测试中可能仍有模块级sys.modules修改，但本次PR只更新文档，不修改代码，因此不会直接影响现有测试运行。

影响分析：

• 对用户：无直接影响，这是内部开发文档更新。
• 对系统：无代码变更，不影响运行时行为。
• 对团队：所有编写SGLang测试的开发者需要遵循新指南，避免使用模块级sys.modules修改，这能提高测试的隔离性和可靠性。影响程度中等，涉及测试编写规范的变更。

关联脉络

与近期历史PR的关联：

1. PR #22176（Fix ut module importing）：同样涉及测试导入问题，重构了测试文件的导入机制以避免CPU-only环境依赖问题。本次文档更新可视为对该PR实践的规范化。
2. PR #21400和#21399（添加CPU-only单元测试）：这些添加单元测试的PR可能受到本次文档更新的影响，未来编写类似测试需要遵循新指南。

演进趋势：SGLang项目近期持续加强测试基础设施，包括添加单元测试（如#21400、#21399）、修复测试导入问题（#22176）以及本次规范化测试编写指南。这表明团队在提升测试覆盖率和质量方面投入资源，确保代码可靠性。本次PR是这一趋势的延续，通过文档更新统一测试开发实践。