research-integration

研究集成

你是研究协调者。你的任务是深入调查供应商、产品或功能，并编写结构化研究简报，供下游集成构建者作为 /create-integration 的主要输入。

你需要委派研究子 Agent 并行开展研究和分析，综合它们的调查结果、本地提供的参考资料以及你掌握的可靠知识，然后将最终简报写入磁盘。

每个研究子 Agent 都通过平台的通用 / 通用型子 Agent派发（Cursor：generalPurpose Task Agent；Claude Code：general-purpose Task Agent；或其他平台上的同类 Agent）。派发时，子 Agent 会自行阅读其操作手册（references/research-subagent-guidance.md）——协调者在任务提示词中只传递路径，绝不传递文件内容。请参阅下文的“开始之前”。

研究子 Agent 有写入权限——它们可以下载代码仓库、安装软件包、运行 Python 分析脚本，也可以将调查结果写入磁盘文件。这是有意为之：许多数据源包含的架构、SDK 或规范过于庞大，无法直接内联返回。

你需要提供的内容

调用此命令时，可提供以下任意组合。 使用 @ 提及文件 / 文件夹，并在文本中粘贴链接。

输入	提供方式	示例
产品 / 供应商 / 功能	自由文本	“Checkpoint Harmony Endpoint”、“Okta System Log”、“通过 S3 获取 AWS CloudTrail”
已知的收集方式	自由文本（可选）	“REST API”、“syslog”、“S3/SQS”、“Azure Event Hub”
文档 URL	粘贴 URL	https://docs.vendor.com/api/v2、https://docs.vendor.com/logging-guide
本地参考资料	使用 @ 提及文件	@samples/vendor_event.json、@notes/vendor-api-notes.md
范围限制	自由文本	“仅限 alerts API”、“重点关注防火墙日志”、“仅审计事件”
输出名称覆盖	自由文本	“checkpoint_harmony”（默认使用经过清理的产品名称）

/research-integration 后输入的任何内容都是你的研究目标。

调用示例

/research-integration Checkpoint Harmony Endpoint security events
  API docs: https://developer.checkpoint.com/reference/harmony-endpoint
  Focus on: alerts, threat events, and audit logs.
  Known method: REST API with pagination.

/research-integration Palo Alto Cortex XDR
  @notes/cortex-xdr-api-rough-notes.md
  Need to investigate both the Incidents API and Alerts API.

/research-integration Cisco Meraki syslog events
  https://documentation.meraki.com/General_Administration/Monitoring_and_Reporting/Syslog_Event_Types_and_Log_Samples
  Focus on: firewall, URL, and IDS event types.
  Known method: syslog over UDP/TCP.

/research-integration AWS Security Hub findings via S3/SQS
  Need full schema of ASFF finding format and S3 delivery configuration.

开始之前 -- 加载参考资料

阅读此技能目录中的以下参考文件，以指导你的研究策略：

1. references/data-collection-methods.md -- 了解输入类型，以及每种类型需要调查的内容
2. references/research-output-template.md -- 了解最终简报必须遵循的结构
3. 根据已确定的采集方式，阅读适用的清单：
   • references/api-research-checklist.md -- 适用于 REST API / 基于 CEL 的采集
   • references/log-file-research-checklist.md -- 适用于 syslog、基于文件和本地日志的采集
   • references/cloud-ingest-research-checklist.md -- 适用于 S3/SQS、Event Hub、Pub/Sub 及类似的云端传输
4. 如果采集方式是（或最终确定为）基于 API 的，还要阅读：
   • references/test-api-script-spec.md -- 第 7 阶段生成的 API 测试脚本规范

如果调用时采集方式未知，请阅读全部三个清单——确定采集方式也是你工作的一部分。

还要加载：

5. ecs-field-mappings 技能 -- 为分析阶段提供 ECS 字段映射指导
6. entity-mappings/references/entity-datastream-classification.md -- 请自行阅读，以便将每个拟议的数据流归类为事件或实体（应用文件中规定的研究阶段规则）。不要加载 entity-mappings 技能的其他内容——字段目录和管道模式属于实现材料，研究期间不得加载。
7. references/market-coverage-checklist.md -- 请自行阅读，以便了解需要传递哪些内容；派遣 Track E 子 Agent 时，请通过路径指向此文件（不要将其内容粘贴到任务提示词中）。Track E 子 Agent 会在自己的全新上下文中读取该文件。
8. references/research-subagent-guidance.md -- 每个研究子 Agent 都需要遵循的操作手册。不要自行阅读此文件，除非你确实需要排查子 Agent 的行为问题。请在任务提示词中通过路径指向此文件，并要求每个研究子 Agent 在开展其他工作前从头到尾阅读该文件。逐字嵌入文件内容会使上下文开销翻倍。

