Genesys Archivist

Захватывает потоки Genesys Cloud Architect и все ресурсы, от которых они зависят, а затем генерирует бизнес- и техническую документацию на основе этого захвата.

Два потребителя, две гарантии:

Archivist не создаёт этот миграционный сервер. Он гарантирует контракт данных, который этот сервер будет потреблять.

Status

Обе стадии работают сквозным образом против реальной организации Genesys. ~1,166 тестов, включая проверку форматирования, линтер, проверку типов для продакшена и тестов, а также валидацию схемы в npm run verify.

Планы 1–5 реализованы. Каждая команда archivist подключена: profile, doctor, capture, document, verify. MCP-сервер предоставляет девять инструментов, восемь из которых подкреплены реальными реализациями. Путь к источнику был определён измерением, а не предположением — конфигурационный endpoint Platform API (ADR-015) — и адаптер обращается к нему через транспорт, который предоставляет только GET, так что режим «только чтение» является свойством типа, а не предметом внимания рецензента (ADR-019).

Измерено на пилотной песочнице: 511 потоков 15 типов, 401 опубликован. Захват context для всей организации — это около 400 запросов, ~95 секунд, ~10 МБ (S6).

Один релизный гейт остаётся открытым

Матрица разрешений не проходит. OAuth-клиент песочницы фактически является администратором: 783 политики разрешений, 580 из них предоставляют изменяющее действие, включая публикацию и удаление architect:flow. Ничто в этом репозитории их не вызывает и не может вызвать, но гейт измеряет предоставленные разрешения, а не совершённые вызовы. npm run spike:s4 выводит роль «только для чтения», которую следует создать. Полные подробности и меры устранения — в S4.

Известные пробелы

• Режим миграции удерживает все ассеты в памяти одновременно — ~110 МБ в песочнице, не ограничен размером организации. Пока не запускайте его против крупной реальной организации; режим context не затронут. Три ранжированных исправления находятся в Plan 5.

• genesys_flow_diff по-прежнему возвращает явный отказ, а не результат.

• Обнаружение изменений существует как чистая функция принятия решения, но её ввод/вывод не подключён, поэтому каждый запуск заново обрабатывает каждый поток.

• Один тестовый файл нестабилен примерно в 1 запуске из 6 на Windows; это задокументировано в его собственном заголовке.

Related MCP server: codebase-doc-generator

Два режима захвата

Согласно ADR-018, у захвата две задачи, и они названы раздельно:

archivist capture --mode context   --org <id> [--flow <id>...]
archivist capture --mode migration --org <id> [--flow <id>...]

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

migration захватывает всё, что нужно для воссоздания IVR в другом месте: каждый ресурс целиком, каждый байт аудио подсказок, строки таблиц данных.

Оба создают пакет. Пакет context записывает policy.mode: "context", сообщает migrationReadiness.archyImportableYaml: false и содержит текстовое предупреждение об этом — его невозможно перепутать с пакетом, готовым к миграции.

Архитектура в одном абзаце

Две стадии, разделённые жёстким швом. Стадия 1 (capture) — единственный код, который общается с Genesys: она обнаруживает все потоки всех типов, получает определения, обходит граф ссылок на ресурсы до замыкания, скачивает бинарные ассеты и запечатывает неизменяемый пакет захвата с хешированием содержимого. Стадия 2 (document) не открывает сокеты — она читает пакет и создаёт Markdown, SVG-диаграммы и PDF, с ИИ-повествованием между ними. Повторная генерация документации, таким образом, не требует ни одного вызова Genesys API, а пакет является опубликованным контрактом, а не одноразовым кэшем.

flowchart TD
    A["AI client"] -->|MCP STDIO| B["MCP adapter"]
    C["archivist CLI"] --> D["Application service"]
    B --> D
    D --> E["Genesys source provider"]
    E --> F["Genesys Cloud"]
    D --> G["Capture bundle (sealed, immutable)"]
    G --> H["Normalize, analyze, document"]
    H --> I["Markdown + diagrams + PDF"]
    G --> J["Future migration server"]

Начало работы

npm install
npm run verify        # format + lint + typecheck + test + schema validation
npm run build

Настройка на организацию

Профиль хранит несекретные метаданные и содержит имя учётных данных. Секрет клиента считывается из stdin или скрытого запроса, никогда — из флага — argv виден в списках процессов и истории оболочки, поэтому --client-secret отклоняется с объяснением, а не принимается.

archivist profile add \
  --id acme --display-name "Acme Bank" \
  --region euw1 --org <organizationId> \
  --client-id <oauthClientId> \
  --output-root /path/to/output
# then paste the secret at the prompt, or:  echo "$SECRET" | archivist profile add ...

archivist doctor                 # Node version, credential store, profiles
archivist profile validate acme  # profile parses, secret present, root writable

Захват и документирование

# Fast, whole-organization. Definitions plus the resource manifest that
# already travels with them. Cannot be migrated — see ADR-018.
archivist capture --profile acme --mode context --org <organizationId>

