# 腳本摘要

## 架構概覽

```
scripts/
├── Browserless 腳本（需 headless browser）
│   ├── yahoo-quote-browserless.py        報價
│   ├── yahoo-institutional-browserless.py 法人買賣超
│   ├── yahoo-technical-browserless.py     技術指標
│   ├── yahoo-market-browserless.py        大盤指數
│   ├── yahoo-dividend-browserless.py      股利政策
│   └── yahoo-broker-trading-browserless.py 主力券商
│
├── Yahoo 直接 API（免 Browserless）
│   ├── yahoo-etf-holdings.py             ETF 持股分析
│   ├── yahoo-ma-signal.py                均線訊號
│   └── yahoo-macd-signal.py              MACD 訊號
│
└── TWSE 公開 API（免 Browserless）
    ├── twse-margin-trading.py            融資融券
    ├── twse-day-trading.py               當沖統計
    └── twse-foreign-holdings.py          外資持股
```

## 各腳本輸出欄位

### yahoo-quote-browserless.py
現價、漲跌（金額＋百分比）、開盤、最高、最低、昨收、成交量（張＋股數）、均價、最佳買價／賣價、市場狀態、資料時間

### yahoo-institutional-browserless.py
日期、外資買賣超（張）、投信買賣超（張）、自營商買賣超（張）、三大法人合計

### yahoo-technical-browserless.py
近 5 日 K 線（開高低收）、RSI14、ATR14、K 值、D 值、布林上軌／中軌／下軌

### yahoo-market-browserless.py
加權指數、漲跌（點數＋百分比）、開盤、最高、最低、昨收、成交金額（億）、資料時間

### yahoo-dividend-browserless.py
現金殖利率、現金股利、股票股利、除息日、發放日、近年股利歷史（年度／現金／股票／合計）

### yahoo-broker-trading-browserless.py
日期、買超前 5 大券商（買進／賣出／差額張數）、賣超前 5 大券商

### yahoo-etf-holdings.py
前十大持股（排名／名稱／占比）、行業比重、資產分佈；支援 text／json／csv 輸出格式

### yahoo-ma-signal.py
收盤價、MA5／10／20／60、20 日乖離率、趨勢判讀（站上月線／跌破月線、中期偏多／偏弱等）

### yahoo-macd-signal.py
DIF、DEA、HIST、訊號判讀（金叉／死叉／多頭延續／空頭延續／震盪）

### twse-margin-trading.py
日期、融資買進／賣出／現償／餘額／限額、融券賣出／買進／現償／餘額／限額、券資比

### twse-day-trading.py
日期、當沖買進股數、當沖賣出股數、當沖成交金額、當沖佔比

### twse-foreign-holdings.py
日期、外資持股股數、外資持股比率、發行股數、尚可投資股數、投資上限比率

## 資料來源

| 來源 | 用途 | 備註 |
|------|------|------|
| Yahoo 奇摩股市 (tw.stock.yahoo.com) | 報價、法人、技術、股利、券商、ETF | 需透過 Browserless 渲染 JS |
| Yahoo Finance Chart API (query1.finance.yahoo.com) | 均線、MACD、技術面 K 線 | 直接 HTTP GET，回傳 JSON |
| 證交所 TWSE (www.twse.com.tw) | 融資融券、當沖、外資持股 | 公開 JSON API，免認證 |

## 共通設計模式

- **輸入**：股票代號作為第一個命令列參數，未提供時使用預設值
- **輸出**：繁體中文條列式摘要，印到 stdout
- **錯誤**：訊息印到 stderr，exit code 1
- **依賴**：僅 Python 標準函式庫（urllib、json、re、datetime 等）
- **日期回溯**：TWSE 腳本自動往前找最多 10 個工作日的資料
- **環境變數**：Browserless 腳本從 `.env` 載入，支援多路徑搜尋