docs: 新增 README、QUICKSTART、SUMMARY 文件
涵蓋功能說明、依賴需求、快速上手步驟、執行流程圖解、 雙版本差異對照，以及 PDF 轉換的已知限制（禁止 emoji）。 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
74
QUICKSTART.md
Normal file
74
QUICKSTART.md
Normal file
@@ -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 字型 |
|
||||||
64
README.md
Normal file
64
README.md
Normal file
@@ -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 開啟錯誤
|
||||||
|
- 白話版使用純文字標記：`[+]` 正面、`[!]` 留意、`[-]` 負面
|
||||||
|
- 所有內容皆為繁體中文（台灣），日期使用西元格式，金額使用千分位
|
||||||
|
|
||||||
|
## 授權
|
||||||
|
|
||||||
|
內部工具，僅供個人使用。
|
||||||
69
SUMMARY.md
Normal file
69
SUMMARY.md
Normal file
@@ -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 閱讀器報錯
|
||||||
Reference in New Issue
Block a user