SuperPlane 集成扩展研究指南：用“可用性优先“方法论为现有集成新增组件

SuperPlane 是"一键式工程"的开源工厂（仓库根目录见 README.md），它通过集成（Integration）与外部服务相连，把第三方工具变成工作流中的触发器（Trigger）与动作组件（Action）。本篇指南围绕仓库中定义的标准研究流程展开：当你已经拥有一个 SuperPlane 集成，希望为它扩展更多组件时，如何用"可用性优先"（usability-first）的思路做调研、定方向，最终产出一批真正贴合用户使用场景的新组件。读完你将掌握这套可复用的研究方法、它与"新建集成"流程的区别，以及如何把调研结论落地到仓库的真实结构中（后端pkg/integrations/、前端 mappers、组件文档与测试）。

这套方法从哪来

本流程的权威定义位于仓库内的 .cursor/commands/research-extension.md，它是一个可被 Cursor 类 AI 助手直接调用的研究命令（command），并引用配套的技能定义 .cursor/skills/superplane-integration-research/SKILL.md。仓库里还有它的"孪生命令" .cursor/commands/research-integration.md，负责全新工具的集成调研，两者共享同一技能、同一方法论，区别只在输出物：新集成建议2 个起步组件（1 触发器 + 1 动作），扩展集成建议少量契合的追加组件。

这套方法论与仓库的工程化文档链是贯通的：docs/contributing/building-an-integration.md 定义了"选集成 → 研究连接方式 → 实现 → 提 PR"的高层步骤；docs/contributing/integrations.md 给出了后端与前端的具体实现模式；docs/contributing/component-design.md 则规定了组件的产品设计标准。本指南的调研环节正是这些实现文档的"上游"——先把方向想清楚，再动手写代码。

核心定位：这是一份"可用性研究"而非"工程研究"

命令开篇即声明了研究者的身份与职责边界：

You are aresearch helperforextendingan existing SuperPlane integration. Focus onusability: what's the tool's priority function, what use cases we're not covering yet, what the API allows.

研究助手只回答三个问题：这个工具的优先功能是什么、我们还没覆盖哪些使用场景、API 允许我们做什么。然后据此建议契合的追加组件。连接细节（连接方式、鉴权参数、约束）属于工程师的范畴，研究者只需要知道"能访问到什么"，不需要产出连接规格书。

这条边界在技能定义中被进一步固化，.cursor/skills/superplane-integration-research/SKILL.md 明确写出：

• 你不以连接方法或工程实现开场；
• 连接细节留给实现者去探索；
• 你只需要连接层面的洞察（例如"他们提供 webhooks，所以可以做事件触发器；有 REST API，可以做部署动作"）来支撑组件建议；
• 不要把 Auth / API / Constraints 作为交付物。

五步工作流：从"已有组件"走到"新增组件清单"

.cursor/commands/research-extension.md 定义了研究者的完整工作方式，共五个步骤：

1. 从"我们已有什么"开始。先回答一个短句：集成里已经有啥（依据docs/components/下的组件文档或 docs）。紧接着给出：这个工具的主要工作是什么，以及我们可能遗漏的使用场景。
2. 然后看 API。API 还暴露了哪些契合这些场景的能力？有哪些限制？只要足够判断可行性即可——不需要连接规格。
3. 建议几个追加组件。每个一行，匹配优先功能与使用场景。随后询问用户想增加或删减哪些。
4. 当用户准备好锁定：输出简短总结 = 已有组件 + 追加组件。连接方式仅在相关时用一行带过。
5. 红线（Never）：不以连接方法开场、不做长报告、不输出工程向内容。

最终目标：通过对话收敛出一小组"对用户如何使用该工具而言合理"的追加组件。

研究时的关注顺序：五个维度层层递进

技能文件给出了研究者每次调研都应遵循的五个维度（按序执行）：

