SoulCast 入门使用教程

SoulCast 是一款本地优先的 AI 对话与角色扮演应用：自备 API Key，即可与助手聊天，或创建角色卡开启沉浸式扮演。

本教程按产品使用顺序说明：初始化 → 基础配置 → 基础 AI 对话 → 角色扮演对话 → Sherpa-ONNX 本地语音。读完后即可完成首次可用配置，并开始两类对话。

1. 初始化

1.1 打开应用

1. 启动 SoulCast。
2. 短暂显示启动页（图标与「SoulCast」），状态依次为「正在启动…」「正在进入应用…」「启动完成」。
3. 自动进入主聊天页。

无需注册或登录即可使用。对话、角色、配置等数据默认保存在本地设备。

1.2 认识主界面

应用以主聊天页为中心，通过左侧抽屉管理会话与功能：

主聊天页
 ├─ 左侧抽屉（菜单）
 │   ├─ 新聊天
 │   ├─ 角色管理
 │   ├─ 文件库
 │   ├─ 最近会话
 │   └─ 设置
 └─ 顶栏「会话信息」

空会话时会看到引导文案：「有什么想聊的？在下方开始一段新对话。」
底部输入框占位为「问问SoulCast」。

重要： 首次打开即可浏览界面，但要真正收到 AI 回复，必须先完成下一章的供应商与模型配置。

2. 基础配置

入口：主页左上角打开抽屉 → 底部 设置。

2.1 建议先做的通用设置（可选）

在 设置 中可按需调整：

2.2 必做：配置 AI 供应商与模型

没有可用模型时，发送消息会提示先配置供应商或选择模型。请按下列步骤完成。

步骤 A：新增供应商

1. 设置 → 供应商配置
2. 点击 新增供应商（也可使用 导入供应商 粘贴 JSON）
3. 填写：
   • 供应商名称：如 OpenAI、DeepSeek、OpenRouter
   • Base URL：如 https://api.openai.com
   • API 路径：如 /v1
   • API Key：你的密钥
   • 请求协议：Chat Completions 或 Responses（按服务商支持选择）
4. 保存供应商

步骤 B：添加并启用模型

1. 在供应商配置页切换到 模型 页签
2. 使用 获取模型 从服务商拉取列表并添加，或手动 新增模型
3. 为模型设置 输入格式 / 输出格式（文本对话至少勾选「文本」；需要生图时再勾选「图片」）
4. 打开 启用模型 并保存

步骤 C：在聊天页选择模型

1. 返回主聊天页
2. 在输入区点击模型按钮（可能显示「选择模型」）
3. 在列表中选中刚启用的模型

至此，基础 AI 能力已就绪。

2.3 常用进阶设置（可选）

完成必做项后，可按需要再调：

工具是否在某次对话中启用，请在聊天页底部的 工具 / MCP 面板中切换；密钥类配置在设置里完成即可。

3. 基础 AI 对话

普通会话使用应用级助手人格（默认可在 设置 › 提示词 中调整），适合问答、创作、工具调用等日常用途。

3.1 开始一段新对话

任选其一：

• 在当前空会话中直接输入；或
• 打开抽屉 → 新聊天

确认输入区已选中可用模型。

3.2 发送与控制

1. 在「问问SoulCast」中输入内容
2. 点击 发送
3. 生成过程中可点击 停止 中断

常用附加能力：

• 语音输入：需先在设置中下载语音模型并设为默认，并授予麦克风权限
• 输入 @ 打开 插件 菜单（如 创建图片）
• 工具 面板：开关内置 Agent 工具（时间、位置、天气、地图、生图等，视配置而定）
• MCP 面板：开关已连接的远程工具

3.3 管理会话

打开抽屉查看 最近：

• 置顶 / 取消置顶
• 重命名
• 查看信息
• 删除（同时清除该会话消息）

首轮有效对话后，系统可能自动生成会话标题。

3.4 会话信息

顶栏进入 会话信息，可查看或编辑：

• 基础配置：摘要、会话系统提示词、会话世界书、清空对话
• 长期记忆：按分类管理（关系、世界观、剧情进展、偏好、约束、其他）

「清空对话」只删除聊天消息，会保留基础配置与长期记忆。

3.5 消息操作

对助手消息通常可：

• 重新生成、在多个版本间切换
• 中断后继续回复
• 复制
• 播放（需配置默认 TTS）

4. 角色扮演对话

角色扮演基于角色卡：名称、人设、场景、开场白等会注入扮演提示，聊天页也可使用角色头像作为沉浸背景。

4.1 创建角色

1. 抽屉 → 角色管理
2. 点击 新建角色（也可 导入角色卡，支持 JSON / PNG）
3. 填写或生成角色信息后 保存

方式一：AI 辅助生成（推荐上手）

1. 编辑页使用 AI 辅助生成
2. 用一两句话描述创意，例如：「傲娇的狐仙巫女，住在古寺」
3. 选择文本模型 → AI 生成
4. 检查自动填充的字段，按需修改后保存

