语义搜索插件

.gitignore

@@ -16,6 +16,8 @@ client/src/.cache-loader/
 # --- 构建产物 ---
 client/dist/
 client/dist-github_pages/
+extension/dist/
+extension/config.js
 build/
 dist/
 *.egg-info/

backend/api/analyze_semantic.py

@@ -19,18 +19,34 @@ from backend.platform.access_log import get_client_ip
 from backend.api.analyze import QueueTimeoutError, ANALYSIS_TIMEOUT, LOCK_WAIT_TIMEOUT
 
 
-def _log_request(query, text, client_ip=None):
+def _log_request(query, text, client_ip=None, privacy_mode=False):
     from backend.platform.access_log import log_analyze_semantic_request
-    return log_analyze_semantic_request(query, text, client_ip)
+    return log_analyze_semantic_request(query, text, client_ip, privacy_mode)
 
 
 def _build_success_response(result, debug_info: bool = False):
-    """构建成功响应。debug_info=True 时包含 debug_info 对象（abbrev、topk_tokens、topk_probs）"""
+    """构建成功响应。debug_info=True 时包含 debug_info 对象（abbrev、topk_tokens、topk_probs）。
+    result 为 List 时（批量 full_match_degree_only），返回 {"success", "results": [...]}。
+    带 input_token_count：full_match_degree_only 时 token_attention 为空，门户 response 日志靠它打 tokens。
+    分析器必须产出该字段；缺则 KeyError，不静默填默认值。"""
+    if isinstance(result, list):
+        return {
+            "success": True,
+            "results": [
+                {
+                    "model": r["model"],
+                    "full_match_degree": r["full_match_degree"],
+                    "input_token_count": r["input_token_count"],
+                }
+                for r in result
+            ],
+        }
     resp = {
         "success": True,
         "model": result["model"],
         "token_attention": result["token_attention"],
         "full_match_degree": result["full_match_degree"],
+        "input_token_count": result["input_token_count"],
     }
     if debug_info and "debug_info" in result:
         resp["debug_info"] = result["debug_info"]