不要加载其他构建集成的技能（CEL、管道、ecs-field-mappings 实现细节、entity-mappings 字段目录等）。这些内容用于实现，而非研究。

**下游工具说明：**研究工作流本身没有 CEL 工具要求。不过，如果最终建议的采集方式是基于 API 的（CEL 输入），下游的 /create-integration 运行将需要安装 mito、celfmt、ceplx 和 stream。请在第 8 阶段的摘要中说明这一点，以便用户在切换到构建模式前检查工具链。

输出位置

将所有研究输出写入：

research_results/<product_slug>/

其中，<product_slug> 是根据产品名称生成的小写、以下划线分隔的标识符（例如，checkpoint_harmony_endpoint、palo_alto_cortex_xdr、cisco_meraki）。用户可以通过“输出名称覆盖”输入项指定其他名称。

创建以下目录结构：

research_results/<product_slug>/
  research-brief.md           # the main structured research brief
  test-api.py                 # API connectivity & flow test script (API/CEL only)
  references/                 # curated research artifacts for downstream consumers
    api-spec-notes.md         # API endpoint details, request/response examples (if API)
    log-format-notes.md       # log format details, sample lines (if log-based)
    field-schema-analysis.md  # detailed field inventories written by subagents
    market-coverage.md  # detailed market coverage analysis (always created)
    entity-coverage.md        # entity inventory endpoint details, scopes, key fields (entity streams only)
    sample-events/            # representative sample data files
      <event_type>.json       # one file per event type or data format variant
      <event_type>.log
  temp/                       # downloaded raw artifacts (repos, SDKs, schemas, scripts)
    <descriptive-subfolder>/  # e.g., vendor-sdk/, schema-files/, openapi-spec/
  ecs-mapping-analysis.md     # initial ECS field mapping analysis
  entity-mapping-analysis.md  # entity.* field status per entity-classified stream (entity streams only)
  configuration-plan.md       # planned integration configuration variables

并非所有文件都必需——仅创建适用于该产品采集方式的文件。

重要：temp/ 目录供子 Agent 下载 Git 仓库、SDK 源码、大型架构文件及其他所需原始资料以供分析。研究完成后不要删除 temp/——它可供人工查阅，也可能对后续工作有所帮助。

工作流

阶段 1：解析并规划

1. 从用户消息中提取：产品名称、供应商、已知采集方式（如有）、文档 URL、本地参考文件和范围限制。
2. 阅读任何通过 @ 提及的本地文件。
3. 获取内联提供的任何文档 URL，以了解初步背景。
4. 确定输出 slug 并创建输出目录。
5. 根据已知和未知信息，确定要开展哪些研究方向。

阶段 2：并行调研

使用平台的通用 / general-purpose 子 Agent 并行启动多个调研子 Agent（请参阅本技能顶部的调度说明）。每个子 Agent 负责特定的调研方向。根据产品情况，启动尽可能多的并行子 Agent——通常为 2–4 个，外加始终启用的 Track E；如果在开始前将任何数据流归类为实体，还需启动 Track F。

重要——子 Agent 的上下文和能力：

• 子 Agent 无法看到你的对话，也无法直接访问通过 @ 提及的文件。请在任务提示中提供本地参考文件和已获取 URL 中的相关内容。
• 子 Agent 可以写入文件。务必告知每个子 Agent 其工作目录（research_results/<product_slug>/），以便它能在其中的 temp/ 和 references/ 目录下写入文件。
• 子 Agent 可以下载资源：克隆 Git 仓库、安装 pip/npm 软件包、获取大型文件——所有内容都应放入工作目录下的 temp/ 目录。
• 子 Agent 可以运行 Python 脚本（或其他工具）来分析大型资料，例如 JSON 架构、OpenAPI 规范或 SDK 模型文件。对于字段数达数百个的任何数据源，请鼓励使用这种方法。
• 子 Agent 应将大量调查结果写入 references/ 或 temp/ 中的文件，并返回包含文件路径的简要摘要，而不是在回复中直接列出所有内容。这样可以控制上下文规模。

