# 把這份說明存成你的 skill

這份說明會隨網站更新。建議你把它存成自己的 skill（長期知識），並定期比對版本，有新版才重抓。

## 1. 讀完所有主題

先讀入口 `https://station-flow.staging.quanhox.com.tw/agent.md`，裡面列出每個主題的 `.md` 完整網址，逐一讀取。

## 2. 存成 Claude Code skill

建議目錄結構（其他 agent 框架請改成對應的長期記憶或知識檔格式）：

```
~/.claude/skills/station-flow/
├── SKILL.md          # 入口（下方範本）
├── overview.md       # 各主題原文，檔名用 slug
├── tasks.md
├── ...
└── version.json      # 抓取當下 version API 的完整回應
```

`SKILL.md` 範本：

```markdown
---
name: station-flow
description: 透過 Station Flow REST API 操作工作站流程：查詢與流轉任務（推進、退回、異常、跳回）、留言、認領、附件、專案檔案、流程設計與報表。觸發：要呼叫 Station Flow API、處理指派給我的任務、設計或調整流程、遇到 Station Flow API 錯誤時。
---

# Station Flow

- 網站：https://station-flow.staging.quanhox.com.tw
- API：https://station-flow.staging.quanhox.com.tw/api/v1（每個請求帶 `Authorization: Bearer <API key>` 與 `Accept: application/json`）
- 說明版本：<抓取時的 version>
- 版本檢查：https://station-flow.staging.quanhox.com.tw/api/v1/agent-docs/version

依需求讀同目錄的主題檔：overview（認證、回傳格式、錯誤碼）、tasks、attachments、projects、process-design、reports。
```

API key 不要寫進 skill 檔，請放在環境變數或你的密鑰管理機制。

## 3. 比對版本、有新版才重抓

```
GET https://station-flow.staging.quanhox.com.tw/api/v1/agent-docs/version
```

此端點公開、不需 API key，回應範例：

```json
{
  "version": "1.6.0",
  "updated_at": "2026-10-30",
  "entry": {
    "url": "https://station-flow.staging.quanhox.com.tw/agent.md",
    "sha256": "<agent.md 內容的 sha256>"
  },
  "topics": [
    {
      "slug": "overview",
      "title": "總覽：概念、認證與基本用法",
      "url": "https://station-flow.staging.quanhox.com.tw/agent/overview.md",
      "sha256": "<該主題 .md 內容的 sha256>",
      "updated_at": "2026-10-30"
    }
  ]
}
```

判斷方式：

1. `version` 與你存的不同 → 有更新。逐一比對 `topics[].sha256`，只重抓 sha256 變了的主題；新出現的 slug 要新增、消失的 slug 要刪除。入口 `agent.md`（主題清單與總覽）有沒有變，看 `entry.sha256`。
2. `version` 相同 → 不用動。
3. 也可以對單一主題或 `agent.md` 送 `If-None-Match`，回 `304 Not Modified` 代表沒變。值要照回應的 `ETag` 原樣帶，**含雙引號**；沒帶引號會被當成不同的 ETag，永遠回 200：

```bash
curl -s -o /dev/null -w '%{http_code}\n' "https://station-flow.staging.quanhox.com.tw/agent/overview.md" \
  -H 'If-None-Match: "<上次的 sha256>"'
```

重抓完更新 `version.json` 與 `SKILL.md` 裡的版本號。

## 什麼時候檢查

- 每週一次。
- 呼叫 API 遇到非預期錯誤（例如 404 端點不存在、422 欄位不符、410 功能已下線）時，先檢查版本再重試——很可能是說明已更新。