### Enter the generated directory and start development

Source: https://github.com/yodaos-project/aiui/blob/main/packages/create-aiui-agent/README.md

After scaffolding, run these commands to install dependencies and start the development server.

```bash
cd my-agent
npm install
npm start
```

--------------------------------

### Start Speech Recognition (Web and wx)

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/3-api/ai/speech-recognition.en-US.md

Two platform-specific ways to start speech recognition. The Web example uses the standard SpeechRecognition API with onresult and onerror handlers. The wx example uses the WeChat Mini Program API wx.speech.startRecognition() and logs the returned session ID.

```javascript
const recognition = new SpeechRecognition();

recognition.onresult = (event) => {
  const best = event.results[0][0];
  console.log(best.transcript, best.confidence);
};

recognition.onerror = (event) => {
  console.error(event.error, event.message);
};

recognition.start();
```

```javascript
const sessionId = wx.speech.startRecognition();
console.log('Recognition session:', sessionId);
```

--------------------------------

### AudioPlayer basic playback example

Source: https://github.com/yodaos-project/aiui/blob/main/skills/aiui-dev/references/apis/media.md

Creates an AudioPlayer, sets a local asset path as the source, enables looping, and starts playback. Use for full audio files or streaming audio data; for streaming, pass options with format 'pcm' or 'ogg_opus' and use append() and finish().

```javascript
import { AudioPlayer } from 'audio';

const player = new AudioPlayer();
player.src = '/assets/intro.ogg';
player.loop = true;
player.play();
```

--------------------------------

### Installing a package with npm

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/1-framework/open-agent-format/package.en-US.md

Command to install the @demo/ui package.

```bash
npm install @demo/ui
```

--------------------------------

### Example .ink Single-file Structure

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/0-guide/structure.en-US.md

Shows the structure of an .ink file with a <script setup> block for data and event handlers, a <page> root element for the interface, and a <style> block. The example uses a text element with a bindtap handler and a data property 'message'.

```html
<script setup>
export default {
  data: { message: 'Hello AIUI' },
  handleTap() {
    this.setData({ message: 'Updated' });
  },
};
</script>

<page>
  <text bindtap="handleTap">{{message}}</text>
</page>

<style>
text {
  font-size: 32rpx;
}
</style>
```

--------------------------------

### Install aix CLI and show help

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/7-tools/cli.en-US.md

Install the aix CLI globally with npm and verify it runs by displaying help. Requires Node.js 20 or later.

```bash
npm install -g @yodaos-pkg/aix-cli
aix --help
```

--------------------------------

### Importing a module after installation

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/1-framework/open-agent-format/package.en-US.md

Shows how to import a module from the installed package.

```javascript
import { formatMessage } from '@demo/ui';
```

--------------------------------

### Inspect and Install Local Project with aix show and aix install

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/0-guide/debug/cli_device_debug.en-US.md

Inspect the effective Agent Definition and install the local project. `aix install` packages the directory before submitting it to the device, so `aix pack` is not needed. If you already have an `.aix` package, use `aix install ./bundle.aix` instead.

```bash
aix show ./my-agent
aix install ./my-agent
```

--------------------------------

### Open a Widget from an installed agent with aix launch-widget

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/7-tools/cli.en-US.md

Open a Widget from an installed agent. --position sets the starting grid position; parameters can be passed with --params or --params-file. Widget size comes from app.json.widgets[].family. The CLI keeps compatible existing placements, replaces overlapping overlay Widgets on conflict, and clears old overlay placements if there is no space. Persistent Widgets are never removed automatically.

```bash
aix launch-widget ./my-agent widgets/order/index

```

```bash
aix launch-widget ./my-agent widgets/order/index --position 2

```

--------------------------------

### Open a page from an installed agent with aix launch-page

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/7-tools/cli.en-US.md

Open a page from an already installed agent. --card opens a card instead of full screen; --params passes a JSON object, and --params-file reads a JSON file for longer parameters. Run aix install first if the agent is not installed yet.

```bash
aix launch-page ./my-agent

```

```bash
aix launch-page ./my-agent pages/index/index

```

```bash
aix launch-page ./my-agent pages/index/index --card

```

```bash
aix launch-page ./my-agent pages/index/index --params '{"id":"123"}'

```

--------------------------------

### Application-root path examples for image, video, and lottie-view

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/1-framework/open-agent-format/assets.en-US.md

Paths beginning with `/` are resolved from the current application's resource root, not the device OS. They cannot read files outside the application package. These examples show the syntax for image, video, and lottie-view components.

```xml
<image src="/assets/logo.png"></image>
<video src="/assets/intro.mp4"></video>
<lottie-view src="/assets/loading.json"></lottie-view>
```

--------------------------------

### requestData() example

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/3-api/media/media-capture.en-US.md

Shows how to listen for the 'dataavailable' event and request an immediate chunk of recorded data. The recorder must be started before calling requestData(), otherwise an InvalidStateError is thrown.

```javascript
recorder.addEventListener('dataavailable', ({ data }) => {
  console.log('Immediate chunk', data.size);
});

recorder.start();
recorder.requestData();
```

--------------------------------

### WXSS Styles Example

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/0-guide/framework/ui.en-US.md

Example WXSS stylesheet using the rpx unit, demonstrating common selectors and styling for the WXML example.

