dsh-calibguard 0.2.4 → 0.3.0

package/engine/audit_service.py

@@ -0,0 +1,304 @@
+"""审计任务封装（T-G2.5）：把 calibguard.pipeline 包成“任务”模型供 API 层调用。
+
+铁律：
+  - 后端审计单并发：_JOB_LOCK 一把全局锁，后来的任务排队等待，禁止多 worker 并行；
+  - 逐字复用引擎入口（load_config + AuditPipeline），禁止重写审计逻辑；
+  - 引擎无阶段回调钩子 → stage 只写 "model" → "report" 两档，禁止伪造细粒度进度；
+  - 单文件异常记账后继续下一个文件，异常文本必须能冒泡到 UI。
+
+设置（gui-settings.json，2026-10-05 扩展）：
+  - 是否启用云端 LLM 复核、API Key、Base URL、模型名；
+  - 灰区范围（allow/block 阈值，默认 0.15 / 0.85）；
+  - LLM 送审内容源（精炼证据 / 文件原文）× 投递模式（截断 / 滑窗 / 一次性全部上传）
+    及其随附参数（截断字符数、滑窗字符数与重叠字符数）。
+  - 应用方式：直接改运行中 pipeline 的 cfg 字段 + 重建 LLM 客户端，**不重载模型**
+    （模型加载耗时数十秒，而上述设置都不影响模型权重与校准参数）。
+"""
+import dataclasses
+import json
+import os
+import threading
+import uuid
+
+from calibguard.config import LLM_CONTENT_SOURCES, LLM_DELIVERY_MODES, load_config, validate_config
+from calibguard.llm_analyzer import LLMAnalyzer
+from calibguard.pipeline import AuditPipeline
+
+_ROOT = os.path.dirname(os.path.abspath(__file__))
+SETTINGS_PATH = os.path.join(_ROOT, "gui-settings.json")
+
+_JOB_LOCK = threading.Lock()                    # 全局单并发锁
+_JOBS: dict[str, dict] = {}                     # job_id -> 状态
+_PIPELINE: AuditPipeline | None = None          # 引擎流水线单例（模型只加载一次）
+_PENDING_SETTINGS_REFRESH = False               # 审计运行期间被暂缓的设置应用请求
+
+# 阶段取值封闭集合（引擎无回调钩子，实际只会出现 model / report 两档）
+STAGE_MODEL = "model"
+STAGE_REPORT = "report"
+
+# ============================== 设置 ==============================
+
+# 默认设置（gui-settings.json 缺键时用这些值；与引擎 AppConfig 默认值保持一致）
+DEFAULT_SETTINGS: dict = {
+    "llm_enabled": True,
+    "deepseek_api_key": "",
+    "llm_base_url": "https://api.deepseek.com",
+    "llm_model": "deepseek-chat",
+    "allow_threshold": 0.15,
+    "block_threshold": 0.85,
+    "llm_content_source": "evidence",
+    "llm_delivery_mode": "truncate",
+    "llm_truncate_chars": 3000,
+    "llm_window_chars": 3000,
+    "llm_window_overlap": 500,
+}
+
+# 设置键 → 引擎 AppConfig 字段（用于把设置写进运行中的 cfg）
+_CFG_FIELDS = {
+    "llm_enabled": "llm_enabled",
+    "deepseek_api_key": "llm_api_key",
+    "llm_base_url": "llm_base_url",
+    "llm_model": "llm_model",
+    "allow_threshold": "allow_threshold",
+    "block_threshold": "block_threshold",
+    "llm_content_source": "llm_content_source",
+    "llm_delivery_mode": "llm_delivery_mode",
+    "llm_truncate_chars": "llm_truncate_chars",
+    "llm_window_chars": "llm_window_chars",
+    "llm_window_overlap": "llm_window_overlap",
+}
+
+_SETTINGS: dict = dict(DEFAULT_SETTINGS)
+
+
+def _coerce_settings(raw: dict) -> dict:
+    """把外部输入（JSON）规范化为合法设置字典；任何非法项抛 ValueError（中文说明）。
+
+    只接受已知键；未知键忽略（向前兼容）。
+    """
+    if not isinstance(raw, dict):
+        raise ValueError("设置必须是 JSON 对象")
+    merged = dict(DEFAULT_SETTINGS)
+    for key in DEFAULT_SETTINGS:
+        if key in raw:
+            merged[key] = raw[key]
+
+    if not isinstance(merged["llm_enabled"], bool):
+        raise ValueError("llm_enabled 必须是布尔值")
+    for key in ("deepseek_api_key", "llm_base_url", "llm_model"):
+        if not isinstance(merged[key], str):
+            raise ValueError(f"{key} 必须是字符串")
+    if merged["llm_enabled"] and not merged["llm_base_url"].strip():
+        raise ValueError("启用云端复核时 llm_base_url 不能为空")
+    if merged["llm_enabled"] and not merged["llm_model"].strip():
+        raise ValueError("启用云端复核时 llm_model 不能为空")
+
+    for key in ("allow_threshold", "block_threshold"):
+        try:
+            merged[key] = float(merged[key])
+        except (TypeError, ValueError) as exc:
+            raise ValueError(f"{key} 必须是 0~1 之间的数字") from exc
+    if not (0.0 < merged["allow_threshold"] < merged["block_threshold"] < 1.0):
+        raise ValueError(
+            f"灰区范围必须满足 0 < 下限({merged['allow_threshold']}) < "
+            f"上限({merged['block_threshold']}) < 1")
+
+    if merged["llm_content_source"] not in LLM_CONTENT_SOURCES:
+        raise ValueError(f"llm_content_source 必须是 {LLM_CONTENT_SOURCES} 之一")
+    if merged["llm_delivery_mode"] not in LLM_DELIVERY_MODES:
+        raise ValueError(f"llm_delivery_mode 必须是 {LLM_DELIVERY_MODES} 之一")
+    for key in ("llm_truncate_chars", "llm_window_chars", "llm_window_overlap"):
+        try:
+            merged[key] = int(merged[key])
+        except (TypeError, ValueError) as exc:
+            raise ValueError(f"{key} 必须是整数") from exc
+    if merged["llm_truncate_chars"] < 1:
+        raise ValueError("截断大小必须 ≥ 1 个字符")
+    if merged["llm_window_chars"] < 1:
+        raise ValueError("滑窗大小必须 ≥ 1 个字符")
+    if not (0 <= merged["llm_window_overlap"] < merged["llm_window_chars"]):
+        raise ValueError(
+            f"滑窗重叠必须满足 0 ≤ 重叠 < 滑窗大小({merged['llm_window_chars']})")
+    return merged
+
+
+def get_settings() -> dict:
+    """返回当前生效设置的副本（供 GET /api/settings 与 UI 回填）。"""
+    return dict(_SETTINGS)
+
+
+def _apply_settings_to_cfg(cfg, settings: dict) -> None:
+    """把设置写进 AppConfig 对应字段（键名映射见 _CFG_FIELDS）。"""
+    for key, field_name in _CFG_FIELDS.items():
+        setattr(cfg, field_name, settings[key])
+
+
+def _build_llm(cfg):
+    """按 cfg 构造云端 LLM 客户端（Key/BaseURL/模型名变更后重建）。"""
+    return LLMAnalyzer(
+        api_key=cfg.llm_api_key, base_url=cfg.llm_base_url, model=cfg.llm_model,
+        temperature=cfg.llm_temperature, max_tokens=cfg.llm_max_tokens,
+        timeout=cfg.llm_timeout, evidence_max_chars=cfg.evidence_max_chars)
+
+
+def _apply_settings_locked() -> None:
+    """把当前设置应用到运行中的 pipeline（调用方必须已持有 _JOB_LOCK）。
+
+    只改 cfg 字段 + 重建 LLM 客户端，**不重载模型**：这样设置变更绝不会与正在进行的
+    审计并发改写状态（补丁 11 约束），也不付出模型加载代价。
+    """
+    global _PENDING_SETTINGS_REFRESH
+    if _PIPELINE is None:
+        _PENDING_SETTINGS_REFRESH = False        # 流水线未建：下次创建自然读新设置
+        return
+    _apply_settings_to_cfg(_PIPELINE.cfg, _SETTINGS)
+    _PIPELINE.llm = _build_llm(_PIPELINE.cfg)
+    _PENDING_SETTINGS_REFRESH = False
+
+
+def _refresh_settings() -> bool:
+    """在 _JOB_LOCK 保护下应用设置；审计运行中则暂缓（不阻塞等待）。
+
+    不阻塞的原因：设置请求若等锁，会在审计期间把 HTTP 请求挂住；补丁 11 要求
+    “审计运行中禁止触发重建，UI 提示当前任务完成后生效”，故记待办后立即返回。
+    第二次尝试用于消解与任务收尾的竞态（锁刚释放时仍可即时生效）。
+    """
+    global _PENDING_SETTINGS_REFRESH
+    for _ in range(2):
+        if _JOB_LOCK.acquire(blocking=False):
+            try:
+                _apply_settings_locked()
+                return True
+            finally:
+                _JOB_LOCK.release()
+        _PENDING_SETTINGS_REFRESH = True         # 有任务在跑：暂缓
+    return False
+
+
+def load_settings() -> None:
+    """读 gui-settings.json，刷新内存设置，并把 Key 注入环境变量 DEEPSEEK_API_KEY。
+
+    引擎的 load_config 从环境变量读取 Key（主文档 6.2），本函数是 GUI 侧唯一注入点。
+    铁律：禁止读写 calibguard 的 config.yaml；禁止把 Key 写进任何日志。
+    """
+    global _SETTINGS
+    if not os.path.isfile(SETTINGS_PATH):
+        return
+    with open(SETTINGS_PATH, "r", encoding="utf-8") as handle:
+        payload = json.load(handle)
+    if not isinstance(payload, dict):
+        raise ValueError(f"设置文件格式错误（应为 JSON 对象）：{SETTINGS_PATH}")
+    _SETTINGS = _coerce_settings(payload)
+    _inject_api_key(_SETTINGS["deepseek_api_key"])
+
+
+def _inject_api_key(key: str) -> None:
+    """把 Key 注入（或清除）环境变量：留空即不使用云端（不留残余环境值）。"""
+    if key:
+        os.environ["DEEPSEEK_API_KEY"] = key
+    else:
+        os.environ.pop("DEEPSEEK_API_KEY", None)
+
+
+def save_settings(payload: dict) -> bool:
+    """合并并落盘设置（UTF-8 无 BOM），立即让配置生效。
+
+    支持部分更新：payload 中未出现的键保持当前值（旧版只传 deepseek_api_key 的调用
+    仍然可用）。返回设置是否已即时生效：False 表示当前有审计任务在跑（_JOB_LOCK 被
+    占用），应用已暂缓，等当前任务结束由 _run_job 落地（补丁 11 约束一）。
+    """
+    global _SETTINGS
+    if not isinstance(payload, dict):
+        raise ValueError("设置必须是 JSON 对象")
+    merged = dict(_SETTINGS)
+    merged.update(payload)
+    settings = _coerce_settings(merged)
+
+    with open(SETTINGS_PATH, "w", encoding="utf-8") as handle:
+        json.dump(settings, handle, ensure_ascii=False, indent=2)
+    _SETTINGS = settings
+    _inject_api_key(settings["deepseek_api_key"])
+    return _refresh_settings()
+
+
+def _get_pipeline() -> AuditPipeline:
+    """引擎流水线单例：首次调用加载模型（可耗时数十秒），之后全程复用。"""
+    global _PIPELINE
+    if _PIPELINE is None:
+        # 铁律 7：禁止读写 calibguard 的 config.yaml → 传 None 走引擎内置默认值，
+        # 相对路径（models/、reports/）由 server 的 cwd（项目根）解析。
+        cfg = load_config()
+        _apply_settings_to_cfg(cfg, _SETTINGS)
+        error = validate_config(cfg)
+        if error:
+            raise ValueError(f"设置非法，无法初始化引擎：{error}")
+        _PIPELINE = AuditPipeline(cfg)
+    return _PIPELINE
+
+
+# ============================== 任务模型 ==============================
+
+def create_job(paths: list[str]) -> str:
+    """建 job（排队态），返回 job_id；执行交给 daemon 线程 + 全局单并发锁。"""
+    job_id = uuid.uuid4().hex[:12]
+    _JOBS[job_id] = {
+        "state": "queued",
+        "paths": list(paths),
+        "stage": "",
+        "done": 0,
+        "total": len(paths),
+        "results": [],
+    }
+    threading.Thread(target=_run_job, args=(job_id,), daemon=True).start()
+    return job_id
+
+
+def job_status(job_id: str) -> dict:
+    """查询任务状态/进度/结果；未知 id 抛 KeyError（API 层转 404）。
+
+    返回浅拷贝：handler 线程序列化时后台线程仍在推进 job，避免“字典迭代期间改变大小”。
+    """
+    return dict(_JOBS[job_id])
+
+
+def _report_to_dict(report) -> dict:
+    """引擎报告归一化：CGv0.2.2 的 audit_file 直接返回 dict，原样透传（不增删字段）。"""
+    if isinstance(report, dict):
+        return report
+    if hasattr(report, "to_dict"):
+        return report.to_dict()
+    if dataclasses.is_dataclass(report):
+        return dataclasses.asdict(report)
+    raise TypeError(f"引擎返回了无法序列化的报告对象：{type(report).__name__}")
+
+
+def _run_job(job_id: str) -> None:
+    """单并发执行任务：逐文件调用引擎，单文件异常记账后继续。"""
+    job = _JOBS[job_id]
+    with _JOB_LOCK:                                  # 后来的任务在此排队等待
+        job["state"] = "running"
+        try:
+            pipeline = _get_pipeline()
+        except Exception as exc:
+            # 模型/校准参数/设置不可用属全局失败：显式暴露，绝不假成功
+            job["error"] = f"引擎初始化失败：{type(exc).__name__}: {exc}"
+            job["stage"] = STAGE_REPORT
+            for path in job["paths"]:
+                job["results"].append({"error": job["error"], "path": path})
+            job["done"] = job["total"]
+            job["state"] = "error"
+        else:
+            for path in job["paths"]:
+                job["stage"] = STAGE_MODEL               # 引擎无回调钩子：粗粒度两档
+                try:
+                    report = pipeline.audit_file(path)
+                    job["results"].append(_report_to_dict(report))
+                except Exception as exc:
+                    job["results"].append({"error": f"{type(exc).__name__}: {exc}", "path": path})
+                job["stage"] = STAGE_REPORT
+                job["done"] += 1
+            job["state"] = "done"
+
+    # 任务已结束（锁已释放）：落地审计运行期间被暂缓的设置更新（补丁 11 约束一）
+    if _PENDING_SETTINGS_REFRESH:
+        _refresh_settings()

