# Project Progress Tracking

**项目名称**: 223-236-template-6
**最后更新**: 2026-03-15

---

## 项目规模

| 指标 | 数值 |
|-----|------|
| Epic | 8 个 (7a + 7b) |
| 用户故事 | 66 个 |
| 总故事点 | 318 点 |
| FR 覆盖率 | 100% |
| PRD 需求 | 52 FRs + 43 NFRs |

---

## 完成阶段

#### 阶段 1：项目初始化
- [x] 项目创建
- [x] 基础文档结构设置

#### 阶段 2：需求分析
- [x] PRD 创建

#### 阶段 3：专家评审
- [x] 架构设计评审
- [x] Epic 与 Story 规划
- [x] UX 设计评审

#### 阶段 4：实现准备度验证与修复
- [x] 实现准备度完整评估
  - 文档完整性验证
  - PRD 分析（52 FRs, 43 NFRs）
  - Epic 覆盖率验证
  - UX 对齐评估
- [x] Epic 质量修复
  - 重写 Epic 目标为用户价值聚焦 (Epic 1, 2, 4)
  - 拆分 Epic 7 为 Epic 7a (调度) 和 7b (UI)
  - 补充 8 个缺失 Story (32 故事点)
- [x] UX 低保真线框图创建
- [x] 技术路线一致性修正

#### 阶段 0：技术验证 (Phase 0 Technical Verification)
- [x] m2m100 模型下载与配置
  - 从魔搭社区下载 m2m100-418M 翻译模型（1.9GB）
  - 模型路径：`/mnt/code/223-236-template-6/models/m2m100`
- [x] 翻译功能验证
  - 中→英翻译测试通过
  - 模型推理正常工作
- [x] CPU 模式性能测试
  - 翻译速度：~1160 字/分钟
  - 大规模测试：494字 → 25.55秒
- [x] 术语表功能验证
  - 14个术语条目测试
  - 术语替换效果显著
  - 保留率计算正常（93.4%）
- [x] Go/No-Go 决策：**✅ GO** - 可以进入 Sprint 开发

#### 阶段 4.5：Epic 优先级调整
- [x] Epic 4 (术语提取与替换) 提升为 **P0 优先级**
  - **原因**: Phase 0 验证确认术语表对翻译质量至关重要
  - **问题**: 没有术语表时，"林风"被译为"Lin wind"而非"Lin Feng"
  - **结论**: 术语表是保证翻译可用性的核心功能

---

## 下一步：Phase 1 开发计划 (3周)

#### 阶段 5：Phase 1 准备完成
- [x] Epic 1.1 Story 文件创建
- [x] Epic 4 Story 文件创建（P0 优先级）
- [x] setup.py 创建
- [x] requirements.txt 更新（添加 ML 依赖）
- [x] 代码结构验证

### Phase 1a: 基础架构核心 (2周)

**Epic 1.1: State Machine** (1周)
- Story 1.2: 实现 State Machine 任务状态管理 (8SP)
- Story 1.3: 实现 Repository 数据持久化抽象 (6SP)
- Story 1.5: 实现 Observer 模式进度通知 (4SP)

**Epic 1.2: Crash-Safe 机制** (1周)
- Story 1.1: 实现 Pipeline 编排框架 (5SP)
- Story 1.4: 实现 Crash-Safe 原子写入机制 (5SP)

### Phase 1b: 术语表功能 (1周，可与 1a 部分并行)

**Epic 4: 术语提取与替换** (P0优先级，30SP)
- Story 4.1: 术语表数据结构设计与术语识别 (6SP)
- Story 4.2: 术语匹配引擎 (5SP)
- Story 4.3: 术语预处理管道 (5SP)
- Story 4.4: 后处理去 `__en__` 前缀 + 术语还原 (5SP)
- Story 4.6: 术语翻译应用 (5SP)

**注意**: Story 4.5 (上下文标注) 可推迟到 Phase 2

---

## 后续阶段规划

- [ ] 阶段 5：Sprint 规划与开发 (Phase 2-7)
- [ ] 阶段 6：测试与部署

---

## 🔌 MCP 服务器配置说明

> **重要**：本项目使用 **HTTP 传输模式**，不是 stdio 模式。

### MCP 连接参数

| 参数 | 值 |
|------|-----|
| **传输模式** | HTTP |
| **端点路径** | `/mcp` |
| **本地端口** | 8080 |
| **外网端点** | `https://d8d-ai-vscode-8080-223-236-template-6-group.dev.d8d.fun/mcp` |

### 子代理调用 MCP 工具时注意

- ✅ **正确**: MCP 服务器已在后台运行，直接调用工具即可
- ❌ **错误**: 不要尝试启动新的 MCP 进程或修改 MCP 配置
- 📡 **协议**: HTTP（服务器已暴露 HTTP 端点）

---

## 📦 容器重启后操作指南

> **⚠️ 重要**：开发容器重启后，需要执行以下步骤才能正常使用 MCP 服务器和翻译功能。

### 步骤 1：启动 MCP 服务器

```bash
# 使用启动脚本（推荐）
./scripts/start_mcp_server.sh
```

### 步骤 2：验证服务器状态

```bash
# 检查进程和日志
ps aux | grep mcp_server
tail -f mcp.log
```

### 步骤 3：外层重新配置 MCP 连接

在本地（外层）执行：
```bash
/root/.local/bin/claude mcp remove novel-translator
/root/.local/bin/claude mcp add --scope project --transport http \
  novel-translator \
  https://d8d-ai-vscode-8080-223-236-template-6-group.dev.d8d.fun/mcp
```

### 🔧 依赖问题修复

| 问题 | 解决方案 |
|------|----------|
| chardet 缺失 | `pip3 install --break-system-packages chardet` |
| torch 安全漏洞 | 已升级到 2.6.0 |
| PYTHONPATH 错误 | 启动脚本已自动设置 |