Capstone 集成：技术与产品演示与“App 护照”

1. 什么是“App 护照”，为什么需要它

App 护照是一份紧凑但信息密集的文档（通常是 1–2 页的 Markdown，或 README 中的一个部分），它能让任何人快速了解你的 ChatGPT App：它的结构、限制、如何赚钱，以及你如何在生产环境中运营它。

这不是营销手册。它不谈“最创新的 AI 技术”，而是聚焦非常落地的内容：

• ChatGPT、你的 Widget、MCP 服务器、Agents 与 ACP/Stripe 之间的边界在哪里；
• 你存哪些 PII，OAuth/scopes 如何设计，密钥如何轮换；
• 你的延迟与可用性 SLO 是什么，有哪些仪表板与告警；
• 一个成功路径平均成本多少，你如何为此收费；
• 已有的典型事故有哪些，Runbook 放在哪里；
• 接下来几个月你打算如何演进该 App。

可以把护照看作链接与高层描述的汇总，它的更新频率低于代码，但高于“面向投资人的官方演示”。

对你这个 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[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。Agent 还可以把目录当资源读取，并执行多个 tools。随后在选择礼物时，在 Stripe 中创建 ACP 会话，结账通过 webhook 完成，结果写入数据库。

最好同时点名技术栈：Next.js 16 + Apps SDK、MCP 服务器（Node/Python）、PostgreSQL、用于缓存的 Redis、作为支付通道的 Stripe。

还可以补一小段技术片段，让人看到这些“砖块”如何在代码中落地。例如，一个 Next.js 路由，向 MCP 客户端透传 requestId 与 userId：

// 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，所以都没问题”。而是要对安全、合规与法务关心的问题给出具体回答。

针对 GiftGenius，建议简要说明：

认证与授权模型：
对于 commerce 场景，使用 OAuth 2.1（带 PKCE）通过 MCP Auth Server；token 绑定 user_id 与 tenant_id；所有与结账相关的 tool 调用都需要 scope commerce.checkout。

哪些数据属于 PII 以及处理方式。
例如：email 与姓名是 PII；礼物偏好是伪匿名数据；仅记录哈希化的 email；不保存收货地址，只把它透传给 Stripe 与 webhook。

数据保留与删除策略：
工具日志保留 30 天；commerce 事件保留 1 年；应用户请求可删除其订单及关联的分析事件。

密钥管理：
简述 OpenAI API key、Stripe secret、OAuth client secret 存放在何处（例如托管的 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 授权的描述中继续引用这些 scopes。这不再是“最小权限”的口号，而是具体的契约。

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：钱与用户行为

这里把之前经济学模块（M19）中的内容串起来：成本指标、定价与产品分析。

在护照中为 GiftGenius 固化：

关键路径的单位经济（可理解为“一次完整任务的经济学”）。
例如：“平均 cost_per_successful_task（完成礼物选择并成功支付） = $0.13（LLM + 基础设施）。每次任务的平均收入 = $0.80（来自合作伙伴的 CPA）。”

主要变现模式。
简述：“提供免费的基础礼物推荐（不强制购买）；通过导流到合作商家赚取 CPA；另有可选的 premium 订阅（更丰富的筛选与礼物历史）。”

关键产品指标。
例如：activation‑rate = 至少完成一次 workflow_completed 的用户占比；repeat‑rate = 月内至少回访一次的用户占比；workflow_completed → checkout_success 的转化。

实验。
活跃的 A/B：“模型 A（昂贵） vs 模型 B（廉价）”、“长流程向导 vs 快速内联”。对每个实验保存 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,
  }));
}

以及在流程成功完成时的调用：

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 大量报错。在护照中说明对应的 Runbook “Checkout Failures”：包括症状、查看位置（错误仪表板、webhook 端点日志）、快速缓解步骤（临时措施：关闭问题 feature‑flag，将部分流量切到 sandbox，或暂时只提供礼品卡）以及后续（post‑mortem、增加新告警）。

MCP/LLM 问题。
例如：suggest_gifts 的 p95 延迟升到 9 秒，或大量请求出现 “Error talking to app”。这里有独立 Runbook：检查 OpenAI、隧道/Vercel 状态，MCP 健康检查，切换到降级模式，在该模式下 Agent 尝试在没有目录访问的情况下回答（更通用的想法，不走 commerce）。

