0
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

【第1回】Windows用PDFユーティリティをCodexで開発し始めた――最初の仕様、APIエラー、EXE化

0
Last updated at Posted at 2026-11-16

シリーズ:Folimeld開発記録(全9回)

最終変更:2026年11月17日 17:02(日本時間)

この記事は、ChatGPTと壁打ちしながら作成しました。開発時の会話、Gitの変更履歴、ソースコードを調査した結果を含みます。

森を抜け、街にたどり着いた主人公(Lv1)。ひと息つく間もなく、通りをふさぐほど大きな青い花霊が現れました。とっさに杖を振ると、青い花びらが石畳に舞い散ります。右へ左へ、裏返しになったものまで。さて、これを一枚ずつ拾って、思いどおりの順番に並べ直せるでしょうか?

石畳の街角で、魔法使いが杖を構え、大きな青い花霊と向き合う

イメージイラスト「青い花霊と魔法使いの街角決戦」

これまで、自炊したPDFを用意するには、フリーのPDF編集ユーティリティやスクリプトを使っていました。見開きPDFビューアで読む環境を整えると、次は読む前のPDFを整える道具が欲しくなりました。

そこで、PDFのページをサムネイルで確認しながら、並べ替えたり回転させたりするデスクトップアプリを作りました。後に「Folimeld」と名付けたアプリです。Windows 11向けの「PDF Utility」としてCline・Gemmaで先行試作し、その後、VS CodeとOpenAI Codexで現在のコードにつながる開発を進めました。

なお、同等のアプリは、次の状況です。(2026年11月10日現在)

  • iPhone(iPhone Duo対応)/iPad/Mac用アプリ「見開きPDFユーティリティ(Mihiraki: PDF Utility)」はApp Storeで公開中です。

  • Android(スマートフォン・タブレット対応)/Chromebook用アプリは「見開きPDFユーティリティ(Mihiraki: PDF Utility)」で公開予定です。現在はクローズドテスト中です。多分Googlebookでも動きます。

Folimeldの配布状況(2026年11月17日確認)

Windowsで通常利用する方にはMicrosoft Store版をお薦めします。公開済みの1.0.1.0はx64版です。コードベース0.3.5・ARM64ネイティブ対応を含む次期Store版1.0.2.0は、11月16日の公開記録ではx64/ARM64の両パッケージを審査提出済みです。審査合格・配信完了は未確認で、公開済み版とは区別します。

GitHubでは、Windows x64/ARM64のDesktopインストーラー0.3.5.0、ソース+uv 0.3.5、uv tool install 0.3.5をプレリリースとして公開しています。筆者はこれらを上級者向けの追加配布経路と位置づけています。

Linux向けの配布物は、旧版0.3.3・0.3.4を含む全19件のGitHub Releasesがプレリリース(試験配布)です(11月17日確認)。Ubuntu/Debian、Fedora 44/45、AlmaLinux 9、openSUSE Leap 16.1・Tumbleweedはamd64/ARM64の0.3.5を公開しています。Kali 2026.3は、amd64がUbuntu/Debian/Kali共通のDEB、ARM64が専用DEBです。同日15時32分にはUbuntu 24.04.5 LTS amd64向けstrict Snap 0.3.5も試験公開されました。検証記録はWSL2/WSLgでのビルド・更新導入・プラグ接続とoffscreenでの起動・動作確認であり、通常画面での全操作確認とは区別します。Snapのgrade: stableはビルド時の設定で、GitHubの安定版分類を意味しません。(amd64 Snapの公開Release)BSDもFreeBSD 15.1・NetBSD 11.1・OpenBSD 8.0向けに、amd64版とARM64版の0.3.5をプレリリースとして公開しています(FreeBSDのパッケージ改訂は0.3.5_1)。amd64版は11月17日15時40分・15時44分・15時45分に順に公開され、更新導入とoffscreen起動の記録があります。通常画面での全編集操作や、設定・履歴を含む包括的な更新試験とは区別します。(FreeBSD・NetBSD・OpenBSD)macOSはApple Silicon向けHomebrew用ソース版0.3.5を公開しています。

