Metadata-Version: 2.4
Name: docs-search
Version: 1.0.0
Summary: Zero-dependency local document search engine — SQLite index, millisecond retrieval, CLI + Web UI with upload
Author: ninjasin-labs
License: MIT License
        
        Copyright (c) 2026 ninjasin-labs
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/ninjasln-labs/docs-search
Project-URL: Repository, https://github.com/ninjasln-labs/docs-search
Project-URL: Issues, https://github.com/ninjasln-labs/docs-search/issues
Keywords: search,sqlite,markdown,docs,cli
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: ruff>=0.6; extra == "test"
Dynamic: license-file

# 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

```bash
# 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

```bash
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/` 下已上传文档 |

上传示例：

```bash
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

```bash
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](DEVELOPMENT.md)，贡献规范见 [CONTRIBUTING.md](CONTRIBUTING.md)，AI 协作纪律见 [AGENTS.md](AGENTS.md)。English docs: [README.en.md](README.en.md)

## 许可证 / License

MIT — 见 [LICENSE](LICENSE)
