# PR #37210 完整报告

- 仓库：`sgl-project/sglang`
- 标题：[CI][RFC] Replace black-jupyter with ruff-format
- 合并时间：2026-09-03 10:46
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/37210

---

## 执行摘要

本 PR 将 CI 代码格式化工具从 black-jupyter 替换为 ruff-format，旨在解决 lint 任务耗时过长的问题。变更包括配置更新和对整个代码库的机械性重新格式化，预计可将 lint 任务时间减半，并提升 CI 稳定性。主要影响 CI 基础设施，对运行时行为无影响。

## 功能与动机

black-jupyter 是 CI lint 任务的主要成本（约 218 秒，占总时间的约 60%），且因其每次运行都重新格式化所有文件，磁盘缓存无法在 CI 中生效。ruff format 产生与 black 兼容的风格，但速度快约 100 倍（约 2 秒），并已与 pre-commit 配置中锁定的 ruff 版本一致。此迁移可将 lint 任务时间减半，并消除唯一的增长项。

## 实现拆解

1. **配置交换**：在 `.pre-commit-config.yaml` 中，将 black-jupyter hook 替换为 ruff-format，保持相同的位置（在 ruff lint hook 之后）和排除列表。由于 black 未使用任何配置，ruff-format 的默认设置与之完全兼容。
2. **机械性重新格式化**：运行 `pre-commit run ruff-format --all-files`，对整个代码库应用 ruff 格式化。所有变更均为风格调整（如隐式字符串连接合并、空行移除、换行优化等），不改变任何语义。
3. **配套处理**：后续 PR #37695 添加了 `.git-blame-ignore-revs` 文件，以忽略本次格式化提交对 git blame 的影响。

### 由于变更为纯格式化，无关键源码片段需要展示。格式化示例可参考 `python/sglang/srt/mem_cache/mamba_radix_cache.py` 中 assert 语句的格式变化。

## 评论区精华

无评论。PR body 已包含详细的动机说明、变更方案和验证方法（如通过二次格式化空 diff 验证），并提供了审查指引。

## 风险与影响

- **合并冲突**：约 1400 个文件被重新格式化，可能与进行中的 PR 产生大量冲突。解决方案是合并 main 后重新运行格式化。
- **开发者工具链**：编辑器中配置 black 的开发者可能需要调整，但 pre-commit 会自动修正，且 ruff 与 black 风格兼容。
- **无运行时风险**：所有变更仅为代码格式，不影响功能、性能或安全性。

## 关联脉络

本 PR 是 CI 性能优化系列的一部分，后续 PR #37695 立即跟进添加了 git-blame-ignore-revs，显示团队对大型代码格式化迁移有成熟的流程。与历史 PR #37203（flatten 其他 lint 成本）共同构成了对 CI lint 任务的全面优化。