Skip to content

test(speakerdeck-knowledge): 画像処理の回帰テストと利用手順を補完 #103

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
9uiLe merged 1 commit into from
Sep 14, 2026
Merged

test(speakerdeck-knowledge): 画像処理の回帰テストと利用手順を補完 #103

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 0 additions & 15 deletions .gitattributes
View file
Open in desktop

This file was deleted.

4 changes: 2 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ codex plugin add <plugin-name>@9uile-plugins
│ ├── speakerdeck-knowledge/
│ │ ├── .claude-plugin/plugin.json
│ │ ├── .codex-plugin/plugin.json
│ │ ├── skills/ ← speakerdeck-knowledge と取得補助・図解用 CSS
│ │ ├── skills/ ← speakerdeck-knowledge と取得・画像生成補助・図解用 CSS
│ │ ├── tests/
│ │ └── README.md
│ └── model-strategy/
Expand All @@ -86,7 +86,7 @@ codex plugin add <plugin-name>@9uile-plugins
│ ├── references/
│ ├── tests/
│ └── README.md
├── docs/ ← 設計指針・ADR
├── docs/ ← 設計指針・運用記録
├── scripts/ ← リリース・バージョン検証
├── releases/ ← リリースノート
├── CHANGELOG.md
Expand Down
10 changes: 5 additions & 5 deletions plugins/speakerdeck-knowledge/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ URL は必須です。形式の指定がなければ Markdown と HTML の両方

## 成果物の保存先と内容

保存先が未指定の場合は、作業ディレクトリの `ai-knowledge/` 配下に、スライドごとのディレクトリを作成します。ディレクトリ名は URL の最後のパス要素で、クエリとフラグメントを除きます。
保存先が未指定の場合は、作業ディレクトリの `ai-knowledge/` 配下に、資料ごとのディレクトリを作成します。ディレクトリ名は URL の最後のパス要素で、クエリとフラグメントを除きます。

```text
作業ディレクトリ/
Expand All @@ -37,7 +37,7 @@ URL は必須です。形式の指定がなければ Markdown と HTML の両方

形式を指定した場合は指定形式だけを作成します。必要な検証記録や配布用画像も、その資料のディレクトリへまとめます。同じ資料の再生成では同じ場所を使い、別資料と名前が重なる場合は著者の URL 識別子を付けて区別します。

取得した HTML・本文・スライド画像一式は一時ディレクトリに保存します。プラグインの配置先や `examples/` は通常利用時の保存先には使いません。
取得した元 HTML・本文・選択したページの元画像は一時ディレクトリに保存します。プラグインの配置先や `examples/` は通常利用時の保存先には使いません。

## 資料の設計

Expand All @@ -47,7 +47,7 @@ HTML は PC 向けの単体ファイルを基本とします。左側の追従

本文を先に読み、図・配置の確認や本文欠損を補うために必要な画像だけを開きます。画像主体の資料も少数ページずつ確認します。取得した範囲と実際に読んだ範囲を成果物に記録し、仮説や提案の効果は観測済みの成果と区別します。資料の作成には、対象プロジェクトの実装や外部への公開・送信は含みません。

画像の閲覧には長辺1280px以下の縮小画像を使い、位置の俯瞰が必要な場合だけ最大6ページのコンタクトシートを作ります。読めない文字や図は必要領域を元画像から切り出し、観察結果をメモして執筆中の再読を抑えます。元画像は引用・配布用に保持し、HTML の画像データはローカルで埋め込みます。実際の token 使用量はモデル・閲覧ツールに依存するため、固定の削減率は保証しません。
画像の閲覧は、既定で長辺1280px以下の縮小画像から始めます。位置の俯瞰が必要な場合だけ最大6ページのコンタクトシートを作り、読めない文字や図は元画像の必要領域を切り出して確認します。寸法の調整方法とコマンド例は [画像読解の手順](skills/speakerdeck-knowledge/references/image-reading.md) に記載しています。観察結果をメモして執筆中の再読を抑え、元画像は引用・配布用に保持します。HTML の画像データはローカルで埋め込みます。実際の token 使用量はモデル・閲覧ツールに依存するため、固定の削減率は保証しません。

## 構成と実行環境

Expand All @@ -66,7 +66,7 @@ HTML は PC 向けの単体ファイルを基本とします。左側の追従
| `scripts/fetch_deck.py` | ページ別本文・画像・書誌情報の取得と保存 |
| `scripts/prepare_images.py` | 対象ページの縮小・切り出し・分割コンタクトシート生成 |

取得スクリプトの `--out` は中間資料の保存先です。最終成果物の保存先決定と執筆は、スキルを実行する AI が担当します。
取得スクリプトの `--out` は中間資料の保存先です。画像生成スクリプトはその中の `reading-images/` に閲覧用画像を作ります。画像の閲覧、`reading-notes.md` への観察記録、最終成果物の保存先決定と執筆は、スキルを実行する AI が担当します。

## 検証

Expand All @@ -81,4 +81,4 @@ rtk proxy python3 -m unittest discover -s plugins/speakerdeck-knowledge/tests -v
rtk proxy bash scripts/verify-versions.sh
```

