Docdex

🚀 Docdex

Docdex 是一款輕量級的本地文檔索引器和搜索守護程序。它按項目運行，對 Markdown 或文本格式的文檔進行本地索引存儲，可通過 HTTP 或 CLI 為任何編碼輔助工具提供排名前 k 的文檔片段，無需外部服務或上傳數據。

🚀 快速開始

# 安裝（npm）
npm i -g docdex
# 或臨時使用
npx docdex --version

# 為倉庫或工作區創建完整索引
docdexd index --repo /path/to/repo

# 啟動 HTTP API 並即時監控文件變化（安全模式需要身份驗證令牌）
docdexd serve --repo /path/to/repo --host 127.0.0.1 --port 46137 --log info --auth-token <token>
# 若為本地使用且無需令牌，可添加 --secure-mode=false
# docdexd serve --repo /path/to/repo --host 127.0.0.1 --port 46137 --log info --secure-mode=false

# 通過 CLI 進行臨時搜索（JSON 格式輸出）
docdexd query --repo /path/to/repo --query "otp flow" --limit 5

✨ 主要特性

• 按倉庫本地索引：對 Markdown 或文本文件進行本地索引（基於 tantivy，無需網絡調用）。
• 統一索引接口：HTTP API（/search、/snippet、/healthz）和 CLI（query、ingest、self-check）共享同一索引。
• 即時文件監控：服務運行時即時監控文件變化，實現增量更新。
• 安全配置選項：支持 TLS（手動配置證書或使用 Certbot），默認需要身份驗證令牌（可通過 --secure-mode=false 禁用），默認僅允許本地迴環訪問，具備默認的速率限制、請求大小限制、嚴格的狀態目錄權限設置、審計日誌，支持 chroot/權限降級/網絡隔離（Unix）。
• 適配編碼輔助工具：輸出格式適用於編碼輔助工具，提供摘要、片段和文檔元數據。
• 對 AI 友好：GET /ai-help 返回一個 JSON 指南，包含端點、CLI 命令、限制和最佳實踐，方便智能代理使用。

📦 安裝指南

• 環境要求：需要 Node.js >= 18。
• 安裝命令：npm i -g docdex（或運行 npx docdex --version 進行驗證）。
• 命令說明：docdex（別名 docdexd）會從匹配的 GitHub 版本中下載適合你平臺的二進制文件。
• 支持平臺：macOS（arm64、x64）、Linux glibc（arm64、x64）、Linux musl（arm64、x64）、Windows（x64、arm64）；安裝程序會獲取匹配平臺的發佈資產。
• 自定義發佈：如果你從分叉倉庫發佈，安裝前設置 DOCDEX_DOWNLOAD_REPO=<owner/repo>，以便下載器獲取你的發佈資產。
• 分發方式：二進制文件存儲在 GitHub Releases 中（npm 包較小）；安裝後會根據 npm 版本獲取 docdexd-<platform>.tar.gz 文件。
• 發佈方式：使用 npm Trusted Publishing（OIDC），無需 NPM 令牌；具體配置見 .github/workflows/release.yml。

💻 使用示例

基礎用法

# 為倉庫創建索引
docdexd index --repo /path/to/repo

# 啟動 HTTP API 服務
docdexd serve --repo /path/to/repo --host 127.0.0.1 --port 46137 --log info --auth-token <token>

# 通過 CLI 進行搜索
docdexd query --repo /path/to/repo --query "otp flow" --limit 5

高級用法

# 使用 Certbot 配置 TLS
docdexd serve --repo <repo> --host 0.0.0.0 --port 46137 --certbot-domain docs.example.com

# 禁用安全模式（本地開發使用）
docdexd serve --repo /path/to/repo --host 127.0.0.1 --port 46137 --log info --secure-mode=false

📚 詳細文檔

功能概述

Docdex 對倉庫內的 Markdown 或文本文件進行索引並本地存儲（默認索引存儲在 <repo>/.docdex/index 目錄下，基於 tantivy）。通過 HTTP（/search、/snippet、/healthz）和 CLI（query、ingest、self-check）提供統一的索引訪問接口，方便自動化和交互式使用。服務運行時會即時監控文件變化，實現增量更新。同時，具備一系列安全配置選項，保障服務的安全性。

索引規則

