create-yss-spec 3.3.1 → 3.3.3

package/template/.qoder/skills/yss-audit-log/assets/AuditLogAspect.java

@@ -1,262 +0,0 @@
-package com.yss.cloud.audit.configuration;
-
-import cn.hutool.jwt.JWT;
-import cn.hutool.jwt.JWTUtil;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.databind.ObjectMapper;
-import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
-import com.yss.cloud.audit.AuditLog;
-import com.yss.cloud.audit.subscriber.YssAuditPublishService;
-import com.yss.cloud.dto.audit.message.AuditMessage;
-import com.yss.cloud.dto.audit.message.AuditResourceType;
-import com.yss.cloud.dto.audit.message.EventMessage;
-import com.yss.cloud.dto.user.UserInfo;
-import com.yss.cloud.user.AuthUserInfoUtil;
-import lombok.SneakyThrows;
-import lombok.extern.slf4j.Slf4j;
-import org.aspectj.lang.JoinPoint;
-import org.aspectj.lang.Signature;
-import org.aspectj.lang.annotation.AfterReturning;
-import org.aspectj.lang.annotation.Aspect;
-import org.aspectj.lang.reflect.MethodSignature;
-import org.springframework.beans.factory.annotation.Autowired;
-import org.springframework.cglib.beans.BeanMap;
-import org.springframework.context.expression.EnvironmentAccessor;
-import org.springframework.context.expression.MapAccessor;
-import org.springframework.expression.Expression;
-import org.springframework.expression.ExpressionParser;
-import org.springframework.expression.ParserContext;
-import org.springframework.expression.spel.standard.SpelExpressionParser;
-import org.springframework.expression.spel.support.StandardEvaluationContext;
-import org.springframework.util.StringUtils;
-import org.springframework.web.context.request.RequestContextHolder;
-import org.springframework.web.context.request.ServletRequestAttributes;
-
-import javax.servlet.ServletRequest;
-import javax.servlet.ServletResponse;
-import javax.servlet.http.HttpServletRequest;
-import java.io.File;
-import java.io.InputStream;
-import java.net.NetworkInterface;
-import java.security.Principal;
-import java.time.LocalDateTime;
-import java.util.*;
-import java.util.regex.Matcher;
-import java.util.regex.Pattern;
-import java.util.stream.Collectors;
-
-@Aspect
-@Slf4j
-public class AuditLogAspect {
-    public static final String USER_AGENT = "User-Agent";
-    /**
-     * 引用来源
-     */
-    public static final String REFERER = "Referer";
-    public static final String UNKNOWN = "unknown";
-    private static final ExpressionParser parser = new SpelExpressionParser();
-    /**
-     * 正则表达式，匹配 #{xxx} 格式的变量表达式
-     */
-    private static final Pattern varPattern = Pattern.compile("#\\{[a-zA-Z0-9_\\[\\]\\?\\.]+\\}");
-    @Autowired
-    private YssAuditPublishService yssAuditPublishService;
-    private static final ObjectMapper OM = new ObjectMapper();
-    static {
-        OM.registerModule(new JavaTimeModule());
-        OM.setSerializationInclusion(JsonInclude.Include.NON_NULL);
-    }
-    private static boolean containsPattern(String text) {
-        Matcher matcher = varPattern.matcher(text);
-        return matcher.find();
-    }
-
-    private static String getMacAddr() {
-        try {
-            Enumeration<NetworkInterface> networkInterfaces = NetworkInterface.getNetworkInterfaces();
-            while (networkInterfaces.hasMoreElements()) {
-                NetworkInterface networkInterface = networkInterfaces.nextElement();
-                if (networkInterface.getName().startsWith("en")) {
-                    byte[] macAddress = networkInterface.getHardwareAddress();
-                    if (macAddress != null) {
-                        StringJoiner macAddressBuilder = new StringJoiner("-");
-                        for (byte b : macAddress) {
-                            macAddressBuilder.add(String.format("%02X", b));
-                        }
-                        return macAddressBuilder.toString();
-                    }
-                }
-            }
-        } catch (Exception e) {
-            return "";
-        }
-        return "";
-    }
-
-    @SneakyThrows
-    @AfterReturning(value = "@annotation(com.yss.cloud.audit.AuditLog)&&execution(public * *(..))", returning = "result")
-    public void logAudit(JoinPoint joinPoint, Object result) {
-        Signature signature = joinPoint.getSignature();
-
-        AuditMessage.AuditMessageBuilder builder = AuditMessage.builder();
-        Map<String, Object> referencedResources = new HashMap<>();
-
-        Class<?> declaringType = signature.getDeclaringType();
-        if (signature instanceof MethodSignature) {
-            AuditLog audit = ((MethodSignature) signature).getMethod().getAnnotation(AuditLog.class);
-            if (audit.isNeedArgs()) {
-                referencedResources.put("参数审计", buildLogArgsDetails(joinPoint));
-            }
-            if (audit.isNeedResult()) {
-                referencedResources.put("结果审计", result);
-            }
-            String summary = StringUtils.hasLength(audit.value()) ? audit.value() : audit.summary();
-
-            boolean containsVariableExpression = containsPattern(summary);
-
-            if (containsVariableExpression) {
-                log.info("文本中包含变量表达式。");
-                StandardEvaluationContext context = new StandardEvaluationContext(referencedResources);
-                context.addPropertyAccessor(new MapAccessor());
-                context.addPropertyAccessor(new EnvironmentAccessor());
-                try {
-                    Expression expression = parser.parseExpression(summary, ParserContext.TEMPLATE_EXPRESSION);
-                    summary = expression.getValue(context, String.class);
-                } catch (Exception e) {
-                    log.warn(e.getLocalizedMessage());
-                }
-
-            }
-
-            builder.operation(Objects.isNull(audit.operation())
-                            ? signature.getName()
-                            : audit.operation().getOperationType())
-                    .content(summary)
-                    .resourceType(audit.resource().getResourceType());
-        }
-
-        EventMessage.EventMessageBuilder eventMessageBuilder = EventMessage.builder()
-                .eventId(UUIDGenerator.generateUUID())
-                .serviceName(declaringType.getName())
-                .eventTime(LocalDateTime.now())
-                .userIdentity(AuthUserInfoUtil.currentUserJson())
-                .macAddr(getMacAddr());
-        if (result instanceof Principal){
-            //登录情况获取用户信息
-            BeanMap beanMap = BeanMap.create(result);
-            Object additionalParameters = beanMap.get("additionalParameters");
-            if (Objects.nonNull(additionalParameters)){
-                Map<String,String> additionalParametersMap = (Map<String,String>)additionalParameters;
-                log.info("[登录用户信息] additionalParametersMap=>{}",additionalParametersMap);
-                String idToken = additionalParametersMap.get("id_token");
-                final JWT jwt = JWTUtil.parseToken(idToken);
-                UserInfo userInfo = new UserInfo();
-                userInfo.setUserName(String.valueOf(jwt.getPayload("sub")));
-
-                String loginDisplayName = Objects.nonNull(jwt.getPayload("loginDisplayName"))?
-                        String.valueOf(jwt.getPayload("loginDisplayName")):
-                        String.valueOf(jwt.getPayload("sub"));
-                userInfo.setLoginDisplayName(loginDisplayName);
-                eventMessageBuilder.userIdentity(OM.writeValueAsString(userInfo));
-            }
-
-        }
-        try{
-            HttpServletRequest request = ((ServletRequestAttributes) RequestContextHolder.currentRequestAttributes()).getRequest();
-            String realIp = getIpAddr(request);
-            eventMessageBuilder.userAgent(request.getHeader(USER_AGENT))
-                    .sourceIpAddress(realIp)
-                    .eventName(signature.getName())
-                    .requestUrl(request.getRequestURL().toString())
-                    .eventSource(Objects.isNull(request.getHeader(REFERER)) ? request.getRequestURL().toString() : request.getHeader(REFERER));
-        }catch (Exception e){
-            log.warn("非rest请求无法获取客户端ip");
-            eventMessageBuilder.userAgent("")
-                    .sourceIpAddress("")
-                    .eventName(signature.getName())
-                    .requestUrl("")
-                    .eventSource("");
-        }
-
-        AuditMessage auditMessage = builder
-                .eventMessage(
-                        eventMessageBuilder.build()
-                )
-                .referencedResources(referencedResources)
-                .build();
-
-
-        auditMessage.setResourceName(AuditResourceType.valueOf(auditMessage.getResourceType()).getResourceName());
-
-        yssAuditPublishService.publish(auditMessage);
-    }
-
-    /**
-     * 辅助方法，构建日志详情
-     *
-     * @param joinPoint 参数点
-     */
-    @SneakyThrows
-    private List<Object> buildLogArgsDetails(JoinPoint joinPoint) {
-        Object[] args = joinPoint.getArgs();
-        return Arrays.stream(args)
-                .filter(arg -> !(arg instanceof ServletRequest || arg instanceof ServletResponse))
-                .map(arg -> {
-                    if (arg instanceof File) {
-                        return ((File) arg).getName();
-                    } else if (arg instanceof InputStream) {
-                        return "参数为输入流";
-                    } else {
-                        return arg;
-                    }
-                })
-                .collect(Collectors.toList());
-    }
-
-    /**
-     * 获取真实ip地址,不返回内网地址
-     *
-     * @param request 请求对象
-     * @return 真实客户ip
-     */
-    public String getIpAddr(HttpServletRequest request) {
-        //目前则是网关ip
-        String ip = request.getHeader("X-Forwarded-For");
-        if (ip != null && !ip.isEmpty() && !UNKNOWN.equalsIgnoreCase(ip)) {
-            return getFirstIpAddr(ip);
-        }
-        if (ip == null || ip.isEmpty() || UNKNOWN.equalsIgnoreCase(ip)) {
-            ip = request.getHeader("Proxy-Client-IP");
-        }
-        if (ip == null || ip.isEmpty() || UNKNOWN.equalsIgnoreCase(ip)) {
-            ip = request.getHeader("WL-Proxy-Client-IP");
-        }
-        if (ip == null || ip.isEmpty() || UNKNOWN.equalsIgnoreCase(ip)) {
-            ip = request.getHeader("HTTP_CLIENT_IP");
-        }
-        if (ip == null || ip.isEmpty() || UNKNOWN.equalsIgnoreCase(ip)) {
-            ip = request.getHeader("HTTP_X_FORWARDED_FOR");
-        }
-        if (ip == null || ip.isEmpty() || UNKNOWN.equalsIgnoreCase(ip)) {
-            ip = request.getRemoteAddr();
-        }
-
-
-        return getFirstIpAddr(ip);
-    }
-
-    private static String getFirstIpAddr(String ip) {
-        if (ip != null && !ip.isEmpty() && !UNKNOWN.equalsIgnoreCase(ip)) {
-            int index = ip.indexOf(',');
-            if (index != -1) {
-                //只获取第一个值
-                return ip.substring(0, index);
-            } else {
-                return ip;
-            }
-        } else {
-            //取不到真实ip则返回空，不能返回内网地址。
-            return "";
-        }
-    }
-}

