编写或审查 Elastic 集成包…

适用于构建或评审 Elastic integration package 的 manifest.yml 与 changelog.yml，并修复 elastic-package lint/check 报出的包元数据问题。

适用场景

解决思路

1. 将本技能及其 references 视为权威来源；参考 elastic/integrations 仓库时，如果现有集成使用与技能冲突的遗留模式，不要复制，始终按本技能规则执行。
2. 在根 manifest.yml 中设置 format_version 声明所遵循的 elastic/package-spec 版本；新包默认使用 `3.4.2`。
3. 使用支持实际使用功能的最低 format_version，不要盲目升级；无需要新功能而 bump 会迫使用户运行不必要的新 Kibana、无理由破坏向后兼容、并让功能依赖更难判断。
4. 只有使用某 spec 版本引入的功能时才 bump format_version，并按功能表选择最低版本：basic package structure 为 `1.0.0`；input-level variables 为 `2.0.0`；elasticsearch.privileges 为 `2.3.0`；routing_rules.yml 支持为 `2.9.0`；lifecycle 字段为 `3.0.0`；secret variables (`secret: true`) 为 `3.0.0`；elasticsearch.source_mode 为 `3.0.3`；var_groups 为 `3.6.1`；provider_permissions（Federated Identity IAM declarations）为 `3.6.4`。
5. 对 Federated Identity 做合理例外：声明 provider_permissions（通常也声明 var_groups）的包必须使用 format_version: `3.6.4`；该 bump 会启用 3.6.0+ pipeline validators；若 lint 暴露既有 pipeline 违规，先完成 pipeline hygiene。
6. 参考 references/format-version-features.md 获取完整 feature-to-version 表（含 3.6.0+ 新增），并按 references/manifest-rules.md 的审查流程执行。
7. 在根 manifest.yml 中设置 conditions.kibana.version；当前默认约束为 `^8.19.0 || ^9.1.0`；data stream manifest 不得设置自己的 conditions。
8. 当集成使用需要更新 agent 的功能（例如 v9.3.0 引入的 CEL functions）时，相应调整 constraints；对 CEL 功能做系统版本验证时参考 review-integration 技能。
9. 对 Federated Identity / use_cloud_connectors 做合理例外：设置 conditions.kibana.version 为 `^9.6.0` 且 conditions.agent.version 为 `^9.4.0`（或更高）；如果当前 Kibana constraint 仍覆盖了 `^9.6.0` 会丢弃的版本线，不要静默 bump，按 input-configurations -> references/federated-identity-aws.md 的 Floors and hygiene 升级处理。
10. 识别 Fleet variables 的四个层级：package level 为 manifest.yml 顶层 vars；policy template level 为 manifest.yml 中 policy_templates[].vars；input level 为 manifest.yml 中 policy_templates[].inputs[].vars；data stream level 为 data_stream/*/manifest.yml 中 streams[].vars。
11. 内层作用域声明的变量不得复用外层作用域变量名；这种 variable shadowing 会被 elastic-package validation 拒绝；完整规则和示例见 references/manifest-rules.md -> Variable shadowing。
12. 确保每个 Handlebars `{{var}}` 都在某个 manifest 中声明；未声明变量会静默解析为空字符串。Handlebars helpers（`{{#if}}`、`{{#each}}`、`{{#unless}}`、`{{#contains}}`）和内置变量（`{{data_stream.type}}`、`{{data_stream.dataset}}`、`{{data_stream.namespace}}`、`{{output}}`）豁免。
13. 当 data stream 使用 routing_rules.yml 时，在 data stream manifest 中声明 `elasticsearch.dynamic_dataset: true` 和 `elasticsearch.dynamic_namespace: true`。
14. 使用正确的 YAML 嵌套，不要用 dotted keys；把 `elasticsearch.dynamic_dataset` 写成字面 key 会创建单个扁平 key，而不是嵌套对象；应使用嵌套 `elasticsearch:` -> `dynamic_dataset:` 结构。
15. 完整 manifest 规则、正误示例和审查清单见 references/manifest-rules.md。
16. 维护 changelog.yml 为按版本分组的数组，较新版本放在顶部。
17. 每个 changelog 条目必须包含 description、type、link。
18. type 只允许 enhancement、bugfix、breaking-change；示例结构为 version 下 changes 数组，每项含 description、type、link。
19. 可直接编辑 changelog.yml，或使用 `elastic-package changelog add`（命令 flags 和 `--next patch|minor|major` 用法见 elastic-package-cli 技能）。
20. patch（`x.y.Z`）用于 bug fixes 和 low-risk fixes。
21. minor（`x.Y.z`）用于新内容：新 data streams、新 fields、新 features。
22. major（`X.y.z`）用于 breaking changes：既有集成的字段类型变更或移除、ECS mapping 冲突、会破坏既有 policies 的 required config/auth 变更、data stream 重构、会改变采集或归一化数据的默认行为变更。
23. 内部 metadata-only 且不改变用户所见交付物的变更不需要 version bump，也不需要 changelog entry：owner.github 重新分配、CODEOWNERS 更新、built package 之外的 CI/dev-tooling 文件；reviewers 不得对此类 diff 缺失 bump 提出 finding。
24. owner.type 变更属于已发布 package metadata，需要 minor bump。
25. 新增顶层 group: manifest 字段需要 patch bump + changelog entry。
26. bot 提交的 requires: dependency bumps 自带 patch bump 和 changelog entry；不要让人类重做或证明。
27. kibana.version constraint 更新不是 breaking changes。
28. changelog type calibration：仅当 diff 或条目自身描述显示可观察的兼容性或行为变化时才标记 type 问题，例如 dropped stack support、dataset/field rename 或 removal、field type change、default-behavior change、policy-breaking config moves；在 bugfix 与 enhancement 之间重新分桶、拆分或合并条目属于作者编辑判断，不应作为 review finding。
29. 避免把 changelog entry 加到错误版本下或没有放在最顶部。
30. 避免缺失或错误 link；link 必须是指向引入该变更的 PR URL（`https://github.com/elastic/integrations/pull/<n>`），不是 issue URL；elastic-package lint 只校验数字为正整数并拒绝 pull/0；开发时可使用 pull/99999 占位，合并前必须替换。Review tooling 识别占位形态（重复数字如 1 或 9999、zeros、99999、12345），CI 对任何不是本 PR 自己的编号都会失败，因此在替换前二者会持续报占位问题，这是预期的 pre-merge 行为。
31. 避免 manifest/package version bump 与 changelog intent 不一致。
32. 避免忘记把占位 link 换回真实 PR link。
33. PR 创建后更新 changelog link：从 `gh pr create` 输出或 PR URL 获取真实 PR number；在 changelog.yml 中把每个占位 link（`https://github.com/elastic/integrations/pull/99999`）替换为 `https://github.com/elastic/integrations/pull/<real-number>`；运行 `elastic-package lint` 确认 link 可验证；提交并推送到同一 PR 分支；合并版本中不得保留占位 link。
34. 将 elastic/package-spec 视为 package structure、manifest schema、validation rules 的上游权威；该仓库 spec/changelog.yml 记录每个 spec 版本新增了哪些功能。
35. package 必须在根 manifest.yml 中指定 format_version；format_version 为 x.y.z 的 package 必须对范围 [x.y.z, X.0.0) 的 specs 有效，其中 X = x + 1。
36. patch 版本可能增加更严格校验（例如 3.6.0 增加 pipeline tag 和 on_failure validation）；minor 版本增加新功能支持；major 版本保留给重大格式变更。
37. 参考 references/format-version-features.md 获取从 elastic/package-spec 整理的 feature-to-version 表。
38. references/manifest-rules.md 包含 format_version 选择、variable shadowing、Handlebars variable declarations、routing rules、YAML structure、severity-tagged review checklist 的完整规则。
39. references/changelog-patterns.md 包含 changelog entry patterns、semver rules、breaking-change checklist、CI examples。
40. references/format-version-features.md 包含从 elastic/package-spec 整理的 feature-to-version 表，含近期 spec additions。
41. references/var-groups-and-provider-permissions.md 包含 var_groups 和 provider_permissions 的 schema、floors、validators，以及转交 Federated Identity 流程。
42. 需要 package directory layout 和 required files 时，查阅 create-integration -> references/package-layout.md。
43. 需要 elastic-package CLI commands 和 troubleshooting 时，查阅 elastic-package-cli。
44. 需要在 AWS integration 上启用 Federated Identity（Cloud Connectors）时，查阅 input-configurations -> references/federated-identity-aws.md。

适用边界 · 注意事项

• 不要用于 package scaffolding 和目录布局，这类任务应使用 create-integration。
• 不要用于 ingest pipeline 设计、field mapping 与 ECS compliance、CEL programs、transform 配置；这些分别属于 ingest-pipelines、ecs-field-mappings、cel-programs、review-integration 的 transform-guide。
• 不要用于在 AWS package 上端到端启用 Federated Identity / Cloud Connectors，这类任务应转 input-configurations -> references/federated-identity-aws.md。