MD 批阅工具

一个基于浏览器的 Markdown 文件批阅工具，模拟导师批改论文的体验。支持选中文本添加评论、标记删除、插入内容，并将所有操作导出为 AI 可读的结构化文档，实现「人工批阅 → AI 执行修改」的协作流程。同时支持在页面上直接编辑 Markdown 源码（所见即所得），兼容手动修改与评阅自动修改。

---

快速开始

1. 前置要求

• Node.js（v14 及以上）：下载地址

2. 启动（推荐）

双击 start.bat 即可一键启动：

1. 自动检测 Node.js 环境
2. 自动创建 md_files/ 和 评审文件/ 目录
3. 启动本地服务器（端口 8083）
4. 3 秒后自动打开浏览器访问 http://localhost:8083

关闭 cmd 窗口即可停止服务器。

3. 手动启动

如果需要手动启动，在 md-review-tool 目录下执行：

node server.js 8083

然后浏览器访问 http://localhost:8083。

⚠️ 请勿直接双击 index.html 打开——file:// 协议下 API 不可用，文件加载和评审保存功能将无法工作。

4. 准备文件

有两种方式加载文件：

• 方式一（列表选择）：将 .md 文件放入 md_files/ 文件夹，启动后页面自动加载文件列表，下拉选择即可。
• 方式二（文件选择器）：点击工具栏 「📂 打开 MD 文件」 按钮，通过系统文件选择对话框打开磁盘上任意位置的 .md 文件。

💡 智能路径搜索：通过文件选择器打开文件时，系统会自动搜索文件的完整路径以确保图片等资源正确加载。搜索策略为：项目目录 → 同盘根目录 → 其他盘符。搜索失败时会弹出提示框，支持手动输入文件路径或文件夹路径。

---

功能说明

打开文件

从文件列表选择

启动后，顶部工具栏的 文件下拉框 会自动列出 md_files/ 中所有 .md 文件，选择即可加载。

从磁盘打开任意文件

点击 「📂 打开 MD 文件」 按钮，通过系统文件选择对话框打开任意位置的 .md 文件。系统会自动完成以下流程：

1. 读取文件内容并提取特征片段
2. 调用服务器自动搜索文件的完整磁盘路径
3. 如果找到多个同名文件，弹窗让用户选择正确的一个
4. 成功定位后，图片从源文件同目录加载，编辑保存回原路径

自动搜索的三阶段策略：

阶段	搜索范围	递归深度	说明
第一阶段	项目内（md_files/、spec_game/、项目根）	5 层	优先级最高，命中即返回
第二阶段	同盘根目录（服务器所在盘符）	6 层	项目内找不到时扩展
第三阶段	其他盘符（C~Z 盘）	5 层	每搜完一个盘检查结果，找到即返回

搜索失败时的 fallback：弹出提示框让用户手动输入路径，支持两种格式：

• 完整文件路径：G:/文档/策划案/xxx.md
• 文件夹路径：G:/文档/策划案/（自动拼接当前文件名）

添加评论

1. 在文档中 选中一段文字
2. 松开鼠标后出现浮层工具条，点击 「💬 评论」（也可右键选择）
3. 在弹窗中输入评论内容
4. 可选：添加图片（支持三种方式）
   • 点击上传区域选择图片文件
   • 拖拽图片文件到上传区域
   • Ctrl+V 粘贴剪贴板中的图片（截图后直接粘贴）
5. 点击 「提交评论」

选中的文字会被标记为 紫色高亮，右侧批注栏同步显示评论卡片。

标记删除

1. 选中 需要删除的文字
2. 点击浮层中的 「🗑️ 删除」（或右键选择）

选中的文字会显示 红色删除线，表示该内容应被移除。

插入内容

1. 选中 一段文字作为插入位置的锚点
2. 点击浮层中的 「➕ 插入」（或右键选择）
3. 在弹窗中输入要插入的内容（支持 Markdown 格式）
4. 可选填写插入说明
5. 点击 「确认插入」

文档中会在锚点文字后出现 蓝色插入标记，表示此处应插入新内容。

批注管理

• 右侧批注栏：展示所有批注卡片，按文档顺序排列
• 双向跳转：点击文档中的批注角标 → 跳转到右侧对应卡片；点击右侧卡片 → 跳转到文档中对应位置
• 删除批注：点击卡片右下角的「删除」按钮
• 查看大图：点击评论中的缩略图可查看原图
• 收起侧栏：点击批注栏顶部的「收起」按钮

