TXT Library

TXT Library 是一个使用 Python 标准库实现的本地 TXT 文库浏览、全文检索和阅读工具。它直接索引现有目录，不移动、不重命名、也不改写原始 TXT 文件。

主要功能：

保留多级目录结构，点击目录即可浏览其中及其子目录的文件；
对标题、相对路径和正文建立 SQLite FTS5 全文索引；
显示文件字数、大小和可解析的发布时间；
按名称自然排序、发布时间、字数或文件大小排序；
列表滚动到底部时自动加载更多文件；
点击结果直接阅读完整 TXT；
可选加载独立的自动标签数据库，显示内容分级和属性标签；
支持按分级、单个或多个标签筛选；
桌面端目录栏和文件列表独立滚动，切换目录后结果自动回到顶部；
移动端使用适配后的目录区和阅读界面。

隐私与生成文件

仓库不包含任何小说正文、全文索引、标签结果、日志或运行状态文件。以下内容已通过 .gitignore 排除：

*.txt
*.sqlite
*.sqlite3
*.db
*.log
*.pid
.env*
__pycache__/

索引数据库和标签数据库都在首次运行后由用户本地生成。不要把自己的 TXT 文库、数据库、WebDAV 凭据或模型服务凭据提交到 Git。

环境要求

Python 3.10 或更高版本；
Python 自带的 SQLite 需要支持 FTS5；
不需要 pip install；
自动标签功能可选，需要另外安装并运行 Ollama，同时准备兼容模型。

如果 SQLite 不支持 trigram tokenizer，程序会自动回退到 unicode61。中文短关键词仍可搜索，但性能会有所不同。

Windows 快速开始

git clone https://github.com/Cyrker/TXT-Library.git
cd TXT-Library

# 建立全文索引；把目录替换成自己的 TXT 文库路径
python .\txt_library.py index `
  --root "D:\Books\TXT" `
  --db ".\txt-library.sqlite3"

# 仅允许本机访问
python .\txt_library.py serve `
  --root "D:\Books\TXT" `
  --db ".\txt-library.sqlite3" `
  --host 127.0.0.1 `
  --port 8765

浏览器打开：

http://127.0.0.1:8765

也可以使用 PowerShell 启动脚本。索引不存在时，启动脚本会先自动建立索引：

.\start_txt_library.ps1 -Root "D:\Books\TXT"

只重新建立索引：

.\index_txt_library.ps1 -Root "D:\Books\TXT"

如需让同一可信局域网中的手机或其他电脑访问：

