AI Agent 问题排查实战：HZERO 低代码 AI 助手故障诊断与修复

一、背景

HZERO 低代码平台提供了「AI 助手」功能，用户通过上传界面截图或描述需求，AI 自动生成业务对象和页面。该功能由 AIP（AI 平台）的 Agent 编排实现，涉及 hzero-aip-app、hzero-aip-server、hzero-modeler 等多个微服务协同。

测试过程中连续遇到两个错误，本文记录了作为 AI Agent 如何逐步分析、定位并解决问题的完整过程。

二、问题一：domainCode 缺失

2.1 现象

在 AIP 中台直接调用「AIGC 生成低代码业务对象和页面」Agent 编排，执行到「批量创建对象」节点时报错：

CommonException: 程序出现错误，请联系管理员

2.2 分析过程

第一步：看截图，定位错误节点

用户提供了错误截图，显示错误发生在流程的「批量创建对象」节点，异常类型为 CommonException，调用栈指向 AbstractInnerRequestNodeHandler.execute。

判断方向：这是 Agent 流程中的内部接口调用节点，调用了低代码平台的后端接口，接口返回了错误。

第二步：查容器状态，确认服务存活

docker ps --format '{{.Names}}\t{{.Status}}' | grep -i aip

结果：hzero-aip-server 和 hzero-aip-app 都 Up 7 hours，排除服务宕机。

第三步：拉日志，精确定位错误

先看 hzero-aip-app（Agent 流程执行方）的日志，过滤错误关键词：

docker logs hzero-aip-app --since 30m 2>&1 | grep -i "error\|exception\|批量创建\|InnerRequest" | tail -50

找到关键错误：

ERROR --- Failed on node AIGC 生成低代码业务对象和页面/LOWCODE.BUSINESS_OBJECT_PAGE/INTERNAL_INTERFACE_...
io.choerodon.core.exception.CommonException: 程序出现错误，请联系管理员
  at ResponseUtils.getResponse(ResponseUtils.java:133)
  at AbstractInnerRequestNodeHandler.execute(AbstractInnerRequestNodeHandler.java:199)

这说明 aip-app 调用了某个内部接口，接口返回了非成功响应，ResponseUtils 解析后抛出通用异常。

第四步：查被调用方日志，找到真实错误

错误堆栈显示调用链终止在 aip-app，但真正的错误来自被调用的服务。查看 hzero-modeler 日志：

docker logs hzero-modeler --since 30m 2>&1 | grep -i "error\|exception\|simple-generator" | tail -30

找到根因：

MissingServletRequestParameterException: Required request parameter 'domainCode' for method parameter type String is not present
  Request: {URI=/v1/0/business-objects/domain/simple-generator}

第五步：回溯参数，确认 domainCode 为 null

回到 aip-app 日志，查看脚本节点的参数输出：

脚本节点参数:{businessObjectList=[...], domainCode=null, pageList=[...]}

确认：domainCode 为 null，导致低代码平台接口报 400 错误。

2.3 根因

Agent 编排流程中，domainCode 需要从低代码平台的上下文中获取。用户直接在 AIP 中台调用 Agent 编排，没有进入低代码平台的领域上下文，导致 domainCode 为空。

2.4 解决方案

从低代码平台进入领域后调用 AI 助手。在低代码平台的工作台中先进入一个领域（如”调研问卷”），再点击 AI 助手按钮，这样 domainCode 会作为上下文参数自动传入 Agent 流程。

2.5 验证

用户从低代码平台领域内调用 AI 助手后，domainCode 正确传入（值为 RSHQ），第一个问题解决。

三、问题二：业务对象依赖顺序错误

3.1 现象

domainCode 问题解决后，AI 成功生成了业务对象和页面数据，但在「批量创建对象」节点再次报错：

CommonException: 业务对象[RS_MEMBERSHIP_CARD]不存在

3.2 分析过程

第一步：看截图，识别新错误

从截图看到错误信息变为「业务对象[RS_MEMBERSHIP_CARD]不存在」，不再是通用的”程序出现错误”，而是一个具体的业务校验错误。

判断方向：这次不是参数缺失，而是业务逻辑问题——接口在创建某个对象时，发现它依赖的另一个对象不存在。

第二步：查日志，确认调用链

docker logs hzero-aip-app --since 15m 2>&1 | grep -i "error\|RS_MEMBERSHIP\|不存在" | tail -30

找到：

ERROR --- Failed on node ...INTERNAL_INTERFACE_...
CommonException: 业务对象[RS_MEMBERSHIP_CARD]不存在

hzero-modeler 侧也确认：

Common exception, Request: {URI=/v1/0/business-objects/domain/simple-generator}
CommonException: 业务对象[RS_MEMBERSHIP_CARD]不存在

第三步：分析数据，发现依赖关系

从 aip-app 日志中提取 AI 生成的业务对象数据：

• RS_MEMBER（会员信息）：包含一个 MASTER_RELATION 类型字段 membershipCard，指向 RS_MEMBERSHIP_CARD
• RS_MEMBERSHIP_CARD（会员卡信息）：被 RS_MEMBER 引用

两个对象都是 CREATE 模式（新建），businessObjectList 中 RS_MEMBER 排在前面。

问题就在这里：批量创建时，RS_MEMBER 先被处理，它的 MASTER_RELATION 字段引用了还不存在的 RS_MEMBERSHIP_CARD，低代码平台校验依赖对象是否存在时失败。

第四步：审查脚本节点代码

用户提供了「页面&业务对象参数处理」脚本节点的完整代码。审查后发现两个问题：

