Q-Silicon Institutional Research AI Agent

以 Python 串起 CrewAI、LiteLLM 與可選 LangGraph，並行產出 加密 與 AI／美股 研究；經 Pydantic 與 validate_report 後輸出 Telegram HTML。客觀數字來自工具與 API 注入，而非模型臆測。可選 BigQuery、Streamlit、FastAPI 與 React PWA。授權與本 repo 根目錄 LICENSE 一致（MIT）。

連結	用途
授權	LICENSE（MIT）·CONTRIBUTING.md · CODE_OF_CONDUCT.md
待辦	TODOS.md
Terminal 總表（中段 M1–M5 + Portal 長線 + 架構看法）	docs/architecture/Terminal_Master_Plan.md
Architecture 狀態索引（已落地／repo-side scaffold／研究稿）	docs/architecture/Terminal_Master_Plan.md#0-architecture-文件狀態矩陣
Portal PWA 驗收清單（§驗收）	docs/architecture/TERMINAL_FRONTEND_PLAN.md
Portal ship checklist（API／PWA／staging signoff）	docs/PORTAL_SHIP_CHECKLIST.md
視覺化狀態／剩餘 staging backlog（§3 勾選表）	docs/architecture/visualization_plan.md
變更紀錄	CHANGELOG.md
Tech pulse（可選，併入日報 exclusion）	docs/ADR_TECH_PULSE_INTEGRATION.md · ENV_TEMPLATE.txt TECH_PULSE_*
Staging 時事 roundtable smoke	docs/STAGING_CURRENT_AFFAIRS_SMOKE.md
營運隊列 18–21 自檢（Redis／VAPID／可選 BQ）	scripts/verify_ops_queue_18_21.py · docs/OPS_QUEUE_18_21_RUNBOOK.md
Reviewer production rollout（Queue 35）	docs/REVIEWER_PRODUCTION_ROLLOUT.md
執行路線圖	docs/REPO_CONTINUATION_EXECUTION.md
開發導覽	CLAUDE.md · AGENTS.md
環境變數	ENV_TEMPLATE.txt → 複製為 .env
日報版面	docs/DAILY_BRIEF_V2.md
日報模組化（路線圖，計畫文件）	modularization_plan.md

本 README 對齊 repo 現況（持續更新；重大變更見 CHANGELOG.md）。 細節與紅線亦見 .cursorrules。

Portal 架構 Phase 2 產品切片（2026-05-14）

與 docs/architecture/Terminal_Master_Plan.md §0 Phase 2 對齊（註：此處指架構治理下的 Portal 切片，非下方 12 週 Roadmap 段落裡的「Phase 2」紙上管線里程碑）：PWA Command Bar 顯示 Crew 執行狀態（輪詢 GET /api/run-crew/status，data-testid="terminal-crew-status-hud"）；Shared Monitor 內 Workspace 支援 同源多分頁 以 localStorage 的 storage 事件與自訂事件 qsi_workspace_changed 同步 layout／panels／高度權重（data-verification-ui/src/constants/workspaceSync.js）。Portal ship readiness 另補 execution-intents、symbols、run-crew router 拆分與 docs/PORTAL_SHIP_CHECKLIST.md；18–21／35 仍須 staging operator 完成雲端 signoff 後才可關帳。Playwright：command-bar-route.spec.js（含 HUD）、workspace-cross-tab.spec.js。變更摘要見 CHANGELOG.md 2026-05-14「PWA — Portal Phase 2」。

Portal 切片 — Crypto on-chain + 翻譯短評（隊列 45 · P5-mock / P4 · 2026-05-16）

P5-mock：/dashboard 在 compute-memory 下方新增 OnchainMetricsPanel.jsx 三區：BTC 估值（MVRV-Z／Realized／Spot/Realized）、交易所淨流入（CEX／Binance／Coinbase）、永續資費（BTC／ETH）。資料源 = 本機 fixture data/onchain_metrics_mock.json；後端 GET /api/macro/onchain 與 P2-mock 同模式（fixture-missing → enabled: false；live 需 fixture + ONCHAIN_LIVE=1 雙條件）。

P4：api_routers/news.py _normalize_item 增 commentary_zh／commentary_en 兩欄 passthrough（零 LLM 呼叫；zh 預設 fallback 既有 gemini_take，en 無 fallback）。ColumnsHome.jsx Deep Brief Panel 顯示中／EN toggle（兩段皆存在時才出現），保留 source URL + published_at 並標「短評為翻譯／轉述；非原文」。

Portal 切片 — 算力／記憶體 dashboard（隊列 45 · P2-mock · 2026-05-16）