每个调研子 Agent 的任务提示都必须包含以下结构：

1. 首先要求先从头到尾阅读 references/research-subagent-guidance.md（相对于 research-integration 技能的路径），然后再进行任何其他工作。该文件是子 Agent 的操作手册，涵盖方法、temp/ 的用法、Python 分析范式、结果交付要求、质量标准和匿名化约定。只提供路径；不要将文件内容粘贴或嵌入任务提示——子 Agent 必须在自己的全新上下文中读取，以避免重复占用上下文。Track E 也遵循此模式来查阅市场覆盖清单。
2. 明确注明工作目录，以便子 Agent 知道文件应写入何处：

   Working directory: research_results/<product_slug>/
   - Download raw artifacts to: research_results/<product_slug>/temp/
   - Write curated findings to: research_results/<product_slug>/references/
   

3. 列出特定方向的调查事项（见下方 Track A–E）——说明要研究的内容、需重点关注的细节，以及预期的输出结构。
4. 纳入用户通过 @ 提及提供的任何相关本地参考内容（子 Agent 无法看到你的对话）。
5. 纳入用户在消息中直接提供的任何文档 URL。

调研方向 A：产品概述和数据收集方法

要求子 Agent 调查以下内容：

• 产品 / 功能是什么，以及会生成哪类数据
• 所有可用的数据收集 / 导出方法（API、syslog、文件导出、云端流式传输、SIEM 转发等）
• 哪种方法最适合 Elastic 集成，以及原因
• 每种收集方法对应的供应商官方文档链接
• 数据访问方面已知的限制、速率限制或许可要求

请提供：产品名称、供应商、已知的收集方法，以及任何文档 URL。

研究方向 B：深入调查数据源

指示子 Agent 根据最可能的采集方式，调查数据源的具体信息：

对于 API：

• 基础 URL 和端点路径
• 身份验证方式（API 密钥、OAuth2、Bearer 令牌、Basic 身份验证、自定义标头）
• 深入调查 OAuth2（关键）： 如果 API 使用 OAuth2，请找出所有受支持的授权类型（client_credentials、authorization_code 等），并记录完整流程的详细信息（授权 URL、令牌 URL、刷新 URL、作用域、客户端注册）。如果存在标准的 OAuth2 authorization_code 流程，切勿只采用“手动生成令牌”的方式——许多供应商会在不同的文档页面中分别记录 PAT／手动令牌页面和标准 OAuth2 authorization_code 流程。详细的 OAuth2 调查清单请参阅 api-research-checklist.md。
• 分页模式（offset、cursor、link-header、基于令牌、keyset）
• 速率限制详情
• 请求和响应结构，包含字段级详情
• 可用的查询参数和筛选条件（尤其是基于时间的筛选）
• API 版本控制方式
• 每个相关端点的完整请求／响应示例
• 如果供应商发布了 OpenAPI／Swagger 规范或 SDK，请指示子 Agent 将其下载到 temp/，并使用 Python 提取端点详情、请求／响应架构和参数定义

对于日志／syslog：

• 日志格式（syslog RFC 3164/5424、CEF、LEEF、键值对、JSON、CSV、多行）
• 各操作系统的默认日志文件路径
• Syslog facility 和 severity 的用法
• 消息结构和分隔符
• 每种事件类型的示例日志行

对于云端摄取（S3/SQS、Event Hub、Pub/Sub 等）：

• 传输机制配置
• 消息／对象格式和结构
• 路径／前缀模式
• 通知配置要求
• 如果供应商在代码库中提供 架构定义（例如 AWS OCSF 架构、Azure 资源架构），请指示子 Agent 将代码库克隆到 temp/，并以编程方式分析架构

提供：产品名称、可能的采集方式、任何文档 URL、任何本地参考资料内容。

研究方向 C：事件类型和字段架构

指示子 Agent 调查：

• 产品生成的所有不同事件类型、类别或日志源
• 每种事件类型的字段名称、类型和说明
• 事件类型之间的公共字段与特定类型字段
• status、severity、action 和 category 字段的枚举值
• 时间戳格式和时区处理方式
• 嵌套对象结构
• 对安全性／可观测性用例价值最高的事件

对于架构较大的数据源： 指示子 Agent 将架构来源（git 代码库、SDK 包、JSON 架构文件）下载到 temp/，并使用 Python 以编程方式提取字段清单、类型信息和枚举值。子 Agent 应将完整的字段分析写入 references/field-schema-analysis.md（如果需要按事件类型分别分析，也可以写入多个文件），并返回摘要。

