后端配置与环境变量

Afterglow 后端通过 pydantic-settings 读取环境变量和 backend/.env。本页覆盖当前 Settings 支持的全部字段；可复制的模板见 backend/.env.example。

IMPORTANT

.env 包含模型密钥、访问密码和身份信息，不得提交到 Git。修改后必须完全重启后端； uvicorn --reload 不会因 .env 变化重建已缓存的 Settings。

首次使用和日常修改推荐使用后端配置 UI 与初始化向导。需要直接管理文件的高级用户可用配置文件编辑器在浏览器本地生成文件。模板提供英文注释版与中文注释版，参数值完全一致。

加载规则

• 操作系统环境变量会覆盖 .env，字段名大小写不敏感；文档统一使用大写。
• .env 和相对路径以启动后端时的工作目录为基准。源码运行时应先 cd backend。
• 未知字段会被忽略，拼写错误不一定在启动时报错，请以本页和 .env.example 为准。
• 下表的“默认/示例”优先表示 .env.example 的推荐值。CHAT_MODEL 模板值是 gpt-4o， 完全没有 .env 时的代码回退值是 gpt-4o-mini；LABEL_MAX_CONCURRENCY 分别是 19 和 1。
• 配置 WebUI 的字段白名单同样来自 .env.example，新增 Settings 字段时必须同步更新示例和本页。

入门配置流程见配置参考，数据外发范围见负责任使用与数据隐私。

重要联动规则

• RELATIONSHIP_TYPE=custom 时 RELATIONSHIP_DESCRIPTION 必填。
• SELF_UID / FRIEND_UID 支持逗号分隔多账号；不要把不同人合并成一个身份。
• LIFE_* 留空时复用主模型；RESPONSE_POLICY_* 再回退到 Life 链。
• QUERY_REWRITE_* 和 SCHEDULE_* 留空时优先复用 LABEL_*，然后回退到 Policy / Life / 主模型。
• RERANK_* 留空时复用 Policy / Life / 主模型；ADAPTIVE_CHUNK_* 优先复用 Label，再回退到 Life / 主模型。
• VISION_ENABLED=true 且 CHAT_MODEL_SUPPORTS_VISION=false 时，必须配置独立 VISION_API_URL / VISION_API_KEY / VISION_MODEL。
• WEB_FETCH_ENABLED 受 WEB_ACCESS_ENABLED 总开关控制。
• WINDOW_OVERLAP 必须小于 WINDOW_SIZE；ADAPTIVE_CHUNK_MAX_CHARS 必须不小于 ADAPTIVE_CHUNK_TARGET_CHARS。
• 更换 Embedding 模型或维度后不能复用旧向量库，需要重建索引。
• WRITEBACK_VECTORIZE=false 会用零向量写入 Live 消息，这些消息不参与语义向量召回。

应用、身份与关系

环境变量	默认/示例	作用
XUWEN_LANGUAGE	en	后端默认语言与主动消息语言：en 或 zh-CN。CLI --language 优先；普通 HTTP 可由 Accept-Language 覆盖；主动消息始终用后端配置。修改后重启。
APP_NAME	Afterglow	API 和前端展示的应用名。
APP_SLOGAN	把曾经对你好的话，续成往后的陪伴	应用副标题。
APP_TIMEZONE	Asia/Shanghai	传给模型的 IANA 时区，影响当前时间、作息和定时任务。
SELF_NAME	留空	当前用户的显示名，身份配置必填。
SELF_UID	留空	当前用户的平台 UID；可用逗号填多个。
FRIEND_NAME	留空	需要模仿的对方显示名，身份配置必填。
FRIEND_UID	留空	对方的平台 UID；可用逗号填多个。
SELF_UIDS	留空	历史兼容的多 UID 列表；推荐使用 SELF_UID 逗号串。
FRIEND_UIDS	留空	历史兼容的对方多 UID 列表；推荐使用 FRIEND_UID。
SELF_ALIASES	留空	当前用户的真名、网名、昵称和外号，逗号分隔。
FRIEND_ALIASES	留空	对方的别名列表，供清洗、检索和 Prompt 识别身份。
RELATIONSHIP_TYPE	friend	friend, lover, family, colleague, custom 之一。
RELATIONSHIP_DESCRIPTION	留空	关系自由描述；custom 时必填，其它类型也可覆盖默认描述。
PERSONA_TEMPLATE	xuwen	内置 xuwen/friend/lover/family/colleague 或自定义 .md.j2 绝对路径。
PROMPT_TEMPLATE_DIR	留空	完全覆盖内置 Prompt 模板目录；空字符串作为未设置处理。