/dashboard macro indicators 下方新增 ComputeMemoryPanel.jsx 三區並列：HBM/DRAM 現貨、Hyperscaler Capex、GPU 現貨（hourly）。資料源 = 本機 fixture data/compute_memory_mock.json（範本，數值預設 null + TEMPLATE 註記，避免假數字進產線）。後端：api_routers/macro.py 之 GET /api/macro/compute-memory，fixture 缺／JSON 無效時回 enabled: false；live flag 需 fixture + COMPUTE_MEMORY_LIVE=1 雙條件 才會 true（P2-live 入接 TrendForce／CoreWeave／hyperscaler capex 前需先過 governance 表）。E2E：dashboard-compute-memory.spec.js。

Portal 切片 — Portfolio TP/SL 計算機（隊列 45 · P1 · 2026-05-16）

/portfolio 頁面 KPI 卡下方新增 PortfolioRiskPanel.jsx：輸入 帳戶總值 × 每筆風險 %（持久化於 localStorage["qsi_risk_budget_v1"]，預設 1%）+ entry／stop／target → 即時輸出 R:R、% 至 stop／target、建議股數（floor(預算 ÷ 每股風險)）、名目部位與實際風險 $。輸入 symbol 後可一鍵套用 ATR14 stop（純前端計算，重用 useAnalysisBundle 之 snapshot.price_series）或「帶入最後收盤」。算完一鍵 送入紙上 PENDING_REVIEW（重用 useCreateExecutionIntent → POST /api/execution-intents），後端零變更、不下單。E2E：portfolio-tpsl.spec.js。

Portal 切片 — 財報 insight 專屬頁（隊列 45 · P3 · 2026-05-16）

新增 /insights?tab=earnings：未來 N 天大型科技與 AI 供應鏈財報行事曆 + per-symbol DeepFilingAnalysis scaffold panel。後端：api_routers/earnings.py — GET /api/earnings/upcoming?days=14（重用 MEGA_CAP_TECH_EARNINGS_TICKERS + yfinance 行事曆，1 小時 in-process 快取，pillar 由手工 mapping）、GET /api/earnings/{symbol}/insight（讀 DEEP_FILING_ANALYSIS_FILE，無資料時明確 enabled: false，不偽造數字）。前端：EarningsInsightHome.jsx + 三條 44c 融合 CTA（深度頁／新聞 focus／專欄 focus）。本機試用：cp data/deep_filing_analysis.example.jsonl data/deep_filing_analysis.jsonl（範本為 TEMPLATE 內容；填寫流程與 schema 約束見 docs/EARNINGS_INSIGHT_SCAFFOLD.md）。詳見 CHANGELOG.md 2026-05-16 ### Portal / API（隊列 45 · P3） 與計畫檔 plans/finance-terminal-repo-1-cheeky-pike.md。

Portal 架構 Phase 4 IA（讀者層 × 工作台層，2026-05-16）

與 Terminal_Master_Plan.md §0 Phase 4 對齊：新聞／專欄與觀點／儀表／組合同一 Portal、不同密度。Gate 0 預設集中於 portalPhase4.js（主戰場 /insights + /portfolio、宏觀 /dashboard、讀者首屏避高密度表、N=3、terminalToneKeep 五項）。44a／44b／44d 已落（讀者／工作台導引條、Command Bar placeholder 分路）；44c 融合層雙向 CTA（2026-05-16 續） — PORTAL_PHASE4_CTA 文案表 + newsContextHref／columnsContextHref／ctaWithSymbol，fusionDirection=bidirectional；InsightsHome 反向 CTA、SymbolDeepDive ?focus={SYM} 雙向 CTA、NewsHome／ColumnsHome 接 ?focus= 過濾並顯示 focus badge。Playwright：phase4-ia-portal.spec.js。詳見 CHANGELOG.md 2026-05-16「PWA（隊列 44 · 44c）」與 TODOS.md 「隊列 44」。

日報模組化（計畫文件 + 已落地切片）

多 profile（full／lite／crypto-only）、templates/blocks/ macro、brief_profiles／BLOCK_REGISTRY、profile-aware validate_report，以及 Phase 4c（BQ profile）／Phase 5（【時事多觀點】）之短／中／長期切分，見 docs/architecture/modularization_plan.md。已交付：Phase 1（2026-04-26，templates/blocks/ + smoke byte 對齊）、Phase 2–3（2026-04-27，REPORT_PROFILE、templates/profiles/、main.py 傳 profile、Gate profile=）、Phase 4a（2026-04-27，telegram_crypto_only、REPORT_PROFILE=crypto-only）、Phase 4b（2026-04-27，config/brief_layouts/、BRIEF_LAYOUT_FILE、brief_profiles_layout、profile_block_ids merge）、Phase 4c（2026-04-16，bigquery_writer.py llm_run_log／gate_failure_log 寫入 profile，見 docs/SQL/bq_brief_profile_columns.sql）、Phase 4d（2026-04-14，modularization_plan.md#phase-4d — profile 一致性錨點、啟動 REPORT_PROFILE 檢、YAML／BQ 文件對齊）；預設 full 與凍結基線 byte-identical — 見 ／／／。：〔時事多觀點〕schema／macro／可選 Gate／／ 並行掛載； 可選 YAML 驅動 重排（預設關閉＝）— 見 、。啟用仍須遵守 與 （見上表「日報版面」）。

