Note: This project is specifically designed for the Taiwan Stock Market. As the target audience is primarily Taiwanese, all documentation and code comments are written in Traditional Chinese.
本專案採用 "Vibe Coding" 模式開發，核心架構與程式碼由 Google Gemini 3 Pro 生成。
tw-stocker-consultant 是一個專為 AI Agent 設計的投資決策支援技能 (Skill)。它整合了 技術分析、籌碼追蹤 與 新聞情緒解讀，讓 AI 能夠像專業投顧一樣為您提供建議。
本專案採用 雲端原生 (Cloud-Native) 架構，直接對接 GitHub Raw Data，無需維護本地資料庫。
✅ 支援多平台 Agent: 雖然本文件以 Gemini CLI 為範例，但本 Skill 亦可適配於其他支援 Tool/Skill 的 AI 環境 (如 MCP-compatible agents, Claude Desktop 等)，僅需調整安裝指令。
- 全方位個股健檢: "幫我分析 2330"，一鍵生成圖文並茂的深度報告。
- 市場雷達: "最近半導體表現如何？"，熱力圖呈現資金流向。
- 策略選股: "篩選外資大買的股票"，自動過濾潛力標的。
- 即時報價 (v1.1): "查詢 2330 現價"，提供純淨 JSON 輸出供外部串接。
- Python 3.10+
- AI Agent Runtime (本範例使用 Gemini CLI)
⚠️ Gemini CLI 設定: 請輸入/settings，開啟 "Enable Agent Skills (experimental)"。
建立一個乾淨的目錄來存放您的報告與設定：
mkdir my-stocker-lab
cd my-stocker-lab透過 Agent 指令安裝 (以 Gemini CLI 為例，務必加上 --scope workspace)：
gemini skills install https://github.com/joyeli/tw-stocker-consultant --scope workspace安裝完成後，請使用以下指令啟動 Gemini CLI，以獲得最佳體驗：
gemini -y -m gemini-3-pro-preview參數說明:
-y(YOLO Mode): 自動核准工具執行。由於 Agent 需要頻繁執行初始化、寫入報告與二次編修，開啟此模式可大幅提升流暢度。
- 安心聲明: 本 Skill 嚴格遵守環境隔離原則，所有操作僅限於您的工作目錄 (
my-stocker-lab) 與虛擬環境，絕不會觸碰系統其他檔案。⚠️ 關於手動模式: 若您選擇不開啟-y，在報告生成階段，Agent 會請求權限以進行「二次改寫」與「補充點評」。此時請務必點選 同意 (Approve)，否則報告將會中斷，您將失去最具價值的 AI 分析觀點。-m gemini-3-pro-preview: 指定使用最新的 Gemini 3 Pro 模型。由於 Skill 功能仍處於實驗階段，建議使用最新模型以確保指令理解與邏輯推演的準確性。
啟動後，直接與 Agent 對話即可：
- 初始化環境: 第一次使用時，Agent 會偵測環境並提示您：「需要初始化環境，是否執行？」。請讓它自動完成設定。
- 下達指令:
- 🗣️ "幫我健檢 2330 台積電。"
- 🗣️ "最近航運股表現如何？"
📖 新手必讀: 想了解詳細的對話範例與報告解讀方式，請參閱 使用者指南 (User Guide)。
若要取得最新功能或修正，您有兩種方式：
-
透過 Agent 更新： 直接對 Agent 說：「幫我更新 Skill」。Agent 會自動執行更新腳本。
-
手動更新： 在終端機執行以下指令：
python scripts/cli.py update
💡 檢查目前版本： 想確認是否更新成功？您可以直接問 Agent：「現在 Skill 是什麼版本？」
若需移除：
gemini skills uninstall tw-stocker-consultant如果您是開發者，或是希望手動執行 Python 腳本進行除錯，請參考以下資訊。
若 Agent 自動初始化失敗，您可以手動執行：
# 互動式安裝 (可選 venv 或 global 模式)
python scripts/cli.py init建議透過 cli.py 統一介面執行，系統會自動處理環境路徑：
# 1. 個股分析
python scripts/cli.py analyze 2330
# 2. 策略選股 (法人買超前10名)
python scripts/cli.py screen --strategy chips --top 10
# 3. 市場雷達 (半導體族群)
python scripts/cli.py radar --group semicon
# 4. 即時報價 (支援 JSON)
python scripts/cli.py quote 2330 2603 --json詳細參數手冊：請參閱
assets/docs/DEVELOPER_GUIDE.md。
- 使用者指南 (User Guide): 從零開始的圖文教學。
- 開發者手冊 (Developer Guide): 系統架構與參數詳解。
- SOP 與決策邏輯: (Agent 專用) 了解 AI 的思考模式。
本系統支援高度客製化。設定檔採「優先覆寫」機制：
- 預設設定:
assets/config/user_config.json - 使用者設定: 工作目錄下的
user_config.json(若存在則優先讀取)
如何修改？
直接告訴 Agent 即可，例如："我買進了 2330 和 0050" (Agent 會自動更新 user_config.json)。
分析報告與圖表將產生於工作目錄下的 stocker_outputs/：
stocker_outputs/
├── 2026-01-22/ <-- 每日戰情室
├── 2330_台積電/ <-- 個股專區
│ ├── README.md (完整圖文分析報告)
│ ├── strategy_card.png (決策戰略卡)
│ ├── ...
└── 00_Market_Radar/ (市場雷達圖)
本系統僅供數據分析與學術研究使用，不構成任何投資建議。程式產出之評分、建議與回測結果僅供參考，使用者應自行判斷投資風險並承擔盈虧。
本專案的核心數據來自以下開源專案 (GitHub Raw)：
- tw_stocker: https://github.com/voidful/tw_stocker
- tw_news_stocker: https://github.com/voidful/tw_news_stocker
- tw-institutional-stocker: https://github.com/voidful/tw-institutional-stocker