文件存放目录

custom_handlers/ 是 GPA MCP 服务容器内的目录，对应产品包目录 /cfg/gpa_mcp/v2_handlers/，生产环境通过 Docker Volume 挂载。部署人员只需将编写好的 .py 文件放入该产品包目录，容器内 custom_handlers/ 目录中便会同步出现该文件。

生效时机

改动或新增 .py 文件之后不需要重启容器：服务按文件的修改时间（mtime）检测变化，下次调用引用该文件的工具时会自动重新加载，与工具 JSON 配置的热加载节奏一致。

验证方法

建议先在测试环境按照前几节的示例写一个最小可用版本，用支持该工具的 LLM 客户端（或直接调用 MCP 接口）触发一次调用，确认以下几点：

• 调用前校验失败时，能看到您写的修改建议；
• 调用后记录、结果改写等效果符合预期；
• 故意把文件名或函数名写错一次，确认能看到 "Handler configuration error" 而不是被静默忽略——这是设计上的行为，不是缺陷。

上线前注意事项

• Handler 在服务进程内以全部权限执行（可读环境变量、可访问内网），不做沙箱——这跟直接改服务代码是同一个信任级别，请当作生产代码来写，并走代码评审；
• 不要在这里写会阻塞事件循环的同步耗时操作（比如用 requests 而不是 httpx/aiohttp 做网络请求），会拖慢整个服务的并发处理能力；
• 只有部署人员能接触到这个目录，不支持终端用户通过界面上传 Handler 代码；如果未来出现该需求，必须另行设计沙箱方案（子进程隔离＋资源限制＋受限 API），不能直接复用本机制。