个人资料头像与保存¶

Electron 克隆工作区在音频上传或录制后立即显示姓名和头像表单。保存会选中新资料；不使用保存则继续使用临时参考。更换语音会打开已保存语音选择器，且不会丢弃脚本。

已保存的语音使用紧凑的可选行，带有独立的预览/删除控件。脚本编辑器填满可用工作区；生成控件和紧凑的最新生成片段播放器保持固定在底部。在优化视觉效果时保留这一既定布局，而不是移动主要操作。参考面板包含已保存参考的播放功能。语言搜索在弹出层挂载后测量其虚拟列表。最新生成片段横跨整个内容面板。关闭它会停止其播放并清除当前播放器，但不会从历史记录中删除已保存的生成片段。

姓名首字母在本地根据资料名称的第一个和最后一个词生成。可选的 JPEG、PNG 和 WebP 上传文件限制为 5 MB 和 16 兆像素，裁剪为 256 × 256，并在不保留源元数据的情况下重新编码。头像与资料音频一同存放，文件名为 <id>.portrait.jpg；删除资料会同时删除其头像。参考面板和已保存资料编辑器允许通过上传或创建资料时使用的同一种显式五结果图片搜索来替换头像。

保存新的克隆资料后，Electron 会释放临时上传文件，并将编辑器切换到返回的资料，作为一次原子状态变更。返回的语言、风格和服务端通过本地 ASR 生成的转录文本成为编辑器元数据，因此删除或更改该资料不会恢复保存前的过期参考文件。

POST /profiles 接受可选的 image 多部分字段，并返回完整资料，包括 image_url。PUT /profiles/{id}/image 替换头像；GET /profiles/{id}/image 返回该头像。无需数据库迁移。

可选图片搜索¶

搜索仅在用户点击搜索图片时运行。它会将输入的名称发送到普通的 Google Images 搜索页面。无需 API 密钥。搜索会请求 SafeSearch 和 Google 的 JPEG 文件类型过滤器，然后返回最多五个有效的缩略图。缩略图通过与上传相同的资料图片流程进行解码、标准化并保存在本地；永远不会获取远程原始文件。

只接受该页面中 Google 的 HTTPS 缩略图代理主机和嵌入式 JPEG 预览。如果 Google 需要浏览器 JavaScript、同意或 CAPTCHA，VoiceStudio 会回退到 Openverse 的公共搜索，排除成人内容并应用适合再使用的许可过滤器。它绝不会绕过 Google 的验证。如果两个来源都没有响应，姓名首字母和文件上传仍然可用。过滤并不能保证每个结果都合适或获得再使用许可。

实况验证：node electron/tests/profile-image-search-real-smoke.mjs 会创建一个一次性的本地资料，打开其 Electron 编辑器，发起显式的无密钥搜索，验证五个可选头像，通过真实的图片端点持久化其中一个，验证标准化 JPEG 和刷新后的头像，然后删除该资料。

可恢复的生成失败¶

生成失败在编辑器中只出现一次，技术细节默认折叠。脚本会保留以供重试。共享音频写入器在写入前会重新创建缺失的父目录，包括后端启动后被删除的文件夹。

播放属于最新生成片段播放器。合成操作始终会启动生成；播放某个生成片段永远不会将该按钮替换为播放控件。合成按钮为标签和取消控件预留固定空间。按钮下方使用等宽数字显示已用时间。在请求进行期间，/model/status 提供本地化的运行时子阶段和模型加载百分比；当音频开始传输时，进度显示改由响应体提供。

语音选择器会明确标记当前激活的语音。语音样本会打开其参考面板，空脚本的提示语会包含所选语音名称。粘贴和插入仍是次要操作；插入操作的无障碍标签和工具提示会解释表达式令牌。这些改进保留了固定布局。

参考转录与编辑¶

保存资料视图使用编辑器的完整内容宽度。新上传或录制的参考使用所选本地听写流水线（包括其配置的 Parakeet/Whisper 回退）。转录前会检查已安装模型的就绪状态；不会主动发起模型下载。缺少模型时仍可手动输入转录文本，旁边是推荐模型的安装按钮（只有点击后才会开始下载，然后重试转录）。ASR 在运行期间绝不会覆盖用户编辑的文本。保存会等待转录完成；不保存直接使用参考仍然可行。

