Sloppy：基于规则优先架构的AI智能体运行时设计与实践

1. 项目概述：一个为“氛围编程”而生的AI智能体运行时

如果你和我一样，是个喜欢在深夜听着音乐、沉浸在代码世界里的“氛围型”开发者，那你肯定也烦透了那些重复、枯燥的“脏活累活”。比如，为不同的项目搭建相似的环境、编写千篇一律的CRUD接口、或者手动整理和分析日志数据。我们渴望将创造力集中在核心逻辑和架构设计上，而不是被繁琐的流程所困。这正是我最近深度体验并投入使用的Sloppy项目试图解决的问题。它不是一个简单的聊天机器人，而是一个用 Swift 6 编写的、面向 macOS 和 Linux 的多智能体运行时，旨在构建“操作员可见”的AI工作流。

简单来说，Sloppy 为你打造了一个由AI专家组成的“虚拟团队”。你可以把这个团队想象成你的私人助理团：一个负责处理 Telegram 上的用户反馈，一个在后台持续监控系统日志并生成报告，另一个则专门负责根据你的指令生成代码片段。Sloppy 的核心价值在于，它让这些AI智能体的工作变得结构化、可观察、可恢复。你不会再面对一个黑盒，不知道AI在干什么、干到哪一步了；相反，你能通过一个清晰的仪表盘，实时看到每个“员工”（智能体）的工作状态、执行记录和产出物，并在任何时候进行干预或调整。

2. 核心架构与设计哲学：为什么是“规则优先”？

在深入代码之前，理解 Sloppy 的设计哲学至关重要。市面上很多AI智能体框架倾向于将所有决策权交给一个大语言模型（LLM），让LLM来决定下一步该调用哪个工具、执行什么操作。这种方式虽然灵活，但带来了两个显著问题：不确定性和不透明性。你很难预测或复现智能体的行为，一旦流程变长，调试就像在迷宫里找路。

Sloppy 采用了截然不同的“规则优先”路径。它将一个工作流拆解为几个核心的运行时实体，并通过一套基于规则的、确定性的路由机制来协调它们。这听起来有点抽象，让我用一个开发中的实际场景来类比。

假设我要构建一个自动化的代码审查助手工作流。在传统LLM驱动的方式下，我可能会给AI一个庞大的提示词：“请审查这个Pull Request，检查代码风格、潜在Bug和安全问题，然后生成评论。”整个过程是单次、黑盒的。

而在 Sloppy 中，我会这样设计：

1. Channel（频道）：这代表一个交互入口。比如，一个与GitHub Webhook集成的频道，专门接收新的PR事件。
2. Rule-based Router（基于规则的路由器）：当频道收到PR事件时，不是直接将事件丢给LLM，而是先经过一个规则引擎。这个引擎根据预定义的规则（例如，IF 事件类型是 “pull_request” AND 仓库是 “backend-service” THEN 路由到 “CodeReviewBranch”）做出决策。这个决策过程是确定且可审查的。
3. Branch（分支）：代表一个独立的、专注的工作流。CodeReviewBranch就是一个专门处理代码审查逻辑的分支。分支内部可以维护自己的状态和上下文。
4. Worker（工作者）：分支中的具体执行单元。我可以创建多个Worker：一个StyleCheckWorker专门用clang-format或SwiftLint检查代码风格；一个SecurityScanWorker调用静态分析工具；一个CommentGenerationWorker负责汇总前两者的结果，并调用LLM生成人性化的审查意见。这些Worker可以并行或串行执行。
5. Compactor（压缩器）：当CommentGenerationWorker与LLM的对话历史（上下文）太长时，Compactor 会自动触发，将冗长的历史总结成精炼的要点，以节省token并保持上下文清晰。
6. Visor（监视器）：它就像一个项目经理，定期生成“项目简报”（Bulletins），告诉我过去一段时间内，所有代码审查分支的处理情况、平均耗时、发现的主要问题类型等。这让我对整个系统的运行状况一目了然。

这个架构的核心优势在于“关注点分离”和“状态持久化”。每个组件职责单一，它们之间的交互通过明确的规则和事件来驱动，并且所有的状态、事件、产物（Artifacts）都被持久化到 SQLite 数据库中。这意味着如果某个 Worker 执行失败，我可以轻松地查看失败时的完整上下文，手动修复后让工作流从断点继续，而不是重头开始。这种确定性和可观察性，对于构建可靠的、长期运行的自动化流程来说是基石。

注意：Sloppy 的“规则优先”并不意味着排斥AI。相反，它是在用确定的规则搭建一个稳固的舞台，然后让AI在这个舞台上扮演它最擅长的角色（如内容生成、复杂判断），而不是让AI去管理舞台本身。这大大降低了系统的整体复杂度。

