create-yss-spec 2.2.10 → 3.0.1

package/template/.hermes/skills/yss-distributed-id/references/README.md

@@ -1,51 +0,0 @@
-# 参考资料
-
-本文档详细介绍了 `yss-component-distributed-id` 框架的核心组件和实现原理。
-
-## 核心类 (Core Classes)
-
-### 1. AutoIdInterceptor.java
-**位置**: `../assets/AutoIdInterceptor.java`
-
-MyBatis 拦截器，是实现自动 ID 注入的核心。
-
-**拦截逻辑**:
-- **拦截点**: `StatementHandler.prepare` 方法。
-- **判断条件**: 仅拦截 `INSERT` 语句。
-- **处理流程**:
-  1. 获取 SQL 绑定的参数对象 (`parameterObject`)。
-  2. 支持处理单对象、`List`、`Array` 和 `Map` (MyBatis 多参数封装)。
-  3. 遍历参数对象的实体类，检查是否有 `@Entity` (JPA) 或 `@TableName` (MP) 注解。
-  4. 扫描实体字段，查找 `@GeneratedValue` 或 `@TableId` 注解。
-  5. 根据注解指定的策略 (`segment`, `snowflake`, `cosid_segment` 等)，调用对应的 ID 生成器获取 ID。
-  6. 通过反射将 ID 设置到实体的相应字段中。
-
-### 2. EnableDistributedId.java
-**位置**: `../assets/EnableDistributedId.java`
-
-开启分布式 ID 功能的注解。
-
-**属性**:
-- `autoRegister`: 是否自动注册配置，默认为 `true`。
-- `cosid`: 是否开启 CosId 模式，默认为 `false` (即默认使用 Leaf 模式)。
-
-**作用**:
-- 导入 `LeafDataSourceConfiguration` 和 `EnableDistributedImportSelector`，从而根据配置加载相应的 Bean。
-
-### 3. LeafConf.java
-**位置**: `../assets/LeafConf.java`
-
-Leaf 模式的配置类，对应 `spring.leaf` 配置项。
-
-**属性**:
-- `leafSegmentEnable`: 是否开启号段模式。
-- `leafSnowflakeEnable`: 是否开启雪花算法模式。
-
-## ID 生成策略详解
-
-| 策略名称 | 依赖组件 | 描述 | 适用场景 |
-| :--- | :--- | :--- | :--- |
-| **Leaf Segment** | DB (MySQL) | 基于数据库号段，每次从 DB 获取一个号段到内存，高性能，ID 趋势递增。 | 大多数业务场景，高可用要求高。 |
-| **Leaf Snowflake** | Zookeeper | 基于 Twitter 雪花算法，依赖 ZK 进行 WorkerID 管理。 | 对 ID 生成速度要求极高，且不依赖 DB 的场景。 |
-| **CosId Segment** | DB (MySQL) | CosId 的号段模式实现，支持更丰富的配置（如步长动态调整）。 | 需要 CosId 特性或作为 Leaf 的替代方案。 |
-| **UUID** | JDK | 标准 UUID。 | 无需有序、不关心存储空间的场景。 |

package/template/.hermes/skills/yss-distributed-id/references/source-index.md

