argo-search 1.0.1 → 2.9.7

package/sub-skills/local-seek/scripts/seek_rank.py

@@ -0,0 +1,193 @@
+#!/usr/bin/env python3
+"""seek_rank.py — local-seek 的内容命中相关度重排（BM25F + BM25+，零依赖）。
+
+为什么存在：rg_search 此前按 (路径,行号) 有界堆选池——那是 2026-10-06 为治
+「rg 发射序不确定」引入的**确定性**口径，但它自身无内容相关性：多词查询的
+top5 常被配置/文档里的顺带提及占满，真正的实现文件进不了前五（2026-10-07
+eval_rank 基线实测，11 用例 topk_hit 5/11、MRR 0.36）。本模块在**同一个
+确定性池**（cap ≤400、与发射序无关）内做相关度重排：池子怎么选不变，
+只变池内的呈现次序——确定性契约（tests/test_determinism_20261006.py）
+由此延续：打分只依赖 (路径, 行号, 行文本, 查询)，并列分按 (路径, 行号)
+升序决出稳定次序。
+（本 docstring 刻意不举具体查询例：本文件就在被搜语料里，注释出现常见
+查询原词会给 eval 制造自污染。）
+
+算法（两件套）：
+  BM25F  Robertson / Zaragoza / Taylor, "Simple BM25 extension to multiple
+         weighted fields" (CIKM 2004)。取 Lucene 式**逐字段 BM25 加权求和**
+         的近似（k1/b 按字段独立），对 ≤400 条的小语料池与全域式等价且更简单。
+  BM25+  Lv & Zhai, "Lower-Bounding Term Frequency Normalization"
+         (ICTIR 2011)。TF 项加下界 δ——修正 BM25 对短字段（文件名通常只有
+         几个词）的过度惩罚，保证「字段命中即有底分」。
+
+字段（文件命中行的三元结构）：
+  name  文件名（额外做 camelCase 细分）    weight 2.0, b 0.3（短字段弱归一）
+  dir   父目录段（同上）                  weight 0.6, b 0.3
+  line  命中行文本                        weight 1.0, b 0.75（长字段强归一）
+
+切词口径（与 local-search/bm25.py **同源不同形**，分叉原因见下）：
+  - 全部字段与查询共用 T1：字母数字连续串小写 + CJK 连续串二元组
+    （单字串出单字；范围沿用 seek.CJK_RE，含假名/谚文）。
+    下划线/点号是**分隔符**——「cache_key_vdom」「node.js」必须切得开，
+    否则文件名字段对这类查询永远失配（首版踩过：T1 保留 _ 时
+    「cache_key_vdom」整体成词，文件名字段全灭）。
+  - name/dir 额外收录 camelCase 细分词（驼峰名拆成子词，查询侧同样收录），
+    让「分写的多个子词」也能命中连写的驼峰文件名。
+  - 与 bm25.py 的分叉原因：那边服务「引擎聚合结果」（title+snippet+引擎
+    位次先验混合），这边服务「文件命中行」（path+line，无位次先验）；
+    且 local-seek 不 import 兄弟子技能（零依赖纪律）。两文件 docstring
+    互相指认，防无人知晓的分叉漂移。
+
+逃生门：ARGO_SEEK_CONTENT_RERANK=0 时 seek.py 不调用本模块；查询切不出
+词元（正则/纯符号）时调用方跳过——两种情况行为与改动前逐位一致。
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from collections import Counter
+
+_CJK_RUN = r"[\u3400-\u4dbf\u4e00-\u9fff\u3040-\u30ff\uac00-\ud7af]+"
+# T1 主切词：字母数字连续串（不含 _ . 等分隔符）+ CJK 连续串
+_RUN_RE = re.compile(r"[A-Za-z0-9]+|" + _CJK_RUN)
+# camelCase 细分：小写/数字段、大写段（后随小写时取「大写+小写尾巴」）
+_CAMEL_RE = re.compile(r"[a-z0-9]+|[A-Z](?=[a-z])[a-z]*|[A-Z]+(?![a-z])")
+_CJK_ONLY_RE = re.compile("^" + _CJK_RUN + "$")
+
+# BM25 常数（与 local-search/bm25.py 同口径：Okapi k1=1.5 b=0.75）
+_K1 = 1.5
+_DELTA = 1.0          # BM25+ 下界（Lv & Zhai 2011）
+
+# 字段权重与长度归一化强度：文件名命中最值钱（「文件恰好叫这个」是强意图
+# 信号）；目录段最弱（scripts/tests 这类段名人人都有，IDF 会自动压它）。
+# 短字段 b 调低：avgdl 只有几个词，强归一化会把略长文件名的分数压没。
+_FIELDS = (
+    ("name", 2.0, 0.3),
+    ("dir", 0.6, 0.3),
+    ("line", 1.0, 0.75),
+)
+
+# 文件级命中数先验：同一文件在池里命中多行（_TOPIC_PRIOR_WEIGHT × ln(1+n)）
+# 比「只顺带提及一行」更可能是「关于这个主题」的文件——经典 IR 的文档级
+# 词项证据在行粒度输出上的等价物。对数封口：命中 100 行的文件也不会把
+# 单行全覆盖的文档按在地上。典型量级 +2~+5 分，够翻「部分命中 vs 全覆盖
+# 单行」的中位对决，翻不了强覆盖单行的 top1。
+_TOPIC_PRIOR_WEIGHT = 1.2
+
+# 逐字短语加成：查询里的完整 CJK 连续串（≥2 字）或 ASCII 词（≥3 字符）在
+# 行文本里**逐字出现**时加分。动机：二元组切词分不清「噪声档的实现行」和
+# 「顺带提到噪声二字的无关文档」——逐字出现是词面层能给出的最强信号
+# （Lucene 短语加成的手搓等价物，零分词器依赖）。每短语一份、封顶两份，
+# 量级与一个中频词元命中相当，够翻二元组的歧义、翻不了多词全覆盖行。
+_PHRASE_BONUS = 3.0
+_PHRASE_BONUS_CAP = 6.0
+
+
+def _split_camel(run: str) -> list[str]:
+    """驼峰细分：BM25Okapi → bm / 25 / okapi（小写输出；无驼峰则空）。"""
+    if run.islower() or run.isdigit():
+        return []
+    return [m.group(0).lower() for m in _CAMEL_RE.finditer(run)]
+
+
+def _tokens(text: str, *, camel: bool = False) -> list[str]:
+    """T1 切词；camel=True 时对每个 ASCII 段追加驼峰细分词。"""
+    out: list[str] = []
+    for m in _RUN_RE.finditer(text):
+        run = m.group(0)
+        if run.isascii():
+            out.append(run.lower())
+            if camel:
+                out.extend(_split_camel(run))
+        elif len(run) == 1:
+            out.append(run)
+        else:
+            out.extend(run[i:i + 2] for i in range(len(run) - 1))
+    return out
+
+
+def _row_fields(fp: str, text: str) -> dict[str, Counter]:
+    """一行命中在三字段下的词频表。fp 无目录段时 dir 为空表。"""
+    fp = fp.rstrip("/")
+    name, _, dirpart = fp.rpartition("/")
+    fields = {
+        "name": Counter(_tokens(name, camel=True)),
+        "dir": Counter(_tokens(dirpart, camel=True)),
+        "line": Counter(_tokens(text or "")),
+    }
+    return fields
+
+
+def rank_rows(rows: list[tuple[str, int, str]], raw_query: str,
+              boost_fn=None) -> list[tuple[str, int, str]]:
+    """BM25F 重排：返回相关度降序的新列表（并列分按 (路径, 行号) 升序）。
+
+    rows 是 rg_search 有界池的 (路径, 行号, 截断行文本) 三元组（≤400 条）。
+    查询切不出词元时原样返回——正则/纯符号查询没有相关性信号可算。
+
+    boost_fn：可选的 (路径 → 加成分) 注入点，供 seek.py 在
+    ARGO_SEEK_FRECENCY=1 时传入访问频次加成（见 seek_frecency.py）。
+    本模块保持无状态，不感知任何使用信号。
+    """
+    q_tf = Counter(_tokens(raw_query or "", camel=True))
+    if not q_tf or not rows:
+        return rows
+
+    # 逐字短语表：完整 CJK 连续串 + 较长 ASCII 连续串（行文本做子串检查用）
+    phrases = [m.group(0).lower()
+               for m in re.finditer(r"[A-Za-z0-9_\-+#.]{3,}|" + _CJK_RUN,
+                                    raw_query or "")]
+    phrases = list(dict.fromkeys(phrases))
+
+    row_fields = [_row_fields(fp, txt) for fp, _ln, txt in rows]
+    n_rows = len(row_fields)
+    avgdl: dict[str, float] = {}
+    for f, _w, _b in _FIELDS:
+        total = sum(sum(row_fields[i][f].values()) for i in range(n_rows))
+        avgdl[f] = (total / n_rows) or 1.0
+
+    # 文件级命中数：池内同路径的行数（对数先验，见 _TOPIC_PRIOR_WEIGHT）
+    file_hits: Counter = Counter(fp for fp, _ln, _txt in rows)
+
+    # 文档频率：每字段一次遍历（行数 × 行内词元数，池 ≤400 时毫秒级）
+    df: dict[str, Counter] = {f: Counter() for f, _w, _b in _FIELDS}
+    for f, _w, _b in _FIELDS:
+        f_df = df[f]
+        for f_tf in row_fields:
+            for term in f_tf[f]:
+                f_df[term] += 1
+
+    scores: list[float] = []
+    for i, f_tf in enumerate(row_fields):
+        total = 0.0
+        for f, w, b in _FIELDS:
+            tf_map = f_tf[f]
+            if not tf_map:
+                continue
+            dl = sum(tf_map.values())
+            norm = _K1 * (1.0 - b + b * dl / avgdl[f])
+            f_df = df[f]
+            for qt, qtf in q_tf.items():
+                tf = tf_map.get(qt)
+                if not tf:
+                    continue
+                idf = math.log(1.0 + (n_rows - f_df[qt] + 0.5) / (f_df[qt] + 0.5))
+                # BM25+：饱和项加下界 δ（只对命中的词，未命中不送底分）
+                sat = (tf * (_K1 + 1.0)) / (tf + norm)
+                total += w * qtf * (sat + _DELTA) * idf
+        total += _TOPIC_PRIOR_WEIGHT * math.log1p(file_hits[rows[i][0]])
+        if phrases:
+            low = (rows[i][2] or "").lower()
+            hits = sum(1 for ph in phrases if ph in low)
+            total += min(hits, 2) * _PHRASE_BONUS
+        if boost_fn is not None:
+            try:
+                total += boost_fn(rows[i][0])
+            except Exception:
+                pass  # 注入的加成失败不拖累打分本体
+        scores.append(total)
+
+    order = sorted(range(n_rows),
+                   key=lambda i: (-scores[i], rows[i][0], rows[i][1]))
+    return [rows[i] for i in order]

package/sub-skills/local-seek/tests/test_content_rank.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+"""tests/test_content_rank.py — 内容 BM25F 重排 + fzf V2 评分契约（2026-10-07 方案甲）。
+
+守四类不变式：
+  A. 重排闸门：逃生门/正则查询/count/context 一律保持 (路径,行号) 原序
+  B. 重排质量：文件名命中 > 纯行命中；多词全覆盖 > 单词擦边；噪声档
+     分层在重排后依然成立（真源在前）
+  C. 确定性：打分只依赖内容，发射序打乱输出逐位一致（2026-10-06 契约延续）
+  D. fzf V2：边界/驼峰/连续/gap 惩罚的相对次序与 fzf 口径一致，全等最优
+
+打桩纪律：unittest.mock.patch.object（自动恢复）——直接给 s.run 赋值且
+不恢复会把同进程后续测试的真实 rg 顶掉（2026-10-06 实锤教训，见
+test_determinism_20261006.py 模块头）。
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT / "scripts"))
+
+import seek as s  # noqa: E402
+import seek_rank as r  # noqa: E402
+
+
+def _proc(stdout: str, rc: int = 0) -> subprocess.CompletedProcess:
+    return subprocess.CompletedProcess(args=[], returncode=rc,
+                                       stdout=stdout, stderr="")
+
+
+class TestRerankGate(unittest.TestCase):
+    """A. 闸门：不该重排的场景必须保持 (路径,行号) 原序。"""
+
+    ROWS = [
+        ("b/beta.py", 5, "alpha"),
+        ("a/alpha.py", 9, "alpha"),
+        ("c/gamma.md", 1, "alpha"),
+    ]
+
+    def _search(self, raw_query, fixed=True, ctx=0, count=False):
+        with patch.object(s, "run", return_value=_proc("a/x.py:1:hit\n")):
+            # 直接对池行调用重排闸门（不走 rg，隔离网络与文件系统）
+            return s._rerank_content(list(self.ROWS), raw_query, ctx, count, fixed)
+
+    def test_escape_hatch_restores_order(self):
+        import os
+        old = os.environ.pop("ARGO_SEEK_CONTENT_RERANK", None)
+        os.environ["ARGO_SEEK_CONTENT_RERANK"] = "0"
+        try:
+            self.assertEqual(self._search("alpha"), self.ROWS)
+        finally:
+            os.environ.pop("ARGO_SEEK_CONTENT_RERANK", None)
+            if old is not None:
+                os.environ["ARGO_SEEK_CONTENT_RERANK"] = old
+
+    def test_regex_query_not_reranked(self):
+        # fixed=False（正则/PCRE2）：词元切分只会产生碎片，闸门必须放行原序
+        self.assertEqual(self._search(r"\d{4}", fixed=False), self.ROWS)
+
+    def test_count_and_context_not_reranked(self):
+        self.assertEqual(self._search("alpha", count=True), self.ROWS)
+        self.assertEqual(self._search("alpha", ctx=3), self.ROWS)
+
+    def test_no_token_query_not_reranked(self):
+        self.assertEqual(self._search("!!!"), self.ROWS)
+
+
+class TestRerankQuality(unittest.TestCase):
+    """B. 重排质量：相关度次序的三条核心判据。"""
+
+    def test_filename_match_beats_content_only(self):
+        rows = [
+            ("docs/notes.md", 12, "支持噪声档降权的说明文字。"),
+            ("src/noise_tier.py", 3, "placeholder"),
+            ("src/other.py", 8, "噪声相关但文件无关。"),
+        ]
+        out = r.rank_rows(rows, "noise_tier")
+        self.assertEqual(out[0][0], "src/noise_tier.py")
+
+    def test_multi_token_coverage_beats_partial(self):
+        rows = [
+            ("a/one.md", 1, "只提到缓存一个词。"),
+            ("b/both.md", 2, "语义缓存与 minhash 软命中都在这行。"),
+        ]
+        out = r.rank_rows(rows, "语义缓存 minhash")
+        self.assertEqual(out[0][0], "b/both.md")
+
+    def test_verbatim_phrase_beats_bigram_scatter(self):
+        # 二元组分不清「噪声档的实现行」与「只有噪声二字的无关行」：
+        # 逐字短语加成必须把前者顶上去
+        rows = [
+            ("a/x.md", 1, "设备噪声很大。"),
+            ("b/y.py", 2, "噪声档的阈值定义在此。"),
+        ]
+        out = r.rank_rows(rows, "噪声档")
+        self.assertEqual(out[0][0], "b/y.py")
+
+    def test_ties_break_by_path_line(self):
+        rows = [("b.py", 2, "same"), ("a.py", 9, "same"), ("a.py", 1, "same")]
+        out = r.rank_rows(rows, "same")
+        self.assertEqual([(p, l) for p, l, _ in out],
+                         [("a.py", 1), ("a.py", 9), ("b.py", 2)])
+
+    def test_noise_floor_after_rerank(self):
+        # 重排改变池内次序后，噪声档分层（真源在前）必须依然成立——
+        # 分层发生在 rg_search 的 _apply_noise_floor（重排之后），走全链路验证
+        rows = [
+            "tmp/x.py:1:noise tier keyword",
+            "src/y.py:2:noise tier keyword here",
+        ]
+        with patch.object(s, "run", return_value=_proc("\n".join(rows) + "\n")):
+            out, err = s.rg_search(["noise"], ".", [], [], 0, False, 5,
+                                   fixed=True, raw_query="noise tier keyword")
+        self.assertIsNone(err)
+        self.assertTrue(out, "真源行不应消失")
+        self.assertTrue(out[0][0].startswith("src/"),
+                        f"真源应排最前，实际: {out[0][0]}")
+
+
+class TestRerankDeterminism(unittest.TestCase):
+    """C. 确定性：打平发射序（2026-10-06 契约在重排开启下延续）。"""
+
+    def test_output_independent_of_emission_order(self):
+        rows = [f"src/f{i:03d}.py:{j + 1}:alpha beta hit {i}-{j}"
+                for i in range(40) for j in range(1)]
+        with patch.object(s, "run", return_value=_proc("\n".join(rows) + "\n")):
+            a, err = s.rg_search(["alpha"], ".", [], [], 0, False, 5,
+                                 fixed=True, raw_query="alpha beta")
+            import random
+            shuffled = rows[:]
+            random.Random(7).shuffle(shuffled)
+            with patch.object(s, "run", return_value=_proc("\n".join(shuffled) + "\n")):
+                b, err2 = s.rg_search(["alpha"], ".", [], [], 0, False, 5,
+                                      fixed=True, raw_query="alpha beta")
+        self.assertIsNone(err)
+        self.assertIsNone(err2)
+        self.assertEqual(a, b)
+
+
+class TestFzfV2(unittest.TestCase):
+    """D. fzf FuzzyMatchV2 口径。"""
+
+    def test_no_match_is_zero(self):
+        self.assertEqual(s._fzf_score("zzz.txt", "rep"), 0)
+
+    def test_smart_case(self):
+        self.assertGreater(s._fzf_score("Report_v2.md", "report"), 0)
+        # 模式带大写 → 区分大小写：R 匹配、r 不配
+        self.assertEqual(s._fzf_score("report.md", "R"), 0)
+
+    def test_boundary_beats_midword(self):
+        # bar 在 foo_bar（词边界）> xbarx（词中）
+        self.assertGreater(s._fzf_score("foo_bar.py", "bar"),
+                           s._fzf_score("xbarx.py", "bar"))
+
+    def test_consecutive_beats_gappy(self):
+        self.assertGreater(s._fzf_score("xabc.md", "abc"),
+                           s._fzf_score("axbxc.md", "abc"))
+
+    def test_camel_bonus(self):
+        self.assertGreater(s._fzf_score("parseHTTPResponse.py", "hr"), 0)
+
+    def test_dp_optimal_alignment(self):
+        # xaabc 搜 ab：DP 应发现「跳过词首 a、取边界 b」的对齐优于顺位连打
+        # （顺位贪心：a@1 + b@4 有 gap；最优：a@1 + b@4 不如 a@3?——此处锚定
+        # 已知反超事实：xaabc 的分必须高于等长无边界对照 axbxc 的同模式分）
+        self.assertGreater(s._fzf_score("xaabc", "ab"),
+                           s._fzf_score("axbxc", "ab"))
+
+    def test_exact_beats_partial(self):
+        self.assertGreater(s._fzf_score("seek.py", "seek.py"),
+                           s._fzf_score("seek_helper.py", "seek.py"))
+
+    def test_exact_case_beats_icase(self):
+        self.assertGreaterEqual(s._fzf_score("Seek.py", "seek.py"),
+                                s._fzf_score("seek.py", "seek.py")
+                                )  # 全等大写版含 case bonus，不小于纯 icase
+
+
+class TestFrecencyWiring(unittest.TestCase):
+    """frecency 默认关闭：不启用时不产生任何行为差异。"""
+
+    def test_disabled_by_default(self):
+        import os
+        old = os.environ.pop("ARGO_SEEK_FRECENCY", None)
+        try:
+            import seek_frecency
+            self.assertFalse(seek_frecency.enabled())
+            self.assertEqual(seek_frecency.boost("/any/path"), 0.0)
+        finally:
+            if old is not None:
+                os.environ["ARGO_SEEK_FRECENCY"] = old
+
+    def test_boost_and_record_roundtrip(self):
+        import os
+        import tempfile
+        old_flag = os.environ.pop("ARGO_SEEK_FRECENCY", None)
+        old_db = os.environ.pop("ARGO_SEEK_FRECENCY_DB", None)
+        with tempfile.TemporaryDirectory() as td:
+            os.environ["ARGO_SEEK_FRECENCY"] = "1"
+            os.environ["ARGO_SEEK_FRECENCY_DB"] = str(Path(td) / "f.json")
+            try:
+                import seek_frecency
+                seek_frecency.record(["/a/b.py", "/c/d.py"])
+                self.assertGreater(seek_frecency.boost("/a/b.py"), 0.0)
+                self.assertEqual(seek_frecency.boost("/z/missing.py"), 0.0)
+            finally:
+                os.environ.pop("ARGO_SEEK_FRECENCY", None)
+                os.environ.pop("ARGO_SEEK_FRECENCY_DB", None)
+                if old_flag is not None:
+                    os.environ["ARGO_SEEK_FRECENCY"] = old_flag
+                if old_db is not None:
+                    os.environ["ARGO_SEEK_FRECENCY_DB"] = old_db
+
+
+if __name__ == "__main__":
+    unittest.main()

