Context Atlas

Context Atlas — это локально-ориентированный, подтверждённый доказательствами слой памяти для программных проектов. Он превращает историю Git, структуру репозитория, манифесты, проектные документы и проверенные человеком объяснения в:

• обзор проекта, удобный для новичков;

• исследуемую карту компонентов и зависимостей;

• хронологическую запись того, как проект менялся;

• объяснения компонентов и решений, связанные с доказательствами; и

• ограниченные контекстные пакеты, которые агенты кодирования могут прочитать перед внесением изменений;

• явно выбранные документы и сводки разговоров с согласия человека; и

• версионированные контракты безопасности расширений и экспорта данных для доверенных хостов.

Этот репозиторий содержит исходный код для рабочего экспериментального кандидата в альфа-релиз 0.1.0: Node.js CLI, локальная веб-панель, библиотека TypeScript, stdio MCP-сервер и пакет плагина Codex. Сгенерированная среда выполнения плагина, локальные поведенческие шлюзы, последний локальный кандидат пакета и чистая проверка установленного пакета, описанные ниже, были проверены на текущем рабочем дереве. Размещённые рабочие процессы и релиз GitHub не проверялись; 0.1.0 остаётся неопубликованным, а более широкий производственный план явно отслеживается в docs/.

Зачем это существует

Длинные сессии кодирования теряют нить. Чаты сжимаются, агенты меняются, недокументированные решения исчезают, а сгенерированные сводки могут незаметно устареть или стать неверными. Context Atlas сохраняет прочную высокоуровневую карту вне любого отдельного чата, соблюдая строгую границу между наблюдаемыми фактами, документированными утверждениями, выводами, предложениями и одобренными человеком объяснениями.

flowchart LR
  A["Git history"] --> I["Evidence-first ingestion"]
  B["Repository structure"] --> I
  C["README, ADRs, manifests"] --> I
  I --> D["Local SQLite knowledge graph"]
  I --> L["Hash-chained audit ledger"]
  D --> O["Overview and orientation"]
  D --> M["Mind map and timeline"]
  D --> P["Task-bounded context pack"]
  O --> H["Developer"]
  M --> H
  P --> X["Coding agent through MCP"]
  R["Human review"] --> D

Related MCP server: CodeIntel MCP Server

Быстрый старт

Требования: Git и Node.js 24 или новее.

git clone https://github.com/moelomda/context-atlas.git
cd context-atlas
npm.cmd ci
npm.cmd run build
node dist/cli.js init C:\path\to\your\git-repository --name "My Project"
node dist/cli.js serve --repo C:\path\to\your\git-repository

Откройте http://127.0.0.1:4242. Сервер намеренно отказывает неаутентифицированным не-loopback хостам.

Для первой передачи используйте следующую последовательность:

node dist/cli.js overview --repo C:\path\to\repo
node dist/cli.js health --repo C:\path\to\repo
node dist/cli.js timeline --repo C:\path\to\repo
node dist/cli.js pack "add subscription retry handling" --json --repo C:\path\to\repo
node dist/cli.js proposals pending --repo C:\path\to\repo

Сгенерированные повествовательные предложения не принимаются как истина автоматически. Просмотрите их доказательства, затем явно одобрите или отклоните конкретное предложение:

node dist/cli.js approve <proposal-id> --actor human:alice --note "Reviewed against ADR-0001 and current code" --repo C:\path\to\repo
node dist/cli.js reject <proposal-id> --actor human:alice --note "Superseded by the current architecture" --repo C:\path\to\repo

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

Один внешний текстовый/Markdown документ или одна сводка разговора могут быть добавлены через рабочий процесс Add source на панели или через CLI. Предпросмотр доступен только для чтения и привязывает точные байты, происхождение, назначение, авторитет, чувствительность и приписываемого человека-актора. Применение требует свежего плана плюс буквального IMPORT; чувствительные импорты сохраняют метаданные и происхождение, опуская их тело. Импортированный материал остаётся недоверенным доказательством и никогда автоматически не одобряет утверждение и не переписывает обзор.

