calibre-metadata-apply

一项用于更新现有 Calibre 图书元数据的技能。

技能选择契约（严格）

• 若用户意图是编辑/修正/更新元数据，本技能为必需项。
• 若请求中同时提及 ID 与编辑/修正/更新意图（例如：ID1011 タイトル修正、ID1011 のタイトルを直して），本技能为必需项。
• 若请求中仅提及 ID，且目的仅为查看/核对/确认（例如：ID1021 を確認して、ID1021 の詳細），请 勿使用 本技能 —— 应路由至 calibre-catalog-read。
• calibre-catalog-read 不得用于任何具有编辑意图的请求。

当用户提出以下任一请求时，请使用本技能：

• “按 ID 修改标题”
• “元数据编辑”
• title/authors/series/series_index/tags/publisher/pubdate/languages 等字段的更新

请 勿 在以下场景中使用本技能：

• 只读查询（例如：“确认 ID 1021”、“显示 ID 1021 的信息”、“show me book 1021”）
• 仅检查某本书当前元数据内容而无修改意图
• 上述场景必须使用 calibre-catalog-read

运行要求

• 运行环境中 PATH 必须可访问 calibredb
• 需安装 subagent-spawn-command-builder（用于生成 spawn 负载）
• pdffonts 为可选/推荐组件，用于 PDF 证据校验
• 需可达 Calibre 内容服务器 URL
  • http://HOST:PORT/#LIBRARY_ID
  • 若 LIBRARY_ID 未知，可使用一次 #- 查询服务器上可用的 ID 列表。
• --with-library 参数可省略的前提是满足以下任一配置：
  • 环境变量：CALIBRE_WITH_LIBRARY 或 CALIBRE_LIBRARY_URL 或 CALIBRE_CONTENT_SERVER_URL
  • 可选的图书馆 ID 补全配置：CALIBRE_LIBRARY_ID
• 请查阅 TOOLS.md 中 “Calibre Content Server” 章节，以获取正确的 --with-library URL。
• 主机故障转移（IP 变更弹性支持）：
  • 可选环境变量：CALIBRE_SERVER_HOSTS=host1,host2,...
  • 脚本将自动尝试候选主机，包括从 /etc/resolv.conf 中提取的 WSL 主机侧 nameserver。
• 若启用了身份验证，优先使用 /home/altair/.openclaw/.env 文件：
  • CALIBRE_USERNAME=
  • CALIBRE_PASSWORD=
• 本工作流的身份验证方案策略：
  • 非 SSL 部署默认采用 Digest 认证方式。
  • 不得显式传入认证模式参数（如 --auth-mode / --auth-scheme）。
• 请传入 --password-env CALIBRE_PASSWORD（用户名将自动从环境变量加载）
• 仍可通过 --username 显式覆盖用户名。

支持的字段

直接字段（对应 set_metadata --field）

• title
• title_sort
• authors（字符串，支持 & 分隔；或数组格式）
• author_sort
• series
• series_index
• tags（字符串或数组）
• publisher
• pubdate（格式为 YYYY-MM-DD）
• languages
• comments

辅助字段

• comments_html（OC 标记块 upsert）
• analysis（自动生成用于 comments 的分析 HTML）
• analysis_tags（追加标签）
• tags_merge（默认值为 true）
• tags_remove（合并后移除指定标签）

必需执行流程

A. 目标确认（强制）

1. 执行只读查询以缩小候选范围
2. 展示 id,title,authors,series,series_index 字段
3. 获取用户对最终目标 ID 的确认
4. 仅基于已确认的 ID 构建 JSONL

B. 提案合成（当元数据缺失时）

1. 从文件抽取 + Web 来源收集证据
2. 展示一张合并提案表格，包含：
   • candidate、source、confidence (high|medium|low)
   • title_sort_candidate、author_sort_candidate
3. 获取用户决策：
   • approve all
   • approve only:
   • reject:
   • edit: =
4. 仅应用经批准/最终确定的字段
5. 若置信度低或来源冲突，则保留字段为空

C. 执行应用

1. 首先执行 dry-run（强制）
2. 仅在获得用户明确批准后，才执行 --apply
3. 重新读取并报告最终值

分析工作器策略

• 使用 subagent-spawn-command-builder 为繁重的候选生成任务生成 sessions_spawn 负载
  • task 字段为必需项。
  • Profile 应包含该工作流所需的模型/思考逻辑/超时/清理配置。
• 分析阶段应使用轻量级子代理模型（避免主重型模型）
• 最终决策及 dry-run/apply 操作保留在主会话中

数据流向披露

• 本地执行：
  • 基于 JSONL 构建 calibredb set_metadata 命令。
  • 读写本地状态文件（state/runs.json）。
• 子代理执行（可选，用于繁重候选生成）：
  • 通过 subagent-spawn-command-builder 使用 sessions_spawn。
  • 发送至子代理的文本/元数据可能到达运行时 profile 所配置的模型端点。
• 远程写入：
  • calibredb set_metadata 将更新目标 Calibre 内容服务器上的元数据。

安全规则：