個人化投資決策夥伴 Roadmap（規劃）

下一階段產品方向是從「通用研報 tool」推進到「個人化投資決策夥伴」，但會沿用既有信任邊界：execution_intents／paper_execution 做 paper-tracked 訊號生命週期，report_quality_agent 與 validate_report 做品質與 Gate 依據，PWA War Room / Terminal 承接可審核操作面。12 週 roadmap 的主線為：paper P&L → quality-adjusted scoring → portfolio alignment → scenario / target optimizer → beta / launch。

v1 僅追蹤 paper-tracked 訊號，不接券商、不自動下單，也不保證任何投資績效；公開績效或月度信函必須使用可回放、可審計的 paper 記錄，且不得弱化無數據幻覺、Telegram HTML 白名單或 validate_report 契約。Phase 2 已補 /api/paper/lifecycle、/api/paper/pnl、manual POST /api/execution-intents、quality-adjusted scoring、internal transparency letter、/insights 紙上生命週期 tab、paper-derived quant backtest、Columns sector rotation 與 local-first workspace import/export/digest；後續隊列見 TODOS.md 28：12 週投資價值優化 Roadmap。

---

設計紅線

1. 無數據幻覺：價格、指標、宏觀數字須由 Python 工具／API 取得並寫入 context；LLM 不得捏造。
2. X／Twitter：日報主線 不依賴 X 搜尋。
3. Telegram HTML：僅 <b> <i> <u> <s> <code> <blockquote> <a>；區塊順序：儀表板 → 核心新聞 → 呢喃 → 精準操作（見 DAILY_BRIEF_V2）。

---

我想做什麼？

目標	指令或步驟	需要金鑰？
戰情室 UI	streamlit run dashboard.py --server.port 8501 --server.headless true — 可選 DASHBOARD_AUTO_REFRESH_SEC（秒，預設 300）；頂層 st.tabs：Overview、Profile / LLM、Gate（7 日）、Roundtable（細節見 CHANGELOG.md 2026-04-18 ### Added）	否（BQ 區塊降級）
PWA 版型	cd data-verification-ui && npm install && VITE_GLASSBOX_MOCK=1 npm run dev	否
PWA Terminal（代號快照／K 線）	同上；開啟 /insights（/briefs、/terminal 會相容導向此頁；5 板塊 Phase 0 見 CHANGELOG.md 2026-05-13）。接實盤 API 時設 VITE_API_URL（例：VITE_API_URL=http://127.0.0.1:8000 npm run dev）；可選 VITE_QSILICON_KEY → X-Q-Silicon-Key（見 ENV_TEMPLATE.txt）	否（mock）；是（讀 BQ 需本機 uvicorn + GCP）
PWA E2E（Playwright）	cd data-verification-ui && npm run test:e2e（內建 mock API + VITE_E2E=1 建置；Bloomberg §6 Dashboard vs /insights BTC 價；另含 Command Bar Crew HUD、Workspace 跨分頁、Phase 4 IA phase4-ia-portal.spec.js 等 spec）	否（需下載 Chromium）
對齊 CI	ruff check . · python3 -m pytest -m smoke -q · ./scripts/ci_terminal_contract_check.sh（quote／OHLC 契約 + PWA build；GitHub Actions 對 data-verification-ui/package.json 啟用 npm cache）	否（PWA build 需 Node）
乾跑管線	SKIP_TELEGRAM=1 SKIP_BIGQUERY=1 python main.py	是（啟動四項 LLM／資料 key，見下）

啟動必填（缺一則 RuntimeError）：XAI_API_KEY、OPENAI_API_KEY、GEMINI_API_KEY、APIFY_API_TOKEN。

常見狀況：main.py 單次 15–30+ 分鐘屬正常；Gate 擋報看終端 issues，可開 GATE_FAILURE_ARTIFACTS=1；CoinGlass 401／Upgrade plan 多為方案不含端點（見 CoinGlass）。

Terminal / Streamlit 口徑提醒：/insights（以及相容導向的 /briefs、/terminal）與 Streamlit Symbol 快照都以 symbol_snapshot_service.py 為 payload 真相來源；若設 SYMBOL_SNAPSHOT_HTTP_BASE，Streamlit 會改打同一條 FastAPI snapshot 路徑。latest_metrics（BigQuery）與 quote（yfinance）不是同一來源，畫面需以 data_provenance / price_alignment 為準。

---

快速開始

pip install -r requirements.txt
cp ENV_TEMPLATE.txt .env   # 編輯填入金鑰
python main.py