$plan = node dist/cli.js source-import-preview C:\path\to\notes.md --type document --origin "Architecture workshop" --authority documented --sensitivity normal --purpose "Preserve retry decisions" --actor human:alice --repo C:\path\to\repo | ConvertFrom-Json
node dist/cli.js source-import C:\path\to\notes.md --plan $plan.planId --confirm IMPORT --type document --origin "Architecture workshop" --authority documented --sensitivity normal --purpose "Preserve retry decisions" --actor human:alice --repo C:\path\to\repo

Запустите sync после значимых коммитов. Отчёты о состоянии здоровья чётко предупреждают, когда репозиторий продвинулся дальше последнего индексированного коммита.

Новые репозитории начинаются с бюджета контекст-пакета в 8 000 токенов. Существующие репозитории сохраняют значение, уже сохранённое в .context-atlas/config.json — включая устаревшее значение по умолчанию в 4 000 токенов — пока оператор не изменит его. pack --budget N по-прежнему переопределяет значение по умолчанию репозитория для одного запроса.

Синхронизация также требуется после изменения конфигурации, влияющей на извлечение, или изменения политики .atlasignore. Context Atlas записывает водяной знак зависимости от руководства, когда содержимое синхронизируется и проверяется; изменение этой границы делает ранее проверенные утверждения неурегулированными. Утверждения, созданные до отслеживания водяного знака, закрываются с ошибкой и требуют синхронизации плюс новой проверки человеком, а не молчаливого дедушкиного исключения.

Плагин Codex и MCP

Исходный пакет плагина находится в plugin/context-atlas/. Соберите и проверьте этот проект перед упаковкой или установкой: сборка встраивает автономную среду выполнения MCP в plugin/context-atlas/runtime/server.mjs, поэтому проверенная скопированная установка из маркетплейса не зависит от этого дерева исходников. Обёртка сохраняет запасной вариант dist/mcp/server.js для локальной разработки исходников.

MCP-сервер предоставляет 13 инструментов только для чтения:

• Текущая навигация: atlas_overview, atlas_context_pack, atlas_explain, atlas_history, atlas_health, atlas_search и atlas_evidence.

• Временные знания: atlas_assertions, atlas_assertion_history и atlas_assertion_evolution.

• Проверка сохранённых пакетов: atlas_pack_history, atlas_pack_snapshot и atlas_pack_diff.

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

• atlas_context_pack может использовать ID существующего переопределения, созданного человеком через CLI. Он не может создать или изменить переопределение, и переопределённые критические находки остаются заметными как в структурированном результате, так и в его текстовом расположении.

Каждый инструмент принимает абсолютный путь repo. Прямой MCP-клиент также может запустить node <абсолютный-путь-к-проекту>/dist/mcp/server.js и установить CONTEXT_ATLAS_REPO на инициализированный репозиторий.

Версионированные HTTP и MCP чтения сравнивают базу знаний, живой Git/рабочее дерево, реестр, синхронизацию и границы политики руководства до и после сборки ответа; одновременное изменение отклоняется с повторяемой ошибкой снимка вместо прикрепления более нового водяного знака к более старым данным. Инструменты истории сохранённых пакетов и diff возвращают один компактный структурированный полезный груз с коротким текстовым указателем, и каждый результат инструмента MCP имеет потолок в 2 500 000 символов с закрытием при ошибке.

Доверенные внутрипроцессные расширения могут использовать публичный экспорт context-atlas/extensions. Его шесть версионированных портов охватывают экстракторы, анализаторы, провайдеров, редакторы, экспортёры и валидаторы; манифесты и входы/выходы проверяются по схеме, небезопасные выходы атомарно завершаются с ошибкой, а установленный код расширений явно рассматривается как доверенный исполняемый код. Основная библиотека также предоставляет шлюз предпросмотра/согласия/авторизации экспорта с точными байтами, с списками разрешённых провайдеров, политикой редактирования/блокировки, бюджетами токенов/стоимости, косвенностью учётных данных, долговечными квитанциями попыток, отзывом и без автоматических повторных попыток. Ни один удалённый провайдер не включён в CLI, веб-панель или MCP-сервер в этой альфе.

Контракт контекст-пакета

