# 骨科論文自動化使用方式

這個專案主流程是 local-only：使用 macOS launchd、Codex CLI / npm scripts、本地檔案與 OpenWiki。主流程不呼叫 LLM API、不寫 Notion API、不自動操作 GPT Pro。

## 最常用的入口

### 0. START HERE

不知道現在該做哪一步時，雙擊：

```bash
START-HERE.command
```

它會刷新控制台與入口選擇，讀取目前的 `Operator Pick`，再打開控制台與推薦頁。這是 Finder 裡最適合放桌面或 Dock 旁邊的入口。

目前設計是先看再動作：它會打開 `index.html` 與 `operator-pick.html`，並在 Terminal 顯示推薦入口；只有你按 `r` 時才會打開推薦的 `.command`。所以平常雙擊它是安全的，不會立刻重跑 pipeline。

要測試入口但不要開視窗：

```bash
cd "."
./START-HERE.command --no-open --skip-sync
```

這個 no-open smoke test 已納入 `automation-ui-smoke.html`。

### 0.1 執行目前推薦

如果你已經看過 `Operator Pick`，確定要直接開目前推薦動作，雙擊：

```bash
do-recommended.command
```

它會解析目前推薦入口並打開對應 `.command`。測試但不開視窗：

```bash
cd "."
./do-recommended.command --no-open --skip-sync
```

### 0a. 按鈕式操作台

雙擊：

```bash
open-cockpit.command
```

它會刷新並打開 `automation-cockpit.html`，把「只看、檢查、執行、修復」分成按鈕。

### 0b. 執行中監控

雙擊：

```bash
open-live-monitor.command
```

它會持續刷新 `automation-live.html`。這個 Terminal 視窗會常駐；要停止時，關閉該視窗或按 `Ctrl-C`。

### 0c. 健康報告

雙擊：

```bash
open-health.command
```

它會刷新 `automation:doctor` 與 `automation-health.html`，直接看 launchd、local-only 邊界、雙擊入口 smoke 與 schema gate 是否全綠。

### 0c.1 可執行性稽核

雙擊：

```bash
open-executability.command
```

它會刷新 `automation-executability.html`，用一頁回答現在能不能交給 `launchd`、能不能雙擊入口、`Automation lock` 是否 free，以及最近 `launchd:test` / `run+verify` / UI smoke / freshness / safety gates 是否全綠。

測試但不要開視窗：

```bash
cd "."
./open-executability.command --no-open --skip-refresh
```

### 0d. 畫面舊了就同步視覺報表

雙擊：

```bash
sync-visuals.command
```

它只刷新 `index.html`、`automation-visual-sync.html`、`automation-freshness.html` 和其他視覺報表，不會重跑 paper pipeline、不下載論文、不碰 Notion / GPT Pro。

內部會先解析目前應使用的 `status.json`，所以每週新 run 產生後不需要手動改路徑。要在 Terminal 查看目前路徑：

```bash
npm run status:path
```

### 1. 10:00 開始閱讀

雙擊：

```bash
open-daily-brief.command
```

它會刷新並打開：

- `daily-brief.html`
- `workflow.html`
- `openwiki/quickstart.md`

這是人類上線閱讀時最該點的入口。

### 1.1 查看目前 run bundle

雙擊：

```bash
open-current-run.command
```

它會解析目前 `status.json`，直接打開本輪 run folder 與主要輸出：

- `status.json`
- `mega.md`
- `workflow.html`
- `gpt-pro-handoff.md`
- `manual-actions.html`
- `report.md`
- `rag-queue.json`

要測試但不要開視窗：

```bash
cd "."
./open-current-run.command --no-open
```

### 查看全部自動化目錄

雙擊：

```bash
open-automation-manifest.command
```

它會刷新並打開 `automation-manifest.html`，列出正式視覺頁、雙擊入口、npm scripts 與 local-only 邊界。

### 2. 日常快速健檢

雙擊：

```bash
check-automation.command
```

