# WriteFlow 开发提示词（迭代式开发指南） > 本指南基于 [README.md](./README.md) 与 [产品策划开发手册](./产品策划开发手册.md) 制定，采用**增量迭代**方式推进。每个阶段均有明确的交付物、技术要点、验收标准，确保代码质量、功能完整性和用户体验一致性。 > **UI 开发必须遵循 `/ui-ux-pro-max` 规范**（即符合产品设计原则、使用 Naive UI 组件库、响应式布局、暗色/亮色主题无缝切换）。 --- ## 总体开发原则 1. **本地优先，数据安全**：所有笔记以 `.md` 文件存储于本地，同步仅作为附加能力，不得破坏本地数据。 2. **所见即所得为核心体验**：编辑器必须达到 Typora 级别的流畅度和渲染效果。 3. **渐进增强**：先保证核心编辑与文件管理可用，再叠加同步、高级功能。 4. **跨平台一致性**：在 Windows/macOS/Linux 上行为一致，UI 适配各平台习惯（如菜单栏、快捷键）。 5. **代码规范**： - 前端：TypeScript + ESLint + Prettier（Vue 官方风格指南） - 后端：Rust 1.70+，遵循 Rustfmt + Clippy，模块化设计，错误处理清晰。 6. **测试覆盖**：关键路径（文件读写、同步、冲突处理）必须有单元测试和集成测试。 7. **性能目标**：冷启动 < 2s，打开 1000 行文件 < 500ms，空闲内存 < 100MB。 --- ## Phase 1 – MVP 基础编辑器（8 周） **目标**：提供可用的本地 Markdown 所见即所得编辑器，包含文件管理、基础主题、导出 HTML/PDF。 **UI/UX 依据**：设计规范第 6 章（沉浸优先、无干扰、反馈及时），使用 Naive UI 组件（布局、按钮、弹窗、消息提示）。 --- ### 迭代 1.1 – 项目骨架与编辑器内核（W1） #### 任务清单 - [ ] **初始化 Tauri + Vue 3 + TypeScript 项目** - 使用 `create-tauri-app` 选择 Vue 3 + TypeScript。 - 配置 `vite.config.ts`，启用别名 `@` 指向 `src`。 - 安装依赖：`naive-ui`、`milkdown`（含 `@milkdown/vue`）、`@milkdown/theme-nord`（或其他主题）、`@milkdown/preset-commonmark`。 - [ ] **集成 Milkdown 编辑器组件** - 在 `App.vue` 或独立 `Editor.vue` 中挂载 Milkdown 编辑器。 - 配置基本 CommonMark 预设，实现标题、加粗、斜体、列表、引用、代码块、链接、图片、表格（基础）的实时渲染。 - 关闭 Milkdown 的工具栏，实现**纯键盘驱动**的所见即所得（光标所在行自动隐藏标记符号）。 - [ ] **实现自定义标题栏（无系统边框）** - 修改 `tauri.conf.json`：`"windows"` 配置 `"decorations": false`。 - 在 Vue 中绘制标题栏，包含应用 Logo、标题（当前文件名）、窗口控制按钮（最小化、最大化、关闭）。 - 实现窗口拖拽区域：使用 Tauri `data-tauri-drag-region` 属性。 - [ ] **基础的亮色/暗色主题** - 定义 CSS 变量（色值参考设计规范 6.4）。 - 提供顶部菜单或设置项切换主题，利用 Naive UI 的 `n-config-provider` 配合自定义类。 #### 关键技术点 - Milkdown 编辑器的 `editor` 实例管理（通过 `ref` 获取，用于后续内容读写）。 - Tauri 的 `window` API 控制窗口大小和位置。 - 使用 `@tauri-apps/api/event` 监听系统主题变更（可选）。 #### 验收标准 - [ ] 启动后编辑器可输入，Markdown 语法正确渲染。 - [ ] 标题栏可拖拽移动窗口，控制按钮功能正常。 - [ ] 主题切换后编辑器背景、文字、边框颜色同步变化。 - [ ] 无控制台报错，内存占用 < 50MB（空文档）。 --- ### 迭代 1.2 – 文件系统集成（W2–W3） #### 任务清单 - [ ] **实现文件树侧边栏** - 使用 Naive UI 的 `n-tree` 组件，绑定目录结构数据。 - 通过 Tauri `fs` 模块（`read_dir`）递归读取工作区目录。 - 支持展开/折叠文件夹，点击 `.md` 文件在编辑器中打开。 - [ ] **新建/打开/保存文件** - 新建：生成 `untitled.md`，弹窗让用户重命名（或自动生成时间戳文件名）。 - 打开：使用 `dialog.open()` 选择 `.md` 文件，读取内容并渲染。 - 保存：使用 `fs.writeFile()`，支持 `Ctrl+S` 快捷键，同时自动保存到当前文件。 - [ ] **最近打开文件列表** - 使用 `localStorage` 或 Tauri `store` 插件存储最近 10 个文件路径。 - 在菜单或侧边栏显示快速入口。 - [ ] **工作区管理（单工作区 MVP）** - 首次启动引导用户选择笔记目录（`dialog.open({ directory: true })`）。 - 将路径持久化（`store` 或配置文件），后续启动自动加载该目录。 #### 技术要点 - 文件读写使用 Tauri 的 `tauri::fs` 和 `tauri::dialog` 模块，注意权限配置（`capabilities`）。 - 文件树数据使用 `ref` 响应式，结合 `watch` 监听目录变更（后续可升级为 `notify` 后端监听）。 - 编辑器内容与文件路径双向绑定：打开文件 → 设置 `editor` 内容，保存时读取 `editor` 内容写入文件。 #### 验收标准 - [ ] 文件树正确显示目录及 `.md` 文件，点击文件立即在编辑器中打开。 - [ ] 新建文件后保存，文件出现在文件树中。 - [ ] 最近文件列表正确记录，重启后依然存在。 - [ ] 打开非文本文件或非 MD 文件时，给出友好提示。 --- ### 迭代 1.3 – 编辑体验增强（W4） #### 任务清单 - [ ] **自动保存与手动保存状态** - 每隔 30 秒自动保存当前文件（若有更改）。 - 状态栏显示“已保存”或“正在保存...”图标（Naive UI `n-icon`）。 - [ ] **快捷键体系（核心）** - `Ctrl+N` 新建，`Ctrl+O` 打开，`Ctrl+S` 保存，`Ctrl+Shift+S` 另存为。 - `Ctrl+Z`/`Ctrl+Y` 撤销/重做（Milkdown 内置）。 - `Ctrl+F` 查找（后续迭代）。 - 使用 Tauri `globalShortcut` 或前端 `@vueuse/core` 的 `useMagicKeys`。 - [ ] **字数统计与文档信息** - 状态栏显示当前文档字数（中英文混合计数）、行数、光标位置。 - 使用 `@milkdown/utils` 的 `prose` 或自行解析 AST 统计。 - [ ] **焦点模式（可选）** - 快捷键 `F11` 或菜单切换：隐藏侧边栏，编辑器全屏。 - 使用 CSS 动画过渡，保持平滑。 #### UI/UX 规范检查 - 状态栏位于底部，信息左对齐，同步状态（尚无）预留位置。 - 快捷键提示可悬浮显示（使用 `n-tooltip`）。 #### 验收标准 - [ ] 自动保存生效，关闭窗口或切换文件时不丢失编辑内容。 - [ ] 核心快捷键全平台（Win/Cmd 适配）正常。 - [ ] 字数统计准确（英文单词、中文字符、总字符）。 - [ ] 焦点模式切换流畅，无闪烁。 --- ### 迭代 1.4 – 主题与导出（W5–W6） #### 任务清单 - [ ] **完整的亮色/暗色主题切换** - 提供至少三种配色：默认亮色、默认暗色、Sepia（暖色）。 - 使用 Naive UI 的 `n-config-provider` 全局管理主题，同时自定义编辑器样式（Milkdown 的样式覆盖）。 - [ ] **导出 HTML** - 将当前 Markdown 内容转换为 HTML（可借助 Milkdown 的 `getMarkdown` + `markdown-it` 或直接使用 Milkdown 渲染结果）。 - 打包为一个自包含的 `.html` 文件（含样式），通过 Tauri `dialog.save()` 选择保存位置。 - [ ] **导出 PDF** - 方案一：使用 `window.print()` 配合 `@media print` 样式实现打印为 PDF（跨平台简单）。 - 方案二：使用 Rust 后端（`printpdf`）生成 PDF，更专业但复杂度高。MVP 采用方案一，后续替换。 - 导出前确保样式一致（保留主题）。 - [ ] **设置存储** - 使用 Tauri `store` 插件（或 `confy` crate）保存用户偏好：主题、最近工作区、自动保存间隔等。 #### 技术要点 - 导出 HTML 时，需内联主题 CSS 和 Milkdown 渲染样式，确保外部打开显示正常。 - PDF 导出使用 Tauri 的 `WebviewWindow` 的 `print` 方法或调用系统打印对话框。 #### 验收标准 - [ ] 三种主题切换后，编辑器、侧边栏、状态栏颜色同步。 - [ ] 导出 HTML 文件，在浏览器中打开与编辑器内显示一致。 - [ ] 导出 PDF 内容完整，中文不乱码，图片（若有）正常显示。 - [ ] 用户设置（主题、最近工作区）在重启后保留。 --- ### 迭代 1.5 – 错误处理与基础测试（W7–W8） #### 任务清单 - [ ] **全局错误处理** - 前端：Vue 全局错误处理器（`app.config.errorHandler`）捕获并显示友好提示（`n-notification`）。 - Rust：使用 `anyhow` 或自定义错误类型，Tauri Command 返回 `Result`，错误信息通过 `invoke` 传递到前端。 - [ ] **文件操作异常场景** - 文件被外部修改（只读、删除）时的提示。 - 磁盘空间不足、权限错误等提示。 - [ ] **单元测试（Rust）** - 文件读写函数、Hash 计算、路径处理等工具函数。 - 使用 `cargo test`，覆盖率 > 70%。 - [ ] **前端单元测试（Vitest）** - 测试文件树组件、编辑器组件（通过 Mock 编辑器 API）。 - [ ] **E2E 测试（Playwright）** - 核心路径：启动 → 新建文件 → 输入内容 → 保存 → 重新打开 → 内容一致。 - 导出 HTML 和 PDF 可验证文件生成。 #### 验收标准 - [ ] 所有错误场景有对应的用户提示，不崩溃。 - [ ] 单元测试全部通过。 - [ ] E2E 测试通过。 - [ ] 打包后的应用在 Windows/macOS/Linux 上可运行（基础功能）。 --- ### Phase 1 交付物 - 可安装的桌面应用（`.msi`/`.dmg`/`.AppImage`）。 - 源码仓库，包含完整的开发文档（README、CONTRIBUTING）。 - 项目网站（VitePress）上线，包含下载链接和用户手册。 --- ## Phase 2 – S3 同步引擎（6 周） **目标**：实现基于 S3 协议的云端同步，支持手动/自动同步、冲突检测、图片上传。 --- ### 迭代 2.1 – S3 连接层（W9–W10） #### 任务清单 - [ ] **添加 Rust S3 客户端** - 依赖 `aws-sdk-s3` 或 `rust-s3`，实现 `SyncProtocol` trait（参考设计文档 8.4）。 - 实现 `connect`、`list_files`、`upload`、`download`、`delete`、`get_metadata` 方法。 - [ ] **凭据安全存储** - 使用 `keyring` crate（macOS/Windows/Linux 统一）或 Tauri 的 `store` 加密存储 AccessKey/SecretKey。 - 前端提供配置表单（Endpoint、Bucket、Region、AccessKey、SecretKey），通过 Tauri Command 保存。 - [ ] **连接测试** - 提供“测试连接”按钮，验证凭据是否正确，Bucket 是否可访问。 #### 技术要点 - 使用 `async`/`await`，超时控制（`tokio::time::timeout`）。 - 处理 S3 的路径前缀（`prefix`）作为远程目录。 #### 验收标准 - [ ] 配置正确的 S3 信息后，测试连接成功。 - [ ] 凭据加密存储，无法在明文配置文件中读取。 - [ ] 列出远程文件（含前缀）正常。 --- ### 迭代 2.2 – 同步核心（W11） #### 任务清单 - [ ] **计算文件 Hash** - 使用 `sha2` 或 `blake3` 计算文件内容的哈希值。 - 存储本地元数据：`last_modified`、`hash`、`sync_status`。 - [ ] **Diff 引擎** - 对比本地文件、远程文件、上次同步基线（存储在本地 `.writeflow/sync_meta.json`）。 - 分类：`local_newer`、`remote_newer`、`both_changed`（冲突）、`identical`。 - [ ] **上传/下载执行** - 实现批量上传（并发控制，避免过多连接）。 - 实现增量下载（仅下载变更文件）。 - 进度反馈：通过 Tauri 事件向前端发送进度信息（`emit`）。 #### 技术要点 - 使用 `tokio` 并发，控制并发数（如 5 个）。 - 前端显示同步进度条（`n-progress`）。 #### 验收标准 - [ ] 本地新增文件 → 同步后出现在远程。 - [ ] 远程新增文件 → 同步后下载到本地。 - [ ] 本地文件修改 → 同步后远程更新。 - [ ] 远程文件修改 → 同步后本地更新。 --- ### 迭代 2.3 – 冲突处理与状态 UI（W12） #### 任务清单 - [ ] **冲突检测与策略** - 实现三种策略：`keep_local`、`keep_remote`、`keep_both`（默认）。 - `keep_both` 生成 `filename_conflict_YYYYMMDDHHMMSS.md`。 - [ ] **同步状态 UI** - 状态栏显示同步状态（空闲、同步中、冲突、错误）。 - 文件树中每个文件显示同步图标（绿勾、橙色感叹号、红色叉）。 - 点击状态可查看详细信息（使用 `n-drawer` 或 `n-modal`）。 - [ ] **手动/自动同步** - 提供“立即同步”按钮。 - 定时同步（可配置间隔，默认 5 分钟）。 #### 验收标准 - [ ] 两台设备修改同一文件，同步后生成冲突副本，原文件保留不丢失。 - [ ] 状态指示器实时更新，冲突有明确提示。 - [ ] 自动同步按设定间隔执行。 --- ### 迭代 2.4 – 图片同步与首次配置向导（W13–W14） #### 任务清单 - [ ] **图片自动上传** - 监听编辑器中的图片插入（拖拽或粘贴），使用 Tauri `fs` 读取图片文件并上传至 S3。 - 替换 Markdown 中的图片路径为相对路径（如 `images/xxx.png`），同时上传到远程对应路径。 - [ ] **图片引用管理** - 确保本地和远程图片目录结构一致。 - [ ] **首次配置向导** - 启动时检测是否已配置同步，若无则弹出向导（`n-steps`）。 - 引导选择工作区、配置 S3 信息、测试连接。 - [ ] **同步日志** - 提供查看同步日志的界面（`n-log` 或 `n-textarea`），便于调试。 #### 验收标准 - [ ] 粘贴图片到编辑器，自动上传到 S3，并在本地生成相对路径引用。 - [ ] 在另一设备同步后，图片正常显示。 - [ ] 向导流程完整，可跳过或稍后配置。 - [ ] 同步日志记录关键操作。 --- ### Phase 2 交付物 - 完整的 S3 同步功能，支持公开云（AWS、阿里云等）和私有部署（MinIO）。 - 冲突处理机制完善，数据安全有保障。 --- ## Phase 3 – 高级编辑功能（8 周） **目标**：补齐 Typora 的高级能力，包括代码高亮、数学公式、图表、目录大纲、多种导出格式。 > 由于篇幅，此处仅列出关键迭代，细节可参考产品手册 4.3。 --- ### 迭代 3.1 – 代码高亮与数学公式 - 引入 `Shiki`（Rust 端可预高亮）或前端 `prism.js` 实现语法高亮。 - 使用 `KaTeX` 渲染行内和块级公式。 - 配置 Milkdown 插件：`@milkdown/plugin-math`（需等待适配）或自定义。 ### 迭代 3.2 – Mermaid 图表与表格编辑器 - 集成 `Mermaid.js`，在渲染阶段将代码块 `mermaid` 转换为 SVG。 - 使用 Naive UI 的 `n-table` 构建可视化表格编辑器（弹窗形式），支持增删行列、对齐。 ### 迭代 3.3 – 文档大纲与导航 - 解析 Markdown 标题，在侧边栏或独立面板生成大纲树，点击跳转。 - 使用 `@milkdown/plugin-toc` 或自行解析。 ### 迭代 3.4 – 导出增强（PDF、Word、图片） - 替换 `window.print()` 为 Rust `genpdf` 或 `html-to-pdf` 引擎，提升 PDF 质量。 - 集成 `docx` crate 或调用 Pandoc（需用户安装）导出 Word。 - 导出为 PNG（截图）。 --- ## Phase 4 – 多协议同步（6 周） **目标**：支持 WebDAV、Git、WebRTC 等协议，扩展同步场景。 > 每个协议作为一个独立迭代，实现相同的 `SyncProtocol` trait，复用核心引擎。 --- ### 迭代 4.1 – WebDAV - 使用 `reqwest` 实现 PROPFIND、PUT、GET、DELETE。 - 支持摘要认证和 OAuth2（如坚果云）。 ### 迭代 4.2 – Git - 集成 `git2-rs`，实现 clone、pull、push、commit。 - 提供版本历史查看（类似 Git 日志）。 ### 迭代 4.3 – WebRTC - 使用 `webrtc-rs` 或通过 Tauri 调用前端 WebRTC，实现 P2P 直连同步。 - 需要信令服务器（简单实现）。 --- ## Phase 5 – 体验打磨与生态（持续） **目标**：多标签页、全文搜索、快捷键自定义、主题市场、插件系统。 --- ### 迭代 5.1 – 多标签页 - 使用 `n-tabs` 管理多个打开的文件，支持拖拽排序。 - 每个标签页独立编辑器实例（或共享实例切换内容）。 ### 迭代 5.2 – 全文搜索 - 使用 `tauri` 后端遍历文件内容，结合 `tantivy` 或 `ripgrep` 实现高速搜索。 - 前端结果列表，点击跳转并高亮匹配项。 ### 迭代 5.3 – 快捷键自定义 - 提供设置界面，使用 `n-dynamic-tags` 编辑快捷键映射。 - 存储为 JSON，动态注册/注销。 ### 迭代 5.4 – 插件系统 - 基于 `deno` 或 `quickjs` 嵌入 JavaScript 引擎，允许用户编写插件扩展。 - 提供插件 API（如 `onSave`、`onRender`）。 --- ## 开发流程与质量保障 ### 代码审查 - 每次 PR 必须通过 CI（检查 lint、test、build）。 - 至少一名 Reviewer 批准。 ### 持续集成 - GitHub Actions： - 前端 lint + test - Rust clippy + test - 构建 Tauri 应用（仅 PR 检查，不发布） ### 文档同步 - 所有 API 变更更新 TSDoc/Rustdoc。 - 用户手册同步更新（VitePress）。 --- ## 附录：UI 开发规范（/ui-ux-pro-max） 1. **使用 Naive UI 组件**：优先使用 `n-*` 组件，避免自定义基础组件（除非必要）。 2. **响应式适配**：窗口缩放时编辑器宽度自适应，侧边栏可折叠。 3. **暗色/亮色完全支持**：所有颜色使用 CSS 变量，随主题切换。 4. **交互反馈**：操作成功/失败使用 `n-message` 或 `n-notification`，加载状态使用 `n-spin`。 5. **可访问性**：使用语义化标签，键盘导航（Tab 顺序合理）。 6. **布局**：遵循设计规范第 6 章，标题栏高度 32px，状态栏 28px，编辑器填充适当留白。 --- **开始开发**：请从 **Phase 1 – 迭代 1.1** 入手，完成后再推进后续。每个迭代完成后进行自测，并更新 CHANGELOG。祝开发顺利！