# 使用官方來源產生依賴升級決策報告

即時核對 GitHub Release、CHANGELOG 與官方文件，以 SoyaOS Cloud 產生可追溯的依賴升級單一 HTML。

這個 Recipe 回答一個常見問題：依賴出現新版本時，應該立即升級、先測試再升級，還是暫緩？案例會即時核對官方資料，交由 SoyaOS Cloud 分析變更和風險，再產生經過機器檢查的單一 HTML。

## 案例目標

預設案例比較 Developer Portal 使用的 `wrangler` `4.122.0` 與 Cloudflare 官方發佈的最新穩定版。最終報告必須列出目前版本、最新版本、重要變更、風險、取捨、驗證步驟和推薦結論。

版本、發佈時間、比較狀態和來源 URL 都由程式碼決定，模型不能改寫。

## 工作方式

1. Node.js 用戶端讀取 GitHub 官方 Release。
2. 用戶端擷取倉庫內的官方 CHANGELOG 和 Cloudflare Wrangler 文件。
3. SoyaOS Cloud 只在已收集的三個來源內分析變更、風險與驗證步驟。
4. 封閉式 JSON schema 拒絕未知來源和互相矛盾的決策。
5. 確定性模板產生 HTML；內容、結構、設計和安全閘門全部通過後才寫入檔案。

這是「用戶端 Recipe 編排 + Cloud 推理」，不依賴 Cloud v0.2.0 尚未提供的 Tool Calls。

## 準備和執行

安裝 Node.js 22 或更新版本，並依照 [Cloud 快速開始](/zh-hant/docs/cloud-quickstart)建立 API Key。Key 是 opaque string，只放在環境變數中。

```bash
git clone https://github.com/soyaos/cloud-recipes.git
cd cloud-recipes
export SOYA_API_KEY='your-soyaos-api-key'
npm run run:dependency-upgrade-advisor
```

預設輸出為 `output/dependency-upgrade-advisor.html`。

## 用於其他版本

```bash
node recipes/dependency-upgrade-advisor/run.mjs \
  --repository cloudflare/workers-sdk \
  --package wrangler \
  --current 4.122.0 \
  --changelog packages/wrangler/CHANGELOG.md \
  --docs-url https://developers.cloudflare.com/workers/wrangler/ \
  --output output/wrangler-upgrade.html
```

目前安全合約只允許 `developers.cloudflare.com` 文件網域，避免把任意 URL 變成 SSRF 入口；GitHub 來源必須屬於指定的公開倉庫。

## 成功標準

成功日誌必須包含三個官方來源、版本比較狀態、Cloud `requestIds` 和四類品質閘門。決策也必須符合版本事實：已是最新版時只能「無須升級」，有新版時不能「無須升級」，目前版本領先官方穩定版時只能「暫緩」。

HTML 不允許腳本、iframe、表單、外部樣式、字型或圖片。模型正文和遠端文件一律視為不可信輸入並轉義。

## 常見錯誤

- `missing_api_key`：目前終端沒有設定 `SOYA_API_KEY`。
- `release_not_found`：近期官方 Release 沒有符合的穩定套件版本。
- `unverified_source`：模型引用了本次未收集的 URL。
- `inconsistent_decision`：模型結論與確定的版本狀態衝突。
- `quality_gate_failed`：最終 HTML 未通過所有閘門。

原始碼與測試：[soyaos/cloud-recipes](https://github.com/soyaos/cloud-recipes)

---

Canonical HTML: https://soyaos.ai/zh-hant/docs/cloud-recipes/dependency-upgrade-advisor