blank/CLAUDE.md

Project Progress Tracking

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

---

项目规模

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

---

完成阶段

阶段 1：项目初始化

• 项目创建
• 基础文档结构设置

阶段 2：需求分析

• PRD 创建

阶段 3：专家评审

• 架构设计评审
• Epic 与 Story 规划
• UX 设计评审

阶段 4：实现准备度验证与修复

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

阶段 0：技术验证 (Phase 0 Technical Verification)

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

阶段 4.5：Epic 优先级调整

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

---

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

阶段 5：Phase 1 准备完成

• Epic 1.1 Story 文件创建
• Epic 4 Story 文件创建（P0 优先级）
• setup.py 创建
• requirements.txt 更新（添加 ML 依赖）
• 代码结构验证

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 服务器

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

步骤 2：验证服务器状态

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

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

在本地（外层）执行：

/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 错误	启动脚本已自动设置