Открыт к новым проектам

Сайд-проекты · исследования

Evidence Board

Доски для исследований: тема в центре, вокруг утверждения, факты, цитаты и источники, между ними стрелки со смыслом.

Доски наполняют вместе человек и агенты — Claude Code и Codex — через API и MCP.

Открыть evidence.devisfun.ru

состояние
в разработке
стек
  • TypeScript
  • React
  • Fastify

Зачем

Исследование по теме — это десятки утверждений, фактов, событий, цитат и источников и связи между ними: что подтверждает, что опровергает, что отвечает на вопрос. На обычной доске карточка — просто текст, у стрелки нет смысла, цитату не сверить с оригиналом, а ИИ-⁠агента приходится либо пускать везде, либо копировать его ответы из чата руками.

В Evidence Board у карточки есть тип, у стрелки смысл, а у цитаты источник, в котором сервер сам её находит: в снимке страницы, PDF, электронной книге или скане архивного документа — и показывает страницу, главу или лист. Карточка живёт отдельно от доски: у неё история версий, и одна карточка может лежать на нескольких досках.

Доски наполняю я и агенты — Claude Code и Codex — через MCP, CLI и публичное API. Агент только добавляет: созданное мной сервер ему менять не даёт, всё его приходит с пометкой «нужна проверка» и откатывается одной кнопкой.

Сделал вместе с Claude Code: я ставил задачи, проверял руками и решал, агент писал код, тесты и документы. Первыми пользователями публичного API тоже были агенты, и их замечания стали правками спецификации.

Что умеет

12345
Evidence Board — демо-доска с синтетическим примером
  1. 1Карточки с типами — тема, утверждение, факт, событие, цитата, источник, вопрос, заметка; можно завести свои.
  2. 2Стрелки со смыслом — «подтверждает», «опровергает», «уточняет», «даёт контекст», «связано», «отвечает на», «затем».
  3. 3Вклад агентов помечен — карточки агента приходят с пометкой «нужна проверка», решает человек.
  4. 4Входящие — предложения агентов копятся во входящих, их принимают или отклоняют.
  5. 5Библиотека источников — PDF, EPUB и сканы; сервер сам ищет цитату в документе и говорит, нашлась ли она.
  6. 6Плашки — человек, организация, место, дата, число; поля из Wikidata, набор видимых полей свой на каждой доске.
  7. 7Вставка ⌘V — ссылка Википедии становится плашкой с фото и полями, дата и число — плашками, картинка — источником.
  8. 8Сканы и книги — листы архивного дела с номерами «л. 12 об.» и распознаванием по кнопке; EPUB, FB2 и MOBI с местом цитаты «гл. 2, с. 13».
  9. 9Снимки страниц — HTML, Markdown и скриншот всей страницы на дату, с подсвеченной цитатой.
  10. 10Раскладка — вокруг карточки, внутри раздела, лентой времени; большую доску раскладывает сервер по предложению агента.
  11. 11Фокус и замок — связи карточки кольцами вокруг неё; замок, чтобы листать доску, не задевая карточек.
  12. 12Общие доски — редактор и смотрящий, ссылка для просмотра без входа, видно, кто правит карточку.
  13. 13Публичное API — ключи по областям, повтор без дублей, вебхуки; правила хорошего исследования для агента отдаёт сервер.
  14. 14Выгрузка — PNG, SVG, PDF, Markdown, BibTeX, RIS, CSL-⁠JSON и JSON Canvas для Obsidian.
  15. 15iPad и телефон — касания, панели поверх доски, «Поделиться» на доску с Android.

Экраны

Доска «Постмодернизм», 908 карточек, на масштабе 48 %Фокус: связи карточки «Жак Деррида» кольцами вокруг неёПлашка человека: поля из Wikidata, на каждой доске видны своиКарточка-источник: книга Бодрийяра со ссылкой на статью в ВикипедииРазвёрнутая карточка: текст, связи и источники в три колонкиСмыслы стрелок: подтверждает, опровергает, уточняет, даёт контекст, связано, отвечает на, затемПоиск по всем доскамБиблиотека: все карточки и источники с фильтрами по типамНа iPad: касания и панели поверх доски
1 / 9 · Доска «Постмодернизм», 908 карточек, на масштабе 48 %

Что было трудно

Плавная доска на 908 карточек и 1850 стрелок

На реальной доске «Постмодернизм» прокрутка шла со скоростью 2–7 кадров в секунду. Первое узкое место — видеокарта. Длинные пунктирные стрелки обрезаются окном вокруг экрана по алгоритму Лианга — Барски, чтобы браузер не нарезал на штрихи то, чего не видно. Обход стрелками карточек ищется по сетке ячеек обходом Аманатидеса — Ву вместо проверки всех 600 карточек вокруг. Издалека доска рисуется проще, а слоёв отрисовки всегда 5, а не до 139. Второе — JavaScript главного потока; его показал профиль Chrome в обычном окне на экране 120 Гц, где мышь стоит над доской, а карточки въезжают и уезжают. Пока доску двигают тачпадом, карточки не откликаются на наведение, высота текста меряется пачкой через ResizeObserver, а подписи стрелок находят свой слой один раз. Итог — больше 60 кадров в секунду на масштабе 10 %, кадров дольше 20 мс за прогон 1–2 вместо 14–17.

