docs-search

零依赖的本地文档搜索引擎。纯 Python 标准库，SQLite 索引，毫秒级检索。

A zero-dependency local document search engine. Pure Python stdlib, SQLite index, millisecond-level retrieval.

特性 / Features

• 零依赖 — 纯 Python 标准库（3.10+），无需 pip install
• 快 — SQLite FTS 索引，检索 < 50ms
• 自动索引 — 搜索前自动检测文件变更并增量重建
• AI Agent 对接 — 内置 MCP stdio server（Cursor / ZCode / Qoder / DSH 等即插即用）+ pi 扩展；支持本地模式与远程模式（--url 连已运行的服务，可配 Bearer/Basic 认证）
• 远端部署 — docs-search-web --host 0.0.0.0 --token <T> 独立启动为远端服务（非回环监听强制认证）；后端与 agent 可分离部署
• Web UI — 内置搜索界面 + 拖拽上传 .md 文档
• 多库隔离 — 不同文档目录各自独立索引，可并存；每次操作可带 workspace 动态切自包含库（MCP/API/CLI 一致）
• 上传安全 — 同名默认提示冲突，可强制覆盖或自动 -N 新文件；.md only、≤10MB、消毒
• 不绑定路径 — 文档目录由参数/环境变量指定，不写死任何本地路径
• 跨平台 — Windows / macOS / Linux

📖 文档站 / Documentation

https://ninjasln-labs.github.io/docs-search/

• 人类使用手册（安装 / CLI / Web / FAQ）
• Agent 接入指南（MCP server + Cursor / ZCode / Qoder / DSH / pi 配置）
• Agent 操作手册 + AGENT-INDEX.json（机器可读索引）
• Web API 参考（调用方）
• 兼容服务端契约（自定义服务实现方规范 + 验收自检）

快速开始 / Quick Start

# 1. 索引一个文档目录（默认 ./docs，也可用 --dir 指定）
python scripts/docs-search.py index --dir /path/to/your/docs

# 2. 搜索
python scripts/docs-search.py search "关键词" --dir /path/to/your/docs

# 3. 启动 Web UI（含上传接口）
python scripts/docs-search-web.py /path/to/your/docs
# 访问 http://127.0.0.1:8765

路径解析规则

索引库按文档目录哈希隔离——多个文档目录可以各自拥有独立索引，互不干扰。

CLI

python scripts/docs-search.py index    [--dir DIR]   # 重建索引
python scripts/docs-search.py search "关键词" [--dir DIR] [-n 8]  # 多关键词 AND 搜索
python scripts/docs-search.py list     [--dir DIR]   # 列出所有文档
python scripts/docs-search.py show <path> [--dir DIR] # 显示文档内容
python scripts/docs-search.py status   [--dir DIR]   # 查看索引状态
python scripts/docs-search.py upload <file.md> [--dir DIR]  # 复制 .md 到文档库 uploads/ 并重建索引
python scripts/docs-search.py open <path> [--dir DIR]  # 用系统默认程序打开

Windows 下可用 scripts/docs-search.bat。

Web API

启动：python scripts/docs-search-web.py [DIR] [--port 8765] [--host 127.0.0.1] [--no-browser]

上传示例：

curl -X POST "http://127.0.0.1:8765/api/upload?filename=notes.md" \
     --data-binary @notes.md

上传的文件存入 <文档目录>/uploads/ 并自动进入索引；同名默认返回重名提示（不写不覆盖），可 if_exists=overwrite 覆盖或 if_exists=keep 生成 -1/-2 新文件；每次操作可带 workspace 切到独立自包含库（不填 = 默认库）。

AI Agent 接入（MCP）

内置零依赖 MCP stdio server，让 AI agent 直接检索/写入文档库：

# Cursor（~/.cursor/mcp.json）
{ "mcpServers": { "docs-search": { "command": "docs-search-mcp", "args": ["--dir", "/path/to/docs"] } } }

# Qoder CLI（-s user 全局；中国版额度在 qodercn，与国际版账号不通用）
qodercn mcp add -s user docs-search -- docs-search-mcp --dir /path/to/docs

暴露 5 个工具：docs_search / docs_read / docs_write / docs_delete / docs_info。 ZCode（Settings → MCP Servers）、DSH（@deepseek-ai/dsh-mcp-client 插件行）配置及 pi 扩展安装， 见 Agent 接入指南。

已有 docs-search 服务在运行时（本机或其他机器，接口与 /api/* 相同），MCP 可直接连它、不读本地目录：

# Cursor（远程模式——服务已启动/异机共享时用；远端启用认证时带 --token/--user/--password）
{ "mcpServers": { "docs-search": { "command": "docs-search-mcp", "args": ["--url", "http://192.168.1.10:8765", "--token", "<TOKEN>"] } } }
# 或环境变量: DOCS_SEARCH_URL=http://192.168.1.10:8765 docs-search-mcp
# 连接代理: 默认跟随环境代理;干扰时 --proxy direct 直连,或 --proxy http://代理:端口 指定(DOCS_SEARCH_PROXY)

# 后端独立启动为远端服务（非回环监听强制要求认证）
docs-search-web /path/to/docs --host 0.0.0.0 --token <TOKEN>

安全说明 / Security

• 服务默认仅监听 127.0.0.1；监听非回环地址（如 --host 0.0.0.0）必须启用认证（--token Bearer 或 --user/--password Basic），否则拒绝启动
• 上传仅接受 .md 文件、单文件 ≤ 10MB、文件名经过消毒（防路径穿越）
• 删除接口仅允许操作 uploads/ 目录内的文件

开发 / Development

pip install -r requirements.lock -e .   # 可编辑安装 + 锁定的开发工具链
python scripts/verify.py        # 验证链单源：ruff + pytest（单元 + CLI E2E + Web API）
ruff check src/ tests/ scripts/  # lint
git config core.hooksPath .githooks  # 启用 pre-commit 验证链

工程结构见 DEVELOPMENT.md，贡献规范见 CONTRIBUTING.md，AI 协作纪律见 AGENTS.md。English docs: README.en.md

许可证 / License

MIT — 见 LICENSE