情境	環境變數或指令
乾跑	SKIP_TELEGRAM=1 SKIP_BIGQUERY=1 python main.py
除錯	LOG_LEVEL=DEBUG CREW_VERBOSE=1 python main.py
雙軌比對	REPORT_COMPARE_MODE=1 python main.py → docs/REPORT_COMPARE_STAGING.md

日報品質代理（可選）

在 .env（由 ENV_TEMPLATE.txt 複製）手動加入：

• REPORT_QUALITY_AGENT=1 — validate_report 通過後跑 report_quality_agent.py（不取代 Gate）。
• OPENAI_API_KEY — 已為管線必填；品質代理的 LLM rubric 與 REPORT_LLM_JUDGE_MODEL 相同，程式預設 openai/gpt-4o-mini（若要明確寫死可設 REPORT_LLM_JUDGE_MODEL=openai/gpt-4o-mini）。
• 其餘門檻／git push 行為見 ENV_TEMPLATE.txt 註解（勿隨意開 REPORT_QUALITY_AGENT_GIT_PUSH）。

載入 .env 後執行：set -a && source .env && set +a && python main.py。詳見 TODOS.md 與 CHANGELOG。

Python：Dockerfile 為 3.11-slim；本機 3.12 通常可。專案為根目錄扁平腳本，無 pyproject.toml。

---

架構概覽

main.py 以 雙 ThreadPoolExecutor 並行 Crypto／AI，每軌可選 CrewAI 或 LangGraph，最後共用 assemble → render → validate。

flowchart TB
  subgraph boot [啟動]
    K[必填金鑰]
    S[可選 PIPELINE_STRICT_ENV]
    T[數值 env 校驗]
    P[工具 prewarm]
  end
  subgraph dual [並行兩軌]
    C1[CryptoResearchCrew]
    A1[AIResearchCrew]
    C2[LangGraph Crypto]
    A2[LangGraph AI]
  end
  subgraph tail [後段共用]
    Asm[assemble + HTML]
    V[validate_report]
    O[Telegram · BQ]
  end
  K --> S --> T --> P
  P --> C1
  P --> A1
  P -.->|USE_LANGGRAPH_ENGINE=1| C2
  P -.->|USE_LANGGRAPH_ENGINE=1| A2
  C1 --> Asm
  A1 --> Asm
  C2 --> Asm
  A2 --> Asm
  Asm --> V --> O

---

LangGraph（可選）

目錄 graph/：graph_state.py（含 merge_raw_data reducer）、graph_nodes.py、graph_crew.py、graph_tools.py。

節點／檔案	說明
data_gatherer	寫入 raw_data（受 GRAPH_ENABLE_TOOL_CALLS 控制）
bull_agent / bear_agent	GRAPH_LLM_DEBATE=1 時走即時 LLM；否則規則式
arbiter	決定 needs_deep_dive / deep_dive_query
deep_research	預設決定性補抓；GRAPH_DEEP_RESEARCH_TOOL_LLM=1 時 bind_tools(RESEARCH_TOOLS) 多輪真實呼叫（需金鑰）
final_formatter	預設交回 CryptoResearchCrew／AIResearchCrew；LANGGRAPH_SKIP_FORMATTER_CREW=1 僅 smoke

graph_tools.py：以 LangChain StructuredTool 包裝 coinglass_data_tool、financial_datasets_tool、newsapi_tool → RESEARCH_TOOLS。

變數	預設	用途
USE_LANGGRAPH_ENGINE	0	1 啟用 LangGraph 雙軌
GRAPH_ENABLE_TOOL_CALLS	1	0 關閉 gatherer／deep 內工具 HTTP
GRAPH_LLM_DEBATE	0	1 Bull／Bear／Arbiter 用 ChatOpenAI
GRAPH_DEEP_RESEARCH_TOOL_LLM	0	1 深度查證用 bind_tools 閉環
LANGGRAPH_SKIP_FORMATTER_CREW	0	1 測試用，不跑完整 Crew

完整列表見 ENV_TEMPLATE.txt。

---

核心檔案

路徑	角色
main.py	啟動、prewarm、雙軌、重試、Telegram、BQ
crew.py	CrewAI agents／tasks、fallback 鏈
graph/	可選狀態機與工具橋接
tools/ · tools_legacy.py	市場／新聞／鏈上工具；MOCK_APIS 見 ADR
schemas.py	DailyBriefReport、QSREC、結構化驗證
report_render.py · templates/telegram_report.j2 · templates/profiles/ · brief_profiles.py · brief_profiles_layout.py ·

---

模型與 Agent 槽位

詳見 config.py 與 ENV_TEMPLATE.txt。Crypto／AI 皆為 研究員（Grok）→ 審計／辯論（Gemini）→ 主編（Gemini） 型流程；備援鏈在 crew.py。

---

環境變數摘錄

