在构建 Elastic 集成前…

当你需要为某个厂商、产品或功能构建 Elastic 集成、但缺乏完整的采集方式、API/日志文档、字段模式与 ECS 映射信息时，用这套并行子代理调研流程产出一份可直接喂给 /create-integration 的研究简报。

适用场景

解决思路

1. 解析用户输入：提取产品名、厂商、已知采集方式、文档 URL、本地参考文件与范围约束；读取所有 @ 提及的本地文件；抓取内联提供的文档 URL 获取初始上下文；确定输出 slug 并创建输出目录；识别需要调研的研究轨道。
2. 在开始前加载参考文件：依次读取 references/data-collection-methods.md、references/research-output-template.md；根据采集方式读取对应清单（api-research-checklist.md / log-file-research-checklist.md / cloud-ingest-research-checklist.md），若采集方式未知则三份都读；若为 API 方式再读 references/test-api-script-spec.md；加载 ecs-field-mappings 技能；自行读取 entity-mappings/references/entity-datastream-classification.md 以分类 event vs entity 数据流（不要加载 entity-mappings 其余部分）；自行读取 references/market-coverage-checklist.md；不要自行读取 references/research-subagent-guidance.md，而是把该文件路径传给每个子代理让其自行完整读取。不要加载其他集成构建类技能（CEL、pipelines、ecs-field-mappings 实现细节、entity-mappings 字段目录等）。
3. 输出目录结构：所有研究输出写入 research_results/<product_slug>/（slug 为小写、下划线分隔，可由用户覆盖）。创建 research-brief.md、test-api.py（仅 API/CEL）、references/（含 api-spec-notes.md、log-format-notes.md、field-schema-analysis.md、market-coverage.md、entity-coverage.md、sample-events/）、temp/（下载的原始产物，如 vendor-sdk/、schema-files/、openapi-spec/）、ecs-mapping-analysis.md、entity-mapping-analysis.md、configuration-plan.md。只创建适用于该产品采集方式的文件；研究完成后不要删除 temp/。
4. 并行派发研究子代理：使用平台的通用/通用目的子代理（Cursor 的 generalPurpose Task agent、Claude Code 的 general-purpose Task agent 或等价物），通常派发 2-4 个并行子代理，外加始终启动的 Track E，以及当有数据流被分类为 entity 时启动的 Track F。每个子代理任务提示必须：以「先完整读取 references/research-subagent-guidance.md」开头（只传路径，不要粘贴内容）；明确声明工作目录 research_results/<product_slug>/ 及 temp/ 与 references/ 的写入位置；包含该轨道的调研项；包含用户提供的本地参考内容；包含用户提供的文档 URL。子代理具备写入能力，可克隆 git 仓库、安装 pip/npm 包、下载大文件到 temp/，可运行 Python 脚本分析大型产物，应将大型发现写入 references/ 或 temp/ 文件并只返回带文件路径的简洁摘要。
5. Track A（产品概览与采集方式）：调研产品/功能是什么、生成何种数据；所有可用的采集/导出方式（API、syslog、文件导出、云流式、SIEM 转发等）；哪种方式最适合 Elastic 集成及原因；每种方式的官方文档链接；数据访问的已知限制、速率限制或许可要求。
6. Track B（数据源深入）：按最可能的采集方式调研。API 方式：基础 URL 与端点路径；认证方式（API key、OAuth2、Bearer token、Basic auth、自定义头）；OAuth2 深入（识别所有支持的 grant type 及完整流程细节：authorization URL、token URL、refresh URL、scopes、client registration，不要满足于「手动生成 token」）；分页模式（offset、cursor、link-header、token、keyset）；速率限制；请求与响应结构及字段级细节；可用查询参数与过滤器（尤其基于时间的过滤）；API 版本策略；每个相关端点的完整请求/响应示例；若厂商发布 OpenAPI/Swagger 规范或 SDK，下载到 temp/ 并用 Python 提取端点、请求/响应模式与参数定义。日志/syslog 方式：日志格式（syslog RFC 3164/5424、CEF、LEEF、key-value、JSON、CSV、多行）；各 OS 默认日志路径；syslog facility 与 severity 用法；消息结构与分隔符；每种事件类型的示例日志行。云采集方式：投递机制配置；消息/对象格式与结构；路径/前缀模式；通知配置要求；若厂商在仓库中提供模式定义，克隆到 temp/ 并以编程方式分析。
7. Track C（事件类型与字段模式）：调研产品生成的所有不同事件类型、类别或日志源；每种事件类型的字段名、类型与描述；跨事件类型的公共字段 vs 类型特有字段；status、severity、action、category 字段的枚举值；时间戳格式与时区处理；嵌套对象结构；哪些事件对安全/可观测性用例价值最高。对于大型模式的数据源，下载模式源到 temp/ 并用 Python 程序化提取字段清单、类型信息与枚举值，将完整字段分析写入 references/field-schema-analysis.md 并返回摘要。
8. Track D（配置与部署，可选，按需启动）：调研最终用户需提供的配置（凭证、URL、路径、过滤器）；如何在厂商侧启用/配置数据导出；网络要求（端口、协议、防火墙规则）；常见部署架构；所需前置条件与权限。
9. Track E（市场覆盖，始终启动）：检查 IBM QRadar、Splunk、Sumo Logic 是否已有该产品的集成或应用，记录各自覆盖范围与采集方式。子代理必须完整遵循 references/market-coverage-checklist.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/。对每个平台确定：是否存在匹配集成（精确、部分或无）；集成名、发布者、目录直链、版本、最后更新日期；覆盖的数据源与事件类型（具体而非笼统）；使用的采集方式；协议与线格式细节（CEF、LEEF、JSON、key-value 等）；支持层级（厂商维护、平台构建、社区/伙伴或不受支持）；跨平台的显著覆盖缺口。将全部发现按清单结构（摘要表 → 各平台 H2 章节 → 对比说明）写入 references/market-coverage.md，返回简洁内联摘要。
10. Track F（实体清单覆盖，仅当有数据流被分类为 entity 时启动）：对每个 entity 分类的数据流调研：列表式端点（返回整个主体群体、无需基于时间过滤的 API 端点，明确记录是否有增量时间过滤）；单条记录的字段名、类型与描述，重点关注身份、状态、权限、组成员关系、MFA 状态与所有权字段；所需 scopes/权限（每个 scope 及其解锁内容，用于 manifest var 列表与简报第 6 节）；稳定主键（跨采集周期持久标识，如 id、login、email，若无则记录复合键）；MFA/权限/管理者/所有权属性（哪些字段承载安全相关状态，值得映射到 ECS entity.attributes.*）；增量时间过滤可用性（是否接受 since/updated_after/modified_since 参数及其语义，若无则记录必须每周期全量重调）。输出规则：只描述数据，不设计管道或字段定义；实现复杂度不是排除 entity 字段的理由（若需额外 API 调用、不同端点或额外 OAuth scope，清楚记录端点路径、响应结构与所需 scopes）；不要发明 entity.* 字段名，只使用固定版本 ECS 中存在的字段，无 ECS 等价物的源字段标记为 <integration_name>.<datastream_name>.<field_name> 自定义字段候选；将发现按每个 entity 数据流一节写入 references/entity-coverage.md 并返回简洁摘要。任务提示还需包含：产品名与 entity 分类数据流名称；列表式端点的 API 文档 URL；entity-mappings/references/entity-datastream-classification.md 的路径（只传路径）；工作目录。
11. Phase 3 综合与补充：读取子代理写入的文件（它们可能只返回摘要）；合并所有研究轨道的发现；与用户提供的本地参考材料交叉比对；用自身可靠知识填补空白，无法验证的细节标记 [UNVERIFIED]；解决子代理发现之间的冲突（官方厂商文档优先于第三方来源）；收集样本数据，将代表性样本事件分别保存到 sample-events/ 子目录；必要时检查 temp/ 产物；读取 references/market-coverage.md 提取摘要表与对比说明用于简报第 1.5 节。
12. Phase 4 ECS 映射分析：使用先前加载的 ECS 参考技能，对每个已识别字段判断是否映射到现有 ECS 字段（及哪个）、是否应作为集成命名空间下的自定义字段、合适的 Elasticsearch 字段类型；确定每种事件类型适用的 event.kind、event.category、event.type、event.outcome 值；标注适合 related.ip、related.user、related.hosts、related.hash 富化的字段；将分析写入 ecs-mapping-analysis.md。对每个 entity 分类的数据流（event.kind: asset），用 Track F 字段数据产出：所代表的 entity.type（从 entity-datastream-classification.md 中 12 个允许值中选）；映射到 entity.id 的源字段（Track F 的稳定主键）；每个 ECS entity.* 字段的逐字段状态表（列：ECS field、Status、Source field、Notes；状态键：✅ direct、🔄 derived、🔍 investigate、⛔ N/A），写入 entity-mapping-analysis.md。仅记录发现，不含 processors、字段 YAML 或 external: ecs 声明。
13. Phase 5 配置规划：根据采集方式规划集成配置：确定必需 vs 可选配置变量；为每个变量指定名称、标题、描述、类型、是否必需、是否向用户展示、合理默认值；将变量映射到相应输入类型的配置面（标准变量见 references/data-collection-methods.md）；将计划写入 configuration-plan.md。
14. Phase 6 撰写研究简报：按 references/research-output-template.md 模板编译完整简报，写入 research_results/<product_slug>/research-brief.md。简报必须自包含，读者可将其作为 /create-integration 的唯一输入。填充第 1.5 节（市场覆盖）时使用 Phase 3 第 8 步提取的摘要表，内联包含一行摘要段落与三行平台表，并加引用指针：See references/market-coverage.md for full per-platform analysis.
15. Phase 7 API 测试脚本（仅 API/CEL 采集）：若推荐采集方式不是基于 API（CEL 输入类型）则完全跳过。读取 references/test-api-script-spec.md 了解全部要求。从先前阶段收集输入：认证方式与凭证创建步骤（简报 3.1 节与 api-spec-notes）；端点路径、查询参数与请求结构（3.2 节）；分页机制、终止条件、游标字段（3.3 节）；基于时间的过滤参数与格式（3.4 节）；配置变量（configuration-plan.md）。将脚本写入 research_results/<product_slug>/test-api.py，关键要求：仅用标准库（urllib.request、json、logging、argparse、ssl 等，无第三方依赖）；全面的模块 docstring 作为独立文档（测试内容、厂商侧设置步骤、所有 CLI 标志用法、输出说明）；凭证与连接参数同时支持 CLI 参数与环境变量（CLI 优先，用 argparse 配合 default=os.environ.get(...)）；基础 URL 始终可配置（含 scheme 的完整 URL，即使厂商只有单一静态 URL，以便指向 mock 服务器）；始终提供 --max-pages 安全限制；禁用 TLS 验证；逐步 stdout 输出（不打印原始请求/响应体或敏感数据）；输出目录含 test-api.log（详细日志，stdout 的超集，用 logging 写入）与 trace.json（详细请求/响应追踪：完整 URL、头、响应体、分页状态转换，认证值脱敏）；结束时打印执行摘要（总体状态、总事件数、抓取页数、类别细分、输出位置）；将输出目录压缩为 .tar.gz 并打印路径与分享说明；错误处理（所有异常捕获并记录，429 时记录速率限制头，优雅处理 KeyboardInterrupt，成功退出 0 失败退出 1）。脚本的请求序列、分页逻辑与终止条件必须镜像简报中描述的 CEL 流程。
16. Phase 8 验证与报告：验证所有输出文件已写入且格式良好；若生成了 test-api.py，运行 python3 -m py_compile research_results/<product_slug>/test-api.py 验证无语法错误；列出所有创建的文件及路径；向用户提供简洁摘要（产品概览 1-2 句、推荐采集方式及原因、识别的事件类型/数据流数量、关键发现或意外、需用户输入的缺口、若生成 test-api.py 则提醒对真实 API 运行并分享归档、若为 API/CEL 方式则提醒在运行 /create-integration 前确认已安装 mito、celfmt、ceplx、stream、建议下一步通常是 /create-integration）。
17. 研究质量标准：所有论断基于来源，可追溯到厂商文档、官方规范或广泛确立的技术参考，使用自身知识时明确标注；优先官方厂商文档而非第三方博客、论坛或 AI 生成内容；尽可能包含源文档直链；采集真实示例（API 响应、日志行、配置片段），不伪造，若必须构造示例以说明结构则标记 [CONSTRUCTED EXAMPLE]；无法从官方来源确认的细节标记 [UNVERIFIED]；具体而非笼统（如「API 通过响应体中的 next_cursor 字段使用游标分页，将其作为 cursor 查询参数传入」）；覆盖边界情况（速率限制、最大页大小、所需权限、弃用端点、已知 bug 与陷阱）。
18. 护栏：不伪造看起来真实的样本数据（样本必须来自文档或明确标记为构造）；不开始构建集成（本技能只产出研究）；不加载实现类技能（CEL、pipelines、ecs-field-mappings 等）；不规定 CEL 实现细节（只记录 API 行为作为事实规范，不推荐具体 CEL 模式、嵌套结构、rate_limit() 用法、状态管理或错误处理策略）；不规定 pipeline、字段映射或 manifest 实现细节（只记录数据，不规定 processor 选择、错误处理结构或管道级可配置性）；研究输出中禁止出现 preserve_duplicate_custom_fields 标志、event.ingested、尾部 event.original 移除开关及对应 manifest 变量/标签/条件（唯一有效的 preserve_* 配置变量是 preserve_original_event，仅用于 file/syslog 输入）；不要提出 references/data-collection-methods.md 权威集合之外的配置变量，除非厂商 API 确实需要新的产品特定变量（如多租户 API 的 tenant ID）且绑定到有文档的厂商侧需求；不要发明 ECS 字段名（只映射固定版本 ECS 中存在的字段，无 ECS 等价物的源字段列为 <integration_name>.<datastream_name>.<field_name> 自定义字段，绝不放在 entity.attributes.*、user.*、host.* 等 ECS 前缀下）；不在 Track F 或 Phase 4 第 5 步规定 entity 字段映射或管道实现细节；绝不推荐 httpjson 作为输入类型（REST/HTTP API 一律推荐 cel，即使 API 很简单或同包现有流使用 httpjson，现有 httpjson 流是遗留模式而非模板）；若产品有多种可行采集方式，全部记录并给出推荐与理由，但只对推荐方式产出深入材料；若研究显示产品无法以 Elastic 可采集的方式暴露数据，在简报中明确说明。
19. 交接：本命令完成后，若生成了 test-api.py（API/CEL 方式），对真实厂商 API 运行脚本以验证连通性并采集追踪数据，分享生成的 .tar.gz 归档（追踪文件对 CEL 程序开发与管道测试很有价值）；运行 /create-integration @research_results/<product_slug>/research-brief.md 以简报为输入构建集成；通过 @ 提及提供 research_results/<product_slug>/references/sample-events/ 中的额外样本数据文件。

适用边界 · 注意事项

• 产品不暴露 Elastic 可采集的数据时（应在简报中明确说明而非强行产出）。
• 仅需构建集成、无需前期调研时（应直接使用 /create-integration）。
• 需要实现细节（CEL 模式、pipeline processor、字段 YAML、manifest 编写）时——本流程只产出研究，不规定实现。