26 KiB

Raw Permalink Blame History

WriteFlow 产品策划开发手册

版本：v1.0 | 作者：产品团队 | 最后更新：2026-07

1. 产品概述

1.1 产品定位

WriteFlow 是一款 本地优先、所见即所得、支持多设备云同步 的 Markdown 笔记编辑器。定位为 Typora 的现代化替代品，补齐 Typora 缺乏云同步能力、不再积极更新的短板。

1.2 产品愿景

让每一个人在任何设备上都能获得沉浸、流畅的 Markdown 写作体验，所有内容安全可控、随处可及。

1.3 核心价值主张

维度	价值
编辑体验	所见即所得，打字即渲染，无干扰沉浸
数据主权	本地 .md 文件存储，不锁定数据格式
多设备	S3/WebDAV 协议打通，你自己的云存储
性能	Tauri 桌面端原生性能，秒启动、低资源
可扩展	插件系统、多导出格式、自定义主题

1.4 产品边界

做什么：Markdown 编辑、本地文件管理、多设备云同步
不做什么：协作编辑（那是 Google Docs 的事）、在线 Web 版（专注桌面端）、知识图谱（那是 Obsidian 的事）

2. 市场分析与竞品调研

2.1 竞品矩阵

产品	编辑模式	同步	价格	优势	劣势
Typora	WYSIWYG	无内置	$14.99 买断	编辑体验最好	停更、无同步、无插件
Obsidian	源码+预览	付费 Obsidian Sync $5/月	免费	插件生态强、双链	学习曲线陡、非 WYSIWYG、同步收费
Notion	Block 编辑器	内置	免费+付费	全能协作	非 Markdown 原生态、云端依赖、慢
VS Code	源码+预览	Git	免费	全能编辑器	Markdown 非核心、体验不够专注
Bear	WYSIWYG	iCloud	免费+订阅	体验精美	仅 Apple 生态
Joplin	双栏	S3/WebDAV/NextCloud 等	免费开源	多协议同步	非 WYSIWYG、界面偏工程化
思源笔记	WYSIWYG	付费 S3/WebDAV	免费+订阅	国产、功能全	数据格式私有

2.2 WriteFlow 的差异化机会

Typora 级别的编辑体验 + 内置同步 — 目前市场上没有产品同时做到这两点
本地文件格式（.md）— 不锁定用户数据，可用任意编辑器打开
自带同步引擎 — 用你自己的 S3/WebDAV，无需额外付费
轻量高性能 — Tauri 比 Electron 内存占用少 60%+
跨平台 — Windows / macOS / Linux 全支持

3. 目标用户与用户故事

3.1 核心用户画像

画像	描述	核心需求
技术写作者	写技术博客、文档的开发者	代码高亮、数学公式、导出、Git 同步
知识管理者	做笔记、写日记的学生/研究者	多设备同步、全文搜索、文件管理
效率追求者	用 Markdown 做一切记录的极客	快捷键、最小干扰、自定义主题
隐私敏感者	不希望数据在第三方服务器	自建 S3/MinIO 同步、纯本地可用

3.2 用户故事（关键场景）

作为一名技术博客作者，
我想要在笔记本上写完文章后，自动同步到台式机继续编辑，
以便无缝切换设备而不需要手动拷贝文件。

作为一个研究生，
我希望能将上课拍的板书照片拖入笔记中，
图片能自动上传到我的 S3 图床并在笔记里用相对路径引用，
以便在任何设备上都能看到完整笔记。

作为一个隐私敏感用户，
我希望能使用自己搭建的 MinIO 服务器作为同步后端，
笔记和图片都不会经过任何第三方服务器。

作为一名程序员，
我希望笔记仓库能通过 Git 协议同步，
以便利用 Git 的版本历史随时回溯笔记变更。

4. 功能规划

4.1 MVP（Phase 1）— 基础编辑器

目标：可用的本地 Markdown 编辑器，核心编辑体验对齐 Typora。

模块	功能点	优先级
编辑器	所见即所得渲染	P0
编辑器	标题（H1-H6）	P0
编辑器	加粗、斜体、删除线、行内代码	P0
编辑器	有序/无序列表、嵌套列表	P0
编辑器	引用块	P0
编辑器	分隔线	P0
编辑器	链接与图片	P0
编辑器	代码块（有/无语言标注）	P0
编辑器	表格（增删行列、对齐）	P1
文件管理	新建/打开/保存 .md 文件	P0
文件管理	文件树侧边栏（浏览目录）	P0
文件管理	最近打开的文件列表	P1
窗口	自定义标题栏（无系统边框）	P0
主题	亮色/暗色主题切换	P0
导出	导出为 HTML	P1

