create-yss-spec 1.0.0

package/template/.codex/skills/yss-distributed-id/assets/AutoIdInterceptor.java

@@ -0,0 +1,246 @@
+package com.yss.cloud.sankuai.mybatis;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import com.yss.cloud.exception.BizException;
+import com.yss.cloud.sankuai.CosidSegmentContextHelper;
+import com.yss.cloud.sankuai.GenerationTypeSeq;
+import com.yss.cloud.sankuai.SegmentContextHelper;
+import com.yss.cloud.sankuai.SnowflakeContextHelper;
+import lombok.extern.slf4j.Slf4j;
+import org.apache.commons.lang3.StringUtils;
+import org.apache.ibatis.binding.BindingException;
+import org.apache.ibatis.binding.MapperMethod;
+import org.apache.ibatis.executor.statement.StatementHandler;
+import org.apache.ibatis.mapping.BoundSql;
+import org.apache.ibatis.plugin.Interceptor;
+import org.apache.ibatis.plugin.Intercepts;
+import org.apache.ibatis.plugin.Invocation;
+import org.apache.ibatis.plugin.Signature;
+import org.springframework.util.ObjectUtils;
+import org.springframework.util.ReflectionUtils;
+
+import javax.persistence.Entity;
+import javax.persistence.GeneratedValue;
+import javax.persistence.Table;
+import java.lang.reflect.Field;
+import java.sql.Connection;
+import java.util.*;
+
+@Intercepts(
+    {
+        @Signature(type = StatementHandler.class, method = "prepare", args = {Connection.class, Integer.class})
+    }
+)
+@Slf4j
+public class AutoIdInterceptor implements Interceptor {
+
+    @Override
+    public Object intercept(Invocation invocation) throws Throwable {
+        StatementHandler statementHandler = (StatementHandler) invocation.getTarget();
+        BoundSql boundSql = statementHandler.getBoundSql();
+        String boundSqlStr = boundSql.getSql();
+        if (StringUtils.startsWithIgnoreCase(StringUtils.trim(boundSqlStr),"INSERT")){
+            processInsertStatement(statementHandler);
+        }
+
+        return invocation.proceed();
+    }
+
+    /**
+     * 1.处理插入的情况
+     *
+     * @apiNote 1.处理新增insert
+     * @param statementHandler 句柄
+     */
+    private void processInsertStatement(StatementHandler statementHandler) {
+        BoundSql boundSql = statementHandler.getBoundSql();
+        Object parameterObject = boundSql.getParameterObject();
+
+        if (parameterObject != null) {
+            processParameterObject(parameterObject);
+        }
+    }
+
+    /**
+     * 处理参数对象
+     *
+     * @apiNote 2.处理参数对象 mapper->entityList,plus->param1
+     * @param parameterObject 参数对象
+     */
+    private void processParameterObject(Object parameterObject) {
+        if (parameterObject instanceof MapperMethod.ParamMap<?>){
+            // 获取批量实体对象，若为空则为single 参数对象
+            Object entityList = null;
+            try {
+                entityList = ((MapperMethod.ParamMap<?>) parameterObject).get("entityList");
+            }catch (BindingException e){
+                log.warn("non entityList. info -> {}",e.getLocalizedMessage());
+            }
+            // 兼容mybatis默认参数 集合的场景
+            if (ObjectUtils.isEmpty(entityList)){
+                try {
+                    entityList = ((MapperMethod.ParamMap<?>) parameterObject).get("collection");
+                }catch (BindingException e){
+                    log.warn("non entityList & non collection. info -> {}",e.getLocalizedMessage());
+                }
+            }
+            // 兼容mybatis默认参数 数组的场景
+            if (ObjectUtils.isEmpty(entityList)){
+                try {
+                    entityList = ((MapperMethod.ParamMap<?>) parameterObject).get("array");
+                }catch (BindingException e){
+                    log.warn("non entityList & non collection & non array. info -> {}",e.getLocalizedMessage());
+                }
+            }
+            if (ObjectUtils.isEmpty(entityList)){
+                try {
+                    entityList = ((MapperMethod.ParamMap<?>) parameterObject).get("param1");
+                }catch (BindingException e){
+                    log.error("non param1. info -> {}",e.getLocalizedMessage());
+                    throw new BizException("FeignAutoIdInterceptor run error");
+                }
+            }
+            if (entityList instanceof List) {
+                // 批量插入
+                List<?> el = (List<?>) entityList;
+                for (Object entity : el) {
+                    processEntity(entity);
+                }
+            } else  if (entityList.getClass().isArray()) {
+                // 批量插入
+                Object[] array = (Object[]) entityList;
+                for (Object entity : array) {
+                    processEntity(entity);
+                }
+            }else {
+                // 单独插入
+                processEntity(entityList);
+            }
+        } else {
+            // 单独插入
+            processEntity(parameterObject);
+        }
+    }
+
+    /**
+     * 3.处理对象实体
+     *
+     * @apiNote 3.处理对象实体
+     * @param entity 对象实体
+     */
+    private void processEntity(Object entity) {
+        Class<?> entityClass = entity.getClass();
+        if (isEntityClass(entityClass)) {
+            autoIdSet(entity);
+        }
+    }
+
+    /**
+     * 4.自动为实体设置id
+     *
+     * @apiNote 4.自动为实体设置id
+     * @param entity 对象实体
+     */
+    private void autoIdSet(Object entity) {
+        Class<?> entityClass = entity.getClass();
+        List<Field> fields = getAllFields(entityClass);
+        for (Field field : fields) {
+
+            if (field.isAnnotationPresent(GeneratedValue.class)||
+                    field.isAnnotationPresent(TableId.class)) {
+                processGeneratedValue(entity, field);
+            }
+        }
+    }
+
+    /**
+     * 5.设置id字段
+     *
+     * @param entity 实体对象
+     * @param field id字段
+     */
+    private void processGeneratedValue(Object entity, Field field) {
+        String genIdType = getGenIdType(field);
+
+        String tableName = getTableName(entity);
+
+        if (Objects.nonNull(genIdType)&&
+                Objects.nonNull(SegmentContextHelper.LeafConf())&&
+                SegmentContextHelper.LeafConf().isLeafSegmentEnable()&&
+                (genIdType.equals(GenerationTypeSeq.SEGMENT) || genIdType.equals(IdType.AUTO.name()) || genIdType.equals(IdType.ASSIGN_ID.name()))) {
+            long idValue = SegmentContextHelper.nextId(tableName);
+            setFieldValue(entity, field, idValue);
+        } else if (Objects.nonNull(genIdType)&&
+                Objects.nonNull(SnowflakeContextHelper.LeafConf())&&
+                SnowflakeContextHelper.LeafConf().isLeafSnowflakeEnable()
+                &&genIdType.equals(GenerationTypeSeq.SNOWFLAKE) ) {
+            long idValue = SnowflakeContextHelper.nextId();
+            setFieldValue(entity, field, idValue);
+        } else if (Objects.nonNull(genIdType)&&
+                (genIdType.equals(GenerationTypeSeq.UUID)|| genIdType.equals(IdType.ASSIGN_UUID.name()))) {
+            String idValue = UUID.randomUUID().toString();
+            setFieldValue(entity, field, idValue);
+        } else if (Objects.nonNull(genIdType) &&
+                genIdType.equals(GenerationTypeSeq.COSID_SEGMENT)) {
+            long idValue = CosidSegmentContextHelper.nextId(tableName);
+            setFieldValue(entity, field, idValue);
+        }
+    }
+
+    private void setFieldValue(Object entity, Field field, Object value) {
+        field.setAccessible(true);
+        // 如果value为null,则ID生成服务不可用,使用默认规则替代;有值则覆盖
+        if(!Objects.isNull(value)) {
+            if (field.getType() == String.class) {
+                ReflectionUtils.setField(field,entity,String.valueOf(value));
+            } else if (field.getType() == Integer.class) {
+                ReflectionUtils.setField(field,entity,Integer.valueOf(String.valueOf(value)));
+            } else {
+                ReflectionUtils.setField(field,entity,value);
+            }
+        }
+    }
+
+    private boolean isEntityClass(Class<?> clazz) {
+        return clazz.isAnnotationPresent(Entity.class)||clazz.isAnnotationPresent(TableName.class);
+    }
+
+    private String getTableName(Object entity){
+        Table table = entity.getClass().getAnnotation(Table.class);
+        if (Objects.nonNull(table)){
+            return table.name();
+        }
+
+        TableName tableName = entity.getClass().getAnnotation(TableName.class);
+
+        if (Objects.nonNull(tableName)){
+            return tableName.value();
+        }
+
+        return null;
+    }
+    private static List<Field> getAllFields(Class<?> clazz) {
+        List<Field> fields = new ArrayList<>();
+        while (clazz != null) {
+            Collections.addAll(fields, clazz.getDeclaredFields());
+            clazz = clazz.getSuperclass();
+        }
+        return fields;
+    }
+    private String getGenIdType(Field field){
+        GeneratedValue generatedValueAnnotation = field.getAnnotation(GeneratedValue.class);
+
+        if (Objects.nonNull(generatedValueAnnotation)){
+           return generatedValueAnnotation.generator();
+        }
+
+        TableId tableId = field.getAnnotation(TableId.class);
+
+        if (Objects.nonNull(tableId)){
+            return tableId.type().name();
+        }
+        return null;
+    }
+}

