lake-cimg 1.0.1 → 1.1.0

package/README.md

@@ -10,7 +10,6 @@
 - 处理过程输出体积对比；失败时非零退出码
 - **`picture` 子命令**：从单张 PNG/JPEG/WebP 源图一次生成 **AVIF + WebP + JPEG**，配合前端 `<picture>` 做渐进增强（不支持 GIF 动图源）
 - **`scan-code` 子命令**：扫描源码中的图片引用并结合真实像素尺寸给出 CLS / 比例等建议（只读）
-- **Agent Skill**：通过 [`npx skills add`](https://www.npmjs.com/package/skills) 安装 [`skills/cimg-audit`](skills/cimg-audit/SKILL.md)（技能名 **`cimg-audit`**，好记），在 Cursor 等环境里用自然语言驱动 `npx lake-cimg@latest …`
 
 ## 环境要求
 
@@ -156,38 +155,6 @@ npx lake-cimg@latest scan-code [path] [--no-recursive] [--limit <n>] [--issues-o
 
 适合在构建脚本或 Node 服务中复用同一套逻辑。
 
-## Agent Skill（Skills CLI / `npx skills add`）
-
-本仓库按 [Skills CLI](https://www.npmjs.com/package/skills) 约定提供可安装 Skill，见目录 [`skills/`](skills/README.md)（与 [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) 的 `skills/<name>/SKILL.md` 布局一致）。技能目录名为 **`cimg-audit`**（短、与包名一致，便于 `-s cimg-audit`）。
-
-**何时需要 / 触发条件（选用本 Skill 的典型场景）**
-
-- 对话或任务涉及：**图片体积与格式**（WebP/AVIF）、**`<picture>` / `srcset`**、**LCP / CLS / layout shift**、首屏大图
-- 要先做**只读**引用审计再改代码：用 **`npx lake-cimg@latest scan-code`** 出 JSON，再按需改标签或压缩
-- 希望 Agent **按固定流程**：先 `scan-code` → 再按需 `npx lake-cimg@latest` 压缩或 `picture` 多格式输出
-
-更细的英文说明见 [`skills/README.md` 的「When to use」一节](skills/README.md#when-to-use)。
-
-**从 GitHub 安装**（需已推送；将 `lake0090/lake-cimg` 换成你的 fork 若不同）：
-
-```bash
-# 安装到用户级（-g），仅本 skill（-s），跳过确认（-y）
-npx skills add lake0090/lake-cimg -s cimg-audit -g -y
-
-# 仅安装到当前项目
-npx skills add lake0090/lake-cimg -s cimg-audit -y
-```
-
-**本地克隆开发时**（在仓库根目录执行）：
-
-```bash
-npx skills add . -s cimg-audit -y
-```
-
-可选：`--agent cursor` 等，见 `npx skills add --help`。Skill 正文在 [`skills/cimg-audit/SKILL.md`](skills/cimg-audit/SKILL.md)，指导用 **`npx lake-cimg@latest scan-code`** 与压缩 / `picture` 子命令配合使用。
-
-安装 Skill 后，在 Agent 对话里可直接让模型按 Skill 流程执行（例如：先 `scan-code` 再按需压缩）；CLI 与 `npx` 均在本地执行，图片不会上传到云端。
-
 ## 常见问题
 
 - **写权限**：`-o` 指向的目录需可创建/写入；否则 sharp 或 `fs` 会报错。
@@ -198,7 +165,7 @@ npx skills add . -s cimg-audit -y
 
 - **Lighthouse 审计**：后续接入 [Lighthouse](https://developer.chrome.com/docs/lighthouse)（或 CI 中的 Lighthouse CI），对典型页面做性能 / 最佳实践等审计。
 - **审计前后对比**：在引入 `scan-code`、压缩、`picture` 等优化前后各跑一轮，保存报告（JSON/HTML），对比 LCP、CLS、资源体积等指标，量化改动效果。
-- **专项优化**：根据 Lighthouse 报告中的具体项（如 LCP 候选、未使用 CSS、图片尺寸等）做针对性迭代，与现有 CLI / Skill 工作流互补。
+- **专项优化**：根据 Lighthouse 报告中的具体项（如 LCP 候选、未使用 CSS、图片尺寸等）做针对性迭代，与现有 CLI 工作流互补。
 
 ## 发布到 npm（维护者）
 

package/bin/cimg.js

@@ -298,7 +298,7 @@ program
   .command("scan [input]")
   .description("扫描图片并给出优化建议（不修改文件）")
   .option("-r, --recursive", "递归处理子目录")
-  .option("--json", "以 JSON 格式输出（适合 AI/脚本消费）")
+  .option("--json", "以 JSON 格式输出（适合脚本与工具消费）")
   .action(async function scanAction(input, opts) {
     if (!input || input.trim() === "") {
       this.outputHelp();

package/lib/compress.js

@@ -17,6 +17,9 @@ import {
   encodeJpegBuffer,
 } from "./sharpHelpers.js";
 
+/** 小于此体积跳过压缩 */
+const THRESHOLD_SKIP_FOR_AGENT = 10 * 1024;
+
 /** Max concurrent tasks for processing images */
 const MAX_CONCURRENCY = Math.max(1, cpus().length);
 
@@ -104,7 +107,9 @@ export async function collectFiles(inputPath, recursive = false) {
  *   originalHeight: number | null,
  *   width: number | null,
  *   height: number | null,
- *   format: string | null
+ *   format: string | null,
+ *   skipped?: true,
+ *   reason?: "small" | "larger"
  * }>}
  */
 export async function processOne(inputPath, options = {}) {
@@ -119,6 +124,21 @@ export async function processOne(inputPath, options = {}) {
 
   const inputBuffer = await readFile(inputPath);
   const sizeBefore = inputBuffer.length;
+  if (sizeBefore < THRESHOLD_SKIP_FOR_AGENT) {
+    return {
+      outPath,
+      sizeBefore,
+      sizeAfter: sizeBefore,
+      originalWidth: null,
+      originalHeight: null,
+      width: null,
+      height: null,
+      format: null,
+      skipped: true,
+      reason: "small",
+    };
+  }
+
   let pipeline = sharp(inputBuffer, { animated: true });
   const inputMeta = await pipeline.metadata();
 
@@ -128,8 +148,23 @@ export async function processOne(inputPath, options = {}) {
     ? await encodeWebpBuffer(pipeline, quality, { lossless: false })
     : await toFormatBuffer(pipeline, ext, quality);
 
-  const outputMeta = await sharp(outputBuffer).metadata();
   const sizeAfter = outputBuffer.length;
+  if (sizeAfter > sizeBefore) {
+    return {
+      outPath,
+      sizeBefore,
+      sizeAfter,
+      originalWidth: inputMeta.width ?? null,
+      originalHeight: inputMeta.height ?? null,
+      width: null,
+      height: null,
+      format: null,
+      skipped: true,
+      reason: "larger",
+    };
+  }
+
+  const outputMeta = await sharp(outputBuffer).metadata();
   await mkdir(outBase, { recursive: true });
   await writeFile(outPath, outputBuffer);
   return {
@@ -166,7 +201,7 @@ async function toFormatBuffer(pipeline, ext, quality) {
 /**
  * Run batch compression.
  * @param {{ inputPath: string, outDir?: string | null, size?: number | null, quality?: number, recursive?: boolean }} options
- * @returns {Promise<{ success: number, failed: number }>} success/failed counts; throws if input invalid
+ * @returns {Promise<{ success: number, failed: number, skipped: number }>} counts; throws if input invalid
  */
 export async function run(options) {
   const {
@@ -208,13 +243,30 @@ export async function run(options) {
 
   let success = 0;
   let failed = 0;
+  let skipped = 0;
   let totalBefore = 0;
   let totalAfter = 0;
   for (let i = 0; i < files.length; i++) {
     const r = results[i];
     const fp = files[i];
     if (r.status === "fulfilled") {
-      const { outPath, sizeBefore, sizeAfter } = r.value;
+      const v = r.value;
+      if (v.skipped) {
+        skipped++;
+        if (v.reason === "small") {
+          console.log(`  ⏭  ${fp}`);
+          console.log(
+            `     不处理：原图 ${formatSize(v.sizeBefore)} 小于 10KB（无需压缩）`
+          );
+        } else {
+          console.log(`  ⏭  ${fp}`);
+          console.log(
+            `     不处理：压缩后 ${formatSize(v.sizeAfter)} 大于原图 ${formatSize(v.sizeBefore)}（已保留原图、未写出新文件）`
+          );
+        }
+        continue;
+      }
+      const { outPath, sizeBefore, sizeAfter } = v;
       totalBefore += sizeBefore;
       totalAfter += sizeAfter;
       console.log(`  ✅ ${fp} → ${basename(outPath)}`);
@@ -225,9 +277,10 @@ export async function run(options) {
       failed++;
     }
   }
-  console.log(`\n完成：成功 ${success}，失败 ${failed}。`);
+  const skipPart = skipped > 0 ? `，跳过 ${skipped}（<10KB 或压缩后更大）` : "";
+  console.log(`\n完成：成功 ${success}，失败 ${failed}${skipPart}。`);
   if (success > 0 && totalBefore > 0) {
     console.log(`合计：${formatCompare(totalBefore, totalAfter)}`);
   }
-  return { success, failed };
+  return { success, failed, skipped };
 }

package/lib/scan.js

@@ -7,6 +7,8 @@ import sharp from "sharp";
 import { collectFiles } from "./compress.js";
 
 const KB = 1024;
+/** 小于此体积一般无压缩收益，建议标记为不处理 */
+const THRESHOLD_SKIP_FOR_AGENT = 10 * KB;
 const THRESHOLD_LARGE_NON_WEBP = 100 * KB;
 const THRESHOLD_LARGE_WEBP = 500 * KB;
 const MAX_EDGE = 1920;
@@ -25,6 +27,9 @@ function formatSize(bytes) {
  * @returns {string}
  */
 function computeSuggestion(sizeBytes, format, width, height) {
+  if (sizeBytes < THRESHOLD_SKIP_FOR_AGENT) {
+    return "不处理：原图 <10KB（体积过小，无需压缩）";
+  }
   const fmt = (format ?? "").toLowerCase();
   if (fmt !== "webp" && sizeBytes > THRESHOLD_LARGE_NON_WEBP) {
     return "convert to webp";

package/lib/scanCodeReferences.js

@@ -895,7 +895,7 @@ export async function scanCodeReferences(rootDir, options = {}) {
       fmt
     ) {
       issues.push("suggest_modern_format");
-      hints.push("可考虑 WebP/AVIF 或 cimg picture 子命令生成多格式 <picture>");
+      hints.push("可考虑 WebP 格式");
     }
 
     const row = {

package/package.json

@@ -1,15 +1,13 @@
 {
   "name": "lake-cimg",
-  "version": "1.0.1",
-  "description": "Batch image compression to WebP — CLI plus Agent Skills for frontend image audit (scan-code, picture stack)",
+  "version": "1.1.0",
+  "description": "Batch image compression to WebP — CLI with picture stack and scan-code for frontend image audit",
   "keywords": [
     "image",
     "compress",
     "webp",
     "sharp",
-    "agent-skills",
-    "skills",
-    "cursor"
+    "cli"
   ],
   "repository": {
     "type": "git",
@@ -23,8 +21,7 @@
   "files": [
     "bin",
     "lib",
-    "README.md",
-    "skills"
+    "README.md"
   ],
   "publishConfig": {
     "access": "public"

package/skills/README.md

@@ -1,40 +0,0 @@
-# Skills (Skills CLI)
-
-This directory follows the layout expected by **[Skills CLI](https://www.npmjs.com/package/skills)** (`npx skills add`), same idea as [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills): each subfolder is one skill with a `SKILL.md`.
-
-| Skill | Summary |
-| --- | --- |
-| [cimg-audit](./cimg-audit/SKILL.md) | Audit `<img>` / Pug `img()` / imports / `url()` for CLS, aspect ratio, and format hints via `npx lake-cimg@latest scan-code` |
-
-### When to use
-
-Skill id **`cimg-audit`** — use it when the conversation or task touches:
-
-- **Performance / layout:** CLS, layout shift, LCP, hero images, `fetchPriority`
-- **Markup / assets:** `<img>` dimensions, `aspect-ratio`, `<picture>`, `srcset` / `sizes`, WebP / AVIF
-- **Workflow:** run **`scan-code`** first (read-only JSON), then fix markup and/or compress with **`npx lake-cimg@latest`** / **`picture`**
-
-The skill name `cimg-audit` is short for discovery; the YAML `description` in `SKILL.md` is what agents match against.
-
-Install from GitHub (after push):
-
-```bash
-npx skills add lake0090/lake-cimg -s cimg-audit -g -y
-```
-
-Install only this repo’s skill into the **current project** (run from another repo):
-
-```bash
-npx skills add lake0090/lake-cimg -s cimg-audit -y
-```
-
-Develop locally from a clone of this repository:
-
-```bash
-cd /path/to/lake-cimg
-npx skills add . -s cimg-audit -y
-```
-
-Use `-g` for a user-level install (`~/.cursor/skills/` etc., depending on agent). See `npx skills add --help` for `--agent` (e.g. `cursor`).
-
-Browse the registry at [skills.sh](https://skills.sh/).

package/skills/cimg-audit/SKILL.md

@@ -1,63 +0,0 @@
----
-name: cimg-audit
-description: >-
-  Audits HTML, Vue, Pug, JS, TS, TSX, and JSX image references against intrinsic
-  dimensions for CLS risk, aspect-ratio mismatches, and modern-format hints.
-  Use when optimizing images, fixing layout shift, LCP heroes, picture/srcset,
-  or running lake-cimg scan-code via npx lake-cimg@latest.
----
-
-# cimg image audit
-
-Run **`npx lake-cimg@latest`** from the **project root** (no global install).
-
-<a id="invoke-scan-code"></a>
-
-## Invoke `scan-code`
-
-Use **one** command starting with `npx` — **not** `cd … && npx …` (PowerShell 5.1 on Windows does not support `&&`).
-
-| `path` | Behavior |
-| --- | --- |
-| *(omitted)* | Scans **`.`** (current working directory). Run from repo root to cover the tree. |
-| **Directory** | Recursively scans supported sources under that folder (honors `--no-recursive`). |
-| **Single file** | Only that file. Extension must be `.html`, `.htm`, `.vue`, `.pug`, `.js`, `.mjs`, `.cjs`, `.ts`, `.tsx`, or `.jsx`. |
-
-**Output:** stdout is **only** pretty-printed JSON: `items[]` with `issues`, `hints`, `snippet`, `intrinsicWidth` / `intrinsicHeight` when metadata was read, plus top-level `summary` and scan metadata. **`--issues-only`** drops rows with empty `issues`. For **`missing_dimensions`**, use **`intrinsicWidth` / `intrinsicHeight`** on the same item and/or the English hint that repeats them.
-
-**Examples:**
-
-```bash
-npx lake-cimg@latest scan-code
-npx lake-cimg@latest scan-code /absolute/path/to/src
-npx lake-cimg@latest scan-code /absolute/path/to/about.pug
-```
-
-More flags: `npx lake-cimg@latest scan-code --help` (e.g. `--limit`, `--issues-only`, `--no-recursive`). Prefer an **absolute** `path` if the shell cwd may not be the repo root.
-
-## Workflow
-
-- [ ] **1. Scan (read-only):** `npx lake-cimg@latest scan-code [path]` — see **Invoke `scan-code`** above.
-- [ ] **2. Triage:** Prefer **`hints`** for what to change; use **`issues`** codes to group or filter. Common codes: `missing_dimensions`, `aspect_ratio_mismatch`, `suggest_modern_format` (default: **single WebP** — point `src` / `srcset` at `.webp` after exporting; use **`<picture>`** with AVIF/WebP + legacy fallback **only if the user explicitly asks** for multi-format markup or old-browser JPEG/PNG fallback), `needs_manual_review`, `missing_src`, `cannot_resolve`, `cannot_read_metadata`.
-- [ ] **3. Fix then optimize:** Apply markup using [reference.md](reference.md) (`<img>` first; `<picture>` only when the user requires it). For **all** raster refs that need format or responsive delivery, not only one hero row. Compress / emit WebP: `npx lake-cimg@latest <path> [options]`. **Optional** full stack for `<picture>` when requested: `npx lake-cimg@latest picture <input> -O <outDir>` (details: package [README.md](../../README.md)).
-
-## Rules of thumb
-
-- **Aspect ratio:** Match display ratio to intrinsic (w÷h), or use **`object-fit`** + explicit box / `aspect-ratio` for crop/letterbox.
-- **CLS:** Add `width` and `height` to `<img>`, or use CSS `aspect-ratio`. For `missing_dimensions`, fill in the exact `intrinsicWidth` / `intrinsicHeight`.
-- **Responsive:** **`srcset` + `sizes`** on `<img>` (works with a single WebP). **`<picture>`** only when the user wants multiple formats in HTML; each `<source type="…">` must match the real file type. Width variants: separate files or `picture … -s <px>` when building a stack.
-- **LCP:** At most one hero per view: **`fetchPriority="high"`**, **`loading="eager"`**; lazy-load the rest.
-- **Alt:** Describe content and purpose; no keyword stuffing; **`alt=""`** only for decorative images.
-
-## What the scanner cannot resolve
-
-Dynamic **`src`** without a static path → **`needs_manual_review`**. **`http(s):`**, **`data:`**, and path aliases (**`@/`**, **`~/`**, etc.) → **`cannot_resolve`** (no alias map reads; no network fetch).
-
-If **`hints`** mention alias skip: use **`rawRef`** and map the alias via Vite/webpack/tsconfig/Nuxt config. With a **real filesystem path**, run `npx lake-cimg@latest scan <resolved-path>` on assets or re-run **`scan-code`** on markup that uses resolvable relative paths. If unresolved, triage without intrinsic dimensions.
-
-## Other CLI (after scan-code)
-
-| Command | Role |
-| --- | --- |
-| `npx lake-cimg@latest <path>` | Compress / WebP — see `npx lake-cimg@latest --help` (`-o`, `-s`, `-q`, `-r`). |
-| `npx lake-cimg@latest picture <input> -O <outDir>` | One raster → AVIF + WebP + JPEG **when the user wants `<picture>` / multi-format**; not the default if single WebP is enough. |

package/skills/cimg-audit/reference.md

@@ -1,49 +0,0 @@
-# Image markup templates
-
-Supplement for [SKILL.md](SKILL.md). Copy-paste starting points; adjust paths, dimensions, and `sizes` to match your assets and layout.
-
-## Basic `<img>`
-
-**When:** Single raster URL; reserve space for CLS. **Check:** `width` / `height` match intrinsic pixels (or use `aspect-ratio` for fluid); meaningful `alt` or `alt=""` if decorative.
-
-```html
-<img
-  srcset="
-    maine-coon-nap-320w.webp 320w,
-    maine-coon-nap-480w.webp 480w,
-    maine-coon-nap-800w.webp 800w
-  "
-  sizes="(max-width: 320px) 280px, (max-width: 480px) 440px, 800px"
-  src="maine-coon-nap-800w.webp"
-  alt="A watercolor illustration of a maine coon napping leisurely in front of a fireplace"
-/>
-```
-
-## `<picture>` + `srcset` + `sizes`
-
-**When:** AVIF/WebP stack with JPEG (or similar) fallback; responsive widths. **Check:** Each `<source type="…">` matches the real file type; `sizes` matches breakpoints; `<img>` is the final fallback with matching `srcset` / `sizes`.
-
-```html
-<picture>
-  <source
-    type="image/avif"
-    srcset="hero-400.avif 400w, hero-800.avif 800w, hero-1200.avif 1200w"
-    sizes="(max-width: 600px) 100vw, 50vw"
-  />
-  <source
-    type="image/webp"
-    srcset="hero-400.webp 400w, hero-800.webp 800w, hero-1200.webp 1200w"
-    sizes="(max-width: 600px) 100vw, 50vw"
-  />
-  <img
-    src="hero-800.jpg"
-    srcset="hero-400.jpg 400w, hero-800.jpg 800w, hero-1200.jpg 1200w"
-    sizes="(max-width: 600px) 100vw, 50vw"
-    width="1200"
-    height="600"
-    alt="Describe subject and purpose on this page"
-    loading="lazy"
-    decoding="async"
-  />
-</picture>
-```