# Threads API 設定

這個 repo 可以用 Threads API keyword search 收集公開 Threads 上的 AI 主題貼文。

## GitHub Secret

到 GitHub repo 設定：

```text
Settings -> Secrets and variables -> Actions -> New repository secret
```

新增：

```text
THREADS_ACCESS_TOKEN
```

值填入你在 Meta Developer 後台產生的 Threads access token。

## 需要的權限

token 至少需要：

```text
threads_basic
threads_keyword_search
```

若要發布 Threads 貼文，token 還需要：

```text
threads_content_publish
```

## Token 有效期限

Threads user access token 預設是短效 token，通常只適合測試。正式自動發布建議交換成 long-lived token。

Meta 官方文件說明：

- 短效 Threads user access token 預設有效時間為 1 小時。
- 短效 token 可用 `th_exchange_token` 交換成 long-lived token。
- long-lived token 有效 60 天。
- long-lived token 至少建立滿 24 小時、尚未過期，且 app user 已授權 `threads_basic` 時，可用 `th_refresh_token` refresh。
- refresh 後會重新取得 60 天有效期。

本機檢查 token：

```bash
python3 scripts/refresh_threads_token.py --mode check
```

把短效 token 交換成 long-lived token：

```bash
python3 scripts/refresh_threads_token.py --mode exchange --write-env
```

這需要 `.env` 有：

```text
THREADS_ACCESS_TOKEN
THREADS_APP_SECRET
```

refresh long-lived token：

```bash
python3 scripts/refresh_threads_token.py --mode refresh --write-env
```

指令會更新 `.env` 裡的 `THREADS_ACCESS_TOKEN`，並寫出本機狀態檔 `.threads-token-status.json`。這個狀態檔已被 `.gitignore` 忽略，不會提交到 repo。

## 查詢關鍵字

目前 workflow 預設查：

```text
AI,人工智慧,OpenAI,LLM,AI Agent,Claude,Gemini,MCP
```

可在 `.github/workflows/fb-ai-digest.yml` 的 `THREADS_SEARCH_QUERIES` 調整。

如果指定日期查不到內容，腳本會額外用 `ThreadsAPI`、`Meta` 做不帶日期的診斷搜尋。若這些官方範例型關鍵字也都回傳 0，通常代表 token/app 還沒有足夠的 keyword search 可見範圍，需要檢查 App Review / Advanced Access。

## 輸出

每次執行會產生或更新：

- `daily/threads-YYYY-MM-DD.md`
- `raw/threads/YYYY-MM-DD.json`
- `index.md`

## 手動執行

GitHub repo 頁面：

```text
Actions -> Daily AI Knowledge Update -> Run workflow
```

可以不填日期，預設整理台北時間的前一天。

也可以填指定日期：

```text
2026-05-18
```