直接编辑 MD 文件（所见即所得）

除了通过批阅 → AI 执行的流程外，还支持在页面上直接编辑，类似 Word 的所见即所得体验：

1. 打开一个 MD 文件后，点击文档面板头部的 「✏️ 编辑」 按钮，切换到编辑模式
2. 直接在渲染后的文档界面上点击文字进行修改，所见即所得
3. 顶部会出现格式工具栏，支持 加粗、斜体、删除线、标题（H1-H3）、列表、引用、分隔线、撤销/重做
4. 自动保存：编辑内容在停止输入 1.5 秒后自动保存到服务器，无需手动操作
5. 切换文件或切回预览模式时，未保存的修改会自动保存
6. 保存时会自动将 HTML 内容转回 Markdown 格式，并备份旧版本到 评审文件/ 目录
7. 外部文件编辑：通过文件选择器打开的外部文件，编辑后会保存回原始路径
8. 浏览位置保持：预览↔编辑模式切换时，自动保持当前浏览位置不跳转（基于视觉锚点定位）

表格编辑

编辑模式下，右键点击表格单元格会弹出表格操作菜单：

• 插入行：在当前行的上方或下方插入新行
• 插入列：在当前列的左侧或右侧插入新列
• 删除行/列：删除当前行或当前列（至少保留一行一列）

💡 兼容批注系统：编辑模式下批注选区功能自动禁用，不会冲突。编辑保存后切回预览模式，批注会自动重新渲染（但由于内容可能已变动，批注位置可能需要调整）。

目录导航栏

文档左侧提供可收起/展开的 目录导航栏，自动从文档中提取 H1-H6 标题生成目录树：

• 点击跳转：点击目录项平滑滚动到对应标题位置
• 滚动高亮：滚动文档时自动高亮当前可见标题对应的目录项
• 收起/展开：点击左侧按钮切换目录面板显隐
• 悬浮半透明：目录面板悬浮在正文左侧，毛玻璃半透明背景，不遮挡正文布局
• 编辑模式自动刷新：编辑模式下修改标题后，目录会在 800ms 内自动更新（防抖）

💡 目录面板支持层级缩进，H1 最粗、H6 最细，方便快速定位文档结构。

刷新与文件变更检测

• 刷新按钮：点击工具栏的 🔄 按钮（或按 F5），重新读取当前 MD 文件并刷新页面
• 自动变更检测：后台每 3 秒检测当前文件是否有修改，检测到变更时工具栏显示黄色 「文件已更新」 提示
• 变更后新建批阅版本：当 MD 文件内容发生变化时，刷新会自动归档当前批阅记录，并创建新的批阅版本（版本号递增）

数据持久化与自动保存

• 所有操作 实时自动保存 到浏览器的 localStorage
• 批阅记录会自动保存到 评审文件/ 目录中，文件名格式为 批阅记录_{文件名}_v{版本}.md
• 关闭页面再打开，之前的批阅进度会自动恢复

注意：清除浏览器数据会丢失 localStorage 中的批阅记录，但 评审文件/ 中保存的记录不受影响。

---

导出与协作

导出批阅记录

点击顶部工具栏的 「导出批阅记录」 按钮，会下载一份结构化的 .md 文件。

如果批注中包含图片，会额外下载一份 .json 文件（含完整图片数据）。

一键更新（AI 执行修改）

批阅完成后点击 「一键更新」 按钮，系统会自动：

1. 将所有批注生成结构化的 AI 修改指令文件，保存到 评审文件/ 目录
2. 指令文件中记录源文件的完整路径（支持外部文件的绝对路径）
3. AI（CodeBuddy）读取指令文件后按指令逐条执行修改

也可以手动导出批阅记录后发送给 AI 执行。

导出文件格式

导出的 MD 文件包含以下内容：

# 批阅记录

- 源文件：xxx.md
- 批阅时间：20260306_1430
- 批注数量：5 条

---

## 操作指令

### 指令 1（修改）
- 操作：根据评论修改内容
- 定位块：第 3 块（"## 系统设计..."）
- 目标文本：「需要优化的原文」
- 评论内容：建议改为更简洁的表述...

### 指令 2（删除）
- 操作：删除以下文本
- 定位块：第 5 块
- 要删除的文本：「这段内容冗余」

### 指令 3（插入）
- 操作：在指定位置后插入新内容
- 定位块：第 7 块
- 插入位置（在此文本之后）：「上一段结尾」
- 要插入的内容：「新增的段落内容...」

