Hermes Toolsets Config

Hermes 工具集配置与验证

管理 agent.disabled_toolsets / platform_toolsets 等工具集配置，并用受控实验证明工具可见性断言。与 tool-visibility（诊断"工具为何缺失"的排查方法论）互补：本技能管配置与验证，那个管诊断。

When to Use

• 工具集被禁用/需恢复（如 disabled_toolsets 包含 skills/memory/search/delegation）
• 修改 config.yaml 的工具集相关配置（hermes config set/unset 通道）
• 需要断言"工具 X 可见/不可见"时——先实验后结论
• 排查"会话工具列表与配置不一致"（生效时机疑问）

关键机制（2026-08-03 受控实验验证）

disabled_toolsets 的真实效果

⚠️ 不要把 "core tools are preserved" 泛化：它只保护 hermes-* bundle 被禁的场景；独立 toolset 禁用直接移除其工具（包括核心）。源码注释有适用边界。

生效时机

• 工具列表在 agent 构建时快照（agent.tools）；配置修改后重启或新会话生效
• get_tool_definitions 有缓存（key 含 cfg_fp：config mtime+size），config 写入后下一次调用全量重算

受控实验 — 验证工具可见性（不碰 config，纯内存）

不要靠源码注释推断、不要靠 tool_search（只索引 deferred/MCP/插件，核心工具永不 defer——搜不到 ≠ 不可见）。用 get_tool_definitions 模拟：

cd <hermes-agent 源码目录>
<venv>/python scripts/verify_toolset.py --disabled skills,memory

（本技能自带可运行脚本 scripts/verify_toolset.py——--disabled 模拟禁用列表、--check 指定待查工具。以下为等效内联版：）

⚠️ 返回元素结构是 {'type','function'}——取名字用 d['function']['name']，不是 d['name']（后者全为 None，集合塌缩成 1 个元素，曾致实验误判）。

配置修改通道

• config.yaml 是安全敏感文件：patch/write_file 工具会被 Hermes 拒绝（"Agent cannot modify security-sensitive configuration"）——不要绕过，用官方通道
• 删除键：hermes config unset agent.disabled_toolsets（删除后默认 []）
• 设置标量：hermes config set <key> <value>（数字/字符串 OK）
• 设置列表：hermes config set 不支持——会写成 JSON 字符串（cli: '["a","b"]'，YAML 解析后是字符串而非列表）。需用 Python 精确改写文件（备份先行）或 hermes config edit
• 修改前备份：cp config.yaml config.yaml.bak.$(date +%s)

Pitfalls

• 断言前必须验证：声称"工具 X 不可用/可用"须满足其一——(a) 实际调用该工具；(b) get_tool_definitions 受控实验；(c) state.db 调用痕迹。源码注释推断不足为凭（2026-08-03 两次断言错误均因此）
• "生效 provider/通道" ≠ 配置（2026-09 第三次同类断言错误，错在配置层）：plugins.enabled: web/<vendor> / web.search_backend 只是意图——插件「已启用／已注册／依赖可导入／实际生效」是四件事。回答"web_search/web_extract 实际走了谁"的唯一权威证据是 logs/agent.log 的 Web search via <provider> / Web extract via <provider>（tools/web_tools.py 每次调用打 INFO）；hermes tools list 只说明 toolset（web ✓ enabled）是否启用，不含 provider 名。向用户报告"用了哪条检索通道"前先 grep 日志，不要据技能文档/记忆里的"某引擎是首选"下结论。完整优先级、能力/凭据矩阵与切换表：references/web-provider-routing.md
• 手工探测可能不等于真实 agent 进程：在独立 python 里调 get_active_search_provider() / _get_backend() 会缺插件发现、缓存与 .env 上下文，可能得到与真实进程不同的名字——探测只用来比对各源顺序，最终结论以日志为准
• tool_search 搜不到 ≠ 工具不可见：核心工具永不 deferral，tool_search 找不到是正常设计
• CLI 工具集管理不覆盖插件工具集：hermes tools enable a2a 报 Unknown toolset 'a2a'、hermes tools list 不显示插件工具集——均属正常，不是故障。插件启用时 register_tools() 无条件注册其工具（plugins/<name>/__init__.py 的 register(ctx) 钩子 → ctx.register_tool(toolset="<name>")），不经 hermes tools 管理、也无法用它启用。断言插件工具已注册的证据：Agent Card skills（GET /.well-known/agent-card.json → skills[].id == "toolset.<name>"）或 get_tool_definitions 受控实验，而非 CLI 列表。插件工具集随 gateway 重启/新会话注册（2026-08-05 A2A 启用实证；完整流程见 hermes-plugins-install 的 references/a2a-platform-enablement.md）
• 平台服务器启动有异步延迟：gateway_state.json 显示 platforms.<name>.state: connected 后，端口可能尚未监听（curl HTTP 000）；等待数秒重试即 200。验证"生效"以实际 HTTP 探针为准，不以状态文件为准
• git 命令形态：数据仓库在 F:\AI\Hermes\hermes-state-git\.git（worktree=F:/AI/Hermes/hermes）；hermes 目录内直接 git 报 not a repository；git -C <repo> add <相对路径> exit 0 但静默不生效（相对路径解析到仓库目录而非工作树）。正确：git --git-dir=../hermes-state-git/.git --work-tree=. add ...
• 恢复后生效：清除禁用后需重启或新会话，当前会话工具列表不变（构建时快照）

相关技能

• tool-visibility：诊断"工具为何缺失"（user-owned / PENDING_REVIEW——如需维护先 hermes curator adopt tool-visibility）
• memory-storage-management：记忆修改流程 + 版本管理约定
• web-search（user-owned，本技能无权改）：搜索/抓取链路与反爬工具能力声明；其中"ddgs = 首选引擎""web_extract 不可用"类静态结论已与实际脱钩，provider 归属一律以 references/web-provider-routing.md 的日志实证为准。如需维护该技能：hermes curator adopt web-search