better-dsh 0.2.5 → 0.3.0-a

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

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

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

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