主聊天模型

环境变量	默认/示例	作用
OPENAI_API_KEY	留空	主聊天模型的 API 密钥。
OPENAI_BASE_URL	https://api.openai.com/v1	OpenAI 兼容基础 URL，不要重复填 /chat/completions 或 /responses。
CHAT_MODEL	gpt-4o	生成最终回复的模型；无 .env 时代码回退为 gpt-4o-mini。
CHAT_API_PROTOCOL	chat_completions	主模型上游协议：chat_completions 或 responses；只影响主模型。
CHAT_TIMEOUT_SECONDS	60	主聊天模型请求超时秒数，必须大于 0。
LLM_REASONING_EFFORT	null	OpenAI 兼容 LLM reasoning effort；none, low, medium, high, xhigh 会传给上游，null 不传该字段。适用于主聊天、Life、互动决策、Schedule、Query Rewrite、Adaptive Chunk、Label、VLM；不作用于 Embedding、搜索、Rerank。

Responses 模式会向上游发送 store=false，不会为了使用 Prompt 缓存而持久化响应。Prompt 缓存由支持它的上游自动处理，是否命中仍取决于服务商能力、输入长度和前缀是否完全一致；切换协议不代表必然节省 token。调试端点的 model_chain[].response.usage.cached_tokens 可查看上游报告的缓存命中 token 数。生活状态、互动决策、Query Rewrite 和 LLM Rerank 等辅助模型仍使用 Chat Completions 协议。

生活状态模型

环境变量	默认/示例	作用
LIFE_API_URL	留空	生活状态模型基础 URL，空时复用主模型。
LIFE_API_KEY	留空	生活状态模型密钥，空时复用主模型。
LIFE_MODEL	留空	维护 life_state.json 的模型名，空时复用 CHAT_MODEL。
LIFE_TEMPERATURE	0.35	状态 JSON 生成温度，取值 0..2。
LIFE_MAX_TOKENS	1500	状态 JSON 最大输出 token；thinking 模型需预留推理 token。
LIFE_TIMEOUT_SECONDS	30	生活状态模型请求超时秒数，必须大于 0。
LIFE_UPDATE_INTERVAL_MINUTES	60	最长重新判断状态间隔；0 表示只按事件和 next_update_at 触发。
LIFE_MAX_REPLY_DELAY_SECONDS	45	生活状态建议的回复延迟上限。
LIFE_SLEEPING_MIN_REPLY_DELAY_SECONDS	8	sleeping 状态的最小延迟兜底；0 关闭。
LIFE_MARKER_UPDATE_ENABLED	true	异步归一化并剥离主模型输出的 <life-event>；兼容旧 <life-update>；false 仍会剥离标记。

互动决策模型

环境变量	默认/示例	作用
RESPONSE_POLICY_MODEL_ENABLED	false	在规则决策后启用小模型有界微调。
RESPONSE_POLICY_API_URL	留空	决策模型 URL，空时复用 Life / 主模型。
RESPONSE_POLICY_API_KEY	留空	决策模型密钥，空时复用 Life / 主模型。
RESPONSE_POLICY_MODEL	留空	决策模型名，空时复用 Life / 主模型。
RESPONSE_POLICY_TEMPERATURE	0.2	决策输出温度。
RESPONSE_POLICY_MAX_TOKENS	260	决策 JSON 最大输出 token。
RESPONSE_POLICY_TIMEOUT_SECONDS	8	决策模型请求超时秒数，必须大于 0。

输出、沉默与 Responses API

