{ "canonical_name": "simstudioai/sim", "compilation_id": "pack_d34af9edaea84accaea8e953329629e9", "created_at": "2026-05-11T19:32:05.207626+00:00", "created_by": "project-pack-compiler", "feedback": { "carrier_selection_notes": [ "viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight", "recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight" ], "evidence_delta": { "confirmed_claims": [ "identity_anchor_present", "capability_and_host_targets_present", "install_path_declared_or_better" ], "missing_required_fields": [], "must_verify_forwarded": [ "Run or inspect `npx simstudio` in an isolated environment.", "Confirm the project exposes the claimed capability to at least one target host." ], "quickstart_execution_scope": "allowlisted_sandbox_smoke", "sandbox_command": "npx simstudio", "sandbox_container_image": "node:22-slim", "sandbox_execution_backend": "docker", "sandbox_planner_decision": "deterministic_isolated_install", "sandbox_validation_id": "sbx_76146d00441145cf9d86c788d213ebd7" }, "feedback_event_type": "project_pack_compilation_feedback", "learning_candidate_reasons": [], "template_gaps": [] }, "identity": { "canonical_id": "project_836115f0eb2ccacd7a3846d42f15427b", "canonical_name": "simstudioai/sim", "homepage_url": null, "license": "unknown", "repo_url": "https://github.com/simstudioai/sim", "slug": "sim", "source_packet_id": "phit_89db729c17574a4ba5b4aedb0c2564e1", "source_validation_id": "dval_e4a6850475664ddc95ab003825de16a5" }, "merchandising": { "best_for": "需要软件开发与交付能力，并使用 cursor的用户", "github_forks": 3592, "github_stars": 28484, "one_liner_en": "

", "one_liner_zh": "

", "primary_category": { "category_id": "software-development", "confidence": "medium", "name_en": "Software Development", "name_zh": "软件开发与交付", "reason": "matched_keywords:git" }, "target_user": "使用 cursor 等宿主 AI 的用户", "title_en": "sim", "title_zh": "sim 能力包", "visible_tags": [ { "label_en": "MCP Tools", "label_zh": "MCP 工具", "source": "repo_evidence_project_characteristics", "tag_id": "product_domain-mcp-tools", "type": "product_domain" }, { "label_en": "Knowledge Base Q&A", "label_zh": "知识库问答", "source": "repo_evidence_project_characteristics", "tag_id": "user_job-knowledge-base-q-a", "type": "user_job" }, { "label_en": "Workflow Automation", "label_zh": "流程自动化", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-workflow-automation", "type": "core_capability" }, { "label_en": "Node-based Workflow", "label_zh": "节点式流程编排", "source": "repo_evidence_project_characteristics", "tag_id": "workflow_pattern-node-based-workflow", "type": "workflow_pattern" }, { "label_en": "Local-first", "label_zh": "本地优先", "source": "repo_evidence_project_characteristics", "tag_id": "selection_signal-local-first", "type": "selection_signal" } ] }, "packet_id": "phit_89db729c17574a4ba5b4aedb0c2564e1", "page_model": { "artifacts": { "artifact_slug": "sim", "files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json", "REPO_INSPECTION.md", "CAPABILITY_CONTRACT.json", "EVIDENCE_INDEX.json", "CLAIM_GRAPH.json" ], "required_files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json" ] }, "detail": { "capability_source": "Project Hit Packet + DownstreamValidationResult", "commands": [ { "command": "npx simstudio", "label": "Node.js / npx · 官方安装入口", "source": "https://github.com/simstudioai/sim#readme", "verified": true } ], "display_tags": [ "MCP 工具", "知识库问答", "流程自动化", "节点式流程编排", "本地优先" ], "eyebrow": "软件开发与交付", "glance": [ { "body": "判断自己是不是目标用户。", "label": "最适合谁", "value": "需要软件开发与交付能力，并使用 cursor的用户" }, { "body": "先理解能力边界，再决定是否继续。", "label": "核心价值", "value": "

" }, { "body": "未完成验证前保持审慎。", "label": "继续前", "value": "publish to Doramagic.ai project surfaces" } ], "guardrail_source": "Boundary & Risk Card", "guardrails": [ { "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。", "label": "Check 1", "value": "不要把试用当真实运行" }, { "body": "cursor", "label": "Check 2", "value": "确认宿主兼容" }, { "body": "publish to Doramagic.ai project surfaces", "label": "Check 3", "value": "先隔离验证" } ], "mode": "mcp_config, recipe, host_instruction, eval, preflight", "pitfall_log": { "items": [ { "body": "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.", "category": "安装坑", "evidence": [ "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" ], "severity": "medium", "suggested_check": "Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。", "title": "社区讨论暴露的待验证问题：Open-source general purpose agent with built-in MCPToolkit support", "user_impact": "这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。" }, { "body": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。", "category": "配置坑", "evidence": [ "capability.host_targets | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | host_targets=cursor" ], "severity": "medium", "suggested_check": "列出会写入的配置文件、目录和卸载/回滚步骤。", "title": "可能修改宿主 AI 配置", "user_impact": "安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。" }, { "body": "README/documentation is current enough for a first validation pass.", "category": "能力坑", "evidence": [ "capability.assumptions | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | README/documentation is current enough for a first validation pass." ], "severity": "medium", "suggested_check": "将假设转成下游验证清单。", "title": "能力判断依赖假设", "user_impact": "假设不成立时，用户拿不到承诺的能力。" }, { "body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.6.63", "category": "运行坑", "evidence": [ "community_evidence:github | cevd_5a97e1d742fe4d7f918e0b42f27b87c3 | https://github.com/simstudioai/sim/releases/tag/v0.6.63 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v0.6.63", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.6.65", "category": "运行坑", "evidence": [ "community_evidence:github | cevd_03f18559029c4724b11011ef96259161 | https://github.com/simstudioai/sim/releases/tag/v0.6.65 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v0.6.65", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.6.67", "category": "运行坑", "evidence": [ "community_evidence:github | cevd_048d1506c1d645b0be435841a26b93ed | https://github.com/simstudioai/sim/releases/tag/v0.6.67 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v0.6.67", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.6.73", "category": "运行坑", "evidence": [ "community_evidence:github | cevd_048864e1cdcc44d2b2a30917b7c4adc2 | https://github.com/simstudioai/sim/releases/tag/v0.6.73 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v0.6.73", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v0.6.71", "category": "维护坑", "evidence": [ "community_evidence:github | cevd_9c30d794fb7344489f96a6ac47cd1d6e | https://github.com/simstudioai/sim/releases/tag/v0.6.71 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v0.6.71", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "未记录 last_activity_observed。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | last_activity_observed missing" ], "severity": "medium", "suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。", "title": "维护活跃度未知", "user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "downstream_validation.risk_items | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "进入安全/权限治理复核队列。", "title": "下游验证发现风险项", "user_impact": "下游已经要求复核，不能在页面中弱化。" }, { "body": "No sandbox install has been executed yet; downstream must verify before user use.", "category": "安全/权限坑", "evidence": [ "risks.safety_notes | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | No sandbox install has been executed yet; downstream must verify before user use." ], "severity": "medium", "suggested_check": "转成明确权限清单和安全审查提示。", "title": "存在安全注意事项", "user_impact": "用户安装前需要知道权限边界和敏感操作。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "risks.scoring_risks | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。", "title": "存在评分风险", "user_impact": "风险会影响是否适合普通用户安装。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Unable to Access Files from Private GitHub Repository in Self-Hosted Setup", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_ed1c9f64533441f5826c1fe98fa9ce49 | https://github.com/simstudioai/sim/issues/4555 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Unable to Access Files from Private GitHub Repository in Self-Hosted Setup", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.6.64", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_5e2aa5311b1748cea446771920242668 | https://github.com/simstudioai/sim/releases/tag/v0.6.64 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v0.6.64", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.6.66", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_7d42c79fecf54003b117f76d49873223 | https://github.com/simstudioai/sim/releases/tag/v0.6.66 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v0.6.66", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.6.68", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_c8fe17ce7ba6424c88017ed644620915 | https://github.com/simstudioai/sim/releases/tag/v0.6.68 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v0.6.68", "user_impact": "可能阻塞安装或首次运行。" } ], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "发现 20 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 社区讨论暴露的待验证问题：Open-source general purpose agent with built-in MCPToolkit support。", "title": "踩坑日志" }, "snapshot": { "contributors": null, "forks": 3592, "license": "unknown", "note": "GitHub API 快照，非实时质量证明；用于开工前背景判断。", "stars": 28484, "open_issues": 205, "pushed_at": "2026-05-13T06:30:48.000Z" }, "source_url": "https://github.com/simstudioai/sim", "steps": [ { "body": "不安装项目，先体验能力节奏。", "code": "preview", "title": "先试 Prompt" }, { "body": "理解输入、输出、失败模式和边界。", "code": "manual", "title": "读说明书" }, { "body": "把上下文交给宿主 AI 继续工作。", "code": "context", "title": "带给 AI" }, { "body": "进入主力环境前先完成安装入口与风险边界验证。", "code": "verify", "title": "沙箱验证" } ], "subtitle": "

", "title": "sim 能力包", "trial_prompt": "# sim - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 sim 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Cursor\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-project-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-system-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. page-workflow-execution：工作流执行引擎。围绕“工作流执行引擎”模拟一次用户任务，不展示安装或运行结果。\n4. page-block-registry：块系统与注册表。围绕“块系统与注册表”模拟一次用户任务，不展示安装或运行结果。\n5. page-agent-integration：代理与AI集成。围绕“代理与AI集成”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-project-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-system-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-workflow-execution\n输入：用户提供的“工作流执行引擎”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-block-registry\n输入：用户提供的“块系统与注册表”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-agent-integration\n输入：用户提供的“代理与AI集成”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-project-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-system-architecture：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-workflow-execution：Step 3 必须围绕“工作流执行引擎”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-block-registry：Step 4 必须围绕“块系统与注册表”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-agent-integration：Step 5 必须围绕“代理与AI集成”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/simstudioai/sim#readme\n- .agents/skills/add-block/SKILL.md\n- .agents/skills/add-connector/SKILL.md\n- .agents/skills/add-integration/SKILL.md\n- .agents/skills/add-tools/SKILL.md\n- .agents/skills/add-trigger/SKILL.md\n- .agents/skills/cleanup/SKILL.md\n- .agents/skills/emcn-design-review/SKILL.md\n- .agents/skills/react-query-best-practices/SKILL.md\n- .agents/skills/ship/SKILL.md\n- .agents/skills/validate-connector/SKILL.md\n- .agents/skills/validate-integration/SKILL.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 sim 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n", "voices": [ { "body": "来源平台：github, reddit。github/github_issue: Unable to Access Files from Private GitHub Repository in Self-Hosted Set（https://github.com/simstudioai/sim/issues/4555）；github/github_release: v0.6.73（https://github.com/simstudioai/sim/releases/tag/v0.6.73）；github/github_release: v0.6.72（https://github.com/simstudioai/sim/releases/tag/v0.6.72）；github/github_release: v0.6.71（https://github.com/simstudioai/sim/releases/tag/v0.6.71）；github/github_release: v0.6.69（https://github.com/simstudioai/sim/releases/tag/v0.6.69）；github/github_release: v0.6.68（https://github.com/simstudioai/sim/releases/tag/v0.6.68）；github/github_release: v0.6.67（https://github.com/simstudioai/sim/releases/tag/v0.6.67）；github/github_release: v0.6.66（https://github.com/simstudioai/sim/releases/tag/v0.6.66）；github/github_release: v0.6.65（https://github.com/simstudioai/sim/releases/tag/v0.6.65）；github/github_release: v0.6.64（https://github.com/simstudioai/sim/releases/tag/v0.6.64）；github/github_release: v0.6.63（https://github.com/simstudioai/sim/releases/tag/v0.6.63）；reddit: I want to built a simple agent with some memory and basic skills ...（https://www.reddit.com/r/LocalLLaMA/comments/1s95mdj/i_want_to_built_a_simple_agent_with_some_memory/）。这些是项目级外部声音，不作为单独质量证明。", "items": [ { "kind": "github_issue", "source": "github", "title": "Unable to Access Files from Private GitHub Repository in Self-Hosted Set", "url": "https://github.com/simstudioai/sim/issues/4555" }, { "kind": "github_release", "source": "github", "title": "v0.6.73", "url": "https://github.com/simstudioai/sim/releases/tag/v0.6.73" }, { "kind": "github_release", "source": "github", "title": "v0.6.72", "url": "https://github.com/simstudioai/sim/releases/tag/v0.6.72" }, { "kind": "github_release", "source": "github", "title": "v0.6.71", "url": "https://github.com/simstudioai/sim/releases/tag/v0.6.71" }, { "kind": "github_release", "source": "github", "title": "v0.6.69", "url": "https://github.com/simstudioai/sim/releases/tag/v0.6.69" }, { "kind": "github_release", "source": "github", "title": "v0.6.68", "url": "https://github.com/simstudioai/sim/releases/tag/v0.6.68" }, { "kind": "github_release", "source": "github", "title": "v0.6.67", "url": "https://github.com/simstudioai/sim/releases/tag/v0.6.67" }, { "kind": "github_release", "source": "github", "title": "v0.6.66", "url": "https://github.com/simstudioai/sim/releases/tag/v0.6.66" }, { "kind": "github_release", "source": "github", "title": "v0.6.65", "url": "https://github.com/simstudioai/sim/releases/tag/v0.6.65" }, { "kind": "github_release", "source": "github", "title": "v0.6.64", "url": "https://github.com/simstudioai/sim/releases/tag/v0.6.64" }, { "kind": "github_release", "source": "github", "title": "v0.6.63", "url": "https://github.com/simstudioai/sim/releases/tag/v0.6.63" }, { "kind": "searxng_indexed", "source": "reddit", "title": "I want to built a simple agent with some memory and basic skills ...", "url": "https://www.reddit.com/r/LocalLLaMA/comments/1s95mdj/i_want_to_built_a_simple_agent_with_some_memory/" } ], "status": "已收录 15 条来源", "title": "社区讨论" } ] }, "homepage_card": { "category": "软件开发与交付", "desc": "

", "effort": "安装已验证", "forks": null, "icon": "code", "name": "sim 能力包", "risk": "可发布", "slug": "sim", "stars": null, "tags": [ "MCP 工具", "知识库问答", "流程自动化", "节点式流程编排", "本地优先" ], "thumb": "gray", "type": "MCP 配置" }, "manual": { "markdown": "# https://github.com/simstudioai/sim 项目说明书\n\n生成时间：2026-05-11 19:14:22 UTC\n\n## 目录\n\n- [项目概述](#page-project-overview)\n- [系统架构](#page-system-architecture)\n- [工作流执行引擎](#page-workflow-execution)\n- [块系统与注册表](#page-block-registry)\n- [代理与AI集成](#page-agent-integration)\n- [工作流编辑器](#page-workflow-editor)\n- [实时协作与UI组件](#page-realtime-ui)\n- [连接器框架](#page-connectors)\n- [部署与基础设施](#page-deployment)\n- [扩展与定制](#page-extensibility)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[系统架构](#page-system-architecture), [部署与基础设施](#page-deployment)\n\n

\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/simstudioai/sim/blob/main/README.md)\n- [apps/sim/package.json](https://github.com/simstudioai/sim/blob/main/apps/sim/package.json)\n- [scripts/README.md](https://github.com/simstudioai/sim/blob/main/scripts/README.md)\n- [packages/ts-sdk/README.md](https://github.com/simstudioai/sim/blob/main/packages/ts-sdk/README.md)\n- [packages/python-sdk/README.md](https://github.com/simstudioai/sim/blob/main/packages/python-sdk/README.md)\n- [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)\n- [apps/sim/lib/webhooks/pending-verification.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/pending-verification.ts)\n- [packages/testing/src/mocks/env.mock.ts](https://github.com/simstudioai/sim/blob/main/packages/testing/src/mocks/env.mock.ts)\n
\n\n# 项目概述\n\n## 1. 项目简介\n\nSim 是一个可视化的工作流自动化平台，旨在帮助用户通过直观的拖拽式界面构建、部署和执行复杂的自动化流程。该项目由 SimStudio 团队开发，支持本地部署和云端托管两种模式，并提供了 TypeScript 和 Python 两种 SDK 供开发者集成。\n\nSim 的核心功能包括：\n\n- **可视化工作流编辑器**：通过图形化界面设计自动化流程\n- **多平台 Webhook 集成**：支持 Webflow、Gong、Typeform、Vercel 等多种第三方服务\n- **实时执行引擎**：支持同步和异步两种执行模式\n- **沙箱执行环境**：安全地运行用户代码和自定义逻辑\n- **AI Copilot**：集成 AI 能力辅助工作流构建\n- **PPTX 渲染引擎**：支持 PowerPoint 文件的解析和展示\n\n## 2. 技术架构\n\n### 2.1 技术栈概览\n\n| 类别 | 技术选型 |\n|------|----------|\n| 前端框架 | Next.js |\n| 包管理器 | Bun |\n| 运行时 | Node.js v20+ |\n| 数据库 | PostgreSQL 12+ with pgvector |\n| 容器化 | Docker, Docker Compose |\n| 开发语言 | TypeScript |\n| SDK | TypeScript, Python |\n\n资料来源：[README.md:1-20](https://github.com/simstudioai/sim/blob/main/README.md)\n\n### 2.2 应用架构\n\nSim 项目采用 monorepo 结构，主要包含以下应用模块：\n\n```\nsim/\n├── apps/\n│ ├── sim/ # 主应用程序（Next.js）\n│ └── realtime/ # 实时执行服务\n├── packages/\n│ ├── ts-sdk/ # TypeScript SDK\n│ ├── python-sdk/ # Python SDK\n│ └── testing/ # 测试工具库\n└── scripts/ # 构建和文档生成脚本\n```\n\n资料来源：[apps/sim/package.json:1-15](https://github.com/simstudioai/sim/blob/main/apps/sim/package.json)\n\n### 2.3 核心模块架构图\n\n```mermaid\ngraph TD\n subgraph \"前端层\"\n A[Web UI] --> B[Workflow Editor]\n A --> C[Block Configuration]\n A --> D[Execution Dashboard]\n end\n \n subgraph \"核心服务层\"\n E[Workflow Engine] --> F[Block Registry]\n E --> G[Trigger System]\n E --> H[Execution Engine]\n end\n \n subgraph \"集成层\"\n I[Webhook Providers] --> J[Event Filter]\n I --> K[Verification Service]\n L[Tool Adapters] --> H\n end\n \n subgraph \"数据层\"\n M[(PostgreSQL + pgvector)]\n N[Redis Cache]\n end\n \n subgraph \"SDK 层\"\n O[TypeScript SDK]\n P[Python SDK]\n end\n \n H --> M\n H --> N\n O --> E\n P --> E\n```\n\n## 3. 核心功能模块\n\n### 3.1 工作流引擎\n\n工作流引擎是 Sim 平台的核心组件，负责解析、验证和执行用户定义的工作流。\n\n#### 3.1.1 工作流组件\n\n| 组件 | 功能描述 |\n|------|----------|\n| Block | 工作流中的基本执行单元 |\n| Loop Block | 循环控制块，支持 for 循环 |\n| Parallel Block | 并行执行块 |\n| Trigger | 触发器，定义工作流启动条件 |\n| Subflow | 子流程，嵌套的工作流片段 |\n\n资料来源：[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)\n\n#### 3.1.2 执行模式\n\nSim 支持两种执行模式：\n\n- **同步执行**：等待工作流完成并返回结果\n- **异步执行**：将任务加入队列，立即返回任务 ID\n\n```typescript\ninterface ExecutionOptions {\n timeout?: number;\n stream?: boolean;\n selectedOutputs?: string[];\n async?: boolean;\n}\n```\n\n资料来源：[packages/ts-sdk/README.md:1-50](https://github.com/simstudioai/sim/blob/main/packages/ts-sdk/README.md)\n\n### 3.2 Webhook 系统\n\nSim 提供了强大的 Webhook 集成能力，支持多种第三方服务。\n\n#### 3.2.1 支持的 Webhook 提供商\n\n| 提供商 | 验证方式 | 特殊配置 |\n|--------|----------|----------|\n| Ashby | 自定义 | `action === 'ping'` |\n| Grain | 自定义 | GET/HEAD 请求自动验证 |\n| Generic | 自定义 | 支持 `verifyTestEvents` 元数据 |\n| Salesforce | 自定义 | 多种请求类型 |\n| Webflow | - | 支持 `collectionId` 过滤 |\n| Gong | - | 通话元数据解析 |\n| Typeform | HMAC | 支持 `includeDefinition` |\n| Vercel | - | 部署和项目信息 |\n\n资料来源：[apps/sim/lib/webhooks/pending-verification.ts:1-30](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/pending-verification.ts)\n\n#### 3.2.2 Webhook 事件过滤机制\n\n```typescript\ninterface EventFilterContext {\n webhook: Webhook;\n body: Record;\n requestId: string;\n providerConfig: Record;\n}\n```\n\nWebflow 提供商实现了集合 ID 过滤功能，只有匹配配置中指定 `collectionId` 的事件才会被处理：\n\n```typescript\nshouldSkipEvent({ webhook, body, requestId, providerConfig }: EventFilterContext) {\n const configuredCollectionId = providerConfig.collectionId as string | undefined\n // ... 过滤逻辑\n}\n```\n\n资料来源：[apps/sim/lib/webhooks/providers/webflow.ts:1-60](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/providers/webflow.ts)\n\n### 3.3 块系统与文档生成\n\nSim 使用块（Block）作为构建工作流的基本单元。每个块包含元数据、输入输出规范和配置参数。\n\n#### 3.3.1 文档生成器\n\n`scripts/generate-docs.ts` 脚本自动扫描 `apps/sim/blocks/blocks/` 目录，提取所有块定义文件的元数据并生成标准化 Markdown 文档。\n\n工作流程：\n\n1. 扫描块定义文件目录\n2. 提取块元数据（名称、描述、分类）\n3. 提取输入输出规范\n4. 提取配置参数\n5. 生成 Markdown 文档\n6. 更新 `meta.json` 导航元数据\n\n资料来源：[scripts/README.md:1-40](https://github.com/simstudioai/sim/blob/main/scripts/README.md)\n\n#### 3.3.2 块类型定义\n\n```typescript\ninterface ToolBlockRecord {\n type: string;\n title?: string;\n toolId?: string;\n operation?: string;\n params?: Record;\n customToolId?: string;\n code?: string;\n usageControl?: 'auto' | 'force' | 'none';\n isExpanded?: boolean;\n schema?: StoredToolSchema;\n}\n```\n\n资料来源：[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)\n\n### 3.4 实时执行服务\n\n实时执行服务（Realtime Service）负责处理工作流的运行时操作，包括状态管理和数据持久化。\n\n#### 3.4.1 数据库操作\n\n```mermaid\ngraph LR\n A[Workflow Update] --> B[Validate Blocks]\n B --> C[Upsert Workflow Blocks]\n C --> D{Block Type}\n D -->|Loop| E[Create Subflow Entry]\n D -->|Parallel| F[Create Subflow Entry]\n E --> G[Commit Transaction]\n F --> G\n```\n\n工作流更新操作使用 PostgreSQL 的 `ON CONFLICT DO UPDATE` 语法进行原子性更新：\n\n```typescript\nawait tx\n .insert(workflowBlocks)\n .values(blockValues)\n .onConflictDoUpdate({\n target: workflowBlocks.id,\n set: {\n type: sql`excluded.type`,\n name: sql`excluded.name`,\n // ... 其他字段\n updatedAt: sql`now()`,\n },\n })\n```\n\n资料来源：[apps/realtime/src/database/operations.ts:1-60](https://github.com/simstudioai/sim/blob/main/apps/realtime/src/database/operations.ts)\n\n### 3.5 PPTX 渲染引擎\n\nSim 内置了 PowerPoint 文件的解析和渲染能力，位于 `apps/sim/lib/pptx-renderer/` 目录。\n\n#### 3.5.1 渲染特性\n\n- 解析 OOXML 格式的 PPTX 文件\n- 支持 WPS Office 和 Microsoft Office 格式识别\n- 基于关系 ID 而非数字幻灯片 ID 的排序逻辑\n- 支持窗口化列表渲染（用于大型演示文稿）\n\n```typescript\ninterface SIM_PPTX_LIST_OPTIONS {\n // 窗口化渲染配置\n}\n```\n\n资料来源：[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)\n\n### 3.6 AI Copilot 集成\n\nSim 平台集成了 AI Copilot 功能，提供智能化的工作流构建辅助。\n\n#### 3.6.1 Copilot 通信协议\n\nCopilot 使用流式通信协议，支持多种消息类型：\n\n```typescript\ninterface SyntheticFilePreviewPayload {\n toolCallId: string;\n toolName: 'workspace_file';\n previewPhase: 'start' | 'target' | 'editMeta' | 'content';\n content?: string;\n contentMode?: 'delta' | 'snapshot';\n previewVersion?: number;\n}\n```\n\n资料来源：[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)\n\n## 4. SDK 文档\n\n### 4.1 TypeScript SDK\n\nTypeScript SDK 提供了与 Sim 平台交互的完整接口。\n\n#### 4.1.1 核心类\n\n| 类名 | 功能 |\n|------|------|\n| `SimStudio` | 主客户端类 |\n| `SimStudioError` | 错误处理类，继承自 Error |\n| `WorkflowExecutionResult` | 执行结果数据类 |\n| `WorkflowStatus` | 工作流状态类 |\n| `AsyncExecutionResult` | 异步执行结果 |\n\n资料来源：[packages/ts-sdk/README.md:50-120](https://github.com/simstudioai/sim/blob/main/packages/ts-sdk/README.md)\n\n#### 4.1.2 速率限制与用量\n\n```typescript\ninterface UsageLimits {\n success: boolean;\n rateLimit: {\n sync: {\n isLimited: boolean;\n limit: number;\n remaining: number;\n resetAt: string;\n };\n async: {\n isLimited: boolean;\n limit: number;\n remaining: number;\n resetAt: string;\n };\n authType: string;\n };\n}\n```\n\n### 4.2 Python SDK\n\nPython SDK 提供 Python 环境的集成支持。\n\n#### 4.2.1 安装要求\n\n| 要求 | 最低版本 |\n|------|----------|\n| Python | 3.8+ |\n| requests | 2.25.0+ |\n\n资料来源：[packages/python-sdk/README.md:1-30](https://github.com/simstudioai/sim/blob/main/packages/python-sdk/README.md)\n\n#### 4.2.2 代码质量工具\n\nPython SDK 使用以下工具保证代码质量：\n\n| 工具 | 用途 |\n|------|------|\n| black | 代码格式化 |\n| flake8 | 代码检查 |\n| mypy | 类型检查 |\n| isort | 导入排序 |\n\n## 5. 部署方式\n\n### 5.1 部署方式对比\n\n| 方式 | 难度 | 适用场景 | 要求 |\n|------|------|----------|------|\n| NPM 在线版 | ⭐ | 快速体验 | 互联网连接 |\n| Docker (npx) | ⭐⭐ | 本地开发 | Docker |\n| Docker Compose | ⭐⭐ | 生产部署 | Docker |\n| 手动安装 | ⭐⭐⭐ | 深度定制 | Bun, Node.js, PostgreSQL |\n\n资料来源：[README.md:20-60](https://github.com/simstudioai/sim/blob/main/README.md)\n\n### 5.2 Docker 部署配置\n\nDocker 部署支持以下配置选项：\n\n| 标志 | 描述 | 默认值 |\n|------|------|--------|\n| `-p, --port ` | 运行端口 | `3000` |\n| `--no-pull` | 跳过拉取最新镜像 | false |\n\n### 5.3 手动安装要求\n\n- **Bun**: JavaScript 运行时和包管理器\n- **Node.js**: v20+\n- **PostgreSQL**: 12+ with pgvector 扩展\n- **Redis**: 可选，用于缓存\n\n### 5.4 本地模型支持\n\nSim 支持使用本地大语言模型：\n\n- **Ollama**: 本地模型推理服务\n- **vLLM**: 高性能推理引擎\n\n详情请参阅 [Docker self-hosting docs](https://docs.sim.ai/self-hosting/docker)。\n\n## 6. 开发指南\n\n### 6.1 项目初始化\n\n```bash\n# 克隆仓库\ngit clone https://github.com/simstudioai/sim.git\ncd sim\n\n# 安装依赖\nbun install\n\n# 初始化\nbun run prepare # 设置 pre-commit hooks\n```\n\n资料来源：[README.md:40-50](https://github.com/simstudioai/sim/blob/main/README.md)\n\n### 6.2 环境变量配置\n\nSim 使用集中化的环境配置系统：\n\n```typescript\ninterface EnvConfig {\n NEXT_PUBLIC_APP_URL?: string;\n // ... 其他配置\n}\n```\n\n资料来源：[packages/testing/src/mocks/env.mock.ts:1-50](https://github.com/simstudioai/sim/blob/main/packages/testing/src/mocks/env.mock.ts)\n\n### 6.3 构建与测试\n\n| 命令 | 功能 |\n|------|------|\n| `bun run build` | 构建生产版本 |\n| `bun run test` | 运行测试 |\n| `bun run test:watch` | 监听模式运行测试 |\n| `bun run lint` | 代码检查并修复 |\n| `bun run type-check` | TypeScript 类型检查 |\n\n资料来源：[apps/sim/package.json:15-30](https://github.com/simstudioai/sim/blob/main/apps/sim/package.json)\n\n### 6.4 负载测试\n\nSim 提供了 Artillery 负载测试脚本：\n\n| 命令 | 描述 |\n|------|------|\n| `bun run load:workflow:waves` | 波浪式负载测试 |\n| `bun run load:workflow:isolation` | 工作空间隔离测试 |\n\n## 7. CI/CD 集成\n\nSim 项目集成了完整的 CI/CD 流程：\n\n- 文档生成器在 main 分支推送时自动运行\n- 更新的文档会自动提交回仓库\n- 代码质量检查（lint、type-check）集成在 CI 流程中\n\n## 8. 总结\n\nSim 是一个功能完整的可视化工作流自动化平台，其技术特点包括：\n\n1. **现代化技术栈**：基于 Next.js、Bun、TypeScript 构建\n2. **灵活的部署方式**：支持云端、本地 Docker 和手动部署\n3. **丰富的集成能力**：支持多种 Webhook 提供商和工具适配\n4. **完善的 SDK 支持**：提供 TypeScript 和 Python 两种 SDK\n5. **AI 能力集成**：内置 Copilot 支持智能化工作流构建\n6. **企业级功能**：包括速率限制、用量监控、沙箱执行等\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目概述](#page-project-overview), [工作流执行引擎](#page-workflow-execution), [实时协作与UI组件](#page-realtime-ui)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [apps/sim/app](https://github.com/simstudioai/sim/blob/main/apps/sim/app)\n- [apps/realtime/src](https://github.com/simstudioai/sim/blob/main/apps/realtime/src)\n- [apps/realtime/src/index.ts](https://github.com/simstudioai/sim/blob/main/apps/realtime/src/index.ts)\n- [packages/db](https://github.com/simstudioai/sim/blob/main/packages/db)\n- [packages/ts-sdk/README.md](https://github.com/simstudioai/sim/blob/main/packages/ts-sdk/README.md)\n- [packages/python-sdk/README.md](https://github.com/simstudioai/sim/blob/main/packages/python-sdk/README.md)\n- [apps/sim/package.json](https://github.com/simstudioai/sim/blob/main/apps/sim/package.json)\n- [packages/cli/README.md](https://github.com/simstudioai/sim/blob/main/packages/cli/README.md)\n
\n\n# 系统架构\n\n## 概述\n\nSim 是一个开源平台，用于构建 AI 代理并运行代理工作流。该平台连接超过 1000 种集成和大语言模型（LLM），以编排代理工作流。Sim 采用现代化全栈架构，基于 Next.js 框架构建，支持自托管部署和云端服务。\n\n技术栈核心组件包括：\n\n| 类别 | 技术选型 | 说明 |\n|------|----------|------|\n| 前端框架 | Next.js (App Router) | 支持 SSR/SSG 的 React 框架 |\n| 运行时 | Bun | 高性能 JavaScript 运行时和打包工具 |\n| 数据库 | PostgreSQL + pgvector | 支持向量存储的关系型数据库 |\n| ORM | Drizzle ORM | 类型安全的数据库操作层 |\n| 认证 | Better Auth | 现代化身份认证解决方案 |\n| 模式验证 | Zod | TypeScript 优先的模式验证库 |\n| UI 组件 | Shadcn + Tailwind CSS | 可定制的设计系统 |\n| 状态管理 | Zustand + TanStack Query | 客户端状态与服务器状态管理 |\n| 实时通信 | WebSocket | Socket 服务器处理实时交互 |\n\n资料来源：[README.md:1-50]()\n\n## 整体架构\n\nSim 平台采用微前端和多服务架构，主要包含以下核心模块：\n\n```mermaid\ngraph TD\n A[客户端浏览器] --> B[Next.js Web 应用]\n A --> C[Sim CLI]\n B --> D[PostgreSQL 数据库]\n B --> E[实时 Socket 服务]\n B --> F[工作流执行引擎]\n F --> D\n E --> F\n G[TypeScript SDK] --> B\n H[Python SDK] --> B\n I[CLI 工具] --> B\n```\n\n### 应用层模块\n\n#### Web 应用 (apps/sim)\n\n主应用程序采用 Next.js App Router 架构，核心目录结构如下：\n\n| 目录 | 功能 |\n|------|------|\n| `app/` | Next.js App Router 页面和 API 路由 |\n| `blocks/` | 预构建的工作流块定义 |\n| `lib/` | 核心业务逻辑库 |\n| `components/` | React UI 组件 |\n| `stores/` | Zustand 状态管理 stores |\n| `hooks/` | 自定义 React Hooks |\n\n资料来源：[apps/sim/package.json:1-30]()\n\n#### 实时服务 (apps/realtime)\n\n独立的 Socket 服务器处理实时通信功能，包括：\n\n- 工作流执行状态的实时推送\n- Copilot 交互的流式响应\n- 协作编辑的实时同步\n\n实时服务通过 WebSocket 协议与应用层通信，采用独立的部署单元以确保可扩展性。\n\n资料来源：[apps/realtime/src/index.ts](https://github.com/simstudioai/sim/blob/main/apps/realtime/src/index.ts)\n\n### 数据层\n\n#### 数据库架构\n\nSim 使用 PostgreSQL 作为主数据库，并通过 Drizzle ORM 提供类型安全的数据访问层：\n\n```mermaid\ngraph LR\n A[应用层] --> B[Drizzle ORM]\n B --> C[PostgreSQL]\n C --> D[pgvector 扩展]\n```\n\n关键数据库表结构通过迁移脚本管理，位于 `packages/db/migrations/` 目录。数据库迁移命令：\n\n```bash\ncd packages/db && bun run db:migrate\n```\n\n#### pgvector 集成\n\n平台集成 pgvector 扩展以支持向量存储和语义搜索功能，这对于 AI 代理的相似度匹配和知识检索至关重要。\n\n资料来源：[README.md:30-40]()\n\n## 工作流引擎架构\n\n### 执行模型\n\n工作流执行采用分层架构，支持同步和异步两种执行模式：\n\n```mermaid\ngraph TD\n A[API 触发器] --> B[工作流调度器]\n B --> C{执行模式}\n C -->|同步| D[沙箱执行器]\n C -->|异步| E[任务队列]\n D --> F[块处理器]\n E --> G[Worker 进程]\n G --> F\n F --> H[输出处理器]\n H --> I[结果聚合]\n```\n\n### 沙箱执行\n\n工作流中的代码块在隔离的沙箱环境中执行，确保安全性和隔离性。沙箱打包通过专门的构建脚本生成：\n\n```bash\nbun run build:sandbox-bundles\n```\n\n资料来源：[apps/sim/package.json:8]()\n\n### 块系统 (Blocks)\n\n块是工作流的基本构建单元，每个块定义包含：\n\n| 属性 | 说明 |\n|------|------|\n| `name` | 块名称 |\n| `description` | 功能描述 |\n| `category` | 分类标签 |\n| `inputs` | 输入规格定义 |\n| `outputs` | 输出规格定义 |\n| `config` | 配置参数 |\n\n块文档通过自动化脚本生成，位于 `scripts/generate-docs.ts`。运行文档生成：\n\n```bash\nbun run scripts/generate-docs.ts\n```\n\n资料来源：[scripts/README.md:1-25]()\n\n## SDK 架构\n\n### TypeScript SDK\n\nTypeScript SDK (`packages/ts-sdk`) 提供完整的客户端集成能力：\n\n```typescript\nimport { SimStudioClient } from '@simstudio/ts-sdk'\n\nconst client = new SimStudioClient({\n apiKey: process.env.SIM_API_KEY,\n baseUrl: 'https://sim.ai'\n})\n```\n\n核心接口包括：\n\n| 接口 | 功能 |\n|------|------|\n| `executeWorkflow` | 执行工作流 |\n| `getWorkflowStatus` | 查询工作流状态 |\n| `getExecutionResult` | 获取执行结果 |\n| `uploadFile` | 文件上传 |\n\n资料来源：[packages/ts-sdk/README.md:1-50]()\n\n### Python SDK\n\nPython SDK (`packages/python-sdk`) 提供 Python 生态的集成支持：\n\n```python\nfrom simstudio import SimStudioClient\n\nclient = SimStudioClient(api_key=os.getenv(\"SIM_API_KEY\"))\nresult = client.execute_workflow('workflow-id', input_data)\n```\n\n文件上传自动转换为 base64 格式，支持单文件和批量上传场景。\n\n资料来源：[packages/python-sdk/README.md:1-40]()\n\n## 认证与安全\n\n### 认证方案\n\n平台使用 Better Auth 作为认证解决方案，支持：\n\n- OAuth 社交登录\n- API Key 认证\n- Webhook 签名验证\n\n### Webhook 安全\n\nWebhook 提供商实现 HMAC 签名验证机制：\n\n```mermaid\ngraph TD\n A[外部服务] -->|POST + 签名| B[Webhook 端点]\n B --> C[验证签名]\n C -->|有效| D[处理事件]\n C -->|无效| E[拒绝请求]\n```\n\n支持的 Webhook 提供商包括 Gong、Webflow、Typeform 等，各提供商使用独立的签名验证策略。\n\n资料来源：[lib/webhooks/providers/typeform.ts:20-40]()\n\n## 部署架构\n\n### 部署模式\n\nSim 支持多种部署方式：\n\n| 部署方式 | 说明 | 适用场景 |\n|----------|------|----------|\n| Docker (npx) | 一键启动本地容器 | 快速原型验证 |\n| Docker Compose | 完整服务编排 | 自托管生产环境 |\n| 手动部署 | 细粒度控制 | 高级定制需求 |\n| Helm Charts | Kubernetes 部署 | 企业级集群环境 |\n\n### Docker 部署\n\n使用 Docker Compose 部署完整生产环境：\n\n```bash\ngit clone https://github.com/simstudioai/sim.git\ncd sim\ndocker compose -f docker-compose.prod.yml up -d\n```\n\n### Kubernetes 部署\n\nHelm Charts 提供 Kubernetes 原生部署支持，核心配置参数：\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `app.image.repository` | 应用镜像仓库 | simstudioai/sim |\n| `app.service.port` | 服务端口 | 3000 |\n| `realtime.enabled` | 启用实时服务 | true |\n| `realtime.replicaCount` | 实时服务副本数 | 1 |\n| `realtime.service.port` | 实时服务端口 | 3002 |\n\n资料来源：[helm/sim/README.md:1-30]()\n\n## 开发环境\n\n### 环境准备\n\n开发环境要求：\n\n- Bun v1.0+\n- Node.js v20+\n- PostgreSQL 12+ (启用 pgvector)\n- Docker (可选，用于数据库)\n\n### 本地开发\n\n```bash\n# 克隆仓库\ngit clone https://github.com/simstudioai/sim.git\ncd sim\n\n# 安装依赖\nbun install\n\n# 初始化数据库\ndocker run --name simstudio-db -e POSTGRES_PASSWORD=password \\\n -e POSTGRES_DB=simstudio -p 5432:5432 -d pgvector/pgvector\ncd packages/db && bun run db:migrate\n\n# 启动开发服务器\nbun run dev:full # 启动 Next.js 和 Socket 服务器\n```\n\n### 可用脚本\n\n| 脚本 | 功能 |\n|------|------|\n| `bun run dev` | 启动 Next.js 开发服务器 |\n| `bun run dev:sockets` | 启动 Socket 服务器 |\n| `bun run test` | 运行单元测试 |\n| `bun run build` | 构建生产版本 |\n| `bun run lint` | 代码风格检查 |\n\n资料来源：[README.md:40-60]()\n\n## 配置管理\n\n### 环境变量\n\n核心环境变量配置：\n\n| 变量 | 说明 | 必需 |\n|------|------|------|\n| `DATABASE_URL` | PostgreSQL 连接字符串 | 是 |\n| `COPILOT_API_KEY` | Copilot 服务 API Key | 可选 |\n| `SIM_API_KEY` | 第三方 SDK 认证 | 可选 |\n\n完整环境变量列表参考 `apps/sim/.env.example`。\n\n### 负载测试配置\n\n平台内置 Artillery 负载测试脚本，支持多种测试场景：\n\n| 脚本 | 场景 |\n|------|------|\n| `load:workflow:waves` | 波浪式负载测试 |\n| `load:workflow:isolation` | 隔离工作区负载测试 |\n\n资料来源：[apps/sim/package.json:5-10]()\n\n## 扩展机制\n\n### 触发器系统\n\n工作流支持多种触发类型，优先级排序如下：\n\n| 优先级 | 触发类型 | 说明 |\n|--------|----------|------|\n| 0 | Unified Start | 统一启动块 |\n| 1 | Legacy Starter | 遗留启动块 |\n| 2 | Schedule | 定时调度 |\n| 3 | Webhook | 外部 Webhook |\n| 4-7 | 其他 | API、手动、聊天触发 |\n\n触发器选择逻辑通过 `trigger-utils.ts` 中的优先级算法确定。\n\n资料来源：[lib/workflows/triggers/trigger-utils.ts:1-30]()\n\n### Webhook 提供商集成\n\n平台原生支持多个第三方服务的 Webhook 集成：\n\n- **Gong**: 通话记录和会议分析\n- **Webflow**: CMS 内容更新事件\n- **Typeform**: 表单提交事件\n- **Ashby**: ATS 招聘事件\n- **Salesforce**: CRM 事件\n\n每个提供商实现独立的格式转换和签名验证逻辑。\n\n资料来源：[lib/webhooks/providers/gong.ts:1-20]()\n资料来源：[lib/webhooks/providers/webflow.ts:1-30]()\n\n## 监控与可观测性\n\n### 执行追踪\n\n工作流执行支持完整的追踪机制：\n\n```mermaid\ngraph LR\n A[执行请求] --> B[追踪开始]\n B --> C[块执行]\n C --> D[输出生成]\n D --> E[追踪结束]\n```\n\n追踪数据包含执行时间戳、输入输出快照和错误信息。\n\n### 待验证 Webhook 处理\n\n平台实现待验证 Webhook 的自动探测和处理机制，防止验证请求被当作正式事件处理：\n\n```typescript\nconst pendingWebhookVerificationProbeMatchers = {\n ashby: ({ method, body }) => method === 'POST' && body?.action === 'ping',\n grain: ({ method, body }) => method === 'GET' || method === 'HEAD' || body?.type === undefined,\n // ...\n}\n```\n\n资料来源：[lib/webhooks/pending-verification.ts:1-30]()\n\n---\n\n\n\n## 工作流执行引擎\n\n### 相关页面\n\n相关主题：[系统架构](#page-system-architecture), [块系统与注册表](#page-block-registry), [代理与AI集成](#page-agent-integration)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [apps/sim/lib/workflows/triggers/trigger-utils.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/triggers/trigger-utils.ts)\n- [apps/sim/lib/workflows/triggers/triggers.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/triggers/triggers.ts)\n- [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)\n- [apps/sim/executor/dag/builder.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/executor/dag/builder.ts) *(未获取到具体内容)*\n- [apps/sim/executor/dag/types.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/executor/dag/types.ts) *(未获取到具体内容)*\n- [apps/sim/executor/execution/engine.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/executor/execution/engine.ts) *(未获取到具体内容)*\n- [apps/sim/executor/execution/executor.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/executor/execution/executor.ts) *(未获取到具体内容)*\n- [apps/sim/executor/execution/snapshot.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/executor/execution/snapshot.ts) *(未获取到具体内容)*\n\n> **注意**：部分核心执行引擎文件未能在当前上下文中获取，以下内容基于可访问的触发器和DAG差异引擎相关代码进行推断和分析。\n\n
\n\n# 工作流执行引擎\n\n## 概述\n\nSim 平台的工作流执行引擎是一个基于有向无环图（DAG）的自动化执行系统，负责解析、编排和执行用户定义的工作流程。该引擎支持多种触发方式、循环结构、并行执行以及复杂的数据流转，是整个自动化平台的核心运行时组件。\n\n工作流执行引擎的核心职责包括：\n\n1. **DAG 构建**：将用户配置的工作流转换为可执行的有向无环图结构\n2. **触发器管理**：支持手动、API、Webhook、定时调度等多种触发方式\n3. **块执行编排**：按照依赖关系顺序执行各个功能块\n4. **状态管理**：维护执行过程中的状态，支持暂停、恢复和快照\n5. **输出处理**：管理块之间的数据传递和变量绑定\n\n资料来源：[apps/sim/executor/orchestrators](https://github.com/simstudioai/sim/blob/main/apps/sim/executor/orchestrators)\n\n---\n\n## 核心架构\n\n### 执行引擎分层\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ 触发层 (Triggers) │\n│ 手动触发 │ API触发 │ Webhook触发 │ 定时调度 │ 聊天触发 │\n└─────────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ 编排层 (Orchestrators) │\n│ 循环编排器 │ 并行编排器 │ 顺序编排器 │\n└─────────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ 执行层 (Execution Engine) │\n│ DAG构建器 │ 执行器 │ 快照管理 │\n└─────────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ 沙箱层 (Sandbox) │\n│ 块代码执行环境 │ 工具函数调用 │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### 触发器优先级系统\n\n触发器系统采用优先级评分机制来选择最佳触发路径。当工作流存在多个可能的触发点时，系统按以下顺序选择：\n\n| 优先级 | 触发路径 | 说明 |\n|--------|----------|------|\n| 0 | `UNIFIED` | 统一入口块，最优先 |\n| 1 | `LEGACY_STARTER` | 传统起始块，兼容旧版本 |\n| 2 | `EXTERNAL_TRIGGER` (schedule) | 定时调度触发器 |\n| 3 | `EXTERNAL_TRIGGER` (其他) | Webhook 及外部集成触发 |\n| 4 | `SPLIT_API` | API 拆分触发 |\n| 5 | `SPLIT_INPUT` | 输入拆分触发 |\n| 6 | `SPLIT_MANUAL` | 手动拆分触发 |\n| 7 | `SPLIT_CHAT` | 聊天拆分触发 |\n| 99 | 未知 | 兜底默认值 |\n\n资料来源：[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)\n\n---\n\n## 触发器系统\n\n### 触发类型\n\nSim 平台定义了以下触发类型：\n\n```typescript\nexport const TRIGGER_TYPES = {\n START: 'start',\n API: 'api',\n CHAT: 'chat',\n STARTER: 'starter',\n} as const\n```\n\n### 启动模式\n\n每个触发块支持三种启动模式：\n\n| 模式值 | 说明 | 触发路径 |\n|--------|------|----------|\n| `manual` | 手动触发 | 启动模式为 undefined 或 'manual' |\n| `api` | API 调用触发 | 启动模式为 'api' 或 'run' |\n| `chat` | 聊天会话触发 | 启动模式为 'chat' |\n\n资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:1-20](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/triggers/triggers.ts)\n\n### 触发器引用别名\n\n系统提供别名映射，简化内联引用：\n\n```typescript\nexport const TRIGGER_REFERENCE_ALIAS_MAP = {\n start: TRIGGER_TYPES.START,\n api: TRIGGER_TYPES.API,\n chat: TRIGGER_TYPES.CHAT,\n manual: TRIGGER_TYPES.START,\n} as const\n```\n\n### 触发器工具类\n\n`TriggerUtils` 类提供静态方法用于触发器识别：\n\n| 方法 | 用途 |\n|------|------|\n| `isTriggerBlock(block)` | 判断块是否为任意类型的触发器 |\n| `isTriggerType(block, triggerType)` | 判断块是否为指定类型的触发器 |\n\n判断逻辑包括三个维度：\n\n1. 显式分类：块配置的 `category === 'triggers'`\n2. 触发模式标志：`block.triggerMode === true`\n3. 遗留兼容：`block.type === TRIGGER_TYPES.STARTER`\n\n资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:40-55](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/triggers/triggers.ts)\n\n### 模拟负载判断\n\n对于外部触发器，系统需要判断是否需要生成模拟负载：\n\n```typescript\nexport function triggerNeedsMockPayload(\n trigger: StartBlockCandidate\n): boolean {\n // 只有 webhook 和外部集成需要模拟负载\n // 定时调度正常运行，无需模拟数据\n return trigger.path === StartBlockPath.EXTERNAL_TRIGGER && trigger.block.type !== 'schedule'\n}\n```\n\n资料来源：[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)\n\n---\n\n## DAG 执行图构建\n\n### 块类型系统\n\n执行引擎通过块注册表管理所有可用块：\n\n```typescript\n// 测试中的 Mock 配置示例\nvi.mock('@/blocks', () => ({\n getBlock: () => null,\n getAllBlocks: () => ({}),\n getAllBlockTypes: () => [],\n getBlockByToolName: () => null,\n getBlocksByCategory: () => [],\n isValidBlockType: () => false,\n registry: {},\n}))\n```\n\n### 块分类\n\n块按功能分为多个类别：\n\n| 分类 | 说明 | 示例 |\n|------|------|------|\n| `triggers` | 触发器块 | 定时调度、Webhook、API |\n| `actions` | 动作块 | 发送消息、调用API |\n| `logic` | 逻辑块 | 条件判断、循环 |\n| `transform` | 转换块 | 数据转换、映射 |\n\n### 循环与并行\n\n系统支持两种高级执行模式：\n\n```typescript\n// 循环块生成\ngenerateLoopBlocks: () => ({})\n\n// 并行块生成\ngenerateParallelBlocks: () => ({})\n```\n\n---\n\n## 执行状态管理\n\n### 快照机制\n\n执行引擎支持执行快照功能，允许暂停和恢复工作流执行：\n\n```typescript\nvi.mock('@/lib/workflows/blocks/block-outputs', () => ({\n getEffectiveBlockOutputs: () => ({}),\n}))\n```\n\n快照功能涉及：\n\n- 块输出状态持久化\n- 执行进度记录\n- 变量上下文保存\n\n资料来源：[apps/sim/executor/execution/snapshot.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/executor/execution/snapshot.ts)\n\n### 执行维度\n\n执行引擎定义了块执行的约束维度：\n\n```typescript\nvi.mock('@/executor/constants', () => ({\n isAnnotationOnlyBlock: () => false,\n BLOCK_DIMENSIONS: { MIN_HEIGHT: 100 },\n HANDLE_POSITIONS: {},\n}))\n```\n\n---\n\n## Webhook 事件处理\n\n### 待验证 Webhook\n\n系统为不同提供商实现了 webhook 验证机制：\n\n| 提供商 | 验证策略 |\n|--------|----------|\n| `ashby` | 始终通过（仅 ping） |\n| `grain` | GET/HEAD 请求直接通过 |\n| `generic` | `verifyTestEvents` 元数据为 true 时通过 |\n| `salesforce` | GET/HEAD 请求直接通过 |\n\n```typescript\nconst pendingWebhookVerificationProbeMatchers: Record<\n string,\n PendingWebhookVerificationProbeMatcher\n> = {\n ashby: ({ method, body }) => method === 'POST' && body?.action === 'ping',\n grain: ({ method, body }) =>\n method === 'GET' ||\n method === 'HEAD' ||\n (method === 'POST' && (!body || Object.keys(body).length === 0 || !body.type)),\n generic: ({ method, body }) =>\n method === 'GET' ||\n method === 'HEAD' ||\n (method === 'POST' && (!body || Object.keys(body).length === 0)),\n salesforce: ({ method, body }) =>\n method === 'GET' ||\n method === 'HEAD' ||\n (method === 'POST' && (!body || Object.keys(body).length === 0)),\n}\n```\n\n资料来源：[apps/sim/lib/webhooks/pending-verification.ts:1-30](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/pending-verification.ts)\n\n---\n\n## 执行流程图\n\n### 完整执行生命周期\n\n```mermaid\ngraph TD\n A[工作流启动] --> B{选择触发器}\n B -->|手动| C[manual 模式]\n B -->|API| D[api 模式]\n B -->|Webhook| E[external_trigger 模式]\n B -->|定时| F[schedule 模式]\n B -->|聊天| G[chat 模式]\n \n C --> H[DAG 构建]\n D --> H\n E --> H\n F --> H\n G --> H\n \n H --> I{检查循环块}\n I -->|是| J[展开循环迭代]\n I -->|否| K{检查并行块}\n J --> K\n K -->|是| L[并行执行分支]\n K -->|否| M[顺序执行]\n \n L --> N[收集块输出]\n M --> N\n N --> O[数据传递]\n O --> P{还有更多块?}\n P -->|是| I\n P -->|否| Q[生成执行快照]\n Q --> R[工作流完成]\n```\n\n---\n\n## 配置与常量\n\n### 执行常量定义\n\n| 常量 | 说明 | 默认值 |\n|------|------|--------|\n| `BLOCK_DIMENSIONS.MIN_HEIGHT` | 块最小高度 | 100 |\n| `HANDLE_POSITIONS` | 连接点位置配置 | 空对象 |\n\n### 环境配置\n\n执行引擎使用统一的环境配置系统：\n\n```typescript\nvi.mock('@/lib/core/config/env', () => createEnvMock())\n```\n\n环境变量支持类型转换和默认值：\n\n```typescript\nenvNumber: (\n value: number | string | undefined | null,\n fallback: number,\n options: { min?: number } = {}\n): number => {\n const min = options.min ?? 0\n if (typeof value === 'number' && Number.isFinite(value) && value >= min) return value\n if (value === undefined || value === null || value === '') return fallback\n const parsed = Number(value)\n return Number.isFinite(parsed) && parsed >= min ? parsed : fallback\n}\n```\n\n资料来源：[packages/testing/src/mocks/env.mock.ts:1-50](https://github.com/simstudioai/sim/blob/main/packages/testing/src/mocks/env.mock.ts)\n\n---\n\n## 测试与调试\n\n### 执行引擎测试\n\n项目使用 Vitest 作为测试框架：\n\n```bash\nbun run test # 运行所有测试\nbun run test:watch # 监听模式\nbun run test:coverage # 覆盖率报告\n```\n\n### 常见 Mock 配置\n\n在测试中，核心模块通过以下方式隔离：\n\n```typescript\nvi.mock('@/stores/workflows/registry/store', () => ({\n useWorkflowRegistry: {\n getState: () => ({\n activeWorkflowId: null,\n }),\n },\n}))\n\nvi.mock('@/tools/utils', () => ({\n getTool: () => null,\n}))\n\nvi.mock('@/lib/workflows/subblocks/visibility', () => ({\n buildDefaultCanonicalModes: () => ({}),\n}))\n```\n\n资料来源：[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)\n\n---\n\n## 最佳实践\n\n### 触发器选择\n\n1. **优先使用统一入口**：对于新工作流，使用 `UNIFIED` 触发器\n2. **外部集成用 Webhook**：需要接收外部事件时使用 `EXTERNAL_TRIGGER`\n3. **定时任务用 Schedule**：周期性任务使用 schedule 类型触发器\n\n### 执行性能\n\n1. **减少循环嵌套深度**：深层循环会影响执行性能\n2. **合理使用并行块**：独立任务应使用并行执行\n3. **优化块输出**：避免传递过大的数据对象\n\n### 错误处理\n\n1. **配置超时时间**：为长时间运行的块设置合理超时\n2. **使用条件块**：在关键路径添加条件判断\n3. **利用快照恢复**：定期保存执行快照以便故障恢复\n\n---\n\n\n\n## 块系统与注册表\n\n### 相关页面\n\n相关主题：[工作流执行引擎](#page-workflow-execution), [连接器框架](#page-connectors)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [apps/sim/lib/workflows/triggers/triggers.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/triggers/triggers.ts)\n- [apps/sim/lib/workflows/sanitization/subblocks.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/sanitization/subblocks.ts)\n
\n\n# 块系统与注册表\n\n## 概述\n\n块系统（Block System）是 Sim 工作流平台的核心组件化架构，用于定义和执行业务逻辑。每个块代表一个独立的功能单元，可通过可视化编辑器组合成复杂的工作流程。\n\n块注册表（Block Registry）提供统一的块发现、检索和验证机制，确保工作流引擎能够正确识别和执行各类块。\n\n## 核心概念\n\n### 块的定义\n\n块是 Sim 平台中最小的可配置功能单元，包含以下关键属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `type` | `string` | 块的唯一标识符 |\n| `category` | `string` | 块所属的分类，如 `triggers` |\n| `triggerMode` | `boolean` | 是否为触发器模式 |\n| `subBlocks` | `Record` | 子块配置 |\n\n### 触发器块\n\n触发器块是特殊类型的块，用于启动工作流执行。Sim 支持多种触发模式：\n\n```typescript\ntype TriggerMode = 'manual' | 'api' | 'chat'\n```\n\n根据触发模式的不同，工作流可以通过以下方式启动：\n\n- **manual（手动）**: 用户通过界面手动触发\n- **api（API）**: 通过外部 API 调用触发\n- **chat（对话）**: 通过聊天接口触发\n\n## 注册表架构\n\n### 块发现接口\n\n注册表提供了完整的块发现 API，支持多种查询方式：\n\n```typescript\n// 根据类型获取块\ngetBlock(type: string): BlockConfig | null\n\n// 获取所有块\ngetAllBlocks(): Record\n\n// 获取所有块类型\ngetAllBlockTypes(): BlockType[]\n\n// 根据工具名称获取块\ngetBlockByToolName(toolName: string): BlockConfig | null\n\n// 根据分类获取块\ngetBlocksByCategory(category: string): BlockConfig[]\n\n// 验证块类型是否有效\nisValidBlockType(type: string): boolean\n```\n\n### 注册表结构\n\n注册表采用单例模式设计，通过 `registry` 对象集中管理所有块定义：\n\n```typescript\n// 资料来源：apps/sim/lib/workflows/diff/diff-engine.test.ts:1-50\nvi.mock('@/blocks', () => ({\n getBlock: () => null,\n getAllBlocks: () => ({}),\n getAllBlockTypes: () => [],\n getBlockByToolName: () => null,\n getBlocksByCategory: () => [],\n isValidBlockType: () => false,\n registry: {},\n}))\n```\n\n## 触发器系统\n\n### TriggerUtils 工具类\n\n`TriggerUtils` 提供了一系列静态方法用于处理触发器块的判断和分类：\n\n```typescript\n// 资料来源：apps/sim/lib/workflows/triggers/triggers.ts:1-50\nexport class TriggerUtils {\n static isTriggerBlock(block: { type: string; triggerMode?: boolean }): boolean {\n const blockConfig = getBlock(block.type)\n\n return (\n // 新触发器块（显式分类）\n blockConfig?.category === 'triggers' ||\n // 启用触发器模式的块\n block.triggerMode === true ||\n // 遗留的启动器块\n block.type === TRIGGER_TYPES.STARTER\n )\n }\n\n static isTriggerType(block: { type: string }, triggerType: TriggerType): boolean {\n return block.type === triggerType\n }\n}\n```\n\n### 触发器类型映射\n\n系统定义了触发器类型的别名映射，便于在引用中使用：\n\n```typescript\n// 资料来源：apps/sim/lib/workflows/triggers/triggers.ts:1-30\nexport const TRIGGER_REFERENCE_ALIAS_MAP = {\n start: TRIGGER_TYPES.START,\n api: TRIGGER_TYPES.API,\n chat: TRIGGER_TYPES.CHAT,\n manual: TRIGGER_TYPES.START,\n} as const\n\nexport type TriggerReferenceAlias = keyof typeof TRIGGER_REFERENCE_ALIAS_MAP\n```\n\n## 子块系统\n\n### 子块结构\n\n子块（SubBlocks）允许在父块内部定义可配置的子单元。每个子块包含：\n\n| 属性 | 说明 |\n|------|------|\n| `id` | 子块的唯一标识符 |\n| `type` | 子块的类型 |\n| `value` | 子块的当前值 |\n\n### 子块验证与修复\n\n系统提供自动化的子块数据校验和修复机制：\n\n```typescript\n// 资料来源：apps/sim/lib/workflows/sanitization/subblocks.ts:1-60\nconst typeFromConfig =\n configuredType || blockConfig?.subBlocks?.find((config) => config.id === id)?.type\n\nconst missingMetadata =\n typeof subBlock.id !== 'string' ||\n subBlock.id.length === 0 ||\n typeof subBlock.type !== 'string' ||\n subBlock.type.length === 0\n\nif (missingMetadata && !typeFromConfig) {\n logger.warn('Skipping malformed subBlock: unrecognized metadata entry', {\n blockId: block.id,\n subBlockId,\n })\n changed = true\n continue\n}\n```\n\n### 空值处理\n\n子块系统支持将空字符串转换为 `null` 的选项：\n\n```typescript\nconst hasValue = Object.hasOwn(subBlock, 'value')\nconst value =\n options.convertEmptyStringToNull && subBlock.value === ''\n ? null\n : hasValue\n ? subBlock.value\n : null\n```\n\n## 块的分类体系\n\n### 分类结构\n\n块按照功能进行分类管理，主要分类包括：\n\n| 分类 | 说明 |\n|------|------|\n| `triggers` | 触发器块，用于启动工作流 |\n| `actions` | 动作块，执行具体操作 |\n| `conditions` | 条件块，控制流程分支 |\n| `transforms` | 转换块，数据处理和转换 |\n\n### 分类查询\n\n通过 `getBlocksByCategory` 方法可以获取指定分类下的所有块：\n\n```typescript\n// 返回指定分类的所有块配置\ngetBlocksByCategory('triggers'): BlockConfig[]\n```\n\n## 工作流集成\n\n### 执行上下文\n\n块在工作流执行时通过注册表获取块配置：\n\n```mermaid\ngraph TD\n A[工作流引擎] --> B[块注册表]\n B --> C[getBlock type]\n C --> D[BlockConfig]\n D --> E[执行块逻辑]\n \n B --> F[getBlocksByCategory]\n F --> G[分类块列表]\n \n B --> H[isValidBlockType]\n H --> I[布尔验证结果]\n```\n\n### 触发器判断流程\n\n在执行工作流时，系统通过以下逻辑判断是否为触发器块：\n\n```mermaid\ngraph TD\n A[检查块配置] --> B{category === 'triggers'}\n B -->|是| E[是触发器块]\n B -->|否| C{triggerMode === true}\n C -->|是| E\n C -->|否| D{type === STARTER}\n D -->|是| E\n D -->|否| F[不是触发器块]\n```\n\n## 注册表初始化\n\n### 模块导出\n\n注册表通过统一的入口模块导出所有块相关的接口：\n\n```typescript\n// apps/sim/blocks/index.ts\nexport {\n registry,\n getBlock,\n getAllBlocks,\n getAllBlockTypes,\n getBlockByToolName,\n getBlocksByCategory,\n isValidBlockType,\n // ...\n}\n```\n\n### 类型定义\n\n系统通过类型定义文件提供完整的类型安全支持：\n\n```typescript\n// apps/sim/blocks/types.ts\nexport interface BlockConfig {\n type: string\n category: string\n name: string\n description?: string\n inputs?: InputSchema\n outputs?: OutputSchema\n config?: ConfigSchema\n subBlocks?: SubBlockDefinition[]\n}\n\nexport interface SubBlockDefinition {\n id: string\n type: string\n label?: string\n defaultValue?: unknown\n}\n```\n\n## 测试支持\n\n### Mock 配置\n\n在单元测试中，注册表模块可以被完全 Mock：\n\n```typescript\n// 资料来源：apps/sim/lib/workflows/diff/diff-engine.test.ts:1-50\nvi.mock('@/blocks', () => ({\n getBlock: () => null,\n getAllBlocks: () => ({}),\n getAllBlockTypes: () => [],\n getBlockByToolName: () => null,\n getBlocksByCategory: () => [],\n isValidBlockType: () => false,\n registry: {},\n}))\n```\n\n这种设计允许测试环境独立于实际块定义进行隔离测试。\n\n## 最佳实践\n\n### 块定义规范\n\n1. **唯一标识**: 每个块必须具有全局唯一的 `type` 标识符\n2. **明确分类**: 通过 `category` 属性声明块的所属分类\n3. **类型安全**: 使用 TypeScript 接口定义块的结构\n4. **配置验证**: 在注册表中验证块的配置完整性\n\n### 子块使用建议\n\n1. **默认值**: 为子块提供合理的默认值\n2. **类型约束**: 明确子块的类型定义\n3. **空值处理**: 使用 `convertEmptyStringToNull` 选项统一空值语义\n4. **日志记录**: 对异常子块数据进行日志记录以便排查\n\n## 相关资源\n\n- 块定义目录：`apps/sim/blocks/blocks/`\n- 块类型定义：`apps/sim/blocks/types.ts`\n- 块注册表实现：`apps/sim/blocks/registry.ts`\n- 触发器工具类：`apps/sim/lib/workflows/triggers/triggers.ts`\n\n---\n\n\n\n## 代理与AI集成\n\n### 相关页面\n\n相关主题：[工作流执行引擎](#page-workflow-execution), [块系统与注册表](#page-block-registry)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/simstudioai/sim/blob/main/README.md) — 项目主说明文件\n- [apps/sim/lib/workflows/triggers/triggers.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/triggers/triggers.ts) — 工作流触发器实现\n- [apps/sim/lib/copilot/request/session/contract.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/copilot/request/session/contract.ts) — Copilot 会话协议定义\n- [apps/sim/lib/core/security/input-validation.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/core/security/input-validation.ts) — 输入验证与安全模块\n- [apps/sim/lib/api/contracts/types.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/api/contracts/types.ts) — API 契约类型定义\n- [packages/testing/src/mocks/env.mock.ts](https://github.com/simstudioai/sim/blob/main/packages/testing/src/mocks/env.mock.ts) — 测试环境模拟\n\n> **注意**：以下代理核心文件未在当前检索上下文中找到：agent.ts、agent-handler.ts、memory.ts、skills-resolver.ts、types.ts。这些文件的缺失意味着本文档基于可用的上下文信息进行编写。\n
\n\n# 代理与AI集成\n\n## 概述\n\nSim 是一个开源平台，用于构建 AI 代理（Agent）并运行代理工作流。该平台连接超过 1000 个集成和 LLM，以编排代理工作流 资料来源：[README.md:1]。\n\nSim 的代理系统通过模块化架构实现，支持多种触发模式、工作流编排、以及与外部工具和 API 的深度集成。代理作为平台的核心执行单元，能够根据配置执行复杂的多步骤任务。\n\n## 核心架构\n\n### 代理与触发器关系\n\nSim 中的代理与触发器紧密耦合。触发器定义了代理何时以及如何被激活，而代理则负责执行业务逻辑。\n\n```mermaid\ngraph TD\n A[触发器 Trigger] --> B[触发模式 Trigger Mode]\n B --> C[manual 手动]\n B --> D[api API调用]\n B --> E[chat 聊天]\n A --> F[代理 Agent]\n F --> G[执行逻辑]\n G --> H[输出结果]\n```\n\n根据触发器实现，代理支持三种触发模式 资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:1-20]：\n\n| 触发模式 | 描述 | 触发方式 |\n|---------|------|---------|\n| `manual` | 手动触发 | 用户通过界面手动启动 |\n| `api` | API 触发 | 通过 HTTP 请求或 `run` 参数触发 |\n| `chat` | 聊天触发 | 通过对话交互触发 |\n\n触发模式通过 `readSubBlockValue(block.subBlocks, 'startWorkflow')` 读取，返回值为 `'chat'`、`'api'`、`'run'` 或 `'manual'` 资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:5-14]。\n\n### 代理块识别机制\n\nSim 使用 `TriggerUtils` 类提供统一的触发器检查功能 资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:35-55]：\n\n```typescript\nstatic isTriggerBlock(block: { type: string; triggerMode?: boolean }): boolean {\n const blockConfig = getBlock(block.type)\n return (\n blockConfig?.category === 'triggers' ||\n block.triggerMode === true ||\n block.type === TRIGGER_TYPES.STARTER\n )\n}\n```\n\n## 代理执行模型\n\n### 会话与流式处理\n\nSim 的代理系统支持流式输出，通过会话协议处理实时的代理响应。协议定义包括合成文件预览、流式引用追踪等高级功能 资料来源：[apps/sim/lib/copilot/request/session/contract.ts:1-50]。\n\n流式数据验证包括：\n\n| 验证项 | 类型 | 说明 |\n|-------|------|------|\n| `seq` | number | 序列号 |\n| `ts` | string | 时间戳 |\n| `stream` | StreamRef | 流引用 |\n| `trace` | Trace | 可选追踪信息 |\n| `scope` | StreamScope | 可选作用域 |\n\n### 文件预览集成\n\n代理执行过程中支持文件操作预览，包括新建文件、编辑元数据、完整内容展示等阶段 资料来源：[apps/sim/lib/copilot/request/session/contract.ts:60-90]：\n\n| 预览阶段 | 触发条件 |\n|---------|---------|\n| `start` | 预览开始 |\n| `target` | 文件操作目标确定 |\n| `editMeta` | 元数据编辑 |\n| `content` | 内容展示 |\n\n## 安全与输入验证\n\n### 代理参数验证\n\n所有代理输入必须经过严格验证，Sim 提供了多种验证器确保安全性 资料来源：[apps/sim/lib/core/security/input-validation.ts:1-80]：\n\n#### 枚举值验证\n\n```typescript\nvalidateEnum(\n value: string | null | undefined,\n allowedValues: readonly T[],\n paramName?: string\n): ValidationResult\n```\n\n此验证器确保代理接收的参数在允许的范围内，防止注入攻击 资料来源：[apps/sim/lib/core/security/input-validation.ts:50-75]。\n\n#### 主机名验证\n\n用于防止 SSRF（服务器端请求伪造）攻击，验证主机名不是私有 IP、本地地址或其他保留地址 资料来源：[apps/sim/lib/core/security/input-validation.ts:80-130]：\n\n| 检查项 | 描述 |\n|-------|------|\n| 私有 IP | 10.x.x.x, 172.16-31.x.x, 192.168.x.x |\n| 本地地址 | localhost, 127.0.0.1 |\n| 保留地址 | 0.0.0.0,169.254.x.x |\n\n## API 契约类型系统\n\nSim 使用强类型 API 契约定义代理与外部系统的交互 资料来源：[apps/sim/lib/api/contracts/types.ts:1-50]：\n\n### 契约参数类型\n\n| 类型别名 | 用途 |\n|---------|------|\n| `ContractParams` | 路由参数 |\n| `ContractQuery` | 查询参数 |\n| `ContractBody` | 请求体参数 |\n| `ContractHeaders` | 请求头参数 |\n\n这些类型通过泛型推断自动从 `ApiRouteContract` 提取对应的 Schema 类型 资料来源：[apps/sim/lib/api/contracts/types.ts:20-45]。\n\n## 工作流编排\n\n### 触发器分类\n\nSim 的工作流通过触发器类型进行分类管理 资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:25-35]：\n\n```mermaid\ngraph LR\n A[START] --> B[入口触发]\n C[API] --> D[API触发]\n E[CHAT] --> F[聊天触发]\n G[STARTER] --> H[遗留触发器]\n```\n\n### 触发引用别名\n\n平台定义了别名映射，简化跨系统的触发器引用 资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:18-24]：\n\n```typescript\nexport const TRIGGER_REFERENCE_ALIAS_MAP = {\n start: TRIGGER_TYPES.START,\n api: TRIGGER_TYPES.API,\n chat: TRIGGER_TYPES.CHAT,\n manual: TRIGGER_TYPES.START,\n} as const\n```\n\n## 环境配置与测试\n\n### 代理运行环境\n\nSim 的代理支持多种运行环境配置，通过环境变量管理 资料来源：[packages/testing/src/mocks/env.mock.ts:1-40]：\n\n| 环境函数 | 描述 |\n|---------|------|\n| `getEnv` | 获取环境变量值 |\n| `isTruthy` | 检查真值 |\n| `isFalsy` | 检查假值 |\n| `envNumber` | 获取数值并支持最小值约束 |\n\n```typescript\nenvNumber(\n value: number | string | undefined | null,\n fallback: number,\n options: { min?: number } = {}\n): number\n```\n\n## 部署模式\n\n### 本地模型支持\n\nSim 支持通过 Ollama 和 vLLM 运行本地模型，为代理提供灵活的 AI 后端选择 资料来源：[README.md:1]。\n\n### 部署方式\n\n| 方式 | 说明 | 适用场景 |\n|-----|------|---------|\n| Docker | 一键部署 | 快速启动 |\n| Docker Compose | 完整生产环境 | 自托管部署 |\n| 手动配置 | 自定义设置 | 高级用户 |\n\n## 总结\n\nSim 的代理与 AI 集成系统采用模块化设计，通过触发器机制实现灵活的代理激活方式，支持手动、API 和聊天三种触发模式。系统内置完善的输入验证和安全防护，使用强类型 API 契约确保通信可靠性，并支持本地和云端多种 AI 模型后端。\n\n代理作为平台的核心执行单元，通过工作流编排实现复杂任务的自动化处理，同时保持高度的可扩展性和安全边界控制。\n\n---\n\n\n\n## 工作流编辑器\n\n### 相关页面\n\n相关主题：[实时协作与UI组件](#page-realtime-ui), [系统架构](#page-system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [apps/sim/lib/workflows/triggers/triggers.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/triggers/triggers.ts)\n- [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)\n- [apps/sim/lib/workflows/sanitization/validation.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/sanitization/validation.ts)\n- [apps/sim/lib/a2a/agent-card.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/a2a/agent-card.ts)\n- [packages/ts-sdk/README.md](https://github.com/simstudioai/sim/blob/main/packages/ts-sdk/README.md)\n- [packages/python-sdk/README.md](https://github.com/simstudioai/sim/blob/main/packages/python-sdk/README.md)\n- [scripts/README.md](https://github.com/simstudioai/sim/blob/main/scripts/README.md)\n
\n\n# 工作流编辑器\n\n## 概述\n\n工作流编辑器（Workflow Editor）是 Sim 平台的核心组件，用于可视化构建、配置和管理自动化工作流。该编辑器允许用户通过组合不同的 **块（Blocks）** 和 **触发器（Triggers）** 来创建复杂的自动化流程。\n\n工作流编辑器的主要职责包括：\n\n- 提供可视化的块编排界面\n- 管理工作流状态和配置\n- 处理触发器类型（手动、API、聊天）\n- 执行工作流验证和清理\n- 生成 A2A（Agent-to-Agent）协议兼容的代理卡片\n\n资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:1-50]()\n\n## 架构概览\n\n```mermaid\ngraph TD\n subgraph 工作流编辑器\n A[工作流编辑器 UI] --> B[块管理器]\n A --> C[触发器管理器]\n A --> D[验证引擎]\n end\n \n subgraph 块系统\n B --> E[块注册表]\n B --> F[子块配置]\n E --> G[块类型]\n G --> G1[Triggers]\n G --> G2[Actions]\n G --> G3[Logic]\n end\n \n subgraph 触发器系统\n C --> H[触发器类型]\n H --> H1[手动触发 Manual]\n H --> H2[API 触发 Api]\n H --> H3[聊天触发 Chat]\n end\n \n subgraph 执行层\n D --> I[工作流执行器]\n I --> J[沙箱执行环境]\n end\n```\n\n## 触发器系统\n\n触发器是工作流的入口点，决定了工作流的激活方式。Sim 平台支持三种主要的触发器类型。\n\n### 触发器类型\n\n| 触发器类型 | 值 | 说明 | 适用场景 |\n|-----------|-----|------|---------|\n| 手动触发 | `manual` | 用户通过界面手动启动 | 调试、测试、临时执行 |\n| API 触发 | `api` / `run` | 通过 API 接口调用触发 | 外部系统集成、Webhook |\n| 聊天触发 | `chat` | 通过聊天界面交互触发 | 对话式自动化 |\n\n资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:35-50]()\n\n### 触发器类型常量\n\n```typescript\nexport const TRIGGER_TYPES = {\n START: 'start',\n INPUT: 'input',\n API: 'api_trigger',\n CHAT: 'chat_trigger',\n MANUAL: 'manual_trigger',\n STARTER: 'starter', // 遗留类型\n} as const\n```\n\n### 触发器判断方法\n\n`TriggerUtils` 类提供了静态方法来判断块是否为触发器：\n\n```typescript\nexport class TriggerUtils {\n // 判断是否为触发器块\n static isTriggerBlock(block: { type: string; triggerMode?: boolean }): boolean\n \n // 判断是否为特定触发器类型\n static isTriggerType(block: { type: string }, triggerType: TriggerType): boolean\n \n // 判断是否为手动触发器\n static isManualTrigger(block: { type: string; subBlocks?: any }): boolean\n \n // 判断是否为 API 触发器\n static isApiTrigger(block: { type: string; subBlocks?: any }, isChildWorkflow?: boolean): boolean\n}\n```\n\n### 触发器引用别名\n\n系统支持通过别名引用触发器：\n\n```typescript\nexport const TRIGGER_REFERENCE_ALIAS_MAP = {\n start: TRIGGER_TYPES.START,\n api: TRIGGER_TYPES.API,\n chat: TRIGGER_TYPES.CHAT,\n manual: TRIGGER_TYPES.START,\n} as const\n```\n\n资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:55-75]()\n\n## 块系统\n\n块（Block）是工作流编辑器的基本构建单元，每个块代表一个具体的操作或功能。\n\n### 块注册表\n\n块通过注册表进行统一管理，提供以下查询接口：\n\n```typescript\n// 获取单个块\ngetBlock(type: string): BlockConfig | null\n\n// 获取所有块\ngetAllBlocks(): Record\n\n// 获取所有块类型\ngetAllBlockTypes(): BlockConfig[]\n\n// 通过工具名称获取块\ngetBlockByToolName(toolName: string): BlockConfig | null\n\n// 按类别获取块\ngetBlocksByCategory(category: string): BlockConfig[]\n\n// 验证块类型是否有效\nisValidBlockType(type: string): boolean\n```\n\n### 块类别\n\n| 类别 | 说明 | 示例 |\n|-----|------|------|\n| `triggers` | 触发器块 | Start、API Trigger、Manual Trigger |\n| `actions` | 操作块 | HTTP 请求、数据处理 |\n| `logic` | 逻辑块 | 条件判断、循环 |\n\n资料来源：[apps/sim/lib/workflows/diff/diff-engine.test.ts:15-30]()\n\n### 子块配置\n\n每个块可以包含多个子块（Sub-Blocks），用于配置块的详细行为：\n\n```typescript\ninterface SubBlockState {\n value: unknown\n visible?: boolean\n annotation?: string\n}\n```\n\n### 块输出管理\n\n块输出（Block Outputs）用于在工作流中传递数据：\n\n```typescript\ngetEffectiveBlockOutputs(blockId: string): Record\n```\n\n资料来源：[apps/sim/lib/workflows/diff/diff-engine.test.ts:35-40]()\n\n## 工作流验证与清理\n\n工作流在保存或执行前需要经过验证和清理流程。\n\n### 验证流程\n\n```mermaid\ngraph TD\n A[工作流状态] --> B[验证块引用]\n B --> C[验证触发器配置]\n C --> D[清理工具配置]\n D --> E[验证工具 Schema]\n E --> F[返回验证结果]\n \n B -->|失败| G[记录错误]\n C -->|失败| G\n D -->|失败| G\n E -->|失败| G\n```\n\n### 验证结果类型\n\n```typescript\nexport interface WorkflowValidationResult {\n valid: boolean // 是否有效\n errors: string[] // 错误列表\n warnings: string[] // 警告列表\n sanitizedState?: WorkflowState // 清理后的状态\n}\n```\n\n### 清理规则\n\n| 规则类型 | 处理方式 | 说明 |\n|---------|---------|------|\n| 自定义工具 ID | `customToolId` | 确保工具标识唯一 |\n| Schema 验证 | `schema` | 验证工具输入输出定义 |\n| 引用工具 | `usageControl` | 设置默认值 `auto` |\n| 内联工具 | `code` | 确保代码字段存在 |\n\n### 工具清理流程\n\n```typescript\n.map((tool: unknown) => {\n if (isRecord(tool) && tool.type === 'custom-tool') {\n // 引用工具：确保 usageControl 默认值\n if (!tool.usageControl) {\n tool.usageControl = 'auto'\n }\n // 内联工具：确保 code 字段\n if (!tool.customToolId && (!tool.code || typeof tool.code !== 'string')) {\n tool.code = ''\n }\n }\n return tool\n})\n```\n\n资料来源：[apps/sim/lib/workflows/sanitization/validation.ts:1-80]()\n\n## A2A 代理集成\n\n工作流编辑器支持通过 A2A（Agent-to-Agent）协议与其他代理系统集成。\n\n### 代理卡片生成\n\n每个工作流可以生成对应的代理卡片，用于服务发现和能力描述：\n\n```typescript\nexport function generateAgentCard(\n agent: AgentConfig,\n workflow: WorkflowConfig,\n baseUrl: string\n): AppAgentCard\n```\n\n### 代理技能定义\n\n```typescript\nexport function generateSkillsFromWorkflow(\n workflowName: string,\n workflowDescription: string | null,\n tags?: string[]\n): AgentSkill[] {\n return [{\n id: 'execute',\n name: `Execute ${workflowName}`,\n description: workflowDescription || `Execute the ${workflowName} workflow`,\n tags: tags || [],\n }]\n}\n```\n\n### 代理卡片验证\n\n```typescript\nexport function validateAgentCard(card: unknown): card is AppAgentCard {\n if (!card || typeof card !== 'object') return false\n \n const c = card as Record\n if (typeof c.name !== 'string' || !c.name) return false\n if (typeof c.url !== 'string' || !c.url) return false\n // ... 更多验证\n}\n```\n\n资料来源：[apps/sim/lib/a2a/agent-card.ts:1-80]()\n\n## 工作流执行\n\n### 执行模式\n\n| 模式 | 说明 | 适用场景 |\n|-----|------|---------|\n| 同步执行 | 等待执行完成返回结果 | 实时响应、快速验证 |\n| 异步执行 | 立即返回任务 ID，后续查询状态 | 长时间运行、外部集成 |\n\n### 执行选项\n\n```typescript\ninterface ExecutionOptions {\n timeout?: number // 超时时间（毫秒）\n stream?: boolean // 是否启用流式输出\n selectedOutputs?: string[] // 选择性输出字段\n async?: boolean // 异步执行模式\n}\n\ninterface RetryOptions {\n maxRetries?: number // 最大重试次数\n initialDelay?: number // 初始延迟\n maxDelay?: number // 最大延迟\n backoffMultiplier?: number // 退避乘数\n}\n```\n\n### 执行结果\n\n```typescript\ninterface WorkflowExecutionResult {\n success: boolean // 是否成功\n output?: any // 输出数据\n error?: string // 错误信息\n logs?: list // 执行日志\n metadata?: Dict // 元数据\n trace_spans?: list // 追踪跨度\n total_duration?: float // 总耗时\n}\n\ninterface AsyncExecutionResult {\n success: boolean // 是否成功\n task_id: str // 任务 ID\n status: 'queued' // 状态\n created_at: str // 创建时间\n links: Dict[str, str] // 相关链接\n}\n```\n\n### 执行常量\n\n```typescript\n// 注释专用块\nisAnnotationOnlyBlock(): boolean\n\n// 块尺寸限制\nBLOCK_DIMENSIONS = { MIN_HEIGHT: 100 }\n\n// 句柄位置\nHANDLE_POSITIONS = {}\n```\n\n资料来源：[apps/sim/lib/workflows/diff/diff-engine.test.ts:45-55]()\n\n## 块文档生成\n\n工作流编辑器包含自动化文档生成功能。\n\n### 文档生成流程\n\n```mermaid\ngraph TD\n A[扫描块目录] --> B[提取元数据]\n B --> C[生成 Markdown]\n C --> D[更新 meta.json]\n D --> E[提交文档]\n```\n\n### 支持的元数据\n\n| 元数据字段 | 说明 |\n|----------|------|\n| Name | 块名称 |\n| Description | 块描述 |\n| Category | 所属类别 |\n| Input | 输入规格 |\n| Output | 输出规格 |\n| Config | 配置参数 |\n\n### 手动内容保留\n\n文档生成器支持保留手动添加的内容：\n\n```markdown\n{/_ MANUAL-CONTENT-START:usage _/}\n\n## Examples\n\n### Basic Usage\n\n```json\n{ \"parameter\": \"value\" }\n```\n\n{/_ MANUAL-CONTENT-END _/}\n```\n\n资料来源：[scripts/README.md:1-60]()\n\n## SDK 支持\n\n### TypeScript SDK\n\n```typescript\nimport { SimStudioClient } from '@simstudio/ts-sdk'\n\nconst client = new SimStudioClient({ apiKey: 'your-api-key' })\n\n// 同步执行\nconst result = await client.workflows.execute('workflow-id', {\n input: { data: 'example' }\n})\n\n// 异步执行\nconst asyncResult = await client.workflows.executeAsync('workflow-id', {\n input: { data: 'example' }\n})\n```\n\n### Python SDK\n\n```python\nfrom simstudio import Client\n\nclient = Client(api_key=\"your-api-key\")\n\n# 同步执行\nresult = client.workflows.execute(\"workflow-id\", {\"data\": \"example\"})\n\n# 异步执行\nasync_result = client.workflows.execute_async(\"workflow-id\", {\"data\": \"example\"})\n```\n\n资料来源：[packages/ts-sdk/README.md:1-100]()\n[packages/python-sdk/README.md:1-100]()\n\n## 相关资源\n\n| 资源类型 | 说明 |\n|---------|------|\n| `/app/workspace/[workspaceId]/w/[workflowId]` | 工作流编辑器主路由 |\n| `/components/panel/components/editor` | 编辑器面板组件 |\n| `/components/workflow-block` | 工作流块组件 |\n| `/components/panel/components/sub-block` | 子块配置组件 |\n\n---\n\n\n\n## 实时协作与UI组件\n\n### 相关页面\n\n相关主题：[系统架构](#page-system-architecture), [工作流编辑器](#page-workflow-editor)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [apps/sim/lib/workflows/triggers/triggers.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/triggers/triggers.ts)\n- [apps/sim/lib/workflows/triggers/trigger-utils.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/triggers/trigger-utils.ts)\n- [apps/sim/lib/webhooks/providers/gong.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/providers/gong.ts)\n- [apps/sim/lib/webhooks/providers/typeform.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/providers/typeform.ts)\n- [apps/sim/lib/api/contracts/types.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/api/contracts/types.ts)\n- [apps/sim/app/workspace/providers/socket-provider.tsx](https://github.com/simstudioai/sim/blob/main/apps/sim/app/workspace/providers/socket-provider.tsx)\n- [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)\n
\n\n# 实时协作与UI组件\n\n## 概述\n\n实时协作与UI组件是 Sim 平台中支持多用户同时编辑和工作流管理的核心功能模块。该系统通过 WebSocket 连接实现实时状态同步，支持工作流设计器的协作编辑、触发器实时监控、以及与外部系统（如 Gong、Typeform）的Webhook集成。\n\n**核心职责：**\n\n- 建立和管理 WebSocket 连接，实现客户端与服务器的实时双向通信\n- 提供协作用户的光标追踪和状态显示功能\n- 处理工作流触发器的实时事件流\n- 集成第三方Webhook提供商的实时数据接收\n\n**技术范围：**\n\n- Socket Provider 客户端组件\n- 光标和协作状态组件\n- 工作流触发器系统\n- Webhook提供商的实时数据处理\n- API契约类型定义\n\n---\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n subgraph 客户端层[\"客户端层\"]\n SP[Socket Provider]\n CURSORS[光标组件]\n UI[工作流编辑器 UI]\n end\n \n subgraph 实时服务[\"实时服务 - apps/realtime\"]\n HANDLERS[事件处理器]\n MIDDLEWARE[中间件]\n ROOMS[房间管理]\n end\n \n subgraph 业务逻辑层[\"业务逻辑层\"]\n TRIGGERS[触发器系统]\n WEBHOOKS[Webhook提供商]\n end\n \n subgraph 外部系统[\"外部集成\"]\n GONG[Gong平台]\n TYPEFORM[Typeform]\n SCHEDULE[调度器]\n end\n \n SP <-->|WebSocket| HANDLERS\n HANDLERS <--> ROOMS\n HANDLERS <--> MIDDLEWARE\n TRIGGERS -->|触发事件| HANDLERS\n WEBHOOKS -->|Webhook事件| TRIGGERS\n UI <--> SP\n CURSORS <--> SP\n```\n\n### Socket Provider 架构\n\nSocket Provider 是 React 上下文提供者，负责管理 WebSocket 连接的生命周期。\n\n```mermaid\ngraph LR\n A[React App] -->|Provider| B[SocketContext]\n B --> C[WebSocket Connection]\n C -->|onOpen| D[连接建立]\n C -->|onMessage| E[消息处理]\n C -->|onClose| F[重连逻辑]\n C -->|onError| G[错误处理]\n```\n\n---\n\n## Socket Provider 组件\n\n### 组件位置\n\n`apps/sim/app/workspace/providers/socket-provider.tsx`\n\n### 核心功能\n\nSocket Provider 组件是 Sim 应用中 WebSocket 连接的中心化管理器，提供以下核心功能：\n\n| 功能 | 说明 |\n|------|------|\n| 连接管理 | 建立与实时服务器的 WebSocket 连接 |\n| 自动重连 | 连接断开时自动尝试重新连接 |\n| 消息订阅 | 支持订阅特定事件类型的消息 |\n| 状态同步 | 维护连接状态并向子组件广播 |\n| 上下文提供 | 通过 React Context 向子树提供 Socket 实例 |\n\n### 连接生命周期\n\n```mermaid\nstateDiagram-v2\n [*] --> Disconnected: 初始状态\n Disconnected --> Connecting: 调用 connect()\n Connecting --> Connected: WebSocket open\n Connecting --> Disconnected: 连接失败\n Connected --> Disconnected: 连接关闭\n Disconnected --> Connecting: 自动重连\n Connected --> [*]: 组件卸载\n```\n\n**连接状态说明：**\n\n| 状态 | 描述 |\n|------|------|\n| `disconnected` | 初始状态或连接已关闭 |\n| `connecting` | 正在建立 WebSocket 连接 |\n| `connected` | 连接已建立，可收发消息 |\n| `reconnecting` | 正在尝试重新连接 |\n\n### 事件订阅机制\n\nSocket Provider 支持基于事件类型的消息订阅，客户端可以注册特定事件的处理器：\n\n```typescript\n// 订阅示例\nsocket.subscribe('workflow.update', handler)\nsocket.subscribe('cursor.move', handler)\n\n// 取消订阅\nsocket.unsubscribe('workflow.update', handler)\n```\n\n---\n\n## 协作用户光标组件\n\n### 组件位置\n\n`apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/cursors/cursors.tsx`\n\n### 功能说明\n\n光标组件负责显示和追踪协作用户在编辑器中的实时位置和操作状态。\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `userId` | `string` | 协作用户唯一标识 |\n| `userName` | `string` | 协作用户显示名称 |\n| `color` | `string` | 用户分配的颜色（用于区分不同用户） |\n| `position` | `{ x: number, y: number }` | 当前光标位置 |\n| `isActive` | `boolean` | 用户当前是否处于活跃状态 |\n| `lastUpdate` | `number` | 最后更新时间戳 |\n\n### 光标渲染逻辑\n\n```mermaid\ngraph TD\n A[接收 CursorMove 事件] --> B{检查用户状态}\n B -->|用户活跃| C[更新本地状态]\n B -->|用户空闲超时| D[降低透明度/隐藏]\n C --> E[重新渲染光标组件]\n D --> E\n E --> F[显示用户名称标签]\n```\n\n### 协作用户管理\n\n光标组件支持显示当前工作区的所有协作用户：\n\n| 用户状态 | 视觉表现 |\n|----------|----------|\n| 活跃编辑 | 正常显示，带有用户名称标签 |\n| 空闲 | 降低透明度至 50% |\n| 长时间无活动 | 隐藏光标（节省渲染资源） |\n| 断开连接 | 立即移除光标显示 |\n\n---\n\n## 工作流触发器系统\n\n### 触发器类型\n\nSim 平台支持多种触发器类型，用于启动工作流执行：\n\n| 触发器类型 | 标识符 | 说明 | 优先级 |\n|-----------|--------|------|--------|\n| 手动触发 | `TRIGGER_TYPES.START` | 用户手动启动工作流 | 0（最高） |\n| API触发 | `TRIGGER_TYPES.API` | 通过API调用触发 | 4 |\n| 聊天触发 | `TRIGGER_TYPES.CHAT` | 通过聊天消息触发 | 7 |\n| 调度触发 | `schedule` | 定时/周期执行 | 2 |\n| Webhook触发 | `external_trigger` | 外部Webhook事件触发 | 3 |\n\n资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:1-50]()\n\n### 触发器引用别名映射\n\n系统定义了触发器引用别名，方便在内部引用不同类型的触发器：\n\n```typescript\nexport const TRIGGER_REFERENCE_ALIAS_MAP = {\n start: TRIGGER_TYPES.START,\n api: TRIGGER_TYPES.API,\n chat: TRIGGER_TYPES.CHAT,\n manual: TRIGGER_TYPES.START,\n} as const\n```\n\n资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:50-60]()\n\n### 触发器优先级排序\n\n触发器根据类型和配置进行优先级排序：\n\n```mermaid\ngraph TD\n A[触发器候选列表] --> B[按路径分组]\n B --> C{StartBlockPath 判断}\n C -->|UNIFIED| D[优先级 0]\n C -->|LEGACY_STARTER| E[优先级 1]\n C -->|EXTERNAL_TRIGGER| F{类型判断}\n C -->|SPLIT_API| G[优先级 4]\n C -->|SPLIT_INPUT| H[优先级 5]\n C -->|SPLIT_MANUAL| I[优先级 6]\n C -->|SPLIT_CHAT| J[优先级 7]\n F -->|schedule| K[优先级 2]\n F -->|其他| L[优先级 3]\n D --> M[排序完成]\n E --> M\n K --> M\n L --> M\n G --> M\n H --> M\n I --> M\n J --> M\n```\n\n资料来源：[apps/sim/lib/workflows/triggers/trigger-utils.ts:1-35]()\n\n### 触发器工具类\n\n`TriggerUtils` 类提供静态方法用于触发器识别和验证：\n\n```typescript\nexport class TriggerUtils {\n // 检查块是否为触发器\n static isTriggerBlock(block: { type: string; triggerMode?: boolean }): boolean\n \n // 检查块是否为特定触发器类型\n static isTriggerType(block: { type: string }, triggerType: TriggerType): boolean\n}\n```\n\n### Mock Payload 需求判断\n\n对于需要测试数据的外部触发器，系统提供智能判断：\n\n```typescript\nexport function triggerNeedsMockPayload(\n trigger: StartBlockCandidate\n): boolean {\n // 仅 Webhook 和外部集成需要 Mock Payload\n // 调度器正常执行不需要模拟数据\n return trigger.path === StartBlockPath.EXTERNAL_TRIGGER && trigger.block...\n}\n```\n\n资料来源：[apps/sim/lib/workflows/triggers/trigger-utils.ts:60-75]()\n\n---\n\n## Webhook 实时数据处理\n\n### Webhook 提供商架构\n\nSim 平台集成了多个第三方 Webhook 提供商，实现实时数据接收：\n\n```mermaid\ngraph LR\n subgraph 外部系统\n GONG[Gong 自动化规则]\n TYPEFORM[Typeform 表单响应]\n end\n \n subgraph 标准化处理\n P_GONG[提供商处理器]\n P_TYPEFORM[提供商处理器]\n end\n \n GONG -->|POST /webhooks/gong| P_GONG\n TYPEFORM -->|POST /webhooks/typeform| P_TYPEFORM\n \n P_GONG --> FORMAT_G[格式化为统一输入]\n P_TYPEFORM --> FORMAT_T[格式化为统一输入]\n \n FORMAT_G --> WORKFLOW[触发工作流]\n FORMAT_T --> WORKFLOW\n```\n\n### Gong Webhook 提供商\n\n**文件位置：** `apps/sim/lib/webhooks/providers/gong.ts`\n\nGong 平台集成支持接收自动化规则事件：\n\n| 配置项 | 说明 |\n|--------|------|\n| `secret` | HMAC 签名验证密钥 |\n| `includeCallData` | 是否包含通话数据 |\n| `includeParties` | 是否包含通话参与者 |\n| `includeContext` | 是否包含通话上下文 |\n| `includeTrackers` | 是否包含追踪器数据 |\n| `includeTopics` | 是否包含主题信息 |\n| `includeHighlights` | 是否包含亮点标记 |\n\n**事件数据结构：**\n\n```typescript\n{\n eventType: 'gong.automation_rule',\n callId: string,\n metaData: Record,\n parties: unknown[],\n context: unknown[],\n trackers: unknown[],\n topics: unknown[],\n highlights: unknown[]\n}\n```\n\n### Typeform Webhook 提供商\n\n**文件位置：** `apps/sim/lib/webhooks/providers/typeform.ts`\n\nTypeform 集成支持接收表单响应事件：\n\n| 配置项 | 说明 |\n|--------|------|\n| `formId` | Typeform 表单 ID |\n| `apiKey` | Typeform API 密钥 |\n| `webhookTag` | Webhook 标签 |\n| `secret` | 签名验证密钥 |\n| `includeDefinition` | 是否包含表单定义 |\n\n**事件数据结构：**\n\n```typescript\n{\n event_id: string,\n event_type: 'form_response',\n form_id: string,\n token: string,\n submitted_at: string,\n landed_at: string,\n calculated: Record,\n variables: unknown[],\n hidden: Record,\n answers: unknown[],\n definition?: Record,\n ending: Record,\n raw: Record\n}\n```\n\n**认证验证：**\n\nTypeform 提供商使用 HMAC 签名验证：\n\n```typescript\nverifyAuth: createHmacVerifier({\n configKey: 'secret',\n headerName: 'Typeform-Signature',\n validateFn: validateTypeformSignature,\n providerLabel: 'Typeform',\n})\n```\n\n---\n\n## API 契约类型系统\n\n### 契约类型定义\n\n**文件位置：** `apps/sim/lib/api/contracts/types.ts`\n\nAPI 契约系统提供强类型的路由定义和参数提取：\n\n| 类型 | 说明 |\n|------|------|\n| `ApiRouteContract` | API 路由契约的核心类型定义 |\n| `ContractParams` | 提取契约中定义的路径参数类型 |\n| `ContractQuery` | 提取契约中定义的查询参数类型 |\n| `ContractBody` | 提取契约中定义的请求体类型 |\n| `ContractHeaders` | 提取契约中定义的头部参数类型 |\n| `ContractParamsInput` | 契约参数的输入形式 |\n\n### 类型提取示例\n\n```typescript\n// 从契约中提取各种参数类型\ntype MyParams = ContractParams\ntype MyQuery = ContractQuery\ntype MyBody = ContractBody\ntype MyHeaders = ContractHeaders\n```\n\n### 契约辅助函数\n\n```typescript\nfunction defineRoute(\n contract: ApiRouteContract\n): ApiRouteContract\n```\n\n---\n\n## 实时事件流\n\n### 工作流更新事件\n\n工作流状态变更通过 WebSocket 实时推送到所有连接的客户端：\n\n```mermaid\nsequenceDiagram\n participant U as 用户A (编辑器)\n participant S as Socket Provider\n participant R as Realtime Server\n participant W as 工作流引擎\n \n U->>W: 修改工作流\n W->>R: 触发 workflow.update 事件\n R->>S: 广播事件\n S->>U: 接收并处理事件\n Note over U: 更新本地 UI 状态\n```\n\n### 协作用户状态同步\n\n多个用户编辑同一工作流时，光标位置和操作状态实时同步：\n\n```mermaid\nsequenceDiagram\n participant U1 as 用户1 (光标移动)\n participant S as Socket Provider\n participant R as Realtime Server\n participant U2 as 用户2 (观察者)\n \n U1->>S: 发送 cursor.move 事件\n S->>R: 转发事件\n R->>S: 广播到其他客户端\n S->>U2: 接收并渲染光标\n Note over U2: 显示用户1的光标\n```\n\n---\n\n## 配置与扩展\n\n### 添加新的 Webhook 提供商\n\n要添加新的 Webhook 提供商，需要实现以下接口：\n\n| 方法 | 说明 |\n|------|------|\n| `formatInput` | 将原始请求格式化为统一输入格式 |\n| `verifyAuth` | 验证请求的认证信息 |\n| `createSubscription` | （可选）创建订阅配置 |\n\n**基本实现模板：**\n\n```typescript\nexport const myProvider: WebhookProvider = {\n formatInput: (body, webhook) => {\n // 格式化输入数据\n return {\n input: {\n // 统一输入格式\n }\n }\n },\n \n verifyAuth: createHmacVerifier({\n configKey: 'secret',\n headerName: 'Provider-Signature',\n validateFn: validateSignature,\n providerLabel: 'ProviderName',\n }),\n \n async createSubscription(ctx) {\n // 创建订阅逻辑\n return { subscriptionId: '...' }\n }\n}\n```\n\n### 触发器类型扩展\n\n要添加新的触发器类型，需要：\n\n1. 在 `TRIGGER_TYPES` 枚举中添加新类型\n2. 在 `StartBlockPath` 中添加对应路径\n3. 更新 `getPriority` 函数中的优先级逻辑\n4. 在触发器选择逻辑中添加相应的判断\n\n---\n\n## 错误处理与重试\n\n### WebSocket 连接错误处理\n\n| 错误类型 | 处理策略 |\n|----------|----------|\n| 连接超时 | 指数退避重连（最大5次） |\n| 网络断开 | 自动检测并重连 |\n| 服务器错误 | 通知用户，显示错误信息 |\n| 认证失败 | 重新认证流程 |\n\n### Webhook 验证失败\n\n验证失败的请求会被拒绝并记录日志：\n\n```typescript\nlogger.warn(`[${ctx.requestId}] Missing formId for Typeform...`)\nreturn undefined // 返回 undefined 表示验证失败\n```\n\n---\n\n## 性能优化\n\n### 光标渲染优化\n\n| 优化策略 | 说明 |\n|----------|------|\n| 空闲检测 | 用户长时间无活动时降低更新频率 |\n| 批量更新 | 合并短时间内的多次位置更新 |\n| 可视区域 | 只渲染当前可视区域内的光标 |\n| 脏检查 | 仅在位置变化时触发重新渲染 |\n\n### WebSocket 消息压缩\n\n| 策略 | 说明 |\n|------|------|\n| 增量更新 | 仅传输变化的字段 |\n| 消息合并 | 批量发送低优先级事件 |\n| 心跳优化 | 动态调整心跳间隔 |\n\n---\n\n## 相关文档\n\n| 文档 | 说明 |\n|------|------|\n| [Socket Provider 组件](/apps/sim/app/workspace/providers/socket-provider.tsx) | WebSocket 连接管理组件 |\n| [光标组件](/apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/cursors/cursors.tsx) | 协作用户光标显示 |\n| [触发器系统](/apps/sim/lib/workflows/triggers/triggers.ts) | 工作流触发器核心逻辑 |\n| [Gong 集成](/apps/sim/lib/webhooks/providers/gong.ts) | Gong Webhook 提供商 |\n| [Typeform 集成](/apps/sim/lib/webhooks/providers/typeform.ts) | Typeform Webhook 提供商 |\n\n---\n\n\n\n## 连接器框架\n\n### 相关页面\n\n相关主题：[块系统与注册表](#page-block-registry), [扩展与定制](#page-extensibility)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [apps/sim/lib/webhooks/providers/gong.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/providers/gong.ts)\n- [apps/sim/lib/webhooks/providers/webflow.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/providers/webflow.ts)\n- [apps/sim/lib/webhooks/providers/typeform.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/providers/typeform.ts)\n- [apps/sim/lib/webhooks/providers/vercel.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/providers/vercel.ts)\n- [apps/sim/blocks/blocks/](https://github.com/simstudioai/sim/blob/main/apps/sim/blocks/blocks/)\n- [apps/sim/blocks/index.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/blocks/index.ts)\n
\n\n# 连接器框架\n\n## 概述\n\nSim 平台中的连接器框架（Connector Framework）是用于实现与外部第三方服务集成的基础架构。该框架提供了一套标准化的模式，使得平台能够统一处理来自不同服务提供商（Provider）的 webhook 事件和数据转换。\n\n连接器框架的核心职责包括：\n\n- **事件接收**：接收来自外部服务的事件通知\n- **数据标准化**：将不同提供商的数据格式转换为统一的内部格式\n- **认证验证**：验证 webhook 请求的真实性\n- **事件过滤**：根据配置条件选择性处理事件\n- **数据映射**：将外部数据结构映射为工作流可用的输入格式\n\n## 架构设计\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[外部服务] -->|Webhook 事件| B[连接器提供者]\n B --> C{事件过滤}\n C -->|跳过| D[丢弃]\n C -->|通过| E[数据标准化]\n E --> F[工作流执行引擎]\n F --> G[Block 输出]\n \n H[认证模块] --> B\n```\n\n### Provider 架构模式\n\n每个连接器提供者（Provider）遵循统一的接口契约，确保系统的一致性和可扩展性：\n\n```mermaid\ngraph LR\n A[Webhook 请求] --> B[formatInput]\n B --> C[verifyAuth]\n C --> D{验证结果}\n D -->|失败| E[返回错误]\n D -->|成功| F[shouldSkipEvent]\n F --> G{跳过检查}\n G -->|是| H[跳过处理]\n G -->|否| I[触发工作流]\n```\n\n## Provider 接口规范\n\n### 核心接口定义\n\n每个连接器提供者必须实现以下核心方法：\n\n| 方法名 | 类型 | 描述 |\n|--------|------|------|\n| `formatInput` | 同步函数 | 将原始 webhook 负载转换为标准化的输入格式 |\n| `verifyAuth` | 认证函数 | 验证请求的认证签名 |\n| `createSubscription` | 异步函数 | 在外部服务创建 webhook 订阅 |\n| `shouldSkipEvent` | 同步函数 | 根据配置判断是否应跳过该事件 |\n\n### 输入格式化\n\n`formatInput` 函数负责将来自不同提供商的事件数据转换为统一的工作流输入格式：\n\n```typescript\ninterface FormatInputResult {\n input: {\n event_id: string\n event_type: string\n // 特定于提供商的其他字段...\n raw: Record // 原始数据保留\n }\n}\n```\n\n资料来源：[apps/sim/lib/webhooks/providers/typeform.ts:20-40]()\n\n### 认证验证模式\n\n认证验证采用工厂模式创建认证验证器，支持多种验证策略：\n\n```typescript\nverifyAuth: createHmacVerifier({\n configKey: 'secret',\n headerName: 'Typeform-Signature',\n validateFn: validateTypeformSignature,\n providerLabel: 'Typeform',\n})\n```\n\n支持的认证类型：\n\n| 认证类型 | 描述 | 适用场景 |\n|---------|------|---------|\n| HMAC 验证 | 基于共享密钥的消息认证码 | Typeform, GitHub |\n| Bearer Token | Bearer 令牌认证 | 通用 API |\n| 自定义验证 | 特定提供商的验证逻辑 | 各 Provider |\n\n资料来源：[apps/sim/lib/webhooks/providers/typeform.ts:47-53]()\n\n## 内置 Provider 实现\n\n### Webflow 连接器\n\nWebflow 连接器处理 CMS 和电商平台的事件，支持集合项的创建、更新和归档：\n\n```typescript\ninterface WebflowFieldMapping {\n lastUpdated: string | number\n createdOn: string | number\n isArchived: boolean\n isDraft: boolean\n fieldData: Record\n}\n```\n\n**事件过滤逻辑**：\n\n```typescript\nshouldSkipEvent({ webhook, body, requestId, providerConfig }: EventFilterContext) {\n const configuredCollectionId = providerConfig.collectionId as string | undefined\n // 当配置了特定集合 ID 时，只处理该集合的事件\n if (payloadCollectionId !== configuredCollectionId) {\n return true // 跳过不匹配的事件\n }\n return false\n}\n```\n\n资料来源：[apps/sim/lib/webhooks/providers/webflow.ts:1-50]()\n\n### Gong 连接器\n\nGong 连接器处理销售对话智能平台的事件，提取会议元数据和内容分析：\n\n```typescript\ninterface GongAutomationData {\n metaData: Record\n parties: unknown[]\n context: unknown[]\n trackers: unknown[]\n topics: unknown[]\n highlights: unknown[]\n eventType: string\n callId: string\n}\n```\n\n**数据映射策略**：\n\n```typescript\n// 安全的类型转换，处理可能的 undefined 值\nparties: (callData?.parties as unknown[]) || [],\ncontext: (callData?.context as unknown[]) || [],\ntrackers: (content?.trackers as unknown[]) || [],\n```\n\n资料来源：[apps/sim/lib/webhooks/providers/gong.ts:1-30]()\n\n### Typeform 连接器\n\nTypeform 连接器处理表单响应事件，支持可选的表单定义包含：\n\n```typescript\ninterface TypeformInput {\n event_id: string\n event_type: string\n form_id: string\n token: string\n submitted_at: string\n landed_at: string\n calculated: Record\n variables: unknown[]\n hidden: Record\n answers: unknown[]\n definition?: Record // 可选配置\n ending: Record\n raw: Record\n}\n```\n\n资料来源：[apps/sim/lib/webhooks/providers/typeform.ts:20-38]()\n\n### Vercel 连接器\n\nVercel 连接器处理部署相关事件，提取部署、项目和团队信息：\n\n```typescript\ninterface VercelDeployment {\n id: string\n url: string\n name: string\n meta: Record\n}\n\ninterface VercelProject {\n id: string\n name: string\n}\n\ninterface VercelTeam {\n id: string\n}\n```\n\n**对象安全转换模式**：\n\n```typescript\ndeployment && typeof deployment === 'object'\n ? {\n id: String((deployment as Record).id),\n url: ((deployment as Record).url as string) ?? '',\n }\n : null\n```\n\n资料来源：[apps/sim/lib/webhooks/providers/vercel.ts:1-60]()\n\n## 事件过滤机制\n\n连接器框架支持精细化的事件过滤控制，通过 `EventFilterContext` 上下文对象传递配置：\n\n```typescript\ninterface EventFilterContext {\n webhook: WebhookRecord\n body: Record\n requestId: string\n providerConfig: Record\n}\n```\n\n**过滤决策流程**：\n\n```mermaid\ngraph TD\n A[接收事件] --> B[提取 providerConfig]\n B --> C{检查配置条件}\n C -->|无过滤条件| D[处理事件]\n C -->|有过滤条件| E{条件匹配}\n E -->|匹配成功| D\n E -->|匹配失败| F[跳过事件]\n D --> G[触发工作流]\n F --> H[记录跳过日志]\n```\n\n## 与 Block 系统的集成\n\n连接器框架与 Sim 的 Block 系统紧密集成，实现工作流自动化：\n\n```mermaid\ngraph LR\n A[连接器 Provider] --> B[Block 输入转换]\n B --> C[工作流 Block 图]\n C --> D[执行引擎]\n D --> E[Block 输出]\n```\n\nBlock 系统通过以下方式使用连接器：\n\n1. **输入规范**：定义每个 Block 的输入 schema\n2. **类型验证**：使用 Zod 进行运行时验证\n3. **输出映射**：将 Block 执行结果映射为下游 Block 的输入\n\n资料来源：[apps/sim/blocks/index.ts](apps/sim/blocks/index.ts)\n\n## 订阅管理\n\n连接器框架支持动态订阅管理，允许在运行时创建和配置 webhook 订阅：\n\n```typescript\nasync createSubscription(ctx: SubscriptionContext): Promise {\n const config = getProviderConfig(ctx.webhook)\n const formId = config.formId as string | undefined\n const apiKey = config.apiKey as string | undefined\n // ... 配置验证和订阅创建逻辑\n}\n```\n\n## 错误处理策略\n\n| 错误类型 | 处理方式 | 返回状态 |\n|---------|---------|---------|\n| 认证失败 | 返回 401 | 拒绝请求 |\n| 配置缺失 | 记录警告日志 | 返回 undefined |\n| 格式转换错误 | 使用默认值 | 继续处理 |\n| 事件过滤 | 静默跳过 | 不触发工作流 |\n\n## 最佳实践\n\n### Provider 开发指南\n\n1. **类型安全**：始终使用类型断言和空值合并\n2. **默认字段**：为可选字段提供安全的默认值\n3. **日志记录**：在跳过事件时记录原因\n4. **错误恢复**：不要让 Provider 错误导致整个流程失败\n\n### 示例代码模式\n\n```typescript\n// 安全地从可能为 undefined 的嵌套对象中提取值\nconst value = \n (itemFields as Record)?.fieldName ||\n (itemFields as Record)?.['alternative-name'] ||\n ''\n```\n\n## 总结\n\nSim 的连接器框架提供了一套灵活且可扩展的集成机制，通过标准化的 Provider 接口实现了与多种外部服务的统一对接。该框架的核心优势包括：\n\n- **一致性**：统一的接口契约简化了新增 Provider 的工作\n- **安全性**：内置的认证验证机制确保了事件来源的可信性\n- **灵活性**：事件过滤机制允许精细化的控制\n- **可维护性**：类型安全的实现和清晰的代码结构便于长期维护\n\n---\n\n\n\n## 部署与基础设施\n\n### 相关页面\n\n相关主题：[项目概述](#page-project-overview), [系统架构](#page-system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [docker-compose.prod.yml](https://github.com/simstudioai/sim/blob/main/docker-compose.prod.yml)\n- [docker-compose.ollama.yml](https://github.com/simstudioai/sim/blob/main/docker-compose.ollama.yml)\n- [apps/sim/.env.example](https://github.com/simstudioai/sim/blob/main/apps/sim/.env.example)\n- [.devcontainer](https://github.com/simstudioai/sim/blob/main/.devcontainer)\n- [apps/docs/content/docs/en/self-hosting](https://github.com/simstudioai/sim/blob/main/apps/docs/content/docs/en/self-hosting)\n
\n\n# 部署与基础设施\n\n## 概述\n\nSim 是一个开源的工作流自动化平台，支持多种部署方式以满足不同规模和需求的场景。项目提供了从简单的本地开发部署到生产级 Kubernetes 集群部署的完整基础设施支持。\n\n部署架构的核心组件包括：\n\n- **应用服务**：基于 Next.js 构建的前后端一体化应用\n- **数据库**：PostgreSQL 12+ 配合 pgvector 扩展用于向量存储\n- **缓存层**：Redis 用于会话管理和实时功能\n- **容器化**：Docker 和 Docker Compose 简化部署流程\n- **编排**：Kubernetes Helm chart 支持生产级部署\n\n资料来源：[README.md](https://github.com/simstudioai/sim/blob/main/README.md)\n\n---\n\n## 部署方式\n\nSim 支持四种主要的部署方式，从简单到复杂依次为：NPM 包快速启动、Docker Compose 生产部署、手动开发和 Kubernetes 生产部署。\n\n### NPM 包快速部署\n\n最简单的方式是使用官方提供的 NPM 包，通过 Docker 自动拉取并运行 Sim：\n\n```bash\nnpx simstudio\n```\n\n默认访问地址为 http://localhost:3000\n\n资料来源：[README.md:8](https://github.com/simstudioai/sim/blob/main/README.md)\n\n**可用参数选项：**\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `-p, --port ` | 指定运行端口 | `3000` |\n| `--no-pull` | 跳过拉取最新 Docker 镜像 | `false` |\n\n使用示例：\n\n```bash\n# 指定端口\nnpx simstudio --port 8080\n\n# 跳过镜像拉取\nnpx simstudio --no-pull\n```\n\n> **前提条件**：必须安装并运行 Docker\n\n---\n\n### Docker Compose 生产部署\n\n对于生产环境，推荐使用 Docker Compose 进行部署，该方式提供完整的服务栈和持久化存储。\n\n```bash\ngit clone https://github.com/simstudioai/sim.git && cd sim\ndocker compose -f docker-compose.prod.yml up -d\n```\n\n资料来源：[README.md:19-22](https://github.com/simstudioai/sim/blob/main/README.md)\n\n**Docker Compose 生产架构图：**\n\n```mermaid\ngraph TD\n subgraph \"Docker Compose Stack\"\n A[用户访问] --> B[NGINX Reverse Proxy]\n B --> C[Sim App Container]\n C --> D[(PostgreSQL + pgvector)]\n C --> E[(Redis Cache)]\n C --> F[File Storage]\n end\n```\n\n**生产部署包含的服务：**\n\n- Sim 应用容器\n- PostgreSQL 数据库（带 pgvector 扩展）\n- Redis 缓存服务\n- 文件存储卷\n\n---\n\n### 本地模型支持\n\nSim 支持通过 Ollama 和 vLLM 连接本地大语言模型，适用于对数据隐私有要求或希望降低 API 成本的场景。\n\n使用 Ollama 部署：\n\n```bash\ndocker compose -f docker-compose.ollama.yml up -d\n```\n\n资料来源：[README.md:29](https://github.com/simstudioai/sim/blob/main/README.md)\n\n**Ollama 部署架构：**\n\n```mermaid\ngraph LR\n A[Sim App] -->|API 调用| B[Ollama Service]\n B --> C[本地 LLM Model]\n C -->|推理结果| B\n B -->|返回结果| A\n```\n\n支持的本地模型功能：\n\n- Ollama 本地模型推理\n- vLLM 高性能推理服务\n- 自定义模型接入\n\n详细的本地模型配置请参考 [Docker 自托管文档](https://docs.sim.ai/self-hosting/docker)。\n\n---\n\n### Kubernetes Helm 部署\n\n对于大规模生产环境，Sim 提供了完整的 Helm Chart 用于 Kubernetes 集群部署。\n\n**基础安装：**\n\n```bash\nhelm install sim ./helm/sim -n sim --create-namespace\n```\n\n**使用自定义值文件：**\n\n```bash\nhelm install sim ./helm/sim -n sim -f values.prod.yaml\n```\n\n资料来源：[helm/sim/README.md](https://github.com/simstudioai/sim/blob/main/helm/sim/README.md)\n\n---\n\n## 环境变量配置\n\nSim 使用环境变量进行配置管理。示例配置文件位于 `apps/sim/.env.example`。\n\n资料来源：[apps/sim/.env.example](https://github.com/simstudioai/sim/blob/main/apps/sim/.env.example)\n\n### 核心配置参数\n\n| 参数名 | 说明 | 必填 | 默认值 |\n|--------|------|------|--------|\n| `DATABASE_URL` | PostgreSQL 连接字符串 | 是 | - |\n| `REDIS_URL` | Redis 连接字符串 | 是 | - |\n| `NEXT_PUBLIC_APP_URL` | 应用公开访问 URL | 是 | - |\n| `OPENAI_API_KEY` | OpenAI API 密钥 | 否 | - |\n| `ANTHROPIC_API_KEY` | Anthropic API 密钥 | 否 | - |\n\n### Helm 全局参数\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `global.imageRegistry` | Docker 镜像仓库地址 | `docker.io` |\n| `global.imagePullSecrets` | 镜像拉取密钥名称 | `[]` |\n| `global.storageClass` | 存储类名称 | `\"\"` |\n| `global.commonLabels` | 通用标签 | `{}` |\n\n资料来源：[helm/sim/README.md](https://github.com/simstudioai/sim/blob/main/helm/sim/README.md)\n\n### 应用参数配置\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `app.enabled` | 启用主应用 | `true` |\n| `app.replicaCount` | 应用副本数 | `1` |\n| `app.image.repository` | 镜像仓库 | `simstudioai/sim` |\n| `app.image.tag` | 镜像标签 | `latest` |\n| `app.image.pullPolicy` | 镜像拉取策略 | `Always` |\n| `app.service.type` | 服务类型 | `ClusterIP` |\n| `app.service.port` | 服务端口 | `3000` |\n| `app.service.targetPort` | 容器目标端口 | `3000` |\n\n---\n\n## 系统要求\n\n### 基础环境要求\n\n| 组件 | 最低版本 | 推荐版本 |\n|------|----------|----------|\n| Docker | 最新稳定版 | 最新稳定版 |\n| Bun | - | 最新版本 |\n| Node.js | v20+ | v20 LTS |\n| PostgreSQL | 12+ | 15+ |\n| pgvector | 0.5+ | 最新版本 |\n\n资料来源：[README.md:32-33](https://github.com/simstudioai/sim/blob/main/README.md)\n\n### 手动部署前置步骤\n\n1. **克隆代码库：**\n\n```bash\ngit clone https://github.com/simstudioai/sim.git\ncd sim\n```\n\n2. **安装依赖：**\n\n```bash\nbun install\nbun run prepare # 设置 pre-commit hooks\n```\n\n3. **配置 PostgreSQL 数据库：**\n\n```bash\ndocker run --name simstudio-db \\\n -e POSTGRES_PASSWORD=your_password \\\n -e POSTGRES_DB=simstudio \\\n -p 5432:5432 \\\n -d \\\n pgvector/pgvector:pg15\n```\n\n4. **配置环境变量：**\n\n复制并编辑环境变量文件：\n\n```bash\ncp apps/sim/.env.example apps/sim/.env\n# 编辑 .env 文件填入实际配置\n```\n\n---\n\n## 开发环境配置\n\n项目支持使用 VS Code Dev Container 进行标准化开发环境配置。\n\n资料来源：[.devcontainer](https://github.com/simstudioai/sim/blob/main/.devcontainer)\n\n### Dev Container 优势\n\n- 开箱即用的标准化开发环境\n- 预配置所有依赖项\n- 与主机隔离，避免环境污染\n- 团队成员环境一致性保证\n\n### 启动开发容器\n\n1. 确保已安装 VS Code 和 Docker\n2. 在 VS Code 中打开项目文件夹\n3. 安装 \"Dev Containers\" 扩展\n4. 点击右下角提示 \"Reopen in Container\"\n5. 等待容器构建完成\n\n---\n\n## 负载测试配置\n\n项目包含用于验证部署性能的负载测试脚本，位于 `scripts/load/` 目录。\n\n资料来源：[apps/sim/package.json](https://github.com/simstudioai/sim/blob/main/apps/sim/package.json)\n\n### 可用的负载测试命令\n\n| 命令 | 说明 |\n|------|------|\n| `load:workflow:waves` | 波次式负载测试 |\n| `load:workflow:isolation` | 隔离工作空间负载测试 |\n\n### 波次式负载测试参数\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `BASE_URL` | 测试目标地址 | `http://localhost:3000` |\n| `WAVE_ONE_DURATION` | 第一波次持续时间（秒） | 20 |\n| `WAVE_ONE_RATE` | 第一波次请求速率 | 10 |\n| `WAVE_TWO_DURATION` | 第二波次持续时间（秒） | 20 |\n| `WAVE_TWO_RATE` | 第二波次请求速率 | 10 |\n| `WAVE_THREE_DURATION` | 第三波次持续时间（秒） | 20 |\n| `WAVE_THREE_RATE` | 第三波次请求速率 | 10 |\n\n运行示例：\n\n```bash\nBASE_URL=http://production-server:3000 bunx artillery run scripts/load/workflow-waves.yml\n```\n\n---\n\n## 安全配置\n\n### 主机名验证\n\n项目实现了 SSRF（服务器端请求伪造）防护机制，通过 `validateHostname` 函数验证目标主机名。\n\n资料来源：[apps/sim/lib/core/security/input-validation.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/core/security/input-validation.ts)\n\n**验证功能：**\n\n- 检查是否为私有 IP 地址\n- 阻止本地主机访问\n- 过滤保留地址和特殊地址\n\n```typescript\nexport function validateHostname(\n hostname: string | null | undefined,\n paramName = 'hostname'\n): ValidationResult {\n // 实现主机名安全性验证\n}\n```\n\n### Webhook 安全验证\n\n项目实现了待验证 Webhook 的安全处理机制，支持多种提供商的事件验证。\n\n资料来源：[apps/sim/lib/webhooks/pending-verification.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/pending-verification.ts)\n\n支持的提供商包括：\n\n- Ashby\n- Grain\n- Salesforce\n- Generic (通用)\n\n---\n\n## 构建与部署流程\n\n### 应用构建\n\n```bash\n# 标准构建\nbun run build\n\n# 仅构建沙箱bundles\nbun run build:sandbox-bundles\n```\n\n资料来源：[apps/sim/package.json](https://github.com/simstudioai/sim/blob/main/apps/sim/package.json)\n\n### 构建流程架构\n\n```mermaid\ngraph LR\n A[源码] --> B[bun run build:sandbox-bundles]\n B --> C[沙箱Bundle生成]\n C --> D[Next.js Build]\n D --> E[Docker Image]\n E --> F[Container Registry]\n```\n\n### 代码质量检查\n\n| 命令 | 说明 |\n|------|------|\n| `lint` | 运行 Biome 代码检查并自动修复 |\n| `lint:check` | 仅检查不修复 |\n| `format` | 运行代码格式化 |\n| `format:check` | 仅检查格式 |\n| `type-check` | TypeScript 类型检查 |\n\n---\n\n## 部署最佳实践\n\n### 生产环境检查清单\n\n- [ ] 使用 Docker Compose 或 Kubernetes 进行部署\n- [ ] 配置 PostgreSQL 外部持久化存储\n- [ ] 启用 Redis 缓存集群\n- [ ] 配置环境变量而非硬编码配置\n- [ ] 设置适当的副本数和资源限制\n- [ ] 配置健康检查探针（liveness/readiness）\n- [ ] 设置安全的镜像拉取策略\n- [ ] 配置日志收集和监控\n\n### 推荐配置示例\n\n```yaml\n# values.prod.yaml\napp:\n replicaCount: 3\n resources:\n limits:\n cpu: \"2000m\"\n memory: \"4Gi\"\n requests:\n cpu: \"1000m\"\n memory: \"2Gi\"\n livenessProbe:\n httpGet:\n path: /api/health\n port: 3000\n initialDelaySeconds: 30\n periodSeconds: 10\n```\n\n---\n\n## 相关文档\n\n- [官方自托管文档](https://docs.sim.ai/self-hosting/docker)\n- [Ollama 集成指南](https://docs.sim.ai/self-hosting/docker)\n- [vLLM 配置说明](https://docs.vllm.ai/)\n- [Helm Chart 完整配置](https://github.com/simstudioai/sim/blob/main/helm/sim/README.md)\n\n---\n\n\n\n## 扩展与定制\n\n### 相关页面\n\n相关主题：[块系统与注册表](#page-block-registry), [连接器框架](#page-connectors)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [apps/sim/blocks/blocks/custom](https://github.com/simstudioai/sim/blob/main/apps/sim/blocks/blocks/custom)\n- [apps/sim/api/tools/custom/route.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/api/tools/custom/route.ts)\n- [apps/sim/app/api/mcp](https://github.com/simstudioai/sim/blob/main/apps/sim/app/api/mcp)\n- [apps/sim/app/api/copilot](https://github.com/simstudioai/sim/blob/main/apps/sim/app/api/copilot)\n- [apps/sim/ee](https://github.com/simstudioai/sim/blob/main/apps/sim/ee)\n- [.agents/skills](https://github.com/simstudioai/sim/blob/main/.agents/skills)\n- [scripts/generate-docs.ts](https://github.com/simstudioai/sim/blob/main/scripts/generate-docs.ts)\n- [apps/sim/lib/workflows/triggers/triggers.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/triggers/triggers.ts)\n- [apps/sim/lib/api/contracts/types.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/api/contracts/types.ts)\n- [apps/sim/lib/webhooks/pending-verification.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/pending-verification.ts)\n
\n\n# 扩展与定制\n\n## 概述\n\nSim 平台提供了丰富的扩展与定制机制，允许开发者在多个层面自定义和扩展系统功能。这些扩展点包括自定义块（Custom Blocks）、API 路由扩展、Webhook 集成、MCP（Model Context Protocol）扩展以及 Copilot 扩展。Sim 的设计理念强调模块化和可插拔性，使得开发者能够根据业务需求灵活地添加新功能，同时保持核心系统的稳定性和一致性。\n\n扩展机制的核心架构遵循以下原则：首先，所有扩展都通过标准化的接口定义进行注册和管理；其次，扩展遵循统一的数据模型和类型系统；最后，扩展可以访问相同的核心服务和工具函数库。这种设计确保了扩展与核心系统之间的高度兼容性，同时也便于维护和升级。\n\nSim 的扩展系统还支持自动化文档生成，通过 `scripts/generate-docs.ts` 脚本可以扫描块目录并提取元数据，自动生成标准化的 Markdown 文档。文档生成器会扫描 `apps/sim/blocks/blocks/` 目录，提取每个块的名称、描述、分类、输入输出规范以及配置参数，然后更新导航元数据文件。这种自动化机制确保了文档与代码的同步更新，减少了人工维护的工作量。\n\n## 自定义块系统\n\n### 块结构与定义\n\n自定义块是 Sim 平台扩展的基本单元，每个块都遵循统一的定义规范。块的定义包括元数据（名称、描述、分类）、输入输出规格以及配置参数。块的元数据存储在定义文件中，文档生成器会扫描这些文件并提取相关信息。块的分类决定了其在工作流设计器中的展示位置和分组方式，常见的分类包括触发器（triggers）、工具（tools）、转换器（transformers）等。\n\n块系统支持多种类型的输入输出连接，包括字符串、数字、布尔值、数组、对象等数据类型。每个块可以定义多个输入端口和输出端口，端口之间的连接遵循类型兼容性规则。块的配置参数允许用户在实例化块时指定行为选项，这些参数在运行时被读取并传递给块的执行逻辑。\n\n### 自定义块注册\n\n自定义块的注册通过 `@/blocks` 模块进行管理，该模块提供了获取块、获取所有块、获取块类型等接口。块的注册表（registry）存储了所有可用块的引用，开发者可以通过 `getBlock` 函数根据块类型获取块定义，通过 `getBlocksByCategory` 函数获取特定分类下的所有块。块的验证通过 `isValidBlockType` 函数进行，确保只有注册的有效块类型才能在工作流中使用。\n\n块的注册过程还支持按工具名称查找，通过 `getBlockByToolName` 函数可以根据工具的别名获取对应的块定义。这种设计使得块的定义与外部工具名称解耦，便于在不影响现有工作流的情况下替换或升级底层实现。块的注册表还支持动态更新，允许在运行时添加或移除块类型。\n\n### 块的执行与输出\n\n块的执行由执行器（executor）统一管理，执行器负责解析工作流、调度块执行、处理依赖关系以及收集输出。执行器提供了块输出处理模块（block-outputs），用于计算每个块的有效输出。有效输出的计算考虑了前置块的条件分支和循环结构，确保只有实际执行的块才会产生输出。\n\n块的输出格式遵循统一的数据结构，包括输出值、元数据、错误信息等字段。输出处理模块支持注释模式（annotation-only mode），在这种模式下块不会产生实际的执行结果，只记录执行信息。这种机制用于调试和性能分析，帮助开发者理解工作流的执行过程和性能瓶颈。\n\n```mermaid\ngraph TD\n A[工作流定义] --> B[块注册表]\n B --> C[块执行器]\n C --> D[依赖解析]\n D --> E[块执行]\n E --> F[输出收集]\n F --> G[结果聚合]\n C --> H[块输出处理]\n H --> I[有效输出计算]\n I --> G\n```\n\n## API 扩展机制\n\n### 路由合约系统\n\nSim 的 API 扩展基于类型安全的路由合约系统，该系统定义在 `apps/sim/lib/api/contracts/types.ts` 中。路由合约（ApiRouteContract）是一个泛型类型，包含参数（params）、查询（query）、请求体（body）、请求头（headers）、响应模式（response mode）以及响应定义（response）等六个维度的类型信息。这种设计确保了 API 的输入输出在整个应用中都遵循一致的类型约束。\n\n路由合约系统提供了多个辅助类型来提取合约中的特定部分：`ContractParams` 用于提取参数类型，`ContractQuery` 用于提取查询参数类型，`ContractBody` 用于提取请求体类型，`ContractHeaders` 用于提取请求头类型。这些辅助类型通过 TypeScript 的条件类型（conditional types）实现，能够在编译时从合约定义中提取出对应的类型信息。\n\n响应模式支持两种类型：JSON 模式和流模式（stream mode）。JSON 模式适用于小规模的、结构化的响应数据，而流模式适用于需要逐步返回大量数据或实时更新场景的 API。路由合约的响应定义使用 Zod schema 进行声明式验证，确保 API 的响应符合预期的数据结构。\n\n### 自定义 API 路由\n\n自定义 API 路由位于 `apps/sim/api/tools/custom/route.ts`，开发者可以在此目录下添加新的 API 端点。路由文件遵循 Next.js 的 API 路由规范，每个文件导出一个或多个 HTTP 方法处理器（GET、POST、PUT、DELETE 等）。路由处理器接收请求上下文，包括请求参数、查询字符串、请求体和请求头，然后执行业务逻辑并返回响应。\n\n自定义路由的开发流程包括：定义路由合约、指定请求处理逻辑、注册路由到应用。对于需要认证的路由，路由处理器可以通过中间件机制注入认证信息。对于需要访问数据库的路由，路由处理器通过依赖注入获取数据库连接实例。这种设计保持了路由逻辑的纯净性，便于单元测试和代码复用。\n\nAPI 路由的验证层自动使用合约定义中的 schema 进行输入验证，验证失败时返回标准化的错误响应。验证包括类型检查、格式验证、范围验证以及自定义验证规则。验证规则的定义使用 Zod 库，支持链式调用和复合条件，使得复杂的数据验证逻辑易于表达和维护。\n\n### Confluence 工具集成\n\nSim 提供了与 Atlassian Confluence 的深度集成，作为 API 扩展的一部分。Confluence 相关的路由定义位于 `apps/sim/lib/api/contracts/selectors/confluence.ts`，包括空间选择器（spaces selector）、页面选择器（pages selector）和页面详情获取等端点。这些端点提供了统一的接口来查询和操作 Confluence 内容。\n\nConfluence 路由使用通用的响应类型（`z.unknown()`），因为不同的 Confluence API 端点返回的数据结构差异较大。这种设计提供了灵活性，允许调用方处理任意形状的响应数据。路由合约定义了查询参数和请求体的 schema，但响应数据保持无类型状态，由调用方负责解析和处理。\n\nConfluence 集成支持分页查询，返回结果包含数据数组和游标（cursor）信息。调用方可以使用游标进行后续查询，实现大结果集的遍历。空间选择器返回空间列表和可选的下一页游标，页面选择器返回文件列表，每个文件包含标识符和名称等基本信息。\n\n## Webhook 集成系统\n\n### Webhook 提供者架构\n\nSim 的 Webhook 系统支持多个第三方服务的集成，包括 Gong、Webflow、Vercel、Typeform 等。每个提供者（provider）实现统一的接口，提供事件解析、数据转换、认证验证和事件过滤等功能。提供者架构定义在 `apps/sim/lib/webhooks/` 目录下，每个提供者位于独立的子目录中。\n\nWebhook 处理流程包括接收请求、验证签名、解析事件、过滤事件、转换数据和触发工作流等步骤。每个步骤都可以由提供者自定义实现，以适应不同服务的特性。例如，Gong 提供者可能需要提取通话相关的元数据，而 Webflow 提供者可能需要处理 CMS 内容更新事件。\n\n### 事件过滤机制\n\n事件过滤是 Webhook 集成的关键功能，用于避免处理不相关的事件。每个提供者可以实现 `shouldSkipEvent` 方法，根据事件内容决定是否跳过处理。过滤条件通常基于配置参数，例如 Webflow 提供者可以根据配置的集合标识符（collectionId）过滤事件，只处理指定集合的更新。\n\n过滤逻辑的执行发生在事件解析之后、工作流触发之前，这样可以确保过滤决策基于完整的解析后数据。提供者接收事件上下文（EventFilterContext），包括 Webhook 配置、请求体和请求标识符等信息。过滤决策由同步函数执行，返回布尔值表示是否跳过该事件。\n\n### 待验证 Webhook 处理\n\n某些 Webhook 服务（如 Shopify、Webflow）要求接收方响应验证请求，以确认端点的有效性。Sim 实现了待验证 Webhook 处理机制，位于 `apps/sim/lib/webhooks/pending-verification.ts`。该机制支持多种验证协议，包括 GET 请求验证、HEAD 请求验证和 POST 请求验证。\n\n验证请求的存储使用 Redis 作为持久化后盾，同时维护内存缓存以提高查询性能。验证条目包含路径、过期时间和元数据，Redis 键使用前缀 `REDIS_KEY_PREFIX` 命名以避免与其他数据冲突。验证条目过期后自动从存储中移除，无需手动清理。\n\n支持的待验证 Webhook 提供者包括 Ashby、Grain、Generic 和 Salesforce。每个提供者定义匹配器（matcher），用于判断请求是否属于待验证请求。匹配器检查请求方法、请求体结构和特定字段值。例如，Generic 提供者的匹配规则是：GET 或 HEAD 请求，或者空请求体的 POST 请求。\n\n## MCP 扩展\n\n### MCP 协议概述\n\nMCP（Model Context Protocol）是一种用于扩展 AI 模型能力的协议标准，Sim 通过 `apps/sim/app/api/mcp` 端点提供 MCP 支持。MCP 扩展允许外部系统通过标准化接口调用 Sim 的功能，同时支持工具注册、资源访问和提示模板等功能。MCP 协议采用 JSON-RPC 格式进行通信，支持请求-响应和通知两种消息模式。\n\nMCP 扩展的核心组件包括：工具注册表、资源管理器、提示引擎和会话管理器。工具注册表维护所有可用 MCP 工具的定义，包括工具名称、描述、参数 schema 和返回值类型。资源管理器提供对 Sim 内部数据的受控访问，支持基于权限的数据隔离。提示引擎允许调用方定义和复用复杂的提示模板。\n\n### MCP 端点实现\n\nMCP 端点实现遵循 JSON-RPC 2.0 规范，支持 `initialize`、`tools/list`、`tools/call`、`resources/list`、`resources/read` 等标准方法。端点接收 JSON-RPC 请求，执行对应的处理逻辑，并返回 JSON-RPC 响应。错误响应包含错误代码、消息和可选的附加数据。\n\n工具调用是 MCP 扩展的核心功能，允许外部系统触发 Sim 中的工作流或执行特定操作。工具调用请求包含工具名称和参数对象，响应包含执行结果或错误信息。工具调用的执行由工作流执行引擎驱动，支持同步和异步两种执行模式。异步执行模式返回任务标识符，调用方可以通过任务标识符查询执行状态和结果。\n\n### MCP 工具定义\n\nMCP 工具的定义存储在配置文件中，定义了工具的元数据和行为规范。每个工具定义包括唯一标识符、显示名称、描述文本、参数 schema 和返回值 schema。参数 schema 使用 JSON Schema 格式，支持必填参数、可选参数、类型约束和默认值等特性。\n\n工具定义的版本管理支持向后兼容性，工具实现可以识别旧版本的参数并提供兼容处理。工具的参数验证在执行前进行，验证失败时返回明确的错误信息，指导调用方提供正确的参数。工具的返回值类型在工具定义中声明，调用方可以依赖这些信息进行类型安全的响应处理。\n\n## Copilot 扩展\n\n### Copilot 集成架构\n\nCopilot 扩展提供与 AI 编程助手的功能集成，位于 `apps/sim/app/api/copilot` 端点。Copilot 集成允许 AI 模型访问 Sim 的上下文信息，包括工作流定义、块配置、执行历史等。这种集成使得 AI 模型能够基于实际的项目上下文生成更准确的建议和代码。\n\nCopilot 扩展采用插件架构，核心系统提供基础接口，扩展模块实现具体的 AI 提供者适配。当前实现支持主流的 AI 提供者，包括 OpenAI、Anthropic 和本地模型服务。每个提供者适配器处理认证、请求格式化和响应解析等细节，使得上层逻辑与具体的 AI 服务解耦。\n\n### 上下文管理\n\nCopilot 扩展的上下文管理模块负责收集和组织传递给 AI 模型的信息。上下文信息来源包括：工作流配置、块定义、变量值、用户偏好和历史交互等。上下文信息的收集遵循最小必要原则，避免传递过多无关信息影响 AI 模型的处理效率和响应质量。\n\n上下文信息的组织采用分层结构，包括全局上下文、工作流上下文和块级上下文三个层次。全局上下文包含项目级别的通用信息，工作流上下文包含特定工作流的配置和状态，块级上下文包含单个块的详细信息。分层组织便于 AI 模型根据需要访问不同范围的信息。\n\n### 建议生成与执行\n\nCopilot 扩展的建议生成功能基于上下文信息和用户请求，生成工作流配置建议、块参数建议和优化建议等。建议的生成由 AI 模型驱动，模型根据上下文推理出最可能的用户意图，然后生成相应的建议内容。建议的格式可以是完整的配置片段，也可以是增量修改指令。\n\n建议的执行支持预览和确认机制，用户可以在执行前预览建议的效果，确认无误后再应用到实际的工作流中。执行过程记录在审计日志中，便于追踪建议的来源和执行结果。Copilot 扩展还支持反馈收集，用户可以对建议的质量进行评分，评分信息用于持续改进建议生成模型。\n\n## 触发器系统\n\n### 触发器类型\n\n触发器是工作流的入口点，决定了工作流何时以及如何被激活。Sim 支持多种触发器类型，包括手动触发（manual）、API 触发（api）、聊天触发（chat）和定时触发（scheduled）。触发器类型的识别通过 `TRIGGER_TYPES` 常量和 `classifyStartBlockType` 函数实现，支持新的显式分类方式和旧版的触发模式标记。\n\n触发器类型的分类逻辑首先检查块配置中的分类是否为 'triggers'，然后检查块是否启用了 `triggerMode` 标记，最后检查块类型是否为遗留的起始块（starter block）。这种多层检查确保了向后兼容性，同时支持新的触发器设计模式。\n\n### 触发器引用别名\n\n触发器引用别名机制允许在工作流中使用简短的别名来引用触发器类型。`TRIGGER_REFERENCE_ALIAS_MAP` 定义了别名到具体触发器类型的映射，包括 `start`、`api`、`chat` 和 `manual` 四个别名。这些别名用于内联引用，格式为 ``、`` 等。\n\n别名映射的设计简化了工作流的编写，用户无需记忆完整的触发器类型标识符。别名到类型的映射是单向的，具体类型到别名的反向映射需要额外实现。别名机制还支持自定义扩展，开发者可以在映射表中添加新的别名和对应的触发器类型。\n\n### 触发器工具函数\n\n`TriggerUtils` 类提供了一系列工具函数用于操作和检查触发器。`isTriggerBlock` 函数判断给定的块是否是触发器类型，检查逻辑包括分类、模式和旧版标识三个维度。`isTriggerType` 函数判断块是否属于特定的触发器类型，接收块对象和目标类型作为参数。\n\n触发器输出（trigger outputs）由 `getTriggerOutputs` 函数获取，返回触发器块产生的输出数据。这些输出数据可以在后续的块中使用，传递触发事件的相关信息，例如 Webhook 请求内容、API 调用参数或定时触发的时间戳等。输出数据的格式和内容取决于触发器类型和配置。\n\n```mermaid\ngraph TD\n A[触发事件] --> B{触发器类型判断}\n B -->|manual| C[手动触发器]\n B -->|api| D[API 触发器]\n B -->|chat| E[聊天触发器]\n B -->|scheduled| F[定时触发器]\n C --> G[读取子块配置]\n D --> G\n E --> G\n F --> G\n G --> H[返回触发模式]\n H --> I[startWorkflow 子块]\n I --> J[触发器输出]\n```\n\n## 企业扩展（EE）\n\n### 企业功能架构\n\n企业扩展（Enterprise Edition）模块位于 `apps/sim/ee` 目录，提供面向大规模部署和企业级应用的增强功能。企业扩展包括高级安全特性、审计日志、细粒度权限控制、高可用部署支持等功能。这些功能面向有严格合规要求和运营标准的企业客户。\n\n企业扩展的设计遵循模块化原则，核心功能与扩展功能分离部署。企业功能可以作为独立模块启用或禁用，不需要修改核心代码。这种设计降低了企业的使用门槛，同时保持了核心系统的简洁性。企业功能的配置通过环境变量和管理界面进行，支持动态生效。\n\n### 企业级 API\n\n企业扩展提供了增强的 API 接口，包括批量操作支持、异步处理能力和高级过滤选项。批量操作 API 允许一次请求处理多个资源，适用于数据迁移和批量配置等场景。异步处理 API 返回任务标识符，调用方可以轮询或等待任务完成通知。\n\n企业 API 的认证机制支持多种协议，包括 OAuth 2.0、SAML 和 LDAP。企业 API 的限流策略比标准 API 更宽松，但需要额外的配额管理机制。配额信息通过 `UsageLimits` 接口获取，包括同步限流、异步限流、当前使用量和限额等信息。\n\n## 技能系统\n\n### 技能定义与注册\n\n技能（Skills）系统位于 `.agents/skills` 目录，定义了 AI 代理可以执行的操作集合。技能是比块更高级的抽象，一个技能可能由多个块组成，形成完整的操作流程。技能的注册和管理由技能引擎处理，支持技能的发现、调用和监控。\n\n技能定义包含技能标识符、名称、描述、参数定义、返回值定义和实现代码。参数和返回值使用类型化的 schema 定义，支持复杂的嵌套结构和自定义验证规则。实现代码支持多种语言和执行环境，包括 JavaScript、Python 和 Shell 脚本等。\n\n### 技能编排\n\n技能的编排功能允许组合多个技能形成更复杂的操作序列。编排支持顺序执行、并行执行和条件分支三种基本模式。顺序执行按照定义的顺序依次调用技能，前一个技能的输出作为后一个技能的输入。并行执行同时调用多个技能，提高执行效率，适用于独立的操作。\n\n条件分支根据中间结果决定后续执行的技能路径。条件表达式支持简单的比较操作和复杂的布尔逻辑。编排的执行由编排引擎驱动，引擎负责管理执行上下文、处理异常和维护执行状态。编排失败时支持回滚操作，恢复到执行前的状态。\n\n## 测试与验证框架\n\n### 测试工具库\n\nSim 提供了完整的测试工具库，位于 `packages/testing/src` 目录。测试工具库包括环境变量模拟（env mock）、数据库模拟、网络请求模拟等功能。环境变量模拟（`createEnvMock`）允许测试用例覆盖和恢复环境变量值，支持字符串、数字和布尔值类型的模拟。\n\n环境变量模拟提供了多种辅助函数：`getEnv` 返回模拟的值，`isTruthy` 判断真值，`isFalsy` 判断假值，`envNumber` 解析数字并支持最小值约束。这些辅助函数覆盖了环境变量处理的各种场景，确保测试用例能够模拟真实的运行环境。\n\n### 模拟与存根\n\n测试工具库提供了完善的模拟和存根功能，用于隔离被测试代码的依赖。模拟（mock）替换整个模块的实现，存根（stub）替换特定的函数或方法。模拟和存根的配置通过工厂函数创建，支持默认行为定义和行为覆盖。\n\n测试工具库还提供了预设的模拟集合（`envMock`），可以直接用于常见的测试场景。预设模拟包含合理的环境变量默认值，无需额外的配置即可在测试中使用。这种开箱即用的设计简化了测试用例的编写，同时保证了测试环境的一致性。\n\n### 集成测试支持\n\n集成测试支持模块提供了端到端的测试能力，包括 API 测试、Webhook 测试和工作流测试等。API 测试使用路由合约定义进行请求构造和响应验证，确保 API 的行为符合规范。Webhook 测试模拟外部服务的请求，验证 Webhook 处理器的解析和过滤逻辑。\n\n工作流测试支持完整的工作流执行模拟，包括触发器激活、块执行和输出收集等步骤。测试用例可以控制块的模拟返回值，验证工作流在各种输入条件下的行为。测试结果包括执行时间、块调用顺序和输出数据，便于分析工作流的性能和正确性。\n\n## 扩展开发最佳实践\n\n### 代码组织\n\n扩展代码应遵循统一的目录结构和命名约定。自定义块放在 `apps/sim/blocks/blocks/custom` 目录下，每个块独占一个子目录，目录名称使用 kebab-case 格式。块的定义文件使用 `index.ts` 命名，导出块的元数据和实现函数。\n\nAPI 扩展放在 `apps/sim/api/tools/custom` 目录下，遵循 Next.js 的 API 路由文件命名规范。路由文件使用 `route.ts` 命名，导出一个或多个 HTTP 方法处理器。相关的类型定义和工具函数放在同目录的 `*.ts` 文件中，与路由文件保持同级的组织关系。\n\n### 文档维护\n\n扩展开发者应维护清晰的代码文档，文档使用 JSDoc 格式编写。块定义需要包含名称、描述、输入输出说明和使用示例。API 路由需要包含端点说明、参数说明和响应示例。文档生成器会从代码注释中提取信息，自动生成用户文档。\n\n手动添加的文档内容应放在指定的区域，使用标记 `` 和 `` 包裹。文档生成器会保留手动添加的内容，不会被自动生成的内容覆盖。这种机制允许开发者在自动文档的基础上添加额外的说明、示例和注意事项。\n\n### 安全性考虑\n\n扩展开发应遵循安全最佳实践，避免引入安全漏洞。所有用户输入必须进行验证和清理，使用 Zod schema 或自定义验证函数。用户输入不应直接用于数据库查询或命令执行，应使用参数化查询和安全的 API 调用。\n\n敏感信息（如 API 密钥、访问令牌）不应硬编码在代码中，应使用环境变量或密钥管理服务。Webhook 处理应验证请求签名，防止伪造请求攻击。API 端点应实现适当的限流和认证机制，防止滥用和未授权访问。\n\n## 配置选项参考\n\n| 配置类别 | 选项名称 | 类型 | 默认值 | 说明 |\n|---------|---------|------|--------|------|\n| 构建 | `NODE_OPTIONS` | string | `--max-old-space-size=8192` | Node.js 运行时选项 |\n| 构建 | `build:sandbox-bundles` | command | - | 沙箱包构建命令 |\n| 测试 | `test` | command | `vitest run` | 测试运行命令 |\n| 测试 | `test:coverage` | command | `vitest run --coverage` | 覆盖率测试命令 |\n| 类型检查 | `type-check` | command | `tsc --noEmit` | TypeScript 类型检查 |\n| 格式 | `lint` | command | `biome check --write` | 代码检查和修复 |\n| 格式 | `format` | command | `biome format --write` | 代码格式化 |\n| 文档 | `generate-docs` | command | `bun run ../../scripts/generate-docs.ts` | 文档生成 |\n\n## 相关资源\n\n- 官方文档：https://docs.sim.ai\n- GitHub 仓库：https://github.com/simstudioai/sim\n- Docker 部署文档：https://docs.sim.ai/self-hosting/docker\n- 本地模型支持：Ollama（https://ollama.ai）、vLLM（https://docs.vllm.ai/）\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：simstudioai/sim\n\n摘要：发现 20 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 社区讨论暴露的待验证问题：Open-source general purpose agent with built-in MCPToolkit support。\n\n## 1. 安装坑 · 社区讨论暴露的待验证问题：Open-source general purpose agent with built-in MCPToolkit support\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：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.\n- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。\n- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。\n- 证据：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\n\n## 2. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | host_targets=cursor\n\n## 3. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | README/documentation is current enough for a first validation pass.\n\n## 4. 运行坑 · 来源证据：v0.6.63\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.6.63\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5a97e1d742fe4d7f918e0b42f27b87c3 | https://github.com/simstudioai/sim/releases/tag/v0.6.63 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 5. 运行坑 · 来源证据：v0.6.65\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.6.65\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_03f18559029c4724b11011ef96259161 | https://github.com/simstudioai/sim/releases/tag/v0.6.65 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 运行坑 · 来源证据：v0.6.67\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.6.67\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_048d1506c1d645b0be435841a26b93ed | https://github.com/simstudioai/sim/releases/tag/v0.6.67 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 运行坑 · 来源证据：v0.6.73\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.6.73\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_048864e1cdcc44d2b2a30917b7c4adc2 | https://github.com/simstudioai/sim/releases/tag/v0.6.73 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 维护坑 · 来源证据：v0.6.71\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v0.6.71\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9c30d794fb7344489f96a6ac47cd1d6e | https://github.com/simstudioai/sim/releases/tag/v0.6.71 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | last_activity_observed missing\n\n## 10. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 12. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 来源证据：Unable to Access Files from Private GitHub Repository in Self-Hosted Setup\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Unable to Access Files from Private GitHub Repository in Self-Hosted Setup\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ed1c9f64533441f5826c1fe98fa9ce49 | https://github.com/simstudioai/sim/issues/4555 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 14. 安全/权限坑 · 来源证据：v0.6.64\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.6.64\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5e2aa5311b1748cea446771920242668 | https://github.com/simstudioai/sim/releases/tag/v0.6.64 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 15. 安全/权限坑 · 来源证据：v0.6.66\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.6.66\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7d42c79fecf54003b117f76d49873223 | https://github.com/simstudioai/sim/releases/tag/v0.6.66 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：v0.6.68\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.6.68\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c8fe17ce7ba6424c88017ed644620915 | https://github.com/simstudioai/sim/releases/tag/v0.6.68 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：v0.6.69\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.6.69\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a47b6988921146ac8fa66d73b0574c88 | https://github.com/simstudioai/sim/releases/tag/v0.6.69 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：v0.6.72\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.6.72\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f13817452da14b5d97c64bde45647685 | https://github.com/simstudioai/sim/releases/tag/v0.6.72 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 19. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | issue_or_pr_quality=unknown\n\n## 20. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | release_recency=unknown\n\n\n", "markdown_key": "sim", "pages": "draft", "source_refs": [ { "evidence_id": "art_4c769793e2db44b09c3ad8f55672a2ea", "kind": "docs", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/simstudioai/sim#readme" } ], "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "sim 说明书", "toc": [ "https://github.com/simstudioai/sim 项目说明书", "目录", "项目概述", "1. 项目简介", "2. 技术架构", "3. 核心功能模块", "4. SDK 文档", "5. 部署方式", "Doramagic 踩坑日志" ] } }, "quality_gate": { "blocking_gaps": [], "category_confidence": "medium", "compile_status": "ready_for_review", "five_assets_present": true, "install_sandbox_verified": true, "missing_evidence": [], "next_action": "publish to Doramagic.ai project surfaces", "prompt_preview_boundary_ok": true, "publish_status": "publishable", "quick_start_verified": true, "repo_clone_verified": true, "repo_commit": "dcaf3e98c132dedaa66490c0e63b6c3ff09aafdd", "repo_inspection_error": null, "repo_inspection_files": [ "package.json", "README.md", "packages/README.md", "packages/cli/package.json", "packages/cli/README.md", "packages/cli/tsconfig.json", "packages/testing/package.json", "packages/testing/tsconfig.json", "packages/audit/vitest.config.ts", "packages/audit/package.json", "packages/audit/tsconfig.json", "packages/workflow-authz/package.json", "packages/workflow-authz/tsconfig.json", "packages/tsconfig/library.json", "packages/tsconfig/package.json", "packages/tsconfig/nextjs.json", "packages/tsconfig/library-build.json", "packages/tsconfig/base.json", "packages/utils/vitest.config.ts", "packages/utils/package.json", "packages/utils/tsconfig.json", "packages/realtime-protocol/package.json", "packages/realtime-protocol/tsconfig.json", "packages/db/schema.ts", "packages/db/constants.ts", "packages/db/vitest.config.ts", "packages/db/index.ts", "packages/db/package.json", "packages/db/triggers.ts", "packages/db/tsconfig.json", "packages/db/drizzle.config.ts", "packages/python-sdk/setup.py", "packages/python-sdk/pyproject.toml", "packages/python-sdk/README.md", "packages/workflow-types/package.json", "packages/workflow-types/tsconfig.json", "packages/workflow-persistence/package.json", "packages/workflow-persistence/tsconfig.json", "packages/logger/vitest.config.ts", "packages/logger/package.json" ], "repo_inspection_verified": true, "review_reasons": [], "tag_count_ok": true, "unsupported_claims": [] }, "schema_version": "0.1", "user_assets": { "ai_context_pack": { "asset_id": "ai_context_pack", "filename": "AI_CONTEXT_PACK.md", "markdown": "# simstudio - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 simstudio 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`.agents/skills/add-block/SKILL.md`, `.agents/skills/add-connector/SKILL.md`, `.agents/skills/add-integration/SKILL.md`, `.agents/skills/add-tools/SKILL.md` 等 Claim：`clm_0004` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`.agents/skills/add-block/SKILL.md`, `.agents/skills/add-connector/SKILL.md`, `.agents/skills/add-integration/SKILL.md`, `.agents/skills/add-tools/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md`, `packages/cli/README.md`, `packages/python-sdk/README.md`, `packages/ts-sdk/README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `npx simstudio` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `git clone https://github.com/simstudioai/sim.git && cd sim` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `git clone https://github.com/simstudioai/sim.git` 证据：`README.md` Claim：`clm_0006` supported 0.86, `clm_0007` supported 0.86\n- `npm install -g simstudio` 证据：`packages/cli/README.md` Claim：`clm_0008` supported 0.86\n- `pip install simstudio-sdk` 证据：`packages/python-sdk/README.md` Claim：`clm_0009` supported 0.86\n- `pip install -e \".[dev]\"` 证据：`packages/python-sdk/README.md` Claim：`clm_0010` supported 0.86\n- `npm install simstudio-ts-sdk` 证据：`packages/ts-sdk/README.md` Claim：`clm_0011` supported 0.86\n- `yarn add simstudio-ts-sdk` 证据：`packages/ts-sdk/README.md` Claim：`clm_0012` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做权限沙盒试用\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：先做权限沙盒试用\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`.agents/skills/add-block/SKILL.md`, `.agents/skills/add-connector/SKILL.md`, `.agents/skills/add-integration/SKILL.md`, `.agents/skills/add-tools/SKILL.md` 等 Claim：`clm_0004` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.agents/skills/add-block/SKILL.md`, `.agents/skills/add-connector/SKILL.md`, `.agents/skills/add-integration/SKILL.md`, `.agents/skills/add-tools/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md`, `packages/cli/README.md`, `packages/python-sdk/README.md`, `packages/ts-sdk/README.md` Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0005` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.agents/skills/add-block/SKILL.md`, `.agents/skills/add-connector/SKILL.md`, `.agents/skills/add-integration/SKILL.md`, `.agents/skills/add-tools/SKILL.md` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`, `packages/cli/README.md`, `packages/python-sdk/README.md`, `packages/ts-sdk/README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.agents/skills/add-block/SKILL.md`, `.agents/skills/add-connector/SKILL.md`, `.agents/skills/add-integration/SKILL.md`, `.agents/skills/add-tools/SKILL.md` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`, `packages/cli/README.md`, `packages/python-sdk/README.md`, `packages/ts-sdk/README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0013` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md`, `packages/cli/README.md`, `packages/python-sdk/README.md`, `packages/ts-sdk/README.md` Claim：`clm_0014` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`.agents/skills/add-block/SKILL.md`, `.agents/skills/add-connector/SKILL.md`, `.agents/skills/add-integration/SKILL.md`, `.agents/skills/add-tools/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md`, `packages/cli/README.md`, `packages/python-sdk/README.md`, `packages/ts-sdk/README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：9590\n- 重要文件覆盖：40/9590\n- 证据索引条目：80\n- 角色 / Skill 条目：17\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 simstudio 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 simstudio 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 simstudio 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 17 个角色 / Skill / 项目文档条目。\n\n- **add-block**（skill）：Create or update a Sim integration block with correct subBlocks, conditions, dependsOn, modes, canonicalParamId usage, outputs, and tool wiring. Use when working on apps/sim/blocks/blocks/{service}.ts or aligning a block with its tools. 激活提示：当用户任务与“add-block”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/add-block/SKILL.md`\n- **add-connector**（skill）：Add or update a Sim knowledge base connector for syncing documents from an external source, including auth mode, config fields, pagination, document mapping, tags, and registry wiring. Use when working in apps/sim/connectors/{service}/ or adding a new external document source. 激活提示：当用户任务与“add-connector”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/add-connector/SKILL.md`\n- **add-integration**（skill）：Add a complete Sim integration from API docs, covering tools, block, icon, optional triggers, registrations, and integration conventions. Use when introducing a new service under apps/sim/tools , apps/sim/blocks , and apps/sim/triggers . 激活提示：当用户任务与“add-integration”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/add-integration/SKILL.md`\n- **add-tools**（skill）：Create or update Sim tool configurations from service API docs, including typed params, request mapping, response transforms, outputs, and registry entries. Use when working in apps/sim/tools/{service}/ or fixing tool definitions for an integration. 激活提示：当用户任务与“add-tools”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/add-tools/SKILL.md`\n- **add-trigger**（skill）：Create or update Sim webhook triggers using the generic trigger builder, service-specific setup instructions, outputs, and registry wiring. Use when working in apps/sim/triggers/{service}/ or adding webhook support to an integration. 激活提示：当用户任务与“add-trigger”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/add-trigger/SKILL.md`\n- **cleanup**（skill）：Run all code quality skills in sequence — effects, memo, callbacks, state, React Query, and emcn design review 激活提示：当用户任务与“cleanup”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/cleanup/SKILL.md`\n- **emcn-design-review**（skill）：Review UI code for alignment with the emcn design system — components, tokens, patterns, and conventions 激活提示：当用户任务与“emcn-design-review”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/emcn-design-review/SKILL.md`\n- **react-query-best-practices**（skill）：Audit React Query usage for best practices — key factories, staleTime, mutations, and server state ownership 激活提示：当用户任务与“react-query-best-practices”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/react-query-best-practices/SKILL.md`\n- **ship**（skill）：Commit, push, and open a PR to staging in one shot 激活提示：当用户任务与“ship”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/ship/SKILL.md`\n- **validate-connector**（skill）：Audit an existing Sim knowledge base connector against the service API docs and repository conventions, then report and fix issues in auth, config fields, pagination, document mapping, tags, and registry entries. Use when validating or repairing code in apps/sim/connectors/{service}/ . 激活提示：当用户任务与“validate-connector”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/validate-connector/SKILL.md`\n- **validate-integration**（skill）：Audit an existing Sim integration against the service API docs and repository conventions, then report and fix issues across tools, blocks, outputs, OAuth scopes, triggers, and registry entries. Use when validating or repairing a service integration under apps/sim/tools , apps/sim/blocks , or apps/sim/triggers . 激活提示：当用户任务与“validate-integration”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/validate-integration/SKILL.md`\n- **validate-trigger**（skill）：Audit an existing Sim webhook trigger against the service's webhook API docs and repository conventions, then report and fix issues across trigger definitions, provider handler, output alignment, registration, and security. Use when validating or repairing a trigger under apps/sim/triggers/{service}/ or apps/sim/lib/webhooks/providers/{service}.ts . 激活提示：当用户任务与“validate-trigger”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/validate-trigger/SKILL.md`\n- **you-might-not-need-a-callback**（skill）：Analyze and fix useCallback anti-patterns in your code 激活提示：当用户任务与“you-might-not-need-a-callback”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/you-might-not-need-a-callback/SKILL.md`\n- **you-might-not-need-a-memo**（skill）：Analyze and fix useMemo/React.memo anti-patterns in your code 激活提示：当用户任务与“you-might-not-need-a-memo”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/you-might-not-need-a-memo/SKILL.md`\n- **you-might-not-need-an-effect**（skill）：Analyze and fix useEffect anti-patterns in your code 激活提示：当用户任务与“you-might-not-need-an-effect”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/you-might-not-need-an-effect/SKILL.md`\n- **you-might-not-need-state**（skill）：Analyze and fix unnecessary useState, derived state, and server-state-in-local-state anti-patterns 激活提示：当用户任务与“you-might-not-need-state”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/you-might-not-need-state/SKILL.md`\n- **add-hosted-key**（skill）：Add hosted API key support to a tool so Sim provides the key when users don't bring their own. Use when adding hosted keys, BYOK support, hideWhenHosted, or hosted key pricing to a tool or block. 激活提示：当用户任务与“add-hosted-key”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.cursor/skills/add-hosted-key/SKILL.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **docs**（documentation）：This is a Next.js application generated with Create Fumadocs https://github.com/fuma-nama/fumadocs . 证据：`apps/docs/README.md`\n- **Sim Development Container**（documentation）：Development container configuration for VS Code Dev Containers and GitHub Codespaces. 证据：`.devcontainer/README.md`\n- **Sim Development Guidelines**（documentation）：You are a professional software engineer. All code must follow best practices: accurate, readable, clean, and efficient. 证据：`AGENTS.md`\n- **Sim Development Guidelines**（documentation）：You are a professional software engineer. All code must follow best practices: accurate, readable, clean, and efficient. 证据：`CLAUDE.md`\n- **Build Workflows with Ease**（documentation）：The open-source platform to build AI agents and run your agentic workforce. Connect 1,000+ integrations and LLMs to orchestrate agentic workflows. 证据：`README.md`\n- **Packages**（documentation）：Package Description --------- ------------- @sim/tsconfig ./tsconfig Shared TypeScript configs base, nextjs, library, library-build @sim/db ./db Database schema and Drizzle ORM utilities @sim/logger ./logger Structured logging with colored output @sim/testing ./testing Test factories, builders, and assertions 证据：`packages/README.md`\n- **Block Documentation Generator**（documentation）：This directory contains scripts to automatically generate documentation for all blocks in the Sim platform. 证据：`scripts/README.md`\n- **Sim App Scope**（documentation）：These rules apply to files under apps/sim/ in addition to the repository root AGENTS.md /AGENTS.md . 证据：`apps/sim/AGENTS.md`\n- **Blocks Scope**（documentation）：These rules apply to block definitions under apps/sim/blocks/ . 证据：`apps/sim/blocks/AGENTS.md`\n- **EMCN Components Scope**（documentation）：These rules apply to apps/sim/components/emcn/ . 证据：`apps/sim/components/emcn/AGENTS.md`\n- **Sim Enterprise Edition**（documentation）：This directory contains enterprise features that require a Sim Enterprise subscription for production use. 证据：`apps/sim/ee/README.md`\n- **Hooks Scope**（documentation）：These rules apply to custom hooks under apps/sim/ /hooks/ and apps/sim/ /use- .ts . 证据：`apps/sim/hooks/AGENTS.md`\n- **React Query Scope**（documentation）：These rules apply to apps/sim/hooks/queries/ . 证据：`apps/sim/hooks/queries/AGENTS.md`\n- **Guardrails Validators**（documentation）：Validation scripts for the Guardrails block. 证据：`apps/sim/lib/guardrails/README.md`\n- **Workflow Load Tests**（documentation）：These local-only Artillery scenarios exercise POST /api/workflows/ id /execute in async mode. 证据：`apps/sim/scripts/load/README.md`\n- **Stores Scope**（documentation）：These rules apply to Zustand stores under apps/sim/ /stores/ and apps/sim/ /store.ts . 证据：`apps/sim/stores/AGENTS.md`\n- **Tools Scope**（documentation）：These rules apply to integration tool definitions under apps/sim/tools/ . 证据：`apps/sim/tools/AGENTS.md`\n- **Triggers Scope**（documentation）：These rules apply to trigger definitions under apps/sim/triggers/ . 证据：`apps/sim/triggers/AGENTS.md`\n- **Sim Helm Chart**（documentation）：This Helm chart deploys Sim, a lightweight AI agent workflow platform, on Kubernetes. 证据：`helm/sim/README.md`\n- **Sim CLI**（documentation）：Sim CLI allows you to run Sim https://sim.ai using Docker with a single command. 证据：`packages/cli/README.md`\n- **Sim Python SDK**（documentation）：The official Python SDK for Sim https://sim.ai , allowing you to execute workflows programmatically from your Python applications. 证据：`packages/python-sdk/README.md`\n- **Sim TypeScript SDK**（documentation）：The official TypeScript/JavaScript SDK for Sim https://sim.ai , allowing you to execute workflows programmatically from your applications. 证据：`packages/ts-sdk/README.md`\n- **Package**（package_manifest）：{ \"name\": \"simstudio\", \"packageManager\": \"bun@1.3.13\", \"version\": \"0.0.0\", \"private\": true, \"license\": \"Apache-2.0\", \"workspaces\": \"apps/ \", \"packages/ \" , \"scripts\": { \"build\": \"turbo run build\", \"dev\": \"turbo run dev\", \"dev:sockets\": \"cd apps/realtime && bun run dev\", \"dev:full\": \"bunx concurrently -n \\\"App,Realtime\\\" -c \\\"cyan,magenta\\\" \\\"cd apps/sim && bun run dev\\\" \\\"cd apps/realtime && bun run dev\\\"\", \"test\": \"turbo run test\", \"format\": \"turbo run format\", \"format:check\": \"turbo run format:check\", \"lint\": \"turbo run lint\", \"lint:check\": \"turbo run lint:check\", \"lint:helm\": \"helm lint ./helm/sim --strict --values ./helm/sim/test/values-lint.yaml\", \"lint:all\": \"turbo run lint && bun run… 证据：`package.json`\n- **Contributing to Sim**（documentation）：Thank you for your interest in contributing to Sim! Our goal is to provide developers with a powerful, user-friendly platform for building, testing, and optimizing agentic workflows. We welcome contributions in all forms—from bug fixes and design improvements to brand-new features. 证据：`.github/CONTRIBUTING.md`\n- **Package**（package_manifest）：{ \"name\": \"docs\", \"version\": \"0.0.0\", \"private\": true, \"license\": \"Apache-2.0\", \"scripts\": { \"dev\": \"next dev --port 3001\", \"build\": \"fumadocs-mdx && NODE OPTIONS='--max-old-space-size=8192' next build\", \"start\": \"next start\", \"postinstall\": \"fumadocs-mdx\", \"type-check\": \"tsc --noEmit\", \"lint\": \"biome check --write --unsafe .\", \"lint:check\": \"biome check .\", \"format\": \"biome format --write .\", \"format:check\": \"biome format .\" }, \"dependencies\": { \"@sim/db\": \"workspace: \", \"@tabler/icons-react\": \"^3.31.0\", \"@vercel/og\": \"^0.6.5\", \"class-variance-authority\": \"^0.7.1\", \"clsx\": \"^2.1.1\", \"drizzle-orm\": \"^0.45.2\", \"fumadocs-core\": \"16.8.5\", \"fumadocs-mdx\": \"14.3.2\", \"fumadocs-openapi\": \"10.8.1\",… 证据：`apps/docs/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@sim/realtime\", \"version\": \"0.1.0\", \"private\": true, \"license\": \"Apache-2.0\", \"type\": \"module\", \"engines\": { \"bun\": \" =1.2.13\", \"node\": \" =20.0.0\" }, \"scripts\": { \"dev\": \"bun --watch src/index.ts\", \"start\": \"bun src/index.ts\", \"type-check\": \"tsc --noEmit\", \"lint\": \"biome check --write --unsafe .\", \"lint:check\": \"biome check .\", \"format\": \"biome format --write .\", \"format:check\": \"biome format .\", \"test\": \"vitest run\", \"test:watch\": \"vitest\" }, \"dependencies\": { \"@sim/audit\": \"workspace: \", \"@sim/auth\": \"workspace: \", \"@sim/db\": \"workspace: \", \"@sim/logger\": \"workspace: \", \"@sim/realtime-protocol\": \"workspace: \", \"@sim/security\": \"workspace: \", \"@sim/utils\": \"workspace: \", \"@sim/w… 证据：`apps/realtime/package.json`\n- **Package**（package_manifest）：{ \"name\": \"sim\", \"version\": \"0.1.0\", \"private\": true, \"license\": \"Apache-2.0\", \"engines\": { \"bun\": \" =1.2.13\", \"node\": \" =20.0.0\" }, \"scripts\": { \"dev\": \"next dev --port 3000\", \"dev:webpack\": \"next dev --webpack\", \"load:workflow\": \"bun run load:workflow:baseline\", \"load:workflow:baseline\": \"BASE URL=${BASE URL:-http://localhost:3000} WARMUP DURATION=${WARMUP DURATION:-10} WARMUP RATE=${WARMUP RATE:-2} PEAK RATE=${PEAK RATE:-8} HOLD DURATION=${HOLD DURATION:-20} bunx artillery run scripts/load/workflow-concurrency.yml\", \"load:workflow:waves\": \"BASE URL=${BASE URL:-http://localhost:3000} WAVE ONE DURATION=${WAVE ONE DURATION:-10} WAVE ONE RATE=${WAVE ONE RATE:-6} QUIET DURATION=${QUIET DURATI… 证据：`apps/sim/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@sim/audit\", \"version\": \"0.1.0\", \"private\": true, \"sideEffects\": false, \"type\": \"module\", \"license\": \"Apache-2.0\", \"engines\": { \"bun\": \" =1.2.13\", \"node\": \" =20.0.0\" }, \"exports\": { \".\": { \"types\": \"./src/index.ts\", \"default\": \"./src/index.ts\" } }, \"scripts\": { \"type-check\": \"tsc --noEmit\", \"lint\": \"biome check --write --unsafe .\", \"lint:check\": \"biome check .\", \"format\": \"biome format --write .\", \"format:check\": \"biome format .\", \"test\": \"vitest run\", \"test:watch\": \"vitest\" }, \"dependencies\": { \"@sim/db\": \"workspace: \", \"@sim/logger\": \"workspace: \", \"@sim/utils\": \"workspace: \", \"drizzle-orm\": \"^0.45.2\" }, \"devDependencies\": { \"@sim/testing\": \"workspace: \", \"@sim/tsconfig\": \"work… 证据：`packages/audit/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@sim/auth\", \"version\": \"0.1.0\", \"private\": true, \"sideEffects\": false, \"type\": \"module\", \"license\": \"Apache-2.0\", \"engines\": { \"bun\": \" =1.2.13\", \"node\": \" =20.0.0\" }, \"exports\": { \"./verify\": { \"types\": \"./src/verify.ts\", \"default\": \"./src/verify.ts\" } }, \"scripts\": { \"type-check\": \"tsc --noEmit\", \"lint\": \"biome check --write --unsafe .\", \"lint:check\": \"biome check .\", \"format\": \"biome format --write .\", \"format:check\": \"biome format .\" }, \"dependencies\": { \"@sim/db\": \"workspace: \", \"better-auth\": \"1.3.12\" }, \"devDependencies\": { \"@sim/tsconfig\": \"workspace: \", \"typescript\": \"^5.7.3\" } } 证据：`packages/auth/package.json`\n- **Package**（package_manifest）：{ \"name\": \"simstudio\", \"version\": \"0.1.19\", \"description\": \"Sim CLI - Run Sim with a single command\", \"type\": \"module\", \"exports\": { \".\": { \"types\": \"./dist/index.d.ts\", \"import\": \"./dist/index.js\" } }, \"bin\": { \"simstudio\": \"dist/index.js\" }, \"scripts\": { \"build\": \"tsc\", \"type-check\": \"tsc --noEmit\", \"lint\": \"biome check --write --unsafe .\", \"lint:check\": \"biome check .\", \"format\": \"biome format --write .\", \"format:check\": \"biome format .\", \"prepublishOnly\": \"bun run build\" }, \"files\": \"dist\" , \"keywords\": \"simstudio\", \"ai\", \"workflow\", \"cli\", \"agent\", \"automation\", \"docker\" , \"author\": \"Sim\", \"license\": \"Apache-2.0\", \"engines\": { \"node\": \" =16\" }, \"dependencies\": { \"chalk\": \"^4.1.2\", \"com… 证据：`packages/cli/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@sim/db\", \"version\": \"0.1.0\", \"private\": true, \"type\": \"module\", \"license\": \"Apache-2.0\", \"engines\": { \"bun\": \" =1.2.13\", \"node\": \" =20.0.0\" }, \"exports\": { \".\": { \"types\": \"./index.ts\", \"default\": \"./index.ts\" }, \"./schema\": { \"types\": \"./schema.ts\", \"default\": \"./schema.ts\" } }, \"scripts\": { \"db:push\": \"bunx drizzle-kit push --config=./drizzle.config.ts\", \"db:migrate\": \"bun --env-file=.env run ./scripts/migrate.ts\", \"db:studio\": \"bunx drizzle-kit studio --config=./drizzle.config.ts\", \"test\": \"vitest run\", \"type-check\": \"tsc --noEmit\", \"lint\": \"biome check --write --unsafe .\", \"lint:check\": \"biome check .\", \"format\": \"biome format --write .\", \"format:check\": \"biome format .\" },… 证据：`packages/db/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@sim/logger\", \"version\": \"0.1.0\", \"private\": true, \"sideEffects\": false, \"type\": \"module\", \"license\": \"Apache-2.0\", \"engines\": { \"bun\": \" =1.2.13\", \"node\": \" =20.0.0\" }, \"exports\": { \".\": { \"types\": \"./src/index.ts\", \"default\": \"./src/index.ts\" } }, \"scripts\": { \"type-check\": \"tsc --noEmit\", \"lint\": \"biome check --write --unsafe .\", \"lint:check\": \"biome check .\", \"format\": \"biome format --write .\", \"format:check\": \"biome format .\", \"test\": \"vitest run\", \"test:watch\": \"vitest\" }, \"dependencies\": { \"chalk\": \"5.6.2\" }, \"devDependencies\": { \"@sim/tsconfig\": \"workspace: \", \"typescript\": \"^5.7.3\", \"vitest\": \"^3.0.8\" } } 证据：`packages/logger/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@sim/realtime-protocol\", \"version\": \"0.1.0\", \"private\": true, \"sideEffects\": false, \"type\": \"module\", \"license\": \"Apache-2.0\", \"engines\": { \"bun\": \" =1.2.13\", \"node\": \" =20.0.0\" }, \"exports\": { \"./constants\": { \"types\": \"./src/constants.ts\", \"default\": \"./src/constants.ts\" }, \"./schemas\": { \"types\": \"./src/schemas.ts\", \"default\": \"./src/schemas.ts\" } }, \"scripts\": { \"type-check\": \"tsc --noEmit\", \"lint\": \"biome check --write --unsafe .\", \"lint:check\": \"biome check .\", \"format\": \"biome format --write .\", \"format:check\": \"biome format .\" }, \"dependencies\": { \"zod\": \"4.3.6\" }, \"devDependencies\": { \"@sim/tsconfig\": \"workspace: \", \"typescript\": \"^5.7.3\" } } 证据：`packages/realtime-protocol/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@sim/security\", \"version\": \"0.1.0\", \"private\": true, \"sideEffects\": false, \"type\": \"module\", \"license\": \"Apache-2.0\", \"engines\": { \"bun\": \" =1.2.13\", \"node\": \" =20.0.0\" }, \"exports\": { \"./compare\": { \"types\": \"./src/compare.ts\", \"default\": \"./src/compare.ts\" }, \"./encryption\": { \"types\": \"./src/encryption.ts\", \"default\": \"./src/encryption.ts\" }, \"./hash\": { \"types\": \"./src/hash.ts\", \"default\": \"./src/hash.ts\" }, \"./hmac\": { \"types\": \"./src/hmac.ts\", \"default\": \"./src/hmac.ts\" }, \"./tokens\": { \"types\": \"./src/tokens.ts\", \"default\": \"./src/tokens.ts\" } }, \"scripts\": { \"type-check\": \"tsc --noEmit\", \"lint\": \"biome check --write --unsafe .\", \"lint:check\": \"biome check .\", \"format\": \"b… 证据：`packages/security/package.json`\n- **Package**（package_manifest）：{ \"name\": \"simstudio-ts-sdk\", \"version\": \"0.1.2\", \"description\": \"Sim SDK - Execute workflows programmatically\", \"type\": \"module\", \"exports\": { \".\": { \"types\": \"./dist/index.d.ts\", \"import\": \"./dist/index.js\" } }, \"scripts\": { \"build\": \"tsc\", \"type-check\": \"tsc --noEmit\", \"lint\": \"biome check --write --unsafe .\", \"lint:check\": \"biome check .\", \"format\": \"biome format --write .\", \"format:check\": \"biome format .\", \"dev:watch\": \"tsc --watch\", \"prepublishOnly\": \"bun run build\", \"test\": \"vitest run\", \"test:watch\": \"vitest\" }, \"files\": \"dist\" , \"keywords\": \"simstudio\", \"ai\", \"workflow\", \"sdk\", \"api\", \"automation\", \"typescript\" , \"author\": \"Sim\", \"license\": \"Apache-2.0\", \"dependencies\": { \"node-fe… 证据：`packages/ts-sdk/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@sim/tsconfig\", \"version\": \"0.0.0\", \"private\": true, \"sideEffects\": false, \"license\": \"Apache-2.0\", \"description\": \"Shared TypeScript configurations for Sim monorepo\", \"exports\": { \"./base.json\": \"./base.json\", \"./nextjs.json\": \"./nextjs.json\", \"./library.json\": \"./library.json\", \"./library-build.json\": \"./library-build.json\" } } 证据：`packages/tsconfig/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@sim/utils\", \"version\": \"0.1.0\", \"private\": true, \"sideEffects\": false, \"type\": \"module\", \"license\": \"Apache-2.0\", \"exports\": { \".\": { \"types\": \"./src/index.ts\", \"default\": \"./src/index.ts\" }, \"./id\": { \"types\": \"./src/id.ts\", \"default\": \"./src/id.ts\" }, \"./errors\": { \"types\": \"./src/errors.ts\", \"default\": \"./src/errors.ts\" }, \"./helpers\": { \"types\": \"./src/helpers.ts\", \"default\": \"./src/helpers.ts\" }, \"./formatting\": { \"types\": \"./src/formatting.ts\", \"default\": \"./src/formatting.ts\" } }, \"scripts\": { \"type-check\": \"tsc --noEmit\", \"lint\": \"biome check --write --unsafe .\", \"lint:check\": \"biome check .\", \"format\": \"biome format --write .\", \"format:check\": \"biome format .\", \"test\":… 证据：`packages/utils/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@sim/workflow-authz\", \"version\": \"0.1.0\", \"private\": true, \"sideEffects\": false, \"type\": \"module\", \"license\": \"Apache-2.0\", \"engines\": { \"bun\": \" =1.2.13\", \"node\": \" =20.0.0\" }, \"exports\": { \".\": { \"types\": \"./src/index.ts\", \"default\": \"./src/index.ts\" } }, \"scripts\": { \"type-check\": \"tsc --noEmit\", \"lint\": \"biome check --write --unsafe .\", \"lint:check\": \"biome check .\", \"format\": \"biome format --write .\", \"format:check\": \"biome format .\" }, \"dependencies\": { \"@sim/db\": \"workspace: \", \"drizzle-orm\": \"^0.45.2\" }, \"devDependencies\": { \"@sim/tsconfig\": \"workspace: \", \"typescript\": \"^5.7.3\" } } 证据：`packages/workflow-authz/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@sim/workflow-persistence\", \"version\": \"0.1.0\", \"private\": true, \"sideEffects\": false, \"type\": \"module\", \"license\": \"Apache-2.0\", \"engines\": { \"bun\": \" =1.2.13\", \"node\": \" =20.0.0\" }, \"exports\": { \".\": { \"types\": \"./src/index.ts\", \"default\": \"./src/index.ts\" }, \"./load\": { \"types\": \"./src/load.ts\", \"default\": \"./src/load.ts\" }, \"./save\": { \"types\": \"./src/save.ts\", \"default\": \"./src/save.ts\" }, \"./subblocks\": { \"types\": \"./src/subblocks.ts\", \"default\": \"./src/subblocks.ts\" }, \"./subflow-helpers\": { \"types\": \"./src/subflow-helpers.ts\", \"default\": \"./src/subflow-helpers.ts\" }, \"./types\": { \"types\": \"./src/types.ts\", \"default\": \"./src/types.ts\" } }, \"scripts\": { \"type-check\": \"tsc -… 证据：`packages/workflow-persistence/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@sim/workflow-types\", \"version\": \"0.1.0\", \"private\": true, \"sideEffects\": false, \"type\": \"module\", \"license\": \"Apache-2.0\", \"engines\": { \"bun\": \" =1.2.13\", \"node\": \" =20.0.0\" }, \"exports\": { \"./blocks\": { \"types\": \"./src/blocks.ts\", \"default\": \"./src/blocks.ts\" }, \"./workflow\": { \"types\": \"./src/workflow.ts\", \"default\": \"./src/workflow.ts\" } }, \"scripts\": { \"type-check\": \"tsc --noEmit\", \"lint\": \"biome check --write --unsafe .\", \"lint:check\": \"biome check .\", \"format\": \"biome format --write .\", \"format:check\": \"biome format .\" }, \"peerDependencies\": { \"reactflow\": \"^11.11.4\" }, \"devDependencies\": { \"@sim/tsconfig\": \"workspace: \", \"reactflow\": \"^11.11.4\", \"typescript\": \"^5.7.3\" } } 证据：`packages/workflow-types/package.json`\n- **Add Block Skill**（skill_instruction）：You are an expert at creating block configurations for Sim. You understand the serializer, subBlock types, conditions, dependsOn, modes, and all UI patterns. 证据：`.agents/skills/add-block/SKILL.md`\n- **Add Connector Skill**（skill_instruction）：You are an expert at adding knowledge base connectors to Sim. A connector syncs documents from an external source Confluence, Google Drive, Notion, etc. into a knowledge base. 证据：`.agents/skills/add-connector/SKILL.md`\n- **Add Integration Skill**（skill_instruction）：You are an expert at adding complete integrations to Sim. This skill orchestrates the full process of adding a new service integration. 证据：`.agents/skills/add-integration/SKILL.md`\n- **Add Tools Skill**（skill_instruction）：You are an expert at creating tool configurations for Sim integrations. Your job is to read API documentation and create properly structured tool files. 证据：`.agents/skills/add-tools/SKILL.md`\n- **Add Trigger**（skill_instruction）：You are an expert at creating webhook triggers for Sim. You understand the trigger system, the generic buildTriggerSubBlocks helper, and how triggers connect to blocks. 证据：`.agents/skills/add-trigger/SKILL.md`\n- **Cleanup**（skill_instruction）：Arguments: - scope: what to review default: your current changes . Examples: \"diff to main\", \"PR 123\", \"src/components/\", \"whole codebase\" - fix: whether to apply fixes default: true . Set to false to only propose changes. 证据：`.agents/skills/cleanup/SKILL.md`\n- **EMCN Design Review**（skill_instruction）：Arguments: - scope: what to review default: your current changes . Examples: \"diff to main\", \"PR 123\", \"src/components/\", \"whole codebase\" - fix: whether to apply fixes default: true . Set to false to only propose changes. 证据：`.agents/skills/emcn-design-review/SKILL.md`\n- **React Query Best Practices**（skill_instruction）：Arguments: - scope: what to analyze default: your current changes . Examples: \"diff to main\", \"PR 123\", \"src/hooks/queries/\", \"whole codebase\" - fix: whether to apply fixes default: true . Set to false to only propose changes. 证据：`.agents/skills/react-query-best-practices/SKILL.md`\n- **Ship Command**（skill_instruction）：You help ship code by creating commits, pushing to the remote branch, and creating PRs in the user's voice. 证据：`.agents/skills/ship/SKILL.md`\n- **Validate Connector Skill**（skill_instruction）：You are an expert auditor for Sim knowledge base connectors. Your job is to thoroughly validate that an existing connector is correct, complete, and follows all conventions. 证据：`.agents/skills/validate-connector/SKILL.md`\n- **Validate Integration Skill**（skill_instruction）：You are an expert auditor for Sim integrations. Your job is to thoroughly validate that an existing integration is correct, complete, and follows all conventions. 证据：`.agents/skills/validate-integration/SKILL.md`\n- **Validate Trigger**（skill_instruction）：You are an expert auditor for Sim webhook triggers. Your job is to validate that an existing trigger implementation is correct, complete, secure, and aligned across all layers. 证据：`.agents/skills/validate-trigger/SKILL.md`\n- **You Might Not Need a Callback**（skill_instruction）：Arguments: - scope: what to analyze default: your current changes . Examples: \"diff to main\", \"PR 123\", \"src/components/\", \"whole codebase\" - fix: whether to apply fixes default: true . Set to false to only propose changes. 证据：`.agents/skills/you-might-not-need-a-callback/SKILL.md`\n- **You Might Not Need a Memo**（skill_instruction）：Arguments: - scope: what to analyze default: your current changes . Examples: \"diff to main\", \"PR 123\", \"src/components/\", \"whole codebase\" - fix: whether to apply fixes default: true . Set to false to only propose changes. 证据：`.agents/skills/you-might-not-need-a-memo/SKILL.md`\n- **You Might Not Need an Effect**（skill_instruction）：Arguments: - scope: what to analyze default: your current changes . Examples: \"diff to main\", \"PR 123\", \"src/components/\", \"whole codebase\" - fix: whether to apply fixes default: true . Set to false to only propose changes. 证据：`.agents/skills/you-might-not-need-an-effect/SKILL.md`\n- **You Might Not Need State**（skill_instruction）：Arguments: - scope: what to analyze default: your current changes . Examples: \"diff to main\", \"PR 123\", \"src/components/\", \"whole codebase\" - fix: whether to apply fixes default: true . Set to false to only propose changes. 证据：`.agents/skills/you-might-not-need-state/SKILL.md`\n- **Adding Hosted Key Support to a Tool**（skill_instruction）：Adding Hosted Key Support to a Tool 证据：`.cursor/skills/add-hosted-key/SKILL.md`\n- **Package**（package_manifest）：{ \"name\": \"@sim/testing\", \"version\": \"0.1.0\", \"private\": true, \"sideEffects\": \"./src/setup/ \" , \"type\": \"module\", \"license\": \"Apache-2.0\", \"engines\": { \"bun\": \" =1.2.13\", \"node\": \" =20.0.0\" }, \"exports\": { \".\": { \"types\": \"./src/index.ts\", \"default\": \"./src/index.ts\" }, \"./factories\": { \"types\": \"./src/factories/index.ts\", \"default\": \"./src/factories/index.ts\" }, \"./builders\": { \"types\": \"./src/builders/index.ts\", \"default\": \"./src/builders/index.ts\" }, \"./mocks\": { \"types\": \"./src/mocks/index.ts\", \"default\": \"./src/mocks/index.ts\" }, \"./mocks/executor\": { \"types\": \"./src/mocks/executor.mock.ts\", \"default\": \"./src/mocks/executor.mock.ts\" }, \"./assertions\": { \"types\": \"./src/assertions/index… 证据：`packages/testing/package.json`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **License**（source_file）：Copyright c 2025-present Sim Studio, Inc. 证据：`apps/sim/ee/LICENSE`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`apps/docs/README.md`, `.devcontainer/README.md`, `AGENTS.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`apps/docs/README.md`, `.devcontainer/README.md`, `AGENTS.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目概述**：importance `high`\n - source_paths: README.md, apps/sim/package.json\n- **系统架构**：importance `high`\n - source_paths: apps/sim/app, apps/realtime/src, apps/realtime/src/index.ts, packages/db\n- **工作流执行引擎**：importance `high`\n - source_paths: apps/sim/executor/dag/builder.ts, apps/sim/executor/dag/types.ts, apps/sim/executor/execution/engine.ts, apps/sim/executor/execution/executor.ts, apps/sim/executor/execution/snapshot.ts\n- **块系统与注册表**：importance `high`\n - source_paths: apps/sim/blocks/registry.ts, apps/sim/blocks/types.ts, apps/sim/blocks/index.ts, apps/sim/blocks/blocks\n- **代理与AI集成**：importance `high`\n - source_paths: apps/sim/blocks/blocks/agent.ts, apps/sim/executor/handlers/agent/agent-handler.ts, apps/sim/executor/handlers/agent/memory.ts, apps/sim/executor/handlers/agent/skills-resolver.ts, apps/sim/executor/handlers/agent/types.ts\n- **工作流编辑器**：importance `high`\n - source_paths: apps/sim/app/workspace/[workspaceId]/w/[workflowId], apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor, apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/workflow-block, apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/sub-block\n- **实时协作与UI组件**：importance `medium`\n - source_paths: apps/realtime/src/handlers, apps/realtime/src/middleware, apps/realtime/src/rooms, apps/sim/app/workspace/providers/socket-provider.tsx, apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/cursors/cursors.tsx\n- **连接器框架**：importance `medium`\n - source_paths: apps/sim/connectors/registry.ts, apps/sim/connectors/types.ts, apps/sim/connectors/index.ts, apps/sim/connectors/slack/slack.ts, apps/sim/connectors/notion/notion.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `dcaf3e98c132dedaa66490c0e63b6c3ff09aafdd`\n- inspected_files: `package.json`, `README.md`, `packages/README.md`, `packages/cli/package.json`, `packages/cli/README.md`, `packages/cli/tsconfig.json`, `packages/testing/package.json`, `packages/testing/tsconfig.json`, `packages/audit/vitest.config.ts`, `packages/audit/package.json`, `packages/audit/tsconfig.json`, `packages/workflow-authz/package.json`, `packages/workflow-authz/tsconfig.json`, `packages/tsconfig/library.json`, `packages/tsconfig/package.json`, `packages/tsconfig/nextjs.json`, `packages/tsconfig/library-build.json`, `packages/tsconfig/base.json`, `packages/utils/vitest.config.ts`, `packages/utils/package.json`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 社区讨论暴露的待验证问题：Open-source general purpose agent with built-in MCPToolkit support\n\n- Trigger: 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.\n- Host AI rule: Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。\n- Why it matters: 这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。\n- Evidence: 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\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 可能修改宿主 AI 配置\n\n- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Evidence: capability.host_targets | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | host_targets=cursor\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：v0.6.63\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.6.63\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_5a97e1d742fe4d7f918e0b42f27b87c3 | https://github.com/simstudioai/sim/releases/tag/v0.6.63 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：v0.6.65\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.6.65\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_03f18559029c4724b11011ef96259161 | https://github.com/simstudioai/sim/releases/tag/v0.6.65 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：v0.6.67\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.6.67\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_048d1506c1d645b0be435841a26b93ed | https://github.com/simstudioai/sim/releases/tag/v0.6.67 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：v0.6.73\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.6.73\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_048864e1cdcc44d2b2a30917b7c4adc2 | https://github.com/simstudioai/sim/releases/tag/v0.6.73 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：v0.6.71\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v0.6.71\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_9c30d794fb7344489f96a6ac47cd1d6e | https://github.com/simstudioai/sim/releases/tag/v0.6.71 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n", "summary": "给宿主 AI 的上下文和工作边界。", "title": "AI Context Pack / 带给我的 AI" }, "boundary_risk_card": { "asset_id": "boundary_risk_card", "filename": "BOUNDARY_RISK_CARD.md", "markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：simstudioai/sim\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：cursor\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 社区讨论暴露的待验证问题：Open-source general purpose agent with built-in MCPToolkit support（medium）：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。\n- 可能修改宿主 AI 配置（medium）：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 来源证据：v0.6.63（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v0.6.65（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n", "summary": "安装、权限、验证和推荐前风险。", "title": "Boundary & Risk Card / 边界与风险卡" }, "human_manual": { "asset_id": "human_manual", "filename": "HUMAN_MANUAL.md", "markdown": "# https://github.com/simstudioai/sim 项目说明书\n\n生成时间：2026-05-11 19:14:22 UTC\n\n## 目录\n\n- [项目概述](#page-project-overview)\n- [系统架构](#page-system-architecture)\n- [工作流执行引擎](#page-workflow-execution)\n- [块系统与注册表](#page-block-registry)\n- [代理与AI集成](#page-agent-integration)\n- [工作流编辑器](#page-workflow-editor)\n- [实时协作与UI组件](#page-realtime-ui)\n- [连接器框架](#page-connectors)\n- [部署与基础设施](#page-deployment)\n- [扩展与定制](#page-extensibility)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[系统架构](#page-system-architecture), [部署与基础设施](#page-deployment)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/simstudioai/sim/blob/main/README.md)\n- [apps/sim/package.json](https://github.com/simstudioai/sim/blob/main/apps/sim/package.json)\n- [scripts/README.md](https://github.com/simstudioai/sim/blob/main/scripts/README.md)\n- [packages/ts-sdk/README.md](https://github.com/simstudioai/sim/blob/main/packages/ts-sdk/README.md)\n- [packages/python-sdk/README.md](https://github.com/simstudioai/sim/blob/main/packages/python-sdk/README.md)\n- [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)\n- [apps/sim/lib/webhooks/pending-verification.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/pending-verification.ts)\n- [packages/testing/src/mocks/env.mock.ts](https://github.com/simstudioai/sim/blob/main/packages/testing/src/mocks/env.mock.ts)\n
\n\n# 项目概述\n\n## 1. 项目简介\n\nSim 是一个可视化的工作流自动化平台，旨在帮助用户通过直观的拖拽式界面构建、部署和执行复杂的自动化流程。该项目由 SimStudio 团队开发，支持本地部署和云端托管两种模式，并提供了 TypeScript 和 Python 两种 SDK 供开发者集成。\n\nSim 的核心功能包括：\n\n- **可视化工作流编辑器**：通过图形化界面设计自动化流程\n- **多平台 Webhook 集成**：支持 Webflow、Gong、Typeform、Vercel 等多种第三方服务\n- **实时执行引擎**：支持同步和异步两种执行模式\n- **沙箱执行环境**：安全地运行用户代码和自定义逻辑\n- **AI Copilot**：集成 AI 能力辅助工作流构建\n- **PPTX 渲染引擎**：支持 PowerPoint 文件的解析和展示\n\n## 2. 技术架构\n\n### 2.1 技术栈概览\n\n| 类别 | 技术选型 |\n|------|----------|\n| 前端框架 | Next.js |\n| 包管理器 | Bun |\n| 运行时 | Node.js v20+ |\n| 数据库 | PostgreSQL 12+ with pgvector |\n| 容器化 | Docker, Docker Compose |\n| 开发语言 | TypeScript |\n| SDK | TypeScript, Python |\n\n资料来源：[README.md:1-20](https://github.com/simstudioai/sim/blob/main/README.md)\n\n### 2.2 应用架构\n\nSim 项目采用 monorepo 结构，主要包含以下应用模块：\n\n```\nsim/\n├── apps/\n│ ├── sim/ # 主应用程序（Next.js）\n│ └── realtime/ # 实时执行服务\n├── packages/\n│ ├── ts-sdk/ # TypeScript SDK\n│ ├── python-sdk/ # Python SDK\n│ └── testing/ # 测试工具库\n└── scripts/ # 构建和文档生成脚本\n```\n\n资料来源：[apps/sim/package.json:1-15](https://github.com/simstudioai/sim/blob/main/apps/sim/package.json)\n\n### 2.3 核心模块架构图\n\n```mermaid\ngraph TD\n subgraph \"前端层\"\n A[Web UI] --> B[Workflow Editor]\n A --> C[Block Configuration]\n A --> D[Execution Dashboard]\n end\n \n subgraph \"核心服务层\"\n E[Workflow Engine] --> F[Block Registry]\n E --> G[Trigger System]\n E --> H[Execution Engine]\n end\n \n subgraph \"集成层\"\n I[Webhook Providers] --> J[Event Filter]\n I --> K[Verification Service]\n L[Tool Adapters] --> H\n end\n \n subgraph \"数据层\"\n M[(PostgreSQL + pgvector)]\n N[Redis Cache]\n end\n \n subgraph \"SDK 层\"\n O[TypeScript SDK]\n P[Python SDK]\n end\n \n H --> M\n H --> N\n O --> E\n P --> E\n```\n\n## 3. 核心功能模块\n\n### 3.1 工作流引擎\n\n工作流引擎是 Sim 平台的核心组件，负责解析、验证和执行用户定义的工作流。\n\n#### 3.1.1 工作流组件\n\n| 组件 | 功能描述 |\n|------|----------|\n| Block | 工作流中的基本执行单元 |\n| Loop Block | 循环控制块，支持 for 循环 |\n| Parallel Block | 并行执行块 |\n| Trigger | 触发器，定义工作流启动条件 |\n| Subflow | 子流程，嵌套的工作流片段 |\n\n资料来源：[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)\n\n#### 3.1.2 执行模式\n\nSim 支持两种执行模式：\n\n- **同步执行**：等待工作流完成并返回结果\n- **异步执行**：将任务加入队列，立即返回任务 ID\n\n```typescript\ninterface ExecutionOptions {\n timeout?: number;\n stream?: boolean;\n selectedOutputs?: string[];\n async?: boolean;\n}\n```\n\n资料来源：[packages/ts-sdk/README.md:1-50](https://github.com/simstudioai/sim/blob/main/packages/ts-sdk/README.md)\n\n### 3.2 Webhook 系统\n\nSim 提供了强大的 Webhook 集成能力，支持多种第三方服务。\n\n#### 3.2.1 支持的 Webhook 提供商\n\n| 提供商 | 验证方式 | 特殊配置 |\n|--------|----------|----------|\n| Ashby | 自定义 | `action === 'ping'` |\n| Grain | 自定义 | GET/HEAD 请求自动验证 |\n| Generic | 自定义 | 支持 `verifyTestEvents` 元数据 |\n| Salesforce | 自定义 | 多种请求类型 |\n| Webflow | - | 支持 `collectionId` 过滤 |\n| Gong | - | 通话元数据解析 |\n| Typeform | HMAC | 支持 `includeDefinition` |\n| Vercel | - | 部署和项目信息 |\n\n资料来源：[apps/sim/lib/webhooks/pending-verification.ts:1-30](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/pending-verification.ts)\n\n#### 3.2.2 Webhook 事件过滤机制\n\n```typescript\ninterface EventFilterContext {\n webhook: Webhook;\n body: Record;\n requestId: string;\n providerConfig: Record;\n}\n```\n\nWebflow 提供商实现了集合 ID 过滤功能，只有匹配配置中指定 `collectionId` 的事件才会被处理：\n\n```typescript\nshouldSkipEvent({ webhook, body, requestId, providerConfig }: EventFilterContext) {\n const configuredCollectionId = providerConfig.collectionId as string | undefined\n // ... 过滤逻辑\n}\n```\n\n资料来源：[apps/sim/lib/webhooks/providers/webflow.ts:1-60](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/providers/webflow.ts)\n\n### 3.3 块系统与文档生成\n\nSim 使用块（Block）作为构建工作流的基本单元。每个块包含元数据、输入输出规范和配置参数。\n\n#### 3.3.1 文档生成器\n\n`scripts/generate-docs.ts` 脚本自动扫描 `apps/sim/blocks/blocks/` 目录，提取所有块定义文件的元数据并生成标准化 Markdown 文档。\n\n工作流程：\n\n1. 扫描块定义文件目录\n2. 提取块元数据（名称、描述、分类）\n3. 提取输入输出规范\n4. 提取配置参数\n5. 生成 Markdown 文档\n6. 更新 `meta.json` 导航元数据\n\n资料来源：[scripts/README.md:1-40](https://github.com/simstudioai/sim/blob/main/scripts/README.md)\n\n#### 3.3.2 块类型定义\n\n```typescript\ninterface ToolBlockRecord {\n type: string;\n title?: string;\n toolId?: string;\n operation?: string;\n params?: Record;\n customToolId?: string;\n code?: string;\n usageControl?: 'auto' | 'force' | 'none';\n isExpanded?: boolean;\n schema?: StoredToolSchema;\n}\n```\n\n资料来源：[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)\n\n### 3.4 实时执行服务\n\n实时执行服务（Realtime Service）负责处理工作流的运行时操作，包括状态管理和数据持久化。\n\n#### 3.4.1 数据库操作\n\n```mermaid\ngraph LR\n A[Workflow Update] --> B[Validate Blocks]\n B --> C[Upsert Workflow Blocks]\n C --> D{Block Type}\n D -->|Loop| E[Create Subflow Entry]\n D -->|Parallel| F[Create Subflow Entry]\n E --> G[Commit Transaction]\n F --> G\n```\n\n工作流更新操作使用 PostgreSQL 的 `ON CONFLICT DO UPDATE` 语法进行原子性更新：\n\n```typescript\nawait tx\n .insert(workflowBlocks)\n .values(blockValues)\n .onConflictDoUpdate({\n target: workflowBlocks.id,\n set: {\n type: sql`excluded.type`,\n name: sql`excluded.name`,\n // ... 其他字段\n updatedAt: sql`now()`,\n },\n })\n```\n\n资料来源：[apps/realtime/src/database/operations.ts:1-60](https://github.com/simstudioai/sim/blob/main/apps/realtime/src/database/operations.ts)\n\n### 3.5 PPTX 渲染引擎\n\nSim 内置了 PowerPoint 文件的解析和渲染能力，位于 `apps/sim/lib/pptx-renderer/` 目录。\n\n#### 3.5.1 渲染特性\n\n- 解析 OOXML 格式的 PPTX 文件\n- 支持 WPS Office 和 Microsoft Office 格式识别\n- 基于关系 ID 而非数字幻灯片 ID 的排序逻辑\n- 支持窗口化列表渲染（用于大型演示文稿）\n\n```typescript\ninterface SIM_PPTX_LIST_OPTIONS {\n // 窗口化渲染配置\n}\n```\n\n资料来源：[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)\n\n### 3.6 AI Copilot 集成\n\nSim 平台集成了 AI Copilot 功能，提供智能化的工作流构建辅助。\n\n#### 3.6.1 Copilot 通信协议\n\nCopilot 使用流式通信协议，支持多种消息类型：\n\n```typescript\ninterface SyntheticFilePreviewPayload {\n toolCallId: string;\n toolName: 'workspace_file';\n previewPhase: 'start' | 'target' | 'editMeta' | 'content';\n content?: string;\n contentMode?: 'delta' | 'snapshot';\n previewVersion?: number;\n}\n```\n\n资料来源：[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)\n\n## 4. SDK 文档\n\n### 4.1 TypeScript SDK\n\nTypeScript SDK 提供了与 Sim 平台交互的完整接口。\n\n#### 4.1.1 核心类\n\n| 类名 | 功能 |\n|------|------|\n| `SimStudio` | 主客户端类 |\n| `SimStudioError` | 错误处理类，继承自 Error |\n| `WorkflowExecutionResult` | 执行结果数据类 |\n| `WorkflowStatus` | 工作流状态类 |\n| `AsyncExecutionResult` | 异步执行结果 |\n\n资料来源：[packages/ts-sdk/README.md:50-120](https://github.com/simstudioai/sim/blob/main/packages/ts-sdk/README.md)\n\n#### 4.1.2 速率限制与用量\n\n```typescript\ninterface UsageLimits {\n success: boolean;\n rateLimit: {\n sync: {\n isLimited: boolean;\n limit: number;\n remaining: number;\n resetAt: string;\n };\n async: {\n isLimited: boolean;\n limit: number;\n remaining: number;\n resetAt: string;\n };\n authType: string;\n };\n}\n```\n\n### 4.2 Python SDK\n\nPython SDK 提供 Python 环境的集成支持。\n\n#### 4.2.1 安装要求\n\n| 要求 | 最低版本 |\n|------|----------|\n| Python | 3.8+ |\n| requests | 2.25.0+ |\n\n资料来源：[packages/python-sdk/README.md:1-30](https://github.com/simstudioai/sim/blob/main/packages/python-sdk/README.md)\n\n#### 4.2.2 代码质量工具\n\nPython SDK 使用以下工具保证代码质量：\n\n| 工具 | 用途 |\n|------|------|\n| black | 代码格式化 |\n| flake8 | 代码检查 |\n| mypy | 类型检查 |\n| isort | 导入排序 |\n\n## 5. 部署方式\n\n### 5.1 部署方式对比\n\n| 方式 | 难度 | 适用场景 | 要求 |\n|------|------|----------|------|\n| NPM 在线版 | ⭐ | 快速体验 | 互联网连接 |\n| Docker (npx) | ⭐⭐ | 本地开发 | Docker |\n| Docker Compose | ⭐⭐ | 生产部署 | Docker |\n| 手动安装 | ⭐⭐⭐ | 深度定制 | Bun, Node.js, PostgreSQL |\n\n资料来源：[README.md:20-60](https://github.com/simstudioai/sim/blob/main/README.md)\n\n### 5.2 Docker 部署配置\n\nDocker 部署支持以下配置选项：\n\n| 标志 | 描述 | 默认值 |\n|------|------|--------|\n| `-p, --port ` | 运行端口 | `3000` |\n| `--no-pull` | 跳过拉取最新镜像 | false |\n\n### 5.3 手动安装要求\n\n- **Bun**: JavaScript 运行时和包管理器\n- **Node.js**: v20+\n- **PostgreSQL**: 12+ with pgvector 扩展\n- **Redis**: 可选，用于缓存\n\n### 5.4 本地模型支持\n\nSim 支持使用本地大语言模型：\n\n- **Ollama**: 本地模型推理服务\n- **vLLM**: 高性能推理引擎\n\n详情请参阅 [Docker self-hosting docs](https://docs.sim.ai/self-hosting/docker)。\n\n## 6. 开发指南\n\n### 6.1 项目初始化\n\n```bash\n# 克隆仓库\ngit clone https://github.com/simstudioai/sim.git\ncd sim\n\n# 安装依赖\nbun install\n\n# 初始化\nbun run prepare # 设置 pre-commit hooks\n```\n\n资料来源：[README.md:40-50](https://github.com/simstudioai/sim/blob/main/README.md)\n\n### 6.2 环境变量配置\n\nSim 使用集中化的环境配置系统：\n\n```typescript\ninterface EnvConfig {\n NEXT_PUBLIC_APP_URL?: string;\n // ... 其他配置\n}\n```\n\n资料来源：[packages/testing/src/mocks/env.mock.ts:1-50](https://github.com/simstudioai/sim/blob/main/packages/testing/src/mocks/env.mock.ts)\n\n### 6.3 构建与测试\n\n| 命令 | 功能 |\n|------|------|\n| `bun run build` | 构建生产版本 |\n| `bun run test` | 运行测试 |\n| `bun run test:watch` | 监听模式运行测试 |\n| `bun run lint` | 代码检查并修复 |\n| `bun run type-check` | TypeScript 类型检查 |\n\n资料来源：[apps/sim/package.json:15-30](https://github.com/simstudioai/sim/blob/main/apps/sim/package.json)\n\n### 6.4 负载测试\n\nSim 提供了 Artillery 负载测试脚本：\n\n| 命令 | 描述 |\n|------|------|\n| `bun run load:workflow:waves` | 波浪式负载测试 |\n| `bun run load:workflow:isolation` | 工作空间隔离测试 |\n\n## 7. CI/CD 集成\n\nSim 项目集成了完整的 CI/CD 流程：\n\n- 文档生成器在 main 分支推送时自动运行\n- 更新的文档会自动提交回仓库\n- 代码质量检查（lint、type-check）集成在 CI 流程中\n\n## 8. 总结\n\nSim 是一个功能完整的可视化工作流自动化平台，其技术特点包括：\n\n1. **现代化技术栈**：基于 Next.js、Bun、TypeScript 构建\n2. **灵活的部署方式**：支持云端、本地 Docker 和手动部署\n3. **丰富的集成能力**：支持多种 Webhook 提供商和工具适配\n4. **完善的 SDK 支持**：提供 TypeScript 和 Python 两种 SDK\n5. **AI 能力集成**：内置 Copilot 支持智能化工作流构建\n6. **企业级功能**：包括速率限制、用量监控、沙箱执行等\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目概述](#page-project-overview), [工作流执行引擎](#page-workflow-execution), [实时协作与UI组件](#page-realtime-ui)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [apps/sim/app](https://github.com/simstudioai/sim/blob/main/apps/sim/app)\n- [apps/realtime/src](https://github.com/simstudioai/sim/blob/main/apps/realtime/src)\n- [apps/realtime/src/index.ts](https://github.com/simstudioai/sim/blob/main/apps/realtime/src/index.ts)\n- [packages/db](https://github.com/simstudioai/sim/blob/main/packages/db)\n- [packages/ts-sdk/README.md](https://github.com/simstudioai/sim/blob/main/packages/ts-sdk/README.md)\n- [packages/python-sdk/README.md](https://github.com/simstudioai/sim/blob/main/packages/python-sdk/README.md)\n- [apps/sim/package.json](https://github.com/simstudioai/sim/blob/main/apps/sim/package.json)\n- [packages/cli/README.md](https://github.com/simstudioai/sim/blob/main/packages/cli/README.md)\n
\n\n# 系统架构\n\n## 概述\n\nSim 是一个开源平台，用于构建 AI 代理并运行代理工作流。该平台连接超过 1000 种集成和大语言模型（LLM），以编排代理工作流。Sim 采用现代化全栈架构，基于 Next.js 框架构建，支持自托管部署和云端服务。\n\n技术栈核心组件包括：\n\n| 类别 | 技术选型 | 说明 |\n|------|----------|------|\n| 前端框架 | Next.js (App Router) | 支持 SSR/SSG 的 React 框架 |\n| 运行时 | Bun | 高性能 JavaScript 运行时和打包工具 |\n| 数据库 | PostgreSQL + pgvector | 支持向量存储的关系型数据库 |\n| ORM | Drizzle ORM | 类型安全的数据库操作层 |\n| 认证 | Better Auth | 现代化身份认证解决方案 |\n| 模式验证 | Zod | TypeScript 优先的模式验证库 |\n| UI 组件 | Shadcn + Tailwind CSS | 可定制的设计系统 |\n| 状态管理 | Zustand + TanStack Query | 客户端状态与服务器状态管理 |\n| 实时通信 | WebSocket | Socket 服务器处理实时交互 |\n\n资料来源：[README.md:1-50]()\n\n## 整体架构\n\nSim 平台采用微前端和多服务架构，主要包含以下核心模块：\n\n```mermaid\ngraph TD\n A[客户端浏览器] --> B[Next.js Web 应用]\n A --> C[Sim CLI]\n B --> D[PostgreSQL 数据库]\n B --> E[实时 Socket 服务]\n B --> F[工作流执行引擎]\n F --> D\n E --> F\n G[TypeScript SDK] --> B\n H[Python SDK] --> B\n I[CLI 工具] --> B\n```\n\n### 应用层模块\n\n#### Web 应用 (apps/sim)\n\n主应用程序采用 Next.js App Router 架构，核心目录结构如下：\n\n| 目录 | 功能 |\n|------|------|\n| `app/` | Next.js App Router 页面和 API 路由 |\n| `blocks/` | 预构建的工作流块定义 |\n| `lib/` | 核心业务逻辑库 |\n| `components/` | React UI 组件 |\n| `stores/` | Zustand 状态管理 stores |\n| `hooks/` | 自定义 React Hooks |\n\n资料来源：[apps/sim/package.json:1-30]()\n\n#### 实时服务 (apps/realtime)\n\n独立的 Socket 服务器处理实时通信功能，包括：\n\n- 工作流执行状态的实时推送\n- Copilot 交互的流式响应\n- 协作编辑的实时同步\n\n实时服务通过 WebSocket 协议与应用层通信，采用独立的部署单元以确保可扩展性。\n\n资料来源：[apps/realtime/src/index.ts](https://github.com/simstudioai/sim/blob/main/apps/realtime/src/index.ts)\n\n### 数据层\n\n#### 数据库架构\n\nSim 使用 PostgreSQL 作为主数据库，并通过 Drizzle ORM 提供类型安全的数据访问层：\n\n```mermaid\ngraph LR\n A[应用层] --> B[Drizzle ORM]\n B --> C[PostgreSQL]\n C --> D[pgvector 扩展]\n```\n\n关键数据库表结构通过迁移脚本管理，位于 `packages/db/migrations/` 目录。数据库迁移命令：\n\n```bash\ncd packages/db && bun run db:migrate\n```\n\n#### pgvector 集成\n\n平台集成 pgvector 扩展以支持向量存储和语义搜索功能，这对于 AI 代理的相似度匹配和知识检索至关重要。\n\n资料来源：[README.md:30-40]()\n\n## 工作流引擎架构\n\n### 执行模型\n\n工作流执行采用分层架构，支持同步和异步两种执行模式：\n\n```mermaid\ngraph TD\n A[API 触发器] --> B[工作流调度器]\n B --> C{执行模式}\n C -->|同步| D[沙箱执行器]\n C -->|异步| E[任务队列]\n D --> F[块处理器]\n E --> G[Worker 进程]\n G --> F\n F --> H[输出处理器]\n H --> I[结果聚合]\n```\n\n### 沙箱执行\n\n工作流中的代码块在隔离的沙箱环境中执行，确保安全性和隔离性。沙箱打包通过专门的构建脚本生成：\n\n```bash\nbun run build:sandbox-bundles\n```\n\n资料来源：[apps/sim/package.json:8]()\n\n### 块系统 (Blocks)\n\n块是工作流的基本构建单元，每个块定义包含：\n\n| 属性 | 说明 |\n|------|------|\n| `name` | 块名称 |\n| `description` | 功能描述 |\n| `category` | 分类标签 |\n| `inputs` | 输入规格定义 |\n| `outputs` | 输出规格定义 |\n| `config` | 配置参数 |\n\n块文档通过自动化脚本生成，位于 `scripts/generate-docs.ts`。运行文档生成：\n\n```bash\nbun run scripts/generate-docs.ts\n```\n\n资料来源：[scripts/README.md:1-25]()\n\n## SDK 架构\n\n### TypeScript SDK\n\nTypeScript SDK (`packages/ts-sdk`) 提供完整的客户端集成能力：\n\n```typescript\nimport { SimStudioClient } from '@simstudio/ts-sdk'\n\nconst client = new SimStudioClient({\n apiKey: process.env.SIM_API_KEY,\n baseUrl: 'https://sim.ai'\n})\n```\n\n核心接口包括：\n\n| 接口 | 功能 |\n|------|------|\n| `executeWorkflow` | 执行工作流 |\n| `getWorkflowStatus` | 查询工作流状态 |\n| `getExecutionResult` | 获取执行结果 |\n| `uploadFile` | 文件上传 |\n\n资料来源：[packages/ts-sdk/README.md:1-50]()\n\n### Python SDK\n\nPython SDK (`packages/python-sdk`) 提供 Python 生态的集成支持：\n\n```python\nfrom simstudio import SimStudioClient\n\nclient = SimStudioClient(api_key=os.getenv(\"SIM_API_KEY\"))\nresult = client.execute_workflow('workflow-id', input_data)\n```\n\n文件上传自动转换为 base64 格式，支持单文件和批量上传场景。\n\n资料来源：[packages/python-sdk/README.md:1-40]()\n\n## 认证与安全\n\n### 认证方案\n\n平台使用 Better Auth 作为认证解决方案，支持：\n\n- OAuth 社交登录\n- API Key 认证\n- Webhook 签名验证\n\n### Webhook 安全\n\nWebhook 提供商实现 HMAC 签名验证机制：\n\n```mermaid\ngraph TD\n A[外部服务] -->|POST + 签名| B[Webhook 端点]\n B --> C[验证签名]\n C -->|有效| D[处理事件]\n C -->|无效| E[拒绝请求]\n```\n\n支持的 Webhook 提供商包括 Gong、Webflow、Typeform 等，各提供商使用独立的签名验证策略。\n\n资料来源：[lib/webhooks/providers/typeform.ts:20-40]()\n\n## 部署架构\n\n### 部署模式\n\nSim 支持多种部署方式：\n\n| 部署方式 | 说明 | 适用场景 |\n|----------|------|----------|\n| Docker (npx) | 一键启动本地容器 | 快速原型验证 |\n| Docker Compose | 完整服务编排 | 自托管生产环境 |\n| 手动部署 | 细粒度控制 | 高级定制需求 |\n| Helm Charts | Kubernetes 部署 | 企业级集群环境 |\n\n### Docker 部署\n\n使用 Docker Compose 部署完整生产环境：\n\n```bash\ngit clone https://github.com/simstudioai/sim.git\ncd sim\ndocker compose -f docker-compose.prod.yml up -d\n```\n\n### Kubernetes 部署\n\nHelm Charts 提供 Kubernetes 原生部署支持，核心配置参数：\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `app.image.repository` | 应用镜像仓库 | simstudioai/sim |\n| `app.service.port` | 服务端口 | 3000 |\n| `realtime.enabled` | 启用实时服务 | true |\n| `realtime.replicaCount` | 实时服务副本数 | 1 |\n| `realtime.service.port` | 实时服务端口 | 3002 |\n\n资料来源：[helm/sim/README.md:1-30]()\n\n## 开发环境\n\n### 环境准备\n\n开发环境要求：\n\n- Bun v1.0+\n- Node.js v20+\n- PostgreSQL 12+ (启用 pgvector)\n- Docker (可选，用于数据库)\n\n### 本地开发\n\n```bash\n# 克隆仓库\ngit clone https://github.com/simstudioai/sim.git\ncd sim\n\n# 安装依赖\nbun install\n\n# 初始化数据库\ndocker run --name simstudio-db -e POSTGRES_PASSWORD=password \\\n -e POSTGRES_DB=simstudio -p 5432:5432 -d pgvector/pgvector\ncd packages/db && bun run db:migrate\n\n# 启动开发服务器\nbun run dev:full # 启动 Next.js 和 Socket 服务器\n```\n\n### 可用脚本\n\n| 脚本 | 功能 |\n|------|------|\n| `bun run dev` | 启动 Next.js 开发服务器 |\n| `bun run dev:sockets` | 启动 Socket 服务器 |\n| `bun run test` | 运行单元测试 |\n| `bun run build` | 构建生产版本 |\n| `bun run lint` | 代码风格检查 |\n\n资料来源：[README.md:40-60]()\n\n## 配置管理\n\n### 环境变量\n\n核心环境变量配置：\n\n| 变量 | 说明 | 必需 |\n|------|------|------|\n| `DATABASE_URL` | PostgreSQL 连接字符串 | 是 |\n| `COPILOT_API_KEY` | Copilot 服务 API Key | 可选 |\n| `SIM_API_KEY` | 第三方 SDK 认证 | 可选 |\n\n完整环境变量列表参考 `apps/sim/.env.example`。\n\n### 负载测试配置\n\n平台内置 Artillery 负载测试脚本，支持多种测试场景：\n\n| 脚本 | 场景 |\n|------|------|\n| `load:workflow:waves` | 波浪式负载测试 |\n| `load:workflow:isolation` | 隔离工作区负载测试 |\n\n资料来源：[apps/sim/package.json:5-10]()\n\n## 扩展机制\n\n### 触发器系统\n\n工作流支持多种触发类型，优先级排序如下：\n\n| 优先级 | 触发类型 | 说明 |\n|--------|----------|------|\n| 0 | Unified Start | 统一启动块 |\n| 1 | Legacy Starter | 遗留启动块 |\n| 2 | Schedule | 定时调度 |\n| 3 | Webhook | 外部 Webhook |\n| 4-7 | 其他 | API、手动、聊天触发 |\n\n触发器选择逻辑通过 `trigger-utils.ts` 中的优先级算法确定。\n\n资料来源：[lib/workflows/triggers/trigger-utils.ts:1-30]()\n\n### Webhook 提供商集成\n\n平台原生支持多个第三方服务的 Webhook 集成：\n\n- **Gong**: 通话记录和会议分析\n- **Webflow**: CMS 内容更新事件\n- **Typeform**: 表单提交事件\n- **Ashby**: ATS 招聘事件\n- **Salesforce**: CRM 事件\n\n每个提供商实现独立的格式转换和签名验证逻辑。\n\n资料来源：[lib/webhooks/providers/gong.ts:1-20]()\n资料来源：[lib/webhooks/providers/webflow.ts:1-30]()\n\n## 监控与可观测性\n\n### 执行追踪\n\n工作流执行支持完整的追踪机制：\n\n```mermaid\ngraph LR\n A[执行请求] --> B[追踪开始]\n B --> C[块执行]\n C --> D[输出生成]\n D --> E[追踪结束]\n```\n\n追踪数据包含执行时间戳、输入输出快照和错误信息。\n\n### 待验证 Webhook 处理\n\n平台实现待验证 Webhook 的自动探测和处理机制，防止验证请求被当作正式事件处理：\n\n```typescript\nconst pendingWebhookVerificationProbeMatchers = {\n ashby: ({ method, body }) => method === 'POST' && body?.action === 'ping',\n grain: ({ method, body }) => method === 'GET' || method === 'HEAD' || body?.type === undefined,\n // ...\n}\n```\n\n资料来源：[lib/webhooks/pending-verification.ts:1-30]()\n\n---\n\n\n\n## 工作流执行引擎\n\n### 相关页面\n\n相关主题：[系统架构](#page-system-architecture), [块系统与注册表](#page-block-registry), [代理与AI集成](#page-agent-integration)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [apps/sim/lib/workflows/triggers/trigger-utils.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/triggers/trigger-utils.ts)\n- [apps/sim/lib/workflows/triggers/triggers.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/triggers/triggers.ts)\n- [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)\n- [apps/sim/executor/dag/builder.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/executor/dag/builder.ts) *(未获取到具体内容)*\n- [apps/sim/executor/dag/types.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/executor/dag/types.ts) *(未获取到具体内容)*\n- [apps/sim/executor/execution/engine.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/executor/execution/engine.ts) *(未获取到具体内容)*\n- [apps/sim/executor/execution/executor.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/executor/execution/executor.ts) *(未获取到具体内容)*\n- [apps/sim/executor/execution/snapshot.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/executor/execution/snapshot.ts) *(未获取到具体内容)*\n\n> **注意**：部分核心执行引擎文件未能在当前上下文中获取，以下内容基于可访问的触发器和DAG差异引擎相关代码进行推断和分析。\n\n
\n\n# 工作流执行引擎\n\n## 概述\n\nSim 平台的工作流执行引擎是一个基于有向无环图（DAG）的自动化执行系统，负责解析、编排和执行用户定义的工作流程。该引擎支持多种触发方式、循环结构、并行执行以及复杂的数据流转，是整个自动化平台的核心运行时组件。\n\n工作流执行引擎的核心职责包括：\n\n1. **DAG 构建**：将用户配置的工作流转换为可执行的有向无环图结构\n2. **触发器管理**：支持手动、API、Webhook、定时调度等多种触发方式\n3. **块执行编排**：按照依赖关系顺序执行各个功能块\n4. **状态管理**：维护执行过程中的状态，支持暂停、恢复和快照\n5. **输出处理**：管理块之间的数据传递和变量绑定\n\n资料来源：[apps/sim/executor/orchestrators](https://github.com/simstudioai/sim/blob/main/apps/sim/executor/orchestrators)\n\n---\n\n## 核心架构\n\n### 执行引擎分层\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ 触发层 (Triggers) │\n│ 手动触发 │ API触发 │ Webhook触发 │ 定时调度 │ 聊天触发 │\n└─────────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ 编排层 (Orchestrators) │\n│ 循环编排器 │ 并行编排器 │ 顺序编排器 │\n└─────────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ 执行层 (Execution Engine) │\n│ DAG构建器 │ 执行器 │ 快照管理 │\n└─────────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ 沙箱层 (Sandbox) │\n│ 块代码执行环境 │ 工具函数调用 │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### 触发器优先级系统\n\n触发器系统采用优先级评分机制来选择最佳触发路径。当工作流存在多个可能的触发点时，系统按以下顺序选择：\n\n| 优先级 | 触发路径 | 说明 |\n|--------|----------|------|\n| 0 | `UNIFIED` | 统一入口块，最优先 |\n| 1 | `LEGACY_STARTER` | 传统起始块，兼容旧版本 |\n| 2 | `EXTERNAL_TRIGGER` (schedule) | 定时调度触发器 |\n| 3 | `EXTERNAL_TRIGGER` (其他) | Webhook 及外部集成触发 |\n| 4 | `SPLIT_API` | API 拆分触发 |\n| 5 | `SPLIT_INPUT` | 输入拆分触发 |\n| 6 | `SPLIT_MANUAL` | 手动拆分触发 |\n| 7 | `SPLIT_CHAT` | 聊天拆分触发 |\n| 99 | 未知 | 兜底默认值 |\n\n资料来源：[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)\n\n---\n\n## 触发器系统\n\n### 触发类型\n\nSim 平台定义了以下触发类型：\n\n```typescript\nexport const TRIGGER_TYPES = {\n START: 'start',\n API: 'api',\n CHAT: 'chat',\n STARTER: 'starter',\n} as const\n```\n\n### 启动模式\n\n每个触发块支持三种启动模式：\n\n| 模式值 | 说明 | 触发路径 |\n|--------|------|----------|\n| `manual` | 手动触发 | 启动模式为 undefined 或 'manual' |\n| `api` | API 调用触发 | 启动模式为 'api' 或 'run' |\n| `chat` | 聊天会话触发 | 启动模式为 'chat' |\n\n资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:1-20](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/triggers/triggers.ts)\n\n### 触发器引用别名\n\n系统提供别名映射，简化内联引用：\n\n```typescript\nexport const TRIGGER_REFERENCE_ALIAS_MAP = {\n start: TRIGGER_TYPES.START,\n api: TRIGGER_TYPES.API,\n chat: TRIGGER_TYPES.CHAT,\n manual: TRIGGER_TYPES.START,\n} as const\n```\n\n### 触发器工具类\n\n`TriggerUtils` 类提供静态方法用于触发器识别：\n\n| 方法 | 用途 |\n|------|------|\n| `isTriggerBlock(block)` | 判断块是否为任意类型的触发器 |\n| `isTriggerType(block, triggerType)` | 判断块是否为指定类型的触发器 |\n\n判断逻辑包括三个维度：\n\n1. 显式分类：块配置的 `category === 'triggers'`\n2. 触发模式标志：`block.triggerMode === true`\n3. 遗留兼容：`block.type === TRIGGER_TYPES.STARTER`\n\n资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:40-55](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/triggers/triggers.ts)\n\n### 模拟负载判断\n\n对于外部触发器，系统需要判断是否需要生成模拟负载：\n\n```typescript\nexport function triggerNeedsMockPayload(\n trigger: StartBlockCandidate\n): boolean {\n // 只有 webhook 和外部集成需要模拟负载\n // 定时调度正常运行，无需模拟数据\n return trigger.path === StartBlockPath.EXTERNAL_TRIGGER && trigger.block.type !== 'schedule'\n}\n```\n\n资料来源：[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)\n\n---\n\n## DAG 执行图构建\n\n### 块类型系统\n\n执行引擎通过块注册表管理所有可用块：\n\n```typescript\n// 测试中的 Mock 配置示例\nvi.mock('@/blocks', () => ({\n getBlock: () => null,\n getAllBlocks: () => ({}),\n getAllBlockTypes: () => [],\n getBlockByToolName: () => null,\n getBlocksByCategory: () => [],\n isValidBlockType: () => false,\n registry: {},\n}))\n```\n\n### 块分类\n\n块按功能分为多个类别：\n\n| 分类 | 说明 | 示例 |\n|------|------|------|\n| `triggers` | 触发器块 | 定时调度、Webhook、API |\n| `actions` | 动作块 | 发送消息、调用API |\n| `logic` | 逻辑块 | 条件判断、循环 |\n| `transform` | 转换块 | 数据转换、映射 |\n\n### 循环与并行\n\n系统支持两种高级执行模式：\n\n```typescript\n// 循环块生成\ngenerateLoopBlocks: () => ({})\n\n// 并行块生成\ngenerateParallelBlocks: () => ({})\n```\n\n---\n\n## 执行状态管理\n\n### 快照机制\n\n执行引擎支持执行快照功能，允许暂停和恢复工作流执行：\n\n```typescript\nvi.mock('@/lib/workflows/blocks/block-outputs', () => ({\n getEffectiveBlockOutputs: () => ({}),\n}))\n```\n\n快照功能涉及：\n\n- 块输出状态持久化\n- 执行进度记录\n- 变量上下文保存\n\n资料来源：[apps/sim/executor/execution/snapshot.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/executor/execution/snapshot.ts)\n\n### 执行维度\n\n执行引擎定义了块执行的约束维度：\n\n```typescript\nvi.mock('@/executor/constants', () => ({\n isAnnotationOnlyBlock: () => false,\n BLOCK_DIMENSIONS: { MIN_HEIGHT: 100 },\n HANDLE_POSITIONS: {},\n}))\n```\n\n---\n\n## Webhook 事件处理\n\n### 待验证 Webhook\n\n系统为不同提供商实现了 webhook 验证机制：\n\n| 提供商 | 验证策略 |\n|--------|----------|\n| `ashby` | 始终通过（仅 ping） |\n| `grain` | GET/HEAD 请求直接通过 |\n| `generic` | `verifyTestEvents` 元数据为 true 时通过 |\n| `salesforce` | GET/HEAD 请求直接通过 |\n\n```typescript\nconst pendingWebhookVerificationProbeMatchers: Record<\n string,\n PendingWebhookVerificationProbeMatcher\n> = {\n ashby: ({ method, body }) => method === 'POST' && body?.action === 'ping',\n grain: ({ method, body }) =>\n method === 'GET' ||\n method === 'HEAD' ||\n (method === 'POST' && (!body || Object.keys(body).length === 0 || !body.type)),\n generic: ({ method, body }) =>\n method === 'GET' ||\n method === 'HEAD' ||\n (method === 'POST' && (!body || Object.keys(body).length === 0)),\n salesforce: ({ method, body }) =>\n method === 'GET' ||\n method === 'HEAD' ||\n (method === 'POST' && (!body || Object.keys(body).length === 0)),\n}\n```\n\n资料来源：[apps/sim/lib/webhooks/pending-verification.ts:1-30](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/pending-verification.ts)\n\n---\n\n## 执行流程图\n\n### 完整执行生命周期\n\n```mermaid\ngraph TD\n A[工作流启动] --> B{选择触发器}\n B -->|手动| C[manual 模式]\n B -->|API| D[api 模式]\n B -->|Webhook| E[external_trigger 模式]\n B -->|定时| F[schedule 模式]\n B -->|聊天| G[chat 模式]\n \n C --> H[DAG 构建]\n D --> H\n E --> H\n F --> H\n G --> H\n \n H --> I{检查循环块}\n I -->|是| J[展开循环迭代]\n I -->|否| K{检查并行块}\n J --> K\n K -->|是| L[并行执行分支]\n K -->|否| M[顺序执行]\n \n L --> N[收集块输出]\n M --> N\n N --> O[数据传递]\n O --> P{还有更多块?}\n P -->|是| I\n P -->|否| Q[生成执行快照]\n Q --> R[工作流完成]\n```\n\n---\n\n## 配置与常量\n\n### 执行常量定义\n\n| 常量 | 说明 | 默认值 |\n|------|------|--------|\n| `BLOCK_DIMENSIONS.MIN_HEIGHT` | 块最小高度 | 100 |\n| `HANDLE_POSITIONS` | 连接点位置配置 | 空对象 |\n\n### 环境配置\n\n执行引擎使用统一的环境配置系统：\n\n```typescript\nvi.mock('@/lib/core/config/env', () => createEnvMock())\n```\n\n环境变量支持类型转换和默认值：\n\n```typescript\nenvNumber: (\n value: number | string | undefined | null,\n fallback: number,\n options: { min?: number } = {}\n): number => {\n const min = options.min ?? 0\n if (typeof value === 'number' && Number.isFinite(value) && value >= min) return value\n if (value === undefined || value === null || value === '') return fallback\n const parsed = Number(value)\n return Number.isFinite(parsed) && parsed >= min ? parsed : fallback\n}\n```\n\n资料来源：[packages/testing/src/mocks/env.mock.ts:1-50](https://github.com/simstudioai/sim/blob/main/packages/testing/src/mocks/env.mock.ts)\n\n---\n\n## 测试与调试\n\n### 执行引擎测试\n\n项目使用 Vitest 作为测试框架：\n\n```bash\nbun run test # 运行所有测试\nbun run test:watch # 监听模式\nbun run test:coverage # 覆盖率报告\n```\n\n### 常见 Mock 配置\n\n在测试中，核心模块通过以下方式隔离：\n\n```typescript\nvi.mock('@/stores/workflows/registry/store', () => ({\n useWorkflowRegistry: {\n getState: () => ({\n activeWorkflowId: null,\n }),\n },\n}))\n\nvi.mock('@/tools/utils', () => ({\n getTool: () => null,\n}))\n\nvi.mock('@/lib/workflows/subblocks/visibility', () => ({\n buildDefaultCanonicalModes: () => ({}),\n}))\n```\n\n资料来源：[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)\n\n---\n\n## 最佳实践\n\n### 触发器选择\n\n1. **优先使用统一入口**：对于新工作流，使用 `UNIFIED` 触发器\n2. **外部集成用 Webhook**：需要接收外部事件时使用 `EXTERNAL_TRIGGER`\n3. **定时任务用 Schedule**：周期性任务使用 schedule 类型触发器\n\n### 执行性能\n\n1. **减少循环嵌套深度**：深层循环会影响执行性能\n2. **合理使用并行块**：独立任务应使用并行执行\n3. **优化块输出**：避免传递过大的数据对象\n\n### 错误处理\n\n1. **配置超时时间**：为长时间运行的块设置合理超时\n2. **使用条件块**：在关键路径添加条件判断\n3. **利用快照恢复**：定期保存执行快照以便故障恢复\n\n---\n\n\n\n## 块系统与注册表\n\n### 相关页面\n\n相关主题：[工作流执行引擎](#page-workflow-execution), [连接器框架](#page-connectors)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [apps/sim/lib/workflows/triggers/triggers.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/triggers/triggers.ts)\n- [apps/sim/lib/workflows/sanitization/subblocks.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/sanitization/subblocks.ts)\n
\n\n# 块系统与注册表\n\n## 概述\n\n块系统（Block System）是 Sim 工作流平台的核心组件化架构，用于定义和执行业务逻辑。每个块代表一个独立的功能单元，可通过可视化编辑器组合成复杂的工作流程。\n\n块注册表（Block Registry）提供统一的块发现、检索和验证机制，确保工作流引擎能够正确识别和执行各类块。\n\n## 核心概念\n\n### 块的定义\n\n块是 Sim 平台中最小的可配置功能单元，包含以下关键属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `type` | `string` | 块的唯一标识符 |\n| `category` | `string` | 块所属的分类，如 `triggers` |\n| `triggerMode` | `boolean` | 是否为触发器模式 |\n| `subBlocks` | `Record` | 子块配置 |\n\n### 触发器块\n\n触发器块是特殊类型的块，用于启动工作流执行。Sim 支持多种触发模式：\n\n```typescript\ntype TriggerMode = 'manual' | 'api' | 'chat'\n```\n\n根据触发模式的不同，工作流可以通过以下方式启动：\n\n- **manual（手动）**: 用户通过界面手动触发\n- **api（API）**: 通过外部 API 调用触发\n- **chat（对话）**: 通过聊天接口触发\n\n## 注册表架构\n\n### 块发现接口\n\n注册表提供了完整的块发现 API，支持多种查询方式：\n\n```typescript\n// 根据类型获取块\ngetBlock(type: string): BlockConfig | null\n\n// 获取所有块\ngetAllBlocks(): Record\n\n// 获取所有块类型\ngetAllBlockTypes(): BlockType[]\n\n// 根据工具名称获取块\ngetBlockByToolName(toolName: string): BlockConfig | null\n\n// 根据分类获取块\ngetBlocksByCategory(category: string): BlockConfig[]\n\n// 验证块类型是否有效\nisValidBlockType(type: string): boolean\n```\n\n### 注册表结构\n\n注册表采用单例模式设计，通过 `registry` 对象集中管理所有块定义：\n\n```typescript\n// 资料来源：apps/sim/lib/workflows/diff/diff-engine.test.ts:1-50\nvi.mock('@/blocks', () => ({\n getBlock: () => null,\n getAllBlocks: () => ({}),\n getAllBlockTypes: () => [],\n getBlockByToolName: () => null,\n getBlocksByCategory: () => [],\n isValidBlockType: () => false,\n registry: {},\n}))\n```\n\n## 触发器系统\n\n### TriggerUtils 工具类\n\n`TriggerUtils` 提供了一系列静态方法用于处理触发器块的判断和分类：\n\n```typescript\n// 资料来源：apps/sim/lib/workflows/triggers/triggers.ts:1-50\nexport class TriggerUtils {\n static isTriggerBlock(block: { type: string; triggerMode?: boolean }): boolean {\n const blockConfig = getBlock(block.type)\n\n return (\n // 新触发器块（显式分类）\n blockConfig?.category === 'triggers' ||\n // 启用触发器模式的块\n block.triggerMode === true ||\n // 遗留的启动器块\n block.type === TRIGGER_TYPES.STARTER\n )\n }\n\n static isTriggerType(block: { type: string }, triggerType: TriggerType): boolean {\n return block.type === triggerType\n }\n}\n```\n\n### 触发器类型映射\n\n系统定义了触发器类型的别名映射，便于在引用中使用：\n\n```typescript\n// 资料来源：apps/sim/lib/workflows/triggers/triggers.ts:1-30\nexport const TRIGGER_REFERENCE_ALIAS_MAP = {\n start: TRIGGER_TYPES.START,\n api: TRIGGER_TYPES.API,\n chat: TRIGGER_TYPES.CHAT,\n manual: TRIGGER_TYPES.START,\n} as const\n\nexport type TriggerReferenceAlias = keyof typeof TRIGGER_REFERENCE_ALIAS_MAP\n```\n\n## 子块系统\n\n### 子块结构\n\n子块（SubBlocks）允许在父块内部定义可配置的子单元。每个子块包含：\n\n| 属性 | 说明 |\n|------|------|\n| `id` | 子块的唯一标识符 |\n| `type` | 子块的类型 |\n| `value` | 子块的当前值 |\n\n### 子块验证与修复\n\n系统提供自动化的子块数据校验和修复机制：\n\n```typescript\n// 资料来源：apps/sim/lib/workflows/sanitization/subblocks.ts:1-60\nconst typeFromConfig =\n configuredType || blockConfig?.subBlocks?.find((config) => config.id === id)?.type\n\nconst missingMetadata =\n typeof subBlock.id !== 'string' ||\n subBlock.id.length === 0 ||\n typeof subBlock.type !== 'string' ||\n subBlock.type.length === 0\n\nif (missingMetadata && !typeFromConfig) {\n logger.warn('Skipping malformed subBlock: unrecognized metadata entry', {\n blockId: block.id,\n subBlockId,\n })\n changed = true\n continue\n}\n```\n\n### 空值处理\n\n子块系统支持将空字符串转换为 `null` 的选项：\n\n```typescript\nconst hasValue = Object.hasOwn(subBlock, 'value')\nconst value =\n options.convertEmptyStringToNull && subBlock.value === ''\n ? null\n : hasValue\n ? subBlock.value\n : null\n```\n\n## 块的分类体系\n\n### 分类结构\n\n块按照功能进行分类管理，主要分类包括：\n\n| 分类 | 说明 |\n|------|------|\n| `triggers` | 触发器块，用于启动工作流 |\n| `actions` | 动作块，执行具体操作 |\n| `conditions` | 条件块，控制流程分支 |\n| `transforms` | 转换块，数据处理和转换 |\n\n### 分类查询\n\n通过 `getBlocksByCategory` 方法可以获取指定分类下的所有块：\n\n```typescript\n// 返回指定分类的所有块配置\ngetBlocksByCategory('triggers'): BlockConfig[]\n```\n\n## 工作流集成\n\n### 执行上下文\n\n块在工作流执行时通过注册表获取块配置：\n\n```mermaid\ngraph TD\n A[工作流引擎] --> B[块注册表]\n B --> C[getBlock type]\n C --> D[BlockConfig]\n D --> E[执行块逻辑]\n \n B --> F[getBlocksByCategory]\n F --> G[分类块列表]\n \n B --> H[isValidBlockType]\n H --> I[布尔验证结果]\n```\n\n### 触发器判断流程\n\n在执行工作流时，系统通过以下逻辑判断是否为触发器块：\n\n```mermaid\ngraph TD\n A[检查块配置] --> B{category === 'triggers'}\n B -->|是| E[是触发器块]\n B -->|否| C{triggerMode === true}\n C -->|是| E\n C -->|否| D{type === STARTER}\n D -->|是| E\n D -->|否| F[不是触发器块]\n```\n\n## 注册表初始化\n\n### 模块导出\n\n注册表通过统一的入口模块导出所有块相关的接口：\n\n```typescript\n// apps/sim/blocks/index.ts\nexport {\n registry,\n getBlock,\n getAllBlocks,\n getAllBlockTypes,\n getBlockByToolName,\n getBlocksByCategory,\n isValidBlockType,\n // ...\n}\n```\n\n### 类型定义\n\n系统通过类型定义文件提供完整的类型安全支持：\n\n```typescript\n// apps/sim/blocks/types.ts\nexport interface BlockConfig {\n type: string\n category: string\n name: string\n description?: string\n inputs?: InputSchema\n outputs?: OutputSchema\n config?: ConfigSchema\n subBlocks?: SubBlockDefinition[]\n}\n\nexport interface SubBlockDefinition {\n id: string\n type: string\n label?: string\n defaultValue?: unknown\n}\n```\n\n## 测试支持\n\n### Mock 配置\n\n在单元测试中，注册表模块可以被完全 Mock：\n\n```typescript\n// 资料来源：apps/sim/lib/workflows/diff/diff-engine.test.ts:1-50\nvi.mock('@/blocks', () => ({\n getBlock: () => null,\n getAllBlocks: () => ({}),\n getAllBlockTypes: () => [],\n getBlockByToolName: () => null,\n getBlocksByCategory: () => [],\n isValidBlockType: () => false,\n registry: {},\n}))\n```\n\n这种设计允许测试环境独立于实际块定义进行隔离测试。\n\n## 最佳实践\n\n### 块定义规范\n\n1. **唯一标识**: 每个块必须具有全局唯一的 `type` 标识符\n2. **明确分类**: 通过 `category` 属性声明块的所属分类\n3. **类型安全**: 使用 TypeScript 接口定义块的结构\n4. **配置验证**: 在注册表中验证块的配置完整性\n\n### 子块使用建议\n\n1. **默认值**: 为子块提供合理的默认值\n2. **类型约束**: 明确子块的类型定义\n3. **空值处理**: 使用 `convertEmptyStringToNull` 选项统一空值语义\n4. **日志记录**: 对异常子块数据进行日志记录以便排查\n\n## 相关资源\n\n- 块定义目录：`apps/sim/blocks/blocks/`\n- 块类型定义：`apps/sim/blocks/types.ts`\n- 块注册表实现：`apps/sim/blocks/registry.ts`\n- 触发器工具类：`apps/sim/lib/workflows/triggers/triggers.ts`\n\n---\n\n\n\n## 代理与AI集成\n\n### 相关页面\n\n相关主题：[工作流执行引擎](#page-workflow-execution), [块系统与注册表](#page-block-registry)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/simstudioai/sim/blob/main/README.md) — 项目主说明文件\n- [apps/sim/lib/workflows/triggers/triggers.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/triggers/triggers.ts) — 工作流触发器实现\n- [apps/sim/lib/copilot/request/session/contract.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/copilot/request/session/contract.ts) — Copilot 会话协议定义\n- [apps/sim/lib/core/security/input-validation.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/core/security/input-validation.ts) — 输入验证与安全模块\n- [apps/sim/lib/api/contracts/types.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/api/contracts/types.ts) — API 契约类型定义\n- [packages/testing/src/mocks/env.mock.ts](https://github.com/simstudioai/sim/blob/main/packages/testing/src/mocks/env.mock.ts) — 测试环境模拟\n\n> **注意**：以下代理核心文件未在当前检索上下文中找到：agent.ts、agent-handler.ts、memory.ts、skills-resolver.ts、types.ts。这些文件的缺失意味着本文档基于可用的上下文信息进行编写。\n
\n\n# 代理与AI集成\n\n## 概述\n\nSim 是一个开源平台，用于构建 AI 代理（Agent）并运行代理工作流。该平台连接超过 1000 个集成和 LLM，以编排代理工作流 资料来源：[README.md:1]。\n\nSim 的代理系统通过模块化架构实现，支持多种触发模式、工作流编排、以及与外部工具和 API 的深度集成。代理作为平台的核心执行单元，能够根据配置执行复杂的多步骤任务。\n\n## 核心架构\n\n### 代理与触发器关系\n\nSim 中的代理与触发器紧密耦合。触发器定义了代理何时以及如何被激活，而代理则负责执行业务逻辑。\n\n```mermaid\ngraph TD\n A[触发器 Trigger] --> B[触发模式 Trigger Mode]\n B --> C[manual 手动]\n B --> D[api API调用]\n B --> E[chat 聊天]\n A --> F[代理 Agent]\n F --> G[执行逻辑]\n G --> H[输出结果]\n```\n\n根据触发器实现，代理支持三种触发模式 资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:1-20]：\n\n| 触发模式 | 描述 | 触发方式 |\n|---------|------|---------|\n| `manual` | 手动触发 | 用户通过界面手动启动 |\n| `api` | API 触发 | 通过 HTTP 请求或 `run` 参数触发 |\n| `chat` | 聊天触发 | 通过对话交互触发 |\n\n触发模式通过 `readSubBlockValue(block.subBlocks, 'startWorkflow')` 读取，返回值为 `'chat'`、`'api'`、`'run'` 或 `'manual'` 资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:5-14]。\n\n### 代理块识别机制\n\nSim 使用 `TriggerUtils` 类提供统一的触发器检查功能 资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:35-55]：\n\n```typescript\nstatic isTriggerBlock(block: { type: string; triggerMode?: boolean }): boolean {\n const blockConfig = getBlock(block.type)\n return (\n blockConfig?.category === 'triggers' ||\n block.triggerMode === true ||\n block.type === TRIGGER_TYPES.STARTER\n )\n}\n```\n\n## 代理执行模型\n\n### 会话与流式处理\n\nSim 的代理系统支持流式输出，通过会话协议处理实时的代理响应。协议定义包括合成文件预览、流式引用追踪等高级功能 资料来源：[apps/sim/lib/copilot/request/session/contract.ts:1-50]。\n\n流式数据验证包括：\n\n| 验证项 | 类型 | 说明 |\n|-------|------|------|\n| `seq` | number | 序列号 |\n| `ts` | string | 时间戳 |\n| `stream` | StreamRef | 流引用 |\n| `trace` | Trace | 可选追踪信息 |\n| `scope` | StreamScope | 可选作用域 |\n\n### 文件预览集成\n\n代理执行过程中支持文件操作预览，包括新建文件、编辑元数据、完整内容展示等阶段 资料来源：[apps/sim/lib/copilot/request/session/contract.ts:60-90]：\n\n| 预览阶段 | 触发条件 |\n|---------|---------|\n| `start` | 预览开始 |\n| `target` | 文件操作目标确定 |\n| `editMeta` | 元数据编辑 |\n| `content` | 内容展示 |\n\n## 安全与输入验证\n\n### 代理参数验证\n\n所有代理输入必须经过严格验证，Sim 提供了多种验证器确保安全性 资料来源：[apps/sim/lib/core/security/input-validation.ts:1-80]：\n\n#### 枚举值验证\n\n```typescript\nvalidateEnum(\n value: string | null | undefined,\n allowedValues: readonly T[],\n paramName?: string\n): ValidationResult\n```\n\n此验证器确保代理接收的参数在允许的范围内，防止注入攻击 资料来源：[apps/sim/lib/core/security/input-validation.ts:50-75]。\n\n#### 主机名验证\n\n用于防止 SSRF（服务器端请求伪造）攻击，验证主机名不是私有 IP、本地地址或其他保留地址 资料来源：[apps/sim/lib/core/security/input-validation.ts:80-130]：\n\n| 检查项 | 描述 |\n|-------|------|\n| 私有 IP | 10.x.x.x, 172.16-31.x.x, 192.168.x.x |\n| 本地地址 | localhost, 127.0.0.1 |\n| 保留地址 | 0.0.0.0,169.254.x.x |\n\n## API 契约类型系统\n\nSim 使用强类型 API 契约定义代理与外部系统的交互 资料来源：[apps/sim/lib/api/contracts/types.ts:1-50]：\n\n### 契约参数类型\n\n| 类型别名 | 用途 |\n|---------|------|\n| `ContractParams` | 路由参数 |\n| `ContractQuery` | 查询参数 |\n| `ContractBody` | 请求体参数 |\n| `ContractHeaders` | 请求头参数 |\n\n这些类型通过泛型推断自动从 `ApiRouteContract` 提取对应的 Schema 类型 资料来源：[apps/sim/lib/api/contracts/types.ts:20-45]。\n\n## 工作流编排\n\n### 触发器分类\n\nSim 的工作流通过触发器类型进行分类管理 资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:25-35]：\n\n```mermaid\ngraph LR\n A[START] --> B[入口触发]\n C[API] --> D[API触发]\n E[CHAT] --> F[聊天触发]\n G[STARTER] --> H[遗留触发器]\n```\n\n### 触发引用别名\n\n平台定义了别名映射，简化跨系统的触发器引用 资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:18-24]：\n\n```typescript\nexport const TRIGGER_REFERENCE_ALIAS_MAP = {\n start: TRIGGER_TYPES.START,\n api: TRIGGER_TYPES.API,\n chat: TRIGGER_TYPES.CHAT,\n manual: TRIGGER_TYPES.START,\n} as const\n```\n\n## 环境配置与测试\n\n### 代理运行环境\n\nSim 的代理支持多种运行环境配置，通过环境变量管理 资料来源：[packages/testing/src/mocks/env.mock.ts:1-40]：\n\n| 环境函数 | 描述 |\n|---------|------|\n| `getEnv` | 获取环境变量值 |\n| `isTruthy` | 检查真值 |\n| `isFalsy` | 检查假值 |\n| `envNumber` | 获取数值并支持最小值约束 |\n\n```typescript\nenvNumber(\n value: number | string | undefined | null,\n fallback: number,\n options: { min?: number } = {}\n): number\n```\n\n## 部署模式\n\n### 本地模型支持\n\nSim 支持通过 Ollama 和 vLLM 运行本地模型，为代理提供灵活的 AI 后端选择 资料来源：[README.md:1]。\n\n### 部署方式\n\n| 方式 | 说明 | 适用场景 |\n|-----|------|---------|\n| Docker | 一键部署 | 快速启动 |\n| Docker Compose | 完整生产环境 | 自托管部署 |\n| 手动配置 | 自定义设置 | 高级用户 |\n\n## 总结\n\nSim 的代理与 AI 集成系统采用模块化设计，通过触发器机制实现灵活的代理激活方式，支持手动、API 和聊天三种触发模式。系统内置完善的输入验证和安全防护，使用强类型 API 契约确保通信可靠性，并支持本地和云端多种 AI 模型后端。\n\n代理作为平台的核心执行单元，通过工作流编排实现复杂任务的自动化处理，同时保持高度的可扩展性和安全边界控制。\n\n---\n\n\n\n## 工作流编辑器\n\n### 相关页面\n\n相关主题：[实时协作与UI组件](#page-realtime-ui), [系统架构](#page-system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [apps/sim/lib/workflows/triggers/triggers.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/triggers/triggers.ts)\n- [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)\n- [apps/sim/lib/workflows/sanitization/validation.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/sanitization/validation.ts)\n- [apps/sim/lib/a2a/agent-card.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/a2a/agent-card.ts)\n- [packages/ts-sdk/README.md](https://github.com/simstudioai/sim/blob/main/packages/ts-sdk/README.md)\n- [packages/python-sdk/README.md](https://github.com/simstudioai/sim/blob/main/packages/python-sdk/README.md)\n- [scripts/README.md](https://github.com/simstudioai/sim/blob/main/scripts/README.md)\n
\n\n# 工作流编辑器\n\n## 概述\n\n工作流编辑器（Workflow Editor）是 Sim 平台的核心组件，用于可视化构建、配置和管理自动化工作流。该编辑器允许用户通过组合不同的 **块（Blocks）** 和 **触发器（Triggers）** 来创建复杂的自动化流程。\n\n工作流编辑器的主要职责包括：\n\n- 提供可视化的块编排界面\n- 管理工作流状态和配置\n- 处理触发器类型（手动、API、聊天）\n- 执行工作流验证和清理\n- 生成 A2A（Agent-to-Agent）协议兼容的代理卡片\n\n资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:1-50]()\n\n## 架构概览\n\n```mermaid\ngraph TD\n subgraph 工作流编辑器\n A[工作流编辑器 UI] --> B[块管理器]\n A --> C[触发器管理器]\n A --> D[验证引擎]\n end\n \n subgraph 块系统\n B --> E[块注册表]\n B --> F[子块配置]\n E --> G[块类型]\n G --> G1[Triggers]\n G --> G2[Actions]\n G --> G3[Logic]\n end\n \n subgraph 触发器系统\n C --> H[触发器类型]\n H --> H1[手动触发 Manual]\n H --> H2[API 触发 Api]\n H --> H3[聊天触发 Chat]\n end\n \n subgraph 执行层\n D --> I[工作流执行器]\n I --> J[沙箱执行环境]\n end\n```\n\n## 触发器系统\n\n触发器是工作流的入口点，决定了工作流的激活方式。Sim 平台支持三种主要的触发器类型。\n\n### 触发器类型\n\n| 触发器类型 | 值 | 说明 | 适用场景 |\n|-----------|-----|------|---------|\n| 手动触发 | `manual` | 用户通过界面手动启动 | 调试、测试、临时执行 |\n| API 触发 | `api` / `run` | 通过 API 接口调用触发 | 外部系统集成、Webhook |\n| 聊天触发 | `chat` | 通过聊天界面交互触发 | 对话式自动化 |\n\n资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:35-50]()\n\n### 触发器类型常量\n\n```typescript\nexport const TRIGGER_TYPES = {\n START: 'start',\n INPUT: 'input',\n API: 'api_trigger',\n CHAT: 'chat_trigger',\n MANUAL: 'manual_trigger',\n STARTER: 'starter', // 遗留类型\n} as const\n```\n\n### 触发器判断方法\n\n`TriggerUtils` 类提供了静态方法来判断块是否为触发器：\n\n```typescript\nexport class TriggerUtils {\n // 判断是否为触发器块\n static isTriggerBlock(block: { type: string; triggerMode?: boolean }): boolean\n \n // 判断是否为特定触发器类型\n static isTriggerType(block: { type: string }, triggerType: TriggerType): boolean\n \n // 判断是否为手动触发器\n static isManualTrigger(block: { type: string; subBlocks?: any }): boolean\n \n // 判断是否为 API 触发器\n static isApiTrigger(block: { type: string; subBlocks?: any }, isChildWorkflow?: boolean): boolean\n}\n```\n\n### 触发器引用别名\n\n系统支持通过别名引用触发器：\n\n```typescript\nexport const TRIGGER_REFERENCE_ALIAS_MAP = {\n start: TRIGGER_TYPES.START,\n api: TRIGGER_TYPES.API,\n chat: TRIGGER_TYPES.CHAT,\n manual: TRIGGER_TYPES.START,\n} as const\n```\n\n资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:55-75]()\n\n## 块系统\n\n块（Block）是工作流编辑器的基本构建单元，每个块代表一个具体的操作或功能。\n\n### 块注册表\n\n块通过注册表进行统一管理，提供以下查询接口：\n\n```typescript\n// 获取单个块\ngetBlock(type: string): BlockConfig | null\n\n// 获取所有块\ngetAllBlocks(): Record\n\n// 获取所有块类型\ngetAllBlockTypes(): BlockConfig[]\n\n// 通过工具名称获取块\ngetBlockByToolName(toolName: string): BlockConfig | null\n\n// 按类别获取块\ngetBlocksByCategory(category: string): BlockConfig[]\n\n// 验证块类型是否有效\nisValidBlockType(type: string): boolean\n```\n\n### 块类别\n\n| 类别 | 说明 | 示例 |\n|-----|------|------|\n| `triggers` | 触发器块 | Start、API Trigger、Manual Trigger |\n| `actions` | 操作块 | HTTP 请求、数据处理 |\n| `logic` | 逻辑块 | 条件判断、循环 |\n\n资料来源：[apps/sim/lib/workflows/diff/diff-engine.test.ts:15-30]()\n\n### 子块配置\n\n每个块可以包含多个子块（Sub-Blocks），用于配置块的详细行为：\n\n```typescript\ninterface SubBlockState {\n value: unknown\n visible?: boolean\n annotation?: string\n}\n```\n\n### 块输出管理\n\n块输出（Block Outputs）用于在工作流中传递数据：\n\n```typescript\ngetEffectiveBlockOutputs(blockId: string): Record\n```\n\n资料来源：[apps/sim/lib/workflows/diff/diff-engine.test.ts:35-40]()\n\n## 工作流验证与清理\n\n工作流在保存或执行前需要经过验证和清理流程。\n\n### 验证流程\n\n```mermaid\ngraph TD\n A[工作流状态] --> B[验证块引用]\n B --> C[验证触发器配置]\n C --> D[清理工具配置]\n D --> E[验证工具 Schema]\n E --> F[返回验证结果]\n \n B -->|失败| G[记录错误]\n C -->|失败| G\n D -->|失败| G\n E -->|失败| G\n```\n\n### 验证结果类型\n\n```typescript\nexport interface WorkflowValidationResult {\n valid: boolean // 是否有效\n errors: string[] // 错误列表\n warnings: string[] // 警告列表\n sanitizedState?: WorkflowState // 清理后的状态\n}\n```\n\n### 清理规则\n\n| 规则类型 | 处理方式 | 说明 |\n|---------|---------|------|\n| 自定义工具 ID | `customToolId` | 确保工具标识唯一 |\n| Schema 验证 | `schema` | 验证工具输入输出定义 |\n| 引用工具 | `usageControl` | 设置默认值 `auto` |\n| 内联工具 | `code` | 确保代码字段存在 |\n\n### 工具清理流程\n\n```typescript\n.map((tool: unknown) => {\n if (isRecord(tool) && tool.type === 'custom-tool') {\n // 引用工具：确保 usageControl 默认值\n if (!tool.usageControl) {\n tool.usageControl = 'auto'\n }\n // 内联工具：确保 code 字段\n if (!tool.customToolId && (!tool.code || typeof tool.code !== 'string')) {\n tool.code = ''\n }\n }\n return tool\n})\n```\n\n资料来源：[apps/sim/lib/workflows/sanitization/validation.ts:1-80]()\n\n## A2A 代理集成\n\n工作流编辑器支持通过 A2A（Agent-to-Agent）协议与其他代理系统集成。\n\n### 代理卡片生成\n\n每个工作流可以生成对应的代理卡片，用于服务发现和能力描述：\n\n```typescript\nexport function generateAgentCard(\n agent: AgentConfig,\n workflow: WorkflowConfig,\n baseUrl: string\n): AppAgentCard\n```\n\n### 代理技能定义\n\n```typescript\nexport function generateSkillsFromWorkflow(\n workflowName: string,\n workflowDescription: string | null,\n tags?: string[]\n): AgentSkill[] {\n return [{\n id: 'execute',\n name: `Execute ${workflowName}`,\n description: workflowDescription || `Execute the ${workflowName} workflow`,\n tags: tags || [],\n }]\n}\n```\n\n### 代理卡片验证\n\n```typescript\nexport function validateAgentCard(card: unknown): card is AppAgentCard {\n if (!card || typeof card !== 'object') return false\n \n const c = card as Record\n if (typeof c.name !== 'string' || !c.name) return false\n if (typeof c.url !== 'string' || !c.url) return false\n // ... 更多验证\n}\n```\n\n资料来源：[apps/sim/lib/a2a/agent-card.ts:1-80]()\n\n## 工作流执行\n\n### 执行模式\n\n| 模式 | 说明 | 适用场景 |\n|-----|------|---------|\n| 同步执行 | 等待执行完成返回结果 | 实时响应、快速验证 |\n| 异步执行 | 立即返回任务 ID，后续查询状态 | 长时间运行、外部集成 |\n\n### 执行选项\n\n```typescript\ninterface ExecutionOptions {\n timeout?: number // 超时时间（毫秒）\n stream?: boolean // 是否启用流式输出\n selectedOutputs?: string[] // 选择性输出字段\n async?: boolean // 异步执行模式\n}\n\ninterface RetryOptions {\n maxRetries?: number // 最大重试次数\n initialDelay?: number // 初始延迟\n maxDelay?: number // 最大延迟\n backoffMultiplier?: number // 退避乘数\n}\n```\n\n### 执行结果\n\n```typescript\ninterface WorkflowExecutionResult {\n success: boolean // 是否成功\n output?: any // 输出数据\n error?: string // 错误信息\n logs?: list // 执行日志\n metadata?: Dict // 元数据\n trace_spans?: list // 追踪跨度\n total_duration?: float // 总耗时\n}\n\ninterface AsyncExecutionResult {\n success: boolean // 是否成功\n task_id: str // 任务 ID\n status: 'queued' // 状态\n created_at: str // 创建时间\n links: Dict[str, str] // 相关链接\n}\n```\n\n### 执行常量\n\n```typescript\n// 注释专用块\nisAnnotationOnlyBlock(): boolean\n\n// 块尺寸限制\nBLOCK_DIMENSIONS = { MIN_HEIGHT: 100 }\n\n// 句柄位置\nHANDLE_POSITIONS = {}\n```\n\n资料来源：[apps/sim/lib/workflows/diff/diff-engine.test.ts:45-55]()\n\n## 块文档生成\n\n工作流编辑器包含自动化文档生成功能。\n\n### 文档生成流程\n\n```mermaid\ngraph TD\n A[扫描块目录] --> B[提取元数据]\n B --> C[生成 Markdown]\n C --> D[更新 meta.json]\n D --> E[提交文档]\n```\n\n### 支持的元数据\n\n| 元数据字段 | 说明 |\n|----------|------|\n| Name | 块名称 |\n| Description | 块描述 |\n| Category | 所属类别 |\n| Input | 输入规格 |\n| Output | 输出规格 |\n| Config | 配置参数 |\n\n### 手动内容保留\n\n文档生成器支持保留手动添加的内容：\n\n```markdown\n{/_ MANUAL-CONTENT-START:usage _/}\n\n## Examples\n\n### Basic Usage\n\n```json\n{ \"parameter\": \"value\" }\n```\n\n{/_ MANUAL-CONTENT-END _/}\n```\n\n资料来源：[scripts/README.md:1-60]()\n\n## SDK 支持\n\n### TypeScript SDK\n\n```typescript\nimport { SimStudioClient } from '@simstudio/ts-sdk'\n\nconst client = new SimStudioClient({ apiKey: 'your-api-key' })\n\n// 同步执行\nconst result = await client.workflows.execute('workflow-id', {\n input: { data: 'example' }\n})\n\n// 异步执行\nconst asyncResult = await client.workflows.executeAsync('workflow-id', {\n input: { data: 'example' }\n})\n```\n\n### Python SDK\n\n```python\nfrom simstudio import Client\n\nclient = Client(api_key=\"your-api-key\")\n\n# 同步执行\nresult = client.workflows.execute(\"workflow-id\", {\"data\": \"example\"})\n\n# 异步执行\nasync_result = client.workflows.execute_async(\"workflow-id\", {\"data\": \"example\"})\n```\n\n资料来源：[packages/ts-sdk/README.md:1-100]()\n[packages/python-sdk/README.md:1-100]()\n\n## 相关资源\n\n| 资源类型 | 说明 |\n|---------|------|\n| `/app/workspace/[workspaceId]/w/[workflowId]` | 工作流编辑器主路由 |\n| `/components/panel/components/editor` | 编辑器面板组件 |\n| `/components/workflow-block` | 工作流块组件 |\n| `/components/panel/components/sub-block` | 子块配置组件 |\n\n---\n\n\n\n## 实时协作与UI组件\n\n### 相关页面\n\n相关主题：[系统架构](#page-system-architecture), [工作流编辑器](#page-workflow-editor)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [apps/sim/lib/workflows/triggers/triggers.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/triggers/triggers.ts)\n- [apps/sim/lib/workflows/triggers/trigger-utils.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/triggers/trigger-utils.ts)\n- [apps/sim/lib/webhooks/providers/gong.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/providers/gong.ts)\n- [apps/sim/lib/webhooks/providers/typeform.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/providers/typeform.ts)\n- [apps/sim/lib/api/contracts/types.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/api/contracts/types.ts)\n- [apps/sim/app/workspace/providers/socket-provider.tsx](https://github.com/simstudioai/sim/blob/main/apps/sim/app/workspace/providers/socket-provider.tsx)\n- [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)\n
\n\n# 实时协作与UI组件\n\n## 概述\n\n实时协作与UI组件是 Sim 平台中支持多用户同时编辑和工作流管理的核心功能模块。该系统通过 WebSocket 连接实现实时状态同步，支持工作流设计器的协作编辑、触发器实时监控、以及与外部系统（如 Gong、Typeform）的Webhook集成。\n\n**核心职责：**\n\n- 建立和管理 WebSocket 连接，实现客户端与服务器的实时双向通信\n- 提供协作用户的光标追踪和状态显示功能\n- 处理工作流触发器的实时事件流\n- 集成第三方Webhook提供商的实时数据接收\n\n**技术范围：**\n\n- Socket Provider 客户端组件\n- 光标和协作状态组件\n- 工作流触发器系统\n- Webhook提供商的实时数据处理\n- API契约类型定义\n\n---\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n subgraph 客户端层[\"客户端层\"]\n SP[Socket Provider]\n CURSORS[光标组件]\n UI[工作流编辑器 UI]\n end\n \n subgraph 实时服务[\"实时服务 - apps/realtime\"]\n HANDLERS[事件处理器]\n MIDDLEWARE[中间件]\n ROOMS[房间管理]\n end\n \n subgraph 业务逻辑层[\"业务逻辑层\"]\n TRIGGERS[触发器系统]\n WEBHOOKS[Webhook提供商]\n end\n \n subgraph 外部系统[\"外部集成\"]\n GONG[Gong平台]\n TYPEFORM[Typeform]\n SCHEDULE[调度器]\n end\n \n SP <-->|WebSocket| HANDLERS\n HANDLERS <--> ROOMS\n HANDLERS <--> MIDDLEWARE\n TRIGGERS -->|触发事件| HANDLERS\n WEBHOOKS -->|Webhook事件| TRIGGERS\n UI <--> SP\n CURSORS <--> SP\n```\n\n### Socket Provider 架构\n\nSocket Provider 是 React 上下文提供者，负责管理 WebSocket 连接的生命周期。\n\n```mermaid\ngraph LR\n A[React App] -->|Provider| B[SocketContext]\n B --> C[WebSocket Connection]\n C -->|onOpen| D[连接建立]\n C -->|onMessage| E[消息处理]\n C -->|onClose| F[重连逻辑]\n C -->|onError| G[错误处理]\n```\n\n---\n\n## Socket Provider 组件\n\n### 组件位置\n\n`apps/sim/app/workspace/providers/socket-provider.tsx`\n\n### 核心功能\n\nSocket Provider 组件是 Sim 应用中 WebSocket 连接的中心化管理器，提供以下核心功能：\n\n| 功能 | 说明 |\n|------|------|\n| 连接管理 | 建立与实时服务器的 WebSocket 连接 |\n| 自动重连 | 连接断开时自动尝试重新连接 |\n| 消息订阅 | 支持订阅特定事件类型的消息 |\n| 状态同步 | 维护连接状态并向子组件广播 |\n| 上下文提供 | 通过 React Context 向子树提供 Socket 实例 |\n\n### 连接生命周期\n\n```mermaid\nstateDiagram-v2\n [*] --> Disconnected: 初始状态\n Disconnected --> Connecting: 调用 connect()\n Connecting --> Connected: WebSocket open\n Connecting --> Disconnected: 连接失败\n Connected --> Disconnected: 连接关闭\n Disconnected --> Connecting: 自动重连\n Connected --> [*]: 组件卸载\n```\n\n**连接状态说明：**\n\n| 状态 | 描述 |\n|------|------|\n| `disconnected` | 初始状态或连接已关闭 |\n| `connecting` | 正在建立 WebSocket 连接 |\n| `connected` | 连接已建立，可收发消息 |\n| `reconnecting` | 正在尝试重新连接 |\n\n### 事件订阅机制\n\nSocket Provider 支持基于事件类型的消息订阅，客户端可以注册特定事件的处理器：\n\n```typescript\n// 订阅示例\nsocket.subscribe('workflow.update', handler)\nsocket.subscribe('cursor.move', handler)\n\n// 取消订阅\nsocket.unsubscribe('workflow.update', handler)\n```\n\n---\n\n## 协作用户光标组件\n\n### 组件位置\n\n`apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/cursors/cursors.tsx`\n\n### 功能说明\n\n光标组件负责显示和追踪协作用户在编辑器中的实时位置和操作状态。\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `userId` | `string` | 协作用户唯一标识 |\n| `userName` | `string` | 协作用户显示名称 |\n| `color` | `string` | 用户分配的颜色（用于区分不同用户） |\n| `position` | `{ x: number, y: number }` | 当前光标位置 |\n| `isActive` | `boolean` | 用户当前是否处于活跃状态 |\n| `lastUpdate` | `number` | 最后更新时间戳 |\n\n### 光标渲染逻辑\n\n```mermaid\ngraph TD\n A[接收 CursorMove 事件] --> B{检查用户状态}\n B -->|用户活跃| C[更新本地状态]\n B -->|用户空闲超时| D[降低透明度/隐藏]\n C --> E[重新渲染光标组件]\n D --> E\n E --> F[显示用户名称标签]\n```\n\n### 协作用户管理\n\n光标组件支持显示当前工作区的所有协作用户：\n\n| 用户状态 | 视觉表现 |\n|----------|----------|\n| 活跃编辑 | 正常显示，带有用户名称标签 |\n| 空闲 | 降低透明度至 50% |\n| 长时间无活动 | 隐藏光标（节省渲染资源） |\n| 断开连接 | 立即移除光标显示 |\n\n---\n\n## 工作流触发器系统\n\n### 触发器类型\n\nSim 平台支持多种触发器类型，用于启动工作流执行：\n\n| 触发器类型 | 标识符 | 说明 | 优先级 |\n|-----------|--------|------|--------|\n| 手动触发 | `TRIGGER_TYPES.START` | 用户手动启动工作流 | 0（最高） |\n| API触发 | `TRIGGER_TYPES.API` | 通过API调用触发 | 4 |\n| 聊天触发 | `TRIGGER_TYPES.CHAT` | 通过聊天消息触发 | 7 |\n| 调度触发 | `schedule` | 定时/周期执行 | 2 |\n| Webhook触发 | `external_trigger` | 外部Webhook事件触发 | 3 |\n\n资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:1-50]()\n\n### 触发器引用别名映射\n\n系统定义了触发器引用别名，方便在内部引用不同类型的触发器：\n\n```typescript\nexport const TRIGGER_REFERENCE_ALIAS_MAP = {\n start: TRIGGER_TYPES.START,\n api: TRIGGER_TYPES.API,\n chat: TRIGGER_TYPES.CHAT,\n manual: TRIGGER_TYPES.START,\n} as const\n```\n\n资料来源：[apps/sim/lib/workflows/triggers/triggers.ts:50-60]()\n\n### 触发器优先级排序\n\n触发器根据类型和配置进行优先级排序：\n\n```mermaid\ngraph TD\n A[触发器候选列表] --> B[按路径分组]\n B --> C{StartBlockPath 判断}\n C -->|UNIFIED| D[优先级 0]\n C -->|LEGACY_STARTER| E[优先级 1]\n C -->|EXTERNAL_TRIGGER| F{类型判断}\n C -->|SPLIT_API| G[优先级 4]\n C -->|SPLIT_INPUT| H[优先级 5]\n C -->|SPLIT_MANUAL| I[优先级 6]\n C -->|SPLIT_CHAT| J[优先级 7]\n F -->|schedule| K[优先级 2]\n F -->|其他| L[优先级 3]\n D --> M[排序完成]\n E --> M\n K --> M\n L --> M\n G --> M\n H --> M\n I --> M\n J --> M\n```\n\n资料来源：[apps/sim/lib/workflows/triggers/trigger-utils.ts:1-35]()\n\n### 触发器工具类\n\n`TriggerUtils` 类提供静态方法用于触发器识别和验证：\n\n```typescript\nexport class TriggerUtils {\n // 检查块是否为触发器\n static isTriggerBlock(block: { type: string; triggerMode?: boolean }): boolean\n \n // 检查块是否为特定触发器类型\n static isTriggerType(block: { type: string }, triggerType: TriggerType): boolean\n}\n```\n\n### Mock Payload 需求判断\n\n对于需要测试数据的外部触发器，系统提供智能判断：\n\n```typescript\nexport function triggerNeedsMockPayload(\n trigger: StartBlockCandidate\n): boolean {\n // 仅 Webhook 和外部集成需要 Mock Payload\n // 调度器正常执行不需要模拟数据\n return trigger.path === StartBlockPath.EXTERNAL_TRIGGER && trigger.block...\n}\n```\n\n资料来源：[apps/sim/lib/workflows/triggers/trigger-utils.ts:60-75]()\n\n---\n\n## Webhook 实时数据处理\n\n### Webhook 提供商架构\n\nSim 平台集成了多个第三方 Webhook 提供商，实现实时数据接收：\n\n```mermaid\ngraph LR\n subgraph 外部系统\n GONG[Gong 自动化规则]\n TYPEFORM[Typeform 表单响应]\n end\n \n subgraph 标准化处理\n P_GONG[提供商处理器]\n P_TYPEFORM[提供商处理器]\n end\n \n GONG -->|POST /webhooks/gong| P_GONG\n TYPEFORM -->|POST /webhooks/typeform| P_TYPEFORM\n \n P_GONG --> FORMAT_G[格式化为统一输入]\n P_TYPEFORM --> FORMAT_T[格式化为统一输入]\n \n FORMAT_G --> WORKFLOW[触发工作流]\n FORMAT_T --> WORKFLOW\n```\n\n### Gong Webhook 提供商\n\n**文件位置：** `apps/sim/lib/webhooks/providers/gong.ts`\n\nGong 平台集成支持接收自动化规则事件：\n\n| 配置项 | 说明 |\n|--------|------|\n| `secret` | HMAC 签名验证密钥 |\n| `includeCallData` | 是否包含通话数据 |\n| `includeParties` | 是否包含通话参与者 |\n| `includeContext` | 是否包含通话上下文 |\n| `includeTrackers` | 是否包含追踪器数据 |\n| `includeTopics` | 是否包含主题信息 |\n| `includeHighlights` | 是否包含亮点标记 |\n\n**事件数据结构：**\n\n```typescript\n{\n eventType: 'gong.automation_rule',\n callId: string,\n metaData: Record,\n parties: unknown[],\n context: unknown[],\n trackers: unknown[],\n topics: unknown[],\n highlights: unknown[]\n}\n```\n\n### Typeform Webhook 提供商\n\n**文件位置：** `apps/sim/lib/webhooks/providers/typeform.ts`\n\nTypeform 集成支持接收表单响应事件：\n\n| 配置项 | 说明 |\n|--------|------|\n| `formId` | Typeform 表单 ID |\n| `apiKey` | Typeform API 密钥 |\n| `webhookTag` | Webhook 标签 |\n| `secret` | 签名验证密钥 |\n| `includeDefinition` | 是否包含表单定义 |\n\n**事件数据结构：**\n\n```typescript\n{\n event_id: string,\n event_type: 'form_response',\n form_id: string,\n token: string,\n submitted_at: string,\n landed_at: string,\n calculated: Record,\n variables: unknown[],\n hidden: Record,\n answers: unknown[],\n definition?: Record,\n ending: Record,\n raw: Record\n}\n```\n\n**认证验证：**\n\nTypeform 提供商使用 HMAC 签名验证：\n\n```typescript\nverifyAuth: createHmacVerifier({\n configKey: 'secret',\n headerName: 'Typeform-Signature',\n validateFn: validateTypeformSignature,\n providerLabel: 'Typeform',\n})\n```\n\n---\n\n## API 契约类型系统\n\n### 契约类型定义\n\n**文件位置：** `apps/sim/lib/api/contracts/types.ts`\n\nAPI 契约系统提供强类型的路由定义和参数提取：\n\n| 类型 | 说明 |\n|------|------|\n| `ApiRouteContract` | API 路由契约的核心类型定义 |\n| `ContractParams` | 提取契约中定义的路径参数类型 |\n| `ContractQuery` | 提取契约中定义的查询参数类型 |\n| `ContractBody` | 提取契约中定义的请求体类型 |\n| `ContractHeaders` | 提取契约中定义的头部参数类型 |\n| `ContractParamsInput` | 契约参数的输入形式 |\n\n### 类型提取示例\n\n```typescript\n// 从契约中提取各种参数类型\ntype MyParams = ContractParams\ntype MyQuery = ContractQuery\ntype MyBody = ContractBody\ntype MyHeaders = ContractHeaders\n```\n\n### 契约辅助函数\n\n```typescript\nfunction defineRoute(\n contract: ApiRouteContract\n): ApiRouteContract\n```\n\n---\n\n## 实时事件流\n\n### 工作流更新事件\n\n工作流状态变更通过 WebSocket 实时推送到所有连接的客户端：\n\n```mermaid\nsequenceDiagram\n participant U as 用户A (编辑器)\n participant S as Socket Provider\n participant R as Realtime Server\n participant W as 工作流引擎\n \n U->>W: 修改工作流\n W->>R: 触发 workflow.update 事件\n R->>S: 广播事件\n S->>U: 接收并处理事件\n Note over U: 更新本地 UI 状态\n```\n\n### 协作用户状态同步\n\n多个用户编辑同一工作流时，光标位置和操作状态实时同步：\n\n```mermaid\nsequenceDiagram\n participant U1 as 用户1 (光标移动)\n participant S as Socket Provider\n participant R as Realtime Server\n participant U2 as 用户2 (观察者)\n \n U1->>S: 发送 cursor.move 事件\n S->>R: 转发事件\n R->>S: 广播到其他客户端\n S->>U2: 接收并渲染光标\n Note over U2: 显示用户1的光标\n```\n\n---\n\n## 配置与扩展\n\n### 添加新的 Webhook 提供商\n\n要添加新的 Webhook 提供商，需要实现以下接口：\n\n| 方法 | 说明 |\n|------|------|\n| `formatInput` | 将原始请求格式化为统一输入格式 |\n| `verifyAuth` | 验证请求的认证信息 |\n| `createSubscription` | （可选）创建订阅配置 |\n\n**基本实现模板：**\n\n```typescript\nexport const myProvider: WebhookProvider = {\n formatInput: (body, webhook) => {\n // 格式化输入数据\n return {\n input: {\n // 统一输入格式\n }\n }\n },\n \n verifyAuth: createHmacVerifier({\n configKey: 'secret',\n headerName: 'Provider-Signature',\n validateFn: validateSignature,\n providerLabel: 'ProviderName',\n }),\n \n async createSubscription(ctx) {\n // 创建订阅逻辑\n return { subscriptionId: '...' }\n }\n}\n```\n\n### 触发器类型扩展\n\n要添加新的触发器类型，需要：\n\n1. 在 `TRIGGER_TYPES` 枚举中添加新类型\n2. 在 `StartBlockPath` 中添加对应路径\n3. 更新 `getPriority` 函数中的优先级逻辑\n4. 在触发器选择逻辑中添加相应的判断\n\n---\n\n## 错误处理与重试\n\n### WebSocket 连接错误处理\n\n| 错误类型 | 处理策略 |\n|----------|----------|\n| 连接超时 | 指数退避重连（最大5次） |\n| 网络断开 | 自动检测并重连 |\n| 服务器错误 | 通知用户，显示错误信息 |\n| 认证失败 | 重新认证流程 |\n\n### Webhook 验证失败\n\n验证失败的请求会被拒绝并记录日志：\n\n```typescript\nlogger.warn(`[${ctx.requestId}] Missing formId for Typeform...`)\nreturn undefined // 返回 undefined 表示验证失败\n```\n\n---\n\n## 性能优化\n\n### 光标渲染优化\n\n| 优化策略 | 说明 |\n|----------|------|\n| 空闲检测 | 用户长时间无活动时降低更新频率 |\n| 批量更新 | 合并短时间内的多次位置更新 |\n| 可视区域 | 只渲染当前可视区域内的光标 |\n| 脏检查 | 仅在位置变化时触发重新渲染 |\n\n### WebSocket 消息压缩\n\n| 策略 | 说明 |\n|------|------|\n| 增量更新 | 仅传输变化的字段 |\n| 消息合并 | 批量发送低优先级事件 |\n| 心跳优化 | 动态调整心跳间隔 |\n\n---\n\n## 相关文档\n\n| 文档 | 说明 |\n|------|------|\n| [Socket Provider 组件](/apps/sim/app/workspace/providers/socket-provider.tsx) | WebSocket 连接管理组件 |\n| [光标组件](/apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/cursors/cursors.tsx) | 协作用户光标显示 |\n| [触发器系统](/apps/sim/lib/workflows/triggers/triggers.ts) | 工作流触发器核心逻辑 |\n| [Gong 集成](/apps/sim/lib/webhooks/providers/gong.ts) | Gong Webhook 提供商 |\n| [Typeform 集成](/apps/sim/lib/webhooks/providers/typeform.ts) | Typeform Webhook 提供商 |\n\n---\n\n\n\n## 连接器框架\n\n### 相关页面\n\n相关主题：[块系统与注册表](#page-block-registry), [扩展与定制](#page-extensibility)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [apps/sim/lib/webhooks/providers/gong.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/providers/gong.ts)\n- [apps/sim/lib/webhooks/providers/webflow.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/providers/webflow.ts)\n- [apps/sim/lib/webhooks/providers/typeform.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/providers/typeform.ts)\n- [apps/sim/lib/webhooks/providers/vercel.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/providers/vercel.ts)\n- [apps/sim/blocks/blocks/](https://github.com/simstudioai/sim/blob/main/apps/sim/blocks/blocks/)\n- [apps/sim/blocks/index.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/blocks/index.ts)\n
\n\n# 连接器框架\n\n## 概述\n\nSim 平台中的连接器框架（Connector Framework）是用于实现与外部第三方服务集成的基础架构。该框架提供了一套标准化的模式，使得平台能够统一处理来自不同服务提供商（Provider）的 webhook 事件和数据转换。\n\n连接器框架的核心职责包括：\n\n- **事件接收**：接收来自外部服务的事件通知\n- **数据标准化**：将不同提供商的数据格式转换为统一的内部格式\n- **认证验证**：验证 webhook 请求的真实性\n- **事件过滤**：根据配置条件选择性处理事件\n- **数据映射**：将外部数据结构映射为工作流可用的输入格式\n\n## 架构设计\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[外部服务] -->|Webhook 事件| B[连接器提供者]\n B --> C{事件过滤}\n C -->|跳过| D[丢弃]\n C -->|通过| E[数据标准化]\n E --> F[工作流执行引擎]\n F --> G[Block 输出]\n \n H[认证模块] --> B\n```\n\n### Provider 架构模式\n\n每个连接器提供者（Provider）遵循统一的接口契约，确保系统的一致性和可扩展性：\n\n```mermaid\ngraph LR\n A[Webhook 请求] --> B[formatInput]\n B --> C[verifyAuth]\n C --> D{验证结果}\n D -->|失败| E[返回错误]\n D -->|成功| F[shouldSkipEvent]\n F --> G{跳过检查}\n G -->|是| H[跳过处理]\n G -->|否| I[触发工作流]\n```\n\n## Provider 接口规范\n\n### 核心接口定义\n\n每个连接器提供者必须实现以下核心方法：\n\n| 方法名 | 类型 | 描述 |\n|--------|------|------|\n| `formatInput` | 同步函数 | 将原始 webhook 负载转换为标准化的输入格式 |\n| `verifyAuth` | 认证函数 | 验证请求的认证签名 |\n| `createSubscription` | 异步函数 | 在外部服务创建 webhook 订阅 |\n| `shouldSkipEvent` | 同步函数 | 根据配置判断是否应跳过该事件 |\n\n### 输入格式化\n\n`formatInput` 函数负责将来自不同提供商的事件数据转换为统一的工作流输入格式：\n\n```typescript\ninterface FormatInputResult {\n input: {\n event_id: string\n event_type: string\n // 特定于提供商的其他字段...\n raw: Record // 原始数据保留\n }\n}\n```\n\n资料来源：[apps/sim/lib/webhooks/providers/typeform.ts:20-40]()\n\n### 认证验证模式\n\n认证验证采用工厂模式创建认证验证器，支持多种验证策略：\n\n```typescript\nverifyAuth: createHmacVerifier({\n configKey: 'secret',\n headerName: 'Typeform-Signature',\n validateFn: validateTypeformSignature,\n providerLabel: 'Typeform',\n})\n```\n\n支持的认证类型：\n\n| 认证类型 | 描述 | 适用场景 |\n|---------|------|---------|\n| HMAC 验证 | 基于共享密钥的消息认证码 | Typeform, GitHub |\n| Bearer Token | Bearer 令牌认证 | 通用 API |\n| 自定义验证 | 特定提供商的验证逻辑 | 各 Provider |\n\n资料来源：[apps/sim/lib/webhooks/providers/typeform.ts:47-53]()\n\n## 内置 Provider 实现\n\n### Webflow 连接器\n\nWebflow 连接器处理 CMS 和电商平台的事件，支持集合项的创建、更新和归档：\n\n```typescript\ninterface WebflowFieldMapping {\n lastUpdated: string | number\n createdOn: string | number\n isArchived: boolean\n isDraft: boolean\n fieldData: Record\n}\n```\n\n**事件过滤逻辑**：\n\n```typescript\nshouldSkipEvent({ webhook, body, requestId, providerConfig }: EventFilterContext) {\n const configuredCollectionId = providerConfig.collectionId as string | undefined\n // 当配置了特定集合 ID 时，只处理该集合的事件\n if (payloadCollectionId !== configuredCollectionId) {\n return true // 跳过不匹配的事件\n }\n return false\n}\n```\n\n资料来源：[apps/sim/lib/webhooks/providers/webflow.ts:1-50]()\n\n### Gong 连接器\n\nGong 连接器处理销售对话智能平台的事件，提取会议元数据和内容分析：\n\n```typescript\ninterface GongAutomationData {\n metaData: Record\n parties: unknown[]\n context: unknown[]\n trackers: unknown[]\n topics: unknown[]\n highlights: unknown[]\n eventType: string\n callId: string\n}\n```\n\n**数据映射策略**：\n\n```typescript\n// 安全的类型转换，处理可能的 undefined 值\nparties: (callData?.parties as unknown[]) || [],\ncontext: (callData?.context as unknown[]) || [],\ntrackers: (content?.trackers as unknown[]) || [],\n```\n\n资料来源：[apps/sim/lib/webhooks/providers/gong.ts:1-30]()\n\n### Typeform 连接器\n\nTypeform 连接器处理表单响应事件，支持可选的表单定义包含：\n\n```typescript\ninterface TypeformInput {\n event_id: string\n event_type: string\n form_id: string\n token: string\n submitted_at: string\n landed_at: string\n calculated: Record\n variables: unknown[]\n hidden: Record\n answers: unknown[]\n definition?: Record // 可选配置\n ending: Record\n raw: Record\n}\n```\n\n资料来源：[apps/sim/lib/webhooks/providers/typeform.ts:20-38]()\n\n### Vercel 连接器\n\nVercel 连接器处理部署相关事件，提取部署、项目和团队信息：\n\n```typescript\ninterface VercelDeployment {\n id: string\n url: string\n name: string\n meta: Record\n}\n\ninterface VercelProject {\n id: string\n name: string\n}\n\ninterface VercelTeam {\n id: string\n}\n```\n\n**对象安全转换模式**：\n\n```typescript\ndeployment && typeof deployment === 'object'\n ? {\n id: String((deployment as Record).id),\n url: ((deployment as Record).url as string) ?? '',\n }\n : null\n```\n\n资料来源：[apps/sim/lib/webhooks/providers/vercel.ts:1-60]()\n\n## 事件过滤机制\n\n连接器框架支持精细化的事件过滤控制，通过 `EventFilterContext` 上下文对象传递配置：\n\n```typescript\ninterface EventFilterContext {\n webhook: WebhookRecord\n body: Record\n requestId: string\n providerConfig: Record\n}\n```\n\n**过滤决策流程**：\n\n```mermaid\ngraph TD\n A[接收事件] --> B[提取 providerConfig]\n B --> C{检查配置条件}\n C -->|无过滤条件| D[处理事件]\n C -->|有过滤条件| E{条件匹配}\n E -->|匹配成功| D\n E -->|匹配失败| F[跳过事件]\n D --> G[触发工作流]\n F --> H[记录跳过日志]\n```\n\n## 与 Block 系统的集成\n\n连接器框架与 Sim 的 Block 系统紧密集成，实现工作流自动化：\n\n```mermaid\ngraph LR\n A[连接器 Provider] --> B[Block 输入转换]\n B --> C[工作流 Block 图]\n C --> D[执行引擎]\n D --> E[Block 输出]\n```\n\nBlock 系统通过以下方式使用连接器：\n\n1. **输入规范**：定义每个 Block 的输入 schema\n2. **类型验证**：使用 Zod 进行运行时验证\n3. **输出映射**：将 Block 执行结果映射为下游 Block 的输入\n\n资料来源：[apps/sim/blocks/index.ts](apps/sim/blocks/index.ts)\n\n## 订阅管理\n\n连接器框架支持动态订阅管理，允许在运行时创建和配置 webhook 订阅：\n\n```typescript\nasync createSubscription(ctx: SubscriptionContext): Promise {\n const config = getProviderConfig(ctx.webhook)\n const formId = config.formId as string | undefined\n const apiKey = config.apiKey as string | undefined\n // ... 配置验证和订阅创建逻辑\n}\n```\n\n## 错误处理策略\n\n| 错误类型 | 处理方式 | 返回状态 |\n|---------|---------|---------|\n| 认证失败 | 返回 401 | 拒绝请求 |\n| 配置缺失 | 记录警告日志 | 返回 undefined |\n| 格式转换错误 | 使用默认值 | 继续处理 |\n| 事件过滤 | 静默跳过 | 不触发工作流 |\n\n## 最佳实践\n\n### Provider 开发指南\n\n1. **类型安全**：始终使用类型断言和空值合并\n2. **默认字段**：为可选字段提供安全的默认值\n3. **日志记录**：在跳过事件时记录原因\n4. **错误恢复**：不要让 Provider 错误导致整个流程失败\n\n### 示例代码模式\n\n```typescript\n// 安全地从可能为 undefined 的嵌套对象中提取值\nconst value = \n (itemFields as Record)?.fieldName ||\n (itemFields as Record)?.['alternative-name'] ||\n ''\n```\n\n## 总结\n\nSim 的连接器框架提供了一套灵活且可扩展的集成机制，通过标准化的 Provider 接口实现了与多种外部服务的统一对接。该框架的核心优势包括：\n\n- **一致性**：统一的接口契约简化了新增 Provider 的工作\n- **安全性**：内置的认证验证机制确保了事件来源的可信性\n- **灵活性**：事件过滤机制允许精细化的控制\n- **可维护性**：类型安全的实现和清晰的代码结构便于长期维护\n\n---\n\n\n\n## 部署与基础设施\n\n### 相关页面\n\n相关主题：[项目概述](#page-project-overview), [系统架构](#page-system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [docker-compose.prod.yml](https://github.com/simstudioai/sim/blob/main/docker-compose.prod.yml)\n- [docker-compose.ollama.yml](https://github.com/simstudioai/sim/blob/main/docker-compose.ollama.yml)\n- [apps/sim/.env.example](https://github.com/simstudioai/sim/blob/main/apps/sim/.env.example)\n- [.devcontainer](https://github.com/simstudioai/sim/blob/main/.devcontainer)\n- [apps/docs/content/docs/en/self-hosting](https://github.com/simstudioai/sim/blob/main/apps/docs/content/docs/en/self-hosting)\n
\n\n# 部署与基础设施\n\n## 概述\n\nSim 是一个开源的工作流自动化平台，支持多种部署方式以满足不同规模和需求的场景。项目提供了从简单的本地开发部署到生产级 Kubernetes 集群部署的完整基础设施支持。\n\n部署架构的核心组件包括：\n\n- **应用服务**：基于 Next.js 构建的前后端一体化应用\n- **数据库**：PostgreSQL 12+ 配合 pgvector 扩展用于向量存储\n- **缓存层**：Redis 用于会话管理和实时功能\n- **容器化**：Docker 和 Docker Compose 简化部署流程\n- **编排**：Kubernetes Helm chart 支持生产级部署\n\n资料来源：[README.md](https://github.com/simstudioai/sim/blob/main/README.md)\n\n---\n\n## 部署方式\n\nSim 支持四种主要的部署方式，从简单到复杂依次为：NPM 包快速启动、Docker Compose 生产部署、手动开发和 Kubernetes 生产部署。\n\n### NPM 包快速部署\n\n最简单的方式是使用官方提供的 NPM 包，通过 Docker 自动拉取并运行 Sim：\n\n```bash\nnpx simstudio\n```\n\n默认访问地址为 http://localhost:3000\n\n资料来源：[README.md:8](https://github.com/simstudioai/sim/blob/main/README.md)\n\n**可用参数选项：**\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `-p, --port ` | 指定运行端口 | `3000` |\n| `--no-pull` | 跳过拉取最新 Docker 镜像 | `false` |\n\n使用示例：\n\n```bash\n# 指定端口\nnpx simstudio --port 8080\n\n# 跳过镜像拉取\nnpx simstudio --no-pull\n```\n\n> **前提条件**：必须安装并运行 Docker\n\n---\n\n### Docker Compose 生产部署\n\n对于生产环境，推荐使用 Docker Compose 进行部署，该方式提供完整的服务栈和持久化存储。\n\n```bash\ngit clone https://github.com/simstudioai/sim.git && cd sim\ndocker compose -f docker-compose.prod.yml up -d\n```\n\n资料来源：[README.md:19-22](https://github.com/simstudioai/sim/blob/main/README.md)\n\n**Docker Compose 生产架构图：**\n\n```mermaid\ngraph TD\n subgraph \"Docker Compose Stack\"\n A[用户访问] --> B[NGINX Reverse Proxy]\n B --> C[Sim App Container]\n C --> D[(PostgreSQL + pgvector)]\n C --> E[(Redis Cache)]\n C --> F[File Storage]\n end\n```\n\n**生产部署包含的服务：**\n\n- Sim 应用容器\n- PostgreSQL 数据库（带 pgvector 扩展）\n- Redis 缓存服务\n- 文件存储卷\n\n---\n\n### 本地模型支持\n\nSim 支持通过 Ollama 和 vLLM 连接本地大语言模型，适用于对数据隐私有要求或希望降低 API 成本的场景。\n\n使用 Ollama 部署：\n\n```bash\ndocker compose -f docker-compose.ollama.yml up -d\n```\n\n资料来源：[README.md:29](https://github.com/simstudioai/sim/blob/main/README.md)\n\n**Ollama 部署架构：**\n\n```mermaid\ngraph LR\n A[Sim App] -->|API 调用| B[Ollama Service]\n B --> C[本地 LLM Model]\n C -->|推理结果| B\n B -->|返回结果| A\n```\n\n支持的本地模型功能：\n\n- Ollama 本地模型推理\n- vLLM 高性能推理服务\n- 自定义模型接入\n\n详细的本地模型配置请参考 [Docker 自托管文档](https://docs.sim.ai/self-hosting/docker)。\n\n---\n\n### Kubernetes Helm 部署\n\n对于大规模生产环境，Sim 提供了完整的 Helm Chart 用于 Kubernetes 集群部署。\n\n**基础安装：**\n\n```bash\nhelm install sim ./helm/sim -n sim --create-namespace\n```\n\n**使用自定义值文件：**\n\n```bash\nhelm install sim ./helm/sim -n sim -f values.prod.yaml\n```\n\n资料来源：[helm/sim/README.md](https://github.com/simstudioai/sim/blob/main/helm/sim/README.md)\n\n---\n\n## 环境变量配置\n\nSim 使用环境变量进行配置管理。示例配置文件位于 `apps/sim/.env.example`。\n\n资料来源：[apps/sim/.env.example](https://github.com/simstudioai/sim/blob/main/apps/sim/.env.example)\n\n### 核心配置参数\n\n| 参数名 | 说明 | 必填 | 默认值 |\n|--------|------|------|--------|\n| `DATABASE_URL` | PostgreSQL 连接字符串 | 是 | - |\n| `REDIS_URL` | Redis 连接字符串 | 是 | - |\n| `NEXT_PUBLIC_APP_URL` | 应用公开访问 URL | 是 | - |\n| `OPENAI_API_KEY` | OpenAI API 密钥 | 否 | - |\n| `ANTHROPIC_API_KEY` | Anthropic API 密钥 | 否 | - |\n\n### Helm 全局参数\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `global.imageRegistry` | Docker 镜像仓库地址 | `docker.io` |\n| `global.imagePullSecrets` | 镜像拉取密钥名称 | `[]` |\n| `global.storageClass` | 存储类名称 | `\"\"` |\n| `global.commonLabels` | 通用标签 | `{}` |\n\n资料来源：[helm/sim/README.md](https://github.com/simstudioai/sim/blob/main/helm/sim/README.md)\n\n### 应用参数配置\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `app.enabled` | 启用主应用 | `true` |\n| `app.replicaCount` | 应用副本数 | `1` |\n| `app.image.repository` | 镜像仓库 | `simstudioai/sim` |\n| `app.image.tag` | 镜像标签 | `latest` |\n| `app.image.pullPolicy` | 镜像拉取策略 | `Always` |\n| `app.service.type` | 服务类型 | `ClusterIP` |\n| `app.service.port` | 服务端口 | `3000` |\n| `app.service.targetPort` | 容器目标端口 | `3000` |\n\n---\n\n## 系统要求\n\n### 基础环境要求\n\n| 组件 | 最低版本 | 推荐版本 |\n|------|----------|----------|\n| Docker | 最新稳定版 | 最新稳定版 |\n| Bun | - | 最新版本 |\n| Node.js | v20+ | v20 LTS |\n| PostgreSQL | 12+ | 15+ |\n| pgvector | 0.5+ | 最新版本 |\n\n资料来源：[README.md:32-33](https://github.com/simstudioai/sim/blob/main/README.md)\n\n### 手动部署前置步骤\n\n1. **克隆代码库：**\n\n```bash\ngit clone https://github.com/simstudioai/sim.git\ncd sim\n```\n\n2. **安装依赖：**\n\n```bash\nbun install\nbun run prepare # 设置 pre-commit hooks\n```\n\n3. **配置 PostgreSQL 数据库：**\n\n```bash\ndocker run --name simstudio-db \\\n -e POSTGRES_PASSWORD=your_password \\\n -e POSTGRES_DB=simstudio \\\n -p 5432:5432 \\\n -d \\\n pgvector/pgvector:pg15\n```\n\n4. **配置环境变量：**\n\n复制并编辑环境变量文件：\n\n```bash\ncp apps/sim/.env.example apps/sim/.env\n# 编辑 .env 文件填入实际配置\n```\n\n---\n\n## 开发环境配置\n\n项目支持使用 VS Code Dev Container 进行标准化开发环境配置。\n\n资料来源：[.devcontainer](https://github.com/simstudioai/sim/blob/main/.devcontainer)\n\n### Dev Container 优势\n\n- 开箱即用的标准化开发环境\n- 预配置所有依赖项\n- 与主机隔离，避免环境污染\n- 团队成员环境一致性保证\n\n### 启动开发容器\n\n1. 确保已安装 VS Code 和 Docker\n2. 在 VS Code 中打开项目文件夹\n3. 安装 \"Dev Containers\" 扩展\n4. 点击右下角提示 \"Reopen in Container\"\n5. 等待容器构建完成\n\n---\n\n## 负载测试配置\n\n项目包含用于验证部署性能的负载测试脚本，位于 `scripts/load/` 目录。\n\n资料来源：[apps/sim/package.json](https://github.com/simstudioai/sim/blob/main/apps/sim/package.json)\n\n### 可用的负载测试命令\n\n| 命令 | 说明 |\n|------|------|\n| `load:workflow:waves` | 波次式负载测试 |\n| `load:workflow:isolation` | 隔离工作空间负载测试 |\n\n### 波次式负载测试参数\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `BASE_URL` | 测试目标地址 | `http://localhost:3000` |\n| `WAVE_ONE_DURATION` | 第一波次持续时间（秒） | 20 |\n| `WAVE_ONE_RATE` | 第一波次请求速率 | 10 |\n| `WAVE_TWO_DURATION` | 第二波次持续时间（秒） | 20 |\n| `WAVE_TWO_RATE` | 第二波次请求速率 | 10 |\n| `WAVE_THREE_DURATION` | 第三波次持续时间（秒） | 20 |\n| `WAVE_THREE_RATE` | 第三波次请求速率 | 10 |\n\n运行示例：\n\n```bash\nBASE_URL=http://production-server:3000 bunx artillery run scripts/load/workflow-waves.yml\n```\n\n---\n\n## 安全配置\n\n### 主机名验证\n\n项目实现了 SSRF（服务器端请求伪造）防护机制，通过 `validateHostname` 函数验证目标主机名。\n\n资料来源：[apps/sim/lib/core/security/input-validation.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/core/security/input-validation.ts)\n\n**验证功能：**\n\n- 检查是否为私有 IP 地址\n- 阻止本地主机访问\n- 过滤保留地址和特殊地址\n\n```typescript\nexport function validateHostname(\n hostname: string | null | undefined,\n paramName = 'hostname'\n): ValidationResult {\n // 实现主机名安全性验证\n}\n```\n\n### Webhook 安全验证\n\n项目实现了待验证 Webhook 的安全处理机制，支持多种提供商的事件验证。\n\n资料来源：[apps/sim/lib/webhooks/pending-verification.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/pending-verification.ts)\n\n支持的提供商包括：\n\n- Ashby\n- Grain\n- Salesforce\n- Generic (通用)\n\n---\n\n## 构建与部署流程\n\n### 应用构建\n\n```bash\n# 标准构建\nbun run build\n\n# 仅构建沙箱bundles\nbun run build:sandbox-bundles\n```\n\n资料来源：[apps/sim/package.json](https://github.com/simstudioai/sim/blob/main/apps/sim/package.json)\n\n### 构建流程架构\n\n```mermaid\ngraph LR\n A[源码] --> B[bun run build:sandbox-bundles]\n B --> C[沙箱Bundle生成]\n C --> D[Next.js Build]\n D --> E[Docker Image]\n E --> F[Container Registry]\n```\n\n### 代码质量检查\n\n| 命令 | 说明 |\n|------|------|\n| `lint` | 运行 Biome 代码检查并自动修复 |\n| `lint:check` | 仅检查不修复 |\n| `format` | 运行代码格式化 |\n| `format:check` | 仅检查格式 |\n| `type-check` | TypeScript 类型检查 |\n\n---\n\n## 部署最佳实践\n\n### 生产环境检查清单\n\n- [ ] 使用 Docker Compose 或 Kubernetes 进行部署\n- [ ] 配置 PostgreSQL 外部持久化存储\n- [ ] 启用 Redis 缓存集群\n- [ ] 配置环境变量而非硬编码配置\n- [ ] 设置适当的副本数和资源限制\n- [ ] 配置健康检查探针（liveness/readiness）\n- [ ] 设置安全的镜像拉取策略\n- [ ] 配置日志收集和监控\n\n### 推荐配置示例\n\n```yaml\n# values.prod.yaml\napp:\n replicaCount: 3\n resources:\n limits:\n cpu: \"2000m\"\n memory: \"4Gi\"\n requests:\n cpu: \"1000m\"\n memory: \"2Gi\"\n livenessProbe:\n httpGet:\n path: /api/health\n port: 3000\n initialDelaySeconds: 30\n periodSeconds: 10\n```\n\n---\n\n## 相关文档\n\n- [官方自托管文档](https://docs.sim.ai/self-hosting/docker)\n- [Ollama 集成指南](https://docs.sim.ai/self-hosting/docker)\n- [vLLM 配置说明](https://docs.vllm.ai/)\n- [Helm Chart 完整配置](https://github.com/simstudioai/sim/blob/main/helm/sim/README.md)\n\n---\n\n\n\n## 扩展与定制\n\n### 相关页面\n\n相关主题：[块系统与注册表](#page-block-registry), [连接器框架](#page-connectors)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [apps/sim/blocks/blocks/custom](https://github.com/simstudioai/sim/blob/main/apps/sim/blocks/blocks/custom)\n- [apps/sim/api/tools/custom/route.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/api/tools/custom/route.ts)\n- [apps/sim/app/api/mcp](https://github.com/simstudioai/sim/blob/main/apps/sim/app/api/mcp)\n- [apps/sim/app/api/copilot](https://github.com/simstudioai/sim/blob/main/apps/sim/app/api/copilot)\n- [apps/sim/ee](https://github.com/simstudioai/sim/blob/main/apps/sim/ee)\n- [.agents/skills](https://github.com/simstudioai/sim/blob/main/.agents/skills)\n- [scripts/generate-docs.ts](https://github.com/simstudioai/sim/blob/main/scripts/generate-docs.ts)\n- [apps/sim/lib/workflows/triggers/triggers.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/workflows/triggers/triggers.ts)\n- [apps/sim/lib/api/contracts/types.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/api/contracts/types.ts)\n- [apps/sim/lib/webhooks/pending-verification.ts](https://github.com/simstudioai/sim/blob/main/apps/sim/lib/webhooks/pending-verification.ts)\n
\n\n# 扩展与定制\n\n## 概述\n\nSim 平台提供了丰富的扩展与定制机制，允许开发者在多个层面自定义和扩展系统功能。这些扩展点包括自定义块（Custom Blocks）、API 路由扩展、Webhook 集成、MCP（Model Context Protocol）扩展以及 Copilot 扩展。Sim 的设计理念强调模块化和可插拔性，使得开发者能够根据业务需求灵活地添加新功能，同时保持核心系统的稳定性和一致性。\n\n扩展机制的核心架构遵循以下原则：首先，所有扩展都通过标准化的接口定义进行注册和管理；其次，扩展遵循统一的数据模型和类型系统；最后，扩展可以访问相同的核心服务和工具函数库。这种设计确保了扩展与核心系统之间的高度兼容性，同时也便于维护和升级。\n\nSim 的扩展系统还支持自动化文档生成，通过 `scripts/generate-docs.ts` 脚本可以扫描块目录并提取元数据，自动生成标准化的 Markdown 文档。文档生成器会扫描 `apps/sim/blocks/blocks/` 目录，提取每个块的名称、描述、分类、输入输出规范以及配置参数，然后更新导航元数据文件。这种自动化机制确保了文档与代码的同步更新，减少了人工维护的工作量。\n\n## 自定义块系统\n\n### 块结构与定义\n\n自定义块是 Sim 平台扩展的基本单元，每个块都遵循统一的定义规范。块的定义包括元数据（名称、描述、分类）、输入输出规格以及配置参数。块的元数据存储在定义文件中，文档生成器会扫描这些文件并提取相关信息。块的分类决定了其在工作流设计器中的展示位置和分组方式，常见的分类包括触发器（triggers）、工具（tools）、转换器（transformers）等。\n\n块系统支持多种类型的输入输出连接，包括字符串、数字、布尔值、数组、对象等数据类型。每个块可以定义多个输入端口和输出端口，端口之间的连接遵循类型兼容性规则。块的配置参数允许用户在实例化块时指定行为选项，这些参数在运行时被读取并传递给块的执行逻辑。\n\n### 自定义块注册\n\n自定义块的注册通过 `@/blocks` 模块进行管理，该模块提供了获取块、获取所有块、获取块类型等接口。块的注册表（registry）存储了所有可用块的引用，开发者可以通过 `getBlock` 函数根据块类型获取块定义，通过 `getBlocksByCategory` 函数获取特定分类下的所有块。块的验证通过 `isValidBlockType` 函数进行，确保只有注册的有效块类型才能在工作流中使用。\n\n块的注册过程还支持按工具名称查找，通过 `getBlockByToolName` 函数可以根据工具的别名获取对应的块定义。这种设计使得块的定义与外部工具名称解耦，便于在不影响现有工作流的情况下替换或升级底层实现。块的注册表还支持动态更新，允许在运行时添加或移除块类型。\n\n### 块的执行与输出\n\n块的执行由执行器（executor）统一管理，执行器负责解析工作流、调度块执行、处理依赖关系以及收集输出。执行器提供了块输出处理模块（block-outputs），用于计算每个块的有效输出。有效输出的计算考虑了前置块的条件分支和循环结构，确保只有实际执行的块才会产生输出。\n\n块的输出格式遵循统一的数据结构，包括输出值、元数据、错误信息等字段。输出处理模块支持注释模式（annotation-only mode），在这种模式下块不会产生实际的执行结果，只记录执行信息。这种机制用于调试和性能分析，帮助开发者理解工作流的执行过程和性能瓶颈。\n\n```mermaid\ngraph TD\n A[工作流定义] --> B[块注册表]\n B --> C[块执行器]\n C --> D[依赖解析]\n D --> E[块执行]\n E --> F[输出收集]\n F --> G[结果聚合]\n C --> H[块输出处理]\n H --> I[有效输出计算]\n I --> G\n```\n\n## API 扩展机制\n\n### 路由合约系统\n\nSim 的 API 扩展基于类型安全的路由合约系统，该系统定义在 `apps/sim/lib/api/contracts/types.ts` 中。路由合约（ApiRouteContract）是一个泛型类型，包含参数（params）、查询（query）、请求体（body）、请求头（headers）、响应模式（response mode）以及响应定义（response）等六个维度的类型信息。这种设计确保了 API 的输入输出在整个应用中都遵循一致的类型约束。\n\n路由合约系统提供了多个辅助类型来提取合约中的特定部分：`ContractParams` 用于提取参数类型，`ContractQuery` 用于提取查询参数类型，`ContractBody` 用于提取请求体类型，`ContractHeaders` 用于提取请求头类型。这些辅助类型通过 TypeScript 的条件类型（conditional types）实现，能够在编译时从合约定义中提取出对应的类型信息。\n\n响应模式支持两种类型：JSON 模式和流模式（stream mode）。JSON 模式适用于小规模的、结构化的响应数据，而流模式适用于需要逐步返回大量数据或实时更新场景的 API。路由合约的响应定义使用 Zod schema 进行声明式验证，确保 API 的响应符合预期的数据结构。\n\n### 自定义 API 路由\n\n自定义 API 路由位于 `apps/sim/api/tools/custom/route.ts`，开发者可以在此目录下添加新的 API 端点。路由文件遵循 Next.js 的 API 路由规范，每个文件导出一个或多个 HTTP 方法处理器（GET、POST、PUT、DELETE 等）。路由处理器接收请求上下文，包括请求参数、查询字符串、请求体和请求头，然后执行业务逻辑并返回响应。\n\n自定义路由的开发流程包括：定义路由合约、指定请求处理逻辑、注册路由到应用。对于需要认证的路由，路由处理器可以通过中间件机制注入认证信息。对于需要访问数据库的路由，路由处理器通过依赖注入获取数据库连接实例。这种设计保持了路由逻辑的纯净性，便于单元测试和代码复用。\n\nAPI 路由的验证层自动使用合约定义中的 schema 进行输入验证，验证失败时返回标准化的错误响应。验证包括类型检查、格式验证、范围验证以及自定义验证规则。验证规则的定义使用 Zod 库，支持链式调用和复合条件，使得复杂的数据验证逻辑易于表达和维护。\n\n### Confluence 工具集成\n\nSim 提供了与 Atlassian Confluence 的深度集成，作为 API 扩展的一部分。Confluence 相关的路由定义位于 `apps/sim/lib/api/contracts/selectors/confluence.ts`，包括空间选择器（spaces selector）、页面选择器（pages selector）和页面详情获取等端点。这些端点提供了统一的接口来查询和操作 Confluence 内容。\n\nConfluence 路由使用通用的响应类型（`z.unknown()`），因为不同的 Confluence API 端点返回的数据结构差异较大。这种设计提供了灵活性，允许调用方处理任意形状的响应数据。路由合约定义了查询参数和请求体的 schema，但响应数据保持无类型状态，由调用方负责解析和处理。\n\nConfluence 集成支持分页查询，返回结果包含数据数组和游标（cursor）信息。调用方可以使用游标进行后续查询，实现大结果集的遍历。空间选择器返回空间列表和可选的下一页游标，页面选择器返回文件列表，每个文件包含标识符和名称等基本信息。\n\n## Webhook 集成系统\n\n### Webhook 提供者架构\n\nSim 的 Webhook 系统支持多个第三方服务的集成，包括 Gong、Webflow、Vercel、Typeform 等。每个提供者（provider）实现统一的接口，提供事件解析、数据转换、认证验证和事件过滤等功能。提供者架构定义在 `apps/sim/lib/webhooks/` 目录下，每个提供者位于独立的子目录中。\n\nWebhook 处理流程包括接收请求、验证签名、解析事件、过滤事件、转换数据和触发工作流等步骤。每个步骤都可以由提供者自定义实现，以适应不同服务的特性。例如，Gong 提供者可能需要提取通话相关的元数据，而 Webflow 提供者可能需要处理 CMS 内容更新事件。\n\n### 事件过滤机制\n\n事件过滤是 Webhook 集成的关键功能，用于避免处理不相关的事件。每个提供者可以实现 `shouldSkipEvent` 方法，根据事件内容决定是否跳过处理。过滤条件通常基于配置参数，例如 Webflow 提供者可以根据配置的集合标识符（collectionId）过滤事件，只处理指定集合的更新。\n\n过滤逻辑的执行发生在事件解析之后、工作流触发之前，这样可以确保过滤决策基于完整的解析后数据。提供者接收事件上下文（EventFilterContext），包括 Webhook 配置、请求体和请求标识符等信息。过滤决策由同步函数执行，返回布尔值表示是否跳过该事件。\n\n### 待验证 Webhook 处理\n\n某些 Webhook 服务（如 Shopify、Webflow）要求接收方响应验证请求，以确认端点的有效性。Sim 实现了待验证 Webhook 处理机制，位于 `apps/sim/lib/webhooks/pending-verification.ts`。该机制支持多种验证协议，包括 GET 请求验证、HEAD 请求验证和 POST 请求验证。\n\n验证请求的存储使用 Redis 作为持久化后盾，同时维护内存缓存以提高查询性能。验证条目包含路径、过期时间和元数据，Redis 键使用前缀 `REDIS_KEY_PREFIX` 命名以避免与其他数据冲突。验证条目过期后自动从存储中移除，无需手动清理。\n\n支持的待验证 Webhook 提供者包括 Ashby、Grain、Generic 和 Salesforce。每个提供者定义匹配器（matcher），用于判断请求是否属于待验证请求。匹配器检查请求方法、请求体结构和特定字段值。例如，Generic 提供者的匹配规则是：GET 或 HEAD 请求，或者空请求体的 POST 请求。\n\n## MCP 扩展\n\n### MCP 协议概述\n\nMCP（Model Context Protocol）是一种用于扩展 AI 模型能力的协议标准，Sim 通过 `apps/sim/app/api/mcp` 端点提供 MCP 支持。MCP 扩展允许外部系统通过标准化接口调用 Sim 的功能，同时支持工具注册、资源访问和提示模板等功能。MCP 协议采用 JSON-RPC 格式进行通信，支持请求-响应和通知两种消息模式。\n\nMCP 扩展的核心组件包括：工具注册表、资源管理器、提示引擎和会话管理器。工具注册表维护所有可用 MCP 工具的定义，包括工具名称、描述、参数 schema 和返回值类型。资源管理器提供对 Sim 内部数据的受控访问，支持基于权限的数据隔离。提示引擎允许调用方定义和复用复杂的提示模板。\n\n### MCP 端点实现\n\nMCP 端点实现遵循 JSON-RPC 2.0 规范，支持 `initialize`、`tools/list`、`tools/call`、`resources/list`、`resources/read` 等标准方法。端点接收 JSON-RPC 请求，执行对应的处理逻辑，并返回 JSON-RPC 响应。错误响应包含错误代码、消息和可选的附加数据。\n\n工具调用是 MCP 扩展的核心功能，允许外部系统触发 Sim 中的工作流或执行特定操作。工具调用请求包含工具名称和参数对象，响应包含执行结果或错误信息。工具调用的执行由工作流执行引擎驱动，支持同步和异步两种执行模式。异步执行模式返回任务标识符，调用方可以通过任务标识符查询执行状态和结果。\n\n### MCP 工具定义\n\nMCP 工具的定义存储在配置文件中，定义了工具的元数据和行为规范。每个工具定义包括唯一标识符、显示名称、描述文本、参数 schema 和返回值 schema。参数 schema 使用 JSON Schema 格式，支持必填参数、可选参数、类型约束和默认值等特性。\n\n工具定义的版本管理支持向后兼容性，工具实现可以识别旧版本的参数并提供兼容处理。工具的参数验证在执行前进行，验证失败时返回明确的错误信息，指导调用方提供正确的参数。工具的返回值类型在工具定义中声明，调用方可以依赖这些信息进行类型安全的响应处理。\n\n## Copilot 扩展\n\n### Copilot 集成架构\n\nCopilot 扩展提供与 AI 编程助手的功能集成，位于 `apps/sim/app/api/copilot` 端点。Copilot 集成允许 AI 模型访问 Sim 的上下文信息，包括工作流定义、块配置、执行历史等。这种集成使得 AI 模型能够基于实际的项目上下文生成更准确的建议和代码。\n\nCopilot 扩展采用插件架构，核心系统提供基础接口，扩展模块实现具体的 AI 提供者适配。当前实现支持主流的 AI 提供者，包括 OpenAI、Anthropic 和本地模型服务。每个提供者适配器处理认证、请求格式化和响应解析等细节，使得上层逻辑与具体的 AI 服务解耦。\n\n### 上下文管理\n\nCopilot 扩展的上下文管理模块负责收集和组织传递给 AI 模型的信息。上下文信息来源包括：工作流配置、块定义、变量值、用户偏好和历史交互等。上下文信息的收集遵循最小必要原则，避免传递过多无关信息影响 AI 模型的处理效率和响应质量。\n\n上下文信息的组织采用分层结构，包括全局上下文、工作流上下文和块级上下文三个层次。全局上下文包含项目级别的通用信息，工作流上下文包含特定工作流的配置和状态，块级上下文包含单个块的详细信息。分层组织便于 AI 模型根据需要访问不同范围的信息。\n\n### 建议生成与执行\n\nCopilot 扩展的建议生成功能基于上下文信息和用户请求，生成工作流配置建议、块参数建议和优化建议等。建议的生成由 AI 模型驱动，模型根据上下文推理出最可能的用户意图，然后生成相应的建议内容。建议的格式可以是完整的配置片段，也可以是增量修改指令。\n\n建议的执行支持预览和确认机制，用户可以在执行前预览建议的效果，确认无误后再应用到实际的工作流中。执行过程记录在审计日志中，便于追踪建议的来源和执行结果。Copilot 扩展还支持反馈收集，用户可以对建议的质量进行评分，评分信息用于持续改进建议生成模型。\n\n## 触发器系统\n\n### 触发器类型\n\n触发器是工作流的入口点，决定了工作流何时以及如何被激活。Sim 支持多种触发器类型，包括手动触发（manual）、API 触发（api）、聊天触发（chat）和定时触发（scheduled）。触发器类型的识别通过 `TRIGGER_TYPES` 常量和 `classifyStartBlockType` 函数实现，支持新的显式分类方式和旧版的触发模式标记。\n\n触发器类型的分类逻辑首先检查块配置中的分类是否为 'triggers'，然后检查块是否启用了 `triggerMode` 标记，最后检查块类型是否为遗留的起始块（starter block）。这种多层检查确保了向后兼容性，同时支持新的触发器设计模式。\n\n### 触发器引用别名\n\n触发器引用别名机制允许在工作流中使用简短的别名来引用触发器类型。`TRIGGER_REFERENCE_ALIAS_MAP` 定义了别名到具体触发器类型的映射，包括 `start`、`api`、`chat` 和 `manual` 四个别名。这些别名用于内联引用，格式为 ``、`` 等。\n\n别名映射的设计简化了工作流的编写，用户无需记忆完整的触发器类型标识符。别名到类型的映射是单向的，具体类型到别名的反向映射需要额外实现。别名机制还支持自定义扩展，开发者可以在映射表中添加新的别名和对应的触发器类型。\n\n### 触发器工具函数\n\n`TriggerUtils` 类提供了一系列工具函数用于操作和检查触发器。`isTriggerBlock` 函数判断给定的块是否是触发器类型，检查逻辑包括分类、模式和旧版标识三个维度。`isTriggerType` 函数判断块是否属于特定的触发器类型，接收块对象和目标类型作为参数。\n\n触发器输出（trigger outputs）由 `getTriggerOutputs` 函数获取，返回触发器块产生的输出数据。这些输出数据可以在后续的块中使用，传递触发事件的相关信息，例如 Webhook 请求内容、API 调用参数或定时触发的时间戳等。输出数据的格式和内容取决于触发器类型和配置。\n\n```mermaid\ngraph TD\n A[触发事件] --> B{触发器类型判断}\n B -->|manual| C[手动触发器]\n B -->|api| D[API 触发器]\n B -->|chat| E[聊天触发器]\n B -->|scheduled| F[定时触发器]\n C --> G[读取子块配置]\n D --> G\n E --> G\n F --> G\n G --> H[返回触发模式]\n H --> I[startWorkflow 子块]\n I --> J[触发器输出]\n```\n\n## 企业扩展（EE）\n\n### 企业功能架构\n\n企业扩展（Enterprise Edition）模块位于 `apps/sim/ee` 目录，提供面向大规模部署和企业级应用的增强功能。企业扩展包括高级安全特性、审计日志、细粒度权限控制、高可用部署支持等功能。这些功能面向有严格合规要求和运营标准的企业客户。\n\n企业扩展的设计遵循模块化原则，核心功能与扩展功能分离部署。企业功能可以作为独立模块启用或禁用，不需要修改核心代码。这种设计降低了企业的使用门槛，同时保持了核心系统的简洁性。企业功能的配置通过环境变量和管理界面进行，支持动态生效。\n\n### 企业级 API\n\n企业扩展提供了增强的 API 接口，包括批量操作支持、异步处理能力和高级过滤选项。批量操作 API 允许一次请求处理多个资源，适用于数据迁移和批量配置等场景。异步处理 API 返回任务标识符，调用方可以轮询或等待任务完成通知。\n\n企业 API 的认证机制支持多种协议，包括 OAuth 2.0、SAML 和 LDAP。企业 API 的限流策略比标准 API 更宽松，但需要额外的配额管理机制。配额信息通过 `UsageLimits` 接口获取，包括同步限流、异步限流、当前使用量和限额等信息。\n\n## 技能系统\n\n### 技能定义与注册\n\n技能（Skills）系统位于 `.agents/skills` 目录，定义了 AI 代理可以执行的操作集合。技能是比块更高级的抽象，一个技能可能由多个块组成，形成完整的操作流程。技能的注册和管理由技能引擎处理，支持技能的发现、调用和监控。\n\n技能定义包含技能标识符、名称、描述、参数定义、返回值定义和实现代码。参数和返回值使用类型化的 schema 定义，支持复杂的嵌套结构和自定义验证规则。实现代码支持多种语言和执行环境，包括 JavaScript、Python 和 Shell 脚本等。\n\n### 技能编排\n\n技能的编排功能允许组合多个技能形成更复杂的操作序列。编排支持顺序执行、并行执行和条件分支三种基本模式。顺序执行按照定义的顺序依次调用技能，前一个技能的输出作为后一个技能的输入。并行执行同时调用多个技能，提高执行效率，适用于独立的操作。\n\n条件分支根据中间结果决定后续执行的技能路径。条件表达式支持简单的比较操作和复杂的布尔逻辑。编排的执行由编排引擎驱动，引擎负责管理执行上下文、处理异常和维护执行状态。编排失败时支持回滚操作，恢复到执行前的状态。\n\n## 测试与验证框架\n\n### 测试工具库\n\nSim 提供了完整的测试工具库，位于 `packages/testing/src` 目录。测试工具库包括环境变量模拟（env mock）、数据库模拟、网络请求模拟等功能。环境变量模拟（`createEnvMock`）允许测试用例覆盖和恢复环境变量值，支持字符串、数字和布尔值类型的模拟。\n\n环境变量模拟提供了多种辅助函数：`getEnv` 返回模拟的值，`isTruthy` 判断真值，`isFalsy` 判断假值，`envNumber` 解析数字并支持最小值约束。这些辅助函数覆盖了环境变量处理的各种场景，确保测试用例能够模拟真实的运行环境。\n\n### 模拟与存根\n\n测试工具库提供了完善的模拟和存根功能，用于隔离被测试代码的依赖。模拟（mock）替换整个模块的实现，存根（stub）替换特定的函数或方法。模拟和存根的配置通过工厂函数创建，支持默认行为定义和行为覆盖。\n\n测试工具库还提供了预设的模拟集合（`envMock`），可以直接用于常见的测试场景。预设模拟包含合理的环境变量默认值，无需额外的配置即可在测试中使用。这种开箱即用的设计简化了测试用例的编写，同时保证了测试环境的一致性。\n\n### 集成测试支持\n\n集成测试支持模块提供了端到端的测试能力，包括 API 测试、Webhook 测试和工作流测试等。API 测试使用路由合约定义进行请求构造和响应验证，确保 API 的行为符合规范。Webhook 测试模拟外部服务的请求，验证 Webhook 处理器的解析和过滤逻辑。\n\n工作流测试支持完整的工作流执行模拟，包括触发器激活、块执行和输出收集等步骤。测试用例可以控制块的模拟返回值，验证工作流在各种输入条件下的行为。测试结果包括执行时间、块调用顺序和输出数据，便于分析工作流的性能和正确性。\n\n## 扩展开发最佳实践\n\n### 代码组织\n\n扩展代码应遵循统一的目录结构和命名约定。自定义块放在 `apps/sim/blocks/blocks/custom` 目录下，每个块独占一个子目录，目录名称使用 kebab-case 格式。块的定义文件使用 `index.ts` 命名，导出块的元数据和实现函数。\n\nAPI 扩展放在 `apps/sim/api/tools/custom` 目录下，遵循 Next.js 的 API 路由文件命名规范。路由文件使用 `route.ts` 命名，导出一个或多个 HTTP 方法处理器。相关的类型定义和工具函数放在同目录的 `*.ts` 文件中，与路由文件保持同级的组织关系。\n\n### 文档维护\n\n扩展开发者应维护清晰的代码文档，文档使用 JSDoc 格式编写。块定义需要包含名称、描述、输入输出说明和使用示例。API 路由需要包含端点说明、参数说明和响应示例。文档生成器会从代码注释中提取信息，自动生成用户文档。\n\n手动添加的文档内容应放在指定的区域，使用标记 `` 和 `` 包裹。文档生成器会保留手动添加的内容，不会被自动生成的内容覆盖。这种机制允许开发者在自动文档的基础上添加额外的说明、示例和注意事项。\n\n### 安全性考虑\n\n扩展开发应遵循安全最佳实践，避免引入安全漏洞。所有用户输入必须进行验证和清理，使用 Zod schema 或自定义验证函数。用户输入不应直接用于数据库查询或命令执行，应使用参数化查询和安全的 API 调用。\n\n敏感信息（如 API 密钥、访问令牌）不应硬编码在代码中，应使用环境变量或密钥管理服务。Webhook 处理应验证请求签名，防止伪造请求攻击。API 端点应实现适当的限流和认证机制，防止滥用和未授权访问。\n\n## 配置选项参考\n\n| 配置类别 | 选项名称 | 类型 | 默认值 | 说明 |\n|---------|---------|------|--------|------|\n| 构建 | `NODE_OPTIONS` | string | `--max-old-space-size=8192` | Node.js 运行时选项 |\n| 构建 | `build:sandbox-bundles` | command | - | 沙箱包构建命令 |\n| 测试 | `test` | command | `vitest run` | 测试运行命令 |\n| 测试 | `test:coverage` | command | `vitest run --coverage` | 覆盖率测试命令 |\n| 类型检查 | `type-check` | command | `tsc --noEmit` | TypeScript 类型检查 |\n| 格式 | `lint` | command | `biome check --write` | 代码检查和修复 |\n| 格式 | `format` | command | `biome format --write` | 代码格式化 |\n| 文档 | `generate-docs` | command | `bun run ../../scripts/generate-docs.ts` | 文档生成 |\n\n## 相关资源\n\n- 官方文档：https://docs.sim.ai\n- GitHub 仓库：https://github.com/simstudioai/sim\n- Docker 部署文档：https://docs.sim.ai/self-hosting/docker\n- 本地模型支持：Ollama（https://ollama.ai）、vLLM（https://docs.vllm.ai/）\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：simstudioai/sim\n\n摘要：发现 20 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 社区讨论暴露的待验证问题：Open-source general purpose agent with built-in MCPToolkit support。\n\n## 1. 安装坑 · 社区讨论暴露的待验证问题：Open-source general purpose agent with built-in MCPToolkit support\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：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.\n- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。\n- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。\n- 证据：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\n\n## 2. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | host_targets=cursor\n\n## 3. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | README/documentation is current enough for a first validation pass.\n\n## 4. 运行坑 · 来源证据：v0.6.63\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.6.63\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5a97e1d742fe4d7f918e0b42f27b87c3 | https://github.com/simstudioai/sim/releases/tag/v0.6.63 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 5. 运行坑 · 来源证据：v0.6.65\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.6.65\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_03f18559029c4724b11011ef96259161 | https://github.com/simstudioai/sim/releases/tag/v0.6.65 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 运行坑 · 来源证据：v0.6.67\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.6.67\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_048d1506c1d645b0be435841a26b93ed | https://github.com/simstudioai/sim/releases/tag/v0.6.67 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 运行坑 · 来源证据：v0.6.73\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.6.73\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_048864e1cdcc44d2b2a30917b7c4adc2 | https://github.com/simstudioai/sim/releases/tag/v0.6.73 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 维护坑 · 来源证据：v0.6.71\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v0.6.71\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9c30d794fb7344489f96a6ac47cd1d6e | https://github.com/simstudioai/sim/releases/tag/v0.6.71 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | last_activity_observed missing\n\n## 10. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 12. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 来源证据：Unable to Access Files from Private GitHub Repository in Self-Hosted Setup\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Unable to Access Files from Private GitHub Repository in Self-Hosted Setup\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ed1c9f64533441f5826c1fe98fa9ce49 | https://github.com/simstudioai/sim/issues/4555 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 14. 安全/权限坑 · 来源证据：v0.6.64\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.6.64\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5e2aa5311b1748cea446771920242668 | https://github.com/simstudioai/sim/releases/tag/v0.6.64 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 15. 安全/权限坑 · 来源证据：v0.6.66\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.6.66\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7d42c79fecf54003b117f76d49873223 | https://github.com/simstudioai/sim/releases/tag/v0.6.66 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：v0.6.68\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.6.68\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c8fe17ce7ba6424c88017ed644620915 | https://github.com/simstudioai/sim/releases/tag/v0.6.68 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：v0.6.69\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.6.69\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a47b6988921146ac8fa66d73b0574c88 | https://github.com/simstudioai/sim/releases/tag/v0.6.69 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：v0.6.72\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.6.72\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f13817452da14b5d97c64bde45647685 | https://github.com/simstudioai/sim/releases/tag/v0.6.72 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 19. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | issue_or_pr_quality=unknown\n\n## 20. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | release_recency=unknown\n\n\n", "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "Human Manual / 人类版说明书" }, "pitfall_log": { "asset_id": "pitfall_log", "filename": "PITFALL_LOG.md", "markdown": "# Pitfall Log / 踩坑日志\n\n项目：simstudioai/sim\n\n摘要：发现 20 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 社区讨论暴露的待验证问题：Open-source general purpose agent with built-in MCPToolkit support。\n\n## 1. 安装坑 · 社区讨论暴露的待验证问题：Open-source general purpose agent with built-in MCPToolkit support\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：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.\n- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。\n- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。\n- 证据：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\n\n## 2. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | host_targets=cursor\n\n## 3. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | README/documentation is current enough for a first validation pass.\n\n## 4. 运行坑 · 来源证据：v0.6.63\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.6.63\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5a97e1d742fe4d7f918e0b42f27b87c3 | https://github.com/simstudioai/sim/releases/tag/v0.6.63 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 5. 运行坑 · 来源证据：v0.6.65\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.6.65\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_03f18559029c4724b11011ef96259161 | https://github.com/simstudioai/sim/releases/tag/v0.6.65 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 运行坑 · 来源证据：v0.6.67\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.6.67\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_048d1506c1d645b0be435841a26b93ed | https://github.com/simstudioai/sim/releases/tag/v0.6.67 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 运行坑 · 来源证据：v0.6.73\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.6.73\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_048864e1cdcc44d2b2a30917b7c4adc2 | https://github.com/simstudioai/sim/releases/tag/v0.6.73 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 维护坑 · 来源证据：v0.6.71\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v0.6.71\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9c30d794fb7344489f96a6ac47cd1d6e | https://github.com/simstudioai/sim/releases/tag/v0.6.71 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | last_activity_observed missing\n\n## 10. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 12. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 来源证据：Unable to Access Files from Private GitHub Repository in Self-Hosted Setup\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Unable to Access Files from Private GitHub Repository in Self-Hosted Setup\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ed1c9f64533441f5826c1fe98fa9ce49 | https://github.com/simstudioai/sim/issues/4555 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 14. 安全/权限坑 · 来源证据：v0.6.64\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.6.64\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5e2aa5311b1748cea446771920242668 | https://github.com/simstudioai/sim/releases/tag/v0.6.64 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 15. 安全/权限坑 · 来源证据：v0.6.66\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.6.66\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7d42c79fecf54003b117f76d49873223 | https://github.com/simstudioai/sim/releases/tag/v0.6.66 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：v0.6.68\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.6.68\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c8fe17ce7ba6424c88017ed644620915 | https://github.com/simstudioai/sim/releases/tag/v0.6.68 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：v0.6.69\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.6.69\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a47b6988921146ac8fa66d73b0574c88 | https://github.com/simstudioai/sim/releases/tag/v0.6.69 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：v0.6.72\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.6.72\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f13817452da14b5d97c64bde45647685 | https://github.com/simstudioai/sim/releases/tag/v0.6.72 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 19. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | issue_or_pr_quality=unknown\n\n## 20. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | art_4c769793e2db44b09c3ad8f55672a2ea | https://github.com/simstudioai/sim#readme | release_recency=unknown\n", "summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。", "title": "Pitfall Log / 踩坑日志" }, "prompt_preview": { "asset_id": "prompt_preview", "filename": "PROMPT_PREVIEW.md", "markdown": "# sim - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 sim 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Cursor\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-project-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-system-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. page-workflow-execution：工作流执行引擎。围绕“工作流执行引擎”模拟一次用户任务，不展示安装或运行结果。\n4. page-block-registry：块系统与注册表。围绕“块系统与注册表”模拟一次用户任务，不展示安装或运行结果。\n5. page-agent-integration：代理与AI集成。围绕“代理与AI集成”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-project-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-system-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-workflow-execution\n输入：用户提供的“工作流执行引擎”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-block-registry\n输入：用户提供的“块系统与注册表”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-agent-integration\n输入：用户提供的“代理与AI集成”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-project-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-system-architecture：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-workflow-execution：Step 3 必须围绕“工作流执行引擎”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-block-registry：Step 4 必须围绕“块系统与注册表”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-agent-integration：Step 5 必须围绕“代理与AI集成”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/simstudioai/sim#readme\n- .agents/skills/add-block/SKILL.md\n- .agents/skills/add-connector/SKILL.md\n- .agents/skills/add-integration/SKILL.md\n- .agents/skills/add-tools/SKILL.md\n- .agents/skills/add-trigger/SKILL.md\n- .agents/skills/cleanup/SKILL.md\n- .agents/skills/emcn-design-review/SKILL.md\n- .agents/skills/react-query-best-practices/SKILL.md\n- .agents/skills/ship/SKILL.md\n- .agents/skills/validate-connector/SKILL.md\n- .agents/skills/validate-integration/SKILL.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 sim 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n", "summary": "不安装项目也能感受能力节奏的安全试用 Prompt。", "title": "Prompt Preview / 安装前试用 Prompt" }, "quick_start": { "asset_id": "quick_start", "filename": "QUICK_START.md", "markdown": "# Quick Start / 官方入口\n\n项目：simstudioai/sim\n\n## 官方安装入口\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx simstudio\n```\n\n来源：https://github.com/simstudioai/sim#readme\n\n## 来源\n\n- docs: https://github.com/simstudioai/sim#readme\n", "summary": "从项目官方 README 或安装文档提取的开工入口。", "title": "Quick Start / 官方入口" } }, "validation_id": "dval_e4a6850475664ddc95ab003825de16a5" }