{ "schemaVersion": "1.0", "item": { "slug": "calibre-catalog-read", "name": "Calibre Catalog Read", "source": "tencent", "type": "skill", "category": "开发工具", "sourceUrl": "https://clawhub.ai/NEXTAltair/calibre-catalog-read", "canonicalUrl": "https://clawhub.ai/NEXTAltair/calibre-catalog-read", "targetPlatform": "OpenClaw" }, "install": { "downloadMode": "redirect", "downloadUrl": "/downloads/calibre-catalog-read", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=calibre-catalog-read", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "installMethod": "Manual import", "extraction": "Extract archive", "prerequisites": [ "OpenClaw" ], "packageFormat": "ZIP package", "includedAssets": [ "README.md", "SKILL.md", "references/subagent-analysis.prompt.md", "references/subagent-analysis.schema.json", "references/subagent-input.schema.json", "scripts/analysis_db.py" ], "primaryDoc": "SKILL.md", "quickSetup": [ "Download the package from Yavira.", "Extract the archive and review SKILL.md first.", "Import or place the package into your OpenClaw setup." ], "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run." } ] }, "sourceHealth": { "source": "tencent", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-04-30T16:55:25.780Z", "expiresAt": "2026-05-07T16:55:25.780Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network", "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"", "redirectLocation": null, "bodySnippet": null }, "scope": "source", "summary": "Source download looks usable.", "detail": "Yavira can redirect you to the upstream package for this source.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/calibre-catalog-read" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] }, "downloadPageUrl": "https://openagent3.xyz/downloads/calibre-catalog-read", "agentPageUrl": "https://openagent3.xyz/skills/calibre-catalog-read/agent", "manifestUrl": "https://openagent3.xyz/skills/calibre-catalog-read/agent.json", "briefUrl": "https://openagent3.xyz/skills/calibre-catalog-read/agent.md" }, "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run." } ] }, "documentation": { "source": "clawhub", "primaryDoc": "SKILL.md", "sections": [ { "title": "calibre-catalog-read", "body": "Use this skill for:\n\nRead-only catalog lookup (list/search/id)\nOne-book AI reading workflow (export -> analyze -> cache -> comments HTML apply)" }, { "title": "Requirements", "body": "calibredb available on PATH in the runtime where scripts are executed.\nebook-convert available for text extraction.\nsubagent-spawn-command-builder installed (for spawn payload generation).\nReachable Calibre Content server URL in --with-library format:\n\nhttp://HOST:PORT/#LIBRARY_ID\n\n\nDo not assume localhost/127.0.0.1; always pass explicit reachable HOST:PORT.\nIf auth is enabled:\n\nPreferred: set in /home/altair/.openclaw/.env\n\nCALIBRE_USERNAME=\nCALIBRE_PASSWORD=\n\n\nThen pass only --password-env CALIBRE_PASSWORD (username auto-loads from env)\nYou can still override with --username explicitly.\nOptional auth cache file: ~/.config/calibre-catalog-read/auth.json\n\nAvoid --save-plain-password unless explicitly requested." }, { "title": "Commands", "body": "List books (JSON):\n\nnode skills/calibre-catalog-read/scripts/calibredb_read.mjs list \\\n --with-library \"http://192.168.11.20:8080/#Calibreライブラリ\" \\\n --password-env CALIBRE_PASSWORD \\\n --limit 50\n\nSearch books (JSON):\n\nnode skills/calibre-catalog-read/scripts/calibredb_read.mjs search \\\n --with-library \"http://192.168.11.20:8080/#Calibreライブラリ\" \\\n --password-env CALIBRE_PASSWORD \\\n --query 'series:\"中公文庫\"'\n\nGet one book by id (JSON):\n\nnode skills/calibre-catalog-read/scripts/calibredb_read.mjs id \\\n --with-library \"http://192.168.11.20:8080/#Calibreライブラリ\" \\\n --password-env CALIBRE_PASSWORD \\\n --book-id 3\n\nRun one-book pipeline (analyze + comments HTML apply + cache):\n\nuv run python skills/calibre-catalog-read/scripts/run_analysis_pipeline.py \\\n --with-library \"http://192.168.11.20:8080/#Calibreライブラリ\" \\\n --password-env CALIBRE_PASSWORD \\\n --book-id 3 --lang ja" }, { "title": "Cache DB", "body": "Initialize DB schema:\n\nuv run python skills/calibre-catalog-read/scripts/analysis_db.py init \\\n --db skills/calibre-catalog-read/state/calibre_analysis.sqlite\n\nCheck current hash state:\n\nuv run python skills/calibre-catalog-read/scripts/analysis_db.py status \\\n --db skills/calibre-catalog-read/state/calibre_analysis.sqlite \\\n --book-id 3 --format EPUB" }, { "title": "Main vs Subagent responsibility (strict split)", "body": "Use this split to avoid long blocking turns on chat listeners." }, { "title": "Main agent (fast control plane)", "body": "Validate user intent and target book_id.\nConfirm subagent runtime knobs: model, thinking, runTimeoutSeconds.\nStart subagent and return a short progress reply quickly.\nAfter subagent result arrives, run DB upsert + Calibre apply.\nReport final result to user." }, { "title": "Subagent (heavy analysis plane)", "body": "Read extracted source payload.\nGenerate analysis JSON strictly by schema.\nDo not run metadata apply or user-facing channel actions." }, { "title": "Never do in main when avoidable", "body": "Long-form content analysis generation.\nMulti-step heavy reasoning over full excerpts." }, { "title": "Turn policy", "body": "One book per run.\nPrefer asynchronous flow: quick ack first, final result after analysis.\nIf analysis is unavailable, either ask user or use fallback only when explicitly acceptable." }, { "title": "Subagent pre-flight (required)", "body": "Before first subagent run in a session, confirm once:\n\nmodel\nthinking (low/medium/high)\nrunTimeoutSeconds\n\nDo not ask on every run. Reuse the confirmed settings for subsequent books in the same session unless the user asks to change them." }, { "title": "Subagent support (model-agnostic)", "body": "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.\n\nPrompt template: references/subagent-analysis.prompt.md\nInput schema: references/subagent-input.schema.json\nOutput schema: references/subagent-analysis.schema.json\nInput preparation helper: scripts/prepare_subagent_input.mjs\n\nSplits extracted text into multiple files to avoid read-tool single-line size issues.\n\nRules:\n\nUse subagent only for heavy analysis generation; keep main agent lightweight and non-blocking.\nIn this environment, Python commands must use uv run python.\nUse the strict prompt template (references/subagent-analysis.prompt.md) as mandatory base; do not send ad-hoc relaxed read instructions.\nKeep final DB upsert and Calibre metadata apply in main agent.\nProcess one book per run.\nConfirm model/thinking/timeout once per session, then reuse; do not hardcode provider-specific model IDs in the skill.\nConfigure callback/announce behavior and rate-limit fallbacks using OpenClaw default model/subagent/fallback settings (not hardcoded in this skill).\nExclude manga/comic-centric books from this text pipeline (skip when title/tags indicate manga/comic).\nIf extracted text is too short, stop and ask user for confirmation before continuing.\n\nThe pipeline returns reason: low_text_requires_confirmation with prompt_en text." }, { "title": "Language policy", "body": "Do not hardcode user-language prose in pipeline scripts.\nGenerate user-visible analysis text from subagent output, with language controlled by user-selected settings and lang input.\nFallback local analysis in scripts is generic/minimal; preferred path is subagent output following the prompt template." }, { "title": "Orchestration note (important)", "body": "run_analysis_pipeline.py is a local script and does not call OpenClaw tools by itself.\nSubagent execution must be orchestrated by the agent layer using sessions_spawn.\n\nRequired runtime sequence:\n\nMain agent prepares subagent_input.json + chunked source_files from extracted text.\n\nUse:\n\nnode skills/calibre-catalog-read/scripts/prepare_subagent_input.mjs \\\n --book-id --title \"\" --lang ja \\\n --text-path /tmp/book_<id>.txt --out-dir /tmp/calibre_subagent_<id>\n\n\nMain agent uses the shared builder skill subagent-spawn-command-builder to generate the sessions_spawn payload, then calls sessions_spawn.\n\nBuild with profile calibre-read and run-specific analysis task text.\nUse the generated JSON as-is (or merge minimal run-specific fields such as label/task text).\n\n\nSubagent reads all source_files and returns analysis JSON (schema-conformant).\nMain agent passes that file via --analysis-json to run_analysis_pipeline.py for DB/apply.\n\nIf step 2 is skipped, pipeline falls back to local minimal analysis (only for emergency/testing)." }, { "title": "Chat execution model (required, strict)", "body": "For Discord/chat, always run as two separate turns." }, { "title": "Turn A: start only (must be fast)", "body": "Select one target book.\nBuild spawn payload with subagent-spawn-command-builder (--profile calibre-read + run-specific --task).\nCall sessions_spawn using that payload.\nRecord run state (runId) via run_state.mjs upsert.\nReply to user with selected title + \"running in background\".\nStop turn here." }, { "title": "Turn B: completion only (separate later turn)", "body": "Trigger: completion announce/event for that run.\n\nRun one command only (completion handler):\n\nscripts/handle_completion.mjs (get -> apply -> remove, and fail on error).\n\n\nIf runId is missing, handler returns stale_or_duplicate and does nothing.\nSend completion/failure reply from handler result.\n\nHard rule:\n\nNever poll/wait/apply in Turn A.\nNever keep a chat listener turn open waiting for subagent completion." }, { "title": "Run state management (single-file, required)", "body": "For one-book-at-a-time operation, keep a single JSON state file:\n\nskills/calibre-catalog-read/state/runs.json\n\nUse runId as the primary key (subagent execution id).\n\nLifecycle:\n\nOn spawn acceptance, upsert one record:\n\nrunId, book_id, title, status: \"running\", started_at\n\n\nDo not wait/poll inside the same chat turn.\nOn completion announce, load record by runId and run apply.\nOn successful apply, delete that record immediately.\nOn failure, set status: \"failed\" + error and keep record for retry/debug.\n\nRules:\n\nKeep this file small and operational (active/failed records only).\nIgnore duplicate completion events when record is already removed.\nIf record is missing at completion time, report as stale/unknown run and do not apply blindly.\n\nUse helper scripts (avoid ad-hoc env var mistakes):\n\n# Turn A: register running task\nnode skills/calibre-catalog-read/scripts/run_state.mjs upsert \\\n --state skills/calibre-catalog-read/state/runs.json \\\n --run-id <RUN_ID> --book-id <BOOK_ID> --title \"<TITLE>\"\n\n# Turn B: completion handler (preferred)\nnode skills/calibre-catalog-read/scripts/handle_completion.mjs \\\n --state skills/calibre-catalog-read/state/runs.json \\\n --run-id <RUN_ID> \\\n --analysis-json /tmp/calibre_<BOOK_ID>/analysis.json \\\n --with-library \"http://HOST:PORT/#LIBRARY_ID\" \\\n --password-env CALIBRE_PASSWORD --lang ja" } ], "body": "calibre-catalog-read\n\nUse this skill for:\n\nRead-only catalog lookup (list/search/id)\nOne-book AI reading workflow (export -> analyze -> cache -> comments HTML apply)\nRequirements\ncalibredb available on PATH in the runtime where scripts are executed.\nebook-convert available for text extraction.\nsubagent-spawn-command-builder installed (for spawn payload generation).\nReachable Calibre Content server URL in --with-library format:\nhttp://HOST:PORT/#LIBRARY_ID\nDo not assume localhost/127.0.0.1; always pass explicit reachable HOST:PORT.\nIf auth is enabled:\nPreferred: set in /home/altair/.openclaw/.env\nCALIBRE_USERNAME=<user>\nCALIBRE_PASSWORD=<password>\nThen pass only --password-env CALIBRE_PASSWORD (username auto-loads from env)\nYou can still override with --username <user> explicitly.\nOptional auth cache file: ~/.config/calibre-catalog-read/auth.json\nAvoid --save-plain-password unless explicitly requested.\nCommands\n\nList books (JSON):\n\nnode skills/calibre-catalog-read/scripts/calibredb_read.mjs list \\\n --with-library \"http://192.168.11.20:8080/#Calibreライブラリ\" \\\n --password-env CALIBRE_PASSWORD \\\n --limit 50\n\n\nSearch books (JSON):\n\nnode skills/calibre-catalog-read/scripts/calibredb_read.mjs search \\\n --with-library \"http://192.168.11.20:8080/#Calibreライブラリ\" \\\n --password-env CALIBRE_PASSWORD \\\n --query 'series:\"中公文庫\"'\n\n\nGet one book by id (JSON):\n\nnode skills/calibre-catalog-read/scripts/calibredb_read.mjs id \\\n --with-library \"http://192.168.11.20:8080/#Calibreライブラリ\" \\\n --password-env CALIBRE_PASSWORD \\\n --book-id 3\n\n\nRun one-book pipeline (analyze + comments HTML apply + cache):\n\nuv run python skills/calibre-catalog-read/scripts/run_analysis_pipeline.py \\\n --with-library \"http://192.168.11.20:8080/#Calibreライブラリ\" \\\n --password-env CALIBRE_PASSWORD \\\n --book-id 3 --lang ja\n\nCache DB\n\nInitialize DB schema:\n\nuv run python skills/calibre-catalog-read/scripts/analysis_db.py init \\\n --db skills/calibre-catalog-read/state/calibre_analysis.sqlite\n\n\nCheck current hash state:\n\nuv run python skills/calibre-catalog-read/scripts/analysis_db.py status \\\n --db skills/calibre-catalog-read/state/calibre_analysis.sqlite \\\n --book-id 3 --format EPUB\n\nMain vs Subagent responsibility (strict split)\n\nUse this split to avoid long blocking turns on chat listeners.\n\nMain agent (fast control plane)\nValidate user intent and target book_id.\nConfirm subagent runtime knobs: model, thinking, runTimeoutSeconds.\nStart subagent and return a short progress reply quickly.\nAfter subagent result arrives, run DB upsert + Calibre apply.\nReport final result to user.\nSubagent (heavy analysis plane)\nRead extracted source payload.\nGenerate analysis JSON strictly by schema.\nDo not run metadata apply or user-facing channel actions.\nNever do in main when avoidable\nLong-form content analysis generation.\nMulti-step heavy reasoning over full excerpts.\nTurn policy\nOne book per run.\nPrefer asynchronous flow: quick ack first, final result after analysis.\nIf analysis is unavailable, either ask user or use fallback only when explicitly acceptable.\nSubagent pre-flight (required)\n\nBefore first subagent run in a session, confirm once:\n\nmodel\nthinking (low/medium/high)\nrunTimeoutSeconds\n\nDo not ask on every run. Reuse the confirmed settings for subsequent books in the same session unless the user asks to change them.\n\nSubagent support (model-agnostic)\n\nBook-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.\n\nPrompt template: references/subagent-analysis.prompt.md\nInput schema: references/subagent-input.schema.json\nOutput schema: references/subagent-analysis.schema.json\nInput preparation helper: scripts/prepare_subagent_input.mjs\nSplits extracted text into multiple files to avoid read-tool single-line size issues.\n\nRules:\n\nUse subagent only for heavy analysis generation; keep main agent lightweight and non-blocking.\nIn this environment, Python commands must use uv run python.\nUse the strict prompt template (references/subagent-analysis.prompt.md) as mandatory base; do not send ad-hoc relaxed read instructions.\nKeep final DB upsert and Calibre metadata apply in main agent.\nProcess one book per run.\nConfirm model/thinking/timeout once per session, then reuse; do not hardcode provider-specific model IDs in the skill.\nConfigure callback/announce behavior and rate-limit fallbacks using OpenClaw default model/subagent/fallback settings (not hardcoded in this skill).\nExclude manga/comic-centric books from this text pipeline (skip when title/tags indicate manga/comic).\nIf extracted text is too short, stop and ask user for confirmation before continuing.\nThe pipeline returns reason: low_text_requires_confirmation with prompt_en text.\nLanguage policy\nDo not hardcode user-language prose in pipeline scripts.\nGenerate user-visible analysis text from subagent output, with language controlled by user-selected settings and lang input.\nFallback local analysis in scripts is generic/minimal; preferred path is subagent output following the prompt template.\nOrchestration note (important)\n\nrun_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.\n\nRequired runtime sequence:\n\nMain agent prepares subagent_input.json + chunked source_files from extracted text.\nUse:\nnode skills/calibre-catalog-read/scripts/prepare_subagent_input.mjs \\\n --book-id <id> --title \"<title>\" --lang ja \\\n --text-path /tmp/book_<id>.txt --out-dir /tmp/calibre_subagent_<id>\n\nMain agent uses the shared builder skill subagent-spawn-command-builder to generate the sessions_spawn payload, then calls sessions_spawn.\nBuild with profile calibre-read and run-specific analysis task text.\nUse the generated JSON as-is (or merge minimal run-specific fields such as label/task text).\nSubagent reads all source_files and returns analysis JSON (schema-conformant).\nMain agent passes that file via --analysis-json to run_analysis_pipeline.py for DB/apply.\n\nIf step 2 is skipped, pipeline falls back to local minimal analysis (only for emergency/testing).\n\nChat execution model (required, strict)\n\nFor Discord/chat, always run as two separate turns.\n\nTurn A: start only (must be fast)\nSelect one target book.\nBuild spawn payload with subagent-spawn-command-builder (--profile calibre-read + run-specific --task).\nCall sessions_spawn using that payload.\nRecord run state (runId) via run_state.mjs upsert.\nReply to user with selected title + \"running in background\".\nStop turn here.\nTurn B: completion only (separate later turn)\n\nTrigger: completion announce/event for that run.\n\nRun one command only (completion handler):\nscripts/handle_completion.mjs (get -> apply -> remove, and fail on error).\nIf runId is missing, handler returns stale_or_duplicate and does nothing.\nSend completion/failure reply from handler result.\n\nHard rule:\n\nNever poll/wait/apply in Turn A.\nNever keep a chat listener turn open waiting for subagent completion.\nRun state management (single-file, required)\n\nFor one-book-at-a-time operation, keep a single JSON state file:\n\nskills/calibre-catalog-read/state/runs.json\n\nUse runId as the primary key (subagent execution id).\n\nLifecycle:\n\nOn spawn acceptance, upsert one record:\nrunId, book_id, title, status: \"running\", started_at\nDo not wait/poll inside the same chat turn.\nOn completion announce, load record by runId and run apply.\nOn successful apply, delete that record immediately.\nOn failure, set status: \"failed\" + error and keep record for retry/debug.\n\nRules:\n\nKeep this file small and operational (active/failed records only).\nIgnore duplicate completion events when record is already removed.\nIf record is missing at completion time, report as stale/unknown run and do not apply blindly.\n\nUse helper scripts (avoid ad-hoc env var mistakes):\n\n# Turn A: register running task\nnode skills/calibre-catalog-read/scripts/run_state.mjs upsert \\\n --state skills/calibre-catalog-read/state/runs.json \\\n --run-id <RUN_ID> --book-id <BOOK_ID> --title \"<TITLE>\"\n\n# Turn B: completion handler (preferred)\nnode skills/calibre-catalog-read/scripts/handle_completion.mjs \\\n --state skills/calibre-catalog-read/state/runs.json \\\n --run-id <RUN_ID> \\\n --analysis-json /tmp/calibre_<BOOK_ID>/analysis.json \\\n --with-library \"http://HOST:PORT/#LIBRARY_ID\" \\\n --password-env CALIBRE_PASSWORD --lang ja" }, "trust": { "sourceLabel": "tencent", "provenanceUrl": "https://clawhub.ai/NEXTAltair/calibre-catalog-read", "publisherUrl": "https://clawhub.ai/NEXTAltair/calibre-catalog-read", "owner": "NEXTAltair", "version": "1.0.5", "license": null, "verificationStatus": "Indexed source record" }, "links": { "detailUrl": "https://openagent3.xyz/skills/calibre-catalog-read", "downloadUrl": "https://openagent3.xyz/downloads/calibre-catalog-read", "agentUrl": "https://openagent3.xyz/skills/calibre-catalog-read/agent", "manifestUrl": "https://openagent3.xyz/skills/calibre-catalog-read/agent.json", "briefUrl": "https://openagent3.xyz/skills/calibre-catalog-read/agent.md" } }