dsh-coding-subscription-oauth 0.7.0 → 0.8.0

package/README.ko.md

@@ -1,304 +1,310 @@
-
-<!-- banner -->
-<div align="center">
-
-# 🔐 dsh-coding-subscription-oauth
-
-**v0.7.0 · 이전 이름 `dsh-grok-build`
-
-**[DeepSeek Harness](https://github.com/deepseek-ai/dsh)용 코딩 구독 OAuth 플러그인.** 이미 결제한 구독으로 한 번에 로그인하고, dsh 설정 페이지나 CLI에서 그 모델을 사용하세요. **채팅에 토큰을 붙여넣을 필요가 없습니다.**
-
-[![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)
-[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
-
-*[English](README.md) · [中文版](README.zh-CN.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Português (BR)](README.pt-BR.md) · [Español](README.es.md) · [Français](README.fr.md) · [Deutsch](README.de.md) · [Русский](README.ru.md)*
-
-</div>
-
----
-
-> **업그레이드:** [`INSTALL.md`](INSTALL.md)의 버전별 단계를 따르세요. `0.7.0`는 공유 dispatcher 런타임을 `dsh-coding-oauth-core@0.1.2`과 `undici@7.29.0`으로 유지하고, Gateway 키 reveal/rotate를 loopback 접근으로 제한합니다. 설정·자격 증명·데이터·라우트 마이그레이션은 필요 없습니다. Grok Imagine은 명시적으로 고정된 dispatcher를 유지합니다. `0.6.2` 이후 릴리스에는 엄격한 Cordis 주입 시작 수정과 DSH `0.1.1-rc.2` 지원이 포함됩니다. profile/설정/자격 증명 파일은 유지하고, 업데이트 후 기존 DSH Web 프로세스를 한 번만 재시작하세요. Hub와 Subscription을 함께 사용할 때 `dsh-coding-oauth-core@0.1.2`과 `undici@7.29.0`은 공유 런타임 핀이며 별도의 DSH 플러그인이 아닙니다.
-
----
-
-## 이름 변경
-
-처음에는 Grok Build 전용 **`dsh-grok-build`** 였습니다. 지금은 SuperGrok / Codex / Kimi / Claude / Antigravity 코딩 구독 OAuth입니다.
-| | 이것을 쓰세요 | 계속 동작 |
-|---|---|---|
-| GitHub / `dsh plugin add` | [`dsh-coding-subscription-oauth`](https://github.com/lninghaha/dsh-coding-subscription-oauth) | `github:lninghaha/dsh-grok-build`（같은 `main`） |
-| npm | `dsh-coding-subscription-oauth@0.7.0`（현재 릴리스） | 레거시 npm 패키지는 게시된 적 없음 |
-| CLI | `dsh-coding-oauth` | `dsh-grok-build` |
-| Cordis 플러그인 id | `llm-grok-build-oauth` | 그대로 |
-| 설정 페이지 HTTP API | `/plugins/dsh-grok-build/*` | 그대로 |
-| 자격 증명 파일 | `$DSH_HOME/.grok-build-auth.json` 및 기타 `*-oauth-auth.json` | 그대로 |
-
-## ✨ 기능
-
-- 🧾 **내 구독 그대로 사용** — 별도 API key 없이 이미 결제한 코딩 플랜을 사용합니다.
-- 🔑 **로컬 OAuth, 키 붙여넣기 불필요** — 설정 페이지나 CLI에서 인증하며, 토큰이 채팅에 들어가지 않습니다.
-- 🧩 **하나의 플러그인, 다섯 프로바이더** — Grok Build, Codex, Kimi, Claude, Google Antigravity.
-- 🛡️ **안전한 설계** — 인증 파일은 소유자 전용 `0600`, 원자적 쓰기, 크로스 프로세스 파일 잠금.
-- ⚙️ **동적 카탈로그** — 선택기에는 인증을 완료한 라우트만 `(OAuth)` 라벨과 함께 표시되며, grok-4.6의 `xhigh`도 포함됩니다.
-- 🌐 **프록시 인지형** — 검증된 신뢰 가능한 구독 도메인만 프록시합니다.
-- 📥 **수동 CLI Pull** — 설정 페이지가 허용 목록에 있는 공식 Grok/Codex/Kimi/Claude CLI OAuth 파일을 읽기 전용으로 검색합니다. 미리보기와 덮어쓰기 확인 후 단방향 복사본을 가져옵니다.
-- 🗂️ **탭으로 나뉜 설정** — Accounts, Gateway, Capabilities, About. 원격 호스트에서는 device code를 우선하고 CLI missing 소음을 줄이며, 로그인된 카드는 펼칠 때까지 접혀 있습니다.
-- 🎛️ **선택적 기능 (기본 꺼짐)** — Codex 검색, 사용량/쿼터, 이미지 생성/편집, Fast, Grok Imagine은 스위치를 켜면 즉시 적용됩니다. 추가 기본 꺼짐 스위치로 비 Codex 모델 라우트가 Codex 이미지 도구를 호출할 수 있지만 Codex 로그인, 세션, 첨부 파일 소유권 검사는 그대로 유지됩니다.
-- 🔌 **옵트인 로컬 API 게이트웨이** — 기본 꺼짐의 루프백 OpenAI/Anthropic 호환 서버. 내 도구 전용이며 공개 릴레이가 아닙니다.
-
-## 이 플러그인이 푸는 연동 문제
-
-코딩 구독을 DSH에 붙일 때 아래 검색어·오류로 이 저장소에 오는 경우가 많습니다.
-
-| 검색 / 화면 | 실제 원인 | 이 플러그인 |
-|---|---|---|
-| SuperGrok / X Premium를 DSH에, Grok Build vs `api.x.ai` | 내장 `xai`는 종량 API. 구독 추론은 `cli-chat-proxy.grok.com` | `grok-build` + CLI 지문 헤더(`X-XAI-Token-Auth` 등), 조용한 403 방지 |
-| `API key is invalid` / `AUTH` | GUI는 모든 AUTH를 그 문구로 표시. 흔히 짧은 OAuth access token 만료 | 만료 **5분 전** refresh. 401이면 저장 토큰을 무효화하고 step 재시도 |
-| Codex/Kimi 두 번째 턴 `INVALID_REPLAY_STATE` | replay가 pi-ai 네이티브 provider id를 유지 | Harness route id를 유지하고 오염된 replay를 복구 |
-| grok-4.6에 **xhigh**가 없음 | `/v1/models-v2`의 `reasoning_efforts`를 버리고 4.5 템플릿을 복제 | live efforts를 `thinkingLevelMap`에 반영. 4.6은 xhigh, 4.5는 low/medium/high |
-| Kimi Code가 Anthropic `x-api-key`로 나감 | OAuth token을 Anthropic 키로 전송 | `Authorization: Bearer`만 사용 |
-| 로그인하지 않은 모델이 선택기에 남음 | 등록된 모든 라우트를 나열 | 미인증은 빈 목록. 인증됨은 `(OAuth)` |
-| 원격/헤드리스에서 PKCE 불가 | localhost로 돌아올 수 없음 | Grok/Codex/Kimi는 디바이스 코드. Claude는 redirect URL 붙여넣기 |
-| 프록시로 Grok은 되고 중국 Kimi는 죽음 | 전역 `HTTPS_PROXY` | 허용 도메인만. Kimi는 기본 직결(`proxyKimi: true`일 때만 프록시) |
-
-## 지원 프로바이더
-
-| 프로바이더 | 라우트 | 인증 | 기존 API-key 라우트와 공존 |
-|---|---|---|---|
-| **xAI Grok Build** | `grok-build` | SuperGrok / X Premium OAuth | `xai` |
-| **OpenAI Codex** | `codex-oauth` | ChatGPT Plus/Pro OAuth | `openai` |
-| **Kimi Code** | `kimi-code-oauth` | Kimi Code OAuth | `kimi-coding` |
-| **Claude Code** | `claude-code-oauth` | Claude Pro/Max OAuth | — |
-| **Google Antigravity** | `agy` | `dsh-agy` Google OAuth | — |
-
-> Grok Build의 디바이스 로그인, 동적 `/v1/models-v2` 카탈로그, Responses 스트리밍 추론은 실제 배포에서 검증되었습니다. Codex/Kimi/Claude는 `@earendil-works/pi-ai`의 네이티브 OAuth/리프레시를 재사용하며 벤더 플로우를 재구현하지 않습니다.
-
-## 🚀 빠른 시작
-
-```bash
-# 1. web 프로필에 플러그인 설치 (현재 npm 릴리스)
-dsh plugin --profile web add dsh-coding-subscription-oauth@0.7.0
-
-# 2. 선택 사항 — Google Antigravity (검증된 고정 버전)
-dsh plugin --profile web add dsh-agy@0.1.2
-
-# 3. 실제로 구성한 프로세스 관리자로 기존 DSH Web 프로세스 재시작
-# `dsh web`은 공식 CLI 별칭이지 서비스 이름이 아닙니다.
-```
-
-그런 다음 **Settings → Coding OAuth**를 열고 원하는 프로바이더에 로그인하세요. 완료입니다 — 선택기에서 인증된 모델을 선택하면 됩니다.
-
-## 📚 목차
-
-- [이름 변경](#이름-변경)
-- [기능](#-기능)
-- [이 플러그인이 푸는 연동 문제](#이-플러그인이-푸는-연동-문제)
-- [지원 프로바이더](#지원-프로바이더)
-- [빠른 시작](#-빠른-시작)
-- [설치](#설치)
-- [설정 페이지](#설정-페이지)
-- [선택적 기능](#선택적-기능)
-- [로컬 API 게이트웨이](#로컬-api-게이트웨이)
-- [CLI](#cli)
-- [중국에서의 Kimi](#중국에서의-kimi)
-- [네트워크 프록시](#네트워크-프록시)
-- [복원력](#복원력)
-- [자격 증명](#자격-증명)
-- [아키텍처](#아키텍처)
-- [기술 메모](#기술-메모)
-- [준수](#준수)
-- [문서](#문서)
-- [관련 프로젝트](#관련-프로젝트)
-- [기여](#기여)
-- [라이선스](#라이선스)
-
-## 설치
-
-DeepSeek Harness `0.1.1-rc.2` 및 Node.js 22.19+가 필요합니다. 자세한 내용은 [설치 노트](INSTALL.md)를 참조하세요.
-
-```bash
-# 현재 npm 릴리스 (권장)
-dsh plugin --profile web add dsh-coding-subscription-oauth@0.7.0
-
-# 개발/대안: GitHub에서
-dsh plugin --profile web add github:lninghaha/dsh-coding-subscription-oauth
-
-# 개발/대안: 로컬 개발 디렉터리에서
-dsh plugin --profile web add ./dsh-coding-subscription-oauth
-```
-
-설치 후 기존 DSH Web 프로세스를 재시작합니다. 실제 배포 검증:
-
-```bash
-pnpm run verify:deployed            # 실제 /api/llm.models + OAuth 상태 확인
-DSH_EXPECT_AGY_AUTH=signed-in pnpm run verify:deployed   # Google에 로그인된 경우
-
-DSH_RESTORE_PROVIDER=openai \
-DSH_RESTORE_MODEL=gpt-5.6-sol \
-DSH_RESTORE_REASONING=max \
-pnpm run smoke:deployed             # 실제 Codex/Kimi 도구 호출 + 두 번째 사용자 turn 재생
-```
-
-> `smoke:deployed`는 임시 세션을 만들고 Codex와 Kimi 도구 호출 및 두 번째 사용자 turn(`INVALID_REPLAY_STATE` 회귀)을 검증한 뒤 선언된 기본 모델을 복원하고 세션을 아카이브합니다.
-
-## 설정 페이지
-
-**Settings → Coding OAuth**를 열어 주세요:
-
-
-
-<table>
-  <tr>
-    <td align="center" valign="top" width="33%">
-      <a href="media/en/settings_accounts.png"><img src="media/en/settings_accounts.png" alt="Coding OAuth Accounts tab" width="280" /></a><br />
-      <sub>Accounts</sub>
-    </td>
-    <td align="center" valign="top" width="33%">
-      <a href="media/en/settings_gateway.png"><img src="media/en/settings_gateway.png" alt="Coding OAuth Gateway tab" width="280" /></a><br />
-      <sub>Gateway</sub>
-    </td>
-    <td align="center" valign="top" width="33%">
-      <a href="media/en/settings_capabilities.png"><img src="media/en/settings_capabilities.png" alt="Coding OAuth Capabilities tab" width="280" /></a><br />
-      <sub>Capabilities</sub>
-    </td>
-  </tr>
-</table>
-
-| 프로바이더 | 방식 |
-|---|---|
-| Grok | 인증 코드 · 디바이스 코드 · Grok CLI import · 모델 선택 |
-| Codex | 디바이스 코드(원격 DSH 권장) · 브라우저 PKCE |
-| Kimi | 디바이스 코드 |
-| Claude | 브라우저 PKCE(원격 브라우저는 전체 localhost redirect URL을 붙여넣기 가능) |
-| Antigravity | `dsh-agy` 설치 상태 + profile-local CLI 명령 |
-
-설정 페이지는 **Accounts**, **Gateway**, **Capabilities**, **About** 네 개의 상위 탭으로 나뉩니다. 로그인된 프로바이더 카드는 간결한 요약으로 접히고 모델 편집 시 펼쳐집니다. CLI pull 미리보기는 전체 너비로 표시되고, Imagine 상태는 Capabilities 탭에서 확인할 수 있습니다.
-
-선택기는 인증을 완료한 라우트만 나열하며, 인증되지 않은 프로바이더는 빈 목록을 반환합니다. 프로바이더 이름에는 `(OAuth)`가 붙고, 로그인/아웃 후 `llm/adapters-updated`를 통해 카탈로그가 갱신됩니다.
-
-## 선택적 기능
-
-8개 스위치 `codexSearch`, `codexImages`, `codexImageEdits`, `codexImagesAnyModel`, `codexUsage`, `codexFast`, `grokImagineImage`, `grokImagineVideo`는 모두 기본적으로 꺼져 있으며 재시작 없이 즉시 적용됩니다. `codexImagesAnyModel`은 호출 모델 라우트 게이트만 완화합니다. 여전히 Codex 로그인, `codexImages`(편집 시 edits 플래그), 세션 첨부 소유권 및 편집 인가가 필요합니다. 숫자 설정은 `searchResults`(1–20, 기본 5), `imageCount`(1–4, 기본 1), `videoArtifactTtlMs`(1시간–7일, 기본 7일, UI에서는 1–168시간)입니다. 보존 시간을 낮추면 기존 아티팩트도 즉시 단축·정리되며, 높인 값은 이후 생성된 아티팩트에만 적용됩니다.
-
-## 로컬 API 게이트웨이
-
-기본값은 **꺼짐**입니다. 활성화하면 DSH 웹 포트와 분리된 독립 `node:http` 서버가 `127.0.0.1:18080`에서 시작되어 같은 로그인 OAuth 세션을 재사용합니다:
-
-```yaml
-gateway:
-  enabled: false
-  bind: 127.0.0.1
-  port: 18080
-```
-
-엔드포인트: `GET /healthz`, `GET /v1/models`, `POST /v1/chat/completions`, `POST /v1/responses`, `POST /v1/messages`. Bearer 키는 `$DSH_HOME/.coding-oauth-gateway.json`(`0600`)에 저장됩니다. 설정에서 OpenAI 베이스 URL(베이스 + `/v1`), Anthropic 베이스 URL, 현재 Bearer 키를 로테이션 없이 복사할 수 있습니다. 키 표시는 루프백에서만 가능하며 브라우저 스토리지에 저장되지 않습니다. 로테이션은 확인이 필요한 파괴적 작업입니다. 리슨 포트는 직접 편집해 Apply로 저장하거나 Random(18100–18999)으로 채울 수 있습니다. 선택한 포트는 소유자 전용 게이트웨이 문서에 저장되고 실행 중인 리스너가 다시 바인딩됩니다. bind는 YAML에서만 변경할 수 있으며, 루프백이 아닌 bind에는 키가 필요합니다. 원격 릴레이가 아닙니다.
-
-## CLI
-
-```bash
-# `dsh-grok-build` 는 같은 CLI 별칭
-dsh-coding-oauth login [--pkce] | import | status | logout
-
-# 최신 프로바이더
-dsh-coding-oauth login codex --device-auth | codex --browser | kimi | claude
-dsh-coding-oauth status all
-dsh-coding-oauth logout codex
-
-# Antigravity (먼저 web 프로필에 설치)
-dsh plugin --profile web exec dsh-agy login --headless
-```
-
-> `dsh-agy` CLI는 DSH 프로세스 밖에서 계정 풀을 수정하므로 프로세스 내 카탈로그 이벤트를 내보낼 수 없습니다 — 로그인/아웃 후 모델 선택기를 닫았다 다시 여세요.
-
-## 중국에서의 Kimi
-
-Kimi Code 구독 OAuth는 `https://auth.kimi.com`, 추론은 `https://api.kimi.com/coding`을 사용합니다. `https://api.moonshot.cn/v1`은 종량제 **Moonshot Open Platform** API-key 채널이며, 전환 가능한 "중국 OAuth 엔드포인트"는 없습니다. 이 플러그인은 별도 `kimi-code-oauth` 라우트를 사용하며 기존 `kimi-coding` API-key 설정에 영향을 주지 않습니다.
-
-## 네트워크 프록시
-
-우선순위: `config.proxy` → `CODING_OAUTH_PROXY` → `GROK_BUILD_PROXY` → `HTTPS_PROXY`/`HTTP_PROXY`.
-
-```yaml
-- id: llm-grok-build-oauth
-  config:
-    proxy: http://127.0.0.1:7890
-    proxyKimi: false
-```
-
-검증된 구독 도메인만 프록시됩니다(xAI/Grok, OpenAI Codex, Claude/Anthropic, Google Antigravity). 나머지 DSH 트래픽은 원래 디스패처를 유지합니다. Kimi는 기본적으로 직결이며 `proxyKimi: true`일 때만 프록시를 사용합니다.
-
-## 복원력
-
-OAuth 액세스 토큰은 저장된 만료 시각 **5분 전**에 선제적으로 갱신됩니다(pi-ai 0.84+). 업스트림이 로컬에서는 아직 유효한 토큰을 401/403으로 거절하면, 플러그인이 저장된 `expires`를 과거로 되돌리고 재시도 단계에서 먼저 갱신한 뒤 다시 요청합니다.
-
-요청 재시도는 harness retry 정책을 따릅니다. 일시 오류(`RATE_LIMIT`/`SERVER`/`TIMEOUT`/`TRANSPORT`/`EMPTY_RESPONSE`)와 **`AUTH`**는 지수 백오프로 재시도합니다(기본 5회, 5 s → 10 s → 20 s → 40 s → 80 s (~155 s 누적), 10% jitter). 쿼터 소진과 죽은 refresh token은 재시도하지 않습니다. 배포별 재정의:
-
-```yaml
-- id: llm-grok-build-oauth
-  config:
-    retryPolicy:
-      mode: normal
-      maxRetries: 5
-      retryableCodes: [EMPTY_RESPONSE, RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT, AUTH]
-      backoff: { initialDelayMs: 5000, maxDelayMs: 80000, jitterRatio: 0.1 }
-```
-
-## 자격 증명
-
-소유자 전용 `0600`, 원자적 쓰기, 크로스 프로세스 파일 잠금:
-
-- `$DSH_HOME/.grok-build-auth.json`
-- `$DSH_HOME/.codex-oauth-auth.json`
-- `$DSH_HOME/.kimi-code-oauth-auth.json`
-- `$DSH_HOME/.claude-code-oauth-auth.json`
-
-선택 캐시는 해당 `*-models.json` 파일에 저장됩니다. **HTTP 상태, 로그, UI가 토큰을 반환해서는 안 됩니다.**
-
-## 아키텍처
-
-```mermaid
-flowchart LR
-    subgraph DSH["DSH Harness"]
-        UI[설정 / Web · Coding OAuth] --> LLM[llm route]
-        LLM --> ALIA[라우트 별칭 어댑터]
-    end
-    ALIA --> PI[pi-ai 네이티브 프로바이더<br/>OAuth · 리프레시 · 스트림]
-    PI --> GROK[Grok Build]
-    PI --> COD[Codex]
-    PI --> KIMI[Kimi]
-    PI --> CLAU[Claude]
-    AGY[dsh-agy 플러그인] --> GAL[Google Antigravity]
-```
-
-## 기술 메모
-
-- **Grok Build**: `cli-chat-proxy.grok.com/v1`의 커스텀 Responses 프로바이더, CLI 핑거프린트 헤더, 동적 모델 카탈로그.
-- **Codex/Kimi/Claude**: pi-ai 네이티브 프로바이더가 OAuth와 리프레시를 처리합니다. 라우트 별칭 어댑터가 이를 네이티브 id에 매핑하되 모델 내부 아이덴티티는 변하지 않습니다.
-- Kimi access token은 명시적으로 `Authorization: Bearer`로 변환됩니다 — Anthropic `x-api-key`로 잘못 보내지는 일이 없습니다.
-- Google Antigravity는 여기서 리버스 엔지니어링**하지 않습니다**. 버전 고정형 전용 DSH 플러그인을 사용합니다.
-
-## 준수
-
-제3자 harness를 통한 코딩 구독 사용은 각 벤더 이용약관의 회색 지대에 놓일 수 있으며 할당량, 지역 또는 계정 리스크 관리가 트리거될 수 있습니다. **본인 계정만 사용하세요.** 이 프로젝트는 대량 계정, 할당량 재판매, 원격 릴레이, 페이월 우회, 클라이언트 사칭을 지원하지 않습니다. 상업용으로는 벤더 공식 API-key 채널을 권장합니다.
-
-## 문서
-
-| 문서 | 용도 |
-|---|---|
-| [`INSTALL.md`](INSTALL.md) | 설치·사용 상세 |
-| [`CHANGELOG.md`](CHANGELOG.md) | 릴리스 이력 |
-| [`docs/00-project-rules.md`](docs/00-project-rules.md) | 버전 관리, 릴리스 루프, 공개/로컬 분리 |
-| [`docs/02-architecture.md`](docs/02-architecture.md) | 내부 아키텍처 (라우트 · 데이터 흐름 · 모듈 · API) · [中文](docs/02-architecture.zh-CN.md) |
-| [`CONTRIBUTING.md`](CONTRIBUTING.md) | 기여 가이드 |
-
-## 관련 프로젝트
-
-- [`dsh-agy`](https://www.npmjs.com/package/dsh-agy) — Google Antigravity용 독립 고정 버전 플러그인.
-
-## 기여
-
-기능, 문서, 번역, 버그 보고 등 모든 기여를 환영합니다. 프로세스, 커밋 규칙 및 릴리스 루프는 **[CONTRIBUTING](CONTRIBUTING.md)**을 참조하세요. 목록에 없는 언어라면 README 번역을 PR로 보내 주세요. 위 언어 테이블에 추가하겠습니다.
-
-## 라이선스
-
-[Apache-2.0](LICENSE) · [NOTICE](NOTICE) 참조. 일부는 [dsh-xai](https://github.com/MirDie/dsh-xai) 프로젝트(Apache-2.0)에서 파생되었습니다.
+
+<!-- banner -->
+<div align="center">
+
+# 🔐 dsh-coding-subscription-oauth
+
+**v0.8.0 · 이전 이름 `dsh-grok-build`
+
+**[DeepSeek Harness](https://github.com/deepseek-ai/dsh)용 코딩 구독 OAuth 플러그인.** 이미 결제한 구독으로 한 번에 로그인하고, dsh 설정 페이지나 CLI에서 그 모델을 사용하세요. **채팅에 토큰을 붙여넣을 필요가 없습니다.**
+
+[![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
+
+*[English](README.md) · [中文版](README.zh-CN.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Português (BR)](README.pt-BR.md) · [Español](README.es.md) · [Français](README.fr.md) · [Deutsch](README.de.md) · [Русский](README.ru.md)*
+
+</div>
+
+---
+
+> **업그레이드:** [`INSTALL.md`](INSTALL.md)의 버전별 단계를 따르세요. `0.7.0`는 공유 dispatcher 런타임을 `dsh-coding-oauth-core@0.1.2`과 `undici@7.29.0`으로 유지하고, Gateway 키 reveal/rotate를 loopback 접근으로 제한합니다. 설정·자격 증명·데이터·라우트 마이그레이션은 필요 없습니다. Grok Imagine은 명시적으로 고정된 dispatcher를 유지합니다. `0.6.2` 이후 릴리스에는 엄격한 Cordis 주입 시작 수정과 DSH `0.1.1-rc.2` 지원이 포함됩니다. profile/설정/자격 증명 파일은 유지하고, 업데이트 후 기존 DSH Web 프로세스를 한 번만 재시작하세요. Hub와 Subscription을 함께 사용할 때 `dsh-coding-oauth-core@0.1.2`과 `undici@7.29.0`은 공유 런타임 핀이며 별도의 DSH 플러그인이 아닙니다.
+
+---
+
+## 이름 변경
+
+처음에는 Grok Build 전용 **`dsh-grok-build`** 였습니다. 지금은 SuperGrok / Codex / Kimi / Claude / Antigravity 코딩 구독 OAuth입니다.
+| | 이것을 쓰세요 | 계속 동작 |
+|---|---|---|
+| GitHub / `dsh plugin add` | [`dsh-coding-subscription-oauth`](https://github.com/lninghaha/dsh-coding-subscription-oauth) | `github:lninghaha/dsh-grok-build`（같은 `main`） |
+| npm | `dsh-coding-subscription-oauth@0.8.0`（현재 릴리스） | 레거시 npm 패키지는 게시된 적 없음 |
+| CLI | `dsh-coding-oauth` | `dsh-grok-build` |
+| Cordis 플러그인 id | `llm-grok-build-oauth` | 그대로 |
+| 설정 페이지 HTTP API | `/plugins/dsh-grok-build/*` | 그대로 |
+| 자격 증명 파일 | `$DSH_HOME/.grok-build-auth.json` 및 기타 `*-oauth-auth.json` | 그대로 |
+
+## ✨ 기능
+
+- 🧾 **내 구독 그대로 사용** — 별도 API key 없이 이미 결제한 코딩 플랜을 사용합니다.
+- 🔑 **로컬 OAuth, 키 붙여넣기 불필요** — 설정 페이지나 CLI에서 인증하며, 토큰이 채팅에 들어가지 않습니다.
+- 🧩 **하나의 플러그인, 다섯 프로바이더** — Grok Build, Codex, Kimi, Claude, Google Antigravity.
+- 🛡️ **안전한 설계** — 인증 파일은 소유자 전용 `0600`, 원자적 쓰기, 크로스 프로세스 파일 잠금.
+- ⚙️ **동적 카탈로그** — 선택기에는 인증을 완료한 라우트만 `(OAuth)` 라벨과 함께 표시되며, grok-4.6의 `xhigh`도 포함됩니다.
+- 🌐 **프록시 인지형** — 검증된 신뢰 가능한 구독 도메인만 프록시합니다.
+- 📥 **수동 CLI Pull** — 설정 페이지가 허용 목록에 있는 공식 Grok/Codex/Kimi/Claude CLI OAuth 파일을 읽기 전용으로 검색합니다. 미리보기와 덮어쓰기 확인 후 단방향 복사본을 가져옵니다.
+- 🗂️ **탭으로 나뉜 설정** — Accounts, Gateway, Capabilities, About. 원격 호스트에서는 device code를 우선하고 CLI missing 소음을 줄이며, 로그인된 카드는 펼칠 때까지 접혀 있습니다.
+- 🎛️ **선택적 기능 (기본 꺼짐)** — Codex 검색, 사용량/쿼터, 이미지 생성/편집, Fast, Grok Imagine은 스위치를 켜면 즉시 적용됩니다. 추가 기본 꺼짐 스위치로 비 Codex 모델 라우트가 Codex 이미지 도구를 호출할 수 있지만 Codex 로그인, 세션, 첨부 파일 소유권 검사는 그대로 유지됩니다.
+- 🔌 **옵트인 로컬 API 게이트웨이** — 기본 꺼짐의 루프백 OpenAI/Anthropic 호환 서버. 내 도구 전용이며 공개 릴레이가 아닙니다.
+- 🤝 **옵트인 OpenCode Go 호환** — 게이트웨이가 OpenCode Go로 채팅을 프록시하고 sticky `x-opencode-session`을 주입(`MissingSessionID` 방지); 기본 off.
+
+## 이 플러그인이 푸는 연동 문제
+
+코딩 구독을 DSH에 붙일 때 아래 검색어·오류로 이 저장소에 오는 경우가 많습니다.
+
+| 검색 / 화면 | 실제 원인 | 이 플러그인 |
+|---|---|---|
+| SuperGrok / X Premium를 DSH에, Grok Build vs `api.x.ai` | 내장 `xai`는 종량 API. 구독 추론은 `cli-chat-proxy.grok.com` | `grok-build` + CLI 지문 헤더(`X-XAI-Token-Auth` 등), 조용한 403 방지 |
+| `API key is invalid` / `AUTH` | GUI는 모든 AUTH를 그 문구로 표시. 흔히 짧은 OAuth access token 만료 | 만료 **5분 전** refresh. 401이면 저장 토큰을 무효화하고 step 재시도 |
+| Codex/Kimi 두 번째 턴 `INVALID_REPLAY_STATE` | replay가 pi-ai 네이티브 provider id를 유지 | Harness route id를 유지하고 오염된 replay를 복구 |
+| grok-4.6에 **xhigh**가 없음 | `/v1/models-v2`의 `reasoning_efforts`를 버리고 4.5 템플릿을 복제 | live efforts를 `thinkingLevelMap`에 반영. 4.6은 xhigh, 4.5는 low/medium/high |
+| Kimi Code가 Anthropic `x-api-key`로 나감 | OAuth token을 Anthropic 키로 전송 | `Authorization: Bearer`만 사용 |
+| 로그인하지 않은 모델이 선택기에 남음 | 등록된 모든 라우트를 나열 | 미인증은 빈 목록. 인증됨은 `(OAuth)` |
+| 원격/헤드리스에서 PKCE 불가 | localhost로 돌아올 수 없음 | Grok/Codex/Kimi는 디바이스 코드. Claude는 redirect URL 붙여넣기 |
+| 프록시로 Grok은 되고 중국 Kimi는 죽음 | 전역 `HTTPS_PROXY` | 허용 도메인만. Kimi는 기본 직결(`proxyKimi: true`일 때만 프록시) |
+| OpenCode Go 채팅이 `MissingSessionID` / `x-opencode-session` 누락으로 실패 | 클라이언트가 sticky 세션 헤더를 보내지 않음 | 옵트인 게이트웨이 OpenCode Go 프록시가 sticky `x-opencode-session` 주입 |
+
+## 지원 프로바이더
+
+| 프로바이더 | 라우트 | 인증 | 기존 API-key 라우트와 공존 |
+|---|---|---|---|
+| **xAI Grok Build** | `grok-build` | SuperGrok / X Premium OAuth | `xai` |
+| **OpenAI Codex** | `codex-oauth` | ChatGPT Plus/Pro OAuth | `openai` |
+| **Kimi Code** | `kimi-code-oauth` | Kimi Code OAuth | `kimi-coding` |
+| **Claude Code** | `claude-code-oauth` | Claude Pro/Max OAuth | — |
+| **Google Antigravity** | `agy` | `dsh-agy` Google OAuth | — |
+
+> Grok Build의 디바이스 로그인, 동적 `/v1/models-v2` 카탈로그, Responses 스트리밍 추론은 실제 배포에서 검증되었습니다. Codex/Kimi/Claude는 `@earendil-works/pi-ai`의 네이티브 OAuth/리프레시를 재사용하며 벤더 플로우를 재구현하지 않습니다.
+
+## 🚀 빠른 시작
+
+```bash
+# 1. web 프로필에 플러그인 설치 (현재 npm 릴리스)
+dsh plugin --profile web add dsh-coding-subscription-oauth@0.8.0
+
+# 2. 선택 사항 — Google Antigravity (검증된 고정 버전)
+dsh plugin --profile web add dsh-agy@0.1.2
+
+# 3. 실제로 구성한 프로세스 관리자로 기존 DSH Web 프로세스 재시작
+# `dsh web`은 공식 CLI 별칭이지 서비스 이름이 아닙니다.
+```
+
+그런 다음 **Settings → Coding OAuth**를 열고 원하는 프로바이더에 로그인하세요. 완료입니다 — 선택기에서 인증된 모델을 선택하면 됩니다.
+
+## 📚 목차
+
+- [이름 변경](#이름-변경)
+- [기능](#-기능)
+- [이 플러그인이 푸는 연동 문제](#이-플러그인이-푸는-연동-문제)
+- [지원 프로바이더](#지원-프로바이더)
+- [빠른 시작](#-빠른-시작)
+- [설치](#설치)
+- [설정 페이지](#설정-페이지)
+- [선택적 기능](#선택적-기능)
+- [로컬 API 게이트웨이](#로컬-api-게이트웨이)
+- [CLI](#cli)
+- [중국에서의 Kimi](#중국에서의-kimi)
+- [네트워크 프록시](#네트워크-프록시)
+- [복원력](#복원력)
+- [자격 증명](#자격-증명)
+- [아키텍처](#아키텍처)
+- [기술 메모](#기술-메모)
+- [준수](#준수)
+- [문서](#문서)
+- [관련 프로젝트](#관련-프로젝트)
+- [기여](#기여)
+- [라이선스](#라이선스)
+
+## 설치
+
+DeepSeek Harness `0.1.1-rc.2` 및 Node.js 22.19+가 필요합니다. 자세한 내용은 [설치 노트](INSTALL.md)를 참조하세요.
+
+```bash
+# 현재 npm 릴리스 (권장)
+dsh plugin --profile web add dsh-coding-subscription-oauth@0.8.0
+
+# 개발/대안: GitHub에서
+dsh plugin --profile web add github:lninghaha/dsh-coding-subscription-oauth
+
+# 개발/대안: 로컬 개발 디렉터리에서
+dsh plugin --profile web add ./dsh-coding-subscription-oauth
+```
+
+설치 후 기존 DSH Web 프로세스를 재시작합니다. 실제 배포 검증:
+
+```bash
+pnpm run verify:deployed            # 실제 /api/llm.models + OAuth 상태 확인
+DSH_EXPECT_AGY_AUTH=signed-in pnpm run verify:deployed   # Google에 로그인된 경우
+
+DSH_RESTORE_PROVIDER=openai \
+DSH_RESTORE_MODEL=gpt-5.6-sol \
+DSH_RESTORE_REASONING=max \
+pnpm run smoke:deployed             # 실제 Codex/Kimi 도구 호출 + 두 번째 사용자 turn 재생
+```
+
+> `smoke:deployed`는 임시 세션을 만들고 Codex와 Kimi 도구 호출 및 두 번째 사용자 turn(`INVALID_REPLAY_STATE` 회귀)을 검증한 뒤 선언된 기본 모델을 복원하고 세션을 아카이브합니다.
+
+## 설정 페이지
+
+**Settings → Coding OAuth**를 열어 주세요:
+
+
+
+<table>
+  <tr>
+    <td align="center" valign="top" width="33%">
+      <a href="media/en/settings_accounts.png"><img src="media/en/settings_accounts.png" alt="Coding OAuth Accounts tab" width="280" /></a><br />
+      <sub>Accounts</sub>
+    </td>
+    <td align="center" valign="top" width="33%">
+      <a href="media/en/settings_gateway.png"><img src="media/en/settings_gateway.png" alt="Coding OAuth Gateway tab" width="280" /></a><br />
+      <sub>Gateway</sub>
+    </td>
+    <td align="center" valign="top" width="33%">
+      <a href="media/en/settings_capabilities.png"><img src="media/en/settings_capabilities.png" alt="Coding OAuth Capabilities tab" width="280" /></a><br />
+      <sub>Capabilities</sub>
+    </td>
+  </tr>
+</table>
+
+| 프로바이더 | 방식 |
+|---|---|
+| Grok | 인증 코드 · 디바이스 코드 · Grok CLI import · 모델 선택 |
+| Codex | 디바이스 코드(원격 DSH 권장) · 브라우저 PKCE |
+| Kimi | 디바이스 코드 |
+| Claude | 브라우저 PKCE(원격 브라우저는 전체 localhost redirect URL을 붙여넣기 가능) |
+| Antigravity | `dsh-agy` 설치 상태 + profile-local CLI 명령 |
+
+설정 페이지는 **Accounts**, **Gateway**, **Capabilities**, **About** 네 개의 상위 탭으로 나뉩니다. 로그인된 프로바이더 카드는 간결한 요약으로 접히고 모델 편집 시 펼쳐집니다. CLI pull 미리보기는 전체 너비로 표시되고, Imagine 상태는 Capabilities 탭에서 확인할 수 있습니다.
+
+선택기는 인증을 완료한 라우트만 나열하며, 인증되지 않은 프로바이더는 빈 목록을 반환합니다. 프로바이더 이름에는 `(OAuth)`가 붙고, 로그인/아웃 후 `llm/adapters-updated`를 통해 카탈로그가 갱신됩니다.
+
+## 선택적 기능
+
+8개 스위치 `codexSearch`, `codexImages`, `codexImageEdits`, `codexImagesAnyModel`, `codexUsage`, `codexFast`, `grokImagineImage`, `grokImagineVideo`는 모두 기본적으로 꺼져 있으며 재시작 없이 즉시 적용됩니다. `codexImagesAnyModel`은 호출 모델 라우트 게이트만 완화합니다. 여전히 Codex 로그인, `codexImages`(편집 시 edits 플래그), 세션 첨부 소유권 및 편집 인가가 필요합니다. 숫자 설정은 `searchResults`(1–20, 기본 5), `imageCount`(1–4, 기본 1), `videoArtifactTtlMs`(1시간–7일, 기본 7일, UI에서는 1–168시간)입니다. 보존 시간을 낮추면 기존 아티팩트도 즉시 단축·정리되며, 높인 값은 이후 생성된 아티팩트에만 적용됩니다.
+
+## 로컬 API 게이트웨이
+
+기본값은 **꺼짐**입니다. 활성화하면 DSH 웹 포트와 분리된 독립 `node:http` 서버가 `127.0.0.1:18080`에서 시작되어 같은 로그인 OAuth 세션을 재사용합니다:
+
+```yaml
+gateway:
+  enabled: false
+  bind: 127.0.0.1
+  port: 18080
+  opencodeGo:
+    enabled: false
+```
+
+엔드포인트: `GET /healthz`, `GET /v1/models`, `POST /v1/chat/completions`, `POST /v1/responses`, `POST /v1/messages`. Bearer 키는 `$DSH_HOME/.coding-oauth-gateway.json`(`0600`)에 저장됩니다. 설정에서 OpenAI 베이스 URL(베이스 + `/v1`), Anthropic 베이스 URL, 현재 Bearer 키를 로테이션 없이 복사할 수 있습니다. 키 표시는 루프백에서만 가능하며 브라우저 스토리지에 저장되지 않습니다. 로테이션은 확인이 필요한 파괴적 작업입니다. 리슨 포트는 직접 편집해 Apply로 저장하거나 Random(18100–18999)으로 채울 수 있습니다. 선택한 포트는 소유자 전용 게이트웨이 문서에 저장되고 실행 중인 리스너가 다시 바인딩됩니다. bind는 YAML에서만 변경할 수 있으며, 루프백이 아닌 bind에는 키가 필요합니다. 원격 릴레이가 아닙니다.
+
+선택적 **OpenCode Go 호환**(`gateway.opencodeGo.enabled`, 기본 off)은 Gateway 탭에서 켤 수 있습니다. 켜면 `POST /v1/chat/completions`를 고정 URL `https://opencode.ai/zen/go/v1/chat/completions`로 전달하고 sticky `x-opencode-session`을 주입하여, OpenCode 세션 친화성을 보내지 않는 클라이언트(아니면 `MissingSessionID`)도 이 루프백 게이트웨이로 대화할 수 있습니다. 세션 id 우선순위: `x-deepseek-harness-session-id` → `x-opencode-session` → `x-session-id` → body `session_id` → 생성 UUID. 해당 모드에서는 게이트웨이 Bearer key를 OpenCode API key로 설정하세요. 재시작 없이 전환됩니다.
+
+## CLI
+
+```bash
+# `dsh-grok-build` 는 같은 CLI 별칭
+dsh-coding-oauth login [--pkce] | import | status | logout
+
+# 최신 프로바이더
+dsh-coding-oauth login codex --device-auth | codex --browser | kimi | claude
+dsh-coding-oauth status all
+dsh-coding-oauth logout codex
+
+# Antigravity (먼저 web 프로필에 설치)
+dsh plugin --profile web exec dsh-agy login --headless
+```
+
+> `dsh-agy` CLI는 DSH 프로세스 밖에서 계정 풀을 수정하므로 프로세스 내 카탈로그 이벤트를 내보낼 수 없습니다 — 로그인/아웃 후 모델 선택기를 닫았다 다시 여세요.
+
+## 중국에서의 Kimi
+
+Kimi Code 구독 OAuth는 `https://auth.kimi.com`, 추론은 `https://api.kimi.com/coding`을 사용합니다. `https://api.moonshot.cn/v1`은 종량제 **Moonshot Open Platform** API-key 채널이며, 전환 가능한 "중국 OAuth 엔드포인트"는 없습니다. 이 플러그인은 별도 `kimi-code-oauth` 라우트를 사용하며 기존 `kimi-coding` API-key 설정에 영향을 주지 않습니다.
+
+## 네트워크 프록시
+
+우선순위: `config.proxy` → `CODING_OAUTH_PROXY` → `GROK_BUILD_PROXY` → `HTTPS_PROXY`/`HTTP_PROXY`.
+
+```yaml
+- id: llm-grok-build-oauth
+  config:
+    proxy: http://127.0.0.1:7890
+    proxyKimi: false
+```
+
+검증된 구독 도메인만 프록시됩니다(xAI/Grok, OpenAI Codex, Claude/Anthropic, Google Antigravity). 나머지 DSH 트래픽은 원래 디스패처를 유지합니다. Kimi는 기본적으로 직결이며 `proxyKimi: true`일 때만 프록시를 사용합니다.
+
+## 복원력
+
+OAuth 액세스 토큰은 저장된 만료 시각 **5분 전**에 선제적으로 갱신됩니다(pi-ai 0.84+). 업스트림이 로컬에서는 아직 유효한 토큰을 401/403으로 거절하면, 플러그인이 저장된 `expires`를 과거로 되돌리고 재시도 단계에서 먼저 갱신한 뒤 다시 요청합니다.
+
+요청 재시도는 harness retry 정책을 따릅니다. 일시 오류(`RATE_LIMIT`/`SERVER`/`TIMEOUT`/`TRANSPORT`/`EMPTY_RESPONSE`)와 **`AUTH`**는 지수 백오프로 재시도합니다(기본 5회, 5 s → 10 s → 20 s → 40 s → 80 s (~155 s 누적), 10% jitter). 쿼터 소진과 죽은 refresh token은 재시도하지 않습니다. 배포별 재정의:
+
+```yaml
+- id: llm-grok-build-oauth
+  config:
+    retryPolicy:
+      mode: normal
+      maxRetries: 5
+      retryableCodes: [EMPTY_RESPONSE, RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT, AUTH]
+      backoff: { initialDelayMs: 5000, maxDelayMs: 80000, jitterRatio: 0.1 }
+```
+
+## 자격 증명
+
+소유자 전용 `0600`, 원자적 쓰기, 크로스 프로세스 파일 잠금:
+
+- `$DSH_HOME/.grok-build-auth.json`
+- `$DSH_HOME/.codex-oauth-auth.json`
+- `$DSH_HOME/.kimi-code-oauth-auth.json`
+- `$DSH_HOME/.claude-code-oauth-auth.json`
+
+선택 캐시는 해당 `*-models.json` 파일에 저장됩니다. **HTTP 상태, 로그, UI가 토큰을 반환해서는 안 됩니다.**
+
+## 아키텍처
+
+```mermaid
+flowchart LR
+    subgraph DSH["DSH Harness"]
+        UI[설정 / Web · Coding OAuth] --> LLM[llm route]
+        LLM --> ALIA[라우트 별칭 어댑터]
+    end
+    ALIA --> PI[pi-ai 네이티브 프로바이더<br/>OAuth · 리프레시 · 스트림]
+    PI --> GROK[Grok Build]
+    PI --> COD[Codex]
+    PI --> KIMI[Kimi]
+    PI --> CLAU[Claude]
+    AGY[dsh-agy 플러그인] --> GAL[Google Antigravity]
+```
+
+## 기술 메모
+
+- **Grok Build**: `cli-chat-proxy.grok.com/v1`의 커스텀 Responses 프로바이더, CLI 핑거프린트 헤더, 동적 모델 카탈로그.
+- **Codex/Kimi/Claude**: pi-ai 네이티브 프로바이더가 OAuth와 리프레시를 처리합니다. 라우트 별칭 어댑터가 이를 네이티브 id에 매핑하되 모델 내부 아이덴티티는 변하지 않습니다.
+- Kimi access token은 명시적으로 `Authorization: Bearer`로 변환됩니다 — Anthropic `x-api-key`로 잘못 보내지는 일이 없습니다.
+- Google Antigravity는 여기서 리버스 엔지니어링**하지 않습니다**. 버전 고정형 전용 DSH 플러그인을 사용합니다.
+
+## 준수
+
+제3자 harness를 통한 코딩 구독 사용은 각 벤더 이용약관의 회색 지대에 놓일 수 있으며 할당량, 지역 또는 계정 리스크 관리가 트리거될 수 있습니다. **본인 계정만 사용하세요.** 이 프로젝트는 대량 계정, 할당량 재판매, 원격 릴레이, 페이월 우회, 클라이언트 사칭을 지원하지 않습니다. 상업용으로는 벤더 공식 API-key 채널을 권장합니다.
+
+## 문서
+
+| 문서 | 용도 |
+|---|---|
+| [`INSTALL.md`](INSTALL.md) | 설치·사용 상세 |
+| [`CHANGELOG.md`](CHANGELOG.md) | 릴리스 이력 |
+| [`docs/00-project-rules.md`](docs/00-project-rules.md) | 버전 관리, 릴리스 루프, 공개/로컬 분리 |
+| [`docs/02-architecture.md`](docs/02-architecture.md) | 내부 아키텍처 (라우트 · 데이터 흐름 · 모듈 · API) · [中文](docs/02-architecture.zh-CN.md) |
+| [`CONTRIBUTING.md`](CONTRIBUTING.md) | 기여 가이드 |
+
+## 관련 프로젝트
+
+- [`dsh-agy`](https://www.npmjs.com/package/dsh-agy) — Google Antigravity용 독립 고정 버전 플러그인.
+
+## 기여
+
+기능, 문서, 번역, 버그 보고 등 모든 기여를 환영합니다. 프로세스, 커밋 규칙 및 릴리스 루프는 **[CONTRIBUTING](CONTRIBUTING.md)**을 참조하세요. 목록에 없는 언어라면 README 번역을 PR로 보내 주세요. 위 언어 테이블에 추가하겠습니다.
+
+## 라이선스
+
+[Apache-2.0](LICENSE) · [NOTICE](NOTICE) 참조. 일부는 [dsh-xai](https://github.com/MirDie/dsh-xai) 프로젝트(Apache-2.0)에서 파생되었습니다.