diff --git a/QUICKSTART.md b/QUICKSTART.md new file mode 100644 index 0000000..8264f80 --- /dev/null +++ b/QUICKSTART.md @@ -0,0 +1,95 @@ +# 快速開始 + +## 1. 設定環境變數 + +在專案根目錄建立 `.env`： + +``` +BROWSERLESS_ENDPOINT=http://192.168.42.124:13000 +BROWSERLESS_TOKEN=your_token_here +``` + +> TWSE 腳本（`twse-*.py`）與 Yahoo 直接 API 腳本不需要此設定，可直接執行。 + +## 2. 確認 Python 版本 + +```bash +python3 --version # 需要 3.10+ +``` + +不需要安裝任何第三方套件，全部使用 Python 標準函式庫。 + +## 3. 測試連線 + +先測試不需要 Browserless 的腳本： + +```bash +# TWSE 融資融券（不需 Browserless） +python3 scripts/twse-margin-trading.py 2330 + +# Yahoo 均線（不需 Browserless） +python3 scripts/yahoo-ma-signal.py 2330 +``` + +再測試 Browserless 腳本： + +```bash +# 個股報價（需 Browserless） +python3 scripts/yahoo-quote-browserless.py 2330 +``` + +## 4. 常用查詢組合 + +### 個股速查（三大核心） + +```bash +python3 scripts/yahoo-quote-browserless.py 2330 +python3 scripts/yahoo-institutional-browserless.py 2330 +python3 scripts/yahoo-technical-browserless.py 2330 +``` + +### 個股深度分析（全套） + +```bash +python3 scripts/yahoo-quote-browserless.py 2330 +python3 scripts/yahoo-institutional-browserless.py 2330 +python3 scripts/yahoo-technical-browserless.py 2330 +python3 scripts/yahoo-dividend-browserless.py 2330 +python3 scripts/yahoo-broker-trading-browserless.py 2330 +python3 scripts/yahoo-ma-signal.py 2330 +python3 scripts/yahoo-macd-signal.py 2330 +python3 scripts/twse-margin-trading.py 2330 +python3 scripts/twse-day-trading.py 2330 +python3 scripts/twse-foreign-holdings.py 2330 +``` + +### ETF 查詢 + +```bash +python3 scripts/yahoo-quote-browserless.py 0050 +python3 scripts/yahoo-etf-holdings.py 0050 +python3 scripts/yahoo-technical-browserless.py 0050 +``` + +### 大盤 + +```bash +python3 scripts/yahoo-market-browserless.py +``` + +## 5. 透過 Claude Code 使用 + +安裝為 skill 後，直接在 Claude Code 中輸入： + +- `2330` → 自動執行個股全套分析 +- `0050` → 自動執行 ETF 分析（含持股） +- `大盤` → 自動執行大盤查詢 + +## 常見問題 + +| 問題 | 解法 | +|------|------| +| `缺少必要環境變數` | 確認 `.env` 檔存在且格式正確 | +| `Browserless 導航逾時` | 檢查 Browserless 服務是否正常運作 | +| `找不到 XXXX 的融資融券資料` | TWSE 假日無資料，腳本會自動回溯 10 個工作日 | +| `Yahoo API 錯誤` | Yahoo 偶有 rate limit，稍後重試 | diff --git a/README.md b/README.md new file mode 100644 index 0000000..804a20d --- /dev/null +++ b/README.md @@ -0,0 +1,95 @@ +# stocks-query + +台股個股與大盤即時查詢工具集，透過 Yahoo 奇摩股市與證交所（TWSE）公開資料，輸出精簡繁體中文摘要。 + +## 功能總覽 + +| 類別 | 腳本 | 說明 | +|------|------|------| +| **報價** | `yahoo-quote-browserless.py` | 個股即時報價（現價、開高低收、成交量、最佳五檔） | +| **法人** | `yahoo-institutional-browserless.py` | 三大法人買賣超（外資／投信／自營商） | +| **技術面** | `yahoo-technical-browserless.py` | RSI14、ATR14、KD、布林通道、近 5 日 K 線 | +| **均線** | `yahoo-ma-signal.py` | MA5／10／20／60 與 20 日乖離率 | +| **MACD** | `yahoo-macd-signal.py` | DIF、DEA、柱體與金叉／死叉判讀 | +| **大盤** | `yahoo-market-browserless.py` | 加權指數即時行情 | +| **股利** | `yahoo-dividend-browserless.py` | 殖利率、歷年現金／股票股利、除息日 | +| **券商** | `yahoo-broker-trading-browserless.py` | 主力券商買賣超排行 | +| **ETF** | `yahoo-etf-holdings.py` | 前十大持股、行業比重、資產分佈 | +| **融資融券** | `twse-margin-trading.py` | 融資融券餘額與券資比 | +| **當沖** | `twse-day-trading.py` | 當日沖銷成交量與佔比 | +| **外資持股** | `twse-foreign-holdings.py` | 外資持有股數與持股比例 | + +## 環境需求 + +- Python 3.10+（僅使用標準函式庫，無需 pip install） +- Browserless 服務（`*-browserless.py` 腳本需要） +- 網路連線（存取 Yahoo Finance TW 與 TWSE API） + +## 環境變數 + +Browserless 腳本需要以下環境變數，可寫在 `.env` 檔中： + +``` +BROWSERLESS_ENDPOINT=http://192.168.42.124:13000 +BROWSERLESS_TOKEN=your_token_here +``` + +`.env` 搜尋順序：目前目錄 → workspace 根目錄（scripts 上三層）。 + +TWSE 系列腳本（`twse-*.py`）與 Yahoo API 腳本（`yahoo-ma-signal.py`、`yahoo-macd-signal.py`、`yahoo-etf-holdings.py`）不需要 Browserless，直接呼叫公開 API。 + +## 使用方式 + +```bash +# 個股完整分析（以台積電 2330 為例） +python3 scripts/yahoo-quote-browserless.py 2330 +python3 scripts/yahoo-institutional-browserless.py 2330 +python3 scripts/yahoo-technical-browserless.py 2330 +python3 scripts/yahoo-dividend-browserless.py 2330 +python3 scripts/yahoo-broker-trading-browserless.py 2330 +python3 scripts/yahoo-ma-signal.py 2330 +python3 scripts/yahoo-macd-signal.py 2330 +python3 scripts/twse-margin-trading.py 2330 +python3 scripts/twse-day-trading.py 2330 +python3 scripts/twse-foreign-holdings.py 2330 + +# ETF（以 0050 為例） +python3 scripts/yahoo-quote-browserless.py 0050 +python3 scripts/yahoo-etf-holdings.py 0050 + +# 大盤 +python3 scripts/yahoo-market-browserless.py +``` + +## 代號格式 + +| 類型 | 格式 | 範例 | +|------|------|------| +| 上市股票 | 4 碼數字 | `2330`、`3481`、`2454` | +| ETF | `00` 開頭 | `0050`、`00922`、`006208` | +| 加權指數 | `^TWII` | 大盤查詢預設值 | + +腳本會自動加上 `.TW` 後綴組成 Yahoo URL。 + +## 輸出範例 + +``` +台積電（2330） +• 現價：598.00 +• 漲跌：+3.00（+0.50%） +• 開盤／最高／最低：596.00／600.00／595.00 +• 昨收：595.00 +• 成交量：25,000,000（Yahoo 顯示 25,000 張，換算股數） +• 均價：597.50 +• 最佳買賣：597.00／598.00 +• 市場狀態：開盤中 +• 資料時間：2026-04-10 13:30:00（台北） +``` + +## 與 Claude Code 整合 + +本工具集已註冊為 Claude Code skill（見 `SKILL.md`）。在 Claude Code 中輸入股票代號（如 `2330`）或輸入「大盤」，即可自動觸發對應腳本並產生綜合摘要。 + +## 授權 + +內部工具，僅供個人使用。 diff --git a/SUMMARY.md b/SUMMARY.md new file mode 100644 index 0000000..6fc3db7 --- /dev/null +++ b/SUMMARY.md @@ -0,0 +1,79 @@ +# 腳本摘要 + +## 架構概覽 + +``` +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` 載入，支援多路徑搜尋