实现与验收

当前工具链：Flutter 3.47.7 stable / Dart 3.13.5。使用 Pub workspaces，一个应用、三个独立包；应用以 View / ViewModel、Repository / Service 分层。

用户要求：每个完整逻辑使用简体中文提交并推送；最终使用附注标签与 GitHub Release 发布安装包，不发布便携压缩包。

验收基准

• 以 design/Vex.html、Vex-Adaptive.html 和 Appearance.html 为视觉基准。
• 桌面八种布局、八套配色及其明暗模式、六套排版与紧凑间距。
• 文件/大纲、源码/即时编辑/阅读/导图、章节编排、查找替换、统一历史、保存提醒。
• 手机单页、平板分栏、键鼠与触控、中文输入法、快捷键、国际化、偏好恢复。
• HTML/PDF/PNG/Word 导出、演示、引导、关于/更新及 MCP 功能需逐项验证。
• 使用固定尺寸、字体环境和场景进行截图对比。98% 还原度是验收目标，未经测量不得报告达到。
• Windows setup.exe、macOS dmg、Linux deb、Android apk 分别验证；用户已确认暂缓 iOS IPA 和 HarmonyOS HAP 发布，签名与工具链齐备后再补。

发布约束

Apple 和 HarmonyOS 安装产物需要相应签名、工具链与设备验证。2026-10-18 用户确认暂不发布这两个平台安装包；保留 iOS 无签名编译检查，不用空文件、压缩包或未签名产物冒充安装包。

当前已验证

• 2026-10-18 第二轮产品复核：补上恢复快照损坏回退、设置故障与恢复隔离、关闭期间继续输入保护、非 Windows 源码行号和滚动位置、窄窗口菜单、原生 Esc 关闭浮层、内置文档独立配色、准确更新状态及跨文档链接。文档核心 24 项、编辑器 223 项、导图 16 项、应用 251 项，共 514 项 Dart/Flutter 测试通过；另有 55 项脚本测试、七组原型契约、严格分析与格式检查通过。Windows 原生集成生成 11 张截图，未将模拟手机宽度等同真机，也未将检查更新等同自动更新。详见第二轮产品复核。

• 2026-10-18 用户体验优先级改进：落实草稿关闭与并发恢复保护、保存期间候选和后续输入保护、隐藏导图按需刷新、异步打开与关闭目标稳定、正文阅读边距和键盘焦点反馈。文档核心 19 项、编辑器 195 项、导图 14 项、应用 184 项，共 412 项 Dart/Flutter 测试通过；20 项安装包与品牌测试、七组原型契约、品牌资源、格式及全仓分析通过。另通过 Windows 原生窗口集成测试并生成 14 张截图，核看桌面和 320/390px 明暗场景；不以窄窗口代替真机输入法验收，也不据此宣称 98% 达标。见用户体验优先级改进。

• 2026-10-18 收尾复跑：文档核心 19 项、编辑器 193 项、导图 14 项、应用 155 项，共 381 项 Dart/Flutter 测试通过；安装包与品牌边界 17 项、七组原型契约检查、品牌资源检查及全仓静态分析通过。应用测试本机串行执行并生成覆盖率，不将覆盖率或测试数量换算为视觉还原率。下文较早的测试数量保留为对应阶段记录。Windows release 重新构建，独立测试安装器通过安装、修复、卸载和文档保留检查，见收尾复验。

• v0.2.1 已接入 tag 触发的 GitHub Actions 安装包流水线。本机通过 Windows setup 安装 / 版本 / 卸载验证，Android 三架构 production APK 通过固定发行签名、包名、版本与 ABI 校验。macOS / Linux 的实际构建与安装检查以对应 runner 结果为准；iOS 仅做无签名编译，HarmonyOS 尚缺工程与适配条件。配方与签名边界见 安装包与自动发布。

• Android 已完成 ARM64／x86_64 release 预览 APK 构建；Android 14 模拟器通过工作区、布局／排版选择、表格插入与撤销测试，并已安装启动正式应用入口。预览包使用独立包名与开发签名；正式签名、真机与系统文件提供程序验收尚待完成。构建方式见 Android构建.md。

• 简体中文、繁体中文、英语、日语使用官方 ARB／gen-l10n，覆盖界面、状态、引导与内置示例；设置中即时切换并持久化。语言切换不重写文档或历史；繁体中文与日语使用相应系统字体回退。四语言、三种屏幕尺寸通过布局与对话框测试，Windows 原生窗口与 Android 14 模拟器通过四语言切换集成测试，并检查原生截图。Apple 语言声明已配置，系统原生界面仍待相应设备验证。