package/engine/calibguard/__init__.py

@@ -0,0 +1,2 @@
+"""CalibGuard：本地 CodeBERT 校准门控 + 云端 LLM 按需分析的安全审计工具。"""
+__version__ = "1.0.0"

package/engine/calibguard/__main__.py

@@ -0,0 +1,4 @@
+from calibguard.cli import main
+
+if __name__ == "__main__":
+    main()

package/engine/calibguard/calibrator.py

@@ -0,0 +1,78 @@
+"""概率校准模块：Platt Scaling。
+
+公式（禁止改写）：P(y=1 | s) = 1 / (1 + exp(A * s + B))
+与温度缩放的关系（v1.0 不实现温度缩放）：P = σ(s/T) 等价于 A = -1/T, B = 0 的特例。
+"""
+import datetime
+import json
+import math
+
+from sklearn.linear_model import LogisticRegression
+
+
+class PlattCalibrator:
+    """Platt 校准器：logit → 校准概率；支持拟合与参数存取。"""
+
+    def __init__(self, A: float = 0.0, B: float = 0.0, method: str = "platt",
+                 n_samples: int = 0):
+        self.A = A
+        self.B = B
+        self.method = method
+        self.n_samples = n_samples
+
+    def fit(self, logits: list[float], labels: list[int]) -> None:
+        """在（logit, label）校准集上拟合 A、B。"""
+        if len(logits) != len(labels) or len(logits) == 0:
+            raise ValueError("logits 与 labels 长度必须相等且非空")
+        try:
+            lr = LogisticRegression(C=1e10, solver="lbfgs")
+            lr.fit([[s] for s in logits], labels)
+        except ValueError as exc:
+            # sklearn 在标签只有单一类别时抛 ValueError
+            raise RuntimeError("校准集必须同时包含良性与恶意样本") from exc
+        # sklearn: P = 1/(1+exp(-(w*s+b)))，与目标公式 1/(1+exp(A*s+B)) 对比得：
+        self.A = -float(lr.coef_[0][0])
+        self.B = -float(lr.intercept_[0])
+        self.n_samples = len(labels)
+
+    def predict_proba(self, logit: float) -> float:
+        """logit → 校准概率（含溢出保护）。"""
+        z = self.A * logit + self.B
+        if z > 700:
+            return 1e-16        # p 趋近 0
+        if z < -700:
+            return 1.0 - 1e-16  # p 趋近 1
+        return 1.0 / (1.0 + math.exp(z))
+
+    def save(self, path: str) -> None:
+        """写 JSON 参数文件（键名固定）。"""
+        payload = {
+            "A": self.A,
+            "B": self.B,
+            "method": self.method,
+            "n_samples": self.n_samples,
+            "fit_at": datetime.datetime.now().astimezone().isoformat(),
+        }
+        with open(path, "w", encoding="utf-8") as handle:
+            json.dump(payload, handle, ensure_ascii=False)
+
+    @classmethod
+    def load(cls, path: str) -> "PlattCalibrator":
+        """读 JSON 还原；文件不存在抛 FileNotFoundError，内容损坏抛 ValueError。"""
+        try:
+            with open(path, "r", encoding="utf-8") as handle:
+                payload = json.load(handle)
+            calibrator = cls(
+                A=float(payload["A"]),
+                B=float(payload["B"]),
+                method=str(payload.get("method", "platt")),
+                n_samples=int(payload.get("n_samples", 0)),
+            )
+        except (ValueError, KeyError, TypeError, AttributeError) as exc:
+            raise ValueError(f"校准参数文件损坏: {path}") from exc
+        return calibrator
+
+    @classmethod
+    def identity(cls) -> "PlattCalibrator":
+        """跳过校准时使用：A=-1, B=0（predict_proba 即 sigmoid）。"""
+        return cls(A=-1.0, B=0.0, method="none", n_samples=0)

