# YouTube Dashboard Plugin

[English](README.en.md) · [首次設定](docs/self-hosting.md) · [資料目錄](docs/data-catalog.md)

開源自架的 YouTube 儀表板。每個人執行自己的副本，使用自己的 Google OAuth 設定；憑證、授權、報表及自訂版面保存在自己的環境。維護者沒有共用的資料接收後端。

網站與 Plugin 使用同一份 `src/` 核心、統計與面板。名稱、副標題、圖標和主題由使用者儲存為顯示偏好，原始碼不綁定特定品牌或頻道。

## 安裝與啟動

需要 Node.js 24 以上。從 GitHub 取得原始碼後：

```sh
git clone https://github.com/KaiQin04/youtube-dashboard-plugin.git
cd youtube-dashboard-plugin
npm ci --ignore-scripts --no-audit --no-fund
npm run setup
```

在自己的系統瀏覽器開啟終端顯示的 `http://127.0.0.1:4318/`。依 [首次設定指南](docs/self-hosting.md) 建立一個 Google OAuth Web client，在本機表單輸入 ID 與 Secret，再授權自己的 YouTube 頻道。加密金鑰會自動在本機產生；不要把憑證貼到聊天。

後續開啟直接讀取保存的連線與快照；需要更新時同步最近 28 天，授權失效才重新連接。

## 安裝 Plugin

停止上述前景服務（Ctrl+C）後，使用 [官方自訂 marketplace 流程](https://developers.openai.com/plugins/build/plugins#add-a-marketplace-from-the-cli)：

```sh
codex plugin marketplace add .
codex plugin add youtube-dashboard@youtube-dashboard-community
```

在桌面客戶端啟用 Plugin，執行 Setup 或請它「開啟我的 YouTube 儀表板」。本機 MCP 會啟動同一工作台；不需要額外的 Google OIDC 登入，也不需要部署共用 Sites。若客戶端的安裝副本尚未包含依賴，先依 Setup 指引在該副本執行鎖定版本安裝，再重新啟動連線。

在支援 [OpenAI 側邊欄入口](https://developers.openai.com/plugins/build/extensions#sidebar-apps) 的桌面 host，可從側邊欄或對話側面板開啟 **YouTube Dashboard**。入口不需頻道 ID，也不會自動同步或啟動 Google 授權；尚未設定時按「Google 設定與頻道授權」前往自己的本機瀏覽器。已有連線時直接顯示保存資料。未支援入口的 host 仍可用工具開啟面板或本機網址。

下載式安裝包以 `npm run build:plugin` 產生 ZIP 與 SHA-256 manifest；ZIP 已包含鎖定的 `jose` 依賴。解壓後同樣可加入本機 marketplace。此方式是 GitHub／自訂 marketplace 發行，尚未提交官方公開目錄。

## 功能與資料

- 頻道總覽、每日趨勢、影片成效、互動、流量來源、國家、裝置與逐段留存等報表區塊，支援 CSV／JSON。
- Cold Porcelain 與 15 種其他主題；自訂名稱、副標題顯示、圖標、區塊與欄位。
- 本機網站和 Plugin 使用相同報表與版面；不同本機 profile、帳號及連線分開保存。

預設查最近 28 天，最多 31 天、500 支可存取影片，成功同步後冷卻 15 分鐘。未提供的數值顯示「—」；不提供 Studio 即時數據，收益、曝光與 CTR 仍未提供。附加報表由各區塊明確更新，留存需選擇已授權頻道的影片。目前沒有關閉程式後仍執行的背景同步。

預設資料位於 `~/.youtube-dashboard/`，可用 `YTDASH_HOME` 選擇獨立資料夾。安裝目錄可以更新，資料不用跟著搬。Tool 回傳的報表仍會提供給聊天主機與模型；詳見 [資料與隱私](docs/self-hosting.md#資料與隱私)。

## 開發與其他部署

```sh
npm test
npm run check
npm run build:plugin
```

多人 Google OIDC 網站保留為 `npm run start:web`；[Sites 適配](sites/README.md) 是選用部署，均引用同一共享核心。實際主機、既有私人資料與憑證不隨安裝包發行；既有 owner-bound 網站可用 [同一核心的相容 adapter](docs/owner-site-integration.md)，保留原資料與授權格式；更新 repository 不會自動部署。

程式使用 [MIT](LICENSE)，第三方出處見 [NOTICE](NOTICE)。