环境变量	默认/示例	作用
SILENCE_RESPONSE_SENTINEL	[silent]	决策层选择不回复时的 content 标识。
SILENCE_FINISH_REASON	silenced	silenced 或 stop；严格 OpenAI SDK 建议使用 stop。
AI_SILENCE_ENABLED	true	允许主模型在低风险场景主动沉默；不影响规则层安全沉默。
RESPONSE_STREAMING_ENABLED	false	false 使用 SSE 假流式整段发送；true 开启真流式。
RESPONSES_STORE_CAPACITY	512	previous_response_id 到 conversation_id 的进程内 LRU 容量，重启丢失。

长会话摘要

/v1/chat/completions 和 /v1/responses 会在历史超过以下任一阈值时，将较早内容增量总结，保留近期消息和当前输入的原文。摘要复用 LIFE_* 模型配置，与 RAG、关系记忆和生活状态准备并发执行。首次或再次触发压缩会增加一次或多次摘要调用，之后复用缓存，减少每轮主模型输入。字符阈值是长度估算，不等于模型 token 数。

变量	默认值	说明
CONVERSATION_SUMMARY_ENABLED	true	启用长会话摘要。关闭后传递全部历史。
CONVERSATION_SUMMARY_TRIGGER_CHARS	16000	未压缩历史与已有摘要的字符总数超过此值时更新摘要。
CONVERSATION_SUMMARY_TRIGGER_MESSAGES	40	未压缩历史消息超过此条数时更新摘要。
CONVERSATION_SUMMARY_KEEP_MESSAGES	16	压缩后最多保留的近期原文消息数。
CONVERSATION_SUMMARY_RECENT_CHARS	8000	压缩后近期原文字符预算；保留完整消息，尽量不拆开问答。
CONVERSATION_SUMMARY_MAX_CHARS	3000	摘要最大字符数。
CONVERSATION_SUMMARY_BATCH_CHARS	12000	每次摘要调用处理的新增原文字符预算；超长消息分批处理。
CONVERSATION_SUMMARY_TIMEOUT_SECONDS	30	单轮摘要更新的总超时预算，必须为有限正数。

摘要存于 PERSONA_DATA_DIR/conversation_summaries/，使用会话 ID 的哈希作为文件名。有稳定的 conversation_id（Chat Completions 也可回退到 caller_id）时可跨请求和重启复用；未提供时只压缩本次输入。缓存校验原文前缀，编辑历史或分支后重新总结。摘要只用于会话连续性，不改写原始聊天，不写入真人历史或长期关系事实。摘要失败会停止当前请求并保留上一版缓存。既有 Live 回写和 relationship_memory.md 继续独立工作。

主聊天 Prompt 使用最终融合/重排候选，FINAL_CONTEXT_K 控制候选总量；内置模板不再在 system 中重复放一份近期原文，自定义模板仍可使用 recent_conversation 变量。

Chat Completions 的 SSE 假流式会先发送完整正文，再解析定时任务并在收尾块交付 schedule_tasks；无需开启逐字流式也可避免正文等待任务提取。stream=false 的单个 JSON 响应仍需等待任务提取结束。

配置网页导入会在所有文件入库后统一尝试构建向量索引，遵循 LANCE_INDEX_MIN_ROWS；失败会显示警告并保留已导入数据，任务报告包含每张表的索引结果。已有数据可用 uv run xuwen index --language zh-CN 补建索引，新增数据可用 uv run xuwen optimize --language zh-CN 整理。

主动聊天（实验性）

环境变量	默认/示例	作用
PROACTIVE_ENABLED	false	主动聊天总开关，当前不建议产品开启。
PROACTIVE_LEARNING_MIN_GAP_MINUTES	120	学习“新一轮主动开聊”时的最小沉默间隔。
PROACTIVE_SCORE_THRESHOLD	0.55	主动触发最低分数。
PROACTIVE_CHECK_INTERVAL_SECONDS	900	前端或外部调度器建议轮询间隔。
PROACTIVE_MIN_IDLE_MINUTES	180	当前会话最小空闲时长。
PROACTIVE_MAX_PER_DAY	1	每个会话每日最多主动次数；0 禁止。
PROACTIVE_QUIET_HOURS	00:00-08:30	安静时段，支持跨午夜；留空关闭。
PROACTIVE_SKIP_WHEN_LIFE_BUSY	true	Life 状态为忙碌、睡眠或离开时跳过。
PROACTIVE_PROFILE_WINDOW_LIMIT	10000	缺少画像时从最近多少个对话窗口兜底重建。
PROACTIVE_AUDIT_MAX_RECORDS	200	主动决策审计的内存记录窗口。
PROACTIVE_CONTEXT_CACHE_ENABLED	true	保存 caller / conversation 的最近短上下文。
PROACTIVE_CONTEXT_CACHE_MAX_ITEMS	40	每会话最多缓存消息数。
PROACTIVE_CONTEXT_CACHE_PROMPT_ITEMS	12	主动生成时最多注入的缓存消息数。
PROACTIVE_CONTEXT_CACHE_MAX_TEXT_CHARS	240	缓存单条文本最大字符数。