package/template/.qoder/skills/yss-audit-log/assets/YssAuditLogPrintSubscriberImpl.java

@@ -1,37 +0,0 @@
-/*
- * Licensed to the Apache Software Foundation (ASF) under one or more
- * contributor license agreements.  See the NOTICE file distributed with
- * this work for additional information regarding copyright ownership.
- * The ASF licenses this file to You under the Apache License, Version 2.0
- * (the "License"); you may not use this file except in compliance with
- * the License.  You may obtain a copy of the License at
- *
- *    http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-package com.yss.cloud.audit.subscriber.impl;
-
-import com.yss.cloud.audit.subscriber.YssAuditSubscriber;
-import com.yss.cloud.dto.audit.message.AuditMessage;
-import lombok.extern.slf4j.Slf4j;
-
-/**
- * 日志打印操作日志订阅器
- *
- * @author zhudaoming
- * @since 1.0.0
- */
-@Slf4j
-public class YssAuditLogPrintSubscriberImpl implements YssAuditSubscriber {
-
-    @Override
-    public void execute(AuditMessage message) {
-        log.info("[AUDIT_MESSAGE] 审计日志 => {}",message.toString());
-    }
-}

package/template/.qoder/skills/yss-audit-log/assets/YssAuditLogSysManagerSubscriberImpl.java

