nanakura/moeka-project
1
0
Fork 0
Code Issues Pull Requests 1 Actions 2 Packages Projects Releases Wiki Activity

chore(docs): rewrite desktop quick start & make docs up to date (#1791)

Browse Source
This commit is contained in:
jim139129
2026-05-19 19:29:14 +08:00
committed by GitHub
parent 04eb616936
commit 8555077836
4 changed files with 216 additions and 400 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/content/en/docs/manual/tamagotchi/index.md
+52 -125
View File
@@ -1,24 +1,22 @@
---
title: Guide to Desktop version
description: How to use Tamagotchi version of Project AIRI
title: Desktop Quick Start
description: How to start using Project AIRI on desktop
---
## I want to chat, now!
## Start Chatting
No problem, follow me:
After installing and launching AIRI, the quickest way to start a conversation is to complete the onboarding flow:
- Complete the onboarding process
1. Choose your desired LLM / AI provider (in the demo video, I chose OpenRouter)
2. Input API Key to interact with LLM / AI (this serve as the brain / soul of your character)
3. Select the desired Chat model (in the demo video, I chose `DeepSeek V3 0324`)
4. Disable **Fade on Hover** mode from system tray
5. Hover to the model UI, click the chat bubble icon, this will bring up the Chat window
6. Input and Chat!
1. Select your language if AIRI asks for it.
2. Choose **setup with your provider**, or sign in if you already use an AIRI account.
3. Pick a chat provider, such as OpenRouter, OpenAI Compatible API, DeepSeek, Ollama, Qwen, Gemini, or Claude.
4. Enter the required API key or local endpoint information.
5. Choose a chat model, then save and continue.
6. On the main character window, click the bottom-right **Expand** button in the Controls Island.
7. Click **Open Chat**, type a message, and send it.
::: tip Using Ollama locally?
You will need to set the `OLLAMA_ORIGINS=*` system environment variable and restart the Ollama
application after finishes.
Set `OLLAMA_ORIGINS=*` as a system environment variable, then restart Ollama before selecting it in AIRI.
:::
<br />
@@ -27,62 +25,41 @@ application after finishes.
<source src="/assets/tutorial-basic-setup-providers.mp4" type="video/mp4">
</video>
<br />
## What Is On Screen
Well yeah, this is too quick, we bet you haven't figured out what is **Fade on Hover**,
and how to customize everything, right?
The desktop version, also called Stage Tamagotchi, usually has these surfaces:
::: warning We are still in early stage of developing it, many things weren't fully available yet
Some of the features are not really ready, but we are working hard to make them true right now:
- **Main character window**: the always-on-desktop Live2D / VRM stage.
- **Controls Island**: the small button group at the bottom-right of the character window.
- **Chat window**: the conversation window opened from Controls Island.
- **Settings window**: provider, character, model, module, data, connection, and system settings.
- **System tray menu**: size, alignment, settings, caption, widgets, and quit actions.
- Transcriptions
- Local Speech Synthesis (GPT-SoVITS, IndexTTS, etc.)
- Singing
- Configuring Discord from UI (but it works already and requires coding skills to set it up)
- Configuring Minecraft agent from UI (but it works already and requires coding skills to set it up)
:::
If the character window is hidden, you can bring it back by clicking the AIRI tray icon or choosing **Show** from the tray menu.
But first...
## Controls Island
::: tip Thank you!
The Controls Island is the most convenient place to operate the desktop app during everyday use.
Thank you for downloading and trying it!
:::
- Click **Expand** to reveal more actions.
- Click **Open Chat** to open the chat window.
- Click **Open Settings** to configure providers, models, modules, characters, and system settings.
- Click **Switch Profile** to change the active character card.
- Click **Refresh** when the stage needs to reload.
- Click the light/dark icon to switch theme.
- Click the pin icon to toggle always-on-top.
- Click the eye icon to toggle **Auto hide** / **Always show**.
- Use the microphone button to open hearing controls.
- Drag the move button to reposition the character window.
After downloaded, start AIRI from anywhere. You will see the user interface consists of two parts:
## Auto Hide
- Onboarding / Wizard setup guide
- Model (capable of showing Live2D & VRM models)
The eye button controls whether AIRI should stay fully interactive or gently reduce visual and click interference while you work.
![](/assets/screenshot-ui.avif)
- **Always show** keeps the character visible and clickable.
- **Auto hide** fades the character and UI when your cursor is nearby, then lets clicks pass through to the app underneath.
We have other options/commands in the system tray, including:
- Show / Hide
- Open Settings
- Auto positioning windows
- etc.
Let's get this started one by one by explaining basic concepts and features.
## Window control
We will go through the following ones:
- How to interact with the model window?
- How to move the model window?
- How to resize it?
### Fade on Hover
::: info TL;DR | Cheatsheet
To toggle this feature (be able to interact with model), use <kbd aria-label="Shift" data-keyboard-key="shift" inline-block>Shift</kbd> + <kbd aria-label="Alt" data-macos-keyboard-key="option" inline-block>Alt</kbd> + <kbd aria-label="I" inline-block>I</kbd> shortcut.
You can customize the key mapping in [Settings] -> [General] -> [Shortcuts]
:::
You will discover that when hovering to the model, the Live2D model fade out / disappears
and you cannot interact with it with cursor.
The first time you enable Auto hide, AIRI shows a short notice explaining the behavior. If AIRI becomes hard to click, move the cursor near the Controls Island and click the eye button again.
<div rounded-lg overflow-hidden>
<video autoplay loop muted class="scale-180 translate-x--30 translate-y--2 lg:scale-150 lg:translate-x--40">
@@ -90,53 +67,9 @@ and you cannot interact with it with cursor.
</video>
</div>
This is because by default, the **Fade on Hover** feature is enabled: which means,
whenever cursor hovers on top of the model window, it will fade out and your clicks passed
through the window entirely.
## Move And Resize
This is a quite powerful feature, you will find it more useful when use it more and more
while having the companion live by your side. Here are two scenarios we came up with:
#### Browsing CrunchyRoll
<video autoplay loop muted>
<source src="/assets/tutorial-demo-browsing-crunchy-roll.mp4" type="video/mp4">
</video>
#### Browsing Steam
<video autoplay loop muted>
<source src="/assets/tutorial-demo-browsing-steam.mp4" type="video/mp4">
</video>
it's easy to disable this feature.
There are two ways to disable this feature:
- System tray
- Shortcut
You can toggle this feature through:
1. Right click system tray icon
2. Click **Window mode**
3. Click **Fade on hover**
<div rounded-lg overflow-hidden>
<video autoplay loop muted class="scale-200 translate-x--35 translate-y--23 lg:scale-180 lg:translate-x--60 lg:translate-y--40">
<source src="/assets/tutorial-basic-disable-fade-on-hover.mp4" type="video/mp4">
</video>
</div>
### Move the window
::: info TL;DR | Cheatsheet
To toggle this feature (be able to interact with model), use <kbd aria-label="Shift" data-keyboard-key="shift" inline-block>Shift</kbd> + <kbd aria-label="Alt" data-macos-keyboard-key="option" inline-block>Alt</kbd> + <kbd aria-label="N" inline-block>N</kbd> shortcut.
You can customize the key mapping in [Settings] -> [General] -> [Shortcuts]
:::
<br />
To move the character window, drag the move button at the bottom-right of the Controls Island.
<div rounded-lg overflow-hidden>
<video autoplay loop muted class="scale-225 translate-x--45 translate-y--5 lg:scale-200 lg:translate-x--80 lg:translate-y--5">
@@ -144,15 +77,13 @@ You can customize the key mapping in [Settings] -> [General] -> [Shortcuts]
</video>
</div>
### Resize the window
On Windows, you can resize the character window by dragging the window edges or corners. The tray menu also provides a few quick presets:
::: info TL;DR | Cheatsheet
To toggle this feature (be able to interact with model), use <kbd aria-label="Shift" data-keyboard-key="shift" inline-block>Shift</kbd> + <kbd aria-label="Alt" data-macos-keyboard-key="option" inline-block>Alt</kbd> + <kbd aria-label="A" inline-block>A</kbd> shortcut.
1. Right-click the AIRI tray icon.
2. Open **Adjust sizes**.
3. Choose **Recommended**, **Full Height**, **Half Height**, or **Full Screen**.
You can customize the key mapping in [Settings] -> [General] -> [Shortcuts]
:::
<br />
You can use **Align to** in the same tray menu to place the window at the center or a screen corner.
<div rounded-lg overflow-hidden>
<video autoplay loop muted class="scale-160 translate-x--20 lg:scale-150 lg:translate-x--40 lg:translate-y-10">
@@ -160,18 +91,14 @@ You can customize the key mapping in [Settings] -> [General] -> [Shortcuts]
</video>
</div>
## Chat
## Settings Worth Checking
There is no direct option/command to summon the Chat window from system tray
right now, but we might add this in the future, currently, in order to open the
Chat window, you will need to toggle off the **Fade on Hover** mode.
These pages are useful to check after the first chat works:
::: info TL;DR | Cheatsheet
Shortcut for Fade on Hover is: <kbd aria-label="Shift" data-keyboard-key="shift" inline-block>Shift</kbd> + <kbd aria-label="Alt" data-macos-keyboard-key="option" inline-block>Alt</kbd> + <kbd aria-label="I" inline-block>I</kbd>.
:::
- **Service Sources**: add or edit Chat, Speech, Transcription, and Artistry providers.
- **Body Modules**: choose which providers AIRI uses for consciousness, voice, hearing, vision, memory, Discord, Minecraft, Factorio, MCP, and other modules.
- **Character Model**: switch between Live2D and VRM models, or import your own model.
- **AIRI Character Card**: change the active character or create a new one.
- **System**: set language, theme, analytics preference, and desktop-specific options.
<br />
<video autoplay loop muted>
<source src="/assets/tutorial-basic-open-chat.mp4" type="video/mp4">
</video>
Some modules are still experimental and may require local source setup or external services. For a more detailed Windows-focused walkthrough, see the [full desktop manual](./setup-and-use/).
docs/content/ja/docs/manual/tamagotchi/index.md
+53 -118
View File
@@ -1,23 +1,22 @@
---
title: デスクトップ版のガイド
description: Project AIRI のたまごっちバージョンの使い方
title: デスクトップ版クイックスタート
description: Project AIRI デスクトップ版の使い方
---
## 今すぐチャットしたい！
## まずチャットする
問題ありません、私についてきてください：
AIRI をインストールして起動したら、まずはオンボーディングを進めると会話を始めやすくなります。
- オンボーディングプロセスを完了する
1. AIRI に求められた場合は言語を選択します。
2. **プロバイダーでセットアップ** を選びます。既に AIRI アカウントを使っている場合は、**サインイン** を選んでもかまいません。
3. OpenRouter、OpenAI Compatible API、DeepSeek、Ollama、Qwen、Gemini、Claude などのチャットプロバイダーを選びます。
4. API キー、またはローカルエンドポイントなど必要な情報を入力します。
5. チャットモデルを選び、保存して続行します。
6. メインのキャラクターウィンドウ右下にあるコントロールアイランドで **展開** をクリックします。
7. **チャットを開く** をクリックし、メッセージを入力して送信します。
1. 希望の LLM / AI プロバイダーを選択します（デモビデオでは OpenRouter を選択しました）
2. LLM / AI と対話するための API キーを入力します（これはキャラクターの脳/魂として機能します）
3. 希望のチャットモデルを選択します（デモビデオでは `DeepSeek V3 0324` を選択しました）
4. システムトレイから **Fade on Hover**（ホバー時にフェード）モードを無効にします
5. モデル UI にカーソルを合わせ、吹き出しアイコンをクリックすると、チャットウィンドウが表示されます
6. 入力してチャットしましょう！
::: tip ローカルで Ollama を使用していますか？
完了後、`OLLAMA_ORIGINS=*` システム環境変数を設定し、Ollama アプリケーションを再起動する必要があります。
::: tip ローカルの Ollama を使う場合
システム環境変数 `OLLAMA_ORIGINS=*` を設定し、Ollama を再起動してから AIRI で選択してください。
:::
<br />
@@ -26,60 +25,41 @@ description: Project AIRI のたまごっちバージョンの使い方
<source src="/assets/tutorial-basic-setup-providers.mp4" type="video/mp4">
</video>
<br />
## 画面にあるもの
ええと、これは早すぎましたね。**Fade on Hover** とは何なのか、どうやってすべてをカスタマイズするのか、まだわかりませんよね？
デスクトップ版は Stage Tamagotchi とも呼ばれ、主に次の画面で構成されています。
::: warning 私たちはまだ開発の初期段階にあり、多くの機能はまだ完全には利用できません
いくつかの機能はまだ準備ができていませんが、現在それらを実現するために懸命に取り組んでいます：
- **メインキャラクターウィンドウ**：デスクトップ上に常駐する Live2D / VRM ステージです。
- **コントロールアイランド**：キャラクターウィンドウ右下の小さなボタングループです。
- **チャットウィンドウ**：コントロールアイランドから開く会話用ウィンドウです。
- **設定ウィンドウ**：プロバイダー、キャラクター、モデル、モジュール、データ、接続、システム設定を変更できます。
- **システムトレイメニュー**：サイズ、配置、設定、キャプション、ウィジェット、終了などを操作できます。
- 文字起こし
- ローカル音声合成 (GPT-SoVITS, IndexTTS など)
- 歌唱
- UI からの Discord の設定（ただし、すでに機能しており、設定にはコーディングスキルが必要です）
- UI からの Minecraft エージェントの設定（ただし、すでに機能しており、設定にはコーディングスキルが必要です）
:::
キャラクターウィンドウが隠れている場合は、AIRI のトレイアイコンをクリックするか、トレイメニューの **表示** から戻せます。
しかし、その前に...
## コントロールアイランド
::: tip ありがとうございます！
コントロールアイランドは、デスクトップ版を日常的に操作するための便利な入口です。
ダウンロードして試していただきありがとうございます！
:::
- **展開** をクリックすると、追加の操作が表示されます。
- **チャットを開く** でチャットウィンドウを開きます。
- **設定を開く** でプロバイダー、モデル、モジュール、キャラクター、システム設定を開きます。
- **プロファイルを切り替え** でアクティブなキャラクターカードを変更します。
- 必要に応じて **再読み込み** でステージを再読み込みします。
- ライト / ダークのアイコンでテーマを切り替えます。
- ピンのアイコンで常に手前に表示するかを切り替えます。
- 目のアイコンで **自動的に隠す** / **常に表示** を切り替えます。
- マイクボタンで聴覚コントロールを開きます。
- 移動ボタンをドラッグして、キャラクターウィンドウを移動します。
ダウンロード後、どこからでも AIRI を起動できます。ユーザーインターフェースは2つの部分で構成されていることがわかります：
## 自動的に隠す
- オンボーディング / ウィザードセットアップガイド
- モデル (Live2D および VRM モデルを表示可能)
目のアイコンは、AIRI をしっかり操作できる状態にするか、作業中の視界やクリックへの干渉をやわらげるかを切り替えます。
![](/assets/screenshot-ui.avif)
- **常に表示** は、キャラクターを表示したままクリックできる状態にします。
- **自動的に隠す** は、カーソルが近づいたときにキャラクターと UI をフェードさせ、背後のアプリへクリックを通しやすくします。
システムトレイには、次のような他のオプション/コマンドがあります：
- 表示 / 非表示
- 設定を開く
- ウィンドウの自動配置
- など
基本的な概念と機能を説明しながら、一つずつ始めていきましょう。
## ウィンドウ操作
以下について説明します：
- モデルウィンドウとの対話方法は？
- モデルウィンドウの移動方法は？
- サイズ変更の方法は？
### Fade on Hover（ホバー時にフェード）
::: info TL;DR | チートシート
この機能を切り替える（モデルと対話できるようにする）には、<kbd aria-label="Shift" data-keyboard-key="shift" inline-block>Shift</kbd> + <kbd aria-label="Alt" data-macos-keyboard-key="option" inline-block>Alt</kbd> + <kbd aria-label="I" inline-block>I</kbd> ショートカットを使用します。
キーのマッピングは [設定] -> [一般] -> [ショートカット] でカスタマイズできます。
:::
モデルにカーソルを合わせると、Live2D モデルがフェードアウト/消え、カーソルで対話できないことに気付くでしょう。
初めて自動的に隠すを有効にすると、AIRI は挙動を説明する短い案内を表示します。AIRI をクリックしづらくなった場合は、カーソルをコントロールアイランド付近に移動し、もう一度目のアイコンをクリックすると戻せます。
<div rounded-lg overflow-hidden>
<video autoplay loop muted class="scale-180 translate-x--30 translate-y--2 lg:scale-150 lg:translate-x--40">
@@ -87,50 +67,9 @@ description: Project AIRI のたまごっちバージョンの使い方
</video>
</div>
これは、デフォルトで **Fade on Hover** 機能が有効になっているためです。つまり、カーソルがモデルウィンドウの上に重なると、ウィンドウがフェードアウトし、クリックがウィンドウを完全に通過します。
## 移動とサイズ変更
これは非常に強力な機能です。コンパニオンがあなたのそばに住んでいる間、それを使えば使うほど便利だと感じるでしょう。ここに私たちが考えた2つのシナリオがあります：
#### CrunchyRoll の閲覧
<video autoplay loop muted>
<source src="/assets/tutorial-demo-browsing-crunchy-roll.mp4" type="video/mp4">
</video>
#### Steam の閲覧
<video autoplay loop muted>
<source src="/assets/tutorial-demo-browsing-steam.mp4" type="video/mp4">
</video>
この機能を無効にするのは簡単です。
この機能を無効にするには2つの方法があります：
- システムトレイ
- ショートカット
以下からこの機能を切り替えることができます：
1. システムトレイアイコンを右クリック
2. **Window mode**（ウィンドウモード）をクリック
3. **Fade on hover**（ホバー時にフェード）をクリック
<div rounded-lg overflow-hidden>
<video autoplay loop muted class="scale-200 translate-x--35 translate-y--23 lg:scale-180 lg:translate-x--60 lg:translate-y--40">
<source src="/assets/tutorial-basic-disable-fade-on-hover.mp4" type="video/mp4">
</video>
</div>
### ウィンドウを移動
::: info TL;DR | チートシート
この機能を切り替える（モデルと対話できるようにする）には、<kbd aria-label="Shift" data-keyboard-key="shift" inline-block>Shift</kbd> + <kbd aria-label="Alt" data-macos-keyboard-key="option" inline-block>Alt</kbd> + <kbd aria-label="N" inline-block>N</kbd> ショートカットを使用します。
キーのマッピングは [設定] -> [一般] -> [ショートカット] でカスタマイズできます。
:::
<br />
キャラクターウィンドウを移動するには、コントロールアイランド右下の移動ボタンをドラッグします。
<div rounded-lg overflow-hidden>
<video autoplay loop muted class="scale-225 translate-x--45 translate-y--5 lg:scale-200 lg:translate-x--80 lg:translate-y--5">
@@ -138,15 +77,13 @@ description: Project AIRI のたまごっちバージョンの使い方
</video>
</div>
### ウィンドウのサイズ変更
Windows では、ウィンドウの端や角をドラッグしてサイズを変更できます。トレイメニューにも便利なプリセットがあります。
::: info TL;DR | チートシート
この機能を切り替える（モデルと対話できるようにする）には、<kbd aria-label="Shift" data-keyboard-key="shift" inline-block>Shift</kbd> + <kbd aria-label="Alt" data-macos-keyboard-key="option" inline-block>Alt</kbd> + <kbd aria-label="A" inline-block>A</kbd> ショートカットを使用します。
1. AIRI のトレイアイコンを右クリックします。
2. **サイズ調節** を開きます。
3. **おすすめ**、**高さ最大**、**高さ半分**、**フルスクリーン** から選びます。
キーのマッピングは [設定] -> [一般] -> [ショートカット] でカスタマイズできます。
:::
<br />
同じトレイメニューの **揃える** を使うと、中央や画面の角にウィンドウを配置できます。
<div rounded-lg overflow-hidden>
<video autoplay loop muted class="scale-160 translate-x--20 lg:scale-150 lg:translate-x--40 lg:translate-y-10">
@@ -154,16 +91,14 @@ description: Project AIRI のたまごっちバージョンの使い方
</video>
</div>
## チャット
## 確認しておくと便利な設定
現在、システムトレイからチャットウィンドウを呼び出す直接のオプション/コマンドはありませんが、将来的に追加する可能性があります。現在、チャットウィンドウを開くには、**Fade on Hover** モードをオフに切り替える必要があります。
最初のチャットができたら、次のページも確認しておくと便利です。
::: info TL;DR | チートシート
Fade on Hover のショートカットは：<kbd aria-label="Shift" data-keyboard-key="shift" inline-block>Shift</kbd> + <kbd aria-label="Alt" data-macos-keyboard-key="option" inline-block>Alt</kbd> + <kbd aria-label="I" inline-block>I</kbd> です。
:::
- **サービスソース**：Chat、Speech、Transcription、Artistry のプロバイダーを追加・編集します。
- **ボディモジュール**：意識、発声、聴覚、視覚、記憶、Discord、Minecraft、Factorio、MCP などで使うプロバイダーを選びます。
- **キャラクターモデル**：Live2D / VRM モデルを切り替えたり、自分のモデルをインポートしたりできます。
- **AIRI キャラクターカード**：アクティブなキャラクターを変更、または新規作成します。
- **システム**：言語、テーマ、分析データの設定、デスクトップ固有の設定を変更します。
<br />
<video autoplay loop muted>
<source src="/assets/tutorial-basic-open-chat.mp4" type="video/mp4">
</video>
一部のモジュールはまだ実験的で、ローカルのソース設定や外部サービスが必要になる場合があります。
docs/content/zh-Hans/docs/manual/tamagotchi/index.md
+52 -122
View File
@@ -1,24 +1,22 @@
---
title: 桌面版上手指南
description: 如何使用桌面版的 Project AIRI
title: 桌面版快速开始
description: 如何开始使用 Project AIRI 桌面版
---
## 我现在就想聊天！
## 先开始聊天
没问题，跟着我来：
安装并启动 AIRI 后，可以先跟随首次引导完成基础配置：
- 完成入门引导教程
1. 选择您想要的 LLM / AI 提供商（在演示视频中，我选择了 OpenRouter）
2. 输入与 LLM / AI 进行交互需要的 API 密钥（会作为角色的「大脑」或「灵魂」）
3. 挑选一个合适的聊天（Chat）模型（在演示视频中，我选择了 `DeepSeek V3 0324`）
4. 从系统托盘中禁用 **悬停时淡化** 模式
5. 将鼠标悬停在「角色模型」的界面上，点击聊天气泡图标，这将调出聊天窗口
6. 现在输入点什么就可以开聊了！
1. 如果 AIRI 要求选择语言，先选择你想使用的语言。
2. 选择 **配置您自己的 AI 服务来源**；如果你已经在使用 AIRI 账号，也可以选择登录。
3. 选择一个聊天服务来源，例如 OpenRouter、OpenAI 兼容 API、DeepSeek、Ollama、Qwen、Gemini 或 Claude。
4. 填入 API Key，或本地服务地址等必要信息。
5. 选择聊天模型，然后保存并继续。
6. 回到主角色窗口后，点击右下角控制岛里的 **展开** 按钮。
7. 点击 **打开聊天**，输入消息并发送。
::: tip 在本地使用 Ollama？
您需要设置系统环境变量 `OLLAMA_ORIGINS=*`，
并在设置完成后重启 Ollama 应用程序。
你需要设置系统环境变量 `OLLAMA_ORIGINS=*`，然后重启 Ollama，再从 AIRI 中选择它。
:::
<br />
@@ -27,62 +25,41 @@ description: 如何使用桌面版的 Project AIRI
<source src="/assets/tutorial-basic-setup-providers.mp4" type="video/mp4">
</video>
<br />
## 你会看到什么
嗯，确实，这节奏太快了。我想... 你应该还没搞明白「**悬停时淡化**」到底是什么功能，
以及如何自定义所有设置，对吧？
桌面版也叫 Stage Tamagotchi，通常由这些界面组成：
::: tip 我们仍处于开发的早期阶段，许多功能尚未完全可用。
其中一些功能尚未真正就绪，但我们正努力让它们尽快实现：
- **主角色窗口**：常驻桌面的 Live2D / VRM 舞台。
- **控制岛**：主角色窗口右下角的小按钮组。
- **聊天窗口**：从控制岛打开的对话窗口。
- **设置窗口**：配置服务来源、角色、模型、机体模块、数据、连接和系统选项。
- **系统托盘菜单**：调整大小、对齐位置、打开设置、字幕、小部件和退出。
- 文本转语音（语音控制）功能
- 本地语音合成（例如 GPT-SoVITS、IndexTTS 等）
- AI 唱歌
- 从用户界面配置 Discord（但已经可以用了！只是需要掌握一些写代码的能力才能配置）
- 从用户界面配置 Minecraft Agent 智能体（但已经可以用了！只是需要掌握一些写代码的能力才能配置）
:::
如果主角色窗口被隐藏了，可以点击 AIRI 的托盘图标，或在托盘菜单里选择 **显示** 把它带回来。
但首先。。。
## 控制岛
::: tip 谢谢你！
控制岛是日常操作桌面版时最方便的入口。
感谢你下载并试用它！
:::
- 点击 **展开** 显示更多操作。
- 点击 **打开聊天** 打开聊天窗口。
- 点击 **打开设置** 配置服务来源、模型、机体模块、角色和系统设置。
- 点击 **切换角色** 更换当前角色卡。
- 需要时，可以点击 **刷新** 重新加载舞台。
- 点击亮色 / 暗色图标切换主题。
- 点击图钉图标切换窗口置顶。
- 点击眼睛图标切换 **悬停时隐藏** / **总是显示**。
- 点击麦克风按钮打开听力控制。
- 拖动移动按钮来移动主角色窗口。
下载完成后，你可以从任何位置启动 AIRI。你将看到用户界面由两部分组成：
## 悬停时隐藏
- 新手引导 / 设置向导
- 模型（可显示 Live2D 和 VRM 模型）
眼睛图标用于切换 AIRI 的显示方式：保持可点击，或在你工作时尽量减少遮挡和点击干扰。
![](/assets/screenshot-ui.avif)
- **总是显示** 会让角色保持可见、可点击。
- **悬停时隐藏** 会在光标靠近时淡出角色和界面，让点击更容易落到下面的应用上。
我们还在系统托盘中提供了其他选项/命令，包括：
- 显示 / 隐藏
- 打开设置
- 自动定位窗口
- 等等。
让我们从逐一讲解基本概念和功能开始吧。
## 窗口控制
我们将介绍以下几个内容：
- 如何与模型窗口互动？
- 如何移动模型窗口？
- 如何调整其大小？
### 悬停时淡化
::: info 快捷键速记
要切换此功能（即可与模型进行交互），请使用快捷键<kbd aria-label="Shift" data-keyboard-key="shift" inline-block>Shift</kbd> + <kbd aria-label="Alt" data-macos-keyboard-key="option" inline-block>Alt</kbd> + <kbd aria-label="I" inline-block>I</kbd> 。
你可以在以下位置自定义按键映射：[设置]-> [外观] -> [通用] -> [快捷键]
:::
你会发现，当鼠标悬停在模型上时，Live2D/VRM 模型会逐渐淡出或消失，
此时你无法通过光标与它进行交互。
首次开启悬停时隐藏时，AIRI 会弹出一个简短说明。若开启后不方便点击 AIRI，把光标移到控制岛附近，再点一次眼睛图标即可切回。
<div rounded-lg overflow-hidden>
<video autoplay loop muted class="scale-180 translate-x--30 translate-y--2 lg:scale-150 lg:translate-x--40">
@@ -90,51 +67,9 @@ description: 如何使用桌面版的 Project AIRI
</video>
</div>
这是因为默认情况下，**悬停时淡化** 功能是启用的：也就是说，
每当光标悬停在模型窗口的上方时，模型会淡出，并且你的点击会直接穿透该窗口。
## 移动和调整大小
这是一个非常强大的功能，在不断让「伙伴」一直陪伴在身边的过程中，你也可能会越来越发现它的有用之处。比如下面这两种我们想到的两个使用场景：
#### 浏览 CrunchyRoll
<video autoplay loop muted>
<source src="/assets/tutorial-demo-browsing-crunchy-roll.mp4" type="video/mp4">
</video>
#### 浏览 Steam
<video autoplay loop muted>
<source src="/assets/tutorial-demo-browsing-steam.mp4" type="video/mp4">
</video>
当然，想要禁用这一功能其实很简单。
有两种方式可以禁用它：
- 系统托盘
- 快捷键
你可以通过以下步骤来切换该功能：
1. 右键单击系统托盘图标；
2. 点击 **窗口模式**
3. 点击 **悬停时淡化**
<div rounded-lg overflow-hidden>
<video autoplay loop muted class="scale-200 translate-x--35 translate-y--23 lg:scale-180 lg:translate-x--60 lg:translate-y--40">
<source src="/assets/tutorial-basic-disable-fade-on-hover.mp4" type="video/mp4">
</video>
</div>
### 移动窗口
::: info 快捷键速记
要切换此功能（即可与模型进行交互），请使用快捷键 <kbd aria-label="Shift" data-keyboard-key="shift" inline-block>Shift</kbd> + <kbd aria-label="Alt" data-macos-keyboard-key="option" inline-block>Alt</kbd> + <kbd aria-label="N" inline-block>N</kbd>。
你可以在 [设置]-> [外观] -> [通用] -> [快捷键] 中自定义按键映射。
:::
<br />
要移动主角色窗口，拖动控制岛右下角的移动按钮。
<div rounded-lg overflow-hidden>
<video autoplay loop muted class="scale-225 translate-x--45 translate-y--5 lg:scale-200 lg:translate-x--80 lg:translate-y--5">
@@ -142,15 +77,13 @@ description: 如何使用桌面版的 Project AIRI
</video>
</div>
### 调整窗口大小
在 Windows 上，你可以拖动窗口边缘或角落来调整大小。托盘菜单里也提供了几个常用尺寸：
::: info 快捷键速记
要切换此功能（即可与模型进行交互），请使用快捷键 <kbd aria-label="Shift" data-keyboard-key="shift" inline-block>Shift</kbd> + <kbd aria-label="Alt" data-macos-keyboard-key="option" inline-block>Alt</kbd> + <kbd aria-label="A" inline-block>A</kbd>。
1. 右键 AIRI 托盘图标。
2. 打开 **调整大小**。
3. 选择 **推荐**、**全高**、**半高** 或 **全屏**。
你可以在 [设置]-> [外观] -> [通用] -> [快捷键] 中自定义按键映射。
:::
<br />
同一个托盘菜单里的 **对齐到** 可以把窗口放到屏幕中央或四角。
<div rounded-lg overflow-hidden>
<video autoplay loop muted class="scale-160 translate-x--20 lg:scale-150 lg:translate-x--40 lg:translate-y-10">
@@ -158,17 +91,14 @@ description: 如何使用桌面版的 Project AIRI
</video>
</div>
## 聊天
## 建议再看看这些设置
目前系统托盘中没有直接打开聊天窗口的选项或命令，但我们未来可能会添加这一功能。
目前，要打开聊天窗口，你需要先关闭 **悬停时淡化** 模式。
完成第一次聊天后，建议再看看这些页面：
::: info 快捷键速记
悬停时淡化（Fade on Hover）的快捷键是：<kbd aria-label="Shift" data-keyboard-key="shift" inline-block>Shift</kbd> + <kbd aria-label="Alt" data-macos-keyboard-key="option" inline-block>Alt</kbd> + <kbd aria-label="I" inline-block>I</kbd>.
:::
- **服务来源**：添加或编辑 Chat、Speech、Transcription、Artistry 服务来源。
- **机体模块**：为意识、发声、听觉、视觉、记忆、Discord、Minecraft、Factorio、MCP 等模块选择服务。
- **角色模型**：切换 Live2D / VRM 模型，或导入自己的模型。
- **AIRI 角色卡**：切换当前角色，或创建一个新的角色卡。
- **系统**：设置语言、主题、数据分析偏好和桌面端专用选项。
<br />
<video autoplay loop muted>
<source src="/assets/tutorial-basic-open-chat.mp4" type="video/mp4">
</video>
部分模块仍处于实验阶段，可能需要本地源码配置或额外的外部服务。更完整的 Windows 使用说明可以参考[桌面版详细说明书](./setup-and-use/)。
docs/content/zh-Hans/docs/overview/index.md
+58 -34
View File
@@ -1,41 +1,55 @@
---
title: 这是什么项目？
description: 了解 Project AIRI 的用户界面
title: Project AIRI 是什么？
description: 了解 Project AIRI 的定位、能力与上手方式
---
### 太长不看
请将我们视为
Project AIRI 是一个开源的 AI VTuber / 数字伙伴项目。你可以把它理解为：
- [Neuro-sama](https://www.youtube.com/@Neurosama) 的开源重建
- [Grok Companion](https://news.ycombinator.com/item?id=44566355) 的开源替代方案
- 一个支持 Live2D，VRM，并且一起玩游戏，或者感知其他应用的 [SillyTavern](https://github.com/SillyTavern/SillyTavern)（酒馆）替代方案
- 受 [Neuro-sama](https://www.youtube.com/@Neurosama) 启发的开源复刻方向；
- [Grok Companion](https://news.ycombinator.com/item?id=44566355) 这类数字陪伴产品的开源替代方案；
- 一个不只聊天，还支持 Live2D、VRM、语音、角色卡、游戏智能体和应用上下文感知的 [SillyTavern](https://github.com/SillyTavern/SillyTavern)（酒馆）延伸。
你是否梦想过拥有一个赛博生命（赛博 waifu），
或者可以陪你玩耍、聊天的数字伙伴？
如果你想要的只是一个聊天机器人，Character.ai、JanitorAI、SillyTavern 已经能覆盖很多场景。AIRI 想推进的是另一件事：让一个虚拟角色真正「住」进你的电脑、浏览器或移动设备里，能说话、能听见、能显示自己的身体，也能逐步接入游戏、直播、Discord、Telegram、MCP 工具和本地模型。
借助现代 LLM 的强大功能，
像 [Character.ai (又名 c.ai)](https://character.ai) 和 [JanitorAI](https://janitorai.com/) 这样的平台，
或者像 [SillyTavern](https://github.com/SillyTavern/SillyTavern) 这样的应用已经可以为基于聊天或视觉 ADV 游戏的体验提供足够完善的解决方案。
换句话说，AIRI 不只是一个聊天界面，而是在尝试把大模型、语音、视觉、角色表现和外部工具连接成一个可扩展的数字生命容器。
> 但是玩游戏呢？或者看看你正在编写什么？
> 一边玩游戏一边聊天、看视频，还能做很多其他事情。
## 可以做什么
或许你已经认识 [Neuro-sama](https://www.youtube.com/@Neurosama) 了，她是目前最好的数字伙伴，可以玩游戏、聊天，还能和你以及（在 VTuber 社区）的参与者互动，有些人也把这种生物称为“数字人”。**可惜的是，它目前尚未开源，直播下线后你就无法与她互动了**。
今天你可以先把 AIRI 当作一个可配置的数字伙伴来使用：
因此 Project AIRI 提供了另一种可能性：
**让你随时随地轻松拥有自己的数字生命、赛博生命。**。
- 通过 OpenAI 兼容接口、OpenRouter、DeepSeek、Ollama、Qwen、Gemini、Claude 等服务为她配置「大脑」；
- 使用角色卡定义名字、性格、说话方式和不同模块使用的模型；
- 在网页端直接开始聊天，也可以在桌面端让她以 Live2D 或 VRM 模型常驻屏幕；
- 配置语音合成、语音识别和说话检测，让交互从文字扩展到语音；
- 在桌面端使用系统托盘、窗口穿透、悬停淡化、移动和缩放等桌宠式交互；
- 通过源码运行或开发中的模块接入 Discord、Telegram、Minecraft、Factorio、MCP Server 等实验能力。
项目仍在快速演进中，稳定版本优先提供聊天、角色、模型显示和基础设置；更深入的游戏智能体、机器人、插件与本地运行能力正在持续开发。
## 为什么是 AIRI
很多 AI 角色项目把重点放在「更像角色地聊天」。AIRI 更关注角色如何进入真实环境：
- **身体**：支持 Live2D 和 VRM，目标是让角色拥有可互动的 2D / 3D 表现；
- **声音**：整合 TTS、STT、VAD 等能力，让角色可以开口、听见你说话，并判断你是否正在说话；
- **上下文**：桌面端和插件系统正在把应用状态、开发环境、游戏状态等上下文接入对话流程；
- **行动能力**：Minecraft、Factorio、Discord、Telegram 等服务侧模块展示了 AIRI 作为智能体参与外部世界的方向；
- **可移植性**：项目从一开始就大量使用 Web 技术，结合 WebGPU、WebAudio、Web Worker、WebAssembly、WebSocket 等能力，让网页、桌面和移动端可以共用很多基础设施。
这也是为什么仓库里同时有 `stage-web`、`stage-tamagotchi`、`stage-pocket`、`stage-ui`、`server-runtime`、`plugin-sdk` 等模块。AIRI 不是单一应用，而是一套围绕虚拟角色体验搭建的 monorepo：前端舞台、桌面运行时、移动端、共享 UI、服务通道、插件协议和智能体服务都在同一个项目里逐步成形。
## 开始使用
我们同时支持网页和客户端。
目前最容易上手的是网页端和桌面端。
<div flex gap-2 w-full justify-center text-xl>
<div w-full flex flex-col items-center gap-2 border="2 solid gray-500/10" rounded-lg px-2 pt-6 pb-4>
<div flex items-center gap-2 text-5xl>
<div i-lucide:app-window />
</div>
<span>网页</span>
<span>网页端</span>
<a href="https://airi.moeru.ai/" target="_blank" decoration-none class="text-primary-900 dark:text-primary-400 text-base not-prose bg-primary-400/10 dark:bg-primary-600/10 block px-4 py-2 rounded-lg active:scale-95 transition-all duration-200 ease-in-out">
打开
</a>
@@ -46,35 +60,37 @@ description: 了解 Project AIRI 的用户界面
/
<div i-lucide:computer />
</div>
<span>客户端</span>
<span>桌面端</span>
<a href="https://github.com/moeru-ai/airi/releases/latest" target="_blank" decoration-none class="text-primary-900 dark:text-primary-400 text-base not-prose bg-primary-400/10 dark:bg-primary-600/10 block px-4 py-2 rounded-lg active:scale-95 transition-all duration-200 ease-in-out">
下载
</a>
</div>
</div>
网页版功能较为基础，适用于在任何设备（包括移动设备）上访问。
**网页端** 适合快速体验。打开浏览器，配置模型提供商和 API Key，就可以开始和 AIRI 对话。它也适合在移动设备上访问，或者用来体验 PWA 与浏览器内能力。
客户端则更适合进行高级操作，例如 VTuber 直播、computer-use 以及访问本地 LLM 模型，此时无需为运行 AIRI 支付大量 token 费用。
**桌面端** 适合长期使用和更完整的桌宠体验。它基于 Electron，可以让 AIRI 以 Live2D / VRM 模型常驻桌面，并提供系统托盘、窗口穿透、悬停淡化、本地模型接入、插件调试和更多实验功能。
**移动端**（`stage-pocket`）正在开发中，基于 Capacitor 复用 Web 舞台能力。现阶段如果你只是想在手机上尝试，优先使用网页端。
<div flex gap-2 w-full flex-col justify-center text-base>
<a href="../overview/guide/tamagotchi/" w-full flex items-center gap-2 border="2 solid gray-500/10" rounded-lg px-4 py-2>
<a href="../manual/tamagotchi/" w-full flex items-center gap-2 border="2 solid gray-500/10" rounded-lg px-4 py-2>
<div w-full flex items-center gap-2>
<div flex items-center gap-2 text-2xl>
<div i-lucide:laptop />
</div>
<span>客户端</span>
<span>桌面端</span>
</div>
<div decoration-none class="text-gray-900 dark:text-gray-200 text-base not-prose rounded-lg active:scale-95 transition-all duration-200 ease-in-out text-nowrap">
如何使用？
</div>
</a>
<a href="../overview/guide/web/" w-full flex items-center gap-2 border="2 solid gray-500/10" rounded-lg px-4 py-2>
<a href="../manual/web/" w-full flex items-center gap-2 border="2 solid gray-500/10" rounded-lg px-4 py-2>
<div w-full flex items-center gap-2>
<div flex items-center gap-2 text-2xl>
<div i-lucide:app-window />
</div>
<span>网页</span>
<span>网页端</span>
</div>
<div class="text-gray-900 dark:text-gray-200 text-base not-prose rounded-lg active:scale-95 transition-all duration-200 ease-in-out text-nowrap">
如何使用？
@@ -82,16 +98,24 @@ description: 了解 Project AIRI 的用户界面
</a>
</div>
<br/>
## 给开发者
AIRI 的主技术栈是 Vue 3、TypeScript、Vite、Pinia、VueUse、UnoCSS 和 Vitest。桌面端使用 Electron，移动端使用 Capacitor；跨进程通信和服务事件使用 `@moeru/eventa`，服务组合大量使用 `injeca`；模型与 LLM Provider 侧主要由 `xsai` 生态驱动。
常见入口如下：
- `apps/stage-web`：网页端，也就是 <https://airi.moeru.ai>；
- `apps/stage-tamagotchi`：桌面端，包含 Electron 主进程、渲染端、桌面窗口、插件宿主和服务通道；
- `apps/stage-pocket`：移动端实验应用；
- `packages/stage-ui`：网页端、桌面端和移动端共享的核心业务组件、设置页、stores 与 composables；
- `packages/stage-ui-three` 与 `packages/stage-ui-live2d`：3D / Live2D 舞台相关能力；
- `packages/server-runtime`、`packages/server-sdk`、`packages/server-shared`：服务通道和外部智能体连接；
- `services/discord-bot`、`services/telegram-bot`、`services/minecraft`：需要源码配置运行的服务侧实验模块。
如果你想贡献代码，可以从[贡献指南](../contributing/)开始；如果你想改进界面，请先阅读[设计指南](../contributing/design-guidelines/resources)。
::: warning 实验性功能与早期开发声明
Project AIRI 目前正处于活跃的早期开发阶段。您在发布的客户端或网页版中体验到的主要为基础的稳定功能。如果您想体验正在开发中的 **实验性功能**（如 Minecraft 智能体、Discord / Telegram 机器人等），**目前暂时只能通过拉取项目源码在本地配置并启动**。
Project AIRI 仍处于活跃开发阶段。发布版会优先保证基础体验；一些高级能力，例如 Minecraft 智能体、Discord / Telegram 机器人、Factorio、插件宿主、MCP、computer-use、更完整的长期记忆等，可能还需要从源码配置、运行或参与开发。
有关环境配置和源码运行的详细步骤，请参阅下方的[贡献指南](../contributing/)。
如果你希望体验这些功能，请参考[贡献指南](../contributing/)和对应服务文档。
:::
## 贡献
有关如何为本项目做出贡献的指南，请参阅 [贡献](../contributing/) 页面。
有关如何设计和改进 Project AIRI 用户界面的参考资料，请参阅 [设计指南](../contributing/design-guidelines/resources) 页面。