better-dsh 0.2.5 → 0.3.0

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

@@ -1,239 +0,0 @@
----
-sidebar_position: 3
-title: "Agent Loop 内部机制"
-description: "AIAgent 执行流程、API 模式、工具、回调及回退行为的详细说明"
----
-
-# Agent Loop 内部机制
-
-核心编排引擎是 `run_agent.py` 中的 `AIAgent` 类——这是一个大型文件（15k+ 行），负责处理从 prompt（提示词）组装到工具分发再到 provider 故障转移的所有逻辑。
-
-## 核心职责
-
-`AIAgent` 负责：
-
-- 通过 `prompt_builder.py` 组装有效的系统 prompt 和工具 schema
-- 选择正确的 provider/API 模式（`chat_completions`、`codex_responses`、`anthropic_messages`）
-- 发起支持取消操作的可中断模型调用
-- 执行工具调用（顺序执行或通过线程池并发执行）
-- 以 OpenAI 消息格式维护对话历史
-- 处理压缩、重试和回退模型切换
-- 跨父 agent 和子 agent 追踪迭代预算
-- 在上下文丢失前将持久化内存刷写到磁盘
-
-## 两个入口点
-
-```python
-# 简单接口——返回最终响应字符串
-response = agent.chat("Fix the bug in main.py")
-
-# 完整接口——返回包含消息、元数据、用量统计的 dict
-result = agent.run_conversation(
-    user_message="Fix the bug in main.py",
-    system_message=None,           # 省略时自动构建
-    conversation_history=None,      # 省略时自动从 session 加载
-    task_id="task_abc123"
-)
-```
-
-`chat()` 是对 `run_conversation()` 的轻量封装，从结果 dict 中提取 `final_response` 字段。
-
-## API 模式
-
-Hermes 支持三种 API 执行模式，通过 provider 选择、显式参数和 base URL 启发式规则来确定：
-
-| API 模式 | 用途 | 客户端类型 |
-|----------|------|-----------|
-| `chat_completions` | 兼容 OpenAI 的端点（OpenRouter、自定义及大多数 provider） | `openai.OpenAI` |
-| `codex_responses` | OpenAI Codex / Responses API | `openai.OpenAI`（使用 Responses 格式） |
-| `anthropic_messages` | 原生 Anthropic Messages API | 通过适配器使用 `anthropic.Anthropic` |
-
-模式决定了消息的格式化方式、工具调用的结构、响应的解析方式，以及缓存/流式传输的工作方式。三种模式在 API 调用前后均收敛到相同的内部消息格式（OpenAI 风格的 `role`/`content`/`tool_calls` dict）。
-
-**模式解析顺序：**
-1. 显式 `api_mode` 构造函数参数（最高优先级）
-2. Provider 特定检测（例如 `anthropic` provider → `anthropic_messages`）
-3. Base URL 启发式规则（例如 `api.anthropic.com` → `anthropic_messages`）
-4. 默认：`chat_completions`
-
-## 单轮生命周期
-
-agent loop 的每次迭代按以下顺序执行：
-
-```text
-run_conversation()
-  1. 若未提供则生成 task_id
-  2. 将用户消息追加到对话历史
-  3. 构建或复用已缓存的系统 prompt（prompt_builder.py）
-  4. 检查是否需要预检压缩（上下文超过 50%）
-  5. 从对话历史构建 API 消息
-     - chat_completions：直接使用 OpenAI 格式
-     - codex_responses：转换为 Responses API 输入项
-     - anthropic_messages：通过 anthropic_adapter.py 转换
-  6. 注入临时 prompt 层（预算警告、上下文压力提示）
-  7. 若使用 Anthropic，应用 prompt 缓存标记
-  8. 发起可中断的 API 调用（_interruptible_api_call）
-  9. 解析响应：
-     - 若有 tool_calls：执行工具，追加结果，回到步骤 5
-     - 若为文本响应：持久化 session，按需刷写内存，返回
-```
-
-### 消息格式
-
-所有消息在内部均使用兼容 OpenAI 的格式：
-
-```python
-{"role": "system", "content": "..."}
-{"role": "user", "content": "..."}
-{"role": "assistant", "content": "...", "tool_calls": [...]}
-{"role": "tool", "tool_call_id": "...", "content": "..."}
-```
-
-推理内容（来自支持扩展思考的模型）存储在 `assistant_msg["reasoning"]` 中，并可选择通过 `reasoning_callback` 展示。
-
-### 消息交替规则
-
-agent loop 强制执行严格的消息角色交替规则：
-
-- 系统消息之后：`User → Assistant → User → Assistant → ...`
-- 工具调用期间：`Assistant（含 tool_calls）→ Tool → Tool → ... → Assistant`
-- **不允许**连续出现两条 assistant 消息
-- **不允许**连续出现两条 user 消息
-- **只有** `tool` 角色可以连续出现（并行工具结果）
-
-Provider 会验证这些序列，并拒绝格式错误的历史记录。
-
-## 可中断的 API 调用
-
-API 请求被封装在 `_interruptible_api_call()` 中，该方法在后台线程中执行实际的 HTTP 调用，同时监听中断事件：
-
-```text
-┌────────────────────────────────────────────────────┐
-│  主线程                        API 线程             │
-│                                                    │
-│   等待：                        HTTP POST           │
-│    - 响应就绪          ───▶    发送至 provider       │
-│    - 中断事件                                       │
-│    - 超时                                          │
-└────────────────────────────────────────────────────┘
-```
-
-当发生中断（用户发送新消息、`/stop` 命令或信号）时：
-- API 线程被放弃（响应被丢弃）
-- agent 可以处理新输入或干净地关闭
-- 不会将部分响应注入对话历史
-
-## 工具执行
-
-### 顺序执行与并发执行
-
-当模型返回工具调用时：
-
-- **单个工具调用** → 直接在主线程中执行
-- **多个工具调用** → 通过 `ThreadPoolExecutor` 并发执行
-  - 例外：标记为交互式的工具（如 `clarify`）强制顺序执行
-  - 无论完成顺序如何，结果均按原始工具调用顺序重新插入
-
-### 执行流程
-
-```text
-for each tool_call in response.tool_calls:
-    1. 从 tools/registry.py 解析处理器
-    2. 触发 pre_tool_call 插件 hook
-    3. 检查是否为危险命令（tools/approval.py）
-       - 若危险：调用 approval_callback，等待用户确认
-    4. 使用参数 + task_id 执行处理器
-    5. 触发 post_tool_call 插件 hook
-    6. 将 {"role": "tool", "content": result} 追加到历史
-```
-
-### Agent 级工具
-
-部分工具在到达 `handle_function_call()` 之前，由 `run_agent.py` *提前*拦截：
-
-| 工具 | 拦截原因 |
-|------|---------|
-| `todo` | 读写 agent 本地任务状态 |
-| `memory` | 向持久化内存文件写入内容（有字符限制） |
-| `session_search` | 通过 agent 的 session DB 查询 session 历史 |
-| `delegate_task` | 以隔离上下文生成子 agent |
-
-这些工具直接修改 agent 状态，并返回合成的工具结果，不经过注册表。
-
-## 回调接口
-
-`AIAgent` 支持平台特定的回调，用于在 CLI、gateway 和 ACP 集成中实现实时进度展示：
-
-| 回调 | 触发时机 | 使用方 |
-|------|---------|--------|
-| `tool_progress_callback` | 每次工具执行前后 | CLI spinner、gateway 进度消息 |
-| `thinking_callback` | 模型开始/停止思考时 | CLI "thinking..." 指示器 |
-| `reasoning_callback` | 模型返回推理内容时 | CLI 推理展示、gateway 推理块 |
-| `clarify_callback` | 调用 `clarify` 工具时 | CLI 输入提示、gateway 交互消息 |
-| `step_callback` | 每次完整 agent 轮次结束后 | Gateway 步骤追踪、ACP 进度 |
-| `stream_delta_callback` | 每个流式 token（启用时） | CLI 流式展示 |
-| `tool_gen_callback` | 从流中解析出工具调用时 | CLI spinner 中的工具预览 |
-| `status_callback` | 状态变更时（思考、执行等） | ACP 状态更新 |
-
-## 预算与回退行为
-
-### 迭代预算
-
-agent 通过 `IterationBudget` 追踪迭代次数：
-
-- 默认：500 次迭代（可通过 `agent.max_turns` 配置）
-- 每个 agent 拥有独立预算。子 agent 获得独立预算，上限为 `delegation.max_iterations`（默认 50）——父 agent 与子 agent 的总迭代次数可超过父 agent 的上限
-- 达到 100% 时，agent 停止并返回已完成工作的摘要
-
-### 回退模型
-
-当主模型失败时（429 限流、5xx 服务器错误、401/403 鉴权错误）：
-
-1. 检查配置中的 `fallback_providers` 列表
-2. 按顺序尝试每个回退 provider
-3. 成功后，使用新 provider 继续对话
-4. 遇到 401/403 时，在故障转移前尝试刷新凭据
-
-回退系统也独立覆盖辅助任务——视觉、压缩和网页提取各自拥有独立的回退链，可通过 `auxiliary.*` 配置节进行配置。
-
-## 压缩与持久化
-
-### 压缩触发时机
-
-- **预检**（API 调用前）：对话超过模型上下文窗口的 50%
-- **Gateway 自动压缩**：对话超过 85%（更激进，在轮次之间运行）
-
-### 压缩过程
-
-1. 首先将内存刷写到磁盘（防止数据丢失）
-2. 将中间对话轮次摘要为紧凑的摘要内容
-3. 保留最后 N 条消息完整不变（`compression.protect_last_n`，默认：20）
-4. 工具调用/结果消息对保持完整（不拆分）
-5. 生成新的 session 血缘 ID（压缩会创建一个"子" session）
-
-### Session 持久化
-
-每轮结束后：
-- 消息保存到 session 存储（通过 `hermes_state.py` 使用 SQLite）
-- 内存变更刷写到 `MEMORY.md` / `USER.md`
-- 可通过 `/resume` 或 `hermes chat --resume` 恢复 session
-
-## 关键源文件
-
-| 文件 | 用途 |
-|------|------|
-| `run_agent.py` | AIAgent 类——完整的 agent loop |
-| `agent/prompt_builder.py` | 从内存、技能、上下文文件和个性组装系统 prompt |
-| `agent/context_engine.py` | ContextEngine ABC——可插拔的上下文管理 |
-| `agent/context_compressor.py` | 默认引擎——有损摘要算法 |
-| `agent/prompt_caching.py` | Anthropic prompt 缓存标记和缓存指标 |
-| `agent/auxiliary_client.py` | 用于辅助任务的辅助 LLM 客户端（视觉、摘要） |
-| `model_tools.py` | 工具 schema 集合，`handle_function_call()` 分发 |
-
-## 相关文档
-
-- [Provider 运行时解析](./provider-runtime.md)
-- [Prompt 组装](./prompt-assembly.md)
-- [上下文压缩与 Prompt 缓存](./context-compression-and-caching.md)
-- [工具运行时](./tools-runtime.md)
-- [架构概览](./architecture.md)

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

