v0.2.5

Add four providers: CTYun OOS (ctyun, unified + resource-pool + Hong Kong endpoints), CUCloud OSS (cucloud, industry-cloud regions), China Mobile EOS (eos, 30 public regions), QingCloud QStor (qingstor, S3-compatible qsstor.com); wired into --provider, find probes and URL auto-recognition (default find probes 71 -> 130, --global 167 -> 226).
Implement URL recognition for Wasabi, DigitalOcean Spaces, Yandex, Exoscale and Arvan (documented before but never matched in code).
Document unsupported vendors with reasons: UPYUN USS (proprietary REST protocol, not S3-compatible); Qiniu Kodo stays removed (anonymous probes always 400; bucket domains are bound CDN domains).
Replace a leftover private test bucket name in scan_test.go with a neutral placeholder.

v0.2.4

场景

• 部分目录转发 / 反向代理类 S3 站点，桶根只有在带尾斜杠时才直接应答 S3 列举；
  客户端按 S3 惯例发出不带尾斜杠的桶根请求（/bucket）时，站点 301 到一个内部端口
  （Web 应用端口，不提供 S3 API）→ 客户端跟随跳转后得到 404。浏览器看不出问题，
  因为它访问的本来就是带斜杠的地址。

修复

• s3x 客户端新增重定向策略 slashPreservingRedirect：当 3xx 只是给路径追加
  尾斜杠、但同时改写了主机/端口/协议（内部端口跳转）时，把目标改写回原始 origin
  • 尾斜杠并跟随——命中该类网关的桶根列出恢复正常；其余重定向（同源跳转、区域
    跳转等）保持 Go 默认行为（含 10 次上限），不受影响
• 新增两个单测：quirk 场景改写验证 + 普通同源跳转不受影响的回归

---

v0.2.4 — fix 404 listing on a class of path-forwarded gateway roots

Scenario

• Some path-forwarded / reverse-proxied S3 sites only answer bucket listings
  when the bucket root carries a trailing slash. A client sending the
  conventional slash-less root (/bucket) is 301'd to an internal port (a web
  app that does not serve the S3 API), and following the redirect yields 404.
  Browsers never hit this because users open the slashed URL.

Fix

• The s3x client now uses slashPreservingRedirect: when a 3xx merely
  appends a trailing slash but also rewrites host/port/scheme (internal-port
  redirect), the target is rewritten back to the original origin with the
  slash appended — bucket-root listings on such gateways work again. All
  other redirects (same-origin, regional, ...) keep Go's default policy
  including the 10-redirect cap
• Two new unit tests: the quirk rewrite + a same-origin regression case

v0.2.3

修复（关键）

• CLI 中间件把派发上下文丢弃、改用 context.Background() 调用各命令，导致
  SIGINT/SIGTERM 取消信号无法传入 handler——oss serve 收到 SIGTERM 后不再
  优雅关停（挂起直至强杀）、oss cat/ls 等大输出场景 Ctrl-C 也无法中断。
  已修复为透传信号上下文：serve/mcp 恢复 1 秒内优雅退出，流式命令可随时中断

升级

• xyz-go v0.3.1 → v0.3.2：serve/mcp 改用其新的 CliHints.Daemon 声明式标记
  （长驻命令：隐式不进入 HTTP/MCP 通道、不渲染返回值、ctx 取消即退出 0），
  替代此前仅靠"不给 HTTP/MCP hint"的约定式隔离

---

v0.2.3 — fix signal cancellation; xyz-go v0.3.2 declarative daemon commands

Fix (critical)

• The CLI middleware discarded the dispatch context and invoked handlers
  with context.Background(), so SIGINT/SIGTERM never reached them — oss serve
  no longer shut down gracefully on SIGTERM (hanging until force-killed), and
  long streaming commands (cat/ls) could not be interrupted with Ctrl-C.
  The signal context is now passed through: serve/mcp exit gracefully within
  a second, streaming commands can be interrupted at any time

Upgrade

