执行摘要

• 一句话：cookbook 安装命令统一加 --prerelease=allow
• 推荐动作：不值得精读代码（本 PR 无代码），但值得完整浏览其 PR body——它是一份高质量的"文档类缺陷修复"范本：有根因分析、可复现的度量数据（uv pip compile 对比表）、显式的排除清单和最终验证手段（git grep）。对维护者：建议跟进 #35912 的 packaging/runtime guard，从包层面让静默降级不可能发生；同时可按环境指纹（0.5.9 + 对应 torch pin + uv 0.11.x）重新分类 #24029 等 6 个旧 issue。

功能与动机

本 PR 修复 #35912 的文档部分。根因是：uv < 0.12.0 不遵循传递依赖元数据中的预发布版本说明（上游 astral-sh/uv#19993 才修复），而 flash-attn-4 自 sglang 0.5.10 起是强制依赖且只在 PyPI 发布预发布版，于是 uv pip install sglang 会把每个 ≥ 0.5.10 的版本判为不可满足，并"无报错、无警告"地回溯到 0.5.9（2026-02-23）。PR body 进一步指出 sglang==0.5.18 固定了 cuda-tile==1.6.0rc5，版本固定后解析器无法回溯，旧 uv 下源码/可编辑安装会直接失败。install.mdx 早已带 flag（#29676），但 cookbook 页面普遍缺失，按模型页照抄命令的用户会静默装到 6 个月前的旧版，并踩到早已修复的 bug——如 #35912 中 Qwen3.8-27B 因缺 #19070 的 down_proj all-reduce 而出现"输出流畅但结果错误、无 crash、无 NaN"的现象。

实现拆解

1. 范围摸排：以 #35912 提供的 uv pip compile 对比数据（uv 0.11.24 默认解析出 sglang==0.5.9，加 flag 后为 sglang==0.5.18）为依据，用 git grep "uv pip install" -- docs 定位所有漏加 flag 的 SGLang 安装命令，覆盖三种安装形态：PyPI（uv pip install sglang、"sglang>=0.5.9"、定版本 nightly）、git（git+...#subdirectory=python）、源码（-e python、-e "python[all]"）。
2. 批量修改 26 个 cookbook 页面：31 条命令统一加 --prerelease=allow；除命令本身外，同步修正周边注释以保持页面自洽，如 Tencent/Hy3.mdx 中"Once a tagged release picks it up, uv pip install sglang is enough"改成了带 flag 的写法，MiniMax-M3.mdx 中关于 #27944 合并后安装方式的预期描述也一并更新。
3. 安装指南补注：在 docs/docs/get-started/install.mdx Method 1 的 PyPI 命令块后新增两句话的 <Note>，直接说明"部分依赖只在 PyPI 发预发布版，旧 uv 会静默装到 0.5.9，uv ≥ 0.12.0 无需该 flag"。
4. 模板层预防：修改 .claude/skills/cookbook-add-model/templates/page.mdx.tmpl 的默认安装命令，让 Claude Code 生成的新模型页面从一开始就带上 flag，从源头杜绝同类遗漏（数据契约层面的预防性修改）。
5. 排除项显式化：刻意不动非 SGLang 安装命令（lmms_eval、natten、".[s2pro]" 属于 sglang-omni 独立仓库）、已带 flag 的 6 个 diffusion 页面与 LongCat-2.0、以及不涉及 flash-attn-4/cuda-tile 的平台页（tpu.mdx 装 sglang-jax；cpu_server.mdx 用 pyproject_cpu.toml；apple_metal.mdx 与 sglang-diffusion/installation.mdx 用 pyproject_other.toml）。
6. 验证配套：纯文档变更，无单元测试；node docs/scripts/check_cookbook_configs.mjs 通过；改动后用 git grep 确认 docs 下已无缺 flag 的 SGLang uv 安装命令。

关键文件：

• docs/docs/get-started/install.mdx（模块 安装指南；类别 docs；类型 documentation）: 安装指南是用户的第一入口，本次在其 Method 1 命令块后新增两句话的 Note，把"为什么需要 --prerelease=allow"和"uv ≥ 0.12.0 不需要"直接写进用户必经页面，是全 PR 的"为什么"落地到文档的关键。
• .claude/skills/cookbook-add-model/templates/page.mdx.tmpl（模块 文档模板；类别 docs；类型 data-contract）: 这是 Claude Code 生成新模型页面的模板，默认安装命令改为带 flag 的写法，相当于在"数据契约"层面做了预防，让未来所有新增页面默认正确，是本 PR 最有长期价值的一处改动。
• docs/cookbook/autoregressive/Qwen/Qwen3.8-27B.mdx（模块 模型文档；类别 docs；类型 documentation）: 这是 #35912 中点名的示例页面，也是 TP>1 输出错误（缺 #19070 修复）受害场景的直接来源；该页同时覆盖 PyPI 与 -e "python[all]"（DFLASH2 专用）两种安装形式。
• docs/cookbook/autoregressive/Qwen/Qwen3.6.mdx（模块 模型文档；类别 docs；类型 documentation）: 该页同时给出 PyPI 与 git 源码两种安装形态，是"命令形态覆盖广度"的代表页面，两条命令都补上了 flag。
• docs/cookbook/autoregressive/Tencent/Hy3.mdx（模块 模型文档；类别 docs；类型 documentation）: 除命令外还同步修正了"tagged release 之后直接 uv pip install 即可"的注释，体现了命令与周边文案一致性的维护，是同类页面中处理最完整的一处。
• docs/cookbook/autoregressive/MiniMax/MiniMax-M3.mdx（模块 模型文档；类别 docs；类型 documentation）: 该页涉及 PR 分支安装（#27944 的 FETCH_HEAD）与 release 后安装预期两处文案，展示了"一次性页面"同样需要同步处理的细节。

