1. 为什么我要把 Issue 分诊这件事交给机器维护过开源项目的人都有一个共同体会写代码本身不累累的是每天打开仓库通知栏看到十几条新 Issue 躺在那里标题五花八门内容质量参差不齐。有的只写了一句用不了求修复有的把使用问题当成 Bug 报有的重复提了三个月前就已经关闭的同一个问题还有的干脆是来发广告的。你花半小时逐条读完、打标签、回复请提供复现步骤结果真正需要你动手修的那个关键 Bug 反而被淹没在噪音里。这件事的本质是Issue 列表的第一轮筛选是一项高重复、低创造性的认知劳动。它需要判断力但不需要深度思考它消耗注意力但不产生代码价值。而恰恰是这种有判断规则、有历史数据、有明确分类标准的任务最适合交给 AI 来做第一轮分诊。我做的这个 Issue 分诊助手核心目标很朴素当一条新 Issue 进来时自动完成分类、打标签、判断优先级、识别重复、生成一段礼貌且信息完整的首轮回复草稿。维护者打开列表时看到的已经不是一堆原始文本而是一份已经分好类、标好优先级、附带了处理建议的清单。你只需要做最终决策而不是从零开始读每一条。这篇文章适合三类人看一是正在维护开源项目、被 Issue 淹没的个人开发者二是团队内部用 Issue 系统做需求收集、想提升处理效率的工程团队三是对 AI 应用落地感兴趣、想找一个真实场景练手的技术同学。我会把整个系统的设计思路、核心模块、提示词工程细节、踩过的坑以及如何评估分诊准确率全部拆开讲清楚。你不需要是 AI 专家只要会调用 API、懂基本的工程结构就能跟着复现一套属于自己的分诊助手。2. 分诊助手到底要解决哪几个具体问题2.1 把读 Issue拆成五个可自动化的判断动作很多人一上来就想做一个全能 AI 助手结果做出来的东西什么都沾一点什么都不精。我的做法是先把维护者读一条 Issue 时的思维过程拆解成离散的判断动作每个动作对应一个明确的输出。第一个动作是分类这条 Issue 属于 Bug 报告、功能请求、使用咨询、文档问题还是无效内容广告、灌水、与项目无关。第二个动作是打标签根据分类和内容匹配仓库已有的标签体系比如bug、enhancement、question、documentation、duplicate。第三个动作是优先级判断结合问题严重程度、影响范围、是否阻塞核心功能给出 P0 到 P3 的初步定级。第四个动作是重复检测判断这条 Issue 是否和已有 Issue 高度相似。第五个动作是首轮回复生成针对信息不完整的 Issue生成一段索要复现步骤、环境信息、日志的标准化回复。把这五个动作分开设计的好处是每个动作的提示词可以独立调优每个动作的准确率可以独立评估出问题时能快速定位是哪个环节的判断偏了。如果把它们揉成一个帮我处理这条 Issue的大提示词你根本不知道错误出在哪一步。2.2 为什么不能让 AI 直接做最终决策这里有一个关键的设计原则AI 只做分诊不做裁决。分诊的意思是分门别类、给出建议裁决的意思是最终拍板。我坚持让 AI 的输出停留在建议层面所有标签的最终应用、Issue 的关闭、优先级的确认都需要人工点一下。原因很实际。AI 分类会犯错尤其是边界模糊的 Issue。比如一条这个功能在特定配置下表现异常的反馈它到底算 Bug 还是功能请求AI 可能给出一个合理但你不认同的判断。如果它直接自动打了标签、甚至自动关闭了 Issue一旦判错对提 Issue 的人来说体验极差对项目声誉也是伤害。而如果它只是给出一条建议分类为 Bug建议标签 bug/needs-repro建议优先级 P2的提示你扫一眼就能确认或修正效率提升依然巨大但风险几乎为零。提示把 AI 定位成给维护者省去第一遍阅读的助手而不是替代维护者做决定的系统这个定位决定了你整个架构的安全边界。2.3 分诊质量的天花板取决于仓库自身的数据质量这一点是我踩坑之后才深刻理解的。AI 分诊的准确率很大程度上不取决于你用了多强的模型而取决于你的仓库有没有清晰、一致、有历史沉淀的标签体系和 Issue 数据。如果一个仓库的标签只有默认的bug和enhancement两个历史 Issue 也从来没认真打过标签那 AI 就没有可参照的分类标准它只能凭通用常识去猜准确率自然上不去。反过来如果一个仓库有十几个语义清晰的标签历史 Issue 都规范地打过标签那你甚至可以把这些历史数据作为少样本示例喂给模型分诊准确率会明显提升。所以我在动手写代码之前先做了一件事梳理并规范化仓库的标签体系。把含义重叠的标签合并把从没用过的僵尸标签删掉给每个标签写一句清晰的适用说明。这一步看起来和 AI 无关但它直接决定了后面分诊效果的上限。3. 系统架构一条 Issue 进来之后发生了什么3.1 整体数据流与模块划分整个分诊助手的数据流可以这样理解Issue 创建事件触发 → 拉取 Issue 正文和元信息 → 预处理与去噪 → 调用分类模块 → 调用重复检测模块 → 调用优先级评估模块 → 生成回复草稿 → 汇总成一条分诊建议 → 推送给维护者确认。我把它拆成了四个核心模块。接入层负责监听 Issue 事件、拉取数据、做格式清洗。分析层是核心包含分类器、重复检测器、优先级评估器三个子模块。生成层负责把分析结果组织成人类可读的分诊建议和回复草稿。交互层负责把结果推送到维护者能看到的地方并接收人工确认反馈。这种分层的好处是每一层都可以独立替换。比如你一开始用规则做重复检测后来想换成向量相似度只需要替换分析层里的一个子模块其他部分不受影响。3.2 接入层怎么拿到干净的 Issue 文本接入层最容易被人忽视但它决定了后面所有分析的输入质量。Issue 正文里往往混着大量噪音用户贴的完整报错日志、大段代码块、截图链接、模板残留的占位文字、甚至是从别处复制来的无关内容。我的处理策略是保留结构、压缩体积。具体做法是把正文按 Markdown 结构解析识别出标题、段落、代码块、引用块。代码块如果超过一定长度只保留前若干行和总行数提示因为对分类判断来说代码块的存在和大致内容比完整内容更重要。模板占位文字比如请描述你的问题下面什么都没填直接剔除。最终拼成一段结构清晰、长度可控的文本送给模型。为什么要压缩因为模型的上下文窗口是有限的而且输入越长推理越慢、成本越高。一条 Issue 正文动辄几千字如果原样送进去既浪费又可能稀释关键信息。压缩到几百字的精华反而能让模型抓重点。3.3 分析层三个判断器如何协同分析层的三个判断器不是简单串行而是有依赖关系的。分类结果是重复检测和优先级评估的重要输入。比如一条被分类为使用咨询的 Issue优先级评估时就不应该给太高的级别而一条被分类为Bug且涉及核心功能的 Issue重复检测时就应该更严格地比对历史 Bug 类 Issue。我的实现方式是先跑分类器拿到分类和置信度然后把分类结果作为上下文分别喂给重复检测器和优先级评估器。重复检测器除了比对文本相似度还会参考分类结果缩小比对范围。优先级评估器则结合分类、正文中提到的关键词如崩溃数据丢失无法启动这类高严重度信号以及影响范围描述综合给出定级。三个判断器的输出最终汇总成一个结构化的 JSON包含分类、标签建议、优先级、重复候选列表、置信度。这个 JSON 就是生成层的输入。3.4 生成层与交互层让维护者一眼看懂生成层的任务是把冷冰冰的 JSON 变成维护者一眼能看懂的分诊卡片。我的卡片结构是这样的顶部一行是分类和优先级中间是标签建议和重复候选底部是回复草稿。回复草稿会根据 Issue 的信息完整度动态调整——如果用户没给复现步骤草稿就礼貌地索要复现步骤如果用户没给环境信息草稿就索要环境信息。交互层我选择把分诊卡片推送到维护者日常工作的沟通渠道里而不是让维护者去某个后台系统里看。因为维护者的注意力在哪里工具就应该出现在哪里。卡片上带确认和修正按钮维护者点一下就能应用标签、发送回复或者修正 AI 的判断。这些修正反馈会被记录下来成为后续优化提示词的宝贵数据。4. 提示词工程分诊准确率的真正战场4.1 分类提示词给模型一套清晰的判断标准分类是整个分诊的起点分类错了后面全错。我在这块提示词上花的功夫最多。核心思路是不要只告诉模型帮我分类而要给它一套明确的判断标准和边界说明。我的分类提示词大致包含这几块内容。第一块是角色设定告诉模型它是一个开源项目的 Issue 分诊助手需要严谨、保守拿不准时倾向于给出低置信度而不是强行分类。第二块是分类定义把每个类别的含义、典型特征、边界情况都写清楚。比如Bug 报告的定义是用户报告项目在特定条件下未按预期工作并明确如果用户只是问怎么用即使语气像在抱怨也应归为使用咨询。第三块是输出格式约束要求模型输出分类名称、置信度、判断理由三部分理由必须引用 Issue 中的具体文字。为什么要让模型输出理由因为理由是你调试提示词的抓手。当分类出错时看理由就能知道是模型理解错了类别定义还是 Issue 本身太模糊。如果只输出一个分类结果你根本无从下手优化。4.2 重复检测文本相似度不够还要语义理解重复检测是最容易做砸的模块。我一开始用简单的文本相似度算法结果发现两个用完全不同措辞描述同一个问题的 Issue相似度可能很低而两个措辞相似但实际问题不同的 Issue相似度反而很高。纯文本匹配根本不够用。后来我改成语义相似度加分类约束的方案。先用向量化模型把 Issue 正文转成向量计算余弦相似度筛出相似度超过阈值的候选集。然后把这个候选集连同当前 Issue 一起送给模型让模型判断这些候选里哪些是真正的重复。模型在判断时会考虑问题的本质是否相同而不是表面措辞。这里有个经验重复检测的候选集不要太大。如果一次给模型几十个候选它容易看花眼判断质量下降。我的做法是先按分类过滤再按向量相似度排序只取前几个最相似的候选送给模型精判。这样既保证了召回又控制了输入规模。4.3 优先级评估把模糊的严重程度变成可打分的维度优先级评估最难的地方在于严重是个主观词。不同维护者对同一个问题的严重程度判断可能完全不同。我的解法是把严重程度拆成几个可独立判断的维度每个维度给出明确的分档标准最后综合打分。我用的维度有三个。影响范围影响所有用户、影响部分用户、还是只影响特定边缘场景。功能重要性涉及核心功能、重要功能、还是次要功能。可绕过性用户有没有临时替代方案还是完全被阻塞。每个维度分三档组合起来映射到 P0 到 P3。这样拆的好处是模型不需要直接回答这有多严重这种模糊问题只需要回答三个相对具体的小问题每个小问题都有明确的判断依据。实测下来这种拆维度打分的方案比让模型直接给优先级要稳定得多不同 Issue 之间的定级也更一致。4.4 回复草稿礼貌、具体、可执行回复草稿的生成原则是礼貌但不啰嗦具体但不机械可执行但不居高临下。我见过太多项目用模板回复请提供更多信息这种回复对提 Issue 的人毫无帮助他根本不知道要提供什么。我的草稿会根据缺失的信息类型动态生成。如果缺复现步骤草稿会写为了帮你定位问题能否补充一下具体的操作步骤比如你执行了哪些操作、期望看到什么结果、实际看到了什么结果。如果缺环境信息草稿会列出需要的信息清单操作系统版本、项目版本、相关依赖版本。如果缺日志草稿会说明需要哪个环节的日志以及如何获取。草稿生成后不会自动发送而是作为建议呈现给维护者。维护者可以一键发送也可以修改后再发。这样既保证了回复的及时性和规范性又保留了人工把关的空间。5. 实测中暴露的问题与我的修正方案5.1 模型对边界模糊的 Issue 容易过度自信跑了一段时间后我发现一个规律模型对分类清晰的 Issue 判断很准但对边界模糊的 Issue它经常给出高置信度的错误判断。比如一条既像 Bug 又像功能请求的 Issue模型可能斩钉截铁地分成 Bug置信度还标得很高。这个问题很危险因为高置信度的错误判断会误导维护者。我的修正方案是在提示词里显式要求模型在遇到边界情况时降低置信度并给出具体的降级规则。比如如果一条 Issue 同时符合两个类别的特征置信度不应超过某个阈值并在理由中说明存在歧义。同时我在后处理逻辑里加了一条置信度低于阈值的分诊结果会被标记为需要人工重点确认在卡片上高亮显示。5.2 长 Issue 的关键信息被淹没有些用户提 Issue 时会把所有信息一股脑写进去正文长达几千字关键信息藏在中间某一段。模型处理这种长文本时容易抓不住重点分类和优先级判断都会受影响。我的应对是在预处理阶段做关键信息抽取。具体做法是先用一个轻量模型或规则从长正文中抽取出可能包含问题描述、复现步骤、环境信息、报错信息的段落把这些段落优先保留并放在送给模型文本的前面。这样即使正文很长关键信息也能出现在模型注意力的黄金位置。实测下来这个改动让长 Issue 的分类准确率有明显提升。5.3 重复检测的误报让人头疼重复检测最怕误报——把两个不重复的 Issue 判成重复然后建议关闭其中一个。这种误报对提 Issue 的人伤害很大他会觉得自己的问题被敷衍了。我踩过的坑是早期阈值设得太松导致大量误报。后来我做了两件事。一是提高判定门槛只有模型明确判断这两个 Issue 描述的是同一个根本问题时才标记为重复仅仅是相关或相似不算。二是把重复判定从自动建议降级为提示卡片上只显示可能与某 Issue 相关请人工确认绝不自动关闭。宁可漏报不可误报这是重复检测的铁律。5.4 不同仓库的标签体系差异导致提示词难以复用我一开始想做一个通用提示词结果发现不同仓库的标签体系差异太大一个仓库的bug标签含义和另一个仓库的完全不同。通用提示词在具体仓库上表现很差。后来我改成提示词模板加仓库配置的方案。提示词模板提供固定的框架和判断逻辑仓库配置提供该仓库特有的标签定义、分类标准、优先级规则。每次分诊时把仓库配置动态注入提示词模板。这样一套模板可以服务多个仓库每个仓库又有自己的定制化判断标准。这个改动让分诊助手从一个只能服务单个项目的工具变成了可以服务多个项目的平台。6. 如何评估分诊助手到底好不好用6.1 建立人工标注的评估集没有评估优化就是盲人摸象。我做的第一件事是从历史 Issue 中抽取一批样本人工标注正确的分类、标签、优先级作为评估集。样本要覆盖各种类型清晰的 Bug、模糊的边界情况、重复 Issue、无效内容、长文本 Issue每种都要有。评估集不需要很大但一定要有代表性。我用了大约一百条历史 Issue 做评估集覆盖了仓库里所有主要类别。每次调整提示词或更换模型后都在这套评估集上跑一遍对比准确率变化。这样每一次优化都有数据支撑而不是凭感觉。6.2 分模块评估而不是只看整体整体准确率会掩盖很多问题。比如整体准确率看起来不错但可能分类很准而优先级评估很差两者一平均就看不出来了。所以我坚持分模块评估分类准确率、重复检测的精确率和召回率、优先级评估与人工标注的一致率分别统计。分模块评估的好处是能精准定位短板。如果发现重复检测召回率低就知道要优化候选集生成如果优先级一致率低就知道要调整维度划分或分档标准。每个模块的优化方向完全不同混在一起评估根本无从下手。6.3 用真实反馈持续迭代评估集是静态的但真实世界的 Issue 是动态的。所以我特别重视维护者在实际使用中的修正反馈。每次维护者修正了 AI 的判断这条记录就被保存下来定期回顾。如果发现某类修正反复出现说明提示词在这类情况上有系统性偏差需要针对性优化。这个反馈闭环是分诊助手能持续变好的关键。一个上线后就不管的 AI 工具准确率只会随着项目演进而下降。只有把真实反馈接进来它才能跟着项目一起成长。7. 部署与成本控制的实际考量7.1 异步处理避免阻塞 Issue 创建流程分诊分析需要调用模型耗时从几秒到几十秒不等。如果同步处理用户提交 Issue 后要等很久才能看到创建成功体验很差。所以我把分诊做成异步任务Issue 创建后立即返回成功分诊在后台队列里慢慢跑跑完再把结果推送给维护者。异步架构还带来一个好处可以控制并发。模型调用有速率限制如果同时来一大批 Issue同步处理会直接撞上限制。异步队列可以平滑削峰按可控的速率消费任务。7.2 分级调用控制成本模型调用是要花钱的如果每条 Issue 都用最强模型全量分析成本会很高。我的策略是分级调用。先用一个轻量、便宜的模型做初步分类和置信度评估。如果置信度高、分类清晰就直接采用不再调用强模型。只有置信度低或分类模糊的 Issue才升级到强模型做精细分析。这个策略在保证准确率的同时把大部分简单 Issue 的处理成本压到了很低。实测下来大约七成的 Issue 可以用轻量模型搞定只有三成需要强模型介入整体成本下降明显。7.3 缓存与去重减少重复计算有些操作是重复的。比如同一个仓库的标签配置每次分诊都要用没必要每次都重新读取和拼接。我把这些静态配置做了缓存。另外如果同一条 Issue 因为某种原因被重复触发分诊可以用 Issue ID 做去重避免重复调用模型。这些优化单看都很小但累积起来对成本和响应速度的影响不小。工程上的事往往就是这些不起眼的细节决定了系统能不能长期稳定运行。8. 我在这件事上踩过的几个真实坑第一个坑是过早追求全自动。我一开始想着让 AI 全自动打标签、自动回复、自动关闭重复 Issue结果上线没几天就出了几次误判搞得提 Issue 的人很不满。后来退回到AI 建议、人工确认的模式效率提升依然明显但风险可控多了。这件事让我明白AI 应用落地信任是一点点建立的不是一步到位的。第二个坑是忽视冷启动问题。新仓库没有历史数据AI 没有可参照的分类标准分诊准确率很低。我的解法是给新仓库准备一套默认的标签体系和分类标准作为起点随着使用积累数据再逐步用真实数据优化。冷启动阶段不要期待太高准确率先把流程跑通让数据积累起来。第三个坑是提示词越改越复杂。有段时间我为了让模型处理各种边界情况不断往提示词里加规则结果提示词变得又长又乱模型反而更容易困惑。后来我做了减法把一些边缘规则移到后处理逻辑里用代码实现提示词只保留最核心的判断标准。提示词不是越长越好清晰比全面更重要。第四个坑是没有考虑多语言 Issue。项目国际化之后Issue 里混着好几种语言早期提示词只针对中文优化处理其他语言的 Issue 时准确率下降。后来我在提示词里明确要求模型用 Issue 本身的语言理解和判断输出则统一用维护者指定的语言这个问题才解决。9. 后续可以继续深挖的方向这套分诊助手跑通之后我发现它其实是一个更大的自动化体系的起点。往深了做有几个方向值得探索。一是从分诊延伸到初步定位。现在助手只告诉你这是一条 Bug优先级 P2未来可以进一步分析报错日志尝试定位可能出问题的模块甚至给出初步的排查建议。这对维护者来说价值更大。二是建立 Issue 与代码的关联。如果能把 Issue 描述的问题和代码仓库里的相关文件、函数关联起来维护者点开 Issue 就能直接跳到可能相关的代码位置省去大量搜索时间。三是把分诊数据反哺到项目决策。长期积累的分诊数据能反映出项目的痛点分布哪类问题最多、哪些功能最容易被误用、文档哪里最不清楚。这些洞察对项目路线规划很有价值是分诊助手带来的额外收益。四是做成可配置的通用平台。现在这套系统虽然支持多仓库配置但配置还需要手动写。未来可以做成可视化配置让不懂技术的维护者也能轻松接入自己的项目。我在实际使用中最大的体会是AI 在开源维护这类场景里的价值不在于替代人做判断而在于把人从重复的、低价值的认知劳动里解放出来让人把精力集中在真正需要创造力和深度思考的地方。分诊助手做的就是这样一件事——它不替你做决定但它让你做决定之前的那段准备时间从半小时缩短到几分钟。这个价值对于任何一个被 Issue 淹没的维护者来说都是实实在在的。 
长河君 · 2026/10/13 12:28:52 · 阅读 1.2k 用AI打造开源Issue自动分诊助手：分类、打标签、优先级评估与重复检测实战
1. 为什么我要把 Issue 分诊这件事交给机器维护过开源项目的人都有一个共同体会写代码本身不累累的是每天打开仓库通知栏看到十几条新 Issue 躺在那里标题五花八门内容质量参差不齐。有的只写了一句用不了求修复有的把使用问题当成 Bug 报有的重复提了三个月前就已经关闭的同一个问题还有的干脆是来发广告的。你花半小时逐条读完、打标签、回复请提供复现步骤结果真正需要你动手修的那个关键 Bug 反而被淹没在噪音里。这件事的本质是Issue 列表的第一轮筛选是一项高重复、低创造性的认知劳动。它需要判断力但不需要深度思考它消耗注意力但不产生代码价值。而恰恰是这种有判断规则、有历史数据、有明确分类标准的任务最适合交给 AI 来做第一轮分诊。我做的这个 Issue 分诊助手核心目标很朴素当一条新 Issue 进来时自动完成分类、打标签、判断优先级、识别重复、生成一段礼貌且信息完整的首轮回复草稿。维护者打开列表时看到的已经不是一堆原始文本而是一份已经分好类、标好优先级、附带了处理建议的清单。你只需要做最终决策而不是从零开始读每一条。这篇文章适合三类人看一是正在维护开源项目、被 Issue 淹没的个人开发者二是团队内部用 Issue 系统做需求收集、想提升处理效率的工程团队三是对 AI 应用落地感兴趣、想找一个真实场景练手的技术同学。我会把整个系统的设计思路、核心模块、提示词工程细节、踩过的坑以及如何评估分诊准确率全部拆开讲清楚。你不需要是 AI 专家只要会调用 API、懂基本的工程结构就能跟着复现一套属于自己的分诊助手。2. 分诊助手到底要解决哪几个具体问题2.1 把读 Issue拆成五个可自动化的判断动作很多人一上来就想做一个全能 AI 助手结果做出来的东西什么都沾一点什么都不精。我的做法是先把维护者读一条 Issue 时的思维过程拆解成离散的判断动作每个动作对应一个明确的输出。第一个动作是分类这条 Issue 属于 Bug 报告、功能请求、使用咨询、文档问题还是无效内容广告、灌水、与项目无关。第二个动作是打标签根据分类和内容匹配仓库已有的标签体系比如bug、enhancement、question、documentation、duplicate。第三个动作是优先级判断结合问题严重程度、影响范围、是否阻塞核心功能给出 P0 到 P3 的初步定级。第四个动作是重复检测判断这条 Issue 是否和已有 Issue 高度相似。第五个动作是首轮回复生成针对信息不完整的 Issue生成一段索要复现步骤、环境信息、日志的标准化回复。把这五个动作分开设计的好处是每个动作的提示词可以独立调优每个动作的准确率可以独立评估出问题时能快速定位是哪个环节的判断偏了。如果把它们揉成一个帮我处理这条 Issue的大提示词你根本不知道错误出在哪一步。2.2 为什么不能让 AI 直接做最终决策这里有一个关键的设计原则AI 只做分诊不做裁决。分诊的意思是分门别类、给出建议裁决的意思是最终拍板。我坚持让 AI 的输出停留在建议层面所有标签的最终应用、Issue 的关闭、优先级的确认都需要人工点一下。原因很实际。AI 分类会犯错尤其是边界模糊的 Issue。比如一条这个功能在特定配置下表现异常的反馈它到底算 Bug 还是功能请求AI 可能给出一个合理但你不认同的判断。如果它直接自动打了标签、甚至自动关闭了 Issue一旦判错对提 Issue 的人来说体验极差对项目声誉也是伤害。而如果它只是给出一条建议分类为 Bug建议标签 bug/needs-repro建议优先级 P2的提示你扫一眼就能确认或修正效率提升依然巨大但风险几乎为零。提示把 AI 定位成给维护者省去第一遍阅读的助手而不是替代维护者做决定的系统这个定位决定了你整个架构的安全边界。2.3 分诊质量的天花板取决于仓库自身的数据质量这一点是我踩坑之后才深刻理解的。AI 分诊的准确率很大程度上不取决于你用了多强的模型而取决于你的仓库有没有清晰、一致、有历史沉淀的标签体系和 Issue 数据。如果一个仓库的标签只有默认的bug和enhancement两个历史 Issue 也从来没认真打过标签那 AI 就没有可参照的分类标准它只能凭通用常识去猜准确率自然上不去。反过来如果一个仓库有十几个语义清晰的标签历史 Issue 都规范地打过标签那你甚至可以把这些历史数据作为少样本示例喂给模型分诊准确率会明显提升。所以我在动手写代码之前先做了一件事梳理并规范化仓库的标签体系。把含义重叠的标签合并把从没用过的僵尸标签删掉给每个标签写一句清晰的适用说明。这一步看起来和 AI 无关但它直接决定了后面分诊效果的上限。3. 系统架构一条 Issue 进来之后发生了什么3.1 整体数据流与模块划分整个分诊助手的数据流可以这样理解Issue 创建事件触发 → 拉取 Issue 正文和元信息 → 预处理与去噪 → 调用分类模块 → 调用重复检测模块 → 调用优先级评估模块 → 生成回复草稿 → 汇总成一条分诊建议 → 推送给维护者确认。我把它拆成了四个核心模块。接入层负责监听 Issue 事件、拉取数据、做格式清洗。分析层是核心包含分类器、重复检测器、优先级评估器三个子模块。生成层负责把分析结果组织成人类可读的分诊建议和回复草稿。交互层负责把结果推送到维护者能看到的地方并接收人工确认反馈。这种分层的好处是每一层都可以独立替换。比如你一开始用规则做重复检测后来想换成向量相似度只需要替换分析层里的一个子模块其他部分不受影响。3.2 接入层怎么拿到干净的 Issue 文本接入层最容易被人忽视但它决定了后面所有分析的输入质量。Issue 正文里往往混着大量噪音用户贴的完整报错日志、大段代码块、截图链接、模板残留的占位文字、甚至是从别处复制来的无关内容。我的处理策略是保留结构、压缩体积。具体做法是把正文按 Markdown 结构解析识别出标题、段落、代码块、引用块。代码块如果超过一定长度只保留前若干行和总行数提示因为对分类判断来说代码块的存在和大致内容比完整内容更重要。模板占位文字比如请描述你的问题下面什么都没填直接剔除。最终拼成一段结构清晰、长度可控的文本送给模型。为什么要压缩因为模型的上下文窗口是有限的而且输入越长推理越慢、成本越高。一条 Issue 正文动辄几千字如果原样送进去既浪费又可能稀释关键信息。压缩到几百字的精华反而能让模型抓重点。3.3 分析层三个判断器如何协同分析层的三个判断器不是简单串行而是有依赖关系的。分类结果是重复检测和优先级评估的重要输入。比如一条被分类为使用咨询的 Issue优先级评估时就不应该给太高的级别而一条被分类为Bug且涉及核心功能的 Issue重复检测时就应该更严格地比对历史 Bug 类 Issue。我的实现方式是先跑分类器拿到分类和置信度然后把分类结果作为上下文分别喂给重复检测器和优先级评估器。重复检测器除了比对文本相似度还会参考分类结果缩小比对范围。优先级评估器则结合分类、正文中提到的关键词如崩溃数据丢失无法启动这类高严重度信号以及影响范围描述综合给出定级。三个判断器的输出最终汇总成一个结构化的 JSON包含分类、标签建议、优先级、重复候选列表、置信度。这个 JSON 就是生成层的输入。3.4 生成层与交互层让维护者一眼看懂生成层的任务是把冷冰冰的 JSON 变成维护者一眼能看懂的分诊卡片。我的卡片结构是这样的顶部一行是分类和优先级中间是标签建议和重复候选底部是回复草稿。回复草稿会根据 Issue 的信息完整度动态调整——如果用户没给复现步骤草稿就礼貌地索要复现步骤如果用户没给环境信息草稿就索要环境信息。交互层我选择把分诊卡片推送到维护者日常工作的沟通渠道里而不是让维护者去某个后台系统里看。因为维护者的注意力在哪里工具就应该出现在哪里。卡片上带确认和修正按钮维护者点一下就能应用标签、发送回复或者修正 AI 的判断。这些修正反馈会被记录下来成为后续优化提示词的宝贵数据。4. 提示词工程分诊准确率的真正战场4.1 分类提示词给模型一套清晰的判断标准分类是整个分诊的起点分类错了后面全错。我在这块提示词上花的功夫最多。核心思路是不要只告诉模型帮我分类而要给它一套明确的判断标准和边界说明。我的分类提示词大致包含这几块内容。第一块是角色设定告诉模型它是一个开源项目的 Issue 分诊助手需要严谨、保守拿不准时倾向于给出低置信度而不是强行分类。第二块是分类定义把每个类别的含义、典型特征、边界情况都写清楚。比如Bug 报告的定义是用户报告项目在特定条件下未按预期工作并明确如果用户只是问怎么用即使语气像在抱怨也应归为使用咨询。第三块是输出格式约束要求模型输出分类名称、置信度、判断理由三部分理由必须引用 Issue 中的具体文字。为什么要让模型输出理由因为理由是你调试提示词的抓手。当分类出错时看理由就能知道是模型理解错了类别定义还是 Issue 本身太模糊。如果只输出一个分类结果你根本无从下手优化。4.2 重复检测文本相似度不够还要语义理解重复检测是最容易做砸的模块。我一开始用简单的文本相似度算法结果发现两个用完全不同措辞描述同一个问题的 Issue相似度可能很低而两个措辞相似但实际问题不同的 Issue相似度反而很高。纯文本匹配根本不够用。后来我改成语义相似度加分类约束的方案。先用向量化模型把 Issue 正文转成向量计算余弦相似度筛出相似度超过阈值的候选集。然后把这个候选集连同当前 Issue 一起送给模型让模型判断这些候选里哪些是真正的重复。模型在判断时会考虑问题的本质是否相同而不是表面措辞。这里有个经验重复检测的候选集不要太大。如果一次给模型几十个候选它容易看花眼判断质量下降。我的做法是先按分类过滤再按向量相似度排序只取前几个最相似的候选送给模型精判。这样既保证了召回又控制了输入规模。4.3 优先级评估把模糊的严重程度变成可打分的维度优先级评估最难的地方在于严重是个主观词。不同维护者对同一个问题的严重程度判断可能完全不同。我的解法是把严重程度拆成几个可独立判断的维度每个维度给出明确的分档标准最后综合打分。我用的维度有三个。影响范围影响所有用户、影响部分用户、还是只影响特定边缘场景。功能重要性涉及核心功能、重要功能、还是次要功能。可绕过性用户有没有临时替代方案还是完全被阻塞。每个维度分三档组合起来映射到 P0 到 P3。这样拆的好处是模型不需要直接回答这有多严重这种模糊问题只需要回答三个相对具体的小问题每个小问题都有明确的判断依据。实测下来这种拆维度打分的方案比让模型直接给优先级要稳定得多不同 Issue 之间的定级也更一致。4.4 回复草稿礼貌、具体、可执行回复草稿的生成原则是礼貌但不啰嗦具体但不机械可执行但不居高临下。我见过太多项目用模板回复请提供更多信息这种回复对提 Issue 的人毫无帮助他根本不知道要提供什么。我的草稿会根据缺失的信息类型动态生成。如果缺复现步骤草稿会写为了帮你定位问题能否补充一下具体的操作步骤比如你执行了哪些操作、期望看到什么结果、实际看到了什么结果。如果缺环境信息草稿会列出需要的信息清单操作系统版本、项目版本、相关依赖版本。如果缺日志草稿会说明需要哪个环节的日志以及如何获取。草稿生成后不会自动发送而是作为建议呈现给维护者。维护者可以一键发送也可以修改后再发。这样既保证了回复的及时性和规范性又保留了人工把关的空间。5. 实测中暴露的问题与我的修正方案5.1 模型对边界模糊的 Issue 容易过度自信跑了一段时间后我发现一个规律模型对分类清晰的 Issue 判断很准但对边界模糊的 Issue它经常给出高置信度的错误判断。比如一条既像 Bug 又像功能请求的 Issue模型可能斩钉截铁地分成 Bug置信度还标得很高。这个问题很危险因为高置信度的错误判断会误导维护者。我的修正方案是在提示词里显式要求模型在遇到边界情况时降低置信度并给出具体的降级规则。比如如果一条 Issue 同时符合两个类别的特征置信度不应超过某个阈值并在理由中说明存在歧义。同时我在后处理逻辑里加了一条置信度低于阈值的分诊结果会被标记为需要人工重点确认在卡片上高亮显示。5.2 长 Issue 的关键信息被淹没有些用户提 Issue 时会把所有信息一股脑写进去正文长达几千字关键信息藏在中间某一段。模型处理这种长文本时容易抓不住重点分类和优先级判断都会受影响。我的应对是在预处理阶段做关键信息抽取。具体做法是先用一个轻量模型或规则从长正文中抽取出可能包含问题描述、复现步骤、环境信息、报错信息的段落把这些段落优先保留并放在送给模型文本的前面。这样即使正文很长关键信息也能出现在模型注意力的黄金位置。实测下来这个改动让长 Issue 的分类准确率有明显提升。5.3 重复检测的误报让人头疼重复检测最怕误报——把两个不重复的 Issue 判成重复然后建议关闭其中一个。这种误报对提 Issue 的人伤害很大他会觉得自己的问题被敷衍了。我踩过的坑是早期阈值设得太松导致大量误报。后来我做了两件事。一是提高判定门槛只有模型明确判断这两个 Issue 描述的是同一个根本问题时才标记为重复仅仅是相关或相似不算。二是把重复判定从自动建议降级为提示卡片上只显示可能与某 Issue 相关请人工确认绝不自动关闭。宁可漏报不可误报这是重复检测的铁律。5.4 不同仓库的标签体系差异导致提示词难以复用我一开始想做一个通用提示词结果发现不同仓库的标签体系差异太大一个仓库的bug标签含义和另一个仓库的完全不同。通用提示词在具体仓库上表现很差。后来我改成提示词模板加仓库配置的方案。提示词模板提供固定的框架和判断逻辑仓库配置提供该仓库特有的标签定义、分类标准、优先级规则。每次分诊时把仓库配置动态注入提示词模板。这样一套模板可以服务多个仓库每个仓库又有自己的定制化判断标准。这个改动让分诊助手从一个只能服务单个项目的工具变成了可以服务多个项目的平台。6. 如何评估分诊助手到底好不好用6.1 建立人工标注的评估集没有评估优化就是盲人摸象。我做的第一件事是从历史 Issue 中抽取一批样本人工标注正确的分类、标签、优先级作为评估集。样本要覆盖各种类型清晰的 Bug、模糊的边界情况、重复 Issue、无效内容、长文本 Issue每种都要有。评估集不需要很大但一定要有代表性。我用了大约一百条历史 Issue 做评估集覆盖了仓库里所有主要类别。每次调整提示词或更换模型后都在这套评估集上跑一遍对比准确率变化。这样每一次优化都有数据支撑而不是凭感觉。6.2 分模块评估而不是只看整体整体准确率会掩盖很多问题。比如整体准确率看起来不错但可能分类很准而优先级评估很差两者一平均就看不出来了。所以我坚持分模块评估分类准确率、重复检测的精确率和召回率、优先级评估与人工标注的一致率分别统计。分模块评估的好处是能精准定位短板。如果发现重复检测召回率低就知道要优化候选集生成如果优先级一致率低就知道要调整维度划分或分档标准。每个模块的优化方向完全不同混在一起评估根本无从下手。6.3 用真实反馈持续迭代评估集是静态的但真实世界的 Issue 是动态的。所以我特别重视维护者在实际使用中的修正反馈。每次维护者修正了 AI 的判断这条记录就被保存下来定期回顾。如果发现某类修正反复出现说明提示词在这类情况上有系统性偏差需要针对性优化。这个反馈闭环是分诊助手能持续变好的关键。一个上线后就不管的 AI 工具准确率只会随着项目演进而下降。只有把真实反馈接进来它才能跟着项目一起成长。7. 部署与成本控制的实际考量7.1 异步处理避免阻塞 Issue 创建流程分诊分析需要调用模型耗时从几秒到几十秒不等。如果同步处理用户提交 Issue 后要等很久才能看到创建成功体验很差。所以我把分诊做成异步任务Issue 创建后立即返回成功分诊在后台队列里慢慢跑跑完再把结果推送给维护者。异步架构还带来一个好处可以控制并发。模型调用有速率限制如果同时来一大批 Issue同步处理会直接撞上限制。异步队列可以平滑削峰按可控的速率消费任务。7.2 分级调用控制成本模型调用是要花钱的如果每条 Issue 都用最强模型全量分析成本会很高。我的策略是分级调用。先用一个轻量、便宜的模型做初步分类和置信度评估。如果置信度高、分类清晰就直接采用不再调用强模型。只有置信度低或分类模糊的 Issue才升级到强模型做精细分析。这个策略在保证准确率的同时把大部分简单 Issue 的处理成本压到了很低。实测下来大约七成的 Issue 可以用轻量模型搞定只有三成需要强模型介入整体成本下降明显。7.3 缓存与去重减少重复计算有些操作是重复的。比如同一个仓库的标签配置每次分诊都要用没必要每次都重新读取和拼接。我把这些静态配置做了缓存。另外如果同一条 Issue 因为某种原因被重复触发分诊可以用 Issue ID 做去重避免重复调用模型。这些优化单看都很小但累积起来对成本和响应速度的影响不小。工程上的事往往就是这些不起眼的细节决定了系统能不能长期稳定运行。8. 我在这件事上踩过的几个真实坑第一个坑是过早追求全自动。我一开始想着让 AI 全自动打标签、自动回复、自动关闭重复 Issue结果上线没几天就出了几次误判搞得提 Issue 的人很不满。后来退回到AI 建议、人工确认的模式效率提升依然明显但风险可控多了。这件事让我明白AI 应用落地信任是一点点建立的不是一步到位的。第二个坑是忽视冷启动问题。新仓库没有历史数据AI 没有可参照的分类标准分诊准确率很低。我的解法是给新仓库准备一套默认的标签体系和分类标准作为起点随着使用积累数据再逐步用真实数据优化。冷启动阶段不要期待太高准确率先把流程跑通让数据积累起来。第三个坑是提示词越改越复杂。有段时间我为了让模型处理各种边界情况不断往提示词里加规则结果提示词变得又长又乱模型反而更容易困惑。后来我做了减法把一些边缘规则移到后处理逻辑里用代码实现提示词只保留最核心的判断标准。提示词不是越长越好清晰比全面更重要。第四个坑是没有考虑多语言 Issue。项目国际化之后Issue 里混着好几种语言早期提示词只针对中文优化处理其他语言的 Issue 时准确率下降。后来我在提示词里明确要求模型用 Issue 本身的语言理解和判断输出则统一用维护者指定的语言这个问题才解决。9. 后续可以继续深挖的方向这套分诊助手跑通之后我发现它其实是一个更大的自动化体系的起点。往深了做有几个方向值得探索。一是从分诊延伸到初步定位。现在助手只告诉你这是一条 Bug优先级 P2未来可以进一步分析报错日志尝试定位可能出问题的模块甚至给出初步的排查建议。这对维护者来说价值更大。二是建立 Issue 与代码的关联。如果能把 Issue 描述的问题和代码仓库里的相关文件、函数关联起来维护者点开 Issue 就能直接跳到可能相关的代码位置省去大量搜索时间。三是把分诊数据反哺到项目决策。长期积累的分诊数据能反映出项目的痛点分布哪类问题最多、哪些功能最容易被误用、文档哪里最不清楚。这些洞察对项目路线规划很有价值是分诊助手带来的额外收益。四是做成可配置的通用平台。现在这套系统虽然支持多仓库配置但配置还需要手动写。未来可以做成可视化配置让不懂技术的维护者也能轻松接入自己的项目。我在实际使用中最大的体会是AI 在开源维护这类场景里的价值不在于替代人做判断而在于把人从重复的、低价值的认知劳动里解放出来让人把精力集中在真正需要创造力和深度思考的地方。分诊助手做的就是这样一件事——它不替你做决定但它让你做决定之前的那段准备时间从半小时缩短到几分钟。这个价值对于任何一个被 Issue 淹没的维护者来说都是实实在在的。