ART - Agent Realtime Transport (智能体实时传输协议)

AI智能体的缺失传输层
移动优先 • 实时流式传输 • 跨设备会话 • 以人为本的设计

🎯 什么是ART？

ART (Agent Realtime Transport) 是一个开放协议，实现了在本地机器上运行的AI智能体与移动设备用户之间的双向实时交互。它填补了强大的命令行智能体（如Claude Code、Codex CLI、Gemini CLI）与移动优先世界之间的鸿沟。

📦 三大核心组件

ART由三个相互连接的组件组成，协同工作：

┌─────────────────────────────────────────────────────────────────────────────┐
│                          您的开发机器                                       │
│   ┌─────────────────────────────────────────────────────────────────────┐   │
│   │                         ART Hook (@art/hook)                        │   │
│   │  ┌─────────────────┐     ┌──────────────────────────────────────┐   │   │
│   │  │   AI智能体       │     │  Hook进程                          │   │   │
│   │  │  Claude Code    │◄───►│  • 捕获stdout/stderr               │   │   │
│   │  │  Codex CLI      │     │  • 向stdin注入用户命令              │   │   │
│   │  │  Gemini CLI     │     │  • 维护Broker连接                   │   │   │
│   │  │  任意CLI工具     │     │  • A2UI适配器(智能体到UI)            │   │   │
│   │  └─────────────────┘     └───────────────┬──────────────────────┘   │   │
│   └──────────────────────────────────────────│──────────────────────────┘   │
└──────────────────────────────────────────────│──────────────────────────────┘
                                               │
                                               │ WebSocket (WSS)
                                               │ 双向流式传输
                                               ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         云端服务器                                          │
│   ┌─────────────────────────────────────────────────────────────────────┐   │
│   │                      ART Broker (@art/broker)                       │   │
│   │                                                                     │   │
│   │  • 会话管理    - 创建、恢复、移交、销毁会话                          │   │
│   │  • 消息路由    - Hook与Player之间的消息路由                          │   │
│   │  • 流多路复用  - stdout、stderr、thinking、a2ui                     │   │
│   │  • A2UI路由    - 管理UI界面和用户行为                                │   │
│   │  • 连接管理    - 处理重连、离线队列                                  │   │
│   │  • 推送通知    - 重要事件通知用户                                    │   │
│   │                                                                     │   │
│   └───────────────────────────────────┬─────────────────────────────────┘   │
└───────────────────────────────────────│─────────────────────────────────────┘
                                        │
                                        │ WebSocket (WSS)
                                        │ 双向流式传输
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                          用户的移动设备                                     │
│   ┌─────────────────────────────────────────────────────────────────────┐   │
│   │                    ARTplayer (微信小程序)                            │   │
│   │                                                                     │   │
│   │  • 实时显示    - 终端 + A2UI融合渲染                                 │   │
│   │  • 命令输入    - 向智能体发送指令                                    │   │
│   │  • 任务管理    - 提交、监控、取消任务                                │   │
│   │  • A2UI组件    - 按钮、输入框、卡片、表单                            │   │
│   │  • 历史记录    - 查看和恢复过去的会话                                │   │
│   │  • 离线支持    - 断线时排队命令                                      │   │
│   │  • 二维码移交  - 扫码即时恢复会话                                    │   │
│   │                                                                     │   │
│   └─────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘

🔄 组件角色与职责

ART Hook (`@art/hook`)

角色: 智能体I/O桥接器
运行环境: 开发者的机器 (Linux/macOS)
包位置: packages/hook/

职责	描述
进程包装	包装任意CLI进程（智能体、bash、python等）
输出捕获	捕获被包装进程的所有stdout/stderr
输入注入	将远程用户的命令写入进程stdin
Broker连接	维持与Broker的持久WebSocket连接
自动重连	网络故障时自动重连
A2UI适配	智能识别场景并生成A2UI界面

# 用法
art-hook --broker wss://art.example.com -- claude-code
art-hook --broker wss://art.example.com -- bash
art-hook --broker wss://art.example.com -- python my_agent.py

支持的CLI智能体

ART Hook可以包装任何命令行AI智能体。以下是我们主要支持的CLI智能体：

智能体	厂商	类型	安装方式	状态	说明
Claude Code	Anthropic	CLI智能体	`npm install -g @anthropic-ai/claude-code`	⭐ 核心支持	最成熟的AI编程助手
Codex CLI	OpenAI	CLI智能体	`npm install -g @openai/codex`	⭐ 核心支持	GitHub官方出品，与Copilot深度集成
Gemini CLI	Google	CLI智能体	`npm install -g @google/gemini-cli`	⭐ 核心支持	Google Gemini 2.5 Pro 驱动
iFlow	iFlow.AI	CLI智能体	`curl -fsSL https://gitee.com/iflow-ai/iflow-cli/raw/main/install.sh \| bash`	⭐ 核心支持	中国AI编程助手

注意： 基于IDE的工具如Cursor、Windsurf或GitHub Copilot不是CLI智能体，需要不同的集成方式。

ART Broker (`@art/broker`)

