From 6b63e539b364844d87bc99accee8bb3754f9bfd0 Mon Sep 17 00:00:00 2001 From: Timmy Date: Fri, 10 Apr 2026 11:05:39 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=20README=E3=80=81QUI?= =?UTF-8?q?CKSTART=E3=80=81SUMMARY=20=E6=96=87=E4=BB=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 涵蓋功能說明、依賴需求、快速上手步驟、執行流程圖解、 雙版本差異對照，以及 PDF 轉換的已知限制（禁止 emoji）。 Co-Authored-By: Claude Opus 4.6 (1M context) --- QUICKSTART.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 64 ++++++++++++++++++++++++++++++++++++++++++++ SUMMARY.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 207 insertions(+) create mode 100644 QUICKSTART.md create mode 100644 README.md create mode 100644 SUMMARY.md diff --git a/QUICKSTART.md b/QUICKSTART.md new file mode 100644 index 0000000..e608868 --- /dev/null +++ b/QUICKSTART.md @@ -0,0 +1,74 @@ +# 快速開始 + +## 1. 確認依賴 + +### stocks-query skill + +報告產生器依賴 `stocks-query` skill 的腳本，確認已安裝在 `../stocks-query/`： + +```bash +ls ../stocks-query/scripts/yahoo-quote-browserless.py +``` + +### Python 套件 + +```bash +python3 -c "import markdown; from weasyprint import HTML; print('OK')" +``` + +若尚未安裝： + +```bash +pip3 install markdown weasyprint +``` + +### CJK 字型 + +PDF 需要中文字型。macOS 內建 PingFang TC，無需額外安裝。Linux 環境需安裝 Noto Sans CJK TC： + +```bash +# Ubuntu/Debian +sudo apt install fonts-noto-cjk +``` + +## 2. 透過 Claude Code 產生報告 + +最簡單的方式是直接在 Claude Code 中使用： + +``` +/stocks-report 2330 # 台積電完整報告 +/stocks-report 00922 # ETF 報告 +``` + +執行完成後會告知四個檔案路徑與大小。 + +## 3. 輸出位置 + +報告存放在工作目錄的 `stocks/` 資料夾： + +``` +stocks/2330-report-20260410.md +stocks/2330-report-20260410.pdf +stocks/2330-report-20260410-beginner.md +stocks/2330-report-20260410-beginner.pdf +``` + +## 4. 本地持股整合 + +若 `stocks/` 目錄中有 `<代號>-TW.md` 檔案，報告會自動讀取並計算： + +- 平均成本與未實現損益 +- 已領配息金額 +- 含息總報酬 +- 各批次是否符合配息資格（對照除息日） + +持股紀錄格式範例請參考既有的 `*-TW.md` 檔案。 + +## 常見問題 + +| 問題 | 解法 | +|------|------| +| PDF 出現字型錯誤 | 確認報告內容不含 emoji，改用 `[+]`/`[!]`/`[-]` 標記 | +| `ModuleNotFoundError: weasyprint` | 執行 `pip3 install weasyprint` | +| 某區段顯示「無資料」 | 正常現象，該資料來源暫時無法取得（假日、ETF 不適用等） | +| PDF 中文亂碼 | 確認系統已安裝 CJK 字型 | diff --git a/README.md b/README.md new file mode 100644 index 0000000..f772192 --- /dev/null +++ b/README.md @@ -0,0 +1,64 @@ +# stocks-report + +台股個股完整分析報告產生器，自動整合即時行情、法人籌碼、技術指標與本地持股紀錄，輸出排版完整的 Markdown 與 PDF。 + +## 功能特色 + +- **雙版本輸出**：專業版（給有經驗的投資人）＋白話解讀版（給入門者） +- **四檔輸出**：每次產出 `.md` + `.pdf` 各兩份 +- **自動整合持股**：若本地有 `<代號>-TW.md` 紀錄，自動計算平均成本、含息報酬 +- **ETF／個股判別**：`00` 開頭自動走 ETF 流程（持股分析），否則走個股流程（月營收、本益比） + +## 報告涵蓋範圍 + +| 區段 | 內容 | +|------|------| +| 大盤同步 | 加權指數、漲跌、成交金額 | +| 報價 | 現價、開高低收、成交量、均價、最佳五檔 | +| 三大法人 | 外資／投信／自營商買賣超 | +| 主力券商 | 買超／賣超前 5 大券商明細 | +| 融資融券 | 融資融券餘額、券資比 | +| 當沖統計 | 當沖成交量與佔比 | +| 外資持股 | 持有股數與持股比例 | +| 技術面 | RSI14、ATR14、KD、布林通道、近 5 日 K 線 | +| 股利殖利率 | 歷年配息、殖利率、除息日 | +| ETF 持股 | 前十大持股、行業比重、資產分佈（僅 ETF） | +| 月營收 | 當月營收、MoM、YoY、累計（僅個股） | +| 本益比 | PE ratio、股價淨值比（僅個股） | +| 白話判斷 | 綜合技術面＋籌碼面＋配息面的多空結論 | +| 個人持股 | 成本、損益、配息資格（若有本地紀錄） | + +## 依賴 + +- **stocks-query skill**（`../stocks-query/`）：所有資料擷取腳本皆在此 +- **Python 套件**：`markdown`、`weasyprint`（PDF 轉換） +- **CJK 字型**：系統需安裝 PingFang TC、Heiti TC 或 Noto Sans CJK TC + +## 輸出路徑 + +``` +stocks/ +├── <代號>-report-YYYYMMDD.md 專業版 Markdown +├── <代號>-report-YYYYMMDD.pdf 專業版 PDF +├── <代號>-report-YYYYMMDD-beginner.md 白話解讀版 Markdown +└── <代號>-report-YYYYMMDD-beginner.pdf 白話解讀版 PDF +``` + +## 透過 Claude Code 使用 + +本工具已註冊為 Claude Code skill。在對話中使用 `/stocks-report` 加上股票代號即可觸發： + +``` +/stocks-report 2330 +/stocks-report 00922 +``` + +## 注意事項 + +- 報告內容禁止使用 emoji，以避免 weasyprint 嵌入 Apple Color Emoji 字型導致 PDF 開啟錯誤 +- 白話版使用純文字標記：`[+]` 正面、`[!]` 留意、`[-]` 負面 +- 所有內容皆為繁體中文（台灣），日期使用西元格式，金額使用千分位 + +## 授權 + +內部工具，僅供個人使用。 diff --git a/SUMMARY.md b/SUMMARY.md new file mode 100644 index 0000000..3376ebd --- /dev/null +++ b/SUMMARY.md @@ -0,0 +1,69 @@ +# 流程摘要 + +## 架構概覽 + +``` +stocks-report（本 skill） +│ +├── SKILL.md 報告產生流程定義（Claude Code 讀取） +├── CLAUDE.md 專案說明與架構文件 +│ +└── 依賴 stocks-query skill + └── scripts/ 所有資料擷取腳本（12 支） +``` + +本 skill 不含程式碼，所有邏輯定義在 `SKILL.md` 中，由 Claude Code 依照流程執行。 + +## 執行流程 + +``` +1. 資料收集 ───────────────────────────────────────────── + │ 平行執行 stocks-query 的 9～12 支腳本 + │ 同時檢查本地持股紀錄 (<代號>-TW.md) + ▼ +2. 組裝專業版 Markdown ────────────────────────────────── + │ 整合所有腳本輸出為結構化報告 + │ → stocks/<代號>-report-YYYYMMDD.md + ▼ +3. 轉換專業版 PDF ─────────────────────────────────────── + │ markdown + weasyprint，CJK 字型排版 + │ → stocks/<代號>-report-YYYYMMDD.pdf + ▼ +4. 組裝白話解讀版 Markdown ────────────────────────────── + │ 問句式標題、術語翻譯、生活化比喻 + │ 純文字標記（禁止 emoji） + │ → stocks/<代號>-report-YYYYMMDD-beginner.md + ▼ +5. 轉換白話解讀版 PDF ────────────────────────────────── + │ 字體 14px、行距 1.8，適合閱讀 + │ → stocks/<代號>-report-YYYYMMDD-beginner.pdf + ▼ +6. 回覆使用者 ─────────────────────────────────────────── + 回報四個檔案路徑與大小 +``` + +## ETF 與個股的差異 + +| 步驟 | ETF（`00` 開頭） | 個股 | +|------|------------------|------| +| 額外腳本 | `yahoo-etf-holdings.py` | `twse-monthly-revenue.py`、`twse-pe-pbr.py` | +| 報告區段 | ETF 持股與配置（前十大、行業、資產） | 月營收、本益比／股價淨值比 | +| 跳過項目 | 月營收、本益比 | ETF 持股 | + +## 雙版本差異 + +| 項目 | 專業版 | 白話解讀版 | +|------|--------|-----------| +| 標題風格 | 標準術語 | 問句式（「大咖們在幹嘛？」） | +| 表格 | 純數據 | 多一欄「白話意思」 | +| 技術指標 | 直接列數值 | 搭配生活化比喻 | +| 總結 | 偏多／偏空／震盪 | 評分表 + 紅綠燈判斷 | +| 字體大小 | 13px / 12px | 14px / 13px | +| 行距 | 1.6 | 1.8 | +| 符號 | 無限制 | 禁止 emoji，使用 `[+]`/`[!]`/`[-]` | + +## PDF 轉換技術細節 + +- 工具：Python `markdown` 套件 → HTML → `weasyprint` → PDF +- 字型優先順序：PingFang TC → Heiti TC → Microsoft JhengHei → Noto Sans CJK TC +- 已知限制：不可使用 emoji 字元，否則 weasyprint 會嵌入 Apple Color Emoji 導致 PDF 閱讀器報錯