1仕組みと動作原理

コアロジックは「ターゲット形式に応じた圧縮ツールの自動選定」です：webpはcwebpを最優先し、次にImageMagickのconvert、最後にsharpを使用；非webpはmacOSではsips、それ以外はconvert、フォールバックとしてsharpを使用します。

skills/canghe-compress-image/scripts/main.ts

if (await commandExists("cwebp")) return "cwebp";

ここでの処理内容：detectCompressorの判定基準は実行プラットフォームおよびPATH上のコマンドであり、npm依存関係リストではありません。cwebp/convert/sipsのいずれかが存在すれば、node_modulesがなくても動作します。

可用性の検出はwhich + child_process.spawnで行い、圧縮自体もシステムCLIをspawnして終了コード/stderrを解析します。

skills/canghe-compress-image/scripts/main.ts

const proc = spawn("which", [cmd], { stdio: "pipe" });

ここでの処理内容：runCmdがstderrを一元的に収集し、終了コードが0以外の場合に'sips failed/cwebp failed/convert failed'をスローします。エラー情報は外部ツールに由来します。

sharpは純粋なJSのフォールバックとして機能し、動的importで遅延読み込みされます（先行するパスがいずれもヒットしなかった場合にのみ読み込みコストが発生します）。

skills/canghe-compress-image/scripts/main.ts

const sharp = (await import("sharp")).default;

ここでの処理内容：3つの形式はそれぞれpipeline.webp/png/jpeg({ quality })を経由します。sharpは不足している場合に実行時エラーを引き起こす唯一の依存関係です。

ディスク書き込みには「一時ファイル + アトミックな名前変更」を採用：まずoutput + '.tmp'に書き込み、成功後にターゲット名へrenameします。

skills/canghe-compress-image/scripts/main.ts

renameSync(tempOutput, output);

ここでの処理内容：処理の中断による不完全なファイルの残存を防ぎます。同一関数内で--keepが有効でなく、入力名と出力名が異なる場合、新しいファイルを書き出す前に元画像の名前を*_originalに変更します。

デフォルトは「別名保存ではなく変換」：同一ディレクトリ・同一ベース名で拡張子のみ変更。--keepが有効かつ拡張子が同じ場合のみ{base}-compressed.{ext}を出力します。

skills/canghe-compress-image/scripts/main.ts

return join(dir, `${base}-compressed${ext}`);

ここでの処理内容：getOutputPathと-o/--outputを組み合わせることで任意の出力先パスを指定でき、その場合は元画像の名前変更は行われません。

--keepが無効な場合、元画像は{base}_original.{ext}に名前を変更して保持されます。

skills/canghe-compress-image/scripts/main.ts

renameSync(absInput, `${base}_original${ext}`);

ここでの処理内容：デフォルトでは元画像は削除されません（名前の変更のみ）が、ファイル名が変わるため、スクリプト等から利用する場合は注意が必要です。

ディレクトリモードでは拡張子のホワイトリストに基づいて再帰的にファイルを収集し、1ファイルずつ処理して合計サイズを集計します。

skills/canghe-compress-image/scripts/main.ts

const SUPPORTED_EXTS = [".png", ".jpg", ".jpeg", ".webp", ".gif", ".tiff"];

ここでの処理内容：collectFilesは-r指定時のみ再帰的に動作します。単一ファイルの処理に失敗してもエラーを出力するだけでバッチ全体の処理は中断せず、最後に合計の削減サイズを出力します。

設定の宣言はSKILL.md層でのみ行われ（EXTEND.mdの3段階検索でヒットした場合に読み込み適用）、スクリプト自体は設定ファイルを読み込みません。

skills/canghe-compress-image/SKILL.md

Read, parse, apply settings

ここでの処理内容：EXTEND.mdはデフォルトの形式/品質/元画像の保持設定をサポートします。純粋なCLI利用時とエージェント経由の利用時で挙動は同一であり、違いはエージェントが設定に基づいてデフォルト引数を補完する点のみです。

2コア機能

01圧縮バックエンドの自動選択（sips / cwebp / ImageMagick / sharpの4段階フォールバック）

02フォーマット変換（webp/png/jpeg）+ 品質パラメータ指定（0〜100、デフォルト80）

03単一ファイルおよびディレクトリの一括処理（-r 再帰的、拡張子ホワイトリスト対応）

04元画像の保持戦略（-kで-compressed命名を採用；デフォルトは元画像の名前を*_originalに変更）

05アトミックなディスク書き込み（.tmp経由の後にrename）、失敗時に破損ファイルを残さない設計

