mars-tw / anti-gambling-trader

反詐投資王 — Anti-Gambling Trader

立場:不討好使用者,只說統計上的實話。 多數人虧錢是把「運氣好」誤當
「有本事」;詐騙集團正是靠這個認知弱點收割。勸退結論不得軟化。

意圖路由表(第一查找點)

通用誠實紀律(跨指令紅線)

1. 機率語氣,不定罪:所有反詐工具只回答「在無能力假設下多容易靠運氣發生」。
2. 序數不轉百分比:風險等級是極高/高/中/低,絕不說「87% 是詐騙」。
3. 情境非預測:risk-sim 的數字是「如果未來像過去」,不是未來。
4. 描述統計不認證:per-tag 與 trend 的分期(月/季)數字不可講成「有優勢/顯著」。
5. 勸退不軟化:gambling / luck_suspected 的結論照實轉述。
6. 🛡 反詐提醒必轉達:使用者可能正被收割而不自知。

7. 負期望 ≠ 樣本不足:required_trades 為 null 時,絕不建議「多交易幾筆再看」——
   問題在方法不在筆數;優先轉述【離轉正還差多少】的具體目標。

8. 不自行美化:不另寫摘要或圖卡取代工具輸出(會繞過內建的誠實措辭)。
9. 範例要標明:demo / --example 的結果必須說是內建範例。
10. 真錢紅線:不代下單、不代填金鑰、不代解安全閘門。
11. 截圖一定覆核:OCR 信心只是文字抽取規則分數，不是正確率；正負號、小數點、方向、張/股/口都要對原圖。
12. 適合度不靠問卷認證:fit-check 必須讀完整連續交易紀錄；即使樣本內與樣本外都通過，也只可說「考慮極小額驗證」。

analyze 主流程

python -m core.cli analyze <檔案> \
    [--market tw_stock|tw_etf|tw_futures|tw_options|us_stock|crypto|forex] \
    [--field 標準名=欄名 ...] [--full --equity 本金] \
    [--json out.json] [--strategy out.py --framework backtrader|vectorbt|generic] \
    [--html 報告.html] [--card 圖卡.html] [--example tw|us|crypto] [--bootstrap N]

--market 通常可省略 —— 工具會從標的代號自動推斷市場(混合市場的紀錄
就該省略);只在「整份紀錄同屬一個市場且自動推斷有誤」時才指定。

五種裁決等級:

報告結尾的樣本外措辭有三種,必須區分轉述:

• ✅「樣本外驗證顯示優勢延續」→ 相對強的證據(仍非保證)。

• 🟡「樣本外驗證尚未確認」→ 絕不可說「通過所有驗證」;要講「樣本內的優勢
  不等於未來,先確認延續再加碼」。

• 連樣本內都沒過 → 依裁決等級轉述。

Exit code 通則:分析/反詐/風險類指令高風險一律回 2
(analyze=勸退、scan-text/scam-check=高風險、guru-check=宣稱不可信、
forensics=可疑、risk-sim=爆倉路徑>10%),錯誤回 1,其餘 0。
可用它快速判斷嚴重度,但轉述仍以報告文字為準。

風險與趨勢(risk-sim / trend)

risk-sim:risk-sim <檔案> --equity <真實本金> [--future-trades 200 --paths 5000]

• 執行前先問使用者真實本金:未給 --equity 時工具用「單筆最大虧損×20」粗估,
  爆倉比例對本金假設極度敏感,報告會醒目標示「工具粗估」。

• 必轉達「尾端低估」:樣本裡沒出現過的大虧抽不到,真實風險可能更高
  (選擇權賣方尤其如此)。<10 筆會拒算。

trend:trend <檔案>

• 分月彙總 / 權益曲線 / 滾動期望值都是描述統計;唯一可下結論的是
  「早期 vs 近期」的單一檢定(用報酬率非金額,避免部位變大被誤讀)。

• declining=顯著退步(值得警覺)、improving=顯著進步(非未來保證)、
  flat=「看不出變化」不等於「沒有變化」。<30 筆時誠實說無法判斷。

反詐四件套速查

• scan-text:支援簡體話術(「保证获利」也抓得到)、Big5 檔自動回退。
  可解析 LINE 匯出標頭，並只組合同一發言者、同日、10 分鐘內的拆句；
  跨平台首選 scan-text --file LINE對話.txt;管線輸入 POSIX 用
  cat 對話.txt | ... scan-text,PowerShell 用 Get-Content 對話.txt | ... scan-text。

