通用会话扩展¶

适用范围：独立 Python Runtime；扩展开发者。 会话扩展用于受信任插件接管会话策略与原生消息流程。普通工具插件仍使用工具注册与观察性钩子。

注册与所有权¶

实现 RuntimeExtension，通过 PluginContext.register_runtime_extension 注册。会话策略只允许一个所有者，重复或冲突注册会失败。严格模式和兼容模式都要求 hook.register 权限。

扩展必须列入 plugins.required。必需插件缺失、被禁用、权限不足或激活失败时，系统阻止启动并清理已激活插件资源。安装使用已有的插件入口或目录发现机制。

配置验证与恢复发生在消息处理之前。事件处理、回合前置处理与展示策略共同控制输入和响应；会话范围、记忆命名空间、流式输出和系统指令由扩展管理。

允许工具模式定义扩展拥有的工具目录，操作者的拒绝规则、安全档位与执行网络策略继续生效。扩展对象保存在私有运行状态中，不序列化到配置或模型上下文。

运行时方法失败向宿主传播。绑定失败阻止启动；工具目录策略失败后，模型目录选择与实际工具执行继续检查故障状态，直到受信任刷新成功。此类控制不能使用观察性钩子的失败放行行为。

MCP 集成调用扩展的绑定、连接配置与适配器构建接口。私有操作可以隐藏；适配器必须保留已验证的注册名称。整个目录验证完成后原子替换，失败时不保留部分工具。

投递记录接收真实的最终通道回执，普通发送与流式最终发送分别记录。管理员恢复发送时，使用已保存的原始入站事件记录恢复回执。需要用户澄清时，保留真实问题与选项，不用普通状态摘要替换提问。

插件自己的 Gateway 端点负责自身认证，通用宿主不解释项目特定协议。

会话扩展是受信任的进程内 Python 代码，注册权限不构成操作系统隔离。项目服务仍需验证业务权限与事务。相关接口见 Plugin API和开发插件。