feat: require explicit runtime configuration

.env.example

@@ -1,21 +1,63 @@
+# 所有变量均为必填项；请在项目根目录复制本文件为 .env 后逐项填写。
+
+# ===== 应用 =====
+# 服务显示名称；仅用于 FastAPI 文档标题。
+KBQA_APP_NAME=KBQA
+# 是否启用调试模式。生产或日常本地使用请保持 false。
+KBQA_DEBUG=false
+
+# ===== DashScope 模型 =====
+# DashScope 兼容模式 API Key。必须保密，禁止提交到 Git。
 KBQA_DASHSCOPE_API_KEY=
+# DashScope OpenAI-compatible API 地址；使用专属实例时填写实例地址。
 KBQA_DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
+# 生成回答及 Agent 工具调用的聊天模型。
 KBQA_CHAT_MODEL=qwen3.5-flash
+# 文档分块向量化模型。
 KBQA_EMBEDDING_MODEL=text-embedding-v4
+# Embedding 向量维度，必须与已有 Milvus Lite 数据库一致。
 KBQA_EMBEDDING_DIM=1024
+
+# ===== 本地持久化 =====
+# SQLite 异步连接串；相对路径以“项目根目录”为基准。
 KBQA_DATABASE_URL=sqlite+aiosqlite:///./data/kbqa.sqlite3
+# Milvus Lite 文件路径；相对路径以“项目根目录”为基准。
 KBQA_MILVUS_URI=./data/milvus/kbqa.db
+# 上传原文件副本目录；相对路径以“项目根目录”为基准。
 KBQA_RAW_DATA_DIR=./data/raw
+
+# ===== 文档切分与检索 =====
+# 单个文本分块的最大字符数。
 KBQA_CHUNK_SIZE=500
+# 相邻分块重叠字符数，必须小于 KBQA_CHUNK_SIZE。
 KBQA_CHUNK_OVERLAP=50
+# 每次向量检索返回的候选数量。
 KBQA_RETRIEVAL_TOP_K=5
+# Research Agent 一轮中允许的最大检索次数。
 KBQA_MAX_RESEARCH_SEARCHES=3
+# 回答中最多展示的引用来源数。
 KBQA_MAX_SOURCES=8
+# 每个会话发送给模型的最大历史消息数。
 KBQA_HISTORY_MESSAGE_LIMIT=20
+# 单个上传文件大小上限，单位 MiB。
 KBQA_MAX_UPLOAD_MIB=20
+# 单次提问的最大字符数。
+KBQA_MAX_QUERY_LENGTH=10000
+# 允许前端跨域访问的地址，必须是合法 JSON 数组。
 KBQA_CORS_ORIGINS=["http://localhost:5173","http://127.0.0.1:5173"]
+
+# ===== 真实模型测试 =====
+# 仅设为 1 时才会执行真实 Chat / Embedding 测试。
 KBQA_RUN_LIVE_TESTS=0
-KBQA_LIVE_TEST_FILE=
+# 真实测试使用的知识文件路径；相对路径以项目根目录为基准。
+KBQA_LIVE_TEST_FILE=./test.txt
+
+# ===== LangSmith 追踪 =====
+# 是否向 LangSmith 写入 Agent、工具与模型追踪。
 LANGSMITH_TRACING=true
+# LangSmith 服务地址；官方服务通常为 https://api.smith.langchain.com。
+LANGSMITH_ENDPOINT=https://api.smith.langchain.com
+# LangSmith API Key。必须保密，禁止提交到 Git。
 LANGSMITH_API_KEY=
+# LangSmith 项目名称，用于归类本系统的追踪记录。
 LANGSMITH_PROJECT=kbqa-local