询问 VoiceStudio 智能体¶

Electron 启动器会在应用内打开一个可调整大小的聊天工作区。选择一个已安装的 Codex、Claude Code、OpenCode 或 Pi 执行环境，然后描述任务。功能标签提供针对设置、修复、声音克隆、声音设计、配音、转录、故事、有声书、工作流和音频工具的聚焦指令。启动卡片会预填请求但不会执行它。使用 Send（Enter）运行；Shift+Enter 换行。

Autopilot 执行所请求的受支持应用操作并验证其结果。Plan 通过只读 API 能力检查应用状态。普通聊天即使在源码构建中也使用临时应用工作区：应用设置、生成或诊断无需源码检出。Features > Allow source-code repair 明确选择加入附加的可写检出以及所选执行环境的源码编辑权限。

回复以聊天消息形式流式输出。后续轮次会接收最近十二条非空消息，每条限制为 4,000 个字符。对话和草稿状态在本应用会话期间跨工作区导航和停靠栏折叠保持；New chat 会清除它们。它们不会持久化到磁盘。所选执行环境会接收当前请求、最近对话、当前路由、最近的渲染器/后端日志和诊断信息。执行环境可以使用其配置的提供商账户。仅打开面板或选择预设不会启动任何执行环境。

每次运行还会收到一个临时连接文件，用于应用拥有的回环 API 网桥。该网桥以当前附加到 VoiceStudio 的后端为目标，在 Electron 主进程内注入远程身份验证，并且只给智能体一个每次运行随机的能力。诊断网桥拒绝变更方法。两种模式下都阻止身份验证路由，并且当运行停止时，网桥、能力和连接文件都会被移除。这使得经授权的 Fix 可以选择引擎、安装模型并验证实时状态，而无需在提示、智能体输出或子环境中放入真实后端地址或 Bearer 令牌。

连接文件还列出了按能力限定的 Electron 控件，用于读取监督状态、重启后端和恢复运行时设置。当 Python 不可用时这些控件仍然可访问，因此后端故障界面保持修复坞挂载，其 Fix 操作可以在使用普通后端 API 之前恢复运行时。故意不提供干净重装，因为它会移除拥有的运行时，并且仍然是明确的 Clean Retry 决定。

设置阻塞器会在调用智能体之前使用受支持的应用操作。例如，在缺失文本转语音通知上的 Fix 会选择已安装的兼容引擎或启动设备感知的所需模型安装器，将该本地或远程任务跟踪到完成，刷新每个挂载的工作流，并激活引擎。安装器或激活失败会成为 ACTION_REQUEST，交给用户已选择加入的默认智能体处理，并已附上当前路由和日志。点击 Fix 是该恢复的明确授权；仅仅查看通知不会改变任何内容。在 Clone 和 Voice Design 合成器上，相同的恢复是主要的 Set up 操作，它会替换 Synthesize 直到文本转语音就绪；在其他地方完成的模型会在 15 秒内清除它。Dubbing、Dictation 和 Voice Conversion 中未解决的 ASR 设置会暴露相同的智能体操作，同时保持准备好的媒体、选定的声音和重试状态不变。Voice Design、声音比较和已保存配置文件预览使用相同的紧凑一键 TTS 恢复，而不是将用户发送到设置页面。参考音频 ASR、精确文件转录和实时听写模型故障会暴露相同的免检出操作，同时保留选定的媒体、可编辑转录和重试状态。

对于免检出的应用操作，智能体从网桥 OpenAPI 文档中发现受支持的操作，根据当前硬件和推荐选择普通的模型和引擎设置，并验证最终状态。在 Autopilot 中发送的设置请求授权其所需的模型下载和引擎选择。许可证、凭证、隐私或遥测同意、数据删除和远程后端连接仍然是明确的用户决定；智能体会在该决定前停下，而不是默默替用户填写。

带 workspace: app 的聊天请求和遗留的 ACTION_REQUEST 恢复运行会在没有源码检出的情况下操作打包应用。智能体在隔离的临时目录中启动，只能访问会话网桥，不能使用身份验证路由，并被指示检查、执行和验证所请求的应用操作，而不编辑用户文件。Codex 在这些会话中保持其工作区沙箱，并启用网络访问以便到达回环网桥。其自动审查模式拥有该工作区写入沙箱；VoiceStudio 不会同时传递 Codex 互斥的显式沙箱标志。Claude Code 和 OpenCode 会收到按运行生成的 MCP 配置，其默认权限为拒绝；它们的免检出会话只能调用 VoiceStudio 的限定范围 API 工具，不能调用 shell 或文件系统工具。MCP 进程从受保护的连接文件读取能力，因此令牌永远不会出现在智能体参数、配置或输出中。

明确的源码诊断和代码修复需要可写的 VoiceStudio 源码检出，并且必须遵循其 AGENTS.md、CLAUDE.md、CONTEXT.md 和已安装的技能。源码构建会自动选择当前检出。打包构建只在实际需要源码工作时要求用户选择检出，并记住该位置（参见 源码检出）。

