AstroResearch/.env.example

# =============================================================================
# AstroResearch 环境变量模板
# 复制此文件为 .env 并填入你的配置值
# =============================================================================

# ─────────────────────────────────────────────────────────────────────────────
# 1. 核心 API 服务
# ─────────────────────────────────────────────────────────────────────────────

# NASA ADS API Token（从 ui.adsabs.harvard.edu 申请）
ADS_API_KEY=your_ads_api_key_here

# VizieR TAP 星表查询服务（CDS 官方，公开访问无需认证，可选）
# VIZIER_TAP_URL=https://tapvizier.cds.unistra.fr/TAPVizieR/tap
# TAP 查询超时秒数（部分复杂 ADQL 较慢，默认 60）
# VIZIER_TIMEOUT_SECS=60

# 大语言模型配置（兼容 OpenAI 接口协议）
LLM_API_KEY=your_llm_api_key_here
LLM_API_BASE=https://api.openai.com/v1
# 可选模型示例：deepseek-chat, qwen-flash, gpt-4o-mini
LLM_MODEL=gpt-4o-mini

# 备用模型（连续 3 次 529 过载后自动切换，优先于 LLM_FALLBACK_CHAIN，可选）
# LLM_FALLBACK_MODEL=gpt-4o-mini
# 备用模型链（逗号分隔，按顺序轮换尝试，可选）
# LLM_FALLBACK_CHAIN=gpt-4o-mini,deepseek-chat

# 中型大语言模型配置（用于文献翻译、RAG，默认级联回退至核心 LLM 配置）
# LLM_MEDIUM_API_KEY=your_llm_medium_api_key_here
# LLM_MEDIUM_API_BASE=https://api.openai.com/v1
# LLM_MEDIUM_MODEL=gpt-4o-mini

# 快速大语言模型配置（用于记忆提取等后台辅助任务，默认级联回退至中型 LLM 配置）
# LLM_FAST_API_KEY=your_llm_fast_api_key_here
# LLM_FAST_API_BASE=https://api.openai.com/v1
# LLM_FAST_MODEL=gpt-3.5-turbo

# ── 视觉模型（可选，配置后启用图片分析能力）──
# 专用视觉模型名称。主 Agent 可为纯文本模型，图片分析通过 analyze_image 工具
# 委托给此模型。用户上传图片时也会先用此模型预处理再交给 Agent。
# LLM_VISION_MODEL=gpt-4o
# LLM_VISION_API_KEY=your_vision_api_key_here（空时回退到 LLM_API_KEY）
# LLM_VISION_API_BASE=https://api.openai.com/v1（空时回退到 LLM_API_BASE）

# 向量嵌入模型配置（未设置时默认回退到 LLM 的 API Key 和 Base）
# EMBEDDING_API_KEY=your_embedding_api_key_here
# EMBEDDING_API_BASE=https://api.openai.com/v1
# EMBEDDING_MODEL=text-embedding-3-small
# 向量维度（需与所选模型输出维度一致，默认 1536）
# EMBEDDING_DIM=1536
# 维度变更确认：修改 EMBEDDING_DIM 后需设置此变量为 1 才能启动（防止误改导致数据丢失）
# EMBEDDING_DIM_FORCE_REBUILD=1

# ─────────────────────────────────────────────────────────────────────────────
# Chunker 结构化切片参数（影响向量化粒度）
# ─────────────────────────────────────────────────────────────────────────────

# 子章节最大字符数（超出则递归切分），默认 2000
# CHUNKER_MAX_CHILD_CHARS=2000
# 短章节合并阈值（字符数），默认 200
# CHUNKER_SHORT_THRESHOLD=200
# 上下文重叠字符数，默认 100
# CHUNKER_OVERLAP_CHARS=100

# ─────────────────────────────────────────────────────────────────────────────
# 2. 七牛云对象存储（PDF 解析后的配图托管）
# ─────────────────────────────────────────────────────────────────────────────

QINIU_AK=your_qiniu_access_key_here
QINIU_SK=your_qiniu_secret_key_here
QINIU_BUCKET=your_bucket_name
QINIU_DOMAIN=http://your_cdn_domain.com

# ─────────────────────────────────────────────────────────────────────────────
# 3. 文档解析服务
# ─────────────────────────────────────────────────────────────────────────────

# MinerU PDF 解析远程 API（不使用 HTML 解析时可选）
# MINERU_API_URL=https://mineru.net/api/v4/extract/task
# MINERU_API_KEY=your_mineru_api_key_here

