项目概述

Sim 是一个开源的 AI Agent 工作流可视化编排平台，其核心定位是"在聊天中构建一切"的 AI 命令中心：用户以自然语言描述需求，系统理解工作区上下文并直接执行——构建 agent、运行工作流、查询数据、生成文档。仓库同时提供两套 Docker Compose 部署方案，docker-compose.prod.yml（生产栈，监听 3000/3002/5432 等端口）与 docker-compose.ollama.yml（附带本地 Ollama，通过 --profile setup 触发模型初始化）。

社区反馈显示，最常见的痛点集中在 VPS 自托管场景——Copilot、AI Agent、Ollama 集成、登录流程在容器化部署时频繁出现兼容性问题（参见 issue #895）。这反映出仓库的部署架构仍在快速演进，本地化文档与生产部署之间存在落差。

资料来源：README.md:1-40

顶层 Monorepo 结构

仓库根采用 Turborepo + pnpm workspaces 的 monorepo 组织方式。根 package.json 暴露了几个关键决策：

graph TD
    Root[sim monorepo 根目录<br/>Turborepo 2.9.14]
    Root --> AppSim[apps/sim<br/>Next.js 主应用]
    Root --> Docs[apps/docs<br/>集成文档站点]
    Root --> Pii[apps/pii<br/>Python Presidio 侧车]
    Root --> Cli[packages/cli<br/>Node CLI]
    Root --> Sdk[packages/ts-sdk<br/>TypeScript SDK]
    Root --> Sec[packages/security<br/>安全工具]
    Root --> Test[packages/testing<br/>测试工具集]
    Root --> Utils[packages/utils<br/>共享纯函数]
    Root --> TsCfg[packages/tsconfig<br/>共享 tsconfig]
    Root --> Scripts[scripts/<br/>集成文档生成器]

资料来源：package.json:1-50

主要子项目职责

• apps/sim 是产品核心。apps/sim/package.json 显示其依赖 [email protected]、[email protected]、@trigger.dev/[email protected]、TipTap 富文本栈、FFmpeg、busboy 等——支撑工作流画布、Agent 执行、文件与触发器。
• packages/cli 是基于 [email protected] + [email protected] + [email protected] 的脚手架工具，封装项目本地化操作。
• packages/ts-sdk 是面向外部使用者的公共 SDK（publishConfig.access: public，要求 node >=16）。
• packages/security 与 packages/testing 是内部支撑包，独立维护 vitest 测试配置。packages/testing/src/builders/index.ts 导出 WorkflowBuilder.linear(3)、ExecutionContextBuilder 等流式构造器；packages/testing/src/assertions/index.ts 提供 expectBlockExecuted、expectPermissionDenied 等语义化断言；packages/testing/src/mocks/schema.mock.ts 则提供 Drizzle ORM schema 的 mock（如 usageLog、credential）。
• apps/docs 是文档站，其 .mdx 集成页由 scripts/README.md 描述的生成器从 apps/sim 的 block/tool/trigger 注册表自动派生。
• apps/pii 是 Python Presidio 侧车，由 docker/pii.Dockerfile 构建，提供 /analyze、/anonymize、/health。

资料来源：apps/sim/package.json:1-60、packages/cli/package.json:1-30、packages/ts-sdk/package.json:1-30、packages/security/package.json:1-20、packages/testing/package.json:1-30、apps/sim/lib/guardrails/README.md:1-30

文档即派生制品

scripts/README.md 明确指出集成文档是派生工件：.mdx 文件不应手改，会在下次生成时被覆盖；唯一可编辑区域是 MANUAL-CONTENT 标记块（支持的 section：intro、usage、configuration、outputs、notes）。CI 在推送到 main 时会重新生成并自动提交。

这种"代码即文档源"的模式让仓库在 v0.7.4–v0.7.7 之间一口气接入 Square、Context.dev、Grafana、Daytona、Convex 等数十个集成时，文档能够自动保持同步。同样的契约也适用于 apps/docs/components/icons.tsx——它由 sim 应用推导而非手维护。

资料来源：scripts/README.md:1-50

辅助服务与社区关切

Guardrails 模块展示了仓库的微服务化倾向：JSON / Regex / 幻觉检测为 TypeScript 内置 validator，但 PII 检测 委托给独立的 Presidio Python 侧车，运行时通过 PII_URL=http://localhost:5001 连接。该设计在 v0.7.13 中进一步强化为"发布 PII 镜像到 GHCR 并加入 Helm chart"。此外，apps/sim/app/api/tools/evernote/lib/thrift.ts 实现了一个最小化的 Thrift 二进制协议编解码器，仅覆盖 NoteStore 操作所需类型（TYPE_STOP、TYPE_BOOL、TYPE_I32、TYPE_STRING、TYPE_STRUCT、TYPE_LIST），反映处理遗留协议时的工程取舍。

社区最近的高频诉求反向影响 monorepo 结构：

1. 自定义 LLM 接入 —— issues #801、#1579、#1637 都要求支持自定义 OpenAI 兼容 URL（DeepInfra、llama.cpp、LM Studio、Ollama），仓库在 v0.7.9 引入"大附件通过 Files API / 远程 URL"作为铺垫。
2. 企业级审计 —— issue #3975 提出"签名审计轨迹" RFC，反映当前执行历史缺乏密码学完整性保证。
3. MCP 生态 —— issue #1553 希望在平台内直接创建与管理 MCP server。

@aws-sdk/client-appconfig 的引入正是为运行时特性开关打基础，使新模型与集成能力可以渐进式发布，与上述社区诉求相呼应。

资料来源：apps/sim/app/api/tools/evernote/lib/thrift.ts:1-20

See Also

• Block & Integration Registry
• Guardrails & PII Detection
• Self-hosting Deployment Guide
• Workflow Execution & Audit Trail

