VoxType AGENTS.md

VoxType AI 维护指南

本文件是 VoxType 的 AI 编码助手工作规则。 所有 AI 修改代码前，必须先阅读本文件。

VoxType 是一个 Windows 桌面语音输入工具。核心链路是：

触发录音 → 麦克风采集 → 豆包流式 ASR → 可选 LLM 润色 → 写入剪贴板 → 自动粘贴 → 恢复剪贴板 → 统计与日志

项目目标：实用、轻量、易维护。避免过度抽象、过度重构和不必要依赖。

---

1. 不可破坏的主链路规则

以下规则不得回退：

1. 空识别必须进入失败态，不得显示“已粘贴”，不得触发润色、粘贴或成功统计。
2. 只有 LLM 已启用、文本长度达到 min_chars，且 Base URL、API Key、模型名完整时，才显示“正在润色文本”。
3. 悬浮字幕只显示实时字幕、耗时状态和错误提示；不得显示“正在粘贴”“已粘贴”等瞬时状态。
4. 写入剪贴板失败时，必须给用户兜底提示；如果文本已复制，应提示用户可手动 Ctrl + V。
5. 统计不得记录识别正文，只能记录时长、字数、速度等非正文数据。
6. 日志和诊断报告默认不得包含真实密钥、识别正文、热词、prompt、最近上下文正文或 Windows 用户名路径。
7. 最终输出必须等待豆包最终包；实时字幕和中间包只作反馈，不得进入润色、粘贴、最近上下文、自动热词历史或成功统计。
8. definite=true 二遍分句用于稳定最终文本，但不能压掉更完整且高度重合的最终包整段文本；最终包补齐开头或尾字时应优先保留最终包。
9. 识别速度优化优先通过首字加速、OCR 超时折中、响应轮询和字幕节流实现，不得为了体感速度把默认 ASR 音频分片改离豆包建议的 100-200ms 范围，默认 200ms 不应轻易缩短。
10. 尾字真实被切断时，优先调整停录尾音窗口和 flush/负包链路，不得用中间 ASR 文本兜底成功。

ASR 速度、识别效果、OCR 等待、尾音和最终包选择相关改动，还必须参考 docs/asr-quality-latency-guardrails.md。

---

2. 不可回退的默认策略

以下默认值不得改回激进状态：

1. 最近上下文默认关闭。
2. 右 Alt 触发默认关闭。
3. 鼠标中键触发默认关闭。
4. 录音期间静音系统声音默认关闭。
5. 最终识别正文默认不打印到控制台。
6. 自动粘贴后默认尝试恢复原剪贴板。

---

3. 代码修改原则

1. 一个任务只解决一个问题。
2. 不要顺手重构无关文件。
3. 不要在同一次修改中同时改 ASR、剪贴板、热键、UI 大结构和配置结构。
4. 不要新增没有必要的依赖。
5. 不要把用户可见文案写死在业务逻辑中，应优先放到 i18n。
6. 不要在首页展示内部路径、协议细节、debug 状态或内部错误堆栈。
7. 修改配置项时必须同步 Rust 默认值、配置模板、前端设置项、三语言文案和 README。
8. 修改用户可见行为时必须同步 README 或相关 docs。
9. 修改用户配置、功能说明、排障流程或发布流程时，应同步检查 README、README.en.md、Wiki 和 docs/wiki/ 草稿。
10. 修改主链路时必须说明影响范围和手工验证步骤。
11. 若不确定，应先输出方案，不要直接改代码。

---

4. 目录职责

前端

• src/routes/+page.svelte：当前主页面入口。可以小范围修改，但不要继续塞大型新功能。
• src/lib/components/：新增 Svelte 组件应放这里。
• src/lib/i18n/：三语言文案和错误码文案。
• src/lib/：可放前端纯函数、格式化函数、状态映射函数。

Rust / Tauri

• src-tauri/src/session.rs：录音会话状态机。
• src-tauri/src/audio.rs：麦克风采集。
• src-tauri/src/asr.rs：ASR 请求组装、上下文和结果解析。
• src-tauri/src/asr_ws/：豆包 WebSocket ASR 会话、音频发送、最终文本和错误映射。
• src-tauri/src/llm_post_edit.rs：LLM 润色。
• src-tauri/src/text_output.rs：剪贴板写入和模拟粘贴。
• src-tauri/src/hotkey.rs：全局热键、右 Alt、鼠标中键输入钩子。
• src-tauri/src/config.rs：配置模型、加载、保存、校验。
• src-tauri/src/app_log.rs：日志与脱敏。
• src-tauri/src/stats.rs：非正文统计。
• src-tauri/src/overlay.rs：悬浮字幕。
• src-tauri/src/tray.rs：系统托盘。