执行摘要

该 PR 为配置系统重构打下基础，通过为 ServerArgs 的每个字段添加命名空间标记（NS）及配套提取函数 namespace_of，并添加全覆盖测试，将配置项与运行时配置领域关联起来，且不改变现有行为。这是后续通过命名空间访问解析配置的关键一步。

功能与动机

动机来自 PR 描述：Part of a stacked series introducing a structured RuntimeContext configuration API (resolved config read through domain namespaces; ServerArgs becomes the read-only record)。需要为每个 ServerArgs 字段分配命名空间，以便后续通过领域命名空间读取解析配置，取代手写的镜像文件。

实现拆解

1. 在 python/sglang/srt/arg_groups/arg_utils.py 中定义冻结数据类 NS（包含 path: str 属性）作为命名空间路径标记，并实现缓存函数 namespace_of(cls)，遍历数据类字段的 Annotated 元数据，提取字段名到命名空间路径的映射。
2. 在 python/sglang/srt/server_args.py 中，为每个 ServerArgs 字段的 Annotated 注解追加 NS("...") 标记；由于 NS 是新增数据类元素，argparse 和配置解析逻辑仅识别 Arg 等已有元数据，因此对现有行为零影响（已验证 AST 一致性）。同时更新导入语句以包含 NS。
3. 新增测试文件 test/registered/unit/test_server_args_namespaces.py，包含三个测试用例：test_every_field_has_a_namespace 确保所有字段都有 NS 标记；test_all_namespaces_are_known 验证所有命名空间路径都在已知列表中；test_namespace_map_covers_all_fields 确保映射覆盖所有字段且数量不少于 440。这些测试构成防火墙，防止后续添加字段时忘记分配命名空间。

NS 类和 namespace_of 函数 (arg_utils.py)

import dataclasses
import functools
from typing import get_origin, get_args, Annotated
​
@dataclasses.dataclass(frozen=True)
class NS:
    """Namespace-path marker for a ServerArgs field.
​
    Attached inside ``Annotated`` metadata:
        field: Annotated[int, Arg(help="..."), NS("parallel")] = 1
​
    Kept separate from ``Arg`` so existing fields only need to *append* one element.
    """
    path: str
​
​
@functools.lru_cache(maxsize=None)
def namespace_of(cls) -> dict:
    """Return ``{field_name: dotted namespace path}`` from each field's ``NS`` marker.
    Fields without ``NS`` are omitted (tests flag them).
    """
    if not dataclasses.is_dataclass(cls):
        return {}
    hints = get_type_hints(cls, include_extras=True)
    out = {}
    for field in dataclasses.fields(cls):
        tp = hints.get(field.name, field.type)
        if get_origin(tp) is Annotated:
            for a in get_args(tp)[1:]: # skip the base type
                if isinstance(a, NS):
                    out[field.name] = a.path
                    break
    return out

测试覆盖 (test_server_args_namespaces.py)

import dataclasses
import unittest
from sglang.srt.arg_groups.arg_utils import namespace_of
from sglang.srt.server_args import ServerArgs
​
VALID_NAMESPACES = {
    "parallel", "device", "model", "schedule", "memory", "spec",
    "lora", "mm", "disagg", "serving", "observability",
    "exec.kernel", "exec.moe", "exec.graph", "exec.comm",
    "exec.mamba", "exec.overlap", "exec.offload", "exec.dllm",
    "exec.deterministic", "exec.features",
}
​
​
def _field_names():
    return {f.name for f in dataclasses.fields(ServerArgs)}
​
​
class TestServerArgsNamespaces(unittest.TestCase):
    def test_every_field_has_a_namespace(self):
        nsmap = namespace_of(ServerArgs)
        missing = sorted(_field_names() - set(nsmap))
        self.assertFalse(
            missing,
            "ServerArgs fields missing an NS(...) marker "
            f"(assign a namespace in server_args.py): {missing}",
        )
​
    def test_all_namespaces_are_known(self):
        nsmap = namespace_of(ServerArgs)
        bad = {f: p for f, p in nsmap.items() if p not in VALID_NAMESPACES}
        self.assertFalse(bad, f"unknown namespace paths (typo or new domain?): {bad}")
​
    def test_namespace_map_covers_all_fields(self):
        nsmap = namespace_of(ServerArgs)
        self.assertEqual(set(nsmap), _field_names())
        self.assertGreaterEqual(len(nsmap), 440)

评论区精华

该 PR 无有效 Review 讨论（仅有一条自动化工具的配额警告）。

风险与影响

风险极低。变更完全是附加性的：新增 NS 类和 namespace_of 函数，不影响任何现有路径；NS 被 argparse 和解析逻辑忽略，不会改变 CLI 或配置解析行为。测试套件提供了强覆盖保障，会对所有字段的命名空间标记进行回归检查。对用户透明，不改变任何外部 API 或行为。对开发者为后续读取配置打下基础：未来可通过 namespace_of 映射直接获取某命名空间下的所有配置项。团队需确保新字段正确添加 NS 标记，测试会自动检查。

关联脉络

该 PR 是配置重构系列的一环，与以下历史 PR 紧密相关：

• #31810 添加了 resolved-config namespace bags 和 accessors
• #31811 使 ServerArgs 只读并添加审计入口
• #31814 开始通过命名空间访问器读取配置

这些 PR 共同构建了 RuntimeContext 命名空间配置 API，本 PR 为其提供字段标注基础。