talebook

Talebook(PoxenStudio)是个人书库管理系统，提供电子书及实体书管理，包括存储、分类、搜索和元数据管理功能。你可以帮助用户：查询书库统计信息和阅读统计,搜索/浏览书籍,获取书籍详情,更新书籍元数据（书名、作者、标签、分类、简介等）,自动联网填充书籍信息,发送书籍到邮箱或阅读器设备,上传电子书或通过ISBN添加实体书,管理阅读状态（想读/在读/已读/收藏）,查看作者信息和分类信息

# talebook

## Requirements
```bash
# 需要配置以下三个环境变量后方可使用
export TALEBOOK_HOST="http://127.0.0.1:8082"
export TALEBOOK_USER="admin"
export TALEBOOK_PASSWORD="your_password"

然后按如下方式执行：
<skill-installation-path>/scripts/talebook_api.py <tool-name> '<json-args>'
```

> **安全提示**：请勿将凭据写入共享或全局配置文件（如 `~/.openclaw/.env`），以避免凭据被其他 agent 或进程意外读取。建议通过会话级环境变量或专用密钥管理工具传入凭据。

## 通用响应格式与认证方式

### 通用 JSON 响应结构
所有 API 均返回如下格式：
```json
{
  "err": "ok",       // "ok" 表示成功，其他字符串表示错误码
  "msg": "...",      // 可选，人类可读的成功/错误说明
  "data": { }        // 可选，具体响应数据（因接口而异）
}
```

常见错误码：
| `err` 值 | 含义 |
|----------|------|
| `"ok"` | 操作成功 |
| `"user.need_login"` | 未登录或登录态已过期 |
| `"permission"` | 无权限执行该操作 |
| `"params.invalid"` | 请求参数错误 |
| `"params.book.invalid"` | 书籍不存在或 ID 错误 |
| `"task.running"` | 后台任务正在进行中，稍后重试 |

### 认证方式
- 脚本通过 `TALEBOOK_USER` / `TALEBOOK_PASSWORD` 环境变量自动调用 `/api/user/sign_in` 完成登录
- 服务端通过 **Secure Cookie**（`user_id` + `lt`）维持会话
- 若响应中出现 `err=user.need_login`，脚本会自动重新登录后重试一次；仍失败则报错退出
- **必须**在调用前配置 `TALEBOOK_HOST`、`TALEBOOK_USER`、`TALEBOOK_PASSWORD` 三个环境变量，否则脚本直接报错退出

---

## 工具列表

### `get_user_info` — 用户信息与系统统计

**使用场景**：获取当前登录用户信息，同时返回书库总体统计（书籍数、作者数等）

**参数**：无

**执行脚本**：
```bash
<skill-installation-path>/scripts/talebook_api.py get_user_info '{}'
```

**响应示例**：
```json
{
  "err": "ok",
  "user": { "is_login": true, "nickname": "管理员", "is_admin": true },
  "sys": { "books": 1280, "authors": 342, "tags": 86, "mtime": "2025-03-01" }
}
```

---

### `library_stats` — 书库统计

**使用场景**：获取书库详细统计，包括电子书/实体书数量及本月新增

**参数**：无

**执行脚本**：
```bash
<skill-installation-path>/scripts/talebook_api.py library_stats '{}'
```

**响应示例**：
```json
{
  "err": "ok",
  "stats": {
    "total_books": 1280,
    "ebook_count": 1210,
    "physical_count": 70,
    "month_ebook_count": 12,
    "month_physical_count": 3,
    "current_year": 2025,
    "current_month": 3
  }
}
```

---

### `reading_stats` — 阅读统计

**使用场景**：获取当前用户的阅读统计（在读/已读数量、本月数据）及当前在读书单

**参数**：无

**执行脚本**：
```bash
<skill-installation-path>/scripts/talebook_api.py reading_stats '{}'
```

**响应示例**：
```json
{
  "err": "ok",
  "stats": {
    "total_reading": 5,
    "total_read_done": 42,
    "month_reading": 2,
    "month_read_done": 3
  },
  "current_reading_books": [ /* 书籍对象列表 */ ],
  "month_read_done_books": [ /* 书籍对象列表 */ ]
}
```

---

### `search_books` — 搜索书籍

