md-redline

用于 Markdown 规范、提示词和设计文档的行内审阅评论。

在渲染文档中高亮文本并留下评论，您的 AI 智能体可以直接读取并处理这些评论。评论以不可见的 HTML 标记形式存储在 .md 文件本身中。无需附属文件，无需数据库，无需外部服务。Markdown 文件始终是事实的唯一来源。

借助内置的 MCP 服务器，您的智能体可以在任务中途请求审阅，并暂停直到您点击 发送审阅 (Send review)。您留下反馈后，智能体将从中断处继续工作。无需复制粘贴，无需切换上下文。

30 秒了解完整的审阅工作流：

https://github.com/user-attachments/assets/7f493201-3aca-489c-86f0-3a7df454f693

适用于 Claude Code、Claude Desktop、Codex CLI、Gemini CLI 以及任何支持 stdio 服务器的 MCP 客户端。正如 Sean Grove 在 specs are the new code 中所言，规范正成为智能体开发中的主要工作单元。mdr 为该工作流提供了类似于代码审查的审阅工具。

快速开始

前提条件：Node 20 或更高版本。

npx md-redline /path/to/spec.md

如果需要，这将启动本地应用程序并在浏览器中打开它。

或者全局安装：

npm install -g md-redline
mdr /path/to/spec.md        # Open a file
mdr /path/to/dir             # Open a directory
mdr --stop                   # Stop the running server

md-redline 也可以作为 mdr 的别名使用。

Related MCP server: md-feedback

MCP 设置

向您的智能体注册 MCP 服务器，以便它可以在任务中途请求审阅。

Claude Code 或 Claude Desktop

mdr mcp install                   # register with both clients (default)
mdr mcp install --claude-code     # just Claude Code (via `claude mcp add`)
mdr mcp install --claude-desktop  # just Claude Desktop (JSON config file)

Codex CLI

codex mcp add md-redline -- mdr mcp

Gemini CLI

gemini mcp add --scope user md-redline mdr mcp

--scope user 标志很重要。Gemini 默认为项目级作用域，这只会为当前目录注册 mdr。

其他 MCP 客户端

将此服务器条目添加到客户端的 MCP 配置文件中：

{
  "mcpServers": {
    "md-redline": {
      "command": "mdr",
      "args": ["mcp"]
    }
  }
}

前提条件：mdr 必须在您的 PATH 中（例如通过 npm install -g md-redline）。如果您的客户端在生成子进程时没有继承 shell 的 PATH，请使用 which mdr 得到的绝对路径作为 command 的值。

审阅工作流

使用 MCP（推荐）

注册后，要求您的智能体请求审阅：

"在继续之前，请让我先在 mdr 中审阅 docs/specs/feature-x.md。"

智能体调用 mdr_request_review，mdr 打开文件，您高亮文本并留下评论，然后点击 发送审阅 (Send review)。智能体将以结构化提示词的形式接收您的反馈，并开始处理您的评论。审阅是按需选择的。智能体仅在您要求时才会暂停。

不使用 MCP

1. 使用 mdr /path/to/spec.md 打开 markdown 文件。

2. 高亮文本并留下行内评论。

3. 复制移交提示词 (hand-off prompt)。

4. 将提示词粘贴到您的 AI 智能体中。

5. 智能体编辑文件，处理反馈，并删除它已处理的评论标记。

6. 在差异视图中查看结果。

可选：解决工作流

在设置中启用解决模式，以进行具有明确 open（打开）和 resolved（已解决）状态的人工审阅。

适用人群

• 在本地编写规范、提示词或设计文档并使用基于文件的 AI 智能体的人员

• 在提交或发送进行更广泛审阅之前审阅文档的团队

• 任何处于人机协作编辑循环中，希望在纯文本文件中获得结构化行内反馈的人

非目标

• 不是协作式多用户编辑工具。

• 不是 GitHub PR 审查的替代品（文件进入 git 后请使用 PR 审查）。

• 不适用于不受信任的内容。这是一个供您个人文件使用的本地开发工具。

