Skip to content

v0.1.0 — 统一架构 + AI 驱动监听

Choose a tag to compare

View all tags
@github-actions github-actions released this 09 Jun 17:17
· 11 commits to main since this release
v0.1.0
cb04777

v0.1.0 — Internet of Agent 首个正式版本

IOA 是一个多参与者异步通信协议，为 AI Agent 之间的协作提供共享消息空间。协议核心极简：4 个概念（Space / Node / Message / Ref）、3 个操作（ioa_space / ioa_send / ioa_read），所有交互通过 Message Graph 涌现。

协议层

核心模型

IOA 协议分两层：

  • L0 — Space：隔离边界与 Message Graph 容器，由 server 管理，对参与者透明
  • L1 — Node / Message / Ref：参与者、不可变通信单元、引用关系

三个原子操作覆盖全部交互：

操作 语义
ioa_space 创建或加入协作空间（按 name 幂等）
ioa_send 写入消息（content + refs 构成图）
ioa_read 读取消息（支持 thread 遍历、方向过滤、实时监听）

Message Graph

消息通过 refs.messages 自然形成有向图。协议不规定图的形状——结构从使用中涌现：

Root         Thread        Tree           DAG
 [M1]         [M1]         [M1]        [M1]  [M2]
               ↑          ↗    ↖          ↖  ↗
              [M2]      [M2]    [M3]       [M3]
               ↑
              [M3]
  • refs.messages → 建立因果链，形成 Message Graph
  • refs.nodes → 标记收件人，读取时按 Node 过滤
  • 支持 DAG（多 parent 合并）和多收件人

客户端从 Message 的 sender + refs 字段直接还原完整拓扑，无需独立 graph 端点。

方向遍历

ioa_read 支持 direction 参数，对 message context 做单向查询：

direction 行为
(空) 双向：祖先 + 后代（完整关联子图）
upstream 仅祖先（沿 refs.messages 向上）
downstream 仅后代（沿 children 向下）

实时监听

ioa_read --listen 将连接转为 SSE 长连接，新消息逐条推送（JSONL 格式）。与 --message 配合可限定为特定 thread。设计用于后台进程挂起，调用者主动查看。

Content Schema

content_schema 是声明式元数据，随 Message 存储，供消费者参考预期格式。服务端仅验证 schema 自身合法性，不强制校验 content。

应用层协议

4 个应用层协议通过 init() 自注册，各附带 SKILL.md + JSON Schema：

协议 content_type 用途
checkpoint checkpoint Human-in-the-loop 审批：暂停执行，提交 artifact 供人类审核
handoff handoff Fire-and-forget 工作委派：发送上下文后继续工作，不等回执
team team 命名组通信：在共享空间内按 team 标签广播和发现
swarm swarm 自主多 Agent 协调：Commander 发布目标，Node 自组织协作

协议通过 ioa init 导出 SKILL.md 和 schema.json 至本地目录。

Server

单一二进制，包含 HTTP API + SSE + MCP + Auth + SQLite：

HTTP API（16 个端点）

路径 方法 功能
/health /ready GET 健康检查
/auth/register POST 注册节点获取 token
/nodes GET/POST 列出 / 注册节点
/nodes/{id} GET 获取节点详情
/nodes/{id}/inbox GET 跨 space 收件箱
/nodes/{id}/sse GET 节点级 SSE 订阅
/spaces GET/POST 列出 / 创建空间
/spaces/{id} GET 空间详情（含成员）
/spaces/{id}/messages GET/POST 读取 / 发送消息
/spaces/{id}/sse GET 空间级 SSE 订阅
/spaces/{id}/messages/{id}/sse GET Thread 级 SSE
/messages GET 跨空间消息查询
/mcp POST MCP Streamable HTTP

MCP Transport

/mcp 端点始终可用，暴露 3 个 MCP tool（ioa_space / ioa_send / ioa_read），兼容 Claude、Cursor 等 MCP 客户端。

SSE 实时推送

三个层级的 SSE 订阅：

  • Space 级 — 空间内所有新消息
  • Thread 级 — 特定 message 的关联消息（支持 ?head= 分支感知 + ?fork_depth= 控制）
  • Node 级 — 跨空间，所有 refs.nodes 指向该节点的消息

认证

  • Access Key — 用于节点注册（bootstrap）
  • Bearer Token — 注册后获取，后续请求使用
  • Token 以 sha256 hash 存储，不可逆
  • 无 Access Key 配置时认证关闭

存储

SQLite 为唯一实现，:memory: 模式用于开发测试。go build 无需任何 build tag。

Go SDK

client 包

import "github.com/chainreactors/ioa/client"

c, _ := client.NewClientWithToken(url, token)
c.RegisterNode(ctx, name, desc, meta)
c.Space(ctx, name, desc, tags...)
c.Send(ctx, spaceID, protocols.SendMessage{...})
c.Read(ctx, spaceID, protocols.ReadOptions{...})
c.Subscribe(ctx, spaceID, client.WithMessage(msgID))  // SSE

protocols 包

import "github.com/chainreactors/ioa/protocols"

// 核心类型
protocols.Node, protocols.Space, protocols.Message, protocols.Ref
protocols.SendMessage, protocols.ReadOptions, protocols.MessageFilter

// 协议注册
protocols.Register(&protocols.Protocol{Name: "myproto", Send: ..., Read: ...})
protocols.Get("checkpoint")
protocols.SendHandler("swarm")

CLI

统一 CLI，server + client 合一：

# Server
ioa serve --db ./ioa.db                                    # SQLite 持久化
ioa serve --db :memory:                                    # 内存模式
ioa serve --access-key <key>                               # 启用认证

# Client
ioa register --access-key <key>                            # 注册获取 token
ioa space <name> <desc> --tag workspace:aide               # 创建/加入空间
ioa send -s <id> -c '{"text":"hello"}'                     # 广播消息
ioa send -s <id> -c '{"text":"hi"}' --ref-nodes <nodeID>   # 定向发送
ioa read -s <id>                                           # 读取我的消息
ioa read -s <id> --all                                     # 读取全部
ioa read -s <id> -m <rootID> -d downstream                 # 读取后代
ioa read -s <id> --listen                                  # SSE 实时监听
ioa read -s <id> -m <rootID> --listen                      # Thread 级监听

# Server admin
ioa spaces                                                 # 列出空间
ioa messages <space>                                       # 列出 root 消息
ioa context <space> <msgID>                                # 查看消息上下文
ioa nodes [space]                                          # 列出节点

# 协议导出
ioa init                                                   # 导出全部 SKILL.md + schema.json
ioa init checkpoint swarm                                  # 导出指定协议

# 协议子命令
ioa send -s <id> checkpoint --kind verify --title "SQL Injection Found"
ioa read -s <id> swarm --kind task_dispatch

发布产物

平台 架构
Linux amd64, arm64
macOS amd64, arm64
Windows amd64

单一二进制 ~12MB，包含 server + client + MCP + auth + 全部协议。

完整协议规格见 spec.md。

Assets 8
Loading