# EchoVerse

**Repository Path**: eltongu/echo-verse

## Basic Information

- **Project Name**: EchoVerse
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-01
- **Last Updated**: 2026-10-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EchoVerse

EchoVerse 是一个 local-first 的桌面有声书制作工具：用户导入 TXT 或标准、未加密的 EPUB，在本地整理章节和旁白文本，使用本地 TTS 生成音频，并按章节导出 WAV 文件与 manifest。

> 当前仓库处于首期实现阶段。产品范围、架构边界和开发规则已经确定，应用功能正在按 handoff 逐步实现。

## 当前范围

首期目标包括：

- TXT 和标准、未加密 EPUB 导入
- 章节提取、重命名、排序、拆分和合并
- 保留原文的段落级旁白稿编辑
- 本地 Qwen3-TTS provider，位于隔离的 provider/worker 边界之后
- 可恢复的串行生成、暂停、取消、重试和状态持久化
- 章节级 WAV 导出与稳定的 manifest
- 可迁移的版本化项目目录和相对路径
- 已完成章节的播放与部分导出

首期明确不包括：

- MP3 编码、章节 MP3 和全书 MP3 合并
- Ollama provider
- 云端 TTS、云端内容处理或自动发布
- DRM 绕过
- Windows 支持声明（Windows 验证尚未完成）

## 项目状态

- 产品基线：`PRD-0002`，修订 `PRD-0001`
- 系统架构：`ARCH-0001`
- 技术决策：`ADR-0001` 至 `ADR-0005`
- 开发 handoff：已批准，可在批准范围内开始实现
- 当前验证平台：macOS
- Windows：延期验证，不能将 macOS 结果视为 Windows 证据

## 文档导航

从以下入口开始：

- [使用手册](docs/user-manual.md)：当前桌面版本的安装、导入、生成、播放和导出操作
- [当前阶段进度评估](docs/implementation/current-stage-progress.md)：按批准路线图和验收证据估算的阶段完成度
- [Agent 入口规则](AGENTS.md)：仓库级开发约束和文档入口
- [治理规则](docs/governance/README.md)：唯一权威的审批、升级和冲突处理规则
- [实现文档索引](docs/implementation/README.md)：当前有效的 PRD、ADR、验收、路线图和 backlog
- [开发 handoff](docs/implementation/developer-handoff.md)：已批准的实现边界和第一批任务
- [开发 backlog](docs/implementation/developer-backlog.md)：开发团队任务列表
- [验收矩阵](docs/implementation/acceptance-matrix.md)：需求到验证证据的对应关系
- [系统架构](docs/baseline/system-architecture.md)：模块边界和数据流
- [产品需求](docs/baseline/product-requirements.md)：当前产品范围和验收要求

归档目录中的草案只用于保留历史，不是当前实现依据：

- [已取代的草案](docs/implementation/archive/superseded/)

## 开发 Agent 首次对接

第一次接手时，不要直接假设模块或文件。请先让 agent 阅读仓库规则和 handoff，检查当前代码结构、测试和 Git 状态，再提出第一个可独立验收的任务。

可直接使用以下提示词：

```text
你现在接手 EchoVerse 开发工作。

请先不要直接修改代码。先完成仓库熟悉和任务分析：

1. 阅读 AGENTS.md、docs/governance/README.md、
   docs/implementation/README.md、
   docs/implementation/developer-handoff.md、
   docs/implementation/developer-backlog.md，
   以及与首个任务相关的 PRD、ADR 和 acceptance-matrix。
2. 检查当前仓库结构、已有代码、测试、Git 状态和最近提交。
3. 根据当前 handoff 和 backlog，找出第一个边界清晰、可独立验收的实现任务。
4. 先报告：当前项目状态、建议任务、选择理由、预计改动范围、验收条目、
   测试方式、依赖、风险和需要维护者确认的问题。

约束：
- 在已批准的 PRD、ADR、验收标准和模块契约内自主拆解、实现和测试。
- 首期只做 chapter WAV 和 manifest；MP3 延期。
- 不得引入或恢复 Ollama。
- Windows 尚未验证，不得声称 Windows 已支持。
- 不要提交模型权重、音频产物或机器特定路径。
- 不要直接修改 docs/baseline/、docs/adr/、
  docs/governance/project-constraints.md 或
  docs/governance/acceptance-criteria.md。
- 如果需要改变产品要求、公开接口、持久化格式、跨模块行为、架构或治理规则，
  只暂停受影响部分并向维护者说明；不要自行把它变成新的项目规则。

这次先完成分析报告，等维护者确认第一个任务后再开始实现。
```

## Branch 与 PR 规则

分支和 PR 按功能批次管理；完整规则及例外流程见 [治理规则](docs/governance/README.md#branch-and-pull-request-workflow)。

## 本地检查与提交

在提交前安装本地 hook：

```bash
scripts/install-hooks.sh
```

提交使用仓库脚本：

```bash
scripts/commit.sh -m "<commit message>"
```

该脚本会运行治理检查和治理回归测试。开发完成时还应报告：

- 修改的文件和实现内容
- 关联的 acceptance-matrix 条目
- 测试命令及结果
- 未完成项、风险和未验证的平台

## 治理原则

维护者是产品、架构和治理决策的最终批准人。开发 agent 可以在已批准边界内自主工作；普通实现细节不需要逐项审批。涉及公开接口、持久化格式或跨模块行为时，需要维护者确认；涉及产品、架构、治理或受保护文档时，需要正式决策记录。

如果规则冲突，只暂停依赖该规则的任务，无关工作可以继续。完整规则以 [docs/governance/README.md](docs/governance/README.md) 为准。

## 许可证

许可证尚未在当前项目基线中确定。