vibe-hnindex

---

功能介绍

vibe-hnindex 是一个 Model Context Protocol 服务。为文件夹建立索引后，助手（Claude、Cursor、Windsurf、Antigravity，等等）便可通过路径和行范围搜索该代码库 — 数据存储在本地（SQLite + 可选的 Qdrant）。嵌入支持 Ollama（默认）、OpenAI、Voyage、Gemini 或 OpenAI 兼容 API；详见嵌入服务商。云端服务商会接收待嵌入的内容；向量使用 Qdrant（Docker、本地或通过 QDRANT_API_KEY 使用 Qdrant Cloud）。

---

文档

源代码安全审查：security_audit、security_context 和 pentest_plan 可提供实时源代码证据和验证检查。可选的 Voyage/HTTP 重排遵循服务配置；rerank:false 可让审查保留在本地。结果是包含明确覆盖范围的启发式审查线索，并非已确认的漏洞报告。

📚 完整文档站点：docs.hnindex.cloud — 共 16 个页面，涵盖入门指南、配置、工具参考、指南和代码 Agent。

页面	你将了解到
简介	vibe-hnindex 的功能、主要特性及工作原理
安装	Node、Ollama、Qdrant 配置 + MCP 配置
快速开始	通过 CLI + Agent 技能快速上手，耗时 5 分钟
配置	全部 25+ 个环境变量及嵌入模型对比
搜索	6 种搜索模式、正则表达式、模糊搜索、流式处理、缓存
代码 Agent 🆕	带安全作用域的 code_session + code_apply
配置 MCP	各平台配置（Claude、Cursor、Antigravity、VS Code……）

仓库内还提供：docs/getting-started.md、docs/configuration.md、docs/tools-reference.md。

---

CLI 安装程序（hnindex）

可选 — 为你写入 MCP JSON 或 Codex TOML（安全合并，与文档中的 npx -y vibe-hnindex 配置块相同）：

npm install -g hnindex-cli

# Setup MCP config
hnindex init --mcp antigravity    # or: claude, cursor, windsurf, vscode, codex
hnindex init --list               # show all targets and paths

# Install AI agent skill (recommended)
hnindex init-skill --target claude    # or: antigravity, cursor, windsurf, vscode
hnindex init-skill --list             # show all skill targets

# Update
hnindex update                    # npm update -g hnindex-cli

完整文档请参见 docs.hnindex.cloud。

---

5 步完成安装

1. Node.js — v22+（nodejs.org）。CI 会验证 Node 22 和 24。SQLite 使用为受支持平台捆绑的 N-API 二进制文件；如果 npm i vibe-hnindex 失败，请参阅故障排除 → Windows。
2. 嵌入提供商 — 选择 OpenAI、Voyage、Gemini 或兼容的 API，也可以使用本地 Ollama：从 ollama.com 安装，然后运行：ollama pull bge-m3:567m，并保持 ollama serve 在运行（或将 OLLAMA_URL 设置为远程服务）。
3. Qdrant — 用于语义／混合搜索：docker run -d --name qdrant -p 6333:6333 qdrant/qdrant（或使用 Qdrant Cloud）。仅关键词搜索无需 Qdrant。
4. MCP 配置 — 将服务添加到助手的 MCP 设置中。最精简示例（可自托管的 Qdrant）：

{
  "mcpServers": {
    "vibe-hnindex": {
      "command": "npx",
      "args": ["-y", "vibe-hnindex"],
      "env": {
        "OLLAMA_URL": "http://localhost:11434",
        "OLLAMA_MODEL": "bge-m3:567m",
        "QDRANT_URL": "http://localhost:6333",
        "SEARCH_STREAM_ENABLED": "true",
        "CODE_AGENT_ENABLED": "true",
        "CODE_AGENT_SCOPE": "moderate",
        "CHAT_MEMORY_ENABLED": "true"
      }
    }
  }
}

5. 重启 IDE 或助手，然后在聊天中要求索引一个路径并进行搜索 — 请参阅入门步骤。

对于 Qdrant Cloud，请添加 QDRANT_API_KEY，并将 QDRANT_URL 设置为你的 HTTPS 集群 URL — 详情请参阅入门指南。

Agent 工作区

workspace_context 用于识别当前项目的用途、Git／索引状态，以及按项目／会话持久化的已声明任务。locate_code 会在本地查找文件／符号，然后搜索关键词，并返回行级证据及新鲜度信息。显式混合模式会使用已配置的语义 API。MCP 启动说明和 knowledge://workspace 会公开此工作流。项目范围的 CLI 安装会自动绑定其根目录；全局安装则遵循客户端根目录，除非显式配置。

请参阅工作区和代码位置。编辑前请刷新过时的位置；对于不可用或已排除的代码，请使用文件系统工具。

代码图谱

仅使用 SQLite，通过 index_code_graph(path, project_name) 构建多语言 AST 符号图。index_codebase 也会构建该图；文件索引和监视会自动更新关系。使用 find_references、callers 和 graph_context 检查源代码证据及有界关系上下文。SQLite 仍是图谱后端。JS/TS 保留编译器解析；Python、PHP、Go、Java、C/C++、C#、Rust、Ruby、Kotlin、Swift、Scala 和 Lua 使用捆绑的离线 Tree-sitter 配置。请参阅图谱指南中的语言覆盖范围和解析限制。

AST 分块会尽可能保留函数／类边界。升级后，请运行一次 index_codebase 以重建分块和向量。有关解析限制、离线用法、令牌预算和质量评估，请参阅代码图谱指南。

可选重排序