```css
/* index.wxss */
.container {
  padding: 20rpx;
  background-color: #f8f8f8;
}

.title {
  font-size: 36rpx;
  font-weight: bold;
  color: #333;
}

.item {
  display: flex;
  justify-content: space-between;
  padding: 30rpx;
  margin-top: 10rpx;
  background-color: #fff;
  border-radius: 8rpx;
}

.badge {
  color: #40FF5E;
  font-size: 24rpx;
}
```

--------------------------------

### Install AIX-CLI with npm

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/0-guide/bundle/cli.en-US.md

Install the AIX-CLI tool globally using npm when you have the source code.

```bash
npm install -g @yodaos-pkg/aix-cli
```

--------------------------------

### WebSocket client example (Web)

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/3-api/network/websocket.en-US.md

Web platform example using the standard WebSocket API. Opens a connection to wss://example.com/realtime, sends a JSON hello message on open, logs received messages, and logs when the connection closes.

```javascript
const socket = new WebSocket('wss://example.com/realtime');

socket.addEventListener('open', () => {
  socket.send(JSON.stringify({
    type: 'hello',
    sessionId: 'demo-session',
  }));
});

socket.addEventListener('message', (event) => {
  console.log('收到消息:', event.data);
});

socket.addEventListener('close', () => {
  console.log('连接已关闭');
});
```

--------------------------------

### Debug a Widget with aix device set-dev, install, launch-widget, and widget-layout

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/0-guide/debug/cli_device_debug.en-US.md

Enable Developer Mode, install the project, launch a Widget, and show its current layout. Replace the sample Widget path with one declared in your `app.json`. Changing Developer Mode reloads Widgets, so dynamic Widgets must be launched again.

```bash
aix device set-dev
aix install ./my-agent
aix launch-widget ./my-agent widgets/order/index
aix widget-layout
```

--------------------------------

### WebSocket client example (wx)

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/3-api/network/websocket.en-US.md

WeChat Mini Program (wx) example using wx.connectSocket. Establishes a WebSocket connection, sends a JSON hello message on open, logs received messages, and logs when the connection closes.

```javascript
const socket = wx.connectSocket({
  url: 'wss://example.com/realtime',
});

socket.onOpen(() => {
  socket.send(JSON.stringify({
    type: 'hello',
    sessionId: 'demo-session',
  }));
});

socket.onMessage(({ data }) => {
  console.log('Message received:', data);
});

socket.onClose(() => {
  console.log('Connection closed');
});
```

--------------------------------

### Install AIX-CLI with Cargo

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/0-guide/bundle/cli.en-US.md

Install the AIX-CLI tool using Cargo from the local source path.

```bash
cargo install --path packages/aix-cli
```

--------------------------------

### Play Local Ogg Data with setBuffer()

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/3-api/media/audio-player.en-US.md

Plays local Ogg audio data by passing the full binary payload to `setBuffer(data, hint)` with `hint = "ogg"`. The example imports the file, converts it to a `Uint8Array`, and starts playback immediately.

```javascript
import introOgg from '../assets/intro.ogg';

const player = new AudioPlayer();
const bytes = new Uint8Array(await introOgg.arrayBuffer());

player.setBuffer(bytes, 'ogg');
player.play();
```

--------------------------------

### RecorderManager.onStart(callback)

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/3-api/media/media-capture.en-US.md

Registers a callback for when recording starts.

```APIDOC
## RecorderManager.onStart(callback)

### Description
Registers a recording-start callback. The callback receives no arguments and runs after the recorder actually begins producing data. Registering again replaces the previous start callback.

### Method
RecorderManager.onStart

### Parameters
#### callback (function) - Required
Callback that receives no arguments.

```

--------------------------------

### Install an agent or package with aix install

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/7-tools/cli.en-US.md

Install a project directory or existing .aix package on the device. A directory installation reuses .aix/agent-id; an artifact installation uses the package's VERSION. --definition supplies custom Agent Definition JSON and can override generated metadata, but not agentId. The CLI checks both the device Apply result and the phone upload result; phone upload confirmation does not mean cloud indexing has finished.

```bash
aix install ./my-agent

```

```bash
aix install ./bundle.aix

```

```bash
aix install ./my-agent --definition ./agent.json --serial <serial>

```

--------------------------------

### Complete .ink Page Example

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/1-framework/open-agent-format/page-definition.en-US.md

Shows the recommended single-file .ink format for an AIUI Page. The <script type="application/json" def> block contains JSON configuration (navigation bar title, schema, usingComponents, disableScroll). The <script setup> block exports the Page logic with data, onLoad, and handleComplete. The <page> block defines the interface structure, and the <style> block defines page styles. Note that <script def> contains JSON, not executable JavaScript.

```html
<script type="application/json" def>
{
  "navigationBarTitleText": "Weather",
  "description": "Displays weather for a city.",
  "schema": {
    "data": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string",
          "description": "The city to query."
        }
      },
      "required": ["city"]
    }
  },
  "usingComponents": {
    "weather-card": "components/weather-card"
  },
  "disableScroll": true
}
</script>

<script setup>
export default {
  data: {
    city: '',
    status: 'Waiting'
  },
  onLoad(query) {
    this.setData({
      city: query.city || '',
      status: query.city ? 'Ready' : 'Choose a city'
    });
  },
  handleComplete() {
    this.finish();
  }
}
</script>

<page>
  <weather-card city="{{city}}" status="{{status}}" />
  <button bindtap="handleComplete">Done</button>
</page>

<style>
page {
  padding: 16px;
}
</style>
```

