fmq/AstroResearch
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
698d007f39
AstroResearch/docs/architecture/agent/env-vars.md
Asfmq f6df9d8136 feat: Agent 思考模式前端可控、子代理全链路持久化、权限系统、工具 ID 追踪体系、前端面板与文档架构重构 
- AgentConfig/LlmClient 新增 enable_thinking 参数，前端 SSE 请求传递 thinking
  开关，仅千问/DashScope 时启用
  - 完善权限系统，支持细粒度的权限控制和用户权限申请
  - delegate_research 工具重命名为 subagent，SubAgentTool/SubAgentRunner 重构
  - 子代理消息（system/user/assistant/tool）持久化到 agent_messages 表，带 agent_name 标识
  - 子代理活动日志（工具调用列表+思考摘要）注入返回结果，Hooks 获得正确 session_id 和 subagent_name
  - LLM 工具调用 ID 回退生成 UUID（llm.rs），ToolCall/ToolResult SSE 事件增加 id/tool_call_id 双字段
  - ToolContext 扩展 session_id/sse_tx/enable_thinking 字段，executor 统一注入而非构造函数传参
  - agent_messages 新增 metadata+raw_json 列，agent_sessions 暴露 summary 字段
  - 删除文件级 transcript 快照（compact.rs），改为依赖 DB 持久化
  - ResearchAgentPanel 重写：TimelineItem 类型替代 StreamStep，支持会话历史回放
  - 新增 AgentMetricsPanel/AskUserQuestionCard/AuditLogViewer 三个前端组件，types.ts 完整类型定义
  - docs/architecture/ 分层重组：概览/核心模块/核心工作流 + agent/ 子目录 11 篇专题文档
  - docs/api.md 补充 RAG/Target/Agent 接口，docs/development.md 新建开发指南
  - .env.example 完全重写，补充 FALLBACK_MODEL 等变量说明
2026-06-18 01:21:02 +08:00

135 lines
7.7 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_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`（程序自动设置） |
Reference in New Issue View Git Blame Copy Permalink