md-redline

Встроенные комментарии для рецензирования спецификаций, промптов и дизайн-документов в формате markdown.

Выделяйте текст в отрендеренном документе, оставляйте комментарии, и ваш ИИ-агент сможет прочитать их и напрямую отреагировать. Комментарии сохраняются как невидимые 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 и любым другим MCP-клиентом, поддерживающим stdio-серверы. Как утверждает Шон Гроув в 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). Если ваш клиент запускает подпроцессы, не наследуя PATH вашей оболочки, используйте абсолютный путь из which mdr в качестве значения command.

Рабочий процесс рецензирования

С использованием MCP (рекомендуется)

После регистрации попросите вашего агента запросить проверку:

"Let me review docs/specs/feature-x.md in mdr before you continue."

Агент вызывает mdr_request_review, mdr открывает файл, вы выделяете текст и оставляете комментарии, затем нажимаете Send review. Агент получает ваш отзыв в виде структурированного промпта и начинает обрабатывать ваши комментарии. Рецензирование происходит по запросу. Агент приостанавливается только тогда, когда вы его об этом просите.

Без MCP

1. Откройте markdown-файл с помощью mdr /path/to/spec.md.

2. Выделите текст и оставьте встроенные комментарии.

3. Скопируйте промпт для передачи.

4. Вставьте промпт в ваш ИИ-агент.

5. Агент редактирует файл, обрабатывает отзыв и удаляет обработанные маркеры комментариев.

6. Проверьте результат в режиме сравнения (diff).

Опционально: рабочий процесс разрешения

Включите режим разрешения (resolve mode) в настройках для рецензирования человеком с явными состояниями open (открыто) и resolved (разрешено).

Для кого это

• Люди, пишущие спецификации, промпты или дизайн-документы локально с помощью файловых ИИ-агентов

• Команды, проверяющие документы перед их коммитом или отправкой на более широкое рецензирование

• Все, кто находится в цикле редактирования человек + агент и хочет получать структурированную встроенную обратную связь в обычных файлах

Не является целью

• Не является инструментом для совместного многопользовательского редактирования.

• Не является заменой для PR-ревью на GitHub (используйте их, когда файл уже в git).

• Не предназначено для недоверенного контента. Это локальный инструмент разработки для ваших собственных файлов.

Как хранятся комментарии

Комментарии хранятся как невидимые 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.

Это делает обратную связь:

• видимой для ИИ-агентов через обычное чтение файла

• переносимой вместе с markdown-файлом

• невидимой в обычных рендерерах (GitHub, предварительный просмотр в VS Code)

Функции

Рецензирование и комментирование

• Встроенные комментарии, привязанные к отрендеренному тексту, включая перекрывающиеся комментарии

• Потоковые ответы и опциональные состояния рецензирования open / resolved

• Регулируемые якоря с маркерами перетаскивания

• Режимы просмотра: отрендеренный, исходный код и diff

• Копирование промпта для передачи для одного или нескольких файлов

Навигация и редактирование

• Редактирование с несколькими вкладками, сохранением сессии и контекстными меню вкладок

• Проводник файлов, недавние файлы и системный выбор файлов ОС

• Поиск в документе (Cmd+F) с навигацией по совпадениям

• Оглавление с отслеживанием прокрутки

• Палитра команд (Cmd+K), сочетания клавиш и панель настроек (Cmd+,)

• Изменяемые панели и контекстные меню по правому клику

Рендеринг и интеграции

• Перезагрузка в реальном времени через SSE при внешнем изменении файлов

• Рендеринг диаграмм Mermaid с возможностью комментирования текста

• Встраивание локальных изображений и кликабельные ссылки между markdown-файлами

• Настраиваемые шаблоны комментариев

• 8 тем: Light, Dark, Sepia, Nord, Solarized, GitHub, Rosé Pine, Catppuccin

Поддерживаемые платформы

• macOS: поддерживается

• Linux: поддерживается; системный выбор файлов требует zenity

• Windows: поддерживается; системный выбор файлов использует PowerShell

Разрешения

По умолчанию md-redline может читать любой markdown-файл в вашей домашней директории. При первом запуске mdr (или при первом запуске после обновления с версии без функции доверенных корней) ваша домашняя папка добавляется в список доверенных корней в ~/.md-redline.json. Файлы вне вашей домашней директории (/tmp, смонтированные тома, системные пути) требуют явного предоставления разрешения через системный выбор папок при первом их открытии. Предоставленные папки запоминаются после перезапуска.

Чтобы использовать строгую модель для каждой папки, запустите 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

Откройте локальный URL, выведенный Vite (обычно 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

Оценка агента

Инструментарий оценки проверяет, правильно ли ИИ-агенты читают, обрабатывают и удаляют встроенные комментарии.

• 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