第4章：模块职责划分：业务逻辑层、编排层、基础设施层的异常职责边界

4.1 边界定义

在Agent系统中，异常处理并非由单一模块完成，而是由三个核心层各司其职、协同闭环。边界划分的核心原则是：异常由产生的源头就近捕获，由拥有恢复信息最丰富的层处理，跨层传递时保持语义不丢失。

4.2 分层职责详述

4.2.1 业务逻辑层

• 输入校验： 对用户输入的Agent指令、参数、上下文进行业务规则校验。校验失败直接返回BusinessValidationError，不向下传递。
• 状态机保护： 当Agent状态（如“待处理→执行中→完成”）发生非法跳转时，产生StateTransitionException，并触发状态回滚。
• 补偿事务： 当业务逻辑内的部分步骤失败时，业务逻辑层自行执行补偿（如撤销已完成的子步骤），补偿失败再上报编排层。

4.2.2 编排层

• 流程健康度检测： 监控每个子任务的预期完成时间，超时后判断是等待还是降级。
• 熔断与降级： 当某个下游依赖连续失败超过阈值（如5次），编排层自动切断该依赖调用，执行预设的降级逻辑（如返回缓存结果或模拟响应）。
• 检查点回滚： 维护流程执行的历史快照，异常不可恢复时回滚至最近的检查点，保证状态一致性。

4.2.3 基础设施层

• 资源隔离： 连接池超时、线程池耗尽等异常应在该层内部完成隔离，不泄露资源句柄。
• 重试策略： 支持可配置的指数退避重试（如初始间隔1s，倍率2，最大重试3次），超过次数后直接向编排层返回ResourceExhaustedError。
• 度量上报： 记录每次失败的类型、频率、流量，供监控系统用于自动弹性和扩缩容决策。

4.3 数据流/控制流/信任链路

下图描述了当一次Agent任务执行过程中，异常在三个层次间的典型传播路径与信任边界。

4.4 选型权衡

4.5 风险点

• 责任链过长： 异常每经过一层都被添加一次包装上下文，最终错误消息膨胀，上层难以提取原始根因。应每层只追加一个关键字段，不要复制整个trace。
• 降级黑盒： 编排层执行降级后，业务逻辑层可能不知道实际响应是降级产生的，导致基于降级数据做出错误业务决策。降级响应中必须附带 x-agent-retryable: true 头。
• 资源泄露闭环： 基础设施层发生连接池异常时，若编排层同时发起了降级操作，新的降级路径可能又试图建立新的连接，导致连接池无法恢复。需要引入“熔断后隔离窗口”机制。

4.6 落地步骤

1. 步骤1：定义三层之间的异常合约 — 明确错误码前缀（如 BIZ_、ORCH_、INFRA_）和每个错误的payload结构。
2. 步骤2：为每层添加异常适配器 — 将原始异常转换为合约定义的格式。
3. 步骤3：配置链路超时和重试参数 — 在编排层设置每个子任务的超时阈值，在基础设施层设置连接池的最大等待时间。
4. 步骤4：安装熔断器与度量探针 — 在编排层关键路径上插入熔断器，在基础设施层所有外部调用处插入失败计数器。
5. 步骤5：集成测试异常场景 — 编写故障注入测试，验证每个异常类型是否在正确的层被捕获且不泄漏。

// 编排层适配器示例
public class OrchestrationExceptionAdapter {
    public static OrchestrationError adapt(InfraException ex) {
        return new OrchestrationError(
            ErrorCode.ORCH_INFRA_DOWN,
            "基础设施资源不可用: " + ex.getResourceType(),
            ex.getCause(),
            ex.isRetryable()
        );
    }
}

4.7 验收标准