notebooklm-py 工件生成结果的密封类型设计：GenerationStatus 角色分区、迁移路径与推迟决策（ADR-0020 深度解析）-育师

notebooklm-py 工件生成结果的密封类型设计：GenerationStatus 角色分区、迁移路径与推迟决策（ADR-0020 深度解析）

【免费下载链接】notebooklm-pyUnofficial Python API and agentic skill for Google Gemini Notebook. Full programmatic access to NotebookLM's features—including capabilities the web UI doesn't expose—via Python, CLI, and AI agents like Claude Code, Codex, and OpenClaw.项目地址: https://gitcode.com/GitHub_Trending/no/notebooklm-py

本篇技术指南围绕 notebooklm-py 仓库中的 ADR-0020 密封异步结果类型（Sealed async result types for artifact generation）展开，深入剖析其决策背景、设计蓝图（A1–A6）、推迟结论与触发重建条件，并结合当前仓库的源码实现与测试证据逐条验证。读者读完后，将能完整理解 NotebookLM 工件（Audio Overview、Report、Video 等）生成任务的状态类型为何采用"扁平 dataclass + 字符串枚举 + 测试强制分区"的现状，以及一套"密封联合类型（sealed union）"方案在真实数据约束下的可行性边界与分阶段迁移路径。

一、背景：一个返回类型、两种角色、约 13 个消费方

ADR-0020 讨论的核心对象是GenerationStatus，定义于 src/notebooklm/_types/artifacts.py：

@dataclass class GenerationStatus: task_id: str # Same as artifact_id - used for polling and becomes Artifact.id status: GenerationState url: str | None = None error: str | None = None error_code: str | None = None # e.g., "USER_DISPLAYABLE_ERROR" for rate limits metadata: dict[str, Any] | None = None

它是一个非 frozen 的@dataclass，由约 13 个方法以两种截然不同的角色返回：

角色	返回值状态集合	方法
Snapshot（快照）	`pending / in_progress / completed / failed / not_found / unknown`	`generate_*`系列 ×10、`revise_slide`、`retry_failed`、`poll_status`
Terminal（终态）	`completed / failed / removed`	`wait_for_completion`

两个角色之间的状态分区是严格的：not_found只由轮询侧产出、removed只由等待侧产出，wait_for_completion在超时场景下抛出ArtifactTimeoutError而非返回一个TimedOut变体。关键点是：这条分区目前只靠"生产者约定"成立，并由测试强制，而不是由类型强制——这就是本 ADR 的出发点。

从源码看，kicokoff（启动）类方法不接收wait标志，因此它们的返回角色是稳定的；这也是设计讨论得以成立的前提。

二、现状盘点：枚举、规范化器与测试强制分区

在 ADR 提出之时（基线mainat #1447f0d2d1be, v0.8.0），GenerationStatus.status已经完成从裸字符串到枚举的升级（#1447，本 ADR 之外已完成的工作），GenerationState(str, Enum)是当前仓库的真实实现：

poll 集合：PENDING、IN_PROGRESS、COMPLETED、FAILED、NOT_FOUND、UNKNOWN；
罕见后端状态：SUGGESTED（当前无生产者，被ArtifactListingService.list_raw的服务器端过滤无条件排除，建模属防御性深度）、PENDING_REVIEW（语义未确认，保留可检索性）；
wait-only：REMOVED——由wait_for_completion在持续消失（sustained delisting）时合成。

GenerationState.is_terminal是"生成是否已结束"的唯一权威定义（COMPLETED / FAILED / REMOVED），且"新加入的成员默认非终态"——因为等待一个已完成任务的代价是一次浪费的轮询，而终结一个仍在运行任务的代价是丢失结果。_TERMINAL_GENERATION_STATESfrozenset 直接由该属性派生，保证分区只定义一次（见 src/notebooklm/_types/artifacts.py）。

