better-dsh 0.2.5 → 0.3.0

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/developer-guide/adding-providers.md

@@ -1,459 +0,0 @@
----
-sidebar_position: 5
-title: "添加 Provider"
-description: "如何向 Hermes Agent 添加新的推理 provider——认证、运行时解析、CLI 流程、适配器、测试与文档"
----
-
-# 添加 Provider
-
-Hermes 已经可以通过自定义 provider 路径与任何 OpenAI 兼容的端点通信。除非你需要为某个服务提供一流的用户体验，否则不要添加内置 provider：
-
-- provider 专属的认证或 token 刷新
-- 精选的模型目录
-- setup / `hermes model` 菜单条目
-- 用于 `provider:model` 语法的 provider 别名
-- 需要适配器的非 OpenAI API 格式
-
-如果该 provider 只是"另一个 OpenAI 兼容的 base URL 和 API key"，一个命名的自定义 provider 可能就足够了。
-
-## 心智模型
-
-内置 provider 需要在几个层面保持一致：
-
-1. `hermes_cli/auth.py` 决定如何查找凭据。
-2. `hermes_cli/runtime_provider.py` 将其转换为运行时数据：
-   - `provider`
-   - `api_mode`
-   - `base_url`
-   - `api_key`
-   - `source`
-3. `run_agent.py` 使用 `api_mode` 决定如何构建和发送请求。
-4. `hermes_cli/models.py` 和 `hermes_cli/main.py` 使 provider 在 CLI 中可见。（`hermes_cli/setup.py` 自动委托给 `main.py`——无需在此处做任何修改。）
-5. `agent/auxiliary_client.py` 和 `agent/model_metadata.py` 保持辅助任务和 token 预算正常运作。
-
-核心抽象是 `api_mode`。
-
-- 大多数 provider 使用 `chat_completions`。
-- Codex 使用 `codex_responses`。
-- Anthropic 使用 `anthropic_messages`。
-- 新的非 OpenAI 协议通常意味着需要添加新的适配器和新的 `api_mode` 分支。
-
-## 首先选择实现路径
-
-### 路径 A——OpenAI 兼容 provider
-
-当 provider 接受标准 chat-completions 风格的请求时使用此路径。
-
-典型工作：
-
-- 添加认证元数据
-- 添加模型目录 / 别名
-- 添加运行时解析
-- 添加 CLI 菜单接线
-- 添加辅助模型默认值
-- 添加测试和用户文档
-
-通常不需要新的适配器或新的 `api_mode`。
-
-### 路径 B——原生 provider
-
-当 provider 的行为与 OpenAI chat completions 不同时使用此路径。
-
-当前代码库中的示例：
-
-- `codex_responses`
-- `anthropic_messages`
-
-此路径包含路径 A 的所有内容，另加：
-
-- `agent/` 中的 provider 适配器
-- `run_agent.py` 中用于请求构建、分发、用量提取、中断处理和响应规范化的分支
-- 适配器测试
-
-## 文件清单
-
-### 每个内置 provider 都必须修改
-
-1. `hermes_cli/auth.py`
-2. `hermes_cli/models.py`
-3. `hermes_cli/runtime_provider.py`
-4. `hermes_cli/main.py`
-5. `agent/auxiliary_client.py`
-6. `agent/model_metadata.py`
-7. 测试
-8. `website/docs/` 下的用户文档
-
-:::tip
-`hermes_cli/setup.py` **无需**修改。setup 向导将 provider/model 选择委托给 `main.py` 中的 `select_provider_and_model()`——在那里添加的任何 provider 都会自动出现在 `hermes setup` 中。
-:::
-
-### 原生 / 非 OpenAI provider 额外需要
-
-10. `agent/<provider>_adapter.py`
-11. `run_agent.py`
-12. 如果需要 provider SDK，则修改 `pyproject.toml`
-
-## 快速路径：简单 API key provider
-
-如果你的 provider 只是一个使用单个 API key 进行认证的 OpenAI 兼容端点，则无需修改 `auth.py`、`runtime_provider.py`、`main.py` 或下面完整清单中的任何其他文件。
-
-你只需要：
-
-1. 在 `plugins/model-providers/<your-provider>/` 下创建一个插件目录，包含：
-   - `__init__.py`——在模块级别调用 `register_provider(profile)`
-   - `plugin.yaml`——清单文件（name、kind: model-provider、version、description）
-2. 就这些。Provider 插件在任何代码首次调用 `get_provider_profile()` 或 `list_providers()` 时自动加载——捆绑插件（本仓库）和位于 `$HERMES_HOME/plugins/model-providers/` 的用户插件都会被加载。
-
-当你添加一个插件并调用 `register_provider()` 时，以下内容会自动接线：
-
-1. `auth.py` 中的 `PROVIDER_REGISTRY` 条目（凭据解析、环境变量查找）
-2. `api_mode` 设置为 `chat_completions`
-3. `base_url` 从配置或声明的环境变量中获取
-4. 按优先级顺序检查 `env_vars` 以获取 API key
-5. 为该 provider 注册 `fallback_models` 列表
-6. `--provider` CLI 标志接受该 provider id
-7. `hermes model` 菜单包含该 provider
-8. `hermes setup` 向导自动委托给 `main.py`
-9. `provider:model` 别名语法正常工作
-10. 运行时解析器返回正确的 `base_url` 和 `api_key`
-11. `--provider <name>` CLI 标志接受该 provider id
-12. 回退模型激活可以干净地切换到该 provider
-
-位于 `$HERMES_HOME/plugins/model-providers/<name>/` 的用户插件会覆盖同名的捆绑插件（`register_provider()` 中后写者获胜）——因此第三方可以在不编辑本仓库的情况下对任何内置 profile 进行 monkey-patch 或替换。
-
-参见 `plugins/model-providers/nvidia/` 或 `plugins/model-providers/gmi/` 作为模板，以及完整的 [Model Provider Plugin 指南](/developer-guide/model-provider-plugin)，了解字段参考、hook 用法和端到端示例。
-
-## 完整路径：OAuth 和复杂 provider
-
-当你的 provider 需要以下任何内容时，使用下面的完整清单：
-
-- OAuth 或 token 刷新（Nous Portal、Codex、Qwen Portal、Copilot）
-- 需要新适配器的非 OpenAI API 格式（Anthropic Messages、Codex Responses）
-- 自定义端点检测或多区域探测（z.ai、Kimi）
-- 精选的静态模型目录或实时 `/models` 获取
-- 带有特定认证流程的 provider 专属 `hermes model` 菜单条目
-
-## 第 1 步：选择一个规范的 provider id
-
-选择一个 provider id 并在所有地方使用它。
-
-代码库中的示例：
-
-- `openai-codex`
-- `kimi-coding`
-- `minimax-cn`
-
-该 id 应出现在：
-
-- `hermes_cli/auth.py` 中的 `PROVIDER_REGISTRY`
-- `hermes_cli/models.py` 中的 `_PROVIDER_LABELS`
-- `hermes_cli/auth.py` 和 `hermes_cli/models.py` 中的 `_PROVIDER_ALIASES`
-- `hermes_cli/main.py` 中的 CLI `--provider` 选项
-- setup / 模型选择分支
-- 辅助模型默认值
-- 测试
-
-如果这些文件之间的 id 不一致，provider 会感觉只接了一半线：认证可能正常，而 `/model`、setup 或运行时解析会静默地遗漏它。
-
-## 第 2 步：在 `hermes_cli/auth.py` 中添加认证元数据
-
-对于 API key provider，在 `PROVIDER_REGISTRY` 中添加一个 `ProviderConfig` 条目，包含：
-
-- `id`
-- `name`
-- `auth_type="api_key"`
-- `inference_base_url`
-- `api_key_env_vars`
-- 可选的 `base_url_env_var`
-
-同时在 `_PROVIDER_ALIASES` 中添加别名。
-
-使用现有 provider 作为模板：
-
-- 简单 API key 路径：Z.AI、MiniMax
-- 带端点检测的 API key 路径：Kimi、Z.AI
-- 原生 token 解析：Anthropic
-- OAuth / auth-store 路径：Nous、OpenAI Codex
-
-需要在此回答的问题：
-
-- Hermes 应该检查哪些环境变量，按什么优先级顺序？
-- provider 是否需要 base URL 覆盖？
-- 是否需要端点探测或 token 刷新？
-- 当凭据缺失时，认证错误应该显示什么？
-
-如果 provider 需要的不仅仅是"查找 API key"，请添加专用的凭据解析器，而不是将逻辑塞进不相关的分支。
-
-## 第 3 步：在 `hermes_cli/models.py` 中添加模型目录和别名
-
-更新 provider 目录，使 provider 在菜单和 `provider:model` 语法中正常工作。
-
-典型修改：
-
-- `_PROVIDER_MODELS`
-- `_PROVIDER_LABELS`
-- `_PROVIDER_ALIASES`
-- `list_available_providers()` 中的 provider 显示顺序
-- 如果 provider 支持实时 `/models` 获取，则修改 `provider_model_ids()`
-
-如果 provider 提供实时模型列表，优先使用它，并将 `_PROVIDER_MODELS` 保留为静态回退。
-
-此文件也是使以下输入正常工作的关键：
-
-```text
-anthropic:claude-sonnet-4-6
-kimi:model-name
-```
-
-如果此处缺少别名，provider 可能认证正常，但在 `/model` 解析中仍然失败。
-
-## 第 4 步：在 `hermes_cli/runtime_provider.py` 中解析运行时数据
-
-`resolve_runtime_provider()` 是 CLI、gateway（网关）、cron、ACP 和辅助客户端共用的路径。
-
-添加一个分支，至少返回包含以下内容的字典：
-
-```python
-{
-    "provider": "your-provider",
-    "api_mode": "chat_completions",  # or your native mode
-    "base_url": "https://...",
-    "api_key": "...",
-    "source": "env|portal|auth-store|explicit",
-    "requested_provider": requested_provider,
-}
-```
-
-如果 provider 与 OpenAI 兼容，`api_mode` 通常应保持为 `chat_completions`。
-
-注意 API key 优先级。Hermes 已经包含避免将 OpenRouter key 泄露给无关端点的逻辑。新 provider 应同样明确地指定哪个 key 对应哪个 base URL。
-
-## 第 5 步：在 `hermes_cli/main.py` 中接线 CLI
-
-在交互式 `hermes model` 流程中出现之前，provider 是不可发现的。
-
-在 `hermes_cli/main.py` 中更新以下内容：
-
-- `provider_labels` 字典
-- `select_provider_and_model()` 中的 `providers` 列表
-- provider 分发（`if selected_provider == ...`）
-- `--provider` 参数选项
-- 如果 provider 支持登录/登出流程，则更新相应选项
-- 一个 `_model_flow_<provider>()` 函数，或者如果适用则复用 `_model_flow_api_key_provider()`
-
-:::tip
-`hermes_cli/setup.py` 无需修改——它调用 `main.py` 中的 `select_provider_and_model()`，因此你的新 provider 会自动出现在 `hermes model` 和 `hermes setup` 中。
-:::
-
-## 第 6 步：保持辅助调用正常工作
-
-这里有两个文件需要关注：
-
-### `agent/auxiliary_client.py`
-
-如果这是一个直接 API key provider，在 `_API_KEY_PROVIDER_AUX_MODELS` 中添加一个廉价/快速的默认辅助模型。
-
-辅助任务包括：
-
-- 视觉摘要
-- 网页提取摘要
-- 上下文压缩摘要
-- 会话搜索摘要
-- 记忆刷新
-
-如果 provider 没有合理的辅助默认值，辅助任务可能会严重回退，或意外使用昂贵的主模型。
-
-### `agent/model_metadata.py`
-
-为 provider 的模型添加上下文长度，以保持 token 预算、压缩阈值和限制的合理性。
-
-## 第 7 步：如果 provider 是原生的，添加适配器和 `run_agent.py` 支持
-
-如果 provider 不是普通的 chat completions，将 provider 专属逻辑隔离在 `agent/<provider>_adapter.py` 中。
-
-保持 `run_agent.py` 专注于编排。它应该调用适配器辅助函数，而不是在整个文件中内联构建 provider 请求载荷。
-
-原生 provider 通常需要在以下地方进行工作：
-
-### 新适配器文件
-
-典型职责：
-
-- 构建 SDK / HTTP 客户端
-- 解析 token
-- 将 OpenAI 风格的对话消息转换为 provider 的请求格式
-- 如有需要，转换工具 schema
-- 将 provider 响应规范化为 `run_agent.py` 期望的格式
-- 提取用量和 finish-reason 数据
-
-### `run_agent.py`
-
-搜索 `api_mode` 并审计每个切换点。至少验证：
-
-- `__init__` 选择了新的 `api_mode`
-- 客户端构建对该 provider 有效
-- `_build_api_kwargs()` 知道如何格式化请求
-- `_interruptible_api_call()` 分发到正确的客户端调用
-- 中断 / 客户端重建路径正常工作
-- 响应验证接受该 provider 的格式
-- finish-reason 提取正确
-- token 用量提取正确
-- 回退模型激活可以干净地切换到新 provider
-- 摘要生成和记忆刷新路径仍然正常工作
-
-同时在 `run_agent.py` 中搜索 `self.client.`。任何假设标准 OpenAI 客户端存在的代码路径，在原生 provider 使用不同客户端对象或 `self.client = None` 时都可能中断。
-
-### Prompt 缓存和 provider 专属请求字段
-
-Prompt（提示词）缓存和 provider 专属的调节项很容易出现回归。
-
-代码库中已有的示例：
-
-- Anthropic 有原生的 prompt 缓存路径
-- OpenRouter 获得 provider 路由字段
-- 并非每个 provider 都应该接收每个请求端选项
-
-添加原生 provider 时，仔细检查 Hermes 只向该 provider 发送它实际理解的字段。
-
-## 第 8 步：测试
-
-至少修改保护 provider 接线的测试。
-
-常见位置：
-
-- `tests/test_runtime_provider_resolution.py`
-- `tests/test_cli_provider_resolution.py`
-- `tests/test_cli_model_command.py`
-- `tests/test_setup_model_selection.py`
-- `tests/test_provider_parity.py`
-- `tests/test_run_agent.py`
-- 原生 provider 的 `tests/test_<provider>_adapter.py`
-
-对于仅文档示例，确切的文件集可能不同。重点是覆盖：
-
-- 认证解析
-- CLI 菜单 / provider 选择
-- 运行时 provider 解析
-- agent 执行路径
-- `provider:model` 解析
-- 任何适配器专属的消息转换
-
-运行目标测试（或使用 `scripts/run_tests.sh`，它在独立子进程中运行每个文件）：
-
-```bash
-source venv/bin/activate
-python -m pytest tests/test_runtime_provider_resolution.py tests/test_cli_provider_resolution.py tests/test_cli_model_command.py tests/test_setup_model_selection.py -q
-```
-
-对于更深层的修改，在推送前运行完整测试套件：
-
-```bash
-source venv/bin/activate
-python -m pytest tests/ -n0 -q
-```
-
-## 第 9 步：实时验证
-
-测试通过后，运行真实的冒烟测试。
-
-```bash
-source venv/bin/activate
-python -m hermes_cli.main chat -q "Say hello" --provider your-provider --model your-model
-```
-
-如果你修改了菜单，也测试交互式流程：
-
-```bash
-source venv/bin/activate
-python -m hermes_cli.main model
-python -m hermes_cli.main setup
-```
-
-对于原生 provider，至少也验证一次工具调用，而不仅仅是纯文本响应。
-
-## 第 10 步：更新用户文档
-
-如果该 provider 打算作为一流选项发布，也更新用户文档：
-
-- `website/docs/getting-started/quickstart.md`
-- `website/docs/user-guide/configuration.md`
-- `website/docs/reference/environment-variables.md`
-
-开发者可以完美地接线 provider，但仍然让用户无法发现所需的环境变量或 setup 流程。
-
-## OpenAI 兼容 provider 清单
-
-如果 provider 是标准 chat completions，使用此清单。
-
-- [ ] 在 `hermes_cli/auth.py` 中添加 `ProviderConfig`
-- [ ] 在 `hermes_cli/auth.py` 和 `hermes_cli/models.py` 中添加别名
-- [ ] 在 `hermes_cli/models.py` 中添加模型目录
-- [ ] 在 `hermes_cli/runtime_provider.py` 中添加运行时分支
-- [ ] 在 `hermes_cli/main.py` 中添加 CLI 接线（setup.py 自动继承）
-- [ ] 在 `agent/auxiliary_client.py` 中添加辅助模型
-- [ ] 在 `agent/model_metadata.py` 中添加上下文长度
-- [ ] 更新运行时 / CLI 测试
-- [ ] 更新用户文档
-
-## 原生 provider 清单
-
-当 provider 需要新的协议路径时使用此清单。
-
-- [ ] OpenAI 兼容清单中的所有内容
-- [ ] 在 `agent/<provider>_adapter.py` 中添加适配器
-- [ ] 在 `run_agent.py` 中支持新的 `api_mode`
-- [ ] 中断 / 重建路径正常工作
-- [ ] 用量和 finish-reason 提取正常工作
-- [ ] 回退路径正常工作
-- [ ] 添加适配器测试
-- [ ] 实时冒烟测试通过
-
-## 常见陷阱
-
-### 1. 将 provider 添加到 auth 但未添加到模型解析
-
-这会导致凭据解析正确，而 `/model` 和 `provider:model` 输入失败。
-
-### 2. 忘记 `config["model"]` 可以是字符串或字典
-
-大量 provider 选择代码必须对两种形式进行规范化。
-
-### 3. 假设必须使用内置 provider
-
-如果该服务只是 OpenAI 兼容的，自定义 provider 可能已经以更少的维护成本解决了用户问题。
-
-### 4. 忘记辅助路径
-
-主聊天路径可能正常工作，而摘要、记忆刷新或视觉辅助失败，因为辅助路由从未更新。
-
-### 5. 原生 provider 分支隐藏在 `run_agent.py` 中
-
-搜索 `api_mode` 和 `self.client.`。不要假设显而易见的请求路径是唯一的。
-
-### 6. 将 OpenRouter 专属字段发送给其他 provider
-
-provider 路由等字段只属于支持它们的 provider。
-
-### 7. 更新了 `hermes model` 但未更新 `hermes setup`
-
-两个流程都需要了解该 provider。
-
-## 实现时的好搜索目标
-
-如果你在寻找 provider 涉及的所有位置，搜索以下符号：
-
-- `PROVIDER_REGISTRY`
-- `_PROVIDER_ALIASES`
-- `_PROVIDER_MODELS`
-- `resolve_runtime_provider`
-- `_model_flow_`
-- `select_provider_and_model`
-- `api_mode`
-- `_API_KEY_PROVIDER_AUX_MODELS`
-- `self.client.`
-
-## 相关文档
-
-- [Provider 运行时解析](./provider-runtime.md)
-- [架构](./architecture.md)
-- [贡献指南](./contributing.md)

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/developer-guide/adding-tools.md

