Capstone 整合：技術‑產品向 Demo 與「App 護照」

1. 什麼是「App 護照」，為何需要它

App 護照是一份精簡但資訊密度高的文件（通常是 1–2 頁的 Markdown，或 README 中的一個章節），讓任何人都能快速理解你的 ChatGPT App：它如何組成、有何限制、如何賺錢，以及你如何在生產環境中營運它。

這不是行銷小冊子。它不談「最創新的 AI 技術」，而是非常落地的內容：

• ChatGPT、你的 Widget、MCP 伺服器、代理與 ACP/Stripe 之間的邊界在哪裡；
• 你保存哪些 PII、OAuth/scopes 如何設計，以及秘密金鑰如何輪替；
• 你對 latency 與 availability 的 SLO 是什麼、有哪些儀表板與警報；
• 完成一次成功流程的平均成本是多少、你如何向使用者收費；
• 有哪些已記錄的典型事故、對應的 runbook 放在哪裡；
• 你打算在未來幾個月如何演進這個 App。

可以把護照想成連結與 high‑level 描述的聚合，更新頻率低於程式碼、高於「對投資人用的正式簡報」。

對作為 ChatGPT App 開發者的你來說，護照同時是成熟度檢查清單。若某個章節是空的（「我們好像沒定 SLO…」），那是一面紅旗：不只是文件缺失，實務上也沒建立起來。

2. GiftGenius 的護照基本結構

對 GiftGenius 而言，採用以下結構是合理的（你可以稍微調整以符合你的 App，但核心概念不變）。

用一個小表格來展示誰會看、為了什麼：

接下來逐一拆解上述區塊，並同步起草 GiftGenius 的實際 PASSPORT.md。

3. 架構：如何用一張圖呈現整個堆疊

架構章節是護照的核心。你不需要畫 200 個方塊的 UML 圖；重點是呈現層次與資料流：從 ChatGPT 的使用者一路到你的資料庫與支付。對使用 Apps SDK 與 MCP 的 ChatGPT App，這條路徑相當標準。

一個好用的格式，是在 PASSPORT.md 中直接放 Mermaid 圖。例如 GiftGenius：

flowchart TD
  U[User in ChatGPT] --> C[ChatGPT + GPT-5]
  C --> W[GiftGenius Widget
Next.js + Apps SDK]
  W --> MCP[MCP Server
giftgenius-mcp]
  MCP --> A[Agent: GiftPlanner]
  A --> DB[(Postgres: products,gifts)]
  A --> ACP[ACP / Stripe]
  ACP --> ORD[(Orders)]

在圖下用文字描述關鍵場景：

使用者在聊天中描述收禮人。模型決定呼叫 MCP 伺服器上的 tool suggest_gifts。代理可能另外把目錄當作資源來讀，並呼叫多個 tools。接著在選定禮物後，於 Stripe 建立 ACP 工作階段，結帳透過 webhook 進行，結果寫入資料庫。

最好同時提到技術選型：Next.js 16 + Apps SDK、MCP 伺服器採用 Node/Python、PostgreSQL、Redis 作為快取、Stripe 作為支付服務。

你也可以在架構章節旁放一小段技術片段，讓人看到「圖上的積木」如何在程式碼中落地。例如，一段把 requestId 與 userId 傳給 MCP 用戶端的 Next.js 路由：

// app/api/suggest-gifts/route.ts
import { mcpClient } from "@/lib/mcpClient";

export async function POST(req: Request) {
  const { occasion, budget } = await req.json();
  const requestId = crypto.randomUUID();      // 用於日誌追蹤
  const userId = req.headers.get("x-user-id") ?? "anonymous";

  const result = await mcpClient.callTool("suggest_gifts", {
    occasion, budget, requestId, userId,
  });

  return Response.json({ requestId, result });
}

這樣的片段能把圖上的「Widget → MCP」箭頭，和實際程式碼對上。

4. Security & Privacy：到底要固定哪些內容

護照中的安全章節，不是「我們用 HTTPS、後端是 TypeScript，所以一切 OK」。它需要對安全、合規與法務的問題給出具體答案。

對 GiftGenius，宜簡要描述：

