calibre-catalog-read

通过正在运行的内容服务器进行只读 Calibre 目录查找和一本书分析评论工作流程。仅用于列表/搜索/id 和分析评论块更新，切勿用于标题/作者/标签/系列/series_index 元数据编辑。

# 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`)

## Skill selection contract (strict)

- This skill is read-only for catalog lookup + analysis workflow.
- If user intent includes metadata edit/fix/update (title/authors/series/series_index/tags/publisher/pubdate/languages),
  route to `calibre-metadata-apply` and do not execute edit paths here.

Do NOT use this skill for:
- Editing title/authors/series/series_index/tags/publisher/pubdate/languages
- Any user request that says "metadata edit", "title fix", "ID指定で編集"
- Those must use `calibre-metadata-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`
  - If `LIBRARY_ID` is unknown, use `#-` once to list available IDs on the server.
- Do not assume localhost/127.0.0.1; always pass explicit reachable `HOST:PORT`.
- `--with-library` can be omitted only when one of these is configured:
  - env: `CALIBRE_WITH_LIBRARY` or `CALIBRE_LIBRARY_URL` or `CALIBRE_CONTENT_SERVER_URL`
  - config: `~/.config/calibre-catalog-read/config.json` with `with_library`
  - optional library id completion: `CALIBRE_LIBRARY_ID` or config `library_id`
- Host failover (IP change resilience):
  - Optional env: `CALIBRE_SERVER_HOSTS=host1,host2,...`
  - Script auto-tries candidates, including WSL host-side `nameserver` from `/etc/resolv.conf`.
- If auth is enabled:
  - Preferred: set in `/home/altair/.openclaw/.env`
    - `CALIBRE_USERNAME=<user>`
    - `CALIBRE_PASSWORD=<password>`
  - Auth scheme policy for this workflow:
    - Non-SSL deployment assumes **Digest** authentication.
    - Do not pass auth mode arguments such as `--auth-mode` / `--auth-scheme`.
  - Then pass only `--password-env CALIBRE_PASSWORD` (username auto-loads from env)
  - You can still override with `--username <user>` explicitly.
  - Optional auth cache file: `~/.config/calibre-catalog-read/auth.json`
    - Avoid `--save-plain-password` unless explicitly requested.

## Commands

List books (JSON):

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

Search books (JSON):

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

Get one book by id (JSON):

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

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

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

## Cache DB

Initialize DB schema:

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

Check current hash state:

```bash
uv run python skills/calibre-catalog-read/scripts/analysis_db.py status \
  --db skills/calibre-catalog-read/state/calibre_analysis.sqlite \
  --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.
- For read operations in agent/chat, prefer `node .../calibredb_read.mjs` instead of direct `calibredb` calls.
- Never run `calibre-server` from this skill.
  - This workflow always connects to an already-running Calibre Content server.

## Connection bootstrap (mandatory)

- Do not ask the user for `--with-library` first.
- First, run read commands (`list/search/id`) without explicit `--with-library` and use saved defaults.
  - Scripts auto-load `.env` and resolve `CALIBRE_WITH_LIBRARY` / `CALIBRE_CONTENT_SERVER_URL`.
- Ask user for URL only if resolution fails (`missing --with-library` / `unable to resolve usable --with-library`).

## 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:
   ```bash
   node skills/calibre-catalog-read/scripts/prepare_subagent_input.mjs \
     --book-id <id> --title "<title>" --lang ja \
     --text-path /tmp/book_<id>.txt --out-dir /tmp/calibre_subagent_<id>
   ```
2. Main agent uses the shared builder skill `subagent-spawn-command-builder` to generate the `sessions_spawn` payload, the