fathom-upgrade-migration

用途

该技能用于处理 Fathom API 的变更与版本迁移。Fathom 是 AI 会议助手，可录制、转录并总结会议。其 API 运行在 /external/v1 下，提供会议、转录文本和行动项等端点。由于 Fathom 对转录结构字段（说话人归属、情感数据、高亮片段）迭代迅速，响应结构的破坏性变更可能静默破坏那些消费会议数据用于 CRM 同步或分析管道的下游集成，因此跟踪 API 变更很重要。

主要能力

版本检测

通过请求会议列表接口，将检测到的字段与已知字段进行对比，输出 apiVersion、knownFields、detectedFields、newFields、removedFields。基础地址为 https://api.fathom.video/external/v1。

const FATHOM_BASE = "https://api.fathom.video/external/v1";

interface FathomVersionCheck {
  apiVersion: string;
  knownFields: string[];
  detectedFields: string[];
  newFields: string[];
  removedFields: string[];
}

async function detectFathomApiChanges(apiKey: string): Promise<FathomVersionCheck> {
  const res = await fetch(`${FATHOM_BASE}/meetings?limit=1`, {
    headers: { Authorization: `Bearer ${apiKey}` },
  });
  const data = await res.json();
  const knownFields = ["id", "title", "created_at", "duration", "attendees", "transcript_url"];
  const detectedFields = data.meetings?.[0] ? Object.keys(data.meetings[0]) : [];
  return {
    apiVersion: res.headers.get("x-api-version") ?? "v1",
    knownFields,
    detectedFields,
    newFields: detectedFields.filter((f) => !knownFields.includes(f)),
    removedFields: knownFields.filter((f) => !detectedFields.includes(f)),
  };
}

迁移检查清单

查阅 Fathom 产品更新，了解 API 变更与弃用
审计代码库中所有引用 /external/v1 的端点
验证会议列表响应结构是否符合当前字段预期
检查转录端点是否有新的说话人归属字段
验证行动项提取格式（结构化 vs. 纯文本）
如认证端点变更，更新 OAuth 令牌刷新流程
测试会议完成事件的 webhook 负载
验证分页参数（cursor vs. offset）是否为当前版本
如会议元数据字段重命名，更新 CRM 同步映射
针对 Fathom 沙箱环境运行集成测试

结构迁移

转录响应从扁平文本演进为带说话人归属的分段结构。

// Fathom transcript response evolved: flat text → speaker-attributed segments
interface OldTranscript {
  meeting_id: string;
  text: string;
  created_at: string;
}

interface NewTranscript {
  meeting_id: string;
  segments: Array<{
    speaker: string;
    text: string;
    start_time: number;
    end_time: number;
    confidence: number;
  }>;
  summary: string;
  action_items: Array<{ text: string; assignee?: string }>;
  created_at: string;
}

function migrateTranscript(old: OldTranscript): NewTranscript {
  return {
    meeting_id: old.meeting_id,
    segments: [{ speaker: "Unknown", text: old.text, start_time: 0, end_time: 0, confidence: 1.0 }],
    summary: "",
    action_items: [],
    created_at: old.created_at,
  };
}

回滚策略

class FathomClient {
  private baseUrl: string;
  private fallbackUrl: string;

  constructor(private apiKey: string) {
    this.baseUrl = "https://api.fathom.video/external/v1";
    this.fallbackUrl = "https://api.fathom.video/external/v1"; // same base, version in path
  }

  async getMeetings(limit = 20): Promise<any> {
    try {
      const res = await fetch(`${this.baseUrl}/meetings?limit=${limit}`, {
        headers: { Authorization: `Bearer ${this.apiKey}` },
      });
      if (!res.ok) throw new Error(`Fathom API ${res.status}`);
      return await res.json();
    } catch (err) {
      console.warn("Primary endpoint failed, attempting fallback:", err);
      const res = await fetch(`${this.fallbackUrl}/meetings?limit=${limit}`, {
        headers: { Authorization: `Bearer ${this.apiKey}`, Accept: "application/json; version=legacy" },
      });
      return await res.json();
    }
  }
}

错误处理

迁移问题	症状	修复方式
转录结构变更	缺少 segments 数组，仅返回扁平文本	更新解析器，同时兼容旧扁平格式与新分段格式
Webhook 负载不匹配	meeting.completed 事件缺少预期字段	使用更新后的事件结构版本重新注册 webhook
OAuth 作用域扩展	转录端点返回 403 Forbidden	使用更新后的作用域重新授权（meetings.read、transcripts.read）
分页游标无效	携带 cursor 令牌时返回 400 Bad Request	如 API 变更，从 offset 分页切换到 cursor 分页
速率限制头变更	返回 429 且无 Retry-After 头	使用指数退避，而非依赖该头

使用方式

前置条件：当前/目标版本清单、兼容性说明、合成测试夹具、验收标准，以及回滚负责人。

操作流程：盘点配置、凭证、CRM 映射、访问、保留与同意行为；在开发/测试环境中用合成会议与记录测试目标版本；在有限金丝雀发布前对比聚合质量、交付、错误、访问与策略结果；出现回归时暂停或回滚，并保留先前配置直到签字确认。

输出：一份分阶段升级记录，包含证据、负责人、观察窗口与回滚修订版本。

适用场景

适用于对 Fathom 集成进行版本升级与迁移，在测试环境运行模拟/单元与合成工作流检查，对比新旧版本的聚合同步/跟进行为。若出现同意、访问、映射或可靠性回归则回滚；不应通过重放客户会议来验证迁移。

限制

触发方式为“upgrade fathom”、“fathom api changes”、“fathom migration”等短语。相关资源包括 Fathom 产品更新与 Fathom API 文档。CI 管道集成参见 fathom-ci-integration。