daily_stock_analysis (DSA) 詳細教學

本教學對應 repo commit 8be6546 (2026-05-20, v3.17.1 之後)，最後驗證日 2026-05-20。 涵蓋專案定位、安裝（4 種方案）、核心架構、CLI 詳細用法、應用場景、資安、FAQ、進階技巧、整合 9 個章節，重點是「多供應商抽象 + GitHub Actions 排程 + 多通道通知」三個可移植 pattern。

1. 專案定位

1.1 是什麼

daily_stock_analysis (DSA) 是中國地區開源圈最熱門的 LLM 股票智能分析系統（38k stars / 1300+ PR 合併 / 約週發 release），核心能力：

• 資產覆蓋：A股、港股、美股、ETF
• 資料整合：行情 + 即時新聞 + 技術指標 + 資金流 + 籌碼 + 公告 + 基本面
• AI 分析：用 LLM 產出「決策儀表盤」（核心結論、評分、趨勢、買賣點位、風險、催化因素、操作 checklist）
• 多通道推送：14+ 通知 (企微 / 飛書 / Telegram / Discord / Slack / Email / Pushover / Ntfy / Gotify / PushPlus / ServerChan / Astrbot / Custom Webhook)
• 5 種介面：CLI / FastAPI / Web 工作台 / 桌面 app / Telegram+Discord Bot
• 零成本：用 GitHub Actions 排程（非交易日不執行、有斷點續傳）

1.2 為什麼重要

1.3 與相關工具的關係

1.4 一句話總結

用 LLM 把「行情 + 新聞」總結成可推送到多通道的決策報告，重點在「多供應商抽象 + GitHub Actions 免費排程 + 14 通道通知」三個 pattern 可移植到任何「定期報告 + 多通道推送」系統。

1.5 重要免責

README 末尾顯著聲明：「本項目僅供研究、教學、娛樂用途，不構成投資建議」。所有輸出需人工複核。

2. 安裝指南（4 種方案）

2.1 方案 A — GitHub Actions（推薦，免費）

1# 1. Fork repo: https://github.com/ZhuLinsen/daily_stock_analysis
2# 2. Settings → Secrets and variables → Actions → New repository secret
3#    (至少配一個 AI 模型 + 一個通知通道 + STOCK_LIST)
4# 3. Actions → "I understand my workflows, go ahead and enable them"
5# 4. Actions → 每日股票分析 → Run workflow → Run workflow

必填 Secrets：

預設排程：工作日 18:00（北京時間）自動執行；非交易日（A/H/US 節假日）跳過。

2.2 方案 B — 本地 Python

 1# 系統需求：Python 3.10+
 2git clone https://github.com/ZhuLinsen/daily_stock_analysis
 3cd daily_stock_analysis
 4
 5# 強烈建議用 uv 管理 env（CLAUDE.md 全域規則）
 6uv venv && source .venv/bin/activate
 7uv pip install -r requirements.txt
 8
 9cp .env.example .env
10vim .env       # 至少填一個 LLM API key + 一個通知 + STOCK_LIST
11
12python main.py

2.3 方案 C — Docker

 1docker pull zhulinsen/daily_stock_analysis:latest
 2# 或自己 build
 3git clone https://github.com/ZhuLinsen/daily_stock_analysis
 4cd daily_stock_analysis
 5docker build -f docker/Dockerfile -t dsa .
 6
 7# 跑：mount .env + 持久化 logs
 8docker run -d --name dsa \
 9  -v $(pwd)/.env:/app/.env \
10  -v $(pwd)/data:/app/data \
11  -v $(pwd)/logs:/app/logs \
12  zhulinsen/daily_stock_analysis:latest

2.4 方案 D — 桌面 app

到 releases 頁 下載對應 OS 的桌面版（macOS / Windows / Linux），由 apps/dsa-desktop/ 打包。

2.5 安裝流程圖

flowchart TD
    A[使用者] --> B{選哪種方案?}
    B -->|免費,推薦| C[Fork GitHub repo]
    B -->|本地 Python| D[git clone + uv venv + pip install]
    B -->|Docker| E[docker pull / build]
    B -->|桌面 GUI| F[下載 release 安裝包]
    C --> G[Secrets: AI key + 通知 + STOCK_LIST]
    D --> H[.env 填配置]
    E --> H
    F --> I[GUI 內配置]
    G --> J[Actions 啟用 + Run workflow]
    H --> K[python main.py / main.py --schedule]
    I --> K
    J --> L[每日 18:00 自動執行 → 推送]
    K --> L

2.6 配置 LLM（從 .env.example 36KB 抽 critical）