Embedding

环境变量	默认/示例	作用
EMBEDDING_API_URL	https://maas-api.cn-huabei-1.xf-yun.com/v2	OpenAI 兼容 Embedding 基础 URL，不要重复填 /embeddings。
EMBEDDING_API_KEY	留空	Embedding 服务密钥。
EMBEDDING_MODEL	xop3qwen8bembedding	向量模型名。
EMBEDDING_DIM	4096	模型输出和 LanceDB schema 维度，必须一致且大于 0。更换后已有向量库需要重建，见故障排查。
EMBEDDING_TIMEOUT_SECONDS	60	Embedding 请求超时秒数，必须大于 0。
EMBEDDING_INPUT_MODE	array	array 批量标准协议或 single 单条协议。
EMBEDDING_BATCH_SIZE	25	每次请求最多文本数；single 模式强制为 1。
EMBEDDING_MAX_CONCURRENCY	20	同时在途的 HTTP 请求上限，必须大于 0。
EMBEDDING_MAX_REQUESTS_PER_MINUTE	0	每分钟请求上限；0 表示不主动限速。
EMBEDDING_INCLUDE_ENCODING_FORMAT	true	是否发送 encoding_format=float；部分网关不兼容时关闭。
EMBEDDING_SEND_DIMENSIONS	true	是否发送 dimensions；使用 MRL 模型时通常需开启。
EMBEDDING_RETRY_ATTEMPTS	8	含首次在内的总尝试次数。
EMBEDDING_RETRY_MAX_WAIT_SECONDS	10	指数退避时的单次最大等待秒数。
EMBEDDING_MAX_CONSECUTIVE_FAILURES	3	导入时连续多少个请求重试耗尽判定为系统性故障并终止；偶发失败只跳过该批继续，重新导入同一文件自动补齐。

视觉与历史图片

环境变量	默认/示例	作用
VISION_ENABLED	false	视觉能力总开关，同时控制历史图片离线描述。
CHAT_MODEL_SUPPORTS_VISION	false	主模型能否直接接收 OpenAI multimodal 图片内容。
VISION_API_URL	留空	主模型不支持图片时使用的 VLM 基础 URL。
VISION_API_KEY	留空	独立 VLM 密钥。
VISION_MODEL	qwen-vl-plus	独立 VLM 模型名。
VISION_DESCRIBE_PROMPT	Describe the image objectively in one or two sentences. Do not invent details.	图片转文本的提示词。
VISION_TIMEOUT_SECONDS	15	在线 chat/responses 路由等待 VLM 描图的总预算秒数，必须大于 0；不改变 VisionClient 默认 60 秒 HTTP 超时。
VISION_MAX_IMAGE_BYTES	8388608	单张图片最大字节，默认 8 MiB。
IMAGE_DATA_DIR	.data/images	按 SHA-256 保存历史原图的目录。

联网搜索与网页读取

环境变量	默认/示例	作用
WEB_ACCESS_ENABLED	false	联网总开关，关闭时不搜索也不读取 URL。
WEB_SEARCH_PROVIDER	tavily	tavily 或 searxng。
WEB_SEARCH_BASE_URL	https://api.tavily.com	搜索服务基础 URL。
WEB_SEARCH_API_KEY	留空	搜索服务密钥；SearXNG 通常可留空。
WEB_SEARCH_MAX_RESULTS	5	搜索结果数，代码最多保留 10。
WEB_SEARCH_TIMEOUT_SECONDS	8	搜索超时秒数，不能为负数。
WEB_SEARCH_LANGUAGE	zh-CN	搜索语言提示。
WEB_FETCH_ENABLED	true	是否读取用户提供的公开 URL，仍受联网总开关控制。
WEB_FETCH_TIMEOUT_SECONDS	8	单个网页读取超时秒数。
WEB_FETCH_MAX_URLS	2	单轮最多读取 URL 数，代码封顶 5。
WEB_FETCH_MAX_REDIRECTS	3	最大重定向次数，代码封顶 10。
WEB_FETCH_MAX_BYTES	524288	单页最大下载字节，代码封顶 2 MiB。
WEB_FETCH_MAX_CHARS	6000	注入 Prompt 的网页最大字符数，代码封顶 20000。

