Communitygithub.com

xcepto/xcepto-skill

用于 AI 代理的 Xcepto.NET 技能

xcepto-skill 是什么?

Xcepto Skill 是一个面向 AI 代理(如 Codex、Cursor 等)的强大技能,旨在帮助开发者高效使用 Xcepto 框架。Xcepto 是一个声明式系统测试框架,专为分布式系统设计,它允许测试者声明状态机,从而避免手动休眠、重试或处理最终一致性异常。该技能的核心价值在于,即使消费者的仓库中不包含 Xcepto 生态系统的主仓库(如 Xcepto.NET 或 HiveShard),它也能正常工作。它会智能地通过本地项目引用、已安装的包 API 以及 IDE/编译器反馈来推断上下文,而不是假设本地代码路径一定存在。技能提供了详尽的操作规则、工作流程和设计指南,指导开发者如何创建适配器(Adapters)、状态(States)、场景(Scenarios)以及使用构建器(Builders)进行流畅测试。它强调 Given-When-Then 语义,测试可观察的行为和领域状态,而非内部实现细节。技能支持 NUnit 测试平台,并推荐保持测试原子性、复用状态类、以及使用 `dotnet test` 进行验证。对于复杂的多组件模拟,它支持“舱室模型”(Compartment)和“枚举执行”(Enumerated Execution)模式,非常适合游戏引擎等帧间隔主机。最后,该技能包含多个参考文档(如 API 地图、生态地图、模式指南和安装说明),为开发者提供了全面的上下文和示例,确保他们能快速上手并编写健壮、可维护的分布式系统测试。

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

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Xcepto 技能

使用此技能来编写与 Xcepto 相关的项目。Xcepto 是一个声明式系统测试框架,专为分布式系统设计:测试声明一个状态机,而不是手动休眠、重试或捕获最终一致性异常。

该技能必须能在不包含 Xcepto 生态系统主仓库的消费者仓库中工作。不要假设存在诸如 Xcepto.NET 或 HiveShard 之类的同级仓库。

操作规则

  • 在依赖特定仓库路径之前,先发现当前工作区中存在什么。当源仓库不存在时,使用本地项目引用、已安装的包 API、现有测试以及 IDE/编译器反馈。
  • 将 Xcepto.NET 视为公共 API 名称、签名、生命周期和行为的逻辑真理来源。如果其源代码不存在,则从已安装的包引用和现有消费者代码中推断,而不是假设本地路径存在。
  • 告知用户此技能无需 Xcepto.NET 源代码即可工作,但将 Xcepto.NET 作为子模块添加是有利的,因为可以为 Codex 提供精确的 API 和实现上下文。
  • 将 HiveShard 视为可选的下游开源上下文。仅当其存在或显式提供时才使用它。
  • 将所有其他 Xcepto 消费者泛化地视为领域项目。从本地代码推断它们的包装器、适配器、场景和状态,而不要命名无关的私有仓库。
  • 保留 Given-When-Then 语义:场景设置是 Given 环境;适配器调用将 When/Then 行为声明为惰性步骤;状态转换基于条件。
  • 除非为了保持现有兼容性需要,否则不要用休眠、测试中的轮询循环、宽泛的重试或异常吞并来替换 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 来保留有用的超时诊断。不要为每个测试用例创建一个不同的状态类。
  • 构建器捕获测试提供的领域特定步骤配置并生成状态。它们应该通过可读的领域词汇隐藏低级断言机制,但绝不能隐藏用例数据本身。
  • 流畅构建器方法必须执行实际工作,并且通常应接受有意义的数据、选项、选择器或期望值。避免仅用于推进链的无参数仪式性方法。
  • 测试夹具应以特性为中心且小巧。优先为每个特性区域创建一个文件夹,每个夹具至少包含一个快乐路径和一个负面路径,并且当一个夹具的测试用例数远超过五个之前,将文件拆分。
  • 舱室模型模拟内存隔离和显式服务暴露。使用它们进行多组件模拟,而不是全局服务定位器。
  • 枚举执行适用于帧间隔主机,例如游戏引擎。保留 IEnumerator 流程,并避免在该路径中使用阻塞调用。

资源

  • references/api-map.md:Xcepto 公共 API 地图、生命周期、执行模型和可移植发现指南。
  • references/ecosystem-map.md:Xcepto.NET 源代码、HiveShard 以及泛型 Xcepto 消费者仓库的可选角色。
  • references/patterns.md:测试、适配器、状态、场景、舱室和枚举执行的实现模式。
  • references/install.md:此版本化技能的本地和仓库安装说明。

相关技能