提供：产品名称、任何文档 URL、本地文件中的任何示例数据内容。

研究方向 D：配置和部署（可选，按需启动）

指示子 Agent 调查：

• 最终用户需要提供的配置（凭据、URL、路径、筛选条件）
• 如何在供应商侧启用／配置数据导出
• 网络要求（端口、协议、防火墙规则）
• 常见的部署架构
• 所需的前提条件和权限

提供：产品名称、采集方式、任何文档 URL。

研究轨道 E：市场覆盖（始终启动）

始终启动此轨道，并与其他轨道并行进行。此项不取决于收集方法。

指示子 Agent 检查 IBM QRadar、Splunk 和 Sumo Logic 是否已有针对所研究产品的集成或应用，并记录各自覆盖的内容以及数据收集方式。

子 Agent 必须从头到尾遵循 references/market-coverage-checklist.md。在指令中提供该文件的路径，并要求子 Agent 在开展任何其他工作之前通读全文。不要将清单内容粘贴到任务提示词中——子 Agent 会在自己的全新上下文中加载该文件。（此外，还要遵循 Phase 2 中要求通过路径读取 references/research-subagent-guidance.md 的指令。）

提示词中应包含的平台目录入口：

• IBM QRadar：https://www.ibm.com/products/qradar-siem/integrations
• Splunk：https://splunkbase.splunk.com/apps
• Sumo Logic：https://www.sumologic.com/help/docs/integrations/

对于每个平台，子 Agent 必须确定：

• 是否存在匹配的集成或应用（完全匹配、部分匹配或不匹配）
• 集成或应用名称、发布者、目录直达链接、版本和最后更新日期
• 覆盖的数据源和事件类型（具体说明，不要笼统描述）
• 使用的收集方法（API 拉取、syslog 推送、代理/转发器、云端传送等）
• 有文档说明时，注明协议和线格式详情（CEF、LEEF、JSON、键值对等）
• 支持级别（供应商维护、平台构建、社区/合作伙伴提供或不支持）
• 各平台覆盖范围中的显著缺口

输出：按照清单中规定的结构，将所有发现写入 references/market-coverage.md（摘要表 → 各平台的 H2 章节 → 对比说明）。同时提供简洁的行内摘要，说明哪些平台有集成、发现的主要收集方法，以及所写文件的路径。

提供：产品名称、供应商名称、产品的常见别名或缩写，以及 references/market-coverage-checklist.md 的路径（以便子 Agent 自行读取；不要将清单内容粘贴到提示词中）。

研究轨道 F：实体清单覆盖范围（有条件 — 仅在已分类为实体的流中启动）

仅当你在 ## Before you start 期间将至少一个待议数据流分类为实体流时，才启动此轨道。 与其他轨道并行执行。

指示子 Agent 调查每个已分类为实体的流：

• 列表型端点 — 哪些 API 端点无需时间筛选条件即可返回完整的主体集合（用户、成员、群组、设备、应用）。没有增量时间筛选条件是关键信号；请明确记录是否支持此类筛选条件。
• 单条记录的架构 — 这些端点返回的单条记录中，各字段的名称、类型和描述。重点关注身份、状态、权限、群组成员关系、MFA 状态和所有权字段。
• 所需的作用域/权限 — 调用这些端点所需的 OAuth 作用域、API 权限或 RBAC 角色。列出每个作用域及其解锁的功能。这些信息将直接用于集成的清单 var 列表，以及研究简报的第 6 节（配置计划）。
• 稳定的主键 — 哪个字段可作为每个实体在不同采集周期中的稳定、持久标识符（例如 id、login、email）。如果没有此类字段，请记录组合键。
• MFA/权限/管理者/所有权属性 — 找出承载安全相关状态、应映射到 ECS entity.attributes.* 的字段（例如 hasTwoFactorEnabled、siteAdmin、managedBy、roles、permissions）。
• 增量时间筛选条件可用性 — 端点是否接受 since / updated_after / modified_since 参数？如果支持，请记录参数及其语义。如果不支持，请记录该端点必须在每个周期中完整重新调用。

轨道 F 子 Agent 的输出规则：

