sophhub 0.4.65 → 0.4.67

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

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""BGE-M3 embedding 与 bge-reranker-v2-m3 客户端。
+
+通过 stdlib urllib 调用 Sophnet 平台接口，返回 L2 归一化后的向量与 rerank 分数。
+平台 ApiKey 在运行时由 sophnet_tools.get_api_key() 获取，不再硬编码。
+"""
+
+import json
+import os
+import urllib.error
+import urllib.request
+from typing import List, Tuple
+
+import numpy as np
+
+# Sophnet 平台接口地址
+BASE_URL = "https://www.sophnet.com/api/open-apis"
+EMBED_URL = BASE_URL + "/projects/easyllms/embeddings"
+RERANK_URL = BASE_URL + "/projects/rerank"
+
+EMBED_MODEL = "bge-m3"
+RERANK_MODEL = "bge-reranker-v2-m3"
+EMBED_DIM = 1024
+EMBED_BATCH = 8      # embedding 单次输入条数上限（按需保守取 8）
+RERANK_BATCH = 256   # rerank 接口单次 documents 上限
+DEFAULT_TIMEOUT = 60
+
+
+class BgeError(RuntimeError):
+    pass
+
+
+def _get_api_key() -> str:
+    """运行时获取平台 ApiKey：优先 sophnet_tools.get_api_key()，回退环境变量 SOPHNET_API_KEY。"""
+    try:
+        import sophnet_tools  # noqa: S404 - 平台运行时提供
+        key = sophnet_tools.get_api_key()
+        if key:
+            return key
+    except ImportError:
+        pass
+    key = os.environ.get("SOPHNET_API_KEY")
+    if not key:
+        raise BgeError("未找到 Sophnet 平台 ApiKey（sophnet_tools 不可用且 SOPHNET_API_KEY 未设置），请联系客户支持")
+    return key
+
+
+def _post_json(url: str, key: str, payload: dict, timeout: int = DEFAULT_TIMEOUT) -> dict:
+    body = json.dumps(payload).encode("utf-8")
+    req = urllib.request.Request(
+        url=url,
+        data=body,
+        method="POST",
+        headers={
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "Authorization": "Bearer %s" % key,
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            raw = resp.read()
+    except urllib.error.HTTPError as e:
+        snippet = e.read()[:300].decode("utf-8", "replace")
+        raise BgeError("HTTP %s 调用 %s 失败：%s" % (e.code, url, snippet))
+    except urllib.error.URLError as e:
+        raise BgeError("网络错误，无法访问 %s：%s" % (url, e.reason))
+    try:
+        return json.loads(raw.decode("utf-8"))
+    except ValueError:
+        raise BgeError("响应非 JSON：%s" % raw[:300].decode("utf-8", "replace"))
+
+
+def _l2_normalize(matrix: np.ndarray) -> np.ndarray:
+    norms = np.linalg.norm(matrix, axis=1, keepdims=True)
+    norms[norms == 0] = 1.0
+    return (matrix / norms).astype(np.float32)
+
+
+def embed(texts: List[str], timeout: int = DEFAULT_TIMEOUT) -> np.ndarray:
+    """批量编码文本，返回 L2 归一化后的 float32 矩阵 (N, 1024)。"""
+    texts = [t for t in texts]
+    if not texts:
+        return np.zeros((0, EMBED_DIM), dtype=np.float32)
+
+    key = _get_api_key()
+    vectors: List[List[float]] = []
+    for start in range(0, len(texts), EMBED_BATCH):
+        batch = texts[start:start + EMBED_BATCH]
+        payload = {
+            "model": EMBED_MODEL,
+            "input_texts": batch,
+            "dimensions": EMBED_DIM,
+        }
+        data = _post_json(EMBED_URL, key, payload, timeout=timeout)
+        # OpenAI 风格：{"data":[{"index":i,"embedding":[...]}, ...]}
+        items = data.get("data") if isinstance(data, dict) else None
+        if not isinstance(items, list) or len(items) != len(batch):
+            raise BgeError("embed 响应形状异常：期望 %d 条，实际 %s" % (len(batch), type(data).__name__))
+        # 按 index 排序后取 embedding，确保与输入顺序对齐
+        items_sorted = sorted(items, key=lambda x: int(x.get("index", 0)))
+        vectors.extend([item["embedding"] for item in items_sorted])
+    matrix = np.asarray(vectors, dtype=np.float32)
+    if matrix.ndim != 2 or matrix.shape[1] != EMBED_DIM:
+        raise BgeError("embed 向量维度异常：%s" % (matrix.shape,))
+    return _l2_normalize(matrix)
+
+
+def rerank(query: str, texts: List[str], timeout: int = DEFAULT_TIMEOUT) -> List[Tuple[int, float]]:
+    """对候选文本按与 query 的相关性打分，返回 [(原下标, score)] 降序。"""
+    if not texts:
+        return []
+    key = _get_api_key()
+
+    def _rerank_batch(batch: List[str], offset: int) -> List[Tuple[int, float]]:
+        payload = {
+            "model": RERANK_MODEL,
+            "query": query,
+            "documents": batch,
+            "return_documents": False,
+        }
+        data = _post_json(RERANK_URL, key, payload, timeout=timeout)
+        # Result 外层：{"status":0,"result":[{"index":i,"score":s}, ...]}
+        if isinstance(data, dict) and data.get("status", 0) != 0:
+            raise BgeError("rerank 接口返回错误：%s" % data.get("message", data))
+        result = data.get("result") if isinstance(data, dict) else None
+        if not isinstance(result, list):
+            raise BgeError("rerank 响应形状异常：%s" % type(data).__name__)
+        return [(int(item["index"]) + offset, float(item["score"])) for item in result]
+
+    # 接口单次最多 256 条；超过则分批打分后合并再统一排序。
+    if len(texts) <= RERANK_BATCH:
+        results = _rerank_batch(texts, 0)
+    else:
+        results: List[Tuple[int, float]] = []
+        for start in range(0, len(texts), RERANK_BATCH):
+            results.extend(_rerank_batch(texts[start:start + RERANK_BATCH], start))
+    results.sort(key=lambda x: x[1], reverse=True)
+    return results

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

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+"""只读加载索引（chunks.json + vectors.npy + bm25.json）。
+
+QA skill 仅检索不构建。bm25.json 缺失（老索引）时返回空 token 列表，向后兼容。
+"""
+
+import json
+from pathlib import Path
+from typing import List, Tuple
+
+import numpy as np
+
+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, 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), []
+    with chunks_path.open("r", encoding="utf-8") as f:
+        chunks = json.load(f)
+    vectors = np.load(str(vectors_path))
+    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

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+"""知识库模糊检索（QA Agent 用）。
+
+链路：load 索引 → dense 召回 + BM25 召回 → RRF 融合 → rerank 精排
+      → sigmoid 归一化 → 类型加权 → 文件级分散 → 阈值闸口 → 输出。
+只读索引，不写任何文件。
+
+输出（stdout）：
+  STATUS=succeeded\nRESULTS=[...]
+  STATUS=failed\nERROR_MESSAGE=...
+"""
+
+import argparse
+import json
+import sys
+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:
+    lines = ["STATUS=%s" % status]
+    for k, v in fields.items():
+        if isinstance(v, (dict, list)):
+            lines.append("%s=%s" % (k, json.dumps(v, ensure_ascii=False)))
+        else:
+            lines.append("%s=%s" % (k, v))
+    sys.stdout.write("\n".join(lines) + "\n")
+    sys.stdout.flush()
+
+
+def main() -> int:
+    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=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, token_lists = load_index(index_dir)
+    except Exception as e:  # noqa: BLE001
+        _emit("failed", ERROR_MESSAGE="加载索引失败：%s" % e)
+        return 1
+    if not chunks:
+        _emit("succeeded", RESULTS=[])
+        return 0
+
+    try:
+        q_vec = embed([args.query], timeout=args.timeout)[0]
+    except Exception as e:  # noqa: BLE001
+        _emit("failed", ERROR_MESSAGE="编码 query 失败：%s" % e)
+        return 1
+
+    n = len(chunks)
+    recall_n = min(args.recall, n)
+
+    sims = vectors @ q_vec
+    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 = []
+
+    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)
+        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)
+
+    results = []
+    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(it["norm"]), 5),
+        }
+        if not args.no_snippet:
+            item["snippet"] = c["text"][:200]
+        results.append(item)
+
+    _emit("succeeded", RESULTS=results)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,31 @@
+{
+  "name": "knowledge-search-admin",
+  "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",
+      "changes": ["BGE 接口切换到 Sophnet 平台（/projects/easyllms/embeddings、/projects/rerank），请求/响应字段按新文档适配；ApiKey 改由 sophnet_tools.get_api_key() 运行时获取，不再硬编码；embedding 单次 batch 降至 8"]
+    },
+    {
+      "version": "1.1.0",
+      "date": "2026-07-27",
+      "changes": ["切块策略改为固定窗口滑窗（窗口 800 / 重叠 150），替换原 Markdown 标题切块；保留 heading_path 与起止行号定位能力"]
+    },
+    {
+      "version": "1.0.0",
+      "date": "2026-07-27",
+      "changes": ["初次提交"]
+    }
+  ],
+  "createdAt": "2026-07-27",
+  "updatedAt": "2026-07-29"
+}

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

@@ -0,0 +1,79 @@
+---
+name: knowledge-search-admin
+description: 构建与检索知识库向量索引（BGE-M3 embedding + bge-reranker）。当管理员要求对 knowledge 目录建库、重建向量索引、增量更新、或做模糊检索自测时使用。
+---
+
+# 知识库向量检索管理
+
+对知识库文档目录构建本地向量索引 + BM25 token 索引（按文档类型分流切块：FAQ 按 ## Q: pair 切、其余固定窗口滑窗 → BGE-M3 embedding + char-bigram 分词 → 落本地），并提供混合召回（dense+BM25 RRF）+ reranker 精排 + 类型加权 + 文件分散的检索自测能力。供知识库管理主 Agent 使用；问答 Agent 的在线检索请用配套的 `knowledge-search` skill。
+
+## 用法
+
+```bash
+# 1. 构建/增量更新索引（扫描 knowledge/ 下所有 .md/.txt）
+uv run {baseDir}/scripts/ksearch.py build \
+  --doc-dir knowledge/ \
+  --index-dir knowledge-index/
+
+# 2. 全量重建（忽略已有索引，全部重新 embedding）
+uv run {baseDir}/scripts/ksearch.py build \
+  --doc-dir knowledge/ --index-dir knowledge-index/ --rebuild
+
+# 3. 检索自测：dense+BM25 召回 → RRF 融合 → rerank 精排 → 类型加权 → Top-10
+uv run {baseDir}/scripts/ksearch.py search \
+  --query "怎么办理退款" \
+  --index-dir knowledge-index/ \
+  --recall 30 --top 10
+```
+
+## 参数
+
+build：
+- `--doc-dir`：知识库文档目录（必填）
+- `--index-dir`：索引产物目录（必填）
+- `--rebuild`：全量重建
+- `--window`：切块窗口字符数（默认 800）
+- `--overlap`：相邻 chunk 重叠字符数（默认 150，步长 = 窗口 - 重叠 = 650）
+- `--timeout`：单次 API 超时秒数（默认 60）
+
+search：
+- `--query`：查询文本（必填）
+- `--index-dir`：索引目录（必填）
+- `--recall`：向量召回数（默认 30）
+- `--top`：最终返回条数（默认 10）
+- `--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）
+
+## 输出格式
+
+stdout 输出结构化键值对，便于 LLM 解析：
+
+```
+# build 成功
+STATUS=succeeded
+STATS={"doc_total":12,"reused_files":10,"reembedded_files":2,"chunk_total":86}
+INDEX_DIR=/abs/path/to/knowledge-index
+
+# search 成功
+STATUS=succeeded
+RESULTS=[{"file":"knowledge/售前流程.md","heading_path":"售前流程.md > 退货 > 退款时效","loc":{"start_line":42,"end_line":58},"score":0.86,"snippet":"..."}]
+
+# 失败
+STATUS=failed
+ERROR_MESSAGE=...
+```
+
+## 注意事项
+
+- 索引产物为 `chunks.json`（chunk 元信息，含 type）+ `vectors.npy`（N×1024 float32，L2 归一化）+ `bm25.json`（每行 chunk 的 token 列表）。三个文件行序对齐，不可单独改动。
+- 增量更新按文件 md5 hash 判断变更；未变更文件复用已有向量，仅对变更/新增文件重 embedding。
+- 切块策略：固定窗口滑窗，默认窗口 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

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

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

@@ -0,0 +1 @@
+# knowledge-search-admin