NEE's Blog

深入 Open Agent SDK（六）：多 LLM 提供商与运行时控制

Wed, 22 Apr 2026 12:30:00 +0000

本文是「深入 Open Agent SDK (Swift)」系列第六篇（完结篇）。系列目录见这里。

一个 Agent 不应该绑定单一 LLM 提供商。不同任务适合不同模型——简单问题用便宜模型，复杂推理用贵模型，有些场景甚至需要本地模型。而且运行时的需求也在变化：用户可能中途要求更深度的思考，可能发现预算快用完了需要降级，可能想切换到本地模型省点钱。

Open Agent SDK 的做法是：定义一个统一的 LLMClient 协议，Anthropic 和 OpenAI 兼容提供商各有一个实现，Agent 内部全部用 Anthropic 格式处理。切换提供商只需要改一个配置参数，运行时还能动态切模型、调思考深度、控预算。

这篇文章分析 SDK 的多提供商适配机制和运行时控制能力。

一、LLMClient 协议——统一接口

先看协议定义：

public protocol LLMClient: Sendable {
    nonisolated func sendMessage(
        model: String,
        messages: [[String: Any]],
        maxTokens: Int,
        system: String?,
        tools: [[String: Any]]?,
        toolChoice: [String: Any]?,
        thinking: [String: Any]?,
        temperature: Double?
    ) async throws -> [String: Any]

    nonisolated func streamMessage(
        model: String,
        messages: [[String: Any]],
        maxTokens: Int,
        system: String?,
        tools: [[String: Any]]?,
        toolChoice: [String: Any]?,
        thinking: [String: Any]?,
        temperature: Double?
    ) async throws -> AsyncThrowingStream<SSEEvent, Error>
}

两个核心方法，一个阻塞一个流式。参数列表覆盖了主流 LLM API 的全部能力：模型选择、消息历史、token 上限、系统提示、工具定义、工具选择策略、思考配置、温度。

关键决策：返回值统一用 Anthropic 格式的字典。不管是 Anthropic 原生 API 还是 OpenAI 兼容 API，最终 Agent 内部拿到的都是同一种结构——content 数组里是 {"type": "text", "text": "..."} 或 {"type": "tool_use", "name": "...", "input": {...}}，stop_reason 是 end_turn / tool_use / max_tokens。这样 Agent Loop 的处理逻辑不需要关心底层是哪家 API。

流式返回用 AsyncThrowingStream<SSEEvent, Error>，SSEEvent 是枚举：

public enum SSEEvent: @unchecked Sendable {
    case messageStart(message: [String: Any])
    case contentBlockStart(index: Int, contentBlock: [String: Any])
    case contentBlockDelta(index: Int, delta: [String: Any])
    case contentBlockStop(index: Int)
    case messageDelta(delta: [String: Any], usage: [String: Any])
    case messageStop
    case ping
    case error(data: [String: Any])
}

7 种事件类型，覆盖了 Anthropic Messages API 流式响应的全部事件。OpenAI 兼容层的流式输出会被转换成同样的 SSEEvent 序列。

二、AnthropicClient——原生 Claude API

AnthropicClient 是 LLMClient 的 Anthropic 原生实现，用 actor 保证并发安全：

public actor AnthropicClient: LLMClient {
    private let apiKey: String
    private let baseURL: URL      // 默认 https://api.anthropic.com
    private let urlSession: URLSession

    public init(apiKey: String, baseURL: String? = nil, urlSession: URLSession? = nil) {
        self.apiKey = apiKey
        self.baseURL = URL(string: baseURL ?? "https://api.anthropic.com")!
        self.urlSession = urlSession ?? URLSession.shared
    }
}

请求就是 POST 到 /v1/messages，header 里放 x-api-key 和 anthropic-version：

private nonisolated func buildRequest(body: [String: Any]) throws -> URLRequest {
    var request = URLRequest(url: URL(string: baseURL.absoluteString + "/v1/messages")!)
    request.httpMethod = "POST"
    request.timeoutInterval = 300
    request.setValue(apiKey, forHTTPHeaderField: "x-api-key")
    request.setValue("2023-06-01", forHTTPHeaderField: "anthropic-version")
    request.setValue("application/json", forHTTPHeaderField: "content-type")
    request.httpBody = try JSONSerialization.data(withJSONObject: body, options: [])
    return request
}

因为用的是 Anthropic 原生 API，所以 sendMessage 的请求体和响应体不需要格式转换——请求参数直接拼成字典发出去，响应直接解析成字典返回。流式模式也是直接解析 Anthropic 的 SSE 文本。

安全方面有个细节：所有错误信息都会把 API Key 替换成 ***，防止 key 泄露到日志里：

let safeMessage = errorMessage.replacingOccurrences(of: apiKey, with: "***")

AnthropicClient 直接支持 Extended Thinking。Agent 在配置了 ThinkingConfig 时，会把 thinking 参数传进来：

if let thinking {
    body["thinking"] = thinking
}

这个参数在 Anthropic API 里控制 Claude 是否进行深度思考以及思考的 token 预算。

三、OpenAI 兼容层——适配 GLM/Ollama/OpenRouter 等

OpenAIClient 是重头戏。它要做的事情是：接受 Anthropic 格式的参数，转换成 OpenAI Chat Completion API 格式发出去，再把 OpenAI 格式的响应转换回 Anthropic 格式。Agent 内部完全不知道底层是 OpenAI 兼容 API。

public actor OpenAIClient: LLMClient {
    private let apiKey: String
    private let baseURL: URL      // 默认 https://api.openai.com/v1

    public init(apiKey: String, baseURL: String? = nil, urlSession: URLSession? = nil) {
        self.apiKey = apiKey
        self.baseURL = URL(string: baseURL ?? "https://api.openai.com/v1")!
        self.urlSession = urlSession ?? URLSession.shared
    }
}

请求发到 /chat/completions，用 Bearer token 认证——这是 OpenAI 兼容 API 的标准做法。只要提供商支持 /v1/chat/completions 端点，就能用这个 Client 连接。

消息格式转换

Anthropic 和 OpenAI 的消息格式有几个关键差异，转换时都要处理：

1. System 消息的位置

Anthropic 把 system prompt 作为顶层参数传，OpenAI 把它作为第一条 role: "system" 消息：

if let system {
    result.append(["role": "system", "content": system])
}

2. Tool Result 的表示方式

Anthropic 把多个 tool_result 打包在一个 role: "user" 消息的 content 数组里，OpenAI 要求每个 tool result 是一条独立的 role: "tool" 消息：

let toolResults = blocks.filter { $0["type"] as? String == "tool_result" }
if !toolResults.isEmpty {
    return toolResults.map { block in
        [
            "role": "tool",
            "tool_call_id": block["tool_use_id"] as? String ?? "",
            "content": block["content"] ?? "",
        ]
    }
}

3. Tool Use 的表示方式

Anthropic 在 content 数组里用 type: "tool_use" 块，OpenAI 用 tool_calls 数组放在 message 顶层：

result["tool_calls"] = toolUseBlocks.enumerated().map { index, block in
    let inputDict = block["input"] as? [String: Any] ?? [:]
    let arguments = (try? JSONSerialization.data(withJSONObject: inputDict, options: []))
        .flatMap { String(data: $0, encoding: .utf8) } ?? "{}"
    return [
        "id": block["id"] as? String ?? "call_\(index)",
        "type": "function",
        "function": [
            "name": block["name"] as? String ?? "",
            "arguments": arguments,  // OpenAI 要求 JSON 字符串，不是字典
        ],
    ]
}

注意 OpenAI 的 arguments 必须是 JSON 字符串而不是字典对象，这里做了序列化。

响应格式转换

OpenAI 的响应结构（choices[0].message）要转成 Anthropic 格式：

// stop_reason 映射
private static func mapStopReason(_ finishReason: String) -> String {
    switch finishReason {
    case "stop": return "end_turn"
    case "tool_calls": return "tool_use"
    case "length": return "max_tokens"
    default: return finishReason
    }
}

// usage 映射
usage = [
    "input_tokens": openAIUsage["prompt_tokens"] as? Int ?? 0,
    "output_tokens": openAIUsage["completion_tokens"] as? Int ?? 0,
]

流式转换

流式的转换更复杂。OpenAI 的流式格式（data: {"choices":[{"delta":{...}}]}）要逐块转成 Anthropic 的 SSEEvent 序列：

第一个 chunk → messageStart
文本 delta → contentBlockDelta(type: "text_delta")
tool call 开始 → contentBlockStart(type: "tool_use")，参数 delta → contentBlockDelta(type: "input_json_delta")
结束 → contentBlockStop + messageDelta + messageStop

转换函数要跟踪当前有多少个 content block、文本块是否关闭、哪些 tool call 块还在打开状态，才能正确生成 index。代码里还加了一个安全检查——确保 messageStop 一定会被发出，即使原始流没有正常结束。

使用示例

连接不同的 OpenAI 兼容提供商只需要改 baseURL 和 model：

// DeepSeek
let agent = createAgent(options: AgentOptions(
    apiKey: "sk-...",
    model: "deepseek-chat",
    baseURL: "https://api.deepseek.com/v1",
    provider: .openai
))

// Ollama 本地
let localAgent = createAgent(options: AgentOptions(
    apiKey: "ollama",           // Ollama 不需要 key，随便填
    model: "qwen3:8b",
    baseURL: "http://localhost:11434/v1",
    provider: .openai
))

// GLM
let glmAgent = createAgent(options: AgentOptions(
    apiKey: "xxx.glm-xxx",
    model: "glm-4-plus",
    baseURL: "https://open.bigmodel.cn/api/paas/v4",
    provider: .openai
))

四、运行时模型切换

SDK 支持在运行时动态切换模型，不需要重新创建 Agent：

let agent = createAgent(options: AgentOptions(
    apiKey: apiKey,
    model: "claude-sonnet-4-6",
    fallbackModel: "claude-haiku-4-5"  // 主模型挂了用这个
))

// 先用 sonnet 跑一个简单问题
let result1 = await agent.prompt("What is 2 + 3?")
print(result1.costBreakdown)
// [CostBreakdownEntry(model: "claude-sonnet-4-6", inputTokens: 45, outputTokens: 3, costUsd: 0.000180)]

// 切换到 opus 跑推理密集型问题
try agent.switchModel("claude-opus-4-6")
let result2 = await agent.prompt("Explain the difference between structs and classes in Swift.")
print(result2.costBreakdown)
// [CostBreakdownEntry(model: "claude-opus-4-6", inputTokens: 52, outputTokens: 156, costUsd: 0.011970)]

switchModel() 的实现：

public func switchModel(_ model: String) throws {
    let trimmed = model.trimmingCharacters(in: .whitespacesAndNewlines)
    guard !trimmed.isEmpty else {
        throw SDKError.invalidConfiguration("Model name cannot be empty")
    }
    let oldModel = self.model
    self.model = trimmed
    self.options.model = trimmed
    Logger.shared.info("Agent", "model_switch", data: ["from": oldModel, "to": trimmed])
}

不做白名单校验——传什么模型名就用什么，API 层面不支持的模型会在请求时报错。这样设计是因为 OpenAI 兼容提供商的模型名无法穷举。

fallbackModel 是在 AgentOptions 里配置的备用模型。主模型彻底失败（重试耗尽）后，SDK 会自动用 fallback model 重试一次：

if let fallbackModel = self.options.fallbackModel, fallbackModel != self.model {
    let fallbackResponse = try await retryClient.sendMessage(
        model: fallbackModel,
        messages: retryMessages, ...
    )
    // 临时切到 fallback model 跑 cost tracking
    let originalModel = self.model
    self.model = fallbackModel
    // ... 处理响应
}

按模型分别计费

CostBreakdownEntry 按模型名分组记录每次查询的费用：

public struct CostBreakdownEntry: Sendable, Equatable {
    public let model: String
    public let inputTokens: Int
    public let outputTokens: Int
    public let costUsd: Double
}

一次查询里如果中途切了模型（或触发了 fallback），QueryResult.costBreakdown 会包含多个条目，每个模型的花费分开算。费用根据内置的价格表计算：

public nonisolated(unsafe) var MODEL_PRICING: [String: ModelPricing] = [
    "claude-opus-4-6":   ModelPricing(input: 15.0 / 1_000_000, output: 75.0 / 1_000_000),
    "claude-sonnet-4-6": ModelPricing(input: 3.0 / 1_000_000, output: 15.0 / 1_000_000),
    "claude-haiku-4-5":  ModelPricing(input: 0.8 / 1_000_000, output: 4.0 / 1_000_000),
    // ...
]

自定义模型可以通过 registerModel(_:pricing:) 注册价格：

registerModel("glm-4-plus", pricing: ModelPricing(
    input: 0.1 / 1_000_000, output: 0.1 / 1_000_000
))

五、Thinking 与 Effort 配置

ThinkingConfig

SDK 用 ThinkingConfig 枚举控制 LLM 的深度思考能力：

public enum ThinkingConfig: Sendable, Equatable {
    case adaptive                  // 模型自己决定要不要思考
    case enabled(budgetTokens: Int) // 指定思考的 token 预算
    case disabled                  // 关闭深度思考
}

三种模式各有用途：

adaptive：让模型自己判断——简单问题不思考，复杂问题自动思考。日常使用最方便。
enabled(budgetTokens:)：明确控制思考预算。比如你想要深度分析，给 10000 个 thinking token。
disabled：完全关闭思考，追求最快速度。

EffortLevel

EffortLevel 是更高层级的抽象，映射到具体的 thinking token 预算：

public enum EffortLevel: String, Sendable, CaseIterable {
    case low    // 1024 tokens
    case medium // 5120 tokens
    case high   // 10240 tokens
    case max    // 32768 tokens

    public var budgetTokens: Int {
        switch self {
        case .low: return 1024
        case .medium: return 5120
        case .high: return 10240
        case .max: return 32768
        }
    }
}

在 AgentOptions 里设置：

let agent = createAgent(options: AgentOptions(
    apiKey: apiKey,
    model: "claude-sonnet-4-6",
    effort: .high  // 10240 thinking tokens
))

运行时动态调节

setMaxThinkingTokens() 可以在查询之间调整思考预算：

// 普通问题，少给点思考 token
try agent.setMaxThinkingTokens(2048)
let r1 = await agent.prompt("Summarize this file.")

// 遇到复杂推理问题，加大预算
try agent.setMaxThinkingTokens(16000)
let r2 = await agent.prompt("Design a concurrent data structure for...")

// 关闭思考
try agent.setMaxThinkingTokens(nil)

传正整数就启用思考并设预算，传 nil 就关闭。传 0 或负数会抛 SDKError.invalidConfiguration。

ModelInfo 描述了每个模型支持哪些能力：

public struct ModelInfo: Sendable, Equatable {
    public let value: String
    public let displayName: String
    public let description: String
    public let supportsEffort: Bool
    public let supportedEffortLevels: [EffortLevel]?
    public let supportsAdaptiveThinking: Bool?
    public let supportsFastMode: Bool?
}

这样 UI 层可以根据模型能力动态展示可选项。

六、Skills 系统

Skills 是 SDK 里一种特殊的扩展机制——本质上是”带工具限制的 prompt 模板”。一个 Skill 定义了一组 prompt 指令、允许使用的工具子集、可选的模型覆盖。

Skill 结构

public struct Skill: Sendable {
    public let name: String
    public let description: String
    public let aliases: [String]              // 别名，如 ["ci"] 代表 commit
    public let userInvocable: Bool            // 用户能否通过 /command 调用
    public let toolRestrictions: [ToolRestriction]?  // 限制可用工具，nil = 全部可用
    public let modelOverride: String?         // 执行时覆盖模型
    public let isAvailable: @Sendable () -> Bool     // 运行时可用性检查
    public let promptTemplate: String         // prompt 模板内容
    public let whenToUse: String?             // 告诉 LLM 什么时候该用这个 skill
    public let argumentHint: String?          // 参数提示，如 "[message]"
    public let baseDir: String?               // skill 目录的绝对路径
    public let supportingFiles: [String]      // 支撑文件（引用、脚本等）
}

5 个内置 Skill

SDK 预定义了 5 个常用 Skill，通过 BuiltInSkills 命名空间访问：

Skill	别名	允许的工具	功能
`commit`	`ci`	bash, read, glob, grep	分析 git diff，生成 commit message
`review`	`review-pr`, `cr`	bash, read, glob, grep	从 5 个维度审查代码变更
`simplify`	—	bash, read, grep, glob	审查代码的复用、质量、效率
`debug`	`investigate`, `diagnose`	read, grep, glob, bash	分析错误，定位根因
`test`	`run-tests`	bash, read, write, glob, grep	生成测试用例并执行

每个 Skill 都限制了工具范围。比如 commit 只允许 bash、read、glob、grep——不需要写文件。debug 也是只读的（read、grep、glob、bash），只做诊断不做修改。test 是唯一允许 write 的内置 Skill，因为要创建测试文件。

test Skill 还有一个运行时可用性检查：

isAvailable: {
    let cwd = FileManager.default.currentDirectoryPath
    let testIndicators = [
        "Package.swift", "pytest.ini", "jest.config",
        "vitest.config", "Cargo.toml", "go.mod",
    ]
    for indicator in testIndicators {
        if FileManager.default.fileExists(atPath: cwd + "/" + indicator) {
            return true
        }
    }
    return false
}

只有检测到测试框架配置文件时，test Skill 才对用户可见。

SkillRegistry

SkillRegistry 是线程安全的 skill 管理器，用 DispatchQueue 保护并发访问：

public final class SkillRegistry: @unchecked Sendable {
    private var skills: [String: Skill] = [:]
    private var orderedNames: [String] = []
    private var aliases: [String: String] = [:]
    private let queue = DispatchQueue(label: "com.openagentsdk.skillregistry")

    public func register(_ skill: Skill) { ... }
    public func find(_ name: String) -> Skill? { ... }   // 按名称或别名查找
    public var allSkills: [Skill] { ... }
    public var userInvocableSkills: [Skill] { ... }
}

SkillLoader：文件系统发现

Skills 不需要全部代码注册。SkillLoader 可以从文件系统自动发现 skill——只要一个目录里包含 SKILL.md 文件，就会被识别为一个 skill 包。

扫描目录按优先级从低到高：

~/.config/agents/skills      （最低优先级）
~/.agents/skills
~/.claude/skills
$PWD/.agents/skills
$PWD/.claude/skills           （最高优先级）

同名 skill 后发现的覆盖先发现的（last-wins）。

SKILL.md 用 YAML frontmatter 定义元数据：

---
name: polyv-live-cli
description: 管理保利威直播服务
aliases: live, plv
allowed-tools: Bash, Read, Write, Glob
when-to-use: user asks about live streaming management
argument-hint: [action] [options]
---

# polyv-live-cli Skill

你是保利威直播服务的管理助手...

frontmatter 里的 allowed-tools 会被解析成 ToolRestriction 数组，限制这个 skill 执行时只能用指定的工具。

SkillLoader 采用”渐进式加载”策略：只加载 SKILL.md 的 Markdown body 作为 prompt 模板，支撑文件（references、scripts、templates）只记录路径不加载内容。Agent 需要时通过 Read/Bash 工具按需读取。

let registry = SkillRegistry()
registry.register(BuiltInSkills.commit)
registry.register(BuiltInSkills.review)
// 从文件系统发现自定义 skills
let count = registry.registerDiscoveredSkills()
// 或指定目录
registry.registerDiscoveredSkills(from: ["/opt/custom-skills"])
// 或只注册白名单里的
registry.registerDiscoveredSkills(skillNames: ["polyv-live-cli"])

ToolRestriction

ToolRestriction 枚举定义了可以被限制的工具：

public enum ToolRestriction: String, Sendable, CaseIterable {
    case bash, read, write, edit, glob, grep
    case webFetch, webSearch, askUser, toolSearch
    case agent, sendMessage
    case taskCreate, taskList, taskUpdate, taskGet, taskStop, taskOutput
    case teamCreate, teamDelete
    case notebookEdit, skill
}

当一个 Skill 设了 toolRestrictions: [.bash, .read, .glob]，执行时 Agent 只能用这三个工具，其他工具调用会被拦截。

在 Agent 里使用 Skills

要让 Agent 能用 Skills，需要把 SkillTool 加到工具列表里：

var tools = getAllBaseTools(tier: .core)
tools.append(createSkillTool(registry: registry))

let agent = createAgent(options: AgentOptions(
    apiKey: apiKey,
    model: "claude-sonnet-4-6",
    permissionMode: .bypassPermissions,
    tools: tools
))

// Agent 会根据 system prompt 里的 skill 列表自动发现并调用
let result = await agent.prompt("Use the commit skill to analyze current changes")

SkillRegistry.formatSkillsForPrompt() 会生成一段 skill 列表注入到 system prompt 里，包含每个 skill 的名称、描述和触发条件。LLM 看到这个列表后就知道该在什么场景下调用哪个 skill。

七、其他运行时控制

预算控制

maxBudgetUsd 设置查询的费用上限：

let agent = createAgent(options: AgentOptions(
    apiKey: apiKey,
    model: "claude-sonnet-4-6",
    maxBudgetUsd: 0.05  // 最多花 5 美分
))

每个 turn 结束后检查累计费用：

if let budget = options.maxBudgetUsd, totalCostUsd > budget {
    status = .errorMaxBudgetUsd
    break
}

超出预算时立即退出循环。已产生的文本和 token 统计仍然保留在 QueryResult 里——你拿到的是部分结果，不是空白的。

查询中断

两种方式中断正在进行的查询：

// 方式 1：调用 interrupt()
agent.interrupt()

// 方式 2：取消 Task
let task = Task {
    await agent.prompt("Long running query...")
}
// 稍后
task.cancel()

interrupt() 内部设置了 _interrupted 标志并取消 stream task。Agent Loop 在多个检查点检查这个标志（循环入口、只读/变更工具之间、SSE 事件循环内部、工具执行前后），检测到后立即退出。

动态权限切换

运行时可以切换权限模式和工具授权回调：

// 切换权限模式
agent.setPermissionMode(.askForPermission)

// 设置自定义授权回调（优先级高于 permissionMode）
agent.setCanUseTool { toolName, input in
    if toolName == "Bash" {
        return .deny("Bash is disabled")
    }
    return .allow
}

// 恢复到 permissionMode 控制
agent.setCanUseTool(nil)

setCanUseTool 的回调优先于 permissionMode。调 setPermissionMode() 会清空之前设的回调。

环境变量配置

SDK 支持通过环境变量配置，优先级是：代码设置 > 环境变量 > 默认值。

环境变量	对应字段	默认值
`CODEANY_API_KEY`	`apiKey`	`nil`
`CODEANY_MODEL`	`model`	`claude-sonnet-4-6`
`CODEANY_BASE_URL`	`baseURL`	`nil`（用提供商默认）

用 SDKConfiguration.resolved() 合并：

// 代码设置的值优先，没设的从环境变量读
let config = SDKConfiguration.resolved(overrides: SDKConfiguration(
    apiKey: "sk-...",           // 优先于 CODEANY_API_KEY
    model: "claude-sonnet-4-6"  // 优先于 CODEANY_MODEL
))

// 只用环境变量
let envConfig = SDKConfiguration.fromEnvironment()

重试机制

所有 LLM 请求经过 withRetry 包装：

public struct RetryConfig: Sendable {
    public let maxRetries: Int          // 最多重试次数，默认 3
    public let baseDelayMs: Int         // 基础延迟，默认 2000ms
    public let maxDelayMs: Int          // 最大延迟，默认 30000ms
    public let retryableStatusCodes: Set<Int>  // 默认 [429, 500, 502, 503, 529]
}

指数退避 + 25% 随机抖动，避免惊群效应。只有 SDKError.apiError 且状态码在可重试集合里才会重试，其他错误直接抛出。

let delay = config.baseDelayMs * (1 << attempt)
let jitterMs = Int(Double(delay) * 0.25 * (Double.random(in: -1...1)))
let totalMs = max(0, min(delay + jitterMs, config.maxDelayMs))

系列回顾

六篇文章写完了，覆盖了 Open Agent SDK (Swift) 的完整架构：

第 0 篇：项目概述——SDK 做什么、整体架构、怎么用
第 1 篇：Agent Loop 内核——从 prompt 到多轮对话的完整循环
第 2 篇：34 个内置工具——ToolProtocol 协议、三层架构、自定义扩展
第 3 篇：MCP 集成——外部工具服务器的连接、发现和通信
第 4 篇：多 Agent 协作——Team/Task 模型、Agent 间通信
第 5 篇：会话持久化与安全——Session 存储、权限控制、Hook 系统
第 6 篇（本文）：多 LLM 提供商与运行时控制——LLMClient 协议、OpenAI 适配层、模型切换、Thinking/Effort、Skills 系统

从 Agent Loop 这个核心出发，工具系统是循环里的”执行”环节，MCP 是外部工具扩展，多 Agent 是协作模式，会话是状态持久化，安全和 Hook 是管控机制，而本文讲的多提供商和运行时控制是灵活性的保障——让同一个 Agent 能根据场景选择最合适的模型和控制策略。

系列文章：

第 0 篇：Open Agent SDK (Swift)：用原生 Swift 并发构建 AI Agent 应用
第 1 篇：Agent Loop 内核：从 prompt 到多轮对话的完整运转机制
第 2 篇：34 个工具的背后：工具协议、三层架构与自定义扩展
第 3 篇：MCP 集成实战：让 Agent 连接万物
第 4 篇：多 Agent 协作：子代理、团队与任务编排
第 5 篇：会话持久化与安全防线
第 6 篇：多 LLM 提供商与运行时控制（本文）

GitHub：terryso/open-agent-sdk-swift

深入 Open Agent SDK（五）：会话持久化与安全防线

Wed, 22 Apr 2026 12:00:00 +0000

本文是「深入 Open Agent SDK (Swift)」系列第五篇。系列目录见这里。

Agent 不只是一次性问答工具。真正有用的 Agent 要做到三件事：记住上下文（上次聊到哪了）、控制权限（哪些操作能做）、审计行为（谁在什么时候干了什么）。Open Agent SDK 用四个子系统来覆盖这些需求——SessionStore、PermissionPolicy、SandboxSettings、HookRegistry。

这篇文章分析这四个子系统的实现细节，看它们各自怎么工作，以及怎么组合起来构建一个安全的 Agent。

一、会话持久化：SessionStore

Agent Loop 每次运行会产生一组 messages 数组。如果不保存，进程退出就没了。SessionStore 负责把这些对话历史持久化到磁盘，下次启动时恢复。

SessionStore 是什么

SessionStore 是一个 actor，所有方法都需要 await 调用。默认把会话存在 ~/.open-agent-sdk/sessions/ 目录下，每个 session 一个子目录，里面放一个 transcript.json。

let sessionStore = SessionStore()  // 默认路径
let sessionStore = SessionStore(sessionsDir: "/custom/path")  // 自定义路径

五个核心操作

SessionStore 提供五个核心方法，覆盖会话的完整生命周期。

save — 保存会话。把 messages 数组和元数据序列化成 JSON 写入磁盘：

try await sessionStore.save(
    sessionId: "my-session",
    messages: messages,
    metadata: PartialSessionMetadata(
        cwd: "/project",
        model: "claude-sonnet-4-6",
        summary: "代码分析会话",
        tag: "analysis",
        firstPrompt: "分析项目结构"
    )
)

存储结构长这样：

~/.open-agent-sdk/sessions/
  my-session/
    transcript.json    // { "metadata": {...}, "messages": [...] }

文件权限是 0600，目录权限是 0700——只有当前用户能读写。每次 save 会保留第一次创建时的 createdAt 时间戳，只更新 updatedAt。

load — 加载会话。从磁盘读取 transcript.json，反序列化为 SessionData：

if let data = try await sessionStore.load(sessionId: "my-session") {
    print("Messages: \(data.metadata.messageCount)")
    print("Model: \(data.metadata.model)")
    // data.messages 是 [[String: Any]] 数组
}

load 支持分页参数 limit 和 offset，不需要加载全部消息时可以只取尾部：

// 只加载最近 50 条消息
let recent = try await sessionStore.load(sessionId: "my-session", limit: 50, offset: nil)

list — 列出所有会话，按 updatedAt 降序排列（最近的在前）：

let sessions = try await sessionStore.list(limit: 10)
for session in sessions {
    print("\(session.id) — \(session.summary ?? "(无标题)") [\(session.messageCount) 条消息]")
}

SessionMetadata 包含 id、cwd、model、createdAt、updatedAt、messageCount，以及可选的 summary、tag、firstPrompt、gitBranch、fileSize。

fork — 分叉会话。从已有会话复制消息到新 session，可以指定截断点：

// 完整复制
let newId = try await sessionStore.fork(sourceSessionId: "my-session")

// 只复制前 10 条消息
let truncatedId = try await sessionStore.fork(
    sourceSessionId: "my-session",
    upToMessageIndex: 10
)

// 指定新 session ID
let customId = try await sessionStore.fork(
    sourceSessionId: "my-session",
    newSessionId: "forked-session"
)

delete — 删除整个会话目录：

let deleted = try await sessionStore.delete(sessionId: "my-session")

此外还有 rename（改标题）和 tag（打标签）两个辅助方法。

会话恢复的三种模式

把 SessionStore 注入 Agent 后，SDK 提供三种恢复策略：

1. 指定 sessionId 恢复

最直接的方式：给定一个 session ID，Agent 启动时从 SessionStore 加载历史消息，追加到 messages 数组前面：

