# PR #28978 完整报告

- 仓库：`sgl-project/sglang`
- 标题：Enhance large class styles and code styles
- 合并时间：2026-07-09 07:32
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/28978

---

# 执行摘要

- 一句话：更新大型类代码风格规则和一般代码风格指南
- 推荐动作：建议所有参与 SGLang 开发的工程师阅读这两份文档，特别是对 `Scheduler`、`TokenizerManager`、`ModelRunner` 有修改需求的团队。值得关注的设计决策是将大型类定义为纯编排角色，严格分离领域逻辑，有助于防止类膨胀。

# 功能与动机

采纳 @merrymercy 的建议，将大型类（Scheduler, TokenizerManager, ModelRunner）的代码风格归纳为正式文档，并补充一般性 Python 代码风格规则，以指导团队保持一致风格。

# 实现拆解

1. **重命名并扩展技能**：将 `.claude/skills/large-class-init-style/` 重命名为 `large-class-style/`，重写 `SKILL.md` 并增加“Frozen Code”章节，定义哪些文件（当前为 `model_runner.py`）为冻结文件，禁止追加领域逻辑；允许的操作为构造（`init_*`）、委派（`self.foo.run(...)`）、协调（`if` 选择、结果传递）。使用示例符号 `init_foo`、`ModelRunner` 等阐明边界。
2. **新增通用代码风格规则**：在 `.claude/rules/general-code-style.md` 中明确 9 条约定，包括偏爱无状态、不可变、保持函数 / 文件较小、避免 mixin、优先 `protected` 方法、使用关键字参数、传递具体值而非 god object 等。
3. **更新组件修改指南**：在 `.claude/rules/modify-component-must-read.md` 中，将引用从 `large-class-init-style` 改为 `large-class-style`，并增加一条“编辑冻结核心文件前必读 `large-class-style`”的提示。
4. **清理旧文档**：删除 `large-class-init-style/SKILL.md`。

测试、配置或部署配套变更：无。

关键文件：
- `.claude/skills/large-class-style/SKILL.md`（模块 技能文档；类别 docs；类型 documentation；符号 init_foo, ModelRunner, bar, foo）: 核心变更文件，定义大型类代码风格，是 PR 主旨。
- `.claude/skills/large-class-init-style/SKILL.md`（模块 技能文档；类别 docs；类型 deletion）: 旧技能文件被删除，因为已被新技能替代。
- `.claude/rules/general-code-style.md`（模块 通用规则；类别 docs；类型 documentation）: 新增通用 Python 代码风格规则文件，作为团队开发规范参考。
- `.claude/rules/modify-component-must-read.md`（模块 组件规则；类别 docs；类型 documentation）: 更新引用以指向新技能文件，并增加冻结核心文件编辑提示。

关键符号：init_foo, ModelRunner, bar, foo

## 关键源码片段

### `.claude/skills/large-class-style/SKILL.md`

核心变更文件，定义大型类代码风格，是 PR 主旨。

---
name: large-class-style
description: 'Code style for SGLang large classes `Scheduler`, `TokenizerManager`, and `ModelRunner`: frozen-code conventions and `__init__` orchestration style. Use when modifying any of these three classes or reviewing changes to them.'
---

# Code Style for Scheduler / TokenizerManager / ModelRunner

Conventions for SGLang's three large classes:

- `Scheduler` — `python/sglang/srt/managers/scheduler.py`
- `TokenizerManager` — `python/sglang/srt/managers/tokenizer_manager.py`
- `ModelRunner` — `python/sglang/srt/model_executor/model_runner.py`

## 1. Frozen Code

- Some core files are **frozen**: *orchestration-only* — a thin composition root that constructs collaborators, wires them, delegates to them, and coordinates the calls. They must stay that way.
- **Domain logic does not belong in a frozen file**; it lives in a collaborator class in its own module.

# Code Style for Scheduler / TokenizerManager / ModelRunner

Conventions for SGLang's three large classes:

- `Scheduler` — `python/sglang/srt/managers/scheduler.py`
- `TokenizerManager` — `python/sglang/srt/managers/tokenizer_manager.py`
- `ModelRunner` — `python/sglang/srt/model_executor/model_runner.py`

## 1. Frozen Code

- Some core files are **frozen**: *orchestration-only* — a thin composition root that constructs collaborators, wires them, delegates to them, and coordinates the calls. They must stay that way.
- **Domain logic does not belong in a frozen file**; it lives in a collaborator class in its own module.

### 1.2 Frozen files

- `python/sglang/srt/model_executor/model_runner.py`

### 1.3 Allowed: orchestration

Every statement refers to a collaborator and is one of:

1. **Construct**— a short `init_<thing>` helper whose body is essentially a single construction (follows §2); use `maybe_init_<thing>` with a one-line gate when conditional.
2. **Wire**— a short call that runs the helper from the orchestrator (e.g. in `__init__`).
3. **Delegate**— calls to a collaborator's methods at the necessary call sites (`self.foo.run(...)`).
4. **Coordinate**— the minimal control flow that *selects or orders* the above: an `if` choosing whether / which collaborator to wire or call, the order of calls, threading one call's result into the next.

```python
# model_runner.py — orchestration only.
def init_foo(self): # construct
    self.foo = FooManager(server_args=self.server_args, device=self.device)

self.init_foo() # wire (in __init__)

if self.server_args.enable_bar: # coordinate: select
    self.bar.prepare(forward_batch) # delegate
out = self.foo.run(forward_batch) # delegate
self.baz.consume(out) # coordinate: thread result into next delegate

```


# 评论区精华

无 review 评论。

- 暂无高价值评论线程

# 风险与影响

- 风险：变更仅涉及 `.claude/` 下的技能和规则文档，不影响运行时代码。主要风险是团队可能未及时阅读或尚未遵循新规则，导致风格不一致，属于低风险。
- 影响：影响 SGLang 团队代码贡献者的开发规范：大型类改动的开发者需遵循冻结代码约定；所有 Python 代码贡献者需参考一般代码风格规则。影响范围限于开发流程，不影响系统运行。
- 风险标记：文档性变更风险低

# 关联脉络

- PR #30483 Enhance mechanical refactor proof construction and verification skill: 同为技能文档增强，本 PR 原本包含机械重构技能变更，后拆分为独立 PR。