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

8.0 KiB

Raw Blame History

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`（程序自动设置）

8.0 KiB Raw Blame History Unescape Escape