> ## Content Index
> Fetch the complete content index at: https://growthhackers.tw/llms.txt
> Use this file to discover other available public pages before exploring further.

# UCP 藏了一個「找門市」的能力：連暗黑廚房要不要曝光，都寫進規格裡了
- URL: https://growthhackers.tw/blog/ucp-location-capability-decode/
- Published: 2026-08-29T13:00:00.000Z
- Updated: 2026-08-29T13:00:00.000Z
- Description: 我上一篇被問「內容真的夠完整了嗎」，回去查才發現 UCP 藏了一個完全沒被提過的能力：Location Capability，讓 agent 查門市、查外送範圍，連暗黑廚房要不要曝光都寫進規格裡。
- Author: Lewis wang
- Tags: Universal Commerce Protocol, agentic commerce, Shopify, AI Agent, 電商趨勢

我上一篇（[UCP 治理名單攤開來看](https://growthhackers.tw/blog/ucp-dev-protocol-governance-decode/)）寫完，被問了一句：「內容真的夠完整了嗎？」

不是我說，這句話問得很準。我回去把 ucp.dev 左側那份完整導覽點開才發現，Specification 底下有一整棵樹我完全沒探過，裡面藏著一個叫 Location Capability（地點能力）的東西，跟前兩篇寫的搜尋、結帳、治理都不一樣，是專門處理「找門市」這件事的。

這篇就是把這個能力拆給你看，順便回答那句問題：內容永遠可以更完整，重點是你有沒有回去再查一次。

## 這個能力在解決什麼問題

Location Capability 官方定位很直白：讓 AI agent 發現、搜尋、查詢商家的實體地點，包括零售門市、餐廳分店，甚至置物櫃（brand locker）。它是「跨產業通用」的，不綁定電商，餐飲、服務業一樣能用。

官方點名兩個核心情境：

**本地取貨探索（Local Pickup Discovery）**：找附近支援取貨的門市或餐廳分店，查它們的營業時間，查你選的商品目前在哪幾家門市有貨。

**履約範圍驗證（Fulfillment Area Verification）**：查一個特定地點，例如水電行、餐廳、在地服務商，能不能服務某個買家的地址。

想像一下，你開一家連鎖餐飲品牌，客人在 AI 助理裡問「這附近哪一家分店可以外帶，而且今天晚上八點還開著」，或者問「我家在內湖，你們外送範圍到得了嗎」，這兩個問題背後，就是這個 Location Capability 在跑。

以前這種功能，每一家品牌要嘛自己刻一個門市地圖頁面，要嘛跟外送平台各簽各的合約、各接各的 API。現在如果雙方都支援 UCP，這件事變成一套共用的問法。

![官方文件截圖：Location Capability 的兩個能力（search / lookup）與兩大商業情境](https://growthhackers.tw/content/images/2026/08/inline-location-overview-v1.png)

官方文件截圖：Location Capability 的兩個能力（search / lookup）與兩大商業情境

## 兩個問法，一個藏了商業機密的巧思

Location Capability 定義了兩種空間關係，這裡我要特別點出來，因為設計得比我原本想的細。

**distance**：給一個中心點加一個半徑，找範圍內的地點，這是標準的「附近搜尋」，沒什麼特別。

**serves**：問「這個地點能不能服務這一個明確指定的地址」，商家對這個答案有最終解釋權，而且官方寫明白：**UCP 刻意不去建模、也不曝露商家實際的服務範圍長什麼形狀**，一個地點的座標不會自動帶出一圈服務半徑。

你知道為什麼要這樣設計嗎？因為外送/服務範圍地圖，對很多商家來說是營運機密，範圍怎麼畫、哪些巷子送得到哪些送不到，牽涉到人力調度跟成本結構，不是每家都想公開一張完整地圖給所有 AI agent 抓取。`serves` 這個設計讓商家可以只回答「這一個地址，送或不送」，不用把整套服務範圍邏輯攤開來給你看。

這就像從只能公開一整份客戶名單，進化到別人問「某某人在不在名單上」，你只回答在或不在，不用把整份名單交出去。

## 探索階段講的話不算數，這是刻意的

我查資料時發現一個很清楚的設計原則，官方把它叫做 Discovery Phase（探索階段）跟 Checkout Phase（結帳階段）的區分。

探索階段查到的營業時間、商品庫存、設施資訊，官方原文寫「provisional」，暫時性的，不是有約束力的承諾。真正算數的條款，要等到後面的階段重新協商、重新驗證，探索訊號不應該被快取或者跨 session 拿來重複用而不重新確認。

具體一點講，`items` 這個篩選條件問「這個地點現在能不能提供這些商品」，回傳「可以」也只是一個粗略、暫時性的斷言，不是幫你留貨，更不是預約。

重點是什麼？ 這套設計把「查詢」跟「承諾」徹底切開，探索階段就是讓你快速篩選出候選名單，真正要算數的，永遠是最後下單那一刻重新問一次。

## 營業時間這種小事，做得意外講究

我本來以為營業時間欄位頂多就是「星期幾、幾點到幾點」，結果官方連日光節約時間的邊界案例都處理了。

固定排程之外還有 `exception_hours`（例外時段，處理國定假日或臨時公休），時區一律用 IANA 時區資料庫識別碼，不能因為查詢的人在哪個時區就換算基準。

最讓我意外的是這句：日光節約時間往前跳的那段「消失的時間」不對應任何實際時刻；往後跳、時間重複發生的那一小時，兩次的排班判定結果會是一樣的，而且目前的資料結構沒辦法區分是兩次裡的哪一次。

會寫到這麼細，通常代表寫規格的人真的被線上線下營業時間對不上這件事坑過。

我自己輔導過的品牌客戶裡，就有不只一次遇到「官網寫的營業時間跟門市實際公休日對不上」的狀況，客人照著網站資訊到店撲空，抱怨都算到行銷頭上。這種事聽起來很小，發生在你自己生意上的時候一點都不小。

## 全篇我覺得最有意思的一段：安全與隱私考量

Location Capability 這頁最後列了五條安全與隱私規則，每一條讀起來都像是「這群人真的做過零售或外送系統，踩過坑」。

**預設只給粗略位置**：Platform 預設應該傳粗略的位置提示，例如郵遞區號或者四捨五入過的座標，只有買家明確同意或選定了特定地點，才傳送精確座標。

**防止庫存試探**：商家應該對帶商品篩選條件的查詢做流量限制，避免有心人拿這個功能大量試探、把整個庫存分布摸個透。

**私有/暗店必須過濾**：商家**必須**把內部限定、買家不能造訪的地點濾掉，官方原文點名了「dark kitchen」，也就是暗黑廚房，這種只做外送不接待客人的據點，不能被查到並曝光給消費者。

**地址資料要驗證完整性**：雖然查地點是唯讀操作，但如果地址在傳輸過程被竄改，比如中間人攻擊，會造成實體安全風險，買家可能被導去一個錯誤的地址取貨。Platform 應該在呈現地點資料給買家之前，先驗證簽章。

**位置紀錄不能亂留**：商家不得在請求結束後保留精確的位置輸入，除非買家明確同意；伺服器日誌應該把座標截斷到大概一公里精度，防止意外存下買家的精確行蹤史。

不是我說，光是「暗黑廚房不能曝光」跟「地址被竄改會造成實體安全風險」這兩條，就已經不是一般 API 文件會寫的東西，這是真的懂零售跟外送這行的人才會想到要防的坑。

![官方文件截圖：Security & Privacy Considerations，連暗黑廚房不能曝光都寫進規則裡](https://growthhackers.tw/content/images/2026/08/inline-location-security-v1.png)

官方文件截圖：Security & Privacy Considerations，連暗黑廚房不能曝光都寫進規則裡

## 這件事對你來說，該做什麼？

如果你是零售或餐飲品牌：

► 盤點你現有的門市/分店資料，特別是營業時間跟取貨/外送服務範圍，這些資料未來可能要用結構化的方式對 AI agent 開放，現在資料越亂，以後要接的時候越痛苦。

► 如果你有暗黑廚房、純物流據點這類「不對客人開放」的場所，先想清楚哪些地點屬於可曝光、哪些不行，這條線現在就該畫好，不要等真的接了協定才發現漏洞。

如果你是做技術、做產品的人：

► 去讀 [ucp.dev 的 Location Capability 完整規格](https://ucp.dev/latest/specification/common/location/?ref=growthhackers.tw)，`distance` 跟 `serves` 這兩種空間關係的切分方式，值得直接參考到你自己設計的地點查詢 API 裡。

► 探索階段跟交易階段訊號分離、不信任快取這套原則，不是只有地點查詢能用，任何牽涉「先查再確認」流程的系統設計，都可以借用這個思路。

## 收尾：完整這件事，沒有終點

這已經是我這幾天寫的第三篇 UCP。第一篇測介面，第二篇讀治理，這篇挖到一個完全沒被提過的能力。

如果你問我，內容到底要挖到多完整才算數？老實說沒有標準答案。Specification 底下還有 Cart、Catalog、Order 這些能力的規格，還有 Payment Handlers、Signatures，我都還沒讀完。

這年頭就是查證、查證、再查證，你永遠可以說「我還可以再挖深一點」，但總要在某個點上，先把已經查到的東西寫出來，讓讀者先看到，而不是等到自認為「絕對完整」才動筆，那一天可能永遠不會來。

---

**協作聲明與免責**

這篇文章由王董與 AI 一起整理製作完成。文中引用的第三方資料、研究或工具都會標註來源名稱；若原始出處有公開連結，會以 `[來源名稱](URL)` 形式附上，方便你進一步查找。若文中內容與原始出處有任何出入，請以原文為準。

內容僅供參考與學習交流，不構成任何專業、商業或投資建議，請依自身情況判斷並自行承擔行動風險。文中提及的工具功能、數據與平台政策可能隨時間異動，請以各官方最新公告為準。