add README.md, QUICKSTART.md, SUMMARY.md documentation
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
95
QUICKSTART.md
Normal file
95
QUICKSTART.md
Normal file
@@ -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，稍後重試 |
|
||||
95
README.md
Normal file
95
README.md
Normal file
@@ -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`）或輸入「大盤」，即可自動觸發對應腳本並產生綜合摘要。
|
||||
|
||||
## 授權
|
||||
|
||||
內部工具，僅供個人使用。
|
||||
79
SUMMARY.md
Normal file
79
SUMMARY.md
Normal file
@@ -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` 載入，支援多路徑搜尋
|
||||
Reference in New Issue
Block a user