**使用场景**：
- 按书名或作者名搜索，支持简繁体自动转换
- "有没有余华的书？" / "找一下《三体》"

**参数**：

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `name` | string | ✅ | — | 搜索关键词（书名或作者名） |
| `num` | int | ❌ | 20 | 每页数量 |
| `page` | int | ❌ | 1 | 页码，从 1 开始 |

**执行脚本**：
```bash
<skill-installation-path>/scripts/talebook_api.py search_books '{"name":"三体"}'
```

**响应示例**：
```json
{
  "err": "ok",
  "title": "搜索：三体",
  "total": 3,
  "books": [ /* 书籍对象列表 */ ]
}
```

---

### `search_by_category` — 按分类查询书籍

**使用场景**：查询指定分类下的所有书籍（基于自定义 `#category` 字段）

**参数**：

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `category` | string | ✅ | — | 分类名称，如 "科幻" |
| `num` | int | ❌ | 20 | 每页数量 |
| `page` | int | ❌ | 1 | 页码，从 1 开始 |

**执行脚本**：
```bash
<skill-installation-path>/scripts/talebook_api.py search_by_category '{"category":"科幻"}'
```

---

### `get_book` — 书籍详情

**使用场景**：获取指定书籍的完整信息，包括元数据、可用格式、封面、阅读状态等

**参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `book_id` | int | ✅ | 书籍 ID |

**执行脚本**：
```bash
<skill-installation-path>/scripts/talebook_api.py get_book '{"book_id":42}'
```

**响应示例**：
```json
{
  "err": "ok",
  "book": {
    "id": 42,
    "title": "活着",
    "authors": ["余华"],
    "tags": ["小说", "中国文学"],
    "publisher": "作家出版社",
    "isbn": "9787506365437",
    "pubdate": "2012-08-01",
    "rating": 9,
    "comments": "《活着》讲述了...",
    "category": "现代文学",
    "available_formats": ["epub", "pdf"],
    "fmt_epub": "/path/to/file.epub",
    "cover_url": "/get/cover/42",
    "state": {
      "favorite": 0,
      "wants": 0,
      "read_state": 1
    }
  },
  "kindle_sender": "sender@example.com"
}
```

---

### `edit_book` — 编辑书籍元数据

**使用场景**：
- 手动修改书名、作者、标签、分类等字段
- 修改实体书数量或类型

**参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `book_id` | int | ✅ | 书籍 ID |
| `title` | string | ❌ | 书名 |
| `authors` | array | ❌ | 作者列表，如 `["余华"]` |
| `tags` | array | ❌ | 标签列表，**替换**原有标签（想追加需先 `get_book` 获取现有标签再合并） |
| `publisher` | string | ❌ | 出版社 |
| `isbn` | string | ❌ | ISBN 编号 |
| `series` | string | ❌ | 系列/丛书名 |
| `rating` | number | ❌ | 评分（0–10） |
| `languages` | array | ❌ | 语言代码列表，如 `["zho"]`（中文）、`["eng"]`（英文） |
| `pubdate` | string | ❌ | 出版日期，格式：`"2024-01-15"` / `"2024-01"` / `"2024"` |
| `comments` | string | ❌ | 书籍简介，支持 HTML，请勿将 `<>` 转义为 `&lt;&gt;` |
| `category` | string | ❌ | 自定义分类（最长 80 字符；传 `"清除"` 或 `"clear"` 清空分类） |
| `book_count` | int | ❌ | 实体书数量（需配合 `book_type: 1` 使用） |
| `book_type` | int | ❌ | 书籍类型：`0`=电子书，`1`=实体书 |

**执行脚本**：
```bash
<skill-installation-path>/scripts/talebook_api.py edit_book '{"book_id":42,"tags":["小说","中国文学"],"category":"现代文学"}'
```

**响应示例**：
```json
{ "err": "ok", "msg": "更新成功", "books": [42] }
```

---

### `book_fill` — 自动联网填充书籍信息

**使用场景**：
- "帮我更新《XX》的封面和简介"
- "书库里有很多书信息不完整，帮我补全"
- 批量补全多本书的封面、简介、出版社、出版日期、标签等

**权限**：需要管理员权限

