Third-party API change monitoring

不再等 API 壞掉,
才發現版本已經改了

把三個外部服務的被動人工查看,重整為有來源、有 owner、有時限的唯讀監測;確定性軟體找差異,AI 解讀語言,人類承擔升級決策。

Proposed · 通用合成案例,尚未連接真實供應商
作業問題人工偶爾查看,涵蓋與責任都不清楚
第一切片唯讀 deterministic shadow
AI 邊界只做有引用、可拒絕的語言解讀
禁止事項不自動改 code、升版或改供應商設定

01 — 改善的是決策鏈,不只是多一個通知 bot

預期結果是:每個可能影響串接的變更,都能在合理時間內被發現、連回實際使用點、交給明確的人決定,並保留來源與處置證據。

白話比喻(大樓門禁改密碼): 就像社區大樓換了新的門禁密碼,如果沒人主動通知快遞員,所有住戶的包裹都會卡在大門口送不進來。公司串接了第三方金流或地圖服務,如果對方悄悄改版而我們不知道,等線上刷卡或地圖壞掉才搶修,往往已經造成巨大的營收損失。
第一階段決策:只做唯讀決策支援。量測偵測延遲、相關變更召回率與無關通知負擔;baseline 與 target 由真正的 owner 實測後接受。

02 — 現況的四種失效路徑

以下是待企業證據驗證的參考假說,不是對任何真實團隊的既成事實。

正常

每個人各自追文件

重複查看 release notes、文件頁與 email,卻不知道三個服務是否都被涵蓋。

例外

公告沒有直接說影響

工程師重新讀公告、搜 code、問原作者,才能判斷 endpoint、SDK 或 auth 是否受影響。

升級

發現後才臨時找 owner

breaking change 或 deprecation 已出現,但責任、review-by time 與排期不清楚。

Rework

判讀沒有可重播證據

缺少內容 hash、當時的使用清冊 revision,以及接受或拒絕理由。

03 — 先修作業,再加入技術

先做
  1. 移除多人重複查看同一來源。
  2. 每個供應商建立一份 owner 接受的來源登錄。
  3. 標準化 API、版本、使用點與處置語義。
  4. 重新分配監測、影響判斷與升級責任。
先不要做
  • 不讓 AI 猜沒有來源的變更。
  • 不把 AI 摘要當唯一證據。
  • 不自動建立升級工作。
  • 不自動修改 dependency、code 或 vendor configuration。
01 · REGISTER

登錄來源

官方 changelog、deprecation、OpenAPI、schema 與 SDK source。

02 · DETECT

確定性比較

保存時間、版本與 hash;比較 endpoint、欄位與棄用日期。

03 · INTERPRET

條件式 AI

需要語言解讀時,產生有引用、標示不確定性的影響候選。

04 · GOVERN

人類審查

指派 owner 與 review-by;逾期升級 fallback owner,直到有證據結案。

04 — 穩定規則交給軟體,語言負擔才考慮 AI

確定性軟體

排程、擷取、hash、版本比較、OpenAPI/schema diff、棄用日期、freshness 與 fail-closed。

條件式 AI · Shadow

摘要散文公告、合併文件、對照核准的使用點 view;必須引用、呈現不確定性,證據不足時 abstain。

可歸責的人類

maintainer 判斷相關性;integration owner 決定升級;data owner 核准模型輸入欄位與遮罩。

資料治理:每次模型請求記錄 input-scope access decision。憑證、secret、原始 auth material、未核准 code 與 metadata 不得進入模型。

05 — 四週最小落地切片

第 0 週

指定 integration owner 與 data owner;確認三個服務、官方來源、內部使用清冊 revision、人工 baseline,以及欄位層級的模型輸入與遮罩政策。

第 1–2 週

啟動唯讀 deterministic shadow;產生 raw diff 與 change record,設定 owner、review-by time 與逾期 escalation,不做任何寫回。

第 3–4 週

對同一批 records 比較 deterministic-only 與 AI-assisted,量測召回、誤報、審查時間與引用正確性。

Promotion gate

owner 接受 source coverage、inventory、notification threshold、fallback owner 與 shadow evidence 後,才能規劃下一階段。

06 — 現在能說到哪裡?

主張狀態限制
串接三個服務,靠被動人工方式檢查proposed來自案例需求;不能宣稱實際工時或漏報率。
官方來源、抓取條款與完整性missing確認前不得啟用真實來源擷取。
內部使用點、owner 與模型資料範圍missing不得宣稱影響判讀完整或資料可送入模型。
AI 比 non-AI baseline 更有價值unverifiableAI selection 維持 conditional,需先做 shadow A/B。
自動升級或寫回權限out of scope第一切片嚴格唯讀;另案才可評估。

07 — 提案完成後,交給開發 agent

FDE project-work skill 負責把作業問題、目標流程、AI 適配、證據限制與第一切片說清楚;它不負責撰寫監測系統。Owner 接受邊界後,由目標 repository 的開發 agent 依當地技術棧與工程規範完成實作。

交付給 agent

可執行契約

提供 source、diff、inventory、AI shadow、review policy 的模組邊界,以及輸出 contract。

Agent 自行確認

Repository 事實

先讀適用的 AGENTS.md、依賴、測試與執行命令;提案不猜測框架或套件。

完成證據

測試與邊界

從 deterministic offline slice 開始,證明可重播、fail-closed、AI 可關閉與 writeBack false。

開發入口:開啟 AI Agent 開發交接契約。缺少真實 owner、access 或資料核准時,agent 只能使用合成 fixtures 建立離線 reference implementation。

下一個 accountable action

由 External Integration Owner 召開 60–90 分鐘工作坊,確認三個服務、官方來源、內部使用點 owner、兩週 shadow baseline 與通知閾值;同時指定 Internal Data Owner,核准模型可見欄位、遮罩政策與 input-scope access decision。完成前,本案例僅能使用合成資料演練。