neogado 0.1.0

AI 驱动的小说规则生成与智能自愈引擎，自带沉浸式终端阅读器 (TUI)

NeoGado - AI驱动小说阅读器

NeoGado 是一个由 AI 驱动的沉浸式小说阅读器与智能规则生成引擎，是 Legado（阅读）的智能替代方案。无需手动配置书源，只需输入小说网站URL，AI自动生成解析规则，实现全站点小说阅读。

✨ 核心特性

🚀 零配置使用

• 智能识别：输入任意小说网站URL，AI自动识别页面类型（首页、列表、详情、目录、正文）
• 自动破盾：内置Playwright无头浏览器，自动绕过Cloudflare等反爬机制
• 规则自动生成：AI自动分析DOM结构，生成CSS选择器提取规则，兼容Legado格式

登录支持

• 按下 Ctrl+L 一键打开浏览器手动登录
• 支持所有登录方式（账号密码、验证码、扫码等）
• 登录状态永久保存，后续访问自动复用

⚡ 一点点缓存

• 多级缓存机制：页面分类、书籍详情、目录、章节全链路缓存
• URL模式学习：自动识别网站URL结构，相同模式无需重复调用AI
• 浏览器实例复用：Playwright浏览器全局复用，大幅提升连续访问速度

🚀 快速开始

1. 环境要求

• Python 3.10+
• 兼容 OpenAI 格式的 API Key（推荐使用 DeepSeek 或 GPT-4o-mini）

2. 安装

# 克隆仓库
git clone https://github.com/your-repo/neogado.git
cd neogado

# 安装依赖（推荐使用uv）
uv pip install -e .
# 或使用pip
pip install -e .

# 安装Playwright浏览器内核
playwright install chromium

3. 配置

在用户主目录下创建 .neogado 文件夹，并新建 .env 文件：

mkdir ~/.neogado
touch ~/.neogado/.env

编辑 .env 文件：

OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"
OPENAI_API_BASE="https://api.deepseek.com/v1"
OPENAI_MODEL_NAME="deepseek-chat"

4. 启动阅读器

neogado --tui

⌨️ 快捷键说明

全局快捷键

快捷键	功能说明
Ctrl + Q	退出程序
Ctrl + L	登录当前网站

阅读器快捷键

快捷键	功能说明
Esc	返回上一页
R	强制刷新（忽略缓存重新解析）
D	下载全本到本地缓存
T / Ctrl + B	显示/隐藏目录侧边栏
N / ]	下一章
P / [	上一章
J	向下滚动
K	向上滚动

其他页面

• 在列表页面按回车选中条目
• 在输入框按回车提交

📖 使用指南

1. 基础使用

1. 启动后在首页输入框粘贴任意小说网站的URL（首页、列表页、详情页、目录页、正文页均可）
2. 按下回车，系统会自动：
   • 抓取页面内容
   • AI识别页面类型
   • 生成对应的解析规则
   • 展示对应的内容（书籍列表、详情、目录、正文）

2. 登录需要验证的网站

1. 导航到需要登录的网站
2. 按下 Ctrl + L，系统会自动打开Chrome浏览器
3. 在浏览器中完成登录操作
4. 关闭浏览器，登录状态会自动保存
5. 后续访问该网站将自动使用登录状态

3. 搜索功能

1. 在书城页面的搜索框输入关键词
2. 按下回车或点击搜索按钮
3. AI自动模拟搜索操作并展示结果

4. 强制刷新

如果遇到解析错误或内容过时，按下 R 键会：

• 忽略本地缓存
• 重新抓取页面
• 重新调用AI生成最新规则

🏗️ 技术架构

核心工作流

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Fetch 抓取    │ →  │  Distill 精简   │ →  │  Extract 提取   │
│  (渐进式抓取)   │    │  (HTML净化)     │    │  (AI生成规则)   │
└─────────────────┘    └─────────────────┘    └─────────────────┘
        ↓                       ↓                       ↓
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  Validate 验证  │ ←  │   Classify 分类 │ ←  │    Cache 缓存   │
│  (规则有效性)   │    │  (页面类型识别)  │    │  (多级缓存)     │
└─────────────────┘    └─────────────────┘    └─────────────────┘

技术栈

• 终端UI：Textual
• 浏览器引擎：Playwright + stealth
• AI解析：大语言模型（OpenAI API兼容）
• 数据存储：SQLite缓存 + JSON规则文件
• HTML处理：BeautifulSoup4

项目结构

neogado/
├── src/
│   ├── tui.py              # 终端界面实现
│   ├── scraper.py          # 页面抓取模块（Playwright封装）
│   ├── distiller.py        # HTML精简净化模块
│   ├── llm_parser.py       # AI解析和规则生成
│   ├── extractor.py        # 规则提取执行模块
│   ├── rule_generator.py   # 规则生成与管理
│   ├── storage.py          # 缓存和存储管理
│   ├── models.py           # 数据模型定义
│   └── validator.py        # 规则验证模块
├── tests/                  # 测试用例
└── README.md               # 项目说明

🛠️ 开发指南

安装开发依赖

uv add --dev pytest ruff

代码检查与格式化

# 代码检查
uv run ruff check --fix .

# 代码格式化
uv run ruff format .

运行测试

uv run pytest tests/

📝 文件存储位置

所有数据都保存在用户主目录的 .neogado 文件夹下：

~/.neogado/
├── .env                # 配置文件
├── neogado.log         # 运行日志
├── cache.db            # SQLite缓存数据库（目录、章节、书籍详情）
├── rules/              # 各网站的解析规则文件（JSON格式）
└── cookies.json        # 登录状态存储

🤝 贡献

欢迎提交Issue和Pull Request！

📄 许可证

MIT License