From 2e6cc60da6ff15aada31241ac58dbf87a7f18ba3 Mon Sep 17 00:00:00 2001
From: root <root@minecraft-server>
Date: Tue, 6 Oct 2026 08:05:37 +0800
Subject: [PATCH] =?UTF-8?q?docs(discovery):=20=E7=94=A8=E5=AE=9E=E6=B5=8B?=
 =?UTF-8?q?=E6=95=B0=E6=8D=AE=E6=9B=BF=E6=8D=A2=E6=B3=A8=E9=87=8A=E9=87=8C?=
 =?UTF-8?q?=E7=9A=84=E7=8C=9C=E6=B5=8B?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

composeImageEndpoint 原注释写着「两种形式都 404，无法区分」，那是我写代码时
的推测，不是观测。后来真实打了一次上游就分清了：

  /v1/images/generations    → 200（图像生成本身要几分钟，是上游耗时）
  /v1/v1/images/generations → 404
  /images/generations      → 404

注释里的假话比没有注释更糟——下一个人会拿它当「已知的模糊地带」而不敢
收紧判据。
---
 internal/gateway/discover.go | 22 +++++++++++++---------
 1 file changed, 13 insertions(+), 9 deletions(-)

diff --git a/internal/gateway/discover.go b/internal/gateway/discover.go
index 279d576..ea0c277 100644
--- a/internal/gateway/discover.go
+++ b/internal/gateway/discover.go
@@ -285,18 +285,22 @@ func composeEndpoint(modelsPath, persistedBase, typedBase string) string {
 //
 //	base "https://h"     + "/v1/images/generations"  → correct
 //	base "https://h/v1"  + "/v1/images/generations"  → "/v1/v1/…" 404
+//	base "https://h/v1"  + "/images/generations"     → "/v1/images/generations"  correct
 //
-// Emitting "" when the base already ends in a version is wrong for a different
-// reason: the vendor's catalog path is not proof that its image path carries
-// the same prefix. Some gateways serve the catalog at "/v1/models" but the
-// image endpoint at "/images/generations" (observed: 404 on both forms, but a
-// 404 from the doubled form is indistinguishable from a 404 from the wrong
-// host). Rather than guess, the value written here is derived from the base so
-// it composes, and the caller can still override image_endpoint by hand.
+// The second row is not a theoretical guess. Measured against the real
+// amr-link endpoint with base_url "https://amr-link.open-design.ai/v1":
+//
+//	…/v1/images/generations   → 200 (the image is then generated; that call
+//	                              takes minutes, which is the upstream's own
+//	                              latency and not a routing problem)
+//	…/v1/v1/images/generations → 404
+//	…/images/generations      → 404
+//
+// Leaving the default in place when the base already ends in a version is
+// therefore always wrong for such an upstream, and the version-relative form
+// is the one that composes.
 func composeImageEndpoint(persistedBase string) string {
 	if b := trimVersionSuffix(persistedBase); b != persistedBase {
-		// The base ends in a version segment, so the default absolute path
-		// would double it. Use the version-relative form instead.
 		return "/images/generations"
 	}
 	return ""