Hermes 输入 @ 就报 NameError: self is not defined？fuzzy file completions 排错指南

在 Hermes Agent CLI 里，@ 通常用来触发文件上下文补全：你输入 @src/...，CLI 会帮你模糊搜索项目文件，并把文件作为上下文交给模型。

但有些版本里，只要输入 @，就会直接抛出异常：

Exception name 'self' is not defined
  File "hermes_cli/commands.py", line 806, in _context_completions
    yield from self._fuzzy_file_completions(word, query, limit)

这不是模型 API 问题，也不是 DeepAI / OpenAI / Anthropic 配置问题，而是 Hermes CLI 自身的 Python 方法绑定 bug。

本文基于 NousResearch/hermes-agent issue #9531，整理 @ fuzzy file completions 报 NameError: name 'self' is not defined 的原因、临时绕过方法和升级建议。

典型症状

你可能遇到这些现象：

Hermes CLI 正常启动；
普通聊天能用；
输入普通文本不会报错；
但一输入 @，或准备引用文件路径时，CLI 立刻异常；
报错里出现 _context_completions；
关键错误是：

NameError: name 'self' is not defined

常见搜索关键词包括：

Hermes @ NameError self is not defined
Hermes fuzzy file completions self not defined
hermes_cli commands.py _context_completions
Hermes input @ crash
Hermes file completion bug

根因：staticmethod 里调用了 self

issue #9531 里给出的根因非常明确：

_context_completions is decorated with @staticmethod but calls self._fuzzy_file_completions(...)

也就是说，代码结构类似这样：

@staticmethod
def _context_completions(...):
    yield from self._fuzzy_file_completions(word, query, limit)

问题在于：

@staticmethod 不会自动接收实例对象；
方法体里却使用了 self；
运行到 self._fuzzy_file_completions(...) 时，Python 找不到 self；
于是抛出 NameError: name 'self' is not defined。

所以这不是用户按错键，也不是文件路径不存在，而是函数定义方式和调用方式不匹配。

为什么只有输入 @ 才触发？

因为这个 bug 位于上下文补全逻辑里。

Hermes CLI 只有在你输入 @、准备触发文件上下文补全时，才会进入 _context_completions 这条路径。

所以你会看到一个很迷惑的现象：

hermes 启动正常；
API Key 正常；
模型回复正常；
甚至普通 /command 也正常；
但一输入 @ 就崩。

排查时不要先去改模型配置，而应该先定位 CLI 版本和 hermes_cli/commands.py 的补全代码。

这个 bug 是怎么引入的？

issue 描述提到，它由 PR #9467 引入：

feat: improve file search UX — fuzzy @ completions

也就是说，这是一次改善文件搜索体验的功能改动，新增或重构了 fuzzy @ completions，但留下了 @staticmethod 与 self 不匹配的问题。

评论中随后出现多个修复 PR，例如：

#9563：移除 @staticmethod，添加 self 参数；
#9546、#9619、#9638、#9649、#9683、#9692、#9725 等相关重复修复或关联 PR；
评论最终指出：This issue has been fixed in #9683。

这说明该问题并不是个别环境导致，而是当时某些版本的已知 bug。

临时解决：不要使用 @ 文件补全

如果你暂时不能升级，可以先绕过 @ 补全。

例如，不要输入：

@src/main.py 请解释这个文件

改成显式粘贴路径或说明：

请读取 src/main.py 并解释这个文件

如果 Hermes 有其他文件读取命令或工具，也可以用命令形式传文件路径，避免触发交互式 fuzzy completion。

这个 workaround 的核心是：不要走 _context_completions 这条代码路径。

如果你能改源码：删除 @staticmethod

如果你正在本地开发 Hermes，可以检查：

hermes_cli/commands.py

找到 _context_completions。

如果它写成了：

@staticmethod
def _context_completions(...):
    ...
    yield from self._fuzzy_file_completions(...)

就需要改成实例方法：

