Перейти к основному содержимому

Обновления конфигурации

Engram использует один движок инвентаризации обновлений для CLI и Entry Web UI. Он сканирует настроенные области workspace и global, классифицирует артефакты, управляемые Engram, строит детерминированный план и использует хеши/отпечатки, чтобы не допускать записи по устаревшим данным.

engram upgrade --latest --plan
engram upgrade --latest --review
engram upgrade --latest
engram upgrade --latest --yes
engram upgrade --help

--plan работает только на чтение. Вывод для человека сгруппирован по типу артефакта в таком порядке: Config, Instructions, Memories, Skillsets, Hooks, Plugins. --plan --json отдаёт тот же сгруппированный план, его отпечаток, состояния проверки и pendingReviewCount. Вкладки типов в UI используют точные подписи All, Config, Instructions, Memories, Skillsets, Hooks, Plugins.

Что обнаруживает Engram​

Инвентаризация охватывает артефакты memory, instruction, skillset, config, hook и plugin в известных расположениях Engram или в зарегистрированных установках подключённых агентов. Корни workspace и global сканируются отдельно; Engram не обходит рекурсивно произвольные деревья домашнего каталога.

Сначала Engram доверяет явным метаданным схемы/версии и метаданным зарегистрированной установки. Для устаревших файлов без маркеров используются известная управляемая структура и ожидаемое содержимое. Каждый элемент классифицируется как current, outdated, conflict или invalid.

Замена и слияние с учётом типа​

Конфликт означает требуется проверка, а не постоянную блокировку. Engram сохраняет правки пользователя, пока тот не подтвердит решение о замене или слиянии.

  • Instructions: Engram предлагает последний управляемый блок, сохраняя текст пользователя вне маркеров Engram. Файл инструкций целиком, принадлежащий Engram, может быть заменён.
  • Skillsets: Engram предлагает последнее содержимое, управляемое Engram. Разделы, явно принадлежащие пользователю, сохраняются, если формат это поддерживает.
  • Config: Engram разбирает конфигурацию и предлагает объединённую миграцию: известные ключи Engram обновляются, при необходимости добавляются новые значения по умолчанию, а посторонние ключи и значения пользователя сохраняются.
  • Memories: Engram выполняет миграцию схемы, а не замену по шаблону.
  • Hooks/plugins: сгенерированные артефакты заменяются только тогда, когда владение можно доказать. Неоднозначный пользовательский код остаётся только на проверку и может быть подтверждён как Keep current.

Проверка конфликтов в Entry Web UI​

Страница Updates теперь представляет собой компактную панель: баннер состояния сообщает, что конфигурация актуальна, требует обновления или требует проверки конфликтов; карточки Workspace, Global и Conflicts показывают основные числа с первого взгляда. После предпросмотра каждый доступный для действия элемент отображается в одной таблице артефактов со столбцами Artifact, Scope, Agent(s), Status, Review и Actions. На узких экранах структура таблицы сохраняется, а вместо полос прокрутки в каждой строке используется один общий контейнер с горизонтальной прокруткой.

Откройте engram entry, затем Settings → Updates. Действие copy command в боковой панели копирует engram upgrade --latest --plan, не уводя вас со страницы. В предпросмотре есть вкладка All и только те вкладки типов, где есть доступные действия: Config, Instructions, Memories, Skillsets, Hooks и Plugins.

У каждого конфликта есть действие Review. Модальное окно предлагает представления Current, Proposed и Diff. Current доступно только для чтения. Proposed редактируется для заменяемых элементов Config/Instruction/Skillset и начинается с результата слияния/замены Engram с учётом типа. Diff по умолчанию показывается как Inline и может переключаться на Parallel. В Inline удалённые строки отмечаются - на красном фоне, добавленные — + на зелёном; Parallel выравнивает строки Current и Proposed с той же красно-зелёной подсветкой. Используйте Use latest, Reset proposed, Keep current или — когда Engram может доказать владение — Force upgrade, затем Confirm change.

Open in editor открывает точный текущий артефакт, определённый сервером, используя $VISUAL, затем $EDITOR, затем запасной вариант платформы. Браузер никогда не передаёт путь к файловой системе. Для Instructions в Proposed находится только управляемый блок <!-- engram:start -->; полный глобальный skillset остаётся в сопутствующем руководстве .agents/engram.md. Если внешняя правка изменила файл, хеш предпросмотра/источника устаревает, и проверку нужно обновить до подтверждения.

У подходящих ожидающих заменяемых конфликтов есть флажки выбора. Select all visible выбирает подходящие строки на активной вкладке типа; выбор сохраняется при переключении вкладок. Confirm selected changes принимает Use latest для отмеченных строк, а Confirm all changes принимает Use latest для каждого подходящего ожидающего конфликта во всём предпросмотре. Незаменяемые, устаревшие и уже проверенные строки выбрать нельзя. Сервер проверяет весь пакет по отпечатку предпросмотра, текущим хешам источников, состояниям проверки и сгенерированным предложениям, после чего выполняет одну атомарную запись в хранилище проверок. Если хотя бы один выбранный элемент не проходит проверку, ни одно решение пакета не сохраняется.

