Metadata-Version: 2.4
Name: neogado
Version: 0.1.0
Summary: AI 驱动的小说规则生成与智能自愈引擎，自带沉浸式终端阅读器 (TUI)
Author: angleyanalbedo
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4>=4.14.3
Requires-Dist: chardet>=7.4.0.post2
Requires-Dist: httpx>=0.28.1
Requires-Dist: openai>=2.30.0
Requires-Dist: playwright-stealth>=2.0.2
Requires-Dist: playwright>=1.58.0
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: textual>=8.2.2
Description-Content-Type: text/markdown

# 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. 安装
```bash
# 克隆仓库
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` 文件：
```bash
mkdir ~/.neogado
touch ~/.neogado/.env
```

编辑 `.env` 文件：
```env
OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"
OPENAI_API_BASE="https://api.deepseek.com/v1"
OPENAI_MODEL_NAME="deepseek-chat"
```

### 4. 启动阅读器
```bash
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               # 项目说明
```

## 🛠️ 开发指南

### 安装开发依赖
```bash
uv add --dev pytest ruff
```

### 代码检查与格式化
```bash
# 代码检查
uv run ruff check --fix .

# 代码格式化
uv run ruff format .
```

### 运行测试
```bash
uv run pytest tests/
```

## 📝 文件存储位置
所有数据都保存在用户主目录的 `.neogado` 文件夹下：
```
~/.neogado/
├── .env                # 配置文件
├── neogado.log         # 运行日志
├── cache.db            # SQLite缓存数据库（目录、章节、书籍详情）
├── rules/              # 各网站的解析规则文件（JSON格式）
└── cookies.json        # 登录状态存储
```

## 🤝 贡献
欢迎提交Issue和Pull Request！

## 📄 许可证
MIT License