--------------------------------

### Widget file with family declaration, setup, template, and style

Source: https://github.com/yodaos-project/aiui/blob/main/skills/aiui-dev/references/framework.md

Complete Widget file for a 1x2 family. The <script def> must declare the same family as in app.json. The setup script defines data and a refresh method; the widget template binds a tap to refresh. The style uses flexbox to center content, avoiding hardcoded dimensions.

```html
<script def>
{ "widget": { "family": "1x2" } }
</script>

<script setup>
export default {
  data: { temperature: 24 },
  refresh() {
    this.setData({ temperature: this.data.temperature + 1 });
  },
};
</script>

<widget>
  <view class="widget" bindtap="refresh">
    <text>{{temperature}}°C</text>
  </view>
</widget>

<style>
.widget {
  width: 100%;
  height: 100%;
  display: flex;
  align-items: center;
  justify-content: center;
}
</style>
```

--------------------------------

### Install the AIUI Agent Development Skill with npx skills add

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/0-guide/quickstart/ai-dev.en-US.md

Installs the aiui-dev Skill into the current project using the vercel-labs/skills ecosystem. After installation, the AI assistant can help with page generation, API integration, style authoring, troubleshooting, and design alignment based on AIUI-specific context.

```bash
# Install the AIUI-related Skill into the current project
npx skills add https://github.com/jsar-project/AIUI/tree/main/skills/aiui-dev
```

--------------------------------

### Install AIX CLI and package an agent

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/4-tutorials/delivery/package-an-aix.en-US.md

Install the AIX CLI globally, then run `aix pack` outside the agent source directory to create an AIX file. Use `-o` to set the output name and `aix list` to inspect the packaged files.

```bash
npm install -g @yodaos-pkg/aix-cli

aix pack ./hello-aiui -o hello-aiui.aix
aix list ./hello-aiui.aix
```

--------------------------------

### Tool response example

Source: https://github.com/yodaos-project/aiui/blob/main/skills/aiui-cloud-apis/references/invoke-agent-api.md

Example of a tool response from the Lingzhu Agent API. It shows a `step: action` event with `status: tool_call_finish`. For tool responses, read the tool name and output from `message.metadata`. For example, `message.metadata.name === 'take_photo'` and `message.metadata.output.data.command === 'take_photo'`. A following `finish` event may contain an empty `final_answer`; do not treat it as the tool result.

```text
event:end
data:{"step":"action","serial_number":1,"agent_id":"f75f295c11334683b595afad6abf16b2","message_id":"e901877f398341538984ba2609a79d0d","status":"tool_call_finish","message":{"type":"tool","content":null,"final_answer":null,"metadata":{"name":"take_photo","output":{"status":1,"data":{"handling_required":true,"command":"take_photo","params":{"is_recall":true,"action":null,"sensor_mode":0,"name":null,"poi_name":null,"navi_type":null,"title":null,"start_time":null,"end_time":null,"prepay_id":null,"order_title":null,"total_amount":null,"pay_sign":null,"agent_id":null,"model_vendor":null,"tools":null,"agent_name":null,"agent_logo":null,"need_param":null,"prologue":null}}}}}

event:end
data:{"step":"action","serial_number":1,"agent_id":"f75f295c11334683b595afad6abf16b2","message_id":"e901877f398341538984ba2609a79d0d","status":"finish","message":{"type":"text","content":null,"final_answer":"","metadata":null}}
```

--------------------------------

### Start speech recognition with SpeechRecognition

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/3-api/ai/speech-recognition.en-US.md

Creates a SpeechRecognition instance, configures language and interim results, sets up result and error handlers, and starts recognition on a button click. Must be called during a user interaction.

```javascript
const recognition = new SpeechRecognition();
recognition.lang = 'en-US';
recognition.interimResults = true;
recognition.onresult = (event) => {
  const result = event.results[event.resultIndex];
  console.log(result[0].transcript, result.isFinal);
};
recognition.onerror = (event) => {
  console.error(event.error, event.message);
};

document.querySelector('#start').addEventListener('click', () => recognition.start());
```

--------------------------------

### Install @yodaos-pkg/cloud-integration npm package

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/5-cloud/overview.en-US.md

Install the npm package for AIUI Cloud integration. Requires Node.js 20 or later.

```bash
npm install @yodaos-pkg/cloud-integration
```

--------------------------------

### AudioPlayer File Playback Examples

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/3-api/media/audio-player.en-US.md

Code examples for using the AudioPlayer class to play audio files via the src property or setBuffer method.

```APIDOC
## [AudioPlayer] File Playback with `src`

### Description
Plays a complete audio file by assigning a local path or network URL to the `src` property. This mode is intended for background music, complete voice clips, or local audio assets.

### Constructor
`new AudioPlayer()`

### Properties
- **src** (string) - Required - Local path (relative or project-root absolute, e.g. `/assets/intro.ogg`) or network URL.
- **autoplay** (boolean) - Optional - If `true`, playback starts automatically; otherwise, call `play()` manually.

### Methods
- **onCanplay(callback)** - Registers a callback invoked when the player can start playback.
- **onEnded(callback)** - Registers a callback invoked when playback finishes.
- **play()** - Starts playback.

### Example
```javascript
const player = new AudioPlayer();