2.1 核心运行时模型深度解析

让我们拆开 Sloppy 的AgentRuntime看看这些核心实体是如何具体运作的。

Channel（频道）：你可以把它理解为一个“消息总线”或“事件源”。它负责从外部世界（如Telegram聊天、Discord服务器、HTTP API请求）接收原始输入，并将其标准化为内部的ChannelEvent。频道插件（如TelegramGateway）负责这种适配工作。一个运行时可以同时运行多个频道，互不干扰。

Branch（分支）与 Worker（工作者）：这是执行逻辑的核心载体。Branch 是一个状态容器，它持有当前工作流的上下文（Context）。Worker 则是附着在 Branch 上的执行单元。Sloppy 支持两种 Worker 模式：

• 交互式 Worker：类似于一个聊天会话，可以多轮对话，上下文会不断累积。适合需要反复沟通、探索的任务。
• 发射后不管式 Worker：接收输入，执行一个特定任务（如调用一个API，运行一段脚本），产生输出，然后结束。适合定义明确的自动化步骤。

关键设计在于，Branch 和 Worker 的生命周期事件（创建、启动、暂停、完成、失败）都会被记录为RuntimeEvent，并连同产生的任何Artifact（如生成的文本、代码文件、报告链接）一起存入数据库。这构成了系统完整的“审计日志”。

Compactor（压缩器）：这是一个防止上下文无限膨胀的智能组件。它监视 Branch 的上下文长度（通常是Token数）。当长度超过预设阈值时，Compactor 会被触发。它的工作是将当前冗长的对话历史，通过调用LLM，总结成一段简短的、包含核心信息的摘要，然后用这个摘要替换掉旧的历史。这个过程称为“压缩”。它确保了工作流可以长期运行，而不会因为上下文窗口限制而丢失早期的重要信息，同时有效控制了API调用成本。

Visor（监视器）：这是面向系统操作员（也就是你）的“仪表盘生成器”。它定期（例如每小时）运行，扫描所有 Branch 和 Worker 的活动，分析事件日志和产物，生成结构化的Bulletin（简报）。这些简报可能包括：“过去一小时处理了12个PR审查请求，平均耗时5分钟”，“SecurityScanWorker在项目X中发现了3个高危漏洞”。Visor 将这些简报推送至仪表盘或你配置的通知频道，让你无需深入细节就能掌握全局。

3. 从零开始：部署与配置你的第一个Sloppy智能体

理论讲得再多，不如亲手跑起来。下面我将带你完成一个最小化的 Sloppy 部署，并配置一个简单的“智能待办事项生成器”工作流。

3.1 环境准备与安装

Sloppy 的核心是 Swift 服务端，因此你需要一个 Swift 6 环境。macOS 用户安装最新版 Xcode 命令行工具即可。Linux 用户（以 Ubuntu 22.04 为例）需要多几个步骤。

# 对于 Ubuntu/Debian 系统 sudo apt-get update sudo apt-get install -y clang libsqlite3-dev # 安装 Swift 工具链 # 访问 https://www.swift.org/download/ 获取最新版链接 wget https://download.swift.org/swift-6.0-release/ubuntu2204/swift-6.0-RELEASE/swift-6.0-RELEASE-ubuntu22.04.tar.gz tar xzf swift-6.0-RELEASE-ubuntu22.04.tar.gz sudo mv swift-6.0-RELEASE-ubuntu22.04 /usr/share/swift echo 'export PATH=/usr/share/swift/usr/bin:$PATH' >> ~/.bashrc source ~/.bashrc

验证安装：

swift --version # 应显示 Swift 6.x

接下来，克隆并安装 Sloppy：

git clone https://github.com/TeamSloppy/Sloppy.git cd Sloppy # 使用安装脚本，它会处理依赖编译和资源构建 bash scripts/install.sh

安装脚本会编译sloppy可执行文件、构建 React 仪表盘的前端资源，并完成初始配置。如果你只想先运行后端API，可以加上--server-only参数。

安装完成后，启动服务：

sloppy run

默认情况下，服务会启动在：

• API 服务器:http://localhost:25101
• 仪表盘:http://localhost:25102

打开浏览器访问http://localhost:25102，你应该能看到 Sloppy 的仪表盘登录界面。初始状态下，系统使用一个内置的默认配置运行，还没有连接任何AI模型提供商。

3.2 核心配置详解：连接你的AI大脑

Sloppy 本身不提供AI模型，它是一个“调度中心”，需要通过插件连接 OpenAI、Anthropic、Ollama（本地运行大模型）等提供商。配置位于Workspace/目录下的config.yaml文件中。