@@ -1,277 +0,0 @@
----
-sidebar_position: 1
-title: "架构"
-description: "Hermes Agent 内部结构——主要子系统、执行路径、数据流及延伸阅读指引"
----
-
-# 架构
-
-本页是 Hermes Agent 内部结构的顶层导图。用它在代码库中定位自己，然后深入各子系统专项文档了解实现细节。
-
-## 系统概览
-
-```text
-┌─────────────────────────────────────────────────────────────────────┐
-│                        Entry Points                                  │
-│                                                                      │
-│  CLI (cli.py)    Gateway (gateway/run.py)    ACP (acp_adapter/)     │
-│  Batch Runner    API Server                  Python Library          │
-└──────────┬──────────────┬───────────────────────┬───────────────────┘
-           │              │                       │
-           ▼              ▼                       ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│                     AIAgent (run_agent.py)                          │
-│                                                                     │
-│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐               │
-│  │ Prompt       │  │ Provider     │  │ Tool         │               │
-│  │ Builder      │  │ Resolution   │  │ Dispatch     │               │
-│  │ (prompt_     │  │ (runtime_    │  │ (model_      │               │
-│  │  builder.py) │  │  provider.py)│  │  tools.py)   │               │
-│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘               │
-│         │                 │                 │                       │
-│  ┌──────┴───────┐  ┌──────┴───────┐  ┌──────┴───────┐               │
-│  │ Compression  │  │ 3 API Modes  │  │ Tool Registry│               │
-│  │ & Caching    │  │ chat_compl.  │  │ (registry.py)│               │
-│  │              │  │ codex_resp.  │  │ 70+ tools    │               │
-│  │              │  │ anthropic    │  │ 28 toolsets  │               │
-│  └──────────────┘  └──────────────┘  └──────────────┘               │
-└─────────┴─────────────────┴─────────────────┴───────────────────────┘
-           │                                    │
-           ▼                                    ▼
-┌───────────────────┐              ┌──────────────────────┐
-│ Session Storage   │              │ Tool Backends         │
-│ (SQLite + FTS5)   │              │ Terminal (7 backends) │
-│ hermes_state.py   │              │ Browser (5 backends)  │
-│ gateway/session.py│              │ Web (4 backends)      │
-└───────────────────┘              │ MCP (dynamic)         │
-                                   │ File, Vision, etc.    │
-                                   └──────────────────────┘
-```
-
-## 目录结构
-
-```text
-hermes-agent/
-├── run_agent.py              # AIAgent — 核心对话循环（大文件）
-├── cli.py                    # HermesCLI — 交互式终端 UI（大文件）
-├── model_tools.py            # 工具发现、schema 收集、分发
-├── toolsets.py               # 工具分组与平台预设
-├── hermes_state.py           # 带 FTS5 的 SQLite 会话/状态数据库
-├── hermes_constants.py       # HERMES_HOME、感知 profile 的路径
-├── batch_runner.py           # 批量轨迹生成
-│
-├── agent/                    # Agent 内部模块
-│   ├── prompt_builder.py     # 系统 prompt 组装
-│   ├── context_engine.py     # ContextEngine ABC（可插拔）
-│   ├── context_compressor.py # 默认引擎——有损摘要压缩
-│   ├── prompt_caching.py     # Anthropic prompt 缓存
-│   ├── auxiliary_client.py   # 辅助 LLM，用于旁路任务（视觉、摘要）
-│   ├── model_metadata.py     # 模型上下文长度、token 估算
-│   ├── models_dev.py         # models.dev 注册表集成
-│   ├── anthropic_adapter.py  # Anthropic Messages API 格式转换
-│   ├── display.py            # KawaiiSpinner、工具预览格式化
-│   ├── skill_commands.py     # Skill 斜杠命令
-│   ├── memory_manager.py    # 记忆管理器编排
-│   ├── memory_provider.py   # 记忆提供者 ABC
-│   └── trajectory.py         # 轨迹保存辅助函数
-│
-├── hermes_cli/               # CLI 子命令与设置
-│   ├── main.py               # 入口点——所有 `hermes` 子命令（大文件）
-│   ├── config.py             # DEFAULT_CONFIG、OPTIONAL_ENV_VARS、迁移
-│   ├── commands.py           # COMMAND_REGISTRY——斜杠命令中央定义
-│   ├── auth.py               # PROVIDER_REGISTRY、凭据解析
-│   ├── runtime_provider.py   # Provider → api_mode + 凭据
-│   ├── models.py             # 模型目录、provider 模型列表
-│   ├── model_switch.py       # /model 命令逻辑（CLI + gateway 共用）
-│   ├── setup.py              # 交互式设置向导（大文件）
-│   ├── skin_engine.py        # CLI 主题引擎
-│   ├── skills_config.py      # hermes skills——按平台启用/禁用
-│   ├── skills_hub.py         # /skills 斜杠命令
-│   ├── tools_config.py       # hermes tools——按平台启用/禁用
-│   ├── plugins.py            # PluginManager——发现、加载、hook
-│   ├── callbacks.py          # 终端回调（clarify、sudo、approval）
-│   └── gateway.py            # hermes gateway 启动/停止
-│
-├── tools/                    # 工具实现（每个工具一个文件）
-│   ├── registry.py           # 中央工具注册表
-│   ├── approval.py           # 危险命令检测
-│   ├── terminal_tool.py      # 终端编排
-│   ├── process_registry.py   # 后台进程管理
-│   ├── file_tools.py         # read_file、write_file、patch、search_files
-│   ├── web_tools.py          # web_search、web_extract
-│   ├── browser_tool.py       # 10 个浏览器自动化工具
-│   ├── code_execution_tool.py # execute_code 沙箱
-│   ├── delegate_tool.py      # 子 agent 委托
-│   ├── mcp_tool.py           # MCP 客户端（大文件）
-│   ├── credential_files.py   # 基于文件的凭据透传
-│   ├── env_passthrough.py    # 沙箱环境变量透传
-│   ├── ansi_strip.py         # ANSI 转义字符剥离
-│   └── environments/         # 终端后端（local、docker、ssh、modal、daytona、singularity）
-│
-├── gateway/                  # 消息平台 gateway
-│   ├── run.py                # GatewayRunner——消息分发（大文件）
-│   ├── session.py            # SessionStore——对话持久化
-│   ├── delivery.py           # 出站消息投递
-│   ├── pairing.py            # DM 配对授权
-│   ├── hooks.py              # Hook 发现与生命周期事件
-│   ├── mirror.py             # 跨会话消息镜像
-│   ├── status.py             # Token 锁、profile 范围的进程追踪
-│   ├── builtin_hooks/        # 始终注册的 hook 扩展点（当前无内置）
-│   └── platforms/            # 20 个适配器：telegram、discord、slack、whatsapp、
-│                             #   signal、matrix、mattermost、email、sms、
-│                             #   dingtalk、feishu、wecom、wecom_callback、weixin、
-│                             #   bluebubbles、qqbot、homeassistant、webhook、api_server、
-│                             #   yuanbao
-│
-├── acp_adapter/              # ACP 服务器（VS Code / Zed / JetBrains）
-├── cron/                     # 调度器（jobs.py、scheduler.py）
-├── plugins/memory/           # 记忆提供者插件
-├── plugins/context_engine/   # 上下文引擎插件
-├── skills/                   # 内置 skill（始终可用）
-├── optional-skills/          # 官方可选 skill（需显式安装）
-├── website/                  # Docusaurus 文档站点
-└── tests/                    # Pytest 测试套件（3,000+ 个测试）
-```
-
-## 数据流
-
-### CLI 会话
-
-```text
-用户输入 → HermesCLI.process_input()
-  → AIAgent.run_conversation()
-    → prompt_builder.build_system_prompt()
-    → runtime_provider.resolve_runtime_provider()
-    → API 调用（chat_completions / codex_responses / anthropic_messages）
-    → tool_calls? → model_tools.handle_function_call() → 循环
-    → 最终响应 → 显示 → 保存至 SessionDB
-```
-
-### Gateway 消息
-
-```text
-平台事件 → Adapter.on_message() → MessageEvent
-  → GatewayRunner._handle_message()
-    → 授权用户
-    → 解析会话 key
-    → 创建带会话历史的 AIAgent
-    → AIAgent.run_conversation()
-    → 通过适配器回传响应
-```
-
-### Cron 任务
-
-```text
-调度器触发 → 从 jobs.json 加载到期任务
-  → 创建全新 AIAgent（无历史）
-  → 将附加的 skill 注入为上下文
-  → 运行任务 prompt
-  → 向目标平台投递响应
-  → 更新任务状态与 next_run
-```
-
-## 推荐阅读顺序
-
-如果你是第一次接触代码库：
-
-1. **本页** — 整体定位
-2. **[Agent 循环内部机制](./agent-loop.md)** — AIAgent 的工作原理
-3. **[Prompt 组装](./prompt-assembly.md)** — 系统 prompt 的构建过程
-4. **[Provider 运行时解析](./provider-runtime.md)** — provider 的选择方式
-5. **[添加 Provider](./adding-providers.md)** — 新增 provider 的实践指南
-6. **[工具运行时](./tools-runtime.md)** — 工具注册表、分发、环境
-7. **[会话存储](./session-storage.md)** — SQLite schema、FTS5、会话血缘
-8. **[Gateway 内部机制](./gateway-internals.md)** — 消息平台 gateway
-9. **[上下文压缩与 Prompt 缓存](./context-compression-and-caching.md)** — 压缩与缓存
-10. **[ACP 内部机制](./acp-internals.md)** — IDE 集成
-
-## 主要子系统
-
-### Agent 循环
-
-同步编排引擎（`run_agent.py` 中的 `AIAgent`）。负责 provider 选择、prompt 构建、工具执行、重试、回退、回调、压缩和持久化。支持三种 API 模式以适配不同 provider 后端。
-
-→ [Agent 循环内部机制](./agent-loop.md)
-
-### Prompt 系统
-
-在对话生命周期中构建和维护 prompt：
-
-- **`prompt_builder.py`** — 从以下来源组装系统 prompt：个性（SOUL.md）、记忆（MEMORY.md、USER.md）、skill、上下文文件（AGENTS.md、.hermes.md）、工具使用指引以及模型专项指令
-- **`prompt_caching.py`** — 为前缀缓存应用 Anthropic 缓存断点
-- **`context_compressor.py`** — 当上下文超出阈值时对中间对话轮次进行摘要
-
-→ [Prompt 组装](./prompt-assembly.md)，[上下文压缩与 Prompt 缓存](./context-compression-and-caching.md)
-
-### Provider 解析
-
-CLI、gateway、cron、ACP 及辅助调用共用的运行时解析器。将 `(provider, model)` 元组映射为 `(api_mode, api_key, base_url)`。支持 18+ 个 provider、OAuth 流程、凭据池和别名解析。
-
-→ [Provider 运行时解析](./provider-runtime.md)
-
-### 工具系统
-
-中央工具注册表（`tools/registry.py`），包含约 28 个 toolset 中的 70+ 个已注册工具。每个工具文件在导入时自行注册。注册表负责 schema 收集、分发、可用性检查和错误包装。终端工具支持 7 种后端（local、Docker、SSH、Daytona、Modal、Singularity、Vercel Sandbox）。
-
-→ [工具运行时](./tools-runtime.md)
-
-### 会话持久化
-
-基于 SQLite 的会话存储，带 FTS5 全文检索。会话具有血缘追踪（跨压缩的父/子关系）、按平台隔离，以及带竞争处理的原子写入。
-
-→ [会话存储](./session-storage.md)
-
-### 消息 Gateway
-
-长驻进程，包含 20 个平台适配器、统一会话路由、用户授权（白名单 + DM 配对）、斜杠命令分发、hook 系统、cron 触发和后台维护。
-
-→ [Gateway 内部机制](./gateway-internals.md)
-
-### 插件系统
-
-三种发现来源：`~/.hermes/plugins/`（用户级）、`.hermes/plugins/`（项目级）和 pip entry point。插件通过上下文 API 注册工具、hook 和 CLI 命令。存在两种专用插件类型：记忆提供者（`plugins/memory/`）和上下文引擎（`plugins/context_engine/`）。两者均为单选——每种同时只能激活一个，通过 `hermes plugins` 或 `config.yaml` 配置。
-
-→ [插件指南](/developer-guide/plugins)，[记忆提供者插件](./memory-provider-plugin.md)
-
-### Cron
-
-一等公民的 agent 任务（非 shell 任务）。任务以 JSON 存储，支持多种调度格式，可附加 skill 和脚本，并可向任意平台投递。
-
-→ [Cron 内部机制](./cron-internals.md)
-
-### ACP 集成
-
-通过 stdio/JSON-RPC 将 Hermes 作为编辑器原生 agent 暴露给 VS Code、Zed 和 JetBrains。
-
-→ [ACP 内部机制](./acp-internals.md)
-
-### 轨迹
-
-从 agent 会话生成 ShareGPT 格式的轨迹，用于训练数据生成。
-
-→ [轨迹与训练格式](./trajectory-format.md)
-
-## 设计原则
-
-| 原则 | 实践含义 |
-|------|---------|
-| **Prompt 稳定性** | 系统 prompt 在对话中途不会改变。除用户显式操作（`/model`）外，不进行破坏缓存的变更。 |
-| **可观测执行** | 每次工具调用均通过回调对用户可见。CLI（spinner）和 gateway（聊天消息）中均有进度更新。 |
-| **可中断** | API 调用和工具执行可被用户输入或信号在执行中途取消。 |
-| **平台无关的核心** | 单一 AIAgent 类同时服务于 CLI、gateway、ACP、批处理和 API 服务器。平台差异存在于入口点，而非 agent 内部。 |
-| **松耦合** | 可选子系统（MCP、插件、记忆提供者、RL 环境）使用注册表模式和 check_fn 门控，而非硬依赖。 |
-| **Profile 隔离** | 每个 profile（`hermes -p <name>`）拥有独立的 HERMES_HOME、配置、记忆、会话和 gateway PID。多个 profile 可并发运行。 |
-
-## 文件依赖链
-
-```text
-tools/registry.py  （无依赖——被所有工具文件导入）
-       ↑
-tools/*.py  （每个文件在导入时调用 registry.register()）
-       ↑
-model_tools.py  （导入 tools/registry 并触发工具发现）
-       ↑
-run_agent.py, cli.py, batch_runner.py, environments/
-```
-
-这条依赖链意味着工具注册发生在导入时，早于任何 agent 实例的创建。任何在顶层调用 `registry.register()` 的 `tools/*.py` 文件都会被自动发现——无需手动维护导入列表。