存储、鉴权、配置 UI 与隐私

环境变量	默认/示例	作用
LANCE_DB_PATH	.data/lancedb	LanceDB 向量库目录。
LANCE_UPSERT_BATCH_SIZE	128	merge_insert 单批行数；越小单批内存占用越低，写库越慢。导入报 Spill has sent an error 时调小无效，见故障排查。
LANCE_INDEX_MIN_ROWS	1000	自动创建物理向量索引的单表行数阈值；0 禁止自动创建。
PERSONA_DATA_DIR	.data/persona	persona、作息、生活状态和主动聊天画像目录。
ANALYSIS_DATA_DIR	.data/analysis	时间线、性格报告、块缓存与隔离实验结果目录。
API_AUTH_REQUIRED	true	是否要求后端 API 鉴权；/healthz 始终公开。
XUWEN_API_KEY	留空	Bearer / x-api-key 访问密码；非空时无论总开关值都会校验。
CONFIG_UI_ENABLED	false	显式挂载配置向导；缺少关键配置时主进程也可自动开启。
CONFIG_UI_PATH_PREFIX	/config	配置 UI 路径，必须以 / 开头且不能与业务 API 前缀重叠。
CONFIG_UI_LOCALHOST_ONLY	true	只允许本机客户端访问配置 UI。
CONFIG_UI_SETUP_TOKEN	留空	配置 UI 独立 token；空时启动生成一次性随机值。
CONFIG_UI_UPLOADS_DIR	.data/uploads	向导上传聊天记录的临时目录。
ENABLE_PII_REDACTION	true	入库前脱敏手机号、邮箱、证件、银行卡和 IP。
PII_RULES_PATH	留空	自定义 YAML / JSON 脱敏规则路径；空字符串作为未设置处理。

API 鉴权矩阵

API_AUTH_REQUIRED	XUWEN_API_KEY	结果
false	空	完全开放。
false	非空	仍强制校验 token。
true	空	业务路由返回 503。
true	非空	正常强制鉴权。

聊天记录切分

环境变量	默认/示例	作用
CHUNKING_STRATEGY	fixed	fixed 固定窗口或 adaptive 自适应话题切分。
SESSION_GAP_MINUTES	30	相邻消息超过此间隔时开启新会话。
WINDOW_SIZE	12	固定多轮窗口的消息数。
WINDOW_OVERLAP	3	相邻窗口重叠消息数，必须严格小于 WINDOW_SIZE。
SINGLE_CONTEXT_BEFORE	6	单条朋友消息前置上下文条数。
SINGLE_CONTEXT_AFTER	2	单条朋友消息后置上下文条数。
SINGLE_CONTEXT_MAX_CHARS	600	adaptive 模式下单条消息的 embedding 上下文字符预算。
ADAPTIVE_CHUNK_MODEL_ENABLED	false	adaptive 切分时是否调用小模型判断话题边界。
ADAPTIVE_CHUNK_API_URL	留空	切分模型 URL，留空使用回退链。
ADAPTIVE_CHUNK_API_KEY	留空	切分模型密钥。
ADAPTIVE_CHUNK_MODEL	留空	切分模型名。
ADAPTIVE_CHUNK_TEMPERATURE	0	分界输出温度，取值 0..2。
ADAPTIVE_CHUNK_MAX_TOKENS	900	单次分界 JSON 最大输出 token。
ADAPTIVE_CHUNK_TIMEOUT_SECONDS	60	adaptive 切分模型请求超时秒数，必须大于 0。
ADAPTIVE_CHUNK_MAX_MESSAGES_PER_CALL	80	单次交给分界模型的最大消息数。
ADAPTIVE_CHUNK_TARGET_CHARS	700	目标 chunk 字符数。
ADAPTIVE_CHUNK_MAX_CHARS	1400	chunk 字符硬上限，必须不小于目标值。
ADAPTIVE_CHUNK_MIN_TURNS	3	单个 adaptive chunk 的最小轮数。
ADAPTIVE_CHUNK_OVERLAP_TURNS	2	相邻 adaptive chunk 的重叠轮数。
ADAPTIVE_CHUNK_SOFT_GAP_MINUTES	8	用于辅助分界的软时间间隔。
ADAPTIVE_CHUNK_MAX_CONCURRENCY	0	>0 强制并发；0 时复用 Label 并发或回退到 4。
ADAPTIVE_CHUNK_CACHE_PATH	.data/ingestion/adaptive_chunk_cache.jsonl	模型切分结果缓存文件；中断重跑或重复导入时命中即免调模型，删除该文件即重置缓存。

