diff --git a/docs/content/en/docs/manual/tamagotchi/setup-and-use.md b/docs/content/en/docs/manual/tamagotchi/setup-and-use.md deleted file mode 100644 index b288452a8..000000000 --- a/docs/content/en/docs/manual/tamagotchi/setup-and-use.md +++ /dev/null @@ -1,473 +0,0 @@ -# Project Airi Manual - -Writing time: (UTC+8) April 2, 2026 – evening - -Corresponding version: AIRI-0.9.0-beta.4-windows-x64 - -
- -Expand to see the authors - -Lead writing team: MuGewRayce - -Contributing editor: JhIcefair (primary) - -
- -
- -Disclaimer: (click to expand) - -- Some technical functions and operations of Airi will not be explained in detail in this manual. -- The primary editor is only responsible for the Chinese version of this manual. Other language versions are AI‑translated and then lightly manually corrected, so they may not match the actual software. Please refer to the actual content. -- Most of the content has been explored by the lead writing team and may differ from reality. Please rely on your own experience. -- This manual may not be updated in a timely manner. -- Due to limited time and ability, this manual currently only covers some detailed tutorials for Airi installed via the installer on Windows. -- Some parts of the software use English without translation. This manual attempts to translate those parts, but the final interpretation should follow the actual software. -- Version updates may change content. This manual only describes the latest version before the writing time. If you encounter differences with other versions, please handle them yourself. -- If you have additions or questions about this manual, please @jhicefair on the official Project Airi Discord channel and leave a message. -- For any other questions, please leave a message on the official Project Airi Discord channel. -- Have fun! AwA - -
- -## Chapter 1 – Installation - -Go to the Project Airi GitHub homepage: [moeru-ai/airi](https://github.com/moeru-ai/airi) - -Find the “**Releases**” option on the right side of the page. - -Click “+ 68 releases” -(Note: the number indicates other releases; yours may not be 68) - -Pick a version, find “**Assets**” below it, and expand. - -Choose the version suitable for your computer and download it. -(Note: You may need to click “Show all 19 assets” at the bottom – the number may vary.) - -[ *The following uses the Windows installer version as an example.* ] - -Locate the downloaded installer and double‑click to install. -*(Due to time constraints, this part is skipped; I believe you can handle it.)* - -## Chapter 2 – Initial Configuration - -### Section 1 – Preparation - -Before you begin, you need to prepare at least one API from an LLM service provider. - -
- -Terminology explanation: (click to expand) - -* LLM - -LLM stands for Large Language Model. -Simply put, an AI. - -* API - -API stands for Application Programming Interface. -It is a set of predefined rules that allow different software applications to communicate, exchange data, and share functions. -You don’t need to understand it deeply, just know how to obtain one. - -
- -[There are many LLM providers, and the methods to obtain an API vary. Due to time constraints, no tutorial or example is provided here. Please search online or ask an AI.] - -Once you have your API, keep it safe and do not share it with others. - -### Section 2 – Launch Airi! - -Open Airi (normally it opens automatically after installation). - -Select your language in the main window. - -Click “**setup with your provider**”. - -Select your service source and click “**Next**”. - -[ *Using Deepseek as an example* ] - -Enter your API Key and click “**Next**”. - -Click “**Next**” again. - -Select the model you wish to use, then click “**Save and continue**”. - -Congratulations! You have completed the initial configuration of Airi. - -## Chapter 3 – Airi Interface Overview - -### Main Window - -This window displays the virtual character. There are four buttons: -- “websocket status” – top right, click to open connection settings (detailed explanation omitted). -- “Expand” – bottom right, click to reveal more options (see below). -- “Open hearing control” – bottom right, allows you to speak to Airi (requires STT service; seems you also need to open the chat window first. Since this function hasn’t worked for me yet, tutorial omitted). -- “Move” – bottom right, long‑press and drag to reposition the main window. - -
- -Terminology explanation: (click to expand) - -* websocket - -WebSocket is a network communication protocol that provides full‑duplex, persistent connections between a browser and a server. -In simple terms, traditional HTTP is a “request‑response” model (client requests, server responds, then disconnects), while WebSocket allows both parties to send messages at any time after the connection is established, without repeated requests. - -* STT - -STT stands for Speech‑to‑Text, also known as automatic speech recognition (ASR). -Its goal is to enable computers to understand human speech and convert it into text. - -
- -Click “Expand” to reveal eight options: -- “Open settings” – opens the settings window. -- “Switch character” – switch character cards (details omitted due to time). -- “Open chat” – opens the chat window. -- “Refresh” – refreshes the main window. -- “Switch to dark mode” – toggles light/dark theme. -- “Unpin” – makes the main window not always on top. -- “Always show” / “Hide on hover” – allows clicking through the window. -- “Close” – closes Airi. - -### System Tray Other Options - -First, locate the Airi icon in the system tray (on Windows you may need to click “Show hidden icons”). - -Right‑click the Airi icon to see ten options: -- “Show” – brings up the main window, usually not needed. -- “Adjust size” – adjusts the main window size and centers it. - Includes four options: “Recommended (450x600)”, “Full height”, “Half height”, “Full screen”. -- “Align to” – aligns the main window to a specific screen position. - Includes five options: “Center”, “Top left”, “Top right”, “Bottom left”, “Bottom right”. -- “Settings” – opens the settings window. -- “About” – details omitted. -- “Open quick actions” – details omitted. -- “Open widgets” – details omitted. -- “Open caption” – opens subtitles (requires TTS service to display text when Airi speaks; default hides on hover). -- “Caption overlay” – includes two options: “Follow window” (default, caption moves with main window) and “Reset position”. -- “Quit” – closes Airi. - -
- -Terminology explanation: (click to expand) - -* TTS - -TTS stands for Text‑to‑Speech, which converts written text into natural‑sounding spoken output. - -
- -### Settings Window - -[ *This section only describes what the window contains; detailed functions are in Chapter 4.* ] - -You can open settings by clicking “Expand” on the main window and selecting “Open settings”, or by right‑clicking the Airi tray icon. - -There are nine sections: - -- “AIRI Character Card” – configure character personality. -- “Body Modules” – configure various functions: Consciousness, Vocalization, Hearing, Vision, Short‑term Memory, Long‑term Memory, Discord, X/Twitter, Minecraft, Factorio, MCP Server, Rhythm Game. -- “Scene” – not yet released. -- “Character Model” – choose and configure the character’s model. -- “Memory Bank” – not yet released. -- “Service Sources” – configure LLM, TTS, STT services. -- “Data” – manage Airi’s data. -- “Connection” – configure WebSocket server address. -- “System” – includes four sub‑sections: “General” (theme, language, etc.), “Color Scheme”, “Window Shortcuts” (empty – see warning), “Developer” (advanced features, see Chapter 4). - -### Chat Window - -You can open the chat window by clicking “Expand” on the main window and selecting “Open chat”. - -Here you can chat with Airi. -Detailed introduction omitted. - -## Chapter 4 – Settings - -You can open settings by clicking “Expand” on the main window and selecting “Open settings”, or by right‑clicking the Airi tray icon. - -### AIRI Character Card - -Here you can upload, create, or modify the default character card. - -About uploading: the popup suggests any file type is supported, but I haven’t used it, and there is no export function, so details omitted. - -About creating a new character card: -You can set the character’s identity, behavior, modules, etc. - -**Identity** includes name, nickname, description, creator’s notes. -Name is the official name; if a nickname is set, it will be used first. -Description is the detailed personality. You can be creative or refer to the default character card. -(Note: if you refer to the default card, you may omit the part about ACT tags.) -Creator’s notes – I haven’t used them, details omitted. - -**Behavior** includes personality, scenario (environment/background/context), and greeting. I haven’t adjusted these, details omitted. - -**Modules** – you can configure character‑specific body modules; usually leave as is, details omitted. - -**Settings** includes system prompt, history prompt instructions, and version (character card version). I haven’t used the first two, details omitted. - -The most important parts are name and description in Identity. After filling them in, click “**Create**” to complete the character card. - -Finally, click the circle in the bottom‑right corner of the card, or select the card and click Activate, to enable your character card. -[ ***Note: Newly created cards are not enabled by default. You must activate them.*** ] - -### Body Modules - -Here you can configure various Airi functions, as follows: - -#### Consciousness - -First select a service source (or add a new one) and select it. -[ *If there are too many sources and you cannot click the ones at the back, move the mouse over a tab, press the middle button, and drag left/right.* ] -Then select a model – configuration is complete. - -#### Vocalization - -First select a service source (or add a new one) and select it. -Then select a model, then select a voice. -You can also choose “None” to disable Airi’s voice. - -At the bottom of this page, you can enter text to test the voice by clicking “**Test voice**”. - -[ Note: The configuration process may vary slightly for different service sources. This uses Alibaba Bailian as an example; follow the actual interface. ] -[ For some services, the Pitch control may not work. ] - -Other details omitted. - -#### Hearing - -First select your audio input device. -Then select a service source (or add a new one) and select it. -Then select a model – configuration is complete. - -Additionally, you can enable “Auto‑send transcribed text” to send automatically, or disable it to adjust the transcription result (I think – I haven’t successfully used Hearing). -You can also set “Auto‑send delay”. - -In the middle of this page, you can test the microphone. -Click “**start monitoring**” to start listening. -You can adjust Sensitivity (I haven’t tried it, details omitted). - -At the bottom of this page, you can test STT. -Click “**start speech‑to‑text**” to begin testing. -The result will appear under “Transcription Result”. - -Other details omitted. - -#### Vision - -First select a service source (or add a new one) and select it. -Then select a model – configuration is complete. - -You can also set “Capture interval”. - -[ ***This function requires enabling vision capture in System → Developer → vision capture. See that section for details.*** ] - -Other details omitted. - -#### Short‑term Memory - -Not yet released. - -#### Long‑term Memory - -Not yet released. - -#### Discord - -Here you can configure a Discord bot so that Airi can join your Discord server and interact. -You need to obtain your Discord bot token and enter it in the appropriate field. - -**Note:** -This function requires a Discord bot, which is not included in the installer version. You need to extract the relevant files from the GitHub page. Since I have a low priority for this, tutorial omitted. - -#### X/Twitter - -Similar to Discord; requires a bot. Tutorial omitted. - -#### Minecraft - -Requires a bot. Tutorial omitted. - -#### Factorio - -Requires a bot. Tutorial omitted. - -#### MCP Server - -I haven’t used this. Tutorial omitted. - -#### Rhythm Game - -I am still exploring this. Tutorial omitted. - -### Scene - -Not yet released. - -### Character Model - -Here you can choose and set the character’s model. - -Airi supports Live2D models and VRM 3D models. - -Click “**select model**” to choose a model. In this version, there are two Live2D and two VRM models by default. -Select one and click “**confirm**” to switch models. -You can also click “**add**” to import your own Live2D or VRM model. - -[ **Note: Old Live2D models are not supported! You must use files including “*.moc3”.** ] -[ **Before importing a Live2D model, you must compress the model folder into a “*.zip” file.** ] - -- **If you choose a Live2D model** - -Expand “Zoom & Position” to adjust the model’s size and position in the main window. -x is horizontal (left/right), y is vertical (up/down). - -Expand “parameters” to set mouse tracking, Idle Animation, frame rate, Auto Blink, Force Auto Blink (fallback timer), Shadow, reset to default parameters, clear model cache, and all model‑specific parameters. -If you want to set an idle animation, ensure the model zip includes animation files. -Other details omitted. - -Expand “Expressions” to enable the Expression System. -I haven’t tested this yet, details omitted. - -- **If you choose a VRM 3D model** - -Expand “Scene” to set Model Position, camera angle (degrees), camera distance (zoom), model orientation (Y‑axis rotation), model gaze direction, etc. -This section, including “Change model”, is omitted due to time constraints. - -### Memory Bank - -Not yet released. - -### Service Sources - -Here you can configure LLM, TTS, and STT service sources. - -Details omitted. - -### Data - -Here you can manage Airi’s various data. - -[ ***Note: This section allows deletion and clearing of data, which cannot be undone. Please operate with caution!*** ] - -The first box contains “Open app data folder”. -Click “**Open folder**” to open it. -[ *Note: There is a bug – it opens the folder multiple times at once.* ] - -The second box allows you to import/export chat history or delete all chat sessions. -(Details omitted.) - -The third box allows you to delete all imported models or reset module preferences and credentials. -(Details omitted.) - -The fourth box allows you to reset desktop settings and state. -(Details omitted.) - -The fifth box allows you to reset all provider settings and credentials, or clear every local setting, provider configuration, and model. -(Details omitted.) - -### Connection - -Here you can configure your WebSocket server address. - -(Details omitted.) - -### System - -#### General - -Here you can set the program theme, language, etc. - -Theme defaults to light; click the button to switch to dark mode. - -Language sets the interface language. - -Control island icon size changes the size of the three buttons at the bottom‑right of the main window. - -Finally, you can choose whether to allow collection of usage data and crash reports, or read the privacy policy (click “Privacy Policy” to open). - -#### Color Scheme - -Here you can change the theme color. - -You can enable the RGB option to make the theme color cycle like an RGB strip. -You can also drag the black line or click on the color bar to change the theme color. -Below that is a color preview. - -You can also select a preset below to change the theme color. -[ ***Note: You should click on a circle, not the square box.*** ] - -#### Window Shortcuts - -[ ***Warning: This option has no content and no back button. Once you enter, you must close and reopen the settings window. Do not click it!*** ] - -#### Developer - -Here you can use some advanced features. - -[ **Since most of this content is in English and consists of advanced features that are rarely needed, this part is for reference only!** ] - -- In the first box, you can click “**Open**” to open the developer tools window (like F12 in a browser). - -- The second “Markdown stress test” – details omitted. - -- The third “Lag visualization” – details omitted. - -- The fourth “Enable stage transition animation” – details omitted. - -- The fifth “Use page‑specific cutscenes” – details omitted. - -##### useMagicKeys tool - -Blank – details omitted. - -##### useElectronWindowMouse - -Here you can detect the mouse cursor position on the screen. - -##### Displays - -Here you can visualize the mouse cursor position on the screen. - -##### widgets calling - -Details omitted. - -##### Context Flow - -Real‑time inspection of incoming context updates (server + broadcast) and outgoing chat hooks. Use this to verify how plugin context (e.g., VSCode coding context) flows into the chat pipeline and out to server events. -Details omitted. - -##### relative mouse - -Here you can visualize the mouse cursor position within this window. - -##### beat sync visualizer - -Details omitted. - -##### WebSocket Inspector - -Details omitted. - -##### Plugin Host Debug - -Details omitted. - -##### Screen Capture - -Here you can capture any application window or the entire screen. -There are four options at the top: -“applications” – select any open application window, click “**share window**” to view it at the top; move the mouse over the capture and click “stop” to stop. -“displays” – capture the whole screen, click “**share screen**” to view; move the mouse over the capture and click “stop” to stop. -“devices” – omitted. -“refetch” – omitted. - -##### vision capture - -Details omitted. diff --git a/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-airi-card.avif b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-airi-card.avif new file mode 100644 index 000000000..a6fd61681 Binary files /dev/null and b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-airi-card.avif differ diff --git a/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-chat-window.avif b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-chat-window.avif new file mode 100644 index 000000000..05d1e9032 Binary files /dev/null and b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-chat-window.avif differ diff --git a/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-consciousness.avif b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-consciousness.avif new file mode 100644 index 000000000..fe5ee4fe1 Binary files /dev/null and b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-consciousness.avif differ diff --git a/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-controls-island-expanded.avif b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-controls-island-expanded.avif new file mode 100644 index 000000000..b7dafd0c5 Binary files /dev/null and b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-controls-island-expanded.avif differ diff --git a/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-data-settings.avif b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-data-settings.avif new file mode 100644 index 000000000..088b96ecd Binary files /dev/null and b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-data-settings.avif differ diff --git a/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-beat-sync.avif b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-beat-sync.avif new file mode 100644 index 000000000..9531f2baa Binary files /dev/null and b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-beat-sync.avif differ diff --git a/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-context-flow.avif b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-context-flow.avif new file mode 100644 index 000000000..0619480da Binary files /dev/null and b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-context-flow.avif differ diff --git a/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-displays.avif b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-displays.avif new file mode 100644 index 000000000..b343ff0b7 Binary files /dev/null and b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-displays.avif differ diff --git a/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-plugin-host.avif b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-plugin-host.avif new file mode 100644 index 000000000..6e823bac8 Binary files /dev/null and b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-plugin-host.avif differ diff --git a/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-relative-mouse.avif b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-relative-mouse.avif new file mode 100644 index 000000000..9386d0eda Binary files /dev/null and b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-relative-mouse.avif differ diff --git a/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-screen-capture.avif b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-screen-capture.avif new file mode 100644 index 000000000..06ab8510c Binary files /dev/null and b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-screen-capture.avif differ diff --git a/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-use-window-mouse.avif b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-use-window-mouse.avif new file mode 100644 index 000000000..16d654fd0 Binary files /dev/null and b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-use-window-mouse.avif differ diff --git a/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-vision-capture.avif b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-vision-capture.avif new file mode 100644 index 000000000..4a646c191 Binary files /dev/null and b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-vision-capture.avif differ diff --git a/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-websocket-inspector.avif b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-websocket-inspector.avif new file mode 100644 index 000000000..8e5bfd83a Binary files /dev/null and b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-websocket-inspector.avif differ diff --git a/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-widgets-calling.avif b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-widgets-calling.avif new file mode 100644 index 000000000..909c95eec Binary files /dev/null and b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-widgets-calling.avif differ diff --git a/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-hearing.avif b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-hearing.avif new file mode 100644 index 000000000..9bf562f1b Binary files /dev/null and b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-hearing.avif differ diff --git a/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-main-window.avif b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-main-window.avif new file mode 100644 index 000000000..f7e4fc974 Binary files /dev/null and b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-main-window.avif differ diff --git a/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-models.avif b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-models.avif new file mode 100644 index 000000000..8946953c4 Binary files /dev/null and b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-models.avif differ diff --git a/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-modules.avif b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-modules.avif new file mode 100644 index 000000000..836b0d088 Binary files /dev/null and b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-modules.avif differ diff --git a/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-providers.avif b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-providers.avif new file mode 100644 index 000000000..2db9d78e0 Binary files /dev/null and b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-providers.avif differ diff --git a/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-settings-window.avif b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-settings-window.avif new file mode 100644 index 000000000..380acfcd7 Binary files /dev/null and b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-settings-window.avif differ diff --git a/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-speech.avif b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-speech.avif new file mode 100644 index 000000000..ed2ac2fde Binary files /dev/null and b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-speech.avif differ diff --git a/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-system-color-scheme.avif b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-system-color-scheme.avif new file mode 100644 index 000000000..cf83c6cbe Binary files /dev/null and b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-system-color-scheme.avif differ diff --git a/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-system-developer.avif b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-system-developer.avif new file mode 100644 index 000000000..135057923 Binary files /dev/null and b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-system-developer.avif differ diff --git a/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-system-general.avif b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-system-general.avif new file mode 100644 index 000000000..8b3ae7d82 Binary files /dev/null and b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-system-general.avif differ diff --git a/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-vision.avif b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-vision.avif new file mode 100644 index 000000000..9c4bbdfba Binary files /dev/null and b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-vision.avif differ diff --git a/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-websocket-settings.avif b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-websocket-settings.avif new file mode 100644 index 000000000..b62cf3f73 Binary files /dev/null and b/docs/content/en/docs/manual/tamagotchi/setup-and-use/assets/manual-websocket-settings.avif differ diff --git a/docs/content/en/docs/manual/tamagotchi/setup-and-use/index.md b/docs/content/en/docs/manual/tamagotchi/setup-and-use/index.md new file mode 100644 index 000000000..aa3d776a2 --- /dev/null +++ b/docs/content/en/docs/manual/tamagotchi/setup-and-use/index.md @@ -0,0 +1,631 @@ +# Project AIRI Manual + +Writing time: (UTC+8) April 2, 2026 – evening + +Corresponding version: AIRI-0.9.0-beta.4-windows-x64 + +::: info Authors +Lead writing team: MuGewRayce + +Contributing editor: JhIcefair (primary) +::: + +::: warning Before You Start +- Some technical functions and operations of AIRI will not be explained in detail in this manual. +- The primary editor is only responsible for the Chinese version of this manual. Other language versions are AI-translated and then lightly manually corrected, so they may not match the actual software. Please refer to the actual content. +- Most of the content has been explored by the lead writing team and may differ from reality. Please rely on your own experience. +- This manual may not be updated in a timely manner. +- Due to limited time and ability, this manual currently only covers some detailed tutorials for AIRI installed via the installer on Windows. +- Some parts of the software use English without translation. This manual attempts to translate those parts, but the final interpretation should follow the actual software. +- Version updates may change content. This manual only describes the latest version before the writing time. If you encounter differences with other versions, please handle them yourself. +- If you have additions or questions about this manual, please @jhicefair on the official Project AIRI Discord channel and leave a message. +- For any other questions, please leave a message on the official Project AIRI Discord channel. +- Have fun! AwA +::: + +## Table Of Contents + +- [Chapter 1 – Installation](#chapter-1-installation) +- [Chapter 2 – Initial Configuration](#chapter-2-initial-configuration) + - [Section 1 – Preparation](#chapter-2-prerequisites) + - [Section 2 – Launch Airi!](#chapter-2-launch) +- [Chapter 3 – Airi Interface Overview](#chapter-3-interface-overview) + - [Main Window](#chapter-3-main-window) + - [System Tray Other Options](#chapter-3-system-tray) + - [Settings Window](#chapter-3-settings-overview) + - [Chat Window](#chapter-3-chat-window) +- [Chapter 4 – Settings](#chapter-4-settings) + - [AIRI Character Card](#chapter-4-airi-card) + - [Body Modules](#chapter-4-modules) + - [Scene](#chapter-4-stage) + - [Character Model](#chapter-4-character-model) + - [Memory Bank](#chapter-4-memory-bank) + - [Service Sources](#chapter-4-providers) + - [Data](#chapter-4-data) + - [Connection](#chapter-4-connection) + - [System](#chapter-4-system) + + +## Chapter 1 – Installation + +Go to the Project AIRI GitHub homepage: [moeru-ai/airi](https://github.com/moeru-ai/airi) + +Follow these steps: + +1. Find the "**Releases**" option on the right side of the page. +2. Click "+ 68 releases". +3. Pick a version, find "**Assets**" below it, and expand. +4. Choose the version suitable for your computer and download it. +5. Locate the downloaded installer and double-click to install. + +::: tip Download Page Notes +- The number in "+ 68 releases" only shows how many other releases exist, so yours may differ. +- You may also need to click "Show all 19 assets" at the bottom; that number may also vary. +- The following sections use the Windows installer version as an example. +- Due to time constraints, the installation walkthrough itself is skipped — you can handle it. +::: + + +## Chapter 2 – Initial Configuration + + +### Section 1 – Preparation + +Before you begin, you need to prepare at least one API from an LLM service provider. + +::: info Terminology +* LLM + +LLM stands for Large Language Model. +Simply put, an AI. + +* API + +API stands for Application Programming Interface. +It is a set of predefined rules that allow different software applications to communicate, exchange data, and share functions. +You don't need to understand it deeply, just know how to obtain one. +::: + +::: tip Getting An API +There are many LLM providers, and the method for obtaining an API varies. Due to time constraints, no tutorial or example is provided here. Please search online or ask an AI. +::: + +::: warning Keep Your API Key Safe +Once you have your API, keep it safe and do not share it with others. +::: + + +### Section 2 – Launch Airi! + +::: info Example +The steps below use Deepseek as the example provider. +::: + +Follow these steps to finish the first-time setup: + +1. Open Airi (normally it opens automatically after installation). +2. Select your language in the main window. +3. Click "**setup with your provider**". +4. Select your service source and click "**Next**". +5. Enter your API Key and click "**Next**". +6. Click "**Next**" again. +7. Select the model you wish to use, then click "**Save and continue**". + +Congratulations! You have completed the initial configuration of Airi. + + +## Chapter 3 – Airi Interface Overview + + +### Main Window + +This window displays the virtual character. There are four buttons: + +- "websocket status" – top right, click to open connection settings where you can configure your WebSocket server address. +- "Expand" – bottom right, click to reveal more options (see below). +- "Open hearing control" – bottom right, allows you to speak to Airi. Requires an STT service. +- "Move" – bottom right, long-press and drag to reposition the main window. + +![Airi main window overview](./assets/manual-main-window.avif) + +::: info About Hearing Control +It seems you also need to open the chat window first. Since this feature has not worked for the editor yet, the tutorial is omitted. +::: + +::: info Terminology +* websocket + +WebSocket is a network communication protocol that provides full-duplex, persistent connections between a browser and a server. +In simple terms, traditional HTTP is a "request-response" model (client requests, server responds, then disconnects), while WebSocket allows both parties to send messages at any time after the connection is established, without repeated requests. + +* STT + +STT stands for Speech-to-Text, also known as automatic speech recognition (ASR). +Its goal is to enable computers to understand human speech and convert it into text. +::: + +Click "Expand" to reveal eight options: + +- "Open settings" – opens the settings window. +- "Switch character" – switch character cards. +- "Open chat" – opens the chat window. +- "Refresh" – refreshes the main window. +- "Switch to dark mode" – toggles light/dark theme. +- "Unpin" – makes the main window not always on top. +- "Always show" / "Hide on hover" – allows clicking through the window. +- "Close" – closes Airi. + +![Airi expanded controls menu](./assets/manual-controls-island-expanded.avif) + + +### System Tray Other Options + +First, locate the Airi icon in the system tray. + +::: tip Windows Taskbar Tip +On Windows, you may need to click "Show hidden icons" in the taskbar to find the Airi icon. +::: + +Right-click the Airi icon to see ten options: + +- "Show" – brings up the main window, usually not needed. +- "Adjust size" – adjusts the main window size and centers it. Includes four sub-options: + - "Recommended (450x600)" – sets the window to the recommended 450x600 size. + - "Full height" – makes the window's height span the full desktop height. + - "Half height" – makes the window's height span half the desktop height. + - "Full screen" – makes the window fill the entire desktop. +- "Align to" – aligns the main window to a specific screen position. Includes five sub-options: + - "Center" – aligns to the center of the desktop. + - "Top left" – aligns to the top-left corner. + - "Top right" – aligns to the top-right corner. + - "Bottom left" – aligns to the bottom-left corner. + - "Bottom right" – aligns to the bottom-right corner. +- "Settings" – opens the settings window. +- "About" – details omitted. +- "Open quick actions" – details omitted. +- "Open widgets" – details omitted. +- "Open caption" – opens subtitles. Requires TTS service to display text when Airi speaks; hidden on hover by default. +- "Caption overlay" – includes two sub-options: + - "Follow window" – default; caption position follows the main window. + - "Reset position" – resets the caption position. +- "Quit" – closes Airi. + +::: info Terminology +* TTS + +TTS stands for Text-to-Speech, which converts written text into natural-sounding spoken output. +::: + + +### Settings Window + +::: info Scope +This section only describes what the window contains. Detailed functions are explained in Chapter 4. +::: + +You can open settings in either of these ways: + +- Click "Expand" on the main window, then select "Open settings". +- Right-click the Airi tray icon and select "Settings". + +The settings window contains nine sections: + +- "AIRI Character Card" – configure character personality. +- "Body Modules" – configure various functions: Consciousness, Vocalization, Hearing, Vision, Short-term Memory, Long-term Memory, Discord, X/Twitter, Minecraft, Factorio, MCP Server, Rhythm Game. +- "Scene" – not yet released. +- "Character Model" – choose and configure the character's model. +- "Memory Bank" – not yet released. +- "Service Sources" – configure LLM, TTS, STT services. +- "Data" – manage Airi's data. +- "Connection" – configure WebSocket server address. +- "System" – includes four sub-sections: + - "General" – theme, language, etc. + - "Color Scheme" – change the theme color. + - "Window Shortcuts" – currently empty, no back button. + - "Developer" – advanced features, see Chapter 4. + +::: warning Do Not Open "Window Shortcuts" +This option currently has no content and no back button. Once you enter it, you must close and reopen the settings window to exit. +::: + +![Airi settings window overview](./assets/manual-settings-window.avif) + + +### Chat Window + +You can open the chat window by clicking "Expand" on the main window and selecting "Open chat". + +![Airi chat window interface](./assets/manual-chat-window.avif) + +Here you can chat with Airi. + + +## Chapter 4 – Settings + +You can open settings in either of these ways: + +- Click "Expand" on the main window, then select "Open settings". +- Right-click the Airi tray icon and select "Settings". + + +### AIRI Character Card + +Here you can upload, create, or modify the default character card. + +![Airi character card settings window](./assets/manual-airi-card.avif) + +::: info About Uploading +The upload dialog suggests any file type is supported, but the editor has not actually used it, and there is no export function either, so details are omitted. +::: + +About creating a new character card, the recommended order is: + +1. Fill out **Identity**, including name, nickname, description, and creator's notes. +2. Then adjust **Behavior**, including personality, scenario, and greeting. +3. If needed, configure **Modules** for character-specific body modules. +4. Finally, review **Settings**, including system prompt, history prompt instructions, and version. +5. When you are ready, click "**Create**" to create the character card. +6. After creation, click the circle in the bottom-right corner of the card, or select the card and click Activate, to enable it. + +The most important fields in **Identity** are name and description: + +- Name is the official name; if a nickname is set, the nickname will be used first. +- Description is the detailed personality. You can be creative or refer to the default character card. + +::: info Editor Notes +- If you refer to the default character card, you may omit the part about ACT tags. +- The editor has not used creator's notes, so details are omitted. +- The editor has not fully tested Behavior, Modules, or Settings yet — only the rough purpose is documented above. +::: + +::: warning Activation Required +Newly created cards are not enabled by default. You must activate them manually. +::: + + +### Body Modules + +Here you can configure various Airi functions, as follows: + +![Airi body modules settings window](./assets/manual-modules.avif) + +#### Consciousness + +Recommended order: + +1. First select a service source, or add a new one and select it. +2. Then select a model. + +::: tip Too Many Service Sources +If there are too many sources and you cannot click the ones at the back, move the mouse over a tab, press the middle mouse button, and drag left or right. +::: + +![Airi consciousness settings window](./assets/manual-consciousness.avif) + +#### Vocalization + +::: tip Vocalization Notes +- The configuration process may vary slightly for different service sources. This section uses Alibaba Bailian as an example; follow the actual interface. +- For some services, the Pitch control may not work. +- If there are too many sources and you cannot click the ones at the back, move the mouse over a tab, press the middle mouse button, and drag left or right. +::: + +Recommended order: + +1. First select a service source, or add a new one and select it. +2. Then select a model. +3. Next select a voice. +4. If you do not want Airi to speak, choose "None". +5. After the basic setup, you can enter text at the bottom of this page and click "**Test voice**" to generate a sample. + +![Airi vocalization settings window](./assets/manual-speech.avif) + +#### Hearing + +::: tip Too Many Service Sources +If there are too many sources and you cannot click the ones at the back, move the mouse over a tab, press the middle mouse button, and drag left or right. +::: + +Recommended order: + +1. First select your audio input device. +2. Then select a service source, or add a new one and select it. +3. Then select a model. + +![Airi hearing settings window](./assets/manual-hearing.avif) + +In addition, you can: + +- Enable "Auto-send transcribed text" to send transcripts automatically. +- Disable it to adjust the transcription result before sending. +- Configure "Auto-send delay" to tune the send delay. + +::: info Editor Note +The claim that "disabling auto-send lets you adjust the transcription" is the editor's guess — the editor has not successfully used the Hearing feature. +::: + +If you want to test the microphone: + +1. Click "**start monitoring**" in the middle of the page. +2. If needed, adjust Sensitivity. + +If you want to test STT: + +1. Click "**start speech-to-text**" at the bottom of the page. +2. Check the result under "Transcription Result". + +#### Vision + +::: tip Too Many Service Sources +If there are too many sources and you cannot click the ones at the back, move the mouse over a tab, press the middle mouse button, and drag left or right. +::: + +Recommended order: + +1. First select a service source, or add a new one and select it. +2. Then select a model. +3. Optionally set "Capture interval" to control the capture frequency. + +![Airi vision settings window](./assets/manual-vision.avif) + +::: warning Requires Vision Capture +This function requires enabling `vision capture` in `System → Developer → vision capture`. See that section for details. +::: + +#### Short-term Memory + +Not yet released. + +#### Long-term Memory + +Not yet released. + +#### Discord + +Here you can configure a Discord bot so that Airi can join your Discord server and interact. + +Recommended order: + +1. Obtain your Discord bot token. +2. Enter it into the appropriate field. +3. Finish the rest of the configuration based on the page. + +::: warning About The Discord Bot +This function requires a Discord bot, which is not included in the installer version. You need to extract the relevant files from the GitHub page. Since the editor's schedule for this is a low priority, the full tutorial is omitted. +::: + +#### X/Twitter + +Similar to Discord; requires a bot. Tutorial omitted. + +#### Minecraft + +Requires a bot. Tutorial omitted. + +#### Factorio + +Requires a bot. Tutorial omitted. + +#### MCP Server + +The editor has not used this. Tutorial omitted. + +#### Rhythm Game + +The editor is still exploring this. Tutorial omitted. + + +### Scene + +Not yet released. + + +### Character Model + +Here you can choose and set the character's model. + +![Airi character model settings window](./assets/manual-models.avif) + +Airi supports Live2D models and VRM 3D models. + +If you only want to switch to an existing model: + +1. Click "**select model**" to open the model picker. +2. In this version, there are two Live2D and two VRM models by default. +3. Select one and click "**confirm**" to switch. + +If you want to import your own model, click "**add**" to import a Live2D or VRM model. + +::: warning Before Importing A Model +- Old Live2D models are not supported. You must use files that include "\*.moc3". +- Before importing a Live2D model, compress the model folder into a "\*.zip" file. +::: + +#### If you choose a Live2D model + +You can continue in this order: + +1. Expand "Zoom & Position" to adjust the model's size and position in the main window. x is horizontal (left/right), y is vertical (up/down). +2. Expand "parameters" to set mouse tracking, Idle Animation, frame rate, Auto Blink, Force Auto Blink (fallback timer), Shadow, reset to default parameters, clear model cache, and all model-specific parameters. +3. If you want idle animation, make sure the model zip includes animation files. +4. If needed, expand "Expressions" to enable the Expression System. + +::: info Editor Note +The editor has not fully tested this part yet, so details are still limited. +::: + +#### If you choose a VRM 3D model + +Expand "Scene" and then set Model Position, camera angle (degrees), camera distance (zoom), model orientation (Y-axis rotation), model gaze direction, and related values. + +::: info Editor Note +This section, including "Change model", is omitted due to time constraints. +::: + + +### Memory Bank + +Not yet released. + + +### Service Sources + +Here you can configure LLM, TTS, and STT service sources. + +![Airi service sources settings window](./assets/manual-providers.avif) + +::: info Editor Note +Details omitted. +::: + + +### Data + +Here you can manage Airi's various data. + +![Airi data settings window](./assets/manual-data-settings.avif) + +::: warning Destructive Actions +This section allows deletion and clearing of data, which cannot be undone. Please operate with caution, and double-check before running any delete or reset action. +::: + +::: tip Known Issue +"Open app data folder" currently has a bug where it may open the folder multiple times at once. +::: + +This page is organized into boxes: + +1. The first box contains "Open app data folder". Click "**Open folder**" to open it. +2. The second box allows you to import/export chat history or delete all chat sessions. +3. The third box allows you to delete all imported models or reset module preferences and credentials. +4. The fourth box allows you to reset desktop settings and state. +5. The fifth box allows you to reset all provider settings and credentials, or clear every local setting, provider configuration, and model. + + +### Connection + +Here you can configure your WebSocket server address. + +![Airi connection settings window](./assets/manual-websocket-settings.avif) + +::: info Editor Note +Details omitted. +::: + + +### System + +#### General + +Here you can set the program theme, language, etc. + +![Airi general system settings window](./assets/manual-system-general.avif) + +- Theme defaults to light; click the button to switch to dark mode. +- Language sets the interface language. +- Control island icon size changes the size of the three buttons at the bottom-right of the main window. +- Finally, you can choose whether to allow collection of usage data and crash reports, or read the privacy policy (click "Privacy Policy" to open). + +#### Color Scheme + +Here you can change the theme color. + +![Airi color scheme settings window](./assets/manual-system-color-scheme.avif) + +- Enable the RGB option to make the theme color cycle like an RGB strip. +- Drag the black line or click on the color bar to change the theme color. +- Below that is a color preview. +- You can also select a preset below to change the theme color. + +::: tip Color Presets +Click on one of the circles, not the square box. +::: + +#### Window Shortcuts + +::: warning Do Not Open +This option has no content and no back button. Once you enter it, you must close and reopen the settings window. Do not click it. +::: + +#### Developer + +Here you can use some advanced features. + +![Airi developer settings window](./assets/manual-system-developer.avif) + +::: info Advanced Features +Most of this content is in English and consists of advanced features that are rarely needed, so this section is for reference only. +::: + +First box and its related options: + +- In the first box, you can click "**Open**" to open the developer tools window (like F12 in a browser). +- The second "Markdown stress test" – details omitted. +- The third "Lag visualization" – details omitted. +- The fourth "Enable stage transition animation" – details omitted. +- The fifth "Use page-specific cutscenes" – details omitted. + +##### useMagicKeys tool + +::: info Editor Note +The page is currently blank; details omitted. +::: + +##### useElectronWindowMouse + +Here you can detect the mouse cursor position on the screen. + +![Airi useElectronWindowMouse tool window](./assets/manual-devtools-use-window-mouse.avif) + +##### Displays + +Here you can visualize the mouse cursor position on the screen. + +![Airi Displays tool window](./assets/manual-devtools-displays.avif) + +##### widgets calling + +![Airi widgets calling tool window](./assets/manual-devtools-widgets-calling.avif) + +##### Context Flow + +Real-time inspection of incoming context updates (server + broadcast) and outgoing chat hooks. Use this to verify how plugin context (e.g., VSCode coding context) flows into the chat pipeline and out to server events. + +![Airi Context Flow tool window](./assets/manual-devtools-context-flow.avif) + +##### relative mouse + +Here you can visualize the mouse cursor position within this window. + +![Airi relative mouse tool window](./assets/manual-devtools-relative-mouse.avif) + +##### beat sync visualizer + +![Airi beat sync visualizer tool window](./assets/manual-devtools-beat-sync.avif) + +##### WebSocket Inspector + +![Airi WebSocket Inspector tool window](./assets/manual-devtools-websocket-inspector.avif) + +##### Plugin Host Debug + +![Airi Plugin Host Debug tool window](./assets/manual-devtools-plugin-host.avif) + +##### Screen Capture + +If you have not granted system-level screen capture permission yet, you will first see a permission prompt like the screenshot below. After granting permission, you can capture any application window or the entire screen. + +There are four options at the top: + +- "applications" – select any open application window, click "**share window**" to view it at the top; move the mouse over the capture and click "stop" to stop. +- "displays" – capture the whole screen, click "**share screen**" to view; move the mouse over the capture and click "stop" to stop. +- "devices" – details omitted. +- "refetch" – details omitted. + +![Airi Screen Capture tool window](./assets/manual-devtools-screen-capture.avif) + +##### vision capture + +If screen capture permission has not been granted yet, this page will also show a permission prompt first. After granting permission, the page can start capturing frames and show the vision processing result. + +![Airi vision capture tool window](./assets/manual-devtools-vision-capture.avif) diff --git a/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use.md b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use.md deleted file mode 100644 index b94b61a68..000000000 --- a/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use.md +++ /dev/null @@ -1,510 +0,0 @@ -# Project Airi 说明书 - -编写时间：（北京时间）2026年4月2日-晚上 - -对应版本：AIRI-0.9.0-beta.4-windows-x64 - -
- -展开了解编写者 - -主编团队：沐玖芸萱（MuGewRayce） - -参与编辑者：JhIcefair（主要） - -
- -
- -声明：（点击展开） - -- 目前关于Airi的部分技术性功能和操作在该说明书中不会具体讲解。 -- 主要编辑者仅对说明书的中文版本负责，其他语言版本目前采用ai翻译，而后人工简单修正的方式处理，可能与实际显示的内容不符，请以实际为准。 -- 说明书的大部分内容为主编团队成员自己探索研究出来的，可能与事实不符或者存在偏差，具体请以自己实际体验到的为准。 -- 该说明书可能不会及时更新。 -- 因能力和时间有限，该说明书暂仅包含windows平台通过安装包安装的Airi的部分详细教程。 -- 软件部分位置使用的是英文而且并没有提供翻译，该说明书会尝试翻译涉及到的部分内容，最终译文请以实际为准。 -- airi的版本更新可能会改变部分内容，该说明书仅介绍编写时间前最新的一个版本的特性，对于前后其他版本的程序，如果遇到不同的地方，请自行解决。 -- 如果您有想要添加的说明或者对该说明书有什么疑问，请在Project_Airi官方Discord频道上@jhicefair并留言。 -- 如果您还有别的什么问题，请在Project_Airi官方Discord频道上留言。 -- 祝您玩的开心！AwA - -
- -## 第一章·安装 - -找到 Project Airi GitHub 主页：[moeru-ai/airi](https://github.com/moeru-ai/airi) - -找到位于页面右侧的“**Releases**”选项 - -点击“+ 68 releases” -（请注意：中间的数字代表的是发布的其他版本的数量，你看到的可能不是68） - -挑一个版本找到下面的“**Assets**”选项并点开 - -选择适合自己电脑的版本点击下载 -（请注意：由于可选的内容比较多，你可能需要再点击列表最下面的“Show all 19 assets”选项，该选项中间的数字表示包含的可下载文件数量，同样可能不是19） - -[ *接下来以windows安装包版本为例* ] - -找到你下载下来的安装包双击左键安装 -*（时间原因该部分教程暂跳过，相信你自己可以解决）* - -## 第二章·初步配置 - -### 第一项·先前准备 - -在一切正式开始前你需要首先至少准备一个LLM服务提供商的API - -
- -名词解释：（点击展开） - -* LLM - -LLM 是“大型语言模型”（Large Language Model）的缩写。 -通俗点讲，一个AI。 - -* API - -API 全称是应用程序编程接口。 -它本质上是一套预先定义好的规则，让不同的软件应用之间可以相互通信、交换数据和功能。 -你可以不用去理解他到底是什么，只要会获取就行。 - -
- -[ LLM提供商有很多而且他们的获取方式各不相同，加上时间原因，这里不提供教程或者举例，具体如何获取你可以去网络上搜索或者询问AI ] - -获取好API后请注意保存好而且不要告诉其他人！ - -### 第二项·Airi 启动！ - -打开Airi（正常情况下安装后会默认自动打开） - -在弹出的主界面选择你的语言 - -点击“**setup with your provider**” -（不知道为什么这里在新版本中都不提供翻译了，这个的意思是：设置您的提供商） - -选中你准备的服务来源并点击“**下一步**” - -[ *接下来以Deepseek为例* ] - -填入你的 API Key 然后点击“**下一步**” - -再点击“**下一步**” - -选择你打算使用的模型，然后点击“**保存并继续**” - -恭喜你，不出意外的话你已经完成了Airi的初步配置！ - -## 第三章·Airi界面介绍 - -### 主窗口 - -该窗口是展示虚拟角色形象的窗口，有四个选项： -- “websocket 状态”——位于右上角，点击可打开连接设置，在这里你可以配置您的WebSocket 服务器地址（该功能暂不做具体讲解） -- “展开”——位于右下角，点击可展开更多选项（具体见下面） -- “打开听力控制”——位于右下角，点击可以与Airi说话，需要提前配置STT服务（好像也得先打开聊天窗口）（由于该功能我这里暂未成功运行，相关教程暂略） -- “移动”——位于右下角，鼠标左键长按并拖动可以改变主窗口在桌面上的位置 - -
- -名词解释：（点击展开） - -* websocket - -WebSocket 是一种网络通信协议，提供了浏览器与服务器之间的全双工、持久连接。 -简单理解就是传统的 HTTP 是“一问一答”模式（客户端请求，服务器响应，然后断开）， -而 WebSocket 建立连接后，双方可以随时互相发送消息，无需重复发起请求。 - -* STT - -STT 是“语音转文本”（Speech-to-Text）的缩写，也称自动语音识别（ASR）。 -它的目标是让计算机听懂人类的语音，并将其转换成对应的文字。 - -
- -点击“展开”选项展开后有八个选项： -- “打开设置”——可以打开Airi的设置界面 -- “切换角色”——可以切换角色卡（点击后的具体内容因为时间原因暂略） -- “打开聊天”——可以打开聊天窗口 -- “刷新”——可以刷新主窗口 -- “切换到暗色模式”——可以切换Airi的界面背景为“亮/暗” -- “取消置顶”——可以使Airi主窗口不再保持置顶显示 -- “总是显示”“悬停时隐藏”——该选项可以使Airi主窗口不影响鼠标光标对窗口下的内容的点击，从而不影响您的工作 -- “关闭”——可以一键关闭Airi - -### 系统托盘其他选项 - -首先，你需要找到Airi在任务栏的小图标 -（在windows平台可能需要你找到任务栏“显示隐藏的图标”点击展开才可以找到） - -右键Airi的小图标，你可以看到十个选项： -- “显示”——可以召唤主窗口，一般用不上 -- “调整大小”——可以调整主窗口的窗口大小，同时也会使主窗口居中。 -其中包括四个选项：“推荐（450x600）”——可以设置为推荐大小450x600； -“全高”——可以设置使主窗口的高占满桌面的高； -“半高”——可以设置使主窗口的高为桌面的高的一半； -“全屏”——可以设置使主窗口填满整个桌面。 -- “对齐到”——可以使主窗口对齐到桌面的特定位置。 -其中包含五个选项：“居中”——可以使主窗口对齐到桌面正中间； -“左上”——可以使主窗口对齐到桌面左上角； -“右上”——可以使主窗口对齐到桌面右上角； -“左下”——可以使主窗口对齐到桌面左下角； -“右下”——可以使主窗口对齐到桌面右下角。 -- “设置”——可以打开设置界面 -- “关于”——相关说明略 -- “打开快速操作”——相关说明暂略 -- “打开小部件”——相关说明暂略 -- “打开字幕”——可以打开字幕，只有启用TTS服务才能在Airi说话时显示出文字，默认鼠标光标悬停时隐藏 -- “字幕浮窗”，包含两个选项：“跟随窗口”，默认选中该模式，此时字幕窗口位置会跟随主窗口一起移动，取消选中则字幕位置独立； -“重置位置”，可以使字幕位置重置。 -- “退出”，可以一键关闭Airi - -
- -名词解释：（点击展开） - -* TTS - -TTS 是“文本转语音”（Text-to-Speech）的缩写，旨在让计算机将文字自动转换为自然流畅的语音输出。 - -
- -### 设置界面 - -[ *该部分仅介绍界面有什么，具体功能介绍见第四章* ] - -你可以通过主窗口点击“展开”找到打开设置的选项 -也可以通过右键系统托盘中的airi小图标找到打开设置的选项 - -在这里包括九大内容： - -- “AIRI角色卡”——可以选择和配置角色的人设 -- “机体模块”——可以配置Airi的各种功能， -包括意识、发声、听觉、视觉、短期记忆、长期记忆、Discord、X/twitter、我的世界、异星工厂、MCP服务器、同步音律 -- “场景”——功能暂未发布 -- “角色模型”——可以选择和设置角色的模型 -- “记忆体”——功能暂未发布 -- “服务来源”——可以配置LLM、TTS、STT服务的来源 -- “Data”——译为“数据”，可以管理Airi的各种数据 -- “连接”——可以配置您的WebSocket服务器地址 -- “系统”——里面包括四个选项：“通用”——可以设置程序主题、语言等内容； -“配色方案”——可以设置主题颜色； -“窗口快捷方式”——空 [ ***警告：由于该选项内没有任何内容也没有返回键，一旦点进去就需要“关掉并重新打开设置窗口”，所以请不要点击该选项！*** ]； -“开发者”——包含很多高级功能，详见第四章 - -### 聊天窗口 - -你可以通过主窗口点击“展开”找到打开聊天窗口的选项 - -在这里，你可以和Airi聊天 -详细介绍暂略 - -## 第四章·设置 - -你可以通过主窗口点击“展开”找到打开设置的选项 -也可以通过右键系统托盘中的airi小图标找到打开设置的选项 - -### AIRI角色卡 - -在这里，你可以上传、创建或者直接修改默认的角色卡。 - -关于上传，从弹出的窗口来看疑似支持任意文件，但是我没有用过，角色卡也没有导出功能，所以相关介绍略 - -关于创建新角色卡： -在这里，你可以设定角色的身份、行为、模块等内容 - -其中身份部分可以设定角色的名字、昵称、描述、创建者笔记。 -名字即角色正式的名称，如果设定了昵称，那么它会被优先使用。 -描述即关于人设具体的细节，你可以自由发挥，也可以参考默认角色卡 -（请注意：如果你选择参考默认角色卡编写自己角色的设定，其中后半部分关于ACT标签的内容可以不添加） -关于创建者笔记，我没用过，介绍暂略 - -行为部分可以设置角色性格、场景（或者理解为周围环境、背景、情境）、问候语，这个部分我没有调整过，介绍暂略 - -模块部分可以配置角色特定的机体模块，一般不用管，具体介绍略 - -设置部分可以配置系统提示词、历史提示指令、版本，其中版本是角色卡的版本，这部分前两项内容我没用过，具体介绍暂略 - -其中最主要的是身份部分的名字和描述，填完后点击“**创建**”即可完成角色卡的创建 - -最后，点击角色卡右下角的圈或者点击角色卡再点击激活即可启用你创建的角色卡 -[ ***请注意：创建角色卡后默认不启用，必须进行激活才可以启用*** ] - -### 机体模块 - -在这里可以配置Airi的各种功能，具体如下： - -#### 意识 - -首先选中一个服务来源或者添加一个新的服务来源并选中 -[ *如果可选的服务来源太多可能点不到位于后面的服务来源，这时候可以把鼠标光标移动到一个选项卡上按鼠标中键然后左右拖动即可解决问题* ] -接着选择一个模型并选中即完成配置 - -#### 发声 - -首先选中一个服务来源或者添加一个新的服务来源并选中 -[ *如果可选的服务来源太多可能点不到位于后面的服务来源，这时候可以把鼠标光标移动到一个选项卡上按鼠标中键然后左右拖动即可解决问题* ] -然后选择一个模型并选中 -接着选择一个声线并选中即可完成配置 -或者你也可以选择“无”不使Airi发声 - -在该页面的最下方可以输入文字测试声音，通过点击“**测试声音**”选项即可生成一段测试音频 - -[ 请注意：不同服务来源在该页面的配置流程可能略有不同，该处以阿里百炼为例，其他以实际为准 ] -[ 其中部分服务关于Pitch（即音调）的功能可能无效 ] - -其他内容说明暂略 - -#### 听觉 - -首先选择你的收音设备（Audio Input Device部分，该英文翻译为“音频输入设备”） -然后选中一个服务来源或者添加一个新的服务来源并选中 -[ *如果可选的服务来源太多可能点不到位于后面的服务来源，这时候可以把鼠标光标移动到一个选项卡上按鼠标中键然后左右拖动即可解决问题* ] -接着选择一个模型并选中即可完成配置 - -除此之外，你还可以启用Auto-send transcribed text（即“自动发送转录文本”）功能以实现自动发送， -或者默认关闭该功能则可以对转录结果进行调整（应该是这样，我没有成功调用过听觉） -同时还可以设置Auto-send delay（即“自动发送延迟”）来调整发送延迟。 - -在该界面的中间部分可以测试麦克风 -点击“**start monitoring**”选项即可开启监听 -你可以调整Sensitivity即灵敏度（我没试过，详细介绍略） - -在该界面的最下方可以测试STT功能 -点击“**start speech-to-text**”选项即可开始测试 -在Transcription Result下会显示结果 - -其他内容说明暂略 - -#### 视觉 - -首先选中一个服务来源或者添加一个新的服务来源并选中 -[ *如果可选的服务来源太多可能点不到位于后面的服务来源，这时候可以把鼠标光标移动到一个选项卡上按鼠标中键然后左右拖动即可解决问题* ] -接着选择一个模型并选中即完成配置 - -另外，你还可以设置Capture interval即“捕获间隔”来调整捕获的时间间隔 - -[ ***该功能需要到系统-开发者-vision capture处启动，具体介绍见对应部分*** ] - -其他内容说明暂略 - -#### 短期记忆 - -功能暂未发布 - -#### 长期记忆 - -功能暂未发布 - -#### Discord - -在这里你可以配置Discord机器人使airi进入你的discord服务器与人互动 -你需要获取你的Discord机器人令牌并输入对应位置然后完成配置。 - -**请注意：** -该功能需要使用Discord-bot，目前安装包版本暂未内置，需要您去github页面提取相关文件才可以使用， -由于目前我关于这个内容的日程还很靠后，所以具体教程暂略 - -#### X/twitter - -该功能需要使用bot才可以使用，具体教程暂略 - -#### 我的世界 minecraft - -该功能需要使用bot才可以使用，具体教程暂略 - -#### 异星工厂 factorio - -该功能需要使用bot才可以使用，具体教程暂略 - -#### MCP服务器 - -该功能我没用过，具体教程暂略 - -#### 同步音律 - -该功能我还在探索当中，具体教程暂略 - -### 场景 - -该功能暂未发布 - -### 角色模型 - -在这里你可以选择和设置角色的模型 - -airi支持的模型包括live2D模型和VRM 3D模型 - -点击“**select model**”选项可以选择模型，在该版本，默认包括两个live2D模型和两个VRM 3D模型可供选择 -选中一个并点击“**confirm**”选项即可切换模型 -另外，你还可以点击“**add**”选项导入自己的live2D模型或者VRM 3D模型 - -[ **请注意：旧版live2D模型不被支持！请选择包括“*.moc3”的文件！！！** ] -[ **导入live2D模型前，你需要先将“模型文件夹”压缩为“*.zip”文件才可以导入** ] - -- **如果你选择的是live2D模型** - -展开“缩放与位置”，你可以调整模型在主窗口中的大小和位置 -其中x为横轴（左右）位置，y为纵轴（上下）位置 - -展开“parameters（译为“参数”）”，你可以设置live2D模型鼠标追踪、Idle Animation（即“待机动画”）、帧率、Auto Blink（即“自动眨眼”）、 -Force Auto Blink (fallback timer)（即“强制自动闪烁（备用计时器）”）、Shadow（即“影子”）、 -reset to default parameters（译为：“重置为默认参数”）、clear model cache（译为“清除模型缓存”）、 -以及模型涉及的所有参数 -如果想要设置待机动画，请确保模型压缩包中包含动画文件 -其他相关内容介绍暂略 - -展开“Expressions（译为“表达”）”，你可以启用Expression System（译为“表达系统”） -该功能我还没有测试，介绍暂略 - -- **如果你选择的是VRM 3D模型** - -展开“场景”，你可以设置Model Position（译为“模型位置”）、视角调整（度）、相机距离（画面缩放）、模型朝向（Y轴旋转）、模型注视方向等内容 - -该部分内容包括下面的“更换模型”的相关介绍因为时间原因暂略 - -### 记忆体 - -功能暂未发布 - -### 服务来源 - -在这里，你可以配置LLM、TTS、STT的服务来源 - -该部分暂略 - -### Data - -在这里，你可以管理Airi的各种数据 - -［ ***请注意：该部分可以删除清理相关数据且无法恢复，请谨慎操作！！！*** ］ - -其中第一个方框中可以Open app data folder（译为“打开APP数据文件夹”） -点击“**Open folder**”选项即可打开 -[ *请注意：该功能目前有bug，会一次性把数据文件夹打开好几次* ] - -第二个方框中你可以导入导出聊天记录或者删除所有聊天会话 -（具体介绍略） - -第三个方框中你可以删除导入的所有模型或者重置模块偏好设置和凭据 -（具体介绍略） - -第四个方框中你可以重置桌面设置和状态 -（具体介绍略） - -第五个方框中你可以重置所有提供商设置和凭据或者清除每个本地设置、提供商配置和模型 -（具体介绍略） - -### 连接 - -在这里你可以配置您的WebSocket服务器地址 - -（具体介绍暂略） - -### 系统 - -#### 通用 - -在这里，你可以设置程序主题、语言等内容 - -主题选项默认亮色，点击后面的按钮可以切换到暗色模式 - -语言选项这里可以设置界面的语言 - -控制岛图标大小选项这里你可以更改主窗口右下角三个按键的大小 - -最后，你还可以设置是否允许收集使用数据及崩溃分析或者阅读隐私政策（点击“隐私政策”打开） - -#### 配色方案 - -在这里，你可以更改主题颜色 - -你可以启动RGB选项来使主题颜色像RGB灯带那样自动变化 -你也可以拖动下方的黑线或者在彩色条中点击来更改主题颜色 -在其下方是颜色效果预览 - -另外，你还可以直接选择下方的预设来改变主题颜色 -[ ***请注意：你应该点击任意一个圆而不是点击方框*** ] - -#### 窗口快捷方式 - -[ ***警告：由于该选项内没有任何内容也没有返回键，一旦点进去就需要“关掉并重新打开设置窗口”，所以请不要点击该选项！*** ] - -#### 开发者 - -在这里，你可以使用一些高级功能 - -[ **由于该部分内容大多为英文而且属于一般用不到的高级功能，所以该部分的介绍仅供参考！** ] - -- 在第一个方框中你可以点击“**打开**”以打开像浏览器F12那样的开发者工具窗口 - -- 第二个“Markdown 压力测试”功能介绍暂略 - -- 第三个“Lag 可视化”功能介绍暂略 - -- 第四个“是否开启舞台切换动画”功能介绍暂略 - -- 第五个“是否使用页面特定过场动画”功能介绍暂略 - -##### useMagicKeys 工具 - -空白 -暂略 - -##### useElectronWindowMouse - -这里可以检测鼠标光标在电脑屏幕上的位置 - -##### Displays - -这里可以可视化鼠标光标在电脑屏幕上的位置 - -##### widgets calling - -译为“小组件调用” -暂略 - -##### Context Flow - -译为“上下文流程” -实时检查传入的上下文更新（服务器 + 广播）和传出的聊天钩子。 -使用此方法验证插件上下文（例如 VSCode 编码上下文）如何传入聊天管道并传出到服务器事件。 -暂略 - -##### relative mouse - -这里可以可视化鼠标光标在该窗口上的位置 - -##### beat sync visualizer - -译为“节拍同步可视化器”即同步音律 -暂略 - -##### WebSocket Inspector - -即“WebSocket 检查器” -暂略 - -##### Plugin Host Debug - -译为“插件主机调试” -暂略 - -##### Screen Capture - -译为“屏幕截图” -在这里你可以捕获任意应用程序窗口或者整个屏幕 -在最上方有四个选项： -“applications”——译为“应用程序”，可以选择捕获任意一个打开的应用程序的任意一个窗口，点击“**share window**”选项即可在页面最上方查看， -在页面最上方将鼠标指针移动到捕获界面上点击“stop”即可停止捕获 -“displays”——可以捕获整个屏幕，点击“**share screen**”选项即可在页面最上方查看，在页面最上方将鼠标指针移动到捕获界面上点击“stop”即可停止捕获 -“devices”——译为“设备”，略 -“refetch”——译为“重新获取”，略 - -##### vision capture - -译为“视觉捕捉” -具体介绍暂略 diff --git a/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-airi-card.avif b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-airi-card.avif new file mode 100644 index 000000000..a6fd61681 Binary files /dev/null and b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-airi-card.avif differ diff --git a/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-chat-window.avif b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-chat-window.avif new file mode 100644 index 000000000..05d1e9032 Binary files /dev/null and b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-chat-window.avif differ diff --git a/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-consciousness.avif b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-consciousness.avif new file mode 100644 index 000000000..fe5ee4fe1 Binary files /dev/null and b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-consciousness.avif differ diff --git a/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-controls-island-expanded.avif b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-controls-island-expanded.avif new file mode 100644 index 000000000..b7dafd0c5 Binary files /dev/null and b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-controls-island-expanded.avif differ diff --git a/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-data-settings.avif b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-data-settings.avif new file mode 100644 index 000000000..088b96ecd Binary files /dev/null and b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-data-settings.avif differ diff --git a/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-beat-sync.avif b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-beat-sync.avif new file mode 100644 index 000000000..9531f2baa Binary files /dev/null and b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-beat-sync.avif differ diff --git a/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-context-flow.avif b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-context-flow.avif new file mode 100644 index 000000000..0619480da Binary files /dev/null and b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-context-flow.avif differ diff --git a/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-displays.avif b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-displays.avif new file mode 100644 index 000000000..b343ff0b7 Binary files /dev/null and b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-displays.avif differ diff --git a/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-plugin-host.avif b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-plugin-host.avif new file mode 100644 index 000000000..6e823bac8 Binary files /dev/null and b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-plugin-host.avif differ diff --git a/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-relative-mouse.avif b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-relative-mouse.avif new file mode 100644 index 000000000..9386d0eda Binary files /dev/null and b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-relative-mouse.avif differ diff --git a/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-screen-capture.avif b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-screen-capture.avif new file mode 100644 index 000000000..06ab8510c Binary files /dev/null and b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-screen-capture.avif differ diff --git a/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-use-window-mouse.avif b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-use-window-mouse.avif new file mode 100644 index 000000000..16d654fd0 Binary files /dev/null and b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-use-window-mouse.avif differ diff --git a/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-vision-capture.avif b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-vision-capture.avif new file mode 100644 index 000000000..4a646c191 Binary files /dev/null and b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-vision-capture.avif differ diff --git a/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-websocket-inspector.avif b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-websocket-inspector.avif new file mode 100644 index 000000000..8e5bfd83a Binary files /dev/null and b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-websocket-inspector.avif differ diff --git a/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-widgets-calling.avif b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-widgets-calling.avif new file mode 100644 index 000000000..909c95eec Binary files /dev/null and b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-devtools-widgets-calling.avif differ diff --git a/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-hearing.avif b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-hearing.avif new file mode 100644 index 000000000..9bf562f1b Binary files /dev/null and b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-hearing.avif differ diff --git a/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-main-window.avif b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-main-window.avif new file mode 100644 index 000000000..f7e4fc974 Binary files /dev/null and b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-main-window.avif differ diff --git a/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-models.avif b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-models.avif new file mode 100644 index 000000000..8946953c4 Binary files /dev/null and b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-models.avif differ diff --git a/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-modules.avif b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-modules.avif new file mode 100644 index 000000000..836b0d088 Binary files /dev/null and b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-modules.avif differ diff --git a/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-providers.avif b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-providers.avif new file mode 100644 index 000000000..2db9d78e0 Binary files /dev/null and b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-providers.avif differ diff --git a/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-settings-window.avif b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-settings-window.avif new file mode 100644 index 000000000..380acfcd7 Binary files /dev/null and b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-settings-window.avif differ diff --git a/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-speech.avif b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-speech.avif new file mode 100644 index 000000000..ed2ac2fde Binary files /dev/null and b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-speech.avif differ diff --git a/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-system-color-scheme.avif b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-system-color-scheme.avif new file mode 100644 index 000000000..cf83c6cbe Binary files /dev/null and b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-system-color-scheme.avif differ diff --git a/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-system-developer.avif b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-system-developer.avif new file mode 100644 index 000000000..135057923 Binary files /dev/null and b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-system-developer.avif differ diff --git a/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-system-general.avif b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-system-general.avif new file mode 100644 index 000000000..8b3ae7d82 Binary files /dev/null and b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-system-general.avif differ diff --git a/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-vision.avif b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-vision.avif new file mode 100644 index 000000000..9c4bbdfba Binary files /dev/null and b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-vision.avif differ diff --git a/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-websocket-settings.avif b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-websocket-settings.avif new file mode 100644 index 000000000..b62cf3f73 Binary files /dev/null and b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/assets/manual-websocket-settings.avif differ diff --git a/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/index.md b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/index.md new file mode 100644 index 000000000..15be1a6f0 --- /dev/null +++ b/docs/content/zh-Hans/docs/manual/tamagotchi/setup-and-use/index.md @@ -0,0 +1,648 @@ +# Project AIRI 说明书 + +编写时间：（北京时间）2026 年 4 月 2 日 - 晚上 + +对应版本：AIRI-0.9.0-beta.4-windows-x64 + +::: info 编写信息 +主编团队：沐玖芸萱（MuGewRayce） + +参与编辑者：JhIcefair（主要） +::: + +::: warning 阅读前说明 +- 目前关于 AIRI 的部分技术性功能和操作在该说明书中不会具体讲解。 +- 主要编辑者仅对说明书的中文版本负责，其他语言版本目前采用 AI 翻译，而后人工简单修正的方式处理，可能与实际显示的内容不符，请以实际为准。 +- 说明书的大部分内容为主编团队成员自己探索研究出来的，可能与事实不符或者存在偏差，具体请以自己实际体验到的为准。 +- 该说明书可能不会及时更新。 +- 因能力和时间有限，该说明书暂仅包含 Windows 平台通过安装包安装的 AIRI 的部分详细教程。 +- 软件部分位置使用的是英文而且并没有提供翻译，该说明书会尝试翻译涉及到的部分内容，最终译文请以实际为准。 +- AIRI 的版本更新可能会改变部分内容，该说明书仅介绍编写时间前最新的一个版本的特性，对于前后其他版本的程序，如果遇到不同的地方，请自行解决。 +- 如果您有想要添加的说明或者对该说明书有什么疑问，请在 Project AIRI 官方 Discord 频道上 @jhicefair 并留言。 +- 如果您还有别的什么问题，请在 Project AIRI 官方 Discord 频道上留言。 +- 祝您玩的开心！AwA +::: + +## 目录 + +- [第一章·安装](#chapter-1-installation) +- [第二章·初步配置](#chapter-2-initial-configuration) + - [第一项·先前准备](#chapter-2-prerequisites) + - [第二项·Airi 启动！](#chapter-2-launch) +- [第三章·Airi 界面介绍](#chapter-3-interface-overview) + - [主窗口](#chapter-3-main-window) + - [系统托盘其他选项](#chapter-3-system-tray) + - [设置界面](#chapter-3-settings-overview) + - [聊天窗口](#chapter-3-chat-window) +- [第四章·设置](#chapter-4-settings) + - [AIRI 角色卡](#chapter-4-airi-card) + - [机体模块](#chapter-4-modules) + - [场景](#chapter-4-stage) + - [角色模型](#chapter-4-character-model) + - [记忆体](#chapter-4-memory-bank) + - [服务来源](#chapter-4-providers) + - [数据（Data）](#chapter-4-data) + - [连接](#chapter-4-connection) + - [系统](#chapter-4-system) + + +## 第一章·安装 + +找到 Project AIRI GitHub 主页：[moeru-ai/airi](https://github.com/moeru-ai/airi) + +建议按下面的步骤操作： + +1. 找到位于页面右侧的「**Releases**」选项。 +2. 点击「+ 68 releases」。 +3. 挑一个版本，找到下面的「**Assets**」选项并点开。 +4. 选择适合自己电脑的版本点击下载。 +5. 找到你下载下来的安装包，双击左键安装。 + +::: tip 下载页面提示 +- 「+ 68 releases」中间的数字代表已发布的其他版本数量，你看到的数字可能不是 68。 +- 由于可选内容较多，你可能还需要点击列表最下方的「Show all 19 assets」；这里的数字同样可能不是 19。 +- 以下均以 Windows 安装包版本为例。 +- 安装过程因时间原因暂跳过，相信你自己可以解决。 +::: + + +## 第二章·初步配置 + + +### 第一项·先前准备 + +在一切正式开始前，你需要首先至少准备一个 LLM 服务提供商的 API。 + +::: info 名词解释 +* LLM + +LLM 是「大型语言模型」（Large Language Model）的缩写。 +通俗点讲，一个 AI。 + +* API + +API 全称是应用程序编程接口。 +它本质上是一套预先定义好的规则，让不同的软件应用之间可以相互通信、交换数据和功能。 +你可以不用去理解他到底是什么，只要会获取就行。 +::: + +::: tip 获取 API +LLM 提供商有很多，而且它们的获取方式各不相同。由于篇幅和时间原因，这里不提供教程或者举例，具体如何获取你可以去网络上搜索或者询问 AI。 +::: + +::: warning API 安全 +获取好 API 后请注意保存好，而且不要告诉其他人！ +::: + + +### 第二项·Airi 启动！ + +::: info 本节示例 +下面的步骤以 Deepseek 为例进行演示。 +::: + +::: tip 界面翻译说明 +「setup with your provider」的意思是「设置您的提供商」。 +::: + +建议按下面的步骤完成初始配置： + +1. 打开 Airi（正常情况下安装后会默认自动打开）。 +2. 在弹出的主界面选择你的语言。 +3. 点击「**setup with your provider**」。 +4. 选中你准备的服务来源，然后点击「**下一步**」。 +5. 填入你的 API Key，然后点击「**下一步**」。 +6. 再点击一次「**下一步**」。 +7. 选择你打算使用的模型，然后点击「**保存并继续**」。 + +恭喜你，不出意外的话你已经完成了 Airi 的初步配置！ + + +## 第三章·Airi 界面介绍 + + +### 主窗口 + +该窗口是展示虚拟角色形象的窗口，共有四个选项： + +- 「websocket 状态」——位于右上角，点击可打开连接设置，在这里你可以配置你的 WebSocket 服务器地址。 +- 「展开」——位于右下角，点击可展开更多选项（见下文）。 +- 「打开听力控制」——位于右下角，点击后可以与 Airi 说话，需要提前配置 STT 服务。 +- 「移动」——位于右下角，鼠标左键长按并拖动即可改变主窗口在桌面上的位置。 + +![Airi 主窗口示意图](./assets/manual-main-window.avif) + +::: info 听力控制补充 +打开听力控制好像还需要先打开聊天窗口。由于该功能在编辑者这里暂未成功运行，相关教程暂略。 +::: + +::: info 名词解释 +* websocket + +WebSocket 是一种网络通信协议，提供了浏览器与服务器之间的全双工、持久连接。 +简单理解就是传统的 HTTP 是「一问一答」模式（客户端请求，服务器响应，然后断开）， +而 WebSocket 建立连接后，双方可以随时互相发送消息，无需重复发起请求。 + +* STT + +STT 是「语音转文本」（Speech-to-Text）的缩写，也称自动语音识别（ASR）。 +它的目标是让计算机听懂人类的语音，并将其转换成对应的文字。 +::: + +点击「展开」选项展开后有八个子选项： + +- 「打开设置」——打开 Airi 的设置界面。 +- 「切换角色」——切换角色卡。 +- 「打开聊天」——打开聊天窗口。 +- 「刷新」——刷新主窗口。 +- 「切换到暗色模式」——切换 Airi 的界面背景为「亮 / 暗」。 +- 「取消置顶」——使 Airi 主窗口不再保持置顶显示。 +- 「总是显示」/「悬停时隐藏」——使 Airi 主窗口不影响鼠标光标对窗口下内容的点击，从而不影响你的工作。 +- 「关闭」——一键关闭 Airi。 + +![Airi 主窗口展开后的控制菜单](./assets/manual-controls-island-expanded.avif) + + +### 系统托盘其他选项 + +首先，你需要找到 Airi 在任务栏的小图标。 + +::: tip Windows 任务栏提示 +在 Windows 平台，可能需要在任务栏点击「显示隐藏的图标」展开后才能找到 Airi 图标。 +::: + +右键 Airi 的小图标，你可以看到十个选项： + +- 「显示」——召唤主窗口，一般用不上。 +- 「调整大小」——调整主窗口的窗口大小，同时也会使主窗口居中。包含四个子选项： + - 「推荐（450x600）」——设置为推荐大小 450x600。 + - 「全高」——使主窗口的高占满桌面的高。 + - 「半高」——使主窗口的高为桌面的高的一半。 + - 「全屏」——使主窗口填满整个桌面。 +- 「对齐到」——使主窗口对齐到桌面的特定位置。包含五个子选项： + - 「居中」——对齐到桌面正中间。 + - 「左上」——对齐到桌面左上角。 + - 「右上」——对齐到桌面右上角。 + - 「左下」——对齐到桌面左下角。 + - 「右下」——对齐到桌面右下角。 +- 「设置」——打开设置界面。 +- 「关于」——相关说明略。 +- 「打开快速操作」——相关说明暂略。 +- 「打开小部件」——相关说明暂略。 +- 「打开字幕」——打开字幕。只有启用 TTS 服务才能在 Airi 说话时显示出文字，默认鼠标光标悬停时隐藏。 +- 「字幕浮窗」——包含两个子选项： + - 「跟随窗口」——默认选中该模式，此时字幕窗口位置会跟随主窗口一起移动；取消选中则字幕位置独立。 + - 「重置位置」——使字幕位置重置。 +- 「退出」——一键关闭 Airi。 + +::: info 名词解释 +* TTS + +TTS 是「文本转语音」（Text-to-Speech）的缩写，旨在让计算机将文字自动转换为自然流畅的语音输出。 +::: + + +### 设置界面 + +::: info 本节范围 +该部分仅介绍界面里有什么，具体功能介绍见第四章。 +::: + +你可以通过以下两种方式打开设置界面： + +- 在主窗口点击「展开」，然后选择「打开设置」。 +- 右键系统托盘中的 Airi 小图标，选择「设置」。 + +设置界面包括以下九大内容： + +- 「AIRI 角色卡」——选择和配置角色的人设。 +- 「机体模块」——配置 Airi 的各种功能，包括意识、发声、听觉、视觉、短期记忆、长期记忆、Discord、X / Twitter、我的世界、异星工厂、MCP 服务器、同步音律。 +- 「场景」——功能暂未发布。 +- 「角色模型」——选择和设置角色的模型。 +- 「记忆体」——功能暂未发布。 +- 「服务来源」——配置 LLM、TTS、STT 服务的来源。 +- 「Data」——译为「数据」，管理 Airi 的各种数据。 +- 「连接」——配置你的 WebSocket 服务器地址。 +- 「系统」——里面包括四个子选项： + - 「通用」——设置程序主题、语言等内容。 + - 「配色方案」——设置主题颜色。 + - 「窗口快捷方式」——当前为空，且没有返回键。 + - 「开发者」——包含很多高级功能，详见第四章。 + +::: warning 不要打开「窗口快捷方式」 +该选项当前没有任何内容，也没有返回键。一旦点进去，就需要「关掉并重新打开设置窗口」才能退出。 +::: + +![Airi 设置界面总览](./assets/manual-settings-window.avif) + + +### 聊天窗口 + +你可以在主窗口点击「展开」，然后选择「打开聊天」来打开聊天窗口。 + +![Airi 聊天窗口界面](./assets/manual-chat-window.avif) + +在这里，你可以和 Airi 聊天。 + + +## 第四章·设置 + +你可以通过以下两种方式打开设置界面： + +- 在主窗口点击「展开」，然后选择「打开设置」。 +- 右键系统托盘中的 Airi 小图标，选择「设置」。 + + +### AIRI 角色卡 + +在这里，你可以上传、创建或者直接修改默认的角色卡。 + +![Airi 角色卡设置界面](./assets/manual-airi-card.avif) + +::: info 关于上传 +从弹出的窗口来看，上传入口疑似支持任意文件类型。但编辑者没有实际使用过，而且角色卡也没有导出功能，因此相关介绍略。 +::: + +关于创建新角色卡，建议按下面的顺序配置： + +1. 先填写身份部分，包括名字、昵称、描述、创建者笔记。 +2. 再根据需要填写行为部分，包括角色性格、场景（或者理解为周围环境、背景、情境）和问候语。 +3. 如果需要，再调整模块部分，为角色配置特定的机体模块。 +4. 最后检查设置部分，包括系统提示词、历史提示指令和版本。 +5. 确认内容无误后，点击「**创建**」完成角色卡创建。 +6. 创建完成后，点击角色卡右下角的圈，或者点击角色卡后再点击激活，正式启用这个角色卡。 + +其中身份部分最重要的是名字和描述： + +- 名字即角色正式的名称，如果设定了昵称，那么昵称会被优先使用。 +- 描述即关于人设具体的细节，你可以自由发挥，也可以参考默认角色卡。 + +::: info 编辑者补充 +- 如果你选择参考默认角色卡编写自己角色的设定，其中后半部分关于 ACT 标签的内容可以不添加。 +- 创建者笔记编辑者暂未使用过，介绍暂略。 +- 行为部分、模块部分和设置部分编辑者也还没有完整测试，这里只先说明它们的大致作用。 +::: + +::: warning 需要手动激活 +创建角色卡后默认不会启用，必须手动激活才可以使用。 +::: + + +### 机体模块 + +在这里可以配置 Airi 的各种功能，具体如下： + +![Airi 机体模块设置界面](./assets/manual-modules.avif) + +#### 意识 + +建议按下面的步骤完成配置： + +1. 先选中一个服务来源，或者添加一个新的服务来源并选中。 +2. 再选择一个模型并选中。 + +::: tip 服务来源过多时 +如果可选的服务来源太多，可能点不到位于后面的服务来源。这时候可以把鼠标光标移动到一个选项卡上，按鼠标中键后左右拖动。 +::: + +![Airi 意识设置界面](./assets/manual-consciousness.avif) + +#### 发声 + +::: tip 发声页补充说明 +- 不同服务来源在该页面的配置流程可能略有不同，该处以阿里百炼为例，其他以实际界面为准。 +- 其中部分服务关于 Pitch（即音调）的功能可能无效。 +- 如果可选的服务来源太多，可能点不到位于后面的服务来源。这时候可以把鼠标光标移动到一个选项卡上，按鼠标中键后左右拖动。 +::: + +建议按下面的步骤完成配置： + +1. 先选中一个服务来源，或者添加一个新的服务来源并选中。 +2. 然后选择一个模型并选中。 +3. 接着选择一个声线并选中。 +4. 如果你不想让 Airi 发声，也可以直接选择「无」。 +5. 完成基础配置后，你还可以在页面最下方输入文字，通过点击「**测试声音**」生成一段测试音频。 + +![Airi 发声设置界面](./assets/manual-speech.avif) + +#### 听觉 + +::: tip 服务来源过多时 +如果可选的服务来源太多，可能点不到位于后面的服务来源。这时候可以把鼠标光标移动到一个选项卡上，按鼠标中键后左右拖动。 +::: + +建议按下面的步骤完成配置： + +1. 先选择你的收音设备（Audio Input Device，译为「音频输入设备」）。 +2. 然后选中一个服务来源，或者添加一个新的服务来源并选中。 +3. 接着选择一个模型并选中。 + +![Airi 听觉设置界面](./assets/manual-hearing.avif) + +除此之外，你还可以： + +- 启用 Auto-send transcribed text（即「自动发送转录文本」）功能以实现自动发送。 +- 关闭该功能则可以对转录结果进行调整。 +- 通过 Auto-send delay（即「自动发送延迟」）调整发送延迟。 + +::: info 编辑者补充 +上面关于「关闭自动发送可以调整转录结果」的说法是编辑者的推测，因为编辑者没有成功调用过听觉功能。 +::: + +如果你想测试麦克风： + +1. 在界面的中间部分点击「**start monitoring**」开启监听。 +2. 如果需要，可以再调整 Sensitivity，即灵敏度。 + +如果你想测试 STT 功能： + +1. 在界面的最下方点击「**start speech-to-text**」开始测试。 +2. 然后在 Transcription Result 下查看识别结果。 + +#### 视觉 + +::: tip 服务来源过多时 +如果可选的服务来源太多，可能点不到位于后面的服务来源。这时候可以把鼠标光标移动到一个选项卡上，按鼠标中键后左右拖动。 +::: + +建议按下面的步骤完成配置： + +1. 先选中一个服务来源，或者添加一个新的服务来源并选中。 +2. 接着选择一个模型并选中。 +3. 如需要可以设置 Capture interval，即「捕获间隔」，用来调整捕获的时间间隔。 + +![Airi 视觉设置界面](./assets/manual-vision.avif) + +::: warning 需要先启用 vision capture +该功能需要先到「系统 → 开发者 → vision capture」处启动，具体介绍见对应部分。 +::: + +#### 短期记忆 + +功能暂未发布。 + +#### 长期记忆 + +功能暂未发布。 + +#### Discord + +在这里你可以配置 Discord 机器人，使 Airi 进入你的 Discord 服务器与人互动。 + +建议按下面的顺序准备： + +1. 先获取你的 Discord 机器人令牌。 +2. 再把它填写到对应位置。 +3. 最后按界面提示完成配置。 + +::: warning Discord 机器人说明 +该功能需要使用 Discord 机器人，目前安装包版本暂未内置，需要你去 GitHub 页面提取相关文件才可以使用。由于编辑者关于这部分内容的日程还很靠后，具体教程暂略。 +::: + +#### X / Twitter + +该功能需要使用机器人才可以使用，具体教程暂略。 + +#### 我的世界（Minecraft） + +该功能需要使用机器人才可以使用，具体教程暂略。 + +#### 异星工厂（Factorio） + +该功能需要使用机器人才可以使用，具体教程暂略。 + +#### MCP 服务器 + +该功能编辑者没用过，具体教程暂略。 + +#### 同步音律 + +该功能编辑者还在探索当中，具体教程暂略。 + + +### 场景 + +功能暂未发布。 + + +### 角色模型 + +在这里你可以选择和设置角色的模型。 + +![Airi 角色模型设置界面](./assets/manual-models.avif) + +Airi 支持的模型包括 Live2D 模型和 VRM 3D 模型。 + +如果你只是想切换现有模型，建议按下面的步骤操作： + +1. 点击「**select model**」打开模型选择界面。 +2. 在当前版本中，默认可以看到两个 Live2D 模型和两个 VRM 3D 模型。 +3. 选中一个模型后，点击「**confirm**」完成切换。 + +如果你想导入自己的模型，可以点击「**add**」导入自己的 Live2D 模型或者 VRM 3D 模型。 + +::: warning 导入模型前请注意 +- 旧版 Live2D 模型不被支持，请选择包括「\*.moc3」的文件。 +- 导入 Live2D 模型前，你需要先将「模型文件夹」压缩为「\*.zip」文件才可以导入。 +::: + +#### 如果你选择的是 Live2D 模型 + +你可以继续按下面的顺序调整： + +1. 展开「缩放与位置」，调整模型在主窗口中的大小和位置。其中 x 为横轴（左右）位置，y 为纵轴（上下）位置。 +2. 展开「parameters」（译为「参数」），继续设置鼠标追踪、Idle Animation（即「待机动画」）、帧率、Auto Blink（即「自动眨眼」）、Force Auto Blink (fallback timer)（即「强制自动闪烁（备用计时器）」）、Shadow（即「影子」）、reset to default parameters（译为「重置为默认参数」）、clear model cache（译为「清除模型缓存」）以及模型涉及的所有参数。 +3. 如果想要设置待机动画，请确保模型压缩包中包含动画文件。 +4. 如果还需要表情功能，可以再展开「Expressions」（译为「表达」）启用 Expression System（译为「表达系统」）。 + +::: info 编辑者补充 +该功能编辑者也还没有完整测试，其他相关内容介绍暂略。 +::: + +#### 如果你选择的是 VRM 3D 模型 + +你可以先展开「场景」，然后设置 Model Position（译为「模型位置」）、视角调整（度）、相机距离（画面缩放）、模型朝向（Y 轴旋转）、模型注视方向等内容。 + +::: info 编辑者补充 +该部分内容以及下面的「更换模型」介绍因为时间原因暂略。 +::: + + +### 记忆体 + +功能暂未发布。 + + +### 服务来源 + +在这里，你可以配置 LLM、TTS、STT 的服务来源。 + +![Airi 服务来源设置界面](./assets/manual-providers.avif) + +::: info 编辑者补充 +该部分介绍暂略。 +::: + + +### 数据（Data） + +在这里，你可以管理 Airi 的各种数据。 + +![Airi 数据设置界面](./assets/manual-data-settings.avif) + +::: warning 不可恢复操作 +该部分可以删除或清理相关数据，而且无法恢复，请谨慎操作。在执行删除和重置操作前，建议先再确认一遍内容。 +::: + +::: tip 已知问题 +「打开 APP 数据文件夹」目前有 Bug，可能会一次性把数据文件夹打开好几次。 +::: + +建议按方框分区理解： + +1. 第一个方框包含 Open app data folder（译为「打开 APP 数据文件夹」），点击「**Open folder**」即可打开。 +2. 第二个方框可以导入 / 导出聊天记录，或者删除所有聊天会话。 +3. 第三个方框可以删除导入的所有模型，或者重置模块偏好设置和凭据。 +4. 第四个方框可以重置桌面设置和状态。 +5. 第五个方框可以重置所有提供商设置和凭据，或者清除每个本地设置、提供商配置和模型。 + + +### 连接 + +在这里你可以配置你的 WebSocket 服务器地址。 + +![Airi 连接设置界面](./assets/manual-websocket-settings.avif) + +::: info 编辑者补充 +具体介绍暂略。 +::: + + +### 系统 + +#### 通用 + +在这里，你可以设置程序主题、语言等内容。 + +![Airi 系统通用设置界面](./assets/manual-system-general.avif) + +- 主题选项默认亮色，点击后面的按钮可以切换到暗色模式。 +- 语言选项这里可以设置界面的语言。 +- 控制岛图标大小选项可以更改主窗口右下角三个按键的大小。 +- 最后，你还可以设置是否允许收集使用数据及崩溃分析，或者阅读隐私政策（点击「隐私政策」打开）。 + +#### 配色方案 + +在这里，你可以更改主题颜色。 + +![Airi 配色方案设置界面](./assets/manual-system-color-scheme.avif) + +- 你可以启动 RGB 选项来使主题颜色像 RGB 灯带那样自动变化。 +- 你也可以拖动下方的黑线或者在彩色条中点击来更改主题颜色。 +- 在其下方是颜色效果预览。 +- 你也可以直接选择下方的预设来改变主题颜色。 + +::: tip 颜色预设 +这里应该点击任意一个圆，而不是点击方框。 +::: + +#### 窗口快捷方式 + +::: warning 请勿打开 +由于该选项内没有任何内容也没有返回键，一旦点进去就需要「关掉并重新打开设置窗口」，所以请不要点击该选项。 +::: + +#### 开发者 + +在这里，你可以使用一些高级功能。 + +![Airi 开发者设置界面](./assets/manual-system-developer.avif) + +::: info 高级功能说明 +该部分内容大多为英文，而且属于一般用不到的高级功能，因此下面的介绍仅供参考。 +::: + +第一个方框及其相关选项： + +- 第一个方框中你可以点击「**打开**」以打开像浏览器 F12 那样的开发者工具窗口。 +- 第二个「Markdown 压力测试」功能介绍暂略。 +- 第三个「Lag 可视化」功能介绍暂略。 +- 第四个「是否开启舞台切换动画」功能介绍暂略。 +- 第五个「是否使用页面特定过场动画」功能介绍暂略。 + +##### useMagicKeys 工具 + +::: info 编辑者补充 +页面当前为空白，介绍暂略。 +::: + +##### useElectronWindowMouse + +这里可以检测鼠标光标在电脑屏幕上的位置。 + +![Airi useElectronWindowMouse 工具界面](./assets/manual-devtools-use-window-mouse.avif) + +##### Displays + +这里可以可视化鼠标光标在电脑屏幕上的位置。 + +![Airi Displays 工具界面](./assets/manual-devtools-displays.avif) + +##### widgets calling + +译为「小组件调用」。 + +![Airi widgets calling 工具界面](./assets/manual-devtools-widgets-calling.avif) + +##### Context Flow + +译为「上下文流程」。实时检查传入的上下文更新（服务器 + 广播）和传出的聊天钩子。使用此方法验证插件上下文（例如 VSCode 编码上下文）如何传入聊天管道并传出到服务器事件。 + +![Airi Context Flow 工具界面](./assets/manual-devtools-context-flow.avif) + +##### relative mouse + +这里可以可视化鼠标光标在该窗口上的位置。 + +![Airi relative mouse 工具界面](./assets/manual-devtools-relative-mouse.avif) + +##### beat sync visualizer + +译为「节拍同步可视化器」，即同步音律。 + +![Airi beat sync visualizer 工具界面](./assets/manual-devtools-beat-sync.avif) + +##### WebSocket Inspector + +即「WebSocket 检查器」。 + +![Airi WebSocket Inspector 工具界面](./assets/manual-devtools-websocket-inspector.avif) + +##### Plugin Host Debug + +译为「插件主机调试」。 + +![Airi Plugin Host Debug 工具界面](./assets/manual-devtools-plugin-host.avif) + +##### Screen Capture + +译为「屏幕截图」。 + +如果你还没有授予系统级的屏幕捕获权限，那么首先会看到下图这样的权限提示窗口。完成授权后，才可以开始捕获任意应用程序窗口或者整个屏幕。 + +在最上方有四个选项： + +- 「applications」——译为「应用程序」，可以选择捕获任意一个打开的应用程序的任意一个窗口，点击「**share window**」即可在页面最上方查看；将鼠标指针移动到捕获界面上点击「stop」即可停止捕获。 +- 「displays」——可以捕获整个屏幕，点击「**share screen**」即可在页面最上方查看；将鼠标指针移动到捕获界面上点击「stop」即可停止捕获。 +- 「devices」——译为「设备」，略。 +- 「refetch」——译为「重新获取」，略。 + +![Airi Screen Capture 工具界面](./assets/manual-devtools-screen-capture.avif) + +##### vision capture + +译为「视觉捕捉」。 + +如果还没有授予屏幕捕获权限，这里同样会先显示权限提示。完成授权后，才可以让该页面真正开始捕获画面并查看视觉处理结果。 + +![Airi vision capture 工具界面](./assets/manual-devtools-vision-capture.avif) diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/final/intro-chat-window.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/intro-chat-window.avif index 16889d0ca..6add8977c 100644 Binary files a/packages/scenarios-stage-tamagotchi-browser/artifacts/final/intro-chat-window.avif and b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/intro-chat-window.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-airi-card.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-airi-card.avif new file mode 100644 index 000000000..2de9ad235 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-airi-card.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-chat-window.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-chat-window.avif new file mode 100644 index 000000000..05d1e9032 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-chat-window.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-consciousness.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-consciousness.avif new file mode 100644 index 000000000..fe5ee4fe1 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-consciousness.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-controls-island-expanded.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-controls-island-expanded.avif new file mode 100644 index 000000000..c1f505996 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-controls-island-expanded.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-data-settings.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-data-settings.avif new file mode 100644 index 000000000..088b96ecd Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-data-settings.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-devtools-beat-sync.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-devtools-beat-sync.avif new file mode 100644 index 000000000..9531f2baa Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-devtools-beat-sync.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-devtools-context-flow.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-devtools-context-flow.avif new file mode 100644 index 000000000..0619480da Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-devtools-context-flow.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-devtools-displays.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-devtools-displays.avif new file mode 100644 index 000000000..b343ff0b7 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-devtools-displays.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-devtools-plugin-host.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-devtools-plugin-host.avif new file mode 100644 index 000000000..6e823bac8 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-devtools-plugin-host.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-devtools-relative-mouse.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-devtools-relative-mouse.avif new file mode 100644 index 000000000..9386d0eda Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-devtools-relative-mouse.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-devtools-screen-capture.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-devtools-screen-capture.avif new file mode 100644 index 000000000..06ab8510c Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-devtools-screen-capture.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-devtools-use-window-mouse.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-devtools-use-window-mouse.avif new file mode 100644 index 000000000..16d654fd0 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-devtools-use-window-mouse.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-devtools-vision-capture.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-devtools-vision-capture.avif new file mode 100644 index 000000000..4a646c191 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-devtools-vision-capture.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-devtools-websocket-inspector.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-devtools-websocket-inspector.avif new file mode 100644 index 000000000..8e5bfd83a Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-devtools-websocket-inspector.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-devtools-widgets-calling.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-devtools-widgets-calling.avif new file mode 100644 index 000000000..909c95eec Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-devtools-widgets-calling.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-hearing.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-hearing.avif new file mode 100644 index 000000000..9bf562f1b Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-hearing.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-main-window.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-main-window.avif new file mode 100644 index 000000000..e949e8b56 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-main-window.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-models.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-models.avif new file mode 100644 index 000000000..8946953c4 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-models.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-modules.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-modules.avif new file mode 100644 index 000000000..55be43010 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-modules.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-providers.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-providers.avif new file mode 100644 index 000000000..9b579d202 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-providers.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-settings-window.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-settings-window.avif new file mode 100644 index 000000000..380acfcd7 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-settings-window.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-speech.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-speech.avif new file mode 100644 index 000000000..ed2ac2fde Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-speech.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-system-color-scheme.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-system-color-scheme.avif new file mode 100644 index 000000000..84f2064b1 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-system-color-scheme.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-system-developer.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-system-developer.avif new file mode 100644 index 000000000..93f902b41 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-system-developer.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-system-general.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-system-general.avif new file mode 100644 index 000000000..8b3ae7d82 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-system-general.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-vision.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-vision.avif new file mode 100644 index 000000000..9c4bbdfba Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-vision.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-websocket-settings.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-websocket-settings.avif new file mode 100644 index 000000000..b62cf3f73 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/final/manual-websocket-settings.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/00-stage-tamagotchi.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/00-stage-tamagotchi.avif index 94ca71af1..02ddab7c0 100644 Binary files a/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/00-stage-tamagotchi.avif and b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/00-stage-tamagotchi.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/01-controls-island-expanded.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/01-controls-island-expanded.avif index 25ac17345..6ab6a873f 100644 Binary files a/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/01-controls-island-expanded.avif and b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/01-controls-island-expanded.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/02-settings-window.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/02-settings-window.avif index bece586f0..5938a7a16 100644 Binary files a/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/02-settings-window.avif and b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/02-settings-window.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/03-websocket-settings.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/03-websocket-settings.avif index f7c0ec0c2..719188b55 100644 Binary files a/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/03-websocket-settings.avif and b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/03-websocket-settings.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/04-chat-window.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/04-chat-window.avif new file mode 100644 index 000000000..2178f7b55 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/04-chat-window.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/05-airi-card.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/05-airi-card.avif new file mode 100644 index 000000000..88766b5df Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/05-airi-card.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/06-providers.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/06-providers.avif new file mode 100644 index 000000000..dcedf1fc2 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/06-providers.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/07-data.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/07-data.avif new file mode 100644 index 000000000..78778b814 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/07-data.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/08-system-general.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/08-system-general.avif new file mode 100644 index 000000000..01dd223d9 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/08-system-general.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/09-system-color-scheme.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/09-system-color-scheme.avif new file mode 100644 index 000000000..9160939d2 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/09-system-color-scheme.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/10-models.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/10-models.avif new file mode 100644 index 000000000..086f93aab Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/10-models.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/11-modules.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/11-modules.avif new file mode 100644 index 000000000..b3313cb1a Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/11-modules.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/12-hearing.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/12-hearing.avif new file mode 100644 index 000000000..54a85b1b7 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/12-hearing.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/13-system-developer.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/13-system-developer.avif new file mode 100644 index 000000000..66edd0686 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/13-system-developer.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/14-consciousness.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/14-consciousness.avif new file mode 100644 index 000000000..72a6979c9 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/14-consciousness.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/15-speech.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/15-speech.avif new file mode 100644 index 000000000..12dc73911 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/15-speech.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/16-vision.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/16-vision.avif new file mode 100644 index 000000000..eefaf0ee4 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/16-vision.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/17-devtools-use-window-mouse.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/17-devtools-use-window-mouse.avif new file mode 100644 index 000000000..bba1704b8 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/17-devtools-use-window-mouse.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/18-devtools-displays.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/18-devtools-displays.avif new file mode 100644 index 000000000..b4262dac0 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/18-devtools-displays.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/19-devtools-widgets-calling.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/19-devtools-widgets-calling.avif new file mode 100644 index 000000000..32f2a0a55 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/19-devtools-widgets-calling.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/20-devtools-context-flow.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/20-devtools-context-flow.avif new file mode 100644 index 000000000..b3bcc71b4 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/20-devtools-context-flow.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/21-devtools-relative-mouse.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/21-devtools-relative-mouse.avif new file mode 100644 index 000000000..3d1d97980 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/21-devtools-relative-mouse.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/22-devtools-beat-sync.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/22-devtools-beat-sync.avif new file mode 100644 index 000000000..f99ac8334 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/22-devtools-beat-sync.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/23-devtools-websocket-inspector.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/23-devtools-websocket-inspector.avif new file mode 100644 index 000000000..319b182d3 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/23-devtools-websocket-inspector.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/24-devtools-plugin-host.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/24-devtools-plugin-host.avif new file mode 100644 index 000000000..9f318ede9 Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/24-devtools-plugin-host.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/25-devtools-screen-capture.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/25-devtools-screen-capture.avif new file mode 100644 index 000000000..63753650f Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/25-devtools-screen-capture.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/26-devtools-vision-capture.avif b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/26-devtools-vision-capture.avif new file mode 100644 index 000000000..d5c386c8b Binary files /dev/null and b/packages/scenarios-stage-tamagotchi-browser/artifacts/raw/26-devtools-vision-capture.avif differ diff --git a/packages/scenarios-stage-tamagotchi-browser/src/scenes/intro-manual-scene.vue b/packages/scenarios-stage-tamagotchi-browser/src/scenes/intro-manual-scene.vue index 5def139c4..aa5148ae2 100644 --- a/packages/scenarios-stage-tamagotchi-browser/src/scenes/intro-manual-scene.vue +++ b/packages/scenarios-stage-tamagotchi-browser/src/scenes/intro-manual-scene.vue @@ -4,7 +4,32 @@ import { ScenarioCanvas, ScenarioCaptureRoot } from '@proj-airi/vishot-runtime/v import { onMounted } from 'vue' import stageShot from '../../artifacts/raw/00-stage-tamagotchi.avif' +import controlsIslandShot from '../../artifacts/raw/01-controls-island-expanded.avif' +import settingsShot from '../../artifacts/raw/02-settings-window.avif' import websocketSettingsShot from '../../artifacts/raw/03-websocket-settings.avif' +import chatWindowShot from '../../artifacts/raw/04-chat-window.avif' +import airiCardShot from '../../artifacts/raw/05-airi-card.avif' +import providersShot from '../../artifacts/raw/06-providers.avif' +import dataShot from '../../artifacts/raw/07-data.avif' +import systemGeneralShot from '../../artifacts/raw/08-system-general.avif' +import systemColorSchemeShot from '../../artifacts/raw/09-system-color-scheme.avif' +import modelsShot from '../../artifacts/raw/10-models.avif' +import modulesShot from '../../artifacts/raw/11-modules.avif' +import hearingShot from '../../artifacts/raw/12-hearing.avif' +import systemDeveloperShot from '../../artifacts/raw/13-system-developer.avif' +import consciousnessShot from '../../artifacts/raw/14-consciousness.avif' +import speechShot from '../../artifacts/raw/15-speech.avif' +import visionShot from '../../artifacts/raw/16-vision.avif' +import useWindowMouseShot from '../../artifacts/raw/17-devtools-use-window-mouse.avif' +import displaysShot from '../../artifacts/raw/18-devtools-displays.avif' +import widgetsCallingShot from '../../artifacts/raw/19-devtools-widgets-calling.avif' +import contextFlowShot from '../../artifacts/raw/20-devtools-context-flow.avif' +import relativeMouseShot from '../../artifacts/raw/21-devtools-relative-mouse.avif' +import beatSyncShot from '../../artifacts/raw/22-devtools-beat-sync.avif' +import websocketInspectorShot from '../../artifacts/raw/23-devtools-websocket-inspector.avif' +import pluginHostShot from '../../artifacts/raw/24-devtools-plugin-host.avif' +import screenCaptureShot from '../../artifacts/raw/25-devtools-screen-capture.avif' +import visionCaptureShot from '../../artifacts/raw/26-devtools-vision-capture.avif' import Icon from '../components/icon.vue' import { PlatformRoot } from '../components/platforms/macos-26' @@ -29,6 +54,50 @@ const websocketWindowStyle = { top: '120px', } +const mainOnlyWindowStyle = { + right: '0px', + bottom: '0px', +} + +const settingsOnlyWindowStyle = { + left: '50%', + top: '84px', + transform: 'translateX(-50%)', +} + +const chatWindowStyle = { + left: '50%', + top: '72px', + transform: 'translateX(-50%)', +} + +const settingsCaptureRoots = [ + { name: 'manual-settings-window', src: settingsShot, imageClass: 'w-130' }, + { name: 'manual-websocket-settings', src: websocketSettingsShot, imageClass: 'w-130' }, + { name: 'manual-airi-card', src: airiCardShot, imageClass: 'w-140' }, + { name: 'manual-providers', src: providersShot, imageClass: 'w-140' }, + { name: 'manual-data-settings', src: dataShot, imageClass: 'w-140' }, + { name: 'manual-system-general', src: systemGeneralShot, imageClass: 'w-140' }, + { name: 'manual-system-color-scheme', src: systemColorSchemeShot, imageClass: 'w-140' }, + { name: 'manual-models', src: modelsShot, imageClass: 'w-150' }, + { name: 'manual-modules', src: modulesShot, imageClass: 'w-140' }, + { name: 'manual-hearing', src: hearingShot, imageClass: 'w-145' }, + { name: 'manual-system-developer', src: systemDeveloperShot, imageClass: 'w-145' }, + { name: 'manual-consciousness', src: consciousnessShot, imageClass: 'w-145' }, + { name: 'manual-speech', src: speechShot, imageClass: 'w-150' }, + { name: 'manual-vision', src: visionShot, imageClass: 'w-145' }, + { name: 'manual-devtools-use-window-mouse', src: useWindowMouseShot, imageClass: 'w-140' }, + { name: 'manual-devtools-displays', src: displaysShot, imageClass: 'w-150' }, + { name: 'manual-devtools-widgets-calling', src: widgetsCallingShot, imageClass: 'w-150' }, + { name: 'manual-devtools-context-flow', src: contextFlowShot, imageClass: 'w-155' }, + { name: 'manual-devtools-relative-mouse', src: relativeMouseShot, imageClass: 'w-150' }, + { name: 'manual-devtools-beat-sync', src: beatSyncShot, imageClass: 'w-155' }, + { name: 'manual-devtools-websocket-inspector', src: websocketInspectorShot, imageClass: 'w-155' }, + { name: 'manual-devtools-plugin-host', src: pluginHostShot, imageClass: 'w-155' }, + { name: 'manual-devtools-screen-capture', src: screenCaptureShot, imageClass: 'w-155' }, + { name: 'manual-devtools-vision-capture', src: visionCaptureShot, imageClass: 'w-155' }, +] as const + async function waitForImageSource(source: string): Promise { await new Promise((resolve, reject) => { const image = new Image() @@ -45,7 +114,32 @@ onMounted(async () => { await Promise.all([ document.fonts.ready, waitForImageSource(stageShot), + waitForImageSource(controlsIslandShot), + waitForImageSource(settingsShot), waitForImageSource(websocketSettingsShot), + waitForImageSource(chatWindowShot), + waitForImageSource(airiCardShot), + waitForImageSource(providersShot), + waitForImageSource(dataShot), + waitForImageSource(systemGeneralShot), + waitForImageSource(systemColorSchemeShot), + waitForImageSource(modelsShot), + waitForImageSource(modulesShot), + waitForImageSource(hearingShot), + waitForImageSource(systemDeveloperShot), + waitForImageSource(consciousnessShot), + waitForImageSource(speechShot), + waitForImageSource(visionShot), + waitForImageSource(useWindowMouseShot), + waitForImageSource(displaysShot), + waitForImageSource(widgetsCallingShot), + waitForImageSource(contextFlowShot), + waitForImageSource(relativeMouseShot), + waitForImageSource(beatSyncShot), + waitForImageSource(websocketInspectorShot), + waitForImageSource(pluginHostShot), + waitForImageSource(screenCaptureShot), + waitForImageSource(visionCaptureShot), ]) markScenarioReady() } @@ -56,8 +150,92 @@ onMounted(async () => { diff --git a/packages/scenarios-stage-tamagotchi-electron/src/scenarios/demo-controls-settings-chat-websocket.ts b/packages/scenarios-stage-tamagotchi-electron/src/scenarios/demo-controls-settings-chat-websocket.ts index 250355871..f528dc7ca 100644 --- a/packages/scenarios-stage-tamagotchi-electron/src/scenarios/demo-controls-settings-chat-websocket.ts +++ b/packages/scenarios-stage-tamagotchi-electron/src/scenarios/demo-controls-settings-chat-websocket.ts @@ -2,27 +2,198 @@ import { sleep } from '@moeru/std' import { defineScenario } from '@proj-airi/vishot-runner-electron' +const airiCardPattern = /sort|排序|upload|上传/i +const providersPattern = /Chat|Speech|Transcription/i +// NOTICE: Must stay unique to /settings/data. The prior alternates `chat` / `聊天` +// also matched the providers page (step 06), which renders a `Chat` / `聊天` provider +// category immediately before this step — so the readiness check could pass on stale +// providers DOM and silently produce a mislabeled screenshot. `打开` was also too +// generic (appears on multiple pages as button labels). `Open app data folder` is +// the desktop-folder section title and is literal English across every locale file. +const dataPattern = /Open app data folder/i +const systemGeneralPattern = /theme|主题|language|语言/i +const systemColorSchemePattern = /RGB|Primary Color|主题颜色|500\/50/i +const modelsPattern = /select model|confirm|缩放与位置|Zoom & Position/i +const modulesPattern = /Consciousness|意识|Speech|发声|Hearing|听觉/i +const hearingPattern = /Audio Input Device|音频输入设备|start monitoring|Start Monitoring|Transcription Result/i +const developerPattern = /Open DevTools|打开|Markdown|Lag|Vision Capture|Screen Capture/i +// NOTICE: Anchor on the consciousness page's always-rendered section description +// (consciousness.vue renders this unconditionally regardless of provider/model state +// or user locale). Previous alternates like `提供商` / `No Providers Configured` did +// not match zh-Hans (which renders `服务来源` / `没有配置服务来源`), and `当前模型` / +// `Current model` only appear when a model is already selected — so fresh environments +// with no providers configured would hang on readiness. +// +// Caveat: vision.vue reuses the same `provider-model-selection.description` i18n key, +// so this pattern also matches on /settings/modules/vision. That is safe here because +// consciousness (step 14) is reached from developer (step 13), which does not render +// either phrase — no stale-DOM collision is possible at this step. If the step order +// ever changes, pick a token unique to consciousness.vue instead. +const consciousnessPattern = /Select the suitable LLM|为意识选择合适/i +const speechPattern = /Hello, my name is AI Assistant|Test voice|Voice|声音|Speech|选择语音合成服务来源/i +const visionPattern = /Capture interval|context|ollama|提供商|Current model|Chat|Vision capture cadence/i +const useWindowMousePattern = /useWindowMouse|\d+,\s*\d+/i +const displaysPattern = /useElectronAllDisplays|@\s*\d+°|Visualize connected displays and cursor position/i +const widgetsCallingPattern = /Widget id is required|Small \(s\)|Spawned widget|Component name/i +const contextFlowPattern = /Active contexts|Prompt projection|Runtime|Context Flow|Filters/i +const relativeMousePattern = /windowX = screenX - windowBounds\.x|Green dot shows current window-relative cursor position|Relative Mouse/i +const beatSyncPattern = /Beat sync driver|Hit beat|Punchy V|Beat Sync Visualizer/i +const websocketInspectorPattern = /Incoming|Outgoing|Filter payload|No messages found|WebSocket Inspector/i +const pluginHostPattern = /Discovered|Enabled|Loaded|Capabilities|Plugin Host Debug/i +const screenCapturePattern = /Applications|Displays|Refetch|Share Window|Share Screen|屏幕捕获|Open system preferences|打开系统偏好设置/i +// NOTICE: Must stay unique to /devtools/vision. Step 25 captures /devtools/screen-capture +// immediately before this, and both pages render `Applications` / `Displays` tab labels, so +// matching against those generics lets the readiness check pass against the stale +// screen-capture DOM and silently produce a mislabeled screenshot. Only use text that does +// not appear on screen-capture.vue. +const visionCapturePattern = /Capture interval|No vision output yet|vision capture/i +const websocketServerAddressPattern = /WebSocket Server Address|WebSocket 服务器地址/i + +function normalizeHashPath(hash: string): string { + const withoutHash = hash.startsWith('#') + ? hash.slice(1) + : hash + + return withoutHash || '/' +} + +function isTimeoutLikeError(error: unknown): boolean { + return error instanceof Error && error.name === 'TimeoutError' +} + export default defineScenario({ id: 'demo-controls-settings-chat-websocket', async run({ capture, controlsIsland, settingsWindow, stageWindows }) { + async function ensureControlsIslandExpanded() { + const chatButton = mainWindow.page + .locator('button') + .filter({ + has: mainWindow.page.locator('[i-solar\\:chat-line-line-duotone]'), + }) + .first() + + const chatButtonVisible = await chatButton.isVisible().catch(() => false) + if (!chatButtonVisible) { + await controlsIsland.expand(mainWindow.page) + await sleep(250) + } + } + + async function captureSettingsRoute(name: string, routePath: string, readyPattern: RegExp, waitMs = 250) { + await settingsWindow.goToRoute(settingsWindowSnapshot.page, routePath) + try { + await settingsWindowSnapshot.page.getByText(readyPattern).first().waitFor({ state: 'visible', timeout: 15_000 }) + } + catch (error) { + if (!isTimeoutLikeError(error)) { + throw error + } + + const currentHashPath = normalizeHashPath(new URL(settingsWindowSnapshot.page.url()).hash) + if (currentHashPath !== routePath) { + throw error + } + + // NOTICE: Some settings/devtools pages animate in or hydrate content asynchronously. + // Give known-slow pages one final bounded grace period, but still fail if the target route never becomes ready. + await sleep(1250) + await settingsWindowSnapshot.page.getByText(readyPattern).first().waitFor({ state: 'visible', timeout: 5_000 }) + } + await sleep(waitMs) + await capture(name, settingsWindowSnapshot.page) + } + const mainWindow = await stageWindows.waitFor('main') + await controlsIsland.waitForReady(mainWindow.page) + await capture('00-stage-tamagotchi', mainWindow.page) await sleep(500) await controlsIsland.expand(mainWindow.page) await sleep(250) await capture('01-controls-island-expanded', mainWindow.page) + await sleep(250) + + await ensureControlsIslandExpanded() + const chatWindowSnapshot = await controlsIsland.openChat(mainWindow.page) + await chatWindowSnapshot.page.getByText(/Chat/i).first().waitFor({ state: 'visible' }) + await sleep(1000) + await capture('04-chat-window', chatWindowSnapshot.page) + await sleep(250) + + await mainWindow.page.bringToFront() + await controlsIsland.waitForReady(mainWindow.page) + await ensureControlsIslandExpanded() const settingsWindowSnapshot = await controlsIsland.openSettings(mainWindow.page) await settingsWindowSnapshot.page.getByText(/connection|websocket|router/i).first().waitFor({ state: 'visible' }) await sleep(1000) await capture('02-settings-window', settingsWindowSnapshot.page) + await settingsWindow.goToRoute(settingsWindowSnapshot.page, '/settings/airi-card') + await settingsWindowSnapshot.page.getByText(airiCardPattern).first().waitFor({ state: 'visible' }) + await sleep(1000) + await capture('05-airi-card', settingsWindowSnapshot.page) + + await settingsWindow.goToRoute(settingsWindowSnapshot.page, '/settings/providers') + await settingsWindowSnapshot.page.getByText(providersPattern).first().waitFor({ state: 'visible' }) + await sleep(1000) + await capture('06-providers', settingsWindowSnapshot.page) + + await settingsWindow.goToRoute(settingsWindowSnapshot.page, '/settings/data') + await settingsWindowSnapshot.page.getByText(dataPattern).first().waitFor({ state: 'visible' }) + await sleep(1000) + await capture('07-data', settingsWindowSnapshot.page) + + await settingsWindow.goToRoute(settingsWindowSnapshot.page, '/settings/system/general') + await settingsWindowSnapshot.page.getByText(systemGeneralPattern).first().waitFor({ state: 'visible' }) + await sleep(1000) + await capture('08-system-general', settingsWindowSnapshot.page) + + await settingsWindow.goToRoute(settingsWindowSnapshot.page, '/settings/system/color-scheme') + await settingsWindowSnapshot.page.getByText(systemColorSchemePattern).first().waitFor({ state: 'visible' }) + await sleep(1000) + await capture('09-system-color-scheme', settingsWindowSnapshot.page) + + await settingsWindow.goToRoute(settingsWindowSnapshot.page, '/settings/models') + await settingsWindowSnapshot.page.getByText(modelsPattern).first().waitFor({ state: 'visible' }) + await sleep(1000) + await capture('10-models', settingsWindowSnapshot.page) + + await settingsWindow.goToRoute(settingsWindowSnapshot.page, '/settings/modules') + await settingsWindowSnapshot.page.getByText(modulesPattern).first().waitFor({ state: 'visible' }) + await sleep(1000) + await capture('11-modules', settingsWindowSnapshot.page) + + await settingsWindow.goToRoute(settingsWindowSnapshot.page, '/settings/modules/hearing') + await settingsWindowSnapshot.page.getByText(hearingPattern).first().waitFor({ state: 'visible' }) + await sleep(1000) + await capture('12-hearing', settingsWindowSnapshot.page) + + await settingsWindow.goToRoute(settingsWindowSnapshot.page, '/settings/system/developer') + await settingsWindowSnapshot.page.getByText(developerPattern).first().waitFor({ state: 'visible' }) + await sleep(1000) + await capture('13-system-developer', settingsWindowSnapshot.page) + + await captureSettingsRoute('14-consciousness', '/settings/modules/consciousness', consciousnessPattern) + await captureSettingsRoute('15-speech', '/settings/modules/speech', speechPattern, 500) + await captureSettingsRoute('16-vision', '/settings/modules/vision', visionPattern) + await captureSettingsRoute('17-devtools-use-window-mouse', '/devtools/use-window-mouse', useWindowMousePattern) + await captureSettingsRoute('18-devtools-displays', '/devtools/use-electron-all-displays', displaysPattern) + await captureSettingsRoute('19-devtools-widgets-calling', '/devtools/widgets-calling', widgetsCallingPattern) + await captureSettingsRoute('20-devtools-context-flow', '/devtools/context-flow', contextFlowPattern) + await captureSettingsRoute('21-devtools-relative-mouse', '/devtools/use-electron-relative-mouse', relativeMousePattern) + await captureSettingsRoute('22-devtools-beat-sync', '/devtools/beat-sync', beatSyncPattern) + await captureSettingsRoute('23-devtools-websocket-inspector', '/devtools/websocket-inspector', websocketInspectorPattern) + await captureSettingsRoute('24-devtools-plugin-host', '/devtools/plugin-host', pluginHostPattern) + await captureSettingsRoute('25-devtools-screen-capture', '/devtools/screen-capture', screenCapturePattern, 500) + await captureSettingsRoute('26-devtools-vision-capture', '/devtools/vision', visionCapturePattern, 500) + await settingsWindowSnapshot.page.bringToFront() await sleep(500) const websocketSettingsPage = await settingsWindow.goToConnection(settingsWindowSnapshot.page) - await websocketSettingsPage.getByText('WebSocket Server Address').waitFor({ state: 'visible' }) + await websocketSettingsPage.getByText(websocketServerAddressPattern).waitFor({ state: 'visible' }) await sleep(1000) await capture('03-websocket-settings', websocketSettingsPage) }, diff --git a/packages/scenarios-stage-tamagotchi-electron/src/scenarios/settings-connection.ts b/packages/scenarios-stage-tamagotchi-electron/src/scenarios/settings-connection.ts index 34d75809a..52228a9ce 100644 --- a/packages/scenarios-stage-tamagotchi-electron/src/scenarios/settings-connection.ts +++ b/packages/scenarios-stage-tamagotchi-electron/src/scenarios/settings-connection.ts @@ -1,16 +1,19 @@ import { defineScenario } from '@proj-airi/vishot-runner-electron' +const websocketServerAddressPattern = /WebSocket Server Address|WebSocket 服务器地址/i + export default defineScenario({ id: 'settings-connection', async run({ capture, stageWindows, controlsIsland, settingsWindow }) { const mainWindow = await stageWindows.waitFor('main') + await controlsIsland.waitForReady(mainWindow.page) await controlsIsland.expand(mainWindow.page) const settings = await controlsIsland.openSettings(mainWindow.page) const page = await settingsWindow.goToConnection(settings.page) await page.waitForTimeout(1000) - await page.getByText('WebSocket Server Address').waitFor({ state: 'visible' }) + await page.getByText(websocketServerAddressPattern).waitFor({ state: 'visible' }) await capture('connection-settings', page) }, }) diff --git a/packages/vishot-runner-electron/src/runtime/context.ts b/packages/vishot-runner-electron/src/runtime/context.ts index eac2c77b5..7709c5031 100644 --- a/packages/vishot-runner-electron/src/runtime/context.ts +++ b/packages/vishot-runner-electron/src/runtime/context.ts @@ -3,8 +3,8 @@ import type { ElectronApplication, Page } from 'playwright' import type { CaptureOptions, ScenarioContext } from './types' import { dismissDialog, dismissDrawer, swipeDownDrawer } from '../utils/overlays' -import { expandControlsIsland, openChatFromControlsIsland, openHearingFromControlsIsland, openSettingsFromControlsIsland } from '../utils/selectors' -import { goToSettingsConnectionPage } from '../utils/settings' +import { expandControlsIsland, openChatFromControlsIsland, openHearingFromControlsIsland, openSettingsFromControlsIsland, waitForControlsIslandReady } from '../utils/selectors' +import { goToSettingsConnectionPage, goToSettingsRoute } from '../utils/settings' import { waitForStageWindow } from '../utils/windows' import { capturePage } from './capture' @@ -41,6 +41,9 @@ export function createScenarioContext( }, }, controlsIsland: { + waitForReady(page) { + return waitForControlsIslandReady(page) + }, async expand(page) { await expandControlsIsland(page) }, @@ -63,6 +66,9 @@ export function createScenarioContext( goToConnection(page) { return goToSettingsConnectionPage(page) }, + goToRoute(page, routePath) { + return goToSettingsRoute(page, routePath) + }, }, dialogs: { dismiss(page) { diff --git a/packages/vishot-runner-electron/src/runtime/types.ts b/packages/vishot-runner-electron/src/runtime/types.ts index b237c2f09..cd330d14a 100644 --- a/packages/vishot-runner-electron/src/runtime/types.ts +++ b/packages/vishot-runner-electron/src/runtime/types.ts @@ -28,6 +28,7 @@ export interface StageWindowsApi { } export interface ControlsIslandApi { + waitForReady: (page: Page) => Promise expand: (page: Page) => Promise openSettings: (page: Page) => Promise openChat: (page: Page) => Promise @@ -37,6 +38,7 @@ export interface ControlsIslandApi { export interface SettingsWindowApi { waitFor: (timeout?: number) => Promise goToConnection: (page: Page) => Promise + goToRoute: (page: Page, routePath: string) => Promise } export interface DialogsApi { diff --git a/packages/vishot-runner-electron/src/utils/selectors.ts b/packages/vishot-runner-electron/src/utils/selectors.ts index 0bfcd3626..20a1807ac 100644 --- a/packages/vishot-runner-electron/src/utils/selectors.ts +++ b/packages/vishot-runner-electron/src/utils/selectors.ts @@ -2,19 +2,30 @@ import type { Page } from 'playwright' import { sleep } from '@moeru/std' +const controlsIslandReadyTimeoutMs = 30_000 + function iconAttributeSelector(iconName: string): string { return `[${iconName.replace(':', '\\:')}]` } -async function clickControlButtonByIcon(page: Page, iconName: string): Promise { - const button = page +function controlButtonsByIcon(page: Page, iconName: string) { + return page .locator('button') .filter({ has: page.locator(iconAttributeSelector(iconName)), }) - .last() +} - await button.waitFor({ state: 'visible', timeout: 15_000 }) +export async function waitForControlsIslandReady(page: Page): Promise { + const button = controlButtonsByIcon(page, 'i-solar:alt-arrow-up-line-duotone').first() + + await button.waitFor({ state: 'visible', timeout: controlsIslandReadyTimeoutMs }) +} + +async function clickControlButtonByIcon(page: Page, iconName: string): Promise { + const button = controlButtonsByIcon(page, iconName).first() + + await button.waitFor({ state: 'visible', timeout: controlsIslandReadyTimeoutMs }) await button.click({ force: true }) await sleep(100) } @@ -24,7 +35,11 @@ export async function expandControlsIsland(page: Page): Promise { } export async function openSettingsFromControlsIsland(page: Page): Promise { - await clickControlButtonByIcon(page, 'i-solar:settings-minimalistic-outline') + await controlButtonsByIcon(page, 'i-solar:settings-minimalistic-outline') + .first() + .click({ force: true, timeout: controlsIslandReadyTimeoutMs }) + + await sleep(100) } export async function openChatFromControlsIsland(page: Page): Promise { @@ -32,12 +47,7 @@ export async function openChatFromControlsIsland(page: Page): Promise { } export async function openHearingFromControlsIsland(page: Page): Promise { - const expandButton = page - .locator('button') - .filter({ - has: page.locator(iconAttributeSelector('i-solar:alt-arrow-up-line-duotone')), - }) - .last() + const expandButton = controlButtonsByIcon(page, 'i-solar:alt-arrow-up-line-duotone').first() const hearingButton = expandButton.locator('xpath=ancestor::button[1]/following::button[1]').first() diff --git a/packages/vishot-runner-electron/src/utils/settings.ts b/packages/vishot-runner-electron/src/utils/settings.ts index 27d987e3a..c5a8d0676 100644 --- a/packages/vishot-runner-electron/src/utils/settings.ts +++ b/packages/vishot-runner-electron/src/utils/settings.ts @@ -13,6 +13,35 @@ function getSettingsSwitch(settingsPage: Page, label: RegExp | string) { return { labelLocator, row, button } } +function normalizeHashPath(hash: string): string { + const withoutHash = hash.startsWith('#') + ? hash.slice(1) + : hash + + return withoutHash || '/' +} + +function getCurrentHashPath(settingsPage: Page): string { + return normalizeHashPath(new URL(settingsPage.url()).hash) +} + +export async function goToSettingsRoute(settingsPage: Page, routePath: string): Promise { + const normalizedRoutePath = routePath.startsWith('/') + ? routePath + : `/${routePath}` + + if (getCurrentHashPath(settingsPage) !== normalizedRoutePath) { + await settingsPage.evaluate((nextRoutePath) => { + window.location.hash = nextRoutePath + }, normalizedRoutePath) + await settingsPage.waitForFunction((expectedHashPath) => { + return window.location.hash === `#${expectedHashPath}` + }, normalizedRoutePath) + } + + return settingsPage +} + export async function openSettingsConnectionPage(_mainPage: Page, settingsPage: Page): Promise { if (!settingsPage.url().includes('#/settings/connection')) { await settingsPage.getByText(/connection|websocket|router/i).first().click({ force: true }) @@ -21,12 +50,7 @@ export async function openSettingsConnectionPage(_mainPage: Page, settingsPage: } export async function goToSettingsConnectionPage(settingsPage: Page): Promise { - if (!settingsPage.url().includes('#/settings/connection')) { - await settingsPage.getByText(/connection|websocket|router/i).first().click({ force: true }) - await settingsPage.waitForURL(/#\/settings\/connection/) - } - - return settingsPage + return goToSettingsRoute(settingsPage, '/settings/connection') } export async function toggleSettingsSwitchByLabel(settingsPage: Page, label: RegExp | string): Promise<{ before: string, after: string }> { diff --git a/packages/vishot-runner-electron/src/utils/windows.ts b/packages/vishot-runner-electron/src/utils/windows.ts index 4797de3be..3a4168c20 100644 --- a/packages/vishot-runner-electron/src/utils/windows.ts +++ b/packages/vishot-runner-electron/src/utils/windows.ts @@ -3,6 +3,7 @@ import type { ElectronApplication, Page } from 'playwright' const stageWindowPollIntervalMs = 250 const stageWindowActivationDelayMs = 750 const stageWindowClassificationLoadStateTimeoutMs = 500 +const mainWindowReadyIconSelector = '[i-solar\\:alt-arrow-up-line-duotone]' async function inferRoute(page: Page): Promise { const url = page.url() @@ -38,7 +39,9 @@ async function classifyWindow(page: Page): Promise { return null } - if (route === '/' || title === 'AIRI') { + const mainControlsVisible = await page.locator(mainWindowReadyIconSelector).first().isVisible().catch(() => false) + + if ((route === '/' || title === 'AIRI') && mainControlsVisible) { return { name: 'main', page, title, route } } @@ -51,7 +54,7 @@ async function classifyWindow(page: Page): Promise { return { name: 'chat', page, title, route } } - if (bodyText.includes('Fade on Hover') || bodyText.includes('Open WebSocket settings')) { + if (mainControlsVisible || bodyText.includes('Fade on Hover') || bodyText.includes('Open WebSocket settings')) { return { name: 'main', page, title, route } }