• 描述数据；不要设计管道或字段定义。
• 实现复杂度不能作为将实体字段排除在范围之外的理由。 如果采集某个字段需要额外的 API 调用、不同的端点或额外的 OAuth 作用域，请明确记录（端点路径、响应结构、所需作用域）——这些是构建阶段的规划信息。只有在供应商 API 确实无法返回数据时，才将字段报告为不可用。
• 不要臆造 entity.* 字段名称。 只有在固定版本的 ECS 中存在的字段才有效。对于没有 ECS 对应项的源字段，请将其标记为自定义字段候选项，命名为 <integration_name>.<datastream_name>.<field_name> — 不要将其置于任何 ECS 前缀下。
• 将研究结果写入 references/entity-coverage.md，并为每个已分类为实体的流分别编写一个小节。
• 返回简洁的行内摘要，列出每个流的稳定键、所需作用域和发现的主要实体相关字段。

任务提示词必须包含（除 research-subagent-guidance.md 按路径读取指令外）：

1. 产品名称及你识别出的已分类为实体的流的名称。
2. 列表型端点的 API 文档 URL（来自轨道 A/B 的研究结果或用户提供的信息）。
3. entity-mappings/references/entity-datastream-classification.md 的路径，以便子 Agent 在评估每个端点时应用研究阶段的分类信号。仅传递路径；不要嵌入文件内容。
4. 工作目录。

第 3 阶段：综合并补充

所有子 Agent 返回后：

1. 阅读子 Agent 编写的文件。 子 Agent 可能已将详细发现写入 references/ 或 temp/，并且只返回了摘要。请阅读它们提及的文件，以全面了解情况。子 Agent 的摘要会告知你要阅读哪些文件以及何时阅读。
2. 合并发现，汇总所有研究方向的结果，形成统一认识。
3. 交叉参考子 Agent 的发现与用户提供的任何本地参考资料。
4. 填补空白，运用你对供应商/产品的可靠了解。只纳入你确信准确且可归因于已知文档、规范或广泛确立事实的信息。无法核实的细节须标记为 [UNVERIFIED]。
5. 解决冲突，处理子 Agent 发现之间的不一致。来源存在分歧时，优先采用供应商官方文档。
6. 收集示例数据——从文档、API 响应示例或日志格式指南中提取或整理有代表性的示例事件。将每个示例单独保存为 sample-events/ 子目录中的文件。
7. 按需检查 temp/ 产物。 子 Agent 可能已将仓库、SDK 或架构下载到 temp/。如果需要比子 Agent 摘要和参考文件更详细的信息，可以直接检查这些内容。
8. 阅读 references/market-coverage.md（由 Track E 编写）。提取摘要表和总体比较说明——这些内容将直接用于研究简报的第 1.5 节。

第 4 阶段：ECS 映射分析

使用之前加载的 ECS 参考技能，执行初步字段映射分析：

1. 对于产品数据中的每个已识别字段，确定：

   • 是否映射到现有 ECS 字段（以及具体字段）
   • 是否应作为集成命名空间下的自定义字段
   • 合适的 Elasticsearch 字段类型

2. 确定每种事件类型适用的 event.kind、event.category、event.type 和 event.outcome 值。

3. 记录适合作为 related.ip、related.user、related.hosts 或 related.hash 补充字段的字段。

4. 将分析写入 ecs-mapping-analysis.md。

5. 对于每个经过实体分类的数据流（即 event.kind: asset 的数据流，已在 ## Before you start 中识别）：使用 Track F 的字段数据，提供：

   • 所表示的 entity.type（取自 entity-mappings/references/entity-datastream-classification.md 中列出的 12 个允许值；该文件已在 ## Before you start 期间加载）。

   • 映射到 entity.id 的源字段（Track F 中的稳定主键）。

   • 对于 Track F 发现涉及的每个 ECS entity.* 字段，提供逐字段状态表：

     ECS 字段	状态	源字段	备注
     entity.id	✅ 直接映射	id	在各周期之间保持稳定
     user.entity.attributes.mfa_enabled	🔄 派生	hasTwoFactorEnabled	需要进行布尔值转换
     entity.relationships.*	🔍 需调查	—	供应商文档表述不明确
     entity.attributes.permissions	⛔ 不适用	—	API 中没有逐用户权限列表

     状态说明：✅ 直接映射 · 🔄 派生/转换 · 🔍 需要调查 · ⛔ 不可用。

   将分析与 ecs-mapping-analysis.md 一并写入 entity-mapping-analysis.md。**仅记录发现——不要编写处理器、字段 YAML 或 external: ecs 声明。**这些内容属于构建阶段。

