sophhub 0.4.66 → 0.4.68

package/agents/ai-cs-admin/.config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.7",
+  "version": "1.1.0",
   "agent_id": "ai-cs-admin",
   "description": "智能客服管理员，负责维护智能客服的知识库和管理智能客服",
   "bot_api_enabled": false,

package/agents/ai-cs-admin/AGENTS.md

@@ -246,7 +246,17 @@ with zipfile.ZipFile(docx_path, 'r') as z:
 ### 4.3 FAQ 维护
 
 - 根据会话审计沉淀的高频问题（`memory/faq-suggestions.md`，来源见「六、会话审计」）或管理员直接要求，更新 `knowledge/FAQ.md`
-- FAQ 格式：`Q: 问题 → A: 简明回答 + 出处`
+- FAQ 格式（必须遵守，向量索引按此识别 pair）：
+
+  ```markdown
+  ## Q: 问题文本
+  A: 简明回答
+  出处: 文档.md > 章节
+  ```
+
+  - 每条 FAQ 必须以 `## Q: ` 开头作为分隔符（标题级别固定 `##`，前缀固定 `Q: `），否则索引无法识别为 FAQ pair，会退化为普通文档滑窗切块、丢失 FAQ 加权。
+  - `A:` 段是答案正文，`出处:` 段可选（指向详细文档，便于溯源）。
+  - 导入或新建 FAQ 时统一规范化到此格式；旧的内联 `Q: 问题 → A: ...` 单行格式需改写。
 - 定期检查现有 FAQ 条目是否仍然准确
 
 ---
@@ -311,7 +321,7 @@ with zipfile.ZipFile(docx_path, 'r') as z:
 1. 拉取指定时间范围的会话记录。
 2. 逐条判定是否命中高危类别（见 6.3）；命中则汇总到 `memory/security-log.md`，记录时间、类别、内容摘要、处置建议。
 3. 提取用户反馈类会话（"这个不对"、"流程变了"等）到 `memory/audit-YYYY-MM-DD.md`，标注涉及文档与状态，必要时更新对应知识文档。
-4. 识别高频问题，沉淀或更新 `knowledge/FAQ.md`（经管理员确认）与 `memory/faq-suggestions.md`。
+4. 识别高频问题，沉淀或更新 `knowledge/FAQ.md`（经管理员确认，按 4.3 的 `## Q:` 格式写入）与 `memory/faq-suggestions.md`。
 5. 发现集中攻击或持续探测时，主动提醒管理员关注，必要时建议调整 QA 配置（如收紧 `networkAllowHosts`、补充 `commandContentDeny`）。
 
 ### 6.3 高危行为类别

package/agents/ai-cs-qa/.config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.14",
+  "version": "1.1.0",
   "agent_id": "ai-cs-qa",
   "description": "智能客服，通过 bot API 为客户提供服务",
   "bot_api_enabled": true,

package/agents/ai-cs-qa/AGENTS.md

@@ -29,13 +29,14 @@
 **永远先查知识库，再回答。**
 
 1. 用户提出问题
-2. 调用 `knowledge-search` skill 做模糊检索：以用户问题为 query，在本地向量索引中召回 + 重排，返回匹配片段的 `file` / `heading_path` / `loc`（起止行）/ `score` / `snippet`
-3. 对 Top 结果用 `read` 工具读取对应 `file` 在 `loc` 前后若干行，获取完整上下文
-4. 若检索无结果或索引未建立，回退到查阅 `knowledge/INDEX.md` 定位相关文档，再 `read` 对应文档
-5. **输出回答** — 在对话中直接回复用户。
+2. **枚举型问题优先读 `knowledge/INDEX.md`**：当用户问"都有哪些 X / 列举 / 全部 / 有哪几种"等要求穷举范围的问题时，先直接 `read` `knowledge/INDEX.md`（它是知识地图，枚举的权威来源），再用 `knowledge-search` 补具体细节。向量检索的本质是模糊定位相关片段，不保证穷举完整，不要靠扩大 `--top` 去碰运气。
+3. 调用 `knowledge-search` skill 做模糊检索：以用户问题为 query，在本地向量索引中召回 + 重排，返回匹配片段的 `file` / `heading_path` / `loc`（起止行）/ `score` / `snippet`
+4. 对 Top 结果用 `read` 工具读取对应 `file` 在 `loc` 前后若干行，获取完整上下文
+5. 若检索无结果或索引未建立，回退到查阅 `knowledge/INDEX.md` 定位相关文档，再 `read` 对应文档
+6. **输出回答** — 在对话中直接回复用户。
    - 若知识库已有相关内容，直接回答用户。
    - 若知识库无相关内容，回复："暂未找到相关内容，我们已经记录您的相关问题。"
-6. 最后追问一个问题。
+7. 最后追问一个问题。
 
 
 **禁止凭空编造流程或数据。**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sophhub",