角色: 云端中继与会话管理器
运行环境: 云服务器
包位置: packages/broker/

职责	描述
会话管理	创建、恢复、移交、销毁会话
消息路由	Hook与Player之间的消息路由
流多路复用	处理多种流类型（stdout、stderr、thinking、a2ui）
连接管理	跟踪连接的客户端，处理重连
任务管理	跟踪任务状态、进度、完成情况
推送通知	发送重要事件通知

// 启动Broker
import { ARTBroker } from "@art/broker";

const broker = new ARTBroker();
broker.start({ port: 8080 });

ARTplayer (微信小程序)

角色: 用户界面
运行环境: 用户的移动设备
位置: apps/artplayer/

职责	描述
实时显示	实时显示智能体输出
命令输入	允许用户发送指令
任务提交	向智能体提交新任务
任务监控	查看任务进度和状态
历史记录	查看和恢复过去的会话
离线队列	断线时排队命令

🔀 交互流程

流程1: 智能体输出 → 用户显示

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│  智能体   │───►│ ART Hook │───►│  Broker  │───►│ARTplayer │
│ (stdout) │    │ (捕获)   │    │ (路由)   │    │(显示)    │
└──────────┘    └──────────┘    └──────────┘    └──────────┘

1. 智能体写入stdout: "正在构建项目..."
2. ART Hook通过进程包装器捕获输出
3. ART Hook发送stream.data到Broker
4. Broker通过WebSocket转发到ARTplayer
5. ARTplayer在实时UI中显示

消息示例:

{
  "art_version": "1.0",
  "jsonrpc": "2.0",
  "method": "stream.data",
  "params": {
    "stream_id": "stream_abc123",
    "stream_type": "stdout",
    "content": "正在构建项目...\n",
    "sequence": 42
  },
  "session_id": "sess_xyz789"
}

流程2: 用户命令 → 智能体执行

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│ARTplayer │───►│  Broker  │───►│ ART Hook │───►│  智能体   │
│ (输入)   │    │ (路由)   │    │ (注入)   │    │ (stdin)  │
└──────────┘    └──────────┘    └──────────┘    └──────────┘

1. 用户在ARTplayer中输入命令: "修复登录bug"
2. ARTplayer发送task.submit到Broker
3. Broker路由到连接的ART Hook
4. ART Hook将命令写入智能体的stdin
5. 智能体接收并处理指令

🎨 A2UI (Agent-to-UI) - 动态界面渲染

ARTP现在支持 A2UI - 一个协议扩展，使AI智能体能够直接在移动设备上渲染动态用户界面。

什么是A2UI？

A2UI允许智能体发送结构化UI组件（按钮、表单、卡片），而不仅仅是文本，创造丰富的交互体验：

┌─────────────────────────────────────────────────────────────┐
│                    A2UI渲染流程                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  智能体决策              A2UI消息            移动端UI        │
│  ┌─────────┐            ┌─────────────┐       ┌─────────┐  │
│  │"我需要   │───────────▶│ {           │──────▶│[确认]   │  │
│  │ 用户     │            │   type:     │       │[取消]   │  │
│  │ 确认"    │            │   "form",   │       │         │  │
│  └─────────┘            │   ...       │       │您确定   │  │
│                         │ }           │       │要执行吗？│  │
│                         └─────────────┘       └─────────┘  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

支持的组件

组件	类型	描述
按钮	`org.a2ui.button`	带动作的交互按钮
输入框	`org.a2ui.input`	带数据绑定的文本输入
卡片	`org.a2ui.card`	带标题、内容、动作的容器
表单	`org.a2ui.form`	带验证的多字段表单

融合渲染模式

ARTplayer支持双模式渲染 - 在终端输出和A2UI界面之间无缝切换：

终端模式: 传统文本流显示
分屏模式: 终端 + A2UI并排显示
A2UI模式: 全屏动态界面

📊 消息粒度

流类型

类型	描述	示例
`stdout`	智能体标准输出	`"正在构建...\n"`
`stderr`	智能体错误输出	`"警告: 已弃用的API"`
`thinking`	智能体推理过程	`"正在分析代码库..."`
`progress`	任务完成百分比	`{ "percent": 50 }`
`artifact`	生成的文件/代码	`{ "path": "/output.py" }`
`a2ui`	A2UI结构化UI更新	`{ "type": "surfaceUpdate", ... }`

任务状态

pending → running → completed
                 ↘  failed
                 ↘  cancelled
                 ↘  waiting_approval → approved → running

🛠️ 快速开始

1. 启动Broker (云端)

cd packages/broker
npm run dev
# Broker运行在 ws://localhost:8080

2. 启动ART Hook (本地机器)

# 全局安装（构建后）
npm link --workspace=@art/hook

# 运行任意命令
art-hook --broker ws://localhost:8080 -- bash

3. 连接ARTplayer (移动端)

打开微信开发者工具
导入 apps/artplayer/
在 app.js 中配置broker URL
在移动设备上预览

📋 协议规范

消息格式 (JSON-RPC 2.0扩展)

