fmq/AstroResearch
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
5db4cc5998
AstroResearch/docs/architecture/agent/env-vars.md
Asfmq b11b8ad015 refactor: Agent 配置硬编码化、压缩系统不可变重构、前端组件化与安全硬化 
- AgentConfig: 移除 10+ 个环境变量读取，仅保留 TOKEN_SOFT/HARD_LIMIT 两个
    可调参数，context_char_limit 替换为统一的 token_soft_limit 阈值
  - compact: find_safe_cut_point 重写为 HashSet O(n) 算法，
    micro_compact 改为不可变风格，compress_context 签名升级为
    token_soft_limit + max_messages 双参数，新增 COMPACTION_OUTPUT_RESERVE
  - modes: ModeConfig.max_steps/tool_timeout_secs 去 Optional 化，
    Deep Research 步数 16→100，Literature Reader 步数 6→25
  - dashboard: 提取 AgentMarkdown/ThoughtCard/ToolCallCard/AnswerCard/
    SubAgentContainer 等共享组件，ResearchAgentPanel 大幅瘦身，
    交互卡片重构为 console-panel 紧凑风格
  - security: 移除 HERMES_YOLO_MODE、AGENT_BLOCK_NETWORK 开关、
    AGENT_CHECKPOINT_ENABLED 开关，关键安全机制强制启用
2026-06-25 00:49:45 +08:00

137 lines
8.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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_TOKEN_SOFT_LIMIT` | 32000 | usize | 各压缩层的统一触发阈值（token）。替代旧版 `AGENT_CONTEXT_CHAR_LIMIT`。用于 micro_compact / auto_compact 层的触发判断及 TokenBudget 软限制。 |
| `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_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`（程序自动设置） |
Reference in New Issue View Git Blame Copy Permalink