RustFS 图像插件模板

给 AI coding agent 的任务提示词

你正在基于 RustFS OCI 插件模板开发一个独立的对象处理插件。先阅读本 README、src/main.rs 和 Cargo.toml，再按我的业务要求修改。保持 Runner 的 rustfs.job/v2alpha1 输入与本地制品输出合同：从 /input/input.json 读取完整 attempt identity、精确对象版本和有界参数；从 /credentials/credential.json 读取短期凭据；只读获取指定版本；只把产物和 result.json 写到 /output。使用 Rust 和 libvips 实现图像操作，为每个新分支补测试。拒绝缺失或 null versionId、未知字段、越界尺寸和不支持的格式。禁止把凭据放进日志、命令行、环境变量或结果文件。完成后运行 README 中的测试和 Docker 构建，报告实际命令、结果、支持范围和未实现能力。

请把这段提示词连同具体业务需求交给 agent。它会把本目录作为可运行模板，不需要先猜 Runner 的容器文件协议。

当前样例

样例接收已版本化的 RustFS 图片对象，使用 Runner 提供的短期只读 S3 凭据获取指定 versionId，再用 libvips 做缩略处理和格式转换。它支持：

等比缩小并限制在目标宽高内（fit: "inside"）；
等比缩小并居中裁剪（fit: "cover"）；源图不足时不放大，结果会小于目标边长；
根据图片方向元数据自动旋正；
输出 PNG、JPEG 或 WebP；JPEG/WebP 使用 libvips 默认编码质量。

这个测试插件只实现上述基础操作。腾讯云数据万象还覆盖水印、模糊、锐化、EXIF/主色调、动图和智能处理等能力；这些都不是本样例已支持的功能。后续可以按需把单项能力做成明确参数和测试，不要在 manifest 或 README 中宣称未实现的功能。

Runner 文件合同

Runner 会把以下只读文件和可写目录挂进容器：

/input/input.json：rustfs.job/v2alpha1，包含 attempt、object 和 parameters；object.version 必须是具体非空版本，不能是 S3 的 null 哨兵。
/credentials/credential.json：access_key、secret_key 和可选 session_token。这是 attempt 级短期凭据，只用于读源对象。
/output/：唯一可写目录。插件写入 image.png、image.jpg 或 image.webp，并写 result.json 声明文件名和原始完整 attempt identity。Runner 负责把本地产物上传到受控结果桶并绑定精确版本。

最小输入示例：

{
  "schema": "rustfs.job/v2alpha1",
  "attempt": {
    "platform": "example",
    "run": "00000000-0000-4000-8000-000000000001",
    "attempt": "00000000-0000-4000-8000-000000000002",
    "epoch": "1",
    "session": "00000000-0000-4000-8000-000000000003",
    "control_generation": "generation-1"
  },
  "object": {
    "bucket": "images",
    "key": "uploads/photo.jpg",
    "version": "3Lg...exact-version"
  },
  "parameters": {
    "width": 320,
    "height": 240,
    "fit": "cover",
    "format": "webp"
  }
}

parameters 可省略：默认 320×240、inside、WebP。源对象上限为 32 MiB，解码像素上限为 50 MP，目标边长上限为 10,000 像素，输出上限为 Runner 的 16 MiB 本地制品预算。容器应通过 CLI --endpoint 和 --region 接收存储地址，不接受密钥参数；HTTPS 是默认要求，仅 loopback HTTP 允许本地 smoke test。

结果文件形状：

{
  "schema": "rustfs.job/v2alpha1",
  "attempt": { "与输入完全相同的 identity" },
  "outcome": "ACCEPTED",
  "artifacts": [{ "name": "image", "file": "image.webp" }]
}

构建与测试

需要 Docker Compose v2 或 Docker CLI，并使用与 Runner 节点相同的 CPU 架构构建。直接运行 Cargo 测试还需要安装 libvips 开发包和 pkg-config；Docker 构建会准备这些依赖并运行单测，运行镜像只带二进制、CA 证书和 libvips 运行库：

cargo test --locked --manifest-path examples/plugin-template-image/Cargo.toml
docker build -t rustfs-image-transform:dev examples/plugin-template-image

把镜像构建并签名后，按 Runner 的受信镜像流程配置 digest 和发布者，不要让 Runner 通过 tag 或无约束 pull 取得镜像。任务命令示例：

["/usr/local/bin/rustfs-image-transform", "--endpoint", "https://s3.example.internal:9000", "--region", "us-east-1"]

扩展边界

每次扩展先决定输入参数、尺寸/像素/帧/内存上限、输出格式与失败语义，然后为变换和边界条件加测试。增加水印或检测能力时，明确字体、图片资源从哪里来，以及是否需要额外权限；不要假设容器可写宿主文件或能访问任意网络。生产镜像应继续使用 Runner 实施的非 root、只读根文件系统、网络出口限制、CPU/内存/PID 和输出容量限制。

功能参考：腾讯云数据万象图片处理；处理引擎：libvips 操作列表；Rust bindings：libvips crate。

README.md Unescape Escape