Knowledge Explorer — этап 1: аудит и технический план

Статус: этап 1 ТЗ docs/human-knowledge-explorer.md (аудит и прототипирование). Документ фиксирует фактическое состояние кода, доступность данных для всех сценариев ТЗ, пробелы и предлагаемый минимальный объём первой версии. Утверждение объёма v1 — точка согласования с пользователем (ТЗ §19, этап 1).

#1. Аудит текущего интерфейса знаний

Вкладка «Знания» живёт в debugger/src/Observability.tsx (не отдельный компонент) и на сегодня даёт:

• список с пагинацией (KNOWLEDGE_PAGE_SIZE, курсор), свободный поиск q (debounce 350 мс) — серверный GET /v1/observations/knowledge;
• фильтры: состояние (STATE_FILTERS: all/alive/at_risk/proposed/confirmed/ challenged/corrected/superseded/invalidated) и scope (all/project/org_unit/ organization);
• фасеты states + scopes (счётчики) — только два измерения;
• битемпоральную навигацию as_of / known_at + режим сравнения двух срезов (knowledge/diff), с пресетами час/день/неделя;
• карточку детали: propositions, topics/entities, история переходов (history), телеметрия подсказок, жизненный цикл (challenge/invalidate/ promote) и цепочка (knowledge/chain);
• предпросмотр подсказок (POST /v1/observations/hints).

Ограничения против ТЗ (по итогам полевого тестирования):

#2. Общий исследовательский слой: готовность данных

Движок observation/explore.go + POST /v1/observations/knowledge/explore (доступен UI через базу /api) закрывает почти все потребности ТЗ без нового бэкенда:

Виды связей (supports/contradicts/derived_from/depends_on/supersedes/related_to) совпадают со словарём knowledge.linked — граф не требует отдельных данных.

#3. Пробелы и решения

1. Фасеты бедны (ТЗ §6). GET /v1/observations/knowledge возвращает facets: {states, scopes}. Нужно расширить сервер (observation/ knowledge_query.go): topics, entities, projects, kinds, at_risk — счётчики по видимым знаниям с учётом тех же фильтров. Объём: S. Без UI-изменений обратно совместимо.
2. Первоисточники (ТЗ §8.3). Evidence.Ref — id события журнала вида r/event/000001; событие несёт context.run. Переход «доказательство → событие → трейс рана» собирается на клиенте из GET /v1/observations/ events?... (поиск по event_id) + существующих ссылок на трейс рана. Эндпоинта «событие по id» нет — добавлять не обязательно: события уже доступны листингом с фильтром, но прямой GET /v1/observations/events/ {id} (S) упростит и ускорит досье. Рекомендуется.
3. Карта знаний (ТЗ §4). Данные есть (orient), визуализации нет. Решение: SVG-облако областей без внешних библиотек (размер ∝ knowledge_count, цвет — доминирующее состояние, бейдж противоречий), рядом — альтернативный список областей (ТЗ §4.5). Объём: M.
4. Исследовательские сессии (ТЗ §11). Хранилища нет. Варианты: а) localStorage (быстро, не переносимо между устройствами) — v1; б) workspace-таблица research_sessions (переносимо, видимо другим) — этап 4. Предлагаем: v1 localStorage, этап 4 — серверное хранилище с экспортом/импортом.
5. Точка входа и маршрут. Новый пункт главного меню «Знания» → /knowledge (страница KnowledgeExplorer.tsx). Вкладка «Знания» в Observability остаётся до этапа 4 как операционная (быстрые lifecycle-действия над свежими предложениями), затем её lifecycle-панель переезжает в Explorer и вкладка удаляется. Это отражено в плане этапа 4.
6. Контекст переходов (ТЗ §3.3, этап 2). Каждая навигация в Explorer пишет запись (откуда → куда → чем инициировано) в стек сессии (в памяти + localStorage). URL продолжает нести состояние (как сейчас: q/state/ selected/…), добавляются area, entity, tab Explorer'а.

#4. Архитектура UI