• 支持的文件類型：.md、.markdown、.mdx、.txt（可通過擴展 DEFAULT_EXTENSIONS 添加更多類型）。
• 跳過的目錄：涵蓋多種生態系統中的 VCS、構建、緩存和供應商文件夾（如 .git、.hg、.svn、node_modules 等；完整列表見 DEFAULT_EXCLUDED_DIR_NAMES）。
• 跳過的相對前綴：logs/、.docdex/、.docdex/logs/ 等。
• 片段大小：摘要約 360 個字符（最多 4 段）；片段約 420 個字符。

HTTP API

• GET /healthz：返回 ok，此端點無需身份驗證和速率限制（IP 白名單仍然適用）。
• GET /search?q=<text>&limit=<n>&snippets=<bool>&max_tokens=<u64>：返回包含文檔 ID、相對路徑、摘要、片段、分數和令牌估計的搜索結果。設置 snippets=false 可僅返回摘要；設置 max_tokens 可過濾超出預算的結果。
• GET /snippet/:doc_id?window=<lines>&q=<query>&text_only=<bool>&max_tokens=<u64>：返回包含可選高亮片段的文檔信息。當查詢高亮為空時，返回預覽（默認窗口為 40 行）。設置 text_only=true 可僅返回文本片段；設置 max_tokens 可過濾超出預算的片段。
• GET /ai-help：返回一個 JSON 快速指南，包含端點、CLI 命令、限制和最佳實踐，供智能代理使用。
• GET /metrics：返回 Prometheus 格式的速率限制、身份驗證和錯誤指標計數器。

CLI 命令

• serve --repo <path> [--host 127.0.0.1] [--port 46137] [--log info]：啟動 HTTP API 服務並即時監控文件變化。
• index --repo <path>：重建整個索引。
• ingest --repo <path> --file docs/new.md：對單個文件進行重新索引。
• query --repo <path> --query "<text>" [--limit 8]：執行搜索並以 JSON 格式輸出結果。
• self-check --repo <path> --terms "foo,bar" [--limit 5]：在啟用訪問前掃描索引中的敏感詞彙。若發現敏感詞彙，退出碼不為 0，並報告示例結果和是否還有其他匹配項。默認包含內置的令牌/密碼模式，可通過 --include-default-patterns=false 禁用，僅使用提供的詞彙進行掃描。

配置選項

版本管理

• 語義化版本：使用帶標籤的版本（vX.Y.Z）。Rust 包和 npm 包使用相同的版本號。
• 發佈流程：通過 Conventional Commits 和 Release Please 生成發佈說明。它會打開發布 PR，更新 Cargo.toml 和 npm/package.json，更新變更日誌，並在合併時創建標籤和發佈版本。
• 集成建議：集成時固定到已發佈的版本（如在腳本或 Dockerfile 中），確保升級操作明確且可回滾。
• 從源代碼構建：版本號來自本倉庫的 Cargo.toml；npm 包裝器使用匹配的版本號下載二進制文件。

路徑和默認值

• 狀態/索引目錄：<repo>/.docdex/index（若該目錄不存在，但舊的 <repo>/.gpt-creator/docdex/index 存在，Docdex 會重用該索引併發出警告）。該目錄默認以 0700 權限創建。
• HTTP API 默認地址：服務啟動時默認監聽 127.0.0.1:46137。
• 數據和日誌存儲：Docdex 的數據和日誌存儲在倉庫內部，無需外部服務。

幫助和命令發現

• 列出所有命令和標誌：docdexd --help。
• 查看所有子命令的幫助信息：docdexd help-all。
• 查看 serve 命令的選項：docdexd serve --help。
• 查看索引選項：docdexd index --help。
• 查看臨時查詢選項：docdexd query --help。
• 查看自我檢查掃描選項：docdexd self-check --help。
• 獲取智能代理幫助信息：curl http://127.0.0.1:46137/ai-help（若設置了 --auth-token，需包含 Authorization: Bearer <token>），返回包含端點、限制和最佳實踐的 JSON 列表。
• MCP 幫助和註冊：docdexd mcp --help 列出 MCP 標誌；使用 docdexd mcp --repo <repo> --log warn 向客戶端註冊。示例 Codex 配置片段：

{
    "mcpServers": {
        "docdex": {
            "command": "docdexd",
            "args": ["mcp", "--repo", ".", "--log", "warn", "--max-results", "8"],
            "env": {}
        }
    }
}