def _context_completions(self, ...):
    ...
    yield from self._fuzzy_file_completions(...)

核心修复就是：

去掉 @staticmethod；
让方法接收 self；
确保调用 _fuzzy_file_completions 时有实例上下文。

当然，更推荐直接升级到官方已修复版本，而不是长期维护本地 patch。

修复后又卡顿？注意文件扫描性能问题

issue 评论里还有一个值得注意的后续反馈：

> 修复后，输入 @ 时 popup 变慢，会冻结几秒。

随后评论解释：文件扫描曾经在主线程执行，有时超过 1 秒，通常也有 500ms 左右。后续通过异步扫描、独立线程优化，对应 issue #9740 和 PR #9741。

所以 @ 补全相关问题可能分成两类：

问题	典型表现	根因
`NameError: self is not defined`	输入 `@` 直接异常	`@staticmethod` 里调用 `self`
输入 `@` 后卡顿	popup 慢、CLI 短暂冻结	文件扫描在主线程执行

如果你升级后不再崩溃，但仍然卡顿，要继续关注文件扫描性能优化，而不是回头排查 self。

排查清单

遇到 Hermes 输入 @ 崩溃时，可以按这个顺序排查：

1. 记录完整 traceback； 2. 确认是否包含 _context_completions； 3. 确认错误是否为 NameError: name 'self' is not defined； 4. 检查 Hermes 版本是否包含 fuzzy @ completions 改动； 5. 升级到包含 #9683 修复的版本； 6. 如果无法升级，临时避免使用 @ 补全； 7. 如果本地开发，移除 _context_completions 的 @staticmethod 并加入 self； 8. 如果修复后卡顿，再排查异步文件扫描优化。

这和 API Key、模型供应商无关

很多 Hermes 报错第一反应是检查：

API Key；
Base URL；
model name；
provider；
OpenAI-compatible endpoint；
DeepAI API 中转站配置。

但这个问题发生在 CLI 输入补全阶段，甚至还没真正发起模型请求。

所以：

NameError: self is not defined in _context_completions

不应该从 API 层排查，而应该从 Hermes CLI 代码和版本排查。

DeepAI API 中转站用户要注意什么？

如果你使用 DeepAI API 中转站为 Hermes 或其他 AI 编程工具提供 OpenAI-compatible 接口，这类问题不会由中转站造成。

DeepAI API 中转站主要解决的是：

模型 API 入口统一；
Base URL 配置；
API Key 管理；
多工具接入 OpenAI-compatible API。

但 @ 文件补全是 Hermes CLI 的本地交互功能，它在模型请求之前就执行。

因此，如果你看到的是：

NameError: name 'self' is not defined

请先升级 Hermes 或修复 CLI 代码；如果看到的是 401、404、model not found、timeout，再回到 DeepAI / provider / base_url 配置层排查。

FAQ

输入 @ 就崩，是文件路径不存在吗？

通常不是。NameError: self is not defined 是代码 bug，和文件是否存在没有直接关系。

为什么普通聊天没问题？

因为普通聊天不会进入 _context_completions。只有输入 @ 触发文件补全时才会走到 bug 代码。

改 API Key 有用吗？

没用。这个错误发生在 CLI 补全层，不是模型请求层。

最小修复是什么？

去掉 _context_completions 上的 @staticmethod，并让它接收 self。

修复后 @ 补全很慢怎么办？

那是另一个性能问题，可能与文件扫描在主线程执行有关。关注异步扫描相关修复，例如 issue #9740 / PR #9741。

总结

Hermes 输入 @ 就报：

NameError: name 'self' is not defined

核心原因是 _context_completions 被定义成 @staticmethod，但内部调用了 self._fuzzy_file_completions(...)。

这类问题的排查方向不是 API Key、Base URL 或模型供应商，而是 Hermes CLI 的补全代码和版本。

一句话：普通聊天正常、输入 @ 才崩时，先查 _context_completions，不要先改模型配置。