@kernel-sig/console 0.1.0

package/backend/app/domain/classification.py

@@ -0,0 +1,689 @@
+"""分类规则引擎与子系统归属推导。
+
+**规则优先，AI 兜底**：规则确定性、零成本、可解释；只有规则未命中或
+置信度低时才值得调用模型。全部走大模型既慢又贵，而且对
+"CVE-2026-1234" 这种标题来说，正则比模型准确得多。
+
+纯函数实现，无数据库与网络依赖。
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+
+def _p(*patterns: str) -> tuple[re.Pattern[str], ...]:
+    """把若干正则源码编译成模式元组。统一走大小写不敏感。"""
+    return tuple(re.compile(p, re.IGNORECASE) for p in patterns)
+
+
+# ---------------------------------------------------------------------------
+# 类型识别
+# ---------------------------------------------------------------------------
+
+
+class Kind(StrEnum):
+    """PR/Issue 的内容类别。
+
+    划分依据是维护者"接下来要做什么"，而不是学术上的完备分类：
+    安全修复有时限、回合补丁要逐行核对上游、新增驱动要看厂商支持范围、
+    自研特性要过 KABI —— 这些动作各不相同，因此必须能分开筛。
+    """
+
+    CVE = "cve"
+    RELEASE = "release"
+    BACKPORT = "backport"
+    DRIVER_NEW = "driver_new"
+    DRIVER_UPDATE = "driver_update"
+    SOC_SUPPORT = "soc_support"
+    OUT_OF_TREE = "out_of_tree"
+    BUGFIX = "bugfix"
+    FEATURE = "feature"
+    PERF = "perf"
+    REFACTOR = "refactor"
+    DOCS = "docs"
+    CLEANUP = "cleanup"
+    UNKNOWN = "unknown"
+
+
+CVE_PATTERN = re.compile(r"CVE-\d{4}-\d{4,}", re.IGNORECASE)
+# openEuler 的 PR 正文约定：fixes #123 / resolves #123 / closes #123
+LINKED_ISSUE_PATTERN = re.compile(
+    r"(?:fix(?:e[sd])?|resolve[sd]?|close[sd]?)\s*:?\s*#(\d+)", re.IGNORECASE
+)
+
+
+# ---------------------------------------------------------------------------
+# 提交信息里的自声明元数据
+# ---------------------------------------------------------------------------
+#
+# openEuler 的补丁在提交信息末尾带一段结构化标注，作者自己填写的：
+#
+#     stable inclusion
+#     from stable-v6.6.64
+#     commit 05b1b33936b71e5f189a813a517f72e8a27fcb2f
+#     category: bugfix
+#     bugzilla: https://atomgit.com/openeuler/kernel/issues/9674
+#
+# 实测 1264 条提交中 1235 条带 category（97.7%）。这比从标题猜关键词
+# 可靠得多 —— 标题描述的是"改了什么"，而这里直接写明"属于哪一类"
+# 以及"从哪来"。因此把它作为首选依据，标题规则退为兜底。
+
+CATEGORY_PATTERN = re.compile(r"^\s*category\s*:\s*(\w+)", re.MULTILINE | re.IGNORECASE)
+INCLUSION_PATTERN = re.compile(r"^\s*([\w-]+)\s+inclusion\b", re.MULTILINE | re.IGNORECASE)
+
+# 作者声明的 category → 类别。实测取值只有这几种，另含一个拼写错误。
+CATEGORY_TO_KIND: dict[str, Kind] = {
+    "bugfix": Kind.BUGFIX,
+    "feature": Kind.FEATURE,
+    "cleanup": Kind.CLEANUP,
+    "performance": Kind.PERF,
+    "perf": Kind.PERF,
+    "other": Kind.UNKNOWN,
+    # 实测存在 1 处拼写错误，宁可容错也不要把它当成新类别
+    "featrue": Kind.FEATURE,
+    "bugfx": Kind.BUGFIX,
+}
+
+# "X inclusion" 的来源标注 → 类别。
+# 它回答的是"这个补丁从哪来"，而来源直接决定评审方式：
+# 回合的要对照上游，自研的要过 KABI，驱动的要看厂商支持范围。
+INCLUSION_BACKPORT = frozenset({"mainline", "stable", "upstream", "lts", "linux", "next"})
+INCLUSION_DRIVER = frozenset({"driver", "drivers", "netdev"})
+INCLUSION_SOC = frozenset(
+    {
+        "kunpeng",
+        "hygon",
+        "phytium",
+        "zhaoxin",
+        "loongarch",
+        "loongson",
+        "ampere",
+        "virt",
+    }
+)
+INCLUSION_OUT_OF_TREE = frozenset(
+    {
+        "hulk",
+        "kylin",
+        "maillist",
+        "urma",
+        "cca",
+        "openeuler",
+        "anolis",
+        "deepin",
+        "opencloudos",
+        "nestos",
+        "uniontech",
+    }
+)
+
+
+def _inclusion_kind(name: str) -> Kind | None:
+    lowered = name.lower()
+    if lowered in INCLUSION_BACKPORT:
+        return Kind.BACKPORT
+    if lowered in INCLUSION_DRIVER:
+        return Kind.DRIVER_UPDATE
+    if lowered in INCLUSION_SOC:
+        return Kind.SOC_SUPPORT
+    if lowered in INCLUSION_OUT_OF_TREE:
+        return Kind.OUT_OF_TREE
+    # 未收录的 "<X> inclusion" 仍属非上游集成路径，归入自研特性而非猜测
+    return Kind.OUT_OF_TREE
+
+
+def parse_commit_metadata(messages: Sequence[str]) -> tuple[Kind | None, str | None]:
+    """从提交信息中提取作者声明的类别与来源。
+
+    返回 (类别, 来源标注)。多个提交时取首个非空值 ——
+    一个 PR 里的补丁通常属于同一批次，混装的情况极少。
+    """
+    declared: Kind | None = None
+    inclusion: str | None = None
+    for message in messages:
+        if not message:
+            continue
+        if declared is None:
+            match = CATEGORY_PATTERN.search(message)
+            if match:
+                declared = CATEGORY_TO_KIND.get(match.group(1).lower())
+        if inclusion is None:
+            match = INCLUSION_PATTERN.search(message)
+            if match:
+                inclusion = match.group(1).lower()
+        if declared is not None and inclusion is not None:
+            break
+    return declared, inclusion
+
+
+# ---------------------------------------------------------------------------
+# 厂商与自研标识
+# ---------------------------------------------------------------------------
+
+# 处理器/SoC 厂商名。两类刻意不收：
+#
+# - arm64 / x86 / riscv 这类通用架构前缀：它们在标题里几乎总是子系统前缀
+#   （"arm64: Fix ..."），算作"处理器支持"会把成片的普通补丁错判。
+# - hisi / hisilicon：内核里的 hisi 是驱动命名空间（hns、hisi_lpc 等），
+#   实测 "HISI-CCA and HISI-CCA-DA bugfixs" 这类标题被错判成了处理器支持，
+#   而它实际是缺陷修复。
+SOC_VENDORS = _p(
+    r"\bphytium\b",
+    r"\bzhaoxin\b",
+    r"\bloongarch\b",
+    r"\bloongson\b",
+    r"\bhygon\b",
+    r"\bkunpeng\b",
+    r"\bascend\b",
+    r"\bsunway\b",
+    r"\bshenwei\b",
+    r"\bampere\b",
+    r"飞腾",
+    r"兆芯",
+    r"龙芯",
+    r"海光",
+    r"鲲鹏",
+    r"申威",
+)
+
+# openEuler 的自研特性。这些子系统不在上游主线里，
+# 因此不能按回合补丁的方式评审。
+OUT_OF_TREE_MARKERS = _p(
+    r"\burma\b",
+    r"\bubcore\b",
+    r"\bub:",
+    r"\betmem\b",
+    r"\benfs\b",
+    r"\bmpath\b",
+    r"\bmultipath\b",
+    r"\bsyscare\b",
+    r"\bhulk\b",
+    r"\bsgx\b",
+    r"\bmilsa\b",
+    r"自研",
+)
+
+
+@dataclass(frozen=True)
+class KindRule:
+    """一条类型识别规则。"""
+
+    name: str
+    kind: Kind
+    patterns: tuple[re.Pattern[str], ...]
+    priority: int
+    # 匹配范围：标题、正文、或两者
+    scope: str = "title"
+
+    def matches(self, title: str, body: str) -> bool:
+        target = title if self.scope == "title" else f"{title}\n{body}"
+        return any(pattern.search(target) for pattern in self.patterns)
+
+
+# 具体形态规则：回答"这是什么"。
+#
+# 它们要优先于来源标注，因为来源只说"从哪来"：
+# "Add Phytium i3c controller support" 标着 openEuler inclusion，
+# 但维护者更需要知道的是"这是一条新增驱动"。
+SPECIFIC_TITLE_RULES: tuple[KindRule, ...] = (
+    KindRule(
+        # "add X driver" / "Add X controller support"：新增驱动是独立的一类，
+        # 因为维护者要判断的是"这个驱动的支持范围与上游是否有重叠"，
+        # 与普通新功能的评审关注点不同。
+        name="driver_new",
+        kind=Kind.DRIVER_NEW,
+        patterns=_p(
+            r"\badd(?:s|ed)?\b[^:]*\b(?:driver|controller)\b",
+            r"\bnew\s+(?:driver|controller)\b",
+            r"\bsupport\s+for\s+\w*\s*(?:driver|controller)\b",
+            r"新增驱动",
+        ),
+        priority=86,
+    ),
+    KindRule(
+        # 驱动版本升级："update X driver to v1.2.3"。
+        # 实测这类补丁来自厂商，改动量大且难以逐行对照上游。
+        name="driver_update",
+        kind=Kind.DRIVER_UPDATE,
+        patterns=_p(
+            r"\bupdate\b.*\bdrivers?\b",
+            r"\bdrivers?\b.*\bto\s+v?\d+\.\d+",
+            r"\bupgrade\b.*\bdrivers?\b",
+            r"驱动更新",
+            r"驱动升级",
+        ),
+        priority=84,
+    ),
+    KindRule(
+        name="soc_support",
+        kind=Kind.SOC_SUPPORT,
+        patterns=SOC_VENDORS,
+        priority=80,
+    ),
+    KindRule(
+        name="out_of_tree",
+        kind=Kind.OUT_OF_TREE,
+        patterns=OUT_OF_TREE_MARKERS,
+        priority=74,
+    ),
+)
+
+# 泛化性质规则：回答"改动的性质"。
+#
+# 排在来源标注之后 —— 来源已经说清"从哪来"时先信来源。
+# 例如 "net: fix NULL deref" 标着 mainline inclusion，
+# 按性质是 bugfix，但维护者需要知道的是"这是回合上游的补丁"。
+KIND_RULES: tuple[KindRule, ...] = (
+    KindRule(
+        # 版本发布。标题形如 "release 6.6.0-173.0.0.155"，是源码包仓的主要工作，
+        # 在那里占了近九成 —— 没有这一类时它们全部落进 unknown，界面上看起来
+        # 像是分类没跑。放在最前面：它是标题层面的强信号，不该被别的规则抢走。
+        name="release",
+        kind=Kind.RELEASE,
+        patterns=_p(r"^release\s+\S"),
+        priority=110,
+    ),
+    KindRule(
+        name="cve",
+        kind=Kind.CVE,
+        patterns=_p(r"CVE-\d{4}-\d{4,}"),
+        priority=100,
+    ),
+    KindRule(
+        name="backport",
+        kind=Kind.BACKPORT,
+        # "from <version> commit <sha>" 与 "from stable/upstream" 是 openEuler
+        # 回合补丁的标准标注；仅凭标题提到 upstream 不足以判定，故不用宽泛词
+        patterns=_p(
+            r"\bbackport(?:ed|ing)?\b",
+            r"cherry[\s-]?pick",
+            r"\bfrom\s+(?:upstream|mainline|stable)\b",
+            r"\bfrom\s+(?:linux-)?v?\d+\.\d+",
+            r"回合",
+            r"从上游",
+        ),
+        priority=60,
+    ),
+    KindRule(
+        name="kabi_breaking",
+        kind=Kind.BUGFIX,
+        patterns=_p(r"\bkabi\b.*(break|不兼容|变更)"),
+        priority=58,
+    ),
+    KindRule(
+        # 内核补丁标题描述的是"改了什么"，而不是"这属于哪一类"。
+        # 仅靠 fix/bug 两个字会漏掉大量实际是缺陷修复的上游风格标题
+        # （实测未命中样本里近半数属此类），因此把缺陷的**具体形态**也列为规则：
+        # 出现崩溃、泄漏、竞争、越界这类词，几乎必然是在修缺陷。
+        name="bugfix",
+        kind=Kind.BUGFIX,
+        patterns=_p(
+            r"\bfix(?:es|ed)?\b",
+            # 匹配 bug / bugs / bugfix / bugfixes —— 实测标题里 "bugfixs" 这种
+            # 拼写也存在，硬编码后缀清单会漏
+            r"\bbug\w*\b",
+            r"修复",
+            r"修正",
+            r"缺陷",
+            # 缺陷形态
+            r"\bpanic\b",
+            r"\bcrash(?:es|ed|ing)?\b",
+            r"\bleak(?:s|ed|ing)?\b",
+            r"\brace(?:s|d)?\b",
+            r"\bdeadlock\b",
+            r"\bhang(?:s|ing)?\b",
+            r"\bstuck\b",
+            r"\boops\b",
+            r"\bUAF\b",
+            r"\buse[- ]after[- ]free\b",
+            r"\bdouble[- ]free\b",
+            r"\bnull[- ]pointer\b",
+            r"\boob\b",
+            r"\boverflow\b",
+            r"\bunderflow\b",
+            r"\bout[- ]of[- ]bounds\b",
+            r"\bcorrupt(?:ion|ed)?\b",
+            r"\bregression\b",
+            r"\bincorrect(?:ly)?\b",
+            # 隐含"现在的行为不对"的措辞
+            r"\bmissing\b",
+            r"\bproperly\b",
+            r"\bprevent\b",
+            r"\bavoid\b",
+            r"\bdon'?t\b",
+            r"\bshould not\b",
+            r"\bno longer\b",
+            r"避免",
+            r"防止",
+            r"问题",
+        ),
+        priority=50,
+    ),
+    KindRule(
+        name="feature",
+        kind=Kind.FEATURE,
+        patterns=_p(
+            r"\bfeat(?:ure)?\b",
+            r"\badd support\b",
+            r"\bsupport for\b",
+            r"\bintroduce\b",
+            r"\benable\b",
+            r"新增",
+            r"支持",
+        ),
+        priority=40,
+    ),
+    KindRule(
+        name="refactor",
+        kind=Kind.REFACTOR,
+        patterns=_p(r"\brefactor\b", r"\bclean\s?up\b", r"\brework\b", r"重构"),
+        priority=30,
+    ),
+    KindRule(
+        name="docs",
+        kind=Kind.DOCS,
+        patterns=_p(r"\bdocs?\b", r"\bdocumentation\b", r"\bREADME\b", r"文档"),
+        priority=20,
+    ),
+)
+
+# 由提交信息自声明推导出的类别，其可信度高于标题关键词匹配 ——
+# 它是作者填写的，而标题只是对改动内容的描述。
+DECLARED_CONFIDENCE = 0.95
+TITLE_CONFIDENCE = 0.9
+# 未收录的 "<X> inclusion" 归入自研特性是靠推断，置信度相应降低
+INFERRED_INCLUSION_CONFIDENCE = 0.75
+
+# 标题前缀里的子系统标识，如 "mm: ..."、"net/sched: ..."
+TITLE_SUBSYSTEM_PATTERN = re.compile(r"^\s*([a-zA-Z0-9_/+-]+)\s*:")
+
+
+@dataclass
+class ClassifyResult:
+    kind: Kind
+    confidence: float
+    rule_name: str | None = None
+    reason: str | None = None
+    cve_ids: list[str] = field(default_factory=list)
+    linked_issues: list[int] = field(default_factory=list)
+    subsystem: str | None = None
+    related_subsystems: list[str] = field(default_factory=list)
+    title_subsystem: str | None = None
+
+
+def extract_cve_ids(text: str) -> list[str]:
+    """提取 CVE 编号并规范化大小写。"""
+    return sorted({match.upper() for match in CVE_PATTERN.findall(text or "")})
+
+
+def extract_linked_issues(text: str) -> list[int]:
+    """提取正文中声明的关联 Issue 编号。"""
+    if not text:
+        return []
+    return sorted({int(match) for match in LINKED_ISSUE_PATTERN.findall(text)})
+
+
+def extract_title_subsystem(title: str) -> str | None:
+    """从标题前缀提取子系统。
+
+    openEuler 与上游内核一致采用 "subsystem: description" 的标题约定，
+    前缀是**作者自己声明的**子系统归属，比从路径推断更贴近意图。
+    """
+    match = TITLE_SUBSYSTEM_PATTERN.match(title or "")
+    if not match:
+        return None
+    candidate = match.group(1).strip()
+    # 排除 "Revert"、"v2"、"PATCH" 这类非子系统前缀
+    if candidate.lower() in {"revert", "patch", "rfc", "v2", "v3", "fix", "fixes"}:
+        return None
+    if re.fullmatch(r"v\d+", candidate, re.IGNORECASE):
+        return None
+    return candidate
+
+
+def _first_match(rules: tuple[KindRule, ...], title: str, body: str) -> KindRule | None:
+    """按 priority 从高到低取首个命中的规则。"""
+    for rule in sorted(rules, key=lambda r: -r.priority):
+        if rule.matches(title, body):
+            return rule
+    return None
+
+
+def _from_rule(rule: KindRule, linked: list[int], title_subsystem: str | None) -> ClassifyResult:
+    return ClassifyResult(
+        kind=rule.kind,
+        confidence=TITLE_CONFIDENCE,
+        rule_name=rule.name,
+        reason=f"标题或正文命中规则「{rule.name}」",
+        linked_issues=linked,
+        title_subsystem=title_subsystem,
+    )
+
+
+def classify_by_rules(title: str, body: str, commit_messages: Sequence[str] = ()) -> ClassifyResult:
+    """按规则判定类型。
+
+    判定顺序刻意是"作者声明 → 标题关键词"：
+
+    1. CVE 编号出现在标题或正文——安全修复有独立时限，优先级最高
+    2. 提交信息里的 ``category:`` 与 ``<X> inclusion`` —— 作者自己填的，
+       实测覆盖率 97.7%，比从标题揣测可靠
+    3. 标题关键词规则
+
+    都不命中时返回 unknown 且置信度为 0，让调用方知道
+    "规则没看懂，可考虑交给 AI"。
+    """
+    cve_ids = extract_cve_ids(f"{title}\n{body}")
+    linked = extract_linked_issues(body)
+    title_subsystem = extract_title_subsystem(title)
+
+    # CVE 编号出现在标题或正文即判定为 CVE，无论标题措辞如何
+    if cve_ids:
+        return ClassifyResult(
+            kind=Kind.CVE,
+            confidence=1.0,
+            rule_name="cve",
+            reason=f"检测到 CVE 编号 {', '.join(cve_ids)}",
+            cve_ids=cve_ids,
+            linked_issues=linked,
+            title_subsystem=title_subsystem,
+        )
+
+    text = (title or "", body or "")
+
+    # 具体形态优先于来源标注：来源只说"从哪来"，
+    # 而"这是一条新增驱动"是维护者更需要的判断。
+    hit = _first_match(SPECIFIC_TITLE_RULES, *text)
+    if hit is not None:
+        return _from_rule(hit, linked, title_subsystem)
+
+    # 来源标注优先于泛化性质：同一个 category: bugfix 的补丁，
+    # 回合自 stable 还是出自自研分支，评审方式完全不同。
+    declared, inclusion = parse_commit_metadata(list(commit_messages or ()))
+    if inclusion is not None:
+        return ClassifyResult(
+            kind=_inclusion_kind(inclusion),
+            confidence=(
+                DECLARED_CONFIDENCE
+                if inclusion
+                in INCLUSION_BACKPORT | INCLUSION_DRIVER | INCLUSION_SOC | INCLUSION_OUT_OF_TREE
+                else INFERRED_INCLUSION_CONFIDENCE
+            ),
+            rule_name="commit_inclusion",
+            reason=f"提交信息声明 {inclusion} inclusion",
+            linked_issues=linked,
+            title_subsystem=title_subsystem,
+        )
+
+    hit = _first_match(KIND_RULES, *text)
+    if hit is not None:
+        return _from_rule(hit, linked, title_subsystem)
+
+    if declared is not None:
+        return ClassifyResult(
+            kind=declared,
+            confidence=DECLARED_CONFIDENCE,
+            rule_name="commit_category",
+            reason="提交信息声明 category",
+            linked_issues=linked,
+            title_subsystem=title_subsystem,
+        )
+
+    return ClassifyResult(
+        kind=Kind.UNKNOWN,
+        confidence=0.0,
+        rule_name=None,
+        reason="规则未命中",
+        linked_issues=linked,
+        title_subsystem=title_subsystem,
+    )
+
+
+# ---------------------------------------------------------------------------
+# 子系统归属
+# ---------------------------------------------------------------------------
+
+# 路径前缀 → 子系统。按最长前缀优先匹配，避免 "drivers/net" 被 "drivers" 抢走。
+SUBSYSTEM_PATHS: dict[str, str] = {
+    "arch/arm64": "arm64",
+    "arch/x86": "x86",
+    "arch/riscv": "riscv",
+    "arch/loongarch": "loongarch",
+    "drivers/net": "net-drivers",
+    "drivers/gpu": "drm",
+    "drivers/scsi": "scsi",
+    "drivers/nvme": "nvme",
+    "drivers/mmc": "mmc",
+    "drivers/usb": "usb",
+    "drivers/pci": "pci",
+    "drivers/acpi": "acpi",
+    "drivers/infiniband": "rdma",
+    "net/": "net",
+    "fs/": "fs",
+    "mm/": "mm",
+    "kernel/": "kernel-core",
+    "include/linux": "headers",
+    "security/": "security",
+    "block/": "block",
+    "io_uring/": "io_uring",
+    "virt/kvm": "kvm",
+    "crypto/": "crypto",
+    "tools/": "tools",
+    "Documentation/": "docs",
+    "drivers/": "drivers-other",
+}
+
+# 展示名：短名便于界面展示，避免 "net-drivers" 这种半中半英
+SUBSYSTEM_LABELS: dict[str, str] = {
+    "net": "网络",
+    "net-drivers": "网络驱动",
+    "fs": "文件系统",
+    "mm": "内存管理",
+    "arm64": "ARM64 架构",
+    "x86": "x86 架构",
+    "riscv": "RISC-V 架构",
+    "loongarch": "LoongArch 架构",
+    "drm": "图形驱动",
+    "scsi": "SCSI",
+    "nvme": "NVMe",
+    "mmc": "MMC",
+    "usb": "USB",
+    "pci": "PCI",
+    "acpi": "ACPI",
+    "rdma": "RDMA",
+    "kernel-core": "内核核心",
+    "headers": "头文件",
+    "security": "安全子系统",
+    "block": "块层",
+    "io_uring": "io_uring",
+    "kvm": "虚拟化 KVM",
+    "crypto": "加密",
+    "tools": "工具",
+    "docs": "文档",
+    "drivers-other": "其他驱动",
+}
+
+
+def subsystem_for_path(path: str) -> str | None:
+    """按最长前缀匹配推导单个路径的子系统。"""
+    if not path:
+        return None
+    best: tuple[int, str] | None = None
+    for prefix, name in SUBSYSTEM_PATHS.items():
+        if path.startswith(prefix) and (best is None or len(prefix) > best[0]):
+            best = (len(prefix), name)
+    return best[1] if best else None
+
+
+def derive_subsystem(filenames: list[str], *, max_related: int = 3) -> tuple[str | None, list[str]]:
+    """从变更文件推导主子系统与相关子系统。
+
+    主子系统 = 变更文件数最多的那个；平局时取路径更深的
+    （改动越具体越能代表这次变更的归属）。
+
+    注意这不是"重要程度"排序，只是量上的多数 ——
+    一个 PR 改了 100 个 drivers/ 文件和 1 个 mm/ 文件，
+    主子系统是 drivers-other，但 mm 的那处改动可能是核心修复。
+    因此相关子系统一并返回，不做取舍。
+    """
+    if not filenames:
+        return None, []
+
+    counts: dict[str, int] = {}
+    for filename in filenames:
+        name = subsystem_for_path(filename)
+        if name:
+            counts[name] = counts.get(name, 0) + 1
+
+    if not counts:
+        return None, []
+
+    ordered = sorted(counts.items(), key=lambda kv: (-kv[1], kv[0]))
+    primary = ordered[0][0]
+    related = [name for name, _ in ordered[1 : max_related + 1]]
+    return primary, related
+
+
+def subsystem_label(name: str | None) -> str:
+    if not name:
+        return "未归类"
+    return SUBSYSTEM_LABELS.get(name, name)
+
+
+def normalize_subsystem(name: str | None) -> str | None:
+    """把标题里声明的子系统归一化到 SUBSYSTEM_PATHS 的取值域。
+
+    标题前缀是自由文本：``mm``、``mm/hugetlb``、``drivers/net/ethernet``
+    指的都是已知子系统，直接入库会让统计里出现几十个近义项。
+    先按已知名称精确匹配，再退化为路径前缀匹配；仍不认识则返回 None ——
+    与其塞进一个假的分类，不如让它留在"未归类"里被看见。
+    """
+    if not name:
+        return None
+    candidate = name.strip().strip("/").lower()
+    if not candidate:
+        return None
+    # 已是已知子系统名（mm、arm64、drm…）
+    if candidate in SUBSYSTEM_LABELS:
+        return candidate
+    # 路径形态（mm/hugetlb、net/sched、drivers/net/ethernet），
+    # 末尾补 "/" 让 "mm" 这类裸名也能走前缀匹配
+    return subsystem_for_path(candidate) or subsystem_for_path(f"{candidate}/")
+
+
+# ---------------------------------------------------------------------------
+# 分类标签名
+# ---------------------------------------------------------------------------
+
+
+def classification_label(kind: Kind) -> str:
+    """平台写回 AtomGit 时使用的标签名。
+
+    统一 `kind/` 前缀，与仓库中已有的 `kind/abandoned`、`kind/kabi-need-review`
+    等标签保持一致的命名习惯。
+    """
+    return f"kind/{kind.value}"