一个最基础的、连接 OpenAI 的配置示例如下：

# Workspace/config.yaml workspace: root: "." # 工作区根目录，存放数据库、日志等 name: "MySloppyWorkspace" runtime: http: port: 25101 dashboard: port: 25102 # 插件配置 plugins: models: # 定义一个名为 `my-gpt-4` 的模型配置 - id: "my-gpt-4" provider: "openai" # 对应 PluginSDK 中的 OpenAI 插件 config: apiKey: ${OPENAI_API_KEY} # 建议从环境变量读取，避免密钥硬编码 model: "gpt-4-turbo-preview" defaultParameters: temperature: 0.7 maxTokens: 2000 # 可以同时配置多个模型，供不同场景的 Worker 选用 # - id: "my-claude" # provider: "anthropic" # config: ... # 网关插件配置，例如启用 Telegram 机器人 gateways: - id: "my-telegram-bot" provider: "telegram" config: botToken: ${TELEGRAM_BOT_TOKEN} # 其他配置...

你需要将OPENAI_API_KEY设置到环境变量中。在启动sloppy run前，在终端执行：

export OPENAI_API_KEY='你的-openai-api-key'

重要安全提示：永远不要将API密钥直接写入config.yaml并提交到版本控制系统。务必使用环境变量（${VAR_NAME}）或安全的密钥管理服务。config.yaml文件应被视为可能包含敏感信息的文件，将其加入.gitignore是标准做法。

3.3 构建你的第一个工作流：自动化待办事项生成

假设我们想创建这样一个工作流：每天上午9点，通过HTTP API触发，让AI根据我今天的日历事件和昨日未完成的任务，自动生成一份今日待办事项清单，并发送到我的Telegram。

步骤1：定义规则（Routing Rules）我们需要在配置中告诉 Sloppy，当收到特定类型的请求时该做什么。这通常在config.yaml的routing部分定义，但更动态的方式是通过API创建。为了入门，我们先理解概念。规则可能像这样：

• IF请求路径是/webhook/daily-planAND请求方法是POST
• THEN创建一个新的 Branch，类型为DailyPlanningBranch

步骤2：创建 Branch 和 Worker 逻辑我们需要编写 Swift 代码来定义DailyPlanningBranch的行为。在 Sloppy 项目中，这通常在Sources/目录下创建新的文件。

// Sources/MyWorkflows/DailyPlanningBranch.swift import SloppyCore public struct DailyPlanningBranch: BranchProtocol { public let id: BranchID public var context: BranchContext // 存储日历事件、昨日任务等状态 // 初始化时可能接收来自HTTP请求的数据 public init(id: BranchID, initialData: [String: Any]) { self.id = id self.context = BranchContext(data: initialData) } // Branch 启动时会调用此方法 public func run() async throws { // 1. 创建第一个 Worker：获取日历事件 let fetchCalendarWorker = FetchCalendarWorker(branchID: self.id) let calendarEvents = try await fetchCalendarWorker.perform() // 2. 创建第二个 Worker：获取昨日遗留任务（可能从另一个系统API） let fetchPendingTasksWorker = FetchPendingTasksWorker(branchID: self.id) let pendingTasks = try await fetchPendingTasksWorker.perform() // 3. 创建核心 Worker：调用LLM生成计划 let planningWorker = DailyPlanningLLMWorker( branchID: self.id, modelID: "my-gpt-4", // 使用配置中定义的模型 inputs: ["calendar": calendarEvents, "pendingTasks": pendingTasks] ) let todaysPlan = try await planningWorker.perform() // 4. 创建第四个 Worker：将计划发送到Telegram let telegramWorker = SendToTelegramWorker( branchID: self.id, channelID: "my-telegram-bot", // 使用配置的网关ID message: todaysPlan ) try await telegramWorker.perform() // 所有Worker执行完毕，Branch 标记为完成 self.context.complete() } } // 一个简单的 Worker 示例：调用LLM struct DailyPlanningLLMWorker: WorkerProtocol { let branchID: BranchID let modelID: String let inputs: [String: Any] func perform() async throws -> String { // 构建给LLM的提示词 let prompt = """ 你是一个高效的私人助理。以下是我今天的日历事件和昨天未完成的任务： 日历事件：\(inputs["calendar"] ?? []) 昨日遗留：\(inputs["pendingTasks"] ?? []) 请为我生成一份清晰、优先级分明的今日待办事项清单。格式为Markdown列表。 """ // 通过 Sloppy 的运行时获取模型实例并调用 let model = try await Runtime.shared.model(for: modelID) let response = try await model.generateText(from: prompt) // 将LLM的响应作为产物保存到数据库，便于后续查看 let artifact = Artifact( branchID: self.branchID, workerID: self.id, type: .text, content: response, metadata: ["purpose": "daily_plan"] ) try await artifact.save() return response } }