配布先と対象OS・CPU、制約はGitHub Releasesを参照してください。Store初回公開は第5回、Windows試験配布と次期Store版は第6回、Linux・macOSは第7回、BSDは第8回で詳しく扱います。

この連載では、アプリの紹介だけでなく、実際の指示、生成されたコード、起きたエラー、修正の判断を開発履歴から振り返ります。第1回は8月23〜24日の先行試作と、8月28〜29日のCodex版が対象です。

本稿の主な対象期間:2026年8月23〜29日。補足では8月20日の従来スクリプトと、10月30日の環境点検も扱います。日時は日本時間です。

連載一覧

回 内容
第1回 Windows用PDFユーティリティをCodexで開発し始めた――最初の仕様、APIエラー、EXE化
第2回 PDF UtilityからFolimeldへ――改名とmacOS対応を進めた
第3回 Ubuntu対応とWSL2での検証――22.04でdebが動かなかった理由
第4回 MITのつもりがAGPL-3.0に――Store公開前に依存ライセンスを見直した
第5回 FolimeldをMicrosoft Storeで公開する――MSIXの準備・認定から配信版の実機確認まで(未公開)
第6回 FolimeldのWindows配布を広げる――試験配布・Antigravityへの引き継ぎと次期Store版(未公開)
第7回 FolimeldをLinux・macOSへ届ける――試験配布の拡大とビルド環境の整備(未公開)
第8回 FolimeldをBSDへ届ける――3つのOSでの移植・パッケージ化とARM64対応(未公開)
第9回 Folimeld開発を振り返る――生成AIが実装したこと、開発者が判断したこと(未公開)

第1・2回は先行試作、Codex版の開始、改名とmacOS対応を扱います。第3回のUbuntu対応(8月31日〜9月7日)と第4回のライセンス整備(8月29日・9月4〜9日)は、時期が重なるテーマ別の構成です。第5回はMSIXの準備から初回Store公開・配信版確認、第6回はその後のWindows試験配布・Antigravityへの引き継ぎと次期Store版を扱います。第7回はLinux・macOS向け配布とビルド環境、第8回はBSDの移植・パッケージ化とARM64対応を振り返ります。最終の第9回では、先行試作から公開・配布までを通して、生成AIが実装したことと開発者が判断・確認したことを整理します。

開発のきっかけと先行試作

きっかけは、自炊PDFを作るときの作業だった

このアプリを作り始めたときは、iOS用の「見開きPDFビューア」を開発し、試用を続けていました。そのために自炊したPDFを用意するときは、フリーのPDF編集ユーティリティと、PDFのプロパティを変更するスクリプトを組み合わせて使っていました。

手元に残るスクリプトでは、pikepdfを使ってPDFのPageLayoutとViewerPreferences.Directionを設定しています。見開き表示のレイアウトや綴じ方向を調整する処理です。この従来のスクリプトと、後にPyMuPDFで作るFolimeldは、使用ライブラリが異なります。

右綴じ設定スクリプトの参考資料は、PythonとpikepdfでPDFを右綴じ(R2L)にする(GitHub Gist)と、PDFの右綴じ変換アプリとプログラム(note)です。

そうした作業を続けるうちに、「PDF編集ユーティリティも生成AIで作れるのではないか」と考え、試してみることにしました。

目的の一つは、生成AIの実力を試すことでした。Cline・Gemmaによる試作ではフル仕様での完成を目指しましたが、期待した形まで仕上げられませんでした。仕様を減らしても開発を完了できず、Clineでの継続をあきらめ、Codexへ切り替えることにしました。

Codex版では、なるべく指示する内容を少なくし、必要最低限と考えた画面設計の仕様を渡す方針にしました。初めから多くの仕様を盛り込むと開発が難航するのではないか、という当時の考えです。

Android版ビューアの開発は、その後の2026年9月1日からです。本連載では、先行するiOS版の試用と区別し、ビューアの実装自体は扱いません。