• xyz-go v0.3.1 → v0.3.2: serve/mcp adopt the new CliHints.Daemon marker
  (blocking commands: implicitly excluded from the HTTP/MCP channels, no
  result rendering, exit 0 on ctx cancellation), replacing the previous
  convention-only isolation

v0.2.2

修复

• 启动告警：此前在 Go/CPU 组合超出 sonic 加速矩阵的环境（如 Go >1.26 或非
  amd64/arm64 构建）上，bytedance/sonic 的 ast 包会在进程启动时向 stderr 打印
  "WARNING: sonic/ast only supports …" 并回退 encoding/json——功能无损但每次运行
  首行都是告警。已整体移除 sonic（及 sonic/loader 间接依赖），JSON 编解码改用
  标准库 encoding/json：任何环境下启动输出都不再有任何第三方提示
• 附带变化：NDJSON/JSON 输出中对象字段按字典序排列（encoding/json 行为），
  字段本身的语义不变

升级

• xyz-go v0.2.4 → v0.3.1：接入其新 i18n 目录（langx），并把它与 oss 的语言检测
  对齐——xyz 框架内置文案（如"位置参数数量不符"）现在同样双语：
  中文环境显示中文，OSS_LANG=en/LANG=en_US 等英文环境显示英文
• 借 v0.3.1 顺带修复 v0.2.0 不一致清单第 2 条的"位置参数数量不符为库内中文文案"一项

---

v0.2.2 — drop the sonic startup warning; xyz-go v0.3.1 bilingual UI

Fix

• Startup warning: on environments outside sonic's acceleration matrix
  (Go >1.26, or non-amd64/arm64 builds), bytedance/sonic's ast package printed
  "WARNING: sonic/ast only supports …" to stderr at init and fell back to
  encoding/json — harmless but noisy on every run. sonic (including the
  sonic/loader indirect dep) is now removed entirely; JSON encoding uses
  the standard library, so no third-party notice ever appears at startup
• Side effect: JSON object fields are now rendered in alphabetical order
  (encoding/json behavior); field semantics are unchanged

Upgrade

• xyz-go v0.2.4 → v0.3.1: wired its new i18n catalog (langx) to oss's language
  detection — framework messages (e.g. the positional-count error) are now
  bilingual too: Chinese on Chinese systems, English on
  OSS_LANG=en/LANG=en_US
• This also closes the "framework Chinese-only message" note from the v0.2.0
  deviations list

v0.2.1

修复

• CLI 运行时错误（解析失败、桶不存在、拒绝访问等 handler 错误）恢复退出码 1
  （v0.2.0 中未分类错误被 xyz 前端按用法错误处理、退出 2）；用法类错误
  （未知 flag、位置参数数量不符）仍按 xyz 语义退出 2

---

v0.2.1 — fix runtime-error exit codes

Fix

• Runtime handler errors (parse failures, missing buckets, access denials)
  exit 1 again (in v0.2.0 uncoded errors were treated as usage errors and
  exited 2); usage errors (unknown flags, positional-count mismatches) keep
  xyz's exit code 2

v0.2.0

变更

• 命令行前端从 urfave/cli 整体迁移到 xyz-go v0.2.4：ls/stat/cat/presign/find 与
  HTTP/MCP 共享同一份命令定义（一个 args 结构体 + 一个 handler），cp/serve/mcp
  为 CLI 专有命令注册于同一注册表；urfave 依赖已从 go.mod 移除
• 自定义中间件恢复原 CLI 行为：--color 偏好、-j/--json 注入、流式输出跳过框架渲染、
  错误行带 "oss: " 前缀（彩色仅在开启彩色时）
• 根帮助保持自绘 dns 风格双语排版（命令表改为从注册表实时生成，永不漂移）；
  各子命令 -h：xyz 模板 + 双语说明与全部示例（CliHints 的 Description/After 块）
• xyz-go v0.2.4 升级带来的 shell 补全（oss completion bash|zsh|fish）

保持不变（逐项回归验证）

• 六命令的参数名/别名/缩写/默认值全部不变；ls 的 PRE 行/彩色/NDJSON/分页缓存/页脚提示、
  find 的流式命中/导出/NDJSON 汇总、cp 的进度条与原子落盘、serve/mcp——与 v0.1.16 一致