let agent = createAgent(options: AgentOptions(
    apiKey: apiKey,
    model: "claude-sonnet-4-6",
    sessionStore: sessionStore,
    sessionId: "my-session"      // 指定恢复哪个 session
))

2. continueRecentSession — 自动接续最近的会话

不知道 session ID 时，让 SDK 自动找最近的一个：

let agent = createAgent(options: AgentOptions(
    apiKey: apiKey,
    model: "claude-sonnet-4-6",
    sessionStore: sessionStore,
    continueRecentSession: true   // 自动加载最近的 session
))

内部实现是调 sessionStore.list() 取第一个（已按 updatedAt 降序排列），把它的 ID 作为恢复目标。

3. forkSession + resumeSessionAt — 分叉并截断

在已有会话的基础上分叉一个新分支，还可以截断到指定消息：

let agent = createAgent(options: AgentOptions(
    apiKey: apiKey,
    model: "claude-sonnet-4-6",
    sessionStore: sessionStore,
    sessionId: "my-session",
    forkSession: true,                     // 复制到新 session
    resumeSessionAt: "msg-uuid-123"        // 截断到这条消息
))

SDK 内部的解析顺序是：先 continueRecentSession 确定 session ID，再 forkSession 创建分叉，再 resumeSessionAt 截断历史。这三个选项可以独立使用也可以组合。

SessionStore 的安全细节

SessionStore 在 session ID 校验上做了路径遍历防护：

private func validateSessionId(_ sessionId: String) throws {
    guard !sessionId.isEmpty else {
        throw SDKError.sessionError(message: "Session ID must not be empty")
    }
    let forbidden = ["/", "\\", ".."]
    for component in forbidden {
        if sessionId.contains(component) {
            throw SDKError.sessionError(message: "Session ID contains invalid character: '\(component)'")
        }
    }
}

session ID 里不能包含 /、\、..——防止攻击者通过构造 ID 来读写预期之外的路径。

二、权限控制：PermissionPolicy

会话持久化解决了”记住”的问题，权限控制解决的是”能做什么”的问题。

六种 PermissionMode

SDK 定义了 6 种权限模式：

模式	行为
`default`	每次工具执行前询问用户
`plan`	只读工具直接执行，写操作需要确认
`auto`	自动执行所有工具，危险操作除外
`acceptEdits`	文件编辑自动执行，其他操作需要确认
`dontAsk`	不询问用户，根据上下文自动判断
`bypassPermissions`	跳过所有权限检查

let agent = createAgent(options: AgentOptions(
    apiKey: apiKey,
    model: "claude-sonnet-4-6",
    permissionMode: .plan  // 只读工具直接跑，写操作要确认
))

canUseTool 回调：比 PermissionMode 更细粒度

permissionMode 是全局开关，粒度比较粗。如果你需要按工具名称或工具属性做精细控制，用 canUseTool 回调：

let agent = createAgent(options: AgentOptions(
    apiKey: apiKey,
    model: "claude-sonnet-4-6",
    permissionMode: .bypassPermissions,
    canUseTool: { tool, input, context in
        if tool.name == "Bash" {
            return CanUseToolResult.deny("Bash is not allowed")
        }
        return nil  // nil 表示"我没意见，交给 permissionMode 决定"
    }
))

canUseTool 返回 CanUseToolResult?。返回 nil 表示该回调没有意见，交给下一个检查环节；返回非 nil 结果时，SDK 用回调的决定，不再看 permissionMode。

CanUseToolResult 有三个工厂方法：

CanUseToolResult.allow()                              // 允许
CanUseToolResult.deny("原因")                          // 拒绝
CanUseToolResult.allowWithInput(modifiedInput)         // 允许但修改输入参数

allowWithInput 比较少见但很实用——你可以在权限检查时修改工具的输入参数。比如把文件写入路径重定向到安全目录。

策略模式：可组合的权限规则

直接写闭包虽然灵活，但不方便复用。SDK 提供了 PermissionPolicy 协议，把权限判断封装成可组合的策略：

public protocol PermissionPolicy: Sendable {
    func evaluate(
        tool: ToolProtocol,
        input: Any,
        context: ToolContext
    ) async -> CanUseToolResult?
}

SDK 内置了四个策略：

ToolNameAllowlistPolicy — 白名单，只允许指定的工具：

let policy = ToolNameAllowlistPolicy(allowedToolNames: ["Read", "Glob", "Grep"])
// Write、Edit、Bash 等工具全部被拒绝

ToolNameDenylistPolicy — 黑名单，拒绝指定的工具：

let policy = ToolNameDenylistPolicy(deniedToolNames: ["Bash", "Write"])
// 其他工具正常执行

ReadOnlyPolicy — 只允许只读工具（isReadOnly == true）：

let policy = ReadOnlyPolicy()
// Read、Glob、Grep、WebSearch 等只读工具允许
// Write、Edit、Bash 等变更工具被拒绝

CompositePolicy — 组合多个策略，按顺序评估：

let policy = CompositePolicy(policies: [
    ToolNameDenylistPolicy(deniedToolNames: ["Bash"]),
    ReadOnlyPolicy()
])
// 先检查黑名单（Bash 被拒绝），再检查只读策略

CompositePolicy 的评估规则：

任何子策略返回 deny，整体 deny（短路）
子策略返回 nil（没意见），跳过
所有子策略都 allow 或没意见，整体 allow

用 canUseTool(policy:) 桥接函数把策略转成回调：

let policy = CompositePolicy(policies: [
    ToolNameDenylistPolicy(deniedToolNames: ["Bash"]),
    ReadOnlyPolicy()
])

let agent = createAgent(options: AgentOptions(
    apiKey: apiKey,
    model: "claude-sonnet-4-6",
    permissionMode: .bypassPermissions,
    canUseTool: canUseTool(policy: policy)
))

三、沙盒机制：SandboxSettings + SandboxChecker

权限控制管的是”这个工具能不能执行”，沙盒管的是”这个操作在不在允许范围内”。比如 Bash 工具通过了权限检查，但你还得确保它不会 rm -rf /。

SandboxSettings 的配置项

let sandbox = SandboxSettings(
    // 路径控制
    allowedReadPaths: ["/project/"],
    allowedWritePaths: ["/project/build/"],
    deniedPaths: ["/etc/", "/var/"],

    // 命令控制
    deniedCommands: ["rm", "sudo"],           // 黑名单
    // allowedCommands: ["git", "swift"],     // 白名单（和黑名单二选一）

    // 行为控制
    allowNestedSandbox: false,
    autoAllowBashIfSandboxed: false,          // 沙箱激活时自动批准 Bash
    allowUnsandboxedCommands: false,
    enableWeakerNestedSandbox: false,

    // 网络控制
    network: SandboxNetworkConfig(
        allowedDomains: ["api.example.com"],
        allowLocalBinding: false
    )
)

路径和命令各有两种模式：

路径：allowedReadPaths / allowedWritePaths 是白名单（空数组=全部允许），deniedPaths 是黑名单（优先级更高）
命令：allowedCommands 是白名单（设为非 nil 就只允许列出的命令），deniedCommands 是黑名单。allowedCommands 优先级高于 deniedCommands

SandboxChecker 的执行逻辑

SandboxChecker 是一个无状态的枚举类，提供 isPathAllowed、checkPath、isCommandAllowed、checkCommand 四个静态方法。isXxx 返回 Bool，checkXxx 不通过时抛出 SDKError.permissionDenied。

路径检查用前缀匹配加段边界保证：

// /project/ 匹配 /project/src/file.swift
// /project/ 不匹配 /project-backup/file.swift
SandboxChecker.isPathAllowed("/project/src/main.swift", for: .read, settings: sandbox)
// -> true

SandboxChecker.isPathAllowed("/project-backup/old.swift", for: .read, settings: sandbox)
// -> false（段边界不匹配）

实现关键在于 SandboxPathNormalizer——先把路径规范化（解析 ..、.、symlink），再做前缀比较时保证尾部有 / 来强制段边界。

// 路径遍历攻击会被 normalize 掉
let normalized = SandboxPathNormalizer.normalize("/project/src/../../etc/passwd")
// -> "/etc/passwd"，然后被 deniedPaths 拦截

命令检查分三个阶段：

Shell 元字符检测——识别 bash -c "cmd"、$(cmd)、`cmd` 等绕过模式
Basename 提取——从 /usr/bin/rm -rf /tmp 提取出 rm
白名单/黑名单匹配

// 黑名单里有 "rm"
SandboxChecker.isCommandAllowed("rm -rf /tmp", settings: blocklist)
// -> false

// 路径形式的命令也能识别
SandboxChecker.isCommandAllowed("/usr/bin/rm -rf /tmp", settings: blocklist)
// -> false（提取 basename 得到 "rm"）

// 反斜杠绕过
SandboxChecker.isCommandAllowed("\\rm -rf /tmp", settings: blocklist)
// -> false（去掉前导 \ 后得到 "rm"）

// 引号绕过
SandboxChecker.isCommandAllowed("\"rm\" -rf /tmp", settings: blocklist)
// -> false（去掉引号后得到 "rm"）

// 子 shell 绕过
SandboxChecker.isCommandAllowed("bash -c \"rm -rf /tmp\"", settings: blocklist)
// -> false（递归检查内部命令）

对于无法可靠解析的命令（比如多层嵌套的 bash -c "bash -c 'rm ...'"），默认拒绝。

命令参数中的文件路径也会被提取并检查——如果命令里出现了 deniedPaths 中的路径，命令也会被拒绝。

autoAllowBashIfSandboxed

这个选项是沙盒和权限系统的桥梁。当 autoAllowBashIfSandboxed = true 时，Bash 工具会跳过 canUseTool 权限回调检查，但仍然经过 SandboxChecker.checkCommand() 的命令过滤。

设计思路是：如果你已经配了完善的沙盒规则，Bash 命令能做什么已经被限制住了，不需要再弹一次权限确认。

四、Hook 系统：20+ 生命周期事件

前三个系统解决的是”能不能做”的问题，Hook 系统解决的是”做了之后要知道”和”做之前要干预”的问题。

20+ 个 HookEvent

SDK 定义了 24 个生命周期事件：

事件	触发时机
`preToolUse`	工具执行前
`postToolUse`	工具执行成功后
`postToolUseFailure`	工具执行失败后
`sessionStart`	Agent 会话开始
`sessionEnd`	Agent 会话结束
`stop`	Agent Loop 停止
`subagentStart`	子 Agent 启动
`subagentStop`	子 Agent 完成
`userPromptSubmit`	用户提交 prompt
`permissionRequest`	权限检查发生
`permissionDenied`	权限被拒绝
`taskCreated`	任务创建
`taskCompleted`	任务完成
`configChange`	配置变更
`cwdChanged`	工作目录变更
`fileChanged`	文件变更
`notification`	通知事件
`preCompact`	对话压缩前
`postCompact`	对话压缩后
`teammateIdle`	团队成员空闲
`setup`	Agent 初始化
`worktreeCreate`	工作树创建
`worktreeRemove`	工作树移除

函数 Hook vs Shell Hook

Hook 有两种实现方式：函数回调和 Shell 命令。

函数 Hook — Swift 闭包，适合进程内逻辑：

await registry.register(.preToolUse, definition: HookDefinition(
    handler: { input in
        // input 是 HookInput，包含 event、toolName、toolInput、sessionId 等
        return HookOutput(message: "拦截成功", block: true)
    }
))

Shell Hook — 外部命令，适合集成非 Swift 脚本：

await registry.register(.preToolUse, definition: HookDefinition(
    command: "python3 /path/to/check.py"  // HookInput 通过 stdin JSON 传入
))

Shell Hook 通过 ShellHookExecutor 执行：用 /bin/bash -c 启动进程，把 HookInput 序列化为 JSON 写入 stdin，从 stdout 读取 HookOutput JSON。Shell 命令的标准输出如果不是合法 JSON，会被包装成 HookOutput(message: stdout)。

Shell Hook 的环境变量里会注入 HOOK_EVENT、HOOK_TOOL_NAME、HOOK_SESSION_ID、HOOK_CWD，方便脚本直接用环境变量判断上下文。

HookRegistry 的注册与执行

HookRegistry 是一个 actor，内部维护 [HookEvent: [HookDefinition]] 映射：

let registry = HookRegistry()

// 注册函数 Hook
await registry.register(.preToolUse, definition: HookDefinition(
    handler: { input in
        return HookOutput(message: "Bash blocked", block: true)
    },
    matcher: "Bash"  // 只匹配 Bash 工具
))

// 注册 Shell Hook
await registry.register(.postToolUse, definition: HookDefinition(
    command: "/usr/bin/logger 'Tool executed'",
    timeout: 5000  // 5 秒超时
))

// 执行所有注册在某事件上的 Hook
let results = await registry.execute(.preToolUse, input: hookInput)
// results: [HookOutput]，包含所有匹配的 Hook 的返回值

matcher 过滤：每个 HookDefinition 可以设一个 matcher（正则表达式）。执行时先检查 input.toolName 是否匹配 matcher，不匹配就跳过这个 Hook。matcher 为 nil 时匹配所有工具。

超时处理：函数 Hook 用 withThrowingTaskGroup 实现超时——把实际执行和 Task.sleep 放在同一个 TaskGroup 里，谁先完成用谁。超时的 Hook 不影响其他 Hook 执行。Shell Hook 通过 DispatchQueue.asyncAfter 设置超时，到时间就 terminate 进程。

执行顺序：同一事件上的 Hook 按注册顺序串行执行。

HookOutput 的能力

HookOutput 可以做这些事：

HookOutput(
    message: "日志消息",                          // 附加信息
    block: true,                                  // 拦截操作
    notification: HookNotification(               // 发送通知
        title: "警告",
        body: "检测到危险操作",
        level: .warning
    ),
    permissionUpdate: PermissionUpdate(           // 动态修改权限
        tool: "Bash",
        behavior: .deny
    ),
    systemMessage: "请在沙箱内操作",               // 注入系统消息
    reason: "安全策略",                            // 拦截原因
    updatedInput: ["command": "echo safe"],       // 修改工具输入
    decision: .block                              // 显式 approve/block
)

其中 block: true 会阻止工具执行，返回一个错误结果给 LLM。permissionUpdate 可以在 Hook 运行时动态修改工具权限。updatedInput 可以替换工具的输入参数。

五、实战组合：构建一个安全的 Agent

四个子系统各有分工：

SessionStore — 记住对话历史
PermissionPolicy — 控制工具能不能执行
SandboxSettings — 限制操作范围
HookRegistry — 审计和拦截

下面用一个完整的例子展示怎么把它们组合起来：

import Foundation
import OpenAgentSDK

// 1. 创建 SessionStore
let sessionStore = SessionStore()

// 2. 创建 HookRegistry，注册审计和安全拦截
let hookRegistry = HookRegistry()

// 记录所有工具执行
await hookRegistry.register(.postToolUse, definition: HookDefinition(
    handler: { input in
        if let toolName = input.toolName {
            print("[审计] 工具 \(toolName) 执行完成")
        }
        return nil
    }
))

// 拦截 Bash 中的危险命令
await hookRegistry.register(.preToolUse, definition: HookDefinition(
    handler: { input in
        return HookOutput(
            message: "Bash 被安全策略拦截",
            block: true,
            decision: .block
        )
    },
    matcher: "Bash"
))

// 记录权限拒绝事件
await hookRegistry.register(.permissionDenied, definition: HookDefinition(
    handler: { input in
        print("[安全告警] 权限被拒绝: \(input.error ?? "unknown")")
        return nil
    }
))

// 会话生命周期追踪
await hookRegistry.register(.sessionStart, definition: HookDefinition(
    handler: { _ in print("[会话] 开始"); return nil }
))
await hookRegistry.register(.sessionEnd, definition: HookDefinition(
    handler: { _ in print("[会话] 结束"); return nil }
))

// 3. 配置沙盒：限制路径和命令
let sandbox = SandboxSettings(
    allowedReadPaths: ["/project/"],
    allowedWritePaths: ["/project/src/", "/project/tests/"],
    deniedPaths: ["/etc/", "/var/", "/tmp/"],
    deniedCommands: ["rm", "sudo", "chmod", "chown"],
    autoAllowBashIfSandboxed: false,
    allowNestedSandbox: false
)

// 4. 配置权限策略：只读 + 排除 Bash
let policy = CompositePolicy(policies: [
    ToolNameDenylistPolicy(deniedToolNames: ["Bash"]),
    ReadOnlyPolicy()
])

// 5. 创建 Agent，注入所有组件
let agent = createAgent(options: AgentOptions(
    apiKey: "sk-...",
    model: "claude-sonnet-4-6",
    systemPrompt: "你是一个代码分析助手。只能读取文件，不能修改。",
    maxTurns: 10,
    permissionMode: .bypassPermissions,
    canUseTool: canUseTool(policy: policy),
    sessionStore: sessionStore,
    sessionId: "analysis-session",
    hookRegistry: hookRegistry,
    sandbox: sandbox
))

// 6. 执行查询
let result = await agent.prompt("分析项目中的 Swift 源文件结构")
print(result.text)

// 7. 后续恢复会话
let resumedAgent = createAgent(options: AgentOptions(
    apiKey: "sk-...",
    model: "claude-sonnet-4-6",
    permissionMode: .bypassPermissions,
    canUseTool: canUseTool(policy: policy),
    sessionStore: sessionStore,
    sessionId: "analysis-session",  // 同一个 session ID，自动恢复历史
    hookRegistry: hookRegistry,
    sandbox: sandbox
))

let continued = await resumedAgent.prompt("继续分析测试文件")
print(continued.text)

这个 Agent 的安全特性：

权限层：CompositePolicy 确保只有只读工具能执行，Bash 被黑名单排除
沙盒层：即使工具通过了权限检查，也受路径限制——只能读 /project/ 下的文件，不能碰 /etc/、/var/
Hook 层：所有工具执行被记录（审计），Bash 调用被 preToolUse Hook 二次拦截
会话层：对话自动保存和恢复，重启后能继续之前的工作

多层防御的好处是：即使某一层的配置有疏漏，其他层还能兜底。比如你误把 Bash 加进了白名单，Hook 的 matcher 还能拦截；即使 Hook 没拦住，沙盒的命令过滤还能挡。

小结

SessionStore、PermissionPolicy、SandboxSettings、HookRegistry 四个系统各管一件事，但组合起来就是一套完整的安全框架：

SessionStore 的 actor 隔离和 session ID 校验保证了存储安全
PermissionPolicy 的策略组合提供了灵活的权限管理
SandboxChecker 的路径规范化和段边界匹配防止目录穿越
HookRegistry 的 matcher 过滤和超时机制确保了 Hook 系统的可靠性

下一篇看 SDK 的 多 LLM 提供商：怎么同时支持 Anthropic、OpenAI 和其他 LLM，Provider 协议的设计，以及运行时切换模型的机制。

系列文章：

第 0 篇：Open Agent SDK (Swift)：用原生 Swift 并发构建 AI Agent 应用
第 1 篇：Agent Loop 内核：从 prompt 到多轮对话的完整运转机制
第 2 篇：34 个工具的背后：工具协议、三层架构与自定义扩展
第 3 篇：MCP 集成实战：让 Agent 连接万物
第 4 篇：多 Agent 协作：子代理、团队与任务编排
第 5 篇：会话持久化与安全防线（本文）
第 6 篇：多 LLM 提供商与运行时控制

GitHub：terryso/open-agent-sdk-swift

深入 Open Agent SDK（四）：多 Agent 协作——子代理、团队与任务编排

Wed, 22 Apr 2026 11:00:00 +0000

本文是「深入 Open Agent SDK (Swift)」系列第四篇。系列目录见这里。

单个 Agent 再强，也只是一个执行者。真实的开发任务往往是多步骤、多角色的：先有人探索代码库，有人设计方案，再有人写代码、跑测试。一个 Agent 单干，上下文容易膨胀，效率也上不去。

Open Agent SDK 从三个层面解决这个问题：

子 Agent – 主 Agent 在运行过程中动态生成子 Agent，把专门的任务委派出去
Task 系统 – 用任务追踪多步骤工作的进度和结果
Team + 消息传递 – 多个 Agent 组成团队，通过邮箱系统互相通信

这篇文章逐一分析这三个层面的实现，最后看它们怎么组合起来做任务编排。

一、子 Agent：SubAgentSpawner 协议与 AgentTool

SubAgentSpawner 协议

子 Agent 的生成不是 AgentTool 直接 new 一个 Agent 出来——中间隔了一层协议。SubAgentSpawner 定义在 Types/AgentTypes.swift 里：

public protocol SubAgentSpawner: Sendable {
    func spawn(
        prompt: String,
        model: String?,
        systemPrompt: String?,
        allowedTools: [String]?,
        maxTurns: Int?
    ) async -> SubAgentResult

    func spawn(
        prompt: String,
        model: String?,
        systemPrompt: String?,
        allowedTools: [String]?,
        maxTurns: Int?,
        disallowedTools: [String]?,
        mcpServers: [AgentMcpServerSpec]?,
        skills: [String]?,
        runInBackground: Bool?,
        isolation: String?,
        name: String?,
        teamName: String?,
        mode: PermissionMode?,
        resume: String?
    ) async -> SubAgentResult
}

两个方法，一个基础版（5 个参数），一个增强版（13 个参数）。协议还提供了默认实现，增强版直接调用基础版，这样已有的实现类不用改代码就能兼容。

为什么要把 spawner 放在 Types/ 而不是 Core/？因为 Tools/Advanced/AgentTool.swift 需要用它，但 Tools/ 不应该导入 Core/。把协议定义在 Types/，具体实现放在 Core/，通过 ToolContext.agentSpawner 注入——这是 SDK 里常见的依赖倒置。

DefaultSubAgentSpawner 实现

DefaultSubAgentSpawner 在 Core/DefaultSubAgentSpawner.swift 里，做了这几件事：

final class DefaultSubAgentSpawner: SubAgentSpawner, @unchecked Sendable {
    private let apiKey: String
    private let baseURL: String?
    private let parentModel: String
    private let parentTools: [ToolProtocol]
    private let provider: LLMProvider
    private let client: (any LLMClient)?

    func spawn(...) async -> SubAgentResult {
        // 1. 过滤掉 AgentTool，防止无限递归
        var subTools = parentTools.filter { $0.name != "Agent" }

        // 2. 如果指定了 allowedTools，进一步过滤
        if let allowed = allowedTools, !allowed.isEmpty {
            let allowedSet = Set(allowed)
            subTools = subTools.filter { allowedSet.contains($0.name) }
        }

        // 3. disallowedTools 再过一遍（优先级高于 allowedTools）
        if let disallowed = disallowedTools, !disallowed.isEmpty {
            let disallowedSet = Set(disallowed)
            subTools = subTools.filter { !disallowedSet.contains($0.name) }
        }

        // 4. 创建子 Agent 并执行
        let options = AgentOptions(
            apiKey: apiKey,
            model: model ?? parentModel,
            systemPrompt: systemPrompt,
            maxTurns: maxTurns ?? 10,
            tools: subTools
        )
        let agent = Agent(options: options)
        let result = await agent.prompt(prompt)

        return SubAgentResult(
            text: result.text.isEmpty
                ? "(Subagent completed with no text output)"
                : result.text,
            toolCalls: [],
            isError: result.status != .success
        )
    }
}

几个关键点：

防递归：子 Agent 不会再拿到 AgentTool，所以不会出现 Agent 套 Agent 套 Agent 的情况
工具继承：子 Agent 默认继承父 Agent 的所有工具（除了 AgentTool），但可以通过 allowedTools / disallowedTools 限制
阻塞式执行：父 Agent 调用 spawn() 后会 await，等子 Agent 跑完才继续

AgentTool：LLM 眼里的子 Agent 工具

AgentTool 是暴露给 LLM 的工具。LLM 调用 Agent 工具时传入 prompt 和参数，AgentTool 负责调用 spawner 生成子 Agent。

它内置了两种预定义的子 Agent 类型：

private let BUILTIN_AGENTS: [String: AgentDefinition] = [
    "Explore": AgentDefinition(
        name: "Explore",
        description: "Fast agent specialized for exploring codebases...",
        systemPrompt: "You are a codebase exploration agent. Search through files and code to answer questions...",
        tools: ["Read", "Glob", "Grep", "Bash"],
        maxTurns: 10
    ),
    "Plan": AgentDefinition(
        name: "Plan",
        description: "Software architect agent for designing implementation plans...",
        systemPrompt: "You are a software architect. Design implementation plans...",
        tools: ["Read", "Glob", "Grep", "Bash"],
        maxTurns: 10
    ),
]

Explore：代码库探索，用 Glob 找文件、Grep 搜内容、Read 读文件
Plan：软件架构师，理解代码库后输出实施方案

LLM 调用 AgentTool 时，通过 subagent_type 字段指定用哪种：

{
  "prompt": "Explore the project structure and find all Swift source files",
  "description": "Explore codebase",
  "subagent_type": "Explore"
}

AgentTool 还支持一堆可选参数：model（指定模型）、maxTurns（覆盖轮次上限）、run_in_background（后台运行）、isolation（隔离模式，比如 worktree）、team_name（关联团队）、mode（权限模式）。这些参数直接透传给 spawner。

一个完整的示例

SDK 自带了一个 SubagentExample，演示了主 Agent 作为协调者，通过 AgentTool 委派 Explore 子 Agent 的完整流程：

// 主 Agent 的系统提示
let systemPrompt = """
You are a coordinator agent. When given a task, you should delegate it to a sub-agent \
using the Agent tool. The Agent tool will spawn a specialized agent (e.g., "Explore" type) \
that can use Read, Glob, Grep, and Bash tools to investigate the codebase. \
After the sub-agent returns its findings, summarize the results for the user.
"""

// 注册工具：核心工具 + AgentTool
let agent = createAgent(options: AgentOptions(
    apiKey: apiKey,
    model: defaultModel,
    systemPrompt: systemPrompt,
    maxTurns: 10,
    tools: getAllBaseTools(tier: .core) + [createAgentTool()]
))

// 发任务——主 Agent 会调用 AgentTool 委派给 Explore 子 Agent
for await message in agent.stream("""
    Explore the current project directory. Find all Swift source files, \
    examine the project structure, and provide a summary. \
    Use the Agent tool to delegate this task to an Explore sub-agent.
""") {
    switch message {
    case .toolUse(let data):
        if data.toolName == "Agent" {
            print("[Sub-agent Delegation: \(data.toolName)]")
        }
    case .toolResult(let data):
        print("[Result: \(data.content.prefix(200))]")
    case .result(let data):
        print("Turns: \(data.numTurns), Cost: $\(data.totalCostUsd)")
    default:
        break
    }
}

执行流程：用户发 prompt -> 主 Agent 判断需要探索代码库 -> 调用 AgentTool -> AgentTool 通过 spawner 生成 Explore 子 Agent -> 子 Agent 用 Glob/Grep/Read 执行探索 -> 结果返回给主 Agent -> 主 Agent 汇总后回复用户。

二、Task 系统：任务追踪与状态机

子 Agent 解决了”谁干活”的问题，Task 系统解决的是”活干了多少、谁在干、结果是什么”的问题。

TaskStore：线程安全的 Actor

TaskStore 是一个 Swift Actor，保证并发安全：

public actor TaskStore {
    private var tasks: [String: Task] = [:]
    private var taskCounter: Int = 0

    public func create(
        subject: String,
        description: String? = nil,
        owner: String? = nil,
        status: TaskStatus = .pending
    ) -> Task {
        taskCounter += 1
        let id = "task_\(taskCounter)"
        let now = dateFormatter.string(from: Date())
        let task = Task(
            id: id, subject: subject, description: description,
            status: status, owner: owner,
            createdAt: now, updatedAt: now
        )
        tasks[id] = task
        return task
    }
}

用 Actor 而不是普通类，意味着所有方法都是隐式串行化的——不需要自己加锁。多个 Agent 同时创建任务不会出现竞态条件。

Task 的状态机

Task 有 5 种状态，流转规则很明确：

public enum TaskStatus: String, Sendable, Equatable, Codable {
    case pending      // 等待开始
    case inProgress   // 进行中
    case completed    // 已完成
    case failed       // 失败
    case cancelled    // 已取消
}

状态转换有约束：pending 和 inProgress 可以转到任何状态，但 completed、failed、cancelled 是终态，不可再变：

private func isValidTransition(from: TaskStatus, to: TaskStatus) -> Bool {
    switch from {
    case .pending, .inProgress:
        return true
    case .completed, .failed, .cancelled:
        return false  // 终态，不能再转
    }
}

画成状态图：

pending ──→ inProgress ──→ completed
   │            │
   │            ├──→ failed
   │            │
   └──→ cancelled ←──┘

TaskStatus 还有个贴心的 parse() 方法，同时支持 camelCase（inProgress）和 snake_case（in_progress），因为 LLM 返回的 JSON 格式不一定统一：

public static func parse(_ string: String) -> TaskStatus? {
    if let direct = TaskStatus(rawValue: string) { return direct }
    // snake_case → camelCase
    let camel = string
        .split(separator: "_")
        .enumerated()
        .map { $0.offset == 0 ? String($0.element) : String($0.element).capitalized }
        .joined()
    return TaskStatus(rawValue: camel)
}

Task 结构体

一个 Task 实例除了基本的状态追踪，还预留了依赖关系和元数据：