---

## 原始数据（JSON）
{ ... }

---

快捷键

快捷键	功能
Ctrl + S	立即保存编辑内容（跳过自动保存延迟）
Ctrl + B	加粗（编辑模式下）
Ctrl + I	斜体（编辑模式下）
Ctrl + Z	撤销（编辑模式下）
Ctrl + V	粘贴图片到评论（评论弹窗中，剪贴板含图片时自动识别）
Ctrl + E	导出批阅记录
F5	刷新当前 MD 文件
Esc	关闭弹窗/菜单

---

操作类型说明

类型	颜色标识	用途	AI 执行方式
💬 评论	紫色高亮	对选中文字提出修改意见	根据评论内容理解意图，修改目标文本
🗑️ 删除	红色删除线	标记应删除的内容	直接删除目标文本
➕ 插入	蓝色虚线标记	在指定位置后插入新内容	在锚点文本后插入指定内容

---

服务器 API

本工具内置 Node.js 服务器（server.js），提供以下 API：

接口	方法	说明
/api/status	GET	服务器状态检查
/api/files	GET	列出 md_files/ 中的 .md 文件
/api/file?name=xxx.md	GET	读取指定文件内容
/api/file-external?path=xxx	GET	通过绝对路径读取任意 MD 文件（外部文件支持）
/api/find-file	POST	通过文件名搜索完整路径（三阶段：项目内→同盘→跨盘）
/api/review-records?name=xxx	GET	读取评审文件夹中的批阅记录（恢复评阅状态）
/api/save	POST	保存评审文件到 评审文件/
/api/save-md	POST	保存编辑后的 MD 源文件（支持外部文件绝对路径，自动备份旧版本）
/api/apply	POST	一键更新：生成 AI 修改指令文件（记录源文件真实路径）

当服务器不可用时（如使用其他静态文件服务器），工具会自动降级为浏览器 File System Access API 模式，通过手动选择文件夹加载文件。

---

技术说明

• 前端：原生 JavaScript，无框架依赖
• 后端：Node.js 内置模块（http/fs/path），无需安装依赖
• Markdown 解析：marked.js（CDN 加载）
• HTML→Markdown 转换：turndown.js（CDN 加载，用于所见即所得编辑保存）
• 数据存储：浏览器 localStorage + 服务器文件系统
• 文件结构：

md-review-tool/

├── index.html             # 主页面
├── server.js              # Node.js 本地服务器（API + 静态文件）
├── start.bat              # Windows 一键启动脚本
├── README.md
├── css/
│   ├── style.css          # 全局样式
│   ├── markdown.css       # Markdown 渲染 + 高亮标记样式
│   └── annotations.css    # 批注侧边栏样式
├── js/
│   ├── store.js           # 数据存储模块（含外部文件路径跟踪）
│   ├── renderer.js        # Markdown 解析与渲染（含外部图片路径重写）
│   ├── annotations.js     # 批注交互逻辑
│   ├── export.js          # 导出模块
│   ├── fileManager.js     # 文件夹管理模块（降级模式：File System Access API）
│   └── app.js             # 主控模块（含文件搜索、外部文件加载）
├── md_files/              # 存放待批阅的 MD 文件
└── 评审文件/              # 批阅记录 + AI 修改指令自动保存目录

---

常见问题

页面显示 file:///G:/api/status 错误

原因：直接双击 index.html 打开了页面，浏览器使用 file:// 协议，无法访问 API。

解决：双击 start.bat 启动，或手动 node server.js 8083 后访问 http://localhost:8083。

端口 8083 被占用

start.bat 会自动检测并关闭占用端口的进程。如果手动启动，可以指定其他端口：

node server.js 9090

批阅记录保存在哪？

• 服务器模式：自动保存到 评审文件/ 目录，文件名格式 批阅记录_{文件名}_v{版本}.md
• 浏览器模式（降级）：保存在浏览器 localStorage 中

打开文件后图片不显示？

可能原因：通过文件选择器打开的文件，自动路径搜索未命中。

解决：搜索失败时会弹出提示框，输入文件所在的 文件夹路径（如 G:/文档/策划案/），系统会自动拼接文件名并加载。图片会从该目录加载。

文件搜索很慢？

搜索按优先级分三阶段执行：项目内 → 同盘 → 其他盘。系统会自动跳过 Windows 系统目录（Windows、Program Files 等），并在找到结果后立即返回，不会继续搜索剩余盘符。