协议规范

代理渲染协议

一种与传输方式无关的双向协议，用于 AI 代理与渲染界面之间的通信。一个代理，适配所有界面。

v0.1 草案

开放标准

CC BY 4.0

问题所在

AI 代理会生成结构化输出——表格、表单、图表、状态消息、代码块——但这些输出的渲染方式与传输层和前端框架紧密耦合。为 Web 聊天构建的代理无法在桌面应用中渲染。通过 SSE 流传输的代理无法服务于期望不同协议的移动客户端。

每接入一个新的渲染界面，就需要编写一套定制集成代码。

解决方案

ARP 定义的是一套协议——而非框架，也非库。就像 Wayland 将应用程序从显示服务器中解耦一样，ARP 将代理从渲染器中解耦。

代理决定显示什么。渲染器决定如何显示。

架构

Agent (backend)                              Renderer (web, CLI, mobile)
───────────────                              ──────────────────────────
Owns surfaces         ── render / delta ──►  Owns display
Owns UI state         ◄── input events ────  Owns input routing

设计原则

无中间层

代理直接发送渲染指令。渲染器直接发送输入。无需中间框架。

异步 & 非阻塞

所有消息均为异步。任何一方都不会阻塞等待响应。

每帧皆完美

原子提交。渲染状态在待定缓冲区中累积，原子性地应用。无闪烁。

能力驱动

渲染器声明其支持的能力，代理随之适配。CLI 获得表格，Web 获得一切。

传输无关

逻辑消息，而非线格式。WebSocket、SSE、gRPC、Unix 套接字、stdio。

类型化组件

代理发出类型化描述符，例如带有 headers 和 rows 的 table——而非 HTML。

协议消息

每条 ARP 消息都是 JSON 格式，至少包含 { v: 1, type: "<type>" }。

服务端到客户端

类型	用途
`hello`	连接时的能力握手
`delta`	增量文本块
`tool_start`	工具开始执行
`tool_end`	工具执行完毕
`render`	生成式 UI 组件
`patch`	组件增量更新
`error`	错误事件
`commit`	流传输完成

客户端到服务端

类型	输入类型	用途
`input`	`text`	用户文本消息
`input`	`action`	按钮点击 / UI 操作
`input`	`form_submit`	表单提交

14 个内置组件

每个符合 ARP 规范的渲染器至少须支持 text。组件声明回退链——chart 回退到 table，table 回退到 text。

text

markdown

status-card

table

code-block

diff

key-value

progress

chart

form

confirm

choices

product-cards

image

传输方式

可用

WebSocket

/_arp/v1

主要传输方式。持久双向连接，支持自动重连。

可用

SSE

Server-Sent Events

备用传输方式。文件上传需通过 multipart/form-data 时使用。

计划中

gRPC

高性能

适用于原生桌面和移动应用程序。

计划中

stdio

NDJSON 分帧

适用于 CLI 渲染器和基于管道的集成。

客户端 SDK

@haira/arp — 核心库（零依赖）

typescript

import { ArpClient } from '@haira/arp'

const client = new ArpClient('ws://localhost:8080/_arp/v1', {
  onDelta: (text) => appendToChat(text),
  onRender: (event) => renderComponent(event.component, event.props),
  onDone: () => markStreamComplete(),
})

client.connect()
client.sendText('Show me the sales data')

@haira/arp-react — 即插即用聊天 UI

tsx

import { ArpChat } from '@haira/arp-react'

function App() {
  return (
    <ArpChat
      url="ws://localhost:8080/_arp/v1"
      theme="dark"
      title="Data Explorer"
    />
  )
}

同样可用：@haira/arp-vue（适用于 Vue 3）和 github.com/haira-lang/arp-go（适用于 Go 后端）。

Haira 集成

每个 Haira 服务器原生支持 ARP，无需任何配置。

haira

import "ui"

tool query_database(query: string) -> any {
    """Executes a SQL query and displays results."""
    rows, err = postgres.query(db, query)
    if err != nil {
        return ui.status_card("error", "Query Failed", conv.to_string(err))
    }
    return ui.table("Query Results", headers, rows)
}

agent DataExplorer {
    provider: OpenAI
    tools: [query_database]
    ui: ui
}

@webhook("/chat")
workflow Chat(message: string, session_id: string) -> stream {
    return DataExplorer.stream(message, session: session_id)
}

扩展生命周期

新组件遵循受 Wayland 启发的三阶段生命周期：

1. 实验阶段

x-vendor-name

由厂商创建。允许破坏性变更。

2. 预发布阶段

s-name

需要至少 2 个渲染器实现。经过治理审查。

3. 核心阶段

无前缀

纳入 ARP 规范。仅允许向后兼容的变更。

合规级别

级别	必需组件	适用场景
最小	`text` + 文本输入	语音助手、IoT
基础	text、table、form、confirm、choices	CLI 终端
标准	所有核心组件，完整对象模型	Web / 桌面
完整	标准级 + 流传输、多界面、文件上传	富 Web 应用

阅读完整参考文档

代理渲染协议

问题所在 ​

解决方案 ​

设计原则 ​

协议消息 ​

14 个内置组件 ​

传输方式 ​

客户端 SDK ​

Haira 集成 ​

扩展生命周期 ​

合规级别 ​