{
  "schemaVersion": "1.0",
  "item": {
    "slug": "calibre-metadata-apply",
    "name": "Calibre Metadata Apply",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/NEXTAltair/calibre-metadata-apply",
    "canonicalUrl": "https://clawhub.ai/NEXTAltair/calibre-metadata-apply",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/calibre-metadata-apply",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=calibre-metadata-apply",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "README.md",
      "SKILL.md",
      "scripts/calibredb_apply.mjs",
      "scripts/handle_completion.mjs",
      "scripts/run_state.mjs"
    ],
    "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-metadata-apply"
    },
    "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-metadata-apply",
    "agentPageUrl": "https://openagent3.xyz/skills/calibre-metadata-apply/agent",
    "manifestUrl": "https://openagent3.xyz/skills/calibre-metadata-apply/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/calibre-metadata-apply/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-metadata-apply",
        "body": "A skill for updating metadata of existing Calibre books."
      },
      {
        "title": "Requirements",
        "body": "calibredb must be available on PATH in the runtime environment\nsubagent-spawn-command-builder installed (for spawn payload generation)\npdffonts is optional/recommended for PDF evidence checks\nReachable Calibre Content server URL\n\nhttp://HOST:PORT/#LIBRARY_ID\n\n\nIf authentication is enabled, prefer /home/altair/.openclaw/.env:\n\nCALIBRE_USERNAME=<user>\nCALIBRE_PASSWORD=<password>\n\n\nPass --password-env CALIBRE_PASSWORD (username auto-loads from env)\nYou can still override explicitly with --username <user>.\nOptional auth cache: --save-auth (default file: ~/.config/calibre-metadata-apply/auth.json)"
      },
      {
        "title": "Direct fields (set_metadata --field)",
        "body": "title\ntitle_sort\nauthors (string with & or array)\nauthor_sort\nseries\nseries_index\ntags (string or array)\npublisher\npubdate (YYYY-MM-DD)\nlanguages\ncomments"
      },
      {
        "title": "Helper fields",
        "body": "comments_html (OC marker block upsert)\nanalysis (auto-generates analysis HTML for comments)\nanalysis_tags (adds tags)\ntags_merge (default true)\ntags_remove (remove specific tags after merge)"
      },
      {
        "title": "A. Target confirmation (mandatory)",
        "body": "Run read-only lookup to narrow candidates\nShow id,title,authors,series,series_index\nGet user confirmation for final target IDs\nBuild JSONL using only confirmed IDs"
      },
      {
        "title": "B. Proposal synthesis (when metadata is missing)",
        "body": "Collect evidence from file extraction + web sources\nShow one merged proposal table with:\n\ncandidate, source, confidence (high|medium|low)\ntitle_sort_candidate, author_sort_candidate\n\n\nGet user decision:\n\napprove all\napprove only: <fields>\nreject: <fields>\nedit: <field>=<value>\n\n\nApply only approved/finalized fields\nIf confidence is low or sources conflict, keep fields empty"
      },
      {
        "title": "C. Apply",
        "body": "Run dry-run first (mandatory)\nRun --apply only after explicit user approval\nRe-read and report final values"
      },
      {
        "title": "Analysis worker policy",
        "body": "Use subagent-spawn-command-builder to generate sessions_spawn payload for heavy candidate generation\n\ntask is required.\nProfile should include model/thinking/timeout/cleanup for this workflow.\n\n\nUse lightweight subagent model for analysis (avoid main heavy model)\nKeep final decisions + dry-run/apply in main"
      },
      {
        "title": "Data flow disclosure",
        "body": "Local execution:\n\nBuild calibredb set_metadata commands from JSONL.\nRead/write local state files (state/runs.json) and optional auth/config files under ~/.config/calibre-metadata-apply/.\n\n\nSubagent execution (optional for heavy candidate generation):\n\nUses sessions_spawn via subagent-spawn-command-builder.\nText/metadata sent to subagent can reach model endpoints configured by runtime profile.\n\n\nRemote write:\n\ncalibredb set_metadata updates metadata on the target Calibre Content server.\n\nSecurity rules:\n\nDo not use --save-plain-password unless explicitly instructed by the user.\nPrefer env-based password (--password-env CALIBRE_PASSWORD) over inline --password.\nIf user does not want external model/subagent processing, keep flow local and skip subagent orchestration."
      },
      {
        "title": "Long-run turn-split policy (library-wide)",
        "body": "For library-wide heavy processing, always use turn-split execution."
      },
      {
        "title": "Unknown-document recovery flow (M3)",
        "body": "Batch sizing rule:\n\nKeep each unknown-document batch small enough to show full row-by-row results in chat (no representative sampling).\nIf unresolved items remain, stop and wait for explicit user instruction to start the next batch."
      },
      {
        "title": "User intervention checkpoints (fixed)",
        "body": "Light pass (metadata-only)\n\nAlways run this stage by default (no extra user instruction required)\nAnalyze existing metadata only (no file content read)\nPresent a table to user:\n\ncurrent file/title\nrecommended title/metadata\nconfidence/evidence summary\n\n\nStop and wait for user instruction before any deeper stage\n\n\n\nOn user request: page-1 pass\n\nRead only the first page and refine proposals\nReport delta from light pass\n\n\n\nIf still uncertain: deep pass\n\nRead first 5 pages + last 5 pages\nAdd web evidence search\nProduce finalized proposal with confidence + rationale\n\n\n\nApproval gate\n\nShow detailed findings and request explicit approval before apply"
      },
      {
        "title": "Pending and unsupported handling",
        "body": "Use pending-review tag for unresolved/hold items.\nIf document is unresolved in current flow, do not force metadata guesses.\n\nTag with pending-review and keep for follow-up investigation."
      },
      {
        "title": "Diff report format (for unknown batch runs)",
        "body": "Return full results (not samples):\n\nexecution summary (target/changed/pending/skipped/error)\nfull changed list with id + key before/after fields\nfull pending list with id + reason\nfull error list with id + error summary\nconfidence must be expressed as high|medium|low"
      },
      {
        "title": "Runtime artifact policy",
        "body": "Keep run-state and temporary artifacts only while a run is active.\nOn successful completion, remove per-run state/artifacts.\nOn failure, keep minimal artifacts only for retry/debug, then clean up after resolution."
      },
      {
        "title": "Internal orchestration (recommended)",
        "body": "Use lightweight subagent for all analysis stages\nKeep apply decisions in main session\nPersist run state for each stage in state/runs.json"
      },
      {
        "title": "Turn 1 (start)",
        "body": "Main defines scope\nMain generates spawn payload via subagent-spawn-command-builder (profile example: calibre-meta), then calls sessions_spawn\nSave run_id/session_key/task via scripts/run_state.mjs upsert\nImmediately tell the user this is a subagent job and state the execution model used for analysis\nReply with \"analysis started\" and keep normal chat responsive"
      },
      {
        "title": "Turn 2 (completion)",
        "body": "Receive subagent completion notice\nSave result JSON\nComplete state handling via scripts/handle_completion.mjs --run-id ... --result-json ...\nReturn summarized proposal (apply only when needed)\n\nRun state file:\n\nstate/runs.json"
      },
      {
        "title": "PDF extraction policy",
        "body": "Try ebook-convert first\nIf empty/failed, fallback to pdftotext\nIf both fail, switch to web-evidence-first mode"
      },
      {
        "title": "Sort reading policy",
        "body": "Use user-configured reading_script for Japanese/non-Latin sort fields\n\nkatakana / hiragana / latin\n\n\nAsk once on first use, then persist and reuse\nDefault policy is full reading (no truncation)\nConfig path: ~/.config/calibre-metadata-apply/config.json\n\nkey: reading_script"
      },
      {
        "title": "Usage",
        "body": "Dry-run:\n\ncat changes.jsonl | node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs \\\n  --with-library \"http://127.0.0.1:8080/#MyLibrary\" \\\n  --password-env CALIBRE_PASSWORD \\\n  --lang ja\n\nApply:\n\ncat changes.jsonl | node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs \\\n  --with-library \"http://127.0.0.1:8080/#MyLibrary\" \\\n  --password-env CALIBRE_PASSWORD \\\n  --apply"
      },
      {
        "title": "Do not",
        "body": "Do not run direct --apply using ambiguous title matches only\nDo not include unconfirmed IDs in apply payload\nDo not auto-fill low-confidence candidates without explicit confirmation"
      }
    ],
    "body": "calibre-metadata-apply\n\nA skill for updating metadata of existing Calibre books.\n\nRequirements\ncalibredb must be available on PATH in the runtime environment\nsubagent-spawn-command-builder installed (for spawn payload generation)\npdffonts is optional/recommended for PDF evidence checks\nReachable Calibre Content server URL\nhttp://HOST:PORT/#LIBRARY_ID\nIf authentication is enabled, prefer /home/altair/.openclaw/.env:\nCALIBRE_USERNAME=<user>\nCALIBRE_PASSWORD=<password>\nPass --password-env CALIBRE_PASSWORD (username auto-loads from env)\nYou can still override explicitly with --username <user>.\nOptional auth cache: --save-auth (default file: ~/.config/calibre-metadata-apply/auth.json)\nSupported fields\nDirect fields (set_metadata --field)\ntitle\ntitle_sort\nauthors (string with & or array)\nauthor_sort\nseries\nseries_index\ntags (string or array)\npublisher\npubdate (YYYY-MM-DD)\nlanguages\ncomments\nHelper fields\ncomments_html (OC marker block upsert)\nanalysis (auto-generates analysis HTML for comments)\nanalysis_tags (adds tags)\ntags_merge (default true)\ntags_remove (remove specific tags after merge)\nRequired execution flow\nA. Target confirmation (mandatory)\nRun read-only lookup to narrow candidates\nShow id,title,authors,series,series_index\nGet user confirmation for final target IDs\nBuild JSONL using only confirmed IDs\nB. Proposal synthesis (when metadata is missing)\nCollect evidence from file extraction + web sources\nShow one merged proposal table with:\ncandidate, source, confidence (high|medium|low)\ntitle_sort_candidate, author_sort_candidate\nGet user decision:\napprove all\napprove only: <fields>\nreject: <fields>\nedit: <field>=<value>\nApply only approved/finalized fields\nIf confidence is low or sources conflict, keep fields empty\nC. Apply\nRun dry-run first (mandatory)\nRun --apply only after explicit user approval\nRe-read and report final values\nAnalysis worker policy\nUse subagent-spawn-command-builder to generate sessions_spawn payload for heavy candidate generation\ntask is required.\nProfile should include model/thinking/timeout/cleanup for this workflow.\nUse lightweight subagent model for analysis (avoid main heavy model)\nKeep final decisions + dry-run/apply in main\nData flow disclosure\nLocal execution:\nBuild calibredb set_metadata commands from JSONL.\nRead/write local state files (state/runs.json) and optional auth/config files under ~/.config/calibre-metadata-apply/.\nSubagent execution (optional for heavy candidate generation):\nUses sessions_spawn via subagent-spawn-command-builder.\nText/metadata sent to subagent can reach model endpoints configured by runtime profile.\nRemote write:\ncalibredb set_metadata updates metadata on the target Calibre Content server.\n\nSecurity rules:\n\nDo not use --save-plain-password unless explicitly instructed by the user.\nPrefer env-based password (--password-env CALIBRE_PASSWORD) over inline --password.\nIf user does not want external model/subagent processing, keep flow local and skip subagent orchestration.\nLong-run turn-split policy (library-wide)\n\nFor library-wide heavy processing, always use turn-split execution.\n\nUnknown-document recovery flow (M3)\n\nBatch sizing rule:\n\nKeep each unknown-document batch small enough to show full row-by-row results in chat (no representative sampling).\nIf unresolved items remain, stop and wait for explicit user instruction to start the next batch.\nUser intervention checkpoints (fixed)\n\nLight pass (metadata-only)\n\nAlways run this stage by default (no extra user instruction required)\nAnalyze existing metadata only (no file content read)\nPresent a table to user:\ncurrent file/title\nrecommended title/metadata\nconfidence/evidence summary\nStop and wait for user instruction before any deeper stage\n\nOn user request: page-1 pass\n\nRead only the first page and refine proposals\nReport delta from light pass\n\nIf still uncertain: deep pass\n\nRead first 5 pages + last 5 pages\nAdd web evidence search\nProduce finalized proposal with confidence + rationale\n\nApproval gate\n\nShow detailed findings and request explicit approval before apply\nPending and unsupported handling\nUse pending-review tag for unresolved/hold items.\nIf document is unresolved in current flow, do not force metadata guesses.\nTag with pending-review and keep for follow-up investigation.\nDiff report format (for unknown batch runs)\n\nReturn full results (not samples):\n\nexecution summary (target/changed/pending/skipped/error)\nfull changed list with id + key before/after fields\nfull pending list with id + reason\nfull error list with id + error summary\nconfidence must be expressed as high|medium|low\nRuntime artifact policy\nKeep run-state and temporary artifacts only while a run is active.\nOn successful completion, remove per-run state/artifacts.\nOn failure, keep minimal artifacts only for retry/debug, then clean up after resolution.\nInternal orchestration (recommended)\nUse lightweight subagent for all analysis stages\nKeep apply decisions in main session\nPersist run state for each stage in state/runs.json\nTurn 1 (start)\nMain defines scope\nMain generates spawn payload via subagent-spawn-command-builder (profile example: calibre-meta), then calls sessions_spawn\nSave run_id/session_key/task via scripts/run_state.mjs upsert\nImmediately tell the user this is a subagent job and state the execution model used for analysis\nReply with \"analysis started\" and keep normal chat responsive\nTurn 2 (completion)\nReceive subagent completion notice\nSave result JSON\nComplete state handling via scripts/handle_completion.mjs --run-id ... --result-json ...\nReturn summarized proposal (apply only when needed)\n\nRun state file:\n\nstate/runs.json\nPDF extraction policy\nTry ebook-convert first\nIf empty/failed, fallback to pdftotext\nIf both fail, switch to web-evidence-first mode\nSort reading policy\nUse user-configured reading_script for Japanese/non-Latin sort fields\nkatakana / hiragana / latin\nAsk once on first use, then persist and reuse\nDefault policy is full reading (no truncation)\nConfig path: ~/.config/calibre-metadata-apply/config.json\nkey: reading_script\nUsage\n\nDry-run:\n\ncat changes.jsonl | node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs \\\n  --with-library \"http://127.0.0.1:8080/#MyLibrary\" \\\n  --password-env CALIBRE_PASSWORD \\\n  --lang ja\n\n\nApply:\n\ncat changes.jsonl | node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs \\\n  --with-library \"http://127.0.0.1:8080/#MyLibrary\" \\\n  --password-env CALIBRE_PASSWORD \\\n  --apply\n\nDo not\nDo not run direct --apply using ambiguous title matches only\nDo not include unconfirmed IDs in apply payload\nDo not auto-fill low-confidence candidates without explicit confirmation"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/NEXTAltair/calibre-metadata-apply",
    "publisherUrl": "https://clawhub.ai/NEXTAltair/calibre-metadata-apply",
    "owner": "NEXTAltair",
    "version": "1.0.1",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/calibre-metadata-apply",
    "downloadUrl": "https://openagent3.xyz/downloads/calibre-metadata-apply",
    "agentUrl": "https://openagent3.xyz/skills/calibre-metadata-apply/agent",
    "manifestUrl": "https://openagent3.xyz/skills/calibre-metadata-apply/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/calibre-metadata-apply/agent.md"
  }
}