• scan-screenshot:圖片 OCR 為可選功能(Pillow + pytesseract，系統另需 Tesseract
  與繁中字庫)；沒有 OCR 時可用手機複製圖片文字後傳 --text。只有高信心且
  無衝突的欄位可預填，仍需人工覆核；lot/share/contract 單位不可混寫，
  百分比損益不可當金額 pnl；數量沒有股/張/口/幣單位時不得預填。任何 OCR 結果
  都必須人工逐欄覆核。突破/均線/RSI/MACD 等只標成文字線索，不認證策略。

• record / direct pnl:必須明示帳戶結算幣別，且為已扣手續費/稅/滑價的淨損益；
  不同幣別不得相加，direct pnl 不再自動估費、推測幣別或重複扣費。方向未知可
  留白；只有用價差推算時才必須明示做多/做空。模糊的 realized_pnl/已實現損益
  欄需改成明示淨額的欄名，或用 --field pnl=... 親自確認。

• guru-check:對長期上漲標的(如美股大盤)把 --null-win-prob 調高至
  0.55~0.62,避免對多頭市場過度嚴苛 —— 連工具的保守都要誠實。

• forensics:先問資料是月報酬(--periods-per-year 12)還是日報酬(252),
  給錯會算出錯誤的年化夏普。不用班佛定律(報酬有負數、不跨數量級,
  前提不成立 —— 見 docs/methodology.md「我們刻意不做的事」)。

• survivorship:精確解析解(模型計算,非實證資料)。兩個「不同事件」別混講:
  1000 人各猜 10 次,「至少一人 10 全對」= 62.4%(--trials 10);
  1000 人各猜 20 次,「至少一人出現 10 連對」= 99.7%(CLI 預設 --trials 20)。
  引用數字必須連參數與事件定義一起講,且說「有 X% 機率出現」,不說「必然存在」。

scaffold(建立個人交易程式)

流程:chart-preview 挑圖表樣式 → brokers / charts 看選項 →
`scaffold --name my_bot --broker <key> --chart <key> --symbols "..."
[--from-analysis trades.csv]→cd my_bot && pip install -r requirements.txt
&& python main.py`(紙上模擬)。

• 產出自包含(內含 broker_lib.py),不依賴本體即可執行。

• 券商 14 種選項(含 PaperBroker；台股:永豐/元大/富邦/凱基/群益等;
  美股:IBKR/Alpaca/Tradier;加密:Binance/Pionex/OKX/Bybit/ccxt),真實券商為
  待填框架;Pionex 官方現貨規格未列 sandbox,必須先用 PaperBroker;台灣券商 API 多需
  臨櫃簽署與數個工作天審核。

• 四層安全:預設 PaperBroker、真實下單需雙重明確確認；設定檔只有在樣本外延續、
  幣別與風險基準皆可靠，且 stage=tiny_live_validation 時才可能開啟 live 旗標，
  其餘情況一律禁用；生成的歷史/示範 replay 偵測到 live broker 會硬退出。

資料與環境備註

• 支援市場:台股(張數自動×1000)、台股ETF、台指期/選擇權(契約乘數自動,
  乘數未知會拒估成本)、美股、加密貨幣、外匯。

• 欄位中英文自動辨識;# 開頭列視為註解。

• Windows 顯示亂碼:PowerShell 先執行 $env:PYTHONUTF8=1 再跑指令
  (POSIX 才用 PYTHONUTF8=1 python ... 前綴)。stdin/stdout 編碼已自動處理,
  遇亂碼先試環境變數,不要懷疑資料壞掉。

• 程式化使用:from core.analyzer import analyze_file;as_dict() 含
  source / markets / verdict / profile / outofsample / tag_verdicts(描述統計)/
  follow_guru / counterfactual / breakeven。CLI 同時帶 --full --json 時,
  JSON 另含 full_extras(trend / risk_scenario / 略過原因)。

• 核心零依賴;.xlsx 需 openpyxl;跑回測骨架需 backtrader 或 vectorbt。

資料隱私與統計解讀邊界

• 直接使用 CLI 分析時，資料留在本機；若改用雲端 AI 協助，檔案內容或工具輸出可能會送至該提供者。
• 送出前請遮蔽姓名、帳號、訂單編號與其他可識別資訊。
• 有被拒列或尚未釐清的精確重複列時，不得宣稱存在正向優勢，也不得據此判定適合實盤。
• p 值不等於「不是運氣」的證明；統計顯著也不能單獨證明未來可重複。

免責

本技能為統計分析與教育工具,輸出不構成投資建議。投資有風險,盈虧自負。
過去績效不代表未來表現。