notebooklm-py 工件生成結果的密封類型設計GenerationStatus 角色分區、遷移路徑與推遲決策ADR-0020 深度解析【免費下載鏈接】notebooklm-pyUnofficial Python API and agentic skill for Google Gemini Notebook. Full programmatic access to NotebookLMs features—including capabilities the web UI doesnt 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.pydataclass 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 / unknowngenerate_*系列 ×10、revise_slide、retry_failed、poll_statusTerminal終態completed / failed / removedwait_for_completion兩個角色之間的狀態分區是嚴格的not_found只由輪詢側產出、removed只由等待側產出wait_for_completion在超時場景下拋出ArtifactTimeoutError而非返回一個TimedOut變體。關鍵點是這條分區目前只靠生產者約定成立并由測試強制而不是由類型強制——這就是本 ADR 的出發點。從源碼看kicokoff啟動類方法不接收wait標志因此它們的返回角色是穩定的這也是設計討論得以成立的前提。二、現狀盤點枚舉、規范化器與測試強制分區在 ADR 提出之時基線mainat #1447f0d2d1be, v0.8.0GenerationStatus.status已經完成從裸字符串到枚舉的升級#1447本 ADR 之外已完成的工作GenerationState(str, Enum)是當前倉庫的真實實現poll 集合PENDING、IN_PROGRESS、COMPLETED、FAILED、NOT_FOUND、UNKNOWN罕見后端狀態SUGGESTED當前無生產者被ArtifactListingService.list_raw的服務器端過濾無條件排除建模屬防御性深度、PENDING_REVIEW語義未確認保留可檢索性wait-onlyREMOVED——由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 狀態碼映射為GenerationStateNone默認映射到PENDING未識別碼落到UNKNOWN永遠不會發射NOT_FOUND/REMOVED——這兩個狀態是在 src/notebooklm/_artifact/polling.py 中直接構造的poll_status在工件 ID 缺席于列表時返回GenerationStatus(task_idtask_id, statusGenerationState.NOT_FOUND)L150wait_for_completion的輪詢循環在consecutive_not_found連續缺失滿足雙閾值 max_not_found且耗時 min_not_found_window或連續次數 max_not_found * 2的窗口無關觸發后構造攜帶REMOVED與說明性錯誤文本的GenerationStatusL441-L453。分區被測試釘死。tests/unit/test_generation_state.py中的test_poll_status_never_returns_removed逐碼驗證poll_status的每一種輸入都不可能返回removedtest_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–A6ADR 將如果構建長什么樣完整規格化共六條。A1 — 兩種角色類型PollResultPending | InProgress | Completed | Failed | NotFound | Unknown快照方法用WaitOutcomeCompleted | Failed | Removed等待器用。分區被編碼進類型本身這是相對現狀的核心增益之一。A2 — 獨立 frozen 變體而非GenerationStatus子類理由frozen 變體無法繼承非 frozen 的GenerationStatus可變的子類也無法讓狀態不可變。字段排序問題可以用kw_onlyTrue規避但不可變性無法規避。但 A2 附帶一個縮小收益的冷水警告頭號賣點——每個變體的必需字段——在當前數據面前大體無法實現Completed.url對非媒體工件合法地為NoneArtifactRow.is_media_ready對非媒體類型恒真kickoff 即完成_parse_generation_result位于_artifacts.py時同樣為NoneFailed.error有時為Nonepoll_status在 src/notebooklm/_artifact/polling.py 中的構造只填充url與metadata不填errorRemoved攜帶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: FailureReasonRATE_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 暴露.statusis_*讓謂詞型消費者可以漸進遷移_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_failedL387match/.status調用方。但它不保留名義類型檢查nominal checks以下引用具體類型的點都是明確的遷移工作generate_retry.py中的isinstance(result, GenerationStatus)門L105、L209CLI 層對 JSON 字段的直接鏡像wait_for_completion的on_status_change回調polling.py 每次狀態轉移都調用它并傳入具體實例ArtifactTimeoutError攜帶的status_transitions歷史polling 循環把每次轉移的GenerationStatus追加進列表并傳入超時錯誤構造L331、L383。此外frozen 變體會丟棄 str-Enum 的裸字符串構造容忍GenerationStatus(statuscompleted)今天合法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。Gapkickoff 沒有廉價的加法對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 更強承重重載已移除#1342str-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_codeL596、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 的庫提供了一個可復用的類型演進決策模板。【免費下載鏈接】notebooklm-pyUnofficial Python API and agentic skill for Google Gemini Notebook. Full programmatic access to NotebookLMs features—including capabilities the web UI doesnt expose—via Python, CLI, and AI agents like Claude Code, Codex, and OpenClaw.項目地址: https://gitcode.com/GitHub_Trending/no/notebooklm-py創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考 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 NotebookLMs features—including capabilities the web UI doesnt 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.pydataclass 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 / unknowngenerate_*系列 ×10、revise_slide、retry_failed、poll_statusTerminal終態completed / failed / removedwait_for_completion兩個角色之間的狀態分區是嚴格的not_found只由輪詢側產出、removed只由等待側產出wait_for_completion在超時場景下拋出ArtifactTimeoutError而非返回一個TimedOut變體。關鍵點是這條分區目前只靠生產者約定成立并由測試強制而不是由類型強制——這就是本 ADR 的出發點。從源碼看kicokoff啟動類方法不接收wait標志因此它們的返回角色是穩定的這也是設計討論得以成立的前提。二、現狀盤點枚舉、規范化器與測試強制分區在 ADR 提出之時基線mainat #1447f0d2d1be, v0.8.0GenerationStatus.status已經完成從裸字符串到枚舉的升級#1447本 ADR 之外已完成的工作GenerationState(str, Enum)是當前倉庫的真實實現poll 集合PENDING、IN_PROGRESS、COMPLETED、FAILED、NOT_FOUND、UNKNOWN罕見后端狀態SUGGESTED當前無生產者被ArtifactListingService.list_raw的服務器端過濾無條件排除建模屬防御性深度、PENDING_REVIEW語義未確認保留可檢索性wait-onlyREMOVED——由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 狀態碼映射為GenerationStateNone默認映射到PENDING未識別碼落到UNKNOWN永遠不會發射NOT_FOUND/REMOVED——這兩個狀態是在 src/notebooklm/_artifact/polling.py 中直接構造的poll_status在工件 ID 缺席于列表時返回GenerationStatus(task_idtask_id, statusGenerationState.NOT_FOUND)L150wait_for_completion的輪詢循環在consecutive_not_found連續缺失滿足雙閾值 max_not_found且耗時 min_not_found_window或連續次數 max_not_found * 2的窗口無關觸發后構造攜帶REMOVED與說明性錯誤文本的GenerationStatusL441-L453。分區被測試釘死。tests/unit/test_generation_state.py中的test_poll_status_never_returns_removed逐碼驗證poll_status的每一種輸入都不可能返回removedtest_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–A6ADR 將如果構建長什么樣完整規格化共六條。A1 — 兩種角色類型PollResultPending | InProgress | Completed | Failed | NotFound | Unknown快照方法用WaitOutcomeCompleted | Failed | Removed等待器用。分區被編碼進類型本身這是相對現狀的核心增益之一。A2 — 獨立 frozen 變體而非GenerationStatus子類理由frozen 變體無法繼承非 frozen 的GenerationStatus可變的子類也無法讓狀態不可變。字段排序問題可以用kw_onlyTrue規避但不可變性無法規避。但 A2 附帶一個縮小收益的冷水警告頭號賣點——每個變體的必需字段——在當前數據面前大體無法實現Completed.url對非媒體工件合法地為NoneArtifactRow.is_media_ready對非媒體類型恒真kickoff 即完成_parse_generation_result位于_artifacts.py時同樣為NoneFailed.error有時為Nonepoll_status在 src/notebooklm/_artifact/polling.py 中的構造只填充url與metadata不填errorRemoved攜帶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: FailureReasonRATE_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 暴露.statusis_*讓謂詞型消費者可以漸進遷移_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_failedL387match/.status調用方。但它不保留名義類型檢查nominal checks以下引用具體類型的點都是明確的遷移工作generate_retry.py中的isinstance(result, GenerationStatus)門L105、L209CLI 層對 JSON 字段的直接鏡像wait_for_completion的on_status_change回調polling.py 每次狀態轉移都調用它并傳入具體實例ArtifactTimeoutError攜帶的status_transitions歷史polling 循環把每次轉移的GenerationStatus追加進列表并傳入超時錯誤構造L331、L383。此外frozen 變體會丟棄 str-Enum 的裸字符串構造容忍GenerationStatus(statuscompleted)今天合法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。Gapkickoff 沒有廉價的加法對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 更強承重重載已移除#1342str-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_codeL596、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 的庫提供了一個可復用的類型演進決策模板。【免費下載鏈接】notebooklm-pyUnofficial Python API and agentic skill for Google Gemini Notebook. Full programmatic access to NotebookLMs features—including capabilities the web UI doesnt expose—via Python, CLI, and AI agents like Claude Code, Codex, and OpenClaw.項目地址: https://gitcode.com/GitHub_Trending/no/notebooklm-py創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考