debugger/src/KnowledgeExplorer.tsx   — страница Explorer (этап 2+)
debugger/src/explorer/
  AreaMap.tsx        — SVG-карта областей (orient)
  Dossier.tsx        — досье знания (trace + chain + lifecycle)
  (фактические пути: debugger/src/Dossier.tsx, debugger/src/explorer/*)
  RelationGraph.tsx  — локальный граф (expand), SVG без зависимостей
  ConflictPanel.tsx  — сравнение противоречий (compare)
  HistoryTimeline.tsx— временная история (trace + diff)
  sessions.ts        — стек переходов + сохранение сессии
debugger/src/observationApi.ts       + explore(), facets (расширенные)
observation/httpapi/knowledge_query.go   + facets topics/entities/projects/kinds/risk
observation/httpapi/server.go        + GET /v1/observations/events/{id} (опц.)

Правила: вся выборка — через существующий API журнала; UI не считает связи сам (только отображает ExploreRelation); права — как у вкладки знаний (чтение reader, lifecycle-действия writer); никаких параллельных хранилищ.

#5. Предлагаемый минимальный объём v1 (этап 2)

1. Страница /knowledge: заголовок с поиском, карта областей (orient по видимым знаниям проекта), список областей справа.
2. Клик по области → поиск по ней (search с вопросом-областью) → список карточек с matched_by и score; клик по карточке → раскрытие досье-кратко (proposition, состояние, evidence-счётчик, риск) с действиями lifecycle.
3. Фасетная панель: состояние, scope, тема, проект (после расширения фасетов), мультивыбор, счётчики.
4. Стек переходов в памяти + URL-синхронизация (назад/вперёд браузера работают).

Не входит в v1 (этапы 3–4): граф связей, досье-полное, временная история внутри Explorer, сравнение противоречий, сессии, просмотр результатов агента (кратко доступен через существующий hints-предпросмотр).

#6. План этапов

• Этап 2 (M): фасеты на сервере; KnowledgeExplorer.tsx + AreaMap + поиск + фасеты + стек переходов; пункт меню и маршрут; i18n ru/en; тесты (фасеты, API-клиент, компоненты карты).
• Этап 3 (M): RelationGraph (expand, кандидаты отдельно), Dossier (trace, первоисточники, lifecycle), HistoryTimeline (битемпоральные срезы), ConflictPanel (compare, разрешение через существующие challenge/correct).
• Этап 4 (M): сессии (localStorage → серверное хранилище), просмотр результатов исследования агента (synthesize + переход к исходным evidence), перенос lifecycle-панели из Observability, удаление старой вкладки.

Оценки: этапы 2–4 — по оценкам командной работы.

#7. Открытые вопросы — решения (2026-10-16)

1. Минимальный объём v1 (§5) утверждён без графа связей — граф в этапе 3.
2. GET /v1/observations/events/{id} — добавлен (этап 2).
3. Сессии: localStorage/память в v1, серверное хранилище в этапе 4 — ок.
4. Вкладка «Знания» в Observability: перенос lifecycle в Explorer и удаление старой вкладки на этапе 4 — ок.

#8. Статус этапа 2 (реализовано)

• Сервер: фасеты topics/entities/projects/kinds + фильтры topic/entity/origin/kind (одиночное значение на измерение, как state/scope); открытые размерности ограничены топ-40 по частоте; GET /v1/observations/events/{id} (+source_id/project для уточнения); orient без вопроса — валидная операция (полная карта областей, ранжирование по размеру).
• UI: страница /knowledge («Знания»), карта областей (SVG, размер ∝ количеству, цвет — преобладающее состояние, бейдж противоречий) и альтернативный список областей (поиск/сортировка/клавиатура); фасетная панель; исследовательский поиск с аннотациями matched_by/score из explore search; карточки с кратким досье и lifecycle-действиями; стек переходов в памяти + URL-синхронизация (back/forward работают).
• Меню: «Знания» → /knowledge; Observability переименован в «Наблюдаемость» (до переноса lifecycle-панели на этапе 4).
• Не входит (этапы 3–4): граф связей, полное досье с первоисточниками, битемпоральная история, сравнение противоречий, сессии-хранилище.

#9. Статус этапа 3 (реализовано)

UI-only поверх существующего движка explore (сервер не менялся, кроме клиентской типизации):

• Dossier.tsx — полное досье с вкладками Обзор / История / Связи / Противоречия: trace + активационная цепочка (/workspace/knowledge/{id}/chain), первоисточники (evidence → GET /v1/observations/events/{id}, раскрытие данных события и контекста), замена (replacement_id → переход в досье приемника), исследование от утверждения; пустые блоки не показываются.
• RelationGraph.tsx — SVG-граф окружения (expand): детерминированная концентрическая укладка по глубине (корень в центре), цвет ребра — тип связи, пунктир — кандидатные рёбра (+ отдельный пунктирный ореол у кандидатных узлов), легенда двух независимых каналов; контролы: глубина 1–3, кандидаты вкл/выкл, фильтр типов связей, фильтр узлов, центрирование на выбранном узле, переход в досье; чистые функции вынесены для тестов.
• HistoryTimeline.tsx — вертикальная история жизненного цикла (иконки/ метки из каталога событий) + битемпоральные срезы as_of/known_at: срез применяется на сервере (повторный trace), локальный хелпер stateAsOf показывает состояние на момент среза; телеметрия использования.
• ConflictPanel.tsx — обнаружение противоречий (compare без targets по всей видимой базе) и режим досье (conflicts по contradicts-рёбрам); формулировки/состояния/контекстные различия рядом, разрешение только через существующие механизмы: оспорить сторону или заменить её в пользу другой (invalidate + replacement_id); резолвнутые конфликты показывают решение.
• LifecycleBar.tsx — общие lifecycle-действия (challenge / invalidate / promote / correct с указанием приемника) для карточки поиска и досье.
• Интеграция: вкладки «Поиск» / «Противоречия», досье занимает правую колонку (кнопка назад), записи стека переходов и URL-параметры view/dossier; observationApi — типизация relations/traces/conflicts + фильтр knowledge_id; i18n ru/en; тесты (укладка графа, stateAsOf, базы конфликтов).

#10. Статус этапа 4 (реализовано)

• Серверное хранилище сессий: таблица workspace_research_session (в squashed baseline 0001_baseline_v2026.2.21) (workspace_research_session: project, title, created_by, payload jsonb, updated_at), Store-методы (workspace/researchsession.go, список — без payload), маршруты /v1/workspace/research-sessions (GET-список/GET-одна — reader; POST/PUT/DELETE — writer) с аудитом research.session.created/updated/deleted; валидация title ≤ 200, payload ≤ 128 КБ; handler-тесты (RBAC, 422/404/400, аудиты).
• Сессии в UI: панель «Сессии» в исследователе — сохранить текущее положение (вопрос, фильтры, область, view, досье, стек переходов) с заметками и выводом исследователя, открыть (позиция восстанавливается, знания ре-резолвятся из текущей проекции — §11.3), «Сохранить как новую» (§11.4), удалить; заметки/вывод помечены как слова исследователя, не знание (§11.2). Payload v1 — только ссылки; толерантный парсинг (applySessionPayload) переживает поля будущих версий, тесты на roundtrip/устойчивость.
• Исследование агента (§12): вкладка «Исследование агента» — выбор рана (ввод + недавние), извлечение вызовов knowledge_explore из журнала (tool.started + аргументы как JSON-строка), «Повторить сейчас» — воспроизведение через explore по текущей базе с пометкой времени и полноты; для synthesize — секции established/disputed/retired/conflicts/ gaps/next_actions/references с дисклеймером интерпретации и переходами в досье; чистый парсер вызовов вынесен и покрыт тестами; synthesis типизирован в клиенте (ExploreSynthesis).
• Перенос из Observability: панель «Подбор подсказок (прайминг)» (query/tool/tool_result → /hints) — сворачиваемый блок во вкладке поиска; вкладка «Знания» удалена (overview + patterns остались), плитки здоровья ведут в исследователь /knowledge?state=… (включая alive/at_risk); lifecycle-действия и активационная цепочка давно в Explorer (этапы 2–3), URL-синхронизация Observability почищена.