dsh-calibguard 0.2.5 → 0.3.0

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

package/engine/calibguard/constants.py

@@ -0,0 +1,117 @@
+"""CalibGuard 全局常量。所有列表为封闭集合，禁止增删；所有阈值禁止修改。"""
+
+# ============ 标签约定 ============
+LABEL_BENIGN = 0     # 良性类别索引（训练时 label=0，模型输出 logits 索引 0）
+LABEL_MALICIOUS = 1  # 恶意类别索引（训练时 label=1，模型输出 logits 索引 1）
+
+# ============ 危险 API 模式（封闭） ============
+DANGEROUS_API_PATTERNS = [
+    r"subprocess\.(?:run|call|Popen|check_output|check_call)\s*\(",
+    r"os\.system\s*\(",
+    r"os\.popen\s*\(",
+    r"\beval\s*\(",
+    r"\bexec\s*\(",
+    r"pickle\.loads?\s*\(",
+    r"__import__\s*\(",
+]
+
+# ============ 网络行为模式（封闭） ============
+NETWORK_PATTERNS = [
+    r"https?://[^\s'\"<>]+",
+    r"\b(?:\d{1,3}\.){3}\d{1,3}\b",
+    r"\b(?:curl|wget)\b",
+    r"requests\.(?:post|get|put|delete|head)\s*\(",
+    r"urllib\.request\.(?:urlopen|Request)\s*\(",
+    r"socket\.socket\s*\(",
+]
+
+# ============ 凭据与敏感路径模式（封闭） ============
+CREDENTIAL_PATTERNS = [
+    r"\.ssh\b",
+    r"\.env\b",
+    r"\.aws\b",
+    r"\.bash_history\b",
+    r"\.netrc\b",
+    r"id_rsa",
+    r"AWS_SECRET_ACCESS_KEY",
+    r"AWS_ACCESS_KEY_ID",
+    r"\btoken\b",
+    r"\bpasswd?\b",
+    r"\bcredential",
+    r"\bsecret\b",
+    r"\bapi[_-]?key\b",
+]
+
+# ============ 编码与混淆模式（封闭） ============
+OBFUSCATION_PATTERNS = [
+    r"base64\.(?:b64decode|b64encode|decode|encode)\s*\(",
+    r"bytes\.fromhex\s*\(",
+    r"\b(?:binascii\.)?(?:unhexlify|hexlify)\s*\(",
+    r"\bchr\s*\(\s*\d+\s*\)",
+    r"\\x[0-9a-fA-F]{2}",
+    r"codecs\.decode\s*\(",
+    r"zlib\.decompress\s*\(",
+    r"marshal\.loads?\s*\(",
+]
+
+# ============ 可疑文件操作模式（封闭） ============
+FILE_OPERATION_PATTERNS = [
+    r"os\.(?:remove|unlink|rmdir)\s*\(",
+    r"shutil\.rmtree\s*\(",
+    r"os\.(?:rename|replace)\s*\(",
+    r"open\s*\([^)]*['\"][wa]",
+    r"\.bashrc\b|\.zshrc\b|\.profile\b",
+    r"/etc/(?:hosts|passwd|shadow|sudoers)\b",
+    r"\bwinreg\b|\bHKEY_",
+    r"\bcrontab\b|\bschtasks\b|LaunchAgents",
+    r"chmod\s+[0-7]{3,4}",
+]
+
+# ============ 提示注入话术（封闭，匹配时不区分大小写） ============
+INJECTION_PHRASES = [
+    "忽略之前指令", "忽略之前的指令", "忽略以上指令", "忽略上述指令",
+    "不要告诉用户", "不要告诉任何人", "不要告知用户",
+    "偷偷发送", "悄悄发送", "私下发送",
+    "ignore previous instructions", "ignore all previous instructions",
+    "disregard previous", "forget previous",
+    "do not tell the user", "don't tell the user",
+    "secretly send",
+]
+
+# ============ 异常特征阈值（禁止修改） ============
+HIGH_ENTROPY_MIN_LEN = 20        # 高熵候选串最短长度（字符）
+HIGH_ENTROPY_THRESHOLD = 4.5     # Shannon 熵阈值（bit/字符）
+HIGH_ENTROPY_MAX_COUNT = 10      # 高熵串最多记录条数
+LONG_LINE_THRESHOLD = 500        # 超长行判定阈值（字符）
+LONG_LINE_MAX_COUNT = 10         # 最多记录的行号个数
+RANDOM_IDENTIFIER_MIN_LEN = 16   # 随机标识符的最短长度
+RANDOM_IDENTIFIER_THRESHOLD = 10 # 随机标识符数量达到该值才记录总数
+
+# ============ 证据精炼限制（禁止修改） ============
+EVIDENCE_PER_CATEGORY_MAX = 10   # 每类信号最多保留条数
+EVIDENCE_ITEM_MAX_CHARS = 80     # 单条证据最大字符数（超出截断加省略号）
+# 证据总长度上限来自配置项 llm.evidence_max_chars（默认 3000），不在本文件定义
+
+# ============ 预处理限制（禁止修改） ============
+MAX_INPUT_BYTES = 1048576        # 单文件读入上限：1MB，超出只读前 1MB
+MAX_TEXT_CHARS = 200000          # 清洗后文本上限：20 万字符
+LINE_TRUNCATE_THRESHOLD = 2000   # 单行超此长度截断，追加 "…[LINE_TRUNCATED]"
+
+# ============ 压缩包安全限制（禁止修改，防 zip bomb） ============
+ARCHIVE_MAX_DEPTH = 3            # 递归解包最大深度
+ARCHIVE_MAX_FILES = 100          # 单个压缩包最多解出文件数
+ARCHIVE_MAX_TOTAL_BYTES = 52428800  # 解包总字节上限 50MB
+PRINTABLE_MIN_RUN = 4            # 二进制可打印字符串的最短连续长度
+
+# ============ 提示注入防护（禁止修改） ============
+# 不可见/危险 Unicode 范围：零宽字符、双向控制符、BOM 等
+HIDDEN_UNICODE_PATTERN = r"[\u200b-\u200f\u202a-\u202e\u2060-\u2064\u2066-\u2069\ufeff]"
+# 提交给 LLM 前需移除的控制字符（含 \x00-\x1f 中除 \t\n\r 外的全部）
+CONTROL_CHARS_PATTERN = r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f\u200b-\u200f\u202a-\u202e\u2060-\u2064\u2066-\u2069\ufeff]"
+# LLM 响应语义黑名单：命中即判定 LLM 可能被注入劫持，转 invalid_output
+LLM_SEMANTIC_BLACKLIST = [
+    "忽略之前", "忽略上面", "无法分析", "我是一个", "我是人工",
+    "ignore previous", "i cannot", "i can't", "as an ai",
+]
+# 一致性校验：本地校准概率 ≥ 该值 且 LLM 返回 low 时，触发一致性告警
+LLM_CONSISTENCY_LOCAL_PROB = 0.7