同一部分还应简述运维节奏：多长时间复查 SLO、做成本评审、审计安全日志与轮换密钥。

注明谁负责 on‑call（即使只有你一个人），以及告警推送到哪个 Slack 频道或邮箱。

8. Roadmap & Risks：向前看的诚实视角

最后一个模块是关于未来。不必写成小说。列出 3–5 个真实的演进步骤及若干已知限制即可。

对 GiftGenius，可以是：

• 上线 LLM 评估（LLM‑evals）以衡量推荐质量，把质量与转化关联；
• 新增一个本地化语言并测试本地化的工具描述；
• 在部分流量上试验更便宜的模型；
• 提升对 Stripe 故障的韧性（更稳地处理 webhook 与延迟确认）；
• 为迁移到新版本 Apps SDK 或 MCP 做准备（为工具契约做版本化）。

限制：API 上限、ChatGPT UI 限制（例如卡片数量限制）、当前架构的薄弱点（单区域数据库、没有 MCP 热备等）。

实验计划：你准备在定价/UX/模型上验证哪些假设，以及用哪些指标来做决策。

9. 护照放在哪里、如何更新

实践上，最方便的形式是在 GiftGenius 仓库根目录的 PASSPORT.md 或 docs/ 目录，同时在你的文档系统（Confluence、Notion 等）保留一份副本或链接。

文档既要足够轻（10–15 分钟可读完），也要足够密（足以回答以下问题）：

• “这到底是个什么 App，架构如何？”
• “如果 X 故障，会发生什么？”
• “获取/服务一个用户的成本是多少？”
• “当前最担心的风险是什么？”

在以下变化发生时应更新护照：

• 架构边界（新服务、新支付通道、迁移到另一栈）；
• 关键 SLO 或安全策略（例如不同的保留期）；
• 变现模型；
• 重大事故及其事后复盘结论。

代码的小改动不必立即修改护照，否则它会沦为又一份过时文档。

护照本质上是关于你 App 的知识浓缩。下一步，就是基于它学会向人讲产品：既面向技术，也面向业务。

10. 技术‑产品演示：为什么需要两套“叙述版本”

演示 GiftGenius 时，你几乎总在面向两类受众（有时混在一屋）：

• 技术人（CTO、架构师、安全、开发负责人）；
• 产品/业务受众（CEO、投资人、产品经理、市场）。

技术受众关心：

• 架构清晰、分层明确、可扩展点在哪；
• 可靠性与可观测性已铺好：日志、追踪、SLO、告警；
• 韧性设计：OpenAI、MCP、Stripe 故障时会发生什么；
• 演进计划（SDK/MCP/模型的迁移）。

业务更在意：

• 用户痛点是什么（例如“挑礼物要花 40 分钟”）；
• GiftGenius 如何在 ChatGPT 内用几分钟解决；
• 你的变现方式、单位经济与增长指标；
• 是否降低获客成本、提升转化/营收。

因此，可以把同一场演示看作两层叙事：成熟产品的信号要给双方看，但侧重点不同。

11. GiftGenius 技术演示脚本（5–7 分钟）

假设你在技术受众面前介绍 GiftGenius。

先给极短的上下文。
大约 30 秒：“GiftGenius——用于礼物挑选的 ChatGPT App，支持 ACP 结账。我们运行在 ChatGPT 内，使用 Apps SDK、MCP 与一个用于步骤规划的 Agent。”

然后是架构页/护照片段。
打开类似我们写的 Mermaid 图，解释 ChatGPT 的职责边界（LLM 部分）、你的 Widget、MCP 以及与 Stripe 的 commerce 层。强调所有 tools 都封装在 MCP 中，而 Widget 是薄 UI 层。

带日志的现场演示。
开启分屏：左边是 ChatGPT 与 GiftGenius，右边是日志或 MCP Inspector。发起自然的请求，比如“给一位玩家预算 50$ 选礼物”。执行过程中展示：

• tool 调用 suggest_gifts，带有 request_id；
• 结构化日志 tool_invocation，包含 tokens、cost_estimate 与 duration_ms；
• 第二个 tool，创建 ACP 会话并生成订单。

如果能当场点开仪表板就更好：“这是该场景过去 24 小时的 p95 延迟，这是 checkout 的成功率。”这会让技术受众意识到，这不是一个 pet‑project，而是具备可观测性的系统。