package/sub-skills/local-seek/tests/test_determinism_20261006.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""tests/test_determinism_20261006.py — 宽查询输出确定性回归（方案一，2026-10-06）。
+
+守 v1.4.1 审计遗留的定性修复：
+  1. rg 并行遍历发射序不定 →「先到先得」截断拿到任意的 cap 条，同查询
+     两次跑结果集与排序都不同。修复后有界堆按 (路径,行号,内容) 选池，
+     **同一命中集无论以什么顺序发射，输出逐条一致**。
+  2. count 模式并列计数按路径升序决出稳定次序。
+  3. grep 兜底路径同款语义。
+  4. 锁定 ja/ko 2-gram 既有行为（CJK_RE 覆盖假名/谚文——2026-10-06 实测
+     已支持，修正审计记忆里「无分词只能整词匹配」的过时记录）。
+
+打桩纪律：一律 unittest.mock.patch.object（自动恢复）。首版直接给
+s.run 赋值且不恢复，把同进程后续测试的真实 rg 全部替换成假输出——
+套件 9 红的根因（2026-10-06 实锤，教训记录在此防再犯）。
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT / "scripts"))
+
+import seek as s  # noqa: E402
+
+
+def _proc(stdout: str, rc: int = 0) -> subprocess.CompletedProcess:
+    return subprocess.CompletedProcess(args=[], returncode=rc,
+                                       stdout=stdout, stderr="")
+
+
+def _matches(n_files: int, lines_per: int = 1) -> list[str]:
+    """n_files 个文件的 rg 命中行（路径 f{i:03d}.py 保证字典序可控）。"""
+    out = []
+    for i in range(n_files):
+        for j in range(lines_per):
+            out.append(f"src/f{i:03d}.py:{j + 1}:hit {i}-{j}")
+    return out
+
+
+class RgBodyDeterminism(unittest.TestCase):
+    """rg 主体路径：池子选择与发射序无关。"""
+
+    def test_output_independent_of_emission_order(self):
+        rows = _matches(40)
+        # max_results=5 → cap = max(5, min(20, 400)) = 20：命中 40 > cap，
+        # 池子选择真正发生截断
+        for drop_noise in (True, False):
+            with self.subTest(drop_noise=drop_noise):
+                with patch.object(s, "run",
+                                  return_value=_proc("\n".join(rows) + "\n")):
+                    a, err = s.rg_search(["q"], ".", [], [], 0, False, 5,
+                                         fixed=True, drop_noise=drop_noise)
+                with patch.object(s, "run",
+                                  return_value=_proc(
+                                      "\n".join(reversed(rows)) + "\n")):
+                    b, err2 = s.rg_search(["q"], ".", [], [], 0, False, 5,
+                                          fixed=True, drop_noise=drop_noise)
+                self.assertIsNone(err)
+                self.assertIsNone(err2)
+                self.assertEqual(a, b, "同一命中集、不同发射序 → 输出必须一致")
+
+    def test_pool_is_path_smallest_and_sorted(self):
+        rows = _matches(40)
+        with patch.object(s, "run",
+                          return_value=_proc("\n".join(rows) + "\n")):
+            out, err = s.rg_search(["q"], ".", [], [], 0, False, 5,
+                                   fixed=True, drop_noise=False)
+        self.assertIsNone(err)
+        self.assertEqual([r[0] for r in out],
+                         [f"src/f{i:03d}.py" for i in range(5)])
+        self.assertEqual(len(out), 5)
+
+    def test_noise_floor_layering_deterministic(self):
+        """clean 在前 noisy 在后的分层语义在确定池子上仍然成立。"""
+        rows = (["src/clean_{:03d}.py:1:hit".format(i) for i in range(30)]
+                + ["src/repos/lib_{:03d}.py:1:hit".format(i) for i in range(30)])
+        outs = []
+        for order in (rows, list(reversed(rows))):
+            with patch.object(s, "run",
+                              return_value=_proc("\n".join(order) + "\n")):
+                out, err = s.rg_search(["q"], ".", [], [], 0, False, 5,
+                                       fixed=True, drop_noise=True)
+            self.assertIsNone(err)
+            outs.append(out)
+        self.assertEqual(outs[0], outs[1])
+        self.assertTrue(all("/repos/" not in r[0] for r in outs[0]),
+                        "clean 够数时噪声档不得混入")
+
+
+class CountTieDeterminism(unittest.TestCase):
+    def test_equal_counts_sorted_by_path(self):
+        rows = ["src/b.py:5", "src/a.py:5", "src/c.py:2"]
+        with patch.object(s, "run",
+                          return_value=_proc("\n".join(rows) + "\n")):
+            out, err = s.rg_search(["q"], ".", [], [], 0, True, 10,
+                                   fixed=True, drop_noise=False)
+        self.assertIsNone(err)
+        self.assertEqual([r[0] for r in out],
+                         ["src/a.py", "src/b.py", "src/c.py"])
+
+
+class GrepFallbackDeterminism(unittest.TestCase):
+    def test_body_and_count_deterministic(self):
+        rows = _matches(40)
+        for order in (rows, list(reversed(rows))):
+            with patch.object(s, "run",
+                              return_value=_proc("\n".join(order) + "\n")):
+                body, err = s.grep_search("grep", ["q"], ".", [], [], 0,
+                                          False, 5, fixed=True)
+            self.assertIsNone(err)
+            self.assertEqual([r[0] for r in body],
+                             [f"src/f{i:03d}.py" for i in range(5)])
+        cnt_rows = ["src/b.py:5", "src/a.py:5"]
+        with patch.object(s, "run",
+                          return_value=_proc("\n".join(cnt_rows) + "\n")):
+            cnt, err = s.grep_search("grep", ["q"], ".", [], [], 0,
+                                     True, 10, fixed=True)
+        self.assertIsNone(err)
+        self.assertEqual([r[0] for r in cnt], ["src/a.py", "src/b.py"])
+
+
+class JaKoBigramLocked(unittest.TestCase):
+    """锁定既有行为（实测于 2026-10-06）：CJK_RE 已覆盖假名/谚文。"""
+
+    def test_japanese_compound_gets_bigrams(self):
+        pats, literal = s.build_patterns("プロンプトエンジニアリング入門")
+        self.assertIn("プロンプトエンジニアリング入門", pats)  # 整词
+        self.assertIn("プロ", pats)                            # 首个 2-gram
+        self.assertTrue(literal)
+
+    def test_korean_spaced_words_and_compound(self):
+        pats, _ = s.build_patterns("프로프트 검색 설정")
+        self.assertIn("프로프트", pats)   # 复合词整词
+        self.assertIn("프로", pats)       # 复合词 2-gram
+        self.assertIn("검색", pats)       # 空格分隔词保持整词
+
+
+if __name__ == "__main__":
+    unittest.main()

