Merge pull request #761 from Wibias/fix/alias-versioned-tilde-encoding

fix(claude): version slash/tilde aliases under claude-ocx2-

Author: Wibias

docs-site/src/content/docs/guides/claude-code.md

@@ -175,7 +175,7 @@ with `claude` or `anthropic`, opencodex exposes routed models as stable, reversi
 
 | Surface | Format | Example |
 | --- | --- | --- |
-| Claude Code CLI | `claude-ocx-<provider>--<model>` | `claude-ocx-native--gpt-5.6-sol` |
+| Claude Code CLI | `claude-ocx-<provider>--<model>` (plain) or `claude-ocx2-…` (escaped) | `claude-ocx-native--gpt-5.6-sol` |
 | Claude Desktop 3P | `claude-opus-4-8-<code>` (3-char base36 hash) | `claude-opus-4-8-ncb` |
 
 The proxy picks the family per request: `?ids=cli` or `?ids=desktop` wins; otherwise the
@@ -200,11 +200,13 @@ slots via
 `ANTHROPIC_MODEL` or type any routed id with `/model` (Claude Code passes strings through).
 
 **Alias grammar rules:** provider must not contain `/` or `--` or equal `native`.
-Model ids may contain `/` — encoded as `~s` in the alias (e.g. `openrouter/anthropic/claude-opus-4-8`
-→ `claude-ocx-openrouter--anthropic~sclaude-opus-4-8`). Literal `~` in a model id is encoded as `~t`.
-Bare `~` not followed by `s`/`t` is treated as a literal tilde so older persisted aliases keep resolving.
-Routes the readable form cannot express fall back to the hashed alias. Model ids MAY contain `--`
-(resolution splits on the first `--` only); native slugs containing `--` fall back to the hashed form.
+Plain model ids (no `/` or `~`) keep the v1 prefix `claude-ocx-…`. Model ids that contain `/` or
+`~` mint the v2 prefix `claude-ocx2-…` with escapes (`/` → `~s`, `~` → `~t`), e.g.
+`openrouter/anthropic/claude-opus-4-8` → `claude-ocx2-openrouter--anthropic~sclaude-opus-4-8`.
+v1 aliases decode literally (so a historical model id that contained the two-char sequences
+`~s` / `~t` is preserved); v2 aliases expand the escapes. Routes that the readable form cannot
+express fall back to the hashed alias. Model ids MAY contain `--` (resolution splits on the first
+`--` only); native slugs containing `--` fall back to the hashed form.
 
 **Model resolution order:** `[1m]` marker stripped → readable alias decoded → Desktop hashed
 alias decoded → `modelMap` exact match → date-stripped match (`-20250514` removed) → passthrough.

docs-site/src/content/docs/ja/guides/claude-code.md

@@ -68,8 +68,8 @@ Claude Code 2.1.129 以降は `GET /v1/models?limit=1000` でゲートウェイ
 受け付けるため、opencodex はルーティングモデルを安定で元に戻せるエイリアスとして公開します。
 
 | 画面 | 形式 | 例 |
- --- | --- | --- |
-| Claude Code CLI | `claude-ocx-<provider>--<model>` | `claude-ocx-native--gpt-5.6-sol` |
+| --- | --- | --- |
+| Claude Code CLI | `claude-ocx-<provider>--<model>` (plain) または `claude-ocx2-…` (escaped) | `claude-ocx-native--gpt-5.6-sol` |
 | Claude Desktop 3P | `claude-opus-4-8-<code>` (3 桁の base36 ハッシュ) | `claude-opus-4-8-ncb` |
 
 プロキシはリクエストごとに系列を選びます。`?ids=cli` または `?ids=desktop` が優先し、指定しないと
@@ -82,12 +82,13 @@ Claude Desktop のフッターピッカーで実行中の 3P 会話のモデル
 含まれるモデル ID をルーティングします。結果は **Logs → requestedModel** で確認できます。
 
 **エイリアス構文ルール:** provider には `/` や `--` を含められず `native` と同じでもいけません。
-model ID には `/` を含められ、エイリアス内では `~s` として符号化します(例: `openrouter/anthropic/claude-opus-4-8` →
-`claude-ocx-openrouter--anthropic~sclaude-opus-4-8`)。model ID のリテラル `~` は `~t` として符号化します。
-`s`/`t` が続かない裸の `~` はリテラルのチルダとして扱い、古い永続化エイリアスも解決し続けます。
-読みやすい形式で表現できないルートはハッシュエイリアスに置き換えます。モデル
-ID には `--` を含め**られます**(解析時は最初の `--` だけを基準に分割します)。`--` を含む
-ネイティブスラッグはハッシュ形式に置き換えます。
+`/` も `~` も含まない plain な model ID は v1 接頭辞 `claude-ocx-…` のままです。`/` または `~` を含む
+model ID は v2 接頭辞 `claude-ocx2-…` で発行し、エスケープします(`/` → `~s`、`~` → `~t`)。例:
+`openrouter/anthropic/claude-opus-4-8` → `claude-ocx2-openrouter--anthropic~sclaude-opus-4-8`。
+v1 エイリアスはリテラルにデコードします(歴史的に model ID に含まれていた 2 文字列 `~s` / `~t` も保持)。
+v2 エイリアスはエスケープを展開します。読みやすい形式で表現できないルートはハッシュエイリアスに
+置き換えます。モデル ID には `--` を含め**られます**(解析時は最初の `--` だけを基準に分割します)。
+`--` を含むネイティブスラッグはハッシュ形式に置き換えます。
 
 **モデル解決順序:** `[1m]` 標識の削除 → 読みやすいエイリアスのデコード → Desktop ハッシュエイリアスのデコード →
 `modelMap` の完全一致 → 日付を削除した値との一致(`-20250514` 削除) → パススルー順です。