• 优先使用基于环境变量的密码（--password-env CALIBRE_PASSWORD），而非内联参数 --password。
• 若用户不希望外部模型/子代理参与处理，则保持流程本地化，跳过子代理编排。
• 在 agent/chat 执行中，禁止直接调用 calibredb 进行编辑操作。
  • 必须始终执行 node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs。
• 切勿从此技能中启动 calibre-server。
  • 本工作流始终面向一个已运行的 Calibre 内容服务器。

连接引导（强制）

• 请勿首先向用户询问 --with-library 参数。
• 应优先使用已保存的默认配置（环境变量），不显式指定 --with-library。
  • 脚本将自动加载 .env 并解析 CALIBRE_WITH_LIBRARY / CALIBRE_CONTENT_SERVER_URL。
• 仅当命令输出显示连接未解析时（例如出现以下提示），才向用户询问 URL：
  • missing --with-library
  • unable to resolve usable --with-library
  • 对所有候选主机重复连接失败

长时运行的分轮次策略（全库级）

针对全库级繁重处理，必须始终采用分轮次（turn-split）执行方式。

未知文档恢复流程（M3）

批量处理尺寸规则：

• 每个未知文档批次应足够小，确保可在聊天界面中完整逐行展示结果（不可采样代表）。
• 若仍有未解决项，应立即停止并等待用户明确指令，再启动下一批次。

用户干预检查点（固定）

1. 轻量扫描（仅元数据）

   • 默认始终执行此阶段（无需额外用户指令）
   • 仅分析现有元数据（不读取文件内容）
   • 向用户呈现一张表格，包含：
     • 当前文件名/标题
     • 推荐的标题/元数据
     • 置信度/证据摘要
   • 在进入任何更深层阶段前，暂停并等待用户指令

2. 用户请求时：第一页扫描

   • 仅读取第一页内容，并优化提案
   • 报告与轻量扫描阶段的差异

3. 若仍不确定：深度扫描

   • 读取前 5 页 + 后 5 页
   • 增加 Web 证据搜索
   • 产出含置信度与推理依据的最终提案

4. 审批关卡

   • 展示详细发现，并在应用前请求用户明确批准

待处理与不支持项的处理

• 对未解决/搁置项使用 pending-review 标签。
• 若文档在当前流程中仍未解决，不得强行猜测元数据。
  • 标注 pending-review 并留待后续调查。

差异报告格式（适用于未知文档批次运行）

返回完整结果（非抽样）：

• 执行摘要（目标数/已变更数/待处理数/跳过数/错误数）
• 完整变更列表，含 id 及各字段变更前/后值
• 完整待处理列表，含 id 及原因
• 完整错误列表，含 id 及错误摘要
• 置信度必须表示为 high|medium|low

运行时产物策略

• 仅在运行进行中时保留运行状态与临时产物。
• 成功完成后，清除本次运行的状态/产物。
• 失败时，仅保留最小必要产物用于重试/调试，并在问题解决后立即清理。

内部编排（推荐）

• 所有分析阶段均使用轻量级子代理
• 应用决策保留在主会话中
• 各阶段的运行状态持久化至 state/runs.json

第一轮（启动）

1. 主会话定义作用域
2. 主会话通过 subagent-spawn-command-builder（示例 profile：calibre-meta）生成 spawn 负载，随后调用 sessions_spawn
3. 通过 scripts/run_state.mjs upsert 保存 run_id/session_key/task
4. 立即告知用户这是一项子代理任务，并说明所使用的分析执行模型
5. 回复 “analysis started”，同时保持常规聊天响应能力

第二轮（完成）

1. 接收子代理完成通知
2. 保存结果 JSON
3. 通过 scripts/handle_completion.mjs --run-id ... --result-json ... 完成状态处理
4. 返回汇总提案（仅在需要时执行应用）

运行状态文件：

• state/runs.json

PDF 抽取策略

1. 优先尝试 ebook-convert
2. 若结果为空或失败，则回退至 pdftotext
3. 若两者均失败，则切换至 Web 证据优先模式

排序读音策略

• 对日文/非拉丁语系的排序字段，使用用户配置的 reading_script
  • katakana / hiragana / latin
• 首次使用时询问一次，之后在会话中复用
• 默认策略为完整读音（不截断）
• 请查阅 TOOLS.md 中 “Calibre Content Server” 章节，获取已配置的 reading_script 值；如需，应作为 CLI 参数传入。

用法

Dry-run：

cat changes.jsonl | node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs 
  --with-library "http://127.0.0.1:8080/#MyLibrary" 
  --password-env CALIBRE_PASSWORD 
  --lang ja

Dry-run（当默认图书馆已通过环境变量/配置预设时）：

cat changes.jsonl | node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs 
  --password-env CALIBRE_PASSWORD 
  --lang ja

Apply：

cat changes.jsonl | node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs 
  --with-library "http://127.0.0.1:8080/#MyLibrary" 
  --password-env CALIBRE_PASSWORD 
  --apply

禁止事项

• 禁止仅依赖模糊标题匹配执行直接 --apply
• 禁止在 apply 负载中包含未经确认的 ID
• 禁止在无用户明确确认的情况下，自动填充低置信度候选值
• 禁止基于猜测路径（如 ~/Calibre Library）启动本地服务器