插件兼容性声明文件（临时方案）

2026年9月进行的功能拆分（PR #102117）将Hermes Agent中的大型模块拆分为了更独立的文件。内部导入路径并非稳定接口，在该PR之后，下方列出的那些名称已不再存在于原来的位置。为给外部插件开发者留出更新时间，目前仍可通过在对应模块后添加PLUGIN-COMPAT块，从旧模块中导入这些名称。

**此临时方案将于2026-09-14被移除。**它是通过一个单独的提交添加的，未来也会通过回滚该提交来删除。请立即将您的插件更新为从“新位置”列指定的路径进行导入。本仓库内的任何代码均不得使用这些旧路径（否则scripts/check_compat_pointers.py脚本会在持续集成测试中失败）。

受影响的插件将会出现以下情况：

时间节点	命令行提示 / `hermes doctor` / `hermes update`	桌面端	插件表现
2026-09-14之前	显示黄色警告，注明插件名称、日期以及`hermes plugins compat`相关信息	每次仅弹出一次模态窗口（针对所有受影响的插件集中显示）	仍可加载；每次尝试通过旧路径访问时都会触发一次`HermesPluginCompatWarning`警告
2026-09-14之后	显示红色警告：插件已禁用	每次仅弹出一次模态窗口	无法加载；`hermes plugins list`命令会显示禁用原因
回滚操作完成后	同上	同上	仍无法加载（因为旧路径已不存在）

对于无法等待开发者更新的用户，可采取以下应急方案：在config.yaml文件中设置plugins.allow_deprecated_imports: true，这样在日期之后受影响的插件仍可继续加载，直到回滚操作真正移除那些旧路径为止。

针对插件开发者： 运行命令 hermes plugins compat <插件文件路径>，该命令会输出每一行的 文件路径:行号、旧路径与新路径的信息；只要仍有未处理的条目，命令就会以状态码 1 退出。请从“新路径”一列中导入相应的文件。

系统会发出警告信息。 当某个进程首次通过这些机制解析某个名称时，Hermes 会生成一个 HermesPluginCompatWarning（属于 FutureWarning 类型），其中会注明旧路径、新路径以及被移除的目标——每个进程针对每个名称仅触发一次此类警告。修复导入问题后，该警告就会消失。若希望在迁移过程中屏蔽此警告，可使用以下命令：python -W ignore::hermes_cli.plugin_compat.HermesPluginCompatWarning 或 warnings.filterwarnings("ignore", category=HermesPluginCompatWarning)。

适用范围。 该机制仅适用于在模块顶层、分解操作之前定义或导入的公共名称（即不以下划线开头的名称）。私有名称（如 _foo、_TG_NAME_LIMIT、_clamp_telegram_names 等）从未暴露在模块接口中，因此不会被恢复；那些对这类私有名称进行了修补或导入的插件，必须将其替换为对应的公共名称或移至新的模块中。同样，通过临时修改实现的测试用例也不会被保留。

类型	数量	含义
moved	0	名称现定义于`新位置`；从旧模块重新导出
moved-lazy	1148	含义相同，通过`__getattr__`延迟解析以避免导入循环
import	592	旧模块曾用于暴露的第三方/标准库名称；已恢复原始导入
restored-def	290	因未被使用而被删除的公共名称；其分解前的原始定义被完整恢复
restored-helper	41	仅因上述某个restored-def需要而恢复的私有辅助函数
restored-import	17	仅因上述某个restored-def需要而重新添加的导入语句
module-stub	3	整个模块已被删除；由替代模块重新导出虚拟模块
unrestorable	34	无法恢复（例如循环变量泄漏）；为保持完整性而列出

名称	类型	新位置
`FutureTimeout`	import	`concurrent.futures`
`clear_edit_approval_requester`	restored-def	`(已删除；恢复了BASE主体)`
`get_edit_approval_requester`	restored-def	`(已删除；恢复了BASE主体)`

名称	类型	新位置
`ACP_MAX_MODELS_PER_PROVIDER`	已延迟移动	`acp_adapter.model_catalog`
`AgentThoughtChunk`	已导入	`acp.schema`
`AudioContentBlock`	已导入	`acp.schema`
`AvailableCommand`	已导入	`acp.schema`
`AvailableCommandsUpdate`	已导入	`acp.schema`
`BlobResourceContents`	已导入	`acp.schema`
`EmbeddedResourceContentBlock`	已导入	`acp.schema`
`ImageContentBlock`	已导入	`acp.schema`
`Path`	已导入	`pathlib`
`ResourceContentBlock`	已导入	`acp.schema`
`TextResourceContents`	已导入	`acp.schema`
`UnstructuredCommandInput`	已导入	`acp.schema`
`base64`	已导入	`base64`
`json`	已导入	`json`
`unquote`	已导入	`urllib.parse`
`urlparse`	已导入	`urllib.parse`

名称	类型	新位置
`agent_runtime_owns_post_tool_hook`	已恢复定义	`(已删除；BASE内容已恢复)`
`intent_ack_continuation_enabled`	已恢复定义	`(已删除；BASE内容已恢复)`

Keyboard shortcuts

Hermes Agent Docs i18n