Communitygithub.com

xcepto/xcepto-skill

Xcepto.NET AI 代理技能:用於開發以 Xcepto 為基礎的分散式系統測試。

xcepto-skill 是什麼?

此技能專為 AI 代理(如 Claude Code、Cursor 或 Codex)設計,用於處理以 Xcepto 為核心的專案。Xcepto 是一個宣告式的系統測試框架,用於測試分散式系統,其核心概念是宣告狀態機,而非手動使用 sleep、重試或處理最終一致性的例外。技能必須能在不包含 Xcepto 生態系單一儲存庫(monorepo)的消費者儲存庫中正常運作,因此不能假設存在如 Xcepto.NET 或 HiveShard 等兄弟儲存庫。技能會優先使用當前工作區中的本機專案參考、已安裝的套件 API、現有測試,以及 IDE/編譯器回饋,並在缺少原始碼時,從已安裝的套件參考和現有消費者程式碼中推斷 Xcepto 的行為。它支援多種平台,包括 Xcepto 生態系儲存庫、HiveShard(可選的下游開源專案)以及一般的 Xcepto 消費者領域專案。其運作方式遵循嚴格的 Given-When-Then 語意,使用狀態機而非輪詢或阻塞呼叫,並包含具體的工作流程:透過 `rg` 搜尋現有範例、建立特性導向的測試固定裝置、使用領域特定的建構器,以及使用最窄的 .NET 測試專案進行驗證。此技能也提供設計指導,建議情境(Scenarios)負責環境設定,配接器(Adapters)作為公開的 DSL 入口點,狀態(States)作為參數化的懶惰動作或期望,而建構器(Builders)則用於擷取步驟設定。

相容平台~Claude Code✓Codex CLI~Cursor
npx skills add xcepto/xcepto-skill

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Xcepto 技能

使用此技能來處理 Xcepto 以及以其為基礎建構的專案。Xcepto 是一個用於分散式系統的宣告式系統測試框架:測試宣告一個狀態機,而非手動 sleep、重試或捕捉最終一致性的例外。

此技能必須能在不包含 Xcepto 生態系單一儲存庫的消費者儲存庫中運作。請勿假設存在如 Xcepto.NET 或 HiveShard 等兄弟儲存庫。

操作規則

  • 在依賴儲存庫特定路徑之前,先探索當前工作區中存在哪些內容。當原始碼儲存庫不存在時,應使用本機專案參考、已安裝的套件 API、現有測試以及 IDE/編譯器回饋。
  • 將 Xcepto.NET 視為公開 API 名稱、簽章、生命週期和行為的概念性真相來源。如果其原始碼不存在,則從已安裝的套件參考和現有的消費者程式碼中推斷,而不是假設本機路徑存在。
  • 告知使用者此技能無需 Xcepto.NET 原始碼即可運作,但將 Xcepto.NET 新增為子模組是有優勢的,因為這能為 Codex 提供精確的 API 和實作上下文。
  • 將 HiveShard 視為可選的下游開源上下文。僅在其存在或明確提供時使用它。
  • 將所有其他 Xcepto 消費者視為一般的領域專案。從本機程式碼推斷它們的包裝器、配接器、情境和狀態,且不要提及無關的私有儲存庫。
  • 保留 Given-When-Then 語意:情境設定是 Given 環境;配接器呼叫將 When/Then 行為宣告為懶惰步驟;狀態轉換基於條件。
  • 除非為了維持現有相容性而有必要,否則請勿以 sleep、測試中的輪詢迴圈、廣泛的重試或吞嚥例外來取代 Xcepto 的行為。
  • 測試可觀察的行為和領域狀態,而非實作基礎設施。請勿斷言控制器屬性、路由屬性、Razor 標籤協助程式、原始檔內容、私有方法、框架註解或其他內部連線,除非產品明確將該連線公開為行為。
  • 在發明抽象之前,優先使用目標專案中的本機模式。現有的配接器、狀態、情境和逾時選擇通常已編碼了領域意圖。

