better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/features/context-files.md

@@ -0,0 +1,218 @@
+---
+sidebar_position: 8
+title: "上下文文件"
+description: "项目上下文文件 — .hermes.md、AGENTS.md、CLAUDE.md、全局 SOUL.md 以及 .cursorrules — 自动注入每次对话"
+---
+
+# 上下文文件
+
+Hermes Agent 会自动发现并加载上下文文件，以塑造其行为方式。部分文件属于项目本地文件，从工作目录中发现。`SOUL.md` 现在对整个 Hermes 实例全局生效，仅从 `HERMES_HOME` 加载。
+
+## 支持的上下文文件
+
+| 文件 | 用途 | 发现方式 |
+|------|---------|-----------| 
+| **.hermes.md** / **HERMES.md** | 项目指令（最高优先级） | 向上遍历至 git 根目录 |
+| **AGENTS.md** | 项目指令、规范、架构说明 | 启动时的 CWD 及子目录（渐进式） |
+| **CLAUDE.md** | Claude Code 上下文文件（同样支持检测） | 启动时的 CWD 及子目录（渐进式） |
+| **SOUL.md** | 当前 Hermes 实例的全局个性与语气定制 | 仅 `HERMES_HOME/SOUL.md` |
+| **.cursorrules** | Cursor IDE 编码规范 | 仅 CWD |
+| **.cursor/rules/*.mdc** | Cursor IDE 规则模块 | 仅 CWD |
+
+:::info 优先级系统
+每次会话仅加载**一种**项目上下文类型（先匹配先生效）：`.hermes.md` → `AGENTS.md` → `CLAUDE.md` → `.cursorrules`。**SOUL.md** 始终作为 agent 身份独立加载（插槽 #1）。
+:::
+
+## AGENTS.md
+
+`AGENTS.md` 是主要的项目上下文文件。它告知 agent 项目的结构、需要遵循的规范以及任何特殊指令。
+
+### 渐进式子目录发现
+
+会话启动时，Hermes 将工作目录中的 `AGENTS.md` 加载到系统 prompt（提示词）中。在会话期间，当 agent 通过 `read_file`、`terminal`、`search_files` 等工具导航进入子目录时，它会**渐进式发现**这些目录中的上下文文件，并在其变得相关的时刻将其注入对话。
+
+```
+my-project/
+├── AGENTS.md              ← 启动时加载（系统 prompt）
+├── frontend/
+│   └── AGENTS.md          ← agent 读取 frontend/ 文件时发现
+├── backend/
+│   └── AGENTS.md          ← agent 读取 backend/ 文件时发现
+└── shared/
+    └── AGENTS.md          ← agent 读取 shared/ 文件时发现
+```
+
+与启动时加载所有内容相比，此方式有两个优势：
+- **避免系统 prompt 膨胀** — 子目录提示仅在需要时出现
+- **保留 prompt 缓存** — 系统 prompt 在各轮次间保持稳定
+
+每个子目录在每次会话中最多检查一次。发现机制同样会向上遍历父目录，因此读取 `backend/src/main.py` 时，即使 `backend/src/` 没有自己的上下文文件，也会发现 `backend/AGENTS.md`。
+
+:::info
+子目录上下文文件与启动时的上下文文件经过相同的[安全扫描](#security-prompt-injection-protection)。恶意文件会被拦截。
+:::
+
+### AGENTS.md 示例
+
+```markdown
+# Project Context
+
+This is a Next.js 14 web application with a Python FastAPI backend.
+
+## Architecture
+- Frontend: Next.js 14 with App Router in `/frontend`
+- Backend: FastAPI in `/backend`, uses SQLAlchemy ORM
+- Database: PostgreSQL 16
+- Deployment: Docker Compose on a Hetzner VPS
+
+## Conventions
+- Use TypeScript strict mode for all frontend code
+- Python code follows PEP 8, use type hints everywhere
+- All API endpoints return JSON with `{data, error, meta}` shape
+- Tests go in `__tests__/` directories (frontend) or `tests/` (backend)
+
+## Important Notes
+- Never modify migration files directly — use Alembic commands
+- The `.env.local` file has real API keys, don't commit it
+- Frontend port is 3000, backend is 8000, DB is 5432
+```
+
+## SOUL.md
+
+`SOUL.md` 控制 agent 的个性、语气和沟通风格。完整详情请参阅[个性](/user-guide/features/personality)页面。
+
+**位置：**
+
+- `~/.hermes/SOUL.md`
+- 或 `$HERMES_HOME/SOUL.md`（若使用自定义主目录运行 Hermes）
+
+重要说明：
+
+- 若 `SOUL.md` 尚不存在，Hermes 会自动生成一个默认文件
+- Hermes 仅从 `HERMES_HOME` 加载 `SOUL.md`
+- Hermes 不会在工作目录中探测 `SOUL.md`
+- 若文件为空，`SOUL.md` 中的内容不会添加到 prompt
+- 若文件有内容，内容在扫描和截断后原样注入
+
+## .cursorrules
+
+Hermes 兼容 Cursor IDE 的 `.cursorrules` 文件和 `.cursor/rules/*.mdc` 规则模块。若这些文件存在于项目根目录，且未找到更高优先级的上下文文件（`.hermes.md`、`AGENTS.md` 或 `CLAUDE.md`），则将其作为项目上下文加载。
+
+这意味着使用 Hermes 时，现有的 Cursor 规范会自动生效。
+
+## 上下文文件的加载方式
+
+### 启动时（系统 prompt）
+
+上下文文件由 `agent/prompt_builder.py` 中的 `build_context_files_prompt()` 加载：
+
+1. **扫描工作目录** — 依次检查 `.hermes.md` → `AGENTS.md` → `CLAUDE.md` → `.cursorrules`（先匹配先生效）
+2. **读取内容** — 以 UTF-8 文本读取每个文件
+3. **安全扫描** — 检查内容是否存在 prompt 注入模式
+4. **截断** — 超过 20,000 个字符的文件进行首尾截断（70% 头部，20% 尾部，中间插入标记）
+5. **组装** — 所有部分合并在 `# Project Context` 标题下
+6. **注入** — 组装后的内容添加到系统 prompt
+
+### 会话期间（渐进式发现）
+
+`agent/subdirectory_hints.py` 中的 `SubdirectoryHintTracker` 监视工具调用参数中的文件路径：
+
+1. **路径提取** — 每次工具调用后，从参数（`path`、`workdir`、shell 命令）中提取文件路径
+2. **祖先目录遍历** — 检查该目录及最多 5 个父目录（跳过已访问的目录）
+3. **提示加载** — 若发现 `AGENTS.md`、`CLAUDE.md` 或 `.cursorrules`，则加载（每个目录先匹配先生效）
+4. **安全扫描** — 与启动文件相同的 prompt 注入扫描
+5. **截断** — 每个文件最多 8,000 个字符
+6. **注入** — 追加到工具结果中，使模型在上下文中自然看到
+
+最终 prompt 部分大致如下：
+
+```text
+# Project Context
+
+The following project context files have been loaded and should be followed:
+
+## AGENTS.md
+
+[Your AGENTS.md content here]
+
+## .cursorrules
+
+[Your .cursorrules content here]
+
+[Your SOUL.md content here]
+```
+
+注意，SOUL 内容直接插入，不带额外的包装文本。
+
+## 安全性：Prompt 注入防护
+
+所有上下文文件在被纳入之前都会扫描潜在的 prompt 注入。扫描器检查以下内容：
+
+- **指令覆盖尝试**：「ignore previous instructions」、「disregard your rules」
+- **欺骗模式**：「do not tell the user」
+- **系统 prompt 覆盖**：「system prompt override」
+- **隐藏 HTML 注释**：`<!-- ignore instructions -->`
+- **隐藏 div 元素**：`<div style="display:none">`
+- **凭据窃取**：`curl ... $API_KEY`
+- **密钥文件访问**：`cat .env`、`cat credentials`
+- **不可见字符**：零宽空格、双向覆盖字符、词连接符
+
+若检测到任何威胁模式，该文件将被拦截：
+
+```
+[BLOCKED: AGENTS.md contained potential prompt injection (prompt_injection). Content not loaded.]
+```
+
+:::warning
+此扫描器可防范常见注入模式，但不能替代对上下文文件的人工审查。对于非本人编写的共享仓库，请务必验证 AGENTS.md 的内容。
+:::
+
+## 大小限制
+
+| 限制 | 值 |
+|-------|-------|
+| 每个文件最大字符数 | 20,000（约 7,000 个 token） |
+| 头部截断比例 | 70% |
+| 尾部截断比例 | 20% |
+| 截断标记 | 10%（显示字符数并建议使用文件工具） |
+
+当文件超过 20,000 个字符时，截断提示如下：
+
+```
+[...truncated AGENTS.md: kept 14000+4000 of 25000 chars. Use file tools to read the full file.]
+```
+
+## 有效使用上下文文件的技巧
+
+:::tip AGENTS.md 最佳实践
+1. **保持简洁** — 远低于 20K 字符；agent 每轮都会读取
+2. **使用标题结构** — 用 `##` 分节描述架构、规范、重要说明
+3. **包含具体示例** — 展示首选代码模式、API 结构、命名规范
+4. **说明禁止事项** — 例如「不得直接修改迁移文件」
+5. **列出关键路径和端口** — agent 在执行终端命令时会用到
+6. **随项目演进更新** — 过时的上下文比没有上下文更糟
+:::
+
+### 子目录上下文
+
+对于 monorepo，在嵌套的 AGENTS.md 文件中放置子目录专属指令：
+
+```markdown
+<!-- frontend/AGENTS.md -->
+# Frontend Context
+
+- Use `pnpm` not `npm` for package management
+- Components go in `src/components/`, pages in `src/app/`
+- Use Tailwind CSS, never inline styles
+- Run tests with `pnpm test`
+```
+
+```markdown
+<!-- backend/AGENTS.md -->
+# Backend Context
+
+- Use `poetry` for dependency management
+- Run the dev server with `poetry run uvicorn main:app --reload`
+- All endpoints need OpenAPI docstrings
+- Database models are in `models/`, schemas in `schemas/`
+```

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/features/context-references.md

@@ -0,0 +1,142 @@
+---
+sidebar_position: 9
+sidebar_label: "Context References"
+title: "Context References"
+description: "用于将文件、文件夹、git diff 及 URL 直接附加到消息中的内联 @-语法"
+---
+
+# Context References
+
+输入 `@` 后跟一个引用，即可将内容直接注入消息。Hermes 会将引用内联展开，并在 `--- Attached Context ---` 区块下追加相应内容。
+
+## 支持的引用类型
+
+| 语法 | 说明 |
+|--------|-------------|
+| `@file:path/to/file.py` | 注入文件内容 |
+| `@file:path/to/file.py:10-25` | 注入指定行范围（从 1 开始，含首尾） |
+| `@folder:path/to/dir` | 注入目录树列表及文件元数据 |
+| `@diff` | 注入 `git diff`（未暂存的工作区变更） |
+| `@staged` | 注入 `git diff --staged`（已暂存的变更） |
+| `@git:5` | 注入最近 N 次提交及补丁（最多 10 次） |
+| `@url:https://example.com` | 抓取并注入网页内容 |
+
+## 使用示例
+
+```text
+Review @file:src/main.py and suggest improvements
+
+What changed? @diff
+
+Compare @file:old_config.yaml and @file:new_config.yaml
+
+What's in @folder:src/components?
+
+Summarize this article @url:https://arxiv.org/abs/2301.00001
+```
+
+单条消息中可使用多个引用：
+
+```text
+Check @file:main.py, and also @file:test.py.
+```
+
+引用值末尾的标点符号（`,`、`.`、`;`、`!`、`?`）会被自动去除。
+
+## CLI Tab 补全
+
+在交互式 CLI 中，输入 `@` 会触发自动补全：
+
+- `@` 显示所有引用类型（`@diff`、`@staged`、`@file:`、`@folder:`、`@git:`、`@url:`）
+- `@file:` 和 `@folder:` 触发文件系统路径补全，并显示文件大小元数据
+- 裸 `@` 后跟部分文本时，显示当前目录中匹配的文件和文件夹
+
+## 行范围
+
+`@file:` 引用支持行范围，用于精确注入内容：
+
+```text
+@file:src/main.py:42        # 单行第 42 行
+@file:src/main.py:10-25     # 第 10 至 25 行（含首尾）
+```
+
+行号从 1 开始。无效范围会被静默忽略（返回完整文件）。
+
+## 大小限制
+
+Context references 受大小限制，以防止超出模型的 context window（上下文窗口）：
+
+| 阈值 | 值 | 行为 |
+|-----------|-------|----------|
+| 软限制 | 上下文长度的 25% | 追加警告，继续展开 |
+| 硬限制 | 上下文长度的 50% | 拒绝展开，返回原始消息不变 |
+| 文件夹条目 | 最多 200 个文件 | 超出部分替换为 `- ...` |
+| Git 提交数 | 最多 10 次 | `@git:N` 限制在 [1, 10] 范围内 |
+
+## 安全性
+
+### 敏感路径拦截
+
+以下路径始终被 `@file:` 引用拦截，以防止凭据泄露：
+
+- SSH 密钥及配置：`~/.ssh/id_rsa`、`~/.ssh/id_ed25519`、`~/.ssh/authorized_keys`、`~/.ssh/config`
+- Shell 配置文件：`~/.bashrc`、`~/.zshrc`、`~/.profile`、`~/.bash_profile`、`~/.zprofile`
+- 凭据文件：`~/.netrc`、`~/.pgpass`、`~/.npmrc`、`~/.pypirc`
+- Hermes 环境文件：`$HERMES_HOME/.env`
+
+以下目录被完全拦截（目录内的任意文件均不可访问）：
+- `~/.ssh/`、`~/.aws/`、`~/.gnupg/`、`~/.kube/`、`$HERMES_HOME/skills/.hub/`
+
+### 路径遍历防护
+
+所有路径均相对于工作目录解析。解析结果超出允许的工作区根目录的引用将被拒绝。
+
+### 二进制文件检测
+
+通过 MIME 类型和空字节扫描检测二进制文件。已知文本扩展名（`.py`、`.md`、`.json`、`.yaml`、`.toml`、`.js`、`.ts` 等）会跳过基于 MIME 的检测。二进制文件将被拒绝并附带警告。
+
+## 平台可用性
+
+Context references 主要是 **CLI 功能**。它们在交互式 CLI 中有效，`@` 触发 tab 补全，引用在消息发送给 agent 之前完成展开。
+
+在**消息平台**（Telegram、Discord 等）中，`@` 语法不会被 gateway 展开——消息原样透传。agent 本身仍可通过 `read_file`、`search_files` 和 `web_extract` 工具引用文件。
+
+## 与 Context 压缩的交互
+
+当对话 context 被压缩时，展开后的引用内容会被纳入压缩摘要。这意味着：
+
+- 通过 `@file:` 注入的大文件内容会占用 context 用量
+- 若对话后续被压缩，文件内容将被摘要处理（而非原文保留）
+- 对于非常大的文件，建议使用行范围（`@file:main.py:100-200`）仅注入相关片段
+
+## 常用模式
+
+```text
+# 代码审查工作流
+Review @diff and check for security issues
+
+# 带上下文的调试
+This test is failing. Here's the test @file:tests/test_auth.py
+and the implementation @file:src/auth.py:50-80
+
+# 项目探索
+What does this project do? @folder:src @file:README.md
+
+# 研究
+Compare the approaches in @url:https://arxiv.org/abs/2301.00001
+and @url:https://arxiv.org/abs/2301.00002
+```
+
+## 错误处理
+
+无效引用会产生内联警告而非直接报错：
+
+| 条件 | 行为 |
+|-----------|----------|
+| 文件未找到 | 警告："file not found" |
+| 二进制文件 | 警告："binary files are not supported" |
+| 文件夹未找到 | 警告："folder not found" |
+| Git 命令失败 | 警告附带 git stderr 输出 |
+| URL 无内容返回 | 警告："no content extracted" |
+| 敏感路径 | 警告："path is a sensitive credential file" |
+| 路径超出工作区 | 警告："path is outside the allowed workspace" |

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/features/credential-pools.md

@@ -0,0 +1,240 @@
+---
+title: 凭证池
+description: 为每个提供商池化多个 API 密钥或 OAuth 令牌，实现自动轮换和速率限制恢复。
+sidebar_label: 凭证池
+sidebar_position: 9
+---
+
+# 凭证池
+
+凭证池允许你为同一提供商注册多个 API 密钥或 OAuth 令牌。当某个密钥触达速率限制或计费配额时，Hermes 会自动轮换到下一个健康密钥——在不切换提供商的情况下保持会话持续运行。
+
+这与[备用提供商](./fallback-providers.md)不同，后者会切换到*另一个*提供商。凭证池是同一提供商内的轮换；备用提供商是跨提供商的故障转移。池会优先尝试——如果池中所有密钥都耗尽，*才会*激活备用提供商。
+
+## 工作原理
+
+```
+Your request
+  → Pick key from pool (round_robin / least_used / fill_first / random)
+  → Send to provider
+  → 429 rate limit?
+      → Plan/usage limit reached (e.g. ChatGPT/Codex "usage limit reached")?
+          → Rotate to next pool key immediately (no retry — the cap won't clear on retry)
+      → Generic / transient 429?
+          → Retry same key once (transient blip)
+          → Second 429 → rotate to next pool key
+      → All keys exhausted → fallback_model (different provider)
+  → 402 billing error?
+      → Immediately rotate to next pool key (24h cooldown)
+  → 401 auth expired?
+      → Try refreshing the token (OAuth)
+      → Refresh failed → rotate to next pool key
+  → Success → continue normally
+```
+
+## 快速开始
+
+如果你已在 `.env` 中设置了 API 密钥，Hermes 会自动将其识别为单密钥池。要充分利用池化功能，请添加更多密钥：
+
+```bash
+# Add a second OpenRouter key
+hermes auth add openrouter --api-key sk-or-v1-your-second-key
+
+# Add a second Anthropic key
+hermes auth add anthropic --type api-key --api-key sk-ant-api03-your-second-key
+
+# Add an Anthropic OAuth credential (requires Claude Max plan + extra usage credits)
+hermes auth add anthropic --type oauth
+# Opens browser for OAuth login
+```
+
+查看你的池：
+
+```bash
+hermes auth list
+```
+
+输出：
+```
+openrouter (2 credentials):
+  #1  OPENROUTER_API_KEY   api_key env:OPENROUTER_API_KEY ←
+  #2  backup-key           api_key manual
+
+anthropic (3 credentials):
+  #1  hermes_pkce          oauth   hermes_pkce ←
+  #2  claude_code          oauth   claude_code
+  #3  ANTHROPIC_API_KEY    api_key env:ANTHROPIC_API_KEY
+```
+
+`←` 标记当前选中的凭证。
+
+## 交互式管理
+
+不带子命令运行 `hermes auth` 以进入交互式向导：
+
+```bash
+hermes auth
+```
+
+这会显示完整的池状态并提供操作菜单：
+
+```
+What would you like to do?
+  1. Add a credential
+  2. Remove a credential
+  3. Reset cooldowns for a provider
+  4. Set rotation strategy for a provider
+  5. Exit
+```
+
+对于同时支持 API 密钥和 OAuth 的提供商（Anthropic、Nous、Codex），添加流程会询问类型：
+
+```
+anthropic supports both API keys and OAuth login.
+  1. API key (paste a key from the provider dashboard)
+  2. OAuth login (authenticate via browser)
+Type [1/2]:
+```
+
+## CLI 命令
+
+| 命令 | 说明 |
+|---------|-------------|
+| `hermes auth` | 交互式池管理向导 |
+| `hermes auth list` | 显示所有池和凭证 |
+| `hermes auth list <provider>` | 显示指定提供商的池 |
+| `hermes auth add <provider>` | 添加凭证（提示选择类型和密钥） |
+| `hermes auth add <provider> --type api-key --api-key <key>` | 非交互式添加 API 密钥 |
+| `hermes auth add <provider> --type oauth` | 通过浏览器登录添加 OAuth 凭证 |
+| `hermes auth remove <provider> <index>` | 按从 1 开始的索引删除凭证 |
+| `hermes auth reset <provider>` | 清除所有冷却时间/耗尽状态 |
+
+## 轮换策略
+
+通过 `hermes auth` → "Set rotation strategy" 配置，或在 `config.yaml` 中设置：
+
+```yaml
+credential_pool_strategies:
+  openrouter: round_robin
+  anthropic: least_used
+```
+
+| 策略 | 行为 |
+|----------|----------|
+| `fill_first`（默认） | 持续使用第一个健康密钥直至耗尽，然后切换到下一个 |
+| `round_robin` | 均匀循环遍历所有密钥，每次选择后轮换 |
+| `least_used` | 始终选择请求次数最少的密钥 |
+| `random` | 在健康密钥中随机选择 |
+
+## 错误恢复
+
+池对不同错误的处理方式不同：
+
+| 错误 | 行为 | 冷却时间 |
+|-------|----------|----------|
+| **429 速率限制** | 对同一密钥重试一次（瞬时错误）。连续第二次 429 则轮换到下一个密钥 | 1 小时 |
+| **402 计费/配额** | 立即轮换到下一个密钥 | 24 小时 |
+| **401 认证过期** | 先尝试刷新 OAuth 令牌。仅在刷新失败时才轮换 | — |
+| **所有密钥耗尽** | 若已配置则转入 `fallback_model` | — |
+
+`has_retried_429` 标志在每次成功的 API 调用后重置，因此单次瞬时 429 不会触发轮换。
+
+## 自定义端点池
+
+自定义 OpenAI 兼容端点（Together.ai、RunPod、本地服务器）拥有各自的池，以 `config.yaml` 中 `custom_providers` 的端点名称作为键。
+
+通过 `hermes model` 设置自定义端点时，会自动生成类似 "Together.ai" 或 "Local (localhost:8080)" 的名称，该名称即成为池的键。
+
+```bash
+# After setting up a custom endpoint via hermes model:
+hermes auth list
+# Shows:
+#   Together.ai (1 credential):
+#     #1  config key    api_key config:Together.ai ←
+
+# Add a second key for the same endpoint:
+hermes auth add Together.ai --api-key sk-together-second-key
+```
+
+自定义端点池以 `custom:` 前缀存储在 `auth.json` 的 `credential_pool` 下：
+
+```json
+{
+  "credential_pool": {
+    "openrouter": [...],
+    "custom:together.ai": [...]
+  }
+}
+```
+
+## 自动发现
+
+Hermes 在启动时自动从多个来源发现凭证并初始化池：
+
+| 来源 | 示例 | 自动初始化？ |
+|--------|---------|-------------|
+| 环境变量 | `OPENROUTER_API_KEY`、`ANTHROPIC_API_KEY` | 是 |
+| OAuth 令牌（auth.json） | Codex device code、Nous device code | 是 |
+| Claude Code 凭证 | `~/.claude/.credentials.json` | 是（Anthropic） |
+| Hermes PKCE OAuth | `~/.hermes/auth.json` | 是（Anthropic） |
+| 自定义端点配置 | `config.yaml` 中的 `model.api_key` | 是（自定义端点） |
+| 手动条目 | 通过 `hermes auth add` 添加 | 持久化至 auth.json |
+
+自动初始化的条目在每次池加载时更新——如果你删除了某个环境变量，其池条目会自动清除。通过 `hermes auth add` 添加的手动条目永远不会被自动清除。
+
+## 委托与子代理共享
+
+当代理通过 `delegate_task` 派生子代理时，父代理的凭证池会自动共享给子代理：
+
+- **相同提供商** — 子代理接收父代理的完整池，在触达速率限制时可进行密钥轮换
+- **不同提供商** — 子代理加载该提供商自己的池（如已配置）
+- **未配置池** — 子代理回退到继承的单个 API 密钥
+
+这意味着子代理无需额外配置即可获得与父代理相同的速率限制弹性。按任务的凭证租用机制确保子代理在并发轮换密钥时不会相互冲突。
+
+## 线程安全
+
+凭证池对所有状态变更操作（`select()`、`mark_exhausted_and_rotate()`、`try_refresh_current()`、`mark_used()`）使用线程锁，确保 gateway（网关）同时处理多个聊天会话时的并发访问安全。
+
+## 架构
+
+完整的数据流图请参见仓库中的 [`docs/credential-pool-flow.excalidraw`](https://excalidraw.com/#json=2Ycqhqpi6f12E_3ITyiwh,c7u9jSt5BwrmiVzHGbm87g)。
+
+凭证池集成于提供商解析层：
+
+1. **`agent/credential_pool.py`** — 池管理器：存储、选择、轮换、冷却时间
+2. **`hermes_cli/auth_commands.py`** — CLI 命令和交互式向导
+3. **`hermes_cli/runtime_provider.py`** — 感知池的凭证解析
+4. **`run_agent.py`** — 错误恢复：429/402/401 → 池轮换 → 备用
+
+## 存储
+
+池状态存储在 `~/.hermes/auth.json` 的 `credential_pool` 键下：
+
+```json
+{
+  "version": 1,
+  "credential_pool": {
+    "openrouter": [
+      {
+        "id": "abc123",
+        "label": "OPENROUTER_API_KEY",
+        "auth_type": "api_key",
+        "priority": 0,
+        "source": "env:OPENROUTER_API_KEY",
+        "access_token": "sk-or-v1-...",
+        "last_status": "ok",
+        "request_count": 142
+      }
+    ]
+  },
+}
+```
+
+策略存储在 `config.yaml` 中（而非 `auth.json`）：
+
+```yaml
+credential_pool_strategies:
+  openrouter: round_robin
+  anthropic: least_used
+```