_status_from_code是"上游 int→state 规范化器"，而不是设计迁移的接缝。它把 API 状态码映射为GenerationState（None默认映射到PENDING，未识别码落到UNKNOWN），永远不会发射NOT_FOUND/REMOVED——这两个状态是在 src/notebooklm/_artifact/polling.py 中直接构造的：

poll_status在工件 ID 缺席于列表时返回GenerationStatus(task_id=task_id, status=GenerationState.NOT_FOUND)（L150）；
wait_for_completion的轮询循环在consecutive_not_found连续缺失满足双阈值（>= max_not_found且耗时>= min_not_found_window，或连续次数>= max_not_found * 2的窗口无关触发）后，构造携带REMOVED与说明性错误文本的GenerationStatus（L441-L453）。

分区被测试钉死。tests/unit/test_generation_state.py中的test_poll_status_never_returns_removed逐码验证poll_status的每一种输入都不可能返回removed；test_status_from_code_never_returns_wait_only_states则把_status_from_code的不可发射范围固定在测试里；test_is_terminal_partitions_the_enum_exactly断言is_terminal恰好三成员；test_generation_status_is_terminal_works_on_a_plain_string_status验证is_terminal是唯一按哈希集合查找的谓词（其余is_*谓词按==比较，因此对裸字符串构造的实例同样有效——这是str在GenerationStateMRO 中先于Enum、str.__hash__胜出的机制后果，测试直接钉住该机制以防基类重排）。

三、残留问题：类型卫生的三个缺口

#1447 之后仍有三处"类型不卫生"（type hygiene）问题，这也是 ADR 动议的动机：

非法字段组合仍可表示：url / error / error_code全部可选，理论上可以构造出"既带 error 又带 url"或"failed 却带 url"的自相矛盾实例；
分区不在类型里：not_found仅轮询、removed仅等待这一约束只是约定 + 测试，类型系统本身不阻止误用；
is_rate_limited的判定脆弱：它先检查error_code == "USER_DISPLAYABLE_ERROR"，失败后回退到对error文本做子串匹配（"rate limit"/"quota"/"limit exceeded"），且把removed与failed同等对待以便限流重试策略在服务端静默丢弃工件时仍能工作（见 src/notebooklm/_types/artifacts.py）。

值得强调的是 ADR 的判断：#1342已经移除了承重的重载（"无法启动即抛异常"的路径），因此这是类型卫生问题，而非正确性缺口——这也直接影响了最终的推迟结论。

四、决策 A：密封结果类型的设计蓝图（A1–A6）

ADR 将"如果构建，长什么样"完整规格化，共六条。

A1 — 两种角色类型

PollResult=Pending | InProgress | Completed | Failed | NotFound | Unknown（快照方法用）；
WaitOutcome=Completed | Failed | Removed（等待器用）。

分区被编码进类型本身，这是相对现状的核心增益之一。

A2 — 独立 frozen 变体，而非`GenerationStatus`子类

理由：frozen 变体无法继承非 frozen 的GenerationStatus；可变的子类也无法让状态不可变。字段排序问题可以用kw_only=True规避，但不可变性无法规避。

但 A2 附带一个"缩小收益的冷水警告"：头号卖点——每个变体的必需字段——在当前数据面前大体无法实现：

Completed.url对非媒体工件合法地为None（ArtifactRow.is_media_ready对非媒体类型恒真），kickoff 即完成（_parse_generation_result，位于_artifacts.py）时同样为None；
Failed.error有时为None（poll_status在 src/notebooklm/_artifact/polling.py 中的构造只填充url与metadata，不填error）；
Removed携带error但没有error_code（等待循环的 removed 构造，见上节 L441-L450）。

因此Completed.url/Failed.error只能保持str | None（或者让Completed拆成媒体完成url: str与文档完成url: str | None两个变体）。变体买到的实际价值是角色分离 + 穷尽式match+ 结构化失败，而不是"非法状态不可表示"。ADR 明确建议：在投入 A1–A6 之前，先重新评估下文 Alternatives 中的子类型细化方案。

A3 — 超时保持为异常

