poxenstudio/mybooks/mybooks

MyBooks

Requirements

# 需要配置以下三个环境变量后方可使用
export MYBOOKS_HOST="http://127.0.0.1:8082"
export MYBOOKS_USER="admin"
export MYBOOKS_PASSWORD="your_password"
export MYBOOKS_SSL_VERIFY="false"   # 如服务器使用自签名证书，设为 false
# 明文 http 仅允许回环/内网地址（如 192.168.x.x）；公网地址必须用 https
# 确需对非内网地址使用明文 http 时：export MYBOOKS_ALLOW_INSECURE_HTTP="true"
 
然后按如下方式执行：
<skill-installation-path>/scripts/mybooks_api.py <tool-name> '<json-args>'

例外：wuming_search / wuming_toplist / wuming_recent_hot / wuming_detail /

wuming_guide / wuming_tags 访问的是公开站点 book345，不需要上面三个环境变量，

其余工具仍然必须配置。

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

权限与网络声明

• 网络访问（必需）：本 skill 是 MyBooks 服务器的 REST 客户端，除 wuming_* 外的所有工具都通过 HTTP(S) 访问且仅访问用户自己配置的 MYBOOKS_HOST，不连接任何其他地址，无遥测、无第三方回传。
• 外部网络（仅 `wuming_*`）：wuming_search / wuming_toplist / wuming_recent_hot / wuming_detail / wuming_guide / wuming_tags 会访问公开站点 https://www.book345.com/api；不携带任何凭据、不上传任何本地数据，只用于读取公开图书元数据。
• 会修改数据的工具：edit_book、set_folder、rename_folder、push_notes(dry_run:false)、clear_imported_notes、book_fill、book_refer_apply、epub_fix、save_meta_to_file、book_upload（含指定 book_id 的替换模式）、book_add_by_isbn、wants/favorite/reading/read_done、set_reading_time、delete_reading_time、书单的创建/修改/删除/增删书/点赞、以及全部 tts_* 写操作、batch_edit(dry_run:false)、library_enrich_apply(dry_run:false)、library_enrich(dry_run:false)、book_add_from_wuming(auto_add:true)。authors_normalize 与 library_audit / library_research* 为只读。删除类工具（delete_booklist、delete_reading_time）脚本内强制 confirm:true 两步确认。
• 本地文件读取：仅 book_upload（新建入库，或为已有书籍新增/替换格式文件；限电子书扩展名 epub/mobi/azw/azw3/pdf/txt/lrf/rtf/djvu/docx）和 tts_clone_upload（限 mp3/wav，≤7MB）会读取用户明确给出路径的文件并上传到 MYBOOKS_HOST；agent 不得自行挑选文件上传。
• 本地文件写入：仅 tts_clone_audio 的 save_to（必须 .wav 结尾，且不覆盖已存在文件）。
• 凭据：见下方"认证方式"。

通用响应格式与认证方式

通用 JSON 响应结构

所有 API 均返回如下格式：

{
  "err": "ok",       // "ok" 表示成功，其他字符串表示错误码
  "msg": "...",      // 可选，人类可读的成功/错误说明
  "data": { }        // 可选，具体响应数据（因接口而异）
}

常见错误码：

认证方式

• 脚本通过 MYBOOKS_USER / MYBOOKS_PASSWORD 环境变量自动调用 /api/user/sign_in 完成登录
• 服务端通过 Secure Cookie（user_id + lt）维持会话
• 若响应中出现 err=user.need_login，脚本会自动重新登录后重试一次；仍失败则报错退出
• 凭据去向说明：MYBOOKS_USER / MYBOOKS_PASSWORD 只会以表单形式 POST 到用户自己配置的 MYBOOKS_HOST 的 /api/user/sign_in，不会发往任何其他地址；登录请求不跟随重定向；MYBOOKS_HOST 必须是 http(s)://host[:port] 且不含内嵌账号密码，对非内网地址要求 https
• 必须在调用前配置 MYBOOKS_HOST、MYBOOKS_USER、MYBOOKS_PASSWORD 三个环境变量，否则脚本直接报错退出