1# 至少配一個：
2ANSPIRE_API_KEYS=sk-...        # 推薦，含免費額度
3AIHUBMIX_KEY=sk-...            # 推薦，10% 優惠
4GEMINI_API_KEY=...             # Google
5ANTHROPIC_API_KEY=sk-ant-...   # Claude
6OPENAI_API_KEY=sk-...
7OPENAI_BASE_URL=https://...    # 兼容 API
8OLLAMA_API_BASE=http://localhost:11434  # 本地

2.7 常見安裝問題

3. 核心架構解析

3.1 整體架構

flowchart TB
    subgraph Inputs["輸入層"]
        S[STOCK_LIST]
        T[排程觸發
cron / 手動 / API]
    end

    subgraph DataLayer["資料層 (data_provider/)"]
        D1[efinance P0] --> D2[AkShare P1] --> D3[Tushare P2] --> D4[Pytdx/Baostock/yfinance/Longbridge fallback]
    end

    subgraph SearchLayer["搜尋層 (src/search_service.py)"]
        N1[Anspire AI Search] --> N2[SerpAPI] --> N3[Tavily/Bocha/Brave/MiniMax/SearXNG]
    end

    subgraph LLMLayer["LLM 層 (src/llm/ via litellm)"]
        L1[Anspire / AIHubMix / Gemini / Claude / OpenAI / DeepSeek / 通義 / Ollama]
    end

    subgraph Analysis["分析核心 (src/core/, src/agent/)"]
        A1[stock_analyzer]
        A2[market_analyzer]
        A3[15 種策略 agent
均線/缠論/波浪/趨勢/熱點/事件/成長/預期]
    end

    subgraph Outputs["輸出層"]
        O1[決策儀表盤
Markdown + PNG]
        O2[(SQLite DB)]
    end

    subgraph NotifyLayer["通知層 (src/notification_sender/)"]
        Z[wechat / feishu / telegram / discord / slack / email / pushover
ntfy / gotify / pushplus / serverchan3 / astrbot / custom_webhook]
    end

    subgraph UILayer["介面層"]
        U1[CLI main.py]
        U2[FastAPI server.py + api/]
        U3[Web 工作台 apps/dsa-web]
        U4[桌面 app apps/dsa-desktop]
        U5[Telegram/Discord Bot bot/]
    end

    Inputs --> Analysis
    DataLayer --> Analysis
    SearchLayer --> Analysis
    Analysis --> LLMLayer
    LLMLayer --> Outputs
    Outputs --> NotifyLayer
    Outputs --> UILayer

3.2 多供應商抽象設計（重點）

3.2.1 LLM 層

• 用 litellm 統一接 8+ provider
• 支援 LITELLM_MODEL、LITELLM_CONFIG（YAML）做多模型路由
• Fallback 鏈：主 model 失敗 → 自動切備用 → 最後 Ollama 本地

3.2.2 行情層（data_provider/）

按優先級順序試：

1. efinance (P0) — 東方財富，免費快
2. AkShare (P1) — 東方財富爬蟲，覆蓋廣
3. Tushare (P2) — Pro API，需 token
4. Pytdx / Baostock / yfinance / Longbridge — 兜底
5. TickFlow — 新整合（v3.17 大盤增強）

3.2.3 新聞搜尋層（src/search_service.py）

按品質順序：

1. Anspire AI Search — 中文最佳
2. SerpAPI — 通用，付費
3. Tavily / Bocha / Brave / MiniMax / SearXNG — 免費 / 自建

3.3 14 通道通知模組

每個 sender 是獨立 src/notification_sender/<channel>_sender.py，pattern 統一：

1class XxxSender:
2    def __init__(self, config): ...
3    def send(self, content, **kwargs):
4        # 1. build payload
5        # 2. requests.post(api_url, json=payload, timeout=10)
6        # 3. handle response, log success/fail

14 通道清單：

• 中國：wechat（企微）、feishu（飛書）、pushplus、serverchan3
• 國際 IM：telegram、discord、slack、astrbot
• 個人通知：pushover、ntfy、gotify
• 通用：email、custom_webhook

3.4 GitHub Actions 排程流程

sequenceDiagram
    participant Cron as GitHub Actions Cron
    participant WF as 00-daily-analysis.yml (30KB)
    participant Run as main.py
    participant LLM as LLM Provider
    participant Notif as Notification Senders

    Cron->>WF: 工作日 18:00 (BJ) 觸發
    WF->>WF: 檢查交易日（A/H/US 節假日）
    alt 非交易日
        WF-->>Cron: 跳過
    else 交易日
        WF->>Run: python main.py
        Run->>Run: load STOCK_LIST + .env
        loop 每支股票
            Run->>Run: data_provider 抓行情（多源 fallback）
            Run->>Run: search_service 抓新聞（多源 fallback）
            Run->>LLM: 送 prompt → 決策報告
            LLM-->>Run: Markdown 報告
        end
        Run->>Run: 組決策儀表盤 + 大盤複盤
        Run->>Notif: 推送到所有啟用通道
        Notif-->>Run: 成功/失敗 status
        Run->>Run: 寫 DB + log
        Run-->>WF: exit 0
    end

