Fireflies 架构与契约迁移
概述
本技能用于将 Fireflies 的 GraphQL 文档与 Webhook 消费者从已弃用字段和旧版事件形态迁移到当前契约，做法包含双重读取证据与回滚机制。
先决条件
需要目标仓库或集成路径，以及所请求的操作者结果。 需要确定本次工作的 Fireflies 主体、团队、环境和数据分类。 需要当前 Fireflies 文档、仅在必要时使用的凭据，以及一名可问责的批准人。
当前契约
当前转录列表过滤器以 keyword 取代 title，并以 organizers 和 participants 取代 organizer_email 和 participant_email。Webhooks V2 使用 event、timestamp、meeting_id 以及更细粒度的 meeting.transcribed 或 meeting.summarized 事件，取代 V1 的 eventType 形态。
认证
对于需要认证的操作，从获批的密钥管理器注入 FIREFLIES_API_KEY，并且仅以 Authorization: Bearer REDACTED_KEY 的形式发送到 https://api.fireflies.ai/graphql。切勿打印、提交、放入 URL、转发到浏览器或在证据中包含该密钥。Webhook 签名密钥是独立凭据，不得复用为 API 密钥。
操作步骤
盘点静态 GraphQL 文档、选取字段、响应解析器、Webhook 负载和夹具。 将弃用字段和 V1 Webhook 假设映射到当前文档化契约。 仅在经测量的过渡需要时添加兼容解析。 在生产流量之前更新合成夹具和契约测试。 对授权元数据运行影子对比，比较 ID、计数、可空性和事件顺序。 一次只切换一个操作或一个事件族，并配合回滚开关。 仅在观察窗口结束并获负责人签核后移除兼容代码。
工具纪律
使用 Read、Glob 和 Grep 检查代码、配置、测试和证据。仅在获批准的实现或文档变更中使用 Write/Edit。不得仅因调用本技能就查询 Fireflies、检索会议内容、创建 AskFred 线程、上传媒体、更改账户状态、重放事件或部署。
审批边界
在启用新事件订阅、扩大转录搜索、更改所选敏感字段或移除回滚兼容之前，必须获得批准。
输出
返回确切的操作或事件表面、环境、授权类别、所选字段组、验证结果、不含内容的指标、决策以及简洁的通过/失败回执。确保密钥和会议衍生内容不出现在通用输出中。
验证
在报告成功之前，重新运行最小相关确定性检查，将实际状态与所请求结果和当前契约进行对比，验证没有密钥或会议衍生内容进入日志或产物，并明确记录未解决的不确定性。
错误处理
新字段缺失：保留可空性并验证权限或处理状态。 重复的 V1/V2 事件：按事件标识和会议 ID 去重。 结果集漂移：停止切换并比较过滤器语义。
示例
“审查 fireflies schema and contract migration”会生成一个受约束的计划和经脱敏的回执。 凡扩大访问权限或变更生产环境的请求，都会在审批边界处暂停。
资源
在依赖某个字段、过滤器、事件、权限、计划限制、变更或处理状态之前，请先阅读官方 Fireflies.ai 证据。