外部元数据源工具列表（无名图书 book345，无需凭据）

这一组工具直接访问公开站点 https://www.book345.com/api，不需要 `MYBOOKS_HOST/USER/PASSWORD`，

不携带任何凭据、不上传任何本地数据，全部只读。适合「先把书查清楚，再决定是否入库」以及

「书库服务器没开 / 还没有书库」的场景。

wuming_search — 搜书（外部）

使用场景：按书名/作者/ISBN/关键词在 book345 检索，拿到 ISBN、出版社、出版日期、评分、简介后再决定入库

参数：

执行脚本：

<skill-installation-path>/scripts/mybooks_api.py wuming_search '{"query":"三体","count":5}'

响应示例（裁剪）：

{
  "page": 1, "count": 5, "totalCount": 1,
  "books": [{
    "isbn": "9787536692930", "title": "三体", "author": "刘慈欣",
    "publisher": "重庆出版社", "pubDate": "2007-12-31", "rate": 8.9,
    "tags": ["科幻", "刘慈欣"], "summary": "……", "img": "/covers/s/9787536692930.jpg"
  }]
}

源站字段是 pubDate（驼峰），不是 pub_date。

wuming_toplist — 精选榜单（外部）

使用场景：逛高分榜/新书榜，发现值得加入想读清单的书（配合 wants 使用）

参数：

执行脚本：

<skill-installation-path>/scripts/mybooks_api.py wuming_toplist '{"type":"top","count":10}'

wuming_recent_hot — 近期热门（外部）

使用场景：看最近更新/热门的书，可按分类过滤

参数：

执行脚本：

<skill-installation-path>/scripts/mybooks_api.py wuming_recent_hot '{"tag":"文学","count":10}'

wuming_detail — 图书详情（外部）

使用场景：已知 ISBN，取权威详情用于核对或回填（作者、出版社、出版日期、页数、定价、评分、简介、目录）

参数：

执行脚本：

<skill-installation-path>/scripts/mybooks_api.py wuming_detail '{"isbn":"9787536692930"}'

响应关键字段：title / author / publisher / pubDate / summary / tags / rate / binding / price / catelogues

wuming_guide — AI 导读（外部）

使用场景：给一本书生成/获取 AI 书评、核心看点、读者共识、章节摘要

参数：

执行脚本：

<skill-installation-path>/scripts/mybooks_api.py wuming_guide '{"isbn":"9787536692930"}'

源站对部分书目返回 {"summarys": null}，属正常情况，不是调用失败。

wuming_tags — 分类列表（外部）

使用场景：查 book345 支持哪些分类 tag，供 wuming_recent_hot 的 tag 参数使用

参数：无

执行脚本：

<skill-installation-path>/scripts/mybooks_api.py wuming_tags '{}'

工具列表

get_user_info — 用户信息与系统统计

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

参数：无

执行脚本：

<skill-installation-path>/scripts/mybooks_api.py get_user_info '{}'

响应示例：

{
  "err": "ok",
  "user": { "is_login": true, "nickname": "管理员", "is_admin": true },
  "sys": { "books": 1280, "authors": 342, "tags": 86, "mtime": "2025-03-01" }
}

library_stats — 书库统计

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

参数：无

执行脚本：

<skill-installation-path>/scripts/mybooks_api.py library_stats '{}'

响应示例：

