人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载本文围绕 docs/dev/extending-pi/21-error-handling.md 展开深入拆解 Pigsd-2 项目扩展系统如何分层处理错误扩展事件错误只记录不崩溃、tool_call 拦截错误 fail-safe 阻断、工具执行错误以isError: true回传 LLM 实现自愈。读完本文你将掌握每一条错误路径的源码级行为以及如何据此写出健壮、可观测的 Pi 扩展。在 Pi 的扩展架构中错误处理被刻意设计为三层模型每一层对应不同的失败来源与恢复策略。其设计目标只有一个任何单个扩展的缺陷都不能让整个 agent 会话崩溃同时把错误信息送达最合适的位置——日志、调用方或被 LLM 看到的工具结果。下面逐一拆解这三层语义。三层错误模型总览原文档用三条规则概括了整个错误处理体系扩展错误Extension errors被记录logged但不会让 Pi 崩溃agent 继续运行tool_callhandler 错误阻断该工具的执行fail-safe 行为工具execute错误以isError: true形式上报给 LLM使其能够从中恢复。这三条规则分别对应错误发生的三个位置事件处理器event handler、工具调用拦截器tool_call interceptor、工具本体执行execute。它们在代码中分别由 runner.ts、wrapper.ts 和 agent-session.ts 实现。错误位置行为恢复主体关键实现事件 handler 抛错记录为ExtensionError继续执行后续 handleragent 继续运行invokeHandlers的 try/catch emitErrortool_callhandler 抛错抛出错误阻断工具执行调用方agent 会话wrapper 的拦截块 /setBeforeToolCall的{ block: true }工具execute抛错以isError: true触发 tool_result 并重新抛出LLM 读到错误文本后自我修正wrapper 的 catch 块 setAfterToolCall第一层扩展事件错误——记录但不崩溃行为语义扩展通过注册事件 handler 来观察 agent 生命周期详见 07-events-the-nervous-system.md。当某个 handler 抛出异常时Pi 不会终止进程也不会中断当前正在进行的 agent 循环而是把错误封装成结构化的ExtensionError交给错误监听器然后继续调用下一个 handler。源码级实现这一行为的核心在ExtensionRunner.invokeHandlersrunner.ts 中的共享调用循环for (const handler of handlers) { try { const event getEvent(); const handlerResult await handler(event, ctx); const action processResult(handlerResult, ext.path); if (action.done) return; } catch (err) { const message err instanceof Error ? err.message : String(err); const stack err instanceof Error ? err.stack : undefined; this.emitError({ extensionPath: ext.path, event: eventType, error: message, stack, }); } }注意几个细节逐 handler 隔离异常只影响当前 handler 的这次调用不影响同一扩展的其他 handler也不影响其他扩展。事件类型语义保留不同事件对返回值有不同要求如before_commit可返回cancel否决提交、session_before_switch可返回cancel取消切换。handler 抛错相当于没有返回结果事件的自然流程继续推进。短路逻辑仍有效processResult返回{ done: true }时可提前终止遍历例如input事件的handled结果、session_before_*的cancel出错并不妨碍短路机制工作。ExtensionError的结构ExtensionError接口定义在 types.tsexport interface ExtensionError { extensionPath: string; event: string; error: string; stack?: string; }extensionPath出错的扩展路径便于定位来源event出错的扩展点事件名如before_commit、tool_resulterror错误消息文本非 Error 对象会被String(err)化stack可选的调用栈。错误监听与分发ExtensionRunner维护一个errorListeners: SetExtensionErrorListenerrunner.ts对外暴露onError(listener): () void——注册监听器并返回注销函数runner.tsemitError(error)——遍历所有监听器分发错误runner.ts。对扩展开发者而言这意味着你可以在自己的扩展里注册onError把 Pi 其他扩展的运行时错误汇总到自己的监控逻辑例如写入日志文件或触发 UI 通知而不影响任何扩展的运行。扩展加载期错误除了运行期事件错误加载期错误同样遵循不崩溃原则。LoadExtensionsResult中携带独立的errors: Array{ path: string; error: string }与warnings: ExtensionLoadWarning[]types.ts。单个扩展模块加载失败或校验不通过时Pi 会将其记录进errors并继续加载其余扩展而不是整体中止。这与扩展错误不崩溃的总原则保持一致。第二层tool_callhandler 错误——fail-safe 阻断行为语义tool_call事件是扩展在工具实际执行前做拦截的扩展点例如审批、改写参数、条件放行。由于该事件直接决定这个工具到底要不要跑它的错误处理策略刻意与第一层相反一旦tool_callhandler 出错该工具的执行被强制阻断。这是典型的 fail-safefail closed设计——宁可让工具不执行也不在一个未经确认、可能处于半处理状态的环境下继续运行。源码级实现工具执行的外层包装在wrapToolWithExtensionswrapper.ts。执行tool_call拦截时if (runner.hasHandlers(tool_call)) { try { const callResult await runner.emitToolCall({ ... }); if (callResult?.block) { const reason callResult.reason || Tool execution was blocked by an extension; throw new Error(reason); } } catch (err) { if (err instanceof Error) { throw err; } throw new Error(Extension failed, blocking execution: ${String(err)}); } }也就是说handler 返回{ block: true }会抛错阻断handler 本身抛错也会被重新抛出同样阻断执行。在 agent 会话侧agent-session.ts 的setBeforeToolCall回调也做了同样的兜底} catch (err) { return { block: true, reason: err instanceof Error ? err.message : Extension failed, blocking execution: ${String(err)} }; }最终统一为{ block: true, reason }返回给会话工具不会被执行。设计权衡这条路径与第一层的差异是有意为之事件 handler第一层是观察者角色出错后跳过即可不影响主流程tool_call拦截器第二层是门卫角色其职责就是决定是否放行。门卫自身出错意味着无法确认安全此时默认拒绝通行fail closed避免在参数未经验证时执行可能造成副作用写文件、跑 bash的工具。第三层工具execute错误——以isError: true上报 LLM行为语义当工具本体ToolDefinition.execute执行失败时错误不会被静默吞掉也不会让会话崩溃而是做两件事触发一次带isError: true的tool_result事件把错误文本作为结果内容广播给扩展重新抛出错误让上层把它包装成工具结果消息送回 LLM 的上下文使 LLM 能看到失败原因并调整策略重试。源码级实现在 wrapper.ts 的 catch 分支} catch (err) { // Emit tool_result event for errors if (runner.hasHandlers(tool_result)) { await runner.emitToolResult({ type: tool_result, toolName: tool.name, toolCallId, input: params, content: [{ type: text, text: err instanceof Error ? err.message : String(err) }], details: undefined, isError: true, }); } throw err; }同时会话层的setAfterToolCall会收到带isError标记的结果agent-session.tsthis.agent.setAfterToolCall(async ({ toolCall, args, result, isError }) { await this._agentEventQueue; if (!this._extensionRunner?.hasHandlers(tool_result)) return undefined; const resultResult await this._extensionRunner.emitToolResult({ type: tool_result, toolName: toolCall.name, toolCallId: toolCall.id, input: args, content: result.content, details: result.details, isError, }); // ... });isError: true被完整传递到tool_result事件事件类型定义见 types.ts 的ToolExecutionEndEvent扩展可以在这一环改写结果内容或修正isError标记emitToolResult的 handler 链允许修改content/details/isError见 runner.ts。为什么这层必须把错误交给 LLM工具调用失败是这个系统最日常的故障。把失败原因送回 LLM 上下文而不仅是写日志让 agent 可以读取错误文本判断是参数错误、环境缺失还是资源不存在修正参数后重试同一个工具或改用其他工具/向用户说明情况。这是 Pi 长时间自主运行能力的关键一环错误不再等于会话中断而是变成模型可消费的输入。三层之外的健壮性实践注册自定义工具时的错误契约在 10-custom-tools-giving-the-llm-new-abilities.md 描述的registerTool()中execute的签名types.ts为execute( toolCallId: string, params: StaticTParams, signal: AbortSignal | undefined, onUpdate: AgentToolUpdateCallbackTDetails | undefined, ctx: ExtensionContext, ): PromiseAgentToolResultTDetails;结合本文三层模型写扩展工具时应注意工具内自行捕获预期错误如果某些失败是可预期的业务失败如文件不存在端口被占用直接在execute内返回错误文本内容而非抛异常这样错误消息更加可控、可读性更好也避免多层重抛的开销处理signalsignal是AbortSignal工具执行期间应监听它及时中止耗时操作配合onUpdate汇报进度避免工具长时间挂起拖慢 agent 循环不依赖tool_result兜底做业务逻辑isError: true的广播是给扩展观察用的工具的最终错误呈现仍以抛错/返回文本为准。命名与资源冲突的诊断式错误除了运行时错误Pi 还对扩展注册阶段的冲突给出诊断而不是崩溃快捷键冲突getShortcuts会对与内置快捷键或扩展间快捷键冲突产生warning级诊断并跳过冲突项runner.ts命令冲突getRegisteredCommands对与内置命令、受保护命令如gsd或其他扩展冲突的命令记录warning并跳过runner.ts诊断结果可通过getShortcutDiagnostics()/getCommandDiagnostics()读取runner.ts。这些诊断同样遵循扩展出错不影响宿主的原则把冲突降级为可见的警告而非致命错误。错误观测建议由于扩展错误默认只进监听器不会中断任何流程为了不静默丢失故障建议扩展作者在开发期自行onError注册一个把ExtensionError打印到标准错误的监听器便于调试结合 27-testing-extensions.md 为每个 handler 编写抛错场景的测试验证扩展在 handler 抛错时不会影响其他功能利用ExtensionError的extensionPathevent字段做结构化归因而不是只记录散落的错误消息。总结Pi 扩展系统用三层错误模型回答了一个关键问题当第三方代码在宿主进程里失败时如何把损失降到最低、把信息送到最有用处。事件 handler出错 → 记录ExtensionErroragent 继续可用性优先tool_call拦截出错 → 阻断工具执行安全优先fail closed工具execute出错 → 以isError: true送回 LLM可恢复性优先。三层语义清晰、职责互补共同支撑了 Pi 让 agent 长时间自主运行而不因扩展故障中断的设计目标。掌握这套模型后你可以更自信地编写扩展知道哪些错误会被安全吸收、哪些会阻断执行、哪些会呈现给模型——从而在设计阶段就为每个失败点选择正确的处理策略。相关扩展生命周期与架构背景可继续参考 02-architecture-mental-model.md 与 06-the-extension-lifecycle.md。赞分享人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载相关推荐goose 错误处理架构传统错误与 LLM 可见的 Agent 错误双层模型goose 错误处理架构传统错误与 LLM 可见的 Agent 错误双层模型 goose 将错误处理视为驱动 Agent 性能的核心机制LLM 的非确定人工智能大模型AI AgentAI 应用本地部署MCP ClientsMCP 服务工具调用桌面应用CLIminiserve错误处理机制Rust错误类型系统的实战应用miniserve错误处理机制Rust错误类型系统的实战应用 miniserve作为一个轻量级的HTTP文件服务器在处理文件服务、上传、删除等复杂操作时其CLI后端终极指南掌握yargs错误处理机制中的fail与exitProcess方法终极指南掌握yargs错误处理机制中的fail与exitProcess方法 yargs是一个强大的Node.js命令行参数解析库其错误处理机制是确保CLI应CLI开发工具上一篇【亲测免费】 探索声音的数字之旅esp32_SoundRecorder项目解读下一篇开源歌词工具163MusicLyrics跨平台歌词获取与批量管理的终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