• Windows 原生 debug、release 构建和真实窗口集成测试通过，正式入口可运行；Logo 采用根目录源文件同步生成的应用内资源，避免跨目录资源加载失败。

• 各平台启动图标由根目录品牌源同步生成；Windows EXE 资源图标已抽取核对。布局与排版使用无背景遮罩的锚定浮层，选择后即时应用并保持面板开启，点击外部可关闭并操作正文。桌面／手机尺寸测试通过；表格对话框校验行列数并保留选区、CRLF 与一次撤销。行内代码和代码块使用不同图标。

• 字体采用系统界面／中文回退，仅内嵌约 0.92 MiB 的 Cascadia Code 并与原型共享；不新增 Inter、完整思源宋体。独立编辑包支持宿主注入字体。PDF 完整中文字体无损压缩，从 20.2 MiB 降为约 12.1 MiB，仅导出时解压；逐字节 SHA256 已核对，未裁剪字形。以上为字体资源大小，并非安装包总大小。

• 代码块在桌面、手机原型和 Flutter 中都使用安静的等宽正文；编辑时才在下方右侧出现语言输入。无复制按钮、无渲染行号，保留源码围栏、中文输入与共享撤销。

• 即时编辑支持点击定位、双向选区与 CRLF 源码映射、块首尾方向键切换、ATX 标题回车转正文；列表、任务及引用支持回车续写与空项退出。保存不结束块编辑，保存后取消改动仍以实际磁盘内容判断未保存状态。

• 复杂列表的显示块边界由 package:markdown 的 CommonMark 列表解析器确定，子列表、同项多段正文、缩进代码和引用不再拆散；保留源码范围与 CRLF，不将列表内标题加入顶级大纲。源码和即时编辑在嵌套代码围栏、引用内代码及缩进代码中按回车保持字面输入，不误续写列表。Windows 原生检查覆盖 1280/390px、明暗主题、编辑/阅读和一次撤销；暗色任务标记已修正对比度。手机宽度截图不等于物理手机输入法认证。

• 表格单元格的中文候选在主题、字号、视口及选区重建时保持；外部修改或切换文档后拒绝旧候选回写，取消候选不阻塞后续输入。四项控件回归测试通过，候选提交只产生一次可撤销的文档修改；编辑包 154 项、应用 155 项测试与全仓分析通过。上述为模拟输入法状态检查，仍需系统输入法实机验收。

• 即时编辑增加文档级鼠标选区，不将多块内容改成一个源码输入框；支持正反向拖选、Shift 点击、整篇全选、复制／剪切／粘贴、删除／输入替换、键盘菜单与一次撤销。选区高亮使用实际文本排版坐标，CommonMark 解析保留源码映射，覆盖隐藏标记、链接地址、实体、CRLF、表格转义和代码围栏；边缘拖动自动滚动并在松开／销毁时停止。输入候选及异步粘贴在文档变更后失效；Windows 1280/390px 明暗主题真实窗口验证通过并检查截图。390px 为窄窗口键鼠检查，不代表触控跨块选择或真机输入法验收。

• 即时编辑补充文档级触控选区，支持长按选词、原生样式手柄跨段落／代码／表格拖动、自适应剪贴板工具栏、全选和更多元素操作；保留 CRLF、字素边界和共享撤销。修复起点滚出视口而终点仍可见时工具栏消失的问题。新增十项控件回归，Android 14 原生模拟器在手机／平板宽度及明暗主题通过选择、系统剪贴板粘贴／复制和一次撤销，并检查截图。iOS 仅完成平台主题下的控件测试，不代表 iOS 原生或物理设备验收。见触控跨块选区验证。

• 正文和表格的行内编辑保留完整原始输入值，用文本样式隐藏非当前项的标记；光标进入时展开当前语法，覆盖粗斜体、删除线、行内代码、链接、高亮及上下标。语法识别复用 CommonMark 与已建立的源位置映射，围栏及缩进代码保持字面内容，表格使用单独的行内解析模式。中文候选期间不变换输入缓冲，提交和一次撤销通过测试；编辑包 172 项、应用 155 项及静态分析通过，Windows 1280/390px 明暗主题原生检查与截图通过。复杂富文本在阅读态与编辑态的换行仍有差异，需继续统一排版；本项不代表整体视觉相似度达标。