4.2 Phase 2 — 同步引擎 v1

目标：S3 协议同步上线，实现多设备笔记互通。

模块	功能点	优先级
同步核心	S3 协议连接配置（Endpoint / Bucket / AK / SK）	P0
同步核心	增量同步（仅上传/下载变更文件）	P0
同步核心	冲突检测（同名文件被两台设备同时修改）	P0
同步核心	手动触发同步 + 定时自动同步	P0
同步核心	同步状态指示（同步中/已同步/冲突/错误）	P0
图片同步	图片上传到 S3，自动替换为 S3 URL	P1
图片同步	图片相对路径引用方案	P1
图片同步	粘贴图片自动上传 + 生成引用	P1
体验	首次配置向导	P1

4.3 Phase 3 — 高级编辑

目标：编辑能力对齐 Typora，满足专业写作需求。

模块	功能点	优先级
代码	语法高亮（100+ 语言）	P0
数学	KaTeX/LaTeX 公式渲染	P0
图表	Mermaid 流程图、甘特图、序列图	P1
图表	PlantUML 可选支持	P2
导航	文档大纲（根据标题自动生成）	P0
导航	大纲点击跳转到对应段落	P0
表格	可视化表格编辑器（拖拽调整列宽）	P1
表格	表格内公式计算	P2
导出	导出 PDF（带样式）	P0
导出	导出 Word (.docx)	P1
导出	导出图片 (.png)	P2
脚注	脚注/尾注	P2
任务	任务列表（checkboxes）	P1
目录	TOC 自动生成	P1

4.4 Phase 4 — 多协议同步

目标：扩展同步协议，覆盖更多使用场景。

协议	功能说明	优先级
WebDAV	支持坚果云、NextCloud、自建 WebDAV 服务器	P0
Git	同步到 GitHub/GitLab/Gitee 仓库，支持版本历史浏览	P1
WebRTC	局域网点对点直连同步（无需中央服务器，极低延迟）	P1
SMB/NFS	局域网共享文件夹模式，检测文件变更自动刷新	P2
OneDrive	利用系统 OneDrive 目录的自动同步能力	P2
iCloud	macOS 上利用 iCloud Drive 目录	P2

4.5 Phase 5 — 体验打磨与生态

目标：完整的桌面应用体验，建立插件生态。

模块	功能点	优先级
标签页	多标签页管理文件	P0
标签页	标签页拖拽排序、分离窗口	P1
搜索	全文搜索（文件名+文件内容）	P0
搜索	正则搜索	P1
搜索	全局搜索与替换	P1
快捷键	完整快捷键体系（可自定义）	P0
插件	插件系统（JS/TS 编写）	P1
插件	插件市场	P2
主题	自定义 CSS 主题	P0
主题	主题市场 / 社区分享	P2
国际化	中英文界面	P0
国际化	社区贡献更多语言	P2
无障碍	屏幕阅读器支持、键盘导航	P2

5. 技术架构

5.1 整体架构图

┌──────────────────────────────────────────────────┐
│                    前端 (Vue 3)                     │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐  │
│  │ 编辑器组件 │ │ 文件树    │ │ 设置/同步管理     │  │
│  │ ProseMirror│ │ 组件      │ │ 组件              │  │
│  └─────┬─────┘ └─────┬─────┘ └────────┬─────────┘  │
│        │             │               │             │
├────────┼─────────────┼───────────────┼─────────────┤
│        │    Tauri IPC Bridge (invoke) │             │
├────────┼─────────────┼───────────────┼─────────────┤
│                    后端 (Rust)                       │
│  ┌──────────────────────────────────────────────┐  │
│  │              Command Layer                    │  │
│  │  read_file / write_file / list_dir / ...     │  │
│  ├──────────────┬───────────────┬───────────────┤  │
│  │  文件管理模块  │   同步引擎     │   导出模块     │  │
│  │  - 文件IO     │  - S3 Client  │  - PDF        │  │
│  │  - 目录监听    │  - Diff 引擎  │  - HTML       │  │
│  │  - 图片处理    │  - 冲突解决   │  - DOCX       │  │
│  ├──────────────┴───────────────┴───────────────┤  │
│  │           Platform Abstraction                │  │
│  │     (文件系统 / 网络 / 系统托盘 / 快捷键)       │  │
│  └──────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────┘

5.2 前端技术选型

