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
  • 自动索引 — 搜索前自动检测文件变更并增量重建
  • Web UI — 内置搜索界面 + 拖拽上传 .md 文档
  • 多库隔离 — 不同文档目录各自独立索引，可并存
  • 不绑定路径 — 文档目录由参数/环境变量指定，不写死任何本地路径
  • 跨平台 — Windows / macOS / Linux

快速开始 / 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

路径解析规则

目标 优先级
文档目录 --dir 参数 > 环境变量 DOCS_SEARCH_DIR > ./docs
索引库 --db 参数（CLI）> 环境变量 DOCS_SEARCH_DB > ~/.docs-search/<目录哈希>/index.db

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

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]

方法 端点 说明
GET /api/stats 统计信息 {count, updated, categories}
GET /api/search?q=关键词&cat= 搜索（多关键词 AND）
GET /api/list?cat= 列出文档
GET /api/show?path=x.md 文档内容
POST /api/upload?filename=x.md 上传文档（raw body = UTF-8 文本）
POST /api/delete?path=uploads/x.md 删除 uploads/ 下已上传文档

上传示例：

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

上传的文件存入 <文档目录>/uploads/ 并自动进入索引；同名自动加 -1、-2 后缀。

安全说明 / Security

  • 服务默认仅监听 127.0.0.1，请勿用 --host 0.0.0.0 暴露到公网（接口无鉴权）
  • 上传仅接受 .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

Project links

Data verified by PyPI on Sep 6, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for NinjaSin from gravatar.com NinjaSin

Credits

Author: ninjasin-labs

GitHub Statistics

Data verified by PyPI on Sep 6, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT License)

Requires

Python >=3.10

Provides Extra

test

Tags

search sqlite markdown docs cli

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

docs_search-1.0.0.tar.gz (22.1 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

docs_search-1.0.0-py3-none-any.whl (18.5 kB view details)

Uploaded Python 3

File details

Details for the file docs_search-1.0.0.tar.gz.

File metadata

  • Download URL: docs_search-1.0.0.tar.gz
  • Upload date:
  • Size: 22.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for docs_search-1.0.0.tar.gz
Algorithm Hash digest
SHA256 30f0978136249d21128db401c8bde8bee4968d38bda4c5990f95d8a738d85943
MD5 ecddcdf2d1c4759f066122055c053ba1
BLAKE2b-256 bff7b4b5d822beaf9a4023d4dfabd249a93b716991b78233fbffdc8aa3976d3e

See more details on using hashes here.

Provenance

The following attestation bundles were made for docs_search-1.0.0.tar.gz:

Publisher: publish.yml on NinjaSln-labs/docs-search

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file docs_search-1.0.0-py3-none-any.whl.

File metadata

  • Download URL: docs_search-1.0.0-py3-none-any.whl
  • Upload date:
  • Size: 18.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for docs_search-1.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 44436fe64f0b8b807d68104e021d094f5851ca3ecc5e8ee4bc00a8b82c8e8ef2
MD5 9c146d9b218a487593d1d88717c32441
BLAKE2b-256 76196a7c7085d7c6ca3bc3b0a4c7ee01aeac87290a5d4c34d405d95627787c59

See more details on using hashes here.

Provenance

The following attestation bundles were made for docs_search-1.0.0-py3-none-any.whl:

Publisher: publish.yml on NinjaSln-labs/docs-search

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page