# ─────────────────────────────────────────────────────────────────────────────
# 4. 本地路径与端口
# ─────────────────────────────────────────────────────────────────────────────

# SQLite 数据库路径
DATABASE_URL=sqlite://library/astro_research.db
# 本地文献馆藏根目录
LIBRARY_DIR=./library
# Agent Skills 目录（Markdown 知识模块）
SKILLS_DIR=./skills
# 后端服务监听端口
PORT=8000
# 认证密码（必填，启动时未设置将拒绝启动）
ADMIN_PASSWORD=your_strong_password_here

# ─────────────────────────────────────────────────────────────────────────────
# 5. 日志配置
# ─────────────────────────────────────────────────────────────────────────────

# 日志级别：trace / debug / info / warn / error（可指定模块级别，如 info,astroresearch=debug）
LOG_LEVEL=info,astroresearch=debug
# 日志格式：pretty（彩色）或 json（结构化）
LOG_FORMAT=pretty
# 日志输出目标：stdout（控制台）、file（文件），逗号分隔可同时启用
LOG_OUTPUTS=stdout,file
# 日志文件目录（仅 LOG_OUTPUTS 含 file 时生效）
LOG_DIR=./logs

# ─────────────────────────────────────────────────────────────────────────────
# 6. Agent 运行时参数
# ─────────────────────────────────────────────────────────────────────────────

# Token 软限制：统一压缩触发阈值（默认 80000）
# AGENT_TOKEN_SOFT_LIMIT=80000
# Token 硬限制：触发强制压缩或终止（默认 100000）
# AGENT_TOKEN_HARD_LIMIT=100000

# ── 权限系统 ──
# Agent 工具权限规则（逗号分隔，支持内容级匹配 "ToolName(pattern)"）
# 规则优先级: Deny > Ask > Allow（先匹配先生效）
#
# 格式: "tool_name"                    → 工具级规则
#       "tool_name(content_pattern)"   → 内容级规则
#         示例: "run_bash(rm *)" 匹配以 rm 开头的 bash 命令
#               "read_file(*.env)" 匹配 .env 后缀的文件读取
#               "file_write(/etc/*)" 匹配 /etc/ 下的文件写入
#
# 权限模式:
#   default      — 标准：逐项按规则决定（默认）
#   accept_edits — 工作目录内的 file_write/file_edit 自动允许
#   bypass       — 跳过所有 Ask 检查（Deny 规则仍生效）
#   dont_ask     — 将所有 Ask 转为 Deny
# AGENT_PERMISSION_MODE=default
#
# 拒绝规则（逗号分隔，不可覆盖）
# AGENT_PERMISSIONS_DENY=run_bash(rm *),run_bash(sudo *)
# 允许规则（逗号分隔，显式允许）
# AGENT_PERMISSIONS_ALLOW=read_file,grep_files,glob_files,search_papers
# 询问规则（逗号分隔，需用户确认）
# AGENT_PERMISSIONS_ASK=run_bash,file_write,file_edit,download_paper

# 附加文件访问目录（逗号分隔，扩展 Agent 工作沙箱范围，默认空=仅工作目录）
# AGENT_ADDITIONAL_DIRS=/data,/tmp/astro

# 子代理工具白名单（逗号分隔工具名，空=继承父代理全部工具，可选）
# AGENT_SUBAGENT_ALLOWED_TOOLS=read_file,grep_files,search_papers

# ─────────────────────────────────────────────────────────────────────────────
# 7. 自动记忆提取（实验性功能，同时控制压缩记忆桥接 P3）
# ─────────────────────────────────────────────────────────────────────────────

# 是否启用自动记忆提取（默认 false，开启后会话结束 + 压缩时均触发提取）
# EXTRACT_MEMORY_ENABLED=false
# 记忆提取节流间隔：每 N 个 turn 触发一次（默认 3）
# EXTRACT_MEMORY_THROTTLE_TURNS=3
# 记忆提取子代理最大步数（默认 3）
# EXTRACT_MEMORY_MAX_STEPS=3

# ─────────────────────────────────────────────────────────────────────────────
# 8. 其他
# ─────────────────────────────────────────────────────────────────────────────

# Obscura 浏览器 Profile 轮换（绕过 Cloudflare/WAF，默认 true）
# OBSCURA_ROTATE_PROFILE=true