无法完全一致的部分（原因逐项说明）

1. find 多位置参数：oss find a b c 报"位置参数数量不符"退出 2——xyz 的位置参数
   个数固定（不支持变长）。改法：位置参数给第一个，其余用重复 --inputs 或 stdin
   （单输入 + stdin 用法完全不变）
2. 用法错误退出码 1→2：未知 flag、位置参数数量不符等用法类错误按 xyz 语义退出 2
   （运行时错误仍为 1）；Flag 解析错误的提示由 xyz 输出（其中"位置参数数量不符"为库内
   中文文案，未做双语）
3. 帮助版式：各子命令 -h 的 flag 列表由 xyz 渲染（自带 (default …)/别名提示，样式
   与 urfave 不同）；双语示例保留在帮助末尾。-v/--version 变为单行
   "oss version X"（原为两行且带仓库地址；仓库地址在 oss -h 中）
4. 逗号拆分取消：--include a,b 不再拆成两个值（xyz 重复 flag 语义）——多个值用
   重复的 --include a --include b；HTTP/MCP 接口与此前一致
5. HTTP/MCP 入参 wire 名对齐 flag：path_style/page_size/start_after/next_token
   改为 kebab（path-style/page-size/start-after/next-token），与 CLI flag 完全同名；
   HTTP 响应字段保持原 snake_case 不变
6. --json 全局化：stat/cat/presign/cp 现在也接受 --json/-j（xyz 全局 flag），
   但仅 ls/find 会切换 JSON 输出，其余命令输出不变

---

v0.2.0 — CLI migrated to xyz-go: one definition, three interfaces

Changes

• The CLI frontend moved from urfave/cli to xyz-go v0.2.4: ls/stat/cat/presign/find
  now share ONE definition (one args struct + handler) with HTTP/MCP; cp/serve/mcp are
  CLI-only commands in the same registry; the urfave dependency is gone from go.mod
• Custom middleware restores the previous CLI behavior: --color preference, -j/--json
  injection, streaming handlers skipping framework rendering, the "oss: " error prefix
• Root help keeps its dns-style bilingual layout (the command table is now generated
  from the registry, so it can never drift); per-command -h: xyz template plus the
  bilingual prose and full examples (Description / CliHints.After blocks)
• Shell completion from xyz-go v0.2.4 (oss completion bash|zsh|fish)

Unchanged (regression-verified item by item)

• Every flag name/alias/shorthand/default of the six commands; ls PRE rows/colors/NDJSON/
  paging cache/footer hints, find's streaming hits/export/NDJSON summary, cp's progress
  bars and atomic writes, serve/mcp — all identical to v0.1.16

Known deviations (with reasons)

1. find multi-positionals: oss find a b c errors with exit 2 — xyz positionals are
   fixed-count (no variadic). Use the first positional plus repeatable --inputs or stdin
   (single-input and stdin usage are unchanged)
2. Usage errors exit 2 instead of 1: unknown flags / positional-count errors follow
   xyz semantics (2 = usage error; runtime errors still exit 1). Some framework messages
   (e.g. the positional-count error) are library-provided Chinese, not bilingual