06ファイルサイズ比較レポート + --jsonによる構造化出力

07EXTEND.mdによる設定（デフォルト形式/品質/元画像保持）と3段階のパス検索

3外部依存関係

Kind	Dependency / Endpoint
cli	sips（macOS 系统自带图像工具，非 webp 时的首选）
cli	cwebp（libwebp 官方 CLI，webp 首选）
cli	ImageMagick convert
cli	which（命令可用性探测）
package	sharp（动态 import 的纯 JS 兜底；skill 目录无 package.json，依赖运行环境解析）

4推奨統制措置と判定根拠

安全運用のための推奨統制措置

Agent 向け

段階的・都度認可、サンドボックス推奨

管理者向け

承認フロー、ロールバック可能、全履歴監査

判定根拠（ファイルパスと抜粋）

scripts/: ローカルスクリプトまたはコマンドの実行: scripts/main.ts（bunで実行；which / sips / cwebp / convertをspawn、sharpを動的import）
本地工作目录: ファイルの読み書きおよび成果物の出力: 画像の出力（同一ディレクトリの新しい拡張子または-oで指定したパス）、一時ファイル<output>.tmp、--keep無効時の元画像の名前変更（{base}_original.{ext}）

監査ノート： (a) すべての動作がローカルで完結：spawn 'which'による検出、sips/cwebp/convertの呼び出しによる圧縮、sharpフォールバック、ローカル画像の読み込みとローカルファイルの書き出し、ネットワークエンドポイントなし、認証情報読み込みなし、設定ファイル解析なし（EXTEND.mdはエージェントのみが読み込む）。(b) 留意すべきファイルの副作用：--keepを付けない場合、スクリプトは元画像をrenameSyncで{base}_original.{ext}に変更してから新規ファイルを書き込むため、ディレクトリ一括処理時の影響範囲が広くなります。事前に小規模でテストするか、-oで出力先を明示することを推奨します。(c) 実行環境にimagemagick/cwebp/sips/sharpのいずれかが存在することに依存し、CLIツールもsharpもない場合は失敗します。先行事例：baoyu-compress-image等のローカル読み書き系はblueに分類されます。

5二重目の独立検証

[ok] 自带脚本只有 scripts/main.ts，且仅本地行为 — 扫描“网络请求”0 命中；唯一执行面是 spawn which/sips/cwebp/convert 与动态 import sharp；无 fetch/http 调用。
[ok] 原图改名副作用 — processFile 中当 !keep 且 absInput !== output 时 renameSync 原图为 *_original.{ext}；已在 risks 提示，批量前建议试跑或 -o。
[ok] sharp 依赖来源（无自带 package.json） — skill 目录确无 package.json；sharp 靠运行环境解析，缺失时仅在前几条 CLI 路径都不命中才会失败。
[ok] 选项表与脚本参数一致 — SKILL.md 的 7 个 option 与 parseArgs 处理的分支完全对应，默认值 format=webp、quality=80、keep/recursive/json=false。
[ok] 安全面与档位 — 零网络、零凭证、零配置解析；仅本地文件读写与系统 CLI 调用，判 blue 与前例一致。
[ok] meta 元数据 — commit dd0bf355…、path skills/canghe-compress-image、license MIT 与 bundle §0 核定值一致。

6結論

npmの必須依存関係がゼロ。インストールされているシステムツールに応じて動作するため、高いクロスプラットフォーム可用性を実現。

アトミックな書き込み + バッチ処理の耐障害性により、単一ファイルの失敗で一括圧縮全体が中断されない。

パラメータ構成がシンプルで、ドキュメントと実装の整合性が極めて高く、挙動の予測が容易。

安全性が高い：完全ローカル実行、ネットワーク通信ゼロ、認証情報不要。

最適な用途： 画像をWebPに一括変換または圧縮してファイルサイズを削減したい、依存関係なしで素早く導入したいライターやフロントエンド/コンテンツエンジニアに最適です。

不向きな用途： 可逆圧縮や不可逆圧縮の品質を細かく制御（カスタムエンコードパラメータの指定など）する必要がある本格的な画像パイプラインには不向きです。元のファイル名を保持したい自動化スクリプトにも不向きです（デフォルトで名前が変更されるため）。

Install Agent-Ready

① Verified Mirror 2026-10-10

Option A · Direct DownloadDownload canghe-compress-image.tar.gz

sha256: 346c02cfdb2597bb…

Option B · Copy Guide for Agent

install.json

Agent はこの JSON ガイドから自動的にダウンロードして検証します。

② Upstream GitHub

GitHub Repo ↗

Pinned to commit dd0bf35595.