package/sub-skills/local-seek/tests/test_noise_tier.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""噪声档降权的回归测试（2026-09-27 新增，方案 C3）。
+
+实测背景（Documents/GPT 搜 "import"，rg 61899 处命中）：
+    vendor/生成物/归档  7% + 测试/fixture/benchmark  27% + tmp/  7% = 41%
+搜代码时，四成命中是「不想看到的东西」。原来的 DEFAULT_EXCLUDES 挡掉了
+node_modules/dist 之类，但漏了三类最大的：repos/（克隆仓）、tests|fixtures|
+benchmark、tmp/。
+
+**为什么是降权不是排除**：排除 = 这些内容永远搜不到。搜「某个克隆仓里怎么
+写的」「我的测试怎么写的」是真实且常见的用法，排除会让工具在这些查询上
+直接回答「未找到匹配」——那比返回噪声更糟。降权 + 无命中自动回落，两者兼得。
+
+本文件锁定的性质：
+  1. 默认搜不到噪声档内容（降权生效）；
+  2. 噪声档独有内容**仍可达**（回落生效，不制造「明明有却搜不到」）；
+  3. --include-noise 显式关闭降权；
+  4. 回落不影响正常命中（有真源时不去噪声档白跑一趟）。
+"""
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+SEEK = Path(__file__).resolve().parent.parent / "scripts" / "seek.py"
+
+
+def _have(*tools) -> bool:
+    import shutil
+    return all(shutil.which(t) for t in tools)
+
+
+def _run(args, cwd):
+    return subprocess.run([sys.executable, str(SEEK)] + args, cwd=cwd,
+                          capture_output=True, text=True, timeout=120)
+
+
+def _make_tree(root: Path):
+    """构造一棵含「真实源」与「噪声档」两类内容的最小目录树。
+
+    标记词刻意选 `zzmarker_*`：pytest 的 tmp_path 目录名会带测试函数名
+    （如 `test_noise_tier_is_deprioritiz0`），若标记词是 `pytest` 之类，
+    路径本身就会命中，测试变成在验证「路径里有这个词」而非「噪声档降权」。
+    这是第一版用例写错的地方。
+    """
+    (root / "src").mkdir(parents=True)
+    (root / "src" / "app.py").write_text("import os\nimport sys\n", encoding="utf-8")
+    (root / "repos" / "thirdparty").mkdir(parents=True)
+    (root / "repos" / "thirdparty" / "lib.py").write_text(
+        "import zzzarker_clonelib\n", encoding="utf-8")
+    (root / "tests").mkdir()
+    (root / "tests" / "test_x.py").write_text(
+        "import zzzarker_fixture\n", encoding="utf-8")
+
+
+def test_noise_tier_is_deprioritized_and_reachable(tmp_path):
+    if not _have("rg"):
+        import pytest
+        pytest.skip("rg 未安装")
+    _make_tree(tmp_path)
+    proj = str(tmp_path)
+
+    # 噪声档独有内容：搜得到（相对根判定，本例的 tests/ 在根之下），
+    # 且**不触发**回落重搜——它本来就没被排除，只是被排到真源之后。
+    r = _run(["zzzarker_fixture", "--path", proj], tmp_path)
+    assert "test_x.py" in r.stdout, r.stdout
+    assert "噪声档" not in r.stdout, "没被排除就不该多跑一趟回落"
+
+    # 正常源：不受降权影响
+    r2 = _run(["import", "--path", proj], tmp_path)
+    assert "app.py" in r2.stdout, r2.stdout
+
+
+def test_deprioritized_means_source_wins(tmp_path):
+    """同一查询同时命中真源与噪声档时，真源必须排在前面。"""
+    if not _have("rg"):
+        import pytest
+        pytest.skip("rg 未安装")
+    (tmp_path / "src").mkdir()
+    (tmp_path / "src" / "real.py").write_text("import shared_token\n", encoding="utf-8")
+    (tmp_path / "repos").mkdir()
+    (tmp_path / "repos" / "copy.py").write_text("import shared_token\n", encoding="utf-8")
+    proj = str(tmp_path)
+
+    r = _run(["shared_token", "--path", proj, "--max", "1"], tmp_path)
+    assert "real.py" in r.stdout, r.stdout
+    assert "copy.py" not in r.stdout, r.stdout
+
+
+def test_include_noise_flag_is_explicit(tmp_path):
+    if not _have("rg"):
+        import pytest
+        pytest.skip("rg 未安装")
+    _make_tree(tmp_path)
+    proj = str(tmp_path)
+    r = _run(["zzzarker_fixture", "--path", proj, "--include-noise"], tmp_path)
+    assert "test_x.py" in r.stdout, r.stdout
+    # 显式开启时不应再回落（那会多跑一趟）
+    assert "噪声档" not in r.stdout, r.stdout