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。