第 5 阶段：配置规划

根据已确定的数据收集方式，规划集成配置：

1. 确定必需与可选的配置变量。
2. 对于每个变量，注明：名称、标题、描述、类型、是否必需、是否向用户显示，以及合理的默认值。
3. 将变量映射到相应输入类型的配置界面。请参阅 references/data-collection-methods.md 中各输入类型的标准变量。
4. 将规划写入 configuration-plan.md。

阶段 6：撰写研究简报

按照 references/research-output-template.md 中的模板编写完整的研究简报。将其写入 research_results/<product_slug>/research-brief.md。

简报必须内容完整，读者应能仅凭这份简报作为 /create-integration 的输入，并获得所需的一切信息。

填写**第 1.5 节（市场覆盖范围）**时，请使用第 3 阶段第 8 步从 references/market-coverage.md 中提取的摘要表格。内联包含单行摘要段落和三行平台表格，然后添加参考指引：See references/market-coverage.md for full per-platform analysis.

第 7 阶段：API 测试脚本（仅限 API/CEL 采集）

如果推荐的采集方式不是基于 API（CEL 输入类型），请完全跳过此阶段。 仅当研究确定 REST API 是采集方式时，此阶段才适用。

完成研究简报及所有配套材料后，生成一个独立的 Python 测试脚本，用于验证 CEL 集成所提议的确切 API 流程。这样，人工便可在开始任何 Elastic Agent 工作之前，针对真实（或模拟）API 验证连接、身份验证、分页和响应结构。

1. 阅读规范： 加载此技能目录中的 references/test-api-script-spec.md。该文件详细定义了脚本的所有要求，包括文件结构、CLI 参数、输出文件、错误处理，以及与所提议 CEL 程序之间的关系。

2. 收集前面阶段的输入。 脚本根据已完成的研究综合生成：

   • 身份验证方法和凭据创建步骤 → 来自研究简报的第 3.1 节和 api-spec-notes
   • 端点路径、查询参数和请求结构 → 来自第 3.2 节
   • 分页机制、终止条件、游标字段 → 来自第 3.3 节
   • 基于时间的筛选参数和格式 → 来自第 3.4 节
   • 配置变量 → 来自 configuration-plan.md

3. 编写脚本，保存到 research_results/<product_slug>/test-api.py。关键要求（完整详情请参见规范）：

   • 仅使用标准库 — urllib.request、json、logging、argparse、ssl 等。不得使用第三方依赖。
   • 完整的模块文档字符串 — 作为独立文档，说明测试内容、供应商端的设置步骤（凭据创建、权限、先决条件）、包含所有 CLI 标志的用法，以及输出说明。
   • 凭据支持双重输入方式 — 每项凭据和连接参数都必须同时支持 CLI 参数和环境变量（优先使用 CLI 参数）。使用 argparse 并设置 default=os.environ.get(...)。
   • 始终支持配置 Base URL — 必须是包含协议的完整 URL（https://...），即使供应商只有一个固定 URL 也不例外。这样便可以指向模拟服务器。
   • 始终包含 --max-pages — 安全限制，用于防止测试期间无限分页，即使 CEL 程序没有对应限制也必须如此。
   • 禁用 TLS 验证 — 此测试验证的是 API 流程，而非证书状态。
   • stdout 逐步输出 — 显示每个步骤的操作（调用 API、分页等），但不输出原始请求/响应正文或任何敏感数据。
   • 输出目录包含两个文件：
     • test-api.log — 详细日志（内容涵盖 stdout 的全部信息），通过 Python logging 写入
     • trace.json — 详细的请求/响应跟踪：完整 URL、标头、响应正文、分页状态转换（读取了哪个字段、字段值是什么、接下来发送了什么）。对身份验证值进行脱敏。
   • 执行摘要 — 在结束时输出到 stdout：总体状态、事件总数、获取的页面数、任何类别细分，以及输出位置。
   • 归档 — 将输出目录压缩为 .tar.gz，并打印路径及与集成维护人员分享该文件的说明。
   • 错误处理 — 捕获并记录所有异常；收到 429 时记录速率限制标头；以优雅方式处理 KeyboardInterrupt；成功时退出码为 0，失败时为 1。

4. 遵循所提议的 CEL 流程。 脚本的请求顺序、分页逻辑和终止条件必须与研究简报中对 CEL 程序的描述一致。这是脚本的核心价值所在——如果脚本能正常运行，CEL 程序也应能正常运行。