身分驗證與授權模型：
對 commerce 情境，使用透過 MCP Auth Server 的 OAuth 2.1 + PKCE；token 綁定 user_id 與 tenant_id；所有與結帳相關的 tool 呼叫都需要 scope commerce.checkout。

哪些資料屬於 PII、你如何處理。
例如：email 與姓名屬 PII，禮物偏好屬假名化資料；日誌只記錄雜湊過的 email；不儲存寄送地址，只轉交給 Stripe 與 webhook。

保留（retention）與刪除策略：
工具日誌保留 30 天、commerce 事件保留 1 年；使用者請求時可刪除其訂單與關聯的分析事件。

你如何管理秘密金鑰：
簡述 OpenAI API key、Stripe secret、OAuth client secret 的存放位置（例如 managed secret store）、多久輪替一次、如何在 staging 測試輪替。

護照中可以放一小段技術導向的片段，展現「最小必要權限」的原則。

// config/scopes.ts
export const TOOL_SCOPES = {
  suggest_gifts: ["read:products"],
  get_gift_details: ["read:products"],
  create_checkout_session: ["read:products", "write:orders", "stripe:checkout"],
} as const;

然後在工具與 MCP‑auth 的描述中引用同一組 scopes。這就不只是口號「least privilege」，而是具體契約。

5. Observability 與 SLO：看見 App 的運行情況

下一個區塊談可觀測性：你如何知道 App 是健康的。這裡涵蓋結構化日誌、指標、SLO 與儀表板連結。

對 GiftGenius，合理的描述包含：

關鍵 SLO。
例如：MCP 可用性 ≥ 99.5%、suggest_gifts 的 p95 延遲 < 5 秒、checkout 成功率 ≥ 99%。

在哪裡查看這些 SLO。
Grafana/Datadog/… 的儀表板名稱與 URL（在護照中可寫「Dashboard: GiftGenius / SLO」）。

結構化日誌的格式。
在前一個可觀測性模組中，你已設計了欄位 request_id、tool_name、user_id/tenant_id、 tokens_in/tokens_out、cost_estimate、duration_ms、error_code。 在護照中最好附一個小 JSON 範例；更棒的是——直接給出在程式中使用的 TypeScript 型別。

// lib/logging.ts
export type ToolInvocationLog = {
  level: "info" | "error";
  timestamp: string;
  requestId: string;
  userId?: string;
  toolName: string;
  tokensIn?: number;
  tokensOut?: number;
  costEstimateUsd?: number;
};

以及一個 helper 函式：

export function logToolInvocation(event: ToolInvocationLog) {
  console.log(JSON.stringify({ type: "tool_invocation", ...event }));
}

於是這個型別成為程式與護照之間的橋樑：在 Observability 章節中你寫明所有 tool 呼叫都以 ToolInvocationLog 格式記錄，並附上彙總這些紀錄的儀表板連結。

也可以加上一段簡短的文字流程：

事件日誌 → 日誌儲存 → SLO 儀表板 → 警報 → 事故／Runbook。

6. Economics & Product Metrics：金流與使用者行為

此處把前一個「經濟性」（第 19 模組，M19）中的內容接起來：成本指標、定價與產品分析。

在 GiftGenius 的護照中，應固定下列內容：

關鍵場景的單位經濟（例如「一次完整任務」的經濟模型）。
例如：「平均 cost_per_successful_task（完成禮物挑選且成功付款）＝ $0.13（LLM + 基礎設施）。平均每次任務的收入＝ $0.80（合作夥伴的 CPA）。」

主要營利模式。
簡述：「提供免費的基本挑選（不一定購買），透過導流到合作商店的 CPA 變現，外加可選的付費進階訂閱（更多篩選與禮物歷史）。」

關鍵產品指標。
例如：activation‑rate＝至少完成一次 workflow_completed 的使用者占比；repeat‑rate＝月內回訪至少一次的使用者占比；workflow_completed → checkout_success 的轉換率。

實驗。
活躍的 A/B 清單：「模型 A（昂貴） vs 模型 B（便宜）」、「長流程嚮導 vs 快速 inline」。對每個實驗，保存 experiment_id、變體、目標指標（轉換、cost_per_task、quality‑score）。