关系分析

关系分析不是常驻行为，只在 xuwen analyze 或分析任务 API 被显式调用时运行。模型配置留空时复用主聊天模型。分析输入可能覆盖全部清洗后聊天文本，使用云端 API 前请阅读负责任使用与数据隐私。

环境变量	默认/示例	作用
ANALYSIS_API_URL	留空	OpenAI 兼容模型 URL；留空复用主聊天模型。
ANALYSIS_API_KEY	留空	分析模型密钥；留空复用主聊天模型密钥。
ANALYSIS_MODEL	留空	分析模型名；留空复用 CHAT_MODEL。
ANALYSIS_FINAL_API_URL	留空	最终关系阶段、普通人格报告、生活画像和实验人格画像使用的独立接口；留空复用 OPENAI_BASE_URL。
ANALYSIS_FINAL_API_KEY	留空	最终大模型的独立密钥；留空复用 OPENAI_API_KEY。
ANALYSIS_FINAL_MODEL	留空	最终关系阶段、普通人格报告、生活画像和实验人格画像使用的大模型；不用于块级失败回退。留空复用 CHAT_MODEL。
ANALYSIS_TEMPERATURE	0.3	块级 Map 与月度候选归并的默认温度，范围 0..2。
ANALYSIS_MAX_TOKENS	6000	单个块或月度候选归并的结构化输出 token 上限。过低可能截断 JSON。
ANALYSIS_FINAL_MAX_TOKENS	6000	最终大模型归并和人格画像输出 token 上限。
ANALYSIS_TIMEOUT_SECONDS	120	单次请求超时秒数，必须大于 0。
ANALYSIS_BLOCK_CHAR_BUDGET	10000	单个分析块的字符预算。
ANALYSIS_MAX_CONCURRENCY	3	同时在途的块分析请求数。
ANALYSIS_REQUEST_INTERVAL_SECONDS	0	相邻请求启动间隔；0 不额外等待。
ANALYSIS_PROACTIVE_ENABLED	true	是否使用最终分析模型逐次解释双方开聊动机和时间原因。每批最多发送 12 条开聊记录，每条记录包含上一轮尾部、开场和首条回应；会增加分析模型请求，续跑时按稳定开场 ID 复用已有结果。
ANALYSIS_PROACTIVE_BATCH_SIZE	4	每批发送的开聊记录数，范围 1..12；较小可降低结构化 JSON 被截断的概率。
ANALYSIS_PROACTIVE_MAX_CONCURRENCY	4	主动开聊原因分析的最大并发批次数，必须至少为 1。
ANALYSIS_LIFE_CONTEXT_ENABLED	false	是否把分析出的作息、睡眠、饮食、活动偏好和忙闲规律提供给生活时间线模型；当前时间和当天状态优先。
ANALYSIS_PERSONALITY_PROMPT_ENABLED	false	是否把去除原文证据后的普通人格画像提供给主聊天模型。独立于实验分析开关。
ANALYSIS_EXPERIMENTAL_ENABLED	false	是否为每个块增加独立实验 Map 并执行一次全局归并；默认关闭。
ANALYSIS_EXPERIMENTAL_PROMPT_ENABLED	false	是否额外调用分析模型优化一份去证据、去诊断措辞后的摘要并提供给主聊天模型；必须与上一项同时开启。