@@ -126,13 +142,19 @@ def _generate_semantic_events(
         from backend.platform.inference_response_log import log_analyze_semantic_response
         from backend.platform.model_routing import is_worker
 
-        if is_worker():
-            log_analyze_semantic_response(
-                request_id=request_id,
-                result=analysis_result,
-                elapsed=elapsed,
-                for_worker=True,
-            )
+        # 本地执行机打完整日志（含 wait/processing）；远程代理门户走 response_log_fn
+        if isinstance(analysis_result, dict):
+            log_result = analysis_result
+        else:
+            total_tokens = sum(r.get("input_token_count", 0) for r in analysis_result)
+            log_result = {"input_token_count": total_tokens}
+        log_analyze_semantic_response(
+            request_id=request_id,
+            result=log_result,
+            elapsed=elapsed,
+            wait_time=lock_wait_time,
+            for_worker=is_worker(),
+        )
         yield send_result_event(_build_success_response(analysis_result, debug_info))
     except Exception as e:
         import traceback
@@ -202,43 +224,67 @@ def analyze_semantic(semantic_request):
     分析原文 token 对 prompt 的关注度。
 
     Args:
-        semantic_request: 包含 query、text、stream（可选）、submode（可选）的字典
+        semantic_request: 包含 query、text、stream（可选）、submode（可选）的字典。
+            texts（可选，字符串数组）：批量 full_match_degree_only 预判性能测试用，
+            与 text 互斥，且必须搭配 full_match_degree_only=True。
+
+            性能结论（详见 backend/core/semantic_analyzer.py 的
+            _analyze_logits_gradient_batch）：
+            batching 对模型前向计算本身的加速有限（batch=4 约 1.5x，batch=8 约
+            1.6x），线上用客户端总耗时测出的更高加速比主要是摊薄了每次 HTTP
+            请求固定的网络/SSE 开销，并非计算变快；因此若追求性能，合并请求本身
+            比加大 batch 更有效，batch 也不宜设得过大。
 
     Returns:
         stream=True 时返回 SSE 响应；否则返回 (响应字典, 状态码) 元组
     """
     query = (semantic_request.get("query") or "")
     text = semantic_request.get("text") or ""
+    texts = semantic_request.get("texts")
     stream = semantic_request.get("stream", False)
     submode = (semantic_request.get("submode") or "").strip() or None
     debug_info = bool(semantic_request.get("debug_info", False))
     full_match_degree_only = bool(semantic_request.get("full_match_degree_only", False))
+    privacy_mode = bool(semantic_request.get("privacy_mode", False))
 
     if not query:
         return {"success": False, "message": "缺少 query 字段"}, 400
-    if not text:
-        return {"success": False, "message": "缺少 text 字段"}, 400
+
+    if texts is not None:
+        if not isinstance(texts, list) or not texts or not all(isinstance(t, str) and t for t in texts):
+            return {"success": False, "message": "texts 字段需为非空字符串数组"}, 400
+        if not full_match_degree_only:
+            return {"success": False, "message": "texts 数组批量模式仅支持 full_match_degree_only=True"}, 400
+        content = texts
+        log_text = f"[批量 x{len(texts)}] " + texts[0]
+    else:
+        if not text:
+            return {"success": False, "message": "缺少 text 字段"}, 400
+        content = text
+        log_text = text
 
     client_ip = get_client_ip()
     logged: dict = {"request_id": None}
 
     def log_fn():
-        logged["request_id"] = _log_request(query, text, client_ip)
+        logged["request_id"] = _log_request(query, log_text, client_ip, privacy_mode)
 
     def local_fn():
         rid = logged["request_id"]
         if stream:
             return _analyze_semantic_with_stream(
-                query, text, submode, debug_info, full_match_degree_only, client_ip, rid
+                query, content, submode, debug_info, full_match_degree_only, client_ip, rid
             )
         return _analyze_semantic_plain(
-            query, text, submode, debug_info, full_match_degree_only, client_ip, rid
+            query, content, submode, debug_info, full_match_degree_only, client_ip, rid
         )
 
     from backend.models.model_manager import ModelSlot
     from backend.platform.inference_ingress import ingress_inference
     from backend.platform.inference_response_log import make_analyze_semantic_response_logger
+    from backend.platform.model_routing import is_local
 
+    # 本地执行：handler 已打完整日志；仅远程代理时门户用 response_log_fn 打端到端
     return ingress_inference(
         slot=ModelSlot.INSTRUCT,
         api_path="/api/analyze-semantic",
@@ -247,5 +293,9 @@ def analyze_semantic(semantic_request):
         timeout=60.0,
         log_fn=log_fn,
         local_fn=local_fn,
-        response_log_fn=make_analyze_semantic_response_logger(logged),
+        response_log_fn=(
+            None
+            if is_local(ModelSlot.INSTRUCT)
+            else make_analyze_semantic_response_logger(logged)
+        ),
     )

backend/core/semantic_analyzer.py

@@ -34,13 +34,22 @@ def _get_logits_gradient_submode() -> str:
         return "fill_blank"
 
 
-def _truncate_text_by_tokens(tokenizer, text: str, max_tokens: int) -> str:
-    """将 text 截断至最多 max_tokens 个 token；超长时打印提示。"""
+def _truncate_text_by_tokens(tokenizer, text: str, max_tokens: int) -> tuple[str, int]:
+    """
+    将 text 截断至最多 max_tokens 个 token；超长时打印提示。
+    返回 (截断后文本, 实际 token 数)，token 数供调用方复用（日志等），避免重复分词。
+
+    已知问题：截断是静默的，响应里没有任何字段告知调用方发生过截断。前端按字节数切 chunk
+    （extension/config.js chunkBytes=800），与这里的 token 上限没有联动；数字/标点/代码等
+    token 密度高的内容，800 字节可能远超 max_tokens，导致相关度判断和 fill_blank 高亮只覆盖
+    截断后的前缀。后果是漏检（chunk 被判无关或部分内容不高亮），不是误报。调大 max_tokens
+    只能缓解、不能根治（数字等本就按字符/短片段单独分词，token 密度上限很高）。
+    """
     text_ids = tokenizer.encode(text, add_special_tokens=False)
     if len(text_ids) > max_tokens:
         print(f"⚠️  原文过长，已截断至前 {max_tokens} token")
-        return tokenizer.decode(text_ids[:max_tokens])
-    return text
+        return tokenizer.decode(text_ids[:max_tokens]), max_tokens
+    return text, len(text_ids)
 
 
 def _get_gradient_checkpointing() -> bool:
@@ -58,6 +67,37 @@ def _get_verbose() -> bool:
     return get_verbose()
 
 
+def _build_prompt_parts(submode: str, query: str) -> tuple:
+    """
+    按子模式（count / match_score已废弃 / fill_blank）构造 (instruction, generation_guide, neg_token)。
+    单条与批量前向共用，避免同一套子模式分叉在两处重复维护。
+
+    - instruction：拼在原文前的指令；文档前用 \\n\\n 分隔，避免 tokenizer 将首字符与空格合并导致 offset_mapping 计算错误
+    - generation_guide：chat template 只支持完整消息，生成引导词需在 apply_chat_template 之后追加
+    - neg_token：计算 full_match_degree（1 - P(neg_token)）用的「无关」token
+    """
+    if submode == "count":
+        return (
+            f"请问下面文字中有多少个词与查询主题（{query}）相关？文字内容：\n\n",
+            f"原文中与查询主题（{query}）相关的词的数量 = **",
+            "0",
+        )
+    if submode == "match_score":  # 已废弃
+        return (
+            f"请问下面文字与查询主题（{query}）的相关程度是多少？请回答0/1/2（2为最高相关）。文字内容：\n\n",
+            f"文章和查询主题（{query}）的相关程度（0-2）打分为：**",
+            "0",
+        )
+    if submode == "fill_blank":
+        return (
+            f"请问下面文字中哪个词与查询主题（{query}）最相关？如无相关词则回答“无”。文字内容：\n\n",
+            # “引号是特意为了防止模型生成引号
+            f"原文中与查询主题（{query}）最相关的一个词是：**“",
+            "无",
+        )
+    raise ValueError(f"未知子模式: {submode}")
+
+
 def _analyze_logits_gradient(
     query: str,
     text: str,
@@ -81,35 +121,16 @@ def _analyze_logits_gradient(
 
     if progress_callback:
         progress_callback(1, TOTAL_STEPS, "encoding", None)
-    # 根据submodule来决定不同的instruction
-    # 文档前用 \n\n 分隔，避免 tokenizer 将首字符与空格合并，导致 offset_mapping 计算错误
-    if submode == "count":
-        instruction = f"请问下面文字中有多少个词与查询主题（{query}）相关？文字内容：\n\n"
-    elif submode == "match_score":  # 已废弃
-        instruction = f"请问下面文字与查询主题（{query}）的相关程度是多少？请回答0/1/2（2为最高相关）。文字内容：\n\n"
-    elif submode == "fill_blank":
-        instruction = f"请问下面文字中哪个词与查询主题（{query}）最相关？如无相关词则回答“无”。文字内容：\n\n"
-    else:
-        raise ValueError(f"未知子模式: {submode}")
+    instruction, generation_guide, neg_token = _build_prompt_parts(submode, query)
 
     # 截断 text 到 max_length token，再拼
-    truncated_text = _truncate_text_by_tokens(tokenizer, text, max_length)
+    truncated_text, input_token_count = _truncate_text_by_tokens(tokenizer, text, max_length)
     
     messages = [{"role": "user", "content": instruction + truncated_text}]
     formatted = tokenizer.apply_chat_template(
         messages, tokenize=False, add_generation_prompt=True,
         enable_thinking=False
     )
-    # 生成引导词：chat template 只支持完整消息，引导词需追加到 formatted
-    if submode == "count":
-        generation_guide = f"原文中与查询主题（{query}）相关的词的数量 = **"
-    elif submode == "match_score":  # 已废弃
-        generation_guide = f"文章和查询主题（{query}）的相关程度（0-2）打分为：**"
-    elif submode == "fill_blank":
-        # “引号是特意为了防止模型生成引号
-        generation_guide = f"原文中与查询主题（{query}）最相关的一个词是：**“"
-    else:
-        raise ValueError(f"未知子模式: {submode}")
     formatted += generation_guide
 
     # logits_gradient count/fill_blank 的 top-k，影响梯度目标覆盖的候选词数量
@@ -170,7 +191,6 @@ def _analyze_logits_gradient(
         if _get_verbose():
             print(f"top{LOGITS_GRADIENT_TOPK}: {[f'{t}({p*100:.1f}%)' for t, p in zip(topk_tokens, topk_probs)]}")
 
-        neg_token = "无" if submode == "fill_blank" else "0"
         neg_id = tokenizer.encode(neg_token, add_special_tokens=False)[0]
         # 全文匹配度：count/match_score(已废弃) 用 1-P("0")，fill_blank 用 1-P("无")
         p_neg = probs[0, neg_id].item()
@@ -181,6 +201,7 @@ def _analyze_logits_gradient(
                 "model": get_instruct_model_display_name(),
                 "token_attention": [],
                 "full_match_degree": full_match_degree,
+                "input_token_count": input_token_count,
             }
 
         if progress_callback:
@@ -239,6 +260,7 @@ def _analyze_logits_gradient(
             "model": get_instruct_model_display_name(),
             "token_attention": token_attention,
             "full_match_degree": full_match_degree,
+            "input_token_count": input_token_count,
         }
         if debug_info:
             out["debug_info"] = {"abbrev": abbrev, "topk_tokens": topk_tokens, "topk_probs": topk_probs}
@@ -250,28 +272,120 @@ def _analyze_logits_gradient(
         DeviceManager.clear_cache(device)
 
 
+def _analyze_logits_gradient_batch(
+    query: str,
+    texts: List[str],
+    tokenizer,
+    model,
+    device,
+    submode_override: Optional[str] = None,
+    progress_callback: Optional[Callable[[int, int, str, Optional[int]], None]] = None,
+) -> List[Dict]:
+    """
+    批量 full_match_degree_only 前向：多条 text 一次 forward，仅用于 count 预判等纯前向场景的性能测试。
+    无反向传播，不产出 token_attention（与单条 full_match_degree_only=True 时一致）。
+
+    性能结论（本地 CPU/线上服务器实测）：
+    batching 对本函数内前向计算的加速有限，batch=4 约 1.3~1.5x，batch=8 约 1.6x，
+    边际递减明显；MPS 上则几乎无收益。线上用客户端总耗时测得的更高"加速比"，
+    大头来自摊薄了每次 HTTP 请求固定的网络/SSE 开销（约 1.2~1.7s，与 batch 无关），
+    并非本函数计算变快。
+    """
+    TOTAL_STEPS = 2  # 批量只有 encoding / inference 两阶段，无 backward/processing
+
+    submode = submode_override if submode_override is not None else _get_logits_gradient_submode()
+    max_length = get_semantic_max_token_length()
+
+    if progress_callback:
+        progress_callback(1, TOTAL_STEPS, "encoding", None)
+    instruction, generation_guide, neg_token = _build_prompt_parts(submode, query)
+
+    formatted_list = []
+    input_token_counts = []
+    for text in texts:
+        truncated_text, input_token_count = _truncate_text_by_tokens(tokenizer, text, max_length)
+        input_token_counts.append(input_token_count)
+        messages = [{"role": "user", "content": instruction + truncated_text}]
+        formatted = tokenizer.apply_chat_template(
+            messages, tokenize=False, add_generation_prompt=True, enable_thinking=False
+        )
+        formatted_list.append(formatted + generation_guide)
+
+    # 左 padding：批内各序列长度不同，取 logits[:, -1, :] 时需保证最后一列都是各自真实末尾 token
+    # pad_token / padding_side 都是共享 tokenizer 上的可变状态，用完必须还原
+    original_pad_token = tokenizer.pad_token
+    original_padding_side = tokenizer.padding_side
+    try:
+        if tokenizer.pad_token_id is None:
+            tokenizer.pad_token = tokenizer.eos_token
+        tokenizer.padding_side = "left"
+        enc = tokenizer(formatted_list, return_tensors="pt", padding=True)
+    finally:
+        tokenizer.padding_side = original_padding_side
+        tokenizer.pad_token = original_pad_token
+
+    input_ids = enc["input_ids"].to(device)
+    attention_mask = enc["attention_mask"].to(device)
+
+    if progress_callback:
+        progress_callback(2, TOTAL_STEPS, "inference", None)
+    model.eval()
+    with torch.no_grad():
+        outputs = model(input_ids=input_ids, attention_mask=attention_mask, output_attentions=False)
+    if device.type == "cuda":
+        torch.cuda.synchronize(device)
+    elif device.type == "mps":
+        torch.mps.synchronize()
+
+    logits = outputs.logits[:, -1, :]
+    probs = torch.softmax(logits, dim=-1)
+    neg_id = tokenizer.encode(neg_token, add_special_tokens=False)[0]
+    full_match_degrees = (1.0 - probs[:, neg_id]).tolist()
+
+    DeviceManager.clear_cache(device)
+    return [
+        {
+            "model": get_instruct_model_display_name(),
+            "token_attention": [],
+            "full_match_degree": round(fmd, 4),
+            "input_token_count": input_token_count,
+        }
+        for fmd, input_token_count in zip(full_match_degrees, input_token_counts)
+    ]
+
+
 def analyze_semantic(
     query: str,
-    text: str,
+    text,
     submode_override: Optional[str] = None,
     progress_callback: Optional[Callable[[int, int, str, Optional[int]], None]] = None,
     debug_info: bool = False,
     full_match_degree_only: bool = False,
-) -> Dict:
+):
     """
     分析原文各 token 与 query 的相关度（使用 logits_gradient 梯度归因）。
 
     Args:
         query: 查询主题
-        text: 原文
+        text: 原文；为 List[str] 时走批量前向（仅支持 full_match_degree_only=True，用于性能测试）
         submode_override: 评估时可选覆盖子模式（count/match_score已废弃/fill_blank）
         progress_callback: 可选进度回调 (step, total_steps, stage, percentage)
         debug_info: 为 True 时返回 debug_abbrev（推理原文缩写）；topk_tokens、topk_probs 始终在结果中
 
     Returns:
-        {"model", "token_attention"（各 token 归因 score；API 历史字段名）, "full_match_degree"}；debug_info=True 时包含 debug_info 对象
+        text 为 str 时：{"model", "token_attention"（各 token 归因 score；API 历史字段名）, "full_match_degree"}；
+        debug_info=True 时包含 debug_info 对象。
+        text 为 List[str] 时：上述字典组成的 List（无 debug_info）。
     """
     tokenizer, model, device = ensure_instruct_slot_ready()
+    if isinstance(text, list):
+        if not full_match_degree_only:
+            raise ValueError("text 为数组（批量）时仅支持 full_match_degree_only=True")
+        return _analyze_logits_gradient_batch(
+            query, text, tokenizer, model, device,
+            submode_override=submode_override,
+            progress_callback=progress_callback,
+        )
     return _analyze_logits_gradient(
         query, text, tokenizer, model, device,
         submode_override=submode_override,

backend/platform/access_log.py

@@ -160,9 +160,28 @@ def log_analyze_semantic_start(request_id: int, wait_time: float, stream_mode: b
     print(f"\t🔄 API analyze_semantic {mode_str} start: req_id={request_id}, wait_time={wait_time:.2f}s")
 
 
-def log_analyze_semantic_request(query: str, text: str, client_ip: str = None):
+_visitor_seq: dict = {}
+_visitor_seq_lock = threading.Lock()
+
+
+def _visitor_seq_no(ip: Optional[str]) -> int:
+    """
+    进程内递增的访客序号：同一 IP 复用同一序号，日志里只留这个号、不落 IP 本身。
+    映射表只在内存里，随进程重启清空，不写盘。
+    """
+    key = ip or "unknown"
+    with _visitor_seq_lock:
+        seq = _visitor_seq.get(key)
+        if seq is None:
+            seq = len(_visitor_seq) + 1
+            _visitor_seq[key] = seq
+        return seq
+
+
+def log_analyze_semantic_request(query: str, text: str, client_ip: str = None, privacy_mode: bool = False):
     """
-    记录收到 semantic 分析请求
+    记录收到 semantic 分析请求。
+    privacy_mode=True（插件请求固定如此）时不落 query/text 内容与明文 IP，仅记字符数和 IP 摘要。
 
     Returns:
         int: 请求ID
@@ -173,11 +192,16 @@ def log_analyze_semantic_request(query: str, text: str, client_ip: str = None):
         _request_counter += 1
         request_id = _request_counter
 
-    preview = 50
-    q_preview = _log_str_preview(query, preview)
-    t_preview = _log_str_preview(text, preview)
-    details = f"req_id={request_id}, query='{q_preview}', text='{t_preview}', chars={len(text)}"
-    log_request("📥 semantic 分析请求", details, client_ip)
+    if privacy_mode:
+        visitor = f"visitor=#{_visitor_seq_no(client_ip)}"
+        details = f"req_id={request_id}, query_chars={len(query)}, text_chars={len(text)}"
+        log_request("📥 semantic 分析请求（隐私模式）", details, client_ip=visitor)
+    else:
+        preview = 50
+        q_preview = _log_str_preview(query, preview)
+        t_preview = _log_str_preview(text, preview)
+        details = f"req_id={request_id}, query='{q_preview}', text='{t_preview}', chars={len(text)}"
+        log_request("📥 semantic 分析请求", details, client_ip)
 
     _hit_api("analyze_semantic")
     return request_id

backend/platform/inference_ingress.py

@@ -75,7 +75,7 @@ def ingress_inference(
     顺序：access_log / bump_api（log_fn）→ 分流 → response_log_fn（非 worker）。
 
     Worker 上未启用的槽位直接 404；remote 槽位 HTTP 代理到对应 Space。
-    门户本地与代理共用同一 response 日志回调。
+    response_log_fn：远程代理端到端日志；本地执行若已在 handler 打完整日志可传 None。
     """
     if is_worker() and not slot_enabled(slot):
         return _slot_unavailable(slot)

backend/platform/inference_response_log.py

@@ -1,4 +1,9 @@
-"""推理 API 响应日志：ingress 统一回调；handler 内仅 worker 本地路径打印。"""
+"""推理 API 响应日志。
+
+- 远程代理：门户 ingress `response_log_fn` 打端到端。
+- 本地执行（门户本地槽位或 worker）：handler 内打完整日志（可含 wait/processing）；
+  用 `for_worker` 区分进程，避免与门户回调重复。
+"""
 from __future__ import annotations
 
 from collections.abc import Callable, Mapping
@@ -43,14 +48,17 @@ def log_analyze_semantic_response(
     request_id: int | None,
     result: dict,
     elapsed: float,
+    wait_time: float | None = None,
     for_worker: bool = False,
 ) -> None:
     if not _should_emit(for_worker=for_worker):
         return
-    tokens = len(result.get("token_attention", []))
+    tokens = result.get("input_token_count", len(result.get("token_attention", [])))
     msg = f"\t📤 API analyze_semantic (stream) response:"
     msg += _req_id_part(request_id)
     msg += f" tokens={tokens}, response_time={elapsed:.4f}s"
+    if wait_time is not None:
+        msg += f" (wait={wait_time:.4f}s, processing={elapsed - wait_time:.4f}s)"
     print(msg)
 
 
@@ -171,12 +179,22 @@ def make_analyze_response_logger(
 def make_analyze_semantic_response_logger(
     logged: Mapping[str, int | None],
 ) -> PortalResponseLogger:
+    """远程代理路径：从响应体取 input_token_count（含批量 results 汇总），无 wait。"""
+
     def _log(data: Any, elapsed: float, _status: int) -> None:
         if not isinstance(data, dict):
             return
+        results = data.get("results")
+        if isinstance(results, list):
+            total = sum(
+                r.get("input_token_count", 0) for r in results if isinstance(r, dict)
+            )
+            result = {"input_token_count": total}
+        else:
+            result = data
         log_analyze_semantic_response(
             request_id=logged.get("request_id"),
-            result=data,
+            result=result,
             elapsed=elapsed,
         )
 

backend/platform/logging_config.py

@@ -16,7 +16,6 @@ def configure_logging(app=None):
     # 屏蔽第三方库的日志
     logging.getLogger('werkzeug').setLevel(logging.CRITICAL)
     logging.getLogger('connexion').setLevel(logging.CRITICAL)
-    logging.getLogger('flask_cors').setLevel(logging.CRITICAL)
     logging.getLogger('flask').setLevel(logging.CRITICAL)
     logging.getLogger('urllib3').setLevel(logging.CRITICAL)
     logging.getLogger('transformers').setLevel(logging.CRITICAL)

backend/platform/runtime_config.py

@@ -86,6 +86,7 @@ RUNTIME_CONFIGS = {
 
 # ============= 语义分析运行时配置（仅 max_token_length） =============
 # 按平台配置，语义分析独立于信息密度模型
+# 已知问题：与前端 chunkBytes 无联动，超限时静默截断导致漏检，见 semantic_analyzer._truncate_text_by_tokens
 
 SEMANTIC_RUNTIME_CONFIGS = {
     "default_cpu_machine": {"max_token_length": 300},

backend/tests/test_inference_response_log.py

@@ -64,3 +64,35 @@ def test_extract_completions_ttft_from_result():
     }
     p, c, ttft = inference_response_log.extract_completions_usage(data)
     assert (p, c, ttft) == (10, 5, 0.25)
+
+
+def test_semantic_response_uses_input_token_count_when_attention_empty(capsys):
+    inference_response_log.log_analyze_semantic_response(
+        request_id=19,
+        result={"token_attention": [], "input_token_count": 142},
+        elapsed=1.564,
+        wait_time=0.012,
+    )
+    out = capsys.readouterr().out
+    assert "tokens=142" in out
+    assert "wait=0.0120s" in out
+    assert "processing=" in out
+
+
+def test_semantic_portal_logger_sums_batch_input_token_count(capsys):
+    logged = {"request_id": 7}
+    log_fn = inference_response_log.make_analyze_semantic_response_logger(logged)
+    log_fn(
+        {
+            "success": True,
+            "results": [
+                {"full_match_degree": 0.5, "input_token_count": 10},
+                {"full_match_degree": 0.2, "input_token_count": 20},
+            ],
+        },
+        0.8,
+        200,
+    )
+    out = capsys.readouterr().out
+    assert "req_id=7" in out
+    assert "tokens=30" in out

client/src/analysis.html

@@ -81,7 +81,7 @@
                                         <span class="semantic-submode-group">
                                             <label class="semantic-submode-label" for="semantic_analysis_toggle">
                                                 <input type="checkbox" id="semantic_analysis_toggle" />
-                                                <span data-i18n>Semantic Query(Beta)</span>
+                                                <span data-i18n>Semantic Find(Beta)</span>
                                             </label>
                                         </span>
                                     </div>

client/src/css/base/_theme-vars.scss

@@ -56,6 +56,25 @@
   --accent-glow: color-mix(in srgb, var(--accent-color) 60%, transparent);
   --accent-shadow: color-mix(in srgb, var(--accent-color) 65%, transparent);
   --accent-stroke: color-mix(in srgb, var(--accent-color) 90%, transparent);
+  // 语义 AI 主题（参考 Gemini 彩虹渐变，区别于交互蓝 --accent-color）
+  --semantic-ai-gradient: linear-gradient(
+    90deg,
+    #4285f4 0%,
+    #9b72cb 28%,
+    #d96570 52%,
+    #fbbc04 78%,
+    #4285f4 100%
+  );
+  --semantic-ai-gradient-muted: linear-gradient(
+    90deg,
+    color-mix(in srgb, #4285f4 48%, #9aa0a6) 0%,
+    color-mix(in srgb, #9b72cb 48%, #9aa0a6) 28%,
+    color-mix(in srgb, #d96570 48%, #9aa0a6) 52%,
+    color-mix(in srgb, #fbbc04 48%, #9aa0a6) 78%,
+    color-mix(in srgb, #4285f4 48%, #9aa0a6) 100%
+  );
+  --semantic-ai-glow: color-mix(in srgb, #9b72cb 42%, transparent);
+  --semantic-ai-glow-muted: color-mix(in srgb, #9b72cb 22%, transparent);
   --text-disabled: #999;
   --text-area-bg: #fff;
   --textarea-actions-button-row-min-height: 3.5rem;
@@ -108,6 +127,24 @@
   --accent-glow: color-mix(in srgb, var(--accent-color) 80%, transparent);
   --accent-shadow: var(--accent-glow);
   --accent-stroke: color-mix(in srgb, var(--accent-color) 90%, transparent);
+  --semantic-ai-gradient: linear-gradient(
+    90deg,
+    #8ab4f8 0%,
+    #c58af9 28%,
+    #f28b82 52%,
+    #fdd663 78%,
+    #8ab4f8 100%
+  );
+  --semantic-ai-gradient-muted: linear-gradient(
+    90deg,
+    color-mix(in srgb, #8ab4f8 45%, #5f6368) 0%,
+    color-mix(in srgb, #c58af9 45%, #5f6368) 28%,
+    color-mix(in srgb, #f28b82 45%, #5f6368) 52%,
+    color-mix(in srgb, #fdd663 45%, #5f6368) 78%,
+    color-mix(in srgb, #8ab4f8 45%, #5f6368) 100%
+  );
+  --semantic-ai-glow: color-mix(in srgb, #c58af9 50%, transparent);
+  --semantic-ai-glow-muted: color-mix(in srgb, #c58af9 24%, transparent);
   --primary-color: var(--accent-color);
   --text-disabled: #666;
   --text-area-bg: #191919;

client/src/css/components/_semantic-analysis.scss

@@ -199,6 +199,13 @@
       border-radius: 4px;
       background: var(--input-bg);
       color: var(--text-color);
+
+      // 搜索中 readOnly：不显示编辑光标、不可点入
+      &:read-only {
+        caret-color: transparent;
+        cursor: default;
+        pointer-events: none;
+      }
     }
 
     .semantic-search-clear {

client/src/css/pages/analysis.scss

@@ -1,7 +1,25 @@
 // Analysis 页专有样式（intro / 统计图 / 分析进度）
 @use 'app-pages';
+@use '../base/breakpoints' as *;
 @use '../base/narrow-ios-form-font-tail' as ios-form-font;
 
+@media (min-width: $breakpoint-tablet) {
+  html:not([data-force-narrow]) {
+    .right_panel {
+      overflow: hidden;
+    }
+
+    .right_panel > #results {
+      flex: 1 1 auto;
+      min-height: 0;
+      height: 100%;
+      max-height: 100%;
+      overflow-x: hidden;
+      overflow-y: auto;
+    }
+  }
+}
+
 // 介绍区域样式
 .intro-section {
   margin-bottom: 15px;

client/src/features/analysis/analyzeFlow.ts

@@ -17,6 +17,7 @@ import { handleServerDemoSave } from '../../shared/controllers/serverDemoControl
 // 国际化
 import { tr } from '../../shared/lang/i18n-lite';
 import { playAnalysisCompleteSound } from '../../shared/cross/soundNotification';
+import { getDesktopTextScrollRoot } from '../../shared/core/responsive';
 
 /**
  * 分析进度回调
@@ -86,10 +87,8 @@ export class AnalyzeFlowManager {
      */
     private scrollToTop(): void {
         requestAnimationFrame(() => {
-            const rightPanel = document.querySelector('.right_panel') as HTMLElement;
-            if (rightPanel) {
-                rightPanel.scrollTop = 0;
-            }
+            const root = getDesktopTextScrollRoot();
+            if (root) root.scrollTop = 0;
         });
     }
 

client/src/features/analysis/appStateManager.ts

@@ -4,6 +4,7 @@
  */
 
 import * as d3 from 'd3';
+import { getSemanticAnalysisEnabled } from '../../shared/cross/semanticAnalysisManager';
 
 /**
  * 应用状态对象
@@ -128,9 +129,10 @@ export class AppStateManager {
             }
         }
 
-        // TextMetrics显示：有有效数据（hasValidData = true 时，stats 一定不为 null）
+        // TextMetrics：仅信息密度模式且有有效数据时显示（语义模式互斥隐藏）
         if (!this.deps.textMetrics.empty()) {
-            this.deps.textMetrics.classed('is-hidden', !this.state.hasValidData);
+            const showMetrics = this.state.hasValidData && !getSemanticAnalysisEnabled();
+            this.deps.textMetrics.classed('is-hidden', !showMetrics);
         }
     }
 
@@ -155,10 +157,20 @@ export class AppStateManager {
         }
         // 语义搜索 loading：独立 loader
         if (updates.isSemanticSearching !== undefined) {
-            d3.select('#semantic_search_loader').style('visibility', updates.isSemanticSearching ? 'visible' : 'hidden');
-            if (!updates.isSemanticSearching) {
+            const searching = updates.isSemanticSearching;
+            d3.select('#semantic_search_loader').style('visibility', searching ? 'visible' : 'hidden');
+            if (!searching) {
                 d3.select('#semantic_progress').text('').style('display', 'none');
             }
+            // 搜索中退出编辑态：失焦、只读、藏光标；结束恢复可编
+            const el = document.getElementById('semantic_search_input') as HTMLInputElement | null;
+            if (el) {
+                el.readOnly = searching;
+                if (searching) el.blur();
+            }
+            if (searching) {
+                document.getElementById('semantic_search_history_dropdown')?.classList.remove('is-visible');
+            }
         }
     }
 

client/src/features/analysis/infoDensityRenderManager.ts

@@ -1,12 +0,0 @@
-import { lsReadBool, lsWriteBool } from '../../shared/storage/localStorageHelpers';
-
-/** 信息密度底色渲染开关 key：为 true 时关闭信息密度/classic 底色（语义叠加层不受影响） */
-export const INFO_DENSITY_RENDER_DISABLED_KEY = 'info_radar_disable_info_density_render';
-
-export function getInfoDensityRenderDisabled(): boolean {
-    return lsReadBool(INFO_DENSITY_RENDER_DISABLED_KEY, false);
-}
-
-export function setInfoDensityRenderDisabled(disabled: boolean): void {
-    lsWriteBool(INFO_DENSITY_RENDER_DISABLED_KEY, disabled);
-}

client/src/features/analysis/visualizationUpdater.ts

@@ -45,14 +45,6 @@ import { getDigitsMergeEnabled } from '../../shared/cross/digitsMergeManager';
 import { getSemanticMatchThreshold } from '../../shared/cross/semanticThresholdManager';
 import { applySemanticDebugInfoPanel } from '../../shared/prediction_attribution/core/semanticDebugInfo';
 
-/** Token 边界不一致时抛出，用于中断联合展示 */
-export class TokenBoundaryInconsistentError extends Error {
-    constructor() {
-        super('Tokenizer results inconsistent: semantic and info-density token boundaries differ.');
-        this.name = 'TokenBoundaryInconsistentError';
-    }
-}
-
 /**
  * P(signal | raw_score_normed = s) 复用 findSignalThreshold 的 bins
  * 每个样本 s 落入对应 bin，P(signal) = (obsInBin - expInBin) / obsInBin
@@ -81,6 +73,8 @@ export interface VisualizationDependencies {
     stats_match_score_progress: ScatterPlot;
     appStateManager: AppStateManager;
     surprisalColorScale: d3.ScaleSequential<string>;
+    /** 语义/密度模式切换时同步 Analyze·上传·保存·metrics 等 chrome 显隐 */
+    syncModeChrome?: (semanticEnabled: boolean) => void;
 }
 
 /** 语义分析原始数据（独立存储） */
@@ -119,7 +113,7 @@ function hasSemanticData(data: { token_attention?: unknown[]; chunkInfos?: unkno
 
 /**
  * 当前数据状态
- * 信息密度与语义分析独立存储，展示时根据一致性决定单独或联合
+ * 信息密度与语义分析独立存储；展示由当前模式二选一，互不合并
  */
 export interface CurrentDataState {
     /** 信息密度分析结果（独立） */
@@ -168,7 +162,7 @@ export class VisualizationUpdater {
     }
 
     /**
-     * 获取当前展示数据（由 infoDensityData 与 semanticData 按展示逻辑计算）
+     * 获取当前展示数据（按当前模式取 infoDensityData 或 semanticData，互不合并）
      */
     getCurrentData(): AnalyzeResponse | null {
         const display = this.computeDisplayResult();
@@ -176,6 +170,24 @@ export class VisualizationUpdater {
         return { request: { text: display.originalText }, result: display };
     }
 
+    /** 语义分块中达到 Match threshold 的 chunk（供 Find 浮条 ↑↓） */
+    getMatchedChunks(): Array<{ startOffset: number; endOffset: number; chunkIndex: number; chunkMatchDegree: number }> {
+        const chunkInfos = this.currentState.semanticData?.chunkInfos;
+        if (!chunkInfos?.length) return [];
+        const threshold = getSemanticMatchThreshold();
+        return chunkInfos.filter((c) => c.chunkMatchDegree >= threshold);
+    }
+
+    /** 切回语义模式时恢复 Match 文案：分块取 max(chunkMatchDegree)，整段取 full_match_degree */
+    peekSemanticMatchDegree(): number | null {
+        const sem = this.currentState.semanticData;
+        if (!sem || !hasSemanticData(sem)) return null;
+        if (sem.chunkInfos?.length) {
+            return Math.max(...sem.chunkInfos.map((c) => c.chunkMatchDegree));
+        }
+        return typeof sem.full_match_degree === 'number' ? sem.full_match_degree : null;
+    }
+
     /**
      * 获取当前 surprisal 数据
      */
@@ -193,12 +205,12 @@ export class VisualizationUpdater {
     /**
      * 清除高亮
      */
-    private clearHighlights(): void {
-        this.deps.highlightController.clearHighlights();
+    private clearHighlights(options?: { preserveChunkInterval?: boolean }): void {
+        this.deps.highlightController.clearHighlights(options);
     }
 
     /**
-     * 计算展示结果：仅信息密度 / 仅语义 / 联合（两者一致时）
+     * 计算展示结果：按当前模式二选一（语义 / 信息密度），不合并
      */
     private computeDisplayResult(): (FrontendAnalyzeResult & {
         rawScoresNormed?: number[];
@@ -208,64 +220,26 @@ export class VisualizationUpdater {
         const info = this.currentState.infoDensityData;
         const sem = this.currentState.semanticData;
         const infoResult = info?.result as FrontendAnalyzeResult | undefined;
-        const infoText = info?.request?.text ?? infoResult?.originalText ?? '';
-        const semText = sem?.text ?? '';
-
-        if (infoResult && sem && infoText === semText && hasSemanticData(sem)) {
-            const infoMerged = infoResult.bpeBpeMergedTokens ?? infoResult.bpe_strings;
-            if (infoMerged?.length) {
-                // 有 token_attention 时校验边界；仅 chunkInfos 时跳过（无语义着色）
-                if (sem.token_attention?.length) {
-                    const boundaryError = this.checkSemanticAlignsWithInfo(sem.token_attention, infoMerged, semText);
-                if (boundaryError) {
-                    const { aSample, bSample, aNext, bNext, textBefore, textAt, textAfter } = boundaryError;
-                    console.warn(
-                        '[联合模式] 两种分析的分词token边界不一致：\n' +
-                        '  语义分析：', aSample, '\n' +
-                        '  信息密度：', bSample, '\n' +
-                        '  语义后一个：', aNext, '\n' +
-                        '  信息后一个：', bNext, '\n' +
-                        '  位置附近原文：', JSON.stringify(textBefore), '|', JSON.stringify(textAt), '|', JSON.stringify(textAfter)
-                    );
-                    showAlertDialog(tr('Error'), tr('Tokenizer results inconsistent: semantic and info-density token boundaries differ.'));
-                    this.currentState.semanticData = null;
-                    throw new TokenBoundaryInconsistentError();
-                }
-                }
-                // 联合模式：bpeMerged 与语义 tokens 超出部分合并为并集，使 rect/渲染范围与截断边界一致
-                const semanticTokens = sem.token_attention ?? [];
-                const { unionTokens, scoresForUnion, rawScoresForUnion } = semanticTokens.length
-                    ? this.mergeBpeWithSemanticBeyond(infoMerged, semanticTokens)
-                    : (() => {
-                        const m = this.mapSemanticTokensToMerged(infoMerged, []);
-                        return {
-                            unionTokens: infoMerged,
-                            scoresForUnion: m.scores,
-                            rawScoresForUnion: m.rawScores,
-                        };
-                    })();
-                return {
-                    ...infoResult,
-                    bpeBpeMergedTokens: unionTokens,
-                    bpe_strings: unionTokens,
-                    rawScoresNormed: scoresForUnion,
-                    tokenRawScores: rawScoresForUnion,
-                    chunkInfos: sem.chunkInfos,
-                };
+
+        if (getSemanticAnalysisEnabled()) {
+            if (sem && hasSemanticData(sem)) {
+                return this.buildSemanticOnlyResult(
+                    { model: sem.model },
+                    sem.token_attention,
+                    sem.text,
+                    sem.chunkInfos
+                );
             }
+            return null;
         }
-        // 有语义数据（token_attention 或 chunkInfos）时用 buildSemanticOnlyResult
-        if (sem && hasSemanticData(sem)) {
-            return this.buildSemanticOnlyResult({ model: sem.model }, sem.token_attention, sem.text, sem.chunkInfos);
-        }
-        if (infoResult) return { ...infoResult, chunkInfos: sem?.chunkInfos ?? undefined };
+        if (infoResult) return { ...infoResult };
         return null;
     }
 
     /**
-     * 分析开始前更新直方图显示/隐藏：基于「已有数据 + 将要得到的数据」判断各统计图是否有意义
+     * 分析开始前更新直方图显示/隐藏：基于当前模式 + 将要得到的数据
      * @param mode 即将进行的分析类型
-     * @param text 即将分析的文本（用于判断与已有数据是否一致、能否联合展示）
+     * @param text 即将分析的文本
      * @param willBeChunked 语义分析时：true 表示将走分块模式，直方图不显示
      */
     public updateHistogramVisibilityForPending(mode: 'infoDensity' | 'semantic', text: string, willBeChunked?: boolean): void {
@@ -274,26 +248,8 @@ export class VisualizationUpdater {
         const rawScoreNormedItem = document.getElementById('raw_score_normed_histogram_item');
         const matchScoreProgressItem = document.getElementById('match_score_progress_item');
 
-        const infoText = this.currentState.infoDensityData?.request?.text ?? '';
-        const semText = this.currentState.semanticData?.text ?? '';
-        const semanticQueryOn = getSemanticAnalysisEnabled();
-
-        let showInfoDensity = false;
-        let showSemantic = false;
-
-        if (mode === 'infoDensity') {
-            /** Semantic Query 勾选时统计区不出现信息密度图占位 */
-            showInfoDensity = !semanticQueryOn;
-            showSemantic =
-                semanticQueryOn &&
-                hasSemanticData(this.currentState.semanticData) &&
-                semText === text;
-        } else {
-            showSemantic = true;
-            showInfoDensity =
-                !semanticQueryOn &&
-                !!(this.currentState.infoDensityData && infoText === text);
-        }
+        const showInfoDensity = mode === 'infoDensity';
+        const showSemantic = mode === 'semantic';
 
         if (tokenHistogramItem) tokenHistogramItem.style.display = showInfoDensity ? '' : 'none';
         if (surprisalProgressItem) surprisalProgressItem.style.display = showInfoDensity ? '' : 'none';
@@ -474,20 +430,21 @@ export class VisualizationUpdater {
                 : colorSource === 'pw_score' ? pwScores
                 : (displayResult!.rawScoresNormed ?? []);
 
-            // 联合模式下 tooltip 需要 pPwValues/pwScores 显示语义匹配信息，即使 fitResult 为 null 也要传递
+            // tooltip / color source 切换需要 pPwValues/pwScores，即使 fitResult 为 null（如 P90 回退）也要传递
             const resultWithExt = hasThreshold
                 ? { ...displayResult, signalProbs, pPwValues, pwScores }
                 : displayResult!;
-            if (fitResult != null) {
-                this.deps.highlightController.updateCurrentData({ result: resultWithExt, signalProbs, pPwValues, pwScores });
-                if (!skipLmfUpdate) {
-                    this.deps.lmf.update({ ...resultWithExt, pwScores, colorScores: scoresForColor } as FrontendAnalyzeResult & { pPwValues?: number[]; pwScores?: number[]; colorScores?: number[] });
-                }
-            } else {
-                this.deps.highlightController.updateCurrentData({ result: resultWithExt });
-                if (!skipLmfUpdate) {
-                    this.deps.lmf.update({ ...resultWithExt, colorScores: scoresForColor } as FrontendAnalyzeResult & { pPwValues?: number[]; pwScores?: number[]; colorScores?: number[] });
-                }
+            this.deps.highlightController.updateCurrentData(
+                hasThreshold
+                    ? { result: resultWithExt, signalProbs, pPwValues, pwScores }
+                    : { result: resultWithExt }
+            );
+            if (!skipLmfUpdate) {
+                this.deps.lmf.update({
+                    ...resultWithExt,
+                    ...(hasThreshold ? { pwScores } : {}),
+                    colorScores: scoresForColor,
+                } as FrontendAnalyzeResult & { pPwValues?: number[]; pwScores?: number[]; colorScores?: number[] });
             }
 
             /** 直方图仅在整段模式显示，chunk 模式下不统计、不显示 */
@@ -594,14 +551,16 @@ export class VisualizationUpdater {
     /** 仅更新语义着色源（color source 切换时调用，不重新拟合） */
     public updateSemanticColorSource(): void {
         const cd = this.deps.highlightController.getCurrentData();
-        const r = cd?.result as (FrontendAnalyzeResult & { rawScoresNormed?: number[] }) | undefined;
+        const r = cd?.result as (FrontendAnalyzeResult & { rawScoresNormed?: number[]; pPwValues?: number[]; pwScores?: number[] }) | undefined;
         if (!r?.rawScoresNormed?.length) return;
         const el = document.getElementById('semantic_color_source_select') as HTMLSelectElement | null;
         const v = el?.value ?? 'pw_score';
-        const scoresForColor = v === 'signal_probability' ? (cd!.pPwValues ?? [])
-            : v === 'pw_score' ? (cd!.pwScores ?? [])
+        const pPwValues = cd!.pPwValues ?? r.pPwValues;
+        const pwScores = cd!.pwScores ?? r.pwScores;
+        const scoresForColor = v === 'signal_probability' ? (pPwValues ?? [])
+            : v === 'pw_score' ? (pwScores ?? [])
             : r.rawScoresNormed;
-        this.deps.lmf.update({ ...r, pPwValues: cd!.pPwValues, pwScores: cd!.pwScores, colorScores: scoresForColor } as FrontendAnalyzeResult & { pPwValues?: number[]; pwScores?: number[]; colorScores?: number[] });
+        this.deps.lmf.update({ ...r, pPwValues, pwScores, colorScores: scoresForColor } as FrontendAnalyzeResult & { pPwValues?: number[]; pwScores?: number[]; colorScores?: number[] });
     }
 
     /** 主题切换时调用：在样式生效后统一重绘直方图与文本（rgba 透出背景，需等新主题生效） */
@@ -628,16 +587,50 @@ export class VisualizationUpdater {
         this.updateSemanticDebugInfo();
     }
 
+    /** 正文重绘回退用原文：语义 → 信息密度 → 左侧输入 */
+    private resolvePlainTextFallback(): string {
+        const infoResult = this.currentState.infoDensityData?.result as FrontendAnalyzeResult | undefined;
+        return (
+            this.currentState.semanticData?.text
+            ?? this.currentState.infoDensityData?.request?.text
+            ?? infoResult?.originalText
+            ?? this.deps.textInputController.getTextValue()
+            ?? ''
+        );
+    }
+
+    /**
+     * 统一正文刷新：有分析结果走完整着色管线，否则 showPlainText 剥掉语义着色。
+     */
+    private refreshTextAfterDataChange(
+        displayResult: ReturnType<VisualizationUpdater['computeDisplayResult']>,
+        plainTextFallback: string
+    ): void {
+        this.deps.lmf.clearHighlight();
+        if (displayResult) {
+            this.updateVisualizationInternal(false);
+        } else {
+            this.deps.highlightController.updateCurrentData(null);
+            this.deps.lmf.showPlainText(plainTextFallback);
+            this.updateVisualizationInternal(true);
+        }
+    }
+
     /**
-     * 清除语义分析相关数据（直方图、debug、semanticData），用于打开模式时初始化
+     * 清除语义分析相关数据并重绘（直方图、debug、正文着色），使界面与「无语义搜索结果」一致
      */
     public clearSemanticState(): void {
+        const plainTextFallback = this.resolvePlainTextFallback();
         this.currentState.semanticData = null;
         const rawScoreNormedItem = document.getElementById('raw_score_normed_histogram_item');
         if (rawScoreNormedItem) rawScoreNormedItem.style.display = 'none';
         const matchScoreProgressItem = document.getElementById('match_score_progress_item');
         if (matchScoreProgressItem) matchScoreProgressItem.style.display = 'none';
         this.updateSemanticDebugInfo();
+        const displayResult = this.computeDisplayResult();
+        this.refreshTextAfterDataChange(displayResult, plainTextFallback);
+        this.deps.appStateManager.updateButtonStates();
+        this.deps.syncModeChrome?.(getSemanticAnalysisEnabled());
     }
 
     /**
@@ -675,52 +668,25 @@ export class VisualizationUpdater {
             this.currentState.currentTokenAvg = computeAverage(mergedSurprisals);
             this.currentState.currentTokenP90 = computeP90(mergedSurprisals);
         }
-        let displayResult: ReturnType<VisualizationUpdater['computeDisplayResult']>;
-        try {
-            displayResult = this.computeDisplayResult();
-        } catch (e) {
-            if (e instanceof TokenBoundaryInconsistentError) {
-                displayResult = this.computeDisplayResult();
-            } else {
-                console.error(e);
-                return;
-            }
-        }
-        this.deps.highlightController.updateCurrentData(displayResult ? { result: displayResult } : null);
-        this.deps.lmf.clearHighlight();
-        if (displayResult) this.deps.lmf.update(displayResult);
-        this.updateVisualizationInternal();
+        const displayResult = this.computeDisplayResult();
+        this.refreshTextAfterDataChange(displayResult, this.resolvePlainTextFallback());
         this.deps.appStateManager.updateButtonStates();
+        this.deps.syncModeChrome?.(getSemanticAnalysisEnabled());
     }
 
     /**
      * 根据语义分析配置同步 UI 状态（查询输入框、文本渲染模式等）
-     * 界面完全由配置决定，不因数据有无而改变
+     * 界面完全由配置决定；切换模式时保留另一边内存数据，仅切换展示
      */
     public syncSemanticUiFromConfig(): void {
         const enabled = getSemanticAnalysisEnabled();
         const el = document.getElementById('semantic_analysis_section');
         if (el) el.style.display = enabled ? '' : 'none';
         this.deps.lmf.updateOptions({ semanticAnalysisMode: enabled }, false);
-        if (!enabled) {
-            // 关闭时清除语义数据；统计图由下方 updateVisualizationInternal 统一刷新
-            this.currentState.semanticData = null;
-            const rawScoreNormedItem = document.getElementById('raw_score_normed_histogram_item');
-            if (rawScoreNormedItem) rawScoreNormedItem.style.display = 'none';
-            const matchScoreProgressItem = document.getElementById('match_score_progress_item');
-            if (matchScoreProgressItem) matchScoreProgressItem.style.display = 'none';
-            this.updateSemanticDebugInfo();
-            const displayResult = this.computeDisplayResult();
-            this.deps.highlightController.updateCurrentData(displayResult ? { result: displayResult } : null);
-            if (!displayResult) {
-                d3.select('#all_result').style('opacity', 0);
-                this.deps.appStateManager.updateState({ hasValidData: false });
-            }
-        }
-        /** 勾选 / 关闭 Semantic Query 后立即刷新统计图显隐（与 getSemanticAnalysisEnabled 一致） */
-        this.updateVisualizationInternal(false);
-        // 语义分析配置影响 Upload/Save 的 dataReadyForSave 条件，需始终更新按钮状态
+        const displayResult = this.computeDisplayResult();
+        this.refreshTextAfterDataChange(displayResult, this.resolvePlainTextFallback());
         this.deps.appStateManager.updateButtonStates();
+        this.deps.syncModeChrome?.(enabled);
     }
 
     /**
@@ -816,16 +782,7 @@ export class VisualizationUpdater {
             this.currentState.infoDensityData = data;
             this.currentState.rawApiResponse = rawSnapshot;
             this.updateSemanticDebugInfo();
-            let displayResult: ReturnType<VisualizationUpdater['computeDisplayResult']>;
-            try {
-                displayResult = this.computeDisplayResult();
-            } catch (e) {
-                if (e instanceof TokenBoundaryInconsistentError) {
-                    displayResult = this.computeDisplayResult();
-                } else {
-                    throw e;
-                }
-            }
+            const displayResult = this.computeDisplayResult();
             this.deps.highlightController.updateCurrentData(displayResult ? { result: displayResult } : null);
 
             this.deps.lmf.clearHighlight();
@@ -963,11 +920,6 @@ export class VisualizationUpdater {
             displayResult = this.computeDisplayResult();
         } catch (e) {
             this.currentState.semanticData = null;
-            if (e instanceof TokenBoundaryInconsistentError) {
-                this.deps.lmf.hideLoading();
-                this.rerenderHistograms();
-                return false;
-            }
             showAlertDialog(tr('Error'), e instanceof Error ? e.message : String(e));
             return false;
         }
@@ -975,8 +927,8 @@ export class VisualizationUpdater {
         d3.select('#all_result').style('opacity', 1).style('display', null);
         this.deps.lmf.hideLoading();
         this.deps.highlightController.updateCurrentData({ result: displayResult });
-        this.deps.lmf.clearHighlight();
-        this.clearHighlights();
+        // 流式 chunk 更新时保留 jumpToChunkHighlight 的区间下划线及其 hold/fade
+        this.clearHighlights({ preserveChunkInterval: true });
         this.updateVisualizationInternal();
 
         this.updateSemanticDebugInfo(res.debug_info);
@@ -1025,142 +977,4 @@ export class VisualizationUpdater {
             chunkInfos
         };
     }
-
-    /**
-     * 检查 semantic token_attention 的边界是否与 info 一致；允许稀疏覆盖（semantic 不必覆盖全文）
-     * @returns 不一致时返回错误描述（含前后文本），一致时返回 null
-     */
-    private checkSemanticAlignsWithInfo(
-        semanticTokens: Array<{ offset: [number, number]; raw?: string }>,
-        infoMerged: Array<{ offset: [number, number] }>,
-        text: string
-    ): { firstBadIdx: number; aSample: string; bSample: string; aNext: string; bNext: string; textBefore: string; textAt: string; textAfter: string } | null {
-        const boundaries = new Set<number>([0]);
-        for (const t of infoMerged) boundaries.add(t.offset[1]);
-        const infoEnd = infoMerged.length > 0 ? infoMerged[infoMerged.length - 1]!.offset[1] : 0;
-        const totalChars = text.length;
-        const ctx = 30;
-        const esc = (s: string) => JSON.stringify(s).slice(1, -1);
-        const fmt = (t: { offset: [number, number]; raw?: string }, idx: number) => {
-            const raw = (t as { raw?: string }).raw ?? text.slice(t.offset[0], t.offset[1]);
-            const s = raw.slice(0, 20) + (raw.length > 20 ? '…' : '');
-            return `第${idx}个token分词 [字符${t.offset[0]}-${t.offset[1]}] "${esc(s)}"`;
-        };
-        for (let i = 0; i < semanticTokens.length; i++) {
-            const [as, ae] = semanticTokens[i].offset;
-            if (as < 0 || ae > totalChars || ae <= as) continue; // 由 validateTokenConsistency 处理
-            if (ae > infoEnd) continue; // 超出双方重叠范围，不参与检查
-            if (!boundaries.has(as) || !boundaries.has(ae)) {
-                const raw = (semanticTokens[i] as { raw?: string }).raw ?? '';
-                const infoIdx = infoMerged.findIndex(t => t.offset[0] <= as && as < t.offset[1]);
-                const infoAt = infoIdx >= 0 ? infoMerged[infoIdx]! : null;
-                const rawShort = (raw || text.slice(as, ae)).slice(0, 20);
-                const infoRaw = infoAt ? (text.slice(infoAt.offset[0], infoAt.offset[1]).slice(0, 20) || '') : '';
-                const nextSem = semanticTokens[i + 1];
-                const nextInfo = infoIdx >= 0 && infoIdx + 1 < infoMerged.length ? infoMerged[infoIdx + 1]! : null;
-                return {
-                    firstBadIdx: i,
-                    aSample: `第${i}个token分词 [字符${as}-${ae}] "${esc(rawShort)}${rawShort.length >= 20 ? '…' : ''}"`,
-                    bSample: infoAt ? `同一位置token分词 [字符${infoAt.offset[0]}-${infoAt.offset[1]}] "${esc(infoRaw)}${infoRaw.length >= 20 ? '…' : ''}"` : '无对应',
-                    aNext: nextSem ? fmt(nextSem, i + 1) : '无',
-                    bNext: nextInfo ? fmt(nextInfo, infoIdx + 1) : '无',
-                    textBefore: text.slice(Math.max(0, as - ctx), as),
-                    textAt: text.slice(as, ae),
-                    textAfter: text.slice(ae, Math.min(totalChars, ae + ctx)),
-                };
-            }
-        }
-        return null;
-    }
-
-    /**
-     * 联合模式：将 bpeMergedTokens 与超出信息密度范围的语义 tokens 合并为并集，用于 rect/渲染范围与截断边界一致。
-     * @returns { unionTokens, scoresForUnion }
-     */
-    private mergeBpeWithSemanticBeyond(
-        bpeMerged: FrontendToken[],
-        semanticTokens: Array<{
-            offset: [number, number];
-            raw: string;
-            score: number;
-            rawScore?: number;
-        }>
-    ): {
-        unionTokens: FrontendToken[];
-        scoresForUnion: (number | undefined)[];
-        rawScoresForUnion: (number | undefined)[];
-    } {
-        const infoEnd = bpeMerged.length > 0 ? bpeMerged[bpeMerged.length - 1]!.offset[1] : 0;
-        const beyond = semanticTokens.filter((t) => t.offset[0] >= infoEnd);
-        if (beyond.length === 0) {
-            const { scores, rawScores } = this.mapSemanticTokensToMerged(bpeMerged, semanticTokens);
-            return {
-                unionTokens: bpeMerged,
-                scoresForUnion: scores,
-                rawScoresForUnion: rawScores,
-            };
-        }
-        /** beyond 已在 handleSemanticResponse 中 overlap+digit 合并；段内用原始 score 重新归一化 */
-        const beyondRenormed = normalizeTokenScores(beyond.map((t) => ({ ...t, score: getTokenRawScore(t) })));
-        const semanticAsFrontend: FrontendToken[] = beyondRenormed.map((t) => ({
-            offset: [t.offset[0], t.offset[1]],
-            raw: t.raw,
-            real_topk: [0, 1] as [number, number],
-            pred_topk: [],
-        }));
-        const unionTokens = [...bpeMerged, ...semanticAsFrontend];
-        const { scores: infoScores, rawScores: infoRawScores } = this.mapSemanticTokensToMerged(
-            bpeMerged,
-            semanticTokens
-        );
-        const beyondScores: (number | undefined)[] = beyondRenormed.map((t) =>
-            Number.isFinite(t.score) ? t.score : undefined
-        );
-        const beyondRawScores: (number | undefined)[] = beyondRenormed.map((t) => {
-            const r = getTokenRawScore(t);
-            return Number.isFinite(r) ? r : undefined;
-        });
-        const scoresForUnion = [...infoScores, ...beyondScores];
-        const rawScoresForUnion = [...infoRawScores, ...beyondRawScores];
-        return { unionTokens, scoresForUnion, rawScoresForUnion };
-    }
-
-    /**
-     * 将语义 API 的 token score 条目（offset 为原文字符偏移）映射到 merged tokens，双指针 O(N+M)。
-     * 前提：两个数组均按 offset 升序排列。
-     */
-    private mapSemanticTokensToMerged(
-        bpeBpeMergedTokens: Array<{ offset: [number, number] }>,
-        semanticTokens: Array<{ offset: [number, number]; score: number; rawScore?: number }>
-    ): {
-        scores: (number | undefined)[];
-        rawScores: (number | undefined)[];
-    } {
-        const n = bpeBpeMergedTokens.length;
-        const scores: number[] = new Array(n).fill(0);
-        const rawScores: number[] = new Array(n).fill(0);
-        const weights: number[] = new Array(n).fill(0);
-
-        let j = 0; // 跳过所有在当前 semantic token 之前结束的 merged token
-        for (const semToken of semanticTokens) {
-            const [as, ae] = semToken.offset;
-            const rawPart = getTokenRawScore(semToken);
-            while (j < n && bpeBpeMergedTokens[j].offset[1] <= as) j++;
-            for (let k = j; k < n && bpeBpeMergedTokens[k].offset[0] < ae; k++) {
-                const [s, e] = bpeBpeMergedTokens[k].offset;
-                // j/k 的推进条件已保证 e > as 且 s < ae，overlap 必然 > 0
-                const overlap = Math.min(e, ae) - Math.max(s, as);
-                scores[k] += semToken.score * overlap;
-                rawScores[k] += rawPart * overlap;
-                weights[k] += overlap;
-            }
-        }
-
-        const norm = (vals: number[]) => vals.map((v, i) => (weights[i] > 0 ? v / weights[i] : undefined));
-        return {
-            scores: norm(scores),
-            rawScores: norm(rawScores),
-        };
-    }
 }
-

client/src/features/chat/chatTurnsView.ts

@@ -25,7 +25,6 @@ const GLTR_OPTIONS = {
     enableRenderAnimation: false,
     enableMinimap: false,
     overlayTokenRenderStyle: 'classic' as const,
-    overlayIgnoreGlobalInfoDensityDisable: true,
     surprisalColorMax: CHAT_SURPRISAL_COLOR_MAP_MAX,
 };
 

client/src/features/demo/demoBusinessLogic.ts

@@ -10,6 +10,7 @@ import type { AppState } from '../analysis/appStateManager';
 import { LocalDemoCache } from '../../shared/storage/localDemoCache';
 import URLHandler from '../../shared/core/URLHandler';
 import { getDemoName } from '../../shared/core/pathUtils';
+import { getDesktopTextScrollRoot } from '../../shared/core/responsive';
 
 /**
  * Demo 渲染选项
@@ -63,10 +64,8 @@ export class DemoBusinessLogic {
      */
     scrollToTop(): void {
         requestAnimationFrame(() => {
-            const rightPanel = document.querySelector('.right_panel') as HTMLElement;
-            if (rightPanel) {
-                rightPanel.scrollTop = 0;
-            }
+            const root = getDesktopTextScrollRoot();
+            if (root) root.scrollTop = 0;
         });
     }
 

client/src/pages/analysis/index.ts

@@ -222,6 +222,16 @@ window.onload = () => {
     initHighlightClearListeners(clearHighlights);
 
     // 创建可视化更新器
+    const syncAnalyzeModeChrome = (semanticEnabled: boolean) => {
+        const isAdmin = adminManager.isInAdminMode();
+        submitBtn.style('display', semanticEnabled ? 'none' : null);
+        loadUrlBtn.style('display', semanticEnabled ? 'none' : null);
+        analyzeSaveBtn.style('display', semanticEnabled || !isAdmin ? 'none' : null);
+        saveBtn.style('display', semanticEnabled || !isAdmin ? 'none' : null);
+        saveLocalBtn.style('display', semanticEnabled ? 'none' : null);
+        // metrics 显隐由 appStateManager（hasValidData ∧ ¬semantic）统一处理
+        appStateManager.updateButtonStates();
+    };
     const visualizationUpdater = new VisualizationUpdater({
         lmf,
         highlightController,
@@ -231,7 +241,8 @@ window.onload = () => {
         stats_surprisal_progress,
         stats_match_score_progress,
         appStateManager,
-        surprisalColorScale: tokenSurprisalColorScale as d3.ScaleSequential<string>
+        surprisalColorScale: tokenSurprisalColorScale as d3.ScaleSequential<string>,
+        syncModeChrome: syncAnalyzeModeChrome,
     });
 
     addDigitsMergeRenderListener(() => {
@@ -311,9 +322,7 @@ window.onload = () => {
         api,
         () => {
             // 根据管理员模式更新写按钮（进/退 admin 会整页 reload，无需在此处理 Compare 链）
-            const isAdmin = adminManager.isInAdminMode();
-            analyzeSaveBtn.style('display', isAdmin ? null : 'none');
-            saveBtn.style('display', isAdmin ? null : 'none');
+            syncAnalyzeModeChrome(getSemanticAnalysisEnabled());
         },
         {
             onMinimapToggle: (enabled: boolean) => {
@@ -323,10 +332,11 @@ window.onload = () => {
                 }, false);
                 lsWriteBool('minimap_enabled', enableMinimap, '1');
             },
-            onSemanticAnalysisToggle: (_enabled: boolean) => {
-                // 打开/关闭时都清除 query，并将 submode/chunked/color/阈值 重置为默认值并写回 localStorage
+            onSemanticAnalysisToggle: (enabled: boolean) => {
+                // submode/chunked/color/阈值重置为默认；不清除另一边分析数据，切回可恢复展示
+                // query：切回语义且仍有 lastSearchedQuery 时回填，避免空输入框配旧高亮
                 const queryEl = document.getElementById('semantic_search_input') as HTMLInputElement | null;
-                if (queryEl) queryEl.value = '';
+                const lastQ = appStateManager.getState().lastSearchedQuery;
                 const submodeEl = document.getElementById('semantic_submode_select') as HTMLSelectElement | null;
                 if (submodeEl) submodeEl.value = 'hybrid';
                 const chunkedEl = document.getElementById('semantic_chunked_mode') as HTMLInputElement | null;
@@ -337,12 +347,28 @@ window.onload = () => {
                 const thresholdEl = document.getElementById('semantic_threshold_input') as HTMLInputElement | null;
                 if (thresholdEl) thresholdEl.value = String(SEMANTIC_MATCH_THRESHOLD);
                 const params = URLHandler.parameters;
-                delete params['semantic_query'];
+                if (enabled && lastQ) {
+                    if (queryEl) queryEl.value = lastQ;
+                    params['semantic_query'] = lastQ;
+                } else {
+                    if (queryEl) queryEl.value = '';
+                    delete params['semantic_query'];
+                    d3.select('#semantic_match_degree').style('display', 'none');
+                }
                 URLHandler.updateUrl(params, false);
                 syncSemanticOptionsToStorage();
-                appStateManager.setLastSearchedQuery(null);
-                visualizationUpdater.clearSemanticState();
                 visualizationUpdater.syncSemanticUiFromConfig();
+                if (enabled && lastQ) {
+                    const md = visualizationUpdater.peekSemanticMatchDegree();
+                    const mdEl = d3.select('#semantic_match_degree');
+                    if (md !== null) {
+                        mdEl.text(tr('Match: {0}%').replace('{0}', (md * 100).toFixed(1)))
+                            .style('display', 'inline-block')
+                            .style('color', md < getSemanticMatchThreshold() ? 'var(--error-color, #e74c3c)' : null);
+                    } else {
+                        mdEl.style('display', 'none');
+                    }
+                }
             },
         },
         themeManager,
@@ -676,6 +702,8 @@ window.onload = () => {
     // 注意：Clear按钮状态和字数统计由TextInputController内部自动管理
     // 使用原生 addEventListener 监听 input 事件，避免覆盖 TextInputController 的监听器
     const textFieldNode = textField.node() as HTMLTextAreaElement | null;
+    /** 用户单方面改过文本，失焦时需把纯文本同步到右侧 */
+    let textDirtyForPlainSync = false;
     if (textFieldNode) {
         textFieldNode.addEventListener('input', (event: Event) => {
             // 检查是否是匹配分析结果的文本填入
@@ -683,6 +711,7 @@ window.onload = () => {
             
             if (!isMatchingAnalysis) {
                 // 单方面的文本修改（用户输入、预填充等），清除数据标记并重置状态（视为新的分析阶段）
+                textDirtyForPlainSync = true;
                 visualizationUpdater.clearDataOnTextChange();
                 appStateManager.updateState({ 
                     hasValidData: false,
@@ -697,6 +726,15 @@ window.onload = () => {
             // 注意：文本修改时不清除文件名显示和URL参数（与远程demo行为一致）
             // 只有点击analyze按钮时才会清除这些状态
         });
+        // 失焦：用户改过字则同步纯文本到右侧（busy 时不消费 dirty，下次失焦再试）
+        textFieldNode.addEventListener('blur', () => {
+            if (!textDirtyForPlainSync) return;
+            const s = appStateManager.getState();
+            if (s.isAnalyzing || s.isSemanticSearching || s.isGlobalLoading) return;
+            textDirtyForPlainSync = false;
+            // dirty 表示已清分析数据；以用户编辑为准同步（showPlainText 会负责显示 #all_result）
+            lmf.showPlainText(textInputController.getTextValue());
+        });
     }
     // 初始化时更新业务逻辑相关的按钮状态
     appStateManager.updateButtonStates();
@@ -886,6 +924,15 @@ window.onload = () => {
             mdEl.style('display', 'none');
         }
     };
+    /** 搜索框为空时：语义高亮与 query 对齐（清空） */
+    const onSemanticQuerySelect = () => {
+        appStateManager.updateButtonStates();
+        if ((semanticSearchInput?.value ?? '').length > 0) return;
+        appStateManager.setLastSearchedQuery(null);
+        d3.select('#semantic_match_degree').style('display', 'none');
+        syncSemanticQueryToUrl();
+        visualizationUpdater.clearSemanticState();
+    };
     const semanticSearchController = new SemanticSearchController({
         getQuery: () => semanticSearchInput?.value ?? '',
         getText: () => (textField.property('value') ?? visualizationUpdater.getCurrentData()?.request?.text ?? '').toString(),
@@ -918,7 +965,7 @@ window.onload = () => {
     initQueryHistoryDropdown({
         input: semanticSearchInput,
         dropdownId: 'semantic_search_history_dropdown',
-        onSelect: () => appStateManager.updateButtonStates(),
+        onSelect: onSemanticQuerySelect,
         onHistorySelect: runSemanticSearchOrChunked,
         onRemove: removeSemanticCacheByQuery
     });

client/src/partials/settings-menu-analysis.html

@@ -8,12 +8,6 @@
                                     <span class="settings-menu-label">Token render style:</span>
                                     <div id="token_render_style_dropdown" class="settings-menu-control settings-dropdown-in-menu"></div>
                                 </div>
-                                <div id="disable_info_density_item" class="settings-menu-item settings-menu-row" data-admin-only style="display: none;">
-                                    <span class="settings-menu-label">Disable info density:</span>
-                                    <label class="settings-menu-control settings-menu-checkbox" style="cursor: pointer;">
-                                        <input type="checkbox" id="disable_info_density_toggle">
-                                    </label>
-                                </div>
                                 <div id="weaken_surprisal_color_item" class="settings-menu-item settings-menu-row" data-admin-only style="display: none;">
                                     <span class="settings-menu-label">Weaken surprisal color:</span>
                                     <label class="settings-menu-control settings-menu-checkbox" style="cursor: pointer;">

client/src/privacy-policy.html

@@ -0,0 +1,56 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <title>Info Lens: Semantic Highlight — Privacy Policy</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+</head>
+
+<body style="max-width:700px;margin:40px auto;padding:0 20px;font-family:-apple-system,BlinkMacSystemFont,Segoe UI,Roboto,sans-serif;line-height:1.6;color:#222;">
+    <h1>Privacy Policy for Info Lens: Semantic Highlight</h1>
+    <p><em>Last updated: July 2026</em></p>
+
+    <h2>Data We Process</h2>
+    <p>When you use the extension to search a page, it sends two things to our backend server (hosted at dqy08-infolens.hf.space):</p>
+    <ul>
+        <li>The search query you type</li>
+        <li>The visible text of the article/body content of the page you are currently viewing</li>
+    </ul>
+    <p>This data is sent only when you actively invoke the extension (via the toolbar icon or the Ctrl+Shift+F shortcut) on the page you are viewing at that moment. The extension does not run in the background and does not access any other tabs or pages.</p>
+
+    <h2>How We Use It</h2>
+    <p>The query and page text are used solely to compute semantic similarity and return matching results, which the extension then highlights on the page. No other use is made of this data.</p>
+
+    <h2>Data We Do Not Collect</h2>
+    <p>We do not collect or store: names, email addresses, passwords, financial information, health information, personal communications, or any other personally identifiable information. We do not track your browsing history across pages or sessions.</p>
+
+    <h2>Data Storage &amp; Retention</h2>
+    <ul>
+        <li>Query text and page content are processed transiently to generate search results and are not stored on our server after the response is returned.</li>
+        <li>Our server keeps a temporary, in-memory counter to distinguish visitor sessions for basic operational purposes (e.g., diagnosing issues). This counter is not written to disk, is not linked to any other data, and is cleared whenever the server restarts.</li>
+        <li>Your recent search queries are saved locally in your browser (via the extension's local storage) so you can reuse them. This data never leaves your device.</li>
+    </ul>
+
+    <h2>Third-Party Sharing</h2>
+    <p>We do not share, sell, or transfer any data to third parties. We do not use your data for advertising.</p>
+
+    <h2>Security</h2>
+    <p>All data is transmitted over HTTPS.</p>
+
+    <h2>Permissions</h2>
+    <p>The extension requests the minimum permissions needed for its single purpose (semantic search on the active page):</p>
+    <ul>
+        <li><strong>activeTab / scripting</strong>: to read and highlight text on the page you are currently viewing, only when you invoke the extension</li>
+        <li><strong>storage</strong>: to save your recent search queries locally in your browser</li>
+    </ul>
+    <p>The extension does <strong>not</strong> declare host permissions. Query and page text are sent to our backend by the extension’s background service worker via a standard cross-origin HTTPS request; the backend allows this with CORS. The page you are viewing never talks to our server directly.</p>
+
+    <h2>Changes to This Policy</h2>
+    <p>If our data practices change, we will update this policy and the Chrome Web Store listing accordingly.</p>
+
+    <h2>Contact</h2>
+    <p>For questions about this policy, please contact <a href="mailto:xiaoyundqy@qq.com">xiaoyundqy@qq.com</a>.</p>
+</body>
+
+</html>

client/src/shared/controllers/highlightController.ts

@@ -28,13 +28,14 @@ export class HighlightController {
     }
 
     /**
-     * 清除所有高亮（文本与直方图）
+     * 清除高亮（直方图选中 + 文本）。
+     * @param options.preserveChunkInterval 为 true 时保留 chunk 区间下划线及其 hold/fade
      */
-    public clearHighlights(): void {
+    public clearHighlights(options?: { preserveChunkInterval?: boolean }): void {
         this.options.stats_frac.clearSelection();
         this.options.stats_raw_score_normed?.clearSelection();
         this.options.stats_match_score_progress?.clearSelection();
-        this.options.lmf.clearHighlight();
+        this.options.lmf.clearHighlight(options);
     }
 
     /**

client/src/shared/controllers/semanticSearchController.ts

@@ -18,33 +18,8 @@ import {
     normalizeTokenScores,
     splitTextToChunks,
 } from '../cross/semanticUtils';
+import { codePointLength, utf16IndexToCodePointIndex } from '../cross/mergeTokenSpans';
 import type { signalFitResult } from '../../features/analysis/signalThresholdDetector';
-import { CHUNK_SEARCH_HOLD_MS } from '../vis/constants';
-import * as semanticResultCache from '../cross/semanticResultCache';
-
-function isChunkSemanticallyCached(chunkText: string, query: string, submode?: string): boolean {
-    if (submode === 'hybrid') {
-        return !!semanticResultCache.get(chunkText, query, 'count')
-            && !!semanticResultCache.get(chunkText, query, 'fill_blank');
-    }
-    return !!semanticResultCache.get(chunkText, query, submode);
-}
-
-/** 可中止的短时等待（abort 时提前结束，不抛错） */
-function delayAbortable(ms: number, signal: AbortSignal): Promise<void> {
-    return new Promise((resolve) => {
-        const id = window.setTimeout(resolve, ms);
-        const onAbort = () => {
-            window.clearTimeout(id);
-            resolve();
-        };
-        if (signal.aborted) {
-            onAbort();
-            return;
-        }
-        signal.addEventListener('abort', onAbort, { once: true });
-    });
-}
 
 export interface SemanticSearchControllerDeps {
     getQuery: () => string;
@@ -143,6 +118,10 @@ export class SemanticSearchController {
         }
     }
 
+    /**
+     * 分块搜索（demo）：严格串行——await 分析 → 上色 → 下一块；无预取/hold/follow；结束滚到首个匹配。
+     * 产品决策：站内节奏刻意简化；扩展侧仍保留预取/hold/follow（见 extension/content.js），两边不必对齐。
+     */
     private async runChunked(params: { query: string; text: string; submode: string | undefined; signal: AbortSignal }): Promise<void> {
         const { query, text, submode, signal } = params;
         const chunks = splitTextToChunks(text, SEMANTIC_CHUNK_BYTES);
@@ -163,27 +142,15 @@ export class SemanticSearchController {
         let allFromCache = true;
         let aborted = false;
         let lastChunkFromCache = false;
-        /** 上一块上色后的 hold 期间已预发起的下一块分析 */
-        let pendingNextAnalysis: ReturnType<TextAnalysisAPI['analyzeSemantic']> | null = null;
-        /** hold 结束后已滚到下一块，本轮循环开头无需再滚 */
-        let scrollDoneForIndex: number | null = null;
 
-        const needsAutoScroll = chunks.some((c) => !isChunkSemanticallyCached(c.text, query, submode));
-        if (needsAutoScroll) {
-            this.deps.lmf.beginChunkSearchAutoScroll();
-        }
-        try {
+        const matchThreshold = () => getSemanticMatchThreshold();
+
         for (let i = 0; i < chunks.length; i++) {
             if (signal.aborted) break;
             const chunk = chunks[i];
             d3.select('#semantic_progress').text(`Chunk ${i + 1}/${chunks.length}`).style('display', 'inline-block');
 
-            const res = pendingNextAnalysis
-                ? await pendingNextAnalysis
-                : await this.deps.api.analyzeSemantic(query, chunk.text, { submode, signal });
-            pendingNextAnalysis = null;
-            // 上色/直方图仍以本块返回的 isSemanticFromCache(res) 为准，从首个非缓存块起才刷新 UI。
-            // isChunkSemanticallyCached 仅用于滚动跟随与预取，与 API 读同一套 semanticResultCache。
+            const res = await this.deps.api.analyzeSemantic(query, chunk.text, { submode, signal });
             if (signal.aborted) {
                 aborted = true;
                 break;
@@ -197,7 +164,7 @@ export class SemanticSearchController {
             if (!lastChunkFromCache) allFromCache = false;
             const matchDegree = res.full_match_degree ?? 0;
             maxMatchDegree = Math.max(maxMatchDegree, matchDegree);
-            const matched = matchDegree >= getSemanticMatchThreshold();
+            const matched = matchDegree >= matchThreshold();
             const merged = mergeTokenSpansFullyForRendering(res.token_attention ?? [], chunk.text, {
                 digitMerge: getDigitsMergeEnabled(),
             });
@@ -206,22 +173,22 @@ export class SemanticSearchController {
                 ? normalized
                 : normalized.map((t) => ({ ...t, rawScore: getTokenRawScore(t), score: 0 }));
 
+            // splitTextToChunks.startOffset 为 UTF-16；token/chunkInfos/渲染均为码点
+            const chunkCpStart = utf16IndexToCodePointIndex(text, chunk.startOffset);
+            const chunkCpEnd = chunkCpStart + codePointLength(chunk.text);
             chunkInfos.push({
-                startOffset: chunk.startOffset,
-                endOffset: chunk.startOffset + chunk.text.length,
+                startOffset: chunkCpStart,
+                endOffset: chunkCpEnd,
                 chunkIndex: i,
                 chunkMatchDegree: matchDegree,
             });
             const tokensOffsetAdjusted = tokens.map(t => ({
                 ...t,
-                offset: [t.offset[0] + chunk.startOffset, t.offset[1] + chunk.startOffset] as [number, number],
+                offset: [t.offset[0] + chunkCpStart, t.offset[1] + chunkCpStart] as [number, number],
             }));
             allChunkProcessedTokens.push(...tokensOffsetAdjusted);
+
             if (!lastChunkFromCache) {
-                if (scrollDoneForIndex !== i) {
-                    this.deps.lmf.followSearchingChunk(chunk.startOffset);
-                }
-                scrollDoneForIndex = null;
                 if (!this.deps.visualizationUpdater.handleSemanticResponse(
                     { token_attention: allChunkProcessedTokens, chunkInfos, debug_info: undefined },
                     text,
@@ -231,20 +198,6 @@ export class SemanticSearchController {
                     this.deps.showSemanticError();
                     break;
                 }
-                const nextIndex = i + 1;
-                if (nextIndex < chunks.length) {
-                    const nextChunk = chunks[nextIndex]!;
-                    pendingNextAnalysis = this.deps.api.analyzeSemantic(query, nextChunk.text, { submode, signal });
-                    await delayAbortable(CHUNK_SEARCH_HOLD_MS, signal);
-                    if (signal.aborted) {
-                        aborted = true;
-                        break;
-                    }
-                    if (!isChunkSemanticallyCached(nextChunk.text, query, submode)) {
-                        this.deps.lmf.followSearchingChunk(nextChunk.startOffset);
-                        scrollDoneForIndex = nextIndex;
-                    }
-                }
             }
         }
 
@@ -256,22 +209,13 @@ export class SemanticSearchController {
                     undefined
                 );
             }
-            if (!allFromCache) {
-                await delayAbortable(CHUNK_SEARCH_HOLD_MS, signal);
-            }
             if (!signal.aborted) {
-                const threshold = getSemanticMatchThreshold();
-                const firstMatch = chunkInfos.find((c) => c.chunkMatchDegree >= threshold);
+                const firstMatch = chunkInfos.find((c) => c.chunkMatchDegree >= matchThreshold());
                 if (firstMatch) {
-                    this.deps.lmf.scrollToChunkStart(firstMatch.startOffset);
+                    this.deps.lmf.jumpToChunkHighlight(firstMatch.startOffset, firstMatch.endOffset);
                 }
                 this.deps.finishSemanticSearch(query, maxMatchDegree, allFromCache);
             }
         }
-        } finally {
-            if (needsAutoScroll) {
-                this.deps.lmf.endChunkSearchAutoScroll();
-            }
-        }
     }
 }

client/src/shared/core/responsive.ts

@@ -83,6 +83,19 @@ export const setForceNarrowScreen = (enabled: boolean): void => {
 export const isNarrowScreen = (): boolean =>
   getMobileMediaQuery().matches || getForceNarrowScreen();
 
+/**
+ * 桌面端正文滚动根。
+ * analysis 页把滚动下放到 `#results`（浮条留在 `.right_panel` 外）；其它页仍滚 `.right_panel`。
+ */
+export const getDesktopTextScrollRoot = (): HTMLElement | null => {
+  const results = document.getElementById('results');
+  if (results) {
+    const oy = getComputedStyle(results).overflowY;
+    if (oy === 'auto' || oy === 'scroll') return results;
+  }
+  return document.querySelector('.right_panel') as HTMLElement | null;
+};
+
 /**
  * 检测是否为移动端设备（基于设备能力）
  * 移动端：有触屏支持，且没有鼠标或没有悬浮支持

client/src/shared/core/waitForSmoothScrollEnd.ts

@@ -1,10 +1,20 @@
-/** 等待 smooth scroll 结束：`scrollend` + 超时兜底。返回取消函数。 */
+/**
+ * 等待 smooth scroll 结束。返回取消函数。
+ *
+ * 仅靠 `scrollend` 不够：无位移时浏览器常不触发该事件，会空等到 maxWait。
+ * 语义：滚动已结束，或确认未产生滚动。
+ */
 export function waitForSmoothScrollEnd(
     target: Window | HTMLElement,
     onDone: () => void,
     maxWaitMs = 5000
 ): () => void {
     let settled = false;
+
+    const getTop = () =>
+        target === window ? window.scrollY : (target as HTMLElement).scrollTop;
+    const startTop = getTop();
+
     const settle = () => {
         if (settled) return;
         settled = true;
@@ -13,12 +23,21 @@ export function waitForSmoothScrollEnd(
     };
 
     const onScrollEnd = () => settle();
+
     const dispose = () => {
         window.clearTimeout(timeoutId);
         target.removeEventListener('scrollend', onScrollEnd);
     };
 
     target.addEventListener('scrollend', onScrollEnd, { once: true });
+
+    // 两帧后位置仍未变 → scrollTo 未产生运动，scrollend 不会来
+    requestAnimationFrame(() => {
+        requestAnimationFrame(() => {
+            if (Math.abs(getTop() - startTop) < 1) settle();
+        });
+    });
+
     const timeoutId = window.setTimeout(settle, maxWaitMs);
 
     return () => {

client/src/shared/cross/mergeTokenSpans.ts

@@ -15,6 +15,23 @@ export function codePointLength(text: string): number {
     return Array.from(text || '').length;
 }
 
+/**
+ * UTF-16 码元下标 → Unicode 码点下标（与扩展 content.js `utf16ToCp` 同语义）。
+ * 分块器 `startOffset` 为 UTF-16；API / 渲染 offset 为码点，拼接前须转换。
+ */
+export function utf16IndexToCodePointIndex(text: string, utf16Index: number): number {
+    const s = text || '';
+    const limit = Math.max(0, Math.min(utf16Index, s.length));
+    let i = 0;
+    let cps = 0;
+    while (i < limit) {
+        const cp = s.codePointAt(i)!;
+        i += cp > 0xffff ? 2 : 1;
+        cps += 1;
+    }
+    return cps;
+}
+
 /**
  * 按码点下标 [start, end) 取子串；与校验、合并管线一致。
  */

client/src/shared/cross/queryHistory.ts

@@ -188,16 +188,26 @@ export function initQueryHistoryDropdown(options: InitQueryHistoryDropdownOption
             window.matchMedia('(hover: hover) and (pointer: fine)').matches;
 
         // 列表过滤：与输入框一致不 trim；存盘与选中回填均为完整字符串
+        // 完全匹配当前输入的候选不展示（已是当前值，无选择意义）
         const filter =
             filterHistoryByInput && input ? (input.value ?? '').toLowerCase() : '';
+        const currentLower = input ? (input.value ?? '').toLowerCase() : null;
         const useEntries = getHistoryEntries != null;
         const entryRows = useEntries ? getHistoryEntries!() : null;
         const list = !useEntries ? (getHistoryItems ? getHistoryItems() : load(storageKey)) : null;
         const filteredEntries = entryRows
-            ? entryRows.filter((e) => !filter || e.label.toLowerCase().includes(filter))
+            ? entryRows.filter((e) => {
+                const labelLower = e.label.toLowerCase();
+                if (currentLower !== null && labelLower === currentLower) return false;
+                return !filter || labelLower.includes(filter);
+            })
             : null;
         const filteredStrings = list
-            ? list.filter((s) => !filter || s.toLowerCase().includes(filter))
+            ? list.filter((s) => {
+                const sLower = s.toLowerCase();
+                if (currentLower !== null && sLower === currentLower) return false;
+                return !filter || sLower.includes(filter);
+            })
             : null;
         dropdown.innerHTML = '';
         const filtered = filteredEntries ?? filteredStrings ?? [];

client/src/shared/cross/semanticUtils.ts

@@ -196,7 +196,7 @@ export function mergeTokenSpansFullyForRendering<T extends { offset: [number, nu
     return mergeTokenDigitSpans(overlapped, text);
 }
 
-/** bytesPerChunk：UTF-8 字节数；startOffset：字符索引。 */
+/** bytesPerChunk：UTF-8 字节数；startOffset：UTF-16 码元下标（非码点；拼到 API offset 前须转码点）。扩展侧副本：`extension/splitTextToChunks.js`（改此处请同步）。 */
 export function splitTextToChunks(text: string, bytesPerChunk: number): Array<{ text: string; startOffset: number }> {
     if (bytesPerChunk <= 0) {
         throw new Error("分块字节上限必须大于 0，当前值: " + bytesPerChunk);

client/src/shared/cross/settingsMenuManager.ts

@@ -14,10 +14,6 @@ import { getSemanticAnalysisEnabled, setSemanticAnalysisEnabled } from './semant
 import { getDigitsMergeEnabled, setDigitsMergeEnabled } from './digitsMergeManager';
 import { getForceNarrowScreen, setForceNarrowScreen, FORCE_NARROW_CHANGE_EVENT } from '../core/responsive';
 import { getSemanticMatchThreshold } from './semanticThresholdManager';
-import {
-    getInfoDensityRenderDisabled,
-    setInfoDensityRenderDisabled,
-} from '../../features/analysis/infoDensityRenderManager';
 import {
     getSurprisalColorWeakened,
     setSurprisalColorWeakened,
@@ -48,7 +44,6 @@ export class SettingsMenuManager {
     private semanticThresholdInput: d3.Selection<HTMLInputElement, unknown, HTMLElement, any>;
     private semanticThresholdItem: d3.Selection<HTMLElement, unknown, HTMLElement, any>;
     private semanticSubmodeRow: d3.Selection<HTMLElement, unknown, HTMLElement, any>;
-    private disableInfoDensityToggle: d3.Selection<HTMLInputElement, unknown, HTMLElement, any>;
     private weakenSurprisalColorToggle: d3.Selection<HTMLInputElement, unknown, HTMLElement, any>;
     private themeDropdownContainer: d3.Selection<Element, unknown, HTMLElement, any>;
     private adminManager: AdminManager;
@@ -86,7 +81,6 @@ export class SettingsMenuManager {
         this.semanticThresholdInput = d3.select<HTMLInputElement, any>('#semantic_threshold_input');
         this.semanticThresholdItem = d3.select<HTMLElement, any>('#semantic_threshold_item');
         this.semanticSubmodeRow = d3.select<HTMLElement, any>('#semantic_submode_row');
-        this.disableInfoDensityToggle = d3.select<HTMLInputElement, any>('#disable_info_density_toggle');
         this.weakenSurprisalColorToggle = d3.select<HTMLInputElement, any>('#weaken_surprisal_color_toggle');
         this.themeDropdownContainer = d3.select('#theme_dropdown');
         this.adminManager = adminManager;
@@ -149,23 +143,12 @@ export class SettingsMenuManager {
                 setSemanticAnalysisEnabled(enabled);
                 this.updateSemanticThresholdVisibility();
                 this.updateSemanticSubmodeRowVisibility();
-                setInfoDensityRenderDisabled(enabled);
-                this.setDisableInfoDensity(enabled);
-                window.dispatchEvent(new CustomEvent('info-density-render-change'));
                 if (this.callbacks.onSemanticAnalysisToggle) {
                     this.callbacks.onSemanticAnalysisToggle(enabled);
                 }
             });
         }
 
-        if (this.menuContext === 'analysis' && this.disableInfoDensityToggle.node()) {
-            this.disableInfoDensityToggle.on('change', () => {
-                const disabled = (this.disableInfoDensityToggle.node() as HTMLInputElement)?.checked || false;
-                setInfoDensityRenderDisabled(disabled);
-                window.dispatchEvent(new CustomEvent('info-density-render-change'));
-            });
-        }
-
         if (this.menuContext === 'analysis' && this.weakenSurprisalColorToggle.node()) {
             this.weakenSurprisalColorToggle.on('change', () => {
                 const weakened = (this.weakenSurprisalColorToggle.node() as HTMLInputElement)?.checked || false;
@@ -210,9 +193,6 @@ export class SettingsMenuManager {
         if (this.menuContext === 'analysis' && this.semanticThresholdInput.node()) {
             this.setSemanticThresholdValue(getSemanticMatchThreshold());
         }
-        if (this.menuContext === 'analysis' && this.disableInfoDensityToggle.node()) {
-            this.setDisableInfoDensity(getInfoDensityRenderDisabled());
-        }
         if (this.menuContext === 'analysis' && this.weakenSurprisalColorToggle.node()) {
             this.setWeakenSurprisalColor(getSurprisalColorWeakened());
         }
@@ -275,9 +255,6 @@ export class SettingsMenuManager {
             this.setSemanticThresholdValue(getSemanticMatchThreshold());
             this.updateSemanticThresholdVisibility();
         }
-        if (this.menuContext === 'analysis' && this.disableInfoDensityToggle.node()) {
-            this.setDisableInfoDensity(getInfoDensityRenderDisabled());
-        }
         if (this.menuContext === 'analysis' && this.weakenSurprisalColorToggle.node()) {
             this.setWeakenSurprisalColor(getSurprisalColorWeakened());
         }
@@ -340,16 +317,6 @@ export class SettingsMenuManager {
         }
     }
 
-    /**
-     * 设置 disable info density 的初始状态
-     */
-    public setDisableInfoDensity(disabled: boolean): void {
-        const checkbox = this.disableInfoDensityToggle.node() as HTMLInputElement | null;
-        if (checkbox) {
-            checkbox.checked = disabled;
-        }
-    }
-
     public setWeakenSurprisalColor(weakened: boolean): void {
         const checkbox = this.weakenSurprisalColorToggle.node() as HTMLInputElement | null;
         if (checkbox) {

client/src/shared/lang/translations.ts

@@ -486,8 +486,9 @@ export const translations: Translations = {
             '无法使用加密API（crypto.subtle），保存到本地缓存功能不可用。',
         'URL text extraction failed': 'URL 文本提取失败',
         'Semantic analysis failed': '语义分析失败',
-        'Semantic Query(Beta)': '语义查询(Beta)',
+        'Semantic Find(Beta)': '语义查找(Beta)',
         'Enter query question or topic': '请输入查询问题或主题',
+        'Semantic find': '语义查找',
         'Tokenizer results inconsistent: semantic and info-density token boundaries differ.': 'Tokenizer 结果不一致：语义分析与信息密度的 token 边界存在差异，属预期外情况。',
         'No data to analyze, please analyze text first': '没有可分析的数据，请先分析文本',
         'User cancelled file selection': '用户取消了文件选择',

client/src/shared/vis/GLTR_Text_Box.ts

@@ -10,11 +10,10 @@ import {TokenPositionCalculator} from "./TokenPositionCalculator";
 import {ResizeHandler} from "./ResizeHandler";
 import {TokenFragmentRect, HighlightStyle} from "./types";
 import { waitForSmoothScrollEnd } from '../core/waitForSmoothScrollEnd';
-import { CHUNK_SEARCH_FOLLOW_VIEWPORT_Y_RATIO, HIGHLIGHT_CONSTANTS } from './constants';
+import { HIGHLIGHT_CONSTANTS } from './constants';
 import {ScrollbarMinimap} from "./ScrollbarMinimap";
-import {isNarrowScreen} from "../core/responsive";
+import {isNarrowScreen, getDesktopTextScrollRoot} from "../core/responsive";
 import {getTokenRenderStyle} from "../cross/tokenRenderStyle";
-import { getInfoDensityRenderDisabled } from "../../features/analysis/infoDensityRenderManager";
 import type { FrontendToken } from "../../shared/api/GLTR_API";
 
 /**
@@ -106,10 +105,8 @@ export class GLTR_Text_Box extends VComponent<FrontendAnalyzeResult> {
         surprisalColorMax: undefined as number | undefined,
         /** 若设置则仅覆盖 SVG 底色的 density/classic；未设置则与全局 getTokenRenderStyle() 一致 */
         overlayTokenRenderStyle: undefined as 'density' | 'classic' | undefined,
-        /** 为 true 时 SVG 底色不受全局「关闭信息密度」影响（如 Chat 需始终显示 token surprisal 底色） */
-        overlayIgnoreGlobalInfoDensityDisable: false,
         /**
-         * 为 true 时本实例始终不画信息密度/classic 底层（透明），不受全局开关与 overlayIgnoreGlobalInfoDensityDisable 影响。
+         * 为 true 时本实例始终不画信息密度/classic 底层（透明）。
          * 用于仅展示语义叠加层（如归因页）而无需伪造 real_topk。
          */
         overlayForceDisableInfoDensityRender: false,
@@ -122,13 +119,7 @@ export class GLTR_Text_Box extends VComponent<FrontendAnalyzeResult> {
 
     /** SVG 信息密度/classic 底色是否应关闭（透明） */
     private getOverlayDisableInfoDensityRender(): boolean {
-        if (this.options.overlayForceDisableInfoDensityRender) {
-            return true;
-        }
-        if (this.options.overlayIgnoreGlobalInfoDensityDisable) {
-            return false;
-        }
-        return getInfoDensityRenderDisabled();
+        return !!this.options.overlayForceDisableInfoDensityRender;
     }
 
     /**
@@ -174,9 +165,6 @@ export class GLTR_Text_Box extends VComponent<FrontendAnalyzeResult> {
     private highlightManager?: HighlightManager;
     private chunkScrollEndCancel: (() => void) | undefined;
     private chunkHighlightHoldTimer: number | undefined;
-    /** 分块语义搜索：用户已手动滚动，后续不再自动跟随 */
-    private chunkSearchAutoScrollUserCancelled = false;
-    private chunkSearchAutoScrollCleanup: (() => void) | undefined;
     
     // 下划线元素缓存，用于第二个直方图的高亮样式（由HighlightManager管理，但需要在这里初始化）
     private underlineCache: Map<string, SVGLineElement> = new Map();
@@ -202,7 +190,6 @@ export class GLTR_Text_Box extends VComponent<FrontendAnalyzeResult> {
         }
     };
     private _onTokenRenderStyleChange = (): void => this._refreshBaseRectColorsOrFullRender();
-    private _onInfoDensityRenderChange = (): void => this._refreshBaseRectColorsOrFullRender();
     private _onSurprisalColorWeakenChange = (): void => {
         this._refreshBaseRectColorsOrFullRender();
         if (this.options.enableMinimap && this.cachedPositions && this.currentRenderData) {
@@ -251,7 +238,6 @@ export class GLTR_Text_Box extends VComponent<FrontendAnalyzeResult> {
         // 监听主题变化
         this.setupThemeListener();
         window.addEventListener('token-render-style-change', this._onTokenRenderStyleChange);
-        window.addEventListener('info-density-render-change', this._onInfoDensityRenderChange);
         window.addEventListener('surprisal-color-weaken-change', this._onSurprisalColorWeakenChange);
 
         // 初始化颜色scale
@@ -369,11 +355,12 @@ export class GLTR_Text_Box extends VComponent<FrontendAnalyzeResult> {
                 this.cachedPositionsTokenCount = rd.bpe_strings.length;
             }
 
-            // Step 3: 更新本 chunk 范围内的语义颜色
+            // Step 3: 语义颜色。仅「chunk 流式追加」时只刷最新 chunk；同 token 数（如 color source 切换）必须全量刷，否则前文颜色会滞后
             const latestChunk = rdExt.chunkInfos?.[rdExt.chunkInfos.length - 1];
-            const fromTokenIndex = latestChunk
-                ? Math.max(0, rd.bpe_strings.findIndex(t => t.offset[0] >= latestChunk.startOffset))
-                : 0;
+            const fromTokenIndex =
+                chunkAppendOnly && latestChunk
+                    ? Math.max(0, rd.bpe_strings.findIndex(t => t.offset[0] >= latestChunk.startOffset))
+                    : 0;
             this.svgOverlayManager!.updateSemanticColors(colorScores!, fromTokenIndex);
 
             // chunk 增量渲染路径也需要同步刷新 minimap，否则会出现刷新滞后
@@ -659,14 +646,15 @@ export class GLTR_Text_Box extends VComponent<FrontendAnalyzeResult> {
     }
 
     /**
-     * 仅显示文本内容，不渲染颜色标记
-     * 用于在等待后端返回时立即显示文本，提升用户体验
-     * @param text 要显示的文本内容
+     * 清空可视化 DOM，仅铺纯文本层（不改 loading / currentRenderData）
      */
-    public setTextOnly(text: string): void {
+    private applyPlainTextDom(text: string): void {
         const baseNode = this.base.node();
         if (!baseNode) return;
 
+        // DOM 将重建，先清掉高亮状态，避免后续流式更新误保留旧 chunk 区间
+        this.clearHighlight();
+
         // 文本切换（如 demo 切换）期间先清空 minimap，避免显示旧数据
         if (this.options.enableMinimap && this.minimapManager) {
             this.minimapManager.clear();
@@ -705,11 +693,30 @@ export class GLTR_Text_Box extends VComponent<FrontendAnalyzeResult> {
         } else {
             this.createLoadingOverlay();
         }
+    }
 
-        // 显示加载状态
+    /**
+     * 仅显示文本内容，不渲染颜色标记
+     * 用于在等待后端返回时立即显示文本，提升用户体验
+     * @param text 要显示的文本内容
+     */
+    public setTextOnly(text: string): void {
+        this.applyPlainTextDom(text);
         this.showLoading();
     }
 
+    /**
+     * 仅显示纯文本（无 loading、无分析结果缓存），用于输入失焦同步等非分析场景。
+     * 负责把分析结果区（#all_result）重新显示：调用方在改字时可能已将其藏起。
+     */
+    public showPlainText(text: string): void {
+        this.currentRenderData = undefined;
+        this.applyPlainTextDom(text);
+        this.hideLoading();
+        // 无节点时（非 analysis 页）为空选，no-op
+        d3.select('#all_result').style('opacity', 1).style('display', null);
+    }
+
     /**
      * 显示加载状态
      */
@@ -1083,7 +1090,7 @@ export class GLTR_Text_Box extends VComponent<FrontendAnalyzeResult> {
 
     /**
      * 计算系统经典滚动条的宽度
-     * 通过 right_panel 和 LMF 的宽度差来判断滚动条是否占用布局空间
+     * 通过正文滚动根与 LMF 的宽度差判断滚动条是否占用布局空间
      * @returns 滚动条宽度（px），如果为0则表示使用覆盖式滚动条或无滚动条
      */
     private calculateTraditionalScrollbarWidth(): number {
@@ -1092,19 +1099,15 @@ export class GLTR_Text_Box extends VComponent<FrontendAnalyzeResult> {
             return 0;
         }
 
-        const rightPanel = document.querySelector('.right_panel') as HTMLElement;
-        if (!rightPanel) {
+        const scrollRoot = getDesktopTextScrollRoot();
+        if (!scrollRoot) {
             return 0;
         }
 
-        // right_panel 的 offsetWidth（包含滚动条，如果滚动条占用布局空间）
-        const rightPanelWidth = rightPanel.offsetWidth;
-        // LMF 的 offsetWidth（包含 padding 和 border，但不包含滚动条）
+        const scrollRootWidth = scrollRoot.offsetWidth;
         const lmfWidth = baseNode.offsetWidth;
-        // 计算滚动条宽度：right_panel 宽度 - LMF 宽度
-        const scrollbarWidth = rightPanelWidth - lmfWidth;
+        const scrollbarWidth = scrollRootWidth - lmfWidth;
 
-        // 返回滚动条宽度（如果小于等于0，表示使用覆盖式滚动条或无滚动条）
         return scrollbarWidth > 0 ? scrollbarWidth : 0;
     }
 
@@ -1173,7 +1176,6 @@ export class GLTR_Text_Box extends VComponent<FrontendAnalyzeResult> {
         // 清理SVG引用
         this.currentSvgOverlay = undefined;
         window.removeEventListener('token-render-style-change', this._onTokenRenderStyleChange);
-        window.removeEventListener('info-density-render-change', this._onInfoDensityRenderChange);
         window.removeEventListener('surprisal-color-weaken-change', this._onSurprisalColorWeakenChange);
 
         // 调用父类的destroy方法
@@ -1281,53 +1283,11 @@ export class GLTR_Text_Box extends VComponent<FrontendAnalyzeResult> {
         this.highlightManager.setCharIntervalUnderlines(segments);
     }
 
-    /** 分块语义搜索开始：wheel / 触摸即视为用户接管滚动 */
-    beginChunkSearchAutoScroll(): void {
-        this.endChunkSearchAutoScroll();
-        this.chunkSearchAutoScrollUserCancelled = false;
-
-        const container = isNarrowScreen()
-            ? window
-            : (document.querySelector('.right_panel') as HTMLElement | null);
-        if (!container) return;
-
-        const opts = { passive: true, capture: true } as const;
-        const onUserScroll = () => {
-            if (this.chunkSearchAutoScrollUserCancelled) return;
-            this.chunkSearchAutoScrollUserCancelled = true;
-            this.chunkScrollEndCancel?.();
-            this.chunkScrollEndCancel = undefined;
-        };
-
-        container.addEventListener('wheel', onUserScroll, opts);
-        container.addEventListener('touchstart', onUserScroll, opts);
-        this.chunkSearchAutoScrollCleanup = () => {
-            container.removeEventListener('wheel', onUserScroll, opts);
-            container.removeEventListener('touchstart', onUserScroll, opts);
-        };
-    }
-
-    endChunkSearchAutoScroll(): void {
-        this.chunkSearchAutoScrollCleanup?.();
-        this.chunkSearchAutoScrollCleanup = undefined;
-        this.chunkSearchAutoScrollUserCancelled = false;
-    }
-
     /** 滚到 chunk 起点（分析结束、直方图 bin 点击，视口 0.2） */
     scrollToChunkStart(charOffset: number, onScrollEnd?: () => void): void {
         this.scrollToUnicodeCharOffset(Math.max(0, Math.floor(charOffset)), onScrollEnd);
     }
 
-    /** 分块语义搜索进行中：滚动跟随当前 chunk 起点（视口 0.6） */
-    followSearchingChunk(charOffset: number): void {
-        if (this.chunkSearchAutoScrollUserCancelled) return;
-        this.scrollToUnicodeCharOffset(
-            Math.max(0, Math.floor(charOffset)),
-            undefined,
-            CHUNK_SEARCH_FOLLOW_VIEWPORT_Y_RATIO
-        );
-    }
-
     /**
      * semantic match per chunk：高亮区间 → 滚到 chunk 起点 → 滚完保持 → 淡出
      */
@@ -1412,7 +1372,7 @@ export class GLTR_Text_Box extends VComponent<FrontendAnalyzeResult> {
     }
 
     /**
-     * 滚动至 Unicode 偏移；桌面滚动 `.right_panel`，窄屏为 `window`
+     * 滚动至 Unicode 偏移；桌面滚正文滚动根（analysis 为 `#results`，其它页多为 `.right_panel`），窄屏为 `window`
      * @param viewportYRatio 目标点在视口中的纵向位置（0=顶部，1=底部），默认 0.2
      */
     scrollToUnicodeCharOffset(charOffset: number, onScrollEnd?: () => void, viewportYRatio = 0.2): void {
@@ -1457,7 +1417,7 @@ export class GLTR_Text_Box extends VComponent<FrontendAnalyzeResult> {
                 return;
             }
 
-            const panel = document.querySelector('.right_panel') as HTMLElement | null;
+            const panel = getDesktopTextScrollRoot();
             if (!panel) {
                 onScrollEnd?.();
                 return;
@@ -1497,15 +1457,23 @@ export class GLTR_Text_Box extends VComponent<FrontendAnalyzeResult> {
     }
 
     /**
-     * 清除所有高亮
+     * 清除高亮。
+     * @param options.preserveChunkInterval 为 true 时保留 chunk 区间下划线及其 hold/fade（语义流式更新用）
      */
-    clearHighlight() {
-        this.cancelChunkHighlightFade();
+    clearHighlight(options?: { preserveChunkInterval?: boolean }) {
+        const preserve = options?.preserveChunkInterval === true;
+        if (!preserve) {
+            this.cancelChunkHighlightFade();
+            this._current.chunkCharRange = null;
+        }
         this._current.highlightedIndices.clear();
-        this._current.chunkCharRange = null;
 
         if (this.highlightManager) {
-            this.highlightManager.clearHighlight();
+            if (preserve) {
+                this.highlightManager.clearTokenHighlights();
+            } else {
+                this.highlightManager.clearHighlight();
+            }
         }
     }
 

client/src/shared/vis/HighlightManager.ts

@@ -157,6 +157,11 @@ export class HighlightManager {
         this.removeIntervalSvgLines();
     }
 
+    /** 仅清除 token 高亮，保留 chunk 区间下划线及其 fade */
+    clearTokenHighlights(): void {
+        this.clearRectHighlightsOnly();
+    }
+
     /** 仅清除 token 矩形上的高亮样式（保留字符区间线，供内部组合使用） */
     private clearRectHighlightsOnly(): void {
         this.rectCache.forEach(({ rect }, rectKey) => {

client/src/shared/vis/SvgOverlayManager.ts

@@ -165,7 +165,7 @@ export class SvgOverlayManager {
 
     /**
      * 更新 base rect（信息密度/classic 底色）颜色，不重建 SVG。
-     * 用于 Disable info density / token render style 切换时，增量路径下刷新底色。
+     * 用于 token render style 切换时，增量路径下刷新底色。
      */
     updateBaseRectColors(
         rd: FrontendAnalyzeResult,

client/src/shared/vis/ToolTip.ts

@@ -312,7 +312,7 @@ export class ToolTip {
     
     /**
      * 更新tooltip内容
-     * 统一结构：语义区块（上） + 分隔线 + 信息密度区块（下，含汇总指标 + top-k 表格）
+     * 结构：语义区块（上）与信息密度区块（下）按数据有无拼接；互斥模式下通常只出现一侧
      */
     private _updateContent(ri: GLTR_RenderItem, augment?: ToolTipUpdateAugment): void {
         const { selectedColor, detailColor, valueColor } = this.themeColors;

client/src/shared/vis/constants.ts

@@ -19,14 +19,8 @@ export const HIGHLIGHT_CONSTANTS = {
     /** 下划线宽度 */
     UNDERLINE_WIDTH: '2',
     /** chunk 进度图跳转：滚动结束后保持高亮时长 */
-    CHUNK_HIGHLIGHT_HOLD_MS: 1000,
+    CHUNK_HIGHLIGHT_HOLD_MS: 200,
     /** chunk 进度图跳转：保持结束后的淡出时长 */
     CHUNK_HIGHLIGHT_FADE_MS: 1400,
 } as const;
 
-/** 分块语义搜索：每块上色后、滚到下一块前的停留时长 */
-export const CHUNK_SEARCH_HOLD_MS = 400;
-
-/** 分块语义搜索跟随：chunk 起点在视口中的纵向位置（0=顶，1=底） */
-export const CHUNK_SEARCH_FOLLOW_VIEWPORT_Y_RATIO = 0.6;
-

client/src/webpack.config.js

@@ -173,6 +173,7 @@ module.exports = {
                 copyHtmlWithIncludesAndPageMeta('chat.html', 'chat.html', 'chat'),
                 copyHtmlWithIncludesAndPageMeta('attribution.html', 'attribution.html', 'attribution'),
                 copyHtmlWithIncludesAndPageMeta('causal_flow.html', 'causal_flow.html', 'causalFlow'),
+                { from: 'privacy-policy.html', to: 'privacy-policy.html' },
             ]
         }),
         new GenAttributeDemoManifestPlugin(),

extension/README.md

@@ -0,0 +1,69 @@
+# InfoLens Semantic Find（可行性 demo）
+
+Chrome MV3 扩展：对当前网页做语义检索，叠层高亮（chunk 下划线 + token 染色）。  
+与 `backend/`、`client/` 同仓并列；只消费 API + 操作 DOM。
+
+Find bar 权威源在 `extension/ui/`，站内为手工副本。挂 Shadow DOM；主题跟系统 `prefers-color-scheme`。  
+正文：Readability 定根 + DOM 映回；失败即放弃。权限：`activeTab` + 手势后再注入（无 `<all_urls>`）。
+
+---
+
+## 开发
+
+```bash
+./extension/dev-env.sh prod   # 或 local；生成 gitignore 的 config.js（clone 后至少一次）
+```
+
+Chrome → `chrome://extensions` → 开发者模式 → 加载已解压 → 选 `extension/`（绿角标 = dev 版）。  
+普通 `https` 页 → 工具栏图标或 `Ctrl+Shift+F`（Mac `⌘⇧F`）→ 输入 query → Enter。
+
+改配置改源头，再生成（**不要手改** `config.js`）：
+
+```bash
+./extension/dev-env.sh local   # apiBase=127.0.0.1:5001（需本地后端，且未传 --no_cors）
+./extension/dev-env.sh prod    # apiBase=HF Spaces
+```
+
+改完扩展页「重新加载」。浮条改 `extension/ui/`，需站内一致再手工同步 client。
+
+### 上架
+
+```bash
+./extension/pack.sh
+```
+
+临时目录打 zip（正式图标 + `config.prod.js` → 包内 `config.js`），不改工作树。产出在 `extension/dist/`（gitignore）。
+
+### 配置字段
+
+| 字段 | 含义 |
+|------|------|
+| `apiBase` | API 根；local / prod 由 `dev-env.sh` 切换 |
+| `chunkBytes` | 分块字节上限 |
+| `maxChunks` | demo 最多请求块数 |
+| `matchThreshold` | 计入 ↑↓ 的 match 阈值 |
+| `submode` | 默认 `hybrid`（前端 count→fill_blank） |
+| `pwScorePercentile` | 简化 pw 分位 τ（默认 0.9） |
+| `domDebug` | `true` 只划正文范围 |
+| `followSearching` | `true` 全程跟随最新 chunk |
+
+### 排查：`Frame with ID 0 was removed`
+
+受限页 / 未加载完 / 标签休眠。换普通文章页 → 加载完 → 重载扩展 → 再点图标。
+
+---
+
+## 目录要点
+
+```text
+manifest.json          # unpacked；图标 icons/dev/
+icons/icon*.png        # 上架正式图标
+pack.sh / dev-env.sh
+config.prod.js         # 上架默认（源头）；pack 打进包
+config.local.js        # 本地（源头）
+config.js              # gitignore；dev-env 生成
+ui/                    # Find bar 权威源
+articleRoot.js         # Readability 定根
+splitTextToChunks.js / mergeTokenSpans.js   # SYNC ← client
+vendor/Readability.js
+```

extension/articleRoot.js

@@ -0,0 +1,85 @@
+/**
+ * 定根：Chrome 纯文本查看器（body 下仅一个 <pre>）直接用 body；
+ * 其余走 Readability（预打标 → clone 上跑算法 → data-il-rid 映回）。
+ * Readability 失败抛错，不回退启发式。
+ */
+(() => {
+  const ATTR = 'data-il-rid';
+
+  /** 扩展注入的宿主，不算页面内容子节点 */
+  function isExtensionHost(el) {
+    const id = el.id;
+    return id === 'il-find-root' || id === 'il-overlay-host';
+  }
+
+  /**
+   * Chrome/WebKit 对 text/plain 等的包装：<body><pre>…</pre></body>
+   * @param {Document} doc
+   * @returns {Element | null}
+   */
+  function findPlainTextRoot(doc) {
+    const body = doc.body;
+    if (!body) return null;
+    const kids = [];
+    for (const el of body.children) {
+      if (!isExtensionHost(el)) kids.push(el);
+    }
+    if (kids.length === 1 && kids[0].tagName === 'PRE') return body;
+    return null;
+  }
+
+  function mark(doc) {
+    if (!doc.body) return;
+    let seq = 0;
+    for (const el of doc.body.querySelectorAll('*')) {
+      el.setAttribute(ATTR, String(++seq));
+    }
+  }
+
+  function unmark(doc) {
+    if (!doc.body) return;
+    for (const el of doc.body.querySelectorAll(`[${ATTR}]`)) {
+      el.removeAttribute(ATTR);
+    }
+  }
+
+  /**
+   * @param {Document} doc
+   * @returns {Element}
+   */
+  function findArticleRoot(doc) {
+    if (!doc?.body) {
+      throw new Error('document.body missing');
+    }
+
+    const plain = findPlainTextRoot(doc);
+    if (plain) return plain;
+
+    if (typeof Readability !== 'function') {
+      throw new Error('Readability missing — inject vendor/Readability.js first');
+    }
+
+    mark(doc);
+    try {
+      const clone = doc.cloneNode(true);
+      const reader = new Readability(clone);
+      const parsed = reader.parse();
+      if (!parsed) {
+        throw new Error('Readability: parse failed');
+      }
+      const rid = reader._ilArticleRootRid;
+      if (rid == null || rid === '') {
+        throw new Error('Readability: no mappable article root');
+      }
+      const root = doc.querySelector(`[${ATTR}="${CSS.escape(String(rid))}"]`);
+      if (!root) {
+        throw new Error(`Readability: live root not found (rid=${rid})`);
+      }
+      return root;
+    } finally {
+      unmark(doc);
+    }
+  }
+
+  globalThis.IL_findArticleRoot = findArticleRoot;
+})();

extension/background.js

@@ -0,0 +1,186 @@
+/**
+ * 工具栏点击 → 注入 content（activeTab 手势）。
+ * API 走 SW fetch：不声明 host_permissions，依赖服务端 CORS（见 run.py CORSMiddleware）。
+ */
+
+importScripts('config.js');
+
+const CONTENT_CSS = ['content.css'];
+const CONTENT_JS = [
+  'config.js',
+  'vendor/Readability.js',
+  'articleRoot.js',
+  'splitTextToChunks.js',
+  'mergeTokenSpans.js',
+  'content.js',
+];
+
+function isRestrictedUrl(url) {
+  if (!url) return true;
+  let u;
+  try {
+    u = new URL(url);
+  } catch {
+    return true;
+  }
+  const proto = u.protocol;
+  if (
+    proto === 'chrome:' ||
+    proto === 'chrome-extension:' ||
+    proto === 'chrome-search:' ||
+    proto === 'chrome-untrusted:' ||
+    proto === 'devtools:' ||
+    proto === 'edge:' ||
+    proto === 'about:' ||
+    proto === 'view-source:'
+  ) {
+    return true;
+  }
+  // Chrome PDF viewer / Web Store：主 frame 常无法注入
+  if (proto === 'file:' && /\.pdf$/i.test(u.pathname)) return true;
+  if (/\.pdf$/i.test(u.pathname)) return true;
+  if (u.hostname === 'chrome.google.com' && u.pathname.startsWith('/webstore')) return true;
+  if (u.hostname === 'chromewebstore.google.com') return true;
+  return false;
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+/** 等到 status=complete；已 complete 则立即返回最新 tab */
+async function waitTabComplete(tabId, timeoutMs = 20000) {
+  const cur = await chrome.tabs.get(tabId);
+  if (cur.status === 'complete') return cur;
+
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      chrome.tabs.onUpdated.removeListener(onUpdated);
+      reject(new Error(`tab ${tabId} load timeout (${timeoutMs}ms)`));
+    }, timeoutMs);
+
+    function onUpdated(id, info) {
+      if (id !== tabId || info.status !== 'complete') return;
+      clearTimeout(timer);
+      chrome.tabs.onUpdated.removeListener(onUpdated);
+      chrome.tabs.get(tabId).then(resolve, reject);
+    }
+    chrome.tabs.onUpdated.addListener(onUpdated);
+  });
+}
+
+function isTransientFrameError(err) {
+  const msg = String(err?.message || err);
+  return (
+    msg.includes('Frame with ID') ||
+    msg.includes('No frame with id') ||
+    msg.includes('Frame does not exist') ||
+    msg.includes('The tab was closed') ||
+    msg.includes('cannot be scripted now')
+  );
+}
+
+async function injectOnce(tabId) {
+  // 显式 frameIds:[0]，避免对已消失子 frame 误操作；主文档未就绪时由上层重试
+  await chrome.scripting.insertCSS({
+    target: { tabId, frameIds: [0] },
+    files: CONTENT_CSS,
+  });
+  await chrome.scripting.executeScript({
+    target: { tabId, frameIds: [0] },
+    files: CONTENT_JS,
+  });
+}
+
+async function injectWithRetry(tabId) {
+  let lastErr;
+  for (let attempt = 1; attempt <= 4; attempt++) {
+    try {
+      const tab = await waitTabComplete(tabId);
+      if (isRestrictedUrl(tab.url)) {
+        throw new Error(`restricted page: ${tab.url || '(no url)'}`);
+      }
+      // 丢弃休眠的 tab：先激活再注
+      if (tab.discarded) {
+        await chrome.tabs.reload(tabId);
+        await waitTabComplete(tabId);
+      }
+      await injectOnce(tabId);
+      return tab;
+    } catch (err) {
+      lastErr = err;
+      if (!isTransientFrameError(err) || attempt === 4) throw err;
+      console.warn(`[InfoLens] inject attempt ${attempt} failed, retry…`, err?.message || err);
+      await sleep(100 * attempt);
+    }
+  }
+  throw lastErr;
+}
+
+async function setBadgeError(brief) {
+  try {
+    await chrome.action.setBadgeBackgroundColor({ color: '#c0392b' });
+    await chrome.action.setBadgeText({ text: '!' });
+    await chrome.action.setTitle({ title: `InfoLens: ${brief}` });
+    setTimeout(() => {
+      chrome.action.setBadgeText({ text: '' });
+      chrome.action.setTitle({ title: 'InfoLens Semantic Find' });
+    }, 5000);
+  } catch {
+    /* ignore */
+  }
+}
+
+async function activateTab(tab) {
+  if (!tab?.id) return;
+
+  // 手势当下立刻读一次 url；无 url 时仍尝试 get（activeTab 授权后）
+  try {
+    const fresh = await chrome.tabs.get(tab.id);
+    if (isRestrictedUrl(fresh.url || tab.url)) {
+      const url = fresh.url || tab.url || '(empty)';
+      console.warn('[InfoLens] cannot run on this page:', url);
+      await setBadgeError('bad page');
+      return;
+    }
+
+    const okTab = await injectWithRetry(tab.id);
+    console.info('[InfoLens] injected into', okTab.url);
+    await chrome.action.setBadgeText({ text: '' });
+  } catch (err) {
+    console.error('[InfoLens] inject failed', err);
+    console.error('[InfoLens] tip: use a normal http(s) article tab (not chrome://, PDF, Web Store); reload extension, then click again after the page finishes loading.');
+    await setBadgeError('inject');
+  }
+}
+
+chrome.action.onClicked.addListener(activateTab);
+
+chrome.commands.onCommand.addListener(async (command) => {
+  if (command !== 'toggle-find') return;
+  const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
+  await activateTab(tab);
+});
+
+chrome.runtime.onMessage.addListener((msg, _sender, sendResponse) => {
+  if (msg?.type !== 'il-analyze-semantic') return;
+  (async () => {
+    try {
+      const apiBase = msg.apiBase || IL_CONFIG.apiBase;
+      const res = await fetch(`${String(apiBase).replace(/\/$/, '')}/api/analyze-semantic`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(msg.body),
+      });
+      const data = await res.json().catch(() => ({}));
+      if (!res.ok || data?.success === false) {
+        const detail = data?.message || data?.detail || `HTTP ${res.status}`;
+        throw new Error(detail);
+      }
+      sendResponse({ ok: true, data });
+    } catch (err) {
+      sendResponse({ ok: false, error: String(err?.message || err) });
+    }
+  })();
+  return true;
+});

extension/config.local.js

@@ -0,0 +1,35 @@
+/**
+ * 本地调试变体（源头）：apiBase 打本地后端；用 dev-env.sh local 生成 config.js。
+ * 除 apiBase（及有意的本地差异如 maxChunks）外与 config.prod.js 对齐。
+ */
+var IL_CONFIG = {
+  apiBase: 'http://127.0.0.1:5001',
+  /**
+   * SYNC: client/src/shared/core/constants.ts → SEMANTIC_CHUNK_BYTES；算法见 splitTextToChunks.js
+   * 已知问题：见 config.prod.js 同名字段注释（与后端 token 截断无联动，密集内容会漏检）。
+   */
+  chunkBytes: 800,
+  /** demo 最多请求的 chunk 数，避免一页打爆本地推理 */
+  maxChunks: 32,
+  /** SYNC: client/src/shared/core/constants.ts → SEMANTIC_MATCH_THRESHOLD */
+  matchThreshold: 0.1,
+  /** SYNC: analysis 默认 hybrid（前端组合 count→fill_blank，非后端枚举值） */
+  submode: 'hybrid',
+  /**
+   * SYNC 近似：
+   * - 站内 τ：signalThresholdDetector（失败回退 P90，见 textStatistics.computeP90）
+   * - 站内 pw：visualizationUpdater.ts → pw_score = score×P_pw×matchDegree
+   * 扩展无 signal-fit，用该分位作 τ（默认 0.9 ≈ P90）；见 content.js prepareChunkTokens
+   */
+  pwScorePercentile: 0.9,
+  /**
+   * DOM 调试：true = 点击抽正文并下划线；再点取消；
+   * false = 正常 Find bar + 语义搜索。
+   */
+  domDebug: false,
+  /**
+   * 扩展侧跟随策略（站内 demo 已无 Follow UI / 搜索中跟随）：
+   * true = 全程跟随最新 chunk；false = 无匹配时跟随，首个匹配后停下并划线。
+   */
+  followSearching: false,
+};

extension/config.prod.js

@@ -0,0 +1,37 @@
+/**
+ * 上架默认配置（源头）。pack.sh 会拷成包内 config.js；本地用 dev-env.sh prod 生成。
+ * 挂到 globalThis（background importScripts / content 注入顺序加载）。
+ */
+var IL_CONFIG = {
+  apiBase: 'https://dqy08-infolens.hf.space',
+  /**
+   * SYNC: client/src/shared/core/constants.ts → SEMANTIC_CHUNK_BYTES；算法见 splitTextToChunks.js
+   * 已知问题：与后端 SEMANTIC_RUNTIME_CONFIGS 的 max_token_length（300~1000 token，按平台）无联动。
+   * 数字/标点/代码等 token 密度高的内容，800 字节可能超出后端 token 限，被静默截断（仅日志提示），
+   * 导致该 chunk 的相关度判断只基于截断后的前缀 —— 后果是漏检，非误报。无法靠调大固定 token 数根治。
+   */
+  chunkBytes: 800,
+  /** demo 最多请求的 chunk 数，避免一页打爆本地推理 */
+  maxChunks: 32,
+  /** SYNC: client/src/shared/core/constants.ts → SEMANTIC_MATCH_THRESHOLD */
+  matchThreshold: 0.1,
+  /** SYNC: analysis 默认 hybrid（前端组合 count→fill_blank，非后端枚举值） */
+  submode: 'hybrid',
+  /**
+   * SYNC 近似：
+   * - 站内 τ：signalThresholdDetector（失败回退 P90，见 textStatistics.computeP90）
+   * - 站内 pw：visualizationUpdater.ts → pw_score = score×P_pw×matchDegree
+   * 扩展无 signal-fit，用该分位作 τ（默认 0.9 ≈ P90）；见 content.js prepareChunkTokens
+   */
+  pwScorePercentile: 0.9,
+  /**
+   * DOM 调试：true = 点击抽正文并下划线；再点取消；
+   * false = 正常 Find bar + 语义搜索。
+   */
+  domDebug: false,
+  /**
+   * 扩展侧跟随策略（站内 demo 已无 Follow UI / 搜索中跟随）：
+   * true = 全程跟随最新 chunk；false = 无匹配时跟随，首个匹配后停下并划线。
+   */
+  followSearching: false,
+};

extension/content.css

@@ -0,0 +1,94 @@
+/* Extension-only: underline overlay + Custom Highlight.
+ * Find bar lives in Shadow DOM (see content.js).
+ *
+ * token / truncated：CSS Custom Highlight API（不改 DOM、不垫字下）
+ * underline：#il-overlay-host 绝对定位盖层（不必垫字下）
+ */
+
+#il-overlay-host {
+  position: absolute;
+  left: 0;
+  top: 0;
+  width: 0;
+  height: 0;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  overflow: visible;
+  pointer-events: none;
+  z-index: 2147483644;
+}
+
+/* SYNC: client/src/shared/vis/constants.ts → HIGHLIGHT_CONSTANTS
+ * UNDERLINE_WIDTH=2, HIGHLIGHT_COLOR fallback #1e6fff */
+.il-chunk-underline {
+  position: absolute;
+  left: 0;
+  top: 0;
+  pointer-events: none;
+  height: 2px;
+  background: #1e6fff;
+  border-radius: 2px;
+}
+
+/*
+ * token：16 档 background-color。
+ * SYNC: SurprisalColorConfig → SURPRISAL_RED_RGB / SURPRISAL_MAX_ALPHA(0.7)
+ * alpha = ((level+1)/16) * 0.7
+ */
+::highlight(il-token-0) {
+  background-color: rgba(255, 71, 64, 0.04375);
+}
+::highlight(il-token-1) {
+  background-color: rgba(255, 71, 64, 0.0875);
+}
+::highlight(il-token-2) {
+  background-color: rgba(255, 71, 64, 0.13125);
+}
+::highlight(il-token-3) {
+  background-color: rgba(255, 71, 64, 0.175);
+}
+::highlight(il-token-4) {
+  background-color: rgba(255, 71, 64, 0.21875);
+}
+::highlight(il-token-5) {
+  background-color: rgba(255, 71, 64, 0.2625);
+}
+::highlight(il-token-6) {
+  background-color: rgba(255, 71, 64, 0.30625);
+}
+::highlight(il-token-7) {
+  background-color: rgba(255, 71, 64, 0.35);
+}
+::highlight(il-token-8) {
+  background-color: rgba(255, 71, 64, 0.39375);
+}
+::highlight(il-token-9) {
+  background-color: rgba(255, 71, 64, 0.4375);
+}
+::highlight(il-token-10) {
+  background-color: rgba(255, 71, 64, 0.48125);
+}
+::highlight(il-token-11) {
+  background-color: rgba(255, 71, 64, 0.525);
+}
+::highlight(il-token-12) {
+  background-color: rgba(255, 71, 64, 0.56875);
+}
+::highlight(il-token-13) {
+  background-color: rgba(255, 71, 64, 0.6125);
+}
+::highlight(il-token-14) {
+  background-color: rgba(255, 71, 64, 0.65625);
+}
+::highlight(il-token-15) {
+  background-color: rgba(255, 71, 64, 0.7);
+}
+
+/*
+ * 未分析后缀置灰：统一灰（不跟链接/标题各自字色）。
+ * CanvasText / Canvas 随色彩方案变，深浅色均可读。
+ */
+::highlight(il-truncated) {
+  color: color-mix(in srgb, CanvasText 40%, Canvas 60%);
+}

extension/content.js

@@ -0,0 +1,1831 @@
+/**
+ * InfoLens semantic find — feasibility content script.
+ * Validates: article extract ↔ DOM map, API call, token paint, chunk underline.
+ *
+ * token / truncated：CSS Custom Highlight API（不改 DOM；truncated 为 CanvasText×Canvas 统一灰）。
+ * underline：#il-overlay-host 绝对定位盖层（不垫字下）。
+ *
+ * IL_CONFIG.domDebug：点击后只抽正文并下划线，便于目测提取范围（不唤起 Find bar）。
+ */
+(() => {
+  // 已注入过：依赖齐全则只 reopen；缺 merge 副本说明上次注入过期（未重载扩展），拆掉重装
+  if (window.__IL_SEMANTIC_DEMO__) {
+    if (typeof globalThis.IL_mergeTokenSpansFullyForRendering === 'function') {
+      window.__IL_SEMANTIC_DEMO__.open();
+      return;
+    }
+    try {
+      window.__IL_SEMANTIC_DEMO__.destroy();
+    } catch {
+      /* ignore */
+    }
+    window.__IL_SEMANTIC_DEMO__ = undefined;
+  }
+
+  const CFG = globalThis.IL_CONFIG || {
+    apiBase: 'http://127.0.0.1:5001',
+    chunkBytes: 800,
+    maxChunks: 3,
+    matchThreshold: 0.1,
+    submode: 'hybrid',
+    // SYNC 默认：站内 signal-fit 失败回退 P90；扩展用分位近似（见 prepareChunkTokens）
+    pwScorePercentile: 0.9,
+    domDebug: true,
+    // 扩展侧节奏：默认 false = 无匹配时跟随、首个匹配后停下并划线（站内 demo 已无 Follow UI）
+    followSearching: false,
+  };
+  const DOM_DEBUG = !!CFG.domDebug;
+
+  // SYNC: client/src/shared/cross/SurprisalColorConfig.ts → SURPRISAL_RED / MAX_ALPHA（色值见 content.css ::highlight）
+  /** token 背景量化档数（::highlight(il-token-0..15)） */
+  const TOKEN_LEVELS = 16;
+  const HL_TOKEN_PREFIX = 'il-token-';
+  const HL_TRUNCATED = 'il-truncated';
+  // SYNC: client/src/shared/vis/constants.ts → HIGHLIGHT_CONSTANTS
+  const CHUNK_HIGHLIGHT_HOLD_MS = 200;
+  const CHUNK_HIGHLIGHT_FADE_MS = 1400;
+  // SYNC: client/src/shared/vis/GLTR_Text_Box.ts → scrollToUnicodeCharOffset 默认 viewportYRatio
+  const CHUNK_JUMP_VIEWPORT_Y_RATIO = 0.2;
+  // 分块语义搜索：最快节奏下限——两次渲染之间至少间隔这么久（无论是否有滚动）
+  const CHUNK_SEARCH_MIN_CYCLE_MS = 900;
+  // 有后续滚动时：染色后先停留一半，另一半留给滚动 settle；无滚动（已 park）时整段都算这里，见下方用法
+  const CHUNK_SEARCH_HOLD_MS = CHUNK_SEARCH_MIN_CYCLE_MS / 2;
+  const CHUNK_SEARCH_FOLLOW_VIEWPORT_Y_RATIO = 0.6;
+  // 自动滚动落点（预滚到下一块 / 首次命中跳转）至少展示这么久，再进入下一块渲染
+  const CHUNK_SEARCH_SCROLL_SETTLE_MS = CHUNK_SEARCH_MIN_CYCLE_MS / 2;
+
+  /** @type {{ node: Text, start: number, end: number }[]} */
+  let pieces = [];
+  /** pieces 的节点集合缓存，供 mutationTouchesPieces 做 O(1) 命中判断，避免逐条 mutation 都线性扫 pieces */
+  /** @type {Set<Text>} */
+  let pieceNodeSet = new Set();
+  let extractedText = '';
+  /** @type {{ start: number, end: number, matchDegree: number }[]} */
+  let matchedChunks = [];
+  /** @type {{ start: number, end: number, matchDegree: number }[]} */
+  let semanticMatchProgress = [];
+  /** 进度条分母（码点数）：maxChunks 截断时用实际搜索覆盖长度，而非全文长度；0 = 未搜索，回退全文 */
+  let progressTextLength = 0;
+  let selectedProgressChunkStart = null;
+  let hoveredProgressChunkStart = null;
+  let progressSelectionFading = false;
+  let matchIndex = -1;
+  /**
+   * 逻辑区间（去重键）；与 DOM 节点分离。
+   * token：CSS Highlight；underline：overlay rect（reflow 时按 spec 重绘，勿按 rect 条数累积）。
+   * @type {{ kind: 'token' | 'underline', cp0: number, cp1: number, level?: number }[]}
+   */
+  let paintSpecs = [];
+  /** @type {HTMLElement[]} 仅 underline DOM */
+  let overlayEls = [];
+  /** 未分析后缀置灰：已分析码点终点；null = 无置灰 */
+  let truncatedAnalyzedCpEnd = null;
+  /**
+   * 长度 1 的搜索结果缓存（含 Stop 半成品）。close 清高亮但保留；
+   * open 时若输入与正文未变则还原，避免重复请求。
+   * @type {null | {
+   *   query: string,
+   *   text: string,
+   *   paintSpecs: typeof paintSpecs,
+   *   matchedChunks: typeof matchedChunks,
+   *   semanticMatchProgress: typeof semanticMatchProgress,
+   *   progressTextLength: number,
+   *   matchIndex: number,
+   *   truncatedAnalyzedCpEnd: number | null,
+   * }}
+   */
+  let lastResult = null;
+  /** @type {Element | null} 正文根（定滚动根用） */
+  let extractRoot = null;
+  /** @type {HTMLElement | null} underline 叠层宿主 + 布局监听哨兵 */
+  let paintMount = null;
+  /** @type {Element | null} 曾被设为 relative 的节点 */
+  let paintPosTarget = null;
+  /** 若曾把 paintPosTarget 从 static 改为 relative，清理时还原 */
+  let paintPosRestore = null;
+  /** @type {ResizeObserver | null} */
+  let paintResizeObserver = null;
+  /** 监听正文子树的文字改写（如翻译插件原地换字），弥补 ResizeObserver 只对尺寸变化敏感的盲区 */
+  /** @type {MutationObserver | null} */
+  let contentMutationObserver = null;
+  let scrollSyncTimer = 0;
+  let searching = false;
+  let abortWanted = false;
+  let reflowQueued = false;
+  let underlineHoldTimer = 0;
+  let underlineFadeTimer = 0;
+  /** @type {(() => void) | null} */
+  let scrollEndCancel = null;
+  let underlineFadeGen = 0;
+  let chunkSearchAutoScrollUserCancelled = false;
+  /** @type {(() => void) | undefined} */
+  let chunkSearchAutoScrollCleanup;
+
+  // ---------- extract（纯文本查看器 / Readability 定根；后者失败不回退） ----------
+
+  function pickArticleRoot() {
+    const find = globalThis.IL_findArticleRoot;
+    if (typeof find !== 'function') {
+      throw new Error('IL_findArticleRoot missing — inject articleRoot.js before content.js');
+    }
+    return find(document);
+  }
+
+  function collectTextMap(root) {
+    const out = [];
+    let text = '';
+    const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, {
+      acceptNode(node) {
+        if (!node.nodeValue) return NodeFilter.FILTER_REJECT;
+        const p = node.parentElement;
+        if (!p) return NodeFilter.FILTER_REJECT;
+        const tag = p.tagName;
+        if (tag === 'SCRIPT' || tag === 'STYLE' || tag === 'NOSCRIPT' || tag === 'TEXTAREA' || tag === 'SVG') {
+          return NodeFilter.FILTER_REJECT;
+        }
+        if (p.closest('#il-find-root, #il-overlay-host, .il-chunk-underline')) {
+          return NodeFilter.FILTER_REJECT;
+        }
+        return NodeFilter.FILTER_ACCEPT;
+      },
+    });
+    let n;
+    while ((n = walker.nextNode())) {
+      const value = n.nodeValue;
+      const start = text.length;
+      text += value;
+      out.push({ node: n, start, end: text.length });
+    }
+    return { text, pieces: out, root };
+  }
+
+  function setPieces(newPieces) {
+    pieces = newPieces;
+    pieceNodeSet = new Set(pieces.map((p) => p.node));
+  }
+
+  function refreshExtract() {
+    clearOverlays();
+    const root = pickArticleRoot();
+    extractRoot = root;
+    ensurePaintMount(root);
+    const mapped = collectTextMap(root);
+    extractedText = mapped.text;
+    setPieces(mapped.pieces);
+    matchedChunks = [];
+    semanticMatchProgress = [];
+    matchIndex = -1;
+    return { root, length: extractedText.length };
+  }
+
+  // ---------- offsets (API = code points; piece map = UTF-16) ----------
+
+  function cpToUtf16(str, cpIndex) {
+    let i = 0;
+    let cps = 0;
+    while (cps < cpIndex && i < str.length) {
+      const cp = str.codePointAt(i);
+      i += cp > 0xffff ? 2 : 1;
+      cps += 1;
+    }
+    return i;
+  }
+
+  function utf16ToCp(str, utf16Index) {
+    let i = 0;
+    let cps = 0;
+    while (i < utf16Index && i < str.length) {
+      const cp = str.codePointAt(i);
+      i += cp > 0xffff ? 2 : 1;
+      cps += 1;
+    }
+    return cps;
+  }
+
+  function findPiece(utf16Offset) {
+    let lo = 0;
+    let hi = pieces.length - 1;
+    while (lo <= hi) {
+      const mid = (lo + hi) >> 1;
+      const p = pieces[mid];
+      if (utf16Offset < p.start) hi = mid - 1;
+      else if (utf16Offset >= p.end) lo = mid + 1;
+      else return p;
+    }
+    return null;
+  }
+
+  function findPieceIndex(utf16Offset) {
+    let lo = 0;
+    let hi = pieces.length - 1;
+    while (lo <= hi) {
+      const mid = (lo + hi) >> 1;
+      const p = pieces[mid];
+      if (utf16Offset < p.start) hi = mid - 1;
+      else if (utf16Offset >= p.end) lo = mid + 1;
+      else return mid;
+    }
+    return -1;
+  }
+
+  /** 最近块级容器；跨块的 Range 会让 getClientRects 多出整块盒子 */
+  function nearestBlock(node, cache) {
+    let el = node.parentElement;
+    while (el) {
+      const cached = cache?.get(el);
+      if (cached !== undefined) return cached;
+      const display = getComputedStyle(el).display;
+      if (
+        display === 'block' ||
+        display === 'flex' ||
+        display === 'grid' ||
+        display === 'list-item' ||
+        display === 'table' ||
+        display === 'table-row' ||
+        display === 'table-cell' ||
+        display === 'flow-root'
+      ) {
+        cache?.set(el, el);
+        return el;
+      }
+      el = el.parentElement;
+    }
+    return document.body;
+  }
+
+  /** 整段 Range（滚动定位等）；绘制请用 rangesFromCpOffsets */
+  function rangeFromCpOffsets(cp0, cp1) {
+    if (!extractedText || cp1 <= cp0) return null;
+    const u0 = cpToUtf16(extractedText, cp0);
+    const u1 = cpToUtf16(extractedText, cp1);
+    if (u1 <= u0) return null;
+
+    const startPiece = findPiece(u0);
+    const endPiece = findPiece(u1 - 1);
+    if (!startPiece || !endPiece) return null;
+    if (!startPiece.node.isConnected || !endPiece.node.isConnected) return null;
+
+    const range = document.createRange();
+    try {
+      range.setStart(startPiece.node, u0 - startPiece.start);
+      range.setEnd(endPiece.node, u1 - endPiece.start);
+    } catch {
+      return null;
+    }
+    return range;
+  }
+
+  /**
+   * 按块级容器切开，避免单个 Range 跨 <p> 等时 getClientRects 叠出双线。
+   * @returns {Range[]}
+   */
+  function rangesFromCpOffsets(cp0, cp1) {
+    if (!extractedText || cp1 <= cp0) return [];
+    const u0 = cpToUtf16(extractedText, cp0);
+    const u1 = cpToUtf16(extractedText, cp1);
+    if (u1 <= u0) return [];
+
+    let i = findPieceIndex(u0);
+    if (i < 0) return [];
+
+    const blockCache = new WeakMap();
+    /** @type {Range[]} */
+    const out = [];
+    /** @type {Range | null} */
+    let cur = null;
+    /** @type {Element | null} */
+    let curBlock = null;
+
+    for (; i < pieces.length; i++) {
+      const p = pieces[i];
+      if (p.start >= u1) break;
+      if (!p.node.isConnected) continue;
+      const seg0 = Math.max(u0, p.start);
+      const seg1 = Math.min(u1, p.end);
+      if (seg1 <= seg0) continue;
+      // 纯空白片段不画（空白行等）；截断当前 Range，避免跨过空白仍被 setEnd 包进区间
+      if (!/\S/.test(extractedText.slice(seg0, seg1))) {
+        if (cur && !cur.collapsed) out.push(cur);
+        cur = null;
+        curBlock = null;
+        continue;
+      }
+
+      const block = nearestBlock(p.node, blockCache);
+      try {
+        if (!cur || block !== curBlock) {
+          if (cur && !cur.collapsed) out.push(cur);
+          cur = document.createRange();
+          cur.setStart(p.node, seg0 - p.start);
+          cur.setEnd(p.node, seg1 - p.start);
+          curBlock = block;
+        } else {
+          cur.setEnd(p.node, seg1 - p.start);
+        }
+      } catch {
+        if (cur && !cur.collapsed) out.push(cur);
+        cur = null;
+        curBlock = null;
+      }
+    }
+    if (cur && !cur.collapsed) out.push(cur);
+    return out;
+  }
+
+  // ---------- chunking（SYNC 副本：splitTextToChunks.js ← semanticUtils.splitTextToChunks） ----------
+
+  function splitChunks(text, byteLimit) {
+    const split = globalThis.IL_splitTextToChunks;
+    if (typeof split !== 'function') {
+      throw new Error('IL_splitTextToChunks missing — inject splitTextToChunks.js before content.js');
+    }
+    return split(text, byteLimit).map((c) => ({
+      start: c.startOffset,
+      end: c.startOffset + c.text.length,
+      text: c.text,
+    }));
+  }
+
+  /** 全空白 chunk 不送 API / 不作为语义匹配目标 */
+  function chunkHasContent(chunk) {
+    return /\S/.test(chunk.text);
+  }
+
+  // ---------- paint：token/truncated = CSS Highlight；underline = overlay host ----------
+
+  /** score∈(0,1] → 0..TOKEN_LEVELS-1；≤0 不画 */
+  function scoreToLevel(score01) {
+    if (!Number.isFinite(score01) || !(score01 > 0)) return -1;
+    const t = Math.max(0, Math.min(1, score01));
+    return Math.min(TOKEN_LEVELS - 1, Math.floor(t * TOKEN_LEVELS));
+  }
+
+  /**
+   * SYNC: client/src/shared/cross/textStatistics.ts → computeP90（同插值：index = (n-1)*p；站内固定 p=0.9）
+   * @param {number[]} values
+   * @param {number} p 0~1
+   * @returns {number | null}
+   */
+  function computePercentile(values, p) {
+    if (!values?.length) return null;
+    if (!(p >= 0 && p <= 1)) {
+      throw new Error(`pwScorePercentile must be in [0,1], got ${p}`);
+    }
+    const sorted = values.filter(Number.isFinite).slice().sort((a, b) => a - b);
+    const n = sorted.length;
+    if (n === 0) return null;
+    const index = (n - 1) * p;
+    const lower = Math.floor(index);
+    const upper = Math.ceil(index);
+    const weight = index - lower;
+    if (lower === upper) return sorted[lower];
+    return sorted[lower] * (1 - weight) + sorted[upper] * weight;
+  }
+
+  /**
+   * SYNC 语义（近似）：
+   * - merge/normalize：client/src/shared/controllers/semanticSearchController.ts
+   *   + semanticUtils.mergeTokenSpansFullyForRendering / normalizeTokenScores
+   * - pw_score：client/src/features/analysis/visualizationUpdater.ts
+   *   → pw_score = score×P_pw×matchDegree（P_pw：score>τ→1）
+   * - τ：站内为 signal-fit（失败回退 P90）；扩展无 fit，用可配置分位代替（默认 0.9 ≈ P90）
+   */
+  function prepareChunkTokens(tokenAttention, chunkText, matchDegree) {
+    const merge = globalThis.IL_mergeTokenSpansFullyForRendering;
+    const normalize = globalThis.IL_normalizeTokenScores;
+    if (typeof merge !== 'function' || typeof normalize !== 'function') {
+      throw new Error(
+        'IL_mergeTokenSpansFullyForRendering missing — 请在 chrome://extensions 重新加载本扩展后再点图标'
+      );
+    }
+    const normalized = normalize(merge(tokenAttention || [], chunkText));
+    const p = CFG.pwScorePercentile ?? 0.9;
+    const tau = computePercentile(
+      normalized.map((t) => t.score),
+      p
+    );
+    if (tau == null) return [];
+    const degree = Number.isFinite(matchDegree) ? matchDegree : 0;
+    return normalized.map((t) => ({
+      ...t,
+      score: t.score > tau ? t.score * degree : 0,
+    }));
+  }
+
+  function isScrollableEl(el) {
+    if (!(el instanceof Element)) return false;
+    const st = getComputedStyle(el);
+    const y = st.overflowY;
+    const x = st.overflowX;
+    const canY =
+      (y === 'auto' || y === 'scroll' || y === 'overlay') && el.scrollHeight > el.clientHeight + 1;
+    const canX =
+      (x === 'auto' || x === 'scroll' || x === 'overlay') && el.scrollWidth > el.clientWidth + 1;
+    return canY || canX;
+  }
+
+  /** 正文所在的最近滚动根（仅用于监听 scrollend） */
+  function findScrollRoot(from) {
+    let node = from instanceof Element ? from : from?.parentElement;
+    while (node && node !== document.documentElement) {
+      if (isScrollableEl(node)) return node;
+      node = node.parentElement;
+    }
+    return document.scrollingElement || document.documentElement;
+  }
+
+  function stopPaintLayoutWatch() {
+    paintResizeObserver?.disconnect();
+    paintResizeObserver = null;
+    contentMutationObserver?.disconnect();
+    contentMutationObserver = null;
+    if (scrollSyncTimer) {
+      clearTimeout(scrollSyncTimer);
+      scrollSyncTimer = 0;
+    }
+  }
+
+  /**
+   * 只关心落在已提取文本节点（pieces）上的变动，忽略正文里跟已提取内容无关的动态
+   * （广告刷新、评论计数、相关阅读懒加载等）。本扩展自己挂的 overlay/下划线 DOM 从不
+   * 包含任何 pieces 节点，天然会被判定为不相关，无需再单独过滤。
+   */
+  function mutationTouchesPieces(record) {
+    if (record.type === 'characterData') {
+      return pieceNodeSet.has(record.target);
+    }
+    const changed = [...record.addedNodes, ...record.removedNodes];
+    if (changed.some((n) => pieceNodeSet.has(n))) return true;
+    // 兜底：整段容器（含某个已提取节点）被摘除/替换，命中率低，允许退化为线性扫描
+    return changed.some((n) => n.nodeType === 1 && pieces.some((p) => n.contains(p.node)));
+  }
+
+  function releasePaintMount() {
+    stopPaintLayoutWatch();
+    if (paintMount) {
+      paintMount.remove();
+      paintMount = null;
+    }
+    if (paintPosTarget && paintPosRestore !== null) {
+      paintPosTarget.style.position = paintPosRestore;
+    }
+    paintPosTarget = null;
+    paintPosRestore = null;
+  }
+
+  /** underline 叠层挂在正文根内；与字同滚动，停稳后再重测坐标 */
+  function ensurePaintMount(articleRoot) {
+    if (paintMount?.isConnected && paintMount.parentElement === articleRoot) return paintMount;
+
+    releasePaintMount();
+
+    const st = getComputedStyle(articleRoot);
+    if (st.position === 'static') {
+      paintPosTarget = articleRoot;
+      paintPosRestore = articleRoot.style.position;
+      articleRoot.style.position = 'relative';
+    }
+
+    const host = document.createElement('div');
+    host.id = 'il-overlay-host';
+    articleRoot.appendChild(host);
+    paintMount = host;
+    startPaintLayoutWatch(articleRoot);
+    return paintMount;
+  }
+
+  /** 视口 rect → 相对 #il-overlay-host */
+  function clientRectToMountPos(rect) {
+    if (!paintMount) throw new Error('paint mount missing');
+    const hr = paintMount.getBoundingClientRect();
+    return {
+      x: rect.left - hr.left,
+      y: rect.bottom - 2 - hr.top,
+    };
+  }
+
+  function requireHighlightApi() {
+    if (!CSS.highlights || typeof Highlight !== 'function') {
+      throw new Error('CSS Custom Highlight API missing');
+    }
+  }
+
+  /** 注册 il-token-0..15 / il-truncated；已存在则复用 */
+  function ensureHighlightRegistry() {
+    requireHighlightApi();
+    for (let i = 0; i < TOKEN_LEVELS; i++) {
+      const name = HL_TOKEN_PREFIX + i;
+      if (!CSS.highlights.has(name)) {
+        const h = new Highlight();
+        h.priority = i;
+        CSS.highlights.set(name, h);
+      }
+    }
+    if (!CSS.highlights.has(HL_TRUNCATED)) {
+      const h = new Highlight();
+      h.priority = TOKEN_LEVELS + 1;
+      CSS.highlights.set(HL_TRUNCATED, h);
+    }
+  }
+
+  function clearTokenHighlights() {
+    if (!CSS.highlights) return;
+    for (let i = 0; i < TOKEN_LEVELS; i++) {
+      CSS.highlights.get(HL_TOKEN_PREFIX + i)?.clear();
+    }
+  }
+
+  function clearAllCustomHighlights() {
+    clearTokenHighlights();
+    CSS.highlights?.get(HL_TRUNCATED)?.clear();
+  }
+
+  /** 把 cp 区间加到指定 Highlight（按块切开，跳过纯空白） */
+  function addCpRangeToHighlight(highlight, cp0, cp1) {
+    for (const range of rangesFromCpOffsets(cp0, cp1)) {
+      if (!/\S/.test(range.toString())) continue;
+      highlight.add(range);
+    }
+  }
+
+  function renderTokenHighlights() {
+    ensureHighlightRegistry();
+    clearTokenHighlights();
+    for (const s of paintSpecs) {
+      if (s.kind !== 'token') continue;
+      const level = s.level;
+      if (level == null || level < 0 || level >= TOKEN_LEVELS) continue;
+      const h = CSS.highlights.get(HL_TOKEN_PREFIX + level);
+      if (!h) throw new Error(`highlight missing: ${HL_TOKEN_PREFIX}${level}`);
+      addCpRangeToHighlight(h, s.cp0, s.cp1);
+    }
+  }
+
+  function applyTruncatedHighlight() {
+    ensureHighlightRegistry();
+    const h = CSS.highlights.get(HL_TRUNCATED);
+    if (!h) throw new Error('highlight missing: il-truncated');
+    h.clear();
+    if (truncatedAnalyzedCpEnd == null || !extractedText || !extractRoot?.isConnected) return;
+    const fullCp = utf16ToCp(extractedText, extractedText.length);
+    const cp0 = Math.max(0, Math.min(truncatedAnalyzedCpEnd, fullCp));
+    if (cp0 >= fullCp) return;
+    addCpRangeToHighlight(h, cp0, fullCp);
+  }
+
+  function clearOverlayEls(options) {
+    const preserveUnderline = options?.preserveUnderline === true;
+    if (!preserveUnderline) {
+      for (const el of overlayEls) el.remove();
+      overlayEls = [];
+      return;
+    }
+    // SYNC: GLTR_Text_Box.clearHighlight({ preserveChunkInterval: true }) — 留下划线 DOM（含 fade）
+    overlayEls = overlayEls.filter((el) => {
+      if (el.classList.contains('il-chunk-underline')) return true;
+      el.remove();
+      return false;
+    });
+  }
+
+  /** SYNC: client/src/shared/vis/GLTR_Text_Box.ts → cancelChunkHighlightFade */
+  function cancelUnderlineFade() {
+    underlineFadeGen += 1;
+    progressSelectionFading = false;
+    if (underlineHoldTimer) {
+      clearTimeout(underlineHoldTimer);
+      underlineHoldTimer = 0;
+    }
+    if (underlineFadeTimer) {
+      clearTimeout(underlineFadeTimer);
+      underlineFadeTimer = 0;
+    }
+    scrollEndCancel?.();
+    scrollEndCancel = null;
+  }
+
+  function clearOverlays() {
+    cancelUnderlineFade();
+    endChunkSearchAutoScroll();
+    clearTruncatedHighlight();
+    clearTokenHighlights();
+    clearOverlayEls();
+    paintSpecs = [];
+    releasePaintMount();
+    extractRoot = null;
+  }
+
+  /**
+   * 清当前会话的渲染与搜索进度。
+   * @param {{ clearCache?: boolean }} [options] clearCache=true 时连 lastResult 一并丢弃（改 query / giveUp）
+   */
+  function resetSearchSession({ clearCache = false } = {}) {
+    clearOverlays();
+    matchedChunks = [];
+    semanticMatchProgress = [];
+    progressTextLength = 0;
+    selectedProgressChunkStart = null;
+    hoveredProgressChunkStart = null;
+    progressSelectionFading = false;
+    matchIndex = -1;
+    if (clearCache) lastResult = null;
+    updateNav();
+    renderSemanticMatchProgress();
+  }
+
+  /**
+   * 正文被第三方（如翻译插件）意外改写、或提取根本身被替换/移除时的止损：
+   * 不尝试修复或用旧偏移套新文本，直接放弃本次结果，回到未搜索状态（等价于清空输入框）。
+   * 下次搜索会走 refreshExtract() 全量重新提取，天然恢复正常。
+   */
+  function giveUp() {
+    abortWanted = true;
+    resetSearchSession({ clearCache: true });
+    setSearching(false);
+  }
+
+  /** 覆盖写入长度 1 结果缓存（specs 浅拷贝，避免后续 clear 连带清空） */
+  function snapshotLastResult(query) {
+    if (!query || extractRoot == null) return;
+    lastResult = {
+      query,
+      text: extractedText,
+      paintSpecs: paintSpecs.map((s) => ({ ...s })),
+      matchedChunks: matchedChunks.map((c) => ({ ...c })),
+      semanticMatchProgress: semanticMatchProgress.map((c) => ({ ...c })),
+      progressTextLength,
+      matchIndex,
+      truncatedAnalyzedCpEnd,
+      selectedProgressChunkStart,
+    };
+  }
+
+  /** @returns {boolean} 是否已还原 */
+  function tryRestoreLastResult(query) {
+    if (!lastResult || !query) return false;
+    if (query !== lastResult.query || extractedText !== lastResult.text) return false;
+    paintSpecs = lastResult.paintSpecs.map((s) => ({ ...s }));
+    matchedChunks = lastResult.matchedChunks.map((c) => ({ ...c }));
+    semanticMatchProgress = lastResult.semanticMatchProgress.map((c) => ({ ...c }));
+    progressTextLength = lastResult.progressTextLength;
+    matchIndex = lastResult.matchIndex;
+    selectedProgressChunkStart = lastResult.selectedProgressChunkStart ?? null;
+    if (lastResult.truncatedAnalyzedCpEnd != null) {
+      setTruncatedHighlight(lastResult.truncatedAnalyzedCpEnd);
+    }
+    renderAllSpecs({
+      preserveUnderline: paintSpecs.some((s) => s.kind === 'underline'),
+    });
+    updateNav();
+    renderSemanticMatchProgress();
+    return true;
+  }
+
+  /**
+   * ChatGPT 等会在滚动时改布局/换节点；滚动停稳或尺寸变化后重绑 Range / 重测 underline。
+   */
+  function syncPaintAfterLayout() {
+    if (!extractRoot?.isConnected) {
+      // 提取根本身被换掉/摘除（如翻译插件重建了整个容器）：有残留结果才需要放弃，否则什么都没画，无需处理
+      if (
+        paintSpecs.length > 0 ||
+        truncatedAnalyzedCpEnd != null ||
+        matchedChunks.length > 0 ||
+        semanticMatchProgress.length > 0
+      ) {
+        giveUp();
+      }
+      return;
+    }
+    if (paintSpecs.length === 0 && truncatedAnalyzedCpEnd == null) return;
+
+    const mapped = collectTextMap(extractRoot);
+    const stale = pieces.some((p) => !p.node.isConnected);
+    if (mapped.text !== extractedText) {
+      // DOM_DEBUG 只是目测提取范围的调试预览，永远反映"当前"文本，文本变了就重新按当前内容分块展示
+      if (DOM_DEBUG) {
+        extractedText = mapped.text;
+        setPieces(mapped.pieces);
+        if (!extractedText.trim()) {
+          clearOverlayEls();
+          clearAllCustomHighlights();
+          return;
+        }
+        const allChunks = splitChunks(extractedText, CFG.chunkBytes).filter(chunkHasContent);
+        matchedChunks = allChunks.map((chunk) => ({
+          start: utf16ToCp(extractedText, chunk.start),
+          end: utf16ToCp(extractedText, chunk.end),
+          matchDegree: 1,
+        }));
+        matchIndex = -1;
+        paintAllUnderlines();
+        return;
+      }
+      // 正文内容真的变了（非仅节点重排）：旧的语义偏移量已经和新文本对不上，放弃而不是套用错位渲染
+      giveUp();
+      return;
+    }
+    if (stale) {
+      // 内容没变、只是节点被重新挂载（如虚拟滚动列表换节点）：重绑节点引用即可，照常渲染
+      setPieces(mapped.pieces);
+    }
+    renderAllSpecs({
+      preserveUnderline: paintSpecs.some((s) => s.kind === 'underline'),
+    });
+  }
+
+  function scheduleSyncPaintAfterLayout() {
+    if (scrollSyncTimer) clearTimeout(scrollSyncTimer);
+    scrollSyncTimer = window.setTimeout(() => {
+      scrollSyncTimer = 0;
+      syncPaintAfterLayout();
+    }, 120);
+  }
+
+  function startPaintLayoutWatch(articleRoot) {
+    stopPaintLayoutWatch();
+    paintResizeObserver = new ResizeObserver(() => scheduleSyncPaintAfterLayout());
+    paintResizeObserver.observe(articleRoot);
+    const scrollRoot = findScrollRoot(articleRoot);
+    if (scrollRoot && scrollRoot !== document.documentElement && scrollRoot !== document.body) {
+      paintResizeObserver.observe(scrollRoot);
+    }
+    // 尺寸不变的原地换字（翻译插件常见）不会触发 ResizeObserver，靠这个兜底触发同一套 sync 判断
+    contentMutationObserver = new MutationObserver((records) => {
+      if (records.some(mutationTouchesPieces)) scheduleSyncPaintAfterLayout();
+    });
+    contentMutationObserver.observe(articleRoot, { childList: true, characterData: true, subtree: true });
+  }
+
+  function specKey(s) {
+    return `${s.kind}|${s.cp0}|${s.cp1}|${s.level ?? ''}`;
+  }
+
+  function upsertSpec(spec) {
+    const key = specKey(spec);
+    const i = paintSpecs.findIndex((s) => specKey(s) === key);
+    if (i >= 0) paintSpecs[i] = spec;
+    else paintSpecs.push(spec);
+  }
+
+  /** underline：挂 #il-overlay-host，盖在内容上 */
+  function appendUnderlineRect(rect) {
+    if (!paintMount) throw new Error('paint mount missing');
+    const el = document.createElement('div');
+    el.className = 'il-chunk-underline';
+    const { x, y } = clientRectToMountPos(rect);
+    el.style.left = `${x}px`;
+    el.style.top = `${y}px`;
+    el.style.width = `${rect.width}px`;
+    paintMount.appendChild(el);
+    overlayEls.push(el);
+  }
+
+  /**
+   * 按 paintSpecs 重绑 Highlight + 重画 underline。
+   * @param {{ preserveUnderline?: boolean }} [options]
+   *   preserveUnderline：对齐站内 preserveChunkInterval — 不拆下划线 DOM（hold/fade 不被流式 token 更新打断）
+   */
+  function renderAllSpecs(options) {
+    const preserveUnderline = options?.preserveUnderline === true;
+    clearOverlayEls({ preserveUnderline });
+    if (!extractRoot?.isConnected) return 0;
+    ensurePaintMount(extractRoot);
+    renderTokenHighlights();
+    applyTruncatedHighlight();
+    let rectCount = overlayEls.length;
+    for (const s of paintSpecs) {
+      if (s.kind !== 'underline') continue;
+      if (preserveUnderline) continue;
+      for (const range of rangesFromCpOffsets(s.cp0, s.cp1)) {
+        if (!/\S/.test(range.toString())) continue;
+        for (const r of range.getClientRects()) {
+          if (r.width < 1 || r.height < 1) continue;
+          appendUnderlineRect(r);
+          rectCount += 1;
+        }
+      }
+    }
+    return rectCount;
+  }
+
+  function paintSpec(kind, cp0, cp1, level) {
+    const before = paintSpecs.length;
+    const spec = kind === 'token' ? { kind, cp0, cp1, level } : { kind, cp0, cp1 };
+    upsertSpec(spec);
+    return paintSpecs.length > before ? 1 : 0;
+  }
+
+  function clearTruncatedHighlight() {
+    truncatedAnalyzedCpEnd = null;
+    CSS.highlights?.get(HL_TRUNCATED)?.clear();
+  }
+
+  /**
+   * SYNC：站内 truncated-text 只改字色。
+   * 扩展：::highlight(il-truncated)，统一灰 = CanvasText × Canvas（不跟各段自身字色）。
+   */
+  function setTruncatedHighlight(analyzedCpEnd) {
+    truncatedAnalyzedCpEnd = analyzedCpEnd;
+    applyTruncatedHighlight();
+  }
+
+  function scheduleReflow() {
+    if (reflowQueued) return;
+    reflowQueued = true;
+    requestAnimationFrame(() => {
+      reflowQueued = false;
+      renderAllSpecs({
+        preserveUnderline: paintSpecs.some((s) => s.kind === 'underline'),
+      });
+    });
+  }
+
+  /** DOM 调试：画出全部提取 chunk 下划线（非语义 match 导航） */
+  function paintAllUnderlines() {
+    cancelUnderlineFade();
+    paintSpecs = paintSpecs.filter((s) => s.kind !== 'underline');
+    matchedChunks.forEach((c) => {
+      upsertSpec({ kind: 'underline', cp0: c.start, cp1: c.end });
+    });
+    renderAllSpecs();
+  }
+
+  /**
+   * SYNC: client/src/shared/vis/GLTR_Text_Box.ts → setChunkCharRangeHighlight
+   * 语义导航只画当前 match 一条下划线（paintAllUnderlines 仅 DOM 调试，非站内语义行为）
+   */
+  function setCurrentUnderline(chunk) {
+    cancelUnderlineFade();
+    paintSpecs = paintSpecs.filter((s) => s.kind !== 'underline');
+    if (chunk) {
+      upsertSpec({ kind: 'underline', cp0: chunk.start, cp1: chunk.end });
+    }
+    renderAllSpecs();
+  }
+
+  /**
+   * SYNC: client/src/shared/vis/HighlightManager.ts → fadeOutCharIntervalUnderlines
+   * + GLTR_Text_Box.fadeCurrentChunkHighlight
+   */
+  function fadeCurrentUnderline() {
+    const gen = ++underlineFadeGen;
+    const fadingProgressChunkStart = selectedProgressChunkStart;
+    const lines = overlayEls.filter((el) => el.classList.contains('il-chunk-underline'));
+    if (!lines.length) {
+      paintSpecs = paintSpecs.filter((s) => s.kind !== 'underline');
+      if (fadingProgressChunkStart != null) {
+        selectedProgressChunkStart = null;
+        progressSelectionFading = false;
+        renderSemanticMatchProgress();
+      }
+      return;
+    }
+    if (fadingProgressChunkStart != null) {
+      progressSelectionFading = true;
+      renderSemanticMatchProgress();
+    }
+    for (const el of lines) {
+      el.style.transition = '';
+      el.style.opacity = '1';
+    }
+    requestAnimationFrame(() => {
+      if (gen !== underlineFadeGen) return;
+      for (const el of lines) {
+        el.style.transition = `opacity ${CHUNK_HIGHLIGHT_FADE_MS}ms ease-out`;
+        el.style.opacity = '0';
+      }
+      underlineFadeTimer = window.setTimeout(() => {
+        underlineFadeTimer = 0;
+        if (gen !== underlineFadeGen) return;
+        paintSpecs = paintSpecs.filter((s) => s.kind !== 'underline');
+        renderAllSpecs();
+        if (selectedProgressChunkStart === fadingProgressChunkStart) {
+          selectedProgressChunkStart = null;
+          progressSelectionFading = false;
+          renderSemanticMatchProgress();
+        }
+      }, CHUNK_HIGHLIGHT_FADE_MS);
+    });
+  }
+
+  /**
+   * SYNC: client/src/shared/core/waitForSmoothScrollEnd.ts
+   * 等滚动停稳或确认未滚动；勿仅依赖 scrollend（无位移时常不触发 → 空等 maxWait）。
+   */
+  /**
+   * SYNC: client/src/shared/core/waitForSmoothScrollEnd.ts
+   * scrollend + 两帧后位置未变则结束 + maxWait；勿仅依赖 scrollend。
+   */
+  function waitForSmoothScrollEnd(target, onDone, maxWaitMs = 5000) {
+    let settled = false;
+    const getTop = () => (target === window ? window.scrollY : target.scrollTop);
+    const startTop = getTop();
+
+    const settle = () => {
+      if (settled) return;
+      settled = true;
+      dispose();
+      onDone();
+    };
+
+    const onScrollEnd = () => settle();
+    const dispose = () => {
+      window.clearTimeout(timeoutId);
+      target.removeEventListener('scrollend', onScrollEnd);
+    };
+
+    target.addEventListener('scrollend', onScrollEnd, { once: true });
+    requestAnimationFrame(() => {
+      requestAnimationFrame(() => {
+        if (Math.abs(getTop() - startTop) < 1) settle();
+      });
+    });
+    const timeoutId = window.setTimeout(settle, maxWaitMs);
+
+    return () => {
+      settled = true;
+      dispose();
+    };
+  }
+
+  /**
+   * SYNC: client/src/shared/vis/GLTR_Text_Box.ts → scrollToUnicodeCharOffset
+   * （宿主页用 findScrollRoot 代替站内 panel）
+   */
+  function scrollToCpOffset(cp0, onScrollEnd, viewportYRatio = CHUNK_JUMP_VIEWPORT_Y_RATIO) {
+    scrollEndCancel?.();
+    scrollEndCancel = null;
+    requestAnimationFrame(() => {
+      const range = rangeFromCpOffsets(cp0, cp0 + 1) || rangeFromCpOffsets(cp0, Math.max(cp0 + 1, cp0));
+      let rect = null;
+      if (range) {
+        rect = range.getBoundingClientRect();
+        if (rect.width === 0 && rect.height === 0) {
+          const rects = range.getClientRects();
+          rect = rects.length ? rects[0] : null;
+        }
+      }
+      if (!rect || !extractRoot) {
+        onScrollEnd?.();
+        return;
+      }
+      const scrollRoot = findScrollRoot(extractRoot);
+      const isWindow =
+        scrollRoot === document.scrollingElement ||
+        scrollRoot === document.documentElement ||
+        scrollRoot === document.body;
+      if (isWindow) {
+        const y = window.scrollY + rect.top - window.innerHeight * viewportYRatio;
+        window.scrollTo({ top: Math.max(0, y), behavior: 'smooth' });
+        if (onScrollEnd) scrollEndCancel = waitForSmoothScrollEnd(window, onScrollEnd);
+        return;
+      }
+      const panel = /** @type {HTMLElement} */ (scrollRoot);
+      const panelRect = panel.getBoundingClientRect();
+      const topInPanel = rect.top - panelRect.top + panel.scrollTop;
+      const target = topInPanel - panel.clientHeight * viewportYRatio;
+      const maxScroll = Math.max(0, panel.scrollHeight - panel.clientHeight);
+      panel.scrollTo({ top: Math.max(0, Math.min(target, maxScroll)), behavior: 'smooth' });
+      if (onScrollEnd) scrollEndCancel = waitForSmoothScrollEnd(panel, onScrollEnd);
+    });
+  }
+
+  /** SYNC: GLTR_Text_Box.scrollToChunkStart（视口 0.2） */
+  function scrollToChunkStart(cp0, onScrollEnd) {
+    scrollToCpOffset(cp0, onScrollEnd, CHUNK_JUMP_VIEWPORT_Y_RATIO);
+  }
+
+  /** 分块搜索进行中：滚到 chunk 起点（视口 0.6）；站内 demo 已去掉跟随，仅扩展使用 */
+  function followSearchingChunk(cp0) {
+    if (chunkSearchAutoScrollUserCancelled) return;
+    scrollToCpOffset(cp0, undefined, CHUNK_SEARCH_FOLLOW_VIEWPORT_Y_RATIO);
+  }
+
+  /** 分块搜索：wheel/touch 取消自动跟随；站内 demo 已去掉，仅扩展使用 */
+  function beginChunkSearchAutoScroll() {
+    endChunkSearchAutoScroll();
+    chunkSearchAutoScrollUserCancelled = false;
+    if (!extractRoot) return;
+    const scrollRoot = findScrollRoot(extractRoot);
+    const isWindow =
+      scrollRoot === document.scrollingElement ||
+      scrollRoot === document.documentElement ||
+      scrollRoot === document.body;
+    const target = isWindow ? window : scrollRoot;
+    const opts = { passive: true, capture: true };
+    const onUserScroll = () => {
+      if (chunkSearchAutoScrollUserCancelled) return;
+      chunkSearchAutoScrollUserCancelled = true;
+      scrollEndCancel?.();
+      scrollEndCancel = null;
+    };
+    target.addEventListener('wheel', onUserScroll, opts);
+    target.addEventListener('touchstart', onUserScroll, opts);
+    chunkSearchAutoScrollCleanup = () => {
+      target.removeEventListener('wheel', onUserScroll, opts);
+      target.removeEventListener('touchstart', onUserScroll, opts);
+    };
+  }
+
+  function endChunkSearchAutoScroll() {
+    chunkSearchAutoScrollCleanup?.();
+    chunkSearchAutoScrollCleanup = undefined;
+    chunkSearchAutoScrollUserCancelled = false;
+  }
+
+  function delayMs(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  /**
+   * SYNC: client/src/shared/vis/GLTR_Text_Box.ts → jumpToChunkHighlight
+   * + client/src/features/analysis/semanticFindBar.ts → jumpTo
+   * 下划线 → 滚到起点 → hold → fade
+   */
+  function jumpToMatch(index) {
+    if (!matchedChunks.length) return;
+    const n = matchedChunks.length;
+    matchIndex = ((index % n) + n) % n;
+    revealChunk(matchedChunks[matchIndex]);
+    updateNav();
+  }
+
+  /**
+   * 选中并展示一个 chunk：进度图线变蓝 + 下划线 → 滚到起点 → hold → fade。
+   * 由「点击进度线」（selectProgressChunk）和「上下按钮跳转」（jumpToMatch）共用，
+   * 保证两者对进度图选中态的表现始终一致。
+   */
+  function revealChunk(chunk) {
+    setCurrentUnderline(chunk);
+    selectedProgressChunkStart = chunk.start;
+    progressSelectionFading = false;
+    renderSemanticMatchProgress();
+    // 导航态需要跟着刷新快照，否则关闭再打开搜索栏时，下划线（回退到旧快照）
+    // 会和进度图选中线（读实时变量）错位
+    if (lastResult) snapshotLastResult(lastResult.query);
+    scrollToChunkStart(chunk.start, () => {
+      underlineHoldTimer = window.setTimeout(() => {
+        underlineHoldTimer = 0;
+        fadeCurrentUnderline();
+      }, CHUNK_HIGHLIGHT_HOLD_MS);
+    });
+  }
+
+  // ---------- API ----------
+
+  /** 底层 JSON 请求（submode 须为后端合法值，不可传 hybrid） */
+  function analyzeSemanticRaw(query, text, opts) {
+    const body = {
+      query,
+      text,
+      stream: false,
+      privacy_mode: true,
+      ...(opts?.submode ? { submode: opts.submode } : {}),
+      ...(opts?.fullMatchDegreeOnly ? { full_match_degree_only: true } : {}),
+    };
+    return new Promise((resolve, reject) => {
+      chrome.runtime.sendMessage(
+        {
+          type: 'il-analyze-semantic',
+          apiBase: CFG.apiBase,
+          body,
+        },
+        (resp) => {
+          if (chrome.runtime.lastError) {
+            reject(new Error(chrome.runtime.lastError.message));
+            return;
+          }
+          if (!resp?.ok) reject(new Error(resp?.error || 'request failed'));
+          else resolve(resp.data);
+        }
+      );
+    });
+  }
+
+  /**
+   * SYNC: client GLTR_API.analyzeSemantic — hybrid 为前端组合：
+   * count(full_match_degree_only) → 未达阈值则空 token；达则再 fill_blank，保留 count 的 matchDegree。
+   */
+  async function analyzeSemantic(query, text) {
+    const submode = CFG.submode || 'hybrid';
+    if (submode === 'hybrid') {
+      const r1 = await analyzeSemanticRaw(query, text, {
+        submode: 'count',
+        fullMatchDegreeOnly: true,
+      });
+      if (r1?.success === false) return r1;
+      if ((r1.full_match_degree ?? 0) < CFG.matchThreshold) {
+        return { ...r1, token_attention: [] };
+      }
+      const r2 = await analyzeSemanticRaw(query, text, { submode: 'fill_blank' });
+      return { ...r2, full_match_degree: r1.full_match_degree };
+    }
+    return analyzeSemanticRaw(query, text, { submode });
+  }
+
+  // ---------- UI（同源 HTML/CSS，Shadow DOM 隔离宿主页样式） ----------
+
+  const STOP_ICON =
+    '<svg width="10" height="10" viewBox="0 0 10 10" aria-hidden="true"><rect x="1" y="1" width="8" height="8" rx="1" fill="currentColor"/></svg>';
+
+  const HOST_CSS = `
+:host {
+  all: initial;
+  position: fixed;
+  top: 12px;
+  right: 12px;
+  z-index: 2147483646;
+  display: block;
+  pointer-events: none;
+}
+.semantic-find-bar-host {
+  position: static;
+  margin: 0;
+  padding: 0;
+  z-index: auto;
+}
+.semantic-find-bar {
+  pointer-events: auto;
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", sans-serif;
+}
+`;
+
+  /** @type {ShadowRoot | null} */
+  let uiShadow = null;
+  let barWired = false;
+  /** 串行化首次构建，避免双击工具栏时 barWired 抢跑 */
+  /** @type {Promise<HTMLElement> | null} */
+  let barReady = null;
+
+  function ui$(id) {
+    return uiShadow?.getElementById(id) ?? null;
+  }
+
+  function uiQuery(sel) {
+    return uiShadow?.querySelector(sel) ?? null;
+  }
+
+  function resolveBarTheme() {
+    return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+  }
+
+  function applyBarTheme(bar) {
+    if (!bar) return;
+    bar.setAttribute('data-theme', resolveBarTheme());
+  }
+
+  function watchBarTheme(bar) {
+    const mq = window.matchMedia('(prefers-color-scheme: dark)');
+    const onScheme = () => applyBarTheme(bar);
+    mq.addEventListener('change', onScheme);
+  }
+
+  // ---------- 输入历史（对齐站内 queryHistory：聚焦/输入弹出、过滤、点选回填并搜索） ----------
+  const HISTORY_KEY = 'il_semantic_find_history';
+  const HISTORY_MAX = 8;
+  /** @type {string[]} */
+  let historyList = [];
+  /** @type {Promise<void> | null} */
+  let historyReady = null;
+
+  function ensureHistory() {
+    if (!historyReady) {
+      historyReady = chrome.storage.local.get(HISTORY_KEY).then((data) => {
+        const raw = data[HISTORY_KEY];
+        historyList = Array.isArray(raw)
+          ? raw.filter((s) => typeof s === 'string').slice(0, HISTORY_MAX)
+          : [];
+      });
+    }
+    return historyReady;
+  }
+
+  function persistHistory() {
+    return chrome.storage.local.set({ [HISTORY_KEY]: historyList });
+  }
+
+  function saveHistory(query) {
+    if (!query) return;
+    historyList = [query, ...historyList.filter((s) => s !== query)].slice(0, HISTORY_MAX);
+    void persistHistory();
+  }
+
+  function removeHistory(query) {
+    historyList = historyList.filter((s) => s !== query);
+    void persistHistory();
+  }
+
+  function hideHistoryDropdown() {
+    ui$('semantic_find_history_dropdown')?.classList.remove('is-visible');
+  }
+
+  function renderHistoryDropdown() {
+    const dropdown = ui$('semantic_find_history_dropdown');
+    const input = /** @type {HTMLInputElement | null} */ (ui$('semantic_find_input'));
+    if (!dropdown || !input || searching) {
+      hideHistoryDropdown();
+      return;
+    }
+    // 列表过滤：与站内一致不 trim；完全匹配当前输入的候选不展示
+    const filter = (input.value ?? '').toLowerCase();
+    const filtered = historyList.filter((s) => {
+      const sLower = s.toLowerCase();
+      if (sLower === filter) return false;
+      return !filter || sLower.includes(filter);
+    });
+    dropdown.innerHTML = '';
+    if (filtered.length === 0) {
+      hideHistoryDropdown();
+      return;
+    }
+    for (const q of filtered) {
+      const li = document.createElement('li');
+      const span = document.createElement('span');
+      span.className = 'history-text';
+      span.textContent = q;
+      span.title = q;
+      span.addEventListener('click', () => {
+        hideHistoryDropdown();
+        input.value = q;
+        input.dispatchEvent(new Event('input', { bubbles: true }));
+        void runSearch();
+      });
+      const btn = document.createElement('button');
+      btn.className = 'demo-delete-btn';
+      btn.type = 'button';
+      btn.textContent = '×';
+      btn.title = 'Remove';
+      btn.addEventListener('click', (e) => {
+        e.stopPropagation();
+        removeHistory(q);
+        renderHistoryDropdown();
+      });
+      li.appendChild(span);
+      li.appendChild(btn);
+      dropdown.appendChild(li);
+    }
+    dropdown.classList.add('is-visible');
+  }
+
+  function wireBar() {
+    if (barWired) return;
+    const findInput = /** @type {HTMLInputElement | null} */ (ui$('semantic_find_input'));
+    if (!findInput) throw new Error('find bar input missing');
+    barWired = true;
+
+    void ensureHistory();
+
+    ui$('semantic_find_prev')?.addEventListener('click', () =>
+      jumpToMatch(matchIndex < 0 ? matchedChunks.length - 1 : matchIndex - 1)
+    );
+    ui$('semantic_find_next')?.addEventListener('click', () =>
+      jumpToMatch(matchIndex < 0 ? 0 : matchIndex + 1)
+    );
+    ui$('semantic_find_close')?.addEventListener('click', () => close());
+    ui$('semantic_find_clear')?.addEventListener('click', (e) => {
+      e.stopPropagation();
+      if (searching) {
+        abortWanted = true;
+        // 按钮立即回退，不等最后一个 chunk 的请求返回
+        syncClearButton(false);
+        return;
+      }
+      findInput.value = '';
+      findInput.dispatchEvent(new Event('input', { bubbles: true }));
+      findInput.focus();
+    });
+    findInput.addEventListener('focus', () => {
+      void ensureHistory().then(renderHistoryDropdown);
+    });
+    findInput.addEventListener('input', () => {
+      if (searching) return;
+      // 输入框内容一变（无论是手改还是点 × 清空），旧的渲染状态即视为过期，统一清掉
+      resetSearchSession({ clearCache: true });
+      syncClearButton(false);
+      if (uiShadow?.activeElement === findInput) renderHistoryDropdown();
+    });
+    findInput.addEventListener('keydown', (e) => {
+      if (e.key === 'Enter' && !e.isComposing) {
+        e.preventDefault();
+        hideHistoryDropdown();
+        void runSearch();
+      } else if (e.key === 'Escape') {
+        e.preventDefault();
+        e.stopPropagation();
+        close();
+      }
+    });
+    document.addEventListener('click', (e) => {
+      const bar = ui$('semantic_find_bar');
+      if (!bar || e.composedPath().includes(bar)) return;
+      hideHistoryDropdown();
+    });
+  }
+
+  function syncClearButton(searchingOn) {
+    const btn = ui$('semantic_find_clear');
+    const input = /** @type {HTMLInputElement | null} */ (ui$('semantic_find_input'));
+    if (!btn) return;
+    if (searchingOn) {
+      btn.classList.add('is-stop', 'is-visible');
+      btn.innerHTML = STOP_ICON;
+      btn.title = 'Stop';
+      btn.setAttribute('aria-label', 'Stop');
+    } else {
+      btn.classList.remove('is-stop');
+      btn.textContent = '×';
+      btn.title = 'Clear';
+      btn.setAttribute('aria-label', 'Clear');
+      btn.classList.toggle('is-visible', (input?.value ?? '').length > 0);
+    }
+  }
+
+  async function buildBar() {
+    let host = document.getElementById('il-find-root');
+    const existing = /** @type {HTMLElement | null} */ (
+      host?.shadowRoot?.getElementById('semantic_find_bar') ?? null
+    );
+    if (existing) {
+      uiShadow = host.shadowRoot;
+      applyBarTheme(existing);
+      wireBar();
+      return existing;
+    }
+    // 上次构建失败可能留下空 host
+    host?.remove();
+
+    host = document.createElement('div');
+    host.id = 'il-find-root';
+    document.documentElement.appendChild(host);
+    uiShadow = host.attachShadow({ mode: 'open' });
+
+    try {
+      const [cssText, html] = await Promise.all([
+        fetch(chrome.runtime.getURL('ui/semantic-find-bar.css')).then((r) => {
+          if (!r.ok) throw new Error(`failed to load find bar css (${r.status})`);
+          return r.text();
+        }),
+        fetch(chrome.runtime.getURL('ui/semantic-find-bar.html')).then((r) => {
+          if (!r.ok) throw new Error(`failed to load find bar html (${r.status})`);
+          return r.text();
+        }),
+      ]);
+
+      const style = document.createElement('style');
+      style.textContent = HOST_CSS + '\n' + cssText;
+      uiShadow.appendChild(style);
+
+      const wrap = document.createElement('div');
+      wrap.innerHTML = html.trim();
+      const bar = /** @type {HTMLElement} */ (wrap.firstElementChild);
+      if (!bar) throw new Error('find bar html empty');
+      applyBarTheme(bar);
+      watchBarTheme(bar);
+      uiShadow.appendChild(bar);
+
+      wireBar();
+      return bar;
+    } catch (err) {
+      host.remove();
+      uiShadow = null;
+      barWired = false;
+      throw err;
+    }
+  }
+
+  function ensureBar() {
+    if (!barReady) {
+      barReady = buildBar().catch((err) => {
+        barReady = null;
+        throw err;
+      });
+    }
+    return barReady;
+  }
+
+  function updateNav() {
+    const prev = /** @type {HTMLButtonElement | null} */ (ui$('semantic_find_prev'));
+    const next = /** @type {HTMLButtonElement | null} */ (ui$('semantic_find_next'));
+    const disabled = matchedChunks.length === 0;
+    if (prev) prev.disabled = disabled;
+    if (next) next.disabled = disabled;
+  }
+
+  /** 简版 semantic match progress：全文位置 × chunk 匹配度。 */
+  function renderSemanticMatchProgress() {
+    const chart = ui$('semantic_match_progress');
+    const lines = ui$('semantic_match_progress_lines');
+    if (!(chart instanceof SVGSVGElement) || !(lines instanceof SVGGElement)) return;
+
+    const hidden = semanticMatchProgress.length === 0 || extractedText.length === 0;
+    chart.toggleAttribute('hidden', hidden);
+    if (hidden) {
+      lines.replaceChildren();
+      return;
+    }
+
+    const width = Math.max(100, Math.round(chart.clientWidth));
+    const height = Math.max(42, Math.round(chart.clientHeight));
+    chart.setAttribute('viewBox', `0 0 ${width} ${height}`);
+    const x0 = 4;
+    const x1 = width - 4;
+    const y0 = height - 7;
+    const y1 = 4;
+    const textLength = progressTextLength || [...extractedText].length;
+    const groupsByStart = new Map(
+      [...lines.children]
+        .filter((el) => el instanceof SVGGElement && el.dataset.progressStart != null)
+        .map((el) => [Number(el.dataset.progressStart), el])
+    );
+    const liveStarts = new Set();
+
+    for (const chunk of semanticMatchProgress) {
+      const degree = Math.max(0, Math.min(1, Number(chunk.matchDegree) || 0));
+      const start = x0 + ((x1 - x0) * chunk.start) / textLength;
+      const end = x0 + ((x1 - x0) * chunk.end) / textLength;
+      const y = y0 - (y0 - y1) * degree;
+      liveStarts.add(chunk.start);
+      let group = groupsByStart.get(chunk.start);
+      if (!group) {
+        group = document.createElementNS('http://www.w3.org/2000/svg', 'g');
+        group.dataset.progressStart = String(chunk.start);
+
+        const line = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+        line.classList.add('semantic-match-progress-line');
+        group.appendChild(line);
+
+        const label = document.createElementNS('http://www.w3.org/2000/svg', 'text');
+        label.classList.add('semantic-match-progress-label');
+        label.setAttribute('text-anchor', 'middle');
+        label.setAttribute('hidden', '');
+        group.appendChild(label);
+
+        const hitArea = document.createElementNS('http://www.w3.org/2000/svg', 'rect');
+        hitArea.classList.add('semantic-match-progress-hit-area');
+        hitArea.addEventListener('mouseenter', () => {
+          setHoveredProgressChunk(chunk.start);
+        });
+        hitArea.addEventListener('mouseleave', () => {
+          if (hoveredProgressChunkStart === chunk.start) setHoveredProgressChunk(null);
+        });
+        hitArea.addEventListener('pointerdown', (event) => {
+          event.preventDefault();
+          event.stopPropagation();
+          /** @type {HTMLInputElement | null} */ (ui$('semantic_find_input'))?.blur();
+          selectProgressChunk(chunk.start);
+        });
+        group.appendChild(hitArea);
+        lines.appendChild(group);
+      }
+
+      const line = /** @type {SVGPathElement} */ (group.querySelector('.semantic-match-progress-line'));
+      const label = /** @type {SVGTextElement} */ (group.querySelector('.semantic-match-progress-label'));
+      const hitArea = /** @type {SVGRectElement} */ (group.querySelector('.semantic-match-progress-hit-area'));
+      line.classList.toggle('is-below-threshold', degree < CFG.matchThreshold);
+      line.classList.toggle('is-selected', selectedProgressChunkStart === chunk.start);
+      line.classList.toggle('is-hovered', hoveredProgressChunkStart === chunk.start);
+      line.classList.toggle(
+        'is-fading',
+        progressSelectionFading && selectedProgressChunkStart === chunk.start
+      );
+      const lineStart = start;
+      const lineEnd = end;
+      line.setAttribute('d', `M${lineStart} ${y}H${lineEnd}`);
+      label.setAttribute('x', String((start + end) / 2));
+      label.setAttribute('y', String(Math.max(y1 + 10, y - 4)));
+      label.textContent = `${Math.round(degree * 100)}%`;
+      label.toggleAttribute('hidden', hoveredProgressChunkStart !== chunk.start);
+      hitArea.setAttribute('x', String(start));
+      hitArea.setAttribute('y', String(y1));
+      hitArea.setAttribute('width', String(Math.max(0.35, end - start)));
+      hitArea.setAttribute('height', String(y0 - y1));
+    }
+    for (const [start, group] of groupsByStart) {
+      if (!liveStarts.has(start)) group.remove();
+    }
+  }
+
+  function setHoveredProgressChunk(start) {
+    if (hoveredProgressChunkStart === start) return;
+    const lines = ui$('semantic_match_progress_lines');
+    if (!(lines instanceof SVGGElement)) return;
+    const previous = hoveredProgressChunkStart;
+    hoveredProgressChunkStart = start;
+    for (const chunkStart of [previous, start]) {
+      if (chunkStart == null) continue;
+      const group = [...lines.children].find((el) => el.dataset.progressStart === String(chunkStart));
+      group
+        ?.querySelector('.semantic-match-progress-line')
+        ?.classList.toggle('is-hovered', chunkStart === start);
+      const label = group?.querySelector('.semantic-match-progress-label');
+      label?.toggleAttribute('hidden', chunkStart !== start);
+    }
+  }
+
+  function selectProgressChunk(start) {
+    const chunk = semanticMatchProgress.find((item) => item.start === start);
+    if (!chunk) return;
+    if (selectedProgressChunkStart === start) {
+      selectedProgressChunkStart = null;
+      setCurrentUnderline(null);
+      renderSemanticMatchProgress();
+      if (lastResult) snapshotLastResult(lastResult.query);
+    } else {
+      revealChunk(chunk);
+    }
+  }
+
+  function setSearching(on) {
+    searching = on;
+    const chromeBar = uiQuery('.semantic-find-bar');
+    chromeBar?.classList.toggle('is-searching', on);
+    const input = /** @type {HTMLInputElement | null} */ (ui$('semantic_find_input'));
+    if (input) {
+      input.readOnly = on;
+      if (on) input.blur();
+    }
+    ui$('semantic_find_history_dropdown')?.classList.remove('is-visible');
+    chromeBar?.classList.remove('is-input-active');
+    syncClearButton(on);
+  }
+
+  async function runSearch() {
+    if (searching) {
+      abortWanted = true;
+      syncClearButton(false);
+      return;
+    }
+    const query = /** @type {HTMLInputElement} */ (ui$('semantic_find_input'))?.value?.trim() || '';
+    if (!query) {
+      return;
+    }
+
+    await ensureHistory();
+    saveHistory(query);
+
+    abortWanted = false;
+    setSearching(true);
+    resetSearchSession();
+
+    try {
+      refreshExtract();
+    } catch (err) {
+      console.error('[InfoLens] extract aborted:', err?.message || err);
+      setSearching(false);
+      return;
+    }
+    if (!extractedText.trim()) {
+      console.error('[InfoLens] no article text found');
+      setSearching(false);
+      return;
+    }
+
+    try {
+      // 全空白 chunk 不送 API；先滤再截断，避免 maxChunks 被空白占满
+      const allChunks = splitChunks(extractedText, CFG.chunkBytes)
+        .filter(chunkHasContent)
+        .slice(0, CFG.maxChunks);
+      progressTextLength = allChunks.length
+        ? utf16ToCp(extractedText, allChunks[allChunks.length - 1].end)
+        : 0;
+
+      // SYNC：站内 truncated-text — 搜索开始全文置灰，随已分析边界后移恢复原色
+      setTruncatedHighlight(0);
+
+      // 产品决策：扩展保留预取/hold/follow；站内 demo 刻意简化为「上色 → 结束跳首个匹配」（见 semanticSearchController），两边不必对齐。
+      // followSearching=true 全程跟随；false=无 match 前跟随、首个 match 停靠划线
+      const followAll = !!CFG.followSearching;
+      let parkedOnFirstMatch = false;
+      let analyzedCpEnd = 0;
+      beginChunkSearchAutoScroll();
+
+      // 双循环流水线：抓取循环只管领先渲染 FETCH_AHEAD 步尽早发请求，不含任何延迟；
+      // 渲染循环按 chunk 顺序消费结果、维持 CHUNK_SEARCH_MIN_CYCLE_MS 展示节奏——二者互不阻塞，
+      // 停留只影响「多久展示下一块」，不再卡住下一次请求的发出时机
+      const FETCH_AHEAD = 1;
+      const pendingChunkResults = new Map();
+      let fetchCursor = 0;
+      const prefetchChunk = (idx) => {
+        const p = analyzeSemantic(query, allChunks[idx].text);
+        p.catch(() => {}); // 真正的错误仍会在被 await 时抛出，这里只是防止预取阶段的悬空 rejection 噪音
+        pendingChunkResults.set(idx, p);
+      };
+      const advanceFetch = (renderIndex) => {
+        while (!abortWanted && fetchCursor < allChunks.length && fetchCursor <= renderIndex + FETCH_AHEAD) {
+          prefetchChunk(fetchCursor);
+          fetchCursor++;
+        }
+      };
+      advanceFetch(0); // 预热：抓取 [0, FETCH_AHEAD]
+
+      try {
+        for (let i = 0; i < allChunks.length; i++) {
+          if (abortWanted) {
+            break;
+          }
+          const chunk = allChunks[i];
+          const res = await pendingChunkResults.get(i);
+          pendingChunkResults.delete(i);
+          if (abortWanted) break;
+
+          const degree = res.full_match_degree ?? 0;
+          // SYNC: semanticSearchController — matched = degree >= threshold；未匹配块不上色
+          const matched = degree >= CFG.matchThreshold;
+          const chunkCpStart = utf16ToCp(extractedText, chunk.start);
+          const chunkCpEnd = utf16ToCp(extractedText, chunk.end);
+          analyzedCpEnd = Math.max(analyzedCpEnd, chunkCpEnd);
+          semanticMatchProgress.push({
+            start: chunkCpStart,
+            end: chunkCpEnd,
+            matchDegree: degree,
+          });
+          renderSemanticMatchProgress();
+
+          // 跟随判定用「本块入列前」是否已有匹配
+          const hadMatchBefore = matchedChunks.length > 0;
+          // 未勾选 Follow：首个匹配处停下并划线；勾选则全程跟随，结束再跳首个匹配
+          const willJump = !followAll && matched && !parkedOnFirstMatch;
+
+          if (matched) {
+            matchedChunks.push({
+              start: chunkCpStart,
+              end: chunkCpEnd,
+              matchDegree: degree,
+            });
+          }
+
+          // SYNC: semanticSearchController — 仅匹配块上色（未匹配等价 score:0）
+          const tokens = matched ? prepareChunkTokens(res.token_attention || [], chunk.text, degree) : [];
+          for (const t of tokens) {
+            if (!t.offset || !(t.score > 0)) continue;
+            const [a, b] = t.offset;
+            const level = scoreToLevel(t.score);
+            if (level < 0) continue;
+            paintSpec('token', chunkCpStart + a, chunkCpStart + b, level);
+          }
+          setTruncatedHighlight(analyzedCpEnd);
+          // SYNC: visualizationUpdater 流式更新 → clearHighlights({ preserveChunkInterval: true })
+          renderAllSpecs({
+            preserveUnderline: paintSpecs.some((s) => s.kind === 'underline'),
+          });
+
+          // followThis = followAll || !hadMatchBefore；willJump 块滚动延后到 hold 后（扩展节奏，非站内）
+          if ((followAll || !hadMatchBefore) && !willJump) {
+            followSearchingChunk(chunkCpStart);
+          }
+          // 每块后快照：close 中途清高亮时仍保留上一版
+          snapshotLastResult(query);
+
+          // 渲染完立即放行抓取循环（不等 hold），避免网络/服务器因停留而空闲
+          advanceFetch(i + 1);
+
+          // 首个匹配块也要先经过与其它块一致的 hold，再触发自动滚动，
+          // 避免着色刚出现就被立刻滚走——即使命中的正好是最后一块
+          const nextIndex = i + 1;
+          // shouldFollow = followAll || !hasMatch；park 后不再滚动/settle，hold 撑满 MIN_CYCLE（扩展节奏）
+          const willSettleAfterHold =
+            willJump || (nextIndex < allChunks.length && (followAll || !parkedOnFirstMatch));
+          if (willJump || nextIndex < allChunks.length) {
+            await delayMs(willSettleAfterHold ? CHUNK_SEARCH_HOLD_MS : CHUNK_SEARCH_MIN_CYCLE_MS);
+            if (abortWanted) break;
+          }
+          if (willJump) {
+            jumpToMatch(0);
+            parkedOnFirstMatch = true;
+            // 跳转落点同样要停留够 CHUNK_SEARCH_SCROLL_SETTLE_MS，避免划线刚定位就被下一块的渲染打断
+            await delayMs(CHUNK_SEARCH_SCROLL_SETTLE_MS);
+            if (abortWanted) break;
+          }
+          if (nextIndex < allChunks.length && (followAll || !parkedOnFirstMatch)) {
+            const nextChunk = allChunks[nextIndex];
+            followSearchingChunk(utf16ToCp(extractedText, nextChunk.start));
+            // 滚动后的新位置也要停留够 CHUNK_SEARCH_SCROLL_SETTLE_MS，
+            // 否则分析过快时会出现「刚滚过去就立刻变色」的突变感；抓取循环已提前放行，不受影响
+            await delayMs(CHUNK_SEARCH_SCROLL_SETTLE_MS);
+            if (abortWanted) break;
+          }
+        }
+      } finally {
+        endChunkSearchAutoScroll();
+      }
+
+      if (extractRoot != null) {
+        setTruncatedHighlight(analyzedCpEnd);
+        renderAllSpecs({
+          preserveUnderline: paintSpecs.some((s) => s.kind === 'underline'),
+        });
+        if (!abortWanted) {
+          if (matchedChunks.length && !parkedOnFirstMatch) jumpToMatch(0);
+          else updateNav();
+        }
+      }
+      snapshotLastResult(query);
+    } catch (err) {
+      console.error('[InfoLens]', err?.message || err);
+      snapshotLastResult(query);
+    } finally {
+      setSearching(false);
+      abortWanted = false;
+    }
+  }
+
+  /** 目测提取：按 chunk 分块，走 paintAllUnderlines；定根失败则放弃 */
+  function previewExtractUnderlines() {
+    let info;
+    try {
+      info = refreshExtract();
+    } catch (err) {
+      clearOverlays();
+      extractedText = '';
+      setPieces([]);
+      matchedChunks = [];
+      matchIndex = -1;
+      console.error('[InfoLens] extract aborted:', err?.message || err);
+      return null;
+    }
+    if (!extractedText.trim()) {
+      console.error('[InfoLens] extract aborted: empty article text');
+      return info;
+    }
+    const allChunks = splitChunks(extractedText, CFG.chunkBytes).filter(chunkHasContent);
+    matchedChunks = allChunks.map((chunk) => ({
+      start: utf16ToCp(extractedText, chunk.start),
+      end: utf16ToCp(extractedText, chunk.end),
+      matchDegree: 1,
+    }));
+    matchIndex = -1;
+    paintAllUnderlines();
+    console.info(
+      `[InfoLens] extract preview · ~${info.length} chars · ${allChunks.length} chunk(s) · ${overlayEls.length} rects`,
+      { root: info.root, scrollRoot: findScrollRoot(info.root) }
+    );
+    return info;
+  }
+
+  async function open() {
+    try {
+      if (DOM_DEBUG) {
+        // 再次点击：取消下划线
+        if (paintSpecs.length > 0 || overlayEls.length > 0) {
+          close();
+          console.info('[InfoLens] extract preview cleared');
+          return;
+        }
+        previewExtractUnderlines();
+        return;
+      }
+      const bar = await ensureBar();
+      if (!bar) throw new Error('find bar missing');
+      bar.hidden = false;
+      const input = /** @type {HTMLInputElement} */ (ui$('semantic_find_input'));
+      // 仅同步 UI（× 按钮可见性），不走 'input' 统一清空路径：reopen 要保留上次渲染结果给下面 tryRestoreLastResult 用
+      syncClearButton(false);
+      input?.focus();
+      input?.select();
+      try {
+        refreshExtract();
+        renderSemanticMatchProgress();
+        tryRestoreLastResult(input?.value?.trim() || '');
+      } catch (err) {
+        console.error('[InfoLens] extract aborted:', err?.message || err);
+        throw err;
+      }
+    } catch (err) {
+      console.error('[InfoLens]', err);
+    }
+  }
+
+  function close() {
+    abortWanted = true;
+    resetSearchSession();
+    hideHistoryDropdown();
+    const bar = ui$('semantic_find_bar');
+    if (bar) {
+      bar.hidden = true;
+      uiQuery('.semantic-find-bar')?.classList.remove('is-input-active', 'is-searching');
+    }
+    setSearching(false);
+  }
+
+  /** 上次注入已过期（重装扩展未刷新页面）需整个丢弃时调用：close() 之外，摘掉本实例注册在 window 上的监听器 */
+  function destroy() {
+    close();
+    window.removeEventListener('scroll', scheduleSyncPaintAfterLayout, true);
+    window.removeEventListener('scrollend', syncPaintAfterLayout, true);
+    window.removeEventListener('resize', scheduleReflow);
+    window.visualViewport?.removeEventListener('resize', scheduleReflow);
+  }
+
+  // underline 与正文同层滚动；token/truncated 为 CSS Highlight。布局漂移时重绑 Range / 重测 underline。
+  window.addEventListener('scroll', scheduleSyncPaintAfterLayout, true);
+  window.addEventListener('scrollend', syncPaintAfterLayout, true);
+  window.addEventListener('resize', () => {
+    scheduleReflow();
+    renderSemanticMatchProgress();
+  });
+  window.visualViewport?.addEventListener('resize', scheduleReflow);
+
+  window.__IL_SEMANTIC_DEMO__ = { open, close, destroy };
+  void open();
+})();

extension/dev-env.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+# 仅切换 apiBase（local=本机后端 / prod=HF Spaces）。两者都属于 unpacked 开发版，
+# 图标与商店版无关：本目录固定用 icons/dev/（绿角标），见 manifest.json。
+# config.js 由本脚本生成（gitignore），Chrome unpacked 实际加载它；
+# 源头是 config.prod.js / config.local.js。上架包由 pack.sh 直接用 config.prod.js。
+# 用法：
+#   ./dev-env.sh local   # 生成本地变体
+#   ./dev-env.sh prod    # 生成上架默认值
+set -euo pipefail
+cd "$(dirname "${BASH_SOURCE[0]}")"
+
+case "${1:-}" in
+  local)
+    cp config.local.js config.js
+    echo "已切到 local：apiBase=127.0.0.1:5001。去 chrome://extensions 重新加载生效。"
+    ;;
+  prod)
+    cp config.prod.js config.js
+    echo "已切回 prod：apiBase=HF Spaces。去 chrome://extensions 重新加载生效。"
+    ;;
+  *)
+    echo "用法: $0 local|prod" >&2
+    exit 1
+    ;;
+esac