Caspian：让 AI Agent 自由穿梭于人类通信网络

痛点切入：一个客服 Agent 的"信息孤岛"困境

想象一下：你的 AI 客服 Agent 部署在 Slack 上，用户 A 上午在 Slack 发起咨询，下午换了个邮箱继续追问——然后你的系统里出现了两个互不相干的对话线程，Agent 需要重新理解上下文。更糟糕的是，Discord 用户 B 也接入了同一个 Agent，GitHub Issue 也接入了，三个平台各自有一套 bot token、webhook 验证逻辑、消息格式、线程管理方案……

这就是当前 AI Agent 生态的真实写照：每个通信渠道都是一座孤岛，每个孤岛都需要单独维护。

Caspian（舄海豚）想解决的就是这个困境——让 AI Agent 用同一个身份、同一套代码，自由地与人对话，无论对方用的是 Slack、Discord、Telegram、Email，还是 Instagram、WhatsApp、X。

背景故事：从 25 个 Adapter 中提炼出的共识

Caspian 的团队在正式启动开发前，调研了 42 个开源 Agent 项目，统计发现：头部 Agent 框架各自维护着 25+ 个渠道适配器，但这些问题追踪器里仍有 8-15% 的 issue 与"渠道集成"相关——这些 issue 不会让 Agent 更聪明，只是让它更难维护。

这揭示了一个本质问题：通信基础设施不是 Agent 的能力，而是 Agent 的税。最大的几个开源 Agent 框架——CrewAI、LangChain Agents——都在无休止地修复 Slack API 变更、Telegram bot token 过期、Discord webhook payload 漂移……这些问题与 Agent 的核心推理能力无关，却吞噬了大量工程资源。

Caspian 的创始团队决定把这个"税"抽象出来，做成一个通用的 Agent 通信层。

类比解释：Caspian 是 Agent 的"通信操作系统"

如果说 AI Agent 是应用程序，那么 Caspian 就是应用程序下层的操作系统（OS）：

• 操作系统屏蔽硬件差异——上层 App 不需要知道键盘是 USB 还是蓝牙，只需调用统一的输入 API。
• Caspian 屏蔽渠道差异——上层 Agent handler 不需要知道消息来自 Telegram 还是 Email，只需调用 message.reply()。

这种设计理念让 Agent 的开发者可以专注于"说什么"，而不是"怎么发"。

核心功能：三层架构解决三个问题

第一层：消息归一化（Normalization）

每条消息进入 Caspian gateway 时，都被转换为统一的 message 对象：

来源平台  →  gateway（签名验证 + 归一化）  →  统一 Message 模型  →  Agent handler

这意味着无论消息来自哪个渠道，Agent 接收到的数据结构完全一致：

@client.on_message
def handle(message):
    sender = message.sender.address  # 不管是 email / telegram / discord
    message.reply(f"You said: {message.text}")  # 自动回复到正确的线程

第二层：身份与线程管理

Caspian 引入了 "one agent identity" 的概念——Agent 在所有渠道上共享同一个身份，用户跨渠道对话自动汇聚到同一个线程中。这解决了传统方案里"同一个用户在不同渠道是不同联系人"的问题。

第三层：渠道能力协商（Capability Negotiation）

每个渠道的适配器会声明自己"能做什么"：

• Discord/Telegram 支持"正在输入…"提示（typing indicator）
• SMS 只支持纯文本
• Slack 支持 Block Kit 富文本
• Email 支持 HTML 富文本

Agent 通过 client.behavior_prompt() 获取每个渠道的"礼仪规范"，将其加入 system prompt，从而学会"在什么渠道说什么话"。

技术细节：FastAPI 网关 + 插件化 Provider 架构

从代码结构看，Caspian 分为两大部分：

服务端（server/）：自托管的 FastAPI 网关，位于 server/src/comm_gateway/providers/ 的每个目录对应一个渠道实现，每个适配器只需实现四个方法：provision（配置资源）、send（发送消息）、reply（回复）、parse_webhook（解析回调）。所有渠道都做了真实的 webhook 签名验证（Slack signing secret、Telegram secret header、X CRC、signed email）。

客户端 SDK（sdks/python/ + sdks/typescript/）：Python SDK 通过 pip 安装（pip install caspian-sdk），TypeScript SDK 通过 npm 安装，零运行时依赖，Node 18+ 兼容。两者 API 契约一致，上手文档极为友好。

CLI 工具（apps/cli/）：caspian init 初始化项目，caspian connect <channel> 交互式连接频道，一条命令即可完成 Telegram Bot 的接入。