public struct Task: Sendable, Equatable, Codable {
    public let id: String
    public var subject: String
    public var description: String?
    public var status: TaskStatus
    public var owner: String?        // 谁在干
    public let createdAt: String
    public var updatedAt: String
    public var output: String?       // 结果
    public var blockedBy: [String]?  // 被哪些任务阻塞
    public var blocks: [String]?     // 阻塞了哪些任务
    public var metadata: [String: String]?
}

blockedBy 和 blocks 字段说明 Task 系统预留了任务依赖的能力——任务 A 可以声明”我需要等任务 B 和 C 完成才能开始”。

三个 Task 工具

SDK 提供了三个工具让 LLM 操作 Task 系统：

TaskCreate – 创建任务：

public func createTaskCreateTool() -> ToolProtocol {
    return defineTool(
        name: "TaskCreate",
        description: "Create a new task for tracking work progress.",
        inputSchema: taskCreateSchema,
        isReadOnly: false
    ) { (input: TaskCreateInput, context: ToolContext) in
        guard let taskStore = context.taskStore else {
            return ToolExecuteResult(content: "Error: TaskStore not available.", isError: true)
        }
        let initialStatus: TaskStatus = input.status.flatMap { TaskStatus.parse($0) } ?? .pending
        let task = await taskStore.create(
            subject: input.subject,
            description: input.description,
            owner: input.owner,
            status: initialStatus
        )
        return ToolExecuteResult(
            content: "Task created: \(task.id) - \"\(task.subject)\" (\(task.status.rawValue))",
            isError: false
        )
    }
}

TaskList – 列出任务（支持按 status 和 owner 过滤）：

// LLM 可以查 "列出所有 pending 状态的任务" 或 "列出分配给 agent-1 的任务"
let tasks = await taskStore.list(status: status, owner: input.owner)

TaskUpdate – 更新任务（状态、描述、负责人、输出）：

do {
    let task = try await taskStore.update(
        id: input.id,
        status: status,
        description: input.description,
        owner: input.owner,
        output: input.output
    )
    return ToolExecuteResult(
        content: "Task updated: \(task.id) - \(task.status.rawValue) - \"\(task.subject)\"",
        isError: false
    )
} catch let error as TaskStoreError {
    return ToolExecuteResult(content: "Error: \(error.localizedDescription)", isError: true)
}

注意 TaskUpdate 会抛出 invalidStatusTransition 错误——比如试图把一个 completed 的任务改成 inProgress，LLM 会收到错误提示，可以据此调整策略。

三、Team 系统：团队组建与管理

Task 系统追踪”做什么”，Team 系统解决”谁跟谁一组”。

TeamStore

和 TaskStore 一样，TeamStore 也是 Actor：

public actor TeamStore {
    private var teams: [String: Team] = [:]
    private var teamCounter: Int = 0

    public func create(
        name: String,
        members: [TeamMember] = [],
        leaderId: String = "self"
    ) -> Team {
        teamCounter += 1
        let id = "team_\(teamCounter)"
        let team = Team(
            id: id, name: name, members: members,
            leaderId: leaderId,
            createdAt: dateFormatter.string(from: Date()),
            status: .active
        )
        teams[id] = team
        return team
    }
}

Team 有两种状态：active 和 disbanded。删除 Team 不是真删，而是把状态改成 disbanded——标记为 disbanded 的 Team 不允许添加/移除成员。

TeamMember 和角色

public enum TeamRole: String, Sendable, Equatable, Codable {
    case leader   // 团队领导
    case member   // 普通成员
}

public struct TeamMember: Sendable, Equatable, Codable {
    public let name: String
    public let role: TeamRole
}

TeamCreateTool 创建 Team 时，所有传入的成员默认都是 member 角色，leaderId 默认是 "self"（即创建者自己）：

let members: [TeamMember] = input.members?.map { TeamMember(name: $0) } ?? []
let team = await teamStore.create(
    name: input.name,
    members: members,
    leaderId: "self"
)

TeamStore 还提供了动态管理成员的能力：

// 添加成员
try teamStore.addMember(teamId: "team_1", member: TeamMember(name: "agent-coder"))

// 移除成员
try teamStore.removeMember(teamId: "team_1", agentName: "agent-coder")

// 查找某个 Agent 属于哪个团队
let team = await teamStore.getTeamForAgent(agentName: "agent-coder")

getTeamForAgent 对消息传递很重要——发消息时需要知道发件人属于哪个 Team，才能验证收件人是不是队友。

AgentRegistry：Agent 注册表

除了 TeamStore，还有一个 AgentRegistry 负责追踪所有活跃的 Agent：

public actor AgentRegistry {
    private var agents: [String: AgentRegistryEntry] = [:]
    private var nameIndex: [String: String] = [:]  // name -> agentId

    public func register(agentId: String, name: String, agentType: String) throws -> AgentRegistryEntry {
        if nameIndex[name] != nil {
            throw AgentRegistryError.duplicateAgentName(name: name)
        }
        let entry = AgentRegistryEntry(...)
        agents[agentId] = entry
        nameIndex[name] = agentId
        return entry
    }

    public func getByName(name: String) -> AgentRegistryEntry? {
        guard let agentId = nameIndex[name] else { return nil }
        return agents[agentId]
    }
}

名字唯一性约束——同一个 AgentRegistry 里不能注册两个同名的 Agent。nameIndex 是一个反查索引，支持 O(1) 的名字查找。

四、消息传递：MailboxStore 与 SendMessage

有了 Team，Agent 之间需要能通信。SDK 用的是邮箱模式（Mailbox）——发消息不直接推给对方，而是放进对方的邮箱，对方自己来取。

MailboxStore

public actor MailboxStore {
    private var mailboxes: [String: [AgentMessage]] = [:]

    // 点对点发送
    public func send(from: String, to: String, content: String, type: AgentMessageType = .text) {
        let message = AgentMessage(from: from, to: to, content: content,
                                   timestamp: dateFormatter.string(from: Date()), type: type)
        if mailboxes[to] == nil { mailboxes[to] = [] }
        mailboxes[to]?.append(message)
    }

    // 广播——发给所有有邮箱的 Agent
    public func broadcast(from: String, content: String, type: AgentMessageType = .text) {
        let timestamp = dateFormatter.string(from: Date())
        for (agentName, _) in mailboxes {
            let message = AgentMessage(from: from, to: agentName, content: content,
                                       timestamp: timestamp, type: type)
            mailboxes[agentName]?.append(message)
        }
    }

    // 读取并清空邮箱
    public func read(agentName: String) -> [AgentMessage] {
        guard let messages = mailboxes[agentName] else { return [] }
        mailboxes[agentName] = []  // 读完清空
        return messages
    }
}

三个核心操作：send（点对点）、broadcast（广播）、read（读取）。read 是破坏性读取——读一次邮箱就清空了。broadcast 只发给已经有邮箱的 Agent，不会凭空创建邮箱。

消息类型除了普通文本（.text），还有 .shutdownRequest、.shutdownResponse、.planApprovalResponse——这些特殊类型用于团队管理的协调操作。

SendMessage 工具

SendMessageTool 做了三层校验：

// 1. 必须有 MailboxStore
guard let mailboxStore = context.mailboxStore else { ... }
// 2. 必须有 TeamStore
guard let teamStore = context.teamStore else { ... }
// 3. 必须知道发送者是谁
guard let senderName = context.senderName else { ... }

// 4. 发送者必须在某个 Team 里
guard let team = await teamStore.getTeamForAgent(agentName: senderName) else { ... }

// 5. 收件人必须是同 Team 的成员
let isMember = team.members.contains { $0.name == input.to }
guard isMember else { ... }

广播用 "*" 作为收件人：

{ "to": "*", "message": "Phase 1 complete, starting Phase 2." }

点对点用具体名字：

{ "to": "agent-coder", "message": "Here's the spec for module A." }

校验不通过时返回错误信息，LLM 能看到哪些成员可用，可以调整发送目标。

五、编排模式：怎么组合这些能力

单个 Agent、Task、Team、Mailbox 各自能做什么清楚了。实际场景中怎么组合？看一个典型的工作流。

模式一：主 Agent + 并行子 Agent

最简单的模式。主 Agent 收到复杂任务后，同时启动多个子 Agent 各自处理一部分：

let agent = createAgent(options: AgentOptions(
    apiKey: apiKey,
    model: "claude-sonnet-4-6",
    systemPrompt: """
    You are a coordinator. Break complex tasks into subtasks, \
    delegate each to an Explore sub-agent, then synthesize results.
    """,
    maxTurns: 20,
    tools: getAllBaseTools(tier: .core) + [
        createAgentTool(),
        createTaskCreateTool(),
        createTaskUpdateTool(),
        createTaskListTool()
    ],
    taskStore: TaskStore()
))

LLM 可能这样编排：

TaskCreate("Analyze module A") – 创建任务
Agent(prompt: "Analyze module A", subagent_type: "Explore") – 委派子 Agent
TaskUpdate(id: "task_1", status: "completed", output: result) – 标记完成
重复步骤 1-3 处理其他模块
汇总所有结果

模式二：团队协作 + 消息传递

需要多个 Agent 长期协作时，用 Team + Mailbox：

let mailboxStore = MailboxStore()
let teamStore = TeamStore()

let agent = createAgent(options: AgentOptions(
    apiKey: apiKey,
    model: "claude-sonnet-4-6",
    agentName: "coordinator",
    mailboxStore: mailboxStore,
    teamStore: teamStore,
    tools: getAllBaseTools(tier: .core) + [
        createAgentTool(),
        createTeamCreateTool(),
        createTeamDeleteTool(),
        createSendMessageTool(),
        createTaskCreateTool(),
        createTaskListTool(),
        createTaskUpdateTool()
    ]
))

LLM 的编排可能像这样：

TeamCreate(name: "refactor-team", members: ["explorer", "planner", "coder"]) – 建团队
TaskCreate("Explore codebase", owner: "explorer") – 创建任务
Agent(prompt: "...", name: "explorer", subagent_type: "Explore") – 启动探索 Agent
SendMessage(to: "planner", message: "Exploration done, here's the summary...") – 通知规划 Agent
TaskCreate("Write implementation plan", owner: "planner") – 下一个任务
持续推进…

模式三：工作队列

用 Task 系统做工作队列，主 Agent 创建一批任务，子 Agent 逐个领取执行：

主 Agent:
  TaskCreate("Fix bug #1")     → task_1 (pending)
  TaskCreate("Fix bug #2")     → task_2 (pending)
  TaskCreate("Add feature X")  → task_3 (pending)

子 Agent A:
  TaskList(status: "pending")       → [task_1, task_2, task_3]
  TaskUpdate(task_1, status: "in_progress", owner: "agent-a")
  ... 干活 ...
  TaskUpdate(task_1, status: "completed", output: "Fixed by ...")

子 Agent B:
  TaskList(status: "pending")       → [task_2, task_3]
  TaskUpdate(task_2, status: "in_progress", owner: "agent-b")
  ... 干活 ...

TaskStore 是 Actor，多个 Agent 并发更新同一条任务不会出问题（先到先得），但不会自动分配——需要 LLM 自己协调谁认领哪个任务。

设计思路的取舍

这套多 Agent 协作机制有几个设计选择：

为什么子 Agent 不能再生子 Agent？ DefaultSubAgentSpawner 在创建子 Agent 时过滤掉了 AgentTool。这是有意的限制——如果不限制，一个 Agent 生成一个 Agent 再生成一个 Agent，递归深度不可控，token 消耗也会指数级增长。

为什么消息是拉取（Pull）不是推送（Push）？ MailboxStore.read() 是破坏性读取，Agent 需要主动调用才能收到消息。这比推送模式简单得多——不需要维护回调、不需要处理 Agent 离线的情况。代价是实时性差，但在 Agent Loop 的工具调用频率下（每个 turn 都可以调工具），拉取的延迟可以接受。

为什么 Task 的状态机没有自动流转？ blockedBy 字段只是声明了依赖关系，但 TaskStore.update() 不会自动检查前置任务是否完成。这意味着”等任务 A 做完再做任务 B”这个逻辑需要 LLM 自己实现——调 TaskList 看状态，再决定下一步。这是一个务实的取舍：自动依赖解析可以加，但对 LLM 来说，显式检查反而更可控。

小结

Open Agent SDK 的多 Agent 协作由三层构成：

子 Agent：通过 SubAgentSpawner 协议和 AgentTool 实现，主 Agent 在运行时动态生成子 Agent 委派任务，内置 Explore 和 Plan 两种类型
Task 系统：基于 TaskStore Actor 的任务追踪，有明确的状态机（pending -> inProgress -> completed/failed/cancelled），终态不可逆转
Team + Mailbox：TeamStore 管理团队和成员，MailboxStore 实现邮箱式消息传递，支持点对点和广播

三层可以独立使用，也可以组合——用 Task 追踪进度，用 Team 组织成员，用 Mailbox 协调通信，用子 Agent 执行具体工作。

下一篇会看 SDK 的 会话持久化：Agent 对话历史怎么存、怎么恢复、怎么在重启后继续之前的工作。

系列文章：

第 0 篇：Open Agent SDK (Swift)：用原生 Swift 并发构建 AI Agent 应用
第 1 篇：Agent Loop 内核：从 prompt 到多轮对话的完整运转机制
第 2 篇：34 个工具的背后：工具协议、三层架构与自定义扩展
第 3 篇：MCP 集成实战：让 Agent 连接万物
第 4 篇：多 Agent 协作：子代理、团队与任务编排（本文）
第 5 篇：会话持久化与安全防线
第 6 篇：多 LLM 提供商与运行时控制

GitHub：terryso/open-agent-sdk-swift

深入 Open Agent SDK（三）：MCP 集成实战——让 Agent 连接万物

Wed, 22 Apr 2026 10:00:00 +0000

本文是「深入 Open Agent SDK (Swift)」系列第三篇。系列目录见这里。

上一篇看了 SDK 内置的 34 个工具——文件读写、Bash 执行、代码搜索，覆盖了常见的开发场景。但 Agent 的能力不可能只靠内置工具撑满。你需要连接数据库、调用企业 API、操作内部系统——这些事情需要一个标准化的接入方式。

MCP（Model Context Protocol）就是干这个的。这篇文章看 Open Agent SDK 怎么通过 MCP 协议把外部工具接到 Agent Loop 里。

MCP 协议是什么

MCP 是 Anthropic 提出的一个开放协议，定义了 LLM 应用和外部工具/数据源之间的通信标准。思路是：

工具端（MCP Server）暴露一组工具，每个工具有名字、描述、输入 schema
调用端（MCP Client）通过标准协议发现工具、调用工具、拿到结果
通信基于 JSON-RPC，传输层可以换

为什么 Agent 需要它？因为不可能把所有工具都写进 SDK。有了 MCP，任何人都可以写一个 MCP Server（比如 @modelcontextprotocol/server-filesystem），任何 Agent 都能对接——不需要改 SDK 代码，不需要写适配器，配一行就接上了。

Open Agent SDK 的 MCP 集成分两条路：

外部 MCP 服务器：通过 stdio/HTTP/SSE 连接第三方 MCP Server，走完整的 MCP 协议
进程内 MCP 服务器：用 InProcessMCPServer 把 SDK 工具包装成 MCP Server，零协议开销

下面逐个看。

五种传输配置

SDK 用 McpServerConfig 枚举统一了所有传输方式：

public enum McpServerConfig: Sendable, Equatable {
    case stdio(McpStdioConfig)       // 子进程 stdin/stdout
    case sse(McpTransportConfig)     // Server-Sent Events
    case http(McpTransportConfig)    // HTTP POST
    case sdk(McpSdkServerConfig)     // 进程内，零开销
    case claudeAIProxy(McpClaudeAIProxyConfig) // ClaudeAI 代理
}

Stdio：启动子进程

最常用的方式。Agent 启动一个子进程，通过 stdin/stdout 交换 JSON-RPC 消息。适用于 Node.js/Python 写的 MCP Server：

let servers: [String: McpServerConfig] = [
    "filesystem": .stdio(McpStdioConfig(
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    )),
    "git": .stdio(McpStdioConfig(
        command: "uvx",
        args: ["mcp-server-git"],
        env: ["GIT_REPO_PATH": "/my/repo"]
    ))
]

MCPStdioTransport 内部用 Foundation 的 Process 启动子进程，用 FileDescriptor 做底层 I/O。几个细节：

命令解析：如果 command 不是绝对路径，会先 which 查找。找不到就当文件路径用
消息分隔：每条 JSON-RPC 消息以换行符分隔，支持 CRLF
安全过滤：CODEANY_API_KEY 默认不会传给子进程，除非你在 env 里显式指定
重连：MCPClient 配置了最多 2 次自动重试，初始间隔 1 秒，指数退避到最大 10 秒

SSE 和 HTTP：连接远程服务

远程 MCP Server 通过 HTTP 连接，区分两种模式：

// SSE 模式（长连接，服务端推送）
let sseServer: [String: McpServerConfig] = [
    "remote-tools": .sse(McpTransportConfig(
        url: "https://mcp.example.com/sse",
        headers: ["Authorization": "Bearer token123"]
    ))
]

// HTTP 模式（请求-响应）
let httpServer: [String: McpServerConfig] = [
    "api-tools": .http(McpTransportConfig(
        url: "https://mcp.example.com/api"
    ))
]

SSE 适合需要服务端主动推送的场景，HTTP 适合简单的请求-响应。两者底层都用 HTTPClientTransport，区别在 streaming 参数。McpSseConfig 和 McpHttpConfig 实际上是 McpTransportConfig 的别名：

public typealias McpSseConfig = McpTransportConfig
public typealias McpHttpConfig = McpTransportConfig

SDK：进程内零开销

不走任何网络协议，直接在进程内把工具注册进去。后面第六部分单独讲。

ClaudeAI Proxy

连接 ClaudeAI 的代理端点，用 server ID 做认证：

let proxyServer: [String: McpServerConfig] = [
    "claude-tools": .claudeAIProxy(McpClaudeAIProxyConfig(
        url: "https://claudeai.example.com/proxy",
        id: "server-abc-123"
    ))
]

内部实现就是 HTTP 传输加了一个 X-ClaudeAI-Server-ID header。

连接流程：从配置到工具池

Agent 怎么把 MCP 工具合并到自己的工具池里？从 assembleFullToolPool() 追踪：

func assembleFullToolPool() async -> ([ToolProtocol], MCPClientManager?) {
    let baseTools = options.tools ?? []

    guard let mcpServers = options.mcpServers, !mcpServers.isEmpty else {
        return (baseTools, nil)
    }

    // 第一步：分离 SDK 配置和外部配置
    let (sdkTools, externalServers) = await Self.processMcpConfigs(mcpServers)

    // 第二步：连接外部 MCP 服务器
    var externalTools: [ToolProtocol] = []
    var manager: MCPClientManager? = nil

    if !externalServers.isEmpty {
        let mcpManager = MCPClientManager()
        await mcpManager.connectAll(servers: externalServers)
        externalTools = await mcpManager.getMCPTools()
        manager = mcpManager
    }

    // 第三步：合并所有工具
    let allMCPTools = sdkTools + externalTools
    let pool = assembleToolPool(
        baseTools: getAllBaseTools(tier: .core) + getAllBaseTools(tier: .specialist),
        customTools: baseTools,
        mcpTools: allMCPTools,
        allowed: options.allowedTools,
        disallowed: options.disallowedTools
    )

    return (pool, manager)
}

三步走：

1. 分离配置。 processMcpConfigs() 把 .sdk 配置和外部配置（stdio/sse/http）分开。SDK 配置直接从 InProcessMCPServer 提取工具，用 SdkToolWrapper 加上命名空间前缀；外部配置留给 MCPClientManager 处理。

2. 连接外部服务器。 MCPClientManager 是一个 actor，用 withTaskGroup 并发连接所有服务器。每个连接经历四步：

创建 Transport → 启动连接 → MCP 握手 (initialize) → listTools() 发现工具

发现的工具被包装成 MCPToolDefinition——一个遵循 ToolProtocol 的结构体。工具名按 mcp__{serverName}__{toolName} 格式命名，避免跟内置工具冲突。比如 filesystem 服务器上的 read_file 工具，最终叫 mcp__filesystem__read_file。

3. 组装工具池。 MCP 工具和内置工具、自定义工具合并，经过 allowedTools / disallowedTools 过滤，形成最终的工具池。LLM 看到的是过滤后的完整工具列表。

完整的端到端使用代码：

let agent = createAgent(options: AgentOptions(
    apiKey: "sk-...",
    model: "claude-sonnet-4-6",
    permissionMode: .bypassPermissions,
    mcpServers: [
        "filesystem": .stdio(McpStdioConfig(
            command: "npx",
            args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
        ))
    ]
))

// Agent Loop 启动时自动连接 MCP 服务器、发现工具、合并到工具池
let result = await agent.prompt("List all files in /tmp and read the first one")

运行时管理

MCP 服务器不是连上就完事了。运行过程中你可能需要查状态、重连、开关、甚至动态替换服务器集合。SDK 提供了四个方法。

查状态：mcpServerStatus()

let status = await agent.mcpServerStatus()
for (name, info) in status {
    print("\(name): \(info.status.rawValue)")  // connected / failed / pending / disabled / needsAuth
    print("  tools: \(info.tools)")             // ["read_file", "write_file", ...]
    if let error = info.error {
        print("  error: \(error)")
    }
}

McpServerStatus 有五个状态值（跟 TypeScript SDK 对齐）：

状态	含义
`connected`	已连接，工具可用
`failed`	连接失败
`pending`	正在连接
`disabled`	被用户禁用
`needsAuth`	需要认证

重连：reconnectMcpServer()

网络抖动或服务端重启后，手动重连某个服务器：

try await agent.reconnectMcpServer(name: "filesystem")

内部实现：断开旧连接 → 清理状态 → 用初始配置重新走一遍连接流程。MCPClientManager 在首次连接时保存了原始配置（originalConfigs），重连时直接用它。

开关：toggleMcpServer()

临时禁用某个服务器（断开连接但保留配置），之后还能再开：

// 禁用
try await agent.toggleMcpServer(name: "filesystem", enabled: false)

// 重新启用
try await agent.toggleMcpServer(name: "filesystem", enabled: true)

动态替换：setMcpServers()

运行时替换整个 MCP 服务器集合。SDK 做了 diff：新增的连接、删除的断开、配置变化的重新连接：

let result = try await agent.setMcpServers([
    "filesystem": .stdio(McpStdioConfig(
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem", "/data"]
    )),
    "database": .stdio(McpStdioConfig(
        command: "python3",
        args: ["-m", "my_db_server"]
    ))
])

print("Added: \(result.added)")      // ["database"]
print("Removed: \(result.removed)")  // 之前有但现在没有的
print("Errors: \(result.errors)")    // 连接失败的

MCPClientManager.setServers() 的 diff 逻辑看一下：

public func setServers(_ servers: [String: McpServerConfig]) async -> McpServerUpdateResult {
    let existingNames = Set(originalConfigs.keys)
    let newNames = Set(servers.keys)

    let addedNames = newNames.subtracting(existingNames)
    let removedNames = existingNames.subtracting(newNames)

    // 配置变化的视为 remove + add
    let changedNames = newNames.intersection(existingNames).filter { name in
        originalConfigs[name] != servers[name]
    }

    let effectiveAdded = addedNames.union(changedNames)
    // ...执行连接和断开
}

先删除不再需要的，再连接新增和变化的。变化的服务器会被完全重建，不是热更新。这对于长运行的 Agent 应用很重要——你可以在不重启 Agent 的情况下调整 MCP 配置。

MCP 资源：不只是工具

MCP 协议除了工具（Tools）还有资源（Resources）。工具是”做事情”，资源是”读数据”——比如一个数据库 MCP Server 可以暴露一个 query 工具，同时暴露 tables 资源让 Agent 看有哪些表。

SDK 内置了两个资源相关工具：ListMcpResources 和 ReadMcpResource。

ListMcpResources

列出所有已连接 MCP 服务器的可用资源：

// LLM 看到的工具描述：
// "List available resources from connected MCP servers.
//  Resources can include files, databases, and other data sources."

// 可选参数：server — 按服务器名过滤

内部实现通过 MCPResourceProvider 协议查询每个连接：

public protocol MCPResourceProvider: Sendable {
    func listResources() async -> [MCPResourceItem]?
    func readResource(uri: String) async throws -> MCPReadResult
}

资源用 MCPResourceItem 表示——有名字、描述、URI。

ReadMcpResource

读取指定 URI 的资源内容：

// LLM 看到的工具：
// "Read a specific resource from an MCP server."
// 参数：server（服务器名）、uri（资源 URI）

两个工具都是只读的，通过 ToolContext.mcpConnections 拿到连接信息——不用全局变量，线程安全。

进程内 MCP：InProcessMCPServer

InProcessMCPServer 是 SDK 里一个独特的设计。它让你用 defineTool() 创建工具，然后包装成一个 MCP Server——但实际上不走 MCP 协议。

为什么？因为有些场景你只是想把自己的工具加到 Agent 的工具池里，不需要跨进程通信。直接调函数比走 JSON-RPC 序列化高效得多。

基本用法

// 用 defineTool 创建工具
struct WeatherInput: Codable {
    let city: String
}

let weatherTool = defineTool(
    name: "get_weather",
    description: "Get the current weather for a given city.",
    inputSchema: [
        "type": "object",
        "properties": [
            "city": ["type": "string", "description": "The city name"]
        ],
        "required": ["city"]
    ],
    isReadOnly: true
) { (input: WeatherInput, context: ToolContext) -> String in
    let data: [String: String] = [
        "Beijing": "Sunny, 22C",
        "Tokyo": "Cloudy, 18C",
    ]
    return data[input.city] ?? "No data for \(input.city)"
}

// 包装为 InProcessMCPServer
let server = InProcessMCPServer(
    name: "weather",       // 工具名将是 mcp__weather__get_weather
    version: "1.0.0",
    tools: [weatherTool],
    cwd: "/tmp"
)

// 通过 asConfig() 生成配置，注入 Agent
let agent = createAgent(options: AgentOptions(
    apiKey: "sk-...",
    model: "claude-sonnet-4-6",
    mcpServers: ["weather": await server.asConfig()]
))

内部实现

InProcessMCPServer 是一个 actor，有两种工作模式：

SDK 内部模式（常用）： processMcpConfigs() 检测到 .sdk 配置时，直接调用 server.getTools() 拿到工具列表，用 SdkToolWrapper 加上命名空间前缀。整个过程中工具的 call() 方法直接被调用，没有任何序列化开销：

private struct SdkToolWrapper: ToolProtocol, Sendable {
    let serverName: String
    let innerTool: ToolProtocol

    var name: String { "mcp__\(serverName)__\(innerTool.name)" }

    func call(input: Any, context: ToolContext) async -> ToolResult {
        return await innerTool.call(input: input, context: context)
    }
}

注意 SdkToolWrapper 的 call() 直接转发到 innerTool——没有 JSON-RPC，没有 Value 转换，就是直接调函数。

外部客户端模式： 如果有外部 MCP Client 想连进来，createSession() 创建一个 InMemoryTransport 对，跑完整的 MCP 握手。这种场景下才有协议开销：

public func createSession() async throws -> (Server, InMemoryTransport) {
    let mcpServer = await getOrCreateMCPServer()
    let session = await mcpServer.createSession()
    let (clientTransport, serverTransport) = await InMemoryTransport.createConnectedPair()
    try await session.start(transport: serverTransport)
    return (session, clientTransport)
}

InProcessMCPServer 内部维护了一个 MCPServer 实例（懒加载），注册工具时把每个 ToolProtocol 的 call() 包装成 MCP 的 handler closure——处理参数格式转换（[String: Value] 到 [String: Any]）、构建 ToolContext、处理错误结果。

注意事项

命名限制：server name 不能包含 __（双下划线），因为会跟命名空间前缀 mcp__{server}__{tool} 冲突。构造器里有 precondition 检查
错误处理：工具返回 isError: true 时，MCP 层面会抛出 ToolExecutionError，让 MCP 协议返回 isError: true
工具注册失败：会触发 assertionFailure，说明是代码 bug（比如重复的工具名）

完整示例：多工具 MCP 服务器

这是 AdvancedMCPExample 示例的核心部分，展示了多工具注册和错误处理：

// 天气工具 — 返回 String
let weatherTool = defineTool(
    name: "get_weather",
    description: "Get the current weather for a given city.",
    inputSchema: [
        "type": "object",
        "properties": [
            "city": ["type": "string", "description": "The city name"]
        ],
        "required": ["city"]
    ],
    isReadOnly: true
) { (input: WeatherInput, context: ToolContext) -> String in
    let data: [String: String] = [
        "Beijing": "Sunny, 22C, humidity 45%",
        "Tokyo": "Cloudy, 18C, humidity 65%",
    ]
    return data[input.city] ?? "No data for \(input.city)"
}

// 邮箱验证 — 返回 ToolExecuteResult，包含错误处理
let validationTool = defineTool(
    name: "validate_email",
    description: "Validate an email address.",
    inputSchema: [
        "type": "object",
        "properties": [
            "email": ["type": "string", "description": "The email address"]
        ],
        "required": ["email"]
    ],
    isReadOnly: true
) { (input: ValidateInput, context: ToolContext) -> ToolExecuteResult in
    if !input.email.contains("@") {
        return ToolExecuteResult(
            content: "Invalid email: '\(input.email)' missing '@'",
            isError: true
        )
    }
    return ToolExecuteResult(content: "Email '\(input.email)' is valid.", isError: false)
}

