接手一个跑了六年的老服务第一周我就被日志里的错误码整懵了同一个“登录鉴权失败”的场景代码里同时出现了10001、ERROR_AUTH、AUTH_FAILED、2023AUTHFAIL四种写法。错误码体系混乱这事几乎每个中大型项目都绕不过去。代码里硬编码的魔法数字、各团队自创的英文缩写、文档里记的和线上跑的对不上……等到真要排查问题时光是在这些“数字/字符串/语义”之间做翻译就够喝一壶的。手动梳理一遍几百个错误码要逐一定义、归类、映射工作量大不说还容易漏。最近我试了一套借助AI来快速理顺的方法先把散落在代码、日志、接口文档里的错误码全部捞出来让模型做语义理解、聚类去重生成一份结构化的错误码字典再人工审核修正。实测下来比纯手工至少快一个数量级而且派生出的“标准码映射表”直接能用于日常排查和监控告警。这篇就聊聊这套玩法以及我踩过的坑适合后端开发、运维、技术负责人参考。1. 先别急着上 AI先给错误码“乱”建立坐标系1.1 错误码混乱的典型症状错误码体系乱起来的时候往往不是单一问题而是一连串问题叠加。最常见的症状是“一义多码”同一个业务语义在不同的模块里用了完全不同的表达。比如订单服务里“库存不足”用STOCK_NOT_ENOUGH支付服务里却用40010到了网关层又变成OUT_OF_STOCK。从用户角度来看都是“没货了”但系统层面各认各的码联调时没人说得清谁是谁。然后是“一码多义”同一个错误码在不同服务、不同版本里含义截然不同。我在某电商后台系统里见过20001在用户服务里表示“用户不存在”在优惠券服务里表示“优惠券已被领取完”。这种问题最危险因为日志聚合到一起时你按错误码搜出来的结果其实混合了好几种故障误判概率极高。还有一类是“无规则硬编码”。错误码的命名规则五花八门有纯数字的、有模块前缀加数字的、有全大写下划线风格、也有小驼峰风格。数字型错误码有些还带随机后缀比如时间戳尾巴导致真正去重时发现几万个候选。更别提那些写死在日志文案里的、连代码注释都没留下的远古错误码。1.2 为什么手动梳理容易翻车很多人第一反应是“搞个 Excel人工对一遍”。但真做起来会发现错误码散落在几十个仓库、几百个文件里先要全部找出来这一步就极其耗时。就算写脚本全扫一遍产出的候选集也可能会上千再靠肉眼逐条判断语义、归属模块、是否重复没个一两周根本下不来。更麻烦的是上下文缺失。一个错误码单独拎出来看很多时候根本不知道它是什么意思。比如某个模块返回-99这个数字在系统里毫无可读性必须回到抛出它的代码位置、看看周围的日志和变量才能判断。手动整理就意味着要去翻源码、翻 Git 历史甚至去问已经离职的同事“这个码是干嘛的”。纯手工流程还很难避免口径不一致。整理的人和审核的人对“标准错误码应该长什么样”可能有不同理解最后产出的规范文档经常刚发布就过时了。这个阶段最适合引入 AI它不擅长做最终决策但特别擅长把凌乱的信息先“洗”一遍给出候选聚合结果再由人来拍板。把 AI 当作筛子和翻译官而不是最终审判者。2. 用 AI 理顺错误码的整体思路从“清洗”到“映射”再到“闸口”2.1 核心目标建立一份可直接使用的错误码矩阵我给自己定的目标是最终产出一张“错误码矩阵表”每一行包含字段说明original_code原始错误码可能是数字、字符串、缩写source_location从哪个文件/哪个服务/哪段日志捕获standard_code标准化后的错误码遵循统一规则semantic_label业务语义标签比如“用户不存在”“库存不足”module所属服务或模块severity影响级别比如致命/警告/提示status状态新增、待迁移、已废弃、冲突待确认suggestion修复建议或迁移路径有了这张表后续不管是做日志平台告警、API 规范设计还是统一异常处理中间件都有了一个靠谱的数据底座。AI 在这个过程里负责的是从“杂乱的原始码集合”到“候选结构化记录”的转换而不是凭空创造规范。2.2 AI 的角色划分哪些环节用 AI哪些必须人工用 AI 之前先把边界划清楚。我建议把 AI 放在这几个环节候选错误码发现与清洗用代码扫描辅助模型识别“疑似错误码”过滤掉明显不是错误码的数字常量。语义聚类把散落但表达同一含义的错误码聚到同一个簇里帮助发现重复定义。标准化名称生成根据语义为每个错误码生成符合命名规范的建议值。冲突检测找出“一码多义”的高危错误码标注为待人工确认。必须人工参与的环节有两个一是业务语义的最终确认二是代码迁移决策。AI 判断出“这两个码大概率是一个意思”但到底要不要合并、合并后是否影响外部依赖只能由熟悉业务的人来决定。另外涉及对外 API 契约的错误码任何改动都可能破坏客户端兼容性这种变更必须走评审不能直接让模型改。把 AI 定位成“加速器”而不是“自动驾驶”整个项目的风险会低很多。3. 实操把一套散落的错误码整理成结构化字典3.1 从代码和日志里先把“错误码种子”收集齐动手第一步是收集原始素材。这里不能只靠人工翻得用脚本先扫一遍代码仓库和日志样本。我习惯先用 Python 扫仓库里常见的源码文件把字符串和数字常量提取出来。重点正则两类大写字符串风格[A-Z][A-Z0-9_]{2,}纯数字风格\b\d{3,5}\b但直接扫会有大量噪音比如数据库 ID、超时时间、端口号。所以我会再加一个朴素的黑名单过滤排除常见的非错误码语义关键词比如timeout、retry、port、count、total等。下面这个脚本片段是我在实际项目里用的简化版用来收集候选错误码及其文件位置import re from pathlib import Path pattern_str re.compile(r\b([A-Z][A-Z0-9_]{2,})\b) pattern_num re.compile(r\b(\d{3,5})\b) skip_words {HTTP, JSON, HTML, PORT, COUNT, TOTAL, TIMEOUT} candidates {} for path in Path(./src).rglob(*): if path.suffix not in {.py, .java, .go, .js, .ts}: continue code path.read_text(errorsignore) for match in pattern_str.finditer(code): val match.group(1) if val in skip_words: continue candidates.setdefault(val, set()).add(str(path)) for match in pattern_num.finditer(code): # 数字单独拎出来后面交给大模型判断 val match.group(1) candidates.setdefault(val, set()).add(str(path)) with open(error_code_candidates.txt, w, encodingutf-8) as f: for code, files in sorted(candidates.items()): f.write(f{code}\t{|.join(sorted(files))}\n)这一步输出的“候选清单”只保证覆盖度不保证准确率。接下来再补一个数据源线上日志里的错误码字段。可以从近一个月的日志里抓取带code、error_code、code:这类键的值和仓库扫描结果做一次并集。经验补充日志里的错误码经常带着随机参数或者时间戳会膨胀候选集。我的做法是把长度大于 32 的字符串候选先剔除再按“高频出现”排序只保留出现次数不低于 3 的候选能去掉大量杂音。3.2 用大模型做语义聚类和规范化素材收集完接下来就是 AI 主战场。我试验过两条路线各有适用场景。路线一直接让大模型批量分析。适合候选集在几百量级、且每个错误码都能附带一些上下文的情况。把错误码列表和它们出现的文件路径一起组织成 JSON一次性塞给模型让它输出聚类结果和标准化建议。我用的 Prompt 模板大致是这个样子你是一个错误码治理专家。下面是从某后端系统中提取的错误码候选列表每个条目包含 - code: 原始错误码 - context: 出现该错误码的文件或日志片段 请完成以下任务 1. 筛选出真正属于错误码的条目排除明显是普通数字常量或随机字符串的条目。 2. 对剩下的错误码做语义聚类每一簇表示“很可能是同一业务含义”。 3. 为每一簇给出一个 recommended_code命名规则为模块缩写_业务关键词全大写下划线分隔。 4. 输出JSON不要输出额外解释。 输入列表 {your_json_list}这里有个很重要的细节context字段不能只放文件路径最好放一小段代码上下文。因为很多错误码本身没有语义比如-99必须结合抛出它的那几行代码才能判断。我在采集阶段会让脚本额外抓取匹配位置前后 3 行内容作为上下文一并喂给模型。实测下来GPT 级别的模型对聚类的准确率能有七八成但偶尔会“过度归纳”把两个看似相近、实际语义不同的错误码合并成一个。所以 AI 的分组结果只能作为“候选簇”后续必须由人工过一遍。路线二向量化 聚类。当候选错误码数量上千或者你希望不依赖外部 API、完全在本地完成预处理时可以用 Embedding 模型把错误码和上下文转成向量再用聚类算法给它们分组。实现思路不复杂from sentence_transformers import SentenceTransformer from sklearn.cluster import DBSCAN model SentenceTransformer(BAAI/bge-small-zh) texts [f{code} | {context} for code, context in candidates] embeddings model.encode(texts, normalize_embeddingsTrue) clustering DBSCAN(eps0.35, min_samples2, metriccosine) labels clustering.fit_predict(embeddings)DBSCAN的好处是不用提前指定簇数量适合这种“不知道到底有多少种错误”的场景。eps参数需要微调一般从 0.3 开始试簇太多就调大簇太少就调小。聚类完成后每个簇再交给大模型生成一个标准错误码名称。我自己实际用下来路线一的效果更贴合人类直觉适合快速出草稿路线二适合在候选集特别大时先做粗筛把明显重复的合并掉减少后续 Prompt 的输入量。3.3 生成映射关系和迁移建议聚类完成只是理顺了一半。接下来要基于簇生成“原始错误码 → 标准错误码 → 建议操作”的映射关系。这一步我通常让 AI 按簇输出结构化建议{ cluster_id: 1, original_codes: [10001, ERROR_AUTH, AUTH_FAILED], semantic_label: 用户认证失败, recommended_code: USER_AUTH_FAILED, conflict_codes: [], suggestion: 建议在各服务统一使用USER_AUTH_FAILED废弃其余写法, severity: warning }需要特别盯紧conflict_codes字段也就是“同一个错误码被不同模块赋予了不同含义”的情况。这种冲突 AI 不一定能精准发现因为它需要跨模块去比较语义。我的做法是在 Prompt 里增加一个指令如果你发现同一个 code 出现在语义明显不同的上下文里请单独标记为冲突不要自动归并。然后人工再重点看这些冲突码。得到映射表后还要把“原始错误码出现的文件列表”一并保留下来这样后续做代码迁移时可以按图索骥而不是靠 grep 全仓库搜。3.4 人工复核流程把 AI 的结果变成可落地的规范AI 输出的初稿不能直接当规范发至少要过三轮确认第一轮业务语义复核。把聚类结果发给各模块负责人请他们确认“原始码 A 和 B 是否同一语义”。这一步可以做成简单的问卷列出“簇内成员”和“AI 给出的标签”让负责人打对勾或修正。第二轮命名规范评审。确认标准码的命名风格统一。比如规定所有错误码必须遵循模块_业务_状态的格式状态只能是FAILED、NOT_FOUND、INVALID、TIMEOUT等有限集合。AI 生成的recommended_code如果不符合规范要打回去重写。第三轮风险分级。判断每个错误码是否涉及对外接口。涉及客户端的迁移要考虑兼容性只在服务内部使用的可以放开手脚统一改。这些决策都记录到错误码矩阵表的status字段里。我习惯在项目里建一个error_code_registry.csv作为最终的唯一事实来源Source of Truth。后续每次代码变更涉及错误码时都要求同步更新这张表。这样才算真正“理顺”了。4. 踩过的坑和排查技巧4.1 AI 幻觉编造不存在的错误码我第一次跑大模型批量分析时收到一份看起来很专业的输出里面居然出现了系统里根本没有的ERR_BIZ_404。模型不是故意的它就是“顺着意思”补了一个看起来合理的名字。应对方法很土但也有效所有 AI 给出的错误码名称必须能在“候选集合”里找到来源。我要求模型输出时带一个source_codes字段列明自己依据了哪些原始错误码。如果某个推荐码对应的原始码为空直接判为无效。同时在 Prompt 里明确写“禁止引入未出现在输入列表中的错误码”。另外不要用 AI 直接生成“需要修改的代码”只让它生成“映射表和迁移建议”。代码层面的改动用最传统的方式完成反而安全。4.2 上下文不足导致误判缺少业务语境的错有一批错误码4001、4002从表面看只是数字AI 凭借上下文猜测为“参数错误”但实际业务里4001代表“余额不足”4002代表“无权限”。光看变量名根本判断不了。解决这个问题的关键是给足上下文。我在采集脚本里不仅抓错误码本身还会抓它所在的函数名、类名、周边注释以及最近的日志文案。比如日志里出现{code: 4001, msg: insufficient balance}这种结构直接整段喂给模型准确率会高很多。如果上下文仍然不够就保留为“未知语义”如实标注交给人工排查。不用强求 AI 给出一个看似准确的答案。4.3 历史“沼泽”代码的防坑技巧有些老代码里的错误码定义很迷惑比如一个常量叫PARAM_ERR实际值是0另一个地方硬编码-1注释写“未知错误”。如果你把所有数字常量都喂给 AI它会把系统里被无数地方使用的0和-1也当成错误码导致聚类结果一片混乱。我的过滤器里加了一条规则排除出现频率过高的通用常量。如果某个候选错误码在文件里出现超过 200 次大概率不是错误码而是公共状态值。另外一个 bug 是编码不一致错误码定义文件和引用文件用了不同的注释风格导致 AI 读上下文时漏掉关键信息。解决办法是写脚本把注释内容也提取出来连同代码一起给模型而不是只给一行字符串。4.4 落地后的验证在测试和监控里加篱笆错误码理顺之后最怕的是过两个月又乱回来。我会在项目里做三道防护第一道代码提交检查。在 CI 里加一个简单脚本扫描本次提交涉及的代码如果出现新的字符串错误码或者数字错误码但error_code_registry.csv里没有对应记录就自动打回。小团队人力不足时至少加一个 warning。第二道单元测试断言。针对统一异常处理函数写死标准错误码映射的测试。谁改了映射关系测试立刻红掉。第三道监控告警。在日志采集侧增加一个“未注册错误码”的统计看板每天跑一遍把新出现的、没登记的错误码列出来。这样即使团队后来变了也能及时发现体系又在腐化。5. 这套方法的适用范围与后续扩展5.1 适合与不适合的场景这套“AI 辅助梳理错误码”的方法最适合历史包袱重、错误码散落多仓库、且团队人力不充裕的场景。我是在一个中等规模的后端系统上验证的效果很明显。如果错误码只有几十个人工整理也很快没必要上模型。不适合的场景主要有两类一类是错误码涉及强外部契约且变更需要严格流程这时 AI 最多只能做参考主导权必须全部压到评审流程上另一类是敏感业务数据不能出内网而团队又没有本地模型的部署条件这时需要先解决数据合规问题。5.2 可以扩展的能力这个思路往后还能延伸不少。比如基于整理好的错误码字典做“智能异常分析”日志平台里出现一个未登记的原始错误码时自动提示最接近的标准码和历史解决办法。还可以结合代码库的历史提交记录让 AI 学习“错误码是怎么演化的”找出废弃原因和替代路径。对我个人来说这次实践最大的收获不是那几张表而是想清楚了一件事AI 处理“混乱”数据的能力比想象中强得多只要把边界和验证机制定好它可以成为手里最好用的清洗工具。以后再遇到其他领域的混乱信息整理我大概率还会用同样的套路先收集、再聚类、生成候选、人工确认、固化流程。这套循环比“上 AI 全自动改代码”稳妥太多。 
长河君 · 2026/10/21 14:25:07 · 阅读 1.2k AI辅助错误码治理：从千头万绪到标准化的实战指南
接手一个跑了六年的老服务第一周我就被日志里的错误码整懵了同一个“登录鉴权失败”的场景代码里同时出现了10001、ERROR_AUTH、AUTH_FAILED、2023AUTHFAIL四种写法。错误码体系混乱这事几乎每个中大型项目都绕不过去。代码里硬编码的魔法数字、各团队自创的英文缩写、文档里记的和线上跑的对不上……等到真要排查问题时光是在这些“数字/字符串/语义”之间做翻译就够喝一壶的。手动梳理一遍几百个错误码要逐一定义、归类、映射工作量大不说还容易漏。最近我试了一套借助AI来快速理顺的方法先把散落在代码、日志、接口文档里的错误码全部捞出来让模型做语义理解、聚类去重生成一份结构化的错误码字典再人工审核修正。实测下来比纯手工至少快一个数量级而且派生出的“标准码映射表”直接能用于日常排查和监控告警。这篇就聊聊这套玩法以及我踩过的坑适合后端开发、运维、技术负责人参考。1. 先别急着上 AI先给错误码“乱”建立坐标系1.1 错误码混乱的典型症状错误码体系乱起来的时候往往不是单一问题而是一连串问题叠加。最常见的症状是“一义多码”同一个业务语义在不同的模块里用了完全不同的表达。比如订单服务里“库存不足”用STOCK_NOT_ENOUGH支付服务里却用40010到了网关层又变成OUT_OF_STOCK。从用户角度来看都是“没货了”但系统层面各认各的码联调时没人说得清谁是谁。然后是“一码多义”同一个错误码在不同服务、不同版本里含义截然不同。我在某电商后台系统里见过20001在用户服务里表示“用户不存在”在优惠券服务里表示“优惠券已被领取完”。这种问题最危险因为日志聚合到一起时你按错误码搜出来的结果其实混合了好几种故障误判概率极高。还有一类是“无规则硬编码”。错误码的命名规则五花八门有纯数字的、有模块前缀加数字的、有全大写下划线风格、也有小驼峰风格。数字型错误码有些还带随机后缀比如时间戳尾巴导致真正去重时发现几万个候选。更别提那些写死在日志文案里的、连代码注释都没留下的远古错误码。1.2 为什么手动梳理容易翻车很多人第一反应是“搞个 Excel人工对一遍”。但真做起来会发现错误码散落在几十个仓库、几百个文件里先要全部找出来这一步就极其耗时。就算写脚本全扫一遍产出的候选集也可能会上千再靠肉眼逐条判断语义、归属模块、是否重复没个一两周根本下不来。更麻烦的是上下文缺失。一个错误码单独拎出来看很多时候根本不知道它是什么意思。比如某个模块返回-99这个数字在系统里毫无可读性必须回到抛出它的代码位置、看看周围的日志和变量才能判断。手动整理就意味着要去翻源码、翻 Git 历史甚至去问已经离职的同事“这个码是干嘛的”。纯手工流程还很难避免口径不一致。整理的人和审核的人对“标准错误码应该长什么样”可能有不同理解最后产出的规范文档经常刚发布就过时了。这个阶段最适合引入 AI它不擅长做最终决策但特别擅长把凌乱的信息先“洗”一遍给出候选聚合结果再由人来拍板。把 AI 当作筛子和翻译官而不是最终审判者。2. 用 AI 理顺错误码的整体思路从“清洗”到“映射”再到“闸口”2.1 核心目标建立一份可直接使用的错误码矩阵我给自己定的目标是最终产出一张“错误码矩阵表”每一行包含字段说明original_code原始错误码可能是数字、字符串、缩写source_location从哪个文件/哪个服务/哪段日志捕获standard_code标准化后的错误码遵循统一规则semantic_label业务语义标签比如“用户不存在”“库存不足”module所属服务或模块severity影响级别比如致命/警告/提示status状态新增、待迁移、已废弃、冲突待确认suggestion修复建议或迁移路径有了这张表后续不管是做日志平台告警、API 规范设计还是统一异常处理中间件都有了一个靠谱的数据底座。AI 在这个过程里负责的是从“杂乱的原始码集合”到“候选结构化记录”的转换而不是凭空创造规范。2.2 AI 的角色划分哪些环节用 AI哪些必须人工用 AI 之前先把边界划清楚。我建议把 AI 放在这几个环节候选错误码发现与清洗用代码扫描辅助模型识别“疑似错误码”过滤掉明显不是错误码的数字常量。语义聚类把散落但表达同一含义的错误码聚到同一个簇里帮助发现重复定义。标准化名称生成根据语义为每个错误码生成符合命名规范的建议值。冲突检测找出“一码多义”的高危错误码标注为待人工确认。必须人工参与的环节有两个一是业务语义的最终确认二是代码迁移决策。AI 判断出“这两个码大概率是一个意思”但到底要不要合并、合并后是否影响外部依赖只能由熟悉业务的人来决定。另外涉及对外 API 契约的错误码任何改动都可能破坏客户端兼容性这种变更必须走评审不能直接让模型改。把 AI 定位成“加速器”而不是“自动驾驶”整个项目的风险会低很多。3. 实操把一套散落的错误码整理成结构化字典3.1 从代码和日志里先把“错误码种子”收集齐动手第一步是收集原始素材。这里不能只靠人工翻得用脚本先扫一遍代码仓库和日志样本。我习惯先用 Python 扫仓库里常见的源码文件把字符串和数字常量提取出来。重点正则两类大写字符串风格[A-Z][A-Z0-9_]{2,}纯数字风格\b\d{3,5}\b但直接扫会有大量噪音比如数据库 ID、超时时间、端口号。所以我会再加一个朴素的黑名单过滤排除常见的非错误码语义关键词比如timeout、retry、port、count、total等。下面这个脚本片段是我在实际项目里用的简化版用来收集候选错误码及其文件位置import re from pathlib import Path pattern_str re.compile(r\b([A-Z][A-Z0-9_]{2,})\b) pattern_num re.compile(r\b(\d{3,5})\b) skip_words {HTTP, JSON, HTML, PORT, COUNT, TOTAL, TIMEOUT} candidates {} for path in Path(./src).rglob(*): if path.suffix not in {.py, .java, .go, .js, .ts}: continue code path.read_text(errorsignore) for match in pattern_str.finditer(code): val match.group(1) if val in skip_words: continue candidates.setdefault(val, set()).add(str(path)) for match in pattern_num.finditer(code): # 数字单独拎出来后面交给大模型判断 val match.group(1) candidates.setdefault(val, set()).add(str(path)) with open(error_code_candidates.txt, w, encodingutf-8) as f: for code, files in sorted(candidates.items()): f.write(f{code}\t{|.join(sorted(files))}\n)这一步输出的“候选清单”只保证覆盖度不保证准确率。接下来再补一个数据源线上日志里的错误码字段。可以从近一个月的日志里抓取带code、error_code、code:这类键的值和仓库扫描结果做一次并集。经验补充日志里的错误码经常带着随机参数或者时间戳会膨胀候选集。我的做法是把长度大于 32 的字符串候选先剔除再按“高频出现”排序只保留出现次数不低于 3 的候选能去掉大量杂音。3.2 用大模型做语义聚类和规范化素材收集完接下来就是 AI 主战场。我试验过两条路线各有适用场景。路线一直接让大模型批量分析。适合候选集在几百量级、且每个错误码都能附带一些上下文的情况。把错误码列表和它们出现的文件路径一起组织成 JSON一次性塞给模型让它输出聚类结果和标准化建议。我用的 Prompt 模板大致是这个样子你是一个错误码治理专家。下面是从某后端系统中提取的错误码候选列表每个条目包含 - code: 原始错误码 - context: 出现该错误码的文件或日志片段 请完成以下任务 1. 筛选出真正属于错误码的条目排除明显是普通数字常量或随机字符串的条目。 2. 对剩下的错误码做语义聚类每一簇表示“很可能是同一业务含义”。 3. 为每一簇给出一个 recommended_code命名规则为模块缩写_业务关键词全大写下划线分隔。 4. 输出JSON不要输出额外解释。 输入列表 {your_json_list}这里有个很重要的细节context字段不能只放文件路径最好放一小段代码上下文。因为很多错误码本身没有语义比如-99必须结合抛出它的那几行代码才能判断。我在采集阶段会让脚本额外抓取匹配位置前后 3 行内容作为上下文一并喂给模型。实测下来GPT 级别的模型对聚类的准确率能有七八成但偶尔会“过度归纳”把两个看似相近、实际语义不同的错误码合并成一个。所以 AI 的分组结果只能作为“候选簇”后续必须由人工过一遍。路线二向量化 聚类。当候选错误码数量上千或者你希望不依赖外部 API、完全在本地完成预处理时可以用 Embedding 模型把错误码和上下文转成向量再用聚类算法给它们分组。实现思路不复杂from sentence_transformers import SentenceTransformer from sklearn.cluster import DBSCAN model SentenceTransformer(BAAI/bge-small-zh) texts [f{code} | {context} for code, context in candidates] embeddings model.encode(texts, normalize_embeddingsTrue) clustering DBSCAN(eps0.35, min_samples2, metriccosine) labels clustering.fit_predict(embeddings)DBSCAN的好处是不用提前指定簇数量适合这种“不知道到底有多少种错误”的场景。eps参数需要微调一般从 0.3 开始试簇太多就调大簇太少就调小。聚类完成后每个簇再交给大模型生成一个标准错误码名称。我自己实际用下来路线一的效果更贴合人类直觉适合快速出草稿路线二适合在候选集特别大时先做粗筛把明显重复的合并掉减少后续 Prompt 的输入量。3.3 生成映射关系和迁移建议聚类完成只是理顺了一半。接下来要基于簇生成“原始错误码 → 标准错误码 → 建议操作”的映射关系。这一步我通常让 AI 按簇输出结构化建议{ cluster_id: 1, original_codes: [10001, ERROR_AUTH, AUTH_FAILED], semantic_label: 用户认证失败, recommended_code: USER_AUTH_FAILED, conflict_codes: [], suggestion: 建议在各服务统一使用USER_AUTH_FAILED废弃其余写法, severity: warning }需要特别盯紧conflict_codes字段也就是“同一个错误码被不同模块赋予了不同含义”的情况。这种冲突 AI 不一定能精准发现因为它需要跨模块去比较语义。我的做法是在 Prompt 里增加一个指令如果你发现同一个 code 出现在语义明显不同的上下文里请单独标记为冲突不要自动归并。然后人工再重点看这些冲突码。得到映射表后还要把“原始错误码出现的文件列表”一并保留下来这样后续做代码迁移时可以按图索骥而不是靠 grep 全仓库搜。3.4 人工复核流程把 AI 的结果变成可落地的规范AI 输出的初稿不能直接当规范发至少要过三轮确认第一轮业务语义复核。把聚类结果发给各模块负责人请他们确认“原始码 A 和 B 是否同一语义”。这一步可以做成简单的问卷列出“簇内成员”和“AI 给出的标签”让负责人打对勾或修正。第二轮命名规范评审。确认标准码的命名风格统一。比如规定所有错误码必须遵循模块_业务_状态的格式状态只能是FAILED、NOT_FOUND、INVALID、TIMEOUT等有限集合。AI 生成的recommended_code如果不符合规范要打回去重写。第三轮风险分级。判断每个错误码是否涉及对外接口。涉及客户端的迁移要考虑兼容性只在服务内部使用的可以放开手脚统一改。这些决策都记录到错误码矩阵表的status字段里。我习惯在项目里建一个error_code_registry.csv作为最终的唯一事实来源Source of Truth。后续每次代码变更涉及错误码时都要求同步更新这张表。这样才算真正“理顺”了。4. 踩过的坑和排查技巧4.1 AI 幻觉编造不存在的错误码我第一次跑大模型批量分析时收到一份看起来很专业的输出里面居然出现了系统里根本没有的ERR_BIZ_404。模型不是故意的它就是“顺着意思”补了一个看起来合理的名字。应对方法很土但也有效所有 AI 给出的错误码名称必须能在“候选集合”里找到来源。我要求模型输出时带一个source_codes字段列明自己依据了哪些原始错误码。如果某个推荐码对应的原始码为空直接判为无效。同时在 Prompt 里明确写“禁止引入未出现在输入列表中的错误码”。另外不要用 AI 直接生成“需要修改的代码”只让它生成“映射表和迁移建议”。代码层面的改动用最传统的方式完成反而安全。4.2 上下文不足导致误判缺少业务语境的错有一批错误码4001、4002从表面看只是数字AI 凭借上下文猜测为“参数错误”但实际业务里4001代表“余额不足”4002代表“无权限”。光看变量名根本判断不了。解决这个问题的关键是给足上下文。我在采集脚本里不仅抓错误码本身还会抓它所在的函数名、类名、周边注释以及最近的日志文案。比如日志里出现{code: 4001, msg: insufficient balance}这种结构直接整段喂给模型准确率会高很多。如果上下文仍然不够就保留为“未知语义”如实标注交给人工排查。不用强求 AI 给出一个看似准确的答案。4.3 历史“沼泽”代码的防坑技巧有些老代码里的错误码定义很迷惑比如一个常量叫PARAM_ERR实际值是0另一个地方硬编码-1注释写“未知错误”。如果你把所有数字常量都喂给 AI它会把系统里被无数地方使用的0和-1也当成错误码导致聚类结果一片混乱。我的过滤器里加了一条规则排除出现频率过高的通用常量。如果某个候选错误码在文件里出现超过 200 次大概率不是错误码而是公共状态值。另外一个 bug 是编码不一致错误码定义文件和引用文件用了不同的注释风格导致 AI 读上下文时漏掉关键信息。解决办法是写脚本把注释内容也提取出来连同代码一起给模型而不是只给一行字符串。4.4 落地后的验证在测试和监控里加篱笆错误码理顺之后最怕的是过两个月又乱回来。我会在项目里做三道防护第一道代码提交检查。在 CI 里加一个简单脚本扫描本次提交涉及的代码如果出现新的字符串错误码或者数字错误码但error_code_registry.csv里没有对应记录就自动打回。小团队人力不足时至少加一个 warning。第二道单元测试断言。针对统一异常处理函数写死标准错误码映射的测试。谁改了映射关系测试立刻红掉。第三道监控告警。在日志采集侧增加一个“未注册错误码”的统计看板每天跑一遍把新出现的、没登记的错误码列出来。这样即使团队后来变了也能及时发现体系又在腐化。5. 这套方法的适用范围与后续扩展5.1 适合与不适合的场景这套“AI 辅助梳理错误码”的方法最适合历史包袱重、错误码散落多仓库、且团队人力不充裕的场景。我是在一个中等规模的后端系统上验证的效果很明显。如果错误码只有几十个人工整理也很快没必要上模型。不适合的场景主要有两类一类是错误码涉及强外部契约且变更需要严格流程这时 AI 最多只能做参考主导权必须全部压到评审流程上另一类是敏感业务数据不能出内网而团队又没有本地模型的部署条件这时需要先解决数据合规问题。5.2 可以扩展的能力这个思路往后还能延伸不少。比如基于整理好的错误码字典做“智能异常分析”日志平台里出现一个未登记的原始错误码时自动提示最接近的标准码和历史解决办法。还可以结合代码库的历史提交记录让 AI 学习“错误码是怎么演化的”找出废弃原因和替代路径。对我个人来说这次实践最大的收获不是那几张表而是想清楚了一件事AI 处理“混乱”数据的能力比想象中强得多只要把边界和验证机制定好它可以成为手里最好用的清洗工具。以后再遇到其他领域的混乱信息整理我大概率还会用同样的套路先收集、再聚类、生成候选、人工确认、固化流程。这套循环比“上 AI 全自动改代码”稳妥太多。