台北的騎樓停機車這件事,沒寫在任何法規裡,但全島兩千三百萬人都知道能停。沒事的時候你覺得自己賺到了便利,直到某天早上回來發現車被拖走,或整條騎樓圍起來施工,前一晚沒有任何通知。
最近在做一個 AI agent 的整合,要讓它查詢某個雲端知識庫服務。找到一個第三方 CLI 工具,裝完、登入、測試,全部順利。幾百個知識來源都能查到,還附帶完整引用內容。這種「能動就是好的」的感覺很容易讓人放心往下做。
那些沒有文件的端點
這個工具的運作方式有點特別:它不走官方 API,而是讀取你瀏覽器裡的 cookie,然後呼叫那個服務的內部端點——那些從來沒有公開文件的端點。沒有參數說明,沒有版本號,沒有 changelog。你能用,是因為它剛好還活著,不是因為有人答應過你它會一直活著。
Cookie 有效期。這是第一個問題。大部分服務的 session cookie 會在七天到三十天之間過期,過期了不會有任何預警,你的整合就直接斷掉。官方 API 通常會給你 refresh token 機制,或至少在 401 回應裡明確告訴你認證失效了。非官方路徑?你只會看到一個奇怪的錯誤訊息,或者更糟——靜默失敗,回傳空結果。
內部 API 的變動週期更短。產品團隊在改前端功能時,順手調整了某個內部端點的參數結構,他們不需要通知任何人,因為這本來就不是對外承諾的介面。你的整合在某個普通的星期二早上就這樣壞了,沒有 breaking change 公告,沒有遷移指南,沒有降級方案。你甚至不知道該去哪裡問。
「約定」與「剛好可以用」的差距
官方 API 給你的是約定。文件寫明了哪些端點存在、接受什麼參數、回傳什麼格式、什麼情況下會改。這個約定不是善意,是商業責任。他們要維持向後相容,或至少提前宣告不相容的變更,因為有其他付費客戶也在用同一套 API。
非官方 API 給你的是「目前剛好可以用」。這兩件事在當下看起來一模一樣,但本質完全不同。前者是穩定性由對方維護,後者是你在借用別人內部系統的穩定性,而對方對你沒有任何維護義務。
台灣有全世界最高的便利商店密度,平均每兩千人一家,每平方公里 4.7 間,二十四小時隨時開。這種密度讓很多非正式的生活模式變得可行——深夜要列印文件、臨時要買電池、需要一個收包裹的地址。但便利商店開在那裡,不是為了替你解決這些問題,是因為它剛好能順便做。哪天政策改了、租約到了、門市調整營業項目,你依賴的那個便利就不見了。
寫進 dependency 之前該問的
整合一個工具之前,我現在會先看三件事。第一,認證機制是什麼。如果是 OAuth 或 API key,代表對方有意圖讓這個東西被外部使用。如果是要你手動複製 cookie,或是從瀏覽器 localStorage 撈 token,這通常是紅旗。
第二,有沒有版本管理。端點 URL 裡有 /v1/ 或 /api/v2/ 這種字樣,代表對方知道 API 會變,也準備好要管理這個變動。如果連版本號都沒有,你很難期待它有穩定性承諾。
第三,這個工具的維護者是誰。是官方提供的 SDK,還是某個熱心工程師的 side project。後者不是不能用,但你要知道它可能在任何時候停止更新,或者因為上游改了什麼而徹底失效。
那個 AI agent 的整合最後還是上了,但我多做了兩件事:寫了一個 healthcheck 每天早上跑一次,確認工具還活著;另外花時間去找官方 API 的申請管道,雖然功能少一點、要多寫一些轉換邏輯,但至少我知道它明年還會在。
順利跑起來的東西不代表可以信任。有時候你需要的不是更強的工具,是一個不會在某個週末突然消失的工具。
— 邱柏宇
延伸閱讀
Integration Succeeded, But the Key Isn’t Yours
Recently integrated a third-party CLI tool into an AI agent to query a cloud knowledge base service. Install, login, test — everything worked. Hundreds of knowledge sources, complete with citation content. The kind of smooth that makes you think you can move on.
But the tool doesn’t use the official API. It reads browser cookies and calls internal endpoints — the ones that never had public documentation.
Endpoints Without Promises
No parameter specs. No version numbers. No changelog. You can use it because it’s alive right now, not because anyone promised it would stay alive.
Cookie expiration is the first problem. Most session cookies expire between seven and thirty days. When they do, there’s no warning — your integration just breaks. Official APIs usually provide refresh token mechanisms, or at least return clear 401 responses when authentication fails. Unofficial routes? You get cryptic error messages, or worse: silent failures that return empty results.
Internal API changes happen faster. When a product team refactors a frontend feature, they might adjust an internal endpoint’s parameter structure. They don’t need to notify anyone because this was never a public interface. Your integration breaks on an ordinary Tuesday morning. No breaking change announcement, no migration guide, no fallback option. You don’t even know who to ask.
The Gap Between “Contract” and “Currently Works”
Official APIs give you contracts. Documentation specifies which endpoints exist, what parameters they accept, what format they return, and when things will change. This isn’t goodwill — it’s commercial obligation. They maintain backward compatibility, or at least announce breaking changes in advance, because paying customers depend on the same API.
Unofficial APIs give you “currently works.” These look identical in the moment but are fundamentally different. The former means stability is maintained by the provider. The latter means you’re borrowing someone else’s internal system stability, and they have zero obligation to maintain it for you.
Taiwan has the world’s highest convenience store density: one store per 2,000 people, 4.7 stores per square kilometer, open 24/7. This density enables many informal living patterns — printing documents at midnight, buying batteries on impulse, using a store address for package delivery. But convenience stores don’t exist to solve these problems for you. They just happen to be able to do it. When policies change, leases expire, or stores adjust their services, that convenience you relied on disappears.
What to Check Before Adding Dependencies
Before integrating a tool, I now check three things. First, the authentication mechanism. If it’s OAuth or API keys, the provider intends for external use. If you’re manually copying cookies or extracting tokens from browser localStorage, that’s usually a red flag.
Second, version management. Endpoint URLs containing /v1/ or /api/v2/ show the provider knows APIs change and is prepared to manage that change. No version numbers? Hard to expect stability commitments.
Third, who maintains the tool. Is it an official SDK or someone’s side project? The latter isn’t unusable, but you should know it might stop updating anytime or break completely when upstream changes.
That AI agent integration still went live, but I added two things: a daily healthcheck to confirm the tool still works, and I spent time finding the official API application process. Fewer features, more conversion logic, but at least I know it’ll be around next year.
Something that runs smoothly doesn’t mean it’s trustworthy. Sometimes what you need isn’t a more powerful tool, but one that won’t vanish on a random weekend.
— 邱柏宇