@@ -1,209 +0,0 @@
----
-sidebar_position: 2
-title: "添加工具"
-description: "如何向 Hermes Agent 添加新工具——schema、handler、注册与 toolset"
----
-
-# 添加工具
-
-在编写工具之前，先问自己：**这是否应该是一个 [skill](creating-skills.md)？**
-
-:::warning 仅限内置核心工具
-本页面用于向仓库本身添加 **Hermes 内置工具**。
-如果你想要个人专用、项目本地或其他自定义工具，而不修改 Hermes 核心，请使用插件方式：
-
-- [插件](/user-guide/features/plugins)
-- [构建 Hermes 插件](/developer-guide/plugins)
-
-大多数自定义工具创建场景默认使用插件。只有当你明确希望在 `tools/` 和 `toolsets.py` 中发布新的内置工具时，才遵循本页面。
-:::
-
-以下情况应创建 **Skill**：该能力可以通过指令 + shell 命令 + 现有工具来实现（如 arXiv 搜索、git 工作流、Docker 管理、PDF 处理）。
-
-以下情况应创建 **Tool**：需要与 API 密钥进行端到端集成、自定义处理逻辑、二进制数据处理或流式传输（如浏览器自动化、TTS、视觉分析）。
-
-## 概述
-
-添加一个工具涉及 **2 个文件**：
-
-1. **`tools/your_tool.py`** — handler、schema、check 函数、`registry.register()` 调用
-2. **`toolsets.py`** — 将工具名称添加到 `_HERMES_CORE_TOOLS`（或特定 toolset）
-
-任何包含顶层 `registry.register()` 调用的 `tools/*.py` 文件都会在启动时被自动发现——无需手动维护导入列表。
-
-## 第一步：创建内置工具文件
-
-每个工具文件遵循相同的结构：
-
-```python
-# tools/weather_tool.py
-"""Weather Tool -- look up current weather for a location."""
-
-import json
-import os
-import logging
-
-logger = logging.getLogger(__name__)
-
-
-# --- Availability check ---
-
-def check_weather_requirements() -> bool:
-    """Return True if the tool's dependencies are available."""
-    return bool(os.getenv("WEATHER_API_KEY"))
-
-
-# --- Handler ---
-
-def weather_tool(location: str, units: str = "metric") -> str:
-    """Fetch weather for a location. Returns JSON string."""
-    api_key = os.getenv("WEATHER_API_KEY")
-    if not api_key:
-        return json.dumps({"error": "WEATHER_API_KEY not configured"})
-    try:
-        # ... call weather API ...
-        return json.dumps({"location": location, "temp": 22, "units": units})
-    except Exception as e:
-        return json.dumps({"error": str(e)})
-
-
-# --- Schema ---
-
-WEATHER_SCHEMA = {
-    "name": "weather",
-    "description": "Get current weather for a location.",
-    "parameters": {
-        "type": "object",
-        "properties": {
-            "location": {
-                "type": "string",
-                "description": "City name or coordinates (e.g. 'London' or '51.5,-0.1')"
-            },
-            "units": {
-                "type": "string",
-                "enum": ["metric", "imperial"],
-                "description": "Temperature units (default: metric)",
-                "default": "metric"
-            }
-        },
-        "required": ["location"]
-    }
-}
-
-
-# --- Registration ---
-
-from tools.registry import registry
-
-registry.register(
-    name="weather",
-    toolset="weather",
-    schema=WEATHER_SCHEMA,
-    handler=lambda args, **kw: weather_tool(
-        location=args.get("location", ""),
-        units=args.get("units", "metric")),
-    check_fn=check_weather_requirements,
-    requires_env=["WEATHER_API_KEY"],
-)
-```
-
-### 关键规则
-
-:::danger 重要
-- Handler **必须**返回 JSON 字符串（通过 `json.dumps()`），不得返回原始 dict
-- 错误**必须**以 `{"error": "message"}` 形式返回，不得抛出异常
-- `check_fn` 在构建工具定义时被调用——若返回 `False`，该工具将被静默排除
-- `handler` 接收 `(args: dict, **kwargs)`，其中 `args` 是 LLM 的工具调用参数
-:::
-
-## 第二步：将内置工具添加到 Toolset
-
-在 `toolsets.py` 中添加工具名称：
-
-```python
-# If it should be available on all platforms (CLI + messaging):
-_HERMES_CORE_TOOLS = [
-    ...
-    "weather",  # <-- add here
-]
-
-# Or create a new standalone toolset:
-"weather": {
-    "description": "Weather lookup tools",
-    "tools": ["weather"],
-    "includes": []
-},
-```
-
-## ~~第三步：添加发现导入~~（不再需要）
-
-包含顶层 `registry.register()` 调用的工具模块会由 `tools/registry.py` 中的 `discover_builtin_tools()` 自动发现。无需手动维护导入列表——只需在 `tools/` 中创建文件，启动时即可自动加载。
-
-## 异步 Handler
-
-如果你的 handler 需要异步代码，使用 `is_async=True` 标记：
-
-```python
-async def weather_tool_async(location: str) -> str:
-    async with aiohttp.ClientSession() as session:
-        ...
-    return json.dumps(result)
-
-registry.register(
-    name="weather",
-    toolset="weather",
-    schema=WEATHER_SCHEMA,
-    handler=lambda args, **kw: weather_tool_async(args.get("location", "")),
-    check_fn=check_weather_requirements,
-    is_async=True,  # registry calls _run_async() automatically
-)
-```
-
-registry 会透明地处理异步桥接——你无需自己调用 `asyncio.run()`。
-
-## 需要 task_id 的 Handler
-
-管理每个会话状态的工具通过 `**kwargs` 接收 `task_id`：
-
-```python
-def _handle_weather(args, **kw):
-    task_id = kw.get("task_id")
-    return weather_tool(args.get("location", ""), task_id=task_id)
-
-registry.register(
-    name="weather",
-    ...
-    handler=_handle_weather,
-)
-```
-
-## Agent 循环拦截工具
-
-某些工具（`todo`、`memory`、`session_search`、`delegate_task`）需要访问每个会话的 agent 状态。这些工具在到达 registry 之前会被 `run_agent.py` 拦截。registry 仍然保存它们的 schema，但如果绕过拦截，`dispatch()` 会返回一个回退错误。
-
-## 可选：Setup Wizard 集成
-
-如果你的工具需要 API 密钥，将其添加到 `hermes_cli/config.py`：
-
-```python
-OPTIONAL_ENV_VARS = {
-    ...
-    "WEATHER_API_KEY": {
-        "description": "Weather API key for weather lookup",
-        "prompt": "Weather API key",
-        "url": "https://weatherapi.com/",
-        "tools": ["weather"],
-        "password": True,
-    },
-}
-```
-
-## 检查清单
-
-- [ ] 已创建包含 handler、schema、check 函数和注册调用的工具文件
-- [ ] 已在 `toolsets.py` 中添加到适当的 toolset
-- [ ] 已确认该工具确实应为内置/核心工具而非插件
-- [ ] Handler 返回 JSON 字符串，错误以 `{"error": "..."}` 形式返回
-- [ ] 可选：已将 API 密钥添加到 `hermes_cli/config.py` 的 `OPTIONAL_ENV_VARS`
-- [ ] 可选：已添加到 `toolset_distributions.py` 以支持批量处理
-- [ ] 已通过 `hermes chat -q "Use the weather tool for London"` 测试