Sim 集成开发规范Tools、Blocks、Icons、Triggers 四层构建顺序与不可逾越的硬性规则【免费下载链接】simSim is the collaborative workspace to build, deploy, and monitor AI agents and workflows. Used by 100,000 builders.项目地址: https://gitcode.com/GitHub_Trending/sim16/sim本文围绕 Sim 仓库中集成Integration开发的核心规范文档 sim-integrations.md 展开系统讲解在 Sim 中新增一个第三方服务集成时的构建顺序、注册表布局以及四组绝不能写错的硬性规则Tool ID 命名、类型强转时机、canonicalParamId语义、SubBlock 选项列表约束。读完后你将掌握 Sim 集成的完整目录结构、各注册表的准确落点以及一套可由仓库自带校验脚本闭环验证的操作流程。构建顺序Tools → Block → Icon → Trigger文档给出的构建顺序是集成开发的总纲Tools(tools/{service}/) →Block(blocks/blocks/{service}.ts) →Icon(components/icons.tsx) → 可选Trigger(triggers/{service}/)。并且要求先查阅该服务的 API 文档再动手写代码。这一顺序对应 Sim 的三层抽象Tools 层apps/sim/tools/{service}/每个文件对应一个 API 操作的工具声明。从源码结构看仓库中已有 a2a、airtable、asana、gmail、jira、notion 等数百个服务目录每个目录内是types.ts 各动作工具文件 index.tsbarrel 导出。Block 层apps/sim/blocks/blocks/{service}.ts把一组工具打包成画布上可拖拽的工作流节点声明 UI 子字段subBlocks、条件、输出。Icon 层apps/sim/components/icons.tsx服务品牌图标作为 React SVG 组件统一存放。Trigger 层apps/sim/triggers/{service}/可选当服务支持 Webhook 或需要轮询时为其添加事件触发器。完整的脚手架级作者指南不在本规则文档内而在仓库的 skills 体系中.claude/skills/add-integration/SKILL.md端到端全流程、add-tools、add-block、add-trigger分别覆盖工具、块、触发器的细节模板以及 SubBlock 属性表、condition/required/dependsOn/mode/canonicalParamId语法和normalizeFileInput等文件处理辅助函数的完整参照。本规则文档是这些 skill 的红线摘要两者配合阅读。三个注册表ID 命名与字母序约定硬性规则第一条要求Tool ID 采用snake_case的service_action形式且必须注册到指定的注册表中。三类资产的注册落点各不相同资产注册文件注册形式Toolstools/registry.tstools: Recordstring, ToolConfig对象按字母序添加Blocksblocks/registry-maps.tsBLOCK_REGISTRY配置映射BLOCK_META_REGISTRY目录元数据映射两张表均按字母序Triggerstriggers/registry.tsTRIGGER_REGISTRY按字母序一个容易踩坑的细节blocks/registry.ts只存放访问器函数getBlock等数据映射全部在 registry-maps.ts。从源码注释可以看到getBlock内部使用Object.hasOwn守卫见 registry.ts 的ownBlock防止调用方传入constructor、toString这类原型链上的键名时把继承函数误当成 block 返回。工具注册的实际形态可以参照 tools/registry.ts 开头的大规模字母序导入块——所有服务的工具符号按 a、c、d… 依次排布新服务必须插入到正确的位置。硬性规则一类型强转必须发生在执行期而非序列化期文档第二条规则精确规定了类型强转Number()等的归属必须放在tools.config.params—— 它在执行期、变量解析完成之后运行绝不能放在tools.config.tool—— 它在序列化期运行此时若对参数做强转会破坏动态的Block.output引用如{{some_block.output}}尚未被解析成真实值强行Number()会得到NaN。与之配合的文件归一化范例是在 block 的tools.config.params中调用normalizeFileInput来自 blocks/utils.ts把序列化后收敛到 canonical 键上的各种文件形态统一成工具可消费的输入import { normalizeFileInput } from /blocks/utils tools: { config: { tool: (params) {service}_${params.operation}, // 只做工具选择不改动输入 params: (params) { // 变量解析后运行负责归一化 const normalizedFile normalizeFileInput(params.file, { single: true }) return normalizedFile ? { file: normalizedFile } : {} }, }, }硬性规则二canonicalParamId的完整语义这是整份文档中最复杂、也最关键的规则。canonicalParamId是 basic/advanced 成对 SubBlock 的对外统一名必须同时满足三条约束不得与任何 SubBlock 的id相同它是第三个名字在整个 block 范围内唯一——因为 canonical 分组跨越所有 subBlocks 按 canonical id 建键、每组只保留一个basicId所以两个操作各自需要一个成对字段时必须使用两个不同的 canonical id同一 canonical 分组内所有 SubBlock 必须共享相同的required状态。序列化机制是理解这一规则的关键inputs节和 params 函数引用的都是canonical ID 而非原始 subblock ID——序列化器会删除 subBlock 的id并把当前激活成员的值重新发布到 canonical ID 之下。仓库中的真实样例是 Gmail 附件blocks/blocks/gmail.tsattachmentFilesbasic 模式的文件上传与attachmentsadvanced 模式的变量引用两个 SubBlock 共享canonicalParamId: attachments且两者required: false保持一致——正好对应上传basic 文件引用advanced的标准文件对模式。规则第四条进一步要求一个 canonical 对只承载一个概念。文件类概念就是上传 文件引用这一对。不要把 URL、提供商资源 ID 等替代标识符塞进 advanced 一侧——它们应当各自拥有独立 SubBlock把互斥来源标记为required: false并在执行期强制恰好一个。硬性规则三SubBlock 选项列表只有两种合法来源选项列表下拉选项等只能二选一selectorKey指向一个已注册的 selector——这是加载远程列表的唯一方式也是唯一能在画布之外正常工作的选项来源options静态数组或者是 block 自身值的纯函数。同时有两条禁令永远不要从 block 定义中发起 fetch永远不要在该位置读取 workflow stores。与凭据相关的两条约束值得单独强调凭据 SubBlock 必须声明canonicalParamId: oauthCredentialGmail block 中即可见该用法gmail.ts依赖方 selector 才能正确解析密钥secret绝不能出现在 selector 的getQueryKey中。此外文档指出bun run check:fork-dependent-coverage会对位于 credential/KB/table 锚点之下、而 fork 同步弹窗无法提供的dependsOn直接判失败——这是一条由 CI 脚本 scripts/check-fork-dependent-coverage.ts 兜底的静态约束。硬性规则四目录与 UI 元数据字段不可缺省每个 block 除了配置本体外还必须设置目录/UI 元数据字段integrationType、tags、authMode、docsLink并导出一个{Service}BlockMeta。字段细节由add-blockskill 的 BlockMeta 章节定义。从规则到流程add-integration skill 的端到端闭环规则文档声明这些红线来自更完整的作者指南 add-integration/SKILL.md。该指南把构建顺序展开为八个步骤研究 API明确禁止猜测未文档化的响应结构、创建 Tools、创建 Block、添加 Icon、可选 Trigger、注册、配置部署可用性OAuth client / service-account 元数据、生成并校验集成目录。与本文规则直接呼应的几处工程实践工具元数据再生成客户端代码从生成的产物中读取params/outputs而不是导入注册表因此注册新工具后必须运行bun run tool-metadata:generate并提交产物否则 UI 看不到该工具、CI 会因产物过期而失败目录页生成bun run scripts/generate-docs.ts会产出每个服务一页的集成文档apps/docs/content/docs/integrations/{service}.mdx其中 Actions 与 Triggers 小节均自动生成唯一可手改的是{/* MANUAL-CONTENT */}区域Icon 的裸渲染主题安全单色 logo 必须用fillcurrentColor而非硬编码黑白否则在浅色/深色模式下的裸图标场景会白底白图/黑底黑图由bun run check:bare-icons静态检查。校验命令速查以下命令均可在仓库根目录直接运行构成集成提交的本地闭环验证脚本入口见 package.jsonbun run check:fork-dependent-coverage # fork 同步弹窗无法提供的 dependsOn 直接失败 bun run check:tool-request-boundary # 工具请求边界InternalToolConfig vs 外部 HTTP bun run check:bare-icons # 图标裸渲染的主题安全隐患 bun run tool-metadata:generate # 再生成工具元数据产物 bun run deployment-config:generate # 再生成部署配置投影 bun run deployment-config:check # 比对已提交投影与来源 bun run integration-catalog:check # 集成目录一致性 bun run docs:check # 生成文档的 drift 检查过期即 CI 失败小结Sim 的集成规范可以用一句话概括按 Tools → Block → Icon → Trigger 的顺序构建把 ID 注册进正确的注册表并保持字母序然后严格遵守四条红线——强转在tools.config.params、canonicalParamId三约束且一对一概念、选项列表只来自selectorKey或纯本地options、目录元数据与{Service}BlockMeta齐备。规则文档负责划红线.claude/skills/下的 add-tools / add-block / add-trigger / add-integration 提供可复制的完整模板仓库自带的check:*与*:generate脚本则把每一条红线变成可自动验证的 CI 断言。【免费下载链接】simSim is the collaborative workspace to build, deploy, and monitor AI agents and workflows. Used by 100,000 builders.项目地址: https://gitcode.com/GitHub_Trending/sim16/sim创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考