From 6dea6cdc149e6ef4a351b3ddefb73c969cf158d6 Mon Sep 17 00:00:00 2001 From: Hubert Date: Tue, 3 Feb 2026 13:46:54 +0800 Subject: [PATCH] feat: Add PRD with OCR and translation features Add product requirements document for ScreenTranslate app: - US-001: Base architecture (menu bar + screenshot) - already implemented - US-002: Local OCR using Vision framework - US-003: Local translation using Apple Translation API - US-004/005: Overlay rendering (in-place and below modes) - US-006/007: Settings panel (engine selection + language config) - US-008/009: Optional PaddleOCR and MTranServer integration - US-010: Translation history - US-011: First-launch onboarding Architecture prioritizes local processing (Vision + Apple Translation) with optional external engines for advanced users. Co-Authored-By: Claude Opus 4.5 --- tasks/prd.json | 262 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 262 insertions(+) create mode 100644 tasks/prd.json diff --git a/tasks/prd.json b/tasks/prd.json new file mode 100644 index 0000000..9a672fe --- /dev/null +++ b/tasks/prd.json @@ -0,0 +1,262 @@ +{ + "name": "macOS ScreenTranslate", + "description": "A macOS menu bar app for screen region OCR and translation using local Vision OCR, Apple Translation API, with optional PaddleOCR and MTranServer support", + "branchName": "ralph/macos-screentranslate", + "userStories": [ + { + "id": "US-001", + "title": "基础架构 - 菜单栏应用与截图功能", + "description": "As a user, I want a menu bar app that can capture screen regions via global hotkey so that I can select any area for OCR processing.", + "acceptanceCriteria": [ + "菜单栏图标（StatusBarItem），点击显示下拉菜单", + "全局快捷键 Cmd+Shift+T 触发截图", + "快捷键可在设置中修改", + "快捷键触发后进入截图模式，屏幕变暗", + "鼠标拖拽绘制选区，实时显示选区边框", + "支持按 Esc 取消截图", + "支持 Retina 屏幕，截图分辨率正确", + "选区确定后获取截图数据", + "swift build passes", + "swift test passes", + "swiftlint passes" + ], + "priority": 1, + "passes": true, + "dependsOn": [], + "notes": "基于现有项目架构", + "completionNotes": "当前项目已实现" + }, + { + "id": "US-002", + "title": "本地 OCR 引擎 - Vision 框架", + "description": "As a user, I want text to be recognized locally using macOS native Vision framework for privacy and zero configuration.", + "acceptanceCriteria": [ + "使用 Vision 框架 VNRecognizeTextRequest 实现 OCR", + "支持中英文混合识别", + "支持自动语言检测", + "OCR 结果包含：文字内容、置信度、每个文字的边界框坐标", + "异步执行 OCR，不阻塞主线程", + "OCR 失败时显示友好错误提示", + "swift build passes", + "swift test passes", + "swiftlint passes" + ], + "priority": 2, + "passes": false, + "dependsOn": [ + "US-001" + ], + "notes": "", + "completionNotes": "" + }, + { + "id": "US-003", + "title": "本地翻译引擎 - Apple Translation API", + "description": "As a user, I want recognized text to be translated using macOS native Translation API without external dependencies.", + "acceptanceCriteria": [ + "使用 Translation 框架 (macOS 12+) 实现本地翻译", + "支持自动检测源语言", + "支持配置目标语言（默认跟随系统，可手动覆盖）", + "翻译请求异步执行，带超时处理（默认 10 秒）", + "翻译失败时显示原文 + 错误提示", + "处理不支持的语言对时给出友好提示", + "swift build passes", + "swift test passes", + "swiftlint passes" + ], + "priority": 3, + "passes": false, + "dependsOn": [ + "US-002" + ], + "notes": "", + "completionNotes": "" + }, + { + "id": "US-004", + "title": "覆盖层渲染引擎 - 原位替换模式", + "description": "As a user, I want to see translated text overlaid at the exact position of original text.", + "acceptanceCriteria": [ + "创建透明覆盖窗口，覆盖整个屏幕或选区", + "根据 OCR 返回的边界框坐标定位译文", + "译文文字样式匹配原文区域（近似字体大小、颜色）", + "支持点击覆盖层外部关闭", + "支持按 Esc 关闭覆盖层", + "swift build passes", + "swift test passes", + "swiftlint passes" + ], + "priority": 4, + "passes": false, + "dependsOn": [ + "US-002", + "US-003" + ], + "notes": "", + "completionNotes": "" + }, + { + "id": "US-005", + "title": "覆盖层渲染引擎 - 原文下方模式", + "description": "As a user, I want to see translation displayed below the original text area.", + "acceptanceCriteria": [ + "在选区下方创建浮窗展示完整译文", + "浮窗样式美观，带阴影和圆角", + "显示原文和译文对照（原文灰色，译文黑色）", + "支持复制译文到剪贴板", + "支持点击外部或按 Esc 关闭", + "swift build passes", + "swift test passes", + "swiftlint passes" + ], + "priority": 5, + "passes": false, + "dependsOn": [ + "US-002", + "US-003" + ], + "notes": "", + "completionNotes": "" + }, + { + "id": "US-006", + "title": "设置面板 - 引擎选择与基础配置", + "description": "As a user, I want to configure OCR/translation engines and app settings through a preferences window.", + "acceptanceCriteria": [ + "创建设置窗口，可从菜单栏打开", + "快捷键设置：显示当前快捷键，点击可修改", + "OCR 引擎选择：Vision（本地默认）、PaddleOCR（可选）", + "翻译引擎选择：Apple Translation（本地默认）、MTranServer（可选）", + "翻译模式选择：原位替换 / 原文下方", + "设置变更立即保存到配置文件", + "swift build passes", + "swift test passes", + "swiftlint passes" + ], + "priority": 6, + "passes": false, + "dependsOn": [ + "US-001" + ], + "notes": "", + "completionNotes": "" + }, + { + "id": "US-007", + "title": "设置面板 - 语言配置", + "description": "As a user, I want to configure source and target languages for translation.", + "acceptanceCriteria": [ + "源语言选项：自动检测、中文、英文、日文、韩文、法文、德文、西班牙文等", + "目标语言选项：跟随系统、中文、英文、日文、韩文、法文、德文、西班牙文等", + "语言配置保存并立即生效", + "根据选择的翻译引擎动态显示支持的语言列表", + "swift build passes", + "swift test passes", + "swiftlint passes" + ], + "priority": 7, + "passes": false, + "dependsOn": [ + "US-006" + ], + "notes": "", + "completionNotes": "" + }, + { + "id": "US-008", + "title": "可选 OCR 引擎 - PaddleOCR 集成", + "description": "As an advanced user, I want to use PaddleOCR for potentially better recognition accuracy on specific languages or scenarios.", + "acceptanceCriteria": [ + "实现 PaddleOCR 引擎适配器，遵循统一的 OCREngine 协议", + "支持通过设置切换到 PaddleOCR 引擎", + "PaddleOCR 支持中英文混合识别", + "OCR 结果格式与 Vision 引擎一致（文字、置信度、边界框）", + "异步执行 OCR，不阻塞主线程", + "PaddleOCR 未安装或启动失败时给出友好提示", + "swift build passes", + "swift test passes", + "swiftlint passes" + ], + "priority": 8, + "passes": false, + "dependsOn": [ + "US-002", + "US-006" + ], + "notes": "", + "completionNotes": "" + }, + { + "id": "US-009", + "title": "可选翻译引擎 - MTranServer 集成", + "description": "As an advanced user, I want to use self-hosted MTranServer for translation to have more control over translation quality and privacy.", + "acceptanceCriteria": [ + "实现 MTranServer 引擎适配器，遵循统一的 TranslationEngine 协议", + "MTranServer 地址配置（默认 localhost:8989）", + "支持通过设置切换到 MTranServer 引擎", + "支持自动检测源语言（可选配置）", + "翻译请求异步执行，带超时处理（默认 10 秒）", + "MTranServer 连接失败时给出友好提示", + "swift build passes", + "swift test passes", + "swiftlint passes" + ], + "priority": 9, + "passes": false, + "dependsOn": [ + "US-003", + "US-006" + ], + "notes": "", + "completionNotes": "" + }, + { + "id": "US-010", + "title": "翻译历史记录", + "description": "As a user, I want to view and manage my recent translation history.", + "acceptanceCriteria": [ + "每次翻译保存记录：时间、原文、译文、截图缩略图", + "历史记录窗口可从菜单栏打开", + "显示最近 50 条记录，支持滚动加载更多", + "支持搜索历史记录（按原文或译文内容）", + "支持删除单条或清空全部历史", + "swift build passes", + "swift test passes", + "swiftlint passes" + ], + "priority": 10, + "passes": false, + "dependsOn": [ + "US-001" + ], + "notes": "", + "completionNotes": "" + }, + { + "id": "US-011", + "title": "首次启动引导", + "description": "As a new user, I want to be guided through initial setup on first launch.", + "acceptanceCriteria": [ + "检测首次启动，显示欢迎窗口", + "说明本地 OCR 和翻译功能已自动启用", + "可选配置：引导用户配置 PaddleOCR 和 MTranServer 地址", + "请求屏幕录制权限（macOS 隐私权限）", + "请求辅助功能权限（用于全局快捷键）", + "提供测试翻译按钮验证配置", + "swift build passes", + "swift test passes", + "swiftlint passes" + ], + "priority": 11, + "passes": false, + "dependsOn": [ + "US-001" + ], + "notes": "", + "completionNotes": "" + } + ], + "metadata": { + "updatedAt": "2026-02-03T00:00:00.000Z" + } +}