Genesys Archivist

Genesys Cloud Architect 플로우와 해당 플로우가 의존하는 모든 리소스를 캡처한 다음, 그 캡처 결과로부터 비즈니스 및 기술 문서를 생성합니다.

두 가지 소비자, 두 가지 보장:

Archivist는 해당 마이그레이션 서버를 구축하지 않습니다. 그 서버가 소비할 데이터 계약을 보장할 뿐입니다.

상태

두 단계 모두 실제 Genesys 조직을 대상으로 엔드투엔드로 작동합니다. 약 1,166개의 테스트가 있으며, npm run verify에서 포맷, 린트, 프로덕션 및 테스트 타입체크, 스키마 검증이 수행됩니다.

플랜 1~5가 구축되었습니다. 모든 archivist 명령이 연결되어 있습니다: profile, doctor, capture, document, verify. MCP 서버는 9개의 도구를 노출하며, 그중 8개는 실제 구현으로 뒷받침됩니다. 소스 경로는 가정이 아닌 측정을 통해 결정되었습니다 — Platform API 구성 엔드포인트(ADR-015) — 그리고 어댑터는 GET만 노출하는 전송을 통해 해당 엔드포인트에 도달하므로, 읽기 전용은 검토자의 주의가 필요한 사항이 아니라 타입의 속성입니다(ADR-019).

파일럿 샌드박스를 기준으로 측정: 15개 유형에 걸친 511개 플로우, 401개 게시됨. 전체 조직 context 캡처는 약 400개 요청, 약 95초, 약 10MB입니다(S6).

릴리스 게이트 하나가 열려 있음

권한 매트릭스가 실패합니다. 샌드박스 OAuth 클라이언트는 사실상 관리자입니다: 783개의 권한 정책 중 580개가 변경 작업을 부여하며, 여기에는 architect:flow 게시 및 삭제가 포함됩니다. 이 저장소의 어떤 것도 이를 호출하지 않으며 호출할 수도 없지만, 게이트는 호출 횟수가 아닌 보유 권한을 측정합니다. npm run spike:s4는 생성할 읽기 전용 역할을 출력합니다. 전체 세부 사항 및 해결 방법은 S4에 있습니다.

알려진 격차

• 마이그레이션 모드는 모든 자산을 한 번에 메모리에 보관합니다 — 샌드박스에서 약 110MB, 조직 규모에 따라 무제한. 아직 대규모 실제 조직에 대해 실행하지 마십시오. context 모드는 영향을 받지 않습니다. 세 가지 순위가 매겨진 수정 사항이 플랜 5에 있습니다.

• genesys_flow_diff는 여전히 결과 대신 명시적 거부를 반환합니다.

• 변경 감지는 순수 결정 함수로 존재하지만 I/O가 연결되지 않아 매 실행마다 모든 플로우를 다시 처리합니다.

• 테스트 파일 하나가 Windows에서 약 6번 중 1번꼴로 불안정하게 실패하며, 자체 헤더에 문서화되어 있습니다.

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단계 (캡처) 는 Genesys와 통신하는 유일한 코드입니다: 모든 유형의 모든 플로우를 발견하고, 정의를 가져오고, 리소스 참조 그래프를 완전히 순회하고, 바이너리 자산을 다운로드하고, 불변의 콘텐츠 해시 캡처 번들을 봉인합니다. 2단계 (문서화) 는 소켓을 열지 않습니다 — 번들을 읽고 Markdown, SVG 다이어그램, PDF를 생성하며, 중간에 AI 내레이션이 있습니다. 따라서 문서를 다시 렌더링하는 데는 Genesys API 호출 비용이 0이며, 번들은 일회용 캐시가 아닌 게시된 계약입니다.

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를 제공합니다.

AI 클라이언트에서 구동

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

STDIO 전용. 서버는 프로토콜 메시지를 stdout에 쓰고 그 외 모든 것을 stderr에 쓰며, 네트워크 리스너를 열지 않고 자격 증명을 수락하는 도구를 노출하지 않습니다 — 테스트가 등록된 모든 도구의 입력 스키마를 순회하며 어떤 속성 이름이 어떤 깊이에서든 자격 증명 형태이면 실패합니다. 프로비저닝은 영원히 CLI 전용입니다.

그런 다음 순서대로 읽으십시오:

1. CLAUDE.md — 여기서 코드를 작성하려는 모든 사람(인간 또는 에이전트)을 위한 오리엔테이션.

2. AGENTS.md — 양보할 수 없는 경계. 위반은 릴리스 차단 요인입니다.

3. 설계 사양 — 무엇을 왜 구축하는지. 섹션 2는 아래의 번호가 매겨진 청사진 문서에서 벗어나는 지점을 나열합니다.

4. 플랜 1: 기반 — Genesys 액세스가 필요 없는 12개의 작업별 TDD 작업.

5. Phase 0 스파이크 — 다른 모든 것을 잠금 해제하는 진행/중단 게이트.

Phase 0은 진행/중단 게이트였으며 통과했습니다

네 가지 소스 경로가 경쟁 중이었습니다 — Platform API, Archy CLI, Architect Scripting SDK, 수동 YAML. 어느 것이 승리했는지는 가정이 아닌 경험적 결과였습니다.

스파이크 S1은 Platform API 구성 엔드포인트를 수동으로 내보낸 Architect YAML 기준선 대비 100% 구조적 충실도로 측정했습니다: 47개 노드, 10개 구성 유형, 설명할 수 없는 차이 0건. 또한 모든 노드에 안정적인 trackingId와 ID 및 노드별 출처가 있는 참조 리소스 매니페스트를 제공합니다. Architect Scripting SDK는 완전히 폐기되었습니다(ADR-015); 훨씬 높은 종속성 비용으로 엄격한 하위 집합만 제공했을 것입니다.

권한 매트릭스 스파이크는 이후 실행되었고 실패했습니다 — S4 및 위의 상태 섹션을 참조하십시오. 프롬프트 오디오 다운로드는 읽기 전용으로 확인되어 킬 기준 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, 라우팅 로직, 고객 PII를 보유할 수 있는 데이터 테이블 행, 프롬프트 오디오를 포함합니다. CI는 이 중 하나라도 추적되면 빌드를 실패시킵니다.

용어

대상은 Genesys Cloud CX이며, IVR 작성 제품은 Architect입니다.

플로우에는 flowId와 같은 식별자와 버전이 있습니다. 큐, 프롬프트, 데이터 액션, 스케줄 및 재사용 가능한 플로우에도 식별자가 있습니다. 이것들은 비밀 API 키가 아닙니다. Genesys OAuth client_id 및 client_secret은 통합을 인증하며 관련된 유일한 비밀입니다. 이 도구는 숨겨진 비밀을 열거하거나, OAuth 클라이언트 시크릿을 복구하거나, 비밀번호를 스크래핑하거나, Genesys 권한을 우회하지 않습니다.

첫 번째 프로덕션 릴리스의 비목표

• Genesys 플로우 편집, 게시, 삭제 또는 가져오기

• 고객 비밀 복구 또는 나열

• 실시간 발신자 데이터, 녹음, 대화 내용 또는 과거 실행 데이터 읽기

• 캡처된 데이터에 대한 쿼리 또는 Q&A 도구

• 원격 HTTP 호스팅, git/PR 자동화 또는 스케줄링 데몬

• 구성에서 추론할 수 없는 비즈니스 의도 주장

청사진 문서

원래 인계 문서. 설계 사양이 이를 재정의하지 않는 한 여전히 적용됩니다.