// 打包为 MCP 服务器
let utilityServer = InProcessMCPServer(
    name: "utility",
    version: "1.0.0",
    tools: [weatherTool, validationTool],
    cwd: "/tmp"
)

// 创建 Agent
let agent = createAgent(options: AgentOptions(
    apiKey: apiKey,
    model: "claude-sonnet-4-6",
    systemPrompt: "You have weather and email validation tools.",
    permissionMode: .bypassPermissions,
    mcpServers: ["utility": await utilityServer.asConfig()]
))

// LLM 会自动调用 mcp__utility__get_weather 或 mcp__utility__validate_email
let result = await agent.prompt("Check weather in Tokyo and validate test@example.com")
print(result.text)

工具返回错误时，Agent 不会崩溃。错误信息喂回 LLM，LLM 看到后会调整策略——比如告诉用户邮箱格式不对。

实战建议

选传输方式。 进程内的工具用 InProcessMCPServer（SDK 模式），外部工具用 stdio（本地）或 HTTP/SSE（远程）。不要用 stdio 去连远程服务，也不要用 HTTP 去连本地命令行工具。

命名要规范。 MCP 工具名是 mcp__{server}__{tool} 三段式。server name 简短有意义，不要用双下划线。filesystem 比 fs-tools-v2 好，因为 LLM 看到 mcp__filesystem__read_file 能直接猜出含义。

错误要包容。 MCPClientManager 的连接失败不会炸掉 Agent——失败的服务器 status 标记为 error，贡献零工具。Agent Loop 照样跑，只是少了那些工具。设计你的系统时也应该遵循这个原则：外部服务不可用时降级运行，不要整体崩溃。

运行时管理用好。 长运行的 Agent 应用应该在启动后检查 mcpServerStatus()，失败的用 reconnectMcpServer() 重试。需要动态调整时用 setMcpServers() 而不是重建 Agent。

系列文章：

第 0 篇：Open Agent SDK (Swift)：用原生 Swift 并发构建 AI Agent 应用
第 1 篇：Agent Loop 内核：从 prompt 到多轮对话的完整运转机制
第 2 篇：34 个工具的背后：工具协议、三层架构与自定义扩展
第 3 篇：MCP 集成实战：让 Agent 连接万物（本文）
第 4 篇：多 Agent 协作：子代理、团队与任务编排
第 5 篇：会话持久化与安全防线
第 6 篇：多 LLM 提供商与运行时控制

GitHub：terryso/open-agent-sdk-swift

深入 Open Agent SDK（二）：34 个工具的背后——工具协议、三层架构与自定义扩展

Wed, 22 Apr 2026 09:00:00 +0000

本文是「深入 Open Agent SDK (Swift)」系列第二篇。系列目录见这里。

上一篇分析了 Agent Loop 的运转机制，其中有一个环节是”执行工具”——LLM 说”我要调 Bash”，SDK 就真的起一个进程跑命令。但这背后的工具系统远不止”调个函数”那么简单。34 个内置工具怎么组织？怎么从 LLM 的 JSON 输入安全地转成 Swift 类型？怎么控制哪些工具能用？

这篇文章从协议定义开始，一层一层看 Open Agent SDK 的工具系统。

ToolProtocol：一个工具长什么样

SDK 里每个工具都遵循 ToolProtocol 协议：

public protocol ToolProtocol: Sendable {
    var name: String { get }
    var description: String { get }
    var inputSchema: ToolInputSchema { get }
    var isReadOnly: Bool { get }
    var annotations: ToolAnnotations? { get }

    func call(input: Any, context: ToolContext) async -> ToolResult
}

五个属性一个方法，逐个说。

name 是工具的唯一标识，LLM 在 tool_use block 里用这个名字指定要调哪个工具。所有内置工具用 PascalCase 命名：Read、Bash、Glob、CronCreate。

description 是给 LLM 看的工具说明。这段文字会作为 tool definition 的一部分发给 API，质量直接影响 LLM 什么时候会选择调用这个工具。

inputSchema 是一个 [String: Any] 类型的 JSON Schema 字典，描述工具接受的输入结构。API 调用时它被原样传给 input_schema 字段。

isReadOnly 是一个布尔标记，用来告诉 Agent Loop 这个工具有没有副作用。上一篇提到过，Agent Loop 用这个字段做分桶：只读工具并发执行，变更工具串行执行。

annotations 是可选的行为提示，包含四个布尔字段：

public struct ToolAnnotations: Sendable, Equatable {
    public let readOnlyHint: Bool       // 只读，无副作用
    public let destructiveHint: Bool    // 可能做不可逆操作
    public let idempotentHint: Bool     // 幂等，多次调用结果相同
    public let openWorldHint: Bool      // 会和外部世界交互
}

注意 destructiveHint 默认是 true——SDK 对工具采取”默认危险”策略，工具需要主动声明自己不危险。这些提示不会影响 SDK 自身的执行逻辑，但 LLM 会参考它们决定怎么使用工具。

ToolResult 和 ToolExecuteResult

call() 方法返回 ToolResult，这是工具执行后喂回给 LLM 的内容：

public struct ToolResult: Sendable {
    public let toolUseId: String         // 对应 LLM 返回的 tool_use ID
    public let content: String           // 文本内容
    public let typedContent: [ToolContent]?  // 多模态内容（文本、图片、资源引用）
    public let isError: Bool             // 是否为错误结果
}

content 和 typedContent 之间有个兼容设计：当 typedContent 有值时，content 会从中提取所有 .text 类型拼接返回；否则直接返回存储的字符串。这样旧代码只用 content 也能正常工作，新代码可以用 typedContent 返回图片等非文本内容。

ToolContent 是一个枚举，支持三种内容类型：

public enum ToolContent: Sendable {
    case text(String)
    case image(data: Data, mimeType: String)
    case resource(uri: String, name: String?)
}

工具闭包内部用的是 ToolExecuteResult——结构和 ToolResult 几乎一样，只是少了 toolUseId（这个 ID 由调用层自动填充）。

ToolContext：工具的运行环境

ToolContext 是每次工具执行时注入的上下文，字段很多：

字段	用途
`cwd`	当前工作目录
`toolUseId`	本次调用的 tool_use ID
`agentSpawner`	子 Agent 生成器（AgentTool 用）
`cronStore`	定时任务存储（CronTools 用）
`todoStore`	待办事项存储（TodoWrite 用）
`worktreeStore`	工作树存储（WorktreeTools 用）
`planStore`	计划模式存储（PlanTools 用）
`taskStore`	任务管理存储（Task*Tools 用）
`mailboxStore`	邮箱存储（SendMessage 用）
`teamStore`	团队存储（TeamCreate 用）
`hookRegistry`	Hook 事件注册表
`permissionMode`	权限模式
`canUseTool`	自定义权限检查回调
`skillRegistry`	技能注册表（SkillTool 用）
`restrictionStack`	工具限制栈
`sandbox`	沙箱设置
`mcpConnections`	MCP 连接信息
`fileCache`	文件缓存
`env`	自定义环境变量

这么多可选字段，规则很简单：工具需要什么就注入什么，不需要的就是 nil。Read 工具只看 cwd、sandbox、fileCache；AgentTool 只看 agentSpawner；CronTools 只看 cronStore。每个工具只依赖自己需要的那个 Store，不知道也不关心其他 Store 的存在。

ToolContext 还提供了两个 copy 方法：withToolUseId() 用于更新调用 ID（每次工具执行时由 ToolExecutor 调用），withSkillContext() 用于递增技能嵌套深度（SkillTool 调用子技能时使用）。

三层工具架构

SDK 把 34 个工具分成三个层级：Core（10 个）、Advanced（11 个）、Specialist（13 个）。

Core 层 (10)          Advanced 层 (11)        Specialist 层 (13)
┌──────────┐         ┌──────────────┐        ┌───────────────┐
│ Read      │         │ Agent        │        │ CronCreate    │
│ Write     │         │ Skill        │        │ CronDelete    │
│ Edit      │         │ TaskCreate   │        │ CronList      │
│ Glob      │         │ TaskGet      │        │ LSP           │
│ Grep      │         │ TaskList     │        │ Config        │
│ Bash      │         │ TaskOutput   │        │ TodoWrite     │
│ AskUser   │         │ TaskStop     │        │ EnterPlanMode │
│ ToolSearch│         │ TaskUpdate   │        │ ExitPlanMode  │
│ WebFetch  │         │ SendMessage  │        │ EnterWorktree │
│ WebSearch │         │ TeamCreate   │        │ ExitWorktree  │
└──────────┘         │ TeamDelete   │        │ RemoteTrigger │
                     │ NotebookEdit │        │ ListMcpRes    │
                     └──────────────┘        │ ReadMcpRes    │
                                              └───────────────┘

分层的依据不是技术实现难度，而是工具的依赖复杂度和使用场景。

Core 层：文件系统和 shell

Core 层的 10 个工具是 Agent 的基础能力——读文件、写文件、搜索代码、跑命令。它们有一个共同特点：只依赖 ToolContext 的基础字段（cwd、sandbox、fileCache），不需要注入任何 Store。

拿 Read 工具来说。它的输入是文件路径、可选的 offset 和 limit：

private struct FileReadInput: Codable {
    let file_path: String
    let offset: Int?
    let limit: Int?
}

执行逻辑很直接：解析路径 → 检查沙箱 → 查缓存 → 读文件 → 分页 → 返回带行号的内容。还有个文件缓存的细节：如果 context.fileCache 有值，先查缓存，命中就跳过磁盘 I/O。

再看 Bash 工具。它比 Read 复杂得多，因为要处理超时、输出截断、后台进程等问题。Bash 的输入有 5 个字段：

private struct BashInput: Codable {
    let command: String
    let timeout: Int?
    let description: String?
    let runInBackground: Bool?
    let dangerouslyDisableSandbox: Bool?
}

几个关键实现细节：

超时控制。默认 120 秒，上限 600 秒。用 DispatchQueue.global().asyncAfter 设置超时，超时后 process.terminate() 杀掉进程。
输出截断。超过 100,000 字符的输出只保留前 50,000 + 后 50,000，中间用 ...(truncated)... 连接。
后台执行。run_in_background = true 时，进程起起来就返回一个 task ID，不等待完成。
进程输出用 ProcessOutputAccumulator 收集，用 @unchecked Sendable 标注，因为 Pipe 的 readability handler 和 termination handler 都在同一个 run loop dispatch queue 上触发，不会产生数据竞争。

Bash 工具的 annotations 设置了 destructiveHint: true，明确告诉 LLM 这个工具有破坏性。

Advanced 层：子 Agent 和任务编排

Advanced 层的工具开始需要外部依赖了——AgentTool 需要 agentSpawner，Task* 系列需要 taskStore，SendMessage 需要 mailboxStore 和 teamStore。

Agent 工具是这一层的代表。它的作用是让 LLM 能”派出一个子 Agent”去完成复杂任务：

public func createAgentTool() -> ToolProtocol {
    return defineTool(
        name: "Agent",
        description: "Launch a subagent to handle complex, multi-step tasks autonomously.",
        inputSchema: agentToolSchema,
        isReadOnly: false
    ) { (input: AgentToolInput, context: ToolContext) async throws -> ToolExecuteResult in
        guard let spawner = context.agentSpawner else {
            return ToolExecuteResult(
                content: "Error: Agent spawner not available.",
                isError: true
            )
        }
        // 解析内置 Agent 类型、权限模式，然后 spawn 子 Agent
        let result = await spawner.spawn(
            prompt: input.prompt,
            model: input.model ?? agentDef?.model,
            systemPrompt: agentDef?.systemPrompt,
            allowedTools: agentDef?.tools,
            ...
        )
        return ToolExecuteResult(content: result.text, isError: result.isError)
    }
}

AgentTool 的输入支持 11 个字段：prompt、description、subagent_type、model、name、maxTurns、run_in_background、isolation、team_name、mode、resume。其中 subagent_type 可以指定内置的 Explore 或 Plan 类型，也可以用自定义名称。

注意 agentSpawner 是通过 ToolContext 注入的协议类型——AgentTool 不知道子 Agent 是怎么创建的，它只调 spawner.spawn()，具体实现由 Core 层注入。这种依赖倒置让工具层完全不用 import Core 模块。

Specialist 层：领域专用工具

Specialist 层的工具依赖更重——它们各自需要一个专属 Store，而且功能高度领域化。

CronTools 是一组三个工具：CronCreate、CronDelete、CronList，通过 context.cronStore 访问定时任务存储：

public func createCronCreateTool() -> ToolProtocol {
    return defineTool(
        name: "CronCreate",
        description: "Create a scheduled recurring task (cron job).",
        inputSchema: cronCreateSchema,
        isReadOnly: false
    ) { (input: CronCreateInput, context: ToolContext) async throws -> ToolExecuteResult in
        guard let cronStore = context.cronStore else {
            return ToolExecuteResult(content: "Error: CronStore not available.", isError: true)
        }
        let job = await cronStore.create(
            name: input.name,
            schedule: input.schedule,
            command: input.command
        )
        return ToolExecuteResult(
            content: "Cron job created: \(job.id) \"\(job.name)\"",
            isError: false
        )
    }
}

三个工具都用 guard let cronStore = context.cronStore 做前置检查——如果 Store 没注入，直接返回错误而不是崩溃。

LSP 工具是另一个有趣的例子。它用 grep 模拟 Language Server Protocol 的常见操作（跳转定义、查找引用、符号搜索），完全不依赖真正的语言服务器：

case "goToDefinition", "goToImplementation":
    // 1. 用正则提取光标位置的符号名
    guard let symbol = getSymbolAtPosition(
        filePath: filePath, line: line, character: character
    ) else { ... }

    // 2. grep 搜索定义模式
    let pattern = "(func|class|struct|enum|protocol|typealias|let|var|export)\\s+\(symbol)"
    let results = await runGrep(
        arguments: ["grep", "-rn", "-E", pattern, cwd],
        cwd: cwd
    )

LSP 工具只依赖 context.cwd，不需要任何 Store——属于 Specialist 层里最轻量的工具。

defineTool：创建自定义工具的工厂函数

SDK 提供了 defineTool 工厂函数，让开发者用最少的代码创建符合 ToolProtocol 的工具。它有四个重载，覆盖不同的使用场景。

基本：Codable 输入 + String 输出

最常用的重载接受一个 Codable 输入类型和一个返回 String 的闭包：

let greetTool = defineTool(
    name: "Greet",
    description: "Generate a greeting message.",
    inputSchema: [
        "type": "object",
        "properties": [
            "name": ["type": "string", "description": "Person's name"]
        ],
        "required": ["name"]
    ],
    isReadOnly: true
) { (input: GreetInput, context: ToolContext) async throws -> String in
    return "Hello, \(input.name)!"
}

// 输入类型只需要遵循 Codable
struct GreetInput: Codable {
    let name: String
}

defineTool 内部做了四件事：

把 LLM 传来的 Any 类型 cast 成 [String: Any]
用 JSONSerialization 序列化成 Data
用 JSONDecoder 解码成你定义的 Input 类型
调用你的闭包

任何一步失败（输入不是字典、JSON 序列化失败、解码失败、闭包抛异常），都会返回 isError: true 的结果，不会炸掉 Agent Loop。这意味着你可以放心地用 try 在闭包里抛错误，它们会被妥善捕获。

结构化输出：ToolExecuteResult

如果工具需要显式标记错误（而不是用 try 抛异常），用返回 ToolExecuteResult 的重载：

let divideTool = defineTool(
    name: "Divide",
    description: "Divide two numbers.",
    inputSchema: [
        "type": "object",
        "properties": [
            "a": ["type": "number"],
            "b": ["type": "number"]
        ],
        "required": ["a", "b"]
    ]
) { (input: DivideInput, context: ToolContext) async throws -> ToolExecuteResult in
    guard input.b != 0 else {
        return ToolExecuteResult(content: "Error: Division by zero.", isError: true)
    }
    return ToolExecuteResult(content: "\(input.a / input.b)", isError: false)
}

内置工具大多用这个重载，因为很多错误是逻辑层面的（文件不存在、Store 没注入），不适合用异常表示。

无输入：NoInputTool

有些工具不需要输入参数（比如列表操作、健康检查），用无输入重载：

let listTool = defineTool(
    name: "ListItems",
    description: "List all items.",
    inputSchema: ["type": "object", "properties": [:]]
) { (context: ToolContext) async throws -> String in
    return "No items found."
}

闭包只接收 ToolContext，完全忽略输入。

原始字典输入：RawInputTool

最后一个重载跳过 Codable 解码，直接把原始 [String: Any] 字典传给闭包。适用于输入字段类型不固定的场景——比如 ConfigTool 的 value 字段可以是字符串、数字、布尔值、数组、对象或 null：

let configTool = defineTool(
    name: "Config",
    description: "Read or write configuration values.",
    inputSchema: configSchema
) { (input: [String: Any], context: ToolContext) async -> ToolExecuteResult in
    let key = input["key"] as? String ?? ""
    let value = input["value"]  // 任意类型
    // ...
}

CodingKeys 处理 snake_case

LLM 发来的 JSON 字段名通常用 snake_case（比如 file_path、run_in_background），但 Swift 的惯用命名是 camelCase。输入类型通过 CodingKeys 枚举做映射：

private struct BashInput: Codable {
    let command: String
    let runInBackground: Bool?

    private enum CodingKeys: String, CodingKey {
        case command
        case runInBackground = "run_in_background"
    }
}

这是 Swift Codable 的标准做法——defineTool 内部的 JSONDecoder 会自动用 CodingKeys 做字段名转换。

工具池组装与过滤

工具不是直接一股脑丢给 LLM 的。SDK 有一套组装和过滤机制。

assembleToolPool

assembleToolPool 把三类工具来源合并成一个去重后的工具池：

public func assembleToolPool(
    baseTools: [ToolProtocol],     // SDK 内置工具
    customTools: [ToolProtocol]?,  // 用户自定义工具
    mcpTools: [ToolProtocol]?,     // MCP 服务器提供的工具
    allowed: [String]?,
    disallowed: [String]?
) -> [ToolProtocol] {
    // 1. 合并所有来源：base + custom + MCP
    var combined = baseTools
    if let customTools { combined.append(contentsOf: customTools) }
    if let mcpTools { combined.append(contentsOf: mcpTools) }

    // 2. 按名称去重（后者覆盖前者）
    var byName = [String: ToolProtocol]()
    for tool in combined {
        byName[tool.name] = tool
    }

    // 3. 应用过滤规则
    return filterTools(
        tools: Array(byName.values),
        allowed: allowed,
        disallowed: disallowed
    )
}

去重用 Dictionary，遍历过程中同名的后者会覆盖前者。这意味着优先级是：MCP > 自定义 > 内置——用户可以用自定义工具或 MCP 工具替换同名内置工具。

filterTools

filterTools 实现白名单/黑名单过滤：

public func filterTools(
    tools: [ToolProtocol],
    allowed: [String]?,       // 白名单，nil 或空表示不过滤
    disallowed: [String]?     // 黑名单，nil 或空表示不过滤
) -> [ToolProtocol] {
    var filtered = tools
    // 先应用白名单
    if let allowed, !allowed.isEmpty {
        let allowedSet = Set(allowed)
        filtered = filtered.filter { allowedSet.contains($0.name) }
    }
    // 再应用黑名单（黑名单优先于白名单）
    if let disallowed, !disallowed.isEmpty {
        let disallowedSet = Set(disallowed)
        filtered = filtered.filter { !disallowedSet.contains($0.name) }
    }
    return filtered
}

两个规则同时存在时，黑名单优先——即使一个工具在白名单里，只要出现在黑名单里也会被排除。

ToolRestrictionStack：Skills 系统的工具限制

ToolRestrictionStack 是一个栈结构，用于 Skills 系统中控制工具可见范围。当一个 Skill 配置了 toolRestrictions 时，执行前 push 限制，执行后 pop 恢复：

let stack = ToolRestrictionStack()
stack.push([.bash, .read])     // Skill A：只能用 Bash 和 Read
stack.push([.grep, .glob])     // Skill B（嵌套）：只能用 Grep 和 Glob
// 此时 currentAllowedToolNames 只返回 Grep 和 Glob
stack.pop()                     // Skill B 完成 → 回到 Bash 和 Read
stack.pop()                     // Skill A 完成 → 恢复全部工具

栈的 LIFO 特性保证了嵌套 Skill 的正确行为——内层 Skill 的限制覆盖外层，退出后自动恢复。线程安全通过内部串行 DispatchQueue 保证。

currentAllowedToolNames 的逻辑很简单：栈空就返回全部工具，栈非空就只返回栈顶限制列表里的工具名。

toApiTool：工具转 API 格式

最后一步是把工具转成 Anthropic API 要求的格式：

public func toApiTool(_ tool: ToolProtocol) -> [String: Any] {
    var result: [String: Any] = [
        "name": tool.name,
        "description": tool.description,
        "input_schema": tool.inputSchema
    ]
    if let annotations = tool.annotations {
        result["annotations"] = [
            "readOnlyHint": annotations.readOnlyHint,
            "destructiveHint": annotations.destructiveHint,
            "idempotentHint": annotations.idempotentHint,
            "openWorldHint": annotations.openWorldHint
        ]
    }
    return result
}

annotations 只在有值时才包含——省点 token。

一个完整的自定义工具示例

把上面说的一切串起来，写一个能直接跑的自定义工具——获取天气：

import Foundation
import OpenAgentSDK

// 1. 定义输入类型
struct WeatherInput: Codable {
    let city: String
    let unit: String?  // "celsius" or "fahrenheit"

    private enum CodingKeys: String, CodingKey {
        case city, unit
    }
}

// 2. 用 defineTool 创建工具
let weatherTool = defineTool(
    name: "Weather",
    description: "Get current weather for a city.",
    inputSchema: [
        "type": "object",
        "properties": [
            "city": [
                "type": "string",
                "description": "City name, e.g. 'Beijing'"
            ],
            "unit": [
                "type": "string",
                "enum": ["celsius", "fahrenheit"],
                "description": "Temperature unit, defaults to celsius"
            ]
        ],
        "required": ["city"]
    ],
    isReadOnly: true,
    annotations: ToolAnnotations(
        readOnlyHint: true,
        destructiveHint: false,
        openWorldHint: true  // 要访问外部 API
    )
) { (input: WeatherInput, context: ToolContext) async throws -> ToolExecuteResult in
    let unit = input.unit ?? "celsius"
    // 调用天气 API（这里省略具体实现）
    let weather = try await fetchWeather(city: input.city, unit: unit)
    return ToolExecuteResult(content: weather, isError: false)
}

// 3. 注册到 Agent
let agent = createAgent(options: AgentOptions(
    apiKey: "sk-...",
    model: "claude-sonnet-4-6",
    customTools: [weatherTool]  // 自定义工具自动加入工具池
))

这个工具会被 assembleToolPool 和内置工具合并、去重、过滤后发给 LLM。LLM 看到工具定义后，在需要查天气时会自动调用它。defineTool 内部的 Codable 桥接会把 LLM 返回的 JSON 自动解码成 WeatherInput，你不需要手动处理任何 JSON 解析。

小结

工具系统的设计思路可以概括为几个关键词：

协议驱动。ToolProtocol 只规定工具的形状（名字、描述、输入 schema、执行方法），不规定工具怎么实现。这让内置工具和自定义工具走完全一样的代码路径。

依赖注入。ToolContext 的 20+ 个可选字段看着多，但每个工具只看自己需要的字段，其余全是 nil。AgentTool 不知道 CronStore 的存在，CronCreate 不知道 SubAgentSpawner 的存在。

分层组织。Core/Advanced/Specialist 三层不是代码分层（它们的代码结构完全一样），而是按依赖复杂度划分。Core 层的工具可以独立运行，Advanced 层需要 Store，Specialist 层需要更专业的领域设施。

容错优先。defineTool 内部把所有可能的失败点（类型转换、序列化、解码、执行）都包在 do/catch 里，任何环节出错都返回 isError: true 而不是 crash。Agent Loop 里工具错误不会传播，LLM 拿到错误信息后可以换策略。

下一篇来看 MCP 集成：SDK 怎么连接外部工具服务器、怎么把 MCP 工具转成 ToolProtocol、怎么在 Agent Loop 里和内置工具共存。

系列文章：

第 0 篇：Open Agent SDK (Swift)：用原生 Swift 并发构建 AI Agent 应用
第 1 篇：Agent Loop 内核：从 prompt 到多轮对话的完整运转机制
第 2 篇：34 个工具的背后：工具协议、三层架构与自定义扩展（本文）
第 3 篇：MCP 集成实战：让 Agent 连接万物
第 4 篇：多 Agent 协作：子代理、团队与任务编排
第 5 篇：会话持久化与安全防线
第 6 篇：多 LLM 提供商与运行时控制

GitHub：terryso/open-agent-sdk-swift

深入 Open Agent SDK（一）：Agent Loop 内核——从 prompt 到多轮对话的完整运转机制

Wed, 22 Apr 2026 08:00:00 +0000

本文是「深入 Open Agent SDK (Swift)」系列第一篇。系列目录见这里。

大多数 LLM 封装库做的事情是：发请求、拿响应、结束。但一个真正的 Agent 不止于此——它要能自己判断需不需要调工具、执行完工具后把结果喂回 LLM、循环往复直到拿到最终答案。这个循环就是 Agent Loop。

这篇文章分析 Open Agent SDK (Swift) 的 Agent Loop 实现，看它怎样用原生 Swift 并发在进程内跑完一整套循环。

Agent Loop 是什么？

用一句话概括：用户发 prompt → LLM 返回响应 → 如果 LLM 要求调工具就执行 → 把工具结果喂回 LLM → 重复，直到 LLM 说”我说完了”。

画成流程图：

flowchart TD
    A["用户 prompt"] --> B["构建 messages + tools"]
    B --> C["调用 LLM API"]
    C -->|end_turn / stop_sequence| D["返回结果"]
    C -->|max_tokens| C2["追加'请继续'"]
    C2 --> C
    C -->|tool_use| E["提取 tool_use blocks"]
    E --> F["按只读/变更分桶"]
    F --> G["只读工具并发执行"]
    F --> H["变更工具串行执行"]
    G --> I["微压缩大结果"]
    H --> I
    I --> J["tool_result 加入 messages"]
    J --> C

这个循环里有几个关键决策点：

什么时候停？ LLM 返回 end_turn 或 stop_sequence 时正常结束；到达 maxTurns 上限时强制停止；超出预算 (maxBudgetUsd) 时中断；用户主动取消时也中断。
工具怎么执行？ 只读工具并发跑（最多 10 个），变更工具串行跑——避免并发写文件。
上下文太长怎么办？ 自动压缩——用一个 LLM 调用把历史摘要，腾出空间继续。
中途出错怎么办？ 内置重试、回退模型、错误隔离（工具报错不会炸掉整个循环）。

两条入口：prompt() 和 stream()

SDK 提供两种方式触发 Agent Loop：

阻塞式 prompt()

let agent = createAgent(options: AgentOptions(
    apiKey: "sk-...",
    model: "claude-sonnet-4-6",
    maxTurns: 10
))

let result = await agent.prompt("Read Package.swift and summarize it.")
print(result.text)
print("Turns: \(result.numTurns), Cost: $\(String(format: "%.4f", result.totalCostUsd))")

prompt() 是”发出去等结果”模式。一次调用跑完所有轮次，返回最终的 QueryResult。适合不需要实时看到中间过程的场景——比如后台任务、CLI 工具。

流式 stream()

for await message in agent.stream("Explain this codebase.") {
    switch message {
    case .partialMessage(let data):
        print(data.text, terminator: "")  // 实时输出文本
    case .toolUse(let data):
        print("[Using tool: \(data.toolName)]")
    case .toolResult(let data):
        print("[Tool done, \(data.content.count) chars]")
    case .result(let data):
        print("\nDone: \(data.numTurns) turns, $\(String(format: "%.4f", data.totalCostUsd))")
    default:
        break
    }
}

stream() 返回 AsyncStream<SDKMessage>，在 LLM 处理过程中持续推送事件。SDK 定义了 17 种消息类型，从 partialMessage（文本片段）到 toolUse（工具调用）到 result（最终结果），覆盖了 Agent Loop 的每个阶段。

选择哪种取决于你的 UI 需求：要实时展示就用 stream()，不需要就用 prompt()。

循环体内部：一个 turn 做了什么

不管走哪条入口，每个 turn 的核心逻辑是相同的。让我们跟一遍代码。

1. 检查是否需要压缩

if shouldAutoCompact(messages: messages, model: model, state: compactState) {
    let (newMessages, _, newState) = await compactConversation(
        client: client, model: model,
        messages: messages, state: compactState,
        fileCache: fileCache,
        sessionMemory: sessionMemory
    )
    messages = newMessages
    compactState = newState
}

每个 turn 开始前先检查：消息历史估计的 token 数是不是快要撑爆上下文窗口了。如果是，用一个 LLM 调用把历史压缩成摘要，替换掉原始消息。

压缩的阈值是 模型上下文窗口 - 10000 tokens（缓冲区）。连续压缩失败 3 次后会停止尝试，避免浪费 token。

2. 发 LLM 请求（带重试和回退）

response = try await withRetry({
    try await client.sendMessage(
        model: model, messages: messages,
        maxTokens: maxTokens, system: buildSystemPrompt(),
        tools: apiTools, ...
    )
}, retryConfig: retryConfig)

