Obsidian Doctor

Набор решений, инструментов и практик для диагностики, очистки и поддержки хранилищ Obsidian.

Что это

Obsidian Doctor — это не очередная «единственно правильная» методология ведения заметок и не ещё одна жёсткая система PKM.

Это репозиторий, который аккумулирует практические решения для типовых задач обслуживания уже существующего хранилища:

• неразрешённые ссылки;
• заметки и файлы без ссылок;
• заметки без исходящих ссылок;
• ссылки на несуществующие файлы;
• хаос во вложениях;
• контроль PDF в исследовательских хранилищах;
• дублирование заметок и медиафайлов;
• пустые папки;
• поиск пропущенных связей;
• периодическая «проверка здоровья» vault.

Основная идея проста:

большинству пользователей нужна не новая философия ведения заметок,
а повторяемая «аптечка» для обслуживания уже накопленного хранилища.

---

Зачем нужен этот репозиторий

По мере роста хранилища проблемы накапливаются постепенно:

• заметки теряют связи друг с другом;
• ссылки начинают вести на несуществующие объекты;
• вложения попадают в случайные папки;
• один и тот же смысл дублируется в нескольких заметках;
• PDF накапливаются внутри vault, хотя должны жить в Zotero;
• после реорганизации остаются пустые папки;
• служебные и дневниковые заметки искажают диагностику;
• наведение порядка становится медленным и полностью ручным.

Поэтому возникает практическая задача: не «перестроить всё с нуля», а иметь набор средств, которые позволяют регулярно проводить аудит хранилища, находить типовые дефекты структуры и по возможности исправлять их полуавтоматически.

---

Принципы проекта

1. Приоритет существующего хранилища

Целевой объект — уже заполненный vault, а не новая система с нуля.

2. Сначала аудит, потом изменения

Каждая операция должна по возможности иметь режимы:

• обнаружить;
• сформировать отчёт;
• предложить исправления;
• и только затем, при явном выборе пользователя, вносить изменения.

3. Безопасность по умолчанию

Потенциально опасные действия должны быть консервативными:

• сначала dry-run;
• затем понятный отчёт;
• удаление — через корзину, где это возможно;
• перед крупной реорганизацией — резервная копия.

4. Модульность

Репозиторий может включать:

• отдельные скрипты;
• подборки плагинов;
• инструкции по интеграции;
• соглашения по именованию;
• сценарии миграции;
• playbook по конкретным проблемам.

Не каждый пользователь обязан использовать все модули.

5. Учёт исследовательского сценария

Для исследовательских хранилищ PDF обычно должны храниться в Zotero, а не внутри vault.
В самом vault должны оставаться заметки, ссылки на литературу, аннотации и структурированные связи.

---

Какие типовые проблемы решает этот репозиторий

1. Слабая связность заметок

Симптомы:

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

Возможные решения:

• отчёты по orphan notes и dead-end notes;
• списки заметок без входящих ссылок;
• подсказки по недостающим ссылкам на основе названий и aliases;
• LLM-подсказки для поиска пропущенных связей;
• панели мониторинга для несвязанных заметок.

2. Неразрешённые и сломанные ссылки

Симптомы:

• [[ссылки]] на заметки, которых не существует;
• ссылки на локальные файлы, которые были перемещены или удалены;
• деградация структуры ссылок со временем.

Возможные решения:

• регулярные отчёты по unresolved links;
• поиск ссылок на несуществующие файлы;
• кликабельные списки для сеансов исправления.

3. Хаос во вложениях

Симптомы:

• скриншоты разбросаны по хранилищу;
• имена файлов случайны и непредсказуемы;
• вложения попадают не в те папки;
• после удаления или переименования заметок медиафайлы остаются без контекста.

Возможные решения:

• единая политика хранения вложений;
• переименование вложений по имени родительской заметки;
• перенос вложений в отдельную медиапапку;
• отчёты по медиафайлам без ссылок.

