cncf-landscape

CNCF Landscape 技术选型

使用此技能，将能力或架构问题转化为有理有据的云原生技术候选清单。Landscape 是发现和获取证据的来源，而不是推荐引擎。

何时加载

当有人：

• 询问当前技术栈中尚未具备某项能力时，有哪些项目或工具可用；
• 想根据成熟度、类别、仓库指标、许可证或生态证据比较 CNCF 项目；
• 需要为架构决策、概念验证、技术雷达条目或自建与采购讨论制定候选清单；
• 需要在阅读项目文档或源代码仓库之前发现 CNCF 项目。

何时不使用

• 如需运维或配置某项特定技术，请加载其运维技能或查阅权威文档。
• 如需了解通用的采纳／暂缓治理流程，请加载 technology-radar，并仅将此技能用于候选项发现和证据收集。
• 如需进行广泛的平台架构、数据架构或 API 设计，且没有 Landscape 发现问题，请使用相应的方法论技能。
• 如需采购、合同、出口管制或许可建议，请将此技能中的许可证字段视为发现证据，并寻求合格的专业审查。

决策工作流

1. 搜索前先明确决策。 记录所需能力、工作负载、接口、运行时和拓扑、规模和 SLO、数据敏感性、部署模式、团队职责、运维技能、预算、时间线、许可证约束以及可接受的成熟度风险。区分硬性约束与偏好。如果用户未提供这些信息，请询问最少量的缺失信息，不要假装类别名称就是一项要求。
2. 从实时 API 中发现候选项。 从捆绑的查询工具开始：

   python3 scripts/landscape_query.py --help
   python3 scripts/landscape_query.py \
     --category "Observability and Analysis" \
     --subcategory Observability \
     --search tracing \
     --maturity graduated \
     --has-license --has-release \
     --sort stars --limit 10
   

   在选择端点、解释字段或诊断响应时，加载 references/api.md。使用 projects 数据源寻找技术候选项。仅将 members 或 end-users 用作生态背景信息；成员身份并不能说明产品质量。
3. 先应用硬性筛选条件。 按能力和类别筛选，然后根据用户明确提出的要求，按成熟度、许可证、仓库证据、部署约束或其他条件筛选。除非用户提出要求，否则不要将星标数、贡献者数量或 CNCF 成熟度隐式设为硬性要求。
4. 检查候选清单。 使用 projects/all.json 返回的 id 获取各项目的单条记录端点。记录 API 端点和检索时间。在对实现做出判断前，请阅读项目自身的文档、支持的部署方式、发布历史、源代码仓库、许可证以及安全／公告材料。
5. 比较适配度，而非知名度。 使用 references/decision-framework.md 和 references/output-template.md。区分：
   • 已观察到： Landscape 返回的字段，或已在项目文档中核实的陈述；
   • 推断得出： 有依据的推论，例如根据仓库活跃度推测生态覆盖范围；
   • 未知： 现有证据无法确定的要求。 切勿仅依据星标数、CNCF 成熟度、成员身份或生成的评分为项目排序。
6. 给出有条件的推荐。 只有针对已说明的约束，才指出最合适的方案。列出可信的替代方案、排除的候选项及排除原因、重大权衡、可逆性和迁移方面的注意事项，以及可能推翻该推荐的下一项实验。
7. 以验证计划收尾。 制定范围明确的概念验证，或进行文档／源代码审查，以验证用户实际使用的接口、工作负载、安全边界、可运维性、升级路径和故障模式。Landscape 记录可以指出需要调查的内容，但无法证明其已具备生产就绪性。

查询工具契约

scripts/landscape_query.py 是一个只读、非交互式的标准库客户端。它获取一个生成的 JSON 快照，应用本地筛选条件，并将 JSON 写入标准输出。诊断信息写入标准错误，发生故障时返回非零退出代码。

常用筛选条件包括 --search、--category、--subcategory、可重复使用的 --maturity、--license、--country、--oss-only、--has-license、--has-release、--min-stars、--min-contributors、--sort 和 --limit。默认结果数上限经过刻意限制；只有在需要完整结果集时，才使用 --limit 0。

查询工具不会为项目评分或提供推荐。请保留原始记录，并在决策文档中说明任何排名或权重。

可用脚本

此技能仅包含一个脚本；无需查找其他脚本。

脚本	用途	调用方式
scripts/landscape_query.py	用于访问公开 CNCF Landscape API 的只读标准库客户端。获取一个生成的 JSON 快照（--source projects、members 或 end-users），应用本地筛选条件，并将有结果数上限的 JSON 封装写入标准输出（诊断信息写入标准错误；发生故障时返回非零退出代码）。在决策工作流的发现阶段需要候选技术时运行此脚本；不确定适用哪些筛选条件时，请先运行 --help。	python3 scripts/landscape_query.py --category "Observability and Analysis" --search tracing --maturity graduated --limit 10

常用筛选条件包括 --search、--category、--subcategory、可重复使用的 --maturity、--license、--country、--oss-only、--has-license、--has-release、--min-stars、--min-contributors、--sort 和 --limit。默认结果数上限经过刻意限制；只有在需要完整结果集时，才使用 --limit 0。

证据规范

• CNCF 成熟度值描述的是项目在 CNCF 生命周期中的状态，而非项目的适用性、安全性、支持合同或运维简便性。
• 仓库星标数和贡献者人数是反映活跃度的大致信号，但存在快照时效性和仓库选择方面的注意事项。它们不代表采用情况、可靠性或支持保证。
• 仓库的许可证字段只是发现线索，并非法律结论。请核实具体仓库、版本、依赖项和组织政策。
• 最新发布版本字段无法证明发布质量、兼容性、补丁政策或支持期限。
• 类别和子类别标签有助于查找候选项目，但不能证明某个项目实现了所请求能力的所有部分。
• 如果 API 不可用或返回非 JSON 内容，请报告此限制。请勿凭记忆编造当前目录、数量或项目状态。

前置条件

• Python 3.8+，仅使用标准库；landscape_query.py 无需第三方软件包或 API 密钥。
• 实时查询需要能够通过 HTTPS 访问 landscape.cncf.io；必要时，可将 --base-url 指向镜像或离线测试服务。

限制

• 每次调用都会获取一个生成的 JSON 快照；结果反映的是该快照的时效性，而非仓库的实时状态。此工具无法替你读取项目文档或源代码仓库。
• 此工具不会为项目评分、排名或提供推荐：星标数、贡献者人数、CNCF 成熟度、成员身份和许可证字段都只是发现证据，且须遵守上述注意事项。
• 如果 API 不可用或返回非 JSON 内容，此工具会按设计明确报错；请勿用记忆中的目录数据替代其输出。

完成标准

当回复包含有结果数上限的候选集、用于生成该候选集的查询和来源证据、明确的硬性筛选条件和假设、观察所得与推断结果的区分、权衡与排除项、未解决的风险，以及具体的下一步验证措施时，即表示此技能已完成。如果 Landscape API 和决策所需的权威项目来源均不可用，请停止并报告阻碍。