不引入TimedOut变体，与 ADR-0019 的异常模型保持一致。

A4 —`failure_reason: FailureReason`（`RATE_LIMIT | OTHER | UNKNOWN`）

挂在Failed/Removed上，推导规则必须钉死：

error_code == "USER_DISPLAYABLE_ERROR"（或当前的消息启发式——因error_code经常缺失而保留在分类器内部）→RATE_LIMIT；
存在失败但非限流 →OTHER；
无法分类（无error_code、消息也不匹配）→UNKNOWN。

关键认知：A4 并不会免费去掉子串匹配，它只是把匹配从散落各处的调用点收拢进单一分类器。error/error_code在变体上仍然可选。

A5 — 兼容性仅限鸭子类型 / 源码层面

通过共享的Protocol/ mixin 暴露.status+is_*，让谓词型消费者可以渐进迁移：

_app/generate_retry.py中的鸭子类型hasattr(status, "is_complete")（从源码看，ADR 记载的 CLI 服务层 duck-type 在重构后由 src/notebooklm/_app/generate_retry.py 承担类似职责）；
_artifact/polling.py轮询循环的status.is_complete or status.is_failed（L387）；
match/.status调用方。

但它不保留名义类型检查（nominal checks），以下引用具体类型的点都是明确的迁移工作：

generate_retry.py中的isinstance(result, GenerationStatus)门（L105、L209）；
CLI 层对 JSON 字段的直接镜像；
wait_for_completion的on_status_change回调（polling.py 每次状态转移都调用它并传入具体实例）；
ArtifactTimeoutError携带的status_transitions历史（polling 循环把每次转移的GenerationStatus追加进列表并传入超时错误构造，L331、L383）。

此外，frozen 变体会丢弃 str-Enum 的裸字符串构造容忍：GenerationStatus(status="completed")今天合法（is_*谓词按==比较故仍工作，测试test_raw_string_constructed_predicates钉住了这一点），而 frozen 联合类型不接受——这是一个需要明示的有意行为变更。

A6 — 加法优先的迁移，带一个诚实的缺口

Phase 1（加法）：新增poll_result()/wait_result()返回变体，内部通过一个GenerationStatus → variant适配器实现，适配器对构造出的.status（即GenerationState成员）做match。再次强调：_status_from_code不是接缝（它是上游规范化器，从不发射NOT_FOUND/REMOVED）。约 13 个扁平方法继续返回GenerationStatus。
Gap（kickoff 没有廉价的加法对）：12 个快照 kickoff 方法（generate_*、revise_slide、retry_failed）各自加*_result()需要新增 12 个方法。选项 (a) 提供公开的GenerationStatus.as_poll_result()转换器供调用方选用；(b) 接受"kickoff 返回翻转只发生在 Phase 3 破坏性变更"。ADR 选择 (a) 作为更便宜的桥梁。
Phase 2（跑道）：按 ADR-0018 的真实契约弃用扁平返回方法；迁移 CLI / services / docs，以及15 个测试文件中 105 处GenerationStatus(...)构造点。
Phase 3（单一破坏性翻转，在大版本）：移除 / 重标注扁平路径并翻转 kickoff 返回值。原地重标注会被 scripts/audit_public_api_compat.py 标记为changed-return，所以只可能发生在该阶段。

五、决策 B：推迟（且被强化）

采纳 A1–A6 作为"设计档案"（design of record），但现在不构建。理由链条比 v1 更强：

承重重载已移除（#1342）；
str-Enum + 测试强制分区已经捕获了"可廉价兑现的价值"；
头号卖点（按变体的必需字段）在真实数据面前大体不可实现（A2）——因此现在做破坏性全拆分，相比非破坏性的子类型细化只多买到"角色分离 + 穷尽 match + 结构化 failure_reason"。

这个边际收益不足以支撑一个跨 13 个方法、CLI、回调/异常、105 处测试构造点的多阶段改造，尤其是在 v0.8.0 刚发布之后。若触发器触发，应先重新评估子类型细化方案（Alternatives）——只有在更轻的路径被否决后，A1–A6 才是规格。

