Horizon 完整教學

把多源新聞（Hacker News / Reddit / Twitter / RSS / GitHub / Telegram / OpenBB）一鍵變成「個人化每日中英雙語簡報」的開源 AI 雷達工具。架在自家機器、用自家的 LLM key，從此不再被資訊洪流追趕。

1. 專案定位

一句話：Horizon 是 self-hosted (自架) 版 Hacker News + The Information + 個人 Twitter list 的 AI 整合層，用 LLM (large language model；大型語言模型) 評分後輸出 Markdown 並推播到 GitHub Pages / Email / Feishu / Slack / Discord / MCP endpoint。

1.1 為什麼會出現 Horizon？

1.2 適用情境

• 個人 RA / 投資 / 研究：把 5-30 個 RSS + HN + Reddit 自動 summarize
• 公司情資：訂閱 competitor blog + Twitter list，每天推到 Slack
• 媒體編輯：multi-source dedup 找熱度上升的故事
• 學術 follow：arXiv RSS + 領域大佬 Twitter（透過 Apify）→ 每日精選

1.3 不適用情境

• 不要拿來做 paywall 內容（HN/Reddit 留言可能僅見摘要）
• 不要拿來做即時新聞 push（pipeline 設計給 daily / hourly，非秒級）
• 不要替代專業 NLP 系統（情緒分析、命名實體都靠 LLM 推理，無 fine-tune）

1.4 它不是

• ❌ 不是搜尋引擎：不主動找新東西，只處理你訂閱的 source
• ❌ 不是聊天機器人：briefing 是被動產出，不對話
• ❌ 不是抓取爬蟲：法律邊界內、走官方 API / RSS / Apify，不刷頁面

2. 安裝指南

2.1 系統需求

• Python ≥ 3.11
• uv（package manager，不可用 pip / poetry）
• Docker / Docker Compose（推薦部署方式）
• 至少 1 個 LLM API key（推薦 DeepSeek 或 Ollama，便宜或免費）
• （選）Apify token 給 Twitter scraping
• （選）GitHub PAT 給高頻率 GitHub source

2.2 三條安裝路徑

A. 一鍵 Docker（推薦）

1git clone https://github.com/Thysrael/Horizon.git
2cd Horizon
3cp .env.example .env
4# 編輯 .env 填入至少一個 API key
5# 編輯 data/config.json 設 sources / outputs
6docker compose run --rm horizon --hours 24

B. uv 本機跑

1git clone https://github.com/Thysrael/Horizon.git
2cd Horizon
3uv sync                           # 不可用 pip install -r
4cp .env.example .env
5uv run horizon-wizard             # 互動式建立 config
6uv run horizon --hours 24

C. GitHub Action（每日自動跑，輸出到 GitHub Pages）

fork repo → Settings → Secrets 加 ANTHROPIC_API_KEY（或其他）→ 啟用 Action deploy-docs.yml。每天 cron 觸發 → action 跑 horizon → push 到 gh-pages branch → 自動發佈到 https://<your-username>.github.io/Horizon/。

2.3 安裝流程圖

flowchart TD
    A[使用者] --> B{怎麼跑?}
    B -->|本機試試| C[git clone + uv sync]
    B -->|生產部署| D[docker compose]
    B -->|自動推 GitHub Pages| E[fork + Action]
    C --> F[uv run horizon-wizard]
    F --> G[編輯 data/config.json]
    D --> H[編輯 .env + data/config.json]
    E --> I[Settings/Secrets 設 API key]
    G --> J[uv run horizon --hours 24]
    H --> K[docker compose run --rm horizon]
    I --> L[每日 cron 自動產 briefing]
    J --> M[輸出 Markdown / 推播]
    K --> M
    L --> M

2.4 推薦的 LLM 選擇（成本對照）

3. 核心架構解析

3.1 6 個 pipeline 階段