サンプルの `validation.md` は読解範囲と表示・操作の確認結果です。通常利用時の必須出力ではありません。独立した読者の理解度や実案件での改善効果は、別途評価する必要があります。ローカル導入は [コントリビューションガイド](../../CONTRIBUTING.md#ローカルで検証する) を参照してください。
自動テストは補助スクリプトの動作を検証します。資料の読解品質・表示・操作、独立した読者の理解度や実案件での改善効果は、別途評価する必要があります。ローカル導入は [コントリビューションガイド](../../CONTRIBUTING.md#ローカルで検証する) を参照してください。
8 changes: 6 additions & 2 deletions ...ns/speakerdeck-knowledge/skills/speakerdeck-knowledge/references/acquisition.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,11 @@ python3 scripts/fetch_deck.py 'https://speakerdeck.com/author/deck' --out /tmp/d

画像は本文ブロックの実在するリンクから取得し、JPEG/PNG の応答を保存する。各ページの状態は `not_requested`、`downloaded`、`failed` のいずれか。取得失敗時には理由を記録し、成功した画像を保持する。

終了コードは成功が0、入力・本文取得・解析・保存の失敗が1、画像の一部取得失敗が2。異なる資料がある保存先はエラーにする。同じ資料では、ページ番号と画像 URL が一致しローカルファイルが残る取得済み画像を再利用し、追加取得時にもその状態を保持する。失敗した画像の再取得は明示した範囲だけ行う。資料の更新を確認したい場合は、新しい一時ディレクトリに取得する。
異なる資料がある保存先はエラーにする。同じ資料では、ページ番号と画像 URL が一致し、取得時のファイル名で空でないローカルファイルが残る取得済み画像を再利用する。過去の取得失敗もページ番号と画像 URL が一致すれば保持し、再取得は明示した範囲だけ行う。再利用時は配信元の画像を再検証しないため、資料の更新を確認したい場合は新しい一時ディレクトリに取得する。

標準出力の JSON は、総ページ数 `pages`、指定した画像の件数 `images_requested`、その実行で取得に失敗したページ `images_failed`、保存先 `out` を返す。`images_requested` は再利用した画像も含む。全ページの取得状態は `deck.json` を参照する。

引数解析後の終了コードは、指定範囲の処理成功が0、入力・本文取得・解析・保存の失敗が1、指定範囲の画像取得失敗が2。指定範囲外の過去の失敗は終了コードと `images_failed` に含めない。必須引数不足など、コマンドライン引数の解析エラーも2で終了し、標準エラーに使用方法を出す。

## 読解の進め方

Expand All @@ -43,6 +47,6 @@ python3 scripts/fetch_deck.py 'https://speakerdeck.com/author/deck' --out /tmp/d

HTTP エラーでは応答と実行環境を確認し、公開ブラウザ閲覧など条件の異なる経路を選ぶ。同じ失敗の再試行には条件の変化を必要とし、認証を迂回しない。

本文を解析できなければ公開の画像や PDF の実在を確認する。PDF はページ数と本文をローカルに抽出し、必要ページだけをレンダリングして画像読解の手順へ進む。OCR を補助に使う場合は否定・数値・コード・矢印の方向を必要な画像領域と照合する。推測した連番 URL でページを補わない。
本文を解析できなければ公開の画像や PDF の実在を確認する。PDF はページ数と本文をローカルに抽出し、必要ページだけをレンダリングして画像読解の手順へ進む。推測した連番 URL でページを補わない。

本文も画像も読めない場合は PDF または画像の提供を求める。説明文や検索スニペットしか確認できていない場合はその範囲を明記し、全スライドの知識抽出として納品しない。
6 changes: 3 additions & 3 deletions ...ins/speakerdeck-knowledge/skills/speakerdeck-knowledge/references/html-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,13 +50,13 @@ PC 専用のレイアウトとし、サイドバー幅360pxを起点に本文幅

`assets/guide.css` を土台として、資料に使う規則を HTML の `style` に埋め込む。単体共有では引用画像を data URI、必要な JavaScript をインラインで含める。画像が多くファイルサイズが問題になる場合は HTML と画像フォルダを一組で渡す。出典リンクを残し、表示に CDN・外部フォント・通信を必要としない構成にする。取得キャッシュやスライド全文は配布対象に含めない。

画像の埋め込みはローカルのコードで行い、base64 をセッションへ出力しない。埋め込み後の HTML は画像データを除いて本文を検査する。画像の扱いとスクリーンショットの範囲は [画像を効率的に読む](image-reading.md) に従う。
画像の埋め込みはローカルのコードで行い、base64・画像バイナリを会話やツールのテキスト結果へ出さない。埋め込み後の HTML 全文や巨大な diff も出さず、本文は埋め込み前か画像データを除いた抽出で検査する。

言語を示す `lang`、ページタイトル、viewport、適切な見出し階層、アンカーを設定する。色にはラベルを併用する。拡大や開閉はキーボードで操作でき、閉じた後は起点へフォーカスを戻す。JavaScript 無効時も知識と作業指示を閲覧できるようにする。

## 完了確認

- 代表的な PC の幅と高さでビューポート単位のスクリーンショットを撮り、実際に見る。ヘッダーのまとまり、本文の読み順、図の可読性、見切れ、サイドバーの追従と内部スクロールを確認する。追加撮影は未確認・修正した領域を中心に行う。
- 目次の全リンク、拡大、開閉、キーボードのフォーカスを操作する。JavaScript 無効時の本文と指示全文、表示時の外部通信とスクリプト例外を確認する。
- 代表的な PC の幅と高さでビューポート単位のスクリーンショットを撮り、実際に見る。ヘッダーのまとまり、本文の読み順、図の可読性、見切れ、サイドバーの追従と内部スクロールを確認する。追加撮影は未確認・修正した領域と影響範囲を対象とし、長いページの全面画像を繰り返し開かない。
- 目次の全リンク、拡大、開閉、キーボードのフォーカスを操作する。リンク・画像の有無や寸法は DOM の検査も使う。JavaScript 無効時の本文と指示全文、表示時の外部通信とスクリプト例外を確認する。
- 印刷では操作部品を隠し、開閉内容を表示し、図とキャプションの分断を避ける。
- Markdown の知識 ID と各項目、根拠ページ、AI 指示を照合する。未検証の環境や読解範囲を検証結果に記載する。
18 changes: 11 additions & 7 deletions .../speakerdeck-knowledge/skills/speakerdeck-knowledge/references/image-reading.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
1. 本文から「ページ・確認したい問い」を選ぶ。本文欠損や画像依存の内容は飛ばさず、画像主体の資料では少数ページずつ進める。全件を一度に開く必要はない。
2. 図のある位置や反復ページの判別だけが必要なら、小さなコンタクトシートを使う。読むページが既に決まっている場合は、単ページの縮小画像へ直接進む。全ページのシート閲覧を必須にしない。
3. 単ページの縮小画像で問いに答えられれば止める。文字・数値・コードが読めない場合は、元画像の必要領域を切り出す。矢印の両端や凡例など、意味を決める周囲も含める。切り出しでは関係が失われる場合だけ単ページの解像度を上げる。
4. 確認直後に一時ディレクトリの `reading-notes.md` へ、ページ・確認方法と領域・観察結果・未解決の問いを短く追記する。執筆、HTML 化、会話の圧縮後はこのメモを参照する。同じ画像は、新しい問いや可読性の問題がある場合だけ再度開く。
4. 確認直後に、読解する AI が一時ディレクトリの `reading-notes.md` へ、ページ・確認方法と領域・観察結果・未解決の問いを短く追記する。補助スクリプトは閲覧や観察の記録を行わない。執筆、HTML 化、会話の圧縮後はこのメモを参照する。同じ画像は、新しい問いや可読性の問題がある場合だけ再度開く。

コンタクトシートで細かな文字を精読した扱いにしない。取得や縮小画像の生成だけでは閲覧済みにしない。本文のみで確認した範囲、画像で確認した範囲、未確認部分と影響を成果物へ記載し、未読部分を推測で補わない。

Expand All @@ -28,12 +28,16 @@ python3 scripts/prepare_images.py --deck /tmp/deck-source/deck.json --pages 5-12
python3 scripts/prepare_images.py --deck /tmp/deck-source/deck.json --pages 19 --crop 0.5,0,1,1
```

出力は一時ディレクトリ内の `reading-images/`。標準出力にはパス・対象ページ・寸法だけを返すので、そのうち次の問いに必要な画像だけを画像閲覧ツールで開く。シートはページ番号を描画し、最大6ページで分割する。`--pages` は必須で `all` は受け付けない。`--max-edge` は必要時に256〜2048pxで調整できる。これはこの補助ツールの運用上の上限であり、モデルの仕様ではない。
| 引数 | 指定と制約 |
| --- | --- |
| `--deck` | 必須。取得済みの `deck.json` |
| `--pages` | 必須。1始まりのページ番号または範囲。重複を除きページ順に処理する。`all` は受け付けない |
| `--mode` | 既定は `preview`。`sheet` はページ番号付きのコンタクトシートを最大6ページずつ生成する |
| `--crop` | `preview` の単一ページだけに指定できる。向き補正後の元画像を基準とする左・上・右・下の座標（0〜1）。切り出した領域を縮小する |
| `--max-edge` | 生成画像の長辺の上限。既定1280px、指定範囲256〜2048px。元画像の拡大は行わない |

同じ元画像・ページ指定・変換条件なら同じ出力を再利用する。ファイルの再利用とセッション内の再閲覧は別なので、既読かどうかはメモで判断する。元画像は変更せず、引用・配布には必要な元画像を使う。OCR が利用できる場合はローカルの補助抽出に使えるが、不確かな文字や視覚的関係は画像で確認する。
寸法とページ数の上限は補助ツールの運用上の制約であり、モデルの仕様ではない。出力は指定した `deck.json` と同じディレクトリ内の `reading-images/` に保存する。標準出力の JSON は `images` 配列にパス `path`、対象ページ `pages`、生成画像の寸法 `width`・`height` だけを返す。そのうち次の問いに必要な画像だけを画像閲覧ツールで開く。

## 成果物と表示確認
終了コードは成功が0、指定値の検証・画像処理・保存や依存ライブラリのエラーが1、必須引数不足などコマンドライン引数の解析エラーが2。失敗時は標準エラーに理由を出す。途中まで生成された画像は残るが、失敗した実行では成功結果の JSON を返さない。

HTML の data URI はローカルのコードで画像ファイルから埋め込み、base64・画像バイナリを会話やツールのテキスト結果へ出さない。埋め込み後の HTML 全文や巨大な diff も出さず、本文の確認は埋め込み前か画像データを除いた抽出で行う。

HTML の表示確認は代表的な PC ビューポートと、問題がある領域のスクリーンショットから始める。長いページの全面画像を繰り返し開かない。リンク・画像の有無・寸法・操作は DOM やブラウザの検査も使い、画像確認は可読性や配置の判断に使う。修正後は変更領域と影響範囲を確認する。
同じ元画像・ページ指定・変換条件なら同じ出力を再利用する。ファイルの再利用とセッション内の再閲覧は別なので、既読かどうかはメモで判断する。元画像は変更せず、引用・配布には必要な元画像を使う。OCR が利用できる場合はローカルの補助抽出に使えるが、不確かな否定・数値・コード・矢印の方向は必要な画像領域と照合する。
Loading
Loading