执行摘要

本PR修复了SGLang版本检测中的bug，通过将setuptools-scm配置从tag-only模式切换为describe模式，确保安装时显示当前checkout的确切版本标签而非最新本地标签，影响所有平台配置，提升版本管理准确性。变更已添加单元测试验证，风险较低。

功能与动机

根据issue #22034，从v0.5.7开始，SGLang安装时显示的版本号总是动态解析为最新的本地标签，而不是当前checkout的确切版本标签。这导致在回滚到旧提交时版本号显示不正确，影响调试和版本管理。PR body明确指出修复此问题，使版本检测逻辑优先使用确切标签，确保版本号与实际代码版本一致。

实现拆解

实现方案包括两部分：

• 配置修改：修改所有相关pyproject.toml文件（如python/pyproject.toml、python/pyproject_npu.toml等），将git_describe_command从["python3", "python/tools/get_version_tag.py", "--tag-only"]改为["python3", "python/tools/get_version_tag.py"]，以使用describe模式。同时，为多个文件添加fallback_version = "0.0.0.dev0"以确保在无Git元数据时安装仍能进行。
• 测试添加：新增单元测试文件test/registered/unit/tools/test_get_version_tag.py，测试内容涵盖：
  • 版本标签排序（如v0.5.10.post1高于v0.5.10）。
  • 确切标签优先级高于最新标签。
  • pyproject配置使用describe模式且包含fallback_version。
  • --tag-only CLI模式保留可用性。

关键代码逻辑示例（来自测试文件）：

def test_exact_version_tag_takes_precedence_over_latest_tag(self):
    with patch.object(
        self.version_helper, "get_exact_version_tag", return_value="v0.5.9"
    ), patch.object(
        self.version_helper, "get_latest_version_tag_describe"
    ) as latest_describe:
        self.assertEqual(self.version_helper.get_version_describe(), "v0.5.9")
        latest_describe.assert_not_called()

评论区精华

review讨论主要围绕配置一致性和测试组织：

• fallback_version添加：gemini-code-assist[bot]建议在多个pyproject.toml文件中添加fallback_version，作者回复“Added the matching fallback_version in d11499b23 and updated the pyproject wiring test to require it across all wheel pyprojects.”，确保跨平台配置健壮性。
• 测试文件位置：Kangyan-Zhou建议“Can we move this file to a dedicated directory under unit/?”，作者回复“Moved the test into test/registered/unit/tools/ and adjusted REPO_ROOT in 689ddc77b so it still resolves from the new location.”，优化代码结构。

风险与影响

• 技术风险：低。变更仅影响版本检测元数据，不涉及运行时路径，无回归、性能或安全风险。添加的测试覆盖确保逻辑正确性，但需注意get_version_tag.py工具函数的潜在错误，已通过测试验证。
• 影响范围：用户安装时将看到正确版本号，提升体验；系统性能不受影响；团队需确保所有平台配置更新同步，但变更已标准化。影响程度为低，限于包构建阶段。

关联脉络

与历史PR的关联：

• PR 21441（升级Intel GPU PyTorch XPU版本）同样涉及dependencies标签，体现依赖管理的一致性，但主题为版本升级而非检测逻辑。
• PR 22653（移除Dockerfile中冗余缓存复制）涉及infra和dependencies，展示基础设施维护，但无直接版本检测关联。

本PR修复了issue #22034，是版本管理流程的重要改进，反映了团队对跨平台配置一致性和用户体验的关注。