@llryiop/avatar-boot-cli 1.0.0 → 1.0.2

package/templates/.claude/skills/avatar-boot-starter-web/SKILL.md

@@ -1,1007 +1,154 @@
 ---
 name: avatar-boot-starter-web
-description: 当使用 avatar-boot-starter-web 模块时使用此技能 - 为 Spring Boot 3.5.3 应用提供全面的 Web 开发基础设施，包括请求上下文管理、结构化日志、全局异常处理、指标集成。
+description: Avatar Boot Web 模块使用指南与代码接入助手。当用户询问 avatar-boot-starter-web 的功能使用、配置方式、异常处理、日志配置、TraceId 传递、@LogInfo 注解、指标监控，或需要接入 Web 模块时触发。
 ---
 
-# Avatar Boot Starter Web 技能
-
-## 何时使用此技能
-
-当用户出现以下情况时调用此技能：
-
-- 提到 "avatar-boot-starter-web"、"web starter" 或 "web 模块"
-- 询问请求上下文、TraceId 或请求追踪
-- 想要配置或排查 Avatar Boot 应用中的日志问题
-- 询问全局异常处理或错误响应
-- 需要为 Web 应用配置 CORS
-- 想要检测或监控慢请求
-- 询问客户端 IP 提取或代理处理
-- 提到 `@LogInfo` 注解或方法级日志
-- 想要集成 Micrometer 指标/监控
-- 正在使用 Avatar Boot 创建新的 Web 应用
-- 询问结构化日志或 JSON 日志格式
-- 需要在业务逻辑中访问请求上下文
-- 排查 TraceId 传播问题
-- 询问异步场景下的 TraceID 传播（1.0.0-SNAPSHOT+）
-- 使用 @Async、CompletableFuture 或自定义线程池（1.0.0-SNAPSHOT+）
-- 想要自定义 TraceID 生成策略（1.0.0-SNAPSHOT+）
-- 需要集成 Micrometer Tracing 或分布式追踪系统（1.0.0-SNAPSHOT+）
-
-## 模块概述
-
-`avatar-boot-starter-web` 模块是一个 Spring Boot starter，为 Avatar Boot 应用提供生产就绪的 Web 开发基础设施。它遵循 Spring Boot 自动配置约定，无需任何配置即可开始使用。
-
-**核心能力：**
-- 自动初始化请求上下文并生成 TraceId
-- 结构化日志并自动注入 TraceId
-- 全局异常处理并返回标准化响应
-- 使用 Micrometer 集成指标
-- CORS 支持（默认禁用）
-- 慢请求检测和监控
-- 代理感知的客户端 IP 提取
-
-## 核心功能
-
-### 1. 请求上下文管理
-
-**功能说明：**
-- 为每个 HTTP 请求自动初始化 `AvatarContext`
-- 从 `X-Trace-Id` 请求头生成或传播 TraceId
-- 提取客户端 IP（代理感知，支持 X-Forwarded-For）
-- 追踪请求耗时并检测慢请求
-- 自动清理 ThreadLocal 以防止内存泄漏
-
-**核心组件：**
-- `RequestContextInterceptor` - 拦截所有请求（可配置路径）
-- `AvatarContext` - 保存请求元数据（traceId、uri、method、clientIp、startTime）
-- `ContextManager` - 基于 ThreadLocal 的上下文访问器
-
-**使用示例：**
-引入pom依赖：
-```xml
-<dependency>
-    <groupId>com.iflytek.avatar.boot</groupId>
-    <artifactId>avatar-boot-starter-web</artifactId>
-    <version>${avatar.boot.version}</version>
-</dependency>
-```
-
-```java
-import com.iflytek.avatar.boot.context.AvatarContext;
-import com.iflytek.avatar.boot.context.ContextManager;
-
-@RestController
-public class UserController {
-
-    @GetMapping("/user/info")
-    public Result<UserInfo> getUserInfo() {
-        // 访问当前请求上下文
-        AvatarContext context = ContextManager.get();
-        String traceId = context.getTraceId();
-        String clientIp = context.getClientIp();
-
-        log.info("Processing request for user from IP: {}", clientIp);
-        return Result.success(userInfo);
-    }
-}
-```
-
-### 2. 结构化日志
-
-**功能说明：**
-- 自动将 TraceId 注入所有日志消息
-- 使用 Logstash Logback Encoder 提供 JSON 日志格式
-- 支持多种日志输出（控制台、文件、JSON 文件）
-- 使用异步 appender 实现高性能
-- 自动为慢请求添加 `[SLOW]` 前缀标记
-
-**日志格式：**
-
-控制台/文件格式：
-```
-2026-03-03 17:04:15.123 [http-nio-8080-exec-1] [abc123def456] INFO  c.i.a.b.controller.UserController - Request started: GET /user/info from 192.168.1.100
-```
-
-JSON 格式：
-```json
-{
-  "timestamp": "2026-03-03T17:04:15.123+08:00",
-  "level": "INFO",
-  "thread": "http-nio-8080-exec-1",
-  "logger": "com.iflytek.avatar.boot.controller.UserController",
-  "message": "Request started: GET /user/info from 192.168.1.100",
-  "traceId": "abc123def456",
-  "app": "avatar-app"
-}
-```
-
-**日志文件：**
-- `logs/${spring.application.name}.log` - 所有日志
-- `logs/${spring.application.name}-error.log` - 仅错误日志
-- `logs/${spring.application.name}-json.log` - JSON 格式日志
-
-**环境特定行为：**
-- **dev/local**：控制台 + 文件输出
-- **test**：控制台 + 文件 + JSON 输出
-- **prod**：仅文件 + JSON 输出（无控制台）
-
-### 3. @LogInfo 注解
-
-**功能说明：**
-- 通过 AOP 提供方法级日志
-- 记录请求参数和响应结果
-- 追踪方法执行时间
-- 集成指标记录
-- 自动记录异常及堆栈信息
-
-**注解参数：**
-```java
-@LogInfo(
-    request = true,      // 记录请求参数（默认：false）
-    response = true,     // 记录响应结果（默认：false）
-    metrics = true,      // 记录指标（默认：false）
-    costTime = 3000      // 慢方法阈值（毫秒）（默认：3000）
-)
-```
-
-**使用示例：**
-```java
-@Service
-public class UserService {
-
-    @LogInfo(request = true, response = true, metrics = true, costTime = 2000)
-    public UserInfo getUserById(Long userId) {
-        // 业务逻辑
-        return userInfo;
-    }
-}
-```
-
-**日志输出：**
-```
-[UserService.getUserById] Status: SUCCESS, Time: 156ms
-→ Request: [123]
-→ Response: {"id":123,"name":"John Doe"}
-```
-
-**慢方法警告：**
-```
-[UserService.getUserById] Status: SUCCESS, Time: 2345ms (⚠️ threshold: 2000ms)
-→ Request: [123]
-→ Response: {"id":123,"name":"John Doe"}
-```
-
-### 4. 全局异常处理
-
-**功能说明：**
-- 捕获所有异常并返回标准化的 `Result<?>` 响应
-- 处理业务异常、参数校验错误和系统错误
-- 记录异常及请求上下文（URI、方法）
-- 返回适当的 HTTP 状态码
-
-**支持的异常类型：**
-- `BusinessException` - 业务逻辑错误（HTTP 200 带错误码）
-- `MethodArgumentNotValidException` - @RequestBody 校验（HTTP 400）
-- `BindException` - @ModelAttribute 校验（HTTP 400）
-- `ConstraintViolationException` - @RequestParam 校验（HTTP 400）
-- `RuntimeException` - 运行时错误（HTTP 500）
-- `Exception` - 所有其他异常（HTTP 500）
-
-**使用示例：**
-```java
-import com.iflytek.avatar.boot.exception.BusinessException;
-import com.iflytek.avatar.boot.entity.response.ResultCode;
-
-@Service
-public class UserService {
-
-    public void updateUser(Long userId) {
-        if (userId == null) {
-            throw new BusinessException(ResultCode.PARAM_ERROR, "用户ID不能为空");
-        }
-        // 业务逻辑
-    }
-}
-```
-
-**响应格式：**
-```json
-{
-  "code": 400,
-  "message": "用户ID不能为空",
-  "data": null,
-  "success": false
-}
-```
-
-### 5. 指标集成
-
-**功能说明：**
-- 记录方法调用次数和执行时间
-- 使用 Micrometer 进行指标收集
-- 缓存指标实例以避免重复注册
-- 支持成功/失败状态追踪
-
-**记录的指标：**
-- `method.invocation.count` - 计数器，标签：class、method、status
-- `method.execution.time` - 计时器，标签：class、method、status
-
-**使用方式：**
-使用 `@LogInfo(metrics = true)` 时会自动记录指标。
-
-**手动记录：**
-```java
-@Autowired
-private MetricsRecorder metricsRecorder;
-
-public void someMethod() {
-    long startTime = System.currentTimeMillis();
-    try {
-        // 业务逻辑
-        long costTime = System.currentTimeMillis() - startTime;
-        metricsRecorder.recordMethodMetrics("MyClass", "someMethod", costTime, null);
-    } catch (Exception e) {
-        long costTime = System.currentTimeMillis() - startTime;
-        metricsRecorder.recordMethodMetrics("MyClass", "someMethod", costTime, e);
-        throw e;
-    }
-}
-```
-
-### 6. CORS 支持
-
-**功能说明：**
-- 提供可配置的跨域资源共享
-- 出于安全考虑默认禁用
-- 支持自定义源、方法、请求头和凭证
-
-**配置示例：**
-```yaml
-avatar:
-  web:
-    cors-enabled: true
-    cors:
-      allowed-origins:
-        - "https://example.com"
-        - "https://app.example.com"
-      allowed-methods:
-        - GET
-        - POST
-        - PUT
-        - DELETE
-      allowed-headers:
-        - "*"
-      exposed-headers:
-        - X-Trace-Id
-      allow-credentials: true
-      max-age: 3600
-```
-
-### 7. TraceID 异步支持与 Micrometer 集成
-
-**版本要求：** Avatar Boot 1.0.0-SNAPSHOT+
-
-**功能说明：**
-- 使用 TransmittableThreadLocal 自动传播 TraceID 到异步线程
-- 支持 @Async、CompletableFuture、自定义线程池
-- 可插拔的 TraceID 生成器（UUID、Snowflake、自定义）
-- 可选的 Micrometer Tracing 集成（支持 Zipkin、Jaeger）
-- 向后兼容，无需修改现有代码
-
-**核心改进：**
-
-#### 7.1 异步场景自动支持
-
-**问题：** 之前使用普通 ThreadLocal，无法在异步线程中传播 TraceID
-
-**解决方案：**
-- 使用阿里巴巴的 TransmittableThreadLocal (TTL)
-- 自动配置 TaskDecorator 装饰异步任务
-- 支持 @Async、CompletableFuture、自定义线程池
-
-**使用示例：**
-
-```java
-@Service
-public class UserService {
-
-    @Async
-    public CompletableFuture<User> getUserAsync(String userId) {
-        // TraceID 自动传播到异步线程
-        String traceId = ContextManager.get().getTraceId();
-        log.info("Async thread TraceID: {}", traceId);
-
-        User user = userRepository.findById(userId);
-        return CompletableFuture.completedFuture(user);
-    }
-}
-```
-
-**日志输出：**
-```
-[main] [abc123] Request started: GET /users/1
-[avatar-async-1] [abc123] Async thread TraceID: abc123
-[main] [abc123] Request completed: GET /users/1 - 150ms
-```
-
-#### 7.2 可插拔的 TraceID 生成器
-
-**默认实现：** 使用 UUID（去除连字符）
-
-**自定义实现：**
-
-```java
-@Component
-public class SnowflakeTraceIdGenerator implements TraceIdGenerator {
-
-    private final Snowflake snowflake = IdUtil.getSnowflake(1, 1);
-
-    @Override
-    public String generate() {
-        return String.valueOf(snowflake.nextId());
-    }
-}
-```
-
-#### 7.3 Micrometer Tracing 集成（可选）
-
-**启用方式：**
-
-```yaml
-avatar:
-  web:
-    tracing:
-      micrometer-enabled: true
-
-management:
-  tracing:
-    enabled: true
-    sampling:
-      probability: 1.0
-```
-
-**收益：**
-- 与 Spring Cloud 生态无缝集成
-- 支持 Zipkin、Jaeger 等分布式追踪系统
-- 自动传播 W3C Trace Context 和 B3 格式
-
-**异步配置：**
-
-```yaml
-avatar:
-  web:
-    async:
-      enabled: true              # 是否启用异步支持（默认：true）
-      core-pool-size: 10         # 核心线程数
-      max-pool-size: 50          # 最大线程数
-      queue-capacity: 200        # 队列容量
-      thread-name-prefix: avatar-async-
-```
-
-**追踪配置：**
-
-```yaml
-avatar:
-  web:
-    tracing:
-      micrometer-enabled: false  # 是否启用 Micrometer 集成（默认：false）
-      generator-type: uuid       # TraceID 生成策略（uuid, snowflake, custom）
-```
-
-**性能影响：**
-- 内存开销：每个异步任务额外复制一份上下文（约 1KB）
-- CPU 开销：上下文复制和恢复（< 1ms）
-- 总体影响：< 5%（压测验证）
-
-**依赖版本：**
-- TransmittableThreadLocal: 2.14.5
-- Micrometer Tracing: 1.4.3（可选）
-
-## 配置指南
-
-### 基础配置（最小化）
-
-```yaml
-spring:
-  application:
-    name: my-app
-
-# 所有功能默认启用，无需额外配置
-```
-
-### 高级配置（所有选项）
-
-```yaml
-avatar:
-  web:
-    # 功能开关
-    interceptor-enabled: true           # 启用请求拦截器（默认：true）
-    exception-handler-enabled: true     # 启用全局异常处理器（默认：true）
-    cors-enabled: false                 # 启用 CORS（默认：false）
-
-    # 拦截器配置
-    interceptor:
-      trace-id-header: X-Trace-Id       # TraceId 请求头名称（默认：X-Trace-Id）
-      include-paths:                    # 拦截路径（默认：/**）
-        - /**
-      exclude-paths:                    # 排除路径
-        - /error
-        - /actuator/**
-        - /favicon.ico
-        - /webjars/**
-        - /swagger-ui/**
-        - /v3/api-docs/**
-
-    # 日志配置
-    log:
-      request-enabled: true             # 记录请求开始（默认：true）
-      response-enabled: true            # 记录请求完成（默认：true）
-      slow-request-threshold: 3000      # 慢请求阈值（毫秒）（默认：3000）
-
-    # 异步配置（1.0.0-SNAPSHOT+）
-    async:
-      enabled: true                     # 启用异步支持（默认：true）
-      core-pool-size: 10                # 核心线程数（默认：10）
-      max-pool-size: 50                 # 最大线程数（默认：50）
-      queue-capacity: 200               # 队列容量（默认：200）
-      thread-name-prefix: avatar-async- # 线程名前缀（默认：avatar-async-）
-
-    # 追踪配置（1.0.0-SNAPSHOT+）
-    tracing:
-      micrometer-enabled: false         # 启用 Micrometer 集成（默认：false）
-      generator-type: uuid              # TraceID 生成策略（uuid, snowflake, custom）
-
-    # CORS 配置（仅当 cors-enabled: true 时生效）
-    cors:
-      allowed-origins:
-        - "*"
-      allowed-methods:
-        - GET
-        - POST
-        - PUT
-        - DELETE
-        - OPTIONS
-      allowed-headers:
-        - "*"
-      exposed-headers:
-        - X-Trace-Id
-      allow-credentials: true
-      max-age: 3600
-
-# 日志配置
-logging:
-  level:
-    root: INFO
-    com.iflytek.avatar.boot: DEBUG
-  file:
-    path: logs
-```
-
-### 环境特定配置
-
-**开发环境（dev）：**
-```yaml
-spring:
-  config:
-    activate:
-      on-profile: dev
-
-avatar:
-  web:
-    log:
-      slow-request-threshold: 5000  # 开发环境放宽阈值
-
-logging:
-  level:
-    root: INFO
-    com.iflytek.avatar.boot: DEBUG
-```
-
-**生产环境（prod）：**
-```yaml
-spring:
-  config:
-    activate:
-      on-profile: prod
-
-avatar:
-  web:
-    cors-enabled: false  # 生产环境禁用 CORS
-    log:
-      slow-request-threshold: 2000  # 生产环境更严格的阈值
-
-logging:
-  level:
-    root: INFO
-    com.iflytek.avatar.boot: INFO
-  file:
-    path: /var/log/app
-```
-
-## 常见使用场景
-
-### 场景 1：API 网关集成
-
-在 API 网关（Kong、Nginx）后构建服务时：
-
-```yaml
-avatar:
-  web:
-    interceptor:
-      trace-id-header: X-Request-Id  # 匹配网关的请求头名称
-      exclude-paths:
-        - /health
-        - /metrics
-```
-
-### 场景 2：微服务分布式追踪
-
-```java
-@Service
-public class OrderService {
-
-    @Autowired
-    private RestTemplate restTemplate;
-
-    public void createOrder(OrderRequest request) {
-        // TraceId 自动可用
-        AvatarContext context = ContextManager.get();
-        String traceId = context.getTraceId();
-
-        // 将 TraceId 传播到下游服务
-        HttpHeaders headers = new HttpHeaders();
-        headers.set("X-Trace-Id", traceId);
-
-        HttpEntity<OrderRequest> entity = new HttpEntity<>(request, headers);
-        restTemplate.postForObject("http://inventory-service/api/reserve", entity, Void.class);
-    }
-}
-```
-
-### 场景 3：性能监控
-
-```java
-@RestController
-@RequestMapping("/api/reports")
-public class ReportController {
-
-    @LogInfo(request = true, response = false, metrics = true, costTime = 5000)
-    @GetMapping("/sales")
-    public Result<SalesReport> generateSalesReport(@RequestParam String startDate,
-                                                     @RequestParam String endDate) {
-        // 重计算
-        SalesReport report = reportService.generateReport(startDate, endDate);
-        return Result.success(report);
-    }
-}
-```
-
-### 场景 4：自定义异常处理
-
-```java
-@Component
-public class CustomExceptionHandler extends GlobalExceptionHandler {
-
-    @ExceptionHandler(AuthenticationException.class)
-    @ResponseStatus(HttpStatus.UNAUTHORIZED)
-    public Result<?> handleAuthenticationException(AuthenticationException e) {
-        log.error("Authentication failed: {}", e.getMessage());
-        return Result.fail(401, "认证失败，请重新登录");
-    }
-}
-```
-
-### 场景 5：@Async 异步方法（1.0.0-SNAPSHOT+）
-
-**自动支持 TraceID 传播**：
-
-```java
-@Service
-public class NotificationService {
-
-    @Async
-    public void sendNotification(String userId, String message) {
-        // TraceID 自动传播到异步线程
-        String traceId = ContextManager.get().getTraceId();
-        log.info("Sending notification with TraceID: {}", traceId);
-        // ... 发送通知
-    }
-}
-```
-
-### 场景 6：CompletableFuture 并行处理（1.0.0-SNAPSHOT+）
-
-**自动支持 TraceID 传播**：
-
-```java
-@Service
-public class OrderService {
-
-    @Autowired
-    private Executor asyncExecutor;
-
-    public Order createOrder(OrderRequest request) {
-        String traceId = ContextManager.get().getTraceId();
-
-        CompletableFuture<Void> inventoryCheck = CompletableFuture.runAsync(() -> {
-            // TraceID 自动传播
-            log.info("Checking inventory with TraceID: {}", traceId);
-            inventoryService.checkStock(request.getProductId());
-        }, asyncExecutor);
-
-        CompletableFuture<Void> paymentProcess = CompletableFuture.runAsync(() -> {
-            // TraceID 自动传播
-            log.info("Processing payment with TraceID: {}", traceId);
-            paymentService.process(request.getPayment());
-        }, asyncExecutor);
-
-        CompletableFuture.allOf(inventoryCheck, paymentProcess).join();
-
-        return orderRepository.save(new Order(request));
-    }
-}
-```
-
-### 场景 7：自定义线程池（1.0.0-SNAPSHOT+）
-
-**需要使用 MdcTaskDecorator**：
-
-```java
-@Configuration
-public class CustomThreadPoolConfig {
-
-    @Autowired
-    private MdcTaskDecorator mdcTaskDecorator;
-
-    @Bean
-    public ThreadPoolTaskExecutor customExecutor() {
-        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
-        executor.setCorePoolSize(5);
-        executor.setMaxPoolSize(10);
-        executor.setQueueCapacity(100);
-        executor.setThreadNamePrefix("custom-");
-
-        // 应用 MDC 任务装饰器以传播 TraceID
-        executor.setTaskDecorator(mdcTaskDecorator);
-
-        executor.initialize();
-        return executor;
-    }
-}
-```
-
-## 故障排查
-
-### 问题 1：日志中未显示 TraceId
-
-**症状：**
-- 日志中没有显示 TraceId（方括号内）
-- JSON 日志中缺少 traceId 字段
-
-**可能原因：**
-1. 请求拦截器被禁用
-2. 请求路径被排除
-3. Logback 配置不正确
-
-**解决方案：**
-```yaml
-# 1. 确保拦截器已启用
-avatar:
-  web:
-    interceptor-enabled: true
-
-# 2. 检查排除路径
-avatar:
-  web:
-    interceptor:
-      exclude-paths:
-        - /actuator/**  # 确保你的路径没有被排除
-
-# 3. 验证 logback-spring.xml 包含 TraceId 模式
-# 模式应包含：[%X{traceId}]
-```
-
-### 问题 2：CORS 错误
-
-**症状：**
-- 浏览器显示 CORS 策略错误
-- 预检 OPTIONS 请求失败
-
-**解决方案：**
-```yaml
-# 显式启用 CORS
-avatar:
-  web:
-    cors-enabled: true
-    cors:
-      allowed-origins:
-        - "https://your-frontend-domain.com"  # 使用凭证时不要用 "*"
-      allow-credentials: true
-```
-
-**重要提示：** 如果 `allow-credentials: true`，则不能使用 `allowed-origins: ["*"]`。必须指定确切的源。
-
-### 问题 3：慢请求误报
-
-**症状：**
-- 许多请求被标记为 [SLOW]，但实际上并不慢
-- 阈值对你的使用场景来说太低
-
-**解决方案：**
-```yaml
-# 根据环境调整阈值
-avatar:
-  web:
-    log:
-      slow-request-threshold: 5000  # 增加到 5 秒
-
-# 或禁用慢请求日志
-avatar:
-  web:
-    log:
-      response-enabled: false
-```
-
-### 问题 4：ThreadLocal 内存泄漏
-
-**症状：**
-- 内存使用随时间增长
-- 生产环境出现 OutOfMemoryError
-
-**诊断：**
-拦截器会在 `afterCompletion()` 中自动清理 ThreadLocal。如果出现内存泄漏：
-
-1. 检查是否手动设置上下文但未清理：
-```java
-// ❌ 错误 - 手动设置但未清理
-ContextManager.set(context);
-// ... 业务逻辑
-// 缺失：ContextManager.clear();
-
-// ✅ 正确 - 让拦截器处理
-AvatarContext context = ContextManager.get();
-```
-
-2. 验证拦截器已注册：
-```yaml
-avatar:
-  web:
-    interceptor-enabled: true  # 必须为 true
-```
-
-### 问题 5：客户端 IP 显示为代理 IP
-
-**症状：**
-- `context.getClientIp()` 返回代理/负载均衡器 IP
-- 未捕获真实客户端 IP
-
-**解决方案：**
-确保你的代理/负载均衡器设置了正确的请求头：
-
-```nginx
-# Nginx 配置
-proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-proxy_set_header X-Real-IP $remote_addr;
-```
-
-拦截器按以下顺序检查请求头：
-1. `X-Forwarded-For`（如果有多个则取第一个 IP）
-2. `X-Real-IP`
-3. `Proxy-Client-IP`
-4. `WL-Proxy-Client-IP`
-5. `request.getRemoteAddr()`
-
-### 问题 6：@LogInfo 不工作
-
-**症状：**
-- 使用 @LogInfo 注解的方法没有日志
-- 指标未记录
-
-**可能原因：**
-1. AOP 未启用
-2. 方法未通过 Spring 代理调用
-3. LogInfoAspect 未注册
-
-**解决方案：**
-```java
-// ❌ 错误 - 直接调用方法会绕过 AOP
-@Service
-public class UserService {
-    @LogInfo
-    public void method1() { }
-
-    public void method2() {
-        this.method1();  // 直接调用，AOP 不会拦截
-    }
-}
-
-// ✅ 正确 - 通过 Spring 代理调用
-@Service
-@RequiredArgsConstructor
-public class UserService {
-    private final UserService self;  // 注入自身
-
-    @LogInfo
-    public void method1() { }
-
-    public void method2() {
-        self.method1();  // 代理调用，AOP 生效
-    }
-}
-```
-
-### 问题 7：异步线程中 TraceID 为 null（1.0.0-SNAPSHOT+）
-
-**症状：**
-- 异步方法中 `ContextManager.get().getTraceId()` 返回 null
-- 异步线程的日志中没有 TraceID
-
-**可能原因：**
-1. 使用了自定义线程池但未应用 MdcTaskDecorator
-2. 异步支持被禁用
-3. 使用了不受管理的线程（如 new Thread()）
-
-**解决方案：**
-
-**方案 1：使用配置的异步执行器**
-```java
-@Service
-public class MyService {
-    @Autowired
-    private Executor asyncExecutor;  // 使用 Avatar Boot 配置的执行器
-
-    public void doWork() {
-        CompletableFuture.runAsync(() -> {
-            // TraceID 自动传播
-            String traceId = ContextManager.get().getTraceId();
-        }, asyncExecutor);
-    }
-}
-```
-
-**方案 2：自定义线程池应用 MdcTaskDecorator**
-```java
-@Configuration
-public class ThreadPoolConfig {
-    @Autowired
-    private MdcTaskDecorator mdcTaskDecorator;
-
-    @Bean
-    public ThreadPoolTaskExecutor customExecutor() {
-        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
-        executor.setTaskDecorator(mdcTaskDecorator);  // 关键：应用装饰器
-        executor.initialize();
-        return executor;
-    }
-}
-```
-
-**方案 3：检查异步支持是否启用**
-```yaml
-avatar:
-  web:
-    async:
-      enabled: true  # 确保为 true
-```
-
-### 问题 8：如何验证异步 TraceID 传播是否生效（1.0.0-SNAPSHOT+）
-
-**验证方法：**
-
-```java
-@RestController
-public class TestController {
-
-    @Autowired
-    private Executor asyncExecutor;
-
-    @GetMapping("/test-async")
-    public String testAsync() {
-        String mainTraceId = ContextManager.get().getTraceId();
-        log.info("Main thread TraceID: {}", mainTraceId);
-
-        CompletableFuture.runAsync(() -> {
-            String asyncTraceId = ContextManager.get().getTraceId();
-            log.info("Async thread TraceID: {}", asyncTraceId);
-        }, asyncExecutor).join();
-
-        return "Check logs";
-    }
-}
-```
-
-**预期日志输出：**
-```
-[http-nio-8080-exec-1] [abc123] Main thread TraceID: abc123
-[avatar-async-1] [abc123] Async thread TraceID: abc123
-```
-
-如果异步线程的 TraceID 为 null 或不一致，说明传播未生效。
-
-## 组件参考
-
-### 核心类
-
-| 类 | 包 | 用途 |
-|-------|---------|---------|
-| `WebAutoConfiguration` | `com.iflytek.avatar.boot.config` | 主自动配置类 |
-| `WebProperties` | `com.iflytek.avatar.boot.config` | 配置属性 |
-| `WebMvcConfiguration` | `com.iflytek.avatar.boot.config` | MVC 配置（拦截器、CORS） |
-| `MetricsConfiguration` | `com.iflytek.avatar.boot.config` | 指标记录器配置 |
-| `RequestContextInterceptor` | `com.iflytek.avatar.boot.interceptor` | 请求上下文初始化 |
-| `GlobalExceptionHandler` | `com.iflytek.avatar.boot.exception` | 全局异常处理 |
-| `LogInfo` | `com.iflytek.avatar.boot.anno` | 方法级日志注解 |
-| `LogInfoAspect` | `com.iflytek.avatar.boot.anno` | @LogInfo 的 AOP 切面 |
-| `MetricsRecorder` | `com.iflytek.avatar.boot.metrics` | 指标记录工具 |
-| `AvatarContext` | `com.iflytek.avatar.boot.context` | 请求上下文持有者（在 core 中） |
-| `ContextManager` | `com.iflytek.avatar.boot.context` | ThreadLocal 上下文管理器（在 core 中） |
-
-### 配置属性
-
-| 属性 | 类型 | 默认值 | 说明 |
-|----------|------|---------|-------------|
-| `avatar.web.interceptor-enabled` | boolean | true | 启用请求拦截器 |
-| `avatar.web.exception-handler-enabled` | boolean | true | 启用全局异常处理器 |
-| `avatar.web.cors-enabled` | boolean | false | 启用 CORS |
-| `avatar.web.interceptor.trace-id-header` | String | X-Trace-Id | TraceId 请求头名称 |
-| `avatar.web.interceptor.include-paths` | List<String> | ["/**"] | 拦截路径 |
-| `avatar.web.interceptor.exclude-paths` | List<String> | ["/error", "/actuator/**", ...] | 排除路径 |
-| `avatar.web.log.request-enabled` | boolean | true | 记录请求开始 |
-| `avatar.web.log.response-enabled` | boolean | true | 记录请求完成 |
-| `avatar.web.log.slow-request-threshold` | long | 3000 | 慢请求阈值（毫秒） |
-| `avatar.web.async.enabled` | boolean | true | 启用异步支持（1.0.0-SNAPSHOT+） |
-| `avatar.web.async.core-pool-size` | int | 10 | 异步执行器核心线程数（1.0.0-SNAPSHOT+） |
-| `avatar.web.async.max-pool-size` | int | 50 | 异步执行器最大线程数（1.0.0-SNAPSHOT+） |
-| `avatar.web.async.queue-capacity` | int | 200 | 异步执行器队列容量（1.0.0-SNAPSHOT+） |
-| `avatar.web.async.thread-name-prefix` | String | avatar-async- | 异步线程名前缀（1.0.0-SNAPSHOT+） |
-| `avatar.web.tracing.micrometer-enabled` | boolean | false | 启用 Micrometer 集成（1.0.0-SNAPSHOT+） |
-| `avatar.web.tracing.generator-type` | String | uuid | TraceID 生成策略（1.0.0-SNAPSHOT+） |
-| `avatar.web.cors.allowed-origins` | List<String> | ["*"] | 允许的源 |
-| `avatar.web.cors.allowed-methods` | List<String> | ["GET", "POST", ...] | 允许的 HTTP 方法 |
-| `avatar.web.cors.allowed-headers` | List<String> | ["*"] | 允许的请求头 |
-| `avatar.web.cors.exposed-headers` | List<String> | ["X-Trace-Id"] | 暴露的响应头 |
-| `avatar.web.cors.allow-credentials` | boolean | true | 允许凭证 |
-| `avatar.web.cors.max-age` | long | 3600 | 预检缓存时间（秒） |
-
-## 依赖
-
-此模块依赖于：
-
-- `avatar-boot-core` - 核心功能（AvatarContext、Result 等）
-- `spring-boot-starter-web` - Spring MVC
-- `spring-boot-starter-validation` - 参数校验
-- `spring-boot-starter-aop` - @LogInfo 的 AOP 支持
-- `micrometer-core` - 指标（可选）
-- `logstash-logback-encoder` - JSON 日志格式化
-- `hutool-all` - 工具库（UUID、字符串处理）
-
-## 最佳实践
-
-1. **始终使用 Result<T> 作为 API 响应** - 确保响应格式一致
-2. **生产环境不要禁用拦截器** - TraceId 对故障排查至关重要
-3. **谨慎使用 @LogInfo** - 仅在关键业务方法上使用，避免日志膨胀
-4. **根据环境配置慢请求阈值** - 开发环境可以放宽，生产环境应严格
-5. **生产环境永远不要使用 CORS "*" 配合凭证** - 安全风险
-6. **始终将 TraceId 传播到下游服务** - 启用分布式追踪
-7. **使用环境特定的日志级别** - 开发环境用 DEBUG，生产环境用 INFO
-8. **在生产环境监控指标** - 为高失败率或慢方法设置告警
-9. **不要捕获并吞掉异常** - 让 GlobalExceptionHandler 处理它们
-10. **在 finally 块中清理资源** - 尽管拦截器会处理上下文清理
-
-## 版本要求
-
-- Java 21+
-- Spring Boot 3.5.3+
-- Maven 3.8.6+
-
-## 相关技能
-
-- `avatar-boot-sdk-development` - 用于整体 Avatar Boot 架构和依赖管理
-- `java-spring-boot` - 用于通用 Spring Boot 开发模式
-- `systematic-debugging` - 用于排查此模块的问题
-
-## 其他资源
-
-- 模块 README：`avatar-boot-starter-web/README.md`
-- 配置示例：`avatar-boot-starter-web/src/main/resources/application-example.yml`
-- Logback 配置：`avatar-boot-starter-web/src/main/resources/logback-spring.xml`
+# Avatar Boot Starter Web 使用指南
+
+你是 Avatar Boot Web 模块的使用顾问与开发助手。
+
+## 交互流程（必须遵守）
+
+**每次被触发时，先通过 AskUserQuestion 工具询问用户意图：**
+
+问题："您好！我是 Avatar Boot Web 模块助手，请问您需要哪方面的帮助？"
+选项：
+1. **快速接入** - 我想把 avatar-boot-starter-web 集成到我的项目中
+2. **功能使用** - 我想了解某个具体功能的用法（异常处理、日志、TraceId、@LogInfo、指标监控等）
+3. **配置调整** - 我想自定义模块的配置项
+4. **自定义扩展** - 我想扩展或覆盖模块的默认行为
+
+**根据用户选择进入对应模式：**
+
+---
+
+### 模式一：快速接入
+
+**先用 Read 工具读取** `references/快速接入指南.md`，然后引导用户完成以下步骤：
+
+1. 添加 Maven 依赖
+2. 确认无需额外配置（开箱即用）
+3. 验证功能是否生效
+
+完成后询问用户是否需要了解具体功能的使用方式。
+
+---
+
+### 模式二：功能使用
+
+用 AskUserQuestion 询问用户关注的功能：
+
+问题："您想了解哪个功能的使用方式？"
+选项：
+1. **全局异常处理** - 统一异常响应、业务异常抛出
+2. **请求上下文（AvatarContext）** - TraceId 获取、客户端 IP、请求耗时
+3. **@LogInfo 方法日志注解** - 方法级日志记录、慢方法检测
+4. **结构化日志体系** - 日志格式、日志文件、环境配置
+5. **指标监控（Micrometer）** - 方法调用统计、执行时间统计
+
+**根据用户选择，用 Read 工具按下方「文档读取路由」加载对应文档，然后给出具体指导。**
+
+---
+
+### 模式三：配置调整
+
+**先用 Read 工具读取** `references/配置参考.md`，然后：
+
+用 AskUserQuestion 询问用户要调整的配置项：
+
+问题："您需要调整哪方面的配置？"
+选项：
+1. **拦截器配置** - 拦截路径、排除路径、TraceId 请求头名称
+2. **日志配置** - 请求/响应日志开关、慢请求阈值
+3. **指标监控配置** - 启用/禁用指标
+4. **关闭某个功能** - 关闭拦截器或全局异常处理
+
+根据用户选择，从读取到的配置文档中提取对应内容，给出**精准的 YAML 配置示例**。
+
+---
+
+### 模式四：自定义扩展
+
+用 AskUserQuestion 询问用户要扩展的内容：
+
+问题："您需要扩展哪方面的功能？"
+选项：
+1. **自定义异常处理器** - 添加新的异常类型处理
+2. **自定义拦截器** - 添加业务拦截逻辑
+3. **自定义响应格式** - 修改 Result 结构
+
+**用 Read 工具读取** `references/自定义扩展指南.md`，然后给出对应的代码示例。
+
+---
+
+## 行为准则
+
+1. **回答要具体**：引用具体的类名、注解、配置项等，不要泛泛而谈
+2. **主动提醒**：回答某个功能时，主动提醒注意事项和常见误区
+3. **逐步引导**：回答完当前问题后，提示用户下一步可以做什么
+4. **使用中文回答**
+5. **版本说明**：
+   - 本模块要求 Java 21+、Spring Boot 3.5.3+
+   - 使用 `jakarta.*` 命名空间，不支持 `javax.*`
+   - 自动配置使用 `AutoConfiguration.imports`，不使用 `spring.factories`
+
+---
+
+## 文档读取路由
+
+> 所有路径相对于 skill 目录 `docs/skills/avatar-boot-starter-web-skill/`
+
+### 模式一：快速接入
+- `references/快速接入指南.md`
+
+### 模式二：功能使用
+
+| 功能 | 需读取的文件 |
+|:--|:--|
+| 全局异常处理 | `references/功能-全局异常处理.md` |
+| 请求上下文（AvatarContext） | `references/功能-请求上下文.md` |
+| @LogInfo 方法日志注解 | `references/功能-LogInfo注解.md` |
+| 结构化日志体系 | `references/功能-日志体系.md` |
+| 指标监控（Micrometer） | `references/功能-指标监控.md` |
+
+### 模式三：配置调整
+- `references/配置参考.md`
+
+### 模式四：自定义扩展
+- `references/自定义扩展指南.md`
+
+### 按需补充
+
+在对话过程中，根据用户需求追加读取：
+- 用户遇到依赖问题 → `references/快速接入指南.md`（依赖说明部分）
+- 用户询问注意事项 → `references/注意事项.md`
+
+---
+
+## 通用参考信息
+
+### 核心类速查
+
+| 类/注解 | 包路径 | 用途 |
+|:--|:--|:--|
+| `AvatarContext` | `com.iflytek.avatar.boot.context` | 请求上下文数据对象 |
+| `ContextManager` | `com.iflytek.avatar.boot.context` | 获取/设置请求上下文 |
+| `Result<T>` | `com.iflytek.avatar.boot.entity.response` | 统一响应封装 |
+| `ResultCode` | `com.iflytek.avatar.boot.entity.response` | 响应状态码枚举 |
+| `BusinessException` | `com.iflytek.avatar.boot.exception` | 业务异常基类 |
+| `BadRequestException` | `com.iflytek.avatar.boot.exception` | 请求参数异常 |
+| `GlobalExceptionHandler` | `com.iflytek.avatar.boot.exception` | 全局异常处理器 |
+| `@LogInfo` | `com.iflytek.avatar.boot.anno` | 方法日志注解 |
+
+### 默认配置值
+
+| 配置项 | 默认值 |
+|:--|:--|
+| `avatar.web.interceptor-enabled` | `true` |
+| `avatar.web.exception-handler-enabled` | `true` |
+| `avatar.web.interceptor.trace-id-header` | `X-Trace-Id` |
+| `avatar.web.interceptor.include-paths` | `/**` |
+| `avatar.web.log.request-enabled` | `false` |
+| `avatar.web.log.response-enabled` | `false` |
+| `avatar.web.log.slow-request-threshold` | `3000`（ms） |
+| `avatar.web.metrics.enabled` | `true` |