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、路由逻辑、可能包含客户 PII 的数据表行以及提示音音频。如果这些文件中的任何一个被跟踪，CI 将导致构建失败。

术语

目标是 Genesys Cloud CX，IVR 创作产品是 Architect。

一个流程具有诸如 flowId 之类的标识符以及一个版本。队列、提示音、数据操作、时间表和可复用流程也具有标识符。这些不是秘密 API 密钥。 Genesys OAuth client_id 和 client_secret 用于对集成进行身份验证，是仅有的秘密。该工具绝不枚举隐藏的秘密、恢复 OAuth 客户端密钥、抓取密码或绕过 Genesys 权限。

首个生产版本的非目标

• 编辑、发布、删除或导入 Genesys 流程

• 恢复或列出客户秘密

• 读取实时呼叫者数据、录音、转录文本或历史执行数据

• 针对捕获数据的查询或问答工具

• 远程 HTTP 托管、git/PR 自动化或调度守护进程

• 声称无法从配置中推断出的业务意图

蓝图文档

原始的交接文档。在设计规范未覆盖之处仍然具有约束力。