前言:
偶然在 Youtube 上看到一個即時監控台積電(TSMC)的頻道, 我立刻截圖, 如下圖:
想利用 Antigravity CLI 做一個類似的功能, 因此把這張截圖請 agy cli 幫忙完成, 果然不到幾分鐘就完成了。
後來, 我又加了幾個功能：
1. 新增了一個 Competitor Pulse 區塊, 加入美股的 Intel 與韓股的 Samsung.
2. 新增了美股或台股交易期間, 每三分鐘更新即時行情(agy cli 自動幫我在非交易期間, 每五分鐘更新一次。）
3. 原本只有顯示台股與美股交易時間的區塊, 我請 agy cli 幫我放台股的大盤指數與櫃買指數, 與美股的紐約證券指數, Nasdaq 指數及費城半導體指數。
結果如下圖:
整個過程花了不到三小時就完成了, Vibe coding 實在太厲害了。
我也請 agy cli 根據這次的開發幫我寫一個針對有 python 程式設計者寫一個 Blog, 結果如下：
# 🚀 從零打造「台積電 ADR 跨國套利監控儀表板」：Python 實戰與大盤指數 API 踩坑記
大家好！身為一個關注台股與美股的投資人/開發者，你是否曾想過即時監控**台積電（2330.TW）**與其在美股發行的 **TSMC ADR（TSM）** 之間的折溢價（跨國套利空間）？
今天這篇文章將帶領大家使用 Python，從零開始打造一個**極具科技感、支援交易時間與非交易時間雙模式更新、並整合美台關鍵大盤指數**的網頁儀表板。
這篇文章特別適合**具備基本 Python 開發經驗**，想嘗試金融 API 串接、自動化背景排程，或是對前端 CSS 排版感興趣的朋友！
---
## 💡 為什麼要監控 TSMC ADR 折溢價？
台積電（2330）普通股在台灣上市，而 TSM ADR 則在美國紐約證交所（NYSE）交易。兩者有著 **1 單位 ADR = 5 股普通股** 的固定換算比例。
由於兩地交易時間不同，加上匯率波動，美股 ADR 的價格換算回台幣後，往往與台股有著數個百分點的「折溢價差」（通常 ADR 會有溢價）。這個價差往往是隔天台股開盤時的重要指標！
我們的公式非常簡單：
1. **ADR 折算台幣價** = $\frac{\text{ADR 收盤價 (USD)} \times \text{匯率}}{5}$
2. **折溢價 %** = $\frac{\text{ADR 折算台幣價} - \text{台股收盤價}}{\text{台股收盤價}} \times 100\%$
---
## 🛠️ 技術挑戰與架構設計
我們希望這個監控系統不只是「跑一次就結束」的腳本，而是一個**可以 24 小時不間斷運行、自動偵測開收盤時間、並定時更新網頁**的常駐服務。
我們設計了以下三個主要機制：
1. **時區與開盤狀態自動偵測**：自動判定台北時間與紐約時間是否處於交易時段。
2. **雙模式定時更新（Dual-Mode Daemon）**：
* **開盤期間**：每 3 分鐘請求一次 API，抓取最新報價，並更新網頁。
* **收盤期間**：每 5 分鐘執行一次，**但不調用 yfinance API**（避免被 Yahoo 限流），而是讀取本地快取 JSON 數據，僅**更新網頁右上角的「編譯時間」**，呈現系統依然在運作。
3. **大盤指數與自製 API 串接**：除了個股，我們還需要台股加權指數、美國 Nasdaq、費半、NYSE 指數，以及台灣的**櫃買指數 (TPEx)**。
---
## 💣 踩坑實錄：櫃買指數 (TPEx) 去哪了？
在開發過程中，我們遇到了一個巨大的坑：**Yahoo Finance (`yfinance`) 對於台灣櫃買指數（代碼 `^TWOII`）的支援極度不穩定**，常常回傳空值或找不到代碼。
### 解決方案：直連櫃買中心官方 OpenAPI
既然第三方庫不給力，我們就直接找官方！我們查到了台灣櫃買中心提供的免費 OpenAPI：
* **端點**：`https://www.tpex.org.tw/openapi/v1/tpex_index`
然而，直接用 Python `requests` 呼叫時會遇到 SSL 憑證錯誤（`SSLCertVerificationError`）。這是因為政府單位的 SSL 憑證鏈可能缺少了部分根憑證。
我們可以用以下代碼，安全地跳過憑證驗證來解決這個問題：
```python
import requests
import urllib3
def get_tpex_index():
try:
# 停用不安全請求警告，避免 Console 輸出大量 Warning
urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
# verify=False 跳過 SSL 驗證，timeout 防止程式卡死
r = requests.get('https://www.tpex.org.tw/openapi/v1/tpex_index', verify=False, timeout=5)
data = r.json()
if data:
latest = data[-1] # 取得最新的一筆資料
close = float(latest["Close"])
change = float(latest["Change"])
prev_close = close - change
pct = (change / prev_close) * 100.0 if prev_close > 0 else 0.0
return close, pct
except Exception as e:
print(f"Warning fetching TPEx index: {e}")
return 0.0, 0.0
```
這段代碼成功幫助我們繞過了 Yahoo Finance 的缺失，直接獲取精準的櫃買指數與漲跌幅！
---
## ⚙️ 雙模式後台 Daemon 實作
為了讓背景服務更聰明地運行，我們在 `main` 函數中實作了時間檢測與快取切換邏輯：
```python
import time
import sys
from datetime import datetime
from zoneinfo import ZoneInfo
def check_tw_market_status(dt):
# 台灣開盤時間為週一至週五 09:00 - 13:30
if dt.weekday() < 5 and 9 * 60 <= dt.hour * 60 + dt.minute <= 13 * 60 + 30:
return "OPEN"
return "CLOSED"
def main():
if "--loop" in sys.argv:
print("常駐模式啟動中...")
while True:
dt_tw = datetime.now(ZoneInfo("Asia/Taipei"))
dt_ny = datetime.now(ZoneInfo("America/New_York"))
tw_status = check_tw_market_status(dt_tw)
us_status = check_us_market_status(dt_ny) # 同理判定美股
if tw_status == "OPEN" or us_status == "OPEN":
# 開盤時間：爬取 API 並更新快取
run_once(use_cache=False)
time.sleep(180) # 3 分鐘更新一次
else:
# 收盤時間：讀取快取僅更新網頁時間戳
run_once(use_cache=True)
time.sleep(300) # 5 分鐘重繪一次
```
這樣的設計保證了網頁能隨時反映監控服務的活躍狀態，又極具效率。
---
## 🎨 儀表板排版美學（CSS 亮點）
對於自動生成的網頁，我們採用了極具質感的**深藍科技風（Dark Mode）**。特別是中間下方的市場指數顯示區，我們使用了精準的 CSS 佈局：
```css
.market-status-card {
background-color: #0b1120;
border: 1px solid #1e293b;
border-radius: 12px;
padding: 15px 20px;
}
.market-indices {
display: flex;
flex-direction: column;
gap: 6px;
margin-top: 8px;
padding-left: 45px; /* 與國家標籤對齊，騰出左側空間 */
border-bottom: 1px dashed #1e293b; /* 虛線分隔 */
padding-bottom: 10px;
}
.index-item {
display: flex;
justify-content: space-between;
align-items: center;
font-size: 11px;
}
.index-value {
color: #f8fafc;
font-family: monospace; /* 數字使用等寬字型，避免跳動 */
font-weight: 700;
margin-left: auto;
margin-right: 15px;
}
```
這段樣式讓數值以 monospace 字型呈現，且將漲跌幅固定寬度靠右對齊，解決了常見網頁數據對不齊、數字寬度不同導致排版凌亂的問題。
---
## 📈 運行效果與總結
當你啟動此監控服務時：
* 終端機（Terminal）會漂亮地列出目前的換算價格與大盤狀態。
* 自動輸出的 HTML 網頁不僅能透過手機或電腦流暢瀏覽，更內含動態套利指針（SVG Gauge）、半導體供應鏈板塊（NVDA, AAPL 等），以及最新大盤表現。
在金融開發的路上，**「合理運用快取降低 API 消耗」**與**「直連官方 API 解決第三方庫失效」**是開發者必備的硬實力。希望這篇實戰筆記能對你有所啟發，歡迎動手自己玩玩看！
*有任何想法或問題，歡迎在下方留言討論！*
留言