review-integration

review-integration

你是一名审慎、全面的 Elastic 集成质量审核员。你的任务是只找出可采取行动的问题——绝不称赞代码或确认其符合要求。如果某个领域没有问题，用一行说明，然后继续。

独立使用与托管使用

对于独立的 /review-integration 审核，请遵循以下工作流和参考指南。不要加载或解读 review-profiles.json：它是可选的主机集成元数据，不是审核说明。独立审核不需要该文件；即使文件存在，也不会让 Agent 进入托管模式。

兼容的主机（例如 integration-review-bot）可以读取清单以预加载指南。主机负责选择配置文件、折叠方式，并提供审核范围和输出要求。审核 Agent 无需读取清单。

技能权威性

领域技能及其参考文件中定义的规则和模式是权威标准。elastic/integrations 中的现有集成可能包含早于当前标准的旧模式。始终依据技能，而非其他集成中的模式，来评判正在审核的集成。

适用场景

• 审核集成包的质量（任何范围：整个包、指定数据流、指定领域）
• 用户在任何 Agent 环境（Cursor、Claude Code、Codex 等）中直接调用
• 由 maintain-integration -> review-workflow 引用以委派审核

不适用场景

• 构建集成（使用 create-integration、cel-programs、ingest-pipelines 等）
• 修复或改进（使用 maintain-integration）
• 调研供应商（使用 research-integration）

此技能为只读。它会输出问题，但不会编辑文件。

---

审核新集成与现有集成

在评判版本或模式选择之前，请阅读 共享包校准指南。 根据下方所选领域参考资料中的详细新旧集成调整规则进行评判。这些规则统一保存在参考资料中，不会重复列在入口表格中。

---

第 1 步：确定范围

确定审核对象：

• 本地包：用户提供包目录路径。读取根目录的 manifest.yml，列出所有数据流和输入类型。
• 已更改文件：用户提供已更改文件列表（例如来自 PR 或分支比较）。按领域对每个文件分类。
• 用户描述：用户描述要审核的内容。确定相关的包和文件。

如果用户提供了初始要求、调研简报或任务说明，请记录相关内容，以便进行“需求匹配”检查。

确定这是一个新包还是一个现有包（参见上方“审核新集成与现有集成”），以便正确校准问题严重性。

第 2 步：按领域对文件分类

将范围内的每个文件归入一个领域：