Схема контекст-пакета v2 всегда представляет одни и те же 15 обязательных разделов: идентичность/авторитет, предупреждения, цели, компоненты, интерфейсы, соглашения, решения, ограничения, риски, недавние изменения, тесты, конфликты, неизвестные, доказательства и исключения. Раздел может явно быть present, none или unknown; пустая область знаний не молчаливо опускается.

Выбор — это целые элементы. Каждая материальная сущность, активная связь, утверждение или событие, допущенное в ограниченную вселенную выбора, либо отображается полностью с его замыканием доказательств, либо перечисляется как материальное исключение с точной причиной; фоновые нематериальные записи сообщаются как агрегированные счётчики. Связи несут статус текущего использования, причину, авторитет, уверенность и метаданные проверки доказательств, и непроверенная топология не представляется как устоявшееся руководство. Жёсткий бюджет применяется ко всему компактному JSON-объекту — не только к телу Markdown — и адаптер MCP также резервирует место для своей обёртки результата инструмента. Текущая оценка — это раскрытое приближение символов, разделённых на четыре, а не токенизатор провайдера. Запросы с бюджетом до 500 токенов принимаются как входные, но генерация отказывается с вычисленным минимумом, когда обязательная обёртка не может поместиться.

pack-save сохраняет проверенный пакет как неизменяемый снимок с адресацией по содержимому. pack-history, pack-diff и pack-refresh предоставляют ограниченную историю, структурное сравнение и рабочие процессы пересборки относительно текущего состояния. Снимки хранятся в .context-atlas/packs/; хранилище отказывает в 257-м отдельном снимке вместо молчаливого удаления истории. Обновление сохраняет исходную задачу и бюджет токенов, не наследует предыдущее переопределение безопасности и отказывает в изменении идентичности репозитория или нестабильных изменениях репозитория/политики. Чтения истории проверяют сохранённый набор перед применением запрошенного лимита отображения, поэтому граница в 256 элементов — это потолок безопасности, а не квалификация производительности для большой истории.

Перед представлением или упаковкой текущего руководства локальные файлы, достижимые коммиты Git, снимки репозитория и снимки компонентов повторно проверяются на соответствие каноническим путям, политике и SHA-256 дайджестам. Неизвестные типы внешних локаторов сообщаются как не проверенные; они не повышаются до проверенных доказательств. Обзор, граф, поиск, объяснение, утверждение, API, MCP, пакет и панель несут метаданные статуса текущего использования/причины/авторитета/доказательств или удерживают неурегулированную проверенную прозу.

Что записывается

Context Atlas хранит своё локальное состояние в <repository>/.context-atlas/:

• config.json: политика сканирования и свежести;

• atlas.db: доказательства, сущности, версии, связи, события и предложения;

• ledger.ndjson: добавляемая только хэш-цепочка, покрывающая записанные действия;

• backups/: проверенные резервные копии SQLite и переносимые снимки знаний;

• exports/: переносимые JSON-экспорты с контрольными суммами; и

• packs/: игнорируемые, неизменяемые снимки контекст-пакетов с жёсткой ёмкостью в 256 элементов.

Полные необработанные diff и полные тела файлов не сохраняются. Context Atlas сохраняет ограниченные, очищенные извлечения документов и метаданные репозитория, необходимые для навигации. Значения, похожие на секреты, и чувствительные пути, такие как .env, учётные данные, закрытые ключи и сертификаты, исключаются. Добавьте специфичные для репозитория исключения в .atlasignore; его упорядоченные правила glob поддерживают отрицание !.

Инициализация создаёт .context-atlas/.gitignore, чтобы база данных, экспорты, резервные копии, пакеты и полные снимки миграции до обновления не были случайно закоммичены. Перед тем как устаревшее хранилище запишет снимок миграции или пакет, Context Atlas безопасно добавляет отсутствующее правило производных данных, не заменяя правила оператора. Закоммитьте .context-atlas/config.json, .context-atlas/ledger.ndjson и .context-atlas/.gitignore, когда хотите общую, проверяемую память проекта; держите игнорируемые материалы базы данных локально или передавайте их только через проверенный рабочий процесс резервного копирования.

Модель безопасности