docs-site/src/content/docs/ko/guides/claude-code.md

@@ -104,7 +104,7 @@ Claude Code 2.1.129 이상은 `GET /v1/models?limit=1000`에서 게이트웨이
 
 | 화면 | 형식 | 예시 |
 | --- | --- | --- |
-| Claude Code CLI | `claude-ocx-<provider>--<model>` | `claude-ocx-native--gpt-5.6-sol` |
+| Claude Code CLI | `claude-ocx-<provider>--<model>` (plain) 또는 `claude-ocx2-…` (escaped) | `claude-ocx-native--gpt-5.6-sol` |
 | Claude Desktop 3P | `claude-opus-4-8-<code>` (3자리 base36 해시) | `claude-opus-4-8-ncb` |
 
 프록시는 요청마다 계열을 골라요. `?ids=cli` 또는 `?ids=desktop`이 우선하고, 지정하지 않으면
@@ -116,13 +116,14 @@ Claude Desktop의 하단 선택기로 이미 실행 중인 3P 대화의 모델
 `/model <id>`를 사용하세요. OpenCodex는 선택기 상태를 따로 볼 수 없고 각 요청에 실린 모델 ID를
 라우팅해요. 적용 결과는 **Logs → requestedModel**에서 확인할 수 있어요.
 
-**별칭 문법 규칙:** provider에는 `/`나 `--`를 넣을 수 없고 `native`와 같아도 안 돼요. model ID에
-`/`가 있으면 별칭에서 `~s`로 인코딩해요(예: `openrouter/anthropic/claude-opus-4-8` →
-`claude-ocx-openrouter--anthropic~sclaude-opus-4-8`). model ID의 리터럴 `~`는 `~t`로 인코딩해요.
-`s`/`t`가 따르지 않는 단독 `~`는 예전 설정과의 호환을 위해 리터럴 `~`로 해석해요. 읽기 쉬운
-형식으로 표현할 수 없는 라우트는 해시 별칭으로 대체해요. 모델 ID에는 `--`를 넣을 **수 있어요**
-(해석할 때 첫 번째 `--`만 기준으로 나눠요). `--`가 포함된 네이티브 슬러그는 해시 형식으로
-대체해요.
+**별칭 문법 규칙:** provider에는 `/`나 `--`를 넣을 수 없고 `native`와 같아도 안 돼요. `/`와 `~`가
+없는 plain model ID는 v1 접두사 `claude-ocx-…`를 유지해요. `/` 또는 `~`가 있는 model ID는 v2
+접두사 `claude-ocx2-…`로 만들고 이스케이프해요(`/` → `~s`, `~` → `~t`). 예:
+`openrouter/anthropic/claude-opus-4-8` → `claude-ocx2-openrouter--anthropic~sclaude-opus-4-8`.
+v1 별칭은 리터럴로 디코딩해요(예전 model ID에 들어 있던 두 글자 시퀀스 `~s` / `~t`도 그대로 보존).
+v2 별칭은 이스케이프를 펼쳐요. 읽기 쉬운 형식으로 표현할 수 없는 라우트는 해시 별칭으로 대체해요.
+모델 ID에는 `--`를 넣을 **수 있어요**(해석할 때 첫 번째 `--`만 기준으로 나눠요). `--`가 포함된
+네이티브 슬러그는 해시 형식으로 대체해요.
 
 **모델 해석 순서:** `[1m]` 표식 제거 → 읽기 쉬운 별칭 디코딩 → Desktop 해시 별칭 디코딩 →
 `modelMap` 정확히 일치 → 날짜를 제거한 값과 일치(`-20250514` 제거) → 패스스루 순서예요.

docs-site/src/content/docs/ru/guides/claude-code.md

@@ -74,7 +74,7 @@ Claude Code 2.1.129+ обнаруживает модели шлюза через
 
 | Интерфейс | Формат | Пример |
 | --- | --- | --- |
-| Claude Code CLI | `claude-ocx-<provider>--<model>` | `claude-ocx-native--gpt-5.6-sol` |
+| Claude Code CLI | `claude-ocx-<provider>--<model>` (plain) или `claude-ocx2-…` (escaped) | `claude-ocx-native--gpt-5.6-sol` |
 | Claude Desktop 3P | `claude-opus-4-8-<code>` (3-символьный base36-хеш) | `claude-opus-4-8-ncb` |
 
 Прокси выбирает семейство для каждого запроса: приоритет у `?ids=cli` или `?ids=desktop`; иначе