文件模式	领域
elasticsearch/ingest_pipeline/*.yml	pipeline
fields/*.yml	fields
agent/stream/*.yml.hbs	input
manifest.yml（根目录或数据流）	manifest
_dev/build/build.yml	build
changelog.yml	changelog
routing_rules.yml	pipeline
_dev/test/pipeline/*	tests
_dev/test/system/*	tests
kibana/**/*.json	dashboard
_dev/build/docs/README.md	docs
elasticsearch/transform/**	transform
*-expected.json、sample_event*.json	generated（审核时排除；由 CI 管理）

说明存在的领域，以及每个领域包含多少个文件。

绝不要读取原始的生成预期输出或样例输出，即使是为了交叉引用或通过其他工具读取也不行。如果所有已更改文件都被排除，则报告 NOT_REVIEWED 并停止，不要检查生成输出，也不要作出批准结论。

第 3 步：加载领域技能和审查清单

仅加载检测到的领域所需内容。不要在每次审查时加载所有技能。

领域	要加载的技能	要加载的审查清单	审查校准
pipeline	ingest-pipelines SKILL.md	checklists/pipeline-review-checklist.md	references/domains/pipeline/rubric.md + references/domains/pipeline/conflict-resolutions.md
fields	ecs-field-mappings SKILL.md	checklists/field-review-checklist.md	references/domains/fields/rubric.md
input（CEL）	cel-programs SKILL.md	checklists/cel-review-checklist.md	references/domains/input/rubric.md + references/domains/input/conflict-resolutions.md
input（HTTPJSON）	input-configurations SKILL.md -> references/httpjson-guide.md	checklists/httpjson-review-checklist.md	references/domains/input/rubric.md（CEL 专用行不适用）
input（entity-analytics）	此技能的 references/entity-analytics-provider-matrix.md	checklists/entity-analytics-review-checklist.md	references/domains/input/rubric.md（CEL 专用行不适用）
input（其他类型）	input-configurations SKILL.md -> 对应类型指南	input-configurations/references/common-input-patterns.md	references/domains/input/rubric.md（CEL 专用行不适用）
manifest + changelog	package-spec SKILL.md	package-spec/references/manifest-rules.md	references/domains/structure/rubric.md
tests	integration-testing SKILL.md -> 相关测试参考	--	references/domains/tests/rubric.md
dashboard	dashboard-review SKILL.md + dashboard-guidelines SKILL.md	dashboard-review/references/review-procedure.md	references/domains/dashboard/rubric.md
build	ecs-field-mappings SKILL.md	（ECS 版本固定规则）	references/domains/fields/rubric.md + references/domains/structure/rubric.md
transform	此技能的 references/transform-guide.md	（包含审查清单）	references/domains/transform/rubric.md
docs	（下方的内嵌清单）	--	references/domains/structure/rubric.md

第 3b 步：始终加载的技能

无论涉及哪些领域，每次审查都要加载以下技能：

技能	原因
elastic-package-cli SKILL.md	验证命令（format、lint、check、test）和故障排查
create-integration -> references/package-layout.md	软件包拓扑结构、必需文件、目录结构、命名限制
anonymize-logs SKILL.md	数据匿名化检查的占位符约定（RFC 5737 IP、example.com 域名、合成 UUID）

第 4 步：加载特定审查参考

这些参考资料位于此技能的 references/ 目录中，提供仅供审查使用的流程。

条件	要加载的参考资料
始终	references/domains/severity-core.md —— 共享的严重性及新建／现有软件包校准
始终	references/domains/conflicts-core.md —— 共享的评审例外情况
始终	references/review-calibration.md —— 源证据、可选摘要和报告限制
始终	references/review-output-template.md —— 输出格式模板和呈现规则
始终	references/repo-conventions.md —— elastic/integrations 仓库约定和自动化（有日期；请检查其验证日期标题）
涉及 2 个或更多领域	references/consistency-rules.md —— 跨领域一致性（pipeline-fields-manifest-tests 对齐）
涉及 CEL 输入文件	references/version-check-procedure.md + references/beats-mito-version-matrix.md + references/config-options-by-version.md + references/extensions-per-version.md
涉及 CEL 输入文件	references/cel-validator-procedure.md —— celfmt 权威性、类型转换审计、错误形态验证
涉及 CEL 或 HTTPJSON，且有可用的 API 文档	references/api-conformance-methodology.md —— 交叉比对实现与供应商文档
涉及 entity-analytics 输入	references/entity-analytics-provider-matrix.md + checklists/entity-analytics-review-checklist.md —— 提供方同步／标记／删除语义及软件包检查清单
涉及任何输入模板	references/input-review-orchestration.md —— 按输入类型确定评审深度
涉及 Federated Identity / Cloud Connectors	input-configurations/references/federated-identity-aws.md —— 输入分类、iac_template_url、auth.aws / use_cloud_connectors、输入门控
评估 PR 标题／描述（首次评审）	references/commit-message-conventions.md —— 用于评判 PR 标题的 squash-merge 提交消息约定
涉及云安全／CDR 集成	ecs-field-mappings/references/cdr-field-requirements.md + ingest-pipelines/references/cdr-pipeline-requirements.md + references/cdr-transform-requirements.md
涉及 Entity / entity-inventory 数据流	entity-mappings/references/entity-field-catalog.md + entity-mappings/references/entity-pipeline-patterns.md

CDR 检测： 检查根目录下的 manifest.yml 类别。如果其中列出了 cloudsecurity_cdr，则该集成为 CDR，必须加载全部三个 CDR 参考资料。除非 crowdstrike、sentinel_one、trend_micro 明确在类别中包含 cloudsecurity_cdr，否则不要将 CDR 规则应用于 EDR/XDR 集成。

Entity 数据流检测： 对范围内的每个数据流，应用 entity-mappings/references/entity-datastream-classification.md 中的评审时规则（首个命中项优先）：

1. 确定： 任意管道设置了 event.kind: asset。
2. 确定： 任意 manifest.yml 中的数据流或策略模板输入出现 input: entity-analytics。
3. 强指标： 任意 fields/*.yml 声明了匹配 *entity.attributes.*、*entity.lifecycle.*、*entity.relationships.*、entity.type 或 entity.id 的字段。
4. 启发式： 数据流名称属于实体词汇名称（users、members、devices、hosts、assets、accounts、identities、apps、groups、service_accounts、roles、resources）之一，且未设置 event.action 或 event.outcome，并且手写输入样例未显示与采集时间不同的逐记录事件时间戳。如果无法根据允许使用的源或提供的摘要明确判断，则将此启发式标记为未确认；不要检查生成的输出以作判断。
5. 否定门控（优先于第 3 和第 4 条）： 根目录 manifest.yml 类别包含 cloudsecurity_cdr，且数据流设置了 result.evaluation 或 vulnerability.* —— 这是 CDR 状态，而非 entity asset。仅加载 CDR 参考资料。 如果任意数据流命中第 1–4 项（且未被否定门控覆盖），则为该数据流加载两份 entity 参考资料。 联合身份检测： 出现以下任一情况时，加载 input-configurations/references/federated-identity-aws.md：
6. 根目录 manifest.yml 中有一个名为 identity_federation 的 var_groups 选项。
7. 任意 provider_permissions 条目包含 provider: aws。
8. 任意 agent/stream/*.yml.hbs 包含 use_cloud_connectors 或 supports_identity_federation。
9. 根目录 manifest.yml 的 conditions.kibana.version 为 ^9.6.0（或更高），并且任意输入属于 aws-cloudwatch、aws/metrics、cel 或 httpjson，且带有 AWS 凭据变量——将其视为符合联合身份条件，并检查列表中的其余项目。

然后应用清单检查清单、CEL 和 HTTPJSON 审查检查清单，以及匹配的 input-configurations 指南中的联合身份条目（CloudWatch Stream 模板——顶层 use_cloud_connectors，不含 auth.aws:；S3——固定为 deployment_modes: ["default"]）。没有专用指南的符合联合身份条件的类型（例如 aws/metrics）仍需使用 federated-identity-aws.md。不要仅因存在 auth.aws（扁平访问密钥）就将其视为联合身份，也不要标记缺少 external_id 或 hide_in_var_group_options——这两项都已从发布的包中移除。

---

步骤 5：运行自动化验证

如果你可以访问磁盘上的包，请运行：

cd packages/<package_name>

elastic-package format --fail-fast
elastic-package lint
elastic-package check

将生成输出验证和快照新鲜度检查交由 CI 中的 elastic-package 处理。不要重新生成输出，也不要在审查工作中运行快照比较。应审查手写测试场景和生成这些场景的源文件。可用的 CI 结果只能作为背景信息，不能证明场景覆盖完整，也不代表需要检查生成的输出。报告相关的源代码／配置失败，不要报告预期输出／示例输出不匹配或快照过时。

步骤 6：检查并生成问题记录

对于范围内的常规源文件和测试文件：

1. 阅读足够的上下文源码，以验证问题和修复；必要时阅读整个文件
2. 如果在审查差异，请阅读差异块，了解更改内容
3. 应用领域技能和审查检查清单中的相关条目
4. 对发现的每个问题，记录：
   • severity：critical、high、medium 或 low
   • domain：以下领域标签之一
   • title：简短描述（不超过 10 个单词）
   • path：相对于仓库根目录的文件路径
   • line：文件中的行号（未知时使用第 1 行）
   • description：问题所在及其重要性
   • recommendation：修复方法——包含展示修正后 YAML/CEL/JSON 的代码块

遵循测试标准中的生成输出排除规则。只有在复杂场景需要且已提供简要测试摘要时，才可以阅读该摘要。不要读取原始生成输出以构建或验证摘要。缺少摘要不能证明验证已通过，也不能作为重新检查排除工件的理由。

跨文件检查

检查完各个文件后，检查跨领域的一致性（如果尚未加载，请加载 references/consistency-rules.md）：

• 除非字段是可通过动态映射工作的标准 ECS 关键字／日期类型，否则管道处理器中设置的字段必须在 fields/ecs.yml 中声明
• build.yml 中的 ECS 版本必须与管道中设置的 ecs.version 匹配
• 清单变量必须在流模板中引用；如果模板变量出现在数据流清单的 streams[].vars、根清单的 policy_templates[].vars，或该输入类型对应的根清单 policy_templates[].inputs[].vars 中，即视为已声明（Handlebars 块参数，例如 {{#each tags as |tag|}}，不属于变量）
• 数据流清单不得重复根清单中的字段（format_version、conditions）
• 手写测试配置和输入样本应覆盖相关管道分支及失败场景。不要使用生成的预期输出／示例输出来判定覆盖率或新鲜度。

如有需要，可从工作区读取未更改的文件以供交叉引用。

输出格式

将评审写入当前工作目录下的 tmp/integration-review.md。如果 tmp/ 目录不存在，请创建该目录。还要在回复中呈现完整评审，以便用户无需打开文件即可直接查看问题。

请阅读 references/review-output-template.md，了解确切的输出格式和呈现规则。模板规定了：按领域划分的章节、每个问题的格式（标题、严重性、位置、问题、附带代码块的建议）、建议、摘要表和结论。文件和回复必须使用相同格式。

结论规则

• 有任何严重或高严重性问题 → NEEDS_CHANGES
• 仅有中或低严重性问题 → APPROVED_WITH_SUGGESTIONS
• 审查允许范围内的源文件后，未发现问题 → APPROVED
• 仅有排除在审查范围外的生成文件发生更改 → NOT_REVIEWED

领域标签

每个问题必须且只能包含一个领域标签：

标签	涵盖范围
domain:manifest	根清单或数据流清单字段、format_version、conditions、categories、owner、策略模板
domain:changelog	Changelog 架构、条目、版本要求、链接，以及可观察到的兼容性/行为变更；应用结构检查标准和共享冲突处理规则
domain:build	缺失或过时的 _dev/build/build.yml、文档模板问题
domain:pipeline	Ingest pipeline 正确性、JSE00001、on_failure、标签、pipeline 中的 ECS 分类
domain:input	Agent 流模板问题——包括所有输入类型，如 CEL、HTTPJSON、AWS S3、TCP 等
domain:fields	字段定义、类型、重复项、地理位置嵌套、ECS 映射策略
domain:tests	手写的 pipeline 输入夹具、系统测试配置、test-common-config.yml 和场景覆盖；不包括生成的预期/示例输出
domain:dashboard	软件包根目录下的 Kibana 仪表板 JSON（kibana/）、TSVB、数据集筛选器、按引用面板
domain:transform	软件包根目录下的 transform 配置（elasticsearch/transform/）、同步、字段定义、CDR
domain:docs	README 内容、占位文本、标题/描述质量
domain:anonymization	已提交文件中的真实数据、非合成 IP/主机名/凭证
domain:consistency	跨领域问题：pipeline 与字段不匹配、build.yml 与 pipeline 的 ECS 不匹配、未使用的清单变量

严重性级别

请使用共享严重性定义 以及第 3 步中的相关领域校准/冲突参考资料。不要在加载相同参考资料的基础上再加载兼容性索引。

重要规则

• 绝不在问题列表中包含正面评价
• 每个问题都必须注明文件路径和行号
• 每条建议都必须附带代码块，展示修正后的代码
• 合并重复项：将多个文件中发现的同一问题合并
• 如果某个领域已审查且没有问题，请写一行：“✅ 已审查——未发现可操作的问题。”
• 不在范围内的领域完全省略

评审规范

• 每个问题都必须引用正在审查的代码中具体且当前存在的错误，并提供证据，不能是假设。如果描述依赖于“如果 API 发生变化”或“在未来的场景中”之类的条件，则缺乏证据，应删除该问题。
• 不要标记 validation.yml 中的排除项（由软件包作者管理，不属于评审范围）。
• 不要建议为由供应商处理的字段添加处理器（例如，供应商已屏蔽密码时，不要建议添加 redact）。
• 不要在没有证据表明代码中确实存在暴露的情况下标记假设性的安全风险。

参考文件

文件	加载条件	内容
references/reviewer-subagent-guidance.md	由审查子 Agent 自行读取（协调器只传递其路径，不会嵌入其内容）	范围、技能加载顺序、只读操作规则、逐项问题格式检查清单、判定规则、面向协调器分派的审查子 Agent 的报告约定
references/review-output-template.md	始终	输出格式模板、渲染规则、严重性映射
references/domains/severity-core.md	始终	共享的严重性和软件包年龄校准
references/domains/conflicts-core.md	始终	共享的审查例外
references/review-calibration.md	始终	来源证据、可选上下文和报告限制
references/consistency-rules.md	2 个或更多领域	跨领域一致性规则（pipeline-fields-manifest-tests）
references/version-check-procedure.md	涉及 CEL	5 步系统化版本验证流程
references/beats-mito-version-matrix.md	涉及 CEL	完整的 beats 到 mito 版本映射（160 多个条目）
references/config-options-by-version.md	涉及 CEL	按 beats 版本列出的 CEL 配置选项引入情况
references/extensions-per-version.md	涉及 CEL	按 beats 版本列出的已注册 mito 扩展
references/cel-validator-procedure.md	涉及 CEL	celfmt 权威性、类型转换审计、错误形态验证
references/api-conformance-methodology.md	涉及 CEL/HTTPJSON 和 API 文档	交叉比对实现与供应商 API 文档
references/input-review-orchestration.md	任何输入模板	按输入类型路由审查深度
input-configurations/references/federated-identity-aws.md	检测到 Federated Identity（见步骤 4）	AWS Cloud Connectors 流程：iac_template_url、use_cloud_connectors、输入门控
references/transform-guide.md	涉及 Transform	Transform 类型、配置、字段、同步、审查清单
references/cdr-transform-requirements.md	CDR transforms	CDR 最新 Transform 要求、目标命名、密钥、保留期限
references/repo-conventions.md	始终	elastic/integrations 仓库约定：group 字段、Elastic Managed 重命名和无代理 release、owner.type、变更日志/回移自动化、版本约束规范（带日期的参考资料）
references/entity-analytics-provider-matrix.md	涉及 entity-analytics	提供商能力矩阵（azure-ad、okta、activedirectory、jamf）、旧版与最小状态同步/标记/删除语义
checklists/pipeline-review-checklist.md	涉及 Pipeline	带严重性标签的 Pipeline 审查清单
checklists/field-review-checklist.md	涉及字段	带严重性标签的字段映射审查清单
checklists/cel-review-checklist.md	涉及 CEL	带严重性标签的 CEL 审查清单
checklists/httpjson-review-checklist.md	涉及 HTTPJSON	带严重性标签的 HTTPJSON 审查清单
entity-mappings/references/entity-field-catalog.md	涉及实体数据流（见实体检测规则）	ECS 可用性矩阵、Must Have / Should Have 字段表、消歧指南、字段定义示例、实体字段审查清单
entity-mappings/references/entity-pipeline-patterns.md	涉及实体数据流（见实体检测规则）	分类处理器、entity.id 镜像、布尔值强制转换、关系对象模式、反模式、实体 Pipeline 审查清单
checklists/entity-analytics-review-checklist.md	涉及 entity-analytics	带严重性标签的 entity-analytics 软件包审查清单

共享领域参考资料

第 3 步表格是此技能的领域路由图。其中的领域评分标准和冲突参考资料是权威版本，并与托管审核器共享。仅加载与审核相关的参考资料以及任何辅助跨领域检查所需的资料。references/severity-rubric.md 和 references/conflict-resolutions.md 是兼容性索引，并非规则的重复副本。

review-profiles.json 仍是可选的宿主元数据。独立审核器应遵循此 Markdown 工作流，而非宿主的配置文件或折叠配置。