package/engine/calibguard/cli.py

@@ -0,0 +1,74 @@
+"""命令行入口：argparse 解析、打印摘要、退出码管理。
+
+退出码：0 正常 / 1 路径不存在 / 2 配置错误 / 3 校准参数缺失 / 4 模型加载失败 / 5 未知内部错误。
+"""
+import argparse
+import os
+import sys
+
+from calibguard import __version__
+from calibguard.config import load_config
+from calibguard.pipeline import AuditPipeline
+
+
+def main() -> None:
+    """程序入口，管理退出码。"""
+    parser = argparse.ArgumentParser(
+        prog="calibguard",
+        description="CalibGuard：本地 CodeBERT 校准门控 + 云端 LLM 按需分析的安全审计工具。")
+    subparsers = parser.add_subparsers(dest="command")
+    audit_parser = subparsers.add_parser("audit", help="审计指定文件或目录")
+    audit_parser.add_argument("path", type=str, help="待审计的文件或目录路径")
+    audit_parser.add_argument("--config", default=None, help="配置文件路径")
+    audit_parser.add_argument("--output-dir", default=None, help="报告输出目录（覆盖配置）")
+    subparsers.add_parser("version", help="打印版本号")
+
+    args = parser.parse_args()
+
+    if args.command == "version":
+        print(f"CalibGuard {__version__}")
+        return
+    if args.command != "audit":
+        parser.print_help()
+        return
+
+    # 1. 加载配置（内部已处理退出码 2）
+    cfg = load_config(args.config)
+    # 2. 命令行覆盖输出目录
+    if args.output_dir:
+        cfg.report_output_dir = args.output_dir
+    # 3. 路径存在性检查
+    if not os.path.exists(args.path):
+        print(f"[错误] 路径不存在: {args.path}", file=sys.stderr)
+        sys.exit(1)
+    # 4. 构建流水线（模型 / 校准参数）
+    try:
+        pipeline = AuditPipeline(cfg)
+    except (FileNotFoundError, ValueError) as exc:
+        print(str(exc), file=sys.stderr)
+        sys.exit(3)
+    except RuntimeError as exc:
+        print(str(exc), file=sys.stderr)
+        sys.exit(4)
+
+    # 5-7. 审计、逐行摘要、统计
+    try:
+        reports = pipeline.audit_path(args.path)
+        total = len(reports)
+        counts = {"allow": 0, "block": 0, "suspicious": 0, "manual_review": 0}
+        for index, report in enumerate(reports, start=1):
+            print(f"[{index}/{total}] {report['file_path']}  "
+                  f"p={report['calibrated_probability']}  "
+                  f"gate={report['gate_decision']}  final={report['final_decision']}")
+            decision = report.get("final_decision")
+            if decision in counts:
+                counts[decision] += 1
+        print(f"审计完成：共 {total} 个文件 | 放行 {counts['allow']} | 拦截 {counts['block']} "
+              f"| 可疑 {counts['suspicious']} | 转人工 {counts['manual_review']}")
+        print(f"报告目录：{os.path.abspath(cfg.report_output_dir)}")
+    except Exception as exc:
+        print(f"[错误] 未知内部错误: {type(exc).__name__}: {exc}", file=sys.stderr)
+        sys.exit(5)
+
+    # 8. 正常结束
+    sys.exit(0)