故障注入（可选但很亮眼）。
如果对系统有足够把握（或预先准备了场景），可以临时关闭目录访问（数据库），再跑一次请求。展示：

• MCP 正确记录错误并触发告警；
• Agent 切到降级模式，并如实告知用户目录不可用，但可给出通用灵感；
• 在该模式下不提供 checkout。

最后，简述运维与演进。
用护照中的一页收尾：SLO、事故与路线图；你的目标指标与监控方式；已有的 Runbook；v2 会做什么（扩容、新模型、新市场）。

要传达的核心信号：你们的不只是漂亮 UI，而是一套可在生产存活的成熟平台。

12. 产品演示脚本（业务视角）

同样是 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 配额、本地化支持尚弱），并给出路线图：有哪些实验与改进在推进中。

如果做到以上，业务受众看到的就不是“又一个 AI 小部件”，而是一个有清晰经济学与增长计划的产品。

13. 实践：围绕 GiftGenius 打磨你的护照与演示

作为本课实践，你可以直接在自己的 GiftGenius 仓库中新建 PASSPORT.md，至少填写五个部分：架构、安全、observability/SLO、经济与产品指标、事故/运维。一旦写了新的 Runbook 或修改了 SLO，就回到护照同步更新。

并行再写一份 5–7 分钟的演示提纲：前 2–3 分钟讲用户路径与价值，后 2–3 分钟讲架构与运行（SLO、成本、事故）。这样的提纲能很好地训练你同时用业务与技术语言表达，而不滑向枯燥代码或空泛营销。

这些产物并非“走过场的作业”，而是最终 Capstone 演示的基础。之后你会依据这份护照与脚本，向假想的 CTO/CEO 为你的 App 做答辩。

14. 准备护照与演示时的常见错误

错误 1：把护照做成营销册。
有时护照会像着陆页：充斥“创新 AI”的空话，缺乏关于架构、SLO、成本与事故的具体信息。这样的文档谁也帮不了：技术看不出内部运作，业务看不到你对风险的掌控。护照应包含事实、图示、指标与链接。

错误 2：只描述代码，不讲数据流与职责。
开发者常见的偏差是罗列所有服务、库与框架，却忘记高层级的“用户 → ChatGPT → Widget → MCP → Agents → ACP/DB”图景。结果新人看不清职责与边界。架构部分更重要的是数据流与分层，而非每个 npm 包的名字。

错误 3：护照没有与可观测性和成本采集打通。
护照里豪言“我们有 SLO”，却看不到它们如何度量、日志在哪、JSON 事件写了哪些字段。或者说“LLM 成本可控”，却没有任何 cost_per_task 指标。与真实日志、指标与仪表板的连接越弱，就越可能意味着 SLO 与成本只活在 Google Docs，而不是监控系统里。

错误 4：只演示漂亮 UI，不讲架构与容错。
很容易陷入秀界面：“看这些精美的礼物卡片”。技术受众此时会想：“Stripe 挂了会怎样？”“你们如何记录 tool 调用？”“可扩展吗？”如果演示不展示至少一两条关于日志、SLO 与事故的故事，技术会觉得它像玩具，而不是产品。

错误 5：只做给技术看的演示，没有用户故事与经济学。
反向的偏差：10 分钟都在聊 p95 延迟、MCP 握手、工具的 JSON Schema，却没有讲你解决什么用户痛点、谁付费、一次场景成本几何。对业务与产品来说，这像是“很酷的工程玩具，但没有商业案例”。请始终戴两顶帽子：工程师与产品经理。

错误 6：护照与演示不一致。
有时护照写一套，演示又是一套：文档里承诺的 SLO 与仪表板上的不一致；护照说有三个带 Runbook 的事故，但现场一出错大家就慌。尽量把护照用作演示脚本：引用相同的 SLO、仪表板与 Runbook。这样听众会感到它是一套完整系统，而非拼凑的碎片。

错误 7：把护照当一次性课程作业。
最大的陷阱是为了交付本模块而写一份 PASSPORT.md，然后就不再维护。在真实团队里，缺少这类文档，知识就会变成“装在脑子里”的个人资产。请把护照当作代码的一部分：当发生重大的架构、运维或商业决策时，就更新它。几个月后你会感谢现在的自己。