重新评估触发器（满足任一即构建）

(a) 扁平形态引发具体的、反复出现的 bug；
(b) 已开启的 planned major / 版本跑道窗口；
(c) 出现需要按变体字段的新功能；
(d) 研究侧收敛——ResearchStatus已经是str, Enum且含NOT_FOUND，一个共享的密封结果模式可以只建一次、在两个生命周期（artifact 与 research）中摊销（项目看重"模式与其门槛一起构建一次"，而非按命名空间反复重新决策）。

六、范围与后果

In：类型形态、角色拆分、超时 /failure_reason/ 兼容性决策、迁移序列。Out：异常模型、GenerationState枚举（#1447 已完成）、Source/Research状态类型，以及——在决策 B 下——实现本身。

后果分两种情形：

推迟（推荐）：零新增代码；设计被记录在案，既不会被反复重提，也不会被意外欠债；取代 ADR-0019 的"Tier 3 推迟"条款；#1447 打下的地基让未来 Phase 1 保持廉价。
若构建：获得穷尽式match、角色区分的 poll/wait 类型、收敛进单一分类器的failure_reason；不获得"非法状态不可表示"（字段仍可选，A2）。代价是：跑道期双表面并存、CLI/services/回调/异常/105 处测试构造点迁移、丢失裸字符串构造、以及大版本上的一次破坏性翻转。

七、备选方案对比

方案	结论	理由
Status quo（现状，扁平`GenerationStatus`）	推荐的静息状态	作为推迟基线被接受
子类型细化（`Completed(GenerationStatus)`…）	触发时更强的候选	非破坏性、覆盖全部 13 个方法（标注仍为`-> GenerationStatus`）、获得`isinstance`/`match`与变体方法。既然 A2 已证明必需字段无论如何不可实现，它就在无跑道、无破坏性翻转的前提下交付了可兑现的收益（角色判别、`match`）。其相对独立联合的唯一损失（真正不可变 + 必需字段）恰是数据上不成立的部分
原地重标注方法	拒绝	`changed-return`破坏、无跑道
`TimedOut`/`RateLimited`作为变体	拒绝	超时是异常性的（A3）；限流是失败细节（A4）

八、如何继续深入：源码阅读路线图

若想验证本文全部论断，可按以下路径阅读当前仓库：

类型层：src/notebooklm/_types/artifacts.py——GenerationState枚举（L483）、_status_from_code（L596）、GenerationStatus与全部is_*谓词（L621）；
轮询 / 等待层：src/notebooklm/_artifact/polling.py——poll_status的NOT_FOUND构造、wait_for_completion的退避重试、removed判定与超时错误组装；
测试强制分区：tests/unit/test_generation_state.py——test_poll_status_never_returns_removed、test_status_from_code_never_returns_wait_only_states、test_is_terminal_partitions_the_enum_exactly等；
兼容性现场：src/notebooklm/_app/generate_retry.py——isinstance(result, GenerationStatus)的名义检查与hasattr(status, "is_complete")的鸭子类型并存，正是 A5 所述迁移工作的真实样本；
异常模型：src/notebooklm/exceptions.py 中的ArtifactTimeoutError层级，以及 src/notebooklm/_app/errors.py 对超时异常的分类映射；
前序决策：ADR-0019 错误与返回契约（Tier 3 条款即被本 ADR 取代）与 ADR-0018 弃用策略（Phase 2 跑道的契约依据）。

这套"现状收益已被廉价兑现 + 头号收益在数据面前不可实现 + 触发条件明确 + 更轻方案优先"的推理结构，不仅是 NotebookLM 工件生成链路的设计注记，也为其他把"状态机 + 异步轮询"暴露为公共 API 的库提供了一个可复用的类型演进决策模板。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

notebooklm-py 工件生成结果的密封类型设计：GenerationStatus 角色分区、迁移路径与推迟决策（ADR-0020 深度解析）