player.src = '/assets/intro.ogg';
player.autoplay = false;
player.onCanplay(() => {
  player.play();
});
player.onEnded(() => {
  console.info('playback finished');
});
```
```

```APIDOC
## [AudioPlayer] Play Local Ogg Data with `setBuffer()`

### Description
Plays a complete audio file from an in-memory binary payload. Use this when you already have the full binary data, for example from a local `.ogg` file.

### Constructor
`new AudioPlayer()`

### Methods
- **setBuffer(data, hint)** - Sets the audio buffer. `data` is a `Uint8Array` containing the binary payload; `hint` is a string indicating the format (e.g. `"ogg"`).
- **play()** - Starts playback.

### Example
```javascript
import introOgg from '../assets/intro.ogg';

const player = new AudioPlayer();
const bytes = new Uint8Array(await introOgg.arrayBuffer());

player.setBuffer(bytes, 'ogg');
player.play();
```
```

--------------------------------

### Module export example (index.js)

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/1-framework/open-agent-format/package.en-US.md

Exports a function from a package's entry point.

```javascript
// index.js
export function formatMessage(name) {
  return `Hello ${name}`;
}
```

--------------------------------

### WXML Page Structure Example

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/0-guide/framework/ui.en-US.md

Example WXML structure for a Page, demonstrating data binding with {{ }}, list rendering with ink:for, conditional rendering with ink:if, and event binding with bindtap.

```html
<!-- index.wxml -->
<view class="container">
  <view class="header">
    <text class="title">{{title}}</text>
  </view>
  
  <view class="list">
    <view class="item" ink:for="{{items}}" ink:key="id" bindtap="handleItemClick">
      <text>{{index + 1}}. {{item.name}}</text>
      <text ink:if="{{item.status === 'active'}}" class="badge">Active</text>
    </view>
  </view>
</view>
```

--------------------------------

### Create a GPX route with start, track, and end points

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/3-api/geo-data/gpx-document.en-US.md

Imports GPXDocument from the 'gpx' module and creates a new route, setting a start point, appending a track point, and setting an end point. The route can then be exported or used with the bounds property.

```javascript
import { GPXDocument } from 'gpx';

const route = new GPXDocument();

route.setStartPoint({
  latitude: 30.2741,
  longitude: 120.1551,
  name: 'Start',
});

route.appendTrackPoint({
  latitude: 30.2765,
  longitude: 120.1582,
  elevation: 18,
  time: new Date().toISOString(),
});

route.setEndPoint({
  latitude: 30.2792,
  longitude: 120.1618,
  name: 'Finish',
});
```

--------------------------------

### onLaunch(Object options)

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/3-api/framework/app.en-US.md

Runs once after the App finishes initializing. `options` contains the launch context. Use this callback to initialize `globalData`, restore persistent state, or establish app-level resources. Do not use it for work that depends on a page completing its initial render.

```APIDOC
## onLaunch(Object options)

### Description
Runs once after the App finishes initializing. `options` contains the launch context. Use this callback to initialize `globalData`, restore persistent state, or establish app-level resources. Do not use it for work that depends on a page completing its initial render.

### Method
N/A (lifecycle callback)

### Endpoint
N/A

### Parameters
- **options** (Object) - Required - The launch context.

### Request Example
```javascript
onLaunch(options) {
  // 智能体初始化
}
```

### Response
#### Success Response
No explicit response documented.

#### Response Example
N/A
```

--------------------------------

### Speak a Text Response (Web and wx)

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/3-api/ai/speech-synthesis.en-US.md

Two platform-specific ways to speak a text response. The Web example uses speechSynthesis.speak() with an utterance and 'enqueue' mode; the wx example uses wx.speech.playTTS(). Both immediately enter the direct-playback flow and do not return a generation task or independent player.

```javascript
const utterance = new SpeechSynthesisUtterance('欢迎使用 AIUI');
speechSynthesis.speak(utterance, 'enqueue');
```

```javascript
wx.speech.playTTS('欢迎使用 AIUI');
```

--------------------------------

### Avoid starting the same work twice with a shared promise

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/1-framework/open-agent-format/agent-worker.en-US.md

Stores the active promise so multiple onOpen calls share the same setup. The service is created once and reused; the promise is cleared after completion.

```javascript
export default {
  service: null,
  startPromise: null,

  onOpen(event) {
    event.waitUntil(this.ensureService());
  },

  ensureService() {
    if (this.service) return Promise.resolve(this.service);

    if (!this.startPromise) {
      this.startPromise = this.createService()
        .then((service) => {
          this.service = service;
          return service;
        })
        .finally(() => {
          this.startPromise = null;
        });
    }
    return this.startPromise;
  },

  async createService() {
    return { startedAt: Date.now() };
  },
};
```

--------------------------------

### AudioPlayer

Source: https://github.com/yodaos-project/aiui/blob/main/skills/aiui-dev/references/apis/media.md

Constructor, properties, methods, and usage example for the AudioPlayer class.

