vb2250158/rabiroute/aiui-dev

AIUI Agent Developer Guide

This guide provides independent and comprehensive context for AI agents developing AIUI applications. It includes project structure, SFC .ink support specifications, and standard API references, designed to help Large Language Models (LLMs) generate accurate AIUI pages and logic code.

At present, AIUI is used in two forms. These two forms describe the current AIUI product shape only; more forms may be added in the future. Different forms can also transition into one another as the user flow changes, for example from a conversation-flow card into a full-screen page.

• Conversation-flow cards: Cards embedded in a conversation flow are display-only and should be treated as non-interactive surfaces for presenting information.
• Full-screen pages: Full-screen pages provide complete interaction capabilities and support richer page logic, event handling, and user input.

1. Project Structure

A standard AIUI application project typically contains the following core files:

• AGENTS.md: The agent manifest, defining the agent's identity and capabilities.
• app.json: Global configuration, including page routes, window settings, etc.
• app.js: Application lifecycle and global logic.
• pages/: Page directory containing the application's pages, primarily using the Single File Component (SFC) .ink format.
• assets/: Directory for storing static resources like images and audio.

1.1 Agent Manifest (AGENTS.md)

The manifest file defines the agent's basic information and required permissions/skills:

# Agent Manifest
 
## Identity
-**Name**: My AIUI Agent
-**Version**: 1.0.0
-**Description**: A brief application description.
-**Author**: Developer Name
 
## Capabilities
-**Permissions**:
  -camera
  -microphone
  -network
  -audio
-**Skills**:
  -weather-lookup

1.2 Global Configuration (app.json)

Defines application page paths and global UI styles. The pages field is required and declares the routing order for all application pages:

{
  "pages": [
    "pages/index/index"
  ],
  "window": {
    "navigationBarTitleText": "My AIUI Agent",
    "viewport": {
      "width": "device-width"
    }
  }
}

• pages is an array of page route strings without file extensions.
• Each entry maps to a page directory such as pages/index/index, which resolves to the corresponding page files in that folder.
• The first item in the array is treated as the application's default landing page.
• Add new pages here whenever you create additional screens, otherwise the framework will not register them for navigation.

1.3 Application Registration (app.js)

AIUI uses an ES module-based registration system, registering the application by exporting a default configuration object:

export default {
  onLaunch() {
    console.log('App Launch');
  },
  globalData: {
    userInfo: null
  }
};

1.4 Page

In AIUI, each page acts as a Model Context Protocol (MCP) UI component. A complete page should define the following parts:

• Configuration: Page-level metadata such as description, and schema. The description explains what the page represents, and schema.data uses JSON Schema to declare the input data required to render the page.
• Logic: Page state, lifecycle hooks, and custom methods used to initialize data and respond to user interactions.
• Structure: The UI template that describes the page layout and binds data to components.
• Style: The WXSS or CSS rules that control the visual presentation of the page.

When writing page configuration, pay special attention to description and schema.data:

• description should describe the page in natural language from a UI perspective.
• State what the page displays or helps the user accomplish.
• Mention the most important dynamic data if the page depends on external input.
• Keep it specific and observable. Prefer "Displays a weather summary for a city" over "Weather page".
• schema.data should define the complete input contract required to render the page.
• Use type: "object" at the top level.
• Put all render-time fields in properties.
• Use required for fields that must exist before the page can render correctly.
• Add description, enum, items, and nested object definitions when they help clarify the data contract.

Examples:

Example 1: Weather card page

{
  "description": "Displays the current weather summary for a city, including temperature, condition, and humidity.",
  "schema": {
    "data": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string",
          "description": "City name shown in the page header"
        },
        "temperature": {
          "type": "number",
          "description": "Current temperature in Celsius"
        },
        "condition": {
          "type": "string",
          "enum": ["sunny", "cloudy", "rainy", "snowy"],
          "description": "Current weather condition"
        },
        "humidity": {
          "type": "number",
          "description": "Current humidity percentage"
        }
      },
      "required": ["city", "temperature", "condition"]
    }
  }
}

Example 2: Product detail page

{
  "description": "Shows product information for an item, including title, price, primary image, and purchase status.",
  "schema": {
    "data": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "description": "Product title"
        },
        "price": {
          "type": "number",
          "description": "Current selling price"
        },
        "imageUrl": {
          "type": "string",
          "description": "Primary product image URL"
        },
        "inStock": {
          "type": "boolean",
          "description": "Whether the product can be purchased"
        },
        "tags": {
          "type": "array",
          "description": "Short product labels shown near the title",
          "items": {
            "type": "string"
          }
        }
      },
      "required": ["title", "price", "imageUrl", "inStock"]
    }
  }
}

