本文件适用于整个仓库,用于规定编码智能体的工作要求。用户指令的优先级始终高于本文件。
README.md:说明当前产品行为、环境配置、常用命令和项目结构。CONTRIBUTING.md:说明贡献流程、代码要求和产品范围。SECURITY.md与docs/PRIVACY.md:说明安全报告流程和数据处理限制。docs/RELEASE.md:说明打包、版本管理和未签名发布包的行为。
src/ 和 src-tauri/ 中的实现是判断产品行为的主要依据。design/ 中的文件仅作为视觉参考,不属于生产代码,也不构成权威规格。
- WordSnap 是一款基于 Tauri 2 的轻量划词翻译工具,不是通用词典或语言学习平台。
- 在 macOS 上按
Option+T,在其他平台上按Alt+T,可以读取可复制的选中文本,并在选区附近显示翻译浮窗。 - 外语输入会翻译为用户配置的目标语言;简体中文输入会翻译为英文,以便快速组织英文表达。
- 只有单个 ASCII 英文单词可以写入 SQLite 词表,单词中可以包含连字符。短语、句子、中文文本和翻译失败的内容不得写入词表。
- 重复查询同一单词时,应更新现有记录,增加
count,刷新last_seen_at,并替换已保存的译文。 - 应在平台能力允许的范围内完整保存并恢复用户剪贴板。修改剪贴板、读取选区和模拟键盘输入的变更必须按平台进行验证。
- 在 macOS 上,应用应保持菜单栏工具的运行方式,不得显示普通 Dock 图标。
- 第一版的产品范围应保持有限。未经明确批准,不得增加 OCR、截图翻译、搜索、标签、导出、编辑、复习系统或其他翻译后端。
src-tauri/src/lib.rs:应用状态、全局快捷键、选区与剪贴板读取、翻译请求、SQLite 存储、窗口、托盘和 Tauri 命令。src/main.ts:视图路由、翻译浮窗、词表、设置、菜单、前端事件和浏览器模拟数据。src/styles.css:生产界面的全部样式及浅色、深色主题行为。src-tauri/tauri.conf.json:窗口定义、打包元数据和 Tauri 安全配置。src-tauri/capabilities/default.json:前端可使用的 Tauri 权限。.github/workflows/ci.yml与.github/workflows/release.yml:验证和打包自动化流程。
后端行为有意集中在 src-tauri/src/lib.rs 中。对于一次性变更,应优先增加小型、职责明确的辅助函数和测试,不应引入新的抽象层。
- 开始工作前运行
git status --short --branch。保留所有已有改动,不得格式化、撤销、暂存或提交无关内容。 - 修改行为前检查实际调用路径,并保持 Rust 载荷字段与 TypeScript 驼峰命名接口同步。
- 对纯逻辑和回归问题增加或更新测试。涉及快捷键、窗口、剪贴板、托盘和定位时,还应记录手动验证步骤和测试平台。
- 不得提交 API Key、真实选中文本、个人数据库、应用数据文件,以及未经脱敏的日志或截图。
- 不得记录完整 API Key 或选中文本。远程服务应使用 HTTPS;只有明确的本机开发接口适合使用 HTTP。
- 如果本地存储、网络请求、剪贴板行为或 Tauri 权限发生变化,应在同一变更中更新
docs/PRIVACY.md或SECURITY.md。 - 如果用户可见行为、环境配置、命令或限制发生变化,应更新
README.md。长期有效的流程说明应保存在相应的专用文档中,不应在本文件中重复。 - 准备具名版本时,应保持
package.json、src-tauri/Cargo.toml和src-tauri/tauri.conf.json中的版本一致。 - 修改发布触发条件、产物命名、签名要求或支持平台声明前,应检查并同步更新
docs/RELEASE.md。
npm ci # 安装锁定版本的前端和 Tauri 工具链
npm run tauri dev # 启动完整桌面应用
npm run dev # 使用模拟数据启动浏览器界面预览
npm run check # 运行前端构建、Rust 格式检查、Clippy 和 Rust 测试
npm run audit # 通过 npm 官方软件源执行依赖漏洞审计
npm run tauri build # 为当前平台打包应用,仅在必要时运行交付前必须通过 npm run check。依赖发生变化时,还必须运行 npm run audit。仅验证浏览器模拟界面时,不得声称已经验证桌面应用行为。
- 已实现请求的行为,且未扩大约定的产品范围。
npm run check通过。- 已记录相关平台的手动验证结果,或明确说明尚未完成平台验证。
- 文档、隐私说明和安全说明与最终代码一致。
git diff --check通过,最终差异中不包含无关文件或生成文件。