AstroResearch/docs/architecture/agent/env-vars.md

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, LLM_FALLBACK_MODEL, LLM_FALLBACK_CHAIN, 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)	LLM_FALLBACK_MODEL (原 FALLBACK_MODEL), LLM_FALLBACK_CHAIN (P3)
src/agent/runtime/mod.rs (AgentRuntime)	AGENT_COORDINATOR_MAX_WORKERS, AGENT_COORDINATOR_WORKER_TIMEOUT (P2)
src/agent/compact.rs (extract_memories_from_compaction)	EXTRACT_MEMORY_ENABLED (P3 压缩记忆桥接)
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（程序自动设置）