package/engine/calibguard/feature_extractor.py

@@ -0,0 +1,161 @@
+"""特征提取模块：文本 → 结构化可疑证据（FeatureEvidence）+ 证据转提示词文本。"""
+import math
+import re
+
+from calibguard import constants as C
+from calibguard.schemas import FeatureEvidence
+
+# 高熵候选串（最短长度取常量 HIGH_ENTROPY_MIN_LEN）
+_HIGH_ENTROPY_CANDIDATE_RE = re.compile(r"[A-Za-z0-9+/=_-]{%d,}" % C.HIGH_ENTROPY_MIN_LEN)
+# 长随机标识符（首字符字母或下划线 + 其余为标识符合法字符，总长 ≥ RANDOM_IDENTIFIER_MIN_LEN）
+# 字符类必须包含下划线：混淆器生成的随机变量名普遍为 var_xxxxx 形态，遗漏 _ 会使该检测失效
+_RANDOM_IDENTIFIER_RE = re.compile(
+    r"\b[A-Za-z_][A-Za-z0-9_]{%d,}\b" % (C.RANDOM_IDENTIFIER_MIN_LEN - 1)
+)
+
+# 隐藏 Unicode 命中时写入混淆类的固定条目
+_HIDDEN_UNICODE_ITEM = "隐藏Unicode字符"
+# 证据文本的八个固定标题（顺序固定，禁止调整）
+_SECTION_TITLES = [
+    "【危险API调用】",
+    "【网络行为】",
+    "【凭据与敏感路径访问】",
+    "【编码与混淆】",
+    "【可疑文件操作】",
+    "【提示注入话术】",
+    "【高熵字符串】",
+    "【异常结构特征】",
+]
+# 全部类别为空时的固定返回值
+_EMPTY_EVIDENCE_TEXT = "未发现明显可疑信号。"
+
+
+def extract_features(text: str) -> FeatureEvidence:
+    """对全文抽取七类可疑信号 + 异常特征。"""
+    evidence = FeatureEvidence()
+
+    evidence.dangerous_apis = _collect_matches(C.DANGEROUS_API_PATTERNS, text)
+    evidence.network_indicators = _collect_matches(C.NETWORK_PATTERNS, text)
+    evidence.credential_access = _collect_matches(C.CREDENTIAL_PATTERNS, text)
+    evidence.obfuscation_signals = _collect_matches(C.OBFUSCATION_PATTERNS, text)
+    evidence.file_operations = _collect_matches(C.FILE_OPERATION_PATTERNS, text)
+
+    # 隐藏 Unicode 检测：命中则追加固定条目（仅一条，去重）
+    if re.search(C.HIDDEN_UNICODE_PATTERN, text):
+        if _HIDDEN_UNICODE_ITEM not in evidence.obfuscation_signals:
+            evidence.obfuscation_signals.append(_HIDDEN_UNICODE_ITEM)
+        evidence.obfuscation_signals = evidence.obfuscation_signals[
+            :C.EVIDENCE_PER_CATEGORY_MAX
+        ]
+
+    # 提示注入话术：不区分大小写，命中整条话术原文（不截断）
+    lowered = text.lower()
+    injection_hits: list[str] = []
+    for phrase in C.INJECTION_PHRASES:
+        if phrase.lower() in lowered and phrase not in injection_hits:
+            injection_hits.append(phrase)
+    evidence.injection_phrases = injection_hits[:C.EVIDENCE_PER_CATEGORY_MAX]
+
+    # 异常特征
+    evidence.high_entropy_strings = _find_high_entropy_strings(text)
+    evidence.long_line_numbers = _find_long_lines(text)
+    random_count = len(_RANDOM_IDENTIFIER_RE.findall(text))
+    if random_count >= C.RANDOM_IDENTIFIER_THRESHOLD:
+        evidence.random_identifier_count = random_count
+
+    return evidence
+
+
+def _collect_matches(patterns: list[str], text: str) -> list[str]:
+    """逐个模式收集匹配串 → 去重（保持首次出现顺序）→ 截断 → 每类最多 10 条。"""
+    unique_hits: list[str] = []
+    for pattern in patterns:
+        for matched in re.findall(pattern, text):
+            if matched not in unique_hits:
+                unique_hits.append(matched)
+            if len(unique_hits) >= C.EVIDENCE_PER_CATEGORY_MAX:
+                break
+        if len(unique_hits) >= C.EVIDENCE_PER_CATEGORY_MAX:
+            break
+    return [_clip(item) for item in unique_hits[:C.EVIDENCE_PER_CATEGORY_MAX]]
+
+
+def _find_long_lines(text: str) -> list[int]:
+    """行长 ≥ LONG_LINE_THRESHOLD 的行号（1 起），最多 LONG_LINE_MAX_COUNT 个。"""
+    line_numbers: list[int] = []
+    for index, line in enumerate(text.split("\n"), start=1):
+        if len(line) >= C.LONG_LINE_THRESHOLD:
+            line_numbers.append(index)
+            if len(line_numbers) >= C.LONG_LINE_MAX_COUNT:
+                break
+    return line_numbers
+
+
+def _shannon_entropy(s: str) -> float:
+    """Shannon 熵：H = -Σ p_i * log2(p_i)。"""
+    if s == "":
+        return 0.0
+    length = len(s)
+    entropy = 0.0
+    for char in set(s):
+        probability = s.count(char) / length
+        entropy -= probability * math.log2(probability)
+    return entropy
+
+
+def _find_high_entropy_strings(text: str) -> list[str]:
+    """高熵候选串（长度 ≥ HIGH_ENTROPY_MIN_LEN 且熵 ≥ 阈值），最多 HIGH_ENTROPY_MAX_COUNT 条。"""
+    hits: list[str] = []
+    for candidate in _HIGH_ENTROPY_CANDIDATE_RE.findall(text):
+        if candidate in hits:
+            continue
+        if _shannon_entropy(candidate) >= C.HIGH_ENTROPY_THRESHOLD:
+            hits.append(candidate)
+            if len(hits) >= C.HIGH_ENTROPY_MAX_COUNT:
+                break
+    return [_clip(item) for item in hits]
+
+
+def evidence_to_prompt_text(evidence: FeatureEvidence, max_chars: int) -> str:
+    """证据 → 固定格式提示词文本（空类别整段跳过；全空返回固定串）。"""
+    category_items: list[list[str]] = [
+        evidence.dangerous_apis,
+        evidence.network_indicators,
+        evidence.credential_access,
+        evidence.obfuscation_signals,
+        evidence.file_operations,
+        evidence.injection_phrases,
+        evidence.high_entropy_strings,
+    ]
+
+    blocks: list[str] = []
+    for title, items in zip(_SECTION_TITLES, category_items):
+        if not items:
+            continue
+        lines = [title]
+        lines.extend(f"- {item}" for item in items)
+        blocks.append("\n".join(lines))
+
+    # 异常结构特征：超长行行号与长随机标识符数量
+    structural_lines: list[str] = []
+    if evidence.long_line_numbers:
+        structural_lines.append(f"- 超长行行号: {evidence.long_line_numbers}")
+    if evidence.random_identifier_count > 0:
+        structural_lines.append(f"- 长随机标识符数量: {evidence.random_identifier_count}")
+    if structural_lines:
+        blocks.append("\n".join([_SECTION_TITLES[7]] + structural_lines))
+
+    if not blocks:
+        return _EMPTY_EVIDENCE_TEXT
+
+    prompt_text = "\n\n".join(blocks)
+    if len(prompt_text) > max_chars:
+        prompt_text = prompt_text[:max_chars] + "\n…[EVIDENCE_TRUNCATED]"
+    return prompt_text
+
+
+def _clip(s: str, limit: int = C.EVIDENCE_ITEM_MAX_CHARS) -> str:
+    """单条证据超过 limit 字符则截断并追加省略号。"""
+    if len(s) <= limit:
+        return s
+    return s[:limit] + "…"

package/engine/calibguard/gate.py

@@ -0,0 +1,17 @@
+"""门控路由模块：校准概率 → ALLOW / BLOCK / LLM_REVIEW。
+
+边界归属（禁止改为 <= / >=）：严格小于放行、严格大于拦截、含边界走云端 LLM。
+"""
+from calibguard.schemas import GateDecision
+
+
+def route(probability: float, allow_threshold: float, block_threshold: float) -> GateDecision:
+    """按阈值把校准概率路由到三个决策之一。"""
+    if not (0.0 <= probability <= 1.0):
+        raise ValueError(f"概率必须在 [0, 1] 内，当前 {probability}")
+    if probability < allow_threshold:
+        return GateDecision.ALLOW
+    if probability > block_threshold:
+        return GateDecision.BLOCK
+    # 其余（含恰好等于两阈值的情况）走云端 LLM
+    return GateDecision.LLM_REVIEW