```APIDOC
## `new AudioPlayer(options?)`

### Description
Creates a new AudioPlayer instance for general-purpose audio playback, supporting both full files and streaming data.

### Constructor
`new AudioPlayer(options?)`

### Parameters
- **options** (object) - Optional. Configuration for streaming playback. Currently supports `format: 'pcm'` and `format: 'ogg_opus'`.

### Properties
- `src` - The audio source. Can be a relative local path, a project-root absolute path (e.g., `/assets/intro.ogg`), or a network URL.
- `autoplay` - Whether to start playback automatically.
- `loop` - Whether to loop playback.
- `volume` - Playback volume.
- `currentTime` - Current playback position.
- `paused` - Whether playback is paused.

### Methods
- `play()` - Starts playback.
- `pause()` - Pauses playback.
- `stop()` - Stops playback.
- `seek(position)` - Seeks to a specified position.
- `destroy()` - Destroys the player instance.
- `append(buffer)` - Appends a streaming data chunk.
- `finish()` - Signals the end of a streaming data.

### Example
```javascript
import { AudioPlayer } from 'audio';

const player = new AudioPlayer();
player.src = '/assets/intro.ogg';
player.loop = true;
player.play();
```
```

--------------------------------

### Shadows and Opacity Example

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/1-framework/wxss/property.en-US.md

Adds a box shadow and sets opacity to 0.9 for a button.

```css
.button {
  box-shadow: 0 4rpx 8rpx rgba(0, 0, 0, 0.1);
  opacity: 0.9;
}
```

--------------------------------

### Create a LanguageModel session with initial prompts and a tool

Source: https://github.com/yodaos-project/aiui/blob/main/skills/aiui-dev/references/apis/ai.md

Shows how to check availability and create a LanguageModelSession with initial prompts and a function tool. The example throws if availability is not 'available'. The session model resolves from options.model or the host defaultModel.

```javascript
import { LanguageModel } from 'language-model';

if ((await LanguageModel.availability()) !== 'available') {
  throw new Error('LanguageModel is unavailable');
}

const session = await LanguageModel.create({
  initialPrompts: [
    {
      role: 'system',
      content: 'You are a concise travel assistant.',
    },
  ],
  tools: [
    {
      type: 'function',
      function: {
        name: 'get_weather',
        description: 'Look up current weather by city name',
        parameters: {
          type: 'object',
          properties: {
            city: { type: 'string' },
          },
          required: ['city'],
        },
      },
    },
  ],
});
```

--------------------------------

### Get account token via HTTP and curl

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/5-cloud/account-token.en-US.md

HTTP endpoint and curl example for retrieving an account token. A successful response is 200 application/json with a string schema; invalid authentication returns 401.

```http
GET https://<aiui-host>/account/v1/token
```

```bash
curl --location 'https://<aiui-host>/account/v1/token' \
  --header 'access_token: <ACCOUNT_ACCESS_TOKEN>'
```

--------------------------------

### task.json for 080-create-greeting

Source: https://github.com/yodaos-project/aiui/blob/main/bench/README.md

Example task.json for a Page creation task. The workspace starts with app.json and app.js; the solver must create the .ink file. Required checks verify the route, file, template binding, and behavior; constraints forbid DOM APIs.

```json
{
  "schemaVersion": 1,
  "id": "080-create-greeting",
  "category": "create",
  "difficulty": "easy",
  "description": "Create a Page at pages/index/index that displays Hello AIUI from bound data. Use AIUI APIs, not browser DOM APIs.",
  "aiuiVersion": "current",
  "workspace": "./workspace",
  "grading": {
    "required": [
      { "id": "route", "type": "route", "value": "pages/index/index" },
      { "id": "page", "type": "file", "path": "pages/index/index.ink" },
      { "id": "message", "type": "template", "path": "pages/index/index.ink", "tag": "text", "binding": "message" },
      { "id": "initial-message", "type": "behavior", "path": "pages/index/index.ink", "expect": { "message": "Hello AIUI" } }
    ],
    "regression": [],
    "constraints": [{ "id": "no-dom", "type": "noDom" }]
  }
}
```

--------------------------------

### Create VideoContext and play on ready

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/3-api/media/video.en-US.md

After the component is mounted, create its context on the current page using wx.createVideoContext('briefing') and start playback. The context is stored on the page instance and cleaned up on unload.

```javascript
export default {
  onReady() {
    this.video = wx.createVideoContext('briefing');
    this.video?.play();
  },

  onUnload() {
    this.video = null;
  },
};
```

--------------------------------

### Recommended .ink single-file component form

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/1-framework/open-agent-format/custom-components.en-US.md

Recommended single-file component structure in AIUI .ink: <script def> for metadata, <template> for structure, <style> for scoped styles, and <script setup> for logic. This example defines a card component with a title property.

```html
<script def>
{
  "component": true
}
</script>

<template>
  <view class="card">
    <text>{{title}}</text>
  </view>
</template>

<style>
.card {
  display: flex;
  padding: 12px;
}
</style>

<script setup>
export default {
  properties: {
    title: {
      type: String,
      value: 'Untitled'
    }
  }
}
</script>
```

--------------------------------

### Build and test the CLI from source

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/7-tools/cli.en-US.md

Run these commands in the AIX repository's packages/cli directory to install dependencies, build the CLI (compiling the Rust engine and bundling the TypeScript program), and verify the build by displaying help.

```bash
npm install
npm run build
node dist/cli.js --help
```

--------------------------------

### List Rendering Example

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/1-framework/wxml/intro.en-US.md

Uses ink:for to iterate over an array and display each item.

```html
<!--wxml-->
<view ink:for="{{array}}"> {{item}} </view>
```

```javascript
// page.js
export default {
  data: {
    array: [1, 2, 3, 4, 5]
  }
}
```

