# 📚 Ecliptic Pathfinder — 个人图书阅读管理

轻量级命令行图书管理工具，零依赖，纯 Python 标准库。

## 快速开始

```bash
# 1. 常规添加书目
python bookshelf.py add "深度工作" --author "卡尔·纽波特" --format paper --status reading --tags "效率,自我管理"

# 2. (进阶) 使用 JSON 强力查重直插所有包含高阶属性的元数据：
python bookshelf.py add "乔布斯传" --json '{"title_en": "Steve Jobs", "author": "Walter Isaacson", "douban_score": 8.9}'

# 列出所有书
python bookshelf.py list

# 按状态/格式/标签筛选
python bookshelf.py list --status reading
python bookshelf.py list --format ebook
python bookshelf.py list --tag "哲学"

# 更新书目
python bookshelf.py update 1 --status read --rating 5 --finish-date 2026-03-25

# 删除书目
python bookshelf.py delete 1

# 生成展示网页
python bookshelf.py build
# 然后用浏览器打开 output/index.html
```
## 批量管理命令

```bash
# 1. 从豆瓣、Goodreads、Google Books 刮削验证并自动补充缺失元数据
python bookshelf.py enrich
# 单独补充某本书：python bookshelf.py enrich --id 12

# 2. 批量将图书封面下载并作为二进制 BLOB 存入 SQLite (解决静态展示防盗链问题)
python bookshelf.py covers
```

## 完整字段

| 参数 | 说明 | 示例 |
|------|------|------|
| `title` (必填) | 书名 | `"深度工作"` |
| `--author` / `--translator` | 作者 / 译者 | `"卡尔·纽波特"` / `"宋伟"` |
| `--publisher` / `--pub-date` | 出版社 / 出版年月 | `"后浪出版"` / `"2017-09"` |
| `--cover-url` | 封面 URL | `"https://..."` |
| `--format` | 格式：`paper` / `ebook` | `paper` |
| `--status` | `to-read` / `reading` / `read` | `reading` |
| `--rating` | 个人评分 1-5 | `5` |
| `--douban-score` / `--goodreads-score` | 豆瓣 / GR 评分 | `7.9` / `4.18` |
| `--douban-url` / `--goodreads-url` | 豆瓣 / GR 链接 | `https://book.douban...` |
| `--title-en` / `--author-en` | 外文书名 / 外文作者 | `Deep Work` / `Cal Newport` |
| `--tags` | 逗号分隔标签 | `"哲学,认知科学"` |
| `--notes` | 简评 | `"值得反复阅读"` |
| `--start-date` / `--finish-date` | 阅读起止日期 | `"2026-03-01"` / `"2026-03-20"` |
| `--group` (db 级别) | 主题领域分组（如"历史学"） | |
| `--priority` (db 级别)| 阅读优先级 | `⭐⭐⭐` |

## 数据存储与静态构建

- 数据库：`books.db`（SQLite，包含 `cover_blob`）
- 静态构建：`python bookshelf.py build` (会自动抽取数据库中 `cover_blob` 至 `output/covers/` 以供显示，网页输出至 `output/index.html`)

## 🤖 AI Agent 交互提示
若你是被指派操作此书库的 AI Agent：
1. **一步到位入库（终极建档）**：若在对话中已经搜索获取到该书丰富的元数据（封面URL、精确书名、外文名、评分等），**切勿**分成“简略 add -> 再 enrich”两步走。请直接使用带自带查重保护的 `add` 结合 `--json` 一键全属性入库。
   - 例：`python bookshelf.py add "史蒂夫·乔布斯传" --json '{"author": "Walter Isaacson", "title_en": "Steve Jobs", "douban_score": 8.9, "cover_url": "..."}'`
2. **多语言支持**：如果判断是一本翻译书，务必在爬取或手工录入时尝试保留由 `enrich` 抓取到的 `title_en` 以及 `goodreads_url`, 不要随意覆盖中文 `title` 字段。
3. **流程必做**：用户添加书目指令执行完 `add` 或 `enrich` 后，必须执行 `bookshelf.py covers` 以及 `bookshelf.py build`，以保持静态页面的同步。
4. **人工纠错**：如果你发现由于刮削不准确导致的封面错误或元数据异常，优先调用网页搜索、图片搜索拿到精准信息，后直接执行 `python bookshelf.py update <ID> --json '{"title_en": "...", "douban_score": 8.5}'` 快速订正。如果你找到了正确的高清原书封面图，请下载到本地后利用 `python bookshelf.py update <ID> --cover "./path/to/better_cover.jpg"` 强制更正库内封面，无须等待用户操作调整。