关键符号：未识别

关键源码片段

docs/cookbook/autoregressive/Qwen/Qwen3.6.mdx

该页同时给出 PyPI 与 git 源码两种安装形态，是"命令形态覆盖广度"的代表页面，两条命令都补上了 flag。

# 注释：Qwen3.6 页面同时给出 PyPI 与 git 源码两种安装方式，
# 两条命令都补上 --prerelease=allow，确保旧版 uv（< 0.12.0）
# 也能正确解析到最新发布版本，而不是静默回退到 0.5.9。
# Install from PyPI
uv pip install --prerelease=allow sglang
​
# Or install from source
uv pip install --prerelease=allow 'git+https://github.com/sgl-project/sglang.git#subdirectory=python'

评论区精华

本 PR 没有任何内联 review 评论，唯一审核人 wisclmy0611 直接 APPROVED（body 为空），说明变更本身没有引发争议。实质性的设计讨论沉淀在 PR body 与 #35912 中：作者明确把修复拆成"docs 一半"和"packaging/runtime guard 一半"，后者（让静默降级在包层面不可能发生的防护，以及对 #24029、#34111、#34112、#34113、#33283、#25670 等旧 issue 的重新分类）刻意留作 follow-up。另一个值得注意的决策是"哪些命令刻意不加 flag"：作者给出排除清单及理由（如 ".[s2pro]" 属于 sglang-omni 独立仓库、pyproject_cpu.toml 不含预发布 pin），并用 git grep 作为覆盖完整性的事后验证。

• 范围界定：只修 docs 一半，packaging guard 留作 follow-up (design): PR 明确只覆盖文档一半，先用 --prerelease=allow 兜底用户侧；包层防护留待 #35912 继续推进。
• 刻意不动的安装命令清单 (question): 以 git grep 验证 docs 中已无缺 flag 的 SGLang uv 安装命令，覆盖完整性得到确认。

风险与影响

• 风险：功能风险：基本为零。flag 在 uv ≥ 0.12.0 是 no-op，pip 与 Docker 安装路径不受影响（PR body 已用 uv pip compile 对比表和 pinned 失败输出佐证）。残余风险有三点：一是文档兜底只能覆盖"按文档操作"的用户，直接用记忆里裸命令的旧 uv 用户仍会静默装到 0.5.9，包层防护依赖 #35912 后续推进；二是模板改动只对之后用模板生成的新页面生效，手工新增页面仍需 review 习惯配合；三是依赖演进风险——未来 flash-attn-4 转 stable 或 cuda-tile==1.6.0rc5 换正式版后，这些 flag 会变成无害但多余的噪音，Hy3.mdx 等页面的"release 后即可"注释也需再次清理，存在文档随版本演进过时的风险。
• 影响：用户侧：使用 uv < 0.12.0 的用户按 cookbook 安装不再静默拿到 0.5.9，从而避免"模型输出错误但无任何报错"的诡异现象（#35912 中 Qwen3.8-27B TP>1 案例）；对 uv ≥ 0.12.0、pip、Docker 用户零行为变化。仓库侧：变更纯文档，28 个文件、+36/-32，不触碰运行时代码、依赖清单或 CI 逻辑；影响面为 26 个 cookbook 页面 + 安装指南 + 页面生成模板。团队侧：模板默认带 flag 能减少后续"新页面漏 flag"的 review 负担，同时为 #35912 的 packaging guard 争取了时间窗口。
• 风险标记：依赖解析行为依赖 uv 版本, 文档兜底无法覆盖不看文档的用户, 文档注释存在版本演进过时风险

关联脉络

• PR #29676 （原文未提供标题）install.mdx 加入 --prerelease=allow: PR body 明确说明 docs/docs/get-started/install.mdx 已通过 #29676 携带该 flag，本次变更是在其基础上的全量补齐，属于同一文档线、同一改动手法。
• PR #35912 [Bug] uv pip install sglang with uv < 0.12 silently installs 0.5.9 (6 months old): 本 PR 修复该 Issue 的 docs 一半；Issue 还包含 packaging guard 与旧 issue 重新分类两个未完成的 follow-up。
• PR #19070 （原文未提供标题）qwen3_5 dense TP>1 修复: Issue #35912 引用它作为 0.5.9 用户受害的具体示例（缺失 down_proj all-reduce 导致 TP>1 输出错误），用于说明静默降级的实际危害。