--------------------------------

### Transition and Active State Example

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/1-framework/wxss/property.en-US.md

Defines a transition on all properties and a scale transform on active state.

```css
.btn-hover {
  transition: all 0.3s ease;
}

.btn-hover:active {
  transform: scale(0.95);
}
```

--------------------------------

### Templates Example

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/1-framework/wxml/intro.en-US.md

Defines a template named 'staffName' and uses it with different data objects.

```html
<!--wxml-->
<template name="staffName">
  <view>
    FirstName: {{firstName}}, LastName: {{lastName}}
  </view>
</template>

<template is="staffName" data="{{...staffA}}"></template>
<template is="staffName" data="{{...staffB}}"></template>
<template is="staffName" data="{{...staffC}}"></template>
```

```javascript
// page.js
export default {
  data: {
    staffA: {firstName: 'Hulk', lastName: 'Hu'},
    staffB: {firstName: 'Shang', lastName: 'You'},
    staffC: {firstName: 'Gideon', lastName: 'Lin'}
  }
}
```

--------------------------------

### Fetch remote data in onLoad() with loading and error states

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/4-tutorials/data/load-remote-data.en-US.md

Starts the request in onLoad(), sets loading to true, then updates page data for success or failure. Uses fetch() with an example HTTPS endpoint; replace it with your own. Throws an error if the response is not ok, and catches errors to set the error message.

```html
<script setup>
export default {
  data: {
    loading: true,
    error: '',
    message: ''
  },

  async onLoad() {
    try {
      const response = await fetch('https://api.example.com/message');
      if (!response.ok) {
        throw new Error(`Request failed: ${response.status}`);
      }

      const result = await response.json();
      this.setData({
        loading: false,
        message: result.message || 'Request completed'
      });
    } catch (error) {
      this.setData({
        loading: false,
        error: error instanceof Error ? error.message : 'Request failed'
      });
    }
  }
};
</script>
```

--------------------------------

### RecorderManager.start(options)

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/3-api/media/media-capture.en-US.md

Starts a new recording session with configurable sample rate, channels, format, and frame size.

```APIDOC
## RecorderManager.start(options)

### Description
Starts a new recording session. Register onFrameRecorded(), onError(), and onStop() first so an early event is not missed. Calling it again while already recording does not create a second session.

### Method
RecorderManager.start

### Parameters
#### options (object) - Optional
- **options.sampleRate** (number) - Optional - Default: 16000 - Requested sample rate.
- **options.numberOfChannels** (number) - Optional - Default: 1 - Requested channel count.
- **options.format** ('pcm' | 'opus') - Optional - Default: 'pcm' - Requested encoding format.
- **options.frameSize** (number) - Optional - Default: 250 - Audio-frame callback interval in milliseconds; only positive values apply.

### Returns
Promise<void>

```

--------------------------------

### wx.request GET with Authorization header

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/3-api/network/https.en-US.md

Sends a GET request with a custom Authorization header. The default method is GET, so no method property is needed.

```javascript
wx.request({
  url: 'https://example.com/items',
  header: {
    Authorization: `Bearer ${token}`,
  },
});
```

--------------------------------

### navigator.mediaDevices

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/3-api/navigator.en-US.md

Media-capture entry point with getUserMedia(), enumerateDevices(), and getSupportedConstraints().

```APIDOC
## navigator.mediaDevices

### Description
Media-capture entry point with `getUserMedia()`, `enumerateDevices()`, and `getSupportedConstraints()`. Camera and microphone access depend on host permissions and device capabilities. See [Media Capture](/AIUI/api/media-media-capture).

### Type
`MediaDevices`.
```

--------------------------------

### Example asset directory structure

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/1-framework/open-agent-format/assets.en-US.md

Shows a recommended but optional layout for organizing static assets under an assets/ directory. This is a suggestion, not a runtime requirement.

```text
agent-app/
├── app.json
├── app.js
├── pages/
│   └── home/
│       └── index.ink
└── assets/
    ├── logo.png
    ├── intro.mp4
    ├── notification.ogg
    ├── loading.json
    └── images/
        └── lottie-icon.png
```

--------------------------------

### Recognize Current Microphone with SpeechRecognitionSession

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/3-api/ai/speech-recognition.en-US.md

Complete example of recognizing the current microphone. It selects a shared audio format, creates a SpeechRecognitionSession with custom phrases and initial context, records via MediaRecorder, and writes chunks to the session. The XML buttons trigger start and stop; startMicrophoneRecognition() must be called from a user click. On stop, it waits for all chunks, closes the writer, and releases the microphone tracks.

