From 3e93a2dcb3c3a02e93940d8b6de8e0fb67cc52a6 Mon Sep 17 00:00:00 2001 From: Timmy Date: Fri, 10 Apr 2026 10:46:35 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E5=88=9D=E5=A7=8B=E6=8F=90=E4=BA=A4=20?= =?UTF-8?q?stocks-report=20skill=EF=BC=8C=E5=90=AB=20emoji=20=E7=A6=81?= =?UTF-8?q?=E7=94=A8=E8=A6=8F=E5=89=87?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 白話解讀版禁止使用 emoji（🟢🟡🔴），改用純文字標記 [+]/[!]/[-]， 避免 weasyprint 嵌入 Apple Color Emoji 字型導致 PDF 開啟時報錯。 Co-Authored-By: Claude Opus 4.6 (1M context) --- CLAUDE.md | 39 +++++++++++++ SKILL.md | 160 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 199 insertions(+) create mode 100644 CLAUDE.md create mode 100644 SKILL.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..29829b8 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,39 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Overview + +This is a Claude Code skill that generates comprehensive Taiwan stock analysis reports (Markdown + PDF). It depends on the sibling `stocks-query` skill (`../stocks-query/scripts/`) for all data-fetching scripts. + +## Architecture + +The skill has no code of its own — `SKILL.md` defines the orchestration workflow: + +1. **Data collection**: Run 9+ Python scripts from `../stocks-query/scripts/` in parallel (Browserless-based scrapers for Yahoo Finance TW, plus direct TWSE API scripts) +2. **Report assembly**: Combine all script outputs into a structured Markdown file at `stocks/<代號>-report-YYYYMMDD.md` +3. **PDF conversion**: Use Python `markdown` + `weasyprint` to render Markdown → styled PDF with CJK font support +4. **Beginner version**: Generate a second "白話解讀版" (plain-language) report pair (`.md` + `.pdf`) with simplified explanations + +## Key Dependencies + +- **stocks-query skill** (`../stocks-query/`): All data scripts live there. See its `CLAUDE.md` for script details, environment variables (`BROWSERLESS_ENDPOINT`, `BROWSERLESS_TOKEN`), and API patterns. +- **Python packages**: `markdown`, `weasyprint` (for PDF generation) +- **CJK fonts**: PDF rendering requires "PingFang TC", "Heiti TC", or "Noto Sans CJK TC" installed on the system + +## ETF vs. Individual Stock Logic + +- ETFs (symbol starts with `00`): run `yahoo-etf-holdings.py`, skip `twse-monthly-revenue.py` and `twse-pe-pbr.py` +- Individual stocks: run `twse-monthly-revenue.py` and `twse-pe-pbr.py`, skip ETF holdings script + +## Output + +All reports go to `stocks/` directory: +- `stocks/<代號>-report-YYYYMMDD.md` — professional report +- `stocks/<代號>-report-YYYYMMDD.pdf` — professional PDF +- `stocks/<代號>-report-YYYYMMDD-beginner.md` — plain-language report +- `stocks/<代號>-report-YYYYMMDD-beginner.pdf` — plain-language PDF + +## Language + +All output, reports, and user-facing text must be in Traditional Chinese (Taiwan). Dates use `YYYY-MM-DD`, monetary values use thousands separators. diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..f47f2d3 --- /dev/null +++ b/SKILL.md @@ -0,0 +1,160 @@ +--- +name: stocks-report +description: 產生台股個股完整分析報告（Markdown + PDF）。輸入股票代號（例如 2330、00922），自動執行所有查詢腳本、整合本地持股紀錄，輸出排版完整的 .md 與 .pdf 到 stocks/ 目錄。 +--- + +# stocks-report + +產生台股個股完整分析報告，輸出 Markdown 與 PDF。 + +## 執行流程 + +### 1) 先執行 stocks-query skill 取得所有資料 + +依序執行（盡量平行呼叫以加快速度）： + +```bash +python3 skills/stocks-query/scripts/yahoo-institutional-browserless.py <代號> +python3 skills/stocks-query/scripts/yahoo-quote-browserless.py <代號> +python3 skills/stocks-query/scripts/yahoo-technical-browserless.py <代號> +python3 skills/stocks-query/scripts/twse-margin-trading.py <代號> +python3 skills/stocks-query/scripts/yahoo-dividend-browserless.py <代號> +python3 skills/stocks-query/scripts/yahoo-market-brief.py +python3 skills/stocks-query/scripts/yahoo-broker-trading-browserless.py <代號> +python3 skills/stocks-query/scripts/twse-day-trading.py <代號> +python3 skills/stocks-query/scripts/twse-foreign-holdings.py <代號> +``` + +若標的**不是** ETF（非 `00` 開頭），額外執行： + +```bash +python3 skills/stocks-query/scripts/twse-monthly-revenue.py <代號> +python3 skills/stocks-query/scripts/twse-pe-pbr.py <代號> +``` + +若標的是 ETF（`00` 開頭），改為額外執行： + +```bash +python3 skills/stocks-query/scripts/yahoo-etf-holdings.py <代號> +``` + +同時檢查本地是否有該代號的持股紀錄（`stocks/<代號>-TW.md`）。 + +### 2) 組裝 Markdown 報告 + +將所有腳本輸出整合為一份結構化 Markdown，存為 `stocks/<代號>-report-YYYYMMDD.md`。 + +報告結構（依序）： + +``` +# <代號> <名稱>｜完整分析報告 +> 報告日期：YYYY-MM-DD +--- +## 大盤同步 +## 報價 +## 三大法人 +## 主力券商進出 + ### 買超前 5 大券商（表格） + ### 賣超前 5 大券商（表格） +## 融資融券 +## 當沖統計 +## 外資持股 +## 技術面 + ### 近 5 日 K 線（表格） +## 股利殖利率 + ### 近期配息明細（表格） +## ETF 持股與配置（僅 ETF） + ### 前十大持股 + ### 行業比重 + ### 資產分佈 +## 月營收（僅非 ETF） +## 本益比／股價淨值比（僅非 ETF） +## 白話判斷 +## 個人持股紀錄（若有本地紀錄） +``` + +規則： +- 所有表格使用 Markdown table 語法 +- 若某腳本失敗或無資料，該區段標註「無資料」，不要省略區段 +- 白話判斷要綜合技術面、籌碼面、配息面給出偏多／偏空／震盪的結論 +- 個人持股需正確計算平均成本、含息報酬、哪幾張可領配息（對照除息日） + +### 3) 轉換為 PDF + +用以下 Python 程式將 Markdown 轉為 PDF： + +```python +import markdown +from weasyprint import HTML + +with open('', 'r') as f: + md_text = f.read() + +html_body = markdown.markdown(md_text, extensions=['tables', 'fenced_code']) + +full_html = ''' + + +''' + html_body + '' + +HTML(string=full_html).write_pdf('') +``` + +輸出：`stocks/<代號>-report-YYYYMMDD.pdf` + +### 4) 產生白話解讀版 + +除了專業版之外，額外產生一份「白話解讀版」，讓不熟悉股市的人也能看懂。 + +存為 `stocks/<代號>-report-YYYYMMDD-beginner.md` 及對應 `.pdf`。 + +白話解讀版規則： +- 標題格式：`# <代號> <名稱>｜白話解讀版` +- 每個區段用**問句**當標題（例如「現在多少錢？」「大咖們在幹嘛？」「散戶有沒有在瘋搶？」） +- 所有術語第一次出現時，用括號或「像是在說...」欄位附上白話翻譯 +- 表格多加一欄「白話意思」，用日常語言解釋數字的含義 +- 技術指標用生活化比喻（例如 RSI 像溫度計、布林通道像天花板和地板） +- 最後總結用簡單評分表呈現結論 +- **禁止使用 emoji**（如 🟢🟡🔴），改用純文字標記（如 `[+]` 正面、`[!]` 留意、`[-]` 負面），避免 weasyprint 嵌入 Apple Color Emoji 字型導致 PDF 開啟時出現字型錯誤 +- 個人持股區段用「什麼時候買的／買多少／能不能領紅包」等直白欄位 +- 字體稍大（font-size: 14px）、行距較寬（line-height: 1.8）方便閱讀 + +轉 PDF 時使用與專業版相同的程式，但 CSS 調整為： +- `font-size: 14px`（body） +- `line-height: 1.8` +- `font-size: 13px`（table） + +### 5) 回覆使用者 + +告知四個檔案路徑（專業版 .md/.pdf + 白話解讀版 .md/.pdf）和檔案大小。 + +## 回覆風格 + +- 使用繁體中文（台灣） +- 報告內容全部繁體中文 +- 日期使用西元格式 YYYY-MM-DD +- 金額使用千分位格式 +- 標題和內容要自行措辭，不要直接引用使用者的指令用語