修复提示禁止打开 issue、推送、发布、合并或创建拉取请求。成功的修复以审查提示结束，以便用户可以在决定是否提议 PR 之前检查 diff 和针对性测试。仅应用恢复则报告已验证的应用状态和任何剩余的用户输入；它永远不会呈现分支或拉取请求指导。

渲染器崩溃时会打开 dock 面板，并显示经过脱敏的错误和堆栈。如果没有以前选择的 harness 可用，预填的聊天会等待点击 Send。开始一次运行会保存本地 harness 选择；之后的渲染器崩溃会自动启动可用的默认代理。如果代码修复缺少源码检出，或所选代理缺失，dock 面板会保持打开并请求相应的先决条件，而不是丢弃这次失败。仅应用内恢复不会显示或需要源码选择器。瞬时的动态模块获取失败只会执行一次受控的渲染器重载，让模块加载器真正重新获取该 chunk。一个会话标记会在重载后保留，所以只有同一失败重复出现时才会触发代理恢复，不会出现重载循环。

同一时间只运行一个代理进程，包括准备会话和翻译会话。Stop 会取消准备，或终止正在运行的进程树。输出会保留在当前应用会话中，并流式传输到 dock 面板；来自受支持 CLI 的 JSON 事件格式会被简化为可读的代理和工具输出。

验证：electron/src/main/repair-api-bridge.test.ts 证明真实的远程凭据绝不会进入代理连接文件，伪造的凭据会在 main 进程内被替换，诊断保持只读，认证路由保持禁用，Electron 的重启/设置控制无需 Python 即可使用，干净重装仍不可用，teardown 会移除该能力。
electron/tests/native-repair-agent-smoke.mjs 冒烟测试会启动一个隔离的 Electron shell，检查原生桥接和源码检出，验证已检测到的代理控件，断言关闭后的启动器保持在右边缘居中，并确认本地化的更新频道标签在渲染时不会出现原始键。
electron/tests/error-recovery-smoke.mjs 验证就地渲染恢复、一次性 chunk 重载、脱敏后的重复失败证据以及自动修复交接。这两个冒烟测试都不会启动代理或修改检出。
electron/src/shared/repair-request.test.ts 界定了无需检出的应用操作与受源码限制的诊断或代码修复之间的边界。
node electron/tests/packaged-repair-agent-smoke.mjs 使用干净的 profile 启动打包后的应用，确认不存在源码检出，保持应用操作 Send/Plan 可用，并验证 Electron 主进程仍然拒绝普通的源码修复请求。
node electron/tests/packaged-repair-operation-acceptance.mjs <agent> 是针对已安装 CLI 和已在运行的打包后端的一项可选现场验收测试。它通过受限桥接执行一次只读的 TTS 就绪检查，并且不会启动任何下载。Windows 打包运行在 Codex、Claude Code 和 OpenCode 上通过；验证主机上未安装 Pi。harness 会根据平台选择原生包和后端端口。一次打包的 Ubuntu 26.04 运行还证明，注入到 WSL 的 PATH 中的 Windows OpenCode npm shim 会被拒绝，而不会被当作可用的 Linux 代理暴露；仍需要使用原生 Linux CLI 进行验收。

错误报告会尽可能包含脱敏后的后端异常类，这些异常类来自流式错误帧或解析后的 API 错误响应。这可以区分原本完全相同的通用引擎故障；缺失或非文本的类值会被省略。

源码检出¶

代码修复会编辑 VoiceStudio 的源码，因此代理需要你自己拥有的仓库副本：源码检出。已安装的应用（例如 /Applications/VoiceStudio.app、C:\Program Files\VoiceStudio 或 AppImage）包含的是打包后的文件，而不是源码，因此无法编辑。从 GitHub 下载的 ZIP 也不是检出，因为它没有可供 diff 的 git 历史。请用以下命令创建一份：

git clone https://github.com/debpalash/VoiceStudio.git

然后打开 Allow source-code repair，点击 Choose folder…，选择新的 VoiceStudio 文件夹。选择你运行 git clone 的文件夹，或克隆内的任意子文件夹也可以：VoiceStudio 会找到克隆根目录。选择过程不需要构建、Python 环境或 bun install。

被拒绝的文件夹会在选择器下方显示原因：

该检查在 macOS、Windows 和 Linux 上相同：文件夹必须位于 git 仓库内，且仓库根目录包含 backend/main.py、electron/package.json 和 package.json；VoiceStudio 还必须能在该文件夹中创建（并立即删除）一个文件。验证：electron/src/main/source-checkout.test.ts 和 voice-studio-agent.test.tsx。

短有声书测试¶

使用 samples/audiobook-agent-smoke.txt，这是一个原创的四段叙述测试样本，段落分隔清晰。选择 Audiobook，粘贴文本，并使用现有的已保存声音请求一个简短预览。验证返回的项目和音频，而不是启动整本书。此示例不包含作为 URL 提供的受版权保护书籍中的文本。

自动渲染器崩溃修复使用源码工作区。未附加检出时，它会打开源码文件夹控件并保留该请求；选择一个检出并按 Send 即可继续。显式的应用操作请求继续使用无需检出的应用工作区。