```javascript
export default {
  session: null,
  recorder: null,
  microphone: null,
  writer: null,
  writeQueue: Promise.resolve(),

  async startMicrophoneRecognition() {
    const capabilities = await SpeechRecognitionSession.getCapabilities();
    const candidates = ['audio/ogg;codecs=opus', 'audio/wav'];
    const mimeType = candidates.find((candidate) =>
      MediaRecorder.isTypeSupported(candidate) &&
      capabilities.audioFormats.some(
        (format) => format.mimeType.toLowerCase() === candidate
      )
    );

    if (!mimeType) {
      throw new Error('Recording and recognition have no shared audio format');
    }

    const session = new SpeechRecognitionSession({
      lang: 'en-US',
      interimResults: capabilities.interimResults,
      audio: { mimeType },
      phrases: capabilities.phrases
        ? [
            { phrase: 'Rokid', boost: 5 },
            { phrase: 'AIUI', boost: 5 },
          ]
        : undefined,
    });
    this.session = session;

    if (capabilities.contextUpdates) {
      await session.updateContext([
        { role: 'user', text: 'I am asking about Rokid products by voice.' },
        { role: 'assistant', text: 'Please say the product name or question.' },
      ]);
    }

    session.onresult = (event) => {
      const result = event.results[event.resultIndex][0];
      console.log(result.transcript);
    };
    session.onerror = (event) => {
      console.error(event.error, event.message);
    };

    this.microphone = await navigator.mediaDevices.getUserMedia({ audio: true });
    this.writer = session.audio.getWriter();
    this.writeQueue = Promise.resolve();
    this.recorder = new MediaRecorder(this.microphone, { mimeType });

    this.recorder.ondataavailable = (event) => {
      if (event.data.size === 0) return;
      this.writeQueue = this.writeQueue.then(() =>
        this.writer.write(event.data)
      );
    };

    this.recorder.onstop = async () => {
      try {
        await this.writeQueue;
        await this.writer.close();
      } finally {
        this.microphone.getTracks().forEach((track) => track.stop());
        this.recorder = null;
        this.microphone = null;
        this.writer = null;
        this.session = null;
      }
    };

    // Start from a user click and produce an audio chunk every 250 ms.
    this.recorder.start(250);
  },

  stopMicrophoneRecognition() {
    if (this.recorder && this.recorder.state !== 'inactive') {
      this.recorder.stop();
    }
  },
};
```

```xml
<button bindtap="startMicrophoneRecognition">Start recognition</button>
<button bindtap="stopMicrophoneRecognition">Stop recognition</button>
```

--------------------------------

### Preview a project with aix preview

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/7-tools/cli.en-US.md

Preview a source directory or .aix package. By default, the CLI starts a local server and prints its address. Add --launch to open your default browser automatically; --launch-target selects a viewport (default blank is 480×352, current is 448×150).

```bash
aix preview bundle.aix
```

```bash
aix preview ./my-agent
```

```bash
aix preview bundle.aix --launch
```

```bash
aix preview bundle.aix --launch --launch-target current
```

--------------------------------

### Example package.json with exports and ink.components

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/1-framework/open-agent-format/package.en-US.md

Defines package metadata including name, main, exports, and explicit component exports for usingComponents.

```json
{
  "name": "@demo/ui",
  "main": "./index.js",
  "exports": {
    ".": "./index.js",
    "./utils": "./utils.js"
  },
  "ink": {
    "components": {
      "./demo-card": "./components/demo-card"
    }
  }
}
```

--------------------------------

### Initialize an AIUI project with npm create

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/7-tools/editor.en-US.md

Initializes a new AIUI agent project. Run the first command to scaffold the project, then navigate into the created folder and list its contents.

```plain
npm create @yodaos-pkg/aiui-agent@latest my-agent
```

```plain
cd my-agent  # Enter the my-agent folder
ls           # List files and subdirectories
```

--------------------------------

### lifetimes.ready()

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/3-api/framework/component.en-US.md

Documentation for the `ready` lifecycle callback.

```APIDOC
## lifetimes.ready()

### Description
Runs after the component subtree completes its initial render. Use it for initialization that depends on the component view being ready. Later state updates do not trigger this callback again.
```

--------------------------------

### GET /api/agent/stream

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/3-api/network/event-source.en-US.md

Creates an EventSource connection to the specified URL for receiving server-sent events. The connection is established via a GET request.

```APIDOC
## [GET] /api/agent/stream

### Description
Creates an EventSource connection to the specified URL for receiving server-sent events. The connection is established via a GET request.

### Method
GET

### Endpoint
/api/agent/stream

### Parameters
#### Query Parameters
- **url** (string) - Required - The SSE service URL to connect to.

### Request Example
```javascript
const eventSource = wx.createEventSource({
  url: '/api/agent/stream',
});
```

### Response
#### Success Response (200)
- **data** (string) - The payload of the message event.

#### Response Example
```javascript
eventSource.onMessage(({ data }) => {
  console.log('Incremental content received:', data);
});
```
```

--------------------------------

### GET /api/agent/stream

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/3-api/network/event-source.en-US.md

Creates an EventSource connection to the specified URL for receiving server-sent events. The connection is established via a GET request.

```APIDOC
## [GET] /api/agent/stream

### Description
Creates an EventSource connection to the specified URL for receiving server-sent events. The connection is established via a GET request.

### Method
GET

### Endpoint
/api/agent/stream

### Parameters
#### Query Parameters
- **url** (string) - Required - The SSE service URL to connect to.

### Request Example
```javascript
const eventSource = new EventSource('/api/agent/stream');
```

### Response
#### Success Response (200)
- **data** (string) - The payload of the message event.

#### Response Example
```javascript
eventSource.onmessage = (event) => {
  console.log('Received incremental content:', event.data);
};
```
```

--------------------------------

### Open Page with aix launch-page

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/0-guide/debug/cli_device_debug.en-US.md

Open the project's entry page or a specific page. `launch-page` only sends an open request; it does not install the agent or prove that the page rendered successfully.

```bash
aix launch-page ./my-agent
aix launch-page ./my-agent pages/index/index
```

--------------------------------