Entry использует одинаковое оформление флажков во всей проверке обновлений: состояния «отмечен», «фокус клавиатуры» и «отключён» визуально различимы. Уведомление toast с результатом использует зелёную рамку/свечение для успеха и красную для ошибок.

Страница показывает ход проверки. Итоговое действие Upgrade остаётся отключённым, пока каждый конфликт явно не разрешён как принятая последняя версия, отредактированное предложение, Force upgrade или Keep current. Итоговое подтверждение сводит вместе автоматические обновления, принятые предложения, отредактированные предложения, принудительные замены, оставленные без изменений файлы и резервные копии.

Принудительное обновление с учётом владения​

Engram канонизирует инвентарь обновлений подключённых агентов по физическому файлу, поэтому общее руководство, например .agents/engram.md, представлено один раз, даже если на него указывают Codex, Claude, Gemini или другой зарегистрированный хост. Список хостов остаётся видимым как метаданные, но один физический файл получает один канонический результат рендера и одну транзакцию записи.

Force upgrade намеренно уже, чем Use latest. Он появляется только тогда, когда Engram может доказать границу владения:

  • Managed region: Engram заменяет только помеченный блок Engram и сохраняет все байты, написанные пользователем, вне его, включая стиль переводов строк файла CRLF/LF.
  • Generated file: Engram может заменить весь зарегистрированный/сгенерированный файл Engram, включая ручные правки внутри этого файла, принадлежащего Engram.
  • Unknown ownership: действие Force upgrade не предлагается; используйте Keep current или сначала устраните неоднозначность владения.

Пакетные элементы управления никогда не применяют принуждение. Confirm selected changes и Confirm all changes ограничены безопасными решениями Use latest. Решения о принудительной замене проверяются по одному и отклоняются, если после предпросмотра изменились хеш источника (source hash), свидетельство владения или режим принуждения.

После завершения записи Engram заново сканирует обновлённые физические артефакты. Элементы, которые должны были обновиться, обязаны прийти к состоянию current; неудачная или откатённая транзакция, а также элемент, оставшийся outdated/conflict, приводят к тому, что вся операция сообщает об ошибке вместо уведомления об успехе. Элементы с явным Keep current из этого требования сходимости исключены.

Проверка конфликтов в CLI​

Запустите:

engram upgrade --latest --review

Интерактивный рецензент обрабатывает неразрешённые конфликты по одному:

[V] View diff
[E] Edit proposed content
[L] Accept latest proposal
[K] Keep current
[Q] Save and quit

E открывает временный файл с предложением, используя $VISUAL, затем $EDITOR, затем запасной вариант платформы. Engram проверяет отредактированное предложение перед принятием. Решения сохраняются в состоянии Engram по отпечатку плана, поэтому Q может прервать сессию, а последующий --review продолжит с сохранёнными решениями.

Для автоматизации:

engram upgrade --latest --yes

--yes никогда не придумывает решения по конфликтам. Если какой-либо конфликт остаётся ожидающим или устаревшим, Engram завершается с ненулевым кодом и просит выполнить engram upgrade --latest --review.

Защита от устаревшей проверки​

Каждый проверенный элемент записывает хеш своего источника. Перед применением Engram сравнивает текущий хеш источника с проверенным. Если файл изменился после проверки, это решение становится устаревшим/ожидающим и требует повторной проверки. Отпечаток плана также не позволяет применить инвентарь, отличный от проверенного.

Группы транзакций, резервные копии и откат​

Принятые замены и слияния проходят тем же путём транзакций, что и безопасные автоматические обновления. Engram фиксирует исходные байты и права доступа, при необходимости создаёт резервные копии, проверяет предлагаемое содержимое, записывает через временный файл и атомарно переименовывает его на место. Неудачное долговременное преобразование откатывает свою группу транзакций. Keep current не выполняет запись.

Векторный индекс работает в режиме fail-open​

Векторный поиск — необязательный слой ускорения. Engram связывает первичные ключи memory_vectors в sqlite-vec целочисленно-совместимыми значениями BigInt. Если перестроение векторов завершается ошибкой, Engram удаляет неполный векторный sidecar/WAL/SHM, сообщает об ухудшенном режиме предупреждением и продолжает долговременное лексическое/графовое обновление. Сбой только векторной части не может прервать в остальном корректное обновление конфигурации.

Версия пакета и состояние конфигурации​

Новый npm-пакет и устаревшая локальная конфигурация — это разные сигналы. Рекомендуемый порядок выпуска:

npm install -g @the-long-ride/engram@latest
engram upgrade --latest --plan
engram upgrade --latest --review
engram upgrade --latest

Повторный запуск обновления идемпотентен для актуальных артефактов. Проверенные файлы Keep current остаются нетронутыми, пока их состояние не изменится и не потребует новой проверки.