Context Atlas — это навигационный помощник, а не доказательство корректности программного обеспечения. Текущий код и тесты остаются авторитетными для поведения во время выполнения. Если контекстный пакет заблокирован, устраните перечисленные критические проверки здоровья. Исключительный рабочий процесс pack-override требует явного человеческого субъекта, обоснования и короткого срока действия, а результирующий пакет остаётся видимо помеченным.

Команды

Выполните node dist/cli.js help для получения полного списка команд. Основные рабочие процессы:

• Исследование: overview, map, timeline, search, explain, evidence, assertions, assertion-history, assertion-evolution.

• Подготовка агента: pack <task> [--budget N] [--json], pack-save <task>, pack-history, pack-diff <left> <right>, pack-refresh <snapshot>.

• Поддержание памяти: sync, proposals, propose, approve, reject; approve/reject также доступны человеку в защищённой loopback-панели.

• Добавление выбранных доказательств: source-import-preview <file> с последующим source-import <file> --plan <id> --confirm IMPORT; панель предоставляет ту же границу предпросмотра/согласия для одного выбранного в браузере файла или вставленной сводки.

• Аудит: health, validate, recover-ledger, privacy, retention-preview, подтверждённый retention-apply и retention-history (validate завершается с кодом 2 при критических находках). Удаление retention ограничено подходящими файлами экспорта/резервных копий и требует точного идентификатора плана предпросмотра, субъекта human:, обоснования и --confirm APPLY.

• Переносимость: export, verify-export, import-preview, атомарный import, rebuild-verify, backup, verify-backup, restore --confirm RESTORE.

• Визуализация: serve на loopback.

Разработка и проверка

npm.cmd run build
npm.cmd test

Текущее локальное рабочее дерево прошло обычный набор поведенческих тестов (122/122 тестов за 693 394 мс) и прогон покрытия (122/122 тестов за 901 735 мс; 95,40% строк, 96,07% функций и 76,81% ветвей). Строгая компиляция TypeScript исходников/тестов, синтаксис JavaScript, разбор JSON/YAML, проверка идентичности релиза и онлайн npm audit с нулём обнаруженных уязвимостей также прошли. Это локальные результаты Windows, а не кроссплатформенные или размещённые результаты.

Финальный локальный прогон производительности также удалил дублирующую работу по репозиторию/доказательствам из контракта обзора: на фикстуре из девяти сущностей реальный запрос /api/v1/overview упал с примерно 8–12 секунд и 58 подпроцессов Git до 1,48–1,61 секунды и 12 подпроцессов Git, сохранив проверки снимков до/после. Это сфокусированный результат регрессии на малой фикстуре, а не квалификация задержки для большого репозитория.

Плагин был перегенерирован из этого исходного кода: исходный код и объединённый рантайм предоставляют одни и те же 13 инструментов только для чтения, валидаторы плагина и навыка проходят, независимая перегенерация рантайма и уведомлений третьих сторон дала детерминированные хэши, а реальный перегенерированный рантайм прошёл MCP-регрессию (1/1). Проверка рабочих процессов с закреплённым Actionlint 1.7.12 прошла все четыре рабочих процесса; все 17 ссылок uses в рабочих процессах закреплены по полному SHA, охватывая семь уникальных коммитов, которые были разрешены и проверены. Эти проверки не заменяют размещённый в GitHub CI, CodeQL, проверку зависимостей, SBOM или задания по происхождению.

Рендерированный браузерный QA в приложении от 2026-08-23 охватывал настольный вьюпорт, а также макеты 390×844 и 320×720, включая обзор и полный поток предпросмотра/согласия для внешних источников. Он подтвердил, что подтверждение скрыто до предпросмотра, выполнил локальный импорт, проверил адаптивный перепоток и переполнение по минимальной ширине и завершился без предупреждений или ошибок в консоли. Прогон обнаружил и исправил преждевременную видимость подтверждения и горизонтальное переполнение на 320px; обновлённый веб-набор прошёл 6/6. Более раннее покрытие навигации, карты, временной шкалы, здоровья, проверки, поиска, брифинга, клавиатуры, Escape и возврата фокуса остаётся частью контракта исходных тестов, но это не результат скринридера, заявление о соответствии WCAG, кроссплатформенная матрица или доказательство на другой операционной системе.