概述

Sim Studio 的工作流引擎与可视化构建器是平台的核心模块，它将 AI 智能体、外部 API、条件分支、循环、人工审批与护栏校验等多种能力以"块（Block）"的形式抽象为可视化节点，使开发者能够在画布上拖拽、连接并部署端到端的智能体工作流。每个块在 apps/sim/blocks/blocks/ 中以独立的 TypeScript 模块存在，定义其 type、name、category、bgColor、配置子块、暴露的 tools.access 动作列表以及 outputs 结构 资料来源：apps/sim/blocks/blocks/agent.ts。

可视化层基于 ReactFlow 11 构建，画布节点的拓扑关系由节点之间的有向边（edge）承载 资料来源：packages/workflow-types/package.json。社区中关于本地 LLM 连接（#1637、#1579）、自定义 OpenAI 兼容 URL（#801）以及托管 MCP 服务器（#1553）等高频需求都集中在 agent 块的 Provider 与 Model 配置子块中处理。

核心块类型

工作流引擎将所有能力统一抽象为"块"，不同 type 对应不同的运行时语义。下表列出平台中常见的核心块类型及其职责：

对于集成类块（如 Gmail、Hubspot），tools.access 字段描述该块暴露哪些 Action；scripts/README.md 中描述的文档生成器会把它作为"事实来源"读取，并据此自动渲染 docs 站点的 ## Actions 与 ## Triggers 段落 资料来源：scripts/README.md。这也意味着：若要新增一个集成，只需要分别在 blocks/blocks/、tools/、triggers/ 三处补充 TypeScript 即可，文档会自动同步。

工作流状态模型

画布上的拖拽结果在内部被序列化为一个工作流状态对象。该对象由三个核心映射组成 资料来源：packages/testing/src/factories/workflow.factory.ts：

• blocks：以块 ID 为键，每个节点包含 type、name、position、subBlocks、outputs、enabled 等字段；
• edges：有向边数组，每条边具有 source、target、sourceHandle（用于区分条件分支的 if / else 端口）；
• loops：循环容器与其子块的映射，子块通过 parentId 关联至循环块。

WorkflowBuilder 工具类提供了链式 API 构造典型拓扑，例如 WorkflowBuilder.branching() 会自动注入 condition-if 与 condition-else 两个 sourceHandle，这与 condition.ts 中定义的输出端口一一对应 资料来源：packages/testing/src/builders/workflow.builder.ts。类似地，withLoop(iterations) 与 linear(n) 等静态方法可一键生成线性、循环与分支工作流，是端到端测试与示例填充的标准脚手架。

graph LR
  Start([starter]) --> Cond{condition}
  Cond -- condition-if --> A[true-branch]
  Cond -- condition-else --> B[false-branch]
  A --> End([end])
  B --> End

执行上下文与决策

工作流进入执行阶段时，引擎会构造一个 ExecutionContext，它不仅携带工作流 ID，还记录执行期间的完整运行时状态 资料来源：packages/testing/src/builders/execution.builder.ts：

• blockLogs：每个块的标准输出与日志；
• metadata / environmentVariables / workflowVariables：环境与变量快照；
• decisions：router 与 condition 的实际取值，用于审计回放；
• loopExecutions / completedLoops / activeExecutionPath：循环路径与当前激活节点；
• abortSignal：取消信号，配合 ExecutionContextBuilder.createCancelled()、createWithTimeout() 工厂方法构造异常场景。

社区 RFC #3975 提出的"工作流执行签名审计追踪"正是建立在该决策与日志结构之上——通过对 blockLogs 与 decisions 进行链式哈希，可以让企业用户在不改工作流逻辑的前提下验证执行未被篡改（资料来源：RFC #3975）。

部署与运行时

工作流最终以 Docker Compose 形式发布，监听 3000 / 3002 / 5432 端口，建议宿主机预留 12GB 以上内存 资料来源：README.md。如需对接 Ollama、llama.cpp、LM Studio 等本地 LLM，可改用 docker-compose.ollama.yml 配置文件（社区反馈 #1637、#895 都指出默认镜像在低内存环境无法启动），这与 agent 块的 provider 下拉项保持一致。此外，自 v0.7.6 起，编程化触发工作流（Programmatic API）已纳入付费计划 资料来源：v0.7.6 release notes，自助部署用户需关注计费网关对外部触发的限制。

参见

• Integration Documentation Generator
• Guardrails Validators
• Testing Utilities
• Community RFC #3975: Signed Audit Trail
• Self-hosting Discussion #895

Chat、Copilot、Agent 与模型提供商

概述

Sim 平台的 Chat / Copilot 是面向工作区的"AI 命令中心"，用户以自然语言描述意图，Copilot 在掌握整个 workspace 上下文（工作流、连接器、知识库、表、文件）后，可直接创建、运行或查询 Agent 与工作流，并生成文件、报告与演示文稿。Copilot 与工作流编辑器中的 Agent 块共享同一套 LLM 提供商抽象与工具调用协议，从而保证"对话式构建"与"画布式构建"在模型选择、结构化输出与函数调用上的行为一致。

Copilot / Chat 体验

README 将 Copilot 定位为"build everything in chat"——以自然语言驱动 Sim 全栈操作。Copilot 会感知当前 workspace、读取其中的块与连接器，并代用户构建 agent、运行 agent、查询数据；其产物可以直接落地为文件或文档（见 README 中 *Build everything in Chat* 与 *Create files and documents* 章节）。这种"对话即构建"的形态降低了非技术用户使用 Sim 的门槛。资料来源：README.md

Agent 块的配置模型

工作流中的 Agent 块采用统一的子块（sub-block）声明式结构描述一次 LLM 调用，测试夹具与运行时共用同一形态：