4. CLI 詳細用法

4.1 main.py 主要旗標

 1# 一次性執行
 2python main.py
 3
 4# Debug 模式（詳細 log）
 5python main.py --debug
 6
 7# Dry-run（不真的推送）
 8python main.py --dry-run
 9
10# 指定股票（覆蓋 STOCK_LIST）
11python main.py --stocks 600519,hk00700,AAPL
12
13# 只跑大盤複盤
14python main.py --market-review
15
16# 排程模式（背景持續）
17python main.py --schedule
18
19# 只啟動 API server，不跑分析
20python main.py --serve-only

完整 22+ 旗標（看 main.py:240 開始的 argparse）：

• 股票範圍：--stocks、--include-etf
• 模式：--schedule、--serve-only、--no-run-immediately
• 行為：--debug、--dry-run、--market-review
• 資料源：--data-source efinance|akshare|tushare|...
• 通知：--notify wechat,feishu（覆蓋預設）

4.2 FastAPI server

1python server.py
2# 或
3python main.py --serve-only
4
5# 預設 http://localhost:8000
6# Swagger UI: http://localhost:8000/docs

主要 endpoints（看 api/v1/）：

• POST /v1/analysis — 觸發分析
• GET /v1/reports/<id> — 取歷史報告
• GET /v1/agent/strategies — 策略列表
• POST /v1/agent/ask — Agent 問股

4.3 Web 工作台

1cd apps/dsa-web
2# 看 apps/dsa-web/README.md

4.4 Bot 模式

1cd bot
2# Telegram bot
3TELEGRAM_BOT_TOKEN=... python platforms/telegram_bot.py
4# Discord bot
5DISCORD_BOT_TOKEN=... python platforms/discord_bot.py

5. 應用場景

6. 資安掃描報告

掃描日期：2026-05-20 / 範圍：src/ + main.py + api/ + bot/ + .github/

6.1 紅黃綠燈總結

6.2 詳細發現

✅ 無 eval / exec / os.system / subprocess(shell=True) / pickle.load — 完全乾淨

✅ 主動 redact 設計（重點！）：

1# src/utils/sanitize.py:16
2sanitized = re.sub(
3    r"(?i)(token|secret|password|sendkey)([=:]\s*)[^\s,;&]+",
4    r"\1\2[REDACTED]",
5    sanitized,
6)

• 所有 log / 輸出走 sanitize()，自動消密
• src/services/system_config_service.py:2121 也有同樣 pattern — 雙重保險

✅ 無 hardcoded secret — 所有 API key 都從 config 或 os.environ 讀，無檔內寫死

✅ GitHub Actions 使用 Secrets 而非 plaintext：

1HAS_DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN != '' && 'true' || 'false' }}

• 用 secrets.* 引用，並用 != '' 判斷存在性，不會把 secret 印到 workflow log

🟡 觀察 1：大量對外 requests.post

• 14 個通知 sender 都對外 POST（這是 by design — 通知就是要送出去）
• 7 個搜尋 API 對外 GET/POST（拿新聞）
• 8 個 LLM provider 對外（送 prompt 取回 response）
• 風險評估：每個請求都包含 API key 在 header / payload；確保 .env 不要 commit 即可（.gitignore 已排除）

🟡 觀察 2：.env.example 36KB

• 內含 N 個 API key 欄位提示
• 使用者要自己保管好 .env、不要 commit
• repo 的 .gitignore 與 .dockerignore 已正確排除

✅ timeout 普遍設置：絕大多數 requests.post 都有 timeout=10 / timeout=30，無無限等待

✅ bandit 設定在 pyproject.toml：

1[tool.bandit]
2exclude_dirs = ["tests", "test_*.py"]
3skips = ["B101"]  # assert in tests OK

• 用 bandit 自動掃描，CI 內可看到

6.3 結論

🟢 整體低風險 + 多處最佳實踐。 38k stars 專案有充足社群審查；開發者主動寫 sanitize / 用 secrets / 設 timeout / 跑 bandit，遠優於一般個人開源專案。

使用者責任：(1) 保管好 .env；(2) 用 GitHub Secrets 而非 env file 在 Actions；(3) LLM 輸出當作 advisory 而非交易訊號。

7. FAQ

Q1: 真的免費嗎？ A: GitHub Actions 部分免費（公開 repo 無限分鐘、私有 repo 每月 2000 分鐘）。LLM API 看用哪家 — Anspire / AIHubMix 有免費額度，Gemini 有免費 tier，Ollama 本地完全免費。新聞 API 大多免費 tier 夠用（SerpAPI 25/日、Tavily 1000/月）。

