Marico's space
最近在折腾 Agent（人工智能代理）集成方案，踩了几个坑才搞明白一件事：光靠 MCP（模型上下文协议）做生产级工具链，远远不够。这篇说说 Corsair 这个思路，值得琢磨。
大多数 Agent 集成工具都把你锁死在单一场景里。接好 MCP 服务器让 LLM 调用工具，然后后端定时任务要调 Slack、用户后台要接钉钉，你又得重写一套 OAuth 流程和 API 适配器。Corsair（GitHub 10937 星，TypeScript 趋势榜第 2）走了另一条路：REST-first 集成平台，同一个适配层同时服务 Agent、后端服务和用户界面。
这事重要，因为生产级 Agent 系统很少孤立存在。同一个集成能力，Agent 要用，定时任务要用，多租户管理后台要用，第三方服务推送 webhook 回调也要处理。纯 MCP 方案逼着你给每个场景维护一套独立的底层逻辑。
MCP 在 Agent 到工具的通信上做得不错，定义了 LLM 发现和调用函数的标准化方式。但 MCP 服务器是无状态的、会话范围的，设计上只支持同步请求-响应模式，根本不处理这些：
如果只做 MCP 方案，你最后要给每个非 Agent 场景写独立的 OAuth 处理器、独立的 API 客户端、独立的凭证存储。Corsair 的解法是在集成层前面加一层 REST API。同样的统一语法，不管调用方是 LLM、定时任务还是 React 组件，都能跑。
Corsair 的核心是一个 REST API，把第三方集成标准化。每个集成（钉钉、飞书、微信、企业微信等）都暴露一致的接口：
流程是这样的：
这样就解决了适配器重复的问题。集成逻辑写一次，各个场景都能用。
Corsair 提供两种部署模式：
| 部署方式 | OAuth 刷新 | Webhook 处理 | 数据所有权 | 运维负担 |
|---|---|---|---|---|
| 自托管 | 你自己管理 token 刷新循环 | 你自己暴露 webhook 端点 | 完全可控，在你自己的基础设施上 | 高（凭证存储、轮换、监控都要自己来） |
| 托管 Hub | Corsair 处理刷新 | Corsair 接收 webhook，转发给你 | 数据是你的，在 Corsair 基础设施上处理 | 低（Corsair 管理 OAuth 状态） |
自托管给你完全控制，但需要跑一个凭证存储、管理 token 刷新定时器、给 webhook 端点配好安全策略。托管 Hub 方案把 OAuth 状态管理外包出去，用户数据仍然在你的应用里。Webhook 先到 Corsair 基础设施，验证后转发到你的回调 URL。
对于生产级 Agent 系统，托管 Hub 减少了 OAuth token 过期导致的 bug 范围。自托管适合需要物理隔离的部署或者有严格数据驻留要求的场景。
Corsair 用 git 仓库里的 markdown 文件做知识层，而不是向量数据库或图存储。这是很有主见的选择，权衡很明显：
选 markdown + git 的理由：
代价：
这套方案对把集成当基础设施代码来管理的团队很友好。如果你需要动态的、用户生成的集成 schema 或者实时搜索集成元数据，它就不够用了。
下面是 Agent 工具调用穿过 Corsair 的完整流程：
// Agent 调用 Corsair 集成
const response = await fetch('https://api.corsair.dev/v1/integrations/slack/send-message', { method: 'POST', headers: { 'Authorization': `Bearer ${corsairApiKey}`, 'X-User-Context': userId // 多租户凭证查询 }, body: JSON.stringify({ channel: '#general', text: 'Agent-generated message' })
}); // Corsair 处理：
// 1. 用户凭证查询（userId + Slack 的 OAuth token）
// 2. Token 过期则自动刷新
// 3. 转换成 Slack API 格式
// 4. 限流处理
// 5. 错误标准化
// 6. 响应映射回统一 schema
后端任务用同样的端点：
// 定时任务，同样的语法
const response = await fetch('https://api.corsair.dev/v1/integrations/slack/send-message', { method: 'POST', headers: { 'Authorization': `Bearer ${corsairApiKey}`, 'X-User-Context': userId }, body: JSON.stringify({ channel: '#alerts', text: 'Scheduled report ready' })
});
用户后台也是同一个端点：
// React 组件，同样的语法
const sendMessage = async (channel: string, text: string) => { return fetch('https://api.corsair.dev/v1/integrations/slack/send-message', { method: 'POST', headers: { 'Authorization': `Bearer ${corsairApiKey}`, 'X-User-Context': currentUser.id }, body: JSON.stringify({ channel, text }) });
};
关键是这个 X-User-Context 请求头。Corsair 根据这个 Header 查到对应用户的 OAuth 凭证，处理 token 刷新，代理请求。调用方不需要知道 Slack API 长什么样，也不用管 OAuth 状态。
Corsair 的多租户设计建立了清晰的安全边界：
X-User-Context 里传用户 ID，Corsair 执行凭证所有权校验风险点：如果你把 API Key 泄露了，攻击者可以通过设置 X-User-Context 冒充任意用户。缓解方案：
对 Agent 系统来说，这意味着你的 LLM 不会意外访问其他用户的集成。用户上下文必须显式传递，Corsair 强制执行边界。
Corsair 抽象了集成层，如果你不仔细埋点，就会出现可观测性盲区：
需要记录的日志：
slack.send-message）需要追踪的链路：
需要告警的指标：
不埋这些点的话，你只会看到"集成失败"的错误，但分不清问题是出在 Corsair 转换层、供应商 API 还是凭证过期。
| 故障模式 | 症状 | 应对 |
|---|---|---|
| OAuth token 过期 | Corsair 返回 401 | Corsair 会自动刷新，但如果 refresh token 也失效了，用户必须重新认证。在你的 UI 里实现重新认证流程。 |
| 供应商 API 限流 | 429 错误 | Corsair 不会排队请求。在你的 Agent 编排层实现指数退避。 |
| Webhook 投递失败 | 第三方事件丢失 | Corsair 会重试 webhook，但如果你的端点挂了，事件就丢了。用消息队列缓冲入站 webhook。 |
| 凭证查询延迟 | 工具调用慢 | Corsair 会缓存凭证，但冷启动还是慢。高频集成提前预热缓存。 |
| 供应商 API schema 变更 | 响应格式异常 | Corsair 维护适配器，但新字段可能没有映射。生产环境锁定集成版本。 |
最大的运维风险是 OAuth token 过期。如果用户的 refresh token 失效了（用户撤销了授权、改了密码等），Corsair 无法自动刷新。你的应用需要一个重新认证流程，引导用户重新连接。
适合的场景：
不适合的场景：
Corsair 解决了一个真实问题：Agent、后端和用户界面场景下集成逻辑的重复。把 REST API 放在 OAuth 流程和第三方 API 前面，让你写一次集成逻辑，各个场景都能用。markdown + git 知识层对把集成当代码管理的团队是合理选择，但不支持扩展到几千个动态生成的 schema。
托管 Hub 是大多数团队的正确默认值。自托管只在有严格数据驻留要求或者需要物理隔离时才值得考虑。无论哪种方式，你都需要仔细埋点 OAuth token 刷新失败和供应商限流的情况，因为 Corsair 抽象掉了帮你排查集成问题的细节。
如果你要做多租户 Agent 系统，需要访问用户已连接的 SaaS 工具，Corsair 能省掉大量重复的适配器代码。如果你只需要 Agent 到工具的通信，乖乖用 MCP。REST 层是你不需要的额外复杂度。