# Hermes Toolsets Config

> Use when 配置/恢复 Hermes 工具集、验证工具可见性断言。含受控实验。

- Skill: `yyyyyhhhhh0639/hermes-toolsets-config` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add yyyyyhhhhh0639/hermes-toolsets-config`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yyyyyhhhhh0639/hermes-toolsets-config/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: yyyyyhhhhh0639 (https://skillmd.com/u/yyyyyhhhhh0639)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/yyyyyhhhhh0639/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 的真实效果

| 禁用目标 | 效果 | 证据 |
|:--|:--|:--|
| 独立 toolset（`skills`、`memory`、`search`…） | **移除注册在该 toolset 的全部工具**——即使它们同时在 `_HERMES_CORE_TOOLS` 里 | 受控实验：禁 skills → skill_view/skills_list/skill_manage 消失；禁 memory → memory 消失 |
| `hermes-*` 平台 bundle（hermes-cli 等） | **仅移除非核心增量**（`bundle_non_core_tools`），核心工具保留 | model_tools.py:416-424 "core tools are preserved" |

⚠️ **不要把 "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` 模拟：

```bash
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`