评论如何存储

评论以不可见的 HTML 标记形式直接存储在 markdown 中，位于它们所引用的文本之前，因此人类和智能体都可以基于同一个文件工作。

Some text <!-- @comment{
  "id":"uuid",
  "anchor":"highlighted text",
  "text":"Rewrite this section to be clearer.",
  "author":"User",
  "timestamp":"2026-03-26T12:00:00.000Z",
  "replies":[]
} -->highlighted text continues here.

这使得反馈：

• 通过纯文件读取对 AI 智能体可见

• 可随 markdown 文件携带

• 在普通渲染器（GitHub、VS Code 预览）中不可见

功能

审阅与评论

• 锚定到渲染文本的行内评论，包括重叠评论

• 线程化回复和可选的 open / resolved 审阅状态

• 带有拖动句柄的可调整锚点

• 渲染视图、原始视图和差异视图

• 用于单个或多个文件的移交提示词复制

导航与编辑

• 具有会话持久性和标签页上下文菜单的多标签页编辑

• 文件资源管理器、最近文件和原生 OS 文件选择器

• 文档内查找 (Cmd+F) 及匹配导航

• 带有滚动跟踪的目录

• 命令面板 (Cmd+K)、键盘快捷键和设置面板 (Cmd+,)

• 可调整大小的面板和右键上下文菜单

渲染与集成

• 当文件在外部更改时，通过 SSE 实现实时重载

• 带有可评论文本的 Mermaid 图表渲染

• 本地图片嵌入和 markdown 文件之间的可点击链接

• 可自定义的评论模板

• 8 种主题：浅色、深色、棕褐色、Nord、Solarized、GitHub、Rosé Pine、Catppuccin

支持的平台

• macOS：支持

• Linux：支持；系统文件选择器需要 zenity

• Windows：支持；系统文件选择器使用 PowerShell

权限

默认情况下，md-redline 可以读取您主目录中的任何 markdown 文件。您第一次运行 mdr 时（或在从没有 trusted-roots 功能的版本升级后的第一次），您的主文件夹会被添加到 ~/.md-redline.json 中的受信任根目录列表中。主目录之外的文件（/tmp、挂载的卷、系统路径）在您第一次打开它们时，需要通过 OS 文件夹选择器明确授予权限。授予的文件夹会在重启后被记住。

若要改用严格的按文件夹模型，请在安装后运行一次 mdr --restrict。这将创建一个没有默认信任的 ~/.md-redline.json，您将在第一次打开其中的文件时明确授予每个文件夹权限。

文件保存使用原子写入后重命名和基于 mtime 的冲突检测，以防止并发编辑导致的数据丢失。Mermaid SVG 输出在渲染前会通过 DOMPurify 进行清理。请仅在您信任的环境中运行 md-redline。

开发

从源码构建

git clone https://github.com/dejuknow/md-redline.git
cd md-redline
npm install
npm run dev

打开 Vite 打印的本地 URL（通常是 http://localhost:5188）。

脚本

npm run dev          # Start dev server
npm run lint         # Lint
npm test             # Production build + unit tests
npm run test:e2e     # Playwright E2E tests
npm run build        # Production build

智能体评估

评估工具集用于测试 AI 智能体是否正确读取、处理和删除行内评论。

• npm run eval:dry 验证评估夹具

• npm run eval 运行完整的评估工具集

• 详情请参阅 eval/README.md

架构

bin/md-redline             CLI entry point (invoked as `mdr` or `md-redline`)
server/index.ts            Hono server for file I/O, browsing, SSE, and local integrations
src/App.tsx                Main application shell
src/components/            Viewer, sidebar, raw view, diff view, TOC, explorer, settings, etc.
src/hooks/                 State, persistence, selection, file watching, drag handles, tabs
src/lib/comment-parser.ts  Inline comment parsing and mutation helpers
src/markdown/pipeline.ts   Markdown rendering pipeline
eval/                      Eval harness for agent behavior against inline comments
e2e/                       Playwright end-to-end coverage

许可证

MIT