# Agent 环境变量参考

Agent 系统的所有可配置参数，按子系统分类。

## 1. AgentConfig — ReAct 循环核心参数

`AgentConfig::from_env_optional()` 加载，所有变量可选，缺失时使用默认值。

| 变量 | 默认值 | 类型 | 说明 |
|:---|:---|:---|:---|
| `AGENT_MAX_STEPS` | 8 | usize | 单轮对话中最大 ReAct 迭代步数。到达后强制终止，注入"请根据已有信息直接给出最终答案"消息，调用 `final_answer_without_tools()` 不带工具生成最终回答。 |
| `AGENT_TOOL_TIMEOUT_SECS` | 120 | u64 | 单个工具调用的超时时间（秒）。`read_file` / `grep_files` 等快速工具通常 <1s；`download_paper` 可能需要 30-60s。超时后返回 `ToolOutput::error`，不终止整个 turn。 |
| `AGENT_MAX_TOOL_OUTPUT_CHARS` | 4000 | usize | 工具输出截断字符数。超过此值的输出被截断并在尾部附加 `[已截断，原始 N 字符]`。大文件的完整内容可通过 `maybe_persist_tool_result()` 写入磁盘，返回文件路径指针。 |
| `AGENT_CONTEXT_CHAR_LIMIT` | 16000 | usize | 上下文字符估算上限。用于 `rough_estimate_tokens` 与 micro_compact 层的触发判断。仅在 LLM 不返回精确 token 计数时作为后备。 |
| `AGENT_TOKEN_SOFT_LIMIT` | 32000 | usize | Token 预算软限制。达到 80% 时注入 💡 "Token 预算提示"；达到 100% 时注入 🟡 "Token 预算警告"；同时作为自动压缩的触发阈值（`estimated_tokens > soft_limit`）。 |
| `AGENT_TOKEN_HARD_LIMIT` | 40000 | usize | Token 预算硬限制。达到时注入 🔴 "已耗尽" 消息，强制要求模型立即给出最终答案。error recovery escalate 步骤可临时提升此值到 64,000。 |
| `AGENT_MAX_MESSAGES` | 50 | usize | snip_compact (Layer 0) 的触发阈值。消息数超过此值时截断中间段：保留前 3 条 + 后 47 条，中间替换为含工具名称列表的占位消息。 |

**硬编码参数**（非环境变量，修改需改代码）：

| 参数 | 值 | 位置 | 说明 |
|:---|:---|:---|:---|
| `duplicate_call_threshold` | 3 | `AgentConfig` | 工具连续以相同参数调用 3 次判定为死循环 |
| `HEAD_KEEP` | 3 | `compact.rs` | snip_compact 保留的头部消息数 |
| `MAX_CONSECUTIVE_FAILURES` | 3 | `circuit_breaker.rs` | 压缩熔断器触发阈值 |
| `AUTO_RECOVERY_TIMEOUT_SECS` | 300 | `circuit_breaker.rs` | 熔断器自动恢复等待时间 |
| `MAX_ENTRIES` | 100 | `file_cache.rs` | 文件状态缓存条目上限 |
| `MAX_CACHE_SIZE_BYTES` | 25 MB | `file_cache.rs` | 文件状态缓存内容总大小上限 |
| `POST_COMPACT_MAX_FILES_TO_RESTORE` | 5 | `file_cache.rs` | 压缩后恢复的文件数 |
| `POST_COMPACT_MAX_CHARS_PER_FILE` | 4,000 | `file_cache.rs` | 每文件恢复内容的字符上限 |
| `nag_after_steps` | 3 | `runtime/mod.rs` | TodoWrite 提醒间隔（步数） |
| `MAX_BACKOFF_RETRIES` | 10 | `runtime/mod.rs` | 429/529 退避重试最大次数 |

---

## 2. 错误恢复

| 变量 | 默认值 | 说明 |
|:---|:---|:---|
| `FALLBACK_MODEL` | — | 529 连续过载 3 次时尝试切换的备用模型名称。当前仅记录日志，因 `LlmClient` 的 model 不可变。需配合支持 model override 的客户端使用。 |

---

## 3. 自动记忆提取 (`memory/extraction.rs`)

`ExtractionConfig::from_env()` 加载。在每次会话结束时，可选地使用受限子代理分析对话内容并自动提取值得保留的记忆。

| 变量 | 默认值 | 说明 |
|:---|:---|:---|
| `EXTRACT_MEMORY_ENABLED` | false | 是否启用自动记忆提取。默认关闭以避免意外的 LLM 费用。提取在 turn 结束时 fire-and-forget 执行，不阻塞会话关闭。如果主代理已通过 `save_memory` 工具写入过记忆，则跳过提取。 |
| `EXTRACT_MEMORY_THROTTLE_TURNS` | 3 | 最小提取间隔（轮次）。避免每轮都消耗 LLM 调用进行提取。 |
| `EXTRACT_MEMORY_MAX_STEPS` | 3 | 提取子代理的最大 ReAct 步数。提取使用受限工具集（read_file, grep_files, glob_files, save_memory），步数较少以控制成本。 |

---

## 4. Agent 关联的系统级环境变量

以下变量在 `Config::from_env()` 中加载，直接影响 Agent 运行时。

### 4.1 核心 API

