Visual Storeは、コーディングエージェント向けのローカルPNGストレージです。画像を不透明なvisual://参照として保存し、CLIから小さなJSONだけを返します。必要になった画像だけをローカルファイルへ取り出せます。保存と取得では画像を表示せず、画像のバイト列を標準出力へ流しません。
MVPは、非インターレースの静止8-bit RGB/RGBA PNGに対応しています。既存のフィルター済み走査線をzlib level 6で可逆再圧縮し、検証に成功した小さい方を保存します。同一の保存blobはSHA-256で重複排除し、同じ画像が複数回現れたという記録は個別の画像レコードとして保持します。
このリポジトリはRust 2024のプロジェクトとして開始しました。Rustでは、パーサーの整数演算とバッファーを安全に制限でき、単一のローカルCLIバイナリとして配布できます。PNG、zlib、SQLite、SHA-256、UUID、JSON、CLI解析には保守されたライブラリを使用しています。SQLiteはソースをバンドルしてビルドします。時間方向コーデックはsystem libvpxへ直接リンクします。実行時にFFmpeg、ImageMagick、ネットワーク接続、APIキーは使用しません。
GitHub ReleasesのvX.Y.Zタグから、OS・CPUに合うvstore-vX.Y.Z-<target>.tar.gzをダウンロードできます。展開したvstoreをPATH上に置いてください。配布版はlibvpxを静的リンクしているため、実行時にlibvpxの別途インストールは不要です。Linux版はDebian 12 (glibc 2.36)をビルド基準とします。各アーカイブにはライセンス通知を同梱し、SHA256SUMSで照合できます。
ソースからインストールする場合は、現在の安定版Rustツールチェーン、Cコンパイラー、pkg-config、libvpx開発packageが必要です。対応するsystem libvpxの範囲は1.12.0〜1.16.0です。
# macOS
brew install libvpx pkg-config
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y libvpx-dev pkg-configcargo install --path . --locked
vstore --version開発中は、以下の例にあるvstoreをcargo run --locked --へ置き換えて実行できます。
vstore --store "$PWD/.visual-store" init
vstore --store "$PWD/.visual-store" put \
--file artifacts/render.png \
--run ui-check-20260915-a \
--stream browser-main \
--label input-border \
--note "後で確認するため保存。画像はまだ見ていない。"
vstore --store "$PWD/.visual-store" list --run ui-check-20260915-a --limit 20
vstore --store "$PWD/.visual-store" pack --run ui-check-20260915-a --dry-run
vstore --store "$PWD/.visual-store" pack --run ui-check-20260915-a
vstore --store "$PWD/.visual-store" get-frame --run ui-check-20260915-a --stream browser-main --frame 0
vstore --store "$PWD/.visual-store" prune --dry-run
# isolated storeでレポートを確認してから明示実行
vstore --store "$PWD/.visual-store" prune --apply
vstore --store "$PWD/.visual-store" info 'visual://STORE_ID/images/IMAGE_ID'
vstore --store "$PWD/.visual-store" features 'visual://STORE_ID/images/IMAGE_ID'
vstore --store "$PWD/.visual-store" judgment list 'visual://STORE_ID/images/IMAGE_ID'
vstore --store "$PWD/.visual-store" get 'visual://STORE_ID/images/IMAGE_ID'
vstore --store "$PWD/.visual-store" verify--helpと--version以外のコマンドは、標準出力へUTF-8のJSONを一件だけ出力します。診断結果に画像本体は含まれません。getは絶対ローカルパスとdisplayed: falseを返します。画像の内容を確認する必要がある場合だけ、そのパスを画像表示機能へ渡してください。
動画圧縮はローカル保存容量を削減します。参照IDで必要な画像だけ扱う設計は、不要な画像を会話へ入れないためのものです。一度モデルへ表示した画像をSkillが後から履歴から消すわけではなく、pack後のbyte削減は画像トークン削減量を表しません。
storeの選択順は--store PATH、VSTORE_ROOT、$CWD/.visual-storeです。親ディレクトリは探索しません。.visual-store/をGit管理に含めないでください。このリポジトリの.gitignoreでは除外済みです。
--runを指定した観測には、(run, stream)ごとに0始まりの不変なframe_noが割り当てられます。--stream省略時はdefaultです。入力と完全に同じバイト列を後で取得する必要がある場合は、put --keep-sourceを指定します。通常は検証済みの可逆保存版だけを保持します。再試行可能な登録には--operation-idを使います。同じ操作IDを異なる元画像やメタデータで再利用するとE_CONFLICTになります。
format version 3では、画像ごとに複数の外部判定を追加できます。producer、model、producer側のschema_version、JSON value、probability、confidence、metadata、時刻を独立して保持します。rule、classical、jev、vision-llm、humanを同じ仕組みで扱えます。
vstore judgment add 'visual://STORE/images/IMAGE' \
--kind needs_visual_inspection \
--producer jev \
--value false \
--confidence 0.96
vstore judgment search --kind needs_visual_inspection --value true
vstore judgment search --producer jev --confidence-below 0.70featuresは、保存済みhash・寸法・sizeと直前frameとのpixel一致だけを返し、画像を取得・表示しません。Jev連携はVisual StoreのcoreではなくSkillのadapter workflowが担います。putを含むcore commandはネットワーク接続、Jev、APIキーを一切必要としません。外部agentはmetadata、features、過去のjudgmentを先に読み、needs_visual_inspection=trueまたはconfidence不足のときだけgetしてVisionへ渡せます。設計判断と後回しにしたfeatureはJudgment Layer ADRに記録しています。
完全な仕様はCLIリファレンス、JSON Schema v2、保存形式を参照してください。旧schema v1のconsumerはv2のrepresentation、pack、get-frame、prune契約へ更新が必要です。
既定buildはsystem libvpxを直接使うVP9 backendを含みます。AV1は未実装で、pack --codec av1はE_CODEC_UNAVAILABLEを返します。FFmpegは不要です。
リポジトリにはVisual Store Skillを同梱しています。Codexは.agents/skills以下のプロジェクトSkillを読み取ります。リポジトリへコピーするか、開発中はシンボリックリンクを作成します。
mkdir -p .agents/skills
ln -s ../../skills/visual-store .agents/skills/visual-store複数のリポジトリで使う場合は、skills/visual-storeを$HOME/.agents/skills/visual-storeへコピーします。CLIとSkillは別々にインストールします。現在のCodexはSkillの変更を自動検出します。表示されない場合はCodexを再起動してください。明示的に使う場合は$visual-storeを指定します。配置場所と呼び出し方法はOpenAI公式のSkillドキュメントに基づいています。
連携手順はcodex-cli 0.154.0を基準に作成しました。自動テストではCLIとSkillファイルを検証しています。新しいCodexセッションでの暗黙選択と、ホスト側の画像表示機能との接続は手動確認が必要です。
すべてのvstoreプロセスを終了し、storeディレクトリ全体をコピーしてから、コピー先でvstore --store COPY verifyを実行してください。storeの使用中にindex.sqlite3だけをコピーしないでください。MVPは画像レコード、blob、exports、一時的な孤立候補を自動削除しません。
format version 1のstoreは読み取り専用で開けます。書き込み前に、全体バックアップを取得してからvstore --store STORE migrate --to 2を明示実行してください。既存のversion 2 storeへJudgment Layerを追加するときはmigrate --to 3を実行します。各migrationの中断時は通常操作がE_MIGRATION_INCOMPLETEで停止します。同じtargetへ--resumeして再開するか、--restoreで直前versionへ戻せます。
storeディレクトリとファイルは、POSIX環境でそれぞれ0700と0600で作成します。既存の所有者や権限は変更しません。ネットワークファイルシステムと複数ホストからの同時利用はサポート対象外です。
cargo test --locked --features fault-injection
cargo clippy --locked --all-targets --all-features -- -D warnings
cargo build --locked --release
cargo run --locked --example vp9_roundtripfault-injection featureは、永続化境界で子プロセスを終了したりENOSPCを発生させたりする隔離テスト専用です。インストール用ビルドでは有効にしないでください。
性能は画像内容とハードウェアによって変わります。性能測定手順に従い、単純なGUI、文字の多いGUI、写真を含む画面、圧縮されにくいfixtureで測定してください。OS、CPU、releaseビルド、圧縮level、キャッシュ状態、並行度も結果と一緒に記録します。
Visual StoreはMITライセンスです。VP9 backendはBSD 3-Clauseのsystem libvpxを、MPL-2.0のlibvpx-native-sys 5.0.17から呼び出します。ほかの実行時直接依存はbase64、chrono、clap、crc32fast、flate2、libc、png、rusqlite、serde、serde_json、sha2、uuidです。これらはMIT、Apache-2.0または互換ライセンスで提供され、rusqliteはMIT、バンドルされるSQLiteはパブリックドメインです。テスト専用依存はtempfileとjsonschemaです。解決済みの正確なRust crate版はCargo.lockへ記録しています。採用版、可逆plane配置、system libraryの再現手順はVP9 codec ADRに記録しています。
リリースアーカイブにはVisual Storeとlibvpxのライセンス、およびCargo依存関係のライセンス一覧と入手できるライセンスファイルを同梱します。再配布時には対象成果物の推移的依存関係と通知を確認してください。開発用ソースにはlibvpxのライセンス文のみを同梱し、サードパーティーのソースはvendorしていません。
Cargo.tomlのversionと同じvX.Y.Zタグをmain上のコミットに付けてpushすると、GitHub ActionsがLinux/macOSのx86_64・ARM64をビルドし、VP9の動作と動的codec依存がないことを確認してGitHub Releaseへ公開します。ワークフローのpull requestでは同じビルドを実行しますが公開はしません。タグがversionと一致しない場合やmain上にない場合は公開を止めます。
ローカルファイルシステム上のmacOSとLinuxを対象とし、それ以外の環境では意図的にコンパイルエラーになります。CIはDebian 12 ARM64のlibvpx 1.12.0と、Ubuntu・macOSのsystem libvpxで既定のVP9 buildを検証します。この開発環境ではmacOS、Rust 1.95.0、libvpx 1.16.0でcodec試験を実行しました。