测试工厂按上述结构构造 Agent 节点，并在工厂内串联 starter → api → function → agent 边以模拟真实工作流（资料来源：packages/testing/src/factories/workflow.factory.ts）。v0.7.9 的 feat(providers) 进一步支持通过 Files API 与远程 URL 投递大附件给 Agent 块，并对 Gemini/vLLM 的附件上限做了收紧（见 v0.7.9 发布说明）。

模型提供商抽象

平台以"块 + 工具 + 触发器"三段式承载所有外部服务（scripts/README.md）：每个集成的块声明在 apps/sim/blocks/blocks/<service>.ts，tools.access 暴露 actions，triggers 暴露可选的 webhook 能力。提供商枚举（OpenAI、Anthropic、Gemini、Ollama、vLLM 等）的运行时解析位于 apps/sim/app/api/providers/，承担三类职责：

1. 在 Copilot 的模型选择器中按用户凭据列出可用模型；
2. 在 Agent 块下拉中按 provider 过滤 model；
3. 为 OpenAI 兼容端点（llama-swap、llama.cpp、LM Studio、DeepInfra）提供统一基址。

apps/sim/package.json 声明了 @tiptap/react、@trigger.dev/sdk、croner、drizzle-orm、busboy、ffmpeg-static 等依赖，分别用于富文本聊天输入、定时与异步任务、计划触发与媒体处理，为 Copilot 与 Agent 块的输入/输出通道提供基础。

测试与构建器基础

平台为 Chat / Agent 行为提供了可复用的测试工具：

• WorkflowBuilder 提供流式 API 构造线性工作流，ExecutionContextBuilder 支持按块 ID 注入状态（packages/testing/src/builders/index.ts）；
• 自定义断言覆盖执行顺序、块启用、权限拒绝等场景（packages/testing/src/assertions/index.ts）；
• schema.mock.ts 暴露完整数据库 schema 形状，便于在测试中模拟 knowledgeConnector、credential（含 oauth / env_workspace / env_personal / service_account 四种凭据类型）等实体（packages/testing/src/mocks/schema.mock.ts）。

社区关注点

仓库的多个高互动 Issue 反映出本地 / 自托管 LLM 是社区最关心的方向：

• #801 呼吁支持自定义 OpenAI API URL，以接入 llama-swap、llama-server、Ollama 的 OpenAI 兼容模式；
• #1637 与 #1579 进一步要求直连 llama.cpp、LM Studio、DeepInfra 等"非 OpenAI 官方"端点；
• #895 报告自托管 VPS 时 Copilot、AI Agent、Ollama 集成易在登录与服务发现阶段失败；
• #1553 希望平台原生支持创建与管理 MCP Server，让 Agent 直接挂载自定义工具。

这些诉求直接影响"模型提供商"层——后续需要在 apps/sim/app/api/providers/ 下扩展更多 OpenAI 兼容适配器，并把 MCP 工具声明纳入 Agent 块的 tools 字段。

另请参阅

• Integration Documentation Generator：scripts/README.md
• Guardrails Validators：apps/sim/lib/guardrails/README.md
• App-level Dependencies：apps/sim/package.json
• Testing Package：packages/testing/package.json

Knowledge Bases、文件与表格

概述

Sim 平台为 AI Agent 工作流提供三类可被检索或注入的数据资产：知识库（Knowledge Bases） 用于向量化文档检索（RAG）、文件（Files） 用于在工具调用或工作流步骤之间传递结构化/非结构化资源、表格（Tables） 用于结构化数据的导入与预览。三者在数据建模层均通过 Drizzle ORM 进行持久化，并通过统一的测试 Mock 包（@sim/testing）对外暴露，以便上层 UI、Agent 块以及 Guardrails 复用。资料来源：packages/testing/src/mocks/index.ts:1-20

平台整体定位在 README 中描述为"AI command center"，强调"Build everything in Chat"——这意味着三类资产必须既能被 Copilot 直接索引，也能被 Agent 块在执行阶段按需检索。资料来源：README.md

知识库（Knowledge Bases）

知识库的持久化结构由两张核心表构成：knowledge 元数据表与 docsEmbeddings 向量/分块表。

• knowledge 表保存知识库配置与启用状态，字段包括 id、userId、workspaceId、name、description、embeddingModel、embeddingDimension、chunkSize、chunkOverlap、三个 boolean1/2/3 自定义过滤位、enabled 以及 contentTsv（PostgreSQL tsvector 全文检索列）。资料来源：packages/testing/src/mocks/schema.mock.ts:1-30
• docsEmbeddings 表存储实际切分后的文档片段，字段包含 chunkId、chunkText、sourceDocument、sourceLink、headerText、headerLevel、tokenCount、embedding、embeddingModel、metadata 以及 chunkTextTsv。这种"元数据 + 分块 + 嵌入向量 + tsvector"四元组结构同时支持语义检索与关键字检索。资料来源：packages/testing/src/mocks/schema.mock.ts:31-60

测试基础设施通过 @sim/testing 的 knowledgeApiUtilsMock 暴露知识库 API 的桩函数，便于在 Guardrails（幻觉检测）等模块中模拟检索行为。资料来源：packages/testing/src/mocks/index.ts:1-20 幻觉检测（Hallucination Detection）校验器正是基于知识库文档进行 RAG 比对，并依赖 LLM 打分。资料来源：apps/sim/lib/guardrails/README.md:1-15

下表汇总知识库的核心字段语义：

文件（Files）

apps/sim 的依赖列表表明文件子系统在客户端与服务器端均具备富文本与媒体处理能力：docx、docx-preview 用于 Word 文档生成与预览；ffmpeg-static + fluent-ffmpeg 用于音视频转码；csv-parse 用于结构化数据解析；busboy 处理 multipart 上传流。资料来源：apps/sim/package.json:1-80