package/template/.codex/skills/yss-distributed-id/assets/EnableDistributedId.java

@@ -0,0 +1,25 @@
+package com.yss.cloud;
+
+import com.yss.cloud.sankuai.config.LeafConf;
+import com.yss.cloud.sankuai.config.LeafDataSourceConfiguration;
+import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.context.annotation.Import;
+
+import java.lang.annotation.*;
+
+@Target({ElementType.TYPE})
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@Inherited
+@Import({LeafDataSourceConfiguration.class, EnableDistributedImportSelector.class})
+@EnableConfigurationProperties(LeafConf.class)
+public @interface EnableDistributedId {
+  /**
+   * 默认自动装载leaf配置，设置默认启用状态
+   */
+  boolean autoRegister() default true;
+  /**
+   * 是否启用cosid模式
+   */
+  boolean cosid() default false;
+}

package/template/.codex/skills/yss-distributed-id/assets/LeafConf.java

@@ -0,0 +1,36 @@
+package com.yss.cloud.sankuai.config;
+
+import org.springframework.boot.context.properties.ConfigurationProperties;
+
+@ConfigurationProperties(prefix = "spring.leaf", ignoreInvalidFields = true)
+public class LeafConf {
+  private boolean leafSegmentEnable;
+  private boolean leafSnowflakeEnable;
+
+  public boolean isLeafSegmentEnable() {
+    return leafSegmentEnable;
+  }
+
+  public void setLeafSegmentEnable(boolean leafSegmentEnable) {
+    this.leafSegmentEnable = leafSegmentEnable;
+  }
+
+  public boolean isLeafSnowflakeEnable() {
+    return leafSnowflakeEnable;
+  }
+
+  public void setLeafSnowflakeEnable(boolean leafSnowflakeEnable) {
+    this.leafSnowflakeEnable = leafSnowflakeEnable;
+  }
+
+  @Override
+  public String toString() {
+    return "LeafConf{"
+        + "leafSegmentEnable="
+        + leafSegmentEnable
+        + ", leafSnowflakeEnable="
+        + leafSnowflakeEnable
+        + ", leafSnowflakePort="
+        + '}';
+  }
+}

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