Codexの前に、ClineとGemmaで試作していた

8月23日15時51分、Clineに「PDF Utilityを開発します」と依頼しました。24日までの関連タスクは12件で、保存メタデータはプロバイダーlmstudio、モデルIDgoogle/gemma-4-26b-a4b-qatです。本稿の「Cline・Gemma」はこの記録に基づく呼び方で、読み込まれた重みまでは検証していません。

最初は、ページ挿入・削除、文書プロパティ、セキュリティ設定などを含む長いヘルプ形式の仕様を渡していました。24日11時53分の依頼は、開く・サムネイル表示・保存・削除に絞られています。

筆者のプロンプト(抜粋)

ファイルを開いた後、PDFファイルをサムネイル表示します。

(Cline資料C02、ui_messages.jsonのUI[0]。前後の仕様を省略。UI番号はJSON配列の0始まり)

同タスクではPyQt6、PyMuPDF、Pillowを使うコードと、pytestによるテストが作られました。続いて並べ替え、回転、挿入、文書プロパティを個別に指示しています。後のCodex版はPySide6を使っており、同じ構成としては扱いません。

最初のタスクにはLM Studioのログ確認やコンテキスト長の調整を案内するAPI失敗があり、別タスクにはツール呼び出しの繰り返し失敗もあります。原因をモデルの性能や仕様の長さだけに帰することはできません。

先行試作では起動時のimportエラーと修正、自動テストの成功も記録されました。ただし、回転・挿入の未完了テストや、文書プロパティ追加の途中で終わった記録もあります。第9回では、この試作の具体的なコード変更から「完成」と「一部の検証成功」の違いを振り返ります。

旧フォルダーがなくても、会話とコードは残っていた

作業場所はDownloads/source/PDFUtilityと記録されています。現在そのフォルダーはありませんが、Cline内部のチェックポイントGitに164件の保存履歴と、最終時点のコード7ファイルが残っていました。現行リポジトリとは別のGit履歴です。

VS Codeには8月25日のPDFUtility2/PDFUtility2_Devという別名の編集履歴もあります。改名かコピーかは未確認で、旧フォルダーが見つからないことだけで削除したとは断定しません。

ClineからCodexへ切り替える際は、コードを移さず、プロンプトだけを流用して仕切り直しました。

Codex版の初期実装

Codex版では、必要最低限と考えた画面・操作の仕様を渡した

取得できたCodex版の初期プロンプトは8月28日19時12分でした。Windows 11、Pythonという前提とともに、最初の画面と操作の条件を渡しています。

  • ウィンドウ幅に応じて折り返す、スクロール可能なサムネイル一覧。
  • サムネイルは縦横比を保ち、最大288×288 px。下にページ番号を表示。
  • 単一・複数ページの選択。
  • PDFを開く、上書き保存、名前を付けて保存。
  • 別PDFの挿入、ボタンやドラッグによる並べ替え、左右90度回転。
  • 文書プロパティと8言語のUI。

技術面ではGUIにPyQt6またはPySide6を使うことを許容し、PDF処理にはPyMuPDFを指定しました。PyMuPDFの採用は、この段階で開発者側が提示した条件です。

端末についても、次の指示が残っています。

筆者のプロンプト(抜粋)

Terminalはcmd.exeを使ってください。

(会話資料S01、9行。長い仕様プロンプトから末尾のみ抜粋)

Codexは次の構成を提示しました。

Codexの回答(抜粋)

そのため、PySide6+PyMuPDF構成を新規に組み立てます。ページ一覧はアイコン表示の折返しグリッドにして、複数選択と内部ドラッグによる並べ替えを同じ部品で実現します。

(S01、29行。冒頭の環境説明を省略)

画面のサイズや選択方法、挿入位置、初期言語など、最初の動きを判断するための条件は指定しました。一方で、使いながら必要になった機能は、後から追加で指示する進め方にしました。仕様を少なくしたことで開発が容易になったかどうかは比較実験をしていないため断定できませんが、これがCodex版で採った進め方でした。