package/engine/calibguard/config.py

@@ -0,0 +1,129 @@
+"""配置加载：config.yaml + 环境变量覆盖。"""
+import os
+import sys
+from dataclasses import dataclass
+
+import yaml
+
+# LLM 复核内容源（封闭集合）：evidence=精炼证据 / raw=预处理后的文件原文
+LLM_CONTENT_SOURCES = ("evidence", "raw")
+# LLM 复核投递模式（封闭集合）：truncate=截断 / window=滑窗 / all=一次性全部上传
+LLM_DELIVERY_MODES = ("truncate", "window", "all")
+
+
+@dataclass
+class AppConfig:
+    # 模型
+    model_base: str = "microsoft/codebert-base"
+    model_path: str = "models/codebert_finetuned"
+    max_length: int = 512
+    window_stride: int = 256
+    window_batch_size: int = 8
+    # 校准
+    calibration_params_path: str = "models/calibration_params.json"
+    # 门控
+    allow_threshold: float = 0.15
+    block_threshold: float = 0.85
+    early_stop_threshold: float = 0.9
+    # LLM
+    llm_enabled: bool = True                    # 是否使用云端 LLM 复核（False 时灰区按 0.5 切）
+    llm_api_key_env: str = "DEEPSEEK_API_KEY"   # 读取 API Key 的环境变量名（可被 yaml 覆盖）
+    llm_api_key: str = ""
+    llm_base_url: str = "https://api.deepseek.com"
+    llm_model: str = "deepseek-chat"
+    llm_temperature: float = 0.0
+    llm_max_tokens: int = 500
+    llm_timeout: int = 30
+    evidence_max_chars: int = 3000
+    # LLM 复核投递（2026-10-05 GUI 需求：内容源 × 投递模式）
+    llm_content_source: str = "evidence"        # evidence=精炼证据 / raw=文件原文
+    llm_delivery_mode: str = "truncate"         # truncate / window / all
+    llm_truncate_chars: int = 3000              # 截断模式：送审前 N 字符
+    llm_window_chars: int = 3000                # 滑窗模式：单窗字符数
+    llm_window_overlap: int = 500               # 滑窗模式：相邻窗重叠字符数
+    # 报告
+    report_output_dir: str = "reports"
+
+
+def validate_config(cfg: AppConfig) -> str | None:
+    """校验配置合法性：返回错误文本；None 表示通过。
+
+    抽成独立函数供两处复用：load_config（非法则退出码 2）与 GUI 设置保存前的预检
+    （非法则 400，绝不把非法值写进运行中的 cfg）。
+    """
+    if not (0.0 < cfg.allow_threshold < cfg.block_threshold < 1.0):
+        return (f"阈值必须满足 0 < allow({cfg.allow_threshold}) < "
+                f"block({cfg.block_threshold}) < 1")
+    if cfg.max_length > 512:
+        return f"max_length 不得超过 512（CodeBERT 上限），当前 {cfg.max_length}"
+    if not (1 <= cfg.window_stride < cfg.max_length):
+        return (f"window_stride 必须满足 1 ≤ stride < max_length(512)，"
+                f"当前 {cfg.window_stride}")
+    if cfg.window_batch_size < 1:
+        return f"window_batch_size 必须 ≥ 1，当前 {cfg.window_batch_size}"
+    if not (0.0 < cfg.early_stop_threshold < 1.0):
+        return f"early_stop_threshold 必须在 (0,1) 内，当前 {cfg.early_stop_threshold}"
+    if cfg.llm_content_source not in LLM_CONTENT_SOURCES:
+        return (f"llm_content_source 必须是 {LLM_CONTENT_SOURCES} 之一，"
+                f"当前 {cfg.llm_content_source!r}")
+    if cfg.llm_delivery_mode not in LLM_DELIVERY_MODES:
+        return (f"llm_delivery_mode 必须是 {LLM_DELIVERY_MODES} 之一，"
+                f"当前 {cfg.llm_delivery_mode!r}")
+    if cfg.llm_truncate_chars < 1:
+        return f"llm_truncate_chars 必须 ≥ 1，当前 {cfg.llm_truncate_chars}"
+    if cfg.llm_window_chars < 1:
+        return f"llm_window_chars 必须 ≥ 1，当前 {cfg.llm_window_chars}"
+    if not (0 <= cfg.llm_window_overlap < cfg.llm_window_chars):
+        return (f"llm_window_overlap 必须满足 0 ≤ overlap < window_chars"
+                f"({cfg.llm_window_chars})，当前 {cfg.llm_window_overlap}")
+    return None
+
+
+def load_config(path: str | None = None) -> AppConfig:
+    """加载配置。规则：默认值 < config.yaml < 环境变量（仅 API Key）。"""
+    cfg = AppConfig()
+    if path is not None and os.path.isfile(path):
+        with open(path, "r", encoding="utf-8") as f:
+            raw = yaml.safe_load(f) or {}
+        # 逐键覆盖（键不存在则保留默认值，禁止因缺键报错）
+        m = raw.get("model", {}) or {}
+        if "base_model" in m: cfg.model_base = str(m["base_model"])
+        if "finetuned_path" in m: cfg.model_path = str(m["finetuned_path"])
+        if "max_length" in m: cfg.max_length = int(m["max_length"])
+        if "window_stride" in m: cfg.window_stride = int(m["window_stride"])
+        if "window_batch_size" in m: cfg.window_batch_size = int(m["window_batch_size"])
+        c = raw.get("calibration", {}) or {}
+        if "params_path" in c: cfg.calibration_params_path = str(c["params_path"])
+        g = raw.get("gate", {}) or {}
+        if "allow_threshold" in g: cfg.allow_threshold = float(g["allow_threshold"])
+        if "block_threshold" in g: cfg.block_threshold = float(g["block_threshold"])
+        if "early_stop_threshold" in g: cfg.early_stop_threshold = float(g["early_stop_threshold"])
+        llm = raw.get("llm", {}) or {}
+        if "enabled" in llm: cfg.llm_enabled = bool(llm["enabled"])
+        if "api_key" in llm: cfg.llm_api_key = str(llm["api_key"])
+        if "base_url" in llm: cfg.llm_base_url = str(llm["base_url"])
+        if "model" in llm: cfg.llm_model = str(llm["model"])
+        if "temperature" in llm: cfg.llm_temperature = float(llm["temperature"])
+        if "max_tokens" in llm: cfg.llm_max_tokens = int(llm["max_tokens"])
+        if "timeout_seconds" in llm: cfg.llm_timeout = int(llm["timeout_seconds"])
+        if "evidence_max_chars" in llm: cfg.evidence_max_chars = int(llm["evidence_max_chars"])
+        if "api_key_env" in llm: cfg.llm_api_key_env = str(llm["api_key_env"])
+        if "content_source" in llm: cfg.llm_content_source = str(llm["content_source"])
+        if "delivery_mode" in llm: cfg.llm_delivery_mode = str(llm["delivery_mode"])
+        if "truncate_chars" in llm: cfg.llm_truncate_chars = int(llm["truncate_chars"])
+        if "window_chars" in llm: cfg.llm_window_chars = int(llm["window_chars"])
+        if "window_overlap" in llm: cfg.llm_window_overlap = int(llm["window_overlap"])
+        r = raw.get("report", {}) or {}
+        if "output_dir" in r: cfg.report_output_dir = str(r["output_dir"])
+    # API Key 环境变量优先级最高——必须在 if 块之外执行：
+    # 无论是否指定 --config、yaml 是否存在，环境变量都要读取
+    # （未加载 yaml 时，环境变量名用字段默认值 "DEEPSEEK_API_KEY"）
+    env_val = os.environ.get(cfg.llm_api_key_env, "")
+    if env_val:
+        cfg.llm_api_key = env_val
+    # 合法性校验：失败直接退出，退出码 2
+    error = validate_config(cfg)
+    if error:
+        print(f"[配置错误] {error}", file=sys.stderr)
+        sys.exit(2)
+    return cfg