Agent 插件如何安全加载与卸载？验收钩子、资源和回退

Agent 扩展可以新增工具、拦截调用、监听目录或保持连接。删掉文件、关闭配置，不足以证明这些效果已经停止。过时的审批回调仍可能影响写入；旧会话的 watcher 仍可能读取文件。发布前应把插件当作一组有生有灭的能力和资源验收，包含重载与失败之后还剩什么。

工具调用契约定义单项可调用操作，Skill 判断卡决定何时封装重复指令。本文处理的是加载到 Agent 宿主中的可执行代码。恢复手册应对已经产生效果的事故；这里先检查日常变更是否让旧代码和资源残留。

别把三种钩子混为一谈

钩子名称及清理保证取决于框架与版本。下表是核对文档的起点，仍要在目标版本上实测。

系统	文档描述的接入方式	需要验证的生命周期含义
Pi Extensions	扩展工厂注册工具、命令和 pi.on() 事件。当前文档称 pi.on() 返回取消订阅函数，reload 会替换扩展运行时；会话长期资源应从 session_start 启动，在 session_shutdown 幂等关闭。	验证旧钩子不再影响新调用，自己打开的 watcher、计时器或 socket 已关闭。文档称处理器错误会在可能时报告并继续，但 tool_call 处理器错误会阻断该工具；不能套用到所有事件。
Cordis core 与 Primer	Primer 介绍通过 ctx.effect() 或 ctx.on() 做作用域注册，并为可逆副作用提供 disposer。	在固定版本上检查实际作用域与撤销顺序。Cordis core 明示 API 仍不稳定；Primer 示例不是所有 Cordis 宿主的永久契约。
OpenAI Agents SDK Python	RunHooks 与 AgentHooks 在 Agent、交接和工具事件周围提供回调。	这些是运行过程钩子；它们的存在不能证明宿主提供插件加载、热重载或后台资源自动清理。那些行为需要应用自己负责。

Pi 文档还说明扩展在 Pi 进程内运行，具有同一操作系统权限。注册表或回调不是系统沙箱。加载前检查来源、版本、文件和网络权限、凭据及数据访问范围；在宿主和部署环境限制能力，再对真实边界做测试。

启用之前，列出所有注册与资源

对一个版本盘点注册项：工具名称及 schema、命令、事件及结果类型、模型提供方、UI 元素、权限或审批钩子。另列代码创建的资源：watcher、计时器、socket、子进程、文件句柄、队列订阅和未完成异步任务。每项都写负责人、创建点和释放动作。区分它属于进程、插件实例、会话还是单次 Agent 运行；这些生命周期不能互换。

建立一个小状态模型：未启用 → 初始化 → 生效 → 停止接新工作 → 已释放。这是本站的发布测试方法，不代表三个框架都暴露这些状态。初始化中把已完成的注册和资源写进台账，以便中途失败时逐项撤销。停止时先不再接收新工作，再按约定等在途任务结束或取消，注销钩子、关闭资源并检查残留能力。清理函数应允许调用两次。

事件监听器返回的取消订阅函数，只管该监听器，不一定管回调内部创建的 watcher。disposer 可以撤销进程内注册，却不能收回已发邮件或撤销已完成的数据库写入。外部操作要有独立台账、操作编号及核实或补偿负责人。

测事件错误，再测重复加载

逐个写清扩展处理的事件：只通知、变换数据、可以阻断动作，还是会产生外部效果。记录声明的返回类型、处理顺序、出错行为，以及已经开始分发的事件是否仍会调用刚移除的处理器。不能凭另一个 SDK 中相似的事件名推断语义。

审批关卡应在宿主强制执行路径中失败即拒绝。回调抛错、超时，或只加载了一半时，危险写入仍应被拒绝。Pi 当前针对失败的 tool_call 处理器记录了阻断规则；其他事件或宿主可能只是记日志并继续，因此必须测试具体路径。纯观察事件有时可以失败而不中断运行，但仍要满足产品对审计记录的要求。

使用合成动作执行固定验收序列：

