# MarkEdit 开发计划 > 2026-11-08 · 个人作品项目 · 先本地应用,再可复用组件。阶段状态以验收结果为准。 ## 1. 项目定位 MarkEdit 是一款使用 React 和 TypeScript 构建的 Markdown 工作台,面向撰写技术笔记、README 和博客草稿的开发者。项目包含可直接使用的个人写作工作台,以及可嵌入业务项目的 React 编辑器组件。发布前检查 npm 名称和品牌冲突。 首版不做账号、云同步、多人协作、AI、富文本 WYSIWYG 和移动端原生应用。这些会稀释个人项目的编辑器技术深度。 ## 2. 产品需求与核心体验 - 面向 Markdown 源码写作,提供实时预览、格式工具栏、搜索替换和撤销/重做。 - 以模块化组件组织编辑器、预览、导航和文档存储,避免将 UI、编辑状态和持久化耦合在单一模块中。 - 组件使用 React props、ESM 和显式扩展配置,工作台使用 IndexedDB 管理文档并提供本地备份。 - 支持 GFM、目录导航、图片回调、公式、图表、主题、只读和可配置工具栏。 - 围绕文档安全、编辑事务和数据恢复建立回归测试,并明确记录兼容范围和未完成验收项。 ## 3. 技术方案和取舍 | 层 | 选择 | 理由 | | -------- | --------------------------------------------- | ------------------------------------------------------ | | 应用 | React 19 + TypeScript strict | 受控数据流、可复用组件与类型化 API | | 工程 | Vite + npm lockfile | 编辑器工作台没有首屏 SEO/SSR 需求,先降低部署复杂度 | | 编辑引擎 | CodeMirror 6 + React 适配层 | Markdown 源码编辑、事务、撤销、搜索、选区和扩展能力 | | 预览 | react-markdown + remark-gfm | AST 渲染、标准 Markdown 和 GFM;默认不执行原始 HTML | | UI | CSS 变量 + Lucide;复杂浮层阶段再引入 Radix | 先建立完整设计令牌,避免为了组件库增加无用依赖 | | 状态 | React state;编辑器持有光标与撤销历史 | 第一阶段不需要全局状态库,避免每次输入同步整个应用模型 | | 持久化 | MVP 单草稿 localStorage;多文档阶段 IndexedDB | 小步交付;存储故障必须显式反馈 | | 测试 | Vitest;后续 Playwright 用户流程 | 重点验证数据恢复、内容安全和真实编辑行为 | | 扩展 | KaTeX、Mermaid 按需加载 | 公式/图表不进入基础首屏包 | 官方资料:[Vite](https://vite.dev/guide/)、[react-markdown](https://github.com/remarkjs/react-markdown)、[CodeMirror](https://codemirror.net/)。依赖实际解析版本见 package-lock.json,主版本升级单独评估。 ## 4. UI 方向 暖白画布、墨绿色强调色、细分隔线、少量圆角;左侧轻量导航、中间编辑/预览、右侧后续目录。正文阅读优先,工具栏只放高频操作。支持浅色/深色、纯编辑/分屏/纯预览、窄屏堆叠。所有图标按钮提供名称、键盘焦点和按下状态。 ## 5. 模块边界 ```text src/ components/MarkdownEditor.tsx # 受控 value/onChange,编辑事务,工具栏 components/MarkdownPreview.tsx # Markdown -> React;不依赖存储 lib/draft.ts # 草稿结构、验证、持久化边界 App.tsx # 工作台、导入导出、保存状态 styles.css # 设计令牌与响应式布局 project/ # 计划、验收和架构决策 ``` P4 已拆出 `packages/editor`;工作台保留根目录入口,独立消费项目放在 `examples/react-consumer`。它使用独立依赖树安装 tarball,便于检验真实包边界。 ## 6. 分阶段实施与验收 按每周 8–12 小时估算,共约 6–8 周;这是安排建议,不是性能或交付承诺。 ### P0 · 需求和技术方案(0.5 周) - [x] 明确产品范围、核心交互与兼容策略。 - [x] 定义范围、技术选型、UI 方向、模块与阶段验收。 - 产物:本计划;验收:每个阶段有明确用户价值和完成条件。 ### P1 · 可运行编辑闭环(1 周,已实现) - React + TS + Vite 工程;CodeMirror 编辑、GFM 预览。 - 加粗、斜体、标题、引用、列表、链接、代码、表格插入;保留原生撤销/搜索。 - 编辑/分屏/预览视图,浅深主题,中文 UI,响应式。 - 单草稿自动保存、刷新恢复、Markdown 文件导入导出;导入保护未保存数据;存储失败反馈。 - 验收:输入改变预览;选区格式化可撤销;刷新恢复;中文导入导出内容不变;危险 HTML 不执行;构建与关键回归测试通过。 ### P2 · 个人知识工作台(1–1.5 周,已实现) - [x] IndexedDB 文档仓库:新建、重命名、搜索、删除与回收站;迁移 P1 草稿。 - [x] AST 提取目录、唯一锚点、标题跳转;重复标题/代码块中的伪标题测试。 - [x] 可调分屏、专注模式、带反馈的命令菜单、快捷键说明。 - [x] 文档版本快照、跨标签页冲突提示;批量备份导入导出。 - [x] 验收:切换文档不串内容、迁移不丢草稿、删除可恢复、存储写入失败可重试。 - 证据:23 项自动化测试;浏览器验证新建/搜索/回收站/版本恢复/备份往返/多标签页同步/390px 与 1440px 布局。故障与并发冲突通过模拟 IndexedDB 和 React hook 测试覆盖;尚未跑真实配额耗尽、浏览器崩溃或完整跨浏览器矩阵。 - 本阶段实现独立目录面板与标题层级导航;不解析非标准 `[TOC]` / `[TOCM]` 指令。 ### P3 · Markdown 扩展与编辑体验(已实现,2026-11-09) 功能与基准已完成;长文最终重渲染约 171ms,性能验收保留优化项;真实上传后端未接入。运行 `npm run benchmark` 可复现本地性能测量。 - KaTeX 公式、Mermaid 图表、预览代码高亮,按需分包;渲染错误就地显示。 - 基于源码位置映射的滚动同步,防止双向滚动反馈循环。 - 图片粘贴/拖拽,通过 `uploadImage(file): Promise` 接口接入;演示应用先支持 URL。 - 表格/链接输入面板、代码块语言选择;按需求增加 emoji。 - 验收:非法图表不破坏整页;图表使用严格安全配置;长文输入不明显阻塞;记录 100KB 文档的实测响应数据。 - 兼容声明:旧 flow/sequence、[TOC]、分页等非标准语法逐项决定迁移方式,不能宣称完全兼容。 ### P4 · 可复用 React 组件(已实现,2026-11-09) 51 项测试通过;ESM/类型/CSS/字体产物检查通过,独立 tarball 消费示例完成构建及浏览器验收。包保持 private,正式发布留待 P5。 - 拆出 editor/preview;value/onChange、defaultValue、readOnly、theme、toolbar、extensions、uploadImage API。 - 明确受控与非受控契约、ref 命令、CSS 作用域、React peerDependencies、ESM 与类型声明。 - 示例和 API 文档;测试双实例、父组件重置、卸载重挂、只读模式、主题切换保留选区。 - 验收:在独立 React 项目安装本地打包产物可运行,无重复 React、全局 CSS 污染或监听器泄漏。 ### P5 · 作品展示与发布准备(进行中,公开发布待确认) CI、E2E 流程、贡献指南、架构和发布报告已实现。GitHub 仓库为 honkinglin/MarkEdit,已采用 MIT,[Vercel 演示](https://markedit-seven.vercel.app)已上线。npm 与正式 release 尚未完成。验收范围见 [VALIDATION.md](VALIDATION.md)。 - CI:类型检查、测试、构建;补充 Playwright 核心流程和键盘可访问性检查。 - Chrome/Firefox/Safari 与窄屏检查,中文输入法、长文、剪贴板和下载测试。 - 性能记录、架构图、README、贡献指南、变更日志、演示 GIF/视频。 - 最后确定本项目开源许可证与第三方致谢;核实依赖和资源的许可,并保留必要声明。 - 部署演示、发布 npm 包和 GitHub release;发布前确认仓库、账号、名称与托管目标。 - 验收:陌生开发者按 README 可启动,并在示例中嵌入组件;所有已知限制有文档。 ### P6 · 英文默认界面与国际化基础(2026-11-10) - [x] 工作台、可复用组件和示例文案集中管理;目前仅支持英文。 - [x] 英文默认模板、错误提示、辅助技术标签与数量/日期格式;已有文档不改写。 - [x] 根目录、组件和示例 README 英文化;更新英文截图。 - [x] 53 项单元测试、28 项跨浏览器测试;中文浏览器环境仍默认英文。 - [ ] 提交后确认远端 CI 与 Vercel 部署。 当前剩余工作与优先级见 [STATUS.md](STATUS.md)。 ### P7 · 首轮性能优化(2026-11-10) - [x] 可复现的 100KB 生产浏览器测量:输入、预览更新、长任务,普通 CPU 与 4 倍降速。 - [x] 工作台目录复用已提交预览的标题元数据,消除重复 Markdown 解析。 - [x] Markdown 编辑配置移除默认 HTML/CSS/JavaScript 解析器加载,保留列表续写和粘贴链接。 - [x] 首屏 JS gzip 从 354,813 降到 287,093 bytes;CI 添加 320,000 bytes 预算。 - [x] 新增标题回调、桌面编辑命令和各布局目录导航回归测试。 - [ ] 后续优化:主线程长任务、复杂文档与密集输入、Mermaid 大型延迟加载块。 - 证据与限制:[PERFORMANCE.md](PERFORMANCE.md)。本阶段不宣称已消除长任务,不改变现有 180ms 长文预览合并策略。 ### P8 · 包发布流程(2026-11-10) - [x] 确认包名 `react-markedit`、首发版本 `0.1.0`、npm 账号 `kyrielin`。 - [x] 安装文档、动态版本产物、独立包消费、发布文件与许可证检查。 - [x] 精确 tarball 校验与 tag 驱动发布工作流;首次发布使用本地登录。 - [ ] npm trusted publisher 账号侧配置;仓库工作流文件不能代替此设置。 - 公开版本状态见 npm 与 GitHub Releases;操作说明见 [RELEASE.md](RELEASE.md)。 ## 7. 风险与处理 - 数据:localStorage 仅用于单草稿;捕获配额/权限异常;损坏数据不静默覆盖;多标签冲突在 P2 处理。 - 安全:默认不启用原始 HTML;若后续开启,需明确 sanitize schema;图片会向外部 URL 发请求,后续增加隐私控制。 - 性能:避免整个文档列表随击键写入;预览延后调度;公式/图表懒加载;先测再做 Worker/虚拟化。 - 兼容:保持 Markdown 源码可移植,明确列出支持的扩展语法,不承诺兼容所有变体。 - 范围:优先把编辑、恢复、导出打磨可靠,云端与 AI 作为 v2 选题。 ## 8. 作为个人作品如何呈现 展示可验证的工程决策:为何选择源码编辑、如何隔离编辑器状态与 React 状态、如何保护草稿、如何处理不可信 Markdown、如何设计扩展 API。README 用实际演示与测试数据支持结论,不写未测的性能数字。每个阶段对应一个里程碑,完成后记录验收证据,再进入下一阶段。