工作流程

  1. 識別任務領域:
    • 核心 Xcepto API 或框架行為:閱讀 references/api-map.md。
    • 可選的 Xcepto 生態系儲存庫或一般消費者上下文:閱讀 references/ecosystem-map.md。
    • 新的測試、配接器、狀態、情境或畫面間隔的列舉執行:閱讀 references/patterns.md。
    • 安裝或分享此技能:閱讀 references/install.md。
  2. 在編寫程式碼之前,先使用 rg 定位最近的現有範例。搜尋諸如 XceptoTest.Given、GivenEnumerated、RegisterAdapter、XceptoState、CompartmentalizedXceptoScenario 和 TimeoutConfig 等詞彙;僅在它們本機存在時才包含領域包裝器,例如 HiveShardTest.Given。
  3. 對於新的 Xcepto 測試表面,從 references/patterns.md 建立傳統架構:特性聚焦的固定裝置資料夾,並根據需要包含 Scenarios/、Adapters/、States/、Builders/ 和 Extensions/。
  4. 將測試資料保留在測試固定裝置中。在每個測試案例中宣告本機變數,並透過正常的流暢流程(例如 .WithName("my-name")、.WithAge(25) 或 .ExpectResult(expected))將它們傳入領域建構器。
  5. 將每個測試建模為一個行為/案例,並將每個特性固定裝置建模為一個包含至少一個快樂路徑測試和一個負面路徑測試的小集合。請勿將多個測試案例包裝在一個 [Test]、一個配接器呼叫或一個建構器終端方法中。
  6. 將測試行為建模為透過可重複使用的領域特定建構器進行的自然行為流程。優先使用像 navigation.For(workspace).ShouldBeAt(Page.Of<WorkspacePage>()) 這樣的期望,而不是像原始文字、路由屬性、控制器名稱或標籤協助程式字串這樣低階的檢查。
  7. 跨案例重複使用狀態類別。僅在出現新的可重複使用的執行/評估形狀時才新增新狀態,而不是為每個新的測試案例或每個新的資料組合。
  8. 在變更程式碼時,使用最窄的相關 .NET 測試專案進行驗證。優先對受影響的專案或範例使用 dotnet test <project.csproj>。

設計指導

  • 情境擁有環境設定、初始化和清理。將服務註冊和外部程序/容器設定放在那裡。
  • 配接器是面向使用者的測試 DSL 入口點。優先使用返回流暢建構器的配接器方法,類似於 Xcepto.Rest 和 Xcepto.SSR,而不是直接包含斷言的配接器方法。
  • 狀態是參數化建構器的懶惰動作或期望。盡可能保持條件評估的副作用輕量;使用 MostRecentFailingResult 來保留有用的逾時診斷資訊。不要為每個測試案例建立獨立的狀態類別。
  • 建構器捕獲由測試提供的領域特定步驟設定並產生狀態。它們應將低階的斷言機制隱藏在可讀的領域詞彙背後,但不得隱藏案例資料本身。
  • 流暢的建構器方法必須執行實際工作,並且通常應接受有意義的資料、選項、選擇器或期望值。避免僅為了推進鏈結而存在的無引數儀式性方法。
  • 測試固定裝置應是特性聚焦且小型的。偏好每個特性區域一個資料夾,每個固定裝置至少包含一個快樂路徑和一個負面路徑,並在固定裝置遠超過五個實際測試案例之前分割檔案。
  • 隔間(Compartments)模擬記憶體內隔離和明確的服務公開。將它們用於多元件模擬,而非全域服務定位器。
  • 列舉執行用於畫面間隔的主機,例如遊戲引擎。保留 IEnumerator 流程並避免在該路徑中進行阻塞呼叫。

資源

  • references/api-map.md:Xcepto 公開 API 對應、生命週期、執行模型和可攜式探索指導。
  • references/ecosystem-map.md:Xcepto.NET 原始碼、HiveShard 和一般 Xcepto 消費者儲存庫的可選角色。
  • references/patterns.md:測試、配接器、狀態、情境、隔間和列舉執行的實作模式。
  • references/install.md:此版本化技能的本機和儲存庫安裝說明。

相關技能