工具调用链路与扩展点介绍
本节说明一次 GPA MCP 工具调用从 LLM 发起到结果返回的完整链路，以及各类扩展代码分别挂在哪个位置。理解调用链路后，再进入开发准备和具体场景会更容易判断应该配置哪个 Handler。
调用链路
扩展点说明
| 钩子 | 工具 JSON 字段 | 执行时机 | 能做什么 | 默认函数名 |
|---|---|---|---|---|
| preHandler | preHandler |
业务执行之前 | 校验/改写 arguments、tool_config；可中断执行 | pre_handle |
| resultHandler | resultHandler |
业务执行成功之后 | 改写/重建最终结果 ctx.result | handle_result |
| postHandler | postHandler |
结果确定之后、返回给 LLM 之前 | 做副作用（记录、通知等），不改返回值 | post_handle |
| 自定义 businessHandler | businessHandler |
替代整个②段 | 完全自己实现业务逻辑（如调用外部 API） | handle |
大多数需求可以按扩展点选择：需要在执行前校验或改写请求时阅读场景一：自定义调用前逻辑；工具的执行逻辑完全不是“调用 GPA 算子”或“查询数据目录”等内置模式时阅读场景二：自定义业务处理；需要调整返回给 LLM 的内容时阅读场景三：自定义返回结果；需要在执行后记录日志、审计或通知外部系统时阅读场景四：自定义调用后逻辑。
异常行为说明
四段钩子的失败语义并不一致—业务已经执行成功之后的 postHandler 出错不应该让用户拿不到结果，但结果尚未产出前的 preHandler/resultHandler 出错必须阻断，避免带着无效数据继续往下走。开发钩子函数时请对照下表处理异常：
| 阶段 | 出错行为 |
|---|---|
| preHandler 抛 HandlerAbort | 阻断，把 message/suggestions 包成错误返回给 LLM |
| preHandler 抛其他异常 | 阻断，返回通用错误 |
| resultHandler 抛任何异常 | 阻断，返回错误（同 preHandler，不含 suggestions 除非也用 HandlerAbort） |
| postHandler 抛任何异常 | 不阻断，只记 warning 日志，正常把结果返回给 LLM |
| 自定义 businessHandler 中 ctx.result 表示失败 | 按标准错误响应处理，跳过 postHandler |
| 文件不存在 / 函数不存在 / 模块 import 失败 | 阻断，返回 "Handler configuration error"——不会静默跳过，工具调用直接失败，方便第一时间发现配置写错了 |
理解了扩展代码的执行顺序后，请继续阅读开发准备，完成目录、配置字段和钩子函数签名的准备工作。