Codex版の初期構成は、画面とPDF操作を分けた

現行リポジトリの初回コミット 3ed50bd は8月28日22時04分です。初期プロンプトより後なので、その間の試行錯誤のすべてが個別コミットになっているわけではありません。

主な構成は次のとおりでした。

main.py
pdfutility/
  app.py       # メイン画面と操作の連携
  model.py     # PDF文書の読み込み・編集・保存
  widgets.py   # サムネイル一覧
  dialogs.py   # 文書プロパティ
  i18n.py      # 言語選択と翻訳の読み込み
locales/       # 8言語のJSON
requirements.txt
PDFUtility.spec
build_exe.bat

サムネイル一覧はQListWidgetを使っています。初回コミットのpdfutility/widgets.pyには次の設定があります。間の設定は省略しています。

self.setViewMode(QListWidget.ViewMode.IconMode)
self.setResizeMode(QListWidget.ResizeMode.Adjust)
# 中略
self.setWrapping(True)
self.setSelectionMode(QListWidget.SelectionMode.ExtendedSelection)
self.setDragDropMode(QListWidget.DragDropMode.InternalMove)
# 中略
self.setIconSize(QSize(288, 288))

PDFの並べ替えは画面だけを動かすのではなく、モデル側でもページの順序を更新します。初期のreorderは、ページ番号のリストを組み替えてDocument.select()に渡す実装でした。

order = list(range(self.doc.page_count))
page = order.pop(old)
order.insert(new, page)
self.doc.select(order)
self.dirty = True

これは初期実装の記録です。後の性能改善で処理が変わっているため、現在のFolimeldの内部実装と同一とは限りません。

実行時の問題と修正

詳細タブを編集可能にすると、存在しないAPIを呼んだ

最初の仕様では、文書プロパティの詳細タブは表示専用でした。20時05分に追加指示を出しています。

筆者のプロンプト(全文)

文書のプロパティの詳細タブの全項目を編集可能に変更してください。

(S01、118行)

CodexはPDFバージョン、ページレイアウト、表紙、方向に関する変更を実装しました。しかし、20時07分に実行時エラーが報告されています。

AttributeError: 'Document' object has no attribute 'set_page_layout'.
Did you mean: 'set_pagelayout'?

(S01、137行のエラーから抜粋。ローカルパスとスタックの途中は省略し、Markdownのエスケープと改行を整形)

原因となった呼び出しと修正は、会話中のパッチに残っています。

変更前:

if layout:
    self.doc.set_page_layout(layout)

変更後:

if layout:
    set_layout = getattr(self.doc, "set_pagelayout", None)
    if set_layout is None:
        set_layout = getattr(self.doc, "set_page_layout", None)
    if set_layout is None:
        raise RuntimeError("This PyMuPDF version cannot edit the page layout.")
    set_layout(layout)

(S01、143行のパッチ。修正後は初回コミットのpdfutility/model.pyにも存在)

ここで確認できるのは、使用した環境ではset_pagelayoutが必要だったことです。Codexは回答でバージョン差への対応と説明しましたが、set_page_layoutという別名が実際にどの版で使えるかは、この記録からは確認できません。残したフォールバックの存在と、そのAPIが実在することは別です。

また、この不具合の修正は現行リポジトリの初回コミットより前です。Gitだけを見た場合、修正済みコードしか見えず、存在しないAPIを呼んだ経緯を拾えませんでした。

「EXEだけで渡せる形」にする

20時14分には、配布の形について指示しました。

筆者のプロンプト(全文)

EXE化して、他のファイルを参照不要にほしい。

(S01、156行。原文のまま)

CodexはPyInstallerのonefile形式(配布用の単体実行ファイル)を選び、翻訳JSONも同梱する方針を示しました。コードから読み取る必要があるデータは、Pythonモジュールとは別に配布設定へ含める必要があります。

初期specには次の指定があります。

datas=[("locales", "locales")],