除啟動四項外，常見還有：NEWSAPI_KEY、TAVILY_API_KEY、COINGLASS_API_KEY、FRED_API_KEY、FMP_API_KEY、FINANCIAL_DATASETS_API_KEY、TELEGRAM_*、GCP_*、可選 STRICT_INSTITUTIONAL_PHASE_A_GATE／B／C、STRICT_NEWS_FRESHNESS_GATE、EARNINGS_FOCUS_MODE（財報日／週末預告 exclusion，見 earnings_focus.py、earnings_watchlist.py）等。權威列表：ENV_TEMPLATE.txt。

Mega-cap／AI 財報 watchlist（yfinance 日曆掃描與財報聚焦共用；含矽光子／光通訊、AI 伺服器／ODM、資料中心網路等公開敘事常見標的，非即時熱度排名）：NVDA、AMD、INTC、AVGO、MRVL、QCOM、MU、TSM、ARM、SMCI、DELL、HPE、MSFT、GOOGL、AAPL、META、AMZN、ORCL、CRM、NOW、SNOW、PLTR、CRWD、NET、ANET、CSCO、LITE、COHR、FN。

---

驗證與觀測

• validate_report：HTML 規則（新聞則數、UTC+8、trade_watch、partial news 等）。
• 結構化：schemas.py 與 QSREC 業務規則。
• 本機：.qsilicon/last_gate_failure/（GATE_FAILURE_ARTIFACTS=1）。
• BQ：gate_failure_log（GATE_FAILURE_BQ_LOG）；SQL 範例 docs/SQL/gate_failure_weekly_summary.sql。

---

開發與測試

ruff check .
python3 -m pytest -m smoke -q    # 與 PR CI 對齊（requirements-ci.txt）
python3 -m pytest -v             # 全量
python3 -m pytest -m boundary -v
python3 -m pytest test_api_positions_bundle.py test_api_stream_war_room.py test_tech_pulse_tool.py -q   # Portal M4–M7 契約 + SSE watch_symbols + tech_pulse（2026-05-11）
python3 -m pytest tests/api/test_portfolio_router.py -q   # Portfolio Tracker Queue 38（CRUD / CSV / P&L）
python3 -m pytest tests/api/test_macro_router.py -q       # Macro Dashboard Queue 39（8 指標 / cache）
./scripts/bench_autoresearch.sh
./scripts/verify_graph_gate.sh     # Graph／Reviewer 變更後（等同 pytest test_reviewer_loop.py -q）

PR／deploy 使用輕量 requirements-ci.txt 與 conftest.py stub。全量測試若含 Hypothesis 需另行 pip install hypothesis。改 graph/ 或 Reviewer 閉環時亦見 docs/architecture/GRAPH_REVIEWER_CHANGE_CHECKLIST.md。

---

目錄結構（精簡）

main.py, crew.py, config.py, schemas.py
graph/
tools/, tools_legacy.py
report_*.py, validation_rules.py
api.py, api_routers/, dashboard.py
symbol_snapshot_service.py
templates/telegram_report.j2
docs/, scripts/, core/
data-verification-ui/
.github/workflows/
ENV_TEMPLATE.txt, TODOS.md, CHANGELOG.md, CLAUDE.md

---

Docker

docker build -t q-silicon-agent .
docker run --env-file .env q-silicon-agent

---

CI／GitHub Actions

Workflow	說明
ci.yml	PR：ruff + smoke；可 workflow_dispatch quick／full
deploy.yml	main 且變更命中 paths（*.py／Docker／依賴等）才自動跑 smoke → Docker；純 .md／文件 push 不觸發。需部署時：Actions → 本 workflow → Run workflow。
nightly-ci.yml	全量 pytest
monitor-intraday.yml	盤中監控（cron 預設關）
weekly-scout.yml	OSS scout

部署與人工閘門：docs/DEPLOY_RUNBOOK.md。

---

資料流（一句話）

BQ／排除 context → 雙軌研究 → assemble／render →（可選 editor）→ validate → Telegram／BQ／儀表與 PWA。

---

輔助腳本

腳本	用途
scripts/bench_autoresearch.sh	Lint + smoke + METRIC
scripts/verify_graph_gate.sh	Graph／Reviewer：pytest test_reviewer_loop.py -q
scripts/verify_ops_queue_18_21.py	營運 18–21：Redis PING、VAPID／admin key 提示、可選 BQ 表存在（見 Runbook Step 0）
scripts/write_ml_weights.py	ML 權重
scripts/run_mock_smoke.sh	MOCK_APIS=1 smoke
python backtest.py	回測

---

文件索引

