Hermes Agent 第三方插件接口向后兼容验证方法 技巧

升级Hermes Agent至v0.8+后插件失效，因运行时契约收紧；需检查pyproject.toml/setup.py中是否声明hermes-agent>=0.8.0、plugin.yaml含compatibility: context_v2、execute函数签名是否为def execute(context: ContextV2, args, *kwargs)。

当你升级 Hermes Agent 到 v0.8.0 或更高版本后，发现原有第三方插件突然无法加载、报 ImportError 或 execute() 函数调用失败，说明插件未通过向后兼容性验证——这并非偶然故障，而是 Hermes v0.8+ 对插件运行时契约进行了实质性收紧，旧版插件若未适配 context_v2 协议或引用已移除的内部模块，将被静默拒绝。

检查插件是否声明兼容目标版本

进入插件源码根目录，打开 pyproject.toml 或 setup.py，确认其中明确声明了对 Hermes Agent 的最低支持版本。若缺失 hermes-agent >= 0.8.0 字样，或仍写着 >= 0.6.0，则该插件未主动声明兼容新 ABI。

执行 pip show hermes-plugin-xxx，查看输出中 Requires 行是否包含 hermes-agent>=0.8.0。若显示为 hermes-agent>=0.6.0，说明安装时未触发版本校验，需强制重装。

验证插件元数据与入口协议一致性

插件必须提供 plugin.yaml 且顶层含 compatibility: context_v2 字段，否则 Hermes 默认按 v0.6 协议加载，但 v0.8+ 已禁用该旧协议。

若 plugin.yaml 中无 compatibility 字段，手动添加：
compatibility: context_v2
注意：该行必须顶格书写，不可缩进，否则解析失败。

检查 entrypoint 指向的 Python 函数签名是否为 def execute(context: ContextV2, *args, **kwargs)。若仍是 execute(context) 且 context 无类型注解，说明未升级上下文对象结构。

运行时符号兼容性诊断

第一步：启用调试模式并捕获真实错误
执行 export HERMES_PLUGIN_DEBUG=1，再运行 hermes run --log-level debug 2>&1 | grep -A 3 -B 3 "ImportError|AttributeError"。

第二步：定位缺失符号
若日志出现 ImportError: cannot import name 'get_config' from 'hermes.tools'，说明插件仍在调用 v0.7 中已废弃的工具函数。当前等效路径是 hermes.config.get_value("plugin.xxx")。

第三步：验证插件模块可独立导入
使用 Hermes 内置 Python 解释器执行：
/path/to/hermes-venv/bin/python -c "from your_plugin_module import execute; print(execute.__annotations__)"
若报错或输出为空字典 {}，证明函数未正确标注 context 类型，不满足 v0.8+ 的 runtime type check。

强制启用旧协议回退（仅临时调试）

方法一：修改 plugin.yaml 添加兼容开关
在 plugin.yaml 顶层添加：
legacy_mode: true
【注意：此字段仅用于临时验证，生产环境禁止启用】

方法二：启动时注入兼容标志
执行：
HERMES_LEGACY_PLUGIN_MODE=1 hermes run
该环境变量会绕过 context_v2 校验，但所有插件功能将降级运行，且无法使用新 API 特性。