混合检索

环境变量	默认/示例	作用
RESPONSE_PAIR_TOP_K	24	response pair 向量召回数。
FRIEND_TOP_K	32	单条朋友发言召回数。
WINDOW_TOP_K	16	多轮历史窗口召回数。
HISTORY_IMAGE_TOP_K	8	历史图片 VLM 摘要召回数。
LIVE_TOP_K	12	Live 记忆语义召回数。
FINAL_CONTEXT_K	12	融合/重排后最多注入主 Prompt 的候选数。
RRF_K	60	Reciprocal Rank Fusion 平滑常数。
RETRIEVAL_TIMEOUT_SECONDS	15	单轮完整记忆检索的总超时秒数，包含改写、向量化、召回和重排；必须大于 0。
RETRIEVAL_OVERFETCH	3	每路向量库过取倍数，用于抵消过滤和去重损耗。
RECENCY_HALF_LIFE_DAYS	30	时间衰减半衰期天数。
RECENCY_MAX_BOOST	0.15	近期记忆最大加成。
WARMTH_BOOST	0.12	暖度评分加成系数。
LIVE_SOURCE_WEIGHT	1.08	Live 记忆来源权重。
HISTORY_SOURCE_WEIGHT	1.0	真人文本历史权重。
HISTORY_IMAGE_SOURCE_WEIGHT	0.75	历史图片摘要的融合权重。
AI_GENERATED_SOURCE_WEIGHT	0.25	AI 生成 Live 记忆的信任权重。
AI_GENERATED_LONG_TERM_ENABLED	false	是否允许 AI 回复跨会话长期参与检索。

Query Rewrite

环境变量	默认/示例	作用
QUERY_REWRITE_ENABLED	false	把短句、口语改写为更适合检索的查询。
QUERY_REWRITE_API_URL	留空	改写模型 URL，空时优先复用 Label 链。
QUERY_REWRITE_API_KEY	留空	改写模型密钥。
QUERY_REWRITE_MODEL	留空	改写模型名。
QUERY_REWRITE_TEMPERATURE	0	改写温度，取值 0..2。
QUERY_REWRITE_MAX_TOKENS	240	改写结果最大 token。
QUERY_REWRITE_MAX_VARIANTS	3	包含原查询在内的最大查询变体数。
QUERY_REWRITE_TIMEOUT_SECONDS	30	改写模型请求超时秒数，必须大于 0。

LLM Rerank（实验性）

环境变量	默认/示例	作用
RERANK_ENABLED	false	使用 LLM 对 RRF 候选做语义/风格精排，弱小模型通常不建议开启。
RERANK_MODE	auto	auto, always, never 之一。
RERANK_API_URL	留空	LLM reranker URL，空时复用 Policy / Life / 主模型。
RERANK_API_KEY	留空	LLM reranker 密钥。
RERANK_MODEL	留空	LLM reranker 模型名。
RERANK_TEMPERATURE	0	精排温度，取值 0..2。
RERANK_MAX_TOKENS	1200	精排 JSON 最大输出 token。
RERANK_TOP_K	28	交给 LLM 精排的候选数。
RERANK_MIN_CANDIDATES	16	触发精排所需的最小候选数。
RERANK_TIMEOUT_SECONDS	30	精排超时，失败时 fail-open 回退 RRF 顺序。
RERANK_WEIGHT	0.55	LLM 精排分与原检索分的混合权重，取值 0..1。
RERANK_MAX_SAME_SESSION	3	最终候选中同一 session 最多保留数。

Cross-encoder Rerank

环境变量	默认/示例	作用
CROSS_RERANK_ENABLED	false	在 LLM 精排前使用专用 cross-encoder 做语义粗排。
CROSS_RERANK_PROTOCOL	jina	jina 或 dashscope 请求协议。
CROSS_RERANK_API_URL	留空	Rerank 服务基础 URL。
CROSS_RERANK_API_KEY	留空	Rerank 服务密钥。
CROSS_RERANK_MODEL	留空	专用 reranker 模型名。
CROSS_RERANK_INPUT_K	48	从 RRF 池中交给 cross-encoder 的候选数。
CROSS_RERANK_TOP_N	16	粗排后保留数；通常应不小于 FINAL_CONTEXT_K。
CROSS_RERANK_TIMEOUT_SECONDS	5	cross-encoder 请求超时秒数，必须大于 0。

