add README.md, QUICKSTART.md, SUMMARY.md documentation

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

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`）或輸入「大盤」，即可自動觸發對應腳本並產生綜合摘要。
+
+## 授權
+
+內部工具，僅供個人使用。