主題	路徑
閾值實驗	docs/STAGING_THRESHOLD_EXPERIMENT.md
Critical env	docs/CRITICAL_ENV_POLICY.md
Gate 人審	docs/GATE_FAILURE_HINT_WORKFLOW.md
儀表契約	docs/DASHBOARD_CONTRACT.md
PWA 離線策略（Workbox）	docs/PWA_OFFLINE.md
Portal Vercel 部署／env／SSO	docs/PORTAL_SHIP_CHECKLIST.md
Bloomberg 對齊（工作流藍圖）	docs/BLOOMBERG_ALIGNMENT.md
選幣輪動	docs/PICK_ROTATION_SEMANTICS.md
邊界測試	docs/BOUNDARY_TEST_MATRIX.md
工具 ADR

---

CoinGlass API v4

• Base：https://open-api-v4.coinglass.com，Header：CG-API-KEY
• 成功：code 為 "0" 或 0
• 401／Upgrade：多為方案不含端點；部分指標有 Binance 等備援

---

安全與維運

勿提交 .env 與服務帳戶 JSON；Telegram 輸出經白名單清洗。

---

War Room PWA 與 API

Mock：cd data-verification-ui && VITE_GLASSBOX_MOCK=1 npm run dev。
本機後端：uvicorn api:app --reload --port 8000（需 GCP 讀 BQ）。細節見 docs/DASHBOARD_CONTRACT.md。

• 離線／快取：生產用 Service Worker 以 Workbox 註冊路由 — /api NetworkOnly（不快取 API），導覽／同源靜態 NetworkFirst。說明見 docs/PWA_OFFLINE.md（CHANGELOG 2026-04-18）。

• 路由：底部導覽五板塊為 /news、/dashboard、/insights、/columns、/portfolio；/insights 承接 Terminal 工作區（watchlist 存 localStorage；代號卡呼叫 GET /api/symbols/{symbol}/snapshot 與輕量 GET /api/symbols/{symbol}/quote（最新日線收盤／1D%，僅 yfinance））。

• VITE_API_URL：Vite 建置時注入；未設時請求為同源相對路徑（Vercel polyglot：PWA 與 FastAPI 同 origin）。本機前後端分埠時例：VITE_API_URL=http://127.0.0.1:8000 npm run dev。

Vercel 正式站

正式 URL：https://[REDACTED].vercel.app。目標是靜態 PWA 與 FastAPI 同一 Vercel 專案（根 vercel.json services）。Dashboard Root Directory = .；PR preview GET /healthz 已通（2026-09-09）。正式站仍指向舊 Cloud Run（GitHub secret VITE_API_URL 未清空），不要假裝 /insights 已通。

• Production：只走 .github/workflows/pwa-deploy.yml prebuilt（vercel pull → vercel build → vercel deploy --prebuilt --prod）。根 vercel.json 設 git.deploymentEnabled.main=false，禁止 Git Integration 對 main 遠端 build 上正式站。
• VITE_API_URL：preview polyglot /healthz 已通；正式切換時清空（同源）。PR Preview 讀 Vercel Preview env，不是 GitHub secrets。
• 驗收／SSO／CORS：見 docs/PORTAL_SHIP_CHECKLIST.md「Vercel PWA Deploy」。建議 Production 關 Vercel Authentication（改靠 QSILICON_MASTER_KEY + /api-key），Preview 保留 SSO。npm run smoke:prod：BASE_URL 必填，API_BASE 預設同一 origin。

正式上線 vs CI／E2E 專用旗標

變數／行為	正式 launch（預設）	僅 CI／E2E
VITE_E2E=1	勿在 production bundle 使用	npm run test:e2e（e2e/run-ci.sh）強制；關閉 PWA plugin、關閉 production 缺 API banner、401 不跳轉 /api-key
VITE_API_URL	空＝同源 /api；本機分埠才設後端基底	E2E 由腳本注入 mock http://127.0.0.1:<port>
VITE_STRUCTURED_REPORT	依產品需求 0／1	E2E 腳本設 1 以走結構化路徑
DailyBriefPage.jsx 等 E2E seed	僅在 VITE_E2E=1 時啟用測試資料	見各 spec 與該頁 import.meta.env.VITE_E2E 分支
VITE_GLASSBOX_MOCK	本機 mock 儀表板用；prod 依治理關閉	E2E 腳本可設 0

完整變數註解見 data-verification-ui/.env.example 與根目錄 ENV_TEMPLATE.txt。Staging／prod 手動 smoke：cd data-verification-ui && BASE_URL=… API_BASE=… npm run smoke:prod（腳本：scripts/smoke-prod.sh）。

