new-markdown/docs/07-stage3-report.md

阶段 3 · 复杂内容编辑报告（实测记录）

日期：2026-11-13 · 范围（需求 §23 阶段 3）：表格、图片、超链接、数学公式、Mermaid、脚注、HTML、附件。

1. 本阶段实现内容

• 表格全套：
  • 插入：段落菜单/Ctrl+T 插入 3×3（gfm insertTableCommand）。
  • 浮动工具栏（TableToolbar.tsx）：选区进入表格时出现在表格上方，滚动时跟随；含 加行/加列/删行/删列/左齐/居中/右齐/删表（删类走 prosemirror-tables 命令、增类与对齐走 gfm 命令）。
  • 整列对齐修正：GFM 对齐由表头行定义、插件的 setAlignCommand 只改选区所在单元格——直接用会在数据格上点了没反应。已封装 setAlignColumn：自动定位同列表头格执行再恢复选区，用户在任意格点对齐都生效。
  • Tab 导航：自研插件——表内 Tab 跳下一格、Shift+Tab 回上一格、末格 Tab 自动新增一行再跳入；IME 组合期不拦截。
• 图片与附件落盘（Rust 新增 copy_to_assets、save_bytes_to_assets，逻辑已在独立 crate 实跑断言）：
  • 资源进 <文档主名>.assets/ 目录，相对路径写回 Markdown；文件名清洗 Windows 非法字符、重名自动 -1 递增。
  • 插入图片（Ctrl+Shift+I）：文件选择 → 复制落盘 → 相对路径插入；未保存文档先提示保存。
  • 粘贴/拖入图片：upload 插件接管，已保存文档落盘回相对路径，未命名/Web 模式退为 data URL。
  • 附件：任意文件复制落盘后以 [文件名](相对路径) 插入。插入带链接文本踩到 ProseMirror 的标记归一化坑（直接插带 mark 的文本节点会丢标记），改走 storedMarks + insertText，已有断言把住。
• 数学公式：接入官方 @milkdown/plugin-math 7.5.9（KaTeX 0.16，许可证 MIT；与内核 7.23 的 peer 范围兼容）——行内 $…$、块级 $$…$$ 解析为公式节点渲染并无损往返；段落菜单可插入公式块（该节点是 atom，LaTeX 存 attrs.value，实现按此处理）。KaTeX CSS 进主包。
• Mermaid：code_block 自有节点视图——language=mermaid 时渲染 SVG 预览（mermaid 12 懒加载分包，不进首屏），头部可切换「编辑源码/查看预览」，编辑后防抖重渲染，渲染失败显示错误信息并保留源码入口；普通代码块维持标准 pre>code。段落菜单可直接插入 Mermaid 示例块。
• 脚注/HTML 转正：阶段 0 的一次性探针改为常驻回归用例（脚注定义/引用、行内 <u>、块级 <div> 往返稳定）。

2. 构建与测试结果（实跑）

项	结果
类型检查 tsc -b	✅ 0 错误
自动化测试	✅ 45/45（9 文件；本阶段新增 14：表格 4、数学 3、Mermaid/代码块 3、脚注/HTML 2、图片/附件 2）
Rust 校验 crate	✅ 新增两命令断言全过（落盘路径、重名去重、字节写入回读）
生产构建	✅ 主包 930KB / gzip 288KB（KaTeX 进主包 +约 280KB；Mermaid 核心 656KB 与 elk 布局 1.5MB 均为懒加载块）
dev 冒烟	✅ HTTP 200

3. 已知问题与边界

1. Mermaid 渲染在 jsdom 无法真验（缺 SVG 布局 API）：测试只断言节点视图容器与源码保真，SVG 真渲染随 Windows 清单验；已做失败兜底（显示错误原因不白屏）。
2. 表格选区拖拽选多格、行列拖动排序未做（插件有 moveRow/moveCol 命令，排阶段 6 体验项）；表格工具栏位置在极端滚动下为选区变化时快照 + 滚动跟随，非逐帧跟踪。
3. 图片暂无缩放/对齐浮动操作条（schema 无宽度属性，扩展需改 schema 与序列化，排阶段 6 评估）；本地图片在 WebView 中的显示依赖相对路径解析，真机验。
4. plugin-math 版本线停在 7.5.9（官方现状），已锁版本；若后续 Milkdown 8 升级需一并评估。

4. 下一阶段（阶段 4）预告

文件与工作区深化：Rust/SQLite 落库（最近文件、工作区、偏好从 localStorage 迁入）、自动保存与崩溃恢复、文件恢复记录、未保存提醒完善、外部修改检测与冲突处理、文件夹工作区增强（新建/重命名/删除文档、拖拽组织）。