人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习【免费下载链接】agent-coreopenJiuwen agent-core可提供AI Agent开发、运行、调优与演进相关的全套SDK能力项目地址https://gitcode.com/openJiuwen/agent-core点击查看免费下载本文聚焦 openJiuwen agent-core 框架的统一异常体系以JiuWenBaseException为起点深入其底层继承关系、BaseError的模板化消息渲染、错误码StatusCode枚举、结构化序列化to_dict/to_json以及raise_error等统一抛出入口并结合源码展示如何在 Agent、工作流、会话等模块中落地这套错误处理机制。概览为什么 openJiuwen 需要一套统一异常体系openJiuwen agent-core 覆盖 AI Agent 的开发、运行、调优与演进全链路涉及工作流编排、LLM 调用、工具执行、知识检索、多智能体协作、会话与运行时等大量模块。若每个模块各自抛出裸的 Python 异常错误将难以识别、无法统一序列化、也难以跨 API 边界传递。为此框架定义了以JiuWenBaseException为入口的统一异常类以及以BaseError为核心的完整异常层级配合全局StatusCode错误码枚举形成错误码 模板化消息 结构化输出 语义化异常类型的四层体系。JiuWenBaseException是框架对外文档化的异常类继承自 Python 内置Exception而框架内部真正的统一异常基类是BaseError。下文将从文档 API 出发逐层还原其实现。JiuWenBaseException框架定义的异常类构造签名与参数说明依据 API 文档exception.mdJiuWenBaseException的构造签名如下openjiuwen.core.common.exception.exception.JiuWenBaseException(error_code: int, message: str)参数含义error_codeint异常的错误码用于标识异常的类型可在整个框架的错误码体系中全局定位。messagestr异常的错误信息用于描述异常发生的具体原因。公开属性异常对象对外暴露两个只读属性属性类型说明error_codeint返回该 openJiuwen 异常对象的错误码messagestr返回该 openJiuwen 异常对象的错误信息这两个属性分别对应构造时传入的error_code与message让上层调用方可以精确判断错误类型并读取可展示的错误描述。使用示例from openjiuwen.core.common.exception.exception import JiuWenBaseException try: raise JiuWenBaseException(error_code100005, messagecomponent execute error) except JiuWenBaseException as e: print(e.error_code) # 100005 print(e.message) # component execute error从 JiuWenBaseException 到 BaseError真正的统一异常基类从源码结构看JiuWenBaseException是文档层面向使用者的异常类而框架内部各模块实际统一继承的基类是BaseError定义于 openjiuwen/core/common/exception/errors.py。两者的定位关系可以理解为JiuWenBaseException携带(error_code, message)二元组的框架异常用于需要显式指定错误码和错误信息的场景BaseError携带(status, msg, details, cause, **kwargs)的完整统一基类直接关联StatusCode枚举具备模板渲染与序列化能力。BaseError 的核心设计BaseError继承自 Python 内置Exception其设计要点源码注释原文是StatusCode 是首要语义标识每个异常必须绑定一个StatusCode枚举成员通过status.code得到整数错误码异常类型表达控制 / 恢复语义通过不同的子类如FrameworkError、ValidationError、ExecutionError表达是否致命、是否可重试/重规划消息渲染基于模板且惰性安全_render_message使用_format_template渲染StatusCode.errmsg模板渲染失败时回退为原始模板绝不向外抛出格式化异常。其关键字段如下errors.pyclass BaseError(Exception): status: StatusCode StatusCode.ERROR recoverable: bool False fatal: bool False def __init__( self, status: StatusCode, *, msg: Optional[str] None, details: Optional[Any] None, cause: Optional[BaseException] None, **kwargs: dict[str, Any], ): self.status status self.code self.status.code self.params kwargs self.details details self.cause cause self.__cause__ cause self._template_message self._render_message() self.message msg if msg else self._template_message super().__init__(self._template_message)statusStatusCode必填位置参数标识异常类型同时作为错误消息模板的来源msgOptional[str]自定义错误消息若提供则覆盖模板渲染结果默认为NonedetailsOptional[Any]结构化上下文信息可为任意类型数据用于补充错误细节causeOptional[BaseException]链式异常记录导致当前异常的原始异常kwargsdict[str, Any]模板参数用于填充StatusCode.errmsg模板中的占位符。语义化异常类型层级BaseError之下框架按错误属于哪类语义定义了完整的子类层级同样位于 errors.py异常类语义recoverablefatalFrameworkError基础设施 / 环境 / 依赖失败必须中止当前执行FalseTrueConfigurationError框架配置错误继承自 FrameworkErrorFalseTrueValidationError约束 / 校验 / 不支持的能力错误不应重试或重规划FalseFalseExecutionError工作流 / Agent / 工具执行期错误通常可通过重试或重规划恢复TrueFalseTermination非错误的控制流终止正常停止、取消、完成等FalseFalse在此基础上框架按业务域派生出WorkflowError、ComponentError、AgentError、RunnerError、GraphError、ModelError、ToolError、ContextError、SessionError、StoreError、GuardrailError、CryptError等模块级异常。例如GuardrailError用于护栏安全检测拦截场景携带详细风险信息供日志与上报使用errors.py。错误码到异常类的映射机制BaseError的STATUS_TO_EXCEPTION全局映射表由build_status_exception_map()构建status_mapping.py其规则分为三层关键字规则KEYWORD_RULES按错误码枚举名中的关键词归类。例如名称含INVALID、PARAM、CONFIG的映射为ValidationError含INIT、CALL、MODEL、PROVIDER的映射为FrameworkError含TIMEOUT、EXECUTION、RUNTIME、STREAM的映射为ExecutionError区间规则RANGE_RULES按错误码数值区间兜底。例如100000–119999映射为WorkflowError120000–129999映射为AgentError130000–139999映射为RunnerError140000–149999映射为GraphError150000–159999映射为ContextError190000–198999映射为SessionError手动覆盖MANUAL_OVERRIDES对特定名称显式指定异常类例如CONTROLLER_INVOKE_LLM_FAILED强制为FrameworkError、TOOL_EXECUTION_ERROR强制为ToolError、TOOL_NOT_FOUND_ERROR强制为ValidationError。这意味着只需传入一个StatusCode框架就能自动决定抛出哪种语义的异常类无需调用方手动选择。StatusCode全局错误码枚举与分区规范错误码枚举定义于 openjiuwen/core/common/exception/codes.py每个枚举成员是(code, message_template)二元组class StatusCode(Enum): SUCCESS (0, success) ERROR (-1, error) WORKFLOW_COMPONENT_ID_INVALID ( 100010, the component id is invalid for component {comp_id}, reason{reason}, workflow{workflow}) COMPONENT_LLM_INVOKE_CALL_FAILED (101003, component llm_invoke call failed, reason: {error_msg}) # ... 更多成员错误码按数值区间划分业务域涵盖组件、工作流、Agent 编排、运行时、上下文引擎、知识库检索、记忆引擎、优化工具链、公共能力等。完整的枚举常量 → 错误码 → 描述 → 解决方案对照表可在 status_code.md 中查阅例如组件相关错误100000–109999如COMPONENT_EXECUTE_ERROR100005表示工作流中组件执行出现异常LLM_COMPONENT_INVOKE_LLM_ERROR101003表示 LLM 服务调用返回错误需检查 LLM 服务配置工作流相关错误110000–119999如GRAPH_ADD_NODE_FAILED110003、WORKFLOW_COMPONENT_CONFIG_ERROR110006Agent 编排相关错误120000–129999如TOOL_NOT_FOUND_ERROR120000、CONTROLLER_INVOKE_LLM_FAILED123000运行时相关错误190000–199999如RUNTIME_AGENT_GET_FAILED190051、STREAM_FRAME_TIMEOUT_FAILED193003。错误码生成规范面向扩展如果需要在框架中新增错误码可参考 code_template.py 提供的生成规范scope 取值域WORKFLOW、COMPONENT、AGENT、TOOL、MODEL、SESSION、GRAPH、CONTROLLER、RUNNER、PROMPT、COMMON、CONTEXT、TOOLCHAIN、MEMORY、RETRIEVAL、SYS_OPERATIONfailure_type 取值域INVALID、NOT_FOUND、NOT_SUPPORTED、CONFIG_ERROR、PARAM_ERROR、TYPE_ERROR、INIT_FAILED、CALL_FAILED、EXECUTION_ERROR、RUNTIME_ERROR、PROCESS_ERROR、TIMEOUT、INTERRUPTED每种 failure_type 对应一套消息模板例如TIMEOUT会生成{scope} {subject} timeout ({timeout}s)并在失败信息末尾追加, reason: {error_msg}消息渲染采用str.format_map安全格式化缺失的占位符会显示为missing:KEY而非抛出KeyError见_SafeDict实现errors.py。异常的结构化输出to_dict 与 to_jsonBaseError提供两个核心序列化方法errors.py这也是JiuWenBaseException面向 API / RPC / 日志场景的重要能力来源to_dict面向 API / RPC / 日志的结构化字典def to_dict(self) - Dict[str, Any]: return { code: self.code, status: self.status.name, message: self._template_message, params: self.params, raw_message: self.message, details: self.details, }返回字典包含六个字段字段类型说明codeint错误码整数statusstr状态码枚举名字符串messagestr由模板渲染出的消息paramsdict模板参数raw_messagestr自定义消息或渲染消息即实际对外展示的原始消息detailsAny详细信息to_jsonUTF-8 安全的 JSON 序列化def to_json(self) - str: return json.dumps(self.to_dict(), ensure_asciiFalse)to_json基于to_dict序列化为 JSON 字符串并指定ensure_asciiFalse保证中文等多语言错误消息以 UTF-8 原文输出而不被转义为\uXXXX。应用场景API 响应将异常统一序列化为{code, status, message, ...}结构客户端可按code精确处理错误分支RPC 调用跨进程传递时使用to_json得到可传输的字符串日志记录结构化日志可直接落库to_dict()结果便于检索与聚合分析。统一抛出入口raise_error 与系列工厂函数为了统一异常抛出方式errors.py 还提供了若干工厂函数它们共同构成框架的错误入口层def build_error(status, *, msgNone, detailsNone, causeNone, **kwargs) - BaseError: # 仅构造不抛出适合延迟抛出或包装场景 exc_cls STATUS_TO_EXCEPTION.get(status, FrameworkError) return exc_cls(status, msgmsg, detailsdetails, causecause, **kwargs) def raise_error(status, *, msgNone, detailsNone, causeNone, **kwargs) - None: # 统一错误抛出入口 raise build_error(status, msgmsg, detailsdetails, causecause, **kwargs) def system_error(status, *, causeNone, **kwargs) - None: raise FrameworkError(status, causecause, **kwargs) def validate_error(status, *, causeNone, **kwargs) - None: raise ValidationError(status, causecause, **kwargs) def terminate(status, **kwargs) - None: raise Termination(status, **kwargs)使用方式示例from openjiuwen.core.common.exception.codes import StatusCode from openjiuwen.core.common.exception.errors import raise_error, system_error, validate_error # 抛出一个工作流组件执行错误并填充模板参数 reason raise_error( StatusCode.COMPONENT_LLM_INVOKE_CALL_FAILED, msgllm service unavailable, details{provider: siliconflow}, error_msgconnection refused, ) # 系统级错误框架初始化失败 system_error(StatusCode.COMPONENT_LLM_INIT_FAILED, error_msginvalid api key) # 校验类错误参数非法 validate_error(StatusCode.WORKFLOW_COMPONENT_ID_INVALID, comp_idcomp-1, reasonduplicated, workflowwf-1)其中error_msg、comp_id、reason、workflow等关键字正是对应StatusCode消息模板中的占位符会被_format_template自动填充。源码佐证异常体系在框架各模块中的实际落地在框架各模块的源码与文档中可以找到大量使用该异常体系的实例印证其调用关系与用法工作流组件在组件执行失败时抛出带StatusCode的框架异常例如 LLM 组件、分支组件、循环组件、子工作流组件各自的错误码均定义在StatusCode中codes.py会话与调测JiuWenBaseException在 Session 调测能力 与 使用预置组件 等文档中被引用说明会话层的错误处理同样遵循该体系图 / 工作流 APIgraph.md 与 components.md 等 API 文档记录了这些模块抛出框架异常时的行为LLM 基础能力llm.md 中 LLM 组件的调用失败、配置错误等均映射到对应的StatusCode枚举。完整异常速查错误码分区与排查建议框架错误码按数值区间划分为 17 个业务域详见 status_code.md常用分区如下错误码区间业务域典型错误码示例100000–109999组件相关INTERACTIVE_INVALID_INPUT_ERROR(100000)、LLM_COMPONENT_INVOKE_LLM_ERROR(101003)、BRANCH_COMPONENT_BRANCH_NOT_FOUND_ERROR(101102)110000–119999工作流相关GRAPH_ADD_NODE_FAILED(110003)、WORKFLOW_COMPONENT_CONFIG_ERROR(110006)120000–129999Agent 编排TOOL_NOT_FOUND_ERROR(120000)、CONTROLLER_PARSE_TOOL_CALL_ERROR(123005)130000–139999多智能体 / RunnerAGENT_GROUP_CREATE_FAILED(132001)、AGENT_NOT_FOUND(134002)、TOOL_NOT_FOUND(134005)140000–149999图执行引擎EXPRESSION_CONDITION_SYNTAX_ERROR(140000)、NUMBER_CONDITION_ERROR(140003)150000–159999上下文 / 检索 / 记忆CONTEXT_ENGINE_MESSAGE_PROCESS_ERROR(153000)、EMBEDDING_EMPTY_INPUT_ERROR(155000)、RETRIEVER_TOP_K_INVALID_ERROR(155210)、MEMORY_ADD_MEMORY_EXECUTION_ERROR(158002)160000–179999优化工具链AGENT_BUILDER_AGENT_PARAMS_ERROR(170000)、AGENT_BUILDER_AGENT_TRAINER_TRAIN_ERROR(170040)180000–189999公共能力MODEL_PROVIDER_INVALID_ERROR(181000)、PLUGIN_RESPONSE_TOO_BIG_ERROR(182003)、LOG_PATH_SENSITIVE_ERROR(183000)、JSON_LOADS_ERROR(188002)190000–199999运行时 / 会话RUNTIME_AGENT_GET_FAILED(190051)、STREAM_FIRST_FRAME_TIMEOUT_FAILED(193004)、RUNTIME_CHECKPOINTER_NONE_AGENT_STORE_ERROR(197001)每个错误码在 status_code.md 中均配有 DESCRIPTION错误描述与 RESOLUTION解决方案两列可直接作为排障手册使用。例如TOOL_NOT_FOUND_ERROR120000的排查建议是根据异常详情检查工具 ID 是否正确并确认工具已创建且处于正常状态。小结异常处理的推荐实践基于上述分析在 openJiuwen 项目中处理异常时推荐以下实践优先使用StatusCoderaise_error不要直接抛出裸Exception通过raise_error(StatusCode.XXX, **模板参数)让框架自动选择正确的异常类并渲染消息善用结构化输出面向外部 API 或日志时统一调用to_dict()/to_json()保证错误信息可机器解析区分异常语义利用FrameworkError致命、需中止、ValidationError不应重试、ExecutionError可重试/重规划表达错误恢复策略方便上层编排逻辑做出正确决策链式保留原始异常构造时传入cause保留异常调用链便于排查根因查阅错误码速查表遇到具体错误码时直接对照 status_code.md 中的 RESOLUTION 列进行排障。相关参考文档与源码exception.mdAPI 文档JiuWenBaseExceptionerrors.mdAPI 文档BaseErrorstatus_code.mdAPI 文档错误码全量表errors.pyBaseError 与异常层级实现codes.pyStatusCode 枚举实现status_mapping.py错误码到异常类的映射规则code_template.py错误码与消息模板生成规范赞分享人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习【免费下载链接】agent-coreopenJiuwen agent-core可提供AI Agent开发、运行、调优与演进相关的全套SDK能力项目地址https://gitcode.com/openJiuwen/agent-core点击查看免费下载相关推荐openJiuwen agent-core 统一异常体系解析BaseError 与 StatusCode 错误码全解openJiuwen agent core 统一异常体系解析BaseError 与 StatusCode 错误码全解 本篇技术指南以 errors.md ht人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习Moonshine Micro 特征生成模块解析面向 MCU 的无堆 log-mel 前端批量 流式Moonshine Micro 特征生成模块解析面向 MCU 的无堆 log mel 前端批量 流式 本指南围绕 micro/feature gene人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习Faraday 错误处理实战指南统一异常体系与 raise_error 中间件Faraday 错误处理实战指南统一异常体系与 raise_error 中间件 Faraday 是用户与底层 HTTP 库之间的抽象层为了让上层应用不依赖具后端网络通信上一篇如何为Win10/11文件资源管理器添加炫酷模糊效果ExplorerBlurMica完整配置指南 下一篇如何高效使用RecafJava字节码编辑与逆向工程的终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考