開発book-knowledge-base

半導体テーマの参考書（紙書籍・554ページ・ダイヤモンド社）を裁断スキャンしたPDFを、朝のうちにyomitokuでOCRして蔵書DBに取り込んだ。OCRそのものより、「DBに見つからない→PDF実体を引き当てる→ドキュメントと実装の不一致を踏む→直す」の道のりに時間がかかった一日。

蔵書DBに無い、を確定させる

まず、半導体テーマの参考書を蔵書DB（Turso）で検索してもらったが、ヒットしなかった。著者名のキーワードでも引っかからず、kindle_library 側にも該当ASINがない。電子版は持っていなかった。

紙の現物は裁断してスキャン済みのはずなので、amazon_metadata の file_no を頼りに Dropbox の「電子化した書籍たち/00連番で管理するフォルダ/」配下を引いた。No858_... 配下にPDF実体が眠っていた。蔵書DB側のメタデータは Amazon 購入履歴から取り込んでいるので、現物のPDFと file_no を紐付けるだけで居場所が確定する。この設計がここで初めて効いた。

目次だけ pymupdf で抜く

PDF全体を読ませると Read ツールが死ぬので、pymupdf で先頭の目次部分だけ抽出してもらった。8部構成、本文54章、序章と後付を含めて554ページ。book_id を chip-war に決めて、yomitoku をバックグラウンドで起動した。

554ページなら30〜60分は覚悟していたが、実際は 約8.6分でOCR完走した。MD 554個と図ファイル5個が出力ディレクトリに並んでいる。図ファイルは figure_xxx.png のような連番なので、yomitoku のリネームヘルパで整えてもらった。

ドキュメントと実装が食い違っていた

リネームが終わって「次はDB格納」の段で詰まった。/yomitoku コマンドのドキュメントには、

init_books_db(db_path) で初期化してから書き込む

と書いてある。しかし現状の db.py を覗いてもらうと、引数なしの init_books_db() で Turso に HTTP 直結する実装に変わっていた。ローカルSQLiteを叩く時代のドキュメントが、そのまま残されていた格好。

コマンドドキュメントを信じて手を動かすと、実装と食い違って事故るので、先に .claude/commands/yomitoku.md を現状の API シグネチャに合わせて直してもらった。バッチ運用節も「HTTP直結デフォルト」に書き換える。「スキルやコマンドのドキュメントは、実装を変えた瞬間に取り残される」という、ありふれた失敗を踏み抜いた格好。db.py の関数シグネチャを見るまで誰も気付かなかった。

このあたりは、/yomitoku を月に何度も叩くわけではないので、たまに走らせたときに足元のドキュメントが古くなっている、というパターンに弱い。今後も同じ事故を踏みそうなので、「ドキュメントの最終更新日と実装の最終更新日が乖離していたら、まず突き合わせる」という運用に倒したい。

Turso 投入と検索テスト

ドキュメントを直したあと、Turso に流し込んでもらった。121チャンクで格納完了。amazon_metadata との紐付けも file_no 経由で通り、FTS検索（全文検索）でキーワードを叩くとどれも本文にヒットする。少なくともインデックスはちゃんと張れている。

ここで「restructure はやってないんでしたっけ？ あと表示確認お願いします」と差し戻しが入った。restructure（章単位への再構成）はまだで、OCR→DB格納の状態で止めていた。表示確認を後回しにしていたので、先にローカルの dev server を 3100 ポートで起動して、Chrome DevTools MCP でブラウザを開いて確認してもらった。フロントから書籍ページを開くと、Turso 経由のチャンク本文と図画像が描画されている。動いている。

restructure で 121 → 117 チャンクへ

表示確認が通ったあとに /restructure-book を回した。目次から拾った構造を当てる作業。

8部構成・全54章＋序章・後付

本文54章は yomitoku の段階で既に「1チャンク=1章」に整っていたので、restructure 側の仕事はほぼ メタデータ正規化＋目次5チャンクの統合で済んだ。121チャンクが117チャンクに縮む。各チャンクに chapter（部）と section（章タイトル）を割り当て、目次部分の細切れチャンクを1つにまとめただけ。

121 → 117 チャンク（▲4）
内訳: 目次5チャンクを1つに統合
     + 本文54章は構造そのまま、メタデータのみ整備

restructure 完了後にもう一度ブラウザで開くと、章タイトルが部単位でグルーピングされて見える。半導体産業の歴史を追う読みものなので、章のまとまりが見えるかどうかで読書UIの当たりが大きく変わる。

今日の学び

  • DBに無い書籍はAmazonメタデータの file_no でPDF実体を引ける。kindle_library を先に当てる癖がついていたが、紙書籍は最初から amazon_metadata を見ればよかった。
  • yomitoku は思っていたより速い。554ページが約8.6分。30〜60分の見積もりは現代のyomitokuには過大だった。次回からは10分前後を基準に据える。
  • スラッシュコマンドのドキュメントは、実装を直したら同時に直す。今回は db.py が引数なし＋Turso直結に変わっていたのに、コマンドドキュメントが古い API のまま残っていた。/yomitoku を叩いたタイミングで踏み抜いて、ようやく気付いた。仕様変更の PR でドキュメントだけ漏れる事故は今後も起きるので、コマンド系のドキュメントは「実装と同時に直す」を運用ルールにしたい。
  • restructure の仕事量は yomitoku の出力品質に強く依存する。今回は yomitoku が章単位できれいに切ってくれていたので、restructure はメタデータを当てるだけで済んだ。逆に章境界が崩れていると restructure 側で章をマージする仕事が増える。yomitoku 側のチャンク分割設定が将来の restructure の負荷を決めている、という構造を体感できた。

取り込みパイプラインの位置づけ

朝の作業の流れを並べると、

  1. 蔵書DBで検索 → ヒットせず
  2. amazon_metadata.file_no から PDF 実体を特定
  3. pymupdf で目次だけ抜いて書誌情報確定
  4. yomitoku をバックグラウンドで起動（約8.6分でOCR完了）
  5. 図ファイルをリネーム
  6. /yomitoku のドキュメントが旧仕様だと気付いて修正
  7. Turso に 121チャンクで投入、FTS検索を確認
  8. dev server で表示確認
  9. /restructure-book で 117チャンクに整理、メタデータ正規化

の9ステップ。半分が「PDF実体を引き当てる」と「ドキュメントを直す」の段取り仕事で、OCR本体は8.6分しか喰っていない。OCRが速くなった分、前後の段取りが律速になり始めている。

次に紙書籍を取り込むときは、

  • 最初から amazon_metadata.file_no で PDF を引く（kindle_library は飛ばす）
  • /yomitoku を走らせる前に .claude/commands/yomitoku.md と db.py の最終更新日を突き合わせる
  • OCR起動からDB投入までを30分以内の段取りに収める

の3点をルーチンにしたい。一冊が30分で蔵書DBに乗るなら、買い溜めしてある紙書籍を週末に5冊くらい一気に流せる目算が立つ。