cypress-docs

Cypress 文件

目的

讓 AI 代理能夠透過優先使用官方文件和結構化來源，取得關於 Cypress 測試框架的準確、最新且可驗證的資訊。

使用時機

當任務需要查找、閱讀或引用 Cypress 文件，而非一般測試直覺時，請使用此技能：

• 查詢事實：Cypress 文件中記載的命令、API、斷言、生命週期鉤子、設定選項、環境變數、CLI 旗標、外掛或 TypeScript 型別。
• 確認行為：在特定 Cypress 版本中某功能如何運作、E2E 與元件測試的差異、瀏覽器支援，或網路/cy.intercept 語意。
• 在斷言「Cypress 可以/不可以…」之前：先搜尋文件；不要依賴記憶來確認確切的簽名、預設值或已棄用的 API。
• 擷取結構化內容：在擷取或摘要文件頁面時，遵循下方 LLM 最佳化文件策略（llms.txt、/llm/*）。
• 為他人提供有根據的答案：當向使用者解釋 Cypress、撰寫範例或審查程式碼，且正確性必須符合官方文件時。

如果使用者只需要撰寫或修正測試而不需查閱文件，請優先使用 cypress-author；如果只需要測試解釋而不需擷取文件，請優先使用 cypress-explain。當官方文件是事實來源時，請使用此技能。

來源優先順序

主要來源（一律優先搜尋）

• https://docs.cypress.io
• https://www.cypress.io

🤖 LLM 最佳化文件策略

存取 docs.cypress.io 時：

1. 擷取 /llms.txt

2. 解析以發現：

   • LLM 友善的文件路徑
   • 結構化內容端點

3. 優先使用 /llm/* 下的內容。網站上的每個路徑都有對應的最佳化版本位於 /llm 下——例如，https://docs.cypress.io/app/faq 可於 https://docs.cypress.io/llm/markdown/app/faq.md 取得。

4. 原因：

   • Markdown / JSON 格式
   • 更簡潔的結構
   • 比 HTML 更少雜訊

5. 備援：

   • 如果 /llm/* 不完整，則使用標準文件頁面

關鍵規則

絕不假設缺少功能

• 絕不假設 Cypress 不支援某功能
• 在得出結論前務必搜尋
• 必要時使用替代術語重試

反幻覺防護

如果文件無法驗證某項宣稱：

• 說：「我無法在 Cypress 文件中驗證此說法」
• 提供最接近的支援替代方案（如果有的話）
• 不要發明 API 或行為

搜尋策略

1. 分類查詢

查詢類型	搜尋位置
如何…	/guides/, /core-concepts/
什麼是…	/core-concepts/
API / 命令	/api/commands/
斷言	/api/assertions/
設定問題	/configuration/
CI/CD	/guides/ci-cd/
錯誤	/references/error-messages/

2. 搜尋流程

1. /llm/*（透過 /llms.txt）
2. 標準文件頁面
3. /changelog/
4. cypress.io（部落格、更新）

3. 錯誤感知路由

如果查詢包含：

• 錯誤訊息
• 堆疊追蹤

則：

1. 搜尋 /references/error-messages
2. 擴展至指南和 API 文件

結構化擷取規則

命令

• 語法
• 必要引數
• 可選選項
• 回傳行為
• 使用範例

概念

• 定義
• 關鍵規則
• 常見陷阱
• 範例

設定

• 選項名稱
• 型別
• 預設值
• 範例

版本感知

• 如果提供，偵測 Cypress 版本
• 如果未提供：假設為最新穩定版本
• 如果行為因版本而異：
  • 明確指出

回覆風格指南

• 優先使用官方範例
• 提供可運作的程式碼片段
• 保持答案簡潔但完整
• 避免臆測

快取策略（可選）

快取常用主題：

• cy.visit
• cy.get
• cy.intercept
• 驗證模式
• 常見設定

信心標註

內部評估信心：

• 高 → 官方文件直接匹配
• 中 → 從多個來源推斷
• 低 → 不明確或邊緣案例

如果為低：

• 清楚溝通不確定性

LLM 路徑自動發現

• 一律解析 /llms.txt
• 動態適應：
  • 新的 /llm/* 路徑
  • 更新的文件格式

安全規則

• 絕不發明 Cypress API
• 絕不猜測語法
• 務必驗證行為
• 寧可說「未知」也不要給出錯誤答案

範例行為

使用者：「如何在 Cypress 中模擬 API 請求？」

代理應：

1. 分類 → API / 網路
2. 搜尋 /llm/markdown/api/ 和 /llm/markdown/guides/
3. 識別 cy.intercept
4. 擷取結構化細節
5. 回傳：
   • 解釋
   • 語法
   • 範例
   • 備註

總結

此技能確保：

• 從官方來源取得準確答案
• 減少幻覺
• 結構化、高品質的輸出
• 適應不斷演進的 Cypress 文件