# 連網選擇微信公眾號文章 Skill，並交付 HTML 報告

使用 SoyaOS Cloud、GitHub 即時搜尋和確定性品質門禁，產生可追溯的 Skill 選型單一 HTML。

這是一個真實可執行的 SoyaOS Cloud 最佳實務。你會從即時網路結果找到多個微信公眾號文章 Skill，比較優缺點並提出推薦，最後取得一個通過內容、結構、設計與安全檢查的單一 HTML。

## 要完成的需求

我們只調整原始需求的語序與標點，不改變範圍：

> 請連網搜尋可用於產生微信公眾號文章的 Skill，提供多個真實可用的候選方案，並分析各自的優點、缺點與適用情境；接著提出推薦方案、推薦理由和需要注意的取捨。最後請把完整結果交付為一個現代、美觀、結構清楚合理的單一 HTML 檔案。結束前請檢查該 HTML 能正常開啟，並確認內容、結構與設計均符合預期；如有異常，修正後再交付。

## 為什麼不能只送一次 Chat 請求

Cloud v0.2.0 的 `soya:starter` 是代管文字 Agent，不提供瀏覽器、Shell 或 Tool Calls。讓模型聲稱「已經連網」，或讓它自由產生未經檢查的大段 HTML，都不是真實案例。

這個 Recipe 明確分工：

1. 本機 Node.js 腳本透過 GitHub 公共 API 即時搜尋倉庫。
2. 腳本擷取候選 `SKILL.md`，記錄來源 URL、倉庫更新時間與搜尋時間。
3. SoyaOS Cloud 只在本次來源白名單內比較與推薦，回傳受約束的 JSON。
4. 版本化範本把 JSON 渲染成 HTML；模型無法注入標籤、腳本或樣式。
5. 四類機器門禁全部通過後，腳本才寫入最終檔案。

這是「用戶端 Recipe 編排 + Cloud 推理」，不是 Cloud 原生 Tool Calls。

## 準備工作

- 安裝 Node.js 22 或更新版本。
- 依照 [Cloud 快速上手](/zh-hant/docs/cloud-quickstart)登入 Developer Portal。
- 建立一個 API Key，並立即存入密碼管理器。用戶端把 Key 視為 opaque string，不需要也不應理解其格式。

取得原始碼：

```bash
git clone https://github.com/soyaos/cloud-recipes.git
cd cloud-recipes
```

## 執行案例

只在目前終端設定 Key，不要寫進程式或提交到 Git：

```bash
export SOYA_API_KEY='your-soyaos-api-key'
npm run run:wechat-skill-research
```

預設輸出為 `output/wechat-skill-research.html`。

公共 GitHub API 通常不需登入。遇到 `github_rate_limited` 時可稍後重試，或暫時設定最小權限的 `GITHUB_TOKEN`：

```bash
export GITHUB_TOKEN='your-github-token'
npm run run:wechat-skill-research
```

確認要覆寫既有產物時使用：

```bash
node recipes/wechat-skill-research/run.mjs --force
```

## 如何判定成功

成功日誌中的 `candidates` 不少於 3，`requestIds` 可在 Portal 查 Trace，`qualityGates` 必須同時包含 `content`、`structure`、`design` 與 `security`。

| 門禁 | 檢查內容 |
|---|---|
| 內容 | 候選數、優缺點、唯一推薦、來源連結與即時搜尋時間 |
| 結構 | doctype、語言、viewport、單一主內容、標題層級、必要章節與閉合文件 |
| 設計 | 內嵌設計變數、候選卡片、推薦強調、行動裝置響應式、鍵盤焦點與列印版面 |
| 安全 | 無腳本、iframe、表單、事件處理器、外部資源或 Key 洩漏 |

任一門禁失敗時，Recipe 會以非零狀態結束，不交付「看起來差不多」的檔案。

## 為什麼結果可能不同

候選來自即時 GitHub 搜尋。倉庫內容、更新時間與搜尋排序會變化，因此最佳實務保證的是可追溯流程與品質合同，不是固定候選名單。

## 隱私與配額

- GitHub 會收到搜尋詞和公開倉庫請求。
- 候選摘要與需求會送至 SoyaOS Cloud 的代管模型；Recipe 不會把正文寫入服務端儲存。
- 一次正常執行消耗一次 Cloud 請求；模型 JSON 無效時最多增加一次格式修復請求。

## 常見錯誤

- `missing_api_key`：目前終端沒有 `SOYA_API_KEY`。
- `cloud_http_error ... invalid_api_key`：Key 無效或已撤銷。
- `github_rate_limited`：等待限流重置，或暫時設定 `GITHUB_TOKEN`。
- `insufficient_live_candidates`：即時結果不足 3 個；不要用 fixture 冒充成功。
- `html_quality_failed`：依照失敗門禁修正後重跑。

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

---

Canonical HTML: https://soyaos.ai/zh-hant/docs/cloud-recipes/wechat-skill-research