@@ -1,18 +0,0 @@
-package com.yss.cloud.audit.subscriber.impl;
-
-import com.yss.cloud.audit.subscriber.YssAuditSubscriber;
-import com.yss.cloud.dto.audit.message.AuditMessage;
-import com.yss.datamiddle.feign.YssDmSystemManageFeign;
-import org.springframework.beans.factory.annotation.Autowired;
-
-/**
- * @author zhudaoming
- */
-public class YssAuditLogSysManagerSubscriberImpl implements YssAuditSubscriber {
-    @Autowired
-    private YssDmSystemManageFeign yssDmSystemManageFeign;
-    @Override
-    public void execute(AuditMessage message) {
-        yssDmSystemManageFeign.saveAuditLog(message);
-    }
-}

package/template/.qoder/skills/yss-audit-log/assets/YssAuditPublishService.java

@@ -1,69 +0,0 @@
-package com.yss.cloud.audit.subscriber;
-
-import com.yss.cloud.audit.configuration.AuditConfigurationProperties;
-import com.yss.cloud.dto.audit.message.AuditMessage;
-import lombok.extern.slf4j.Slf4j;
-import org.springframework.beans.factory.annotation.Autowired;
-
-import javax.annotation.PostConstruct;
-import java.util.List;
-import java.util.concurrent.ArrayBlockingQueue;
-import java.util.concurrent.BlockingQueue;
-import java.util.concurrent.ExecutorService;
-import java.util.concurrent.Executors;
-
-@Slf4j
-public class YssAuditPublishService {
-
-    private final BlockingQueue<AuditMessage> auditMessageQueue = new ArrayBlockingQueue<>(1000);
-    private final ExecutorService executorService = Executors.newFixedThreadPool(10);
-    @Autowired
-    private List<YssAuditSubscriber> subscribers;
-    @Autowired
-    private AuditConfigurationProperties auditConfigurationProperties;
-
-    /**
-     * Initialize the service and start the message processing.
-     */
-    @PostConstruct
-    private void init() {
-        for (int i = 0; i < 10; i++) {
-            executorService.submit(this::doPublish);
-        }
-    }
-
-    /**
-     * Publish a new audit message.
-     *
-     * @param message audit message
-     */
-    public void publish(AuditMessage message) {
-        if (auditConfigurationProperties.getEnabled()) {
-            if (!auditMessageQueue.offer(message)) {
-                log.error("Publish audit message failed, message:{}", message);
-            }
-        }
-    }
-
-    /**
-     * Execute the message processor for each subscriber.
-     */
-    private void doPublish() {
-        while (true) {
-            try {
-                AuditMessage message = auditMessageQueue.take();
-                for (YssAuditSubscriber subscriber : subscribers) {
-                    try {
-                        subscriber.execute(message);
-                    } catch (Exception e) {
-                        log.error("Consume audit message failed, message:{}", message, e);
-                    }
-                }
-            } catch (InterruptedException e) {
-                log.error("Consume audit message failed", e);
-                Thread.currentThread().interrupt();
-                break;
-            }
-        }
-    }
-}

