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 淹没的维护者来说，都是实实在在的。