После исправлений функций и рендерированного UI локальный кандидат пакета из 124 файлов был пересобран и прошёл проверку инвентаря, запрещённых файлов, размера, SHA-1 и SHA-512. Чистый временный проект установил этот архив и его зависимости, импортировал выбранный внешний источник, загрузил панель/API и защищённый API проверки, импортировал публичный подпуть расширения и прошёл дымовые тесты конфиденциальности, override и MCP; дымовой тест проверил полный инвентарь из 13 инструментов только для чтения и выполнил репрезентативные чтения навигации, pack-history, доказательств и override. Правки документации создают новый кандидат архива, поэтому финальная передача записывает только самую последнюю повторную квалификацию после документации. Точные дайджесты и размеры архива остаются в локальном отчёте пакета, а не в этом самореферентном документе. Это остаётся локальным артефактным доказательством, а не удалённым репозиторием, размещённой проверкой, подписанным/подтверждённым SBOM артефактом или опубликованным предрелизом.

Сборка копирует лицензию проекта в плагин, генерирует уведомления третьих сторон из зависимостей, фактически включённых в автономный рантайм, а релизные рабочие процессы определены для отклонения дрейфа рантайма/лицензии/уведомлений. Локальные проверки дрейфа рантайма/уведомлений и идентичности релиза проходят, включая паритет между входным тегом-кандидатом, пакетом, lockfile, манифестом плагина, версией, объявленной в MCP, и датированным журналом изменений. Последний локальный дымовой тест пакета также проходит, но эти контроли не доказывают размещённое выполнение или публикацию; те же ворота должны пройти на неизменяемом коммите, выбранном для реального предрелиза GitHub.

Реализация в настоящее время использует встроенный SQLite API Node, который Node 24 всё ещё помечает как экспериментальный. Эта альфа предназначена для одного локального репозитория и одного писателя; размещённое сотрудничество, панели IDE, инкрементальное наблюдение за файловой системой, интеграция хранилища провайдера/UI, более богатый семантический анализ языка и работа над производительностью для больших репозиториев остаются пунктами дорожной карты. Детектирование приватных путей сохранённых пакетов блокирует корень текущего репозитория и широкий набор узнаваемых корней файловой системы хоста, но свободный текст не может идеально отличить каждый пользовательский абсолютный путь POSIX от маршрута API. Retention сужает гонки путей с помощью проверок дескрипторов и идентичности, но не заявляет о безгонковом удалении против злонамеренной подмены компонента каталога тем же пользователем.

Детальный план и доказательства

• docs/PRODUCT_PLAN.md — пользователи, задачи, область охвата, функциональные и нефункциональные требования.

• docs/ARCHITECTURE.md — темпоральная модель данных, границы доверия, приём данных, поиск и проектирование развёртывания.

• docs/RISK_REGISTER.md — сценарии отказов, меры контроля, тесты и остаточный риск.

• docs/IMPLEMENTATION_ROADMAP.md — этапы от прототипа до производственной стабилизации.

• docs/REQUIREMENTS_TRACEABILITY.md — реестр соответствия «требование — мера контроля/тест».

• docs/IMPLEMENTATION_STATUS.md — честные свидетельства того, что реализовано в этой альфа-версии и что осталось в планах.

Участие в проекте, поддержка и релизы

• Прочтите CONTRIBUTING.md перед тем, как предлагать или вносить изменения. В нём задокументированы инварианты границ доверия и стандарт проверки.

• Используйте структурированные формы GitHub issues для воспроизводимых ошибок, запросов на функциональность и проблем с документацией.

• Сообщайте об уязвимостях конфиденциально через SECURITY.md; никогда не публикуйте учётные данные, проприетарный исходный код или реальный каталог .context-atlas/ в публичном issue.

• Участие в проекте регулируется CODE_OF_CONDUCT.md.

• Информация о изменениях в релизах и процедура для мейнтейнеров находятся в CHANGELOG.md и docs/RELEASING.md.

Лицензия

MIT