research-integration

用途

research-integration 是 Elastic 集成技能体系中的“调研编排器”角色。它并不直接构建集成，而是负责在构建之前对一个厂商、产品或功能进行全面调研，产出一份结构化的研究简报，作为下游集成构建工具 /create-integration 的主要输入。

其核心思路是：把调研工作拆分为多个并行的研究轨道，交由研究子代理执行，再由编排器综合各子代理的发现、本地提供的参考资料以及自身知识，写出最终简报。

主要能力

并行调研编排：通过平台的通用子代理机制（Cursor 的 generalPurpose Task agent、Claude Code 的 general-purpose Task agent，或其他平台的等价机制）并行派发多个研究子代理，通常为 2-4 个，外加始终启用的市场覆盖轨道，以及在存在 entity 数据流时启用的实体轨道。
子代理具备写入能力：子代理可以下载仓库、安装包、运行 Python 分析脚本，并把发现写入磁盘。这是有意设计的，因为很多数据源的 schema、SDK 或规格文档太大，无法内联返回。
多轨道调研：
- Track A：产品概览与数据采集方式——产品生成什么数据、有哪些采集/导出方式、哪种最适合 Elastic 集成、官方文档链接、已知限制与速率限制、许可要求。
- Track B：数据源深入——针对 API 调研基础 URL、端点路径、认证方式（含 OAuth2 授权类型与完整流程）、分页模式、速率限制、请求/响应结构、查询参数与过滤、API 版本策略；针对日志/ syslog 调研日志格式（RFC 3164/5424、CEF、LEEF、键值、JSON、CSV、多行）、默认日志路径、facility 与 severity、消息结构、样例日志行；针对云采集调研投递机制配置、消息/对象格式、路径前缀、通知配置。若厂商提供 OpenAPI/Swagger 规格或 SDK，可下载到 temp/ 并用 Python 提取端点、schema 与参数。
- Track C：事件类型与字段 schema——所有不同事件类型/类别/日志源、字段名类型描述、公共字段与专属字段、状态/严重性/动作/类别枚举值、时间戳格式与时区、嵌套结构、高价值事件。大型 schema 可下载并用 Python 程序化提取。
- Track D（可选）：配置与部署——终端用户需提供的配置、如何在厂商侧启用数据导出、网络要求、常见部署架构、前置条件与权限。
- Track E（始终启用）：市场覆盖——检查 IBM QRadar、Splunk、Sumo Logic 是否已有针对该产品的集成或应用，覆盖哪些内容、如何采集数据，并记录名称、发布方、目录链接、版本、更新时间、采集方式与协议/线格式细节。
- Track F：当某数据流被归类为 entity 时启用。

使用方式

通过命令 /research-integration 调用，命令后接研究目标。可组合提供以下输入：

产品 / 厂商 / 功能（自由文本），例如 "Checkpoint Harmony Endpoint"、"Okta System Log"、"AWS CloudTrail via S3"。
已知采集方式（可选自由文本），例如 "REST API"、"syslog"、"S3/SQS"、"Azure Event Hub"。
文档 URL（粘贴链接）。
本地参考资料（@ 提及文件或文件夹）。
范围约束（自由文本），例如 "only the alerts API"、"focus on firewall logs"、"audit events only"。
输出名称覆盖（自由文本），默认使用净化后的产品名。

调用示例：

/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.

技能启动前会读取一系列参考文件：data-collection-methods.md、research-output-template.md，以及按采集方式选择对应的清单（api-research-checklist.md、log-file-research-checklist.md、cloud-ingest-research-checklist.md）。若调用时采集方式未知，则三份清单都读取。此外还会加载 ecs-field-mappings 技能、entity-mappings 的 entity-datastream-classification.md、market-coverage-checklist.md 和 research-subagent-guidance.md 等。注意：不应加载其它集成构建类技能（CEL、pipelines、ecs-field-mappings 实现细节、entity-mappings 字段目录等），这些属于实现材料。

工作流程

Phase 1 解析与规划：从用户消息中提取产品名、厂商、已知采集方式、文档 URL、本地参考文件、范围约束；读取 @ 提及的本地文件；抓取内联文档 URL；确定输出 slug 并创建输出目录；识别需要推进的调研轨道。
Phase 2 并行调研：并行启动多个研究子代理。子代理看不到对话、也无法直接访问 @ 提及的文件，因此需在任务提示中包含相关内容。每个子代理任务提示以读取 references/research-subagent-guidance.md 为开头，并明确工作目录，只传路径不嵌入内容以控制上下文成本。
后续阶段包括分析与综合、API 测试脚本生成、市场覆盖与实体覆盖处理、ECS 映射分析、配置计划等，最终写入研究简报。

输出位置与结构

所有输出写入 research_results/<product_slug>/，其中 <product_slug> 为小写下划线分隔的标识符（如 checkpoint_harmony_endpoint）。目录结构包括：

research-brief.md：主结构化研究简报
test-api.py：API 连接与流程测试脚本（仅 API/CEL）
references/：供下游使用的整理后研究产物，含 api-spec-notes.md、log-format-notes.md、field-schema-analysis.md、market-coverage.md、entity-coverage.md、sample-events/ 等
temp/：下载的原始产物（仓库、SDK、schema、脚本），完成后不应删除，供人工参考与后续使用
ecs-mapping-analysis.md：初步 ECS 字段映射分析
entity-mapping-analysis.md：每个 entity 归类流的 entity.* 字段状态（仅 entity 流）
configuration-plan.md：计划的集成配置变量

并非所有文件都必需，只创建适用于该产品采集方式的部分。

适用场景

适用于需要为某厂商、产品或功能构建新的 Elastic 集成，且希望在动手实现前系统性收集采集方式、API/日志细节、事件与字段 schema、配置部署要求以及竞品覆盖情况的场景。

限制

研究流程本身没有 CEL 工具要求；但如果最终推荐的采集方式是基于 API 的（CEL 输入），下游 /create-integration 需要安装 mito、celfmt、ceplx 和 stream，技能会在 Phase 8 摘要中提示用户核对工具链。其它具体功能边界、收费、价格与平台支持细节暂未提供。