@@ -1,86 +0,0 @@
-# yss-distributed-id Source Index
-
-Generated: 2026-08-17T12:03:37.436Z
-Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
-Source worktree: `dirty`
-Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
-
-This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
-
-Paths below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using `YSS_SOURCE_ROOT`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.
-
-## Component Path Hints
-
-- `yss-microservice-components/yss-component-distributed-id` (existed when indexed)
-- `yss-microservice-components/yss-component-leaf` (existed when indexed)
-
-## Documentation Files
-
-- `yss-microservice-components/yss-component-distributed-id/readme.md`
-- `yss-microservice-components/yss-component-leaf/README.md`
-- `yss-microservice-components/yss-component-leaf/TECHNICAL_DESIGN.md`
-
-## Maven Modules
-
-- `yss-microservice-components/yss-component-distributed-id`
-- `yss-microservice-components/yss-component-leaf`
-- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-feign`
-- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc-lib`
-- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc`
-- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-rest`
-
-## Key Java Entry Points
-
-- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/EnableDistributedId.java`
-- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/EnableDistributedImportSelector.java`
-- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/ApplicationContextHelper.java`
-- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/SegmentContextHelper.java`
-- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/SnowflakeContextHelper.java`
-- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/config/DistributedIdInjectionModeGuard.java`
-- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/config/DistributedIdProperties.java`
-- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/config/LeafConf.java`
-- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/config/LeafDataSourceConfiguration.java`
-- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/config/LeafDatabaseType.java`
-- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/config/LeafSegmentProperties.java`
-- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/config/MissingTagPolicy.java`
-- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/config/SnowflakeProperties.java`
-- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/exception/LeafIdErrorCode.java`
-- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/exception/LeafIdException.java`
-- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/exception/LeafServerException.java`
-- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/health/LeafSegmentHealth.java`
-- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/inf/leaf/common/PropertyFactory.java`
-- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/inf/leaf/common/Result.java`
-- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/inf/leaf/common/Status.java`
-- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/inf/leaf/segment/dao/IDAllocMapper.java`
-- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/inf/leaf/segment/model/LeafAlloc.java`
-- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/inf/leaf/snowflake/SnowflakeNodeIdentity.java`
-- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/inf/leaf/snowflake/SnowflakeNodeIdentityResolver.java`
-- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/metrics/LeafSegmentMetrics.java`
-- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/mybatis/AutoIdInterceptor.java`
-- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/mybatis/DistributedIdIdentifierGenerator.java`
-- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-feign/src/main/java/com/yss/cloud/leaf/conf/YssCloudLeafAutoConfiguration.java`
-- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-feign/src/main/java/com/yss/cloud/leaf/context/RestGenIdContextHelper.java`
-- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-feign/src/main/java/com/yss/cloud/leaf/feign/YssIdGenFeign.java`
-- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-feign/src/main/java/com/yss/cloud/leaf/mybatis/FeignAutoIdInterceptor.java`
-- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc-lib/src/main/java/com/yss/cloud/grpc/protobuf/GenerateUniqueIdRequest.java`
-- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc-lib/src/main/java/com/yss/cloud/grpc/protobuf/GenerateUniqueIdRequestOrBuilder.java`
-- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc-lib/src/main/java/com/yss/cloud/grpc/protobuf/GenerateUniqueIdResponse.java`
-- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc-lib/src/main/java/com/yss/cloud/grpc/protobuf/GenerateUniqueIdResponseOrBuilder.java`
-- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc-lib/src/main/java/com/yss/cloud/grpc/protobuf/IdGenType.java`
-- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc-lib/src/main/java/com/yss/cloud/grpc/protobuf/UniqueIdProto.java`
-- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc-lib/src/main/java/com/yss/cloud/grpc/protobuf/UniqueIdServiceGrpc.java`
-- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc-lib/src/main/java/com/yss/cloud/leaf/context/GrpcClientService.java`
-- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc-lib/src/main/java/com/yss/cloud/leaf/context/GrpcGenIdContextHelper.java`
-- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc/src/main/java/com/yss/cloud/leaf/conf/YssCloudLeafAutoConfiguration.java`
-- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc/src/main/java/com/yss/cloud/leaf/service/UniqueIdService.java`
-- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-rest/src/main/java/com/yss/cloud/leaf/conf/YssLeafRestConfiguration.java`
-- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-rest/src/main/java/com/yss/cloud/leaf/controller/IdGenController.java`
-- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-rest/src/main/java/com/yss/cloud/leaf/controller/LeafIdRestResponseFactory.java`
-- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-rest/src/main/java/com/yss/cloud/leaf/health/LeafSegmentHealthIndicator.java`
-- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-rest/src/main/java/com/yss/cloud/leaf/health/LeafSnowflakeHealthIndicator.java`
-
-## Recommended Next Reads
-
-- Start with the documentation files above when learning component usage.
-- Search the key Java entry points for annotations, auto configuration, properties, aspects, interceptors, handlers, and result objects before changing application code.
-- Prefer existing component extension points over rewriting framework logic in business modules.

package/template/.hermes/skills/yss-domain/SKILL.md

@@ -1,69 +0,0 @@
----
-name: yss-domain
-description: 用于构建或重构 YSS 领域层代码。当用户要求设计聚合、Entity、Domain Gateway、领域规则、状态流转或先做领域建模再补持久层时调用。
----
-
-# yss-domain
-
-这是一个领域实现 skill。核心目标是消费已批准的战术模型，将领域行为落实为代码；战术模型的设计与批准由 `yss-tactical-design` 和 `yss-product-lifecycle` 负责。
-
-本 skill 在新脚手架链路只支持 `target-domain-model`。`core/client/repository`、贫血对象和 VO 型 Gateway 对该链路均为 `unsupported`，不提供旧架构分支。
-
-## 何时使用
-
-- 用户要求先做 Domain、先抽象实体或聚合。
-- 用户要补 `Entity`、`Gateway`、领域规则或状态机。
-- 用户给出页面流程、业务规则、DDL，希望先沉淀领域模型。
-
-## 不适用
-
-- 只生成持久层时，优先 `yss-repository`。
-- 只生成 Controller 时，优先 `yss-web-controller`。
-- 只初始化项目骨架时，优先 `yss-ddd-scaffold-generator`。
-
-## 工作方式
-
-1. 先读取批准且版本当前的 tactical-design contract 和 Slice Implementation Contract。
-2. 数据库字段只做补充，不直接决定领域对象结构。
-3. 按合同实现领域行为、状态机、不变量和 Gateway 边界。
-4. 规则不清晰或模型需要扩展时，返回 `new_impacts` / `drift` 并停止，不要静默猜测。
-
-## 产物范围
-
-- `domain/{segment}/model/*Entity.java`
-- `domain/{segment}/gateway/*Gateway.java`
-- DTO/VO 属于 client/web 契约，转交 `yss-dto` / `yss-web-controller`；Domain skill 不顺带生成。
-
-## 建模约束
-
-- Domain 层不依赖 Repository、Mapper、Controller。
-- 领域行为放在模型方法，不要放在 Web 层。
-- Gateway 只暴露领域能力，不暴露持久化细节。
-- 对关键状态流转给出明确方法，如 `publish()`、`cancel()`、`terminate()`。
-- 明确 Aggregate Root、Entity identity、Value Object、不变量、Domain Event 和一致性边界；没有业务行为时不要伪造富领域模型。
-- 发现旧架构时停止套用新脚手架合同并返回 `unsupported`；旧项目继续按原工程维护，现代化改造单独立项。
-
-## 质量要求
-
-- 命名体现业务语义，不照抄表名缩写。
-- 生成代码应可编译，且没有跨层依赖泄漏。
-- 对不确定规则写出假设或 TODO，不要伪装成已确认事实。
-
-## 协同顺序
-
-- 需要用例编排时，再接 `yss-application`
-- 需要持久层时，再接 `yss-repository`
-- 需要 Web 层时，再接 `yss-web-controller`
-- 需要完整工程时，先 `yss-ddd-scaffold-generator`
-
-## 分层开发规范
-
-脚手架生成或进入 Domain 实现前，必须加载 `references/domain-layer-guide.md`：其中定义 Aggregate、Domain Gateway、Domain Error、依赖门禁与旧架构 `unsupported` 边界；HTTP DTO/VO 明确不属于 Domain。
-
-## 阶段 7 合同
-
-- 只消费生命周期已批准的 `Slice Implementation Contract` 和当前 `work_unit`；不得扩大 `allowed_write_paths`。
-- `Slice Implementation Contract` 必须引用批准且版本当前的 `tactical_design_ref`；不得在实现阶段重新批准或替换聚合、不变量和一致性策略。
-- 领域规则、状态机和不变量必须使用 `behavior-tdd`，先形成失败测试，再实现最小行为。
-- 完成后按 `yss-router/references/yss-skill-execution-result.md` 返回统一 `YSS Skill Execution Result`：changed files、领域/测试证据、实际验证结果、偏离和新增影响。
-- 发现新 API、权限、状态机、数据模型或架构影响时填入 `new_impacts` 并暂停，不得静默扩张切片。

package/template/.hermes/skills/yss-domain/agents/openai.yaml

@@ -1,5 +0,0 @@
-version: 1
-interface:
-  display_name: "YSS Domain"
-  short_description: "领域建模、聚合根、规则与网关设计实践落地标准化规范"
-  default_prompt: "Use $yss-domain to design aggregates, entities, domain gateways, and business rules for a YSS domain model."

package/template/.hermes/skills/yss-domain/references/domain-layer-guide.md

@@ -1,99 +0,0 @@
-# YSS Domain Target Profile 指南
-
-本指南只定义新 DDD `target-domain-model`。历史 DTO/VO 型 Gateway、`core/client/repository` 和贫血对象均为 `unsupported`，不存在旧架构 Profile 或迁移分支。
-
-## 1. Domain 所有权
-
-Domain 只拥有：
-
-- Aggregate Root、Entity、Value Object。
-- 领域行为、不变量、状态转换和 Domain Event。
-- 聚合持久化及外部领域能力所需的 Gateway/Port。
-- 稳定的领域错误标识与错误参数。
-
-Domain 不拥有：
-
-- HTTP Cmd/Query/VO、YSS `PageQuery` / `PageResult`。
-- Repository PO、Mapper、SQL、Controller。
-- HTTP status、YSS Result 包装或公开错误消息。
-
-## 2. 包结构
-
-```text
-{base_package}.domain.{segment}
-├── model
-├── gateway
-├── service
-└── event
-```
-
-DTO/VO 位于 `{base_package}.rest.dto`。独立 client Maven module 对当前 Target Profile 为 `unsupported`；不得放回 Domain module。
-
-## 3. Aggregate 与行为
-
-- Aggregate Root 是一致性边界，不按表数量机械拆分。
-- Entity identity 使用明确类型；Value Object 按值相等并尽量不可变。
-- 对外暴露业务动作，例如 `publish()`、`cancel()`，不要让 Application 任意修改状态字段。
-- 每个批准不变量必须有 `behavior-tdd` 测试；测试通过聚合公开方法观察结果。
-- 没有真实行为时保持简单模型，不为了“看起来像 DDD”制造空 Domain Service。
-
-## 4. Gateway
-
-Gateway 描述领域能力，只交换 Domain Model、领域值和领域标识。例如：
-
-```java
-package com.yss.quality.domain.template.gateway;
-
-import com.yss.quality.domain.template.model.QualityTemplate;
-import com.yss.quality.domain.template.model.QualityTemplateId;
-import java.util.Optional;
-
-public interface QualityTemplateGateway {
-    Optional<QualityTemplate> findById(QualityTemplateId id);
-    void save(QualityTemplate template);
-}
-```
-
-禁止在 Domain Gateway 中出现：
-
-- `*AddCmd`、`*UpdateCmd`、HTTP request。
-- `*VO`、`PageResult`、Repository PO。
-- MyBatis、Spring MVC、Jackson、Swagger 类型。
-
-分页、列表和投影查询由 Application Query Port 定义，Infrastructure 实现。
-
-## 5. Domain Error
-
-领域错误携带稳定标识和参数，不决定 HTTP 行为：
-
-```java
-public final class QualityTemplateNameConflict extends RuntimeException {
-    private final String templateName;
-
-    public QualityTemplateNameConflict(String templateName) {
-        super("quality-template-name-conflict");
-        this.templateName = templateName;
-    }
-
-    public String templateName() {
-        return templateName;
-    }
-}
-```
-
-Web Exception Translator 再将它映射为批准的状态码、错误码和消毒消息。Domain 不直接依赖 YSS `BizException`。
-
-## 6. 依赖门禁
-
-生成工程的 ArchUnit 规则必须证明：
-
-- Domain 不依赖 Application、Infrastructure、Repository 或 Web。
-- Domain 不依赖 YSS DTO/Exception、Jackson、Swagger 或 Validation。
-- 负例 fixture 中的 Domain → Web DTO 引用会使验证失败。
-
-## 7. 生命周期证据
-
-- 消费批准且当前的 Tactical Design 与 Slice Implementation Contract。
-- 返回 YSS Skill Execution Result，包含 Domain 文件、行为测试、ArchUnit 结果及实际 `./mvnw ...` 证据。
-- 新聚合、不变量、状态机或跨上下文影响进入 `new_impacts` 并暂停。
-- 检测到旧架构时返回 `unsupported`；如需现代化，退出 scaffold 工作流并单独立项评估。

package/template/.hermes/skills/yss-dto/SKILL.md

@@ -1,86 +0,0 @@
----
-name: yss-dto
-description: Use when YSS `Result`, `SingleResult`, `MultiResult`, `PageResult`, `PageQuery`, `CommandDTO`, `QueryDTO`, pagination, or response-wrapper boundaries are involved.
----
-
-# yss-dto
-
-用于处理 `yss-component-dto` 的使用规范和代码接入。
-
-本 skill 同时负责把中台 DTO 映射到公开 HTTP/JSON 边界。`references/openapi-wire-profile.yaml` 是可复用的机器可读映射源；OpenAPI 治理和 Draft Review 必须消费它，不得各自复制一份 wrapper 或分页字段表。
-
-## 何时使用
-
-- 用户要定义新的分页查询对象。
-- 用户要统一接口返回结构。
-- 用户提到 `Result`、`PageQuery`、`CommandDTO`、`QueryDTO`。
-- 用户在排查分页参数、返回结构或 DTO 继承不一致问题。
-
-## 工作方式
-
-1. 优先沿用项目现有 DTO 体系，不重复造返回包装类。
-2. 涉及真实类名、返回结构、分页字段或排障时，先读 `references/source-index.md`，再定位源码或文档。
-3. 新 Target Profile 的 canonical 包固定为 `com.yss.cloud.dto.result`；`com.yss.cloud.dto.response` 为 `unsupported`，不得在新契约或脚手架输出中引入。检测到旧包时只报告边界，不自动改写；旧项目现代化须单独立项。
-4. 需要设计或审查 API 时，先校验 `references/openapi-wire-profile.yaml`，再把 endpoint 的具体 DTO/VO schema 组合到 wrapper；Java 泛型不是 OpenAPI schema。
-5. 只围绕当前 DTO 结构回答，不泛化到整个微服务理论。
-
-## 源码索引
-
-- 源码位置不要假设固定目录；先按 `yss-source-index/references/source-location.md` 定位。
-- 当前技能索引：`references/source-index.md`
-- OpenAPI wire profile：`references/openapi-wire-profile.yaml`
-- 重点源码入口通常包括 `CommandDTO`、`QueryDTO`、`PageQuery`、`PageRequestFactory`、`Result`、`SingleResult`、`MultiResult`、`PageResult`。
-
-当组件源码变化后，用 `yss-source-index` 刷新索引；刷新或读取前先按源码定位策略确认真实位置。
-
-## 使用规则
-
-- 写操作参数优先继承 `CommandDTO`。
-- Application/Infrastructure 内部读参数可按项目 Profile 使用 `QueryDTO` 或 `PageQuery`。
-- 公开 HTTP Page Request 默认不继承 `PageQuery`，只复制冻结 OpenAPI 允许的分页字段，再由 WebConvertor 转为 Application Query；避免继承的 `offset`、`needTotalCount`、`tempTotalCount` 进入绑定面。
-- Controller 返回优先使用项目既有的 `Result` 或派生结果对象。
-- 单对象返回优先 `SingleResult`，列表返回优先 `MultiResult`，分页返回优先 `PageResult`，前提是当前项目已采用这套体系。
-- 三种泛型结果要求 `T extends Serializable`；生成的 VO/响应类型必须满足该编译约束。
-- OpenAPI 响应以 `YssResultMeta` 表达公共字段，并用 `allOf` 叠加 endpoint-specific `data` / page 字段；每个响应声明 `x-yss-response-wrapper: SingleResult|MultiResult|PageResult`，不得把 `SingleResult<T>` 文字写成 schema。
-- wire shape 不是 Java 字段清单：`success` 为 boolean，`dataType` 为 `string|null`，`code` 只允许 `string|integer|null`；不得把全局 `code` 放宽为任意 object。
-- `MultiResult.data` 和 `PageResult.data` 对外是数组，空值按 `[]` 建模；`SingleResult.data` 按 endpoint schema 建模并显式处理 nullability。
-- `PageResult` 当前稳定公共字段为 `totalCount/pageSize/pageIndex/data[]`；`totalPages` 是计算 getter，只有目标 HTTP mapper / contract fixture 证明后才能进入具体契约。
-- `PageQuery` 客户端输入只允许 `pageIndex/pageSize/orderBy/orderDirection/groupBy`（后四项按 profile 的 optional / whitelist 规则）；`orderDirection` 只能是 `ASC|DESC`。`offset`、`needTotalCount`、`tempTotalCount` 是计算或内部协作字段，禁止成为客户端输入。
-- `buildSuccess(...)` 各重载设置 code 的行为并不一致；冻结契约必须测试 `success/code/message/tips/dataType`、nullability 和三种 data shape，不能只测试 data。
-- Java getter、Lombok、`@JsonIgnore` 或默认 Jackson 结果都不是目标 HTTP wire fact；冻结前必须记录 mapper identity、代表性序列化 fixture 和 contract-test / 等价 HTTP 证据。
-- DTO 只表达接口契约，不承载 Repository PO 或领域对象的持久化细节。
-
-## 检查清单
-
-- 分页字段名是否和框架约定一致。
-- `orderBy` / `groupBy` 是否经过 Repository 白名单映射，禁止直接拼接 SQL。
-- Application Query Port / Infrastructure 是否收到批准的分页语义；Domain Gateway 不接收 `PageQuery`。
-- 新增 DTO 是否与现有序列化和校验方式兼容。
-- 返回结构是否和前端或上游调用方契约一致。
-- 是否通过 `scripts/verify-yss-dto-openapi-profile`，并引用 profile 版本。
-- wrapper extension、`YssResultMeta`、`allOf`、具体 data schema 和方向性是否逐 endpoint 对齐。
-- 是否有针对 `offset` / `needTotalCount` / `tempTotalCount` 的负向断言，以及对 `totalPages` 的目标 mapper 证据。
-- Controller、Application Service、Domain、Repository 之间是否存在 DTO/VO/DO/PO 混穿。
-- 前端 Orval 或调用方是否依赖当前返回包装结构。
-
-## 修改约束
-
-- 不要在一个项目里混用多套返回包装类。
-- 不要新建与 `PageQuery` 含义重叠的分页基类。
-- 不要把 `com.yss.cloud.dto.response` 作为新 API 的 canonical 包，也不要从 Java getter 机械生成 wire schema。
-- 不要把 `offset`、`needTotalCount`、`tempTotalCount` 作为客户端分页输入；不要无证据把 `totalPages` 写入所有分页响应。
-- 若项目已有 `SingleResult`、`PageResult`、`MultiResult` 体系，优先保持一致。
-
-## 按需读取
-
-- 源码索引：`references/source-index.md`
-- DTO 基类示例：`assets/CommandDTO.java`、`assets/QueryDTO.java`
-- 分页基类：`assets/PageQuery.java`
-- 返回结构：`assets/Result.java`
-- HTTP/JSON 映射：`references/openapi-wire-profile.yaml`
-
-## 阶段 7 合同
-
-- DTO/VO 必须消费冻结 OpenAPI/no-impact record 和批准合同，写入合同允许路径。
-- POJO 样板可 `controlled-generation`；校验、权限输入、错误结构和序列化行为必须由对应 `behavior-tdd` 工作单元覆盖。
-- 必须加载合同要求的 `lombok`、`mapstruct` 和 `alibaba-java-code-style`，并按统一 `YSS Skill Execution Result` 返回文件、契约测试和偏离。

package/template/.hermes/skills/yss-dto/agents/openai.yaml

@@ -1,5 +0,0 @@
-version: 1
-interface:
-  display_name: "YSS DTO"
-  short_description: "统一响应、分页查询、Command 与 DTO 设计规范"
-  default_prompt: "Use $yss-dto to define YSS-style DTOs, page queries, commands, unified response models, and their OpenAPI HTTP/JSON wire shapes."

package/template/.hermes/skills/yss-dto/assets/CommandDTO.java

@@ -1,8 +0,0 @@
-package com.yss.cloud.dto;
-
-import java.io.Serializable;
-
-public abstract class CommandDTO implements Serializable {
-
-  private static final long serialVersionUID = 1L;
-}

package/template/.hermes/skills/yss-dto/assets/PageQuery.java

@@ -1,133 +0,0 @@
-package com.yss.cloud.dto.page;
-
-import com.fasterxml.jackson.annotation.JsonIgnore;
-import com.yss.cloud.dto.QueryDTO;
-
-public class PageQuery extends QueryDTO {
-
-  private static final long serialVersionUID = 1L;
-
-  public static final String ASC = "ASC";
-
-  public static final String DESC = "DESC";
-
-  private static final int DEFAULT_PAGE_SIZE = 10;
-  /**
-   * 每页显示
-   * @mock 10
-   */
-  private int pageSize = DEFAULT_PAGE_SIZE;
-
-  /**
-   * 当前页
-   * @mock 1
-   */
-  private int pageIndex = 1;
-
-  /**
-   * 排序字段
-   * @mock id
-   */
-  private String orderBy;
-
-  /**
-   * 默认倒序
-   * @mock DESC
-   */
-  private String orderDirection = DESC;
-
-  /** 分组字段 */
-  private String groupBy;
-
-  /**
-   * 是否需要总数
-   * @apiNote 暂时未实现
-   * @mock true
-   */
-  @JsonIgnore
-  private boolean needTotalCount = true;
-
-  /**
-   * 总数dto临时字段，忽略即可
-   * @mock 0
-   */
-  @JsonIgnore
-  private long tempTotalCount = 0;
-
-  public int getPageIndex() {
-    return Math.max(pageIndex, 1);
-  }
-
-  public PageQuery setPageIndex(int pageIndex) {
-    this.pageIndex = pageIndex;
-    return this;
-  }
-
-  public int getPageSize() {
-    if (pageSize < 1) {
-      pageSize = DEFAULT_PAGE_SIZE;
-    }
-    return pageSize;
-  }
-
-  public PageQuery setPageSize(int pageSize) {
-    if (pageSize < 1) {
-      pageSize = DEFAULT_PAGE_SIZE;
-    }
-    this.pageSize = pageSize;
-    return this;
-  }
-
-  public int getOffset() {
-    return (getPageIndex() - 1) * getPageSize();
-  }
-
-  public String getOrderBy() {
-    return orderBy;
-  }
-
-  public PageQuery setOrderBy(String orderBy) {
-    this.orderBy = orderBy;
-    return this;
-  }
-
-  public String getOrderDirection() {
-    return orderDirection;
-  }
-
-  public PageQuery setOrderDirection(String orderDirection) {
-    if (ASC.equalsIgnoreCase(orderDirection) || DESC.equalsIgnoreCase(orderDirection)) {
-      this.orderDirection = orderDirection;
-    }
-    return this;
-  }
-
-  public long getTempTotalCount() {
-    return tempTotalCount;
-  }
-
-  public void setTempTotalCount(long tempTotalCount) {
-    this.tempTotalCount = tempTotalCount;
-  }
-
-  public String getGroupBy() {
-    return groupBy;
-  }
-
-  public void setGroupBy(String groupBy) {
-    this.groupBy = groupBy;
-  }
-
-  public boolean isNeedTotalCount() {
-    return needTotalCount;
-  }
-
-  public void setNeedTotalCount(boolean needTotalCount) {
-    this.needTotalCount = needTotalCount;
-  }
-
-  @Override
-  public String toString() {
-    return "PageQuery(" + "pageSize=" + pageSize + ", pageIndex=" + pageIndex + ')';
-  }
-}

