# https://github.com/simstudioai/sim 项目说明书
生成时间：2026-05-11 19:14:22 UTC
## 目录
- [项目概述](#page-project-overview)
- [系统架构](#page-system-architecture)
- [工作流执行引擎](#page-workflow-execution)
- [块系统与注册表](#page-block-registry)
- [代理与AI集成](#page-agent-integration)
- [工作流编辑器](#page-workflow-editor)
- [实时协作与UI组件](#page-realtime-ui)
- [连接器框架](#page-connectors)
- [部署与基础设施](#page-deployment)
- [扩展与定制](#page-extensibility)
## 项目概述
### 相关页面
相关主题：[系统架构](#page-system-architecture), [部署与基础设施](#page-deployment)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/simstudioai/sim/blob/main/README.md)
- [apps/sim/package.json](https://github.com/simstudioai/sim/blob/main/apps/sim/package.json)
- [scripts/README.md](https://github.com/simstudioai/sim/blob/main/scripts/README.md)
- [packages/ts-sdk/README.md](https://github.com/simstudioai/sim/blob/main/packages/ts-sdk/README.md)
- [packages/python-sdk/README.md](https://github.com/simstudioai/sim/blob/main/packages/python-sdk/README.md)
- [apps/sim/lib/workflows/diff/diff-engine.test.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/diff/diff-engine.test.ts)
- [apps/sim/lib/webhooks/pending-verification.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/pending-verification.ts)
- [packages/testing/src/mocks/env.mock.ts](https://github.com/simstudioai/sim/blob/main/packages/testing/src/mocks/env.mock.ts)
# 项目概述
## 1. 项目简介
Sim 是一个可视化的工作流自动化平台，旨在帮助用户通过直观的拖拽式界面构建、部署和执行复杂的自动化流程。该项目由 SimStudio 团队开发，支持本地部署和云端托管两种模式，并提供了 TypeScript 和 Python 两种 SDK 供开发者集成。
Sim 的核心功能包括：
- **可视化工作流编辑器**：通过图形化界面设计自动化流程
- **多平台 Webhook 集成**：支持 Webflow、Gong、Typeform、Vercel 等多种第三方服务
- **实时执行引擎**：支持同步和异步两种执行模式
- **沙箱执行环境**：安全地运行用户代码和自定义逻辑
- **AI Copilot**：集成 AI 能力辅助工作流构建
- **PPTX 渲染引擎**：支持 PowerPoint 文件的解析和展示
## 2. 技术架构
### 2.1 技术栈概览
| 类别 | 技术选型 |
|------|----------|
| 前端框架 | Next.js |
| 包管理器 | Bun |
| 运行时 | Node.js v20+ |
| 数据库 | PostgreSQL 12+ with pgvector |
| 容器化 | Docker, Docker Compose |
| 开发语言 | TypeScript |
| SDK | TypeScript, Python |
资料来源：[README.md:1-20](https://github.com/simstudioai/sim/blob/main/README.md)
### 2.2 应用架构
Sim 项目采用 monorepo 结构，主要包含以下应用模块：
```
sim/
├── apps/
│ ├── sim/ # 主应用程序（Next.js）
│ └── realtime/ # 实时执行服务
├── packages/
│ ├── ts-sdk/ # TypeScript SDK
│ ├── python-sdk/ # Python SDK
│ └── testing/ # 测试工具库
└── scripts/ # 构建和文档生成脚本
```
资料来源：[apps/sim/package.json:1-15](https://github.com/simstudioai/sim/blob/main/apps/sim/package.json)
### 2.3 核心模块架构图
```mermaid
graph TD
subgraph "前端层"
A[Web UI] --> B[Workflow Editor]
A --> C[Block Configuration]
A --> D[Execution Dashboard]
end
subgraph "核心服务层"
E[Workflow Engine] --> F[Block Registry]
E --> G[Trigger System]
E --> H[Execution Engine]
end
subgraph "集成层"
I[Webhook Providers] --> J[Event Filter]
I --> K[Verification Service]
L[Tool Adapters] --> H
end
subgraph "数据层"
M[(PostgreSQL + pgvector)]
N[Redis Cache]
end
subgraph "SDK 层"
O[TypeScript SDK]
P[Python SDK]
end
H --> M
H --> N
O --> E
P --> E
```
## 3. 核心功能模块
### 3.1 工作流引擎
工作流引擎是 Sim 平台的核心组件，负责解析、验证和执行用户定义的工作流。
#### 3.1.1 工作流组件
| 组件 | 功能描述 |
|------|----------|
| Block | 工作流中的基本执行单元 |
| Loop Block | 循环控制块，支持 for 循环 |
| Parallel Block | 并行执行块 |
| Trigger | 触发器，定义工作流启动条件 |
| Subflow | 子流程，嵌套的工作流片段 |
资料来源：[apps/sim/lib/workflows/diff/diff-engine.test.ts:1-50](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/diff/diff-engine.test.ts)
#### 3.1.2 执行模式
Sim 支持两种执行模式：
- **同步执行**：等待工作流完成并返回结果
- **异步执行**：将任务加入队列，立即返回任务 ID
```typescript
interface ExecutionOptions {
timeout?: number;
stream?: boolean;
selectedOutputs?: string[];
async?: boolean;
}
```
资料来源：[packages/ts-sdk/README.md:1-50](https://github.com/simstudioai/sim/blob/main/packages/ts-sdk/README.md)
### 3.2 Webhook 系统
Sim 提供了强大的 Webhook 集成能力，支持多种第三方服务。
#### 3.2.1 支持的 Webhook 提供商
| 提供商 | 验证方式 | 特殊配置 |
|--------|----------|----------|
| Ashby | 自定义 | `action === 'ping'` |
| Grain | 自定义 | GET/HEAD 请求自动验证 |
| Generic | 自定义 | 支持 `verifyTestEvents` 元数据 |
| Salesforce | 自定义 | 多种请求类型 |
| Webflow | - | 支持 `collectionId` 过滤 |
| Gong | - | 通话元数据解析 |
| Typeform | HMAC | 支持 `includeDefinition` |
| Vercel | - | 部署和项目信息 |
资料来源：[apps/sim/lib/webhooks/pending-verification.ts:1-30](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/pending-verification.ts)
#### 3.2.2 Webhook 事件过滤机制
```typescript
interface EventFilterContext {
webhook: Webhook;
body: Record;
requestId: string;
providerConfig: Record;
}
```
Webflow 提供商实现了集合 ID 过滤功能，只有匹配配置中指定 `collectionId` 的事件才会被处理：
```typescript
shouldSkipEvent({ webhook, body, requestId, providerConfig }: EventFilterContext) {
const configuredCollectionId = providerConfig.collectionId as string | undefined
// ... 过滤逻辑
}
```
资料来源：[apps/sim/lib/webhooks/providers/webflow.ts:1-60](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/providers/webflow.ts)
### 3.3 块系统与文档生成
Sim 使用块（Block）作为构建工作流的基本单元。每个块包含元数据、输入输出规范和配置参数。
#### 3.3.1 文档生成器
`scripts/generate-docs.ts` 脚本自动扫描 `apps/sim/blocks/blocks/` 目录，提取所有块定义文件的元数据并生成标准化 Markdown 文档。
工作流程：
1. 扫描块定义文件目录
2. 提取块元数据（名称、描述、分类）
3. 提取输入输出规范
4. 提取配置参数
5. 生成 Markdown 文档
6. 更新 `meta.json` 导航元数据
资料来源：[scripts/README.md:1-40](https://github.com/simstudioai/sim/blob/main/scripts/README.md)
#### 3.3.2 块类型定义
```typescript
interface ToolBlockRecord {
type: string;
title?: string;
toolId?: string;
operation?: string;
params?: Record;
customToolId?: string;
code?: string;
usageControl?: 'auto' | 'force' | 'none';
isExpanded?: boolean;
schema?: StoredToolSchema;
}
```
资料来源：[apps/sim/lib/workflows/tool-input/types.ts:1-40](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/tool-input/types.ts)
### 3.4 实时执行服务
实时执行服务（Realtime Service）负责处理工作流的运行时操作，包括状态管理和数据持久化。
#### 3.4.1 数据库操作
```mermaid
graph LR
A[Workflow Update] --> B[Validate Blocks]
B --> C[Upsert Workflow Blocks]
C --> D{Block Type}
D -->|Loop| E[Create Subflow Entry]
D -->|Parallel| F[Create Subflow Entry]
E --> G[Commit Transaction]
F --> G
```
工作流更新操作使用 PostgreSQL 的 `ON CONFLICT DO UPDATE` 语法进行原子性更新：
```typescript
await tx
.insert(workflowBlocks)
.values(blockValues)
.onConflictDoUpdate({
target: workflowBlocks.id,
set: {
type: sql`excluded.type`,
name: sql`excluded.name`,
// ... 其他字段
updatedAt: sql`now()`,
},
})
```
资料来源：[apps/realtime/src/database/operations.ts:1-60](https://github.com/simstudioai/sim/blob/main/apps/realtime/src/database/operations.ts)
### 3.5 PPTX 渲染引擎
Sim 内置了 PowerPoint 文件的解析和渲染能力，位于 `apps/sim/lib/pptx-renderer/` 目录。
#### 3.5.1 渲染特性
- 解析 OOXML 格式的 PPTX 文件
- 支持 WPS Office 和 Microsoft Office 格式识别
- 基于关系 ID 而非数字幻灯片 ID 的排序逻辑
- 支持窗口化列表渲染（用于大型演示文稿）
```typescript
interface SIM_PPTX_LIST_OPTIONS {
// 窗口化渲染配置
}
```
资料来源：[apps/sim/lib/pptx-renderer/sim-pptx-viewer.test.ts:1-50](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/pptx-renderer/sim-pptx-viewer.test.ts)
### 3.6 AI Copilot 集成
Sim 平台集成了 AI Copilot 功能，提供智能化的工作流构建辅助。
#### 3.6.1 Copilot 通信协议
Copilot 使用流式通信协议，支持多种消息类型：
```typescript
interface SyntheticFilePreviewPayload {
toolCallId: string;
toolName: 'workspace_file';
previewPhase: 'start' | 'target' | 'editMeta' | 'content';
content?: string;
contentMode?: 'delta' | 'snapshot';
previewVersion?: number;
}
```
资料来源：[apps/sim/lib/copilot/request/session/contract.ts:1-80](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/copilot/request/session/contract.ts)
## 4. SDK 文档
### 4.1 TypeScript SDK
TypeScript SDK 提供了与 Sim 平台交互的完整接口。
#### 4.1.1 核心类
| 类名 | 功能 |
|------|------|
| `SimStudio` | 主客户端类 |
| `SimStudioError` | 错误处理类，继承自 Error |
| `WorkflowExecutionResult` | 执行结果数据类 |
| `WorkflowStatus` | 工作流状态类 |
| `AsyncExecutionResult` | 异步执行结果 |
资料来源：[packages/ts-sdk/README.md:50-120](https://github.com/simstudioai/sim/blob/main/packages/ts-sdk/README.md)
#### 4.1.2 速率限制与用量
```typescript
interface UsageLimits {
success: boolean;
rateLimit: {
sync: {
isLimited: boolean;
limit: number;
remaining: number;
resetAt: string;
};
async: {
isLimited: boolean;
limit: number;
remaining: number;
resetAt: string;
};
authType: string;
};
}
```
### 4.2 Python SDK
Python SDK 提供 Python 环境的集成支持。
#### 4.2.1 安装要求
| 要求 | 最低版本 |
|------|----------|
| Python | 3.8+ |
| requests | 2.25.0+ |
资料来源：[packages/python-sdk/README.md:1-30](https://github.com/simstudioai/sim/blob/main/packages/python-sdk/README.md)
#### 4.2.2 代码质量工具
Python SDK 使用以下工具保证代码质量：
| 工具 | 用途 |
|------|------|
| black | 代码格式化 |
| flake8 | 代码检查 |
| mypy | 类型检查 |
| isort | 导入排序 |
## 5. 部署方式
### 5.1 部署方式对比
| 方式 | 难度 | 适用场景 | 要求 |
|------|------|----------|------|
| NPM 在线版 | ⭐ | 快速体验 | 互联网连接 |
| Docker (npx) | ⭐⭐ | 本地开发 | Docker |
| Docker Compose | ⭐⭐ | 生产部署 | Docker |
| 手动安装 | ⭐⭐⭐ | 深度定制 | Bun, Node.js, PostgreSQL |
资料来源：[README.md:20-60](https://github.com/simstudioai/sim/blob/main/README.md)
### 5.2 Docker 部署配置
Docker 部署支持以下配置选项：
| 标志 | 描述 | 默认值 |
|------|------|--------|
| `-p, --port ` | 运行端口 | `3000` |
| `--no-pull` | 跳过拉取最新镜像 | false |
### 5.3 手动安装要求
- **Bun**: JavaScript 运行时和包管理器
- **Node.js**: v20+
- **PostgreSQL**: 12+ with pgvector 扩展
- **Redis**: 可选，用于缓存
### 5.4 本地模型支持
Sim 支持使用本地大语言模型：
- **Ollama**: 本地模型推理服务
- **vLLM**: 高性能推理引擎
详情请参阅 [Docker self-hosting docs](https://docs.sim.ai/self-hosting/docker)。
## 6. 开发指南
### 6.1 项目初始化
```bash
# 克隆仓库
git clone https://github.com/simstudioai/sim.git
cd sim
# 安装依赖
bun install
# 初始化
bun run prepare # 设置 pre-commit hooks
```
资料来源：[README.md:40-50](https://github.com/simstudioai/sim/blob/main/README.md)
### 6.2 环境变量配置
Sim 使用集中化的环境配置系统：
```typescript
interface EnvConfig {
NEXT_PUBLIC_APP_URL?: string;
// ... 其他配置
}
```
资料来源：[packages/testing/src/mocks/env.mock.ts:1-50](https://github.com/simstudioai/sim/blob/main/packages/testing/src/mocks/env.mock.ts)
### 6.3 构建与测试
| 命令 | 功能 |
|------|------|
| `bun run build` | 构建生产版本 |
| `bun run test` | 运行测试 |
| `bun run test:watch` | 监听模式运行测试 |
| `bun run lint` | 代码检查并修复 |
| `bun run type-check` | TypeScript 类型检查 |
资料来源：[apps/sim/package.json:15-30](https://github.com/simstudioai/sim/blob/main/apps/sim/package.json)
### 6.4 负载测试
Sim 提供了 Artillery 负载测试脚本：
| 命令 | 描述 |
|------|------|
| `bun run load:workflow:waves` | 波浪式负载测试 |
| `bun run load:workflow:isolation` | 工作空间隔离测试 |
## 7. CI/CD 集成
Sim 项目集成了完整的 CI/CD 流程：
- 文档生成器在 main 分支推送时自动运行
- 更新的文档会自动提交回仓库
- 代码质量检查（lint、type-check）集成在 CI 流程中
## 8. 总结
Sim 是一个功能完整的可视化工作流自动化平台，其技术特点包括：
1. **现代化技术栈**：基于 Next.js、Bun、TypeScript 构建
2. **灵活的部署方式**：支持云端、本地 Docker 和手动部署
3. **丰富的集成能力**：支持多种 Webhook 提供商和工具适配
4. **完善的 SDK 支持**：提供 TypeScript 和 Python 两种 SDK
5. **AI 能力集成**：内置 Copilot 支持智能化工作流构建
6. **企业级功能**：包括速率限制、用量监控、沙箱执行等
---
## 系统架构
### 相关页面
相关主题：[项目概述](#page-project-overview), [工作流执行引擎](#page-workflow-execution), [实时协作与UI组件](#page-realtime-ui)
相关源码文件
以下源码文件用于生成本页说明：
- [apps/sim/app](https://github.com/simstudioai/sim/blob/main/apps/sim/app)
- [apps/realtime/src](https://github.com/simstudioai/sim/blob/main/apps/realtime/src)
- [apps/realtime/src/index.ts](https://github.com/simstudioai/sim/blob/main/apps/realtime/src/index.ts)
- [packages/db](https://github.com/simstudioai/sim/blob/main/packages/db)
- [packages/ts-sdk/README.md](https://github.com/simstudioai/sim/blob/main/packages/ts-sdk/README.md)
- [packages/python-sdk/README.md](https://github.com/simstudioai/sim/blob/main/packages/python-sdk/README.md)
- [apps/sim/package.json](https://github.com/simstudioai/sim/blob/main/apps/sim/package.json)
- [packages/cli/README.md](https://github.com/simstudioai/sim/blob/main/packages/cli/README.md)
# 系统架构
## 概述
Sim 是一个开源平台，用于构建 AI 代理并运行代理工作流。该平台连接超过 1000 种集成和大语言模型（LLM），以编排代理工作流。Sim 采用现代化全栈架构，基于 Next.js 框架构建，支持自托管部署和云端服务。
技术栈核心组件包括：
| 类别 | 技术选型 | 说明 |
|------|----------|------|
| 前端框架 | Next.js (App Router) | 支持 SSR/SSG 的 React 框架 |
| 运行时 | Bun | 高性能 JavaScript 运行时和打包工具 |
| 数据库 | PostgreSQL + pgvector | 支持向量存储的关系型数据库 |
| ORM | Drizzle ORM | 类型安全的数据库操作层 |
| 认证 | Better Auth | 现代化身份认证解决方案 |
| 模式验证 | Zod | TypeScript 优先的模式验证库 |
| UI 组件 | Shadcn + Tailwind CSS | 可定制的设计系统 |
| 状态管理 | Zustand + TanStack Query | 客户端状态与服务器状态管理 |
| 实时通信 | WebSocket | Socket 服务器处理实时交互 |
资料来源：[README.md:1-50]()
## 整体架构
Sim 平台采用微前端和多服务架构，主要包含以下核心模块：
```mermaid
graph TD
A[客户端浏览器] --> B[Next.js Web 应用]
A --> C[Sim CLI]
B --> D[PostgreSQL 数据库]
B --> E[实时 Socket 服务]
B --> F[工作流执行引擎]
F --> D
E --> F
G[TypeScript SDK] --> B
H[Python SDK] --> B
I[CLI 工具] --> B
```
### 应用层模块
#### Web 应用 (apps/sim)
主应用程序采用 Next.js App Router 架构，核心目录结构如下：
| 目录 | 功能 |
|------|------|
| `app/` | Next.js App Router 页面和 API 路由 |
| `blocks/` | 预构建的工作流块定义 |
| `lib/` | 核心业务逻辑库 |
| `components/` | React UI 组件 |
| `stores/` | Zustand 状态管理 stores |
| `hooks/` | 自定义 React Hooks |
资料来源：[apps/sim/package.json:1-30]()
#### 实时服务 (apps/realtime)
独立的 Socket 服务器处理实时通信功能，包括：
- 工作流执行状态的实时推送
- Copilot 交互的流式响应
- 协作编辑的实时同步
实时服务通过 WebSocket 协议与应用层通信，采用独立的部署单元以确保可扩展性。
资料来源：[apps/realtime/src/index.ts](https://github.com/simstudioai/sim/blob/main/apps/realtime/src/index.ts)
### 数据层
#### 数据库架构
Sim 使用 PostgreSQL 作为主数据库，并通过 Drizzle ORM 提供类型安全的数据访问层：
```mermaid
graph LR
A[应用层] --> B[Drizzle ORM]
B --> C[PostgreSQL]
C --> D[pgvector 扩展]
```
关键数据库表结构通过迁移脚本管理，位于 `packages/db/migrations/` 目录。数据库迁移命令：
```bash
cd packages/db && bun run db:migrate
```
#### pgvector 集成
平台集成 pgvector 扩展以支持向量存储和语义搜索功能，这对于 AI 代理的相似度匹配和知识检索至关重要。
资料来源：[README.md:30-40]()
## 工作流引擎架构
### 执行模型
工作流执行采用分层架构，支持同步和异步两种执行模式：
```mermaid
graph TD
A[API 触发器] --> B[工作流调度器]
B --> C{执行模式}
C -->|同步| D[沙箱执行器]
C -->|异步| E[任务队列]
D --> F[块处理器]
E --> G[Worker 进程]
G --> F
F --> H[输出处理器]
H --> I[结果聚合]
```
### 沙箱执行
工作流中的代码块在隔离的沙箱环境中执行，确保安全性和隔离性。沙箱打包通过专门的构建脚本生成：
```bash
bun run build:sandbox-bundles
```
资料来源：[apps/sim/package.json:8]()
### 块系统 (Blocks)
块是工作流的基本构建单元，每个块定义包含：
| 属性 | 说明 |
|------|------|
| `name` | 块名称 |
| `description` | 功能描述 |
| `category` | 分类标签 |
| `inputs` | 输入规格定义 |
| `outputs` | 输出规格定义 |
| `config` | 配置参数 |
块文档通过自动化脚本生成，位于 `scripts/generate-docs.ts`。运行文档生成：
```bash
bun run scripts/generate-docs.ts
```
资料来源：[scripts/README.md:1-25]()
## SDK 架构
### TypeScript SDK
TypeScript SDK (`packages/ts-sdk`) 提供完整的客户端集成能力：
```typescript
import { SimStudioClient } from '@simstudio/ts-sdk'
const client = new SimStudioClient({
apiKey: process.env.SIM_API_KEY,
baseUrl: 'https://sim.ai'
})
```
核心接口包括：
| 接口 | 功能 |
|------|------|
| `executeWorkflow` | 执行工作流 |
| `getWorkflowStatus` | 查询工作流状态 |
| `getExecutionResult` | 获取执行结果 |
| `uploadFile` | 文件上传 |
资料来源：[packages/ts-sdk/README.md:1-50]()
### Python SDK
Python SDK (`packages/python-sdk`) 提供 Python 生态的集成支持：
```python
from simstudio import SimStudioClient
client = SimStudioClient(api_key=os.getenv("SIM_API_KEY"))
result = client.execute_workflow('workflow-id', input_data)
```
文件上传自动转换为 base64 格式，支持单文件和批量上传场景。
资料来源：[packages/python-sdk/README.md:1-40]()
## 认证与安全
### 认证方案
平台使用 Better Auth 作为认证解决方案，支持：
- OAuth 社交登录
- API Key 认证
- Webhook 签名验证
### Webhook 安全
Webhook 提供商实现 HMAC 签名验证机制：
```mermaid
graph TD
A[外部服务] -->|POST + 签名| B[Webhook 端点]
B --> C[验证签名]
C -->|有效| D[处理事件]
C -->|无效| E[拒绝请求]
```
支持的 Webhook 提供商包括 Gong、Webflow、Typeform 等，各提供商使用独立的签名验证策略。
资料来源：[lib/webhooks/providers/typeform.ts:20-40]()
## 部署架构
### 部署模式
Sim 支持多种部署方式：
| 部署方式 | 说明 | 适用场景 |
|----------|------|----------|
| Docker (npx) | 一键启动本地容器 | 快速原型验证 |
| Docker Compose | 完整服务编排 | 自托管生产环境 |
| 手动部署 | 细粒度控制 | 高级定制需求 |
| Helm Charts | Kubernetes 部署 | 企业级集群环境 |
### Docker 部署
使用 Docker Compose 部署完整生产环境：
```bash
git clone https://github.com/simstudioai/sim.git
cd sim
docker compose -f docker-compose.prod.yml up -d
```
### Kubernetes 部署
Helm Charts 提供 Kubernetes 原生部署支持，核心配置参数：
| 参数 | 说明 | 默认值 |
|------|------|--------|
| `app.image.repository` | 应用镜像仓库 | simstudioai/sim |
| `app.service.port` | 服务端口 | 3000 |
| `realtime.enabled` | 启用实时服务 | true |
| `realtime.replicaCount` | 实时服务副本数 | 1 |
| `realtime.service.port` | 实时服务端口 | 3002 |
资料来源：[helm/sim/README.md:1-30]()
## 开发环境
### 环境准备
开发环境要求：
- Bun v1.0+
- Node.js v20+
- PostgreSQL 12+ (启用 pgvector)
- Docker (可选，用于数据库)
### 本地开发
```bash
# 克隆仓库
git clone https://github.com/simstudioai/sim.git
cd sim
# 安装依赖
bun install
# 初始化数据库
docker run --name simstudio-db -e POSTGRES_PASSWORD=password \
-e POSTGRES_DB=simstudio -p 5432:5432 -d pgvector/pgvector
cd packages/db && bun run db:migrate
# 启动开发服务器
bun run dev:full # 启动 Next.js 和 Socket 服务器
```
### 可用脚本
| 脚本 | 功能 |
|------|------|
| `bun run dev` | 启动 Next.js 开发服务器 |
| `bun run dev:sockets` | 启动 Socket 服务器 |
| `bun run test` | 运行单元测试 |
| `bun run build` | 构建生产版本 |
| `bun run lint` | 代码风格检查 |
资料来源：[README.md:40-60]()
## 配置管理
### 环境变量
核心环境变量配置：
| 变量 | 说明 | 必需 |
|------|------|------|
| `DATABASE_URL` | PostgreSQL 连接字符串 | 是 |
| `COPILOT_API_KEY` | Copilot 服务 API Key | 可选 |
| `SIM_API_KEY` | 第三方 SDK 认证 | 可选 |
完整环境变量列表参考 `apps/sim/.env.example`。
### 负载测试配置
平台内置 Artillery 负载测试脚本，支持多种测试场景：
| 脚本 | 场景 |
|------|------|
| `load:workflow:waves` | 波浪式负载测试 |
| `load:workflow:isolation` | 隔离工作区负载测试 |
资料来源：[apps/sim/package.json:5-10]()
## 扩展机制
### 触发器系统
工作流支持多种触发类型，优先级排序如下：
| 优先级 | 触发类型 | 说明 |
|--------|----------|------|
| 0 | Unified Start | 统一启动块 |
| 1 | Legacy Starter | 遗留启动块 |
| 2 | Schedule | 定时调度 |
| 3 | Webhook | 外部 Webhook |
| 4-7 | 其他 | API、手动、聊天触发 |
触发器选择逻辑通过 `trigger-utils.ts` 中的优先级算法确定。
资料来源：[lib/workflows/triggers/trigger-utils.ts:1-30]()
### Webhook 提供商集成
平台原生支持多个第三方服务的 Webhook 集成：
- **Gong**: 通话记录和会议分析
- **Webflow**: CMS 内容更新事件
- **Typeform**: 表单提交事件
- **Ashby**: ATS 招聘事件
- **Salesforce**: CRM 事件
每个提供商实现独立的格式转换和签名验证逻辑。
资料来源：[lib/webhooks/providers/gong.ts:1-20]()
资料来源：[lib/webhooks/providers/webflow.ts:1-30]()
## 监控与可观测性
### 执行追踪
工作流执行支持完整的追踪机制：
```mermaid
graph LR
A[执行请求] --> B[追踪开始]
B --> C[块执行]
C --> D[输出生成]
D --> E[追踪结束]
```
追踪数据包含执行时间戳、输入输出快照和错误信息。
### 待验证 Webhook 处理
平台实现待验证 Webhook 的自动探测和处理机制，防止验证请求被当作正式事件处理：
```typescript
const pendingWebhookVerificationProbeMatchers = {
ashby: ({ method, body }) => method === 'POST' && body?.action === 'ping',
grain: ({ method, body }) => method === 'GET' || method === 'HEAD' || body?.type === undefined,
// ...
}
```
资料来源：[lib/webhooks/pending-verification.ts:1-30]()
---
## 工作流执行引擎
### 相关页面
相关主题：[系统架构](#page-system-architecture), [块系统与注册表](#page-block-registry), [代理与AI集成](#page-agent-integration)
相关源码文件
以下源码文件用于生成本页说明：
- [apps/sim/lib/workflows/triggers/trigger-utils.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/triggers/trigger-utils.ts)
- [apps/sim/lib/workflows/triggers/triggers.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/triggers/triggers.ts)
- [apps/sim/lib/workflows/diff/diff-engine.test.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/diff/diff-engine.test.ts)
- [apps/sim/executor/dag/builder.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/executor/dag/builder.ts) *(未获取到具体内容)*
- [apps/sim/executor/dag/types.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/executor/dag/types.ts) *(未获取到具体内容)*
- [apps/sim/executor/execution/engine.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/executor/execution/engine.ts) *(未获取到具体内容)*
- [apps/sim/executor/execution/executor.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/executor/execution/executor.ts) *(未获取到具体内容)*
- [apps/sim/executor/execution/snapshot.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/executor/execution/snapshot.ts) *(未获取到具体内容)*
> **注意**：部分核心执行引擎文件未能在当前上下文中获取，以下内容基于可访问的触发器和DAG差异引擎相关代码进行推断和分析。
# 工作流执行引擎
## 概述
Sim 平台的工作流执行引擎是一个基于有向无环图（DAG）的自动化执行系统，负责解析、编排和执行用户定义的工作流程。该引擎支持多种触发方式、循环结构、并行执行以及复杂的数据流转，是整个自动化平台的核心运行时组件。
工作流执行引擎的核心职责包括：
1. **DAG 构建**：将用户配置的工作流转换为可执行的有向无环图结构
2. **触发器管理**：支持手动、API、Webhook、定时调度等多种触发方式
3. **块执行编排**：按照依赖关系顺序执行各个功能块
4. **状态管理**：维护执行过程中的状态，支持暂停、恢复和快照
5. **输出处理**：管理块之间的数据传递和变量绑定
资料来源：[apps/sim/executor/orchestrators](https://github.com/simstudioai/sim/blob/main/apps/sim/executor/orchestrators)
---
## 核心架构
### 执行引擎分层
```
┌─────────────────────────────────────────────────────────────┐
│ 触发层 (Triggers) │
│ 手动触发 │ API触发 │ Webhook触发 │ 定时调度 │ 聊天触发 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 编排层 (Orchestrators) │
│ 循环编排器 │ 并行编排器 │ 顺序编排器 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 执行层 (Execution Engine) │
│ DAG构建器 │ 执行器 │ 快照管理 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 沙箱层 (Sandbox) │
│ 块代码执行环境 │ 工具函数调用 │
└─────────────────────────────────────────────────────────────┘
```
### 触发器优先级系统
触发器系统采用优先级评分机制来选择最佳触发路径。当工作流存在多个可能的触发点时，系统按以下顺序选择：
| 优先级 | 触发路径 | 说明 |
|--------|----------|------|
| 0 | `UNIFIED` | 统一入口块，最优先 |
| 1 | `LEGACY_STARTER` | 传统起始块，兼容旧版本 |
| 2 | `EXTERNAL_TRIGGER` (schedule) | 定时调度触发器 |
| 3 | `EXTERNAL_TRIGGER` (其他) | Webhook 及外部集成触发 |
| 4 | `SPLIT_API` | API 拆分触发 |
| 5 | `SPLIT_INPUT` | 输入拆分触发 |
| 6 | `SPLIT_MANUAL` | 手动拆分触发 |
| 7 | `SPLIT_CHAT` | 聊天拆分触发 |
| 99 | 未知 | 兜底默认值 |
资料来源：[apps/sim/lib/workflows/triggers/trigger-utils.ts:3-19](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/triggers/trigger-utils.ts)
---
## 触发器系统
### 触发类型
Sim 平台定义了以下触发类型：
```typescript
export const TRIGGER_TYPES = {
START: 'start',
API: 'api',
CHAT: 'chat',
STARTER: 'starter',
} as const
```
### 启动模式
每个触发块支持三种启动模式：
| 模式值 | 说明 | 触发路径 |
|--------|------|----------|
| `manual` | 手动触发 | 启动模式为 undefined 或 'manual' |
| `api` | API 调用触发 | 启动模式为 'api' 或 'run' |
| `chat` | 聊天会话触发 | 启动模式为 'chat' |
资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:1-20](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/triggers/triggers.ts)
### 触发器引用别名
系统提供别名映射，简化内联引用：
```typescript
export const TRIGGER_REFERENCE_ALIAS_MAP = {
start: TRIGGER_TYPES.START,
api: TRIGGER_TYPES.API,
chat: TRIGGER_TYPES.CHAT,
manual: TRIGGER_TYPES.START,
} as const
```
### 触发器工具类
`TriggerUtils` 类提供静态方法用于触发器识别：
| 方法 | 用途 |
|------|------|
| `isTriggerBlock(block)` | 判断块是否为任意类型的触发器 |
| `isTriggerType(block, triggerType)` | 判断块是否为指定类型的触发器 |
判断逻辑包括三个维度：
1. 显式分类：块配置的 `category === 'triggers'`
2. 触发模式标志：`block.triggerMode === true`
3. 遗留兼容：`block.type === TRIGGER_TYPES.STARTER`
资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:40-55](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/triggers/triggers.ts)
### 模拟负载判断
对于外部触发器，系统需要判断是否需要生成模拟负载：
```typescript
export function triggerNeedsMockPayload(
trigger: StartBlockCandidate
): boolean {
// 只有 webhook 和外部集成需要模拟负载
// 定时调度正常运行，无需模拟数据
return trigger.path === StartBlockPath.EXTERNAL_TRIGGER && trigger.block.type !== 'schedule'
}
```
资料来源：[apps/sim/lib/workflows/triggers/trigger-utils.ts:40-47](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/triggers/trigger-utils.ts)
---
## DAG 执行图构建
### 块类型系统
执行引擎通过块注册表管理所有可用块：
```typescript
// 测试中的 Mock 配置示例
vi.mock('@/blocks', () => ({
getBlock: () => null,
getAllBlocks: () => ({}),
getAllBlockTypes: () => [],
getBlockByToolName: () => null,
getBlocksByCategory: () => [],
isValidBlockType: () => false,
registry: {},
}))
```
### 块分类
块按功能分为多个类别：
| 分类 | 说明 | 示例 |
|------|------|------|
| `triggers` | 触发器块 | 定时调度、Webhook、API |
| `actions` | 动作块 | 发送消息、调用API |
| `logic` | 逻辑块 | 条件判断、循环 |
| `transform` | 转换块 | 数据转换、映射 |
### 循环与并行
系统支持两种高级执行模式：
```typescript
// 循环块生成
generateLoopBlocks: () => ({})
// 并行块生成
generateParallelBlocks: () => ({})
```
---
## 执行状态管理
### 快照机制
执行引擎支持执行快照功能，允许暂停和恢复工作流执行：
```typescript
vi.mock('@/lib/workflows/blocks/block-outputs', () => ({
getEffectiveBlockOutputs: () => ({}),
}))
```
快照功能涉及：
- 块输出状态持久化
- 执行进度记录
- 变量上下文保存
资料来源：[apps/sim/executor/execution/snapshot.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/executor/execution/snapshot.ts)
### 执行维度
执行引擎定义了块执行的约束维度：
```typescript
vi.mock('@/executor/constants', () => ({
isAnnotationOnlyBlock: () => false,
BLOCK_DIMENSIONS: { MIN_HEIGHT: 100 },
HANDLE_POSITIONS: {},
}))
```
---
## Webhook 事件处理
### 待验证 Webhook
系统为不同提供商实现了 webhook 验证机制：
| 提供商 | 验证策略 |
|--------|----------|
| `ashby` | 始终通过（仅 ping） |
| `grain` | GET/HEAD 请求直接通过 |
| `generic` | `verifyTestEvents` 元数据为 true 时通过 |
| `salesforce` | GET/HEAD 请求直接通过 |
```typescript
const pendingWebhookVerificationProbeMatchers: Record<
string,
PendingWebhookVerificationProbeMatcher
> = {
ashby: ({ method, body }) => method === 'POST' && body?.action === 'ping',
grain: ({ method, body }) =>
method === 'GET' ||
method === 'HEAD' ||
(method === 'POST' && (!body || Object.keys(body).length === 0 || !body.type)),
generic: ({ method, body }) =>
method === 'GET' ||
method === 'HEAD' ||
(method === 'POST' && (!body || Object.keys(body).length === 0)),
salesforce: ({ method, body }) =>
method === 'GET' ||
method === 'HEAD' ||
(method === 'POST' && (!body || Object.keys(body).length === 0)),
}
```
资料来源：[apps/sim/lib/webhooks/pending-verification.ts:1-30](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/pending-verification.ts)
---
## 执行流程图
### 完整执行生命周期
```mermaid
graph TD
A[工作流启动] --> B{选择触发器}
B -->|手动| C[manual 模式]
B -->|API| D[api 模式]
B -->|Webhook| E[external_trigger 模式]
B -->|定时| F[schedule 模式]
B -->|聊天| G[chat 模式]
C --> H[DAG 构建]
D --> H
E --> H
F --> H
G --> H
H --> I{检查循环块}
I -->|是| J[展开循环迭代]
I -->|否| K{检查并行块}
J --> K
K -->|是| L[并行执行分支]
K -->|否| M[顺序执行]
L --> N[收集块输出]
M --> N
N --> O[数据传递]
O --> P{还有更多块?}
P -->|是| I
P -->|否| Q[生成执行快照]
Q --> R[工作流完成]
```
---
## 配置与常量
### 执行常量定义
| 常量 | 说明 | 默认值 |
|------|------|--------|
| `BLOCK_DIMENSIONS.MIN_HEIGHT` | 块最小高度 | 100 |
| `HANDLE_POSITIONS` | 连接点位置配置 | 空对象 |
### 环境配置
执行引擎使用统一的环境配置系统：
```typescript
vi.mock('@/lib/core/config/env', () => createEnvMock())
```
环境变量支持类型转换和默认值：
```typescript
envNumber: (
value: number | string | undefined | null,
fallback: number,
options: { min?: number } = {}
): number => {
const min = options.min ?? 0
if (typeof value === 'number' && Number.isFinite(value) && value >= min) return value
if (value === undefined || value === null || value === '') return fallback
const parsed = Number(value)
return Number.isFinite(parsed) && parsed >= min ? parsed : fallback
}
```
资料来源：[packages/testing/src/mocks/env.mock.ts:1-50](https://github.com/simstudioai/sim/blob/main/packages/testing/src/mocks/env.mock.ts)
---
## 测试与调试
### 执行引擎测试
项目使用 Vitest 作为测试框架：
```bash
bun run test # 运行所有测试
bun run test:watch # 监听模式
bun run test:coverage # 覆盖率报告
```
### 常见 Mock 配置
在测试中，核心模块通过以下方式隔离：
```typescript
vi.mock('@/stores/workflows/registry/store', () => ({
useWorkflowRegistry: {
getState: () => ({
activeWorkflowId: null,
}),
},
}))
vi.mock('@/tools/utils', () => ({
getTool: () => null,
}))
vi.mock('@/lib/workflows/subblocks/visibility', () => ({
buildDefaultCanonicalModes: () => ({}),
}))
```
资料来源：[apps/sim/lib/workflows/diff/diff-engine.test.ts:1-70](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/diff/diff-engine.test.ts)
---
## 最佳实践
### 触发器选择
1. **优先使用统一入口**：对于新工作流，使用 `UNIFIED` 触发器
2. **外部集成用 Webhook**：需要接收外部事件时使用 `EXTERNAL_TRIGGER`
3. **定时任务用 Schedule**：周期性任务使用 schedule 类型触发器
### 执行性能
1. **减少循环嵌套深度**：深层循环会影响执行性能
2. **合理使用并行块**：独立任务应使用并行执行
3. **优化块输出**：避免传递过大的数据对象
### 错误处理
1. **配置超时时间**：为长时间运行的块设置合理超时
2. **使用条件块**：在关键路径添加条件判断
3. **利用快照恢复**：定期保存执行快照以便故障恢复
---
## 块系统与注册表
### 相关页面
相关主题：[工作流执行引擎](#page-workflow-execution), [连接器框架](#page-connectors)
相关源码文件
以下源码文件用于生成本页说明：
- [apps/sim/lib/workflows/diff/diff-engine.test.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/diff/diff-engine.test.ts)
- [apps/sim/lib/workflows/triggers/triggers.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/triggers/triggers.ts)
- [apps/sim/lib/workflows/sanitization/subblocks.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/sanitization/subblocks.ts)
# 块系统与注册表
## 概述
块系统（Block System）是 Sim 工作流平台的核心组件化架构，用于定义和执行业务逻辑。每个块代表一个独立的功能单元，可通过可视化编辑器组合成复杂的工作流程。
块注册表（Block Registry）提供统一的块发现、检索和验证机制，确保工作流引擎能够正确识别和执行各类块。
## 核心概念
### 块的定义
块是 Sim 平台中最小的可配置功能单元，包含以下关键属性：
| 属性 | 类型 | 说明 |
|------|------|------|
| `type` | `string` | 块的唯一标识符 |
| `category` | `string` | 块所属的分类，如 `triggers` |
| `triggerMode` | `boolean` | 是否为触发器模式 |
| `subBlocks` | `Record` | 子块配置 |
### 触发器块
触发器块是特殊类型的块，用于启动工作流执行。Sim 支持多种触发模式：
```typescript
type TriggerMode = 'manual' | 'api' | 'chat'
```
根据触发模式的不同，工作流可以通过以下方式启动：
- **manual（手动）**: 用户通过界面手动触发
- **api（API）**: 通过外部 API 调用触发
- **chat（对话）**: 通过聊天接口触发
## 注册表架构
### 块发现接口
注册表提供了完整的块发现 API，支持多种查询方式：
```typescript
// 根据类型获取块
getBlock(type: string): BlockConfig | null
// 获取所有块
getAllBlocks(): Record
// 获取所有块类型
getAllBlockTypes(): BlockType[]
// 根据工具名称获取块
getBlockByToolName(toolName: string): BlockConfig | null
// 根据分类获取块
getBlocksByCategory(category: string): BlockConfig[]
// 验证块类型是否有效
isValidBlockType(type: string): boolean
```
### 注册表结构
注册表采用单例模式设计，通过 `registry` 对象集中管理所有块定义：
```typescript
// 资料来源：apps/sim/lib/workflows/diff/diff-engine.test.ts:1-50
vi.mock('@/blocks', () => ({
getBlock: () => null,
getAllBlocks: () => ({}),
getAllBlockTypes: () => [],
getBlockByToolName: () => null,
getBlocksByCategory: () => [],
isValidBlockType: () => false,
registry: {},
}))
```
## 触发器系统
### TriggerUtils 工具类
`TriggerUtils` 提供了一系列静态方法用于处理触发器块的判断和分类：
```typescript
// 资料来源：apps/sim/lib/workflows/triggers/triggers.ts:1-50
export class TriggerUtils {
static isTriggerBlock(block: { type: string; triggerMode?: boolean }): boolean {
const blockConfig = getBlock(block.type)
return (
// 新触发器块（显式分类）
blockConfig?.category === 'triggers' ||
// 启用触发器模式的块
block.triggerMode === true ||
// 遗留的启动器块
block.type === TRIGGER_TYPES.STARTER
)
}
static isTriggerType(block: { type: string }, triggerType: TriggerType): boolean {
return block.type === triggerType
}
}
```
### 触发器类型映射
系统定义了触发器类型的别名映射，便于在引用中使用：
```typescript
// 资料来源：apps/sim/lib/workflows/triggers/triggers.ts:1-30
export const TRIGGER_REFERENCE_ALIAS_MAP = {
start: TRIGGER_TYPES.START,
api: TRIGGER_TYPES.API,
chat: TRIGGER_TYPES.CHAT,
manual: TRIGGER_TYPES.START,
} as const
export type TriggerReferenceAlias = keyof typeof TRIGGER_REFERENCE_ALIAS_MAP
```
## 子块系统
### 子块结构
子块（SubBlocks）允许在父块内部定义可配置的子单元。每个子块包含：
| 属性 | 说明 |
|------|------|
| `id` | 子块的唯一标识符 |
| `type` | 子块的类型 |
| `value` | 子块的当前值 |
### 子块验证与修复
系统提供自动化的子块数据校验和修复机制：
```typescript
// 资料来源：apps/sim/lib/workflows/sanitization/subblocks.ts:1-60
const typeFromConfig =
configuredType || blockConfig?.subBlocks?.find((config) => config.id === id)?.type
const missingMetadata =
typeof subBlock.id !== 'string' ||
subBlock.id.length === 0 ||
typeof subBlock.type !== 'string' ||
subBlock.type.length === 0
if (missingMetadata && !typeFromConfig) {
logger.warn('Skipping malformed subBlock: unrecognized metadata entry', {
blockId: block.id,
subBlockId,
})
changed = true
continue
}
```
### 空值处理
子块系统支持将空字符串转换为 `null` 的选项：
```typescript
const hasValue = Object.hasOwn(subBlock, 'value')
const value =
options.convertEmptyStringToNull && subBlock.value === ''
? null
: hasValue
? subBlock.value
: null
```
## 块的分类体系
### 分类结构
块按照功能进行分类管理，主要分类包括：
| 分类 | 说明 |
|------|------|
| `triggers` | 触发器块，用于启动工作流 |
| `actions` | 动作块，执行具体操作 |
| `conditions` | 条件块，控制流程分支 |
| `transforms` | 转换块，数据处理和转换 |
### 分类查询
通过 `getBlocksByCategory` 方法可以获取指定分类下的所有块：
```typescript
// 返回指定分类的所有块配置
getBlocksByCategory('triggers'): BlockConfig[]
```
## 工作流集成
### 执行上下文
块在工作流执行时通过注册表获取块配置：
```mermaid
graph TD
A[工作流引擎] --> B[块注册表]
B --> C[getBlock type]
C --> D[BlockConfig]
D --> E[执行块逻辑]
B --> F[getBlocksByCategory]
F --> G[分类块列表]
B --> H[isValidBlockType]
H --> I[布尔验证结果]
```
### 触发器判断流程
在执行工作流时，系统通过以下逻辑判断是否为触发器块：
```mermaid
graph TD
A[检查块配置] --> B{category === 'triggers'}
B -->|是| E[是触发器块]
B -->|否| C{triggerMode === true}
C -->|是| E
C -->|否| D{type === STARTER}
D -->|是| E
D -->|否| F[不是触发器块]
```
## 注册表初始化
### 模块导出
注册表通过统一的入口模块导出所有块相关的接口：
```typescript
// apps/sim/blocks/index.ts
export {
registry,
getBlock,
getAllBlocks,
getAllBlockTypes,
getBlockByToolName,
getBlocksByCategory,
isValidBlockType,
// ...
}
```
### 类型定义
系统通过类型定义文件提供完整的类型安全支持：
```typescript
// apps/sim/blocks/types.ts
export interface BlockConfig {
type: string
category: string
name: string
description?: string
inputs?: InputSchema
outputs?: OutputSchema
config?: ConfigSchema
subBlocks?: SubBlockDefinition[]
}
export interface SubBlockDefinition {
id: string
type: string
label?: string
defaultValue?: unknown
}
```
## 测试支持
### Mock 配置
在单元测试中，注册表模块可以被完全 Mock：
```typescript
// 资料来源：apps/sim/lib/workflows/diff/diff-engine.test.ts:1-50
vi.mock('@/blocks', () => ({
getBlock: () => null,
getAllBlocks: () => ({}),
getAllBlockTypes: () => [],
getBlockByToolName: () => null,
getBlocksByCategory: () => [],
isValidBlockType: () => false,
registry: {},
}))
```
这种设计允许测试环境独立于实际块定义进行隔离测试。
## 最佳实践
### 块定义规范
1. **唯一标识**: 每个块必须具有全局唯一的 `type` 标识符
2. **明确分类**: 通过 `category` 属性声明块的所属分类
3. **类型安全**: 使用 TypeScript 接口定义块的结构
4. **配置验证**: 在注册表中验证块的配置完整性
### 子块使用建议
1. **默认值**: 为子块提供合理的默认值
2. **类型约束**: 明确子块的类型定义
3. **空值处理**: 使用 `convertEmptyStringToNull` 选项统一空值语义
4. **日志记录**: 对异常子块数据进行日志记录以便排查
## 相关资源
- 块定义目录：`apps/sim/blocks/blocks/`
- 块类型定义：`apps/sim/blocks/types.ts`
- 块注册表实现：`apps/sim/blocks/registry.ts`
- 触发器工具类：`apps/sim/lib/workflows/triggers/triggers.ts`
---
## 代理与AI集成
### 相关页面
相关主题：[工作流执行引擎](#page-workflow-execution), [块系统与注册表](#page-block-registry)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/simstudioai/sim/blob/main/README.md) — 项目主说明文件
- [apps/sim/lib/workflows/triggers/triggers.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/triggers/triggers.ts) — 工作流触发器实现
- [apps/sim/lib/copilot/request/session/contract.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/copilot/request/session/contract.ts) — Copilot 会话协议定义
- [apps/sim/lib/core/security/input-validation.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/core/security/input-validation.ts) — 输入验证与安全模块
- [apps/sim/lib/api/contracts/types.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/api/contracts/types.ts) — API 契约类型定义
- [packages/testing/src/mocks/env.mock.ts](https://github.com/simstudioai/sim/blob/main/packages/testing/src/mocks/env.mock.ts) — 测试环境模拟
> **注意**：以下代理核心文件未在当前检索上下文中找到：agent.ts、agent-handler.ts、memory.ts、skills-resolver.ts、types.ts。这些文件的缺失意味着本文档基于可用的上下文信息进行编写。
# 代理与AI集成
## 概述
Sim 是一个开源平台，用于构建 AI 代理（Agent）并运行代理工作流。该平台连接超过 1000 个集成和 LLM，以编排代理工作流 资料来源：[README.md:1]。
Sim 的代理系统通过模块化架构实现，支持多种触发模式、工作流编排、以及与外部工具和 API 的深度集成。代理作为平台的核心执行单元，能够根据配置执行复杂的多步骤任务。
## 核心架构
### 代理与触发器关系
Sim 中的代理与触发器紧密耦合。触发器定义了代理何时以及如何被激活，而代理则负责执行业务逻辑。
```mermaid
graph TD
A[触发器 Trigger] --> B[触发模式 Trigger Mode]
B --> C[manual 手动]
B --> D[api API调用]
B --> E[chat 聊天]
A --> F[代理 Agent]
F --> G[执行逻辑]
G --> H[输出结果]
```
根据触发器实现，代理支持三种触发模式 资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:1-20]：
| 触发模式 | 描述 | 触发方式 |
|---------|------|---------|
| `manual` | 手动触发 | 用户通过界面手动启动 |
| `api` | API 触发 | 通过 HTTP 请求或 `run` 参数触发 |
| `chat` | 聊天触发 | 通过对话交互触发 |
触发模式通过 `readSubBlockValue(block.subBlocks, 'startWorkflow')` 读取，返回值为 `'chat'`、`'api'`、`'run'` 或 `'manual'` 资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:5-14]。
### 代理块识别机制
Sim 使用 `TriggerUtils` 类提供统一的触发器检查功能 资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:35-55]：
```typescript
static isTriggerBlock(block: { type: string; triggerMode?: boolean }): boolean {
const blockConfig = getBlock(block.type)
return (
blockConfig?.category === 'triggers' ||
block.triggerMode === true ||
block.type === TRIGGER_TYPES.STARTER
)
}
```
## 代理执行模型
### 会话与流式处理
Sim 的代理系统支持流式输出，通过会话协议处理实时的代理响应。协议定义包括合成文件预览、流式引用追踪等高级功能 资料来源：[apps/sim/lib/copilot/request/session/contract.ts:1-50]。
流式数据验证包括：
| 验证项 | 类型 | 说明 |
|-------|------|------|
| `seq` | number | 序列号 |
| `ts` | string | 时间戳 |
| `stream` | StreamRef | 流引用 |
| `trace` | Trace | 可选追踪信息 |
| `scope` | StreamScope | 可选作用域 |
### 文件预览集成
代理执行过程中支持文件操作预览，包括新建文件、编辑元数据、完整内容展示等阶段 资料来源：[apps/sim/lib/copilot/request/session/contract.ts:60-90]：
| 预览阶段 | 触发条件 |
|---------|---------|
| `start` | 预览开始 |
| `target` | 文件操作目标确定 |
| `editMeta` | 元数据编辑 |
| `content` | 内容展示 |
## 安全与输入验证
### 代理参数验证
所有代理输入必须经过严格验证，Sim 提供了多种验证器确保安全性 资料来源：[apps/sim/lib/core/security/input-validation.ts:1-80]：
#### 枚举值验证
```typescript
validateEnum(
value: string | null | undefined,
allowedValues: readonly T[],
paramName?: string
): ValidationResult
```
此验证器确保代理接收的参数在允许的范围内，防止注入攻击 资料来源：[apps/sim/lib/core/security/input-validation.ts:50-75]。
#### 主机名验证
用于防止 SSRF（服务器端请求伪造）攻击，验证主机名不是私有 IP、本地地址或其他保留地址 资料来源：[apps/sim/lib/core/security/input-validation.ts:80-130]：
| 检查项 | 描述 |
|-------|------|
| 私有 IP | 10.x.x.x, 172.16-31.x.x, 192.168.x.x |
| 本地地址 | localhost, 127.0.0.1 |
| 保留地址 | 0.0.0.0,169.254.x.x |
## API 契约类型系统
Sim 使用强类型 API 契约定义代理与外部系统的交互 资料来源：[apps/sim/lib/api/contracts/types.ts:1-50]：
### 契约参数类型
| 类型别名 | 用途 |
|---------|------|
| `ContractParams` | 路由参数 |
| `ContractQuery` | 查询参数 |
| `ContractBody` | 请求体参数 |
| `ContractHeaders` | 请求头参数 |
这些类型通过泛型推断自动从 `ApiRouteContract` 提取对应的 Schema 类型 资料来源：[apps/sim/lib/api/contracts/types.ts:20-45]。
## 工作流编排
### 触发器分类
Sim 的工作流通过触发器类型进行分类管理 资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:25-35]：
```mermaid
graph LR
A[START] --> B[入口触发]
C[API] --> D[API触发]
E[CHAT] --> F[聊天触发]
G[STARTER] --> H[遗留触发器]
```
### 触发引用别名
平台定义了别名映射，简化跨系统的触发器引用 资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:18-24]：
```typescript
export const TRIGGER_REFERENCE_ALIAS_MAP = {
start: TRIGGER_TYPES.START,
api: TRIGGER_TYPES.API,
chat: TRIGGER_TYPES.CHAT,
manual: TRIGGER_TYPES.START,
} as const
```
## 环境配置与测试
### 代理运行环境
Sim 的代理支持多种运行环境配置，通过环境变量管理 资料来源：[packages/testing/src/mocks/env.mock.ts:1-40]：
| 环境函数 | 描述 |
|---------|------|
| `getEnv` | 获取环境变量值 |
| `isTruthy` | 检查真值 |
| `isFalsy` | 检查假值 |
| `envNumber` | 获取数值并支持最小值约束 |
```typescript
envNumber(
value: number | string | undefined | null,
fallback: number,
options: { min?: number } = {}
): number
```
## 部署模式
### 本地模型支持
Sim 支持通过 Ollama 和 vLLM 运行本地模型，为代理提供灵活的 AI 后端选择 资料来源：[README.md:1]。
### 部署方式
| 方式 | 说明 | 适用场景 |
|-----|------|---------|
| Docker | 一键部署 | 快速启动 |
| Docker Compose | 完整生产环境 | 自托管部署 |
| 手动配置 | 自定义设置 | 高级用户 |
## 总结
Sim 的代理与 AI 集成系统采用模块化设计，通过触发器机制实现灵活的代理激活方式，支持手动、API 和聊天三种触发模式。系统内置完善的输入验证和安全防护，使用强类型 API 契约确保通信可靠性，并支持本地和云端多种 AI 模型后端。
代理作为平台的核心执行单元，通过工作流编排实现复杂任务的自动化处理，同时保持高度的可扩展性和安全边界控制。
---
## 工作流编辑器
### 相关页面
相关主题：[实时协作与UI组件](#page-realtime-ui), [系统架构](#page-system-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [apps/sim/lib/workflows/triggers/triggers.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/triggers/triggers.ts)
- [apps/sim/lib/workflows/diff/diff-engine.test.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/diff/diff-engine.test.ts)
- [apps/sim/lib/workflows/sanitization/validation.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/sanitization/validation.ts)
- [apps/sim/lib/a2a/agent-card.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/a2a/agent-card.ts)
- [packages/ts-sdk/README.md](https://github.com/simstudioai/sim/blob/main/packages/ts-sdk/README.md)
- [packages/python-sdk/README.md](https://github.com/simstudioai/sim/blob/main/packages/python-sdk/README.md)
- [scripts/README.md](https://github.com/simstudioai/sim/blob/main/scripts/README.md)
# 工作流编辑器
## 概述
工作流编辑器（Workflow Editor）是 Sim 平台的核心组件，用于可视化构建、配置和管理自动化工作流。该编辑器允许用户通过组合不同的 **块（Blocks）** 和 **触发器（Triggers）** 来创建复杂的自动化流程。
工作流编辑器的主要职责包括：
- 提供可视化的块编排界面
- 管理工作流状态和配置
- 处理触发器类型（手动、API、聊天）
- 执行工作流验证和清理
- 生成 A2A（Agent-to-Agent）协议兼容的代理卡片
资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:1-50]()
## 架构概览
```mermaid
graph TD
subgraph 工作流编辑器
A[工作流编辑器 UI] --> B[块管理器]
A --> C[触发器管理器]
A --> D[验证引擎]
end
subgraph 块系统
B --> E[块注册表]
B --> F[子块配置]
E --> G[块类型]
G --> G1[Triggers]
G --> G2[Actions]
G --> G3[Logic]
end
subgraph 触发器系统
C --> H[触发器类型]
H --> H1[手动触发 Manual]
H --> H2[API 触发 Api]
H --> H3[聊天触发 Chat]
end
subgraph 执行层
D --> I[工作流执行器]
I --> J[沙箱执行环境]
end
```
## 触发器系统
触发器是工作流的入口点，决定了工作流的激活方式。Sim 平台支持三种主要的触发器类型。
### 触发器类型
| 触发器类型 | 值 | 说明 | 适用场景 |
|-----------|-----|------|---------|
| 手动触发 | `manual` | 用户通过界面手动启动 | 调试、测试、临时执行 |
| API 触发 | `api` / `run` | 通过 API 接口调用触发 | 外部系统集成、Webhook |
| 聊天触发 | `chat` | 通过聊天界面交互触发 | 对话式自动化 |
资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:35-50]()
### 触发器类型常量
```typescript
export const TRIGGER_TYPES = {
START: 'start',
INPUT: 'input',
API: 'api_trigger',
CHAT: 'chat_trigger',
MANUAL: 'manual_trigger',
STARTER: 'starter', // 遗留类型
} as const
```
### 触发器判断方法
`TriggerUtils` 类提供了静态方法来判断块是否为触发器：
```typescript
export class TriggerUtils {
// 判断是否为触发器块
static isTriggerBlock(block: { type: string; triggerMode?: boolean }): boolean
// 判断是否为特定触发器类型
static isTriggerType(block: { type: string }, triggerType: TriggerType): boolean
// 判断是否为手动触发器
static isManualTrigger(block: { type: string; subBlocks?: any }): boolean
// 判断是否为 API 触发器
static isApiTrigger(block: { type: string; subBlocks?: any }, isChildWorkflow?: boolean): boolean
}
```
### 触发器引用别名
系统支持通过别名引用触发器：
```typescript
export const TRIGGER_REFERENCE_ALIAS_MAP = {
start: TRIGGER_TYPES.START,
api: TRIGGER_TYPES.API,
chat: TRIGGER_TYPES.CHAT,
manual: TRIGGER_TYPES.START,
} as const
```
资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:55-75]()
## 块系统
块（Block）是工作流编辑器的基本构建单元，每个块代表一个具体的操作或功能。
### 块注册表
块通过注册表进行统一管理，提供以下查询接口：
```typescript
// 获取单个块
getBlock(type: string): BlockConfig | null
// 获取所有块
getAllBlocks(): Record
// 获取所有块类型
getAllBlockTypes(): BlockConfig[]
// 通过工具名称获取块
getBlockByToolName(toolName: string): BlockConfig | null
// 按类别获取块
getBlocksByCategory(category: string): BlockConfig[]
// 验证块类型是否有效
isValidBlockType(type: string): boolean
```
### 块类别
| 类别 | 说明 | 示例 |
|-----|------|------|
| `triggers` | 触发器块 | Start、API Trigger、Manual Trigger |
| `actions` | 操作块 | HTTP 请求、数据处理 |
| `logic` | 逻辑块 | 条件判断、循环 |
资料来源：[apps/sim/lib/workflows/diff/diff-engine.test.ts:15-30]()
### 子块配置
每个块可以包含多个子块（Sub-Blocks），用于配置块的详细行为：
```typescript
interface SubBlockState {
value: unknown
visible?: boolean
annotation?: string
}
```
### 块输出管理
块输出（Block Outputs）用于在工作流中传递数据：
```typescript
getEffectiveBlockOutputs(blockId: string): Record
```
资料来源：[apps/sim/lib/workflows/diff/diff-engine.test.ts:35-40]()
## 工作流验证与清理
工作流在保存或执行前需要经过验证和清理流程。
### 验证流程
```mermaid
graph TD
A[工作流状态] --> B[验证块引用]
B --> C[验证触发器配置]
C --> D[清理工具配置]
D --> E[验证工具 Schema]
E --> F[返回验证结果]
B -->|失败| G[记录错误]
C -->|失败| G
D -->|失败| G
E -->|失败| G
```
### 验证结果类型
```typescript
export interface WorkflowValidationResult {
valid: boolean // 是否有效
errors: string[] // 错误列表
warnings: string[] // 警告列表
sanitizedState?: WorkflowState // 清理后的状态
}
```
### 清理规则
| 规则类型 | 处理方式 | 说明 |
|---------|---------|------|
| 自定义工具 ID | `customToolId` | 确保工具标识唯一 |
| Schema 验证 | `schema` | 验证工具输入输出定义 |
| 引用工具 | `usageControl` | 设置默认值 `auto` |
| 内联工具 | `code` | 确保代码字段存在 |
### 工具清理流程
```typescript
.map((tool: unknown) => {
if (isRecord(tool) && tool.type === 'custom-tool') {
// 引用工具：确保 usageControl 默认值
if (!tool.usageControl) {
tool.usageControl = 'auto'
}
// 内联工具：确保 code 字段
if (!tool.customToolId && (!tool.code || typeof tool.code !== 'string')) {
tool.code = ''
}
}
return tool
})
```
资料来源：[apps/sim/lib/workflows/sanitization/validation.ts:1-80]()
## A2A 代理集成
工作流编辑器支持通过 A2A（Agent-to-Agent）协议与其他代理系统集成。
### 代理卡片生成
每个工作流可以生成对应的代理卡片，用于服务发现和能力描述：
```typescript
export function generateAgentCard(
agent: AgentConfig,
workflow: WorkflowConfig,
baseUrl: string
): AppAgentCard
```
### 代理技能定义
```typescript
export function generateSkillsFromWorkflow(
workflowName: string,
workflowDescription: string | null,
tags?: string[]
): AgentSkill[] {
return [{
id: 'execute',
name: `Execute ${workflowName}`,
description: workflowDescription || `Execute the ${workflowName} workflow`,
tags: tags || [],
}]
}
```
### 代理卡片验证
```typescript
export function validateAgentCard(card: unknown): card is AppAgentCard {
if (!card || typeof card !== 'object') return false
const c = card as Record
if (typeof c.name !== 'string' || !c.name) return false
if (typeof c.url !== 'string' || !c.url) return false
// ... 更多验证
}
```
资料来源：[apps/sim/lib/a2a/agent-card.ts:1-80]()
## 工作流执行
### 执行模式
| 模式 | 说明 | 适用场景 |
|-----|------|---------|
| 同步执行 | 等待执行完成返回结果 | 实时响应、快速验证 |
| 异步执行 | 立即返回任务 ID，后续查询状态 | 长时间运行、外部集成 |
### 执行选项
```typescript
interface ExecutionOptions {
timeout?: number // 超时时间（毫秒）
stream?: boolean // 是否启用流式输出
selectedOutputs?: string[] // 选择性输出字段
async?: boolean // 异步执行模式
}
interface RetryOptions {
maxRetries?: number // 最大重试次数
initialDelay?: number // 初始延迟
maxDelay?: number // 最大延迟
backoffMultiplier?: number // 退避乘数
}
```
### 执行结果
```typescript
interface WorkflowExecutionResult {
success: boolean // 是否成功
output?: any // 输出数据
error?: string // 错误信息
logs?: list // 执行日志
metadata?: Dict // 元数据
trace_spans?: list // 追踪跨度
total_duration?: float // 总耗时
}
interface AsyncExecutionResult {
success: boolean // 是否成功
task_id: str // 任务 ID
status: 'queued' // 状态
created_at: str // 创建时间
links: Dict[str, str] // 相关链接
}
```
### 执行常量
```typescript
// 注释专用块
isAnnotationOnlyBlock(): boolean
// 块尺寸限制
BLOCK_DIMENSIONS = { MIN_HEIGHT: 100 }
// 句柄位置
HANDLE_POSITIONS = {}
```
资料来源：[apps/sim/lib/workflows/diff/diff-engine.test.ts:45-55]()
## 块文档生成
工作流编辑器包含自动化文档生成功能。
### 文档生成流程
```mermaid
graph TD
A[扫描块目录] --> B[提取元数据]
B --> C[生成 Markdown]
C --> D[更新 meta.json]
D --> E[提交文档]
```
### 支持的元数据
| 元数据字段 | 说明 |
|----------|------|
| Name | 块名称 |
| Description | 块描述 |
| Category | 所属类别 |
| Input | 输入规格 |
| Output | 输出规格 |
| Config | 配置参数 |
### 手动内容保留
文档生成器支持保留手动添加的内容：
```markdown
{/_ MANUAL-CONTENT-START:usage _/}
## Examples
### Basic Usage
```json
{ "parameter": "value" }
```
{/_ MANUAL-CONTENT-END _/}
```
资料来源：[scripts/README.md:1-60]()
## SDK 支持
### TypeScript SDK
```typescript
import { SimStudioClient } from '@simstudio/ts-sdk'
const client = new SimStudioClient({ apiKey: 'your-api-key' })
// 同步执行
const result = await client.workflows.execute('workflow-id', {
input: { data: 'example' }
})
// 异步执行
const asyncResult = await client.workflows.executeAsync('workflow-id', {
input: { data: 'example' }
})
```
### Python SDK
```python
from simstudio import Client
client = Client(api_key="your-api-key")
# 同步执行
result = client.workflows.execute("workflow-id", {"data": "example"})
# 异步执行
async_result = client.workflows.execute_async("workflow-id", {"data": "example"})
```
资料来源：[packages/ts-sdk/README.md:1-100]()
[packages/python-sdk/README.md:1-100]()
## 相关资源
| 资源类型 | 说明 |
|---------|------|
| `/app/workspace/[workspaceId]/w/[workflowId]` | 工作流编辑器主路由 |
| `/components/panel/components/editor` | 编辑器面板组件 |
| `/components/workflow-block` | 工作流块组件 |
| `/components/panel/components/sub-block` | 子块配置组件 |
---
## 实时协作与UI组件
### 相关页面
相关主题：[系统架构](#page-system-architecture), [工作流编辑器](#page-workflow-editor)
相关源码文件
以下源码文件用于生成本页说明：
- [apps/sim/lib/workflows/triggers/triggers.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/triggers/triggers.ts)
- [apps/sim/lib/workflows/triggers/trigger-utils.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/triggers/trigger-utils.ts)
- [apps/sim/lib/webhooks/providers/gong.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/providers/gong.ts)
- [apps/sim/lib/webhooks/providers/typeform.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/providers/typeform.ts)
- [apps/sim/lib/api/contracts/types.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/api/contracts/types.ts)
- [apps/sim/app/workspace/providers/socket-provider.tsx](https://github.com/simstudioai/sim/blob/main/apps/sim/app/workspace/providers/socket-provider.tsx)
- [apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/cursors/cursors.tsx](https://github.com/simstudioai/sim/blob/main/apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/cursors/cursors.tsx)
# 实时协作与UI组件
## 概述
实时协作与UI组件是 Sim 平台中支持多用户同时编辑和工作流管理的核心功能模块。该系统通过 WebSocket 连接实现实时状态同步，支持工作流设计器的协作编辑、触发器实时监控、以及与外部系统（如 Gong、Typeform）的Webhook集成。
**核心职责：**
- 建立和管理 WebSocket 连接，实现客户端与服务器的实时双向通信
- 提供协作用户的光标追踪和状态显示功能
- 处理工作流触发器的实时事件流
- 集成第三方Webhook提供商的实时数据接收
**技术范围：**
- Socket Provider 客户端组件
- 光标和协作状态组件
- 工作流触发器系统
- Webhook提供商的实时数据处理
- API契约类型定义
---
## 系统架构
### 整体架构图
```mermaid
graph TD
subgraph 客户端层["客户端层"]
SP[Socket Provider]
CURSORS[光标组件]
UI[工作流编辑器 UI]
end
subgraph 实时服务["实时服务 - apps/realtime"]
HANDLERS[事件处理器]
MIDDLEWARE[中间件]
ROOMS[房间管理]
end
subgraph 业务逻辑层["业务逻辑层"]
TRIGGERS[触发器系统]
WEBHOOKS[Webhook提供商]
end
subgraph 外部系统["外部集成"]
GONG[Gong平台]
TYPEFORM[Typeform]
SCHEDULE[调度器]
end
SP <-->|WebSocket| HANDLERS
HANDLERS <--> ROOMS
HANDLERS <--> MIDDLEWARE
TRIGGERS -->|触发事件| HANDLERS
WEBHOOKS -->|Webhook事件| TRIGGERS
UI <--> SP
CURSORS <--> SP
```
### Socket Provider 架构
Socket Provider 是 React 上下文提供者，负责管理 WebSocket 连接的生命周期。
```mermaid
graph LR
A[React App] -->|Provider| B[SocketContext]
B --> C[WebSocket Connection]
C -->|onOpen| D[连接建立]
C -->|onMessage| E[消息处理]
C -->|onClose| F[重连逻辑]
C -->|onError| G[错误处理]
```
---
## Socket Provider 组件
### 组件位置
`apps/sim/app/workspace/providers/socket-provider.tsx`
### 核心功能
Socket Provider 组件是 Sim 应用中 WebSocket 连接的中心化管理器，提供以下核心功能：
| 功能 | 说明 |
|------|------|
| 连接管理 | 建立与实时服务器的 WebSocket 连接 |
| 自动重连 | 连接断开时自动尝试重新连接 |
| 消息订阅 | 支持订阅特定事件类型的消息 |
| 状态同步 | 维护连接状态并向子组件广播 |
| 上下文提供 | 通过 React Context 向子树提供 Socket 实例 |
### 连接生命周期
```mermaid
stateDiagram-v2
[*] --> Disconnected: 初始状态
Disconnected --> Connecting: 调用 connect()
Connecting --> Connected: WebSocket open
Connecting --> Disconnected: 连接失败
Connected --> Disconnected: 连接关闭
Disconnected --> Connecting: 自动重连
Connected --> [*]: 组件卸载
```
**连接状态说明：**
| 状态 | 描述 |
|------|------|
| `disconnected` | 初始状态或连接已关闭 |
| `connecting` | 正在建立 WebSocket 连接 |
| `connected` | 连接已建立，可收发消息 |
| `reconnecting` | 正在尝试重新连接 |
### 事件订阅机制
Socket Provider 支持基于事件类型的消息订阅，客户端可以注册特定事件的处理器：
```typescript
// 订阅示例
socket.subscribe('workflow.update', handler)
socket.subscribe('cursor.move', handler)
// 取消订阅
socket.unsubscribe('workflow.update', handler)
```
---
## 协作用户光标组件
### 组件位置
`apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/cursors/cursors.tsx`
### 功能说明
光标组件负责显示和追踪协作用户在编辑器中的实时位置和操作状态。
| 属性 | 类型 | 说明 |
|------|------|------|
| `userId` | `string` | 协作用户唯一标识 |
| `userName` | `string` | 协作用户显示名称 |
| `color` | `string` | 用户分配的颜色（用于区分不同用户） |
| `position` | `{ x: number, y: number }` | 当前光标位置 |
| `isActive` | `boolean` | 用户当前是否处于活跃状态 |
| `lastUpdate` | `number` | 最后更新时间戳 |
### 光标渲染逻辑
```mermaid
graph TD
A[接收 CursorMove 事件] --> B{检查用户状态}
B -->|用户活跃| C[更新本地状态]
B -->|用户空闲超时| D[降低透明度/隐藏]
C --> E[重新渲染光标组件]
D --> E
E --> F[显示用户名称标签]
```
### 协作用户管理
光标组件支持显示当前工作区的所有协作用户：
| 用户状态 | 视觉表现 |
|----------|----------|
| 活跃编辑 | 正常显示，带有用户名称标签 |
| 空闲 | 降低透明度至 50% |
| 长时间无活动 | 隐藏光标（节省渲染资源） |
| 断开连接 | 立即移除光标显示 |
---
## 工作流触发器系统
### 触发器类型
Sim 平台支持多种触发器类型，用于启动工作流执行：
| 触发器类型 | 标识符 | 说明 | 优先级 |
|-----------|--------|------|--------|
| 手动触发 | `TRIGGER_TYPES.START` | 用户手动启动工作流 | 0（最高） |
| API触发 | `TRIGGER_TYPES.API` | 通过API调用触发 | 4 |
| 聊天触发 | `TRIGGER_TYPES.CHAT` | 通过聊天消息触发 | 7 |
| 调度触发 | `schedule` | 定时/周期执行 | 2 |
| Webhook触发 | `external_trigger` | 外部Webhook事件触发 | 3 |
资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:1-50]()
### 触发器引用别名映射
系统定义了触发器引用别名，方便在内部引用不同类型的触发器：
```typescript
export const TRIGGER_REFERENCE_ALIAS_MAP = {
start: TRIGGER_TYPES.START,
api: TRIGGER_TYPES.API,
chat: TRIGGER_TYPES.CHAT,
manual: TRIGGER_TYPES.START,
} as const
```
资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:50-60]()
### 触发器优先级排序
触发器根据类型和配置进行优先级排序：
```mermaid
graph TD
A[触发器候选列表] --> B[按路径分组]
B --> C{StartBlockPath 判断}
C -->|UNIFIED| D[优先级 0]
C -->|LEGACY_STARTER| E[优先级 1]
C -->|EXTERNAL_TRIGGER| F{类型判断}
C -->|SPLIT_API| G[优先级 4]
C -->|SPLIT_INPUT| H[优先级 5]
C -->|SPLIT_MANUAL| I[优先级 6]
C -->|SPLIT_CHAT| J[优先级 7]
F -->|schedule| K[优先级 2]
F -->|其他| L[优先级 3]
D --> M[排序完成]
E --> M
K --> M
L --> M
G --> M
H --> M
I --> M
J --> M
```
资料来源：[apps/sim/lib/workflows/triggers/trigger-utils.ts:1-35]()
### 触发器工具类
`TriggerUtils` 类提供静态方法用于触发器识别和验证：
```typescript
export class TriggerUtils {
// 检查块是否为触发器
static isTriggerBlock(block: { type: string; triggerMode?: boolean }): boolean
// 检查块是否为特定触发器类型
static isTriggerType(block: { type: string }, triggerType: TriggerType): boolean
}
```
### Mock Payload 需求判断
对于需要测试数据的外部触发器，系统提供智能判断：
```typescript
export function triggerNeedsMockPayload(
trigger: StartBlockCandidate
): boolean {
// 仅 Webhook 和外部集成需要 Mock Payload
// 调度器正常执行不需要模拟数据
return trigger.path === StartBlockPath.EXTERNAL_TRIGGER && trigger.block...
}
```
资料来源：[apps/sim/lib/workflows/triggers/trigger-utils.ts:60-75]()
---
## Webhook 实时数据处理
### Webhook 提供商架构
Sim 平台集成了多个第三方 Webhook 提供商，实现实时数据接收：
```mermaid
graph LR
subgraph 外部系统
GONG[Gong 自动化规则]
TYPEFORM[Typeform 表单响应]
end
subgraph 标准化处理
P_GONG[提供商处理器]
P_TYPEFORM[提供商处理器]
end
GONG -->|POST /webhooks/gong| P_GONG
TYPEFORM -->|POST /webhooks/typeform| P_TYPEFORM
P_GONG --> FORMAT_G[格式化为统一输入]
P_TYPEFORM --> FORMAT_T[格式化为统一输入]
FORMAT_G --> WORKFLOW[触发工作流]
FORMAT_T --> WORKFLOW
```
### Gong Webhook 提供商
**文件位置：** `apps/sim/lib/webhooks/providers/gong.ts`
Gong 平台集成支持接收自动化规则事件：
| 配置项 | 说明 |
|--------|------|
| `secret` | HMAC 签名验证密钥 |
| `includeCallData` | 是否包含通话数据 |
| `includeParties` | 是否包含通话参与者 |
| `includeContext` | 是否包含通话上下文 |
| `includeTrackers` | 是否包含追踪器数据 |
| `includeTopics` | 是否包含主题信息 |
| `includeHighlights` | 是否包含亮点标记 |
**事件数据结构：**
```typescript
{
eventType: 'gong.automation_rule',
callId: string,
metaData: Record,
parties: unknown[],
context: unknown[],
trackers: unknown[],
topics: unknown[],
highlights: unknown[]
}
```
### Typeform Webhook 提供商
**文件位置：** `apps/sim/lib/webhooks/providers/typeform.ts`
Typeform 集成支持接收表单响应事件：
| 配置项 | 说明 |
|--------|------|
| `formId` | Typeform 表单 ID |
| `apiKey` | Typeform API 密钥 |
| `webhookTag` | Webhook 标签 |
| `secret` | 签名验证密钥 |
| `includeDefinition` | 是否包含表单定义 |
**事件数据结构：**
```typescript
{
event_id: string,
event_type: 'form_response',
form_id: string,
token: string,
submitted_at: string,
landed_at: string,
calculated: Record,
variables: unknown[],
hidden: Record,
answers: unknown[],
definition?: Record,
ending: Record,
raw: Record
}
```
**认证验证：**
Typeform 提供商使用 HMAC 签名验证：
```typescript
verifyAuth: createHmacVerifier({
configKey: 'secret',
headerName: 'Typeform-Signature',
validateFn: validateTypeformSignature,
providerLabel: 'Typeform',
})
```
---
## API 契约类型系统
### 契约类型定义
**文件位置：** `apps/sim/lib/api/contracts/types.ts`
API 契约系统提供强类型的路由定义和参数提取：
| 类型 | 说明 |
|------|------|
| `ApiRouteContract` | API 路由契约的核心类型定义 |
| `ContractParams` | 提取契约中定义的路径参数类型 |
| `ContractQuery` | 提取契约中定义的查询参数类型 |
| `ContractBody` | 提取契约中定义的请求体类型 |
| `ContractHeaders` | 提取契约中定义的头部参数类型 |
| `ContractParamsInput` | 契约参数的输入形式 |
### 类型提取示例
```typescript
// 从契约中提取各种参数类型
type MyParams = ContractParams
type MyQuery = ContractQuery
type MyBody = ContractBody
type MyHeaders = ContractHeaders
```
### 契约辅助函数
```typescript
function defineRoute(
contract: ApiRouteContract
): ApiRouteContract
```
---
## 实时事件流
### 工作流更新事件
工作流状态变更通过 WebSocket 实时推送到所有连接的客户端：
```mermaid
sequenceDiagram
participant U as 用户A (编辑器)
participant S as Socket Provider
participant R as Realtime Server
participant W as 工作流引擎
U->>W: 修改工作流
W->>R: 触发 workflow.update 事件
R->>S: 广播事件
S->>U: 接收并处理事件
Note over U: 更新本地 UI 状态
```
### 协作用户状态同步
多个用户编辑同一工作流时，光标位置和操作状态实时同步：
```mermaid
sequenceDiagram
participant U1 as 用户1 (光标移动)
participant S as Socket Provider
participant R as Realtime Server
participant U2 as 用户2 (观察者)
U1->>S: 发送 cursor.move 事件
S->>R: 转发事件
R->>S: 广播到其他客户端
S->>U2: 接收并渲染光标
Note over U2: 显示用户1的光标
```
---
## 配置与扩展
### 添加新的 Webhook 提供商
要添加新的 Webhook 提供商，需要实现以下接口：
| 方法 | 说明 |
|------|------|
| `formatInput` | 将原始请求格式化为统一输入格式 |
| `verifyAuth` | 验证请求的认证信息 |
| `createSubscription` | （可选）创建订阅配置 |
**基本实现模板：**
```typescript
export const myProvider: WebhookProvider = {
formatInput: (body, webhook) => {
// 格式化输入数据
return {
input: {
// 统一输入格式
}
}
},
verifyAuth: createHmacVerifier({
configKey: 'secret',
headerName: 'Provider-Signature',
validateFn: validateSignature,
providerLabel: 'ProviderName',
}),
async createSubscription(ctx) {
// 创建订阅逻辑
return { subscriptionId: '...' }
}
}
```
### 触发器类型扩展
要添加新的触发器类型，需要：
1. 在 `TRIGGER_TYPES` 枚举中添加新类型
2. 在 `StartBlockPath` 中添加对应路径
3. 更新 `getPriority` 函数中的优先级逻辑
4. 在触发器选择逻辑中添加相应的判断
---
## 错误处理与重试
### WebSocket 连接错误处理
| 错误类型 | 处理策略 |
|----------|----------|
| 连接超时 | 指数退避重连（最大5次） |
| 网络断开 | 自动检测并重连 |
| 服务器错误 | 通知用户，显示错误信息 |
| 认证失败 | 重新认证流程 |
### Webhook 验证失败
验证失败的请求会被拒绝并记录日志：
```typescript
logger.warn(`[${ctx.requestId}] Missing formId for Typeform...`)
return undefined // 返回 undefined 表示验证失败
```
---
## 性能优化
### 光标渲染优化
| 优化策略 | 说明 |
|----------|------|
| 空闲检测 | 用户长时间无活动时降低更新频率 |
| 批量更新 | 合并短时间内的多次位置更新 |
| 可视区域 | 只渲染当前可视区域内的光标 |
| 脏检查 | 仅在位置变化时触发重新渲染 |
### WebSocket 消息压缩
| 策略 | 说明 |
|------|------|
| 增量更新 | 仅传输变化的字段 |
| 消息合并 | 批量发送低优先级事件 |
| 心跳优化 | 动态调整心跳间隔 |
---
## 相关文档
| 文档 | 说明 |
|------|------|
| [Socket Provider 组件](/apps/sim/app/workspace/providers/socket-provider.tsx) | WebSocket 连接管理组件 |
| [光标组件](/apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/cursors/cursors.tsx) | 协作用户光标显示 |
| [触发器系统](/apps/sim/lib/workflows/triggers/triggers.ts) | 工作流触发器核心逻辑 |
| [Gong 集成](/apps/sim/lib/webhooks/providers/gong.ts) | Gong Webhook 提供商 |
| [Typeform 集成](/apps/sim/lib/webhooks/providers/typeform.ts) | Typeform Webhook 提供商 |
---
## 连接器框架
### 相关页面
相关主题：[块系统与注册表](#page-block-registry), [扩展与定制](#page-extensibility)
相关源码文件
以下源码文件用于生成本页说明：
- [apps/sim/lib/webhooks/providers/gong.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/providers/gong.ts)
- [apps/sim/lib/webhooks/providers/webflow.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/providers/webflow.ts)
- [apps/sim/lib/webhooks/providers/typeform.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/providers/typeform.ts)
- [apps/sim/lib/webhooks/providers/vercel.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/providers/vercel.ts)
- [apps/sim/blocks/blocks/](https://github.com/simstudioai/sim/blob/main/apps/sim/blocks/blocks/)
- [apps/sim/blocks/index.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/blocks/index.ts)
# 连接器框架
## 概述
Sim 平台中的连接器框架（Connector Framework）是用于实现与外部第三方服务集成的基础架构。该框架提供了一套标准化的模式，使得平台能够统一处理来自不同服务提供商（Provider）的 webhook 事件和数据转换。
连接器框架的核心职责包括：
- **事件接收**：接收来自外部服务的事件通知
- **数据标准化**：将不同提供商的数据格式转换为统一的内部格式
- **认证验证**：验证 webhook 请求的真实性
- **事件过滤**：根据配置条件选择性处理事件
- **数据映射**：将外部数据结构映射为工作流可用的输入格式
## 架构设计
### 整体架构
```mermaid
graph TD
A[外部服务] -->|Webhook 事件| B[连接器提供者]
B --> C{事件过滤}
C -->|跳过| D[丢弃]
C -->|通过| E[数据标准化]
E --> F[工作流执行引擎]
F --> G[Block 输出]
H[认证模块] --> B
```
### Provider 架构模式
每个连接器提供者（Provider）遵循统一的接口契约，确保系统的一致性和可扩展性：
```mermaid
graph LR
A[Webhook 请求] --> B[formatInput]
B --> C[verifyAuth]
C --> D{验证结果}
D -->|失败| E[返回错误]
D -->|成功| F[shouldSkipEvent]
F --> G{跳过检查}
G -->|是| H[跳过处理]
G -->|否| I[触发工作流]
```
## Provider 接口规范
### 核心接口定义
每个连接器提供者必须实现以下核心方法：
| 方法名 | 类型 | 描述 |
|--------|------|------|
| `formatInput` | 同步函数 | 将原始 webhook 负载转换为标准化的输入格式 |
| `verifyAuth` | 认证函数 | 验证请求的认证签名 |
| `createSubscription` | 异步函数 | 在外部服务创建 webhook 订阅 |
| `shouldSkipEvent` | 同步函数 | 根据配置判断是否应跳过该事件 |
### 输入格式化
`formatInput` 函数负责将来自不同提供商的事件数据转换为统一的工作流输入格式：
```typescript
interface FormatInputResult {
input: {
event_id: string
event_type: string
// 特定于提供商的其他字段...
raw: Record // 原始数据保留
}
}
```
资料来源：[apps/sim/lib/webhooks/providers/typeform.ts:20-40]()
### 认证验证模式
认证验证采用工厂模式创建认证验证器，支持多种验证策略：
```typescript
verifyAuth: createHmacVerifier({
configKey: 'secret',
headerName: 'Typeform-Signature',
validateFn: validateTypeformSignature,
providerLabel: 'Typeform',
})
```
支持的认证类型：
| 认证类型 | 描述 | 适用场景 |
|---------|------|---------|
| HMAC 验证 | 基于共享密钥的消息认证码 | Typeform, GitHub |
| Bearer Token | Bearer 令牌认证 | 通用 API |
| 自定义验证 | 特定提供商的验证逻辑 | 各 Provider |
资料来源：[apps/sim/lib/webhooks/providers/typeform.ts:47-53]()
## 内置 Provider 实现
### Webflow 连接器
Webflow 连接器处理 CMS 和电商平台的事件，支持集合项的创建、更新和归档：
```typescript
interface WebflowFieldMapping {
lastUpdated: string | number
createdOn: string | number
isArchived: boolean
isDraft: boolean
fieldData: Record
}
```
**事件过滤逻辑**：
```typescript
shouldSkipEvent({ webhook, body, requestId, providerConfig }: EventFilterContext) {
const configuredCollectionId = providerConfig.collectionId as string | undefined
// 当配置了特定集合 ID 时，只处理该集合的事件
if (payloadCollectionId !== configuredCollectionId) {
return true // 跳过不匹配的事件
}
return false
}
```
资料来源：[apps/sim/lib/webhooks/providers/webflow.ts:1-50]()
### Gong 连接器
Gong 连接器处理销售对话智能平台的事件，提取会议元数据和内容分析：
```typescript
interface GongAutomationData {
metaData: Record
parties: unknown[]
context: unknown[]
trackers: unknown[]
topics: unknown[]
highlights: unknown[]
eventType: string
callId: string
}
```
**数据映射策略**：
```typescript
// 安全的类型转换，处理可能的 undefined 值
parties: (callData?.parties as unknown[]) || [],
context: (callData?.context as unknown[]) || [],
trackers: (content?.trackers as unknown[]) || [],
```
资料来源：[apps/sim/lib/webhooks/providers/gong.ts:1-30]()
### Typeform 连接器
Typeform 连接器处理表单响应事件，支持可选的表单定义包含：
```typescript
interface TypeformInput {
event_id: string
event_type: string
form_id: string
token: string
submitted_at: string
landed_at: string
calculated: Record
variables: unknown[]
hidden: Record
answers: unknown[]
definition?: Record // 可选配置
ending: Record
raw: Record
}
```
资料来源：[apps/sim/lib/webhooks/providers/typeform.ts:20-38]()
### Vercel 连接器
Vercel 连接器处理部署相关事件，提取部署、项目和团队信息：
```typescript
interface VercelDeployment {
id: string
url: string
name: string
meta: Record
}
interface VercelProject {
id: string
name: string
}
interface VercelTeam {
id: string
}
```
**对象安全转换模式**：
```typescript
deployment && typeof deployment === 'object'
? {
id: String((deployment as Record).id),
url: ((deployment as Record).url as string) ?? '',
}
: null
```
资料来源：[apps/sim/lib/webhooks/providers/vercel.ts:1-60]()
## 事件过滤机制
连接器框架支持精细化的事件过滤控制，通过 `EventFilterContext` 上下文对象传递配置：
```typescript
interface EventFilterContext {
webhook: WebhookRecord
body: Record
requestId: string
providerConfig: Record
}
```
**过滤决策流程**：
```mermaid
graph TD
A[接收事件] --> B[提取 providerConfig]
B --> C{检查配置条件}
C -->|无过滤条件| D[处理事件]
C -->|有过滤条件| E{条件匹配}
E -->|匹配成功| D
E -->|匹配失败| F[跳过事件]
D --> G[触发工作流]
F --> H[记录跳过日志]
```
## 与 Block 系统的集成
连接器框架与 Sim 的 Block 系统紧密集成，实现工作流自动化：
```mermaid
graph LR
A[连接器 Provider] --> B[Block 输入转换]
B --> C[工作流 Block 图]
C --> D[执行引擎]
D --> E[Block 输出]
```
Block 系统通过以下方式使用连接器：
1. **输入规范**：定义每个 Block 的输入 schema
2. **类型验证**：使用 Zod 进行运行时验证
3. **输出映射**：将 Block 执行结果映射为下游 Block 的输入
资料来源：[apps/sim/blocks/index.ts](apps/sim/blocks/index.ts)
## 订阅管理
连接器框架支持动态订阅管理，允许在运行时创建和配置 webhook 订阅：
```typescript
async createSubscription(ctx: SubscriptionContext): Promise {
const config = getProviderConfig(ctx.webhook)
const formId = config.formId as string | undefined
const apiKey = config.apiKey as string | undefined
// ... 配置验证和订阅创建逻辑
}
```
## 错误处理策略
| 错误类型 | 处理方式 | 返回状态 |
|---------|---------|---------|
| 认证失败 | 返回 401 | 拒绝请求 |
| 配置缺失 | 记录警告日志 | 返回 undefined |
| 格式转换错误 | 使用默认值 | 继续处理 |
| 事件过滤 | 静默跳过 | 不触发工作流 |
## 最佳实践
### Provider 开发指南
1. **类型安全**：始终使用类型断言和空值合并
2. **默认字段**：为可选字段提供安全的默认值
3. **日志记录**：在跳过事件时记录原因
4. **错误恢复**：不要让 Provider 错误导致整个流程失败
### 示例代码模式
```typescript
// 安全地从可能为 undefined 的嵌套对象中提取值
const value =
(itemFields as Record)?.fieldName ||
(itemFields as Record)?.['alternative-name'] ||
''
```
## 总结
Sim 的连接器框架提供了一套灵活且可扩展的集成机制，通过标准化的 Provider 接口实现了与多种外部服务的统一对接。该框架的核心优势包括：
- **一致性**：统一的接口契约简化了新增 Provider 的工作
- **安全性**：内置的认证验证机制确保了事件来源的可信性
- **灵活性**：事件过滤机制允许精细化的控制
- **可维护性**：类型安全的实现和清晰的代码结构便于长期维护
---
## 部署与基础设施
### 相关页面
相关主题：[项目概述](#page-project-overview), [系统架构](#page-system-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [docker-compose.prod.yml](https://github.com/simstudioai/sim/blob/main/docker-compose.prod.yml)
- [docker-compose.ollama.yml](https://github.com/simstudioai/sim/blob/main/docker-compose.ollama.yml)
- [apps/sim/.env.example](https://github.com/simstudioai/sim/blob/main/apps/sim/.env.example)
- [.devcontainer](https://github.com/simstudioai/sim/blob/main/.devcontainer)
- [apps/docs/content/docs/en/self-hosting](https://github.com/simstudioai/sim/blob/main/apps/docs/content/docs/en/self-hosting)
# 部署与基础设施
## 概述
Sim 是一个开源的工作流自动化平台，支持多种部署方式以满足不同规模和需求的场景。项目提供了从简单的本地开发部署到生产级 Kubernetes 集群部署的完整基础设施支持。
部署架构的核心组件包括：
- **应用服务**：基于 Next.js 构建的前后端一体化应用
- **数据库**：PostgreSQL 12+ 配合 pgvector 扩展用于向量存储
- **缓存层**：Redis 用于会话管理和实时功能
- **容器化**：Docker 和 Docker Compose 简化部署流程
- **编排**：Kubernetes Helm chart 支持生产级部署
资料来源：[README.md](https://github.com/simstudioai/sim/blob/main/README.md)
---
## 部署方式
Sim 支持四种主要的部署方式，从简单到复杂依次为：NPM 包快速启动、Docker Compose 生产部署、手动开发和 Kubernetes 生产部署。
### NPM 包快速部署
最简单的方式是使用官方提供的 NPM 包，通过 Docker 自动拉取并运行 Sim：
```bash
npx simstudio
```
默认访问地址为 http://localhost:3000
资料来源：[README.md:8](https://github.com/simstudioai/sim/blob/main/README.md)
**可用参数选项：**
| 参数 | 说明 | 默认值 |
|------|------|--------|
| `-p, --port ` | 指定运行端口 | `3000` |
| `--no-pull` | 跳过拉取最新 Docker 镜像 | `false` |
使用示例：
```bash
# 指定端口
npx simstudio --port 8080
# 跳过镜像拉取
npx simstudio --no-pull
```
> **前提条件**：必须安装并运行 Docker
---
### Docker Compose 生产部署
对于生产环境，推荐使用 Docker Compose 进行部署，该方式提供完整的服务栈和持久化存储。
```bash
git clone https://github.com/simstudioai/sim.git && cd sim
docker compose -f docker-compose.prod.yml up -d
```
资料来源：[README.md:19-22](https://github.com/simstudioai/sim/blob/main/README.md)
**Docker Compose 生产架构图：**
```mermaid
graph TD
subgraph "Docker Compose Stack"
A[用户访问] --> B[NGINX Reverse Proxy]
B --> C[Sim App Container]
C --> D[(PostgreSQL + pgvector)]
C --> E[(Redis Cache)]
C --> F[File Storage]
end
```
**生产部署包含的服务：**
- Sim 应用容器
- PostgreSQL 数据库（带 pgvector 扩展）
- Redis 缓存服务
- 文件存储卷
---
### 本地模型支持
Sim 支持通过 Ollama 和 vLLM 连接本地大语言模型，适用于对数据隐私有要求或希望降低 API 成本的场景。
使用 Ollama 部署：
```bash
docker compose -f docker-compose.ollama.yml up -d
```
资料来源：[README.md:29](https://github.com/simstudioai/sim/blob/main/README.md)
**Ollama 部署架构：**
```mermaid
graph LR
A[Sim App] -->|API 调用| B[Ollama Service]
B --> C[本地 LLM Model]
C -->|推理结果| B
B -->|返回结果| A
```
支持的本地模型功能：
- Ollama 本地模型推理
- vLLM 高性能推理服务
- 自定义模型接入
详细的本地模型配置请参考 [Docker 自托管文档](https://docs.sim.ai/self-hosting/docker)。
---
### Kubernetes Helm 部署
对于大规模生产环境，Sim 提供了完整的 Helm Chart 用于 Kubernetes 集群部署。
**基础安装：**
```bash
helm install sim ./helm/sim -n sim --create-namespace
```
**使用自定义值文件：**
```bash
helm install sim ./helm/sim -n sim -f values.prod.yaml
```
资料来源：[helm/sim/README.md](https://github.com/simstudioai/sim/blob/main/helm/sim/README.md)
---
## 环境变量配置
Sim 使用环境变量进行配置管理。示例配置文件位于 `apps/sim/.env.example`。
资料来源：[apps/sim/.env.example](https://github.com/simstudioai/sim/blob/main/apps/sim/.env.example)
### 核心配置参数
| 参数名 | 说明 | 必填 | 默认值 |
|--------|------|------|--------|
| `DATABASE_URL` | PostgreSQL 连接字符串 | 是 | - |
| `REDIS_URL` | Redis 连接字符串 | 是 | - |
| `NEXT_PUBLIC_APP_URL` | 应用公开访问 URL | 是 | - |
| `OPENAI_API_KEY` | OpenAI API 密钥 | 否 | - |
| `ANTHROPIC_API_KEY` | Anthropic API 密钥 | 否 | - |
### Helm 全局参数
| 参数 | 说明 | 默认值 |
|------|------|--------|
| `global.imageRegistry` | Docker 镜像仓库地址 | `docker.io` |
| `global.imagePullSecrets` | 镜像拉取密钥名称 | `[]` |
| `global.storageClass` | 存储类名称 | `""` |
| `global.commonLabels` | 通用标签 | `{}` |
资料来源：[helm/sim/README.md](https://github.com/simstudioai/sim/blob/main/helm/sim/README.md)
### 应用参数配置
| 参数 | 说明 | 默认值 |
|------|------|--------|
| `app.enabled` | 启用主应用 | `true` |
| `app.replicaCount` | 应用副本数 | `1` |
| `app.image.repository` | 镜像仓库 | `simstudioai/sim` |
| `app.image.tag` | 镜像标签 | `latest` |
| `app.image.pullPolicy` | 镜像拉取策略 | `Always` |
| `app.service.type` | 服务类型 | `ClusterIP` |
| `app.service.port` | 服务端口 | `3000` |
| `app.service.targetPort` | 容器目标端口 | `3000` |
---
## 系统要求
### 基础环境要求
| 组件 | 最低版本 | 推荐版本 |
|------|----------|----------|
| Docker | 最新稳定版 | 最新稳定版 |
| Bun | - | 最新版本 |
| Node.js | v20+ | v20 LTS |
| PostgreSQL | 12+ | 15+ |
| pgvector | 0.5+ | 最新版本 |
资料来源：[README.md:32-33](https://github.com/simstudioai/sim/blob/main/README.md)
### 手动部署前置步骤
1. **克隆代码库：**
```bash
git clone https://github.com/simstudioai/sim.git
cd sim
```
2. **安装依赖：**
```bash
bun install
bun run prepare # 设置 pre-commit hooks
```
3. **配置 PostgreSQL 数据库：**
```bash
docker run --name simstudio-db \
-e POSTGRES_PASSWORD=your_password \
-e POSTGRES_DB=simstudio \
-p 5432:5432 \
-d \
pgvector/pgvector:pg15
```
4. **配置环境变量：**
复制并编辑环境变量文件：
```bash
cp apps/sim/.env.example apps/sim/.env
# 编辑 .env 文件填入实际配置
```
---
## 开发环境配置
项目支持使用 VS Code Dev Container 进行标准化开发环境配置。
资料来源：[.devcontainer](https://github.com/simstudioai/sim/blob/main/.devcontainer)
### Dev Container 优势
- 开箱即用的标准化开发环境
- 预配置所有依赖项
- 与主机隔离，避免环境污染
- 团队成员环境一致性保证
### 启动开发容器
1. 确保已安装 VS Code 和 Docker
2. 在 VS Code 中打开项目文件夹
3. 安装 "Dev Containers" 扩展
4. 点击右下角提示 "Reopen in Container"
5. 等待容器构建完成
---
## 负载测试配置
项目包含用于验证部署性能的负载测试脚本，位于 `scripts/load/` 目录。
资料来源：[apps/sim/package.json](https://github.com/simstudioai/sim/blob/main/apps/sim/package.json)
### 可用的负载测试命令
| 命令 | 说明 |
|------|------|
| `load:workflow:waves` | 波次式负载测试 |
| `load:workflow:isolation` | 隔离工作空间负载测试 |
### 波次式负载测试参数
| 参数 | 说明 | 默认值 |
|------|------|--------|
| `BASE_URL` | 测试目标地址 | `http://localhost:3000` |
| `WAVE_ONE_DURATION` | 第一波次持续时间（秒） | 20 |
| `WAVE_ONE_RATE` | 第一波次请求速率 | 10 |
| `WAVE_TWO_DURATION` | 第二波次持续时间（秒） | 20 |
| `WAVE_TWO_RATE` | 第二波次请求速率 | 10 |
| `WAVE_THREE_DURATION` | 第三波次持续时间（秒） | 20 |
| `WAVE_THREE_RATE` | 第三波次请求速率 | 10 |
运行示例：
```bash
BASE_URL=http://production-server:3000 bunx artillery run scripts/load/workflow-waves.yml
```
---
## 安全配置
### 主机名验证
项目实现了 SSRF（服务器端请求伪造）防护机制，通过 `validateHostname` 函数验证目标主机名。
资料来源：[apps/sim/lib/core/security/input-validation.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/core/security/input-validation.ts)
**验证功能：**
- 检查是否为私有 IP 地址
- 阻止本地主机访问
- 过滤保留地址和特殊地址
```typescript
export function validateHostname(
hostname: string | null | undefined,
paramName = 'hostname'
): ValidationResult {
// 实现主机名安全性验证
}
```
### Webhook 安全验证
项目实现了待验证 Webhook 的安全处理机制，支持多种提供商的事件验证。
资料来源：[apps/sim/lib/webhooks/pending-verification.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/pending-verification.ts)
支持的提供商包括：
- Ashby
- Grain
- Salesforce
- Generic (通用)
---
## 构建与部署流程
### 应用构建
```bash
# 标准构建
bun run build
# 仅构建沙箱bundles
bun run build:sandbox-bundles
```
资料来源：[apps/sim/package.json](https://github.com/simstudioai/sim/blob/main/apps/sim/package.json)
### 构建流程架构
```mermaid
graph LR
A[源码] --> B[bun run build:sandbox-bundles]
B --> C[沙箱Bundle生成]
C --> D[Next.js Build]
D --> E[Docker Image]
E --> F[Container Registry]
```
### 代码质量检查
| 命令 | 说明 |
|------|------|
| `lint` | 运行 Biome 代码检查并自动修复 |
| `lint:check` | 仅检查不修复 |
| `format` | 运行代码格式化 |
| `format:check` | 仅检查格式 |
| `type-check` | TypeScript 类型检查 |
---
## 部署最佳实践
### 生产环境检查清单
- [ ] 使用 Docker Compose 或 Kubernetes 进行部署
- [ ] 配置 PostgreSQL 外部持久化存储
- [ ] 启用 Redis 缓存集群
- [ ] 配置环境变量而非硬编码配置
- [ ] 设置适当的副本数和资源限制
- [ ] 配置健康检查探针（liveness/readiness）
- [ ] 设置安全的镜像拉取策略
- [ ] 配置日志收集和监控
### 推荐配置示例
```yaml
# values.prod.yaml
app:
replicaCount: 3
resources:
limits:
cpu: "2000m"
memory: "4Gi"
requests:
cpu: "1000m"
memory: "2Gi"
livenessProbe:
httpGet:
path: /api/health
port: 3000
initialDelaySeconds: 30
periodSeconds: 10
```
---
## 相关文档
- [官方自托管文档](https://docs.sim.ai/self-hosting/docker)
- [Ollama 集成指南](https://docs.sim.ai/self-hosting/docker)
- [vLLM 配置说明](https://docs.vllm.ai/)
- [Helm Chart 完整配置](https://github.com/simstudioai/sim/blob/main/helm/sim/README.md)
---
## 扩展与定制
### 相关页面
相关主题：[块系统与注册表](#page-block-registry), [连接器框架](#page-connectors)
相关源码文件
以下源码文件用于生成本页说明：
- [apps/sim/blocks/blocks/custom](https://github.com/simstudioai/sim/blob/main/apps/sim/blocks/blocks/custom)
- [apps/sim/api/tools/custom/route.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/api/tools/custom/route.ts)
- [apps/sim/app/api/mcp](https://github.com/simstudioai/sim/blob/main/apps/sim/app/api/mcp)
- [apps/sim/app/api/copilot](https://github.com/simstudioai/sim/blob/main/apps/sim/app/api/copilot)
- [apps/sim/ee](https://github.com/simstudioai/sim/blob/main/apps/sim/ee)
- [.agents/skills](https://github.com/simstudioai/sim/blob/main/.agents/skills)
- [scripts/generate-docs.ts](https://github.com/simstudioai/sim/blob/main/scripts/generate-docs.ts)
- [apps/sim/lib/workflows/triggers/triggers.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/triggers/triggers.ts)
- [apps/sim/lib/api/contracts/types.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/api/contracts/types.ts)
- [apps/sim/lib/webhooks/pending-verification.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/pending-verification.ts)
# 扩展与定制
## 概述
Sim 平台提供了丰富的扩展与定制机制，允许开发者在多个层面自定义和扩展系统功能。这些扩展点包括自定义块（Custom Blocks）、API 路由扩展、Webhook 集成、MCP（Model Context Protocol）扩展以及 Copilot 扩展。Sim 的设计理念强调模块化和可插拔性，使得开发者能够根据业务需求灵活地添加新功能，同时保持核心系统的稳定性和一致性。
扩展机制的核心架构遵循以下原则：首先，所有扩展都通过标准化的接口定义进行注册和管理；其次，扩展遵循统一的数据模型和类型系统；最后，扩展可以访问相同的核心服务和工具函数库。这种设计确保了扩展与核心系统之间的高度兼容性，同时也便于维护和升级。
Sim 的扩展系统还支持自动化文档生成，通过 `scripts/generate-docs.ts` 脚本可以扫描块目录并提取元数据，自动生成标准化的 Markdown 文档。文档生成器会扫描 `apps/sim/blocks/blocks/` 目录，提取每个块的名称、描述、分类、输入输出规范以及配置参数，然后更新导航元数据文件。这种自动化机制确保了文档与代码的同步更新，减少了人工维护的工作量。
## 自定义块系统
### 块结构与定义
自定义块是 Sim 平台扩展的基本单元，每个块都遵循统一的定义规范。块的定义包括元数据（名称、描述、分类）、输入输出规格以及配置参数。块的元数据存储在定义文件中，文档生成器会扫描这些文件并提取相关信息。块的分类决定了其在工作流设计器中的展示位置和分组方式，常见的分类包括触发器（triggers）、工具（tools）、转换器（transformers）等。
块系统支持多种类型的输入输出连接，包括字符串、数字、布尔值、数组、对象等数据类型。每个块可以定义多个输入端口和输出端口，端口之间的连接遵循类型兼容性规则。块的配置参数允许用户在实例化块时指定行为选项，这些参数在运行时被读取并传递给块的执行逻辑。
### 自定义块注册
自定义块的注册通过 `@/blocks` 模块进行管理，该模块提供了获取块、获取所有块、获取块类型等接口。块的注册表（registry）存储了所有可用块的引用，开发者可以通过 `getBlock` 函数根据块类型获取块定义，通过 `getBlocksByCategory` 函数获取特定分类下的所有块。块的验证通过 `isValidBlockType` 函数进行，确保只有注册的有效块类型才能在工作流中使用。
块的注册过程还支持按工具名称查找，通过 `getBlockByToolName` 函数可以根据工具的别名获取对应的块定义。这种设计使得块的定义与外部工具名称解耦，便于在不影响现有工作流的情况下替换或升级底层实现。块的注册表还支持动态更新，允许在运行时添加或移除块类型。
### 块的执行与输出
块的执行由执行器（executor）统一管理，执行器负责解析工作流、调度块执行、处理依赖关系以及收集输出。执行器提供了块输出处理模块（block-outputs），用于计算每个块的有效输出。有效输出的计算考虑了前置块的条件分支和循环结构，确保只有实际执行的块才会产生输出。
块的输出格式遵循统一的数据结构，包括输出值、元数据、错误信息等字段。输出处理模块支持注释模式（annotation-only mode），在这种模式下块不会产生实际的执行结果，只记录执行信息。这种机制用于调试和性能分析，帮助开发者理解工作流的执行过程和性能瓶颈。
```mermaid
graph TD
A[工作流定义] --> B[块注册表]
B --> C[块执行器]
C --> D[依赖解析]
D --> E[块执行]
E --> F[输出收集]
F --> G[结果聚合]
C --> H[块输出处理]
H --> I[有效输出计算]
I --> G
```
## API 扩展机制
### 路由合约系统
Sim 的 API 扩展基于类型安全的路由合约系统，该系统定义在 `apps/sim/lib/api/contracts/types.ts` 中。路由合约（ApiRouteContract）是一个泛型类型，包含参数（params）、查询（query）、请求体（body）、请求头（headers）、响应模式（response mode）以及响应定义（response）等六个维度的类型信息。这种设计确保了 API 的输入输出在整个应用中都遵循一致的类型约束。
路由合约系统提供了多个辅助类型来提取合约中的特定部分：`ContractParams` 用于提取参数类型，`ContractQuery` 用于提取查询参数类型，`ContractBody` 用于提取请求体类型，`ContractHeaders` 用于提取请求头类型。这些辅助类型通过 TypeScript 的条件类型（conditional types）实现，能够在编译时从合约定义中提取出对应的类型信息。
响应模式支持两种类型：JSON 模式和流模式（stream mode）。JSON 模式适用于小规模的、结构化的响应数据，而流模式适用于需要逐步返回大量数据或实时更新场景的 API。路由合约的响应定义使用 Zod schema 进行声明式验证，确保 API 的响应符合预期的数据结构。
### 自定义 API 路由
自定义 API 路由位于 `apps/sim/api/tools/custom/route.ts`，开发者可以在此目录下添加新的 API 端点。路由文件遵循 Next.js 的 API 路由规范，每个文件导出一个或多个 HTTP 方法处理器（GET、POST、PUT、DELETE 等）。路由处理器接收请求上下文，包括请求参数、查询字符串、请求体和请求头，然后执行业务逻辑并返回响应。
自定义路由的开发流程包括：定义路由合约、指定请求处理逻辑、注册路由到应用。对于需要认证的路由，路由处理器可以通过中间件机制注入认证信息。对于需要访问数据库的路由，路由处理器通过依赖注入获取数据库连接实例。这种设计保持了路由逻辑的纯净性，便于单元测试和代码复用。
API 路由的验证层自动使用合约定义中的 schema 进行输入验证，验证失败时返回标准化的错误响应。验证包括类型检查、格式验证、范围验证以及自定义验证规则。验证规则的定义使用 Zod 库，支持链式调用和复合条件，使得复杂的数据验证逻辑易于表达和维护。
### Confluence 工具集成
Sim 提供了与 Atlassian Confluence 的深度集成，作为 API 扩展的一部分。Confluence 相关的路由定义位于 `apps/sim/lib/api/contracts/selectors/confluence.ts`，包括空间选择器（spaces selector）、页面选择器（pages selector）和页面详情获取等端点。这些端点提供了统一的接口来查询和操作 Confluence 内容。
Confluence 路由使用通用的响应类型（`z.unknown()`），因为不同的 Confluence API 端点返回的数据结构差异较大。这种设计提供了灵活性，允许调用方处理任意形状的响应数据。路由合约定义了查询参数和请求体的 schema，但响应数据保持无类型状态，由调用方负责解析和处理。
Confluence 集成支持分页查询，返回结果包含数据数组和游标（cursor）信息。调用方可以使用游标进行后续查询，实现大结果集的遍历。空间选择器返回空间列表和可选的下一页游标，页面选择器返回文件列表，每个文件包含标识符和名称等基本信息。
## Webhook 集成系统
### Webhook 提供者架构
Sim 的 Webhook 系统支持多个第三方服务的集成，包括 Gong、Webflow、Vercel、Typeform 等。每个提供者（provider）实现统一的接口，提供事件解析、数据转换、认证验证和事件过滤等功能。提供者架构定义在 `apps/sim/lib/webhooks/` 目录下，每个提供者位于独立的子目录中。
Webhook 处理流程包括接收请求、验证签名、解析事件、过滤事件、转换数据和触发工作流等步骤。每个步骤都可以由提供者自定义实现，以适应不同服务的特性。例如，Gong 提供者可能需要提取通话相关的元数据，而 Webflow 提供者可能需要处理 CMS 内容更新事件。
### 事件过滤机制
事件过滤是 Webhook 集成的关键功能，用于避免处理不相关的事件。每个提供者可以实现 `shouldSkipEvent` 方法，根据事件内容决定是否跳过处理。过滤条件通常基于配置参数，例如 Webflow 提供者可以根据配置的集合标识符（collectionId）过滤事件，只处理指定集合的更新。
过滤逻辑的执行发生在事件解析之后、工作流触发之前，这样可以确保过滤决策基于完整的解析后数据。提供者接收事件上下文（EventFilterContext），包括 Webhook 配置、请求体和请求标识符等信息。过滤决策由同步函数执行，返回布尔值表示是否跳过该事件。
### 待验证 Webhook 处理
某些 Webhook 服务（如 Shopify、Webflow）要求接收方响应验证请求，以确认端点的有效性。Sim 实现了待验证 Webhook 处理机制，位于 `apps/sim/lib/webhooks/pending-verification.ts`。该机制支持多种验证协议，包括 GET 请求验证、HEAD 请求验证和 POST 请求验证。
验证请求的存储使用 Redis 作为持久化后盾，同时维护内存缓存以提高查询性能。验证条目包含路径、过期时间和元数据，Redis 键使用前缀 `REDIS_KEY_PREFIX` 命名以避免与其他数据冲突。验证条目过期后自动从存储中移除，无需手动清理。
支持的待验证 Webhook 提供者包括 Ashby、Grain、Generic 和 Salesforce。每个提供者定义匹配器（matcher），用于判断请求是否属于待验证请求。匹配器检查请求方法、请求体结构和特定字段值。例如，Generic 提供者的匹配规则是：GET 或 HEAD 请求，或者空请求体的 POST 请求。
## MCP 扩展
### MCP 协议概述
MCP（Model Context Protocol）是一种用于扩展 AI 模型能力的协议标准，Sim 通过 `apps/sim/app/api/mcp` 端点提供 MCP 支持。MCP 扩展允许外部系统通过标准化接口调用 Sim 的功能，同时支持工具注册、资源访问和提示模板等功能。MCP 协议采用 JSON-RPC 格式进行通信，支持请求-响应和通知两种消息模式。
MCP 扩展的核心组件包括：工具注册表、资源管理器、提示引擎和会话管理器。工具注册表维护所有可用 MCP 工具的定义，包括工具名称、描述、参数 schema 和返回值类型。资源管理器提供对 Sim 内部数据的受控访问，支持基于权限的数据隔离。提示引擎允许调用方定义和复用复杂的提示模板。
### MCP 端点实现
MCP 端点实现遵循 JSON-RPC 2.0 规范，支持 `initialize`、`tools/list`、`tools/call`、`resources/list`、`resources/read` 等标准方法。端点接收 JSON-RPC 请求，执行对应的处理逻辑，并返回 JSON-RPC 响应。错误响应包含错误代码、消息和可选的附加数据。
工具调用是 MCP 扩展的核心功能，允许外部系统触发 Sim 中的工作流或执行特定操作。工具调用请求包含工具名称和参数对象，响应包含执行结果或错误信息。工具调用的执行由工作流执行引擎驱动，支持同步和异步两种执行模式。异步执行模式返回任务标识符，调用方可以通过任务标识符查询执行状态和结果。
### MCP 工具定义
MCP 工具的定义存储在配置文件中，定义了工具的元数据和行为规范。每个工具定义包括唯一标识符、显示名称、描述文本、参数 schema 和返回值 schema。参数 schema 使用 JSON Schema 格式，支持必填参数、可选参数、类型约束和默认值等特性。
工具定义的版本管理支持向后兼容性，工具实现可以识别旧版本的参数并提供兼容处理。工具的参数验证在执行前进行，验证失败时返回明确的错误信息，指导调用方提供正确的参数。工具的返回值类型在工具定义中声明，调用方可以依赖这些信息进行类型安全的响应处理。
## Copilot 扩展
### Copilot 集成架构
Copilot 扩展提供与 AI 编程助手的功能集成，位于 `apps/sim/app/api/copilot` 端点。Copilot 集成允许 AI 模型访问 Sim 的上下文信息，包括工作流定义、块配置、执行历史等。这种集成使得 AI 模型能够基于实际的项目上下文生成更准确的建议和代码。
Copilot 扩展采用插件架构，核心系统提供基础接口，扩展模块实现具体的 AI 提供者适配。当前实现支持主流的 AI 提供者，包括 OpenAI、Anthropic 和本地模型服务。每个提供者适配器处理认证、请求格式化和响应解析等细节，使得上层逻辑与具体的 AI 服务解耦。
### 上下文管理
Copilot 扩展的上下文管理模块负责收集和组织传递给 AI 模型的信息。上下文信息来源包括：工作流配置、块定义、变量值、用户偏好和历史交互等。上下文信息的收集遵循最小必要原则，避免传递过多无关信息影响 AI 模型的处理效率和响应质量。
上下文信息的组织采用分层结构，包括全局上下文、工作流上下文和块级上下文三个层次。全局上下文包含项目级别的通用信息，工作流上下文包含特定工作流的配置和状态，块级上下文包含单个块的详细信息。分层组织便于 AI 模型根据需要访问不同范围的信息。
### 建议生成与执行
Copilot 扩展的建议生成功能基于上下文信息和用户请求，生成工作流配置建议、块参数建议和优化建议等。建议的生成由 AI 模型驱动，模型根据上下文推理出最可能的用户意图，然后生成相应的建议内容。建议的格式可以是完整的配置片段，也可以是增量修改指令。
建议的执行支持预览和确认机制，用户可以在执行前预览建议的效果，确认无误后再应用到实际的工作流中。执行过程记录在审计日志中，便于追踪建议的来源和执行结果。Copilot 扩展还支持反馈收集，用户可以对建议的质量进行评分，评分信息用于持续改进建议生成模型。
## 触发器系统
### 触发器类型
触发器是工作流的入口点，决定了工作流何时以及如何被激活。Sim 支持多种触发器类型，包括手动触发（manual）、API 触发（api）、聊天触发（chat）和定时触发（scheduled）。触发器类型的识别通过 `TRIGGER_TYPES` 常量和 `classifyStartBlockType` 函数实现，支持新的显式分类方式和旧版的触发模式标记。
触发器类型的分类逻辑首先检查块配置中的分类是否为 'triggers'，然后检查块是否启用了 `triggerMode` 标记，最后检查块类型是否为遗留的起始块（starter block）。这种多层检查确保了向后兼容性，同时支持新的触发器设计模式。
### 触发器引用别名
触发器引用别名机制允许在工作流中使用简短的别名来引用触发器类型。`TRIGGER_REFERENCE_ALIAS_MAP` 定义了别名到具体触发器类型的映射，包括 `start`、`api`、`chat` 和 `manual` 四个别名。这些别名用于内联引用，格式为 ``、`` 等。
别名映射的设计简化了工作流的编写，用户无需记忆完整的触发器类型标识符。别名到类型的映射是单向的，具体类型到别名的反向映射需要额外实现。别名机制还支持自定义扩展，开发者可以在映射表中添加新的别名和对应的触发器类型。
### 触发器工具函数
`TriggerUtils` 类提供了一系列工具函数用于操作和检查触发器。`isTriggerBlock` 函数判断给定的块是否是触发器类型，检查逻辑包括分类、模式和旧版标识三个维度。`isTriggerType` 函数判断块是否属于特定的触发器类型，接收块对象和目标类型作为参数。
触发器输出（trigger outputs）由 `getTriggerOutputs` 函数获取，返回触发器块产生的输出数据。这些输出数据可以在后续的块中使用，传递触发事件的相关信息，例如 Webhook 请求内容、API 调用参数或定时触发的时间戳等。输出数据的格式和内容取决于触发器类型和配置。
```mermaid
graph TD
A[触发事件] --> B{触发器类型判断}
B -->|manual| C[手动触发器]
B -->|api| D[API 触发器]
B -->|chat| E[聊天触发器]
B -->|scheduled| F[定时触发器]
C --> G[读取子块配置]
D --> G
E --> G
F --> G
G --> H[返回触发模式]
H --> I[startWorkflow 子块]
I --> J[触发器输出]
```
## 企业扩展（EE）
### 企业功能架构
企业扩展（Enterprise Edition）模块位于 `apps/sim/ee` 目录，提供面向大规模部署和企业级应用的增强功能。企业扩展包括高级安全特性、审计日志、细粒度权限控制、高可用部署支持等功能。这些功能面向有严格合规要求和运营标准的企业客户。
企业扩展的设计遵循模块化原则，核心功能与扩展功能分离部署。企业功能可以作为独立模块启用或禁用，不需要修改核心代码。这种设计降低了企业的使用门槛，同时保持了核心系统的简洁性。企业功能的配置通过环境变量和管理界面进行，支持动态生效。
### 企业级 API
企业扩展提供了增强的 API 接口，包括批量操作支持、异步处理能力和高级过滤选项。批量操作 API 允许一次请求处理多个资源，适用于数据迁移和批量配置等场景。异步处理 API 返回任务标识符，调用方可以轮询或等待任务完成通知。
企业 API 的认证机制支持多种协议，包括 OAuth 2.0、SAML 和 LDAP。企业 API 的限流策略比标准 API 更宽松，但需要额外的配额管理机制。配额信息通过 `UsageLimits` 接口获取，包括同步限流、异步限流、当前使用量和限额等信息。
## 技能系统
### 技能定义与注册
技能（Skills）系统位于 `.agents/skills` 目录，定义了 AI 代理可以执行的操作集合。技能是比块更高级的抽象，一个技能可能由多个块组成，形成完整的操作流程。技能的注册和管理由技能引擎处理，支持技能的发现、调用和监控。
技能定义包含技能标识符、名称、描述、参数定义、返回值定义和实现代码。参数和返回值使用类型化的 schema 定义，支持复杂的嵌套结构和自定义验证规则。实现代码支持多种语言和执行环境，包括 JavaScript、Python 和 Shell 脚本等。
### 技能编排
技能的编排功能允许组合多个技能形成更复杂的操作序列。编排支持顺序执行、并行执行和条件分支三种基本模式。顺序执行按照定义的顺序依次调用技能，前一个技能的输出作为后一个技能的输入。并行执行同时调用多个技能，提高执行效率，适用于独立的操作。
条件分支根据中间结果决定后续执行的技能路径。条件表达式支持简单的比较操作和复杂的布尔逻辑。编排的执行由编排引擎驱动，引擎负责管理执行上下文、处理异常和维护执行状态。编排失败时支持回滚操作，恢复到执行前的状态。
## 测试与验证框架
### 测试工具库
Sim 提供了完整的测试工具库，位于 `packages/testing/src` 目录。测试工具库包括环境变量模拟（env mock）、数据库模拟、网络请求模拟等功能。环境变量模拟（`createEnvMock`）允许测试用例覆盖和恢复环境变量值，支持字符串、数字和布尔值类型的模拟。
环境变量模拟提供了多种辅助函数：`getEnv` 返回模拟的值，`isTruthy` 判断真值，`isFalsy` 判断假值，`envNumber` 解析数字并支持最小值约束。这些辅助函数覆盖了环境变量处理的各种场景，确保测试用例能够模拟真实的运行环境。
### 模拟与存根
测试工具库提供了完善的模拟和存根功能，用于隔离被测试代码的依赖。模拟（mock）替换整个模块的实现，存根（stub）替换特定的函数或方法。模拟和存根的配置通过工厂函数创建，支持默认行为定义和行为覆盖。
测试工具库还提供了预设的模拟集合（`envMock`），可以直接用于常见的测试场景。预设模拟包含合理的环境变量默认值，无需额外的配置即可在测试中使用。这种开箱即用的设计简化了测试用例的编写，同时保证了测试环境的一致性。
### 集成测试支持
集成测试支持模块提供了端到端的测试能力，包括 API 测试、Webhook 测试和工作流测试等。API 测试使用路由合约定义进行请求构造和响应验证，确保 API 的行为符合规范。Webhook 测试模拟外部服务的请求，验证 Webhook 处理器的解析和过滤逻辑。
工作流测试支持完整的工作流执行模拟，包括触发器激活、块执行和输出收集等步骤。测试用例可以控制块的模拟返回值，验证工作流在各种输入条件下的行为。测试结果包括执行时间、块调用顺序和输出数据，便于分析工作流的性能和正确性。
## 扩展开发最佳实践
### 代码组织
扩展代码应遵循统一的目录结构和命名约定。自定义块放在 `apps/sim/blocks/blocks/custom` 目录下，每个块独占一个子目录，目录名称使用 kebab-case 格式。块的定义文件使用 `index.ts` 命名，导出块的元数据和实现函数。
API 扩展放在 `apps/sim/api/tools/custom` 目录下，遵循 Next.js 的 API 路由文件命名规范。路由文件使用 `route.ts` 命名，导出一个或多个 HTTP 方法处理器。相关的类型定义和工具函数放在同目录的 `*.ts` 文件中，与路由文件保持同级的组织关系。
### 文档维护
扩展开发者应维护清晰的代码文档，文档使用 JSDoc 格式编写。块定义需要包含名称、描述、输入输出说明和使用示例。API 路由需要包含端点说明、参数说明和响应示例。文档生成器会从代码注释中提取信息，自动生成用户文档。
手动添加的文档内容应放在指定的区域，使用标记 `` 和 `` 包裹。文档生成器会保留手动添加的内容，不会被自动生成的内容覆盖。这种机制允许开发者在自动文档的基础上添加额外的说明、示例和注意事项。
### 安全性考虑
扩展开发应遵循安全最佳实践，避免引入安全漏洞。所有用户输入必须进行验证和清理，使用 Zod schema 或自定义验证函数。用户输入不应直接用于数据库查询或命令执行，应使用参数化查询和安全的 API 调用。
敏感信息（如 API 密钥、访问令牌）不应硬编码在代码中，应使用环境变量或密钥管理服务。Webhook 处理应验证请求签名，防止伪造请求攻击。API 端点应实现适当的限流和认证机制，防止滥用和未授权访问。
## 配置选项参考
| 配置类别 | 选项名称 | 类型 | 默认值 | 说明 |
|---------|---------|------|--------|------|
| 构建 | `NODE_OPTIONS` | string | `--max-old-space-size=8192` | Node.js 运行时选项 |
| 构建 | `build:sandbox-bundles` | command | - | 沙箱包构建命令 |
| 测试 | `test` | command | `vitest run` | 测试运行命令 |
| 测试 | `test:coverage` | command | `vitest run --coverage` | 覆盖率测试命令 |
| 类型检查 | `type-check` | command | `tsc --noEmit` | TypeScript 类型检查 |
| 格式 | `lint` | command | `biome check --write` | 代码检查和修复 |
| 格式 | `format` | command | `biome format --write` | 代码格式化 |
| 文档 | `generate-docs` | command | `bun run ../../scripts/generate-docs.ts` | 文档生成 |
## 相关资源
- 官方文档：https://docs.sim.ai
- GitHub 仓库：https://github.com/simstudioai/sim
- Docker 部署文档：https://docs.sim.ai/self-hosting/docker
- 本地模型支持：Ollama（https://ollama.ai）、vLLM（https://docs.vllm.ai/）
---
---
## Doramagic 踩坑日志
项目：simstudioai/sim
摘要：发现 20 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 社区讨论暴露的待验证问题：Open-source general purpose agent with built-in MCPToolkit support。
## 1. 安装坑 · 社区讨论暴露的待验证问题：Open-source general purpose agent with built-in MCPToolkit support
- 严重度：medium
- 证据强度：source_linked
- 发现：Open-source general purpose agent with built-in MCPToolkit support 15 May 2025 · ... MCP for local-agent workflows · r/LocalLLaMA - A visual ... r/commandline - CLI tool to simplify open source monitoring agent installation.
- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。
- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。
- 证据：social_signal:reddit | ssig_7a250aac9fa1441c8186a7b73d669d8f | https://www.reddit.com/r/LocalLLaMA/comments/1kn8m8t/opensource_general_purpose_agent_with_builtin/ | Open-source general purpose agent with built-in MCPToolkit support
## 2. 配置坑 · 可能修改宿主 AI 配置
- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- 证据：capability.host_targets | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | host_targets=cursor
## 3. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | README/documentation is current enough for a first validation pass.
## 4. 运行坑 · 来源证据：v0.6.63
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.6.63
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_5a97e1d742fe4d7f918e0b42f27b87c3 | https://github.com/simstudioai/sim/releases/tag/v0.6.63 | 来源类型 github_release 暴露的待验证使用条件。
## 5. 运行坑 · 来源证据：v0.6.65
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.6.65
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_03f18559029c4724b11011ef96259161 | https://github.com/simstudioai/sim/releases/tag/v0.6.65 | 来源类型 github_release 暴露的待验证使用条件。
## 6. 运行坑 · 来源证据：v0.6.67
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.6.67
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_048d1506c1d645b0be435841a26b93ed | https://github.com/simstudioai/sim/releases/tag/v0.6.67 | 来源类型 github_release 暴露的待验证使用条件。
## 7. 运行坑 · 来源证据：v0.6.73
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.6.73
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_048864e1cdcc44d2b2a30917b7c4adc2 | https://github.com/simstudioai/sim/releases/tag/v0.6.73 | 来源类型 github_release 暴露的待验证使用条件。
## 8. 维护坑 · 来源证据：v0.6.71
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v0.6.71
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_9c30d794fb7344489f96a6ac47cd1d6e | https://github.com/simstudioai/sim/releases/tag/v0.6.71 | 来源类型 github_release 暴露的待验证使用条件。
## 9. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | last_activity_observed missing
## 10. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | no_demo; severity=medium
## 11. 安全/权限坑 · 存在安全注意事项
- 严重度：medium
- 证据强度：source_linked
- 发现：No sandbox install has been executed yet; downstream must verify before user use.
- 对用户的影响：用户安装前需要知道权限边界和敏感操作。
- 建议检查：转成明确权限清单和安全审查提示。
- 防护动作：安全注意事项必须面向用户前置展示。
- 证据：risks.safety_notes | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | No sandbox install has been executed yet; downstream must verify before user use.
## 12. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | no_demo; severity=medium
## 13. 安全/权限坑 · 来源证据：Unable to Access Files from Private GitHub Repository in Self-Hosted Setup
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Unable to Access Files from Private GitHub Repository in Self-Hosted Setup
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_ed1c9f64533441f5826c1fe98fa9ce49 | https://github.com/simstudioai/sim/issues/4555 | 来源类型 github_issue 暴露的待验证使用条件。
## 14. 安全/权限坑 · 来源证据：v0.6.64
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.6.64
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_5e2aa5311b1748cea446771920242668 | https://github.com/simstudioai/sim/releases/tag/v0.6.64 | 来源类型 github_release 暴露的待验证使用条件。
## 15. 安全/权限坑 · 来源证据：v0.6.66
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.6.66
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_7d42c79fecf54003b117f76d49873223 | https://github.com/simstudioai/sim/releases/tag/v0.6.66 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。
## 16. 安全/权限坑 · 来源证据：v0.6.68
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.6.68
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_c8fe17ce7ba6424c88017ed644620915 | https://github.com/simstudioai/sim/releases/tag/v0.6.68 | 来源类型 github_release 暴露的待验证使用条件。
## 17. 安全/权限坑 · 来源证据：v0.6.69
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.6.69
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_a47b6988921146ac8fa66d73b0574c88 | https://github.com/simstudioai/sim/releases/tag/v0.6.69 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。
## 18. 安全/权限坑 · 来源证据：v0.6.72
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.6.72
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_f13817452da14b5d97c64bde45647685 | https://github.com/simstudioai/sim/releases/tag/v0.6.72 | 来源类型 github_release 暴露的待验证使用条件。
## 19. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | issue_or_pr_quality=unknown
## 20. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | release_recency=unknown