• VITE_TERMINAL_POLL_MS（可選）：/insights 內 snapshot／意圖列表／War Room 輪詢間隔（毫秒），預設 45000；本機除錯可設 15000。見 docs/TERMINAL_MID_TIER_ROADMAP.md。
• SSE（可選）：後端 TERMINAL_SSE_ENABLED=1 時提供 GET /api/stream/war-room；查詢參數 watch_symbols（CSV，例 BTC,NVDA）可驅動 symbol_quote 事件；前端 VITE_SSE_ENABLED=1，若設 API_STREAM_AUTH_KEY 則同步 VITE_SSE_STREAM_KEY。短期 token（2026-05-16）：POST /api/stream/token（預設 404，須 API_STREAM_AUTH_KEY）回傳 {token, expires_at, ttl_seconds}，瀏覽器以 ?stream_token= 連 SSE，避免長效金鑰外洩；TTL 由 SSE_TOKEN_TTL_SECONDS 控制（預設 60s，10–600 clamp）。事件節流：SSE_MAX_EVENTS_PER_SEC >0 時啟用每連線滑動 1 秒視窗，超量 yield event: throttled。紙上一輪：python scripts/paper_execution_tick.py 或 PAPER_TICK_HTTP_ENABLED=1 時 POST /api/paper/execution-tick（可選 PAPER_TICK_API_KEY）。

Portal API（M4–M7 + Phase 2 paper lifecycle）

五模組頁面所用聚合（詳見 CHANGELOG.md 2026-05-11／2026-05-13；完整隊列邊界見 TODOS.md 隊列 28–35）：

方法	路徑	說明
GET	/api/positions	開倉建議聚合 + execution intents（legacy M4 read slice）
GET	/api/paper/lifecycle	execution-intents 紙上生命週期 summary + risk metrics
GET	/api/paper/pnl	realized/unrealized paper P&L，active rows best-effort quote enrichment
GET	/api/paper/transparency-letter	internal-only monthly paper letter + sample threshold + portfolio symbol alignment
POST	/api/execution-intents	手動建立 PENDING_REVIEW intent；append-only，不下單
GET	/api/execution-intents	最新 intent blotter；含 quality score/grade/reasons read-model 欄位
GET	/api/industries/themes	靜態主題表 + sector rotation + regime 提示（M5）
GET	/api/analysis/{symbol}	quote + snapshot（snapshot 可失敗降級）；/insights?symbol= 顯示 deep dive
GET	/api/quant/signals	紙上敘事用訊號列（M7；不承諾收益）
GET	/api/quant/backtest	QUANT_BACKTEST_ENABLED=1 時回傳 paper-derived deterministic equity curve

Macro Dashboard API（Queue 39，2026-05-13）

/dashboard 讀 GET /api/macro/snapshot：8 個 macro / risk 指標（10Y、2s10s、DXY、VIX、BTC、SOXX/SPY、AI Momentum、Next Fed/CPI），每列含 value、change_1d、change_5d、7 點 spark、source、as_of。市場資料以 yfinance 為主；next_fed_cpi 的未來 7 天 catalyst 可選讀 FMP_API_KEY，未設時顯示 N/A 而不阻斷 dashboard。後端有 60 秒 in-process cache。

Tech News API（Queue 40，2026-05-13）

/news 讀 Firestore-backed tech pulse digest。預設 collection 為 TECH_PULSE_FIRESTORE_COLLECTION=tech_pulse_memory_items，可選 TECH_PULSE_FIRESTORE_PROJECT 指定專案；所有新聞 item 必須有 headline 與 source，缺來源資料會被 API 過濾。

方法	路徑	說明
GET	/api/news/digest?date=YYYY-MM-DD&limit=20	讀 digest items；回傳 headline、Gemini take、source domain/url、time、tags、confidence
GET	/api/news/deep?pillar=ai|semiconductor|crypto&limit=20	科技專欄 deep brief list；回傳 title、summary、body/content、source、tickers、reading_minutes
GET	/api/news/deep/{item_id}	讀單則 deep brief；含 thesis breakdown、confidence、tickers
GET	/api/news/themes	由近期 sourced items 聚合今日主題

Columns / Cross-board Terminal（Queues 42–43，2026-05-13）

/columns 已接 AI／半導體／Crypto 三支柱 Deep Brief，相關主題仍讀 GET /api/industries/themes。全域 Command Bar 支援 5 板塊跳轉與 /insights?symbol=... deep-link；右下角 shared monitor 提供 localStorage Watchlist 與 price alert queue。

