From 01b5a29b62c4d4aed2a8db4923f955538a8a4f75 Mon Sep 17 00:00:00 2001
From: gqt <3217233537@qq.com>
Date: Mon, 13 Jul 2026 14:49:35 +0800
Subject: [PATCH] feat: require explicit runtime configuration

---
 .env.example               | 44 +++++++++++++++++++++++++++++++-
 README.md                  | 22 +++++++++++++---
 backend/src/kbqa/config.py | 52 ++++++++++++++++++++------------------
 3 files changed, 88 insertions(+), 30 deletions(-)

diff --git a/.env.example b/.env.example
index f2250ea..b3c6591 100644
--- a/.env.example
+++ b/.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
diff --git a/README.md b/README.md
index 8f55e63..d78fb75 100644
--- a/README.md
+++ b/README.md
@@ -12,22 +12,36 @@
 
 ## 本地配置
 
-复制 `.env.example` 为 `.env` 并填写本地密钥。`.env`、`1.md`、`test.txt`
-均被 Git 忽略。LangSmith 会接收 Agent 输入、工具结果和运行轨迹。
+`.env` 是唯一运行配置来源，所有变量均为必填项；程序不提供运行参数默认值。复制
+`.env.example` 为 `.env`，阅读每项中文注释并填写真实值。必须从**项目根目录**执行下列
+命令，否则相对路径和 `.env` 文件位置会改变。`.env`、`1.md`、`test.txt` 均被 Git 忽略。
+LangSmith 会接收 Agent 输入、工具结果和运行轨迹。
+
+首次运行前建立本地数据目录：
+
+```bash
+mkdir -p data/raw data/milvus
+```
 
 ## 后端
 
 ```bash
+cd "$(git rev-parse --show-toplevel)"
 uv sync --project backend --all-groups
+mkdir -p data/raw data/milvus
 uv run --project backend alembic -c backend/alembic.ini upgrade head
-uv run --project backend uvicorn kbqa.main:app --app-dir backend/src --port 8000
+uv run --project backend uvicorn kbqa.main:app --app-dir backend/src --host 127.0.0.1 --port 8000
 ```
 
+`--port` 必须与 `web/vite.config.ts` 中 `/api` 代理目标的端口一致。仓库默认示例为
+`8000`；若你本地将代理改为 `8003`，后端也必须使用 `--port 8003`。
+
 ## 前端
 
 ```bash
+cd "$(git rev-parse --show-toplevel)"
 npm --prefix web install
-npm --prefix web run dev
+npm --prefix web run dev -- --host 127.0.0.1
 ```
 
 ## 普通验证
diff --git a/backend/src/kbqa/config.py b/backend/src/kbqa/config.py
index 817b81a..db4d99f 100644
--- a/backend/src/kbqa/config.py
+++ b/backend/src/kbqa/config.py
@@ -9,37 +9,39 @@ class Settings(BaseSettings):
     model_config = SettingsConfigDict(
         env_file=".env",
         env_prefix="KBQA_",
-        extra="ignore",
+        extra="forbid",
     )
 
-    app_name: str = "KBQA"
-    debug: bool = False
+    app_name: str
+    debug: bool
 
-    dashscope_api_key: str = ""
-    dashscope_base_url: str = "https://dashscope.aliyuncs.com/compatible-mode/v1"
-    chat_model: str = "qwen3.5-flash"
-    embedding_model: str = "text-embedding-v4"
-    embedding_dim: int = 1024
+    dashscope_api_key: str
+    dashscope_base_url: str
+    chat_model: str
+    embedding_model: str
+    embedding_dim: int
 
-    database_url: str = "sqlite+aiosqlite:///./data/kbqa.sqlite3"
-    milvus_uri: str = "./data/milvus/kbqa.db"
-    raw_data_dir: Path = Path("./data/raw")
+    database_url: str
+    milvus_uri: str
+    raw_data_dir: Path
 
-    chunk_size: int = Field(default=500, ge=1)
-    chunk_overlap: int = Field(default=50, ge=0)
-    retrieval_top_k: int = Field(default=5, ge=1, le=100)
-    max_research_searches: int = Field(default=3, ge=1, le=10)
-    max_sources: int = Field(default=8, ge=1, le=50)
-    history_message_limit: int = Field(default=20, ge=1, le=200)
-    max_upload_mib: int = Field(default=20, ge=1, le=1024)
-    max_query_length: int = Field(default=10_000, ge=1, le=100_000)
-    cors_origins: list[str] = [
-        "http://localhost:5173",
-        "http://127.0.0.1:5173",
-    ]
+    chunk_size: int = Field(ge=1)
+    chunk_overlap: int = Field(ge=0)
+    retrieval_top_k: int = Field(ge=1, le=100)
+    max_research_searches: int = Field(ge=1, le=10)
+    max_sources: int = Field(ge=1, le=50)
+    history_message_limit: int = Field(ge=1, le=200)
+    max_upload_mib: int = Field(ge=1, le=1024)
+    max_query_length: int = Field(ge=1, le=100_000)
+    cors_origins: list[str]
 
-    run_live_tests: bool = False
-    live_test_file: Path | None = None
+    run_live_tests: bool
+    live_test_file: Path
+
+    langsmith_tracing: bool = Field(validation_alias="LANGSMITH_TRACING")
+    langsmith_endpoint: str = Field(validation_alias="LANGSMITH_ENDPOINT")
+    langsmith_api_key: str = Field(validation_alias="LANGSMITH_API_KEY")
+    langsmith_project: str = Field(validation_alias="LANGSMITH_PROJECT")
 
     @field_validator("chunk_overlap")
     @classmethod