1. 从干净状态启用 A 版。确认各预期能力只出现一次，一次事件只触发一次回调。
2. 热重载到 B 版，再热重载一次 B 版。每次都触发同一事件；确认仅有一个现行回调、使用现行规则，A 版没有留下回调或资源。已经在途的事件另测，因为取消订阅未必改变本次分发列表。
3. 禁用扩展。确认旧工具和命令既不可发现也不可调用，不再触发回调，watcher／计时器／socket 均关闭；即使旧客户端记住了工具名，宿主也要拒绝其能力。
4. 在完成一项注册和创建一项资源后注入初始化失败。确认半成品实例已撤销，此后仍可干净加载；重复清理一次以发现双重关闭错误。
5. 注入处理器错误和关闭超时。确认规定的放行或阻断结果、可见诊断、在途任务去向，以及未确定外部效果的负责人。

对照前后注册表、回调次数、打开资源数与受控外部操作日志。“重载完成”提示本身不能证明旧权限消失。

案例一：审批钩子重复注册

一个财务助手的扩展要求审核人批准确切收款方和金额后，才允许调用付款提交工具。A 版注册钩子；开发者重载 B 版收紧规则，又重载一次。在有缺陷的宿主接入中，A 版回调没有撤销，B 版又注册了两次。一次提交触发三个审批提示，更危险的是旧回调可能仍按过时规则放行。

测试记录合成操作编号、回调版本及实例编号、最终决定。预期只有一个现行规则作决定，任何写入前还要通过后端授权检查。让 B 版回调抛错，确认付款保持阻断。禁用扩展后再试相同工具名：宿主不能在审批关卡消失时仍允许付款工具运行。若关闭审批插件就必须一并关闭写入工具，应把这种依赖写入宿主配置。

试验不发送真实付款。若写入在重载前已经越过边界，移除钩子无法撤销；应由操作台账和恢复规则决定下一步。

案例二：文件 watcher 跨会话泄漏

一个研究扩展监听获准输入文件夹，发现新文件时发出“可用来源”事件。它在会话开始时开启 watcher，却只在会话结束时移除事件监听器。下个会话再开一个 watcher；两次重载后，一次文件变化产生多次事件，旧实例还可能读取新会话不该使用的目录。

验收试验使用临时合成文件夹，记录 watcher 实例编号、会话编号、打开句柄数量和事件次数。先开一个会话、改动一个文件、结束会话，再开另一个会话并改动一个文件。每个活动会话只应收到自己预期的一次事件；结束和禁用后，新变化不应通知任何旧实例。还要在创建 watcher 后立即注入失败，证明半成品资源会关闭。如果关停时已有回调正在处理变化，应测试取消或排空规则，确认它不会把消息发布到后续会话。

填写插件发布验收表

用下面的工作台登记能力、资源、事件语义和测试证据。它在浏览器中保存草稿，只写合成编号与受控证据位置。复核者应能指出任何残留能力，并决定是否阻断发布。

检查项	通过证据
加载与中途失败	确切版本及可信来源；预期注册／资源；初始化失败没有留下活跃半成品
事件契约	逐事件的返回及错误语义；审批故障经强制执行路径阻断写入
两次重载	每个事件只有一个现行回调；旧工具、命令、权限、watcher 与在途任务处理清楚
禁用	旧名称不可调用；资源和权限无残留；依赖的写入工具仍受保护
外部效果	已完成和未知写入都有操作编号及负责人；清理不声称会自动撤销它们

常见问题

**agent_end 表示可以释放插件的全部资源吗？**不是。Pi 中该事件后仍可能继续自动重试或队列工作，文档把会话资源清理放在 session_shutdown；OpenAI Agents SDK 的 Agent 结束回调属于运行钩子，不是插件卸载事件。

**disposer 会取消已经运行的回调吗？**不能默认如此。Pi 明确说取消订阅不影响已经开始的分发。需要停止标志或取消规则，并实测宿主的在途处理。

**热重载成功就表示已回滚吗？**不是。它只能验证注册与资源是否替换。外部写入需要独立操作台账、状态查询和获授权的修正路径。

不适用边界

本表验收指定宿主和版本中的可执行插件行为，不能证明不可信代码已隔离、事件钩子自身足以强制授权，也不能把 Pi 的错误语义或 Cordis 的 effect 管理套到每个框架。API 版本和嵌入方式会变。插件、宿主、事件契约、权限或依赖发生变化时重跑试验；不可逆外部效果仍需自己的审批与恢复控制。