{
  "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 — 阅读统计

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

参数：无

执行脚本：

<skill-installation-path>/scripts/mybooks_api.py reading_stats '{}'

响应示例：

{
  "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 — 搜索书籍

使用场景：

• 关键词模糊搜索（书名/作者/简介），支持简繁体自动转换："有没有余华的书？" / "找一下《三体》"
• 按字段精确定位：只查书名、只查作者、按 ISBN 查找："ISBN 9787536692930 是哪本书？"
• 组合条件搜索：多个字段参数同时给出时按 AND 组合："余华在作家出版社出的书"
• Calibre 条件表达式：name 中写入 字段:值 形式的表达式，支持 AND/OR/NOT 与括号："评分 4 星以上的科幻小说"

参数（name/title/author/isbn/publisher/series/tag 至少提供一个）：

`name` 的三种解析方式（后台自动识别）：

1. 纯 ISBN（10/13 位数字，可含 -）→ 按 ISBN 精确查找。
2. Calibre 条件表达式（包含 字段: 形式，字段为 Calibre 内置搜索字段或 # 开头的自定义列）→ 原样交给 Calibre 搜索（同时追加简繁体转换版本以 OR 合并）。
3. 其它 → 普通关键字，在书名/作者/简介等所有字段中模糊搜索。

Calibre 表达式速查：

常用字段：title authors tags publisher series isbn identifiers comments rating pubdate timestamp formats languages id，以及 # 开头的自定义列。

执行脚本：

# 关键词
<skill-installation-path>/scripts/mybooks_api.py search_books '{"name":"三体"}'
# 按 ISBN
<skill-installation-path>/scripts/mybooks_api.py search_books '{"isbn":"978-7-5366-9293-0"}'
# 组合条件：余华 + 作家出版社
<skill-installation-path>/scripts/mybooks_api.py search_books '{"author":"余华","publisher":"作家出版社"}'
# 书名精确匹配
<skill-installation-path>/scripts/mybooks_api.py search_books '{"title":"活着"}'
# Calibre 表达式
<skill-installation-path>/scripts/mybooks_api.py search_books '{"name":"tags:科幻 AND rating:>=4","order":"rating"}'

选择建议：用户只给出模糊描述时用 name 关键词；明确说出"作者是…/出版社是…/ISBN…"时用对应字段参数；需要评分、日期、格式、排除等条件时用 Calibre 表达式。字段参数与 name 可同时使用，彼此为 AND 关系。

响应示例：

{
  "err": "ok",
  "title": "搜索作者:余华 出版社:作家出版社",
  "total": 3,
  "books": [ /* 书籍对象列表 */ ]
}

search_by_category — 按分类查询书籍

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

参数：

执行脚本：

<skill-installation-path>/scripts/mybooks_api.py search_by_category '{"category":"科幻"}'

list_folders — 查看目录树

使用场景：查看书库的"目录"（层级有上限，当前为两级，如 文学.小说）及各目录书籍数量；未设置目录的书在根目录 /

参数：无

执行脚本：

<skill-installation-path>/scripts/mybooks_api.py list_folders '{}'

响应示例（count 含子目录，root_count 为未设置目录的书）：

{
  "err": "ok",
  "folders": [
    { "name": "文学", "count": 12, "children": [{ "name": "小说", "count": 8 }] }
  ],
  "root_count": 5,
  "max_depth": 2
}

search_by_folder — 按目录查询书籍

使用场景：查看某个目录下直属的书（不含子目录的书）；path 为空表示根目录

参数：

执行脚本：

<skill-installation-path>/scripts/mybooks_api.py search_by_folder '{"path":"文学.小说"}'

set_folder — 设置书籍目录

使用场景：把一本或多本书放进某个目录。单本需管理员或书籍所有者；批量（book_ids）仅管理员

参数：

执行脚本：

<skill-installation-path>/scripts/mybooks_api.py set_folder '{"book_id":42,"folder":"文学.小说"}'

rename_folder — 重命名目录

使用场景：修改目录的最后一段名称（仅管理员），子目录随之改名，如 文学 → 读物 后 文学.小说 变为 读物.小说

参数：

执行脚本：

<skill-installation-path>/scripts/mybooks_api.py rename_folder '{"path":"文学.小说","name":"故事"}'

get_book — 书籍详情

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

参数：