local-search

name	local-search
description	本地文档检索与 RAG 工具，支持多 Workspace 管理。 当用户需要： (1) 在本地文档库中搜索信息 (2) 管理多个文档集合（workspace） (3) 将本地文件/目录（支持 md, pdf, txt, srt, ass）入库并向量化 使用此 skill。

Local Search - 本地 RAG 检索工具

这是一个轻量级、可移植的本地 RAG 检索库。

⚠️ 首次使用 / 环境初始化 (CRITICAL)

由于包含 C++ 扩展（hnswlib），本 Skill 不包含 预编译环境。 在任何项目中使用此 Skill 时，Agent 必须首先执行以下命令来初始化环境：

# 使用 run_shell_command 执行
.\scripts\install.ps1

该脚本将自动：

1. 检查或创建 .venv 虚拟环境。
2. 安装所有必需的依赖项（numpy, hnswlib, openai, pdfplumber, requests 等）。 切勿将 .venv 提交到版本控制系统中。

---

使用方式

环境初始化成功后，你可以通过 CLI 脚本快速执行入库和检索任务。 默认情况下，索引数据会保存在当前命令执行目录下的 local_search_data 文件夹中。

1. 检查当前状态

.\.venv\Scripts\python.exe .\scripts\run_local_search.py --status

2. 文档入库 (Ingest)

自动扫描目标文件夹并将支持的文件入库。

# 将 "docs" 文件夹内容入库到 "my_project" 工作区
.\.venv\Scripts\python.exe .\scripts\run_local_search.py --workspace "my_project" --ingest "./docs"

3. 检索 (Search)

在指定工作区中进行混合检索（基于向量和 SiliconFlow Rerank）。

.\.venv\Scripts\python.exe .\scripts\run_local_search.py --workspace "my_project" --query "如何使用 RAG？" --top-k 5

---

进阶：通过 Python 脚本调用 API

如果 CLI 无法满足复杂的逻辑流，你可以写一个临时的 Python 脚本并在 .venv 中运行它：

# test_rag.py
import sys
from pathlib import Path

# 确保能找到 local_search 模块
sys.path.append(str(Path(".").resolve() / "scripts"))

from local_search import create_local_search_tool

tool = create_local_search_tool(
    reranker_api_key="your-siliconflow-api-key",  # 不传将使用默认测试 key
    use_silicon_flow=True,
)

# 入库
tool.add_directory("./我的文档", recursive=True)

# 搜索
results = tool.search("目标关键词", top_k=3)
print(tool.format_results(results))

执行：.\.venv\Scripts\python.exe test_rag.py

路径与工作区说明

• local_search_data：默认的数据存储目录，相对于启动 Agent 时所在的当前工作目录创建。
• Workspace：代表一个独立的向量库。可以通过 --workspace <名称> 隔离不同项目或知识领域的文档。如果不指定，则默认放入 default 工作区。