package-spec

package-spec

技能权威性

本技能及其参考文件中定义的规则和模式是权威依据。查阅 elastic/integrations 仓库中的现有集成以供参考时，你可能会遇到与此处规范冲突的模式——许多集成包含早于当前标准的旧模式。**始终以本技能为准，不要遵循其他集成中的模式。**如果参考集成使用了已弃用或禁止的模式，请勿照搬。

适用场景

在任务涉及以下内容时使用本技能：

• 在根目录或数据流级别构建或审核 manifest.yml
• 添加或验证 changelog.yml 条目
• 选择正确的变更类型和语义化版本升级幅度
• 配置策略模板、输入和变量声明
• 声明 var_groups 或 provider_permissions（架构和最低版本）
• 调试清单或变更日志中的 elastic-package lint 或 elastic-package check 错误
• 审核包、策略模板、输入和数据流各级别的变量作用域
• 根据清单声明验证 Handlebars 模板变量
• 配置路由规则及其所需的清单标志
• 确定包功能所需的 format_version

不适用场景

• 包的脚手架和目录布局（create-integration）
• 在 AWS 包上端到端启用 Federated Identity / Cloud Connectors（input-configurations -> references/federated-identity-aws.md）
• 数据摄取管道设计（ingest-pipelines）
• 字段映射和 ECS 合规性（ecs-field-mappings）
• CEL 程序（cel-programs）
• 转换配置（参见 review-integration 技能的 references/transform-guide.md）

后续指引

关于包目录布局和必需文件，请参见 create-integration -> references/package-layout.md。关于 elastic-package CLI 命令和故障排查，请参见 elastic-package-cli。关于在 AWS 集成中启用 Federated Identity（Cloud Connectors），请参见 input-configurations -> references/federated-identity-aws.md。

---

format_version

manifest.yml 中的 format_version 字段声明包符合哪个 elastic/package-spec 版本。新包当前的默认值是 "3.4.2"。

使用支持包实际所用功能的最低版本，而不是最新可用的规范版本。无须新功能却升级版本：

• 会迫使用户运行不必要的新版本 Kibana
• 会无故破坏向后兼容性
• 会增加确定包所依赖功能的难度

只有在包使用了较新规范版本中引入的功能时才升级：

功能	最低 format_version
基本包结构	1.0.0
输入级变量	2.0.0
elasticsearch.privileges	2.3.0
支持 routing_rules.yml	2.9.0
lifecycle 字段	3.0.0
Secret 变量（secret: true）	3.0.0
elasticsearch.source_mode	3.0.3
var_groups	3.6.1
provider_permissions（Federated Identity IAM 声明）	3.6.4

**合理的例外情况——Federated Identity：**声明 provider_permissions（通常还包括 var_groups）的包必须使用 format_version: "3.6.4"。此升级会启用 3.6.0 及更高版本的管道验证器；如果 lint 暴露出之前就存在的违规项，请先处理管道规范问题。参见 references/var-groups-and-provider-permissions.md 和 input-configurations -> references/federated-identity-aws.md。

完整的功能与版本对应表（包括近期规范新增内容，3.6.0 及更高版本）请参见 references/format-version-features.md；审核流程请参见 references/manifest-rules.md。

---

conditions.kibana.version

当前的 默认 约束为 "^8.19.0 || ^9.1.0"。该设置仅位于根目录 manifest.yml 中——数据流清单不得设置自己的 conditions。

当集成使用需要更新版本 Agent 的功能时（例如，v9.3.0 中引入的 CEL 函数），必须相应调整约束。有关 CEL 功能的系统化版本验证，请参阅 review-integration 技能中的版本检查参考资料。

**合理例外——Federated Identity / use_cloud_connectors：**将 conditions.kibana.version 设为 "^9.6.0"，将 conditions.agent.version 设为 "^9.4.0"（或更高版本）。如果当前 Kibana 约束仍覆盖了 "^9.6.0" 会排除的某个版本系列，请勿静默升级——根据 input-configurations -> references/federated-identity-aws.md 中的 Floors and hygiene 升级处理。

---

变量作用域

Fleet 变量分为四个层级：

