add-auth 是做什麼的？
將此插件中經過測試的驗證模板複製到使用者的專案中，並將它們連接起來。請勿從頭撰寫驗證程式碼，也不要更改模板中的安全邏輯；僅調整邊緣設定（資料庫存取、匯入、UI）。
模板位於 <skill-dir>/../../templates/，其中 <skill-dir> 是此技能的基礎目錄：
templates/fastapi/auth/– FastAPI 套件：config.py、security.py、models.py、db.py、deps.py、routes.py、email.py；測試位於templates/fastapi/tests/test_auth.py。templates/node/lib/auth/core.ts– 無框架核心（雜湊、存取與重設權杖、Cookie 選項），附有core.test.ts。templates/nextjs/– 基於上述核心的 Next.js App Router 層：lib/auth/{schema,users,session,email}.ts、app/(auth)/actions.ts、proxy.ts。
1. 複製前先檢查
找出以下資訊，並用一兩行告訴使用者：
- 技術棧：FastAPI（在 pyproject/requirements 中尋找
fastapi）、Next.js（package.json 中的next）或其他 Node 伺服器（Express、Hono、Fastify、純http）。 - 資料庫層：SQLModel/SQLAlchemy、Drizzle、Prisma 或純 SQL，以及工作階段或
db物件的位置。 - 現有驗證：
users資料表、登入路由、JWT 函式庫、驗證提供者（Clerk、Supabase、Auth.js）。如果已存在驗證功能，請停止並詢問是要取代還是擴展它。 - 專案是否已有包含資料的
users資料表。如果是，則透過遷移將模板的欄位映射到該資料表，而不是建立第二個資料表。
2. 複製並連接
使用插件的腳本進行複製，不要透過讀取和重新撰寫檔案：腳本會原樣複製檔案且不消耗 Token。腳本位於此技能基礎目錄上兩層的 scripts/install.mjs（<skill-dir>/../../scripts/install.mjs）。先在專案根目錄使用 --dry-run 執行，然後再實際執行：
node <skill-dir>/../../scripts/install.mjs fastapi app --tests tests # app/auth/*.py, tests/test_auth.py
node <skill-dir>/../../scripts/install.mjs nextjs . # 或 src/（如果 @/ 別名指向那裡）
node <skill-dir>/../../scripts/install.mjs node src/auth # 僅核心，用於其他 Node 伺服器
如果任何目標檔案已存在，腳本會拒絕覆寫且不複製任何內容。當衝突的檔案是需要合併的檔案（現有的 proxy.ts 或 middleware.ts）時，請使用 --keep-existing 重新執行，這會複製其餘檔案，然後手動合併。僅在使用者同意遺失該檔案後才使用 --force。如果無法使用 node，請手動複製相同檔案（使用 cp），且仍然不要重新輸入它們。
複製後，僅更改下方步驟中指定的內容。保留 security.py、core.ts 和路由中的邏輯不變。
FastAPI
- 使用
install.mjs fastapi <package-dir> --tests <tests-dir>複製（例如app/auth/）。 - 編輯
auth/db.py，讓get_session成為專案現有的工作階段依賴項。這是驗證功能唯一觸及資料庫設定的地方。 - 如果專案使用純 SQLAlchemy 而非 SQLModel，請將
models.py中的User重寫為具有相同欄位的 SQLAlchemy 模型，並保留 Pydantic 架構。 - 在應用程式的主檔案中執行
app.include_router(auth_router)。 - 使用
user: CurrentUser或dependencies=[Depends(require_role("admin"))]保護路由。 - 新增依賴項：
pyjwt、pwdlib[argon2,bcrypt]、email-validator、python-multipart、sqlmodel（如果尚未存在）。 - 透過專案的遷移機制建立
users資料表（如果專案有 Alembic，則使用 Alembic 自動產生）。 - 修正已複製的
test_auth.py中的匯入路徑，使其符合套件路徑（例如from auth變為from app.auth），然後執行測試。
Next.js（App Router）
- 使用
install.mjs nextjs <app-root>複製：核心及其測試、lib/auth/*、app/(auth)/actions.ts和proxy.ts。 - Next.js 15 或更早版本：將
proxy.ts重新命名為middleware.ts，並將其匯出名稱改為middleware。如果專案已有中介軟體/代理檔案，請將驗證檢查合併到其中。 - 將
lib/auth/users.ts指向專案的資料庫：變更db匯入，或為 Prisma/純 SQL 重新撰寫其五個函式。將schema.ts合併到現有的 Drizzle 架構中，並產生遷移。 - 在代理程式中將
PROTECTED設定為應用程式的私有路徑。 - 使用專案自己的元件和樣式建立
/sign-in、/sign-up、/forgot-password和/reset-password頁面。每個頁面都是一個表單，透過useActionState將資料提交到對應的伺服器動作；在登入頁面將next作為隱藏欄位傳遞，在重設頁面則傳遞token查詢參數。 - 在伺服器元件和動作中，使用
lib/auth/session.ts中的getUser()或requireUser("admin")。 - 依賴項：
jose、bcryptjs、zod、server-only（如果按原樣使用 Drizzle 檔案，則還需要drizzle-orm）。
其他 Node 伺服器（Express、Hono、Fastify、純 http）
僅使用 install.mjs node <dir> 複製核心。以專案的風格撰寫路由，但保持與 templates/nextjs/app/(auth)/actions.ts 相同的行為：註冊、登入（對未知電子郵件和錯誤密碼回傳相同錯誤；即使找不到使用者也要呼叫 verifyPassword）、登出、個人資料、變更密碼、忘記密碼（無論帳戶是否存在都回傳相同回覆）、重設密碼（使用使用者的目前雜湊值呼叫 readResetToken）。從 session cookie（使用 cookieOptions() 設定）或 Authorization: Bearer 標頭讀取權杖。新增 requireUser/requireRole 中介軟體。
3. 環境設定
在 .env.example 中新增（切勿新增到已提交的 .env）：
AUTH_SECRET– 至少 32 個隨機字元。使用node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"為使用者的本地.env產生一個；切勿在聊天中列印出來。AUTH_ACCESS_TOKEN_MINUTES（預設 7 天）、AUTH_RESET_TOKEN_MINUTES（預設 60）。- FastAPI：
FRONTEND_URL，以及用於重設電子郵件的SMTP_HOST、SMTP_PORT、SMTP_USER、SMTP_PASSWORD、EMAIL_FROM。Next.js：APP_URL，然後將lib/auth/email.ts的內容替換為專案的電子郵件提供者。 如果未設定電子郵件，重設連結會記錄在日誌中，這在本地開發環境中是可以接受的。
4. 驗證功能正常
執行已複製的測試以及專案自己的檢查（測試、型別檢查、Lint、建置）。報告失敗情況及其輸出。然後說明使用者仍需自行完成的事項，通常是：在正式環境中設定 AUTH_SECRET、設定電子郵件、在真實資料庫上執行遷移。
規則
- 保留：Argon2/bcrypt 雜湊、針對未知電子郵件的虛擬雜湊檢查、針對未知帳戶的相同回覆、與密碼雜湊綁定的重設權杖、權杖上的
purpose檢查、httpOnly SameSite=Lax cookie、重新導向時的safeNext。 - 不要將權杖存放在 localStorage 中，不要記錄密碼或權杖，不要為驗證路由放寬 CORS。
- 登入速率限制不在模板中。如果專案有速率限制器，請將登入和忘記密碼路由置於其後；如果沒有，請提及這一點。
- 工作階段是簽署的權杖，因此登出只會結束該瀏覽器中的工作階段，但複製的權杖在過期前仍然有效。如果使用者需要「全部登出」，請新增
token_version欄位，並在權杖讀取器中檢查它。