better-dsh 0.2.4 → 0.2.5

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

@@ -0,0 +1,126 @@
+---
+sidebar_position: 8
+title: "程序化集成"
+description: "从外部程序驱动 hermes-agent 的三种协议：ACP、TUI gateway JSON-RPC 以及兼容 OpenAI 的 HTTP API"
+---
+
+# 程序化集成
+
+Hermes 提供三种协议，供外部程序驱动 agent——IDE 插件、自定义 UI、CI 流水线、嵌入式子 agent。根据你的传输方式和消费端选择合适的协议。
+
+| 协议 | 传输方式 | 适用场景 | 定义位置 |
+|----------|-----------|----------|------------|
+| **ACP** | JSON-RPC over stdio | 已支持 [Agent Client Protocol](https://github.com/zed-industries/agent-client-protocol) 的 IDE 客户端（VS Code、Zed、JetBrains） | `acp_adapter/` |
+| **TUI gateway** | JSON-RPC over stdio（或 WebSocket） | 需要精细控制会话、slash 命令、审批及流式事件的自定义宿主 | `tui_gateway/server.py` |
+| **API server** | HTTP + Server-Sent Events | 兼容 OpenAI 的前端（Open WebUI、LobeChat、LibreChat……）及语言无关的 Web 客户端 | `gateway/platforms/api_server.py` |
+
+三种协议均驱动同一个 `AIAgent` 核心，区别仅在于线路格式和所暴露的功能集。
+
+---
+
+## ACP（Agent Client Protocol）
+
+`hermes acp` 启动一个基于 stdio 的 JSON-RPC 服务器，使用 ACP 协议。已在 VS Code（Zed Industries 的 ACP 扩展）、Zed 以及所有安装了 ACP 插件的 JetBrains IDE 中投入生产使用。
+
+暴露的能力：会话创建、prompt（提示词）提交、流式 agent 消息块、工具调用事件、权限请求、会话 fork、取消及身份验证。工具输出会被渲染为 IDE 可理解的 ACP `Diff`/`ToolCall` 内容块。
+
+完整生命周期、事件桥接及审批流程：[ACP 内部机制](./acp-internals)。
+
+```bash
+hermes acp                  # 在 stdio 上提供 ACP 服务
+hermes acp --bootstrap      # 打印适用于支持 ACP 的 IDE 的安装代码片段
+```
+
+---
+
+## TUI Gateway JSON-RPC
+
+`tui_gateway/server.py` 是 Ink TUI（`hermes --tui`）和嵌入式仪表板 PTY 桥接所使用的协议。任何外部宿主均可通过 stdio（或经由 `tui_gateway/ws.py` 的 WebSocket）使用相同协议。
+
+### 方法目录（精选）
+
+```
+prompt.submit           prompt.background       session.steer
+session.create          session.list            session.interrupt
+session.history         session.compress        session.branch
+session.title           session.usage           session.status
+clarify.respond         sudo.respond            secret.respond
+approval.respond        config.set / config.get commands.catalog
+command.resolve         command.dispatch        cli.exec
+reload.mcp              reload.env              process.stop
+delegation.status       subagent.interrupt      spawn_tree.save / list / load
+terminal.resize         clipboard.paste         image.attach
+```
+
+### 流式返回的事件
+
+`message.delta`、`message.complete`、`tool.start`、`tool.progress`、`tool.complete`、`approval.request`、`clarify.request`、`sudo.request`、`secret.request`、`gateway.ready`，以及会话生命周期和错误事件。
+
+### Pi 风格 RPC 映射
+
+Pi-mono RPC 规范（[issue #360](https://github.com/NousResearch/hermes-agent/issues/360)）中的每条命令均有对应的 TUI gateway 等价项：
+
+| Pi 命令 | Hermes 等价项 |
+|------------|-------------------|
+| `prompt` | `prompt.submit`（或 ACP `session/prompt`） |
+| `steer` | `session.steer` |
+| `follow_up` | 在当前轮次结束后排队的 `prompt.submit` |
+| `abort` | `session.interrupt` |
+| `set_model` | 通过 `command.dispatch` 执行 `/model <provider:model>`（会话中途生效，持久化） |
+| `compact` | `session.compress` |
+| `get_state` | `session.status` |
+| `get_messages` | `session.history` |
+| `switch_session` | `session.resume` |
+| `fork` | `session.branch` |
+| `ui_request` / `ui_response` | `clarify.respond` / `sudo.respond` / `secret.respond` / `approval.respond` |
+
+---
+
+## 兼容 OpenAI 的 API Server
+
+`gateway/platforms/api_server.py` 通过 HTTP 暴露 Hermes，供任何已支持 OpenAI 格式的客户端使用。适用于需要 Web 前端、curl 驱动的 CI 运行器或非 Python 消费端的场景。
+
+端点：
+
+```
+POST /v1/chat/completions        OpenAI Chat Completions（通过 SSE 流式传输）
+POST /v1/responses               OpenAI Responses API（有状态）
+POST /v1/runs                    启动一次运行，返回 run_id（202）
+GET  /v1/runs/{id}               运行状态
+GET  /v1/runs/{id}/events        生命周期事件的 SSE 流
+POST /v1/runs/{id}/approval      解决待处理的审批
+POST /v1/runs/{id}/stop          中断运行
+GET  /v1/capabilities            机器可读的功能标志
+GET  /v1/models                  列出 hermes-agent
+GET  /health, /health/detailed
+```
+
+配置、请求头（`X-Hermes-Session-Id`、`X-Hermes-Session-Key`）及前端接入：[API Server](../user-guide/features/api-server)。
+
+---
+
+## 该选哪个？
+
+- **正在编写 IDE 插件，且 IDE 已支持 ACP** → 选 ACP。IDE 侧无需任何协议工作。
+- **正在编写自定义桌面 / Web / TUI 宿主，且需要 Hermes 的全部功能**（slash 命令、审批、clarify、多 agent、会话分支）→ 选 TUI gateway JSON-RPC。
+- **需要任意兼容 OpenAI 的前端、语言无关的 HTTP 客户端或 curl 驱动的自动化** → 选 API server。
+- **需要在 Python 进程内嵌入，不想启动子进程** → 直接导入 `run_agent.AIAgent`。参见 [Agent Loop](./agent-loop)。
+
+---
+
+## 模型热切换
+
+会话中途切换模型在所有接入方式上均可用——底层均为 `/model` slash 命令。
+
+- **CLI / TUI：** `/model claude-sonnet-4` 或 `/model openrouter:anthropic/claude-sonnet-4.6`
+- **TUI gateway RPC：** 使用 `{"command": "/model claude-sonnet-4"}` 调用 `command.dispatch`
+- **ACP：** IDE 将 slash 命令作为 prompt 发送，agent 负责分发
+- **API server：** 在请求体中包含 `model` 字段，或设置 `X-Hermes-Model`
+
+内置 provider 感知解析（相同的模型名称会根据当前 provider 自动选择正确格式）。参见 `hermes_cli/model_switch.py`。
+
+---
+
+## 关于 `--mode rpc` 的说明
+
+Hermes 没有 `--mode rpc` 标志。上述三种协议已覆盖所有使用场景——ACP 用于 IDE 协议客户端，TUI gateway 用于 stdio JSON-RPC 宿主，API server 用于 HTTP。如果你发现上述协议均无法满足的真实需求，请提交 issue 并说明你正在构建的具体消费端。

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

@@ -0,0 +1,273 @@
+---
+sidebar_position: 5
+title: "Prompt 组装"
+description: "Hermes 如何构建系统 prompt、保持缓存稳定性并注入临时层"
+---
+
+# Prompt 组装
+
+Hermes 刻意将以下内容分离：
+
+- **已缓存的系统 prompt 状态**
+- **API 调用时临时添加的内容**
+
+这是项目中最重要的设计决策之一，因为它影响：
+
+- token 用量
+- prompt 缓存效果
+- 会话连续性
+- 记忆正确性
+
+主要文件：
+
+- `run_agent.py`
+- `agent/prompt_builder.py`
+- `tools/memory_tool.py`
+
+## 已缓存的系统 prompt 层
+
+已缓存的系统 prompt 大致按以下顺序组装：
+
+1. agent 身份 — 优先使用 `HERMES_HOME` 中的 `SOUL.md`，否则回退到 `prompt_builder.py` 中的 `DEFAULT_AGENT_IDENTITY`
+2. 工具感知行为指导
+3. Honcho 静态块（激活时）
+4. 可选系统消息
+5. 冻结的 MEMORY 快照
+6. 冻结的 USER 配置文件快照
+7. skills 索引
+8. 上下文文件（`AGENTS.md`、`.cursorrules`、`.cursor/rules/*.mdc`）— 若 SOUL.md 已在第 1 步作为身份加载，则此处**不**再包含它
+9. 时间戳 / 可选会话 ID
+10. 平台提示
+
+当设置了 `skip_context_files`（例如子 agent 委托）时，不会加载 SOUL.md，而是使用硬编码的 `DEFAULT_AGENT_IDENTITY`。
+
+### 具体示例：组装后的系统 prompt
+
+以下是所有层都存在时最终系统 prompt 的简化视图（注释说明每个部分的来源）：
+
+```
+# Layer 1: Agent Identity (from ~/.hermes/SOUL.md)
+You are Hermes, an AI assistant created by Nous Research.
+You are an expert software engineer and researcher.
+You value correctness, clarity, and efficiency.
+...
+
+# Layer 2: Tool-aware behavior guidance
+You have persistent memory across sessions. Save durable facts using
+the memory tool: user preferences, environment details, tool quirks,
+and stable conventions. Memory is injected into every turn, so keep
+it compact and focused on facts that will still matter later.
+...
+When the user references something from a past conversation or you
+suspect relevant cross-session context exists, use session_search
+to recall it before asking them to repeat themselves.
+
+# Tool-use enforcement (for GPT/Codex models only)
+You MUST use your tools to take action — do not describe what you
+would do or plan to do without actually doing it.
+...
+
+# Layer 3: Honcho static block (when active)
+[Honcho personality/context data]
+
+# Layer 4: Optional system message (from config or API)
+[User-configured system message override]
+
+# Layer 5: Frozen MEMORY snapshot
+## Persistent Memory
+- User prefers Python 3.12, uses pyproject.toml
+- Default editor is nvim
+- Working on project "atlas" in ~/code/atlas
+- Timezone: US/Pacific
+
+# Layer 6: Frozen USER profile snapshot
+## User Profile
+- Name: Alice
+- GitHub: alice-dev
+
+# Layer 7: Skills index
+## Skills (mandatory)
+Before replying, scan the skills below. If one clearly matches
+your task, load it with skill_view(name) and follow its instructions.
+...
+<available_skills>
+  software-development:
+    - code-review: Structured code review workflow
+    - test-driven-development: TDD methodology
+  research:
+    - arxiv: Search and summarize arXiv papers
+</available_skills>
+
+# Layer 8: Context files (from project directory)
+# Project Context
+The following project context files have been loaded and should be followed:
+
+## AGENTS.md
+This is the atlas project. Use pytest for testing. The main
+entry point is src/atlas/main.py. Always run `make lint` before
+committing.
+
+# Layer 9: Timestamp + session
+Current time: 2026-03-30T14:30:00-07:00
+Session: abc123
+
+# Layer 10: Platform hint
+You are a CLI AI Agent. Try not to use markdown but simple text
+renderable inside a terminal.
+```
+
+## SOUL.md 在 prompt 中的位置
+
+`SOUL.md` 位于 `~/.hermes/SOUL.md`，作为 agent 的身份标识——系统 prompt 的第一个部分。`prompt_builder.py` 中的加载逻辑如下：
+
+```python
+# From agent/prompt_builder.py (simplified)
+def load_soul_md() -> Optional[str]:
+    soul_path = get_hermes_home() / "SOUL.md"
+    if not soul_path.exists():
+        return None
+    content = soul_path.read_text(encoding="utf-8").strip()
+    content = _scan_context_content(content, "SOUL.md")  # Security scan
+    content = _truncate_content(content, "SOUL.md")       # Cap defaults to 20k chars, configurable
+    return content
+```
+
+当 `load_soul_md()` 返回内容时，它会替换硬编码的 `DEFAULT_AGENT_IDENTITY`。随后调用 `build_context_files_prompt()` 时传入 `skip_soul=True`，以防止 SOUL.md 出现两次（一次作为身份，一次作为上下文文件）。
+
+若 `SOUL.md` 不存在，系统将回退到：
+
+```
+You are Hermes Agent, built by Nous Research. Be direct: match the length
+of your reply to the weight of the ask — a one-line question gets a
+one-line answer, and finished work gets a short report of what changed,
+what's verified, and what's left, never a replay of the process. No
+filler ("Great question," "I'd be happy to"), no restating the request
+back, no re-summarizing what you already said, no narrating tool calls
+the user can see. Plain claims over adjectives; when unsure, say so
+plainly. Agree because it's right, not because the user said it. Depth
+is earned — give it when the user asks for detail, teaches, or the
+stakes demand it, not by default.
+```
+
+## 上下文文件的注入方式
+
+`build_context_files_prompt()` 使用**优先级系统**——只加载一种项目上下文类型（先匹配先赢）：
+
+```python
+# From agent/prompt_builder.py (simplified)
+def build_context_files_prompt(cwd=None, skip_soul=False):
+    cwd_path = Path(cwd).resolve()
+
+    # Priority: first match wins — only ONE project context loaded
+    project_context = (
+        _load_hermes_md(cwd_path)       # 1. .hermes.md / HERMES.md (walks to git root)
+        or _load_agents_md(cwd_path)    # 2. AGENTS.md (cwd only)
+        or _load_claude_md(cwd_path)    # 3. CLAUDE.md (cwd only)
+        or _load_cursorrules(cwd_path)  # 4. .cursorrules / .cursor/rules/*.mdc
+    )
+
+    sections = []
+    if project_context:
+        sections.append(project_context)
+
+    # SOUL.md from HERMES_HOME (independent of project context)
+    if not skip_soul:
+        soul_content = load_soul_md()
+        if soul_content:
+            sections.append(soul_content)
+
+    if not sections:
+        return ""
+
+    return (
+        "# Project Context\n\n"
+        "The following project context files have been loaded "
+        "and should be followed:\n\n"
+        + "\n".join(sections)
+    )
+```
+
+### 上下文文件发现详情
+
+| 优先级 | 文件 | 搜索范围 | 说明 |
+|--------|------|----------|------|
+| 1 | `.hermes.md`、`HERMES.md` | 从 CWD 向上至 git 根目录 | Hermes 原生项目配置 |
+| 2 | `AGENTS.md` | 仅 CWD | 常见 agent 指令文件 |
+| 3 | `CLAUDE.md` | 仅 CWD | Claude Code 兼容性 |
+| 4 | `.cursorrules`、`.cursor/rules/*.mdc` | 仅 CWD | Cursor 兼容性 |
+
+所有上下文文件均会：
+- **安全扫描** — 检查 prompt 注入模式（不可见 unicode、"ignore previous instructions"、凭据窃取尝试）
+- **截断处理** — 使用 70/20 头尾比例上限为 20,000 字符，并附截断标记
+- **剥离 YAML frontmatter** — `.hermes.md` 的 frontmatter 会被移除（保留供未来配置覆盖使用）
+
+## 仅在 API 调用时生效的层
+
+以下内容刻意*不*作为已缓存系统 prompt 的一部分持久化：
+
+- `ephemeral_system_prompt`
+- prefill 消息
+- gateway 派生的会话上下文覆盖层
+- 注入当前轮次用户消息的后续轮次 Honcho 召回内容
+
+这种分离使稳定前缀保持稳定，从而有效缓存。
+
+## 记忆快照
+
+本地记忆和用户配置文件数据在会话开始时作为冻结快照注入。会话中途的写入操作会更新磁盘状态，但不会修改已构建的系统 prompt，直到新会话开始或强制重建时才生效。
+
+## 上下文文件
+
+`agent/prompt_builder.py` 使用**优先级系统**扫描并清理项目上下文文件——只加载一种类型（先匹配先赢）：
+
+1. `.hermes.md` / `HERMES.md`（向上遍历至 git 根目录）
+2. `AGENTS.md`（启动时的 CWD；子目录在会话期间通过 `agent/subdirectory_hints.py` 逐步发现）
+3. `CLAUDE.md`（仅 CWD）
+4. `.cursorrules` / `.cursor/rules/*.mdc`（仅 CWD）
+
+`SOUL.md` 通过 `load_soul_md()` 单独加载用于身份槽位。加载成功后，`build_context_files_prompt(skip_soul=True)` 会防止其出现两次。
+
+长文件在注入前会被截断。
+
+## Skills 索引
+
+当 skills 工具可用时，skills 系统会向 prompt 贡献一个紧凑的 skills 索引。
+
+## 支持的 prompt 自定义入口
+
+大多数用户应将 `agent/prompt_builder.py` 视为实现代码，而非配置入口。推荐的自定义路径是修改 Hermes 已加载的 prompt 输入，而非直接编辑 Python 模板。
+
+### 优先使用这些入口
+
+- `~/.hermes/SOUL.md` — 用自定义 agent 角色和固定行为替换内置默认身份块。
+- `~/.hermes/MEMORY.md` 和 `~/.hermes/USER.md` — 提供应在新会话中快照的持久跨会话事实和用户配置文件数据。
+- 项目上下文文件，如 `.hermes.md`、`HERMES.md`、`AGENTS.md`、`CLAUDE.md` 或 `.cursorrules` — 注入仓库特定的工作规则。
+- Skills — 打包可复用的工作流和参考资料，无需编辑核心 prompt 代码。
+- 可选系统 prompt 配置 / API 覆盖 — 添加部署特定的指令文本，无需 fork Hermes。
+- 临时覆盖层，如 `HERMES_EPHEMERAL_SYSTEM_PROMPT` 或 prefill 消息 — 添加不应成为已缓存 prompt 前缀一部分的轮次级指导。
+
+### 何时应编辑代码
+
+仅当你刻意维护一个 fork 或向上游贡献行为变更时，才编辑 `agent/prompt_builder.py`。该文件为每个会话组装 prompt 管道、缓存边界和注入顺序。直接编辑该文件是全局产品变更，而非针对单个用户的 prompt 自定义。
+
+换言之：
+
+- 若想要不同的助手身份，编辑 `SOUL.md`
+- 若想要不同的仓库规则，编辑项目上下文文件
+- 若想要可复用的操作流程，添加或修改 skills
+- 若想改变 Hermes 为所有人组装 prompt 的方式，修改 Python 代码并将其视为代码贡献
+
+## Prompt 组装为何如此拆分
+
+该架构刻意优化以：
+
+- 保留提供商侧的 prompt 缓存
+- 避免不必要地修改历史记录
+- 保持记忆语义清晰可理解
+- 允许 gateway/ACP/CLI 添加上下文而不污染持久 prompt 状态
+
+## 相关文档
+
+- [上下文压缩与 Prompt 缓存](./context-compression-and-caching.md)
+- [会话存储](./session-storage.md)
+- [Gateway 内部机制](./gateway-internals.md)

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

@@ -0,0 +1,208 @@
+---
+sidebar_position: 4
+title: "Provider 运行时解析"
+description: "Hermes 如何在运行时解析 provider、凭据、API 模式及辅助模型"
+---
+
+# Provider 运行时解析
+
+Hermes 拥有一个共享的 provider 运行时解析器，用于以下场景：
+
+- CLI
+- gateway
+- cron 任务
+- ACP
+- 辅助模型调用
+
+主要实现：
+
+- `hermes_cli/runtime_provider.py` — 凭据解析，`_resolve_custom_runtime()`
+- `hermes_cli/auth.py` — provider 注册表，`resolve_provider()`
+- `hermes_cli/model_switch.py` — 共享 `/model` 切换流水线（CLI + gateway）
+- `agent/auxiliary_client.py` — 辅助模型路由
+- `providers/` — ABC + 注册表入口点（`ProviderProfile`、`register_provider`、`get_provider_profile`、`list_providers`）
+- `plugins/model-providers/<name>/` — 每个 provider 的插件（内置），声明 `api_mode`、`base_url`、`env_vars`、`fallback_models` 并在首次访问时将自身注册到注册表。用户插件位于 `$HERMES_HOME/plugins/model-providers/<name>/`，会覆盖同名的内置插件。
+
+`providers/` 中的 `get_provider_profile()` 为给定 provider id 返回一个 `ProviderProfile`。`runtime_provider.py` 在解析时调用它，以获取规范的 `base_url`、`env_vars` 优先级列表、`api_mode` 和 `fallback_models`，无需在多个文件中重复这些数据。在 `plugins/model-providers/<your-provider>/`（或 `$HERMES_HOME/plugins/model-providers/<your-provider>/`）下添加一个调用 `register_provider()` 的新插件，即可让 `runtime_provider.py` 自动识别它——无需在解析器本身中添加分支。
+
+如果你想添加一个新的一等推理 provider，请结合本页阅读 [添加 Provider](./adding-providers.md) 和 [Model Provider 插件指南](./model-provider-plugin.md)。
+
+## 解析优先级
+
+从高层来看，provider 解析使用以下顺序：
+
+1. 显式 CLI/运行时请求
+2. `config.yaml` 中的模型/provider 配置
+3. 环境变量
+4. provider 特定的默认值或自动解析
+
+该顺序很重要，因为 Hermes 将已保存的模型/provider 选择视为正常运行的真实来源。这可以防止过时的 shell 导出变量悄悄覆盖用户在 `hermes model` 中最后选择的端点。
+
+## Provider
+
+当前 provider 系列包括（完整内置集合见 `plugins/model-providers/`）：
+
+- AI Gateway（Vercel）
+- OpenRouter
+- Nous Portal
+- OpenAI Codex
+- Copilot / Copilot ACP
+- Anthropic（原生）
+- Google / Gemini（`gemini`）
+- Alibaba / DashScope（`alibaba`、`alibaba-coding-plan`）
+- DeepSeek
+- Z.AI
+- Kimi / Moonshot（`kimi-coding`、`kimi-coding-cn`）
+- MiniMax（`minimax`、`minimax-cn`、`minimax-oauth`）
+- Kilo Code
+- Hugging Face
+- OpenCode Zen / OpenCode Go
+- AWS Bedrock
+- Azure Foundry
+- NVIDIA NIM
+- xAI（Grok）
+- Arcee
+- GMI Cloud
+- StepFun
+- Qwen OAuth
+- Xiaomi
+- Ollama Cloud
+- LM Studio
+- Tencent TokenHub
+- Custom（`provider: custom`）— 适用于任何 OpenAI 兼容端点的一等 provider
+- 命名自定义 provider（`config.yaml` 中的 `custom_providers` 列表）
+
+## 运行时解析的输出
+
+运行时解析器返回的数据包括：
+
+- `provider`
+- `api_mode`
+- `base_url`
+- `api_key`
+- `source`
+- provider 特定的元数据，如过期/刷新信息
+
+## 为什么这很重要
+
+该解析器是 Hermes 能够在以下场景之间共享认证/运行时逻辑的主要原因：
+
+- `hermes chat`
+- gateway 消息处理
+- 在全新会话中运行的 cron 任务
+- ACP 编辑器会话
+- 辅助模型任务
+
+## AI Gateway
+
+在 `~/.hermes/.env` 中设置 `AI_GATEWAY_API_KEY`，并使用 `--provider ai-gateway` 运行。Hermes 从 gateway 的 `/models` 端点获取可用模型，筛选出支持工具调用的语言模型。
+
+## OpenRouter、AI Gateway 与自定义 OpenAI 兼容 base URL
+
+Hermes 包含相关逻辑，以避免在存在多个 provider 密钥时（例如同时存在 `OPENROUTER_API_KEY`、`AI_GATEWAY_API_KEY` 和 `OPENAI_API_KEY`）将错误的 API key 泄露给自定义端点。
+
+每个 provider 的 API key 仅作用于其自身的 base URL：
+
+- `OPENROUTER_API_KEY` 仅发送至 `openrouter.ai` 端点
+- `AI_GATEWAY_API_KEY` 仅发送至 `ai-gateway.vercel.sh` 端点
+- `OPENAI_API_KEY` 用于自定义端点及作为回退
+
+Hermes 还区分以下两种情况：
+
+- 用户主动选择的真实自定义端点
+- 未配置自定义端点时使用的 OpenRouter 回退路径
+
+这种区分对以下场景尤为重要：
+
+- 本地模型服务器
+- 非 OpenRouter/非 AI Gateway 的 OpenAI 兼容 API
+- 无需重新运行 setup 即可切换 provider
+- 通过 config 保存的自定义端点，即使当前 shell 中未导出 `OPENAI_BASE_URL` 也应正常工作
+
+## 原生 Anthropic 路径
+
+Anthropic 不再仅限于"通过 OpenRouter"访问。
+
+当 provider 解析选择 `anthropic` 时，Hermes 使用：
+
+- `api_mode = anthropic_messages`
+- 原生 Anthropic Messages API
+- `agent/anthropic_adapter.py` 进行转换
+
+原生 Anthropic 的凭据解析现在在两者同时存在时，优先使用可刷新的 Claude Code 凭据，而非复制的环境变量 token。实际效果为：
+
+- 包含可刷新认证的 Claude Code 凭据文件被视为首选来源
+- 手动设置的 `ANTHROPIC_TOKEN` / `CLAUDE_CODE_OAUTH_TOKEN` 值仍可作为显式覆盖
+- Hermes 在调用原生 Messages API 前会预检 Anthropic 凭据刷新
+- Hermes 在重建 Anthropic 客户端后，仍会在收到 401 时重试一次，作为回退路径
+
+## OpenAI Codex 路径
+
+Codex 使用独立的 Responses API 路径：
+
+- `api_mode = codex_responses`
+- 专用的凭据解析和认证存储支持
+
+## 辅助模型路由
+
+辅助任务包括：
+
+- 视觉
+- 网页提取摘要
+- 上下文压缩摘要
+- skills hub 操作
+- MCP 辅助操作
+- 记忆刷新
+
+这些任务可以使用各自独立的 provider/模型路由，而非主对话模型。
+
+当辅助任务配置的 provider 为 `main` 时，Hermes 通过与普通对话相同的共享运行时路径进行解析。实际效果为：
+
+- 环境变量驱动的自定义端点仍然有效
+- 通过 `hermes model` / `config.yaml` 保存的自定义端点同样有效
+- 辅助路由能够区分真实保存的自定义端点与 OpenRouter 回退
+
+## 回退模型
+
+Hermes 支持配置回退 provider 链——一个按顺序尝试的 `(provider, model)` 条目列表，当主模型遇到错误时依次尝试。旧版单对 `fallback_model` 字典仍被接受以保持向后兼容（并在首次写入时迁移）。
+
+### 内部工作原理
+
+1. **存储**：`AIAgent.__init__` 存储 `fallback_model` 字典并将 `_fallback_activated` 设为 `False`。
+
+2. **触发点**：`_try_activate_fallback()` 在 `run_agent.py` 主重试循环的三处被调用：
+   - 在无效 API 响应（None choices、缺少 content）达到最大重试次数后
+   - 在不可重试的客户端错误（HTTP 401、403、404）时
+   - 在瞬时错误（HTTP 429、500、502、503）达到最大重试次数后
+
+3. **激活流程**（`_try_activate_fallback`）：
+   - 若已激活或未配置，立即返回 `False`
+   - 调用 `auxiliary_client.py` 中的 `resolve_provider_client()` 构建带有正确认证的新客户端
+   - 确定 `api_mode`：openai-codex 使用 `codex_responses`，anthropic 使用 `anthropic_messages`，其余使用 `chat_completions`
+   - 原地替换：`self.model`、`self.provider`、`self.base_url`、`self.api_mode`、`self.client`、`self._client_kwargs`
+   - 对于 anthropic 回退：构建原生 Anthropic 客户端而非 OpenAI 兼容客户端
+   - 重新评估 prompt 缓存（对 OpenRouter 上的 Claude 模型启用）
+   - 将 `_fallback_activated` 设为 `True`——防止再次触发
+   - 将重试计数重置为 0 并继续循环
+
+4. **配置流程**：
+   - CLI：`cli.py` 读取 `CLI_CONFIG["fallback_model"]` → 传递给 `AIAgent(fallback_model=...)`
+   - Gateway：`gateway/run.py._load_fallback_model()` 读取 `config.yaml` → 传递给 `AIAgent`
+   - 验证：`provider` 和 `model` 键均须非空，否则回退被禁用
+
+### 不支持回退的场景
+
+- **子代理委托**（`tools/delegate_tool.py`）：子代理继承父代理的 provider，但不继承回退配置
+- **辅助任务**：使用各自独立的 provider 自动检测链（见上方辅助模型路由）
+
+Cron 任务**支持**回退：`run_job()` 从 `config.yaml` 读取 `fallback_providers`（或旧版 `fallback_model`）并传递给 `AIAgent(fallback_model=...)`，与 gateway 的 `_load_fallback_model()` 模式一致。参见 [Cron 内部机制](./cron-internals.md)。
+
+### 测试覆盖
+
+参见 `tests/test_fallback_model.py`，其中包含覆盖所有支持 provider、单次触发语义及边界情况的完整测试。
+
+## 相关文档
+
+- [Agent 循环内部机制](./agent-loop.md)
+- [ACP 内部机制](./acp-internals.md)
+- [上下文压缩与 Prompt 缓存](./context-compression-and-caching.md)