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

实时核对 GitHub Release、CHANGELOG 与官方文档，用 SoyaOS Cloud 生成可追溯的依赖升级单文件 HTML。

这个 Recipe 解决一个常见但容易出错的问题：依赖有了新版本，到底应当立即升级、先测试再升级，还是暂缓？案例会实时核对官方资料，让 SoyaOS Cloud 分析变化和风险，再生成经过机器检查的单文件 HTML。

案例目标

默认案例比较 Developer Portal 当前使用的 wrangler 4.122.0 与 Cloudflare 官方发布的最新稳定版。最终报告必须回答：

当前版与最新版分别是什么；
新版本有哪些值得关注的变化；
风险、取舍和验证步骤是什么；
推荐结论及其理由是什么。

版本、发布时间、比较状态和来源 URL 均由代码确定，模型无权改写。

工作方式

Node.js 客户端读取 GitHub 官方 Release。
客户端抓取仓库内的官方 CHANGELOG 和 Cloudflare Wrangler 文档。
SoyaOS Cloud 只在已采集的三个来源内分析变化、风险与验证步骤。
关闭式 JSON schema 拒绝未知来源和自相矛盾的决策。
确定性模板生成 HTML；内容、结构、设计和安全门禁全部通过后才写入文件。

这仍是“客户端 Recipe 编排 + Cloud 推理”，并不依赖 Cloud v0.2.0 尚未提供的 Tool Calls。

准备和运行

安装 Node.js 22 或更高版本，并按 Cloud 快速上手创建 API Key。Key 是 opaque string，只放在环境变量中。

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

用于其他版本

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

在 GitHub 上编辑本页