执行摘要

• 一句话：更新大型类代码风格规则和一般代码风格指南
• 推荐动作：建议所有参与 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.

# 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。