Sailhouse：用于构建和协调AI智能体的事件驱动控制平台

Sailhouse是一个面向开发者的事件驱动基础设施平台，它的核心定位是“智能体控制平面”。这个平台旨在帮助开发者快速、可靠地构建和发布AI智能体（Agent）和各类异步应用。传统的智能体开发常常需要复杂的编排框架或消息队列，而Sailhouse提供了一个更轻量的解决方案。它通过事件驱动的模式，让开发者可以定义动态的工作流程，从而协调多个智能体或服务之间的协作。无论是需要按时执行的计划任务，还是需要并行处理多个步骤的复杂工作流，Sailhouse都提供了相应的工具。该平台支持在AWS、GCP、Vercel等主流云服务上部署，并且与具体编程语言无关，开发者可以使用自己熟悉的技术栈进行开发。

機能一覧

• 时间触发器: 支持设置定时事件和Cron计划任务，可以在未来的特定时间点或按固定周期自动触发任务。
• 等待组 (Wait Groups): 允许将多个并行的任务组合在一起（Fan-out），并等待所有任务完成后再触发一个新事件（Fan-in），适合处理多步骤的复杂工作流。
• クロスプラットフォームの互換性: Sailhouse不限制代码的运行环境，无论是在AWS、Azure、GCP等主流云厂商，还是在Vercel、Netlify等Serverless平台，都可以正常工作。
• 灵活的事件接收模式: 同时支持“推送（Push）”和“拉取（Pull）”两种模式。开发者既可以配置一个HTTP端点来接收事件推送，也可以编写一个Worker主动从队列中拉取事件。
• 事件过滤: 允许在订阅时设置过滤规则，只接收符合条件的事件，避免处理不相关的消息。
• 制限速度: 可以控制事件的处理速率，防止下游服务因流量过载而崩溃。

ヘルプの使用

Sailhouse的设计理念是简化事件驱动应用的开发，让开发者可以专注于业务逻辑，而不用关心底层复杂的基础设施。下面将详细介绍如何使用Sailhouse的核心功能。

コア・コンセプト

在使用之前，了解三个基本概念很重要：

1. 事件 (Events): 事件是系统中发生的事情的记录，比如“用户完成支付”或“需要处理一个文件”。它通常包含描述事件的数据。
2. 主题 (Topics): 主题是事件的分类频道。生产者将特定类型的事件发布到对应的主题上。例如，所有关于代码审查的事件都可以发布到名为code-review的主题。
3. 订阅 (Subscriptions): 订阅是消费者消费事件的方式。消费者通过订阅一个或多个主题来接收它们感兴趣的事件。

インストールと設定

Sailhouse主要通过其官方提供的SDK与用户的应用程序进行交互。

1. アカウント登録: 首先，你需要在Sailhouse的官方网站上注册一个账号并登录到控制台（Console）。
2. アプリケーションの作成: 在控制台中，你需要创建一个应用（App）。创建后，系统会生成一个唯一的API密钥（API Key），这个密钥是你的应用程序与Sailhouse服务通信的凭证。
3. SDKのインストール: Sailhouse为不同编程语言提供了相应的SDK。以JavaScript/TypeScript为例，你可以使用npm或yarn进行安装：

   npm install @sailhouse/client
   

基础操作：发送和接收事件

1. 发送事件 (Publishing an Event)

发送事件非常直接。首先，在你的代码中初始化Sailhouse客户端，然后调用publish方法。

示例代码 (JavaScript):

import { Sailhouse } from '@sailhouse/client';
// 使用你在控制台获取的API密钥初始化客户端
const sailhouse = new Sailhouse({ apiKey: 'YOUR_API_KEY' });
async function publishReviewTask() {
await sailhouse.publish({
topic: 'security-review', // 指定要发布到的主题
data: { // 附带的数据
commitId: 'a1b2c3d4',
repo: 'my-project'
}
});
console.log('安全审查任务事件已发送。');
}
publishReviewTask();

2. 接收事件 (Receiving Events)

Sailhouse提供两种接收事件的方式：推送（Push）和拉取（Pull）。

方式一：推送 (Push Subscription)
这是最简单的方式。你只需要提供一个公开的HTTP(S) API端点（也称为Webhook）。当有新事件发布到你订阅的主题时，Sailhouse会立即将事件作为HTTP POST请求发送到你的这个端点。

• ワークフロー:
  1. 在你的项目中创建一个API路由，例如/api/webhooks/sailhouse.
  2. 在Sailhouse控制台中创建一个订阅，选择“Push”模式，并将你的API端点URL填入。
  3. 你的API端点会收到类似下面格式的JSON数据：

     {
     "id": "event_id_string",
     "topic": "security-review",
     "data": {
     "commitId": "a1b2c3d4",
     "repo": "my-project"
     }
     }
     

  4. 你的服务端代码接收到请求后，解析data字段并执行相应业务逻辑。