package/template/.hermes/skills/yss-dto/assets/QueryDTO.java

@@ -1,6 +0,0 @@
-package com.yss.cloud.dto;
-
-public abstract class QueryDTO extends CommandDTO {
-
-  private static final long serialVersionUID = 1L;
-}

package/template/.hermes/skills/yss-dto/assets/Result.java

@@ -1,105 +0,0 @@
-package com.yss.cloud.dto.result;
-
-import java.io.Serializable;
-
-/**
- * @author zhudaoming
- */
-public class Result implements Serializable {
-
-  private static final long serialVersionUID = 2405172041950251807L;
-
-  private static final String DEFAULT_MESSAGE = "数据返回正常";
-  private static final String DEFAULT_TIPS = "信息返回正常";
-
-  /** 状态 */
-  private boolean success;
-  /** 返回数据格式 */
-  private String dataType;
-  /** 返回状态码 */
-  private Object code;
-  /** 返回消息 */
-  private String message = DEFAULT_MESSAGE;
-  /** 返回提示消息 */
-  private String tips = DEFAULT_TIPS;
-  public Object getCode() {
-    return code;
-  }
-
-  public Result setCode(Object code) {
-    this.code = code;
-    return this;
-  }
-
-  public String getMessage() {
-    return message;
-  }
-
-  public Result setMessage(String message) {
-    this.message = message;
-    return this;
-  }
-
-  public String getTips() {
-    return tips;
-  }
-
-  public void setTips(String tips) {
-    this.tips = tips;
-  }
-
-  public boolean isSuccess() {
-    return success;
-  }
-
-  public void setSuccess(boolean success) {
-    this.success = success;
-  }
-
-  public String getDataType() {
-    return dataType;
-  }
-
-  public void setDataType(String dataType) {
-    this.dataType = dataType;
-  }
-
-  public static Result buildSuccess() {
-    Result response = new Result();
-    response.setSuccess(true);
-    response.setCode("DM-A0001");
-    return response;
-  }
-
-  public static Result buildSuccess(String message) {
-    Result response = new Result();
-    response.setSuccess(true);
-    response.setMessage(message);
-    return response;
-  }
-  public static Result buildSuccess(String code,String message) {
-    Result response = new Result();
-    response.setSuccess(true);
-    response.setCode(code);
-    response.setMessage(message);
-    return response;
-  }
-  public static Result buildFailure(String message) {
-    Result response = new Result();
-    response.setSuccess(false);
-    response.setMessage(message);
-    return response;
-  }
-  public static Result buildFailure(String errCode,String message) {
-    Result response = new Result();
-    response.setSuccess(false);
-    response.setCode(errCode);
-    response.setMessage(message);
-    return response;
-  }
-  @Override
-  public String toString() {
-    return "Response [success=" + success + "]";
-  }
-
-}