方法	路徑	說明
GET	/api/push/price-alerts	讀 JSONL price alerts（PRICE_ALERTS_FILE 可覆寫）
POST	/api/push/price-alerts	新增 alert：symbol、`direction=above
DELETE	/api/push/price-alerts/{id}	刪除 alert
POST	/api/push/price-alerts/check?send_push=false	以 yfinance quote helper 檢查 threshold；send_push=true 時接既有 Web Push send path

Track Record API（Queue 41，2026-05-13）

/insights 的 Track Record tab 讀 append-only execution_intents.jsonl 中最新 PAPER_CLOSED rows，計算 paper-only W/L、hit rate、avg return、Sharpe 近似、max drawdown 與累積曲線；每列帶 source／source_id 供審計。可選 RECOMMENDATION_OUTCOMES_TABLE 搭配 python scripts/mark_recommendations.py 將 active/closed paper signals mark-to-market 寫入 BigQuery（DDL：docs/SQL/recommendation_outcomes.sql）。

方法	路徑	說明
GET	/api/track-record/summary	Track Record KPI 與 equity curve
GET	/api/track-record/closed	closed paper signals，支援 limit／offset
GET	/api/track-record/by-tag?tag=AI	依 category / asset / outcome tag 切片

Portfolio Tracker API（Queue 38，2026-05-13）

/portfolio 使用本機 JSONL storage（預設 portfolio_holdings.jsonl，可用 PORTFOLIO_HOLDINGS_FILE 覆寫；此檔為本機資料，不提交 repo）。CSV 唯一支援欄位順序：symbol,shares,cost_basis,opened_at,notes。

方法	路徑	說明
GET	/api/portfolio	讀取 holdings
POST	/api/portfolio	新增 holding（symbol、shares、cost_basis、opened_at、notes?）
PATCH	/api/portfolio/{holding_id}	更新 shares、cost_basis、opened_at、notes
DELETE	/api/portfolio/{holding_id}	刪除 holding
POST	/api/portfolio/import	multipart CSV 匯入
GET	/api/portfolio/pnl	以 yfinance quote enrich 市值、P&L、權重；單檔 quote 失敗只標該列錯誤

• 日報可選 — Tech pulse：TECH_PULSE_IN_BRIEF=1 時 main.py 於 _run_pipeline_once 將 tools/tech_pulse_tool.py 摘要併入 exclude_context（與 CrewAI／LangGraph 雙軌共用）；TECH_PULSE_URL 與 MOCK_APIS 行為見 docs/ADR_TECH_PULSE_INTEGRATION.md 與 ENV_TEMPLATE.txt。
• 產品對齊說明：docs/BLOOMBERG_ALIGNMENT.md（能力映射與驗收；非外觀複製 Terminal）。
• 實盤價格觀測（BQ vs yfinance）：python scripts/symbol_price_probe.py BTC（stdout JSON）；可選 PRICE_PROBE_WRITE_BQ=1 + PRICE_PROBE_LOG_TABLE=… 寫入 BQ（建表 docs/SQL/price_probe_log.sql）。
• Web Push（T4a）：docs/PWA_WEB_PUSH.md — WEB_PUSH_REDIS_URL、WEB_PUSH_VAPID_*、POST /api/push/test-send（WEB_PUSH_ADMIN_KEY）；產鑰 python scripts/vapid_generate.py。

Streamlit 戰情室（v4）

streamlit run dashboard.py（與上表「戰情室 UI」同）。主題與 Plotly 樣式抽至 dashboard/theme.py。可選環境變數 DASHBOARD_AUTO_REFRESH_SEC（預設 300）驅動頁面自動刷新；分頁資料源含 BQ llm_run_log／gate_failure_log 與本機日報 JSON（DAILY_BRIEF_JSON_DIR／.qsilicon／logs/run_* 之 current_affairs_roundtable）。完整條目見 CHANGELOG.md 2026-04-18 ### Added。

結構化日報（戰報區塊視圖，可選）

• 前端：cd data-verification-ui && VITE_STRUCTURED_REPORT=1 npm run dev — 單日戰報改走 GET /api/reports/{date}/structured；當回應 structured_body_available 且含 daily_brief_report 時，以 structuredBlockContent.js 對 DailyBriefReport 做逐區塊渲染（否則 legacy 摘要）。詳見 visualization_plan.md、docs/DASHBOARD_CONTRACT.md。
• 後端：管線成功 assemble 後會寫 .qsilicon/daily_brief_reports/{date}.json（或環境 DAILY_BRIEF_JSON_DIR）；另保留 logs/run_YYYYMMDD_*/raw_data.json。可選 DAILY_BRIEF_JSON_BQ_TABLE 寫完整 JSON row（DDL：docs/SQL/daily_brief_report_json.sql）。讀取路徑見 api.py。

Optional Research Scaffolds

NotebookLM、Agency、TradingView 皆為 repo-side scaffold，預設關閉或 fallback；不會取代 validate_report、Telegram HTML Gate 或客觀價格來源。

• NOTEBOOKLM_ENABLED=1 + NOTEBOOKLM_NOTEBOOK_ID：允許 LangGraph 在 filing keywords 命中時產生 optional deep_filing_block；live NotebookLM client 尚未接，缺 citation 時不渲染。
• AGENCY_RESEARCH_ENABLED=1：允許 Agency template parser、LangGraph optional agency_finance_block 與 Crew backstory 摘要注入。
• TRADINGVIEW_MCP_ENABLED=1 + TRADINGVIEW_MCP_COMMAND：啟用 repo-side TradingView command bridge；不修改 ~/.claude，失敗時依 TRADINGVIEW_FALLBACK_YFINANCE fallback。

---

gstack（選用）

瀏覽器 QA、review、ship 等流程 — 見 AGENTS.md 與 gstack.md。