方式二：拉取 (Pull Subscription)
如果你的服务位于防火墙后或没有固定的公网IP，拉取模式是更好的选择。你的应用程序（通常称为Worker）会主动向Sailhouse请求事件。

• ワークフロー:
  1. 在Sailhouse控制台中创建一个订阅，并选择“Pull”模式。
  2. 在你的Worker代码中使用SDK的pull方法来获取事件。SDK会处理长轮询等细节，简化开发。

示例代码 (JavaScript Worker):

import { Sailhouse } from '@sailhouse/client';
const sailhouse = new Sailhouse({ apiKey: 'YOUR_API_KEY' });
async function processEvents() {
console.log('Worker启动，开始拉取事件...');
// 循环拉取指定订阅的事件
for await (const event of sailhouse.pull({ subscription: 'security-review-worker' })) {
try {
console.log('收到事件:', event.data);
// 在这里执行你的业务逻辑
// ...
// 任务处理完成后，确认事件已被成功处理
await event.ack();
} catch (error) {
console.error('处理事件失败:', error);
// 如果处理失败，可以选择让事件重新入队
await event.nack();
}
}
}
processEvents();

高级功能：使用等待组 (Wait Groups)

等待组是Sailhouse的特色功能，用于协调多个并行任务。当你需要确保一组任务全部完成后才能进行下一步时，这个功能非常有用。

例如，一个代码合并请求需要同时通过“安全审查”和“代码风格审查”两个流程。你可以使用sailhouse.wait来编排这个工作流。

示例代码 (JavaScript):

import { Sailhouse } from '@sailhouse/client';
const sailhouse = new Sailhouse({ apiKey: 'YOUR_API_KEY' });
async function startCodeReviewWorkflow() {
// `wait`方法会做两件事：
// 1. 立即将两个审查任务事件分别发送到'security-review'和'style-review'主题。
// 2. 创建一个监听器，等待这两个任务都完成后，自动向'code-review-complete'主题发送一个新事件。
await sailhouse.wait(
'code-review-complete', // 当所有任务完成后，向此主题发送事件
[
{
topic: 'security-review', // 第一个任务
data: { commitId: 'a1b2c3d4', repo: 'my-project' },
},
{
topic: 'style-review', // 第二个任务
data: { commitId: 'a1b2c3d4', repo: 'my-project' },
},
]
);
console.log('代码审查工作流已启动。');
}
startCodeReviewWorkflow();

通过这种方式，你无需自己编写复杂的状态管理逻辑来跟踪多个并行任务的进度。

アプリケーションシナリオ

1. AI智能体工作流编排
   当一个复杂的任务需要多个不同功能的AI智能体协作完成时，Sailhouse可以作为它们之间的协调中心。例如，一个“自动化报告生成”任务可能包括：数据搜集智能体、数据分析智能体、图表生成智能体和文本撰写智能体。Sailhouse可以使用等待组功能确保前序任务全部完成后，再触发后续任务，最终将所有结果汇总。
2. 异步后台任务处理
   在Web应用中，某些操作（如发送邮件、视频转码、生成数据报表）非常耗时，不应在用户请求中同步执行。开发者可以将这些任务作为事件发布到Sailhouse，由后台的Worker服务订阅并异步处理。这可以显著提升应用的响应速度和用户体验。
3. 计划性任务与数据同步
   对于需要定期执行的任务，例如每天凌晨备份数据库、每小时从第三方API同步一次数据，或者在特定日期向用户发送营销邮件，可以使用Sailhouse的Cron计划任务或定时事件功能。开发者只需定义好执行周期和任务内容，Sailhouse会确保任务被准时触发。

品質保証

1. Sailhouse所说的“控制平面”是什么意思？
   在Sailhouse的语境中，“控制平面”指的是一个用于协调和管理分布式组件（即智能体或服务）的基础设施层。它不侵入你的业务代码，也不是一个让你必须遵守其规则的“框架”。相反，它提供了一套工具（如事件路由、定时器、工作流编排），让你的各个独立服务能够相互通信和协作，你只需要关注每个服务自身的逻辑即可。
2. Sailhouse支持哪些编程语言和云平台？
   Sailhouse被设计为语言和平台无关的。它的核心是通过HTTP API或SDK进行交互，因此理论上任何能够发送HTTP请求的语言都可以使用它。官方会提供主流语言的SDK来简化开发。在部署方面，你的智能体或服务可以运行在任何地方，包括AWS、GCP、Azure等大型云平台，Vercel、Netlify等无服务器平台，甚至是本地的开发机器上。
3. 推送（Push）和拉取（Pull）订阅模式有什么区别，应该如何选择？
   推送模式是由Sailhouse主动将事件发送到你指定的URL。这种方式延迟低，实现简单，适合有固定公网IP的服务（如部署在服务器或Serverless函数上的API）。拉取模式则是由你的程序主动向Sailhouse请求事件。这种方式更灵活，适合运行在内网环境、开发环境或不方便暴露公网端口的服务。如果你的服务处理能力有限，拉取模式还可以让你根据自身负载来控制消费事件的速度。