【免费下载链接】superplaneOpen source factory for one-shot engineering项目地址https://gitcode.com/gh_mirrors/su/superplane点击查看免费下载SuperPlane 是一个一次性工程工厂Open source factory for one-shot engineering其核心能力由大量组件Components、触发器Triggers与集成Integrations组成。为了让这些模块在功能、命名、安全、测试与文案上保持一致仓库维护了一份可扩展的组件评审规则清单并配套了一个 Cursor 命令用于逐条自动审查。本文以.cursor/commands/component-review.rules.md为主线结合pkg/core、pkg/registry、pkg/configuration等源码系统讲解这套评审体系的设计思路、每条规则的判定标准与落地方式帮助你理解并复用于自己的组件开发与评审流程。规则清单的设计理念聚焦、可测试、可扩展规则文件开篇即明确了三条元规则格式统一新规则必须以相同格式追加进清单每条规则保持聚焦focused且可测试testable分类驱动排序规则按 Category分类组织分类同时决定规则的顺序与适用范围双入口协同规则文件.cursor/commands/component-review.rules.md只描述标准是什么配套命令.cursor/commands/component-review.md则描述如何用这套标准去审查。其中命令文件定义的审查流程如下判定类别先确认被审查对象是核心组件pkg/components/...还是集成组件pkg/integrations/...定位元数据找到组件的Name()、Label()、Description()、Documentation()、Icon()、Color()、ExampleOutput()、Configuration()等实现逐条审查从规则文件按顺序逐条评估不得跳过任何规则格式化输出每条规则输出### 规则名子标题下一行给出OK或NOT OK: 证据不通过时必须给出具体文件与标识符函数名、常量、文件作为证据并附带一句可操作的修复提示最后以 Summary 汇总所有失败规则可扩展约束命令必须始终读取规则文件并应用新增规则任何人只需编辑规则文件即可扩展评审范围。需要特别注意的是审查结论只允许OK/NOT OK二选一不允许出现 N/A这保证了评审结果的确定性、可扫描性与机器可处理性。Product functionality面向 UI 外部可见行为的规则这一大类规则要求评审者把注意力放在 UI 中用户可见的行为上而不是内部函数细节。所有规则都围绕用户在画布Canvas上看到什么、配置什么、触发什么展开。注册Registration组件必须真实进入应用核心组件必须通过registry.RegisterComponent注册集成组件则必须出现在该集成Components()或Triggers()的返回值里。在源码层面pkg/registry/registry.go用包级 map 维护注册表registeredActions、registeredTriggers、registeredIntegrations等 map 由带互斥锁的RegisterAction、RegisterTrigger、RegisterIntegration、RegisterIntegrationWithWebhookHandler、RegisterWidget写入见 registry.goNewRegistry/NewRegistryWithOptions在Init()中把注册表快照拷贝进运行时 Registry并统一用NewPanicableAction、NewPanicableTrigger等包装为运行时 panic 提供防护见 registry.go带命名空间的查找逻辑GetTrigger/GetAction会先按.拆分名称无前缀按核心组件查有前缀则委托给GetIntegrationTrigger/GetIntegrationAction遍历集成的Triggers()/Actions()见 registry.go。这意味着评审时注册成功不只是代码能编译还要确认组件名确实进入了运行时注册表UI 才能在画布节点列表中枚举到它。命名Naming从名字就能判断角色命名规则是一套可机器校验的约定核心组件名与注册名一致集成组件名遵循integration.name格式且使用 camelCase例如github.getIssue而不是github.GetIssue组件名永不包含空格与下划线触发器必须以on开头触发器名称应引用其监听资源而非动作例如github.onIssueComment而不是github.onIssueCommented——除非该触发器本身就是针对某个具体动作的。这套约定的价值在于用户在节点选择器中看到on前缀即可判断这是触发器通过integration.name前缀即可判断来源集成从而形成统一的导航心智模型。标签与描述Label / Description人性化文案LabelUI 中显示的标签必须非空、人类可读、使用 Title Case首字母大写的标题风格不允许出现原始 slug如getIssue这类内部命名直接暴露DescriptionUI 中显示的描述必须非空、面向用户、简短清晰。在pkg/core/action.go与pkg/core/trigger.go的接口定义中Label()、Description()、Documentation()都是独立的方法见 action.go、trigger.go它们承载的正是 UI 节点面板中展示给用户的全部文案信息。文档Documentation有效 Markdown 且层级克制组件文档必须非空、是合法 Markdown如果使用标题最大层级应为##。这一约定有两个实际原因一是组件文档最终会被渲染进 UI 面板#一级标题会与页面既有标题冲突二是强制文档聚焦使用说明而非长篇架构论述。图标与颜色Icon / Color视觉一致性图标必须非空且映射到有效 UI 图标要么是 Lucide Icon slug要么是仓库中已有的自定义资源颜色必须非空并与既有组件颜色使用习惯保持一致。这两条保证了组件在画布上的视觉可区分性与整体一致性避免出现图标 404 或颜色刺眼失配。示例输出Example outputJSON 必须真实有效组件 UI 中展示的示例输出必须内嵌一个示例 JSON 文件如example_output.json且该文件必须合法、并与组件实际发射的 payload 结构一致。这条规则防止了文档与实现脱节——示例是用户理解输出的第一手材料若结构与真实输出不符会直接误导使用者。配置字段Configuration fields表单体验的硬性标准这是规则最密集的小节逐条如下每个配置字段都必须具备Name、Label、Type、Description四项元数据必填字段必须标记Required: true并且必填字段永远排在可选字段之前尽量避免要求用户输入不易获取的 ID例如要求用户手填 Discord 频道 ID当用户可以从既有资源中选择如 GitHub 仓库时必须使用FieldTypeIntegrationResource。例如channelId应使用FieldTypeIntegrationResource类型而不是FieldTypeString触发器的过滤器与组件配置中涉及相等、不相等或正则匹配的优先使用configuration.FieldTypeAnyPredicateList并通过configuration.MatchesAnyPredicate匹配值避免临时性的通配符或逗号解析除非any-predicate-list无法表达需求若其无法满足应先尝试扩展它而非自造实现如果过滤器属于触发器的一部分必须为最常见的用例提供默认过滤器——这既降低用户配置成本也避免系统产生不必要的事件。例如默认的github.onPushrefs 过滤器是针对 main 分支的提交。这些约定在源码中均有对应支撑pkg/configuration/field.go定义了完整的字段类型常量表FieldTypeString、FieldTypeIntegrationResource、FieldTypeAnyPredicateList等以及Field结构体的Name/Label/Type/Description/Required/Default/Sensitive等属性见 field.go并提供了MatchesAnyPredicate、any-predicate-list等配套实现pkg/registry/registry.go的FindConfigurableComponent与ComponentType则负责把组件名解析为可配置对象及其节点类型见 registry.go。输出通道Output channels至少一个通道UI 中展示的输出通道必须至少包含一个或依赖默认通道且通道名/标签非空。这与core.Action接口中的OutputChannels(configuration any) []OutputChannel方法对应——若返回空列表则使用默认default通道见 action.go。设置Setup引用的资源必须被验证如果组件/触发器使用FieldTypeIntegrationResource配置字段其Setup()必须验证被引用的资源确实存在并在验证通过后把资源信息存入组件/触发器元数据中的 struct。这保证画布上不会出现引用了已删除资源的悬空节点。Webhooks两种模式的正确选择若 webhook 不是通过集成配置的使用ctx.Webhook.Setup()节点级自管理 webhook见 component.go 的NodeWebhookContext若 webhook 通过集成配置使用ctx.Integration.RequestWebhook()并实现core.WebhookHandler含Setup、Cleanup、CompareConfig通过registry.RegisterIntegrationWithWebhookHandler注册见 registry.go、integration.go当多个组件使用相同底层事件配置时应尽量共享 webhook通过CompareConfig判断配置等价。例如两个github.onPush触发器一个监听 main 分支、一个监听 release 分支在 GitHub 侧应使用同一个 webhook。后者的共享机制意味着当第二个触发器请求相同配置时系统只需复用既有 webhook 并合并订阅而非重复创建外部资源从而降低第三方平台的配额消耗与事件噪音。触发器Triggers作用域必须明确触发器永远被限定在1特定资源类型 2特定资源 3其他附加条件之上。规则给出了三个典型示例semaphore.onPipelineDone选择要监听的特定项目github.onPush选择要监听的仓库pagerduty.onIncident选择服务。这种资源优先的设计保证了触发器在画布上是可配置、可预测的——用户配置一个触发器时必然明确监听什么而不是面对一个全局模糊的事件源。安全Security三条不可逾越的底线组件必须始终通过HTTPContext执行 HTTP 请求绝不直接使用net/http。在 component.go 中HTTPContext接口的注释明确写道组件/触发器/应用应始终使用该 context 而非直接使用 net/http 执行 HTTP 请求因为统一出口便于为所有实现编写单元测试也便于在一处集中控制 HTTP 超时组件绝不允许导入pkg/models直接操作数据库只能通过 core 接口提供的方法访问数据HandleWebhook()组件/触发器与HandleRequest()集成实现必须始终使用 webhook 中的 secret 验证请求是否已认证。三条规则共同保证了组件与核心引擎的解耦HTTP 与数据访问都走受控通道外部回调则强制鉴权避免组件成为安全漏洞入口。Code Quality可维护性与工程规范的规则第二大类规则面向代码本身的质量与可测试性。单元测试Unit testing覆盖范围有明确边界静态方法如Configuration()、Label()、Name()无需单元测试它们只是数据返回禁止在单元测试中 dummy 实现pkg/core接口应使用 test/support/contexts 中已有的上下文。该文件提供了EventContext、NodeWebhookContext、WebhookContext等可复用的测试替身见 contexts.go避免了每个组件测试各自维护一份残缺 mock 的重复劳动测试必须覆盖验证失败与错误处理路径按接口类型划定必测方法Component接口Setup()与Execute()必须测试若实现了Hooks()也必须单测Trigger接口Setup()与HandleWebhook()必须测试若实现了Hooks()也必须单测Integration接口Sync必须测试若实现了Hooks()也必须单测。这条规则的深层逻辑是Setup与Execute/HandleWebhook是组件唯一的会真实执行逻辑的入口其余方法基本是元数据测试资源应集中投向有行为的地方。通用原则General principles代码风格基线倾向提前返回early return与辅助函数而非嵌套if/else重复出现的字符串名称、payload 类型必须定义为常量新引入的 import 必须被使用不允许死代码或未使用的辅助函数。Golang 专属规范优先any而非interface{}类型判断列表中是否存在某元素时使用slice.Contains或slice.ContainsFunc变量命名避免*Str、*UUID这类类型后缀写法——Go 是静态类型语言类型信息已由编译器保证不需要写进变量名测试中需要特定时间戳时一律基于time.Now()构造禁止使用time.Date写绝对时间——这保证了测试不会随时间推移而过期失效检查事务使用事务流中的任何数据库访问都必须使用*InTransaction()变体绝不使用database.Conn()避免绕过事务边界导致的数据不一致。TypeScript 专属规范禁止隐式 any内联处理器参数必须显式标注类型禁止滥用 any避免无理由的as any/ts-ignore应优先收窄类型确需绕过时使用带注释的ts-expect-error。这条规则主要约束 web 前端web_src/src中与组件配置表单、节点渲染相关的代码保证前端类型安全与后端配置 schema 的一致性。Copy面向用户的文案标准第三大类规则专注文案质量与 Product functionality 中的 Label/Description 规则互相呼应用户可见文本所有面向用户的字符串必须简短、清晰、简洁原文保留拼写concise清晰性标签、描述与文档要避免内部行话internal jargon并解释设计意图一致性文档中使用的术语必须与配置标签及输出字段完全一致格式组件文档中的 Markdown 必须渲染干净不允许损坏的代码块围栏或标题层级。其中术语一致性尤为重要如果配置字段叫repository文档里就不能写成repo否则用户在表单与文档之间对照时会产生歧义。评审流程闭环从规则到命令的自动化把规则文件与命令文件放在一起看这套体系形成了完整的闭环规则文件是标准源——任何新约定只需以统一格式追加即可自动进入评审范围命令文件是执行器——它强制按顺序逐条评估、要求OK/NOT OK二选一、要求失败时必须给出文件级证据与修复提示规则按 CategoryProduct functionality / Code Quality / Copy组织决定了审查时的遍历顺序与关注重点最终产出Summary 失败规则列表可以直接转化为待办项喂给开发者或 Agent 进行修复。这种机器可读的规则 强制证据的评审输出模式特别适合组件数量庞大、需要多人并行维护的仓库评审结论不依赖评审者个人口味而依赖可验证的事实文件、函数名、常量、接口方法。对于 SuperPlane 这种拥有 200 核心组件文件与 1700 集成 Go 文件的仓库见 pkg/components 与 pkg/integrations这种规范化评审是维持整体质量一致性的关键机制。小结评审对象分两类核心组件pkg/components/...与集成组件pkg/integrations/...判定依据是注册方式与命名空间功能类规则覆盖注册、命名、标签、描述、文档、图标、颜色、示例输出、配置字段、输出通道、Setup 资源验证、Webhook 模式选择、触发器作用域与安全底线质量类规则覆盖单元测试边界复用 test/support/contexts、代码风格、Go 与 TypeScript 专属规范以及事务使用检查文案类规则确保用户可见文本简短清晰、术语一致、Markdown 渲染干净配套命令.cursor/commands/component-review.md把规则清单变成可重复执行的审查流程失败项必须附带文件级证据与可操作提示。无论你是要提交一个新的 SuperPlane 组件/集成 PR还是想为自有项目建立一套组件评审机制这套聚焦、可测试、可扩展的规则清单都值得直接借鉴——把标准写进文件把审查交给命令把质量留给证据。赞分享【免费下载链接】superplaneOpen source factory for one-shot engineering项目地址https://gitcode.com/gh_mirrors/su/superplane点击查看免费下载相关推荐Pandora.js与Docker集成构建可观测的Node.js容器化应用Pandora.js与Docker集成构建可观测的Node.js容器化应用 想要在Docker容器中构建可观测、可管理的Node.js应用吗 阿里开源的OneKey钱包Monorepo架构优势为什么大型项目选择这种代码组织方式OneKey钱包Monorepo架构优势为什么大型项目选择这种代码组织方式 OneKey钱包作为一款安全、开源且社区驱动的加密货币钱包采用Monorepo架Simple Icons代码质量保障ESLint规则与代码审查清单Simple Icons代码质量保障ESLint规则与代码审查清单 在开源项目开发中代码质量是项目可持续发展的基石。Simple Icons作为一个专注于提前端UI组件上一篇3 类根因定位 2168-0002Atmosphere 启动失败完整修复下一篇EdgeDB备份恢复终极指南保护你的图关系数据库数据安全创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考