feat(Calibre): add a CLI-Anything harness for Calibre Desktop

.gitignore

@@ -75,6 +75,7 @@
 !/rms/
 !/renderdoc/
 !/cloudcompare/
+!/calibre
 !/openscreen/
 !/QGIS/
 !/n8n/
@@ -83,6 +84,7 @@
 !/nsight-graphics/
 !/lldb/
 
+
 # Step 5: Inside each software dir, ignore everything (including dotfiles)
 /gimp/*
 /gimp/.*

README.md

@@ -869,6 +869,13 @@ Each application received complete, production-ready CLI interfaces — not demo
 <td align="center">✅ <a href="zotero/agent-harness/">New</a></td>
 </tr>
 <tr>
+<td align="center"><strong>📚 <a href="calibre/agent-harness/">Calibre</a></strong></td>
+<td>Ebook Library Management</td>
+<td><code>cli-anything-calibre</code></td>
+<td>calibredb + ebook-meta + ebook-convert</td>
+<td align="center">✅ <a href="calibre/agent-harness/">New</a></td>
+</tr>
+<tr>
 <td align="center"><strong>📝 <a href="mubu/agent-harness/">Mubu</a></strong></td>
 <td>Knowledge Management &amp; Outlining</td>
 <td><code>cli-anything-mubu</code></td>
@@ -1156,6 +1163,7 @@ cli-anything/
 ├── 🌐 browser/agent-harness/            # Browser CLI (DOMShell MCP, new)
 ├── 📄 libreoffice/agent-harness/        # LibreOffice CLI (158 tests)
 ├── 📚 zotero/agent-harness/             # Zotero CLI (new, write import support)
+├── 📚 calibre/agent-harness/            # Calibre CLI (new, ebook workflow support)
 ├── 📝 mubu/agent-harness/               # Mubu CLI (96 tests)
 ├── 📹 obs-studio/agent-harness/         # OBS Studio CLI (153 tests)
 ├── 🎞️ kdenlive/agent-harness/           # Kdenlive CLI (155 tests)

README_CN.md

@@ -548,6 +548,13 @@ CLI-Anything 适用于任何有代码库的软件 —— 不限领域，不限
 <td align="center">✅ <a href="zotero/agent-harness/">新增</a></td>
 </tr>
 <tr>
+<td align="center"><strong>📚 <a href="calibre/agent-harness/">Calibre</a></strong></td>
+<td>电子书库管理</td>
+<td><code>cli-anything-calibre</code></td>
+<td>calibredb + ebook-meta + ebook-convert</td>
+<td align="center">✅ <a href="calibre/agent-harness/">新增</a></td>
+</tr>
+<tr>
 <td align="center"><strong>📹 OBS Studio</strong></td>
 <td>直播与录制</td>
 <td><code>cli-anything-obs-studio</code></td>
@@ -724,6 +731,7 @@ cli-anything/
 ├── 🎵 audacity/agent-harness/           # Audacity CLI（161 项测试）
 ├── 📄 libreoffice/agent-harness/        # LibreOffice CLI（158 项测试）
 ├── 📚 zotero/agent-harness/             # Zotero CLI（新增，支持文献导入）
+├── 📚 calibre/agent-harness/            # Calibre CLI（新增，电子书工作流）
 ├── 📹 obs-studio/agent-harness/         # OBS Studio CLI（153 项测试）
 ├── 🎞️ kdenlive/agent-harness/           # Kdenlive CLI（155 项测试）
 ├── 🎬 shotcut/agent-harness/            # Shotcut CLI（154 项测试）

README_JA.md

@@ -508,6 +508,13 @@ CLI-Anythingはコードベースを持つあらゆるソフトウェアで動
 <td align="center">✅ 158</td>
 </tr>
 <tr>
+<td align="center"><strong>📚 <a href="calibre/agent-harness/">Calibre</a></strong></td>
+<td>電子書籍ライブラリ管理</td>
+<td><code>cli-anything-calibre</code></td>
+<td>calibredb + ebook-meta + ebook-convert</td>
+<td align="center">✅ <a href="calibre/agent-harness/">新規</a></td>
+</tr>
+<tr>
 <td align="center"><strong>📹 OBS Studio</strong></td>
 <td>ライブストリーミング & 録画</td>
 <td><code>cli-anything-obs-studio</code></td>
@@ -646,6 +653,7 @@ cli-anything/
 ├── ✏️ inkscape/agent-harness/            # Inkscape CLI (202テスト)
 ├── 🎵 audacity/agent-harness/           # Audacity CLI (161テスト)
 ├── 📄 libreoffice/agent-harness/        # LibreOffice CLI (158テスト)
+├── 📚 calibre/agent-harness/            # Calibre CLI（新規、電子書籍ワークフロー）
 ├── 📹 obs-studio/agent-harness/         # OBS Studio CLI (153テスト)
 ├── 🎞️ kdenlive/agent-harness/           # Kdenlive CLI (155テスト)
 ├── 🎬 shotcut/agent-harness/            # Shotcut CLI (154テスト)

calibre/agent-harness/AGENT_TEST_PROMPT.md

@@ -0,0 +1,164 @@
+# Calibre Agent Test Prompt (Bilingual)
+
+> Purpose: reproducible **Agent test** prompt for OpenCode/Cursor/Claude Code in CLI-only mode.  
+> 目的：提供可复用的 **Agent test** 提示词（仅 CLI），用于开源复现。
+> Note / 说明：This file is an **example agent-test prompt/keyword template** for reproducible validation and can be adapted per environment.  
+> 注：该文件是用于复现实验的**示例智能体测试提示词/关键词模板**，可按环境替换路径与参数。
+> Status / 状态：**Example template (not a normative spec)**.  
+> 状态：**示例模板（非规范性标准文档）**。
+
+---
+
+## Quick Notes / 使用说明
+
+- **System / 系统**: Windows (PowerShell examples below)
+- **Terminal / 终端类型**: PowerShell (if using CMD, adjust line continuation syntax)
+- **Agent mode / 代理模式**: CLI-only (no GUI actions during Agent test)
+- **Path placeholders / 路径变量可替换**:
+  - `{{LIB}}` = calibre library root (must contain `metadata.db`)
+  - `{{EPUB}}` = input epub path
+  - `{{OUT}}` = export output directory
+  - `{{CONVERTED_FILE}}` = converted mobi output path
+
+Recommended defaults:
+
+```text
+{{LIB}} = D:\Books\Calibre Library
+{{EPUB}} = D:\AgentTest\sample.epub
+{{OUT}} = D:\AgentTest\out
+{{CONVERTED_FILE}} = D:\AgentTest\out\converted\agent-test.mobi
+```
+
+---
+
+## Prompt (ZH + EN)
+
+```text
+[中文]
+你是一个只允许使用 CLI 的执行代理。当前目标：完成 calibre 的 Agent test（加分/高阶验证）。不要生成新 harness，不要使用任何 GUI。
+
+【环境与固定路径】
+- OS: Windows (PowerShell)
+- calibre 已安装
+- cli-anything-calibre 已安装
+- LIB = {{LIB}}
+- EPUB = {{EPUB}}
+- OUT = {{OUT}}
+- CONVERTED_FILE = {{CONVERTED_FILE}}
+
+【硬性规则】
+1) 禁止猜参数；不确定必须先运行对应 --help。
+2) 每一步都输出：执行命令、exit code、关键输出。
+3) 失败时先打印错误，再自修复继续。
+4) 全程仅 CLI，不得调用 GUI。
+5) 路径必须使用绝对路径。
+
+【Preflight（必须先执行）】
+A. 检查命令可用（逐条执行）：
+- cli-anything-calibre --help
+- calibredb --version
+- ebook-convert --version
+- ebook-meta --version
+
+B. 若 `cli-anything-calibre` 不可调用：
+- 自动定位并使用 Python 用户 Scripts 下的 `cli-anything-calibre.exe`（或临时修正 PATH）后重试，直到可用。
+
+C. 若 `EPUB` 不存在：
+- 自动创建一个合法 EPUB 后继续（可用 html -> ebook-convert，或最小合法 zip 结构，确保 mimetype 未压缩）。
+
+D. 若 `LIB` 不是有效 calibre 书库（缺少 metadata.db）：
+- 先初始化书库（例如 `calibredb --with-library "<LIB>" list`），再继续。
+
+E. 探测子命令帮助（逐条执行）：
+- cli-anything-calibre library --help
+- cli-anything-calibre book --help
+- cli-anything-calibre export --help
+- cli-anything-calibre convert --help
+- cli-anything-calibre meta --help
+
+【主任务链（严格按顺序）】
+1) `library stats`（JSON）
+2) `book add`：将 `EPUB` 入库，`--title "Agent Test Book"`，`--authors "OpenCode Bot"`
+3) `book search "title:Agent Test Book"` 并提取 `book_id`（字段通常为 `id`）
+4) `export book <book_id> --to-dir "<OUT>" --single-dir`
+5) 在 `OUT` 下递归发现导出的 `.epub`（不要写死文件名），记为 `exported_epub`
+6) `convert run "<exported_epub>" "<CONVERTED_FILE>" --preset kindle`
+7) `meta show "<exported_epub>"`
+8) 校验 `CONVERTED_FILE` 存在且大小 > 0，并输出字节数
+
+【输出格式要求】
+- 先输出完整分步复盘（命令 + exit code + 关键输出）
+- 最后一行必须输出单行 JSON：
+  FINAL_RESULT={"library_path":"...","book_id":...,"export_dir":"...","exported_epub":"...","converted_file":"...","converted_file_size_bytes":...,"all_exit_zero":true/false}
+
+------------------------------------------------------------
+
+[English]
+You are a CLI-only execution agent. Goal: complete a calibre Agent test (bonus/advanced verification). Do not generate a new harness. Do not use GUI.
+
+[Environment and fixed paths]
+- OS: Windows (PowerShell)
+- calibre is installed
+- cli-anything-calibre is installed
+- LIB = {{LIB}}
+- EPUB = {{EPUB}}
+- OUT = {{OUT}}
+- CONVERTED_FILE = {{CONVERTED_FILE}}
+
+[Hard rules]
+1) Do not guess arguments; run --help first when unsure.
+2) For every step, print command, exit code, and key output.
+3) On failure, print error first, then self-correct and continue.
+4) CLI-only flow; no GUI actions.
+5) Use absolute paths only.
+
+[Preflight (required)]
+A. Verify command availability:
+- cli-anything-calibre --help
+- calibredb --version
+- ebook-convert --version
+- ebook-meta --version
+
+B. If `cli-anything-calibre` is not callable:
+- Auto-locate `cli-anything-calibre.exe` from Python user Scripts (or temporarily fix PATH), then retry.
+
+C. If `EPUB` does not exist:
+- Auto-create a valid EPUB (html -> ebook-convert, or minimal valid zip EPUB with uncompressed mimetype).
+
+D. If `LIB` is not a valid calibre library (missing metadata.db):
+- Initialize it first (e.g., `calibredb --with-library "<LIB>" list`).
+
+E. Probe subcommand helps:
+- cli-anything-calibre library --help
+- cli-anything-calibre book --help
+- cli-anything-calibre export --help
+- cli-anything-calibre convert --help
+- cli-anything-calibre meta --help
+
+[Main task chain (strict order)]
+1) `library stats` (JSON)
+2) `book add` with `--title "Agent Test Book"` and `--authors "OpenCode Bot"`
+3) `book search "title:Agent Test Book"` and extract `book_id` (typically `id`)
+4) `export book <book_id> --to-dir "<OUT>" --single-dir`
+5) Recursively discover exported `.epub` under `OUT` (do not hardcode filename), call it `exported_epub`
+6) `convert run "<exported_epub>" "<CONVERTED_FILE>" --preset kindle`
+7) `meta show "<exported_epub>"`
+8) Validate `CONVERTED_FILE` exists and size > 0, print file size in bytes
+
+[Output requirements]
+- First provide step-by-step recap (command + exit code + key output)
+- Final line must be a one-line JSON:
+  FINAL_RESULT={"library_path":"...","book_id":...,"export_dir":"...","exported_epub":"...","converted_file":"...","converted_file_size_bytes":...,"all_exit_zero":true/false}
+```
+
+---
+
+## Optional: GUI Round-trip Checklist / 可选 GUI 往返检查
+
+After CLI flow succeeds, verify consistency in Calibre GUI:
+
+1. Open the same library path (`{{LIB}}`).
+2. Confirm book row exists (`Agent Test Book` / `OpenCode Bot`).
+3. Open metadata editor and verify title/author.
+4. Confirm exported and converted files exist and are non-empty.
+

calibre/agent-harness/CALIBRE.md

@@ -0,0 +1,133 @@
+# Calibre: Project-Specific Analysis & SOP
+
+## Architecture Summary
+
+calibre is an ebook management suite covering library operations, metadata editing,
+export, and format conversion. Unlike many GUI-first tools, calibre already
+ships mature native CLI binaries, so the harness strategy is to compose these
+commands into an agent-friendly, stateful interface.
+
+```
+┌──────────────────────────────────────────┐
+│              Calibre GUI                 │
+│  ┌──────────┐ ┌──────────┐ ┌──────────┐ │
+│  │ Library  │ │ Metadata │ │ Convert  │ │
+│  └────┬─────┘ └────┬─────┘ └────┬─────┘ │
+│       │             │            │       │
+│  ┌────┴─────────────┴────────────┴─────┐ │
+│  │   Calibre backend (db + metadata)   │ │
+│  │  SQLite library + conversion stack  │ │
+│  └─────────────────┬───────────────────┘ │
+│                    │                     │
+│   ┌────────────────┴──────────────────┐  │
+│   │ Native CLI binaries               │  │
+│   │ calibredb | ebook-meta |          │  │
+│   │ ebook-convert                     │  │
+│   └───────────────────────────────────┘  │
+└──────────────────────────────────────────┘
+```
+
+Primary backend components:
+- Library database: `src/calibre/db/backend.py`
+- Database cache layer: `src/calibre/db/cache.py`
+- Legacy library API: `src/calibre/db/legacy.py`
+- Search/query layer: `src/calibre/db/search.py`
+- Metadata readers/writers: `src/calibre/ebooks/metadata/`
+- Conversion pipeline: `src/calibre/ebooks/conversion/`
+
+The GUI is primarily a PyQt6 frontend over these backend capabilities.
+
+## CLI Strategy: Native CLI Composition + Session Layer
+
+The harness wraps real calibre binaries and adds:
+1. stable command groups for agents (`library`, `book`, `meta`, `convert`, `export`, `session`)
+2. consistent machine-readable output via `--json`
+3. REPL-first interactive flow with undo/redo session history
+4. explicit validation and clearer error reporting for automation
+
+### Core Domains
+
+| Domain | Module | Native Tool(s) | Key Operations |
+|--------|--------|----------------|----------------|
+| Library | `core/library.py` | `calibredb` | open/info/list-fields/stats |
+| Books | `core/books.py` | `calibredb` | add/list/get/search/remove/set-field |
+| Metadata | `core/metadata.py` | `ebook-meta`, `calibredb` | show/set/clear/set-cover |
+| Convert | `core/convert.py` | `ebook-convert` | formats/presets/run |
+| Export | `core/export.py` | `calibredb` | export book/catalog/backup |
+| Session | `core/session.py` | harness layer | status/undo/redo/history/save |
+
+### Native Tool Registry
+
+From `src/calibre/linux.py`, calibre ships these console tools:
+- `calibredb`
+- `ebook-convert`
+- `ebook-meta`
+- `ebook-polish`
+- `calibre-server`
+- `calibre-debug`
+- `calibre-customize`
+- `fetch-ebook-metadata`
+- `calibre-smtp`
+- `calibre-parallel`
+- `calibre-complete`
+- `web2disk`
+
+Harness-critical tools:
+- `calibredb` for library inspection and mutation
+- `ebook-meta` for per-file metadata inspection/update
+- `ebook-convert` for format conversion
+
+### Conversion Presets
+
+Current harness-facing presets:
+- `kindle`
+- `tablet`
+- `generic-epub`
+
+These are mapped to curated `ebook-convert` argument bundles for stable agent use.
+
+### Translation Gap: Low Risk
+
+There is minimal translation gap because the harness delegates core behavior to
+calibre's own binaries rather than reimplementing internals. The main harness
+responsibility is orchestration, validation, and normalized output.
+
+## Data Model and Mapping
+
+calibre libraries are directory-based and centered on `metadata.db` (SQLite).
+Book records map to folders containing one or more format files plus metadata.
+This allows direct CLI operations without emulating GUI state.
+
+### Library/book mapping (`calibredb`)
+- list books -> `calibredb list --for-machine`
+- search books -> `calibredb list --search ... --for-machine`
+- add book -> `calibredb add`
+- remove book -> `calibredb remove`
+- show metadata -> `calibredb show_metadata`
+- export books -> `calibredb export`
+- backup metadata -> `calibredb backup_metadata`
+
+### File metadata mapping (`ebook-meta`)
+- inspect file metadata -> `ebook-meta <file>`
+- mutate file metadata -> `ebook-meta <file> --title ... --authors ...`
+- library-record metadata update -> `calibredb set_metadata <id> <opf-file>`
+
+### Conversion mapping (`ebook-convert`)
+- convert formats -> `ebook-convert input.epub output.mobi ...`
+
+## GUI Toolkit
+
+The GUI uses PyQt6 through calibre's lazy-loading `qt` shim.
+
+Relevant paths:
+- `src/qt/`
+- `src/calibre/gui2/`
+- `pyproject.toml`
+
+## Constraints
+
+- Real calibre tools are hard dependencies for E2E workflows
+- The harness must fail clearly if required binaries are not on PATH
+- REPL should remain the default entry behavior
+- All commands should support `--json`
+- Session persistence should use locked JSON writes