Доска «Постмодернизм» на масштабе 10 %: 908 карточек и 1850 стрелок
Доска «Постмодернизм» на масштабе 10 %: 908 карточек и 1850 стрелок

Живая доска без потерь при обрывах связи

Доску одновременно правят люди и агенты, и порядок правок не должен ломаться ни после переподключения, ни после перезапуска сервера. Каждая правка пишется в журнал событий доски в Postgres, а номер события выдаётся в той же транзакции, под блокировкой строки доски. Вкладка после обрыва сама дочитывает журнал с последнего известного номера. Правка карточки, лежащей на нескольких досках, попадает в журналы всех. Это не CRDT: порядок задаёт сервер, а вкладки применяют события пачкой за кадр.

Агент только добавляет — и это проверяет сервер

Агент присылает пачку действий, и она выполняется одной транзакцией в две фазы: сначала все элементы, затем стрелки к ним по временным id. Новые карточки сервер расставляет сам, без наложений: координаты агенту не доверяются. Менять, двигать и удалять созданное человеком агенту не даёт код, а не просьба в инструкции. Весь прогон откатывается одной кнопкой, а повтор пачки после таймаута не создаёт дублей: ключ повтора хранится в той же транзакции, что и записи. Одно действие стоит 4–6 мс независимо от размера доски, поэтому прогон может создать до 5000 карточек.

Агент видит доску числами

Картинку доски на 908 карточек модель не прочтёт: на карточку приходится пара пикселей. Поэтому агент получает скелет доски — номера, разделы, рамки, стрелки и счётчики пересечений: 122 КБ, около 40 тысяч токенов, за 1,5 секунды. Геометрию стрелок я вынес в общий пакет, поэтому сервер считает те же пути, что рисует браузер. Агент решает смысл — как сгруппировать разделы и что главное, а координаты считает ELK на сервере в отдельном потоке. Пересечений стрелок стало 54 663 вместо 94 063, стрелок поверх карточек — 1196 вместо 1690. Раскладка приходит предложением во «Входящие», применяю её я.

Цитату находит сервер

Цитата на доске должна доказывать, что источник действительно это говорит. Сервер сам ищет каждую цитату в каждой копии источника — снимке страницы, PDF, электронной книге — и ставит якорь: место и по 32 знака контекста вокруг. Текст файла извлекается один раз и хранится вместе с версией извлекателя; новая цитата или копия сама попадает в очередь сверки. Сервер и окно просмотра склеивают текст PDF одной и той же функцией, с переносами слов на концах строк, поэтому подсветка в просмотре совпадает с найденным местом. У цитаты три статуса: «найдено», «похоже», «не найдено».

Выгрузка доски, которую нельзя нарисовать картинкой

SVG большой доски не успевал собраться и за 150 секунд: готовая библиотека вписывала все вычисленные стили в каждый из 52 тысяч элементов. Свой сериализатор кладёт таблицу стилей один раз — 15 секунд и 6,5 МБ. Читаемый PNG этой доски — 29 788 × 17 710 точек, то есть 528 млн пикселей, а Chrome рисует картинку не больше 268 млн. Поэтому окно выгрузки заранее предупреждает и предлагает SVG, а в SVG обрезанная карточка раскрывается под мышкой: весь текст и так лежит в файле, правила для наведения добавлены в его таблицу стилей.

Выгрузка большой доски: окно заранее предупреждает и предлагает SVG
Выгрузка большой доски: окно заранее предупреждает и предлагает SVG

Как устроен

Интерфейс
  • React
  • Vite
  • React Flow
  • TipTap
  • pdf.js
Сервер и API
  • Node.js
  • Fastify
  • Zod
  • OpenAPI
  • WebSocket
Домен
  • TypeScript
  • раскладки
  • геометрия стрелок
Данные
  • PostgreSQL
  • Drizzle
  • S3
Источники
  • pdf.js
  • Calibre
  • Tesseract
  • img2pdf
Агенты
  • MCP
  • CLI
  • вебхуки
Внешние службы
  • Firecrawl
  • Gemini
  • Wikidata
Деплой
  • Docker
  • Caddy
  • GitHub Actions
  • Раскладки, геометрия стрелок и сверка цитат — чистые функции в общем пакете: браузер и сервер считают одно и то же.
  • Сверку цитат, снимки страниц, конвертацию книг и распознавание делают очереди в Postgres внутри сервера, без отдельного брокера.
  • Файлы источников хранятся по sha-256 и не удаляются никогда: это доказательства.
  • Выкладка — одна команда: образ собирается на своём раннере GitHub Actions, перед переключением снимается копия базы.

Контакт

Открыт к новым проектам и предложениям о работе. Проще всего — почтой или в Telegram.

hello@alexandr.sh·GitHub·Telegram

Резюме · PDFCV in English · PDF