1. 包级别——manifest.yml 顶层的 vars:
2. 策略模板级别——manifest.yml 中 policy_templates[].vars: 下
3. 输入级别——manifest.yml 中 policy_templates[].inputs[].vars: 下
4. 数据流级别——data_stream/*/manifest.yml 中 streams[].vars: 下

内层作用域中声明的变量不得与外层作用域中的变量重名。这称为变量遮蔽，会被 elastic-package 验证拒绝。

完整规则、示例和常见模式请参阅 references/manifest-rules.md -> Variable shadowing。

---

清单规则（简要）

• 每个 Handlebars {{var}} 都必须在清单中声明——未声明的变量会静默解析为空字符串。Handlebars 帮助程序（{{#if}}、{{#each}}、{{#unless}}、{{#contains}}）和内置变量（{{data_stream.type}}、{{data_stream.dataset}}、{{data_stream.namespace}}、{{output}}）除外。

• 路由规则需要动态标志——当数据流使用 routing_rules.yml 时，数据流清单必须声明 elasticsearch.dynamic_dataset: true 和 elasticsearch.dynamic_namespace: true。

• 使用正确的 YAML 嵌套结构，而非带点号的键——elasticsearch.dynamic_dataset 作为字面键名会创建一个扁平键，而不是嵌套对象。应使用 elasticsearch: -> dynamic_dataset: 的嵌套结构。

• lint 通过并不能证明输入存在——输入的名称在所有出现的位置都只是未经验证的字符串：在集成包中，位于 policy_templates[].inputs[].type 和数据流的 streams[].input；在输入包中，位于 policy_templates[].input。不要将其与由枚举值限定的、名称相同但含义不同的数据流 type 字段混淆。请参阅 references/manifest-rules.md -> Input names are not validated。

完整规则、正确与错误示例以及审查清单请参阅 references/manifest-rules.md。

---

Changelog 架构

changelog.yml 是按版本分组的数组；较新的版本放在顶部：

- version: "1.2.0"
  changes:
    - description: Added example parsing for edge-case payloads.
      type: enhancement
      link: https://github.com/elastic/integrations/pull/12345

每个条目都必须包含 description、type 和 link。有效类型：enhancement、bugfix、breaking-change。

版本升级规则

• patch（x.y.Z）：错误修复和低风险修复
• minor（x.Y.z）：新增内容——新数据流、新字段、新功能
• major（X.y.z）：破坏性变更——现有集成中的字段类型变更或字段移除、ECS 映射冲突、会破坏现有策略的必需配置或身份验证变更、数据流结构调整、改变所收集或规范化数据的默认行为

无需更新版本的情况

不会改变面向用户发布内容的内部元数据变更，无需更新版本，也无需添加变更日志条目：重新指定 owner.github、更新 CODEOWNERS，以及构建包之外的 CI／开发工具文件。审查者不得因这类差异未更新版本而提出问题。

elastic/integrations 实践中的相关版本更新约定（日期详情见 review-integration/references/repo-conventions.md）：

• owner.type 变更属于已发布的包元数据，需更新 次要版本。
• 添加顶层 group: 清单字段，需更新 补丁版本并添加变更日志条目。
• 由机器人创建的 requires: 依赖项版本更新会自带补丁版本更新和变更日志条目；切勿要求人工重新处理或说明理由。
• kibana.version 约束更新不属于破坏性变更。

变更日志 type 的判定（供审查者参考）

仅当差异或条目自身的描述表明存在可观察到的兼容性或行为变更时，才标记条目的 type：移除对某个 Stack 的支持、重命名或移除数据集／字段、更改字段类型、更改默认行为、会破坏策略的配置迁移。在 bugfix 和 enhancement 之间重新归类，或拆分／合并条目，属于作者的编辑判断，不是审查问题。

添加变更日志条目

直接编辑 changelog.yml，或使用 elastic-package changelog add（命令行标志和 --next patch|minor|major 用法见 elastic-package-cli 技能）。

常见的变更日志问题

• 将条目添加到了错误的版本下，或未放在顶部
• 缺少 link 字段或链接有误——链接必须指向引入该变更的拉取请求 URL（https://github.com/elastic/integrations/pull/<n>），而非问题 URL。elastic-package lint 只会验证编号是否为正整数，并且会拒绝 pull/0；请使用真实的 PR 编号，或使用 pull/99999 作为开发占位符，并在合并前替换。审查工具能识别占位符形式（重复数字，如 1 或 9999、全零、99999、12345），CI 会对任何与该 PR 编号不一致的编号报错，因此在占位符被替换前，这两者都会持续标记该占位符——这是预期的合并前行为，并非误报
• 清单／包版本更新与变更日志意图不一致
• 忘记将占位符链接替换回真实链接——见下文

详细模式、破坏性变更检查清单和 CI 示例见 references/changelog-patterns.md。

创建 PR 后更新变更日志链接

变更日志的 link 字段必须指向引入该变更的 PR，但只有实际创建 PR 后才能知道真实 PR 编号——在此之前，所有步骤都必须使用上文问题中提到的 pull/99999 占位符。这一步很容易被遗漏，因为它发生在其余包工作完成之后，不在常规的构建／测试循环中。

PR 在 GitHub 上创建后：

1. 获取真实 PR 编号（从 gh pr create 的输出或 PR URL 中获取）。
2. 在 changelog.yml 中，将每个占位符链接 （https://github.com/elastic/integrations/pull/99999）替换为 https://github.com/elastic/integrations/pull/<real-number>。
3. 运行 elastic-package lint，确认链接现在通过验证。
4. 将更新提交并推送到同一个 PR 分支——合并的版本中不得保留占位符。

---

上游：elastic/package-spec

elastic/package-spec 仓库是软件包结构、清单架构和验证规则的上游权威来源。该仓库中的 spec/changelog.yml 记录了每个规范版本新增的功能。

package-spec 版本模型要点：

• 软件包必须在根目录的 manifest.yml 中指定 format_version
• format_version: x.y.z 的软件包必须符合版本范围 [x.y.z, X.0.0) 内的规范，其中 X = x + 1
• 补丁版本可能会增加更严格的验证规则（例如，3.6.0 增加了 pipeline 标签和 on_failure 验证）
• 次要版本会增加对新功能的支持
• 主要版本留作重大格式变更使用

请参阅 references/format-version-features.md，了解整理后的功能与版本对照表。

参考文件

文件	内容
references/manifest-rules.md	format_version 选择、变量覆盖、Handlebars 变量声明、路由规则、YAML 结构以及带严重程度标签的审查清单的完整规则
references/changelog-patterns.md	更新日志条目模式、语义化版本规则、破坏性变更检查清单、CI 示例
references/format-version-features.md	来源于 elastic/package-spec 的功能与版本对照表，包含近期新增的规范内容
references/var-groups-and-provider-permissions.md	var_groups 和 provider_permissions 的架构、下限、验证器；移交给 Federated Identity 流程