• 正文中的链接改为可合并的行内文本，不再各自占用独立换行区域；保留点击、右键与长按，统一字号、字距及嵌套格式。链接手势跟随当前回调并随源码销毁，主题／文字缩放重新解析时重置链接与图片序号。表格阅读态与编辑态使用相同可用宽度，修正阅读态居中／右对齐；行内代码的字号、字距与行高一致。三种宽度和三种表格对齐、重复链接重建回归通过；编辑包 182 项、应用 155 项与静态分析通过，Windows 1280/390px 明暗主题实际字体下逐字坐标、后续块位置、候选提交／撤销及截图通过。此项覆盖常用文本／代码／链接，不代表特殊行内公式、图片、引用式链接或全平台排版已全部达标。

• 即时编辑改为按需创建内容块，保留块位置键与选区源映射，不预建整篇控件和几何。28.5 万字符／2520 块的 Windows Profile 检查覆盖输入／撤销、全文选区、替换与恢复；同机单轮输入中位耗时约 99→88 ms，全选约 259→244 ms，结束时采样 RSS 峰值约 324→304 MiB，最差全选延迟未改善。隐藏全文输入的缩小字体试验反而变慢，已撤回。方法与限制见富文本长文档输入压力测试，不据此宣称性能最终达标。

• 文档核心 12 项、编辑控件 15 项、导图 3 项测试；应用 33 项测试覆盖八种桌面布局的明暗模式、手机布局、本地保存冲突、草稿、临时引导、导出及四语言适配。Windows 真实窗口分别验证代码块交互、选区工具栏格式化、标题转正文和任务续写。

• HTML 为独立页面；Word 生成真实 OOXML，覆盖标题、粗斜体、表格、代码换行；PDF 使用离线中文静态字体，已检查中文和引号提取、页面渲染，以及 150 行代码跨四页连续输出；导图 PNG 导出完整树。

• HTML/PDF/Word 通过同一资源解析器嵌入正文图片：支持文档相对路径、file/data/resource、HTTP/HTTPS；SVG 和动画首帧转为 PNG。重复图片复用资源，缺失或损坏图片保留替代文字；下载限制为 12 秒、单图 32 MiB，另有总字节数与像素限制，未保存文档不从进程工作目录读取相对资源。普通、表格、列表、长竖图与宽图的 PDF 已实际渲染检查；Word 已验证 OOXML、关系、尺寸、描述与唯一绘图 ID，本机缺少 LibreOffice，Word 页面视觉检查仍待补充。

• 数学和图表导出见对应专项记录。PDF/Word 列表导出保留嵌套层级、编号起点、同项多段正文、任务、引用和代码；Word 使用原生多级编号，后续段落不重复编号。PDF 的 1600 词单项跨五页已逐页检查，编号不重复且后一项正确续号。Word 列表结构已验证，视觉检查同样受本机渲染器缺失限制；编辑区复杂列表及系统打印的实际打印机验证仍待完成。上述测试不代表完成全部 Markdown 兼容性验收。

• 正文、大纲与导图演示共用页序；支持翻页、节点聚焦、字号 / 缩放和全图适配，退出恢复工作区。正式应用和原生测试共享自定义标题栏初始化；窗口全屏及恢复测试通过。详细记录见演示与标题栏验证。

• 原型 98% 还原度的完整对照矩阵尚未通过验收；跨平台安装包、平台签名、MCP、系统原生界面的语言及输入法适配仍需完成。

• 即时编辑的特殊行内公式／图片／引用式链接／实体、上下标真实基线和全语法换行一致性仍需完善；跨块触控已通过上述自动检查，真实软键盘、系统中文输入法、物理设备与长文档性能仍需专项验收。

品牌只编辑根目录 Logo，再运行 python scripts/sync_brand_assets.py。生成资源已提交，普通 flutter run 无需先安装 Python；CI 通过 --check 防止偏差。导出字体来源及重建方式见应用 assets/fonts/README.md。

收尾与发布门槛

维护入口见根目录 贡献指南 和 安全政策，GitHub 已配置缺陷、功能建议和 PR 模板。CI 检查全部已跟踪 Dart 文件的格式、七组原型契约，并保存三个 Flutter 包／应用的 LCOV 与纯 Dart 核心的覆盖率数据。不设置未经评估的覆盖率门槛，也不以这些检查代替原生集成与视觉验收。

下列项目尚未关闭，不应提前升级版本或打正式发布标签：

iOS IPA 和 HarmonyOS HAP 发布按用户确认暂缓，不计为本轮可发布安装包；这一豁免不代表已完成相应系统适配。

开发顺序

1. 文档模型、章节命令和共享撤销历史。
2. 独立编辑控件、导图控件及组件示例。
3. 原生工作区、文件工作流、外观、导出、设置、引导及平台集成。
4. 自动验证、视觉校准、原生安装包与 GitHub 发布。