它不重跑 paper pipeline，只檢查目前輸出、視覺頁、連結、操作入口與既有深驗收報告。通常約 10 到 30 秒。

### 2b. 正式重跑完整流程

雙擊：

```bash
run-automation.command
```

它會先跑完整 local-only pipeline 與驗收，成功後自動接著跑 `sync-visuals.command` 同一套視覺同步邏輯。因此跑完後打開的 `index.html`、`automation-visual-sync.html`、`automation-freshness.html` 會是同一輪狀態。

### 3. 排錯儀表板

雙擊：

```bash
open-debug-dashboard.command
```

它會刷新並打開：

- `automation-state.html`
- `automation-local.html`
- `automation-run-and-verify.html`
- `automation-check.html`
- `automation-launchd.html`

如果不確定哪裡壞了，先點這個。

### 3.1 最近失敗 log

雙擊：

```bash
open-latest-failure.command
```

它會讀取 `automation-run-and-verify.json`、`automation-log.json`、`automation-timeline.json`，打開最近 failed step 的 stdout/stderr、timeline 與 health。若目前沒有新失敗，會清楚印出目前沒有 failed step。

要測試但不要開視窗：

```bash
cd "."
./open-latest-failure.command --no-open
```

## launchd 出錯時

先雙擊：

```bash
diagnose-launchd.command
```

它會產生並打開：

- `automation-launchd-diagnose.html`
- `automation-launchd-diagnose.json`

這頁會檢查專案 plist、已安裝 plist、plist 是否同步、service 是否載入，並列出 `No such file or directory`、`Bootstrap failed`、`Could not find service` 的對應修復指令。

如果診斷頁顯示需要修復，再雙擊：

```bash
repair-launchd.command
```

## 正式重跑

雙擊：

```bash
run-automation.command
```

或終端機：

```bash
cd "."
npm run automation:run-and-verify
```

這會跑完整 local pipeline 與深驗收。改流程後、週四正式跑前、或想確認整條鏈時使用。

## 週四 06:00 排程

安裝或重載：

```bash
install-launchd.command
```

完整驗收 launchd 排程，會安裝、立即觸發、輪詢到結束並產生報告：

```bash
install-and-test-launchd.command
```

只想立刻送出 launchd 觸發，不等待完整流程結束：

```bash
kickstart-launchd.command
```

查看排程狀態頁：

```text
automation-launchd.html
```

查看 launchd 安裝診斷頁：

```text
automation-launchd-diagnose.html
```

目前排程是每週四 06:00，使用 `scripts/run-and-verify-local.mjs`。

## 重要頁面

- `index.html`：控制中心。
- `automation-cockpit.html`：按鈕式操作台，分清楚只看、檢查、執行、修復。
- `automation-live.html`：執行中監控；搭配 `open-live-monitor.command` 會持續刷新。
- `automation-state.html`：總狀態，先看這頁判斷能不能自動跑。
- `daily-brief.html`：10:00 閱讀入口。
- `automation-local.html`：底層 local pipeline 的每一步與 stdout/stderr。
- `automation-run-and-verify.html`：完整流程與深驗收。
- `automation-check.html`：快速健檢。
- `automation-map.html`：n8n-like 節點圖。
- `automation-timeline.html`：最近執行歷史。
- `manual-actions.html`：GPT Pro、OpenWiki review、RAG 等人工待辦。

## 判斷現在是否可靠

先看：

```text
automation-state.html
```

狀態為 `ready` 且 `failed gates` 為空，代表本地自動化目前可交給排程。人工待辦不阻塞 06:00 自動跑，也不阻塞 10:00 閱讀，只代表後續品質補完項目。

## 外部服務邊界

目前主流程不做：

- 不呼叫 OpenAI / Claude API。
- 不自動寫 Notion。
- 不自動操作 GPT Pro。
- 不把 live PubMed / 瀏覽器抓取放進 10:00 前阻塞流程。

GPT Pro、Notion、live search 都保留為 optional/manual。