方式二：手动填写

主要分区与字段：

头像可从相册、文件库选择，或用 AI 根据提示词生成（需已配置支持图片输出的图像模型）。

绑定 世界书 前请先保存角色；世界书条目可按关键词在对话中触发补充设定。

4.2 开始角色聊天

1. 在 角色管理 中点选角色，或选择 开始聊天
2. 若有多条开场白，在底部弹层中 选择开场白
3. 应用会创建新的角色会话（标题一般为角色名；每次开始聊天都会新建会话，不复用旧会话）
4. 若配置了开场白，会先出现一条助手开场消息，然后进入主聊天页继续扮演

角色会话与普通会话的主要差异：

角色会话中，深度思考类展示可能显示为「内心戏」。在会话信息中可进入 编辑角色，或查看该会话的长期记忆与世界书绑定。

4.3 让扮演更沉浸（进阶）

1. 设置 › 世界书：创建设定库与关键词条目
2. 在角色页绑定主/附加世界书，或在会话信息中绑定会话世界书
3. 按需调整 设置 › 提示词 中的角色扮演相关模板
4. 开启合适的 记忆写入频率，让关系、剧情等长期信息自动沉淀

5. Sherpa-ONNX 本地语音

SoulCast 的语音识别（ASR）与语音合成（TTS）基于 Sherpa-ONNX，模型在设备本地运行，不经过云端语音服务。应用不会内置下载地址，需要你自行粘贴官方模型压缩包 URL。

5.1 能力与入口

当前适配范围：

• ASR：流式 Online Transducer（常见为 streaming zipformer / zipformer2 包，目录内需有 encoder / decoder / joiner 与 tokens.txt）
• TTS：VITS、Matcha、Kokoro、Pocket、Supertonic

暂不支持：离线非流式 ASR、仅 CTC 的流式包、以及未适配家族的 TTS 包。

5.2 安装模型（通用步骤）

1. 打开 设置 › 语音模型
2. 点击 添加模型
3. 选择类型：语音识别 (ASR) 或 语音合成 (TTS)
4. 粘贴模型压缩包下载地址（支持 .tar.bz2 / .zip）
5. 可选填写显示名称 → 添加
6. 在列表中点 下载，等待「解压中」变为 已就绪
7. 对该模型点 设为默认（ASR、TTS 各需一个默认项）

默认 ASR 就绪后即可语音输入；默认 TTS 就绪后即可播放消息。

5.3 语音输出设置（TTS）

设置 › 语音输出：

非 Pocket 模型一般只需选好说话人与语速即可。

5.4 推荐模型

下列地址来自 Sherpa-ONNX 官方 Release，可直接粘贴到「下载地址」。完整列表见：

• ASR：asr-models
• TTS：tts-models
• 说明文档：Pre-trained models

ASR（语音输入）— 优先选流式 Zipformer Transducer

新手默认建议：先装 zh-int8-2025-06-30，设为默认 ASR。

不要选名字里带 ctc、或非 streaming 的离线包——当前应用按流式 Transducer 解析，这类包无法正常用于语音输入。

TTS（消息朗读）— 优先选中文 VITS

新手默认建议：先装 vits-icefall-zh-aishell3，设为默认 TTS，再到 语音输出 里试几个说话人 sid。

角色向可再试官方角色音色包（如 vits-zh-hf-keqing、vits-zh-hf-eula 等，同在 tts-models Release）。

5.5 快速验收

1. ASR：聊天页点 语音输入 → 授权麦克风 → 说一句中文 → 输入框出现识别文字 → 发送
2. TTS：对一条助手消息点 播放 → 能听到朗读；可在 语音输出 调整说话人与语速

5.6 使用注意

• 模型文件较大，建议在 Wi‑Fi 下下载；下载与解压期间可保持 App 在前台。
• ASR / TTS 默认项相互独立，需要分别 设为默认。
• Pocket TTS 未配置参考音频时无法合成，请到 语音输出 › 参考音频 选择包内样例或导入 .wav。
• vits-melo-tts-* 等包若内含有问题的 model.int8.onnx，部分机型可能异常；中文场景优先用上表的 icefall / aishell3 推荐项。
• 本地模型占用可在 设置 › 存储空间 中查看与清理。

6. 常见问题

7. 推荐上手路径（约 10 分钟）

1. 打开 App，进入主界面
2. 设置 › 供应商配置：填好 Base URL 与 API Key，添加并启用至少一个文本模型
3. 主聊天页选择模型，发送一句「你好」，确认普通对话可用
4. 角色管理 › 新建角色：用 AI 辅助生成一个角色并保存
5. 开始聊天，选择开场白，进入角色扮演继续对话

完成以上步骤后，即可按需探索世界书、长期记忆、工具与语音等进阶能力。若要用语音输入 / 朗读，详见第 5 章。