组件	技术选型	选型理由
框架	Vue 3 + Composition API	与 Tauri 生态结合好，轻量灵活
语言	TypeScript	类型安全，大型项目必备
UI 库	Naive UI	Vue3 高颜值 UI 库，TypeScript 原生支持
Markdown 编辑器	ProseMirror / Milkdown	插件化架构，WYSIWYG 能力强
代码高亮	Shiki / Prism.js	服务端级语法高亮
数学渲染	KaTeX	比 MathJax 更快
图表	Mermaid.js	标准 Markdown 图表方案
打包	Vite 6	极速 HMR，生态完善

5.3 Rust 后端技术选型

模块	选型	说明
框架	Tauri 2	桌面框架，Rust 后端
S3 客户端	rust-s3 / aws-sdk-s3	S3 协议实现
WebDAV 客户端	reqwest + 自实现	HTTP 协议扩展
Git	git2-rs	libgit2 绑定
文件监听	notify	跨平台文件变更监听
Markdown 解析	pulldown-cmark	高性能 Markdown 解析器
PDF 生成	printpdf / genpdf	Rust 原生 PDF 生成
序列化	serde + serde_json	配置与 IPC 通信
加密	ring / aes-gcm	远程凭据加密存储
压缩	flate2	gzip 压缩（WebDAV）

5.4 前端与后端通信设计

// Rust 侧 - 定义 Tauri Command
#[tauri::command]
async fn read_file(path: String) -> Result<String, String> {
    std::fs::read_to_string(&path).map_err(|e| e.to_string())
}

#[tauri::command]
async fn sync_to_s3(
    config: S3Config,
    files: Vec<SyncFile>,
) -> Result<SyncResult, String> {
    // 同步逻辑
}

// 前端侧 - 调用 Tauri Command
import { invoke } from '@tauri-apps/api/core';

const content = await invoke<string>('read_file', { path: '/path/to/file.md' });
const result = await invoke<SyncResult>('sync_to_s3', { config, files });

5.5 Tauri Capabilities 权限设计

{
  "identifier": "default",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "fs:allow-read-text-file",
    "fs:allow-write-text-file",
    "fs:allow-read-dir",
    "fs:allow-exists",
    "dialog:allow-open",
    "dialog:allow-save",
    "http:default"
  ]
}

6. UI/UX 设计规范

6.1 设计原则

沉浸优先 — 编辑器占据视觉重心，Chrome 尽可能少
所见即所得 — 光标所在行的 Markdown 语法标记即时隐藏，只展示渲染结果
无干扰 — 默认隐藏工具栏，聚焦模式更进一步隐藏侧边栏
反馈及时 — 同步状态、保存状态始终可见，不超过 200ms 延迟给出反馈
渐进披露 — 高级功能隐藏在二级菜单，不干扰日常使用

6.2 布局方案

┌─────────────────────────────────────────┐
│  自定义标题栏 (拖拽区 + 窗口控制 + Logo)  │
├────────┬────────────────────────────────┤
│ 侧边栏  │                                │
│        │                                │
│ 文件树  │         编辑器主区域             │
│        │    (所见即所得 Markdown)         │
│ 大纲    │                                │
│        │                                │
│ 同步状态│                                │
│        │                                │
├────────┴────────────────────────────────┤
│  状态栏 (文件路径 | 字数 | 同步状态 | 光标位置) │
└─────────────────────────────────────────┘

6.3 三种视图模式

模式	描述	使用场景
编辑模式（默认）	所见即所得，打字时隐藏 Markdown 标记	日常写作
源码模式	显示原始 Markdown 文本	精确控制格式、调试
阅读模式	纯渲染，不可编辑	阅读长文、演示

6.4 色彩方案

亮色主题：背景 #FFFFFF，文字 #333333，强调色 #2080F0
暗色主题：背景 #1E1E1E，文字 #D4D4D4，强调色 #4FC1FF
Sepia 主题：背景 #FBF0D9，文字 #5F4B32（类 Kindle）

7. 数据结构设计

7.1 笔记本（Workspace）配置

{
  "workspaces": [
    {
      "id": "ws-001",
      "name": "我的笔记",
      "local_path": "~/Documents/WriteFlow/notes",
      "sync": {
        "enabled": true,
        "protocol": "s3",
        "config": {
          "endpoint": "https://s3.amazonaws.com",
          "bucket": "my-notes-bucket",
          "region": "us-east-1",
          "prefix": "writeflow/"
        },
        "auto_sync_interval_secs": 300,
        "conflict_strategy": "keep_both"
      }
    }
  ]
}

7.2 同步元数据

