企业官网建设流程全解析

gent 在后台跑 Agent Loop（调工具、读文件、执行命令）→ 流式输出结果到 UI。

在集成 SDK 之前，Motive 的 Agent 后端长这样：

Motive App (SwiftUI) └── OpenCodeBridge (actor) ├── OpenCodeServer — 启动外部 opencode 二进制进程 (opencode serve) ├── SSEClient — 通过 Server-Sent Events 接收流式事件 └── OpenCodeAPIClient — 通过 REST API 发送 prompt、回复权限请求

每次用户发 prompt，Motive 要：

1. 启动一个外部opencode serve进程（如果没在跑的话）
2. 通过 REST APIPOST /sessions创建会话
3. 通过 REST APIPOST /sessions/{id}/prompt发送 prompt
4. 通过 SSE 连接接收事件流（文本片段、工具调用、完成信号等）

这套架构能用，但有几个问题：

• 依赖外部二进制：用户要自己安装opencodeCLI，Motive 还要处理二进制签名、路径查找
• 进程间通信开销：REST API + SSE 意味着事件要经过 HTTP 序列化/反序列化
• 启动延迟：外部进程冷启动需要时间
• 调试困难：跨进程的问题很难定位

SDK 的出现正好给了另一种可能——把 Agent Loop 直接跑在应用进程内。

目标：SDKBridge

我想做的替换：不启动外部进程，不经过 HTTP，直接在 Motive 进程内用 SDK 的Agent.stream()跑 Agent Loop。

目标架构：

Motive App (SwiftUI) └── BackendBridge (enum wrapper) ├── .opencode → OpenCodeBridge (原有架构，保留) └── .sdk → SDKBridge (新增，用 OpenAgentSDK) └── Agent.stream() → 直接在进程内跑 Agent Loop

保留原有的OpenCodeBridge作为备选，让用户可以在设置中切换后端类型。这是一个务实的决定——万一 SDK 后端有问题，用户还能切回去。

第一步：BackendBridge 抽象层

原有的OpenCodeBridge是一个 actor，Motive 的AppState直接跟它交互。现在要加一个平行的SDKBridge，需要一个分派层。

我用了一个enum而不是 protocol：