package/template/.qoder/skills/yss-audit-log/references/README.md

@@ -1,69 +0,0 @@
-# 参考资料
-
-本文档详细介绍了 `yss-component-audit-log` 组件的核心类和配置类。
-
-## 核心类 (Core Classes)
-
-### 1. AuditLogAspect.java
-
-**位置**: `../assets/AuditLogAspect.java`
-
-审计日志切面，是日志收集的核心入口。
-
-**拦截逻辑**:
-
-- **切点**: 拦截带有 `@AuditLog` 注解且为 public 的方法。
-- **处理流程**:
-  1. **解析注解**: 获取 `@AuditLog` 中的操作类型、描述、资源类型等信息。
-  2. **SpEL 解析**: 如果 `summary` 中包含 `#{...}` 表达式，会解析方法参数和返回值，动态生成日志内容。
-  3. **构建消息**:
-     - 收集用户信息（从 JWT 解析）。
-     - 收集请求信息（URL, IP, User-Agent）。
-     - 收集参数和结果（根据 `isNeedArgs` 和 `isNeedResult` 配置）。
-  4. **发布消息**: 调用 `YssAuditPublishService.publish` 将构建好的 `AuditMessage` 发布出去。
-
-### 2. YssAuditPublishService.java
-
-**位置**: `../assets/YssAuditPublishService.java`
-
-异步日志发布服务。
-
-**机制**:
-
-- 维护一个内部阻塞队列 `ArrayBlockingQueue` (容量1000)。
-- 启动固定线程池（10个线程）作为消费者，不断从队列中获取消息。
-- 将消息分发给所有注册的 `YssAuditSubscriber` 实现类。
-
-### 3. Subscriber 实现
-
-#### YssAuditLogPrintSubscriberImpl.java
-
-**位置**: `../assets/YssAuditLogPrintSubscriberImpl.java`
-
-- **功能**: 简单的控制台日志打印，用于开发调试。
-- **开关**: 通过 `yss.audit.auditLogPrintEnabled` 控制。
-
-#### YssAuditLogSysManagerSubscriberImpl.java
-
-**位置**: `../assets/YssAuditLogSysManagerSubscriberImpl.java`
-
-- **功能**: 调用 `YssDmSystemManageFeign` 将审计日志发送到系统管理服务进行持久化存储。
-- **开关**: 通过 `yss.audit.sendSysManageEnabled` 控制。
-
-## 关键注解
-
-### @AuditLog
-
-用于标记需要审计的方法。
-
-```java
-@Target({ElementType.TYPE, ElementType.METHOD})
-@Retention(RetentionPolicy.RUNTIME)
-public @interface AuditLog {
-    String summary() default ""; // 操作描述，支持 SpEL
-    AuditOperationType operation(); // 操作类型 (ADD, UPDATE, DELETE, QUERY, etc.)
-    AuditResourceType resource() default AuditResourceType.DM; // 资源类型
-    boolean isNeedResult() default false; // 是否记录返回值
-    boolean isNeedArgs() default true; // 是否记录参数
-}
-```