所有 LLM 请求都经过 withRetry 包装，按配置的重试策略处理临时错误（网络超时、429 限流等）。

如果主模型彻底失败，还配置了 fallbackModel，SDK 会用备用模型再试一次：

if let fallbackModel = self.options.fallbackModel, fallbackModel != self.model {
    // 用 fallbackModel 重试...
}

3. 处理 stop_reason

LLM 响应里的 stop_reason 决定了循环的走向：

stop_reason	含义	循环行为
`end_turn`	LLM 说完了	正常退出循环
`stop_sequence`	碰到停止符	正常退出循环
`tool_use`	LLM 想调工具	执行工具，继续循环
`max_tokens`	输出被截断	追加”请继续”，继续循环

max_tokens 的情况有个保护：最多自动续接 3 次，防止无限循环。

4. 工具执行：分桶并发

当 LLM 返回 tool_use 时，SDK 不是简单地把工具排着队一个个跑，而是做了分桶：

// ToolExecutor.partitionTools()
for block in blocks {
    let tool = tools.first { $0.name == block.name }
    if let tool = tool, tool.isReadOnly {
        readOnly.append(item)   // 只读桶
    } else {
        mutations.append(item)  // 变更桶
    }
}

只读工具（Read、Glob、Grep、WebSearch 等）可以安全并发，用 TaskGroup 跑，最多 10 个一批：

let batchResults = await withTaskGroup(of: ToolResult.self) { group in
    for item in batchSlice {
        group.addTask {
            await executeSingleTool(block: item.block, tool: item.tool, context: ...)
        }
    }
    // 收集结果
}

变更工具（Write、Edit、Bash 等）必须串行执行，一个跑完再跑下一个，避免并发写冲突：

for item in items {
    let result = await executeSingleTool(...)
    results.append(result)
}

执行顺序：先跑所有只读工具（并发），再跑所有变更工具（串行）。这在 LLM 一次返回多个工具调用时能显著提升性能——比如 LLM 同时要求读 5 个文件，5 个读操作并行完成。

5. 微压缩

工具执行完后，结果在喂回 LLM 之前还要过一道微压缩：

for result in toolResults {
    let processedContent = await processToolResult(result.content, isError: result.isError)
    processedResults.append(ToolResult(
        toolUseId: result.toolUseId,
        content: processedContent,
        isError: result.isError
    ))
}

如果一个工具返回的内容超过 50000 字符（比如读了一个大文件），SDK 会用一次额外的 LLM 调用把内容压缩。错误结果不压缩——保留了完整的错误信息供 LLM 诊断。

成本追踪：逐 turn 累加

每一轮 LLM 调用后，SDK 都会更新 token 用量和费用：

let turnCost = estimateCost(model: model, usage: turnUsage)
totalCostUsd += turnCost
costByModel[model] = CostBreakdownEntry(
    model: model,
    inputTokens: turnUsage.inputTokens,
    outputTokens: turnUsage.outputTokens,
    costUsd: turnCost
)

costByModel 按 model 分组记录。这意味着如果你中途切换了模型（通过 switchModel()），每个模型的费用是分开计算的。最终 result.costBreakdown 能告诉你每个模型花了多少钱。

预算检查在每个 turn 后执行：

if let budget = options.maxBudgetUsd, totalCostUsd > budget {
    status = .errorMaxBudgetUsd
    break
}

超出预算时立即退出循环，但已产生的文本会保留在结果里——你拿到的是部分结果，不是空白的。

取消：协作式取消

Swift 的结构化并发用 Task.isCancelled 做协作式取消。SDK 在循环的多个检查点都检查了这个标志：

while 循环入口
只读工具和变更工具之间
SSE 事件循环内部
工具执行前后

// 循环入口
if Task.isCancelled || _interrupted {
    status = .cancelled
    break
}

// 只读/变更之间
if Task.isCancelled { return results }

stream() 还额外支持通过 interrupt() 方法取消——内部就是 cancel 掉持有 stream 的 Task。

取消后返回的是 QueryResult(isCancelled: true)，附带截止到取消时刻的部分文本和 token 用量。

错误处理：不炸、不丢

SDK 的错误处理原则是：工具执行错误不传播，API 错误有重试，最终失败保留部分结果。

工具执行时，任何错误都被捕获为 ToolResult(isError: true)：

static func executeSingleTool(...) async -> ToolResult {
    guard let tool = tool else {
        return ToolResult(toolUseId: block.id, content: "Error: Unknown tool", isError: true)
    }
    // ... try executing
    let result = await tool.call(input: block.input, context: context)
    return ToolResult(toolUseId: block.id, content: result.content, isError: result.isError)
}

工具报错的结果照样喂回 LLM，LLM 看到错误信息后可以决定换个策略。Agent Loop 不会因为一个工具挂了就崩溃。

API 层面的错误（网络问题、500 等）会触发重试；重试失败后触发 fallback 模型；全挂了才返回 errorDuringExecution 状态。

Hook 集成：循环的生命周期

Agent Loop 在关键节点触发 Hook 事件：

Hook 事件	触发时机
`sessionStart`	循环开始前
`preToolUse`	每个工具执行前
`postToolUse`	工具成功执行后
`postToolUseFailure`	工具执行失败后
`stop`	循环结束时（正常或异常）
`sessionEnd`	返回结果前

Hook 的一个典型用法是在 preToolUse 拦截危险操作：

await hookRegistry.register(.preToolUse, definition: HookDefinition(
    matcher: "Bash",
    handler: { input in
        return HookOutput(message: "Bash blocked in production", block: true)
    }
))

被 Hook 拦截的工具不会执行，而是返回一个错误结果——LLM 会看到”Bash blocked in production”，可以换个方式完成任务。

还有一个入口：streamInput()

除了 prompt() 和 stream()，SDK 还提供了第三种入口——streamInput()，接受一个 AsyncStream<String> 作为输入：

let input = AsyncStream<String> { continuation in
    continuation.yield("What's in this project?")
    continuation.yield("Now explain the test structure.")
    continuation.finish()
}

for await message in agent.streamInput(input) {
    // 处理每条输入对应的响应
}

每个输入元素被视为一条新的用户消息，触发一个完整的 prompt 周期。这适合聊天式交互：用户的每条消息都是输入流的一个元素，Agent 逐条处理并流式输出。

小结

Agent Loop 是整个 SDK 的心脏。理解了它的工作方式，剩下的功能都是在它的基础上叠加的：

工具系统 — Loop 里的”执行工具”环节
MCP 集成 — Loop 启动时连接外部工具服务器
会话持久化 — Loop 结束后保存 messages 数组
权限控制 — 工具执行前的拦截点
Hook 系统 — Loop 生命周期的事件回调

下一篇我们深入 工具系统：34 个内置工具怎么组织、ToolProtocol 协议的设计思路、以及怎么用 defineTool 创建自定义工具。

系列文章：

第 0 篇：Open Agent SDK (Swift)：用原生 Swift 并发构建 AI Agent 应用
第 1 篇：Agent Loop 内核：从 prompt 到多轮对话的完整运转机制（本文）
第 2 篇：34 个工具的背后：工具协议、三层架构与自定义扩展（下一篇）

GitHub：terryso/open-agent-sdk-swift

CC Live — 实时围观 Claude Code 编程，一键分享你的 AI 编程直播

Mon, 20 Apr 2026 02:00:00 +0000

想看别人是怎么用 Claude Code 写代码的？或者想开一个 AI 编程直播教学？CC Live 就是干这个的。

它是什么

一个单文件 Node.js 服务器，零依赖。启动后把你正在运行的 Claude Code 会话实时推送到浏览器，别人打开链接就能围观你写代码的全过程。

项目地址：github.com/terryso/cc-live

核心功能

实时围观 — 基于 SSE 流式推送，消息、思考过程、工具调用实时可见，跟现场看一样的体验
自动发现项目 — 从 ~/.claude/projects/ 读取所有 Claude Code 项目，侧边栏一目了然
一键分享 — 通过 ngrok / Cloudflare Tunnel 生成带 token 的分享链接，发给任何人围观，随时可撤回
敏感数据脱敏 — 内置 API Key、Token、密码等自动过滤，放心分享
暗色主题 — 适合长时间观看，移动端也能用

快速开始

git clone https://github.com/terryso/cc-live.git
cd cc-live
node server.js
open http://localhost:3456/

然后点分享按钮，把链接发出去就行了。

适用场景

编程直播教学 — 老师用 Claude Code 写代码，学生实时围观思考过程和工具调用
团队围观 — 团队成员可以实时观看 AI 编程过程，学习和 Code Review
AI 编程直播 — 像 Twitch 直播一样，但播的是 AI 写代码

MIT 协议，欢迎 star 和 PR。

Open Agent SDK (Swift)：用原生 Swift 并发构建 AI Agent 应用

Sat, 18 Apr 2026 07:00:00 +0000

如果你是一名 Swift 开发者，想要在自己的 macOS 应用中集成 AI Agent 能力，选择并不多。大多数 Agent 框架都是 Python 或 TypeScript 的，Swift 生态几乎没有成熟的解决方案。Open Agent SDK (Swift) 正是为了填补这个空白而生的。

它是什么？

Open Agent SDK 用 Swift 6.1 编写，要求 macOS 13+。它在进程内跑完整个 Agent Loop：发送提示、解析响应、执行工具调用、把结果喂回 LLM，循环往复直到拿到最终答案。全程用原生 Swift 并发（async/await、AsyncStream）驱动。

项目灵感来自 open-agent-sdk-typescript，把同样的 Agent 架构搬到了 Swift 生态。同系列还有 Go 版本。

快速上手

安装只需在 Package.swift 中添加依赖：

dependencies: [
    .package(url: "https://github.com/terryso/open-agent-sdk-swift.git", from: "0.1.0")
]

几行代码就能跑起一个 Agent：

import OpenAgentSDK

let agent = createAgent(options: AgentOptions(
    apiKey: "sk-...",
    model: "claude-sonnet-4-6",
    systemPrompt: "You are a helpful assistant.",
    maxTurns: 10
))

let result = await agent.prompt("Explain Swift concurrency in one paragraph.")
print(result.text)
print("Used \(result.usage.inputTokens) input + \(result.usage.outputTokens) output tokens")

prompt() 是阻塞式的，一次调用完成整个 Agent Loop。如果需要流式输出，用 stream()：

for await message in agent.stream("Read Package.swift and summarize it.") {
    switch message {
    case .partialMessage(let data):
        print(data.text, terminator: "")
    case .toolUse(let data):
        print("Using tool: \(data.toolName)")
    case .result(let data):
        print("\nDone (\(data.numTurns) turns, $\(String(format: "%.4f", data.totalCostUsd)))")
    default:
        break
    }
}

核心架构

你的应用 (import OpenAgentSDK)
  └── Agent (prompt() / stream())
        └── Agentic Loop (API 调用 → 工具执行 → 重复)
              ├── LLMClient Protocol (AnthropicClient / OpenAIClient)
              ├── 34 个内置工具
              ├── MCP 服务器集成
              ├── Session Store (JSON 持久化)
              └── Hook Registry (20+ 生命周期事件)

LLMClient Protocol：抽象了 LLM 提供商，目前支持 Anthropic (Claude) 和 OpenAI 兼容 API（GLM、Ollama、OpenRouter 等）。支持运行时动态切换模型，按模型分别计费。
Agent Loop：自动管理多轮对话、工具调用、预算控制、自动压缩。
Tool System：34 个内置工具，分 Core（10 个）、Advanced（11 个）、Specialist（13 个）三层。支持 defineTool() 自定义工具，输入走 Codable 自动解码。
MCP 集成：支持 stdio、SSE、HTTP 和进程内四种传输方式，MCP 工具自动发现并合并到工具池。
多 Agent 协作：通过 AgentTool 生成子 Agent（内置 Explore、Plan 两种类型），Task 系统追踪任务进度，Team + Mailbox 支持 Agent 间通信。
会话持久化：对话历史保存、恢复、分叉，支持三种恢复策略。
权限与安全：6 种权限模式 + 可组合的策略（白名单、黑名单、只读）+ 沙盒机制（路径和命令过滤）+ Hook 系统（24 个生命周期事件，支持拦截和修改工具输入）。
Skills 系统：5 个内置 Skill（Commit、Review、Simplify、Debug、Test），支持文件系统自动发现自定义 Skill。
Thinking/Effort 配置：控制 LLM 深度思考能力和 token 预算，支持运行时动态调节。

项目状态

SDK 附带 31 个示例项目，覆盖基本用法、流式输出、自定义工具、MCP 集成、会话管理、多 Agent 协作、权限控制、沙盒、模型切换等场景。代码分为 API、Core、Hooks、MCP、Skills、Stores、Tools、Types、Utils 九个模块，约 90 个 Swift 源文件，MIT 许可证。

本系列后续文章会逐一深入每个子系统的实现细节。

深入 Open Agent SDK 系列文章：

第 0 篇：Open Agent SDK (Swift)：用原生 Swift 并发构建 AI Agent 应用（本文）
第 1 篇：Agent Loop 内核：从 prompt 到多轮对话的完整运转机制
第 2 篇：34 个工具的背后：工具协议、三层架构与自定义扩展
第 3 篇：MCP 集成实战：让 Agent 连接万物
第 4 篇：多 Agent 协作：子代理、团队与任务编排
第 5 篇：会话持久化与安全防线
第 6 篇：多 LLM 提供商与运行时控制

GitHub：terryso/open-agent-sdk-swift

优化的黄金标准：深入剖析《过山车大亨》的技术内幕

Mon, 23 Mar 2026 02:56:07 +0000

本文翻译自 The gold standard of optimization: A look under the hood of RollerCoaster Tycoon，原载于 Hacker News。

最近有幸参加了德国最大的游戏播客之一「Stay Forever」，聊了聊《过山车大亨》（RollerCoaster Tycoon，1999）的技术实现。这是一次很棒的访谈，强烈推荐德语听众去听听完整节目。

《过山车大亨》及其续作经常被 cited 为史上优化最好的游戏之一——由 Chris Sawyer 几乎完全用汇编语言（Assembly）编写。这款游戏在 1999 年的硬件上，居然能流畅模拟拥有数千个游客的完整主题公园，着实令人惊叹。要知道，即使到了今天，很多类似的建造类游戏仍然难以保持稳定的帧率。

那么，Chris Sawyer 究竟是如何做到的？

使用汇编语言

最常被提到的原因是游戏用汇编语言编写。在游戏开发早期，汇编语言是标准做法，但到了 1999 年，这已经是一种几乎被放弃的实践。即使比它早六年发布的初代《毁灭战士》（Doom），大部分代码也已经是用 C 语言编写，只有少数关键部分使用汇编。

虽然很难确定，但《过山车大亨》很可能是最后一款大规模使用汇编开发的商业游戏。在当时，使用汇编带来的性能提升可能比现在更显著——现代编译器已经非常擅长优化高级语言代码，许多当年需要手动完成的优化，现在编译器都能自动处理。

金钱的类型设计

你会如何在游戏中存储金钱数值？通常的做法是考虑游戏中可能需要的最大金额，然后选择合适的数据类型。Chris Sawyer 的做法更加精细：

存储公园总价值的变量使用 4 字节（因为公园价值可能达到很高的数字）
商店商品的可调价格？只需要 1 字节就够了

这种精细的类型选择在 OpenRCT2（开源重制版）中已经被移除，改为统一使用 8 字节变量——因为现代 CPU 上这已经不会造成性能差异了。

用位运算替代数学运算

在阅读 OpenRCT2 的源码时，你会频繁看到这样的语法：

value = value << 2;

这行代码做的事情和大多数人会写的 value = value * 4; 是一样的。<< 操作符执行的是位左移，把变量的所有二进制位向左移动两位，新位置用零填充。在二进制系统中，每左移一位就相当于数值翻倍。

这个技巧听起来可能有点技术宅，但其实我们在十进制中也在做类似的事情。当你计算 57 × 10 时，你是真的在「计算」乘法吗？还是直接在 57 后面加个 0？同样的原理，只是进制不同。

同样的技巧也可以用于除法：

value = value >> 1;  // 相当于 value = value / 2;

《过山车大亨》到处都在用这个技巧，即使是 OpenRCT2 版本也保留了这种写法，因为编译器不会自动做这种优化。

更有趣的是，位运算只能用于 2 的幂次方的乘除法（如 2、4、8、16 等）。代码中频繁使用这种技巧说明：游戏内的公式是专门设计成尽可能使用这些数字的。

在现代开发流程中，这几乎是不可能的。想象一下，程序员去问游戏设计师：「能不能把公式里的 9.5 改成 8？因为 CPU 更喜欢计算这个数字。」在大多数公司，游戏设计师一辈子都不应该担心二进制算术的运行时性能特性——那是程序员的事。但《过山车大亨》的游戏设计师和程序员是同一个人。

为性能而生的游戏设计

《过山车大亨》并不完全是一个「单人项目」——游戏的图形由 Simon Foster 创作，音效由 Allister Brimble 负责。但 Chris Sawyer 既是主程序员，也是唯一的游戏设计师。

这种角色的重叠使得一种深层次的优化成为可能：根据性能特征来设计游戏机制。

路径寻找的巧妙设计

一个绝佳的例子是游戏中的寻路系统（pathfinding）。

在设计公园建造游戏的文档时，很容易设计出这样的方案：游客先决定想去哪个景点（基于个人偏好），然后找到前往该景点的路径。

但从技术角度来看，这设计简直是性能噩梦。寻路是一项昂贵的计算任务，同时为数千个智能体运行寻路算法，即使在现代机器上也是令人头疼的挑战。

所以，《过山车大亨》的游客行为从根本上就不同：

游客不是先选择目标再找路，而是「盲目」地在公园里闲逛，等待偶然发现有趣的游乐设施。 他们沿着当前路径走，根本不考虑游乐设施或需求。当到达岔路口时，他们几乎是随机选择新的方向，只使用极少量的额外规则来避免死胡同等。

在游戏中仔细观察一个游客，你很容易发现这个「缺陷」：他们走路毫无目的。即使抱怨又饿又渴，他们也不会主动寻找最近的食物摊位，而是继续闲逛直到偶然经过一个。

当然，《过山车大亨》并非完全不做寻路。有些情况仍然需要传统寻路：

维修工需要到达损坏的游乐设施
游客想要离开公园

但即使在这些情况下，游戏也有安全网来避免帧率骤降。最重要的是，寻路器有一个内置的搜索深度限制。如果在达到限制前还没找到路径，寻路器可以直接取消搜索并返回失败。

作为玩家，你可以实时看到寻路失败——通过阅读游客的想法：

没错，每当游客抱怨找不到出口，本质上就是寻路器在说：「可能存在一条路径，但为了性能，我就不再继续找了。」

这部分让我特别着迷：它把出于技术必要性所做的优化，变成了一个游戏特性。在现代游戏开发中，这种事情几乎不可能发生，因为程序员和游戏设计师的角色是严格分离的。

更妙的是，还有更多游戏系统与之关联：

默认情况下，寻路器最多遍历 5 个岔路口的深度
维修工比普通游客更重要，所以他们可以搜索 8 个岔路口的深度
如果游客买了公园地图（在信息亭出售），他们的寻路限制会从 5 增加到 7

拥挤但不拥堵

另一个例子是《过山车大亨》如何处理拥挤的公园。

拥挤的道路在每个主题公园都很常见，游戏显然也需要处理这种情况。但显而易见的解决方案——实现某种智能体碰撞或避让系统——对帧率的伤害就像氪石对超人的伤害一样大。

解决方案？直接绕过这个技术挑战。

《过山车大亨》中的游客不会互相碰撞，也不会互相避让。实际上，数千名游客可以同时占据同一个路径格子：

当然，这并不意味着玩家不需要考虑拥挤问题。虽然游客不会与周围的其他游客互动，但他们会「感知」到周围的人数。如果附近有太多其他游客，这会影响他们的快乐度并触发对玩家的抱怨。对玩家来说，结果是一样的——他们仍然需要规划布局来避免过于拥挤的道路。但这种实现方式所需的计算量要小几个数量级。

启示与总结

《过山车大亨》可能是这种特定优化方法的「完美风暴」，但这并不意味着现在不能这样做。它只是需要程序员和游戏设计师之间更多的对话，以及面对技术挑战时说「不」的勇气。

这篇文章给我们的启示：

极致优化需要全栈思维：Chris Sawyer 既是程序员又是设计师，这种角色重叠使得性能优化可以深入到游戏设计层面，而不仅仅是代码层面。
有时最好的优化是重新设计问题：不是解决「如何高效地为数千人做寻路」，而是问「我们真的需要寻路吗？」
技术限制可以变成游戏特性：游客找不到出口的抱怨，本质上是性能优化的副作用，但它增加了游戏的真实感和挑战性。
现代开发流程的权衡：角色分工虽然提高了效率，但也失去了这种深度优化的可能性。也许在某些项目中，值得重新思考这种分工。
编译器的进步：当年需要手动做的许多优化，现代编译器已经能自动处理。但有些优化（如位运算替代乘除）编译器仍然不会自动做，因为会影响边界情况的处理。

如果你对游戏开发技术感兴趣，强烈推荐去看看 OpenRCT2 的源码，它是了解这款传奇游戏技术实现的绝佳窗口。

Manyana：基于 CRDT 的版本控制未来

Mon, 23 Mar 2026 01:54:19 +0000

本文翻译自 Manyana，原载于 Hacker News。

Bram Cohen（BitTorrent 发明者）最近发布了一个名为 Manyana 的项目，展示了一个关于版本控制未来的一致性愿景——以及一个令人信服的实现理由。

CRDT 与版本控制：迟来的结合

Manyana 的核心理念是使用 CRDT（Conflict-Free Replicated Data Types，无冲突复制数据类型） 来实现版本控制。这个方向在技术上一直被认为是正确的，但因为一些微妙的 UX 问题，至今没有被主流工具采用。

CRDT 的关键特性是：合并永远不会失败。传统意义上不存在”冲突”——关键洞察在于，当两个改动”相互触碰”时，系统应该将这些改动标记为冲突状态，但合并操作本身永远成功。这让你可以在一个永不失败的系统之上，获得有意义的冲突呈现。

更智能的冲突标记

来看一个具体例子。两个人从同一个文件分支：

甲删除了一个函数
乙在这个函数中间添加了一行代码

传统 VCS 给你的是这样的冲突标记：

<<<<<<< left
=======
def calculate(x):
a = x * 2
logger.debug(f"a={a}")
b = a + 1
return b
>>>>>>> right

两块不透明的代码块。你需要脑补还原到底发生了什么。

Manyana 给你的是：

<<<<<<< begin deleted left
def calculate(x):
a = x * 2
======= begin added right
logger.debug(f"a={a}")
======= begin deleted left
b = a + 1
return b
>>>>>>> end conflict

每一部分都告诉你 发生了什么 和 谁做的。左边删除了函数，右边在中间添加了一行。你可以看到冲突的结构，而不是盯着两块代码发呆。

CRDT 带来的深层改变

CRDT 提供了最终一致性：合并永不失败，而且无论以什么顺序合并分支——包括多个人独立工作的多个分支混在一起——结果始终相同。这个属性对版本控制设计的每个方面都有深远影响。

行顺序永久确定。当两个分支在同一点插入代码时，CRDT 选择一个顺序并固定下来。这解决了冲突部分被保留但在不同分支上以不同顺序解决的问题。

冲突是信息性的，不是阻塞性的。合并总是产生结果。当并发编辑发生在”太近”的地方时，冲突会被标记出来供审查，但它们从不阻塞合并本身。而且因为算法追踪的是 每一边做了什么，而不仅仅是展示两个结果，冲突呈现真正有用。

历史存在于结构中。状态是一个 weave——一个包含文件中曾经存在的每一行的单一结构，带有何时添加和删除的元数据。这意味着合并不需要寻找共同祖先或遍历 DAG。两个状态进去，一个状态出来，永远正确。

Rebase 不必销毁历史

Bram 特别兴奋的一个想法：rebase 不必销毁历史。

传统的 rebase 创造一个虚构的历史，假装你的提交发生在最新的 main 之上。在 CRDT 系统中，你可以获得相同的效果——一次一个地在新基础上重放提交——同时保留完整历史。唯一需要的是在 DAG 中添加一个”主要祖先”注解。

这很重要，因为激进的 rebase 很快会产生没有单一共同祖先的合并拓扑，而这恰恰是传统三路合并崩溃的地方。CRDT 不在乎——历史在 weave 中，不是从 DAG 重建的。

项目现状

Manyana 目前是一个 demo，不是完整的版本控制系统。它大约 470 行 Python 代码，操作单个文件。Cherry-pick 和本地 undo 还没实现，但 README 中已经规划了如何优雅地实现它们。

但它证明了：基于 CRDT 的版本控制可以处理棘手的 UX 问题，并给出比我们今天使用的工具更好的答案——以及一个构建真正系统的连贯设计。

代码是公共领域的。完整的设计文档在 README 中。

个人思考

CRDT 在分布式系统领域已经相当成熟（被用于 Redis、Apple Notes、Figma 等产品），但在版本控制领域一直没有突破性的实践。Manyana 的价值在于它不仅讨论了技术可行性，还深入解决了”冲突呈现”这个真正影响开发者体验的问题。

如果这个方向能够发展成熟，我们可能会看到一个真正挑战 Git 的新一代版本控制系统。Git 的三路合并 + 基于文本的冲突标记确实是 2005 年设计的产物，是时候重新思考了。

关键要点：

CRDT 让合并永不失败，冲突只是信息性标记
新的冲突呈现方式让你看到”谁做了什么”，而不是两块代码
Rebase 可以保留完整历史，不需要销毁真相
历史存在于 weave 结构中，合并不需要共同祖先

Flash-MoE：在笔记本上运行 397B 参数大模型

Sun, 22 Mar 2026 13:47:03 +0000

本文翻译自 Flash-MoE: Running a 397B Parameter Model on a Laptop，原载于 Hacker News。

惊人的壮举

想象一下：在一台普通的笔记本电脑上运行一个 3970 亿参数 的大语言模型，而且能以每秒 4.4 个 token 的速度生成文本。这不是科幻小说，这是 Flash-MoE 项目的真实成果。

Flash-MoE 是一个纯 C/Metal 推理引擎，它可以在配备 48GB 内存的 MacBook Pro 上运行 Qwen3.5-397B-A17B（一个 397B 参数的 Mixture-of-Experts 模型），达到 4.4+ tokens/秒 的推理速度，并且支持完整的工具调用（tool calling）功能。

整个 209GB 的模型通过自定义的 Metal 计算管道从 SSD 流式加载。没有 Python，没有框架，只有 C、Objective-C 和手工优化的 Metal 着色器。

性能表现

配置	tok/s	质量	备注
4-bit experts, FMA kernel	4.36	优秀	当前最佳配置。完整工具调用支持。磁盘占用 209GB。
4-bit experts, baseline	3.90	优秀	FMA kernel 优化前的版本。
2-bit experts, trust OS	5.74	良好*	磁盘占用 120GB。*会破坏 JSON/工具调用。
2-bit peak single token	7.05	良好*	热缓存峰值。*不适合工具使用。

2-bit 量化会在 JSON 输出中产生 \name\ 而不是 "name"，导致工具调用不可靠。4-bit 是生产环境推荐配置。

硬件配置

这项成就的硬件基础是一台 MacBook Pro：

机器：MacBook Pro, Apple M3 Max
芯片：16 核 CPU（12P + 4E），40 核 GPU，16 核 ANE
内存：48 GB 统一内存（约 400 GB/s 带宽）
SSD：1TB Apple Fabric，实测 17.5 GB/s 顺序读取
macOS：26.2 (Darwin 25.2.0)

模型架构

该模型包含 60 个 transformer 层：45 个 GatedDeltaNet（线性注意力）+ 15 个标准全注意力层。每层有 512 个专家（experts），每个 token 激活 K=4 个专家（外加一个共享专家）。隐藏维度为 4096。

核心技术

1. SSD 专家流式加载（SSD Expert Streaming）

专家权重（4-bit 下 209GB）通过并行 pread() 和 GCD dispatch groups 从 NVMe SSD 按需读取。每层只有 K=4 个活跃专家被加载（每个约 6.75MB）。操作系统页面缓存管理所有缓存——不需要自定义缓存（”Trust the OS” 原则）。这个设计灵感来自 Apple 的 “LLM in a Flash” 论文。

2. FMA 优化的反量化内核（FMA-Optimized Dequant Kernel）

4-bit 反量化矩阵-向量乘法的内循环将数学运算从 (nibble * scale + bias) * x 重排为 fma(nibble, scale*x, bias*x)。预先计算 scale*x 和 bias*x 让 GPU 的融合乘加单元（FMA）在一条指令中完成反量化和乘法。比原始实现快 12%。

3. Metal 计算着色器

手工编写的 Metal 内核包括：

4-bit 和 2-bit 反量化矩阵-向量乘法（分块、SIMD 约简、共享输入缓存、FMA 优化）
融合 SwiGLU 激活
RMS 归一化（两遍：平方和约简 + 应用）
批量 GPU 注意力（Q@K^T, softmax, scores@V）用于全注意力层
GPU RoPE（与 Q 解交织和 K 归一化融合）
MoE combine + residual + sigmoid gate（融合内核）

4. 延迟 GPU 专家计算

CMD3（专家前向传播）被提交但不等待。GPU 执行它的同时 CPU 准备下一层。combine + residual + norm 也在 GPU 上，直接馈入下一层的注意力投影。

