开始前准备
需要 Windows 10/11 x64、网络连接，以及你自己的 LLM 和 DashScope 凭据。安装包已包含本地 Python 服务与 .NET 桌面运行文件。
最小可用路径：只配置 LLM 即可先验证文字对话；DashScope 用于实时 ASR 和两种 TTS 链路。
安装应用
下载安装包
从下载页获取 VirtualCompanion-Setup-0.2.0.exe，建议核对 SHA256。
运行安装程序
默认安装到 %LOCALAPPDATA%\Programs\VirtualCompanion，不要求管理员权限。
第一次启动
桌面壳会启动本地 FastAPI 服务，健康检查通过后再显示主页面。
完成首次配置
首启向导包含以下字段：
| 字段 | 是否必需 | 用途 |
|---|---|---|
| LLM API Key / URL / Model | 文字对话必需 | 调用 OpenAI 兼容的对话模型 |
| DashScope API Key | 语音能力必需 | ASR、Qwen3-TTS 与 CosyVoice |
| Workspace ID | 按账户情况 | 使用业务空间专属配置时填写 |
| OSS 配置 | 仅 CosyVoice | 托管声音复刻的公网参考音频 |
跳过向导也能进入应用，之后可在“服务设置”补充。密钥状态只以是否配置和掩码提示返回页面，不在设置接口响应中回传原值。
完成第一次文字对话
- 在左侧角色列表选择默认角色。
- 在底部输入框输入消息并发送。
- 确认回复文字逐步出现，而不是等待完整内容一次性返回。
- 对话完成后刷新页面，检查历史是否仍存在。
开启语音
点击“语音”进行一次识别，或点击“对话模式”进入自动监听。浏览器请求麦克风权限时选择允许。角色未注册音色时仍可正常文字聊天，只是不播放 TTS。
桌宠页面与主窗口是两个浏览器环境。第一次分别使用麦克风时，权限行为可能不同；应用仅对本机回环地址放行麦克风。
打开桌宠
- 在左侧工具区点击“弹出桌宠”。
- 等待 VRM 和动作资源加载完成。
- 拖动顶部半透明条移动，右键 3D 舞台打开菜单。
- 从右键菜单启动连续对话、恢复主窗口或退出桌宠。
- 在设置页分别调整舞台宽度、高度与默认待机动作。