什么是 Calibre Catalog Read？

Calibre Catalog Read 技能是 Openclaw Skills 框架的专业级扩展，旨在弥合本地电子书管理与大语言模型智能之间的鸿沟。它使 AI 代理能够通过 calibredb 直接与 Calibre 内容服务器交互，实现自动化的库审计、元数据丰富和深层内容理解。该技能专为性能和可靠性而设计，采用双代理架构，确保繁重的文本分析不会阻塞用户交互。通过将其集成到您的 Openclaw Skills 设置中，您可以将静态书籍收藏转化为动态、AI 可搜索的知识库，洞察结果将以整洁的 HTML 格式自动写回书库备注。

下载入口:https://github.com/openclaw/skills/tree/main/skills/nextaltair/calibre-catalog-read

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

Calibre Catalog Read 应用场景

• 为新加入的书籍自动生成主题摘要和批判性分析。
• 通过自然语言界面在大型 Calibre 藏书中搜索和列出书籍。
• 将 AI 生成的见解同步回数据库，从而丰富 Calibre 元数据。
• 从 EPUB 和其他格式中进行高性能文本提取，用于研究和存档。

1. 主代理与 Calibre 内容服务器交互，根据用户查询识别目标书籍。
2. 使用 ebook-convert 处理选定的电子书文件以提取原始文本内容。
3. 该技能准备分段负载以避免工具调用限制，并生成一个专门的子代理。
4. 子代理根据严格的 JSON 模式对书籍内容进行多步骤分析。
5. 主代理接收分析结果，将其缓存在本地 SQLite 数据库中，并使用 HTML 格式的分析块更新 Calibre 书籍备注。

Calibre Catalog Read 配置指南

要在您的 Openclaw Skills 环境中部署此技能，请确保您的系统路径中已安装 calibredb、ebook-convert、node 和 uv。在环境中配置您的库凭据：

export CALIBRE_PASSWORD='your_password'
export CALIBRE_USERNAME='your_username'

使用以下命令初始化持久缓存数据库：

uv run python skills/calibre-catalog-read/scripts/analysis_db.py init --db skills/calibre-catalog-read/state/calibre_analysis.sqlite

Calibre Catalog Read 数据架构与分类体系

该技能通过一组结构化的文件和数据库管理其运行数据：

• **运行状态 (runs.json)**：跟踪活动分析任务的生命周期，包括运行 ID 和时间戳。
• **分析缓存 (calibre_analysis.sqlite)**：存储内容哈希和之前分析结果的 SQLite 数据库，以减少冗余 API 调用。
• **身份验证 (auth.json)**：可选的 Calibre 内容服务器会话令牌本地存储。
• 元数据映射：分析结果作为标准化的 HTML 存储在 calibre:comments-metadata 字段中。

name: calibre-catalog-read
description: Read Calibre catalog data via calibredb over a Content server, and run one-book analysis workflow that writes HTML analysis block back to comments while caching analysis state in SQLite. Use for list/search/id lookups and AI reading pipeline for a selected book.
metadata: {"openclaw":{"requires":{"bins":["node","uv","calibredb","ebook-convert"],"env":["CALIBRE_PASSWORD"]},"optionalEnv":["CALIBRE_USERNAME"],"primaryEnv":"CALIBRE_PASSWORD","dependsOnSkills":["subagent-spawn-command-builder"],"localWrites":["skills/calibre-catalog-read/state/runs.json","skills/calibre-catalog-read/state/calibre_analysis.sqlite","skills/calibre-catalog-read/state/cache/**","~/.config/calibre-catalog-read/auth.json"],"modifiesRemoteData":["calibre:comments-metadata"]}}

calibre-catalog-read

Use this skill for:

• Read-only catalog lookup (list/search/id)
• One-book AI reading workflow (export -> analyze -> cache -> comments HTML apply)

Requirements

• calibredb available on PATH in the runtime where scripts are executed.
• ebook-convert available for text extraction.
• subagent-spawn-command-builder installed (for spawn payload generation).
• Reachable Calibre Content server URL in --with-library format:
  • http://HOST:PORT/#LIBRARY_ID
• Do not assume localhost/127.0.0.1; always pass explicit reachable HOST:PORT.
• If auth is enabled:
  • Preferred: set in /home/altair/.openclaw/.env
    • CALIBRE_USERNAME=
    • CALIBRE_PASSWORD=
  • Then pass only --password-env CALIBRE_PASSWORD (username auto-loads from env)
  • You can still override with --username explicitly.
  • Optional auth cache file: ~/.config/calibre-catalog-read/auth.json
    • Avoid --save-plain-password unless explicitly requested.

