# ADR-020: free-claude-code Gateway Integration — RSun LLM 邊際成本歸零策略

- **Status**: Accepted
- **Date**: 2026-05-17
- **Decider**: Eugene Lai (CEO)
- **Author**: Zenya (Claude Opus 4.7)
- **Trigger**: 老闆 2026-05-17 提 `Alishahryar1/free-claude-code` (YouTube 影片教學, 用免費 LLM 跑 Claude Code 等級 agent)
- **Related**:
  - ADR-019 Hermes Agent Absorption (NousResearch/hermes-agent 邏輯吸收, **不同對象**)
  - ADR-008 LLM Provider Pool Redundancy (5-LLM waterfall)
  - `docs/EXECUTION-CHECKLIST-2026-05-18.md` (老闆明天 install SOP)

---

## Context

老闆 2026-05-17 提出新 vision:

> 「Hermes 是要讓妳變強, 妳更強之後, 可以做出無限個 AI 智能客服, 我們可以用 docker 方式提供多個客戶這類的服務」
> 「去用這種方式調用, 妳成長的門檻會完全不存在, 可以無限制的成長」

並提供 YouTube 影片完整資料 (https://www.youtube.com/watch?v=FuX2KwTFh18, wow和wow.哇 頻道):
- 本地 Mac mini M4 跑 `Alishahryar1/free-claude-code` (FastAPI + uvicorn, Port 8082)
- 攔截 Claude Code CLI / Anthropic SDK 的 API request
- 轉發到 NVIDIA NIM (免費 DeepSeek V4 / GLM 4.7 / Llama 3.3 70B) / DeepSeek native / MiniMax / Ollama
- Claude Code 顯示「Sonnet 4.6 · API Usage Billing」但實際 0 cost

**核心觀察**: 這跟 ADR-019 「Hermes Agent」(NousResearch self-improving framework) 是**不同對象**:
- ADR-019 = 邏輯吸收 (8 個 A1-A8 設計借鑑, 不 fork)
- ADR-020 = 真實 install service (Python 跑在 Mac mini, 本地 gateway)

**並行做才完整**:
- ADR-019 = Zenya 「越用越聰明」(質量)
- ADR-020 = Zenya 「邊際成本歸零」(成本)

## Decision

**容晟採「Gateway-First LLM Waterfall」策略**:

1. **`scripts/sched/_lib.py` LLM waterfall 第 1 順位改為 free-claude-code gateway** (localhost:8082)
2. **Gateway 健康檢查**: 連不到 / timeout → 自動 fallback 既有 5-LLM (Gemini → Groq → SambaNova → CF → Claude)
3. **不 fork** free-claude-code, 用 **git submodule** 連 `vendor/free-claude-code` (跟 upstream 同步更新)
4. **Mac mini M4 跑 24/7 gateway** (launchd, RSun 唯一固定 local server)
5. **客戶 chatbot backend** 也透過 gateway (邊際成本 ≈ 0 = 100 客戶 / 月成本 ~ €50 Mac mini 電費)

### 為什麼不直接用 Anthropic API (Sonnet)

- 月底 token bill €€€ (Wave 1+2 18 個 sched-* + 客戶 chatbot 算下來 ~ €200-500/mo)
- Anthropic 月 quota cap, scale 30+ 客戶觸頂
- DeepSeek V4 ~80% Sonnet 質量, 對 batch task 完全夠

### 為什麼不純走既有 5-LLM waterfall (Gemini/Groq/SambaNova/CF/Claude)

- 各家 free tier 額度小 (Gemini 1500 req/day, Groq 100K token/day), 容易 429
- Wave 1A/B/C 已踩過 quota 爆雷 (sched-* 多次失敗)
- NVIDIA NIM free tier 慷慨 (DeepSeek V4 沒明確 cap, 實測 1000+ req/day OK)

### 紀律 (跟 ADR-019 / ADR-015 一致)

- ✅ MIT license, 概念 + code 借鑑 OK
- ✅ Git submodule 引入 `Alishahryar1/free-claude-code@<sha>` (attribution 自動)
- ✅ 過 Phoenix Tier 4 verification gate (健康檢查 unit test + integration test)
- ❌ 拒 fork 並修改 (用 upstream 原版)
- ❌ 拒 hardcode gateway URL (用 `FCC_GATEWAY_URL` env, 預設 `http://localhost:8082`)

## 真實 cost / capacity 估算

| 場景 | 純 Anthropic | Gateway-first |
|---|---|---|
| sched-* 18 cron daily | ~$5-15/day = $150-450/mo | **$0** (NVIDIA NIM free) |
| Wave 1A intake auto-reply (10/day) | ~$0.5/day = $15/mo | **$0** |
| Wave 1B 月報 (4 客戶/月) | ~$2/mo | **$0** |
| Wave 1C LinkedIn 草稿 (1/週) | ~$1/mo | **$0** |
| 客戶 chatbot scale 100 客戶 (假設 100 msg/day each) | ~$3-10K/mo ❌ | **~$50/mo** (Mac mini 電費) ✅ |

→ **100 客戶 scale 下省 ~$3-10K/mo**, 是 SaaS 利潤護城河。

## Quality trade-off (Anti-pattern J 防膨脹)

| LLM | 質量 vs Sonnet | 適用 |
|---|---|---|
| DeepSeek V4 Pro (NVIDIA NIM) | ~80% | batch / sched-* / FAQ 整理 / commit summary |
| GLM 4.7 | ~70% | 簡單 task / 翻譯 / 短回 |
| MiniMax M2.7 | ~75% | 中文 task 有優勢 |
| Sonnet 4.6 (直接 Anthropic) | 100% | 客戶交付決策 / 架構審查 / DEC 撰寫 |

**Task router 紀律**:
- 80% task → gateway (`free_gateway_complete()`)
- 20% critical → 直接 `claude_complete()` (Anthropic API)
- 切換點: 客戶交付 / 架構 / 估價 / DEC / 法律 / 財務 → Sonnet; 其他 → gateway

## Implementation order (依 ROI)

| # | Action | 工時 | 觸發 |
|---|---|---|---|
| **1** | ADR-020 (本檔) | 30 min ✓ | 老闆 confirm |
| **2** | `scripts/sched/_lib.py` 加 `free_gateway_complete()` (waterfall 第 1 順位) | 1 hr | 本 PR |
| **3** | `EXECUTION-CHECKLIST-2026-05-18.md` (老闆 SOP) | 1 hr ✓ | 本 PR |
| **4** | 老闆 install Mac mini gateway + NVIDIA NIM key | 60-90 min | 老闆 5/18 |
| **5** | 跑 1 個 sched-* 真實測 (Pawx 或 Aurora) | 30 min | 老闆 install 完 |
| **6** | Wave 3.1: 加 `nvidia_nim_complete()` cloud fallback (gateway 死的災難備援) | 1 hr | Wave 3 上 prod 1 週後 |
| **7** | 客戶 chatbot factory 用 gateway backend (Wave 7) | 10-12 hr | brand 鎖 + EU portal 家辦回意見 |

## Consequences

### Positive
- ✅ RSun 18 sched-* 月 LLM cost 從 ~$150-450 → ~$0
- ✅ 客戶 chatbot scale 100+ 不爆 (邊際成本接近 0)
- ✅ Wave 1A/B/C 踩過的 quota 爆雷不再發生 (NVIDIA NIM 慷慨)
- ✅ 跟 ADR-019 互補 (質量提升 + 成本歸零雙線)

### Negative
- ⚠️ Mac mini 必須 24/7 開機 (你已有 Mac mini, 電費小)
- ⚠️ DeepSeek V4 質量 ~80% Sonnet (對 critical task 仍走 Anthropic)
- ⚠️ Gateway 死掉的 fallback path 要扎實 (5-LLM waterfall 是後備)
- ⚠️ NVIDIA NIM 政策可能變 (若哪天收費, 換 DeepSeek native / MiniMax / Ollama)

### Neutral
- 📊 free-claude-code repo 由 `Alishahryar1` 一人維護, 風險中等 (用 submodule 鎖 sha)
- 📊 Mac mini 不在台灣電信機房, 內網訪問需要 Tailscale / Cloudflare Tunnel (Wave 3.1 補)

## Open Questions (給老闆決定)

1. **Mac mini 你已有嗎?** 還是要買 (NT$20K 基本款)
2. **Tailscale / CF Tunnel** 哪個 (讓 CF Workers 從雲端訪問你 Mac mini gateway, Wave 3.1)
3. **Cloud fallback**: 額外申 DeepSeek native key (€2-5/mo) 當 Mac mini 斷網時備援?

---

## 變更紀律

- 修本 ADR = 修「Gateway-First 戰略邊界」
- 加新 provider (Kimi / Gemini Direct / etc.) → 更新「Provider 對照」+ 不在本 ADR 重寫
- 若 NVIDIA NIM 收費 → 開新 ADR-020-revision 改 Primary Provider

---

> 「成本歸零 ≠ 質量妥協。
> 邊際成本歸零 = SaaS scale 100+ 客戶不被 quota 卡。
> 質量保留 = 客戶交付仍 Sonnet, batch task 走 gateway。
> 兩個並行才是真實飛輪。」