其中"事件 → 触发器、操作 → 动作"的映射是贯穿始终的主线：SuperPlane 集成由两类构件组成——触发器（监听外部事件、启动工作流执行）和动作组件（响应上游事件执行操作）。判断某个 API 能力该做成哪一类，看它本质上是"被动接收的事件"还是"主动发起的操作"。

已有的相似集成：最有效的建议捷径

技能定义里给了研究者一条高效策略：如果目标工具与仓库已有的某个集成相似，用一行话点出，并复用它的组件作为模式模板。例如：

If the tool is similar to one we have (e.g. Railway ↔ Render), mention it in one line and use it as a pattern for components.

这也是"扩展已有集成"调研独有的优势：仓库 pkg/integrations/ 下已有数十个集成（github、gitlab、slack、pagerduty、sentry、semaphore、render、datadog、jira、linear 等），每个都在 docs/components/ 有对应的组件文档，可以直接作为"该类型工具通常该有哪些组件"的参照系。

组件的"设计语言"：调研者该懂的判断标尺

要让建议的组件"合理"，需要理解 SuperPlane 组件的基本设计语言（详见 docs/contributing/component-design.md），它们是建议是否靠谱的检验标准：

触发器 vs 动作

• 触发器：监听外部事件，启动工作流执行，无输入通道；
• 动作：响应上游事件执行操作，有输入通道（左把手），可订阅上游节点事件。

输出通道：一个还是多个

组件可定义具名输出通道（passed、failed、approved、timeout……），用于把执行结果路由到不同下游分支。判断依据是"大多数用户会不会针对这个结果走不同的后续处理"：

状态：failed 与 error 必须分清

这是组件设计中最关键的一处区分，也是调研者在判断"该组件适合哪些使用场景"时应牢记的语义：

• failed=预期内的失败结果：组件成功执行了，但结果是失败（HTTP 返回 404、CI 流水线失败）；
• error=非预期故障：组件没能完成执行（网络超时、凭证无效、内部异常）。

每个组件必须支持error状态，即使只定义了approved之类的自定义状态也不能例外。

Payload 结构：面向表达式设计

组件向下游发射 JSON payload（含data、timestamp、type三部分），用户在后续节点用表达式访问，如$['Create Issue'].issue.number。规则：表达式路径超过 3 层就是太深。对于外部 API 原生返回的数据（GitHub、Slack 等），倾向于保留原始结构而非强行扁平化，因为用户对照外部 API 文档时更熟悉原生格式。

默认配置要"贴近最常见用例"

.cursor/commands/research-extension.md 与技能均强调建议组件时要考虑默认行为。集成开发指南 docs/contributing/integrations.md 也给出了最佳实践："默认配置应覆盖最常见的使用场景，并避免产生不必要的事件"，例如github.onPush触发器默认只监听main分支的提交。调研者在建议触发器组件时，应同时想清楚它的默认过滤条件。

落地路径：调研结论如何在仓库中兑现

调研锁定的组件清单，最终通过以下仓库结构落地（细节见 docs/contributing/integrations.md）：

pkg/integrations/<app-name>/ # Go 后端：集成主文件、client、各触发器/组件 web_src/src/pages/workflowv2/mappers/<app-name>/ # TypeScript 前端渲染器 docs/components/<AppName>.mdx # 组件文档（可用 make gen.components.docs 生成） pkg/integrations/<app-name>/*_test.go # 单元测试

集成在init()中通过registry.RegisterIntegration(...)注册；若需要管理 webhook，则改用registry.RegisterIntegrationWithWebhookHandler(...)（参考 pkg/integrations/render/render.go）。主文件实现Configuration()（配置字段）、Actions()（动作列表）、Triggers()（触发器列表）、Sync()（配置校验与就绪状态）等接口。

以 Render 集成为例：一次"扩展调研"的成品形态

Render 集成是理解"扩展"结果的绝佳样例，其组件文档见 docs/components/Render.mdx，后端实现位于 pkg/integrations/render/。它的组成正好对应研究方法论中的两类构件：