5. Accelerate BLAS 用于线性注意力

GatedDeltaNet 递归使用 cblas_sscal、cblas_sgemv 和 cblas_sger 进行 64 头 × 128×128 状态矩阵更新。比标量代码快 64%。

6. 信任操作系统（Trust the OS）

没有自定义专家缓存。操作系统页面缓存（约 35GB）通过标准 LRU 管理专家数据缓存。我们测试的每种自定义缓存方法（Metal LRU、malloc 缓存、LZ4 压缩缓存）都因为 GPU 内存压力或开销而更慢。页面缓存自然达到约 71% 的命中率。

每层流水线（4-bit 平均 4.28ms）

CMD3(prev) → CMD1: attention projections + delta-net  [1.22ms GPU]
           → CPU: flush results                       [0.01ms CPU]
           → CMD2: o_proj + norm + routing + shared    [0.55ms GPU]
           → CPU: softmax + topK routing               [0.003ms]
           → I/O: parallel pread K=4 experts           [2.41ms SSD]
           → CMD3: expert forward + combine + norm     [0.04ms encode, DEFERRED]

统一内存约束

在 Apple Silicon 上，SSD DMA 和 GPU 计算共享同一内存控制器，无法有效重叠。GPU 的反量化内核在约 418 GiB/s 时达到带宽饱和。即使很小的后台 SSD DMA 也会通过内存控制器仲裁导致不成比例的 GPU 延迟峰值。串行流水线（GPU → SSD → GPU）是硬件最优的。

快速开始

cd metal_infer
make
# 4-bit 推理（需要 packed_experts/ 目录）
./infer --prompt "Explain quantum computing" --tokens 100

# 2-bit 推理（更快但会破坏工具调用）
./infer --prompt "Explain quantum computing" --tokens 100 --2bit

# 带工具调用的交互式聊天
./chat

# 每层时间分解
./infer --prompt "Hello" --tokens 20 --timing

项目结构

metal_infer/
  infer.m              # 完整推理引擎（约 7000 行）
  shaders.metal        # Metal 计算内核（约 1200 行）
  chat.m               # 带工具调用的交互式聊天 TUI
  tokenizer.h          # C BPE tokenizer（单头文件，449 行）
  main.m               # MoE 基准测试
  Makefile             # 构建系统
  extract_weights.py   # 从 safetensors 创建 model_weights.bin
  repack_experts_2bit.py  # 4-bit → 2-bit 专家重量化

我们尝试过的方法（及其效果）

保留的优化

方法	结果	影响
FMA dequant kernel	GPU 计算 -12%	+12% tok/s
信任 OS 页面缓存	删除 Metal LRU → +38%	基础性改进
GPU combine+norm in CMD3	消除 CPU 往返	流水线优化
BLAS delta-net (Accelerate)	cpu_attn 0.78→0.28ms	+64% attention
F_NOCACHE for 2-bit	+3%（避免页面抖动）	仅限 2-bit
GPU fused attention (RoPE)	全注意力层 +2%	小幅提升
C BPE tokenizer	180ms vs 3500ms 启动	20x 启动速度
Deferred CMD3 execution	GPU/CPU 重叠	流水线优化

舍弃的方法（58 个实验中的亮点）

方法	结果	原因
LZ4 专家压缩	-13%	解压开销 > 热缓存节省
F_RDADVISE 预取	净 0%	统一内存：SSD DMA 使 GPU 变慢 -73%
时序专家预测	-18%	25% 命中率，SSD 带宽浪费
MLP 路由预测器	31% 准确率	比时序基准更差
GPU LUT dequant kernel	-2%	间接寄存器访问序列化
dispatch_io	-70%	dispatch_data 管理开销
mmap 专家文件	-5x	冷数据上的每页故障开销
MTP 推测解码	持平	MoE I/O 按 token 扩展（与密集模型不同）

内存安全

这是一台主要开发机器。引擎明确控制内存：

非专家权重：5.5GB（mmap’d，只读）
Metal 临时缓冲区：约 200MB
总计：约 6GB，为 OS + 页面缓存留出 42GB
无 OOM 风险。专家数据按需从 SSD 流式加载。
没有自定义缓存。信任操作系统。

我的思考

这个项目展示了几个非常有趣的设计理念：

“Trust the OS” - 作者尝试了多种自定义缓存策略，最终发现操作系统的页面缓存效果最好。这是一个很好的提醒：有时候最简单的方案就是最优解。
纯 C/Metal 实现 - 在当今 Python 和各种框架盛行的时代，作者选择从头用 C 和 Metal 实现，最终获得了极致的性能。这让我想起了早期程序员的精神。
SSD 作为扩展内存 - 通过流式加载，209GB 的模型可以在 48GB 内存的机器上运行。这种思路对于资源受限的开发者来说非常有价值。
统一内存的双刃剑 - Apple Silicon 的统一内存架构既是优势（高带宽），也是限制（SSD DMA 和 GPU 计算不能并行）。作者深入理解硬件特性后做出了正确的串行流水线设计。

对于想要在本地运行大模型的开发者来说，这个项目提供了宝贵的参考。虽然 48GB 内存的 M3 Max MacBook Pro 仍然是高端设备，但相比于专业 GPU 服务器，这已经是触手可及的消费级硬件了。

关键要点

🚀 397B 模型，48GB 内存 - 通过 SSD 流式加载实现
⚡ 4.4+ tok/s - 生产质量的推理速度
🔧 完整工具调用支持 - 4-bit 量化配置
💡 Trust the OS - 操作系统页面缓存比自定义缓存更高效
🛠️ 纯 C/Metal - 无 Python、无框架的极致优化

有些事情，就是急不来

Sun, 22 Mar 2026 11:43:05 +0000

本文翻译自 Some Things Just Take Time，原载于 Hacker News。

树木的生长需要漫长的时间。如果有人在 50 年前在你的土地上种下了一排橡树或一棵栗树，你今天拥有的，是无论多少金钱或努力都无法复制的东西。唯一的办法就是等待。林荫大道、古老花园、被几十年树冠庇护的房屋——如果你想在一块空地上从零开始，你永远无法获得这些。

因为，有些事情就是需要时间。

这一点我们心知肚明。我们愿意为瑞士手表、爱马仕包袋和老房子支付溢价，正是因为它们身上沉淀着时间——要么是制作它们所耗费的时间，要么是它们本身的年代感。我们对驾驶、投票、饮酒设定年龄限制，因为我们相信成熟只能通过生活阅历获得。

然而，当下的我们也生活在一个即时满足的时代，这种心态正在渗透到我们构建软件和公司的方式中。无论代码生成可以加速多少，一家成功的公司或一个开源项目真正的决定性因素，仍然是韧性（tenacity）。是领导层或维护者数年如一日地坚持解决一个问题、建立关系、处理那些根本上由人类生命周期定义的挑战的能力。

摩擦是好事

当下的创业者和程序员群体对速度有着近乎偏执的追求。快速迭代、敏捷部署，一切都要尽可能快。对于很多事情来说，这没问题。你可以追求速度，在质量上有所妥协，并在过程中学到一些东西。

但有些事情，速度不仅无益，反而有害——摩擦的存在是有原因的。合规（Compliance）就是其中之一。如今有一种强烈的冲动想要消除 SOC2 等流程所要求的一切，整个行业都涌现出”交钥匙”解决方案来帮助实现这一点——Delve 只是其中一例，还有更多。

人们有种感觉：生活中所有制造摩擦的东西都应该被自动化掉。人工参与应该被基于 AI 的决策取代。因为摩擦似乎就是问题的根源。

但事实上，很多时候，摩擦，或者说事情就是需要时间，恰恰是意义所在。

我们在生活中的一些重要决定上设置”冷静期”是有原因的。我们认识到人们需要时间来思考自己在做什么，而一次性做对某事并不意味着什么——你需要能够在更长的时间跨度上持续做对。

推理速度下的「氛围垃圾」

AI 写代码很快，这已经不是新闻了。有趣的是，我们正在把这种力量向下传导：我们似乎有一种前所未有的渴望要更快地发布、运行更多实验，这催生了一种新的欲望——消除所有剩余的摩擦，无论是代码审查、设计还是基础设施配置，任何拖慢流水线的东西。既然机器这么强大，为什么我们还需要检查清单或权限系统？表达欲望，享受结果。

因为我们现在相信，一切都要更快。

但我越来越觉得，这意味着当今大量正在被创造的软件——那些人和企业应该依赖的软件——的保质期只能用月来衡量，而不是十年；与此同时，各种关系也是如此。

在去年早些时候的 YC 批次中，已经有一小批项目直接消失了，甚至没有说明他们学到了什么，也没有向客户道别。他们只是关闭了公开存在，转向其他事情。在我看来，这不是健康迭代的标志。这是破坏与客户建立关系所需的基本信任的标志。一个体面的关闭需要时间和精力，而我们当下的环境将其视为不值得花费的时间。最好直接转向下一件事。

这种现象也延伸到了开源项目。突然间，一切都成了”开源项目”，但其中许多只有一周左右的提交，然后就消失了，因为创作者的动力已经消退。以实验的名义，这无可厚非，但一个好的开源项目的标志是：你认为并真正相信创建者要么会长期坚持，要么能够制定继任策略，要么已经建立了足够强大的社区，使这些项目能够以某种形式经受住时间的考验。

我的时间

与此相关的是，我也越来越对任何声称能”节省我时间”的东西持怀疑态度。当我看到的是，每个像我一样、完全拥抱 AI 和代理工具的人，似乎可用的时间越来越少——因为我们掉进了一个陷阱，立刻用更多的事情填满它。

我们互相兜售”节省时间”的理念，但这并非正在发生的事情。任何节省下来的时间都会立刻被竞争捕获。一个真正停下来喘口气的人，会被一个用新产出填满每一个空闲小时的人超越。没有简单的方法来”存储”时间，它就这样消失了。

我对此感受强烈。我非常接近 AI 经济活动的”红热中心”，而最重要的是，我的时间越来越少，即使我试图有意识地缩减并创造空间。对我来说，这是一个问题。这是一个问题，因为即使有最好的意图，我发现当我们快速将软件商品化、而机器又如此诱人时，我实际上很难创造质量。

我不断回到树木的比喻。我维护开源项目已经接近二十年了。我参与的最后一家创业公司，我在那里待了 10 年。这并不是因为我特别自律或高尚。而是因为我或其他人种下了一些东西，然后我持续出现，最终，这个东西有了比我任何一天的热情更深根。这就是时间的作用！ 它把某个想法或计划变成承诺，把承诺变成可以庇护和滋养他人的东西。

没有人能大规模生产一棵 50 岁的橡树。也没有人能在一个周末冲刺中变出信任、质量或社区。我最珍视的东西——项目、关系、社区——都是经过多年才成为今天的样子。没有任何工具，无论多快，能让它们更早到达。

我们最近和 Colin 一起种了一棵新树。我希望它长成一棵大树。我知道这需要时间，而我不着急。

核心观点总结

时间是无可替代的：就像树木需要几十年才能成材，信任、质量和社区也无法通过工具加速获得。
摩擦有其价值：合规流程、冷却期等「摩擦」不是效率的敌人，而是确保质量和深思熟虑的机制。
速度的陷阱：AI 时代追求的「节省时间」往往是错觉——节省下来的时间会被竞争立即占据，真正重要的是如何分配注意力。
坚持的力量：开源项目和创业公司成功的核心不是技术速度，而是持续出现（showing up）的坚韧。
给中国开发者的启示：在追逐 AI 辅助编程的热潮中，别忘了那些真正有价值的东西——深度学习、长期关系、技术积累——都需要时间的沉淀。

作者 Armin Ronacher 是 Flask、Jinja2 等知名 Python 项目的创造者，在开源社区有近二十年的深耕经验。

JavaScript 膨胀的三大支柱

Sun, 22 Mar 2026 10:39:54 +0000

本文翻译自 The Three Pillars of JavaScript Bloat，原载于 Hacker News。

在过去的几年里，我们见证了 e18e 社区的显著成长，以及随之而来的性能导向贡献的增加。其中一个重要组成部分是”清理”（cleanup）倡议——社区在持续修剪那些冗余、过时或无人维护的包。

在这个过程中，最常被提及的话题之一就是”依赖膨胀”（dependency bloat）——即 npm 依赖树随时间变得越来越大，其中充斥着平台早已原生支持的冗余代码。

在这篇文章中，我想简要探讨我认为依赖树中存在的三种主要膨胀类型，分析它们存在的原因，以及我们如何开始解决这些问题。

1. 旧运行时支持（及安全性与跨 Realm 问题）

上面的图在许多 npm 依赖树中非常常见——一个看似应该原生可用的小工具函数，后面跟着许多类似的小型深层依赖。

那么，为什么会存在这种情况？为什么我们需要 is-string 而不是直接用 typeof 检查？为什么需要 hasown 而不是 Object.hasOwn（或 Object.prototype.hasOwnProperty）？原因有三：

对非常旧引擎的支持
防止全局命名空间被篡改
跨 Realm 值的处理

对非常旧引擎的支持

在这个世界上，确实有一些人需要支持 ES3——想想 IE6/7，或者极早期版本的 Node.js。

对于这些人来说，我们今天习以为常的很多东西根本不存在。例如，他们没有以下任何一个：

Array.prototype.forEach
Array.prototype.reduce
Object.keys
Object.defineProperty

这些都是 ES5 特性，意味着它们在 ES3 引擎中根本不存在。

对于那些仍然运行旧引擎的不幸者，他们需要自己重新实现一切，或者依赖 polyfill。

当然，更好的选择是——升级。

防止全局命名空间被篡改

这些包存在的第二个原因是”安全性”。

基本上，在 Node.js 内部有一个”primordials”的概念。这些本质上是在启动时包装的全局对象，Node 从那时起导入它们，以避免 Node 本身被某人篡改全局命名空间而破坏。

例如，如果 Node 本身使用 Map，而我们重新定义了 Map 是什么——我们就能破坏 Node。为了避免这种情况，Node 保留了对原始 Map 的引用，它导入这个引用而不是访问全局对象。

你可以在 Node 仓库中了解更多相关内容。

这对于引擎来说非常有道理，因为它不应该因为脚本搞乱了全局命名空间而崩溃。

一些维护者也认为这也是构建包的正确方式。这就是为什么我们在上面的图中看到 math-intrinsics 这样的依赖——它基本上重新导出各种 Math.* 函数以避免被篡改。

跨 Realm 值

最后，我们有跨 Realm 值的问题。这些基本上是你从一个 Realm 传递到另一个 Realm 的值——例如，从网页传递到子 <iframe> 或反之。

在这种情况下，在 iframe 中 new RegExp(pattern) 创建的正则表达式，与父页面中的 RegExp 类不是同一个。这意味着 window.RegExp !== iframeWindow.RegExp，当然也就意味着如果值来自 iframe（另一个 Realm），val instanceof RegExp 将返回 false。

举个例子，我是 chai 的维护者，我们就遇到了这个问题。我们需要支持跨 Realm 的断言（因为测试运行器可能在 VM 或 iframe 中运行测试），所以我们不能依赖 instanceof 检查。因此，我们使用 Object.prototype.toString.call(val) === '[object RegExp]' 来检查某物是否是正则表达式，这在跨 Realm 时有效，因为它不依赖于构造函数。

在上面的图中，is-string 基本上在做同样的工作，以防我们从另一个 Realm 传递 new String(val)。

为什么这是个问题

所有这些对于极小的一群人来说是有意义的。如果你需要支持非常旧的引擎、跨 Realm 传递值，或者想要防止环境被篡改的保护——这些包正是你需要的。

问题在于，我们绝大多数人根本不需要这些。我们运行的是过去 10 年内的 Node.js 版本，或者使用自动更新的浏览器。我们不需要支持 ES5 之前的环境，我们不在 frame 之间传递值，我们会卸载那些破坏环境的包。

这些小众的兼容性层 somehow 进入了日常包的”热路径”。真正需要这些东西的一小群人应该是去寻找特殊包的人。然而，情况是反过来的——我们所有人都在付出代价。

2. 原子化架构

有些人认为包应该被拆分到几乎原子的级别，创建一组小的构建块，之后可以重新用来构建其他更高层次的东西。

这种架构意味着我们最终会得到这样的图：

如你所见，最细粒度的代码片段都有自己的包。例如，在写这篇文章时，shebang-regex 的内容如下：

const shebangRegex = /^#!(.*)/;
export default shebangRegex;

通过将代码拆分到这种原子级别，理论上我们可以简单地通过连接这些点来创建更高层次的包。

一些原子包的例子，让你感受一下这种粒度：

arrify - 将值转换为数组（Array.isArray(val) ? val : [val]）
slash - 将文件系统路径中的反斜杠替换为 /
cli-boxes - 一个包含盒子边缘的 JSON 文件
path-key - 获取当前平台的 PATH 环境变量键（Unix 上是 PATH，Windows 上是 Path）
onetime - 确保函数只被调用一次
is-wsl - 检查 process.platform 是否为 linux 且 os.release() 包含 microsoft
is-windows - 检查 process.platform 是否为 win32

如果我们想构建一个新的 CLI，可以拉入几个这样的包而不用担心实现。我们不需要自己写 env['PATH'] || env['Path']，可以直接拉一个包来处理。

为什么这是个问题

实际上，大多数或所有这些包并没有成为它们本该成为的可重用构建块。它们要么在更广泛的树中大量重复（各种版本），要么是只有一个其他包使用的单用途包。

单用途包

让我们看看一些最细粒度的包：

shebang-regex 几乎只被同一维护者的 shebang-command 使用
cli-boxes 几乎只被同一维护者的 boxen 和 ink 使用
onetime 几乎只被同一维护者的 restore-cursor 使用

这些每个都只有一个消费者，意味着它们相当于内联代码，但获取成本更高（npm 请求、tar 解压、带宽等）。

重复

看看 nuxt 的依赖树，我们可以看到一些这样的构建块被重复：

is-docker（2 个版本）
is-stream（2 个版本）
is-wsl（2 个版本）
isexe（2 个版本）
npm-run-path（2 个版本）
path-key（2 个版本）
path-scurry（2 个版本）

内联它们并不意味着我们不再重复代码，但确实意味着我们不需要支付版本解析、冲突、获取成本等代价。

内联使重复几乎免费，而打包使其变得昂贵。

更大的供应链攻击面

我们拥有的包越多，供应链攻击面就越大。每个包都是维护、安全等方面的潜在故障点。

例如，去年这些包的许多维护者被入侵了。这意味着数百个小型构建块被入侵，进而意味着我们实际安装的高层次包也被入侵了。

像 Array.isArray(val) ? val : [val] 这样简单的逻辑可能不需要自己的包、安全审查、维护等。它可以直接内联，我们可以避免被入侵的风险。

与第一个支柱类似，这种哲学进入了”热路径”，而它可能本不应该如此。同样，我们都在付出代价却没有真正受益。

3. 过期未退的”Ponyfill”

如果你在构建应用，可能想使用你选择的引擎尚不支持的”未来”特性。在这种情况下，polyfill 可以派上用场——它在特性应该在的地方提供后备实现，这样你可以像原生支持一样使用它。

例如，temporal-polyfill polyfill 了新的 Temporal API，这样我们可以使用 Temporal，无论引擎是否支持。

那么，如果你在构建库，应该怎么做？

一般来说，没有任何库应该加载 polyfill，因为这是消费者的责任，库不应该改变它周围的环境。作为替代，一些维护者选择使用所谓的 ponyfill（延续独角兽、闪粉和彩虹的主题）。

ponyfill 基本上是一个你导入的 polyfill，而不是一个改变环境的。

这在某种程度上可行，因为库可以通过导入一个实现来使用未来技术——如果原生存在则传递给原生实现，否则使用后备。这不会改变环境，所以库可以安全使用。

例如，fastly 提供了 @fastly/performance-observer-polyfill，其中包含 PerformanceObserver 的 polyfill 和 ponyfill。

为什么这是个问题

这些 ponyfill 在当时完成了它们的工作——它们允许库作者使用未来技术而不改变环境，也不强迫消费者知道安装哪些 polyfill。

问题在于，这些 ponyfill 赖着不走。当它们填充的特性现在已被我们关心的所有引擎支持时，ponyfill 应该被移除。然而，这往往没有发生，ponyfill 在不再需要后仍然存在。

我们现在留下了许多依赖 ponyfill 的包，而这些特性我们所有人已经用了十年了。

例如：

globalthis - globalThis 的 ponyfill（2019 年广泛支持，每周 4900 万次下载）
indexof - Array.prototype.indexOf 的 ponyfill（2010 年广泛支持，每周 230 万次下载）
object.entries - Object.entries 的 ponyfill（2017 年广泛支持，每周 3500 万次下载）

除非这些包是因为支柱 1 而被保留，否则它们通常只是因为没人想过要移除它们而继续被使用。

当引擎的所有长期支持版本都有该特性时，ponyfill 应该被移除。

我们能做些什么？

这种膨胀如今深深嵌入了依赖树中，要解开这一切并达到良好状态是一项相当艰巨的任务。这需要时间，也需要维护者和消费者的大量努力。

话虽如此，如果我们共同努力，我相信我们可以在这方面取得重大进展。

开始问问自己：”为什么我有这个包？”和”我真的需要它吗？”。

如果你发现某些东西看起来是冗余的，向维护者提出 issue 询问是否可以移除。

如果你遇到一个直接依赖有许多这样的问题，找一个没有这些问题的替代品。一个好的起点是 module-replacements 项目。

使用 Knip 移除未使用的依赖

Knip 是一个很棒的项目，可以帮助你找到并移除未使用的依赖、死代码等等。在这种情况下，它可以是一个很好的工具，帮助你在做更复杂的工作之前找到并移除不再使用的依赖。

你可以在它们的文档中了解更多关于 Knip 如何处理未使用依赖的信息。

使用 e18e CLI 检测可替换的依赖

e18e CLI 有一个超级有用的 analyze 模式，可以确定哪些依赖不再需要，或者有社区推荐的替代品。

例如，如果你得到这样的结果：

$ npx @e18e/cli analyze

...

│  Warnings:
│    • Module "chalk" can be replaced with native functionality. You can read more at
│      https://nodejs.org/docs/latest/api/util.html#utilstyletextformat-text-options. See more at
│      https://github.com/es-tooling/module-replacements/blob/main/docs/modules/chalk.md.

...

使用这个，我们可以快速识别哪些直接依赖可以被清理。我们还可以使用 migrate 命令自动迁移一些依赖：

$ npx @e18e/cli migrate --all

e18e (cli v0.0.1)

┌  Migrating packages...
│
│  Targets: chalk
│
◆  /code/main.js (1 migrated)
│
└  Migration complete - 1 files migrated.

在这个例子中，它会从 chalk 迁移到 picocolors——一个提供相同功能的更小包。

未来，这个 CLI 甚至会根据你的环境进行推荐——例如，如果你运行足够新的 Node 版本，它可能会建议原生的 styleText 而不是颜色库。

使用 npmgraph 调查你的依赖树

npmgraph 是一个可视化依赖树并调查膨胀来源的好工具。

例如，让我们看看写这篇文章时 ESLint 依赖图的下半部分：

我们可以在这个图中看到 find-up 分支是孤立的，没有其他东西使用它的深层依赖。对于像向上遍历文件系统这样简单的事情，也许我们不需要 6 个包。我们可以寻找替代品，比如 empathic，它有更小的依赖图并实现相同的功能。

模块替换

module-replacements 项目被用作社区的中央数据集，记录哪些包可以用原生功能或更高性能的替代品替换。

如果你需要一个替代品或只是想检查你的依赖，这个数据集非常棒。

同样，如果你在依赖树中遇到已被原生功能淘汰的包，或者只是有更好的经过实战检验的替代品，这个项目绝对是一个贡献的好地方，这样其他人也可以受益。

与数据配套的还有一个 codemods 项目，提供 codemods 来自动将一些包迁移到它们建议的替代品。

结语

我们所有人都在为极小的一群人付出代价——他们有着他们喜欢的异常架构，或者他们需要的向后兼容级别。

这不一定是最初创建这些包的人的错，因为每个人都应该以自己想要的方式构建。他们中许多人是老一代有影响力的 JavaScript 开发者——在一个更黑暗的时代构建包，那时我们今天拥有的许多好的 API 和跨兼容性根本不存在。他们以那种方式构建是因为那可能是当时最好的方式。

问题在于我们从未从中走出来。即使我们已经拥有这些功能好几年了，我们今天仍然在下载所有这些膨胀。

我认为我们可以通过逆转情况来解决这个问题。这个小群体应该付出代价——他们应该有自己特殊的堆栈，几乎只有他们使用。其他人则获得现代、轻量级和广泛支持的代码。

希望 e18e 和 npmx 这样的事物可以通过文档、工具等帮助实现这一点。你也可以通过仔细查看你的依赖并问”为什么？”来帮助。向你的依赖提出 issue，询问它们是否以及为什么仍然需要这些包。

我们可以解决这个问题。

核心要点

旧运行时兼容性的代价：为极少数需要支持 ES3 或跨 Realm 场景的用户，我们所有人都在依赖树中承担了额外的包
原子化架构的陷阱：将代码拆分成过多微小包不仅没有带来预期的复用，反而增加了获取成本和供应链风险
Ponyfill 应及时清理：当特性已成为所有 LTS 版本的标准支持时，相应的 ponyfill 应该被移除
行动建议：使用 knip 清理未使用依赖，用 e18e CLI 分析可替换的包，通过 npmgraph 可视化依赖树

这篇文章让我深刻反思了自己项目中的依赖选择。作为开发者，我们往往只关注”能用就行”，却忽略了依赖膨胀带来的长期成本。e18e 社区的工作值得更多关注和支持。

BMAD 技能验证系统：14 条确定性规则捕获真实 Bug

Sun, 22 Mar 2026 00:00:00 +0000

BMAD 的技能验证系统（tools/validate-skills.js）实现了 14 条确定性规则，作为基于推理的验证的”快速预检”补充。这不只是代码检查——它能捕获会破坏 LLM 工作流的真实结构性 Bug。

核心哲学：确定性优先，推理其次

/**
 * Deterministic Skill Validator
 *
 * Validates 14 deterministic rules across all skill directories.
 * Acts as a fast first-pass complement to the inference-based skill validator.
 */

为什么用确定性规则？因为正则表达式不会产生幻觉。当你能用简单的模式匹配捕获结构性错误时，就应该这么做——更快、更便宜，而且 100% 一致。

14 条规则详解

SKILL-01 到 SKILL-07：SKILL.md 验证

SKILL-01：SKILL.md 必须存在

if (!fs.existsSync(skillMdPath)) {
  findings.push({
    rule: 'SKILL-01',
    severity: 'CRITICAL',
    detail: 'SKILL.md not found in skill directory.',
  });
}

SKILL-02/03：Frontmatter 必须包含 name 和 description

缺少这些意味着 Agent 无法发现该技能

SKILL-04：名称格式验证

const NAME_REGEX = /^bmad-[a-z0-9]+(-[a-z0-9]+)*$/;

必须小写、连字符分隔、无空格
示例：bmad-create-story、bmad-dev-story

SKILL-05：名称必须与目录匹配

防止 bmad-create-story/ 目录中出现 name: bmad-make-story

SKILL-06：描述质量检查

if (!/use\s+when\b/i.test(description) && !/use\s+if\b/i.test(description)) {
  // Must contain trigger phrase
}

必须包含 “Use when” 或 “Use if”——告诉 Agent 何时调用

SKILL-07：正文内容必填

仅有 frontmatter 的 SKILL.md 毫无用处——需要实际的指令内容

WF-01/WF-02：工作流文件规范

非 SKILL.md 文件（如 workflow.md、step 文件）不应在 frontmatter 中包含 name 或 description：

if ('name' in fm) {
  findings.push({
    rule: 'WF-01',
    severity: 'HIGH',
    detail: 'frontmatter contains `name` — this belongs only in SKILL.md.',
  });
}

为什么？因为这些元数据字段会导致 Agent 发现时的混乱——只有入口文件（SKILL.md）才应定义技能的身份。

PATH-02：禁止 `installed_path` 变量

if (/installed_path/i.test(line)) {
  findings.push({
    rule: 'PATH-02',
    severity: 'HIGH',
    detail: '`installed_path` reference found in content.',
    fix: 'Use relative paths (`./path` or `../path`) instead.',
  });
}

这捕获了一个常见错误：使用绝对安装路径，当技能安装到不同位置时就会失效。

STEP-01/STEP-06/STEP-07：步骤文件验证

STEP-01：步骤文件名格式

const STEP_FILENAME_REGEX = /^step-\d{2}[a-z]?-[a-z0-9-]+\.md$/;

合法：step-01-load-context.md、step-02a-analyze.md
非法：Step1.md、step-1.md、step-01_load.md

STEP-06：步骤文件不应有 name/description

步骤的元数据是冗余的——步骤从父技能继承

STEP-07：步骤数必须在 2-10 之间

if (stepCount > 0 && (stepCount < 2 || stepCount > 10)) {
  const detail = stepCount < 2
    ? `Only ${stepCount} step file found — consider inlining into workflow.md.`
    : `${stepCount} step files found — more than 10 risks LLM context degradation.`;
}

这是一个实用约束：少于 2 步不需要单独的文件；超过 10 步则有 LLM 上下文退化的风险。

SEQ-02：禁止时间估算

