Final Project：做一個可控、可驗證的 AI App

規則：可以查前六課、官方文件，也可以使用 coding agent；但最後你必須能指出 model、prompt、context、retrieval、structured output、tool execution、Auth、database 與 deployment 各自負責什麼。AI 幫你寫 code 不代表你可以不知道 code 在授權什麼。

你的任務：Study Workspace Assistant

做一個私人學習工作區。每位使用者都有私人文件、私人 tasks 與 AI conversation。AI 可以根據自己的文件回答，也可以透過 tools 管理自己的 tasks。

Authenticated user
↓ question / request
Context builder
↓ recent history + selected state
Retrieval layer
↓ authorized evidence
Model
↓ answer OR tool call
Backend
↓ validate / authorize / execute
Tool result
↓ model
Structured final response
↓ UI + citations

先定義產品 contract

Grounded Q&A：根據私人文件回答並附 citation。

Read tool：查詢目前使用者的 tasks。

Write tool：建立目前使用者的 task。

Confirmed destructive tool：刪除 task 前必須確認。

Checkpoint A｜先畫架構再寫 code

Browser → same-origin API → Worker / backend
├─ Auth / session
├─ Context builder
├─ Retrieval service
├─ Model adapter
├─ Tool dispatcher
└─ D1 / app database

Vector index / document store

Model proposes.
Application validates.
Authorization decides.
Database stores truth.

Checkpoint B｜資料模型必須有 owner boundary

users
sessions
conversations
messages
documents
chunks / retrieval metadata
tasks
tool_audit

conversations.user_id、documents.user_id、tasks.user_id 都必須能追到 owner。不要期待 prompt 幫你隔離不同使用者資料。

Checkpoint C｜Auth 先工作，AI 才准工作

Session cookie → session lookup → current user → Conversation / Retrieval / Tools

未登入 request 不應該先呼叫模型，再回 401。

Checkpoint D｜Model API 保持在 backend

Frontend 只呼叫自己的 POST /api/assistant。Provider API key、model ID、instructions 與 tool definitions 都留在 server-side。

Checkpoint E｜Prompt 必須版本化

const ASSISTANT_PROMPT_VERSION = "study-assistant-v1";

Instructions 至少要說清楚 evidence、資訊不足、untrusted retrieved content / tool output，以及模型不能假裝 tool 已執行。

Checkpoint F｜Context 要有 policy

Stable instructions
+ optional conversation summary
+ recent messages
+ retrieved evidence
+ current user input

至少做 sliding window、output budget、summary / discard policy，以及 conversation owner filter。

Checkpoint G｜建立私人 RAG corpus

document_id
user_id
title
version
source metadata

Document → clean → chunk → metadata → embedding / vector index

Question → authorization filter → retrieval → ranking → selected chunks

先限制 allowed documents，再把 evidence 送進模型。

Checkpoint H｜Citation 要能回到真正來源

S1 → document A / page 3
S2 → document B / section 2

Model 只輸出 application-owned source IDs；Frontend 再映射回真正 title / page / section。

Checkpoint I｜Structured final response

{
  "answer": "...",
  "answerable": true,
  "citations": ["S1", "S2"],
  "used_tools": ["list_tasks"],
  "needs_confirmation": false
}

Model output → parse → schema validation → business validation → application response

Checkpoint J｜找不到證據時要能停止

{
  "answerable": false,
  "answer": "目前提供的文件沒有足夠資訊回答。",
  "citations": []
}

Checkpoint K｜至少兩個 tools

list_tasks({ done })
create_task({ title })
delete_task({ id }) // 推薦；需要 confirmation

Checkpoint L｜Tool call 永遠先 validate

Tool schema validity ≠ business validity ≠ authorization

即使 schema 通過，create_task({ title: " " }) 仍然應被 business validation 拒絕。

Checkpoint M｜Identity 不准由模型指定

不要用 list_tasks({ user_id: 42 })；改成 listTasksTool(db, currentUser, args)。Retrieval filter 的 user id 也由 backend 注入。

