AI 功能上线检查

学习目标

读完本课你能：把「AI 功能能不能上线」从感觉变成清单——秘密、配置、权限、失败、日志、评估六组检查，每一项都有明确的验证动作；执行一遍本站的真实检查清单并留档。

问题场景

周五晚上你把 AI 助手改完，本地一切正常，合上电脑。周一换到另一台机器启动，聊天框全是「AI 服务未配置」。排查半小时，发现新机器没有 .env.local。问题不在环境，在于「能不能跑」只存在你的脑子里，没有变成可执行、可重复的检查。

核心解释

上线检查清单的关键不是「全」，而是每一项都能执行出结果。「检查秘密管理是否良好」这种项没法打勾；「确认 .env.local 不在版本库里、启动后 /api/ai/status 返回 configured: true」才能打勾。本站对应的六组检查：

配置组的验证端点是 /api/ai/status，本站的真实实现（app/api/ai/status/route.ts）：

// GET 只报布尔，POST 才做真实连接测试
export async function GET() {
  const status = getAiConfigStatus(); // { configured, provider, model, baseUrlSet, keySet }
  return NextResponse.json(status);
}
export async function POST() {
  const result = await testConnection(); // 真发一条「回复两个字：在线」
  return NextResponse.json(result, { status: result.ok ? 200 : 502 });
}

检查命令按序执行，每一层过了才进下一层，失败定位最快：

npm run typecheck && npm run lint && npm run test   # 检查链（E01）
curl -s localhost:3000/api/ai/status                # 配置状态（GET）
curl -s -X POST localhost:3000/api/ai/status        # 真实连接（POST）
node scripts/e2e-core.mjs                           # 核心路径回归（E03）

示例拆解

拿「失败」这组做一次完整演示。目标：AiErrorCategory 的七类错误，每一类都亲手触发过一次，且用户看到的提示与类别匹配：

关键点：cancelled 是正常分支不是故障（A12 的结论，检查时别误报）；触发不了的类别（比如 quota）标注「无法本地触发，依赖上游」也是合格的检查结论——诚实比凑满重要。

动手任务

1. 把本节两张表抄进项目文档（如 docs/launch-checklist.md），逐项执行并打勾，留下日期与结果。
2. 故意把 AI_API_KEY 改成错值重启，验证 /api/ai/status 的 POST 返回 not_configured 类别，恢复后再验证一遍。
3. 给清单补一项本课没覆盖、但你认为该查的（比如「data/ 目录损坏后如何恢复」），写清验证动作。

常见错误

• 清单项不可执行：写「确保安全」「注意性能」，没法打勾也没法复查，等于没写。
• 只验证 happy path：只测「配置对了能用」，不测「配置错了表现是否体面」——后者才是上线后最先遇到的事。
• 检查一次管终身：配置、依赖、上游都会漂移，清单要跟着每次大改动重跑，留日期。
• 把 cancelled 计入故障：用户主动停止不是错误，混进错误统计会污染 E06 的排错数据。

检查与复盘

• 六组检查各能说出至少一个「可执行的验证动作」
• 亲手触发过至少四类错误并确认 UI 提示与类别匹配
• 本站清单已执行留档，包含执行日期与结果

参考资料

• Next.js 官方文档 —— 环境变量加载与生产构建的官方说明
• The Twelve-Factor App：配置 —— 「配置存于环境」的原则原文（官方中文版）
• OWASP GenAI 安全部 —— LLM 应用常见风险的系统清单