• MCP 快速添加命令（適用於流行的智能代理）：
  • Docdex 助手：docdex mcp-add --repo /path/to/repo --log warn --max-results 8 自動檢測支持的智能代理；添加 --all 嘗試所有已知客戶端並打印僅支持 UI 操作的客戶端的手動步驟，或添加 --remove 進行卸載。
  • Codex CLI：codex mcp add docdex -- docdexd mcp --repo /path/to/repo --log warn --max-results 8。
  • 通用 JSON 配置（適用於 Cursor、Continue、Windsurf、Cline、Claude Desktop 開發工具）：將上述 mcpServers.docdex 塊添加到 MCP 配置文件中（路徑因客戶端而異；大多數客戶端接受所示的 command/args 模式）。
  • 手動/僅支持標準輸入輸出的客戶端：手動啟動 docdexd mcp --repo /path/to/repo --log warn --max-results 8，並將客戶端指向該命令或二進制文件。
• 暴露的工具：
  • docdex_search：參數 { "query": "<text>", "limit": <int optional>, "project_root": "<path optional>" }。返回 { "results": [...], "repo_root": "...", "state_dir": "...", "limit": <int>, "project_root": "...", "meta": {...} }。
  • docdex_index：參數 { "paths": ["relative/or/absolute"], "project_root": "<path optional>" }。空的 paths 表示重新索引所有文件；否則，僅索引列出的文件。
  • docdex_files：參數 { "limit": <int optional, default 200, max 1000>, "offset": <int optional, default 0>, "project_root": "<path optional>" }。返回 { "results": [{ "doc_id", "rel_path", "summary", "token_estimate" }], "total", "limit", "offset", "repo_root", "project_root" }。
  • docdex_open：參數 { "path": "<relative file>", "start_line": <int optional>, "end_line": <int optional>, "project_root": "<path optional>" }。返回 { "path", "start_line", "end_line", "total_lines", "content", "repo_root", "project_root" }（拒絕倉庫外的路徑和大文件）。
  • docdex_stats：參數 { "project_root": "<path optional>" }。返回 { "num_docs", "state_dir", "index_size_bytes", "segments", "avg_bytes_per_doc", "generated_at_epoch_ms", "last_updated_epoch_ms", "repo_root", "project_root" }。
• 示例調用：
  • 初始化：{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
  • 帶工作區根目錄的初始化：{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"workspace_root":"/path/to/repo"}}（必須與服務器倉庫匹配；為後續調用設置默認的項目根目錄）
  • 列出工具：{"jsonrpc":"2.0","id":2,"method":"tools/list"}
  • 重新索引：{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"docdex_index","arguments":{"paths":[]}}}
  • 搜索：{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"docdex_search","arguments":{"query":"payment auth flow","limit":3,"project_root":"/repo"}}}
  • 列出文件：{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"docdex_files","arguments":{"limit":10,"offset":0}}}
  • 打開文件：{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"docdex_open","arguments":{"path":"docs/readme.md","start_line":1,"end_line":20}}}
  • 統計信息：{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"docdex_stats","arguments":{}}}
• 錯誤處理：無效的 JSON → 代碼 -32700；不支持或缺失 jsonrpc → -32600；未知的工具或方法 → -32601；無效的參數（空查詢、錯誤的參數、項目根目錄不匹配） → -32602；內部錯誤在 error.data 中包含 reason 字符串。
• 智能代理使用指南：編碼前使用簡潔的查詢調用 docdex_search；僅獲取少量結果；若結果看起來過時，調用 docdex_index；若你的技術棧不支持 MCP，繼續使用 HTTP 或 CLI 接口。
• 幫助信息：docdexd mcp --help 顯示 MCP 標誌和默認值；docdexd help-all 包含一個 MCP 部分，列出工具和使用方法。

故障排除

• 索引過時：重新運行 docdexd index --repo <path>。
• 端口衝突：更改 --host/--port 參數。

安全考慮

• 綁定地址：默認綁定 127.0.0.1，除非你在可信的反向代理或防火牆後面，否則不要更改。避免在不可信的網絡上使用 --host 0.0.0.0。
• TLS 配置：默認情況下，非本地迴環綁定需要 TLS。僅當流量已在可信代理處終止時，可通過 --require-tls=false 或 --insecure 禁用。
• 外部暴露：若要將服務暴露到外部網絡，建議在前面放置一個反向代理，終止 TLS，並要求身份驗證（基本認證、OAuth 或 mTLS）以及 IP 或 VPN 白名單。示例（nginx）：

server {
    listen 443 ssl;
    server_name docdex.example.com;
    ssl_certificate /path/fullchain.pem;
    ssl_certificate_key /path/privkey.pem;
    auth_basic "Protected";
    auth_basic_user_file /etc/nginx/.htpasswd; # 或使用 OAuth/mTLS 替代
    allow 10.0.0.0/8;
    allow 192.168.0.0/16;
    deny all;
    location / {
        proxy_pass http://127.0.0.1:46137;
        proxy_set_header Host $host;
    }
}