flowchart LR
    A[Sources] -->|httpx| B[Fetch]
    B --> C[Deduplicate]
    C -->|LLM 0-10 score| D[Score & Filter]
    D -->|web search| E[Enrich]
    E -->|LLM| F[Summarize]
    F --> G[GitHub Pages]
    F --> H[Email]
    F --> I[Webhook]
    F --> J[MCP server]
    K[data/config.json] -.設定.-> B
    K -.threshold.-> D
    K -.model 選擇.-> F
    L[SQLite data/horizon.db] -.state.-> C

3.2 五大模組

3.3 一份 config 走完所有設定

data/config.json 一張表設定：

3.4 Setup wizard 簡化第一次設定

1uv run horizon-wizard
2# → 問你: 興趣領域? 語言? 想看 HN? Reddit? 推薦的 RSS?
3# → 自動產 data/config.json（可手動再改）

4. CLI 與工具腳本詳細用法

4.1 4 個 CLI 入口

4.2 常用 flag

 1# 抓最近 24 小時內容
 2uv run horizon --hours 24
 3
 4# 抓最近 7 天（週報）
 5uv run horizon --hours 168
 6
 7# 跳過 enrichment（省 LLM 成本）
 8uv run horizon --skip-enrich
 9
10# 只跑單一 source（除錯用）
11uv run horizon --only hn
12
13# 模擬模式（不真的呼叫 LLM、不真的推 webhook）
14uv run horizon --dry-run

4.3 環境變數對照表（.env.example）

4.4 daily-run.sh

scripts/daily-run.sh 是給 GitHub Action / cron 用的入口，內部 sequence：

11. uv run horizon --hours 24                  # 跑 pipeline
22. mv data/briefing-*.md docs/_posts/         # 移到 Jekyll posts 目錄
33. git add . && git commit -m "daily: ..."    # commit
44. git push                                   # 觸發 gh-pages 重 build

5. 應用場景

6. 資安掃描報告

工具：手動 grep eval/exec/subprocess/pickle/secret/api_key/token over src/ + scripts/ + .env.example 對照。

6.1 結果總表

6.2 詳細說明

🟢 API key 環境變數

src/main.py:97-130、src/models.py:62-305 顯示所有 API key 都用 api_key_env: str（環境變數名稱字串）做配置，實際 key 由 os.environ.get(...) 讀。.env.example 不含真實 key。✅

🟢 無 dangerous 函式

grep -rn -E "eval\(|exec\(|os\.system|shell=True|pickle\.loads|__import__" 結果只在註解 / 字串中出現，無實際呼叫。✅

🟡 Twitter scraping 走 Apify

src/scrapers/twitter.py:77/91/111/145 用：

1url = f"{_APIFY_BASE}/acts/{self.config.actor_id}/runs?token={token}"

風險：

1. token 在 URL query string，被 reverse proxy log / WAF rule 抓到的機率高於 header auth
2. Apify 是雲端服務，你監看的 Twitter user list 會被 Apify 看到

緩解：

• 不想用 Apify 就把 config 內 twitter source 關掉
• 想用就接受「Twitter scraping 必然走第三方」這個事實

🟢 data/config.json 已 gitignore

issue #71 / #72 已修：data/config.json 加進 .gitignore，避免使用者個人化設定被 git pull 覆蓋或被誤 commit。

🟢 LLM 內容傳送

任何 source 抓回來的內容會送給 LLM 評分 / 總結。與你用 ChatGPT 貼新聞讓它總結是同等的隱私風險。要 air-gap 用 Ollama 即可（localhost LLM）。

6.3 部署建議

7. FAQ

Q1. 為什麼一定要 uv？不能用 pip 嗎？

A: pyproject.toml 與 uv.lock 強綁定 uv（hatchling build backend）。pip 仍可裝但會跳過 lockfile，依賴版本不確定。維持 uv 一致。

Q2. 一定要 Docker 嗎？

A: 不必，但 Docker 處理掉 Python 環境、cron 時區、volume mount 三件事。本機 uv run horizon 一樣可跑。

Q3. 我沒有 GitHub Pages 怎麼用？

A: 把 outputs.pages 關掉，留 outputs.markdown（寫本地檔）+ outputs.webhook（推 Feishu/Slack）。

Q4. Twitter 一定要花錢嗎？