@@ -87,13 +87,14 @@ user-agent `claude-code/*` получает читаемую CLI-форму, а
 маршрутизирует id модели из каждого запроса. Результат можно проверить в **Logs → requestedModel**.
 
 **Правила грамматики алиасов:** provider не может содержать `/` или `--` и не может быть равен
-`native`. Id моделей могут содержать `/` — в алиасе это кодируется как `~s` (например,
-`openrouter/anthropic/claude-opus-4-8` → `claude-ocx-openrouter--anthropic~sclaude-opus-4-8`).
-Литеральный `~` в id модели кодируется как `~t`. Голый `~` без следующего `s`/`t`
-считается литеральной тильдой, чтобы старые сохранённые алиасы продолжали разрешаться.
-Маршруты, которые невозможно выразить читаемой формой,
-откатываются на хешированный алиас. Id моделей МОГУТ содержать `--` (при разрешении разбиение
-выполняется только по первому `--`); нативные слаги с `--` откатываются на хешированную форму.
+`native`. Обычные id моделей (без `/` и `~`) остаются с префиксом v1 `claude-ocx-…`. Id с `/`
+или `~` выпускаются с префиксом v2 `claude-ocx2-…` и экранированием (`/` → `~s`, `~` → `~t`),
+например `openrouter/anthropic/claude-opus-4-8` →
+`claude-ocx2-openrouter--anthropic~sclaude-opus-4-8`. Алиасы v1 декодируются литерально (исторические
+двухсимвольные последовательности `~s` / `~t` в id модели сохраняются); алиасы v2 раскрывают
+экранирование. Маршруты, которые невозможно выразить читаемой формой, откатываются на
+хешированный алиас. Id моделей МОГУТ содержать `--` (при разрешении разбиение выполняется только
+по первому `--`); нативные слаги с `--` откатываются на хешированную форму.
 
 **Порядок разрешения модели:** удаление маркера `[1m]` → декодирование читаемого алиаса →
 декодирование Desktop-хеша → точное совпадение в `modelMap` → совпадение без даты (удаляется

docs-site/src/content/docs/zh-cn/guides/claude-code.md

@@ -77,7 +77,7 @@ opencodex 会将已路由模型公开为稳定且可逆的别名：
 
 | 界面 | 格式 | 示例 |
 | --- | --- | --- |
-| Claude Code CLI | `claude-ocx-<provider>--<model>` | `claude-ocx-native--gpt-5.6-sol` |
+| Claude Code CLI | `claude-ocx-<provider>--<model>`（plain）或 `claude-ocx2-…`（escaped） | `claude-ocx-native--gpt-5.6-sol` |
 | Claude Desktop 3P | `claude-opus-4-8-<code>`（3 字符 base36 哈希） | `claude-opus-4-8-ncb` |
 
 代理会按请求选择别名族：`?ids=cli` 或 `?ids=desktop` 优先；否则，`claude-code/*`
@@ -89,11 +89,12 @@ user-agent 会获得易读的 CLI 形式，其他客户端会获得 Desktop 哈
 **Logs → requestedModel** 中确认结果。
 
 **别名语法规则：**provider 不得包含 `/` 或 `--`，也不得等于 `native`。
-model ID 可以包含 `/` — 在别名中编码为 `~s`（例如 `openrouter/anthropic/claude-opus-4-8`
-→ `claude-ocx-openrouter--anthropic~sclaude-opus-4-8`）。model ID 中的字面 `~` 编码为 `~t`。
-后面不是 `s`/`t` 的裸 `~` 视为字面波浪号，以便旧版已持久化的别名继续解析。
-易读形式无法表达的路由会回退到哈希别名。模型 ID **可以**包含 `--`（解析时只按第一个
-`--` 分割）；含 `--` 的原生 slug 会回退到哈希形式。
+不含 `/` 或 `~` 的普通 model ID 继续使用 v1 前缀 `claude-ocx-…`。包含 `/` 或 `~` 的 model ID
+会使用 v2 前缀 `claude-ocx2-…` 并转义（`/` → `~s`，`~` → `~t`），例如
+`openrouter/anthropic/claude-opus-4-8` → `claude-ocx2-openrouter--anthropic~sclaude-opus-4-8`。
+v1 别名按字面解码（历史上 model ID 中包含的两字符序列 `~s` / `~t` 会被保留）；v2 别名会展开转义。
+易读形式无法表达的路由会回退到哈希别名。模型 ID **可以**包含 `--`（解析时只按第一个 `--` 分割）；
+含 `--` 的原生 slug 会回退到哈希形式。
 
 **模型解析顺序：**移除 `[1m]` 标记 → 解码易读别名 → 解码 Desktop 哈希别名 →
 `modelMap` 精确匹配 → 移除日期后的匹配（移除 `-20250514`）→ 透传。