Copilot Search Pipeline — 本地演示

这是一个轻量的本地 Copilot-style search pipeline 演示工程，目的是展示语义检索与基础符号/引用查找的端到端工作流。主要功能：

• 文档/代码加载 (src/loader.py)
• 本地嵌入（sentence-transformers，见 src/embedder.py）
• 向量索引（FAISS，回退到 NumPy，见 src/indexer.py）
• 检索与重排序（retriever + cross-encoder reranker，见 src/retriever.py、src/reranker.py）
• 符号索引与引用查找（Python AST + jedi 回退，见 src/symbols.py）

适用场景：研究/验证语义搜索思路、在本地对小到中等代码仓库做意图检索、演示与教学。

先决条件

• Python 3.9+（推荐使用同仓库下的虚拟环境 .venv）
• 建议网络可访问 Hugging Face Hub（模型首次会下载）

快速开始（推荐）

在项目根目录执行：

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

# 构建语义索引（会下载模型并生成嵌入）
.
python src\app.py --build

# 构建 Python 符号索引
python src\app.py --build-symbols

# 运行一次语义查询
python src\app.py --query "如何写一个单元测试？"

# 查找符号引用（示例）
python src\app.py --find-refs foo

主要命令说明

• --build：生成语义嵌入并构建向量索引（FAISS 或 NumPy 回退）。
• --query <文本>：按自然语言或代码片段检索相关文档/片段并输出重排序后的 top-k。
• --build-symbols：扫描 Python 源文件，写入 .index/symbols.json（函数/类列表）。
• --symbol <name>：在已构建的符号索引中按名称查找（子串匹配）。
• --find-refs <symbol>：查找符号引用；优先使用 jedi 做 Python 引用解析，回退到 token 扫描以支持其他语言。

集成测试与日志

项目包含一个轻量的集成测试脚本：scripts/integration_test.py。

用法：

.\.venv\Scripts\python scripts\integration_test.py       # 运行测试（不安装依赖）
.\.venv\Scripts\python scripts\integration_test.py --install   # 先安装依赖再运行

脚本会执行：--build、--build-symbols、--query、--find-refs，并把每步输出写到 reports/（例如 reports/query.log），最终生成 reports/integration_report.json。

故障排查快速指南

• 报错 ModuleNotFoundError: No module named 'numpy'：通常是虚拟环境未激活或依赖未安装。请运行：

   .\.venv\Scripts\Activate.ps1
   python -m pip install -r requirements.txt

• Hugging Face 下载慢或受限：设置 HF_TOKEN 环境变量以提高速率限制，或预先手动下载模型到缓存。
• 若需要更准确的跨语言符号/引用：建议安装 universal-ctags 并集成解析，或在编辑器内使用 LSP（推荐用于生产级跳转）。

示例输出（预期）

• --query 会打印重排序后的结果列表（例如 doc1.txt, doc2.txt, ...）。
• --find-refs foo 会列出包含 foo 的引用行及文件位置（在 sample_data/example.py 有示例）。

（如需进一步功能或集成说明，请查看上方命令与日志章节，或直接运行集成测试以验证环境。）