| 变量 | 默认值 | 说明 |
|:---|:---|:---|
| `LLM_API_KEY` | — | LLM API 密钥（OpenAI 兼容协议） |
| `LLM_API_BASE` | `https://api.openai.com/v1` | LLM API 基础地址 |
| `LLM_MODEL` | `gpt-4o-mini` | Agent 使用的对话模型 |
| `EMBEDDING_API_KEY` | 同 `LLM_API_KEY` | Embedding API 密钥 |
| `EMBEDDING_API_BASE` | 同 `LLM_API_BASE` | Embedding API 基础地址 |
| `EMBEDDING_MODEL` | `text-embedding-3-small` | RAG 使用的向量模型 |
| `EMBEDDING_DIM` | 1536 | 向量维度。与 `vec_paper_chunks` 表的维度校验相关，不匹配时自动重建。 |
| `ADS_API_KEY` | — | NASA ADS API Token（`search_papers` 工具使用） |

### 4.2 本地路径与端口

| 变量 | 默认值 | 说明 |
|:---|:---|:---|
| `DATABASE_URL` | `sqlite://library/astro_research.db` | SQLite 数据库路径 |
| `LIBRARY_DIR` | `./library` | 文献下载/解析/缓存的根目录 |
| `SKILLS_DIR` | `./skills` | Agent Skills 目录，SkillRegistry 从此加载 `{name}/SKILL.md` |
| `PORT` | 8000 | Axum 服务监听端口 |

### 4.3 云存储与解析

| 变量 | 默认值 | 说明 |
|:---|:---|:---|
| `QINIU_AK` | — | 七牛云 Access Key（PDF 配图托管） |
| `QINIU_SK` | — | 七牛云 Secret Key |
| `QINIU_BUCKET` | — | 七牛云存储空间名 |
| `QINIU_DOMAIN` | — | 七牛云 CDN 域名 |
| `MINERU_API_URL` | — | MinerU PDF 解析远程 API 地址 |
| `MINERU_API_KEY` | — | MinerU API Token |

### 4.4 日志

| 变量 | 默认值 | 说明 |
|:---|:---|:---|
| `LOG_LEVEL` | `info,astroresearch=debug` | 日志级别：trace / debug / info / warn / error，可指定模块级别 |
| `LOG_FORMAT` | `pretty` | 日志格式：`pretty`（彩色控制台）或 `json`（结构化） |
| `LOG_OUTPUTS` | `stdout,file` | 日志输出目标，逗号分隔：`stdout`（控制台）、`file`（滚动文件） |
| `LOG_DIR` | `./logs` | 日志文件目录（仅 `LOG_OUTPUTS` 含 `file` 时生效），按天滚动 |

### 4.5 其他

| 变量 | 默认值 | 说明 |
|:---|:---|:---|
| `OBSCURA_ROTATE_PROFILE` | `true` | Obscura 浏览器 Profile 轮换，用于绕过 Cloudflare/WAF |
| `OBSCURA_ALLOW_PRIVATE_NETWORK` | — | Obscura 内网访问许可（程序自动设置，无需手动配置） |

---

## 5. 与模型 Context Window 的配置建议

推荐的配置比例（为多轮对话预留空间）：

| 模型 Context | 建议 soft_limit | 建议 hard_limit | 说明 |
|:---|:---|:---|:---|
| 128K (GPT-4o) | 32,000 (25%) | 40,000 (31%) | 默认值适用 |
| 128K (Claude) | 32,000 (25%) | 64,000 (50%) | Claude 200K 则向上调整 |
| 200K (Claude) | 64,000 (32%) | 100,000 (50%) | 大 context 可更宽松 |
| 32K (旧模型) | 8,000 (25%) | 16,000 (50%) | 小 context 需更激进压缩 |

---

## 6. 关键源文件索引

| 文件 | 加载的变量 |
|:---|:---|
| `src/lib.rs` (Config) | `LLM_API_KEY`, `LLM_API_BASE`, `LLM_MODEL`, `EMBEDDING_*`, `ADS_API_KEY`, `DATABASE_URL`, `LIBRARY_DIR`, `SKILLS_DIR`, `PORT`, `QINIU_*`, `MINERU_*` |
| `src/main.rs` | `EMBEDDING_DIM` |
| `src/services/logging.rs` | `LOG_LEVEL`, `LOG_FORMAT`, `LOG_OUTPUTS`, `LOG_DIR` |
| `src/agent/runtime/mod.rs` (AgentConfig) | `AGENT_MAX_STEPS`, `AGENT_TOOL_TIMEOUT_SECS`, `AGENT_MAX_TOOL_OUTPUT_CHARS`, `AGENT_CONTEXT_CHAR_LIMIT`, `AGENT_TOKEN_SOFT_LIMIT`, `AGENT_TOKEN_HARD_LIMIT`, `AGENT_MAX_MESSAGES` |
| `src/agent/runtime/mod.rs` (call_llm_with_recovery) | `FALLBACK_MODEL` |
| `src/agent/memory/extraction.rs` (ExtractionConfig) | `EXTRACT_MEMORY_ENABLED`, `EXTRACT_MEMORY_THROTTLE_TURNS`, `EXTRACT_MEMORY_MAX_STEPS` |
| `src/services/download.rs` | `OBSCURA_ALLOW_PRIVATE_NETWORK`（程序自动设置） |