const TIME_ESTIMATE_PATTERNS = [
  /takes?\s+\d+\s*min/i,
  /~\s*\d+\s*min/i,
  /estimated\s+time/i,
  /\bETA\b/
];

为什么？因为 AI 执行速度差异太大。”这需要 5 分钟”对某些模型/用户来说永远是不准确的。

Frontmatter 解析器

验证器包含一个支持多行的 frontmatter 解析器：

function parseFrontmatterMultiline(content) {
  // 处理如下 YAML：
  // description: |
  //   This is a long description
  //   that spans multiple lines

  let currentKey = null;
  let currentValue = '';

  for (const line of fmBlock.split('\n')) {
    const colonIndex = line.indexOf(':');
    if (colonIndex > 0 && line[0] !== ' ' && line[0] !== '\t') {
      // 列 0 处的新键
      if (currentKey !== null) {
        result[currentKey] = stripQuotes(currentValue.trim());
      }
      currentKey = line.slice(0, colonIndex).trim();
      currentValue = line.slice(colonIndex + 1);
    } else if (currentKey !== null) {
      // 续行
      currentValue += '\n' + line;
    }
  }
}

命令行使用

# 验证所有技能，人类可读格式
node tools/validate-skills.js

# 验证单个技能
node tools/validate-skills.js path/to/skill-dir

# 严格模式（HIGH+ 级别错误时退出码为 1）
node tools/validate-skills.js --strict

# JSON 输出，适用于 CI
node tools/validate-skills.js --json

GitHub Actions 集成

验证器会自动生成 GitHub Actions 标注：

if (process.env.GITHUB_ACTIONS) {
  const level = f.severity === 'LOW' ? 'notice' : 'warning';
  console.log(`::${level} file=${ghFile},line=${line}::${escapeAnnotation(...)}`);
}

以及步骤摘要：

if (process.env.GITHUB_STEP_SUMMARY) {
  let summary = '## Skill Validation\n\n';
  summary += '| Skill | Rule | Severity | File | Detail |\n';
  // ...
  fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, summary);
}

为什么这很重要

在构建 LLM 驱动的工作流时，结构性 Bug 是致命的：

错误的技能名称 → Agent 找不到它
缺少描述触发词 → Agent 不知道何时使用
步骤过多 → 上下文溢出，Agent 忘记前面的步骤
绝对路径 → 在你的机器上能运行，在其他地方就挂了

这些不是理论上的担忧——它们是 BMAD 团队真实遇到并修复的 Bug。这 14 条规则编码了关于什么会真正破坏 LLM 工作流的宝贵经验。

文件引用验证（配套工具）

BMAD 还包含 validate-file-refs.js 用于跨文件引用验证：

验证 {project-root}/_bmad/ 引用能解析到真实文件
捕获损坏的 exec="..." 目标
检测绝对路径泄漏（/Users/、/home/、C:\）
验证 CSV 工作流文件引用

这两个验证器共同构成了一个确定性安全网，在结构性 Bug 到达 LLM 之前将其捕获。

源码：tools/validate-skills.js

核心洞察：对于结构性问题，确定性验证比基于推理的验证更快、更便宜、更可靠。能使用正则/模式的地方就用，把 LLM 推理留给无法模式匹配的部分。

OpenCode：开源 AI 编程代理新秀

Sat, 21 Mar 2026 14:25:59 +0000

本文翻译自 OpenCode - The Open Source AI Coding Agent，原载于 Hacker News。

什么是 OpenCode？

在 AI 编程工具百花齐放的今天，OpenCode 作为一款开源的 AI 编程代理（AI Coding Agent）脱颖而出。它不仅提供了终端界面、桌面应用和 IDE 扩展等多种使用方式，更重要的是——它是完全开源的。

OpenCode 的核心优势在于其灵活性：你可以使用内置的免费模型，也可以连接任意 LLM 提供商，包括 Claude、GPT、Gemini 等 75+ 种模型选择。

令人瞩目的社区增长

OpenCode 的增长速度令人惊叹：

120,000+ GitHub Star
800+ 位贡献者
10,000+ 次提交
5M+ 月活跃开发者

在短短一年内获得近 10 万 Star，这在开源社区实属罕见。MorphLLM 的评测甚至称其为”如果你想要一个拥有强大社区势头的开源终端代理，这是最佳选择”。

核心功能特性

1. LSP 支持

OpenCode 能够为 LLM（Large Language Model）自动加载合适的 Language Server Protocol，这意味着它能更好地理解你的代码上下文，提供更精准的代码建议和修改。

2. 多会话并行

在同一个项目中，你可以并行启动多个代理实例。这对于需要同时处理多个任务的场景非常有用——比如一边修复 bug，一边开发新功能。

3. 会话分享

你可以生成任意会话的分享链接，方便团队成员参考或调试。这在团队协作中是一个非常实用的功能。

4. 灵活的模型选择

GitHub Copilot：使用 GitHub 登录即可使用你的 Copilot 账户
ChatGPT Plus/Pro：使用 OpenAI 登录即可使用你的 ChatGPT 订阅
任意模型：通过 Models.dev 支持 75+ LLM 提供商，包括本地部署的模型

5. 多平台支持

终端界面（TUI）
桌面应用（macOS、Windows、Linux）
IDE 扩展

隐私优先的设计

对于企业用户和注重隐私的开发者来说，OpenCode 的设计理念非常友好：它不存储你的任何代码或上下文数据。这意味着你可以在对隐私敏感的环境中放心使用，无需担心代码泄露到第三方服务器。

快速上手

安装 OpenCode 非常简单，只需一行命令：

curl -fsSL https://opencode.ai/install | bash

你也可以通过 npm、Homebrew、Docker 等多种方式安装：

# npm
npm install -g opencode-ai

# Homebrew (推荐使用官方 tap)
brew install anomalyco/tap/opencode

# Docker
docker run -it --rm ghcr.io/anomalyco/opencode

使用技巧

提问模式

你可以让 OpenCode 为你讲解代码库：

How is authentication handled in @packages/functions/src/api/index.ts

计划模式

对于复杂的功能开发，建议先使用计划模式（按 Tab 键切换）。OpenCode 会分析需求并给出实施方案，而不是直接修改代码。这让你有机会在实施前审查和调整计划。

撤销与重做

如果修改不符合预期，可以使用 /undo 命令撤销。OpenCode 会还原修改并重新显示之前的对话，让你调整提示词后重试。

OpenCode Zen：精选模型服务

OpenCode 还提供了 Zen 服务——一组经过团队测试和基准测试的精选 AI 模型。这些模型专门针对编程代理场景优化，免去了在不同提供商之间比较性能的麻烦。

个人看法

OpenCode 的出现为 AI 编程工具市场带来了一个真正开放的选择。与闭源的竞争对手相比，开源意味着：

透明度：你可以审计代码，了解工具的真实行为
可定制性：可以根据团队需求进行二次开发
社区驱动：800+ 贡献者意味着更快的问题修复和功能迭代

不过，作为一款相对年轻的工具，OpenCode 在某些方面的成熟度可能还不如 Cursor 等老牌选手。但考虑到其惊人的增长速度和活跃的社区，这只是一个时间问题。

如果你正在寻找一款开源、灵活且注重隐私的 AI 编程助手，OpenCode 绝对值得一试。

总结

OpenCode 是一款完全开源的 AI 编程代理，支持终端、桌面、IDE 多种使用方式
已获得 12 万+ GitHub Star，增长势头强劲
支持 75+ LLM 提供商，模型选择极其灵活
隐私优先设计，不存储用户代码和上下文
多会话、LSP 支持、会话分享等功能提升开发效率

参考资料：

FFmpeg 入门指南：架构概述与实践

Sat, 21 Mar 2026 12:20:08 +0000

本文翻译自 FFmpeg 101，原载于 Hacker News。

FFmpeg 简介

FFmpeg 是多媒体处理领域的瑞士军刀，无论是视频转码、音频提取，还是流媒体传输，它都能胜任。本文将从架构层面带你快速上手 FFmpeg，理解其核心组件和工作原理。

FFmpeg 包的组成

FFmpeg 由一套工具和库组成，我们可以根据需求选择命令行工具直接使用，或者通过库函数集成到自己的产品中。

FFmpeg 命令行工具

这些工具可以直接在终端中使用：

ffmpeg：最常用的命令行工具，用于在各种多媒体格式之间转换
ffplay：基于 SDL 和 FFmpeg 库的简易媒体播放器，适合快速预览
ffprobe：多媒体流分析器，可以查看文件的编码信息、元数据等

FFmpeg 核心库

如果你想在自己的程序中集成多媒体处理能力，可以使用这些库：

libavformat：负责 I/O 操作和复用/解复用（muxing/demuxing）
libavcodec：核心编解码库
libavfilter：基于图形的滤镜框架，用于处理原始媒体数据
libavdevice：输入/输出设备支持
libavutil：通用多媒体工具函数
libswresample：音频重采样、采样格式转换和音频混音
libswscale：颜色转换和图像缩放
libpostproc：视频后处理（去块效应/降噪滤镜）

实现一个简单的 FFmpeg 播放器

FFmpeg 的基本使用场景之一是：从文件或网络获取多媒体流，解复用（demux）成音频流和视频流，然后解码成原始的音频和视频数据。

核心数据结构

FFmpeg 使用以下核心结构来管理媒体流：

AVFormatContext：高层结构，提供流的同步、元数据和复用功能
AVStream：表示一个连续的流（音频或视频）
AVCodec：定义数据的编码和解码方式
AVPacket：流中的编码数据包
AVFrame：解码后的数据（原始视频帧或原始音频采样）

处理流程

整个解复用和解码的流程如下：

第一步：打开文件并分析流

下面的代码展示了如何从文件中读取编码的多媒体流，分析其内容并解复用音频和视频流。这些功能由 libavformat 库提供，使用 AVFormatContext 和 AVStream 结构来存储信息。

// 为上下文结构分配内存
AVFormatContext* format_context = avformat_alloc_context();

// 打开多媒体文件（如 mp4 文件或 FFmpeg 识别的任何格式）
avformat_open_input(&format_context, filename, NULL, NULL);
printf("File: %s, format: %s\n", filename, format_context->iformat->name);

// 分析文件内容并识别其中的流
avformat_find_stream_info(format_context, NULL);

// 列出所有流
for (unsigned int i = 0; i < format_context->nb_streams; ++i)
{
    AVStream* stream = format_context->streams[i];

    printf("---- Stream %02d\n", i);
    printf("  Time base: %d/%d\n", stream->time_base.num, stream->time_base.den);
    printf("  Framerate: %d/%d\n", stream->r_frame_rate.num, stream->r_frame_rate.den);
    printf("  Start time: %" PRId64 "\n", stream->start_time);
    printf("  Duration: %" PRId64 "\n", stream->duration);
    printf("  Type: %s\n", av_get_media_type_string(stream->codecpar->codec_type));

    uint32_t fourcc = stream->codecpar->codec_tag;
    printf("  FourCC: %c%c%c%c\n", fourcc & 0xff, (fourcc >> 8) & 0xff, (fourcc >> 16) & 0xff, (fourcc >> 24) & 0xff);
}

// 关闭多媒体文件并释放上下文结构
avformat_close_input(&format_context);

第二步：查找解码器

获取到多媒体文件中的各个流之后，我们需要找到相应的编解码器来将这些流解码成原始的音频和视频数据。所有的编解码器都静态地包含在 libavcodec 中。

💡 扩展知识：你也可以创建自己的编解码器，只需创建一个 FFCodec 结构体的实例，并在 libavcodec/allcodecs.c 中将其注册为 extern const FFCodec。不过这是另一个话题了。

要找到与 AVStream 内容对应的编解码器，可以使用以下代码：

// 从之前的流列表循环中获取的 AVStream
AVStream* stream = format_context->streams[i];

// 查找兼容的解码器
const AVCodec* codec = avcodec_find_decoder(stream->codecpar->codec_id);
if (!codec)
{
    fprintf(stderr, "Unsupported codec\n");
    continue;
}
printf("  Codec: %s, bitrate: %" PRId64 "\n", codec->name, stream->codecpar->bit_rate);

if (codec->type == AVMEDIA_TYPE_VIDEO)
{
    printf("  Video resolution: %dx%d\n", stream->codecpar->width, stream->codecpar->height);
}
else if (codec->type == AVMEDIA_TYPE_AUDIO)
{
    printf("  Audio: %d channels, sample rate: %d Hz\n",
        stream->codecpar->ch_layout.nb_channels,
        stream->codecpar->sample_rate);
}

第三步：初始化解码器上下文

有了正确的编解码器和从 AVStream 中提取的编解码器参数，我们现在可以分配 AVCodecContext 结构，用于解码相应的流。

⚠️ 注意：记住要保存我们要解码的流在流列表中的索引，因为后续这个索引将用于标识由 AVFormatContext 解复用出来的数据包。

下面的代码将选择多媒体文件中的第一个视频流：

// first_video_stream_index 在之前的流列表循环中确定
int first_video_stream_index = ...;

AVStream* first_video_stream = format_context->streams[first_video_stream_index];
AVCodecParameters* first_video_stream_codec_params = first_video_stream->codecpar;
const AVCodec* first_video_stream_codec = avcodec_find_decoder(first_video_stream_codec_params->codec_id);

// 为解码上下文结构分配内存
AVCodecContext* codec_context = avcodec_alloc_context3(first_video_stream_codec);

// 使用编解码器参数配置解码器
avcodec_parameters_to_context(codec_context, first_video_stream_codec_params);

// 打开解码器
avcodec_open2(codec_context, first_video_stream_codec, NULL);

第四步：解复用和解码

现在我们有了一个运行中的解码器，可以使用 AVFormatContext 结构提取解复用的数据包，并将它们解码成原始视频帧。我们需要两个不同的结构：

AVPacket：包含从输入多媒体文件中提取的编码数据包
AVFrame：在 AVCodecContext 解码前面的数据包后，将包含原始视频帧

// 为编码数据包结构分配内存
AVPacket* packet = av_packet_alloc();

// 为解码帧结构分配内存
AVFrame* frame = av_frame_alloc();

// 从输入多媒体文件中解复用下一个数据包
while (av_read_frame(format_context, packet) >= 0)
{
    // 解复用的数据包使用流索引来标识它来自哪个 AVStream
    printf("Packet received for stream %02d, pts: %" PRId64 "\n", packet->stream_index, packet->pts);

    // 在我们的示例中，我们只解码之前由 first_video_stream_index 标识的第一个视频流
    if (packet->stream_index == first_video_stream_index)
    {
        // 将数据包发送到之前初始化的解码器
        int res = avcodec_send_packet(codec_context, packet);
        if (res < 0)
        {
            fprintf(stderr, "Cannot send packet to the decoder: %s\n", av_err2str(res));
            break;
        }

        // 解码器（AVCodecContext）就像一个 FIFO 队列，我们在一端推入编码数据包，
        // 需要从另一端轮询来获取解码后的帧。编解码器实现可能使用不同的线程来执行实际的解码。

        // 轮询运行中的解码器以获取到目前为止所有可用的解码帧
        while (res >= 0)
        {
            // 获取下一个可用的解码帧
            res = avcodec_receive_frame(codec_context, frame);
            if (res == AVERROR(EAGAIN) || res == AVERROR_EOF)
            {
                // 解码器输出队列中没有更多的解码帧，继续下一个编码数据包
                break;
            }
            else if (res < 0)
            {
                fprintf(stderr, "Error while receiving a frame from the decoder: %s\n", av_err2str(res));
                goto end;
            }

            // 现在 AVFrame 结构包含一个解码后的原始视频帧，我们可以进一步处理它...
            printf("Frame %02" PRId64 ", type: %c, format: %d, pts: %03" PRId64 ", keyframe: %s\n",
                codec_context->frame_num, av_get_picture_type_char(frame->pict_type), frame->format, frame->pts,
                (frame->flags & AV_FRAME_FLAG_KEY) ? "true" : "false");

            // AVFrame 的内部内容在下一次调用 avcodec_receive_frame(codec_context, frame) 时会自动 unref 和回收
        }
    }

    // Unref 数据包的内部内容，以便为下一个解复用的数据包回收它
    av_packet_unref(packet);
}

// 释放之前为各种 FFmpeg 结构分配的内存
end:
    av_packet_free(&packet);
    av_frame_free(&frame);
    avcodec_free_context(&codec_context);
    avformat_close_input(&format_context);

完整流程图

上述代码的工作方式可以用下图总结：

编译和运行示例

完整的示例代码可以在原文仓库中找到。

编译需要 meson 和 ninja。如果你已经安装了 python 和 pip，可以通过 pip3 install meson ninja 轻松安装。

编译步骤：

# 解压示例代码到 ffmpeg-101 文件夹
cd ffmpeg-101
meson setup build    # 如果系统中没有安装 FFmpeg，会自动下载正确的版本
ninja -C build       # 编译代码
./build/ffmpeg-101 sample.mp4  # 运行

示例输出

File: sample.mp4, format: mov,mp4,m4a,3gp,3g2,mj2
---- Stream 00
  Time base: 1/3000
  Framerate: 30/1
  Start time: 0
  Duration: 30000
  Type: video
  FourCC: avc1
  Codec: h264, bitrate: 47094
  Video resolution: 206x80
---- Stream 01
  Time base: 1/44100
  Framerate: 0/0
  Start time: 0
  Duration: 440320
  Type: audio
  FourCC: mp4a
  Codec: aac, bitrate: 112000
  Audio: 2 channels, sample rate: 44100 Hz
Packet received for stream 00, pts: 0
Send video packet to decoder...
Frame 01, type: I, format: 0, pts: 000, keyframe: true
Packet received for stream 00, pts: 100
Send video packet to decoder...
Frame 02, type: P, format: 0, pts: 100, keyframe: false
...

关键要点总结

FFmpeg 架构清晰：工具层（ffmpeg/ffplay/ffprobe）用于命令行操作，库层（libav*）用于程序集成
核心概念：
- AVFormatContext 管理整个媒体文件
- AVStream 代表单个流（音频或视频）
- AVPacket 是编码数据，AVFrame 是解码后的原始数据
解码流程：打开文件 → 分析流信息 → 查找解码器 → 初始化解码上下文 → 循环读取数据包 → 发送到解码器 → 接收解码帧
解码器是 FIFO 队列：推送编码数据包后，需要轮询获取解码帧，可能存在延迟
内存管理：FFmpeg 使用引用计数，记得在适当的时候调用 av_packet_unref() 和各种 *_free() 函数

FFmpeg 是学习多媒体处理的绝佳起点，理解了这些基础概念后，你就可以进一步探索滤镜、编码、流媒体传输等更高级的主题了。

为什么我们把 Rust WASM 解析器重写成了 TypeScript

Fri, 20 Mar 2026 23:05:11 +0000

本文翻译自 Rewriting our Rust WASM Parser in TypeScript，原载于 Hacker News。

我们最初用 Rust 构建了 openui-lang 解析器，并编译成 WASM。这个思路看起来很合理：Rust 很快，WASM 能在浏览器中获得接近原生的速度，而且我们的解析器是一个相当复杂的多阶段流水线。有什么理由不用 Rust 呢？

结果发现，我们一直在优化错误的东西。

问题背景

openui-lang 解析器负责将 LLM 生成的自定义 DSL 转换为 React 组件树。它在每个流式 chunk 上都会运行——所以延迟非常关键。整个流水线有六个阶段：

autocloser → lexer → splitter → parser → resolver → mapper → ParseResult

Autocloser：通过追加最小化的闭合括号/引号，使部分（流式中间）文本在语法上有效
Lexer：单遍字符扫描器，生成类型化 token
Splitter：将 token 流切分为 id = expression 语句
Parser：递归下降表达式解析器，构建 AST
Resolver：内联所有变量引用（支持提升、循环引用检测）
Mapper：将内部 AST 转换为 React 渲染器消费的公共 OutputNode 格式

WASM 的隐形成本

每次调用 WASM 解析器都会产生固定开销，无论 Rust 代码本身跑多快：

JS 世界                           WASM 世界
────────────────────────────────────────────────────────
wasmParse(input)
│
├─ 复制字符串: JS heap → WASM 线性内存 (分配 + memcpy)
│
│  Rust 解析 ✓ 很快
│  serde_json::to_string() ← 序列化结果
│
├─ 复制 JSON 字符串: WASM → JS heap (分配 + memcpy)
│
JSON.parse(jsonString) ← 反序列化结果
│
return ParseResult

Rust 解析本身从来不是慢的地方。开销完全在边界上：复制字符串进去、序列化结果为 JSON 字符串、复制 JSON 字符串出来，然后 V8 把它反序列化回 JS 对象。

serde-wasm-bindgen 尝试：更慢了

我们自然想到：如果 WASM 直接返回 JS 对象，跳过 JSON 序列化步骤会怎样？我们集成了 serde-wasm-bindgen，它正是做这个的——把 Rust 结构体转换成 JsValue 直接返回。

结果是慢了 30%。

原因如下：JS 无法从 WASM 线性内存中直接读取 Rust 结构体的字节作为原生 JS 对象——两个运行时使用完全不同的内存布局。要从 Rust 数据构造 JS 对象，serde-wasm-bindgen 必须递归地将 Rust 数据物化为真正的 JS 数组和对象，这涉及到每次 parse() 调用时大量细粒度的跨运行时边界转换。

对比 JSON 方式：serde_json::to_string() 在纯 Rust 中运行，零边界穿越，生成一个字符串，一次 memcpy 把它复制到 JS heap，然后 V8 原生的 C++ JSON.parse 在单次优化遍历中处理它。少量、大型、优化的操作胜过大量小型操作。

基准测试：JSON 字符串 vs 直接 JsValue（1000 次运行，每次调用 µs）

Fixture	JSON round-trip	serde-wasm-bindgen	变化
simple-table	20.5	22.5	-9% 更慢
contact-form	61.4	79.4	-29% 更慢
dashboard	57.9	74.0	-28% 更慢

我们立刻回滚了这个改动。

TypeScript 重写

我们把完整的解析器流水线移植到了 TypeScript。同样的六阶段架构，同样的 ParseResult 输出格式——没有 WASM，没有边界，完全在 V8 heap 中运行。

基准测试方法：单次解析

测量内容：对完整字符串的单次 parse(completeString) 调用。这隔离了每次调用的解析成本。

运行方式：30 次预热迭代以稳定 JIT，然后使用 performance.now()（µs 精度）进行 1000 次计时迭代。报告中位数。Fixture 是真实的 LLM 生成组件树，以各格式的真实流式语法序列化。

Fixture 说明：

simple-table — root + 一个 3 列 5 行的 Table（约 180 字符）
contact-form — root + 包含 6 个输入字段的表单布局 + 提交按钮（约 400 字符）
dashboard — root + 侧边栏导航 + 3 个指标卡片 + 图表 + 数据表（约 950 字符）

结果：单次解析（中位数 µs，1000 次运行）

Fixture	TypeScript	WASM	加速比
simple-table	9.3	20.5	2.2x
contact-form	13.4	61.4	4.6x
dashboard	19.4	57.9	3.0x

进一步优化：语句级增量缓存

消除了 WASM 解决了每次调用的成本，但流式架构还有一个更深层的问题。

解析器在每个 LLM chunk 上都会被调用。朴素方法是累积 chunks 并每次从头重新解析整个字符串：

Chunk 1: parse("root = Root([t") → 14 chars
Chunk 2: parse("root = Root([tbl])\ntbl = T") → 27 chars
Chunk 3: parse(full_accumulated_string) → ...

对于 1000 字符输出、20 字符 chunk 分片：50 次解析调用，累计处理约 25,000 字符。O(N²) 复杂度。

解决方案

以 depth-0 换行符终止的语句是不可变的——LLM 永远不会回来修改它们。我们添加了一个流式解析器，缓存已完成语句的 AST：

State: { buf, completedEnd, completedSyms, firstId }

On each push(chunk):
1. 从 completedEnd 扫描 buf 寻找 depth-0 换行符
2. 对于每个找到的完整语句: 解析 + 缓存 AST → 推进 completedEnd
3. 待处理（最后的、不完整的）语句: autoclose + 重新解析
4. 合并已缓存 + 待处理 → resolve + map → 返回 ParseResult

已完成的语句永远不会被重新解析。每个 chunk 只重新解析尾部进行中的语句。O(total_length) 而不是 O(N²)。

结果：完整流式解析总成本（所有 chunk 的中位数 µs）

Fixture	朴素 TS（每 chunk 重解析）	增量 TS（缓存已完成）	加速比
simple-table	69	77	无（单语句，无缓存收益）
contact-form	316	122	2.6x
dashboard	840	255	3.3x

simple-table fixture 是单条语句——没有东西可缓存，所以两种方法等效。收益随语句数量增加而增加，因为更多文档被缓存并在每个 chunk 中跳过。

为什么两个 TS 数字看起来不同

单次解析表格显示 contact-form 为 13.4µs；流式表格显示 316µs（朴素）。这并不矛盾——它们测量的是不同东西：

13.4µs = 对完整 400 字符字符串的一次 parse() 调用成本
316µs = 流式过程中约 20 次 parse() 调用的总成本（chunk 1 解析 20 字符，chunk 2 解析 40 字符，…，chunk 20 解析 400 字符——所有这些增长调用的累计和）

最终对比

方法	每次调用成本	完整流式总计	备注
WASM + JSON round-trip	20-61µs	baseline	每次调用有复制开销
WASM + serde-wasm-bindgen	22-79µs	+9-29% 更慢	内部有数百次边界穿越
TypeScript（朴素重解析）	9-19µs	69-840µs	无边界，但 O(N²) 流式
TypeScript（增量）	9-19µs	69-255µs	无边界 + O(N) 流式

最终结果：每次调用快 2.2-4.6 倍，完整流式成本低 2.6-3.3 倍。

WASM 适用场景总结

这次经历让我们对 WASM 的正确使用场景有了更清晰的认识：

✅ 计算密集型且最小互操作：图像/视频处理、密码学、物理模拟、音频编解码器。大输入 → 标量输出或原地修改。边界穿越很少。

✅ 可移植原生库：将 C/C++ 库（SQLite、OpenCV、libpng）发布到浏览器，无需完整 JS 重写。

❌ 将结构化文本解析为 JS 对象：无论如何都要付出序列化成本。解析计算足够快，V8 的 JIT 消除了任何 Rust 优势。边界开销占主导。

❌ 频繁调用的小输入函数：如果函数每个流被调用 50 次，计算只需 5µs，你无法摊销边界成本。

关键经验

在选择实现语言之前，先分析时间实际花在哪里。对我们来说，成本从来不在计算中——始终在跨 WASM-JS 边界的数据传输中。
通过 serde-wasm-bindgen 的”直接对象传递”并不更便宜。从 Rust 逐字段构造 JS 对象比单次 JSON 字符串传输涉及更多边界穿越，而不是更少。边界穿越发生在单次 FFI 调用内部，是不可见的。
算法复杂度改进主导语言级优化。在流式场景中，从 O(N²) 到 O(N) 的改进比从 WASM 切换到 TypeScript 有更大的实际影响。
WASM 和 JS 不共享堆。WASM 有扁平的线性内存（WebAssembly.Memory），JS 可以作为原始字节读取，但这些字节是 Rust 的内部布局——指针、枚举判别式、对齐填充——对 JS 运行时完全不透明。转换总是必需的，总是有成本的。

这篇文章给我们的启示是：性能优化需要找到真正的瓶颈。有时候，”更快的语言”反而因为运行时边界开销而变慢。在做技术选型时，要考虑完整的数据流路径，而不仅仅是某个环节的计算速度。

Attention Residuals：用注意力机制重塑 Transformer 的残差连接

Fri, 20 Mar 2026 22:03:19 +0000

本文翻译自 Attention Residuals，原载于 Hacker News。

背景：传统残差连接的困境

自从 ResNet 引入残差连接（Residual Connection）以来，这一技术已经成为深度学习模型的标配。在 Transformer 架构中，残差连接采用简单的加法操作：

h_l = h_{l-1} + f(h_{l-1})

这种设计虽然简单有效，但随着模型深度的增加，问题也逐渐显现：

均匀稀释问题：所有层的输出都以固定权重 1 进行累加，随着深度增加，每一层的贡献被均匀稀释
数值膨胀问题：在 PreNorm 架构中，hidden-state 的幅度会无界增长，这是业界已知的一个痛点

Moonshot AI 团队提出的 Attention Residuals（AttnRes） 正是为了解决这些问题。

核心创新：用注意力替代固定累加

AttnRes 的核心思想非常优雅：用可学习的注意力权重替代固定的单位权重。具体来说：

\[\mathbf{h}_l = \sum_{i=0}^{l-1} \alpha_{i \to l} \cdot \mathbf{v}_i\]

其中权重 $\alpha_{i \to l}$ 通过每个层学习一个伪查询向量 $\mathbf{w}_l \in \mathbb{R}^d$ 来计算。这样，每一层都可以根据输入内容选择性地聚合之前所有层的表示。

（a）标准残差：均匀加法累加（b）完整 AttnRes：每层对之前所有输出进行注意力聚合（c）分块 AttnRes：将层分组为块，减少内存开销

Block AttnRes：工程友好的变体

完整的 AttnRes 虽然直观，但在大规模应用时需要 O(Ld) 的内存。为了解决这个问题，作者提出了 Block AttnRes：

将层划分为 N 个块
在每个块内部使用标准残差连接
只在块级别应用注意力机制

实验表明，使用约 8 个块时，Block AttnRes 能够恢复完整 AttnRes 大部分性能提升，同时保持极小的额外开销。

