零依赖的本地文档搜索引擎。纯 Python 标准库，SQLite 索引，毫秒级检索。
A zero-dependency local document search engine. Pure Python stdlib, SQLite index, millisecond-level retrieval.
- 零依赖 — 纯 Python 标准库（3.10+），无需 pip install
- 快 — SQLite FTS 索引，检索 < 50ms
- 自动索引 — 搜索前自动检测文件变更并增量重建
- AI Agent 对接 — 内置 MCP stdio server（Cursor / ZCode / Qoder / DSH / Cline / OpenCode / Reasonix / Command Code / MiniMax Code / pi 等即插即用）；支持本地模式与远程模式（
--url连已运行的服务，可配 Bearer/Basic 认证）；docs-search-install一键写入各家 agent 配置 - 远端部署 —
docs-search-web --host 0.0.0.0 --token <T>独立启动为远端服务（非回环监听强制认证）；后端与 agent 可分离部署 - Web UI — 内置搜索界面 + 拖拽上传 .md 文档
- 多库隔离 — 不同文档目录各自独立索引，可并存；每次操作可带
workspace动态切自包含库（MCP/API/CLI 一致） - 上传安全 — 同名默认提示冲突，可强制覆盖或自动
-N新文件；.mdonly、≤10MB、消毒 - 不绑定路径 — 文档目录由参数/环境变量指定，不写死任何本地路径
- 跨平台 — Windows / macOS / Linux
https://ninjasln-labs.github.io/docs-search/
- 人类使用手册（安装 / CLI / Web / FAQ）
- Agent 接入指南（MCP server + Cursor / ZCode / Qoder / DSH / Cline / OpenCode / Reasonix / Command Code / MiniMax Code / pi 配置）
- Agent 操作手册 + AGENT-INDEX.json（机器可读索引）
- Web API 参考（调用方）
- 兼容服务端契约（自定义服务实现方规范 + 验收自检）
# 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 |
索引库按文档目录哈希隔离——多个文档目录可以各自拥有独立索引，互不干扰。
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。
启动：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/ 并自动进入索引；同名默认返回重名提示（不写不覆盖），可 if_exists=overwrite 覆盖或 if_exists=keep 生成 -1/-2 新文件；每次操作可带 workspace 切到独立自包含库（不填 = 默认库）。
内置零依赖 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。
搜索结果为 agent 友好格式：命中点摘要（关键词【】标注）+ 行号 + 确定性排序（标题命中优先、路径升序）+ 总数/截断提示：
"部署" -> 3 matches (showing 3)
1. ops/deploy.md | 部署指南 (line 4)
…执行【部署】脚本前先跑测试…
远程模式需服务端 ≥1.5.0 才有 total/服务端截断；旧服务端自动降级（客户端切片、无总数、无标注）。
ZCode（Settings → MCP Servers）、DSH（@deepseek-ai/dsh-mcp-client 插件行）、Cline（~/.cline/data/settings/cline_mcp_settings.json）、
OpenCode（mcp.servers）、Reasonix（reasonix mcp add）、Command Code（commandcode mcp add）、
MiniMax Code（~/.minimax/mcp.json）、pi（pi mcp add）配置，
见 Agent 接入指南。
不想逐家手改配置？docs-search-install 自动检测已安装的 agent 并写入（幂等，覆盖前备份 .bak）：
docs-search-install --dir ./docs # 本地模式（全部检测到的 agent）
docs-search-install --url https://docs.example.com --agents pi,cursor,opencode # 远程模式 + 子集
docs-search-install --dir ./docs --mcp-arg proxy=direct --dry-run # 附加 mcp 参数 + 预览不写入完整参数/支持矩阵/排错见 docs/INSTALL.md。
已有 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>- 服务默认仅监听
127.0.0.1；监听非回环地址（如--host 0.0.0.0）必须启用认证（--tokenBearer 或--user/--passwordBasic），否则拒绝启动 - 上传仅接受
.md文件、单文件 ≤ 10MB、文件名经过消毒（防路径穿越） - 删除接口仅允许操作
uploads/目录内的文件
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
MIT — 见 LICENSE