3. Help layout: per-command flag lists are rendered by xyz (with (default …)/alias
   hints, differing from urfave's style); bilingual examples live at the end of -h.
   -v/--version prints a single "oss version X" line (the repo URL is in oss -h)
4. No comma splitting: --include a,b is one value now (xyz repeatable-flag
   semantics) — pass multiple values via repeated flags; HTTP/MCP behavior unchanged
5. HTTP/MCP input wire names match flags: path_style/page_size/start_after/next_token
   are now kebab-case to equal the CLI flags exactly; HTTP response fields keep their
   snake_case names
6. --json is global: stat/cat/presign/cp now accept --json/-j (xyz global flag), but
   only ls/find switch to JSON output; the others keep their usual output

v0.1.16

变更

• 依赖升级 xyz-go v0.2.2 → v0.2.4
• MCP 服务器在 initialize 之后向客户端返回 Instructions 帮助说明（双语：
  五个工具用途、目标写法、凭证参数约定、cat 的 text/base64 语义与 16MiB 上限），
  stdio/http/sse 三种传输均生效
• 继承 v0.2.4 的文本渲染修正：tools/call 的 textContent 不再带尾随换行
  （MCP 客户端按字符串读取时更干净）
• README（中/英）补充 Instructions 说明

说明

• v0.2.4 新增的 CLI 自定义帮助块（Config.HelpBefore/HelpAfter、
  CliHints.Before/After）与默认子命令只作用于 xyz 自己的 CLI 前端；
  oss 命令行沿用 urfave 体系，不受影响、无行为变化

---

v0.1.16 — xyz-go v0.2.4: MCP client instructions and text-render fix

Changes

• Dependency xyz-go v0.2.2 → v0.2.4
• The MCP server now returns usage Instructions to clients right after
  initialize (bilingual: the five tools, target syntax, credential argument
  conventions, cat's text/base64 semantics and its 16MiB cap) on all three
  transports (stdio/http/sse)
• Inherits the v0.2.4 render fix: tools/call textContent no longer carries a
  trailing newline (cleaner for clients reading it as a string)
• README (zh/en) documents the Instructions

Notes

• v0.2.4's new CLI help blocks (Config.HelpBefore/HelpAfter, CliHints.Before/After)
  and the default subcommand only affect xyz's own CLI frontend; the oss command
  line stays on the urfave stack with no behavior change

v0.1.15

新增

• HTTP 新增 GET /cat：对象内容以原始字节流输出（非 JSON，二进制安全），
  range 查询参数（0-1023，与 CLI --range 同义）或标准 Range 请求头均可，
  响应透传 Content-Type/Content-Length，范围读取返回 206 + Content-Range
• MCP 新增 cat 工具（工具列表现为 5 个：ls/stat/cat/presign/find）：读取对象内容，
  UTF-8 文本放 text 字段、二进制放 base64 字段（二选一），单次上限 16MiB——
  更大的对象提示改用 CLI oss cat 或 HTTP GET /cat
• 原始 /cat 路由同样支持公共连接参数（query 方式）与 X-Oss-Ak/Sk/Token/Profile 凭证头，
  错误沿用统一 {"error":"..."} + 状态码映射
• README（中/英）与 serve/mcp 帮助同步 cat 的用法说明与示例

内部

• cat 命令抽出 catTarget 核心，CLI 输出、HTTP 原始流、MCP 工具三条路径共用

---

v0.1.15 — cat over HTTP/MCP: raw byte stream with range reads

New

• New HTTP GET /cat: object content as a raw byte stream (not JSON, binary-safe);
  range query param (0-1023, same syntax as CLI --range) or a standard Range
  header, with Content-Type/Content-Length passed through and 206 +
  Content-Range on range reads
• New MCP cat tool (5 tools now: ls/stat/cat/presign/find): reads object content;
  UTF-8 text goes into the text field, binary into base64 (one of the two), capped
  at 16MiB per call — larger objects point to the CLI oss cat or HTTP GET /cat
• The raw /cat route supports the common connection params (query) and the
  X-Oss-Ak/Sk/Token/Profile credential headers, with the standard
  {"error":"..."} body and status-code mapping
• README (zh/en) and the serve/mcp help document the cat usage with examples

Internals

• The cat command now shares a catTarget core across the CLI stream, the HTTP
  raw route and the MCP tool

v0.1.14

新增

• 接入 xyz-go（v0.2.2，一次定义、三个界面）：ls / stat / presign / find 四个查询命令新增 HTTP REST 与 MCP 工具 两种对外调用方式（cat/cp 属原始流式与文件传输，保持仅 CLI）
• 新增 oss serve：一个端口同时提供 REST 路由（GET /ls /stat /presign /find）、/openapi.json、/healthz 与 /mcp（MCP streamable HTTP）；支持 --bearer 鉴权、--cors、--tls-cert/--tls-key、--timeout，SIGINT/SIGTERM 优雅关停，未配置鉴权时启动即告警
• 新增 oss mcp：MCP 工具服务器（stdio/http/sse 三种传输），工具名即命令名，带只读标注与反射生成的 inputSchema
• HTTP 凭据走请求头 X-Oss-Ak/X-Oss-Sk/X-Oss-Token/X-Oss-Profile（不进 URL 日志），未提供时回落服务端环境变量 / ~/.aws
• 统一错误分类：smithy 错误码与传输异常映射为 HTTP 状态码（400/401/403/404/503）与 MCP 错误码
• README（中/英双语）补齐 v0.1.12/0.1.13 find 新行为说明，新增对外服务章节与参数手册

内部改造（CLI 行为不变，全部既有测试通过）

• ls/stat/presign/find 的查询核心从 urfave 处理器中抽离，CLI 与 API 共享同一实现（新增 listWindow 分页窗口与框架无关的 listFlags）

---

v0.1.14 — serve/mcp: REST + OpenAPI + MCP interfaces

New

• Adopted xyz-go (v0.2.2, one definition, three interfaces): ls / stat / presign / find are now also exposed as HTTP REST and MCP tools (cat/cp stream raw bytes or move files and stay CLI-only)
• New oss serve: one port serves the REST routes (GET /ls /stat /presign /find), /openapi.json, /healthz and /mcp (MCP streamable HTTP); --bearer auth, --cors, --tls-cert/--tls-key, --timeout, graceful shutdown, and a loud warning when left unauthenticated
• New oss mcp: MCP tool server over stdio/http/sse; tool names equal command names, with read-only annotations and reflection-generated inputSchema
• HTTP credentials travel via X-Oss-Ak/X-Oss-Sk/X-Oss-Token/X-Oss-Profile headers (never in the URL), falling back to the server environment / ~/.aws
• One error taxonomy maps smithy error codes and transport conditions to HTTP status codes (400/401/403/404/503) and MCP error codes
• README (zh/en) documents the find behavior introduced in v0.1.12/0.1.13, plus the serving section and parameter reference

Internals (no CLI behavior change; the full existing test suite passes)

• The ls/stat/presign/find cores were extracted from the urfave handlers (new listWindow pager and framework-free listFlags), so the CLI and the API share one implementation

v0.1.13

v0.1.13 — find 支持 AK/SK/STS 凭证探测，可验证非匿名桶

新增 / 变更

• find 支持凭证探测：配置了凭证（--ak/--sk，STS 加 --token；或 OSS_*/AWS_* 环境变量、--profile，与 ls/cp 相同）时，自动从匿名探测切换为 SigV4 签名探测，可验证非匿名桶；--anonymous 强制匿名
• 防误报：凭证本身被拒（InvalidAccessKeyId、SignatureDoesNotMatch 等）判为「无法判断」；只有明确目标的探测（--provider 指定或完整桶 URL）才把普通 403 判为「存在·拒绝访问」
• --provider 可把裸桶名的扇出收窄到指定厂商（对 minio/r2/b2 等无探针厂商会明确报错）
• JSON 汇总行新增 "auth": "anonymous|signed"；输出文案随模式区分（如「可列目录（凭证）」）

用法示例

oss find mybucket --provider aliyun --ak LTAI... --sk ...

---

v0.1.13 — find supports credentialed (AK/SK/STS) probing for non-anonymous buckets

• find switches from anonymous to SigV4-signed probes when credentials are configured (--ak/--sk, --token for STS, OSS_*/AWS_* env vars or --profile — same as ls/cp), so non-anonymous buckets can be verified; --anonymous forces anonymous probing
• No false positives: credential rejections (InvalidAccessKeyId, SignatureDoesNotMatch, ...) stay inconclusive; a plain 403 counts as "exists but denied" only for targeted probes (--provider or a full bucket URL)
• --provider now also narrows the bare-name fan-out to that provider (providers without probes, e.g. minio/r2/b2, produce a clear error)
• JSON summary gains "auth": "anonymous|signed"; wording adapts to the mode

Full Changelog: v0.1.12...v0.1.13