PyTorch 风格伪代码

def block_attn_res(blocks: list[Tensor], partial_block: Tensor, proj: Linear, norm: RMSNorm) -> Tensor:
    """
    Inter-block attention: attend over block reps + partial sum.
    blocks:
        N tensors of shape [B, T, D]: completed block representations for each previous block
    partial_block:
        [B, T, D]:    intra-block partial sum (b_n^i)
    """
    V = torch.stack(blocks + [partial_block])  # [N+1, B, T, D]
    K = norm(V)
    logits = torch.einsum('d, n b t d -> n b t', proj.weight.squeeze(), K)
    h = torch.einsum('n b t, n b t d -> b t d', logits.softmax(0), V)
    return h

def forward(self, blocks: list[Tensor], hidden_states: Tensor) -> tuple[list[Tensor], Tensor]:
    partial_block = hidden_states
    # apply block attnres before attn
    # blocks already include token embedding
    h = block_attn_res(blocks, partial_block, self.attn_res_proj, self.attn_res_norm)

    # if reaches block boundary, start new block
    # block_size counts ATTN + MLP; each transformer layer has 2
    if self.layer_number % (self.block_size // 2) == 0:
        blocks.append(partial_block)
        partial_block = None

    # self-attention layer
    attn_out = self.attn(self.attn_norm(h))
    partial_block = partial_block + attn_out if partial_block is not None else attn_out

    # apply block attnres before MLP
    h = block_attn_res(blocks, partial_block, self.mlp_res_proj, self.mlp_res_norm)

    # MLP layer
    mlp_out = self.mlp(self.mlp_norm(h))
    partial_block = partial_block + mlp_out

    return blocks, partial_block

实验结果：全面领先

Scaling Laws 实验

AttnRes 在所有计算预算下都稳定超越基线。值得注意的是，Block AttnRes 的损失值与使用 1.25 倍计算量训练的基线相当——这相当于免费获得了 25% 的计算效率提升！

下游任务表现（Kimi Linear 48B / 3B 激活，1.4T tokens）

类别	基准测试	Baseline	AttnRes
通用	MMLU	73.5	74.6
	GPQA-Diamond	36.9	44.4
	BBH	76.3	78.0
	TriviaQA	69.9	71.8
数学与代码	Math	53.5	57.1
	HumanEval	59.1	62.2
	MBPP	72.0	73.9
中文	CMMLU	82.0	82.9
	C-Eval	79.6	82.5

最亮眼的提升出现在：

多步推理：GPQA-Diamond 提升了 +7.5 分
代码生成：HumanEval 提升了 +3.1 分

训练动力学分析

AttnRes 有效缓解了 PreNorm 的稀释问题：输出幅度在深度方向保持有界，梯度范数在各层之间分布更加均匀。

个人思考

AttnRes 的设计让我联想到几个有趣的方向：

与 DenseNet 的联系：DenseNet 通过密集连接让每层都能访问之前所有层的特征，AttnRes 可以看作是一种”软性”的 DenseNet，通过注意力机制学习哪些层的特征更重要。
计算效率的权衡：虽然 Block AttnRes 降低了内存开销，但引入了额外的注意力计算。在大规模训练中，这个权衡是否值得需要根据具体场景评估。
与 MoE 的协同：Kimi 的模型采用了 MoE（Mixture of Experts）架构，AttnRes 是否与 MoE 有特殊的协同效应？论文中没有详细讨论，但这可能是一个值得探索的方向。
即插即用的特性：AttnRes 最大的优势在于它是一个”drop-in replacement”，可以直接替换现有模型中的残差连接，无需重新设计架构。这使得它非常容易被社区采纳。

总结

Attention Residuals 是一个简单但 powerful 的创新：

核心思想：用可学习的注意力权重替代固定的残差累加
实用设计：Block AttnRes 降低了内存开销，保持工程可行性
显著效果：多步推理 +7.5 分，代码生成 +3.1 分
易于采用：可直接替换现有 Transformer 中的残差连接

这项工作展示了在深度学习基础组件上持续创新的价值。有时候，改变一个看似简单的”加法”操作，也能带来意想不到的收益。

相关链接：

VisiCalc 复刻：500 行 C 代码实现电子表格

Fri, 20 Mar 2026 19:59:55 +0000

本文翻译自 VisiCalc reconstructed，原载于 Hacker News。

VisiCalc：改变世界的电子表格

近半个世纪以来，电子表格一直统治着商业计算领域。我坚信它是史上最优秀的 UX 设计之一——简洁易学，却能让用户快速处理数据、描述逻辑、可视化结果，甚至创作艺术作品或运行 GameBoy 游戏。

这一切始于 1979 年，Dan Bricklin 和 Bob Frankston 创造了 VisiCalc——世界上第一款电子表格软件。仅用几千行手写的 6502 汇编代码，VisiCalc 就能在 16K RAM 的机器上流畅运行。它迅速成为 Apple ][ 的「杀手级应用」，销量超过 100 万份，让早期的个人电脑成为严肃的商业工具。

我觉得从零开始重建一个最小化的 VisiCalc 克隆会是个有趣的练习。我们需要的核心组件只有三个：数据模型、公式求值器，以及一个简单的单元格显示界面。

单元格（Cells）：电子表格的基石

就像生活中的万物一样，电子表格也是由单元格组成的。每个单元格可以包含一个值、一个公式，或者为空。值可以是数字或文本。公式则是基本的数学表达式，可以引用其他单元格。

你可能从 Excel 中熟悉这些概念，但在 VisiCalc 中，公式前缀通常是 + 而不是 =。例如 +A1+A2*B1 是一个公式，而 A1 则是文本值。

#define MAXIN 128 // 最大单元格输入长度
enum { EMPTY, NUM, LABEL, FORMULA }; // 单元格类型
struct cell {
    int type;
    float val;
    char text[MAXIN]; // 原始用户输入
};

这足以表示电子表格中的单元格。电子表格本身就是一个单元格网格。Excel 的限制是 1,048,576 行和 16,384 列，VisiCalc 有 256 行和 64 列。我们可以从更小的规模开始：

#define NCOL 26 // 最大列数 (A..Z)
#define NROW 50 // 最大行数
struct grid {
    struct cell cells[NCOL][NROW];
};

公式解析：递归下降解析器

接下来我们需要实现公式求值器。我们可以使用一个简单的递归下降解析器（recursive descent parser），即时计算公式结果。由于公式可能包含单元格引用，解析器需要感知网格并能够从中获取值。

struct parser {
    const char* s;
    int pos;
    struct grid* g;
};

我们从顶层函数 expr 开始，它调用 term 来解析项，term 又调用 primary 来解析因子。一个因子可以是数字、单元格引用或括号表达式：

// 跳过空白字符
void skipws(struct parser* p) { for (; isspace(*p->p); p->p++); }
// 解析单元格引用，如 A1, AA12 等
int ref(const char* s, int* col, int* row) { ... }
// 解析数字
float number(struct parser* p) { ... }
// 解析单元格引用并返回其值
static float cellval(struct parser* p) { ... }
// 解析函数调用，如 @SUM(A1...B5) 或 @ABS(-A1)
float func(struct parser* p) { ... }
// 解析基本表达式（数字、单元格引用、函数调用、括号表达式）
float primary(struct parser* p) { ... }
// 解析项 (factor [*|/ factor]*)
float term(struct parser* p) { ... }
// 解析表达式 (term [+|- term]*)
float expr(struct parser* p) { ... }

这是一个经典的「自顶向下」解析器结构：

float primary(struct parser* p) {
    skipws(p);
    if (!*p->p) return NAN;
    if (*p->p == '+') p->p++;
    if (*p->p == '-') {
        p->p++;
        return -primary(p);
    }
    if (*p->p == '@') {
        p->p++;
        return func(p);
    }
    if (*p->p == '(') {
        p->p++;
        float v = expr(p);
        skipws(p);
        if (*p->p != ')') return NAN;
        p->p++;
        return v;
    }
    if (isdigit(*p->p) || *p->p == '.') return number(p);
    return cellval(p);
}

float term(struct parser* p) {
    float l = primary(p);
    for (;;) {
        skipws(p);
        char op = *p->p;
        if (op != '*' && op != '/') break;
        p->p++;
        float r = primary(p);
        if (op == '*')
            l *= r;
        else if (r == 0)
            return NAN;
        else
            l /= r;
    }
    return l;
}

float expr(struct parser* p) {
    float l = term(p);
    for (;;) {
        skipws(p);
        char op = *p->p;
        if (op != '+' && op != '-') break;
        p->p++;
        float r = term(p);
        l = (op == '+') ? l + r : l - r;
    }
    return l;
}

我们使用 NAN（Not a Number）来表示错误，它会优雅地传播——几乎所有对 NAN 的操作都会返回 NAN。

单元格引用的解析也很直观。对于有限的网格，我们可以使用简单的解析来支持更多列和行，比如 “AB123”：

int ref(const char* s, int* col, int* row) {
    char* end;
    const char* p = s;
    if (!isalpha(*p)) return 0;
    *col = toupper(*p++) - 'A';
    if (isalpha(*p)) *col = *col * 26 + (toupper(*p++) - 'A');
    int n = strtol(p, &end, 10);
    if (n <= 0 || end == p) return 0;
    *row = n - 1;
    return (int)(end - s);
}

解析数字很简单，但解析函数稍微复杂一些。我们需要支持单参数函数（如 @ABS(-A1)）和范围函数（如 @SUM(A1...C3)）。本文中我只支持 @SUM、@ABS、@INT、@SQRT，但添加更多函数应该不难。

有了解析器，我们就可以对单元格中的公式求值了：

struct grid g;
struct parser p = { .g = &g };
// A1 := 42
g.cells[0][0].val = 42; g.cells[0][0].type = NUMBER;
// A2 := 123
g.cells[0][1].val = 123; g.cells[0][1].type = NUMBER;
p.s = p.p = "+A1+A2*4";
float n = expr(&p); // n = 534

重算机制：响应式更新的秘密

有了表达式求值器，电子表格的核心功能就有了，但这还不够——因为计算是响应式的。一个单元格可能包含引用其他单元格的公式，当那些单元格变化时，公式应该重新求值。

一种方法是追踪所有单元格之间的依赖关系，在必要时触发更新。维护依赖图能带来最高效的更新，但对于电子表格来说往往是过度设计。

VisiCalc 在 16K RAM 的机器上用一个更简单的技巧实现了这个功能：每次单元格更新时，重新计算整个电子表格。用户可以选择按行优先或按列优先的求值顺序。VisiCalc 手册说，在过去的古董电脑上，大型电子表格的重算可能需要几秒钟。这就是为什么 VisiCalc 提供了手动重算命令，并建议运行几次，直到所有依赖都被解决。

我们可以做得更好——自动运行几次求值迭代，直到没有新的变化被检测到。尽管简单，但这对于大多数实际电子表格来说是非常高效的方式：

void recalc(struct grid* g) {
    for (int pass = 0; pass < 100; pass++) {
        int changed = 0;
        for (int r = 0; r < NROW; r++)
            for (int c = 0; c < NCOL; c++) {
                struct cell* cl = &g->cells[c][r];
                if (cl->type != FORMULA) continue;
                struct parser p = {cl->text, cl->text, g};
                float v = expr(&p);
                if (v != cl->val) changed = 1;
                cl->val = v;
            }
        if (!changed) break;
    }
}

现在我们可以添加一个 setter 函数，更新单元格值并触发重算：

void setcell(struct grid* g, int c, int r, const char* input) {
    struct cell* cl = cell(g, c, r);
    if (!cl) return;
    if (!*input) {
        *cl = (struct cell){0};
        recalc(g);
        return;
    }
    strncpy(cl->text, input, MAXIN - 1);
    if (input[0] == '+' || input[0] == '-' || input[0] == '(' || input[0] == '@') {
        cl->type = FORMULA;
    } else if (isdigit(input[0]) || input[0] == '.') {
        char* end;
        double v = strtod(input, &end);
        cl->type = (*end == '\0') ? NUM : LABEL;
        if (cl->type == NUM) cl->val = v;
    } else {
        cl->type = LABEL;
    }
    recalc(g);
}

测试我们的电子表格数据模型变得简单易读：

struct grid g = {0};
// 设置 A1=5, A2=7, A3=11, A4=@SUM(A1...A3)
setcell(&g, 0, 0, "5");
setcell(&g, 0, 1, "7");
setcell(&g, 0, 2, "11");
setcell(&g, 0, 3, "+@SUM(A1...A3)");
assert(g.cells[0][3].val == 23.0f);

// 改变值，求和应该被重新计算
setcell(&g, 0, 0, "5");
setcell(&g, 0, 1, "+A1+5");
setcell(&g, 0, 2, "+A2+A1");
assert(g.cells[0][3].val == 5.0f + 10.0f + 15.0f);

// 改变 A1，所有公式应该被重新计算
setcell(&g, 0, 0, "7");
assert(g.cells[0][3].val == 7.0f + 12.0f + 19.0f);

TUI 界面：用 ncurses 构建界面

构建 TUI（Terminal User Interface）可能是这个项目中最不具挑战性但最有成就感的部分。我们可以使用经典的 ncurses 库创建一个简单的界面，让我们在单元格中导航、编辑并显示它们的值。

首先需要确定我们要绘制什么。VisiCalc 的屏幕有四个垂直堆叠的不同区域：

状态栏：当前单元格地址及其值或公式
编辑行：你正在输入的内容
列标题：A, B, C, …, AA, AB, AC, …
网格：单元格本身，左边有行号

不是每个单元格都能在屏幕上显示。我们的网格是 26×50，但典型的终端可能只有 80×24。我们需要一个视口（viewport）——一个在网格上滑动的窗口，跟随光标滚动。VisiCalc 也是这样做的：

#define CW 9 // 列显示宽度
#define GW 4 // 行号宽度
// 可见行数和列数
int vcols(void) { return (COLS - GW) / CW; }
int vrows(void) { return LINES - 4; }

struct grid {
    struct cell cells[NCOL][NROW];
    int cc, cr; // 光标列，光标行
    int vc, vr; // 视口左上角
};

当光标移出屏幕时，视口跟随：

if (g.cc < g.vc) g.vc = g.cc;
if (g.cc >= g.vc + vcols()) g.vc = g.cc - vcols() + 1;
if (g.cr < g.vr) g.vr = g.cr;
if (g.cr >= g.vr + vrows()) g.vr = g.cr - vrows() + 1;

实际渲染有点冗长但很线性。状态栏显示当前单元格地址及其值或公式，还显示当前模式——就像 VisiCalc 会在等待输入时显示「READY」，在你输入公式时显示「ENTRY」：

enum { READY, ENTRY, GOTO };

static void draw(struct grid* g, int mode, const char* buf) {
    erase();
    // 状态栏：单元格地址 + 值 + 模式指示器
    attron(A_BOLD | A_REVERSE);
    mvprintw(0, 0, " %c%d", 'A' + g->cc, g->cr + 1);
    if (cur->type == FORMULA)
        printw(" %s = %.10g", cur->text, cur->val);
    mvprintw(0, COLS - 6, mode == ENTRY ? "ENTRY" : "READY");
    attroff(A_BOLD | A_REVERSE);

    // 编辑行：显示正在输入的内容，或当前单元格内容
    if (mode)
        mvprintw(1, 0, "> %s_", buf);
    else if (cur->type != EMPTY)
        mvprintw(1, 0, " %s", cur->text);

然后是列标题和网格单元格。对于每个可见单元格，我们格式化它的值：标签左对齐，数字右对齐，错误显示为「ERROR」。当前单元格用反色高亮：

// 列标题
attron(A_BOLD | A_REVERSE);
for (int c = 0; c < vcols(); c++)
    mvprintw(2, GW + c * CW, "%*c", CW, 'A' + g->vc + c);
attroff(A_BOLD | A_REVERSE);

// 网格单元格
for (int r = 0; r < vrows() && g->vr + r < NROW; r++) {
    int row = g->vr + r, y = 3 + r;
    // 行号
    attron(A_REVERSE);
    mvprintw(y, 0, "%*d ", GW - 1, row + 1);
    attroff(A_REVERSE);

    for (int c = 0; c < vcols() && g->vc + c < NCOL; c++) {
        int col = g->vc + c;
        struct cell* cl = cell(g, col, row);
        // ... 将 cl->val 格式化到显示缓冲区 ...
        int is_cur = (col == g->cc && row == g->cr);
        if (is_cur) attron(A_REVERSE);
        mvprintw(y, GW + c * CW, "%s", fb);
        if (is_cur) attroff(A_REVERSE);
    }
}

整数显示时不带小数，浮点数保留两位小数，标签左对齐。VisiCalc 还有格式化命令——你可以设置单元格显示为货币（$）或左对齐（L）。我们也支持这个：/F 命令让你为当前单元格选择格式。

输入处理：模态界面

主循环将所有内容整合在一起。VisiCalc 有一个模态界面：你要么在网格中导航，要么在单元格中输入。

在 READY 模式下只有三个特殊的首字符：

/ 进入命令模式（VisiCalc 风格：/B 清空，/Q 退出，/F 格式化）
> 进入跳转模式（输入单元格地址如 B5，然后按 Enter）
其他任何字符——进入单元格编辑模式

一旦进入编辑模式，setcell 决定你输入的内容类型：如果以 +、-、( 或 @ 开头，就是公式；如果解析为数字，就是数字；其他都是标签。

要输入特殊的标签文本如 /// 或 >hello，你可以用引号包裹："///"。我们在存储前去掉最外层的引号：

if (ch == '/') {
    // 命令模式：/B 清空，/Q 退出，/F 格式化
} else if (ch == '>') {
    // 跳转模式：输入单元格地址，按 Enter
} else if (ch >= 32 && ch < 127) {
    mode = ENTRY;
    buf[0] = ch; buf[1] = '\0'; len = 1;
}

当用户按 Enter 时，我们确认编辑并向下移动。Tab 确认并向右移动。这让数据输入感觉像在 Excel 中填写表格：

if (ch == 10 && mode == ENTRY) {
    setcell(&g, g.cc, g.cr, buf);
    if (g.cr < NROW - 1) g.cr++;
    mode = READY;
}

整个主循环就是一个 for(;;)，一个 getch()，一个模式变量和一个字符缓冲区。显示和输入处理加起来大约 150 行。

你可以在 GitHub Gist 上查看 mini-VisiCalc 的完整代码。

还有什么没实现

相当多。我们没有文件 I/O，没有 /R（复制）命令来跨范围复制公式，我们可以添加更多函数和运算符，让网格更大，添加控制列宽或锁定行/列的命令。范围上的复杂操作，如移动或复制也缺失了，并且需要在单元格移动时调整公式。

但精髓都在这里：单元格、公式、引用、重算，以及模态 TUI，全部在 500 行 C 代码以内。

令人惊叹的是，在 VisiCalc 首次诞生四十七年后，今天所有的电子表格仍然以同样的方式工作：单元格、公式、重算、网格。试着自己创建一个，或者看看 GitHub 上更完整的 VisiCalc 重新实现——kalk。

总结

这篇文章展示了如何用不到 500 行 C 代码从零实现一个最小可用的电子表格程序。核心要点：

数据模型极其简洁：单元格只需要类型、值和原始文本三个字段
递归下降解析器：经典的 expr → term → primary 结构，优雅处理运算符优先级
响应式更新：VisiCalc 的「暴力重算」策略——每次更新重算整个表格，简单高效
模态界面：READY/ENTRY/GOTO 三种模式，用 ncurses 约 150 行代码实现

这个项目让我重新审视了电子表格的设计。在追求复杂性和功能性的今天，回到 1979 年的 simplicity（简洁）是一种很好的学习方式。47 年过去了，电子表格的核心范式依然未变——这本身就是对原始设计最好的致敬。

如果你想深入了解，可以访问作者的 GitHub 查看更完整的实现。

pperl：用 Rust 重写的 Perl 5 解释器——由 AI 打造

Fri, 20 Mar 2026 18:55:32 +0000

本文翻译自 Perl mit AI — Richard Jelinek — GPW 2026，原载于 Hacker News。

引言

Richard Jelinek 是一位使用 Perl 进行 AI 开发数十年的资深程序员。在 2026 年德国 Perl Workshop（GPW 2026）上，他做了一个令人印象深刻的演讲，主题是：把谓词反过来——让 AI 来写 Perl。

“I have been doing AI with Perl for a few decades. Now — 3 decades into Perl — I think it is time to turn the predicate around and let AI do Perl.”

这句话道出了演讲的核心思想：不再只是用 Perl 写 AI，而是让 AI 来帮助写 Perl。

背景故事：从智能家居到 AI 编程

演讲的前半部分，Jelinek 分享了他过去十年的一些项目经历。他设计并建造了一套完全离网的智能家居系统（Villa-A），配备：

40 kWp 太阳能板
120 kWh LiFePO4 电池组
地源热泵
毛细管天花板采暖/制冷系统
完整的 DALI 照明控制

这套系统需要一个自动化控制系统，但他尝试了现有的解决方案都不满意：

MisterHouse：Perl 写的，但 2017 年就停止更新了
FHEM：Perl 写的，但架构设计有问题（”We do not like CPAN”、”Tests? That’s superfluous work!”）
Home Assistant：Python 写的，不够 “Perl”

于是他决定自己造轮子——WHIP (Witty House Infrastructure Processor)。这套系统使用 CAN 总线、STM32 微控制器、FreeRTOS，以及 Perl 作为上层控制语言。

在这个过程中，AI 帮他写了大量的代码：

Modbus 和 CANbus 工具
各种 API 接口（Discord、Reddit、Twitter、Kraken、Ollama、Proxmox…）
SNMP::MIB::Compiler（99.2% 的 MIB 解析通过率，比 Python 和 Go 的实现都好）
Grpc::FFI（326 个测试通过，零内存泄漏）

但这些都只是前奏，真正的主角是 pperl。

pperl：用 Rust 重写的 Perl 5 解释器

历史背景

在 Perl 5 的历史上，有过多次重写尝试：

项目	时间	结局
Topaz	1999	C++ 重写，放弃
B::C / perlcc	1996-2016	Perl 到 C 编译器，已死
cperl	2015-2020	Perl 5 分支，休眠
RPerl	-	受限 Perl 到 C++，休眠
WebPerl	-	Perl 到 WebAssembly，半活跃
PerlOnJava	-	JVM 上的 Perl 5，活跃

“Common failure mode: underestimating Perl 5’s complexity” 常见的失败模式：低估 Perl 5 的复杂性

pperl 的目标

兼容性：追求与 Perl 5.42 的最大兼容
性能：追求 V8 级别的性能
XS：不使用 XS，而是用原生 Rust 实现
平台：仅支持 Linux

目前状态：

22,000+ 测试
61-400 个失败（取决于如何计算）
性能表现：有好有坏，也有惊艳的

核心特性

1. 自动并行化（Autoparallelization）

使用 Rust 的 Rayon 库实现数据并行：

# 这段代码会自动并行执行
my @results = map { expensive_computation($_) } @large_list;
# 不需要 threads、MCE 或 forks
# pperl 检测安全的循环 → Rayon 处理其余部分

启用条件：

使用 --parallel 标志
列表元素 ≥ 1000
没有共享变量修改

2. JIT 编译

使用 Cranelift 作为 JIT 后端：

解释器正常运行，同时分析热点代码路径
检测到热点循环 → 降级为 Cranelift IR
Cranelift 编译为原生机器码
下一次迭代直接执行原生代码——零分发开销

Mandelbrot 基准测试结果：

基准测试	perl5	pperl 解释执行	pperl JIT	vs perl5
Mandelbrot	133ms	1493ms	41ms	3.2× 更快
Ackermann	13ms	630ms	12ms	1.1× 更快

完整嵌套循环 JIT：

Mandelbrot 1000×1000	perl5	pperl JIT	vs perl5
执行时间	12,514ms	163ms	76× 更快

JIT + 自动并行（8 线程）：

Mandelbrot	perl5	pperl JIT	pperl JIT + 8 线程	vs perl5
1000×1000	12,514ms	163ms	29ms	431× 更快
4000×4000	~200s	2,304ms	342ms	~580× 更快

“Perl. With JIT. That’s a sentence nobody expected.” Perl 加上 JIT。没人想到会有这种句子。

3. 自动 FFI（Auto-FFI）

不需要 XS、Inline::C 或编译，直接调用 C 库：

# Layer 0 —— 原始模式：任意库，你需要提供类型签名
use Peta::FFI qw(dlopen call);
my $lib = dlopen("libz.so.1");
my $ver = call($lib, "zlibVersion", "()p");
say "zlib: $ver"; # 1.3.1

# Layer 1 —— 预制模式：精选的函数签名，零配置
use Peta::FFI::Libc qw(getpid strlen strerror uname);
say strlen("hello"); # 5
my @info = uname();
say "$info[0] $info[2]"; # Linux 6.18.6-arch1-1

# Layer 2 —— 发现模式：扫描系统中的所有库
use Peta::FFI qw(scan dlopen call);
my $libs = scan();
say scalar(keys %$libs), " libraries found";

4. 字节码缓存（.plc）

类似 Python 的 .pyc，但用于 Perl：

# 默认：不缓存（适合开发）
$ pperl script.pl

# 启用：编译一次，后续运行从缓存加载
$ pperl --cache script.pl

# 清除所有缓存
$ pperl --flush

基准测试	perl5	pperl	pperl –cache
three_modules	22.3ms	12.6ms	9.9ms
mixed_native_fallback	26.3ms	13.0ms	10.0ms
deep_deps	18.1ms	13.1ms	9.9ms

模块加载成本降低 33-37%。

5. 守护进程化（Daemonize）

类似 Emacs 的 daemon/client 模式：

$ pperl --daemon script.pl  # 编译、预热、监听
$ pperl --client script.pl  # 连接 → fork → 运行 → 响应
$ pperl --stop script.pl    # 清理关闭

基准测试	perl5	pperl	–cache	–daemon
fallback + native mix	23.5ms	15.8ms	~10ms	5.0ms (3.2×)

通过 fork() 实现请求隔离，每个请求获得全新的地址空间，同时继承已编译的内存区域——零 I/O，零解析，零反序列化。

AI 的角色：导航员与执行者

Jelinek 强调，AI 不会独自完成这一切。成功的公式是：

人类：策略、架构、学习路径、优先级 AI：执行、文档、模式学习、迭代

以 gRPC 为例：

他决定”先做 UUID，然后 SQLite，最后 gRPC”
AI 执行每个阶段，记录经验教训，逐步升级

“Without the navigator — the AI builds impressive things that go nowhere. Without the AI — the navigator doesn’t have enough hours in the day.”

没有导航员，AI 会构建出令人印象深刻但无处可去的东西。没有 AI，导航员一天中没有足够的小时数。

兼容性：追求极致

Jelinek 分享了一个关于 $,（OFS）和 $\（ORS）在 print 中的行为差异的 bug 修复案例。

perl5 对两者的检查方式不同：

// perl5 — $, (OFS)
if (SvGMAGICAL(ofs) || SvOK(ofs))
// 检查 get-magic 和 ok-flags

// perl5 — $\ (ORS)
if (PL_ors_sv && SvOK(PL_ors_sv))
// 只检查 ok-flags，不检查 get-magic

pperl 最初对两者使用了相同的检查掩码，这是错误的。实际触发这个问题的概率几乎为零，但他们还是修复了它。

“The depth of compatibility is the product’s guarantee.” 兼容性的深度是产品的保证。

何时使用 pperl

适合：

受益于 JIT 和/或自动并行化的工作负载
使用原生内置模块的脚本（50+ Rust 模块，速度快）
快速启动——本身就比 perl5 快约 2 倍，加上 –cache 更快
pperl 特有功能：Auto-FFI、Daemonize、Bytecode Cache
安全性：不同的代码库——不太可能与 perl5 共享 CVE
较小、不太复杂的脚本

暂不适合：

大型、复杂的代码库——pperl 与 perl5 的边缘情况可能不同
如果不想修改代码，继续使用 perl5

经验法则：脚本越长越复杂，就越可能遇到边界情况。

彩蛋：psh——交互式 Perl Shell

演讲最后还展示了一个交互式 Perl shell：

ls "-la";      # 就是一个子程序调用
cd "/tmp";     # chdir 包装
ps "aux";      # 系统命令

# 但你已经在脚本语言中：
for my $f (glob("*.log")) {
    if (-M $f > 7) {
        rm $f;
        say "cleaned $f";
    }
}

支持对象管道——传递数据结构而非文本：

ps() | grep { $_->{mem} > 100_000 }
    | sort { $b->{cpu} <=> $a->{cpu} };

PowerShell 的哲学 + Perl 的文本处理能力 + pperl 的 JIT 速度

总结

这次演讲展示了一个令人兴奋的未来：AI 不仅能帮助我们写代码，还能帮助我们重新实现整个编程语言。pperl 项目证明了：

AI 可以处理极端复杂性——Perl 5 是出了名的复杂，但 AI 能够理解并重新实现它
人机协作是关键——人类提供方向，AI 提供执行力
性能提升可以是革命性的——431 倍甚至 580 倍的性能提升不是渐进式的改进，而是范式转移
兼容性可以被认真对待——即使是最小的边缘情况也被修复

项目地址：perl.petamem.com

这是一次令人印象深刻的工程实践，也是对”AI 时代程序员该如何定位自己”这个问题的一个回答：我们不是被替代，而是被赋能——前提是我们知道该往哪里走。