argo-search 1.0.1 → 2.9.7

package/scripts/query_enhance.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""query_enhance.py — 首轮查询增强（无 LLM）：归一化 + 拆词变体 + 复杂度门控
+
+目标：让「简单问题首轮就命中、复杂问题才走多轮」，避免简单问题被拖成多轮
+浪费 token。纯规则，零外部依赖，中英双语。
+
+设计（保持一致 Adaptive-RAG 的复杂度分流 + Algolia 的 query expansion/relaxation）：
+  1. normalize_query      词形规范化：全角→半角、拆斜杠、压多余空格。
+                           治「型号/日期/分隔符检索命中难」，如 LongCat-2.0/1.6 万亿。
+  2. retrieval_variants   生成有序检索变体（归一化主词 + 拆连字符型号词 + 概念/同义词）。
+                           供「首轮多路召回」用（低复杂度时用少数变体并行补齐召回）。
+  3. complexity_gate      复杂度门控：把查询分为 low / medium / high。
+                           low  → 单轮多路召回即可，不放行多轮 recovery；
+                           high → 允许多轮/全变体（复杂、多跳、对比）。
+
+复杂度信号来源：query_understanding 的 intents/confidence/multi_intent_splits + 长度 +
+多跳词（对比/因果/区别/为什么/vs 等）。与 query_understanding 互不相干，仅做启发式分级。
+"""
+
+from __future__ import annotations
+
+import re
+
+# ── 词形规范化 ──────────────────────────────────────────────────────────────
+
+# 全角标点/空白 → 半角：中文输入常见，易导致精确源（版本号/路径/符号）漏检
+_FULL_TO_HALF = str.maketrans(
+    "，。！？：；（）【】《》“”‘’％＋－",
+    ",.!?:;()[]<>\"\"''%+-",
+)
+# 全角字母数字/符号 → 半角：ＡＢＣ１２３ 常见于粘贴文本，与标点同批处理
+_FULL_ALNUM = str.maketrans(
+    "０１２３４５６７８９ＡＢＣＤＥＦＧＨＩＪＫＬＭＮＯＰＱＲＳＴＵＶＷＸＹＺ"
+    "ａｂｃｄｅｆｇｈｉｊｋｌｍｎｏｐｑｒｓｔｕｖｗｘｙｚ￥～",
+    "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+    "abcdefghijklmnopqrstuvwxyz¥~",
+)
+_FULL_SPACE = str.maketrans("\u3000", " ")
+
+# 只拆「版本/模型号」的斜杠（如 LongCat-2.0/1.6 万亿 → LongCat-2.0 1.6 万亿）。
+# 斜杠前必须是「点号分隔的数字」形态（2.0/），据此精准命中版本号，
+# 不碰日期(2023/2024)、分数(1/2)、URL(https://…)、路径、比例、颜色选项等保留
+# 斜杠语义的查询——全量拆斜杠会把 `https://example.com/a/b` 毁成
+# `https: example.com a b`、把「1/2 怎么算」毁成「1 2 怎么算」。
+_MODEL_SLASH = re.compile(r"(?<=[0-9A-Za-z]\.[0-9])\/")
+
+
+def normalize_query(query: str) -> str:
+    """词形规范化：全角→半角（标点+字母数字）、按「点号版本」拆斜杠、压缩多余空格。
+    保留连字符（避免 GPT-5 拆散）；仅拆点号版本斜杠，不破坏日期/分数/URL/路径。"""
+    if not query or not isinstance(query, str):
+        return query
+    q = query.translate(_FULL_TO_HALF).translate(_FULL_ALNUM).translate(_FULL_SPACE)
+    q = _MODEL_SLASH.sub(" ", q)
+    q = re.sub(r"\s+", " ", q).strip()
+    return q
+
+
+# ── 检索变体（首轮多路召回用）────────────────────────────────────────────────
+
+def retrieval_variants(query: str, max_n: int = 3) -> list[str]:
+    """返回有序检索变体：归一化主词 + 拆连字符型号词 + 概念/同义词。
+
+    max_n 默认 3（低复杂度只取少量，控制成本）。去重、保持稳定顺序。
+    """
+    if not query or not isinstance(query, str):
+        return []
+    base = normalize_query(query)
+    out = [base]
+
+    # 拆连字符型号：LongCat-2.0 → LongCat 2.0（仅字母后接数字，避免拆分普通词）
+    split_hyphen = re.sub(r"(?<=[A-Za-z])\-(?=[0-9])", " ", base)
+    split_hyphen = re.sub(r"\s+", " ", split_hyphen).strip()
+    if split_hyphen and split_hyphen != base:
+        out.append(split_hyphen)
+
+    # 概念/同义变体（复用 query_variants 的概念/缩写表，只取首个替代）
+    concept = _concept_variant(base)
+    if concept and concept not in out:
+        out.append(concept)
+
+    seen = set()
+    uniq = []
+    for v in out:
+        k = v.strip().lower()
+        if k not in seen:
+            seen.add(k)
+            uniq.append(v)
+    return uniq[:max_n]
+
+
+def _concept_variant(base: str) -> str | None:
+    """把命中的概念/缩写替换为首个等价表述；无命中返回 None。"""
+    try:
+        from query_variants import CONCEPT_MAP, ACRONYM_MAP
+    except ImportError:
+        return None
+    ql = base.lower()
+    for word, alts in CONCEPT_MAP.items():
+        if word in ql and alts:
+            target = alts[0]
+            if target.lower() == ql:
+                continue
+            return re.sub(r"\b" + re.escape(word) + r"\b", target, base, count=1,
+                          flags=re.IGNORECASE)
+    for word, full in ACRONYM_MAP.items():
+        if word in ql:
+            return re.sub(r"\b" + re.escape(word) + r"\b", full, base, count=1,
+                          flags=re.IGNORECASE)
+    return None
+
+
+# ── 复杂度门控 ──────────────────────────────────────────────────────────────
+
+# 多跳 / 对比 / 归因信号：这类问题往往需要多轮或全变体位
+_MULTI_HOP = re.compile(
+    r"对比|比较|区别|差异|为什么|导致|原因|vs|versus|between|compared|"
+    r"impact\s+of|effect\s+of|influence|relationship|影响|关系|关联|如何影响|"
+    r"列举|有哪些|总结|回顾|evolution|timeline|历程|归因|走势|趋势",
+    re.I,
+)
+
+
+def complexity_gate(query: str, qu=None) -> str:
+    """返回查询复杂度：low / medium / high。
+
+    low  → 短、单意图、无多跳词、置信度较高 → 单轮多路召回即可，不放行多轮 recovery。
+    high → 多跳/对比词 或 多意图 或 较长 → 允许多轮/全变体。
+    medium → 其余。
+    """
+    if not query or not isinstance(query, str):
+        return "low"
+    ql = query.strip()
+    length = len(ql)
+
+    multi_hop = bool(_MULTI_HOP.search(ql))
+
+    intent_cnt = 0
+    conf = 0.0
+    multi_splits = 0
+    if qu is not None:
+        intent_cnt = len(getattr(qu, "intents", []) or [])
+        conf = float(getattr(qu, "confidence", 0.0) or 0.0)
+        multi_splits = len(getattr(qu, "multi_intent_splits", []) or [])
+
+    if multi_hop or intent_cnt >= 2 or multi_splits >= 2 or length > 60:
+        return "high"
+    if length <= 24 and intent_cnt <= 1 and not multi_hop:
+        return "low"
+    if conf >= 0.6 and length <= 30 and not multi_hop:
+        return "low"
+    return "medium"
+
+
+def low_complexity(query: str, qu=None) -> bool:
+    """是否为「首轮即可解决」的低复杂度查询。"""
+    return complexity_gate(query, qu) == "low"

package/scripts/query_operators.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+"""query_operators.py — 查询级操作符契约层（2026-10-17，借鉴 DeepSeek Search）。
+
+## 解决什么问题
+
+Google 风格查询里的操作符（site:/-site:/-词/-"短语"/lang:/after:/before:）
+此前散落四处：引号短语走 phrase_filter、-词走 query_understanding 的否定、
+after/before 只认 CLI flag、lang 靠自动检测、site: 更是只以「域正则触发词」
+的形态存在——结果是一条 `DeepSeek site:github.com` 把路由锁死进 code_search，
+而引擎侧拿到的还是含字面 site: 的脏查询（2026-10-17 实测：github 引擎返回
+GitHub Pages 通用页）。同一能力五种形态、没有一处是契约。
+
+## 本层的契约（对照 DeepSeek Search 的透传语义）
+
+Argo 侧选择**解析而非透传**：DeepSeek 把操作符原样甩给上游搜索服务，Argo 的
+上游是 260 个异构引擎（多数不认识这些语法），原样透传=把字面 site: 喂给
+不认识它的引擎。故本层抽取为结构化 operators，路由/缓存/查询理解只认
+clean_query（剥掉指令后的意图核心），operators 走三个既有消费点：
+
+  - langs     → route 的语言偏好覆盖（替代自动检测的选择）
+  - after/before → 时间窗归一化（--since/--until 的同一判据；CLI flag 优先）
+  - exclude_terms → query_understanding 的排除项汇合（融合后过滤）
+  - sites/exclude_sites/phrases → v1 只记录可观测（results 的 limitations 提示
+    未下推），不污染检索词；按引擎能力下推是后续增量（extra_params 的查询级
+    覆盖机制已就位）
+
+## 语法（与 DeepSeek 对齐的子集）
+
+  site:github.com / -site:x.com   站点限定/排除（多个空格分隔按 OR 语义记录）
+  -词 / -"短语"                   排除关键词/短语
+  "短语"                          精确短语（保留在 clean_query——它是意图
+                                  本体不是指令，phrase_filter 照常提取）
+  lang:zh,en                      语言限定（逗号分隔）
+  after:2026 / after:2026-01-01   发布时间下界
+  before:2026 / before:2026-06-01 发布时间上界
+
+纯函数、零依赖、无全局状态。用法：
+  from query_operators import parse_query_operators
+  clean, ops = parse_query_operators('DeepSeek site:github.com lang:zh after:2026')
+  # clean == 'DeepSeek'；ops['sites'] == ['github.com']；ops['langs'] == ['zh']
+"""
+from __future__ import annotations
+
+import re
+import urllib.parse
+from typing import Any
+
+# site: 的值：域名形态（字母数字点连字符），到空白/引号/结尾收边
+# site: 值；尾部 OR 连接词仅在「后面还跟 site:」时消费（DeepSeek 文档的
+# 多站点 OR 语义），否则查询里的裸 OR 原样保留。
+_SITE_RE = re.compile(r"(?<![\w-])(-?)site:([a-zA-Z0-9.\-]+)(?:\s+OR(?=\s+site:))?")
+# lang: 的值：逗号分隔的语言代码
+_LANG_RE = re.compile(r"(?<![\w-])lang:([a-zA-Z,]+)")
+# after:/before: 的值：年份或 YYYY-MM-DD
+_DATE_RE = re.compile(r"(?<![\w-])(after|before):(\d{4}(?:-\d{2}-\d{2})?)")
+# 排除短语：-"..."（先于单词排除处理）
+_EXCL_PHRASE_RE = re.compile(r'-\s*"([^"]+)"')
+# 排除单词：-词（字母数字或 CJK 串；连字符后紧跟非空白非连字符）
+_EXCL_TERM_RE = re.compile(r"(?<![\w\"])-(\S+)")
+
+
+def parse_query_operators(query: str) -> tuple[str, dict[str, Any]]:
+    """抽取查询操作符 → (clean_query, operators)。
+
+    clean_query 剥掉全部指令（site/-site/-词/-"短语"/lang/after/before），
+    保留精确短语 "..."（它是意图本体）。operators 字段：
+      sites / exclude_sites: list[str]
+      exclude_terms: list[str]（-词 与 -"短语" 合并，供排除过滤）
+      langs: list[str]
+      after / before: str | None
+      dropped: list[str]（原操作符文本，可观测/limitations 提示用）
+    """
+    if not query or not isinstance(query, str):
+        return (query or ""), _empty_ops()
+
+    ops = _empty_ops()
+    text = query
+
+    def _take(match: re.Match) -> str:
+        ops["dropped"].append(match.group(0).strip())
+        return " "
+
+    # 1) 站点限定/排除
+    def _site_sub(m: re.Match) -> str:
+        (ops["exclude_sites"] if m.group(1) else ops["sites"]).append(m.group(2))
+        return _take(m)
+    text = _SITE_RE.sub(_site_sub, text)
+
+    # 2) 语言
+    def _lang_sub(m: re.Match) -> str:
+        langs = [x.strip() for x in m.group(1).split(",") if x.strip()]
+        ops["langs"].extend(langs)
+        return _take(m)
+    text = _LANG_RE.sub(_lang_sub, text)
+
+    # 3) 时间窗
+    def _date_sub(m: re.Match) -> str:
+        ops[m.group(1)] = m.group(2)
+        return _take(m)
+    text = _DATE_RE.sub(_date_sub, text)
+
+    # 4) 排除短语（先于 -词，避免 " 被当词的一部分）
+    def _excl_phrase_sub(m: re.Match) -> str:
+        ops["exclude_terms"].append(m.group(1).strip())
+        return _take(m)
+    text = _EXCL_PHRASE_RE.sub(_excl_phrase_sub, text)
+
+    # 5) 排除单词
+    def _excl_term_sub(m: re.Match) -> str:
+        term = m.group(1).strip()
+        if term:
+            ops["exclude_terms"].append(term)
+        return _take(m)
+    text = _EXCL_TERM_RE.sub(_excl_term_sub, text)
+
+    clean = re.sub(r"\s+", " ", text).strip()
+    return clean, ops
+
+
+def _host_matches(host: str, site: str) -> bool:
+    """host 是否属于 site（含子域）。site 为空或非法时返回 False。"""
+    host = (host or "").lower().strip(".")
+    site = (site or "").lower().strip().strip(".")
+    if not host or not site:
+        return False
+    return host == site or host.endswith("." + site)
+
+
+def operator_cache_suffix(operators: dict[str, Any] | None) -> str:
+    """把影响结果集的操作符拼成缓存键后缀；无操作符返回空串。
+
+    缓存键的主体是剥掉指令后的 clean_query，若不把指令本身并入键，
+    `python asyncio` 与 `python asyncio -site:realpython.com` 会命中同一条
+    缓存：要么把受限结果回给无约束查询，要么相反——后者更隐蔽，
+    用户写了约束却拿到未过滤的结果。langs 同理（它改变路由与引擎选择）。
+    after/before 已归一化为 since/until，由调用方单独并入，不在这重复。
+    """
+    ops = operators or {}
+    parts: list[str] = []
+    for key, tag in (("sites", "site"), ("exclude_sites", "xsite"),
+                     ("exclude_terms", "not"), ("langs", "lang")):
+        vals = [str(v).strip() for v in (ops.get(key) or [])
+                if isinstance(v, (str, int, float)) and str(v).strip()]
+        if vals:
+            parts.append(f"{tag}={','.join(vals)}")
+    return "".join(f"|{p}" for p in parts)
+
+
+def filter_results_by_sites(
+    results: list[dict[str, Any]],
+    sites: list[str] | None,
+    exclude_sites: list[str] | None = None,
+) -> tuple[list[dict[str, Any]], int]:
+    """按 site:/-site: 后置过滤结果，返回 (保留项, 剔除数)。
+
+    为什么是后置过滤而不是下推检索词：argo 的上游是 260 个异构引擎，多数
+    不认识 site: 语法；把它留在检索串里只会降低召回。解析层已经把它从
+    clean_query 剥掉，若不再执行就等于「宣称支持但静默忽略」——实测
+    `DeepSeek site:github.com` 会返回 models.dev 的模型页（2026-10-17）。
+
+    子域算匹配：site:github.com 命中 gist.github.com。多个 site 之间是 OR。
+    无 url 的模态卡不参与站点判定（不因无法判定而被误删）。
+    """
+    include = [s for s in (sites or []) if isinstance(s, str) and s.strip()]
+    exclude = [s for s in (exclude_sites or []) if isinstance(s, str) and s.strip()]
+    if not include and not exclude:
+        return results, 0
+    kept: list[dict[str, Any]] = []
+    dropped = 0
+    for r in results:
+        if not isinstance(r, dict):
+            kept.append(r)
+            continue
+        url = str(r.get("url") or "")
+        if not url:
+            kept.append(r)
+            continue
+        try:
+            host = urllib.parse.urlsplit(url).hostname or ""
+        except ValueError:
+            host = ""
+        if include and not any(_host_matches(host, s) for s in include):
+            dropped += 1
+            continue
+        if exclude and any(_host_matches(host, s) for s in exclude):
+            dropped += 1
+            continue
+        kept.append(r)
+    return kept, dropped
+
+
+def _empty_ops() -> dict[str, Any]:
+    return {
+        "sites": [], "exclude_sites": [], "exclude_terms": [],
+        "langs": [], "after": None, "before": None, "dropped": [],
+    }

package/scripts/query_rewriter.py

@@ -28,9 +28,10 @@ REWRITE_MAP: dict[tuple[str, str], str] = {
     # 科技公司/产品
     ("苹果", "finance"): "Apple 公司 AAPL 股票行情",
     ("苹果", "tech"): "Apple 公司 iPhone Mac iOS",
-    ("Python", "tech"): "Python 编程语言 pip 库 框架",
+    # 改写词不得触发 package_search 等域规则（禁止 pip/npm/pypi/cargo 等包管理词）
+    ("Python", "tech"): "Python 编程语言 异步 开发",
     ("Java", "tech"): "Java 编程语言 JDK Spring JVM",
-    ("Rust", "tech"): "Rust 编程语言 cargo crate 所有权",
+    ("Rust", "tech"): "Rust 编程语言 所有权 并发",
     ("小米", "tech"): "小米科技 手机 MIUI HyperOS",
     ("小米", "auto"): "小米汽车 SU7",
     ("华为", "tech"): "华为技术 鸿蒙 5G 芯片 Mate",
@@ -125,13 +126,56 @@ def rewrite_query(query: str, min_confidence: float = 0.7) -> dict[str, Any]:
     # 延迟导入避免循环依赖
     from clarify import AMBIGUOUS_TERMS, BRAND_COLLISIONS
 
+    # 长查询自带完整上下文，扩词只会引入噪声：research 子查询含「GPT-4o」时
+    # 曾被扩成「…大语言模型 OpenAI ChatGPT GPT-4 technical overview…」，
+    # 整条检索串从照片趋势题变成模型架构题。短查询才需要补召回信号。
+    if len(query) > 60:
+        return {
+            "original": query,
+            "rewritten": None,
+            "confidence": 0.0,
+            "reason": "长查询跳过改写（自带完整上下文）",
+            "type": "direct",
+        }
+
+    # 非中文查询跳过策略1（REWRITE_MAP 中文领域扩词）：领域词全是中文
+    # （「编程语言 异步 开发」），拼进俄文/日文/泰文查询后检索串变成混合语，
+    # 实测俄文查询被污染成 9/9 中文结果（原文 0 中文）。
+    # 策略2（英文术语拆分）保留：追加的是查询自带的拉丁术语，无语言污染，
+    # 是非中文查询补召回信号的正途。
+    # 日语特殊：日文本身混用汉字（「比較」），不能靠汉字正则放行——
+    # detect_language 判 ja/ko 时直接按非中文处理。
+    try:
+        from lang_detect import detect_language as _detect_lang
+        _lang = _detect_lang(query)
+        _is_zh = _lang in ("zh", "mixed") or (
+            _lang not in ("ja", "ko") and re.search(r"[\u4e00-\u9fff]", query))
+        _skip_zh_expand = not _is_zh
+    except ImportError:
+        _skip_zh_expand = False
+
+    # P0-001：先做查询理解，用 clean_query（去否定片段）做消歧，
+    # 避免否定实体（如「除了百度」的百度）污染消歧信号。
+    understanding = None
+    disambig_source = query
+    try:
+        from query_understanding import _understand_cached as understand
+        understanding = understand(query)
+        if understanding.clean_query:
+            disambig_source = understanding.clean_query
+    except ImportError:
+        pass  # query_understanding 不可用，退回原查询
+    except Exception:
+        pass  # query_understanding 不可用或返回异常：退回原查询，不阻断改写
+
     rewritten_parts: list[str] = []
     reasons: list[str] = []
     total_confidence = 0.0
     match_count = 0
 
     # ── 策略 1：歧义消解改写 ──
-    query_lower = query.lower()
+    # 用 clean_query（去否定片段）做歧义定位，避免被排除实体干扰
+    query_lower = disambig_source.lower()
     for term, info in AMBIGUOUS_TERMS.items():
         # 在查询中定位歧义词（大小写不敏感）
         term_lower = term.lower()
@@ -140,6 +184,12 @@ def rewrite_query(query: str, min_confidence: float = 0.7) -> dict[str, Any]:
             and re.search(r"\b" + re.escape(term) + r"\b", query, re.I)
         ):
             continue
+        # 型号后缀守卫：词后跟数字（GPT-4o / GPT5 / iPhone 15）是具体型号
+        # 提及而非品牌歧义词，展开只会把查询推向无关领域
+        if term.isascii() and re.search(
+            r"\b" + re.escape(term) + r"[-.\s]?\d", query, re.I
+        ):
+            continue
 
         best_domain = None
         best_conf = 0.0
@@ -198,14 +248,23 @@ def rewrite_query(query: str, min_confidence: float = 0.7) -> dict[str, Any]:
         if best_domain and best_conf >= min_confidence:
             rewrite_key = (term, best_domain)
             append = REWRITE_MAP.get(rewrite_key)
-            if append:
+            if append and not _skip_zh_expand:
                 rewritten_parts.append(append)
                 reasons.append(f"「{term}」→ {best_domain} 领域")
                 total_confidence += best_conf
                 match_count += 1
 
     # ── 策略 2：混合语言拆分 ──
-    if _has_chinese(query) and _has_english(query):
+    # 多语种（v2.7）：主语言非英文（日/韩/西里尔/泰/阿等）且含拉丁术语时
+    # 也做混合拆分，抽出英文技术词补检索；中文+英文逻辑保持原样。
+    lang = "en"
+    try:
+        from lang_detect import detect_language
+        lang = detect_language(query)
+    except ImportError:
+        pass
+    mixed_latin = _has_chinese(query) or lang not in ("en", "latin")
+    if mixed_latin and _has_english(query):
         eng_terms = _extract_english_terms(query)
         technical = any(
             t
@@ -214,7 +273,7 @@ def rewrite_query(query: str, min_confidence: float = 0.7) -> dict[str, Any]:
                 "npm", "pip", "git", "ssh", "rest", "graphql", "grpc",
                 "react", "vue", "node", "python", "java", "rust", "go",
                 "docker", "kubernetes", "linux", "nginx", "redis",
-                "async", "await", "thread", "process", "async",
+                "async", "await", "thread", "process",
             }
             for t in eng_terms
         )
@@ -227,6 +286,8 @@ def rewrite_query(query: str, min_confidence: float = 0.7) -> dict[str, Any]:
             match_count += 1
 
     # ── 构建结果 ──
+    understanding_dict = understanding.to_dict() if understanding is not None else None
+
     if not rewritten_parts:
         return {
             "original": query,
@@ -234,10 +295,31 @@ def rewrite_query(query: str, min_confidence: float = 0.7) -> dict[str, Any]:
             "confidence": 0.0,
             "reason": "无需改写",
             "type": "direct",
+            "understanding": understanding_dict,
         }
 
     avg_confidence = round(total_confidence / match_count, 2)
-    rewritten = query + " " + " ".join(rewritten_parts)
+    # 追加词与原查询词级去重：消歧/拆分追加只补「新增信息」。
+    # 此前 "Python async" + "Python 编程语言 异步 开发" 直接拼接成
+    # "Python async Python 编程语言 异步 开发"，重复词污染检索串，
+    # 且混入子查询分解后产生 "Python async Python" 半改写残留。
+    append_str = _dedupe_append_words(query, rewritten_parts)
+    if not append_str:
+        # 去重后全空：中文查询的混合拆分场景（日文查询 + 原文已有的英文术语）
+        # 仍保留追加，旧行为不改写会丢失语言补充信号；
+        # 非中文查询的追加全为原文术语时，重复拼接是纯噪声
+        # （实测俄文查询末尾重复 "python asyncio" 无增益），直接不改写。
+        if _skip_zh_expand:
+            return {
+                "original": query,
+                "rewritten": None,
+                "confidence": 0.0,
+                "reason": "非中文查询追加词与原文重复，跳过改写",
+                "type": "direct",
+                "understanding": understanding_dict,
+            }
+        append_str = " ".join(rewritten_parts)
+    rewritten = query + " " + append_str
 
     return {
         "original": query,
@@ -245,9 +327,36 @@ def rewrite_query(query: str, min_confidence: float = 0.7) -> dict[str, Any]:
         "confidence": avg_confidence,
         "reason": "；".join(reasons),
         "type": "disambiguate",
+        "understanding": understanding_dict,
     }
 
 
+def _dedupe_append_words(original: str, parts: list[str]) -> str:
+    """追加词与原查询词级去重：已出现在原文里的词不再追加。
+
+    例：original="Python async"，parts=["Python 编程语言 异步 开发"]
+      → Python 已在原文 → 保留 "编程语言 异步 开发"。
+    以词块为单位（空格分词），中文词块与英文词均按字面比较。
+    """
+    import re as _re
+    if not parts:
+        return ""
+    q_tokens = set(
+        t.lower()
+        for t in _re.findall(r"[\u4e00-\u9fff]+|[a-zA-Z0-9]+", original)
+    )
+    kept: list[str] = []
+    for part in parts:
+        fresh = [
+            w for w in part.split()
+            if _re.sub(r"[^a-zA-Z0-9\u4e00-\u9fff]", "", w).lower()
+            not in q_tokens
+        ]
+        if fresh:
+            kept.append(" ".join(fresh))
+    return " ".join(kept)
+
+
 # ── CLI 测试 ──────────────────────────────────────────────────────────────────
 
 if __name__ == "__main__":