arona-agent 1.0.3 → 1.0.5

package/README.md

@@ -8,14 +8,14 @@
 
 ![示意图](./intro.png)
 
-基于 [Pi SDK](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) 构建的终端对话式 AI Agent，集成 Computer Use、语音（TTS/STT）、桌面宠物、持久记忆与会话管理。
+基于 [Pi SDK](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) 构建的终端对话式 AI Agent，集成 Computer Use、语音（TTS/STT）、桌面宠物与持久记忆。
 
 ---
 
 ## 安装
 
 ```bash
-npm install -g arona-agent
+npm i -g arona-agent
 
 # 初始化配置文件
 arona setup
@@ -24,7 +24,7 @@ arona setup
 arona
 
 # 更新
-npm update -g arona-agent
+npm u -g arona-agent
 
 # 禁用TTS+STT并启动
 arona --no-voice
@@ -39,7 +39,7 @@ arona voice add [<角色名>]   # 不带角色名则进入 TUI 选择未补全
 
 - **Computer Use**：基于 [cua](https://pypi.org/project/cua/) 。
 - **语音**：非流式 TTS + STT。
-- **桌宠**：透明无边框置顶 Electron 窗口 + 情绪切换 + 瞳孔跟随鼠标 + 头部摇动摸头彩蛋 + 全屏点击/拖尾特效。
+- **桌宠**：透明无边框置顶 Electron 窗口 + 情绪切换 + 瞳孔跟随鼠标 + 头部摇动摸头彩蛋 + 全屏点击/拖尾特效；TTS 说话时嘴型跟随音量（lip-sync）。
 - **多角色群聊**：主 Agent 单窗口、子 Agent 同屏；每轮主 Agent 回复完后子 Agent 依次接话。
 
 
@@ -48,7 +48,7 @@ arona voice add [<角色名>]   # 不带角色名则进入 TUI 选择未补全
 ## 环境要求
 
 - **Node.js >= 22.19.0**
-- **Python 3.12 / 3.13**
+- **Python 3.9+（CUA需要 3.12 / 3.13）**
 
 ---
 
@@ -59,8 +59,8 @@ arona voice add [<角色名>]   # 不带角色名则进入 TUI 选择未补全
 | 字段 | 说明 | 默认值 |
 |---|---|---|
 | `apiKey` | API Key | — |
-| `apiBaseUrl` | API地址（留空则按模型名自动匹配） | — |
-| `model` | 模型名（`provider/model-id`，裸名自动补前缀） | `openai/gpt-4o` |
+| `apiBaseUrl` | API地址 | — |
+| `model` | 模型名 | `openai/gpt-4o` |
 | `thinkingLevel` | 思考等级 | `medium` |
 | `contextWindow` | 上下文窗口 | `1000000` |
 | `language` | 界面语言（`auto`/`zh`/`en`） | `auto` |
@@ -71,6 +71,8 @@ arona voice add [<角色名>]   # 不带角色名则进入 TUI 选择未补全
 | `workspaceId` | 阿里云百炼业务空间 ID | — |
 | `ttsApiKey` | 百炼 API Key | — |
 | `ttsModel` | TTS 模型 | `qwen-audio-3.0-tts-plus` |
+| `ttsProvider` | TTS 后端（`aliyun`/`gpt-sovits`） | `aliyun` |
+| `ttsConfig` | 各 Provider 配置 | `{}` |
 | `sttApiKey` | 百炼 API Key | — |
 | `sttModel` | STT 模型 | `qwen-audio-3.0-asr-flash-streaming` |
 | `sttFormat` | STT 音频格式 | `pcm` |
@@ -89,7 +91,7 @@ arona voice add [<角色名>]   # 不带角色名则进入 TUI 选择未补全
 | 路径 | 说明 |
 |---|---|
 | `settings.json` | 本地总配置文件，字段见 [配置](#配置) |
-| `voices.json` | 角色音色克隆 voice_id |
+| `voices.json` | TTS音色配置文件 |
 | `MEMORY.md` | 持久记忆 |
 | `sessions/` | 已保存会话 |
 | `skills/` | 自定义 Skill |
@@ -101,8 +103,10 @@ arona voice add [<角色名>]   # 不带角色名则进入 TUI 选择未补全
 ## 桌宠与 STT 热键
 
 - **桌宠**：透明无边框置顶窗口；拖动窗口可移动，在头部区域左右摇晃可触发"摸头"彩蛋；点击/拖拽还会触发特效
-- **STT 热键**：右 Cmd 键，长按 ≥ 2 秒触发一次性录音。
-- **macOS 权限**：全局键盘监听需「系统设置 → 隐私与安全性 → 辅助功能」为Python授权；Computer Use 截图需授予终端「屏幕录制」权限。
+- **STT 热键**：macOS 为右 Cmd 键，Windows/Linux 为右 Ctrl 键，长按 ≥ 2 秒触发一次性录音。
+> MacOS下，全局键盘监听需「系统设置 → 隐私与安全性 → 辅助功能」为Python授权；
+
+> Computer Use 截图需授予终端「屏幕录制」权限。
 
 ---
 

package/README_en.md

@@ -0,0 +1,145 @@
+# ARONA Agent
+
+[中文](README.md) | [English](README_en.md)
+
+![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+
+![Screenshot](./intro.png)
+
+A terminal-based conversational AI Agent built on the [Pi SDK](https://www.npmjs.com/package/@earendil-works/pi-coding-agent), featuring Computer Use, voice (TTS/STT), desktop pets and persistent memory.
+
+---
+
+## Installation
+
+```bash
+npm i -g arona-agent
+
+# Initialize configuration
+arona setup
+
+# Launch after setup
+arona
+
+# Upgrade
+npm u -g arona-agent
+
+# Launch with TTS/STT disabled
+arona --no-voice
+
+# Clone/re-clone a character's voice
+arona voice add [<character-name>]   # omit the name to enter the TUI for missing voices
+```
+
+---
+
+## Key Features
+
+- **Computer Use**: based on [cua](https://pypi.org/project/cua/).
+- **Voice**: Non-streaming TTS (whole-sentence synthesis for natural prosody) + STT.
+- **Desktop pet**: transparent frameless always-on-top Electron window + emotion switching + cursor-following pupils + head-pat easter egg + full-screen click/trail FX; lip-sync mouth animation driven by TTS volume.
+- **Multi-character group chat**: main agent + sub agents on the same screen. After the main agent replies, sub agents take turns in order.
+
+---
+
+## Requirements
+
+- **Node.js >= 22.19.0**
+- **Python 3.12 / 3.13**
+
+---
+
+## Configuration
+
+All configuration lives in the JSON file `~/.arona/settings.json`, mostly generated interactively by `arona setup`. Some advanced parameters must be entered manually.
+
+| Field | Description | Default |
+|---|---|---|
+| `apiKey` | API key | — |
+| `apiBaseUrl` | API base URL | — |
+| `model` | Model name | `openai/gpt-4o` |
+| `thinkingLevel` | Thinking level | `medium` |
+| `contextWindow` | Context window | `1000000` |
+| `language` | Interface language (`auto`/`zh`/`en`) | `auto` |
+| `mainAgent` | Main agent (`arona`/`plana`) | `arona` |
+| `subAgents` | Enabled sub agents array | `[]` |
+| `ttsEnabled` | Enable TTS | `true` |
+| `sttEnabled` | Enable STT | `true` |
+| `workspaceId` | Alibaba Cloud Model Studio business space ID | — |
+| `ttsApiKey` | DashScope API key | — |
+| `ttsModel` | TTS model | `qwen-audio-3.0-tts-plus` |
+| `ttsProvider` | TTS backend (`aliyun`/`gpt-sovits`) | `aliyun` |
+| `ttsConfig` | Provider-specific config | `{}` |
+| `sttApiKey` | DashScope API key | — |
+| `sttModel` | STT model | `qwen-audio-3.0-asr-flash-streaming` |
+| `sttFormat` | STT audio format | `pcm` |
+| `sttSampleRate` | STT sample rate | `16000` |
+| `cuaApiKey` | Cua API key | — |
+| `tavilyApiKey` | Tavily API key | — |
+| `pythonPath` | Python path | `python3` |
+| `mcpServers` | MCP server JSON | `{}` |
+
+Model prefix auto-detection: if `model` contains no `/`, a `provider/` prefix is added automatically based on the model name prefix or the `apiBaseUrl` domain.
+
+---
+
+## Data Paths (`~/.arona/`)
+
+| Path | Description |
+|---|---|
+| `settings.json` | Main config file; see the [Configuration](#configuration) section for fields |
+| `voices.json` | TTS Voices config file |
+| `MEMORY.md` | Persistent memory |
+| `sessions/` | Saved sessions |
+| `skills/` | Custom skills |
+| `undo/` | Undo/redo snapshots |
+| `pet.json` | Desktop pet window position |
+
+---
+
+## Key functions
+
+- **Desktop pet**: transparent frameless always-on-top window; drag to move; shake the head region left-right to trigger the "head-pat" easter egg; clicks/drags also fire FX.
+- **STT hotkey**: right Cmd on macOS, right Ctrl on Windows/Linux — hold for ≥ 2 seconds to start a one-shot recording.
+> Global keyboard listening requires Accessibility permission for Python (System Settings → Privacy & Security → Accessibility).
+
+> Computer Use screenshots require Screen Recording permission for the terminal.
+
+---
+
+## Slash Commands
+
+| Category | Commands |
+|---|---|
+| Session | `/new` `/clear` · `/resume` · `/exit` · `/export` · `/compact` |
+| Display | `/thinking` · `/details` |
+| Voice | `/tts` · `/stt` |
+| Extensions | `/skill` · `/mcp` |
+| Other | `/change-agent` · `/undo` · `/redo` · `/help` |
+
+---
+
+## Extensions
+
+- **Custom Skills**: place `SKILL.md` in `~/.arona/skills/<name>/`, then invoke with `/skill <name>`.
+- **MCP servers**: configure a JSON object in the `mcpServers` field of `~/.arona/settings.json`; tools are registered automatically.
+
+---
+
+## License
+
+This project is open-sourced under the [MIT License](LICENSE).
+
+---
+
+## Copyright
+
+This project is an independently developed unofficial project and is not directly affiliated with or endorsed by Nexon Games Co., Ltd., YOSTAR LIMITED, or the official Blue Archive game team.
+
+- The core project code is released under the MIT License. However, no license is granted by this project (or any third party) for any files within the assets/blue-archive/ directory. These files pertain to the intellectual property of Blue Archive and include, but are not limited to, character illustrations, artwork, audio files, text content, and related derivative assets. No warranty of legality or usability is provided for these assets.
+- The use, reproduction, and distribution of such content must strictly comply with the [rules](https://bluearchive.jp/fankit/guidelines) published by Nexon Games Co., Ltd. and YOSTAR LIMITED, as well as all applicable laws and regulations.
+- This project does not provide access to these third-party files. Users must obtain legitimate copies independently from the official channels of the rights holders and assume full responsibility for their use.
+- This project must not be used for distribution that infringes upon the rights of the copyright holders; any such infringement is the sole responsibility of the user.
+
+All intellectual property rights for such content belong to Nexon Games Co., Ltd. and YOSTAR LIMITED. Usage, reproduction, and distribution must strictly adhere to the official terms set by these rights holders and applicable laws.
+If a rights holder believes this disclaimer or the project's usage violates any terms, please contact me. Upon verification, the relevant content will be adjusted or removed promptly.