已保存语音的铅笔按钮，以及语音样本面板中选中语音上的编辑语音，会打开资料编辑器，用于编辑姓名、转录文本、风格、头像和参考样本。点击已保存语音仍然只选中它；编辑不会选中其他语音。语音样本面板的 V 形图标会折叠该面板；语音样本工具栏控件可重新打开它。

编辑器播放已存储的参考。对于克隆语音，替换参考接受与新建语音相同的格式和时长检查的上传或录制。保留当前参考会丢弃新剪辑。保存会将其写入同一资料。资料的 id、名称、头像、风格、语言和历史记录保持不变。选择新剪辑时转录文本字段会清空；留空将在本地转录新剪辑。替换参考还会清除语音的锁定的生成片段和本人语音验证，因为新剪辑可能来自不同的说话人。设计语音则通过其配方进行编辑。

PUT /profiles/{id}/audio（多部分字段 ref_audio，可选 ref_text、name、instruct、language 和 personality）将剪辑存储在新的 <id>-<token>.<ext> 文件名下，并在同一次数据库更新中保存其他字段，因此编辑器保存要么提交所有更改，要么什么都不提交。旧文件仅在数据库更新成功后才被删除。新文件名还会使引擎提示缓存和有声书章节缓存失效，因为这些缓存以参考路径为键。资料记录包含带版本的 audio_url，以便播放器重新加载新剪辑，GET /profiles/{id}/audio 按各自的媒体类型返回每个剪辑。该路由接受 WAV、MP3、M4A、FLAC、OGG、Opus、AAC 和 WebM 格式，最大 128 MiB，并要求 libsndfile 或 FFmpeg 在剪辑替换旧文件之前解码真实样本；两者都无法解码的文件返回 422。同一语音的替换一次只运行一个，上传期间若另一写入者更改了剪辑则返回 409。设计语音返回 409。参考被替换的 Gallery 或 Community 语音计作用户自己的编辑：再次导入同一语音会创建单独的资料，并保持已编辑的资料不变。无需数据库迁移。

侧边栏列出所选的 TTS、ASR 和 LLM 引擎、在可用时解析出的模型标识，以及所选已安装的听写模型。这些只是选择项，并不表示模型权重当前已加载。

引擎更改控件会打开设置 / 模型页面，其中包含独立的 TTS、ASR、听写和 LLM 页面。列表独立于设置侧边栏滚动；不可用的引擎和未下载的听写模型无法选择。引擎选择使用共享的后端偏好设置，并刷新侧边栏元数据。

脚本导入支持 TXT、Markdown、DOC、DOCX、PDF 和 EPUB（文本类文档，而非扫描图像 OCR）。粘贴会在插入符处插入内容；替换脚本提供撤销功能。点击脚本会在插入符附近显示表达式选择器，且不会夺取输入焦点。语音选择器和保存配置文件表单共享编辑器宽度。

删除已保存的语音会先提交配置文件和历史记录更改，再移除其引用、锁定的录制片段、同意录音和肖像。数据库事务失败时，这些资源仍保持可用。删除成功后的清理为尽力而为；某个资源不可用不会阻止其余资源的清理。

如果配置文件记录删除后清理失败，响应会报告清理不完整，并列出相对于 voices 文件夹的剩余受限路径（包括嵌套位置）。如果某个位置不再受限，响应会引导操作员查看本地后端日志，而不是暴露主机路径。后端日志会记录其本地位置以供手动清理，并将主目录前缀以 ~ 代替。Electron 在出错后会刷新已保存语音列表，并且仅当该列表确认配置文件已不存在时，才会清除所选的克隆/设计引用；现有错误消息仍会报告资源清理不完整。再次删除缺失的配置文件不会重试其之前的音频文件；不承诺自动重试清理。

如果在删除错误期间后端变得不可用，错误会立即结束，而确认会在受管的已保存语音查询中等待。后端就绪后会恢复该查询。只有确认缺失的成功列表才会清除所选语音；回滚、确认失败和查询取消都会保留它。此刷新不会重试资源清理。

批量删除期间的错误按顺序逐一检查，因此后来的错误不会丢弃先前的删除检查。停滞 30 秒的确认请求会被取消，以便后续检查继续；超时的检查会保留其语音选择，因为缺失状态仍未知。离线状态下暂停的时间不计入此请求限制。清除查询客户端缓存会取消来自先前缓存生命周期的检查。