{
  "file_sync_meta": {
    "notes/getting-started.md": {
      "last_local_modified": "2026-07-15T10:30:00Z",
      "local_hash": "sha256:abc123...",
      "last_remote_modified": "2026-07-15T09:00:00Z",
      "remote_hash": "sha256:abc123...",
      "sync_status": "synced"
    },
    "notes/draft.md": {
      "last_local_modified": "2026-07-15T10:35:00Z",
      "local_hash": "sha256:def456...",
      "last_remote_modified": "2026-07-15T09:00:00Z",
      "remote_hash": "sha256:old789...",
      "sync_status": "local_newer"
    }
  }
}

7.3 图片存储方案

笔记目录/
├── notes/
│   ├── article.md
│   └── images/
│       └── article/
│           ├── screenshot-01.png
│           └── diagram-02.png

Markdown 中引用方式：

![截图](images/article/screenshot-01.png)

同步时策略：

S3 模式：图片上传到 s3://bucket/prefix/notes/images/article/screenshot-01.png，本地保留原始文件
图片引用不做 URL 替换，保持相对路径，确保本地和远程均可渲染

8. 同步引擎设计

8.1 同步流程

用户操作 / 定时触发
        │
        ▼
  ┌─ 计算本地文件 Hash ─┐
  │                      │
  ▼                      ▼
┌──────────┐      ┌──────────────┐
│ 本地变更  │      │ 获取远程文件列表 │
│ 文件列表  │      │ (S3 ListObjects)│
└────┬─────┘      └──────┬───────┘
     │                   │
     └───────┬───────────┘
             ▼
     ┌──────────────┐
     │   Diff 对比   │
     │  三元对比:     │
     │  本地 / 远程  │
     │  / 上次同步基线│
     └──────┬───────┘
            │
    ┌───────┼───────┐
    ▼       ▼       ▼
 仅本地上传  仅远程下载  冲突
(Upload)  (Download) (Conflict)
    │       │       │
    └───────┼───────┘
            ▼
     ┌──────────────┐
     │  更新同步基线  │
     │ (保存到本地)   │
     └──────────────┘

8.2 冲突处理策略

策略	描述	适用场景
`keep_local`	以本地版本为准，覆盖远程	确定本地是最新
`keep_remote`	以远程版本为准，覆盖本地	刚换了新设备
`keep_both`	保留冲突副本 `filename_conflict_20260715.md`	不确定优先级的默认策略
`manual_merge`	弹出对比界面，用户手动合并	重要文件

8.3 安全性

凭据加密：S3 的 AccessKey/SecretKey 使用 AES-256-GCM 加密存储在本机 Keychain（macOS Keychain / Windows Credential Manager / Linux Secret Service）
传输加密：HTTPS/TLS 加密传输（S3 SDK 默认开启）
本地文件不动：同步失败不会删除或修改本地文件

8.4 同步协议抽象设计

// 统一的同步接口
#[async_trait]
pub trait SyncProtocol {
    async fn connect(&self, config: SyncConfig) -> Result<(), SyncError>;
    async fn list_files(&self, prefix: &str) -> Result<Vec<RemoteFile>, SyncError>;
    async fn upload(&self, local_path: &Path, remote_key: &str) -> Result<(), SyncError>;
    async fn download(&self, remote_key: &str, local_path: &Path) -> Result<(), SyncError>;
    async fn delete(&self, remote_key: &str) -> Result<(), SyncError>;
    async fn get_metadata(&self, remote_key: &str) -> Result<FileMetadata, SyncError>;
}

// 具体实现
pub struct S3SyncEngine { /* ... */ }
pub struct WebDAVSyncEngine { /* ... */ }
pub struct GitSyncEngine { /* ... */ }
pub struct WebRTCSyncEngine { /* ... */ }

9. 开发排期与里程碑

9.1 整体时间线

2026 Q3          2026 Q4          2027 Q1          2027 Q2
├──────┼──────────┼───────┼────────┼───────┼────────┼──────
│      │          │       │        │       │        │
Phase 1          Phase 2         Phase 3         Phase 4
(MVP)           (S3同步)        (高级编辑)       (多协议同步)
8 周             6 周             8 周             6 周

9.2 Phase 1 MVP 详细排期（8 周）

周次	里程碑	交付物
W1	编辑器基础	Milkdown 集成，基础 Markdown 实时渲染
W2	编辑器进阶	代码块、表格、链接、图片、任务列表
W3	文件系统	文件树侧边栏、新建/打开/保存文件
W4	文件管理	最近文件、自动保存、文件监听刷新
W5	主题系统	亮色/暗色主题、CSS 变量体系
W6	导出功能	HTML 导出、PDF 导出
W7	打磨与测试	快捷键、Bug 修复、性能优化
W8	发布 MVP	打包、签名、发布 GitHub Release