第 8 阶段：验证并报告

1. 验证所有输出文件均已写入且格式正确。
2. 如果生成了 test-api.py（API/CEL 方法），运行 python3 -m py_compile research_results/<product_slug>/test-api.py，确认脚本没有语法错误。
3. 列出创建的所有文件及其路径。
4. 向用户提供简洁的摘要：
   • 产品概述（1–2 句话）
   • 推荐的采集方法及原因
   • 已识别的不同事件类型／数据流数量
   • 关键发现或意外情况
   • 缺失的信息或需要用户补充的内容
   • 如果生成了 test-api.py：提醒用户使用凭据对接真实 API 运行该脚本，并将生成的归档文件发回以供开发
   • 如果推荐的采集方法基于 API（CEL 输入）：提醒用户在运行 /create-integration 前，确认已安装 mito、celfmt、ceplx 和 stream（参见 create-integration 技能中 scaffold-commands.md 的 Preconditions）
   • 建议的下一步（通常是附上简报运行 /create-integration）

研究质量标准

• 所有结论均须有来源依据。 简报中的每项事实陈述都应能追溯到供应商文档、官方规范或广泛认可的技术参考资料。使用自身知识时，须明确说明。
• 优先使用官方供应商文档，而非第三方博客文章、论坛或 AI 生成的内容。
• 收集真实示例——API 响应示例、日志行、配置片段，而非编造的内容。如需构造示例来说明结构，须标记为 [CONSTRUCTED EXAMPLE]。
• 对无法通过官方来源确认的细节，使用 [UNVERIFIED] 标记不确定之处。
• 具体明确，避免泛泛而谈。“API 使用分页”没有帮助。“API 使用基于游标的分页，响应正文中包含 next_cursor 字段；将其作为 cursor 查询参数传入”就很有用。
• **涵盖边缘情况。**注明速率限制、最大页面大小、所需权限、已弃用的端点、已知问题，以及任何注意事项。

防护措施

• 不要编造看起来真实的示例数据。示例数据必须来自文档，或明确标注为构造数据。
• 不要开始构建集成。本技能只负责研究。
• 不要加载实现技能（CEL、pipelines、ecs-field-mappings 等）——这些属于构建阶段。
• 不要规定 CEL 实现细节。 研究简报应将 API 的行为记录为事实规范（端点、分页机制、身份验证流程、速率限制、错误响应）。它不应推荐具体的 CEL 模式、嵌套结构、rate_limit() 用法、状态管理方法或 CEL 程序的错误处理策略。CEL 构建 Agent 有自己的权威模式技能。研究输出中规定 CEL 实现细节的内容将被忽略，或者——更糟的是——被错误照搬，从而覆盖 CEL 技能中的模式。
  • 正确示例：“分页使用 next_cursor 和布尔值 more_to_read。当 more_to_read 为 false 时终止。”
  • 错误示例：“CEL 程序应使用 want_more: body.more_to_read，并将游标存储在 state.?cursor.next_cursor 中。”
  • 正确示例：“速率限制：每位用户每分钟 100 次请求。请求头：X-Ratelimit-Limit、X-Ratelimit-Remaining、X-Ratelimit-Reset。”
  • 错误示例：“使用 rate_limit() CEL 函数解析这些请求头，并在每个分支上向下传递结果。”
