开源项目 Issue 自动化分诊机器人的首周运行报告

作为开源项目 Maintainer 或企业内部基础架构库的维护者，每天最令人身心俱疲的不是修复核心 Bug，而是被大量无效、重复或缺乏上下文的 Issue 淹没。典型的低质 Issue 往往只有一句“启动报错了怎么办”，既没有贴出完整的日志堆栈，也没有说明运行环境、操作系统与依赖版本。Maintainer 不得不一遍遍机械回复：“请提供最小复现 Demo”、“请附带操作系统和 Node/Go 版本”。

为了将维护者从繁琐的初筛劳动中解放出来，我们开发并部署了一款基于轻量大模型的 Issue 自动化分诊机器人（Triage Bot），并在一个 Star 数超 10k 的核心基础库中完成了为期 7 天的首周运行测试。

分诊机器人架构与处理策略

分诊机器人通过 GitHub App 监听 issues.opened 与 issues.edited 事件，执行四步漏斗式分流：

1. 第一步：模板契约与要素完备性校验
   检测正文中是否包含必填环境信息（OS, Arch, Version, Minimal Reproducible Example）。若核心字段为空，直接触发温和提示并打上 needs-reproduce-info 标签。
2. 第二步：历史 Issue 与向量知识库检索去重
   对新 Issue 的标题和内容生成 Embedding，在已解决的 Closed Issues 与 FAQ 文档库中进行 Top-3 相似度检索。如果余弦相似度高于 0.88，自动引用历史解决方案并引导用户自助核对。
3. 第三步：意图识别与多维度自动化打标
   将 Issue 内容送入语义分类器，自动打上组件标签（如 area/auth、area/storage）与属性标签（kind/bug、kind/enhancement、kind/question）。
4. 第四步：高危漏洞与紧急事故自动指派
   如果内容涉及“安全漏洞、内存越界、未授权访问”等高危特征，自动标记 priority/critical 并通过 Slack/飞书 Webhook 实时通知当周 On-Call 轮值成员。

import os
import requests
from typing import Dict, Any, List

class IssueTriageHandler:
    def __init__(self, github_token: str, repo: str):
        self.headers = {
            "Authorization": f"token {github_token}",
            "Accept": "application/vnd.github.v3+json"
        }
        self.repo = repo

    def triage_issue(self, issue_number: int, title: str, body: str):
        # 1. 快速检查要素完备性
        missing_fields = []
        if "### Environment" not in body or "Version:" not in body:
            missing_fields.append("环境与版本信息")
        if "### Steps to Reproduce" not in body and "```" not in body:
            missing_fields.append("最小复现代码片段 (Code Snippet)")

        if missing_fields:
            comment_body = (
                f"👋 感谢提交 Issue！为了方便维护者排查，检测到当前 Issue 缺少以下必要信息：\n\n"
                f"- " + "\n- ".join(missing_fields) + "\n\n"
                f"请编辑您的 Issue 补充上述内容。在信息补全前，该 Issue 将被暂时搁置。"
            )
            self._add_comment(issue_number, comment_body)
            self._add_labels(issue_number, ["status/needs-info"])
            return

        # 2. 模拟大模型意图推断与标签建议
        labels_to_add = ["status/triage-passed"]
        if "panic:" in body or "segmentation fault" in body:
            labels_to_add.extend(["kind/bug", "priority/urgent"])
        elif "feature" in title.lower() or "support" in title.lower():
            labels_to_add.append("kind/feature")
        else:
            labels_to_add.append("kind/question")

        self._add_labels(issue_number, labels_to_add)

    def _add_comment(self, issue_num: int, body: str):
        url = f"https://api.github.com/repos/{self.repo}/issues/{issue_num}/comments"
        requests.post(url, headers=self.headers, json={"body": body}, timeout=10)

    def _add_labels(self, issue_num: int, labels: List[str]):
        url = f"https://api.github.com/repos/{self.repo}/issues/{issue_num}/labels"
        requests.post(url, headers=self.headers, json={"labels": labels}, timeout=10)

首周运行数据分析与反馈

在首周运行中，机器人累计处理了 142 个新提交的 Issue，运行表现如下：

运营经验与调优建议

首周实践让我们收获了几个关键的认知迭代：

1. 语气必须温和克制：自动化机器人的回复千万不能给提问者居高临下的“拒止感”。在评论模板中必须真诚感谢贡献者，并清晰给出“为什么需要这些字段”、“如何提供这些字段”的示例。
2. 避免过早自动关闭（Auto-Close）：不要在提问不规范的瞬间立即将 Issue 关闭（Close），这会极大地挫伤社区提问者的积极性。合理的做法是打上等待标记（needs-info），并设置 7 天无响应定时任务（Stale Action）后再执行关闭。
3. 分诊机器人的终极价值是凝聚高质量上下文：维护者介入时，面对的不再是残缺不全的吐槽，而是已经带有版本号、最小复现用例与分类标签的清晰技术报告。

自动化分诊不是冷冰冰的拦截墙，而是开源项目维护者与社区贡献者之间的“翻译器”与“协作者”。将低效沟通标准化，开源社区才能形成持续正向的技术循环。