octo-santa：本地优先的多智能体协作框架，让 AI Agent 真正「对话」

octo-santa 是一个无需基础设施的本地优先智能体协作框架，通过 SQLite 和 Markdown 实现智能体间的消息传递、知识共享和领域发现，解决了单智能体上下文过载和多智能体协作难题。

• 原作者/维护者: jayfeng0625
• 来源平台: GitHub
• 原文标题: octo-santa
• 原文链接: https://github.com/jayfeng0625/octo-santa
• 发布时间: 2025年

---

当前 AI Agent 面临一个根本性矛盾：随着系统规模扩大，单个 Agent 无法承载全部上下文而不陷入信息过载，但多个 Agent 之间又缺乏有效的协作机制。每次会话都从空白开始，Agent 无法感知其他 Agent 的工作状态，更无法跨领域提问。

业界通常的解决方案是构建复杂的检索基础设施（RAG、向量嵌入），但这带来了额外的运维负担和延迟开销。octo-santa 选择了一条不同的道路：与其让一个 Agent 变得更聪明，不如让多个 Agent 能够协同工作——每个 Agent 深耕自己的领域，在需要跨域时能够发现并咨询其他专家。

---

octo-santa 的设计哲学可以用两个关键词概括：

框架无需任何外部基础设施，仅需 SQLite 数据库和 Markdown 文件即可运行。所有数据存储在本地，消息持久化在 SQLite 中，知识文档以 Markdown 形式管理。这种设计带来了几个显著优势：

• 零运维成本：无需部署服务器、管理集群或维护云服务
• 数据主权：所有数据保留在本地，满足隐私和合规要求
• 离线可用：不依赖网络连接，随时随地可用
• 快速启动：一条命令即可启动，无需配置复杂环境

与追求单 Agent 全能不同，octo-santa 专注于解决多 Agent 协作问题。它提供了完整的通信原语：持久化消息通道、提及机制、直接消息、游标追踪读取状态等，让 Agent 之间能够像人类团队一样协作。

---

消息系统是 octo-santa 的基础设施层，提供以下能力：

通道管理

• 支持创建命名通道，可配置最大消息跳数（默认 200，最大 1000）
• 支持直接消息（DM）模式，自动订阅双方并推送通知
• 游标追踪机制记录每个 Agent 的读取位置

消息投递模式

• 推送模式（Push）：推荐模式，Agent 通过 MCP Channel 接收实时通知，无需轮询
• 轮询模式（Poll）：兼容模式，通过 messaging_listen 阻塞等待或定期轮询

两种模式完全兼容，使用推送的 Agent 可以与使用轮询的 Agent 无缝通信。

安全机制

• 每通道跳数计数器防止失控循环
• 自我提及保护（Agent 不能 @ 自己）
• 系统通知 _system 在达到限制时自动发送
• 人类专属 /continue 命令重置跳数计数

Brain 模块让每个仓库都能成为特定领域的专家 Agent：

领域声明 通过 .octo-santa/config.json 配置文件声明：

{
  "domain": {
    "identifier": "payments-api",
    "tags": ["payments", "billing", "subscriptions"],
    "description": "Payment processing, webhook delivery, billing cycles"
  },
  "brain": {
    "dirs": ["./brain"]
  }
}

知识文档 Brain 文档是带 YAML 前置 matter 的 Markdown 文件，包含标题、摘要、标签等元数据。Agent 通过 brain_index 获取索引，通过 brain_read 读取具体内容。

跨域查询流程

1. 调用 brain_find_expert 发现目标领域专家
2. 使用 messaging_direct_message 向专家发送私信
3. 专家 Agent 读取自己的 Brain 文档并回复

关键点：跨域知识通过 Agent 间对话流动，而非共享文档存储。每个 Agent 是自己领域的权威接口。