也可以在程式裡體現這些，避免護照流於理論，例如提供統一的分析事件 helper：

// lib/analytics.ts
export function trackEvent(
  name: string,
  payload: Record<string, unknown>,
) {
  console.log(JSON.stringify({
    type: "analytics",
    name,
    ts: new Date().toISOString(),
    ...payload,
  }));
}

並在 workflow 成功時呼叫：

trackEvent("workflow_completed", {
  userId,
  requestId,
  experimentId: "model_ab_01",
  variant: "A",
  costUsd: 0.13,
  checkoutSuccess: true,
});

在護照中，描述哪些事件是關鍵、有哪些 KPI 綁定其上。程式碼證明你真的在量測，而不是口頭承諾。

但只有當 App 穩定在生產環境運作時，指標與經濟才有意義。因此下一章我們會固定 GiftGenius 在營運上的面向：事故、on‑call 與 runbook。

7. Ops & Incidents：你將如何在生產環境與 App 共存

本章節談「當事情不順利時你如何應對」。

對 GiftGenius，護照中至少應列出兩種典型事故：

付款問題。
例如：checkout 成功率低於 SLO、大量 Stripe webhook 錯誤。在護照中寫明已有名為「Checkout Failures」的 runbook，描述症狀、查看位置（錯誤儀表板、webhook 端點日誌）、快速緩解步驟（臨時措施：關閉有問題的 feature flag、把部分流量導到 sandbox 或暫時只提供禮品卡），以及後續（post‑mortem、新增警報）。

MCP/LLM 問題。
例如：suggest_gifts 的 p95 延遲升到 9 秒，或大量請求出現「Error talking to app」。對此有另一份 runbook：檢查 OpenAI、tunnel/Vercel 狀態，MCP 健康檢查，切換到降級模式（代理在無法存取目錄時，改用模型的一般知識提供建議、關閉 commerce）。

此處也簡述營運的例行節奏：多久重審一次 SLO、做成本檢視、檢查安全日誌、輪替秘密金鑰。

同時標示 on‑call 角色（即便只有你一人），以及警報會送到哪個 Slack 頻道或信箱。

8. Roadmap & Risks：誠實面向未來

最後一個區塊談未來。無須長篇大論，3–5 個實際的 App 演進步驟，加上幾個已知限制即可。

對 GiftGenius，可能如下：

• 啟用 LLM 評估（LLM‑evals）來衡量推薦品質，讓品質與轉換掛鉤；
• 新增另一個在地語系，並測試工具描述的在地化；
• 在部分流量上試驗較便宜的模型；
• 提升對 Stripe 故障的韌性（更可靠地處理 webhook 與延遲確認）；
• 準備升級到新版 Apps SDK 或 MCP（工具契約版本化）。

限制： API 配額、ChatGPT UI 限制（例如結果卡片數量上限）、當前架構的薄弱之處（單區域資料庫、沒有 MCP 熱備等）。

實驗計畫：你要驗證的 pricing/UX/模型假設，以及將依哪些指標來做決策。

9. 護照該放哪，如何更新

實務上最方便的格式是把 PASSPORT.md 放在 GiftGenius 儲存庫根目錄或 docs/ 目錄內，並在你的文件系統（Confluence、Notion 等）放副本或連結。

它應該足夠精簡，10–15 分鐘內可讀完；同時資訊密度要夠，能據此回答：

• 「這個 App 到底是什麼、怎麼組成的？」
• 「如果 X 掛了會怎樣？」
• 「一位使用者讓我們花多少成本？」
• 「眼下我們最擔心的風險是什麼？」

在下列情況應更新護照：

• 架構邊界變動（新增服務、新的支付、遷移到不同技術棧）；
• 關鍵 SLO 或安全政策變更（例如不同的 retention）；
• 營利模式調整；
• 重大事故與對應 post‑mortem 的結論。

細微的程式碼變動不必立刻改護照，否則它會變成另一份過時文件。

本質上，護照是你對 App 所知的一切的濃縮。下一步，就是學會以此為基礎，向技術與商務兩類真人好好地講述產品。

10. 技術‑產品向 Demo：為什麼需要兩種「敘事版本」