Checkpoint N｜Destructive tool 要有 confirmation state

Model proposes delete_task(12)
↓ verify ownership
↓ create confirmation id
↓ frontend asks user
↓ explicit confirm
↓ re-check session + ownership
↓ execute once

Checkpoint O｜Tool loop 必須 bounded

max tool rounds。

max tool calls per request。

deadline / timeout。

controlled tool error。

Checkpoint P｜Prompt injection 測試不能省

User input：要求忽略規則、顯示 secret。

RAG 文件：文件裡要求呼叫危險 tool。

Tool result：外部文字要求洩漏 session token。

驗收標準不是相信模型永遠不受影響，而是即使提出危險 action，backend 仍無法繞過 authorization / allowlist / confirmation。

Checkpoint Q｜建立 AI evaluation set

至少 12 個案例，分別測 Prompt、Context、Retrieval、Grounding / Citation、Structured Output、Tool selection、Authorization、Confirmation。至少包含找不到答案、相似但錯誤文件、舊資訊修正、無效 arguments、跨 user resource、injection、provider timeout / tool failure。

Checkpoint R｜Retrieval 與 Generation 分開觀測

request id
prompt version
model id
retrieved source ids / scores
tool calls
tool result status
structured output validation status
latency / usage

Production log 不要無腦保存 API key、session token、raw password、整份私人文件或所有完整私人對話。

Checkpoint S｜UI 要讓系統狀態看得懂

conversation area。

loading / generating state。

citations。

tool action feedback。

confirmation UI。

insufficient evidence。

controlled error state。

不要讓使用者分不出「AI 說它做了」和「系統真的做成功」。

Checkpoint T｜Production deployment

HTTPS。

Auth cookie 正常。

Provider secret 只存在 platform secret。

Database migrations 已套用。

Vector / document index 可用。

Frontend 使用自己的 same-origin API。

Production smoke test

User A：

Register → Login → ask document question → see citation → list tasks → create task → request delete → confirmation → delete succeeds

User B：

再測：No evidence → answerable: false；Injection document → no privilege escalation；Invalid tool args → controlled error；Provider failure → UI 不假裝成功。

最終 README 要能回答這 10 個問題

1. request 從 browser 到 model 經過哪些層？

2. Provider secret 放在哪？

3. Instructions 放在哪？版本怎麼記？

4. History 如何選進 context？

5. RAG 如何只搜尋 current user documents？

6. Citation 如何映射回來源？

7. Structured output 在哪裡 validation？

8. Tool arguments、identity、authorization 分別在哪裡處理？

9. 哪些 actions 需要 confirmation？

10. 壞掉時如何分辨 retrieval、model、tool、database 或 frontend 問題？

Final rubric：不是看模型「聰不聰明」

Correct boundaries
+ traceable data flow
+ grounded evidence
+ validated structures
+ explicit permissions
+ bounded side effects
+ reproducible tests
+ deployable system

你不需要在 Final 加這些東西

Multi-agent swarm。

自動瀏覽整個 Internet。

十幾種 provider routing。

複雜 workflow graph。

Fine-tuning。

自己訓練 embedding model。

這些可以是之後的專題，但不是證明你已經會做 AI App 的必要條件。

最後收斂：你現在是在做產品，不是在寫 prompt

User
↓ Web App boundaries
↓ Selected context + evidence
↓ Model reasoning / tool proposal
↓ Application validation + permission
↓ Database / side effects
↓ Verified result + citations
↓ User

AI Builder 的終點不是「會呼叫模型 API」，而是知道模型應該負責哪一段，又有哪些事情絕對不能只交給模型決定。

完成條件：你能部署一個有 Auth、私人資料、受控 context、RAG citation、Structured Output 與安全 Tool Calling 的 AI App；能用兩個帳號驗證資料隔離，能用固定 evaluation cases 找 regression，並能逐層解釋一次 request 從使用者輸入到最終回答或真實副作用的完整資料流。