步骤3：注册工作流并触发编写完代码后，需要将其编译并注册到 Sloppy 运行时。一种方式是通过插件机制，另一种更直接的方式是在初始化运行时加载这些 Branch 定义。然后，你就可以通过向http://localhost:25101/api/v1/branches发送一个 POST 请求来手动触发这个工作流，或者使用系统的定时任务（如cron）在每天9点自动调用这个API。

# 使用 curl 手动触发 curl -X POST http://localhost:25101/api/v1/branches \ -H "Content-Type: application/json" \ -d '{ "type": "DailyPlanningBranch", "initialData": {"trigger": "manual"} }'

触发后，你可以在仪表盘的“活动”页面实时看到这个 Branch 被创建、各个 Worker 依次执行、以及最终产出的待办事项清单 Artifact。整个过程的日志和状态变化一览无余。

4. 插件系统深度探索：如何扩展 Sloppy 的能力

Sloppy 的强大扩展性源于其插件系统（PluginSDK）。它定义了清晰的边界，让你可以轻松集成新的模型提供商、工具、记忆存储和网关，而无需修改核心运行时代码。

4.1 模型插件：连接任何 LLM

Sloppy 通过AnyLanguageModel协议抽象了不同的LLM提供商。要添加一个新的模型（比如接入本地部署的Llama 3通过 Ollama），你本质上需要实现一个符合该协议的插件。

假设我们要创建一个OllamaModelPlugin：