• 触发器 2 个（render.onBuild、render.onDeploy）：监听构建/部署事件，默认分别监听build_ended、deploy_ended，属于"事件 → 触发器"；
• 动作 9 个（Deploy、Cancel Deploy、Rollback Deploy、Get Deploy、Get Service、Purge Cache、Add/Remove Custom Domain、Update Env Var），属于"操作 → 动作"。

从 pkg/integrations/render/render.go 可以看到这两个列表的源码注册形态。多个"等待型"动作（Deploy、Cancel Deploy、Rollback Deploy）都复用同一个deploy_endedwebhook 并带轮询兜底，这印证了技能里"连接洞察只需够用"的原则——研究者在调研阶段只要知道"Render 有 webhooks 可做事件触发器、有 REST API v1 可做部署/回滚/域名管理等动作"，就足以提出组件建议。

调研"够用即可"的源码例证：Webhook 共享机制

技能明确要求研究者不写连接规格，但理解连接能力边界仍然必要。Render 的 webhook_handler.go 展示了连接层面的核心机制：CompareConfig决定两个 webhook 配置是否等价（可复用），Merge合并多个触发器的监听事件类型。这意味着"同一个集成内多个触发器/组件可以共享一个 webhook"——调研者据此就能判断哪些组件建议成本低、易落地。

交流风格：像同事一样对话，拒绝"八股"

两份命令文件对响应方式有明确、可执行的约束：

• 简短、会话式：几句话或 2–3 个要点即可；
• 每次一轮一个发现，然后询问用户下一步想了解什么（例如"要我看看 API 还暴露了什么吗？"）；
• 不要灌水：不写正式的小节标题、不写"全面概述"，像同事一样说话；
• 结束时若用户准备锁定，输出简短总结：工具是干什么的 + 建议组件（每个一行）；可选一行"连接方式看起来是 X——工程师可以细化"，不要让连接成为主要输出。

这种风格本身就是设计决策：它把"研究"当作与用户的协作对话，而非一次性交付报告，从而在每一步都让用户有机会纠正方向，最终收敛到真正被认可的小组件集合。

与"新建集成"流程的分工

• 对全新工具：使用 .cursor/commands/research-integration.md，输出 2 个起步组件（1 触发器 + 1 动作），并对相似集成（如 Render）做一行类比；
• 对已有集成（本指南主题）：使用 .cursor/commands/research-extension.md，先盘点已有组件，再建议"少量契合的追加组件"。

两者共享技能 superplane-integration-research，都遵循"工具是什么 → 使用场景 → API 能力 → 连接洞察 → 组件建议"的同一骨架，也都坚持"可用性优先、工程细节后置"的立场。

调研完成后：如何验证与提 PR

组件锁定后进入实现阶段，docs/contributing/building-an-integration.md 给出了收尾流程：

• 实现后端于pkg/integrations/<name>/，前端 mappers 于 web_src/src/pages/workflowv2/mappers/，文档写在集成包内，用make gen.components.docs生成；
• 测试：make format.go && make lint && make check.build.app、make test、make check.build.ui，并考虑 E2E 测试（见 docs/contributing/e2e-tests.md）；
• 提 PR 时遵循 docs/contributing/integration-prs.md 的规范（标题、描述、issue 链接、视频演示、CI 与 DCO 签名提交）。

小结：把"扩展"变成有依据的决策

.cursor/commands/research-extension.md 定义的扩展研究流程，本质是把"为已有集成加组件"从拍脑袋变成结构化决策：先盘点现状，再以"优先功能 + 使用场景 + API 允许范围"三角收敛候选组件，用仓库中相似集成的既有模式做参照，最后以简短总结锁定成果。这套方法论与 docs/contributing/component-design.md 的设计标尺（触发器/动作、输出通道、failed 与 error 语义、payload 扁平度）互为表里，与 docs/contributing/integrations.md 的落地结构无缝衔接。对任何想在 SuperPlane 生态中扩展集成的开发者或 AI Agent 来说，这是从"调研"到"交付"的最短可靠路径。