### AudioScheduledSourceNode

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/3-api/media/web-audio.en-US.md

AudioScheduledSourceNode is the base class for sources that can start and stop on the audio timeline. It provides start and stop methods and an onended event handler.

```APIDOC
## AudioScheduledSourceNode

### Description
Base class for sources that can start and stop on the audio timeline. Cannot be constructed directly.

### Members
- **start(when?)** - Starts at an audio time, or immediately when omitted.
- **stop(when?)** - Stops at an audio time, or immediately when omitted.
- **onended** - Called when the source finishes.

### Inherited by
OscillatorNode and AudioBufferSourceNode inherit these capabilities.
```

--------------------------------

### Create microphone source and connect to analyser

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/3-api/media/web-audio.en-US.md

Uses getUserMedia to obtain an audio stream, creates an AudioContext, a MediaStreamAudioSourceNode, and an AnalyserNode, then connects the microphone to the analyser. The stream must contain an audio track; otherwise the constructor throws TypeError.

```javascript
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const context = new AudioContext();
const microphone = context.createMediaStreamSource(stream);
const analyser = context.createAnalyser();

microphone.connect(analyser);
```

--------------------------------

### Scenario check JSON example: timer-cleanup

Source: https://github.com/yodaos-project/aiui/blob/main/bench/README.md

Example of a scenario check definition. It uses the 'scenario' type, specifies a path to an Ink file, and defines steps that call lifecycle methods, advance the virtual clock, and expect data and effects. This example verifies timer cleanup on unload.

```json
{
  "id": "timer-cleanup", "type": "scenario", "path": "pages/index/index.ink",
  "steps": [
    { "action": "call", "method": "onShow" },
    { "action": "advance", "ms": 1000 },
    { "action": "expect", "data": { "ticks": 1 }, "effects": { "activeTimers": 1 } },
    { "action": "call", "method": "onUnload" },
    { "action": "advance", "ms": 1000 },
    { "action": "expect", "data": { "ticks": 1 }, "effects": { "activeTimers": 0 } }
  ]
}
```

--------------------------------

### Create a new project with locally available package

Source: https://github.com/yodaos-project/aiui/blob/main/packages/create-aiui-agent/README.md

Use this command if the package is already available locally, to scaffold a new project named 'my-agent'.

```bash
npx create-aiui-agent my-agent
```

--------------------------------

### Web EventSource Example

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/3-api/network/event-source.en-US.md

Web-standard EventSource example for receiving server-pushed messages. Uses onmessage to log data and onerror to close the connection on error.

```javascript
const eventSource = new EventSource('/api/agent/stream');

eventSource.onmessage = (event) => {
  console.log('Received incremental content:', event.data);
};

eventSource.onerror = () => {
  console.error('Event Source connection error');
  eventSource.close();
};
```

--------------------------------

### onShow(Object options)

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/3-api/framework/app.en-US.md

Runs when the App is first shown and whenever it returns from the background. `options` contains the current show context. Use it to refresh app-level visibility state, resume paused work, or check whether data needs to be synchronized again.

```APIDOC
## onShow(Object options)

### Description
Runs when the App is first shown and whenever it returns from the background. `options` contains the current show context. Use it to refresh app-level visibility state, resume paused work, or check whether data needs to be synchronized again.

### Method
N/A (lifecycle callback)

### Endpoint
N/A

### Parameters
- **options** (Object) - Required - The current show context.

### Request Example
```javascript
onShow(options) {
  // 智能体显示
}
```

### Response
#### Success Response
No explicit response documented.

#### Response Example
N/A
```

--------------------------------

### wx.speech.startRecognition()

Source: https://github.com/yodaos-project/aiui/blob/main/skills/aiui-dev/references/apis/wx.md

Starts speech recognition. Requires an interactive call site and throws when the interaction gate check fails.

```APIDOC
## wx.speech.startRecognition()

### Description
Starts speech recognition. Requires an interactive call site and throws when the interaction gate check fails.

### Method
startRecognition

### Parameters
None

### Returns
- **string** - The result of the operation.

### Errors
- Throws an error if the interaction gate check fails.

```

--------------------------------

### Install TypeScript and AIUI type package

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/1-framework/open-agent-format/module.en-US.md

Command to install TypeScript and the AIUI type package as dev dependencies. Required before using TypeScript in an AIUI project.

```bash
npm install -D typescript @yodaos-pkg/ink-env
```

--------------------------------

### fetch() GET request

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/3-api/network/https.en-US.md

Sends a GET request to the given URL and awaits the Response object. This is the simplest way to fetch data when you only need the final result.

```javascript
const response = await fetch('https://example.com/data.json');
```

--------------------------------

### Export static HTML with --html-out

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/7-tools/cli.en-US.md

Export static HTML instead of starting a server. This option cannot be combined with --launch.

```bash
aix preview bundle.aix --html-out ./artifacts/preview.html
```

--------------------------------

### Install AIX CLI and Check Device Status

Source: https://github.com/yodaos-project/aiui/blob/main/documentation/0-guide/debug/cli_device_debug.en-US.md

Install the AIX CLI globally, verify ADB sees the device, and inspect device status. `adb devices` should show status `device`; if `unauthorized`, allow debugging on the device. `aix device` displays Developer Mode, Widget status, and installed agents.

```bash
npm install -g @yodaos-pkg/aix-cli
adb devices
aix device
```