📈 Buy-Side Memo Agent — 台股 × 美股個股研究備忘錄生成器

每天自動為你追蹤的每一檔個股,產出買方(buy-side)等級的研究備忘錄:
決策先行、數字可溯源、交叉檢核不過就不出報告。
不是「AI 幫你寫心得」,是一條帶硬性資料紀律的研究生產線。

Markdown 技能包 + 純 stdlib Python 工具,可安裝到任何 Claude Code / Agent SDK 環境。

✨ 能力總覽

能力	說明
🇹🇼 台股全套紀律	民國年→西元、財報「千元」單位、除權息缺口、零覆蓋小型股——台股特有的資料陷阱全部內建為檢核項
🔒 月營收×季報自動交叉檢核	Σ(當季三個月營收) vs 季報合併營收,±2% 容差,逐季 `PASS / FAIL / INCOMPLETE` 判定 + 千元/元單位錯置偵測。FAIL = 該檔停止出報告
🇺🇸 美股確定性數據骨幹	價格+新鮮度、52 週區間定位、DCF 三情境錨點(bear/base/bull + 生成日期)、匯率——量化數字一次到位,網路研究只負責質化內容
🧾 決策先行的備忘錄結構	Decision Box 開頭:評等傾向、目標價區間、上下行不對稱、核心辯論、可觀察有日期的論點斷點
📅 每日歷史留存	每天一份快照 `memos/<代號>/<日期>.html`,日期選單回顧,更新協定先驗證斷點再刷新
🎨 主題化編輯級渲染	襯線標題+等寬數字的 editorial 版面、跟隨 App 深淺主題、CJK 兩端對齊、手機自適應表格
🌐 可攜與降級	`$IFW_PROJECT_ROOT` 自動定位資料庫;沒有專案的機器上,公開 API 部分照常運作,其餘區塊明確回報 unavailable——絕不編造數字

🖼 效果展示

台股備忘錄(桌面)——決策框先行,數字帶出處

### 美股備忘錄(桌面)——DCF 錨點 + 反向 DCF 已定價分析

---

🏗 架構

flowchart LR
    subgraph 確定性提取層["確定性提取層(可重跑、可稽核)"]
        TW["tw_data.py<br/>月營收/YoY/法人<br/>(FinMind 公開 API)"]
        US["us_data.py<br/>價格/52週/DCF錨點/匯率<br/>(本地專案 DB)"]
        XC{{"月營收×季報<br/>交叉檢核 ±2%"}}
    end
    subgraph Agent研究層
        R["質化研究<br/>(法說/年報/新聞)"]
        L["分析透鏡整合<br/>(DCF/Bayesian/PEG/籌碼)"]
    end
    subgraph 產出層
        REN["render_memo.py<br/>主題化 HTML 渲染"]
        AR[("每日快照庫<br/>memos/代號/日期.html")]
    end
    TW --> XC
    XC -- PASS --> R
    XC -- FAIL --> STOP["🛑 不出報告<br/>回報差異"]
    US --> R
    R --> L --> REN --> AR

🔬 嚴謹性設計(這是本體,不是附加)

1. 交叉檢核寫進程式,不靠 LLM 自律

// tw_data.py --symbol 2330 的實際輸出(節錄)
"revenue_cross_check": {
  "tolerance_pct": 2.0,
  "status": "PASS",
  "quarters": [
    { "quarter_end": "2025-12-31", "verdict": "PASS", "diff_pct": 0.0 },
    { "quarter_end": "2026-03-31", "verdict": "PASS", "diff_pct": 0.0,
      "monthly_sum_ntd": 1134103440000, "statement_revenue_ntd": 1134103440000 }
  ]
}

單位錯置也抓:若 Σ月營收/季報 ≈ 1000×,即標記「千元/元混淆嫌疑」。

2. 新鮮度與資料缺口,明示不隱藏

"db":       { "price_age_days": 0, "price_stale": false,
              "week52": { "high": 495.0, "low": 273.0, "position_pct": 42.6 } },
"dcf":      { "generated_at": "…", "age_days": 0, "dcf_stale": false },
"continuity": { "complete": true, "missing_months": [] }

任何 *_stale: true 都必須寫進備忘錄的「資料概至」行。

3. 籌碼數字附上分母

三大法人買賣超同時輸出佔期間成交量 %——原始「大數字」若 <2% 成交量,
標記為噪音(佐證級證據,永遠不能當論點)。

4. 沒有資料就說沒有

// 在沒有本地專案的機器上執行 us_data.py
"dcf": { "status": "unavailable",
         "note": "thin-coverage menu applies — do not fabricate a DCF" }

零覆蓋小型股走「歷史 P/E band + 殖利率 band + 同業對照」替代選單,
整節明標「無分析師覆蓋」——誠實就是方法論。

📦 安裝

# 解壓技能包到 Claude 技能目錄
unzip memo-skills-bundle.zip -d ~/.claude/skills/
# 得到:
#   ~/.claude/skills/tw-stock-memo/                  # 台股紀律 + 全部工具
#   ~/.claude/skills/buy-side-equity-research-memo/  # 美股/通用備忘錄框架

重啟 Claude session 即自動註冊。Python 3.11+,純標準庫,零 pip 依賴。

環境變數(皆為選填)

變數	作用
`IFW_PROJECT_ROOT`	指向含 `db.sqlite3` 的資料專案 → 啟用價格/52週/DCF/匯率區塊
`FINMIND_API_TOKEN`	提高 FinMind 公開 API 的速率上限

🧭 使用

對 Agent 說:

「幫我研究 2330(台股)」/「更新 MRVL 的 memo」

或直接使用工具:

python tw_data.py --symbol 2330 --months 36    # 台股數據包 + 交叉檢核
python us_data.py --symbol MRVL                # 美股量化骨幹
python render_memo.py --symbol 2330 --title "…" --body body.html --out-dir ./memos

配合排程(如每日 09:30)即成全自動:新標的→初次覆蓋;既有標的→先驗證
論點斷點,再以新證據做貝氏更新;無實質變化時,誠實的一行「無變化」
也是合法更新——絕不假裝有進展。

🛡 不變量

交叉檢核 FAIL → 該檔不出報告,回報差異
任何 stale 旗標 → 必須揭露於「資料概至」
DCF 不可得 → 走替代估值選單,禁止捏造
每個數字都能指回產生它的區塊(來源+擷取日)
產出為研究參考,非投資建議(每份備忘錄含標準免責聲明)

📄 免責

本技能之所有輸出僅供研究參考,不構成任何投資建議。範例截圖中之個股分析
為自動化研究流程的演示樣本,其數據與觀點不應作為交易依據。

TW/US STOCK REPORT