docs: 新增 README、QUICKSTART、SUMMARY 文件

涵蓋功能說明、依賴需求、快速上手步驟、執行流程圖解、
雙版本差異對照,以及 PDF 轉換的已知限制(禁止 emoji)。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-04-10 11:05:39 +08:00
parent 3e93a2dcb3
commit 6b63e539b3
3 changed files with 207 additions and 0 deletions

74
QUICKSTART.md Normal file
View 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 字型 |