混合搜索使用 RRF 合并关键词结果和嵌入向量。可选的重排序支持 Voyage（RERANK_PROVIDER=voyage、VOYAGE_API_KEY 或 RERANK_API_KEY）和自定义 HTTP（RERANK_PROVIDER=http、RERANK_URL）。如果没有重排序器，或重排序器运行失败，则保留原始检索排序。精确符号／正则模式会跳过重排序。

环境变量	用途
SEARCH_RERANK	设置为 false 可禁用重排序。
SEARCH_RERANK_POOL	最终截取前的候选池（默认值为 50；至少等于请求的上限）。
RERANK_PROVIDER	none、http、voyage；设置了 RERANK_URL 时默认为 http，否则为 none。
RERANK_MODEL	Voyage 模型，默认值为 rerank-3-lite。
RERANK_URL	自定义端点；HTTP 格式为 {query, documents} -> {scores}。
RERANK_API_KEY	可选的 Bearer 凭据；Voyage 可使用 VOYAGE_API_KEY。
RERANK_TIMEOUT_MS	完整请求／正文超时时间，默认值为 15000。

请参阅配置。

超时

为避免 Ollama 或 Qdrant 无响应时一直等待，vibe-hnindex 会对所有外部调用设置超时。你可以通过环境变量调整这些超时时间：

环境变量	默认值	控制范围
OLLAMA_TIMEOUT_MS	30000（30s）	Ollama /api/embed 和 /api/tags 调用的最长等待时间
QDRANT_TIMEOUT_MS	15000（15s）	Qdrant API 调用（搜索、upsert 等）的最长等待时间
SEARCH_TIMEOUT_MS	60000（60s）	整个搜索操作的总超时时间

如果机器速度较慢或数据集较大，可将任一变量设为更高的值。设为 0 可禁用该层的超时（不推荐）。

Google Antigravity

使用与上文相同的 mcpServers 配置块，但将其保存到 Antigravity 的 MCP 文件中：

文件	用户文件夹下 .gemini/antigravity/ 中的 mcp_config.json
Windows	C:\Users\<your-username>\.gemini\antigravity\mcp_config.json
macOS / Linux	~/.gemini/antigravity/mcp_config.json
界面	⋮ 菜单 → MCP → 管理 MCP 服务 → 查看原始配置

分步说明：集成 → Google Antigravity。

---

功能（简要）

搜索	6 种模式：关键词（FTS5+BM25）、语义（Qdrant 向量）、混合（RRF 融合）、正则表达式、符号、自动
编码 Agent	code_session — 1 次调用可替代 5-15 次搜索。code_apply — 安全修改代码，并自动运行测试、lint 和类型检查
聊天记忆 🆕	自动追踪工具调用，通过 Qdrant 进行语义搜索，在不同会话间持久保留 AI 上下文
流式处理	并行执行关键词和语义搜索，并发送进度通知
模糊搜索	Levenshtein 距离算法可自动纠正拼写错误（“fucntion” → “function”）
智能上下文	感知任务的上下文：影响分析、测试文件检测、相似代码模式
存储	使用 SQLite 存储关键词、图和元数据；使用 Qdrant 存储向量；可选云端嵌入和重排服务提供商
索引	增量变更检测、并行工作线程、监视模式、跨语言文本索引、.hnindexignore
弹性	即使没有 Qdrant 或 Ollama，关键词搜索也能正常工作；可优雅降级
基准测试	内置 benchmark_search 工具 — 比较流式与非流式处理，以及所有搜索模式
多种嵌入服务提供商	Ollama、OpenAI、Voyage、Gemini 和兼容 OpenAI 的 API；向量集合可感知服务提供商和模型
多种嵌入模型	bge-m3（默认）、nomic-embed-text、qwen3-embedding、mxbai-embed-large 等

---

架构

flowchart TB
    accTitle: hnindex system architecture
    accDescr: An MCP agent calls a local hnindex server with workspace files and SQLite storage. Semantic retrieval optionally uses embeddings and Qdrant.
    agent_client["AI agent / MCP client<br/>Codex · Claude · Cursor"]
    subgraph local_workspace["Local workspace"]
        hnindex_server["hnindex MCP server<br/>Context · multilingual AST · code lookup"]
        project_files["Source files<br/>README · Git"]
        sqlite_store[("SQLite<br/>FTS · graph · declared tasks")]
        security_review["Security review<br/>Live source · bounded leads · validation plan"]
        hnindex_server --> security_review
        project_files --> security_review
        project_files -->|Read and check freshness| hnindex_server
        hnindex_server <-->|Index and task storage| sqlite_store
    end
    subgraph semantic_services["Optional semantic retrieval"]
        embedding_provider["Embeddings<br/>Ollama local or cloud API"]
        qdrant_store[("Qdrant vectors<br/>Local or hosted")]
    end
    agent_client <-->|MCP / stdio| hnindex_server
    hnindex_server -.->|Code chunks and queries| embedding_provider
    embedding_provider -.->|Vectors| hnindex_server
    hnindex_server <-.->|Store and retrieve vectors| qdrant_store
    security_review -.->|Redacted query and evidence when enabled| reranker["Optional Voyage / HTTP rerank"]

索引与搜索的工作原理 →

---

许可证

MIT — 参见 LICENSE。

参与贡献

问题反馈和 PR：github.com/AndyAnh174/vibe-hnindex。

联系方式

Ho Viet Anh (AndyAnh174) · [email protected] · GitHub

Codex 与架构

在项目中运行 npx -y hnindex-cli init --mcp codex，然后可选运行 npx -y hnindex-cli init-skill --target codex。Codex 项目 MCP 使用 .codex/config.toml（仅限受信任的项目）；技能使用 .agents/skills/use-vibe-hnindex。重启或重新连接 Codex，并请求 workspace_context，然后请求 index_code_graph。

参见 CLI 配置、系统、时序和用户图，以及 Codex 官方 MCP 设置指南。