From 8cec41db34acd9cd912d2481857949b022237596 Mon Sep 17 00:00:00 2001 From: Ismael Martinez Ramos Date: Mon, 14 Sep 2026 13:56:01 +0100 Subject: [PATCH] docs(go): ask clients to reuse one session ID across all endpoints Requirement 3 did not say the same ID must be reused on every request and sent on every endpoint, which is how a client can set it in one SDK's middleware and miss the others. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_019u64ksoe2v3xjdRe4uBMhX --- packages/web/src/content/docs/ar/go.mdx | 3 +++ packages/web/src/content/docs/bs/go.mdx | 3 +++ packages/web/src/content/docs/da/go.mdx | 3 +++ packages/web/src/content/docs/de/go.mdx | 4 ++++ packages/web/src/content/docs/es/go.mdx | 3 +++ packages/web/src/content/docs/fr/go.mdx | 4 ++++ packages/web/src/content/docs/go.mdx | 3 +++ packages/web/src/content/docs/it/go.mdx | 4 ++++ packages/web/src/content/docs/ja/go.mdx | 3 +++ packages/web/src/content/docs/ko/go.mdx | 3 +++ packages/web/src/content/docs/nb/go.mdx | 3 +++ packages/web/src/content/docs/pl/go.mdx | 4 ++++ packages/web/src/content/docs/pt-br/go.mdx | 4 ++++ packages/web/src/content/docs/ru/go.mdx | 4 ++++ packages/web/src/content/docs/th/go.mdx | 3 +++ packages/web/src/content/docs/tr/go.mdx | 3 +++ packages/web/src/content/docs/zh-cn/go.mdx | 2 ++ packages/web/src/content/docs/zh-tw/go.mdx | 2 ++ 18 files changed, 58 insertions(+) diff --git a/packages/web/src/content/docs/ar/go.mdx b/packages/web/src/content/docs/ar/go.mdx index 60a130ee9bc3..949cc920e55e 100644 --- a/packages/web/src/content/docs/ar/go.mdx +++ b/packages/web/src/content/docs/ar/go.mdx @@ -94,6 +94,9 @@ OpenCode Go هو اشتراك منخفض التكلفة بقيمة **$10/شهر من اسم عام لحزمة SDK أو مكتبة HTTP. 3. يرسل معرّف جلسة ثابتًا في `x-opencode-session` لكل محادثة حتى نتمكن من تحسين التوجيه والتخزين المؤقت للمطالبات. + ويعيد استخدام المعرّف نفسه في كل طلبات المحادثة، بما فيها الطلبات المساعدة، بدلًا من إنشاء معرّف لكل طلب أو لكل + عملية، ويرسله على كل نقاط النهاية التي يستخدمها العميل (`/responses` و`/chat/completions` و`/messages`)؛ + فالترويسة المضافة في وسيط SDK واحد فقط لا تصل إلى البقية. ### العملاء الذين تم التحقق منهم diff --git a/packages/web/src/content/docs/bs/go.mdx b/packages/web/src/content/docs/bs/go.mdx index 95c902a6fac4..7846d716a044 100644 --- a/packages/web/src/content/docs/bs/go.mdx +++ b/packages/web/src/content/docs/bs/go.mdx @@ -104,6 +104,9 @@ Vaš klijent treba: generičkim nazivom SDK-a ili HTTP biblioteke. 3. Slati stabilan ID sesije u zaglavlju `x-opencode-session` za svaki razgovor kako bismo mogli optimizovati usmjeravanje i keširanje promptova. + Koristiti isti ID za sve zahtjeve u razgovoru, uključujući pomoćne pozive, umjesto kreiranja novog po zahtjevu + ili po procesu, i slati ga na sve endpointe koje klijent koristi (`/responses`, `/chat/completions` i + `/messages`); zaglavlje dodano samo u middleware jednog SDK-a ne stiže do ostalih. ### Provjereni klijenti diff --git a/packages/web/src/content/docs/da/go.mdx b/packages/web/src/content/docs/da/go.mdx index 076f76bcf1a9..a53d55e929e4 100644 --- a/packages/web/src/content/docs/da/go.mdx +++ b/packages/web/src/content/docs/da/go.mdx @@ -104,6 +104,9 @@ Din klient skal: for et generisk navn på et SDK eller HTTP-bibliotek. 3. Sende et stabilt sessions-id i `x-opencode-session` for hver samtale, så vi kan optimere routing og prompt-caching. + Genbruge det samme id til alle forespørgsler i en samtale, også hjælpekald, i stedet for at oprette et nyt pr. + forespørgsel eller pr. proces, og sende det på alle de endpoints, klienten bruger (`/responses`, + `/chat/completions` og `/messages`); en header, der kun tilføjes i ét SDK's middleware, når ikke de andre. ### Validerede klienter diff --git a/packages/web/src/content/docs/de/go.mdx b/packages/web/src/content/docs/de/go.mdx index 18354b41ee57..d42964b35ba8 100644 --- a/packages/web/src/content/docs/de/go.mdx +++ b/packages/web/src/content/docs/de/go.mdx @@ -96,6 +96,10 @@ Dein Client sollte: nicht mit dem allgemeinen Namen eines SDKs oder einer HTTP-Bibliothek. 3. für jede Unterhaltung eine stabile Sitzungs-ID in `x-opencode-session` senden, damit wir das Routing und Prompt-Caching optimieren können. + Dieselbe ID für alle Anfragen einer Unterhaltung wiederverwenden, Hilfsaufrufe eingeschlossen, statt pro Anfrage + oder pro Prozess eine neue zu erzeugen, und sie an allen vom Client genutzten Endpunkten senden (`/responses`, + `/chat/completions` und `/messages`); ein Header, der nur in der Middleware eines einzigen SDK gesetzt wird, + erreicht die anderen nicht. ### Validierte Clients diff --git a/packages/web/src/content/docs/es/go.mdx b/packages/web/src/content/docs/es/go.mdx index c10bb6f0d53b..701e4b5a60d3 100644 --- a/packages/web/src/content/docs/es/go.mdx +++ b/packages/web/src/content/docs/es/go.mdx @@ -104,6 +104,9 @@ Tu cliente debe: del nombre genérico de un SDK o una biblioteca HTTP. 3. Enviar un ID de sesión estable en `x-opencode-session` para cada conversación, de modo que podamos optimizar el enrutamiento y el almacenamiento en caché de prompts. + Reutilizar el mismo ID en todas las peticiones de una conversación, incluidas las llamadas auxiliares, en lugar + de generar uno por petición o por proceso, y enviarlo en todos los endpoints que use el cliente (`/responses`, + `/chat/completions` y `/messages`); una cabecera añadida solo en el middleware de un SDK no llega a los demás. ### Clientes validados diff --git a/packages/web/src/content/docs/fr/go.mdx b/packages/web/src/content/docs/fr/go.mdx index 0dc8ea985821..05895b67ba70 100644 --- a/packages/web/src/content/docs/fr/go.mdx +++ b/packages/web/src/content/docs/fr/go.mdx @@ -94,6 +94,10 @@ Votre client doit : qu'avec le nom générique d'un SDK ou d'une bibliothèque HTTP. 3. Envoyer un ID de session stable dans `x-opencode-session` pour chaque conversation afin que nous puissions optimiser le routage et la mise en cache des prompts. + Réutiliser le même ID pour toutes les requêtes d'une conversation, appels auxiliaires compris, plutôt que d'en + générer un par requête ou par processus, et l'envoyer sur tous les endpoints utilisés par le client + (`/responses`, `/chat/completions` et `/messages`) ; un en-tête ajouté uniquement dans le middleware d'un seul + SDK n'atteint pas les autres. ### Clients validés diff --git a/packages/web/src/content/docs/go.mdx b/packages/web/src/content/docs/go.mdx index f8d36bb7a4e5..f46040fd1cef 100644 --- a/packages/web/src/content/docs/go.mdx +++ b/packages/web/src/content/docs/go.mdx @@ -104,6 +104,9 @@ Your client should: than a generic SDK or HTTP-library name. 3. Send a stable session ID in `x-opencode-session` for each conversation so we can optimize routing and prompt caching. + Reuse the same ID for every request in a conversation, auxiliary calls included, rather than minting one per + request or per process, and send it on whichever endpoints your client uses (`/responses`, `/chat/completions` + and `/messages`); a header added in only one SDK's middleware misses the others. ### Validated Clients diff --git a/packages/web/src/content/docs/it/go.mdx b/packages/web/src/content/docs/it/go.mdx index 9e40b40bf0ab..103470440bb8 100644 --- a/packages/web/src/content/docs/it/go.mdx +++ b/packages/web/src/content/docs/it/go.mdx @@ -102,6 +102,10 @@ Il tuo client deve: con il nome generico di un SDK o di una libreria HTTP. 3. Inviare un ID di sessione stabile in `x-opencode-session` per ogni conversazione, in modo da consentirci di ottimizzare il routing e il caching dei prompt. + Riutilizzare lo stesso ID per tutte le richieste di una conversazione, chiamate ausiliarie comprese, invece di + generarne uno per richiesta o per processo, e inviarlo su tutti gli endpoint usati dal client (`/responses`, + `/chat/completions` e `/messages`); un header aggiunto solo nel middleware di un singolo SDK non raggiunge gli + altri. ### Client convalidati diff --git a/packages/web/src/content/docs/ja/go.mdx b/packages/web/src/content/docs/ja/go.mdx index 3c2889d7d5a8..50410df8ea95 100644 --- a/packages/web/src/content/docs/ja/go.mdx +++ b/packages/web/src/content/docs/ja/go.mdx @@ -91,6 +91,9 @@ OpenCode Goは、[OpenCode](https://opencode.ai)および同様の種類のリ 1. 一般的なコーディングエージェントのトラフィックを送信する。 2. 汎用的なSDK名やHTTPライブラリ名ではなく、`my-coding-agent/1.0`のような独自のユーザーエージェントで自身を識別する。 3. ルーティングとプロンプトキャッシュを最適化できるよう、会話ごとに安定したセッションIDを`x-opencode-session`で送信する。 + 会話内のすべてのリクエスト（補助的な呼び出しを含む）で同じIDを再利用し、リクエストごとやプロセスごとに新しいIDを生成しない。 + また、クライアントが使用するすべてのエンドポイント（`/responses`、`/chat/completions`、`/messages`）で送信する。 + 1つのSDKのミドルウェアだけでヘッダーを付与すると、他のエンドポイントには届かない。 ### 動作確認済みのクライアント diff --git a/packages/web/src/content/docs/ko/go.mdx b/packages/web/src/content/docs/ko/go.mdx index 3578c6b7afa8..c3bbe5d336f8 100644 --- a/packages/web/src/content/docs/ko/go.mdx +++ b/packages/web/src/content/docs/ko/go.mdx @@ -91,6 +91,9 @@ OpenCode Go는 [OpenCode](https://opencode.ai) 및 유사한 유형의 요청을 1. 일반적인 코딩 에이전트 트래픽을 전송합니다. 2. 일반적인 SDK 또는 HTTP 라이브러리 이름이 아닌 `my-coding-agent/1.0`과 같은 자체 user agent로 식별합니다. 3. 라우팅과 프롬프트 캐싱을 최적화할 수 있도록 각 대화에서 안정적인 세션 ID를 `x-opencode-session`으로 전송합니다. + 요청마다 또는 프로세스마다 새 ID를 만들지 말고, 보조 호출을 포함한 대화의 모든 요청에서 같은 ID를 재사용하며, + 클라이언트가 사용하는 모든 엔드포인트(`/responses`, `/chat/completions`, `/messages`)에 전송합니다. + 하나의 SDK 미들웨어에서만 추가한 헤더는 다른 엔드포인트에는 전달되지 않습니다. ### 검증된 클라이언트 diff --git a/packages/web/src/content/docs/nb/go.mdx b/packages/web/src/content/docs/nb/go.mdx index 3837446ed2c5..b25b1a3c1e9c 100644 --- a/packages/web/src/content/docs/nb/go.mdx +++ b/packages/web/src/content/docs/nb/go.mdx @@ -104,6 +104,9 @@ Klienten din skal: for et generisk navn på et SDK eller HTTP-bibliotek. 3. Sende en stabil sesjons-ID i `x-opencode-session` for hver samtale, slik at vi kan optimalisere ruting og promptbufring. + Gjenbruke samme ID for alle forespørsler i en samtale, hjelpekall inkludert, i stedet for å lage en ny per + forespørsel eller per prosess, og sende den på alle endepunktene klienten bruker (`/responses`, + `/chat/completions` og `/messages`); en header som bare legges til i ett SDKs mellomvare, når ikke de andre. ### Validerte klienter diff --git a/packages/web/src/content/docs/pl/go.mdx b/packages/web/src/content/docs/pl/go.mdx index 18d99e5fb0ad..b2af02c923e2 100644 --- a/packages/web/src/content/docs/pl/go.mdx +++ b/packages/web/src/content/docs/pl/go.mdx @@ -98,6 +98,10 @@ Twój klient powinien: ogólnej nazwy SDK lub biblioteki HTTP. 3. Wysyłać stabilny identyfikator sesji w nagłówku `x-opencode-session` dla każdej rozmowy, aby umożliwić optymalizację routingu i buforowania promptów. + Używać tego samego identyfikatora dla wszystkich żądań w rozmowie, łącznie z wywołaniami pomocniczymi, zamiast + tworzyć nowy dla każdego żądania lub procesu, i wysyłać go na wszystkich endpointach używanych przez klienta + (`/responses`, `/chat/completions` i `/messages`); nagłówek dodany tylko w middleware jednego SDK nie trafia do + pozostałych. ### Zweryfikowane klienty diff --git a/packages/web/src/content/docs/pt-br/go.mdx b/packages/web/src/content/docs/pt-br/go.mdx index b62cae09a66a..b9777fe81b5a 100644 --- a/packages/web/src/content/docs/pt-br/go.mdx +++ b/packages/web/src/content/docs/pt-br/go.mdx @@ -104,6 +104,10 @@ Seu cliente deve: do nome genérico de um SDK ou de uma biblioteca HTTP. 3. Enviar um ID de sessão estável em `x-opencode-session` para cada conversa, para que possamos otimizar o roteamento e o cache de prompts. + Reutilizar o mesmo ID em todas as requisições de uma conversa, incluindo chamadas auxiliares, em vez de gerar um + por requisição ou por processo, e enviá-lo em todos os endpoints que o cliente usa (`/responses`, + `/chat/completions` e `/messages`); um cabeçalho adicionado apenas no middleware de um único SDK não chega aos + demais. ### Clientes validados diff --git a/packages/web/src/content/docs/ru/go.mdx b/packages/web/src/content/docs/ru/go.mdx index eaa63ba96f92..28eccc29ed76 100644 --- a/packages/web/src/content/docs/ru/go.mdx +++ b/packages/web/src/content/docs/ru/go.mdx @@ -104,6 +104,10 @@ OpenCode Go предназначен для [OpenCode](https://opencode.ai) и универсального названия SDK или HTTP-библиотеки. 3. Отправлять стабильный идентификатор сессии в заголовке `x-opencode-session` для каждого диалога, чтобы мы могли оптимизировать маршрутизацию и кеширование промптов. + Использовать один и тот же идентификатор для всех запросов в рамках диалога, включая вспомогательные вызовы, а не + создавать новый на каждый запрос или процесс, и отправлять его на все эндпоинты, которые использует клиент + (`/responses`, `/chat/completions` и `/messages`); заголовок, добавленный только в middleware одного SDK, до + остальных не доходит. ### Проверенные клиенты diff --git a/packages/web/src/content/docs/th/go.mdx b/packages/web/src/content/docs/th/go.mdx index 85898df258b9..ad7147ccc0ad 100644 --- a/packages/web/src/content/docs/th/go.mdx +++ b/packages/web/src/content/docs/th/go.mdx @@ -91,6 +91,9 @@ OpenCode Go ออกแบบมาสำหรับ [OpenCode](https://openco 1. ส่งทราฟฟิกตามปกติของ coding agent 2. ระบุตัวตนด้วย user agent ของตนเอง เช่น `my-coding-agent/1.0` แทนชื่อ SDK หรือไลบรารี HTTP แบบทั่วไป 3. ส่ง session ID ที่คงที่ใน `x-opencode-session` สำหรับแต่ละบทสนทนา เพื่อให้เราปรับ routing และ prompt caching ให้เหมาะสมได้ + ใช้ ID เดิมซ้ำสำหรับทุกคำขอในบทสนทนา รวมถึงการเรียกเสริมด้วย แทนที่จะสร้างใหม่ต่อคำขอหรือต่อโปรเซส และส่งไปยังทุก endpoint + ที่ไคลเอนต์ใช้ (`/responses`, `/chat/completions` และ `/messages`) เพราะ header ที่เพิ่มไว้ใน middleware ของ SDK + เพียงตัวเดียวจะไม่ถูกส่งไปยัง endpoint อื่น ### ไคลเอนต์ที่ผ่านการตรวจสอบแล้ว diff --git a/packages/web/src/content/docs/tr/go.mdx b/packages/web/src/content/docs/tr/go.mdx index 66fa9299f3c6..d48daa321d5d 100644 --- a/packages/web/src/content/docs/tr/go.mdx +++ b/packages/web/src/content/docs/tr/go.mdx @@ -91,6 +91,9 @@ Trafik, diğer kullanıcıların deneyimini olumsuz etkileyen kötüye kullanım 1. Tipik kodlama aracısı trafiği göndermelidir. 2. Genel bir SDK veya HTTP kitaplığı adı yerine `my-coding-agent/1.0` gibi kendine ait bir user agent ile kendini tanıtmalıdır. 3. Yönlendirmeyi ve istem önbelleğe almayı optimize edebilmemiz için her konuşmada `x-opencode-session` içinde değişmeyen bir oturum kimliği göndermelidir. + Aynı kimlik, yardımcı çağrılar dahil bir konuşmadaki tüm isteklerde yeniden kullanılmalı, istek veya süreç başına + yeni bir kimlik üretilmemeli ve istemcinin kullandığı tüm uç noktalara (`/responses`, `/chat/completions` ve + `/messages`) gönderilmelidir; yalnızca tek bir SDK'nın ara katmanına eklenen bir başlık diğerlerine ulaşmaz. ### Doğrulanmış İstemciler diff --git a/packages/web/src/content/docs/zh-cn/go.mdx b/packages/web/src/content/docs/zh-cn/go.mdx index 7123ffcf8a0d..f2c685e88869 100644 --- a/packages/web/src/content/docs/zh-cn/go.mdx +++ b/packages/web/src/content/docs/zh-cn/go.mdx @@ -92,6 +92,8 @@ OpenCode Go 适用于 [OpenCode](https://opencode.ai) 以及其他会产生类 1. 发送典型的编程 Agent 流量。 2. 使用自身专属的 user agent 标识（例如 `my-coding-agent/1.0`），而不是通用的 SDK 或 HTTP 库名称。 3. 为每段对话在 `x-opencode-session` 请求头中发送稳定的会话 ID，以便我们优化路由和提示词缓存。 + 在同一段对话的所有请求（包括辅助调用）中复用同一个 ID，而不是每个请求或每个进程各生成一个，并在客户端使用的所有端点 + （`/responses`、`/chat/completions` 和 `/messages`）上发送；只在某一个 SDK 的中间件里添加请求头，其他端点就收不到。 ### 已验证的客户端 diff --git a/packages/web/src/content/docs/zh-tw/go.mdx b/packages/web/src/content/docs/zh-tw/go.mdx index 16c2b4b20aa9..151f51bb5bec 100644 --- a/packages/web/src/content/docs/zh-tw/go.mdx +++ b/packages/web/src/content/docs/zh-tw/go.mdx @@ -92,6 +92,8 @@ OpenCode Go 適用於 [OpenCode](https://opencode.ai) 以及其他會產生類 1. 傳送典型的程式設計 Agent 流量。 2. 使用自身專屬的 user agent 識別資訊（例如 `my-coding-agent/1.0`），而非通用的 SDK 或 HTTP 函式庫名稱。 3. 為每段對話在 `x-opencode-session` 請求標頭中傳送穩定的工作階段 ID，以便我們最佳化路由和提示詞快取。 + 在同一段對話的所有請求（包括輔助呼叫）中重複使用同一個 ID，而不是每個請求或每個處理程序各產生一個，並在用戶端使用的所有端點 + （`/responses`、`/chat/completions` 和 `/messages`）上傳送；只在某一個 SDK 的中介軟體裡加入請求標頭，其他端點就收不到。 ### 已驗證的用戶端