# Research Dashboard

這是 `brain/research/` 的靜態研究索引，解決「研究做完後不知道去哪裡找、也看不出前後差異」的問題。

## 檔案

```
brain/research/
  INDEX.md                     ← 人類可讀索引（自動生成）
  dashboard/
    build_dashboard.py         ← 掃描 research.json，生成下面兩個檔
    dashboard.json             ← 機器可讀索引（自動生成）
    index.html                 ← 靜態網頁入口（自動生成）
    README.md                  ← 本文件
```

## 手機版

手機 app 通常不支援直接預覽 workspace 的 raw HTML；如果點 `index.html` 會跳回對話，請改開 **Markdown 版**：

```
brain/research/DASHBOARD.md
```

Markdown 版包含同樣的索引、指標表、shadow test 與圖片，mobile app 的 `.md` 檢視器可以直接顯示。

## 怎麼看（桌面/瀏覽器）

直接用瀏覽器打開：

```
brain/research/dashboard/index.html
```

或透過 workspace file server 開啟同一路徑。頁面包含：

- 按日期倒序的研究卡片
- 每個研究的 status / verdict / tags
- 校正後指標表（CAGR、Sharpe、MDD、OOS）
- 關鍵發現、圖表縮圖、報告/表格/協議/程式連結
- 搜尋與策略/狀態/分級篩選

## Active study for the daily log

Edit `brain/research/daily_log_study.txt` to choose which study the daily log
uses when `--study` is omitted. It currently points to `R-2026-11-14-01`.

## GitHub Pages

把 dashboard 發佈成一個真的網址（手機可直接開）：

```bash
uv run python brain/research/dashboard/build_dashboard.py
uv run python brain/research/dashboard/make_offline_bundle.py
uv run python brain/research/dashboard/publish_pages.py
```

`publish_pages.py` 會把 bundle 解到 `docs/research/`，並建立 `docs/research/index.html` redirect。之後：

1. commit + push `docs/research/`
2. GitHub repo → Settings → Pages → Source: **Deploy from a branch**
3. Branch: `main`，Folder: **`/docs`**
4. 網址：`https://gogoenergy.github.io/nyrobrain-workspace/research/`

每天 03:00 的 GitHub Action 會自動 rebuild dashboard、更新 `docs/research/`、commit 回 repo，Pages 會跟著更新。workflow 也設定了 `on: push`：任何 `research.json`、`report.md`、`G1_REVIEW.md`、`assets/` 或 dashboard code 的變更，都會觸發 rebuild + Pages 更新。

注意：`/docs` 會同時公開 repo 既有的 `docs/`（adrs/pipelines 等）。若只想公開 dashboard，應改用 `gh-pages` branch 或另一個 repo。

## Google Drive

同一個 Apps Script webhook 可以把 `DASHBOARD.md` 與 `standalone.html` 存到 Google Drive。設定見 `GOOGLE_DRIVE.md`。Drive 是檔案存檔，不是 web host；要 live URL 請用 GitHub Pages。

## GitHub Actions

`.github/workflows/daily-log.yml` 每天 19:00 UTC（03:00 台北，隔天）跑 `daily_log.py --sync`，並把 `daily_log.csv` commit 回 repo。GitHub Secrets 需設定 `GOOGLE_SHEET_WEBHOOK_URL`、`DAILY_LOG_SECRET`。詳見 `GOOGLE_SHEET.md`。

> 若平台 GitHub token 沒有 `workflow` scope，無法 push `.github/workflows/*`。請用 GitHub 網頁版建立 workflow，內容可直接複製 `daily-log.workflow.yml`。

## 離線 / 下載

- **單檔 HTML：** `standalone.html` — 所有圖表已用 base64 嵌入，下載後直接用瀏覽器打開。
- **完整 bundle：** `research_dashboard_bundle.zip` — 保留 `dashboard/` 與各 study 的相對路徑；解壓後打開 `dashboard/index.html`，報告/表格/G1/圖表連結都會工作。

一般 `index.html` 是給 workspace file server 用的；單獨下載它會讓 `../<study>/assets/...` 的縮圖失效。

## Workflow

研究生命週期與 G1/G2/G3 門檻見：

```
brain/research/RESEARCH_WORKFLOW.md
```

新 session 可用 `/research-workflow` 查目前 stage/gate 與下一步。

## Skill

新 session 可以直接用：

```
/research-dashboard
```

skill 會檢查 `research.json`、跑 build、驗證連結，並回報 mobile / desktop 入口。Skill 檔案在 `.agents/skills/research-dashboard/SKILL.md`；若目前 session 的 skill 清單還沒出現它，重新載入/重開 session 即可。

## 怎麼新增一個研究

1. 建立資料夾：

```
brain/research/YYYY-MM-DD_<slug>/
```

2. 在資料夾內放一個 `research.json`：

```json
{
  "id": "R-YYYY-MM-DD-01",
  "date": "YYYY-MM-DD",
  "project": "Project Name",
  "title": "研究標題",
  "status": "completed",
  "verdict": "keep-in-research",
  "stage": "10",
  "gate": "G1",
  "gate_status": "partial",
  "gate_scope": "Strategy or baseline name",
  "gate_decision": "One-line gate decision",
  "next_stage": "G1",
  "strategy": "Strategy Name",
  "strategy_group": "Strategy Group Name",
  "phases": ["baseline", "audit", "robustness"],
  "strategy_path": "brain/strategy/...",
  "portfolio_path": "brain/portfolio/...",
  "tags": ["tag1", "tag2"],
  "summary": "3–5 行摘要",
  "key_findings": ["重點 1", "重點 2"],
  "links": {
    "readme": "YYYY-MM-DD_slug/README.md",
    "report": "YYYY-MM-DD_slug/report.md",
    "tables": "YYYY-MM-DD_slug/results/tables.md",
    "protocol": "YYYY-MM-DD_slug/paper_trial_protocol.md",
    "code": "YYYY-MM-DD_slug/src/"
  },
  "metrics": [
    {
      "name": "Baseline",
      "cagr": 0.3651,
      "sharpe": 0.956,
      "mdd": -0.6210,
      "oos_return": -0.1358,
      "oos_sharpe": -0.143,
      "verdict": "Reject",
      "note": "幾何權益曲線"
    }
  ],
  "shadow_test": {
    "period": "YYYY-MM-DD → YYYY-MM-DD",
    "btc_buy_hold": -0.13,
    "eth_buy_hold": -0.15,
    "sol_buy_hold": -0.20,
    "strategy_return": 0.0,
    "strategy_exposure": 0.0,
    "note": "說明"
  },
  "plots": [
    {"title": "圖表標題", "path": "YYYY-MM-DD_slug/assets/plot.png"}
  ]
}
```

3. 重新生成：

```bash
uv run python brain/research/dashboard/build_dashboard.py
```

4. 重新打開 `index.html`。

## 設計原則

- `research.json` 是唯一資料來源；`INDEX.md`、`DASHBOARD.md`、`dashboard.json`、`index.html` 都是生成物。`project` 用來跨策略分組。
- 不改 `brain/strategy/`、`brain/portfolio/`、`report.parquet` 或 `brain/execution/`。
- `metrics` 的數字應該用**幾何權益曲線**，不要混用算術 total return / 算術 MDD。
- 每個研究都應該有 `report.md`、`results/tables.md`、`assets/`、`src/`，讓結果可重現。
- `verdict` 建議只用：`Reject`、`Keep in research`、`Paper candidate`、`Eligible for paper trading`。
- `status` 建議只用：`completed`、`in-progress`、`parked`。
