# 用官方来源生成依赖升级决策报告

实时核对 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/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
```

默认输出是：

```text
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/docs/cloud-recipes/dependency-upgrade-advisor