9.3 Phase 2 S3 同步详细排期（6 周）

周次	里程碑	交付物
W9-W10	S3 连接层	S3 Client 实现、连接配置 UI
W11	同步核心	Hash 计算、Diff 引擎、上传/下载
W12	冲突处理	冲突检测、三种冲突策略、状态 UI
W13	图片同步	图片上传 + 引用管理
W14	打磨发布	首次配置向导、同步日志、发布 v0.2

9.4 关键指标

指标	目标值
冷启动时间	< 2 秒
空闲内存占用	< 100 MB
打开 1000 行 .md 文件	< 500ms
S3 同步 100 个文件	< 30 秒（首次）/< 5 秒（增量）
冲突检测准确率	100%（不应有静默覆盖）

10. 质量保障与测试策略

10.1 测试金字塔

         ┌───────┐
         │  E2E  │  端到端测试 (Playwright)
         │  10%  │
        ┌┴───────┴┐
        │ 集成测试  │  前后端联调 + 同步集成
        │   30%   │
       ┌┴─────────┴┐
       │  单元测试   │  Rust + Vitest
       │    60%    │
      └────────────┘

10.2 各层测试策略

层级	工具	覆盖重点
Rust 单元测试	`cargo test`	文件操作、Hash 计算、同步协议逻辑
Rust 集成测试	`cargo test --test`	S3 客户端连接、同步引擎完整流程
前端单元测试	Vitest + Vue Test Utils	组件渲染、编辑器 API、状态管理
E2E 测试	Playwright	核心用户路径（新建-编辑-保存-同步-导出）

10.3 关键测试用例

创建新文件 → 编辑内容 → Ctrl+S 保存 → 文件系统验证内容正确
粘贴图片 → 图片保存到相对路径 → Markdown 引用正确
配置 S3 → 点击同步 → 文件出现在 S3 Bucket
两台设备修改同一文件 → 同步 → 检测到冲突 → 生成冲突副本
导出 PDF → 样式正确、图片完整、中文正常显示
暗色主题切换 → 编辑器/侧边栏/状态栏全部切换

11. 发布与运营策略

11.1 发布平台

平台	渠道	说明
GitHub	Releases	主要发布渠道，附带 Release Notes
macOS	Homebrew Cask	`brew install writeflow`
Windows	Winget / Chocolatey	包管理器分发
Linux	AppImage / Snap / Flatpak	主流格式覆盖
官网	writeflow.app	下载页 + 文档

11.2 版本策略

采用语义化版本 MAJOR.MINOR.PATCH
偶数次版本号为稳定版，奇数次为开发版
每 4-6 周发布一个 MINOR 版本

11.3 开源策略

License：MIT（最大化社区采用）
贡献指南：CONTRIBUTING.md + Issue Template + PR Template
文档站点：VitePress 搭建，托管于 GitHub Pages
社区：GitHub Discussions + Discord Server

11.4 商业化（长期可选）

方式	说明	时机
完全免费开源	核心功能永久免费	从 Phase 1 起
赞助	GitHub Sponsors / Open Collective	Phase 3 后
增值服务	官方托管同步服务（WriteFlow Sync）	Phase 5 后
企业版	SAML/SSO、审计日志、集中管理	Phase 5 后

12. 风险评估与应对

风险	影响	概率	应对措施
ProseMirror/Milkdown 集成复杂度超出预期	延期 2-4 周	中	备选方案：使用 markdown-it 双栏模式先上线
S3 SDK 某些平台兼容性问题	同步功能不可用	低	多测试主力 S3 服务商，抽象接口可快速替换
文件系统同步冲突数据丢失	用户数据丢失	低	默认 `keep_both` 策略，绝不静默删除文件
Tauri 2.x 大版本 API 变更	编译失败	中	锁定 Tauri 版本，定期评估升级风险
竞品（Typora 复活/Obsidian 推出 WYSIWYG）	差异化被削弱	中	主打同步能力作为核心壁垒
Linux 桌面碎片化导致兼容问题	部分 Linux 用户不可用	高	AppImage 一份构建覆盖主流发行版

附录 A：参考资源

附录 B：命名备选

名称	含义	可用性
WriteFlow	写作流动	暂未注册
MarkNote	Markdown + Note	暂未注册
InkWell	墨池	暂未注册
Scripta	拉丁文"写作"	GitHub 同名项目存在
TypeStone	刻字石	暂未注册
WriteFlow ✅	最终选择	—

文档维护：产品团队
下次评审时间：Phase 1 MVP 完成后

26 KiB Raw Permalink Blame History Unescape Escape