package/template/.qoder/skills/yss-audit-log/references/source-index.md

@@ -1,43 +0,0 @@
-# yss-audit-log 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-skill-source-index-refresh/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-audit-log` (existed when indexed)
-
-## Documentation Files
-
-- No component documentation files found.
-
-## Maven Modules
-
-- `yss-microservice-components/yss-component-audit-log`
-
-## Key Java Entry Points
-
-- `yss-microservice-components/yss-component-audit-log/src/main/java/com/yss/cloud/audit/AuditLog.java`
-- `yss-microservice-components/yss-component-audit-log/src/main/java/com/yss/cloud/audit/EnableAuditLog.java`
-- `yss-microservice-components/yss-component-audit-log/src/main/java/com/yss/cloud/audit/configuration/AuditConfiguration.java`
-- `yss-microservice-components/yss-component-audit-log/src/main/java/com/yss/cloud/audit/configuration/AuditConfigurationProperties.java`
-- `yss-microservice-components/yss-component-audit-log/src/main/java/com/yss/cloud/audit/configuration/AuditLogAspect.java`
-- `yss-microservice-components/yss-component-audit-log/src/main/java/com/yss/cloud/audit/configuration/EnableAuditLogImportSelector.java`
-- `yss-microservice-components/yss-component-audit-log/src/main/java/com/yss/cloud/audit/configuration/UUIDGenerator.java`
-- `yss-microservice-components/yss-component-audit-log/src/main/java/com/yss/cloud/audit/feign/YssDmSystemManageFeign.java`
-- `yss-microservice-components/yss-component-audit-log/src/main/java/com/yss/cloud/audit/subscriber/YssAuditPublishService.java`
-- `yss-microservice-components/yss-component-audit-log/src/main/java/com/yss/cloud/audit/subscriber/YssAuditSubscriber.java`
-- `yss-microservice-components/yss-component-audit-log/src/main/java/com/yss/cloud/audit/subscriber/impl/YssAuditLogPrintSubscriberImpl.java`
-- `yss-microservice-components/yss-component-audit-log/src/main/java/com/yss/cloud/audit/subscriber/impl/YssAuditLogSysManagerSubscriberImpl.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/.qoder/skills/yss-cache/SKILL.md

@@ -1,44 +0,0 @@
----
-name: yss-cache
-description: 用于 YSS 缓存框架的接入、配置、代码修改和故障诊断。Use when tasks involve QueryCache、UpdateCache、ClearCache、TTL、SpEL key、事务提交后缓存操作、Redis/Caffeine/Hazelcast 后端切换、Redis Standalone/Sentinel/Cluster、Jedis 连接池、Redis fallback、JetCache、多级缓存、序列化兼容、缓存不命中或失效不一致。
----
-
-# yss-cache
-
-处理 `yss-component-cache-parent` 及其消费项目的缓存任务。
-
-## 工作流
-
-1. 按 `yss-skill-source-index-refresh/references/source-location.md` 定位真实源码。当前工作区有 `.codegraph/` 时先用 CodeGraph；否则读取 [source-index.md](references/source-index.md) 后用符号或 Maven 模块搜索。
-2. 识别使用模型：Spring Cache 单后端路由、Redis 故障降级，或 JetCache local + remote。不要混用三者的行为假设。
-3. 明确缓存名、key、TTL、更新/删除路径、跨节点一致性和序列化兼容要求。
-4. 先检查现有依赖、启动注解、配置和注解用法，再决定修改业务代码、配置还是组件。
-5. 修改后执行对应 reference 的验证；组件跨模块修改必须从父 reactor 构建，不要依赖本地旧 SNAPSHOT。
-
-## 不变量
-
-- 新增查询缓存时同时覆盖更新、删除和状态变更的失效路径。
-- key 必须稳定并显式包含租户、机构、账套等隔离维度；不要依赖 DTO 的不稳定序列化结果。
-- 不要把 Redis fallback 当作正常二级缓存。Caffeine fallback 存在节点间不一致窗口。
-- 不要声称纯 Redis 后端会广播本地缓存失效。只有确认 JetCache 配置了 local、remote 和 broadcast channel 后才能作此判断。
-- 不要在没有双读、版本前缀、灰度清理或迁移窗口时修改 serializer、key prefix 或 cache name。
-- 不明确一致性要求时，不默认启用本地缓存或 fallback。
-
-## 按场景读取
-
-- 模块、后端选择或多级缓存边界：[architecture.md](references/architecture.md)
-- 新增或修改缓存注解、SpEL、空 key、全量清理：[annotations.md](references/annotations.md)
-- 依赖、启动注解、TTL、Caffeine/Hazelcast、Bean backoff：[configuration.md](references/configuration.md)
-- Redis 单机、哨兵、集群、认证、SSL、超时、Jedis pool：[redis-topology.md](references/redis-topology.md)
-- Redis 故障、fallback、恢复清理和一致性：[redis-fallback.md](references/redis-fallback.md)
-- RedisTemplate/RedisCacheManager 数据格式或迁移：[serialization.md](references/serialization.md)
-- 缓存不生效、未失效、启动失败、Redis 异常：[troubleshooting.md](references/troubleshooting.md)
-- 完成修改后的组件与消费项目验收：[verification.md](references/verification.md)
-
-## 工具
-
-- `scripts/inspect-cache-usage.sh <project-root>`：只读扫描消费项目；发现阻断缺陷返回 1，输入或环境错误返回 2。
-- `scripts/verify-cache-component.sh [--source-root PATH] [--consumer-root PATH --consumer-module MODULE]`：验证组件、真实 Redis、Java 8 字节码及可选消费模块。
-- `scripts/check-skill-freshness.sh [source-root]`：比较技能契约与当前组件源码；发现漂移返回 1。
-
-当组件源码变化后，用 `yss-skill-source-index-refresh` 刷新 [source-index.md](references/source-index.md)，再运行 freshness 检查。不要手工修改生成索引。

package/template/.qoder/skills/yss-cache/agents/openai.yaml

@@ -1,5 +0,0 @@
-version: 1
-interface:
-  display_name: "YSS Cache"
-  short_description: "YSS 缓存注解、Redis 拓扑、降级与序列化诊断"
-  default_prompt: "Use $yss-cache to configure or diagnose YSS cache annotations, Redis topology, fallback, TTL, and serialization behavior."

package/template/.qoder/skills/yss-cache/references/annotations.md

@@ -1,39 +0,0 @@
-# 注解契约
-
-## 映射
-
-- `@QueryCache` -> Spring `CacheableOperation`。
-- `@UpdateCache` -> Spring `CachePutOperation`。
-- `@ClearCache` -> Spring `CacheEvictOperation`。
-- `value` 与 `cacheNames` 是别名；非空 `cacheName` 会覆盖枚举 cache names。
-- 默认 resolver 是 `cacheComposeResolver`。
-- `key` 与 `keyGenerator` 互斥。
-
-## 参数语义
-
-- `condition`：调用前判断，false 时跳过缓存操作。
-- `unless`：结果产生后判断；Query/Update 支持。ClearCache 虽保留该字段，但当前解析器不映射它。
-- `sync`：QueryCache 映射到同步加载；UpdateCache 和 ClearCache 当前不映射该字段。
-- `allEntries=true`：明确清空整个 cache。
-- `beforeInvocation=true`：业务方法执行前清理；后续业务失败不会恢复旧缓存。
-
-## Key 与清理
-
-```java
-@QueryCache(cacheName = "valuation:plan", key = "#tenantId + ':' + #planId")
-public PlanDTO get(String tenantId, Long planId) { ... }
-
-@ClearCache(cacheName = "valuation:plan", key = "#tenantId + ':' + #planId")
-public void delete(String tenantId, Long planId) { ... }
-```
-
-- 未配置 key 时由 Spring KeyGenerator 生成；无参数方法会得到 `SimpleKey.EMPTY`。
-- 当前 YSS 拦截器将 `SimpleKey.EMPTY` 视为全量清理。需要单 key 清理时必须给出稳定 key。
-- 全量清理优先显式写 `allEntries=true`，不要依赖偶然 key 形态。
-- 集合参数先稳定排序；null、大小写和空白必须归一化。
-
-## AOP 与事务
-
-- 缓存方法必须通过 Spring 代理调用；同类 `this.method()` 自调用会绕过拦截。
-- private 方法不能作为代理入口；final 方法/类受代理方式限制。
-- `put`、`evict`、`clear` 在事务同步激活时延迟到 `afterCommit`；回滚不执行缓存变更。

package/template/.qoder/skills/yss-cache/references/architecture.md

@@ -1,25 +0,0 @@
-# 架构与选择
-
-## 三种模型
-
-| 模型 | 行为 | 一致性边界 |
-|---|---|---|
-| Spring Cache 后端路由 | `yss.cache.active-type` 在 Redis、Caffeine、Hazelcast 中选择一个 Provider | 同一时刻是单后端，不是多级缓存 |
-| Redis fallback | Redis 故障时可临时改用另一个 Provider | 是故障降级；Caffeine 会产生节点间不一致窗口 |
-| JetCache | 独立扩展，可配置 local + remote | 只有实际配置 broadcast channel 才能认为本地失效会同步 |
-
-## 模块
-
-- `yss-component-spring-cache`：注解、解析器、拦截器、路由和公共属性。
-- `yss-component-redis-cache`：Jedis 连接、RedisTemplate、RedisCacheManager、健康检查和 fallback。
-- `yss-component-caffeine-cache`：节点本地缓存。
-- `yss-component-hazelcast-cache`：显式依赖的集群内存后端。
-- `yss-component-cache-starter`：默认聚合 Spring Cache、Redis 和 Caffeine。
-- `yss-component-jetcache`：与 Spring Cache 路由模型分开分析。
-
-## 选择规则
-
-- 跨节点共享且不接受节点本地旧值：使用纯 Redis。
-- 读多写少并允许短暂节点差异：可选择 Caffeine。
-- Redis 故障期间业务可用性高于缓存一致性：评估后启用 fallback。
-- 需要 local + remote：先确认 JetCache 的 local、remote、序列化和广播配置，不要只看依赖名称。

package/template/.qoder/skills/yss-cache/references/configuration.md

@@ -1,34 +0,0 @@
-# 接入与配置
-
-## 推荐接入
-
-```xml
-<dependency>
-  <groupId>com.yss.cloud</groupId>
-  <artifactId>yss-component-cache-starter</artifactId>
-</dependency>
-```
-
-启动类使用 `@EnableYssCloudCache`。`@EnableYssCloudRedisCache` 仅为兼容保留并已废弃。
-
-## 公共属性
-
-```yaml
-yss:
-  cache:
-    active-type: redis       # redis | caffeine | hazelcast
-    default-ttl: 1h
-    redis:
-      fallback-enabled: false
-      fallback-type: caffeine
-      clear-fallback-on-recovery: true
-```
-
-- Redis 动态 cache 和 Caffeine 默认 TTL 使用 `yss.cache.default-ttl`。
-- `CacheKeyCode` 中声明的 TTL 覆盖默认 TTL。
-- Caffeine 的 `spring.cache.caffeine.spec` 可覆盖默认构建规格，修改前检查项目现有配置。
-- Hazelcast 不在 starter 生产依赖中；使用时显式引入模块并配置 `active-type=hazelcast`。
-
-## 自定义 Bean
-
-默认配置会对用户提供的 `RedisProperties`、`RedisConnectionFactory`、`JedisClientConfiguration`、pool config、RedisCacheManager、resolver、provider、serializer、RedisTemplate 和 RedisMappingContext 回退。排障时按类型和名称检查实际 Bean，不能假设框架默认 Bean 一定生效。