當你展示 GiftGenius，幾乎總是面對兩種受眾（有時混在同一間房）：

• 技術人員（CTO、架構師、security、研發主管）；
• 產品／商務受眾（CEO、投資人、PM、行銷）。

對技術人來說重要的是：

• 架構清楚、層次分明、擴充點到位；
• 可靠性與可觀測性已設計：日誌、追蹤、SLO、警報；
• 有韌性故事：OpenAI、MCP、Stripe 掛了會怎樣；
• 你如何規劃演進（升級 SDK/MCP/模型）。

對商務方更重要的是：

• 使用者的痛點是什麼（例如「找禮物要花 40 分鐘」）；
• GiftGenius 如何在 ChatGPT 中用幾分鐘解決這個痛點；
• 你的變現方式、單位經濟與成長指標；
• 是否能降低獲客成本、提升轉換／營收。

因此應把它想成同一個 Demo 故事的兩個「層次」：對雙方都展示成熟產品的跡象，但著重點不同。

11. GiftGenius 的技術向 Demo 劇本（5–7 分鐘）

假設你面對技術受眾介紹 GiftGenius。

先給極短的背景。
大約 30 秒：「GiftGenius 是一個用於挑選禮物的 ChatGPT App，支援 ACP 結帳。我們運行在 ChatGPT 內，使用 Apps SDK、MCP 與規劃步驟的代理。」

接著是架構投影片／護照片段。
打開與我們在 Mermaid 中類似的圖，說明 ChatGPT（LLM 部分）、你的 Widget、MCP 與 Stripe commerce 層的責任邊界。此處最好指出：所有 tools 都封裝在 MCP 內，Widget 是薄 UI。

Live Demo 加日誌。
開啟分割畫面：左邊是 ChatGPT + GiftGenius，右邊是日誌或 MCP Inspector。發一個自然的請求，例如「幫我找 50 美元以內、送給電玩迷的禮物」。在執行過程中展示：

• 帶有 request_id 的 suggest_gifts tool 呼叫；
• 結構化日誌 tool_invocation，可見 tokens、cost_estimate 與 duration_ms；
• 建立 ACP 工作階段並創建訂單的第二個 tool。

若能立刻切到儀表板更好：「這是過去 24 小時此場景的 p95 延遲，這是 checkout 成功率。」這一刻，技術受眾會感受到這不是玩具，而是具有可觀測性的系統。

故障注入（可選，但很有效）。
若你對系統有把握（或事先準備好場景），可以暫時關閉目錄（資料庫）存取，再重試請求。你展示：

• MCP 正確記錄錯誤並觸發警報；
• 代理切到降級模式，誠實地告知使用者目錄不可用，但能提供一般性的點子；
• 此模式下不開放結帳。

最後——簡述運維與演進。
用護照中的一頁收尾：SLO、事故與 roadmap：你的目標指標是什麼、如何監控、有哪些事故已有 runbook、v2 會做什麼（擴展、換模型、進新市場）。

給受眾的關鍵訊號是：你不只做出漂亮 UI，而是準備好上線運行的平台。

12. 產品向 Demo（商務視角）

換成產品敘事的 GiftGenius。

從使用者故事開始。
例如：「有位使用者卡佳，晚上要幫同事選一份禮物。她通常會在各大商店網站上逛 30–40 分鐘。」

展示 ChatGPT + GiftGenius。
卡佳輸入自然語句，而不是在市集網站上點篩選：「幫我找一份 50 美元以內、送給熱愛桌遊的同事的禮物」。ChatGPT 解釋可以使用 GiftGenius，並開啟 widget。GiftGenius 追問幾個細節後，列出候選清單。

接著講結果與價值。
展示禮物卡片，可儲存或直接前往購買，透過 ACP/Stripe 結帳。重點說明：「全流程只花 3–5 分鐘，而且發生在使用者本來就會逗留的地方——ChatGPT。」

接著用 1–2 分鐘說明變現與指標。
解釋你靠 CPA 或商店分潤賺錢，並可為重度使用者提供進階付費模式。引用護照中的數字：完成一次成功場景的成本、轉購率與毛利空間。