# Everything needed to rebuild elsewhere: resource bodies, prompt audio,
# data-table rows. See the memory caveat above before running this at scale.
archivist capture --profile acme --mode migration --org <organizationId> --flow <flowId>

archivist verify   --bundle <bundleDir>    # content hashes still match
archivist document --bundle <bundleDir>    # business.md, technical.md, operations.md, diagrams

--profile обязателен для capture, и не просто для удобства: профиль задаёт утверждённый корневой каталог вывода и expectedOrganizationId, который защищает от того, чтобы ошибочно введённые учётные данные захватили конфигурацию не того заказчика.

Управление из ИИ-клиента

{
  "mcpServers": {
    "genesys-archivist": { "command": "genesys-archivist-mcp" }
  }
}

Только STDIO. Сервер пишет протокольные сообщения в stdout, а всё остальное — в stderr, не открывает сетевой слушатель и не предоставляет ни одного инструмента, принимающего учётные данные — тест проходит по схеме ввода каждого зарегистрированного инструмента и завершается ошибкой, если имя любого свойства на любой глубине имеет форму учётных данных. Настройка — только через CLI, навсегда.

Затем прочитайте по порядку:

1. CLAUDE.md — ориентация для любого (человека или агента), кто собирается писать здесь код.

2. AGENTS.md — необсуждаемые границы. Нарушение любой из них — блокер релиза.

3. Дизайн-спецификация — что и зачем строится. Раздел 2 перечисляет, где она отступает от нумерованных документов-чертежей ниже.

4. План 1: Фундамент — двенадцать задач TDD, по одной задаче за раз, которым не нужен доступ к Genesys.

5. Спайки фазы 0 — гейт go/no-go, который разблокирует всё остальное.

Фаза 0 была гейтом go/no-go, и он был пройден

На рассмотрении были четыре пути к источнику — Platform API, CLI Archy, Architect Scripting SDK и ручной YAML. Какой из них победил, было установлено эмпирически, а не предположением.

Спайк S1 измерил конфигурационный endpoint Platform API, показав 100% структурную точность относительно вручную экспортированного базового YAML Architect: 47 узлов, 10 типов конструкций, ноль необъяснённых различий. Кроме того, он предоставляет стабильный trackingId на каждом узле и манифест ресурсов, на которые есть ссылки, с идентификаторами и происхождением для каждого узла. Architect Scripting SDK был полностью исключён (ADR-015); он дал бы строгое подмножество при гораздо более высокой стоимости зависимостей.

Спайк матрицы разрешений с тех пор был запущен и провалился — см. S4 и раздел Status выше. Загрузка аудио подсказок работает в режиме только чтения, что закрывает критерий остановки 11 (S5), а бюджеты масштабирования измерены (S6). Обратите внимание: две схемы нумерации спайков расходятся, начиная с S3; ссылайтесь на спайки по имени файла, а не по номеру.

Структура репозитория

apps/cli               archivist CLI
apps/mcp-server        genesys-archivist MCP STDIO server
packages/domain        contracts and DTOs. Pure: no I/O, no SDK types
packages/application   use cases, run state machines, policy
packages/composition   the one place adapters are wired to interfaces
packages/...           adapters, capture, analysis, documentation, rendering, narrative
schemas/               versioned JSON Schema contracts
fixtures/              sanitized test fixtures. Never real customer configuration
docs/                  blueprint, design spec, plans, ADRs, spikes

Направление зависимостей обеспечивается ESLint, а не соглашением: domain ничего не импортирует, application импортирует только domain, а apps/* остаются тонкими.

Никогда не коммитьте

bundles/, derived/, documentation/, spike-evidence/ или любые .wav / .mp3. Пакеты захвата относятся к категории restricted — они содержат URL-адреса конечных точек, DID, логику маршрутизации, строки таблиц данных, которые могут содержать персональные данные клиентов, и аудио подсказок. CI завершает сборку ошибкой, если любой из этих файлов отслеживается.

Терминология

Целевая платформа — Genesys Cloud CX, а продукт для создания IVR — Architect.

У потока есть идентификаторы, такие как flowId, и версия. Очереди, подсказки, действия с данными, расписания и переиспользуемые потоки также имеют идентификаторы. Это не секретные API-ключи. OAuth client_id и client_secret Genesys аутентифицируют интеграцию и являются единственными используемыми секретами. Инструмент никогда не перечисляет скрытые секреты, не восстанавливает секреты OAuth-клиента, не собирает пароли и не обходит разрешения Genesys.

Не-цели первого производственного релиза

• Редактирование, публикация, удаление или импорт потоков Genesys

• Восстановление или перечисление секретов клиентов

• Чтение оперативных данных о звонящих, записей разговоров, транскриптов или исторических данных выполнения

• Инструменты запросов и Q&A по захваченным данным

• Удалённый HTTP-хостинг, автоматизация git/PR или демон планировщика

• Утверждение бизнес-намерения, которое невозможно вывести из конфигурации

Документы-чертежи

Исходная передача. По-прежнему действует везде, где дизайн-спецификация её не отменяет.