SuperAPI AI 工具集

version-aware-recommendations

部署与运维

查看项目

更新于 11-02 16:14

技能介绍

Version-Aware Recommendations 是一项面向智能体的技能规范,用于约束版本与功能推荐行为。

用途:当需要推荐、安装、部署或锁定外部软件、库、工具版本,或列举外部软件功能、能力与需求时使用。典型场景包括:推荐语言运行时、框架、库或工具版本;执行 apt、pip、npm、docker、homebrew 等安装或部署;将依赖锁定到特定版本;比较软件选型;配置 CI/CD 工具链、基础镜像或 SDK 目标。项目内部版本(自有应用版本、内部 monorepo 包)不需要使用本技能。

核心规则:绝不根据内部记忆推荐版本或功能集,必须对照当前外部来源核实。模型对软件版本的记忆会在数月内过时,功能集、默认值、弃用项都会变化,因此每次版本推荐都须基于实时查询。

主要流程:

  1. 明确软件名称,即确切的包、镜像或工具。
  2. 检索官方来源,可使用网络搜索或直接阅读官方 URL;一手来源包括项目网站、GitHub/GitLab 发布页、Docker Hub、包仓库(PyPI、npm、crates.io、Maven)、Homebrew formula。
  3. 确定最新稳定版,过滤 alpha、beta、RC、pre-release 等标签。
  4. 核实当前文档,阅读所识别版本的现行文档,不依赖记忆。
  5. 带证据推荐,说明版本并附上找到该信息的来源链接,功能集取自当前文档。

文档查询方式:优先使用 context7 MCP 工具(resolve-library-id 与 query-docs),用于核实库或框架的功能、配置、默认值、代码示例与弃用项;版本号仍以包仓库和发布页为准。指定版本文档可使用版本固定 ID。若 resolve-library-id 三次尝试仍无合适匹配,则回退到通过阅读官方文档核实,并对关键功能声明对照项目发布说明。每个问题预算内各 context7 工具最多调用三次,多概念核实需合并查询或优先核实关键概念。

预发布例外:默认推荐稳定版。仅当所需功能或修复只存在于预发布版且为当前需求所必需,或项目近 12 个月无稳定发布、处于早期阶段或已废弃时,才可使用预发布版,并须明确说明适用例外、稳定版不适用的原因、所推荐的预发布版本及其风险。

版本锁定:锁定非最新版本时须记录理由,例如兼容性约束、已知回归、可复现性、EOL 或安全原因。不得静默锁定,锁定及其原因应体现在代码注释、锁文件或文档中。

常见陷阱:记忆漂移导致版本号过时;凭旧记忆编造功能;猜测文档 URL 导致 404;用 context7 查询版本号;将预发布版当作稳定版;静默锁定依赖;只核实版本却猜测功能;依赖博客、Stack Overflow 等可能过时的二手来源。

验证要点:推荐后确认版本号与官方来源一致并附链接;所列功能与当前文档一致;若为预发布版须说明例外与理由;若锁定版本须内联记录原因。