测试工厂层 tool-responses.factory.ts 提供 Supabase、Notion 等服务的响应 Mock，意味着文件既可来自本地工作区，也可来自第三方集成检索结果，统一在工具调用上下文里以响应对象的形式传递。资料来源：packages/testing/src/factories/tool-responses.factory.ts:1-40

表格（Tables）

表格能力由 v0.7.10 的"stream large CSV previews and import-as-table"特性引入，依赖 csv-parse 对大文件进行流式解析。在前端表现为对超大 CSV 的流式分块渲染，在后端则体现为将解析后的行集作为表格结构注入到工作流变量，供下游节点按列引用。

数据流：从上传到检索

下图展示三类资产的典型数据通路——以知识库为例，文档从上传、切片、嵌入到最终被 Agent 检索的完整链路。

flowchart LR
  A[用户上传文档] --> B[knowledge 表<br/>写入元数据]
  B --> C[文档切片<br/>chunkSize / chunkOverlap]
  C --> D[调用 embeddingModel<br/>生成向量]
  D --> E[docsEmbeddings 表<br/>写入 chunk + embedding + chunkTextTsv]
  E --> F{检索请求}
  F -->|语义| G[向量相似度匹配]
  F -->|关键字| H[contentTsv / chunkTextTsv]
  G --> I[Agent 注入上下文]
  H --> I

失败模式与社区关切

• 检索一致性：docsEmbeddings 同时持有 embedding 与 chunkTextTsv，任一列写入失败都会导致混合检索结果偏移，需在事务内保证两者同步。资料来源：packages/testing/src/mocks/schema.mock.ts:31-60
• PII 与数据保留：v0.7.11/v0.7.13 引入 PII 识别（基于 Presidio sidecar）与 workspace 级别的保留期覆盖，知识库中的文档须走 apps/pii/server.py 提供的 /anonymize 流程后入库。资料来源：apps/sim/lib/guardrails/README.md:1-20
• 大文件预览：CSV 流式分块渲染需要 csv-parse 的增量解析，常见坑为未设置 BOM 跳过或字符编码不一致导致首列错位。

See Also

• Sim Studio 主仓库
• 集成文档生成器
• Guardrails 校验器说明

1. 概述与设计理念

Sim Studio 是一个可视化 AI Agent 工作流编排平台，其"集成（Integrations）"、"MCP（Model Context Protocol）服务器"与"工具（Tools）"构成了平台与外部世界交互的全部能力边界。在仓库中遵循一个核心本体论：一切皆为 Block（块），而一个"集成"则是一个拥有 Actions（操作）以及可选 Trigger（触发器）的 Block 资料来源：scripts/README.md:1-15。

