Genesys Archivist

捕获 Genesys Cloud Architect 流程及其所依赖的所有资源，然后根据捕获内容生成业务和技术文档。

两个消费者，两个保证：

Archivist 不会构建那个迁移服务器。它保证该服务器将消费的数据契约。

状态

两个阶段都针对真实的 Genesys 组织端到端工作。 约 1,166 个测试，包括 npm run verify 中的格式、lint、生产和测试类型检查以及 schema 验证。

计划 1-5 已构建。每个 archivist 命令都已接线：profile、doctor、capture、document、verify。MCP 服务器公开了九个工具，其中八个由真实实现支持。源路径是通过测量而非假设确定的——Platform API 配置端点（ADR-015）——适配器通过仅暴露 GET 的传输方式访问它，因此只读是类型的一个属性，而不是审查者需要注意的问题（ADR-019）。

针对试点沙箱的测量：15 种类型的 511 个流程，其中 401 个已发布。整个组织的 context 捕获大约 400 个请求，约 95 秒，约 10 MB（S6）。

权限门已关闭

S4 通过。一个专用的只读角色将捕获凭据从 783 个权限策略（580 个变更授权）减少到 16 个策略，零变更、调用方数据或凭据权限——同时保持适配器调用的所有端点可达。详细信息以及该练习发现的四件仅靠阅读无法发现的事情，请参阅 S4。

已知差距

• 迁移模式会一次将所有资产保存在内存中——沙箱上约 110 MB，组织规模无限制。暂时不要对大型真实组织运行它；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 调用，并且该包是一个已发布的契约，而不是一个一次性的缓存。

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

将其指向一个组织

配置文件保存非秘密元数据并命名凭据。客户端密钥从标准输入或隐藏提示中读取，绝不从标志中读取——argv 在进程列表和 shell 历史记录中可见，因此 --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。服务器将协议消息写入标准输出，将其他所有内容写入标准错误，不打开网络监听器，并且不暴露任何接受凭据的工具——一个测试会遍历每个已注册工具的输入模式，如果任何属性名称在任何深度看起来像凭据，则失败。配置仅限 CLI，永远如此。

然后按顺序阅读：

1. CLAUDE.md — 为即将在此编写代码的任何人（人类或代理）提供的方向指南。

2. AGENTS.md — 不可协商的边界。违反其中一条是发布阻塞问题。

3. 设计规范 — 正在构建什么以及为什么。第 2 节列出了与下面编号蓝图文档的差异。

4. 计划 1：基础 — 十二个逐任务 TDD 任务，无需 Genesys 访问权限。

5. 阶段 0 探究 — 解锁其他所有内容的继续/停止门。

阶段 0 是一个继续/停止门，它通过了

有四个源路径在争论中——Platform API、Archy CLI、Architect Scripting SDK 和手动 YAML。哪一个获胜是一个经验结果，而不是一个假设。

探究 S1 测量了 Platform API 配置端点与手动导出的 Architect YAML 基线相比 100% 的结构保真度：47 个节点，10 种构造类型，零无法解释的差异。它还在每个节点上提供了稳定的 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 自动化或调度守护进程

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

蓝图文档

原始交接。在设计规范未覆盖的地方仍然有效。