Commands

List books (JSON):

node skills/calibre-catalog-read/scripts/calibredb_read.mjs list r
  --with-library "http://192.168.11.20:8080/#Calibreライブラリ" r
  --password-env CALIBRE_PASSWORD r
  --limit 50

Search books (JSON):

node skills/calibre-catalog-read/scripts/calibredb_read.mjs search r
  --with-library "http://192.168.11.20:8080/#Calibreライブラリ" r
  --password-env CALIBRE_PASSWORD r
  --query 'series:"中公文庫"'

Get one book by id (JSON):

node skills/calibre-catalog-read/scripts/calibredb_read.mjs id r
  --with-library "http://192.168.11.20:8080/#Calibreライブラリ" r
  --password-env CALIBRE_PASSWORD r
  --book-id 3

Run one-book pipeline (analyze + comments HTML apply + cache):

uv run python skills/calibre-catalog-read/scripts/run_analysis_pipeline.py r
  --with-library "http://192.168.11.20:8080/#Calibreライブラリ" r
  --password-env CALIBRE_PASSWORD r
  --book-id 3 --lang ja

Cache DB

Initialize DB schema:

uv run python skills/calibre-catalog-read/scripts/analysis_db.py init r
  --db skills/calibre-catalog-read/state/calibre_analysis.sqlite

Check current hash state:

uv run python skills/calibre-catalog-read/scripts/analysis_db.py status r
  --db skills/calibre-catalog-read/state/calibre_analysis.sqlite r
  --book-id 3 --format EPUB

Main vs Subagent responsibility (strict split)

Use this split to avoid long blocking turns on chat listeners.

Main agent (fast control plane)

• Validate user intent and target book_id.
• Confirm subagent runtime knobs: model, thinking, runTimeoutSeconds.
• Start subagent and return a short progress reply quickly.
• After subagent result arrives, run DB upsert + Calibre apply.
• Report final result to user.

Subagent (heavy analysis plane)

• Read extracted source payload.
• Generate analysis JSON strictly by schema.
• Do not run metadata apply or user-facing channel actions.

Never do in main when avoidable

• Long-form content analysis generation.
• Multi-step heavy reasoning over full excerpts.

Turn policy

• One book per run.
• Prefer asynchronous flow: quick ack first, final result after analysis.
• If analysis is unavailable, either ask user or use fallback only when explicitly acceptable.

Subagent pre-flight (required)

Before first subagent run in a session, confirm once:

• model
• thinking (low/medium/high)
• runTimeoutSeconds

Do not ask on every run. Reuse the confirmed settings for subsequent books in the same session unless the user asks to change them.

Subagent support (model-agnostic)

Book-reading analysis is a heavy task. Use a subagent with a lightweight model for analysis generation, then return results to main agent for cache/apply steps.

• Prompt template: references/subagent-analysis.prompt.md
• Input schema: references/subagent-input.schema.json
• Output schema: references/subagent-analysis.schema.json
• Input preparation helper: scripts/prepare_subagent_input.mjs
  • Splits extracted text into multiple files to avoid read-tool single-line size issues.

Rules:

• Use subagent only for heavy analysis generation; keep main agent lightweight and non-blocking.
• In this environment, Python commands must use uv run python.
• Use the strict prompt template (references/subagent-analysis.prompt.md) as mandatory base; do not send ad-hoc relaxed read instructions.
• Keep final DB upsert and Calibre metadata apply in main agent.
• Process one book per run.
• Confirm model/thinking/timeout once per session, then reuse; do not hardcode provider-specific model IDs in the skill.
• Configure callback/announce behavior and rate-limit fallbacks using OpenClaw default model/subagent/fallback settings (not hardcoded in this skill).
• Exclude manga/comic-centric books from this text pipeline (skip when title/tags indicate manga/comic).
• If extracted text is too short, stop and ask user for confirmation before continuing.
  • The pipeline returns reason: low_text_requires_confirmation with prompt_en text.

Language policy

• Do not hardcode user-language prose in pipeline scripts.
• Generate user-visible analysis text from subagent output, with language controlled by user-selected settings and lang input.
• Fallback local analysis in scripts is generic/minimal; preferred path is subagent output following the prompt template.

Orchestration note (important)

run_analysis_pipeline.py is a local script and does not call OpenClaw tools by itself. Subagent execution must be orchestrated by the agent layer using sessions_spawn.

Required runtime sequence:

1. Main agent prepares subagent_input.json + chunked source_files from extracted text.
   • Use:

   node skills/calibre-catalog-read/scripts/prepare_subagent_input.mjs r
     --book-id  --title "