• 語料庫清理：建議使用經過篩選的暫存目錄，或在索引前使用 --exclude-dir / --exclude-prefix 排除敏感或私有路徑。服務會監控 repo 目錄下的文件變化並進行增量更新。
• 日誌管理：若片段或路徑包含敏感信息，避免在生產環境中使用詳細日誌。反向代理的訪問日誌也可能記錄查詢詞和路徑。
• 最小權限原則：以低權限用戶或容器運行 Docdex，並確保狀態目錄具有受限的權限。
• 發佈前驗證：運行 docdexd query 檢查敏感關鍵詞，確保沒有匹配結果。若需要，將索引存儲在加密磁盤上。
• 可選的強化措施：在 HTTP API 或代理上要求身份驗證令牌；非本地主機時強制使用 TLS（默認），僅在可信代理後通過 --require-tls=false/--insecure 明確禁用；啟用速率限制（--rate-limit-per-min）並限制 limit/請求大小（--max-limit、--max-query-bytes、--max-request-bytes）；若嵌入片段，對 HTML 進行轉義或清理，或通過 --disable-snippet-text 完全禁用片段；狀態目錄默認以 0700 權限創建，建議由非特權用戶管理，可選擇使用 --run-as-uid/--run-as-gid、--chroot 或容器化；保持訪問日誌最小化/脫敏（--access-log），在暴露服務前運行 self-check 檢查敏感詞彙；為了靜態數據的保密性，將狀態目錄放置在加密存儲上或使用主機級磁盤加密。

與 LLM 工具集成

Docdex 與工具無關，以下是與智能代理或代碼生成工具集成的步驟：

• 啟動服務：每個倉庫運行一次 docdexd index --repo <repo>，然後運行 docdexd serve --repo <repo> --host 127.0.0.1 --port 46137 --log warn（或直接使用 CLI 而不啟動服務）。
• 環境配置：通過環境變量配置 DOCDEX_STATE_DIR（索引位置）、DOCDEX_EXCLUDE_PREFIXES、DOCDEX_EXCLUDE_DIRS、RUST_LOG=docdexd=debug（可選的詳細日誌）。
• HTTP 查詢：GET /search?q=<text>&limit=<n> 返回 {"hits":[{"doc_id","rel_path","score","summary","snippet","token_estimate"}...]}；GET /snippet/:doc_id 獲取聚焦的片段和文檔元數據。
• CLI 查詢：docdexd query --repo <repo> --query "<text>" --limit 8（JSON 輸出到標準輸出）。
• 健康檢查：在發出搜索請求前，GET /healthz 應返回 ok。
• 將片段注入提示：

"You are building features for this repo. Use the following documentation snippets for context. If a snippet cites a path, keep that path in your response. Snippets:\n<insert docdex snippets here>\nQuestion: <your question>"

MCP（可選的適用於支持 MCP 的客戶端的標準輸入輸出服務器）

Docdex 可以作為 MCP 工具提供者通過標準輸入輸出運行，但不會替代 HTTP 守護進程，你可以根據智能代理或編輯器的需求選擇合適的方式。若你的 MCP 客戶端支持資源模板，Docdex 會宣傳一個 docdex_file 模板（docdex://{path}），該模板委託給 docdex_open。

• 運行命令：docdexd mcp --repo /path/to/repo --log warn --max-results 8（別名：--mcp-max-results 8）。
• 環境變量覆蓋：DOCDEX_MCP_MAX_RESULTS 限制 docdex_search 的結果數量（最小值為 1）。
• 打包方式：MCP 服務器集成在主 docdexd 二進制文件中（通過 docdexd mcp 或 docdex mcp 從 npm 二進制文件調用），無需單獨下載 docdex-mcp。
• 向 MCP 客戶端註冊：添加一個名為 docdex 的服務器，運行 docdexd mcp --repo <repo> --log warn。示例 Codex 配置片段：

{
    "mcpServers": {
        "docdex": {
            "command": "docdexd",
            "args": ["mcp", "--repo", ".", "--log", "warn", "--max-results", "8"],
            "env": {}
        }
    }
}