@@ -0,0 +1,51 @@
+# 参考资料
+
+本文档详细介绍了 `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/.codex/skills/yss-distributed-id/references/source-index.md

@@ -0,0 +1,71 @@
+# yss-distributed-id Source Index
+
+Generated: 2026-06-29T16:11:14+00:00
+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.py`. 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`
+- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc-lib`
+- `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/cosid/dao/CosidMapper.java`
+- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/cosid/segment/CusJdbcIdSegmentDistributor.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/CosidSegmentContextHelper.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/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/exception/LeafServerException.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/mybatis/AutoIdInterceptor.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/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-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-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`
+
+## 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/.codex/skills/yss-domain/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: yss-domain
+description: 用于构建或重构 YSS 领域层代码。当用户要求设计聚合、Entity、Domain Gateway、领域规则、状态流转或先做领域建模再补持久层时调用。
+---
+
+# yss-domain
+
+这是一个建模型 skill。核心目标是先把领域语义和边界建立清楚，再落代码。
+
+## 何时使用
+
+- 用户要求先做 Domain、先抽象实体或聚合。
+- 用户要补 `Entity`、`Gateway`、领域规则或状态机。
+- 用户给出页面流程、业务规则、DDL，希望先沉淀领域模型。
+
+## 不适用
+
+- 只生成持久层时，优先 `yss-repository` 或 `yss-db2mybatis`。
+- 只生成 Controller 时，优先 `yss-web-controller`。
+- 只初始化项目骨架时，优先 `yss-ddd-scaffold-generator`。
+
+## 工作方式
+
+1. 先抽业务术语、聚合边界和状态变化。
+2. 数据库字段只做补充，不直接决定领域对象结构。
+3. 先定义领域行为，再决定 Gateway 边界。
+4. 规则不清晰时，保留显式假设，不要静默猜测。
+
+## 产物范围
+
+- `domain/{segment}/model/*Entity.java`
+- `domain/{segment}/gateway/*Gateway.java`
+- 任务明确要求时，可顺带补 `client/dto/cmd`、`client/dto/query`、`client/vo`
+
+## 建模约束
+
+- Domain 层不依赖 Repository、Mapper、Controller。
+- 领域行为放在模型方法，不要放在 Web 层。
+- Gateway 只暴露领域能力，不暴露持久化细节。
+- 对关键状态流转给出明确方法，如 `publish()`、`cancel()`、`terminate()`。
+
+## 质量要求
+
+- 命名体现业务语义，不照抄表名缩写。
+- 生成代码应可编译，且没有跨层依赖泄漏。
+- 对不确定规则写出假设或 TODO，不要伪装成已确认事实。
+
+## 协同顺序
+
+- 需要持久层时，再接 `yss-repository` 或 `yss-db2mybatis`
+- 需要 Web 层时，再接 `yss-web-controller`
+- 需要完整工程时，先 `yss-ddd-scaffold-generator`

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

@@ -0,0 +1,5 @@
+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/.codex/skills/yss-domain-modeling/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: yss-domain-modeling
+description: 用于 YSS 项目在实现前进行 DDD 领域建模。当用户提供 PRD、RDD Spec、OpenAPI、页面流程、业务规则、DDL、元数据或现有代码，希望先识别统一语言、上下文边界、聚合、实体、值对象、领域行为、状态流转、Domain Gateway、领域事件、ADR 和实现 handoff 时调用。
+---
+
+# yss-domain-modeling
+
+这是一个建模前置 skill。目标是在写代码前建立领域语义、边界和规则，并输出可交给 `yss-domain` 等实现型 skill 使用的建模 brief。
+
+## 何时使用
+
+- 用户要求先做 DDD、领域建模、聚合分析、上下文边界或统一语言。
+- 用户提供 PRD、RDD Spec、OpenAPI、页面流程、业务规则、DDL、元数据或现有代码，希望先沉淀领域模型。
+- 用户要求从业务规则推导实体、值对象、领域行为、状态流转、Domain Gateway 或领域事件。
+- 用户要判断某个设计是否应该写 ADR、更新 `CONTEXT.md`，或如何交给后续实现。
+
+## 不适用
+
+- 直接生成 Java Domain 层代码时，使用 `yss-domain`。
+- 从零生成完整多模块后端工程时，使用 `yss-ddd-scaffold-generator`。
+- 只生成 Repository/MyBatis/PO/Mapper 时，使用 `yss-repository`、`yss-db2mybatis` 或 `yss-mybatis`。
+- 只生成 Controller/DTO/VO/Web Convertor 时，使用 `yss-web-controller` 和 `yss-dto`。
+
+## 工作流
+
+1. 先读取输入资料：PRD、RDD Spec、OpenAPI、页面流程、DDL、`CONTEXT.md`、ADR 和现有代码。
+2. 抽取业务术语，识别同义词、歧义词、禁用词和待确认含义。
+3. 划分上下文边界，明确每个上下文负责什么、不负责什么、依赖什么。
+4. 识别聚合、聚合根、实体、值对象、领域服务和领域事件。
+5. 明确不变量、领域行为、状态流转、失败路径和边界条件。
+6. 识别 Domain Gateway：只描述领域需要的能力，不泄漏 Repository、Mapper、SQL 或 Controller 细节。
+7. 判断是否需要更新 `CONTEXT.md`、补充 ADR 或进入人工确认。
+8. 输出实现 handoff，并说明后续应调用 `yss-domain`、`yss-repository`、`yss-web-controller` 等 skill。
+
+## 按需读取
+
+- 建模流程：`references/modeling-workflow.md`
+- 输出模板：`references/modeling-output-template.md`
+- YSS DDD 规则：`references/yss-ddd-rules.md`
+- 实现交接：`references/handoff-to-implementation.md`
+
+## 后续协同
+
+- 需要落 Domain 层代码：把实现 Handoff 交给 `yss-domain`。
+- 需要持久层：在领域模型稳定后接 `yss-repository`、`yss-db2mybatis` 或 `yss-mybatis`。
+- 需要 Web 层：在 API/DTO/VO 边界稳定后接 `yss-web-controller` 和 `yss-dto`。
+- 需要完整工程骨架：先由 `yss-ddd-scaffold-generator` 生成骨架，再回到本 skill 做业务化建模。

package/template/.codex/skills/yss-domain-modeling/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "YSS Domain Modeling"
+  short_description: "Model YSS domains before implementation"
+  default_prompt: "Use $yss-domain-modeling to derive YSS domain aggregates, boundaries, rules, and implementation handoff from PRD/RDD/spec inputs."

package/template/.codex/skills/yss-domain-modeling/references/handoff-to-implementation.md

@@ -0,0 +1,56 @@
+# Handoff To Implementation
+
+Use this reference after the modeling brief is complete.
+
+## To `yss-domain`
+
+Use `yss-domain` when the next task is to create or refactor:
+
+- `domain/{segment}/model/*Entity.java`
+- `domain/{segment}/gateway/*Gateway.java`
+- Domain behavior methods such as `publish()`, `cancel()`, `enable()`, `disable()`, `submit()`, or `approve()`
+- Domain services that coordinate multiple aggregates
+
+Pass the stable parts of the modeling brief: aggregate roots, entities, value objects, invariants, state transitions, gateway candidates, and unresolved assumptions.
+
+## To `yss-repository` / `yss-db2mybatis` / `yss-mybatis`
+
+Use persistence skills only after the domain boundary is stable.
+
+- Use `yss-db2mybatis` when metadata or DDL should generate persistence scaffolding.
+- Use `yss-repository` when implementing Repository, GatewayImpl, PO, and Convertor.
+- Use `yss-mybatis` when the task depends on MyBatis/MyBatis-Plus conventions, BaseRepository, pagination, datasource, or mapper behavior.
+
+Do not let persistence generation redefine aggregate boundaries.
+
+## To `yss-web-controller` / `yss-dto`
+
+Use web and DTO skills when API or adapter boundaries are clear.
+
+- Use `yss-dto` for `CommandDTO`, `QueryDTO`, `PageQuery`, Result, validation, and DTO conventions.
+- Use `yss-web-controller` for Controller, Web Convertor, AddCmd, UpdateCmd, PageQuery, and VO scaffolding.
+
+Keep Web DTOs aligned with OpenAPI and acceptance criteria. Do not move domain rules into Controller.
+
+## To `yss-ddd-scaffold-generator`
+
+Use scaffold generation when the project/module does not exist yet or the user explicitly asks for a full DDD backend service skeleton.
+
+After skeleton generation, return to `yss-domain-modeling` for business-specific modeling before writing detailed domain code.
+
+## Handoff Format
+
+Use this compact handoff:
+
+```md
+## 实现 Handoff
+
+- 推荐下一步 skill: `yss-domain`
+- 稳定模型: <aggregates/entities/value objects>
+- 关键行为: <behaviors/state transitions>
+- Gateway 候选: <gateway names and capabilities>
+- 待确认: <questions>
+- 后续持久层: `yss-repository` / `yss-db2mybatis`
+- 后续 Web 层: `yss-web-controller` / `yss-dto`
+- 人工门禁: <security/data/API decisions>
+```

package/template/.codex/skills/yss-domain-modeling/references/modeling-output-template.md

@@ -0,0 +1,64 @@
+# Modeling Output Template
+
+Use this structure for the final modeling brief. Omit empty optional sections only when they truly do not apply.
+
+## 统一语言
+
+| 术语 | 定义 | 避免使用 | 备注 |
+| --- | --- | --- | --- |
+
+## 上下文边界
+
+| 上下文 | 职责 | 不负责 | 外部依赖 |
+| --- | --- | --- | --- |
+
+## 聚合设计
+
+| 聚合 | 聚合根 | 实体 | 值对象 | 不变量 |
+| --- | --- | --- | --- | --- |
+
+## 领域行为
+
+| 行为 | 所属模型 | 前置条件 | 结果 | 失败场景 |
+| --- | --- | --- | --- | --- |
+
+## 状态流转
+
+| 对象 | 当前状态 | 触发行为 | 目标状态 | 约束 |
+| --- | --- | --- | --- | --- |
+
+## Domain Gateway 候选
+
+| Gateway | 领域需要的能力 | 入参 | 返回 | 备注 |
+| --- | --- | --- | --- | --- |
+
+## 领域服务候选
+
+| 服务 | 使用场景 | 协调对象 | 不应放入实体的原因 |
+| --- | --- | --- | --- |
+
+## 领域事件候选
+
+| 事件 | 触发时机 | 载荷 | 消费方 | 是否必须 |
+| --- | --- | --- | --- | --- |
+
+## ADR 建议
+
+| 决策 | 是否难逆 | 是否有取舍 | 建议 |
+| --- | --- | --- | --- |
+
+## `CONTEXT.md` 更新建议
+
+| 术语 | 新增/修改 | 建议定义 |
+| --- | --- | --- |
+
+## 待确认问题
+
+-
+
+## 实现 Handoff
+
+- 推荐下一步 skill：
+- 建议实现范围：
+- 需要后续调用：
+- 人工门禁：