Example 3: Task list page

{
  "description": "Renders a task list with completion status, assignee information, and an optional empty-state message.",
  "schema": {
    "data": {
      "type": "object",
      "properties": {
        "tasks": {
          "type": "array",
          "description": "Tasks displayed in the list",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Task identifier"
              },
              "title": {
                "type": "string",
                "description": "Task title"
              },
              "completed": {
                "type": "boolean",
                "description": "Whether the task has been completed"
              },
              "assignee": {
                "type": "string",
                "description": "Person responsible for the task"
              }
            },
            "required": ["id", "title", "completed"]
          }
        },
        "emptyMessage": {
          "type": "string",
          "description": "Message shown when there are no tasks"
        }
      },
      "required": ["tasks"]
    }
  }
}

AIUI supports two page authoring modes:

1. Multi-file mode: Split the page across separate files such as page.json, page.js, page.wxml, and page.wxss.

• page.json: Page configuration and metadata.
• page.js: Page logic, data, lifecycle hooks, and methods.
• page.wxml: Page template structure.
• page.wxss: Page styles.

1. Single-file mode: Define the entire page in one .ink file.

• <script def>: Page configuration and metadata.
• <script setup>: Page logic, data, lifecycle hooks, and methods.
• <page>: Page template structure.
• <style>: Page styles.

Choose exactly one mode for each page. Do not mix multi-file page definitions with an .ink file for the same route.

2. Single File Component (SFC) .ink Specification

In AIUI, page development is recommended to use the Single File Component (SFC) format, which is the .ink file. This format centralizes the page's configuration, logic, structure, and style in a single file.

A standard .ink file structure contains four main tag blocks:

1. <script def>: Used to define page-level JSON configuration, such as the navigation bar title.
2. <script setup>: Contains the page's JavaScript logic code, exporting the page configuration object (including data, lifecycle hooks, custom methods, etc.) via export default.
3. <page>: The page's template structure (WXML-like syntax).
4. <style>: The page's stylesheet (CSS).

2.1 .ink Example Code:

<script def>
{
  "navigationBarTitleText": "Home"
}
</script>
 
<script setup>
import wx from 'wx';
 
export default {
  data: {
    greeting: 'Hello AIUI!'
  },
  onLoad() {
    console.log('Page loaded');
  },
  handleTap() {
    this.setData({
      greeting: 'Hello, World!'
    });
  }
}
</script>
 
<page>
  <view class="container">
    <text class="title">{{ greeting }}</text>
    <button bindtap="handleTap">Click Me</button>
  </view>
</page>
 
<style>
.container {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  height: 100vh;
}
 
.title {
  font-size: 24px;
  margin-bottom: 20px;
}
</style>

3. WXML (WeiXin Markup Language) & Components

In AIUI, the structure of a page is described using WXML (WeiXin Markup Language), which is used within the <page> tag of an .ink file (or a standalone .wxml file). It allows you to build user interfaces using components, data binding, and conditional rendering.

3.1 Basic Syntax and Data Binding

WXML uses double curly braces {{ }} for data binding. You can bind properties from your page's data object directly to the UI.

<!-- Text binding -->
<view>{{ message }}</view>
 
<!-- Attribute binding -->
<view class="{{ dynamicClass }}"></view>
 
<!-- Expression binding -->
<view>{{ count + 1 }}</view>

3.2 Directives (Conditional Rendering and Lists)

AIUI supports conditional rendering using the ink:if, ink:elif, and ink:else directives to control whether a component is rendered based on a condition.

<view ink:if="{{condition === 1}}"> Rendered if condition is 1 </view>
<view ink:elif="{{condition === 2}}"> Rendered if condition is 2 </view>
<view ink:else> Rendered otherwise </view>

AIUI supports basic list rendering with ink:for, allowing you to repeat a component structure for each item in an array.

<view ink:for="{{cities}}" ink:key="name">
  <text>{{item.name}}</text>
  <text>{{item.temperature}}</text>
</view>

Use item to access the current element and index to access its position in the array. Prefer providing a stable ink:key when rendering dynamic collections.

Current Limitation: Nested ink:for is not supported yet. Keep list rendering to a single level, and flatten data in JavaScript first when you need to present hierarchical content.

3.3 Built-in Components

AIUI provides a set of built-in components that you can use within your WXML templates. These components are mapped to native implementations for optimal performance.

For parameter-by-parameter documentation, event behavior, content model notes, and examples, see components.md. The reference there is intentionally aligned with the current component registry and implementation details in ink-builtin-components.

For runtime API details, constructor behavior, supported overloads, and current implementation limits, see apis.md. Use the linked domain reference files there when you need Canvas, wx, device, media, or AI-specific details.