Q2: 能跑台股 (TWSE)? A: README 列 A/H/US，未明確列台股。技術上若有資料源（如 yfinance 用 .TW 後綴），LLM 分析邏輯通用。需自己驗證。

Q3: LLM 會「幻覺」出錯誤股價嗎？ A: 會。本系統設計上先給 LLM 真實行情 + 新聞 context，再讓它生成分析，降低幻覺。但仍可能誤判趨勢。所有輸出僅供參考。

Q4: 怎麼確保 API key 不外洩？ A: (1) GitHub Secrets 而非 plaintext file；(2) 不要把 .env push（已在 .gitignore）；(3) sanitize.py 自動 redact log；(4) 通知時推送的是分析報告非 secret。

Q5: 為什麼會超時？ A: 多源 fallback + 多 API 重試需要時間；首次跑或市場新聞密集時可能 > 5 分鐘。--debug 看哪個 source 慢，可在 .env 關掉不需要的源。

Q6: 桌面 app 可以 Mac / Windows 同時用嗎？ A: 是。Releases 提供三 OS 包，由 apps/dsa-desktop/ 用 Tauri / Electron 類框架打包。

Q7: 我要怎麼貢獻？ A: 看 AGENTS.md（也是 CLAUDE.md）— 內含 Claude Code 規則。直接開 PR，作者很活躍會 review。

8. 進階技巧

8.1 抽通知模組到自己的專案

1# 把 14 個 sender 整包複製
2cp -r src/notification_sender /your/project/notifications
3
4# 每個 sender 是 self-contained，只依賴 requests + config
5# 改 import path、改 config 載入方式即可

最簡單的：discord_sender.py、telegram_sender.py、email_sender.py 都 < 200 行，可直接讀懂並改造。

8.2 自定 LLM prompt

看 src/llm/ 與 src/core/ 內的 prompt template，可自己改 system prompt 改變分析口吻 / 結構。

8.3 加新策略 agent

1# 看 src/agent/ 既有 15 個策略 .py 檔
2# 仿同樣 pattern 加 my_strategy.py
3# 在 __init__.py 註冊

8.4 用 Ollama 本地模型完全離線

 1# 1. 裝 Ollama
 2curl -fsSL https://ollama.com/install.sh | sh
 3ollama pull qwen3:8b
 4
 5# 2. .env
 6OLLAMA_API_BASE=http://localhost:11434
 7LITELLM_MODEL=ollama/qwen3:8b
 8LLM_CHANNELS=ollama
 9
10# 3. 跑
11python main.py

完全離線，但需自備 RAM（8B 模型約 5-8GB VRAM）。

8.5 把 sanitize 套到自己的 log

1# 抽出 src/utils/sanitize.py 直接用
2from sanitize import sanitize
3logger.info(sanitize(f"Got config: {config}"))
4# → "Got config: API_KEY=[REDACTED] ..."

8.6 取消 GitHub Actions 預設排程，改自己的

1# .github/workflows/00-daily-analysis.yml
2on:
3  workflow_dispatch:        # 只允許手動
4  # schedule:               # 註解掉自動排程
5  #   - cron: '0 10 * * 1-5'

9. 整合進其他工作流

9.1 與本知識庫其他 Layer 配合

9.2 衍生 / 後續題目

• 生醫研究每日推送：仿 DSA pattern，把「股票」換成「目標 paper / 患者 cohort 監控 / 模型結果」

• 多 LLM 服務抽象層：仿 src/llm/ 結構，給本知識庫所有需要 LLM 的 layer 用統一 client

• 不直接相關（股票 vs 生醫）

• 但可借鑑：(1) 多供應商 fallback chain；(2) GitHub Actions 排程；(3) 多通道通知 — 對「每日實驗結果推送」直接適用

10. 重點摘要 Checklist

• 38k stars 中國最熱門 LLM 股票分析，週發 release，1300+ PR 合併
• 5 種介面：CLI / API / Web / 桌面 / Bot 共用 src/core/ + src/agent/
• 多供應商抽象：LLM (8+) / 行情 (7+) / 搜尋 (7+) / 通知 (14)，都有 fallback chain
• GitHub Actions 排程：30KB workflow，含交易日檢查 / 斷點續傳
• 資安：🟢 低 + 多最佳實踐：主動 sanitize / 無 hardcoded / 用 secrets / 設 timeout / bandit CI
• License：MIT + 明顯免責聲明
• 可移植 pattern：通知 / 排程 / LLM 抽象 / sanitize
• 不適合：自動化交易、機構嚴格合規場景

11. 進一步閱讀

本教學由 gh-tutorial-qd skill 自動生成 / 2026-05-20 / commit 8be6546。 對「多供應商抽象 + GitHub Actions 排程 + 多通道通知」三個工程 pattern 感興趣的讀者請特別細讀 §3.2、§3.4、§8.1。