A: Apify 是付費（有 free tier $5 額度可用一陣）。完全不想花錢就把 twitter source 關掉，Telegram + Reddit + RSS 已涵蓋 80% 內容。

Q5. 中文評分品質如何？

A: DeepSeek / Doubao / Qwen 中文都不錯；Claude / GPT 中英都好但貴。建議先用 DeepSeek 試一週再決定要不要升級。

Q6. 跟 Feedly / Inoreader 比有什麼差別？

A: Feedly 只給你 raw RSS feed；Horizon 多了 dedup + LLM 評分 + 補背景 + 雙語輸出 + 自架 webhook，是「reader」前的 pipeline。

Q7. 為什麼會有 OpenClaw badge？

A: Horizon 跟 OpenClaw（AI agent SDK）有整合可能；目前 issue #74 提到 MyClaw.ai partnership inquiry。

Q8. 跑壞了怎麼除錯？

A: 加 --dry-run 看流程；加 --only hn 限制 source；用 --skip-enrich 跳過 LLM enrich（最大宗 cost & error 來源）。

8. 進階技巧

8.1 雙模式 cron（issue #75 預告）

未來 v0.2 預計支援：

• 高頻 cron（每小時）：只跑 fetch + dedup，存 SQLite
• 低頻 cron（每天 8AM）：跑 score + enrich + summarize + deliver

目前可手動拆：horizon --skip-enrich --skip-summary 跑 fetch only。

8.2 自訂 LLM provider

src/ai/ 提供 base class，要加新 provider（例如 Cohere、xAI）只需 ~50 行 subclass。

8.3 自訂 source scraper

src/scrapers/ 8 個適配是 reference impl。要加新 source（例如 Lobsters、Mastodon）照 rss.py pattern 寫 ~100 行 async class，註冊到 orchestrator。

8.4 整合進 Claude Desktop / Cursor

 1# Claude Desktop config (~/.config/claude_desktop_config.json)
 2{
 3  "mcpServers": {
 4    "horizon": {
 5      "command": "uv",
 6      "args": ["run", "horizon-mcp"],
 7      "cwd": "/path/to/Horizon"
 8    }
 9  }
10}

Claude 就能 @horizon 拉今日 briefing 進對話。

8.5 Email newsletter 訂閱

uv run horizon-webhook 啟 SMTP/IMAP 服務：

• 訂閱者寄 subscribe@your-domain → 自動加進名單
• 每日 briefing 自動寄出（HTML + 退訂連結）
• 退訂寄 unsubscribe@your-domain → 自動移除

8.6 多語言 briefing 雙簡報

config.json 設 languages: ["en", "zh"] → 跑一次 pipeline 出兩份輸出，省一份 fetch cost。

8.7 跟本 AI-knowledge_template 整合

9. 整合進其他工作流

10. 重點摘要 Checklist

• Horizon 是 self-hosted 多 source AI 新聞雷達，輸出英中雙語 daily briefing
• 安裝必用 uv（不可 pip）
• 至少設 1 個 LLM API key（推薦 DeepSeek 便宜、Ollama 免費）
• config 全寫在 data/config.json 一個檔
• horizon-wizard 幫你互動式建 config
• 8 個 source scraper（HN / Reddit / RSS / Telegram / Twitter / GitHub / OSSInsight / OpenBB）
• 5 種 output（Markdown / GitHub Pages / Email / Webhook / MCP）
• 資安：🟢 低風險、API key 走 env，但 Twitter 走 Apify 雲端（🟡 中度資料外流）
• MIT license，企業內可商用
• 無 release tag，main 滾動更新

11. 進一步閱讀

• 官方 Live Demo: https://thysrael.github.io/Horizon/
• Configuration Guide: https://thysrael.github.io/Horizon/configuration
• Hub design doc（社群 source hub）: docs/horizon-hub-design.md
• Scoring 細節: docs/scoring.md
• Scrapers 細節: docs/scrapers.md
• 簡中 README: README_zh.md
• 議題追蹤: https://github.com/Thysrael/Horizon/issues
• HelloGitHub 收錄頁: https://hellogithub.com/repository/Thysrael/Horizon