这一设计让用户能够在画布上以统一方式拖拽并连接 Gmail、Slack、HubSpot、Notion、GitHub 等任意第三方服务，而底层的 Block / Tools / Triggers 注册表则由 apps/sim 内的 TypeScript 源码定义，并被 scripts/generate-docs.ts 自动编译为 apps/docs/content/docs/en/integrations/ 下的文档页面 资料来源：scripts/README.md:18-50。仓库以"代码即文档"的方式保证 integrations/*.mdx 与 Block 定义始终同步：CI 在合并到 main 后会自动重新生成并提交 资料来源：scripts/README.md:115-130。

2. 三层数据模型：Block、Tools、Triggers

每个集成在代码侧由三处源共同定义，形成清晰的关注点分离：

资料来源：scripts/README.md:8-16

Block.tools.access 通过 id 引用 Action，文档生成器会在 apps/sim/tools/ 中反查以渲染完整参数说明 资料来源：scripts/README.md:55-70。除了 category: 'tools' 的常规集成外，memory / knowledge / table 等类别也按相同流程处理 资料来源：scripts/README.md:75-90。

3. 文档自动生成与人工内容

generate-docs.ts 单次执行会完成四项任务 资料来源：scripts/README.md:60-110：

1. 图标同步 — 将 apps/sim/components/icons.tsx 复制到 apps/docs/components/icons.tsx，并构建 icon-mapping.ts。
2. Block Pass — 遍历所有工具类 Block，生成 integrations/<service>.mdx。
3. Trigger Pass — 读取 apps/sim/triggers/<provider>/，向对应服务页面追加 ## Triggers 章节；纯触发器服务会生成独立页面。
4. 索引重建 — 写出 integrations/meta.json 与首页的 integrations.json。

生成器强制遵守一条金科玉律：所有 .mdx 都是派生产物，不可手改，CI 会在下次推送时覆盖；唯一可编辑区域是 MANUAL-CONTENT 标记块 资料来源：scripts/README.md:5-15。支持 intro / usage / configuration / outputs / notes 五种命名片段，合并时按标记名重新插入 资料来源：scripts/README.md:90-105。核心 Block 页面、原生触发器（start / schedule / webhook / rss / table）、服务账号页面是手写的，通过 HANDWRITTEN_INTEGRATION_DOCS / HANDWRITTEN_TRIGGER_DOCS / SKIP_TRIGGER_PROVIDERS 跳过 资料来源：scripts/README.md:70-90。

flowchart LR
    Block["blocks/blocks/*.ts"] --> Doc["integrations/*.mdx"]
    Tools["tools/<svc>/*.ts"] --> Doc
    Trig["triggers/<provider>/*"] --> Doc
    Icons["components/icons.tsx"] --> Doc
    Manual["MANUAL-CONTENT<br/>标记块"] --> Doc
    CI["GitHub CI<br/>(generate-docs)"] --> Doc

4. 工具调用、Guardrails 与测试支撑

平台对工具的"调用与校验"提供了多层护栏。apps/sim/lib/guardrails/ 内置了四类校验器：JSON、Regex、基于 RAG + LLM 评分的幻觉检测，以及通过 Microsoft Presidio 实现的PII 检测。PII 走的是单进程长连接 Sidecar 模式（docker/pii.Dockerfile，源码 apps/pii/server.py），同时暴露 /analyze / /anonymize / /health，并内置了校验位校验的 VIN 识别器与多语言 NLP 识别器 资料来源：apps/sim/lib/guardrails/README.md:1-45。

测试侧由 packages/testing 提供语义化的断言、流式 Builder 与 Mock 工厂：expectBlockExists / expectEdgeConnects / expectExecutionOrder 用来验证工作流结构；WorkflowBuilder.linear(3).build() 可一键生成线性工作流 资料来源：packages/testing/src/assertions/index.ts:1-30、资料来源：packages/testing/src/builders/index.ts:1-20。schema.mock.ts 暴露了 Drizzle 表的列名 Mock，覆盖 credential、copilotChats、usageLog 等关键实体，方便在不连库的情况下进行集成测试 资料来源：packages/testing/src/mocks/schema.mock.ts:1-30。

5. 社区关注与当前局限

社区中呼声最高的诉求之一是自定义 OpenAI 兼容端点（Issue #801）——目前被锁定在固定模型列表中，无法对接 llama-swap、llama-server、Ollama 的 OpenAI 兼容模式；Issue #1579 进一步要求支持 DeepInfra 等只改 URL/模型/Key 的服务。Issue #1637 与 #895 则反映自托管 / 本地 LLM（llama.cpp、LM Studio）以及 Docker Compose 完整部署文档的缺失。Issue #1553 提出希望平台原生支持创建与管理 MCP Server，将自定义 API 暴露为 MCP 端点供 Agent / Workflow 调用——这也与 v0.7.12 中"fix(mcp): missing isDeployed in contract"的修复方向一致，说明 MCP 协议集成正在持续演进 资料来源：README.md:1-30。

此外，packages/ts-sdk 为 Node ≥16 提供了对外发布的 TypeScript SDK（@sim/ts-sdk），是程序化触发工作流与集成能力的官方入口；packages/cli 与 packages/security 则为命令行运维与安全相关工具集，与 package.json 中通过 turbo 编排的 monorepo 一起支撑平台扩展 资料来源：packages/ts-sdk/package.json:1-30、资料来源：packages/cli/package.json:1-20、资料来源：package.json:1-30。

6. See Also

• Sim Studio 架构总览 — 平台整体设计
• Guardrails 校验器 — 工具调用的安全护栏
• 集成文档生成器 — generate-docs.ts 的详细说明
• PII Sidecar 部署 — Presidio 服务的容器化定义

实时协作与触发器 (Realtime Collaboration & Triggers)

1. 概述与定位

Sim Studio 的"实时协作 (Realtime Collaboration)"与"触发器 (Triggers)"是平台工作流引擎的两大核心交互机制。实时协作允许多个用户同时编辑同一份工作流画布；触发器则负责在工作流外部事件发生时启动一次执行（例如 webhook、定时计划、第三方服务的入站通知等）。

根据 scripts/README.md 中描述的本体论，一切皆为 block (everything is a block)，而一个集成 (integration) 是拥有"操作 (Actions)"和可选"触发器 (Trigger)"的 block。原生触发器类型包括 start（手动启动）、schedule（定时）、webhook（HTTP 回调）、rss（订阅源）以及 table（数据表）来源：[scripts/README.md]。同时，每个第三方集成（如 GitLab、PagerDuty、Zendesk 等）也可注册自己的 provider-specific 触发器 来源：[v0.7.11 Release Notes]。

2. 实时协作：基于 socket 的多人编辑

实时协作层通过基于 socket 的事件通道在客户端之间广播画布变更，确保多人同时编辑时的最终一致性和低延迟。社区版本历史中明确提到一次修复：fix(realtime): re-check workspace role on mutating socket events (#5080)，表明对画布产生副作用的 socket 事件会在服务端重新校验工作区角色 来源：[v0.7.9 Release Notes]。

权限语义与 permission.assertions 提供的测试断言一致——例如 expectSocketAccessGranted / expectSocketAccessDenied 直接针对 socket 事件路径 来源：[packages/testing/src/assertions/index.ts]。在测试辅助中，WorkflowBuilder 用来构造画布拓扑（blocks + edges），再通过 socket 事件驱动协作测试 来源：[packages/testing/src/builders/index.ts]。

测试入口 @sim/testing 把工厂、构造器、断言和 mock 统一暴露，便于编写实时协作与权限组合的端到端用例 来源：[packages/testing/src/index.ts]。

3. 触发器：定时、Webhook 与集成触发

触发器系统覆盖三类来源：

• 原生触发器：start、schedule、webhook、rss、table——它们是平台自带的、不依赖第三方服务的入口点 来源：[scripts/README.md]。
• 定时任务触发器：v0.7.8 将 jobs agent 迁移到 scheduled tasks agent；v0.7.6 引入了"暂停/恢复、变更提示、提交守卫、空状态"以及"分钟级粒度的日历与用户时区偏好" 来源：[v0.7.8 Release Notes，v0.7.6 Release Notes]。
• 集成触发器：v0.7.11 新增 GitLab、PagerDuty、Zendesk 的 webhook 触发器 来源：[v0.7.11 Release Notes]。

文档生成器在 generateAllTriggerDocs 阶段会扫描 apps/sim/triggers/<provider>/ 目录，为对应服务页面追加 ## Triggers 小节（若该服务仅有触发器，则写出独立页面）来源：[scripts/README.md]。

4. 架构关系与数据流

下图给出实时协作与触发器在一次工作流执行中的位置关系：

flowchart LR
  A[外部用户] -->|编辑画布| B[Realtime Socket 通道]
  B -->|变更事件| C[服务端权限校验]
  C -->|允许| D[工作流状态广播]
  D --> B
  T1[Webhook Trigger] --> E[工作流执行引擎]
  T2[Schedule Trigger] --> E
  T3[Integration Trigger] --> E
  E -->|执行结果| F[执行历史 / 审计]

其中：客户端变更经由 socket 通道 (B) 到达服务端 (C)，权限通过后 (C→D) 再回放到所有订阅者；触发器 (T1/T2/T3) 则绕过协作层，直接驱动工作流执行引擎 (E)，其执行结果会落库形成审计历史 (F)——这与社区提出的"签名审计轨迹 (Signed audit trail) RFC"直接相关 来源：[Issue #3975]。

5. 已知限制与社区反馈

• 自托管用户经常报告实时协作 / Copilot / 登录链路在 Docker Compose 部署下表现不稳定，README 中的常见问题章节也提示需要 12GB+ 内存 来源：[README.md，Issue #895]。
• PII 检测等守门人模块 (guardrails) 与触发器共享执行引擎，部署时需启动 Presidio 旁车并通过 PII_URL 注入 来源：[apps/sim/lib/guardrails/README.md]。
• 平台功能开关由 @aws-sdk/client-appconfig 支持的 AppConfig 后端在运行时统一管理，可用于按环境灰度触发器 来源：[package.json]。

另请参阅

• 架构总览 (Architecture Overview)
• 工作流执行引擎 (Workflow Execution Engine)
• 权限模型 (Permissions & RBAC)
• 触发器参考 (Triggers Reference)

1. 身份认证：Better Auth 与 SSO

Sim Studio 使用 Better Auth 作为统一的认证层，所有与认证相关的 HTTP 入口都通过一个 catch-all 路由暴露：

// apps/sim/app/api/auth/[...all]/route.ts
// 将所有 Better Auth 处理函数挂载到 /api/auth/*
export const { GET, POST } = toNextJsHandler(auth.handler)

这种 catch-all 模式意味着登录、注册、会话续期、密码重置、OAuth 回调、Magic Link 等端点全部由 Better Auth 的 handler 统一处理，开发者无需为每个流程手写路由 [file:apps/sim/app/api/auth/[...all]/route.ts]()。

在企业场景中，团队通常需要把身份源对接到公司 IdP（Okta、Azure AD、Google Workspace 等）。Sim 通过 apps/sim/app/api/auth/sso/providers/route.ts 提供 SSO provider 发现接口，前端可以在登录页面动态渲染可用的 SSO 选项，而不需要把 IdP 的元数据硬编码到客户端。该机制与 package.json:devDependencies 中的 better-auth 1.6.11 版本保持一致。

社区反馈：自托管用户在部署到 VPS 时常遇到登录流程异常（见 issue #895）。建议在自托管前先确认 BETTER_AUTH_SECRET 与 ENCRYPTION_KEY 已经按照 helm/sim/examples/values-production.yaml 的方式注入。

2. 组织与权限模型

Sim 的权限模型区分三种实体类型和三种角色，其核心定义位于测试工厂中（也是 schema 的真实反映）：

// packages/testing/src/factories/permission.factory.ts
export type PermissionType = 'admin' | 'write' | 'read'
export type EntityType = 'workspace' | 'workflow' | 'organization'

这意味着权限既可以挂在 Organization（跨 workspace 的公司层）上，也可以挂在 Workspace（团队/项目层）或单个 Workflow（资源层）上，满足从粗到细的访问控制需求 file:packages/testing/src/factories/permission.factory.ts。

API 层通过两条路由管理组织与权限：

permission-groups 的存在让管理员可以预先定义"安全审计组""开发组"等模板，再把成员批量加入，而不需要逐个赋权，这与企业 IT 的常见工作流匹配。

3. 审计日志与执行追溯

Sim 提供两套审计日志 API：

• 内部 API：apps/sim/app/api/audit-logs/route.ts —— 用于平台自身的 UI（如"活动日志"页）。
• 公开 v1 API：apps/sim/app/api/v1/audit-logs/route.ts —— 用于第三方集成与合规导出，遵循 v1 契约。

两套接口共用相同的底层数据模型（参见 packages/testing/src/mocks/schema.mock.ts 中的表结构），但鉴权与分页策略不同：内部 API 基于会话 Cookie，公开 API 基于 API Key 与签名校验。

社区请求：issue #3975 提出"Signed audit trail for Sim workflow executions"，希望在每条执行记录上加上密码学签名，以满足金融/医疗等行业的不可篡改要求。当前的实现已记录完整执行轨迹，但签名链尚未内置；接入方可通过 v1/audit-logs 自行落地签名校验。

4. 数据治理：PII、保留策略与凭据保护

数据治理是 Sim 在 v0.7 系列中投入最大的方向之一，主要由下列机制组成：

1. PII 检测与脱敏：通过 Presidio sidecar 提供服务，镜像构建自 docker/pii.Dockerfile（apps/sim/lib/guardrails/README.md）。Guardrails block 中的"PII Detection"操作把数据发送给 sidecar，由其返回脱敏结果。v0.7.13 已将镜像发布到 GHCR 并加入 Helm chart（见 release notes #5188）。

1. 数据保留（Data Retention）：v0.7.13 引入 workspace 级覆盖项（#5186），允许管理员在 workspace 设置中自定义保留周期与是否启用 PII 再处理。v0.7.11 起该能力以 feature flag 形式逐步开放（#5144）。

1. 凭据加密：所有接入第三方服务的凭据都通过 ENCRYPTION_KEY 加密后落库，密钥在 helm chart 中通过 secret 引用注入（见 helm/sim/README.md 中的 values-existing-secret.yaml 与 values-external-secrets.yaml 示例）。

flowchart LR
    User[用户/服务账号] -->|SSO/OAuth| Auth[Better Auth]
    Auth --> Session[会话与权限]
    Session --> OrgAPI[Organizations API]
    OrgAPI --> PermGroup[Permission Groups]
    PermGroup --> Workspace[Workspace / Workflow]
    Workspace --> Execution[Workflow 执行]
    Execution --> Audit[Audit Logs v1]
    Execution --> PII[Presidio Sidecar]
    PII -->|脱敏后落库| Store[(Postgres)]
    Audit --> Store

部署提示：在生产环境，请优先使用 values-external-db.yaml 与 values-external-secrets.yaml，让 Postgres 与密钥都由云厂商托管，避免在容器内长期持有明文密钥（helm/sim/README.md）。

常见失败模式

• 登录循环：通常是 BETTER_AUTH_SECRET 在多副本间不一致，导致会话签名校验失败（issue #895 的根因之一）。
• 权限升级失败：permissionType 字段只接受 admin | write | read，传 "owner" 等历史值会被 schema 拒绝（packages/testing/src/factories/permission.factory.ts）。
• PII 检测超时：默认 sidecar URL 为 http://localhost:5001，在 K8s 中需通过 PII_URL 环境变量指向 service 名（apps/sim/lib/guardrails/README.md）。

See Also

• 自托管与 Helm 部署：helm/sim/README.md
• Guardrails 与 PII：apps/sim/lib/guardrails/README.md
• 测试与权限工厂：packages/testing/src/factories/permission.factory.ts
• 集成页生成器：scripts/README.md

1. 仓库形态与部署入口

Sim 是一份基于 Bun + Turborepo 的多包 monorepo，根目录通过 package.json 把工作流串起来并启用 lint-staged（package.json:1-50）。scripts/README.md 中描述了 scripts/generate-docs.ts 的作用：把 apps/sim/blocks/blocks/*.ts、apps/sim/tools/*、apps/sim/triggers/* 编译成 apps/docs/content/docs/en/integrations/ 下的派生 MDX（scripts/README.md:1-60）。这意味着自托管时如果修改了任何 block/tool/trigger 元数据，需要在 CI 或本地重新跑文档生成器。

主仓库入口仍是 Docker Compose。README.md 给出了标准流程：

git clone https://github.com/simstudioai/sim.git
cd sim
docker compose -f docker-compose.prod.yml up -d
docker compose -f docker-compose.prod.yml ps

应用默认监听 http://localhost:3000。文档同时指出：

• 关键端口：3000（应用）、3002、5432（数据库）（README.md:1-40）。
• 最低资源：≥ 12GB RAM（README.md:1-40）。
• 带本地模型的可选 profile：docker-compose.ollama.yml --profile setup（README.md:1-40）。
• 常见排错：端口被占用、Docker 未启动、内存不足。

社区反馈 #895 指出，目前自托管到 VPS 后 Copilot、AI Agent、Ollama、登录流经常出现"启动成功但功能异常"的情况，需要补充更完整的 Docker Compose 教程；#1637 与 #1579 进一步要求支持 llama.cpp / LM Studio / DeepInfra 等 OpenAI 兼容端点。docker-compose.ollama.yml 是当前官方提供的本地模型接入路径。

2. 应用配置与 PII Sidecar

Sim 的运行时分两层：apps/sim 是 Next.js 应用，apps/pii 是独立 Python 服务。apps/sim/lib/guardrails/README.md 明确指出，Guardrails 块中的 PII Detection 走的是 Presidio sidecar，而 JSON / Regex / Hallucination 校验则是 TypeScript 内置：

PII 服务的标准启动方式（apps/sim/lib/guardrails/README.md:1-40）：

docker build -f docker/pii.Dockerfile -t sim-pii .
docker run -d -p 5001:5001 sim-pii

应用通过 PII_URL 指向该 sidecar（默认 http://localhost:5001）。v0.7.13 的发布说明进一步说明：PII 镜像已发布到 GHCR，并在 Helm chart 中加入 Presidio sidecar，同时支持 workspace 级别的留存与 PII 覆盖（v0.7.13 release notes）。这意味着在生产环境（例如 Kubernetes）里，PII 与主应用应当作为同一 Pod/Task 的两个容器编排，共享网络命名空间。apps/sim/package.json:1-80 列出了完整的依赖集合（@aws-sdk/*、@anthropic-ai/sdk、drizzle-orm、@trigger.dev/sdk 等），可用于确认运行时能力边界。

3. 数据迁移与定时任务

数据层使用 Postgres + Drizzle ORM，封装在 packages/db 中（packages/db/package.json:1-40），对外暴露 ./schema 与 drizzle-orm、postgres、zod 等关键依赖。packages/db/package.json 提供的脚本包括：

• db:push：drizzle-kit 直推 schema；
• db:migrate：在 Bun 环境下执行 scripts/migrate.ts；
• db:studio：drizzle 可视化。

v0.7.3 引入"在 GitHub CI 中按环境作用域执行 DB 迁移"的能力（v0.7.3 release notes），运维应把生产环境 migrations 走 CI 而非本地直连，避免漂移。v0.7.6 加入了定时任务（Sceduled Tasks）的暂停/恢复与提交守卫（v0.7.6 release notes），v0.7.8 把 jobs agent 迁移到 scheduled-tasks agent（v0.7.8 release notes）。此外 v0.7.6 还将"程序化触发工作流"纳入付费计划（v0.7.6 release notes），自托管用户在计费关闭时仍可走本地 API。

4. 审计、安全与运维生态

仓库已抽出一组以 @sim/* 为前缀的内部包，覆盖了运维所需的基础设施（package.json:1-50）：

packages/audit/package.json:1-30 显示审计包完全基于 @sim/db 与 @sim/utils，这与社区 RFC #3975 "为工作流执行记录增加签名审计追踪"的方向一致，企业自托管方可以在此之上做链式签名与外部存证。v0.7.8 还把 3 个 env 行为开关迁到 AppConfig 化的运行时 Feature Flag（v0.7.8 release notes），意味着开关调整不再需要重启容器。

v0.7.13 进一步统一了升级路由与存储/Tables 限额（v0.7.13 release notes），并引入"工作区级别留存与 PII 覆盖"（v0.7.13 release notes），这与 PII sidecar 一起构成数据合规的最小闭环。

故障与限制

基于社区证据与源码边界，运维需关注：

• OpenAI 兼容端点：默认仅暴露特定 provider，自托管到本地 LLM 时需通过 docker-compose.ollama.yml 走 Ollama profile，或使用 OpenAI 兼容模式（#801、#1637、#1579）。
• 资源占用：12GB+ RAM 是起步要求，Ollama profile 在小内存 VPS 上 OOM 是已知现象（#1637）。
• MCP 服务：自托管方希望平台内置 MCP server 创建能力，目前仍以请求为主（#1553）。
• 审计完整性：当前执行历史无密码学保证，企业部署需要外部加固（#3975）。

See Also

• Guardrails Validators — apps/sim/lib/guardrails/README.md
• Integration Documentation Generator — scripts/README.md
• Database Schema & Migrations — packages/db
• Audit & Signed Trail (RFC) — simstudioai/sim#3975

Pitfall Log / 踩坑日志

项目：simstudioai/sim

摘要：发现 20 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 失败模式：installation: RFC: Signed audit trail for Sim workflow executions。

1. 安装坑 · 失败模式：installation: RFC: Signed audit trail for Sim workflow executions

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: RFC: Signed audit trail for Sim workflow executions
• 对用户的影响：Developers may fail before the first successful local run: RFC: Signed audit trail for Sim workflow executions
• 证据：failure_mode_cluster:github_issue | https://github.com/simstudioai/sim/issues/3975 | RFC: Signed audit trail for Sim workflow executions

2. 安装坑 · 来源证据：RFC: Signed audit trail for Sim workflow executions

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：RFC: Signed audit trail for Sim workflow executions
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/simstudioai/sim/issues/3975 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

3. 安装坑 · 来源证据：[REQUEST] Optional: add an HVTracker trust badge to the README

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[REQUEST] Optional: add an HVTracker trust badge to the README
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/simstudioai/sim/issues/5198 | 来源类型 github_issue 暴露的待验证使用条件。

4. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/simstudioai/sim | host_targets=cursor

5. 配置坑 · 失败模式：configuration: v0.7.10

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v0.7.10
• 对用户的影响：Upgrade or migration may change expected behavior: v0.7.10
• 证据：failure_mode_cluster:github_release | https://github.com/simstudioai/sim/releases/tag/v0.7.10 | v0.7.10

6. 配置坑 · 失败模式：configuration: v0.7.11

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v0.7.11
• 对用户的影响：Upgrade or migration may change expected behavior: v0.7.11
• 证据：failure_mode_cluster:github_release | https://github.com/simstudioai/sim/releases/tag/v0.7.11 | v0.7.11

7. 配置坑 · 失败模式：configuration: v0.7.3

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v0.7.3
• 对用户的影响：Upgrade or migration may change expected behavior: v0.7.3
• 证据：failure_mode_cluster:github_release | https://github.com/simstudioai/sim/releases/tag/v0.7.3 | v0.7.3

8. 配置坑 · 失败模式：configuration: v0.7.4

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v0.7.4
• 对用户的影响：Upgrade or migration may change expected behavior: v0.7.4
• 证据：failure_mode_cluster:github_release | https://github.com/simstudioai/sim/releases/tag/v0.7.4 | v0.7.4

9. 配置坑 · 失败模式：configuration: v0.7.5

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v0.7.5
• 对用户的影响：Upgrade or migration may change expected behavior: v0.7.5
• 证据：failure_mode_cluster:github_release | https://github.com/simstudioai/sim/releases/tag/v0.7.5 | v0.7.5

10. 配置坑 · 失败模式：configuration: v0.7.7

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v0.7.7
• 对用户的影响：Upgrade or migration may change expected behavior: v0.7.7
• 证据：failure_mode_cluster:github_release | https://github.com/simstudioai/sim/releases/tag/v0.7.7 | v0.7.7

11. 配置坑 · 失败模式：configuration: v0.7.8

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v0.7.8
• 对用户的影响：Upgrade or migration may change expected behavior: v0.7.8
• 证据：failure_mode_cluster:github_release | https://github.com/simstudioai/sim/releases/tag/v0.7.8 | v0.7.8

12. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/simstudioai/sim | README/documentation is current enough for a first validation pass.

13. 运行坑 · 失败模式：runtime: v0.7.9

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: v0.7.9
• 对用户的影响：Upgrade or migration may change expected behavior: v0.7.9
• 证据：failure_mode_cluster:github_release | https://github.com/simstudioai/sim/releases/tag/v0.7.9 | v0.7.9

14. 维护坑 · 失败模式：migration: v0.7.12

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: v0.7.12
• 对用户的影响：Upgrade or migration may change expected behavior: v0.7.12
• 证据：failure_mode_cluster:github_release | https://github.com/simstudioai/sim/releases/tag/v0.7.12 | v0.7.12

15. 维护坑 · 失败模式：migration: v0.7.6

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: v0.7.6
• 对用户的影响：Upgrade or migration may change expected behavior: v0.7.6
• 证据：failure_mode_cluster:github_release | https://github.com/simstudioai/sim/releases/tag/v0.7.6 | v0.7.6

16. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/simstudioai/sim | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/simstudioai/sim | no_demo; severity=medium

18. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/simstudioai/sim | no_demo; severity=medium

19. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/simstudioai/sim | issue_or_pr_quality=unknown

20. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/simstudioai/sim | release_recency=unknown