# dsh-super-subscriptions

[![CI](https://github.com/JoeeLiu/dsh-super-subscriptions/actions/workflows/ci.yml/badge.svg)](https://github.com/JoeeLiu/dsh-super-subscriptions/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)
[![DSH Plugin](https://img.shields.io/badge/DeepSeek%20Harness-plugin-6f42c1.svg)](https://github.com/deepseek-ai/deepseek-harness)
[![版本](https://img.shields.io/badge/version-1.0.1-0ea5e9.svg)](./CHANGELOG.md)

> DeepSeek Harness（DSH）的統一訂閱供應商整合外掛：把帳號登入、模型路由、用量顯示、搜尋與媒體能力整合到單一 Cordis plugin。

[English](./README.md)

## 外掛解決什麼問題

`dsh-super-subscriptions` 讓 DSH Web profile 透過訂閱帳號使用多個模型供應商。它把原本需要分別安裝、而且容易重複註冊 route、工具與設定 UI 的功能整合為一個清楚的外掛入口。

主要功能：

- ChatGPT/Codex、Grok、Google AntiGravity 的 OAuth 與本機帳號管理。
- 保留原始訂閱外掛中的 Claude 與 GitHub Copilot 選用整合。
- 供應商模型探索、預設帳號、帳號池、token 更新與失敗切換。
- 側邊欄固定全寬的用量區塊，依供應商分組顯示 5 小時、每週及其他服務回報的限制視窗。
- Web 設定頁：登入、帳號狀態、用量刷新、路由、Proxy 與診斷。
- 統一註冊 `image_generate`、`video_generate`、`x_search`、`view_image` 工具。
- 接回 Codex Connect 原生圖片生成註冊與本機附件預覽。
- 將舊的 `openai-codex` route 遷移至統一的 `codex` route。

本專案是獨立的 DSH 社群專案，與 DeepSeek AI、OpenAI、xAI、Google、Anthropic、GitHub 沒有隸屬、背書或官方合作關係。

## 供應商一覽

| 供應商 | 預設 | Route | 登入方式 | 已整合能力 |
| --- | ---: | --- | --- | --- |
| ChatGPT / Codex | 開啟 | `codex` | OAuth PKCE | Responses 串流、帳號池、用量刷新、GPT 圖片生成 |
| Grok | 開啟 | `grok` | OAuth PKCE | Responses 串流、帳號池、X 搜尋、Grok 圖片與影片生成 |
| Google AntiGravity | 開啟 | `antigravity` / `agy` | Google OAuth 或既有 `agy` 憑證 | 模型探索、思考串流、帳號池、用量與 CLI bridge |
| Claude | 關閉 | `claude` | Claude Code 憑證或 OAuth | 保留的選用訂閱供應商整合 |
| GitHub Copilot | 關閉 | `copilot` | GitHub device flow | 保留的選用訂閱供應商整合 |

實際可用的模型、額度視窗、媒體 endpoint 與能力會受各供應商服務和訂閱方案控制。登入成功不代表該帳號一定能使用所有模型或功能。

## 需求與相容性

- DeepSeek Harness `0.1.1-rc.2` 或相容的目前 `0.1.x` Web profile。
- Node.js 20 以上。
- 開發與本機安裝需要 pnpm 9 以上。
- 每個開啟的供應商都需要對應的有效訂閱帳號。
- AntiGravity 需要 `agy` 可執行檔，或使用內建 Google OAuth 流程；內建流程需要由環境變數提供自己的 `AGY_CLIENT_ID` 與 `AGY_CLIENT_SECRET`。

`1.0.1` 已在 Windows 的 DSH `0.1.1-rc.2`、Node.js 24、pnpm 11 環境完成型別檢查、測試與 production build。

## 安裝

### 從公開 GitHub repository 安裝

目前本專案透過 GitHub 發佈，尚未假設 npm 已有同名套件：

```bash
dsh plugin --profile web add github:JoeeLiu/dsh-super-subscriptions
```

安裝後重啟 Web profile：

```bash
dsh web
```

未來若發布 npm 版本，會在此 README 補上正式 npm 安裝指令。在 npm 發布前，不要把 `dsh-super-subscriptions` 當成已存在的 npm 套件直接安裝。

若要使用固定的 `v1.0.1` 預建置套件，可直接安裝 GitHub Release tarball：

```bash
dsh plugin --profile web add https://github.com/JoeeLiu/dsh-super-subscriptions/releases/download/v1.0.1/dsh-super-subscriptions-1.0.1.tgz
```

### 本機開發安裝

```bash
git clone https://github.com/JoeeLiu/dsh-super-subscriptions.git
cd dsh-super-subscriptions
pnpm install
pnpm run check
```

若要把工作目錄掛入本機 Web profile，請在該 profile 的 `package.json` 使用 `file:` dependency。當此整合外掛取代重疊的上游 provider bundle 時，profile 只應啟用這個 bundle。

### 卸載與回復

從指定 profile 移除套件後重啟 DSH：

```bash
dsh plugin --profile web remove dsh-super-subscriptions
dsh web
```

如果這次安裝取代了原本重疊的 provider，請在重啟前恢復 profile 的 package 與 Cordis patch 備份。除非你也要刪除帳號，否則不要刪除本機 credential store。

## 第一次設定

1. 啟動 DSH Web，使用一般瀏覽器開啟 `http://127.0.0.1:3080`。
2. 開啟 **設定 → 外掛 → Super Subscriptions**。
3. 開啟需要使用的供應商。
4. 對 ChatGPT/Codex、Grok 或 AntiGravity 按下 **登入**，在瀏覽器完成供應商 OAuth。AntiGravity 請先設定 OAuth 環境變數，或直接使用既有的 `agy` CLI 登入。
5. 回到 DSH，重新整理供應商狀態與模型清單。

如果登入流程依賴瀏覽器原有 Cookie，啟動器必須使用一般瀏覽器的既有 profile。隔離的嵌入式瀏覽器或臨時 profile 不會自動共享那些 Cookie。

登入後直接選擇供應商模型即可使用；route 由模型 id 決定。訂閱登入流程不需要 API key，API-key 型整合不在本外掛範圍內。

## 設定

[`cordis.patch.yml`](./cordis.patch.yml) 已提供預設配置：

```yaml
- insert:
    - id: llm-super-subscriptions
      name: dsh-super-subscriptions
      config:
        providers:
          chatgpt:
            enabled: true
          grok:
            enabled: true
          antigravity:
            enabled: true
            permissionMode: skip
          claude:
            enabled: false
          copilot:
            enabled: false
        codexRoute: codex
        migrateOpenAiCodex: true
        enableSearch: true
        enableImageTool: true
        enableImageGeneration: true
```

完整設定 schema：

```ts
interface SuperSubscriptionsConfig {
  providers?: {
    chatgpt?: { enabled?: boolean; streamIdleTimeoutMs?: number }
    grok?: { enabled?: boolean; streamIdleTimeoutMs?: number }
    antigravity?: {
      enabled?: boolean
      agyBin?: string
      permissionMode?: 'skip' | 'plan' | 'accept-edits'
      workspaceRoot?: string
      defaultModel?: string
      defaultEffort?: string
    }
    claude?: { enabled?: boolean; streamIdleTimeoutMs?: number }
    copilot?: { enabled?: boolean; streamIdleTimeoutMs?: number }
  }
  codexRoute?: string
  migrateOpenAiCodex?: boolean
  enableSearch?: boolean
  enableImageTool?: boolean
  enableImageGeneration?: boolean
}
```

AntiGravity 內建 Google OAuth 流程會從 DSH 程序環境讀取 `AGY_CLIENT_ID` 與 `AGY_CLIENT_SECRET`。這兩個值刻意不放入公開 repository。如果不想自行建立 OAuth client，可以先使用 `agy` 登入，外掛會沿用本機的 `agy` 憑證。

除非已明確設定不重疊的 route，否則不要同時啟用 `dsh-plugin-subscriptions`、`dsh-agy-link` 或 `dsh-codex-connect`。它們會註冊相近的供應商、工具或設定 UI，容易造成重複註冊或帳號儲存衝突。

## 工具與媒體能力

| 工具 | 供應商 | 用途 |
| --- | --- | --- |
| `image_generate` | ChatGPT/Codex 或 Grok | 統一圖片生成，可傳入 `provider: "gpt"` 或 `provider: "grok"` |
| `codex_connect_image_generate` | ChatGPT/Codex | Codex Connect 原生 GPT Image 2 路由與 DSH 附件預覽 |
| `view_image` | 本機附件儲存 | 解析與顯示生成或附加的圖片 |
| `video_generate` | Grok | 生成並儲存短片 Grok Imagine 影片 |
| `x_search` | Grok | 透過 xAI hosted tool 搜尋 X 貼文及相關公開內容 |

訂閱圖片路徑在供應商帳號與 endpoint 支援時使用 `gpt-image-2` 與 `grok-imagine-image-2.0`。圖片內容儲存在本機 DSH 附件區，不會提交到此 Git repository。

## 帳號儲存、權限與隱私

- 供應商 token 儲存在本機 DSH home，通常是 `~/.dsh/plugins/super-subscriptions/`。
- 舊訂閱帳號會以非破壞方式匯入，不會刪除原本的 credential store。
- AntiGravity 也可能使用使用者 home 下的原生憑證格式，讓 `agy` binary 能使用對應帳號。
- 選用的 AntiGravity OAuth client credentials 由環境變數提供，絕不儲存在此 repository。
- 外掛會對已開啟的供應商 OAuth、模型、用量、搜尋與媒體 endpoint 發出必要的 HTTPS 請求。
- Web 設定與 loopback callback server 綁定本機 DSH endpoint，並在適用處使用 callback state、PKCE 與 trusted-origin 檢查。
- Proxy 為選用設定，儲存在本機 DSH profile。
- Token、API key、瀏覽器 Cookie、私人帳號資料與生成媒體都不應進入 Git；`.gitignore` 已排除本機 credential、環境檔、build 產物與上游參考目錄。

安裝前請閱讀原始碼與各供應商服務條款。這個外掛以 DSH 程序的權限執行，能存取你啟用的訂閱帳號。

## 疑難排解

### 瀏覽器顯示登入成功，但 DSH 仍顯示未登入

保持 DSH 在同一個 loopback origin，於一般瀏覽器完成 callback，並等待設定頁輪詢 callback 結果。如果 callback 頁顯示成功但 UI 尚未更新，先重新整理供應商狀態，不要立刻重跑整個 OAuth。

### Grok 或 ChatGPT 出現串流/parser 錯誤

確認 profile 只有這個整合外掛擁有 `grok` 與 `codex` route。`1.0.1` 已輸出 DSH 的 `text-delta`、`reasoning-delta`、`tool-call-delta`、`reasoning`、`tool-call` chunk，並在 access token 過期時自動刷新後重試。

### Grok 回傳 request validation error

沒有工具的普通 Grok 對話不應送出工具專用欄位。請更新至 `1.0.1`，並確認 profile 沒有同時載入舊的 Grok adapter。

### AntiGravity 出現 `payload.provider must be one of ...`

通常代表未經 DSH tools 編譯的舊工具定義或重複的 AntiGravity 工具仍在 host 中。只保留這個 bundle，重啟 DSH，再刷新供應商與模型清單。

### 圖片已生成，但 UI 只顯示附件 ID

Web client 必須透過 DSH attachment RPC 載入附件。請確認 host 與 client 都是同一個 `1.0.1` build，然後重新整理 Web 頁面。

### 用量沒有顯示

用量 API 會受供應商、帳號與方案影響。從設定頁刷新供應商，確認 token 有效，再檢查供應商狀態；空的限制視窗不應直接解讀成使用量為零。

## 開發與測試

```bash
pnpm install
pnpm run typecheck
pnpm test
pnpm run build
```

`pnpm run check` 會依序執行型別檢查、完整 Vitest 測試與 production bundle build。供應商修改應加入登入、request shape、串流轉換、用量與錯誤恢復的針對性測試。

`.upstream/` 是開發整合時使用的本機參考快取，刻意列入 ignore，不是本專案的發佈內容，也不會進入套件。

## 架構與目錄

```text
src/
├── index.ts                    Cordis host entry 與註冊
├── config.ts                   Schemastery 設定與預設值
├── auth/                       OAuth、callback、device flow、token store
├── core/                       migration、RPC、token lifecycle、安全 helper
├── providers/
│   ├── codex/                  ChatGPT/Codex adapter 與登入
│   ├── grok/                   Grok adapter、登入、搜尋與媒體
│   ├── antigravity/            Google AntiGravity 與 agy bridge
│   ├── claude/                 選用 Claude 整合
│   └── copilot/                選用 GitHub Copilot 整合
├── features/                   search、image transport、proxy、diagnostics
├── tools/                      可由模型呼叫的搜尋、圖片、影片工具
└── client/                     設定頁、側欄用量、工具 view、語系
```

架構總覽請見 [`docs/architecture-overview.md`](./docs/architecture-overview.md)，設計決策請見 [`docs/architecture/`](./docs/architecture/)。

## DSH Market metadata 與提交資訊

`package.json` 的 `dsh.market` 已加入 DSH Market 所需的雙語名稱、描述、分類、圖示、功能 tags 與預設供應商資訊。Repository 也宣告 `dsh-plugin` keyword，並提供根目錄 `dsh.bundle.patch`，方便社群 DSH catalog 掃描與驗證。

公開列表文案與提交檢查表維護在 [`docs/DSH-MARKET.md`](./docs/DSH-MARKET.md)。公開 GitHub repository 與 `dsh-plugin` topic 是基本條件；在市場 registry 實際接受或掃描到之前，不會把本專案宣稱為「已上架」。

## 版本與發佈

本專案遵循 Semantic Versioning 與 Keep a Changelog。`1.0.1` 是第一個完成 ChatGPT/Codex、Grok、AntiGravity、用量 UI 與圖片能力修復的整合版本，變更詳情請見 [`CHANGELOG.md`](./CHANGELOG.md)。

## 授權與致謝

本專案採用 [Apache License 2.0](./LICENSE)。整合的上游原始碼與架構來源列在 [`NOTICE`](./NOTICE) 與 [`THIRD_PARTY_NOTICES`](./THIRD_PARTY_NOTICES)，每個上游原始部分仍依其原本授權條款適用。

安全問題請依 [`SECURITY.md`](./SECURITY.md) 回報，不要直接建立公開 issue。