api-smoke

Files (1)

• SKILL.md

SKILL.md (first lines)

# API Smoke Verification

此 Skill 用於完成 Web API 變更後的低成本煙霧驗證。它不是完整 E2E 測試框架，不負責新增可重跑的測試案例；若使用者要求建立正式測試，改依專案既有測試架構處理。

## 啟動條件

符合任一條件時套用：

- 使用者明確要求「測 API」、「呼叫 Swagger 確認」、「寫腳本測一下 API」、「跑多情境 API 測試」。
- 本次修改影響 Web API 端點、請求 / 回應結構、驗證邏輯或授權規則。
- 由 `integration-verify` 判定為 Web API 專案後路由進入。

以下情境不強制套用：

- 只修改與 API 行為無關的內部邏輯、文件或設定。
- 專案已有明確的 CI API 測試，且本輪只需執行該測試。

## 驗證流程

1. **確認驗證目標**：
   - 若使用者指定端點，直接使用該端點。
   - 若未指定，從本次 diff 找出受影響的 Controller、Minimal API 路由或處理常式。
   - 若無法判斷，回報需要使用者指明端點。
2. **啟動或沿用本機服務**：
   - 優先沿用已執行的服務。
   - 若需啟動，使用專案既有指令，例如 `dotnet run`。
   - 不新增套件、不改 `.env`，也不讀取 `.env` 內容。若缺少帳號、測試資料或外部服務，明確回報阻塞條件。
3. **取得 API 規格**：
   - 優先讀取專案的 Swagger / OpenAPI 文件（如 `/swagger/v1/swagger.json`），據此挑選代表性端點與參數。
   - 若無 OpenAPI 文件，從原始碼讀取端點簽章與 DTO 定義。
4. **執行多情境呼叫**：
   - 優先使用當前環境提供的 HTTP 工具；若無，撰寫一次性腳本（PowerShell 或專案慣用語言）呼叫 API。
   - 一次性腳本屬於臨時檔案，存入 `<work-root>/.local/ai-sessions/scratch/`，驗證完成後刪除。
   - 對本次修改相關端點，至少涵蓋下列情境：
     - **正常情境**：合法輸入，預期成功。
     - **邊界情境**：空值、極值、長度上限等臨界輸入。
     - **錯誤輸入**：缺少必填欄位、型別錯誤、格式不符，預期回傳 4xx 與清楚的錯誤訊息。
     - **授權情境**：未帶 token 或權限不足時，預期回傳 401 / 403。
5. **檢查回應**：
   - HTTP 狀態碼符合該情境預期。
   - 回應主體結構與欄位符合 API 規格。
   - 錯誤情境回傳的訊息明確、不洩漏內部細節（如堆疊追蹤）。
   - 服務端 log 沒有與本次變更直接相關的未處理例外。
6. **驗證寫入結果**（端點會寫入資料庫或產生外部副作用時）：
   - 操作後直接查詢資料來源，確認 row 確實新增、更新或刪除，且關鍵欄位值與送出的請求一致。
   - 重新呼叫對應的查詢端點，確認寫入的資料能正確讀回。
   - 寫入佇列、發信等副作用，以對應的 MCP 工具或專案既有方式查證實際結果。

## 共用規範

**以 `integration-verify` 為單一來源的共用規範**（行為基準、結果驗證原則、主動詢問規範、步驟二判定執行環境、步驟六寫入回查 gate、資料異動安全規範、修正迴圈）：由 `integration-verify` 路由進入時已套用；獨立執行本 skill 時，先讀取上述各節並套用。

## 修正迴圈

修正迴圈規範以 `integration-verify` §修正迴圈 為單一來源，由 `integration-verify` 路由進入時已套用；獨立執行本 skill 時，先讀取並套用。本 skill 重跑驗證時的標的為「同一組情境」。

停止時回報（本 skill 領域專屬延伸）：

- 失敗端點與情境。
- 觀察到的狀態碼、回應內容與 log 現象。
- 已修正的項目。
- 尚未解決的原因或需要使用者補充的條件。

## 收尾清理

驗證結束後（成功或中止皆適用）：

- 關閉本流程自行啟動的 API 服務。沿用的既有服務不關閉；若使用者要繼續使用，可保留並於報告中註明仍在執行。
- 刪除步驟四產生的一次性腳本與臨時檔案。

## 驗證報告格式

完成後用精簡格式回報：

```text
API 煙霧驗證：
- 端點：
- 情境與結果：（正常 / 邊界 / 錯誤輸入 / 授權）
- 修正迴圈：
- 未解決項目：
```

若沒有問題，`未解決項目` 可省略。若未能執行驗證，必須說明缺少的工具、服務或資料條件。

有未解項目或阻塞條件時的檔案輸出：

獨立執行且需要寫入或刪除固定報告時，先從呼叫端取得 `LineContext`，驗證 `lineSlug` 符合 `^[a-z0-9]+(?:-[a-z0-9]+)*$`，並確認 `<work-root>/.local/ai-sessions/handoff/<lineSlug>/line.json` 的 `line-slug` 欄位相符。缺少有效 `LineContext` 或 manifest 時停止固定報告的寫入或刪除操作，不得改用預設值。

- 本流程由 `integration-verify` 呼叫時，未解項目交回由其統一輸出，不自行寫檔。
- 本流程為獨立執行時，將未解項目與阻塞條件寫入 `<work-root>/.local/ai-sessions/report/<lineSlug>/verify-unresolved.md`（覆寫模式）。
- 全部通過時不寫檔；若該檔先前已存在，刪除它。

From CloudyWing/ai-dotfiles, MIT.

More from CloudyWing/ai-dotfiles