翻訳の読み込み側も、通常実行とPyInstallerによる実行の両方を扱う構成に変更されました。

root = Path(getattr(sys, "_MEIPASS", Path(__file__).resolve().parent.parent))
path = root / "locales" / f"{language}.json"
fallback = root / "locales" / "en.json"

(初回コミット、pdfutility/i18n.py)

Pythonの実体を見つけられず確認し直した後、既存の仮想環境を使ってビルドへ進みました。この環境確認については後半の補足で扱います。

20時15分の依存情報では、PySide6が6.11.2、PyMuPDFが1.28.2でした。requirements.txtのPySide6>=6.7とPyMuPDF>=1.24は最低条件であり、実際に使われた版とは区別できます。

Codexの最終報告では、単体EXEのサイズは約66.5 MBで、8言語の翻訳データを含むとされています。初回コミットにもdist/PDFUtility.exeが登録されています。ただし、これをもって「Python未導入の別PCで全機能が確認できた」とは言えません。その試験記録は今回確認できていません。

翌朝、「初回が英語になる」を修正した

翌29日にはパスワード関連の追加指示が複数回出ています。9時37分には言語判定の問題も報告しました。

筆者のプロンプト(全文)

初回起動時に英語になっている。

(S01、411行)

修正コミット ba5b4eeでは、Pythonのロケールから直接言語を決める処理を、専用の取得処理へ変えています。

-system = (locale.getlocale()[0] or "en").split("_")[0].lower()
+system = self._system_language()

WindowsではGetUserDefaultUILanguage()でUI言語を取り、取得できない場合はQtのQLocale.system()へフォールバックします。

language_id = ctypes.windll.kernel32.GetUserDefaultUILanguage()
windows_name = locale.windows_locale.get(language_id, "")
code = windows_name.split("_")[0].lower()

「システムの言語」という一つの言葉でも、最初に使ったロケール取得方法が、期待したWindowsの表示言語と一致するとは限りません。生成された実装を実際に起動し、期待と違った結果を戻すことで、この修正につながりました。

小さな追加指示で、使うための機能を増やした

29日の会話とコミットには、次の追加が残っています。

追加したもの 記録
閲覧パスワードの設定・解除 6aa125e、9:34
選択ページと同サイズの空白ページ、削除、エクスプローラー連携 8938d8a、10:06
最後に開いたフォルダーの記憶 0e10b78、10:40
MITのLICENSEとCodex使用のREADME記載 14c9e38、11:47

ここまでは初期版の追加です。Undo/Redoや画像フォルダーからのPDF作成は後の変更で、MITからのライセンス方針の見直しは第4回で扱います。

最初の実装を、実行結果から直していく

初日の骨格ができた後も、詳細タブの編集、EXE化、初期言語の修正などの指示を追加しました。画面とPDF操作を作るところから、実際に動かして期待との差を直す段階へ進んだのが、この2日間でした。

次回は、PageCraftを経由したFolimeldへの改名と、macOS対応を取り上げます。

開発環境の補足

補足:PythonとGitは、導入経路と実行先を確認する

筆者は、公式インストーラー、Microsoft Store、CMDやPowerShellからの導入を試し、参考記事ごとに手順が違うことにも迷いました。PowerShellの入力履歴にはwinget install Python.Python.3.11やpipによる導入コマンドが残りますが、実施日や導入完了までは分かりません。Python本体の導入と、pipによるライブラリの導入は分けて考える必要がありました。

8月28日のCodexも、PATH検索でPythonを見つけられず、その後に実体や仮想環境を調べ直しています(S01、56〜63行・93〜109行・156行以降)。「コマンドが見つからない」と「未導入」は同じではありません。

次はPowerShell用の確認例です。VS Codeで選択したPythonと、ターミナルの実行先も照合します。

Get-Command python, py, git -All
python -c "import sys; print(sys.executable); print(sys.version)"
python -m pip --version
git --version