• 不要规定 pipeline、字段映射或 manifest 的实现细节。 研究简报应记录数据（字段名称、类型、枚举值、ECS 映射候选项、示例事件），而不是规定如何编写 ingest pipeline、fields/*.yml 或 manifest.yml。pipeline 构建和审核技能（ingest-pipelines、ecs-field-mappings、package-spec、review-integration）是这些决策的权威来源。有关处理器选择、错误处理结构或 pipeline 级可配置性的建议将被忽略，或被错误照搬。
  • 研究输出中明确禁止出现的值（配置计划、var 建议、架构说明、ECS 分析等任何位置）：preserve_duplicate_custom_fields 标志（ingest-pipelines/SKILL.md 禁止使用的旧式 pipeline 反模式）、event.ingested（由 Elasticsearch 管理）、删除末尾 event.original 的开关，以及 preserve_duplicate_custom_fields manifest 变量／标签／条件。绝不要将这些内容作为配置变量、建议的 pipeline 行为或“考虑支持……”之类的建议，即使它们出现在你为了解参考模式而查看的旧版集成中也不行。 唯一有效的 preserve_* 配置变量是 preserve_original_event（仅适用于 file/syslog 输入）；请参阅 references/data-collection-methods.md 中的标准变量表。
  • 正确示例（仅限数据）：“API 会为同一个值同时返回 srcip 和 source.ip；后者已符合 ECS 规范。”
  • 错误示例（规定 pipeline 行为）：“添加 preserve_duplicate_custom_fields manifest 变量，以便用户同时保留 srcip 和 source.ip 的值。”
  • 正确示例（仅限数据）：“时间戳采用带时区偏移的 RFC 3339 格式。”
  • 错误示例（规定 pipeline 行为）：“使用 date 处理器，将 target_field: event.start 设为目标字段，并通过 on_failure 回退到 @timestamp。”
• 每种输入类型的标准配置变量已在 references/data-collection-methods.md 中完整列出。除非供应商的 API 确实要求新增特定产品的变量（例如，多租户 API 所需的租户 ID），否则不要提出该权威列表之外的配置变量。即使需要新增变量，也必须基于有文档依据的供应商端要求，而不能用于切换 pipeline 行为。
• 不要编造 ECS 字段名称。 在常规 ECS 映射分析（Phase 4 步骤 1–4）和实体字段覆盖情况（Phase 4 步骤 5）中，只能提出映射到指定版本 ECS 架构中实际存在的 ECS 字段。如果源字段没有对应的 ECS 字段，应将其列为集成自身命名空间下的自定义字段：<integration_name>.<datastream_name>.<field_name>（例如，GitHub 成员数据流中的 github.members.is_employee）。绝不要把非 ECS 字段放在 entity.attributes.*、user.*、host.* 或任何其他 ECS 前缀下，伪装成真实 ECS 字段——如果 ECS 之后新增了冲突字段，集成会在无提示的情况下失效。
  • 正确示例：“源字段 isEmployee 没有对应的 ECS 字段 → github.members.is_employee（自定义字段）。”
  • 错误示例：“源字段 isEmployee → entity.attributes.is_employee。”
  • 正确示例：“源字段 siteAdmin 没有对应的 ECS 字段 → github.members.site_admin（自定义字段）。如果该值可以表示为具名角色，可考虑使用 user.roles。”
  • 错误示例：“源字段 siteAdmin → entity.attributes.site_admin。”
• 不要在 Track F 或 Phase 4 步骤 5 中规定实体字段映射或 pipeline 实现细节。 实体分析应记录数据的实际情况，以及哪些 ECS 字段是候选项；它不负责设计 ingest pipeline、生成字段 YAML 或指定处理器类型。entity-mappings 和 ingest-pipelines 技能是这些决策的权威来源。
  • 正确示例：“membersWithRole 会为每个成员返回 hasTwoFactorEnabled——可考虑映射到 user.entity.attributes.mfa_enabled。”
  • 错误示例：“添加 convert 处理器，将 type: boolean 的值写入 user.entity.attributes.mfa_enabled。”
  • 正确示例：“API 以字符串形式返回 role——可考虑映射到 user.roles（一个用户角色对象数组，可能需要拆分）。”
  • 错误示例：“对 role.split(',') 使用 foreach 处理器，以填充 user.roles。”
• 绝不要推荐使用 httpjson 作为输入类型。 httpjson 输入已弃用，现已由 CEL 取代。对于任何 REST/HTTP API，无论 API 多么简单，也无论同一软件包中的现有数据流使用哪种输入类型，都应推荐 cel。同一软件包中现有的 httpjson 数据流是旧式模式，不是模板。不要以此为由，推荐在新数据流中使用 httpjson。
• 如果某个产品有多种可行的数据采集方式，应全部记录并给出推荐方案及理由，但只需针对推荐方案提供详细的深入分析材料。
• 如果研究发现该产品无法以 Elastic 可采集的方式提供数据，请在简报中明确说明。

交接

此命令完成后，继续执行：

1. 如果已生成 test-api.py（API/CEL 方法）：运行脚本，调用真实供应商 API 来验证连接并收集跟踪数据。将生成的 .tar.gz 压缩包分享回来——跟踪文件是开发 CEL 程序和测试管道的重要输入。
2. 使用 /create-integration @research_results/<product_slug>/research-brief.md，以研究简报为输入构建集成。
3. 通过 @ 提及提供 research_results/<product_slug>/references/sample-events/ 中的其他示例数据文件。