enum BackendBridge { case opencode(OpenCodeBridge) case sdk(SDKBridge) func submitIntent(text: String, cwd: String, ...) async { ... } func interrupt() async { ... } func stop() async { ... } // ... }

为什么不用 protocol？因为OpenCodeBridge和SDKBridge的能力不完全一样。OpenCodeBridge有权限请求（permission）、问题回复（question）等 SDK 后端不需要的概念。用 enum 可以在共享接口上做统一分派，同时保留各自特有的方法：

// OpenCode-only 方法，SDK 后端直接 no-op func replyToQuestion(requestID: String, answers: [[String]], ...) async { guard case .opencode(let bridge) = self else { return } await bridge.replyToQuestion(requestID: requestID, answers: answers, ...) }

对于 AppState 来说，大部分代码不需要改——它调bridge.submitIntent()，至于底层是 HTTP 还是 SDK，它不关心。

第二步：SDKBridge 核心——361 行的 Actor

SDKBridge是整个替换的核心。它是一个 actor，负责：

1. 接收Configuration（API key、model、MCP servers 等）
2. 用 SDK 的createAgent()创建 Agent
3. 调用Agent.stream()获取流式响应
4. 把 SDK 的SDKMessage映射成 Motive 已有的OpenCodeEvent

配置

actor SDKBridge { struct Configuration: Sendable { let apiKey: String let model: String let provider: String // "anthropic", "openai", etc. let baseURL: String? let debugMode: Bool let projectDirectory: String let mcpEntries: [String: MCPEntry]? let env: [String: String]? let skillDirectories: [String]? } struct MCPEntry: Sendable { let command: String let args: [String]? let env: [String: String]? } }

MCPEntry是中间类型——Motive 的配置系统有自己的 MCP 描述格式，在传入 SDK 之前转成McpServerConfig.stdio。

创建 Agent

private func createAgent(from config: Configuration, sessionId: String? = nil) -> Agent { let provider: LLMProvider = Self.anthropicProviders.contains(config.provider) ? .anthropic : .openai let mcpServers = config.mcpEntries?.mapValues { entry in McpServerConfig.stdio(McpStdioConfig( command: entry.command, args: entry.args, env: entry.env )) } // 始终包含 core + specialist 工具，确保基本能力 let coreTools = getAllBaseTools(tier: .core) + getAllBaseTools(tier: .specialist) return OpenAgentSDK.createAgent(options: AgentOptions( apiKey: config.apiKey, model: config.model, baseURL: config.baseURL, provider: provider, permissionMode: .bypassPermissions, cwd: config.projectDirectory, tools: coreTools, mcpServers: mcpServers, sessionStore: sessionStore, sessionId: sessionId, skillDirectories: config.skillDirectories, logLevel: config.debugMode ? .debug : .none, env: config.env )) }

注意几个细节：

• provider 映射：Motive 用字符串（"anthropic"、"openai"），SDK 用LLMProvider枚举，这里做了转换
• core + specialist 工具：始终包含基础工具，即使 MCP 服务器连接失败，Agent 也有读写文件、执行命令的能力
• sessionStore + sessionId：传入 SessionStore 让 SDK 自动持久化对话历史，传入 sessionId 实现会话恢复

流式响应：submitIntent

这是最核心的方法。用户每次发 prompt 都走这里：

func submitIntent( text: String, cwd: String, agent: String? = nil, forceNewSession: Bool = false, correlationId: String? = nil ) async { guard let config = configuration else { eventContinuation.yield(OpenCodeEvent(kind: .error, rawJson: "", text: "SDK bridge not configured")) return } let sessionId = forceNewSession ? UUID().uuidString : (currentSessionId ?? UUID().uuidString) currentSessionId = sessionId // 创建 Agent let sdkAgent = createAgent(from: config, sessionId: sessionId) self.agent = sdkAgent // 取消之前的流 streamTask?.cancel() // 在后台 Task 中消费 stream streamTask = _Task { [weak self] in guard let self else { return } for await message in sdkAgent.stream(text) { guard !_Task.isCancelled else { return } await self.handleSDKMessage(message, sessionId: sessionId) } } }

用 Swift 的Task包裹stream()的for await循环，这样用户中断时可以 cancel 掉这个 Task。注意_Task是_Concurrency.Task的别名——因为 OpenAgentSDK 里也有个Task类型，直接用Task会冲突。

SDKMessage → OpenCodeEvent 映射

Motive 的 UI 已经有一套基于OpenCodeEvent的事件处理系统。与其重写 UI 层，不如在 bridge 层做映射：

private func handleSDKMessage(_ message: SDKMessage, sessionId: String) { switch message { case .partialMessage(let data): eventContinuation.yield(OpenCodeEvent(kind: .assistant, rawJson: "", text: data.text)) case .toolUse(let data): eventContinuation.yield(OpenCodeEvent(kind: .tool, rawJson: "", text: data.input, toolName: data.toolName, toolCallId: data.toolUseId)) case .toolResult(let data): let output = data.isError ? "Error: \(data.content)" : data.content eventContinuation.yield(OpenCodeEvent(kind: .tool, rawJson: "", text: "", toolName: "Result", toolOutput: output, toolCallId: data.toolUseId)) case .result(let data): // 映射 usage // 映射 finish / error ... default: break } }

eventContinuation是一个AsyncStream<OpenCodeEvent>.Continuation，在初始化时传入。AppState 在 MainActor 上消费这个流，驱动 UI 更新。这个设计让 SDKBridge 和 OpenCodeBridge 共用同一套 UI 处理逻辑——AppState 不知道也不关心事件来自哪个后端。

第三步：踩过的坑

这不是一次顺利的替换。以下是我遇到的真实问题。

坑 1：macOS GUI 应用没有 shell PATH

这是最头疼的问题。macOS 的 GUI 应用不继承用户的 shell 环境。SDK 的MCPStdioTransport用Process启动 MCP 子进程时，PATH里没有nvm、homebrew等路径——MCP 服务器找不到node、python。

解决方案：在buildSDKMcpServers()里手动构建扩展 PATH：

let extendedPath = configManager.buildExtendedPath(base: ProcessInfo.processInfo.environment["PATH"]) for entry in mcpEntries { var mergedEnv = spec.environment // ... mergedEnv["PATH"] = extendedPath // 注入扩展 PATH }

这样 MCP 子进程能找到正确的node/python可执行文件。OpenCode 后端没这个问题，因为opencodeCLI 是从终端启动的，自带完整 shell 环境。

坑 2：核心工具在无 MCP 时不加载

SDK 的assembleFullToolPool()在没有 MCP 服务器时走了一条短路径——只返回baseTools（用户自定义工具），不包含内置的 Core 和 Specialist 工具。这意味着如果不配 MCP，Agent 连Read、Write、Bash都没有。

修复：在createAgent()里始终传入 core + specialist 工具：

let coreTools = getAllBaseTools(tier: .core) + getAllBaseTools(tier: .specialist) return OpenAgentSDK.createAgent(options: AgentOptions( // ... tools: coreTools, // 始终包含 // ... ))

坑 3：时序问题——配置还没完成就发 prompt

AppState.start()里异步配置 bridge，但用户可能在配置完成之前就发了 prompt。这导致 "SDK bridge not configured" 错误。

修复：在每次submitIntent和resumeSession之前都调用configureBridge()，确保配置是最新的：

func submitIntent(...) async { await configureBridge() // 先确保配置完成 // 然后检查配置是否成功 guard configuration != nil else { ... } // ... }

坑 4：Swift Task 命名冲突

OpenAgentSDK 的类型命名跟 Swift 标准库有冲突——SDK 里有个Task类型（用于任务追踪），跟 Swift 并发的Task撞了。直接写Task { }编译器会找错类型。

用 typealias 解决：

private typealias _Task = _Concurrency.Task

然后所有地方用_Task { }代替Task { }。

坑 5：API Key 可选问题

不是所有 LLM 提供商都需要 API key。本地运行的 Ollama、LM Studio 就不需要。但 SDK 默认要求 API key 不为空。

修复：在配置时检查 provider 是否允许空 API key：

if apiKey.isEmpty, !configManager.provider.allowsOptionalAPIKey { lastErrorMessage = "API key required for SDK backend. Check Settings." return }

SDK 本身也支持空 API key——传入空字符串就行，它会跳过认证 header。

第四步：MCP 服务器配置 UI

为了让 SDK 后端能连接外部 MCP 工具，我在 Advanced Settings 里加了一个 MCP 服务器配置界面。用户可以添加自定义的 MCP stdio 服务器（配置命令、参数、环境变量），保存到 UserDefaults，然后在创建 Agent 时注入。

struct CustomMcpServerConfig: Codable, Identifiable { let id: UUID var name: String var command: String var args: [String] var env: [String: String] var enabled: Bool }

这些自定义服务器在buildSDKMcpServers()里跟 Skill 系统注册的 MCP 服务器合并，一起传给 SDK。

架构对比

替换前后的关键差异：

替换后代码量对比：

• SDKBridge.swift：361 行（新增）
• BackendBridge.swift：134 行（新增）
• AppState+Bridge.swift：+123/-16 行（修改）
• AdvancedSettingsView.swift：+309/-44 行（MCP UI）
• 其他测试和配置文件：+60/-8 行

总共净增约 600 行，换来的是去掉了对外部二进制的依赖。

验证结论

这次集成验证了 SDK 在以下方面的工程表现：

能用的部分：

• Agent.stream()的AsyncStream<SDKMessage>接口简洁，可以直接用在 SwiftUI 的响应式流程里
• SessionStore的会话持久化开箱即用，不需要自己管理 JSON 文件
• MCP stdio 连接在注入正确的 PATH 后稳定工作
• 多 provider 支持（Anthropic/OpenAI 兼容）覆盖了 Motive 已有的 provider 列表
• permissionMode: .bypassPermissions适合桌面应用的自动执行场景

需要注意的部分：

• macOS GUI 应用的环境变量（PATH）问题需要额外处理，这不是 SDK 的 bug，而是 macOS 的安全机制
• Swift 并发的Task命名冲突需要手动解决
• assembleFullToolPool()在无 MCP 时的短路径行为需要了解清楚

整体评价：SDK 的 API 设计对 GUI 应用集成是友好的。核心的createAgent+stream两个调用就替代了原来启动外部进程 + HTTP 服务 + SSE 客户端 + REST API 客户端四个组件。对于一个 361 行的 actor 来