Timmy
7d72aed984
Recover 7 existing scripts from remote repo and rebuild 5 missing ones: - twse-margin-trading.py (融資融券) - twse-day-trading.py (當沖交易) - twse-foreign-holdings.py (外資持股) - yahoo-dividend-browserless.py (股利資訊) - yahoo-broker-trading-browserless.py (主力券商進出) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
108 lines
4.3 KiB
Markdown
108 lines
4.3 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Overview
|
|
|
|
This is a stock query skill for Taiwan stock market data. Python scripts in `scripts/` fetch data from Yahoo Finance Taiwan using a Browserless headless browser service, then output concise Chinese summaries.
|
|
|
|
## Environment Variables
|
|
|
|
All `*-browserless.py` scripts require these environment variables (loaded from `.env`):
|
|
- `BROWSERLESS_ENDPOINT` - Browserless service URL (e.g., `http://192.168.42.124:13000`)
|
|
- `BROWSERLESS_TOKEN` - Authentication token for Browserless
|
|
|
|
The `.env` file is searched first in current directory, then at workspace root (3 levels up from scripts).
|
|
|
|
## Architecture
|
|
|
|
Scripts fall into two categories:
|
|
|
|
### 1. Browserless Scripts (Dynamic Content Scraping)
|
|
Use Browserless to fetch Yahoo pages that require JavaScript rendering:
|
|
|
|
| Script | Purpose |
|
|
|--------|---------|
|
|
| `yahoo-quote-browserless.py` | Individual stock quote (price, OHLC, volume, bid/ask) |
|
|
| `yahoo-institutional-browserless.py` | Three major institutional investors (foreign, trust, dealer) |
|
|
| `yahoo-technical-browserless.py` | Technical indicators (RSI14, ATR14, KD, Bollinger Bands, 5-day K-line) |
|
|
| `yahoo-market-browserless.py` | TAIEX weighted index (^TWII) market summary |
|
|
| `yahoo-dividend-browserless.py` | Dividend history (cash/stock dividend, ex-date, yield) |
|
|
| `yahoo-broker-trading-browserless.py` | Top broker buy/sell rankings |
|
|
|
|
### 2. Direct API Scripts (No Browserless Required)
|
|
Use Yahoo Finance Chart API directly:
|
|
|
|
| Script | Purpose |
|
|
|--------|---------|
|
|
| `yahoo-etf-holdings.py` | ETF holdings (top 10, industry distribution, asset allocation) |
|
|
| `yahoo-ma-signal.py` | Moving averages (MA5/10/20/60) and 20-day bias |
|
|
| `yahoo-macd-signal.py` | MACD indicator (DIF, DEA, histogram) |
|
|
|
|
### 3. TWSE Public API Scripts (No Browserless Required)
|
|
Use TWSE open data API directly:
|
|
|
|
| Script | Purpose |
|
|
|--------|---------|
|
|
| `twse-margin-trading.py` | Margin trading balance (融資融券餘額) |
|
|
| `twse-day-trading.py` | Day trading statistics (當沖交易統計) |
|
|
| `twse-foreign-holdings.py` | Foreign investor holdings ratio (外資持股比例) |
|
|
|
|
## Common Commands
|
|
|
|
### Query individual stock (full analysis)
|
|
```bash
|
|
# Three scripts are typically run together for complete picture
|
|
python3 skills/stocks-query/scripts/yahoo-institutional-browserless.py 2330
|
|
python3 skills/stocks-query/scripts/yahoo-quote-browserless.py 2330
|
|
python3 skills/stocks-query/scripts/yahoo-technical-browserless.py 2330
|
|
```
|
|
|
|
### Query ETF (with holdings)
|
|
```bash
|
|
python3 skills/stocks-query/scripts/yahoo-quote-browserless.py 0050
|
|
python3 skills/stocks-query/scripts/yahoo-etf-holdings.py 0050
|
|
```
|
|
|
|
### Query market index
|
|
```bash
|
|
python3 skills/stocks-query/scripts/yahoo-market-browserless.py
|
|
```
|
|
|
|
### MA/MACD signals (direct API, no Browserless)
|
|
```bash
|
|
python3 skills/stocks-query/scripts/yahoo-ma-signal.py 2330
|
|
python3 skills/stocks-query/scripts/yahoo-macd-signal.py 2330
|
|
```
|
|
|
|
### Dividend / Broker trading (Browserless)
|
|
```bash
|
|
python3 skills/stocks-query/scripts/yahoo-dividend-browserless.py 2330
|
|
python3 skills/stocks-query/scripts/yahoo-broker-trading-browserless.py 2330
|
|
```
|
|
|
|
### TWSE data (margin, day-trading, foreign holdings)
|
|
```bash
|
|
python3 skills/stocks-query/scripts/twse-margin-trading.py 2330
|
|
python3 skills/stocks-query/scripts/twse-day-trading.py 2330
|
|
python3 skills/stocks-query/scripts/twse-foreign-holdings.py 2330
|
|
```
|
|
|
|
## Script Patterns
|
|
|
|
- All scripts accept stock symbol as first command-line argument (default provided)
|
|
- Browserless scripts use `urllib` or `subprocess` with `curl` to POST to Browserless `/content` endpoint
|
|
- HTML parsing uses regex patterns (not BeautifulSoup) to minimize dependencies
|
|
- Output format is Chinese text summaries with bullet points
|
|
- Error handling exits with code 1 and prints error message to stderr
|
|
|
|
## Stock Number Format
|
|
|
|
- Taiwan stocks: 4-digit number (e.g., `2330`, `3481`)
|
|
- ETFs: Typically start with `00` (e.g., `0050`, `00922`)
|
|
- Yahoo suffix: `.TW` is appended automatically in URLs
|
|
|
|
## Skill Integration
|
|
|
|
This directory is registered as a skill (see `SKILL.md`). When users input a stock number or ask about "大盤" (market), the scripts should be executed in sequence and results synthesized into a concise Chinese summary with plain-language interpretation of technical indicators.
|