pip install caspian-sdk
pipx install caspian-cli   # 或 uvx caspian-cli
caspian init
caspian connect email        # 免费，即时生效
caspian connect telegram     # 填入 bot token

测试覆盖：Python + TypeScript 各有 100+ 和 31 个离线测试用例（vitest），所有测试均为"假渠道"（fake adapters），无需网络即可验证。

部署体验：docker compose 一键启动

docker compose up

这条命令会启动：Postgres 数据库 + FastAPI gateway（comm-gateway），监听在 http://localhost:8000，使用内存中的 fake provider（无需任何凭证）。开发者只需将 SDK 指向本地地址即可开始测试：

client = CommClient(
    base_url="http://localhost:8000",
    api_key="comm_dev_key_change_me"
)

若要启用真实渠道，从 server/.env.example 复制配置并填入对应 token（Slack、Discord、Telegram、Email 等），然后取消 docker-compose.yml 中的 env_file 注释即可。

支持渠道一览

渠道	自托管（用自己的凭证）	托管服务
Email（Gmail）	✅	✅ 即时 Inbox
Telegram Bot	✅	✅
Discord	✅	✅ 一键接入
Slack	✅	✅ 一键接入
Bluesky	✅	✅
GitHub Issues/PR	✅	—
Instagram DM	✅	✅
Facebook Messenger	✅	✅
X/Twitter	✅ *	✅
WhatsApp Business	—	✅ 一键接入
SMS（GSM modem）	✅ *	—

*X 需要付费 X API 订阅（免费版仅支持写）；Telegram 用户账号自动化属 ToS 灰色地带；GSM SMS 需自备 modem 和 SIM 卡。

争议与局限：云端依赖与 AGPL 约束

托管模式的隐忧

Caspian 默认连接 https://api.trycaspianai.com（官方托管网关）。这意味着：Agent 的消息流量经过 Caspian 的服务器。虽然官方表示不读取消息内容，但这是一个不可忽视的隐私风险——尤其是企业客户在处理敏感信息时。

自托管虽然完全可行，但需要维护 Postgres + FastAPI 服务，有一定的运维成本。官方文档对此着墨不多，入门用户可能默认选择托管模式而未意识到数据去向。

AGPL 许可证的约束

server/ 目录（即 comm-gateway 自托管网关）采用 AGPL-3.0 许可证。这比 Apache/MIT 严格得多——如果你修改了网关代码并以服务形式对外提供，必须开源你的修改（即使只改了前端界面）。这对于希望深度定制企业通信功能的公司来说是一个硬约束。

相比之下，sdks/（Python + TypeScript 客户端）和 apps/cli（CLI 工具）采用 MIT 许可证，非常宽松——可以在任何项目中免费使用，无需开源。

付费渠道的现实成本

X、WhatsApp、iMessage 等渠道需要付费 API 订阅或平台账号认证。"一键接入"的体验依赖额外的资金投入，实际落地时需纳入成本核算。

行业意义：填补 Agent-to-Human 通信的空白

当前 AI 领域的协议热点是 A2A（Agent-to-Agent） 和 ACP（Agent Communication Protocol）——这些解决的是 Agent 之间如何对话的问题。但 Caspian 另辟蹊径，专注于 Agent-to-Human 的通信层——如何让 Agent 自然地与人类用户交互。

这是一个被低估的需求。随着 AI Agent 逐渐从"技术玩具"走向"生产工具"，每个 Agent 都需要一个"出口"——通过用户日常使用的渠道触达用户。Caspian 正是这个需求的系统性解法。

其 monorepo 架构（server/ + sdks/ + packages/ + apps/）设计清晰，Python + TypeScript 双语言支持覆盖了大多数 Agent 开发场景。与 OpenClaw、OpenCode 等主流 Agent 框架的集成（已有现成插件）进一步降低了迁移成本。

快速上手建议

推荐路径（面向 AI 开发者）：

1. pip install caspian-sdk + pipx install caspian-cli
2. caspian init → 生成 .env 配置
3. caspian connect email → 立即获得一个免费专属 Agent 邮箱地址
4. 写一个 on_message handler，Agent 即可通过邮件与人对话
5. 想加渠道？再加一行 connect_*()

进阶路径：

• 想自托管？docker compose up 直接启动完整服务
• 想深度定制？Fork server/ 并遵守 AGPL 义务
• 想接入 OpenClaw？clawhub install @trycaspian/caspian