.\start_txt_library.ps1 `
  -Root "D:\Books\TXT" `
  -HostAddress "0.0.0.0" `
  -Port 8765

然后访问 http://<电脑局域网IP>:8765。如果 Windows 防火墙询问，只为可信的家庭或局域网放行。

Debian / Linux 快速开始

git clone https://github.com/Cyrker/TXT-Library.git
cd TXT-Library
chmod +x index.sh start.sh stop.sh status.sh

# 建立索引
TXT_ROOT=/srv/txt-library-data ./index.sh

# 默认只监听 127.0.0.1:8765
TXT_ROOT=/srv/txt-library-data ./start.sh

# 查看状态
./status.sh

# 停止服务
./stop.sh

允许可信局域网访问：

TXT_ROOT=/srv/txt-library-data TXT_HOST=0.0.0.0 TXT_PORT=8765 ./start.sh

生命周期脚本支持以下环境变量：

变量	用途	默认值
`TXT_ROOT`	TXT 文库根目录	必填
`TXT_DB`	全文索引数据库	`./txt-library.sqlite3`
`TXT_TAGS_DB`	可选标签数据库	`./auto-tags.sqlite3`
`TXT_HOST`	HTTP 监听地址	`127.0.0.1`
`TXT_PORT`	HTTP 端口	`8765`
`TXT_PID_FILE`	PID 文件	`./txt-library.pid`
`TXT_LOG_FILE`	日志文件	`./txt-library.log`
`TXT_PYTHON`	Python 命令	`python3`

更新全文索引

新增、删除或修改 TXT 后，需要重新建立索引。索引过程只读取 TXT，生成新的 SQLite 数据库后原子替换旧索引，不会修改文库内容。

Windows：

python .\txt_library.py index `
  --root "D:\Books\TXT" `
  --db ".\txt-library.sqlite3"

Debian / Linux：

./stop.sh
TXT_ROOT=/srv/txt-library-data ./index.sh
TXT_ROOT=/srv/txt-library-data ./start.sh

索引记录了源目录的绝对路径。同一个索引数据库不能直接在 Windows 和 Linux 之间复用；更换机器或挂载点后需要在目标机器重新建立索引。

搜索行为

输入 3 个字或以上时，优先使用 SQLite FTS5 trigram 索引；
输入 1～2 个字时会逐文件扫描索引内容，结果正确但速度较慢；
搜索范围可以限制在当前选中的目录；
搜索结果包含标题、完整相对路径和正文上下文；
同名文件通过相对路径区分。

可选自动标签

classify_tags.py 可以调用本机 Ollama，对 TXT 生成独立的 auto-tags.sqlite3。分级、标签及其说明统一定义在 tag-taxonomy.json 中，README 不展开具体内容；需要了解或调整标签体系时，请直接查看该文件。

先确认 Ollama 正在运行并且目标模型已存在：

ollama list

运行一个 300 篇的平衡抽样实验：

python .\classify_tags.py `
  --root "D:\Books\TXT" `
  --include "." `
  --taxonomy ".\tag-taxonomy.json" `
  --output ".\auto-tags.sqlite3" `
  --model "sakura-14b-qwen2.5:iq4xs" `
  --limit 300 `
  --sample-mode balanced `
  --workers 2 `
  --max-chars 1500 `
  --num-ctx 8192

处理全部文件：

.\classify_txt_library.ps1 `
  -Root "D:\Books\TXT" `
  -Include "." `
  -Limit 0 `
  -SampleMode all

分类结果逐篇提交。相对路径、内容 SHA-256、模型名称和标签体系版本未变化时，重新运行会自动跳过已有结果，因此任务可以中断后继续。不要添加 --force，除非确实需要重新分类全部文件。

分类器使用全文规则和模型结果合并判断，但模型结果仍可能出错。低置信度和标记为“需复核”的内容应由人工检查。当前网页只读展示标签，尚不包含人工审核写入界面。

标签数据库与全文索引数据库相互独立。只要 auto-tags.sqlite3 位于索引数据库旁边，或启动时通过 --tags-db / TXT_TAGS_DB 指定，网页就会加载标签。

WebDAV、SMB 和网络目录

程序索引的是操作系统能够直接访问的目录，不直接爬取 WebDAV URL。可以先把 WebDAV、SMB 或其他网络存储挂载到本地目录，再把挂载点作为 --root 或 TXT_ROOT。

不要直接在 WebDAV、SMB 或 SSHFS 上写 SQLite 数据库。索引和标签数据库应保存在本机磁盘；分类或索引完成后，再把关闭状态下的数据库作为完整文件同步到目标机器。

HTTP API

服务提供以下只读接口：

路径	用途
`/api/health`	索引、文档数量和标签库状态
`/api/tree`	目录树
`/api/files`	分页浏览目录文件
`/api/search`	全文搜索
`/api/file`	读取指定 TXT 正文
`/api/tags`	标签目录和统计

安全说明

当前 HTTP 服务没有账号、登录或权限控制。默认监听 127.0.0.1，只建议在本机或可信局域网使用。不要把 8765 端口直接暴露到公网；需要远程访问时，应在前面配置带认证的反向代理或使用 VPN。

测试

python -m unittest -v test_tags.py
python -m py_compile txt_library.py classify_tags.py test_tags.py

Cyrker/TXT-Library

README