4. Накопление PDF внутри исследовательского vault

Симптомы:

• PDF хранятся прямо в vault;
• литература дублируется;
• заметки ссылаются на PDF-файлы напрямую, а не на literature note;
• переход от локальных PDF к Zotero выполнен непоследовательно.

Возможные решения:

• инвентаризация PDF внутри vault;
• поиск заметок, которые на них ссылаются;
• сопоставление этих PDF с Zotero;
• замена ссылок на файл ссылками на заметки вида [[@citationkey]].

5. Дублирование заметок и файлов

Симптомы:

• несколько заметок про одну и ту же сущность;
• близкие или конфликтующие названия;
• повторяющиеся изображения или экспортированные файлы;
• параллельные копии после синхронизации или реорганизации.

Возможные решения:

• поиск повторяющихся названий;
• анализ alias-конфликтов;
• отчёты о похожем содержимом;
• поиск дубликатов вложений по хешам.

6. Пустые папки после реорганизации

Симптомы:

• в дереве остаются пустые ветви;
• файловая структура визуально засоряется;
• папки уже не отражают реальное содержимое хранилища.

Возможные решения:

• поиск пустых папок;
• безопасная рекурсивная очистка.

---

Цель репозитория

Этот репозиторий задуман как аптечка для обслуживания Obsidian vault.

То есть его задача:

• собирать существующие решения, а не переписывать всё с нуля;
• документировать известные плагины и их ограничения;
• давать обёртки над штатными возможностями Obsidian и внешними инструментами;
• поддерживать и минимальные, и продвинутые сценарии;
• делать обслуживание хранилища повторяемым.

Иными словами:

этот репозиторий — суммация решений для типовых проблем, с которыми сталкиваются пользователи Obsidian.

---

Предполагаемая структура репозитория

obsidian-doctor/
├─ README.md
├─ docs/
│  ├─ problems/
│  │  ├─ unresolved-links.md
│  │  ├─ orphan-notes.md
│  │  ├─ attachments.md
│  │  ├─ pdf-zotero.md
│  │  ├─ duplicates.md
│  │  └─ empty-folders.md
│  ├─ workflows/
│  │  ├─ audit.md
│  │  ├─ repair.md
│  │  └─ research-vault.md
│  └─ integrations/
│     ├─ obsidian-cli.md
│     ├─ zotero.md
│     └─ plugins.md
├─ scripts/
│  ├─ audit/
│  ├─ links/
│  ├─ attachments/
│  ├─ zotero/
│  └─ folders/
├─ prompts/
│  ├─ repo-discovery.md
│  ├─ plugin-evaluation.md
│  └─ migration-assistant.md
└─ examples/
   ├─ reports/
   └─ configs/

---

## Статус прототипа (v0.1)

В репозитории реализован рабочий read-only прототип `Obsidian Doctor`:

- scan одного vault за запуск;
- индексация заметок и вложений;
- парсинг `wikilinks`, `embeds`, `markdown links`, `frontmatter`;
- построение графа входящих/исходящих связей;
- 16 обязательных правил MVP;
- JSON-отчёт;
- локальный GUI (FastAPI) с фильтрами и карточкой проблемы;
- CLI режимы `scan` и `gui`.

### Быстрый запуск

```bash
python -m venv .venv
. .venv/Scripts/activate
pip install -e .

Сканирование:

python -m app scan --vault D:/path/to/vault --config example_config.yaml --out reports/report.json

GUI по готовому отчёту:

python -m app gui --report reports/report.json

GUI с прямым сканированием:

python -m app gui --vault D:/path/to/vault --config example_config.yaml

Конфигурация и примеры

• пример конфигурации: example_config.yaml
• пример отчёта: example_report.json

Текущие ограничения

• режим apply/fix не реализован (только анализ и отчёты);
• near-duplicate по текстовому сходству отложен на следующий этап;
• резолвинг некоторых редких edge-cases ссылок реализован как best-effort.