定时任务提取

环境变量	默认/示例	作用
SCHEDULE_EXTRACT_ENABLED	false	解析主模型的 <schedule-hint> 为结构化任务。
SCHEDULE_API_URL	留空	提取模型 URL，空时按 Label 到主模型的回退链复用。
SCHEDULE_API_KEY	留空	提取模型密钥。
SCHEDULE_MODEL	留空	提取模型名。
SCHEDULE_TEMPERATURE	0.1	时间解析 JSON 温度。
SCHEDULE_MAX_TOKENS	400	提取 JSON 最大 token。
SCHEDULE_TIMEOUT_SECONDS	60	定时任务提取模型请求超时秒数，必须大于 0。
SCHEDULE_MAX_HINTS_PER_TURN	5	单轮最多解析的 hint 数。
SCHEDULE_EXTRACT_TIMEOUT_SECONDS	10	整批解析超时；失败返回空且不阻断主回复。

Live 回写

环境变量	默认/示例	作用
WRITEBACK_ENABLED	true	是否把新对话写入 Live Memory。
WRITEBACK_QUEUE_SIZE	1000	异步回写队列容量。
WRITEBACK_BATCH_TURNS	8	每个会话累积多少轮后批量向量化与入库。
WRITEBACK_FLUSH_INTERVAL_SECONDS	300	会话无新消息时强制 flush 的间隔。
WRITEBACK_VECTORIZE	true	是否为 Live 消息生成向量；false 只用零向量入库。

调试与指标

环境变量	默认/示例	作用
DEBUG_ENDPOINTS_ENABLED	false	是否开放 /debug/*；调试完应关闭。
DEBUG_MODEL_FULL_PAYLOADS_ENABLED	false	是否在调试记录中保存完整 Prompt / Response 原文。
METRICS_CAPACITY	100	每类调用指标和模型链记录的环形缓冲容量。

表情包

环境变量	默认/示例	作用
STICKER_DATA_DIR	.data/stickers	表情包原图和 index.json 目录。
STICKER_MAX_FOR_AI	30	最多向主模型展示的可选表情数。
STICKER_MAX_IMAGE_BYTES	2097152	单张表情包最大字节，默认 2 MiB。
STICKER_REJECT_RETRY	true	非流式回复选中不存在的 sticker 时重试一次。

语义标签

环境变量	默认/示例	作用
LABELING_ENABLED	false	启用 mood / topic / importance 软标签。
LABEL_API_URL	https://open.bigmodel.cn/api/paas/v4	OpenAI 兼容打标模型 URL。
LABEL_API_KEY	留空	打标模型密钥。
LABEL_MODEL	glm-4-flash	打标模型名。
LABEL_TIMEOUT_SECONDS	30	打标模型请求超时秒数，必须大于 0。
LABEL_BATCH_SIZE	8	单次打标请求的消息数。
LABEL_MAX_CONCURRENCY	19	同时在途的打标批次；无 .env 时代码回退为 1。
LABEL_REQUEST_INTERVAL_SECONDS	0	相邻请求启动间隔；0 不额外等待。
LABEL_FLUSH_AFTER_N	20	保留字段，当前业务流程未消费。
LABEL_FLUSH_INTERVAL_SECONDS	300	保留字段，当前业务流程未消费。
LABEL_INCREMENTAL	true	保留字段；当前离线打标固定只处理未标注 chunk。
LABEL_MAX_CHARS_PER_MESSAGE	200	单条 chunk 放入打标 Prompt 的最大字符数。
LABEL_MOOD_VOCAB	留空	逗号分隔的自定义 mood 枚举；空时使用内置词表。

版本更新检查

环境变量	默认/示例	作用
UPDATE_CHECK_ENABLED	true	启动时是否查询最新发布版本。
UPDATE_CHECK_URL	https://api.github.com/repos/kldhsh123/Afterglow/releases/latest	版本查询公开 URL。
UPDATE_CHECK_TIMEOUT_SECONDS	8	更新检查超时秒数。