interface ARTMessage {
  // 标准JSON-RPC 2.0
  jsonrpc: "2.0";
  id?: string | number;
  method?: string;
  params?: any;
  result?: any;
  error?: ErrorObject;
  
  // ART扩展
  art_version: "1.0";
  session_id?: string;
  
  // 流式传输
  stream?: boolean;
  stream_id?: string;
  stream_sequence?: number;
  stream_end?: boolean;
}

核心方法

命名空间	方法	方向	描述
`session`	`create`	任意 → Broker	创建新会话
`session`	`resume`	任意 → Broker	恢复现有会话
`session`	`handoff`	任意 → Broker	将会话转移到另一设备
`session`	`destroy`	任意 → Broker	结束会话
`task`	`submit`	Player → Hook	提交任务指令
`task`	`status`	任意 → Broker	获取任务状态
`task`	`approve`	Player → Hook	批准待定操作
`task`	`cancel`	Player → Hook	取消运行中的任务
`stream`	`data`	Hook → Player	流式输出数据
`stream`	`subscribe`	Player → Broker	订阅流
`terminal`	`input`	Player → Hook	发送原始终端输入 (stdin)
`terminal`	`resize`	Player → Hook	调整远程终端PTY大小
`agent`	`list`	Player → Hook	列出可用智能体
`agent`	`start`/`stop`	Player → Hook	管理智能体进程生命周期
`capabilities`	`list`	任意	发现功能/方法
`a2ui`	`surface.create`	Hook → Broker	创建A2UI界面
`a2ui`	`surface.update`	Hook → Broker	更新A2UI组件
`a2ui`	`userAction`	Player → Hook	发送用户交互事件

🔐 安全模型

┌─────────────────────────────────────────────────────────────┐
│                    安全层                                    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  传输层:  WSS (TLS 1.3)                                     │
│  会话层:  JWT令牌, 设备绑定                                  │
│  端到端:  X25519密钥交换, AES-256-GCM                       │
│  认证:    访问令牌 (15分钟) + 刷新令牌 (30天)               │
│                                                             │
└─────────────────────────────────────────────────────────────┘

🏛️ 设计原则

移动优先 — 每个设计决策都考虑移动网络限制
双向通信 — 真正的双向通信，不仅仅是监控
弹性设计 — 自动重连、离线队列、会话恢复
智能体无关 — 与任何AI智能体架构兼容，不依赖内部实现
默认安全 — 端到端加密是内置的，不是可选的
A2UI原生 — 内置支持动态UI渲染

📁 项目结构

ARTP/
├── packages/
│   ├── protocol/          # @art/protocol - 类型定义和常量
│   │   └── src/a2ui.ts    # A2UI类型定义
│   ├── broker/            # @art/broker   - 云端中继服务器
│   │   └── src/a2ui-router.ts  # A2UI界面管理
│   └── hook/              # @art/hook     - 本地智能体桥接CLI
│       └── src/a2ui/      # A2UI适配器和场景检测器
├── apps/
│   ├── artplayer/         # 微信小程序客户端
│   │   ├── components/a2ui/    # A2UI组件 (按钮, 输入框, 卡片)
│   │   ├── utils/a2ui-engine.js    # A2UI消息解析器
│   │   └── utils/fused-renderer.js # 终端 + A2UI融合渲染器
│   └── a-flow/            # 替代小程序 (开发中)
├── art.0017.eu.cc_nginx/  # 服务器部署配置
├── docs/                  # 文档
│   └── ARTP-A2UI-Fusion-Analysis-Report.md
├── Dockerfile             # 容器构建
├── docker-compose.yml     # Docker Compose配置
└── package.json           # Monorepo根

🚀 部署

ARTP 包含三个主要组件。各组件的部署方式如下：

组件	部署方式	部署者	使用方式
ART Hook	自行部署	用户	在本地机器上安装
ART Broker	官方SaaS	ARTP 团队	使用官方服务
ARTplayer	官方SaaS	ARTP 团队	微信小程序（扫码使用）

部署 ART Hook（自行部署）

ART Hook 必须安装在您运行 AI 智能体的本地机器上。

# 从 npm 安装
npm install -g @art/hook

# 或本地安装
npm install @art/hook

使用方法：

# 包装您的 CLI 智能体
art-hook --broker wss://art.0017.eu.cc -- claude-code

# 或其他任何 CLI 工具
art-hook --broker wss://art.0017.eu.cc -- bash
art-hook --broker wss://art.0017.eu.cc -- python my_agent.py

使用官方服务

Broker（官方）

使用官方 Broker 服务，无需自行部署：

wss://art.0017.eu.cc

ARTplayer（官方）

扫描下方二维码使用官方微信小程序：

ARTplayer 二维码
扫码打开 ARTplayer

环境变量（Hook）

变量	描述	默认值
`ART_BROKER_URL`	默认 Broker WebSocket 地址	-
`ART_SESSION_ID`	默认会话 ID	-

📜 许可证

本项目采用 CC BY-SA 4.0 许可证。

ART — 连接AI智能体与移动世界
为智能体AI时代而生