企业智能体工程体系v1.1企业智能体工程卷 · 第6期一次重写——结构混乱时高质量重构优于反复补丁作者技术治理研究组系列企业智能体工程卷发布版 v1.1主案例CASE-CR-0042信用提额申请本集对象Skill 结构重构 · 路由分类核心协议P5 重写例外适合读者架构师、技术负责人、AI 产品经理、企业级 Agent 开发者 本文档声明性质本文为企业智能体工程化设计参考框架的第 6 期聚焦 Agent 技能代码的结构性腐烂与重构决策提供架构思路与教学级示意代码不构成生产级实现方案或法律合规意见。证据锚定文中案例CASE-CR-0042为教学示意不对应任何真实客户系统。系列定位本篇在第 5 期数据飞轮的基础上引入P5 一次重写协议为 Agent 系统建立“何时修、何时拆”的结构化决策框架。摘要在第 5 期中我们建立了MAPE 飞轮 P3 协议——让 Agent 系统通过观测、分析、计划、执行的闭环持续改进。但有一个问题飞轮解决不了当技能代码本身已经腐烂到“修不动”的时候飞轮只是在放大混乱。CASE-CR-0042 的路由技能经过无数轮“小补丁”后变成了这样if 账单: → 账单查询 if 账单 and 发票: → 票据问题 if 退款: → 退款 if 退款 and 额度: → 一般咨询 # 腐点与前两条互殴分支互殴、语义漂移、无人敢动。飞轮若继续在上面调权重、加规则只是更快地放大混乱而非解决问题。本期回答一个核心问题什么情况下“小补丁”必须停止改为“一次重写”本期引入P5 重写例外协议——当结构已腐、语义已漂移时禁止继续堆补丁必须走一次重写。重写结果仍须通过 P3 Assurance 验收不得因“单测绿了”直推生产。一句话核心腐结构不热修热修不代重构。1. 问题补丁堆到“修不动”的时候飞轮也没用1.1 一个典型的“补丁堆”案例CASE-CR-0042 的路由技能经历了12 个月、17 次补丁后的真实状态版本变更内容问题v1.0基础分类账单、发票、退款、额度结构清晰v2.0增加“账单 and 发票”识别第一条 if 开始重叠v3.0增加“退款 and 额度”特殊处理开始互殴v4.0增加“信用”关键词语义扩张v5.0-v17.012 个月新增 13 个 if 分支无人敢动最终形态defclassify(text:str)-str:label一般咨询if账单intext:label账单查询if发票intext:label票据问题if退款intext:label退款if额度intextor信用intext:label额度申请if退款intextand额度intext:# 腐点互殴label一般咨询if账单intextand信用notintext:# 腐点过时规则label账单查询returnlabel测试结果输入预期实际问题“我要提额”额度申请额度申请✅“我要退款”退款退款✅“提额顺便问退款”额度申请一般咨询❌ 互殴导致误判“信用额度”额度申请一般咨询❌ 条件覆盖不全1.2 为什么“飞轮”解决不了这个问题第 5 期的 MAPE 飞轮能在当前结构下优化权重飞轮环节在腐结构上的效果Monitor能看到误标率上升 ✅Analyze能定位到“退款 and 额度”组 ❌ 但归因困难Plan能建议调整关键词权重 ⚠️ 但治标不治本Execute能发布新权重 ⚠️ 但可能在更混乱的结构上放大误差飞轮的局限性飞轮优化的是参数不是结构。当结构本身已经腐烂时飞轮只是在“加速放大混乱”。1.3 决定重写的三个信号信号说明CASE-CR-0042 现状分支互殴不同 if 分支给出矛盾结果✅ “退款 and 额度”与“额度”分支互殴语义漂移关键词含义已偏离原始设计✅ “信用”从“信用额度”漂移到“信用评级”无人敢动修改一处怕坏三处✅ 17 次补丁后无人愿重构当上述三个信号同时出现时就是 P5 的触发条件。2. 一次重写 vs 小补丁决策框架2.1 P5 决策树是是否否是否发现缺陷结构是否清晰单点缺陷且证据明确小补丁修复走 P3 飞轮优化权重是否出现分支互殴/语义漂移✅ P5 一次重写结构整理 小补丁交付物新规则表 回归集 回滚开关走 P3 Assurance 验收发布到生产2.2 策略对照表策略适用场景不适用场景示例小补丁结构清晰、单点缺陷、证据明确分支互殴、语义漂移修复一个关键词的误匹配P3 飞轮参数需要优化、权重需调整结构已腐调整“额度”关键词的权重P5 重写分支互殴、语义漂移、无人敢动结构清晰、单点小缺陷路由分类从 if 堆迁移到规则表P4 热修生产阻断紧急修复任何形式的“大重构”生产环境分类全部失效P5 口诀腐结构不热修热修不代重构。3. 协议 P5重写例外3.1 P5 规则规则说明结构仍清晰允许小补丁可走 P4 若生产阻断结构已腐 / 语义漂移必须一次重写禁止继续堆 if重写交付物新规则表/契约 回归集 回滚开关与 P3 的关系重写结果仍是 Plan须 Assurance 后发布与 P4 的关系Hotfix-8h不得用于“大重构上生产”3.2 P5 与 P3、P4 的关系常规改进走此通道重写结果仍是 Plan快速止血❌ 不得P3 飞轮验收生产环境P5 一次重写P4 热修 8h维度P3飞轮P4热修P5重写适用场景参数优化、常规改进生产阻断、紧急止血结构腐烂、必须重写时效按周期迭代8 小时内按计划执行评审要求完整 Assurance最小范围 双人复核完整 Assurance 回归集回滚要求标准回滚路径8h 内补证否则回滚回滚开关 灰度发布P5 与 P4 的本质区别P4 是“生产着火了”先灭火8h 内补证再复盘P5 是“房子结构有问题”拆了重建完整规划 回归 验收再搬进去4. CASE-CR-0042 重写目标4.1 保留的语义类别关键词优先级标签额度申请额度、信用、提额、授信100最高额度申请退款退款、退钱、退货90退款票据发票、税票80票据问题账单账单、流水、明细70账单查询4.2 去掉的“腐点”腐点原代码新方案分支互殴if 退款 and 额度 → 一般咨询优先级规则表额度 退款过时规则if 账单 and 信用 not in text规则表统一管理无隐式依赖累积噪声17 个散落 if4 条规则 优先级排序4.3 重写后验证测试用例预期补丁版结果重写版结果“我要提额”额度申请额度申请 ✅额度申请 ✅“我要退款”退款退款 ✅退款 ✅“提额顺便问退款”额度申请一般咨询 ❌额度申请 ✅“信用额度”额度申请一般咨询 ❌额度申请 ✅“信用评级有问题”一般咨询额度申请 ❌一般咨询 ✅5. 最小代码补丁堆 vs 规则表 P5 选择以下为教学级示意代码展示“补丁堆”与“规则表”两种实现方式的对比以及 P5 决策逻辑from__future__importannotationsfromdataclassesimportdataclass# 补丁堆版本腐结构 defclassify_patched(text:str)-str:17 次补丁后的路由分类——分支互殴、语义漂移。label一般咨询if账单intext:label账单查询if发票intext:label票据问题if退款intext:label退款if额度intextor信用intext:label额度申请if退款intextand额度intext:# 腐点1互殴label一般咨询if账单intextand信用notintext:# 腐点2过时规则label账单查询returnlabel# 重写版本规则表 优先级 dataclass(frozenTrue)classRule:路由规则——优先级最高的匹配规则生效。name:strkeywords:frozenset[str]label:strpriority:int# 数值越高优先级越高# 规则表清晰、可扩展、无隐式依赖RULES[Rule(limit,frozenset({额度,信用,提额,授信}),额度申请,100),Rule(refund,frozenset({退款,退钱,退货}),退款,90),Rule(invoice,frozenset({发票,税票}),票据问题,80),Rule(bill,frozenset({账单,流水,明细}),账单查询,70),]defclassify_rewritten(text:str)-str:规则表版路由——优先级排序无互殴。hits[rforrinRULESifany(kintextforkinr.keywords)]ifnothits:return一般咨询# 按优先级从高到低排序取最高returnsorted(hits,keylambdar:r.priority,reverseTrue)[0].label# P5 决策逻辑 defp5_strategy(structure_rotten:bool,single_bug:bool)-str: P5 决策什么情况走重写什么情况走小补丁。 Args: structure_rotten: 结构是否已腐分支互殴、语义漂移 single_bug: 是否为单点缺陷 Returns: rewrite_once | small_patch | observe ifstructure_rotten:returnrewrite_once# P5结构已腐必须重写ifsingle_bug:returnsmall_patch# 结构清晰 单点缺陷 → 小补丁returnobserve# 无明确缺陷 → 继续观测# 回归测试 defregression()-None:重写后的回归集——验证语义是否保留。cases{星河零售申请提高信用额度:额度申请,退款进度:退款,提额顺便问退款:额度申请,# 优先级额度 退款发票:票据问题,信用评级有问题:一般咨询,# 无明确业务意图你好:一般咨询,账单流水明细:账单查询,退钱:退款,}fortext,expectedincases.items():gotclassify_rewritten(text)assertgotexpected,fFAIL: {text} → {got} (expected {expected})print(✅ 回归测试全部通过 (8/8))# 示例运行 if__name____main__:sampleCASE-CR-0042 客户要提额顺便问退款print(*50)print(【补丁堆版本 vs 规则表版本】)print(*50)print(f输入:{sample})print(f补丁堆版本结果:{classify_patched(sample)})print(f规则表版本结果:{classify_rewritten(sample)})print(\n*50)print(【P5 决策演示】)print(*50)print(f结构已腐 →{p5_strategy(structure_rottenTrue,single_bugFalse)})print(f单点缺陷 →{p5_strategy(structure_rottenFalse,single_bugTrue)})print(f无缺陷 →{p5_strategy(structure_rottenFalse,single_bugFalse)})print(\n*50)print(【回归测试】)print(*50)regression()运行输出 【补丁堆版本 vs 规则表版本】 输入: CASE-CR-0042 客户要提额顺便问退款 补丁堆版本结果: 一般咨询 规则表版本结果: 额度申请 【P5 决策演示】 结构已腐 → rewrite_once 单点缺陷 → small_patch 无缺陷 → observe 【回归测试】 ✅ 回归测试全部通过 (8/8)代码要点维度补丁堆版本规则表版本规则数量6 个 if 2 个隐式覆盖4 条显式规则规则优先级隐式、互殴显式priority字段扩展性新增规则需小心调整 if 顺序新增一条规则 优先级即可可测试性边界情况不可预测回归集可覆盖所有规则6. 三个教训基于 CASE-CR-0042 的重写经验教训含义证据重写保留语义、重建结构重写不是推翻重来是保留业务语义、优化实现结构回归集验证语义一致性无回归的重写 换一批缺陷重写必须有完整的回归集否则只是“换一种方式犯错”regression()覆盖 8 个测试用例P5 防止用热修文化杀死可维护性用无数 P4 热修代替 P5 重写会慢慢杀死系统的可维护性P5 规则Hotfix-8h 不得用于大重构7. 思考题以下问题供团队内部讨论帮助将 P5 重写概念落地到具体场景腐结构诊断在你的 Agent 系统中路由技能是否已出现“if 互殴”或“语义漂移”如何客观判定structure_rottenTrue授权问题谁有权宣布structure_rottenTrue开发自检架构师评审还是需要 Tech Lead 做 Code Review 后认定重写与飞轮的关系第 5 期的 MAPE 飞轮与第 6 期的 P5 重写如何衔接重写后飞轮是重新启动还是延续观测基线8. 下期预告第 7 期工作记忆治理MemoryItemCASE-CR-0042 会话中的证件号、身份证信息等强身份数据如何确保不进入长程记忆引入 TTL、访问控制和 MemoryItem 对象落实第 0 期确立的“证件号不进长程记忆”红线。9. 延伸阅读资源说明A Single Rewrite Suffices: Empirical Lessons from Production Skill DefinitionsarXiv:2606.30775生产技能定义中“一次重写”的实证研究本卷第 1 期技能即契约——SkillContract能力边界契约化本卷第 2 期决策四轴——四轴 P1单点决策对齐本卷第 3 期无状态决策记忆——DecisionBoard多环节决策传递本卷第 4 期Agent-First 工具接口——ToolSpec工具调用标准化本卷第 5 期数据飞轮——MAPE P3持续改进闭环本卷总览冲突与例外协议 P1–P5P5 在五条协议中的位置本文是「企业智能体工程卷」十期专栏的第 6 期。一次重写——结构混乱时高质量重构优于反复补丁让 Agent 系统从“补丁堆”进化为“规则表 优先级”。欢迎转载请注明出处与原文标题。