# Augma 0.2.0

Source: https://augma.yunyoujun.cn/markdown/ai/index.md

# AI 接入

让编程助手使用真实组件、明确的 API 和一致的设计规范。首版面向开发时的集成与界面构建。

## 安装 Skill

```sh
npx skills add YunYouJun/augma --skill augma
```

仓库中的 Skill 适用于支持 Agent Skills 的编程助手，例如 Codex 和 Claude。以下提示可以直接使用：

```text
使用 $augma 为当前 Vue 项目创建一个设备控制面板。
使用公开组件和语义 tokens，保留现有品牌与可访问行为。
先查阅组件 API，再实现状态切换和交互示例。
```

新版本的 Skill 和 Registry 需要随本仓库发布后才能通过公开 URL 获取；本地开发可直接加载 `skills/augma/SKILL.md`，并使用本地预览的资源地址。

## 机器可读入口

- [llms.txt](/llms.txt)：精简文档索引。
- [llms-full.txt](/llms-full.txt)：完整 Markdown 文档集合。
- [components.json](/components.json)：包含版本、导入、API、示例与 Registry 地址的组件契约。
- <a href="/markdown/guide/index.md" download>纯文本指南</a>：方便编程助手直接读取。

所有入口由同一套源码、示例与元数据生成。`components.json` 使用 `schemaVersion: 1`，消费者应检查版本。

## 组件 Registry

在已初始化 shadcn-vue 的 Vue 项目中执行：

```sh
pnpm dlx shadcn-vue@2.8.2 add https://augma.yunyoujun.cn/r/button.json
pnpm dlx shadcn-vue@2.8.2 add https://augma.yunyoujun.cn/r/dialog.json
```

首批支持 Button、Input、Panel、Dialog、HudStatus、HudProgress。Registry 复制与 npm 组件相同的源文件，同时声明样式与行为依赖。

在应用入口导入：

```ts
import '@augma/core/style.css'
```

复制后的 Vue 文件可以自由修改。Registry 自身不要求 Tailwind 来渲染 Augma 样式；CLI 对宿主项目的初始化要求遵循 shadcn-vue。

## 验收一个 AI 生成的界面

检查实际导入和 Props 是否存在，执行类型检查和构建，使用键盘走完主流程，并检查窄屏与减少动画设置。可用以下任务检查编程助手：

1. 创建带有 Select、Switch、Slider 的控制面板。
2. 创建同时展示正常、等待、错误状态的 HUD。
3. 通过 tokens 更改强调色，保留焦点和文字对比。

[展示页](/showcase/) 提供这三类任务的可运行参考，每个示例都可展开和复制源码。纯文本源文件：

- <a href="/markdown/compositions/control-panel.vue" download>控制面板</a>
- <a href="/markdown/compositions/hud.vue" download>HUD 状态</a>
- <a href="/markdown/compositions/theme.vue" download>主题定制</a>

Skill 提供设计与集成知识。站内聊天和实时生成 UI 属于后续独立功能。


---

Source: https://augma.yunyoujun.cn/markdown/components/button.md


# Button 按钮

轻触，即刻响应。用于触发操作与状态切换。

## 基础用法

