执行摘要

本 PR 为 SGLang 仓库新增 Claude 技能文档 env-var-conventions，系统化定义了环境变量的定义位置、类型描述符选择、API 访问、命名规范、重命名与弃用流程，并更新组件修改规则使其成为开发流程必读项。这是一项纯文档变更，对生产代码无影响，但能显著提高环境变量管理的规范性。

功能与动机

随着 SGLang 项目发展，各类环境变量散落在 environ.py、utils/common.py 及各处 os.getenv 调用中，缺乏统一规范。本 PR 旨在填补这一空白，通过一份权威的技能文档明确以下问题的答案：

• 新加环境变量应定义在哪个文件？→ Envs 类（python/sglang/srt/environ.py）
• 该使用哪种描述符？→ EnvBool / EnvInt / EnvStr / EnvTuple 等
• 如何读取？→ 通过 EnvField.get()，而非直接 os.getenv
• 如何命名？→ SGLANG_* 前缀，SGL_* 已弃用
• 如何重命名或弃用？→ 遵循两阶段弃用流程

同时更新 .claude/rules/modify-component-must-read.md，确保任何修改环境变量的人必须先阅读该技能，形成制度约束。

实现拆解

1. 新增技能文档（python/sglang/.claude/skills/env-var-conventions/SKILL.md，+203 行）：以规则形式组织，包含：

   • 规则 1：定义在 Envs 类，并提供决策表区分 SGLANG_*、上游变量、外部变量和弃用的 SGL_*
   • 规则 2：使用类型化描述符，列出 EnvBool、EnvInt、EnvFloat、EnvStr、EnvTuple
   • 规则 3：通过 envs.X.get() 访问，仅 UPDATE_ENV_VARS 支持批量覆盖
   • 规则 4：命名以 SGLANG_* 开头，避免负数或否定默认值
   • 规则 5：重命名分两阶段（新增别名 + 弃用旧名 → 移除旧名）
   • 规则 6：若存在对应 CLI 标志，确保两者行为一致，并提供 --help 输出验证

2. 更新组件修改规则（.claude/rules/modify-component-must-read.md，+1 行）：将 env-var-conventions 技能加入对 SGLANG_* 相关修改的必读列表。

整项变更不涉及 python/sglang/srt/ 下的任何代码，属于纯文档和流程规范。无需测试配置或部署配套。

本次变更不涉及运行时代码，仅为 Markdown 文档，因此无需展示源码片段。技能文档全文可通过 .claude/skills/env-var-conventions/SKILL.md 查看。

评论区精华

• gemini-code-assist[bot] 建议在技能中同时提及 get_int_env_var 辅助函数，因为 common.py 中同样存在 FIXME 警告，防止开发者误用。作者在后续 commit 中补充了这一细节。
• gemini-code-assist[bot] 指出“双否定”表述不准确，建议区分标志默认值与双否定模式。作者修正了措辞，明确提醒避免定义默认值为 True 的否定标志（如 DISABLE_FOO = EnvBool(True)），因为会导致调用处出现 if not 这样的双否定写法。

两个建议均以解决告终，最终文档更加严谨。

风险与影响

• 风险：极低。不修改任何生产代码，仅增加文档。唯一风险是若未来环境变量实际行为与文档不一致，可能误导开发者。需要维护者持续同步。
• 影响：
  • 直接影响：所有新增或修改环境变量的开发者必须阅读该技能，遵守约定。
  • 间接影响：长期看将减少环境变量相关的设计缺陷和疏漏，提高可维护性。
  • 范围：限于仓库内部开发流程，用户无感知。

关联脉络

• 与本 PR 同属环境变量相关的前序 PR #26193 新增了 SGLANG_DISABLE_FLASHINFER_AUTOTUNE 变量，体现了遵循本技能定义的命名和注册方式。
• 未来，所有新建环境变量的 PR 都应引用本技能作为约束，期待环境变量管理逐渐收敛到 Envs 类，淘汰 utils/common.py 中的遗留帮助函数。