1. 没有依赖排序：businessObjectList 按原始顺序传给 API，没有按 MASTER_RELATION 依赖关系排序
2. masterBusinessObjectCode 未同步更新：脚本给 businessObjectCode 加了 domainCode 前缀（如 RSHQ_RS_MEMBER），但字段里的 masterBusinessObjectCode 没同步更新，仍指向旧编码 RS_MEMBERSHIP_CARD

3.3 根因

脚本节点缺少两个关键处理：

1. 业务对象未按依赖关系排序，导致被引用对象排在引用者之后
2. 加 domainCode 前缀后，MASTER_RELATION 字段的 masterBusinessObjectCode 指向了不存在的旧编码

3.4 解决方案

在脚本节点中增加两处修复：

修复 1：同步更新 masterBusinessObjectCode

在遍历 businessObjectFields 的循环中增加：

if(field.componentType === 'MASTER_RELATION' && field.masterBusinessObjectCode
   && boCodeToNewMap.has(field.masterBusinessObjectCode)) {
  field.masterBusinessObjectCode = boCodeToNewMap.get(field.masterBusinessObjectCode);
}

修复 2：拓扑排序

在 return 之前，对 businessObjectList 做 Kahn 拓扑排序：

function sortByDependency(objList){
  if(!objList || objList.length <= 1) return objList;

  var codeSet = {};
  objList.forEach(function(o){ codeSet[o.businessObjectCode] = true; });

  var deps = {};
  var inDegree = {};
  objList.forEach(function(o){
    deps[o.businessObjectCode] = [];
    inDegree[o.businessObjectCode] = 0;
  });

  objList.forEach(function(o){
    if(o.businessObjectFields){
      o.businessObjectFields.forEach(function(f){
        if(f.componentType === 'MASTER_RELATION' && f.masterBusinessObjectCode
           && codeSet[f.masterBusinessObjectCode]){
          deps[f.masterBusinessObjectCode].push(o.businessObjectCode);
          inDegree[o.businessObjectCode]++;
        }
      });
    }
  });

  var queue = [];
  objList.forEach(function(o){
    if(inDegree[o.businessObjectCode] === 0) queue.push(o.businessObjectCode);
  });

  var sorted = [];
  while(queue.length > 0){
    var code = queue.shift();
    var obj = objList.find(function(o){ return o.businessObjectCode === code; });
    if(obj) sorted.push(obj);
    deps[code].forEach(function(dep){
      inDegree[dep]--;
      if(inDegree[dep] === 0) queue.push(dep);
    });
  }

  // 循环依赖兜底
  if(sorted.length < objList.length){
    objList.forEach(function(o){
      var found = false;
      for(var i = 0; i < sorted.length; i++){
        if(sorted[i].businessObjectCode === o.businessObjectCode){ found = true; break; }
      }
      if(!found) sorted.push(o);
    });
  }

  return sorted;
}

3.5 验证

用户更新脚本节点后重新测试，业务对象和页面成功创建。

四、方法论总结：AI Agent 如何排查问题

4.1 排查框架

整个排查过程遵循一个清晰的框架：

截图/现象 → 服务状态 → 日志分析 → 参数回溯 → 代码审查 → 定位根因 → 修复验证

4.2 关键原则

原则	说明	实际应用
先看现象，不急于下结论	错误截图是最直接的信息源	第一次看到 CommonException 通用错误，不能止步于此，需要追查具体原因
服务存活先确认	排除基础设施问题	docker ps 确认容器都在运行
调用方与被调用方日志对照看	错误往往在被调用方	aip-app 抛通用异常，hzero-modeler 才有具体错误
参数回溯定位数据问题	日志中的参数数据是关键证据	从脚本节点日志中找到 domainCode=null 和 businessObjectList 的完整数据
代码审查发现逻辑缺陷	静态分析补充动态调试	审查脚本代码发现缺少排序和字段同步
一次只改一个问题	控制变量，便于验证	先修 domainCode，再修依赖顺序

4.3 工具使用策略

阶段	工具/命令	目的
服务检查	docker ps	确认容器存活状态
日志检索	docker logs --since + grep	精确过滤错误信息
参数分析	日志中的脚本节点参数输出	回溯传入接口的实际数据
代码审查	人工提供脚本源码	静态分析逻辑缺陷
修复验证	用户在平台上重新执行	端到端验证

4.4 AI Agent 的优势

在这次排查中，AI Agent 展现了几个独特优势：

1. 多服务日志关联分析：同时查看 aip-app、aip-server、modeler 三个服务的日志，快速关联调用链，人工排查往往需要切换多个终端窗口
2. 从海量日志中精准提取关键信息：在数万行日志中用 grep 精确定位到 3 行关键错误，避免了人工翻阅的眼疲劳
3. 数据与代码交叉验证：从日志中提取业务对象数据结构，再对照脚本代码分析，快速发现两个缺陷
4. 直接给出可执行的修复代码：拓扑排序算法、字段同步逻辑，不需要人工再翻译成代码

五、涉及的容器服务

服务	角色
hzero-aip-app	AI 应用前端，执行 Agent 流程编排
hzero-aip-server	AI 平台后端，处理 LLM 调用、知识检索
hzero-modeler	低代码建模服务，提供业务对象/页面创建 API
hzero-lowcode	低代码前端服务
hzero-lowcodedata	低代码数据服务

六、结论

两个问题的根因不同但都出在「参数传递」环节：

1. 问题一是上下文参数（domainCode）未传入 — 需要从正确的入口调用
2. 问题二是脚本节点对参数的处理不完整 — 缺少依赖排序和字段同步

修复后，AI 助手能够正确生成业务对象和页面，整个链路跑通。建议将脚本修复同步到产品主线版本。