**参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `idlist` | array 或 `"all"` | ✅ | 书籍 ID 数组，或 `"all"` 表示全库处理 |

**注意**：任务在后台异步执行，调用后立即返回；书名**默认保留原值不修改**（防止错误覆盖）

**执行脚本**：
```bash
# 更新单本书
<skill-installation-path>/scripts/talebook_api.py book_fill '{"idlist":[42]}'

# 批量更新
<skill-installation-path>/scripts/talebook_api.py book_fill '{"idlist":[42,43,44]}'
```

**响应示例**：
```json
{ "err": "ok", "msg": "任务启动成功！请耐心等待，稍后再来刷新页面" }
```

---

### `mailto` — 发送书籍到邮箱

**使用场景**：将书籍以附件形式发送到指定邮箱（如 Kindle 邮箱）

**格式优先级**：epub > azw3 > pdf > mobi > txt（取首个存在的格式）

**权限**：需要登录，且账号需有推送权限（`can_push`）

**参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `book_id` | int | ✅ | 书籍 ID |
| `email` | string | ✅ | 目标邮箱地址（可以是 Kindle 邮箱） |

**执行脚本**：
```bash
<skill-installation-path>/scripts/talebook_api.py mailto '{"book_id":42,"email":"user@kindle.com"}'
```

**响应示例**：
```json
{ "err": "ok", "msg": "后台正在推送，稍后可以刷新页面，在通知消息中查看结果。" }
```

---

### `send_to_device` — 发送书籍到阅读器设备

**使用场景**：通过 WiFi 将书籍直接推送到阅读器设备（仅支持当前网络内的临时设备）

**支持的设备类型（`device_type`）**：

| 类型 | 设备 | 传输方式 | `device_url` 说明 |
|------|------|----------|-------------------|
| `kindle` | Kindle 系列 | 邮件发送 | 不需填写，改用 `mailbox` 参数 |
| `duokan` | 多看阅读器 | HTTP WiFi 上传 | 设备局域网 IP，如 `192.168.1.100` |
| `ireader` | 掌阅 iReader | HTTP WiFi 上传 | 设备局域网 IP |
| `hanwang` | 汉王电纸书 | HTTP WiFi 上传 | 设备局域网 IP |
| `boox` | 文石 BOOX | HTTP WiFi 上传 | 设备局域网 IP |
| `dangdang` | 当当阅读器 | HTTP WiFi 上传 | 设备局域网 IP |

**WiFi 传输格式优先级**：epub > azw3 > pdf > txt

**参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `book_id` | int | ✅ | 书籍 ID |
| `device_type` | string | ✅ | 设备类型（见上表） |
| `device_url` | string | kindle 以外必填 | 设备局域网 IP 或地址（如 `"192.168.1.100"` 或 `"http://192.168.1.100:80"`） |
| `mailbox` | string | kindle 时必填 | Kindle 邮箱地址 |

**执行脚本**：
```bash
# 发送到多看设备
<skill-installation-path>/scripts/talebook_api.py send_to_device \
  '{"book_id":42,"device_type":"duokan","device_url":"192.168.1.100"}'

# 发送到 Kindle（通过邮件）
<skill-installation-path>/scripts/talebook_api.py send_to_device \
  '{"book_id":42,"device_type":"kindle","mailbox":"mykindle@kindle.cn"}'
```

**响应示例**：
```json
{ "err": "ok", "msg": "书籍发送成功" }
```

---

### `categories` — 查看分类信息

**使用场景**：获取当前书库中所有自定义分类及各分类下的书籍数量

**参数**：无

**执行脚本**：
```bash
<skill-installation-path>/scripts/talebook_api.py categories '{}'
```

**响应示例**：
```json
{
  "err": "ok",
  "categories": [
    { "name": "现代文学", "count": 128 },
    { "name": "科幻", "count": 56 }
  ]
}
```

---

### `list_authors` — 查看作者列表

**使用场景**：获取所有有在库书籍的作者及其书籍数量

**参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `show` | string | ❌ | 传 `"all"` 显示全部，否则返回前 N 条 |

**执行脚本**：
```bash
<skill-installation-path>/scripts/talebook_api.py list_authors '{}'
```

**响应示例**：
```json
{
  "err": "ok",
  "meta": "author",
  "title": "全部作者",
  "items": [