[Vue example](https://augma.yunyoujun.cn/markdown/examples/button.vue)

## API

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `variant` | 'primary' \| 'outline' \| 'ghost' | 'primary' | 视觉层级 |
| `disabled` | boolean | false | 禁止操作 |
| `loading` | boolean | false | 处理中，同时禁止重复操作 |
| `type` | 'button' \| 'submit' \| 'reset' | 'button' | 原生按钮类型 |

### 插槽

- default：按钮文字

## 键盘操作与使用边界

Tab 聚焦；Enter 或 Space 激活。加载中与禁用状态不接受操作。

## 安装

```ts
import { AgmButton } from 'augma'
import 'augma/style.css'
```

复制可编辑源码：

```sh
pnpm dlx shadcn-vue@2.8.2 add https://augma.yunyoujun.cn/r/button.json
```


---

Source: https://augma.yunyoujun.cn/markdown/components/dialog.md


# Dialog 对话框

让注意力聚焦在当前操作，完成后回到原处。

## 基础用法

[Vue example](https://augma.yunyoujun.cn/markdown/examples/dialog.vue)

## API

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `open` | boolean | false | 通过 v-model:open 更新 |
| `title` | string | 必填 | 可访问标题 |
| `description` | string | 必填 | 操作说明 |

### 事件

- `update:open(boolean)`

### 插槽

- trigger：单个可聚焦触发元素
- default：内容
- footer：操作区

## 键盘操作与使用边界

打开后焦点进入对话框，Tab 循环，Escape 关闭并返回触发器。推荐使用 trigger 插槽保证焦点返回。

## 安装

```ts
import { AgmDialog } from 'augma'
import 'augma/style.css'
```

复制可编辑源码：

```sh
pnpm dlx shadcn-vue@2.8.2 add https://augma.yunyoujun.cn/r/dialog.json
```


---

Source: https://augma.yunyoujun.cn/markdown/components/hud-progress.md


# HudProgress 进度

线性或环形进度，让过程清晰可见。

## 基础用法

[Vue example](https://augma.yunyoujun.cn/markdown/examples/hud-progress.vue)

## API

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `label` | string | 必填 | 进度名称 |
| `value` | number | undefined | 未提供或非有限数值表示不确定进度 |
| `max` | number | 100 | 有效上界，非法值回退到 100 |
| `variant` | 'bar' \| 'ring' | 'bar' | 显示形式 |

## 键盘操作与使用边界

只读进度使用 progressbar 语义；数值被约束到 0 到 max，不确定进度不设置 aria-valuenow。

## 安装

```ts
import { AgmHudProgress } from 'augma'
import 'augma/style.css'
```

复制可编辑源码：

```sh
pnpm dlx shadcn-vue@2.8.2 add https://augma.yunyoujun.cn/r/hud-progress.json
```


---

Source: https://augma.yunyoujun.cn/markdown/components/hud-status.md


# HudStatus 状态

用文字与颜色共同表达状态变化。

## 基础用法

[Vue example](https://augma.yunyoujun.cn/markdown/examples/hud-status.vue)

## API

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `tone` | 'success' \| 'warning' \| 'danger' \| 'neutral' | 'success' | 状态语义 |

### 插槽

- default：状态文字

## 键盘操作与使用边界

使用 role=status 温和播报动态变化；始终提供文字，不单靠颜色。

## 安装

```ts
import { AgmHudStatus } from 'augma'
import 'augma/style.css'
```

复制可编辑源码：

```sh
pnpm dlx shadcn-vue@2.8.2 add https://augma.yunyoujun.cn/r/hud-status.json
```


---

Source: https://augma.yunyoujun.cn/markdown/components/icon-button.md


# IconButton 图标按钮

圆形操作入口，为图标提供明确的可访问名称。

## 基础用法

[Vue example](https://augma.yunyoujun.cn/markdown/examples/icon-button.vue)

## API

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `label` | string | 必填 | 可访问名称 |
| `disabled` | boolean | false | 禁止操作 |
| `pressed` | boolean | undefined | 可选的切换状态 |

### 插槽

- default：图标，默认加号

## 键盘操作与使用边界

Tab 聚焦；Enter 或 Space 激活。label 必须描述动作。

## 安装

```ts
import { AgmIconButton } from 'augma'
import 'augma/style.css'
```


---

Source: https://augma.yunyoujun.cn/markdown/components/index.md

# 组件

从原生交互到轻盈 HUD。每个组件都有可运行示例、完整源码和明确的 API。




---

Source: https://augma.yunyoujun.cn/markdown/components/input.md


# Input 输入框

清晰的标签与错误信息，让输入始终有方向。

## 基础用法

[Vue example](https://augma.yunyoujun.cn/markdown/examples/input.vue)

## API

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `id` | string | undefined | 可选的输入元素 ID，默认自动生成 |
| `modelValue` | string | '' | 通过 v-model 更新 |
| `label` | string | 必填 | 可见标签 |
| `error` | string | undefined | 错误说明 |
| `disabled` | boolean | false | 禁止输入 |
| `type` | string | 'text' | 原生输入类型 |

### 事件

- `update:modelValue(string)`

## 键盘操作与使用边界

使用原生输入键盘行为。placeholder、name、autocomplete、required 等属性传递到 input。

## 安装

```ts
import { AgmInput } from 'augma'
import 'augma/style.css'
```

复制可编辑源码：

```sh
pnpm dlx shadcn-vue@2.8.2 add https://augma.yunyoujun.cn/r/input.json
```


---

Source: https://augma.yunyoujun.cn/markdown/components/panel.md


# Panel 面板

轻盈的半透明容器，为相关信息建立层次。

## 基础用法

[Vue example](https://augma.yunyoujun.cn/markdown/examples/panel.vue)

## API

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `title` | string | undefined | 面板标题 |

### 插槽

- default：内容
- header：自定义标题
- actions：标题栏操作

## 键盘操作与使用边界

面板本身不接管焦点；内容遵循自然的文档顺序。

## 安装

```ts
import { AgmPanel } from 'augma'
import 'augma/style.css'
```

复制可编辑源码：

```sh
pnpm dlx shadcn-vue@2.8.2 add https://augma.yunyoujun.cn/r/panel.json
```


---

Source: https://augma.yunyoujun.cn/markdown/components/select.md


# Select 选择器

在清晰的选项列表中做出选择。

## 基础用法

[Vue example](https://augma.yunyoujun.cn/markdown/examples/select.vue)

## API

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `modelValue` | string | undefined | 通过 v-model 更新 |
| `label` | string | 必填 | 可见标签 |
| `options` | { label: string, value: string, disabled?: boolean }[] | 必填 | value 必须为非空且唯一的字符串 |
| `placeholder` | string | '请选择' | 未选择提示 |
| `disabled` | boolean | false | 禁止选择 |
| `name` | string | undefined | 表单字段名 |

### 事件

- `update:modelValue(string)`

## 键盘操作与使用边界

Enter / Space 打开，方向键移动，Enter 选择，Escape 关闭；支持字符搜索。

## 安装

```ts
import { AgmSelect } from 'augma'
import 'augma/style.css'
```


---

Source: https://augma.yunyoujun.cn/markdown/components/slider.md


# Slider 滑块

以连续反馈调整数值，支持触控与键盘。

## 基础用法

[Vue example](https://augma.yunyoujun.cn/markdown/examples/slider.vue)

## API

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `modelValue` | number | 0 | 通过 v-model 更新 |
| `label` | string | 必填 | 可见标签 |
| `min` | number | 0 | 最小值 |
| `max` | number | 100 | 最大值，应大于 min |
| `step` | number | 1 | 正数步长 |
| `disabled` | boolean | false | 禁止调整 |
| `name` | string | undefined | 表单字段名 |

### 事件

- `update:modelValue(number)`

## 键盘操作与使用边界

方向键按步长调节，Home / End 到达边界，Page Up / Down 大步调节。

## 安装

```ts
import { AgmSlider } from 'augma'
import 'augma/style.css'
```


---

Source: https://augma.yunyoujun.cn/markdown/components/switch.md


# Switch 开关

即时切换一个明确的二元状态。

## 基础用法

[Vue example](https://augma.yunyoujun.cn/markdown/examples/switch.vue)

## API

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `modelValue` | boolean | false | 通过 v-model 更新 |
| `label` | string | 必填 | 可见标签 |
| `disabled` | boolean | false | 禁止切换 |
| `name` | string | undefined | 表单字段名 |

### 事件

- `update:modelValue(boolean)`

## 键盘操作与使用边界

Tab 聚焦，Space 或 Enter 切换。

## 安装

```ts
import { AgmSwitch } from 'augma'
import 'augma/style.css'
```


---

Source: https://augma.yunyoujun.cn/markdown/components/toast.md


# Toast 通知

对已完成的操作给出轻量、可关闭的反馈。

## 基础用法

[Vue example](https://augma.yunyoujun.cn/markdown/examples/toast.vue)

## API

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `open` | boolean | false | 通过 v-model:open 更新 |
| `title` | string | 必填 | 通知标题 |
| `description` | string | undefined | 补充内容 |
| `duration` | number | 5000 | 自动关闭时间（毫秒） |

### 事件

- `update:open(boolean)`

## 键盘操作与使用边界

F8 聚焦通知区域，Escape 或关闭按钮关闭。悬停或聚焦时暂停倒计时。每个应用建议放置一个 AgmToast。

## 安装

```ts
import { AgmToast } from 'augma'
import 'augma/style.css'
```


---

Source: https://augma.yunyoujun.cn/markdown/components/tooltip.md


# Tooltip 提示

为可聚焦操作补充简短说明。

## 基础用法

[Vue example](https://augma.yunyoujun.cn/markdown/examples/tooltip.vue)

## API

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `text` | string | 必填 | 提示内容 |
| `delay` | number | 250 | 悬停延迟（毫秒） |

### 插槽

- default：单个可聚焦触发元素

## 键盘操作与使用边界

悬停或聚焦触发元素显示，Escape 关闭。触屏必需信息应直接展示，不仅放在提示里。

## 安装

```ts
import { AgmTooltip } from 'augma'
import 'augma/style.css'
```


---

Source: https://augma.yunyoujun.cn/markdown/design/index.md

# 设计规范

灵感来自《刀剑神域：序列之争》中的 Augma：在真实环境之上，以清晰、轻盈、克制的方式呈现信息。这里将这一方向提炼为原创的 Web 界面语言。

## 表面与层级

白色与冰灰构成主要表面。透明度与细线边框建立层次，切角只用于可操作入口，环形元素用于状态和进度。阅读区域保持安静，复杂背景上的面板应有足够实色背景，保证文字对比。

## 颜色

| Token | 浅色值 | 用途 |
| --- | --- | --- |
| `--agm-bg` | `#ffffff` | 页面背景 |
| `--agm-surface` | `#f3f6f8` | 次级表面 |
| `--agm-text` | `#263442` | 主要文字 |
| `--agm-muted` | `#5c7187` | 辅助说明 |
| `--agm-accent` | `#b75e08` | 主要操作与强调 |
| `--agm-highlight` | `#f28c12` | 装饰性高亮与 HUD 图形 |
| `--agm-cyan` | `#258ca4` | 连续控制 |
| `--agm-success` | `#287947` | 成功 |
| `--agm-danger` | `#bc394a` | 错误 |

在应用根部覆盖变量即可定制主题。改变强调色时同时检查 `--agm-on-accent` 的文字对比。状态必须包含文字，不能仅用颜色表达。

## 字体与排版

站点使用 Exo 2 的几何字形，中文回退系统无衬线字体。组件通过 `--agm-font` 接受宿主字体；CSS 包不请求外部字体。正文与控件保持易读尺寸，数字适合展示实时状态。

## 操作与动效

按钮、开关等操作区至少提供 44px 的触控高度或足够的周边操作空间。焦点环保持完整，不被切角裁剪。动效用于解释状态变化，尊重 `prefers-reduced-motion`。

## 组合

Panel 建立信息分组；HudStatus 说明当前状态；HudProgress 表达过程。先确定信息层级，再选择视觉元素。文档页和工作界面无需复用主页上的装饰轨道。

## 来源

设计方向参考 [Augma 官方设备介绍](https://sao-movie.net/sp/story/augma.html)。这是独立的界面实验，与作品版权方没有关联。


---

Source: https://augma.yunyoujun.cn/markdown/guide/ar.md

# AR 设备模拟器

<a href="/ar/" data-no-router>打开设备模拟器</a>。无需佩戴设备，也无需开启摄像头，即可体验 Augma 的空间图层和应用操作。

## 在模拟视界中探索

视界延续 [Augma 原站](https://augma.elpsy.cn/)：默认仅显示灰色背景、顶部时钟与白色横线、底部九个圆形图标。点击应用展开悬浮窗口，再次点击或按 Escape 关闭。开启摄像头后，现实画面成为背景。

底部依次为镜像、天气、HUD 显示、声音、空间、摄像头、导航、GitHub 和组件文档。右上角系统菜单提供全屏、镜头切换、主题、设置、通知与设备控制；左上角麦克风打开可点击的模拟语音指令，不请求麦克风权限。


| 应用 | 可以体验的操作 |
| --- | --- |
| 天气 | 切换城市并查看示例温度，非实时天气 |
| 空间 | 切换空中庭院 / 城市漫游，扫描或取消扫描，固定 / 释放锚点，点击场景中的地点 |
| 导航 | 选择目的地、切换彩色路线、开始模拟导航，逐步推进直到抵达，或结束导航 |
| 声音 | 播放本地合成和弦、暂停、切换曲目、调整进度与音量 |
| 通知 | 查看本次体验中的操作记录，打开即标记已读，可清空记录 |
| 设置 | 面板不透明度、深色视界、专注模式、镜像、景深动画、弧线视界，以及恢复默认设置 |

在系统菜单的「设备」中，可以待机、唤醒、断开和重新连接。待机或断开会停止扫描、导航、声音、摄像头与空间 AR。底部眼睛图标可以暂时收起应用和空间图层，再次点击即可恢复。

地图、地点、距离和扫描结果均为模拟数据，不代表定位、真实环境识别或实时交通。界面参考 Augma 的现实叠加图层、圆形应用控件与悬浮路线，以可交互 SVG 实现。

显示设置与音量保存在当前浏览器；通知与场景进度仅存在于本次体验中。播放声音后切换浏览器标签页会自动暂停，不会自动恢复。

## 可选视界效果

右上角「系统菜单 → 设置 → 视界效果」提供两个独立开关，默认关闭并自动保存：

- **景深动画**：鼠标移动时，空间图层和浮窗产生轻微视差与透视；浮窗展开时渐显并对焦，地图背景与摄像头背景轻微虚化。触屏保留入场动画，不跟随手指移动，便于滚动和点击。
- **弧线视界**：上下白线变为浅弧形，底部九个圆形图标沿弧线排列。可单独开启，不依赖景深动画。

系统开启「减少动态效果」时暂停景深动画，但保留弧线外观。隐藏 HUD、设备待机、进入空间 AR 或切到后台也会暂停景深。恢复默认设置会关闭两个效果。

## 接入摄像头

打开底部「摄像头」应用，点击「开启摄像头」后，浏览器才会请求权限。摄像头只在当前页面显示，画面不会上传。可切换镜头，在设置中开启镜像，或保存一张不含 HUD 的摄像头快照。等待权限时可以取消；关闭摄像头、设备待机或离开页面时释放视频轨道。

摄像头需要 HTTPS（localhost 开发例外）和支持 MediaDevices 的浏览器。权限拒绝、设备不可用时仍可体验模拟界面。

## 空间 AR

支持 `immersive-ar` 的浏览器会出现「准备空间 AR」按钮。点击后才加载 Babylon 与 XR 代码；准备完成后再次点击「进入空间 AR」，由这次用户操作启动会话。可返回摄像头模式。

普通桌面浏览器通常只能使用模拟或摄像头模式。空间 AR 的设备支持、环境参考空间和权限以浏览器实际能力为准；自动化测试不能替代实机验证。

## Vue 示例结构

模拟器使用 Vue 3.5 的 `<script setup lang="ts">`、响应式 Props 解构、类型化事件、`defineModel` 和 `useTemplateRef`。入口仅组合设备功能，各应用通过 Props / Events 接收状态和发出操作。

- `SystemBar`、`DeviceDock` 和 `DeviceWindow` 管理系统栏、应用入口与浮窗；没有应用打开时保留空视界。
- `useSimulator` 管理连接、场景、扫描、导航与通知。
- `useDisplaySettings` 管理显示偏好和本地保存，并校验读取的设置。
- `useSoundscape`、`useCamera`、`useXr` 管理浏览器资源，退出时清理。
- 设备应用复用公开的 Augma 组件；业务状态、场景数据和 Babylon 留在演示工程中。


---

Source: https://augma.yunyoujun.cn/markdown/guide/index.md

# 快速开始

Augma 将《刀剑神域：序列之争》中 AR 界面的轻盈感转化为可复用的 Web 组件。使用独立的设计基础，或直接开始构建 Vue 界面。

## Vue 组件

需要 Vue 3.5 或更新版本。

```sh
pnpm add augma
```

在应用入口导入样式：

```ts
import 'augma/style.css'
```

在组件中具名导入：

```vue
<script setup lang="ts">
import { AgmButton, AgmPanel } from 'augma'
</script>

<template>
  <AgmPanel title="连接设备">
    <AgmButton>开始连接</AgmButton>
  </AgmPanel>
</template>
```

不需要全局注册，也不需要配置 UnoCSS 或 Tailwind。组件包包含 TypeScript 声明。Vue 组件负责行为，Reka UI 为复杂交互提供键盘和焦点支持。

## 只使用样式

```sh
pnpm add @augma/core
```

```ts
// 只引入语义变量，不改变全局元素样式。
import '@augma/core/tokens.css'
// 或者使用包含组件样式的完整入口。
import '@augma/core/style.css'
```

```html
<button class="agm-button agm-button--primary" type="button">连接设备</button>
```

CSS 包没有 Vue 运行时依赖。复杂组件的交互、语义、键盘和焦点管理需要原生元素或相应的行为组件。

## 可编辑源码

已初始化 shadcn-vue 的 Vue 项目可以从 [Registry](/ai/#组件-registry) 复制核心组件。复制后的代码由你的项目维护，样式继续引用 `@augma/core/style.css`。

## 主题

默认提供浅色主题。在根元素添加 `class="dark"` 或 `data-agm-theme="dark"` 可启用深色主题。弹层会挂载到 body，因此主题应设置在 `html` 或 `body`，不能只设置在局部容器上。

## 从 0.1 迁移

0.2 重构了公共 API：使用 `AgmButton` 等具名导入，样式入口为 `augma/style.css`。旧的 `app.use(augma)`、内部 workspace 导入和 UnoCSS preset 不再作为公开接口。

旧 Card 的布局需求可使用 Panel；Clock 和应用菜单属于组合示例。摄像头与 WebXR 留在 `/ar/` 演示应用中，组件安装不会加载这些依赖。


---

Source: https://augma.yunyoujun.cn/markdown/guide/migration.md

# 从 0.1 迁移

0.2 是一次允许不兼容调整的重构。升级前先检查项目对旧组件、内部路径和样式 preset 的依赖。

| 旧用法 / 功能 | 0.2 用法 |
| --- | --- |
| `app.use(augma)` | `import { AgmButton } from 'augma'` 等具名导入 |
| 旧 SCSS / UnoCSS preset | `import 'augma/style.css'` |
| workspace 内部组件路径 | `augma` 的公开出口，或 Registry 复制到自己的项目 |
| Card | AgmPanel，按内容组合插槽 |
| Clock / Menu / BottomMenu | 由基础组件组合；[查看展示](/showcase/) |
| Button / Input / Select 等旧 Props | 查阅新的组件 API，不能直接保证兼容 |
| 摄像头与 Babylon 混入组件包 | 独立的 [AR 演示](/guide/ar) |
| TensorFlow / 目标检测实验 | 首版移除，没有作为稳定能力发布 |

框架无关样式使用 `@augma/core`。Vue 包需要 Vue 3.5+，复杂行为由 Reka UI 提供。首版没有提供全局组件注册插件或 React 包。

文档和展示统一于 `augma.yunyoujun.cn`，并在 `augma.yyj.moe` 的 Cloudflare Pages 部署提供相同内容。旧域名的迁移状态取决于实际托管切换，不能通过升级 npm 包自动完成。


---

Source: https://augma.yunyoujun.cn/markdown/index.md




---

Source: https://augma.yunyoujun.cn/markdown/showcase/index.md