Skip to content

Latest commit

 

History

History
115 lines (94 loc) · 5.42 KB

AGENTS-TODO.md

File metadata and controls

115 lines (94 loc) · 5.42 KB

AGENTS-TODO（OSS 图片服务差异清单）

目的：基于阿里云 OSS 图片处理文档，对比本项目当前实现，罗列尚未实现或行为差异的功能点，便于按优先级补齐。

提示：本项目当前已实现的最小集包括 image/resize（m_lfit|m_fill）、image/crop（g_center|north|south|east|west）、image/format（jpg|png）、video/snapshot、video/preview、派生内容缓存与派生 ETag、直出 Range 透传、签名与鉴权等。

— 以下均为“未实现/待补齐”的功能或差异 —

2) Crop（裁剪）

  • 绝对坐标裁剪：支持 x_/y_/w_/h_ 指定矩形区域（当前仅重心裁剪）
  • 九宫格/索引裁剪（indexcrop）
  • 按比例区域裁剪等扩展语法

3) 旋转/翻转/方向

  • image/rotate,<90|180|270...>
  • 显式 auto-orient 开关：image/auto-orient,0|1（当前默认总是自动，无法关闭）
  • 翻转/转置：flipH/flipV/transpose/transverse

4) 画质与压缩

  • image/quality,q_<0-100>（JPEG/WEBP/AVIF 等质量控制）
  • 渐进/交错：image/interlace,1（JPEG 渐进或 PNG 交错）
  • image/strip（去除 EXIF/ICC/元数据）
  • 细粒度选项：如 chroma subsampling、无损/有损切换等（按目标格式区分）

5) 输出格式

  • 目标格式扩展：gif、bmp、tiff、heic、avif 等（webp 已支持；需 CGO 与 libwebp 支持）
  • 针对格式的参数：
    • WebP：quality、lossless、method
    • AVIF：quality、speed、chroma、depth
    • GIF：是否保留动图、多帧处理策略

6) 滤镜与调色

  • 高斯模糊：image/blur,r_,s_
  • 锐化：image/sharpen[,参数]
  • 亮度/对比度/饱和度：image/bright、image/contrast、image/saturation
  • 灰度/反相/着色等常见滤镜（与 OSS 支持子集对齐）

7) 外观与几何

  • 圆角：image/rounded-corners,r_
  • 圆形：image/circle,r_
  • 边框/留白颜色：与 m_pad 联动的 color_ 参数（如 color_FFFFFF）

8) 水印

  • 文字水印：image/watermark,text_，字体/字号/颜色/透明度/旋转/位置（g_/x_/y_）
  • 图片水印：image/watermark,image_<url|base64>，缩放、透明度、平铺/单点、位置（g_/x_/y_）

8.1 文字水印（语法细节与 Base64 原因）

  • 语法（与 OSS 对齐，建议严格校验并给出明确错误）

    • x-oss-process=image/watermark, text_<Base64(UTF-8 文本)>, type_<Base64(字体名)>, size_<像素整数>, color_, t_<0-100>, rotate_<0-360>, g_<nw|north|ne|west|center|east|sw|south|se>, x_<偏移像素>, y_<偏移像素>

  • 参数说明

    • text_: 要渲染的文字内容，先 UTF-8，再 Base64。
    • type_: 字体名称，同样 Base64（例如常见 wqy-microhei → d3F5LW1pY3JvaGVp）。
    • size_: 字号（像素）。
    • color_: 颜色，6 位十六进制，不带 #（例如 FF0000）。
    • t_: 透明度 0–100（数值越大越不透明）。
    • rotate_: 旋转角度 0–360。
    • g_: 位置九宫格：nw|north|ne|west|center|east|sw|south|se。
    • x_/y_: 在 g_ 基准位置上的像素偏移（可为 0，正数向内偏移）。

  • 为什么 text_/type_ 需要 Base64

    • 允许中文、空格、标点、emoji 等任意字符安全传输，避免 URL 保留字符冲突。
    • 避免处理串中的分隔符（逗号、斜杠等）破坏解析。
    • 使签名与回放更稳定：不同客户端 URL-encode 细节差异较大，Base64 后字符集稳定。
    • 注意：若使用标准 Base64，结果中可能包含 + / =，请再做 URL 编码（或采用 URL-safe Base64：+→-，/→_，去掉尾部 =）。

  • 示例

    • 文本 “你好，OSS” 的 Base64：5L2g5aW977yMT1NT
    • 字体名 wqy-microhei 的 Base64：d3F5LW1pY3JvaGVp
    • 右下角（se）红色 40px，透明度 80，向内偏移 10px：
      • ?x-oss-process=image/watermark,text_5L2g5aW977yMT1NT,type_d3F5LW1pY3JvaGVp,size_40,color_FF0000,t_80,rotate_0,g_se,x_10,y_10

9) 信息与取色

  • image/info（返回图片元信息/EXIF）
  • 主色/平均色提取（average-hue/主色调）

10) 规则样式

  • x-oss-process=style/（基于 Bucket 预置样式名的处理）

11) 动图与多帧

  • 动图（GIF/Animated WebP/TIFF 多帧）处理：当前仅首帧，未对齐 OSS 对多帧保留/处理策略
  • 需要定义：是否保持动图、是否对每帧处理、是否可指定截取帧范围

12) 兼容性差异待对齐

  • 元数据保留策略可控（strip 开关）
  • 像素/边长/总像素等限制阈值与 OSS 文档对齐

参考链接（便于实现查阅）

建议的落地顺序（可调整）

  1. 扩充输出格式（webp/avif）+ quality/interlace/strip
  2. 增加 rotate/auto-orient 显式参数、x/y 裁剪
  3. 增加水印（text/image）与常用滤镜（blur/sharpen/bright/contrast）
  4. 外观（rounded-corners/circle）与样式名 style/
  5. 动图多帧处理策略与像素/放大限制对齐