-  "version": "0.4.66",
+  "version": "0.4.68",
   "description": "SophHub CLI - Manage and download AI Agent skills and agents",
   "type": "module",
   "bin": {

package/skills/flight-booking/src/SKILL.md

@@ -94,8 +94,8 @@ python3 {baseDir}/scripts/flight_booking.py create-order --flight-no CA1723 --ca
 | `originalSalePrice` | 查询时的票价（search 缓存） |
 | `updatedSalePrice` | 实时票价（验价后） |
 | `salePriceDiff` | 票价差额（正数为涨价，负数为降价） |
-| `originalTotal` | 原订单总额（含税费服务费） |
-| `updatedTotal` | 新订单总额（含税费服务费） |
+| `originalTotal` | 原订单总额（含税费） |
+| `updatedTotal` | 新订单总额（含税费） |
 | `totalDiff` | 总额差额 |
 | `message` | API 返回的价格变动说明原文 |
 

package/skills/flight-booking/src/scripts/flight_booking.py

@@ -818,9 +818,7 @@ def cmd_create_order(args: argparse.Namespace) -> int:
         shopping_code = cabin.get("shoppingCode", "")
         price_info = None
 
-    # 服务费来源：航班顶层 serviceFee 或舱位层级 serviceFee（两者值相同，优先取 flight）
-    service_fee = float(flight.get("serviceFee", 0) or cabin.get("serviceFee", 0) or 0)
-    estimated_total = sale_price + dep_tax + fuel_tax + service_fee
+    estimated_total = sale_price + dep_tax + fuel_tax
 
     # 价格变动检测：当 check_price 返回 code=10301 或 isUpdatePrice=true 时，记录新旧价格对比
     price_changed = (
@@ -832,8 +830,7 @@ def cmd_create_order(args: argparse.Namespace) -> int:
         orig_sale = float(cabin.get("salePrice", 0))
         orig_total = orig_sale \
             + float(flight.get("departureTax", 0)) \
-            + float(flight.get("fuelTax", 0)) \
-            + float(flight.get("serviceFee", 0) or cabin.get("serviceFee", 0) or 0)
+            + float(flight.get("fuelTax", 0))
         price_diff = {
             "originalSalePrice": orig_sale,
             "updatedSalePrice": sale_price,
@@ -843,7 +840,6 @@ def cmd_create_order(args: argparse.Namespace) -> int:
             "totalDiff": round(estimated_total - orig_total, 2),
             "departureTax": dep_tax,
             "fuelTax": fuel_tax,
-            "serviceFee": service_fee,
             "message": verify_res.get("msg", ""),
         }
 
@@ -1129,8 +1125,7 @@ def cmd_change_order(args: argparse.Namespace) -> int:
         shopping_code = cabin.get("shoppingCode", "")
         price_info = None
 
-    service_fee = float(flight.get("serviceFee", 0) or cabin.get("serviceFee", 0) or 0)
-    estimated_total = sale_price + dep_tax + fuel_tax + service_fee
+    estimated_total = sale_price + dep_tax + fuel_tax
 
     price_changed = (
         verify_res.get("code") == "10301"
@@ -1141,8 +1136,7 @@ def cmd_change_order(args: argparse.Namespace) -> int:
         orig_sale = float(cabin.get("salePrice", 0))
         orig_total = orig_sale \
             + float(flight.get("departureTax", 0)) \
-            + float(flight.get("fuelTax", 0)) \
-            + float(flight.get("serviceFee", 0) or cabin.get("serviceFee", 0) or 0)
+            + float(flight.get("fuelTax", 0))
         price_diff = {
             "originalSalePrice": orig_sale,
             "updatedSalePrice": sale_price,
@@ -1152,7 +1146,6 @@ def cmd_change_order(args: argparse.Namespace) -> int:
             "totalDiff": round(estimated_total - orig_total, 2),
             "departureTax": dep_tax,
             "fuelTax": fuel_tax,
-            "serviceFee": service_fee,
             "message": verify_res.get("msg", ""),
         }
 

package/skills/knowledge-search/skill.json

@@ -1,10 +1,15 @@
 {
   "name": "knowledge-search",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "types": ["store"],
   "displayName": "知识库模糊检索",
   "description": "基于向量召回+重排的知识库模糊检索，返回匹配文件位置与片段。当客服 Agent 需要按一句话模糊定位知识库中相关文档位置时使用。",
   "changelog": [
+    {
+      "version": "1.2.0",
+      "date": "2026-07-29",
+      "changes": ["混合召回（dense+BM25 RRF）+ rerank 精排 + 类型加权 + 文件级分散 + 阈值闸口；score 改为 sigmoid 归一化值（0~1）"]
+    },
     {
       "version": "1.1.0",
       "date": "2026-07-29",

package/skills/knowledge-search/src/SKILL.md

@@ -5,7 +5,7 @@ description: 基于向量召回+重排的知识库模糊检索，返回匹配文
 
 # 知识库模糊检索
 
-对一句话查询做模糊检索：BGE-M3 编码 query → 本地向量余弦召回 Top-N → bge-reranker 精排 Top-K → 返回匹配片段的文件位置（文件路径 + 标题路径 + 行范围 + 分数 + 片段）。供客服问答 Agent 在线使用；只读索引，不写任何文件。
+对一句话查询做模糊检索：BGE-M3 编码 query → dense 召回 + BM25 召回 → RRF 融合 → bge-reranker 精排 → sigmoid 归一化 + 类型加权 → 文件级分散 → 阈值闸口 → 返回匹配片段的文件位置（文件路径 + 标题路径 + 行范围 + 分数 + 片段）。供客服问答 Agent 在线使用；只读索引，不写任何文件。
 
 ## 前置条件
 
@@ -26,7 +26,11 @@ uv run {baseDir}/scripts/ksearch.py \
 - `--index-dir`：索引目录，只读（必填）
 - `--recall`：向量召回数（默认 30）
 - `--top`：最终返回条数（默认 10）
-- `--threshold`：rerank 分数阈值，低于则丢弃（默认 0.0，即不过滤）
+- `--threshold`：相关度闸口，作用于归一化 norm（默认 0.6；0=不过滤）
+- `--max-per-file`：同一文件最多进榜条数（默认 2）
+- `--faq-boost`：FAQ 加权幅度（默认 0.15）
+- `--no-bm25`：关闭 BM25，纯 dense
+- `--no-faq-boost`：关闭类型加权
 - `--no-snippet`：不输出片段文本
 - `--timeout`：单次 API 超时秒数（默认 60）
 
@@ -55,5 +59,5 @@ RESULTS=[
 - 本 skill 只读索引，不构建；建库/更新索引请用 `knowledge-search-admin`。
 - 拿到 `file` + `loc` 后，由调用方用 `read` 工具到文件中读取 `loc` 前后内容做最终回答。
 - 平台 ApiKey 运行时由 `sophnet_tools.get_api_key()` 获取，不硬编码；接口走 Sophnet 平台 `https://www.sophnet.com/api/open-apis`。
-- rerank 接口失败时自动回退到向量余弦分数，不中断检索。
+- rerank 失败回退到 dense+BM25 融合分排序，不中断检索。
 - embedding 单次输入 ≤ 8 条、rerank 单次 ≤ 256 条，脚本已自动分批。

package/skills/knowledge-search/src/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "knowledge-search"
-version = "1.1.0"
+version = "1.2.0"
 description = "Fuzzy knowledge-base search via BGE-M3 embedding recall + bge-reranker"
 requires-python = ">=3.8"
 dependencies = [

package/skills/knowledge-search/src/scripts/bm25.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""BM25 稀疏检索：混合 char-bigram 分词 + 内存倒排打分（search 侧）。
+
+分词策略与 knowledge-search-admin skill 一致。
+"""
+
+import math
+import re
+from typing import List
+
+_ASCII_RUN = re.compile(r"[A-Za-z0-9_-]+")
+_CJK_RUN = re.compile(r"[㐀-鿿]+")
+
+
+def tokenize(text: str) -> List[str]:
+    if not text:
+        return []
+    tokens: List[str] = []
+    for m in _ASCII_RUN.finditer(text):
+        tokens.append(m.group(0).lower())
+    for m in _CJK_RUN.finditer(text):
+        seg = m.group(0)
+        for i in range(len(seg) - 1):
+            tokens.append(seg[i:i + 2])
+    return tokens
+
+
+def bm25_scores(query_tokens: List[str], doc_tokens: List[List[str]],
+               k1: float = 1.5, b: float = 0.75) -> List[float]:
+    """对每篇 doc 按 BM25 打分，返回与 doc_tokens 同序的分值列表。"""
+    N = len(doc_tokens)
+    if N == 0:
+        return []
+    df: dict = {}
+    doc_len: List[int] = []
+    for toks in doc_tokens:
+        seen = set(toks)
+        for t in seen:
+            df[t] = df.get(t, 0) + 1
+        doc_len.append(len(toks))
+    avgdl = (sum(doc_len) / N) or 1.0
+    if not query_tokens:
+        return [0.0] * N
+    scores = [0.0] * N
+    for i, toks in enumerate(doc_tokens):
+        tf: dict = {}
+        for t in toks:
+            tf[t] = tf.get(t, 0) + 1
+        dl = doc_len[i] or 1
+        s = 0.0
+        for t in query_tokens:
+            d = df.get(t, 0)
+            if d == 0:
+                continue
+            idf = math.log(1 + (N - d + 0.5) / (d + 0.5))
+            f = tf.get(t, 0)
+            denom = f + k1 * (1 - b + b * dl / avgdl)
+            s += idf * (f * (k1 + 1)) / denom
+        scores[i] = s
+    return scores

package/skills/knowledge-search/src/scripts/index_loader.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
-"""只读加载向量索引（chunks.json + vectors.npy）。
+"""只读加载索引（chunks.json + vectors.npy + bm25.json）。
 
-QA skill 仅需检索，不构建索引。本模块是 index_store 的只读子集，避免引入切块与构建依赖。
+QA skill 仅检索不构建。bm25.json 缺失（老索引）时返回空 token 列表，向后兼容。
 """
 
 import json
@@ -14,15 +14,22 @@ from bge_client import EMBED_DIM
 
 CHUNKS_FILE = "chunks.json"
 VECTORS_FILE = "vectors.npy"
+BM25_FILE = "bm25.json"
 
 
-def load_index(index_dir: Path) -> Tuple[List[dict], np.ndarray]:
-    """返回 (chunks, vectors)。索引不存在则返回空。"""
+def load_index(index_dir: Path) -> Tuple[List[dict], np.ndarray, List[List[str]]]:
+    """返回 (chunks, vectors, token_lists)。索引不存在则返回空。"""
     chunks_path = index_dir / CHUNKS_FILE
     vectors_path = index_dir / VECTORS_FILE
     if not chunks_path.exists() or not vectors_path.exists():
-        return [], np.zeros((0, EMBED_DIM), dtype=np.float32)
+        return [], np.zeros((0, EMBED_DIM), dtype=np.float32), []
     with chunks_path.open("r", encoding="utf-8") as f:
         chunks = json.load(f)
     vectors = np.load(str(vectors_path))
-    return chunks, vectors
+    bm25_path = index_dir / BM25_FILE
+    if bm25_path.exists():
+        with bm25_path.open("r", encoding="utf-8") as f:
+            token_lists = json.load(f)
+    else:
+        token_lists = [[] for _ in chunks]
+    return chunks, vectors, token_lists

package/skills/knowledge-search/src/scripts/ksearch.py

@@ -1,8 +1,9 @@
 #!/usr/bin/env python3
 """知识库模糊检索（QA Agent 用）。
 
-链路：load 索引 → embed query → 本地余弦召回 Top-N → reranker 精排 Top-K → 输出匹配片段位置。
-只读索引，不写任何文件；仅发 embed + rerank 两个 API 请求。
+链路：load 索引 → dense 召回 + BM25 召回 → RRF 融合 → rerank 精排
+      → sigmoid 归一化 → 类型加权 → 文件级分散 → 阈值闸口 → 输出。
+只读索引，不写任何文件。
 
 输出（stdout）：
   STATUS=succeeded\nRESULTS=[...]
@@ -17,10 +18,17 @@ from pathlib import Path
 import numpy as np
 
 from bge_client import embed, rerank
+from bm25 import bm25_scores, tokenize
 from index_loader import load_index
+from ranker import (
+    FAQ_BOOST_DEFAULT, OVERVIEW_BOOST_DEFAULT, THRESHOLD_DEFAULT,
+    apply_type_boost, diversify_by_file, rrf_fuse, sigmoid_norm,
+)
 
 DEFAULT_RECALL = 30
+DEFAULT_RECALL_TOP = 50
 DEFAULT_TOP = 10
+DEFAULT_MAX_PER_FILE = 2
 
 
 def _emit(status: str, **fields) -> None:
@@ -35,19 +43,26 @@ def _emit(status: str, **fields) -> None:
 
 
 def main() -> int:
-    parser = argparse.ArgumentParser(description="知识库模糊检索：向量召回 + rerank 精排")
+    parser = argparse.ArgumentParser(description="知识库模糊检索：混合召回 + rerank 精排")
     parser.add_argument("--query", required=True, help="查询文本")
     parser.add_argument("--index-dir", required=True, help="索引目录（只读）")
-    parser.add_argument("--recall", type=int, default=DEFAULT_RECALL, help="向量召回数（默认 30）")
-    parser.add_argument("--top", type=int, default=DEFAULT_TOP, help="最终返回条数（默认 10）")
-    parser.add_argument("--threshold", type=float, default=0.0, help="rerank 分数阈值，低于则丢弃")
+    parser.add_argument("--recall", type=int, default=DEFAULT_RECALL, help="每路召回数（默认 30）")
+    parser.add_argument("--top", type=int, default=DEFAULT_TOP, help="最终返回数（默认 10）")
+    parser.add_argument("--threshold", type=float, default=THRESHOLD_DEFAULT,
+                        help="相关度闸口，作用于归一化 norm（默认 0.5；0=不过滤）")
+    parser.add_argument("--max-per-file", type=int, default=DEFAULT_MAX_PER_FILE,
+                        help="同一文件最多进榜条数（默认 2）")
+    parser.add_argument("--faq-boost", type=float, default=FAQ_BOOST_DEFAULT,
+                        help="FAQ 加权幅度（默认 0.15）")
+    parser.add_argument("--no-bm25", action="store_true", help="关闭 BM25，纯 dense")
+    parser.add_argument("--no-faq-boost", action="store_true", help="关闭类型加权")
     parser.add_argument("--no-snippet", action="store_true", help="不输出片段文本")
     parser.add_argument("--timeout", type=int, default=60, help="单次 API 超时秒数")
     args = parser.parse_args()
 
     index_dir = Path(args.index_dir).resolve()
     try:
-        chunks, vectors = load_index(index_dir)
+        chunks, vectors, token_lists = load_index(index_dir)
     except Exception as e:  # noqa: BLE001
         _emit("failed", ERROR_MESSAGE="加载索引失败：%s" % e)
         return 1
@@ -61,28 +76,58 @@ def main() -> int:
         _emit("failed", ERROR_MESSAGE="编码 query 失败：%s" % e)
         return 1
 
+    n = len(chunks)
+    recall_n = min(args.recall, n)
+
     sims = vectors @ q_vec
-    recall_n = min(args.recall, len(chunks))
-    top_idx = np.argsort(-sims)[:recall_n].tolist()
+    dense_rank = np.argsort(-sims)[:recall_n].tolist()
+
+    if args.no_bm25 or not token_lists or not any(token_lists):
+        bm25_rank = []
+    else:
+        q_tokens = tokenize(args.query)
+        if q_tokens:
+            scores = bm25_scores(q_tokens, token_lists)
+            bm25_rank = [i for i in np.argsort(-np.asarray(scores))[:recall_n].tolist()]
+        else:
+            bm25_rank = []
 
-    cand_texts = [chunks[i]["text"] for i in top_idx]
+    if bm25_rank:
+        cand_idx = rrf_fuse(dense_rank, bm25_rank, top=DEFAULT_RECALL_TOP)
+    else:
+        cand_idx = dense_rank[:DEFAULT_RECALL_TOP]
+
+    cand_texts = [chunks[i]["text"] for i in cand_idx]
     try:
         ranked = rerank(args.query, cand_texts, timeout=args.timeout)
-    except Exception as e:  # noqa: BLE001
-        ranked = [(j, float(sims[top_idx[j]])) for j in range(len(top_idx))]
+        raw_scores = {local: s for local, s in ranked}
+    except Exception:
+        raw_scores = {j: float(sims[cand_idx[j]]) for j in range(len(cand_idx))}
+
+    items = []
+    for local, idx in enumerate(cand_idx):
+        norm = sigmoid_norm(float(raw_scores.get(local, 0.0)))
+        items.append({
+            "idx": idx,
+            "norm": norm,
+            "type": chunks[idx].get("type", "normal"),
+            "file": chunks[idx]["file"],
+        })
+
+    faq_boost = 0.0 if args.no_faq_boost else args.faq_boost
+    over_boost = 0.0 if args.no_faq_boost else OVERVIEW_BOOST_DEFAULT
+    boosted = apply_type_boost(items, faq_boost=faq_boost, overview_boost=over_boost)
+    final = diversify_by_file(boosted, max_per_file=args.max_per_file,
+                              top=args.top, threshold=args.threshold)
 
-    top_k = min(args.top, len(ranked))
     results = []
-    for local_idx, score in ranked[:top_k]:
-        if args.threshold > 0 and score < args.threshold:
-            continue
-        global_idx = top_idx[local_idx]
-        c = chunks[global_idx]
+    for it in final:
+        c = chunks[it["idx"]]
         item = {
             "file": c["file"],
             "heading_path": c["heading_path"],
             "loc": {"start_line": c["start_line"], "end_line": c["end_line"]},
-            "score": round(float(score), 5),
+            "score": round(float(it["norm"]), 5),
         }
         if not args.no_snippet:
             item["snippet"] = c["text"][:200]

package/skills/knowledge-search/src/scripts/ranker.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""检索排序管线：RRF 融合 + sigmoid 归一化 + 类型加权 + 文件级分散 + 阈值。
+
+与 knowledge-search skill 中的 ranker.py 保持一致。
+
+排序流程：
+  dense 召回 Top-N + bm25 召回 Top-N
+    → rrf_fuse 融合取 Top-F（候选下标，按 final 排序前的池子）
+  → 对候选调 rerank 得原始分 → sigmoid_norm 归一化为 norm (0~1)
+  → apply_type_boost：final = norm + boost(type)，按 final 降序
+  → diversify_by_file：按 final 降序、同 file 上限、norm 阈值过滤、取 Top-K
+  输出 score 字段 = norm（不含 boost），FAQ 优先体现在排序而非 score 值。
+"""
+
+import math
+from typing import List, Sequence
+
+FAQ_BOOST_DEFAULT = 0.15
+OVERVIEW_BOOST_DEFAULT = 0.05
+THRESHOLD_DEFAULT = 0.6
+RRF_K = 60
+
+
+def rrf_fuse(dense_rank: Sequence[int], bm25_rank: Sequence[int],
+             k: int = RRF_K, top: int = 50) -> List[int]:
+    """两路排名 RRF 融合，返回融合后按分降序的下标列表（最多 top 个，去重）。"""
+    scores: dict = {}
+    for rank, idx in enumerate(dense_rank):
+        scores[idx] = scores.get(idx, 0.0) + 1.0 / (k + rank + 1)
+    for rank, idx in enumerate(bm25_rank):
+        scores[idx] = scores.get(idx, 0.0) + 1.0 / (k + rank + 1)
+    ordered = sorted(scores.items(), key=lambda kv: kv[1], reverse=True)
+    return [idx for idx, _ in ordered[:top]]
+
+
+def sigmoid_norm(raw: float) -> float:
+    """rerank 原始分（无界）→ (0,1) 归一化。"""
+    if raw >= 0:
+        z = math.exp(-raw)
+        return 1.0 / (1.0 + z)
+    z = math.exp(raw)
+    return z / (1.0 + z)
+
+
+def apply_type_boost(items: List[dict], faq_boost: float, overview_boost: float) -> List[dict]:
+    """给每个 item 加 final = norm + boost(type)，按 final 降序返回。"""
+    out: List[dict] = []
+    for it in items:
+        norm = it["norm"]
+        t = it.get("type", "normal")
+        boost = faq_boost if t == "faq" else (overview_boost if t == "overview" else 0.0)
+        enriched = dict(it)
+        enriched["final"] = norm + boost
+        out.append(enriched)
+    # round 排序键以抵消浮点误差（如 0.55+0.05 略大于 0.6+0.0），同分时稳定保序
+    out.sort(key=lambda x: round(x["final"], 9), reverse=True)
+    return out
+
+
+def diversify_by_file(items: List[dict], max_per_file: int, top: int,
+                      threshold: float = THRESHOLD_DEFAULT) -> List[dict]:
+    """按 final 降序遍历，同 file 计数上限 max_per_file；norm < threshold 丢弃；取 top。"""
+    per_file: dict = {}
+    out: List[dict] = []
+    for it in items:  # items 已按 final 降序
+        f = it.get("file", "")
+        if per_file.get(f, 0) >= max_per_file:
+            continue
+        if it.get("norm", 1.0) < threshold:
+            continue
+        per_file[f] = per_file.get(f, 0) + 1
+        out.append(it)
+        if len(out) >= top:
+            break
+    return out

package/skills/knowledge-search-admin/skill.json

@@ -1,10 +1,15 @@
 {
   "name": "knowledge-search-admin",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "types": ["store"],
   "displayName": "知识库向量检索管理",
   "description": "构建与检索知识库向量索引（BGE-M3 embedding + bge-reranker）。当管理员要求对 knowledge 目录建库、重建向量索引、增量更新、或做模糊检索自测时使用。",
   "changelog": [
+    {
+      "version": "1.3.0",
+      "date": "2026-07-29",
+      "changes": ["新增 BM25 稀疏召回与 RRF 融合（补 dense 词项盲区）；FAQ 文档按 ## Q: pair 切块并打 type=faq；chunk 类型加权（FAQ +0.15、INDEX 概览 +0.05），rerank 分 sigmoid 归一化、阈值作用于 norm；文件级分散解决广度查询覆盖不全；索引新增 bm25.json"]
+    },
     {
       "version": "1.2.0",
       "date": "2026-07-29",

package/skills/knowledge-search-admin/src/SKILL.md

@@ -5,7 +5,7 @@ description: 构建与检索知识库向量索引（BGE-M3 embedding + bge-reran
 
 # 知识库向量检索管理
 
-对知识库文档目录构建本地向量索引（固定窗口滑窗切块 → BGE-M3 embedding → 落本地），并提供向量召回 + reranker 精排的检索自测能力。供知识库管理主 Agent 使用；问答 Agent 的在线检索请用配套的 `knowledge-search` skill。
+对知识库文档目录构建本地向量索引 + BM25 token 索引（按文档类型分流切块：FAQ 按 ## Q: pair 切、其余固定窗口滑窗 → BGE-M3 embedding + char-bigram 分词 → 落本地），并提供混合召回（dense+BM25 RRF）+ reranker 精排 + 类型加权 + 文件分散的检索自测能力。供知识库管理主 Agent 使用；问答 Agent 的在线检索请用配套的 `knowledge-search` skill。
 
 ## 用法
 
@@ -19,7 +19,7 @@ uv run {baseDir}/scripts/ksearch.py build \
 uv run {baseDir}/scripts/ksearch.py build \
   --doc-dir knowledge/ --index-dir knowledge-index/ --rebuild
 
-# 3. 检索自测：向量召回 Top-30 → rerank Top-10
+# 3. 检索自测：dense+BM25 召回 → RRF 融合 → rerank 精排 → 类型加权 → Top-10
 uv run {baseDir}/scripts/ksearch.py search \
   --query "怎么办理退款" \
   --index-dir knowledge-index/ \
@@ -41,7 +41,11 @@ search：
 - `--index-dir`：索引目录（必填）
 - `--recall`：向量召回数（默认 30）
 - `--top`：最终返回条数（默认 10）
-- `--threshold`：rerank 分数阈值，低于则丢弃（默认 0.0，即不过滤）
+- `--threshold`：相关度闸口，作用于归一化 norm（默认 0.6；0=不过滤）
+- `--max-per-file`：同一文件最多进榜条数（默认 2）
+- `--faq-boost`：FAQ 加权幅度（默认 0.15）
+- `--no-bm25`：关闭 BM25，纯 dense
+- `--no-faq-boost`：关闭类型加权
 - `--no-snippet`：不输出片段文本
 - `--timeout`：单次 API 超时秒数（默认 60）
 
@@ -66,9 +70,10 @@ ERROR_MESSAGE=...
 
 ## 注意事项
 
-- 索引产物为 `chunks.json`（chunk 元信息）+ `vectors.npy`（N×1024 float32，L2 归一化）。两个文件行序对齐，不可单独改动。
+- 索引产物为 `chunks.json`（chunk 元信息，含 type）+ `vectors.npy`（N×1024 float32，L2 归一化）+ `bm25.json`（每行 chunk 的 token 列表）。三个文件行序对齐，不可单独改动。
 - 增量更新按文件 md5 hash 判断变更；未变更文件复用已有向量，仅对变更/新增文件重 embedding。
-- 切块策略：固定窗口滑窗，默认窗口 800 字符、重叠 150 字符（步长 650）；每个 chunk 记录起始位置所属的标题路径与起止行号，便于结果定位。末尾不足 100 字符的碎块并入上一个 chunk。
+- 切块策略：固定窗口滑窗，默认窗口 800 字符、重叠 150 字符（步长 650）；每个 chunk 记录起始位置所属的标题路径与起止行号，便于结果定位。末尾不足 100 字符的碎块并入上一个 chunk。FAQ 文档（文件名 FAQ.md 或路径含 `/faq/`，且含 `## Q:` pair）按 pair 切块、type=faq；INDEX.md → type=overview；其余固定窗口滑窗、type=normal。
+- FAQ 导入格式约定 `## Q: 问题 / A: 答案 / 出处: ...`，管理员导入时统一规范化。
 - 平台 ApiKey 运行时由 `sophnet_tools.get_api_key()` 获取，不硬编码；接口走 Sophnet 平台 `https://www.sophnet.com/api/open-apis`。
 - embedding 单次输入 ≤ 8 条、rerank 单次 ≤ 256 条，脚本已自动分批。
 - 仅处理 `.md` / `.txt`；图片、附件等不纳入向量索引。

package/skills/knowledge-search-admin/src/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "knowledge-search-admin"
-version = "1.2.0"
+version = "1.3.0"
 description = "Build and search a local BGE-M3 vector index over a knowledge directory"
 requires-python = ">=3.8"
 dependencies = [

package/skills/knowledge-search-admin/src/scripts/bm25.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+"""BM25 稀疏检索：混合 char-bigram 分词 + 索引构建。
+
+分词策略（与 knowledge-search skill 保持一致）：
+- ASCII/数字连续段 [A-Za-z0-9_]+ 整段作一个 token（保住 "SF103"/"PLUS" 整体性）。
+- CJK 段取相邻字符 bigram。
+- 标点/空白作分隔符，不产生 token。
+- ASCII 全部小写化。
+
+本模块在 build 侧只负责分词与 token 列表生成；查询打分在 search 侧（knowledge-search skill）。
+"""
+
+import re
+from typing import List
+
+_ASCII_RUN = re.compile(r"[A-Za-z0-9_-]+")
+# CJK Unified + Ext A 常用范围；覆盖中文
+_CJK_RUN = re.compile(r"[㐀-鿿]+")
+
+
+def tokenize(text: str) -> List[str]:
+    """文本 → token 列表。ASCII 段小写化，CJK 段取 bigram。"""
+    if not text:
+        return []
+    tokens: List[str] = []
+    for m in _ASCII_RUN.finditer(text):
+        tokens.append(m.group(0).lower())
+    for m in _CJK_RUN.finditer(text):
+        seg = m.group(0)
+        for i in range(len(seg) - 1):
+            tokens.append(seg[i:i + 2])
+    return tokens
+
+
+def build_token_lists(chunk_texts: List[str]) -> List[List[str]]:
+    """对每个 chunk 文本分词，返回与输入同序的 token 列表。"""
+    return [tokenize(t) for t in chunk_texts]

package/skills/knowledge-search-admin/src/scripts/chunker.py

@@ -1,27 +1,36 @@
 #!/usr/bin/env python3
-"""固定窗口滑窗切块。
+"""文档切块。
 
-以约 800 字符为窗口、150 字符重叠做滑窗切块。每个 chunk 记录其起始位置所属的最深标题路径（heading_path）与起止行号，用于结果定位。重叠保证跨边界内容同时出现在相邻 chunk 中，提升召回稳定性。
+按文档类型分流：
+- FAQ 文档（文件名 FAQ.md 或路径含 /faq/，且含 `## Q:` pair）→ 每条 Q-A pair 一个 chunk，type=faq。
+- INDEX.md → type=overview，走滑窗。
+- 其余 → 固定窗口滑窗，type=normal。
+
+每个 chunk 记录 heading_path、起止行号、text、type。
 """
 
+import re
 from bisect import bisect_right
 from dataclasses import dataclass
 from pathlib import Path
 from typing import List, Tuple
 
-# 窗口与重叠（字符数）。步长 = 窗口 - 重叠 = 650。
 DEFAULT_WINDOW = 800
 DEFAULT_OVERLAP = 150
-MIN_TAIL = 100  # 末尾碎块若不足此长度，并入上一个 chunk
+MIN_TAIL = 100
+
+_FAQ_FILE_RE = re.compile(r"(^|/)faq(/|$)|faq\.md$", re.IGNORECASE)
+_FAQ_PAIR_RE = re.compile(r"^##\s+Q[:：]\s*(.+?)\s*$")
 
 
 @dataclass
 class Chunk:
-    file: str           # 相对根目录的路径
-    heading_path: str   # 形如 "售前流程.md > 退货 > 退款时效"
-    start_line: int     # 1-based
-    end_line: int       # 1-based，含
+    file: str
+    heading_path: str
+    start_line: int
+    end_line: int
     text: str
+    type: str = "normal"
 
     def to_dict(self) -> dict:
         return {
@@ -30,11 +39,20 @@ class Chunk:
             "start_line": self.start_line,
             "end_line": self.end_line,
             "text": self.text,
+            "type": self.type,
         }
 
 
+def _is_faq_path(path: Path, root: Path) -> bool:
+    rel = str(path.relative_to(root))
+    return bool(_FAQ_FILE_RE.search("/" + rel + "/") or _FAQ_FILE_RE.search(path.name))
+
+
+def _is_overview_path(path: Path) -> bool:
+    return path.name.upper() == "INDEX.MD"
+
+
 def _heading_level(line: str) -> int:
-    """返回 ATX 标题级别（1~6），非标题返回 0。"""
     stripped = line.lstrip()
     if not stripped.startswith("#"):
         return 0
@@ -56,12 +74,6 @@ def _heading_title(line: str) -> str:
 
 
 def _build_index(lines: List[str]) -> Tuple[str, List[int], List[Tuple[int, List[str]]]]:
-    """返回 (text, line_starts, heading_checkpoints)。
-
-    line_starts[k] = 第 k 行（0-based）在 text 中的起始字符偏移。
-    heading_checkpoints = [(offset, heading_stack), ...]，按 offset 升序；
-      offset 处及之后的字符用该 stack（标题行本身归入新 stack）。
-    """
     line_starts: List[int] = []
     checkpoints: List[Tuple[int, List[str]]] = [(0, [])]
     heading_stack: List[str] = []
@@ -73,13 +85,12 @@ def _build_index(lines: List[str]) -> Tuple[str, List[int], List[Tuple[int, List
             heading_stack = heading_stack[: level - 1]
             heading_stack.append(_heading_title(ln))
             checkpoints.append((pos, list(heading_stack)))
-        pos += len(ln) + 1  # +1 for "\n"
+        pos += len(ln) + 1
     text = "\n".join(lines)
     return text, line_starts, checkpoints
 
 
 def _line_of(line_starts: List[int], offset: int) -> int:
-    """字符偏移 → 1-based 行号。"""
     if offset < 0:
         offset = 0
     idx = bisect_right(line_starts, offset) - 1
@@ -100,29 +111,47 @@ def _heading_path_for(file_stem: str, checkpoints: List[Tuple[int, List[str]]],
     return file_stem
 
 
-def chunk_file(
-    path: Path,
-    root: Path,
-    window: int = DEFAULT_WINDOW,
-    overlap: int = DEFAULT_OVERLAP,
-) -> List[Chunk]:
-    """读取单个 Markdown/文本文件，按固定窗口滑窗切块。"""
-    rel = str(path.relative_to(root))
-    try:
-        with path.open("r", encoding="utf-8") as f:
-            lines = f.read().splitlines()
-    except UnicodeDecodeError:
+def _chunk_faq(rel: str, file_stem: str, lines: List[str]) -> List[Chunk]:
+    """按 ## Q: 分隔 pair，每 pair 一个 chunk。无 pair 则返回空（调用方回退滑窗）。"""
+    # 找出所有 pair 起始行
+    pair_starts: List[int] = []
+    questions: List[str] = []
+    for i, ln in enumerate(lines):
+        m = _FAQ_PAIR_RE.match(ln)
+        if m:
+            pair_starts.append(i)
+            questions.append(m.group(1).strip())
+    if not pair_starts:
         return []
 
-    file_stem = path.name
-    if not lines:
-        return []
+    chunks: List[Chunk] = []
+    n = len(lines)
+    for idx, start in enumerate(pair_starts):
+        end = pair_starts[idx + 1] if idx + 1 < len(pair_starts) else n
+        block = lines[start:end]
+        # 去掉末尾空行
+        while block and not block[-1].strip():
+            block.pop()
+        if not block:
+            continue
+        text = "\n".join(block)
+        chunks.append(Chunk(
+            file=rel,
+            heading_path="%s > %s" % (file_stem, questions[idx]),
+            start_line=start + 1,  # 1-based
+            end_line=start + len(block),  # 末行（含，已去尾空行后）
+            text=text,
+            type="faq",
+        ))
+    return chunks
+
 
+def _chunk_sliding(rel: str, file_stem: str, lines: List[str],
+                   window: int, overlap: int, ctype: str) -> List[Chunk]:
     text, line_starts, checkpoints = _build_index(lines)
     n = len(text)
     if n == 0:
         return []
-
     if window <= 0:
         window = DEFAULT_WINDOW
     if overlap < 0 or overlap >= window:
@@ -131,7 +160,6 @@ def chunk_file(
     if step <= 0:
         step = 1
 
-    # 计算所有窗口的 [start, end) 偏移
     offsets: List[Tuple[int, int]] = []
     start = 0
     while start < n:
@@ -140,8 +168,6 @@ def chunk_file(
         if end >= n:
             break
         start += step
-
-    # 末尾碎块并入上一个 chunk
     if len(offsets) >= 2 and (offsets[-1][1] - offsets[-1][0]) < MIN_TAIL:
         last = offsets.pop()
         prev = offsets[-1]
@@ -152,5 +178,33 @@ def chunk_file(
         hp = _heading_path_for(file_stem, checkpoints, s)
         sl = _line_of(line_starts, s)
         el = _line_of(line_starts, e - 1) if e > s else sl
-        chunks.append(Chunk(rel, hp, sl, el, text[s:e]))
+        chunks.append(Chunk(rel, hp, sl, el, text[s:e], ctype))
     return chunks
+
+
+def chunk_file(
+    path: Path,
+    root: Path,
+    window: int = DEFAULT_WINDOW,
+    overlap: int = DEFAULT_OVERLAP,
+) -> List[Chunk]:
+    """读取单文件，按类型切块。FAQ 无 pair 结构时回退滑窗并 type=normal。"""
+    rel = str(path.relative_to(root))
+    try:
+        with path.open("r", encoding="utf-8") as f:
+            lines = f.read().splitlines()
+    except UnicodeDecodeError:
+        return []
+    if not lines:
+        return []
+    file_stem = path.name
+
+    if _is_faq_path(path, root):
+        faq_chunks = _chunk_faq(rel, file_stem, lines)
+        if faq_chunks:
+            return faq_chunks
+        # FAQ 文件但无 ## Q: pair → 退化为 normal 滑窗（格式异常，不误标 faq）
+        return _chunk_sliding(rel, file_stem, lines, window, overlap, "normal")
+
+    ctype = "overview" if _is_overview_path(path) else "normal"
+    return _chunk_sliding(rel, file_stem, lines, window, overlap, ctype)

package/skills/knowledge-search-admin/src/scripts/index_store.py

@@ -1,11 +1,12 @@
 #!/usr/bin/env python3
-"""向量索引存储与增量构建。
+"""向量索引 + BM25 token 索引存储与增量构建。
 
-索引产物：
-  <index_dir>/chunks.json  — chunk 列表，每条含 file/heading_path/start_line/end_line/text/file_hash
-  <index_dir>/vectors.npy  — N×1024 float32 矩阵，行序与 chunks.json 一致
+索引产物（行序三者严格对齐，不可单独改动）：
+  <index_dir>/chunks.json  — chunk 列表，含 file/heading_path/start_line/end_line/text/file_hash/type
+  <index_dir>/vectors.npy  — N×1024 float32 矩阵
+  <index_dir>/bm25.json    — 每行 chunk 的 token 列表
 
-增量策略：按文件 md5 hash 判断是否变更；未变更文件复用已有 chunk 与向量，仅对变更/新增文件重切重 embed。
+增量策略：按文件 md5 hash 判断变更；未变更文件复用已有 chunk + 向量 + token 列表。
 """
 
 import hashlib
@@ -16,10 +17,12 @@ from typing import Dict, List, Tuple
 import numpy as np
 
 from bge_client import EMBED_DIM, embed
+from bm25 import build_token_lists
 from chunker import DEFAULT_OVERLAP, DEFAULT_WINDOW, Chunk, chunk_file
 
 CHUNKS_FILE = "chunks.json"
 VECTORS_FILE = "vectors.npy"
+BM25_FILE = "bm25.json"
 DOC_EXTS = (".md", ".txt")
 
 
@@ -39,32 +42,42 @@ def scan_docs(doc_dir: Path) -> List[Path]:
     return docs
 
 
-def load_index(index_dir: Path) -> Tuple[List[dict], np.ndarray]:
+def load_index(index_dir: Path) -> Tuple[List[dict], np.ndarray, List[List[str]]]:
+    """返回 (chunks, vectors, token_lists)。bm25.json 缺失则 token_lists 为空（向后兼容）。"""
     chunks_path = index_dir / CHUNKS_FILE
     vectors_path = index_dir / VECTORS_FILE
     if not chunks_path.exists() or not vectors_path.exists():
-        return [], np.zeros((0, EMBED_DIM), dtype=np.float32)
+        return [], np.zeros((0, EMBED_DIM), dtype=np.float32), []
     with chunks_path.open("r", encoding="utf-8") as f:
         chunks = json.load(f)
     vectors = np.load(str(vectors_path))
-    return chunks, vectors
+    bm25_path = index_dir / BM25_FILE
+    if bm25_path.exists():
+        with bm25_path.open("r", encoding="utf-8") as f:
+            token_lists = json.load(f)
+    else:
+        token_lists = [[] for _ in chunks]
+    return chunks, vectors, token_lists
 
 
-def save_index(index_dir: Path, chunks: List[dict], vectors: np.ndarray) -> None:
+def save_index(index_dir: Path, chunks: List[dict], vectors: np.ndarray,
+               token_lists: List[List[str]]) -> None:
     index_dir.mkdir(parents=True, exist_ok=True)
     with (index_dir / CHUNKS_FILE).open("w", encoding="utf-8") as f:
         json.dump(chunks, f, ensure_ascii=False, indent=2)
     np.save(str(index_dir / VECTORS_FILE), vectors.astype(np.float32))
+    with (index_dir / BM25_FILE).open("w", encoding="utf-8") as f:
+        json.dump(token_lists, f, ensure_ascii=False)
 
 
-def _group_by_file(chunks: List[dict], vectors: np.ndarray) -> Dict[str, dict]:
-    """把现有索引按 file 分组，便于按文件复用。"""
+def _group_by_file(chunks: List[dict], vectors: np.ndarray, token_lists: List[List[str]]) -> Dict[str, dict]:
     grouped: Dict[str, dict] = {}
     for i, c in enumerate(chunks):
         f = c["file"]
-        grouped.setdefault(f, {"hash": c.get("file_hash", ""), "chunks": [], "vectors": []})
+        grouped.setdefault(f, {"hash": c.get("file_hash", ""), "chunks": [], "vectors": [], "tokens": []})
         grouped[f]["chunks"].append(c)
         grouped[f]["vectors"].append(vectors[i])
+        grouped[f]["tokens"].append(token_lists[i] if i < len(token_lists) else [])
     return grouped
 
 
@@ -76,7 +89,6 @@ def build(
     overlap: int = DEFAULT_OVERLAP,
     timeout: int = 60,
 ) -> dict:
-    """构建/增量更新索引，返回统计信息。"""
     docs = scan_docs(doc_dir)
     current: Dict[str, Tuple[Path, str]] = {}
     for p in docs:
@@ -84,37 +96,40 @@ def build(
 
     existing_chunks: List[dict] = []
     existing_vectors = np.zeros((0, EMBED_DIM), dtype=np.float32)
+    existing_tokens: List[List[str]] = []
     if not rebuild:
-        existing_chunks, existing_vectors = load_index(index_dir)
-    grouped = _group_by_file(existing_chunks, existing_vectors)
+        existing_chunks, existing_vectors, existing_tokens = load_index(index_dir)
+    grouped = _group_by_file(existing_chunks, existing_vectors, existing_tokens)
 
     new_chunks: List[dict] = []
     new_vectors: List[np.ndarray] = []
+    new_tokens: List[List[str]] = []
     reused = 0
     reembedded_files = 0
     total_chunks = 0
 
-    # 按相对路径排序，保证索引顺序稳定
     for rel in sorted(current.keys()):
         path, fhash = current[rel]
         cached = grouped.get(rel)
         if cached and cached["hash"] == fhash and not rebuild:
             new_chunks.extend(cached["chunks"])
             new_vectors.extend([np.asarray(v, dtype=np.float32) for v in cached["vectors"]])
+            new_tokens.extend(cached["tokens"])
             reused += 1
             total_chunks += len(cached["chunks"])
             continue
 
-        # 变更/新增：重切 + 重 embed
         file_chunks: List[Chunk] = chunk_file(path, doc_dir, window=window, overlap=overlap)
         if not file_chunks:
             continue
         vecs = embed([c.text for c in file_chunks], timeout=timeout)
-        for c, v in zip(file_chunks, vecs):
+        file_tokens = build_token_lists([c.text for c in file_chunks])
+        for c, v, toks in zip(file_chunks, vecs, file_tokens):
             d = c.to_dict()
             d["file_hash"] = fhash
             new_chunks.append(d)
             new_vectors.append(v)
+            new_tokens.append(toks)
         reembedded_files += 1
         total_chunks += len(file_chunks)
 
@@ -122,7 +137,7 @@ def build(
         vectors = np.zeros((0, EMBED_DIM), dtype=np.float32)
     else:
         vectors = np.vstack(new_vectors).astype(np.float32)
-    save_index(index_dir, new_chunks, vectors)
+    save_index(index_dir, new_chunks, vectors, new_tokens)
 
     return {
         "doc_total": len(current),

package/skills/knowledge-search-admin/src/scripts/ksearch.py

@@ -1,9 +1,9 @@
 #!/usr/bin/env python3
-"""知识库向量检索管理入口。
+"""知识库检索管理入口。
 
 子命令：
-  build    扫描文档目录，构建/增量更新本地向量索引
-  search   对一条 query 做向量召回 + rerank 精排，输出匹配片段的位置
+  build    扫描文档目录，构建/增量更新向量索引 + BM25 token 索引
+  search   混合召回（dense+BM25 RRF）+ rerank 精排 + 类型加权 + 文件分散
 
 输出格式（stdout）：
   build   -> STATUS=...\nSTATS=...（JSON）
@@ -13,17 +13,25 @@
 
 import argparse
 import json
+import math
 import sys
 from pathlib import Path
 
 import numpy as np
 
 from bge_client import embed, rerank
+from bm25 import tokenize
 from chunker import DEFAULT_OVERLAP, DEFAULT_WINDOW
 from index_store import build, load_index
+from ranker import (
+    FAQ_BOOST_DEFAULT, OVERVIEW_BOOST_DEFAULT, THRESHOLD_DEFAULT,
+    apply_type_boost, diversify_by_file, rrf_fuse, sigmoid_norm,
+)
 
 DEFAULT_RECALL = 30
+DEFAULT_RECALL_TOP = 50
 DEFAULT_TOP = 10
+DEFAULT_MAX_PER_FILE = 2
 
 
 def _emit(status: str, **fields) -> None:
@@ -52,17 +60,52 @@ def cmd_build(args: argparse.Namespace) -> int:
             overlap=args.overlap,
             timeout=args.timeout,
         )
-    except Exception as e:  # noqa: BLE001 - 顶层兜底，输出结构化错误
+    except Exception as e:  # noqa: BLE001
         _emit("failed", ERROR_MESSAGE="build 失败：%s" % e)
         return 1
     _emit("succeeded", STATS=stats, INDEX_DIR=str(index_dir))
     return 0
 
 
+def _bm25_search(token_lists, query_tokens):
+    """内存 BM25 打分。返回 [(idx, score)] 降序。"""
+    N = len(token_lists)
+    if N == 0:
+        return []
+    df: dict = {}
+    doc_len = []
+    for toks in token_lists:
+        seen = set(toks)
+        for t in seen:
+            df[t] = df.get(t, 0) + 1
+        doc_len.append(len(toks))
+    avgdl = (sum(doc_len) / N) if N else 0.0
+    avgdl = avgdl or 1.0
+    k1, b = 1.5, 0.75
+    scores = [0.0] * N
+    for i, toks in enumerate(token_lists):
+        tf: dict = {}
+        for t in toks:
+            tf[t] = tf.get(t, 0) + 1
+        dl = doc_len[i] or 1
+        s = 0.0
+        for t in query_tokens:
+            d = df.get(t, 0)
+            if d == 0:
+                continue
+            idf = math.log(1 + (N - d + 0.5) / (d + 0.5))
+            f = tf.get(t, 0)
+            denom = f + k1 * (1 - b + b * dl / avgdl)
+            s += idf * (f * (k1 + 1)) / denom
+        scores[i] = s
+    ranked = sorted(range(N), key=lambda i: scores[i], reverse=True)
+    return [(i, scores[i]) for i in ranked]
+
+
 def cmd_search(args: argparse.Namespace) -> int:
     index_dir = Path(args.index_dir).resolve()
     try:
-        chunks, vectors = load_index(index_dir)
+        chunks, vectors, token_lists = load_index(index_dir)
     except Exception as e:  # noqa: BLE001
         _emit("failed", ERROR_MESSAGE="加载索引失败：%s" % e)
         return 1
@@ -71,36 +114,63 @@ def cmd_search(args: argparse.Namespace) -> int:
         return 0
 
     try:
-        q_vec = embed([args.query], timeout=args.timeout)[0]  # (1024,)
+        q_vec = embed([args.query], timeout=args.timeout)[0]
     except Exception as e:  # noqa: BLE001
         _emit("failed", ERROR_MESSAGE="编码 query 失败：%s" % e)
         return 1
 
-    # 余弦相似度（向量已 L2 归一化，内积即余弦）
-    sims = vectors @ q_vec
-    recall_n = min(args.recall, len(chunks))
-    top_idx = np.argsort(-sims)[:recall_n].tolist()
+    n = len(chunks)
+    recall_n = min(args.recall, n)
 
-    # rerank 精排
-    cand_texts = [chunks[i]["text"] for i in top_idx]
+    # dense 召回
+    sims = vectors @ q_vec
+    dense_rank = np.argsort(-sims)[:recall_n].tolist()
+
+    # BM25 召回（可关）
+    if args.no_bm25 or not token_lists or not any(token_lists):
+        bm25_rank = []
+    else:
+        q_tokens = tokenize(args.query)
+        bm25_all = _bm25_search(token_lists, q_tokens) if q_tokens else []
+        bm25_rank = [idx for idx, _ in bm25_all[:recall_n]]
+
+    # RRF 融合
+    if bm25_rank:
+        cand_idx = rrf_fuse(dense_rank, bm25_rank, top=DEFAULT_RECALL_TOP)
+    else:
+        cand_idx = dense_rank[:DEFAULT_RECALL_TOP]
+
+    cand_texts = [chunks[i]["text"] for i in cand_idx]
     try:
         ranked = rerank(args.query, cand_texts, timeout=args.timeout)
-    except Exception as e:  # noqa: BLE001
-        # rerank 失败时回退到向量召回分数
-        ranked = [(j, float(sims[top_idx[j]])) for j in range(len(top_idx))]
+        raw_scores = {local: s for local, s in ranked}
+    except Exception:
+        raw_scores = {j: float(sims[cand_idx[j]]) for j in range(len(cand_idx))}
+
+    items = []
+    for local, idx in enumerate(cand_idx):
+        norm = sigmoid_norm(float(raw_scores.get(local, 0.0)))
+        items.append({
+            "idx": idx,
+            "norm": norm,
+            "type": chunks[idx].get("type", "normal"),
+            "file": chunks[idx]["file"],
+        })
+
+    faq_boost = 0.0 if args.no_faq_boost else args.faq_boost
+    over_boost = 0.0 if args.no_faq_boost else OVERVIEW_BOOST_DEFAULT
+    boosted = apply_type_boost(items, faq_boost=faq_boost, overview_boost=over_boost)
+    final = diversify_by_file(boosted, max_per_file=args.max_per_file,
+                              top=args.top, threshold=args.threshold)
 
-    top_k = min(args.top, len(ranked))
     results = []
-    for rank_pos, (local_idx, score) in enumerate(ranked[:top_k]):
-        if args.threshold > 0 and score < args.threshold:
-            continue
-        global_idx = top_idx[local_idx]
-        c = chunks[global_idx]
+    for it in final:
+        c = chunks[it["idx"]]
         item = {
             "file": c["file"],
             "heading_path": c["heading_path"],
             "loc": {"start_line": c["start_line"], "end_line": c["end_line"]},
-            "score": round(float(score), 5),
+            "score": round(float(it["norm"]), 5),
         }
         if not args.no_snippet:
             item["snippet"] = c["text"][:200]
@@ -111,26 +181,33 @@ def cmd_search(args: argparse.Namespace) -> int:
 
 
 def main() -> int:
-    parser = argparse.ArgumentParser(description="知识库向量检索管理：build / search")
+    parser = argparse.ArgumentParser(description="知识库检索管理：build / search")
     sub = parser.add_subparsers(dest="command", required=True)
 
-    p_build = sub.add_parser("build", help="构建/增量更新向量索引")
-    p_build.add_argument("--doc-dir", required=True, help="知识库文档目录（如 knowledge/）")
+    p_build = sub.add_parser("build", help="构建/增量更新索引")
+    p_build.add_argument("--doc-dir", required=True, help="知识库文档目录")
     p_build.add_argument("--index-dir", required=True, help="索引产物目录")
-    p_build.add_argument("--rebuild", action="store_true", help="全量重建（忽略已有索引）")
+    p_build.add_argument("--rebuild", action="store_true", help="全量重建")
     p_build.add_argument("--window", type=int, default=DEFAULT_WINDOW, help="切块窗口字符数（默认 800）")
-    p_build.add_argument("--overlap", type=int, default=DEFAULT_OVERLAP, help="相邻 chunk 重叠字符数（默认 150）")
+    p_build.add_argument("--overlap", type=int, default=DEFAULT_OVERLAP, help="重叠字符数（默认 150）")
     p_build.add_argument("--timeout", type=int, default=60, help="单次 API 超时秒数")
     p_build.set_defaults(func=cmd_build)
 
-    p_search = sub.add_parser("search", help="向量召回 + rerank 检索")
+    p_search = sub.add_parser("search", help="混合召回 + rerank 检索")
     p_search.add_argument("--query", required=True, help="查询文本")
     p_search.add_argument("--index-dir", required=True, help="索引目录")
-    p_search.add_argument("--recall", type=int, default=DEFAULT_RECALL, help="向量召回数")
-    p_search.add_argument("--top", type=int, default=DEFAULT_TOP, help="最终返回条数")
-    p_search.add_argument("--threshold", type=float, default=0.0, help="rerank 分数阈值，低于则丢弃")
+    p_search.add_argument("--recall", type=int, default=DEFAULT_RECALL, help="每路召回数（默认 30）")
+    p_search.add_argument("--top", type=int, default=DEFAULT_TOP, help="最终返回数（默认 10）")
+    p_search.add_argument("--threshold", type=float, default=THRESHOLD_DEFAULT,
+                          help="相关度闸口，作用于归一化 norm（默认 0.5；0=不过滤）")
+    p_search.add_argument("--max-per-file", type=int, default=DEFAULT_MAX_PER_FILE,
+                          help="同一文件最多进榜条数（默认 2）")
+    p_search.add_argument("--faq-boost", type=float, default=FAQ_BOOST_DEFAULT,
+                          help="FAQ 加权幅度（默认 0.15）")
+    p_search.add_argument("--no-bm25", action="store_true", help="关闭 BM25，纯 dense")
+    p_search.add_argument("--no-faq-boost", action="store_true", help="关闭类型加权")
     p_search.add_argument("--no-snippet", action="store_true", help="不输出片段文本")
-    p_search.add_argument("--timeout", type=int, default=60, help="单次 API 趃时秒数")
+    p_search.add_argument("--timeout", type=int, default=60, help="单次 API 超时秒数")
     p_search.set_defaults(func=cmd_search)
 
     args = parser.parse_args()

package/skills/knowledge-search-admin/src/scripts/ranker.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""检索排序管线：RRF 融合 + sigmoid 归一化 + 类型加权 + 文件级分散 + 阈值。
+
+与 knowledge-search skill 中的 ranker.py 保持一致。
+
+排序流程：
+  dense 召回 Top-N + bm25 召回 Top-N
+    → rrf_fuse 融合取 Top-F（候选下标，按 final 排序前的池子）
+  → 对候选调 rerank 得原始分 → sigmoid_norm 归一化为 norm (0~1)
+  → apply_type_boost：final = norm + boost(type)，按 final 降序
+  → diversify_by_file：按 final 降序、同 file 上限、norm 阈值过滤、取 Top-K
+  输出 score 字段 = norm（不含 boost），FAQ 优先体现在排序而非 score 值。
+"""
+
+import math
+from typing import List, Sequence
+
+FAQ_BOOST_DEFAULT = 0.15
+OVERVIEW_BOOST_DEFAULT = 0.05
+THRESHOLD_DEFAULT = 0.6
+RRF_K = 60
+
+
+def rrf_fuse(dense_rank: Sequence[int], bm25_rank: Sequence[int],
+             k: int = RRF_K, top: int = 50) -> List[int]:
+    """两路排名 RRF 融合，返回融合后按分降序的下标列表（最多 top 个，去重）。"""
+    scores: dict = {}
+    for rank, idx in enumerate(dense_rank):
+        scores[idx] = scores.get(idx, 0.0) + 1.0 / (k + rank + 1)
+    for rank, idx in enumerate(bm25_rank):
+        scores[idx] = scores.get(idx, 0.0) + 1.0 / (k + rank + 1)
+    ordered = sorted(scores.items(), key=lambda kv: kv[1], reverse=True)
+    return [idx for idx, _ in ordered[:top]]
+
+
+def sigmoid_norm(raw: float) -> float:
+    """rerank 原始分（无界）→ (0,1) 归一化。"""
+    if raw >= 0:
+        z = math.exp(-raw)
+        return 1.0 / (1.0 + z)
+    z = math.exp(raw)
+    return z / (1.0 + z)
+
+
+def apply_type_boost(items: List[dict], faq_boost: float, overview_boost: float) -> List[dict]:
+    """给每个 item 加 final = norm + boost(type)，按 final 降序返回。"""
+    out: List[dict] = []
+    for it in items:
+        norm = it["norm"]
+        t = it.get("type", "normal")
+        boost = faq_boost if t == "faq" else (overview_boost if t == "overview" else 0.0)
+        enriched = dict(it)
+        enriched["final"] = norm + boost
+        out.append(enriched)
+    # round 排序键以抵消浮点误差（如 0.55+0.05 略大于 0.6+0.0），同分时稳定保序
+    out.sort(key=lambda x: round(x["final"], 9), reverse=True)
+    return out
+
+
+def diversify_by_file(items: List[dict], max_per_file: int, top: int,
+                      threshold: float = THRESHOLD_DEFAULT) -> List[dict]:
+    """按 final 降序遍历，同 file 计数上限 max_per_file；norm < threshold 丢弃；取 top。"""
+    per_file: dict = {}
+    out: List[dict] = []
+    for it in items:  # items 已按 final 降序
+        f = it.get("file", "")
+        if per_file.get(f, 0) >= max_per_file:
+            continue
+        if it.get("norm", 1.0) < threshold:
+            continue
+        per_file[f] = per_file.get(f, 0) + 1
+        out.append(it)
+        if len(out) >= top:
+            break
+    return out