Genesys Archivist

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

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

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

Статус

Предреализационный этап. Фаза 0 не запускалась. Дизайн и планы завершены; производственного кода пока нет.

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

Два этапа, разделённые жёстким стыком. Этап 1 (захват) — единственный код, который общается с Genesys: он обнаруживает все потоки всех типов, получает определения, обходит граф ссылок на ресурсы до замыкания, загружает бинарные ассеты и запечатывает неизменяемый пакет захвата с хешированием содержимого. Этап 2 (документирование) не открывает сокетов — он читает пакет и создаёт Markdown, SVG-диаграммы и PDF, с AI-повествованием посередине. Повторная генерация документации поэтому не стоит ни одного вызова 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

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

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

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

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

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

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

Фаза 0 — это ворота go/no-go

Прежде чем создавать адаптеры Genesys, докажите на непроизводственной организации, что OAuth-клиент с доступом только на чтение может перечислить все требуемые типы потоков по страницам и подразделениям; что исходный путь может корректно загружать и экспортировать опубликованные потоки; что аудио подсказок загружается только на чтение; и что не требуется разрешение на изменение. Десять спайков, двенадцать критериев остановки. См. docs/spikes/.

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

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

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 или демон планировщика

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

Проектные документы

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