1. 定义插件结构：在独立的 Swift Package 中，定义一个实现了ModelPlugin协议的类型。
2. 实现请求逻辑：在插件内部，处理与 Ollama 本地 API (http://localhost:11434/api/generate) 的通信，将 Sloppy 内部的通用请求格式转换为 Ollama 所需的格式，并处理响应。
3. 注册插件：在插件的入口点，使用PluginRegistry注册你的OllamaModelPlugin。
4. 更新配置：在config.yaml中，就可以像使用openai一样使用你的ollama提供商了。

plugins: models: - id: "my-local-llama" provider: "ollama" # 你自定义的插件标识符 config: baseURL: "http://localhost:11434" model: "llama3:8b"

这种设计使得切换或测试不同模型变得极其简单，只需在配置文件中更改modelID引用即可。

4.2 工具插件：赋予智能体“手脚”

智能体除了思考，还需要能执行动作，比如读写文件、查询数据库、调用外部API。Sloppy 的Tool协议就是为此而生。一个工具插件可以暴露多个具体的工具函数。

例如，创建一个FileSystemTool：

public struct FileSystemTool: Tool { public var name: String = "read_file" public var description: String = "读取指定路径文件的内容" public var parameters: [String: Any] = ["path": "文件路径字符串"] public func execute(with parameters: [String: Any]) async throws -> String { guard let path = parameters["path"] as? String else { throw ToolError.invalidParameters } let contents = try String(contentsOfFile: path, encoding: .utf8) return contents } }

然后，在你的 Worker 中，可以通过运行时获取这个工具并调用它：

let fileTool = try await Runtime.shared.tool(named: "read_file") let fileContent = try await fileTool.execute(with: ["path": "/path/to/note.md"])

这样，你的AI智能体就具备了读取文件的能力。同理，你可以创建发送邮件、执行Shell命令、查询数据库等任何你需要的工具。

4.3 网关插件：连接更多交互渠道

内置的 Telegram 和 Discord 网关展示了如何将外部聊天平台接入 Sloppy 的 Channel 系统。如果你需要接入 Slack、钉钉、甚至电子邮件，遵循相同的模式开发一个网关插件即可。网关的核心职责是双向转换：将外部平台的消息转换为标准的ChannelEvent，并将来自 Sloppy 的响应转换回外部平台的格式。

5. 生产环境考量、监控与问题排查

将 Sloppy 用于个人自动化是一回事，用于团队或生产环境则需要更多考量。

5.1 部署与高可用

对于生产部署，建议使用Docker容器化。Sloppy 仓库提供了Dockerfile示例。你可以构建镜像，并通过docker-compose或 Kubernetes 来管理服务、数据库（如果使用PostgreSQL替代SQLite）和反向代理（如 Nginx）。

# 基于官方 Swift 镜像构建 FROM swift:6.0 AS builder WORKDIR /app COPY . . RUN bash scripts/install.sh --server-only FROM ubuntu:22.04 # 安装运行时依赖，如 libsqlite3 COPY --from=builder /app/.build/release/sloppy /usr/local/bin/ COPY --from=builder /app/Workspace /app/Workspace WORKDIR /app EXPOSE 25101 CMD ["sloppy", "run", "--config", "/app/Workspace/config.production.yaml"]

关键的生产配置调整包括：

• 数据库：对于高负载场景，考虑将 SQLite 替换为 PostgreSQL。这需要实现一个符合PersistencePlugin的插件。
• 配置管理：使用环境变量或专业的配置管理工具（如 HashiCorp Vault）来管理敏感信息。
• 日志与监控：Sloppy 会输出结构化日志（JSON格式）。你可以配置日志驱动，将日志发送到 ELK Stack、Datadog 或 Grafana Loki 进行集中分析和告警。

5.2 性能调优与成本控制

1. Worker 并发：合理设计工作流，让可以并行的 Worker 同时执行，缩短整体流程耗时。Sloppy 的运行时支持异步并发执行。
2. 上下文管理：善用Compactor。为不同的 Branch 类型设置合理的上下文长度阈值。对于需要长期记忆但交互频繁的对话型任务，阈值可以设低一些（如 2000 tokens），触发频繁压缩以节省成本。对于一次性的分析任务，阈值可以设高或关闭压缩。
3. 模型选择：在配置中为不同的 Worker 分配合适的模型。不需要高创造性的总结任务可以使用更便宜、更快的模型（如gpt-3.5-turbo），而需要复杂推理和代码生成的任务再使用gpt-4。
4. 错误重试与降级：在自定义 Worker 中实现健壮的错误处理。例如，当主要模型API调用失败时，可以自动降级到备用模型或执行一个简化的本地逻辑。

5.3 常见问题排查实录

在实际使用中，你可能会遇到以下典型问题：

实操心得：日志是你的第一道防线。养成在开发复杂 Worker 时大量使用Runtime.log记录关键状态和中间结果的習慣。Sloppy 的仪表盘提供了非常好的日志聚合和筛选视图，能帮你快速定位问题。对于生产环境，务必配置日志的持久化和轮转策略，避免日志文件撑满磁盘。

6. 进阶应用场景与生态展望

当你熟悉了 Sloppy 的基础后，可以探索更强大的应用模式：

场景一：多智能体协作研发创建一个CodeReviewBranch，其中包含三个 Worker：LinterWorker（调用 ESLint/SwiftLint）、SecurityScanWorker（调用 Semgrep）、HumanLikeReviewWorker（调用 GPT-4 生成代码评语）。通过规则路由，将 GitHub 的 PR 事件自动分配给这个分支。三个 Worker 并行执行，最后HumanLikeReviewWorker汇总前两者的结果，生成综合评语并提交回 GitHub。整个流程在仪表盘上清晰可见，任何环节失败都可以重试或手动介入。

场景二：7x24小时智能客服与工单分类通过 Telegram/Discord 网关接入用户咨询。一个TriageBranch首先启动，其中的IntentClassificationWorker使用一个轻量级模型快速判断用户意图（如“技术问题”、“账单咨询”、“功能请求”）。根据分类结果，路由规则将其分派到不同的专业处理分支：TechnicalSupportBranch、BillingBranch或FeatureRequestBranch。每个分支都有更专业的工具和知识库来处理对应问题。Visor 每天生成客服简报，总结问题类型分布和解决率。

场景三：个人知识库的持续消化与问答开发一个KnowledgeDigestBranch，它订阅你的 RSS 源、稍后读列表（如 Pocket）、或是笔记文件夹（如 Obsidian）。定期（如每小时）运行，FetchContentWorker获取新内容，SummarizationWorker调用 LLM 进行摘要，VectorizeWorker将摘要存入向量数据库（如通过工具插件连接 ChromaDB）。最后，你可以通过一个QABranch来向你的个人知识库提问，RetrievalWorker从向量库搜索相关摘要，AnswerGenerationWorker合成最终答案。

Sloppy 的插件化架构和清晰的运行时模型，使得构建这类复杂、可观察、可维护的智能体系统变得前所未有的清晰。它可能不是那个能一键解决所有问题的“魔法按钮”，但它提供了搭建属于你自己的、可靠AI自动化帝国所需的全部脚手架和蓝图。从我个人的使用体验来看，它将我从“提示词工程”的泥潭中解放了出来，让我能更专注于定义工作流的逻辑和规则，而把不确定的部分交给专业的AI模型去发挥。这种确定性与灵活性的结合，正是当前AI应用从玩具走向工具的关键。