better-dsh 0.2.4 → 0.2.5

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

@@ -0,0 +1,239 @@
+---
+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

@@ -0,0 +1,277 @@
+---
+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` 文件都会被自动发现——无需手动维护导入列表。