再來談成長。
說明如何導入使用者：透過 ChatGPT 的 Store 列表頁、內容行銷、合作整合；同時綁定到產品指標：「我們觀察列表頁改動對 app_opened 與 activation‑rate 的影響；文章與影片對留存與至少完成一次 workflow_completed 的使用者占比的影響。」

最後是風險與計畫。
誠實說明當前限制（例如依賴 OpenAI/Stripe 的配額限制、語系支援仍弱），並展示 roadmap：有哪些實驗與優化已在管線中。

若表述得當，商務受眾看到的就不只是「又一個 AI 小工具」，而是有經濟模型與成長計畫的產品。

13. 實作：圍繞 GiftGenius 建立你的護照與 Demo

作為本講次的實作，你可以直接在自己的 GiftGenius 儲存庫中建立 PASSPORT.md，至少填滿五個區塊：架構、安全、observability/SLO、經濟與產品指標、事故／營運。每當你新增 runbook 或調整 SLO，就回到護照反映變更。

同時，寫一份 5–7 分鐘的 Demo 提綱：前 2–3 分鐘講使用者場景與價值，後 2–3 分鐘講架構與營運（SLO、成本、事故）。這樣的提綱能訓練用商務與技術雙語表述的能力，避免只剩乾巴巴的程式碼或空泛行銷。

這些工件不是「交差的紙本」，而是最終 capstone Demo 的基底。屆時你就按照這份護照與劇本，向 CTO/CEO 等角色進行答辯。

14. 準備護照與 Demo 時的常見錯誤

錯誤 №1：把護照寫成行銷手冊。
有時護照會長得像 landing page：滿滿「創新 AI」的空話，缺乏架構、SLO、成本與事故的具體內容。這種文件幫不了誰：技術方看不出內部如何運作，商務方看不見你如何控風險。護照中應該是事實、圖示、指標與連結。

錯誤 №2：只描述程式碼，不描述資料流與責任。
開發者常見的偏誤，是列出所有服務、函式庫與框架，卻忘了高階的「使用者 → ChatGPT → Widget → MCP → 代理 → ACP/資料庫」圖景。新加入的人於是搞不清楚責任邊界在哪。架構章節中，資料流與層次比列舉所有 npm 套件名稱更重要。

錯誤 №3：沒有把護照與可觀測性與成本工具化連上。
常見情況是護照上大寫著「我們有 SLO」，但看不到如何量測、日誌在哪、JSON 事件到底有哪些欄位。或寫著「LLM 成本可控」，卻沒有任何 cost_per_task 指標。跟真實日誌、指標與儀表板的連結越弱，越可能代表 SLO 與成本只活在 Google Docs，而不是監控系統。

錯誤 №4：Demo 只講漂亮 UI，不談架構與韌性。
很容易變成一場秀：「看，多漂亮的禮物卡片」。技術受眾會想：「Stripe 掛了會怎樣？」「你們如何記錄 tool 呼叫？」「可擴展嗎？」若 Demo 不至少展示 1–2 則關於日誌、SLO 與事故的故事，技術方會覺得這是玩具而非產品。

錯誤 №5：Demo 只講技術，不講使用者故事與經濟。
相反的偏誤：花 10 分鐘談 p95 延遲、MCP handshake、工具的 JSON Schema，卻從未說明要解的使用者痛點、誰付錢、一次場景要花多少成本。對商務與產品來說，這像是「很酷的工程玩意兒，但沒有商務案例」。務必同時戴著工程師與 PM 兩頂帽子。

錯誤 №6：護照與 Demo 前後不一。
有時護照寫一套，Demo 演另一套：文件承諾的 SLO 與儀表板實際不符；護照說有三個事故與 runbook，但現場一出包大家就慌了。盡量把護照當作 Demo 劇本：引用相同的 SLO、相同的儀表板、相同的 runbook。讓聽者感受到這是一個完整一致的系統，而不是隨機的拼湊。

錯誤 №7：把護照當一次性課業。
最大的陷阱是為了交作業寫了 PASSPORT.md 就丟著不管。現實中，正是這類文件把團隊從「口耳相傳」解放出來。請把護照當作程式碼的一部分對待：當發生重大的架構、營運或商務決策時跟著更新。幾個月後你會很感謝當時的自己。