10月30日のこのPCでは、Python 3.14.7とGit for Windows 2.54.0が動き、ツール同梱の別のGitも実行パスにありました。これは現在の点検結果で、8月の全作業の環境を示すものではありません。導入時はGit公式のWindows向け案内などと既存環境を照合します。

用途を確認せずPython関連のディレクトリーを削除し、復元した経験もあります。この環境整理の話は第9回で取り上げます。

Windowsの実行エイリアス、導入したPython本体、アプリ同梱Pythonは区別します。Python公式資料も、Windowsにはシステム標準のPython環境が含まれないと説明しています。「Windowsの本体用Python」と決めつけず、保存先と参照関係を確認した経験でした。

補足:CMD・PowerShell・Git Bashをどう使い分けるか

初期プロンプトでは実行環境をそろえるため、cmd.exeを指定しました。CMDとPowerShellでは、環境変数の設定だけでも次の違いがあります。

rem CMD
set "FOLIMELD_MODE=debug"
# PowerShell
$env:FOLIMELD_MODE = "debug"

Git BashやLinux互換環境も入れると、似たコマンド画面が増えて混乱しました。Windows TerminalやVS Codeのターミナルは画面の入れ物、CMD・PowerShell・Bashはシェルです。Git for WindowsのGit Bashと、第3回で使うWSL上のBashも実行環境は異なります。Bashではpwd、command -v python、command -v gitなどで現在位置と実行先を確認できます。

8月20日の従来スクリプトの相談には「PowerShell 7でr2l_nocover.batを実行すると、ファイル名を指定しても、Usageが表示される理由を教えて」とあります(Cline相談記録、UI[0])。ただし、切り分け用バッチにはArg1: img001.pdfと出ていました(UI[61])。引数が渡らないという単純な原因では説明できず、原因特定・解消まで確認できた記録もありません。

参考スクリプトを使うときは、PowerShellの解析規則も確認し、シェル名・版・実行コマンド・引数・出力をセットで残すようにします。

先行試作の参照記録

Cline資料C01は8月23日開始、C02・C03は8月24日開始のタスク記録です。各タスクのtask_metadata.json、ui_messages.json、api_conversation_history.jsonを参照しました。本文のUI/API番号はJSON配列の0始まりです。Cline内部Gitの最終チェックポイントは3a9b314ddb67a59f774d4e7fe287fc4cb7cf1c00(8月24日21時07分)。現行Gitのコミットではなく、生ログや個人の環境パスは公開していません。

【2026年11月17日16:44までの更新】初回公開後の主な修正:冒頭の説明と誤字を修正しました。「Folimeldの配布状況」では、Windowsの公開済み版と次期Store版の審査提出・未確認事項、Linux全19件のプレリリースとamd64 strict Snap 0.3.5、BSD amd64版0.3.5(FreeBSDは改訂1)および各配布物の検証範囲を反映しました。連載紹介では第6・7回の対象期間と内容を更新しました。通常画面での全操作確認とoffscreen起動、公開済みの実績と予定を区別しています。画像の差し替えは行っていません。

ソースコードと本稿の対象

ソースコード:tyamada/Folimeld。Codex版の基準は2026年10月25日取得のHEAD 50d0d5b4bcd6677b71ea4dd46dcef027b104717fです。10月30日に先行試作・環境の資料と筆者の振り返りを補い、当時の記録と区別しました。

開発動機は10月25・30日の説明、切り替え理由とコードを移さなかった判断は10月30日の筆者追記に基づきます。従来スクリプトは実ファイルを参照し、作成時期や流用を断定していません。

今回、アプリのビルド・動作試験は再実行していません。成功報告・実行ログ・未確認事項を区別し、引用は原文を保って省略・整形を注記しています。

参照した履歴

非公開会話資料:S01は2026年8月28日開始、S02は同年8月29日開始のCodex会話記録です。引用の行番号は展開後JSONLの物理行です。生ログにはローカル情報が含まれるため公開していません。


次の記事:第2回:PDF UtilityからFolimeldへ――改名とmacOS対応を進めた

0
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?