version-aware-recommendations

版本感知型推荐

核心原则：绝不要根据内部记忆推荐版本或功能集。务必通过当前的外部来源进行核实。

Agent 对软件版本的记忆会在数月内过时。功能集会变更，重大版本会发布，“最新稳定版”也会不再准确。每项版本推荐都必须以实时查询为依据。

适用场景

• 推荐语言运行时、框架、库或工具的版本
• 安装或部署软件（apt、pip、npm、docker、homebrew 等）
• 将依赖项固定到特定版本
• 列出外部软件的功能、能力或要求
• 比较软件选项（“我们应该使用哪个数据库？”）
• 设置 CI/CD 工具链、基础镜像或 SDK 目标版本

无需使用的场景： 项目内部版本（你自己的应用版本、内部单体仓库软件包）。

操作流程

1. 确定软件 — 指明确切的软件包、镜像或工具。
2. 搜索官方来源 — 使用 web_search 或通过 read 读取官方 URL。首选来源：项目网站、GitHub/GitLab 发布页面、Docker Hub、软件包注册表（PyPI、npm、crates.io、Maven）、Homebrew formula。
3. 确定最新稳定版 — 排除 alpha、beta、RC 和预发布标签。找出最新的稳定版版本号。
4. 核实当前文档 — 阅读与已确定版本对应的当前文档。功能、默认值和弃用情况都会变化；不要依赖记忆。使用下方的文档查询表。
5. 提供有依据的推荐 — 给出版本号，并附上查到该信息的来源链接。功能集应依据当前文档，而非记忆。

文档查询（步骤 4）

可用工具	用途	不要用于
context7 MCP 工具（以 resolve-library-id + query-docs 的形式提供，或设备路径 xd://mcp__context_context_resolve_library_id / xd://mcp__context_context_query_docs）	根据库或框架的官方文档核实功能、配置、默认值、代码示例和弃用情况	版本号——注册表和发布页面才是权威来源
通过 read 读取官方文档	context7 不可用或没有相关条目时的后备方案；核实版本和发布信息时始终使用	—

context7 可用时，文档查询步骤应优先使用它——不要猜测文档 URL：

1. 使用 {libraryName: "FastAPI", query: "<what you need to verify>"} 调用 resolve-library-id。选择名称完全匹配、来源声誉为 High/Medium 且代码片段最多的结果。
2. 使用 {libraryId: "/org/project", query: "<one specific topic>"} 调用 query-docs。参数名是 query，不是 topic。每次调用查询一个概念；不同概念应分别调用。
3. 要核实特定版本的文档，请使用固定版本的 ID（例如 /vercel/next.js/v14.3.0）——从 resolve-library-id 列出的版本中选择。
4. 如果 resolve-library-id 尝试不超过 3 次后仍未返回合适结果，则改用 read 读取官方文档，并通过项目自己的发布说明佐证关键功能声明。

每个问题的调用预算： 每个 context7 工具最多调用 3 次，超出后会报错。涉及多个概念的核实必须确保每个概念只调用一次 query-docs，且总调用次数不超过 3 次——仅当多个概念彼此相关时才合并查询，否则优先核实推荐所依赖的概念，其余内容通过 read 查阅官方文档佐证。

预发布版本例外

默认选择稳定版。 除非符合以下某项例外，否则不接受预发布版本（alpha、beta、RC、nightly、canary、-dev、-preview）：

• 必需功能缺失： 某项特定功能或错误修复仅存在于预发布版本中，且是当前需求所必需的。请说明具体功能，以及稳定版为何不够用。
• 近期没有稳定版： 项目在过去 12 个月内没有稳定版，或处于早期阶段／已被弃用。请说明项目的发布历史，以及预发布版为何是当前最佳选择。

如果符合例外，Agent 必须明确说明：

1. 符合哪项例外
2. 稳定版为何不合适
3. 推荐的预发布版本
4. 依赖预发布软件的风险

版本固定

固定到非最新版本时，须记录理由：

理由	示例
兼容性限制	“固定到 v3.2，因为 v4.0 不再支持 Node < 18”
已知回归问题	“避开 v2.7.1——上游问题 #1234 会导致我们的用例失效；v2.7.0 可正常使用”
可复现性	“固定到 v1.4.3，以匹配现有 CI 和生产环境”
生命周期结束／安全性	“固定到 v5.x LTS；v6.x 不支持我们的平台”

绝不可静默固定版本。 固定的版本及其理由必须明确写在代码注释、锁定文件或文档中。

易犯问题

• 记忆过时：“Python 3.11 是最新版”——错误；当前版本可能是 3.12 或 3.13。务必查询。
• **臆造功能：**根据过时的记忆罗列功能。请阅读当前文档。
• **猜测文档 URL：**编造文档路径（/tutorial/websockets/ → 404）并尝试其他变体。context7 可用时请查询；否则从文档索引或限定网站范围的搜索开始。
• **用 context7 查版本：**context7 索引的是文档，而非发布注册表。版本号仍应从 PyPI/npm/GitHub Releases/Docker Hub 获取。
• 把预发布版当作稳定版：“v2.0.0-rc.1”并非稳定版。除非符合例外，否则应过滤掉预发布版本。
• **静默固定版本：**固定 flask==2.2.0，却不说明原因。未来的 Agent（包括你自己）都不会知道这一限制。
• **验证不完整：**查询了版本，却靠猜测判断功能。版本和功能集都需要实时核实。
• **依赖二手来源：**博客文章、Stack Overflow 或第三方文章可能已经过时。务必向官方来源确认。

验证

提出建议后，请确认：

• 版本号与官方来源一致（附上链接）
• 列出的功能符合当前文档，而非凭记忆
• 如果是预发布版：说明例外情况及理由
• 如果固定了版本：在相关位置记录理由

继续前快速检查：

Is this version number from a live lookup? If no → stop, search.
Am I listing features from memory? If yes → stop, read docs.
Did I guess a documentation URL while context7 was available? If yes → stop, use query-docs.
Is this a pre-release without documented justification? If yes → stop, either find stable or document exception.
Is this pin documented with a reason? If no → stop, add rationale.