AUP 协议规范

概述

AUP is a semantic node graph for structured UI rendering. An agent writes an AUP document (a tree of components) to create any UI. The runtime renders the tree, handles events, and manages live data updates.

An AUP document is a JSON object written to a session tree or rendered via aup_render action.

文档格式

An AUP document is a JSON object with 8 core fields and 2 universal props.

Core Fields

Universal Props

These props can appear on any node type:

空间意图

Fine-grained layout control for view containers. Pass an object as the layout prop instead of a string.

Example

{
  "layout": {
    "direction": "row",
    "align": "center",
    "crossAlign": "center",
    "gap": 16,
    "wrap": true
  }
}

尺寸

Sizing constraints via the view.props.size object.

主题令牌

Themes provide color tokens. Set the theme in the aup_render action (style param) or page meta. Read /themes/:name for available tokens.

覆盖层主题

Overlay themes are broadcast 'graphics packages' for overlay-grid layouts. Like TV graphics (CNN vs ESPN vs Apple Keynote), they control the visual identity of overlay elements. Agents declare semantic roles (WHAT), themes handle styling (HOW). Set theme prop on a view with layout: 'overlay-grid' to activate.

Presets

Roles (12)

• live-badge — LIVE indicator, recording status
• clock — time display with tabular-nums
• viewer-count — audience/viewer counter
• speaker-bar — name + title card for current speaker
• hashtag — event hashtag or topic tag
• logo — brand logo placement
• data-widget — live data card (stats, weather, stocks)
• alert — breaking/urgent notification
• featured-comment — highlighted audience comment
• score-bug — sports score compact display
• lower-third — TV-standard name/title bar
• ticker-item — individual ticker content item

Custom Theme

Pass an object instead of a string for custom themes: { badgeBg: "#ff6b00", cardRadius: "0", fonts: ["CustomFont:wght@400;700"] }. camelCase keys are mapped to --overlay-* CSS variables.

Example

{
  "id": "themed-overlay",
  "type": "view",
  "props": {
    "layout": "overlay-grid",
    "theme": "cnn"
  },
  "children": [
    {
      "id": "live",
      "type": "text",
      "props": {
        "region": "top-start",
        "role": "live-badge",
        "content": "\u25cf LIVE"
      }
    },
    {
      "id": "speaker",
      "type": "view",
      "props": {
        "region": "lower-start",
        "role": "speaker-bar",
        "layout": "column"
      },
      "children": [
        { "id": "sp-name", "type": "text",
          "props": { "content": "Jane Doe" } },
        { "id": "sp-title", "type": "text",
          "props": { "content": "CEO, Acme Corp",
                     "scale": "xs" } }
      ]
    }
  ]
}

国际化

AUP supports internationalization via server-side $t() resolution. Translation is transparent to the agent — use $t(key) in any string prop, and the server resolves it before the tree reaches the client.

Page Templates

Use $t(key) syntax in AUP node string props for translatable text. The pageResolver resolves all $t() placeholders server-side before rendering.

{
  "id": "greeting",
  "type": "text",
  "props": { "content": "$t(welcome)" }
}

Locale Files

Translation files live in .aup/locales/ as JSON:

• en.json → { "welcome": "Welcome" }
• zh.json → { "welcome": "欢迎" }
• ja.json → { "welcome": "ようこそ" }

Adding a new language = adding a new .json file.

AFS Data Convention

AFS data uses a suffix convention for locale variants: intro.json (default), intro.zh.json (Chinese), intro.ja.json (Japanese). When a node's src binds to an AFS path, the runtime reads with locale context. Fallback chain: zh-CN → zh → default.

Locale State

Locale is session-level. Set via ?locale=zh URL param or the settings bar. Changing locale re-renders the current page with the new locale. Pass locale in aup_render: { root, fullPage: true, style: "midnight", locale: "zh" }.

事件模型

Events flow: user interacts → client sends aup_event → server resolves node events config. Three dispatch modes:

1. exec: calls AFS exec on the specified path; agent responds with aup_patch.
2. target+set: directly patches another node (e.g. update surface src); no exec round-trip needed. $args.* placeholders in set values are resolved from the event data payload.
3. page: navigates to a named page; AUP session resolves page tree + style from the app's pageResolver.

Event Payload Format

{
  "type": "aup_event",
  "nodeId": "string",
  "event": "string",
  "data": "object (optional)"
}

Supported Events (11)

智能体工作流

How an agent creates and manages UI:

1. Read /primitives to discover available components
2. Read /primitives/:name for detailed props and examples
3. Read /themes to choose a visual theme
4. Read /examples for complete working documents
5. Build an AUP node tree (JSON) with unique IDs
6. Call aup_render action with { root, fullPage: true, style: "midnight", chrome: true, locale: "en" } — chrome shows lang/theme/mode toolbar
7. Handle events: when user interacts, event triggers your AFS exec path
8. Update UI: send aup_patch ops (create/update/remove/reorder nodes)

Frame 工作流

AUP is the OS, pages are applications running inside it. Use frame when you need a complete HTML page (complex JS, third-party libraries, Canvas/WebGL, or any content that needs its own document context). For standard UI, prefer native AUP primitives.

When to Use Frame

• Page needs its own JavaScript runtime (games, visualizations, third-party widgets)
• Content includes <script> tags or complex CSS that would conflict with the surface
• You want crash isolation — if the page breaks, the surface survives
• Embedding external URLs (documentation sites, dashboards, tools)

Steps

1. Write a complete HTML page to AFS: write('/ui/web/pages/mypage', { content: '<html>...</html>', format: 'html' })
2. Reference it in the AUP tree: { type: 'frame', props: { src: '/pages/mypage', bridge: true } }
3. The surface resolves /pages/mypage to an HTTP URL with session tokens
4. The iframe loads the page in a sandbox with the bridge script injected

Bridge API

When bridge: true, the page gets window.aup — a lightweight postMessage API for communicating with the parent surface. The bridge script is ~2KB, auto-injected.

Example

{
  "id": "app",
  "type": "view",
  "props": {
    "layout": { "direction": "row", "gap": 0 },
    "size": { "height": "100vh" }
  },
  "children": [
    {
      "id": "sidebar",
      "type": "view",
      "props": {
        "layout": "column",
        "size": { "width": "240px" },
        "variant": "card"
      },
      "children": [
        { "id": "nav", "type": "text",
          "props": { "content": "Navigation", "level": 3 } }
      ]
    },
    {
      "id": "main",
      "type": "frame",
      "props": {
        "src": "/pages/sales-chart",
        "bridge": true,
        "size": { "height": "100%" }
      }
    }
  ]
}

降级

When a device does not support a primitive, AUP applies degradation chains. Each chain is tried left-to-right; the first supported type wins. Degraded nodes are annotated with _degradedFrom in props.

The degradeTree(node, caps) function walks the AUP tree and degrades unsupported primitives. It returns a new tree (does not mutate the original). A PrimitiveCap of "native", "webview", or "partial" is considered supported; "unsupported" or missing means not supported.