• MCP 快速添加命令（適用於流行的智能代理）：
  • Docdex 助手：docdex mcp-add --repo /path/to/repo --log warn --max-results 8 自動檢測支持的智能代理；添加 --all 嘗試所有已知客戶端並打印僅支持 UI 操作的客戶端的手動步驟，或添加 --remove 進行卸載。
  • Codex CLI：codex mcp add docdex -- docdexd mcp --repo /path/to/repo --log warn --max-results 8。
  • 通用 JSON 配置（適用於 Cursor、Continue、Windsurf、Cline、Claude Desktop 開發工具）：將上述 mcpServers.docdex 塊添加到 MCP 配置文件中（路徑因客戶端而異；大多數客戶端接受所示的 command/args 模式）。
  • 手動/僅支持標準輸入輸出的客戶端：手動啟動 docdexd mcp --repo /path/to/repo --log warn --max-results 8，並將客戶端指向該命令或二進制文件。
• 暴露的工具：
  • docdex_search：參數 { "query": "<text>", "limit": <int optional>, "project_root": "<path optional>" }。返回 { "results": [...], "repo_root": "...", "state_dir": "...", "limit": <int>, "project_root": "...", "meta": {...} }。
  • docdex_index：參數 { "paths": ["relative/or/absolute"], "project_root": "<path optional>" }。空的 paths 表示重新索引所有文件；否則，僅索引列出的文件。
  • docdex_files：參數 { "limit": <int optional, default 200, max 1000>, "offset": <int optional, default 0>, "project_root": "<path optional>" }。返回 { "results": [{ "doc_id", "rel_path", "summary", "token_estimate" }], "total", "limit", "offset", "repo_root", "project_root" }。
  • docdex_open：參數 { "path": "<relative file>", "start_line": <int optional>, "end_line": <int optional>, "project_root": "<path optional>" }。返回 { "path", "start_line", "end_line", "total_lines", "content", "repo_root", "project_root" }（拒絕倉庫外的路徑和大文件）。
  • docdex_stats：參數 { "project_root": "<path optional>" }。返回 { "num_docs", "state_dir", "index_size_bytes", "segments", "avg_bytes_per_doc", "generated_at_epoch_ms", "last_updated_epoch_ms", "repo_root", "project_root" }。
• 示例調用：
  • 初始化：{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
  • 帶工作區根目錄的初始化：{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"workspace_root":"/path/to/repo"}}（必須與服務器倉庫匹配；為後續調用設置默認的項目根目錄）
  • 列出工具：{"jsonrpc":"2.0","id":2,"method":"tools/list"}
  • 重新索引：{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"docdex_index","arguments":{"paths":[]}}}
  • 搜索：{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"docdex_search","arguments":{"query":"payment auth flow","limit":3,"project_root":"/repo"}}}
  • 列出文件：{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"docdex_files","arguments":{"limit":10,"offset":0}}}
  • 打開文件：{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"docdex_open","arguments":{"path":"docs/readme.md","start_line":1,"end_line":20}}}
  • 統計信息：{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"docdex_stats","arguments":{}}}
• 錯誤處理：無效的 JSON → 代碼 -32700；不支持或缺失 jsonrpc → -32600；未知的工具或方法 → -32601；無效的參數（空查詢、錯誤的參數、項目根目錄不匹配） → -32602；內部錯誤在 error.data 中包含 reason 字符串。
• 智能代理使用指南：編碼前使用簡潔的查詢調用 docdex_search；僅獲取少量結果；若結果看起來過時，調用 docdex_index；若你的技術棧不支持 MCP，繼續使用 HTTP 或 CLI 接口。
• 幫助信息：docdexd mcp --help 顯示 MCP 標誌和默認值；docdexd help-all 包含一個 MCP 部分，列出工具和使用方法。

HTTPS 和 Certbot

• TLS 支持：支持 PKCS8、PKCS1/RSA 和 SEC1/EC 私鑰（與 Certbot 輸出兼容）。
• 手動配置證書：docdexd serve --repo <repo> --tls-cert /path/fullchain.pem --tls-key /path/privkey.pem。
• 使用 Certbot 助手：docdexd serve --repo <repo> --host 0.0.0.0 --port 46137 --certbot-domain docs.example.com（使用 /etc/letsencrypt/live/docs.example.com/{fullchain.pem,privkey.pem}），或通過 --certbot-live-dir /custom/live/dir 指定自定義活動目錄。
• 證書更新：使用 Certbot 時，設置部署鉤子，在證書更新後重啟或重新加載 Docdex（例如，certbot renew --deploy-hook "systemctl restart docdexd.service" 或向進程管理器發送 -HUP 信號）。
• 端口綁定：若直接綁定到 443 端口，需要相應的權限；否則，將 Docdex 綁定到 127.0.0.1，由反向代理終止 TLS。