BBDuck

优先做视觉无损压缩的本地图片压缩 skill：压缩单张图片、读取流式压缩日志，并在需要时打包下载结果 ZIP。

Security Scan

The skill's instructions, requirements, and behavior are internally consistent for a local image-compression helper, but it relies on running an unvetted Docker image (zhaoolee/bbduck:latest) which you should verify before executing locally.

Purpose & Capability

Name/description (local visual-lossless image compression, streaming logs, ZIP download) match the SKILL.md and README. The skill only needs to talk to a local bbduck service and handle image files, which is coherent with its stated purpose.

Instruction Scope

SKILL.md limits actions to calling local endpoints (http://127.0.0.1:28642), uploading user-supplied image files, reading NDJSON stream logs, and requesting ZIP downloads. It does not instruct reading arbitrary system files, accessing unrelated environment variables, or sending data to external endpoints.

Install Mechanism

There is no formal install spec (instruction-only), but README/SKILL.md recommend running a Docker image from Docker Hub (docker run -d -p 28642:8000 zhaoolee/bbduck:latest). Pulling and running an unvetted container is the primary operational risk because it will execute third-party code on the host; this is expected for a local service but should be noted.

Credentials

The skill declares no required env vars, credentials, or config paths. The runtime instructions operate solely on images provided by the user and the local HTTP service; no extraneous secrets or unrelated service credentials are requested.

Persistence & Privilege

Skill is instruction-only and not marked always:true. It does not request permanent presence or alter other skills' configs. Autonomous invocation is allowed (platform default) and is not combined with other concerning privileges.

Assessment

This skill appears to do what it says: call a local bbduck service to compress images with a visual-lossless default and read streaming logs. Before using it, be aware that the README suggests running docker run zhaoolee/bbduck:latest — pulling and running that container will execute third-party code on your machine. If you plan to run the container, verify the image source (owner, Docker Hub page, image digest), run it in a sandbox or isolated environment, or build from source if available. Also confirm you only upload images you intend to compress (the service runs locally at 127.0.0.1) and that no unexpected external endpoints are used.

当需要调用本地运行的 BBDuck 图片压缩服务时，使用这个 skill。

它的核心优势不是“极限压缩”，而是：

• 优先保证肉眼观感基本不变
• 在网页默认策略下直接走 visual-lossless
• 压缩过程中可以实时读取每一步日志
• 日志里包含每一步的 spend_time_ms
• 压缩完成后仍可继续打包下载 ZIP

服务前提

默认连接本地 Docker 服务：

docker run -d -p 28642:8000 zhaoolee/bbduck:latest

默认访问地址：

• API 根地址：http://127.0.0.1:28642
• Swagger UI：http://127.0.0.1:28642/docs
• OpenAPI JSON：http://127.0.0.1:28642/openapi.json

适用图片类型

• jpg / jpeg
• png
• webp
• gif

默认压缩模式

默认和网页保持一致：

• visual-lossless

只要用户没有明确要求更激进的策略，就按 visual-lossless 调用，不要擅自切到 safe 或 aggressive。

这个 skill 最适合的场景

1. 用户要“尽量压小，但看起来别变”

这是首选场景。

2. 用户要看压缩过程

优先使用流式接口，边压缩边读日志。

3. 用户要拿到压缩后的文件合集

压缩结束后，用 ZIP 接口统一下载。

推荐接口

1. 单张图片压缩并获取流式日志

优先使用：

• POST /api/compress/stream

原因：

• 可以压缩单张图片
• 可以持续读取后端返回的 NDJSON 日志
• 可以拿到每一步的 message
• 可以拿到每一步的 spend_time_ms
• 最后一条会返回 result

2. 批量下载压缩结果

当用户明确要“下载全部压缩图”时，使用：

• POST /api/download/outputs.zip

单张压缩调用规则

请求方式

用 multipart/form-data 发送：

• files: 单张图片文件
• parallelism: 传 1

如果接口未来支持 profile 参数，也优先传：

• compression_profile=visual-lossless

当前若未显式提供 profile，则服务默认就是 visual-lossless。

返回流格式

/api/compress/stream 返回 application/x-ndjson。 每一行都是一条 JSON，常见类型：

• log
• error
• result

日志处理规则

当读取到：

• type=log
  • 记录 message
  • 如果有 spend_time_ms，一起记录
• type=error
  • 立即视为失败
  • 输出错误信息
• type=result
  • 记录最终压缩结果
  • 结果里通常包含：
    • file_name
    • original_size
    • compressed_size
    • original_url
    • compressed_url
    • mime_type
    • status
    • algorithm
    • metrics

curl 示例：单张图片压缩并查看流式日志

curl -N -X POST http://127.0.0.1:28642/api/compress/stream \
  -F 'parallelism=1' \
  -F 'files=@/absolute/path/to/demo.png'

如果服务端后来支持显式传 profile，可用：

curl -N -X POST http://127.0.0.1:28642/api/compress/stream \
  -F 'parallelism=1' \
  -F 'compression_profile=visual-lossless' \
  -F 'files=@/absolute/path/to/demo.png'

典型流式响应示例

{"type":"log","stage":"start","message":"开始压缩 demo.png","spend_time_ms":0}
{"type":"log","stage":"candidate","message":"生成候选 pngquant-85-98：12.3 KB","spend_time_ms":37}
{"type":"result","item":{"file_name":"demo.png","status":"completed","algorithm":"png-pillow-optimize"}}

ZIP 下载请求体

{
  "files": [
    {
      "stored_name": "8b0a-demo.compressed.webp",
      "download_name": "demo-compressed.webp"
    }
  ]
}

ZIP 下载字段含义

• stored_name: 后端真实保存的文件名，通常从 compressed_url 的最后一段提取
• download_name: ZIP 包里给用户看到的文件名

使用步骤建议

场景 1：用户要压缩一张图并查看过程

1. 调用 POST /api/compress/stream
2. 上传 1 张图片
3. 读取并整理 log 事件
4. 展示每一步 message 与 spend_time_ms
5. 收到 result 后再汇总压缩结果

场景 2：用户要下载全部压缩图

1. 先从压缩结果里的 compressed_url 提取文件名
2. 组装 files 数组
3. 调用 POST /api/download/outputs.zip
4. 将返回内容保存为 zip 文件

输出时应强调的价值

在向用户总结结果时，优先突出这些信息：

• 这次压缩走的是 visual-lossless
• 重点是“看起来基本不变，但体积更小”
• 如果有日志，展示关键步骤和每一步 spend_time_ms
• 如果结果被跳过，也要说明原因，而不是硬说压缩成功

规则

• 这个 skill 默认连本地容器服务：http://127.0.0.1:28642
• 默认压缩模式按网页行为处理：visual-lossless
• 当用户要看压缩过程时，优先用 /api/compress/stream
• 当用户只说“压缩一张图片”，也优先用 /api/compress/stream，因为它同时给结果和日志
• 只有在用户明确要“批量下载压缩图”时，才调用 /api/download/outputs.zip
• 不要把 jpg、jpeg、png、webp、gif 之外的文件交给这个服务
• 不要把这个 skill 描述成“追求极限画质损失换取极限压缩率”的工具；它的默认卖点是视觉无损优先